@xplortech/apollo-core 2.5.0 → 2.6.0

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

@@ -1,38 +1,175 @@
 # xpl-button
 
-Buttons allow users to take an action.  Three sizes and three sentiments are available with leading and trailing icons. Hide an icon and the label for an icon-only button.
+Buttons allow users to take an action with clear visual hierarchy (variant), semantic meaning (sentiment), and size.
+
+## Usage
+
+> [!IMPORTANT]
+> Older props such as `state` still work, but we recommend using the sentiment described below.
+
+
+### Basic button
+
+Pass button text via the default slot (same as native `<button>`):
+
+```html
+<xpl-button>Primary action</xpl-button>
+```
+
+### Variant and sentiment
+
+Use `variant` for style (primary, secondary, tertiary) and `sentiment` for intent (default, positive, negative):
+
+```html
+<xpl-button variant="secondary">Secondary</xpl-button>
+<xpl-button variant="tertiary" sentiment="positive">Positive action</xpl-button>
+<xpl-button sentiment="negative">Destructive</xpl-button>
+```
+
+### Size
+
+Use **`size`** for button size: `default`, `sm` (small), or `xs` (extra small):
+
+```html
+<xpl-button size="sm">Small</xpl-button>
+<xpl-button size="xs">Extra small</xpl-button>
+```
+
+### Icon from Apollo icon library
+
+Use `icon` with a name from the xpl-icon library; use `icon-position` to place the icon at start or end:
+
+```html
+<xpl-button icon="download" icon-position="end">
+  Download
+</xpl-button>
+```
+
+### Icon-only button
+
+Use `icon-only` when the button shows only an icon (no label). Always set `icon` and use a descriptive `aria-label` on the host or inner button for accessibility:
+
+```html
+<xpl-button icon-only icon="x" aria-label="Close"></xpl-button>
+```
+
+### Loading state
+
+When `is-loading` is true, the button shows a spinner, hides the label and icon, stays the same size, and is non-interactive:
+
+```html
+<xpl-button is-loading>Submitting</xpl-button>
+```
+
+### Form submission
+
+The component renders a native `<button>`. Use `type` (`submit`, `reset`, or `button`), `name`, `value`, and `form` for form behaviour:
+
+```html
+<form id="my-form">
+  <xpl-button type="submit" name="action" value="save">Save</xpl-button>
+</form>
+```
+
+### Disabled
+
+Use the `disabled` prop to disable the button (same as native `disabled`):
+
+```html
+<xpl-button disabled>Disabled</xpl-button>
+```
+
+## DOM classes
+
+The host element includes BEM-style classes, including:
+
+- **Size:** `xpl-button--default` | `xpl-button--sm` | `xpl-button--xs`
+- **Variant:** `xpl-button--primary` | `xpl-button--secondary` | `xpl-button--tertiary` (and `xpl-button--subtle` while that value is still supported)
+- **Sentiment:** `xpl-button--neutral` | `xpl-button--positive` | `xpl-button--negative` when using `sentiment`
+- **Deprecated `state`:** if set, legacy classes `xpl-button--neutral` | `xpl-button--warning` | `xpl-button--success` are applied instead of the sentiment-based classes above (see migration)
+
+Prefer targeting **`sentiment`** + **`variant`** + **`size`** in new code; avoid relying on deprecated `state` class names for new selectors.
+
+## Migration Notes:
+
+The class **`xpl-button--default`** on the host continues to mean **size** (`size="default"`), not sentiment.
+
+### Deprecated `state` prop
+
+The **`state`** prop (`neutral` | `warning` | `success`) is deprecated. Use **`sentiment`** instead:
+
+| Old `state`   | New `sentiment` |
+| ------------- | ----------------- |
+| `neutral`     | `neutral` (default) |
+| `warning`     | `negative`        |
+| `success`     | `positive`        |
+
+**Backward compatibility:** if **`state`** is set, it controls the sentiment segment of the host class list (`xpl-button--neutral`, `xpl-button--warning`, `xpl-button--success`) so existing styles or tests that key off those class names can keep working. New work should use **`sentiment`** only (`neutral` | `negative` | `positive`).
+
+### Deprecated `variant="subtle"` → `tertiary`
+
+**`variant="subtle"`** is deprecated and retained only for backward compatibility, applying the **`xpl-button--subtle`** class. Use **`variant="tertiary"`** instead, which applies **`xpl-button--tertiary`**.
+
+### Other API notes
+
+- **`isLoading` / `is-loading`:** loading UI without forcing the disabled (gray) visual treatment.
+- **`icon`**, **`icon-position`**, **`icon-only`:** use Apollo icon names; no inline SVGs required.
+- **`data-*` and `aria-*` on the host:** mirrored onto the inner `<button>` after render for accessibility and testing tools.
+
+## Guidelines
+
+- **Pass button content via the default slot:** `<xpl-button>Save</xpl-button>`. Slots support rich content (formatted text, inline icons, etc.).
+- Use **`iconOnly`** for icon-only buttons and provide an **`aria-label`** (or ensure the inner button has an accessible name).
+- Use **`icon`** for icon names from the xpl-icon library; use **`icon-position`** to place the icon at start or end of the slot content.
+
+## Accessibility
+
+- The component renders a native `<button>`, so it is focusable and keyboard-activable by default.
+- When **`is-loading`** is true, the inner button has `aria-busy="true"` and the loading spinner is marked **`aria-hidden="true"`** so the label remains the accessible name.
+- For **icon-only** buttons, provide an accessible name via **`aria-label`** on the host (e.g. `<xpl-button icon-only icon="x" aria-label="Close">`) so screen readers announce the action.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property    | Attribute    | Description                                       | Type                                   | Default     |
-| ----------- | ------------ | ------------------------------------------------- | -------------------------------------- | ----------- |
-| `disabled`  | `disabled`   | whether button should be disabled                 | `boolean`                              | `undefined` |
-| `form`      | `form`       |                                                   | `string`                               | `undefined` |
-| `fullWidth` | `full-width` | whether button should render with full width      | `boolean`                              | `undefined` |
-| `iconOnly`  | `icon-only`  | whether button should render icon only            | `boolean`                              | `undefined` |
-| `link`      | `link`       | whether button should yield a slot for a link tag | `boolean`                              | `undefined` |
-| `name`      | `name`       |                                                   | `string`                               | `undefined` |
-| `size`      | `size`       |                                                   | `"default" \| "sm" \| "xs"`            | `'default'` |
-| `state`     | `state`      |                                                   | `"neutral" \| "success" \| "warning"`  | `'neutral'` |
-| `type`      | `type`       |                                                   | `"button" \| "reset" \| "submit"`      | `undefined` |
-| `value`     | `value`      |                                                   | `string`                               | `undefined` |
-| `variant`   | `variant`    |                                                   | `"primary" \| "secondary" \| "subtle"` | `'primary'` |
+| Property       | Attribute       | Description                                                                                                                                        | Type                                                 | Default     |
+| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------- |
+| `disabled`     | `disabled`      | Whether button should be disabled                                                                                                                  | `boolean`                                            | `false`     |
+| `form`         | `form`          | An optional form attribute for the button if type is submit                                                                                        | `string`                                             | `undefined` |
+| `fullWidth`    | `full-width`    | Whether the button should be of full width as per parent container.                                                                                | `boolean`                                            | `false`     |
+| `icon`         | `icon`          | Icon to render - icon name as string (from xpl-icon library).                                                                                      | `string`                                             | `''`        |
+| `iconOnly`     | `icon-only`     | When true, the button renders in icon-only circular style. Use for icon-only buttons.                                                              | `boolean`                                            | `false`     |
+| `iconPosition` | `icon-position` | Icon position relative to slot content. Ignored if no icon is provided.                                                                            | `"end" \| "start"`                                   | `'start'`   |
+| `isLoading`    | `is-loading`    | When true, shows a loading overlay with spinner over the button. Button is non-interactive.                                                        | `boolean`                                            | `false`     |
+| `link`         | `link`          | whether button should yield a slot for a link tag                                                                                                  | `boolean`                                            | `undefined` |
+| `name`         | `name`          | Name of the button, submitted with form data. Passed through to the native button element.                                                         | `string`                                             | `undefined` |
+| `sentiment`    | `sentiment`     | Sentiment of the button, which applies different color schemes to indicate purpose/intent.                                                         | `"negative" \| "neutral" \| "positive"`              | `'neutral'` |
+| `size`         | `size`          | Button size. Use 'default', 'xs' (extra small), or 'sm' (small).                                                                                   | `"default" \| "sm" \| "xs"`                          | `'default'` |
+| `state`        | `state`         | <span style="color:red">**[DEPRECATED]**</span> : Use `sentiment` with values "neutral", "negative", "positive" instead of `state` .<br/><br/>     | `"neutral" \| "success" \| "warning"`                | `undefined` |
+| `type`         | `type`          | HTML button type attribute.                                                                                                                        | `"button" \| "reset" \| "submit"`                    | `undefined` |
+| `value`        | `value`         | Value of the button, submitted with form data. Passed through to the native button element.                                                        | `string`                                             | `undefined` |
+| `variant`      | `variant`       | Button variant/style. Use "primary", "secondary", "tertiary" for new usage. "subtle" is deprecated but still supported for backward compatibility. | `"primary" \| "secondary" \| "subtle" \| "tertiary"` | `'primary'` |
 
 
 ## Dependencies
 
 ### Used by
 
