Skip to content

Commit

Permalink
chore: export defs needed by Payment Request
Browse files Browse the repository at this point in the history
  • Loading branch information
@marcoscaceres
marcoscaceres committed Feb 20, 2024
1 parent 2c6c63d commit 488649a
Showing 1 changed file with 44 additions and 37 deletions.
81 changes: 44 additions & 37 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,9 @@ text macro: JOINTWEBAPPS yes
<pre class=link-defaults>
spec:infra; type:dfn; text:list
spec:html; type:dfn; for:/; text:browsing context
spec:html; type:dfn; for:/; text:origin
spec:html; type:dfn; for:/; text:valid e-mail address
spec:html; type:dfn; for:/; text:valid email address
spec:html; type:dfn; for:/; text:event loop
spec:html; type:dfn; for:environment settings object; text:origin
</pre>

# Introduction # {#intro}
Expand Down Expand Up @@ -137,10 +138,10 @@ parties. A picker model is enforced so that the user agent can offer a user expe
it clear what information is going to be shared with the website and when.

The following constraints are also enforced:
* The API is only available in a [=top-level browsing context=] which must also be a
* The API is only available in a [=navigable/top-level traversable=], which must also be a
[=secure context=]. These restrictions help ensure that the provided contact information reaches
its intended recipient.
* A user gesture is needed to initiate the API, to disallow programmatic requests to the user's
* [=Transient activation=] is needed to initiate the API, to disallow programmatic requests to the user's
contacts.

# Realms # {#realms}
Expand All @@ -161,29 +162,29 @@ The <dfn>contact picker task source</dfn> is a [=task source=].

## Physical address ## {#infrastructure-physical-address}

A <dfn>physical address</dfn> consists of:
A <dfn export>physical address</dfn> consists of:
<div dfn-for="physical address">

* <dfn>country</dfn>, a {{DOMString}} representing the country of the address as an
* <dfn for="physical address" export>country</dfn>, a {{DOMString}} representing the country of the address as an
[[ISO3166-1]] alpha-2 code stored in its canonical uppercase form or the empty string. For
example, "JP".
* <dfn>address line</dfn>, a [=list=] of {{DOMString}}s, containing the most specific part of the
* <dfn for="physical address" export>address line</dfn>, a [=list=] of {{DOMString}}s, containing the most specific part of the
address. It can include, for example, a street name, a house number, apartment number, a rural
delivery route, descriptive instructions, or a post office box number.
* <dfn>region</dfn>, a {{DOMString}} representing the top level administrative subdivision of the
* <dfn for="physical address" export>region</dfn>, a {{DOMString}} representing the top level administrative subdivision of the
country. For example, this can be a state, a province, an oblast, or a prefecture.
* <dfn>city</dfn>, a {{DOMString}} representing the city/town portion of the address.
* <dfn>dependent locality</dfn>, a {{DOMString}} representing the dependent locality or sublocality
* <dfn for="physical address" export>city</dfn>, a {{DOMString}} representing the city/town portion of the address.
* <dfn for="physical address" export>dependent locality</dfn>, a {{DOMString}} representing the dependent locality or sublocality
within a city. For example, neighborhoods, boroughs, districts, or UK dependent localities.
* <dfn>postal code</dfn>, a {{DOMString}} representing the postal code or ZIP code, also known as
* <dfn for="physical address" export>postal code</dfn>, a {{DOMString}} representing the postal code or ZIP code, also known as
PIN code in India.
* <dfn>sorting code</dfn>, a {{DOMString}} representing the sorting code system, such as the CEDEX
* <dfn for="physical address" export>sorting code</dfn>, a {{DOMString}} representing the sorting code system, such as the CEDEX
system used in France.
* <dfn>organization</dfn>, a {{DOMString}} representing the organization, firm, company, or
* <dfn for="physical address" export>organization</dfn>, a {{DOMString}} representing the organization, firm, company, or
institution at the address.
* <dfn>recipient</dfn>, a {{DOMString}} representing the name of the recipient or contact person at
* <dfn for="physical address" export>recipient</dfn>, a {{DOMString}} representing the name of the recipient or contact person at
the address.
* <dfn>phone number</dfn>, a {{DOMString}} representing the phone number of the recipient or contact
* <dfn for="physical address" export>phone number</dfn>, a {{DOMString}} representing the phone number of the recipient or contact
person at the address, optionally structured to adhere to [[E.164]].

</div>
Expand All @@ -193,15 +194,15 @@ A <dfn>physical address</dfn> consists of:
A <dfn>user contact</dfn> consists of:
<div dfn-for="user contact">

