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

Jump to bottom

Add regionCode attribute #690

Merged
merged 12 commits into from May 16, 2018
Merged

Add regionCode attribute #690

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
25bf943
Add regionCode attribute to PaymentAddress
marcoscaceres Nov 20, 2017
66a1237
wip: iso stuff
marcoscaceres Mar 19, 2018
8f030ca
xrefs, cleanup, feedback
marcoscaceres Mar 22, 2018
8199e35
nit: redudant reference
marcoscaceres Mar 22, 2018
58e0d95
fix typo
marcoscaceres May 10, 2018
2febe42
Return just the subdivision part
marcoscaceres May 11, 2018
cdd18dc
fixup
marcoscaceres May 11, 2018
5f23fac
Fixup
marcoscaceres May 11, 2018
d1aca5d
Rename regionCode var to countrySubdivisionCodeElement
marcoscaceres May 16, 2018
1695891
missing and
marcoscaceres May 16, 2018
d2b59ee
use putativeCountrySubdivisionCodeElement instead
marcoscaceres May 16, 2018
699d329
typo
marcoscaceres May 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
69 changes: 42 additions & 27 deletions index.html
View file
Open in desktop
Expand Up @@ -2185,7 +2185,8 @@ <h2>
<li>If <var>details</var> was not passed, return
<var>address</var>.
</li>
<li>If <var>details</var>["<a>country</a>"] is present:
<li>If <var>details</var>["<a>country</a>"] is present and not the
empty string:
<ol>
<li>Set <var>country</var> the result of <a>strip leading and
trailing ASCII whitespace</a> from
Expand All @@ -2203,12 +2204,16 @@ <h2>
<li>If <var>details</var>["<a>regionCode</a>"] is present and not
the empty string:
<ol>
<li>Let <var>regionCode</var> be the result of <a>strip leading
<li>Let <var>regionPart</var> be the result of <a>strip leading
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The variable naming here is super-confusing. To a web developer, a regionCode is something like "CA", right? But in this algorithm, details["regionCode"] is "CA", regionPart is "CA", and regionCode is "USA-CA".

I think the variable on this line should be regionCode, and on line 2213 should be putativeCountrySubdivisionCodeElement or similar.

and trailing ASCII whitespace</a> from
<var>details</var>["<a>regionCode</a>"] and then
<a data-cite="!INFRA#ascii-uppercase">ASCII uppercasing</a>
the result.
</li>
<li>Let <var>regionCode</var> be the concatenation of
<var>address</var>.<a>[[\country]]</a>, a single U+002D (-) <a>
code point</a>, <var>regionPart</var>.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing "and" after last comma.

</li>
<li>
<p>
If <var>regionCode</var> is not a valid <a>country
Expand Down Expand Up @@ -2246,27 +2251,31 @@ <h2>
</div>
</li>
<li>Set <var>address</var>.<a>[[\regionCode]]</a> to
<var>regionCode</var>.
<var>regionPart</var>.
</li>
<li>Let <var>region</var> be the corresponding <a>country
subdivision name</a> for <var>regionCode</var>. Where
[[!ISO3166-2]] defines multiple <a>country subdivision
names</a> for a <var>regionCode</var>, it is RECOMMENDED the
user agent select one by matching on:
<li>If <var>details</var>["<a>region</a>"] is not present:
<ol>
<li>The <a data-cite="!HTML#language">language</a> of
<a data-cite="HTML#the-body-element-2">the body
element</a>.
</li>
<li>The user's preferred languages.
<li>Let <var>region</var> be the corresponding <a>country
subdivision name</a> for <var>regionCode</var>. Where
[[!ISO3166-2]] defines multiple <a>country subdivision
names</a> for a <var>regionCode</var>, it is RECOMMENDED
the user agent select one by matching on:
<ol>
<li>The <a data-cite="!HTML#language">language</a> of
<a data-cite="HTML#the-body-element-2">the body
element</a>.
</li>
<li>The user's preferred languages.
</li>
<li>Any other criteria the user agent deems suitable.
</li>
</ol>
</li>
<li>Any other criteria the user agent deems suitable.
<li>
<var>details</var>["<a>region</a>"] to <var>region</var>.
</li>
</ol>
</li>
<li>Set <var>address</var>.<a>[[\region]]</a> to
<var>region</var>.
</li>
</ol>
</li>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we consider deriving region from regionCode, so the caller only has to pass one? I'm thinking ahead to the constructor; do we want to prevent new PaymentAddress({ ..., regionCode: "PT-11", region: "Tasmania" })?

I guess for the cases where there is no corresponding regionCode, we'd still want to pass region. But if regionCode is not the empty string, deriving region from it might be good...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But if regionCode is not the empty string, deriving region from it might be good...

Agree. It's definitely doable. ISO3166-2 provides lookup tables, for example:

