@getflip/swirl-ai 0.448.0

package/LICENSE.md

@@ -0,0 +1,25 @@
+Copyright (c) 2022-present Flip GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The rights granted above may only be exercised to develop and distribute
+applications that integrate or interoperate with Flip software or services, and
+in the case of external, stand-alone applications that do not embed directly
+inside Flip, the rights granted above may only be exercised to develop and
+distribute applications that are dissimilar and visually distinct from Flip
+products and services, as determined by Flip in its sole discretion.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @getflip/swirl-ai
+
+Swirl Design System artifacts for AI agents: a compact component index,
+per-component docs, and the full custom elements manifest with TypeScript types.
+
+## Artifacts (after `npm run build`)
+
+| Artifact                     | Path                                 | Purpose                                                                                                                                                                                         |
+| ---------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Custom elements manifest** | `dist/custom-elements.manifest.json` | Full CEM schema (tags, props, events, slots, descriptions). Use when you need complete API detail.                                                                                              |
+| **Agent components index**   | `dist/agent/components-index.json`   | Compact, agent-oriented list: tag, summary, required/optional props, events, slots, methods, a11y hints, related components. Prefer this for “which component?” and quick lookup.               |
+| **Per-component docs**       | `dist/agent/components/<tag>.md`     | One markdown file per component: purpose, required/optional props, slots, events, methods, composition, accessibility, minimal example, common mistakes. Use for retrieval and code generation. |
+| **TypeScript types**         | `dist/types/`                        | Declarations for all components (props, events, methods). Use for type-checking and IDE support.                                                                                                |
+
+## Recommended retrieval order for agents
+
+1. **Discover** – Load `dist/agent/components-index.json` to choose components
+   by summary and related components.
+2. **Detail** – For each chosen tag, load `dist/agent/components/<tag>.md` for
+   usage, composition, and examples.
+3. **Precision** – If needed, use `dist/custom-elements.manifest.json` or
+   `dist/types/` for exact types and full API.
+
+## Package exports
+
+Consumers can resolve these paths from `@getflip/swirl-ai`:
+
+- `@getflip/swirl-ai/manifest` → `dist/custom-elements.manifest.json`
+- `@getflip/swirl-ai/agent-index` → `dist/agent/components-index.json`
+
+Per-component docs are under `dist/agent/components/` (e.g.
+`node_modules/@getflip/swirl-ai/dist/agent/components/swirl-accordion.md`).
+Resolve via your bundler or file system relative to the package root.
+
+## Agent index schema
+
+`components-index.json` has `schemaVersion: 1` and a `components` array. Each
+entry includes:
+
+- `tag`, `summary`, `whenToUse`, `requiredProps`, `optionalProps`
+- `events`, `slots`, `methods`
+- `accessibilityInfo`, `compositionRules`, `relatedComponents`, `status`
+  (`stable` | `deprecated` | `experimental`)
+
+Schema and field semantics are stable within major package versions; new
+optional fields may be added.
+
+## Versioning
+
+Artifacts are generated from `@getflip/swirl-components` at build time. Keep
+`@getflip/swirl-ai` and `@getflip/swirl-components` versions in sync so the
+index and docs match the installed components.

package/dist/agent/components/swirl-accordion-item.md

