@aurodesignsystem-dev/auro-datetime 0.0.0-pr110.0 → 0.0.0-pr112.0

package/README.md

@@ -12,7 +12,7 @@ The following sections are editable by making changes to the following files:
 | SECTION                | DESCRIPTION                                       | FILE LOCATION                       |
 |------------------------|---------------------------------------------------|-------------------------------------|
 | Description            | Description of the component                      | `./docs/partials/description.md`    |
-| Use Cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
+| Use cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
 | Additional Information | For use to add any component specific information | `./docs/partials/readmeAddlInfo.md` |
 | Component Example Code | HTML sample code of the components use            | `./apiExamples/basic.html`          |
 -->
@@ -21,20 +21,22 @@ The following sections are editable by making changes to the following files:
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
 <!-- The below content is automatically added from ./docs/partials/description.md -->
-The `<auro-datetime>` custom element makes it really easy to add dates to your web app with a simple HTML API.
+The `<auro-datetime>` element shows a date or time as text, formatted for a language and region you choose and, optionally, a specific time zone. Set `type` to choose the full date, the time, a numeric date, or a single part, such as the weekday.
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/readmeAddlInfo.md) -->
 <!-- The below content is automatically added from ./docs/partials/readmeAddlInfo.md -->
 <!-- AURO-GENERATED-CONTENT This file is to be used for any additional content that should be included in the README.md which is specific to this component. -->
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Use Cases
+## Use cases
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
 <!-- The below content is automatically added from ./docs/partials/useCases.md -->
-The `<auro-datetime>` element should be used in situations where users may:
+Use `<auro-datetime>` to:
 
-* A date and/or time is required
+* Show a date or time, such as a departure date or arrival time.
+* Show a time in a specific time zone, such as a flight's local time at its airport.
+* Format a date for a language and region, such as `de-DE` or `ja-JP`.
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Install
@@ -45,84 +47,71 @@ The `<auro-datetime>` element should be used in situations where users may:
 [![License](https://img.shields.io/npm/l/@aurodesignsystem/auro-datetime?color=blue&style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)
 ![ESM supported](https://img.shields.io/badge/ESM-compatible-FFE900?style=for-the-badge)
 
-```shell
-$ npm i @aurodesignsystem/auro-datetime
-```
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-datetime</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
-### Define Dependency in Project
+### Define dependency in project
 
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/componentImportDescription.md) -->
-Defining the dependency within each project that is using the `<auro-datetime>` component.
+Import the component in each project that uses `<auro-datetime>`.
 
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/componentImport.md) -->
 
-```js
-import "@aurodesignsystem/auro-datetime";
-```
+<pre class="language-js"><code class="language-js">import "@aurodesignsystem/auro-datetime";</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ### Use CDN
 
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/bundleInstallDescription.md) -->
-In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
+If your project can't process JS assets, use the pre-processed assets. Legacy browsers, such as IE11, aren't supported.
 
-```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-datetime@latest/+esm"></script>
-```
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-datetime@latest/+esm"&gt;&lt;/script&gt;</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Basic Example
+## Basic example
 
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./apiExamples/basic.html) -->
 <!-- The below code snippet is automatically added from ./apiExamples/basic.html -->
 
-```html
-<auro-datetime type="date"></auro-datetime>
-```
+<pre class="language-html"><code class="language-html">&lt;auro-datetime type="date"&gt;&lt;/auro-datetime&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Custom Component Registration for Version Management
+## Custom component registration for version management
 
-There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition.
+Every Auro component has two key parts: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition.
 The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.
 
-When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
+Installing the component as described in the Install section imports the class and registers the component globally for you.
 
-However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
+However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), register the class manually under a custom element name to avoid conflicts.
 
-You can do this by importing only the component class and using the `register(name)` method with a unique name:
+To do this, import only the component class and call the `register(name)` method with a unique name:
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
 <!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
 