* <dfn>names</dfn>, a [=list=] of {{DOMString}}s, each [=list/item=] representing a unique name
* <dfn for="user contact">names</dfn>, a [=list=] of {{DOMString}}s, each [=list/item=] representing a unique name
corresponding to the user.
* <dfn>emails</dfn>, a [=list=] of {{DOMString}}s, each [=list/item=] representing a unique
[=valid e-mail address=] of the user.
* <dfn>numbers</dfn>, a [=list=] of {{DOMString}}s, each [=list/item=] representing a unique phone
* <dfn for="user contact">emails</dfn>, a [=list=] of {{DOMString}}s, each [=list/item=] representing a unique
[=valid email address=] of the user.
* <dfn for="user contact">numbers</dfn>, a [=list=] of {{DOMString}}s, each [=list/item=] representing a unique phone
number of the user.
* <dfn>addresses</dfn>, a [=list=] of {{ContactAddress}}es, each [=list/item=] representing a
* <dfn for="user contact">addresses</dfn>, a [=list=] of {{ContactAddress}}es, each [=list/item=] representing a
unique [=physical address=] of the user.
* <dfn>icons</dfn>, a [=list=] of {{Blob}}s, each [=list/item=] representing a unique image of the
* <dfn for="user contact">icons</dfn>, a [=list=] of {{Blob}}s, each [=list/item=] representing a unique image of the
user.

NOTE: An icon {{Blob}}'s {{Blob/type}} is an [=image mime type=].
Expand Down Expand Up @@ -249,7 +250,7 @@ The <dfn attribute>contacts</dfn> attribute's getter must return the [=this=]'s
[=Navigator/contacts manager=].
</div>

The [=browsing context=] has a <dfn>contact picker is showing flag</dfn>, initially unset.
The [=Window/navigable=] has a <dfn>contact picker is showing flag</dfn>, initially unset.

## {{ContactProperty}} ## {#contact-property}

Expand Down Expand Up @@ -369,27 +370,29 @@ interface ContactsManager {
<div algorithm>
The <dfn method>select(|properties|, |options|)</dfn> method, when invoked, runs these steps:

1. Let |relevantBrowsingContext| be the [=this=]'s [=relevant settings object=]'s
[=environment settings object/responsible browsing context=].
1. If |relevantBrowsingContext| is not a [=top-level browsing context=], then return
1. Let |global| be the [=this=]'s [=relevant global object=].
1. Let |navigable| be |global|'s [=Window/navigable=].
1. If |navigable| is not a [=navigable/top-level traversable=], then return
[=a promise rejected with=] an {{InvalidStateError}} {{DOMException}}.
1. If the algorithm is not [=triggered by user activation=] then return
1. If |global| does not have [=transient activation=], then return
[=a promise rejected with=] a {{SecurityError}} {{DOMException}}.
1. If |relevantBrowsingContext|'s [=contact picker is showing flag=] is set then return
1. Otherwise, [=consume user activation=] of the |global|.
1. If |navigable|'s [=contact picker is showing flag=] is set then return
[=a promise rejected with=] an {{InvalidStateError}} {{DOMException}}.
1. If |properties| is [=list/empty=], then return [=a promise rejected with=] a {{TypeError}}.
1. [=list/For each=] |property| of |properties|:
1. If [=contacts source=]'s [=contacts source/supported properties=] does not [=list/contain=]
|property|, then return [=a promise rejected with=] a {{TypeError}}.
1. Set |relevantBrowsingContext|'s [=contact picker is showing flag=].
1. Set |navigable|'s [=contact picker is showing flag=].
1. Let |promise| be [=a new promise=].
1. Run the following steps [=in parallel=]:
1. Let |selectedContacts| be be the result of [=launching a contact picker=] with |options|'
`multiple` member and |properties|. If this fails, then:
1. Return [=a promise rejected with=] an {{InvalidStateError}} {{DOMException}}.
1. Unset |relevantBrowsingContext|'s [=contact picker is showing flag=].
1. Abort these steps.
1. Unset |relevantBrowsingContext|'s [=contact picker is showing flag=].
1. [=Queue a contact picker task=] to run these steps:
1. [=Reject=] |promise| an {{InvalidStateError}} {{DOMException}}.
1. Unset |navigable|'s [=contact picker is showing flag=].
1. Abort these steps.
1. Unset |navigable|'s [=contact picker is showing flag=].
1. [=Queue a contact picker task=] to run these steps:
1. Let |contacts| be an empty [=list=].
1. [=list/For each=] |selectedContact| in |selectedContacts|:
Expand Down Expand Up @@ -422,13 +425,13 @@ interface ContactsManager {
interface that follows these rules:

* If presenting a user interface fails or accessing the [=contacts source=]'s
[=contacts source/available contacts=] fails, then return failure.
* The UI MUST prominently display the [=browsing context=]'s [=origin=].
[=contacts source/available contacts=] fails, then return failure.
* The UI MUST prominently display the [=navigable/top-level traversable=]'s [=origin=].
* The UI MUST make it clear which `properties` of the contacts are requested.

NOTE: This information is derived from |properties|.
* The UI SHOULD provide a way for users to opt out of sharing certain contact information.

* The UI SHOULD provide a way for users to opt out of sharing certain contact information.

NOTE: If the user opts out, the appropriate [=user contact=] fields should be modified before
returning the selected contacts. It should be indistinguishable from the returned
Expand All @@ -444,7 +447,11 @@ interface ContactsManager {
remove the UI and return a [=list=] of the selected contacts as [=user contacts=].
</div>

# Acknowledgments
# Security Considerations # {#security-considerations}

TBW

# Acknowledgments # {#acknowledgments}

There has been multiple earlier attempts to standardize a Contacts API for the web and this
API strives to learn from this rich history. Earlier attempts include Mozilla's
Expand Down

0 comments on commit 488649a

Please sign in to comment.