Add contextual options to expression-attributes design doc

[eemeli]

The core idea is to provide explicit and well-defined support for u:id, u:locale, and u:dir when used as function or markup options, and to thereby clarify that expression attributes have no runtime impact.

[aphillips]

Partial review

[mihnita]

TLDR: I am happy with namespaced attributes to represent global/universal options (non-function dependent)
But that makes the attributes even less useful.
So I would suggest we drop them.

[aphillips]

In the 2024-05-20 call, we agreed not to merge this PR but to have @eemeli fold this into exploration/expression-attributes.md design.

[eemeli]

Refactored the PR to be a change/expansion of the expression-attributes design doc rather than a separate one.

[aphillips]

This change doesn't belong here in the expression attributes design. Keep the u: stuff for the design option in which we suggest u:

[eemeli]

That design option is here presented as the proposed one.

[aphillips]

why is a custom function wanted here? I used the implicit :string function on purpose before.

I agree that a custom function example is a good idea, just not maybe here.

[eemeli]

Because the design proposed here uses u: options for contextual effects, and those require an annotation.

[aphillips]

"Special" or "common"?

[eemeli]

Special, because that can account for implementations-specific things that may be "common" within their scope, but not universally. So e.g. @amzn:marketplace=US or amzn:marketplace=US.

[aphillips]

Why are you changing the proposed design section instead of just adding the additional options? We can make changes to the proposed design when we've chosen one.

[eemeli]

Because I'm proposing that we support both u: options and @ attributes?

I would like to advance this discussion towards a solution, and so I'm here proposing this as a potentially viable solution for us to agree on.

[aphillips]

How is this different from "do nothing"?

[eemeli]

"Do nothing" leaves the caution in the syntax.md file; this would remove that.

[aphillips]

Lots of these comments are related to the formatting and structuring of the design doc rather than to the technical arguments.

[aphillips]

I think spelling out the pros/cons here might be useful?

Pros

• implementations would be free to define these options/attributes to suit local implementation needs

Cons

• users could not count on these options to be available in each function
• users would have to learn different requirements/restrictions
  on option use for each function and for each separate implementation

[eemeli]

At the moment, these alternative descriptions are not formatted as pro/con lists, and I would rather keep them internally consistent. Therefore, I'd much prefer not adding such a list to just one option, and I don't want to refactor the entire PR again to include such a reformatting. We could do such a reformatting as a follow-on change.

[aphillips]

I don't follow this statement. Why wouldn't I be able to have a {#b id=foo}? Or a {$x :number id=foo}?

[eemeli]

This statement is specifically about formatted parts for markup, not expressions. Functions can define how expressions get formatted, but markup is not configurable. Sure, you could pass markup an id=foo option, but that option would be only present in the general bag of options in the formatted part, and would potentially conflict with other use.

For example, it's rather common for HTML elements to include an id value, which is already relevant for the CSS or JS executing on that document, but an identifier may be separately relevant for the post-processing of a formatted message, such as adding in parameters that were not included in the translation.

In other words, if we're translating a message like

Would you like to {#a u:id=continue}accept{/a} or {#a u:id=cancel}reject{/a} the offer?

we need a way to disambiguate the two formatted {#a} spans from each other, hence the u:id. That way the message can end up first formatted as:

[
  { type: 'literal', value: 'Would you like to ' },
  { type: 'markup', kind: 'open', source: '#a', name: 'a', id: 'continue' },
  { type: 'literal', value: 'accept' },
  { type: 'markup', kind: 'close', source: '/a', name: 'a' },
  { type: 'literal', value: ' or ' },
  { type: 'markup', kind: 'open', source: '#a', name: 'a', 'id': 'cancel' },
  { type: 'literal', value: 'reject' },
  { type: 'markup', kind: 'close', source: '/a', name: 'a' },
  { type: 'literal', value: ' the offer?' }
]

And from there, we can construct an HTML snippet with additional properties:

Would you like to <a href="continue?token=123abc">accept</a> or <a href="cancel?token=123abc">reject</a> the offer?

But if there's no common u:id definition, then the identifier ends up mixed together with the other markup options, and it gets much trickier to build tooling that's universal across different implementations and function authors, and doesn't risk bleeding through into the output HTML, where a property like id="continue" could very easily conflict with some other operations and expectations of the page.

[aphillips]

Okay, I see what you're saying now. My example omitted the u: by mistake. I still think that the text you have the design document is super-mysterious, though. Note that attributed strings can have overlapping markup (that would be illegal in HTML). For example:

Would you like to {#span type=foo u:id=1}click {#span type=bar u:id=2}here{/span u:id=1} to get {/span u:id=2} illegal stuff.

Perhaps:

Suggested change

	Formatted parts for markup would not be able to directly include an identifier.
	Lack of a built-in identifier would inhibit tools support for markup,
	particularly when formatted to parts,
	when the relationship of open and close markup is ambiguous.
	> For example, the two `{/a}` markup elements in this mess:
	>```
	> Would you like to {#a u:id=continue}accept{/a} or {#a u:id=cancel}reject{/a} the offer?
	>```

[aphillips]

I think you should address how id could work here. Presumably the id property of the resolved value could be queried?

[eemeli]

I'm honestly not sure how to make id sensibly work, if we're not defining it generally in the spec but only specifically for each standard registry function. That would mean not having any specific field for it in the formatting-internal resolved values, and intermingling it with the other resolved options.

I hope we do not end up with this option, and so can avoid needing to answer all the questions that it would introduce.

[aphillips]

I agree that we should not end up with this option. I'd probably address it by saying:

Suggested change

	Define at least `locale` and `dir` as options for default registry functions,
	with handling internal to each function implementation.
	Define the `locale`, `dir`, and `id` options for all default registry functions
	and establish a policy of including them in all future default registry functions,
	with the hope that other functions and implementations will adopt this as a best practice.
	Actually implementation would be internal to each function.

[aphillips]

This is too suppositional.

Suggested change

	Allow expression attributes to influence the formatting context,
	but do not directly pass them to user-defined functions.
	Expression attributes are stored in or modify the formatting context,
	rather than passed directly to functions (including user-defined functions).
	Function implementations can access the values of attributes via the formatting
	context, but are not required to do so.

[eemeli]

I'm not sure what you mean by "suppositional". I think what you're describing is one possible way of implementing this alternative, but it's not the only one. Should we split this option into two, one of which only defines an explicit short list of attributes with well-defined runtime effects, and the other allows for values to be stored in the expression's formatting context?

[aphillips]

I said "suppositional" because it's hard to say what "influencing" the formatting context means?

I agree that my suggestion is one possible way of implementing this and that there could be others. However, by expressing it concretely, I hope to enable us to have a concrete conversation about which option to pursue.

I probably wouldn't go to the trouble of splitting the option up. I'd just note that my suggestion is one route and limiting the attributes to the built-in set is another?