@@ -0,0 +1,78 @@
+# `<swirl-accordion-item>`
+
+## Purpose
+
+The SwirlAccordionItem component is used to provide a collapsible section of content. It is always contained within a [SwirlAccordion](?path=/docs/components-swirlaccordion--docs) component.
+
+## Required props
+
+- `heading` (string) – 
+
+## Optional props
+
+- `description` (string | undefined) – 
+- `disabled` (boolean | undefined) – 
+- `headingLevel` (1 | 2 | 3 | 4 | 5 | 6 | undefined) – 
+- `initiallyOpen` (boolean | undefined) – 
+- `itemId` (string | undefined) – 
+
+## Slots
+
+- **`media`** – Media slot for content to be displayed before the content.
+- **`slot`** – The accordion item content.
+- **`trailing`** – Trailing slot for content to be displayed before the expand icon.
+
+## Events
+
+- `expansionChange` – CustomEvent<boolean>
+
+## Methods
+
+- `collapse()` – Collapses the accordion item.
+- `expand()` – Expands the accordion item.
+- `toggle()` – Toggles the accordion item.
+
+## Related components
+
+- **[swirl-accordion](?path=/docs/components-swirlaccordion--docs)** (parent) —
+  Container for accordion items; `swirl-accordion-item` must be used as a direct
+  child.
+
+## Accessibility
+
+See [SwirlAccordion](?path=/docs/components-swirlaccordion--docs).
+
+### Keyboard
+
+| Key              | Action                      |
+| ---------------- | --------------------------- |
+| <kbd>Enter</kbd> | Toggles the accordion item. |
+| <kbd>Space</kbd> | Toggles the accordion item. |
+
+## Minimal example
+
+```html
+<swirl-accordion-item heading="..."></swirl-accordion-item>
+```
+
+## Usage example
+
+```html
+<swirl-accordion-item description="Lorem ipsum dolor sit amet, consectetur adipiscing elit." heading="Accordion item">
+    <swirl-avatar slot="media" icon="<swirl-icon-groups></swirl-icon-groups>"></swirl-avatar>
+    <swirl-text slot="trailing" color="subdued">Trailing slot</swirl-text>
+    <swirl-stack spacing="16">
+        <swirl-text size="sm">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod euismod libero, nec sollicitudin diam
+            ultricies ut. Donec eget consectetur libero. Donec et mi non mauris fermentum dictum. Sed scelerisque,
+            sapien vitae fringilla aliquam, quam sapien aliquet.
+        </swirl-text>
+        <swirl-button label="A button" variant="flat"></swirl-button>
+    </swirl-stack>
+</swirl-accordion-item>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.

package/dist/agent/components/swirl-accordion.md

@@ -0,0 +1,132 @@
+# `<swirl-accordion>`
+
+## Purpose
+
+The SwirlAccordion component is used to display vertically stacked headings that reveal sections of content.
+
+## Required props
+
+_None._
+
+## Optional props
+
+- `multiExpand` (boolean | undefined) – 
+
+## Slots
+
+- **`slot`** – The accordion items (e.g. swirl-accordion-item).
+
+## Events
+
+- `expandedItemChange` – CustomEvent<string>
+
+## Methods
+
+- `collapseItem()` – Collapses an accordion item.
+- `expandItem()` – Expands an accordion item.
+
+## Related components
+
+- **[swirl-accordion-item](?path=/docs/components-swirlaccordionitem--docs)**
+  (child) — Individual expandable section; use as a direct child of
+  `swirl-accordion`.
+
+## Accessibility
+
+### ARIA
+
+The component follows the
+[WAI-ARIA Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
+
+| ARIA              | Usage                                                                     |
+| ----------------- | ------------------------------------------------------------------------- |
+| `role="heading"`  | Used to provide a heading for each accordion item.                        |
+| `role="button"`   | Contained by the headline of each accordion item.                         |
+| `aria-expanded`   | Set on the item's button.                                                 |
+| `aria-controls`   | Set on the item's button, referencing the controlled content section.     |
+| `role="region"`   | Set on each content section container.                                    |
+| `aria-labelledby` | Set on each content section container, referencing the associated button. |
+
+### Keyboard
+
+| Key              | Action                                                         |
+| ---------------- | -------------------------------------------------------------- |
+| <kbd>ENTER</kbd> | Activates the focused accordion item, closing all other items. |
+| <kbd>SPACE</kbd> | Activates the focused accordion item, closing all other items. |
+
+## Minimal example
+
+```html
+<swirl-accordion></swirl-accordion>
+```
+
+## Usage example
+
+```html
+<swirl-accordion>
+    <swirl-accordion-item
+        description="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+        heading="Accordion item 1"
+        initially-open
+        item-id="item-1"
+    >
+        <swirl-avatar slot="media" icon="<swirl-icon-groups></swirl-icon-groups>"></swirl-avatar>
+        <swirl-stack spacing="16">
+            <swirl-text size="sm">
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod euismod libero, nec sollicitudin
+                diam ultricies ut. Donec eget consectetur libero. Donec et mi non mauris fermentum dictum. Sed
+                scelerisque, sapien vitae fringilla aliquam, quam sapien aliquet.
+            </swirl-text>
+            <swirl-button label="A button" variant="flat"></swirl-button>
+        </swirl-stack>
+    </swirl-accordion-item>
+    <swirl-accordion-item
+        description="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+        heading="Accordion item 2"
+        item-id="item-2"
+    >
+        <swirl-stack spacing="16">
+            <swirl-text size="sm">
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod euismod libero, nec sollicitudin
+                diam ultricies ut. Donec eget consectetur libero. Donec et mi non mauris fermentum dictum. Sed
+                scelerisque, sapien vitae fringilla aliquam, quam sapien aliquet.
+            </swirl-text>
+            <swirl-button label="A button" variant="flat"></swirl-button>
+        </swirl-stack>
+    </swirl-accordion-item>
+    <swirl-accordion-item
+        description="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+        heading="Accordion item 3"
+        item-id="item-3"
+    >
+        <swirl-stack spacing="16">
+            <swirl-text size="sm">
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod euismod libero, nec sollicitudin
+                diam ultricies ut. Donec eget consectetur libero. Donec et mi non mauris fermentum dictum. Sed
+                scelerisque, sapien vitae fringilla aliquam, quam sapien aliquet.
+            </swirl-text>
+            <swirl-button label="A button" variant="flat"></swirl-button>
+        </swirl-stack>
+    </swirl-accordion-item>
+    <swirl-accordion-item
+        description="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+        disabled
+        heading="Accordion item 4"
+        item-id="item-4"
+    >
+        <swirl-stack spacing="16">
+            <swirl-text size="sm">
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod euismod libero, nec sollicitudin
+                diam ultricies ut. Donec eget consectetur libero. Donec et mi non mauris fermentum dictum. Sed
+                scelerisque, sapien vitae fringilla aliquam, quam sapien aliquet.
+            </swirl-text>
+            <swirl-button label="A button" variant="flat"></swirl-button>
+        </swirl-stack>
+    </swirl-accordion-item>
+</swirl-accordion>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.

