@xplortech/apollo-core 2.5.0 → 2.7.0

package/dist/docs/xpl-input/xpl-input-phone/readme.md

@@ -0,0 +1,168 @@
+# xpl-input-phone
+
+The Phone Input Field allows users to input properly formatted phone numbers. It supports two modes: **international** (country selector + dial code prefix) and **domestic** (single country, no selector). Used as a subcomponent of `xpl-input` when `type="phone"`. The value is always emitted in **E.164** format (e.g. `+14155551234`).
+
+## Usage
+
+### International mode (default)
+
+Use via the parent component for full international support with a country selector:
+
+```html
+<xpl-input type="phone" label="Phone number" name="phone"></xpl-input>
+```
+
+With preferred countries pinned to the top of the list:
+
+```html
+<xpl-input
+  type="phone"
+  label="Phone number"
+  name="phone"
+  preferred-countries='["US","CA","GB"]'
+></xpl-input>
+```
+
+### Domestic mode
+
+Set `is-international="false"` to lock the input to a single country. The country selector trigger and dropdown are hidden, and no dial code is shown in the input. The emitted value is still E.164.
+
+```html
+<xpl-input
+  type="phone"
+  label="Phone number"
+  name="phone"
+  default-country="US"
+  is-international="false"
+></xpl-input>
+```
+
+### Pre-populating a value
+
+Pass an E.164 string to `value`. The component parses it into the correct country and national number:
+
+```html
+<xpl-input type="phone" label="Phone" value="+14155551234"></xpl-input>
+```
+
+## Value format
+
+- **value** / **valueChange**: E.164 string (e.g. `+14155551234`). You can set `value` to pre-fill; the component parses it into country and national number.
+- **defaultCountry**: ISO 3166-1 alpha-2 code (e.g. `"US"`) used when value is empty. In domestic mode, this locks the country permanently.
+- **preferredCountries**: Optional array of country codes to show at the top of the country list (international mode only).
+- **isInternational**: When `true` (default), the full international UI is shown. When `false`, the component is a simple domestic phone input locked to `defaultCountry`.
+
+## Design and behaviour
+
+### Country selector (international mode)
+
+- The **trigger** displays a country flag icon (`xpl-icon`) and a chevron-down icon.
+- Clicking the trigger opens an `xpl-dropdown` panel containing a **type-ahead search** field and a scrollable list of countries. Each option shows its flag icon, name, and dial code.
+- Search filters by country name, dial code, or ISO country code.
+- When a country is selected, focus returns to the phone input and the cursor is positioned after the dial code.
+- Countries sharing a dial code (e.g. US and Canada both use `+1`) are handled correctly: changing the country in the dropdown preserves the selection even when the dial code is the same.
+
+### Domestic mode
+
+No country selector is rendered. The input behaves as a standard phone field with country-specific formatting and validation based on `defaultCountry`. The dial code is not displayed in the input, but the emitted value is still E.164.
+
+### Input handling
+
+- **Sanitization**: Non-numeric characters are automatically stripped on every keystroke, paste, or autofill. The input only accepts digits.
+- **Max length**: Enforced per country based on the national number format (e.g. 10 digits for US/CA, 9 for AU/FR).
+- **Cursor protection** (international mode): The dial code prefix (e.g. `+1 `) is read-only within the input. Users cannot backspace into it, click before it, or use Home/ArrowLeft to move the cursor before it.
+- **Clear button**: A clear (`x-circle`) button appears when there is input and the field is not disabled or readonly.
+
+### Phone formatting
+
+The national number is formatted as the user types (e.g. US: `415 555 1234`, FR: `6 12 34 56 78`). The stored and emitted value remains E.164. Cursor position is intelligently preserved during formatting so it does not jump.
+
+Countries with custom formatters: US/CA, GB, AU, DE/AT/CH, FR, BR, MX, JP, CN, IN, KR. All other countries use a generic grouping format.
+
+### Validation and errors
+
+- When `required` is set, the component emits a `hasErrorStateChanged` event with `"required"` if the national number is empty on change.
+- The parent `xpl-input` can pass an `error` prop for external error messages (e.g. server-side validation).
+- The component applies `xpl-input-phone--error` to the host when an internal error state is active.
+
+### Accessibility
+
+- The country selector trigger has `aria-haspopup="listbox"` and `aria-expanded`.
+- The country selector trigger has `aria-label="Select country"` for screen-reader clarity.
+- The dropdown panel has `aria-label="Country"`.
+- The clear button has `aria-label="Clear phone number"`.
+- The input uses `inputmode="numeric"` to hint a numeric keyboard on mobile and `autocomplete="tel-national"` (international) or `autocomplete="tel"` (domestic).
+- The input sets `aria-invalid="true"` when in an error state (e.g. required field left empty).
+- Decorative icons (flag, chevron) use `aria-hidden="true"` to avoid screen reader noise.
+
+## Supported countries
+
+28 countries are currently supported. See `phone-country-data.ts` for the full list. Countries with custom number formatting are noted above. To add a new country, add an entry to the `PHONE_COUNTRIES` array and optionally add a formatter in `phone-format.ts`.
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property             | Attribute          | Description                                                                                                                                                                                                                    | Type       | Default     |
+| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----------- |
+| `defaultCountry`     | `default-country`  | Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. "US".                                                                                                                                                      | `string`   | `'US'`      |
+| `disabled`           | `disabled`         | Whether the field is disabled                                                                                                                                                                                                  | `boolean`  | `undefined` |
+| `inputId`            | `input-id`         | The `inputId` is used to associate the input with a label.                                                                                                                                                                     | `string`   | `undefined` |
+| `isInternational`    | `is-international` | Enables international mode with a country selector and dial code prefix. When false, the input is locked to `defaultCountry` with no country picker and no dial code shown in the display value. Emitted value is still E.164. | `boolean`  | `true`      |
+| `name`               | `name`             | Most inputs are used in forms, and should have a `name` associated with the input for handling form data.                                                                                                                      | `string`   | `undefined` |
+| `placeholder`        | `placeholder`      | Placeholder text that appears when the field has no value                                                                                                                                                                      | `string`   | `undefined` |
+| `preferredCountries` | --                 | Country codes to show at the top of the country list, e.g. ["US", "CA", "GB"].                                                                                                                                                 | `string[]` | `undefined` |
+| `readonly`           | `readonly`         | Whether the input is editable                                                                                                                                                                                                  | `boolean`  | `undefined` |
+| `required`           | `required`         | Whether the input is required                                                                                                                                                                                                  | `boolean`  | `undefined` |
+| `value`              | `value`            | Including a `value` will pre-populate the input (E.164 format, e.g. +14155551234).                                                                                                                                             | `string`   | `undefined` |
+
+
+## Events
+
+| Event                  | Description                                                     | Type                  |
+| ---------------------- | --------------------------------------------------------------- | --------------------- |
+| `hasErrorStateChanged` | Event that is emitted when the hasErrorState state changes.     | `CustomEvent<string>` |
+| `valueChange`          | Event that emits the current value of the input (E.164 format). | `CustomEvent<string>` |
+
+
+## Dependencies
+
+### Used by
+
+ - [xpl-input](..)
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+- [xpl-dropdown](../../xpl-dropdown)
+- [xpl-input](..)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-input-phone --> xpl-icon
+  xpl-input-phone --> xpl-dropdown
+  xpl-input-phone --> xpl-input
+  xpl-dropdown --> xpl-dropdown-group
+  xpl-dropdown --> xpl-dropdown-option
+  xpl-dropdown-group --> xpl-dropdown-group
+  xpl-dropdown-group --> xpl-dropdown-option
+  xpl-dropdown-group --> xpl-dropdown-heading
+  xpl-dropdown-option --> xpl-icon
+  xpl-input --> xpl-input-phone
+  xpl-input-file --> xpl-icon
+  xpl-input-color --> xpl-popover
+  xpl-input-color --> xpl-icon
+  xpl-input-color --> xpl-input
+  xpl-input-date --> xpl-icon
+  xpl-input-time --> xpl-input
+  xpl-input-time --> xpl-icon
+  xpl-input-time --> xpl-dropdown
+  xpl-input-search --> xpl-icon
+  style xpl-input-phone fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-input/xpl-input-search/readme.md

