@xplortech/apollo-core 2.6.0 → 2.7.1

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

@@ -7,17 +7,18 @@ Checkboxes allow users to make selections or choices. Checkboxes can be multi-se
 
 ## Properties
 
-| Property        | Attribute       | Description                                                                         | Type      | Default     |
-| --------------- | --------------- | ----------------------------------------------------------------------------------- | --------- | ----------- |
-| `checked`       | `checked`       | Whether the input is checked                                                        | `boolean` | `undefined` |
-| `dataId`        | `data-id`       | A custom data attribute for the checkbox                                            | `string`  | `undefined` |
-| `description`   | `description`   | Description text for the field                                                      | `string`  | `undefined` |
-| `disabled`      | `disabled`      | Whether the input is disabled                                                       | `boolean` | `undefined` |
-| `indeterminate` | `indeterminate` | A visual state for when the input has not been interacted with                      | `boolean` | `undefined` |
-| `name`          | `name`          | The name attribute for the html input. (submitted in form as name/value pair)       | `string`  | `undefined` |
-| `required`      | `required`      | Whether the input is required                                                       | `boolean` | `undefined` |
-| `styled`        | `styled`        | Whether the input is contained in a box with a border and a background              | `boolean` | `undefined` |
-| `value`         | `value`         | The value attribute for the checkbox input. (submittted in form as name/value pair) | `string`  | `undefined` |
+| Property        | Attribute       | Description                                                                                                                                                                                                                                                                          | Type      | Default     |
+| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------- |
+| `ariaLabel`     | `aria-label`    | Accessible name for the native checkbox input (sets `aria-label` on the `input`). Use when there is no visible label text in the default slot. Defaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source. | `string`  | `''`        |
+| `checked`       | `checked`       | Whether the input is checked                                                                                                                                                                                                                                                         | `boolean` | `undefined` |
+| `dataId`        | `data-id`       | A custom data attribute for the checkbox                                                                                                                                                                                                                                             | `string`  | `undefined` |
+| `description`   | `description`   | Description text for the field                                                                                                                                                                                                                                                       | `string`  | `undefined` |
+| `disabled`      | `disabled`      | Whether the input is disabled                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
+| `indeterminate` | `indeterminate` | A visual state for when the input has not been interacted with                                                                                                                                                                                                                       | `boolean` | `undefined` |
+| `name`          | `name`          | The name attribute for the html input. (submitted in form as name/value pair)                                                                                                                                                                                                        | `string`  | `undefined` |
+| `required`      | `required`      | Whether the input is required                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
+| `styled`        | `styled`        | Whether the input is contained in a box with a border and a background                                                                                                                                                                                                               | `boolean` | `undefined` |
+| `value`         | `value`         | The value attribute for the checkbox input. (submittted in form as name/value pair)                                                                                                                                                                                                  | `string`  | `undefined` |
 
 
 ## Events

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

@@ -1,7 +1,7 @@
-# xpl-divider
-
-Allows for easy separation and titling of sections within forms or other content.
-
+# xpl-divider
+
+Allows for easy separation and titling of sections within forms or other content.
+
 <!-- Auto Generated Below -->
 
 
@@ -16,11 +16,13 @@ Allows for easy separation and titling of sections within forms or other content
 
 ### Used by
 
+ - [xpl-list-item](../xpl-list/xpl-list-item)
  - [xpl-slideout](../xpl-slideout)
 
 ### Graph
 ```mermaid
 graph TD;
+  xpl-list-item --> xpl-divider
   xpl-slideout --> xpl-divider
   style xpl-divider fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -3,24 +3,26 @@
 A Dropdown is a menu with a list of actions a user can take. Use a dropdown when you want to present a list of actions in a limited space. Dropdowns are single-select ***actions***, can be presented in groups, and can be triggered by other elements such as a button, icon, text etc. 
 A selection within a dropdown does not change the parent trigger.
 
-***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://xplor-apollo.herokuapp.com/?path=/story/components-select--select).***
+***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://apollo.xplordocs.com/?path=/story/components-select--select).***
 
 <!-- Auto Generated Below -->
 
 
 ## 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: Dropdown; }) => 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`           |
