@xplortech/apollo-core 2.5.0 → 2.6.0

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

@@ -0,0 +1,167 @@
+# 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
+  style xpl-input-phone 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,15 @@ 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
   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 -->
 

package/dist/docs/xpl-modal/readme.md

@@ -1,6 +1,8 @@
 # xpl-modal
 
+Modals are dialogs that focus the user’s attention exclusively on one task or piece of information via a window layer above the current content.
 
+Modals are disruptive and should only be used when disrupting the user’s flow is desired.
 
 <!-- Auto Generated Below -->
 
@@ -47,6 +49,7 @@ graph TD;
   xpl-modal --> xpl-backdrop
   xpl-modal --> xpl-icon
   xpl-modal --> xpl-button
+  xpl-button --> xpl-icon
   style xpl-modal fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

package/dist/docs/xpl-pagination/readme.md

@@ -1,5 +1,7 @@
 # xpl-pagination
 
+Pagination bar allows users to navigate pages of content.
+
 > **Note:** This component is in beta. Use with caution and expect updates before the full release.
 
 <!-- Auto Generated Below -->
@@ -44,6 +46,7 @@ graph TD;
   xpl-dropdown-group --> xpl-dropdown-group
   xpl-dropdown-group --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-heading
+  xpl-dropdown-option --> xpl-icon
   style xpl-pagination fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

package/dist/docs/xpl-panel/readme.md

@@ -0,0 +1,83 @@
+# xpl-panel
+
+## Overview
+
+XPL-Panel is a stateless, composable container component that defines a section on a page and can house any type of content. Panels are not dismissible and may contain a top accent in 5 standard accent colors.
+
+## Usage
+
+### Basic panel (no accent)
+
+```html
+<xpl-panel>
+  <p>Any content goes here.</p>
+</xpl-panel>
+```
+
+### Panel with accent
+
+```html
+<xpl-panel accent="primary">
+  <p>Content with a primary accent bar.</p>
+</xpl-panel>
+```
+
+Available accent values: `none` (default), `primary`, `secondary`, `positive`,
+`negative`, `highlight`.
+
+### Padding density
+
+```html
+<xpl-panel padding="tight">
+  <p>Tighter padding on all breakpoints.</p>
+</xpl-panel>
+```
+
+Available padding values: `default`, `tight`, `loose`. Padding is responsive
+and automatically scales down at tablet (768 px) and mobile (480 px) breakpoints.
+
+### Composing with other components
+
+```html
+<xpl-panel accent="secondary" padding="loose">
+  <xpl-accordion header="Details">
+    <div slot="content">Accordion inside a panel.</div>
+  </xpl-accordion>
+</xpl-panel>
+```
+
+### Dark mode
+
+Wrap with an ancestor that has the `dark` class — the panel automatically
+adapts its background, border, and accent colors.
+
+## Design
+
+- [Figma: XPL-Panel](https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=1546-136120&p=f&t=SMeY3LnfDOiNmx1p-11)
+
+<!-- Auto Generated Below -->
+
+
+## Overview
+
+A stateless container that defines a section on a page and can house any
+type of content. Panels are not dismissible and may contain a top accent.
+
+## Properties
+
+| Property  | Attribute | Description                                                                                                                                                                                                                                                                         | Type                                                                            | Default     |
+| --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------- |
+| `accent`  | `accent`  | Color accent bar displayed at the top of the panel.  - `none` – no accent (default) - `primary` – brand primary color - `secondary` – brand secondary color - `positive` – positive / success color - `negative` – negative / error color - `highlight` – highlight / warning color | `"highlight" \| "negative" \| "none" \| "positive" \| "primary" \| "secondary"` | `'none'`    |
+| `padding` | `padding` | Padding density applied to the content area. Responsive: scales down at tablet and mobile breakpoints.  - `default` – 24 px desktop / 16 px tablet+mobile - `tight`   – 16 px desktop / 8 px tablet+mobile - `loose`   – 40 px desktop / 32 px tablet / 24 px mobile                | `"default" \| "loose" \| "tight"`                                               | `'default'` |
+
+
+## Slots
+
+| Slot | Description                                                                                                        |
+| ---- | ------------------------------------------------------------------------------------------------------------------ |
+|      | Default slot for panel content. Compose other Apollo components within the slot or build your own local component. |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-popover/readme.md