package/dist/agent/components/swirl-action-list-item.md

@@ -0,0 +1,92 @@
+# `<swirl-action-list-item>`
+
+## Purpose
+
+The SwirlActionListItem component is used to render menu items inside the [SwirlActionList component](?path=/docs/components-swirlactionlist--docs).
+
+## Required props
+
+- `label` (string) – 
+
+## Optional props
+
+- `badge` (string | undefined) – 
+- `description` (string | undefined) – 
+- `disabled` (boolean | undefined) – 
+- `icon` (string | undefined) – 
+- `iconBadge` (string | undefined) – 
+- `intent` ("critical" | "default" | undefined) – 
+- `size` ("l" | "m" | undefined) – 
+- `suffix` (string | undefined) – 
+- `swirlAriaExpanded` (string | undefined) – 
+- `swirlAriaHaspopup` (string | undefined) – 
+- `truncateLabel` (boolean | undefined) – 
+
+## Slots
+
+- **`avatar`** – Optional avatar displayed to the left of the label
+- **`suffix`** – Used to add custom content to the end of the action list item.
+
+## Events
+
+_None._
+
+## Methods
+
+_None._
+
+## Related components
+
+- **[swirl-action-list](?path=/docs/components-swirlactionlist--docs)** (parent)
+  — Container for action list items and sections; use as a direct child of
+  `swirl-action-list` or inside `swirl-action-list-section`.
+
+## Accessibility
+
+### ARIA
+
+The component follows the
+[WAI-ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+
+| ARIA              | Usage                                                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `role="menuitem"` | The action list item has `role` set to `menuitem`. It should only be used inside a component with `role="menu"`. |
+
+### Keyboard
+
+| Key              | Action              |
+| ---------------- | ------------------- |
+| <kbd>ENTER</kbd> | Activates the item. |
+| <kbd>SPACE</kbd> | Activates the item. |
+
+## Minimal example
+
+```html
+<swirl-action-list-item label="..."></swirl-action-list-item>
+```
+
+## Usage example
+
+```html
+<swirl-action-list-item
+    badge="Badge"
+    description="Description of the action list item"
+    icon="<swirl-icon-mention></swirl-icon-mention>"
+    icon-badge='<swirl-badge label="1"></swirl-badge>'
+    label="This is an action"
+    suffix="<swirl-icon-chevron-right></swirl-icon-chevron-right>"
+>
+    <swirl-avatar
+        slot="avatar"
+        label="Jane Doe"
+        size="l"
+        src="https://api.dicebear.com/7.x/bottts-neutral/svg?size=144&seed=a"
+    ></swirl-avatar>
+    <swirl-switch checked hide-label label="Test" slot="suffix"></swirl-switch>
+</swirl-action-list-item>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.

package/dist/agent/components/swirl-action-list-section.md

@@ -0,0 +1,64 @@
+# `<swirl-action-list-section>`
+
+## Purpose
+
+The SwirlActionListSection component is used to group related [SwirlActionListItems](?path=/docs/components-swirlactionlistitem--docs).
+
+## Required props
+
+- `label` (string) – 
+
+## Optional props
+
+- `hasSeparator` (boolean | undefined) – 
+- `separatorSpacing` ("0" | "12" | "16" | "2" | "24" | "32" | "4" | "8" | undefined) – 
+- `spacing` ("0" | "12" | "16" | "2" | "24" | "32" | "4" | "40" | "48" | "64" | "8" | undefined) – 
+
+## Slots
+
+- **`slot`** – The action list item components
+
+## Events
+
+_None._
+
+## Methods
+
+_None._
+
+## Related components
+
+- **[swirl-action-list](?path=/docs/components-swirlactionlist--docs)** (parent)
+  — Container for action list sections and items; use as a direct child of
+  `swirl-action-list`.
+- **[swirl-action-list-item](?path=/docs/components-swirlactionlistitem--docs)**
+  (child) — Menu items; use as direct children of this section.
+
+## Accessibility
+
+### ARIA
+
+| ARIA           | Usage                                      |
+| -------------- | ------------------------------------------ |
+| `role="group"` | The action list has `role` set to `group`. |
+
+### Keyboard
+
+No component-specific keyboard behavior.
+
+## Minimal example
+
+```html
+<swirl-action-list-section label="..."></swirl-action-list-section>
+```
+
+## Usage example
+
+```html
+<swirl-action-list-section label="Section label" has-separator></swirl-action-list-section>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.

package/dist/agent/components/swirl-action-list.md

@@ -0,0 +1,88 @@
+# `<swirl-action-list>`
+
+## Purpose
+
+The SwirlActionList component is used to render a menu containing of [SwirlActionListSections](?path=/docs/components-swirlactionlistsection--docs) and [SwirlActionListItems](?path=/docs/components-swirlactionlistitem--docs). It should be used in combination with the [SwirlPopover component](?path=/docs/components-swirlpopover--docs).
+
+## Required props
+
+_None._
+
+## Optional props
+
+_None._
+
+## Slots
+
+- **`slot`** – The action list items and sections
+
+## Events
+
+_None._
+
+## Methods
+
+_None._
+
+## Related components
+
+- **[swirl-action-list-section](?path=/docs/components-swirlactionlistsection--docs)**
+  (child) — Optional grouping for items; use as a direct child of
+  `swirl-action-list`.
+- **[swirl-action-list-item](?path=/docs/components-swirlactionlistitem--docs)**
+  (child) — Menu items; use as direct children of `swirl-action-list` or inside
+  `swirl-action-list-section`. Often used inside
+  [swirl-popover](?path=/docs/components-swirlpopover--docs).
+
+## Accessibility
+
+### ARIA
+
+The component follows the
+[WAI-ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/).
+
+| ARIA               | Usage                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `role="menu"`      | The action list has `role` set to `menu`.                                                                         |
+| `role="menuitem"`  | Set for all menu items via the [SwirlActionListItem](?path=/docs/components-swirlactionlistitem--docs) component. |
+| `aria-orientation` | Set to `vertical`.                                                                                                |
+
+### Keyboard
+
+| Key                                    | Action                                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| <kbd>TAB</kbd>, <kbd>SHIFT + TAB</kbd> | Moves focus out of the menu, if it has focus.                                                     |
+| <kbd>ENTER</kbd>, <kbd>SPACE</kbd>     | Activates the focused menu item.                                                                  |
+| <kbd>RIGHT</kbd>, <kbd>DOWN</kbd>      | Focuses the next menu item; moves focus to the first menu item, if the last one was in focus.     |
+| <kbd>LEFT</kbd>, <kbd>UP</kbd>         | Focuses the previous menu item; moves focus to the last menu item, if the first one was in focus. |
+
+## Minimal example
+
+```html
+<swirl-action-list></swirl-action-list>
+```
+
+## Usage example
+
+```html
+<swirl-action-list>
+    <swirl-action-list-item
+        icon="<swirl-icon-mention></swirl-icon-mention>"
+        label="Action item 1"
+    ></swirl-action-list-item>
+    <swirl-action-list-item
+        icon="<swirl-icon-mention></swirl-icon-mention>"
+        label="Action item 2"
+    ></swirl-action-list-item>
+    <swirl-separator></swirl-separator>
+    <swirl-action-list-item
+        icon="<swirl-icon-mention></swirl-icon-mention>"
+        label="Action item 3"
+    ></swirl-action-list-item>
+</swirl-action-list>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.

package/dist/agent/components/swirl-app-bar.md

@@ -0,0 +1,84 @@
+# `<swirl-app-bar>`
+
+## Purpose
+
+The SwirlAppBar component is used to display a header app bar inside the [SwirlAppLayout](?path=/docs/components-swirlapplayout--docs) or [SwirlModal](?path=/docs/components-swirlmodal--docs).
+
+## Required props
+
+_None._
+
+## Optional props
+
+- `backButtonLabel` (string | undefined) – 
+- `closeButtonIcon` (string | undefined) – 
+- `closeButtonLabel` (string | undefined) – 
+- `paddingInlineEnd` ("0" | "12" | "16" | "2" | "20" | "24" | "32" | "4" | "8" | undefined) – 
+- `paddingInlineStart` ("0" | "12" | "16" | "2" | "20" | "24" | "32" | "4" | "8" | undefined) – 
+- `showBackButton` (boolean | undefined) – 
+- `showCloseButton` (boolean | undefined) – 
+- `showHeading` (boolean | undefined) – 
+- `showStepperControls` (boolean | undefined) – 
+- `stepDownButtonLabel` (string | undefined) – 
+- `stepUpButtonLabel` (string | undefined) – 
+
+## Slots
+
+- **`center-controls`** – Container for controls displayed in the center
+- **`cta`** – Container for a call to action button
+- **`heading`** – The app bar's heading element
+- **`right-controls`** – Container for controls displayed at the end of the bar
+
+## Events
+
+- `backButtonClick` – CustomEvent<MouseEvent>
+- `closeButtonClick` – CustomEvent<MouseEvent>
+- `stepDownButtonClick` – CustomEvent<MouseEvent>
+- `stepUpButtonClick` – CustomEvent<MouseEvent>
+
+## Methods
+
+_None._
+
+## Related components
+
+No related components.
+
+## Accessibility
+
+SwirlAppBar is a layout container for header content. Buttons (back, close,
+stepper) use accessible labels via props. No component-level ARIA role or
+keyboard shortcuts; interaction is handled by slotted controls.
+
+### Keyboard
+
+No component-specific keyboard behavior; slotted buttons and links handle focus
+and activation.
+
+## Minimal example
+
+```html
+<swirl-app-bar></swirl-app-bar>
+```
+
+## Usage example
+
+```html
+<swirl-app-bar show-close-button>
+    <swirl-heading as="h1" level="3" slot="heading" text="Heading" truncate></swirl-heading>
+    <swirl-stack justify="center" orientation="horizontal" spacing="8" slot="center-controls">
+        <swirl-button label="All posts" variant="flat"></swirl-button>
+        <swirl-button label="Groups"></swirl-button>
+        <swirl-button label="Saved"></swirl-button>
+        <swirl-button label="Scheduled"></swirl-button>
+    </swirl-stack>
+    <div slot="right-controls">
+        <swirl-button hide-label="true" icon="<swirl-icon-search></swirl-icon-search>" label="Search"></swirl-button>
+    </div>
+</swirl-app-bar>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.

package/dist/agent/components/swirl-app-icon.md

@@ -0,0 +1,57 @@
+# `<swirl-app-icon>`
+
+## Purpose
+
+The SwirlAppIcon component is used to provide icons for different use cases. E.g. [ShellLayout](?path=/docs/components-swirlshelllayout--docs) or the [ShellNavigationItem](?path=/docs/components-swirlshellnavigationitem--docs)
+
+## Required props
+
+_None._
+
+## Optional props
+
+- `icon` (string | undefined) – 
+- `src` (string | undefined) – 
+
+## Slots
+
+_None._
+
+## Events
+
+_None._
+
+## Methods
+
+_None._
+
+## Related components
+
+No related components.
+
+## Accessibility
+
+SwirlAppIcon is a presentational icon component with no ARIA attributes or
+keyboard-specific behavior. When used as the only content of a button or link,
+ensure the parent provides an accessible label.
+
+### Keyboard
+
+No component-specific keyboard behavior.
+
+## Minimal example
+
+```html
+<swirl-app-icon></swirl-app-icon>
+```
+
+## Usage example
+
+```html
+<swirl-app-icon src="https://picsum.photos/id/433/144/144"></swirl-app-icon>
+```
+
+## Common mistakes
+
+- Ensure required props are set.
+- Use only allowed slot names and child components where documented.