+| `flipFallbackPlacements` | --                  | When `anchorToTrigger` is true, additional placements to try when the default `placement` does not fit (passed to Floating UI `flip`). | `Placement[]`                                                                                                                                                        | `undefined`      |
+| `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`      |
+| `placement`              | `placement`         | Floating UI placement when `anchorToTrigger` is true (e.g. `bottom-start`, `top-start`).                                               | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'bottom-start'` |
+| `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

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

@@ -43,18 +43,24 @@ The `icon` property accepts any icon name as a string. See the links above for t
  - [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-search](../xpl-input/xpl-input-search)
  - [xpl-input-time](../xpl-input/xpl-input-time)
  - [xpl-large-card](../xpl-large-card)
- - [xpl-list](../xpl-list)
+ - [xpl-list-item](../xpl-list/xpl-list-item)
  - [xpl-modal](../xpl-modal)
  - [xpl-pagination](../xpl-pagination)
  - [xpl-progress-bar](../xpl-progress-bar)
+ - [xpl-progress-indicator](../xpl-progress-indicator)
  - [xpl-select](../xpl-select)
  - [xpl-side-nav-item](../xpl-side-nav/xpl-side-nav-item)
  - [xpl-slideout](../xpl-slideout)
+ - [xpl-spotlight](../xpl-spotlight)
  - [xpl-table](../xpl-table)
  - [xpl-table-header-cell](../xpl-table-header-cell)
+ - [xpl-tag](../xpl-tag)
  - [xpl-toast](../xpl-toast)
+ - [xpl-top-nav](../xpl-top-nav)
+ - [xpl-top-nav-item](../xpl-top-nav/xpl-top-nav-item)
  - [xpl-utility-bar](../xpl-utility-bar)
 
 ### Graph
@@ -71,18 +77,24 @@ graph TD;
   xpl-input-date --> xpl-icon
   xpl-input-file --> xpl-icon
   xpl-input-phone --> xpl-icon
+  xpl-input-search --> xpl-icon
   xpl-input-time --> xpl-icon
   xpl-large-card --> xpl-icon
-  xpl-list --> xpl-icon
+  xpl-list-item --> xpl-icon
   xpl-modal --> xpl-icon
   xpl-pagination --> xpl-icon
   xpl-progress-bar --> xpl-icon
+  xpl-progress-indicator --> xpl-icon
   xpl-select --> xpl-icon
   xpl-side-nav-item --> xpl-icon
   xpl-slideout --> xpl-icon
+  xpl-spotlight --> xpl-icon
   xpl-table --> xpl-icon
   xpl-table-header-cell --> xpl-icon
+  xpl-tag --> xpl-icon
   xpl-toast --> xpl-icon
+  xpl-top-nav --> xpl-icon
+  xpl-top-nav-item --> xpl-icon
   xpl-utility-bar --> xpl-icon
   style xpl-icon fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -1,58 +1,80 @@
 # 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.
