Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add sections 4,5,6 to Amount explainer #36

Merged
merged 3 commits into from
Dec 30, 2024
Merged

add sections 4,5,6 to Amount explainer #36

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d808f7d
add sections 4,5,6 to explainer
tantek Dec 23, 2024
efd8d63
Update amount.md
tantek Dec 28, 2024
921f1d1
fix quote typo
tantek Dec 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 41 additions & 4 deletions amount.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ or with unfamiliar punctuation denoting large or decimal amounts which can eithe
If publishers had a mechanism to explicitly denote these numerical amounts and their units if any,
then browsers could offer a privacy-respecting user-interface to display these amounts to the user according to their local units and punctuation preferences.

## Methodology for approaching & evaluating solutions
## Methodology for approaching and evaluating solutions

Per the priority of constituencies, we should first look for solutions that users can trust,
e.g. if a solution enables an affordance to convert units, it should be 100% reliable like a calculator,
Expand All @@ -20,8 +20,12 @@ In particular, we should look for and prefer [declarative approaches](https://ww
Out of scope:
* currencies (for this Explainer), because their conversions are subjective and changing (not 100% reliable). We may still consider the backward compatible extensibility of any solutions, in order to enable a future Explainer to add currency support. We may also consider how solutions could treat a currency amount as a numerical amount with an unknown unit, for the purposes of converting at least the numerical portion to user preferred or locale-specific punctuation for large or decimal numbers.

## Prior features and existing proposals
## Existing features and prior proposals
There is a broad range from implemented features to various prior and in-progress proposals that address or attempt to address some to all of the user problems noted above.
This section documents them, roughly clustered into well implemented existing standards features,
to proposals that may have some to no partial or experimental support from publishers or perhaps a single implementation.

### Existing features
In HTML we have the `<time>` element which is useful for publishing date time information,
and in particular [durations](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-duration-string)
amounts with units of seconds, minutes, hours, or days.
Expand All @@ -43,6 +47,7 @@ however without any default user-discernible effects,
including [in screen readers](https://twitter.com/LeonieWatson/status/1333078194925264898),
despite the “[First rule of ARIA use](https://www.w3.org/TR/aria-in-html/#rule1)” encouraging publishers to use native HTML semantic elements.

### Prior proposals
The microformats community did a lot of [research into measure formats](https://microformats.org/wiki/measure)
for amounts with physical units in the mid-2000s,
culminating in an [hmeasure draft proposal](https://microformats.org/wiki/measure-brainstorming#Draft_Schema),
Expand All @@ -67,5 +72,37 @@ There is also an existing early stage [measure proposal](https://github.com/tc39
despite the imperative approach, may have some additional useful (researched) semantics to consider
in a proposed declarative amount solution, such as compound units and separate major and minor units.


...
## Flaws or limitations in existing features and prior proposals
* The HTML `<time>` element is limited to representing temporal amounts, and would be inappropriate for other physical or numerical amounts.
* The HTML `<data>` element is limited to representing unitless numerical amounts.
* The `h-measure` proposed microformat while cleverly re-uses `<data>` elements, requires multiple (3-4) elements to represent a single numerical amount.
Multiple elements for a single amount are a substantially lengthier syntax,
both suboptimal for developer ergonomics and easier to get wrong or break in maintenance.
* The WebWeWant `<amount>` proposal is both incomplete, and yet seems to also have unnecessary features like the boolean `non-zero-decimals.
* The TC39 measure proposal is both a semantic layer violation (meaning in the web platform should be encoded in markup, not script),
and also creates even worse developer ergonomics (wordier and more fragile imperative syntax) than the `h-measure` microformat.

## Motivation for this explainer
By choosing the best from prior proposals, we can create a simpler, more ergonomic and robust solution for web developers that starts with solving the most common use-cases, with room for extensions to solve more use-cases as necessary.

By taking inspiration from the prior declarative features and proposals in particular, we can create a solution for [the declarative web](https://www.mozilla.org/en-US/about/webvision/full/#thedeclarativeweb) for all the reasons that such solutions are better than procedural or imperative approaches.

## Outline of proposed solution
Proposal: a new HTML `<amount>` element (similar to `<data>` and `<time>`), with:
* `value` attribute: optional numerical value, similar to the `<data>` element’s `value` attribute. Otherwise element contents are parsed for a numberical value.
* E.g. `<amount>42.2</amount>` or `<amount value=42.2 lang=de>42,2</amount>`
* `unit` attribute: optional physical ([SI](https://en.wikipedia.org/wiki/International_System_of_Units)) unit to express measures.
Absent a `unit` attribute, the element contents are parsed for a numerical value, and the remaining portion of the element contents is parsed for an SI unit.
Simple compound SI units (e.g. `km/h`) are common enough in web content to also merit supporting.
User agents may fully algorithmically transform such a unit to the user’s locale (user opt-in) or other display preferences.
* E.g. `<amount>42.2km</amount>` or `<amount value=42.2 unit=km> lang=de>42,2km</amount>`
* If there is no `unit` attribute, and no valid unit parsed from the element contents, the amount is unitless and expresses a quantity.
User agents may format (user opt-in) large and/or decimal quantities in locale-specific tridigit and
decimal separators (e.g. ',' vs '.' etc.), taking care to preserve any script observable metrics to avoid exposing locale information.

### currency extension
As an exploration, to extend the `<amount>` element to support currency, we could do so with:
* `currency` attribute: optional currency code (([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) to express a monetary amount. User agents could use an online exchange service to compute rough equivalents and note the source and time dependency (temporal context) of any such conversions.
* e.g. `<amount currency=USD value=64000>$64,000</amount>`
* The presence of both `unit` and `currency` attributes is an error. The user agent must ignore both attributes.
* Quantity change: If neither a unit (attribute or parsed) nor `currency` attribute are present, the amount is unitless and expresses a quantity.