+ - [xpl-banner](../xpl-banner)
  - [xpl-button-row](../xpl-button-row)
  - [xpl-modal](../xpl-modal)
  - [xpl-slideout](../xpl-slideout)
 
+### Depends on
+
+- [xpl-icon](../xpl-icon)
+
 ### Graph
 ```mermaid
 graph TD;
+  xpl-button --> xpl-icon
+  xpl-banner --> xpl-button
   xpl-button-row --> xpl-button
   xpl-modal --> xpl-button
   xpl-slideout --> xpl-button

package/dist/docs/xpl-button-row/readme.md

@@ -33,6 +33,7 @@
 ```mermaid
 graph TD;
   xpl-button-row --> xpl-button
+  xpl-button --> xpl-icon
   style xpl-button-row fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -1,6 +1,7 @@
 # xpl-calendar
 
-
+Calendars allow users to view and select dates.  Use XPL-Calendar when date picking is needed on a page or in a in a container.
+If a calendar is needed within a form, use [XPL-Datepicker](https://xplor-apollo.herokuapp.com/?path=/story/components-input--datepicker).
 
 <!-- Auto Generated Below -->
 

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

@@ -1,5 +1,7 @@
 # xpl-checkbox
 
+Checkboxes allow users to make selections or choices. Checkboxes can be multi-select, and also act as controls.
+
 <!-- Auto Generated Below -->
 
 

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

@@ -1,5 +1,6 @@
 # xpl-choicelist
 
+A Choice List allows users to make single or multiple selections from a list of choices.  This component is meant to consume the radio and checkbox components, either styled or unstyled, then allow for customizing an option list very quickly.
 <!-- Auto Generated Below -->
 
 

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

@@ -1,8 +1,8 @@
 # xpl-data-card
 
-The `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.
+Data Cards display snippets of information and can be linked to larger data sets. Data Cards give users "at a glance" information about their data.
 
----
+The `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.
 
 <!-- Auto Generated Below -->
 

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

@@ -1,6 +1,6 @@
 # xpl-divider
 
-
+Allows for easy separation and titling of sections within forms or other content.
 
 <!-- Auto Generated Below -->
 

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

@@ -10,17 +10,17 @@ A selection within a dropdown does not change the parent trigger.
 
 ## Properties
 
-| Property          | Attribute           | Description                                                                         | Type                                                           | Default     |
-| ----------------- | ------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------- |
-| `anchorToTrigger` | `anchor-to-trigger` | whether to anchor the dropdown to the trigger element, requires triggerId to be set | `boolean`                                                      | `false`     |
-| `closeOnSelect`   | `close-on-select`   | options that are listed                                                             | `boolean`                                                      | `true`      |
-| `isOpen`          | `open`              | text to display as heading                                                          | `boolean`                                                      | `false`     |
-| `mode`            | `mode`              | constant representing number of options that can be selected                        | `"multi" \| "single"`                                          | `'single'`  |
-| `options`         | --                  | options that are listed                                                             | `Partial<DropdownOption & DropdownOptionGroup>[]`              | `undefined` |
-| `selectOnFocus`   | `select-on-focus`   | whether selection should be made when focusing on interactive element               | `boolean`                                                      | `false`     |
-| `selectedValues`  | `selected-values`   | The currently selected value(s) in the dropdown.                                    | `string \| string[]`                                           | `undefined` |
-| `triggerId`       | `trigger-id`        | the id for the element that triggers the open state                                 | `string`                                                       | `undefined` |
-| `update`          | --                  | call back function invoked when a selection is made                                 | `(e: any, { component }: { component: XplDropdown; }) => void` | `undefined` |
+| Property          | Attribute           | Description                                                                         | Type                                                        | Default     |
+| ----------------- | ------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------- |
+| `anchorToTrigger` | `anchor-to-trigger` | whether to anchor the dropdown to the trigger element, requires triggerId to be set | `boolean`                                                   | `false`     |
+| `closeOnSelect`   | `close-on-select`   | options that are listed                                                             | `boolean`                                                   | `true`      |
+| `isOpen`          | `open`              | text to display as heading                                                          | `boolean`                                                   | `false`     |
+| `mode`            | `mode`              | constant representing number of options that can be selected                        | `"multi" \| "single"`                                       | `'single'`  |
+| `options`         | --                  | options that are listed                                                             | `Partial<DropdownOption & DropdownOptionGroup>[]`           | `undefined` |
+| `selectOnFocus`   | `select-on-focus`   | whether selection should be made when focusing on interactive element               | `boolean`                                                   | `false`     |
+| `selectedValues`  | `selected-values`   | The currently selected value(s) in the dropdown.                                    | `string \| string[]`                                        | `undefined` |
+| `triggerId`       | `trigger-id`        | the id for the element that triggers the open state                                 | `string`                                                    | `undefined` |
+| `update`          | --                  | call back function invoked when a selection is made                                 | `(e: any, { component }: { component: Dropdown; }) => void` | `undefined` |
 
 
 ## Events
@@ -54,6 +54,7 @@ Type: `Promise<void>`
 
 ### Used by
 
+ - [xpl-input-phone](../xpl-input/xpl-input-phone)
  - [xpl-input-time](../xpl-input/xpl-input-time)
  - [xpl-select](../xpl-select)
 
@@ -70,6 +71,8 @@ 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-input-phone --> xpl-dropdown
   xpl-input-time --> xpl-dropdown
   xpl-select --> xpl-dropdown
   style xpl-dropdown fill:#f9f,stroke:#333,stroke-width:4px

package/dist/docs/xpl-dropdown/xpl-dropdown-group/readme.md

@@ -30,6 +30,7 @@
 ```mermaid
 graph TD;
   xpl-dropdown-group --> xpl-dropdown-group
+  xpl-dropdown-option --> xpl-icon
   xpl-dropdown --> xpl-dropdown-group
   style xpl-dropdown-group fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/docs/xpl-dropdown/xpl-dropdown-option/readme.md

@@ -9,6 +9,7 @@
 
 | Property     | Attribute  | Description                                                                               | Type      | Default     |
 | ------------ | ---------- | ----------------------------------------------------------------------------------------- | --------- | ----------- |
+| `icon`       | `icon`     | optional icon name to display before the label (uses xpl-icon)                            | `string`  | `undefined` |
 | `isDisabled` | `disabled` | whether option is disabled                                                                | `boolean` | `undefined` |
 | `isSelected` | `selected` | whether option is selected                                                                | `boolean` | `undefined` |
 | `label`      | `label`    | text to display for option                                                                | `string`  | `undefined` |
@@ -23,9 +24,14 @@
  - [xpl-dropdown](..)
  - [xpl-dropdown-group](../xpl-dropdown-group)
 
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+
 ### Graph
 ```mermaid
 graph TD;
+  xpl-dropdown-option --> xpl-icon
   xpl-dropdown --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-option
   style xpl-dropdown-option fill:#f9f,stroke:#333,stroke-width:4px

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

@@ -33,18 +33,24 @@ The `icon` property accepts any icon name as a string. See the links above for t
 ### Used by
 
  - [xpl-accordion](../xpl-accordion)
+ - [xpl-banner](../xpl-banner)
+ - [xpl-button](../xpl-button)
  - [xpl-data-card](../xpl-data-card)
+ - [xpl-dropdown-option](../xpl-dropdown/xpl-dropdown-option)
  - [xpl-header-accordion](../xpl-header-accordion)
  - [xpl-input](../xpl-input)
  - [xpl-input-color](../xpl-input/xpl-input-color)
  - [xpl-input-date](../xpl-input/xpl-input-date)
  - [xpl-input-file](../xpl-input/xpl-input-file)
+ - [xpl-input-phone](../xpl-input/xpl-input-phone)
  - [xpl-input-time](../xpl-input/xpl-input-time)
  - [xpl-large-card](../xpl-large-card)
  - [xpl-list](../xpl-list)
  - [xpl-modal](../xpl-modal)
  - [xpl-pagination](../xpl-pagination)
+ - [xpl-progress-bar](../xpl-progress-bar)
  - [xpl-select](../xpl-select)
+ - [xpl-side-nav-item](../xpl-side-nav/xpl-side-nav-item)
  - [xpl-slideout](../xpl-slideout)
  - [xpl-table](../xpl-table)
  - [xpl-table-header-cell](../xpl-table-header-cell)
@@ -55,18 +61,24 @@ The `icon` property accepts any icon name as a string. See the links above for t
 ```mermaid
 graph TD;
   xpl-accordion --> xpl-icon
+  xpl-banner --> xpl-icon
+  xpl-button --> xpl-icon
   xpl-data-card --> xpl-icon
+  xpl-dropdown-option --> xpl-icon
   xpl-header-accordion --> xpl-icon
   xpl-input --> xpl-icon
   xpl-input-color --> xpl-icon
   xpl-input-date --> xpl-icon
   xpl-input-file --> xpl-icon
+  xpl-input-phone --> xpl-icon
   xpl-input-time --> xpl-icon
   xpl-large-card --> xpl-icon
   xpl-list --> xpl-icon
   xpl-modal --> xpl-icon
   xpl-pagination --> xpl-icon
+  xpl-progress-bar --> xpl-icon
   xpl-select --> xpl-icon
+  xpl-side-nav-item --> xpl-icon
   xpl-slideout --> xpl-icon
   xpl-table --> xpl-icon
   xpl-table-header-cell --> xpl-icon

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

@@ -1,43 +1,48 @@
 # xpl-input
 
+A flexible form input that supports multiple `type` values: `text`, `number`, `password`, `date`, `time`, `file`, `color`, and `phone`. Each type delegates to a dedicated sub-component (`xpl-input-date`, `xpl-input-time`, `xpl-input-phone`, etc.) while sharing a common label, description, and error-message wrapper.
 
+For `type="phone"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property              | Attribute                | Description                                                                                                                                                                                                                                          | Type                                                                        | Default     |
-| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------- |
-| `_id`                 | `_id`                    | Because `id` is a reserved HTMLElement attribute, we prefix it with an underscore here so that it doesn't get automatically applied to the outer container.  Applies to all input types.                                                             | `string`                                                                    | `undefined` |
-| `accept`              | `accept`                 | The accepted file types for the file input. Corresponds to the `accept` attribute on the input element. Example: 'image/*' for all image types, '.pdf' for PDF files, etc.  Applies to file inputs.                                                  | `string`                                                                    | `''`        |
-| `allowCustomOption`   | `allow-custom-option`    | For time inputs, whether to allow custom option in the input even if not available in the dropdown. Example: A step of 30 minutes will allow 15:03, 15:37, etc.  Applies to time inputs.                                                             | `boolean`                                                                   | `false`     |
-| `autocomplete`        | `autocomplete`           | Hint for form autofill feature  Applies to text, password, number.                                                                                                                                                                                   | `string`                                                                    | `undefined` |
-| `dateFormat`          | `date-format`            | The date format to use for the datepicker input. This is used by flatpickr to format the date. Default is 'Y-m-d' (e.g., 2023-10-01).  See https://flatpickr.js.org/formatting/ for more details.  Applies to date inputs.                           | `string`                                                                    | `'Y-m-d'`   |
-| `description`         | `description`            | Optional text that appears below the input label.  Applies to all input types.                                                                                                                                                                       | `string`                                                                    | `undefined` |
-| `disabled`            | `disabled`               | Whether the field is disabled  Applies to all input types.                                                                                                                                                                                           | `boolean`                                                                   | `undefined` |
-| `error`               | `error`                  | If an empty string (attribute present with no value), will display visually as an error. If a string is included, will display visually as an error and include the value as an error message.  Applies to all input types.                          | `string`                                                                    | `undefined` |
-| `hideAcceptText`      | `hide-accept-text`       | Hides the "Accept" text that indicates the accepted file types This is useful for cases where you want to hide the "Accept" text.  Applies to file inputs.                                                                                           | `boolean`                                                                   | `false`     |
-| `hideEyeDropper`      | `hide-eye-dropper`       | Hide eye dropper  Applies to color inputs.                                                                                                                                                                                                           | `boolean`                                                                   | `undefined` |
-| `hideFileNames`       | `hide-file-names`        | Hides the file names in the file upload component This is useful for cases where you want to hide the file names after selection.  Applies to file inputs.                                                                                           | `boolean`                                                                   | `false`     |
-| `hideTriggerOnSelect` | `hide-trigger-on-select` | Hides the trigger element when a file is selected. This is useful for cases where you want to hide the trigger after a file is selected.  Applies to file inputs.                                                                                    | `boolean`                                                                   | `false`     |
-| `label`               | `label`                  | Label text for the field  Applies to all input types.                                                                                                                                                                                                | `string`                                                                    | `undefined` |
-| `max`                 | `max`                    | Maximum value for the input.  Applies to number, time, and date inputs.  If the input is a time input, the value must be in 24 hour format, ex: 18:25 for 6:25 PM                                                                                    | `number \| string`                                                          | `undefined` |
-| `maxCharacterCount`   | `max-character-count`    | For multiline inputs, a max. character count will display along with the current character count, and will automatically render as an error if the character count exceeds the max.  This is only applicable if `multiline` is `true`.               | `number`                                                                    | `undefined` |
-| `min`                 | `min`                    | The minimum value for the input.  Applies to number, time, and date inputs.  If the input is a time input, the value must be in 24 hour format, ex: 05:25 for 5:25 AM                                                                                | `number \| string`                                                          | `undefined` |
-| `mode`                | `mode`                   | For datepicker inputs, whether to allow only a single date or a range of dates. (Multiple non-consecutive dates planned to be supported in the future.)  Applies to date inputs.                                                                     | `"range" \| "single"`                                                       | `'single'`  |
-| `multiline`           | `multiline`              | Whether to render as a singleline text input or as a multiline textarea. (If `true`, `pre` and `post` values will be ignored, if present.)  Applies to text inputs.                                                                                  | `boolean`                                                                   | `false`     |
-| `multiple`            | `multiple`               | Whether the user can select multiple files at once. Corresponds to the `multiple` attribute on the input element.  Applies to file inputs.                                                                                                           | `boolean`                                                                   | `false`     |
-| `name`                | `name`                   | Most inputs are used in forms, and should have a `name` associated with the input for handling form data.  Applies to all input types.                                                                                                               | `string`                                                                    | `undefined` |
-| `placeholder`         | `placeholder`            | Placeholder text that appears when the field has no value  Applies to text, password, number, and date inputs.                                                                                                                                       | `string`                                                                    | `undefined` |
-| `post`                | `post`                   | A string (recommended max 3 characters) that gets shown visually to the left of (before) the input.  Applies to text, password, number, and date inputs. Note: This will be ignored if `multiline` is `true`.                                        | `string`                                                                    | `undefined` |
-| `pre`                 | `pre`                    | A string (recommended max 8 characters) that gets shown visually to the right of (after) the input.  Applies to text, password, number, and date inputs. Note: This will be ignored if `multiline` is `true`.                                        | `string`                                                                    | `undefined` |
-| `readonly`            | `readonly`               | Whether the input is editable  Applies to text, password, number, and date inputs.                                                                                                                                                                   | `boolean`                                                                   | `undefined` |
-| `required`            | `required`               | Whether the input is required  Applies to all input types.                                                                                                                                                                                           | `boolean`                                                                   | `undefined` |
-| `step`                | `step`                   | The granularity that the value in a `number` input must adhere to when incrementing or decrementing. The default stepping value for number inputs is 1  Applies to number and time inputs.                                                           | `number`                                                                    | `undefined` |
-| `timeFormat`          | `time-format`            | The time format to display for the input.  Applies to time inputs.  If 12h is selected, the value will be displayed in 12 hour format, ex: 05:25 PM for 17:25 If 24h is selected, the value will be displayed in 24 hour format, ex: 17:25 for 17:25 | `"12h" \| "24h"`                                                            | `'24h'`     |
-| `type`                | `type`                   | The type of form control                                                                                                                                                                                                                             | `"color" \| "date" \| "file" \| "number" \| "password" \| "text" \| "time"` | `'text'`    |
-| `value`               | `value`                  | Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, and date inputs.                                                                                                                          | `string`                                                                    | `undefined` |
+| Property              | Attribute                | Description                                                                                                                                                                                                                                          | Type                                                                                   | Default     |
+| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------- |
+| `_id`                 | `_id`                    | Because `id` is a reserved HTMLElement attribute, we prefix it with an underscore here so that it doesn't get automatically applied to the outer container.  Applies to all input types.                                                             | `string`                                                                               | `undefined` |
+| `accept`              | `accept`                 | The accepted file types for the file input. Corresponds to the `accept` attribute on the input element. Example: 'image/*' for all image types, '.pdf' for PDF files, etc.  Applies to file inputs.                                                  | `string`                                                                               | `''`        |
+| `allowCustomOption`   | `allow-custom-option`    | For time inputs, whether to allow custom option in the input even if not available in the dropdown. Example: A step of 30 minutes will allow 15:03, 15:37, etc.  Applies to time inputs.                                                             | `boolean`                                                                              | `false`     |
+| `autocomplete`        | `autocomplete`           | Hint for form autofill feature  Applies to text, password, number.                                                                                                                                                                                   | `string`                                                                               | `undefined` |
+| `dateFormat`          | `date-format`            | The date format to use for the datepicker input. This is used by flatpickr to format the date. Default is 'Y-m-d' (e.g., 2023-10-01).  See https://flatpickr.js.org/formatting/ for more details.  Applies to date inputs.                           | `string`                                                                               | `'Y-m-d'`   |
+| `defaultCountry`      | `default-country`        | Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. "US".  Applies to phone inputs.                                                                                                                                                  | `string`                                                                               | `'US'`      |
+| `description`         | `description`            | Optional text that appears below the input label.  Applies to all input types.                                                                                                                                                                       | `string`                                                                               | `undefined` |
+| `disabled`            | `disabled`               | Whether the field is disabled  Applies to all input types.                                                                                                                                                                                           | `boolean`                                                                              | `undefined` |
+| `error`               | `error`                  | If an empty string (attribute present with no value), will display visually as an error. If a string is included, will display visually as an error and include the value as an error message.  Applies to all input types.                          | `string`                                                                               | `undefined` |
+| `hideAcceptText`      | `hide-accept-text`       | Hides the "Accept" text that indicates the accepted file types This is useful for cases where you want to hide the "Accept" text.  Applies to file inputs.                                                                                           | `boolean`                                                                              | `false`     |
+| `hideEyeDropper`      | `hide-eye-dropper`       | Hide eye dropper  Applies to color inputs.                                                                                                                                                                                                           | `boolean`                                                                              | `undefined` |
+| `hideFileNames`       | `hide-file-names`        | Hides the file names in the file upload component This is useful for cases where you want to hide the file names after selection.  Applies to file inputs.                                                                                           | `boolean`                                                                              | `false`     |
+| `hideTriggerOnSelect` | `hide-trigger-on-select` | Hides the trigger element when a file is selected. This is useful for cases where you want to hide the trigger after a file is selected.  Applies to file inputs.                                                                                    | `boolean`                                                                              | `false`     |
+| `isInternational`     | `is-international`       | Enables international mode with country selector for phone inputs. When false, the phone input is locked to defaultCountry with no country picker.                                                                                                   | `boolean`                                                                              | `true`      |
+| `label`               | `label`                  | Label text for the field  Applies to all input types.                                                                                                                                                                                                | `string`                                                                               | `undefined` |
+| `max`                 | `max`                    | Maximum value for the input.  Applies to number, time, and date inputs.  If the input is a time input, the value must be in 24 hour format, ex: 18:25 for 6:25 PM                                                                                    | `number \| string`                                                                     | `undefined` |
+| `maxCharacterCount`   | `max-character-count`    | For multiline inputs, a max. character count will display along with the current character count, and will automatically render as an error if the character count exceeds the max.  This is only applicable if `multiline` is `true`.               | `number`                                                                               | `undefined` |
+| `min`                 | `min`                    | The minimum value for the input.  Applies to number, time, and date inputs.  If the input is a time input, the value must be in 24 hour format, ex: 05:25 for 5:25 AM                                                                                | `number \| string`                                                                     | `undefined` |
+| `mode`                | `mode`                   | For datepicker inputs, whether to allow only a single date or a range of dates. (Multiple non-consecutive dates planned to be supported in the future.)  Applies to date inputs.                                                                     | `"range" \| "single"`                                                                  | `'single'`  |
+| `multiline`           | `multiline`              | Whether to render as a singleline text input or as a multiline textarea. (If `true`, `pre` and `post` values will be ignored, if present.)  Applies to text inputs.                                                                                  | `boolean`                                                                              | `false`     |
+| `multiple`            | `multiple`               | Whether the user can select multiple files at once. Corresponds to the `multiple` attribute on the input element.  Applies to file inputs.                                                                                                           | `boolean`                                                                              | `false`     |
+| `name`                | `name`                   | Most inputs are used in forms, and should have a `name` associated with the input for handling form data.  Applies to all input types.                                                                                                               | `string`                                                                               | `undefined` |
+| `placeholder`         | `placeholder`            | Placeholder text that appears when the field has no value  Applies to text, password, number, and date inputs.                                                                                                                                       | `string`                                                                               | `undefined` |
+| `post`                | `post`                   | A string (recommended max 3 characters) that gets shown visually to the left of (before) the input.  Applies to text, password, number, and date inputs. Note: This will be ignored if `multiline` is `true`.                                        | `string`                                                                               | `undefined` |
+| `pre`                 | `pre`                    | A string (recommended max 8 characters) that gets shown visually to the right of (after) the input.  Applies to text, password, number, and date inputs. Note: This will be ignored if `multiline` is `true`.                                        | `string`                                                                               | `undefined` |
+| `preferredCountries`  | --                       | Country codes to show at the top of the country list, e.g. ["US", "CA", "GB"].  Applies to phone inputs.                                                                                                                                             | `string[]`                                                                             | `undefined` |
+| `readonly`            | `readonly`               | Whether the input is editable  Applies to text, password, number, and date inputs.                                                                                                                                                                   | `boolean`                                                                              | `undefined` |
+| `required`            | `required`               | Whether the input is required  Applies to all input types.                                                                                                                                                                                           | `boolean`                                                                              | `undefined` |
+| `step`                | `step`                   | The granularity that the value in a `number` input must adhere to when incrementing or decrementing. The default stepping value for number inputs is 1  Applies to number and time inputs.                                                           | `number`                                                                               | `undefined` |
+| `timeFormat`          | `time-format`            | The time format to display for the input.  Applies to time inputs.  If 12h is selected, the value will be displayed in 12 hour format, ex: 05:25 PM for 17:25 If 24h is selected, the value will be displayed in 24 hour format, ex: 17:25 for 17:25 | `"12h" \| "24h"`                                                                       | `'24h'`     |
+| `type`                | `type`                   | The type of form control                                                                                                                                                                                                                             | `"color" \| "date" \| "file" \| "number" \| "password" \| "phone" \| "text" \| "time"` | `'text'`    |
+| `value`               | `value`                  | Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, and date inputs.                                                                                                                          | `string`                                                                               | `undefined` |
 
 
 ## Events
@@ -55,6 +60,7 @@
 ### Used by
 
  - [xpl-input-color](xpl-input-color)
+ - [xpl-input-phone](xpl-input-phone)
  - [xpl-input-time](xpl-input-time)
 
 ### Depends on
@@ -63,6 +69,7 @@
 - [xpl-input-color](xpl-input-color)
 - [xpl-input-date](xpl-input-date)
 - [xpl-input-time](xpl-input-time)
+- [xpl-input-phone](xpl-input-phone)
 - [xpl-icon](../xpl-icon)
 
 ### Graph
@@ -72,6 +79,7 @@ graph TD;
   xpl-input --> xpl-input-color
   xpl-input --> xpl-input-date
   xpl-input --> xpl-input-time
+  xpl-input --> xpl-input-phone
   xpl-input --> xpl-icon
   xpl-input-file --> xpl-icon
   xpl-input-color --> xpl-input
@@ -82,6 +90,8 @@ 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-input-phone --> xpl-input
   style xpl-input fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -53,6 +53,10 @@ 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-input-phone --> xpl-icon
+  xpl-input-phone --> xpl-dropdown
+  xpl-input-phone --> xpl-input
   style xpl-input-color fill:#f9f,stroke:#333,stroke-width:4px
 ```