+A flexible form input that supports multiple `type` values: `text`, `number`, `password`, `date`, `time`, `file`, `color`, `phone`, and `search`. Each type delegates to a dedicated sub-component (`xpl-input-date`, `xpl-input-time`, `xpl-input-phone`, `xpl-input-search`, 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.
 
+### Delegated types (`search`, `phone`, `date`, `time`, …)
+
+`valueChange`, `inputEvent`, `focusEvent`, and `blurEvent` are emitted by the inner component and **bubble** to `<xpl-input>`. For **`type="search"`**, **`focusEvent`** and **`blurEvent`** are **re-emitted from `<xpl-input>`** (parent uses **`onFocusEvent`** / **`onBlurEvent`** on **`<xpl-input-search>`** with **`stopPropagation`**) so **`event.target`** matches **`type="text"`**. For **`valueChange`** and **`inputEvent`** on search, events still **bubble** from **`xpl-input-search`** without parent re-emission; **`event.target`** may be the inner host—prefer **`event.detail`** (the string) or **`event.currentTarget`** when you attach the listener on **`<xpl-input>`**. Other delegated types follow the same **`event.detail`** / **`event.currentTarget`** guidance.
+
+For **`type="search"`** commit: **`<xpl-input-search>`** defines a Stencil **`@Event() search`** (trimmed query in **`detail`**). **`<xpl-input>`** listens with **`onSearch`** on the inner tag, **`stopPropagation`s**, then **`this.search.emit(detail)`** so the canonical **`search`** **`@Event`** stays on **`<xpl-input>`** and listeners are not doubled. **`setFocus()`** on **`<xpl-input>`** uses a **`ref`** to the inner component to delegate focus.
+
 <!-- 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'`   |
-| `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` |
+| 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`     |
+| `ariaLabel`           | `aria-label`             | Accessible name for search inputs when there is no visible `label` (after trim). Ignored for naming when a visible label is shown. Defaults to `''`; whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed when there is no visible label.  Applies to search inputs (`type="search"`). | `string`                                                                                           | `''`        |
+| `autocomplete`        | `autocomplete`           | Hint for form autofill feature  Applies to text, password, number, and search inputs.                                                                                                                                                                                                                                                     | `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, date, and search 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, date, and search inputs.                                                                                                                                                                                                                                                | `boolean`                                                                                          | `undefined` |
+| `required`            | `required`               | Whether the input is required  Applies to all input types.                                                                                                                                                                                                                                                                                | `boolean`                                                                                          | `undefined` |
+| `shape`               | `shape`                  | Shell corner radius for search inputs: `rounded` (pill) or `box` (rounded rectangle).  Applies to search inputs (`type="search"`).                                                                                                                                                                                                        | `"box" \| "rounded"`                                                                               | `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" \| "search" \| "text" \| "time"` | `'text'`    |
+| `value`               | `value`                  | Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, date, and search inputs.                                                                                                                                                                                                       | `string`                                                                                           | `undefined` |
 
 
 ## Events
 
-| Event         | Description                                                                        | Type                      |
-| ------------- | ---------------------------------------------------------------------------------- | ------------------------- |
-| `blurEvent`   | The event handler for the blur event                                               | `CustomEvent<FocusEvent>` |
-| `focusEvent`  | The event handler for the focus event                                              | `CustomEvent<FocusEvent>` |
-| `inputEvent`  | Event that emits the current value of the input  Applies to text like inputs only. | `CustomEvent<string>`     |
-| `valueChange` | Event that emits the current value of the input                                    | `CustomEvent<string>`     |
+| Event         | Description                                                                                                                                                                                                  | Type                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
+| `blurEvent`   | The event handler for the blur event                                                                                                                                                                         | `CustomEvent<FocusEvent>` |
+| `focusEvent`  | The event handler for the focus event                                                                                                                                                                        | `CustomEvent<FocusEvent>` |
+| `inputEvent`  | Event that emits the current value of the input  Applies to text-like inputs and search inputs.                                                                                                              | `CustomEvent<string>`     |
+| `search`      | Emitted when the user commits a search (Enter with no enclosing form owner, or submit of the internal search form). `event.detail` is the trimmed query string.  Applies to search inputs (`type="search"`). | `CustomEvent<string>`     |
+| `valueChange` | Event that emits the current value of the input (including search fields).                                                                                                                                   | `CustomEvent<string>`     |
+
+
+## Methods
+
+### `setFocus() => Promise<void>`
+
+Moves keyboard focus to the native control (text field, textarea, or search inner input).
+
+#### Returns
+
+Type: `Promise<void>`
+
+
 
 
 ## Dependencies
@@ -70,6 +92,7 @@ For `type="phone"`, the value is always emitted in **E.164** format (e.g. `+1415
 - [xpl-input-date](xpl-input-date)
 - [xpl-input-time](xpl-input-time)
 - [xpl-input-phone](xpl-input-phone)
+- [xpl-input-search](xpl-input-search)
 - [xpl-icon](../xpl-icon)
 
 ### Graph
@@ -80,6 +103,7 @@ graph TD;
   xpl-input --> xpl-input-date
   xpl-input --> xpl-input-time
   xpl-input --> xpl-input-phone
+  xpl-input --> xpl-input-search
   xpl-input --> xpl-icon
   xpl-input-file --> xpl-icon
   xpl-input-color --> xpl-input
@@ -92,6 +116,7 @@ graph TD;
   xpl-dropdown-group --> xpl-dropdown-heading
   xpl-dropdown-option --> xpl-icon
   xpl-input-phone --> xpl-input
+  xpl-input-search --> xpl-icon
   style xpl-input fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -57,6 +57,7 @@ graph TD;
   xpl-input-phone --> xpl-icon
   xpl-input-phone --> xpl-dropdown
   xpl-input-phone --> xpl-input
+  xpl-input-search --> xpl-icon
   style xpl-input-color fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -159,6 +159,7 @@ graph TD;
   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
 ```
 

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/)*