-```js
-// Import the class only
+<pre class="language-js"><code class="language-js">// Import the class only
 import { AuroDatetime } from '@aurodesignsystem/auro-datetime/class';
+&#10;// Register it under a custom name
+AuroDatetime.register('custom-datetime');</code></pre>
 
-// Register with a custom name if desired
-AuroDatetime.register('custom-datetime');
-```
-
-This will create a new custom element `<custom-datetime>` that behaves exactly like `<auro-datetime>`, allowing both to coexist on the same page without interfering with each other.
+`<custom-datetime>` then works the same as `<auro-datetime>`, and both can run on the same page without affecting each other.
 <!-- AURO-GENERATED-CONTENT:END -->
 <div class="exampleWrapper exampleWrapper--flex">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./apiExamples/custom.html) -->
-  <!-- The below content is automatically added from ./apiExamples/custom.html -->
-  <custom-datetime type="date"></custom-datetime>
-  <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./apiExamples/custom.html) -->
+<!-- The below content is automatically added from ./apiExamples/custom.html -->
+<custom-datetime type="date"></custom-datetime>
+<!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+<span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./apiExamples/custom.html) -->
 <!-- The below code snippet is automatically added from ./apiExamples/custom.html -->
 
-```html
-<custom-datetime type="date"></custom-datetime>
-```
+<pre class="language-html"><code class="language-html">&lt;custom-datetime type="date"&gt;&lt;/custom-datetime&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>

package/custom-elements.json