@@ -0,0 +1,175 @@
+# xpl-input-search
+
+Inner search field used by [`xpl-input`](../readme.md) when `type="search"`. It provides a leading magnifier, a native text field with `role="searchbox"`, an optional clear control, and a `shape` shell (`rounded` pill vs `box`). You normally consume search through **`xpl-input`**; use `xpl-input-search` only when composing a custom shell that still matches Apollo search visuals.
+
+## Usage
+
+### Recommended: `xpl-input` with `type="search"`
+
+Default pill shell (`shape` defaults to `rounded`), placeholder, and optional `name` for forms:
+
+```html
+<xpl-input type="search" name="q" placeholder="Search products"></xpl-input>
+```
+
+Visible label, description, `box` shape, and `autocomplete`:
+
+```html
+<xpl-input
+  type="search"
+  label="Search catalog"
+  description="SKU or product name"
+  name="q"
+  placeholder="SKU or name"
+  shape="box"
+  autocomplete="search"
+></xpl-input>
+```
+
+When there is no visible label, set `aria-label` on `xpl-input` (forwarded to the inner field for assistive naming):
+
+```html
+<xpl-input type="search" aria-label="Search help topics" placeholder="Search…"></xpl-input>
+```
+
+Error state (border, `aria-invalid`, and error text on the parent) and an initial value (clear control appears when there is text):
+
+```html
+<xpl-input type="search" shape="box" error="Invalid query" value="abc"></xpl-input>
+```
+
+Listening for submit and live updates (vanilla JS):
+
+```html
+<xpl-input id="search" type="search" placeholder="Search"></xpl-input>
+<script type="module">
+  const el = document.getElementById('search');
+  el.addEventListener('search', (e) => {
+    console.log('submit', e.detail); // trimmed string
+  });
+  el.addEventListener('valueChange', (e) => {
+    console.log('value', e.detail); // raw string
+  });
+</script>
+```
+
+### Events on `<xpl-input type="search">`
+
+`valueChange`, `inputEvent`, `focusEvent`, and `blurEvent` are Stencil **`@Event`s** on **`xpl-input-search`** and **bubble** to the **`<xpl-input>`** host. **`focusEvent`** / **`blurEvent`** are also **re-emitted from `<xpl-input>`** so **`event.target`** matches **`type="text"`** (see **`xpl-input`** readme). **`valueChange`** / **`inputEvent`** are **not** re-emitted by the parent; use **`event.detail`** for the string if you do not want to depend on **`event.target`**.
+
+The **commit** signal is a Stencil **`search`** **`@Event`** on **`xpl-input-search`** (trimmed query in **`detail`**). **`xpl-input`** wires **`onSearch`** on the inner tag, **`stopPropagation`s**, and **`this.search.emit(detail)`** so the public **`search`** **`@Event`** remains on **`<xpl-input>`**. **`setFocus()`** on **`<xpl-input>`** uses a **`ref`** to call the inner **`setFocus()`** only.
+
+For advanced composition you can render `<xpl-input-search>` directly. You must pass **`input-id`** (matches a `<label for="…">` when used with a visible label). Set **`disabled`** and **`has-error`** (plus **`error-message-id`** when invalid) for both accessibility and visuals: the host adds `xpl-input-search--disabled` / `xpl-input-search--error` so disabled and error chrome match the wrapped `xpl-input` case. When nested under `xpl-input type="search"`, those props are set for you from the parent.
+
+```html
+<label class="xpl-input-label" for="sid">Search</label>
+<xpl-input-search input-id="sid" name="q" placeholder="Search…"></xpl-input-search>
+```
+
+## Design tokens
+
+| Part | Token |
+| ---- | ----- |
+| Host text (input inherits) | `--xpl-text-default` |
+| Shell layout | `gap`: `--xpl-space-12`; horizontal padding: `--xpl-space-12`; `min-height` / `max-height`: `--xpl-size-250` |
+| Shell fill (resting) | `--xpl-background-surface-default` |
+| Shell `border-radius` (pill, default `shape="rounded"`) | `--xpl-border-radius-button` |
+| Shell `border-radius` (`shape="box"`) | `--xpl-border-radius-small` |
+| Shell border (resting) | `--xpl-border-default` |
+| Shell border (input focus, empty) | `--xpl-border-active` |
+| Shell border (input focus, with value) | `--xpl-border-focus` |
+| Shell border (error, from parent `xpl-input`) | `--xpl-border-negative` |
+| Disabled shell (parent) | `--xpl-background-action-disabled` |
+| Input typography | `--xpl-font-family-default`, `--xpl-font-size-body`, `--xpl-font-weight-normal` |
+| Placeholder | `--xpl-text-subdued` |
+| Disabled text / placeholder (parent) | `--xpl-text-disabled` |
+| Leading icon | `--xpl-icon-default` / `--xpl-icon-disabled` |
+| Clear icon | `--xpl-icon-subtle` |
+| Caret (focus, with value) | `--xpl-border-focus` |
+| Caret (focus, error, parent) | `--xpl-border-negative` |
+
+Light and dark mode use Foundation purpose-specific tokens only (no component `.dark` overrides).
+
+## Icon mapping
+
+| Role | When | `xpl-icon` name | `size` |
+| ---- | ---- | ----------------- | ------ |
+| Leading search | Always (when the control renders) | `magnifier` | 20 |
+| Clear | Value non-empty and not `disabled` | `circle-xmark` | 16 |
+
+## Accessibility
+
+- **Role and naming:** The field uses a native `<input type="text">` with `role="searchbox"`. `type="text"` avoids browser search-field chrome that would clash with the design-system clear control. When the parent does not render a visible label, `aria-label` on the inner input defaults to `"Search"` unless `ariaLabel` / parent `aria-label` overrides it. With a visible label, the input is named via `<label for="…">` and redundant `aria-label` on the input is omitted.
+- **`autocomplete`:** Default `off` is typical for inline search; set `autocomplete` on `xpl-input` for search fields when you need a specific token.
+- **Errors:** With `xpl-input`, non-empty `error` sets `aria-invalid`, links the message with `aria-describedby`, and styles the shell from the parent host.
+- **Keyboard — standalone `xpl-input-search`:** An inner `<form>` wraps the shell when the host is not already inside a `<form>`. **Enter** submits that inner form (default prevented); the host emits a Stencil **`search`** event (trimmed value in **`detail`**). Listen with **`addEventListener('search', …)`** on **`xpl-input-search`**. **Tab** visits the input and the clear control when visible.
+- **Keyboard — inside a parent `<form>`:** The inner `<form>` is omitted. **Enter** uses native form submission; listen on the parent form’s **`submit`**. Use **`valueChange`** / **`inputEvent`** for live typing.
+- **Clear control:** The clear button exposes **`aria-label="Clear search"`**. Activating it clears the value, emits **`valueChange`** / **`inputEvent`** with `''`, and refocuses the input. When **`disabled`** or **`readonly`** is true, the clear control is hidden and inert (no value mutation).
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property               | Attribute           | Description                                                                                                                                                                                                                                                                                                                               | Type                 | Default     |
+| ---------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
+| `ariaLabel`            | `aria-label`        | Accessible name when there is no visible label from the parent; maps to `aria-label` on the input. When the parent provides a visible label, the input is named by `<label for="…">` — this prop is ignored for naming. Empty or whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed. | `string`             | `'Search'`  |
+| `autocomplete`         | `autocomplete`      | Passed to the native input (`autocomplete` attribute). Default `off` matches common inline-search UX; browsers may still apply heuristics.                                                                                                                                                                                                | `string`             | `'off'`     |
+| `disabled`             | `disabled`          | Disables the field and clear control.                                                                                                                                                                                                                                                                                                     | `boolean`            | `false`     |
+| `errorMessageId`       | `error-message-id`  | Element id for `aria-describedby` when `hasError` (error message lives on `xpl-input`).                                                                                                                                                                                                                                                   | `string`             | `undefined` |
+| `hasError`             | `has-error`         | Set by `xpl-input` when `error` is shown — drives `aria-invalid` / `aria-describedby`.                                                                                                                                                                                                                                                    | `boolean`            | `false`     |
+| `hasVisibleLabel`      | `has-visible-label` | When true, parent `xpl-input` renders a visible label — omit `aria-label` on the input.                                                                                                                                                                                                                                                   | `boolean`            | `false`     |
+| `inputId` _(required)_ | `input-id`          | Associates the control with the parent `xpl-input` label (`for` / `id`).                                                                                                                                                                                                                                                                  | `string`             | `undefined` |
+| `name`                 | `name`              | Form field `name` on the native input.                                                                                                                                                                                                                                                                                                    | `string`             | `undefined` |
+| `placeholder`          | `placeholder`       | Placeholder shown when the value is empty.                                                                                                                                                                                                                                                                                                | `string`             | `'Search'`  |
+| `readonly`             | `readonly`          | Whether the input is editable.                                                                                                                                                                                                                                                                                                            | `boolean`            | `false`     |
+| `required`             | `required`          | Whether the input is required.                                                                                                                                                                                                                                                                                                            | `boolean`            | `false`     |
+| `shape`                | `shape`             | Shell corner radius: `rounded` (pill) or `box` (rounded rectangle).                                                                                                                                                                                                                                                                       | `"box" \| "rounded"` | `'rounded'` |
+| `value`                | `value`             | Current value (controlled-friendly).                                                                                                                                                                                                                                                                                                      | `string`             | `''`        |
+
+
+## Events
+
+| Event         | Description                                                                                                                                                                                                                                                                                                        | Type                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
+| `blurEvent`   | Emitted when the inner control loses focus. When nested under `xpl-input type="search"`, this event bubbles to the `xpl-input` host (same event name as other input types).                                                                                                                                        | `CustomEvent<FocusEvent>` |
+| `focusEvent`  | Emitted when the inner control receives focus. When nested under `xpl-input type="search"`, this event bubbles to the `xpl-input` host (same event name as other input types).                                                                                                                                     | `CustomEvent<FocusEvent>` |
+| `inputEvent`  | Fired on every input change (typing, paste) and when the value is cleared — mirrors `xpl-input` text fields. When nested under `xpl-input type="search"`, bubbles to the `xpl-input` host.                                                                                                                         | `CustomEvent<string>`     |
+| `search`      | Emitted when the user commits a search (Enter with no enclosing form owner, or submit of the inner search form). `event.detail` is the trimmed query string. When nested under `xpl-input type="search"`, the parent listens with `onSearch` and re-emits so the canonical `search` `@Event` stays on `xpl-input`. | `CustomEvent<string>`     |
+| `valueChange` | Fired on every input change (typing, paste) and when the value is cleared. `event.detail` is the raw `value` string (not trimmed). When nested under `xpl-input type="search"`, bubbles to the `xpl-input` host.                                                                                                   | `CustomEvent<string>`     |
+
+
+## Methods
+
+### `setFocus() => Promise<void>`
+
+Moves keyboard focus to the search field.
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+
+## Dependencies
+
+### Used by
+
+ - [xpl-input](..)
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-input-search --> xpl-icon
+  xpl-input --> xpl-input-search
+  style xpl-input-search fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-input/xpl-input-time/readme.md

@@ -56,11 +56,16 @@ graph TD;
   xpl-input-color --> xpl-icon
   xpl-input-color --> xpl-input
   xpl-input-date --> xpl-icon
+  xpl-input-phone --> xpl-icon
+  xpl-input-phone --> xpl-dropdown
+  xpl-input-phone --> xpl-input
   xpl-dropdown --> xpl-dropdown-group
   xpl-dropdown --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-group
   xpl-dropdown-group --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-heading
+  xpl-dropdown-option --> xpl-icon
+  xpl-input-search --> xpl-icon
   style xpl-input-time fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

package/dist/docs/xpl-large-card/readme.md

@@ -1,6 +1,6 @@
 # xpl-large-card
 
-
+A card is a container and can contain any type of information. Cards contain actions and a content slot. Cards are flexible and can be arranged in grids or lists.
 
 <!-- Auto Generated Below -->