AD-07* Andorra la Vella
AD-02* Canillo
AD-03* Encamp
AD-08* Escaldes-Engordany
AD-04* La Massana
AD-05* Ordino
AD-06* Sant Julià de Lòria

Where column 2 (defined thing) is "...the country subdivision names in the administrative language of the country concerned, where relevant with diacritic signs..." (as Unicode). Note that "a country’s administrative language is a written language used by the administration of the country at the national level". So, the result won't be in English a lot of the time - but that's fine, IMO. This is not for display purposes.

So, something like:

The steps to derive a region from a country subdivision code element are as follows. The string takes a DOMString subCode as input and returns a DOMString.

  1. If validate a region code subCode return false, throw RangeError exception.
  2. ASCII uppercase subCode, and let normalizeCode be the result.
  3. Find normalizeCode in Section 8, "List of country subdivision names and their code elements" of ISO3166-2 and return the value of "column 2" for the matching country subdivision code element.

Sound good?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds great! Probably we should get implementer buy-ins though; maybe as a separate PR? Because it'd mean having to ship that table with the browser...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree... ☝️@rsolomakhin, @mnoorenberghe, something to start thinking about. Would appreciate your input.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are already using libaddressinput (and I believe Chromium does too) so it would be great if we could also use that here instead of having two versions of similar data. Does ISO3166-2 only have one name per region? What about when there are multiple official languages? Consider CA-QC: is it "Quebec" or "Québec" in ISO3166-2. libaddressinput provides both but without a clear way to know which one would match ISO3166-2.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Presumedly, we can just grab the "en" column 2

I'm not quite sure how this all fits together but won't this affect what gets returned in the region property and therefore may be displayed back to the user on the payment confirmation page the merchant renders? If so, it would seem like we should use the language best for the user.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can probably perform some kind of lookup, based on the document language. But then it gets into preference order for when it doesn't match the user's language (and there is no "en").

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems crazy town, but:

  1. Try to match document language.
  2. Try to match user language (like Accept-Language)?
  3. Try to match "en".
  4. Um... just give me whatever you got.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use libaddressinput in Chromium and @sebsg is helping us to add the ISO codes to that.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But if regionCode is not the empty string, deriving region from it might be good.

The regionCode field takes care of interop, so we don't necessarily have to agree on how the region field is derived from that. Having said that, the rule of thumb we have been using in Chrome is to use the browser user interface language when deciding between Quebec and Québec. If the browser user interface language does not match any of the languages supported by the country, then Chrome falls back to the first language specified in libaddressinput data for that country. For example, if the browser user interface language is Italian, then Canadian addresses will be in English. Although the default language works out to be English for Canada, that's not something that we should hardcode for all countries in the world, IMHO.

<li>If <var>details</var>["<a>languageCode</a>"] is present:
Expand Down Expand Up @@ -2391,10 +2400,10 @@ <h2>
<dfn>regionCode</dfn> attribute
</h2>
<p data-link-for="">
Represents the <a>region</a> of the address as an [[!ISO3166-2]]
<a>country subdivision code element</a>. When getting, returns the
value of the <a>PaymentAddress</a>'s <a>[[\regionCode]]</a>
internal slot.
Represents the <a>region</a> of the address, but as the code
element of an [[!ISO3166-2]] country subdivision name (e.g., "CA"
for California, USA). When getting, returns the value of the
<a>PaymentAddress</a>'s <a>[[\regionCode]]</a> internal slot.
</p>
</section>
<section>
Expand Down Expand Up @@ -2525,10 +2534,12 @@ <h2>
<dfn>[[\regionCode]]</dfn>
</td>
<td>
A <a>region</a> represented as a [[!ISO3166-2]] <a>country
subdivision code element</a> stored in its canonical uppercase
form, or the empty string. For example, "<code>PT-11</code>"
represents the Lisbon district of Portugal.
Either the empty string, or one to three code points that
represent a <a>region</a> as the code element of an
[[!ISO3166-2]] country subdivision name (i.e., the characters
after the hyphen in an ISO3166-2 <a>country subdivision code
element</a>, such as "CA" for the state of California in the
USA, or "11" for the Lisbon district of Portugal).
</td>
</tr>
<tr>
Expand Down Expand Up @@ -2647,8 +2658,12 @@ <h2>
<dfn>regionCode</dfn> member
</dt>
<dd>
An <a>region</a>, represented as a <a>country subdivision code
element</a>.
Either the empty string, or one to three code points that represent
a <a>region</a> as the code element of an [[!ISO3166-2]] country
subdivision name (i.e., the characters after the hyphen in an
ISO3166-2 <a>country subdivision code element</a>, such as "CA" for
the state of California in the USA, or "11" for the Lisbon district
of Portugal)
</dd>
<dt>
<dfn>city</dfn> member
Expand Down