add PaymentAddress.regionCode attribute (#690)

marcoscaceres · web-flow · commit f0018f9267fc · 2018-05-16T15:44:17.000+10:00
diff --git a/index.html b/index.html
@@ -2148,6 +2148,7 @@ <h2>
             readonly attribute DOMString postalCode;
             readonly attribute DOMString recipient;
             readonly attribute DOMString region;
+            readonly attribute DOMString regionCode;
             readonly attribute DOMString sortingCode;
             readonly attribute FrozenArray&lt;DOMString&gt; addressLine;
           };
@@ -2184,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
@@ -2199,6 +2201,83 @@ <h2>
                 </li>
               </ol>
             </li>
+            <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
+                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>putativeCountrySubdivisionCodeElement</var> be the
+                concatenation of <var>address</var>.<a>[[\country]]</a>, a
+                single U+002D (-) <a>code point</a>, and <var>regionCode</var>.
+                </li>
+                <li>
+                  <p>
+                    If <var>putativeCountrySubdivisionCodeElement</var> is not
+                    a valid <a>country subdivision code element</a> as per
+                    [[!ISO3166-2]]'s section 5.2 "Structure of country
+                    subdivision code elements" (non-normative details below),
+                    throw a <a>RangeError</a> exception.
+                  </p>
+                  <div class="note" title=
+                  "Structure of country subdivision code elements">
+                    <p>
+                      <strong>Do not implement from this note.</strong> The
+                      structure of a <a>country subdivision code element</a> is
+                      formally defined in [[!ISO3166-2]] (section 5.2).
+                      Although the structure is not expected to change at the
+                      time of writing, implementers are expected to track
+                      updates to [[!ISO3166-2]] directly from ISO.
+                    </p>
+                    <p>
+                      As [[!ISO3166-2]] is not freely available to the general
+                      public, the structure of a <a>country subdivision code
+                      element</a> at the time of publication is as follows:
+                    </p>
+                    <ul>
+                      <li>Two <a>code points</a> that match an [[!ISO3166-1]]
+                      alpha-2 country code.
+                      </li>
+                      <li>A single U+002D (-) <a>code point</a>.
+                      </li>
+                      <li>One, two, or three <a data-cite=
+                      "INFRA#ascii-alphanumeric">ASCII alphanumeric</a> code
+                      points, in any order.
+                      </li>
+                    </ul>
+                  </div>
+                </li>
+                <li>Set <var>address</var>.<a>[[\regionCode]]</a> to
+                <var>regionCode</var>.
+                </li>
+                <li>If <var>details</var>["<a>region</a>"] is not present:
+                  <ol>
+                    <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>Set <var>details</var>["<a>region</a>"] to
+                    <var>region</var>.
+                    </li>
+                  </ol>
+                </li>
+              </ol>
+            </li>
             <li>If <var>details</var>["<a>languageCode</a>"] is present:
               <ol>
                 <li>If <a data-cite=
@@ -2316,6 +2395,17 @@ <h2>
             internal slot.
           </p>
         </section>
+        <section>
+          <h2>
+            <dfn>regionCode</dfn> attribute
+          </h2>
+          <p data-link-for="">
+            Represents the <a>region</a> of the address as a 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>
           <h2>
             <dfn>city</dfn> attribute
@@ -2434,9 +2524,22 @@ <h2>
                 <dfn>[[\region]]</dfn>
               </td>
               <td>
-                A <a>region</a> as a country subdivision name or the empty
-                string, such as "Victoria", representing the state of Victoria
-                in Australia.
+                A <a>region</a> as a <a>country subdivision name</a> or the
+                empty string, such as "Victoria", representing the state of
+                Victoria in Australia.
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <dfn>[[\regionCode]]</dfn>
+              </td>
+              <td>
+                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>
@@ -2516,6 +2619,7 @@ <h2>
             DOMString country;
             sequence&lt;DOMString&gt; addressLine;
             DOMString region;
+            DOMString regionCode;
             DOMString city;
             DOMString dependentLocality;
             DOMString postalCode;
@@ -2550,6 +2654,17 @@ <h2>
           <dd>
             A <a>region</a>.
           </dd>
+          <dt>
+            <dfn>regionCode</dfn> member
+          </dt>
+          <dd>
+            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
           </dt>
@@ -2684,9 +2799,17 @@ <h2>
           <var>details</var>["<a>recipient</a>"] to the user-provided recipient
           of the transaction, or to the empty string if none was provided.
           </li>
-          <li>If "region" is not in <var>redactList</var>, set
-          <var>details</var>["<a>region</a>"] to the user-provided region, or
-          to the empty string if none was provided.
+          <li>If "region" is not in <var>redactList</var>:
+            <ol>
+              <li>Set <var>details</var>["<a>region</a>"] to the user-provided
+              region, or to the empty string if none was provided.
+              </li>
+              <li>If <var>details</var>["<a>region</a>"] has a corresponding
+              <a>country subdivision code element</a>, set
+              <var>details</var>["<a>regionCode</a>"] to that <a>country
+              subdivision code element</a>.
+              </li>
+            </ol>
           </li>
           <li>If "sortingCode" is not in <var>redactList</var>, set
           <var>details</var>["<a>sortingCode</a>"] to the user-provided sorting
@@ -3923,6 +4046,14 @@ <h2>
         This specification relies on several other underlying specifications.
       </p>
       <dl data-sort="">
+        <dt>
+          ISO 3366-2
+        </dt>
+        <dd>
+          <dfn data-lt="country subdivision names">Country subdivision
+          name</dfn> and <dfn>country subdivision code element</dfn> are
+          defined in [[!ISO3166-2]].
+        </dd>
         <dt>
           Infra
         </dt>