@@ -0,0 +1,373 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/auro-datetime.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Shows a date or time as text, formatted for a language and region you choose and, optionally, a specific time zone.\n\n**Key capabilities**\n- **What to show**: `type` picks the full date, the time, a numeric date, or a single part, such as the year or weekday.\n- **Date and time to show**: `value` takes an ISO 8601 date or date-time; without it, the element shows the current date and time.\n- **Language formatting**: `locale` formats month names, separators, and the 12- or 24-hour clock for a language, such as `de-DE`.\n- **Time zones**: `timezone` shows the moment in a time zone, such as `America/Los_Angeles`.\n- **Name length**: `month=\"long\"` and `weekday=\"long\"` spell out the month and weekday names.\n\n**Example**\n```html\n<auro-datetime type=\"date\" value=\"2022-07-14T08:00:00\"></auro-datetime>\n```",
+          "name": "AuroDatetime",
+          "slots": [
+            {
+              "description": "Content shown after the `post` slot's content, such as the end of a sentence that includes the date.",
+              "name": "",
+              "category": "ui"
+            },
+            {
+              "description": "Content shown after the date or time, such as \"local time\". The element doesn't currently let content sit right against the date or time: this content, or text right after the element, always shows with a space between them, so a period or comma can't follow the date or time directly.",
+              "name": "post",
+              "category": "ui"
+            },
+            {
+              "description": "Content shown before the date or time, such as \"Departs\". The element doesn't currently let content sit right against the date or time: this content, or text right before the element, always shows with a space between it and the date or time.",
+              "name": "pre",
+              "category": "ui"
+            }
+          ],
+          "members": [
+            {
+              "kind": "method",
+              "name": "_initializeDefaults",
+              "description": "Sets the element's default values.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_resolveInputDate",
+              "description": "Gets the Date to show and the `timeZone` option for `Intl.DateTimeFormat`,\nfrom `value` and `timezone`. Returns `{ date: null }` for invalid input,\nincluding an empty string.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ date: Date | null, timeZoneOption: string | undefined }"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_resolveLocale",
+              "parameters": [
+                {
+                  "name": "input",
+                  "description": "The locale tag set on the element.",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Checks a BCP 47 locale tag and returns its canonical form. Empty or invalid\ninput falls back to \"en-US\". Each invalid value logs a console warning the\nfirst time this element sees it.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_resolveTimeZone",
+              "parameters": [
+                {
+                  "name": "input",
+                  "description": "The time zone name set on the element.",
+                  "type": {
+                    "text": "string | undefined"
+                  }
+                }
+              ],
+              "description": "Checks an IANA time zone name. An invalid name logs a console warning\nthe first time this element sees it and returns `undefined`, so the\nelement acts as if `timezone` isn't set.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string | undefined"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_zonedWallClockToUtc",
+              "parameters": [
+                {
+                  "name": "localISO",
+                  "description": "The ISO 8601 date-time with no offset, such as \"2022-07-14T08:00:00\".",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "timeZone",
+                  "description": "The IANA time zone name, such as \"America/New_York\".",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Creates a Date that shows the given wall-clock time when displayed in\nthe given IANA time zone. `_resolveInputDate` uses it when `value` has\nno offset and `timezone` is set, so the time is read as already being\nin that zone rather than the viewer's.\n\nIt parses the wall-clock time as if it were UTC, asks `Intl` what that\nmoment looks like in the target zone, and uses the difference between\nthe two to find the real moment.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Date"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "humanDate",
+              "description": "Formats the full date, such as \"Thu, Jul 14, 2022\", with the current `month` and `weekday` settings.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "humanDateConversion",
+              "description": "Formats the single date part that `type` names: the year, month, weekday, or day.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "humanTime",
+              "description": "Formats the hour and minute. When the time ends in AM or PM, it lowercases the period and drops a leading zero.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "field",
+              "name": "locale",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sets the language and region used to format the date or time, such as `en-GB`, `de-DE`, or `ja-JP` (a BCP 47 language tag). It changes month and weekday names, separators, and whether times use a 12- or 24-hour clock, but not the time zone. A malformed tag logs a console warning and falls back to `en-US`; a well-formed tag the browser doesn't support, such as `zz-ZZ`, uses the browser's default language instead, with no warning.",
+              "default": "\"en-US\"",
+              "attribute": "locale",
+              "category": "ui"
+            },
+            {
+              "kind": "field",
+              "name": "month",
+              "privacy": "public",
+              "type": {
+                "text": "\"short\" | \"long\""
+              },
+              "description": "Sets how the month name is written: `short`, such as \"Jul\", or `long`, such as \"July\". It applies to the full date and to `type=\"month\"`.",
+              "default": "\"short\"",
+              "attribute": "month",
+              "category": "ui"
+            },
+            {
+              "kind": "method",
+              "name": "numericDate",
+              "description": "Formats the date in numbers, in the order and with the separators `locale` uses, such as \"7/14/2022\" for `en-US`.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "register",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "name",
+                  "default": "\"auro-datetime\"",
+                  "description": "The tag name to register the element under, such as `custom-datetime`.",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Registers the element with the browser under a tag name. Use a custom name to run more than one version of the element on the same page. If the tag name is already registered, it does nothing.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "type": {
+                "text": "register(name?: string = \"auro-datetime\") => void"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "timezone",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sets the time zone to show the date or time in, such as `America/Los_Angeles` or `UTC` (an IANA time zone name). When `value` has an offset or `Z`, the element converts that moment into this zone; when it has none, the element reads `value` as a time already in this zone. Without it, or with an invalid name, which logs a console warning, the element shows the date and time in `value` as written, or the current date and time in the viewer's own time zone when `value` isn't set.",
+              "attribute": "timezone",
+              "category": "behavior"
+            },
+            {
+              "kind": "field",
+              "name": "type",
+              "privacy": "public",
+              "type": {
+                "text": "\"date\" | \"time\" | \"year\" | \"month\" | \"weekday\" | \"day\" | \"numeric\""
+              },
+              "description": "Sets which part of the date or time to show: `date` for the full date, such as \"Thu, Jul 14, 2022\", `numeric` for a numeric date, such as \"7/14/2022\", `time` for the hour and minute, such as \"8:00 am\", or `year`, `month`, `weekday`, or `day` for that part alone. Without it, or with any other value, the element shows the full date.",
+              "attribute": "type",
+              "category": "ui"
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sets the date or time to show, as an ISO 8601 date or date-time, such as `2022-07-14`, `2022-07-14T08:00:00`, or `2022-07-14T08:00:00-07:00`. Without it, the element shows the current date and time from when it last rendered; it doesn't currently update as time passes. Invalid input, including an empty value, logs a console warning and shows nothing.",
+              "attribute": "value",
+              "category": "behavior"
+            },
+            {
+              "kind": "field",
+              "name": "weekday",
+              "privacy": "public",
+              "type": {
+                "text": "\"short\" | \"long\""
+              },
+              "description": "Sets how the weekday name is written: `short`, such as \"Thu\", or `long`, such as \"Thursday\". It applies to the full date and to `type=\"weekday\"`.",
+              "default": "\"short\"",
+              "attribute": "weekday",
+              "category": "ui"
+            },
+            {
+              "kind": "method",
+              "name": "whichDate",
+              "description": "Gets the text to show for the current `type`.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sets the language and region used to format the date or time, such as `en-GB`, `de-DE`, or `ja-JP` (a BCP 47 language tag). It changes month and weekday names, separators, and whether times use a 12- or 24-hour clock, but not the time zone. A malformed tag logs a console warning and falls back to `en-US`; a well-formed tag the browser doesn't support, such as `zz-ZZ`, uses the browser's default language instead, with no warning.",
+              "default": "\"en-US\"",
+              "fieldName": "locale",
+              "category": "ui"
+            },
+            {
+              "name": "month",
+              "type": {
+                "text": "\"short\" | \"long\""
+              },
+              "description": "Sets how the month name is written: `short`, such as \"Jul\", or `long`, such as \"July\". It applies to the full date and to `type=\"month\"`.",
+              "default": "\"short\"",
+              "fieldName": "month",
+              "category": "ui"
+            },
+            {
+              "name": "timezone",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sets the time zone to show the date or time in, such as `America/Los_Angeles` or `UTC` (an IANA time zone name). When `value` has an offset or `Z`, the element converts that moment into this zone; when it has none, the element reads `value` as a time already in this zone. Without it, or with an invalid name, which logs a console warning, the element shows the date and time in `value` as written, or the current date and time in the viewer's own time zone when `value` isn't set.",
+              "fieldName": "timezone",
+              "category": "behavior"
+            },
+            {
+              "name": "type",
+              "type": {
+                "text": "\"date\" | \"time\" | \"year\" | \"month\" | \"weekday\" | \"day\" | \"numeric\""
+              },
+              "description": "Sets which part of the date or time to show: `date` for the full date, such as \"Thu, Jul 14, 2022\", `numeric` for a numeric date, such as \"7/14/2022\", `time` for the hour and minute, such as \"8:00 am\", or `year`, `month`, `weekday`, or `day` for that part alone. Without it, or with any other value, the element shows the full date.",
+              "fieldName": "type",
+              "category": "ui"
+            },
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sets the date or time to show, as an ISO 8601 date or date-time, such as `2022-07-14`, `2022-07-14T08:00:00`, or `2022-07-14T08:00:00-07:00`. Without it, the element shows the current date and time from when it last rendered; it doesn't currently update as time passes. Invalid input, including an empty value, logs a console warning and shows nothing.",
+              "fieldName": "value",
+              "category": "behavior"
+            },
+            {
+              "name": "weekday",
+              "type": {
+                "text": "\"short\" | \"long\""
+              },
+              "description": "Sets how the weekday name is written: `short`, such as \"Thu\", or `long`, such as \"Thursday\". It applies to the full date and to `type=\"weekday\"`.",
+              "default": "\"short\"",
+              "fieldName": "weekday",
+              "category": "ui"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "auro-datetime",
+          "customElement": true,
+          "summary": "Date or time text formatted by language and time zone, with full, numeric, and single-part formats.",
+          "modulePath": "src/auro-datetime.js"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "AuroDatetime",
+          "declaration": {
+            "name": "AuroDatetime",
+            "module": "src/auro-datetime.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/index.js",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "AuroDatetime",
+          "declaration": {
+            "name": "AuroDatetime",
+            "module": "src/index.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/registered.js",
+      "declarations": [],
+      "exports": []
+    }
+  ],
+  "package": "@aurodesignsystem-dev/auro-datetime@0.0.0-pr112.0"
+}