@@ -1,6 +1,6 @@
 # xpl-popover
 
-
+A popover is an overlay that pops up over all other layers and is triggered by a click or tap, and dismissed by clicking outside the popover or a dismiss icon. Popovers can contain additional actions and allow those actions to be triggered.
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-progress-bar/readme.md

@@ -0,0 +1,145 @@
+# xpl-progress-bar
+
+The `xpl-progress-bar` component displays the progress of an operation, such as file uploads, form completion, or loading states. It supports multiple visual variants including default, success, error, and indeterminate states, with optional label and helper text.
+
+## Usage
+
+### Basic progress bar
+
+```html
+<xpl-progress-bar label="Uploading..." value="45"></xpl-progress-bar>
+```
+
+### With helper text
+
+```html
+<xpl-progress-bar
+    label="Uploading file..."
+    value="65"
+    helper-text="2.4 MB of 5 MB">
+</xpl-progress-bar>
+```
+
+### Error state
+
+```html
+<xpl-progress-bar
+    label="Upload failed"
+    value="30"
+    variant="error"
+    helper-text="Network error. Please check your connection.">
+</xpl-progress-bar>
+```
+
+### Indeterminate loading
+
+```html
+<xpl-progress-bar label="Processing..." variant="indeterminate"></xpl-progress-bar>
+```
+
+### Small size
+
+```html
+<xpl-progress-bar value="60" size="sm"></xpl-progress-bar>
+```
+
+### Custom max value
+
+```html
+<xpl-progress-bar value="75" max="150" label="75 of 150 items"></xpl-progress-bar>
+```
+
+## Variants
+
+| Variant | Description |
+|---------|-------------|
+| `default` | Standard progress bar with accent color fill. Shows a checkmark icon when value reaches max. |
+| `success` | Explicit success state with positive color. Shows a checkmark icon. |
+| `error` | Error state with negative color. Shows an error (x-mark) icon. Helper text is recommended for this state. |
+| `indeterminate` | Used when the progress duration is unknown. Displays an animated sliding bar instead of a fill percentage. |
+
+## Sizes
+
+- `lg` (default): 6px height
+- `sm`: 4px height
+
+## Icon Mapping
+
+The component automatically renders status icons based on the variant or completion state:
+
+| State | xpl-icon name |
+|-------|---------------|
+| Complete (default variant when value equals max) | `circle-check-1` |
+| Success variant | `circle-check-1` |
+| Error variant | `circle-xmark-1` |
+
+## Design Tokens
+
+The following Apollo Foundation tokens are used by this component:
+
+### Background Colors (Fill)
+- `--xpl-background-accent-default` - Default variant fill
+- `--xpl-background-accent-positive-bold` - Success/complete fill
+- `--xpl-background-accent-negative-bold` - Error fill
+- `--xpl-background-accent-neutral` - Track background
+
+### Icon Colors
+- `--xpl-icon-positive` - Success/complete icon
+- `--xpl-icon-negative` - Error icon
+
+### Text Colors
+- `--xpl-text-default` - Label text
+- `--xpl-text-subdued` - Helper text
+- `--xpl-text-negative` - Error helper text
+
+### Typography
+- `--xpl-font-size-callout` - Label font size
+- `--xpl-font-size-caption` - Helper text font size
+- `--xpl-font-weight-normal` - Label and helper font weight
+
+### Spacing & Sizing
+- `--xpl-space-8` - Gap between elements
+- `--xpl-size-025` (4px) - Small bar height
+- `--xpl-size-0375` (6px) - Large bar height
+- `--xpl-border-radius-full` - Bar border radius
+
+## Accessibility
+
+- **Determinate variants** (default, success, error) use the native HTML `<progress>` element, which provides:
+  - Native `role="progressbar"` semantics
+  - Automatic `aria-valuenow`, `aria-valuemin`, `aria-valuemax` handling
+  - Native value/max API with built-in clamping
+- **Indeterminate variant** uses a custom `<div role="progressbar">` since native `<progress>` indeterminate state cannot be styled cross-browser
+- The `aria-label` is set from the `label` prop, or falls back to `'Progress'` when no label is provided
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property     | Attribute     | Description                                                                    | Type                                                   | Default     |
+| ------------ | ------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ | ----------- |
+| `helperText` | `helper-text` | The helper text displayed below the progress bar (recommended for error state) | `string`                                               | `undefined` |
+| `label`      | `label`       | The label text displayed above the progress bar                                | `string`                                               | `undefined` |
+| `max`        | `max`         | The maximum value of the progress (mirrors native <progress> max attribute)    | `number`                                               | `100`       |
+| `size`       | `size`        | The size of the progress bar height: sm = 4px, lg = 6px                        | `"lg" \| "sm"`                                         | `'lg'`      |
+| `value`      | `value`       | The current value of the progress (mirrors native <progress> value attribute)  | `number`                                               | `0`         |
+| `variant`    | `variant`     | The visual variant of the progress bar                                         | `"default" \| "error" \| "indeterminate" \| "success"` | `'default'` |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-icon](../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-progress-bar --> xpl-icon
+  style xpl-progress-bar fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-select/readme.md

@@ -78,6 +78,7 @@ graph TD;
   xpl-dropdown-group --> xpl-dropdown-group
   xpl-dropdown-group --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-heading
+  xpl-dropdown-option --> xpl-icon
   xpl-pagination --> xpl-select
   xpl-tabs --> xpl-select
   style xpl-select fill:#f9f,stroke:#333,stroke-width:4px

package/dist/docs/xpl-side-nav/readme.md

@@ -0,0 +1,71 @@
+# xpl-side-nav
+
+Slot-based sidebar for app navigation: scrollable main area and a fixed footer. Compose with [`xpl-side-nav-item`](./xpl-side-nav-item) for rows in the section and footer.
+
+## Slots
+
+| Slot | Description |
+| ---- | ----------- |
+| `section` | Primary navigation. Place `xpl-side-nav-item` elements (or wrappers) inside this slot; layout uses internal section markup. |
+| `nav-footer` | Footer actions (e.g. Help, Logout). Same item component; typically smaller label styling via CSS. |
+
+## Usage
+
+Use the **`label`** prop for a unique accessible name on the `<nav>` when multiple landmarks exist on the page (see **Multi-Navigation Layouts** below).
+
+```html
+<xpl-side-nav label="Main navigation">
+  <div slot="section">
+    <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
+    <xpl-side-nav-item has-children label="Settings" expanded>
+      <xpl-side-nav-item label="Profile"></xpl-side-nav-item>
+    </xpl-side-nav-item>
+  </div>
+  <div slot="nav-footer">
+    <xpl-side-nav-item label="Help" icon="headset"></xpl-side-nav-item>
+  </div>
+</xpl-side-nav>
+```
+
+**Link rows:** use `xpl-side-nav-item` with `link` and an anchor in the default slot — see [xpl-side-nav-item](./xpl-side-nav-item) **Link mode**.
+
+### Multi-Navigation Layouts (Accessibility)
+
+When multiple navigation landmarks exist on a page (e.g., side nav, top nav, breadcrumbs), use the `label` prop to provide a unique accessible name for each `<nav>` element. This helps screen reader users distinguish between them.
+
+```html
+<!-- Main side navigation -->
+<xpl-side-nav label="Main navigation">
+  ...
+</xpl-side-nav>
+
+<!-- Top navigation (different component) -->
+<xpl-top-navigation label="User menu">
+  ...
+</xpl-top-navigation>
+
+<!-- Breadcrumbs (different component) -->
+<xpl-breadcrumbs label="Breadcrumb">
+  ...
+</xpl-breadcrumbs>
+```
+
+**WCAG Note:** When a page has multiple `<nav>` landmarks, each should have a unique accessible name via `aria-label`.
+
+## Related components
+
+- [xpl-side-nav-item](../xpl-side-nav-item) — Navigation rows (leaf, expandable, or link) for section and footer.
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property | Attribute | Description                                                                                                                                                                                                                                 | Type     | Default     |
+| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- |
+| `label`  | `label`   | Accessible label for the navigation landmark. Maps to `aria-label` on the `<nav>` element. Recommended when multiple navigation landmarks exist on a page (e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them. | `string` | `undefined` |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*