# File types

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets/file-types

<AssetExplorer collection="file-types" />

## Folders [#folders]

```tsx
import { Icons } from '@commenda/pathfinder';

<Icons.Folder status="closed" size={24} />
<Icons.Folder status="open" size={24} />
```

`status` is required and accepts `open` or `closed`. Sizes are 16 (default), 24, and 40. Native `width` and `height` can change display dimensions while `size` selects the authored drawing. These are the illustrated document folders; outline interface glyphs remain under `Icons.Interface`.

## Usage [#usage]

```tsx
import { FileTypeIcon, FileTypeHelper } from '@commenda/pathfinder/file-types';
<FileTypeIcon
  kind={FileTypeHelper.fromFilename('Annual report.PDF')}
  size={24}
/>;
```

**ASSET-FILE-01:** Use 16 for rows/chips/inline links, 24 for lists/tables, and 40 for uploads/cards. All 13 families and 39 variants are local. Preserve outlined lettering and type colors; no font is required to render the badges.

**ASSET-FILE-02:** Pair artwork with a filename. File kind is conveyed by badge lettering and filename, not color alone. The 16px JSON drawing exports at **17×16** because its badge extends outside the component; preserve that width rather than squeezing the lettering.

`kind` accepts `pdf`, `doc`, `xls`, `csv`, `ppt`, `txt`, `image`, `json`, `xml`, `zip`, `generic`, `folder`, and `folder-open`. The filename helper normalizes extension case and uses the final filename segment. Extensionless names, dotfiles, and unfamiliar extensions return `generic`. It does not inspect file content or parse URLs.

**ASSET-FILE-03:** The resolver follows the extension lists printed beneath the Figma component sets:

| Kind           | Extensions                           |
| -------------- | ------------------------------------ |
| PDF            | pdf                                  |
| Document       | docx, doc, rtf, odt                  |
| Spreadsheet    | xlsx, xls, xlsm, ods                 |
| Delimited data | csv, tsv                             |
| Presentation   | pptx, ppt, key                       |
| Text           | txt, md, log                         |
| Image          | png, jpg, jpeg, gif, svg, webp, heic |
| JSON           | json                                 |
| XML            | xml, html                            |
| Archive        | zip, rar, 7z, tar, gz                |

The source component descriptions are empty; the visible gallery annotations carry these rules. Full text and source IDs are retained in `figma-guidance.json`.


---

# Flags

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets/flags

<AssetExplorer collection="flags" />

## Usage [#usage]

```tsx
import { DZFlag } from '@commenda/pathfinder/flags';
<DZFlag size={16} label="Algeria" />;
```

**ASSET-FLAG-01:** Sizes are 12, 16 (default), 20, and 24. Preserve the round crop and inside 0.5px Soft Pearl 300 hairline at every size; do not recolor the flag.

**ASSET-FLAG-02:** Flags represent countries or territories, not languages. Display a country name when identification matters. Figma includes 256 codes, including `GE-AB`, `GE-OS`, and `XK`; codes are not constrained to two characters.

For dynamic country data, explicitly import the registry-backed component. It includes the flag collection; use named imports when codes are known in advance.

```tsx
import { CountryFlag } from '@commenda/pathfinder/flags/dynamic';
<CountryFlag code="US" label="United States" />;
```

Codes are trimmed and case-normalized. Unknown codes render a neutral circle without inventing a country identity. Provide your own localized label, such as “Country unavailable.”


---

# Icons

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets/icons

<AssetExplorer collection="icons" />

## Usage [#usage]

```tsx
import { SearchMdIcon } from '@commenda/pathfinder/icons';
<SearchMdIcon size={16} tone="brand" label="Search" />;
```

**ASSET-ICON-01:** Sizes are 12, 16 (default), 20, and 24. Use 16 beside Label/13 and small/medium controls; 20 for large controls; 12 for badges/dense tables; 24 for featured/empty states.

**ASSET-ICON-02:** The 16px drawing uses an effective 1.5px stroke. The 12/20/24 variants reuse the 24px SVG where a rendered comparison verifies matching geometry. Width and height change at rendering time; redundant source copies are removed. Outlined geometry does not accept a stroke-weight override.

**ASSET-ICON-03:** Default is Soft Pearl 900; `quiet` uses 800, `strong` 1000, `brand` Blue 700, and `destructive` Red 700. `inherit` takes the parent's color. Brand-colored Commenda artwork retains its own colors and has no tone prop.

Figma contains 1,186 families: 1,173 Untitled UI icons, five Commenda marks, and **eight** Pathfinder additions. Its introduction still says seven additions; `stop-fill` is the extra family. The [asset reference](/assets.txt) lists every named export and supported size; `assets.json` retains source-node provenance.


---

# Visual assets

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets

Browse the collections below, search by name, and select artwork to copy its import. The [machine-readable asset reference](/assets.txt) records the complete public surface and any explicit exclusions.

<AssetPreview />

## Install and render [#install-and-render]

Import `@commenda/pathfinder/styles.css` once. Each collection has its own entry point. Individual components also have direct imports, such as `@commenda/pathfinder/icons/SearchMdIcon`. No application Tailwind scan, SVG loader, remote asset service, or asset-copy step is required.

Artwork renders as native inline SVG. Pathfinder generates and compiles the React components at package build time; consuming apps need no SVG loader. Monochrome paths use `currentColor`; multicolor artwork preserves its source colors. Simple glyphs are server components. Artwork with masks, clipping paths, or gradients uses a small client boundary with React `useId` so repeated instances remain unique through server rendering and hydration. Original embedded raster images are retained where they are part of a supplied logo.

### Category namespaces [#category-namespaces]

```tsx
import { Icons } from '@commenda/pathfinder';

<Icons.Flags.US label="United States" />
<Icons.Interface.SearchMd size={16} tone="quiet" />
<Icons.FileTypes.Pdf label="PDF document" />
<Icons.Folder status="closed" size={24} />
<Icons.Status status="completed" label="Completed" />
<Icons.Progress.Ring value={33} label="Documents complete" />
<Icons.Logos.Integrations.Quickbooks label="QuickBooks" />
<Icons.Logos.Payments.Visa label="Visa" />
<Icons.Logos.Software.Google label="Google" />
<Icons.Logos.Commenda.Lockup label="Commenda" />
```

The categories autocomplete in TypeScript and preserve each component's props. Country names use uppercase codes; territory hyphens are removed in JSX names, for example `Icons.Flags.GEAB`. Every component's namespace is listed in the [machine-readable asset reference](/assets.txt) and `assets.json`. Static member access is tree-shakeable. Passing whole categories around or indexing them dynamically may retain that category's artwork; use `CountryFlag` from `/flags/dynamic` when the country code comes from data.

### Folder and status rules [#folder-and-status-rules]

**ASSET-API-01:** Use one `Icons.Folder` component with the required `status="open" | "closed"` prop. It renders the illustrated document-folder family. Choose `size={16 | 24 | 40}`; the default is 16. Do not use the former `Icons.FileTypes.Folder` or `Icons.FileTypes.FolderOpen` aliases. Outline interface-folder glyphs are a separate family under `Icons.Interface`.

**ASSET-API-02:** `Icons.Status` is a component, not a category namespace. Its required `status` is one of `to-do`, `scheduled`, `in-progress`, `in-review`, `completed`, `canceled`, `blocking`, `blocked-by`, `failed`, or `needs-attention`. Always supply a translated `label`. Use `size={12 | 16 | 20 | 24}`; the default is 16. Replace `Icons.Status.Completed` with `<Icons.Status status="completed" label="Completed" />`. Existing named `StatusIcon` imports continue to work.

### Native sizing [#native-sizing]

**ASSET-SIZE-01:** `size` selects an authored optical variant. `width` and `height` control the rendered dimensions while the source `viewBox` preserves its proportions. You do not need another downloaded file for a different display size.

```tsx
<Icons.Interface.SearchMd size={24} width={32} height={32} tone="inherit" />
<Icons.Logos.Integrations.Quickbooks width={48} height={48} label="QuickBooks" />
```

Native SVG attributes such as `aria-label`, `aria-labelledby`, `aria-describedby`, `className`, `style`, and event handlers are forwarded to the SVG. Event handlers belong in client components. Prefer `label` for a simple accessible name; an explicit `aria-label` takes precedence. Refs and replacement children are not part of this API.

## Accessibility rules [#accessibility-rules]

- **ASSET-A11Y-01:** Omit `label` for decorative artwork beside equivalent visible text. Meaningful standalone artwork needs an explicit, localized `label`.
- **ASSET-A11Y-02:** Name an icon-only button on the button. The icon stays decorative; a tooltip alone is insufficient.
- **ASSET-A11Y-03:** Status and progress information must have a readable name/count. Color is never the only signal. Assets do not create focus stops.
- **ASSET-SOURCE-01:** Canonical source SVGs, original checksums, and verified shared-source mappings are retained locally. Never fetch temporary Figma URLs at runtime. Do not hand-edit generated components.

## AI and provenance [#ai-and-provenance]

The same pages are available through the Markdown links, `/llms.txt`, and `/llms-full.txt`. Import `@commenda/pathfinder/assets.json` to inspect the versioned catalog without importing a runtime registry. It records availability, source node IDs, sizes, export names, upstream versions, and downloaded-source checksums. Shared source references record deduplication without losing the original Figma IDs. Activity’s tooltip and motion variants are explicitly excluded from the static API.

Brand marks remain their owners' trademarks. See the package's third-party notices for source licenses. The package remains UNLICENSED.


---

# Logos

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets/logos

<AssetExplorer collection="logos" />

## Usage [#usage]

```tsx
import { QuickbooksLogo } from '@commenda/pathfinder/logos/integrations';
<QuickbooksLogo size={40} label="QuickBooks" />;
```

**ASSET-LOGO-01:** Preserve original brand colors, proportions, and raster/vector artwork. Never trace or recolor logos. Integration tiles have a white round background and inside 0.5px Soft Pearl 300 border, with authored sizes 16, 24, 32, and 40. The API defaults to 40 for integration cards.

**ASSET-LOGO-02:** Payment marks use their own rectangular 46×32 or square 32×32 geometry plus 24/16 variants. Software/sign-in marks are bare. Import these from `@commenda/pathfinder/logos/payments` and `@commenda/pathfinder/logos/software`, respectively. Do not wrap an integration logo to approximate them.

Figma inventories 48 integrations, 50 payments, four software/sign-in marks, and an additional `commenda-lockup` at 106×18. The lockup has its own `@commenda/pathfinder/logos/commenda` entry point. The catalog preserves each mark’s width-to-height ratio; `size` selects the authored height.

The 24px rectangular payment variant has a 34.5px Figma frame; Figma exports a 35×24 SVG viewport. The renderer preserves that export width so the artwork is not squeezed.


---

# Status icons and progress

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets/status-icons

<AssetExplorer collection="status-icons" />

## Usage [#usage]

```tsx
import { Icons } from '@commenda/pathfinder';
<Icons.Status status="in-review" label="In review" />
<Icons.Progress.Ring value={33} label="Documents complete" valueText="3 of 9 complete" />
```

**ASSET-STATUS-01:** Ten statuses use sizes 12, 16 (default), 20, and 24. `to-do` is backlog; `scheduled` is planned but not started. They share a glyph, so their labels carry the distinction. `in-progress` means started; `in-review` awaits a reviewer; `completed` is done; `canceled` will not be done.

**ASSET-STATUS-02:** `blocking` holds up another item; `blocked-by` waits on another item. These relationships stay neutral. `failed` needs a redo; `needs-attention` needs someone to act. In progress uses Amber 600, review Blue 600, completed Green 700, failed Red 700, attention Orange 700, and neutral states Soft Pearl 700.

**ASSET-PROGRESS-01:** The semantic `ProgressRing` / `Icons.Progress.Ring` accepts any measured numeric value with an optional `max` (100 by default), or `null` for indeterminate progress. Sizes remain 16 (default), 24 and 32. The source-aligned arc sweeps clockwise from 12 o'clock; track Soft Pearl 700 at 35% opacity. Provide a name and pair with a count; `valueText` supplies a human-readable value. Explicit complete/failed states and reduced-motion-aware animation follow the [Progress contract](/docs/components/progress). The nine static `Progress0Icon` through `Progress100Icon` artwork exports remain available for static specimens.

The additional Figma `activity` family contains five row-indicator states with tooltip variants and a running-motion rule. Its ten source variants are retained, but are explicitly excluded from this static status API. Its tooltip and animation behavior require a dedicated component.

## Progress library [#progress-library]

<AssetExplorer collection="progress" />


---

# Accordion

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/accordion
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=363-2

```tsx
import { Accordion, type AccordionItem } from '@commenda/pathfinder/accordion';

const filingSections: AccordionItem[] = [
  {
    value: 'scope',
    title: 'What the annual report covers',
    content:
      'We file the Delaware annual report, pay the franchise tax and send you the state’s confirmation.',
  },
  {
    value: 'due',
    title: 'When it is due',
    description: 'Delaware, due 1 March',
    content:
      'Complete your review by 15 February so there is time to prepare the filing.',
  },
  {
    value: 'details',
    title: 'What we need from you',
    badgeConfig: { label: 'Action needed', tone: 'warning' },
    content: (
      <label>
        Company reference{' '}
        <input aria-label="Company reference" placeholder="Add a reference" />
      </label>
    ),
  },
];

export const AccordionDefault = () => (
  <Accordion headingLevel={2} defaultValue={['scope']} items={filingSections} />
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/accordion`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly AccordionItem[]` | required | Required; value, title, content; optional description, badgeConfig, disableConfig |
| `variant` | `"card" \| "divided"` | optional | divided |
| `mode` | `"multiple" \| "single"` | conditional | multiple |
| `value` | `readonly string[] \| string \| null` | conditional | Array in multiple mode; string/null in single mode |
| `defaultValue` | `readonly string[] \| string \| null` | optional | Array in multiple mode; string/null in single mode |
| `onValueChange` | `((value: readonly string[]) => void) \| ((value: string \| null) => void)` | conditional | Required with value; follows mode type |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | optional | 3; choose for the surrounding document |
| `panelConfig` | `{ keepMounted?: boolean; }` | optional | true; retains embedded form values |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### panelConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | No |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Controlled value requires onValueChange and cannot be combined with defaultValue. Item IDs/values must be unique and stable.

## Usage rules [#usage-rules]

Multiple mode permits several open sections. Single mode opens at most one and allows closing it to `null`. All start closed unless defaultValue is supplied; open the first when it contains the main information.

The entire header is one button. `badgeConfig` is read-only; do not put links, checkboxes, or action buttons in the title. `disableConfig` groups isDisabled/reason. Tab visits headers in document order; Enter/Space toggles. No arrow-key roving focus. The chevron turns 180° and content height animates over 200ms, disabled with reduced motion.

Keep mounted panels preserve state while their content is hidden from focus. The application opens the section containing a form error before focusing that field. Do not nest accordions. A single Show more block belongs to a Collapsible pattern.

## Examples [#examples]

### Cards [#cards]


```tsx
import { Accordion, type AccordionItem } from '@commenda/pathfinder/accordion';

const filingSections: AccordionItem[] = [
  {
    value: 'scope',
    title: 'What the annual report covers',
    content:
      'We file the Delaware annual report, pay the franchise tax and send you the state’s confirmation.',
  },
  {
    value: 'due',
    title: 'When it is due',
    description: 'Delaware, due 1 March',
    content:
      'Complete your review by 15 February so there is time to prepare the filing.',
  },
  {
    value: 'details',
    title: 'What we need from you',
    badgeConfig: { label: 'Action needed', tone: 'warning' },
    content: (
      <label>
        Company reference{' '}
        <input aria-label="Company reference" placeholder="Add a reference" />
      </label>
    ),
  },
];

export const AccordionCards = () => (
  <Accordion
    headingLevel={2}
    variant="card"
    defaultValue={['scope']}
    items={filingSections.map((item, index) => ({
      ...item,
      title:
        ['Annual filing scope', 'Filing deadline', 'Company details'][index] ??
        item.title,
    }))}
  />
);
```


### Single [#single]


```tsx
import { Accordion, type AccordionItem } from '@commenda/pathfinder/accordion';

const filingSections: AccordionItem[] = [
  {
    value: 'scope',
    title: 'What the annual report covers',
    content:
      'We file the Delaware annual report, pay the franchise tax and send you the state’s confirmation.',
  },
  {
    value: 'due',
    title: 'When it is due',
    description: 'Delaware, due 1 March',
    content:
      'Complete your review by 15 February so there is time to prepare the filing.',
  },
  {
    value: 'details',
    title: 'What we need from you',
    badgeConfig: { label: 'Action needed', tone: 'warning' },
    content: (
      <label>
        Company reference{' '}
        <input aria-label="Company reference" placeholder="Add a reference" />
      </label>
    ),
  },
];

export const AccordionSingle = () => (
  <Accordion
    headingLevel={2}
    mode="single"
    defaultValue="scope"
    items={filingSections.map((item, index) => ({
      ...item,
      title:
        ['Included in the report', 'Submission date', 'Required information'][
          index
        ] ?? item.title,
    }))}
  />
);
```


### Disabled [#disabled]


```tsx
import { Accordion } from '@commenda/pathfinder/accordion';

export const AccordionDisabled = () => (
  <Accordion
    headingLevel={2}
    items={[
      {
        value: 'restricted',
        title: 'Billing details',
        content: 'Billing details',
        disableConfig: {
          isDisabled: true,
          reason: 'Administrator access required',
        },
      },
    ]}
  />
);
```


The header `badgeConfig` accepts `label`, `tone`, and `indicatorConfig`. Its size is fixed to the small Badge variant so callers cannot request a size the header silently overrides.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Accordion [#accordion]

Source: [363:267](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=363-267), item 363:159, docs 364:217.

- `ACCORDION-01` — Source: whole header toggles; Label/13 Strong title, optional Copy/12 description and read-only badge; trailing 16 chevron turns 180°. No interactive elements inside the toggle.
- `ACCORDION-02` — Source/Pathfinder: multiple open is default; single mode is for mutually exclusive sections. All closed unless initialized. Preserve form state by keeping closed content mounted by default, without leaving it focusable.
- `ACCORDION-03` — Source: no nesting. Show more for one long block is a Collapsible pattern. Divided header padding 10/8, 0.5 rule, hover darkens only chevron. Card header 14/16, radius 10, section gap 8. Height/chevron transitions 200ms; reduced motion immediate.
- `ACCORDION-04` — Pathfinder: heading/button/panel relationships, native Tab order, Enter/Space toggle. App opens sections containing form errors before focusing the field. disableConfig groups disabled state and its reason. Single values are string/null; multiple values are readonly string arrays.


---

# Action card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/action-card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=658-33976

```tsx
import { ActionCard } from '@commenda/pathfinder/action-card';

<ActionCard
  title="Connect your accounting software"
  description="Bring transactions into Commenda."
  artwork={<IntegrationLogo />}
  actionConfig={{
    label: 'Connect account',
    onAction: connectAccount,
    pendingDescription: 'Finish connecting in the window that opened.',
  }}
  dismissConfig={{ onDismiss: persistDismissal }}
/>;
```


## Usage [#usage]

```tsx
import { ActionCard } from '@commenda/pathfinder/action-card';

<ActionCard
  title="Connect your accounting software"
  description="Bring transactions into Commenda."
  artwork={<IntegrationLogo />}
  actionConfig={{
    label: 'Connect account',
    onAction: connectAccount,
    pendingDescription: 'Finish connecting in the window that opened.',
  }}
  dismissConfig={{ onDismiss: persistDismissal }}
/>;
```

## Inline action [#inline-action]


```tsx
import { ActionCard } from '@commenda/pathfinder/action-card';

<ActionCard
  placement="inline"
  title="Connect your accounting software"
  description="Bring transactions into Commenda."
  artwork={<IntegrationLogo />}
  actionConfig={{
    label: 'Connect account',
    onAction: connectAccount,
    pendingDescription: 'Finish connecting in the window that opened.',
  }}
  dismissConfig={{ onDismiss: persistDismissal }}
/>;
```


## Failure and retry [#failure-and-retry]


```tsx
// Return { status: 'failed', message: 'Please try again.' } from the handler to retain this card.
import { ActionCard } from '@commenda/pathfinder/action-card';

<ActionCard
  title="Connect your accounting software"
  description="Bring transactions into Commenda."
  artwork={<IntegrationLogo />}
  actionConfig={{
    label: 'Connect account',
    onAction: connectAccount,
    pendingDescription: 'Finish connecting in the window that opened.',
  }}
  dismissConfig={{ onDismiss: persistDismissal }}
/>;
```


Reset restores the example. Simulate failure retains the card for retry; no backend request is made.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `title` | `string` | required | Required title and optional supporting text |
| `description` | `string` | optional | Required title and optional supporting text |
| `artwork` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | required | Decorative artwork rendered in the existing 40px Avatar |
| `actionConfig` | `{ label: string; onAction: () => ActionResult \| Promise<ActionResult>; pendingDescription?: string; }` | required | Handler returns `{ status: 'completed' }` or `{ status: 'failed', message }`, synchronously or asynchronously |
| `dismissConfig` | `{ label?: string; onDismiss: () => void; }` | optional | Optional secondary action, defaults to Not now; persists permanent dismissal |
| `state` | `"ready" \| "pending" \| "completed" \| "dismissed"` | optional | Host status; local pending/completion also tracked |
| `placement` | `"docked" \| "inline"` | optional | Docked radius16/raised, inline radius10/flat |
| `className` | `string` | optional | Layout override |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `onAction` | `() => ActionResult \| Promise<ActionResult>` | Yes |  |
| `pendingDescription` | `string` | No |  |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onDismiss` | `() => void` | Yes |  |

## Design rules [#design-rules]

- **ACTION-01:** Optional next action outside the blocking request flow. The frame is not a click target; only buttons activate.
- **ACTION-02:** One primary action and at most one secondary dismissal. Loading retains the action label with a spinner. Explain external-window work in the pending description when relevant.
- **ACTION-03:** Completion or dismissal removes the card. The host persists that outcome. No automatic agent turn, success toast, or promised follow-up. Historical cards remain usable until acted on or dismissed.

Return completion only when the action succeeds, not merely when an external window opens. If a blocked popup fails, return a failure message. Use a new React key for a new action, and store its completion/dismissal independently from conversational requests.

## Integration and accessibility [#integration-and-accessibility]

Buttons have explicit names and keyboard focus. No network transport or AI SDK provider is required. Requests, tool execution, permission checks, durable outcomes and composer coordination stay in the application. See [AI content integration](/docs/guides/ai-content) for migration mappings; application migration is outside this build.


---

# Address input

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/address-input
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=286-2

```tsx
import { AddressInput } from '@commenda/pathfinder/address-input';

export const AddressInputDefault = () => (
  <AddressInput
    label="Registered address"
    name="address"
    defaultValue={{
      country: 'US',
      addressLine1: '',
      addressLine2: '',
      city: '',
      region: '',
      postalCode: '',
    }}
    description="Enter the address shown on your registration documents."
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import {
  AddressInput,
  type AddressValue,
} from '@commenda/pathfinder/address-input';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | conditional | Accessible group name; one is required |
| `aria-label` | `string` | conditional | Accessible group name; one is required |
| `hideLabel` | `boolean` | optional | Visually hides the group label |
| `value` | `AddressValue` | conditional | Controlled or uncontrolled complete address; defaults to empty fields |
| `defaultValue` | `AddressValue` | optional | Controlled or uncontrolled complete address; defaults to empty fields |
| `onValueChange` | `((value: AddressValue) => void)` | conditional | Complete value on every edit; required with `value` |
| `countryConfig` | `AddressCountryConfig` | optional | Defaults to Kakashi's 199 named supported countries |
| `regionConfig` | `{ options: readonly ChoiceOption[]; }` | optional | Overrides the country-based searchable state/region selector |
| `suggestionsConfig` | `AddressSuggestionsConfig` | optional | Optional address lookup; manual entry always remains available |
| `requiredFields` | `readonly ("country" \| "addressLine1" \| "city" \| "region" \| "postalCode")[]` | optional | Per-field native required validation; line 2 is always optional |
| `fieldErrors` | `Partial<Record<keyof AddressValue, string>>` | optional | Field-specific messages displayed immediately |
| `disableConfig` | `{ isDisabled: boolean; reason?: string; }` | optional | Disables all fields and excludes them from native submission |
| `readOnly` | `boolean` | optional | Preserves readable, copyable, submittable values |
| `description` | `string` | optional | Group help text |
| `id` | `string` | optional | Group ID, field-name prefix, and native form association |
| `name` | `string` | optional | Group ID, field-name prefix, and native form association |
| `form` | `string` | optional | Group ID, field-name prefix, and native form association |
| `className` | `string` | optional | Root styling and additional accessible description |
| `aria-describedby` | `string` | optional | Root styling and additional accessible description |

### value fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `string` | Yes |  |
| `addressLine1` | `string` | Yes |  |
| `addressLine2` | `string` | Yes |  |
| `city` | `string` | Yes |  |
| `region` | `string` | Yes |  |
| `postalCode` | `string` | Yes |  |

### defaultValue fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `string` | Yes |  |
| `addressLine1` | `string` | Yes |  |
| `addressLine2` | `string` | Yes |  |
| `city` | `string` | Yes |  |
| `region` | `string` | Yes |  |
| `postalCode` | `string` | Yes |  |

### countryConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `allowedCountries` | `readonly ("AD" \| "AE" \| "AF" \| "AG" \| "AL" \| "AM" \| "AO" \| "AR" \| "AT" \| "AU" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BN" \| "BO" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EG" \| "ER" \| "ES" \| "ET" \| "FI" \| "FJ" \| "FM" \| "FR" \| "GA" \| "GB" \| "GD" \| "GE" \| "GH" \| "GM" \| "GN" \| "GQ" \| "GR" \| "GT" \| "GW" \| "GY" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IN" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MR" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NE" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PG" \| "PH" \| "PK" \| "PL" \| "PR" \| "PT" \| "PW" \| "PY" \| "QA" \| "RO" \| "RS" \| "RU" \| "RW" \| "SA" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SI" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SY" \| "SZ" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "US" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VN" \| "VU" \| "WS" \| "YE" \| "ZA" \| "ZM" \| "ZW")[]` | No |  |
| `excludedCountries` | `readonly ("AD" \| "AE" \| "AF" \| "AG" \| "AL" \| "AM" \| "AO" \| "AR" \| "AT" \| "AU" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BN" \| "BO" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EG" \| "ER" \| "ES" \| "ET" \| "FI" \| "FJ" \| "FM" \| "FR" \| "GA" \| "GB" \| "GD" \| "GE" \| "GH" \| "GM" \| "GN" \| "GQ" \| "GR" \| "GT" \| "GW" \| "GY" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IN" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MR" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NE" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PG" \| "PH" \| "PK" \| "PL" \| "PR" \| "PT" \| "PW" \| "PY" \| "QA" \| "RO" \| "RS" \| "RU" \| "RW" \| "SA" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SI" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SY" \| "SZ" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "US" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VN" \| "VU" \| "WS" \| "YE" \| "ZA" \| "ZM" \| "ZW")[]` | No |  |

### regionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `options` | `readonly ChoiceOption[]` | Yes |  |

### suggestionsConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `readonly AddressSuggestion[]` | Yes |  |
| `isLoading` | `boolean` | Yes |  |
| `error` | `string` | No |  |
| `resultsQuery` | `string` | Yes | Query that produced the supplied items; stale results cannot be selected. |
| `onQueryChange` | `(query: string) => void` | Yes |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

`AddressValue` contains six strings: `country` (ISO code), `addressLine1`, `addressLine2`, `city`, `region`, and `postalCode`. A `name="address"` produces fields named `address.country`, `address.addressLine1`, and so on. Uncontrolled values restore their defaults on form reset.

## Countries [#countries]


```tsx
import { AddressInput } from '@commenda/pathfinder/address-input';

export const AddressInputCountries = () => (
  <AddressInput
    label="Business address"
    countryConfig={{ allowedCountries: ['GB', 'US', 'IN', 'SG'] }}
    description="Country order follows Kakashi, regardless of the order in allowedCountries."
  />
);
```


Pathfinder's available country codes and labels are bundled at build time. United States, Canada, India, United Kingdom, Singapore, United Arab Emirates, and Ireland appear first, followed by other countries sorted alphabetically by label. `None`, `Other`, and entries without a label are omitted. Empty `allowedCountries` means all available countries; exclusions always apply. Filtering preserves the canonical order.

Pathfinder owns the supported countries, labels, priority order, and region exclusions in `packages/pathfinder/data/address-countries.json`. Run `pnpm --filter @commenda/pathfinder generate:address-countries` after changing this file. Regional metadata comes from Pathfinder's pinned `country-state-city` build dependency. Generation does not read another workspace package.

## Address suggestions [#address-suggestions]


```tsx
import { useState } from 'react';

import {
  AddressInput,
  type AddressValue,
} from '@commenda/pathfinder/address-input';

export const AddressInputSuggestions = () => {
  const [query, setQuery] = useState('');
  const address: AddressValue = {
    country: 'US',
    addressLine1: '350 Fifth Avenue',
    addressLine2: '',
    city: 'New York',
    region: 'NY',
    postalCode: '10118',
  };

  return (
    <AddressInput
      label="Search or enter an address"
      suggestionsConfig={{
        resultsQuery: query,
        onQueryChange: setQuery,
        isLoading: false,
        items:
          query && '350 fifth avenue'.includes(query.toLowerCase())
            ? [
                {
                  id: 'example',
                  label: address.addressLine1,
                  description: 'New York, NY 10118, United States',
                  address,
                },
              ]
            : [],
      }}
      description="Demo: type 350. You can always enter the address manually."
    />
  );
};
```


The example uses local demonstration data. Production applications supply `suggestionsConfig` with `items`, `isLoading`, `resultsQuery`, `onQueryChange`, and optional `error`. Each suggestion is `{ id, label, description?, address: AddressValue }`.

The application owns requests, debouncing, cancellation, and credentials. Set `resultsQuery` to the query that produced the current items, not the latest input before its request finishes. Stale results are hidden until their query matches the typed street address. Selecting a suggestion fills all six fields. Suggestions outside the allowed country list cannot be selected. Search failure never prevents manual entry.

## Validation [#validation]


```tsx
import { AddressInput } from '@commenda/pathfinder/address-input';

export const AddressInputStates = () => (
  <AddressInput
    label="Required address"
    requiredFields={['country', 'addressLine1', 'city', 'postalCode']}
    fieldErrors={{
      addressLine1: 'Enter the registered street address.',
      postalCode: 'Enter a postal code.',
    }}
  />
);
```


Country changes preserve all entered fields for review. State and region options default to the pinned country-state-city metadata, including Pathfinder's US territory exclusions. Countries with no metadata allow free-text entry. Applications can override the options with `regionConfig`; country-specific validation remains application-owned. Changing a country does not silently erase an address or select a region.

## Design and implementation rules [#design-and-implementation-rules]

- **ADDRESS-001:** Figma 292:9094 and 293:3032 establish the compact field treatment. Keep the approved stable order: country, street, optional line 2, city, region, postal code. Narrow layouts stack the fields.
- **ADDRESS-002:** Suggestions overlay the street field without moving the form. Manual editing remains available when search fails.
- **ADDRESS-003:** Preserve Pathfinder country availability, labels, and priority/alphabetical ordering. There is no private runtime dependency.
- **ADDRESS-004:** Preserve drafts on country changes; default regions follow the bundled metadata and application options override them. The application owns validation and requests.
- **ADDRESS-005:** Line 2 cannot be required. Preserve native autocomplete and form association for each field.
- **ADDRESS-006:** Only results matching the current street query can be selected.

These rules also live alongside the component implementation and are available through the Markdown endpoint, `llms.txt`, and `llms-full.txt`.

### Shared rules [#shared-rules]

Labels activate the first input. Descriptions, disabled reasons, and validation messages stay associated with the field. Error icons center on the first 18px text line, including wrapped messages. Controlled values require callbacks; uncontrolled form resets restore defaults. Public props expose application values, never private primitive or calendar objects. Styles ship precompiled for React 18/19 and Next.js consumers.


---

# Alert

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/alert
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=299-2

```tsx
import { Alert } from '@commenda/pathfinder/alert';
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Alert } from '@commenda/pathfinder/alert';
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
/>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `title` | `string` | conditional | At least one required |
| `description` | `string` | conditional | At least one required |
| `tone` | `FeedbackTone` | optional | neutral |
| `actionConfig` | `FeedbackAction` | optional | Secondary button |
| `secondaryActionConfig` | `FeedbackAction` | optional | Optional link |
| `dismissConfig` | `DismissConfig` | optional | Omit for a persistent callout |
| `open` | `boolean` | conditional | Controlled / uncontrolled; true initially |
| `defaultOpen` | `boolean` | optional | Controlled / uncontrolled; true initially |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Required with open; requests closure |
| `announcement` | `FeedbackAnnouncement` | optional | auto maps tone to live-region priority |
| `className` | `string` | optional | Additional classes for the component root. |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onDismiss` | `(() => void)` | No |  |

Never auto-dismiss. Title says what happened; description says what to do. Keep copy concise without truncating essential instructions. Field errors remain on fields; an alert may summarize them. onOpenChange requests closure immediately; onDismiss runs after the 200 ms collapse only when the owner allows closure. The application owns focus restoration after removing a focused alert.

### Actions [#actions]

`FeedbackAction` requires a label and exactly one of `onClick` (command) or `href` (native navigation). Commands support `disabled`, `disabledReason`, `loadingConfig`, and `leadingIcon`; navigation supports `target`, `rel`, and `leadingIcon`. The application owns async work and retry state.

## Examples [#examples]

### Tones [#tones]


```tsx
<>
  {(['neutral', 'info', 'success', 'warning', 'error'] as const).map((tone) => (
    <Alert
      key={tone}
      tone={tone}
      title="Review your filing"
      description="Review the filing details before submitting."
    />
  ))}
</>;
```


### Actions [#actions-1]


```tsx
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
  actionConfig={{ label: 'Review filing', onClick: onReviewFiling }}
  secondaryActionConfig={{ label: 'Learn more', href: '#usage' }}
/>;
```


### Dismissible [#dismissible]


```tsx
<Alert
  tone="info"
  title="Review your filing"
  description="Review the filing details before submitting."
  dismissConfig={{}}
/>;
```


Read the [design guidance](/docs/components/alert#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Alert and Banner — 299:2 [#alert-and-banner--2992]

- **ALERT-01:** Persistent, contextual feedback beside the form, table or figure it concerns. Never auto-dismiss. No dismissConfig produces a callout that stays until the owner removes it. Field errors remain on fields; form alerts summarize them.
- **ALERT-02:** Title states what happened without a period; description states the next step. Aim for two lines, but never clip essential text. At most a secondary small Button for recovery plus a link for more information. Passing confirmations use Toast.
- **ALERT-03:** Neutral is a state, info is news, success is completion, warning is an approaching issue, error is a current problem. Auto announcement maps warnings/errors to alert and info/success to status; neutral stays nonurgent. The explicit announcement prop can override this for the actual event.
- **ALERT-04:** Tinted background and 0.5 px border, radius 8, padding 12 vertical/16 start/12 end, gap 10; icon 16, Label/13 Strong title, Copy/13 body, gap 2. Close uses plain IconButton xs on tinted surfaces.
- **BANNER-01:** Whole-account or product context only; place beneath the breadcrumb across the content card. One at a time, one concise message, one link. The application owns placement and prioritization. Wrap on narrow screens rather than truncate.
- **BANNER-02:** Announcement is the sixth banner tone from node 917:314: blue 100/background, blue 300 bottom border, centered blue 900 copy, no icon or title, optional secondary small Button.
- **FEEDBACK-DISMISS-01:** Dismissal fades and collapses space over 200 ms, ease-out. onOpenChange requests closure immediately; onDismiss follows the collapse after an accepted close. A controlled owner can reject the request. The owner restores focus if needed.
- **FEEDBACK-ACTION-01:** Commands use Button; navigation uses native anchors. Require a label and exactly one of onClick or href. Components choose action appearance; callers own loading, disabled reasons and async behavior.


---

# Approval card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/approval-card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=607-4660

```tsx
import { ApprovalCard } from '@commenda/pathfinder/approval-card';

<ApprovalCard
  key={request.id}
  title="Send the documents to the accountant?"
  description="This email cannot be recalled."
  consequence="The accountant will receive these documents and entity contact details."
  approveConfig={{ label: 'Send documents', onApprove: approveRequest }}
  onDeny={denyRequest}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Usage [#usage]

```tsx
import { ApprovalCard } from '@commenda/pathfinder/approval-card';

<ApprovalCard
  key={request.id}
  title="Send the documents to the accountant?"
  description="This email cannot be recalled."
  consequence="The accountant will receive these documents and entity contact details."
  approveConfig={{ label: 'Send documents', onApprove: approveRequest }}
  onDeny={denyRequest}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```

## Inline approval [#inline-approval]


```tsx
import { ApprovalCard } from '@commenda/pathfinder/approval-card';

<ApprovalCard
  placement="inline"
  key={request.id}
  title="Send the documents to the accountant?"
  description="This email cannot be recalled."
  consequence="The accountant will receive these documents and entity contact details."
  approveConfig={{ label: 'Send documents', onApprove: approveRequest }}
  onDeny={denyRequest}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Failure and retry [#failure-and-retry]


```tsx
// Return { status: 'failed', message: 'Please try again.' } from the handler to retain this card.
import { ApprovalCard } from '@commenda/pathfinder/approval-card';

<ApprovalCard
  key={request.id}
  title="Send the documents to the accountant?"
  description="This email cannot be recalled."
  consequence="The accountant will receive these documents and entity contact details."
  approveConfig={{ label: 'Send documents', onApprove: approveRequest }}
  onDeny={denyRequest}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Loading [#loading]


```tsx
import { ApprovalCard } from '@commenda/pathfinder/approval-card';

<ApprovalCard
  state={{ status: 'loading' }}
  key={request.id}
  title="Send the documents to the accountant?"
  description="This email cannot be recalled."
  consequence="The accountant will receive these documents and entity contact details."
  approveConfig={{ label: 'Send documents', onApprove: approveRequest }}
  onDeny={denyRequest}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


Reset restores the example. Simulate failure retains the card for retry; no backend request is made.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `consequence` | `string` | required | Required concrete effect of approval; explain reversibility in `description` |
| `approveConfig` | `{ label: string; onApprove: RequestHandler<{ alwaysAllow: boolean; }>; destructive?: boolean; }` | required | Explicit verb, handler receiving `{ alwaysAllow: boolean }`, optional destructive styling |
| `onDeny` | `RequestHandler` | required | Separate denial callback; returns accepted receipt or failure |
| `denyLabel` | `string` | optional | Defaults to Deny |
| `detailsConfig` | `{ label?: string; onOpen: () => void; }` | optional | Optional host-owned detail view |
| `alwaysAllowConfig` | `{ label: string; value: boolean; onValueChange: (value: boolean) => void; }` | optional | Explicit controlled permission, omitted unless supported by the host |
| `title` | `string` | required |  |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `placement` | `"docked" \| "inline"` | optional |  |
| `state` | `RequestState` | optional |  |
| `onDismiss` | `(() => void)` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |

### approveConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `onApprove` | `RequestHandler<{ alwaysAllow: boolean; }>` | Yes |  |
| `destructive` | `boolean` | No |  |

### detailsConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onOpen` | `() => void` | Yes |  |

### alwaysAllowConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `value` | `boolean` | Yes |  |
| `onValueChange` | `(value: boolean) => void` | Yes |  |

### state fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"ready" \| "pending" \| "loading"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"resolved"` | Yes |  |
| `recap` | `ResponseRecapProps` | Yes |  |

### Shared request props [#shared-request-props]

| Prop          | Type                   | Behavior                                                                 |
| ------------- | ---------------------- | ------------------------------------------------------------------------ |
| `title`       | `string`               | Required card title.                                                     |
| `description` | `string`               | Optional supporting text.                                                |
| `placement`   | `'docked' \| 'inline'` | Docked by default; parent controls width and placement                   |
| `state`       | `RequestState`         | Ready, loading skeleton, externally pending, or resolved with a recap    |
| `onDismiss`   | `() => void`           | Temporary dismissal via Not now or scoped Escape; not a submitted answer |
| `className`   | `string`               | Layout override                                                          |

`RequestHandler<T>` returns `{ status: 'accepted', recap: ResponseRecapProps }` or `{ status: 'failed', message: string }`, directly or as a Promise. A thrown error shows a retry message and preserves the draft. The host persists accepted responses; the component displays the returned receipt. `state={{ status: 'resolved', recap }}` restores history. Use a stable request ID as the React key, and change the key when the request changes. External pending is a rendering state; authorization and idempotency remain server responsibilities.

**REQUEST-01:** Docked tray uses pearl100, a raised shadow, radius16 and a white radius10 inset with 16px padding. Header40, footer at least44; controls wrap on narrow screens.

**REQUEST-02:** The parent places the request 12px above Composer at the same width. Inline requests are flat and fill their message column. Escape only temporarily dismisses; no global listener is installed.

**REQUEST-03:** Reading content does not animate. Existing Button and Popover motion respects reduced motion. Pending retains the draft and exposes a polite status. Acceptance never precedes the host result.

## Design rules [#design-rules]

- **APPROVAL-01:** Show the action, its consequence, and reversibility before requesting consent. No numeric/global approval shortcut.
- **APPROVAL-02:** Deny and approval are distinct explicit outcomes. Escape and Not now temporarily dismiss; they never deny or approve.
- **APPROVAL-03:** Always allow starts from the host's actual permission state. Accepted approval and denial receipts use `kind: 'approval'` with actor and timestamp. The server owns authorization and must validate the request again before executing it.

A typed composer reply while approval is active follows the Figma denial path. Implement that mapping in the application orchestrator, not as an arbitrary keyboard handler on ApprovalCard. Do not translate temporary dismissal, network failure, or a closed browser tab into consent.

## Integration and accessibility [#integration-and-accessibility]

Buttons have explicit names and keyboard focus. No network transport or AI SDK provider is required. Requests, tool execution, permission checks, durable outcomes and composer coordination stay in the application. See [AI content integration](/docs/guides/ai-content) for migration mappings; application migration is outside this build.


---

# Attachment group

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/attachment-group
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=569-26690

```tsx
import { AttachmentGroup } from '@commenda/pathfinder/attachment-group';

<AttachmentGroup
  items={attachments}
  onRemove={removeAttachment}
  onPreview={openPreview}
  maxRows={3}
/>;
```


## Usage [#usage]

```tsx
import { AttachmentGroup } from '@commenda/pathfinder/attachment-group';

<AttachmentGroup
  items={attachments}
  maxRows={3}
  onRemove={removeAttachment}
  onRetry={retryUpload}
  onPreview={openPreview}
  getPreview={(item) => ({ content: <FileSummary attachment={item} /> })}
/>;
```

The group measures actual pill widths and reserves room for +N within the last permitted row. It recomputes after container resize, font loading, or item changes. IDs must be unique and stable. Input order is preserved; grouping files into folder records is application-owned.

## Sent-message alignment [#sent-message-alignment]

`align="end"` aligns toward the inline end and suppresses all removal controls, including overflow checkboxes. Preview actions continue to work. Place the group 6px above the message bubble in the conversation composition.


```tsx
<AttachmentGroup
  items={attachments}
  align="end"
  onPreview={openPreview}
/>;
```


## Overflow behavior [#overflow-behavior]

+N opens a named Popover listing hidden attachments. Uncheck an item to request removal in an editable group; select its pill to preview or retry. This uses a Popover with Checkbox rather than the action-only Dropdown so selection and preview remain distinct controls. The app updates `items` after removal; if it rejects the request, the attachment remains selected.

The initial server render provides +N access; measurement takes place before the client paints. Hidden measurement labels are excluded from the accessibility tree and contain no focusable controls.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly AttachmentItem[]` | required | Required; empty arrays render nothing |
| `align` | `"start" \| "end"` | optional | Start default; end is a non-removable sent group |
| `maxRows` | `1 \| 2 \| 3` | optional | Default 3; +N stays inside this row budget |
| `onPreview` | `((item: AttachmentItem) => void)` | optional | Same lifecycle callbacks as Attachment |
| `onRetry` | `((item: AttachmentItem) => void)` | optional | Same lifecycle callbacks as Attachment |
| `onRemove` | `((item: AttachmentItem) => void)` | optional | Same lifecycle callbacks as Attachment |
| `getPreview` | `((item: AttachmentItem) => AttachmentProps["previewConfig"])` | optional | Optional per-item hover/focus preview |
| `label` | `string` | optional | Accessible group name; defaults to Attachments |
| `className` | `string` | optional | Outer layout |

## Design rules [#design-rules]

- **ATTACH-GROUP-01:** Figma 569:26690. Wrap with a 6px gap, cap at three rows, and expose every remaining item through +N. Never clip a fourth row of keyboard-focusable items.
- **ATTACH-GROUP-02:** Composer alignment enables removal when supplied; sent alignment removes editing controls but retains preview.
- Retain failed items and their retry action. Width calculations use original labels and update when item state changes.

## Migration notes [#migration-notes]

Existing `{ key, fileName, mimeType, fileRef }` arrays map to AttachmentItem without changing persisted data. Keep existing folder aggregation before the group. Overflow, measurement, and keyboard management are handled inside Pathfinder.


---

# Attachment

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/attachment
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=569-26294

```tsx
import { Attachment } from '@commenda/pathfinder/attachment';

<Attachment
  item={{ id: 'pdf', filename: 'GST F5 return.pdf' }}
  onPreview={openPreview}
  onRemove={removeAttachment}
/>;
```


## Usage [#usage]

```tsx
import { Attachment } from '@commenda/pathfinder/attachment';

<Attachment
  item={{
    id: 'filing-pdf',
    filename: 'GST F5 return.pdf',
    mediaType: 'application/pdf',
  }}
  onPreview={openPreview}
  onRemove={removeAttachment}
  onRetry={retryUpload}
/>;
```

The application owns uploads, cancellation, retry, storage URLs, and viewer content. Callbacks receive the original item with its stable ID. Updating an item's `upload` value changes the pill without replacing its identity.

## Upload lifecycle [#upload-lifecycle]

Use `upload: { status: 'uploading', progress: 42 }` for measured progress, `progress: null` for indeterminate progress, and `{ status: 'failed', error: 'Connection lost' }` for failure. Omit `upload`, or set its status to `ready`, after success. Failed uploads remain visible; clicking retries only when `onRetry` is supplied. Set the uploading state promptly when retry begins.

## Sent attachments [#sent-attachments]

Omit `onRemove` after sending. Hover previews and the main preview action remain available. Images use the image file-type icon in the pill; the actual picture belongs in the preview.


```tsx
<Attachment item={attachment} onPreview={openPreview} />;
```


## Preview composition [#preview-composition]

`previewConfig={{ content: <FileSummary />, isLoading }}` supplies the hover/focus preview. `onPreview` can open Pathfinder's Sheet or your existing viewer. No PDF viewer, fetcher, or file URL resolver is bundled. The example uses a Sheet with app-supplied content.

## Validate before upload [#validate-before-upload]

```tsx
import { AttachmentValidation } from '@commenda/pathfinder/attachment';

const result = AttachmentValidation.validate(
  selectedFiles,
  { accept: ['.pdf', 'image/*'], maxBytes: 10_000_000, maxCount: 10 },
  existingAttachments.length
);
// Start uploads for result.accepted.
// Summarize result.rejected in one application-owned Toast.
```

Validation preserves file objects and selection order. Rejections contain `file` and `reasons` (`type`, `size`, `count`). Extensions are case-insensitive, size limits are inclusive, and count includes existing attachments plus accepted candidates. File extensions can be checked when browsers omit MIME metadata. This is pre-upload feedback; the server must enforce its own upload constraints.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `item` | `AttachmentItem` | required | Required stable `id` and original `filename`; optional `mediaType`, `url`, and byte `size` |
| `onPreview` | `((item: AttachmentItem) => void)` | optional | Ready pill activation; host opens its viewer |
| `onRetry` | `((item: AttachmentItem) => void)` | optional | Failed pill activation; host performs retry |
| `onRemove` | `((item: AttachmentItem) => void)` | optional | Separate remove control, including during uploads |
| `previewConfig` | `{ content: ReactNode; isLoading?: boolean; }` | optional | Optional host-owned preview content |
| `className` | `string` | optional | Outer pill styling |

### previewConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | `ReactNode` | Yes |  |
| `isLoading` | `boolean` | No |  |

## Design and accessibility rules [#design-and-accessibility-rules]

- **ATTACH-01:** Figma 569:26294. Height 28px, radius 6px, 0.5px pearl-300 border, Label/12 Strong. Keep the original filename and extension; truncate at 240px with full name available to assistive technology and native hover text.
- **ATTACH-02:** Uploading replaces the file icon with ProgressRing. Failure uses StatusFailed, a 1px red-300 border and red-800 text. Keep failures in the list; a Toast must not replace them.
- **ATTACH-03:** Removal is a separate named button. The host cancels outstanding upload work and ignores stale completion results after removal.
- **ATTACH-04:** These are user-added inputs. Agent-returned files are artifacts and belong to the output components in a later phase.
- Preview and retry use native buttons with keyboard activation. Removal never triggers preview. Existing Popover and Sheet primitives supply focus and reduced-motion behavior.

## Migration notes [#migration-notes]

Map existing `key` to `id`, `fileName` to `filename`, and `mimeType` to `mediaType`. Keep opaque `fileRef` resolution inside your `onPreview` or preview-content adapter; do not treat it as a public URL. Existing per-item callbacks can be delegated by ID. Actual consumer migration is out of scope.


---

# Avatar

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/avatar
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=408-2

```tsx
import { Avatar } from '@commenda/pathfinder/avatar';

export const AvatarDefault = () => (
  <Avatar
    identity={{ kind: 'person', userId: 'priya', name: 'Priya Shah' }}
    size={32}
  />
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/avatar`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `identity` | `AvatarIdentity` | required | Required discriminated person, organization, or logo object |
| `size` | `AvatarSize` | optional | 24 |
| `label` | `string` | optional | Optional accessible-name override/localized fallback |
| `decorative` | `boolean` | optional | false; true suppresses name and tooltip |
| `tooltipConfig` | `false \| { label?: string; }` | optional | Name tooltip enabled; false when visible copy already names it |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### identity fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"person"` | Yes |  |
| `userId` | `string` | No |  |
| `name` | `string` | No |  |
| `email` | `string` | No |  |
| `src` | `string` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"organization"` | Yes |  |
| `name` | `string` | Yes |  |
| `src` | `string` | No |  |

#### Option 3

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"logo"` | Yes |  |
| `label` | `string` | Yes |  |
| `artwork` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | Yes |  |

### tooltipConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported.

## Usage rules [#usage-rules]

### Identity structure [#identity-structure]

```ts
type AvatarIdentity =
  | {
      kind: 'person';
      userId?: string;
      name?: string;
      email?: string;
      src?: string;
    }
  | { kind: 'organization'; name: string; src?: string }
  | { kind: 'logo'; label: string; artwork: ReactElement };
```

Person: photo → initials → neutral person icon. Initials use name, then email local-part; grapheme-aware extraction preserves emoji and non-Latin names. Size 16 shows one initial; other sizes show up to two. Image failure keeps the same dimensions and reveals the fallback.

Tone comes from the stable user ID, never name/email. UTF-8 FNV-1a modulo eight chooses clay, apricot, ochre, olive, sage, dusk, plum, or rose using existing token pairs. Without an ID the fallback is neutral. The accessible fallback is “Unknown person”; label can localize it. Organizations use a neutral plate, logos use supplied artwork, legal entities use flags. Commenda's existing short-form mark is `Icons.Interface.CommendaBrand`.

### AvatarGroup [#avatargroup]

| Prop           | Type                                                     | Default / behavior                |
| -------------- | -------------------------------------------------------- | --------------------------------- |
| label          | string                                                   | Required group name               |
| people         | `readonly { id; name?; email?; src? }[]`                 | Stable id also determines tone    |
| size           | 20 or 24 or 32                                           | 24                                |
| surface        | white or canvas                                          | white; determines separating ring |
| overflowConfig | `{ label?(count): string; formatNames?(names): string }` | Localize disclosure and name list |
| unknownLabel   | string                                                   | Unknown person                    |

Three visible people, then +N. Names remain available on hover/focus, and the overflow supports tap. Escape or clicking outside closes the disclosure. Earlier people sit above later ones with a 1.5px surface ring. Empty groups render no fake members; hidden people must be supplied, not just a total count. Use a full people list elsewhere for very large groups.

## Examples [#examples]

### Sizes [#sizes]


```tsx
import { Avatar } from '@commenda/pathfinder/avatar';

export const AvatarSizes = () => (
  <div
    style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 16 }}
  >
    {([16, 20, 24, 32, 40, 64] as const).map((size) => (
      <Avatar
        key={size}
        size={size}
        identity={{ kind: 'person', userId: 'priya', name: 'Priya Shah' }}
      />
    ))}
  </div>
);
```


### Types [#types]


```tsx
import { Icons } from '@commenda/pathfinder';
import { Avatar } from '@commenda/pathfinder/avatar';

export const AvatarTypes = () => (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 16 }}>
    <Avatar
      identity={{ kind: 'person', userId: 'priya', name: 'Priya Shah' }}
      size={40}
    />
    <Avatar identity={{ kind: 'person' }} size={40} />
    <Avatar
      identity={{ kind: 'organization', name: 'Acme Finance' }}
      size={40}
    />
    <Avatar
      identity={{
        kind: 'logo',
        label: 'Commenda',
        artwork: <Icons.Interface.CommendaBrand />,
      }}
      size={40}
    />
  </div>
);
```


### Groups [#groups]


```tsx
import { AvatarGroup } from '@commenda/pathfinder/avatar';

const people = [
  { id: 'priya', name: 'Priya Shah' },
  { id: 'jan', name: 'Jan Kowalski' },
  { id: 'mei', name: 'Mei Tan' },
  { id: 'ana', name: 'Ana Silva' },
  { id: 'sara', name: 'Sara Ali' },
];

export const AvatarGroups = () => (
  <div style={{ display: 'grid', gap: 24 }}>
    {([20, 24, 32] as const).map((size) => (
      <AvatarGroup
        key={size}
        size={size}
        people={people}
        label={`Assignees at size ${String(size)}`}
      />
    ))}
  </div>
);
```


### Fallback [#fallback]


```tsx
import { Avatar } from '@commenda/pathfinder/avatar';

export const AvatarFallback = () => (
  <Avatar
    identity={{
      kind: 'person',
      userId: 'priya',
      name: 'Priya Shah',
      src: '/missing-avatar.png',
    }}
    size={40}
  />
);
```


## Photo [#photo]

An image loads inside the same fixed-size frame, retaining initials if loading fails. The demo portrait is a local copy of the sample provided in Figma (identified there as an Unsplash free-license image). Replace the example URL with your application's image URL.


```tsx
import { Avatar } from '@commenda/pathfinder/avatar';

const portrait = new URL('./images/portrait.png', import.meta.url).href;

export const AvatarPhoto = () => (
  <Avatar
    identity={{
      kind: 'person',
      userId: 'priya',
      name: 'Priya Shah',
      src: portrait,
    }}
    size={64}
  />
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Avatar and AvatarGroup [#avatar-and-avatargroup]

Source: [412:74](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=412-74), group 412:12893, palette 533:26418, docs 414:485.

- `AVATAR-01` — Source: people circular; organization/logo rounded plate, radii5/6/8/10/12/20 for sizes16/20/24/32/40/64. Legal entities use flags. Identity is a person/organization/logo union. Reuse the existing CommendaBrand icon for the short-form mark.
- `AVATAR-02` — Source/Pathfinder: stable user-ID FNV-1a modulo8; UTF-8 and unsigned32 arithmetic. Tone order clay/apricot/ochre/olive/sage/dusk/plum/rose; reuse token pairs. No random tone or name/email hash. Missing user ID is neutral.
- `AVATAR-03` — Source/Pathfinder: photo, then name/email initials, then neutral person. Grapheme-safe uppercase initials, one at16 and up to two otherwise. Dimensions stay reserved on image failure. Logo slots are10/12/14/18/22/36 at the six sizes, on white; neutral-person artwork is12/12/16/16/20/33.6. Full accessible name or localized fallback; decorative avatars suppress tooltip and repeated naming.
- `AVATAR-04` — Source: show three people then +N; tooltip names hidden people; group sizes20/24/32. Earlier people stack above later ones. 1.5 surface-color rings separate overlapping avatars. Do not supply count without identities.
- `AVATAR-05` — Pathfinder: names reachable on focus; overflow supports touch tap, outside press, and Escape. Localize overflow label/name list and unknown identity copy. No action semantics on ordinary avatars. Large groups need a full people list in the owning interface.

### Source discrepancies and implementation decisions [#source-discrepancies-and-implementation-decisions]


---

# Badge

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/badge
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=240-2

```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeDefault = () => <Badge label="Filed" tone="success" />;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/badge`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required; conveys meaning independently of color |
| `tone` | `BadgeTone` | optional | neutral |
| `size` | `"sm" \| "md"` | optional | sm: 20 high; md: 24 high |
| `indicatorConfig` | `{ type: "dot"; } \| { type: "status"; status: StatusKind; }` | optional | Optional; dot and status icon are mutually exclusive |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### indicatorConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"dot"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"status"` | Yes |  |
| `status` | `"failed" \| "completed" \| "to-do" \| "scheduled" \| "in-progress" \| "in-review" \| "canceled" \| "blocking" \| "blocked-by" \| "needs-attention"` | Yes |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported.

## Usage rules [#usage-rules]

Badges never remove a value, navigate, or trigger actions. Use Tag for user-chosen values and Button/link for interactions. Static badges do not create live regions.

The application maps domain statuses to label, tone, and optional existing lifecycle icon. Pathfinder does not infer status from English text or depend on filing enums. Keep labels to one or two words in sentence case. Small badges use a 12px status icon, medium uses the existing 16px artwork scaled to its authored 14px slot. Text wraps for unexpected long translations without clipping the meaning.

## Examples [#examples]

### Tones [#tones]


```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeTones = () => (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
    <Badge label="Draft" />
    <Badge label="In review" tone="info" />
    <Badge label="Filed" tone="success" />
    <Badge label="Due soon" tone="warning" />
    <Badge label="Overdue" tone="error" />
  </div>
);
```


### Sizes [#sizes]


```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeSizes = () => (
  <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
    <Badge label="Filed" tone="success" size="sm" />
    <Badge label="Filed" tone="success" size="md" />
  </div>
);
```


### Indicators [#indicators]


```tsx
import { Badge } from '@commenda/pathfinder/badge';

export const BadgeIndicators = () => (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
    <Badge label="Due soon" tone="warning" indicatorConfig={{ type: 'dot' }} />
    <Badge
      label="Filed"
      tone="success"
      indicatorConfig={{ type: 'status', status: 'completed' }}
    />
    <Badge
      label="In progress"
      tone="info"
      size="md"
      indicatorConfig={{ type: 'status', status: 'in-progress' }}
    />
  </div>
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Badge [#badge]

Source: [240:123](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=240-123), anatomy 242:311, guidance 242:344.

- `BADGE-01` — Source: system-reported status, read-only. User-picked values belong to Tag; actions belong to Button/link. No removal, click, loading, disabled, or automatic live-region behavior.
- `BADGE-02` — Source: label conveys meaning without color; neutral/info/success/warning/error; optional 6px dot or lifecycle icon, never both. sm 20/radius4/padding6/Label12 Strong/icon12; md 24/radius6/padding8/Label13 Strong/icon14; gap6, no border. Scale existing 16 artwork for the 14 slot, not a duplicate SVG download.
- `BADGE-03` — Source/Pathfinder: one domain mapping owned by the application. One or two words, sentence case. Neutral pearl-200/900; semantic 100 fills and 800/900 copy. Unexpected long labels wrap without clipping meaning.


---

# Banner

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/banner
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=299-282

```tsx
import { Banner } from '@commenda/pathfinder/banner';
<Banner
  tone="info"
  description="Review the filing details before submitting."
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Banner } from '@commenda/pathfinder/banner';
<Banner
  tone="info"
  description="Review the filing details before submitting."
/>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `description` | `string` | required | Required |
| `title` | `string` | optional | Optional; unavailable for announcement |
| `tone` | `FeedbackTone \| "announcement"` | conditional | neutral |
| `actionConfig` | `FeedbackAction` | optional | One link; secondary button for announcement |
| `dismissConfig` | `DismissConfig` | optional | Optional close control |
| `open` | `boolean` | conditional | Controlled / uncontrolled; true initially |
| `defaultOpen` | `boolean` | optional | Controlled / uncontrolled; true initially |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Required with open |
| `announcement` | `FeedbackAnnouncement` | optional | auto |
| `className` | `string` | optional | Additional classes for the component root. |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onDismiss` | `(() => void)` | No |  |

Place below the breadcrumb at the top of the content card. Use one banner at a time for account or product context, never a single record. Announcement centers the message and omits icon and title. Copy wraps on narrow screens. Dismissal follows Alert’s controlled-state and completion-callback rules; nothing expires automatically.

### Actions [#actions]

`FeedbackAction` requires a label and exactly one of `onClick` (command) or `href` (native navigation). Commands support `disabled`, `disabledReason`, `loadingConfig`, and `leadingIcon`; navigation supports `target`, `rel`, and `leadingIcon`. The application owns async work and retry state.

## Examples [#examples]

### Tones [#tones]


```tsx
<>
  {(['neutral', 'info', 'success', 'warning', 'error'] as const).map((tone) => (
    <Banner
      key={tone}
      tone={tone}
      description="Review the filing details before submitting."
    />
  ))}
</>;
```


### Actions [#actions-1]


```tsx
<Banner
  tone="info"
  description="Review the filing details before submitting."
  actionConfig={{ label: 'Review filing', onClick: onReviewFiling }}
/>;
```


### Announcement [#announcement]


```tsx
<Banner
  tone="announcement"
  description="Review the filing details before submitting."
  actionConfig={{ label: 'Review filing', onClick: onReviewFiling }}
/>;
```


### Dismissible [#dismissible]


```tsx
<Banner
  tone="info"
  description="Review the filing details before submitting."
  dismissConfig={{}}
/>;
```


Read the [design guidance](/docs/components/banner#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Alert and Banner — 299:2 [#alert-and-banner--2992]

- **ALERT-01:** Persistent, contextual feedback beside the form, table or figure it concerns. Never auto-dismiss. No dismissConfig produces a callout that stays until the owner removes it. Field errors remain on fields; form alerts summarize them.
- **ALERT-02:** Title states what happened without a period; description states the next step. Aim for two lines, but never clip essential text. At most a secondary small Button for recovery plus a link for more information. Passing confirmations use Toast.
- **ALERT-03:** Neutral is a state, info is news, success is completion, warning is an approaching issue, error is a current problem. Auto announcement maps warnings/errors to alert and info/success to status; neutral stays nonurgent. The explicit announcement prop can override this for the actual event.
- **ALERT-04:** Tinted background and 0.5 px border, radius 8, padding 12 vertical/16 start/12 end, gap 10; icon 16, Label/13 Strong title, Copy/13 body, gap 2. Close uses plain IconButton xs on tinted surfaces.
- **BANNER-01:** Whole-account or product context only; place beneath the breadcrumb across the content card. One at a time, one concise message, one link. The application owns placement and prioritization. Wrap on narrow screens rather than truncate.
- **BANNER-02:** Announcement is the sixth banner tone from node 917:314: blue 100/background, blue 300 bottom border, centered blue 900 copy, no icon or title, optional secondary small Button.
- **FEEDBACK-DISMISS-01:** Dismissal fades and collapses space over 200 ms, ease-out. onOpenChange requests closure immediately; onDismiss follows the collapse after an accepted close. A controlled owner can reject the request. The owner restores focus if needed.
- **FEEDBACK-ACTION-01:** Commands use Button; navigation uses native anchors. Require a label and exactly one of onClick or href. Components choose action appearance; callers own loading, disabled reasons and async behavior.


---

# Breadcrumb

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/breadcrumb
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=346-2

```tsx
import { Breadcrumb } from '@commenda/pathfinder/breadcrumb';
import { GBFlag } from '@commenda/pathfinder/flags/GBFlag';

export const BreadcrumbDefault = () => (
  <Breadcrumb
    label="Entity breadcrumb"
    ancestors={[
      { id: 'entities', label: 'Entities', linkConfig: { href: '#entities' } },
      {
        id: 'acme',
        label: 'Acme UK Ltd',
        leadingIcon: <GBFlag size={16} />,
        linkConfig: { href: '#acme' },
      },
    ]}
    current={{ label: 'Annual report 2027' }}
  />
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/breadcrumb`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `ancestors` | `readonly BreadcrumbAncestor[]` | required | Required; each has id, label, linkConfig, optional leadingIcon |
| `current` | `BreadcrumbCurrent` | required | Required; never a link |
| `label` | `string` | optional | Breadcrumb; names the navigation landmark |
| `pageActionsConfig` | `{ menu: DropdownMenu; label?: string; }` | optional | Optional; trigger defaults to Page actions |
| `overflowLabel` | `string` | optional | Show parent pages |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### current fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `leadingIcon` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | No |  |

### pageActionsConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `menu` | `DropdownMenu` | Yes |  |
| `label` | `string` | No |  |

### pageActionsConfig.menu fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | `DropdownGroup[]` | Yes |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Item IDs/values must be unique and stable.

## Usage rules [#usage-rules]

`linkConfig` requires `href`, with optional `target`, `rel`, and `render(anchorProps)` for Next Link or another anchor-compatible component. Forward all supplied props and the ref. Collapsed items remain real links inside the menu, preserving browser navigation and modified clicks.

Beyond four levels, the component keeps the root, immediate parent, and current page. It derives hidden ancestors; do not maintain a second collapsed list. Labels truncate at 240 and reveal full text on hover/focus when truncated. The current page is not a link. Tabs never add breadcrumb levels. Show entity flags with the existing flag components.

Page actions render only when supplied with a nonempty menu. In a page header, avoid a second visible copy of the current title; the enclosing page still owns a semantic heading.

## Examples [#examples]

### Collapsed [#collapsed]


```tsx
import { Breadcrumb } from '@commenda/pathfinder/breadcrumb';

export const BreadcrumbCollapsed = () => (
  <Breadcrumb
    label="Filing breadcrumb"
    ancestors={['Entities', 'Acme UK Ltd', 'Filings', 'Annual reports'].map(
      (label) => ({
        id: label,
        label,
        linkConfig: { href: `#${encodeURIComponent(label)}` },
      })
    )}
    current={{ label: 'Delaware annual report 2027' }}
  />
);
```


### Actions [#actions]


```tsx
import { useState } from 'react';

import { Breadcrumb } from '@commenda/pathfinder/breadcrumb';

export const BreadcrumbActions = () => {
  const [message, setMessage] = useState('');

  return (
    <div>
      <Breadcrumb
        label="Entity page breadcrumb"
        ancestors={[]}
        current={{ label: 'Annual report 2027' }}
        pageActionsConfig={{
          menu: {
            groups: [
              {
                id: 'page',
                items: [
                  {
                    id: 'duplicate',
                    label: 'Duplicate',
                    type: 'action',
                    onClick: () => {
                      setMessage('Report duplicated');
                    },
                  },
                ],
              },
            ],
          },
        }}
      />
      <output>{message}</output>
    </div>
  );
};
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Breadcrumb [#breadcrumb]

Source: [346:10629](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=346-10629), crumb 346:56, docs 348:309.

- `BREADCRUMB-01` — Source: final crumb is current, not a link. Past four levels retain root and last two. Crumbs are 28 high, side padding 6, radius 6, Label/13 Strong; chevron 12, gap 2. Truncate labels at 240 and expose full names on hover/focus.
- `BREADCRUMB-02` — Source: real names; entities lead with flags. Tabs never add levels. Do not add a redundant Back button or repeat the visible page title below the breadcrumb. The enclosing page supplies its semantic heading.
- `BREADCRUMB-03` — Pathfinder: ancestors require stable IDs and native linkConfig; current is a separate non-link object. Page actions render only for a supplied nonempty menu, with a localized accessible label. Hidden ancestors retain native anchor behavior through recursive Dropdown link items.


---

# Button

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/button
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=44-2

```tsx
'use client';

import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';

const ButtonBasic = () => {
  const [saved, setSaved] = useState(false);

  return (
    <Button
      completionConfig={{ isComplete: saved, label: 'Changes saved' }}
      onClick={() => {
        setSaved(true);
      }}
    >
      Save changes
    </Button>
  );
};

export default ButtonBasic;
```


## Usage [#usage]

```tsx
import { Button } from '@commenda/pathfinder/button';

<Button
  variant="primary"
  loadingConfig={{ isLoading: isSaving, label: 'Saving changes' }}
  completionConfig={{ isComplete: isSaved, label: 'Changes saved' }}
  disabled={!canSave}
  disabledReason="Administrator access required"
  onClick={onSave}
>
  Save changes
</Button>;
```

## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

## Examples [#examples]

### Variants [#variants]


```tsx
'use client';

import { Button } from '@commenda/pathfinder/button';

const ButtonVariants = () => (
  <>
    <Button variant="primary">View details</Button>
    <Button variant="secondary">View details</Button>
    <Button variant="tertiary">View details</Button>
    <Button variant="link">View details</Button>
    <Button variant="link-subtle">View details</Button>
  </>
);

export default ButtonVariants;
```


### Sizes and icons [#sizes-and-icons]


```tsx
'use client';

import { Button } from '@commenda/pathfinder/button';
import { PlusIcon } from '@commenda/pathfinder/icons/PlusIcon';

const ButtonSizes = () => (
  <>
    <Button size="sm" leadingIcon={<PlusIcon />}>
      Add entity
    </Button>
    <Button size="md" leadingIcon={<PlusIcon />}>
      Add entity
    </Button>
    <Button size="lg" leadingIcon={<PlusIcon />}>
      Add entity
    </Button>
  </>
);

export default ButtonSizes;
```


### Loading and completion [#loading-and-completion]


```tsx
'use client';

import { Button } from '@commenda/pathfinder/button';

const ButtonFeedback = () => (
  <>
    <Button loadingConfig={{ isLoading: true, label: 'Saving changes' }}>
      Save changes
    </Button>
    <Button completionConfig={{ isComplete: true, label: 'Changes saved' }}>
      Save changes
    </Button>
  </>
);

export default ButtonFeedback;
```


### Disabled reason [#disabled-reason]


```tsx
'use client';

import { Button } from '@commenda/pathfinder/button';

const ButtonDisabled = () => (
  <Button disabled disabledReason="Administrator access required">
    Save changes
  </Button>
);

export default ButtonDisabled;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| "tertiary" \| "link" \| "link-subtle"` | conditional | primary |
| `size` | `"sm" \| "md" \| "lg"` | optional | md; 28/32/36px minimum height |
| `destructive` | `boolean` | conditional | false; only primary/secondary/tertiary |
| `loadingConfig` | `LoadingConfig` | optional | Spinner with optional replacement label |
| `completionConfig` | `CompletionConfig` | optional | Explicit success, default check; only non-destructive primary/secondary/tertiary |
| `leadingIcon` | `ReactNode` | optional | Decorative icon slots, 16px at sm/md and 20px at lg |
| `trailingIcon` | `ReactNode` | optional | Decorative icon slots, 16px at sm/md and 20px at lg |
| `disabledReason` | `string` | optional | Prevent activation; explain unavailable actions |
| `className` | `string` | optional | Additional classes for the component root. |

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

### completionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isComplete` | `boolean` | Yes |  |
| `label` | `string` | Yes |  |
| `icon` | `ReactNode` | No |  |

`ButtonProps`, `ButtonBaseProps`, `LoadingConfig` and `CompletionConfig` are exported from root and `/button`.

## Feedback rules [#feedback-rules]

`CONTROL-STATE-01`: Loading ending does not mean success. Set `isComplete` only after application success. Loading wins if both flags are true. Disabled always blocks activation. Loading blocks repeat activation while retaining keyboard focus; the label and busy state remain accessible. Feedback replaces the normal leading icon; the trailing icon remains.

The application owns completion timing. Figma's recipe resets after 1.5 seconds; clear your timer on unmount and reset success before the next request. Errors belong in application feedback. No `status` or `onActionComplete` configuration prop exists.

## Keyboard and labels [#keyboard-and-labels]

Tab focuses the control; Enter/Space activates it. Disabled controls normally leave tab order. A disabled control with a reason remains focusable with `aria-disabled`, an accessible description and a tooltip; activation is blocked. Loading controls remain focusable. Preserve this behavior when composing custom elements.

`BUTTON-COPY-01`: Name the action and object in sentence case: “Export entities”, “Delete version”. Avoid “Submit” and “OK”. Icon-only actions use IconButton. Labels wrap at narrow widths and enlarged text sizes; minimum heights can grow to keep content readable. Unnamed/whitespace-only labels are invalid.

Import `@commenda/pathfinder/styles.css` once at the app root. Event handlers require a client component in Next.js App Router.

For navigation, use a real anchor or Next Link. Base UI Button composition can assign button semantics to an anchor; changing the rendered tag alone does not guarantee link semantics.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Action rules [#action-rules]

- `BUTTON-COPY-01` — Figma: labels name the action and object in sentence case. Use one primary main action; secondary alongside it; tertiary for quiet repeated actions. Add icons only when they add meaning. Navigation uses a real link.

- `CONTROL-STATE-01` — Pathfinder: loadingConfig and completionConfig are explicit application signals. Loading wins over completion; disabled blocks activation. Ending loading never implies success. Applications own the 1.5-second completion reset recipe from Figma.

- `CONTROL-SIZE-01` — Figma: Button and SplitButton sm/md/lg have 28/32/36px visual heights; md default. IconButton adds xs 24. Button icons are 16 through md and 20 at lg; pass size to generated icons to select optical artwork. Link styles have text-sized geometry. Long content can increase minimum height for accessibility.

- `CONTROL-FOCUS-01` — Figma: show focus from keyboard, not pointer click. Button family uses a blue ring separated by a white gap. Open triggers retain hover styling. Disabled reason is a Pathfinder extension: retain action name, expose description, and allow focus without activation where the native wrapper supports it.


---

# Calendar

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/calendar
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=804-5708

Review deadlines across entities, inspect a record without leaving the calendar, and start a filing or task for a specific day.

## Month [#month]


```tsx
import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

const calendarEntities = [
  { id: 'us', label: 'Meridian US Inc.', flag: <USFlag /> },
  { id: 'de', label: 'Meridian GmbH', flag: <DEFlag /> },
];

const calendarEvents: CalendarEvent[] = [
  {
    id: '1',
    title: 'Corporate income tax',
    date: '2026-10-13',
    category: { id: 'direct', label: 'Direct tax', tone: 'amber' },
    entity: calendarEntities[0],
    status: { label: 'Overdue', tone: 'error', appearance: 'overdue' },
    assignee: { kind: 'person', name: 'Priya Shah' },
  },
  {
    id: '2',
    title: 'VAT return Q3',
    date: '2026-10-13',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: calendarEntities[1],
    status: { label: 'In progress', tone: 'info' },
  },
  {
    id: '3',
    title: 'Transfer pricing report',
    date: '2026-10-13',
    category: { id: 'transfer', label: 'Transfer pricing', tone: 'indigo' },
    entity: calendarEntities[1],
    status: { label: 'Filed', tone: 'success', appearance: 'filed' },
  },
  {
    id: '4',
    title: 'Annual report',
    date: '2026-10-13',
    category: { id: 'entity', label: 'Entity compliance', tone: 'purple' },
    entity: calendarEntities[0],
    status: { label: 'Extended', tone: 'neutral', appearance: 'extended' },
  },
  {
    id: '5',
    title: 'Payroll withholding',
    date: '2026-10-13',
    category: { id: 'payroll', label: 'Payroll', tone: 'teal' },
    entity: calendarEntities[0],
    status: { label: 'To do', tone: 'neutral' },
  },
  {
    id: '6',
    title: 'Import declaration',
    date: '2026-10-20',
    category: { id: 'customs', label: 'Customs', tone: 'rose' },
    entity: calendarEntities[1],
    status: { label: 'Due soon', tone: 'warning' },
    assignee: { kind: 'person', name: 'Lucas Moreau' },
  },
  {
    id: '7',
    title: 'Board review',
    date: '2026-10-28',
    category: { id: 'other', label: 'Other', tone: 'neutral' },
    entity: calendarEntities[0],
  },
];

export const CalendarDefault = () => (
  <Calendar
    label="Compliance calendar"
    events={calendarEvents}
    dateConfig={{ today: '2026-10-13' }}
    viewConfig={{ defaultValue: 'month' }}
  />
);
```


Click a filing to inspect its details. October 13 has five records: **2 more** opens all five; choosing a record replaces that list inside the same popup. Escape closes the preview and returns focus to the originating trigger. Today, previous and next navigate the selected month.

The month has five or six weeks. Adjacent-month dates are muted but their events retain their colors. Weekend cells have a quiet background. Today uses the red date badge. At most three chips appear per day.

## Choosing the Component [#choosing-the-component]

| You need to…                                       | Use                                        |
| -------------------------------------------------- | ------------------------------------------ |
| Review records by month or in a chronological list | **Calendar**                               |
| Enter a date, month or date range in a form        | [DatePicker](/docs/components/date-picker) |
| Sort and filter records with many columns          | [Table](/docs/components/table)            |

Calendar owns presentation and interaction. Your application owns records, permissions, status calculations and persistence. Dates represent whole days; time slots, recurrence and drag scheduling are outside this component's contract.

## Usage [#usage]

```tsx
import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';

const events: CalendarEvent[] = [
  {
    id: 'vat-q3',
    title: 'VAT return Q3',
    date: '2026-10-20',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: { id: 'de', label: 'Meridian GmbH' },
    status: { label: 'In progress', tone: 'info' },
  },
];

<Calendar
  label="Compliance calendar"
  events={events}
  dateConfig={{ today: '2026-10-13' }}
/>;
```

Import `@commenda/pathfinder/styles.css` once in the application. No consumer Tailwind compilation is needed. Interactive callbacks belong in a client component in Next.js App Router.

## Agenda [#agenda]


```tsx
import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

const calendarEntities = [
  { id: 'us', label: 'Meridian US Inc.', flag: <USFlag /> },
  { id: 'de', label: 'Meridian GmbH', flag: <DEFlag /> },
];

const calendarEvents: CalendarEvent[] = [
  {
    id: '1',
    title: 'Corporate income tax',
    date: '2026-10-13',
    category: { id: 'direct', label: 'Direct tax', tone: 'amber' },
    entity: calendarEntities[0],
    status: { label: 'Overdue', tone: 'error', appearance: 'overdue' },
    assignee: { kind: 'person', name: 'Priya Shah' },
  },
  {
    id: '2',
    title: 'VAT return Q3',
    date: '2026-10-13',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: calendarEntities[1],
    status: { label: 'In progress', tone: 'info' },
  },
  {
    id: '3',
    title: 'Transfer pricing report',
    date: '2026-10-13',
    category: { id: 'transfer', label: 'Transfer pricing', tone: 'indigo' },
    entity: calendarEntities[1],
    status: { label: 'Filed', tone: 'success', appearance: 'filed' },
  },
  {
    id: '4',
    title: 'Annual report',
    date: '2026-10-13',
    category: { id: 'entity', label: 'Entity compliance', tone: 'purple' },
    entity: calendarEntities[0],
    status: { label: 'Extended', tone: 'neutral', appearance: 'extended' },
  },
  {
    id: '5',
    title: 'Payroll withholding',
    date: '2026-10-13',
    category: { id: 'payroll', label: 'Payroll', tone: 'teal' },
    entity: calendarEntities[0],
    status: { label: 'To do', tone: 'neutral' },
  },
  {
    id: '6',
    title: 'Import declaration',
    date: '2026-10-20',
    category: { id: 'customs', label: 'Customs', tone: 'rose' },
    entity: calendarEntities[1],
    status: { label: 'Due soon', tone: 'warning' },
    assignee: { kind: 'person', name: 'Lucas Moreau' },
  },
  {
    id: '7',
    title: 'Board review',
    date: '2026-10-28',
    category: { id: 'other', label: 'Other', tone: 'neutral' },
    entity: calendarEntities[0],
  },
];

export const CalendarAgenda = () => (
  <Calendar
    label="Upcoming deadlines"
    events={calendarEvents}
    dateConfig={{ today: '2026-10-13' }}
    viewConfig={{ defaultValue: 'agenda' }}
  />
);
```


Agenda groups the selected month's records by date. Entity flags, category and status remain visible. Status, assignee and action slots retain their alignment when a record has no assignee. Actions are available on hover, keyboard focus and touch. Narrow containers move trailing details to a second line.

## Controlled State [#controlled-state]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Calendar, type CalendarView } from '@commenda/pathfinder/calendar';

export const CalendarDataControlled = () => {
  const [month, setMonth] = useState('2026-10');
  const [view, setView] = useState<CalendarView>('agenda');

  return (
    <>
      <Button
        variant="secondary"
        size="sm"
        onClick={() => {
          setMonth('2026-10');
          setView('auto');
        }}
      >
        Reset to October and automatic view
      </Button>
      <Calendar
        label="Controlled deadlines"
        dateConfig={{ today: '2026-10-13' }}
        events={[
          {
            id: 'annual',
            title: 'Annual report',
            date: '2026-10-20',
            category: {
              id: 'entity',
              label: 'Entity compliance',
              tone: 'purple',
            },
            entity: { id: 'us', label: 'Meridian US Inc.' },
          },
        ]}
        monthConfig={{ value: month, onValueChange: setMonth }}
        viewConfig={{ value: view, onValueChange: setView }}
      />
      <output aria-live="polite">
        Application state: {month} · {view}
      </output>
    </>
  );
};
```


The text below the example shows application state. Navigate or change view, then use Reset. This is the pattern for URL state, saved preferences or a parent-owned toolbar.

Use `defaultValue` for internal state with an optional change notification. Use `value` **with** `onValueChange` when the parent owns state. Calendar emits the requested value; it does not override a controlled prop. Supplying both modes is a TypeScript error.

## Responsive View [#responsive-view]


```tsx
import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

const calendarEntities = [
  { id: 'us', label: 'Meridian US Inc.', flag: <USFlag /> },
  { id: 'de', label: 'Meridian GmbH', flag: <DEFlag /> },
];

const calendarEvents: CalendarEvent[] = [
  {
    id: '1',
    title: 'Corporate income tax',
    date: '2026-10-13',
    category: { id: 'direct', label: 'Direct tax', tone: 'amber' },
    entity: calendarEntities[0],
    status: { label: 'Overdue', tone: 'error', appearance: 'overdue' },
    assignee: { kind: 'person', name: 'Priya Shah' },
  },
  {
    id: '2',
    title: 'VAT return Q3',
    date: '2026-10-13',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: calendarEntities[1],
    status: { label: 'In progress', tone: 'info' },
  },
  {
    id: '3',
    title: 'Transfer pricing report',
    date: '2026-10-13',
    category: { id: 'transfer', label: 'Transfer pricing', tone: 'indigo' },
    entity: calendarEntities[1],
    status: { label: 'Filed', tone: 'success', appearance: 'filed' },
  },
  {
    id: '4',
    title: 'Annual report',
    date: '2026-10-13',
    category: { id: 'entity', label: 'Entity compliance', tone: 'purple' },
    entity: calendarEntities[0],
    status: { label: 'Extended', tone: 'neutral', appearance: 'extended' },
  },
  {
    id: '5',
    title: 'Payroll withholding',
    date: '2026-10-13',
    category: { id: 'payroll', label: 'Payroll', tone: 'teal' },
    entity: calendarEntities[0],
    status: { label: 'To do', tone: 'neutral' },
  },
  {
    id: '6',
    title: 'Import declaration',
    date: '2026-10-20',
    category: { id: 'customs', label: 'Customs', tone: 'rose' },
    entity: calendarEntities[1],
    status: { label: 'Due soon', tone: 'warning' },
    assignee: { kind: 'person', name: 'Lucas Moreau' },
  },
  {
    id: '7',
    title: 'Board review',
    date: '2026-10-28',
    category: { id: 'other', label: 'Other', tone: 'neutral' },
    entity: calendarEntities[0],
  },
];

export const CalendarResponsive = () => (
  <Calendar
    label="Responsive calendar"
    events={calendarEvents}
    dateConfig={{ today: '2026-10-13' }}
  />
);
```


The default `auto` view uses Agenda below **900px of container width** and Month at or above it. Choosing Month or Agenda makes that choice persistent. Set a controlled `viewConfig.value` to `auto` to restore automatic behavior. An explicitly selected Month view scrolls within its container on narrow screens.

## Entity Filtering [#entity-filtering]


```tsx
import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

const calendarEntities = [
  { id: 'us', label: 'Meridian US Inc.', flag: <USFlag /> },
  { id: 'de', label: 'Meridian GmbH', flag: <DEFlag /> },
];

const calendarEvents: CalendarEvent[] = [
  {
    id: '1',
    title: 'Corporate income tax',
    date: '2026-10-13',
    category: { id: 'direct', label: 'Direct tax', tone: 'amber' },
    entity: calendarEntities[0],
    status: { label: 'Overdue', tone: 'error', appearance: 'overdue' },
    assignee: { kind: 'person', name: 'Priya Shah' },
  },
  {
    id: '2',
    title: 'VAT return Q3',
    date: '2026-10-13',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: calendarEntities[1],
    status: { label: 'In progress', tone: 'info' },
  },
  {
    id: '3',
    title: 'Transfer pricing report',
    date: '2026-10-13',
    category: { id: 'transfer', label: 'Transfer pricing', tone: 'indigo' },
    entity: calendarEntities[1],
    status: { label: 'Filed', tone: 'success', appearance: 'filed' },
  },
  {
    id: '4',
    title: 'Annual report',
    date: '2026-10-13',
    category: { id: 'entity', label: 'Entity compliance', tone: 'purple' },
    entity: calendarEntities[0],
    status: { label: 'Extended', tone: 'neutral', appearance: 'extended' },
  },
  {
    id: '5',
    title: 'Payroll withholding',
    date: '2026-10-13',
    category: { id: 'payroll', label: 'Payroll', tone: 'teal' },
    entity: calendarEntities[0],
    status: { label: 'To do', tone: 'neutral' },
  },
  {
    id: '6',
    title: 'Import declaration',
    date: '2026-10-20',
    category: { id: 'customs', label: 'Customs', tone: 'rose' },
    entity: calendarEntities[1],
    status: { label: 'Due soon', tone: 'warning' },
    assignee: { kind: 'person', name: 'Lucas Moreau' },
  },
  {
    id: '7',
    title: 'Board review',
    date: '2026-10-28',
    category: { id: 'other', label: 'Other', tone: 'neutral' },
    entity: calendarEntities[0],
  },
];

export const CalendarEntities = () => (
  <Calendar
    label="Entity deadlines"
    events={calendarEvents}
    dateConfig={{ today: '2026-10-13' }}
    entityFilterConfig={{ entities: calendarEntities }}
    viewConfig={{ defaultValue: 'agenda' }}
  />
);
```


Empty selected IDs mean all entities. Choose one entity to remove its repeated name from agenda metadata; flags remain. Filter selection survives month and view changes. The optional configuration follows Pathfinder's `value/onValueChange` or `defaultValue` pattern. Supply the complete available entity choices and stable IDs.

## Categories and Statuses [#categories-and-statuses]

Category and lifecycle status are independent. The examples use these verified Figma bar modes:

| Category          | `category.tone` |
| ----------------- | --------------- |
| Direct tax        | `amber`         |
| Indirect tax      | `blue`          |
| Transfer pricing  | `indigo`        |
| Entity compliance | `purple`        |
| Payroll           | `teal`          |
| Customs           | `rose`          |
| Other             | `neutral`       |

`status.label` and `status.tone` describe the agenda badge. Optional `status.appearance` controls the compact record presentation:

| Appearance | Behavior                                                    |
| ---------- | ----------------------------------------------------------- |
| `default`  | Neutral chip with category bar                              |
| `overdue`  | Category bar retained; red status mark with Overdue tooltip |
| `filed`    | Muted category bar and text; green Completed mark           |
| `extended` | Dashed neutral outline                                      |

The revised October 12 Figma treatment supersedes older tinted-chip descriptions. The package never infers status from `today`. For example, an extended deadline can retain an “In progress” badge while using `appearance: 'extended'`. A flag is an optional React element; Pathfinder gives it optical 12px dimensions. Use the circular country flag assets.

## Record Previews and Actions [#record-previews-and-actions]


```tsx
import { useState } from 'react';

import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

const calendarEntities = [
  { id: 'us', label: 'Meridian US Inc.', flag: <USFlag /> },
  { id: 'de', label: 'Meridian GmbH', flag: <DEFlag /> },
];

const calendarEvents: CalendarEvent[] = [
  {
    id: '1',
    title: 'Corporate income tax',
    date: '2026-10-13',
    category: { id: 'direct', label: 'Direct tax', tone: 'amber' },
    entity: calendarEntities[0],
    status: { label: 'Overdue', tone: 'error', appearance: 'overdue' },
    assignee: { kind: 'person', name: 'Priya Shah' },
  },
  {
    id: '2',
    title: 'VAT return Q3',
    date: '2026-10-13',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: calendarEntities[1],
    status: { label: 'In progress', tone: 'info' },
  },
  {
    id: '3',
    title: 'Transfer pricing report',
    date: '2026-10-13',
    category: { id: 'transfer', label: 'Transfer pricing', tone: 'indigo' },
    entity: calendarEntities[1],
    status: { label: 'Filed', tone: 'success', appearance: 'filed' },
  },
  {
    id: '4',
    title: 'Annual report',
    date: '2026-10-13',
    category: { id: 'entity', label: 'Entity compliance', tone: 'purple' },
    entity: calendarEntities[0],
    status: { label: 'Extended', tone: 'neutral', appearance: 'extended' },
  },
  {
    id: '5',
    title: 'Payroll withholding',
    date: '2026-10-13',
    category: { id: 'payroll', label: 'Payroll', tone: 'teal' },
    entity: calendarEntities[0],
    status: { label: 'To do', tone: 'neutral' },
  },
  {
    id: '6',
    title: 'Import declaration',
    date: '2026-10-20',
    category: { id: 'customs', label: 'Customs', tone: 'rose' },
    entity: calendarEntities[1],
    status: { label: 'Due soon', tone: 'warning' },
    assignee: { kind: 'person', name: 'Lucas Moreau' },
  },
  {
    id: '7',
    title: 'Board review',
    date: '2026-10-28',
    category: { id: 'other', label: 'Other', tone: 'neutral' },
    entity: calendarEntities[0],
  },
];

export const CalendarPreview = () => {
  const [opened, setOpened] = useState('');

  return (
    <>
      <Calendar
        label="Record previews"
        events={calendarEvents}
        dateConfig={{ today: '2026-10-13' }}
        viewConfig={{ defaultValue: 'agenda' }}
        eventConfig={{
          onOpen: (event) => {
            setOpened(`Navigate to record ${event.id}: ${event.title}`);
          },
          getMenu: (event) => ({
            groups: [
              {
                id: 'actions',
                items: [
                  {
                    id: 'edit',
                    label: 'Edit deadline',
                    type: 'action',
                    onClick: () => {
                      setOpened(`Edit ${event.title}`);
                    },
                  },
                ],
              },
            ],
          }),
        }}
      />
      <output aria-live="polite">{opened}</output>
    </>
  );
};
```


Clicking a record opens its preview. Navigation occurs only through the explicit Open record action. `eventConfig.getMenu(event)` supplies the existing recursive Dropdown menu contract for record actions. All records retain their stable IDs when filtering or navigating.


```tsx
import { Calendar } from '@commenda/pathfinder/calendar';

export const CalendarDataCustomPreview = () => (
  <Calendar
    label="Task calendar"
    dateConfig={{ today: '2026-10-13', weekStartsOn: 1, locale: 'en-GB' }}
    events={[
      {
        id: 'task',
        title: 'Review supporting documents',
        date: '2026-10-13',
        category: { id: 'task', label: 'Task', tone: 'neutral' },
        entity: { id: 'us', label: 'Meridian US Inc.' },
      },
    ]}
    eventConfig={{
      renderPreview: (event) => (
        <div>
          <p>{event.entity.label}</p>
          <p>
            Application-owned task details, attachments and permissions go here.
          </p>
        </div>
      ),
    }}
  />
);
```


`renderPreview(event)` replaces the default metadata body. Calendar retains the accessible popup title, close control and focus return. Applications own authorization and save flows. Keep critical information readable without relying on color or a tooltip.

## Create on a Date [#create-on-a-date]


```tsx
import { useState } from 'react';

import { Calendar, type CalendarEvent } from '@commenda/pathfinder/calendar';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

const calendarEntities = [
  { id: 'us', label: 'Meridian US Inc.', flag: <USFlag /> },
  { id: 'de', label: 'Meridian GmbH', flag: <DEFlag /> },
];

const calendarEvents: CalendarEvent[] = [
  {
    id: '1',
    title: 'Corporate income tax',
    date: '2026-10-13',
    category: { id: 'direct', label: 'Direct tax', tone: 'amber' },
    entity: calendarEntities[0],
    status: { label: 'Overdue', tone: 'error', appearance: 'overdue' },
    assignee: { kind: 'person', name: 'Priya Shah' },
  },
  {
    id: '2',
    title: 'VAT return Q3',
    date: '2026-10-13',
    category: { id: 'indirect', label: 'Indirect tax', tone: 'blue' },
    entity: calendarEntities[1],
    status: { label: 'In progress', tone: 'info' },
  },
  {
    id: '3',
    title: 'Transfer pricing report',
    date: '2026-10-13',
    category: { id: 'transfer', label: 'Transfer pricing', tone: 'indigo' },
    entity: calendarEntities[1],
    status: { label: 'Filed', tone: 'success', appearance: 'filed' },
  },
  {
    id: '4',
    title: 'Annual report',
    date: '2026-10-13',
    category: { id: 'entity', label: 'Entity compliance', tone: 'purple' },
    entity: calendarEntities[0],
    status: { label: 'Extended', tone: 'neutral', appearance: 'extended' },
  },
  {
    id: '5',
    title: 'Payroll withholding',
    date: '2026-10-13',
    category: { id: 'payroll', label: 'Payroll', tone: 'teal' },
    entity: calendarEntities[0],
    status: { label: 'To do', tone: 'neutral' },
  },
  {
    id: '6',
    title: 'Import declaration',
    date: '2026-10-20',
    category: { id: 'customs', label: 'Customs', tone: 'rose' },
    entity: calendarEntities[1],
    status: { label: 'Due soon', tone: 'warning' },
    assignee: { kind: 'person', name: 'Lucas Moreau' },
  },
  {
    id: '7',
    title: 'Board review',
    date: '2026-10-28',
    category: { id: 'other', label: 'Other', tone: 'neutral' },
    entity: calendarEntities[0],
  },
];

export const CalendarCreation = () => {
  const [message, setMessage] = useState(
    'Click a day background or use Add filing.'
  );

  return (
    <>
      <Calendar
        label="Create deadlines"
        events={calendarEvents}
        dateConfig={{ today: '2026-10-13' }}
        viewConfig={{ defaultValue: 'month' }}
        entityFilterConfig={{ entities: calendarEntities }}
        addConfig={{
          actions: [
            {
              id: 'filing',
              label: 'Add filing',
              onAction: ({ date }) => {
                setMessage(`Open the filing form with due date ${date}.`);
              },
            },
            {
              id: 'task',
              label: 'Add task',
              onAction: ({ date }) => {
                setMessage(`Open the task form with due date ${date}.`);
              },
            },
          ],
        }}
      />
      <output aria-live="polite">{message}</output>
    </>
  );
};
```


Click a day background or its plus affordance to choose an action. A temporary New chip appears while the menu is open; cancellation removes it. Each callback receives `{ date, entityIds }`. Clicking an existing record never invokes creation.

The toolbar uses the first action as its default and puts alternatives in a SplitButton. Toolbar creation uses the supplied business-local today; day creation uses the clicked date, including adjacent-month cells. The app opens the form and persists a new event. Calendar does not insert optimistic records automatically.

## API Loading and Recovery [#api-loading-and-recovery]


```tsx
import { useEffect, useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import {
  Calendar,
  type CalendarEvent,
  type CalendarVisibleRange,
} from '@commenda/pathfinder/calendar';

export const CalendarDataDefault = () => {
  const [range, setRange] = useState<CalendarVisibleRange>();
  const [response, setResponse] = useState<{
    key: string;
    events: CalendarEvent[];
  }>();
  const [failed, setFailed] = useState(false);
  const key = range ? `${range.start}/${range.end}` : '';
  useEffect(() => {
    if (!range || failed) return;
    const timer = setTimeout(() => {
      setResponse({
        key: `${range.start}/${range.end}`,
        events: [
          {
            id: range.month,
            title: 'API-loaded deadline',
            date: `${range.month}-15`,
            category: { id: 'tax', label: 'Direct tax', tone: 'amber' },
            entity: { id: 'company', label: 'Meridian US Inc.' },
          },
        ],
      });
    }, 500);

    return () => {
      clearTimeout(timer);
    };
  }, [range, failed]);

  return (
    <>
      <Button
        variant="secondary"
        size="sm"
        onClick={() => {
          setFailed(true);
        }}
      >
        Simulate API failure
      </Button>
      {range && (
        <p>
          Requested dates: {range.start} through {range.end} ({range.view}).
        </p>
      )}
      <Calendar
        label="API deadlines"
        dateConfig={{ today: '2026-10-13' }}
        events={response?.key === key ? response.events : []}
        onVisibleRangeChange={setRange}
        stateConfig={{
          isLoading: !failed && response?.key !== key,
          error: failed
            ? {
                message: 'Could not load deadlines.',
                onRetry: () => {
                  setResponse(undefined);
                  setFailed(false);
                },
              }
            : undefined,
        }}
      />
    </>
  );
};
```


This example simulates a request, discards obsolete results, and exposes failure/retry. Navigate rapidly or click Simulate API failure. Replace its timer with your query client or `fetch` and `AbortController`.

`onVisibleRangeChange` reports inclusive `{ start, end, month, view }`. Month includes adjacent grid dates; Agenda reports the selected month's first and last dates. Include selected entity IDs in the application query key. Cancel stale requests and only pass results belonging to the current key. Do not turn loading or failed responses into an empty event array without the corresponding `stateConfig`.

## Empty State [#empty-state]


```tsx
import { Calendar } from '@commenda/pathfinder/calendar';

export const CalendarDataEmpty = () => (
  <Calendar
    label="Empty calendar"
    events={[]}
    dateConfig={{ today: '2026-10-13' }}
    stateConfig={{ emptyContent: 'No deadlines match your current entities.' }}
  />
);
```


`stateConfig.emptyContent` explains an empty month or current entity filter. Month retains its date grid so creation remains available. Loading and retryable errors take precedence over empty content.

## API Reference [#api-reference]

Import `CalendarProps`, `CalendarEvent`, `CalendarEntity`, `CalendarView`, `CalendarTone`, `CalendarVisibleRange`, `CalendarAddContext` and `CalendarAddAction` from `@commenda/pathfinder/calendar` or the package root. The public API is one component with direct configuration props; day cells and popup components are internal.

| Prop                      | Type                                                 | Default / ownership                       |
| ------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| `label`                   | `string`                                             | Required accessible region name           |
| `events`                  | `readonly CalendarEvent[]`                           | Required; app owns data and unique IDs    |
| `dateConfig.today`        | `string`                                             | Required `YYYY-MM-DD` business-local date |
| `dateConfig.locale`       | `string`                                             | `en-US`; dates use Intl formatting        |
| `dateConfig.weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                    | `0` (Sunday)                              |
| `monthConfig`             | `SelectionProps<string>`                             | Today’s `YYYY-MM` month                   |
| `viewConfig`              | `SelectionProps<CalendarView>`                       | `auto`; also `month` or `agenda`          |
| `entityFilterConfig`      | Selection config + `entities`, optional `label`      | Omitted: no filter; empty IDs: all        |
| `eventConfig`             | `renderPreview`, `onOpen`, `getMenu`                 | Default metadata preview                  |
| `addConfig.actions`       | `readonly CalendarAddAction[]`                       | Omitted: read-only calendar               |
| `stateConfig`             | `isLoading`, `loadingLabel`, `error`, `emptyContent` | Ready                                     |
| `onVisibleRangeChange`    | `(range: CalendarVisibleRange) => void`              | App-owned requests                        |
| `className`               | `string`                                             | Root styling only                         |

### Event Records [#event-records]

| Field      | Type                            | Guidance                                                                      |
| ---------- | ------------------------------- | ----------------------------------------------------------------------------- |
| `id`       | `string`                        | Stable and unique across the supplied collection                              |
| `title`    | `string`                        | Full record name; chips truncate, previews expose it                          |
| `date`     | `string`                        | Canonical `YYYY-MM-DD` deadline                                               |
| `category` | `{ id, label, tone }`           | Category identity, readable label and one of the seven bar tones              |
| `entity`   | `{ id, label, flag? }`          | Stable entity identity; optional circular flag element                        |
| `status`   | `{ label, tone?, appearance? }` | Badge content and independent compact-chip treatment                          |
| `assignee` | `PersonIdentity`                | `{ kind: 'person', userId?, name?, email?, src? }`; omission means unassigned |

Input order determines event order within each day. Agenda sorts day groups chronologically. The application should sort its records before passing them if a business-specific priority is required.

### Navigation and Entity Configs [#navigation-and-entity-configs]

| Config               | Fields                                                                   | Behavior                                             |
| -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------- |
| `monthConfig`        | `value`, `onValueChange` **or** `defaultValue`, optional `onValueChange` | Values are `YYYY-MM`                                 |
| `viewConfig`         | Same controlled/uncontrolled shape                                       | `month`, `agenda` or `auto`                          |
| `entityFilterConfig` | Same shape with `readonly string[]`, plus `entities`, optional `label`   | Empty IDs means all; omitted config hides the filter |

`entities` is a readonly array of `{ id, label, flag? }`. The app reconciles selected IDs when its available entities change. Calendar filters the supplied event collection by those IDs; it does not fetch missing records.

### Record Interactions [#record-interactions]

| `eventConfig` field | Signature                                | When to use it                                                    |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| `renderPreview`     | `(event: CalendarEvent) => ReactNode`    | Replace default metadata with a domain-specific preview           |
| `onOpen`            | `(event: CalendarEvent) => void`         | Show Open record and route to the full record when it is pressed  |
| `getMenu`           | `(event: CalendarEvent) => DropdownMenu` | Supply recursive actions; available in Agenda and record previews |

An event click opens its preview; it does **not** call `onOpen`. Action callbacks receive the same record object you supplied. Check permissions before supplying action items, and apply the same checks in your API.

### Creation Config [#creation-config]

`addConfig.actions` is a readonly array of `{ id, label, onAction }`. Its context is:

```tsx
type CalendarAddContext = {
  date: string;
  entityIds: readonly string[];
};
```

The first action is the toolbar default; remaining actions appear in its split menu. Every supplied action appears in the day menu. Omit `addConfig` for a review-only calendar. An empty action array also hides creation controls.

### Loading, Errors and Empty Results [#loading-errors-and-empty-results]

| `stateConfig` field | Type                                        | Behavior                                                                          |
| ------------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| `isLoading`         | `boolean`                                   | Replaces the event content with a named loading status; navigation remains usable |
| `loadingLabel`      | `string`                                    | Defaults to “Loading events…”                                                     |
| `error`             | `{ message: string; onRetry?: () => void }` | Displays the message and an optional Retry action                                 |
| `emptyContent`      | `ReactNode`                                 | Shown when the selected month/filter has no events                                |

Precedence is **loading → error → ready/empty**. On a request failure, clear loading and provide the error. Use empty content only for a successful request with no matching records. Do not pass stale results for a new visible range.

### Visible Range Callback [#visible-range-callback]

```tsx
type CalendarVisibleRange = {
  start: string; // Inclusive YYYY-MM-DD
  end: string; // Inclusive YYYY-MM-DD
  month: string; // YYYY-MM
  view: 'month' | 'agenda'; // Effective view, never 'auto'
};
```

The callback runs after the initial render and when its range or effective view changes. Changing entities alone does not change the date range; include entity state separately in your request key. `auto` can report Agenda initially and then Month after the container is measured, so request cancellation matters.

Dates are canonical date-only values. No timestamps, locale-formatted strings, UTC-midnight conversions or implicit browser clock. Calendar arithmetic does not shift dates across timezones. The supported range is years 1000–9999; boundary grid slots outside that range are blank. Invalid dates throw a descriptive RangeError; validate API data before rendering.

## Keyboard and Accessibility [#keyboard-and-accessibility]

| Key / input                     | Result                                                                     |
| ------------------------------- | -------------------------------------------------------------------------- |
| Tab / Shift+Tab                 | Move through navigation, filters, event triggers and available day actions |
| Enter / Space on an event       | Open its preview                                                           |
| Enter / Space on N more         | Open all events for the day                                                |
| Escape                          | Close the active popup and restore focus to its trigger                    |
| Arrow keys in the view selector | Choose Month or Agenda                                                     |
| Hover / focus a status mark     | Show Completed or Overdue text                                             |

Provide an accessible `label`, meaningful event titles and text status labels. Color is supplementary. Every event remains reachable through its day overflow. The mobile default is Agenda; an explicitly chosen Month view uses internal horizontal scrolling.

## Figma Rules and Decisions [#figma-rules-and-decisions]

- **CALENDAR-001:** Shared toolbar and filter state for both views; named navigation controls and month announcements.
- **CALENDAR-002:** Outside-month text uses pearl-800 instead of the master’s pearl-600 to meet text contrast. Sunday-first default, five/six rows, 120px nominal days, 4px padding, half-pixel rules.
- **CALENDAR-003:** Three chips plus overflow; selecting from a day list replaces its content in one dialog.
- **CALENDAR-004:** 20px chips, 3px bar, 12px circular flag, single-line title. The preview exposes full text.
- **CALENDAR-005:** Revised neutral fills; separate category and lifecycle presentation.
- **CALENDAR-006:** Status tooltip targets are keyboard-focusable siblings, never nested buttons.
- **CALENDAR-007:** Agenda retains status104 / avatar24 / actions24 slots; missing assignments do not shift columns.
- **CALENDAR-008:** Creation forwards the date and entity IDs; a draft is temporary, not saved data.
- **CALENDAR-009:** Enter/Space open previews. Escape/outside dismiss; focus returns to the originating trigger.
- **CALENDAR-010:** Month changes are instant for all input methods, including reduced motion. The toolbar never slides.

Month uses table semantics and native buttons, not an incomplete ARIA grid. Tab traverses interactive records and add targets; arrow keys operate the view selector and existing selection/menu primitives. Mobile defaults to Agenda. No dragging, timed-event scheduling or recurrence engine is included.

Sources: [Calendar rules](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=804-5708), [component masters](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=781-3), [interaction examples](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=790-1134). Revised category modes were verified directly from Figma, including indigo Transfer pricing and teal Payroll.


---

# Card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=938-2

```tsx
import { Badge } from '@commenda/pathfinder/badge';
import { Card } from '@commenda/pathfinder/card';

export const CardDefault = () => (
  <Card
    headerConfig={{
      title: 'Upcoming filings',
      headingLevel: 2,
      description: 'Due in the next 30 days',
      actionConfig: { label: 'View all', href: '#filings' },
    }}
  >
    Delaware annual report <Badge label="Due soon" tone="warning" />
  </Card>
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/card`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `children` | `ReactNode` | required | Required section body |
| `headerConfig` | `CardHeaderConfig` | optional | Optional; heading level defaults to 3 |
| `footerConfig` | `CardFooterConfig` | optional | At least one action required |
| `elevation` | `"flat" \| "raised"` | optional | raised |
| `padding` | `"default" \| "none"` | optional | default: 16 body padding |
| `scrollConfig` | `{ maxHeight: NonNullable<CSSProperties["maxHeight"]>; label: string; }` | optional | Optional explicit, named scrolling region |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `className` | `string` | optional | Additional classes for the component root. |

### headerConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Yes |  |
| `description` | `string` | No |  |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | No |  |
| `actionConfig` | `FeedbackAction` | No |  |

### footerConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primaryAction` | `FeedbackAction` | Yes |  |
| `secondaryAction` | `FeedbackAction` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secondaryAction` | `FeedbackAction` | Yes |  |

Do not supply: `primaryAction`.

### scrollConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `maxHeight` | `NonNullable<Property.MaxHeight<string \| number> \| undefined>` | Yes |  |
| `label` | `string` | Yes |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported.

## Usage rules [#usage-rules]

Card keeps an arbitrary table, list, or form body as children, with direct header/footer configs. Header/footer actions use the established `FeedbackAction` contract: a label and either onClick or href. Primary and secondary action appearance follows the component design. Do not wrap a form/table in a card-wide link.

Body content grows naturally unless scrollConfig is supplied. It becomes a keyboard-reachable scrolling region when it actually overflows. The authored Figma examples contain different height caps; none is imposed globally. Raised cards sit on the canvas, flat cards sit within another surface.

### StatCard [#statcard]

| Prop         | Type                                 | Default / behavior            |
| ------------ | ------------------------------------ | ----------------------------- |
| label        | string                               | Required metric label         |
| value        | string or number                     | Required; zero is preserved   |
| meta         | string                               | Optional comparison/context   |
| changeConfig | `{ label: string; tone: BadgeTone }` | Optional change Badge         |
| elevation    | raised or flat                       | raised                        |
| linkConfig   | `{ href; target?; rel?; render? }`   | Optional native-link behavior |

The application formats currency/numbers and determines whether a change is positive: a negative cost change can be good. Only linked StatCards have a hover affordance. A static section Card remains a content container. Neither component fetches data or hides arbitrary children behind a fabricated loading state.

## Examples [#examples]

### Flat [#flat]


```tsx
import { Card } from '@commenda/pathfinder/card';

export const CardFlat = () => (
  <Card
    elevation="flat"
    headerConfig={{ title: 'Filing details', headingLevel: 2 }}
  >
    <p>Annual report · Delaware</p>
    <p>Due 1 March 2027</p>
  </Card>
);
```


### Footer [#footer]


```tsx
import { useState } from 'react';

import { Card } from '@commenda/pathfinder/card';

export const CardFooter = () => {
  const [saved, setSaved] = useState(false);

  return (
    <Card
      headerConfig={{ title: 'Filing reference', headingLevel: 2 }}
      footerConfig={{
        primaryAction: {
          label: saved ? 'Saved' : 'Save',
          onClick: () => {
            setSaved(true);
          },
        },
        secondaryAction: {
          label: 'Cancel',
          onClick: () => {
            setSaved(false);
          },
        },
      }}
    >
      <label>
        Reference{' '}
        <input aria-label="Filing reference" defaultValue="ANNUAL-2027" />
      </label>
    </Card>
  );
};
```


### Scrolling [#scrolling]


```tsx
import { Card } from '@commenda/pathfinder/card';

export const CardScrolling = () => (
  <Card
    padding="none"
    headerConfig={{ title: 'Upcoming filings', headingLevel: 2 }}
    scrollConfig={{ maxHeight: 160, label: 'Upcoming filing list' }}
  >
    <ul>
      {Array.from({ length: 12 }, (_, index) => (
        <li key={index}>Annual report {2027 + index}</li>
      ))}
    </ul>
  </Card>
);
```


### Stats [#stats]


```tsx
import { StatCard } from '@commenda/pathfinder/card';

export const CardStats = () => (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 16 }}>
    <StatCard
      label="Filed this quarter"
      value="$1,284,500"
      changeConfig={{ label: '+12%', tone: 'success' }}
      meta="vs last quarter"
    />
    <StatCard
      label="Upcoming filings"
      value={12}
      linkConfig={{ href: '#filings' }}
      meta="View all upcoming filings"
    />
    <StatCard label="Overdue" value={0} elevation="flat" />
  </div>
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Card and StatCard [#card-and-statcard]

Source: [938:223](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=938-223), section 938:6, stat 938:182, padding-none 942:38. The Card documentation frame contains placeholder text; it is not a source of confirmed guidance.

- `SURFACE-CARD-01` — Source: white, 0.5 pearl-300 border, radius12. Raised on canvas, flat within surfaces. Section header title/description/one action, divider, body, optional footer. Header padding12/16/12; body16 or none. No arbitrary dashboard/business behavior.
- `SURFACE-CARD-02` — Pathfinder: natural body height by default. scrollConfig explicitly supplies maxHeight and region label; overflow becomes keyboard reachable. Caller-supplied dimensions are an intentional inline-style exception, not additional design tokens.
- `SURFACE-CARD-03` — Source/Pathfinder: static cards have no hover affordance. Section actions remain individual buttons/anchors; no card-wide anchor around arbitrary forms/tables. Footer config requires at least one action, using the existing FeedbackAction contract.
- `SURFACE-CARD-04` — Source/Pathfinder: StatCard is a separate small API with shared surface styles, padding16/gap8/Heading24 and optional Badge change. App formats values and chooses change meaning. linkConfig alone enables native navigation and authored hover/focus behavior; zero is a valid value.

### Source discrepancies and implementation decisions [#source-discrepancies-and-implementation-decisions]


---

# Chain of thought

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/chain-of-thought
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=601-225

```tsx
import { ChainOfThought } from '@commenda/pathfinder/chain-of-thought';

<ChainOfThought
  isStreaming={isReasoningStreaming}
  duration={elapsedSeconds}
  steps={[
    { id: 'summary', type: 'reasoning', content: summary },
    {
      id: toolCallId,
      type: 'tool',
      tool: { name: 'list_entities', status: 'running' },
    },
  ]}
/>;
```


## Usage [#usage]

```tsx
import { ChainOfThought } from '@commenda/pathfinder/chain-of-thought';

<ChainOfThought
  isStreaming={isReasoningStreaming}
  duration={elapsedSeconds}
  steps={[
    { id: 'summary', type: 'reasoning', content: summary },
    {
      id: toolCallId,
      type: 'tool',
      tool: { name: 'list_entities', status: 'running' },
    },
  ]}
/>;
```

## Live activity [#live-activity]


```tsx
import { ChainOfThought } from '@commenda/pathfinder/chain-of-thought';

<ChainOfThought
  isStreaming={isReasoningStreaming}
  duration={elapsedSeconds}
  steps={[
    { id: 'summary', type: 'reasoning', content: summary },
    {
      id: toolCallId,
      type: 'tool',
      tool: { name: 'list_entities', status: 'running' },
    },
  ]}
/>;
```


Use Start/Finish activity to exercise streaming updates. New run resets disclosure intent.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `steps` | `readonly ChainOfThoughtStep[]` | required | Required ordered list with stable unique IDs |
| `isStreaming` | `boolean` | optional | Live label and elapsed summary |
| `duration` | `number` | optional | Live label and elapsed summary |
| `label` | `string` | optional | Live label and elapsed summary |
| `disclosureConfig` | `ActivityDisclosureConfig` | optional | Outer disclosure; each tool has independent configuration |
| `className` | `string` | optional | Layout override |

### disclosureConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | No |  |
| `defaultOpen` | `boolean` | No |  |
| `onOpenChange` | `((open: boolean) => void)` | No |  |

## Step model [#step-model]

```tsx
type ChainOfThoughtStep =
  | { id: string; type: 'reasoning'; content: ReactNode }
  | { id: string; type: 'tool'; tool: ToolCallProps };
```

Update a step in place using the same ID. Several tool steps may be running concurrently; the host determines when the overall reasoning part ends. An empty list creates an empty disclosure without fabricated progress.

## Design rules [#design-rules]

- **CHAIN-01:** IDs must be unique and stable across streaming updates and reordering. Use toolCallId for tool steps.
- **CHAIN-02:** Figma 600:29113 / 600:32905: 12px between prose groups, 4px between consecutive tool rows; preserve source order and do not invent steps.
- **CHAIN-03:** History starts closed, live starts open and closes after the next part plus 1s. Manual expansion stays respected; each nested tool retains its own disclosure.

`disclosureConfig.onOpenChange` reports user toggle requests. A controlled `open` value delegates timing and persistence to the host. Automatic collapse also preserves a panel containing keyboard focus.

## Accessibility and integration [#accessibility-and-integration]

Disclosure buttons support Enter and Space, preserve focus, and expose `aria-expanded`. Payload copy buttons are outside the disclosure trigger. Pointer disclosure uses the existing 200ms height transition; keyboard and reduced-motion interaction are immediate. Long text wraps while code scrolls inside its own region. Use one meaningful ThinkingIndicator status per active response rather than announcing every streamed token or tool payload.

The application owns requests, cancellation, approval, retries, durations, and history persistence. No AI SDK provider is required. See [AI content integration](/docs/guides/ai-content) for migration mappings; consumer migration is outside this phase.


---

# Checkbox

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/checkbox
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-2

```tsx
import { Checkbox } from '@commenda/pathfinder/checkbox';

<Checkbox label="Send me a copy" />;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once at the app root. The stylesheet is precompiled with Tailwind v4; your application does not need Tailwind or source scanning. Event handlers belong in a client component in Next.js App Router.

## Usage [#usage]

```tsx
import { Checkbox } from '@commenda/pathfinder/checkbox';

<Checkbox
  label="Send me a copy"
  description="We email the filing receipt to you as well."
  checked={sendReceipt}
  onCheckedChange={setSendReceipt}
  name="receipt"
  value="email"
/>;
```

| Prop                   | Type                         | Default / behavior                                                              |
| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------- |
| `label`                | `string`                     | Required, visible text and accessible name                                      |
| `hideLabel`            | `boolean`                    | `false`; retains the accessible name for dense/table controls                   |
| `description`          | `string`                     | Optional supporting text, associated with the control                           |
| `checked`              | `boolean`                    | Controlled selection; pair with `onCheckedChange` or `readOnly`                 |
| `defaultChecked`       | `boolean`                    | `false`; initial uncontrolled selection                                         |
| `onCheckedChange`      | `(checked: boolean) => void` | Receives the next boolean only                                                  |
| `indeterminate`        | `boolean`                    | `false`; mixed parent selection, separate from `checked`                        |
| `disabled`             | `boolean`                    | Blocks interaction and submission                                               |
| `disabledReason`       | `string`                     | Visible explanation while disabled, included in accessible description          |
| `readOnly`             | `boolean`                    | Prevents changes while retaining value                                          |
| `required`             | `boolean`                    | Requires selection for form validation                                          |
| `variant`              | `'default' \| 'card'`        | `'default'`; card retains checkbox semantics                                    |
| `details`              | `readonly string[]`          | Optional explanatory bullet lines, intended for cards                           |
| `name`                 | `string`                     | Name used when the control submits its value with a form.                       |
| `value`                | `string`                     | Value submitted when checked; defaults to 'on'.                                 |
| `uncheckedValue`       | `string`                     | Value submitted when unchecked; omitted when not configured.                    |
| `form`                 | `string`                     | ID of the form associated with the control.                                     |
| `id`                   | `string`                     | ID of the underlying form input.                                                |
| `inputRef`             | `Ref<HTMLInputElement>`      | Access to the underlying form input.                                            |
| `className`            | `string`                     | Additional class names for the outer layout.                                    |
| `ref`                  | `Ref<HTMLElement>`           | Access to the interactive root element.                                         |
| Native events and ARIA | Base UI root props           | Typed passthrough; arbitrary children/render overrides are intentionally hidden |

A checkbox saves with a form. Its label is part of the target. `indeterminate` is a parent summary, not a third answer: the application derives it from children and updates the children on change. Do not pass `checked` and `defaultChecked` together. Use positive labels such as “Send me a copy”. A visible description is preferable to a tooltip-only disabled reason for form controls.

The Figma control is one size: a 16px box, 4px radius, 12px check/minus mark and 8px label gap. There is no invented size or cosmetic hover/focus state prop. Checkbox cards reuse the same component with `variant="card"`.

## Examples [#examples]

### Checked, unchecked and mixed [#checked-unchecked-and-mixed]


```tsx
<>
  <Checkbox label="Unchecked" />
  <Checkbox label="Checked" defaultChecked />
  <Checkbox
    label="Some filings selected"
    indeterminate={mixed}
    onCheckedChange={() => setMixed(false)}
  />
</>;
```


### Description [#description]


```tsx
<Checkbox
  label="Send me a copy"
  description="We email the filing receipt to you as well."
/>;
```


### Parent and children [#parent-and-children]


```tsx
const filings = ['Annual filing', 'Quarterly filing', 'Monthly filing'];
const [selected, setSelected] = useState(['Annual filing']);

<>
  <Checkbox
    label="All filings"
    checked={selected.length === filings.length}
    indeterminate={selected.length > 0 && selected.length < filings.length}
    onCheckedChange={(checked) => setSelected(checked ? [...filings] : [])}
  />
  {filings.map((label) => (
    <Checkbox
      key={label}
      label={label}
      checked={selected.includes(label)}
      onCheckedChange={(checked) =>
        setSelected((current) =>
          checked
            ? [...current, label]
            : current.filter((item) => item !== label)
        )
      }
    />
  ))}
</>;
```


### Checkbox card [#checkbox-card]


```tsx
<Checkbox
  variant="card"
  label="Send me a copy"
  description="We email the filing receipt to you as well."
  details={['Due 15 April', 'Includes state apportionment']}
/>;
```


### Disabled states [#disabled-states]


```tsx
<>
  <Checkbox label="Unchecked" disabled />
  <Checkbox label="Checked" defaultChecked disabled />
  <Checkbox label="Some filings selected" indeterminate disabled />
</>;
```


Read the [Figma choice-control rules](/docs/components/checkbox#design-rules) for design guidance, source discrepancies and accessibility requirements.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Checkbox [#checkbox]

Source: [199:2](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-2), variants 199:90, guidance 203:226.

- **CHECKBOX-01** — Use independent checkboxes for choices saved with a form. An immediate setting uses Switch. The label is part of the target. Use positive labels such as “Send me a copy”, not questions.
- **CHECKBOX-02** — Mixed/indeterminate summarizes a parent whose children are partly selected. Activating it selects all its children. It is never a third answer. Applications own the child selection and derive the parent's checked/mixed flags.
- **CHECKBOX-03** — Box 16px, radius 4px, 1px soft-pearl-400 border. Hover uses soft-pearl-500. Checked/mixed uses blue-700 and a white 12px check/minus; hover blue-800. Keyboard focus adds a white 2px gap and blue 2px ring. Disabled uses soft-pearl-100 surface, soft-pearl-300 border and soft-pearl-600 mark/text.
- **CHECKBOX-04** — Label/13 regular sits 8px from the box; Copy/12 description uses soft-pearl-800, 2px below. Child rows indent 24px. Long content wraps and must not clip the box or focus ring.

### Radio and cards [#radio-and-cards]

Source: [199:3](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-3), radio variants 200:46, card variants 201:413, guidance 205:320.

- **RADIO-01** — One choice from two to five visible options. Use Select for longer lists or limited space. A lone boolean option uses Checkbox/Switch. Arrow keys move selection and skip disabled items; Tab enters/leaves the group.
- **RADIO-02** — Prefer a sensible default. Leave the group unanswered only when deliberate choice is required. Never silently choose the first value or replace a removed controlled value. The application reconciles dynamic options.
- **RADIO-03** — Order options by frequency, size or time rather than alphabetically by default. Circle 16px, selected white dot 6px; colors and focus match Checkbox. Group row gap 8px.
- **CARD-01** — Use a card when each option needs title and description. Keep cards in one row equal-height. The “Radio card” Figma collection contains both radio and checkbox controls; Pathfinder exposes `RadioGroup variant="card"` for one choice and `Checkbox variant="card"` for independent choices.
- **CARD-02** — Card padding 16px, control/text gap 12px, radius 8px. Title Label/13 Strong; description Copy/12 with 4px gap. Detail bullets have 2px gap and 4px top padding. Surface remains white when selected; border becomes blue-700. Focus surrounds the whole card. Disabled surface/border/text use soft-pearl-100/300/600. The 320px specimen width adapts to the container.

### Implementation decisions and source differences [#implementation-decisions-and-source-differences]

The complete prop tables are on [Checkbox](/docs/components/checkbox), [RadioGroup](/docs/components/radio-group) and [Switch](/docs/components/switch). Source rule IDs are also kept in the component implementation comments and exported through `llms.txt`, `llms-full.txt` and the Markdown routes.

- **CHOICE-01** — The sheets describe 8px list gaps but some documentation frames place rows 32px apart. Use the documented 8px component-list gap; documentation specimen whitespace is not a new size token.

- **CHOICE-02** — Built-in text is plain, wrapping content. Do not place links, buttons or nested interactive controls inside labels or cards. Disabled reasons are visible descriptions, not tooltip-only explanations on controls removed from keyboard navigation.

- **CHOICE-03** — Visual control size is not the hit target. Coarse-pointer rows provide at least 44px height, while preserving 16px marks and the 36×20px switch track. Cards already exceed this height.

- **CHOICE-04** — Hover/focus are real browser states, not public cosmetic props. Retain native `name`, `value`, `form`, `required`, `readOnly`, disabled semantics and input refs. `hideLabel` preserves the required accessible label.

- **CHOICE-05** — Use Pathfinder's existing Check/Minus optical artwork at 12px. Boxes, circles, tracks and thumbs are interactive primitive geometry, styled with the Figma tokens; they are not flattened screenshots. This keeps focus, RTL and switch movement functional.


---

# Code block

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/code-block
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=596-28365

```tsx
import { CodeBlock } from '@commenda/pathfinder/code-block';

<CodeBlock
  code="SELECT entity, filing FROM filings;"
  language="sql"
  filename="q3_filings.sql"
/>;
```


## Usage [#usage]

```tsx
import { CodeBlock } from '@commenda/pathfinder/code-block';
import '@commenda/pathfinder/styles.css';
import '@commenda/pathfinder/code-font.css';

<CodeBlock code={source} language="sql" filename="q3_filings.sql" />;
```

Load compiled CSS once in your application. The optional code-font stylesheet supplies Geist Mono; without it, the component uses the host's monospace fallback. No app-side Tailwind compilation or syntax stylesheet is needed.

## Examples [#examples]

### Tool request and response [#tool-request-and-response]

Pass the original payload string when exact formatting matters. The component does not parse, prettify, or execute it.


```tsx
<CodeBlock
  variant="payload"
  language="json"
  filename="list_filings"
  code={JSON.stringify({ request, response }, null, 2)}
/>;
```


### Diff [#diff]

Mark one-based **source line positions**. The original code remains unchanged, including when copied. Added and removed lines have both a background and a gutter marker.


```tsx
<CodeBlock
  variant="diff"
  language="json"
  filename="registration.json"
  code={source}
  diffConfig={{ removed: [3], added: [4] }}
/>;
```


### Plain text and unknown languages [#plain-text-and-unknown-languages]

Unsupported languages fall back to readable plain text. Line numbers can be hidden.


```tsx
<CodeBlock
  language="unknown-format"
  code={source}
  lineNumberConfig={{ visible: false }}
/>;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `code` | `string` | required | Required source; copying preserves whitespace and trailing newlines |
| `language` | `string` | optional | `text`; Highlight.js common languages and aliases |
| `filename` | `string` | optional | Optional header label; long names truncate with full native title |
| `variant` | `"code" \| "payload" \| "diff"` | optional | `code` |
| `lineNumberConfig` | `{ visible?: boolean; start?: number; }` | optional | Visible, starts at 1 |
| `showLineNumbers` | `boolean` | optional | Compatibility prop; explicit `lineNumberConfig.visible` wins |
| `diffConfig` | `{ added?: readonly number[]; removed?: readonly number[]; }` | optional | One-based source line positions, independent of displayed starting number |
| `copyConfig` | `CodeCopyConfig` | optional | Copy enabled by default |

### lineNumberConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` | No |  |
| `start` | `number` | No |  |

### diffConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `added` | `readonly number[]` | No |  |
| `removed` | `readonly number[]` | No |  |

### copyConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | No |  |
| `label` | `string` | No |  |
| `copiedLabel` | `string` | No |  |
| `errorLabel` | `string` | No |  |
| `onCopy` | `(() => void)` | No |  |
| `onError` | `((error: Error) => void)` | No |  |

`CodeCopyConfig` supports `enabled`, `label`, `copiedLabel`, `errorLabel`, `onCopy`, and `onError(error)`. Clipboard failure is announced and remains retryable; the success indicator resets after two seconds. Callbacks run after the clipboard outcome.

## Design and accessibility rules [#design-and-accessibility-rules]

- **CODE-01:** White surface, pearl-300 hairline, radius 8, 32px header, 12px body inset, Geist Mono 10/16 without ligatures.
- **CODE-02:** Show line numbers by default. Long source scrolls horizontally; never truncate or collapse code silently.
- **CODE-03:** Copy excludes labels and the gutter. Diff meaning must not rely on color alone.
- **CODE-04:** Payloads remain inert source; unknown languages still render. Highlighting loads after mount and does not block initial content.
- The scroll region is keyboard-focusable. Clipboard outcomes use a polite status announcement.

## Migration notes [#migration-notes]

Existing `code`, `language`, and `showLineNumbers` values can be reused. Replace compound CodeBlock header/copy children with `filename` and `copyConfig`. This is a documented future migration path; no existing consumers are changed. The renderer uses Lowlight/Highlight.js, not Shiki. See the [AI content integration guide](/docs/guides/ai-content).


---

# Composer context

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/composer-context
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=582-1565

```tsx
import { ComposerContext } from '@commenda/pathfinder/composer-context';

<ComposerContext items={contextItems} onRemove={removeContext}>
  {editor}
</ComposerContext>;
```


## Usage [#usage]

```tsx
import { ComposerContext } from '@commenda/pathfinder/composer-context';

<ComposerContext
  items={[
    { id: 'page', label: 'Legal entities', role: 'current' },
    {
      id: 'workflow',
      label: 'Incorporate in the UK',
      role: 'carried',
      removable: true,
    },
  ]}
  onRemove={removeContext}
>
  {editor}
</ComposerContext>;
```

The child is your editor surface. This phase demonstrates the existing TextArea; the AI Composer will be implemented in Phase 3. The wrapper never invents page context, adds it to prompts, or owns the request payload.

## Connector invitation [#connector-invitation]


```tsx
<ComposerContext
  position="bottom"
  connectorConfig={{
    label: 'Connect your tools to Commenda',
    onConnect: openConnectors,
    onDismiss: dismissSuggestion,
  }}
>
  {editor}
</ComposerContext>;
```


Use `position="bottom"` with `connectorConfig`. Its main action opens the application's connector flow; dismiss is independent. Supply existing Pathfinder logos through `logos`. After dismissal, set `connectorConfig={null}`. This removes the invitation and its colored footer while preserving the mounted editor and its draft.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `children` | `ReactNode` | required | Required editor surface |
| `position` | `"top" \| "bottom"` | conditional | Top default; determines the configuration branch |
| `items` | `readonly ComposerContextItem[]` | conditional | Top only: stable `id`, `label`, `role: current \| carried`, optional `removable` |
| `onRemove` | `((id: string) => void)` | optional | Top only; shown only on explicitly removable items |
| `connectorConfig` | `{ label: string; logos?: readonly ReactNode[]; onConnect: () => void; onDismiss?: () => void; } \| null` | conditional | Required for bottom position |
| `className` | `string` | optional | Outer wrapper |

### connectorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `logos` | `readonly ReactNode[]` | No |  |
| `onConnect` | `() => void` | Yes |  |
| `onDismiss` | `(() => void)` | No |  |

## Design and behavior rules [#design-and-behavior-rules]

- **CONTEXT-01:** Figma 582:1565 and 588:27564. Pearl-200 wrapper, top pills inset 12px and separated from the editor by 6px. Current context is white with pearl-1000 text; carried context uses pearl-100 and pearl-800. Pills use Label/12 Strong, radius 6px and a 0.5px border.
- **CONTEXT-02:** Only show context actually supplied by the host. Removal emits the stable ID; the application changes both displayed context and request data.
- **CONTEXT-03:** Bottom connector invitation uses stacked logos and a separate dismiss control. Native buttons preserve Enter/Space activation and visible focus.

## Migration notes [#migration-notes]

Map ChatPanelPill `label` and `onDismiss` to an item and `onRemove(id)`. Keep the existing decision about whether the assistant receives page content in the application. Current/carried presentation is explicit and does not replace stored conversation state.


---

# Composer

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/composer
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=580-28168

```tsx
import { Composer } from '@commenda/pathfinder/composer';

<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
  requestConfig={{ status, onStop: stop }}
/>;
```


## Usage [#usage]

```tsx
import { Composer } from '@commenda/pathfinder/composer';

<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={({ text, attachments, command }) => {
    // Set request status synchronously; catch failures in your request handler.
    sendDraft({ text, attachments, command });
  }}
  requestConfig={{ status, onStop: stop }}
/>;
```

The host owns the draft, uploads, selected skill, and request lifecycle. Composer never starts a network request or clears data. Clear the submitted draft only after acceptance, and avoid clearing text the user has typed since submitting. Handle rejected requests in the application and preserve the draft for retry.

## Standard and hero [#standard-and-hero]

Standard starts with one 20px text line. Hero reserves a 53px editing area. Both grow with content, cap the composer surface at 40dvh, and keep Send reachable while the editor scrolls. The maximum width is 736px; smaller containers fill available width.


```tsx
<Composer
  label="Message"
  size="hero"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
/>;
```


## Skills and API search [#skills-and-api-search]

Type `/` at a word boundary to open skills. Text after the slash filters local labels and descriptions. Arrow keys move through enabled results; Enter selects without sending. Selection removes the query and displays the selected skill as a blue Tag beside the editable text. The submit payload preserves the command separately from plain text; no rich-text document or Vercel message object is required.

```tsx
<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
  commandConfig={{
    items: results,
    selected: selectedSkill,
    onSelect: setSelectedSkill,
    filterMode: 'manual',
    onSearchChange: setQuery,
    isLoading,
  }}
/>
```

Manual mode preserves API ranking and does not filter results again. `onSearchChange` receives the query while open and `null` when closed. Debounce, cancel outdated requests, and supply results only for the current query. Set `isLoading` while results are stale: selection is blocked and previous options are hidden. Empty results cannot accidentally send the query. The following example simulates an API; search for `tax` to receive semantically related results.


```tsx
<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
  commandConfig={{
    items: results,
    selected: skill,
    onSelect: setSkill,
    filterMode: 'manual',
    onSearchChange: setQuery,
    isLoading,
  }}
/>;
```


The selected skill is one token preceding the plain-text draft. This is not an arbitrary inline rich-text mention editor. Shared context comes from the host through `contextConfig`; no undocumented `@` picker is introduced.

## Attachments, mode, and dictation [#attachments-mode-and-dictation]

`attachmentConfig` composes AttachmentGroup above the editor. `onAdd` opens your existing file picker or upload menu; validate with AttachmentValidation before uploading. Pending or failed uploads disable Send until resolved or removed. Removal, retry, previews, cancellation, and URLs remain application-owned.

`toolbar.leading` accepts Mode/Model Select or Dropdown controls. `toolbar.trailing` accepts a dictation IconButton. Render only actions your application supports and pass their disabled states explicitly. Composer does not request microphone permission or connect to a speech service.


```tsx
<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
  attachmentConfig={{
    items: attachments,
    onAdd: openFilePicker,
    onRemove: removeAttachment,
  }}
  toolbar={{
    leading: (
      <Select
        label="Mode"
        hideLabel
        options={modes}
        value={mode}
        onValueChange={setMode}
      />
    ),
    trailing: (
      <IconButton
        label="Dictate message"
        size="sm"
        onClick={startDictation}
      >
        <Microphone01Icon />
      </IconButton>
    ),
  }}
/>;
```


## Context [#context]

Pass ComposerContext's top or bottom configuration through `contextConfig`. Context stays separate from the outgoing text; your host adds any domain identifiers to its request. To dismiss a bottom invitation, retain its position and set `connectorConfig: null`.


```tsx
<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
  contextConfig={{ items: contextItems }}
/>;
```


## Sending and failure [#sending-and-failure]

`submitted` and `streaming` show Stop. Typing remains available, but Enter never queues a message. `ready` and `error` allow an explicit retry when text and attachments are valid. An absent `onStop` disables Stop. Errors belong in the appropriate Attachment, Message, or host notification, with no red composer border.


```tsx
<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submitWithErrorHandling}
  requestConfig={{ status: 'error' }}
/>;
```


## Keyboard and accessibility [#keyboard-and-accessibility]

- Provide a meaningful `label`; the placeholder is not the accessible name.
- `enter` sends with Enter, while Shift+Enter inserts a newline. `mod-enter` sends with Command/Ctrl+Enter and leaves ordinary Enter for newlines.
- IME composition does not submit or choose a skill. Pasted line breaks are preserved.
- Skills use a listbox linked to the textarea, with an active descendant. Focus stays in the editor.
- Escape closes suggestions and stops propagation. It never cancels generation; use Stop. Tab leaves suggestions without choosing a result.
- Disabled state locks the editor and built-in actions. Its visible reason is associated with the editor. Host toolbar controls must also receive disabled state.
- The forwarded ref is the textarea, so selecting a starter prompt can focus it.


```tsx
<Composer
  label="Message"
  value={draft}
  onValueChange={setDraft}
  onSubmit={submit}
  disableConfig={{
    isDisabled: true,
    reason: 'This conversation is archived.',
  }}
/>;
```


## Mobile layout [#mobile-layout]

The host uses a flex column with scrollable conversation history and a footer that stays above the software keyboard. This example listens to `visualViewport.resize`, bounds its height, and includes the bottom safe area. Composer stays in normal document flow. Test the containing application on actual iOS/Android keyboards before release.


```tsx
// Host layout: viewport resize and safe-area padding belong to your chat shell.
<div className="chat-layout">
  <div className="scrollable-history">{messages}</div>
  <footer>
    <Composer
      label="Message"
      value={draft}
      onValueChange={setDraft}
      onSubmit={submit}
    />
  </footer>
</div>;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required accessible editor name |
| `value` | `string` | required | Required controlled draft |
| `onValueChange` | `((value: string) => void)` | required | Required controlled draft |
| `onSubmit` | `((message: ComposerSubmission) => void)` | required | Required; host handles async failures |
| `size` | `"standard" \| "hero"` | optional | `standard` |
| `placeholder` | `string` | optional | `Ask Commenda anything`; mention `/` only when skills are configured |
| `requestConfig` | `{ status: "ready" \| "submitted" \| "streaming" \| "error"; onStop?: () => void; submitLabel?: string; stopLabel?: string; }` | optional | `status`: `ready`, `submitted`, `streaming`, or `error` |
| `attachmentConfig` | `Omit<AttachmentGroupProps, "className" \| "align"> & { onAdd?: () => void; addLabel?: string; }` | optional | Alignment/class controlled internally; default three rows |
| `commandConfig` | `ComposerCommandConfig` | optional | Optional local/manual skill list and controlled selection |
| `contextConfig` | `ComposerContextConfig` | optional | Top context or bottom connector invitation |
| `toolbar` | `{ leading?: ReactNode; trailing?: ReactNode; }` | optional | Application-owned controls |
| `submitShortcut` | `"enter" \| "mod-enter"` | optional | `enter` |
| `disableConfig` | `{ isDisabled: boolean; reason?: string; }` | optional | Optional disabled state and caption |
| `inputProps` | `Pick<TextareaHTMLAttributes<HTMLTextAreaElement>, "autoFocus" \| "id" \| "spellCheck" \| "aria-describedby" \| "onFocus" \| "onBlur" \| "name" \| "autoComplete" \| "maxLength">` | optional | `id`, `name`, `autoFocus`, `autoComplete`, `spellCheck`, `maxLength`, `aria-describedby`, `onFocus`, `onBlur` |
| `className` | `string` | optional | Outer layout and imperative focus |

### requestConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"ready" \| "submitted" \| "streaming" \| "error"` | Yes |  |
| `onStop` | `(() => void)` | No |  |
| `submitLabel` | `string` | No |  |
| `stopLabel` | `string` | No |  |

### commandConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `readonly ComposerCommand[]` | Yes |  |
| `selected` | `ComposerCommand \| null` | Yes |  |
| `onSelect` | `(command: ComposerCommand \| null) => void` | Yes |  |
| `filterMode` | `"local" \| "manual"` | No | Manual mode accepts results as supplied, without applying a second filter. |
| `onSearchChange` | `((query: string \| null) => void)` | No |  |
| `isLoading` | `boolean` | No |  |
| `label` | `string` | No |  |
| `emptyLabel` | `string` | No |  |

### commandConfig.selected fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `description` | `string` | No |  |
| `disabled` | `boolean` | No |  |

### contextConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `readonly ComposerContextItem[]` | Yes |  |
| `onRemove` | `((id: string) => void)` | No |  |
| `position` | `"top"` | No |  |

Do not supply: `connectorConfig`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `position` | `"bottom"` | Yes |  |
| `connectorConfig` | `{ label: string; logos?: readonly ReactNode[]; onConnect: () => void; onDismiss?: () => void; } \| null` | Yes |  |

Do not supply: `items`, `onRemove`.

### contextConfig.connectorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `logos` | `readonly ReactNode[]` | No |  |
| `onConnect` | `() => void` | Yes |  |
| `onDismiss` | `(() => void)` | No |  |

### toolbar fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `leading` | `ReactNode` | No |  |
| `trailing` | `ReactNode` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

`ComposerSubmission` contains `{ text: string; attachments: readonly AttachmentItem[]; command: ComposerCommand | null }`. `ComposerCommand` contains `{ id, label, description?, disabled? }`. IDs must be unique and stable. `ComposerCommandConfig` requires `items`, `selected`, and `onSelect`, with optional `filterMode`, `onSearchChange`, `isLoading`, `label`, and `emptyLabel`.

## Design rules [#design-rules]

- **COMPOSER-01:** Figma 580:28873: 16px inset, 6px gap, 20px radius, pearl400 hairline, soft raised shadow, 736px maximum. Hover/focus border uses blue700.
- **COMPOSER-02:** Send requires nonblank text and ready attachments. Generating changes Send to Stop without locking the draft.
- **COMPOSER-03:** Never clear, silently queue, upload, or execute commands internally.
- **COMPOSER-04:** Respect IME and both keyboard modes. Escape is scoped to suggestions; explicit Stop avoids cancelling a request when dismissing a menu.
- **COMPOSER-05:** Do not render a red error composer. Disabled state explains why in a caption.
- **COMPOSER-06:** Skills use a searchable listbox and blue Tag; toolbar actions use existing Pathfinder controls. Application context is supplied by the host.
- **COMPOSER-07:** Mobile editor text is 16px. The host docks its chat layout above the keyboard and accounts for safe areas; Composer itself does not take over the viewport.

The existing TextArea's field shell is intentionally not reused: it adds a second border, field padding, and an 80px minimum. Composer keeps a private native textarea and reuses AttachmentGroup, ComposerContext, Tag, and IconButton.


---

# Conversation

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/conversation
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=543-2

```tsx
import { Conversation } from '@commenda/pathfinder/conversation';

<Conversation
  messages={messages}
  getMessageKey={(message) => message.id}
  renderMessage={renderMessage}
  footer={<Composer {...composerProps} />}
  announcement="Response complete."
  className="conversation-layout"
/>;
```


## Usage [#usage]

```tsx
import { Conversation } from '@commenda/pathfinder/conversation';
import { Message } from '@commenda/pathfinder/message';

<Conversation
  messages={messages}
  getMessageKey={(message) => message.id}
  renderMessage={(message, { isLast }) => (
    <Message
      from={message.role}
      parts={message.parts}
      getPartKey={getPartKey}
      renderPart={renderPart}
      actionConfig={{
        retry: { isLatest: isLast, onRetry: regenerate },
      }}
    />
  )}
  announcement={turnAnnouncement}
  footer={<Composer {...composerProps} />}
  className="conversation-layout"
/>;
```

Give the container a bounded height or `flex: 1; min-height: 0` inside a bounded flex layout. Conversation owns its scrolling viewport, not the page scroll. Change its React `key` when switching conversation IDs.

## Docked request and recap [#docked-request-and-recap]


```tsx
import { Conversation } from '@commenda/pathfinder/conversation';

<Conversation
  messages={messages}
  getMessageKey={(message) => message.id}
  renderMessage={renderMessage}
  footer={
    <div className="composer-dock">
      {pendingRequest && (
        <QuestionCard {...pendingRequest} onSubmit={saveAnswerAndAppendRecap} />
      )}
      <Composer {...composerProps} />
    </div>
  }
  className="conversation-layout"
/>;
```


The live question sits 12px above Composer. Acceptance appends a stable recap part to the originating reply and removes the docked card. Temporary dismissal keeps the question pending and provides a way to reopen it. Escape belongs to the focused nested overlay first; the request handles it only after the overlay closes. Typing in Composer never activates a question's numeric shortcuts.

## Empty conversation [#empty-conversation]


```tsx
import { Conversation } from '@commenda/pathfinder/conversation';

<Conversation
  messages={[]}
  getMessageKey={getMessageKey}
  renderMessage={renderMessage}
  emptyState={<SuggestedPromptGroup {...suggestions} />}
  className="conversation-layout"
/>;
```


Supply `emptyState` with suggested prompts or introductory content. Message fetching, permissions and transport remain in the host.

## History and stream following [#history-and-stream-following]

Use **Load earlier messages**, scroll into the history, and choose **Append reply** or **Stream chunk**. The viewport follows only within 32px of the bottom. Earlier rows retain their keys and the first visible row retains its offset. **Jump to latest** resumes following. ResizeObserver also handles delayed image/font/content growth. Scroll positioning is immediate and respects reduced-motion users without animated jumps.

`historyConfig` reports loading and an optional inline error. The host guards overlapping loads, keeps previously loaded items, and retries via `onLoadMore`. This component does not virtualize an unbounded history: paginate on the server and profile realistic histories before adding a virtualization layer.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `messages` | `readonly Item[]` | required | Original typed application/SDK objects |
| `getMessageKey` | `((message: Item, index: number) => string)` | required | Stable unique identity across prepend/append |
| `renderMessage` | `((message: Item, context: { index: number; isLast: boolean; }) => ReactNode)` | required | Host maps roles, states and parts |
| `historyConfig` | `{ hasMore: boolean; isLoading: boolean; onLoadMore: () => void; error?: string; }` | optional | App-owned earlier-history loading |
| `emptyState` | `ReactNode` | optional | Empty transcript content |
| `footer` | `ReactNode` | optional | Composer, docked requests and related controls |
| `announcement` | `string` | optional | Concise turn-level live status |
| `label` | `string` | optional | Conversation and transcript accessible names |
| `className` | `string` | optional | Bounded layout; no default fixed height |

### historyConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasMore` | `boolean` | Yes |  |
| `isLoading` | `boolean` | Yes |  |
| `onLoadMore` | `() => void` | Yes |  |
| `error` | `string` | No |  |

## Design rules and integration [#design-rules-and-integration]

- **CONVERSATION-01:** Preserve original objects and keyed part identity. Do not flatten text around tool calls or discard unknown custom parts.
- **CONVERSATION-02:** Do not pull a reader to the bottom while they inspect history. Preserve the visible row during prepend and delayed layout changes.
- **CONVERSATION-03:** The transcript is a keyboard-focusable region, not a per-token live log. Use `announcement` for “Response complete”, “Stopped” or an error once per transition.
- **CONVERSATION-04:** Transport, providers, execution, feedback persistence and message storage remain in the application. Compose existing Pathfinder components through the footer and typed render callbacks.

The API follows the separation in [Vercel AI Elements Conversation](https://elements.ai-sdk.dev/components/conversation) and [Message](https://elements.ai-sdk.dev/components/message), using Pathfinder's direct props instead of requiring compound children. Existing `useChat` messages can pass through unchanged; adapt rendering at the boundary. Migration of the existing application is out of scope. Download/export, virtualization and automatic message trimming are not performed here.


---

# Data grid

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/data-grid
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=506-22089

```tsx
'use client';

import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

const rows = [
  { id: 'revenue', label: 'Revenue', actual: 450000, budget: 420000 },
  {
    id: 'expenses',
    label: 'Operating expenses',
    actual: 185000,
    budget: 190000,
  },
];

const DataGridBasic = () => (
  <DataGrid
    label="Quarterly financial summary"
    rows={rows}
    rowConfig={{ getId: (row) => row.id }}
    rowHeaderConfig={{
      header: 'Line item',
      getLabel: (row) => row.label,
      width: 200,
    }}
    columns={[
      {
        id: 'q1',
        header: 'Q1 2026',
        columns: [
          {
            id: 'actual',
            header: 'Actual',
            align: 'end',
            width: 160,
            cell: (row) => <TableNumberCell value={row.actual} unit="USD" />,
          },
          {
            id: 'budget',
            header: 'Budget',
            align: 'end',
            width: 160,
            cell: (row) => <TableNumberCell value={row.budget} unit="USD" />,
          },
        ],
      },
    ]}
  />
);

export default DataGridBasic;
```


Use DataGrid when readers compare values across periods or entities. Each record supplies a row label and values; the grid preserves that context while navigating cells. Use [Table](/docs/components/table) for searchable record lists with selection and pagination.

## Usage [#usage]

```tsx
'use client';

import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';
```

Import `@commenda/pathfinder/styles.css` once in your application layout. Each example's **Code** tab contains its complete source with formatting and line numbers. Start with stable row IDs, a `rowHeaderConfig`, and value columns; add grouping or editing when needed.

## Grouped headers [#grouped-headers]


```tsx
import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridPatternsDefault = () => {
  const rows = [
    { id: 'revenue', label: 'Revenue', actual: 125400, budget: 120000 },
    { id: 'expenses', label: 'Expenses', actual: 86000, budget: 84000 },
  ];

  return (
    <DataGrid
      label="Nested reporting bands"
      rows={rows}
      rowConfig={{ getId: (row) => row.id }}
      rowHeaderConfig={{ header: 'Line item', getLabel: (row) => row.label }}
      columns={[
        {
          id: 'year',
          header: 'FY 2026',
          columns: [
            {
              id: 'quarter',
              header: 'Q1',
              columns: [
                {
                  id: 'actual',
                  header: 'Actual',
                  width: 160,
                  cell: (row) => (
                    <TableNumberCell value={row.actual} unit="USD" />
                  ),
                },
                {
                  id: 'budget',
                  header: 'Budget',
                  width: 160,
                  cell: (row) => (
                    <TableNumberCell value={row.budget} unit="USD" />
                  ),
                },
              ],
            },
            {
              id: 'total',
              header: 'Total actual',
              width: 160,
              cell: (row) => <TableNumberCell value={row.actual} unit="USD" />,
            },
          ],
        },
        {
          id: 'variance',
          header: 'Variance',
          width: 160,
          cell: (row) => (
            <TableNumberCell
              value={row.actual - row.budget}
              unit="USD"
              tone={row.id === 'expenses' ? 'critical' : 'positive'}
            />
          ),
        },
      ]}
    />
  );
};
```


FY 2026 contains Q1 Actual/Budget and a Total column. Variance sits outside the year. This intentionally mixes header depths: groups span their descendant leaves and shallower branches span the remaining levels.

A group has `{ id, header, columns }`; a value column has an accessor or renderer. Groups recurse, but all IDs must be unique across the tree and every group must contain columns. Use a Total column per period group when the domain supports that aggregate.

## Expandable rows and totals [#expandable-rows-and-totals]


```tsx
import { useState } from 'react';

import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridGuidesDefault = () => {
  interface Account {
    id: string;
    label: string;
    amount: number;
    children?: Account[];
  }

  const rows: Account[] = [
    {
      id: 'expenses',
      label: 'Operating expenses',
      amount: 86000,
      children: [
        { id: 'salary', label: 'Salaries', amount: 70000 },
        { id: 'rent', label: 'Office rent', amount: 16000 },
      ],
    },
  ];
  const [expanded, setExpanded] = useState<readonly string[]>(['expenses']);

  return (
    <DataGrid
      label="Account hierarchy"
      rows={rows}
      rowConfig={{
        getId: (row) => row.id,
        getChildren: (row) => row.children ?? [],
        getSubtotal: (row) => ({
          ...row,
          label: `Total ${row.label.toLowerCase()}`,
        }),
      }}
      rowHeaderConfig={{ header: 'Account', getLabel: (row) => row.label }}
      expansionConfig={{ value: expanded, onValueChange: setExpanded }}
      columns={[
        {
          id: 'amount',
          header: 'Amount',
          width: 240,
          cell: (row) => (
            <TableNumberCell
              value={row.amount}
              unit="USD"
              format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
            />
          ),
        },
      ]}
      totalConfig={{
        label: 'Grand total',
        row: { id: 'total', label: 'Grand total', amount: 86000 },
      }}
    />
  );
};
```


Collapse Operating expenses. The parent now shows its supplied aggregate; expand it to reveal Salaries, Office rent and a subtotal below the children. The grand total remains independent of expansion.

Control expanded IDs with `expansionConfig`. `getChildren` supplies the hierarchy and `getSubtotal` supplies the subtotal record. The app owns every aggregate. Do not add parent aggregates and their children together, or assume averages and ratios are additive.

## Currency and trends [#currency-and-trends]


```tsx
import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridGuidesFormatting = () => {
  const rows = [
    { id: 'revenue', label: 'Revenue', amount: 125400.5, change: 0.12 },
    { id: 'expenses', label: 'Expenses', amount: 86000, change: 0.04 },
    { id: 'other', label: 'Other income', amount: null, change: null },
  ];

  return (
    <DataGrid
      label="Formatted financial values"
      rows={rows}
      rowConfig={{ getId: (row) => row.id }}
      rowHeaderConfig={{ header: 'Line item', getLabel: (row) => row.label }}
      columns={[
        {
          id: 'amount',
          header: 'Amount',
          width: 200,
          cell: (row) => (
            <TableNumberCell
              value={row.amount}
              unit="USD"
              format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
            />
          ),
        },
        {
          id: 'change',
          header: 'Change',
          width: 180,
          cell: (row) => (
            <TableNumberCell
              value={row.change}
              format={{
                style: 'percent',
                minimumFractionDigits: 1,
                maximumFractionDigits: 1,
                signDisplay: 'exceptZero',
              }}
              tone={
                row.id === 'expenses'
                  ? 'critical'
                  : row.id === 'revenue'
                    ? 'positive'
                    : 'neutral'
              }
              trend={
                row.change === null
                  ? undefined
                  : {
                      direction: 'up',
                      intent: row.id === 'expenses' ? 'critical' : 'positive',
                    }
              }
            />
          ),
        },
      ]}
    />
  );
};
```


Amounts keep two decimal places and a separate USD code. Missing income is an en dash. Both trends point up, but rising expenses are critical while rising revenue is positive: direction does not determine business meaning.

`TableNumberCell` formats at the display boundary. Use `unit="USD"` for a separate ISO code; avoid also asking Intl to add a currency symbol unless repetition is intended. `style: 'percent'` expects a fraction (`0.12` → 12%). For whole percentage values use `value={12}` with `suffix="%"` instead. Accounting precision, rounding and conversion belong to the application.

## Frozen headers and scrolling [#frozen-headers-and-scrolling]


```tsx
import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridGuidesScrolling = () => {
  const rows = Array.from({ length: 16 }, (_, index) => ({
    id: `account-${String(index)}`,
    label: `Account ${String(index + 1).padStart(2, '0')}`,
    monthly: (index + 1) * 1250,
  }));

  return (
    <DataGrid<(typeof rows)[number]>
      label="Scrollable monthly budget"
      rows={rows}
      rowConfig={{ getId: (row) => row.id }}
      rowHeaderConfig={{
        header: 'Account',
        getLabel: (row) => row.label,
        width: 200,
      }}
      scrollConfig={{ maxHeight: 260 }}
      columns={['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'].map((month) => ({
        id: month,
        header: month,
        width: 160,
        cell: (row) => <TableNumberCell value={row.monthly} unit="USD" />,
      }))}
      totalConfig={{
        label: 'Total budget',
        row: {
          id: 'total',
          label: 'Total budget',
          monthly: rows.reduce((sum, row) => sum + row.monthly, 0),
        },
      }}
    />
  );
};
```


Scroll through sixteen accounts and six monthly columns. The first column preserves row context, headers stay above the values, and the grand total pins below them. Set a bounded `scrollConfig.maxHeight` rather than allowing a long matrix to dominate the page.

At narrow widths, horizontal pinning releases when the label plus one value column cannot fit. Values remain reachable through horizontal scrolling. The example repeats a monthly budget for clarity; real monthly amounts and totals should come from your reporting data.

## Editing allocations [#editing-allocations]


```tsx
import { useState } from 'react';

import { DataGrid } from '@commenda/pathfinder/data-grid';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { GBFlag } from '@commenda/pathfinder/flags/GBFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { TableCell, TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridEditing = () => {
  const [rows, setRows] = useState([
    {
      id: 'de',
      label: 'Meridian GmbH',
      it: 40,
      hr: 25,
      finance: 30,
      legal: 35,
    },
    {
      id: 'us',
      label: 'Meridian US Inc.',
      it: 35,
      hr: 45,
      finance: 35,
      legal: 40,
    },
    {
      id: 'uk',
      label: 'Meridian UK Ltd.',
      it: 25,
      hr: 30,
      finance: 25,
      legal: 25,
    },
  ]);
  const [saveStatus, setSaveStatus] = useState('All changes saved');

  const sum = (key: 'it' | 'hr' | 'finance' | 'legal') =>
    rows.reduce((total, row) => total + row[key], 0);

  return (
    <div className="pf:w-full pf:min-w-0">
      <DataGrid<(typeof rows)[number]>
        label="Cost allocation"
        rows={rows}
        rowConfig={{ getId: (row) => row.id }}
        rowHeaderConfig={{
          header: 'Entity',
          getLabel: (row) => row.label,
          width: 240,
          cell: (row) => (
            <TableCell
              type="entity"
              label={row.label}
              icon={
                row.id === 'de' ? (
                  <DEFlag />
                ) : row.id === 'uk' ? (
                  <GBFlag />
                ) : (
                  <USFlag />
                )
              }
            />
          ),
        }}
        columns={(['it', 'hr', 'legal'] as const).map((key) => ({
          id: key,
          header: key === 'it' ? 'IT' : key === 'hr' ? 'HR' : 'Legal',
          width: 128,
          cell: (row) => (
            <TableNumberCell
              value={row[key]}
              tone={
                row.id === 'total' && Math.abs(row[key] - 100) > 0.001
                  ? 'critical'
                  : 'neutral'
              }
              suffix="%"
              format={{
                minimumFractionDigits: 2,
                maximumFractionDigits: 2,
              }}
            />
          ),
          validationMessage: (row) =>
            row.id === 'total' && Math.abs(row[key] - 100) > 0.001
              ? `${key.toUpperCase()} adds up to ${String(row[key])}%. Allocations need to total 100%.`
              : undefined,
          editConfig: {
            editor: { type: 'number', min: 0, max: 100, suffix: '%' },
            getValue: (row) => String(row[key]),
            validate: (value) =>
              value.trim() === '' ||
              !Number.isFinite(Number(value)) ||
              Number(value) < 0 ||
              Number(value) > 100
                ? 'Enter a percentage between 0 and 100.'
                : undefined,
            onCommit: async (row, value) => {
              setSaveStatus('Saving changes…');
              await new Promise((resolve) => setTimeout(resolve, 250));
              setRows((current) =>
                current.map((item) =>
                  item.id === row.id ? { ...item, [key]: Number(value) } : item
                )
              );
              setSaveStatus('Saved just now');
            },
          },
        }))}
        totalConfig={{
          label: 'Total',
          row: {
            id: 'total',
            label: 'Total',
            it: sum('it'),
            hr: sum('hr'),
            finance: sum('finance'),
            legal: sum('legal'),
          },
        }}
      />
      <p
        role="status"
        className="pf:mt-lg pf:text-label-12 pf:text-soft-pearl-800"
      >
        {saveStatus}
      </p>
    </div>
  );
};
```


Click the German entity's Legal allocation, change **35** to **40**, then press Enter. The example saves the value, updates “Saved just now”, and marks the Legal total **105%** with an explanation. A successful save and a valid aggregate are separate states.

Only leaf record cells edit; parents, subtotals and totals remain read-only. Enter or leaving a changed text/number cell saves; Escape cancels. Finish or cancel an open editor before starting another. Select/calendar portals remain part of the same editing session.

The app owns persistence and the status line. After the request resolves, replace the row immutably with the canonical response. Use server versions or another concurrency policy to reject stale writes from other sessions.

## Save failure and retry [#save-failure-and-retry]


```tsx
import { useState } from 'react';

import { Checkbox } from '@commenda/pathfinder/checkbox';
import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridPatternsRecovery = () => {
  const [amount, setAmount] = useState('40.00');
  const [rejectSave, setRejectSave] = useState(true);
  const [status, setStatus] = useState(
    'Changes are saved locally in this demo'
  );

  return (
    <div className="pf:w-full pf:space-y-lg">
      <Checkbox
        label="Simulate a failed save"
        checked={rejectSave}
        onCheckedChange={setRejectSave}
      />
      <DataGrid
        label="Save recovery"
        rows={[{ id: 'de', label: 'Acme GmbH', amount }]}
        rowConfig={{ getId: (row) => row.id }}
        rowHeaderConfig={{ header: 'Entity', getLabel: (row) => row.label }}
        columns={[
          {
            id: 'allocation',
            header: 'Allocation',
            width: 240,
            cell: (row) => (
              <TableNumberCell
                value={Number(row.amount)}
                suffix="%"
                format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
              />
            ),
            editConfig: {
              outlined: true,
              editor: { type: 'number', min: 0, max: 100, suffix: '%' },
              getValue: (row) => row.amount,
              validate: (value) =>
                value.trim() ? undefined : 'Enter an allocation.',
              onCommit: async (_row, value) => {
                setStatus('Saving…');
                await new Promise((resolve) => setTimeout(resolve, 300));
                if (rejectSave) {
                  setStatus('Save failed; your draft is retained');
                  throw new Error(
                    'Could not save. Check your connection and retry.'
                  );
                }
                setAmount(value);
                setStatus('Saved just now');
              },
            },
          },
        ]}
      />
      <p role="status" className="pf:text-label-12 pf:text-soft-pearl-800">
        {status}
      </p>
    </div>
  );
};
```


Change the outlined allocation and press Enter with simulated failure enabled. The draft stays available. Disable the simulation and choose Retry save. Success is announced only after the simulated request resolves; the example makes no network calls.

| Event                                   | Result                                                  |
| --------------------------------------- | ------------------------------------------------------- |
| Click, Enter or F2 on an editable value | Opens one editor with its canonical string draft        |
| Valid changed draft + Enter or leaving  | Starts one commit transaction                           |
| Escape before persistence               | Restores the original value and cell focus              |
| Validation failure                      | Keeps the editor and explanation visible                |
| Pending request                         | Prevents duplicate commits                              |
| Rejected request                        | Retains the draft and exposes Retry save                |
| Resolved request                        | Closes the editor; app supplies updated data and status |

Use `outlined` for persistent resting borders. Text and number editors use compact 28px sizing; existing Select/DatePicker controls retain their accessible dimensions. Numeric drafts remain strings until validated and parsed by the application.

## Profit and loss [#profit-and-loss]


```tsx
import { DataGrid } from '@commenda/pathfinder/data-grid';
import { TableNumberCell } from '@commenda/pathfinder/table';

export const DataGridPivot = () => {
  interface Line {
    id: string;
    label: string;
    q1: number;
    q2: number;
    q3: number;
    q4: number;
    previous: number;
    children?: Line[];
  }

  const rows: Line[] = [
    {
      id: 'revenue',
      label: 'Revenue',
      q1: 450000,
      q2: 480000,
      q3: 510000,
      q4: 560000,
      previous: 1800000,
      children: [
        {
          id: 'services',
          label: 'Services',
          q1: 350000,
          q2: 380000,
          q3: 410000,
          q4: 450000,
          previous: 1400000,
        },
        {
          id: 'licences',
          label: 'Licences',
          q1: 100000,
          q2: 100000,
          q3: 100000,
          q4: 110000,
          previous: 400000,
        },
      ],
    },
    {
      id: 'expenses',
      label: 'Operating expenses',
      q1: 185000,
      q2: 195000,
      q3: 200000,
      q4: 210000,
      previous: 730000,
      children: [
        {
          id: 'salaries',
          label: 'Salaries',
          q1: 140000,
          q2: 150000,
          q3: 155000,
          q4: 165000,
          previous: 550000,
        },
        {
          id: 'rent',
          label: 'Office rent',
          q1: 30000,
          q2: 30000,
          q3: 30000,
          q4: 30000,
          previous: 120000,
        },
        {
          id: 'software',
          label: 'Software',
          q1: 15000,
          q2: 15000,
          q3: 15000,
          q4: 15000,
          previous: 60000,
        },
      ],
    },
    {
      id: 'costs',
      label: 'Cost of sales',
      q1: 95000,
      q2: 105000,
      q3: 115000,
      q4: 130000,
      previous: 420000,
      children: [
        {
          id: 'delivery',
          label: 'Delivery',
          q1: 95000,
          q2: 105000,
          q3: 115000,
          q4: 130000,
          previous: 420000,
        },
      ],
    },
  ];

  const currency = (value: number) => (
    <TableNumberCell value={value} unit="USD" />
  );

  const annual = (row: Line) => row.q1 + row.q2 + row.q3 + row.q4;

  return (
    <DataGrid
      label="Profit and loss"
      scrollConfig={{ maxHeight: 560 }}
      rows={rows}
      rowConfig={{
        getId: (row) => row.id,
        getChildren: (row) => row.children ?? [],
        getSubtotal: (row) => ({
          ...row,
          label: `Total ${row.label.toLowerCase()}`,
        }),
      }}
      rowHeaderConfig={{
        header: 'Line item',
        getLabel: (row) => row.label,
        width: 240,
      }}
      expansionConfig={{ defaultValue: ['revenue', 'expenses'] }}
      columns={[
        {
          id: 'fy2026',
          header: 'FY 2026',
          columns: [
            ...(['q1', 'q2', 'q3', 'q4'] as const).map((key) => ({
              id: key,
              header: key.toUpperCase(),
              width: 128,
              cell: (row: Line) => currency(row[key]),
            })),
            {
              id: 'current',
              header: 'Total',
              width: 144,
              cell: (row) => currency(annual(row)),
            },
          ],
        },
        {
          id: 'fy2025',
          header: 'FY 2025',
          columns: [
            {
              id: 'previous',
              header: 'Total',
              width: 144,
              cell: (row) => currency(row.previous),
            },
          ],
        },
        {
          id: 'change',
          header: 'Change vs FY 2025',
          width: 160,
          cell: (row) => (
            <TableNumberCell
              value={(annual(row) - row.previous) / row.previous}
              tone={
                row.id === 'expenses' ||
                row.id === 'costs' ||
                row.id === 'salaries'
                  ? 'critical'
                  : 'positive'
              }
              format={{
                style: 'percent',
                signDisplay: 'exceptZero',
                minimumFractionDigits: 1,
                maximumFractionDigits: 1,
              }}
              trend={{
                direction: annual(row) >= row.previous ? 'up' : 'down',
                intent:
                  row.id === 'expenses' || row.id === 'costs'
                    ? 'critical'
                    : 'positive',
              }}
            />
          ),
        },
      ]}
      totalConfig={{
        label: 'Operating profit',
        row: {
          id: 'profit',
          label: 'Operating profit',
          q1: 170000,
          q2: 180000,
          q3: 195000,
          q4: 220000,
          previous: 650000,
        },
      }}
    />
  );
};
```


This complete example combines year/quarter bands, expandable account groups, period totals, prior-year comparison and operating profit. It demonstrates composition after the smaller examples above. Subtotals and profit are supplied deliberately; the grid is not a formula engine.

## Loading, empty and error [#loading-empty-and-error]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { DataGrid } from '@commenda/pathfinder/data-grid';

export const DataGridPatternsStates = () => {
  const [state, setState] = useState<'loading' | 'empty' | 'error'>('loading');

  return (
    <div className="pf:w-full pf:space-y-lg">
      <div className="pf:flex pf:flex-wrap pf:gap-md">
        {(['loading', 'empty', 'error'] as const).map((value) => (
          <Button
            key={value}
            size="sm"
            variant="secondary"
            onClick={() => {
              setState(value);
            }}
          >
            {value === 'loading'
              ? 'Loading'
              : value === 'empty'
                ? 'Empty'
                : 'Error'}
          </Button>
        ))}
      </div>
      <DataGrid
        label="Matrix states"
        rows={[]}
        rowConfig={{ getId: () => '' }}
        rowHeaderConfig={{ header: 'Entity', getLabel: () => '' }}
        columns={[{ id: 'value', header: 'Allocation' }]}
        stateConfig={{
          isLoading: state === 'loading',
          error:
            state === 'error'
              ? {
                  message:
                    'Could not load allocations. Your reporting scope is preserved.',
                  onRetry: () => {
                    setState('loading');
                  },
                }
              : undefined,
          empty: {
            title: 'No allocations yet',
            description: 'Choose a reporting period with allocation data.',
          },
        }}
      />
    </div>
  );
};
```


Switch between skeletons, no allocation data and a retryable failure. These reuse Pathfinder's existing state components. Keep the reporting scope stable during loading and retry; distinguish “no data in this period” from a failed request.

## Keyboard navigation [#keyboard-navigation]

| Key               | Behavior                                                        |
| ----------------- | --------------------------------------------------------------- |
| Tab               | Enters the active owning cell; leaves the grid when not editing |
| Arrow keys        | Moves among cells; horizontal direction follows RTL             |
| Home / End        | Moves to the row edges                                          |
| Ctrl + Home / End | Moves to the first/last grid cell                               |
| Enter / F2        | Edits a value or activates the row-group control                |
| Escape            | Cancels an edit and restores cell focus                         |

Native controls retain their own keyboard interactions while editing. Avoid independently tabbable action clusters in every matrix cell; record-heavy actions usually belong in Table.

## Scope and performance [#scope-and-performance]

The grid renders its scoped matrix without virtualization. Use bounded periods/entities and profile representative row and column counts. Storybook's 1,000-row adversarial fixture is a stress scenario, not an unlimited-data performance guarantee. Range selection, fill handle, bulk paste and undo remain outside the Figma v1 scope.

See the [Figma source coverage and deliberate differences](/docs/components/data-grid#design-rules) for provenance, dimensions and accessibility adjustments.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required accessible grid name |
| `rows` | `readonly TRow[]` | required | Root rows; app owns immutable updates |
| `columns` | `readonly DataGridColumn<TRow>[]` | required | Recursive bands or value columns |
| `rowConfig` | `{ getId: (row: TRow) => string; getChildren?: (row: TRow) => readonly TRow[]; getSubtotal?: (row: TRow) => TRow \| undefined; }` | required | Stable IDs; optional child and subtotal accessors |
| `rowHeaderConfig` | `{ header: string; getLabel: (row: TRow) => string; cell?: (row: TRow) => ReactNode; width?: number; }` | required | Frozen row axis; width defaults to 240px |
| `expansionConfig` | `SelectionProps<readonly string[]>` | optional | Controlled/default expanded row IDs |
| `totalConfig` | `{ row: TRow; label: string; }` | optional | App-supplied grand total pinned at the bottom |
| `scrollConfig` | `{ maxHeight?: number; }` | optional | Bounded scrolling; default maximum height 480px |
| `stateConfig` | `TabularStateConfig` | optional | Skeleton, retryable error and first-use state |
| `dataMode` | `"local" \| "remote"` | optional | Local filters matching leaf paths; remote renders supplied rows unchanged |
| `searchConfig` | `SelectionProps<string> & { getText?: ((row: TRow) => string) \| undefined; placeholder?: string; }` | optional | Controlled or local search; defaults to row labels |
| `filterConfig` | `{ filters: readonly TableFilter<TRow>[]; operators?: SelectionProps<Readonly<Record<string, TableFilterOperator>>>; value: Readonly<Record<string, readonly string[]>>; onValueChange: (value: Record<string, readonly string[]>) => void; }` | optional | Definitions, controlled values/callback, controlled or default operators |
| `toolbarConfig` | `TableToolbarConfig` | optional | Primary, secondary, export and overflow actions |
| `toolbar` | `ReactNode` | optional | App-owned matrix controls above the grid |
| `className` | `string` | optional | Root classes |

### rowConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `getId` | `(row: TRow) => string` | Yes |  |
| `getChildren` | `((row: TRow) => readonly TRow[])` | No |  |
| `getSubtotal` | `((row: TRow) => TRow \| undefined)` | No |  |

### rowHeaderConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `header` | `string` | Yes |  |
| `getLabel` | `(row: TRow) => string` | Yes |  |
| `cell` | `((row: TRow) => ReactNode)` | No |  |
| `width` | `number` | No |  |

### expansionConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `readonly string[]` | Yes |  |
| `onValueChange` | `(value: readonly string[]) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `readonly string[]` | No |  |
| `onValueChange` | `((value: readonly string[]) => void)` | No |  |

Do not supply: `value`.

### totalConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `row` | `TRow` | Yes |  |
| `label` | `string` | Yes |  |

### scrollConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `maxHeight` | `number` | No |  |

### stateConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | No |  |
| `error` | `{ message: string; onRetry: () => void; }` | No |  |
| `empty` | `{ title: string; description?: string; action?: TableAction; }` | No |  |

### stateConfig.error fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `onRetry` | `() => void` | Yes |  |

### stateConfig.empty fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Yes |  |
| `description` | `string` | No |  |
| `action` | `TableAction` | No |  |

### stateConfig.empty.action fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `onAction` | `() => void` | Yes |  |
| `disabled` | `boolean` | No |  |

### filterConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | `readonly TableFilter<TRow>[]` | Yes |  |
| `operators` | `SelectionProps<Readonly<Record<string, TableFilterOperator>>>` | No |  |
| `value` | `Readonly<Record<string, readonly string[]>>` | Yes |  |
| `onValueChange` | `(value: Record<string, readonly string[]>) => void` | Yes |  |

### filterConfig.operators fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `Readonly<Record<string, TableFilterOperator>>` | Yes |  |
| `onValueChange` | `(value: Readonly<Record<string, TableFilterOperator>>) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Readonly<Record<string, TableFilterOperator>>` | No |  |
| `onValueChange` | `((value: Readonly<Record<string, TableFilterOperator>>) => void)` | No |  |

Do not supply: `value`.

### toolbarConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | `readonly TableAction[]` | No | Prefer named actions. Legacy actions use first=primary, second=secondary, remainder=overflow. |
| `primaryAction` | `(TableAction & { menu?: DropdownMenu; icon?: ReactNode; })` | No |  |
| `secondaryAction` | `TableAction` | No |  |
| `onExport` | `(() => void)` | No |  |
| `moreMenu` | `DropdownMenu` | No |  |

### toolbarConfig.secondaryAction fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `onAction` | `() => void` | Yes |  |
| `disabled` | `boolean` | No |  |

### toolbarConfig.moreMenu fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | `DropdownGroup[]` | Yes |  |

A column group is `{ id, header, columns }`; groups can nest recursively. A value column is `{ id, header, value?, cell?, width?, align?, editConfig?, validationMessage? }`. Default width is 128px and alignment is `end`. IDs must be unique across the column tree; groups cannot be empty. Row IDs must be unique throughout an acyclic row tree. Invalid recursive structures throw a clear configuration error.

Use `cell` with TableCell/TableNumberCell for entity flags, numeric/currency formatting and trends. Header bands span their descendant leaves; shorter branches span the remaining header levels. The first column and headers remain visible while scrolling horizontally and vertically. If the container cannot fit the row header plus a value column, horizontal pinning releases so values remain reachable; column headers still pin vertically. Keyboard arrows follow logical order in RTL.

### Editing configuration [#editing-configuration]

A value column's `editConfig` contains:

| Property   | Type                                    | Behavior                                               |
| ---------- | --------------------------------------- | ------------------------------------------------------ |
| `editor`   | TableCellEditor                         | Text, numeric draft, Select or segmented date/calendar |
| `outlined` | boolean                                 | Keeps resting editor outlines visible                  |
| `getValue` | `(row) => string`                       | Editable canonical draft                               |
| `canEdit`  | `(row) => boolean`                      | Optional app permission predicate                      |
| `validate` | `(value, row) => string or undefined`   | App validation before saving                           |
| `onCommit` | `(row, value) => void or Promise<void>` | App persistence and row update                         |

Only leaf record rows edit; groups, subtotals and totals stay read-only. One editor opens at a time. Leaving a changed cell saves; Enter saves text/numbers; Escape discards the draft. Pending saves cannot duplicate. Rejection retains the draft with a readable error and retry. While an editor is still open, finish or cancel it before editing another cell. Do not silently accept failed requests.

`validationMessage(row)` exposes invalid totals with an accessible explanation and error color. The allocation example calculates totals in its application layer; changing Legal from 35 to 40 produces a 105% invalid total, not a modal alert. Number strings are parsed by the app after validation. Financial precision, permissions, stale-write protection and server transactions remain application responsibilities.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Shared cells [#shared-cells]

- **CELL-001:** Text starts at the logical leading edge; numbers align at the trailing edge and use tabular figures. Empty values show an en dash. Entity flags are 16px, person avatars 20px. Entity names wrap; do not truncate monetary amounts. Cells compose existing Badge, Tag, Avatar, ProgressBar and exact icon assets.
- **CELL-002:** Currency units remain quiet and separate from values. Fixed decimals are supplied via Intl format options. Trend direction and semantic intent are separate. A cost increase can be critical even though its arrow points up.
- **CELL-003:** At most primary bordered icon, secondary icon and overflow in a row action group. Do not repeat text CTAs in every row.
- **CELL-EDIT-001:** Compact text/number editor minimum 28px and radius 6px; calm border at rest, outline on hover/focus, persistent invalid treatment. Existing Select and DatePicker keep their accessible field geometry; the DatePicker retains the user's approved Kakashi DateField padding rather than shrinking its segmented inputs.
- **CELL-EDIT-002:** Enter or leaving the editor commits one cell; Escape cancels. Pending work cannot duplicate; errors retain drafts and offer retry. React portal focus stays within the same editing session. Application code validates and persists canonical values.

The Figma cell master depicts combinations, not 32 separate exported component classes. The shared content family composes those visual patterns. Toggle and upload actions use existing Switch/FileUpload application workflows in custom cells; they do not pretend to be string editors. TableCell content, TableNumberCell, TableRowActions and TableEditCell work in both owning components.

### Matrix grid [#matrix-grid]

- **GRID-001:** Pearl-100 headers, 36px bands, 40px minimum body rows, 0.5px vertical/horizontal gridlines. Freeze the first column and headers. Grouped columns recurse; row-header width defaults to 240px and value columns to 128px.
- **GRID-002:** Collapsed groups display supplied aggregates. Expanded groups place supplied subtotals below children; subtotal background is pearl-100. Grand total pins to the bottom with a pearl-400 1px top border. No inferred formulas or double-counting.
- **GRID-003:** One active cell with inset blue-700 outline and blue-200 ring. Arrow keys navigate; Enter/F2 edits or opens a group; Escape cancels. No range selection, fill handle, bulk paste, undo or virtualization in this version.
- **GRID-004:** Only leaf record cells edit. Totals/aggregates remain read-only. Invalid totals explain the problem with error styling and a tooltip, not a modal. The app owns calculations, precision, constraints, permission checks and persistence.

Quiet secondary text uses pearl-800 where the design's lighter text would fail contrast at these small sizes. Narrow layouts release horizontal pinning when the frozen columns would hide readable values and scroll within their own container; financial values retain their width. Storybook's shared worst-case fixture covers long CJK/emoji names, large negative values, 1,000 paginated records, empty data, RTL and a 320px container.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

| Reference                                                                                                 | Coverage                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Cell master 430:13537](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=430-13537) | Text/description/icon/badge, people/groups/email, entities, files, tags, boolean, progress, copy/link, numbers/units/currency/trends, loading and totals compose TableCell, TableNumberCell and TableRowActions. Tree parent/child/grandchild behavior belongs to the recursive DataGrid examples. Hover and selection share the row tint in both densities. |

- **Accessibility:** quiet text uses pearl-800 for contrast. Long content and text zoom can grow rows. Narrow viewports release horizontal pinning. Copy controls remain visible on touch, and long status labels expose their full text on focus/hover.

- **Application patterns:** presets, summary aggregates, “Saved just now”, network requests, exports, permissions and financial calculations are owned by the app. Demos perform local updates or simulated requests and say so.

- **States and scale:** matrix loading/error fallbacks reuse existing primitives. No virtualization, range operations or spreadsheet formulas are claimed. Stress fixtures do not establish an unlimited-data performance guarantee.

AI consumers should read this page together with the component API and integration pages. Do not infer a public prop from a Figma variant name, or treat a prototype's sample amounts as domain validation rules.

### Header and cell master reconciliation [#header-and-cell-master-reconciliation]

| Reference                                                                                                        | Coverage                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Header master 430:13536](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=430-13536)      | Start/center/end alignment, unsorted/ascending/descending, hover/focus, optional information, checkbox and empty action header; Headers, Selection and Pinning examples. |
| [Groups and add row 445:13858](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=445-13858) | Grouped filings show flags, counts, collapse and page-selection persistence; editable lines show totals and Add line. Application callbacks own actual persistence.      |

Long content and zoom can grow rows beyond Figma's nominal heights. Linear progress and ring progress use their existing Pathfinder primitives; cell recipes do not introduce a new progress implementation. A file-picker example selects a local file and displays its name; production upload, progress and retry belong to the application's upload workflow. These are deliberate compositional boundaries, not built-in backend features.

## Search and filters [#search-and-filters]


```tsx
import { useState } from 'react';

import { DataGrid } from '@commenda/pathfinder/data-grid';

const records = [
  {
    id: 'uk',
    label: 'Meridian UK',
    jurisdiction: 'GB',
    status: 'review',
    due: '2026-10-20',
    amount: 1200,
  },
  {
    id: 'us',
    label: 'Meridian US',
    jurisdiction: 'US',
    status: 'complete',
    due: '2026-11-10',
    amount: 2400,
  },
  {
    id: 'de',
    label: 'Meridian Germany',
    jurisdiction: 'DE',
    status: 'review',
    due: '2026-10-25',
    amount: 800,
  },
];

export const DataGridFiltersDefault = () => {
  const [filters, setFilters] = useState<Record<string, readonly string[]>>({});

  return (
    <DataGrid
      label="Entity allocations"
      rows={records}
      rowConfig={{ getId: (row) => row.id }}
      rowHeaderConfig={{ header: 'Entity', getLabel: (row) => row.label }}
      columns={[
        {
          id: 'jurisdiction',
          header: 'Country',
          value: (row) => row.jurisdiction,
          align: 'start',
        },
        { id: 'amount', header: 'Allocation', value: (row) => row.amount },
        { id: 'due', header: 'Due date', value: (row) => row.due },
      ]}
      searchConfig={{ defaultValue: '' }}
      filterConfig={{
        value: filters,
        onValueChange: setFilters,
        filters: [
          {
            id: 'jurisdiction',
            label: 'Country',
            type: 'multiple',
            searchable: true,
            getValue: (row) => row.jurisdiction,
            options: [
              { value: 'GB', label: 'United Kingdom' },
              { value: 'US', label: 'United States' },
              { value: 'DE', label: 'Germany' },
            ],
          },
          {
            id: 'status',
            label: 'Status',
            type: 'single',
            getValue: (row) => row.status,
            options: [
              { value: 'review', label: 'In review' },
              { value: 'complete', label: 'Complete' },
            ],
          },
          {
            id: 'due',
            label: 'Due date',
            type: 'date',
            getValue: (row) => row.due,
            presets: [
              {
                id: 'october',
                label: 'October 2026',
                start: '2026-10-01',
                end: '2026-10-31',
              },
            ],
          },
          {
            id: 'amount',
            label: 'Allocation',
            type: 'number',
            initiallyVisible: false,
            getValue: (row) => row.amount,
          },
        ],
      }}
    />
  );
};
```


`searchConfig`, `filterConfig` and `toolbarConfig` share Table’s contracts. The grid reuses its single/multiple choice, searchable options, date presets/ranges, numeric operators, active chips, overflow and clear controls. Supply `toolbarConfig` for named primary/secondary/overflow/export actions; `toolbar` remains available for custom controls.

Local mode searches row labels by default; `searchConfig.getText` adds searchable fields. Filters combine with AND between fields. Matching leaves retain and expand their ancestor paths, including groups whose labels match the search. Clearing the search and filters restores the previous expansion state. Expansion controls are unavailable while showing filtered paths.

**GRID-FILTER-001:** Local filtering hides subtotals and grand totals because arbitrary cell values cannot safely be aggregated. Clear filters to restore complete totals. If the API computes filtered aggregates, pass those with `dataMode="remote"`.

### API-owned filtering [#api-owned-filtering]


```tsx
import { useState } from 'react';

import {
  DataGrid,
  type DataGridFilterOperator,
} from '@commenda/pathfinder/data-grid';

const records = [
  {
    id: 'uk',
    label: 'Meridian UK',
    jurisdiction: 'GB',
    status: 'review',
    due: '2026-10-20',
    amount: 1200,
  },
  {
    id: 'us',
    label: 'Meridian US',
    jurisdiction: 'US',
    status: 'complete',
    due: '2026-11-10',
    amount: 2400,
  },
  {
    id: 'de',
    label: 'Meridian Germany',
    jurisdiction: 'DE',
    status: 'review',
    due: '2026-10-25',
    amount: 800,
  },
];

export const DataGridFiltersRemote = () => {
  const [query, setQuery] = useState('');
  const [operators, setOperators] = useState<
    Readonly<Record<string, DataGridFilterOperator>>
  >({});
  const [filters, setFilters] = useState<Record<string, readonly string[]>>({});
  // Simulates a server response. Real applications fetch with query/filter/operator state and cancel stale requests.
  const response = records.filter(
    (row) =>
      row.label.toLowerCase().includes(query.toLowerCase()) &&
      (!Object.hasOwn(filters, 'status') ||
        filters.status.length === 0 ||
        (operators.status === 'isNot'
          ? !filters.status.includes(row.status)
          : filters.status.includes(row.status)))
  );

  return (
    <div style={{ display: 'grid', gap: 12, width: '100%' }}>
      <p>
        Simulated API response. Search and filter callbacks own the request
        state.
      </p>
      <DataGrid
        label="API allocations"
        dataMode="remote"
        rows={response}
        rowConfig={{ getId: (row) => row.id }}
        rowHeaderConfig={{ header: 'Entity', getLabel: (row) => row.label }}
        columns={[
          { id: 'amount', header: 'Allocation', value: (row) => row.amount },
        ]}
        searchConfig={{ value: query, onValueChange: setQuery }}
        filterConfig={{
          operators: { value: operators, onValueChange: setOperators },
          value: filters,
          onValueChange: setFilters,
          filters: [
            {
              id: 'status',
              label: 'Status',
              type: 'single',
              options: [
                { value: 'review', label: 'In review' },
                { value: 'complete', label: 'Complete' },
              ],
            },
          ],
        }}
      />
    </div>
  );
};
```


**GRID-FILTER-002:** In `dataMode="remote"`, the component renders the rows supplied by the application without applying local filtering. Control query, values and operators with their callbacks, cancel stale requests, and supply `stateConfig` for loading, errors and retry. The example simulates a response in memory; it does not perform a network request.


---

# Date picker

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/date-picker
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=188-2

```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';

export const DatePickerDefault = () => (
  <DatePicker label="Filing date" format="us" clearConfig={{}} />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `mode` | `"single" \| "range" \| "month"` | conditional | `'single'`; discriminates value and constraints |
| `value` | `string \| null \| DateRange` | conditional | Single `YYYY-MM-DD`, month `YYYY-MM`, range `{ start, end }` of date strings/null |
| `defaultValue` | `string \| null \| DateRange` | optional | Single `YYYY-MM-DD`, month `YYYY-MM`, range `{ start, end }` of date strings/null |
| `onValueChange` | `((value: string \| null) => void) \| ((value: DateRange) => void)` | conditional | Controlled mode requires it. Receives valid values, explicit clears, or partial ranges |
| `format` | `"us" \| "in" \| "iso"` | optional | `'iso'`; MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD |
| `calendarConfig` | `false \| { weekStartsOn?: 0 \| 1; }` | optional | Calendar enabled, Sunday first; false is typed-only |
| `constraintConfig` | `DateConstraints \| MonthConstraints` | optional | Single/range date constraints; month mode uses `isMonthUnavailable` and month strings |
| `presetConfig` | `{ items: readonly { id: string; label: string; value: DateRange; }[]; }` | optional | Range-only; presets obey the same constraints |
| `clearConfig` | `{ label?: string; }` | optional | Optional clear action |
| `name` | `string` | optional | Single/month submit one ISO value; range submits `name.start` and `name.end` |
| `form` | `string` | optional | Single/month submit one ISO value; range submits `name.start` and `name.end` |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Defines a string value that labels the current element. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `className` | `string` | optional | Additional classes for the component root. |
| `readOnly` | `boolean` | optional | Allow reading the current value without editing it. |
| `onBlur` | `FocusEventHandler<HTMLDivElement>` | optional | Called when focus leaves the component. |
| `onFocus` | `FocusEventHandler<HTMLDivElement>` | optional | Called when focus enters the component. |

### value fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | `string \| null` | Yes |  |
| `end` | `string \| null` | Yes |  |

### defaultValue fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | `string \| null` | Yes |  |
| `end` | `string \| null` | Yes |  |

### calendarConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `weekStartsOn` | `0 \| 1` | No |  |

### constraintConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | `string` | No |  |
| `max` | `string` | No |  |
| `isDateUnavailable` | `((date: string) => boolean)` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | `string` | No |  |
| `max` | `string` | No |  |
| `isMonthUnavailable` | `((month: string) => boolean)` | No |  |

### presetConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `readonly { id: string; label: string; value: DateRange; }[]` | Yes |  |

### clearConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

Shared presentation and `readOnly` follow [Input](/docs/components/input). Refs and native form behavior differ because this is a composite editor. Set valid ISO strings in controlled props; invalid or incomplete drafts remain in the editor and block native form submission. They never silently revert on blur. A changed external value replaces the draft; form reset restores uncontrolled defaults and clears draft edits.

## Typing and calendar selection [#typing-and-calendar-selection]

The parent field is the Kakashi-derived DateField: type or adjust its day, month, and year segments directly. The calendar icon opens the matching day, range, or month picker. Choosing a date updates those same segments and the same ISO value; neither interaction owns a second date state. Invalid drafts stay visible until corrected.

## Range and presets [#range-and-presets]


```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';

export const DatePickerRange = () => (
  <DatePicker
    mode="range"
    label="Reporting period"
    defaultValue={{ start: '2026-10-01', end: '2026-10-31' }}
    presetConfig={{
      items: [
        {
          id: 'october',
          label: 'October 2026',
          value: { start: '2026-10-01', end: '2026-10-31' },
        },
        {
          id: 'quarter',
          label: 'Fourth quarter',
          value: { start: '2026-10-01', end: '2026-12-31' },
        },
      ],
    }}
    clearConfig={{}}
  />
);
```


Click a day to start a new range; the calendar stays open while you choose its end. The second click completes the range, including a same-day range, and closes the calendar. Choosing an earlier second day orders the two dates chronologically. End must be on or after start. A range cannot cross an unavailable date. Wide screens show two months; narrow screens show one navigable month. For large selectable periods, provide practical application min/max bounds so predicate checks stay inexpensive.

## Month [#month]


```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';

export const DatePickerMonth = () => (
  <DatePicker
    mode="month"
    label="Accounting month"
    defaultValue="2026-10"
    clearConfig={{}}
  />
);
```


## Typed-only [#typed-only]


```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';

export const DatePickerTyped = () => (
  <DatePicker
    label="Date of incorporation"
    format="in"
    calendarConfig={false}
    description="Type DD/MM/YYYY. Arrow keys navigate and adjust segments."
  />
);
```


Each segment has an accessible name. Arrow keys move between or adjust segments. Dates are calendar strings; do not convert through `new Date('YYYY-MM-DD').toISOString()` in application adapters.

## Constraints [#constraints]


```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';

export const DatePickerConstraints = () => (
  <DatePicker
    label="Available filing date"
    defaultValue="2026-10-01"
    constraintConfig={{
      min: '2026-10-01',
      max: '2026-10-31',
      isDateUnavailable: (date) => date === '2026-10-15',
    }}
    description="October only; the 15th is unavailable. Typed dates use the same constraints."
  />
);
```


## States [#states]


```tsx
import { DatePicker } from '@commenda/pathfinder/date-picker';

export const DatePickerStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <DatePicker label="Read-only date" defaultValue="2026-10-12" readOnly />
    <DatePicker
      label="Disabled date"
      defaultValue="2026-10-12"
      disableConfig={{ isDisabled: true }}
    />
    <DatePicker
      label="Required date"
      required
      errorConfig={{ message: 'Choose a filing date.', reveal: 'immediate' }}
    />
  </div>
);
```


Read [composite field rules](/docs/components/date-picker#design-rules).

## Design rules [#design-rules]

The calendar follows [Calendar](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=190-587), [day cells](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=188-33), and [month cells](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=188-50).

- The typed block follows Kakashi DateField spacing: 40px minimum height, 8px horizontal padding, 24px-tall segments, 40px year and 28px month/day widths, 2px gaps, and 2px separator padding. This user-requested spacing overrides Figma's compact 28px field. The 16px calendar icon sits in a 24px action target.
- The floating card has a 10px radius, pearl-300 hairline, menu shadow, and 12px calendar padding.
- Navigation is 24px; weekday labels are 24px tall; days are 32px square with 2px between weeks. Month options are 72 × 32px.
- Selected dates and range ends use blue-700. Interior dates form a continuous blue-100 band. Today has a 4px dot. Presets show a check when their range matches.
- Outside days and weekday labels use pearl-800 for readable contrast, a deliberate adjustment from Figma's lighter colors.
- At narrow widths the range calendar shows one month and puts supplied presets above the calendar. Preset dates and labels remain application-owned.

### Reference rules [#reference-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Dates [#dates]

- **DATE-001:** Single, range, month, and typed-only use Kakashi DateField spacing per the user override: minimum height 40px, horizontal inset 8px, fixed 40px year and 28px month/day segments, 24px segment height, 2px segment gaps and separator padding. Locale segment order is explicit through `format`; default is ISO.
- **DATE-002:** Calendar 190:587, day cell 188:33, and month cell 188:50: offset 4px, radius 10, pearl-300 hairline, 12px padding, 24px navigation and weekday row, 32px days with 2px week gaps, 72 × 32px month options. Sunday first; selected blue-700, continuous blue-100 range band, 4px today dot, unavailable dates disabled and muted. These exact cell frames supersede the older page note about strikethrough. Supplied presets have a divided sidebar and selection check; narrow screens place presets above one month. Weekday/outside text is strengthened to pearl-800 for contrast.
- **DATE-003:** Private DateField derives from Kakashi's editing/navigation engine, with Pathfinder tokens and no private workspace runtime imports. Keep incomplete/invalid drafts visible; never replace them with the old committed value on blur.
- **DATE-004:** ISO date-only strings, no UTC conversion. Typed input, calendar, and presets use identical constraints. Typed ranges reject reversed dates and ranges crossing unavailable days. Calendar selection uses two clicks: the first starts a new range and keeps the popup open; the second completes it (including the same day). Month mode uses month predicates.
- **DATE-005:** `calendarConfig={false}` removes the icon/popover. Composite refs target the group. Native forms submit ISO values; invalid drafts cannot submit an older saved value.

- **DATE-006:** First calendar click starts a fresh range and keeps the popup open. Second click completes it, including a same-day range. Display a prompt for the pending end date. Selected days retain their blue fill on hover.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

- **Editors:** Select and DatePicker retain their existing control heights; they are not pixel-identical to compact picker drawings. Text/number editors use the compact geometry. Async save errors remain visibly actionable with retry.

### Shared rules [#shared-rules]

Labels activate the first input; every date segment has its own accessible label. Descriptions, disabled reasons, and validation messages stay associated with the field. Error icons center on the first 18px text line, including wrapped messages. Controlled values require callbacks; uncontrolled form resets restore defaults. Public props expose application values, never private primitive or calendar objects. Styles ship precompiled for React 18/19 and Next.js consumers.

Date segments use native text selection as their single editing highlight. Focusing a segment selects its text for replacement; the field retains its own outer focus or validation border.


---

# Description list

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/description-list
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=967-2

```tsx
import { Badge } from '@commenda/pathfinder/badge';
import { DescriptionList } from '@commenda/pathfinder/description-list';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

export const DescriptionListDefault = () => (
  <DescriptionList
    items={[
      {
        id: 'name',
        label: 'Entity name',
        value: 'Commenda Technologies Inc.',
        copyConfig: { text: 'Commenda Technologies Inc.' },
      },
      {
        id: 'country',
        label: 'Country',
        value: 'United States',
        leadingIcon: <USFlag size={16} />,
      },
      {
        id: 'status',
        label: 'Status',
        value: <Badge label="Active" tone="success" />,
      },
      { id: 'tax', label: 'Tax ID', value: null },
    ]}
  />
);
```


Import from `@commenda/pathfinder/description-list`, and load the shared stylesheet once.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly DescriptionItem[]` | required | Stable IDs, label, and ReactNode value |
| `layout` | `"inline" \| "auto" \| "stacked"` | optional | `auto`: stack below 480px of container width |
| `size` | `"default" \| "compact"` | optional | Default 36px inline minimum; compact 28px |
| `emptyLabel` | `string` | optional | `Not set`; zero and false remain visible |
| `className` | `string` | optional | Root dl styling |

Each item supports `localLabel`, `help` text, `leadingIcon`, `copyConfig: { text, onCopy?, onError? }`, and `editConfig`. Editable items use `{ kind: 'editable', onEdit }`; protected items use `{ kind: 'locked', reason, onRequestChange }`. The application opens its editor or change-request flow. Copy text is explicit, including when the displayed value is a badge or link.

## Copy and edit [#copy-and-edit]


```tsx
import { useState } from 'react';

import { DescriptionList } from '@commenda/pathfinder/description-list';

export const DescriptionListActions = () => {
  const [status, setStatus] = useState('');

  return (
    <>
      <DescriptionList
        items={[
          {
            id: 'name',
            label: 'Legal name',
            localLabel: 'Registered company name',
            value: 'Acme GmbH',
            help: 'The legal name on registration documents.',
            copyConfig: { text: 'Acme GmbH' },
            editConfig: {
              kind: 'locked',
              reason: 'A registration change requires review.',
              onRequestChange: () => {
                setStatus('Change request opened.');
              },
            },
          },
          {
            id: 'website',
            label: 'Website',
            value: <a href="https://example.com">example.com</a>,
            editConfig: {
              kind: 'editable',
              onEdit: () => {
                setStatus('Website editor opened.');
              },
            },
          },
        ]}
      />
      <output>{status}</output>
    </>
  );
};
```


Copy success appears only after the clipboard write succeeds. Failed writes announce an error. Actions appear on hover, keyboard focus, and touch without moving content. Protected fields remain readable and request a change rather than opening an inline editor.

## Compact panels [#compact-panels]


```tsx
import { DescriptionList } from '@commenda/pathfinder/description-list';

export const DescriptionListCompact = () => (
  <DescriptionList
    size="compact"
    layout="stacked"
    items={[
      { id: 'staff', label: 'Employees', value: 0 },
      { id: 'registration', label: 'Registration verified', value: false },
    ]}
  />
);
```


Use a Card with `padding="none"` for section framing. DescriptionList supplies its own 8px inset. Section titles and section-level Edit actions belong to Card. Read the [record component rules](/docs/components/description-list#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule            | Contract and provenance                                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DESCRIPTION-001 | Figma 967:9 / 969:377: 8px list inset, 2px row gaps, 200px inline label column; stack below 480px container width. Default/compact row heights are minimums, allowing wrapping. |
| DESCRIPTION-002 | Native dl/dt/dd; zero/false are values. Actions reserve space and appear on focus/touch as well as hover.                                                                       |
| DESCRIPTION-003 | Copy explicit text, announce real success/failure. Locked edit requests a change; apps own editor surfaces.                                                                     |

### Recorded design decisions [#recorded-design-decisions]

Description row source/provenance, sensitive-value reveal, and edit-history explorations are not combined into the initial approved row interface. Consumers can compose record value content; future named behavior needs a chosen design contract.


---

# Dialog

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/dialog
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=372-2

```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Dialog } from '@commenda/pathfinder/dialog';
import { Input } from '@commenda/pathfinder/input';

export const DialogDefault = () => {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState('Acme Inc.');

  return (
    <Dialog
      title="Edit entity details"
      description="Changes apply to filings created from today."
      trigger={<Button variant="secondary">Edit entity</Button>}
      open={open}
      onOpenChange={setOpen}
      footerConfig={{
        primaryAction: {
          label: 'Save changes',
          type: 'submit',
          form: 'entity-dialog-form',
        },
      }}
    >
      <form
        id="entity-dialog-form"
        onSubmit={(event) => {
          event.preventDefault();
          setOpen(false);
        }}
      >
        <Input label="Entity name" value={name} onValueChange={setName} />
      </form>
    </Dialog>
  );
};
```


Import `Dialog` and `ConfirmDialog` from `@commenda/pathfinder/dialog`.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `title` | `string` | required | Required accessible heading |
| `description` | `ReactNode` | optional | Optional supporting text |
| `trigger` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | optional | Optional ref-forwarding button |
| `children` | `ReactNode` | required | Form or focused task body |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | optional | lg; 400 / 480 / 600 / 800px, viewport-clamped |
| `footerConfig` | `OverlayFooterConfig` | optional | Optional footer |
| `dismissConfig` | `OverlayDismissConfig` | optional | Outside dismissal enabled; guard may be async |
| `focusConfig` | `OverlayFocusConfig` | optional | First body control, then popup; returns to trigger |
| `className` | `string` | optional | Popup classes |
| `open` | `boolean` | conditional |  |
| `onOpenChange` | `((open: boolean) => void)` | conditional |  |
| `defaultOpen` | `boolean` | optional |  |

### footerConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primaryAction` | `OverlayAction` | No |  |
| `secondaryAction` | `OverlayAction` | No |  |
| `leadingContent` | `ReactNode` | No |  |
| `cancelLabel` | `string` | No |  |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outsidePress` | `boolean` | No |  |
| `beforeClose` | `((reason: OverlayCloseReason) => boolean \| Promise<boolean>)` | No |  |
| `onError` | `((error: unknown) => void)` | No |  |

### focusConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `initialFocusRef` | `RefObject<HTMLElement \| null>` | No |  |
| `returnFocusRef` | `RefObject<HTMLElement \| null>` | No |  |

`open` with `onOpenChange` is controlled; otherwise use `defaultOpen`. Primary actions never imply success or automatically close the surface. Close it after the application completes its work.

`footerConfig` accepts `primaryAction`, `secondaryAction`, `leadingContent`, and `cancelLabel`. Actions have `label`, `onClick`, native `type`/`form`, `disabled`, `disabledReason`, `loadingConfig`, `destructive`, and icons. Without a secondary action the footer renders Cancel. A footer is absent unless configured. Submit uses native form IDs; IDs must be unique.

## Sizes [#sizes]


```tsx
import { Button } from '@commenda/pathfinder/button';
import { Dialog } from '@commenda/pathfinder/dialog';

export const DialogSizes = () => (
  <div className="pf:flex pf:flex-wrap pf:gap-md">
    {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
      <Dialog
        key={size}
        size={size}
        title={`Dialog ${size}`}
        trigger={<Button variant="secondary">{size}</Button>}
        footerConfig={{}}
      >
        <p className="pf:m-0">
          Choose the smallest size that comfortably fits the task.
        </p>
      </Dialog>
    ))}
  </div>
);
```


## Confirmation [#confirmation]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { ConfirmDialog } from '@commenda/pathfinder/dialog';

export const DialogConfirmation = () => {
  const [open, setOpen] = useState(false);
  const [deleted, setDeleted] = useState(false);

  return (
    <>
      <ConfirmDialog
        title="Delete this policy?"
        description="Contract R&D services and its 3 versions will be removed. This can’t be undone."
        trigger={
          <Button variant="secondary" destructive>
            Delete policy
          </Button>
        }
        open={open}
        onOpenChange={setOpen}
        confirmAction={{
          label: 'Delete policy',
          destructive: true,
          onClick: () => {
            setDeleted(true);
            setOpen(false);
          },
        }}
      />
      <output>{deleted ? 'Policy deleted.' : ''}</output>
    </>
  );
};
```


`ConfirmDialog` requires `title`, `description`, and `confirmAction`. It also accepts the same open state, trigger, focus config, a `cancelLabel`, and dismissal guard. It uses alert-dialog semantics, focuses Cancel, has no close icon, and ignores outside presses. A loading confirmation blocks dismissal until the application completes or reports an error.

## Scrolling and nested controls [#scrolling-and-nested-controls]


```tsx
import { Button } from '@commenda/pathfinder/button';
import { Dialog } from '@commenda/pathfinder/dialog';
import { Select } from '@commenda/pathfinder/select';

export const DialogScrolling = () => (
  <Dialog
    title="Review filings"
    description="The body scrolls independently of actions."
    trigger={<Button variant="secondary">Review filings</Button>}
    footerConfig={{
      primaryAction: { label: 'Save review', onClick: () => {} },
    }}
  >
    <Select
      label="Jurisdiction"
      options={[
        { value: 'US', label: 'United States' },
        { value: 'GB', label: 'United Kingdom' },
      ]}
    />
    {Array.from({ length: 30 }, (_, index) => (
      <p key={index}>
        Filing {index + 1}: Review the registration details and supporting
        documents.
      </p>
    ))}
  </Dialog>
);
```


Body scrolling adds header/footer hairlines. Select menus and popovers remain inside the focus boundary through their portals. Escape closes the innermost surface first.

`beforeClose(reason)` receives `escape`, `outside`, `close`, `cancel`, or `trigger` and returns a boolean or promise. False keeps the dialog open; failure announces an error. Duplicate requests are ignored while pending; a decision from an earlier open cycle cannot close a reopened dialog. Setting controlled `open=false` is an explicit application decision and bypasses the guard. Read the [overlay rules](/docs/components/dialog#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Dialog and confirmation [#dialog-and-confirmation]

- **DIALOG-001:** One focused task. sm/md/lg/xl are 400/480/600/800px; default lg. Radius 12, 0.5px pearl-300 edge, modal shadow. Backdrop pearl-1000 at 10%, no blur. Full-screen and multi-step work belongs on a page.
- **DIALOG-002:** Heading/15 title, Copy/13 description. Header padding 20px top, 24px start, 16px end/bottom; text inset 4px. Body 24px horizontal, 4px top, 16px bottom. Footer 24px horizontal, 16px top, 20px bottom. Body scrolls independently; hairlines appear after scrolling. Cancel then action-named primary at 32px; optional leading content.
- **DIALOG-003:** Initial focus enters the body, focus remains contained, and returns to the trigger. Explicit refs override defaults. Escape affects the innermost surface. Async guards block duplicate requests and ignore stale cycles; callers own mutation success and controlled closure.
- **CONFIRM-001:** Alertdialog with question and consequence. Focus Cancel; no close icon or outside dismissal. Destructive action is named, not “Yes”.
- **CONFIRM-002:** Clicking is not success. Loading and failure remain app-owned; a loading confirmation cannot be dismissed by its controls.

### Motion and edge cases [#motion-and-edge-cases]

Occasional overlays use motion for spatial consistency. Motion paths and timings follow Kakashi: Dialog fades and moves from 95% scale with a 2% vertical offset in 200ms both ways; Popover fades from 95% scale and an 8px offset toward its trigger in 150ms both ways. Popover direction follows the resolved placement after collision handling. Right Sheet slides in for 500ms and out for 300ms; bottom Sheet slides for 500ms both ways. Sheet panels do not fade during normal motion, and modal backdrops follow the panel duration.

Pathfinder retains its foundation ease-out curve for Dialog/Popover and drawer curve `(0.32,0.72,0,1)` for Sheets. These are deliberate curve choices; this is not a copy of Kakashi’s legacy Radix keyframe implementation. Base UI continues to own presence, focus and dismissal. Transitions use a single `transform` value plus opacity where relevant, so Tailwind v4’s separate scale/translate properties cannot bypass interpolation. Closing or reopening mid-transition reverses from the current rendered position.

Keyboard opening and dismissal remain immediate, including Close and Cancel activation. Reduced motion removes scale and translation: Dialog/Popover keep their fade, while Sheets change position immediately and their modal backdrop can fade. Drag writes only the popup transform, never layout or inherited animation variables. Programmatic openings animate by default; explicit keyboard interactions suppress motion.


---

# Distribution bar

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/distribution-bar
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=876-2

```tsx
import {
  DistributionBar,
  type DistributionSegment,
} from '@commenda/pathfinder/distribution-bar';

const segments: readonly DistributionSegment[] = [
  { id: 'holding', label: 'Commenda Holding LLC', value: 32, color: '1' },
  { id: 'tushar', label: 'Tushar Shudeesh', value: 18.5, color: '2' },
  { id: 'horizon', label: 'Horizon Ventures Pte. Ltd.', value: 15, color: '3' },
  { id: 'priya', label: 'Priya Sharma', value: 14, color: '4' },
  { id: 'daniel', label: 'Daniel Kim', value: 9.5, color: '5' },
  { id: 'elena', label: 'Elena Petrova', value: 6, color: '6' },
  {
    id: 'other-a',
    label: 'Aleksandra Wiśniewska-Kowalczyk',
    value: 3,
    color: '1',
  },
  { id: 'other-b', label: 'Jo', value: 2, color: '2' },
];

export const DistributionBarDefault = () => (
  <DistributionBar
    label="Ownership distribution"
    segments={segments}
    legend="inline"
  />
);
```


Import from `@commenda/pathfinder/distribution-bar` and load the shared stylesheet once.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Accessible figure caption |
| `segments` | `readonly DistributionSegment[]` | required | `{ id, label, value, color }`; IDs must be unique |
| `total` | `number` | optional | Sum when omitted; explicit totals support remaining allocation |
| `size` | `"sm" \| "md"` | optional | 6px / 8px; defaults to md |
| `legend` | `"inline" \| "list" \| "none"` | optional | Inline by default; none retains an accessible breakdown |
| `formatValue` | `((value: number) => string)` | optional | Numeric formatting for values |
| `highlightConfig` | `{ activeId: string \| null; onActiveChange: (id: string \| null) => void; }` | optional | Optional controlled highlighting for a linked table |
| `className` | `string` | optional | Root styling |

### highlightConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activeId` | `string \| null` | Yes |  |
| `onActiveChange` | `(id: string \| null) => void` | Yes |  |

`color` accepts `1` through `6`, `other`, and semantic `success / warning / error / info / neutral`. Assign it by identity before sorting so the same holder keeps the same color. Categorical colors come from Figma's data palette; red belongs to status breakdowns.

## List legend [#list-legend]


```tsx
import {
  DistributionBar,
  type DistributionSegment,
} from '@commenda/pathfinder/distribution-bar';

const segments: readonly DistributionSegment[] = [
  { id: 'holding', label: 'Commenda Holding LLC', value: 32, color: '1' },
  { id: 'tushar', label: 'Tushar Shudeesh', value: 18.5, color: '2' },
  { id: 'horizon', label: 'Horizon Ventures Pte. Ltd.', value: 15, color: '3' },
  { id: 'priya', label: 'Priya Sharma', value: 14, color: '4' },
  { id: 'daniel', label: 'Daniel Kim', value: 9.5, color: '5' },
  { id: 'elena', label: 'Elena Petrova', value: 6, color: '6' },
  {
    id: 'other-a',
    label: 'Aleksandra Wiśniewska-Kowalczyk',
    value: 3,
    color: '1',
  },
  { id: 'other-b', label: 'Jo', value: 2, color: '2' },
];

export const DistributionBarLegend = () => (
  <DistributionBar
    label="Ownership distribution"
    segments={segments}
    legend="list"
    formatValue={(value) => `${String(value)} shares`}
  />
);
```


The largest parts appear first. Above six items, the largest five remain individual and the rest form Other. Every source member remains in the accessible breakdown and Other tooltip. Hovering a segment or focusing a legend entry highlights its group. A linked table can supply a source member ID to highlight Other when that member is grouped. The generated Other ID starts at `__other__`, adding leading underscores if needed to avoid collisions.

## Remaining allocation [#remaining-allocation]


```tsx
import {
  DistributionBar,
  type DistributionSegment,
} from '@commenda/pathfinder/distribution-bar';

const segments: readonly DistributionSegment[] = [
  { id: 'holding', label: 'Commenda Holding LLC', value: 32, color: '1' },
  { id: 'tushar', label: 'Tushar Shudeesh', value: 18.5, color: '2' },
  { id: 'horizon', label: 'Horizon Ventures Pte. Ltd.', value: 15, color: '3' },
  { id: 'priya', label: 'Priya Sharma', value: 14, color: '4' },
  { id: 'daniel', label: 'Daniel Kim', value: 9.5, color: '5' },
  { id: 'elena', label: 'Elena Petrova', value: 6, color: '6' },
  {
    id: 'other-a',
    label: 'Aleksandra Wiśniewska-Kowalczyk',
    value: 3,
    color: '1',
  },
  { id: 'other-b', label: 'Jo', value: 2, color: '2' },
];

export const DistributionBarRemainder = () => (
  <DistributionBar
    label="Capacity"
    total={100}
    size="sm"
    segments={[{ id: 'used', label: 'Used', value: 38, color: '1' }]}
  />
);
```


The unused total remains as track. A visual 4px minimum helps tiny positive parts remain visible; numeric shares are authoritative. Zero-valued entries remain in the legend but have no painted segment.

## Over-allocation [#over-allocation]


```tsx
import {
  DistributionBar,
  type DistributionSegment,
} from '@commenda/pathfinder/distribution-bar';

const segments: readonly DistributionSegment[] = [
  { id: 'holding', label: 'Commenda Holding LLC', value: 32, color: '1' },
  { id: 'tushar', label: 'Tushar Shudeesh', value: 18.5, color: '2' },
  { id: 'horizon', label: 'Horizon Ventures Pte. Ltd.', value: 15, color: '3' },
  { id: 'priya', label: 'Priya Sharma', value: 14, color: '4' },
  { id: 'daniel', label: 'Daniel Kim', value: 9.5, color: '5' },
  { id: 'elena', label: 'Elena Petrova', value: 6, color: '6' },
  {
    id: 'other-a',
    label: 'Aleksandra Wiśniewska-Kowalczyk',
    value: 3,
    color: '1',
  },
  { id: 'other-b', label: 'Jo', value: 2, color: '2' },
];

export const DistributionBarOverflow = () => (
  <DistributionBar
    label="Ownership allocation"
    total={80}
    segments={segments}
    legend="list"
  />
);
```


When the sum exceeds the total, the bar scales to the sum and a persistent Alert explains the original percentage. Negative, non-finite, duplicate-ID, and invalid-total inputs produce an error rather than misleading geometry. Empty/zero allocations show an empty track. This is a figure with a data breakdown, not an ARIA progressbar.

Read the [record component rules](/docs/components/distribution-bar#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule             | Contract and provenance                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| DISTRIBUTION-001 | Figma 876:59943 / 883:100: 6/8px track, 2px gaps, identity-stable data colors.                                      |
| DISTRIBUTION-002 | Six visible groups maximum, five plus Other when necessary; source members remain available.                        |
| DISTRIBUTION-003 | Unallocated remainder stays track. Over-allocation scales geometry and explains the original percentage.            |
| DISTRIBUTION-004 | Visual minimum 4px is not numeric precision. Keep exact shares and a textual breakdown, including with legend=none. |

### Recorded design decisions [#recorded-design-decisions]

The Figma distribution instance paints six categories plus Other, while its documentation says at most six parts. The approved implementation plan uses six total (five plus Other when grouping). Tiny segments use constrained minimum widths, so the legend and tooltip supply exact data. Supporting text uses soft-pearl 800 where lighter Figma text would miss contrast requirements.


---

# Drag handle

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/drag-handle
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=694-2

```tsx
import { DragHandle } from '@commenda/pathfinder/drag-handle';

// Inside a sortable item; the owner supplies sensors, order and announcements.
<DragHandle
  ref={setActivatorNodeRef}
  {...attributes}
  {...listeners}
  label={`Reorder ${item.label}`}
  dragging={isDragging}
/>;
```


## Usage [#usage]

```tsx
import { DragHandle } from '@commenda/pathfinder/drag-handle';

<DragHandle
  ref={setActivatorNodeRef}
  {...attributes}
  {...listeners}
  label={`Reorder ${item.label}`}
  dragging={isDragging}
  disabled={item.pinned}
  disabledReason="Pinned items cannot move"
/>;
```

## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Visible field label. Supply an accessible name when it is omitted. |
| `dragging` | `boolean` | optional |  |
| `disabledReason` | `string` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |

The handle is an activator; it does not reorder data by itself. The playground uses dnd-kit as a documentation-only dependency, not a runtime dependency of the exported component. Application code owns stable IDs, ordering, sensors, movement, drop feedback, announcements and cancellation. Copy the integration pattern from the playground when connecting your sortable owner.

`DRAG-ALTERNATIVES-01`: Space/Enter picks up and drops, arrows move, Escape restores original order. Announce pickup, positions, drop and cancellation. Provide Move up, Move down and Move to top alternatives. Touch uses 250ms long press with a movement tolerance; ordinary page scroll remains possible before activation.

`DRAG-GEOMETRY-01`: Keep the handle inside the row at its leading edge. Reserve its space while hidden; reveal on hover and focus-within. On touch always show it with a 44px target. Desktop is a 16px glyph in a 16×24 area. Rest/hover/pressed use soft-pearl 700/800/900; disabled uses 400. Pinned items require an explanation. Do not apply handles to tabs or palette cards that drag by the whole item. Never use deprecated aria-grabbed.

ResizeHandle is separate future work despite sharing the Figma sheet; DragHandle has no resize mode. Do not claim the activator alone implements these integration behaviors.

Import `@commenda/pathfinder/styles.css` once at the app root. Event handlers require a client component in Next.js App Router.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Reordering [#reordering]

- `DRAG-ALTERNATIVES-01` — Figma integration requirement: focus handle, Space/Enter pickup/drop, arrows move immediately, Escape cancels. Announce each move with position and count. Supply Move up/down/to top alternatives. A 250ms long press starts touch dragging; scrolling stops during active dragging. Handle alone cannot implement ordering; application/sortable owner supplies behavior.

- `DRAG-GEOMETRY-01` — Figma: leading inside the row, never hanging outside. Reserve space while hidden; reveal on hover/focus, always on touch. Desktop 16px glyph in 16×24 area; touch target 44px. Soft-pearl 700 rest, 800 hover, 900 pressed, 400 disabled. Input-style focus ring. Pinned items have a reason. Whole-item draggable tabs/palette cards do not get a handle.

- `DRAG-FUTURE-01` — ResizeHandle is separate future work. Source specifies arrows 16, Shift 64, Home/End limits, Enter or double-click reset. Do not add resize semantics to DragHandle.


---

# Dropdown

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/dropdown
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=92-2

```tsx
import { Dropdown } from '@commenda/pathfinder/dropdown';
import { Button } from '@commenda/pathfinder/button';

<Dropdown
  trigger={<Button variant="secondary">Entity actions</Button>}
  menu={menu}
/>;
```


## Usage [#usage]

```tsx
import { Button, Dropdown, type DropdownMenu } from '@commenda/pathfinder';

const menu: DropdownMenu = {
  groups: [
    {
      id: 'actions',
      items: [
        { id: 'edit', type: 'action', label: 'Edit details', onClick: onEdit },
        {
          id: 'export',
          type: 'submenu',
          label: 'Export',
          menu: {
            groups: [
              {
                id: 'formats',
                items: [
                  {
                    id: 'csv',
                    type: 'action',
                    label: 'Export CSV',
                    onClick: onExportCsv,
                  },
                ],
              },
            ],
          },
        },
      ],
    },
  ],
};

<Dropdown
  trigger={<Button variant="secondary">Entity actions</Button>}
  menu={menu}
/>;
```

## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `trigger` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | required | Required element forwarding refs and events; use Button or IconButton. |
| `menu` | `DropdownMenu` | required | Required menu definition. See the object fields and menu structure below. |
| `open` | `boolean` | conditional | Controlled visibility. Provide onOpenChange when using this prop. |
| `defaultOpen` | `boolean` | optional | Initial uncontrolled visibility; defaults to false. |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Called when visibility changes. Required in controlled mode. |
| `side` | `Side` | optional | Preferred side; defaults to bottom. Adjusts for viewport collisions. |
| `align` | `Align` | optional | Preferred alignment; defaults to start. |
| `sideOffset` | `number` | optional | Gap from the trigger in pixels; defaults to 4. |
| `portalContainer` | `HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null` | optional | Optional destination for the menu portal. |
| `disabled` | `boolean` | optional | Disables the trigger. |
| `disabledReason` | `string` | optional | Explanation for an unavailable trigger. |

### menu fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | `DropdownGroup[]` | Yes |  |

## Menu structure [#menu-structure]

`menu.groups` is an array of `DropdownGroup` objects:

| Field   | Type             | Behavior                        |
| ------- | ---------------- | ------------------------------- |
| `id`    | `string`         | Required stable group identity. |
| `label` | `string`         | Optional visible group heading. |
| `items` | `DropdownItem[]` | Required ordered menu items.    |

Every item has these shared fields:

| Field            | Type        | Behavior                                             |
| ---------------- | ----------- | ---------------------------------------------------- |
| `id`             | `string`    | Required stable identity within its group.           |
| `label`          | `string`    | Required visible text and typeahead label.           |
| `leadingIcon`    | `ReactNode` | Optional decorative icon.                            |
| `description`    | `string`    | Optional supporting text.                            |
| `trailingText`   | `string`    | Optional display hint; does not register a shortcut. |
| `disabled`       | `boolean`   | Prevents activation.                                 |
| `disabledReason` | `string`    | Explanation for an unavailable item.                 |

Choose exactly one item kind:

| Kind      | Required field                     | Behavior                                               |
| --------- | ---------------------------------- | ------------------------------------------------------ |
| `action`  | `onClick: () => void`              | Runs an action. Supports optional `destructive`.       |
| `link`    | `linkConfig: NavigationLinkConfig` | Navigates to a URL.                                    |
| `submenu` | `menu: DropdownMenu`               | Opens another menu using the same recursive structure. |

- `type: 'action'` requires `onClick`, permits `destructive`, and cannot have `menu`.
- `type: 'link'` requires `linkConfig: { href; target?; rel?; render? }` and renders a native anchor. Its optional render adapter forwards anchor props and ref for Next Link. It cannot have onClick or a submenu.
- `type: 'submenu'` requires another `DropdownMenu` and cannot have `onClick` or `destructive`.

`DROPDOWN-RECURSION-01`: Supply an acyclic tree with stable sibling IDs. Submenus recurse with the same rules at every level; there is no fixed depth limit. Prefer shallow menus for usability. Shortcuts in trailing text are display hints, not registered key bindings. Actions close the menu by default; callbacks work from both pointer and keyboard.

## Keyboard and accessibility [#keyboard-and-accessibility]

Enter/Space/ArrowDown opens. Arrows navigate items; inline-end opens a submenu and inline-start returns (directions reverse in RTL). Escape closes the current submenu before its parent. Focus returns to the invoking trigger. Disabled branches never open or execute. Disabled reasons are visible/described on rows. Labels support typeahead. Portal positioning constrains menus to available viewport space.

## Menu versus Select [#menu-versus-select]

`DROPDOWN-SEMANTICS-01`: This component invokes actions. Select and MultiSelect are separate field components using selection primitives. Their popup/row appearance can share private presentation; roles, keyboard behavior and value state cannot be copied from Menu. A checkmark alone does not define a Select. Dropdown itself does not expose search, selection values, checkbox rows, or remote loading props.

`DROPDOWN-ACTIONS-01`: Group related actions with dividers. Put destructive actions last, never first or alone, and confirm consequential destruction in the application. Use icons for actions; trailing text holds shortcuts, counts, formats or ages. No actions shows an empty message.

Import `@commenda/pathfinder/styles.css` once at the app root. Event handlers require a client component in Next.js App Router.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Menus and selection [#menus-and-selection]

- `DROPDOWN-SEMANTICS-01` — Pathfinder: Dropdown invokes actions. Select and MultiSelect have their own value, search and selection contracts and appropriate semantics. A checkmark does not determine the component role. Use Dropdown for commands, and Select or MultiSelect for field values.

- `DROPDOWN-RECURSION-01` — Pathfinder: acyclic menu data, stable sibling IDs, mutually exclusive action/link/submenu types, identical behavior at every recursive depth. Based on Kakashi's data approach, rebuilt over Base UI without private workspace runtime dependencies. Prefer shallow navigation even though the renderer has no fixed depth limit.

- `DROPDOWN-ACTIONS-01` — Figma: group with dividers; destructive action last, never first or alone, usually followed by application confirmation. Icons identify actions; flags identify entities/jurisdictions. Trailing text is right-aligned shortcut/count/format/age metadata. Only one row is highlighted. Open below the trigger with collision handling. Pointer opening may animate from the trigger; keyboard opening is immediate.


---

# Empty state

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/empty-state
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=331-2

```tsx
import { EmptyState } from '@commenda/pathfinder/empty-state';
<EmptyState
  headingLevel={2}
  kind="first-use"
  title="No filings yet"
  description="Filings you create, or that we prepare for you, show up here."
  primaryAction={{ label: 'Create filing', onClick: onCreateFiling }}
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { EmptyState } from '@commenda/pathfinder/empty-state';
<EmptyState
  kind="first-use"
  title="No filings yet"
  description="Filings you create, or that we prepare for you, show up here."
  primaryAction={{ label: 'Create filing', onClick: onCreateFiling }}
/>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `kind` | `"error" \| "first-use" \| "no-results" \| "all-done" \| "no-access"` | required | Required |
| `title` | `string` | required | Required, sentence case |
| `description` | `string` | optional | Optional supporting explanation |
| `size` | `"section" \| "page"` | optional | section; 32 / 64 px vertical padding |
| `headingLevel` | `2 \| 3 \| 4` | optional | 3 |
| `primaryAction` | `FeedbackAction` | optional | Second only for a genuine alternate path |
| `secondaryAction` | `FeedbackAction` | optional | Second only for a genuine alternate path |
| `referenceId` | `string` | optional | Only available for kind="error" |
| `className` | `string` | optional | Parent layout customization |

Replace the table body, card or content region, rather than leaving an empty table beside the message. First-use invites creation, no-results offers a way back, no-access explains who can grant access, and error offers retry. Use Skeleton until loading completes. The caller owns retry/loading, subsequent content replacement and focus. Page size fills its parent, not the viewport. The source prototype’s 1.2-second delay is not production behavior.

### Actions [#actions]

`FeedbackAction` requires a label and exactly one of `onClick` (command) or `href` (native navigation). Commands support `disabled`, `disabledReason`, `loadingConfig`, and `leadingIcon`; navigation supports `target`, `rel`, and `leadingIcon`. The application owns async work and retry state.

## Examples [#examples]

### Kinds [#kinds]


```tsx
<>
  <EmptyState
    headingLevel={2}
    kind="first-use"
    title="No filings yet"
    description="Filings you create, or that we prepare for you, show up here."
    primaryAction={{ label: 'Create filing', onClick: onAction }}
  />
  <EmptyState
    headingLevel={2}
    kind="no-results"
    title="No results for “Delaware 2027”"
    description="Try a different search, or clear the filters."
    primaryAction={{ label: 'Clear filters', onClick: onAction }}
  />
  <EmptyState
    headingLevel={2}
    kind="all-done"
    title="You’re all caught up"
    description="No tasks need you right now. New ones show up here."
    primaryAction={{ label: 'View completed', onClick: onAction }}
  />
  <EmptyState
    headingLevel={2}
    kind="no-access"
    title="You don’t have access"
    description="Ask an admin to give you access to Transfer pricing."
    primaryAction={{ label: 'Request access', onClick: onAction }}
  />
  <EmptyState
    headingLevel={2}
    kind="error"
    referenceId="EXP-42"
    title="Could not load filings"
    description="Check your connection and try again."
    primaryAction={{ label: 'Try again', onClick: onAction }}
  />
</>;
```


### Page [#page]


```tsx
import { EmptyState } from '@commenda/pathfinder/empty-state';
<EmptyState
  headingLevel={2}
  kind="first-use"
  size="page"
  title="No filings yet"
  description="Filings you create, or that we prepare for you, show up here."
  primaryAction={{ label: 'Create filing', onClick: onCreateFiling }}
/>;
```


Read the [design guidance](/docs/components/empty-state#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Empty state — 331:2 [#empty-state--3312]

- **EMPTY-01:** Replace the content region with an explanation of why it is empty and what fills it. Do not place the message beside an empty table. First-use invites creation; no-results names the search when possible and offers a way back; all-done acknowledges completion; no-access explains who grants access; error explains failure and offers retry.
- **EMPTY-02:** Sentence-case title without a period, description in one or two concise lines. One useful action, a second only for a genuine alternative. Show error references only where support uses them; never display a raw error code alone. Skeleton remains until loading has actually completed.
- **EMPTY-03:** Plain neutral 24 px source icon; no illustration or featured circle. Heading/15 title, Copy/13 description with 400 px max width; gap 12, text gap 4, actions gap 8/padding-top 4. Horizontal padding 24; page vertical 64, section vertical 32. Page fills the parent content region, not the viewport.
- **EMPTY-04:** Application owns retry/loading and replacement content. Preserve focus and layout when content arrives. The source prototype's 1.2-second timer illustrates an asynchronous request and is not a production default.


---

# File card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/file-card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=291-146

```tsx
import { FileCard } from '@commenda/pathfinder/file-card';

<FileCard
  file={{
    id: 'return',
    filename: 'Q3 2026 sales tax return.pdf',
    sizeBytes: 1_200_000,
    upload: { status: 'uploading', progress: 64 },
  }}
  actionConfig={{ onCancel: cancelUpload }}
/>;
```


## Usage [#usage]

```tsx
import { FileCard } from '@commenda/pathfinder/file-card';

<FileCard
  file={{
    id: 'return',
    filename: 'Q3 2026 sales tax return.pdf',
    sizeBytes: 1_200_000,
    upload: { status: 'uploading', progress: 64 },
  }}
  actionConfig={{ onCancel: cancelUpload }}
/>;
```

Use this card independently in a form or let [File upload](/docs/components/file-upload) compose it. File icons come from the filename extension; unknown extensions use the generic file icon. File sizes use decimal units, so 1,000,000 bytes is 1 MB. Omit `sizeBytes` when it is unknown.

## State and actions [#state-and-actions]

| State     | Data                                         | Available actions         |
| --------- | -------------------------------------------- | ------------------------- |
| Uploading | `{ status: 'uploading', progress?: number }` | Cancel                    |
| Complete  | `{ status: 'complete' }`                     | Preview, Download, Remove |
| Failed    | `{ status: 'failed', message: string }`      | Retry, Remove             |

A finite progress value is clamped to 0–100; omitted or non-finite progress is indeterminate. Only `status: 'complete'` shows Uploaded. Every action is optional and receives the stable file ID. The card never starts a request, opens a URL, or mutates the file. Actions have accessible names that include the original filename.

## Long filenames and errors [#long-filenames-and-errors]

Names truncate with their full text preserved in the title tooltip. Errors wrap and increase card height, keeping Retry and Remove available. Standalone cards leave list-level focus recovery and announcements to their owner; FileUpload supplies those behaviors.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `file` | `UploadFileItem` | required | Stable `id`, original `filename`, optional `sizeBytes`, and `upload` state |
| `actionConfig` | `FileActionConfig` | optional | `onCancel`, `onRetry`, `onRemove`, `onPreview`, `onDownload`; each receives an ID |
| `disabled` | `boolean` | optional | Disable all provided actions |
| `className` | `string` | optional | Host layout customization |

### file fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `filename` | `string` | Yes |  |
| `sizeBytes` | `number` | No |  |
| `upload` | `UploadState` | Yes |  |

### file.upload fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"uploading"` | Yes |  |
| `progress` | `number` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"complete"` | Yes |  |

#### Option 3

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"failed"` | Yes |  |
| `message` | `string` | Yes |  |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `onCancel` | `((id: string) => void)` | No |  |
| `onRetry` | `((id: string) => void)` | No |  |
| `onRemove` | `((id: string) => void)` | No |  |
| `onPreview` | `((id: string) => void)` | No |  |
| `onDownload` | `((id: string) => void)` | No |  |

`UploadFileItem`, `UploadState`, and `FileActionConfig` are exported from both file-upload and file-card subpaths. The upload state is a discriminated union: failed requires an error message, uploading optionally carries progress, and complete carries neither.

## Design rules [#design-rules]

- **FILE-CARD-01:** A 24px type icon, 12px leading inset/gap, 8px trailing inset, 8px radius, and subtle border. Complete/failed rows have a 56px minimum; uploading has a 63px minimum. Error content may grow.
- **FILE-CARD-02:** Actions reflect lifecycle state. Do not interpret progress reaching 100% as server-confirmed success. Hide actions without callbacks.
- **FILE-CARD-03:** Never rename a file for display or remove a failed upload silently. Preserve the original name, show a specific failure message, and retain retry/removal controls.


---

# File upload

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/file-upload
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=291-146

```tsx
'use client';

import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

// Layout stays inline so copied examples work without documentation-only CSS.
const FileUploadBasic = () => {
  const [files, setFiles] = useState<UploadFileItem[]>([]);

  const onRemove = (id: string) => {
    setFiles((current) => current.filter((file) => file.id !== id));
  };

  const onRetry = (id: string) => {
    setFiles((current) =>
      current.map((file) =>
        file.id === id ? { ...file, upload: { status: 'uploading' } } : file
      )
    );
  };

  return (
    <div
      className="pf-upload-basic"
      style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 480 }}
    >
      <FileUpload
        label="Supporting documents"
        files={files}
        onFilesAccepted={(selected) => {
          // Demo only: replace these manual controls with your upload transport.
          setFiles((current) => [
            ...current,
            ...selected.map(
              (file): UploadFileItem => ({
                id: crypto.randomUUID(),
                filename: file.name,
                sizeBytes: file.size,
                upload: { status: 'uploading' },
              })
            ),
          ]);
        }}
        validationConfig={{
          accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
          maxSizeBytes: 10_000_000,
          maxFiles: 5,
        }}
        actionConfig={{ onCancel: onRemove, onRemove, onRetry }}
      />
      <p
        className="pf-demo-note"
        style={{
          margin: 0,
          fontSize: 12,
          lineHeight: 1.6,
          color: 'var(--pf-color-soft-pearl-800)',
        }}
      >
        No files leave your browser. Choose a PDF or CSV, then simulate the
        result.
      </p>
      <div
        className="pf-demo-actions"
        style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}
      >
        <Button
          variant="secondary"
          disabled={!files.some((file) => file.upload.status === 'uploading')}
          onClick={() => {
            setFiles((current) =>
              current.map((file) =>
                file.upload.status === 'uploading'
                  ? { ...file, upload: { status: 'complete' } }
                  : file
              )
            );
          }}
        >
          Complete uploads
        </Button>
        <Button
          variant="secondary"
          disabled={!files.some((file) => file.upload.status === 'uploading')}
          onClick={() => {
            setFiles((current) =>
              current.map((file) =>
                file.upload.status === 'uploading'
                  ? {
                      ...file,
                      upload: {
                        status: 'failed',
                        message: 'Upload failed. Retry to try again.',
                      },
                    }
                  : file
              )
            );
          }}
        >
          Fail uploads
        </Button>
      </div>
    </div>
  );
};

export default FileUploadBasic;
```


## Usage [#usage]

```tsx
import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

<FileUpload
  label="Supporting documents"
  files={files}
  onFilesAccepted={startUploads}
  validationConfig={{
    accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
    maxSizeBytes: 10_000_000,
    maxFiles: 5,
  }}
  actionConfig={{
    onCancel: cancelUpload,
    onRetry: retryUpload,
    onRemove: removeFile,
    onPreview: previewFile,
    onDownload: downloadFile,
  }}
/>;
```

The first example keeps files in memory and never uploads them. Pick a PDF or CSV, then use **Complete uploads** or **Fail uploads** to simulate a result. Retry returns a failed card to uploading. Its Code tab includes all state and handlers; replace the simulation with your upload transport.

Append accepted files to controlled `files` immediately, with stable IDs and `upload: { status: 'uploading', progress: 0 }`. Start your upload in `onFilesAccepted`; update progress from actual transport events and set `complete` only after the server confirms success. Retain the original `File` objects in your application for retries. Keep completed and failed cards in selection order, newest last.

## Compact button [#compact-button]


```tsx
'use client';

import { useState } from 'react';

import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

// Layout stays inline so copied examples work without documentation-only CSS.
const FileUploadButton = () => {
  const [files, setFiles] = useState<UploadFileItem[]>([]);

  const onRemove = (id: string) => {
    setFiles((current) => current.filter((file) => file.id !== id));
  };

  const onRetry = (id: string) => {
    setFiles((current) =>
      current.map((file) =>
        file.id === id ? { ...file, upload: { status: 'uploading' } } : file
      )
    );
  };

  return (
    <div
      className="pf-upload-basic"
      style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 480 }}
    >
      <FileUpload
        label="Supporting documents"
        variant="button"
        files={files}
        onFilesAccepted={(selected) => {
          // Demo only: replace these manual controls with your upload transport.
          setFiles((current) => [
            ...current,
            ...selected.map(
              (file): UploadFileItem => ({
                id: crypto.randomUUID(),
                filename: file.name,
                sizeBytes: file.size,
                upload: { status: 'uploading' },
              })
            ),
          ]);
        }}
        validationConfig={{
          accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
          maxSizeBytes: 10_000_000,
          maxFiles: 5,
        }}
        actionConfig={{ onCancel: onRemove, onRemove, onRetry }}
      />
    </div>
  );
};

export default FileUploadButton;
```


Use the button where a dropzone would compete with the form. Limits remain visible beside it and wrap on narrow screens. The dropzone itself is a single native button: its entire area opens the file picker with pointer, Enter, or Space; “browse” is styled text, not a nested button.

## Single file [#single-file]


```tsx
'use client';

import { useState } from 'react';

import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

// Layout stays inline so copied examples work without documentation-only CSS.
const FileUploadSingle = () => {
  const [files, setFiles] = useState<UploadFileItem[]>([]);

  const onRemove = (id: string) => {
    setFiles((current) => current.filter((file) => file.id !== id));
  };

  const onRetry = (id: string) => {
    setFiles((current) =>
      current.map((file) =>
        file.id === id ? { ...file, upload: { status: 'uploading' } } : file
      )
    );
  };

  return (
    <div
      className="pf-upload-basic"
      style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 480 }}
    >
      <FileUpload
        label="Supporting documents"
        files={files}
        onFilesAccepted={(selected) => {
          // Demo only: replace these manual controls with your upload transport.
          setFiles((current) => [
            ...current,
            ...selected.map(
              (file): UploadFileItem => ({
                id: crypto.randomUUID(),
                filename: file.name,
                sizeBytes: file.size,
                upload: { status: 'uploading' },
              })
            ),
          ]);
        }}
        validationConfig={{
          accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
          maxSizeBytes: 10_000_000,
          maxFiles: 1,
        }}
        actionConfig={{ onCancel: onRemove, onRemove, onRetry }}
      />
    </div>
  );
};

export default FileUploadSingle;
```


`validationConfig.maxFiles: 1` replaces the picker with the selected file's card. Cancel or remove that card to choose another file. Supply those callbacks to allow replacement. Multiple-file mode keeps the picker visible; exceeding the limit reports a rejection. Existing uploading, failed, and completed items all count toward the limit.

## Upload states and recovery [#upload-states-and-recovery]


```tsx
'use client';

import { useState } from 'react';

import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

// Layout stays inline so copied examples work without documentation-only CSS.
const FileUploadStates = () => {
  const [files, setFiles] = useState<UploadFileItem[]>([
    {
      id: 'uploading',
      filename: 'Board resolution, signed.pdf',
      sizeBytes: 1200000,
      upload: { status: 'uploading', progress: 64 },
    },
    {
      id: 'complete',
      filename: 'Q3 2026 sales tax return.pdf',
      sizeBytes: 1200000,
      upload: { status: 'complete' },
    },
    {
      id: 'failed',
      filename: 'Nexus study, California.csv',
      sizeBytes: 2000000,
      upload: {
        status: 'failed',
        message: 'Upload failed. Retry to try again.',
      },
    },
  ]);

  const onRemove = (id: string) => {
    setFiles((current) => current.filter((file) => file.id !== id));
  };

  const onRetry = (id: string) => {
    setFiles((current) =>
      current.map((file) =>
        file.id === id ? { ...file, upload: { status: 'uploading' } } : file
      )
    );
  };

  return (
    <div
      className="pf-upload-basic"
      style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 480 }}
    >
      <FileUpload
        label="Supporting documents"
        files={files}
        onFilesAccepted={(selected) => {
          // Demo only: replace these manual controls with your upload transport.
          setFiles((current) => [
            ...current,
            ...selected.map(
              (file): UploadFileItem => ({
                id: crypto.randomUUID(),
                filename: file.name,
                sizeBytes: file.size,
                upload: { status: 'uploading' },
              })
            ),
          ]);
        }}
        validationConfig={{
          accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
          maxSizeBytes: 10_000_000,
          maxFiles: 5,
        }}
        actionConfig={{ onCancel: onRemove, onRemove, onRetry }}
      />
    </div>
  );
};

export default FileUploadStates;
```


Uploading shows progress and Cancel. Completed files offer Preview, Download, and Remove when those callbacks exist. Failed files retain their filename and error with Retry and Remove. Unknown progress is indeterminate; 100% alone does not mean success. No operation blocks the surrounding page. Removing a focused action restores focus to an available control within the uploader.

## Validation and errors [#validation-and-errors]


```tsx
'use client';

import { useState } from 'react';

import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

// Layout stays inline so copied examples work without documentation-only CSS.
const FileUploadError = () => {
  const [files, setFiles] = useState<UploadFileItem[]>([]);

  const onRemove = (id: string) => {
    setFiles((current) => current.filter((file) => file.id !== id));
  };

  const onRetry = (id: string) => {
    setFiles((current) =>
      current.map((file) =>
        file.id === id ? { ...file, upload: { status: 'uploading' } } : file
      )
    );
  };

  return (
    <div
      className="pf-upload-basic"
      style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 480 }}
    >
      <FileUpload
        label="Supporting documents"
        errorConfig={{ message: 'Choose a file smaller than 10 MB.' }}
        files={files}
        onFilesAccepted={(selected) => {
          // Demo only: replace these manual controls with your upload transport.
          setFiles((current) => [
            ...current,
            ...selected.map(
              (file): UploadFileItem => ({
                id: crypto.randomUUID(),
                filename: file.name,
                sizeBytes: file.size,
                upload: { status: 'uploading' },
              })
            ),
          ]);
        }}
        validationConfig={{
          accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
          maxSizeBytes: 10_000_000,
          maxFiles: 5,
        }}
        actionConfig={{ onCancel: onRemove, onRemove, onRetry }}
      />
    </div>
  );
};

export default FileUploadError;
```


Empty files are always rejected. An accept entry matches its MIME type (including a wildcard such as `image/*`) **or** one of its extension fallbacks, case-insensitively. Extensions should include their leading dot. A file exactly at `maxSizeBytes` is accepted. Use positive finite size limits and positive integer file limits.

Validation processes selected files in order: valid files fill remaining capacity; rejected files never enter `onFilesAccepted`. `onFilesRejected` receives `{ file, code, message }` for each rejection, with codes `empty`, `type`, `size`, or `count`. Re-selecting the same file works because the native input is reset. Duplicate filenames are not deduplicated: assign distinct IDs or apply your product's duplicate policy in the host.

Limits are generated from `validationConfig`; `description` can provide localized copy. Built-in error messages are English; use `onFilesRejected` with `errorConfig` for application translations. Browser MIME/extension validation is a convenience, not content verification. The server still enforces size, content, permissions, and scanning. No credential, company ID, storage URL, or API client enters this component.

## Disabled state [#disabled-state]


```tsx
'use client';

import { useState } from 'react';

import {
  FileUpload,
  type UploadFileItem,
} from '@commenda/pathfinder/file-upload';

// Layout stays inline so copied examples work without documentation-only CSS.
const FileUploadDisabled = () => {
  const [files, setFiles] = useState<UploadFileItem[]>([
    {
      id: 'uploading',
      filename: 'Board resolution, signed.pdf',
      sizeBytes: 1200000,
      upload: { status: 'uploading', progress: 64 },
    },
    {
      id: 'complete',
      filename: 'Q3 2026 sales tax return.pdf',
      sizeBytes: 1200000,
      upload: { status: 'complete' },
    },
    {
      id: 'failed',
      filename: 'Nexus study, California.csv',
      sizeBytes: 2000000,
      upload: {
        status: 'failed',
        message: 'Upload failed. Retry to try again.',
      },
    },
  ]);

  const onRemove = (id: string) => {
    setFiles((current) => current.filter((file) => file.id !== id));
  };

  const onRetry = (id: string) => {
    setFiles((current) =>
      current.map((file) =>
        file.id === id ? { ...file, upload: { status: 'uploading' } } : file
      )
    );
  };

  return (
    <div
      className="pf-upload-basic"
      style={{ display: 'grid', gap: 16, width: '100%', maxWidth: 480 }}
    >
      <FileUpload
        label="Supporting documents"
        disableConfig={{
          isDisabled: true,
          reason: 'You have read-only access.',
        }}
        files={files}
        onFilesAccepted={(selected) => {
          // Demo only: replace these manual controls with your upload transport.
          setFiles((current) => [
            ...current,
            ...selected.map(
              (file): UploadFileItem => ({
                id: crypto.randomUUID(),
                filename: file.name,
                sizeBytes: file.size,
                upload: { status: 'uploading' },
              })
            ),
          ]);
        }}
        validationConfig={{
          accept: { 'application/pdf': ['.pdf'], 'text/csv': ['.csv'] },
          maxSizeBytes: 10_000_000,
          maxFiles: 5,
        }}
        actionConfig={{ onCancel: onRemove, onRemove, onRetry }}
      />
    </div>
  );
};

export default FileUploadDisabled;
```

Disabled state prevents file acceptance and card actions. Use a reason to
explain unavailable access. Long original filenames truncate visually with a
native full-name tooltip; error messages wrap. File selection, progress, and
failure are announced through status changes without announcing every progress
percentage.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required accessible field name |
| `hideLabel` | `boolean` | optional | Visually hide the field label |
| `variant` | `"button" \| "dropzone"` | optional | Picker presentation; defaults to dropzone |
| `files` | `readonly UploadFileItem[]` | required | Controlled list, in host-provided order |
| `onFilesAccepted` | `((files: readonly File[]) => void)` | required | Receive validated files and start host uploads |
| `onFilesRejected` | `((rejections: readonly FileRejection[]) => void)` | optional | Report client-side validation failures |
| `validationConfig` | `FileValidationConfig` | optional | Optional type, size, and count limits |
| `actionConfig` | `FileActionConfig` | optional | Cancel, retry, remove, preview, download callbacks by ID |
| `disableConfig` | `{ isDisabled: boolean; reason?: string; }` | optional | Disable selection and card actions |
| `description` | `string` | optional | Override generated visible limits |
| `errorConfig` | `{ message: string; }` | optional | Host error overrides client validation copy |
| `className` | `string` | optional | Host width/layout; no fixed 480px component width |

### validationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accept` | `Readonly<Record<string, readonly string[]>>` | No | MIME types with extension fallbacks, e.g. {'application/pdf': ['.pdf']}. |
| `maxSizeBytes` | `number` | No |  |
| `maxFiles` | `number` | No | Counts all controlled items, including uploading and failed files. One swaps the picker for its card. |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `onCancel` | `((id: string) => void)` | No |  |
| `onRetry` | `((id: string) => void)` | No |  |
| `onRemove` | `((id: string) => void)` | No |  |
| `onPreview` | `((id: string) => void)` | No |  |
| `onDownload` | `((id: string) => void)` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |

## Design rules and integration [#design-rules-and-integration]

- **FILE-UPLOAD-01:** One dropzone per form where space permits; use a button in compact layouts. Show limits before selection. Radius 8px, dashed Pearl 400 border, 24px zone padding, and 6px content gaps follow the rendered frame.
- **FILE-UPLOAD-02:** Accept valid files immediately and append newest last. Reject invalid files before inserting cards; preserve failed uploads for retry.
- **FILE-UPLOAD-03:** The application owns files, progress, upload cancellation, preview/download, and removal persistence. Update controlled files synchronously when accepting a batch; guard concurrent transport operations and ignore late progress after cancel/removal.
- **FILE-UPLOAD-04:** Full-zone keyboard/pointer activation; restore focus on picker cancellation and card removal. Drag-over tint takes 150ms, inserted cards fade/translate 4px for 200ms, and the existing ProgressBar interpolates for 300ms. Reduced motion removes these transitions.

Kakashi's `MultiFileUploader` supplies useful `accept`, size/count, preview, and upload callback patterns. Its company/authentication props, S3 helper, and signed-URL viewer stay application-owned. Map `FileBasic.fileName` to `filename`, retain IDs separately, and map existing upload results to `upload.status`. No consumer migration is performed. AI `Attachment` remains a compact message/composer presentation; FileCard is the form upload lifecycle row. `UploadRequestCard` can continue its existing integration without an API change.


---

# Icon button

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/icon-button
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=61-3

```tsx
import { IconButton } from '@commenda/pathfinder/icon-button';
import { PlusIcon } from '@commenda/pathfinder/icons/PlusIcon';

<IconButton label="Add entity">
  <PlusIcon />
</IconButton>;
```


## Usage [#usage]

```tsx
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Trash01Icon } from '@commenda/pathfinder/icons/Trash01Icon';

<IconButton
  label="Delete entity"
  destructive
  disabled={!canDelete}
  disabledReason="Only administrators can delete entities"
  onClick={onDelete}
>
  <Trash01Icon />
</IconButton>;
```

## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

## Examples [#examples]

### Variants [#variants]

Primary, Secondary, Tertiary and Plain. Hover or focus each example to inspect its interactive states and tooltip.


```tsx
<>
  <IconButton variant="primary" label="Add entity">
    <PlusIcon />
  </IconButton>
  <IconButton variant="secondary" label="Add entity">
    <PlusIcon />
  </IconButton>
  <IconButton variant="tertiary" label="Add entity">
    <PlusIcon />
  </IconButton>
  <IconButton variant="plain" label="Add entity">
    <PlusIcon />
  </IconButton>
</>;
```


### Sizes [#sizes]


```tsx
<>
  {(['xs', 'sm', 'md', 'lg'] as const).map((size) => (
    <IconButton key={size} size={size} label="Add entity">
      <PlusIcon />
    </IconButton>
  ))}
</>;
```


### Destructive variants [#destructive-variants]

Primary, Secondary and Tertiary support destructive actions. Plain intentionally does not.


```tsx
<>
  <IconButton variant="primary" label="Delete entity" destructive>
    <Trash01Icon />
  </IconButton>
  <IconButton variant="secondary" label="Delete entity" destructive>
    <Trash01Icon />
  </IconButton>
  <IconButton variant="tertiary" label="Delete entity" destructive>
    <Trash01Icon />
  </IconButton>
</>;
```


### Disabled with a reason [#disabled-with-a-reason]

All four variants support disabled actions. Focus or hover to read the reason; activation remains blocked.


```tsx
<>
  {(['primary', 'secondary', 'tertiary', 'plain'] as const).map((variant) => (
    <IconButton
      key={variant}
      variant={variant}
      label="Add entity"
      disabled
      disabledReason="Administrator access required"
    >
      <PlusIcon />
    </IconButton>
  ))}
</>;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Visible field label. Supply an accessible name when it is omitted. |
| `children` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | required |  |
| `className` | `string` | optional | Additional classes for the component root. |
| `size` | `"sm" \| "md" \| "lg" \| "xs"` | optional |  |
| `disabledReason` | `string` | optional |  |
| `tooltip` | `boolean` | optional | Disable the automatic hint when an explicit Tooltip wraps this control. |
| `variant` | `"primary" \| "secondary" \| "tertiary" \| "plain"` | conditional |  |
| `destructive` | `boolean \| false` | optional |  |

`ICON-BUTTON-A11Y-01`: Name the action and target, not the glyph. “More options for Meridian UK Ltd” is useful; “Dots” is not. A disabled reason supplements this name. Tooltips work on focus and hover. With a reason, the disabled control remains focusable but cannot activate. `aria-pressed` is available for toggle actions.

Use tertiary for repeated row actions, secondary when an edge is needed and primary for the single main icon action such as Send. Plain has no hover background. xs is for input clear/chip close controls; never nest a button inside another button. Use a labeled Button when the icon is unfamiliar. Icons use 16px optical artwork through md and 20px at lg. Visual square size alone does not guarantee an adequate touch target; allocate sufficient spacing/hit area in touch layouts.

Import `@commenda/pathfinder/styles.css` once at the app root. Event handlers require a client component in Next.js App Router.

Set `tooltip={false}` when an explicit [Tooltip](/docs/components/tooltip) wraps the control, so it receives one hint. The accessible `label` remains required.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Action rules [#action-rules]

- `CONTROL-SIZE-01` — Figma: Button and SplitButton sm/md/lg have 28/32/36px visual heights; md default. IconButton adds xs 24. Button icons are 16 through md and 20 at lg; pass size to generated icons to select optical artwork. Link styles have text-sized geometry. Long content can increase minimum height for accessibility.

- `CONTROL-FOCUS-01` — Figma: show focus from keyboard, not pointer click. Button family uses a blue ring separated by a white gap. Open triggers retain hover styling. Disabled reason is a Pathfinder extension: retain action name, expose description, and allow focus without activation where the native wrapper supports it.

- `ICON-BUTTON-A11Y-01` — Figma: labels are required and repeated in tooltips. Name action/target, never the glyph. Use familiar icons; otherwise use a text Button. Primary is reserved for the single main icon action. xs is reserved for controls inside a field/chip visually, never nested interactive markup. Touch layouts need adequate target space; 32/36px visual bounds do not themselves provide 44px targets.


---

# Inline reference

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/inline-reference
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=621-441

```tsx
import { InlineReference } from '@commenda/pathfinder/inline-reference';

<InlineReference
  label="Acme Pte Ltd"
  href="/entities/acme"
  previewConfig={{ content: 'Singapore · Active GST registration' }}
/>;
```


## Preview without navigation [#preview-without-navigation]

Without an `href`, a reference with preview content is a button. Click, tap, or Enter opens the existing Pathfinder Popover; Escape closes it and restores focus.


```tsx
<InlineReference
  label="entity details"
  previewConfig={{ title: 'Acme Pte Ltd', content: <EntitySummary /> }}
/>;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required visible and accessible record name |
| `href` | `string` | optional | Native link target; unsafe schemes are rejected |
| `icon` | `ReactNode` | optional | Optional decorative 16px icon or flag |
| `onClick` | `MouseEventHandler<HTMLAnchorElement \| HTMLButtonElement>` | optional | App routing callback; preserve modifier-click behavior when intercepting links |
| `previewConfig` | `{ title?: string; content: ReactNode; isLoading?: boolean; }` | optional | App-supplied preview; defaults title to label |
| `className` | `string` | optional | Optional styling extension |

### previewConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | No |  |
| `content` | `ReactNode` | Yes |  |
| `isLoading` | `boolean` | No |  |

With a URL, hover/focus shows a read-only preview and click retains navigation. Without a URL, click/tap opens a form-mode Popover suitable for interactive content. Without a URL, callback, or preview, the label is noninteractive text.

## Design and accessibility rules [#design-and-accessibility-rules]

- **MARKDOWN-REF-01:** Copy/13 Strong, pearl-1000 text and pearl-400 underline. Reuse an existing Pathfinder flag/icon when appropriate.
- **MARKDOWN-REF-02:** Application owns fetching and navigation. Preserve native link behavior, modified clicks, and touch navigation.
- Essential information must remain available at the destination; a hover preview is supplementary.
- Read-only previews must not contain controls; use the preview-only button form for interactive content.


---

# Input

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/input
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=68-2

```tsx
import { Input } from '@commenda/pathfinder/input';

export const InputDefault = () => (
  <Input
    label="Entity name"
    placeholder="e.g. Meridian UK Ltd"
    description="Use the legal name on the certificate of incorporation."
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { Input } from '@commenda/pathfinder/input';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `type` | `"password" \| "number" \| "search" \| "text" \| "email" \| "url" \| "tel"` | conditional | text |
| `leadingIcon` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | optional | Decorative 16px slot |
| `prefix` | `string` | optional | Non-editable unit segments |
| `suffix` | `string` | optional | Non-editable unit segments |
| `actionConfig` | `FieldActionConfig \| CopyAction \| { kind: "clear"; label?: string; }` | optional | Reveal is password-only; copy supports onCopyError, reveal supports hideLabel |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Accessible name when the field has no visible label. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `value` | `string` | conditional |  |
| `onValueChange` | `((value: string) => void)` | conditional |  |
| `defaultValue` | `string` | optional |  |

### actionConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"copy"` | Yes |  |
| `label` | `string` | No |  |
| `onCopyError` | `((error: Error) => void)` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"clear"` | Yes |  |
| `label` | `string` | No |  |

#### Option 3

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"reveal"` | Yes |  |
| `label` | `string` | No |  |
| `hideLabel` | `string` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

## Shared field props [#shared-field-props]

| Prop            | Type                                                | Behavior                                                     |
| --------------- | --------------------------------------------------- | ------------------------------------------------------------ |
| `label`         | `string`                                            | Visible accessible label; hideLabel hides it visually.       |
| `aria-label`    | `string`                                            | Accessible name when a visible label is not supplied.        |
| `value`         | `string`                                            | Controlled value; provide the corresponding change callback. |
| `defaultValue`  | `string`                                            | Initial value for an uncontrolled control.                   |
| `onValueChange` | `(value: string) => void`                           | Immediate editing changes; no implicit parsing.              |
| `description`   | `string`                                            | Visible supporting guidance.                                 |
| `required`      | `boolean`                                           | Native required semantics and visual asterisk.               |
| `labelConfig`   | `{ optionalLabel }` or `{ help }`                   | One annotation; cannot combine with required.                |
| `errorConfig`   | `{ message, reveal?: 'after-blur' \| 'immediate' }` | Replaces guidance after blur by default.                     |
| `disableConfig` | `{ isDisabled, reason? }`                           | Disables editing; reason stays visible.                      |
| `readOnly`      | `boolean`                                           | Preserves focus, selection, and form submission.             |

Native `name`, `form`, autocomplete, focus/blur handlers, constraints, IDs, ARIA attributes, and typed refs are supported. `className` styles the outer field. Use `onValueChange` for text changes. Form reset restores uncontrolled defaults; controlled values remain application-owned.

## Usage rules [#usage-rules]

Use noun labels in sentence case, examples as placeholders, and actionable error messages. One authored 28px size with radius 6. Copy remains available when editing is disabled. Clear never mutates disabled/read-only input. Password reveal changes visibility without changing the value. Numeric input retains native string editing; currency formatting is not included.

### Segments [#segments]


```tsx
import { Input } from '@commenda/pathfinder/input';

export const InputSegments = () => (
  <Input
    label="Annual revenue"
    prefix="$"
    suffix="USD"
    inputMode="decimal"
    placeholder="e.g. 250000"
  />
);
```


### Actions [#actions]


```tsx
import { Input } from '@commenda/pathfinder/input';

export const InputActions = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <Input
      label="Entity name"
      defaultValue="Meridian UK Ltd"
      actionConfig={{ kind: 'clear' }}
    />
    <Input
      label="Registration number"
      defaultValue="GB123456"
      readOnly
      actionConfig={{ kind: 'copy' }}
    />
    <Input
      label="Password"
      type="password"
      autoComplete="new-password"
      actionConfig={{ kind: 'reveal' }}
    />
  </div>
);
```


### States [#states]


```tsx
import { Input } from '@commenda/pathfinder/input';

export const InputStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <Input label="Required name" required />
    <Input label="Trading name" labelConfig={{ optionalLabel: '(optional)' }} />
    <Input
      label="Jurisdiction"
      labelConfig={{ help: 'The country in which this entity is registered.' }}
    />
    <Input
      label="Entity name"
      errorConfig={{
        message: 'Enter the registered legal name.',
        reveal: 'immediate',
      }}
    />
    <Input
      label="Registration number"
      defaultValue="GB123456"
      disableConfig={{
        isDisabled: true,
        reason: 'Managed by your administrator.',
      }}
      actionConfig={{ kind: 'copy' }}
    />
  </div>
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule      | Source           | Contract                                                                      |
| --------- | ---------------- | ----------------------------------------------------------------------------- |
| INPUT-001 | 68:225, 158:222  | 28px field, radius 6, pearl control border, blue focus glow.                  |
| INPUT-002 | 158:318, 158:819 | One label annotation; units use prefix/suffix, actions use their own segment. |
| INPUT-003 | 158:807, 158:816 | Sentence-case noun label; actionable error replaces guidance after blur.      |
| INPUT-004 | 158:482          | Copy remains available for disabled values.                                   |

All source IDs refer to [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=68-2).

### Explicit implementation decisions [#explicit-implementation-decisions]

True native readOnly remains distinct from disabled despite Figma 158:822 using disabled appearance for non-editable fields. Disabled values do not submit; read-only values do. Disabled editing does not disable the independent copy/reveal actions. Clear cannot modify a disabled/read-only field.

Error reveal defaults to after-blur; immediate reveal supports submission/server errors. Soft-limit feedback is immediate. Applications own validation schemas and server error clearing. Additional required/help guidance belongs in description when the single label annotation is already occupied.

Optional-label text uses pearl 800 instead of the authored pearl 700: browser axe measured the latter at 3.38:1 on white, below the 4.5:1 requirement for this text.


---

# List

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/list
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=1101-2

```tsx
import { useState } from 'react';

import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { List } from '@commenda/pathfinder/list';

export const ListDefault = () => {
  const [selected, setSelected] = useState<string | null>('annual');
  const [pinned, setPinned] = useState(false);

  return (
    <List
      label="Inbox"
      selectedId={selected}
      onSelectionChange={setSelected}
      items={[
        {
          id: 'annual',
          title: 'Delaware annual report',
          description:
            'Thanks. I’ll file it today and send you the receipt here.',
          timestamp: { label: '9:41 AM', dateTime: '2026-10-13T09:41:00' },
          entityConfig: {
            label: 'Commenda Technologies Inc.',
            flag: <USFlag size={12} />,
          },
          unread: true,
          pinned,
          onAction: () => {},
          menuConfig: {
            groups: [
              {
                id: 'actions',
                items: [
                  {
                    id: 'pin',
                    type: 'action',
                    label: pinned ? 'Unpin record' : 'Pin record',
                    onClick: () => {
                      setPinned(!pinned);
                    },
                  },
                ],
              },
            ],
          },
        },
        {
          id: 'tax',
          title: 'Tax registration documents',
          description: 'Your documents are ready for review.',
          timestamp: { label: 'Yesterday' },
          onAction: () => {},
        },
      ]}
    />
  );
};
```


Import from `@commenda/pathfinder/list` and load the shared stylesheet once. This component represents inbox/mailroom records, not bullet lists or selection options.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Accessible list name |
| `items` | `readonly ListItem[]` | required | Stable ID and title; each item has `onAction` or `linkConfig` |
| `selectedId` | `string \| null` | optional | The currently open record |
| `onSelectionChange` | `((id: string) => void)` | optional | Activation notification; app owns selection |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` | optional | Announces loading and marks list busy |
| `emptyContent` | `ReactNode` | optional | Defaults to `No items.` |
| `paginationConfig` | `{ hasMore: boolean; isLoading: boolean; onLoadMore: () => void; }` | optional | App-owned paging with Load more |
| `className` | `string` | optional | Root styling |

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

### paginationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasMore` | `boolean` | Yes |  |
| `isLoading` | `boolean` | Yes |  |
| `onLoadMore` | `() => void` | Yes |  |

Items also accept `description`, `leadingIcon`, `entityConfig: { label, flag }`, `timestamp: { label, dateTime? }`, `unread`, `pinned`, and `menuConfig` using Dropdown's existing menu groups. `linkConfig` preserves native link behavior and supports an anchor-compatible `render` function for Next Link. More is a separate control; it never activates the row.

Titles, entity names, and previews truncate with the full text retained in the DOM and native title. The selected row retains the same font weight. Time and More share reserved space, with menus available on focus and touch.

## Loading and empty states [#loading-and-empty-states]


```tsx
import { List } from '@commenda/pathfinder/list';

export const ListStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <List label="Empty inbox" items={[]} emptyContent="No messages yet." />
    <List
      label="Loading inbox"
      items={[]}
      loadingConfig={{ isLoading: true }}
    />
  </div>
);
```


## Paging [#paging]


```tsx
import { useState } from 'react';

import { List } from '@commenda/pathfinder/list';

export const ListPagination = () => {
  const [count, setCount] = useState(3);

  return (
    <List
      label="Filings"
      items={Array.from({ length: count }, (_, index) => ({
        id: String(index),
        title: `Filing ${String(index + 1)}`,
        linkConfig: { href: `#filing-${String(index + 1)}` },
      }))}
      paginationConfig={{
        hasMore: count < 9,
        isLoading: false,
        onLoadMore: () => {
          setCount(count + 3);
        },
      }}
    />
  );
};
```


Use server paging for large datasets. List renders the provided page without virtualization; avoid loading an entire unbounded inbox. It does not fetch or automatically advance pages. Read the [record component rules](/docs/components/list#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule     | Contract and provenance                                                                                                          |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| LIST-001 | Figma 1101:3: 80px minimum inbox/mailroom rows, stable font weight; selected soft-pearl 300.                                     |
| LIST-002 | Native record link/action and a separate More button. No nested buttons or accidental record activation from its menu.           |
| LIST-003 | Application owns paging, selection, and remote state. Timestamp swaps with More without shifting content; touch exposes actions. |


---

# Markdown

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/markdown
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=620-31413

```tsx
import { Markdown } from '@commenda/pathfinder/markdown';

<Markdown content={messageText} referenceConfig={referenceConfig} />;
```


## Usage [#usage]

```tsx
import { Markdown } from '@commenda/pathfinder/markdown';

<Markdown content={messagePart.text} isStreaming={status === 'streaming'} />;
```

Pass each text part without flattening tool calls, attachments, or other message parts into Markdown. The renderer needs no chat provider or AI SDK runtime.

## Streaming [#streaming]

Incomplete fences and formatting remain readable while content arrives. Finished blocks use the same components and styles as static content.


```tsx
<Markdown content={streamedText} isStreaming={status === 'streaming'} />;
```


## References [#references]

Resolve known record URLs using application data. Pathfinder renders the reference and preview; the application supplies routing and data access.

```tsx
<Markdown
  content={messagePart.text}
  referenceConfig={{
    resolve: (href, label) =>
      href === '/entities/acme'
        ? {
            label,
            href,
            previewConfig: {
              title: 'Acme Pte Ltd',
              content: <EntitySummary entity={entity} />,
            },
          }
        : undefined,
  }}
/>
```

Use an icon in the resolved reference to add the correct Pathfinder flag to an entity in a table. The renderer does not infer countries from names.

## Tables [#tables]

Tables use compact Pathfinder cell styles, a pinned first column, horizontal scrolling, copy as TSV, CSV/Markdown downloads, and an expanded dialog. Use Markdown alignment markers (`---:`) for numeric columns. Rich cell overrides can use existing Pathfinder cells; sorting, editing, and pagination belong in the standalone Table component.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `content` | `string` | conditional | Required; choose one. `children` preserves the existing MessageResponse calling pattern |
| `children` | `string` | conditional | Required; choose one. `children` preserves the existing MessageResponse calling pattern |
| `isStreaming` | `boolean` | optional | Enables incomplete Markdown handling; defaults to false |
| `isAnimating` | `boolean` | optional | Compatibility alias; explicit `isStreaming` wins. Does not add word animation |
| `components` | `MarkdownComponents` | optional | Typed overrides for prose, headings, links, lists, tables/cells, and images |
| `referenceConfig` | `{ resolve: (href: string, label: string) => InlineReferenceProps \| undefined; }` | optional |  |
| `codeConfig` | `{ showLineNumbers?: boolean; }` | optional |  |

### referenceConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resolve` | `(href: string, label: string) => InlineReferenceProps` | Yes |  |

### codeConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `showLineNumbers` | `boolean` | No |  |

Custom renderers are trusted application code and own their accessibility and URL handling. Raw HTML is not a supported extension mechanism. Math, diagrams, custom tool cards, and executable previews are outside Phase 1; their fences render as code.

## Design and accessibility rules [#design-and-accessibility-rules]

- **MARKDOWN-01:** Body 13/20; h1/h2 use Heading/15, h3–h6 use Copy/13 Strong. Paragraph gaps 12px; lists 4px between items. No library-default typography.
- **MARKDOWN-02:** Use this renderer for chat, briefing, and human threads. Keep the application's original message text.
- **MARKDOWN-03:** Code is inert. Unsafe navigation schemes and executable HTML are not rendered. External links use native browser navigation; app-specific confirmation is an explicit link override.
- **MARKDOWN-REF-01:** Record references have strong body text and a neutral underline. Preview data belongs to the application.
- **MARKDOWN-TABLE-01:** Subtle tray, compact semantic table, pinned first column, copy/export/expand controls.
- Streaming marks the content busy but does not announce every token. The conversation layer owns meaningful reply announcements.

## Migration notes [#migration-notes]

```tsx
// Existing text and stream state can be reused without converting messages.
<Markdown isAnimating={isLiveAssistant && isLastSegment}>
  {segment.part.text}
</Markdown>
```

`components` remains available. Product-specific question fences, math/Mermaid plugins, link-confirmation providers, and word animations are not silently copied; document those separately before migrating a consumer. See the [AI content integration guide](/docs/guides/ai-content).


---

# Message

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/message
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=543-2

```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="assistant"
  parts={message.parts}
  getPartKey={(part) => part.id}
  renderPart={renderPart}
  actionConfig={{ copy: { text: plainText } }}
/>;
```


## Usage [#usage]

Pass your existing typed parts directly. The renderer receives the original part, including tool IDs, metadata and custom fields.

```tsx
import { Message } from '@commenda/pathfinder/message';
import { Markdown } from '@commenda/pathfinder/markdown';

<Message
  from="assistant"
  parts={message.parts}
  getPartKey={(part, index) => part.id ?? `${message.id}:${index}`}
  renderPart={(part) => {
    switch (part.type) {
      case 'text':
        return <Markdown content={part.text} />;
      case 'request-recap':
        return <ResponseRecap {...part.recap} />;
      default:
        return renderCustomPart(part);
    }
  }}
  actionConfig={{
    copy: { text: plainText },
    feedback: { value: feedback, onChange: saveFeedback },
    retry: { isLatest: isLatestReply, onRetry: regenerate },
  }}
/>;
```

Use a stable tool/part ID where available. An index fallback is safe only for append-only SDK parts; never reorder those parts. Keep Markdown a separate subpath import. Message does not import a parser or require an AI SDK provider.

## User and people threads [#user-and-people-threads]


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="user"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
  authorConfig={{ identity: currentPerson, showName: true }}
/>;
```


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="person"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
  authorConfig={{ identity: currentPerson, showName: true }}
/>;
```


`from` is a presentation choice. A person in a shared thread does not introduce a new AI SDK role. User avatars come from `authorConfig`; set `showName` for shared conversations. People threads show the name automatically. Assistant replies never render the author avatar.

## System events [#system-events]


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="system"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
/>;
```


Keep system events short. They are visual timeline events, not model system instructions.

## Versions [#versions]


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="assistant"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
  branchConfig={{
    index: activeVersion,
    count: versions.length,
    onChange: setActiveVersion,
  }}
/>;
```


The host stores alternatives and swaps the selected message. Keep the active index within `[0, count - 1]`. Controls appear only with at least two alternatives; changing version does not call the model.

## Interleaved activity and content [#interleaved-activity-and-content]


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="assistant"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
  // renderPart maps reasoning, tools, text and recaps in their original order.
/>;
```


Reasoning and tool calls remain ordered parts of their originating reply. Applications map their existing tool state into ToolCall without flattening the transcript.

## Streaming and stopped replies [#streaming-and-stopped-replies]


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="assistant"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
  state={{ status: isStreaming ? 'streaming' : 'stopped' }}
/>;
```


Hide actions while streaming. A stopped reply retains its parts and exposes its configured actions. Put activity components in the original parts array when activity is associated with that turn.

## Partial failure [#partial-failure]


```tsx
import { Message } from '@commenda/pathfinder/message';

<Message
  from="assistant"
  parts={message.parts}
  getPartKey={getPartKey}
  renderPart={renderPart}
  state={{ status: 'error', message: 'Connection lost.' }}
  actionConfig={{ retry: { isLatest: true, onRetry: regenerate } }}
/>;
```


Errors preserve streamed content and hide the regular action toolbar. Retry appears inline only for an eligible latest assistant reply. The host handles retry failures and supplies the next state; Message never starts network requests.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `from` | `"user" \| "assistant" \| "system" \| "person"` | required | Display kind, separate from the app's model role |
| `parts` | `readonly Part[]` | required | Original ordered typed parts |
| `getPartKey` | `((part: Part, index: number) => string)` | required | Stable unique key within the message |
| `renderPart` | `((part: Part, index: number) => ReactNode)` | required | Typed content renderer; preserve unsupported parts intentionally |
| `state` | `MessageState` | optional | Done by default |
| `authorConfig` | `{ identity: PersonIdentity; showName?: boolean; }` | optional | User/person Avatar, no assistant avatar |
| `timestamp` | `{ dateTime: string; label: string; }` | optional | Host-formatted accessible time |
| `attachmentConfig` | `AttachmentGroupProps` | optional | Attachments above the bubble, aligned by author |
| `actionConfig` | `MessageActionConfig` | optional | Copy, controlled feedback, latest-only retry, reply and controlled pin |
| `branchConfig` | `MessageBranchConfig` | optional | Controlled zero-based alternative selection |
| `label` | `string` | optional | Accessible article name and layout extension |
| `className` | `string` | optional | Accessible article name and layout extension |

### state fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"streaming" \| "done" \| "stopped"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"error"` | Yes |  |
| `message` | `string` | Yes |  |

### authorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `identity` | `PersonIdentity` | Yes |  |
| `showName` | `boolean` | No |  |

### authorConfig.identity fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"person"` | Yes |  |
| `userId` | `string` | No |  |
| `name` | `string` | No |  |
| `email` | `string` | No |  |
| `src` | `string` | No |  |

### timestamp fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dateTime` | `string` | Yes |  |
| `label` | `string` | Yes |  |

### attachmentConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `readonly AttachmentItem[]` | Yes |  |
| `align` | `"start" \| "end"` | No |  |
| `maxRows` | `1 \| 2 \| 3` | No |  |
| `getPreview` | `((item: AttachmentItem) => AttachmentProps["previewConfig"])` | No |  |
| `className` | `string` | No |  |
| `label` | `string` | No |  |
| `onPreview` | `((item: AttachmentItem) => void)` | No |  |
| `onRetry` | `((item: AttachmentItem) => void)` | No |  |
| `onRemove` | `((item: AttachmentItem) => void)` | No |  |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `copy` | `{ text: string; }` | No |  |
| `feedback` | `{ value: "good" \| "bad" \| null; onChange: (value: "good" \| "bad" \| null) => void; }` | No |  |
| `retry` | `{ isLatest: boolean; onRetry: () => void; disabled?: boolean; }` | No |  |
| `onReply` | `(() => void)` | No |  |
| `pin` | `{ isPinned: boolean; onChange: (value: boolean) => void; }` | No |  |

### actionConfig.copy fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Yes |  |

### actionConfig.feedback fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `"good" \| "bad" \| null` | Yes |  |
| `onChange` | `(value: "good" \| "bad" \| null) => void` | Yes |  |

### actionConfig.retry fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLatest` | `boolean` | Yes |  |
| `onRetry` | `() => void` | Yes |  |
| `disabled` | `boolean` | No |  |

### actionConfig.pin fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isPinned` | `boolean` | Yes |  |
| `onChange` | `(value: boolean) => void` | Yes |  |

### branchConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `index` | `number` | Yes | Zero-based active alternative; keep the message/part keys stable within each alternative. |
| `count` | `number` | Yes |  |
| `onChange` | `(index: number) => void` | Yes |  |

`actionConfig.copy` accepts `{ text }`. Feedback accepts `{ value: 'good' | 'bad' | null, onChange }`; clicking a chosen thumb clears it. Retry accepts `{ isLatest, onRetry, disabled? }`. People-thread actions use `onReply` and `pin: { isPinned, onChange }`. Callbacks own persistence and error reporting; only copy writes to the clipboard locally.

## Design rules and accessibility [#design-rules-and-accessibility]

- **MESSAGE-01:** User bubble pearl 300, person bubble pearl 200, radius 12, padding 12 vertically/16 horizontally, content at most 520px. Rendered frames use Copy/15, superseding the stale Copy/13 description.
- **MESSAGE-02:** Assistant parts stack 16px apart without an avatar. Generated files, requests and recaps stay in their originating reply.
- **MESSAGE-03:** Actions sit 8px below per the component description. No actions while streaming; branches require alternatives; retry requires latest-reply eligibility. Copy changes to a check for two seconds, selected feedback changes fill rather than weight.
- **MESSAGE-04:** Keep partial output and show the error inline. Do not announce each token or replace the reply with a toast.

Long messages wrap; turn long pasted documents into attachments at the application boundary. Screen readers navigate named articles and labeled action buttons. The Storybook worst-case switch retains Unicode, unbroken text and long author fixtures.


---

# Multi select

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/multi-select
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=865-3077

```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const MultiSelectDefault = () => (
  <MultiSelect
    label="Entity"
    defaultValue={['gb', 'de', 'in', 'sg']}
    options={entityOptions}
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { MultiSelect } from '@commenda/pathfinder/multi-select';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## Empty [#empty]


```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const MultiSelectEmpty = () => (
  <MultiSelect
    label="Entity"
    placeholder="Select entities"
    options={entityOptions}
  />
);
```


## Clearable [#clearable]


```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const MultiSelectClearable = () => (
  <MultiSelect
    label="Entity"
    defaultValue={['gb', 'de']}
    options={entityOptions}
    clearConfig={{}}
  />
);
```


## States [#states]


```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const MultiSelectStates = () => (
  <div style={{ display: 'grid', gap: 24 }}>
    <MultiSelect
      label="Entity"
      placeholder="Select entities"
      options={entityOptions}
    />
    <MultiSelect
      label="Entity"
      placeholder="Select entities"
      options={entityOptions}
      disableConfig={{ isDisabled: true }}
    />
    <MultiSelect
      label="Entity"
      defaultValue={['gb', 'de', 'in', 'sg']}
      options={entityOptions}
      disableConfig={{ isDisabled: true }}
    />
    <MultiSelect
      label="Entity"
      placeholder="Select entities"
      options={entityOptions}
      errorConfig={{ message: 'Choose an entity.', reveal: 'immediate' }}
    />
    <MultiSelect
      label="Entity"
      defaultValue={['gb', 'de', 'in', 'sg']}
      options={entityOptions}
      errorConfig={{ message: 'Choose an entity.', reveal: 'immediate' }}
    />
  </div>
);
```


## Search [#search]


```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const MultiSelectSearch = () => (
  <MultiSelect
    label="Entity"
    defaultValue={['gb', 'de']}
    options={entityOptions}
    searchConfig={{
      mode: 'local',
      enabled: true,
      placeholder: 'Search entities',
    }}
    selectAllConfig={{ label: 'Select all' }}
  />
);
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `options` | `readonly ChoiceOption[]` | conditional | Same option contract as Select |
| `groups` | `readonly ChoiceGroup[]` | conditional | Same option contract as Select |
| `value` | `readonly string[]` | conditional | Controlled callback required; empty array clears |
| `defaultValue` | `readonly string[]` | optional | Controlled callback required; empty array clears |
| `searchConfig` | `{ mode: "local"; enabled?: boolean; placeholder?: string; } \| { mode: "remote"; query: string; onQueryChange: (query: string) => void; resultsQuery: string; isLoading: boolean; error?: string; onRetry?: () => void; placeholder?: string; }` | conditional | Same contract as Select |
| `selectedOptions` | `readonly ChoiceOption[]` | optional | Remote selected metadata independent from current results |
| `paginationConfig` | `ChoicePaginationConfig` | optional | Remote-only pagination |
| `selectionDisplayConfig` | `{ mode: "tags"; } \| { mode: "summary"; format: (count: number) => string; }` | optional | tags; measured +N overflow |
| `selectionLimitConfig` | `{ max: number; message?: string; }` | optional | Blocks additional selection, permits deselection |
| `selectAllConfig` | `{ label?: string; }` | optional | Only listed eligible options; respects limits |
| `clearConfig` | `{ label?: string; }` | optional | Clears unlocked values |
| `renderConfig` | `{ optionContent?: (option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode; selectedContent?: (option: ChoiceOption) => ReactNode; }` | optional | Shared customization, virtualization, creation action |
| `listConfig` | `{ virtualized?: boolean; maxHeight?: number; }` | optional | Shared customization, virtualization, creation action |
| `addItemConfig` | `{ label: string; onAddItem: (query: string) => void; isDisabled?: boolean; }` | optional | Shared customization, virtualization, creation action |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Defines a string value that labels the current element. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `name` | `string` | optional |  |
| `form` | `string` | optional |  |
| `autoComplete` | `string` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |
| `placeholder` | `string` | optional |  |
| `onBlur` | `FocusEventHandler<HTMLButtonElement>` | optional | Called when focus leaves the component. |
| `onFocus` | `FocusEventHandler<HTMLButtonElement>` | optional | Called when focus enters the component. |
| `emptyLabel` | `string` | optional |  |
| `onValueChange` | `((value: readonly string[]) => void)` | conditional |  |

### searchConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"local"` | Yes |  |
| `enabled` | `boolean` | No |  |
| `placeholder` | `string` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"remote"` | Yes |  |
| `query` | `string` | Yes |  |
| `onQueryChange` | `(query: string) => void` | Yes |  |
| `resultsQuery` | `string` | Yes |  |
| `isLoading` | `boolean` | Yes |  |
| `error` | `string` | No |  |
| `onRetry` | `(() => void)` | No |  |
| `placeholder` | `string` | No |  |

### paginationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasMore` | `boolean` | Yes |  |
| `isLoadingMore` | `boolean` | Yes |  |
| `onLoadMore` | `() => void` | Yes |  |
| `error` | `string` | No |  |
| `onRetry` | `(() => void)` | No |  |

### selectionDisplayConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"tags"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"summary"` | Yes |  |
| `format` | `(count: number) => string` | Yes |  |

### selectionLimitConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max` | `number` | Yes |  |
| `message` | `string` | No |  |

### selectAllConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |

### clearConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |

### renderConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionContent` | `((option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode)` | No |  |
| `selectedContent` | `((option: ChoiceOption) => ReactNode)` | No |  |

### listConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `virtualized` | `boolean` | No |  |
| `maxHeight` | `number` | No |  |

### addItemConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `onAddItem` | `(query: string) => void` | Yes |  |
| `isDisabled` | `boolean` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

Shared labels, descriptions, required annotations, errorConfig, disableConfig, IDs, form names, refs, and focus/blur callbacks follow [Input](/docs/components/input). Selection controls do not expose readOnly.

## Local and remote search [#local-and-remote-search]

A ChoiceOption has `value`, `label`, optional `description`, `keywords`, `leadingIcon`, and `disableConfig`. Groups contain stable `id`, `label`, and `options`. Keywords participate only in local filtering. Rich rendering preserves plain-text labels for accessibility and search.

Local config: `{ mode: 'local', enabled?, placeholder? }`. Small local lists use Base UI Select; searchable lists use Base UI Combobox internally. There are exactly two public selection components: Select and MultiSelect.

Remote config: `{ mode: 'remote', query, onQueryChange, resultsQuery, isLoading, error?, onRetry?, placeholder? }`. Query updates immediately; the application owns debouncing, requests, cache, and cancellation. Remote results bypass client filtering and retain server order. While query differs from resultsQuery, stale options are unavailable for selection. Associate resultsQuery with the response that actually produced the options.

Supply selectedOptions for edit-form selections absent from current results. Selection never disappears merely because a page changes. A selected-only cache bridges user selection updates; it is not an unbounded history of every result. Missing metadata renders an explicit unavailable-value label until supplied.

Pagination receives accumulated, deduplicated options. New pages preserve scroll; new queries reset it. The UI gates duplicate load-more requests and provides a keyboard-accessible Load more button. Page errors preserve loaded results and offer retry. Virtualization limits mounted rows; remote pagination limits fetched data. Use both where appropriate.

Locked selected options survive tag removal, clear-all, Backspace, and bulk operations. MultiSelect select-all affects listed enabled options only and cannot imply selecting every record on a server. Bulk selection that would exceed a limit is disabled rather than partially applied.

### Limit [#limit]


```tsx
import { DEFlag, GBFlag, INFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

export const MultiSelectLimit = () => (
  <MultiSelect
    label="Countries"
    selectionLimitConfig={{ max: 2 }}
    selectAllConfig={{}}
    options={[
      {
        leadingIcon: <GBFlag size={16} />,
        value: 'gb',
        label: 'United Kingdom',
      },
      { leadingIcon: <DEFlag size={16} />, value: 'de', label: 'Germany' },
      { leadingIcon: <INFlag size={16} />, value: 'in', label: 'India' },
    ]}
  />
);
```


### Summary [#summary]


```tsx
import { DEFlag, GBFlag } from '@commenda/pathfinder/flags';
import { MultiSelect } from '@commenda/pathfinder/multi-select';

export const MultiSelectSummary = () => (
  <MultiSelect
    label="Entities"
    selectionDisplayConfig={{
      mode: 'summary',
      format: (count) => `${String(count)} entities selected`,
    }}
    defaultValue={['gb', 'de']}
    options={[
      {
        leadingIcon: <GBFlag size={16} />,
        value: 'gb',
        label: 'Meridian UK Ltd',
      },
      {
        leadingIcon: <DEFlag size={16} />,
        value: 'de',
        label: 'Meridian GmbH',
      },
    ]}
  />
);
```


### Remote [#remote]


```tsx
import { useEffect, useState } from 'react';

import {
  type ChoiceOption,
  MultiSelect,
} from '@commenda/pathfinder/multi-select';

export const MultiSelectRemote = () => {
  const [query, setQuery] = useState('');
  const [values, setValues] = useState<readonly string[]>(['saved']);
  const [selected, setSelected] = useState<readonly ChoiceOption[]>([
    { value: 'saved', label: 'Previously saved entity' },
  ]);
  const [response, setResponse] = useState({
    query: '',
    options: [] as ChoiceOption[],
    count: 10,
  });
  const [loading, setLoading] = useState(true);
  const [loadingMore, setLoadingMore] = useState(false);
  useEffect(() => {
    const abort = new AbortController();
    // Demo transport: replace this timer with your query library or fetch using abort.signal.
    // Query updates immediately; the 250ms delay represents request debouncing.
    const timer = setTimeout(() => {
      if (abort.signal.aborted) return;
      const options = Array.from({ length: 30 }, (_, index) => ({
        value: String(index),
        label: `Meridian entity ${String(index + 1)}`,
      })).filter((option) =>
        option.label.toLowerCase().includes(query.toLowerCase())
      );
      setResponse({ query, options, count: 10 });
      setLoading(false);
    }, 250);

    return () => {
      abort.abort();
      clearTimeout(timer);
    };
  }, [query]);
  const listed = response.options.slice(0, response.count);

  return (
    <MultiSelect
      label="Entities"
      value={values}
      onValueChange={(next) => {
        setValues(next);
        const lookup = new Map(
          [...selected, ...listed].map((option) => [option.value, option])
        );
        setSelected(
          next.flatMap((value) => {
            const option = lookup.get(value);

            return option ? [option] : [];
          })
        );
      }}
      selectedOptions={selected}
      options={listed}
      searchConfig={{
        mode: 'remote',
        query,
        onQueryChange: (next) => {
          setQuery(next);
          setLoading(true);
        },
        resultsQuery: response.query,
        isLoading: loading,
      }}
      paginationConfig={{
        hasMore: response.count < response.options.length,
        isLoadingMore: loadingMore,
        onLoadMore: () => {
          setLoadingMore(true);
          setTimeout(() => {
            setResponse((current) =>
              current.query === query
                ? { ...current, count: current.count + 10 }
                : current
            );
            setLoadingMore(false);
          }, 250);
        },
      }}
      clearConfig={{}}
    />
  );
};
```


### Large [#large]


```tsx
import { MultiSelect } from '@commenda/pathfinder/multi-select';

export const MultiSelectLarge = () => (
  <MultiSelect
    label="Entities"
    options={Array.from({ length: 10000 }, (_, index) => ({
      value: String(index),
      label: `Entity ${String(index + 1)}`,
    }))}
    listConfig={{ virtualized: true, maxHeight: 280 }}
  />
);
```


Read [selection and search rules](/docs/components/multi-select#design-rules) for source provenance, API ownership, and constraints.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule            | Figma source | Contract                                                        |
| --------------- | ------------ | --------------------------------------------------------------- |
| MULTISELECT-001 | 865:59967    | Single-line tags with measured +N; removal does not open popup. |
| MULTISELECT-002 | 865:59988    | Keep popup open during selection; preserve option order.        |

Sources: [Search](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=635-13518), [Select](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=179-2), [MultiSelect](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=865-3077). The supplied Select node 182:1182 is its dimensions frame; 180:1177 is the actual component set.

### Field geometry and states [#field-geometry-and-states]

The component sheets are [Select 182:1216](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=182-1216) and [MultiSelect 865:3078](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=865-3078).

- **SELECT-VISUAL-001:** 28px field, 6px radius, 8px inner padding, 4px content gaps, 16px flag and chevron. Clear precedes the chevron (180:593). Empty fields have no leading flag.
- **MULTISELECT-VISUAL-001:** 4px starting inset; selected chips and +N are 20px high with radius 4 and a 0.5px pearl 300 border. Chip icons/removal are 12px; the final chevron is 16px (180:620).
- **SELECTION-STATE-001:** Pearl 400 default border; pearl 500 hover. Open fields retain blue 700 border and a 2px blue 200 ring while focus is in the popup (180:152, 180:766). Invalid uses red 600 at rest and red 700/red 200 when open. Error text is red 900 with a 12px alert icon (180:1031).
- **SELECTION-STATE-002:** Disabled fields use pearl 100 background, pearl 300 border, pearl 600 values and pearl 800 labels. Disabled MultiSelect chips omit removal buttons (180:839).

The Figma 320px MultiSelect frame clips part of the second chip inside a 256px strip. The implementation deliberately truncates the final visible chip's label instead, preserving its removal button and full-label tooltip; a 96px minimum keeps partial chips readable before using +N. Placeholder text uses pearl 800 rather than source pearl 700 to meet text contrast on white. These are documented accessibility adjustments, not new design variants.

The entire field opens the list; removal and clear remain independent buttons. Simple and searchable paths share the same field rendering. Popups follow the embedded Dropdown instances 182:606 and 865:59996 (10px radius, 6px list inset, 2px row gap, 32px minimum rows, 36px flush search row with 12px horizontal inset); option roles remain Select/Combobox semantics. Multi-selection uses Pathfinder Checkbox in read-only presentation mode inside each option; the option owns selection and keyboard focus. Select-all is a functional Checkbox with mixed state. Single selection shows a trailing check. Search, clear and removal icons sit in explicit flex boxes so their centers align with the input and chip rows.

### API ownership [#api-ownership]

Exactly Select and MultiSelect are public. Both support local search, server search, groups, rich option content, pagination, and virtualization. Dropdown remains an action menu. Free-text query entry belongs to Search; typed text never silently becomes a selected option ID.

The application owns query requests, debounce, cancellation, cursors, deduplicated page merging, and cache invalidation. Pathfinder blocks stale-query selection using query/resultsQuery, retains server ranking, and displays initial loading, empty, error, load-more, and retry states. Do not pass yesterday's query as resultsQuery for today's response.

Use a query-keyed data hook or AbortController plus request identity protection. A late response for an earlier query must not overwrite the active query's results. Reset cursors when the query changes. The interactive remote example uses a cancellable simulated transport so it works without an application endpoint; replace it with your authenticated API adapter.

Selected IDs and selectedOptions are separate from fetched pages. selectedOptions resolves labels/icons for saved values missing from the current result set. It does not pin unmatched rows to the results. The component caches only currently selected metadata as a bridge; applications remain responsible for authoritative record updates and deleted-record decisions.

### Large lists and bulk actions [#large-lists-and-bulk-actions]

Enable listConfig.virtualized for large lists. This enables searchable interaction and measured-height rows; keyboard-highlighted options stay mounted. API pagination and virtualization solve different costs and can be combined. Option values must be globally unique and stable across groups and pages.

Select-all means currently listed, filtered, enabled results. Locked values survive all UI removal paths. A bulk selection that exceeds selectionLimitConfig.max is disabled; it never chooses an arbitrary subset. Selecting all matches across an entire backend requires a separate server-side selection model.

Custom renderers supply noninteractive content. Pathfinder owns trigger and option roles, events, refs, selection indicators, and focus. Add-item is a separate explicit action; application creation returns a real record and updates options/value.

### Accessibility and forms [#accessibility-and-forms]

Labels, descriptions, error reveal, and disable reasons follow the shared field contract. Single selection serializes one ID; multiple selection serializes repeated names. Trigger refs and form reset work for both primitive paths. Searchable popups provide an explicitly named query input. Load more and retry are keyboard-accessible buttons outside the option list.

Tag remove buttons are siblings of the trigger, never nested inside it. Long selected labels remain available through tooltips. Search result compositions must handle overlay Escape before field clear/collapse through preventDefault.

Flags, chevrons, and clear/remove icons sit in explicit square flex containers with both axes centered. Do not rely on inline SVG baseline alignment or compensate with pixel offsets. The selected value, tags, and trailing controls share the field’s vertical center. Row Checkbox instances are inert visual indicators; the option owns selection and accessibility semantics.

### Selection guidance [#selection-guidance]

- `DROPDOWN-FUTURE-01` — Figma selection guidance (the historical rule ID is retained): search beyond about eight choices; empty state names the query; footer has one link action outside options. Multiple selection keeps the popup open and preserves row order. Selected rows have checks; highlight remains independent. These selection behaviors belong to Select and MultiSelect, not the action-oriented Dropdown.


---

# OTP

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/otp
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=85-2

```tsx
import { OTP } from '@commenda/pathfinder/otp';

export const OTPDefault = () => (
  <OTP
    label="Verification code"
    description="Enter the 6-digit code from your authenticator app."
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { OTP } from '@commenda/pathfinder/otp';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `value` | `string` | conditional | Keep leading zeros; controlled mode requires `onValueChange` |
| `defaultValue` | `string` | optional | Keep leading zeros; controlled mode requires `onValueChange` |
| `length` | `4 \| 5 \| 6 \| 7 \| 8` | optional | `6` numeric characters |
| `groupConfig` | `{ sizes: readonly number[]; }` | optional | Six digits use `[3, 3]`; other lengths use one group. Sizes must sum to length |
| `onComplete` | `((code: string) => void)` | optional | Fires after an edit completes the code; never on mount or blur |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` | optional | Locks edits, retains form value, announces verification |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Accessible name when the field has no visible label. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `onValueChange` | `((value: string) => void)` | conditional |  |

### groupConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sizes` | `readonly number[]` | Yes |  |

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

Shared `label`, `hideLabel`, `description`, `required`, `errorConfig`, `disableConfig`, and `readOnly` follow [Input](/docs/components/input). The underlying `input-otp` primitive is private.

## Grouping [#grouping]


```tsx
import { OTP } from '@commenda/pathfinder/otp';

export const OTPGrouping = () => (
  <OTP label="Recovery code" length={8} groupConfig={{ sizes: [4, 4] }} />
);
```


## Verification [#verification]

The application starts verification from `onComplete`, owns pending/error state, and clears its previous server error in `onValueChange`. Do not submit a form automatically from both `onComplete` and a separate input handler. Guard against a previous request completing after the user has edited the code; associate the response with the submitted code or request ID.


```tsx
import { useState } from 'react';

import { OTP } from '@commenda/pathfinder/otp';

export const OTPVerification = () => {
  const [code, setCode] = useState('');
  const [error, setError] = useState<string>();
  const [complete, setComplete] = useState(false);

  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <OTP
        label="Verification code"
        value={code}
        onValueChange={(next) => {
          setCode(next);
          setError(undefined);
          setComplete(false);
        }}
        onComplete={(next) => {
          if (next === '012345') setComplete(true);
          else setError('That code is incorrect. Try again.');
        }}
        errorConfig={
          error ? { message: error, reveal: 'immediate' } : undefined
        }
        description="Demo verification: enter 012345. Your application owns the real request."
      />
      {complete && <p role="status">Code accepted.</p>}
    </div>
  );
};
```


## States [#states]


```tsx
import { OTP } from '@commenda/pathfinder/otp';

export const OTPStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <OTP
      label="Verifying"
      defaultValue="012345"
      loadingConfig={{ isLoading: true }}
    />
    <OTP
      label="Unavailable"
      defaultValue="123456"
      disableConfig={{
        isDisabled: true,
        reason: 'Request a new code before continuing.',
      }}
    />
    <OTP
      label="Invalid code"
      defaultValue="123456"
      errorConfig={{
        message: 'That code has expired. Request a new one.',
        reveal: 'immediate',
      }}
    />
  </div>
);
```


Paste fills the code, Backspace edits the previous slot, and leading zeros remain strings. Read [composite field rules](/docs/components/otp#design-rules) for Figma provenance and accessibility rules.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### OTP [#otp]

- **OTP-001:** Default six 36px slots in two groups of three; radius 6, 15px medium digits. Other supported lengths are 4–8.
- **OTP-002:** One accessible native input; numeric string values preserve leading zeros, paste, and one-time-code autocomplete. Slots are presentational.
- **OTP-003:** Completion emits an event. The application verifies the code, handles stale responses, and clears server errors on edit. Figma's auto-submit wording is implemented as `onComplete`, with no implicit form submission.
- **OTP-004:** Loading makes the input read-only and announces verification without dropping its native form value. Disabled fields do not submit.

### Shared rules [#shared-rules]

Labels activate the first input. Descriptions, disabled reasons, and validation messages stay associated with the field. Error icons center on the first 18px text line, including wrapped messages. Controlled values require callbacks; uncontrolled form resets restore defaults. Public props expose application values, never private primitive or calendar objects. Styles ship precompiled for React 18/19 and Next.js consumers.


---

# Output List

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/output-list
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=670-38136

```tsx
import { OutputList } from '@commenda/pathfinder/output-list';

<OutputList
  items={outputs}
  selectedId={activeArtifactId}
  onSelectionChange={setActiveArtifactId}
  onOpen={openArtifact}
  actionConfig={{
    onDownload: downloadArtifact,
    onSaveToDocuments: saveArtifact,
  }}
/>;
```


## Usage [#usage]

```tsx
import { OutputList } from '@commenda/pathfinder/output-list';

<OutputList
  items={outputs}
  selectedId={activeArtifactId}
  onSelectionChange={setActiveArtifactId}
  onOpen={openArtifact}
  actionConfig={{
    onDownload: downloadArtifact,
    onSaveToDocuments: saveArtifact,
  }}
  disclosureConfig={{ open: outputsOpen, onOpenChange: setOutputsOpen }}
/>;
```

Pass stable IDs and newest-first items. Opening, downloading, saving, permissions, and persistence belong to the application. The menu offers download/save only when callbacks are supplied; set an item's `actions.download` or `actions.saveToDocuments` to `false` to omit that action for a particular artifact. Menu actions never activate the row.

## Empty, loading, and collapsed [#empty-loading-and-collapsed]


```tsx
import { OutputList } from '@commenda/pathfinder/output-list';

<OutputList items={[]} onOpen={onOpen} />;
```


```tsx
import { OutputList } from '@commenda/pathfinder/output-list';

<OutputList items={[]} loadingConfig={{ isLoading: true }} onOpen={onOpen} />;
```


```tsx
import { OutputList } from '@commenda/pathfinder/output-list';

<OutputList
  items={items}
  disclosureConfig={{ defaultOpen: false }}
  onOpen={onOpen}
/>;
```


Initial loading shows four skeleton lines. Refreshing a populated list keeps its rows visible. A collapsed section shows the loaded artifact count. Use `disclosureConfig.defaultOpen` for local state, or `open` with `onOpenChange` to persist the preference in your app.

## Responsive output panel [#responsive-output-panel]


```tsx
import { Button } from '@commenda/pathfinder/button';
import { OutputList } from '@commenda/pathfinder/output-list';
import { RunList } from '@commenda/pathfinder/run-list';
import { Sheet } from '@commenda/pathfinder/sheet';

<Sheet
  title="Outputs and runs"
  side="bottom"
  open={open}
  onOpenChange={setOpen}
  trigger={<Button>Show outputs</Button>}
>
  <RunList items={runs} onOpen={openRun} />
  <OutputList items={outputs} onOpen={openArtifact} />
</Sheet>;
```


The example composes Output List and Run List in a 292px column. At viewport widths of 1280px and above it starts visible; from 1024px to 1279px it starts hidden with a header toggle. Below 1024px, the toggle opens a modal bottom Sheet. These layout and preference choices remain in the host, so a compact card is also usable outside chat.

## Complete workflow [#complete-workflow]


```tsx
import { Conversation } from '@commenda/pathfinder/conversation';
import { Message } from '@commenda/pathfinder/message';
import { Composer } from '@commenda/pathfinder/composer';

<Conversation
  messages={messages}
  getMessageKey={(message) => message.id}
  renderMessage={(message) => (
    <Message
      from={message.role}
      parts={message.parts}
      getPartKey={(part) => part.id}
      renderPart={renderPart}
    />
  )}
  footer={<Composer value={draft} onValueChange={setDraft} onSubmit={submit} />}
/>;
```


Choose a suggested prompt, add the simulated ledger attachment, send, answer the entity question, and open the generated workpaper. This example composes Composer, Attachment, Conversation, Message, Reasoning, Tool Call, Question Card, Response Recap, and the output panel. Timers simulate upload and processing; there is no backend, real file upload/download, artifact viewer, or editor. Stop cancels the pending simulated response; a temporarily dismissed question can be reopened.

## Overflow and interaction [#overflow-and-interaction]

Titles and kind labels truncate without moving the icon or menu. The full title remains in the accessible name and native title tooltip. Touch devices keep the menu button visible; hover devices reveal it on hover or keyboard focus. Removing a focused row moves focus to the next available row or section trigger.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly OutputItem[]` | required | Stable IDs, newest-first order |
| `onOpen` | `((id: string) => void)` | required | Open the app's artifact preview |
| `selectedId` | `string \| null` | optional | Controlled active artifact |
| `onSelectionChange` | `((id: string) => void)` | optional | Selection request; does not persist internally |
| `actionConfig` | `{ onDownload?: (id: string) => void; onSaveToDocuments?: (id: string) => void; }` | optional | Callbacks receive the artifact ID |
| `disclosureConfig` | `OutputDisclosureConfig` | optional | Controlled or local disclosure |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` | optional | Initial skeletons / busy state |
| `title` | `string` | optional | Defaults to Outputs |
| `emptyLabel` | `string` | optional | Empty-state explanation |
| `className` | `string` | optional | Host width and placement |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `onDownload` | `((id: string) => void)` | No |  |
| `onSaveToDocuments` | `((id: string) => void)` | No |  |

### disclosureConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | Yes |  |
| `onOpenChange` | `(open: boolean) => void` | Yes |  |

Do not supply: `defaultOpen`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | No |  |
| `onOpenChange` | `((open: boolean) => void)` | No |  |

Do not supply: `open`.

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

`OutputItem` includes `id`, `title`, optional `kindLabel`, `disabled`, and `actions`. `kind` is `document`, `plan`, `workpaper`, `pdf`, `csv`, `file`, or `record`. A file can specify `fileType`; a record requires an `icon` such as its country flag. Other kinds can override their icon too. Prefer user-facing artifact names and localized kind labels.

## Design rules [#design-rules]

- **OUTPUT-01:** Use 32px rows, a 40px header, 12px card radius, 6px body padding, and 2px row gaps. Do not add a shadow or bold the selected title.
- **OUTPUT-02:** Show artifact titles and kinds, never internal tool names. The host supplies newest-first order without date headers.
- **OUTPUT-03:** Keep row opening and menu actions independent. Do not place buttons inside another button. The app owns storage, routing, permissions, and disclosure persistence.
- **OUTPUT-04:** New rows fade in and displaced rows slide for the base duration; keyboard-focused lists and reduced-motion users get immediate updates. Retain stable keys and restore focus after removal.

Metadata uses Soft Pearl 800 for readable contrast at 12px, a deliberate contrast adjustment from Figma's lighter 700. The header disclosure uses the existing Base UI measured-height pattern; only infrequent disclosure changes animate height, while insertion animates opacity and transforms.


---

# Phone input

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/phone-input
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=284-2

```tsx
import { PhoneInput } from '@commenda/pathfinder/phone-input';

export const PhoneInputDefault = () => (
  <PhoneInput
    label="Phone number"
    defaultValue={{ country: 'US', number: '' }}
    placeholder="(201) 555-0123"
    description="Include the area code. We format it when you leave the field."
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { PhoneInput } from '@commenda/pathfinder/phone-input';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

Country artwork loads through an isolated lazy module; other field entry points do not import phone metadata or flags.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `value` | `PhoneValue` | conditional | One is required; the app supplies its initial jurisdiction |
| `defaultValue` | `PhoneValue` | conditional | One is required; the app supplies its initial jurisdiction |
| `onValueChange` | `((value: PhoneValue) => void)` | conditional | Required in controlled mode; receives the editable text |
| `countryConfig` | `{ allowedCountries?: readonly CountryCode[]; }` | optional | All metadata-supported countries unless constrained |
| `onValidationChange` | `((details: PhoneValueDetails) => void)` | optional | Normalized details when validation changes |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Accessible name when the field has no visible label. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |

### value fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `CountryCode` | Yes |  |
| `number` | `string` | Yes |  |

### defaultValue fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `CountryCode` | Yes |  |
| `number` | `string` | Yes |  |

### countryConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `allowedCountries` | `readonly CountryCode[]` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

Shared presentation, native input attributes, and `readOnly` follow [Input](/docs/components/input). Disabled fields do not submit. Read-only values remain copyable and valid values submit. `CountryCode` is a phone metadata type, with no application enum dependency.

## Countries [#countries]


```tsx
import { PhoneInput } from '@commenda/pathfinder/phone-input';

export const PhoneInputCountries = () => (
  <PhoneInput
    label="Contact number"
    defaultValue={{ country: 'GB', number: '' }}
    countryConfig={{ allowedCountries: ['GB', 'DE', 'IN', 'SG', 'US'] }}
    description="The application supplies the allowed countries and initial jurisdiction."
  />
);
```


Search by country name or calling code. Switching country preserves entered text for review. International input updates country only when metadata resolves it unambiguously; a partial shared dial code such as `+1` does not guess US or Canada.

## Validation and submission [#validation-and-submission]


```tsx
import { useState } from 'react';

import {
  PhoneInput,
  type PhoneValueDetails,
} from '@commenda/pathfinder/phone-input';

export const PhoneInputValidation = () => {
  const [details, setDetails] = useState<PhoneValueDetails>({
    isValid: false,
    e164: null,
  });

  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <PhoneInput
        label="Phone number"
        defaultValue={{ country: 'US', number: '' }}
        onValidationChange={setDetails}
      />
      <output style={{ fontSize: 12 }}>
        {details.e164 ?? 'Enter a valid number to see its E.164 value.'}
      </output>
    </div>
  );
};
```


Typing preserves spaces, brackets, dashes, and incomplete text. Valid numbers format nationally on blur. `onValidationChange` supplies E.164 separately; store the draft and canonical value according to application needs. E.164 excludes extensions; if your workflow uses extensions, retain the draft or collect an extension separately. Phone metadata validity is not proof that a number exists or belongs to a person; ownership verification is application-owned.

## States [#states]


```tsx
import { PhoneInput } from '@commenda/pathfinder/phone-input';

export const PhoneInputStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <PhoneInput
      label="Read-only number"
      defaultValue={{ country: 'US', number: '2015550123' }}
      readOnly
    />
    <PhoneInput
      label="Disabled number"
      defaultValue={{ country: 'US', number: '2015550123' }}
      disableConfig={{ isDisabled: true }}
    />
    <PhoneInput
      label="Required number"
      defaultValue={{ country: 'US', number: '' }}
      required
      errorConfig={{
        message: 'Enter a contact phone number.',
        reveal: 'immediate',
      }}
    />
  </div>
);
```


Read [composite field rules](/docs/components/phone-input#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Phones [#phones]

- **PHONE-001:** One 28px border/focus ring, 16px country flag, 13px dial code, 12px chevron, and searchable country selector. Center artwork in flex containers, never through inline SVG baselines.
- **PHONE-002:** Preserve editable text; format valid numbers nationally on blur. Validate with libphonenumber metadata and expose E.164 separately. The app owns verification and storage.
- **PHONE-003:** The application must supply its jurisdiction. Resolve international input only when unambiguous; do not infer a country from shared partial dial codes or browser locale.
- **PHONE-004:** Country switches preserve typed text for review. Allowed-country policy comes from the application, and restricted countries cannot yield a valid canonical form value.

### Shared rules [#shared-rules]

Labels activate the first input. Descriptions, disabled reasons, and validation messages stay associated with the field. Error icons center on the first 18px text line, including wrapped messages. Controlled values require callbacks; uncontrolled form resets restore defaults. Public props expose application values, never private primitive or calendar objects. Styles ship precompiled for React 18/19 and Next.js consumers.


---

# Plan review card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/plan-review-card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=607-4610

```tsx
import { PlanReviewCard } from '@commenda/pathfinder/plan-review-card';

<PlanReviewCard
  key={request.id}
  title="Approve this plan?"
  description="Onboard 5 entities · 6 steps"
  planConfig={{ onOpen: openPlanTab }}
  onSuggestChanges={focusComposer}
  onApprove={approvePlan}
/>;
```


## Usage [#usage]

```tsx
import { PlanReviewCard } from '@commenda/pathfinder/plan-review-card';

<PlanReviewCard
  key={request.id}
  title="Approve this plan?"
  description="Onboard 5 entities · 6 steps"
  planConfig={{ onOpen: openPlanTab }}
  onSuggestChanges={focusComposer}
  onApprove={approvePlan}
/>;
```

## Inline plan review [#inline-plan-review]


```tsx
import { PlanReviewCard } from '@commenda/pathfinder/plan-review-card';

<PlanReviewCard
  placement="inline"
  key={request.id}
  title="Approve this plan?"
  description="Onboard 5 entities · 6 steps"
  planConfig={{ onOpen: openPlanTab }}
  onSuggestChanges={focusComposer}
  onApprove={approvePlan}
/>;
```


## Failure and retry [#failure-and-retry]


```tsx
// Return { status: 'failed', message: 'Please try again.' } from the handler to retain this card.
import { PlanReviewCard } from '@commenda/pathfinder/plan-review-card';

<PlanReviewCard
  key={request.id}
  title="Approve this plan?"
  description="Onboard 5 entities · 6 steps"
  planConfig={{ onOpen: openPlanTab }}
  onSuggestChanges={focusComposer}
  onApprove={approvePlan}
/>;
```


Reset restores the example. Simulate failure retains the card for retry; no backend request is made.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `planConfig` | `{ label?: string; onOpen: () => void; }` | required | Opens the application plan tab; label defaults to Open plan |
| `onApprove` | `RequestHandler` | required | Explicit plan approval; return an attributed plan receipt |
| `onSuggestChanges` | `(() => void)` | required | Opens/focuses the host's change workflow without accepting the plan |
| `approveLabel` | `string` | optional | Defaults to Approve plan |
| `title` | `string` | required |  |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `placement` | `"docked" \| "inline"` | optional |  |
| `state` | `RequestState` | optional |  |
| `onDismiss` | `(() => void)` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |

### planConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |
| `onOpen` | `() => void` | Yes |  |

### state fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"ready" \| "pending" \| "loading"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"resolved"` | Yes |  |
| `recap` | `ResponseRecapProps` | Yes |  |

### Shared request props [#shared-request-props]

| Prop          | Type                   | Behavior                                                                 |
| ------------- | ---------------------- | ------------------------------------------------------------------------ |
| `title`       | `string`               | Required card title.                                                     |
| `description` | `string`               | Optional supporting text.                                                |
| `placement`   | `'docked' \| 'inline'` | Docked by default; parent controls width and placement                   |
| `state`       | `RequestState`         | Ready, loading skeleton, externally pending, or resolved with a recap    |
| `onDismiss`   | `() => void`           | Temporary dismissal via Not now or scoped Escape; not a submitted answer |
| `className`   | `string`               | Layout override                                                          |

`RequestHandler<T>` returns `{ status: 'accepted', recap: ResponseRecapProps }` or `{ status: 'failed', message: string }`, directly or as a Promise. A thrown error shows a retry message and preserves the draft. The host persists accepted responses; the component displays the returned receipt. `state={{ status: 'resolved', recap }}` restores history. Use a stable request ID as the React key, and change the key when the request changes. External pending is a rendering state; authorization and idempotency remain server responsibilities.

**REQUEST-01:** Docked tray uses pearl100, a raised shadow, radius16 and a white radius10 inset with 16px padding. Header40, footer at least44; controls wrap on narrow screens.

**REQUEST-02:** The parent places the request 12px above Composer at the same width. Inline requests are flat and fill their message column. Escape only temporarily dismisses; no global listener is installed.

**REQUEST-03:** Reading content does not animate. Existing Button and Popover motion respects reduced motion. Pending retains the draft and exposes a polite status. Acceptance never precedes the host result.

## Design rules [#design-rules]

- **PLAN-01:** Keep the card compact: title, short scope summary, Open plan, Suggest changes, Approve plan. No Skip and no embedded plan editor.
- **PLAN-02:** Opening the plan or asking for changes does not approve it. Return a `kind: 'plan'` recap with actor and timestamp after explicit server acceptance.

The host owns the plan version. Key each review by request/version ID so an in-flight response cannot approve a newly replaced plan.

## Integration and accessibility [#integration-and-accessibility]

Buttons have explicit names and keyboard focus. No network transport or AI SDK provider is required. Requests, tool execution, permission checks, durable outcomes and composer coordination stay in the application. See [AI content integration](/docs/guides/ai-content) for migration mappings; application migration is outside this build.


---

# Popover

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/popover
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=384-2

```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Input } from '@commenda/pathfinder/input';
import { Popover } from '@commenda/pathfinder/popover';

export const PopoverDefault = () => {
  const [open, setOpen] = useState(false);

  return (
    <Popover
      title="Publish workflow"
      trigger={<Button variant="secondary">Publish workflow</Button>}
      open={open}
      onOpenChange={setOpen}
      footerConfig={{
        primaryAction: {
          label: 'Publish',
          type: 'submit',
          form: 'publish-workflow',
        },
      }}
    >
      <form
        id="publish-workflow"
        onSubmit={(event) => {
          event.preventDefault();
          setOpen(false);
        }}
      >
        <Input label="Version name" defaultValue="Version 2" />
      </form>
    </Popover>
  );
};
```


Import `Popover` and optional `PopoverGroup` from `@commenda/pathfinder/popover`.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `mode` | `"form" \| "preview"` | conditional | form; click versus hover/focus |
| `trigger` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | required | Required; forward native props/ref |
| `title` | `string` | required | Required accessible heading |
| `description` | `ReactNode` | optional | Supporting text and content |
| `children` | `ReactNode` | required | Supporting text and content |
| `positionConfig` | `{ side?: "top" \| "right" \| "bottom" \| "left"; align?: "start" \| "center" \| "end"; }` | optional | bottom / start, collision-aware |
| `open` | `boolean` | conditional | Application can control opening |
| `defaultOpen` | `boolean` | optional | Application can control opening |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Application can control opening |
| `footerConfig` | `OverlayFooterConfig` | optional | Form only |
| `focusConfig` | `OverlayFocusConfig` | optional | Form only |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` | optional | Preview only |
| `className` | `string` | optional | Popup classes |

### positionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | No |  |
| `align` | `"start" \| "end" \| "center"` | No |  |

### footerConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primaryAction` | `OverlayAction` | No |  |
| `secondaryAction` | `OverlayAction` | No |  |
| `leadingContent` | `ReactNode` | No |  |
| `cancelLabel` | `string` | No |  |

### focusConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `initialFocusRef` | `RefObject<HTMLElement \| null>` | No |  |
| `returnFocusRef` | `RefObject<HTMLElement \| null>` | No |  |

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

Forms use Base UI Popover; previews use PreviewCard. Width is 320px, clamped to the viewport; offset is 4px, radius 10px. Use Dialog or Sheet for longer tasks. Form footer actions have the same shape as [Dialog](/docs/components/dialog), including native form submission. Cancel closes; primary actions stay open until the application closes them.

## Preview recipes [#preview-recipes]


```tsx
import { Avatar } from '@commenda/pathfinder/avatar';
import { Badge } from '@commenda/pathfinder/badge';
import { DescriptionList } from '@commenda/pathfinder/description-list';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { Popover, PopoverGroup } from '@commenda/pathfinder/popover';

export const PopoverPreview = () => (
  <PopoverGroup>
    <div className="pf:flex pf:flex-wrap pf:gap-xl">
      <Popover
        mode="preview"
        title="Acme Inc."
        trigger={<a href="#entity-record">Acme Inc.</a>}
      >
        <DescriptionList
          size="compact"
          layout="stacked"
          items={[
            {
              id: 'country',
              label: 'Country',
              value: 'United States',
              leadingIcon: <USFlag size={16} />,
            },
            {
              id: 'status',
              label: 'Status',
              value: <Badge label="Active" tone="success" />,
            },
          ]}
        />
      </Popover>
      <Popover
        mode="preview"
        title="Annual report"
        trigger={<a href="#filing-record">Annual report</a>}
      >
        <DescriptionList
          size="compact"
          layout="stacked"
          items={[
            { id: 'entity', label: 'Entity', value: 'Acme Inc.' },
            { id: 'due', label: 'Due date', value: '1 March 2027' },
          ]}
        />
      </Popover>
      <Popover
        mode="preview"
        title="Certificate of incorporation.pdf"
        trigger={<a href="#file-record">Certificate</a>}
      >
        <p>PDF · 248 KB</p>
        <p>Uploaded 12 October 2026</p>
      </Popover>
      <Popover
        mode="preview"
        title="Avery Morgan"
        trigger={<a href="#person-record">Avery Morgan</a>}
      >
        <Avatar
          identity={{ kind: 'person', name: 'Avery Morgan', userId: 'avery' }}
        />
        <p>avery@example.com</p>
        <a href="mailto:avery@example.com">Email Avery</a>
      </Popover>
    </div>
  </PopoverGroup>
);
```


Entity, record, file, and person previews compose existing components. Keep them read-only. The trigger stays a real link and touch activation follows its destination. General previews allow one destination; the Figma person recipe permits up to two. Preview hover open and close delays are 150ms; keyboard focus also opens the preview without moving focus into it.

## Loading [#loading]


```tsx
import { Popover } from '@commenda/pathfinder/popover';

export const PopoverLoading = () => (
  <Popover
    mode="preview"
    title="Entity preview"
    trigger={<a href="#loading-record">Hover for loading preview</a>}
    loadingConfig={{ isLoading: true }}
  >
    Entity details
  </Popover>
);
```


Applications own fetching, cancellation, errors, and cached data. Skeletons match the content area and announce the loading state.

Dialog and Sheet provide a local scope automatically. Wrap page siblings with `PopoverGroup` to ensure opening one closes another; standalone popovers remain independent. Controlled callers must honor `onOpenChange(false)`. There is no global singleton or required app provider. Read the [overlay rules](/docs/components/popover#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Popover [#popover]

- **POPOVER-001:** Width320, radius10, menu shadow, 0.5px pearl300 edge, offset4, no backdrop. Form header16px start/8px end, top12/bottom4; content16px horizontal, footer12px vertical. Forms contain one or two fields; use larger surfaces for longer tasks.
- **POPOVER-002:** Read-only previews open/close after150ms hover delays and support keyboard focus. Keep trigger destination on touch. No edit controls in hover previews. Person permits two links as an explicit exception to the general one-link recommendation.
- **POPOVER-003:** Coordinate within the nearest local overlay/PopoverGroup. Fetching, caching, loading, permissions and application state remain outside the component.

### Motion and edge cases [#motion-and-edge-cases]

Occasional overlays use motion for spatial consistency. Motion paths and timings follow Kakashi: Dialog fades and moves from 95% scale with a 2% vertical offset in 200ms both ways; Popover fades from 95% scale and an 8px offset toward its trigger in 150ms both ways. Popover direction follows the resolved placement after collision handling. Right Sheet slides in for 500ms and out for 300ms; bottom Sheet slides for 500ms both ways. Sheet panels do not fade during normal motion, and modal backdrops follow the panel duration.

Pathfinder retains its foundation ease-out curve for Dialog/Popover and drawer curve `(0.32,0.72,0,1)` for Sheets. These are deliberate curve choices; this is not a copy of Kakashi’s legacy Radix keyframe implementation. Base UI continues to own presence, focus and dismissal. Transitions use a single `transform` value plus opacity where relevant, so Tailwind v4’s separate scale/translate properties cannot bypass interpolation. Closing or reopening mid-transition reverses from the current rendered position.

Keyboard opening and dismissal remain immediate, including Close and Cancel activation. Reduced motion removes scale and translation: Dialog/Popover keep their fade, while Sheets change position immediately and their modal backdrop can fade. Drag writes only the popup transform, never layout or inherited animation variables. Programmatic openings animate by default; explicit keyboard interactions suppress motion.


---

# Progress

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/progress
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=269-2

```tsx
import { ProgressBar } from '@commenda/pathfinder/progress';
<ProgressBar
  label="Uploading documents"
  value={40}
  helperText="107 of 256 files"
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { ProgressBar } from '@commenda/pathfinder/progress';
<ProgressBar
  label="Uploading documents"
  value={40}
  helperText="107 of 256 files"
/>;
```

## API reference [#api-reference]

| Prop          | Type                           | Default / behavior                      |
| ------------- | ------------------------------ | --------------------------------------- |
| `label`       | `string`                       | Required stable task name               |
| `value`       | `number \| null`               | Required; null is indeterminate         |
| `max`         | `number`                       | 100; invalid maxima normalize to 100    |
| `status`      | `active \| complete \| failed` | active; complete requires numeric value |
| `size (bar)`  | `sm \| md`                     | sm: 4 px; md: 8 px                      |
| `size (ring)` | `16 \| 24 \| 32`               | 16                                      |
| `helperText`  | `string`                       | Bar count or failure explanation        |
| `hideLabel`   | `boolean`                      | false; accessible name stays            |
| `showValue`   | `boolean`                      | true for determinate bars               |
| `valueText`   | `string`                       | Optional human-readable ARIA value      |

Clamp values to 0–max; nonfinite numeric values become 0. Reaching max does not confirm success: explicitly set status="complete". Failure retains its last measured value. The application owns monotonic updates, task identity, retry and cancellation. ProgressRing retains its previous status-icons import path and accepts continuous values. Use a chart or meter for quotas and budgets.

## Examples [#examples]

### Statuses [#statuses]


```tsx
<>
  <ProgressBar
    label="Uploading documents"
    value={40}
    helperText="107 of 256 files"
  />
  <ProgressBar
    label="Uploading documents"
    value={100}
    status="complete"
    helperText="All files uploaded"
  />
  <ProgressBar
    label="Uploading documents"
    value={40}
    status="failed"
    helperText="Connection lost. Try again."
  />
  <ProgressBar
    label="Preparing export"
    value={null}
    helperText="Calculating file count"
  />
</>;
```


### Sizes [#sizes]


```tsx
<>
  <ProgressBar
    label="Uploading documents"
    value={40}
    size="md"
    helperText="107 of 256 files"
  />
  <ProgressBar label="Uploading documents" value={40} />
</>;
```


### Ring [#ring]


```tsx
import { ProgressRing } from '@commenda/pathfinder/progress';
<>
  {([16, 24, 32] as const).map((size) => (
    <ProgressRing
      key={size}
      size={size}
      label="Documents uploaded"
      value={3}
      max={9}
      valueText="3 of 9 documents"
    />
  ))}
  <span>3 of 9 documents</span>
</>;
```


Read the [design guidance](/docs/components/progress#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Progress — 269:2 [#progress--2692]

- **PROGRESS-01:** Long measured tasks such as upload, import, export or sync. Bar for one task; ring for a completion count beside text. Never use progress for budgets, limits or quotas.
- **PROGRESS-02:** Keep the task label stable, and put counts or the current step in helper text. Avoid backwards progress and reaching 100% while still waiting. Success is explicit; numeric max alone does not confirm it.
- **PROGRESS-03:** Failure preserves its last measured value, turns red and explains the problem; the application offers Retry. Offer cancellation for long work and explain what happens to completed work. Use null for unknown length, then switch to measured values when available.
- **PROGRESS-04:** Bar heights 4 by default or 8 for a page's main task. Track pearl 300/full radius; active blue 700, complete green 700, failed red 700. Label/13 Strong, value Label/13 pearl 800, helper Copy/12 pearl 800 or red 800; gaps 8, status icon 16 with gap 6. Value changes ease out over 300 ms. Indeterminate segment is 30% and loops linearly over 1.2 seconds. Reduced motion removes spatial loops. Ring sizes 16/24/32 retain the source geometry and accept continuous counts.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

- **Progress:** compose the existing 16px ProgressRing for the Figma ring pattern. `TableCell` also offers a linear progress renderer; these are named alternatives, not interchangeable artwork.


---

# Question card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/question-card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=607-4462

```tsx
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  key={request.id}
  title="Which entity should I set up first?"
  options={entities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Usage [#usage]

```tsx
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  key={request.id}
  title="Which entity should I set up first?"
  options={entities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```

## Multiple answers [#multiple-answers]


```tsx
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  mode="multiple"
  key={request.id}
  title="Which entity should I set up first?"
  options={entities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## More options and search [#more-options-and-search]


```tsx
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  key={request.id}
  title="Which entity should I set up first?"
  options={allEntities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Inline placement [#inline-placement]


```tsx
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  placement="inline"
  key={request.id}
  title="Which entity should I set up first?"
  options={entities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Failed submission and retry [#failed-submission-and-retry]


```tsx
// Return { status: 'failed', message: 'Please try again.' } from the handler to retain this card.
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  key={request.id}
  title="Which entity should I set up first?"
  options={entities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


## Loading [#loading]


```tsx
import { QuestionCard } from '@commenda/pathfinder/question-card';

<QuestionCard
  state={{ status: 'loading' }}
  key={request.id}
  title="Which entity should I set up first?"
  options={entities.map((entity) => ({ id: entity.id, label: entity.name }))}
  writeInConfig={{}}
  onSubmit={async (answer) => {
    const receipt = await saveAnswer(request.id, answer);
    return receipt.ok
      ? { status: 'accepted', recap: receipt.recap }
      : { status: 'failed', message: receipt.message };
  }}
  onDismiss={() => temporarilyHide(request.id)}
/>;
```


Reset restores the example. Simulate failure retains the card for retry; no backend request is made.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `options` | `readonly QuestionOption[]` | required | Stable unique `id`, `label`, optional `description`, decorative `icon`, `disabled` |
| `mode` | `"single" \| "multiple"` | optional | Single by default; activating a single option submits immediately |
| `defaultAnswer` | `QuestionAnswer` | optional | Initial draft; use a new React key for a new request |
| `onAnswerChange` | `((answer: QuestionAnswer) => void)` | optional | Observe draft changes for host persistence |
| `onSubmit` | `RequestHandler<QuestionAnswer>` | required | Accept or reject explicitly; do not clear the draft before acceptance |
| `onSkip` | `RequestHandler` | optional | Optional explicit skip, distinct from temporary dismissal |
| `writeInConfig` | `{ placeholder?: string; label?: string; maxLength?: number; }` | optional | Enables a written answer; single choice clears it when selecting an option |
| `paginationConfig` | `{ index: number; count: number; onChange: (index: number) => void; }` | optional | Zero-based host-owned question navigation; pending disables navigation |
| `title` | `string` | required |  |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `placement` | `"docked" \| "inline"` | optional |  |
| `state` | `RequestState` | optional |  |
| `onDismiss` | `(() => void)` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |

### defaultAnswer fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionIds` | `readonly string[]` | Yes |  |
| `text` | `string` | Yes |  |

### writeInConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | No |  |
| `label` | `string` | No |  |
| `maxLength` | `number` | No |  |

### paginationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `index` | `number` | Yes |  |
| `count` | `number` | Yes |  |
| `onChange` | `(index: number) => void` | Yes |  |

### state fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"ready" \| "pending" \| "loading"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"resolved"` | Yes |  |
| `recap` | `ResponseRecapProps` | Yes |  |

### Shared request props [#shared-request-props]

| Prop          | Type                   | Behavior                                                                 |
| ------------- | ---------------------- | ------------------------------------------------------------------------ |
| `title`       | `string`               | Required card title.                                                     |
| `description` | `string`               | Optional supporting text.                                                |
| `placement`   | `'docked' \| 'inline'` | Docked by default; parent controls width and placement                   |
| `state`       | `RequestState`         | Ready, loading skeleton, externally pending, or resolved with a recap    |
| `onDismiss`   | `() => void`           | Temporary dismissal via Not now or scoped Escape; not a submitted answer |
| `className`   | `string`               | Layout override                                                          |

`RequestHandler<T>` returns `{ status: 'accepted', recap: ResponseRecapProps }` or `{ status: 'failed', message: string }`, directly or as a Promise. A thrown error shows a retry message and preserves the draft. The host persists accepted responses; the component displays the returned receipt. `state={{ status: 'resolved', recap }}` restores history. Use a stable request ID as the React key, and change the key when the request changes. External pending is a rendering state; authorization and idempotency remain server responsibilities.

**REQUEST-01:** Docked tray uses pearl100, a raised shadow, radius16 and a white radius10 inset with 16px padding. Header40, footer at least44; controls wrap on narrow screens.

**REQUEST-02:** The parent places the request 12px above Composer at the same width. Inline requests are flat and fill their message column. Escape only temporarily dismisses; no global listener is installed.

**REQUEST-03:** Reading content does not animate. Existing Button and Popover motion respects reduced motion. Pending retains the draft and exposes a polite status. Acceptance never precedes the host result.

## Design rules [#design-rules]

- **QUESTION-01:** Single pointer/Space/Enter or number activation submits; arrow keys only move selection. Multiple choices and written answers require Continue (Enter also submits written text outside IME composition).
- **QUESTION-02:** Up to four options remain inline. Five or more show the first three and More options; eight or more enable search. Selected overflow labels remain visible outside the popup. Only the selected number lead turns blue.
- **QUESTION-03:** Number shortcuts operate only inside this card, never inside text fields or the overflow dialog. They cannot approve an action. Escape dismisses the popup first, then the request on a subsequent Escape.
- **QUESTION-04:** Failures retain the answer, pending blocks duplicate submission, and acceptance renders the supplied ResponseRecap.

Use unique IDs rather than labels as values. Keep the option set stable for a request. RadioGroup primitives provide single-choice arrow navigation; Checkbox provides multiple-choice semantics. The overflow uses a Popover instead of an action-only Dropdown so choices retain radio/checkbox semantics.

## Integration and accessibility [#integration-and-accessibility]

Buttons have explicit names and keyboard focus. No network transport or AI SDK provider is required. Requests, tool execution, permission checks, durable outcomes and composer coordination stay in the application. See [AI content integration](/docs/guides/ai-content) for migration mappings; application migration is outside this build.


---

# Radio group

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/radio-group
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-3

```tsx
import { RadioGroup } from '@commenda/pathfinder/radio-group';

<RadioGroup
  label="Filing frequency"
  name="frequency"
  value={frequency}
  onValueChange={setFrequency}
  options={[
    { value: 'annual', label: 'Annual' },
    { value: 'quarterly', label: 'Quarterly' },
    { value: 'monthly', label: 'Monthly' },
  ]}
/>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once at the app root. The stylesheet is precompiled with Tailwind v4; your application does not need Tailwind or source scanning. Event handlers belong in a client component in Next.js App Router.

## Usage [#usage]

```tsx
import { RadioGroup } from '@commenda/pathfinder/radio-group';

<RadioGroup
  label="Filing frequency"
  name="frequency"
  value={frequency}
  onValueChange={setFrequency}
  options={[
    { value: 'annual', label: 'Annual' },
    { value: 'quarterly', label: 'Quarterly' },
    { value: 'monthly', label: 'Monthly' },
  ]}
/>;
```

| Prop                   | Type                         | Default / behavior                                               |
| ---------------------- | ---------------------------- | ---------------------------------------------------------------- |
| `label`                | `string`                     | Required group name, visible by default                          |
| `hideLabel`            | `boolean`                    | `false`; hides only the visible group heading                    |
| `description`          | `string`                     | Optional group guidance                                          |
| `options`              | `readonly RadioOption[]`     | Required; stable, unique string values                           |
| `value`                | `string \| null`             | Controlled selected value; `null` means intentionally unanswered |
| `defaultValue`         | `string`                     | Uncontrolled initial selection; omitted means unanswered         |
| `onValueChange`        | `(value: string) => void`    | Required with controlled `value`, optional when uncontrolled     |
| `variant`              | `'default' \| 'card'`        | `'default'`                                                      |
| `orientation`          | `'vertical' \| 'horizontal'` | `'vertical'`; horizontal layout wraps and cards share row height |
| `disabled`             | `boolean`                    | Disables interaction for the control or group.                   |
| `readOnly`             | `boolean`                    | Keeps the current value visible while preventing changes.        |
| `required`             | `boolean`                    | Requires a value for native form validation.                     |
| `name`                 | `string`                     | Name used when the control submits its value with a form.        |
| `form`                 | `string`                     | ID of the form associated with the control.                      |
| `inputRef`             | `Ref<HTMLInputElement>`      | Access to the underlying form input.                             |
| `className`            | `string`                     | Additional class names for the outer layout.                     |
| `ref`                  | `Ref<HTMLDivElement>`        | Access to the interactive root element.                          |
| Native events and ARIA | Base UI group props          | Typed passthrough                                                |

`RadioOption`:

| Property         | Type                | Purpose                                                            |
| ---------------- | ------------------- | ------------------------------------------------------------------ |
| `value`          | `string`            | Required stable, unique identity and submitted value               |
| `label`          | `string`            | Required option name                                               |
| `description`    | `string`            | Supporting explanation                                             |
| `details`        | `readonly string[]` | Additional card bullets                                            |
| `disabled`       | `boolean`           | Unavailable option; keyboard navigation skips it                   |
| `disabledReason` | `string`            | Visible and associated while the option or whole group is disabled |

Use two to five visible options. Prefer a sensible default, but permit an empty group when explicitly choosing is necessary. Do not auto-select the first item or silently replace a removed controlled value. The owner reconciles changing options. Labels select their option; arrow keys move selection, and only one value submits. For longer lists use Select. Never use one radio for a boolean setting.

Radio cards use `variant="card"`; they are the same radio group, not an unrelated clickable card API. Figma calls its collection “Radio card” but includes checkbox cards; those belong to Checkbox to preserve multiple-selection semantics. Cards have 16px padding, 12px control/text gap, 8px radius and 13px medium labels. Their width adapts from the 320px Figma specimen.

## Examples [#examples]

### Descriptions [#descriptions]


```tsx
<RadioGroup
  label="Filing frequency"
  defaultValue="annual"
  options={[
    { value: 'annual', label: 'Annual', description: 'One return per year.' },
    {
      value: 'quarterly',
      label: 'Quarterly',
      description: 'Four returns per year.',
    },
  ]}
/>;
```


### Radio cards [#radio-cards]


```tsx
<RadioGroup
  label="Filing frequency"
  variant="card"
  orientation="horizontal"
  defaultValue="annual"
  options={[
    {
      value: 'annual',
      label: 'Annual',
      description: 'One return at the end of the fiscal year.',
      details: ['Due 15 April'],
    },
    {
      value: 'quarterly',
      label: 'Quarterly',
      description: 'One return every three months.',
    },
    {
      value: 'monthly',
      label: 'Monthly',
      description: 'One return every month.',
    },
  ]}
/>;
```


### Disabled group [#disabled-group]


```tsx
<RadioGroup
  label="Filing frequency"
  defaultValue="annual"
  disabled
  options={[
    { value: 'annual', label: 'Annual' },
    { value: 'quarterly', label: 'Quarterly' },
    {
      value: 'monthly',
      label: 'Monthly',
      disabledReason: 'Unavailable on the current plan',
    },
  ]}
/>;
```


Read the [Figma choice-control rules](/docs/components/radio-group#design-rules) for design guidance, source discrepancies and accessibility requirements.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Radio and cards [#radio-and-cards]

Source: [199:3](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-3), radio variants 200:46, card variants 201:413, guidance 205:320.

- **RADIO-01** — One choice from two to five visible options. Use Select for longer lists or limited space. A lone boolean option uses Checkbox/Switch. Arrow keys move selection and skip disabled items; Tab enters/leaves the group.
- **RADIO-02** — Prefer a sensible default. Leave the group unanswered only when deliberate choice is required. Never silently choose the first value or replace a removed controlled value. The application reconciles dynamic options.
- **RADIO-03** — Order options by frequency, size or time rather than alphabetically by default. Circle 16px, selected white dot 6px; colors and focus match Checkbox. Group row gap 8px.
- **CARD-01** — Use a card when each option needs title and description. Keep cards in one row equal-height. The “Radio card” Figma collection contains both radio and checkbox controls; Pathfinder exposes `RadioGroup variant="card"` for one choice and `Checkbox variant="card"` for independent choices.
- **CARD-02** — Card padding 16px, control/text gap 12px, radius 8px. Title Label/13 Strong; description Copy/12 with 4px gap. Detail bullets have 2px gap and 4px top padding. Surface remains white when selected; border becomes blue-700. Focus surrounds the whole card. Disabled surface/border/text use soft-pearl-100/300/600. The 320px specimen width adapts to the container.

### Implementation decisions and source differences [#implementation-decisions-and-source-differences]

The complete prop tables are on [Checkbox](/docs/components/checkbox), [RadioGroup](/docs/components/radio-group) and [Switch](/docs/components/switch). Source rule IDs are also kept in the component implementation comments and exported through `llms.txt`, `llms-full.txt` and the Markdown routes.

- **CHOICE-01** — The sheets describe 8px list gaps but some documentation frames place rows 32px apart. Use the documented 8px component-list gap; documentation specimen whitespace is not a new size token.

- **CHOICE-02** — Built-in text is plain, wrapping content. Do not place links, buttons or nested interactive controls inside labels or cards. Disabled reasons are visible descriptions, not tooltip-only explanations on controls removed from keyboard navigation.

- **CHOICE-03** — Visual control size is not the hit target. Coarse-pointer rows provide at least 44px height, while preserving 16px marks and the 36×20px switch track. Cards already exceed this height.

- **CHOICE-04** — Hover/focus are real browser states, not public cosmetic props. Retain native `name`, `value`, `form`, `required`, `readOnly`, disabled semantics and input refs. `hideLabel` preserves the required accessible label.

- **CHOICE-05** — Use Pathfinder's existing Check/Minus optical artwork at 12px. Boxes, circles, tracks and thumbs are interactive primitive geometry, styled with the Figma tokens; they are not flattened screenshots. This keeps focus, RTL and switch movement functional.


---

# Reasoning

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/reasoning
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=601-225

```tsx
import { Reasoning } from '@commenda/pathfinder/reasoning';
import { Markdown } from '@commenda/pathfinder/markdown';

<Reasoning isStreaming={isReasoningStreaming} duration={elapsedSeconds}>
  <Markdown content={summary} isStreaming={isReasoningStreaming} />
</Reasoning>;
```


## Usage [#usage]

```tsx
import { Reasoning } from '@commenda/pathfinder/reasoning';
import { Markdown } from '@commenda/pathfinder/markdown';

<Reasoning isStreaming={isReasoningStreaming} duration={elapsedSeconds}>
  <Markdown content={summary} isStreaming={isReasoningStreaming} />
</Reasoning>;
```

## Live activity [#live-activity]


```tsx
import { Reasoning } from '@commenda/pathfinder/reasoning';
import { Markdown } from '@commenda/pathfinder/markdown';

<Reasoning isStreaming={isReasoningStreaming} duration={elapsedSeconds}>
  <Markdown content={summary} isStreaming={isReasoningStreaming} />
</Reasoning>;
```


Use Start/Finish activity to exercise streaming updates. New run resets disclosure intent.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `children` | `ReactNode` | required | Required app-provided summary; compose Markdown explicitly |
| `isStreaming` | `boolean` | optional | Whether this reasoning part is live, not whether the whole answer is live |
| `duration` | `number` | optional | Supplied elapsed seconds; invalid values use “Thought process” |
| `label` | `string` | optional | Override the trigger for localization |
| `disclosureConfig` | `ActivityDisclosureConfig` | optional | Manual intent overrides automation; controlled open is entirely host-owned |
| `className` | `string` | optional | Layout override |

### disclosureConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | No |  |
| `defaultOpen` | `boolean` | No |  |
| `onOpenChange` | `((open: boolean) => void)` | No |  |

## Design rules [#design-rules]

- **REASONING-01:** Only render summaries supplied by the application. Never invent or reconstruct private model reasoning.
- **REASONING-02:** Live content opens automatically. Stop isStreaming when the next message part arrives; collapse after 1s. A user toggle, explicit defaultOpen, or controlled open wins over automation. History starts closed. Use a new React key for a new run.
- **REASONING-03:** Copy13 pearl800, a pearl300 hairline rail, 12px header gap and 12px inset. Compose Pathfinder Markdown when needed; plain text stays lightweight.

`disclosureConfig.onOpenChange` reports user toggle requests. A controlled `open` value delegates timing and persistence to the host. Automatic collapse also preserves a panel containing keyboard focus.

## Accessibility and integration [#accessibility-and-integration]

Disclosure buttons support Enter and Space, preserve focus, and expose `aria-expanded`. Payload copy buttons are outside the disclosure trigger. Pointer disclosure uses the existing 200ms height transition; keyboard and reduced-motion interaction are immediate. Long text wraps while code scrolls inside its own region. Use one meaningful ThinkingIndicator status per active response rather than announcing every streamed token or tool payload.

The application owns requests, cancellation, approval, retries, durations, and history persistence. No AI SDK provider is required. See [AI content integration](/docs/guides/ai-content) for migration mappings; consumer migration is outside this phase.


---

# Response recap

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/response-recap
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=607-31552

```tsx
import { ResponseRecap } from '@commenda/pathfinder/response-recap';

<ResponseRecap
  kind="approval"
  items={[{ id: 'approval', question: 'Send documents?', answer: 'Approved' }]}
  attribution={{
    name: 'Alex Morgan',
    dateTime: '2026-10-13T10:30:00Z',
    label: '13 Oct 2026, 10:30 UTC',
  }}
/>;
```


## Usage [#usage]

```tsx
import { ResponseRecap } from '@commenda/pathfinder/response-recap';

<ResponseRecap
  kind="approval"
  items={[{ id: 'approval', question: 'Send documents?', answer: 'Approved' }]}
  attribution={{
    name: 'Alex Morgan',
    dateTime: '2026-10-13T10:30:00Z',
    label: '13 Oct 2026, 10:30 UTC',
  }}
/>;
```

Long answers and Unicode text wrap within the available width.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly ResponseRecapItem[]` | required | Stable IDs and plain text; each pair renders as `dt`/`dd` |
| `kind` | `"questions" \| "upload" \| "approval" \| "plan"` | conditional | Defaults to questions |
| `attribution` | `{ name: string; dateTime: string; label: string; }` | conditional | Required by TypeScript for approval and plan; ISO dateTime plus localized display label |
| `className` | `string` | optional | Layout override |

### attribution fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes |  |
| `dateTime` | `string` | Yes |  |
| `label` | `string` | Yes |  |

## Design rules [#design-rules]

- **RECAP-01:** Flat white card, hairline border, radius16, padding16. Questions use Label12 pearl800; answers use Copy13 with 4px separation and 12px between groups.
- **RECAP-02:** Render only accepted responses. Approval/plan recaps require actor and timestamp. Persist the receipt in its originating message so it survives reload and appears in history.

The recap is informational, not editable. Use the original question for corrections or a new request. Long text wraps; no Markdown parser or AI provider is imported.

## Integration and accessibility [#integration-and-accessibility]

Buttons have explicit names and keyboard focus. No network transport or AI SDK provider is required. Requests, tool execution, permission checks, durable outcomes and composer coordination stay in the application. See [AI content integration](/docs/guides/ai-content) for migration mappings; application migration is outside this build.


---

# Run List

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/run-list
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=670-38136

```tsx
import { RunList } from '@commenda/pathfinder/run-list';

<RunList
  items={runs}
  selectedId={activeRunId}
  onOpen={openRun}
  onMarkRead={markRead}
  actionConfig={{
    onRunNow: runNow,
    onMarkAllRead: markAllRead,
    onSettings: openSettings,
  }}
  paginationConfig={{ hasMore, isLoading, onLoadMore: loadOlder }}
/>;
```


## Usage [#usage]

```tsx
import { RunList } from '@commenda/pathfinder/run-list';

<RunList
  items={runs}
  selectedId={activeRunId}
  onOpen={openConversation}
  onMarkRead={markRunRead}
  nextRun={{ label: 'Tomorrow at 9:00 AM', dateTime: '2026-10-14T09:00:00Z' }}
  actionConfig={{
    onRunNow: runNow,
    onMarkAllRead: markAllRead,
    onSettings: openSettings,
  }}
  paginationConfig={{ hasMore, isLoading, onLoadMore: loadOlder, error }}
/>;
```

The host provides newest-first runs and a localized timestamp label plus a machine-readable `dateTime`. Opening a row calls `onOpen` and requests `onMarkRead` only if it was unread. Update the controlled data after your app accepts that operation. Fetching, scheduling, routing, and unread persistence stay outside the component.

## Status and unread indicators [#status-and-unread-indicators]

Each row has a stable 16px leading slot. Awaiting input is amber, failures red, running uses a blue arc, and an unread completed run has a blue dot. Canceled and skipped runs remain neutral even when unread; their trailing label explains the outcome. Queued and read completed runs use a neutral ring. Status is included in the button's accessible name, so it is not communicated by color alone.

The header menu exposes only supplied actions: Run now, Mark all as read, and Agent settings. Its button is separate from the disclosure trigger. Output counts hide at zero and use compact formatting for large values. Unread counts describe the loaded items, not an assumed server total.

## Empty, loading, and collapsed [#empty-loading-and-collapsed]


```tsx
import { RunList } from '@commenda/pathfinder/run-list';

<RunList items={[]} onOpen={onOpen} />;
```


```tsx
import { RunList } from '@commenda/pathfinder/run-list';

<RunList items={[]} loadingConfig={{ isLoading: true }} onOpen={onOpen} />;
```


```tsx
import { RunList } from '@commenda/pathfinder/run-list';

<RunList
  items={items}
  disclosureConfig={{ defaultOpen: false }}
  onOpen={onOpen}
/>;
```


A collapsed section shows the loaded unread count. Initial loading uses skeleton rows; refreshing retains the existing history. Supply `nextRun` only when there is a schedule. Pagination preserves existing items, disables repeated requests while loading, and displays `error` next to the retry control.

## Responsive behavior [#responsive-behavior]

Long dates, large counts, empty lists, row removal, and new-run insertion use the same controls as Output List. A mobile menu stays available without hover. The host should guard overlapping requests and retain IDs across page loads.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly RunItem[]` | required | Newest-first run history |
| `onOpen` | `((id: string) => void)` | required | Navigate to the run conversation |
| `onMarkRead` | `((id: string) => void)` | optional | Request unread persistence |
| `selectedId` | `string \| null` | optional | Controlled active run |
| `onSelectionChange` | `((id: string) => void)` | optional | Notify selection intent |
| `nextRun` | `{ label: string; dateTime?: string; }` | optional | Optional scheduled run |
| `actionConfig` | `{ onRunNow?: () => void; onMarkAllRead?: () => void; onSettings?: () => void; }` | optional | Optional header actions |
| `paginationConfig` | `{ hasMore: boolean; isLoading: boolean; onLoadMore: () => void; error?: string; }` | optional | Older history and errors |
| `disclosureConfig` | `OutputDisclosureConfig` | optional | App-persisted or local disclosure |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` | optional | Initial skeletons / busy state |
| `title` | `string` | optional | Copy and host placement |
| `emptyLabel` | `string` | optional | Copy and host placement |
| `className` | `string` | optional | Copy and host placement |

### nextRun fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `dateTime` | `string` | No |  |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `onRunNow` | `(() => void)` | No |  |
| `onMarkAllRead` | `(() => void)` | No |  |
| `onSettings` | `(() => void)` | No |  |

### paginationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasMore` | `boolean` | Yes |  |
| `isLoading` | `boolean` | Yes |  |
| `onLoadMore` | `() => void` | Yes |  |
| `error` | `string` | No |  |

### disclosureConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | Yes |  |
| `onOpenChange` | `(open: boolean) => void` | Yes |  |

Do not supply: `defaultOpen`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | No |  |
| `onOpenChange` | `((open: boolean) => void)` | No |  |

Do not supply: `open`.

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

A `RunItem` has `id`, `timestamp: { dateTime, label }`, `status`, optional `outputCount`, `unread`, and `disabled`. Status accepts `queued`, `running`, `awaiting`, `completed`, `failed`, `canceled`, or `skipped`. Disabled rows cannot open. Pagination is explicit; this small rail does not virtualize an unbounded run history.

## Design rules and compatibility [#design-rules-and-compatibility]

- **RUN-01:** Match Output List's compact card and 32px row geometry. The status indicator leads; the date is the primary label.
- **RUN-02:** Canceled and skipped runs are neutral, never failures. Awaiting, failed, and running take precedence over unread; reduced motion stops the running animation.
- **RUN-03:** Opening an unread run requests marking it read. Keep all mutations and routing in host callbacks; selected and unread state remain controlled.
- **RUN-04:** Keep header actions independent from disclosure, retain existing rows during pagination, and preserve keyboard focus during removal.

The existing enterprise `AgentRunsRail` can map its IDs, formatted timestamps, selected conversation, paging, and mutation callbacks into this API. Its current canceled-as-failed mapping must change intentionally to the neutral Figma behavior. No consumer migration is included here. Compose [Output List](/docs/components/output-list) beside it for the responsive panel and complete simulated workflow.


---

# Search

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/search
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=635-13518

```tsx
import { Search } from '@commenda/pathfinder/search';

export const SearchDefault = () => (
  <Search label="Search filings" hideLabel placeholder="Search filings" />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { Search } from '@commenda/pathfinder/search';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `variant` | `"fixed" \| "expandable" \| "global"` | optional | fixed; heights 28/28/40px |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` | optional | Spinner replaces search icon |
| `shortcutConfig` | `{ key: string; label: string; scopeId: string; }` | optional | Opt-in scoped shortcut; ignores typing targets |
| `onSearch` | `((query: string) => void)` | optional | Enter submission; ignored during IME composition |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Accessible name when the field has no visible label. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `value` | `string` | conditional |  |
| `onValueChange` | `((value: string) => void)` | conditional |  |
| `defaultValue` | `string` | optional |  |

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

### shortcutConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `scopeId` | `string` | Yes |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

Supports Input’s shared field presentation and native search-input attributes. Use hideLabel where the surrounding toolbar supplies visual context; an accessible label is still required.

## Keyboard and request behavior [#keyboard-and-request-behavior]

Application code handles debounce and requests; onValueChange is immediate. onSearch is Enter submission, not each keystroke. Escape clears the query, then blurs a fixed/global input or collapses expandable search and restores trigger focus. The clear button clears and folds expandable search. Loading is application-owned.

A result overlay handles Escape first through onKeyDown and preventDefault; the field then retains its query. Search result navigation is a documented composition, separate from selecting a saved value. Do not implement a second global shortcut listener on every instance: shortcutConfig binds only to the specified scope element and ignores editing targets.

### Variants [#variants]


```tsx
import { Search } from '@commenda/pathfinder/search';

export const SearchVariants = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <Search label="Fixed search" hideLabel placeholder="Search filings" />
    <Search
      label="Expandable search"
      hideLabel
      variant="expandable"
      placeholder="Search filings"
    />
    <Search
      label="Global search"
      hideLabel
      variant="global"
      placeholder="Search documents across all entities"
    />
  </div>
);
```


### States [#states]


```tsx
import { Search } from '@commenda/pathfinder/search';

export const SearchStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <Search
      label="Loading search"
      hideLabel
      defaultValue="Delaware"
      loadingConfig={{ isLoading: true }}
    />
    <Search
      label="Disabled search"
      hideLabel
      disableConfig={{
        isDisabled: true,
        reason: 'Search is unavailable while importing.',
      }}
    />
  </div>
);
```


### Results [#results]


```tsx
import { useState } from 'react';

import { Search } from '@commenda/pathfinder/search';

export const SearchResults = () => {
  const [query, setQuery] = useState('');
  const [open, setOpen] = useState(false);

  return (
    <div>
      <Search
        label="Search documents"
        hideLabel
        value={query}
        onValueChange={(next) => {
          setQuery(next);
          setOpen(true);
        }}
        onKeyDown={(event) => {
          if (event.key === 'Escape' && open) {
            event.preventDefault();
            setOpen(false);
          }
        }}
      />
      {open && query && (
        <nav aria-label="Search results">
          <ul>
            <li>
              <a href="#certificate">Certificate of incorporation</a>
            </li>
            <li>
              <a href="#report">Annual report</a>
            </li>
          </ul>
        </nav>
      )}
    </div>
  );
};
```


Read [selection and search rules](/docs/components/search#design-rules) for source provenance, API ownership, and constraints.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule       | Figma source         | Contract                                                                            |
| ---------- | -------------------- | ----------------------------------------------------------------------------------- |
| SEARCH-001 | 636:31822            | Fixed/expandable 28px; expandable opens to 220px; global 40px/max720.               |
| SEARCH-002 | 637:32230, 637:32236 | Expandable in table toolbar; result counts belong in table range text.              |
| SEARCH-003 | 637:32193, 637:1779  | Escape closes results, clears, then blurs/collapses. Clear folds expandable search. |

Sources: [Search](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=635-13518), [Select](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=179-2), [MultiSelect](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=865-3077). The supplied Select node 182:1182 is its dimensions frame; 180:1177 is the actual component set.

### Accessibility and forms [#accessibility-and-forms]

Labels, descriptions, error reveal, and disable reasons follow the shared field contract. Single selection serializes one ID; multiple selection serializes repeated names. Trigger refs and form reset work for both primitive paths. Searchable popups provide an explicitly named query input. Load more and retry are keyboard-accessible buttons outside the option list.

Tag remove buttons are siblings of the trigger, never nested inside it. Long selected labels remain available through tooltips. Search result compositions must handle overlay Escape before field clear/collapse through preventDefault.

Flags, chevrons, and clear/remove icons sit in explicit square flex containers with both axes centered. Do not rely on inline SVG baseline alignment or compensate with pixel offsets. The selected value, tags, and trailing controls share the field’s vertical center. Row Checkbox instances are inert visual indicators; the option owns selection and accessibility semantics.


---

# Segmented control

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/segmented-control
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=211-2

```tsx
import { SegmentedControl } from '@commenda/pathfinder/segmented-control';

<SegmentedControl
  label="View mode"
  value={value}
  onValueChange={setValue}
  options={[
    { value: 'monthly', label: 'Monthly' },
    { value: 'quarterly', label: 'Quarterly' },
    { value: 'annual', label: 'Annual' },
  ]}
/>;
```


## Usage [#usage]

```tsx
import { SegmentedControl } from '@commenda/pathfinder/segmented-control';

<SegmentedControl
  label="Billing interval"
  value={interval}
  onValueChange={setInterval}
  options={[
    { value: 'monthly', label: 'Monthly' },
    { value: 'quarterly', label: 'Quarterly' },
    { value: 'annual', label: 'Annual' },
  ]}
/>;
```

## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

## Examples [#examples]

### Small [#small]


```tsx
<SegmentedControl
  size="sm"
  label="View mode"
  value={value}
  onValueChange={setValue}
  options={options}
/>;
```


### Icon-only options [#icon-only-options]


```tsx
<SegmentedControl
  label="View mode"
  value={value}
  onValueChange={setValue}
  options={[
    {
      value: 'monthly',
      label: 'Grid view',
      iconOnly: true,
      leadingIcon: <Grid01Icon />,
    },
    {
      value: 'annual',
      label: 'List view',
      iconOnly: true,
      leadingIcon: <ListIcon />,
    },
  ]}
/>;
```


### Disabled [#disabled]


```tsx
<SegmentedControl
  disabled
  label="View mode"
  defaultValue="monthly"
  options={options}
/>;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Visible field label. Supply an accessible name when it is omitted. |
| `options` | `SegmentedControlOption[]` | required |  |
| `size` | `"sm" \| "md"` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |
| `disabledReason` | `string` | optional |  |
| `value` | `string` | conditional |  |
| `onValueChange` | `((value: string) => void)` | conditional |  |
| `defaultValue` | `string` | conditional |  |

Icon-only options use `iconOnly: true` and require `leadingIcon`; label remains required for the tooltip and accessible name. No public Root/Item parts or arbitrary row renderer.

`SEGMENTED-SELECTION-01`: Use two to four short, equal-weight choices with exactly one selected. Changes update immediately without Apply. Use one or two words per label, similar lengths. Use Tabs for more options or content sections, Switch for on/off, Button for actions. No empty selection. The caller must supply a valid value and reconcile removal of a selected option.

Tab enters the selected radio; arrows select enabled alternatives, including RTL behavior. Re-activating the selected option never deselects it. Name submits the selected string with the form. Disabled choices cannot be selected. Selected state remains visible when the whole group is disabled.

The source uses content-width segments, 16px icons at both sizes, a soft-pearl tray, 2px padding/gaps, 8px outer and 6px inner radii. Selected segment uses white, a hairline and control elevation. Exact source geometry and prose discrepancies are in the rules reference.

Import `@commenda/pathfinder/styles.css` once at the app root. Event handlers require a client component in Next.js App Router.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Menus and selection [#menus-and-selection]

- `SEGMENTED-SELECTION-01` — Figma: two to four short, equal-weight modes, one always selected, immediate change with no Apply. Use Tabs for more options/content sections, Switch for binary on/off, Button for actions. One or two words per label with similar lengths. Icon-only choices need tooltip and accessible name.

- `SEGMENTED-STYLE-01` — Figma: soft-pearl 200 tray, 300 hairline, radius 8, padding/gap 2. Segment radius 6, horizontal padding 8 sm/12 md, Label/13 Strong, optional 16px icon with gap 6. White selected segment uses control elevation. Hover fills 300; disabled dims the label.


---

# Select

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/select
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=182-1182

```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { Select } from '@commenda/pathfinder/select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const SelectDefault = () => (
  <Select
    label="Entity"
    placeholder="Select an entity"
    options={entityOptions}
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { Select } from '@commenda/pathfinder/select';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## Filled [#filled]


```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { Select } from '@commenda/pathfinder/select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const SelectFilled = () => (
  <Select label="Entity" defaultValue="gb" options={entityOptions} />
);
```


## Clearable [#clearable]


```tsx
import { DEFlag, GBFlag, INFlag, SGFlag } from '@commenda/pathfinder/flags';
import { Select } from '@commenda/pathfinder/select';

const entityOptions = [
  { value: 'gb', label: 'Meridian UK Ltd', leadingIcon: <GBFlag size={16} /> },
  { value: 'de', label: 'Meridian GmbH', leadingIcon: <DEFlag size={16} /> },
  { value: 'in', label: 'Meridian India', leadingIcon: <INFlag size={16} /> },
  {
    value: 'sg',
    label: 'Meridian Singapore',
    leadingIcon: <SGFlag size={16} />,
  },
];

export const SelectClearable = () => (
  <Select
    label="Entity"
    defaultValue="gb"
    options={entityOptions}
    clearConfig={{}}
  />
);
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `options` | `readonly ChoiceOption[]` | conditional | Exactly one source, stable string IDs |
| `groups` | `readonly ChoiceGroup[]` | conditional | Exactly one source, stable string IDs |
| `value` | `string \| null` | conditional | Controlled callback required; null clears |
| `defaultValue` | `string \| null` | optional | Controlled callback required; null clears |
| `searchConfig` | `{ mode: "local"; enabled?: boolean; placeholder?: string; } \| { mode: "remote"; query: string; onQueryChange: (query: string) => void; resultsQuery: string; isLoading: boolean; error?: string; onRetry?: () => void; placeholder?: string; }` | conditional | Local search enabled above eight options |
| `selectedOptions` | `readonly ChoiceOption[]` | optional | Remote metadata for selected IDs absent from results |
| `paginationConfig` | `ChoicePaginationConfig` | optional | Remote-only; application owns cursors |
| `renderConfig` | `{ optionContent?: (option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode; selectedContent?: (option: ChoiceOption) => ReactNode; }` | optional | Content only; no interactive descendants |
| `listConfig` | `{ virtualized?: boolean; maxHeight?: number; }` | optional | 320px maximum by default; opt-in virtualization enables search |
| `clearConfig` | `{ label?: string; }` | optional | Optional clear button |
| `addItemConfig` | `{ label: string; onAddItem: (query: string) => void; isDisabled?: boolean; }` | optional | Explicit creation action; app supplies the resulting record |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Defines a string value that labels the current element. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `name` | `string` | optional |  |
| `form` | `string` | optional |  |
| `autoComplete` | `string` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |
| `placeholder` | `string` | optional |  |
| `onBlur` | `FocusEventHandler<HTMLButtonElement>` | optional | Called when focus leaves the component. |
| `onFocus` | `FocusEventHandler<HTMLButtonElement>` | optional | Called when focus enters the component. |
| `emptyLabel` | `string` | optional |  |
| `onValueChange` | `((value: string \| null) => void)` | conditional |  |

### searchConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"local"` | Yes |  |
| `enabled` | `boolean` | No |  |
| `placeholder` | `string` | No |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"remote"` | Yes |  |
| `query` | `string` | Yes |  |
| `onQueryChange` | `(query: string) => void` | Yes |  |
| `resultsQuery` | `string` | Yes |  |
| `isLoading` | `boolean` | Yes |  |
| `error` | `string` | No |  |
| `onRetry` | `(() => void)` | No |  |
| `placeholder` | `string` | No |  |

### paginationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasMore` | `boolean` | Yes |  |
| `isLoadingMore` | `boolean` | Yes |  |
| `onLoadMore` | `() => void` | Yes |  |
| `error` | `string` | No |  |
| `onRetry` | `(() => void)` | No |  |

### renderConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionContent` | `((option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode)` | No |  |
| `selectedContent` | `((option: ChoiceOption) => ReactNode)` | No |  |

### listConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `virtualized` | `boolean` | No |  |
| `maxHeight` | `number` | No |  |

### clearConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |

### addItemConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `onAddItem` | `(query: string) => void` | Yes |  |
| `isDisabled` | `boolean` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

Shared labels, descriptions, required annotations, errorConfig, disableConfig, IDs, form names, refs, and focus/blur callbacks follow [Input](/docs/components/input). Selection controls do not expose readOnly.

## Local and remote search [#local-and-remote-search]

A ChoiceOption has `value`, `label`, optional `description`, `keywords`, `leadingIcon`, and `disableConfig`. Groups contain stable `id`, `label`, and `options`. Keywords participate only in local filtering. Rich rendering preserves plain-text labels for accessibility and search.

Local config: `{ mode: 'local', enabled?, placeholder? }`. Small local lists use Base UI Select; searchable lists use Base UI Combobox internally. There are exactly two public selection components: Select and MultiSelect.

Remote config: `{ mode: 'remote', query, onQueryChange, resultsQuery, isLoading, error?, onRetry?, placeholder? }`. Query updates immediately; the application owns debouncing, requests, cache, and cancellation. Remote results bypass client filtering and retain server order. While query differs from resultsQuery, stale options are unavailable for selection. Associate resultsQuery with the response that actually produced the options.

Supply selectedOptions for edit-form selections absent from current results. Selection never disappears merely because a page changes. A selected-only cache bridges user selection updates; it is not an unbounded history of every result. Missing metadata renders an explicit unavailable-value label until supplied.

Pagination receives accumulated, deduplicated options. New pages preserve scroll; new queries reset it. The UI gates duplicate load-more requests and provides a keyboard-accessible Load more button. Page errors preserve loaded results and offer retry. Virtualization limits mounted rows; remote pagination limits fetched data. Use both where appropriate.

Locked selected options survive tag removal, clear-all, Backspace, and bulk operations. MultiSelect select-all affects listed enabled options only and cannot imply selecting every record on a server. Bulk selection that would exceed a limit is disabled rather than partially applied.

### Search [#search]


```tsx
import { DEFlag, GBFlag, INFlag } from '@commenda/pathfinder/flags';
import { Select } from '@commenda/pathfinder/select';

export const SelectSearch = () => (
  <Select
    label="Country"
    searchConfig={{ mode: 'local', enabled: true }}
    clearConfig={{}}
    options={[
      {
        leadingIcon: <GBFlag size={16} />,
        value: 'gb',
        label: 'United Kingdom',
        keywords: ['Britain', 'UK'],
      },
      {
        leadingIcon: <DEFlag size={16} />,
        value: 'de',
        label: 'Germany',
        keywords: ['Deutschland'],
      },
      { leadingIcon: <INFlag size={16} />, value: 'in', label: 'India' },
    ]}
  />
);
```


### Groups [#groups]


```tsx
import { DEFlag, GBFlag } from '@commenda/pathfinder/flags';
import { Select } from '@commenda/pathfinder/select';

export const SelectGroups = () => (
  <Select
    label="Entity"
    groups={[
      {
        id: 'europe',
        label: 'Europe',
        options: [
          {
            leadingIcon: <GBFlag size={16} />,
            value: 'gb',
            label: 'Meridian UK Ltd',
            description: 'London',
          },
          {
            leadingIcon: <DEFlag size={16} />,
            value: 'de',
            label: 'Meridian GmbH',
            description: 'Berlin',
          },
        ],
      },
      {
        id: 'asia',
        label: 'Asia',
        options: [
          {
            value: 'in',
            label: 'Meridian India',
            disableConfig: { isDisabled: true, reason: 'Pending registration' },
          },
        ],
      },
    ]}
  />
);
```


### States [#states]


```tsx
import { GBFlag } from '@commenda/pathfinder/flags';
import { Select } from '@commenda/pathfinder/select';

export const SelectStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <Select label="Entity" options={[]} emptyLabel="No entities available." />
    <Select
      label="Locked entity"
      options={[
        {
          leadingIcon: <GBFlag size={16} />,
          value: 'gb',
          label: 'Meridian UK Ltd',
        },
      ]}
      defaultValue="gb"
      disableConfig={{ isDisabled: true, reason: 'This filing is locked.' }}
    />
    <Select
      label="Required entity"
      required
      options={[
        {
          leadingIcon: <GBFlag size={16} />,
          value: 'gb',
          label: 'Meridian UK Ltd',
        },
      ]}
      errorConfig={{ message: 'Choose an entity.', reveal: 'immediate' }}
    />
  </div>
);
```


### Large [#large]


```tsx
import { Select } from '@commenda/pathfinder/select';

export const SelectLarge = () => (
  <Select
    label="Entity"
    options={Array.from({ length: 10000 }, (_, index) => ({
      value: String(index),
      label: `Entity ${String(index + 1)}`,
    }))}
    listConfig={{ virtualized: true, maxHeight: 280 }}
  />
);
```


Read [selection and search rules](/docs/components/select#design-rules) for source provenance, API ownership, and constraints.

`autoComplete` forwards the native autocomplete token to the underlying selection control. Composite address fields use `country` and `address-level1`.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule       | Figma source       | Contract                                                                        |
| ---------- | ------------------ | ------------------------------------------------------------------------------- |
| SELECT-001 | 180:1177, 182:1206 | One selected value; popup 4px below trigger; search beyond about eight choices. |
| SELECT-002 | 182:236            | Selected flag/icon matches option presentation; placeholder has no flag.        |

Sources: [Search](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=635-13518), [Select](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=179-2), [MultiSelect](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=865-3077). The supplied Select node 182:1182 is its dimensions frame; 180:1177 is the actual component set.

### Field geometry and states [#field-geometry-and-states]

The component sheets are [Select 182:1216](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=182-1216) and [MultiSelect 865:3078](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=865-3078).

- **SELECT-VISUAL-001:** 28px field, 6px radius, 8px inner padding, 4px content gaps, 16px flag and chevron. Clear precedes the chevron (180:593). Empty fields have no leading flag.
- **MULTISELECT-VISUAL-001:** 4px starting inset; selected chips and +N are 20px high with radius 4 and a 0.5px pearl 300 border. Chip icons/removal are 12px; the final chevron is 16px (180:620).
- **SELECTION-STATE-001:** Pearl 400 default border; pearl 500 hover. Open fields retain blue 700 border and a 2px blue 200 ring while focus is in the popup (180:152, 180:766). Invalid uses red 600 at rest and red 700/red 200 when open. Error text is red 900 with a 12px alert icon (180:1031).
- **SELECTION-STATE-002:** Disabled fields use pearl 100 background, pearl 300 border, pearl 600 values and pearl 800 labels. Disabled MultiSelect chips omit removal buttons (180:839).

The Figma 320px MultiSelect frame clips part of the second chip inside a 256px strip. The implementation deliberately truncates the final visible chip's label instead, preserving its removal button and full-label tooltip; a 96px minimum keeps partial chips readable before using +N. Placeholder text uses pearl 800 rather than source pearl 700 to meet text contrast on white. These are documented accessibility adjustments, not new design variants.

The entire field opens the list; removal and clear remain independent buttons. Simple and searchable paths share the same field rendering. Popups follow the embedded Dropdown instances 182:606 and 865:59996 (10px radius, 6px list inset, 2px row gap, 32px minimum rows, 36px flush search row with 12px horizontal inset); option roles remain Select/Combobox semantics. Multi-selection uses Pathfinder Checkbox in read-only presentation mode inside each option; the option owns selection and keyboard focus. Select-all is a functional Checkbox with mixed state. Single selection shows a trailing check. Search, clear and removal icons sit in explicit flex boxes so their centers align with the input and chip rows.

### API ownership [#api-ownership]

Exactly Select and MultiSelect are public. Both support local search, server search, groups, rich option content, pagination, and virtualization. Dropdown remains an action menu. Free-text query entry belongs to Search; typed text never silently becomes a selected option ID.

The application owns query requests, debounce, cancellation, cursors, deduplicated page merging, and cache invalidation. Pathfinder blocks stale-query selection using query/resultsQuery, retains server ranking, and displays initial loading, empty, error, load-more, and retry states. Do not pass yesterday's query as resultsQuery for today's response.

Use a query-keyed data hook or AbortController plus request identity protection. A late response for an earlier query must not overwrite the active query's results. Reset cursors when the query changes. The interactive remote example uses a cancellable simulated transport so it works without an application endpoint; replace it with your authenticated API adapter.

Selected IDs and selectedOptions are separate from fetched pages. selectedOptions resolves labels/icons for saved values missing from the current result set. It does not pin unmatched rows to the results. The component caches only currently selected metadata as a bridge; applications remain responsible for authoritative record updates and deleted-record decisions.

### Large lists and bulk actions [#large-lists-and-bulk-actions]

Enable listConfig.virtualized for large lists. This enables searchable interaction and measured-height rows; keyboard-highlighted options stay mounted. API pagination and virtualization solve different costs and can be combined. Option values must be globally unique and stable across groups and pages.

Select-all means currently listed, filtered, enabled results. Locked values survive all UI removal paths. A bulk selection that exceeds selectionLimitConfig.max is disabled; it never chooses an arbitrary subset. Selecting all matches across an entire backend requires a separate server-side selection model.

Custom renderers supply noninteractive content. Pathfinder owns trigger and option roles, events, refs, selection indicators, and focus. Add-item is a separate explicit action; application creation returns a real record and updates options/value.

### Accessibility and forms [#accessibility-and-forms]

Labels, descriptions, error reveal, and disable reasons follow the shared field contract. Single selection serializes one ID; multiple selection serializes repeated names. Trigger refs and form reset work for both primitive paths. Searchable popups provide an explicitly named query input. Load more and retry are keyboard-accessible buttons outside the option list.

Tag remove buttons are siblings of the trigger, never nested inside it. Long selected labels remain available through tooltips. Search result compositions must handle overlay Escape before field clear/collapse through preventDefault.

Flags, chevrons, and clear/remove icons sit in explicit square flex containers with both axes centered. Do not rely on inline SVG baseline alignment or compensate with pixel offsets. The selected value, tags, and trailing controls share the field’s vertical center. Row Checkbox instances are inert visual indicators; the option owns selection and accessibility semantics.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

- **Editors:** Select and DatePicker retain their existing control heights; they are not pixel-identical to compact picker drawings. Text/number editors use the compact geometry. Async save errors remain visibly actionable with retry.

### Motion and edge cases [#motion-and-edge-cases]

Long titles, action labels and descriptions wrap. Bodies scroll within constrained viewports. Test nested Select/Popover, narrow screens, RTL, zoom, repeated Escape, pending/rejected close guards, pointer cancel, and focus return. Do not hide validation errors or close a form before submission succeeds.

### Selection guidance [#selection-guidance]

- `DROPDOWN-FUTURE-01` — Figma selection guidance (the historical rule ID is retained): search beyond about eight choices; empty state names the query; footer has one link action outside options. Multiple selection keeps the popup open and preserves row order. Selected rows have checks; highlight remains independent. These selection behaviors belong to Select and MultiSelect, not the action-oriented Dropdown.


---

# Separator

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/separator
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=342-2

```tsx
import { Separator } from '@commenda/pathfinder/separator';

export const SeparatorDefault = () => (
  <div style={{ width: '100%' }}>
    <p>Registered agent</p>
    <Separator />
    <p>Fiscal year end</p>
  </div>
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/separator`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `variant` | `"line" \| "label" \| "dot"` | conditional | line; label requires visible label text |
| `orientation` | `"vertical" \| "horizontal"` | optional | horizontal; line only |
| `decorative` | `boolean` | optional | true; line only |
| `label` | `string` | conditional | Required for label; disallowed for other variants |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `className` | `string` | optional | Additional classes for the component root. |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported.

## Usage rules [#usage-rules]

Use spacing first. A separator has no surrounding margin: its parent owns the layout. Use `decorative={false}` for boundaries that assistive technology should identify. Vertical separators are 16 tall by default; a parent can stretch them through layout classes. Labeled lines keep their text available while hiding the rules. Dot is always decorative.

## Examples [#examples]

### Variants [#variants]


```tsx
import { Separator } from '@commenda/pathfinder/separator';

export const SeparatorVariants = () => (
  <div style={{ display: 'grid', gap: 24, width: '100%' }}>
    <Separator />
    <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
      Subsidiary
      <Separator variant="dot" />
      Berlin
      <Separator orientation="vertical" />
      Active
    </div>
    <Separator variant="label" label="or" />
  </div>
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Separator [#separator]

Source: [342:9](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=342-9), docs 343:542, dot 405:47.

- `SEPARATOR-01` — Source: 0.5 soft-pearl-300 hairline, horizontal fill or vertical 16. Parent owns spacing. A label sits between two lines with 12 gaps; inline dot uses parent gap 6. Prefer whitespace before adding a rule.
- `SEPARATOR-02` — Source/Pathfinder: decorative by default. Meaningful line boundaries expose separator orientation; the label's word remains readable while its lines are decorative. Dot is always decorative and never focusable.

### Source discrepancies and implementation decisions [#source-discrepancies-and-implementation-decisions]

Vertical lines use a 1px inline width to stay visible on standard-density displays; their default height is 16px. The parent owns surrounding spacing.


---

# Sheet

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/sheet
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=379-2

```tsx
import { Button } from '@commenda/pathfinder/button';
import { Input } from '@commenda/pathfinder/input';
import { Sheet } from '@commenda/pathfinder/sheet';

export const SheetDefault = () => (
  <Sheet
    title="Delaware annual report 2026"
    description="Acme Inc. · due 1 March 2027"
    trigger={<Button variant="secondary">Open filing</Button>}
    footerConfig={{}}
  >
    <Input label="Filing reference" defaultValue="DE-2026-001" />
    <p>The page remains available while reviewing this filing.</p>
  </Sheet>
);
```


Import `Sheet` from `@commenda/pathfinder/sheet`.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `side` | `"right" \| "bottom"` | conditional | right |
| `size` | `"sm" \| "md" \| "lg"` | optional | md; right widths 400 / 520 / 720px |
| `modal` | `boolean` | optional | false; page stays usable and page clicks do not dismiss |
| `dragConfig` | `{ dismissible: boolean; }` | optional | Bottom only; true by default |
| `title` | `string` | required | Required accessible title |
| `description` | `ReactNode` | optional | Required accessible title |
| `trigger` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | optional | Required accessible title |
| `children` | `ReactNode` | required | Required accessible title |
| `open` | `boolean` | conditional | Controlled or uncontrolled |
| `defaultOpen` | `boolean` | optional | Controlled or uncontrolled |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Controlled or uncontrolled |
| `footerConfig` | `OverlayFooterConfig` | optional | Shared action/focus/guard contracts |
| `dismissConfig` | `OverlayDismissConfig` | optional | Shared action/focus/guard contracts |
| `focusConfig` | `OverlayFocusConfig` | optional | Shared action/focus/guard contracts |
| `className` | `string` | optional | Shared action/focus/guard contracts |

### dragConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dismissible` | `boolean` | Yes |  |

### footerConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primaryAction` | `OverlayAction` | No |  |
| `secondaryAction` | `OverlayAction` | No |  |
| `leadingContent` | `ReactNode` | No |  |
| `cancelLabel` | `string` | No |  |

### dismissConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `outsidePress` | `boolean` | No |  |
| `beforeClose` | `((reason: OverlayCloseReason) => boolean \| Promise<boolean>)` | No |  |
| `onError` | `((error: unknown) => void)` | No |  |

### focusConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `initialFocusRef` | `RefObject<HTMLElement \| null>` | No |  |
| `returnFocusRef` | `RefObject<HTMLElement \| null>` | No |  |

`open` with `onOpenChange` is controlled; otherwise use `defaultOpen`. Primary actions never imply success or automatically close the surface. Close it after the application completes its work.

`footerConfig` accepts `primaryAction`, `secondaryAction`, `leadingContent`, and `cancelLabel`. Actions have `label`, `onClick`, native `type`/`form`, `disabled`, `disabledReason`, `loadingConfig`, `destructive`, and icons. Without a secondary action the footer renders Cancel. A footer is absent unless configured. Submit uses native form IDs; IDs must be unique.

## Bottom sheet [#bottom-sheet]


```tsx
import { Button } from '@commenda/pathfinder/button';
import { Input } from '@commenda/pathfinder/input';
import { Sheet } from '@commenda/pathfinder/sheet';

export const SheetBottom = () => (
  <Sheet
    side="bottom"
    title="Filter filings"
    description="Drag the handle down or use Close to dismiss."
    trigger={<Button variant="secondary">Filter filings</Button>}
    footerConfig={{}}
  >
    <Input label="Reference" placeholder="DE-2026" />
    <div style={{ minHeight: 280, paddingTop: 16 }}>
      <p>Keep short filters in the centered content column.</p>
    </div>
  </Sheet>
);
```


The centered column is at most 640px; the sheet is at most 96dvh. Drag only the handle: a downward release over 0.4px/ms or distance over 25% of sheet height requests dismissal. Close, Escape, Cancel, and keyboard activation of the handle are equivalent alternatives. The body remains independently scrollable.

## Modal mode [#modal-mode]


```tsx
import { Button } from '@commenda/pathfinder/button';
import { Input } from '@commenda/pathfinder/input';
import { Sheet } from '@commenda/pathfinder/sheet';

export const SheetModal = () => (
  <Sheet
    modal
    title="Edit registered address"
    trigger={<Button variant="secondary">Open modal sheet</Button>}
    footerConfig={{}}
  >
    <Input label="Address line 1" defaultValue="100 Main Street" />
  </Sheet>
);
```


Modal mode couples the backdrop, focus containment, and page scroll lock. Outside dismissal remains off unless `dismissConfig.outsidePress=true`. Nonmodal sheets always ignore page clicks. Right sheets have a 16px inset and clamp to the viewport.

## Unsaved changes [#unsaved-changes]


```tsx
import { useRef, useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { ConfirmDialog } from '@commenda/pathfinder/dialog';
import { Input } from '@commenda/pathfinder/input';
import { Sheet } from '@commenda/pathfinder/sheet';

export const SheetGuarded = () => {
  const [open, setOpen] = useState(false);
  const [confirmation, setConfirmation] = useState(false);
  const decision = useRef<((allow: boolean) => void) | null>(null);

  const finish = (allow: boolean) => {
    decision.current?.(allow);
    decision.current = null;
    setConfirmation(false);
  };

  return (
    <Sheet
      open={open}
      onOpenChange={setOpen}
      title="Edit entity"
      trigger={
        <Button variant="secondary">Edit with discard protection</Button>
      }
      dismissConfig={{
        beforeClose: () =>
          new Promise<boolean>((resolve) => {
            decision.current = resolve;
            setConfirmation(true);
          }),
      }}
      footerConfig={{}}
    >
      <Input label="Legal name" defaultValue="Acme Inc." />
      <ConfirmDialog
        open={confirmation}
        onOpenChange={(next) => {
          if (!next) finish(false);
        }}
        title="Discard changes?"
        description="Your unsaved changes will be lost."
        cancelLabel="Keep editing"
        confirmAction={{
          label: 'Discard changes',
          destructive: true,
          onClick: () => {
            finish(true);
          },
        }}
      />
    </Sheet>
  );
};
```


`beforeClose` also receives `swipe`. The application can show a ConfirmDialog and resolve the pending decision. Keep a single Sheet open, with at most its confirmation above it. The application owns request cancellation and should resolve outstanding confirmations if it removes the sheet. Read the [overlay rules](/docs/components/sheet#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Sheet [#sheet]

- **SHEET-001:** Right widths 400/520/720px, default 520, inset 16, viewport height minus 32. Bottom maximum 96dvh, pearl-100 surface, top radius12, centered640 column, handle48×6; safe-area bottom padding.
- **SHEET-002:** Nonmodal by default, unlike Kakashi’s legacy default. Page remains usable and page clicks do not close it. Modal mode couples backdrop, focus containment, and scroll lock. Keep one Sheet, with its confirmation when necessary.
- **SHEET-003:** Bottom handle only: distance over25% or downward release velocity over0.4px/ms, pointer capture, multi-pointer protection, cancel/reset. Body scroll does not drag. Guard swipe just like Close; keyboard, Escape, and Cancel alternatives remain available. Base UI Drawer1.9 uses a fixed0.5px/ms threshold and broader gesture handling, so the private gesture layer wraps Base UI Dialog rather than copying app logic.

### Motion and edge cases [#motion-and-edge-cases]

Occasional overlays use motion for spatial consistency. Motion paths and timings follow Kakashi: Dialog fades and moves from 95% scale with a 2% vertical offset in 200ms both ways; Popover fades from 95% scale and an 8px offset toward its trigger in 150ms both ways. Popover direction follows the resolved placement after collision handling. Right Sheet slides in for 500ms and out for 300ms; bottom Sheet slides for 500ms both ways. Sheet panels do not fade during normal motion, and modal backdrops follow the panel duration.

Pathfinder retains its foundation ease-out curve for Dialog/Popover and drawer curve `(0.32,0.72,0,1)` for Sheets. These are deliberate curve choices; this is not a copy of Kakashi’s legacy Radix keyframe implementation. Base UI continues to own presence, focus and dismissal. Transitions use a single `transform` value plus opacity where relevant, so Tailwind v4’s separate scale/translate properties cannot bypass interpolation. Closing or reopening mid-transition reverses from the current rendered position.

Keyboard opening and dismissal remain immediate, including Close and Cancel activation. Reduced motion removes scale and translation: Dialog/Popover keep their fade, while Sheets change position immediately and their modal backdrop can fade. Drag writes only the popup transform, never layout or inherited animation variables. Programmatic openings animate by default; explicit keyboard interactions suppress motion.


---

# Side nav

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/side-nav
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=714-2

```tsx
import { useState } from 'react';

import { Avatar } from '@commenda/pathfinder/avatar';
import { Dropdown } from '@commenda/pathfinder/dropdown';
import { BookOpen01Icon } from '@commenda/pathfinder/icons/BookOpen01Icon';
import { Building06Icon } from '@commenda/pathfinder/icons/Building06Icon';
import { CalendarIcon } from '@commenda/pathfinder/icons/CalendarIcon';
import { CheckDone01Icon } from '@commenda/pathfinder/icons/CheckDone01Icon';
import { CoinsStacked03Icon } from '@commenda/pathfinder/icons/CoinsStacked03Icon';
import { CoinsSwap01Icon } from '@commenda/pathfinder/icons/CoinsSwap01Icon';
import { CommendaBrandIcon } from '@commenda/pathfinder/icons/CommendaBrandIcon';
import { File06Icon } from '@commenda/pathfinder/icons/File06Icon';
import { FolderIcon } from '@commenda/pathfinder/icons/FolderIcon';
import { HelpCircleIcon } from '@commenda/pathfinder/icons/HelpCircleIcon';
import { HomeLineIcon } from '@commenda/pathfinder/icons/HomeLineIcon';
import { Inbox01Icon } from '@commenda/pathfinder/icons/Inbox01Icon';
import { PneumaIcon } from '@commenda/pathfinder/icons/PneumaIcon';
import { Settings01Icon } from '@commenda/pathfinder/icons/Settings01Icon';
import { ShoppingBag02Icon } from '@commenda/pathfinder/icons/ShoppingBag02Icon';
import { Users01Icon } from '@commenda/pathfinder/icons/Users01Icon';
import { CommendaLockupLogo } from '@commenda/pathfinder/logos/commenda/CommendaLockupLogo';
import { SideNav, type SideNavSection } from '@commenda/pathfinder/side-nav';

const workspaceSections: SideNavSection[] = [
  {
    id: 'main',
    items: [
      {
        kind: 'link',
        id: 'home',
        label: 'Home',
        icon: <HomeLineIcon />,
        linkConfig: { href: '#home' },
      },
      {
        kind: 'link',
        id: 'tasks',
        label: 'Tasks',
        icon: <CheckDone01Icon />,
        count: 4,
        linkConfig: { href: '#tasks' },
      },
      {
        kind: 'link',
        id: 'inbox',
        label: 'Inbox',
        icon: <Inbox01Icon />,
        count: 3,
        unread: true,
        linkConfig: { href: '#inbox' },
      },
    ],
  },
  {
    id: 'overview',
    label: 'Overview',
    collapsible: true,
    items: [
      {
        kind: 'link',
        id: 'entities',
        label: 'Legal entities',
        icon: <Building06Icon />,
        linkConfig: { href: '#entities' },
      },
      {
        kind: 'link',
        id: 'people',
        label: 'Key persons',
        icon: <Users01Icon />,
        linkConfig: { href: '#people' },
      },
      {
        kind: 'link',
        id: 'calendar',
        label: 'Compliance calendar',
        icon: <CalendarIcon />,
        linkConfig: { href: '#calendar' },
      },
      {
        kind: 'group',
        id: 'documents',
        label: 'Documents',
        icon: <FolderIcon />,
        linkConfig: { href: '#documents' },
        children: [
          {
            kind: 'link',
            id: 'formation',
            label: 'Formation',
            icon: <FolderIcon />,
            linkConfig: { href: '#formation' },
          },
          {
            kind: 'link',
            id: 'tax-docs',
            label: 'Tax',
            icon: <FolderIcon />,
            linkConfig: { href: '#tax-docs' },
          },
        ],
      },
    ],
  },
  {
    id: 'apps',
    label: 'My apps',
    collapsible: true,
    items: [
      {
        kind: 'link',
        id: 'indirect-tax',
        label: 'Global indirect tax',
        icon: <CoinsStacked03Icon />,
        linkConfig: { href: '#indirect-tax' },
      },
      {
        kind: 'link',
        id: 'reporting',
        label: 'Tax & reporting',
        icon: <File06Icon />,
        linkConfig: { href: '#reporting' },
      },
      {
        kind: 'link',
        id: 'accounting',
        label: 'Accounting',
        icon: <BookOpen01Icon />,
        linkConfig: { href: '#accounting' },
      },
      {
        kind: 'link',
        id: 'transfer',
        label: 'Transfer pricing',
        icon: <CoinsSwap01Icon />,
        linkConfig: { href: '#transfer' },
      },
      {
        kind: 'link',
        id: 'marketplace',
        label: 'Marketplace',
        icon: <ShoppingBag02Icon />,
        linkConfig: { href: '#marketplace' },
      },
    ],
  },
];

const chatSections: SideNavSection[] = [
  {
    id: 'chat-main',
    items: [
      {
        kind: 'link',
        id: 'new-chat',
        label: 'New chat',
        icon: <PneumaIcon />,
        linkConfig: { href: '#new-chat' },
      },
      {
        kind: 'link',
        id: 'agents',
        label: 'Agents',
        icon: <Users01Icon />,
        linkConfig: { href: '#agents' },
      },
    ],
  },
];

const accountFooter = (collapsed: boolean) => (
  <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
    {[
      {
        label: 'Settings',
        href: '#settings',
        icon: <Settings01Icon size={16} />,
      },
      {
        label: 'Help & support',
        href: '#help',
        icon: <HelpCircleIcon size={16} />,
      },
    ].map((item) => (
      <a
        key={item.href}
        href={item.href}
        aria-label={item.label}
        title={collapsed ? item.label : undefined}
        style={{
          display: 'flex',
          alignItems: 'center',
          gap: 12,
          padding: collapsed ? 6 : '6px 8px',
          minHeight: 28,
          boxSizing: 'border-box',
          color: 'inherit',
          textDecoration: 'none',
          borderRadius: 6,
        }}
      >
        {item.icon}
        {!collapsed && item.label}
      </a>
    ))}
    <Dropdown
      menu={{
        groups: [
          {
            id: 'account',
            items: [
              {
                id: 'profile',
                type: 'link',
                label: 'Your profile',
                linkConfig: { href: '#profile' },
              },
              {
                id: 'organization',
                type: 'link',
                label: 'Organization settings',
                linkConfig: { href: '#organization' },
              },
            ],
          },
        ],
      }}
      trigger={
        <button
          type="button"
          aria-label="Account menu for Sam Schulte"
          style={{
            display: 'flex',
            alignItems: 'center',
            gap: 8,
            padding: 4,
            border: 0,
            background: 'transparent',
            font: 'inherit',
            color: 'inherit',
            textAlign: 'start',
            borderRadius: 6,
          }}
        >
          <Avatar
            identity={{ kind: 'person', userId: 'sam', name: 'Sam Schulte' }}
            size={20}
            decorative
          />
          {!collapsed && 'Sam Schulte'}
        </button>
      }
    />
  </div>
);

export const SideNavDefault = () => {
  const [mode, setMode] = useState('home');
  const [active, setActive] = useState<string | null>('home');

  return (
    <div style={{ height: 720, display: 'flex', gap: 16, minWidth: 0 }}>
      <SideNav
        label="Workspace"
        activeId={active}
        sections={mode === 'home' ? workspaceSections : chatSections}
        header={(collapsed) =>
          collapsed ? (
            <CommendaBrandIcon size={20} label="Commenda" />
          ) : (
            <CommendaLockupLogo label="Commenda" />
          )
        }
        footer={accountFooter}
        modeConfig={{
          label: 'Workspace mode',
          value: mode,
          onValueChange: setMode,
          options: [
            { value: 'home', label: 'Home', leadingIcon: <HomeLineIcon /> },
            { value: 'chat', label: 'Chat', leadingIcon: <PneumaIcon /> },
          ],
        }}
        renderLink={(props) => (
          <a
            {...props}
            href={props.href}
            onClick={(event) => {
              event.preventDefault();
              setActive(props.href?.slice(1) ?? null);
            }}
          >
            {props.children}
          </a>
        )}
      />
    </div>
  );
};
```


Import `SideNav` from `@commenda/pathfinder/side-nav`. The application owns routes, active destination, permissions and persistence. No workspace providers, cookies or global shortcuts are required.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required navigation landmark name |
| `sections` | `readonly SideNavSection[]` | required | IDs, optional label/collapsible, recursive items |
| `activeId` | `string \| null` | required | Current destination; receives aria-current=page |
| `collapseConfig` | `SelectionProps<boolean>` | optional | `{ value, onValueChange }` or `{ defaultValue?, onValueChange? }`; false initially |
| `expansionConfig` | `SelectionProps<readonly string[]>` | optional | Section and group IDs; collapsible sections start open |
| `header` | `ReactNode \| ((collapsed: boolean) => ReactNode)` | optional | Slots can adapt to the rail |
| `footer` | `ReactNode \| ((collapsed: boolean) => ReactNode)` | optional | Slots can adapt to the rail |
| `modeConfig` | `SegmentedControlProps` | optional | Optional view-mode switch; app supplies matching sections |
| `renderLink` | `((props: React.ComponentPropsWithRef<"a">) => React.ReactElement)` | optional | Next Link integration; item renderer takes precedence |
| `className` | `string` | optional | Root nav classes; parent supplies available height |

### collapseConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `boolean` | Yes |  |
| `onValueChange` | `(value: boolean) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `boolean` | No |  |
| `onValueChange` | `((value: boolean) => void)` | No |  |

Do not supply: `value`.

### expansionConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `readonly string[]` | Yes |  |
| `onValueChange` | `(value: readonly string[]) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `readonly string[]` | No |  |
| `onValueChange` | `((value: readonly string[]) => void)` | No |  |

Do not supply: `value`.

An item has `id`, `label`, `icon`, optional `count`, `unread`, and `disableConfig: { isDisabled, reason? }`. Its `kind` distinguishes `link` with `linkConfig`, `action` with `onAction`, or `group` with recursive `children` and optional landing `linkConfig`. A landing link and its chevron are distinct targets. A group without a landing link expands on activation.

Keep section and item IDs stable and globally distinct. `linkConfig` supports `href`, `target`, `rel`, and a ref-forwarding `render`. Renderers must preserve supplied accessibility props, handlers and refs. Actions and links are mutually exclusive. Counts and unread state stay accessible in the rail.

## Collapsed rail [#collapsed-rail]


```tsx
import { Avatar } from '@commenda/pathfinder/avatar';
import { Dropdown } from '@commenda/pathfinder/dropdown';
import { BookOpen01Icon } from '@commenda/pathfinder/icons/BookOpen01Icon';
import { Building06Icon } from '@commenda/pathfinder/icons/Building06Icon';
import { CalendarIcon } from '@commenda/pathfinder/icons/CalendarIcon';
import { CheckDone01Icon } from '@commenda/pathfinder/icons/CheckDone01Icon';
import { CoinsStacked03Icon } from '@commenda/pathfinder/icons/CoinsStacked03Icon';
import { CoinsSwap01Icon } from '@commenda/pathfinder/icons/CoinsSwap01Icon';
import { CommendaBrandIcon } from '@commenda/pathfinder/icons/CommendaBrandIcon';
import { File06Icon } from '@commenda/pathfinder/icons/File06Icon';
import { FolderIcon } from '@commenda/pathfinder/icons/FolderIcon';
import { HelpCircleIcon } from '@commenda/pathfinder/icons/HelpCircleIcon';
import { HomeLineIcon } from '@commenda/pathfinder/icons/HomeLineIcon';
import { Inbox01Icon } from '@commenda/pathfinder/icons/Inbox01Icon';
import { Settings01Icon } from '@commenda/pathfinder/icons/Settings01Icon';
import { ShoppingBag02Icon } from '@commenda/pathfinder/icons/ShoppingBag02Icon';
import { Users01Icon } from '@commenda/pathfinder/icons/Users01Icon';
import { CommendaLockupLogo } from '@commenda/pathfinder/logos/commenda/CommendaLockupLogo';
import { SideNav, type SideNavSection } from '@commenda/pathfinder/side-nav';

const workspaceSections: SideNavSection[] = [
  {
    id: 'main',
    items: [
      {
        kind: 'link',
        id: 'home',
        label: 'Home',
        icon: <HomeLineIcon />,
        linkConfig: { href: '#home' },
      },
      {
        kind: 'link',
        id: 'tasks',
        label: 'Tasks',
        icon: <CheckDone01Icon />,
        count: 4,
        linkConfig: { href: '#tasks' },
      },
      {
        kind: 'link',
        id: 'inbox',
        label: 'Inbox',
        icon: <Inbox01Icon />,
        count: 3,
        unread: true,
        linkConfig: { href: '#inbox' },
      },
    ],
  },
  {
    id: 'overview',
    label: 'Overview',
    collapsible: true,
    items: [
      {
        kind: 'link',
        id: 'entities',
        label: 'Legal entities',
        icon: <Building06Icon />,
        linkConfig: { href: '#entities' },
      },
      {
        kind: 'link',
        id: 'people',
        label: 'Key persons',
        icon: <Users01Icon />,
        linkConfig: { href: '#people' },
      },
      {
        kind: 'link',
        id: 'calendar',
        label: 'Compliance calendar',
        icon: <CalendarIcon />,
        linkConfig: { href: '#calendar' },
      },
      {
        kind: 'group',
        id: 'documents',
        label: 'Documents',
        icon: <FolderIcon />,
        linkConfig: { href: '#documents' },
        children: [
          {
            kind: 'link',
            id: 'formation',
            label: 'Formation',
            icon: <FolderIcon />,
            linkConfig: { href: '#formation' },
          },
          {
            kind: 'link',
            id: 'tax-docs',
            label: 'Tax',
            icon: <FolderIcon />,
            linkConfig: { href: '#tax-docs' },
          },
        ],
      },
    ],
  },
  {
    id: 'apps',
    label: 'My apps',
    collapsible: true,
    items: [
      {
        kind: 'link',
        id: 'indirect-tax',
        label: 'Global indirect tax',
        icon: <CoinsStacked03Icon />,
        linkConfig: { href: '#indirect-tax' },
      },
      {
        kind: 'link',
        id: 'reporting',
        label: 'Tax & reporting',
        icon: <File06Icon />,
        linkConfig: { href: '#reporting' },
      },
      {
        kind: 'link',
        id: 'accounting',
        label: 'Accounting',
        icon: <BookOpen01Icon />,
        linkConfig: { href: '#accounting' },
      },
      {
        kind: 'link',
        id: 'transfer',
        label: 'Transfer pricing',
        icon: <CoinsSwap01Icon />,
        linkConfig: { href: '#transfer' },
      },
      {
        kind: 'link',
        id: 'marketplace',
        label: 'Marketplace',
        icon: <ShoppingBag02Icon />,
        linkConfig: { href: '#marketplace' },
      },
    ],
  },
];

const accountFooter = (collapsed: boolean) => (
  <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
    {[
      {
        label: 'Settings',
        href: '#settings',
        icon: <Settings01Icon size={16} />,
      },
      {
        label: 'Help & support',
        href: '#help',
        icon: <HelpCircleIcon size={16} />,
      },
    ].map((item) => (
      <a
        key={item.href}
        href={item.href}
        aria-label={item.label}
        title={collapsed ? item.label : undefined}
        style={{
          display: 'flex',
          alignItems: 'center',
          gap: 12,
          padding: collapsed ? 6 : '6px 8px',
          minHeight: 28,
          boxSizing: 'border-box',
          color: 'inherit',
          textDecoration: 'none',
          borderRadius: 6,
        }}
      >
        {item.icon}
        {!collapsed && item.label}
      </a>
    ))}
    <Dropdown
      menu={{
        groups: [
          {
            id: 'account',
            items: [
              {
                id: 'profile',
                type: 'link',
                label: 'Your profile',
                linkConfig: { href: '#profile' },
              },
              {
                id: 'organization',
                type: 'link',
                label: 'Organization settings',
                linkConfig: { href: '#organization' },
              },
            ],
          },
        ],
      }}
      trigger={
        <button
          type="button"
          aria-label="Account menu for Sam Schulte"
          style={{
            display: 'flex',
            alignItems: 'center',
            gap: 8,
            padding: 4,
            border: 0,
            background: 'transparent',
            font: 'inherit',
            color: 'inherit',
            textAlign: 'start',
            borderRadius: 6,
          }}
        >
          <Avatar
            identity={{ kind: 'person', userId: 'sam', name: 'Sam Schulte' }}
            size={20}
            decorative
          />
          {!collapsed && 'Sam Schulte'}
        </button>
      }
    />
  </div>
);

export const SideNavCollapsed = () => (
  <div style={{ height: 720 }}>
    <SideNav
      label="Compact workspace"
      activeId="home"
      sections={workspaceSections}
      collapseConfig={{ defaultValue: true }}
      header={(collapsed) =>
        collapsed ? (
          <CommendaBrandIcon size={20} label="Commenda" />
        ) : (
          <CommendaLockupLogo label="Commenda" />
        )
      }
      footer={accountFooter}
    />
  </div>
);
```


Expanded width is 208px; the rail is 56px. Rows are 28px, icons 16px. In the rail, group activation expands navigation to reveal its children; groups with a destination preserve that link, and the Expand sidebar control reveals their descendants. Header/footer render functions prevent a long organization name from overflowing a rail.

## Controlled state [#controlled-state]


```tsx
import { useState } from 'react';

import { BookOpen01Icon } from '@commenda/pathfinder/icons/BookOpen01Icon';
import { Building06Icon } from '@commenda/pathfinder/icons/Building06Icon';
import { CalendarIcon } from '@commenda/pathfinder/icons/CalendarIcon';
import { CheckDone01Icon } from '@commenda/pathfinder/icons/CheckDone01Icon';
import { CoinsStacked03Icon } from '@commenda/pathfinder/icons/CoinsStacked03Icon';
import { CoinsSwap01Icon } from '@commenda/pathfinder/icons/CoinsSwap01Icon';
import { File06Icon } from '@commenda/pathfinder/icons/File06Icon';
import { FolderIcon } from '@commenda/pathfinder/icons/FolderIcon';
import { HomeLineIcon } from '@commenda/pathfinder/icons/HomeLineIcon';
import { Inbox01Icon } from '@commenda/pathfinder/icons/Inbox01Icon';
import { ShoppingBag02Icon } from '@commenda/pathfinder/icons/ShoppingBag02Icon';
import { Users01Icon } from '@commenda/pathfinder/icons/Users01Icon';
import { SideNav, type SideNavSection } from '@commenda/pathfinder/side-nav';

const workspaceSections: SideNavSection[] = [
  {
    id: 'main',
    items: [
      {
        kind: 'link',
        id: 'home',
        label: 'Home',
        icon: <HomeLineIcon />,
        linkConfig: { href: '#home' },
      },
      {
        kind: 'link',
        id: 'tasks',
        label: 'Tasks',
        icon: <CheckDone01Icon />,
        count: 4,
        linkConfig: { href: '#tasks' },
      },
      {
        kind: 'link',
        id: 'inbox',
        label: 'Inbox',
        icon: <Inbox01Icon />,
        count: 3,
        unread: true,
        linkConfig: { href: '#inbox' },
      },
    ],
  },
  {
    id: 'overview',
    label: 'Overview',
    collapsible: true,
    items: [
      {
        kind: 'link',
        id: 'entities',
        label: 'Legal entities',
        icon: <Building06Icon />,
        linkConfig: { href: '#entities' },
      },
      {
        kind: 'link',
        id: 'people',
        label: 'Key persons',
        icon: <Users01Icon />,
        linkConfig: { href: '#people' },
      },
      {
        kind: 'link',
        id: 'calendar',
        label: 'Compliance calendar',
        icon: <CalendarIcon />,
        linkConfig: { href: '#calendar' },
      },
      {
        kind: 'group',
        id: 'documents',
        label: 'Documents',
        icon: <FolderIcon />,
        linkConfig: { href: '#documents' },
        children: [
          {
            kind: 'link',
            id: 'formation',
            label: 'Formation',
            icon: <FolderIcon />,
            linkConfig: { href: '#formation' },
          },
          {
            kind: 'link',
            id: 'tax-docs',
            label: 'Tax',
            icon: <FolderIcon />,
            linkConfig: { href: '#tax-docs' },
          },
        ],
      },
    ],
  },
  {
    id: 'apps',
    label: 'My apps',
    collapsible: true,
    items: [
      {
        kind: 'link',
        id: 'indirect-tax',
        label: 'Global indirect tax',
        icon: <CoinsStacked03Icon />,
        linkConfig: { href: '#indirect-tax' },
      },
      {
        kind: 'link',
        id: 'reporting',
        label: 'Tax & reporting',
        icon: <File06Icon />,
        linkConfig: { href: '#reporting' },
      },
      {
        kind: 'link',
        id: 'accounting',
        label: 'Accounting',
        icon: <BookOpen01Icon />,
        linkConfig: { href: '#accounting' },
      },
      {
        kind: 'link',
        id: 'transfer',
        label: 'Transfer pricing',
        icon: <CoinsSwap01Icon />,
        linkConfig: { href: '#transfer' },
      },
      {
        kind: 'link',
        id: 'marketplace',
        label: 'Marketplace',
        icon: <ShoppingBag02Icon />,
        linkConfig: { href: '#marketplace' },
      },
    ],
  },
];

export const SideNavControlled = () => {
  const [collapsed, setCollapsed] = useState(false);
  const [expanded, setExpanded] = useState<readonly string[]>([
    'overview',
    'documents',
  ]);

  return (
    <div style={{ height: 480 }}>
      <SideNav
        label="Controlled workspace"
        activeId="formation"
        sections={workspaceSections}
        collapseConfig={{ value: collapsed, onValueChange: setCollapsed }}
        expansionConfig={{ value: expanded, onValueChange: setExpanded }}
      />
      <p>
        {collapsed ? 'Rail' : 'Expanded'} · {expanded.length} expanded groups
      </p>
    </div>
  );
};
```


Expansion and collapse are independent of the active route. The app may persist them per user; Pathfinder does not read browser storage. Overflow fades follow actual scroll position. Use an app-owned mobile navigation surface when the persistent sidebar does not fit; the component does not guess viewport breakpoints or mutate routes. Chat conversation history remains a separately composed pattern. Read the [hierarchy rules](/docs/components/side-nav#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Side navigation [#side-navigation]

- **NAV-001:** Expanded 208px, rail 56px, pearl100 background, 12px inset, 24px section gaps. Header mark/wordmark and collapse control; optional Home/Chat SegmentedControl; footer account composition. Rows 28px, radius 6, horizontal inset 8, gap 12, icons 16.
- **NAV-002:** Label/13 pearl900; icon pearl800. Hover pearl200, selected pearl300, selected label1000 and icon blue700. The landing link and expansion chevron share one continuous hover/selected row surface. Weight never changes. The docs prose mentions selected 200, but the reviewed component 714:15 uses 300; the implementation follows the component. Count Label/12, optional unread dot; rail uses tooltip and accessible metadata.
- **NAV-003:** Stable globally distinct IDs, one active destination, real anchors, separate group chevrons. Routing, auth, persistence and fetching belong to the application. Collapse retains group/section state. Chat history is a separate composed pattern; do not embed an application’s routes or conversation API in SideNav.
- **NAV-004:** Scroll fades match CommendaNavbar: 48px from the Soft Pearl 100 surface (#FCFBF8) to transparent, appearing only at overflowing edges. The parent supplies available height. No global keyboard shortcut, cookie or workspace provider is installed by the component.


---

# Skeleton

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/skeleton
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=262-2

```tsx
import { SkeletonGroup, SkeletonText } from '@commenda/pathfinder/skeleton';
<SkeletonGroup label="Loading filings">
  <SkeletonText />
</SkeletonGroup>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { SkeletonGroup, SkeletonText } from '@commenda/pathfinder/skeleton';
<SkeletonGroup label="Loading filings">
  <SkeletonText />
</SkeletonGroup>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `shape` | `"circle" \| "text" \| "block"` | optional | text |
| `width` | `Property.Width<string \| number>` | optional | Match incoming content |
| `height` | `Property.Height<string \| number>` | optional | Match incoming content |
| `animate` | `boolean` | optional | true; reduced motion is static |
| `className` | `string` | optional | Additional classes for the component root. |

The application owns the 300 ms delay to avoid flashes. After about 10 seconds, offer meaningful progress or recovery; never fabricate a percentage. Render stable headers, filters and buttons immediately. Match the content layout and show 5–8 list rows. Group placeholders into one loading region; each shape is decorative.

## Examples [#examples]

### Shapes [#shapes]


```tsx
<SkeletonGroup label="Loading shapes example">
  <Skeleton />
  <Skeleton shape="circle" />
  <Skeleton shape="block" />
</SkeletonGroup>;
```


### List [#list]


```tsx
<SkeletonGroup label="Loading list example">
  {Array.from({ length: 5 }, (_, index) => (
    <SkeletonListRow key={index} />
  ))}
</SkeletonGroup>;
```


### Card [#card]


```tsx
<SkeletonGroup label="Loading card example">
  <SkeletonCard />
</SkeletonGroup>;
```


### Static [#static]


```tsx
<SkeletonGroup label="Loading static example" animate={false}>
  <SkeletonText />
</SkeletonGroup>;
```


Read the [design guidance](/docs/components/skeleton#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Skeleton — 262:2 [#skeleton--2622]

- **SKELETON-01:** Match the arriving layout, including row height, columns, padding and card frames. Skeleton content, never stable headers, filters, tabs or buttons. Do not skeleton menus, toasts or dialog shells; loading content inside a dialog may use it.
- **SKELETON-02:** One named loading region with decorative shapes. Show 5–8 list rows. Use one synchronized 1.5-second linear shimmer phase for shapes mounted together; reduced motion stays still.
- **SKELETON-03:** Applications delay presentation by 300 ms to avoid flashes. After about 10 seconds, provide progress or useful recovery. Never invent a known percentage; unknown task length uses indeterminate Progress. Single controls use their own loading indicator.
- **SKELETON-04:** Pearl 200; text height 10/radius 4, block radius 6, circle full. Text preset widths 100/92/64%, gap 8. List row: 32 px avatar, 10 px name, 8 px metadata, gap 8, trailing value width 48; padding 12/16 and gap 12. Card: white, 0.5 px border, radius 12, padding/gaps 16, header icon 24, two text lines, optional media height 120, two footer placeholders.


---

# Split button

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/split-button
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=51-2

```tsx
import { SplitButton } from '@commenda/pathfinder/split-button';

<SplitButton
  label="Export entities"
  onClick={onExport}
  menuConfig={{ groups: exportGroups, label: 'More export options' }}
/>;
```


## Usage [#usage]

```tsx
import { SplitButton } from '@commenda/pathfinder/split-button';

<SplitButton
  label="Export entities"
  onClick={onExport}
  loadingConfig={{ isLoading: isExporting }}
  menuConfig={{
    label: 'More export options',
    groups: [
      {
        id: 'formats',
        items: [
          {
            id: 'csv',
            type: 'action',
            label: 'Export CSV',
            onClick: onExportCsv,
          },
          {
            id: 'pdf',
            type: 'action',
            label: 'Export PDF',
            onClick: onExportPdf,
          },
        ],
      },
    ],
  }}
/>;
```

## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

The package currently lives in the Commenda workspace. External installation requires a published version or packed tarball. Import the precompiled stylesheet once; no application Tailwind setup is required.

## Examples [#examples]

### Secondary [#secondary]


```tsx
<SplitButton
  variant="secondary"
  label="Export entities"
  onClick={onExport}
  menuConfig={{ groups: exportGroups }}
/>;
```


### Loading the main action [#loading-the-main-action]


```tsx
<SplitButton
  label="Export entities"
  loadingConfig={{ isLoading: true }}
  menuConfig={{ groups: exportGroups }}
/>;
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `className` | `string` | optional | Additional classes for the component root. |
| `size` | `"sm" \| "md" \| "lg"` | optional |  |
| `loadingConfig` | `LoadingConfig` | optional |  |
| `leadingIcon` | `ReactNode` | optional |  |
| `disabledReason` | `string` | optional |  |
| `open` | `boolean` | conditional |  |
| `onOpenChange` | `((open: boolean) => void)` | conditional |  |
| `defaultOpen` | `boolean` | optional |  |
| `label` | `string` | required | Visible field label. Supply an accessible name when it is omitted. |
| `variant` | `"primary" \| "secondary"` | optional |  |
| `completionConfig` | `CompletionConfig` | optional |  |
| `menuConfig` | `SplitButtonMenuConfig` | required |  |

### loadingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | Yes |  |
| `label` | `string` | No |  |

### completionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isComplete` | `boolean` | Yes |  |
| `label` | `string` | Yes |  |
| `icon` | `ReactNode` | No |  |

### menuConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | `DropdownGroup[]` | Yes |  |
| `label` | `string` | No |  |
| `disabled` | `boolean` | No |  |
| `disabledReason` | `string` | No |  |
| `side` | `Side` | No |  |
| `align` | `Align` | No |  |
| `sideOffset` | `number` | No |  |
| `portalContainer` | `HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null` | No |  |

`SplitButtonMenuConfig`: required `groups: DropdownGroup[]`; optional `label`, `disabled`, `disabledReason`, `side`, `align`, `sideOffset`, `portalContainer`. Label defaults to `More options for ${label}`. Menu configuration disables only alternatives; component disabled disables both halves. There are no public Root/Trigger/Content parts or top-level menuLabel/menuDisabled props.

`SPLIT-ACTION-01`: Use one obvious default with two to five related alternatives. The main half acts immediately; the chevron opens the menu. Each is a separate keyboard stop with independent hover/focus. Loading blocks only the main action; disable the menu explicitly when alternatives conflict with ongoing work. Escape closes the menu and restores trigger focus. The menu trigger never submits a form.

No tertiary or destructive default. Destructive alternatives belong last in the menu and generally require confirmation. Without a default action use Dropdown with a normal Button. Do not put two SplitButtons beside each other in a row. Inner corners are square; outer corners follow Button radius. Recursive menus use the same model as Dropdown.

Import `@commenda/pathfinder/styles.css` once at the app root. Event handlers require a client component in Next.js App Router.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Action rules [#action-rules]

- `CONTROL-STATE-01` — Pathfinder: loadingConfig and completionConfig are explicit application signals. Loading wins over completion; disabled blocks activation. Ending loading never implies success. Applications own the 1.5-second completion reset recipe from Figma.

- `CONTROL-SIZE-01` — Figma: Button and SplitButton sm/md/lg have 28/32/36px visual heights; md default. IconButton adds xs 24. Button icons are 16 through md and 20 at lg; pass size to generated icons to select optical artwork. Link styles have text-sized geometry. Long content can increase minimum height for accessibility.

- `CONTROL-FOCUS-01` — Figma: show focus from keyboard, not pointer click. Button family uses a blue ring separated by a white gap. Open triggers retain hover styling. Disabled reason is a Pathfinder extension: retain action name, expose description, and allow focus without activation where the native wrapper supports it.

- `SPLIT-ACTION-01` — Figma: one obvious default and two to five related alternatives; no tertiary/destructive default. Each half reacts independently. Main-only loading; trigger-only open styling. No default means a normal dropdown trigger. Avoid two SplitButtons side by side. Square inner corners, 1px join, rounded outer corners.


---

# Stepper

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/stepper
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=676-2

```tsx
import { Stepper, type StepperItem } from '@commenda/pathfinder/stepper';

const filingSteps: StepperItem[] = [
  {
    id: 'compose',
    label: 'Compose',
    description: 'Write the title and message',
    state: 'done',
  },
  {
    id: 'audience',
    label: 'Audience',
    description: 'Who sees this alert',
    state: 'current',
  },
  {
    id: 'schedule',
    label: 'Schedule',
    description: 'When it goes live',
    state: 'upcoming',
  },
];

export const StepperDefault = () => (
  <Stepper label="Create alert" items={filingSteps} />
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/stepper`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required; ordered-list name |
| `items` | `readonly StepperItem[]` | required | Required; id, label, state, optional description |
| `orientation` | `"vertical" \| "horizontal"` | optional | horizontal |
| `navigationConfig` | `{ onStepChange: (id: string) => void; }` | optional | Optional; only done steps request navigation |
| `stateLabels` | `Partial<Record<"done" \| "disabled" \| "upcoming" \| "current", string>>` | optional | Localized Upcoming, Current step, Completed, Unavailable |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `className` | `string` | optional | Additional classes for the component root. |

### navigationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `onStepChange` | `(id: string) => void` | Yes |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Item IDs/values must be unique and stable.

## Usage rules [#usage-rules]

Each step explicitly declares `state: upcoming | current | done | disabled`. At most one is current; a finished flow can have none. The component does not duplicate that state with a separate current index.

Done steps become native buttons when navigationConfig is supplied. Upcoming and disabled steps do not navigate. The application owns validation, retained answers, Back/Continue/Submit actions, and focus after navigation. A failed field remains a field error; it does not create a red step marker. Keep later completed steps done when revisiting earlier answers unless those answers invalidate them.

Prefer three to six steps on a full page. Use the vertical layout when a narrow container cannot fit clear horizontal labels. The page owns sticky positioning. The Navigation example illustrates navigation only, not a production validation engine.

## Examples [#examples]

### Vertical [#vertical]


```tsx
import { Stepper, type StepperItem } from '@commenda/pathfinder/stepper';

const filingSteps: StepperItem[] = [
  {
    id: 'compose',
    label: 'Compose',
    description: 'Write the title and message',
    state: 'done',
  },
  {
    id: 'audience',
    label: 'Audience',
    description: 'Who sees this alert',
    state: 'current',
  },
  {
    id: 'schedule',
    label: 'Schedule',
    description: 'When it goes live',
    state: 'upcoming',
  },
];

export const StepperVertical = () => (
  <Stepper
    label="Create alert"
    orientation="vertical"
    items={[
      ...filingSteps,
      {
        id: 'review',
        label: 'Review',
        state: 'disabled',
        description: 'Available after scheduling',
      },
    ]}
  />
);
```


### Navigation [#navigation]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Stepper, type StepperItem } from '@commenda/pathfinder/stepper';

const filingSteps: StepperItem[] = [
  {
    id: 'compose',
    label: 'Compose',
    description: 'Write the title and message',
    state: 'done',
  },
  {
    id: 'audience',
    label: 'Audience',
    description: 'Who sees this alert',
    state: 'current',
  },
  {
    id: 'schedule',
    label: 'Schedule',
    description: 'When it goes live',
    state: 'upcoming',
  },
];

export const StepperNavigation = () => {
  const [current, setCurrent] = useState(0);
  const [completed, setCompleted] = useState<readonly string[]>([]);

  return (
    <div style={{ display: 'grid', gap: 24 }}>
      <Stepper
        label="Create alert"
        items={filingSteps.map((step, index) => ({
          ...step,
          state:
            index === current
              ? 'current'
              : completed.includes(step.id)
                ? 'done'
                : 'upcoming',
        }))}
        navigationConfig={{
          onStepChange: (id) => {
            setCurrent(filingSteps.findIndex((step) => step.id === id));
          },
        }}
      />
      <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 8 }}>
        <Button
          variant="secondary"
          disabled={current === 0}
          onClick={() => {
            setCurrent(Math.max(0, current - 1));
          }}
        >
          Back
        </Button>
        <Button
          disabled={current === filingSteps.length}
          onClick={() => {
            const step = filingSteps[current];
            if (current < filingSteps.length)
              setCompleted([...new Set([...completed, step.id])]);
            setCurrent(Math.min(filingSteps.length, current + 1));
          }}
        >
          {current < filingSteps.length - 1
            ? 'Continue'
            : current === filingSteps.length
              ? 'Published'
              : 'Publish'}
        </Button>
      </div>
    </div>
  );
};
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Stepper [#stepper]

Source: [676:104](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=676-104), items 676:61, behavior 676:35169, guidance 676:35190.

- `STEPPER-01` — Source/Pathfinder: explicit upcoming/current/done/disabled states, at most one current. Only done steps with navigationConfig become buttons; callbacks request navigation without changing caller-owned state. Current exposes aria-current=step.
- `STEPPER-02` — Source: current-step validation, saved answers, footer buttons, and focus belong to the application. Field errors never invent a red marker. Final primary action says Publish, Submit, or Create. Keep completed steps when revisiting unless the application invalidates them.
- `STEPPER-03` — Source: three to six steps on full pages. Short labels, optional descriptions. Parent owns sticky positioning and responsive choice of horizontal/vertical layout.
- `STEPPER-04` — Source: 20 markers, upcoming pearl-300/900, current blue-700/white, done green-700/check, disabled pearl-100/600. Horizontal text gap 8, connector at marker center with 12 side gaps. Vertical 240, padding 8, gap 12, row gap 2, radius 8. Weight never shifts; completion enters without bounce and never animates on initial mount.


---

# Suggested prompt group

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/suggested-prompt-group
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=1058-3

```tsx
import { SuggestedPromptGroup } from '@commenda/pathfinder/suggested-prompt-group';

<SuggestedPromptGroup
  items={prompts}
  onSelect={(prompt) => {
    setDraft(prompt);
    editorRef.current?.focus();
  }}
/>;
```


## Usage [#usage]

```tsx
import { SuggestedPromptGroup } from '@commenda/pathfinder/suggested-prompt-group';

<SuggestedPromptGroup
  items={[
    { id: 'filings', label: 'Which filings are due in the next 30 days?' },
    { id: 'gst', label: 'Reconcile my GST return' },
    { id: 'entities', label: 'Review entity details' },
  ]}
  onSelect={(prompt, item) => {
    setDraft(prompt);
    recordPromptSelection(item.id);
  }}
/>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `items` | `readonly SuggestedPromptItem[]` | required | Stable unique IDs, labels, optional prompt text and disabled state |
| `onSelect` | `((prompt: string, item: SuggestedPromptItem) => void)` | required | Text plus original item for analytics or host behavior |
| `label` | `string` | optional | Accessible group label; defaults to `Suggested prompts` |
| `disabled` | `boolean` | optional | Disables every prompt |
| `className` | `string` | optional | Host layout |

## Design rules [#design-rules]

- **PROMPT-GROUP-01:** Recommend three or four relevant prompts with an 8px wrapping gap. Never force a horizontally overflowing row.
- Empty input renders nothing. Existing item order is preserved; no selection, randomization, fetching, or sending happens internally.
- The group uses native button keyboard behavior, not radio or tab semantics. Each prompt remains independently reachable.

For AI Elements migration, map each existing Suggestion's text and click callback to a SuggestedPrompt item and `onSelect`. Keep request handling and analytics in the application.


---

# Suggested prompt

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/suggested-prompt
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=1058-3

```tsx
import { SuggestedPrompt } from '@commenda/pathfinder/suggested-prompt';

<SuggestedPrompt
  label="Which filings are due in the next 30 days?"
  onSelect={setDraft}
/>;
```


## Usage [#usage]

```tsx
import { SuggestedPrompt } from '@commenda/pathfinder/suggested-prompt';

<SuggestedPrompt
  label="Review upcoming filings"
  prompt="Review all filings due in the next 30 days"
  onSelect={setDraft}
/>;
```

`onSelect` receives `prompt`, or `label` when no separate prompt is provided. The application decides whether selection fills the Composer or sends a first message. The example inserts text and focuses the editor; it does not send without review.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required visible and accessible text |
| `prompt` | `string` | optional | Optional full text; defaults to label |
| `onSelect` | `((prompt: string) => void)` | required | Required selection callback |

## Design rules [#design-rules]

- **PROMPT-01:** Figma 1058:8: Copy13, one line, full radius, 12px horizontal/6px vertical inset, pearl200 fill and pearl300 hover/border. The hairline makes the exported frame 33px high around 32px content.
- **PROMPT-02:** Selection emits text; the library does not own requests or mutate a draft.
- **PROMPT-03:** Long labels truncate within their container while preserving the full accessible name and title. Prefer short, concrete tasks.

This uses native button semantics with its own prompt recipe; it is not a Button variant. Enter and Space activate it, and focus remains visible. For several starters use [Suggested prompt group](/docs/components/suggested-prompt-group).


---

# Switch

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/switch
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-4

```tsx
import { Switch } from '@commenda/pathfinder/switch';

<Switch label="Weekly summary" />;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once at the app root. The stylesheet is precompiled with Tailwind v4; your application does not need Tailwind or source scanning. Event handlers belong in a client component in Next.js App Router.

## Usage [#usage]

```tsx
import { Switch } from '@commenda/pathfinder/switch';

<Switch
  label="Weekly summary"
  description="Sent each Monday."
  checked={weeklySummary}
  onCheckedChange={onWeeklySummaryChange}
/>;
```

| Prop                   | Type                         | Default / behavior                                           |
| ---------------------- | ---------------------------- | ------------------------------------------------------------ |
| `label`                | `string`                     | Required stable setting name                                 |
| `hideLabel`            | `boolean`                    | `false`; accessible name retained                            |
| `description`          | `string`                     | Optional supporting explanation                              |
| `checked`              | `boolean`                    | Controlled state                                             |
| `defaultChecked`       | `boolean`                    | `false`; uncontrolled initial state                          |
| `onCheckedChange`      | `(checked: boolean) => void` | Next state; application owns persistence                     |
| `disabled`             | `boolean`                    | Disables interaction for the control or group.               |
| `readOnly`             | `boolean`                    | Keeps the current value visible while preventing changes.    |
| `required`             | `boolean`                    | Requires a value for native form validation.                 |
| `disabledReason`       | `string`                     | Visible, associated explanation while disabled               |
| `name`                 | `string`                     | Name used when the control submits its value with a form.    |
| `value`                | `string`                     | Value submitted when checked; defaults to 'on'.              |
| `uncheckedValue`       | `string`                     | Value submitted when unchecked; omitted when not configured. |
| `form`                 | `string`                     | ID of the form associated with the control.                  |
| `id`                   | `string`                     | ID of the underlying form input.                             |
| `inputRef`             | `Ref<HTMLInputElement>`      | Access to the underlying form input.                         |
| `className`            | `string`                     | Additional class names for the outer layout.                 |
| `ref`                  | `Ref<HTMLElement>`           | Access to the interactive root element.                      |
| Native events and ARIA | Base UI root props           | Typed passthrough                                            |

A switch applies immediately. Keep its label the same in both states, such as “Weekly summary”, rather than “Turn on weekly summary”. On a failed asynchronous save, the application reverts the controlled state and explains the failure; this component does not invent persistence or loading/completion states. For form-save behavior use Checkbox, and for non-boolean choices use RadioGroup or SegmentedControl.

Track 36×20px, thumb 16px inset 2px, control elevation and 200ms ease-out movement. Honor reduced motion and RTL; coarse-pointer layouts provide at least a 44px row target without enlarging the visual control.

## Examples [#examples]

### Off and on [#off-and-on]


```tsx
<>
  <Switch label="Weekly summary" />
  <Switch label="Filing reminders" defaultChecked />
</>;
```


### Description [#description]


```tsx
<Switch label="Weekly summary" description="Sent each Monday." />;
```


### Disabled states [#disabled-states]


```tsx
<>
  <Switch label="Weekly summary" disabled />
  <Switch
    label="Filing reminders"
    defaultChecked
    disabled
    disabledReason="Administrator access required"
  />
</>;
```


Read the [Figma choice-control rules](/docs/components/switch#design-rules) for design guidance, source discrepancies and accessibility requirements.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Switch [#switch]

Source: [199:4](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=199-4), variants 200:5083, anatomy 207:148, guidance 207:184.

- **SWITCH-01** — Apply immediately with no separate Save action. Use Checkbox for changes saved later. Never use a switch to choose between two non-boolean options.
- **SWITCH-02** — The label names the setting and remains unchanged between states. Show results immediately; if persistence fails, the application reverts the controlled state and explains why. No invented loading/completion status is part of this API.
- **SWITCH-03** — Track 36×20px, radius full. Thumb 16px with 2px inset and Elevation/control. Off soft-pearl-400, on blue-700; hover soft-pearl-500/blue-800. Move the thumb 200ms ease-out; turn movement off for reduced motion and reverse travel in RTL. Label starts 8px from track, with 2px top alignment.
- **SWITCH-04** — Disabled off uses soft-pearl-100 track with soft-pearl-300 edge; disabled on uses soft-pearl-300 track. Thumb uses soft-pearl-200 without shadow. Keep the label readable with soft-pearl-600.

### Implementation decisions and source differences [#implementation-decisions-and-source-differences]

The complete prop tables are on [Checkbox](/docs/components/checkbox), [RadioGroup](/docs/components/radio-group) and [Switch](/docs/components/switch). Source rule IDs are also kept in the component implementation comments and exported through `llms.txt`, `llms-full.txt` and the Markdown routes.

- **CHOICE-01** — The sheets describe 8px list gaps but some documentation frames place rows 32px apart. Use the documented 8px component-list gap; documentation specimen whitespace is not a new size token.

- **CHOICE-02** — Built-in text is plain, wrapping content. Do not place links, buttons or nested interactive controls inside labels or cards. Disabled reasons are visible descriptions, not tooltip-only explanations on controls removed from keyboard navigation.

- **CHOICE-03** — Visual control size is not the hit target. Coarse-pointer rows provide at least 44px height, while preserving 16px marks and the 36×20px switch track. Cards already exceed this height.

- **CHOICE-04** — Hover/focus are real browser states, not public cosmetic props. Retain native `name`, `value`, `form`, `required`, `readOnly`, disabled semantics and input refs. `hideLabel` preserves the required accessible label.

- **CHOICE-05** — Use Pathfinder's existing Check/Minus optical artwork at 12px. Boxes, circles, tracks and thumbs are interactive primitive geometry, styled with the Figma tokens; they are not flattened screenshots. This keeps focus, RTL and switch movement functional.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

| Reference                                                                                         | Coverage                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Editing 442:767](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=442-767) | Account mapping demonstrates select, numeric validation, outline toggle, failed-save recovery and Add line. The companion example composes date, Switch and attachment selection. |


---

# Table

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/table
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=428-2

```tsx
import { Table } from '@commenda/pathfinder/table';

export const TableDefault = () => (
  <Table
    label="Recent invoices"
    rows={[
      { id: 'INV-001', customer: 'Meridian GmbH', amount: 2400 },
      { id: 'INV-002', customer: 'Meridian US Inc.', amount: 1800 },
      { id: 'INV-003', customer: 'Meridian UK Ltd.', amount: 950 },
    ]}
    rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
    columns={[
      { id: 'invoice', header: 'Invoice', value: (row) => row.id },
      {
        id: 'customer',
        header: 'Customer',
        width: 240,
        value: (row) => row.customer,
      },
      {
        id: 'amount',
        header: 'Amount (USD)',
        align: 'end',
        value: (row) => row.amount,
      },
    ]}
  />
);
```


Use Table for records people find, open and act on. Start with `rows`, typed `columns`, and stable row identities, then add the features your screen needs. Use [DataGrid](/docs/components/data-grid) for financial matrices with grouped headers and keyboard cell navigation.

## Headers and alignment [#headers-and-alignment]


```tsx
import { Table, TableNumberCell } from '@commenda/pathfinder/table';

const records = [
  {
    id: 'INV-001',
    customer: 'Meridian GmbH',
    entity: 'Germany',
    owner: 'Lucas Moreau',
    status: 'Paid',
    amount: 4800,
  },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    entity: 'United States',
    owner: 'Priya Shah',
    status: 'Open',
    amount: 2150,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    entity: 'United Kingdom',
    owner: 'Aisha Khan',
    status: 'Open',
    amount: 3200,
  },
];

export const TableLayoutHeaders = () => (
  <Table
    label="Header alignment"
    rows={records}
    rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
    selectionConfig={{}}
    sortingConfig={{ defaultValue: { columnId: 'amount', direction: 'asc' } }}
    columns={[
      { id: 'id', header: 'Invoice', value: (row) => row.id, sortable: true },
      {
        id: 'status',
        header: 'Status',
        align: 'center',
        value: (row) => row.status,
        sortable: true,
      },
      {
        id: 'amount',
        header: 'Amount',
        description: 'Invoice total in USD, including tax.',
        align: 'end',
        value: (row) => row.amount,
        sortable: true,
        cell: (row) => <TableNumberCell value={row.amount} unit="USD" />,
      },
    ]}
  />
);
```


Headers are 36px high with 12px medium labels and 12px icons. Hover or focus an unsorted header to reveal the neutral sort indicator; the active column keeps its direction visible. Click to cycle sorting. End-aligned numeric columns place sorting before the label. Supply `description` for a separate, keyboard-accessible information tooltip. Selection headers use the same horizontal inset as row checkboxes.

## Usage [#usage]

```tsx
'use client';

import { Table } from '@commenda/pathfinder/table';

const invoices = [
  { id: 'inv-001', number: 'INV-001', customer: 'Meridian UK Ltd' },
  { id: 'inv-002', number: 'INV-002', customer: 'Meridian US Inc.' },
];

export default function InvoicesTable() {
  return (
    <Table
      label="Invoices"
      rows={invoices}
      rowConfig={{ getId: (invoice) => invoice.id }}
      columns={[
        { id: 'number', header: 'Invoice', value: (invoice) => invoice.number },
        {
          id: 'customer',
          header: 'Customer',
          value: (invoice) => invoice.customer,
        },
      ]}
    />
  );
}
```

Import `@commenda/pathfinder/styles.css` once in your app layout. Pathfinder ships its own compiled styles. Open **Code** on any example for the complete, formatted implementation; the snippet comes from the same source as its preview.

Columns define a stable `id`, a visible `header`, and a `value(row)` accessor. Add `cell(row)` when rendering richer content. Keep the accessor when sorting or searching should use the underlying value rather than its formatted label. `rowConfig.getId` must return a stable record ID, not an array index.

## Sorting [#sorting]


```tsx
import { useState } from 'react';

import {
  Table,
  TableNumberCell,
  type TableSort,
} from '@commenda/pathfinder/table';

const invoices = [
  { id: 'INV-001', customer: 'Meridian GmbH', status: 'Paid', amount: 2400 },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    status: 'Pending',
    amount: 1800,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    status: 'Overdue',
    amount: 950,
  },
  {
    id: 'INV-004',
    customer: 'Meridian Singapore',
    status: 'Pending',
    amount: 3200,
  },
];

export const TableInteractionsDefault = () => {
  const [sort, setSort] = useState<TableSort | null>({
    columnId: 'amount',
    direction: 'desc',
  });

  return (
    <div className="pf:w-full pf:space-y-md">
      <Table
        label="Sortable invoices"
        rows={invoices}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
        columns={[
          {
            id: 'invoice',
            header: 'Invoice',
            value: (row) => row.id,
            sortable: true,
          },
          {
            id: 'customer',
            header: 'Customer',
            width: 240,
            value: (row) => row.customer,
            sortable: true,
          },
          {
            id: 'amount',
            header: 'Amount',
            align: 'end',
            value: (row) => row.amount,
            sortable: true,
            cell: (row) => (
              <TableNumberCell
                value={row.amount}
                unit="USD"
                format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
              />
            ),
          },
        ]}
        sortingConfig={{ value: sort, onValueChange: setSort }}
      />
      <p role="status" className="pf:text-label-12 pf:text-soft-pearl-800">
        {sort
          ? `Sorted by ${sort.columnId}, ${sort.direction === 'asc' ? 'ascending' : 'descending'}`
          : 'Original order'}
      </p>
    </div>
  );
};
```


Click Amount to cycle descending, unsorted and ascending order. The initial sort is controlled by `sortingConfig`; the status below the example reflects the current value. Numeric accessors sort numerically even when the cell formats money. Local sorting runs before pagination.

## Search and filters [#search-and-filters]


```tsx
import { useState } from 'react';

import { Table, TableCell } from '@commenda/pathfinder/table';

const invoices = [
  { id: 'INV-001', customer: 'Meridian GmbH', status: 'Paid', amount: 2400 },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    status: 'Pending',
    amount: 1800,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    status: 'Overdue',
    amount: 950,
  },
  {
    id: 'INV-004',
    customer: 'Meridian Singapore',
    status: 'Pending',
    amount: 3200,
  },
];

export const TableInteractionsFiltering = () => {
  const [query, setQuery] = useState('');
  const [filters, setFilters] = useState<Record<string, readonly string[]>>({});

  return (
    <Table
      label="Searchable invoices"
      rows={invoices}
      rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
      columns={[
        { id: 'invoice', header: 'Invoice', value: (row) => row.id },
        {
          id: 'customer',
          header: 'Customer',
          width: 240,
          value: (row) => row.customer,
        },
        {
          id: 'status',
          header: 'Status',
          align: 'end',
          value: (row) => row.status,
          cell: (row) => (
            <TableCell
              type="badge"
              items={[
                {
                  label: row.status,
                  tone:
                    row.status === 'Paid'
                      ? 'success'
                      : row.status === 'Overdue'
                        ? 'error'
                        : 'neutral',
                },
              ]}
            />
          ),
        },
      ]}
      searchConfig={{
        value: query,
        onValueChange: setQuery,
        getText: (row) => `${row.id} ${row.customer}`,
      }}
      filterConfig={{
        value: filters,
        onValueChange: setFilters,
        filters: [
          {
            id: 'status',
            label: 'Status',
            options: ['Paid', 'Pending', 'Overdue'].map((value) => ({
              value,
              label: value,
            })),
            matches: (row, values) => values.includes(row.status),
          },
        ],
      }}
    />
  );
};
```


Open search and enter **Meridian UK**, or choose **Pending** from Status. Search and filters combine. Search opens in place; tools stay together and excess filter buttons move into +N. A query with no matches offers Clear filters. This example supplies `getText` explicitly so invoice numbers and customer names are searchable.

For a local collection, `matches(row, values)` defines filter membership. In remote mode the server applies it; use controlled search/filter state as request inputs. Reset the page when an externally controlled filter changes.

## Single-choice filters [#single-choice-filters]


```tsx
import { useState } from 'react';

import { Table } from '@commenda/pathfinder/table';

export const TableFiltersSingle = () => {
  const [value, setValue] = useState<Record<string, readonly string[]>>({});

  return (
    <Table
      label="Single status filter"
      rows={[
        { id: 'INV-001', status: 'Paid' },
        { id: 'INV-002', status: 'Open' },
        { id: 'INV-003', status: 'Overdue' },
      ]}
      columns={[
        { id: 'id', header: 'Invoice', value: (row) => row.id },
        { id: 'status', header: 'Status', value: (row) => row.status },
      ]}
      rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
      filterConfig={{
        value,
        onValueChange: setValue,
        filters: [
          {
            id: 'status',
            label: 'Status',
            type: 'single',
            options: ['Paid', 'Open', 'Overdue'].map((label) => ({
              value: label,
              label,
            })),
            getValue: (row) => row.status,
          },
        ],
      }}
    />
  );
};
```


Choose a status. Single choice replaces the previous selection, shows a checkmark and closes its menu. Clear resets that field. The selected value becomes an editable chip below the toolbar.

## Complex filters [#complex-filters]


```tsx
import { useState } from 'react';

import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { Building07Icon } from '@commenda/pathfinder/icons/Building07Icon';
import { CalendarIcon } from '@commenda/pathfinder/icons/CalendarIcon';
import { RefreshCw05Icon } from '@commenda/pathfinder/icons/RefreshCw05Icon';
import {
  Table,
  TableCell,
  type TableFilterOperator,
  TableNumberCell,
} from '@commenda/pathfinder/table';

export const TableFiltersDefault = () => {
  const [value, setValue] = useState<Record<string, readonly string[]>>({
    status: ['Overdue', 'Due soon'],
  });
  const [operators, setOperators] = useState<
    Readonly<Record<string, TableFilterOperator>>
  >({});
  const [notice, setNotice] = useState('');
  const rows = [
    {
      id: '1',
      filing: 'VAT return Q3',
      entity: 'DE',
      status: 'Filed',
      due: '2026-10-07',
      amount: 0,
      owner: 'Lucas Moreau',
    },
    {
      id: '2',
      filing: 'Trade tax return',
      entity: 'DE',
      status: 'In review',
      due: '2026-10-30',
      amount: 180,
      owner: 'Priya Shah',
    },
    {
      id: '3',
      filing: 'Annual accounts',
      entity: 'DE',
      status: 'Due soon',
      due: '2026-11-14',
      amount: 95,
      owner: 'Aisha Khan',
    },
    {
      id: '4',
      filing: 'Delaware annual report',
      entity: 'US',
      status: 'Overdue',
      due: '2026-10-01',
      amount: 450,
      owner: 'Jun Tan',
    },
    {
      id: '5',
      filing: 'BOI report update',
      entity: 'US',
      status: 'Due soon',
      due: '2026-11-14',
      amount: 0,
      owner: 'Priya Shah',
    },
  ];

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <Table
        label="Filtered filings"
        rows={rows}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.filing }}
        searchConfig={{
          getText: (row) => `${row.filing} ${row.owner}`,
          placeholder: 'Search filings',
        }}
        columns={[
          {
            id: 'filing',
            header: 'Filing',
            width: 240,
            value: (row) => row.filing,
          },
          {
            id: 'entity',
            header: 'Entity',
            width: 180,
            cell: (row) => (
              <TableCell
                type="entity"
                label={row.entity === 'DE' ? 'Acme GmbH' : 'Acme Inc.'}
                icon={
                  row.entity === 'DE' ? (
                    <DEFlag size={16} />
                  ) : (
                    <USFlag size={16} />
                  )
                }
              />
            ),
          },
          {
            id: 'status',
            header: 'Status',
            width: 130,
            cell: (row) => (
              <TableCell
                type="badge"
                items={[
                  {
                    label: row.status,
                    tone:
                      row.status === 'Overdue'
                        ? 'error'
                        : row.status === 'Filed'
                          ? 'success'
                          : 'warning',
                  },
                ]}
              />
            ),
          },
          { id: 'due', header: 'Due', width: 140, value: (row) => row.due },
          {
            id: 'amount',
            header: 'Amount',
            width: 140,
            align: 'end',
            cell: (row) => <TableNumberCell value={row.amount} unit="USD" />,
          },
        ]}
        filterConfig={{
          value,
          onValueChange: setValue,
          operators: { value: operators, onValueChange: setOperators },
          filters: [
            {
              id: 'status',
              label: 'Status',
              icon: <RefreshCw05Icon size={16} />,
              options: ['Overdue', 'Due soon', 'In review', 'Filed'].map(
                (label) => ({ value: label, label })
              ),
              getValue: (row) => row.status,
            },
            {
              id: 'entity',
              label: 'Entity',
              icon: <Building07Icon size={16} />,
              searchable: true,
              options: [
                {
                  value: 'DE',
                  label: 'Acme GmbH',
                  leading: <DEFlag size={16} />,
                },
                {
                  value: 'US',
                  label: 'Acme Inc.',
                  leading: <USFlag size={16} />,
                },
              ],
              getValue: (row) => row.entity,
            },
            {
              id: 'due',
              label: 'Due date',
              type: 'date',
              icon: <CalendarIcon size={16} />,
              getValue: (row) => row.due,
              presets: [
                {
                  id: 'october',
                  label: 'October 2026',
                  start: '2026-10-01',
                  end: '2026-10-31',
                },
                {
                  id: 'quarter',
                  label: 'Q4 2026',
                  start: '2026-10-01',
                  end: '2026-12-31',
                },
              ],
            },
            {
              id: 'owner',
              label: 'Assignee',
              type: 'single',
              initiallyVisible: false,
              options: [
                'Lucas Moreau',
                'Priya Shah',
                'Aisha Khan',
                'Jun Tan',
              ].map((label) => ({ value: label, label })),
              getValue: (row) => row.owner,
            },
            {
              id: 'amount',
              label: 'Amount',
              type: 'number',
              initiallyVisible: false,
              getValue: (row) => row.amount,
            },
          ],
        }}
        toolbarConfig={{
          onExport: () => {
            setNotice('Export requested for the current filter state');
          },
        }}
      />
      <p
        role="status"
        className="pf:m-0 pf:text-copy-12 pf:text-soft-pearl-800"
      >
        {notice ||
          'Fields combine with AND. Selected values within a field combine with OR. Date presets use a fixed demonstration period.'}
      </p>
    </div>
  );
};
```


This implements **Option A** from Figma: one compound chip per active filter, with **field · operator · value · remove**. Change Status from “is either of” to “is not”, search Entity options, or open Due date to choose a preset or calendar range. Use More filters to add Assignee or Amount; the field editor opens immediately. Resize the container to reveal the +N filter overflow menu.

The toolbar keeps quiet field buttons. Applied chips wrap below it. Multiple choices stay checked while searching, selected options appear first, and country flags lead entity names. Each menu clears only its own field; Clear filters resets the whole filter map. Date changes apply once a complete range exists. Numeric conditions apply after validation.

Fields combine with **AND**; multiple selected choices within one field combine with **OR**. “is not” negates membership. The app controls the value map and can control operators independently. For remote tables, serialize both into your API request and query-selection key; the table never re-filters a server page. Missing dates/numbers do not match a numeric/date condition. Arbitrarily nested AND/OR expressions are not part of this field-filter API.

## Pagination [#pagination]


```tsx
import { useState } from 'react';

import { Table } from '@commenda/pathfinder/table';

const invoices = Array.from({ length: 12 }, (_, index) => ({
  id: `INV-${String(index + 1).padStart(3, '0')}`,
  customer: ['Meridian GmbH', 'Meridian US Inc.', 'Meridian UK Ltd.'][
    index % 3
  ],
  amount: (index + 1) * 250,
}));

export const TableDataDefault = () => {
  const [page, setPage] = useState({ page: 1, pageSize: 5 });

  return (
    <Table
      label="Paginated invoices"
      rows={invoices}
      rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
      columns={[
        { id: 'invoice', header: 'Invoice', value: (row) => row.id },
        {
          id: 'customer',
          header: 'Customer',
          width: 240,
          value: (row) => row.customer,
        },
        {
          id: 'amount',
          header: 'Amount (USD)',
          align: 'end',
          value: (row) => row.amount,
        },
      ]}
      paginationConfig={{
        value: page,
        onValueChange: setPage,
        pageSizes: [5, 10],
      }}
    />
  );
};
```


Move through twelve records in pages of five, then change Rows per page. The example controls `{ page, pageSize }` and offers 5/10 for demonstration. Defaults are page **1**, 25 rows, and 25/50/100 choices. Filtering and sorting apply to the full local collection before it is sliced.

## Column visibility [#column-visibility]


```tsx
import { useState } from 'react';

import { Table } from '@commenda/pathfinder/table';

const invoices = Array.from({ length: 12 }, (_, index) => ({
  id: `INV-${String(index + 1).padStart(3, '0')}`,
  customer: ['Meridian GmbH', 'Meridian US Inc.', 'Meridian UK Ltd.'][
    index % 3
  ],
  amount: (index + 1) * 250,
}));

export const TableDataVisibility = () => {
  const [hidden, setHidden] = useState<readonly string[]>(['amount']);

  return (
    <div className="pf:w-full pf:space-y-md">
      <Table
        label="Column preferences"
        rows={invoices.slice(0, 3)}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
        columns={[
          {
            id: 'invoice',
            header: 'Invoice',
            hideable: false,
            value: (row) => row.id,
          },
          {
            id: 'customer',
            header: 'Customer',
            width: 240,
            value: (row) => row.customer,
          },
          {
            id: 'amount',
            header: 'Amount (USD)',
            align: 'end',
            value: (row) => row.amount,
          },
        ]}
        viewConfig={{
          hiddenColumns: { value: hidden, onValueChange: setHidden },
        }}
      />
      <p role="status" className="pf:text-label-12 pf:text-soft-pearl-800">
        {hidden.length
          ? `Hidden columns: ${hidden.join(', ')}`
          : 'All columns visible'}
      </p>
    </div>
  );
};
```


Open Columns and enable Amount. Invoice cannot be hidden because it identifies the record. The controlled `viewConfig.hiddenColumns` array can be stored in application preferences; column IDs should survive label changes and translations. Density and visibility can be controlled independently.

## Column pinning [#column-pinning]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Table, TableCell, TableNumberCell } from '@commenda/pathfinder/table';

const records = [
  {
    id: 'INV-001',
    customer: 'Meridian GmbH',
    entity: 'Germany',
    owner: 'Lucas Moreau',
    status: 'Paid',
    amount: 4800,
  },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    entity: 'United States',
    owner: 'Priya Shah',
    status: 'Open',
    amount: 2150,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    entity: 'United Kingdom',
    owner: 'Aisha Khan',
    status: 'Open',
    amount: 3200,
  },
];

export const TableLayoutDefault = () => {
  const [pins, setPins] = useState<
    Readonly<Partial<Record<string, 'start' | 'end' | null>>>
  >({ id: 'start', amount: 'end' });

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <Table
        label="Pinned invoices"
        rows={records}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
        selectionConfig={{}}
        viewConfig={{ columnPinning: { value: pins, onValueChange: setPins } }}
        columns={[
          {
            id: 'id',
            header: 'Invoice',
            width: 140,
            hideable: false,
            value: (row) => row.id,
          },
          {
            id: 'customer',
            header: 'Customer',
            width: 280,
            cell: (row) => <TableCell value={row.customer} />,
          },
          {
            id: 'entity',
            header: 'Entity',
            width: 180,
            value: (row) => row.entity,
          },
          {
            id: 'owner',
            header: 'Owner',
            width: 180,
            value: (row) => row.owner,
          },
          {
            id: 'status',
            header: 'Status',
            width: 120,
            value: (row) => row.status,
          },
          {
            id: 'amount',
            header: 'Amount',
            width: 160,
            align: 'end',
            cell: (row) => <TableNumberCell value={row.amount} unit="USD" />,
          },
        ]}
      />
      <p
        role="status"
        className="pf:m-0 pf:text-copy-12 pf:text-soft-pearl-800"
      >
        Scroll horizontally. Invoice starts pinned; Amount ends pinned. Change
        pins from Columns.
      </p>
      <Button
        size="sm"
        variant="secondary"
        onClick={() => {
          setPins({
            id: null,
            amount: null,
            customer: null,
            entity: null,
            owner: null,
            status: null,
          });
        }}
      >
        Unpin all columns
      </Button>
    </div>
  );
};
```


Scroll horizontally: Invoice stays at the logical start and Amount at the end. Open Columns, then a column's pin control to move it or unpin it. Selection and action cells remain at their edges alongside pinned data. Hidden columns do not leave gaps. Pinning uses logical edges in RTL and releases in a narrow container when the pinned regions would obscure readable data.

Use `column.pin` for a fixed default or `viewConfig.columnPinning` for interactive preferences. Its value is a map of column IDs to `'start'`, `'end'`, or `null` (explicitly unpinned). `pinnable: false` locks a column's configured position.

## Drag column widths [#drag-column-widths]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Table, TableCell, TableNumberCell } from '@commenda/pathfinder/table';

const records = [
  {
    id: 'INV-001',
    customer: 'Meridian GmbH',
    entity: 'Germany',
    owner: 'Lucas Moreau',
    status: 'Paid',
    amount: 4800,
  },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    entity: 'United States',
    owner: 'Priya Shah',
    status: 'Open',
    amount: 2150,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    entity: 'United Kingdom',
    owner: 'Aisha Khan',
    status: 'Open',
    amount: 3200,
  },
];

export const TableLayoutResizing = () => {
  const [widths, setWidths] = useState<
    Readonly<Partial<Record<string, number>>>
  >({});

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <Table
        label="Resizable invoices"
        rows={records}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
        viewConfig={{
          columnWidths: { value: widths, onValueChange: setWidths },
          columnPinning: { defaultValue: { id: 'start' } },
        }}
        columns={[
          {
            id: 'id',
            header: 'Invoice',
            width: 140,
            minWidth: 100,
            maxWidth: 240,
            value: (row) => row.id,
          },
          {
            id: 'customer',
            header: 'Customer',
            width: 280,
            minWidth: 160,
            maxWidth: 440,
            cell: (row) => <TableCell value={row.customer} />,
          },
          {
            id: 'owner',
            header: 'Owner',
            width: 200,
            minWidth: 160,
            maxWidth: 320,
            value: (row) => row.owner,
          },
          {
            id: 'amount',
            header: 'Amount',
            width: 160,
            minWidth: 140,
            maxWidth: 240,
            align: 'end',
            cell: (row) => <TableNumberCell value={row.amount} unit="USD" />,
          },
        ]}
      />
      <p
        role="status"
        className="pf:m-0 pf:text-copy-12 pf:text-soft-pearl-800"
      >
        Customer width: {widths.customer ?? 280}px. Drag a header edge, or focus
        it and use Left/Right (10px), Shift (50px), Home/End.
      </p>
      <Button
        size="sm"
        variant="secondary"
        onClick={() => {
          setWidths({});
        }}
      >
        Reset column widths
      </Button>
    </div>
  );
};
```


Drag a header's trailing edge to increase or decrease its width. Focus the handle to use Left/Right in 10px steps, Shift for 50px, or Home/End for the bounds. Escape during a drag restores its starting width. Resize does not trigger sorting; pinned offsets follow the updated widths.

Enable handles with `viewConfig.columnWidths`. Set each column's `width`, `minWidth`, `maxWidth`, and optionally `resizable: false`. The default bounds are 80–800px; choose bounds appropriate to the content, especially money and dates. Controlled width and pin maps can be saved in application preferences. Explicit layout widths preserve accurate drag distances and pin offsets; a table can leave unused space when its configured total is narrower than its container.

## Row selection [#row-selection]


```tsx
import { useState } from 'react';

import { Table, type TableSelection } from '@commenda/pathfinder/table';

const invoices = [
  { id: 'INV-001', customer: 'Meridian GmbH', status: 'Paid', amount: 2400 },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    status: 'Pending',
    amount: 1800,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    status: 'Overdue',
    amount: 950,
  },
  {
    id: 'INV-004',
    customer: 'Meridian Singapore',
    status: 'Pending',
    amount: 3200,
  },
];

export const TableInteractionsSelection = () => {
  const [selection, setSelection] = useState<TableSelection>({
    kind: 'ids',
    ids: [],
  });
  const [notice, setNotice] = useState(
    'Select unpaid invoices to request a reminder.'
  );

  return (
    <div className="pf:w-full pf:space-y-md">
      <Table
        label="Invoice selection"
        rows={invoices}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
        columns={[
          { id: 'invoice', header: 'Invoice', value: (row) => row.id },
          {
            id: 'customer',
            header: 'Customer',
            width: 240,
            value: (row) => row.customer,
          },
          { id: 'status', header: 'Status', value: (row) => row.status },
        ]}
        paginationConfig={{
          defaultValue: { page: 1, pageSize: 2 },
          pageSizes: [2, 4],
        }}
        selectionConfig={{
          value: selection,
          onValueChange: setSelection,
          canSelect: (row) => row.status !== 'Paid',
          allMatching: { queryKey: 'demo-unpaid-invoices', total: 3 },
          actions: [
            {
              id: 'remind',
              label: 'Request reminder',
              onAction: () => {
                const count =
                  selection.kind === 'all'
                    ? 3 - selection.excludedIds.length
                    : selection.ids.length;
                setNotice(
                  `Reminder requested for ${String(count)} invoices. No messages were sent by this demo.`
                );
              },
            },
          ],
        }}
      />
      <p role="status" className="pf:text-label-12 pf:text-soft-pearl-800">
        {notice}
      </p>
    </div>
  );
};
```


Select an unpaid invoice, move to the next page, or choose **Select all 3** in the bulk bar. Paid invoices are ineligible. Selection persists by stable ID. Request reminder updates the status message only; this demo does not send messages.

`TableSelection` is `{ kind: 'ids', ids }` or `{ kind: 'all', queryKey, excludedIds }`. The header checkbox selects the current eligible page. `allMatching` explicitly enables the entire eligible query, including unloaded pages. Pass a new query key when filter membership or authorization scope changes. The server must interpret that query/exclusion model and recheck permissions.

## Row actions and copying [#row-actions-and-copying]


```tsx
import { useState } from 'react';

import { Table, TableCell } from '@commenda/pathfinder/table';

const invoices = [
  { id: 'INV-001', customer: 'Meridian GmbH', status: 'Paid', amount: 2400 },
  {
    id: 'INV-002',
    customer: 'Meridian US Inc.',
    status: 'Pending',
    amount: 1800,
  },
  {
    id: 'INV-003',
    customer: 'Meridian UK Ltd.',
    status: 'Overdue',
    amount: 950,
  },
  {
    id: 'INV-004',
    customer: 'Meridian Singapore',
    status: 'Pending',
    amount: 3200,
  },
];

export const TableInteractionsActions = () => {
  const [notice, setNotice] = useState('Open a row or use its menu.');

  return (
    <div className="pf:w-full pf:space-y-md">
      <Table
        label="Invoice actions"
        rows={invoices}
        rowConfig={{
          getId: (row) => row.id,
          getLabel: (row) => row.id,
          onActivate: (row) => {
            setNotice(`Opening ${row.id}`);
          },
          menu: (row) => ({
            groups: [
              {
                id: 'record',
                items: [
                  {
                    id: 'view',
                    type: 'action',
                    label: 'View invoice',
                    onClick: () => {
                      setNotice(`Opening ${row.id}`);
                    },
                  },
                  {
                    id: 'download',
                    type: 'action',
                    label: 'Download receipt',
                    disabled: row.status !== 'Paid',
                    disabledReason: 'A receipt is available after payment.',
                    onClick: () => {
                      setNotice(`Receipt download requested for ${row.id}`);
                    },
                  },
                ],
              },
            ],
          }),
        }}
        columns={[
          {
            id: 'invoice',
            header: 'Invoice',
            value: (row) => row.id,
            cell: (row) => (
              <TableCell
                type="copy"
                value={row.id}
                copyLabel={`Copy invoice number ${row.id}`}
                onCopy={() => {
                  void navigator.clipboard.writeText(row.id).then(
                    () => {
                      setNotice(`${row.id} copied`);
                    },
                    () => {
                      setNotice(
                        'Clipboard unavailable. Select the invoice number to copy it.'
                      );
                    }
                  );
                }}
              />
            ),
          },
          {
            id: 'customer',
            header: 'Customer',
            width: 240,
            value: (row) => row.customer,
          },
          { id: 'status', header: 'Status', value: (row) => row.status },
        ]}
      />
      <p role="status" className="pf:text-label-12 pf:text-soft-pearl-800">
        {notice}
      </p>
    </div>
  );
};
```


Click a record to open it, use its overflow menu, or hover/focus the invoice number to copy it. Those controls do not also activate the row. Download receipt is unavailable before payment. The example reports requested actions locally; real navigation/downloads belong to the application.

Use specific action names and at most a primary icon, secondary icon and overflow per row. Keep whole-record editing in a Sheet; reserve inline editing for frequently changed fields.

## Custom cells [#custom-cells]


```tsx
import { useState } from 'react';

import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { EyeIcon } from '@commenda/pathfinder/icons/EyeIcon';
import {
  Table,
  TableCell,
  TableRowActions,
  type TableSelection,
} from '@commenda/pathfinder/table';

const filingRows = [
  {
    id: '1',
    filing: 'Delaware annual report',
    description: 'Annual compliance · 2026',
    entity: 'Meridian US Inc.',
    country: 'US',
    assignee: 'Priya Shah',
    status: 'In progress',
    due: '2026-10-15',
  },
  {
    id: '2',
    filing: 'VAT return Q3',
    description: 'Quarterly tax return',
    entity: 'Meridian GmbH',
    country: 'DE',
    assignee: 'Lucas Moreau',
    status: 'To do',
    due: '2026-10-20',
  },
  {
    id: '3',
    filing: 'Corporate income tax',
    description: 'Financial year 2025',
    entity: 'Meridian US Inc.',
    country: 'US',
    assignee: 'Aisha Khan',
    status: 'Done',
    due: '2026-10-25',
  },
  {
    id: '4',
    filing: 'Financial statements',
    description: 'Annual financial reporting',
    entity: 'Meridian GmbH',
    country: 'DE',
    assignee: 'Jun Tan',
    status: 'To do',
    due: '2026-10-30',
  },
];

export const TableOverview = () => {
  const [filters, setFilters] = useState<Record<string, readonly string[]>>({});
  const [selection, setSelection] = useState<TableSelection>({
    kind: 'ids',
    ids: [],
  });
  const [notice, setNotice] = useState('');

  return (
    <div className="pf:w-full pf:min-w-0">
      <Table
        label="Filings"
        rows={filingRows}
        rowConfig={{
          getId: (row) => row.id,
          getLabel: (row) => row.filing,
          onActivate: (row) => {
            setNotice(`Opened ${row.filing}`);
          },
        }}
        columns={[
          {
            id: 'filing',
            header: 'Filing',
            width: 260,
            value: (row) => row.filing,
            sortable: true,
            hideable: false,
            cell: (row) => (
              <TableCell value={row.filing} description={row.description} />
            ),
          },
          {
            id: 'entity',
            header: 'Entity',
            width: 200,
            value: (row) => row.entity,
            cell: (row) => (
              <TableCell
                type="entity"
                label={row.entity}
                icon={row.country === 'US' ? <USFlag /> : <DEFlag />}
              />
            ),
          },
          {
            id: 'assignee',
            header: 'Assignee',
            width: 180,
            value: (row) => row.assignee,
            cell: (row) => (
              <TableCell
                type="person"
                identity={{
                  kind: 'person',
                  userId: row.assignee,
                  name: row.assignee,
                }}
              />
            ),
          },
          {
            id: 'status',
            header: 'Status',
            align: 'center',
            width: 120,
            value: (row) => row.status,
            cell: (row) => (
              <TableCell
                type="badge"
                items={[
                  {
                    label: row.status,
                    tone:
                      row.status === 'Done'
                        ? 'success'
                        : row.status === 'To do'
                          ? 'neutral'
                          : 'info',
                  },
                ]}
              />
            ),
          },
          {
            id: 'due',
            header: 'Due date',
            width: 120,
            value: (row) => row.due,
            sortable: true,
          },
          {
            id: 'actions',
            header: 'Actions',
            width: 56,
            hideable: false,
            cell: (row) => (
              <TableRowActions
                primary={{
                  label: `View ${row.filing}`,
                  icon: <EyeIcon />,
                  onAction: () => {
                    setNotice(`Opened ${row.filing}`);
                  },
                }}
              />
            ),
          },
        ]}
        searchConfig={{
          getText: (row) => `${row.filing} ${row.entity} ${row.assignee}`,
        }}
        filterConfig={{
          filters: [
            {
              id: 'status',
              label: 'Status',
              options: ['To do', 'In progress', 'Done'].map((value) => ({
                value,
                label: value,
              })),
              matches: (row, values) => values.includes(row.status),
            },
          ],
          value: filters,
          onValueChange: setFilters,
        }}
        selectionConfig={{
          value: selection,
          onValueChange: setSelection,
          actions: [
            {
              id: 'assign',
              label: 'Assign',
              onAction: () => {
                setNotice('Assignment requested for selected records');
              },
            },
          ],
        }}
        toolbarConfig={{
          onExport: () => {
            setNotice('Export requested');
          },
        }}
      />
      {notice && <p role="status">{notice}</p>}
    </div>
  );
};
```


This filing table combines descriptions, country flags, assignees, status badges and row actions in a real record layout. `cell(row)` composes existing Pathfinder components without changing the underlying record shape. Entity names use flags; people use Avatar. System status uses Badge, while selected removable values use Tag.

Text aligns at the leading edge, numbers at the trailing edge, and badges align with their header. Missing values use an en dash, not zero. Use `TableNumberCell` for consistent decimals and ISO currency labels. Long names can grow a row rather than lose essential content.

## Grouped records [#grouped-records]


```tsx
import { useState } from 'react';

import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { Table, TableCell, TableNumberCell } from '@commenda/pathfinder/table';

export const TableWorkflowsDefault = () => {
  const rows = [
    {
      id: '1',
      filing: 'VAT return Q3',
      description: 'Monthly · Federal Central Tax Office',
      entity: 'DE',
      assignee: 'Lucas Moreau',
      status: 'Filed',
      fee: 0,
    },
    {
      id: '2',
      filing: 'Trade tax return',
      description: 'Annual · Munich',
      entity: 'DE',
      assignee: 'Priya Shah',
      status: 'In review',
      fee: 180,
    },
    {
      id: '3',
      filing: 'Annual accounts',
      description: 'Annual · Bundesanzeiger',
      entity: 'DE',
      assignee: 'Aisha Khan',
      status: 'Not started',
      fee: 95,
    },
    {
      id: '4',
      filing: 'Delaware annual report',
      description: 'Annual · Delaware',
      entity: 'US',
      assignee: 'Jun Tan',
      status: 'Overdue',
      fee: 450,
    },
    {
      id: '5',
      filing: 'BOI report update',
      description: 'One-time · FinCEN',
      entity: 'US',
      assignee: 'Mira de Vries',
      status: 'Due soon',
      fee: 0,
    },
  ];
  const [notice, setNotice] = useState('');

  return (
    <div className="pf:w-full pf:min-w-0">
      <Table
        label="Grouped filings"
        rows={rows}
        rowConfig={{
          getId: (row) => row.id,
          getLabel: (row) => row.filing,
          menu: (row) => ({
            groups: [
              {
                id: 'filing',
                items: [
                  {
                    id: 'review',
                    type: 'action',
                    label: 'Review filing',
                    onClick: () => {
                      setNotice(`Reviewing ${row.filing}`);
                    },
                  },
                ],
              },
            ],
          }),
        }}
        groupingConfig={{
          getId: (row) => row.entity,
          getLabel: (id) => (id === 'DE' ? 'Acme GmbH' : 'Acme Inc.'),
          leading: (id) =>
            id === 'DE' ? <DEFlag size={16} /> : <USFlag size={16} />,
          summary: (_id, pageRows) =>
            `${String(pageRows.filter((row) => row.status === 'Filed').length)} of ${String(pageRows.length)} filed`,
        }}
        selectionConfig={{}}
        columns={[
          {
            id: 'filing',
            header: 'Filing',
            width: 280,
            cell: (row) => (
              <TableCell value={row.filing} description={row.description} />
            ),
          },
          {
            id: 'assignee',
            header: 'Assignee',
            width: 180,
            cell: (row) => (
              <TableCell
                type="person"
                identity={{
                  kind: 'person',
                  name: row.assignee,
                  userId: row.assignee,
                }}
              />
            ),
          },
          {
            id: 'status',
            header: 'Status',
            width: 128,
            cell: (row) => (
              <TableCell
                type="badge"
                items={[
                  {
                    label: row.status,
                    tone:
                      row.status === 'Filed'
                        ? 'success'
                        : row.status === 'Overdue'
                          ? 'error'
                          : 'neutral',
                  },
                ]}
              />
            ),
          },
          {
            id: 'fee',
            header: 'Fee',
            width: 120,
            align: 'end',
            cell: (row) => (
              <TableNumberCell
                value={row.fee}
                unit={row.entity === 'DE' ? 'EUR' : 'USD'}
              />
            ),
          },
        ]}
      />
      <p role="status" className="pf:text-copy-12 pf:text-soft-pearl-800">
        {notice ||
          'Collapse a group, select records, then reopen it. Selection persists; counts describe the current page.'}
      </p>
    </div>
  );
};
```


Group filings by entity with a flag, count and read-only summary. Activate a group header to collapse it. Selection survives collapse, and the header checkbox still selects eligible records on the current page. Search, sort and pagination operate before grouping; page counts describe records, never group headers. A large entity may span pages. The summary callback receives the current page's group records; pass app-owned aggregates if the summary must describe the entire query.

Use `groupingConfig.getId`, `getLabel`, optional `leading`, `summary`, and controlled/uncontrolled `collapsedGroups`. For recursive financial rows, use [DataGrid hierarchy](/docs/components/data-grid#expandable-rows-and-totals).

## Toolbar actions [#toolbar-actions]


```tsx
import { useState } from 'react';

import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { PlusIcon } from '@commenda/pathfinder/icons/PlusIcon';
import { Table, TableCell } from '@commenda/pathfinder/table';

export const TableWorkflowsActions = () => {
  const [notice, setNotice] = useState('');

  return (
    <div className="pf:w-full pf:min-w-0">
      <Table
        label="Document actions"
        rows={[
          { id: '1', name: 'Articles of association.pdf' },
          { id: '2', name: 'Register of directors.pdf' },
        ]}
        columns={[
          {
            id: 'name',
            header: 'Document',
            width: 400,
            cell: (row) => (
              <TableCell
                type="file"
                label={row.name}
                icon={<FilePdfIcon size={16} />}
              />
            ),
          },
        ]}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.name }}
        searchConfig={{ getText: (row) => row.name }}
        toolbarConfig={{
          onExport: () => {
            setNotice('Export requested');
          },
          secondaryAction: {
            id: 'folder',
            label: 'New folder',
            onAction: () => {
              setNotice('New folder requested');
            },
          },
          primaryAction: {
            id: 'upload',
            label: 'Upload',
            icon: <PlusIcon />,
            onAction: () => {
              setNotice('Upload files requested');
            },
            menu: {
              groups: [
                {
                  id: 'upload',
                  items: [
                    {
                      id: 'folder',
                      type: 'action',
                      label: 'Upload folder',
                      onClick: () => {
                        setNotice('Upload folder requested');
                      },
                    },
                  ],
                },
              ],
            },
          },
          moreMenu: {
            groups: [
              {
                id: 'extra',
                items: [
                  {
                    id: 'refresh',
                    type: 'action',
                    label: 'Refresh documents',
                    onClick: () => {
                      setNotice('Refresh requested');
                    },
                  },
                ],
              },
            ],
          },
        }}
      />
      <p role="status" className="pf:text-copy-12 pf:text-soft-pearl-800">
        {notice ||
          'Demonstration actions update this message. Your application supplies the upload, export and folder workflows.'}
      </p>
    </div>
  );
};
```


The right side contains tools, overflow, a divider, then at most one secondary and one primary action. Export becomes an icon when actions are present. A primary action with `menu` renders a SplitButton: the main button performs the default action, while the arrow exposes alternatives. Selection actions belong in the bulk bar.

Use named `primaryAction` and `secondaryAction`; put extra actions in `moreMenu`. These examples report callbacks locally. Your application supplies upload, export and navigation workflows.

## Documents [#documents]


```tsx
import { useState } from 'react';

import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { DEFlag } from '@commenda/pathfinder/flags/DEFlag';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { Table, TableCell } from '@commenda/pathfinder/table';

export const TableWorkflowsDocuments = () => {
  const [notice, setNotice] = useState('');
  const rows = [
    {
      id: 'HRB 284731',
      name: 'Delaware annual report.pdf',
      country: 'DE',
      entity: 'Acme GmbH',
      person: 'Priya Shah',
      date: '2026-10-02',
    },
    {
      id: 'DE-7745120',
      name: 'Articles of association.pdf',
      country: 'US',
      entity: 'Acme Inc.',
      person: 'Lucas Moreau',
      date: '2026-09-28',
    },
  ];

  return (
    <div className="pf:w-full pf:min-w-0">
      <Table
        label="Documents"
        rows={rows}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.name }}
        sortingConfig={{
          defaultValue: { columnId: 'uploaded', direction: 'desc' },
        }}
        columns={[
          {
            id: 'name',
            header: 'Document',
            width: 300,
            cell: (row) => (
              <TableCell
                type="file"
                label={row.name}
                icon={<FilePdfIcon size={16} />}
              />
            ),
          },
          {
            id: 'entity',
            header: 'Entity',
            width: 180,
            cell: (row) => (
              <TableCell
                type="entity"
                label={row.entity}
                icon={
                  row.country === 'DE' ? (
                    <DEFlag size={16} />
                  ) : (
                    <USFlag size={16} />
                  )
                }
              />
            ),
          },
          {
            id: 'reference',
            header: 'Reference',
            width: 170,
            cell: (row) => (
              <TableCell
                type="copy"
                value={row.id}
                onCopy={() => {
                  void navigator.clipboard.writeText(row.id).then(
                    () => {
                      setNotice(`Copied ${row.id}`);
                    },
                    () => {
                      setNotice('Clipboard permission is unavailable');
                    }
                  );
                }}
              />
            ),
          },
          {
            id: 'person',
            header: 'Uploaded by',
            width: 170,
            cell: (row) => (
              <TableCell
                type="person"
                identity={{
                  kind: 'person',
                  name: row.person,
                  userId: row.person,
                }}
              />
            ),
          },
          {
            id: 'uploaded',
            header: 'Uploaded',
            width: 140,
            sortable: true,
            value: (row) => row.date,
          },
        ]}
      />
      <p role="status" className="pf:text-copy-12 pf:text-soft-pearl-800">
        {notice || 'Copy a reference or change the upload-date sort.'}
      </p>
    </div>
  );
};
```


File icons identify documents, country flags identify entities, and avatars identify uploaders. References expose a copy action on hover, focus or touch. The demo writes the selected reference to the clipboard and reports failures.

## Team members [#team-members]


```tsx
import { useState } from 'react';

import { Table, TableCell } from '@commenda/pathfinder/table';

export const TablePeopleDefault = () => {
  const [notice, setNotice] = useState('');
  const people = [
    {
      id: 'priya',
      name: 'Priya Shah',
      email: 'priya@acme.com',
      role: 'Admin',
      status: 'Active',
      twoFactor: true,
      active: 'Today',
    },
    {
      id: 'lucas',
      name: 'Lucas Moreau',
      email: 'lucas@acme.com',
      role: 'Member',
      status: 'Active',
      twoFactor: true,
      active: 'Yesterday',
    },
    {
      id: 'aisha',
      name: 'Aisha Khan',
      email: 'aisha@acme.com',
      role: 'Read only',
      status: 'Invited',
      twoFactor: false,
      active: null,
    },
    {
      id: 'jun',
      name: 'Jun Tan',
      email: 'jun@acme.com',
      role: 'Member',
      status: 'Deactivated',
      twoFactor: false,
      active: '12 Aug 2026',
    },
  ];

  return (
    <div className="pf:w-full pf:min-w-0">
      <Table
        label="Team members"
        rows={people}
        searchConfig={{ getText: (row) => `${row.name} ${row.email}` }}
        rowConfig={{
          getId: (row) => row.id,
          getLabel: (row) => row.name,
          menu: (row) => ({
            groups: [
              {
                id: 'member',
                items: [
                  {
                    id: 'details',
                    type: 'action',
                    label: 'View member',
                    onClick: () => {
                      setNotice(`Viewing ${row.name}`);
                    },
                  },
                ],
              },
            ],
          }),
        }}
        columns={[
          {
            id: 'name',
            header: 'Member',
            width: 280,
            cell: (row) => (
              <TableCell
                type="person"
                identity={{ kind: 'person', userId: row.id, name: row.name }}
                description={row.email}
              />
            ),
          },
          {
            id: 'role',
            header: 'Role',
            width: 150,
            cell: (row) => (
              <TableCell type="tag" items={[{ label: row.role }]} />
            ),
          },
          {
            id: 'status',
            header: 'Status',
            width: 120,
            cell: (row) => (
              <TableCell
                type="badge"
                items={[
                  {
                    label: row.status,
                    tone:
                      row.status === 'Active'
                        ? 'success'
                        : row.status === 'Invited'
                          ? 'info'
                          : 'neutral',
                  },
                ]}
              />
            ),
          },
          {
            id: 'twoFactor',
            header: '2FA',
            width: 80,
            align: 'center',
            cell: (row) => (
              <TableCell
                type="boolean"
                value={row.twoFactor}
                label={
                  row.twoFactor ? 'Two-factor enabled' : 'Two-factor disabled'
                }
              />
            ),
          },
          {
            id: 'active',
            header: 'Last active',
            width: 140,
            value: (row) => row.active,
          },
        ]}
      />
      <p role="status" className="pf:text-copy-12 pf:text-soft-pearl-800">
        {notice ||
          'Roles are values (Tags); account statuses are read-only Badges.'}
      </p>
    </div>
  );
};
```


People include their email, role as a Tag, account status as a Badge and an accessible yes/no symbol for two-factor authentication. Missing activity is an en dash. Row-specific actions live in the overflow menu.

## Density and containers [#density-and-containers]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Table, TableCell } from '@commenda/pathfinder/table';

export const TablePatternsDefault = () => {
  const [density, setDensity] = useState<'compact' | 'relaxed'>('compact');
  const [container, setContainer] = useState<'card' | 'flat'>('card');

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <Button
        size="sm"
        variant="secondary"
        onClick={() => {
          setContainer(container === 'card' ? 'flat' : 'card');
        }}
      >
        Container: {container}
      </Button>
      <Table
        label="Density and containers"
        container={container}
        viewConfig={{ density: { value: density, onValueChange: setDensity } }}
        rows={[
          { id: 'vat', label: 'VAT return Q3', description: undefined },
          {
            id: 'annual',
            label: 'Annual accounts',
            description: 'Financial year ending 31 Dec 2026',
          },
        ]}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.label }}
        columns={[
          {
            id: 'filing',
            header: 'Filing',
            width: 300,
            cell: (row) => (
              <TableCell value={row.label} description={row.description} />
            ),
          },
          {
            id: 'status',
            header: 'Status',
            width: 140,
            align: 'end',
            cell: () => (
              <TableCell
                type="badge"
                items={[{ label: 'In review', tone: 'info' }]}
              />
            ),
          },
        ]}
      />
    </div>
  );
};
```


Use the view menu to compare compact and relaxed density, and the button to switch card/flat containers. The second record includes a description to show the two-line behavior.

| Measurement             | Compact | Relaxed |
| ----------------------- | ------- | ------- |
| Header                  | 36px    | 36px    |
| Single-line row minimum | 40px    | 52px    |
| Two-line text row       | 52px    | 64px    |
| Horizontal cell padding | 12px    | 12px    |

A card adds a 12px radius and hairline border. Use flat inside an existing surface. Wrapped content, text enlargement and taller custom controls can increase these heights.

## Presets and summary [#presets-and-summary]


```tsx
import { useState } from 'react';

import { Table, TableCell, TableNumberCell } from '@commenda/pathfinder/table';

export const TablePatternsPresets = () => {
  const rows = [
    { id: '1', label: 'Annual accounts', status: 'Overdue', amount: 2400 },
    { id: '2', label: 'VAT return Q3', status: 'Due soon', amount: 1800 },
    { id: '3', label: 'Trade tax return', status: 'Filed', amount: 950 },
    { id: '4', label: 'Corporate income tax', status: 'Filed', amount: 1250 },
  ];
  const [filters, setFilters] = useState<{ status?: readonly string[] }>({});
  const selected =
    filters.status?.length === 1
      ? filters.status[0]
      : filters.status?.length
        ? undefined
        : 'All';
  const visible = rows.filter(
    (row) => !filters.status?.length || filters.status.includes(row.status)
  );

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <div
        role="group"
        aria-label="Filing presets"
        className="pf:grid pf:grid-cols-2 pf:sm:grid-cols-4 pf:gap-lg"
      >
        {['All', 'Overdue', 'Due soon', 'Filed'].map((label) => (
          <button
            key={label}
            type="button"
            aria-pressed={selected === label}
            onClick={() => {
              setFilters(label === 'All' ? {} : { status: [label] });
            }}
            className="pf:min-w-0 pf:rounded-xl pf:border pf:border-solid pf:border-soft-pearl-300 pf:bg-background pf:p-lg pf:text-start pf:text-inherit pf:font-inherit pf:cursor-pointer pf:aria-pressed:border-blue-700 pf:focus-visible:outline-2 pf:focus-visible:outline-blue-700"
          >
            <span className="pf:block pf:text-label-12 pf:text-soft-pearl-800">
              {label}
            </span>
            <span className="pf:block pf:mt-md pf:text-heading-20">
              {label === 'All'
                ? rows.length
                : rows.filter((row) => row.status === label).length}
            </span>
          </button>
        ))}
      </div>
      <Table
        label="Preset filings"
        rows={rows}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.label }}
        columns={[
          {
            id: 'filing',
            header: 'Filing',
            width: 260,
            value: (row) => row.label,
          },
          {
            id: 'amount',
            header: 'Amount',
            width: 160,
            align: 'end',
            cell: (row) => <TableNumberCell value={row.amount} unit="USD" />,
          },
          {
            id: 'status',
            header: 'Status',
            width: 140,
            align: 'end',
            cell: (row) => (
              <TableCell
                type="badge"
                items={[
                  {
                    label: row.status,
                    tone:
                      row.status === 'Filed'
                        ? 'success'
                        : row.status === 'Overdue'
                          ? 'error'
                          : 'warning',
                  },
                ]}
              />
            ),
          },
        ]}
        searchConfig={{}}
        filterConfig={{
          value: filters,
          onValueChange: setFilters,
          filters: [
            {
              id: 'status',
              label: 'Status',
              options: ['Overdue', 'Due soon', 'Filed'].map((label) => ({
                value: label,
                label,
              })),
              matches: (row, values) => values.includes(row.status),
            },
          ],
        }}
        summary={
          <div className="pf:flex pf:flex-wrap pf:gap-3xl">
            <span>
              Matching records <strong>{visible.length}</strong>
            </span>
            <span>
              Total due{' '}
              <strong>
                {new Intl.NumberFormat('en-US', {
                  style: 'currency',
                  currency: 'USD',
                }).format(visible.reduce((sum, row) => sum + row.amount, 0))}
              </strong>
            </span>
          </div>
        }
      />
    </div>
  );
};
```


Choose Overdue, then clear its toolbar filter. Preset cards and filters share state, so the selected preset updates with the query. The summary is read-only. Cards sit above the table; summary content lives inside it.

This example's summary follows the status filter. Production summaries should use aggregates for the same reporting query, including search when applicable, rather than summing one loaded API page. Preset definitions, counts and persistence are app-owned.

## Editable cells and totals [#editable-cells-and-totals]


```tsx
import { useState } from 'react';

import {
  Table,
  TableEditCell,
  TableNumberCell,
} from '@commenda/pathfinder/table';

export const TablePatternsEditing = () => {
  const [rows, setRows] = useState([
    { id: '1', name: 'Software subscriptions', amount: '2400.00' },
    { id: '2', name: 'Office rent', amount: '1800.00' },
  ]);
  const [notice, setNotice] = useState('All changes saved');

  return (
    <div className="pf:w-full pf:min-w-0">
      <Table
        label="Editable lines"
        rows={rows}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.name }}
        columns={[
          {
            id: 'name',
            header: 'Account',
            width: 300,
            hideable: false,
            cell: (row) => (
              <TableEditCell
                label={`Account ${row.id}`}
                value={row.name}
                editor={{ type: 'text' }}
                validate={(value) =>
                  value.trim() ? undefined : 'Enter an account name.'
                }
                onCommit={(name) => {
                  setRows((current) =>
                    current.map((item) =>
                      item.id === row.id ? { ...item, name } : item
                    )
                  );
                  setNotice('Saved just now');
                }}
              />
            ),
          },
          {
            id: 'amount',
            header: 'Amount',
            width: 180,
            align: 'end',
            cell: (row) => (
              <TableEditCell
                label={`${row.name} amount`}
                value={row.amount}
                editor={{ type: 'number', min: 0, unit: 'USD' }}
                display={
                  <TableNumberCell
                    value={Number(row.amount)}
                    unit="USD"
                    format={{
                      minimumFractionDigits: 2,
                      maximumFractionDigits: 2,
                    }}
                  />
                }
                validate={(value) =>
                  value.trim() ? undefined : 'Enter an amount.'
                }
                onCommit={(amount) => {
                  setRows((current) =>
                    current.map((item) =>
                      item.id === row.id ? { ...item, amount } : item
                    )
                  );
                  setNotice('Saved just now');
                }}
              />
            ),
          },
        ]}
        footerConfig={{
          total: {
            label: 'Total',
            cells: {
              amount: (
                <TableNumberCell
                  value={rows.reduce((sum, row) => sum + Number(row.amount), 0)}
                  unit="USD"
                  format={{
                    minimumFractionDigits: 2,
                    maximumFractionDigits: 2,
                  }}
                />
              ),
            },
          },
          addAction: {
            id: 'add',
            label: 'Add line',
            onAction: () => {
              setRows((current) => [
                ...current,
                {
                  id: String(current.length + 1),
                  name: 'New account',
                  amount: '0.00',
                },
              ]);
              setNotice('Line added locally');
            },
          },
        }}
      />
      <p role="status" className="pf:text-label-12 pf:text-soft-pearl-800">
        {notice}
      </p>
    </div>
  );
};
```


Hover a row, click an account or amount, and edit it. Enter saves, Escape cancels, and Add line appends a record. Totals recompute from application data and align by column ID through `footerConfig.total.cells`. The first visible column contains the total label.

The example saves in memory. An async `onCommit` must resolve only after persistence succeeds and reject on failure; the editor retains rejected drafts and offers Retry save. Text/number fields use 28px compact geometry. Select and DatePicker preserve their existing accessible dimensions and can increase row height.

## Account mapping and validation [#account-mapping-and-validation]


```tsx
import { useState } from 'react';

import { Checkbox } from '@commenda/pathfinder/checkbox';
import {
  Table,
  TableEditCell,
  TableNumberCell,
} from '@commenda/pathfinder/table';

export const TableEditingDefault = () => {
  const [rows, setRows] = useState([
    {
      id: '6100',
      name: 'Office rent',
      mapping: 'OPEX',
      allocation: '60',
      amount: 48000,
    },
    {
      id: '6200',
      name: 'Software subscriptions',
      mapping: 'OPEX',
      allocation: '100',
      amount: 21340.5,
    },
    {
      id: '5000',
      name: 'Cost of goods sold',
      mapping: 'COGS',
      allocation: '100',
      amount: 412880,
    },
    {
      id: '6400',
      name: 'Shared services fee',
      mapping: 'OPEX',
      allocation: '140',
      amount: 96000,
    },
  ]);
  const [outlined, setOutlined] = useState(false);
  const [fail, setFail] = useState(false);
  const [notice, setNotice] = useState(
    'The last row has an invalid allocation. Edit it to correct the value.'
  );

  const save = (
    id: string,
    patch: { mapping?: string; allocation?: string }
  ) => {
    if (fail)
      return Promise.reject(
        new Error('Save failed. Your draft is retained; try again.')
      );
    setRows((current) =>
      current.map((row) => (row.id === id ? { ...row, ...patch } : row))
    );
    setNotice('Saved just now');

    return Promise.resolve();
  };

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <div className="pf:flex pf:flex-wrap pf:gap-xl">
        <Checkbox
          label="Keep fields outlined"
          checked={outlined}
          onCheckedChange={setOutlined}
        />
        <Checkbox
          label="Simulate save failure"
          checked={fail}
          onCheckedChange={setFail}
        />
      </div>
      <Table
        label="Account mapping"
        rows={rows}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.name }}
        columns={[
          { id: 'id', header: 'Account', width: 96, value: (row) => row.id },
          { id: 'name', header: 'Name', width: 260, value: (row) => row.name },
          {
            id: 'mapping',
            header: 'Mapping',
            width: 200,
            cell: (row) => (
              <TableEditCell
                label={`${row.name} mapping`}
                value={row.mapping}
                editor={{
                  type: 'select',
                  options: ['OPEX', 'COGS', 'Revenue'].map((label) => ({
                    value: label,
                    label,
                  })),
                }}
                outlined={outlined}
                onCommit={(mapping) => save(row.id, { mapping })}
              />
            ),
          },
          {
            id: 'allocation',
            header: 'Allocation',
            width: 160,
            align: 'end',
            cell: (row) => (
              <TableEditCell
                label={`${row.name} allocation`}
                value={row.allocation}
                editor={{ type: 'number', min: 0, max: 100, suffix: '%' }}
                outlined={outlined}
                validationMessage={
                  Number(row.allocation) > 100
                    ? 'Allocation cannot exceed 100%.'
                    : undefined
                }
                validate={(value) =>
                  Number(value) < 0 || Number(value) > 100 || !value.trim()
                    ? 'Enter an allocation from 0 to 100.'
                    : undefined
                }
                onCommit={(allocation) => save(row.id, { allocation })}
              />
            ),
          },
          {
            id: 'amount',
            header: 'Amount',
            width: 160,
            align: 'end',
            cell: (row) => (
              <TableNumberCell
                value={row.amount}
                unit="EUR"
                format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
              />
            ),
          },
        ]}
        footerConfig={{
          total: {
            label: 'Total',
            cells: {
              amount: (
                <TableNumberCell
                  value={rows.reduce((sum, row) => sum + row.amount, 0)}
                  unit="EUR"
                />
              ),
            },
          },
          addAction: {
            id: 'add',
            label: 'Add line',
            onAction: () => {
              setRows((current) => [
                ...current,
                {
                  id: `new-${String(current.length)}`,
                  name: 'New account',
                  mapping: 'OPEX',
                  allocation: '0',
                  amount: 0,
                },
              ]);
            },
          },
        }}
      />
      <p
        role="status"
        className="pf:m-0 pf:text-copy-12 pf:text-soft-pearl-800"
      >
        {notice}
      </p>
    </div>
  );
};
```


This account-mapping example combines Select and numeric editors, an existing invalid allocation, aligned money totals and Add line. Try Keep fields outlined for form-style tables. Simulate save failure retains the draft and exposes retry; disable the simulation to complete the save. The app owns validation and financial calculations.

## Dates, switches and attachments [#dates-switches-and-attachments]


```tsx
import { useRef, useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Upload01Icon } from '@commenda/pathfinder/icons/Upload01Icon';
import { Switch } from '@commenda/pathfinder/switch';
import { Table, TableCell, TableEditCell } from '@commenda/pathfinder/table';

export const TableEditingControls = () => {
  const [date, setDate] = useState('2026-10-30');
  const [enabled, setEnabled] = useState(true);
  const [filename, setFilename] = useState('');
  const fileInput = useRef<HTMLInputElement>(null);

  return (
    <div className="pf:w-full pf:min-w-0 pf:space-y-lg">
      <Table
        label="Editable filing controls"
        rows={[{ id: 'vat', name: 'VAT return Q3' }]}
        rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.name }}
        columns={[
          {
            id: 'name',
            header: 'Filing',
            width: 240,
            value: (row) => row.name,
          },
          {
            id: 'due',
            header: 'Due date',
            width: 220,
            cell: () => (
              <TableEditCell
                label="VAT due date"
                value={date}
                editor={{ type: 'date' }}
                onCommit={setDate}
              />
            ),
          },
          {
            id: 'enabled',
            header: 'Reminders',
            width: 120,
            cell: () => (
              <Switch
                label="Send VAT reminders"
                hideLabel
                checked={enabled}
                onCheckedChange={setEnabled}
              />
            ),
          },
          {
            id: 'attachment',
            header: 'Attachment',
            width: 260,
            cell: () =>
              filename ? (
                <TableCell
                  type="file"
                  label={filename}
                  icon={<FilePdfIcon size={16} />}
                />
              ) : (
                <IconButton
                  label="Attach PDF"
                  size="sm"
                  onClick={() => fileInput.current?.click()}
                >
                  <Upload01Icon size={16} />
                </IconButton>
              ),
          },
        ]}
      />
      <input
        ref={fileInput}
        className="pf:sr-only"
        type="file"
        accept="application/pdf,.pdf"
        aria-label="Choose PDF attachment"
        tabIndex={-1}
        onChange={(event) => {
          setFilename(event.currentTarget.files?.[0]?.name ?? '');
        }}
      />
      {filename && (
        <Button
          size="sm"
          variant="secondary"
          onClick={() => {
            setFilename('');
            if (fileInput.current) fileInput.current.value = '';
          }}
        >
          Remove attachment
        </Button>
      )}
      <p
        role="status"
        className="pf:m-0 pf:text-copy-12 pf:text-soft-pearl-800"
      >
        {filename
          ? `Selected ${filename} locally; no file was uploaded.`
          : 'Date, reminder and attachment changes are local to this example.'}
      </p>
    </div>
  );
};
```


Compose DatePicker editing, an immediate Switch and an upload action directly in cells. The picker keeps Pathfinder's approved DateField geometry. Once a PDF is chosen, its filename replaces the upload action. File selection is local in this example; no bytes leave the browser. Real uploads need application-side file validation, progress, persistence and failure handling.

## API-controlled data [#api-controlled-data]


```tsx
import { useState } from 'react';

import { Table } from '@commenda/pathfinder/table';

const filingRows = [
  {
    id: '1',
    filing: 'Delaware annual report',
    description: 'Annual compliance · 2026',
    entity: 'Meridian US Inc.',
    country: 'US',
    assignee: 'Priya Shah',
    status: 'In progress',
    due: '2026-10-15',
  },
  {
    id: '2',
    filing: 'VAT return Q3',
    description: 'Quarterly tax return',
    entity: 'Meridian GmbH',
    country: 'DE',
    assignee: 'Lucas Moreau',
    status: 'To do',
    due: '2026-10-20',
  },
  {
    id: '3',
    filing: 'Corporate income tax',
    description: 'Financial year 2025',
    entity: 'Meridian US Inc.',
    country: 'US',
    assignee: 'Aisha Khan',
    status: 'Done',
    due: '2026-10-25',
  },
  {
    id: '4',
    filing: 'Financial statements',
    description: 'Annual financial reporting',
    entity: 'Meridian GmbH',
    country: 'DE',
    assignee: 'Jun Tan',
    status: 'To do',
    due: '2026-10-30',
  },
];

export const TableRemote = () => {
  const [page, setPage] = useState({ page: 1, pageSize: 25 });
  const [query, setQuery] = useState('');
  // Replace this synchronous fixture with an API response. The app owns request cancellation.
  const matches = filingRows.filter((row) =>
    row.filing.toLowerCase().includes(query.toLowerCase())
  );

  return (
    <Table
      label="Remote filings"
      dataMode="remote"
      rows={matches.slice(
        (page.page - 1) * page.pageSize,
        page.page * page.pageSize
      )}
      columns={[{ id: 'name', header: 'Filing', value: (row) => row.filing }]}
      rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.filing }}
      paginationConfig={{
        value: page,
        onValueChange: setPage,
        totalRows: matches.length,
      }}
      searchConfig={{ value: query, onValueChange: setQuery }}
    />
  );
};
```


`dataMode="remote"` displays exactly the rows returned by the app. Table never sorts, filters or slices that received page again. The example uses synchronous fixture filtering to demonstrate state ownership, not a production API adapter.

Use search, filters, sort and pagination as a request key. Keep typing responsive, debounce requests rather than the displayed value, cancel obsolete requests, and prevent stale responses from replacing newer results. Remote numbered pages require `paginationConfig.totalRows`. URL persistence, exports and server authorization remain application responsibilities.

### Cursor pagination [#cursor-pagination]


```tsx
import { useState } from 'react';

import { Table } from '@commenda/pathfinder/table';

const invoices = Array.from({ length: 12 }, (_, index) => ({
  id: `INV-${String(index + 1).padStart(3, '0')}`,
  customer: ['Meridian GmbH', 'Meridian US Inc.', 'Meridian UK Ltd.'][
    index % 3
  ],
  amount: (index + 1) * 250,
}));

export const TableDataCursor = () => {
  // Simulates server pages; a real API owns opaque cursors and request cancellation.
  const [pageIndex, setPageIndex] = useState(0);
  const pageSize = 4;
  const pageRows = invoices.slice(
    pageIndex * pageSize,
    (pageIndex + 1) * pageSize
  );

  return (
    <Table
      label="Cursor-paginated invoices"
      dataMode="remote"
      rows={pageRows}
      rowConfig={{ getId: (row) => row.id, getLabel: (row) => row.id }}
      columns={[
        { id: 'invoice', header: 'Invoice', value: (row) => row.id },
        {
          id: 'customer',
          header: 'Customer',
          width: 240,
          value: (row) => row.customer,
        },
      ]}
      paginationConfig={{
        mode: 'cursor',
        pageSize,
        hasPrevious: pageIndex > 0,
        hasNext: (pageIndex + 1) * pageSize < invoices.length,
        onPrevious: () => {
          setPageIndex((current) => current - 1);
        },
        onNext: () => {
          setPageIndex((current) => current + 1);
        },
        summary: `Showing ${String(pageRows.length)} records`,
      }}
    />
  );
};
```


Use Previous and Next without an invented total. The demo simulates server pages; real applications hold opaque API cursors. Supply `hasNext`, `hasPrevious`, callbacks and an honest summary. Pair cursor configuration with `dataMode="remote"`.

## Loading, empty and error [#loading-empty-and-error]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { Table } from '@commenda/pathfinder/table';

export const TableStates = () => {
  const [state, setState] = useState<'loading' | 'empty' | 'error'>('loading');

  return (
    <div className="pf:w-full">
      <div className="pf:flex pf:gap-md pf:mb-lg">
        {(['loading', 'empty', 'error'] as const).map((value) => (
          <Button
            key={value}
            variant="secondary"
            size="sm"
            onClick={() => {
              setState(value);
            }}
          >
            {value === 'loading'
              ? 'Loading'
              : value === 'empty'
                ? 'Empty'
                : 'Error'}
          </Button>
        ))}
      </div>
      <Table
        label="Record states"
        rows={[]}
        columns={[{ id: 'name', header: 'Filing' }]}
        rowConfig={{ getId: () => '', getLabel: () => '' }}
        stateConfig={{
          isLoading: state === 'loading',
          error:
            state === 'error'
              ? {
                  message: 'The request failed. Your filters are preserved.',
                  onRetry: () => {
                    setState('loading');
                  },
                }
              : undefined,
          empty: {
            title: 'No filings yet',
            description: 'Add your first filing to start tracking compliance.',
          },
        }}
      />
    </div>
  );
};
```


Switch between loading skeletons, first-use emptiness and a retryable error. Search/filter emptiness instead offers Clear filters. Keep toolbar and column geometry stable while requests run. Retry should repeat the current query, not discard the user's scope.

## Accessibility and responsive behavior [#accessibility-and-responsive-behavior]

Table retains native table semantics. Checkbox selection is separate from row activation; a focused activatable row opens with Enter. Search shortcuts apply while focus is in table tools. The scroll region supports keyboard access. Narrow layouts scroll within the component and release pinned columns if they would hide readable values.

Read the [Figma rules and explicit differences](/docs/components/table#design-rules) before changing dimensions or behavior.

## API reference [#api-reference]

`groupingConfig` groups the current page: `{ getId(row), getLabel(id), leading?(id), summary?(id, pageRows), collapsedGroups? }`. Collapsed state is a list of group IDs using the same `value` / `onValueChange` or `defaultValue` convention as other preferences.

`TableFilter` is discriminated by `type`:

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Visible field label. Supply an accessible name when it is omitted. |
| `rows` | `readonly TRow[]` | required |  |
| `columns` | `readonly TableColumn<TRow>[]` | required |  |
| `rowConfig` | `{ getId: (row: TRow) => string; getLabel: (row: TRow) => string; onActivate?: ((row: TRow) => void) \| undefined; menu?: ((row: TRow) => DropdownMenu) \| undefined; }` | required |  |
| `viewConfig` | `{ density?: SelectionProps<"compact" \| "relaxed">; hiddenColumns?: SelectionProps<readonly string[]>; columnWidths?: SelectionProps<Readonly<Partial<Record<string, number>>>>; columnPinning?: SelectionProps<Readonly<Partial<Record<string, "start" \| "end" \| null>>>>; }` | optional |  |
| `groupingConfig` | `{ getId: (row: TRow) => string; getLabel: (id: string) => string; leading?: (id: string) => ReactNode; summary?: ((id: string, pageRows: readonly TRow[]) => ReactNode) \| undefined; collapsedGroups?: SelectionProps<readonly string[]>; }` | optional |  |
| `container` | `"card" \| "flat"` | optional |  |
| `sortingConfig` | `SelectionProps<TableSort \| null>` | optional |  |
| `searchConfig` | `SelectionProps<string> & { getText?: ((row: TRow) => string) \| undefined; placeholder?: string; }` | optional |  |
| `filterConfig` | `{ filters: readonly TableFilter<TRow>[]; operators?: SelectionProps<Readonly<Record<string, TableFilterOperator>>>; value: Readonly<Record<string, readonly string[]>>; onValueChange: (value: Record<string, readonly string[]>) => void; }` | optional |  |
| `selectionConfig` | `SelectionProps<TableSelection> & { canSelect?: ((row: TRow) => boolean) \| undefined; allMatching?: { queryKey: string; total: number; }; actions?: readonly TableAction[]; moreMenu?: DropdownMenu; }` | optional |  |
| `toolbarConfig` | `TableToolbarConfig` | optional |  |
| `stateConfig` | `TabularStateConfig` | optional |  |
| `summary` | `ReactNode` | optional |  |
| `footerConfig` | `{ total?: { label: string; cells: Readonly<Record<string, ReactNode>>; }; addAction?: TableAction; }` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |
| `dataMode` | `"local" \| "remote"` | conditional |  |
| `paginationConfig` | `{ mode?: "pages"; totalRows?: number; pageSizes?: readonly number[]; } & SelectionProps<TablePage> \| { mode: "cursor"; hasNext: boolean; hasPrevious: boolean; onNext: () => void; onPrevious: () => void; summary?: string; pageSize: number; onPageSizeChange?: (size: number) => void; } \| ({ mode?: "pages"; totalRows?: number; pageSizes?: readonly number[]; } & SelectionProps<TablePage>) & { totalRows: number; }` | conditional |  |

### rowConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `getId` | `(row: TRow) => string` | Yes |  |
| `getLabel` | `(row: TRow) => string` | Yes |  |
| `onActivate` | `((row: TRow) => void)` | No |  |
| `menu` | `((row: TRow) => DropdownMenu)` | No |  |

### viewConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `density` | `SelectionProps<"compact" \| "relaxed">` | No |  |
| `hiddenColumns` | `SelectionProps<readonly string[]>` | No |  |
| `columnWidths` | `SelectionProps<Readonly<Partial<Record<string, number>>>>` | No |  |
| `columnPinning` | `SelectionProps<Readonly<Partial<Record<string, "start" \| "end" \| null>>>>` | No |  |

### viewConfig.density fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `"compact" \| "relaxed"` | Yes |  |
| `onValueChange` | `(value: "compact" \| "relaxed") => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `"compact" \| "relaxed"` | No |  |
| `onValueChange` | `((value: "compact" \| "relaxed") => void)` | No |  |

Do not supply: `value`.

### viewConfig.hiddenColumns fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `readonly string[]` | Yes |  |
| `onValueChange` | `(value: readonly string[]) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `readonly string[]` | No |  |
| `onValueChange` | `((value: readonly string[]) => void)` | No |  |

Do not supply: `value`.

### viewConfig.columnWidths fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `Readonly<Partial<Record<string, number>>>` | Yes |  |
| `onValueChange` | `(value: Readonly<Partial<Record<string, number>>>) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Readonly<Partial<Record<string, number>>>` | No |  |
| `onValueChange` | `((value: Readonly<Partial<Record<string, number>>>) => void)` | No |  |

Do not supply: `value`.

### viewConfig.columnPinning fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `Readonly<Partial<Record<string, "start" \| "end" \| null>>>` | Yes |  |
| `onValueChange` | `(value: Readonly<Partial<Record<string, "start" \| "end" \| null>>>) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Readonly<Partial<Record<string, "start" \| "end" \| null>>>` | No |  |
| `onValueChange` | `((value: Readonly<Partial<Record<string, "start" \| "end" \| null>>>) => void)` | No |  |

Do not supply: `value`.

### groupingConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `getId` | `(row: TRow) => string` | Yes |  |
| `getLabel` | `(id: string) => string` | Yes |  |
| `leading` | `((id: string) => ReactNode)` | No |  |
| `summary` | `((id: string, pageRows: readonly TRow[]) => ReactNode)` | No |  |
| `collapsedGroups` | `SelectionProps<readonly string[]>` | No |  |

### groupingConfig.collapsedGroups fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `readonly string[]` | Yes |  |
| `onValueChange` | `(value: readonly string[]) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `readonly string[]` | No |  |
| `onValueChange` | `((value: readonly string[]) => void)` | No |  |

Do not supply: `value`.

### sortingConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `TableSort \| null` | Yes |  |
| `onValueChange` | `(value: TableSort \| null) => void` | Yes |  |

Do not supply: `defaultValue`.

### sortingConfig.value fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columnId` | `string` | Yes |  |
| `direction` | `"desc" \| "asc"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `TableSort \| null` | No |  |
| `onValueChange` | `((value: TableSort \| null) => void)` | No |  |

Do not supply: `value`.

### sortingConfig.defaultValue fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columnId` | `string` | Yes |  |
| `direction` | `"desc" \| "asc"` | Yes |  |

### filterConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | `readonly TableFilter<TRow>[]` | Yes |  |
| `operators` | `SelectionProps<Readonly<Record<string, TableFilterOperator>>>` | No |  |
| `value` | `Readonly<Record<string, readonly string[]>>` | Yes |  |
| `onValueChange` | `(value: Record<string, readonly string[]>) => void` | Yes |  |

### filterConfig.operators fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `Readonly<Record<string, TableFilterOperator>>` | Yes |  |
| `onValueChange` | `(value: Readonly<Record<string, TableFilterOperator>>) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Readonly<Record<string, TableFilterOperator>>` | No |  |
| `onValueChange` | `((value: Readonly<Record<string, TableFilterOperator>>) => void)` | No |  |

Do not supply: `value`.

### toolbarConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | `readonly TableAction[]` | No | Prefer named actions. Legacy actions use first=primary, second=secondary, remainder=overflow. |
| `primaryAction` | `(TableAction & { menu?: DropdownMenu; icon?: ReactNode; })` | No |  |
| `secondaryAction` | `TableAction` | No |  |
| `onExport` | `(() => void)` | No |  |
| `moreMenu` | `DropdownMenu` | No |  |

### toolbarConfig.secondaryAction fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `onAction` | `() => void` | Yes |  |
| `disabled` | `boolean` | No |  |

### toolbarConfig.moreMenu fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | `DropdownGroup[]` | Yes |  |

### stateConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isLoading` | `boolean` | No |  |
| `error` | `{ message: string; onRetry: () => void; }` | No |  |
| `empty` | `{ title: string; description?: string; action?: TableAction; }` | No |  |

### stateConfig.error fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `onRetry` | `() => void` | Yes |  |

### stateConfig.empty fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Yes |  |
| `description` | `string` | No |  |
| `action` | `TableAction` | No |  |

### stateConfig.empty.action fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `onAction` | `() => void` | Yes |  |
| `disabled` | `boolean` | No |  |

### footerConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `total` | `{ label: string; cells: Readonly<Record<string, ReactNode>>; }` | No |  |
| `addAction` | `TableAction` | No |  |

### footerConfig.total fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `cells` | `Readonly<Record<string, ReactNode>>` | Yes |  |

### footerConfig.addAction fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `label` | `string` | Yes |  |
| `onAction` | `() => void` | Yes |  |
| `disabled` | `boolean` | No |  |

### paginationConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"cursor"` | Yes |  |
| `hasNext` | `boolean` | Yes |  |
| `hasPrevious` | `boolean` | Yes |  |
| `onNext` | `() => void` | Yes |  |
| `onPrevious` | `() => void` | Yes |  |
| `summary` | `string` | No |  |
| `pageSize` | `number` | Yes |  |
| `onPageSizeChange` | `((size: number) => void)` | No |  |

All filters have `id`, `label`, optional `icon`, and `initiallyVisible: false` for fields added through More filters. `filterConfig.operators` uses a controlled/uncontrolled map of `is`, `isNot`, `isAnyOf`, `within`, `greaterThan` or `lessThan`; menus expose only operators meaningful for that field type. Range filters use inclusive endpoints. A custom choice `matches` predicate describes positive membership; `isNot` is applied by Table.

| Prop               | Type                                                                   | Behavior                                                                                                          |
| ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `label`            | string                                                                 | Required accessible table name                                                                                    |
| `rows`             | readonly TRow[]                                                        | Immutable local collection or one received API page                                                               |
| `columns`          | readonly TableColumn&lt;TRow&gt;[]                                     | IDs, headers, accessors and renderers                                                                             |
| `rowConfig`        | `{ getId, getLabel, onActivate?, menu? }`                              | Stable unique IDs; activation opens the record, checkbox selects it                                               |
| `dataMode`         | `'local'` or `'remote'`                                                | Local by default; remote never reprocesses the received page                                                      |
| `viewConfig`       | `{ density?, hiddenColumns?, columnWidths?, columnPinning? }`          | Each uses controlled value/onValueChange or defaultValue; compact and all columns visible by default              |
| `container`        | `'card'` or `'flat'`                                                   | Card by default                                                                                                   |
| `sortingConfig`    | SelectionProps&lt;TableSort or null&gt;                                | Controlled value/onValueChange or defaultValue                                                                    |
| `searchConfig`     | `{ value?, defaultValue?, onValueChange?, getText?, placeholder? }`    | Enables search; default local searchable text joins column values                                                 |
| `filterConfig`     | `{ filters, value, onValueChange, operators? }`                        | Controlled filter map; typed choice/date/number definitions, optional controlled operators                        |
| `paginationConfig` | Page or cursor configuration                                           | Local page 1 and 25 rows by default                                                                               |
| `selectionConfig`  | SelectionProps plus selection options                                  | Stable IDs, optional eligibility, query-scoped select-all and bulk actions                                        |
| `toolbarConfig`    | `{ primaryAction?, secondaryAction?, onExport?, moreMenu?, actions? }` | App callbacks; exports never imply just the loaded rows                                                           |
| `stateConfig`      | `{ isLoading?, error?, empty? }`                                       | Skeleton rows, retryable failure or empty state                                                                   |
| `summary`          | ReactNode                                                              | Read-only summary inside the container; put app preset controls above Table                                       |
| `footerConfig`     | `{ total?: { label, cells }, addAction? }`                             | App-owned totals keyed by column ID and an explicit add-row action; first visible column contains the total label |
| `className`        | string                                                                 | Root classes                                                                                                      |

`TableColumn` has `id`, string `header`, optional `description` tooltip, `value(row)`, `cell(row)`, `width`, `minWidth`, `maxWidth` in pixels, `resizable`, `pinnable`, `align: 'start' | 'center' | 'end'`, `sortable`, `compare(left, right)`, `hideable`, and `pin: 'start' | 'end'`. `value` supplies sortable/searchable data even when `cell` renders rich content. Pinned columns are grouped at their logical edge; horizontal pinning releases when it would leave insufficient space for a value column. Do not hide every column. Column IDs and row IDs must remain stable, nonempty and unique when updating data. Invalid IDs, empty column collections and invalid page numbers fail with configuration errors.

`viewConfig.density` uses `compact` or `relaxed`; `viewConfig.hiddenColumns` uses column IDs. Control either independently to persist user preferences. Non-hideable columns stay visible, and the first column remains as a safeguard if all hideable columns were requested hidden.

`TableSort` is `{ columnId, direction: 'asc' | 'desc' }`; the sort control cycles ascending, descending, unsorted. Local search/filter/sort run before pagination. Search and sort changes return to the first page. App-controlled filters should reset the page when changed externally.

### Cell renderers [#cell-renderers]

`TableCell` is a discriminated content component; the owning table supplies padding and height:

| `type`            | Content props                                                       |
| ----------------- | ------------------------------------------------------------------- |
| `text` (default)  | `value`, `description`, `leadingIcon`, `badge`, `tooltip`, `struck` |
| `entity` / `file` | `label`, `icon`, optional `description`                             |
| `person`          | Avatar `identity`, optional `description`                           |
| `people`          | `label`, AvatarGroup `people`                                       |
| `badge` / `tag`   | `items` using existing Badge/Tag props                              |
| `boolean`         | `value`, optional accessible `label`                                |
| `progress`        | existing ProgressBar `progress` props                               |
| `link`            | `label`, `linkConfig`                                               |
| `copy`            | `value`, `onCopy`, optional `copyLabel`                             |
| `loading`         | Skeleton content                                                    |
| `number`          | All TableNumberCell props                                           |

`TableNumberCell` accepts `value`, optional `locale`, Intl.NumberFormat `format`, `unit`, `suffix`, `tone`, `struck` and `trend: { direction: 'up' | 'down', intent: 'positive' | 'critical' | 'neutral' }`. Numbers align right without truncation; unit labels stay separate. Empty and non-finite numeric values show an en dash. Numeric strings preserve their supplied formatting. Trend direction does not determine business meaning: rising costs may be critical.

`TableEditCell` accepts `label`, string `value`, `editor`, optional `display`, `outlined`, `disabled`, `validationMessage`, `validate(value)` and async `onCommit(value)`. Editors are `{ type: 'text', placeholder? }`, `{ type: 'number', min?, max?, step?, unit?, suffix? }`, `{ type: 'select', options, placeholder? }`, or `{ type: 'date', min?, max? }`. Number drafts remain strings; validate and parse at the application boundary. Enter or leaving the editor saves; Escape cancels. Failed saves retain the draft and show Retry save. Select/calendar portals belong to the same editing session. DatePicker retains the approved Kakashi DateField padding. DataGrid manages `editingConfig` internally; ordinary Table renderers use the local editing state.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### API references [#api-references]

The API review used [shadcn's Data Table guide](https://ui.shadcn.com/docs/components/base/data-table), [TanStack controlled state](https://tanstack.com/table/v8/docs/framework/react/guide/table-state) and [typed column definitions](https://tanstack.com/table/v8/docs/guide/column-defs). Pathfinder adopts independently controlled state and reusable boundaries while retaining direct props, Figma styling and precompiled CSS. It keeps TanStack 8.21.3 implementation types private; the current shadcn guide's v9 code is not copied into this v8 integration. Matrix keyboard behavior follows the [ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).

### Table [#table]

- **TABLE-001:** White card, radius 12px, pearl-300 hairline 0.5px; optional flat container. Header 36px, compact row minimum 40px, relaxed 52px, horizontal padding 12px. Two-line text rows are 52px compact and 64px relaxed; longer wrapping and accessible controls can grow further. Toolbar and pagination minimum 48px.
- **TABLE-002:** Hover and selected rows share pearl-200. Checkbox distinguishes selection; clicking the row opens the record. Links, editors, menus and checkboxes do not also activate the row. Enter opens a focused activatable row.
- **TABLE-003:** Local processing is filter/search, sort, then page. Remote processing belongs entirely to the app; no double filtering, sorting or slicing. The app owns URL state, fetching, cancellation, permissions, exports and API cursors. Slash opens search while focus is within table tools. Escape clears then closes search. Search opens in place and its clear action clears and closes. Tools remain together; excess filter buttons use +N. Active compound filter chips wrap below the toolbar.
- **TABLE-004:** Selection persists by stable IDs. All-matching selection requires a query key and eligible total, with explicit excluded IDs. Changing the query key invalidates stale all-selection. Bulk actions float 24px above the viewport bottom; three actions show directly and additional actions use overflow.

- **TABLE-005:** Totals are supplied by column ID through footerConfig. The first visible column labels the total; Add line is a separate explicit application action.

- **TABLE-006:** Column width handles support pointer capture, bounded drag, RTL, 10px arrow steps, Shift 50px, Home/End and Escape rollback. Widths and pinning can be controlled independently. Logical pin offsets include selection/action columns and follow resized or hidden columns.
- **TABLE-007:** Group bars use a 2px inset, pearl-100 and radius 6px. Collapse preserves selection. Group only the current page; page counts and select-current-page refer to records, including collapsed descendants.
- **TABLE-008:** Toolbar tools precede overflow and a divider; at most one secondary and one primary action follow. Export becomes an icon when actions are present. Primary plus alternatives uses SplitButton. Bulk actions never move into the ordinary toolbar.
- **FILTER-001:** AND across fields, OR within multiple choices; `isNot` negates membership. Remote tables forward controlled values/operators to the application and never filter the received page.
- **FILTER-002:** Menus align to their trigger at 4px offset. Single choice replaces; multiple choices retain selection while searching and show selected values first. Date presets/ranges reuse DateCalendar. Numeric ranges require valid ascending endpoints. Clear resets only the owning field.
- **FILTER-003:** Option A chips are bordered, radius 6px and minimum 28px. Field/value reopen the editor; operator opens only compatible operators; remove clears that field. Separate chips wrap beneath the toolbar.
- **FILTER-004:** More filters adds a secondary field and opens its editor immediately. +N exposes filters that do not fit. No active field becomes inaccessible when the container narrows.

- **TABLE-009:** Header master `430:13536` / `428:76`: 36px high, Label/12 Strong, 12px icons, 4px gaps, pearl-800 at rest and pearl-1000 for interactive hover/focus. The neutral selector appears on unsorted hover/focus; sorted direction stays visible. End-aligned headers place sorting before the label. Optional information has an independent keyboard-focusable tooltip. Table backgrounds are white; DataGrid headers retain pearl-100 and vertical rules.

### Shared cells [#shared-cells]

- **CELL-001:** Text starts at the logical leading edge; numbers align at the trailing edge and use tabular figures. Empty values show an en dash. Entity flags are 16px, person avatars 20px. Entity names wrap; do not truncate monetary amounts. Cells compose existing Badge, Tag, Avatar, ProgressBar and exact icon assets.
- **CELL-002:** Currency units remain quiet and separate from values. Fixed decimals are supplied via Intl format options. Trend direction and semantic intent are separate. A cost increase can be critical even though its arrow points up.
- **CELL-003:** At most primary bordered icon, secondary icon and overflow in a row action group. Do not repeat text CTAs in every row.
- **CELL-EDIT-001:** Compact text/number editor minimum 28px and radius 6px; calm border at rest, outline on hover/focus, persistent invalid treatment. Existing Select and DatePicker keep their accessible field geometry; the DatePicker retains the user's approved Kakashi DateField padding rather than shrinking its segmented inputs.
- **CELL-EDIT-002:** Enter or leaving the editor commits one cell; Escape cancels. Pending work cannot duplicate; errors retain drafts and offer retry. React portal focus stays within the same editing session. Application code validates and persists canonical values.

The Figma cell master depicts combinations, not 32 separate exported component classes. The shared content family composes those visual patterns. Toggle and upload actions use existing Switch/FileUpload application workflows in custom cells; they do not pretend to be string editors. TableCell content, TableNumberCell, TableRowActions and TableEditCell work in both owning components.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

- **Selection:** the Table prototype's row-click selection is superseded by its written best practice: row activation opens a record; checkbox selects. The implementation follows that distinction.

- **Accessibility:** quiet text uses pearl-800 for contrast. Long content and text zoom can grow rows. Narrow viewports release horizontal pinning. Copy controls remain visible on touch, and long status labels expose their full text on focus/hover.

- **Application patterns:** presets, summary aggregates, “Saved just now”, network requests, exports, permissions and financial calculations are owned by the app. Demos perform local updates or simulated requests and say so.

- **States and scale:** matrix loading/error fallbacks reuse existing primitives. No virtualization, range operations or spreadsheet formulas are claimed. Stress fixtures do not establish an unlimited-data performance guarantee.

AI consumers should read this page together with the component API and integration pages. Do not infer a public prop from a Figma variant name, or treat a prototype's sample amounts as domain validation rules.

### Header and cell master reconciliation [#header-and-cell-master-reconciliation]

| Reference                                                                                                        | Coverage                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Header master 430:13536](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=430-13536)      | Start/center/end alignment, unsorted/ascending/descending, hover/focus, optional information, checkbox and empty action header; Headers, Selection and Pinning examples. |
| [Groups and add row 445:13858](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=445-13858) | Grouped filings show flags, counts, collapse and page-selection persistence; editable lines show totals and Add line. Application callbacks own actual persistence.      |

Long content and zoom can grow rows beyond Figma's nominal heights. Linear progress and ring progress use their existing Pathfinder primitives; cell recipes do not introduce a new progress implementation. A file-picker example selects a local file and displays its name; production upload, progress and retry belong to the application's upload workflow. These are deliberate compositional boundaries, not built-in backend features.


---

# Tabs

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tabs
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=352-2

```tsx
import { type TabItem, Tabs } from '@commenda/pathfinder/tabs';

const entityTabs: TabItem[] = [
  {
    value: 'details',
    label: 'Details',
    content: 'Your workspace name, logo and default entity.',
  },
  {
    value: 'filings',
    label: 'Filings',
    count: 12,
    content: 'Review upcoming and completed filings.',
  },
  {
    value: 'documents',
    label: 'Documents',
    count: 3,
    content: 'Manage the documents for this entity.',
  },
  {
    value: 'activity',
    label: 'Activity',
    content: 'Recent changes to this entity.',
  },
];

export const TabsDefault = () => (
  <Tabs label="Entity views" items={entityTabs} />
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/tabs`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required; tablist accessible name |
| `items` | `readonly TabItem[]` | required | Required; value, label, content; optional count and disableConfig |
| `value` | `string \| null` | conditional | Controlled / initial selection; first enabled item if omitted |
| `defaultValue` | `string \| null` | optional | Controlled / initial selection; first enabled item if omitted |
| `onValueChange` | `((value: string \| null) => void)` | conditional | Required with value |
| `orientation` | `"vertical" \| "horizontal"` | optional | horizontal |
| `activationMode` | `"manual" \| "automatic"` | optional | automatic; use manual for slow remote content |
| `divider` | `boolean` | optional | true; horizontal only |
| `panelConfig` | `{ keepMounted?: boolean; className?: string; }` | optional | keepMounted false |
| `overflowConfig` | `{ label?: string; }` | optional | More |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `className` | `string` | optional | Additional classes for the component root. |

### panelConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | No |  |
| `className` | `string` | No |  |

### overflowConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Controlled value requires onValueChange and cannot be combined with defaultValue. Item IDs/values must be unique and stable.

## Usage rules [#usage-rules]

`disableConfig: { isDisabled: boolean; reason?: string }` keeps disabled state and its explanation together. Counts are plain numbers, including zero; do not use a Badge or icons inside the tab label.

Horizontal overflow is measured against the container and moves hidden options into More. The active tab stays visible; choosing an overflow item returns focus to its promoted tab. Before measurement, a local scrolling row keeps options reachable. Extremely long active labels remain horizontally scrollable without overflowing the page.

Arrow keys navigate visible tabs; Home/End reach their ends. Automatic mode also selects on arrow focus. Manual mode activates with Enter/Space. More is a separate menu button, reached with Tab. Hidden options remain available in that menu. Disabled options cannot activate. `keepMounted` retains inactive content without leaving it focusable.

Uncontrolled tabs fall back to the first enabled item after removal/disablement. Controlled callers reconcile changed items and own URL synchronization. `null` means no active panel. These tabs model related panels, not an unrelated route-only sidebar.

## Examples [#examples]

### Vertical [#vertical]


```tsx
import { type TabItem, Tabs } from '@commenda/pathfinder/tabs';

const entityTabs: TabItem[] = [
  {
    value: 'details',
    label: 'Details',
    content: 'Your workspace name, logo and default entity.',
  },
  {
    value: 'filings',
    label: 'Filings',
    count: 12,
    content: 'Review upcoming and completed filings.',
  },
  {
    value: 'documents',
    label: 'Documents',
    count: 3,
    content: 'Manage the documents for this entity.',
  },
  {
    value: 'activity',
    label: 'Activity',
    content: 'Recent changes to this entity.',
  },
];

export const TabsVertical = () => (
  <Tabs label="Settings" orientation="vertical" items={entityTabs} />
);
```


### Overflow [#overflow]


```tsx
import { type TabItem, Tabs } from '@commenda/pathfinder/tabs';

const entityTabs: TabItem[] = [
  {
    value: 'details',
    label: 'Details',
    content: 'Your workspace name, logo and default entity.',
  },
  {
    value: 'filings',
    label: 'Filings',
    count: 12,
    content: 'Review upcoming and completed filings.',
  },
  {
    value: 'documents',
    label: 'Documents',
    count: 3,
    content: 'Manage the documents for this entity.',
  },
  {
    value: 'activity',
    label: 'Activity',
    content: 'Recent changes to this entity.',
  },
];

export const TabsOverflow = () => (
  <div style={{ maxWidth: 280, width: '100%' }}>
    <Tabs
      label="Entity views"
      items={[
        ...entityTabs,
        { value: 'billing', label: 'Billing', content: 'Billing details' },
        { value: 'audit', label: 'Audit log', content: 'Audit history' },
      ]}
    />
  </div>
);
```


### Controlled [#controlled]


```tsx
import { useState } from 'react';

import { type TabItem, Tabs } from '@commenda/pathfinder/tabs';

const entityTabs: TabItem[] = [
  {
    value: 'details',
    label: 'Details',
    content: 'Your workspace name, logo and default entity.',
  },
  {
    value: 'filings',
    label: 'Filings',
    count: 12,
    content: 'Review upcoming and completed filings.',
  },
  {
    value: 'documents',
    label: 'Documents',
    count: 3,
    content: 'Manage the documents for this entity.',
  },
  {
    value: 'activity',
    label: 'Activity',
    content: 'Recent changes to this entity.',
  },
];

export const TabsControlled = () => {
  const [value, setValue] = useState<string | null>('details');

  return (
    <div>
      <Tabs
        label="Entity views"
        value={value}
        onValueChange={setValue}
        activationMode="manual"
        panelConfig={{ keepMounted: true }}
        items={[
          ...entityTabs,
          {
            value: 'billing',
            label: 'Billing',
            content: 'Billing',
            disableConfig: {
              isDisabled: true,
              reason: 'Administrator access required',
            },
          },
        ]}
      />
      <p>Selected view: {value}</p>
    </div>
  );
};
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Tabs [#tabs]

Source: [352:10826](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=352-10826), horizontal 352:95, vertical 352:121, docs 354:278.

- `TABS-01` — Source: horizontal height 28, gap 12, Label/12 Strong, 0.5 divider, 2px blue-700 indicator. Counts are plain Label/12 numbers, gap 4; never Badge or icons. Vertical width 180, padding 6/8, radius 6, gap 2, Label/13 Strong, selected pearl-200.
- `TABS-02` — Source/Pathfinder: related panels for one subject. First enabled item is the uncontrolled default. Caller controls URL synchronization; unrelated routes use navigation. Indicator 200ms ease-out, no panel animation, reduced motion immediate.
- `TABS-03` — Source/Pathfinder: More exposes options that do not fit. Measurement reserves More and the active tab; selected hidden tabs become visible and receive focus. Inert copies measure widths; pre-measurement and exceptionally narrow layouts retain local horizontal scrolling. Never discard a tab to solve overflow.
- `TABS-04` — Pathfinder: automatic or manual keyboard activation; disabled items cannot activate. Controlled callers reconcile missing selections; uncontrolled removal/disablement selects the first enabled item. null permits no active panel. keepMounted retains inactive content without focusability; zero counts remain visible.

### Source discrepancies and implementation decisions [#source-discrepancies-and-implementation-decisions]


---

# Tag input

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tag-input
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=179-3

```tsx
import { TagInput } from '@commenda/pathfinder/tag-input';

export const TagInputDefault = () => (
  <TagInput
    label="Labels"
    defaultValue={['Finance', 'Reviewed']}
    description="Press Enter or comma to add a label."
  />
);
```


## Usage [#usage]

Import `TagInput` from `@commenda/pathfinder/tag-input`. Import the compiled stylesheet once. Use Tag input for free-form values; use Multi select when values come from a known set of options.

## Examples [#examples]

### Editing and paste [#editing-and-paste]


```tsx
import { useState } from 'react';

import { TagInput } from '@commenda/pathfinder/tag-input';

export const TagInputEditing = () => {
  const [tags, setTags] = useState<readonly string[]>([
    'Finance',
    'Operations',
  ]);

  return (
    <TagInput
      label="Team labels"
      value={tags}
      onValueChange={setTags}
      entryConfig={{ editable: true, addOnPaste: true, maxTags: 5 }}
      description="Add up to five labels. Double-click a tag to edit it, or paste comma-separated values."
    />
  );
};
```


### Validation [#validation]


```tsx
import { TagInput } from '@commenda/pathfinder/tag-input';

export const TagInputValidation = () => (
  <TagInput
    label="Recipients"
    entryConfig={{
      addOnPaste: true,
      validate: (value) =>
        /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
          ? undefined
          : 'Enter an email address.',
    }}
    description="This example checks email syntax only; the application owns recipient validation."
  />
);
```


### States [#states]


```tsx
import { TagInput } from '@commenda/pathfinder/tag-input';

export const TagInputStates = () => (
  <div style={{ display: 'grid', gap: 24, width: '100%' }}>
    <TagInput label="Read-only labels" defaultValue={['Finance']} readOnly />
    <TagInput
      label="Protected labels"
      defaultValue={['Archived']}
      disableConfig={{ isDisabled: true, reason: 'This record is archived.' }}
    />
    <TagInput
      label="Required labels"
      required
      errorConfig={{
        message: 'Add a label before continuing.',
        reveal: 'immediate',
      }}
    />
  </div>
);
```


## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | conditional | Required accessible field name; alternatively use `aria-label` |
| `hideLabel` | `boolean` | optional | Required accessible field name; alternatively use `aria-label` |
| `value` | `readonly string[]` | conditional | Controlled values; callback is required with `value` |
| `onValueChange` | `((value: readonly string[]) => void)` | conditional | Controlled values; callback is required with `value` |
| `defaultValue` | `readonly string[]` | optional | Initial uncontrolled values |
| `entryConfig` | `{ editable?: boolean; addOnPaste?: boolean; addOnTab?: boolean; delimiter?: string; maxTags?: number; validate?: (tag: string) => string \| undefined; }` | optional | `editable`, `addOnPaste`, `addOnTab`, `delimiter`, `maxTags`, `validate` |
| `name` | `string` | optional | Submit each tag as a repeated named value; read with `FormData.getAll(name)` |
| `form` | `string` | optional | Submit each tag as a repeated named value; read with `FormData.getAll(name)` |
| `readOnly` | `boolean` | optional | Values submit, editing and removal are blocked |
| `disableConfig` | `DisableConfig` | optional | Blocks editing and omits values from form submission |
| `description` | `string` | optional | Associated guidance and validation |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Associated guidance and validation |
| `required` | `boolean` | conditional | Associated guidance and validation |
| `placeholder` | `string` | optional | The ref targets the entry input |
| `onBlur` | `FocusEventHandler<HTMLInputElement>` | optional | The ref targets the entry input |
| `aria-label` | `string` | conditional | Accessible name when the field has no visible label. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `id` | `string` | optional | Stable HTML identifier for the component. |
| `className` | `string` | optional | Additional classes for the component root. |

### entryConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `editable` | `boolean` | No |  |
| `addOnPaste` | `boolean` | No |  |
| `addOnTab` | `boolean` | No |  |
| `delimiter` | `string` | No |  |
| `maxTags` | `number` | No |  |
| `validate` | `((tag: string) => string \| undefined)` | No | Return a message to reject a tag; undefined accepts it. |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

## Keyboard and validation [#keyboard-and-validation]

Enter or the configured delimiter adds a trimmed tag. Duplicates are rejected. Arrow keys navigate tags, Backspace removes a highlighted tag, and editable tags support keyboard editing. Tab retains normal focus navigation unless `addOnTab` is enabled. Composition input does not create a tag until composition is complete.

Provide unique, nonempty initial values. Validation belongs to the application; the component never treats an email-shaped value as proof of an address or identity. Uncontrolled native resets restore defaults. Controlled resets remain application-owned.

## Design rules [#design-rules]

- **TAG-INPUT-001:** Reuse the Dice UI primitive used by Kakashi TagInput; ship Pathfinder’s compiled styling without a runtime Kakashi dependency.
- **TAG-INPUT-002:** Use the existing field shell and Tag geometry. Wrap long tags without pushing the entry field outside its container.
- **TAG-INPUT-003:** Announce invalid entries and retain keyboard focus during editing and removal.
- **TAG-INPUT-004:** Read-only and disabled modes prevent mutations; only enabled values participate in form submission.

Tag input is a Kakashi-derived composition of Input and Tag, not a newly extracted standalone Figma component.


---

# Tag

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tag
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=179-3

```tsx
import { Tag } from '@commenda/pathfinder/tag';

export const TagDefault = () => <Tag label="Meridian UK Ltd" />;
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { Tag } from '@commenda/pathfinder/tag';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required value name |
| `tone` | `"neutral" \| "blue"` | optional | neutral; blue marks added context |
| `leadingIcon` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | optional | Decorative 12px slot |
| `removeConfig` | `{ onRemove: () => void; label?: string; isDisabled?: boolean; }` | optional | Named separate button; app owns removal and undo |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### removeConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `onRemove` | `() => void` | Yes |  |
| `label` | `string` | No |  |
| `isDisabled` | `boolean` | No |  |

## Usage rules [#usage-rules]

20px minimum height, radius 4, Label 12. Long labels truncate and expose full text on hover and keyboard focus. Removal stops bubbling to a parent selection control. Do not nest Tag inside a button. Use Badge for system status. Overflow counts have no remove action.

### Tones [#tones]


```tsx
import { Tag } from '@commenda/pathfinder/tag';

export const TagTones = () => (
  <div style={{ display: 'flex', gap: 12 }}>
    <Tag label="United Kingdom" />
    <Tag label="Added context" tone="blue" />
  </div>
);
```


### Removal [#removal]


```tsx
import { useState } from 'react';

import { Tag } from '@commenda/pathfinder/tag';

export const TagRemoval = () => {
  const [removed, setRemoved] = useState(false);

  return removed ? (
    <span role="status">Entity removed</span>
  ) : (
    <Tag
      label="Meridian UK Ltd"
      removeConfig={{
        onRemove: () => {
          setRemoved(true);
        },
      }}
    />
  );
};
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule    | Source            | Contract                                                    |
| ------- | ----------------- | ----------------------------------------------------------- |
| TAG-001 | 179:22            | 20px value chip, radius 4, 12px artwork, optional removal.  |
| TAG-002 | 184 documentation | Keep label single-line; full text available on hover/focus. |

All source IDs refer to [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=68-2).

### Explicit implementation decisions [#explicit-implementation-decisions]

Tag's full-label span is keyboard-focusable for its tooltip and remains text; it is not a fake action button. Only its optional remove button changes data. App code owns undo and selection state.


---

# Text area

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/text-area
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=84-2

```tsx
import { TextArea } from '@commenda/pathfinder/text-area';

export const TextAreaDefault = () => (
  <TextArea
    label="Functional analysis"
    placeholder="e.g. What the entity does for the group and how it is paid."
    description="Shown in the transfer pricing report."
  />
);
```


## Installation [#installation]

Import the component in your screen:

```tsx
import { TextArea } from '@commenda/pathfinder/text-area';
```

Load the stylesheet once in your app root, after host styles:

```tsx
import '@commenda/pathfinder/styles.css';
```

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See [installation](/docs/getting-started/installation) for the workspace setup.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `resizeConfig` | `{ mode: "auto"; minHeight?: number; maxHeight: number; } \| { mode: "manual"; minHeight?: number; maxHeight?: number; } \| { mode: "fixed"; height: number; }` | optional | Auto 80–240px |
| `characterLimitConfig` | `{ max: number; }` | conditional | Soft grapheme limit; excess text is preserved |
| `maxLength` | `number` | optional | Native UTF-16 hard limit; mutually exclusive with soft limit |
| `actionConfig` | `CopyAction` | optional | Optional copy action |
| `label` | `string` | conditional | Visible field label. Supply an accessible name when it is omitted. |
| `hideLabel` | `boolean` | optional | Visually hide the label while preserving its accessible name. |
| `aria-label` | `string` | conditional | Accessible name when the field has no visible label. |
| `required` | `boolean` | conditional | Mark the field as required. See validation guidance for the component. |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` | optional | Choose either `optionalLabel` or `help`, never both. `never` excludes the other field. |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` | optional | Validation message and when it becomes visible. |
| `disableConfig` | `DisableConfig` | optional | Disabled state with an optional explanation. |
| `value` | `string` | conditional |  |
| `onValueChange` | `((value: string) => void)` | conditional |  |
| `defaultValue` | `string` | optional |  |

### resizeConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"auto"` | Yes |  |
| `minHeight` | `number` | No |  |
| `maxHeight` | `number` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"manual"` | Yes |  |
| `minHeight` | `number` | No |  |
| `maxHeight` | `number` | No |  |

#### Option 3

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `"fixed"` | Yes |  |
| `height` | `number` | Yes |  |

### characterLimitConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max` | `number` | Yes |  |

### actionConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"copy"` | Yes |  |
| `label` | `string` | No |  |
| `onCopyError` | `((error: Error) => void)` | No |  |

### labelConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `optionalLabel` | `string` | Yes |  |

Do not supply: `help`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `help` | `string` | Yes |  |

Do not supply: `optionalLabel`.

### errorConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes |  |
| `reveal` | `"after-blur" \| "immediate"` | No |  |

### disableConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDisabled` | `boolean` | Yes |  |
| `reason` | `string` | No |  |

## Shared field props [#shared-field-props]

| Prop            | Type                                                | Behavior                                                     |
| --------------- | --------------------------------------------------- | ------------------------------------------------------------ |
| `label`         | `string`                                            | Visible accessible label; hideLabel hides it visually.       |
| `aria-label`    | `string`                                            | Accessible name when a visible label is not supplied.        |
| `value`         | `string`                                            | Controlled value; provide the corresponding change callback. |
| `defaultValue`  | `string`                                            | Initial value for an uncontrolled control.                   |
| `onValueChange` | `(value: string) => void`                           | Immediate editing changes; no implicit parsing.              |
| `description`   | `string`                                            | Visible supporting guidance.                                 |
| `required`      | `boolean`                                           | Native required semantics and visual asterisk.               |
| `labelConfig`   | `{ optionalLabel }` or `{ help }`                   | One annotation; cannot combine with required.                |
| `errorConfig`   | `{ message, reveal?: 'after-blur' \| 'immediate' }` | Replaces guidance after blur by default.                     |
| `disableConfig` | `{ isDisabled, reason? }`                           | Disables editing; reason stays visible.                      |
| `readOnly`      | `boolean`                                           | Preserves focus, selection, and form submission.             |

Native `name`, `form`, autocomplete, focus/blur handlers, constraints, IDs, ARIA attributes, and typed refs are supported. `className` styles the outer field. Use `onValueChange` for text changes. Form reset restores uncontrolled defaults; controlled values remain application-owned.

## Usage rules [#usage-rules]

Minimum authored height is 80px with Copy 13 text. Auto mode grows until its maximum and then scrolls; manual mode resizes vertically. Soft counters count grapheme clusters including emoji and report excess immediately. Hard native limits use browser UTF-16 counting. A composer/send action belongs outside this component.

### Limit [#limit]


```tsx
import { TextArea } from '@commenda/pathfinder/text-area';

export const TextAreaLimit = () => (
  <TextArea
    label="Summary"
    characterLimitConfig={{ max: 100 }}
    description="Keep the summary concise."
  />
);
```


### Resize [#resize]


```tsx
import { TextArea } from '@commenda/pathfinder/text-area';

export const TextAreaResize = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <TextArea
      label="Auto-growing notes"
      resizeConfig={{ mode: 'auto', maxHeight: 160 }}
    />
    <TextArea label="Resizable notes" resizeConfig={{ mode: 'manual' }} />
    <TextArea
      label="Fixed notes"
      resizeConfig={{ mode: 'fixed', height: 100 }}
    />
  </div>
);
```


### States [#states]


```tsx
import { TextArea } from '@commenda/pathfinder/text-area';

export const TextAreaStates = () => (
  <div style={{ display: 'grid', gap: 20 }}>
    <TextArea
      label="Report text"
      defaultValue="The entity provides management services."
      readOnly
      actionConfig={{ kind: 'copy' }}
    />
    <TextArea
      label="Notes"
      disableConfig={{ isDisabled: true, reason: 'This report is locked.' }}
    />
    <TextArea
      label="Description"
      errorConfig={{
        message: 'Describe the entity’s activities.',
        reveal: 'immediate',
      }}
    />
  </div>
);
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Source rules [#source-rules]

| Rule         | Source           | Contract                                                                  |
| ------------ | ---------------- | ------------------------------------------------------------------------- |
| TEXTAREA-001 | 84:363, 159:383  | Minimum 80px, Copy 13, grow to maximum then scroll.                       |
| TEXTAREA-002 | 159:146, 159:324 | Soft limit permits excess and reports how much; counter opposite support. |
| TEXTAREA-003 | 159:374          | Sending is composer behavior, not TextArea behavior.                      |

All source IDs refer to [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=68-2).

### Explicit implementation decisions [#explicit-implementation-decisions]

True native readOnly remains distinct from disabled despite Figma 158:822 using disabled appearance for non-editable fields. Disabled values do not submit; read-only values do. Disabled editing does not disable the independent copy/reveal actions. Clear cannot modify a disabled/read-only field.

The auto-grow maximum of 240px is a configurable implementation default, not an authored Figma measurement. Soft counters use Unicode graphemes; native maxLength uses browser UTF-16 counting. They are mutually exclusive to avoid contradictory limits.

Error reveal defaults to after-blur; immediate reveal supports submission/server errors. Soft-limit feedback is immediate. Applications own validation schemas and server error clearing. Additional required/help guidance belongs in description when the single label annotation is already occupied.

Optional-label text uses pearl 800 instead of the authored pearl 700: browser axe measured the latter at 3.38:1 on white, below the 4.5:1 requirement for this text.


---

# Thinking indicator

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/thinking-indicator
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=601-225

```tsx
import { ThinkingIndicator } from '@commenda/pathfinder/thinking-indicator';

<ThinkingIndicator
  variant="orb"
  size={32}
  label="Thinking…"
  showLabel={!hasContent}
/>;
```


## Usage [#usage]

```tsx
import { ThinkingIndicator } from '@commenda/pathfinder/thinking-indicator';

<ThinkingIndicator
  variant="orb"
  size={32}
  label="Thinking…"
  showLabel={!hasContent}
/>;
```

## Live activity [#live-activity]


```tsx
import { ThinkingIndicator } from '@commenda/pathfinder/thinking-indicator';

<ThinkingIndicator
  variant="orb"
  size={32}
  label="Thinking…"
  showLabel={!hasContent}
/>;
```


Use Start/Finish activity to exercise streaming updates. New run resets disclosure intent.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `variant` | `"orb" \| "dots"` | optional | Rings by default; hidden Figma avatar/globe variants are excluded |
| `size` | `24 \| 32 \| 40` | optional | 32 in a Thinking row; 40 for a standalone chat mark |
| `label` | `string` | optional | Accessible status, defaults to Thinking… |
| `showLabel` | `boolean` | optional | Default true; hide after first step or word while retaining the orb |
| `active` | `boolean` | optional | Default true; false renders a still |
| `className` | `string` | optional | Layout override |

## Design rules [#design-rules]

- **THINKING-01:** Figma 599:7 / 599:28306: approved dotted rings and typing dots only; sizes 24/32/40. Default row 32, Label13 pearl800, gap4.
- **THINKING-02:** Remove the visible Thinking… label after the first step/word. Keep the orb for the generation; unmount when finished. The host owns this lifecycle.
- **THINKING-03:** The canvas loop uses Figma ring counts, radii and tilts, a 1s sine gather, 1.9s cubic growth staggered by 0.3s, and an inner-first 1.8s fold when switching from orb to dots, and stops in background tabs. Reduced motion and inactive states render a still. The status label remains accessible.

## Accessibility and integration [#accessibility-and-integration]

The canvas is decorative and hidden from assistive technology. A persistent `role="status"` label uses polite announcements; `showLabel={false}` keeps that label available to screen readers. Render one meaningful status per response and do not replace its label with every streamed token. Reduced motion and `active={false}` produce a still, with the same accessible text. There are no interactive controls in ThinkingIndicator itself.

The application owns requests, cancellation, approval, retries, durations, and history persistence. No AI SDK provider is required. See [AI content integration](/docs/guides/ai-content) for migration mappings; consumer migration is outside this phase.


---

# Toast

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/toast
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=316-2

```tsx
import { Toaster, toast } from '@commenda/pathfinder/toast';
// Mount Toaster once in your application shell.
<>
  <Toaster />
  <Button
    onClick={() =>
      toast.show({
        title: 'Updated filing',
        description: 'Your filing details are up to date.',
        tone: 'success',
      })
    }
  >
    Show success
  </Button>
</>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Toaster, toast } from '@commenda/pathfinder/toast';
// Mount Toaster once in your application shell.
<>
  <Toaster />
  <Button
    onClick={() =>
      toast.show({
        title: 'Updated filing',
        description: 'Your filing details are up to date.',
        tone: 'success',
      })
    }
  >
    Show success
  </Button>
</>;
```

## API reference [#api-reference]

| Prop                        | Type                                                        | Default / behavior                                |
| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `Toaster.label`             | `string`                                                    | Notifications; Alt+T enters stack                 |
| `Toaster.direction`         | `ltr \| rtl \| auto`                                        | auto                                              |
| `toast.show(options)`       | `ToastId`                                                   | Creates a notification                            |
| `toast.update(id, options)` | `ToastId`                                                   | Replaces the same notification; pass full options |
| `toast.dismiss(id?)`        | `void`                                                      | Dismisses one or all Pathfinder notifications     |
| `title`                     | `string`                                                    | Required, past tense, sentence case               |
| `description`               | `string`                                                    | Optional concise supporting copy                  |
| `tone`                      | `neutral \| success \| info \| warning \| error \| loading` | neutral                                           |
| `id`                        | `string`                                                    | Optional stable task identifier                   |
| `actionConfig`              | `FeedbackAction & { appearance?: link \| secondary }`       | One action; secondary only for neutral            |
| `onDismiss`                 | `(reason: manual \| timeout \| swipe) => void`              | Notification removed from the active queue        |

Mount one Toaster in the application shell. Import Pathfinder styles once; no extra Sonner CSS is required. Neutral, success and info expire after 4 seconds; warning, error and loading persist. Hover, keyboard focus, hidden documents and queued messages pause expiry. Replace loading in place with update; never show a second result notification. Body clicks do not dismiss. Actions do not dismiss automatically: call toast.dismiss(id) when appropriate. Never put form validation or required decisions in a toast. This wrapper does not migrate or clear the application’s existing Sonner notifications.

### Actions [#actions]

`FeedbackAction` requires a label and exactly one of `onClick` (command) or `href` (native navigation). Commands support `disabled`, `disabledReason`, `loadingConfig`, and `leadingIcon`; navigation supports `target`, `rel`, and `leadingIcon`. The application owns async work and retry state.

## Examples [#examples]

### Tones [#tones]


```tsx
<>
  {(['neutral', 'info', 'success', 'warning', 'error', 'loading'] as const).map(
    (tone) => (
      <Button
        key={tone}
        onClick={() =>
          toast.show({
            title: tone === 'loading' ? 'Submitting filing' : 'Updated filing',
            description: 'Your filing details are up to date.',
            tone,
          })
        }
      >
        Show {tone}
      </Button>
    )
  )}
</>;
```


### Actions [#actions-1]


```tsx
import { Button } from '@commenda/pathfinder/button';
import { toast } from '@commenda/pathfinder/toast';
// Mount Toaster once in the application shell.
<>
  <Button
    variant="secondary"
    onClick={() => {
      toast.show({
        id: 'archive',
        title: 'Filing archived',
        tone: 'neutral',
        actionConfig: {
          label: 'Undo',
          appearance: 'secondary',
          onClick: () => {
            toast.update('archive', {
              title: 'Filing restored',
              tone: 'success',
            });
          },
        },
      });
    }}
  >
    Show Undo
  </Button>
  <Button
    variant="secondary"
    onClick={() => {
      toast.show({
        title: 'Report is ready',
        tone: 'info',
        actionConfig: { label: 'View report', href: '#usage' },
      });
    }}
  >
    Show link
  </Button>
  <Button
    variant="secondary"
    onClick={() => {
      toast.show({
        id: 'retry',
        title: 'Upload failed',
        tone: 'error',
        actionConfig: {
          label: 'Try again',
          onClick: () => {
            toast.update('retry', {
              title: 'Uploading files',
              tone: 'loading',
            });
          },
        },
      });
    }}
  >
    Show retry
  </Button>
</>;
```


### Update [#update]


```tsx
<>
  <Button
    onClick={() =>
      toast.show({ id: 'filing', title: 'Submitting filing', tone: 'loading' })
    }
  >
    Start submission
  </Button>
  <Button
    onClick={() =>
      toast.update('filing', { title: 'Filing submitted', tone: 'success' })
    }
  >
    Complete submission
  </Button>
</>;
```


Read the [design guidance](/docs/components/toast#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Toast — 316:2 [#toast--3162]

- **TOAST-01:** Confirm a recent save, send or copy. Required decisions and durable problems belong in inline Alert. Never use a toast for form validation. Title uses past tense, sentence case, no period; description adds concise supporting text.
- **TOAST-02:** Neutral has no icon; success/info/warning/error use the solid 16 px glyphs from 464:357, not outline substitutes. Neutral/info/success expire after 4 seconds; warning/error/loading persist. Pause on hover, keyboard focus or hidden document. Queued messages get their reading time once visible.
- **TOAST-03:** Loading updates to its result under the same ID. One action maximum, normally a link; never a primary Button. Actions only dismiss when application code requests it. Body clicks do not dismiss.
- **TOAST-04:** Bottom center above overlays; three visible, newest in front. Collapsed peek 14 px at 0.95 scale; expanded gap 8. Width 356 with viewport/safe-area caps, white background, pearl 300 hairline, radius 10, panel elevation, padding 12/16, gap 10. Enter 400 ms ease-out, exit 200 ms; honor reduced motion. Close has a 16 px visible circle and a larger target. Alt+T enters the stack.
- **TOAST-05:** Mount one Pathfinder Toaster. A dedicated Sonner toaster ID and prefixed notification IDs isolate notifications from the existing application toaster. Pathfinder dismiss-all only dismisses its own active IDs. The scoped upstream structural stylesheet is a documented adapter exception to utility-only component styling; applications import only Pathfinder's finished CSS.


---

# Tool call

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tool-call
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=601-225

```tsx
import { ToolCall } from '@commenda/pathfinder/tool-call';

<ToolCall
  name="list_entities"
  status="done"
  meta="2 of 5 have a UK filing"
  output={{ code: '{"count":2}', language: 'json' }}
/>;
```


## Usage [#usage]

```tsx
import { ToolCall } from '@commenda/pathfinder/tool-call';

<ToolCall
  name="list_entities"
  status="done"
  meta="2 of 5 have a UK filing"
  output={{ code: '{"count":2}', language: 'json' }}
/>;
```

## Live activity [#live-activity]


```tsx
import { ToolCall } from '@commenda/pathfinder/tool-call';

<ToolCall
  name="list_entities"
  status="done"
  meta="2 of 5 have a UK filing"
  output={{ code: '{"count":2}', language: 'json' }}
/>;
```


Use Start/Finish activity to exercise streaming updates. New run resets disclosure intent.

## Failure and recovery [#failure-and-recovery]


```tsx
<ToolCall
  name="get_calendar"
  status="failed"
  error="Request timed out."
  input={{ code: '{"jurisdiction":"UK"}', language: 'json' }}
/>;
```


A failure retains the tool glyph and exposes its error outside the disclosure. Retrying belongs to the application: update the same stable tool step to running while preserving the payload disclosure. Use input and output together to show Request and Response CodeBlocks.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `name` | `string` | required | Required machine tool name, such as `list_entities` |
| `status` | `"pending" \| "running" \| "done" \| "failed"` | required | Required execution state |
| `label` | `string` | optional | Overrides automatic English tense/localizes the row |
| `meta` | `string` | optional | Optional inline metadata and supporting copy |
| `description` | `string` | optional | Optional inline metadata and supporting copy |
| `error` | `string` | optional | Visible failure detail outside the collapsed payload |
| `input` | `ToolCallPayload` | optional | Complete pre-serialized, redacted payload; language defaults to text |
| `output` | `ToolCallPayload` | optional | Complete pre-serialized, redacted payload; language defaults to text |
| `disclosureConfig` | `ActivityDisclosureConfig` | optional | Payload starts closed and remains independent of execution |
| `className` | `string` | optional | Layout override |

### input fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes | Complete, pre-serialized text. Redaction and safe serialization belong to the host. |
| `language` | `string` | No |  |
| `filename` | `string` | No |  |

### output fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Yes | Complete, pre-serialized text. Redaction and safe serialization belong to the host. |
| `language` | `string` | No |  |
| `filename` | `string` | No |  |

### disclosureConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | No |  |
| `defaultOpen` | `boolean` | No |  |
| `onOpenChange` | `((open: boolean) => void)` | No |  |

## Design rules [#design-rules]

- **TOOLCALL-01:** Figma 600:180: Label12 pearl800 with a 12px tool glyph and 6px gap. Failure retains the tool glyph and adds a red800 “Failed to” prefix.
- **TOOLCALL-02:** Only payload-bearing rows are disclosure buttons. The chevron is 12px and payload CodeBlocks are indented 18px; complete code scrolls horizontally.
- **TOOLCALL-03:** The host executes and retries tools, serializes values, and removes secrets. The component never executes tools or parses payloads. Errors remain visible when collapsed.
- **TOOLCALL-04:** Name verbs follow Figma: list → check, get → look up; search/create/update/add/set/remove/post/assign retain their verbs. Unknown verbs use run. Override label for localized/domain copy. Disclosure is independent of lifecycle.

## Accessibility and integration [#accessibility-and-integration]

Disclosure buttons support Enter and Space, preserve focus, and expose `aria-expanded`. Payload copy buttons are outside the disclosure trigger. Pointer disclosure uses the existing 200ms height transition; keyboard and reduced-motion interaction are immediate. Long text wraps while code scrolls inside its own region. Use one meaningful ThinkingIndicator status per active response rather than announcing every streamed token or tool payload.

The application owns requests, cancellation, approval, retries, durations, and history persistence. No AI SDK provider is required. See [AI content integration](/docs/guides/ai-content) for migration mappings; consumer migration is outside this phase.


---

# Tooltip

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tooltip
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=252-57

```tsx
import { Tooltip, TooltipProvider } from '@commenda/pathfinder/tooltip';
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Download01Icon } from '@commenda/pathfinder/icons/Download01Icon';
<TooltipProvider>
  <Tooltip
    content="Download receipt"
    trigger={
      <IconButton label="Download receipt" tooltip={false}>
        <Download01Icon />
      </IconButton>
    }
  />
</TooltipProvider>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Tooltip, TooltipProvider } from '@commenda/pathfinder/tooltip';
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Download01Icon } from '@commenda/pathfinder/icons/Download01Icon';
<TooltipProvider>
  <Tooltip
    content="Download receipt"
    trigger={
      <IconButton label="Download receipt" tooltip={false}>
        <Download01Icon />
      </IconButton>
    }
  />
</TooltipProvider>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `trigger` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | required | Required; must forward its ref and event props |
| `content` | `string` | required | Required noninteractive text |
| `title` | `string` | optional | Optional title and shortcut chip |
| `shortcut` | `string` | optional | Optional title and shortcut chip |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | optional | top; collision-aware |
| `align` | `"start" \| "end" \| "center"` | optional | center |
| `showArrow` | `boolean` | optional | false |
| `sideOffset` | `number` | optional | 6; 11 with arrow |
| `disabled` | `boolean` | optional | Disables the tooltip, not its trigger |
| `open` | `boolean` | conditional | Controlled / uncontrolled visibility |
| `defaultOpen` | `boolean` | optional | Controlled / uncontrolled visibility |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Required with open |
| `portalContainer` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | optional | Optional portal destination |

Mount TooltipProvider once per region for the 300 ms neighbor window. Hover opens after 100 ms; keyboard focus opens immediately. Escape closes it, and the pointer can move onto its content. Give the trigger its own accessible name. When wrapping IconButton, set tooltip={false} to avoid two hints. Use adjacent help for essential information and disabled reasons.

## Examples [#examples]

### Title [#title]


```tsx
<Tooltip
  title="Filing receipt"
  content="Download receipt"
  trigger={
    <IconButton label="Download receipt" tooltip={false}>
      <Download01Icon />
    </IconButton>
  }
/>;
```


### Shortcut [#shortcut]


```tsx
<Tooltip
  content="Download receipt"
  shortcut="⌘D"
  trigger={
    <IconButton label="Download receipt" tooltip={false}>
      <Download01Icon />
    </IconButton>
  }
/>;
```


### Placement [#placement]


```tsx
<>
  {(['top', 'bottom', 'left', 'right'] as const).map((side) => (
    <Tooltip
      key={side}
      side={side}
      showArrow
      content="Download receipt"
      trigger={
        <IconButton label="Download receipt" tooltip={false}>
          <Download01Icon />
        </IconButton>
      }
    />
  ))}
</>;
```


Read the [design guidance](/docs/components/tooltip#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Tooltip — 252:57 [#tooltip--25257]

- **TOOLTIP-01:** Supplemental, noninteractive text only. Essential instructions, errors, validation and required steps stay on the page. Links and buttons belong in Popover.
- **TOOLTIP-02:** Open after 100 ms hover, immediately on keyboard focus or for a neighboring tooltip within 300 ms. Use TooltipProvider around a region. Escape closes; the pointer can enter the popup without closing it. Open for as long as hover or focus remains.
- **TOOLTIP-03:** Icon-only controls need an accessible name that matches their tooltip. Do not repeat an already visible label. Field help uses a separate info control beside its label. Shortcut chips supplement another discoverable shortcut reference.
- **TOOLTIP-04:** Plain copy: sentence case, no period, ideally one line. Titles explain a metric or status. More than two lines belongs on the page. Pearl 1000, white Copy/12, 6 px radius, 8/12 px padding, menu elevation; 240 px maximum width, 320 with a title. Title/body gap 2; shortcut gap 8, chip height 16, pearl 900, radius 4. Arrow 10×5, off by default. Top placement flips as space requires; offsets 6 or 11 with arrow.


---

# Tree

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tree
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=818-2

```tsx
import { useState } from 'react';

import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { Tree, type TreeNode } from '@commenda/pathfinder/tree';

const documentNodes: TreeNode[] = [
  {
    kind: 'branch',
    id: 'entity',
    label: 'Commenda Technologies Inc.',
    icon: <USFlag size={16} />,
    children: {
      status: 'loaded',
      nodes: [
        {
          kind: 'branch',
          id: 'formation',
          label: 'Formation',
          children: {
            status: 'loaded',
            nodes: [
              {
                kind: 'leaf',
                id: 'certificate',
                label: 'Certificate of incorporation.pdf',
                icon: <FilePdfIcon size={16} />,
              },
              {
                kind: 'leaf',
                id: 'bylaws',
                label: 'Bylaws.pdf',
                icon: <FilePdfIcon size={16} />,
              },
            ],
          },
        },
        {
          kind: 'branch',
          id: 'tax',
          label: 'Tax',
          count: 12,
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'payroll',
          label: 'Payroll',
          count: 4,
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'ownership',
          label: 'Ownership',
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'board',
          label: 'Board minutes',
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'contracts',
          label: 'Contracts',
          children: { status: 'loading' },
        },
      ],
    },
  },
];

export const TreeDefault = () => {
  const [selected, setSelected] = useState<string | null>('payroll');
  const [message, setMessage] = useState('');

  return (
    <div style={{ width: 256, maxWidth: '100%' }}>
      <Tree
        label="Entity documents"
        nodes={documentNodes}
        selectionConfig={{ value: selected, onValueChange: setSelected }}
        expansionConfig={{
          defaultValue: ['entity', 'formation', 'board', 'contracts'],
        }}
        onCreateFolder={(id) => {
          setMessage(`Create folder under ${id}`);
        }}
        menuConfig={(node) => ({
          groups: [
            {
              id: 'item',
              items: [
                {
                  type: 'action',
                  id: 'rename',
                  label: 'Rename',
                  onClick: () => {
                    setMessage(`Rename ${node.label}`);
                  },
                },
              ],
            },
          ],
        })}
      />
      <output>{message}</output>
    </div>
  );
};
```


Import `Tree` and its types from `@commenda/pathfinder/tree`.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `label` | `string` | required | Required tree name |
| `nodes` | `readonly TreeNode[]` | required | Globally unique IDs, acyclic immutable data |
| `selectionConfig` | `SelectionProps<string \| null>` | optional | Controlled value/onValueChange or defaultValue; single selection |
| `expansionConfig` | `SelectionProps<readonly string[]>` | optional | Controlled/default expanded branch IDs |
| `onLoadChildren` | `((id: string) => void)` | optional | App request when an unloaded branch opens or error retries |
| `menuConfig` | `((node: TreeNode) => DropdownMenu)` | optional | App actions appended after built-in tree actions |
| `onCreateFolder` | `((parentId: string) => void)` | optional | Enables New folder control and menu action |
| `moveConfig` | `TreeMoveConfig` | optional | Enables pointer dragging, Move menu and keyboard move dialog |
| `emptyContent` | `ReactNode` | optional | Defaults to No items |
| `className` | `string` | optional | Root wrapper classes |

### selectionConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string \| null` | Yes |  |
| `onValueChange` | `(value: string \| null) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| null` | No |  |
| `onValueChange` | `((value: string \| null) => void)` | No |  |

Do not supply: `value`.

### expansionConfig fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `readonly string[]` | Yes |  |
| `onValueChange` | `(value: readonly string[]) => void` | Yes |  |

Do not supply: `defaultValue`.

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultValue` | `readonly string[]` | No |  |
| `onValueChange` | `((value: readonly string[]) => void)` | No |  |

Do not supply: `value`.

### moveConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `canMove` | `(request: TreeMove) => boolean` | Yes |  |
| `onMove` | `(request: TreeMove) => void \| Promise<void>` | Yes |  |

Every node has `id`, `label`, optional `icon`, `count`, and `disabled`. A leaf has `kind: 'leaf'`. A branch has `kind: 'branch'` and explicit `children`:

```ts
// Undefined does not mean an empty folder.
type TreeChildren =
  | { status: 'unloaded' | 'loading' }
  | { status: 'loaded'; nodes: readonly TreeNode[] }
  | { status: 'error'; message?: string };
```

Entity roots use flags. Branches default to the exact open/closed Folder artwork; pass a matching FileType icon for files. The component preserves labels for assistive technology and exposes the full truncated label on hover. Duplicate/empty IDs render a clear error instead of creating unstable navigation.

## Loading and retry [#loading-and-retry]


```tsx
import { useEffect, useRef, useState } from 'react';

import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { Tree, type TreeNode } from '@commenda/pathfinder/tree';

export const TreeAsync = () => {
  const [nodes, setNodes] = useState<TreeNode[]>([
    {
      kind: 'branch',
      id: 'remote',
      label: 'Archived contracts',
      children: { status: 'unloaded' },
    },
  ]);
  const attempts = useRef(0);
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
  useEffect(
    () => () => {
      if (timer.current) clearTimeout(timer.current);
    },
    []
  );

  return (
    <Tree
      label="Remote documents"
      nodes={nodes}
      onLoadChildren={() => {
        attempts.current += 1;
        setNodes([
          {
            kind: 'branch',
            id: 'remote',
            label: 'Archived contracts',
            children: { status: 'loading' },
          },
        ]);
        timer.current = setTimeout(() => {
          setNodes([
            {
              kind: 'branch',
              id: 'remote',
              label: 'Archived contracts',
              children:
                attempts.current === 1
                  ? { status: 'error', message: 'Couldn’t load this folder' }
                  : {
                      status: 'loaded',
                      nodes: [
                        {
                          kind: 'leaf',
                          id: 'contract',
                          label: 'Signed contract.pdf',
                          icon: <FilePdfIcon size={16} />,
                        },
                      ],
                    },
            },
          ]);
        }, 500);
      }}
    />
  );
};
```


The example deliberately fails its first request. Retry succeeds. The app owns fetching, cancellation and replacing nodes; mark loading while pending, distinguish loaded-empty from unloaded, and supply readable failures. Known ancestor paths are revealed for a newly selected node; callers must provide expansion IDs for ancestors that have not been loaded yet.

## Moving items [#moving-items]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { Tree, type TreeMove, type TreeNode } from '@commenda/pathfinder/tree';

const relocateNodes = (
  nodes: readonly TreeNode[],
  request: TreeMove
): TreeNode[] => {
  let source: TreeNode | undefined;

  const remove = (items: readonly TreeNode[]): TreeNode[] =>
    items.flatMap((node) => {
      if (node.id === request.sourceId) {
        source = node;

        return [];
      }

      return node.kind === 'branch' && node.children.status === 'loaded'
        ? [
            {
              ...node,
              children: {
                status: 'loaded',
                nodes: remove(node.children.nodes),
              },
            },
          ]
        : [node];
    });

  const remaining = remove(nodes);
  if (!source) return [...nodes];
  const moved = source;

  const insert = (items: readonly TreeNode[]): TreeNode[] =>
    items.flatMap((node) => {
      if (node.id === request.targetId) {
        if (request.position === 'before') return [moved, node];
        if (request.position === 'after') return [node, moved];
        if (node.kind === 'branch' && node.children.status === 'loaded')
          return [
            {
              ...node,
              children: {
                status: 'loaded',
                nodes: [...node.children.nodes, moved],
              },
            },
          ];
      }

      return node.kind === 'branch' && node.children.status === 'loaded'
        ? [
            {
              ...node,
              children: {
                status: 'loaded',
                nodes: insert(node.children.nodes),
              },
            },
          ]
        : [node];
    });

  return insert(remaining);
};

export const TreeMoving = () => {
  const [nodes, setNodes] = useState<TreeNode[]>([
    {
      kind: 'branch',
      id: 'source',
      label: 'Formation',
      children: {
        status: 'loaded',
        nodes: [
          {
            kind: 'leaf',
            id: 'certificate',
            label: 'Certificate.pdf',
            icon: <FilePdfIcon size={16} />,
          },
        ],
      },
    },
    {
      kind: 'branch',
      id: 'destination',
      label: 'Tax',
      children: { status: 'loaded', nodes: [] },
    },
  ]);
  const [fail, setFail] = useState(false);

  return (
    <>
      <p>Drag a row, choose Move from its menu, or press Ctrl/⌘ + Shift + M.</p>
      <Button
        variant="tertiary"
        onClick={() => {
          setFail(!fail);
        }}
      >
        {fail ? 'Simulating API failure' : 'Simulate API failure'}
      </Button>
      <Tree
        label="Movable documents"
        nodes={nodes}
        expansionConfig={{ defaultValue: ['source', 'destination'] }}
        moveConfig={{
          canMove: () => true,
          onMove: (request) => {
            if (fail) return Promise.reject(new Error('Example API failure'));
            setNodes((current) => relocateNodes(current, request));
          },
        }}
      />
    </>
  );
};
```


`TreeMove` is `{ sourceId, targetId, position: 'before' | 'after' | 'inside' }`. Self and descendant targets are always rejected; inside requires a branch. `canMove` adds application permission and business rules and must be pure. `onMove` returns void or a promise; the application updates `nodes` only after accepting the change. No optimistic data mutation occurs inside Tree. Pending requests cannot duplicate; rejection keeps the dialog open and announces an error for retry.

Pointer drop zones are the top quarter (before), middle half (inside), and bottom quarter (after). Invalid targets do not accept drops. Touch or keyboard users choose Move from the menu and select a destination/placement. `Ctrl/⌘ + Shift + M` opens the same move dialog for the focused item; `Shift + F10` or the context-menu key opens its actions. The example includes an API-failure toggle.

## Keyboard [#keyboard]

Focus is separate from selection. Up/Down move among visible nodes; Right expands or enters children, Left collapses or returns to parent (mirrored in RTL); Home/End jump to edges; typing finds matching names. Enter/Space selects. Chevron activation expands without selecting. Row actions remain discoverable on focus/touch, and the menu includes New folder/Retry/Move alternatives. Removing the focused row recovers focus to a surviving tree item.

## Scope deep folders [#scope-deep-folders]


```tsx
import { useState } from 'react';

import { Button } from '@commenda/pathfinder/button';
import { FilePdfIcon } from '@commenda/pathfinder/file-types/FilePdfIcon';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';
import { Tree, type TreeNode } from '@commenda/pathfinder/tree';

const documentNodes: TreeNode[] = [
  {
    kind: 'branch',
    id: 'entity',
    label: 'Commenda Technologies Inc.',
    icon: <USFlag size={16} />,
    children: {
      status: 'loaded',
      nodes: [
        {
          kind: 'branch',
          id: 'formation',
          label: 'Formation',
          children: {
            status: 'loaded',
            nodes: [
              {
                kind: 'leaf',
                id: 'certificate',
                label: 'Certificate of incorporation.pdf',
                icon: <FilePdfIcon size={16} />,
              },
              {
                kind: 'leaf',
                id: 'bylaws',
                label: 'Bylaws.pdf',
                icon: <FilePdfIcon size={16} />,
              },
            ],
          },
        },
        {
          kind: 'branch',
          id: 'tax',
          label: 'Tax',
          count: 12,
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'payroll',
          label: 'Payroll',
          count: 4,
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'ownership',
          label: 'Ownership',
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'board',
          label: 'Board minutes',
          children: { status: 'loaded', nodes: [] },
        },
        {
          kind: 'branch',
          id: 'contracts',
          label: 'Contracts',
          children: { status: 'loading' },
        },
      ],
    },
  },
];

export const TreeScoped = () => {
  const [scope, setScope] = useState<TreeNode | null>(null);
  const nodes =
    scope?.kind === 'branch' && scope.children.status === 'loaded'
      ? scope.children.nodes
      : documentNodes;

  return (
    <>
      <nav aria-label="Folder scope">
        <Button
          variant="link"
          onClick={() => {
            setScope(null);
          }}
        >
          All documents
        </Button>
        {scope && <span> / {scope.label}</span>}
      </nav>
      <Tree
        key={scope?.id ?? 'all'}
        label={scope ? `${scope.label} contents` : 'All documents'}
        nodes={nodes}
        expansionConfig={{ defaultValue: ['entity', 'formation'] }}
        menuConfig={(node) => ({
          groups:
            node.kind === 'branch' && node.children.status === 'loaded'
              ? [
                  {
                    id: 'scope',
                    items: [
                      {
                        id: 'focus',
                        type: 'action',
                        label: 'Focus this folder',
                        onClick: () => {
                          setScope(node);
                        },
                      },
                    ],
                  },
                ]
              : [],
        })}
      />
    </>
  );
};
```


Use Focus this folder to show a subtree and a return path. Tree accepts arbitrary depth but caps visual indentation after four levels to keep labels usable in narrow panels; `aria-level` and hierarchy remain accurate. Prefer scoped browsing for deeper structures and load large branches incrementally. The stress fixture covers 1,000 rendered leaves; it is not a virtualization or unbounded-scale guarantee. Read the [hierarchy rules](/docs/components/tree#design-rules).

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Tree [#tree]

- **TREE-001:** Rows 28px, radius 6, horizontal inset 8 and gap 6, indent 16 per visual level; 12px chevron in a reserved 16px slot even on leaves. Exact Folder artwork, flags at entity roots, file-type icons for files, Label/13, optional count; New folder/More on hover, focus and touch. Hover pearl200, selected pearl300 without a weight change, drop target blue100/blue600.
- **TREE-002:** Semantic nested treeitem/group hierarchy and one roving row tab stop. Focus is independent from selection; arrows, Home/End, typeahead and Enter/Space work. RTL mirrors expand/collapse arrows. Full accessible labels preserve truncated text. Loaded selected ancestors reveal; app supplies unknown remote ancestors. Removal recovers focus.
- **TREE-003:** Explicit unloaded/loading/loaded/error states. Empty folder is not an unknown folder. Loading uses a skeleton/status; errors have Retry and a keyboard menu alternative. API requests, cancellation and immutable data replacement are app-owned.
- **TREE-004:** Every move uses the same validation: no self, no descendant, inside only a branch, then application canMove. Drag before/inside/after, menu Move and Ctrl/⌘+Shift+M share one commit path. The app updates data after success; duplicate pending moves are blocked; failure is announced and retryable. Permissions must also be enforced by the application/API.

### Scale and scope [#scale-and-scope]

Do not silently remove deep nodes. Keep semantic depth accurate; visual indentation stops growing after four levels. Compose a focused subtree with a return/breadcrumb path for deeper work. Load large folders incrementally; this component does not promise virtualization. Keep worst-case fixtures in Storybook, not enterprise. Test long non-Latin names, huge counts, empty/single/large branches, disabled nodes, data replacement, RTL, keyboard and pointer moves, and async rejection.

### Reviewed accessibility and geometry adjustments [#reviewed-accessibility-and-geometry-adjustments]

Tree prose describes a 4px inset, while the reviewed item 818:274 uses 8px horizontal padding and a 6px gap. The implementation follows the component and the full tree 820:211, including its root spacer and 2px row gaps.

### Explicit differences and boundaries [#explicit-differences-and-boundaries]

| Reference                                                                                                 | Coverage                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Cell master 430:13537](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=430-13537) | Text/description/icon/badge, people/groups/email, entities, files, tags, boolean, progress, copy/link, numbers/units/currency/trends, loading and totals compose TableCell, TableNumberCell and TableRowActions. Tree parent/child/grandchild behavior belongs to the recursive DataGrid examples. Hover and selection share the row tint in both densities. |


---

# Upload request card

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/upload-request-card
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=607-4714

```tsx
import { UploadRequestCard } from '@commenda/pathfinder/upload-request-card';

<UploadRequestCard
  key={request.id}
  title="Upload the signed documents"
  uploadConfig={{ accept: '.pdf', onFilesSelected: validateAndUpload }}
  attachmentConfig={{
    items: attachments,
    onRemove: removeAttachment,
    onRetry: retryUpload,
  }}
  onSubmit={submitDocumentIds}
/>;
```


## Usage [#usage]

```tsx
import { UploadRequestCard } from '@commenda/pathfinder/upload-request-card';

<UploadRequestCard
  key={request.id}
  title="Upload the signed documents"
  uploadConfig={{ accept: '.pdf', onFilesSelected: validateAndUpload }}
  attachmentConfig={{
    items: attachments,
    onRemove: removeAttachment,
    onRetry: retryUpload,
  }}
  onSubmit={submitDocumentIds}
/>;
```

## Share an upload link [#share-an-upload-link]


```tsx
import { UploadRequestCard } from '@commenda/pathfinder/upload-request-card';

<UploadRequestCard
  linkConfig={{ url: uploadUrl }}
  key={request.id}
  title="Upload the signed documents"
  uploadConfig={{ accept: '.pdf', onFilesSelected: validateAndUpload }}
  attachmentConfig={{
    items: attachments,
    onRemove: removeAttachment,
    onRetry: retryUpload,
  }}
  onSubmit={submitDocumentIds}
/>;
```


## Inline request [#inline-request]


```tsx
import { UploadRequestCard } from '@commenda/pathfinder/upload-request-card';

<UploadRequestCard
  placement="inline"
  key={request.id}
  title="Upload the signed documents"
  uploadConfig={{ accept: '.pdf', onFilesSelected: validateAndUpload }}
  attachmentConfig={{
    items: attachments,
    onRemove: removeAttachment,
    onRetry: retryUpload,
  }}
  onSubmit={submitDocumentIds}
/>;
```


## Failure and retry [#failure-and-retry]


```tsx
// Return { status: 'failed', message: 'Please try again.' } from the handler to retain this card.
import { UploadRequestCard } from '@commenda/pathfinder/upload-request-card';

<UploadRequestCard
  key={request.id}
  title="Upload the signed documents"
  uploadConfig={{ accept: '.pdf', onFilesSelected: validateAndUpload }}
  attachmentConfig={{
    items: attachments,
    onRemove: removeAttachment,
    onRetry: retryUpload,
  }}
  onSubmit={submitDocumentIds}
/>;
```


## Loading [#loading]


```tsx
import { UploadRequestCard } from '@commenda/pathfinder/upload-request-card';

<UploadRequestCard
  state={{ status: 'loading' }}
  key={request.id}
  title="Upload the signed documents"
  uploadConfig={{ accept: '.pdf', onFilesSelected: validateAndUpload }}
  attachmentConfig={{
    items: attachments,
    onRemove: removeAttachment,
    onRetry: retryUpload,
  }}
  onSubmit={submitDocumentIds}
/>;
```


Reset restores the example. Simulate failure retains the card for retry; no backend request is made.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `uploadConfig` | `RequestUploadConfig` | required | Native picker/drop events; default multiple true; callback receives `readonly File[]` |
| `attachmentConfig` | `Omit<AttachmentGroupProps, "className" \| "align">` | required | Stable uploaded file IDs and ready/uploading/failed state; remove, preview, retry callbacks |
| `onSubmit` | `RequestHandler<readonly string[]>` | required | Sends attachment IDs only, after all files are ready |
| `onSkip` | `RequestHandler` | optional | Optional explicit skip |
| `linkConfig` | `{ url: string; description?: string; }` | optional | Optional app-issued upload link and copy control |
| `title` | `string` | required |  |
| `description` | `string` | optional | Supporting guidance associated with the field. |
| `placement` | `"docked" \| "inline"` | optional |  |
| `state` | `RequestState` | optional |  |
| `onDismiss` | `(() => void)` | optional |  |
| `className` | `string` | optional | Additional classes for the component root. |

### uploadConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accept` | `string` | No | Browser hint only. Validate types, size, permissions and scan files on the server. |
| `multiple` | `boolean` | No |  |
| `description` | `string` | No |  |
| `onFilesSelected` | `(files: readonly File[]) => void` | Yes |  |

### attachmentConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `readonly AttachmentItem[]` | Yes |  |
| `maxRows` | `1 \| 2 \| 3` | No |  |
| `getPreview` | `((item: AttachmentItem) => AttachmentProps["previewConfig"])` | No |  |
| `label` | `string` | No |  |
| `onPreview` | `((item: AttachmentItem) => void)` | No |  |
| `onRetry` | `((item: AttachmentItem) => void)` | No |  |
| `onRemove` | `((item: AttachmentItem) => void)` | No |  |

### linkConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Yes |  |
| `description` | `string` | No |  |

### state fields

Choose one shape; excluded fields cannot be combined.

#### Option 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"ready" \| "pending" \| "loading"` | Yes |  |

#### Option 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"resolved"` | Yes |  |
| `recap` | `ResponseRecapProps` | Yes |  |

### Shared request props [#shared-request-props]

| Prop          | Type                   | Behavior                                                                 |
| ------------- | ---------------------- | ------------------------------------------------------------------------ |
| `title`       | `string`               | Required card title.                                                     |
| `description` | `string`               | Optional supporting text.                                                |
| `placement`   | `'docked' \| 'inline'` | Docked by default; parent controls width and placement                   |
| `state`       | `RequestState`         | Ready, loading skeleton, externally pending, or resolved with a recap    |
| `onDismiss`   | `() => void`           | Temporary dismissal via Not now or scoped Escape; not a submitted answer |
| `className`   | `string`               | Layout override                                                          |

`RequestHandler<T>` returns `{ status: 'accepted', recap: ResponseRecapProps }` or `{ status: 'failed', message: string }`, directly or as a Promise. A thrown error shows a retry message and preserves the draft. The host persists accepted responses; the component displays the returned receipt. `state={{ status: 'resolved', recap }}` restores history. Use a stable request ID as the React key, and change the key when the request changes. External pending is a rendering state; authorization and idempotency remain server responsibilities.

**REQUEST-01:** Docked tray uses pearl100, a raised shadow, radius16 and a white radius10 inset with 16px padding. Header40, footer at least44; controls wrap on narrow screens.

**REQUEST-02:** The parent places the request 12px above Composer at the same width. Inline requests are flat and fill their message column. Escape only temporarily dismisses; no global listener is installed.

**REQUEST-03:** Reading content does not animate. Existing Button and Popover motion respects reduced motion. Pending retains the draft and exposes a polite status. Acceptance never precedes the host result.

## Design rules [#design-rules]

- **UPLOAD-REQUEST-01:** The dropzone is at least 120px high, radius8, dashed pearl400. Existing AttachmentGroup renders files and overflow.
- **UPLOAD-REQUEST-02:** Send documents requires at least one file and every upload ready. Failed, uploading, and folder items block submission. Removing/retrying is blocked while submitting.
- **UPLOAD-REQUEST-03:** Selecting or dropping files never resolves the request. The host validates size/type/count, uploads, handles retries and cancellation, and returns stable IDs. `accept` is a browser hint, not validation; validate on the server too.

Pathfinder currently has no standalone FileUpload, so this phase adds a private native picker/dropzone rather than importing a private Kakashi runtime dependency. The demo keeps files in memory and makes no network request. Production code must mark them uploading until the server accepts them.

## Integration and accessibility [#integration-and-accessibility]

Buttons have explicit names and keyboard focus. No network transport or AI SDK provider is required. Requests, tool execution, permission checks, durable outcomes and composer coordination stay in the application. See [AI content integration](/docs/guides/ai-content) for migration mappings; application migration is outside this build.


---

# Documentation standards

Package: @commenda/pathfinder@0.1.0
Page: /docs/contributing/documentation

## Page structure [#page-structure]

Start with the component's purpose and one realistic working example. Follow with minimal usage, focused examples, API reference, behavior and accessibility, and relevant design guidance. Keep related components linked where the choice matters. Scale the length to the component: a separator needs less explanation than a data grid.

Use sentence case for headings and exact exported names in code. Explain state ownership and callback behavior. Describe what ships today. Keep internal Figma reconciliation, implementation history, test reports, and unresolved design questions in the repository's decision archive.

## Working examples [#working-examples]

Author complete starter examples in `packages/pathfinder/documentation/examples/<component>/`. Register their IDs in `manifest.json` and run `pnpm --filter @commenda/pathfinder generate:examples`. Their source is formatted and used by the rendered preview, Code tab, and Markdown reference. Source generation rejects private fixture imports. Existing navigation and field examples also generate source from their React implementations.

Focused usage snippets may omit application orchestration when the page explains it; they must be labeled as snippets. Never silently substitute another example's code. Missing example IDs fail the documentation build.

Keep stress switches, adversarial data, and test reset controls in Storybook. Documentation examples teach a specific capability. Simulated network operations must say they are simulated. Use subdued explanatory text and a separate action row for necessary demo controls.

## API reference [#api-reference]

`pnpm --filter @commenda/pathfinder-docs generate:api` extracts component-owned props from public TypeScript exports. `lib/api-notes.json` owns the written behavior/default guidance. Update those notes when behavior changes. Conditional requirements depend on modes, controlled state, or label configurations; the published type is authoritative for legal combinations. Native and library-inherited props remain defined by the exported type.

Use `ApiReference` for generated component APIs and ordinary Markdown tables for comparison or design guidance. Keep types readable: long types expand on demand. Do not invent defaults from TypeScript optionality.

## Navigation and links [#navigation-and-links]

`lib/documentation-catalog.json` owns component categories and Figma links. Run `pnpm --filter @commenda/pathfinder-docs generate:navigation` after changes. Generated metadata supplies Fumadocs navigation without runtime regrouping. Keep existing page URLs stable.

## AI reference [#ai-reference]

The MDX transformer exports examples and API tables as Markdown without replacing their live HTML components. Human and AI docs share the same source. The index is available at [llms.txt](/llms.txt), with a [full reference](/llms-full.txt). Stable design-rule IDs stay with their relevant component; internal conflict history lives in the repository archive.

## Verification [#verification]

Run Pathfinder lint, tests, and types; regenerate/check examples, navigation, and API data; build Fumadocs and Storybook. Check source links, rendered tables, keyboard tabs, copy behavior, narrow screens, and accessibility. Review a simple, stateful, and complex page. Test evidence records the browser and limits of coverage.

## Object props and unions [#object-props-and-unions]

Use one prop per row, with separate Type and Behavior columns. Do not group independent props or combine prose and type signatures in a single cell.

The generated API reference links object props to field disclosures. Each shape lists its fields and requirements; excluded fields describe mutually exclusive alternatives. Use the exported TypeScript declarations for the complete signature; do not repeat a type-alias name in a definition disclosure. Native/third-party types remain opaque; the generator only expands package-owned objects, to three levels. Document array element models and deeper recursive structures explicitly on the owning component page, as Dropdown does.

Add prose examples for meaningful choices. For example, `labelConfig={{ optionalLabel: 'Optional' }}` and `labelConfig={{ help: 'Use the legal entity name' }}` are alternatives; do not combine them. Never invent an exported type name for an anonymous object. Defaults come from reviewed behavior notes, not TypeScript optionality.

## Source formatting [#source-formatting]

Follow [Formatting and linting](/docs/contributing/formatting) for spacing, imports, generators, and editor setup. Run `pnpm pathfinder:format` before the documentation verification commands.


---

# Formatting and linting

Package: @commenda/pathfinder@0.1.0
Page: /docs/contributing/formatting

## Commands [#commands]

Run these from the repository root:

```sh
# Fix ESLint findings, then apply Prettier.
pnpm pathfinder:format

# Check formatting without changing files.
pnpm pathfinder:format:check

# Check spacing, imports, types, hooks, and accessibility.
pnpm pathfinder:lint

# Run the complete package verification.
pnpm pathfinder:check
```

The root formatting command also refreshes generated example source and API metadata after fixing source files. The fast formatting pass runs only spacing and import rules without constructing a TypeScript program. Full type-aware lint remains a required separate gate; use the workspace `lint:fix` command for other autofixable lint findings. The commands cover `packages/pathfinder` and `apps/pathfinder-docs`. They do not reformat other applications. Prettier 3.6.2 is pinned in both workspaces. CI checks formatting separately from ESLint; formatting errors do not run through an ESLint Prettier plugin.

The package and docs `lint` and `lint:fix` commands give ESLint a 4 GB JavaScript heap limit for type-aware analysis. This avoids the roughly 2 GB default heap limit on CI runners without disabling rules or excluding source files. `pathfinder:ci` runs heavy tasks sequentially to bound total memory use.

## Formatting conventions [#formatting-conventions]

Prettier owns indentation, wrapping, punctuation, and repeated empty lines. The scoped configs inherit the repository's 80-column target, two-space indentation, single JS/TS quotes, JSX double quotes, semicolons, ES5 trailing commas, parentheses around arrow parameters, and LF endings. Line width is a target, not a hard limit for strings or import paths.

Prettier preserves a single blank line between logical groups, collapses repeated blank lines, removes empty lines at block boundaries, and ends each file with one newline. Avoid manual alignment or line-length lint rules that compete with the formatter.

Pathfinder disables the root Prettier plugins. Import organization belongs to ESLint; source formatting does not delete imports or reorder Tailwind classes. Tailwind class sorting would require a separate configuration using the package's v4 stylesheet and generated tokens.

## Blank lines [#blank-lines]

ESLint enforces one blank line:

- After directives such as `'use client'` and after the import block.
- Before and after type aliases, interfaces, functions, and classes, including exported declarations.
- Before and after variables initialized directly with an arrow function or function expression, including exported components.
- Before a `return` when another statement precedes it in the same block.

Related constants and hook calls may remain consecutive. Simple object/type fields and JSX children do not require artificial blank lines. A return-only function does not need a blank line after its opening brace.

```tsx
type Option = {
  id: string;
  label: string;
};

const getLabels = (options: readonly Option[]) => {
  const labels = options.map((option) => option.label);
  const uniqueLabels = new Set(labels);

  return [...uniqueLabels];
};
```

Spacing around function wrappers such as `memo(...)` remains an authoring choice; the automatic function-variable rule matches direct function initializers. Function overload signatures remain together.

## Imports [#imports]

ESLint sorts imports into these groups, separated by blank lines:

1. Side-effect imports, preserving their relative order.
2. Node built-ins and external packages.
3. Workspace packages under `@commenda/`.
4. Internal absolute aliases (`@/` and `~/`).
5. Relative imports.

Type imports follow the existing `consistent-type-imports` rule. Unused imports are checked by ESLint. Handwritten export barrels are not automatically reordered. Generated barrels are sorted by their generator. Keep stylesheet override imports in their intended relative order; the import sorter moves the side-effect group before named imports, so modules with initialization dependencies must be reviewed when applying fixes.

## Generated files and examples [#generated-files-and-examples]

Edit SVG sources, inventories, example TSX, or generator scripts rather than generated React components. TypeScript generators use the shared spacing/import formatter followed by the same Prettier configuration, so generator checks and formatting checks agree. Generated source stays checked; build output, raw assets, public files, and isolated consumer fixtures are excluded from broad formatting.

After editing example source, run the affected generator:

```sh
pnpm --filter @commenda/pathfinder generate:examples
pnpm --filter @commenda/pathfinder-docs generate:api
pnpm --filter @commenda/pathfinder-docs generate:navigation
```

Documentation display formatting preserves teaching-only imports and uses the same whitespace conventions. Component snippets may be incomplete intentionally; the docs renderer never runs unused-import fixes on them.

## Editor setup [#editor-setup]

Select Prettier as the formatter for these workspaces and use their local ESLint 9 installation. In VS Code, add the two directories to `eslint.workingDirectories` alongside any existing workspace entries. Enable format on save and `source.fixAll.eslint` for explicit saves. The CLI runs ESLint before Prettier and is the authoritative check when editor save actions differ.

Keep the repository's other applications on their existing tooling. Do not add global editor settings or repository-wide save actions just for Pathfinder.

## References [#references]

- [Prettier's treatment of blank lines](https://prettier.io/docs/rationale#empty-lines)
- [Prettier and linters](https://prettier.io/docs/integrating-with-linters)
- [ESLint Stylistic statement spacing](https://eslint.style/rules/padding-line-between-statements)
- [Import sorting and side effects](https://github.com/lydell/eslint-plugin-simple-import-sort)


---

# Color reference

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/color-reference

Choose a scale by its role, then check the foreground and background together. Each swatch below uses the actual exported color.

100–300 are fills; 400–600 are borders; 700–800 are solid fills; 900–1000 are text and icons. Check contrast for the actual foreground/background pair. Amber and orange solid fills require dark text; a scale step alone does not guarantee accessible contrast.

`--pf-color-background-subtle` aliases Soft Pearl 100. Dark values are not defined yet.

## Background surfaces [#background-surfaces]

<ColorPalette scale="background" />

Use white for surfaces and Soft Pearl 100 for a subtle canvas. Keep text outside decorative swatches so the reference stays readable.

## Soft pearl [#soft-pearl]

<ColorPalette scale="soft-pearl" />

<details>
<summary>Token values and CSS variables</summary>

| Token           | CSS variable                 | Hex       |
| --------------- | ---------------------------- | --------- |
| soft-pearl-100  | `--pf-color-soft-pearl-100`  | `#fcfbf8` |
| soft-pearl-200  | `--pf-color-soft-pearl-200`  | `#f8f6f1` |
| soft-pearl-300  | `--pf-color-soft-pearl-300`  | `#edeae3` |
| soft-pearl-400  | `--pf-color-soft-pearl-400`  | `#dedbd4` |
| soft-pearl-500  | `--pf-color-soft-pearl-500`  | `#c8c4be` |
| soft-pearl-600  | `--pf-color-soft-pearl-600`  | `#a6a29c` |
| soft-pearl-700  | `--pf-color-soft-pearl-700`  | `#8f8b85` |
| soft-pearl-800  | `--pf-color-soft-pearl-800`  | `#6d6963` |
| soft-pearl-900  | `--pf-color-soft-pearl-900`  | `#57524d` |
| soft-pearl-1000 | `--pf-color-soft-pearl-1000` | `#14120f` |

</details>

## Blue [#blue]

<ColorPalette scale="blue" />

<details>
<summary>Token values and CSS variables</summary>

| Token     | CSS variable           | Hex       |
| --------- | ---------------------- | --------- |
| blue-100  | `--pf-color-blue-100`  | `#f1f8ff` |
| blue-200  | `--pf-color-blue-200`  | `#e5f2ff` |
| blue-300  | `--pf-color-blue-300`  | `#d4e9ff` |
| blue-400  | `--pf-color-blue-400`  | `#bcddff` |
| blue-500  | `--pf-color-blue-500`  | `#93c8fd` |
| blue-600  | `--pf-color-blue-600`  | `#63aaed` |
| blue-700  | `--pf-color-blue-700`  | `#026eb9` |
| blue-800  | `--pf-color-blue-800`  | `#005a9c` |
| blue-900  | `--pf-color-blue-900`  | `#014679` |
| blue-1000 | `--pf-color-blue-1000` | `#012543` |

</details>

## Red [#red]

<ColorPalette scale="red" />

<details>
<summary>Token values and CSS variables</summary>

| Token    | CSS variable          | Hex       |
| -------- | --------------------- | --------- |
| red-100  | `--pf-color-red-100`  | `#fff4f2` |
| red-200  | `--pf-color-red-200`  | `#feebe8` |
| red-300  | `--pf-color-red-300`  | `#feded8` |
| red-400  | `--pf-color-red-400`  | `#ffcbc2` |
| red-500  | `--pf-color-red-500`  | `#ffa99b` |
| red-600  | `--pf-color-red-600`  | `#f77a68` |
| red-700  | `--pf-color-red-700`  | `#c93829` |
| red-800  | `--pf-color-red-800`  | `#b01b0f` |
| red-900  | `--pf-color-red-900`  | `#920a02` |
| red-1000 | `--pf-color-red-1000` | `#520d07` |

</details>

## Amber [#amber]

<ColorPalette scale="amber" />

<details>
<summary>Token values and CSS variables</summary>

| Token      | CSS variable            | Hex       |
| ---------- | ----------------------- | --------- |
| amber-100  | `--pf-color-amber-100`  | `#fff5ed` |
| amber-200  | `--pf-color-amber-200`  | `#feedde` |
| amber-300  | `--pf-color-amber-300`  | `#fde0c8` |
| amber-400  | `--pf-color-amber-400`  | `#fbd0ab` |
| amber-500  | `--pf-color-amber-500`  | `#f1b47e` |
| amber-600  | `--pf-color-amber-600`  | `#de9145` |
| amber-700  | `--pf-color-amber-700`  | `#d87e09` |
| amber-800  | `--pf-color-amber-800`  | `#bb6c07` |
| amber-900  | `--pf-color-amber-900`  | `#864c02` |
| amber-1000 | `--pf-color-amber-1000` | `#452501` |

</details>

## Green [#green]

<ColorPalette scale="green" />

<details>
<summary>Token values and CSS variables</summary>

| Token      | CSS variable            | Hex       |
| ---------- | ----------------------- | --------- |
| green-100  | `--pf-color-green-100`  | `#f1f9f1` |
| green-200  | `--pf-color-green-200`  | `#e7f5e6` |
| green-300  | `--pf-color-green-300`  | `#d6eed6` |
| green-400  | `--pf-color-green-400`  | `#c1e4c0` |
| green-500  | `--pf-color-green-500`  | `#a0d29f` |
| green-600  | `--pf-color-green-600`  | `#75b876` |
| green-700  | `--pf-color-green-700`  | `#36863a` |
| green-800  | `--pf-color-green-800`  | `#1e7125` |
| green-900  | `--pf-color-green-900`  | `#0f5b18` |
| green-1000 | `--pf-color-green-1000` | `#0c320f` |

</details>

## Purple [#purple]

<ColorPalette scale="purple" />

<details>
<summary>Token values and CSS variables</summary>

| Token       | CSS variable             | Hex       |
| ----------- | ------------------------ | --------- |
| purple-100  | `--pf-color-purple-100`  | `#f9f5fe` |
| purple-200  | `--pf-color-purple-200`  | `#f5ecfc` |
| purple-300  | `--pf-color-purple-300`  | `#eee0fa` |
| purple-400  | `--pf-color-purple-400`  | `#e4cff7` |
| purple-500  | `--pf-color-purple-500`  | `#d3b4ec` |
| purple-600  | `--pf-color-purple-600`  | `#b991d8` |
| purple-700  | `--pf-color-purple-700`  | `#8c5eae` |
| purple-800  | `--pf-color-purple-800`  | `#774a98` |
| purple-900  | `--pf-color-purple-900`  | `#61397d` |
| purple-1000 | `--pf-color-purple-1000` | `#372147` |

</details>

## Rose [#rose]

<ColorPalette scale="rose" />

<details>
<summary>Token values and CSS variables</summary>

| Token     | CSS variable           | Hex       |
| --------- | ---------------------- | --------- |
| rose-100  | `--pf-color-rose-100`  | `#fff3f6` |
| rose-200  | `--pf-color-rose-200`  | `#ffeaef` |
| rose-300  | `--pf-color-rose-300`  | `#fedce4` |
| rose-400  | `--pf-color-rose-400`  | `#ffc8d5` |
| rose-500  | `--pf-color-rose-500`  | `#fda5bc` |
| rose-600  | `--pf-color-rose-600`  | `#eb7d9d` |
| rose-700  | `--pf-color-rose-700`  | `#ce507a` |
| rose-800  | `--pf-color-rose-800`  | `#b63966` |
| rose-900  | `--pf-color-rose-900`  | `#982b53` |
| rose-1000 | `--pf-color-rose-1000` | `#50152a` |

</details>

## Orange [#orange]

<ColorPalette scale="orange" />

<details>
<summary>Token values and CSS variables</summary>

| Token       | CSS variable             | Hex       |
| ----------- | ------------------------ | --------- |
| orange-100  | `--pf-color-orange-100`  | `#fff4f0` |
| orange-200  | `--pf-color-orange-200`  | `#feece4` |
| orange-300  | `--pf-color-orange-300`  | `#fedfd2` |
| orange-400  | `--pf-color-orange-400`  | `#ffccb7` |
| orange-500  | `--pf-color-orange-500`  | `#feab88` |
| orange-600  | `--pf-color-orange-600`  | `#f3804c` |
| orange-700  | `--pf-color-orange-700`  | `#ef6820` |
| orange-800  | `--pf-color-orange-800`  | `#d35502` |
| orange-900  | `--pf-color-orange-900`  | `#983b02` |
| orange-1000 | `--pf-color-orange-1000` | `#501b00` |

</details>

Background: `--pf-color-background: #ffffff`. Subtle: `--pf-color-background-subtle` → `--pf-color-soft-pearl-100`.

## Avatar tones [#avatar-tones]

Only for avatar initials; these are matched background/foreground pairs, not general-purpose status colors.

<ColorPalette avatars />

| Tone    | Background | Foreground |
| ------- | ---------- | ---------- |
| clay    | #fee0d8    | #804536    |
| apricot | #fae3d1    | #7a4b21    |
| ochre   | #f3e7ce    | #6e5414    |
| olive   | #e7ebd1    | #575d1f    |
| sage    | #d8efdc    | #31653e    |
| dusk    | #d5ebfe    | #2a5c84    |
| plum    | #f3e1f7    | #6d4875    |
| rose    | #fedfe2    | #80424d    |

CSS variables: `--pf-color-avatar-{tone}-bg` and `--pf-color-avatar-{tone}-fg`.

## Design guidance [#design-guidance]

Read [Design principles](/docs/foundations/design-rules) for shared usage guidance and motion recipes.

Source: [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System). Snapshot: 2026-10-12.


---

# Design principles

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/design-rules

Use these principles alongside the guidance on each component page.

## Source coverage [#source-coverage]

| Sheet                                                                                                  | Reviewed frame | Coverage here                                              |
| ------------------------------------------------------------------------------------------------------ | -------------- | ---------------------------------------------------------- |
| [Color](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=5-5)                    | `164:2`        | Scale jobs, neutral roles, contrast, avatars, migration    |
| [Typography](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=5-6)               | `165:2`        | Role selection, weights, leading, tracking, semantics      |
| [Spacing, radius and size](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=5-7) | `165:17`       | Spacing jobs, radius, controls, icons, widths, focus       |
| [Elevation and borders](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=5-8)    | `165:29`       | Surface recipes, border states, sticky edges               |
| [Motion](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=472-17719)             | `472:17720`    | Principles, presets, all 12 recipes, constants, exceptions |
| [Layout](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=237-2)                 | `238:2`        | Shell, grid, responsive policy, content and overlay widths |

Coverage is of the displayed foundation guidance. Historical usage counts, decorative example copy, and the referenced external `Color scales.oklch.json` file are not treated as implementation requirements; that JSON file was not retrieved. Values and visual examples are in the corresponding foundation reference pages.

## Color rules [#color-rules]

Source: [Color frame](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=164-2). Values: [Color reference](/docs/foundations/color-reference).

| ID       | Figma guidance                                                                                                                                                                                                                                                                           |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| COLOR-01 | Use eight ten-step scales plus background; background/subtle is an alias of Soft Pearl 100. The same names are intended for future dark values; dark values are not currently defined.                                                                                                   |
| COLOR-02 | Steps 100/200/300 are default/hover/active light fills. Steps 400/500/600 are default/hover/strong colored borders. Steps 700/800 are solid fill/hover. Steps 900/1000 are secondary/primary text and icons on light fills.                                                              |
| COLOR-03 | The scales were designed in OKLCH, but hex values ship in code and Figma. Contrast labels in Figma compare against white; 4.5 or greater is the sheet's normal-text threshold. Check the actual pair rather than inferring accessibility from the step.                                  |
| COLOR-04 | Blue is brand, links, focus and info; Red is error/destructive; Amber is warning; Green is success; Purple, Rose and Orange are accents. Amber and Orange solid fills take dark text; Amber 700 uses 1000 text.                                                                          |
| COLOR-05 | Avatar tones are matched fill/initial pairs, chosen from a stable user ID. Use them only for initials, not status colors. Figma describes these pairs as AA; verify the actual rendered text size and pair when implementing.                                                            |
| COLOR-06 | Use white background for cards, inputs, menus and dialogs; subtle for the chat conversation, sidebar and canvas around white cards.                                                                                                                                                      |
| COLOR-07 | Retire the old utility layer, fg/text split, cool-gray ramp, primary-hover-300 and irregular Soft Pearl 10/25/1050 steps. Info blue and indigo merge into Blue; violet becomes Purple. This is a migration direction, not an instruction to remove legacy application tokens in this PR. |
| COLOR-08 | Retired #EDECEB and #EAE7E0 merge into Soft Pearl 300 #EDEAE3. #F3F0E7 and #403B36 retire; dark fills use 1000. #FCFBF8 becomes 100. Disabled text moves from #B1ADA7 to 600 #A6A29C.                                                                                                    |

### Soft pearl jobs [#soft-pearl-jobs]

| Step | Intended use                              |
| ---- | ----------------------------------------- |
| 100  | Canvas behind cards                       |
| 200  | Row hover and table headers               |
| 300  | Hairlines, wells, tags and selected fills |
| 400  | Control borders and fill hover            |
| 500  | Border hover                              |
| 600  | Strong borders and disabled text          |
| 700  | Placeholders and quiet icons              |
| 800  | Tertiary/helper text                      |
| 900  | Secondary text and default icons          |
| 1000 | Primary text and tooltip fills            |

## Typography rules [#typography-rules]

Source: [Typography frame](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=165-2). Values: [Typography](/docs/foundations/typography).

| ID      | Figma guidance                                                                                                                                                                                                                                                                     |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TYPE-01 | Choose the job first: Heading for titles, Label for compact single-line controls/cells, Copy for wrapping content. The product has 17 Inter styles, replacing 33; Display leaves the product library.                                                                              |
| TYPE-02 | Use one Heading/24 page title. Heading/32 is for metrics and empty-state headlines; 20 for section/dialog titles; 18 for cards/panels; 15 for form blocks/sidebar groups.                                                                                                          |
| TYPE-03 | Label/15 is for large buttons/inputs and navigation; Label/13 is the product default for table cells, inputs, small/medium buttons, menus and tabs; Label/12 is for badges, headers, timestamps and single-line tooltips. Strong labels mark values, selections and button labels. |
| TYPE-04 | Copy/15 is for chat, dialog bodies and documents; Copy/13 for descriptions, help and multiline table cells; Copy/12 for helpers, multiline tooltips and footnotes. Strong Copy is inline emphasis.                                                                                 |
| TYPE-05 | Use only weights 400, 500 and 600. Heading is 600; Label Strong is 500; Copy Strong is 600. Text recipes carry no color: choose Soft Pearl 1000, 900 or 800 by role.                                                                                                               |
| TYPE-06 | Heading level follows document structure, never the font size. Tables and metrics use tabular figures.                                                                                                                                                                             |
| TYPE-07 | Label/13 uses 16px leading: small controls are 16 + 6 + 6 = 28px; medium controls are 16 + 8 + 8 = 32px. Control height follows leading and padding.                                                                                                                               |
| TYPE-08 | Tracking is 0 at 12/13px, −1% at 15px, −1.5% at 18/20px, −2% at 24/32px. Pathfinder represents these percentages as em.                                                                                                                                                            |

**Pathfinder implementation:** typography classes do not force `nowrap` or choose an HTML element. Controls retain wrapping and may grow for long content or enlarged text; the single-line role is not permission to clip content.

## Spacing, radius and sizing rules [#spacing-radius-and-sizing-rules]

Source: [Dimensions frame](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=165-17). Values: [Sizing and elevation](/docs/foundations/sizing-elevation).

| ID      | Figma guidance                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SIZE-01 | Bind every padding and gap to the spacing scale. Off-scale spacing such as 10px or 14px is an override to correct, not a new token. This rule applies to spacing; radius/lg remains 10px.                                                        |
| SIZE-02 | Spacing 8xl–11xl (80–160px baseline) is for page/section layout, never component interiors.                                                                                                                                                      |
| SIZE-03 | Buttons, split buttons and icon buttons use radius/md (8px) at every size; inputs/other controls use sm (6px); menus/popovers lg (10px); cards/panels/dialogs xl (12px); sheets 2xl (16px); pills full. Component guidance specifies exceptions. |
| SIZE-04 | Nested corner radius equals the outer radius minus the intervening padding. Pathfinder implementation must avoid negative CSS radii; the sheet does not define a negative-result policy.                                                         |
| SIZE-05 | Bind control height to tokens. xs 24px is for icon buttons inside controls; sm 28px for dense tables/toolbars/filters; md 32px is default; lg 36px for prominent actions; xl 40px for hero/empty-state actions.                                  |
| SIZE-06 | Icons: xs 12px for dense tables/badges; sm 16px is default in sm/md controls; md 20px in lg/xl controls; lg 24px for featured icons/empty states.                                                                                                |
| SIZE-07 | Containers use a 0.5px hairline, interactive control edges use 1px, and focus uses a 2px Blue 700 ring offset 2px outside the element.                                                                                                           |

### Spacing jobs [#spacing-jobs]

| Token             | Intended use                                                     |
| ----------------- | ---------------------------------------------------------------- |
| none / 0          | No gap                                                           |
| xxs / 2           | Icon-to-text inside badges/tags                                  |
| xs / 4            | Dense-control gaps and badge padding                             |
| sm / 6            | Icon-to-label inside buttons/menu items                          |
| md / 8            | Related-control gaps and vertical input padding                  |
| lg / 12           | Horizontal control padding and list-item gaps                    |
| xl / 16           | Form-field gaps and compact card padding                         |
| 2xl / 20          | Docked-chat and sheet panel padding                              |
| 3xl / 24          | Card/dialog padding and groups inside panels                     |
| 4xl / 32          | Form blocks and page sections                                    |
| 5xl / 40          | Major page regions                                               |
| 6xl / 48          | Page sections on wide layouts                                    |
| 7xl / 64          | Outer page margins on 1440px frames; depending on layout context |
| 8xl–11xl / 80–160 | Page and section layout only                                     |

Radius/none is for square tables/full-bleed panels; xs is for checkboxes, small badges and tags; sm also covers OTP slots/tooltips; md also covers menu items, badges, small cards and wells; xl also covers the chat composer; full also covers avatars, switches and dots. Old xxs/3xl/4xl radius names are removed.

Generic container widths: xxs 320 for narrow menus/popovers; xs 384 for content tooltips/filter popovers; sm 480 for small dialogs; md 560 for default dialogs; lg 640 for wide dialogs/sheets; xl 768 for a form column; 2xl 1024 for document reading; 3xl 1280 for content maximum; 4xl 1440 for the design frame; 5xl 1600 for wide dashboards; 6xl 1920 for Full HD. These generic containers and named product-layout widths serve different purposes; do not interchange the two scales.

**Pathfinder implementation:** token lengths use rem at a 16px baseline, with px for strokes/full radius. Control sizes are minimum baselines when content needs to grow.

## Elevation and border rules [#elevation-and-border-rules]

Source: [Elevation frame](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=165-29).

| ID      | Figma guidance                                                                                                                                                                                                    |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ELEV-01 | Start flat: white background, Soft Pearl 300 hairline, radius xl, no shadow. Separate surfaces with a hairline and a neutral fill step before adding elevation.                                                   |
| ELEV-02 | A floating surface pairs its shadow with a hairline. Choose elevation by job, never by visual shadow size; a shadow alone is not a full recipe.                                                                   |
| ELEV-03 | Inputs are flat. Buttons and segmented controls use control elevation with radius md. Other elevation specimens show radius xl; component-specific radius belongs to its component guidance.                      |
| ELEV-04 | Use raised for hover-lifted cards/dragged items; soft for the composer and fields resting on the page; menu for trigger-anchored dropdowns/popovers/tooltips; panel for docked/floating panes; modal for dialogs. |
| ELEV-05 | A sticky header/footer gets a Soft Pearl 300 hairline where content scrolls beneath it.                                                                                                                           |
| ELEV-06 | Shadows use neutral #121212, never a tinted color.                                                                                                                                                                |
| ELEV-07 | Border states: Soft Pearl 400 default, 500 hover, 600 strong; Blue 700 selected; Red 600 invalid. Control states use 1px. Focus is Blue 700 at 2px with 2px outside offset.                                       |

## Motion rules [#motion-rules]

Source: [Motion frame](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=472-17720). Values: [Motion tokens](/docs/foundations/motion).

| ID        | Figma guidance                                                                                                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MOTION-01 | Motion explains origin: menus come from their trigger, toasts from their edge, inserted rows from the insertion point. Change state on the same element rather than blinking it out and recreating it.        |
| MOTION-02 | Press feedback begins on pointer down, within 100ms, without waiting for the network. Large surfaces (cards, rows, radio cards) never scale on press; only their control does.                                |
| MOTION-03 | Every transition uses a token or documented recipe. If none fits, add a recipe to the design before implementing an independent transition. Raw timings/curves are overrides.                                 |
| MOTION-04 | Springs are for movement; durations are for color, exits and CSS-only fallbacks. Closing never bounces; use fast/out, described as roughly 70% of opening time.                                               |
| MOTION-05 | Bounce is reserved for success and direct manipulation. Never bounce data, errors, readable content or toasts. Keep readable surfaces steady.                                                                 |
| MOTION-06 | Prefer transform and opacity. Animate size only when the element itself changes size, such as stateful buttons or expanding sections. Prefer one moving part; other parts change color/text/opacity in place. |
| MOTION-07 | Keyboard-initiated menus, tabs, radios and toggles change instantly. Keyboard presses never scale.                                                                                                            |
| MOTION-08 | Reduced motion replaces springs with a 150ms out-eased fade and removes scale, offset and blur. Loading indicators may continue.                                                                              |
| MOTION-09 | Only disclosure chevrons rotate (accordions/table groups). Menu-trigger chevrons stay still; the held hover fill indicates an open menu.                                                                      |
| MOTION-10 | Animate toward the current target so interruption continues from the present state; never restart from a fixed origin.                                                                                        |
| MOTION-11 | Duration-based transitions stay at or below 300ms except sheets; the deliberate row also mentions whole-page transitions, recorded as an unresolved exception below.                                          |
| MOTION-12 | Prototype with the specified Figma spring settings to match the intended product feel. The package exports duration/bounce presets, not an animation engine.                                                  |

### Preset jobs and prototype settings [#preset-jobs-and-prototype-settings]

| Preset     | Product duration / bounce | Figma stiffness / damping / mass | Intended use                                                                                                          |
| ---------- | ------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Snappy     | 0.2s / 0                  | 685 / 52.4 / 1                   | Presses, switches, checkboxes, opening menus                                                                          |
| Smooth     | 0.3s / 0.15               | 305 / 29.7 / 1                   | Indicators, expansion, size/layout changes, toasts, dialogs, rows; apply no-bounce restrictions before implementation |
| Expressive | 0.4s / 0.25               | 171 / 19.6 / 1                   | Success only, never expansion/data/errors                                                                             |

Durations: instant/100ms for hover/press color; fast/150ms for exits, disclosure chevrons, focus and checkbox ticks; base/200ms for menus/tooltips/selects without springs; slow/300ms for panels/dialogs without springs; deliberate/500ms for sheets with the Vaul curve. Easing/out is for entering, pressing, responding and every exit; in-out moves between screen positions; standard/ease is only for color/hover.

### Component recipes [#component-recipes]

These are **documented targets**, not animations currently shipped by Pathfinder. Preserve keyboard and reduced-motion overrides above.

| ID        | Recipe              | Figma behavior and intended components                                                                                                                                                                                              |
| --------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RECIPE-01 | Press               | Snappy: pointer-down scale 0.97, or 0.94 for 16px checkbox/radio controls; release to 1. Buttons, icon/split buttons, checkbox/radio.                                                                                               |
| RECIPE-02 | Hover               | Instant + standard; color only, never movement or scale. Every control.                                                                                                                                                             |
| RECIPE-03 | Open from trigger   | Snappy: opacity 0→1, scale 0.96→1, anchored offset 4px. Exit opacity 0/scale 0.98. Source prose says 120ms but names fast/150ms. Dropdown/select/date picker/popover/tooltip; tooltip has 100ms delay. Keyboard opening is instant. |
| RECIPE-04 | Enter and exit      | Smooth: backdrop fades; dialog rises 8px and scales 0.96→1. Exit fades/scales to 0.98 using fast. Dialog/confirmation.                                                                                                              |
| RECIPE-05 | Slide in            | Sheet enters from its edge over deliberate with cubic-bezier(0.32, 0.72, 0, 1). Drag closes past 25% or velocity 0.4; velocity units are unspecified.                                                                               |
| RECIPE-06 | Change state        | Current content exits with 1px blur in 90ms; next content arrives on snappy; width follows with smooth. Loading/done buttons, copy icons, file upload.                                                                              |
| RECIPE-07 | Sliding indicator   | Position and width move together on smooth; a darker copy of labels is clipped to the indicator. Tabs/segmented controls; switch thumb uses snappy.                                                                                 |
| RECIPE-08 | Expand and collapse | Height expands as content fades up 4px on smooth; collapse uses fast without bounce. Accordion, alert details, grouped table rows.                                                                                                  |
| RECIPE-09 | Swap a value        | Crossfade the entire value once: 80ms out, 150ms in through 1px blur. No per-digit roll. Badge counts, table numbers, progress labels.                                                                                              |
| RECIPE-10 | Add and remove      | Append at end: fade only. Insert elsewhere/remove: fade while following items move with transforms. Fast + snappy; stagger 30ms for at most 5 items, then show the rest together. Rows, lists, tags, toast stacks.                  |
| RECIPE-11 | Success             | Expressive check: scale from 0.4 and rotate 20° into place. Completion/copy/upload/success-toast feedback; do not bounce the readable toast surface.                                                                                |
| RECIPE-12 | Loading             | The only looping motion. Fade in after 150ms so fast responses do not flash a loader. Skeleton/progress/progress ring.                                                                                                              |

Distances: anchored 4px, overlay/list-row 8px, edge-toast 16px. Text blur is 1px for swaps; icon blur is 3px. Enter/exit scales are 0.96/0.98, with the success check's separate 0.4 start. These constants belong to complete recipes, not individually configurable theme variables. The icon-blur row mentions rolling digits despite the value-swap recipe forbidding them; use the whole-value recipe.

## Layout rules [#layout-rules]

Source: [Layout frame](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=238-2). Full dimensions: [Layout guidance](/docs/foundations/layout).

| ID        | Figma guidance                                                                                                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LAYOUT-01 | Start from Layout / App shell at 1440×900; review at widths 1280 and 1024 before handoff.                                                                                                                     |
| LAYOUT-02 | Client app below 768px shows the desktop-only message; partner pages are an exception. 768–1023 works but is not a design target. This is a product routing policy, not a package-level viewport restriction. |
| LAYOUT-03 | Shell: sidebar 208px expanded/56px collapsed, 8px gutters, white main card with 12px radius and 0.5px hairline, optional 44px breadcrumb, 24px content padding, optional 400px aside.                         |
| LAYOUT-04 | Use 12 fluid columns with 24px gutters in main content, 16px in asides/sheets. Map existing half/third form layouts to spans 6/4. Use spans instead of per-screen fixed widths.                               |
| LAYOUT-05 | Full is the default content width; Wide caps at 1200px; Reading is centered at 720px. Change content width rather than overriding the 24px page padding.                                                      |
| LAYOUT-06 | Use scale gaps: 8px within groups, 16/24px between cards, 32/48px between page sections.                                                                                                                      |
| LAYOUT-07 | Use the specified sheet/dialog sizes. The source says content beyond lg should become a page, but also lists xl/full dialogs; this needs a design decision.                                                   |

**Pathfinder implementation:** the package currently exports breakpoint and generic width tokens. It does not yet export an app shell, a layout-width scale, Sheet or Dialog. Documenting their intended geometry does not migrate enterprise routing or layout.


---

# Foundations

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations

Start with the foundation that matches your decision. Each reference combines visual examples, usage guidance, and the exact values available in the package.

<div className="pathfinder-foundation-links not-prose">
  <a href="/docs/foundations/color-reference">
    <strong>Color</strong>
    <span>Compare scales, background surfaces, and avatar pairs.</span>
  </a>
  <a href="/docs/foundations/typography">
    <strong>Typography</strong>
    <span>
      Try the 17 Inter styles and choose between headings, labels, and copy.
    </span>
  </a>
  <a href="/docs/foundations/sizing-elevation">
    <strong>Dimensions and elevation</strong>
    <span>
      See spacing, corner radius, control sizes, borders, and surface shadows.
    </span>
  </a>
  <a href="/docs/foundations/motion">
    <strong>Motion</strong>
    <span>
      Choose durations and spring presets, with input and accessibility
      guidance.
    </span>
  </a>
</div>

## Read the design rules [#read-the-design-rules]

[Design principles](/docs/foundations/design-rules) captures guidance from all six Figma foundation sheets, including motion recipes and layout guidance. Read it before implementing a component. [Layout guidance](/docs/foundations/layout) covers the app shell, columns and intended overlay sizes, with their current implementation status.

## Use in your application [#use-in-your-application]

Import the compiled stylesheet once. Inter is available as a separate, optional font import.

```tsx
import '@commenda/pathfinder/styles.css';
import '@commenda/pathfinder/fonts.css';
```

Use `pf-txt-*` classes for complete text styles and `--pf-*` variables in your CSS. Your application does not need Tailwind to consume them. [Tokens and styling](/docs/foundations/tokens) covers imports, overrides, and compatibility.

## How to use these references [#how-to-use-these-references]

- **Preview first.** Compare actual colors and dimensions before choosing a token. Scaled diagrams are labeled.
- **Check the context.** A color step alone does not guarantee contrast; control heights must accommodate enlarged text and wrapping labels.
- **Look up the exact value.** Expand the reference tables for token names and CSS variables. These tables also remain in the Markdown version for AI tools.

The current foundations describe the light theme. Color previews stay on a light surface so their meaning does not change with the documentation theme.


---

# Layout guidance

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/layout

Source: [Layout sheet](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=237-2), frame `238:2`, reviewed **2026-10-12**.

Use these layout principles when composing application screens. Pathfinder supplies [Sheet](/docs/components/sheet), [Dialog](/docs/components/dialog), and [Side nav](/docs/components/side-nav); the application owns the complete shell. Component pages define supported sizes and defaults.

## Viewports and design review [#viewports-and-design-review]

Design at 1440×900, then check widths 1280 and 1024. The client product shows its desktop-only message below 768px; partner pages are excepted. Widths 768–1023 work but are not a design target. This is an application policy: standalone Pathfinder components must still accommodate narrow containers and enlarged text.

| Breakpoint | Minimum viewport width |
| ---------- | ---------------------- |
| sm         | 640px                  |
| md         | 768px                  |
| lg         | 1024px                 |
| xl         | 1280px                 |
| 2xl        | 1536px                 |

Figma also mentions an `md-h` minimum-height query of 768px for tall modals. It is source guidance, not an exported Pathfinder breakpoint. Do not invent a `--pf-breakpoint-md-h` variable.

## App shell [#app-shell]

Start screens from the Figma Layout / App shell composition.

| Region           | Geometry                                      |
| ---------------- | --------------------------------------------- |
| Sidebar          | 208px expanded; 56px collapsed                |
| Gutters          | 8px                                           |
| Main card        | White background; 12px radius; 0.5px hairline |
| Breadcrumb strip | Optional; 44px high                           |
| Content padding  | 24px; do not override per page                |
| Aside            | Optional; 400px; detached or bordered         |

The sheet describes migration from older 270/72px sidebars to 208/56px, and 408/340px auxiliary panels to 400px. These are intended migrations, not verified current measurements of every repository screen.

## Column grid [#column-grid]

Use 12 fluid columns inside content, with 24px gutters. Asides and sheets use 16px gutters. Existing half/third form layouts map to spans 6 and 4.

| Composition                  | Column spans  |
| ---------------------------- | ------------- |
| Full row                     | 12            |
| Two equal cards              | 6 + 6         |
| Three equal cards            | 4 + 4 + 4     |
| Four equal cards             | 3 + 3 + 3 + 3 |
| Main and summary             | 8 + 4         |
| Wide main and narrow summary | 9 + 3         |

Lay out by spans rather than fixed per-screen pixel widths. Use 8px gaps within groups, 16px or 24px between cards, and 32px or 48px between page sections.

## Content widths [#content-widths]

| Mode    | Width and alignment      | Use                                                                          |
| ------- | ------------------------ | ---------------------------------------------------------------------------- |
| Full    | Fluid; default           | Tables, dashboards, lists                                                    |
| Wide    | Centered, maximum 1200px | Overview pages; usually behaves like Full until the viewport is about 1480px |
| Reading | Centered, maximum 720px  | Home, onboarding, settings, checklists, chat                                 |

Choose one content mode rather than overriding the 24px shell padding. Reading replaces inconsistent centered columns in the source design. It is distinct from the generic `width/2xl` token's 1024px document-width description.

## Panels, sheets and dialogs [#panels-sheets-and-dialogs]

| Surface | Source size names and widths                                       |
| ------- | ------------------------------------------------------------------ |
| Aside   | 400px                                                              |
| Sheet   | sm 400px; md 520px; lg 720px                                       |
| Dialog  | sm 400px; md 480px; lg 600px; xl 800px; full 95vw capped at 1200px |

Choose the component size for the task and available viewport. Prefer a dedicated page for flows that need sustained reading or extensive navigation. Generic container-width tokens and named component sizes serve different purposes.


---

# Motion tokens

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/motion

These are tokens and guidance, not an animation engine. No motion runtime or automatic animation is installed.

## Durations [#durations]

| Token      | CSS variable               | Milliseconds |
| ---------- | -------------------------- | ------------ |
| instant    | `--pf-duration-instant`    | 100          |
| fast       | `--pf-duration-fast`       | 150          |
| base       | `--pf-duration-base`       | 200          |
| slow       | `--pf-duration-slow`       | 300          |
| deliberate | `--pf-duration-deliberate` | 500          |

## Easing [#easing]

| Token    | CSS variable           | Value                             |
| -------- | ---------------------- | --------------------------------- |
| out      | `--pf-easing-out`      | `cubic-bezier(0.23, 1, 0.32, 1)`  |
| in-out   | `--pf-easing-in-out`   | `cubic-bezier(0.77, 0, 0.175, 1)` |
| standard | `--pf-easing-standard` | `ease`                            |

## Springs [#springs]

Import `spring` from `@commenda/pathfinder/tokens`. Durations in these presets are seconds, and bounce is dimensionless. Use duration/bounce only with engines that support that model; do not treat them as CSS easing curves.

| Preset     | Seconds | Bounce |
| ---------- | ------- | ------ |
| snappy     | 0.2     | 0      |
| smooth     | 0.3     | 0.15   |
| expressive | 0.4     | 0.25   |

Use snappy for presses and small controls; smooth for sliding and expanding content; expressive only for success. Exits do not bounce. Color hover changes use instant plus standard easing. Closing uses fast plus out. Sheets alone use deliberate with `motionRecipe.sheetEasing`.

## Recipe constants [#recipe-constants]

These constants are available on `motionRecipe`; they are not independently themeable CSS variables. Offsets and blur values are px; stagger is milliseconds; scales are dimensionless.

| Constant        | Value                          |
| --------------- | ------------------------------ |
| pressScale      | 0.97                           |
| smallPressScale | 0.94                           |
| enterScale      | 0.96                           |
| exitScale       | 0.98                           |
| anchoredOffset  | 4                              |
| overlayOffset   | 8                              |
| edgeOffset      | 16                             |
| textBlur        | 1                              |
| iconBlur        | 3                              |
| stagger         | 30                             |
| staggerLimit    | 5                              |
| sheetEasing     | cubic-bezier(0.32, 0.72, 0, 1) |

## Input and reduced motion [#input-and-reduced-motion]

Keyboard-initiated menus, tabs and toggles change instantly. With reduced motion, replace springs with a 150ms fade using out easing; remove scale, offset and blur. Loading indicators can continue. Hover never translates or scales. Animations follow the current state toward a target so interruptions do not restart from a fixed origin.

## Design guidance [#design-guidance]

Read [Design principles](/docs/foundations/design-rules) for shared usage guidance and motion recipes.

Source: [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System). Snapshot: 2026-10-12.


---

# Spacing, sizing and elevation

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/sizing-elevation

Lengths are rem at a 16px baseline, except strokes and full radius, which stay in px. Use control sizes as minimum heights when content must grow for wrapping or enlarged text. Spacing 8xl and above is for page layout, never component interiors.

## Spacing [#spacing]

<DimensionPreview group="spacing" />

<details>
<summary>Token values and CSS variables</summary>

| Token | CSS variable        | Value    |
| ----- | ------------------- | -------- |
| none  | `--pf-spacing-none` | 0rem     |
| xxs   | `--pf-spacing-xxs`  | 0.125rem |
| xs    | `--pf-spacing-xs`   | 0.25rem  |
| sm    | `--pf-spacing-sm`   | 0.375rem |
| md    | `--pf-spacing-md`   | 0.5rem   |
| lg    | `--pf-spacing-lg`   | 0.75rem  |
| xl    | `--pf-spacing-xl`   | 1rem     |
| 2xl   | `--pf-spacing-2xl`  | 1.25rem  |
| 3xl   | `--pf-spacing-3xl`  | 1.5rem   |
| 4xl   | `--pf-spacing-4xl`  | 2rem     |
| 5xl   | `--pf-spacing-5xl`  | 2.5rem   |
| 6xl   | `--pf-spacing-6xl`  | 3rem     |
| 7xl   | `--pf-spacing-7xl`  | 4rem     |
| 8xl   | `--pf-spacing-8xl`  | 5rem     |
| 9xl   | `--pf-spacing-9xl`  | 6rem     |
| 10xl  | `--pf-spacing-10xl` | 8rem     |
| 11xl  | `--pf-spacing-11xl` | 10rem    |

</details>

## Corner radius [#corner-radius]

<DimensionPreview group="radius" />

<details>
<summary>Token values and CSS variables</summary>

| Token | CSS variable       | Value    |
| ----- | ------------------ | -------- |
| none  | `--pf-radius-none` | 0rem     |
| xs    | `--pf-radius-xs`   | 0.25rem  |
| sm    | `--pf-radius-sm`   | 0.375rem |
| md    | `--pf-radius-md`   | 0.5rem   |
| lg    | `--pf-radius-lg`   | 0.625rem |
| xl    | `--pf-radius-xl`   | 0.75rem  |
| 2xl   | `--pf-radius-2xl`  | 1rem     |
| full  | `--pf-radius-full` | 9999px   |

</details>

## Control heights [#control-heights]

<DimensionPreview group="control" />

<details>
<summary>Token values and CSS variables</summary>

| Token | CSS variable      | Value   |
| ----- | ----------------- | ------- |
| xs    | `--pf-control-xs` | 1.5rem  |
| sm    | `--pf-control-sm` | 1.75rem |
| md    | `--pf-control-md` | 2rem    |
| lg    | `--pf-control-lg` | 2.25rem |
| xl    | `--pf-control-xl` | 2.5rem  |

</details>

## Icon sizes [#icon-sizes]

<DimensionPreview group="icon" />

<details>
<summary>Token values and CSS variables</summary>

| Token | CSS variable   | Value   |
| ----- | -------------- | ------- |
| xs    | `--pf-icon-xs` | 0.75rem |
| sm    | `--pf-icon-sm` | 1rem    |
| md    | `--pf-icon-md` | 1.25rem |
| lg    | `--pf-icon-lg` | 1.5rem  |

</details>

## Container widths [#container-widths]

<DimensionPreview group="width" />

<details>
<summary>Token values and CSS variables</summary>

| Token | CSS variable     | Value  |
| ----- | ---------------- | ------ |
| xxs   | `--pf-width-xxs` | 20rem  |
| xs    | `--pf-width-xs`  | 24rem  |
| sm    | `--pf-width-sm`  | 30rem  |
| md    | `--pf-width-md`  | 35rem  |
| lg    | `--pf-width-lg`  | 40rem  |
| xl    | `--pf-width-xl`  | 48rem  |
| 2xl   | `--pf-width-2xl` | 64rem  |
| 3xl   | `--pf-width-3xl` | 80rem  |
| 4xl   | `--pf-width-4xl` | 90rem  |
| 5xl   | `--pf-width-5xl` | 100rem |
| 6xl   | `--pf-width-6xl` | 120rem |

</details>

## Border strokes [#border-strokes]

<DimensionPreview group="stroke" />

<details>
<summary>Token values and CSS variables</summary>

| Token    | CSS variable           | Value |
| -------- | ---------------------- | ----- |
| hairline | `--pf-stroke-hairline` | 0.5px |
| control  | `--pf-stroke-control`  | 1px   |
| focus    | `--pf-stroke-focus`    | 2px   |

</details>

## Breakpoints [#breakpoints]

<DimensionPreview group="breakpoint" />

<details>
<summary>Token values and CSS variables</summary>

| Token | CSS variable          | Value |
| ----- | --------------------- | ----- |
| sm    | `--pf-breakpoint-sm`  | 40rem |
| md    | `--pf-breakpoint-md`  | 48rem |
| lg    | `--pf-breakpoint-lg`  | 64rem |
| xl    | `--pf-breakpoint-xl`  | 80rem |
| 2xl   | `--pf-breakpoint-2xl` | 96rem |

</details>

Breakpoints describe viewport widths. CSS custom properties cannot be used in media-query conditions; use explicit media queries from these reviewed values or the package's own Tailwind build. Product desktop-only routing is an application decision, not a restriction built into these tokens.

Buttons use radius md (8px); inputs use sm (6px); menus use lg (10px); cards, dialogs and panels use xl (12px); large sheets use 2xl (16px); pills use full. The older xxs, 3xl, 4xl and circle radius names are not part of the new Figma scale.

## Elevation [#elevation]

<ElevationPreview />

| Job     | CSS variable          | Shadow                                           |
| ------- | --------------------- | ------------------------------------------------ |
| flat    | `--pf-shadow-flat`    | `none`                                           |
| control | `--pf-shadow-control` | `0 1px 2px 0 #1212120a, 0 1px 4px 0 #12121208`   |
| raised  | `--pf-shadow-raised`  | `0 1px 2px 0 #12121205, 0 2px 12px 0 #1212120d`  |
| soft    | `--pf-shadow-soft`    | `0 1px 2px 0 #12121205, 0 1px 16px 0 #12121214`  |
| menu    | `--pf-shadow-menu`    | `0 1px 2px 0 #12121205, 0 4px 20px 0 #12121214`  |
| panel   | `--pf-shadow-panel`   | `0 1px 2px 0 #12121205, 0 8px 32px 0 #12121214`  |
| modal   | `--pf-shadow-modal`   | `0 1px 4px 0 #12121205, 0 16px 48px 0 #1212121a` |

Flat is the default: background fill, Soft Pearl 300 hairline, radius xl and no shadow. Elevation/control uses radius md; the documentation's other specimens use xl. Component geometry can specify a different radius (for example menu lg), so choose that component's radius when composing a surface. Shadows are neutral #121212. Floating surfaces always pair a shadow with a hairline; a shadow token alone is not a full surface recipe.

Controls use stroke/control (1px), containers stroke/hairline (0.5px). Control borders use Soft Pearl 400, hover 500, strong 600. Selected and focus use Blue 700; invalid uses Red 600. Focus is 2px with a 2px offset.

## Design guidance [#design-guidance]

Read [Design principles](/docs/foundations/design-rules) for shared usage guidance and motion recipes.

Source: [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System). Snapshot: 2026-10-12.


---

# Tokens and styling

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/tokens

Pathfinder owns its tokens in `packages/pathfinder/src/foundations`, reviewed
against [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=164-2).
The existing application token package remains unchanged.

## Consume without Tailwind [#consume-without-tailwind]

```tsx
import '@commenda/pathfinder/styles.css';
import '@commenda/pathfinder/fonts.css'; // Optional local Inter fonts.
import {
  colors,
  typography,
  spacing,
  spring,
} from '@commenda/pathfinder/tokens';
```

CSS variables, all typography classes, and component styles are already compiled.
A consumer does not scan source files or install Tailwind. Arbitrary Tailwind
utility strings are not a public contract: use the documented typography classes,
components and CSS variables in your own CSS.

```css
.summary {
  color: var(--pf-color-soft-pearl-1000);
  background: var(--pf-color-background);
  padding: var(--pf-spacing-xl);
  border: var(--pf-stroke-hairline) solid var(--pf-color-soft-pearl-300);
  border-radius: var(--pf-radius-xl);
}
```

## Reference [#reference]

- [Colors and avatar tones](/docs/foundations/color-reference)
- [Typography and playground](/docs/foundations/typography)
- [Spacing, sizing, borders and elevation](/docs/foundations/sizing-elevation)
- [Motion tokens and reduced-motion guidance](/docs/foundations/motion)

## Machine-readable source [#machine-readable-source]

`@commenda/pathfinder/tokens.json` exports the values with schema version, Figma
node IDs, snapshot date, units and aliases. `/tokens` provides the same data as
ESM and readonly TypeScript types. The Markdown tables above are generated from
those exports; `check-types` checks they are current. Edit source tokens, build
Pathfinder, then run `pnpm --filter @commenda/pathfinder-docs generate:foundations`.

## Isolation and compatibility [#isolation-and-compatibility]

Variables use `--pf-*`; utilities use `pf:`; typography recipes use `pf-txt-*`.
Internal Tailwind variables use `--pf-tw-*`. No global Preflight is included.
Import the stylesheet after your application's base styles.

The initial Button override variables remain supported: `--pf-color-primary`,
`--pf-color-primary-hover`, `--pf-color-on-primary`, `--pf-color-disabled` and
`--pf-color-on-disabled`. They reference Blue 700/800, Background and Soft Pearl
300/600. New components should use the Figma scale names rather than introduce
another semantic color layer. Set Button overrides directly on a theme container
when needed and verify contrast for every state.

Inter replaces the bootstrap Mulish fallback. The Button now uses Label/13 Strong
at 13px/16px and weight 500, with wrapping retained. Font loading is opt-in.
`className` is additive; conflicting utilities follow the cascade and are not
merged. Dark-mode values have not been defined by the design system yet.

The Tailwind v4 browser baseline remains Safari 16.4+, Chrome 111+, Firefox 128+.


---

# Typography

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/typography

<TypographyPlayground />

## Use a complete text style [#use-a-complete-text-style]

`pf-txt-heading-24` includes font family, size, line height, weight and tracking. All 17 classes ship in the finished stylesheet, even when the consuming application has no Tailwind installation. Text color and HTML semantics remain the caller's choice.

```tsx
import '@commenda/pathfinder/styles.css';
import '@commenda/pathfinder/fonts.css';

export const SectionTitle = () => (
  <h2 className="pf-txt-heading-20">Intercompany agreements</h2>
);
```

## Styles [#styles]

Sizes below are rem relative to the root font. Multiply by 16 for the Figma baseline in pixels. Tracking is em: Figma's −2% becomes −0.02em, not −2px.

| Class                    | Size      | Line height | Weight | Tracking |
| ------------------------ | --------- | ----------- | ------ | -------- |
| `pf-txt-heading-32`      | 2rem      | 2.5rem      | 600    | -0.02em  |
| `pf-txt-heading-24`      | 1.5rem    | 2rem        | 600    | -0.02em  |
| `pf-txt-heading-20`      | 1.25rem   | 1.75rem     | 600    | -0.015em |
| `pf-txt-heading-18`      | 1.125rem  | 1.625rem    | 600    | -0.015em |
| `pf-txt-heading-15`      | 0.9375rem | 1.375rem    | 600    | -0.01em  |
| `pf-txt-label-15`        | 0.9375rem | 1.25rem     | 400    | -0.01em  |
| `pf-txt-label-15-strong` | 0.9375rem | 1.25rem     | 500    | -0.01em  |
| `pf-txt-label-13`        | 0.8125rem | 1rem        | 400    | 0em      |
| `pf-txt-label-13-strong` | 0.8125rem | 1rem        | 500    | 0em      |
| `pf-txt-label-12`        | 0.75rem   | 1rem        | 400    | 0em      |
| `pf-txt-label-12-strong` | 0.75rem   | 1rem        | 500    | 0em      |
| `pf-txt-copy-15`         | 0.9375rem | 1.5rem      | 400    | -0.01em  |
| `pf-txt-copy-15-strong`  | 0.9375rem | 1.5rem      | 600    | -0.01em  |
| `pf-txt-copy-13`         | 0.8125rem | 1.25rem     | 400    | 0em      |
| `pf-txt-copy-13-strong`  | 0.8125rem | 1.25rem     | 600    | 0em      |
| `pf-txt-copy-12`         | 0.75rem   | 1.125rem    | 400    | 0em      |
| `pf-txt-copy-12-strong`  | 0.75rem   | 1.125rem    | 600    | 0em      |

## Roles and accessibility [#roles-and-accessibility]

- Heading introduces a page or section. Choose h1–h6 by document structure, never font size. Heading/24 is the page title; Heading/32 is for metric values or an empty-state headline.
- Label is compact UI text. Label Strong is 500, including button labels. The recipe does not force nowrap: controls must still support long labels and enlarged text.
- Copy is wrapping prose. Copy Strong is 600 for emphasis. Use Copy/15 for chat or dialog body; Copy/13 for descriptions; Copy/12 for helper text.
- Use `pf-tabular-nums` for tables and metrics. Typography recipes carry no color; use Soft Pearl 1000, 900 or 800 as appropriate.

## Font delivery [#font-delivery]

`fonts.css` loads locally packaged Inter Variable wght normal fonts with `font-display: swap`. It makes no request to Google or Figma. Unicode subsets cover Inter's Latin, Latin extended, Vietnamese, Greek and Cyrillic coverage; other scripts use system fallback fonts. Font files and the SIL license ship in the package.

If your application already loads Inter, omit `fonts.css` and supply `--font-inter` from your existing loader on the root. The family falls back to Inter and system sans-serif. Merely importing `styles.css` does not download a font. Only normal fonts are bundled; product styles use weights 400, 500 and 600.

## Design guidance [#design-guidance]

Read [Design principles](/docs/foundations/design-rules) for shared usage guidance and motion recipes.

Source: [The System](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System). Snapshot: 2026-10-12.


---

# Installation

Package: @commenda/pathfinder@0.1.0
Page: /docs/getting-started/installation

## Workspace installation [#workspace-installation]

The package is currently available in the Commenda workspace and has not been
published to a registry. Add `@commenda/pathfinder` with the `workspace:*` version
to a consumer's dependencies, then run `pnpm install`.

For another repository, build and pack it first:

```sh
pnpm --dir packages/pathfinder pack --pack-destination /tmp
```

Install the resulting `.tgz` file with that repository's package manager. Once
registry publishing is configured, a normal versioned dependency can replace it.

## Styles [#styles]

Import the stylesheet once, after your app's base styles. For Next.js Pages Router,
use `pages/_app.tsx`; for App Router, use `app/layout.tsx`.

```tsx
import '@commenda/pathfinder/styles.css';
```

Consumers do not need Tailwind, Pathfinder source scanning, a PostCSS plugin,
or a `transpilePackages` entry. Next.js still bundles the finished CSS.

## Components [#components]

```tsx
import { Button } from '@commenda/pathfinder';

export const SaveButton = () => <Button>Save changes</Button>;
```

The direct `@commenda/pathfinder/button` import is also supported. Private source
and output paths are not public APIs.

## React and Next.js [#react-and-nextjs]

React and React DOM are peer dependencies. Supported versions are React 18.3.1
and React 19. Interactive components preserve their client boundary. In App Router,
place event handlers and state in a component marked `'use client'`.

Use the same React version for React and React DOM. Components should not depend
on application auth providers, a router, or Commenda APIs.


---

# AI content integration

Package: @commenda/pathfinder@0.1.0
Page: /docs/guides/ai-content

## Package contract [#package-contract]

All components live in `@commenda/pathfinder`. Import `styles.css` once and optionally `code-font.css` for Geist Mono. Individual entry points are `markdown`, `code-block`, and `inline-reference`. No app-side CSS compilation, AI SDK provider, router, or upload client is required.

Streamdown 2.5.0 supplies streaming Markdown parsing. Lowlight 3.3.0 supplies Highlight.js token trees rendered as React spans; new AI runtime components do not use Shiki. Fumadocs examples and MDX fences also use Lowlight, rendered on the server; its default Shiki highlighting is disabled. Mermaid and math rendering are not enabled. Streamdown itself lists Mermaid transitively; Pathfinder does not enable its renderer.

## Migration readiness [#migration-readiness]

Migration is out of scope for this build. Keep legacy components in place until their consumers are explicitly migrated.

| Existing API / call site                                 | Pathfinder equivalent                                                          | Difference / future work                                                                   |
| -------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `MessageResponse` in `CommendaAiMessageItem`             | `Markdown children` and `isAnimating`                                          | Reuse the same `segment.part.text`; no message conversion                                  |
| Streamdown `components`                                  | `Markdown.components`                                                          | Typed semantic overrides; no leaking upstream AST types into the public contract           |
| Compound `CodeBlock`, header, filename and copy children | `CodeBlock code/language/filename/copyConfig`                                  | Header layout is internal; old children must be mapped explicitly                          |
| `showLineNumbers`                                        | Same compatibility prop                                                        | Defaults on to match Figma; `lineNumberConfig.visible` takes precedence                    |
| `MarkdownLink` with host routing and record lookup       | `referenceConfig.resolve`, `InlineReference.onClick`, or a typed link override | Host provider is not imported; app retains business routing and link confirmation          |
| Question fence renderer                                  | Plain code fallback in Phase 1                                                 | Interactive requests belong to Phase 5; do not migrate such consumers without mapping them |
| Math/Mermaid plugins and word animation                  | Not enabled                                                                    | Separate opt-in work, not silent migration parity                                          |
| Table copy/export/expand                                 | Built-in Markdown table controls                                               | Static semantic table; interactive sorting/editing remain Table features                   |

Preserve stable message/part IDs in the parent, part ordering, and application-owned state. Do not flatten tool results or attachments into strings. New reference configuration must update even when the text is unchanged.

## Upstream provenance [#upstream-provenance]

Behavioral reference: Vercel AI Elements `MessageResponse` and Code Block, revision `6a9d5b1822ffb10bba4bd97175f01edd7d8651cd`, Apache-2.0. Pathfinder replaces the visual controls, uses compact Figma typography, removes default plugins and the text-only memo comparator, and uses Lowlight instead of Shiki. See the package's `THIRD_PARTY_NOTICES.md`.

## Rendering rules [#rendering-rules]

Treat custom renderers as trusted application code. Keep untrusted raw HTML disabled, render code as text, and validate navigation schemes. References receive ready-to-render data or a loading state; they do not fetch records. Clipboard failures stay recoverable. Do not announce each streamed token.

Markdown is intentionally available through `@commenda/pathfinder/markdown` only (its types are also exported from the root). Streamdown has module side effects; keeping this runtime off the root barrel prevents unrelated icon and button imports from loading the Markdown parser.

## Attachments and context [#attachments-and-context]

Use [Attachment](/docs/components/attachment), [Attachment group](/docs/components/attachment-group), and [Composer context](/docs/components/composer-context) as independent leaves. Each accepts caller-owned data and callbacks; none requires an AI provider or transport.

Existing attachment `key`/`fileName`/`mimeType` values map to `id`/`filename`/`mediaType`. Keep opaque `fileRef` lookup, folder aggregation, cancellation, and viewer selection in the app. Context `onDismiss` maps to removal by stable ID. These are documented mappings and type fixtures, not consumer migrations.

## Composer and conversation starters [#composer-and-conversation-starters]

Use `/composer`, `/suggested-prompt`, and `/suggested-prompt-group` for Phase 3. These exports have no AI SDK runtime dependency. The Composer's `requestConfig.status` accepts AI SDK's `ready`, `submitted`, `streaming`, and `error` values directly.

| Existing surface                                       | Pathfinder mapping                                                                |
| ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| ChatComposer `initialInput` / provider text state      | Initialize React state and pass `value` / `onValueChange`                         |
| `onSubmit(text, attachments)`                          | Adapt `onSubmit({ text, attachments, command })` in the host                      |
| `status`, `onStop`                                     | `requestConfig={{ status, onStop }}`                                              |
| Existing attachment objects                            | Map to stable AttachmentItem IDs; keep backend metadata in the host               |
| `toolsSlot`                                            | `toolbar.leading`                                                                 |
| `contextSlot`                                          | `contextConfig` or existing ComposerContext composition                           |
| Existing upload service, file ingestion, folder upload | Retain in the host; wire `attachmentConfig.items`, `onAdd`, `onRemove`, `onRetry` |
| Suggestion click handler                               | SuggestedPrompt `onSelect` or SuggestedPromptGroup `onSelect`                     |

The selected skill is separate typed metadata, so plain-text drafts and existing backend payloads do not require rich-text migration. Convert that metadata only where the application builds its request. Do not serialize internal component state or import private implementation files.

Vercel AI Elements' [Prompt Input](https://elements.ai-sdk.dev/components/prompt-input) and [Suggestion](https://elements.ai-sdk.dev/components/suggestion) informed the textarea, toolbar, keyboard, and request-state responsibilities. Pathfinder implements those behaviors using its existing primitives and its controlled-data contract. It does not vendor a second Radix/shadcn component stack or introduce Shiki. Actual application migration remains out of scope.

## Activity and execution [#activity-and-execution]

| Existing AI Elements concept                    | Pathfinder                                                | Host responsibility                                  |
| ----------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
| Reasoning / ReasoningTrigger / ReasoningContent | `Reasoning` with optional `disclosureConfig` and children | Supply approved summary text and elapsed duration    |
| Tool / ToolInput / ToolOutput                   | `ToolCall` with `input` and `output` source strings       | Map tool status and redact secrets before rendering  |
| ChainOfThought step composition                 | `ChainOfThought` with discriminated `steps`               | Keep stable IDs and preserve source ordering         |
| Thinking / Shimmer                              | `ThinkingIndicator`                                       | Hide label after first content; remove at completion |

AI SDK mapping: `input-streaming` → pending, `input-available` → running, `output-available` → done, `output-error` → failed. Approval states require application UI; do not present approval as completed execution. Keep this adapter in the host so SDK upgrades do not change the design system contract. No consumer migrations are included.

Reasoning's `isStreaming` describes the reasoning part, not the entire chat request. Set it false when answer content starts so automatic collapse happens a second later. A manual toggle wins until remount; use a stable key for one response, a new key for a new response. A controlled `disclosureConfig.open` delegates all automation to the host. Compose `Markdown` explicitly for formatted summaries; it remains a subpath-only runtime dependency.

Architecture references: [Vercel Reasoning](https://elements.ai-sdk.dev/components/reasoning), [Tool](https://elements.ai-sdk.dev/components/tool), and [Chain of Thought](https://elements.ai-sdk.dev/components/chain-of-thought). Pathfinder adapts these concepts to Figma and uses Base UI Collapsible, the same panel measurement foundation used by Accordion. It does not import legacy UI wrappers or their Shiki/Streamdown code plugins.

## Requests, approvals, and optional actions [#requests-approvals-and-optional-actions]

QuestionCard, ApprovalCard, PlanReviewCard and UploadRequestCard share a request result contract. Keep request IDs and tool-call IDs stable and key each card by request ID/version. A handler returns accepted plus the server receipt, or failed plus a user-facing message. Retain drafts on failure and persist accepted ResponseRecap data in the originating message. Approval/plan receipts include the actor and timestamp. Explicit skip, deny, approve and submit are different domain events; temporary dismissal never resolves a request.

Route a typed Composer response to the active question as a written answer. For an active approval, the Figma contract treats a typed response as denial. Implement that deliberate mapping in the host orchestrator, together with authorization and idempotency. Do not attach approval to global keyboard shortcuts or merely closing a card. Plan review opens app-owned plan content. Upload request passes files to app-owned validation/upload and sends only ready attachment IDs.

ActionCard is optional: it does not pause or resume a turn. Return completed only after the action succeeds. Persist completion/dismissal independently; no toast or follow-up message is generated. Use state to restore completed or dismissed actions from history.

For migration, map existing Ask single/multiple data to QuestionCard; approve to ApprovalCard; plan to PlanReviewCard; upload to UploadRequestCard. Map accepted records to ResponseRecap and optional Action records to ActionCard. Keep existing orchestration callbacks behind these typed boundaries. No application migration, AI SDK state conversion, plan editor or upload transport is included in this phase.

### Existing question flow compatibility [#existing-question-flow-compatibility]

Reviewed `QuestionDockedCard` in `CommendaAiConversation`, the historical `QuestionBlockRenderer`, `QuestionSelectCard`, `QuestionPlanCard`, `QuestionAnsweredRecap`, and the `question-block.ts` backend contract. These remain unchanged.

| Existing contract                                                 | Pathfinder mapping                                                 | Preserved behavior / adapter boundary                                                                                                   |
| ----------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `toolCallId` and indexed `questions[]`                            | React key `${toolCallId}:${questionIndex}` plus `paginationConfig` | Host keeps the tool-call ID, batches answers and persists drafts; no automatic 250ms page advance in the primitive                      |
| `single_select` / `multi_select`, positional options with `title` | `mode`, `options: { id, label, description }[]`                    | Use stable position-derived IDs for this immutable request, not labels; duplicate labels remain distinct                                |
| `selectedByIndex`, `writeInByIndex`                               | `defaultAnswer`, `onAnswerChange`                                  | Store per-question drafts in the adapter before changing pages                                                                          |
| `ANSWER_MAX_LENGTH = 300`                                         | `writeInConfig={{ maxLength: 300 }}`                               | Retain the current backend limit; validate combined multi-choice text server-side                                                       |
| `onAnswer({toolCallId, answers, text})`                           | `onSubmit` / `onSkip`                                              | Adapter maps selected IDs back to `questionIndex`/`chosen`, carries the original tool ID and answer marker; accepted result is explicit |
| Plan body and correction textarea                                 | `planConfig.onOpen`, `onSuggestChanges`                            | Intentional new Figma design: plan/editor lives in the host, no Skip or embedded correction editor                                      |
| Completed `QuestionRecord`                                        | `ResponseRecap` / `state: resolved`                                | Restore accepted answers from persisted records; do not infer receipt state from message text                                           |
| `onClose`                                                         | `onDismiss`                                                        | Temporary hide only; do not submit an answer or cancel a tool                                                                           |

The existing `data-question-answer` marker and backend request schema remain application-owned. The visual component never rewrites history or infers a tool-call ID. ApprovalCard, UploadRequestCard and optional ActionCard are new surfaces with no required legacy transport. This phase implements the Figma request/action designs directly with Pathfinder controls; it vendors no additional Vercel AI Elements source or dependencies.

## Messages and conversation composition [#messages-and-conversation-composition]

Use `@commenda/pathfinder/message` and `@commenda/pathfinder/conversation`. Keep existing SDK objects and pass typed render callbacks; no serialization or role conversion is required. Message's `from="person"` is presentation only. Markdown remains a separate import, and unknown tool/custom parts must be handled by the application renderer.

| Existing integration                                 | Pathfinder boundary                                      | Host responsibility                                                        |
| ---------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------- |
| `CommendaAiMessageItem` and compound Message content | `Message<Part>` with `parts`, `getPartKey`, `renderPart` | Preserve original IDs, order, custom metadata and tool states              |
| `MessageActions` / feedback modal                    | `actionConfig`                                           | Controlled feedback, app modal, persistence and retry eligibility          |
| Compound Conversation / scroll button                | `Conversation<Item>`                                     | Stable message keys, bounded height and app-owned history loading          |
| Docked questions                                     | `footer` containing QuestionCard and Composer            | Put accepted recap in the originating message, persist it, remove the dock |

`MESSAGE-04`: errors retain partial replies. `CONVERSATION-02`: follow only near bottom and preserve reading position across history prepend. `CONVERSATION-03`: supply turn-level announcements, never per-token live text. These are optional boundaries for a future migration; the existing application is unchanged.

## Outputs and run history [#outputs-and-run-history]

Use [Output List](/docs/components/output-list) for artifact rows and [Run List](/docs/components/run-list) for execution history. The responsive panel and complete simulated workflow live in the Output List examples. Import each component from its own package subpath; no global AI provider is required.

| Existing integration                                | Pathfinder boundary                                         | Preserved behavior / intentional difference                                          |
| --------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `AgentRunsRail` active conversation and run queries | `RunList.items`, `selectedId`, `onOpen`, `paginationConfig` | Host maps IDs, formatted dates, paging, and router navigation                        |
| `useMarkRunRead` and schedule actions               | `onMarkRead`, `actionConfig`                                | Host owns mutations; no optimistic unread change in the primitive                    |
| Canceled treated as failure                         | `status="canceled"`                                         | Deliberate Figma change: canceled and skipped use neutral indicators                 |
| `AttachmentPreviewPanel` / document viewer          | `OutputList.onOpen`                                         | Host retains signed URLs, preview tabs, downloads, and viewer lifecycle              |
| Per-person rail preference                          | `disclosureConfig` and host panel state                     | Host persists disclosure and responsive visibility; no storage access in the package |

`OUTPUT-03` keeps independent row/menu actions, and `RUN-02` keeps canceled runs neutral. Supply newest-first records with stable IDs. The compact lists do not sort backend data or virtualize unlimited history. These boundaries make incremental adoption possible; actual migration and full artifact editing are out of scope.


---

# Component conventions

Package: @commenda/pathfinder@0.1.0
Page: /docs/guides/component-conventions

Component-specific rules, Figma sources and reviewed differences live on each component page. These conventions apply across the library.

## Styling and distribution [#styling-and-distribution]

Import `@commenda/pathfinder/styles.css` once, after host styles. Use public root or component subpath exports. Applications do not need to scan Pathfinder source or compile Tailwind utilities. Public components support React 18 and 19 and both Next.js router families; event handlers belong in client components in App Router.

Pathfinder resets Tailwind’s default theme. Its private `--spacing-0` alias points to the existing `none` token so zero-size, inset, margin, padding and minimum-width utilities compile. A packed-CSS test guards this contract.

## Accessible presentation [#accessible-presentation]

Use meaningful labels, associate supporting and error text with controls, and preserve focus visibility. Figma’s fixed specimen heights are minimums when content wraps or text is enlarged. Decorative artwork must not compete with the accessible control name.

## Forms and application state [#forms-and-application-state]

Use native names, autocomplete, refs and blur handlers with your form library. Pathfinder has no dependency on a form framework. Controlled changes request application updates; uncontrolled form resets restore defaults. Error messages and disabled reasons remain associated with the control. Prefixes and suffixes do not become part of submitted values.

Applications own network requests, validation schemas, permissions and persistence. A visual loading or success state is an explicit application signal, not evidence that a request completed.

## Right-to-left layouts [#right-to-left-layouts]

Set HTML direction on the document or section and use `DirectionProvider` for primitive keyboard and positioning behavior. Pathfinder styles use logical properties.

```tsx
import { DirectionProvider } from '@commenda/pathfinder';

<DirectionProvider direction="rtl">
  <div dir="rtl">{children}</div>
</DirectionProvider>;
```

## Documentation and verification [#documentation-and-verification]

Storybook and Fumadocs share example implementations. Code previews and AI Markdown include source from those examples. Figma references provide evidence for rules; screenshots are not runtime component artwork. Follow each component’s documented contract instead of inferring public props from Figma variant names.

Before completing a change, verify relevant keyboard behavior, focus return, wrapping, empty and error states, touch, 320px layouts, 200% zoom and reduced motion. Check RTL where supported. Export, stylesheet and declaration changes also require packed-consumer checks. These are development gates; implementation notes record which checks actually ran.


---

# Contributing

Package: @commenda/pathfinder@0.1.0
Page: /docs/guides/contributing

## Develop locally [#develop-locally]

Run the package watcher and docs from the workspace root in separate terminals:

```sh
pnpm pathfinder:dev
pnpm pathfinder:docs
```

`pnpm pathfinder:storybook` starts Storybook and its own package watcher. When
using it, you do not need a second `pathfinder:dev` process.

The package watcher does not serve a web page. Documentation runs on port 3002;
Storybook runs on port 6006. Run development commands without `sudo`.

## Component structure [#component-structure]

Keep implementation, props, stories, and behavior tests in
`packages/pathfinder/src/components/<component>/`. Export the intended API through
the component's `index.ts` and the package entry points. Create shared hooks or
types only when multiple components need them.

## Contribution checklist [#contribution-checklist]

1. Define the use case, API, states, and Base UI primitive.
2. Use semantic tokens and preserve React 18/19 compatibility.
3. Verify keyboard behavior, focus, disabled states, and accessible names.
4. Add stories and meaningful behavior/type tests.
5. Update these docs with examples, limitations, and accessibility guidance.
6. Check compiled exports, declarations, and CSS when the package contract changes.
7. Run applicable worst-case content/layout checks with Emil's `break-ui` and retain
   Storybook fixtures. Report verification results in the PR. Follow the [development skills guide](/docs/guides/development-skills)
   for UI, motion, API design, and test guidance.

Follow the [component conventions](/docs/guides/component-conventions) and
[formatting guide](/docs/contributing/formatting) when extending the package.

## Required checks [#required-checks]

`pnpm pathfinder:check` runs formatting checks, lint, behavior/artifact tests, public API type fixtures,
and package/docs type checking. `pnpm pathfinder:lint` runs lint alone;
`pnpm --filter @commenda/pathfinder lint:fix` applies supported safe fixes.

The scoped ESLint configuration checks strict TypeScript, promise handling,
React hooks, JSX accessibility, unused imports, and package boundaries. Published
components cannot import Next.js, application code, private workspace packages,
or generated output. CI rejects warnings, and inline rule suppressions are disabled.
Document justified exceptions in the scoped config. Accessibility lint does not
replace browser keyboard tests and Storybook accessibility scans.

### Overlay motion regression [#overlay-motion-regression]

After changing overlay motion, build and serve Storybook, then run:

```bash
pnpm --filter @commenda/pathfinder exec playwright install chromium
PATHFINDER_STORYBOOK_URL=http://localhost:6006 pnpm --filter @commenda/pathfinder test:motion
```

Use the URL of your running Storybook (including a served static build). This browser check samples computed transforms across animation frames, rather than trusting duration classes. It covers Dialog, Popover, side/bottom Sheet entry and exit, interrupted exits, keyboard activation, reduced motion and bottom-sheet drag release. Keep it separate from the unit suite because it requires Chromium and a running browser preview.

## Component styling [#component-styling]

Author components with Tailwind CSS v4 utilities prefixed with `pf:`. Shared class recipes belong beside the components that use them. Use generated tokens for color, typography, spacing, radii, and elevation; arbitrary values are for Figma geometry without a matching token.

- Keep complete utility names in source. Do not build class names from interpolated fragments.
- Style Base UI states with data-attribute variants. Preserve focus, disabled, read-only, and reduced-motion behavior.
- Use `DirectionProvider` and the matching document `dir` for RTL. Direction-sensitive controls use Base UI's direction context.
- Keep CSS for generated foundations, fonts, and keyframes. Component-specific selector stylesheets require a documented reason.
- Build and test the packed CSS: consumers import `@commenda/pathfinder/styles.css` once after their own base stylesheet and never scan Pathfinder source or install Tailwind.
- Run Prettier, `pnpm pathfinder:check`, packed-consumer checks, and affected Storybook/Fumadocs previews before completing a styling change.

The `pf-*` marker classes in rendered components support documentation selectors; component appearance comes from the prefixed utilities. They are not a public styling API.

## Documentation structure [#documentation-structure]

Use readable component names in navigation and headings: “Icon button” and “Data grid”. Preserve exact API identifiers inside code and prop tables. Write explanatory copy in sentence case with complete sentences.

Each component page should contain a live preview, usage, focused examples, API reference, accessibility guidance and its own source-linked design rules. Keep stable rule IDs and reviewed Figma differences when updating a component. Shared accessibility, styling and framework conventions belong in Guides; foundation values belong in Foundations.

Navigation groups are defined in `lib/documentation-catalog.json`. Add new components to the appropriate group without changing their public documentation URLs. If a page moves, provide redirects for both its HTML and Markdown routes.

The asset browser shares its implementation with Storybook. Keep names visible, categories searchable, and copy examples accurate for the selected artwork and supported size. Test long labels, empty results, keyboard focus and mobile layouts in the Gallery worst case story.

`llms.txt`, page Markdown and `llms-full.txt` are generated from the same content. The AI reference check guards migrated rule IDs and example source; do not create a separate manually maintained AI copy.

## CI and application integration [#ci-and-application-integration]

Run `pnpm pathfinder:check` from the repository root. Turbo builds Pathfinder before
checking its source, examples, tests, and public types. Documentation type generation
runs before documentation lint. `pnpm pathfinder:ci` also builds the documentation
and Storybook and tests packed React consumers. CI enables Next.js consumer checks
with `PATHFINDER_NEXT_SMOKE=1`.

GitHub Actions builds the package once and shares its Turbo build cache with eight
parallel jobs: formatting, library lint, library types, unit/contract tests, docs
lint/types, docs production build, Storybook, and packed-consumer tests. Each job
has a separate runner; heavy tasks remain sequential inside that runner. The final
`validate` check succeeds only when the build and every matrix job succeed. Keep
`validate` as the required branch-protection check. New commits cancel obsolete
runs on the same PR. The local `pathfinder:ci` command still runs the complete set
sequentially on one machine.

The Pathfinder workflow owns library validation. Enterprise uses these root commands:

```sh
pnpm enterprise:dev
pnpm enterprise:check
pnpm enterprise:build
```

These commands use the same Turbo graph as CI and deployment. Enterprise builds
Pathfinder's compiled exports and validates its own integration; it does not rerun
Pathfinder's internal lint or type checks. Enterprise's `prisma:generate` task runs
before development, type checking, and production builds. Prisma generation is not
cached because its output lives inside pnpm-managed dependency directories.

The application package scripts are underlying tasks; use the root commands above
to prepare their dependencies. The standalone Pathfinder `test` and `test:package`
commands still build first. The `test:unit` and `test:package:run` tasks are scheduled
by Turbo after the build; the latter packs the verified output without rerunning
package lifecycle scripts. Normal `pnpm pack` still runs `prepack`.

Both workflows read Node 22 from `.node-version` and use pnpm 9.9.0. They share
Turbo cache credentials and compatible cache restore keys. Build hashes include
Pathfinder's own country data and the generated asset reference; changes to those
sources also trigger Pathfinder CI. Enterprise's type-check cache tracks workspace
dependency sources through transit tasks without executing their checks.


---

# Development skills

Package: @commenda/pathfinder@0.1.0
Page: /docs/guides/development-skills

Skills guide implementation and review. Our package contract, Figma decisions,
lint rules, and compiler checks remain the source of truth. Use the relevant skill
for the work at hand; reading every skill is not a contribution requirement.

## UI and motion [#ui-and-motion]

Use skills from [Emil's official repository](https://github.com/emilkowalski/skills):

| Skill                   | Use it for                                                                                     |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `break-ui`              | Stress-testing realistic content and layout limits in new or substantially changed components. |
| `emil-design-eng`       | Component polish, interaction states, typography, and visual review.                           |
| `animate`               | Building motion with a clear purpose, reduced-motion handling, and existing tokens.            |
| `review-animations`     | Reviewing timing, interruption, origin, and reduced-motion behavior.                           |
| `animation-performance` | Investigating dropped frames with browser/device evidence.                                     |
| `improve-animations`    | A broader motion audit and improvement plan.                                                   |

Preserve Base UI semantics and React 18/19 support. Verify animation recipes against
our supported browsers. A skill does not authorize introducing a new motion library,
overriding Figma, or assuming a performance optimization works without measurement.

## Worst-case testing [#worst-case-testing]

Keep realistic synthetic fixtures beside stories. Use a Storybook-only
**Demo data / Worst case** control that changes props through the same interface.
Keep this harness out of the package bundle and enterprise production UI.

Cover long/unbreakable labels, short labels, non-Latin text, and emoji. For components
that support them, also cover missing data/media, empty and single-item collections,
large counts, and disabled states. Record input limits or note that none are defined.
Do not invent unsupported loading/variant APIs for the test.

Check the actual container, 320px, the widest supported layout, and 200% browser
zoom. Check dark mode and RTL only when supported, and record missing coverage.
Keep keyboard and accessibility checks alongside these layout checks.

Record the fixture, story URL, viewport/zoom, severity, expected and actual behavior,
source location, proposed fix, and screenshots where available. Distinguish observed
failures from code-only concerns. Record what held up too. Resolve design choices
against Figma/the component spec, then recheck both datasets after fixing.

The Button's existing long-label story is a starting point. A complete `break-ui`
audit is still pending; installing the skill does not mean that audit has passed.

## TypeScript, APIs, and tests [#typescript-apis-and-tests]

Use skills from [Matt's official repository](https://github.com/mattpocock/skills):

| Skill                   | Pathfinder application                                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `tdd`                   | One failing behavior test followed by its implementation, using the public test surface agreed in the component spec. |
| `codebase-design`       | Small public APIs that hide useful behavior and are straightforward to test.                                          |
| `setup-ts-deep-modules` | Optional package-boundary reference. Its setup migration is not part of our workflow.                                 |

Matt's reviewed repository has no general skill named `typescript`.
`setup-ts-deep-modules` concerns architecture; our existing `typescript-advanced-types`
skill and TypeScript documentation cover types and compiler behavior.

Keep the pnpm workspace layout, explicit package exports, and colocated component
tests. Do not replace them with the skill's example layout or automatically install
dependency-cruiser. Public type checks still exercise Bundler and NodeNext consumers;
lint and packed-package checks enforce the existing contract.

## Install and maintain [#install-and-maintain]

These are local agent tools, not package dependencies or CI executables. For Codex:

```sh
npx skills add emilkowalski/skills --skill break-ui animate animation-performance emil-design-eng review-animations improve-animations --agent codex --global
npx skills add mattpocock/skills --skill setup-ts-deep-modules tdd codebase-design --agent codex --global
```

The commands resolve current upstream versions. Review updates before adopting them.
Locally installed skills become available on
the next Codex turn. These docs, including this guide, also appear in Pathfinder's
AI-readable Markdown endpoints.


---

# Build with Pathfinder

Package: @commenda/pathfinder@0.1.0
Page: /docs

Pathfinder brings Commenda’s visual language to React. Every component ships with typed props, accessible interactions and compiled styles, ready to use in Next.js without an application Tailwind build.

## Start building [#start-building]

[Install Pathfinder](/docs/getting-started/installation), import the stylesheet once, and start with a [Button](/docs/components/button). Component pages pair live previews with copyable code, prop references and design guidance.

## Explore the library [#explore-the-library]

- **Foundations** — [Color](/docs/foundations/color-reference), [typography](/docs/foundations/typography), [spacing and elevation](/docs/foundations/sizing-elevation), and [motion](/docs/foundations/motion).
- **Components** — From [inputs](/docs/components/input) and [selection](/docs/components/select) to [tables](/docs/components/table), [calendars](/docs/components/calendar), and [dialogs](/docs/components/dialog).
- **Assets** — Search [icons](/docs/assets/icons), [flags](/docs/assets/flags), [file types](/docs/assets/file-types), and [logos](/docs/assets/logos); select an asset to copy its import.
- **Guides** — [Shared conventions](/docs/guides/component-conventions), [contribution standards](/docs/guides/contributing), and [development skills](/docs/guides/development-skills).

## Designed for your workflow [#designed-for-your-workflow]

Fumadocs explains when and how to use each component. Storybook provides isolated examples and controls for development. Figma rules and reviewed accessibility adjustments live alongside the component they describe.

Pathfinder supports React 18 and 19, with Next.js Pages and App Router integrations. It currently uses a light theme and is maintained as a workspace package; see installation for the distribution contract.

## For AI tools [#for-ai-tools]

Start with [/llms.txt](/llms.txt) to discover component documentation. Use [/llms-full.txt](/llms-full.txt) for the complete reference or the **Read as Markdown** link on any page for focused context. These endpoints use the same source as this site, including component rules and executable examples.


---

# Asset reference

Complete import and size reference for AI and tooling.

Explicit exclusions: [{"id":"activity","reason":"Interactive tooltip and running-motion contract requires a separate Activity component; outside the approved static status/ring scope.","nodeIds":["670:37380","670:37382","670:37384","670:37386","670:37388","739:422","739:431","739:440","739:449","739:458"]}]

asterisk-01: Asterisk01Icon; <Icons.Interface.Asterisk01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

asterisk-02: Asterisk02Icon; <Icons.Interface.Asterisk02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dice-1: Dice1Icon; <Icons.Interface.Dice1 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dice-2: Dice2Icon; <Icons.Interface.Dice2 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dice-3: Dice3Icon; <Icons.Interface.Dice3 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dice-4: Dice4Icon; <Icons.Interface.Dice4 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dice-5: Dice5Icon; <Icons.Interface.Dice5 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dice-6: Dice6Icon; <Icons.Interface.Dice6 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

divide-01: Divide01Icon; <Icons.Interface.Divide01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

divide-02: Divide02Icon; <Icons.Interface.Divide02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

divide-03: Divide03Icon; <Icons.Interface.Divide03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

equal: EqualIcon; <Icons.Interface.Equal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

equal-not: EqualNotIcon; <Icons.Interface.EqualNot />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

filter-funnel-01: FilterFunnel01Icon; <Icons.Interface.FilterFunnel01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

filter-funnel-02: FilterFunnel02Icon; <Icons.Interface.FilterFunnel02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

filter-lines: FilterLinesIcon; <Icons.Interface.FilterLines />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

infinity: InfinityIcon; <Icons.Interface.Infinity />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

life-buoy-01: LifeBuoy01Icon; <Icons.Interface.LifeBuoy01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

life-buoy-02: LifeBuoy02Icon; <Icons.Interface.LifeBuoy02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mark: MarkIcon; <Icons.Interface.Mark />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

medical-circle: MedicalCircleIcon; <Icons.Interface.MedicalCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

medical-cross: MedicalCrossIcon; <Icons.Interface.MedicalCross />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

medical-square: MedicalSquareIcon; <Icons.Interface.MedicalSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

minus: MinusIcon; <Icons.Interface.Minus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

minus-circle: MinusCircleIcon; <Icons.Interface.MinusCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

minus-square: MinusSquareIcon; <Icons.Interface.MinusSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

placeholder: PlaceholderIcon; <Icons.Interface.Placeholder />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

plus: PlusIcon; <Icons.Interface.Plus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

plus-circle: PlusCircleIcon; <Icons.Interface.PlusCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

plus-square: PlusSquareIcon; <Icons.Interface.PlusSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

search-lg: SearchLgIcon; <Icons.Interface.SearchLg />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

search-md: SearchMdIcon; <Icons.Interface.SearchMd />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

search-refraction: SearchRefractionIcon; <Icons.Interface.SearchRefraction />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

search-sm: SearchSmIcon; <Icons.Interface.SearchSm />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

settings-01: Settings01Icon; <Icons.Interface.Settings01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

settings-02: Settings02Icon; <Icons.Interface.Settings02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

settings-03: Settings03Icon; <Icons.Interface.Settings03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

settings-04: Settings04Icon; <Icons.Interface.Settings04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sliders-01: Sliders01Icon; <Icons.Interface.Sliders01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sliders-02: Sliders02Icon; <Icons.Interface.Sliders02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sliders-03: Sliders03Icon; <Icons.Interface.Sliders03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sliders-04: Sliders04Icon; <Icons.Interface.Sliders04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speedometer-01: Speedometer01Icon; <Icons.Interface.Speedometer01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speedometer-02: Speedometer02Icon; <Icons.Interface.Speedometer02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speedometer-03: Speedometer03Icon; <Icons.Interface.Speedometer03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speedometer-04: Speedometer04Icon; <Icons.Interface.Speedometer04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

target-01: Target01Icon; <Icons.Interface.Target01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

target-02: Target02Icon; <Icons.Interface.Target02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

target-03: Target03Icon; <Icons.Interface.Target03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

target-04: Target04Icon; <Icons.Interface.Target04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

target-05: Target05Icon; <Icons.Interface.Target05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tool-01: Tool01Icon; <Icons.Interface.Tool01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tool-02: Tool02Icon; <Icons.Interface.Tool02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trash-01: Trash01Icon; <Icons.Interface.Trash01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trash-02: Trash02Icon; <Icons.Interface.Trash02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trash-03: Trash03Icon; <Icons.Interface.Trash03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trash-04: Trash04Icon; <Icons.Interface.Trash04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

virus: VirusIcon; <Icons.Interface.Virus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zap: ZapIcon; <Icons.Interface.Zap />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zap-circle: ZapCircleIcon; <Icons.Interface.ZapCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zap-fast: ZapFastIcon; <Icons.Interface.ZapFast />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zap-off: ZapOffIcon; <Icons.Interface.ZapOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zap-square: ZapSquareIcon; <Icons.Interface.ZapSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alert-circle: AlertCircleIcon; <Icons.Interface.AlertCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alert-hexagon: AlertHexagonIcon; <Icons.Interface.AlertHexagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alert-octagon: AlertOctagonIcon; <Icons.Interface.AlertOctagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alert-square: AlertSquareIcon; <Icons.Interface.AlertSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alert-triangle: AlertTriangleIcon; <Icons.Interface.AlertTriangle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

announcement-01: Announcement01Icon; <Icons.Interface.Announcement01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

announcement-02: Announcement02Icon; <Icons.Interface.Announcement02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

announcement-03: Announcement03Icon; <Icons.Interface.Announcement03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-01: Bell01Icon; <Icons.Interface.Bell01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-02: Bell02Icon; <Icons.Interface.Bell02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-03: Bell03Icon; <Icons.Interface.Bell03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-04: Bell04Icon; <Icons.Interface.Bell04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-minus: BellMinusIcon; <Icons.Interface.BellMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-off-01: BellOff01Icon; <Icons.Interface.BellOff01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-off-02: BellOff02Icon; <Icons.Interface.BellOff02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-off-03: BellOff03Icon; <Icons.Interface.BellOff03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-plus: BellPlusIcon; <Icons.Interface.BellPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-ringing-01: BellRinging01Icon; <Icons.Interface.BellRinging01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-ringing-02: BellRinging02Icon; <Icons.Interface.BellRinging02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-ringing-03: BellRinging03Icon; <Icons.Interface.BellRinging03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bell-ringing-04: BellRinging04Icon; <Icons.Interface.BellRinging04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bookmark: BookmarkIcon; <Icons.Interface.Bookmark />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bookmark-add: BookmarkAddIcon; <Icons.Interface.BookmarkAdd />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bookmark-check: BookmarkCheckIcon; <Icons.Interface.BookmarkCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bookmark-minus: BookmarkMinusIcon; <Icons.Interface.BookmarkMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bookmark-x: BookmarkXIcon; <Icons.Interface.BookmarkX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check: CheckIcon; <Icons.Interface.Check />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-circle: CheckCircleIcon; <Icons.Interface.CheckCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-circle-broken: CheckCircleBrokenIcon; <Icons.Interface.CheckCircleBroken />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-done-01: CheckDone01Icon; <Icons.Interface.CheckDone01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-done-02: CheckDone02Icon; <Icons.Interface.CheckDone02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-heart: CheckHeartIcon; <Icons.Interface.CheckHeart />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-square: CheckSquareIcon; <Icons.Interface.CheckSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-square-broken: CheckSquareBrokenIcon; <Icons.Interface.CheckSquareBroken />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-verified-01: CheckVerified01Icon; <Icons.Interface.CheckVerified01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-verified-02: CheckVerified02Icon; <Icons.Interface.CheckVerified02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

check-verified-03: CheckVerified03Icon; <Icons.Interface.CheckVerified03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flag-01: Flag01Icon; <Icons.Interface.Flag01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flag-02: Flag02Icon; <Icons.Interface.Flag02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flag-03: Flag03Icon; <Icons.Interface.Flag03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flag-04: Flag04Icon; <Icons.Interface.Flag04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flag-05: Flag05Icon; <Icons.Interface.Flag05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flag-06: Flag06Icon; <Icons.Interface.Flag06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart: HeartIcon; <Icons.Interface.Heart />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart-circle: HeartCircleIcon; <Icons.Interface.HeartCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart-hand: HeartHandIcon; <Icons.Interface.HeartHand />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart-hexagon: HeartHexagonIcon; <Icons.Interface.HeartHexagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart-octagon: HeartOctagonIcon; <Icons.Interface.HeartOctagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart-rounded: HeartRoundedIcon; <Icons.Interface.HeartRounded />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heart-square: HeartSquareIcon; <Icons.Interface.HeartSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hearts: HeartsIcon; <Icons.Interface.Hearts />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

help-circle: HelpCircleIcon; <Icons.Interface.HelpCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

help-hexagon: HelpHexagonIcon; <Icons.Interface.HelpHexagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

help-octagon: HelpOctagonIcon; <Icons.Interface.HelpOctagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

help-square: HelpSquareIcon; <Icons.Interface.HelpSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

info-circle: InfoCircleIcon; <Icons.Interface.InfoCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

info-hexagon: InfoHexagonIcon; <Icons.Interface.InfoHexagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

info-octagon: InfoOctagonIcon; <Icons.Interface.InfoOctagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

info-square: InfoSquareIcon; <Icons.Interface.InfoSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

loading-01: Loading01Icon; <Icons.Interface.Loading01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

loading-02: Loading02Icon; <Icons.Interface.Loading02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

loading-03: Loading03Icon; <Icons.Interface.Loading03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

notification-box: NotificationBoxIcon; <Icons.Interface.NotificationBox />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

notification-message: NotificationMessageIcon; <Icons.Interface.NotificationMessage />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

notification-text: NotificationTextIcon; <Icons.Interface.NotificationText />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

slash-circle-01: SlashCircle01Icon; <Icons.Interface.SlashCircle01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

slash-circle-02: SlashCircle02Icon; <Icons.Interface.SlashCircle02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

slash-divider: SlashDividerIcon; <Icons.Interface.SlashDivider />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

slash-octagon: SlashOctagonIcon; <Icons.Interface.SlashOctagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-01: Star01Icon; <Icons.Interface.Star01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-02: Star02Icon; <Icons.Interface.Star02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-03: Star03Icon; <Icons.Interface.Star03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-04: Star04Icon; <Icons.Interface.Star04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-05: Star05Icon; <Icons.Interface.Star05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-06: Star06Icon; <Icons.Interface.Star06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

star-07: Star07Icon; <Icons.Interface.Star07 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stars-01: Stars01Icon; <Icons.Interface.Stars01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stars-02: Stars02Icon; <Icons.Interface.Stars02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stars-03: Stars03Icon; <Icons.Interface.Stars03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thumbs-down: ThumbsDownIcon; <Icons.Interface.ThumbsDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thumbs-up: ThumbsUpIcon; <Icons.Interface.ThumbsUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

x: XIcon; <Icons.Interface.X />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

x-circle: XCircleIcon; <Icons.Interface.XCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

x-close: XCloseIcon; <Icons.Interface.XClose />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

x-square: XSquareIcon; <Icons.Interface.XSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-block-down: ArrowBlockDownIcon; <Icons.Interface.ArrowBlockDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-block-left: ArrowBlockLeftIcon; <Icons.Interface.ArrowBlockLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-block-right: ArrowBlockRightIcon; <Icons.Interface.ArrowBlockRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-block-up: ArrowBlockUpIcon; <Icons.Interface.ArrowBlockUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-down: ArrowCircleBrokenDownIcon; <Icons.Interface.ArrowCircleBrokenDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-down-left: ArrowCircleBrokenDownLeftIcon; <Icons.Interface.ArrowCircleBrokenDownLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-down-right: ArrowCircleBrokenDownRightIcon; <Icons.Interface.ArrowCircleBrokenDownRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-left: ArrowCircleBrokenLeftIcon; <Icons.Interface.ArrowCircleBrokenLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-right: ArrowCircleBrokenRightIcon; <Icons.Interface.ArrowCircleBrokenRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-up: ArrowCircleBrokenUpIcon; <Icons.Interface.ArrowCircleBrokenUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-up-left: ArrowCircleBrokenUpLeftIcon; <Icons.Interface.ArrowCircleBrokenUpLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-broken-up-right: ArrowCircleBrokenUpRightIcon; <Icons.Interface.ArrowCircleBrokenUpRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-down: ArrowCircleDownIcon; <Icons.Interface.ArrowCircleDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-down-left: ArrowCircleDownLeftIcon; <Icons.Interface.ArrowCircleDownLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-down-right: ArrowCircleDownRightIcon; <Icons.Interface.ArrowCircleDownRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-left: ArrowCircleLeftIcon; <Icons.Interface.ArrowCircleLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-right: ArrowCircleRightIcon; <Icons.Interface.ArrowCircleRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-up: ArrowCircleUpIcon; <Icons.Interface.ArrowCircleUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-up-left: ArrowCircleUpLeftIcon; <Icons.Interface.ArrowCircleUpLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-circle-up-right: ArrowCircleUpRightIcon; <Icons.Interface.ArrowCircleUpRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-down: ArrowDownIcon; <Icons.Interface.ArrowDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-down-left: ArrowDownLeftIcon; <Icons.Interface.ArrowDownLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-down-right: ArrowDownRightIcon; <Icons.Interface.ArrowDownRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-left: ArrowLeftIcon; <Icons.Interface.ArrowLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-down: ArrowNarrowDownIcon; <Icons.Interface.ArrowNarrowDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-down-left: ArrowNarrowDownLeftIcon; <Icons.Interface.ArrowNarrowDownLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-down-right: ArrowNarrowDownRightIcon; <Icons.Interface.ArrowNarrowDownRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-left: ArrowNarrowLeftIcon; <Icons.Interface.ArrowNarrowLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-right: ArrowNarrowRightIcon; <Icons.Interface.ArrowNarrowRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-up: ArrowNarrowUpIcon; <Icons.Interface.ArrowNarrowUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-up-left: ArrowNarrowUpLeftIcon; <Icons.Interface.ArrowNarrowUpLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-narrow-up-right: ArrowNarrowUpRightIcon; <Icons.Interface.ArrowNarrowUpRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-right: ArrowRightIcon; <Icons.Interface.ArrowRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-down: ArrowSquareDownIcon; <Icons.Interface.ArrowSquareDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-down-left: ArrowSquareDownLeftIcon; <Icons.Interface.ArrowSquareDownLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-down-right: ArrowSquareDownRightIcon; <Icons.Interface.ArrowSquareDownRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-left: ArrowSquareLeftIcon; <Icons.Interface.ArrowSquareLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-right: ArrowSquareRightIcon; <Icons.Interface.ArrowSquareRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-up: ArrowSquareUpIcon; <Icons.Interface.ArrowSquareUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-up-left: ArrowSquareUpLeftIcon; <Icons.Interface.ArrowSquareUpLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-square-up-right: ArrowSquareUpRightIcon; <Icons.Interface.ArrowSquareUpRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-up: ArrowUpIcon; <Icons.Interface.ArrowUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-up-left: ArrowUpLeftIcon; <Icons.Interface.ArrowUpLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrow-up-right: ArrowUpRightIcon; <Icons.Interface.ArrowUpRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrows-down: ArrowsDownIcon; <Icons.Interface.ArrowsDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrows-left: ArrowsLeftIcon; <Icons.Interface.ArrowsLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrows-right: ArrowsRightIcon; <Icons.Interface.ArrowsRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrows-triangle: ArrowsTriangleIcon; <Icons.Interface.ArrowsTriangle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

arrows-up: ArrowsUpIcon; <Icons.Interface.ArrowsUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-down: ChevronDownIcon; <Icons.Interface.ChevronDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-down-double: ChevronDownDoubleIcon; <Icons.Interface.ChevronDownDouble />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-left: ChevronLeftIcon; <Icons.Interface.ChevronLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-left-double: ChevronLeftDoubleIcon; <Icons.Interface.ChevronLeftDouble />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-right: ChevronRightIcon; <Icons.Interface.ChevronRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-right-double: ChevronRightDoubleIcon; <Icons.Interface.ChevronRightDouble />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-selector-horizontal: ChevronSelectorHorizontalIcon; <Icons.Interface.ChevronSelectorHorizontal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-selector-vertical: ChevronSelectorVerticalIcon; <Icons.Interface.ChevronSelectorVertical />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-up: ChevronUpIcon; <Icons.Interface.ChevronUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chevron-up-double: ChevronUpDoubleIcon; <Icons.Interface.ChevronUpDouble />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-down-left: CornerDownLeftIcon; <Icons.Interface.CornerDownLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-down-right: CornerDownRightIcon; <Icons.Interface.CornerDownRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-left-down: CornerLeftDownIcon; <Icons.Interface.CornerLeftDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-left-up: CornerLeftUpIcon; <Icons.Interface.CornerLeftUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-right-down: CornerRightDownIcon; <Icons.Interface.CornerRightDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-right-up: CornerRightUpIcon; <Icons.Interface.CornerRightUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-up-left: CornerUpLeftIcon; <Icons.Interface.CornerUpLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

corner-up-right: CornerUpRightIcon; <Icons.Interface.CornerUpRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

expand-01: Expand01Icon; <Icons.Interface.Expand01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

expand-02: Expand02Icon; <Icons.Interface.Expand02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

expand-03: Expand03Icon; <Icons.Interface.Expand03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

expand-04: Expand04Icon; <Icons.Interface.Expand04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

expand-05: Expand05Icon; <Icons.Interface.Expand05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

expand-06: Expand06Icon; <Icons.Interface.Expand06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-in-01: LogIn01Icon; <Icons.Interface.LogIn01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-in-02: LogIn02Icon; <Icons.Interface.LogIn02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-in-03: LogIn03Icon; <Icons.Interface.LogIn03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-in-04: LogIn04Icon; <Icons.Interface.LogIn04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-out-01: LogOut01Icon; <Icons.Interface.LogOut01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-out-02: LogOut02Icon; <Icons.Interface.LogOut02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-out-03: LogOut03Icon; <Icons.Interface.LogOut03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

log-out-04: LogOut04Icon; <Icons.Interface.LogOut04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

maximize-01: Maximize01Icon; <Icons.Interface.Maximize01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

maximize-02: Maximize02Icon; <Icons.Interface.Maximize02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

minimize-01: Minimize01Icon; <Icons.Interface.Minimize01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

minimize-02: Minimize02Icon; <Icons.Interface.Minimize02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

navigation-pointer-01: NavigationPointer01Icon; <Icons.Interface.NavigationPointer01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

navigation-pointer-02: NavigationPointer02Icon; <Icons.Interface.NavigationPointer02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

navigation-pointer-off-01: NavigationPointerOff01Icon; <Icons.Interface.NavigationPointerOff01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

navigation-pointer-off-02: NavigationPointerOff02Icon; <Icons.Interface.NavigationPointerOff02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-ccw-01: RefreshCcw01Icon; <Icons.Interface.RefreshCcw01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-ccw-02: RefreshCcw02Icon; <Icons.Interface.RefreshCcw02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-ccw-03: RefreshCcw03Icon; <Icons.Interface.RefreshCcw03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-ccw-04: RefreshCcw04Icon; <Icons.Interface.RefreshCcw04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-ccw-05: RefreshCcw05Icon; <Icons.Interface.RefreshCcw05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-cw-01: RefreshCw01Icon; <Icons.Interface.RefreshCw01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-cw-02: RefreshCw02Icon; <Icons.Interface.RefreshCw02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-cw-03: RefreshCw03Icon; <Icons.Interface.RefreshCw03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-cw-04: RefreshCw04Icon; <Icons.Interface.RefreshCw04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

refresh-cw-05: RefreshCw05Icon; <Icons.Interface.RefreshCw05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

repeat-01: Repeat01Icon; <Icons.Interface.Repeat01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

repeat-02: Repeat02Icon; <Icons.Interface.Repeat02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

repeat-03: Repeat03Icon; <Icons.Interface.Repeat03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

repeat-04: Repeat04Icon; <Icons.Interface.Repeat04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

reverse-left: ReverseLeftIcon; <Icons.Interface.ReverseLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

reverse-right: ReverseRightIcon; <Icons.Interface.ReverseRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

switch-horizontal-01: SwitchHorizontal01Icon; <Icons.Interface.SwitchHorizontal01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

switch-horizontal-02: SwitchHorizontal02Icon; <Icons.Interface.SwitchHorizontal02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

switch-vertical-01: SwitchVertical01Icon; <Icons.Interface.SwitchVertical01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

switch-vertical-02: SwitchVertical02Icon; <Icons.Interface.SwitchVertical02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

activity: ActivityIcon; <Icons.Interface.Activity />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

activity-heart: ActivityHeartIcon; <Icons.Interface.ActivityHeart />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-01: BarChart01Icon; <Icons.Interface.BarChart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-02: BarChart02Icon; <Icons.Interface.BarChart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-03: BarChart03Icon; <Icons.Interface.BarChart03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-04: BarChart04Icon; <Icons.Interface.BarChart04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-05: BarChart05Icon; <Icons.Interface.BarChart05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-06: BarChart06Icon; <Icons.Interface.BarChart06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-07: BarChart07Icon; <Icons.Interface.BarChart07 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-08: BarChart08Icon; <Icons.Interface.BarChart08 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-09: BarChart09Icon; <Icons.Interface.BarChart09 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-10: BarChart10Icon; <Icons.Interface.BarChart10 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-11: BarChart11Icon; <Icons.Interface.BarChart11 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-12: BarChart12Icon; <Icons.Interface.BarChart12 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-circle-01: BarChartCircle01Icon; <Icons.Interface.BarChartCircle01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-circle-02: BarChartCircle02Icon; <Icons.Interface.BarChartCircle02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-circle-03: BarChartCircle03Icon; <Icons.Interface.BarChartCircle03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-01: BarChartSquare01Icon; <Icons.Interface.BarChartSquare01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-02: BarChartSquare02Icon; <Icons.Interface.BarChartSquare02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-03: BarChartSquare03Icon; <Icons.Interface.BarChartSquare03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-down: BarChartSquareDownIcon; <Icons.Interface.BarChartSquareDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-minus: BarChartSquareMinusIcon; <Icons.Interface.BarChartSquareMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-plus: BarChartSquarePlusIcon; <Icons.Interface.BarChartSquarePlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-chart-square-up: BarChartSquareUpIcon; <Icons.Interface.BarChartSquareUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bar-line-chart: BarLineChartIcon; <Icons.Interface.BarLineChart />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chart-breakout-circle: ChartBreakoutCircleIcon; <Icons.Interface.ChartBreakoutCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chart-breakout-square: ChartBreakoutSquareIcon; <Icons.Interface.ChartBreakoutSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

data: DataIcon; <Icons.Interface.Data />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

horizontal-bar-chart-01: HorizontalBarChart01Icon; <Icons.Interface.HorizontalBarChart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

horizontal-bar-chart-02: HorizontalBarChart02Icon; <Icons.Interface.HorizontalBarChart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

horizontal-bar-chart-03: HorizontalBarChart03Icon; <Icons.Interface.HorizontalBarChart03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-down-01: LineChartDown01Icon; <Icons.Interface.LineChartDown01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-down-02: LineChartDown02Icon; <Icons.Interface.LineChartDown02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-down-03: LineChartDown03Icon; <Icons.Interface.LineChartDown03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-down-04: LineChartDown04Icon; <Icons.Interface.LineChartDown04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-down-05: LineChartDown05Icon; <Icons.Interface.LineChartDown05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-up-01: LineChartUp01Icon; <Icons.Interface.LineChartUp01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-up-02: LineChartUp02Icon; <Icons.Interface.LineChartUp02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-up-03: LineChartUp03Icon; <Icons.Interface.LineChartUp03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-up-04: LineChartUp04Icon; <Icons.Interface.LineChartUp04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-chart-up-05: LineChartUp05Icon; <Icons.Interface.LineChartUp05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pie-chart-01: PieChart01Icon; <Icons.Interface.PieChart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pie-chart-02: PieChart02Icon; <Icons.Interface.PieChart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pie-chart-03: PieChart03Icon; <Icons.Interface.PieChart03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pie-chart-04: PieChart04Icon; <Icons.Interface.PieChart04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

presentation-chart-01: PresentationChart01Icon; <Icons.Interface.PresentationChart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

presentation-chart-02: PresentationChart02Icon; <Icons.Interface.PresentationChart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

presentation-chart-03: PresentationChart03Icon; <Icons.Interface.PresentationChart03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trend-down-01: TrendDown01Icon; <Icons.Interface.TrendDown01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trend-down-02: TrendDown02Icon; <Icons.Interface.TrendDown02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trend-up-01: TrendUp01Icon; <Icons.Interface.TrendUp01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trend-up-02: TrendUp02Icon; <Icons.Interface.TrendUp02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation: AnnotationIcon; <Icons.Interface.Annotation />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-alert: AnnotationAlertIcon; <Icons.Interface.AnnotationAlert />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-check: AnnotationCheckIcon; <Icons.Interface.AnnotationCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-dots: AnnotationDotsIcon; <Icons.Interface.AnnotationDots />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-heart: AnnotationHeartIcon; <Icons.Interface.AnnotationHeart />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-info: AnnotationInfoIcon; <Icons.Interface.AnnotationInfo />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-plus: AnnotationPlusIcon; <Icons.Interface.AnnotationPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-question: AnnotationQuestionIcon; <Icons.Interface.AnnotationQuestion />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

annotation-x: AnnotationXIcon; <Icons.Interface.AnnotationX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

at-sign: AtSignIcon; <Icons.Interface.AtSign />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

inbox-01: Inbox01Icon; <Icons.Interface.Inbox01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

inbox-02: Inbox02Icon; <Icons.Interface.Inbox02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mail-01: Mail01Icon; <Icons.Interface.Mail01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mail-02: Mail02Icon; <Icons.Interface.Mail02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mail-03: Mail03Icon; <Icons.Interface.Mail03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mail-04: Mail04Icon; <Icons.Interface.Mail04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mail-05: Mail05Icon; <Icons.Interface.Mail05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-alert-circle: MessageAlertCircleIcon; <Icons.Interface.MessageAlertCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-alert-square: MessageAlertSquareIcon; <Icons.Interface.MessageAlertSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-chat-circle: MessageChatCircleIcon; <Icons.Interface.MessageChatCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-chat-square: MessageChatSquareIcon; <Icons.Interface.MessageChatSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-check-circle: MessageCheckCircleIcon; <Icons.Interface.MessageCheckCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-check-square: MessageCheckSquareIcon; <Icons.Interface.MessageCheckSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-circle-01: MessageCircle01Icon; <Icons.Interface.MessageCircle01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-circle-02: MessageCircle02Icon; <Icons.Interface.MessageCircle02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-dots-circle: MessageDotsCircleIcon; <Icons.Interface.MessageDotsCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-dots-square: MessageDotsSquareIcon; <Icons.Interface.MessageDotsSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-heart-circle: MessageHeartCircleIcon; <Icons.Interface.MessageHeartCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-heart-square: MessageHeartSquareIcon; <Icons.Interface.MessageHeartSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-notification-circle: MessageNotificationCircleIcon; <Icons.Interface.MessageNotificationCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-notification-square: MessageNotificationSquareIcon; <Icons.Interface.MessageNotificationSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-plus-circle: MessagePlusCircleIcon; <Icons.Interface.MessagePlusCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-plus-square: MessagePlusSquareIcon; <Icons.Interface.MessagePlusSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-question-circle: MessageQuestionCircleIcon; <Icons.Interface.MessageQuestionCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-question-square: MessageQuestionSquareIcon; <Icons.Interface.MessageQuestionSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-smile-circle: MessageSmileCircleIcon; <Icons.Interface.MessageSmileCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-smile-square: MessageSmileSquareIcon; <Icons.Interface.MessageSmileSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-square-01: MessageSquare01Icon; <Icons.Interface.MessageSquare01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-square-02: MessageSquare02Icon; <Icons.Interface.MessageSquare02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-text-circle-01: MessageTextCircle01Icon; <Icons.Interface.MessageTextCircle01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-text-circle-02: MessageTextCircle02Icon; <Icons.Interface.MessageTextCircle02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-text-square-01: MessageTextSquare01Icon; <Icons.Interface.MessageTextSquare01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-text-square-02: MessageTextSquare02Icon; <Icons.Interface.MessageTextSquare02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-x-circle: MessageXCircleIcon; <Icons.Interface.MessageXCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

message-x-square: MessageXSquareIcon; <Icons.Interface.MessageXSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone: PhoneIcon; <Icons.Interface.Phone />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-01: Phone01Icon; <Icons.Interface.Phone01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-02: Phone02Icon; <Icons.Interface.Phone02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-call-01: PhoneCall01Icon; <Icons.Interface.PhoneCall01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-call-02: PhoneCall02Icon; <Icons.Interface.PhoneCall02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-hang-up: PhoneHangUpIcon; <Icons.Interface.PhoneHangUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-incoming-01: PhoneIncoming01Icon; <Icons.Interface.PhoneIncoming01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-incoming-02: PhoneIncoming02Icon; <Icons.Interface.PhoneIncoming02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-outgoing-01: PhoneOutgoing01Icon; <Icons.Interface.PhoneOutgoing01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-outgoing-02: PhoneOutgoing02Icon; <Icons.Interface.PhoneOutgoing02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-pause: PhonePauseIcon; <Icons.Interface.PhonePause />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-plus: PhonePlusIcon; <Icons.Interface.PhonePlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

phone-x: PhoneXIcon; <Icons.Interface.PhoneX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

send-01: Send01Icon; <Icons.Interface.Send01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

send-02: Send02Icon; <Icons.Interface.Send02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

send-03: Send03Icon; <Icons.Interface.Send03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-01: Share01Icon; <Icons.Interface.Share01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-02: Share02Icon; <Icons.Interface.Share02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-03: Share03Icon; <Icons.Interface.Share03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-04: Share04Icon; <Icons.Interface.Share04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-05: Share05Icon; <Icons.Interface.Share05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-06: Share06Icon; <Icons.Interface.Share06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

share-07: Share07Icon; <Icons.Interface.Share07 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

translate-01: Translate01Icon; <Icons.Interface.Translate01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

translate-02: Translate02Icon; <Icons.Interface.Translate02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

voicemail: VoicemailIcon; <Icons.Interface.Voicemail />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets: BracketsIcon; <Icons.Interface.Brackets />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets-check: BracketsCheckIcon; <Icons.Interface.BracketsCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets-ellipses: BracketsEllipsesIcon; <Icons.Interface.BracketsEllipses />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets-minus: BracketsMinusIcon; <Icons.Interface.BracketsMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets-plus: BracketsPlusIcon; <Icons.Interface.BracketsPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets-slash: BracketsSlashIcon; <Icons.Interface.BracketsSlash />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brackets-x: BracketsXIcon; <Icons.Interface.BracketsX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

browser: BrowserIcon; <Icons.Interface.Browser />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-01: Code01Icon; <Icons.Interface.Code01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-02: Code02Icon; <Icons.Interface.Code02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-browser: CodeBrowserIcon; <Icons.Interface.CodeBrowser />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-circle-01: CodeCircle01Icon; <Icons.Interface.CodeCircle01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-circle-02: CodeCircle02Icon; <Icons.Interface.CodeCircle02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-circle-03: CodeCircle03Icon; <Icons.Interface.CodeCircle03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-snippet-01: CodeSnippet01Icon; <Icons.Interface.CodeSnippet01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-snippet-02: CodeSnippet02Icon; <Icons.Interface.CodeSnippet02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-square-01: CodeSquare01Icon; <Icons.Interface.CodeSquare01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

code-square-02: CodeSquare02Icon; <Icons.Interface.CodeSquare02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

codepen: CodepenIcon; <Icons.Interface.Codepen />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

command: CommandIcon; <Icons.Interface.Command />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

container: ContainerIcon; <Icons.Interface.Container />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cpu-chip-01: CpuChip01Icon; <Icons.Interface.CpuChip01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cpu-chip-02: CpuChip02Icon; <Icons.Interface.CpuChip02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cube-01: Cube01Icon; <Icons.Interface.Cube01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cube-02: Cube02Icon; <Icons.Interface.Cube02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cube-03: Cube03Icon; <Icons.Interface.Cube03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cube-04: Cube04Icon; <Icons.Interface.Cube04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cube-outline: CubeOutlineIcon; <Icons.Interface.CubeOutline />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

database-01: Database01Icon; <Icons.Interface.Database01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

database-02: Database02Icon; <Icons.Interface.Database02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

database-03: Database03Icon; <Icons.Interface.Database03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dataflow-01: Dataflow01Icon; <Icons.Interface.Dataflow01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dataflow-02: Dataflow02Icon; <Icons.Interface.Dataflow02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dataflow-03: Dataflow03Icon; <Icons.Interface.Dataflow03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dataflow-04: Dataflow04Icon; <Icons.Interface.Dataflow04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

git-branch-01: GitBranch01Icon; <Icons.Interface.GitBranch01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

git-branch-02: GitBranch02Icon; <Icons.Interface.GitBranch02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

git-commit: GitCommitIcon; <Icons.Interface.GitCommit />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

git-merge: GitMergeIcon; <Icons.Interface.GitMerge />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

git-pull-request: GitPullRequestIcon; <Icons.Interface.GitPullRequest />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hash-01: Hash01Icon; <Icons.Interface.Hash01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hash-02: Hash02Icon; <Icons.Interface.Hash02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

package: PackageIcon; <Icons.Interface.Package />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

package-check: PackageCheckIcon; <Icons.Interface.PackageCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

package-minus: PackageMinusIcon; <Icons.Interface.PackageMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

package-plus: PackagePlusIcon; <Icons.Interface.PackagePlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

package-search: PackageSearchIcon; <Icons.Interface.PackageSearch />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

package-x: PackageXIcon; <Icons.Interface.PackageX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

puzzle-piece-01: PuzzlePiece01Icon; <Icons.Interface.PuzzlePiece01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

puzzle-piece-02: PuzzlePiece02Icon; <Icons.Interface.PuzzlePiece02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

qr-code-01: QrCode01Icon; <Icons.Interface.QrCode01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

qr-code-02: QrCode02Icon; <Icons.Interface.QrCode02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

server-01: Server01Icon; <Icons.Interface.Server01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

server-02: Server02Icon; <Icons.Interface.Server02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

server-03: Server03Icon; <Icons.Interface.Server03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

server-04: Server04Icon; <Icons.Interface.Server04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

server-05: Server05Icon; <Icons.Interface.Server05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

server-06: Server06Icon; <Icons.Interface.Server06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

terminal: TerminalIcon; <Icons.Interface.Terminal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

terminal-browser: TerminalBrowserIcon; <Icons.Interface.TerminalBrowser />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

terminal-circle: TerminalCircleIcon; <Icons.Interface.TerminalCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

terminal-square: TerminalSquareIcon; <Icons.Interface.TerminalSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

toggle-01-left: Toggle01LeftIcon; <Icons.Interface.Toggle01Left />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

toggle-01-right: Toggle01RightIcon; <Icons.Interface.Toggle01Right />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

toggle-02-left: Toggle02LeftIcon; <Icons.Interface.Toggle02Left />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

toggle-02-right: Toggle02RightIcon; <Icons.Interface.Toggle02Right />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

toggle-03-left: Toggle03LeftIcon; <Icons.Interface.Toggle03Left />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

toggle-03-right: Toggle03RightIcon; <Icons.Interface.Toggle03Right />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

variable: VariableIcon; <Icons.Interface.Variable />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-bottom-01: AlignBottom01Icon; <Icons.Interface.AlignBottom01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-bottom-02: AlignBottom02Icon; <Icons.Interface.AlignBottom02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-center: AlignCenterIcon; <Icons.Interface.AlignCenter />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-horizontal-centre-01: AlignHorizontalCentre01Icon; <Icons.Interface.AlignHorizontalCentre01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-horizontal-centre-02: AlignHorizontalCentre02Icon; <Icons.Interface.AlignHorizontalCentre02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-justify: AlignJustifyIcon; <Icons.Interface.AlignJustify />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-left: AlignLeftIcon; <Icons.Interface.AlignLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-left-01: AlignLeft01Icon; <Icons.Interface.AlignLeft01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-left-02: AlignLeft02Icon; <Icons.Interface.AlignLeft02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-right: AlignRightIcon; <Icons.Interface.AlignRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-right-01: AlignRight01Icon; <Icons.Interface.AlignRight01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-right-02: AlignRight02Icon; <Icons.Interface.AlignRight02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-top-01: AlignTop01Icon; <Icons.Interface.AlignTop01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-top-02: AlignTop02Icon; <Icons.Interface.AlignTop02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-vertical-center-01: AlignVerticalCenter01Icon; <Icons.Interface.AlignVerticalCenter01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

align-vertical-center-02: AlignVerticalCenter02Icon; <Icons.Interface.AlignVerticalCenter02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

attachment-01: Attachment01Icon; <Icons.Interface.Attachment01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

attachment-02: Attachment02Icon; <Icons.Interface.Attachment02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bezier-curve-01: BezierCurve01Icon; <Icons.Interface.BezierCurve01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bezier-curve-02: BezierCurve02Icon; <Icons.Interface.BezierCurve02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bezier-curve-03: BezierCurve03Icon; <Icons.Interface.BezierCurve03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bold-01: Bold01Icon; <Icons.Interface.Bold01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bold-02: Bold02Icon; <Icons.Interface.Bold02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bold-square: BoldSquareIcon; <Icons.Interface.BoldSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brush-01: Brush01Icon; <Icons.Interface.Brush01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brush-02: Brush02Icon; <Icons.Interface.Brush02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

brush-03: Brush03Icon; <Icons.Interface.Brush03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

colors: ColorsIcon; <Icons.Interface.Colors />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

colors-1: Colors1Icon; <Icons.Interface.Colors1 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-01: Copy01Icon; <Icons.Interface.Copy01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-02: Copy02Icon; <Icons.Interface.Copy02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-03: Copy03Icon; <Icons.Interface.Copy03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-04: Copy04Icon; <Icons.Interface.Copy04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-05: Copy05Icon; <Icons.Interface.Copy05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-06: Copy06Icon; <Icons.Interface.Copy06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

copy-07: Copy07Icon; <Icons.Interface.Copy07 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

crop-01: Crop01Icon; <Icons.Interface.Crop01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

crop-02: Crop02Icon; <Icons.Interface.Crop02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-01: Cursor01Icon; <Icons.Interface.Cursor01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-02: Cursor02Icon; <Icons.Interface.Cursor02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-03: Cursor03Icon; <Icons.Interface.Cursor03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-04: Cursor04Icon; <Icons.Interface.Cursor04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-box: CursorBoxIcon; <Icons.Interface.CursorBox />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-click-01: CursorClick01Icon; <Icons.Interface.CursorClick01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cursor-click-02: CursorClick02Icon; <Icons.Interface.CursorClick02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

delete: DeleteIcon; <Icons.Interface.Delete />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

distribute-spacing-horizontal: DistributeSpacingHorizontalIcon; <Icons.Interface.DistributeSpacingHorizontal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

distribute-spacing-vertical: DistributeSpacingVerticalIcon; <Icons.Interface.DistributeSpacingVertical />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dotpoints-01: Dotpoints01Icon; <Icons.Interface.Dotpoints01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dotpoints-02: Dotpoints02Icon; <Icons.Interface.Dotpoints02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

drop: DropIcon; <Icons.Interface.Drop />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

droplets-01: Droplets01Icon; <Icons.Interface.Droplets01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

droplets-02: Droplets02Icon; <Icons.Interface.Droplets02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

droplets-03: Droplets03Icon; <Icons.Interface.Droplets03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dropper: DropperIcon; <Icons.Interface.Dropper />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

edit-01: Edit01Icon; <Icons.Interface.Edit01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

edit-02: Edit02Icon; <Icons.Interface.Edit02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

edit-03: Edit03Icon; <Icons.Interface.Edit03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

edit-04: Edit04Icon; <Icons.Interface.Edit04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

edit-05: Edit05Icon; <Icons.Interface.Edit05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

eraser: EraserIcon; <Icons.Interface.Eraser />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

feather: FeatherIcon; <Icons.Interface.Feather />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

figma: FigmaIcon; <Icons.Interface.Figma />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flip-backward: FlipBackwardIcon; <Icons.Interface.FlipBackward />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flip-forward: FlipForwardIcon; <Icons.Interface.FlipForward />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

framer: FramerIcon; <Icons.Interface.Framer />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heading-01: Heading01Icon; <Icons.Interface.Heading01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heading-02: Heading02Icon; <Icons.Interface.Heading02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

heading-square: HeadingSquareIcon; <Icons.Interface.HeadingSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

intersect-circle: IntersectCircleIcon; <Icons.Interface.IntersectCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

intersect-square: IntersectSquareIcon; <Icons.Interface.IntersectSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

italic-01: Italic01Icon; <Icons.Interface.Italic01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

italic-02: Italic02Icon; <Icons.Interface.Italic02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

italic-square: ItalicSquareIcon; <Icons.Interface.ItalicSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

left-indent-01: LeftIndent01Icon; <Icons.Interface.LeftIndent01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

left-indent-02: LeftIndent02Icon; <Icons.Interface.LeftIndent02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

letter-spacing-01: LetterSpacing01Icon; <Icons.Interface.LetterSpacing01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

letter-spacing-02: LetterSpacing02Icon; <Icons.Interface.LetterSpacing02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

line-height: LineHeightIcon; <Icons.Interface.LineHeight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-01: Link01Icon; <Icons.Interface.Link01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-02: Link02Icon; <Icons.Interface.Link02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-03: Link03Icon; <Icons.Interface.Link03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-04: Link04Icon; <Icons.Interface.Link04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-05: Link05Icon; <Icons.Interface.Link05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-broken-01: LinkBroken01Icon; <Icons.Interface.LinkBroken01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-broken-02: LinkBroken02Icon; <Icons.Interface.LinkBroken02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-external-01: LinkExternal01Icon; <Icons.Interface.LinkExternal01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

link-external-02: LinkExternal02Icon; <Icons.Interface.LinkExternal02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

list: ListIcon; <Icons.Interface.List />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

magic-wand-01: MagicWand01Icon; <Icons.Interface.MagicWand01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

magic-wand-02: MagicWand02Icon; <Icons.Interface.MagicWand02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

move: MoveIcon; <Icons.Interface.Move />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

paint: PaintIcon; <Icons.Interface.Paint />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

paint-pour: PaintPourIcon; <Icons.Interface.PaintPour />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

palette: PaletteIcon; <Icons.Interface.Palette />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

paragraph-spacing: ParagraphSpacingIcon; <Icons.Interface.ParagraphSpacing />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

paragraph-wrap: ParagraphWrapIcon; <Icons.Interface.ParagraphWrap />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pen-tool-01: PenTool01Icon; <Icons.Interface.PenTool01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pen-tool-02: PenTool02Icon; <Icons.Interface.PenTool02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pen-tool-minus: PenToolMinusIcon; <Icons.Interface.PenToolMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pen-tool-plus: PenToolPlusIcon; <Icons.Interface.PenToolPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pencil-01: Pencil01Icon; <Icons.Interface.Pencil01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pencil-02: Pencil02Icon; <Icons.Interface.Pencil02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pencil-line: PencilLineIcon; <Icons.Interface.PencilLine />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

perspective-01: Perspective01Icon; <Icons.Interface.Perspective01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

perspective-02: Perspective02Icon; <Icons.Interface.Perspective02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pilcrow-01: Pilcrow01Icon; <Icons.Interface.Pilcrow01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pilcrow-02: Pilcrow02Icon; <Icons.Interface.Pilcrow02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pilcrow-square: PilcrowSquareIcon; <Icons.Interface.PilcrowSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

reflect-01: Reflect01Icon; <Icons.Interface.Reflect01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

reflect-02: Reflect02Icon; <Icons.Interface.Reflect02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

right-indent-01: RightIndent01Icon; <Icons.Interface.RightIndent01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

right-indent-02: RightIndent02Icon; <Icons.Interface.RightIndent02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

roller-brush: RollerBrushIcon; <Icons.Interface.RollerBrush />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

ruler: RulerIcon; <Icons.Interface.Ruler />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scale-01: Scale01Icon; <Icons.Interface.Scale01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scale-02: Scale02Icon; <Icons.Interface.Scale02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scale-03: Scale03Icon; <Icons.Interface.Scale03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scissors-01: Scissors01Icon; <Icons.Interface.Scissors01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scissors-02: Scissors02Icon; <Icons.Interface.Scissors02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scissors-cut-01: ScissorsCut01Icon; <Icons.Interface.ScissorsCut01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scissors-cut-02: ScissorsCut02Icon; <Icons.Interface.ScissorsCut02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

skew: SkewIcon; <Icons.Interface.Skew />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

spacing-height-01: SpacingHeight01Icon; <Icons.Interface.SpacingHeight01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

spacing-height-02: SpacingHeight02Icon; <Icons.Interface.SpacingHeight02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

spacing-width-01: SpacingWidth01Icon; <Icons.Interface.SpacingWidth01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

spacing-width-02: SpacingWidth02Icon; <Icons.Interface.SpacingWidth02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

strikethrough-01: Strikethrough01Icon; <Icons.Interface.Strikethrough01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

strikethrough-02: Strikethrough02Icon; <Icons.Interface.Strikethrough02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

strikethrough-square: StrikethroughSquareIcon; <Icons.Interface.StrikethroughSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

subscript: SubscriptIcon; <Icons.Interface.Subscript />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

text-input: TextInputIcon; <Icons.Interface.TextInput />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

transform: TransformIcon; <Icons.Interface.Transform />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

type-01: Type01Icon; <Icons.Interface.Type01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

type-02: Type02Icon; <Icons.Interface.Type02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

type-square: TypeSquareIcon; <Icons.Interface.TypeSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

type-strikethrough-01: TypeStrikethrough01Icon; <Icons.Interface.TypeStrikethrough01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

type-strikethrough-02: TypeStrikethrough02Icon; <Icons.Interface.TypeStrikethrough02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

underline-01: Underline01Icon; <Icons.Interface.Underline01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

underline-02: Underline02Icon; <Icons.Interface.Underline02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

underline-square: UnderlineSquareIcon; <Icons.Interface.UnderlineSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zoom-in: ZoomInIcon; <Icons.Interface.ZoomIn />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

zoom-out: ZoomOutIcon; <Icons.Interface.ZoomOut />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

atom-01: Atom01Icon; <Icons.Interface.Atom01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

atom-02: Atom02Icon; <Icons.Interface.Atom02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

award-01: Award01Icon; <Icons.Interface.Award01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

award-02: Award02Icon; <Icons.Interface.Award02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

award-03: Award03Icon; <Icons.Interface.Award03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

award-04: Award04Icon; <Icons.Interface.Award04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

award-05: Award05Icon; <Icons.Interface.Award05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

backpack: BackpackIcon; <Icons.Interface.Backpack />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

beaker-01: Beaker01Icon; <Icons.Interface.Beaker01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

beaker-02: Beaker02Icon; <Icons.Interface.Beaker02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

book-closed: BookClosedIcon; <Icons.Interface.BookClosed />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

book-open-01: BookOpen01Icon; <Icons.Interface.BookOpen01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

book-open-02: BookOpen02Icon; <Icons.Interface.BookOpen02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

briefcase-01: Briefcase01Icon; <Icons.Interface.Briefcase01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

briefcase-02: Briefcase02Icon; <Icons.Interface.Briefcase02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calculator: CalculatorIcon; <Icons.Interface.Calculator />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

certificate-01: Certificate01Icon; <Icons.Interface.Certificate01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

certificate-02: Certificate02Icon; <Icons.Interface.Certificate02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

glasses-01: Glasses01Icon; <Icons.Interface.Glasses01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

glasses-02: Glasses02Icon; <Icons.Interface.Glasses02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

graduation-hat-01: GraduationHat01Icon; <Icons.Interface.GraduationHat01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

graduation-hat-02: GraduationHat02Icon; <Icons.Interface.GraduationHat02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightbulb-01: Lightbulb01Icon; <Icons.Interface.Lightbulb01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightbulb-02: Lightbulb02Icon; <Icons.Interface.Lightbulb02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightbulb-03: Lightbulb03Icon; <Icons.Interface.Lightbulb03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightbulb-04: Lightbulb04Icon; <Icons.Interface.Lightbulb04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightbulb-05: Lightbulb05Icon; <Icons.Interface.Lightbulb05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

microscope: MicroscopeIcon; <Icons.Interface.Microscope />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stand: StandIcon; <Icons.Interface.Stand />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

telescope: TelescopeIcon; <Icons.Interface.Telescope />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trophy-01: Trophy01Icon; <Icons.Interface.Trophy01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

trophy-02: Trophy02Icon; <Icons.Interface.Trophy02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

archive: ArchiveIcon; <Icons.Interface.Archive />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

box: BoxIcon; <Icons.Interface.Box />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard: ClipboardIcon; <Icons.Interface.Clipboard />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard-attachment: ClipboardAttachmentIcon; <Icons.Interface.ClipboardAttachment />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard-check: ClipboardCheckIcon; <Icons.Interface.ClipboardCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard-download: ClipboardDownloadIcon; <Icons.Interface.ClipboardDownload />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard-minus: ClipboardMinusIcon; <Icons.Interface.ClipboardMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard-plus: ClipboardPlusIcon; <Icons.Interface.ClipboardPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clipboard-x: ClipboardXIcon; <Icons.Interface.ClipboardX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

download-01: Download01Icon; <Icons.Interface.Download01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

download-02: Download02Icon; <Icons.Interface.Download02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

download-03: Download03Icon; <Icons.Interface.Download03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

download-04: Download04Icon; <Icons.Interface.Download04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

download-cloud-01: DownloadCloud01Icon; <Icons.Interface.DownloadCloud01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

download-cloud-02: DownloadCloud02Icon; <Icons.Interface.DownloadCloud02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-01: File01Icon; <Icons.Interface.File01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-02: File02Icon; <Icons.Interface.File02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-03: File03Icon; <Icons.Interface.File03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-04: File04Icon; <Icons.Interface.File04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-05: File05Icon; <Icons.Interface.File05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-06: File06Icon; <Icons.Interface.File06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-07: File07Icon; <Icons.Interface.File07 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-attachment-01: FileAttachment01Icon; <Icons.Interface.FileAttachment01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-attachment-02: FileAttachment02Icon; <Icons.Interface.FileAttachment02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-attachment-03: FileAttachment03Icon; <Icons.Interface.FileAttachment03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-attachment-04: FileAttachment04Icon; <Icons.Interface.FileAttachment04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-attachment-05: FileAttachment05Icon; <Icons.Interface.FileAttachment05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-check-01: FileCheck01Icon; <Icons.Interface.FileCheck01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-check-02: FileCheck02Icon; <Icons.Interface.FileCheck02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-check-03: FileCheck03Icon; <Icons.Interface.FileCheck03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-code-01: FileCode01Icon; <Icons.Interface.FileCode01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-code-02: FileCode02Icon; <Icons.Interface.FileCode02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-download-01: FileDownload01Icon; <Icons.Interface.FileDownload01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-download-02: FileDownload02Icon; <Icons.Interface.FileDownload02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-download-03: FileDownload03Icon; <Icons.Interface.FileDownload03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-heart-01: FileHeart01Icon; <Icons.Interface.FileHeart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-heart-02: FileHeart02Icon; <Icons.Interface.FileHeart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-heart-03: FileHeart03Icon; <Icons.Interface.FileHeart03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-lock-01: FileLock01Icon; <Icons.Interface.FileLock01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-lock-02: FileLock02Icon; <Icons.Interface.FileLock02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-lock-03: FileLock03Icon; <Icons.Interface.FileLock03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-minus-01: FileMinus01Icon; <Icons.Interface.FileMinus01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-minus-02: FileMinus02Icon; <Icons.Interface.FileMinus02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-minus-03: FileMinus03Icon; <Icons.Interface.FileMinus03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-plus-01: FilePlus01Icon; <Icons.Interface.FilePlus01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-plus-02: FilePlus02Icon; <Icons.Interface.FilePlus02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-plus-03: FilePlus03Icon; <Icons.Interface.FilePlus03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-question-01: FileQuestion01Icon; <Icons.Interface.FileQuestion01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-question-02: FileQuestion02Icon; <Icons.Interface.FileQuestion02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-question-03: FileQuestion03Icon; <Icons.Interface.FileQuestion03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-search-01: FileSearch01Icon; <Icons.Interface.FileSearch01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-search-02: FileSearch02Icon; <Icons.Interface.FileSearch02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-search-03: FileSearch03Icon; <Icons.Interface.FileSearch03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-shield-01: FileShield01Icon; <Icons.Interface.FileShield01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-shield-02: FileShield02Icon; <Icons.Interface.FileShield02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-shield-03: FileShield03Icon; <Icons.Interface.FileShield03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-x01: FileX01Icon; <Icons.Interface.FileX01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-x02: FileX02Icon; <Icons.Interface.FileX02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

file-x03: FileX03Icon; <Icons.Interface.FileX03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder: FolderIcon; <Icons.Interface.Folder />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-check: FolderCheckIcon; <Icons.Interface.FolderCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-closed: FolderClosedIcon; <Icons.Interface.FolderClosed />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-code: FolderCodeIcon; <Icons.Interface.FolderCode />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-download: FolderDownloadIcon; <Icons.Interface.FolderDownload />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-lock: FolderLockIcon; <Icons.Interface.FolderLock />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-minus: FolderMinusIcon; <Icons.Interface.FolderMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-plus: FolderPlusIcon; <Icons.Interface.FolderPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-question: FolderQuestionIcon; <Icons.Interface.FolderQuestion />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-search: FolderSearchIcon; <Icons.Interface.FolderSearch />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-shield: FolderShieldIcon; <Icons.Interface.FolderShield />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

folder-x: FolderXIcon; <Icons.Interface.FolderX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

paperclip: PaperclipIcon; <Icons.Interface.Paperclip />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

save-01: Save01Icon; <Icons.Interface.Save01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

save-02: Save02Icon; <Icons.Interface.Save02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

save-03: Save03Icon; <Icons.Interface.Save03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sticker-circle: StickerCircleIcon; <Icons.Interface.StickerCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sticker-square: StickerSquareIcon; <Icons.Interface.StickerSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

upload-01: Upload01Icon; <Icons.Interface.Upload01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

upload-02: Upload02Icon; <Icons.Interface.Upload02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

upload-03: Upload03Icon; <Icons.Interface.Upload03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

upload-04: Upload04Icon; <Icons.Interface.Upload04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

upload-cloud-01: UploadCloud01Icon; <Icons.Interface.UploadCloud01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

upload-cloud-02: UploadCloud02Icon; <Icons.Interface.UploadCloud02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bank: BankIcon; <Icons.Interface.Bank />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bank-note-01: BankNote01Icon; <Icons.Interface.BankNote01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bank-note-02: BankNote02Icon; <Icons.Interface.BankNote02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bank-note-03: BankNote03Icon; <Icons.Interface.BankNote03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-01: Coins01Icon; <Icons.Interface.Coins01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-02: Coins02Icon; <Icons.Interface.Coins02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-03: Coins03Icon; <Icons.Interface.Coins03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-04: Coins04Icon; <Icons.Interface.Coins04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-hand: CoinsHandIcon; <Icons.Interface.CoinsHand />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-stacked-01: CoinsStacked01Icon; <Icons.Interface.CoinsStacked01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-stacked-02: CoinsStacked02Icon; <Icons.Interface.CoinsStacked02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-stacked-03: CoinsStacked03Icon; <Icons.Interface.CoinsStacked03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-stacked-04: CoinsStacked04Icon; <Icons.Interface.CoinsStacked04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-swap-01: CoinsSwap01Icon; <Icons.Interface.CoinsSwap01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

coins-swap-02: CoinsSwap02Icon; <Icons.Interface.CoinsSwap02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-01: CreditCard01Icon; <Icons.Interface.CreditCard01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-02: CreditCard02Icon; <Icons.Interface.CreditCard02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-check: CreditCardCheckIcon; <Icons.Interface.CreditCardCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-down: CreditCardDownIcon; <Icons.Interface.CreditCardDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-download: CreditCardDownloadIcon; <Icons.Interface.CreditCardDownload />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-edit: CreditCardEditIcon; <Icons.Interface.CreditCardEdit />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-lock: CreditCardLockIcon; <Icons.Interface.CreditCardLock />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-minus: CreditCardMinusIcon; <Icons.Interface.CreditCardMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-plus: CreditCardPlusIcon; <Icons.Interface.CreditCardPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-refresh: CreditCardRefreshIcon; <Icons.Interface.CreditCardRefresh />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-search: CreditCardSearchIcon; <Icons.Interface.CreditCardSearch />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-shield: CreditCardShieldIcon; <Icons.Interface.CreditCardShield />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-up: CreditCardUpIcon; <Icons.Interface.CreditCardUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-upload: CreditCardUploadIcon; <Icons.Interface.CreditCardUpload />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

credit-card-x: CreditCardXIcon; <Icons.Interface.CreditCardX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cryptocurrency-01: Cryptocurrency01Icon; <Icons.Interface.Cryptocurrency01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cryptocurrency-02: Cryptocurrency02Icon; <Icons.Interface.Cryptocurrency02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cryptocurrency-03: Cryptocurrency03Icon; <Icons.Interface.Cryptocurrency03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cryptocurrency-04: Cryptocurrency04Icon; <Icons.Interface.Cryptocurrency04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-bitcoin: CurrencyBitcoinIcon; <Icons.Interface.CurrencyBitcoin />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-bitcoin-circle: CurrencyBitcoinCircleIcon; <Icons.Interface.CurrencyBitcoinCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-dollar: CurrencyDollarIcon; <Icons.Interface.CurrencyDollar />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-dollar-circle: CurrencyDollarCircleIcon; <Icons.Interface.CurrencyDollarCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-ethereum: CurrencyEthereumIcon; <Icons.Interface.CurrencyEthereum />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-ethereum-circle: CurrencyEthereumCircleIcon; <Icons.Interface.CurrencyEthereumCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-euro: CurrencyEuroIcon; <Icons.Interface.CurrencyEuro />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-euro-circle: CurrencyEuroCircleIcon; <Icons.Interface.CurrencyEuroCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-pound: CurrencyPoundIcon; <Icons.Interface.CurrencyPound />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-pound-circle: CurrencyPoundCircleIcon; <Icons.Interface.CurrencyPoundCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-ruble: CurrencyRubleIcon; <Icons.Interface.CurrencyRuble />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-ruble-circle: CurrencyRubleCircleIcon; <Icons.Interface.CurrencyRubleCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-rupee: CurrencyRupeeIcon; <Icons.Interface.CurrencyRupee />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-rupee-circle: CurrencyRupeeCircleIcon; <Icons.Interface.CurrencyRupeeCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-yen: CurrencyYenIcon; <Icons.Interface.CurrencyYen />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

currency-yen-circle: CurrencyYenCircleIcon; <Icons.Interface.CurrencyYenCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

diamond-01: Diamond01Icon; <Icons.Interface.Diamond01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

diamond-02: Diamond02Icon; <Icons.Interface.Diamond02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

gift-01: Gift01Icon; <Icons.Interface.Gift01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

gift-02: Gift02Icon; <Icons.Interface.Gift02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

percent-01: Percent01Icon; <Icons.Interface.Percent01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

percent-02: Percent02Icon; <Icons.Interface.Percent02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

percent-03: Percent03Icon; <Icons.Interface.Percent03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

piggy-bank-01: PiggyBank01Icon; <Icons.Interface.PiggyBank01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

piggy-bank-02: PiggyBank02Icon; <Icons.Interface.PiggyBank02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

receipt: ReceiptIcon; <Icons.Interface.Receipt />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

receipt-check: ReceiptCheckIcon; <Icons.Interface.ReceiptCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

safe: SafeIcon; <Icons.Interface.Safe />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sale-01: Sale01Icon; <Icons.Interface.Sale01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sale-02: Sale02Icon; <Icons.Interface.Sale02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sale-03: Sale03Icon; <Icons.Interface.Sale03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sale-04: Sale04Icon; <Icons.Interface.Sale04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scales-01: Scales01Icon; <Icons.Interface.Scales01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scales-02: Scales02Icon; <Icons.Interface.Scales02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shopping-bag-01: ShoppingBag01Icon; <Icons.Interface.ShoppingBag01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shopping-bag-02: ShoppingBag02Icon; <Icons.Interface.ShoppingBag02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shopping-bag-03: ShoppingBag03Icon; <Icons.Interface.ShoppingBag03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shopping-cart-01: ShoppingCart01Icon; <Icons.Interface.ShoppingCart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shopping-cart-02: ShoppingCart02Icon; <Icons.Interface.ShoppingCart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shopping-cart-03: ShoppingCart03Icon; <Icons.Interface.ShoppingCart03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tag-01: Tag01Icon; <Icons.Interface.Tag01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tag-02: Tag02Icon; <Icons.Interface.Tag02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tag-03: Tag03Icon; <Icons.Interface.Tag03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wallet-01: Wallet01Icon; <Icons.Interface.Wallet01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wallet-02: Wallet02Icon; <Icons.Interface.Wallet02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wallet-03: Wallet03Icon; <Icons.Interface.Wallet03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wallet-04: Wallet04Icon; <Icons.Interface.Wallet04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wallet-05: Wallet05Icon; <Icons.Interface.Wallet05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

camera-01: Camera01Icon; <Icons.Interface.Camera01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

camera-02: Camera02Icon; <Icons.Interface.Camera02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

camera-03: Camera03Icon; <Icons.Interface.Camera03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

camera-lens: CameraLensIcon; <Icons.Interface.CameraLens />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

camera-off: CameraOffIcon; <Icons.Interface.CameraOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

camera-plus: CameraPlusIcon; <Icons.Interface.CameraPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

contrast-01: Contrast01Icon; <Icons.Interface.Contrast01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

contrast-02: Contrast02Icon; <Icons.Interface.Contrast02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

contrast-03: Contrast03Icon; <Icons.Interface.Contrast03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

film-01: Film01Icon; <Icons.Interface.Film01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

film-02: Film02Icon; <Icons.Interface.Film02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

film-03: Film03Icon; <Icons.Interface.Film03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flash: FlashIcon; <Icons.Interface.Flash />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flash-off: FlashOffIcon; <Icons.Interface.FlashOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-01: Image01Icon; <Icons.Interface.Image01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-02: Image02Icon; <Icons.Interface.Image02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-03: Image03Icon; <Icons.Interface.Image03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-04: Image04Icon; <Icons.Interface.Image04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-05: Image05Icon; <Icons.Interface.Image05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-check: ImageCheckIcon; <Icons.Interface.ImageCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-down: ImageDownIcon; <Icons.Interface.ImageDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-indent-left: ImageIndentLeftIcon; <Icons.Interface.ImageIndentLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-indent-right: ImageIndentRightIcon; <Icons.Interface.ImageIndentRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-left: ImageLeftIcon; <Icons.Interface.ImageLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-plus: ImagePlusIcon; <Icons.Interface.ImagePlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-right: ImageRightIcon; <Icons.Interface.ImageRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-up: ImageUpIcon; <Icons.Interface.ImageUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user: ImageUserIcon; <Icons.Interface.ImageUser />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-check: ImageUserCheckIcon; <Icons.Interface.ImageUserCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-down: ImageUserDownIcon; <Icons.Interface.ImageUserDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-left: ImageUserLeftIcon; <Icons.Interface.ImageUserLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-plus: ImageUserPlusIcon; <Icons.Interface.ImageUserPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-right: ImageUserRightIcon; <Icons.Interface.ImageUserRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-up: ImageUserUpIcon; <Icons.Interface.ImageUserUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-user-x: ImageUserXIcon; <Icons.Interface.ImageUserX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

image-x: ImageXIcon; <Icons.Interface.ImageX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

columns-01: Columns01Icon; <Icons.Interface.Columns01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

columns-02: Columns02Icon; <Icons.Interface.Columns02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

columns-03: Columns03Icon; <Icons.Interface.Columns03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

divider: DividerIcon; <Icons.Interface.Divider />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dots-grid: DotsGridIcon; <Icons.Interface.DotsGrid />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dots-horizontal: DotsHorizontalIcon; <Icons.Interface.DotsHorizontal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

dots-vertical: DotsVerticalIcon; <Icons.Interface.DotsVertical />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flex-align-bottom: FlexAlignBottomIcon; <Icons.Interface.FlexAlignBottom />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flex-align-left: FlexAlignLeftIcon; <Icons.Interface.FlexAlignLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flex-align-right: FlexAlignRightIcon; <Icons.Interface.FlexAlignRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

flex-align-top: FlexAlignTopIcon; <Icons.Interface.FlexAlignTop />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-01: Grid01Icon; <Icons.Interface.Grid01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-02: Grid02Icon; <Icons.Interface.Grid02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-03: Grid03Icon; <Icons.Interface.Grid03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-blank: GridDotsBlankIcon; <Icons.Interface.GridDotsBlank />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-bottom: GridDotsBottomIcon; <Icons.Interface.GridDotsBottom />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-horizontal-center: GridDotsHorizontalCenterIcon; <Icons.Interface.GridDotsHorizontalCenter />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-left: GridDotsLeftIcon; <Icons.Interface.GridDotsLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-outer: GridDotsOuterIcon; <Icons.Interface.GridDotsOuter />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-right: GridDotsRightIcon; <Icons.Interface.GridDotsRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-top: GridDotsTopIcon; <Icons.Interface.GridDotsTop />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

grid-dots-vertical-center: GridDotsVerticalCenterIcon; <Icons.Interface.GridDotsVerticalCenter />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layer-single: LayerSingleIcon; <Icons.Interface.LayerSingle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layers-three-01: LayersThree01Icon; <Icons.Interface.LayersThree01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layers-three-02: LayersThree02Icon; <Icons.Interface.LayersThree02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layers-two-01: LayersTwo01Icon; <Icons.Interface.LayersTwo01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layers-two-02: LayersTwo02Icon; <Icons.Interface.LayersTwo02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-alt-01: LayoutAlt01Icon; <Icons.Interface.LayoutAlt01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-alt-02: LayoutAlt02Icon; <Icons.Interface.LayoutAlt02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-alt-03: LayoutAlt03Icon; <Icons.Interface.LayoutAlt03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-alt-04: LayoutAlt04Icon; <Icons.Interface.LayoutAlt04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-bottom: LayoutBottomIcon; <Icons.Interface.LayoutBottom />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-grid-01: LayoutGrid01Icon; <Icons.Interface.LayoutGrid01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-grid-02: LayoutGrid02Icon; <Icons.Interface.LayoutGrid02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-left: LayoutLeftIcon; <Icons.Interface.LayoutLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-right: LayoutRightIcon; <Icons.Interface.LayoutRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

layout-top: LayoutTopIcon; <Icons.Interface.LayoutTop />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

menu-01: Menu01Icon; <Icons.Interface.Menu01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

menu-02: Menu02Icon; <Icons.Interface.Menu02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

menu-03: Menu03Icon; <Icons.Interface.Menu03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

menu-04: Menu04Icon; <Icons.Interface.Menu04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

menu-05: Menu05Icon; <Icons.Interface.Menu05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rows-01: Rows01Icon; <Icons.Interface.Rows01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rows-02: Rows02Icon; <Icons.Interface.Rows02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rows-03: Rows03Icon; <Icons.Interface.Rows03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

table: TableIcon; <Icons.Interface.Table />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

anchor: AnchorIcon; <Icons.Interface.Anchor />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-01: Building01Icon; <Icons.Interface.Building01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-02: Building02Icon; <Icons.Interface.Building02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-03: Building03Icon; <Icons.Interface.Building03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-04: Building04Icon; <Icons.Interface.Building04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-05: Building05Icon; <Icons.Interface.Building05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-06: Building06Icon; <Icons.Interface.Building06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-07: Building07Icon; <Icons.Interface.Building07 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

building-08: Building08Icon; <Icons.Interface.Building08 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bus: BusIcon; <Icons.Interface.Bus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

car-01: Car01Icon; <Icons.Interface.Car01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

car-02: Car02Icon; <Icons.Interface.Car02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

compass: CompassIcon; <Icons.Interface.Compass />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

compass-01: Compass01Icon; <Icons.Interface.Compass01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

compass-02: Compass02Icon; <Icons.Interface.Compass02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

compass-03: Compass03Icon; <Icons.Interface.Compass03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-01: Globe01Icon; <Icons.Interface.Globe01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-02: Globe02Icon; <Icons.Interface.Globe02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-03: Globe03Icon; <Icons.Interface.Globe03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-04: Globe04Icon; <Icons.Interface.Globe04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-05: Globe05Icon; <Icons.Interface.Globe05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-06: Globe06Icon; <Icons.Interface.Globe06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-slated-01: GlobeSlated01Icon; <Icons.Interface.GlobeSlated01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

globe-slated-02: GlobeSlated02Icon; <Icons.Interface.GlobeSlated02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-01: Home01Icon; <Icons.Interface.Home01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-02: Home02Icon; <Icons.Interface.Home02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-03: Home03Icon; <Icons.Interface.Home03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-04: Home04Icon; <Icons.Interface.Home04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-05: Home05Icon; <Icons.Interface.Home05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-line: HomeLineIcon; <Icons.Interface.HomeLine />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

home-smile: HomeSmileIcon; <Icons.Interface.HomeSmile />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

luggage-01: Luggage01Icon; <Icons.Interface.Luggage01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

luggage-02: Luggage02Icon; <Icons.Interface.Luggage02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

luggage-03: Luggage03Icon; <Icons.Interface.Luggage03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

map-01: Map01Icon; <Icons.Interface.Map01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

map-02: Map02Icon; <Icons.Interface.Map02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

marker-pin-01: MarkerPin01Icon; <Icons.Interface.MarkerPin01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

marker-pin-02: MarkerPin02Icon; <Icons.Interface.MarkerPin02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

marker-pin-03: MarkerPin03Icon; <Icons.Interface.MarkerPin03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

marker-pin-04: MarkerPin04Icon; <Icons.Interface.MarkerPin04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

marker-pin-05: MarkerPin05Icon; <Icons.Interface.MarkerPin05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

marker-pin-06: MarkerPin06Icon; <Icons.Interface.MarkerPin06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

passport: PassportIcon; <Icons.Interface.Passport />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pin-01: Pin01Icon; <Icons.Interface.Pin01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pin-02: Pin02Icon; <Icons.Interface.Pin02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

plane: PlaneIcon; <Icons.Interface.Plane />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rocket-01: Rocket01Icon; <Icons.Interface.Rocket01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rocket-02: Rocket02Icon; <Icons.Interface.Rocket02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

route: RouteIcon; <Icons.Interface.Route />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

ticket-01: Ticket01Icon; <Icons.Interface.Ticket01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

ticket-02: Ticket02Icon; <Icons.Interface.Ticket02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

train: TrainIcon; <Icons.Interface.Train />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tram: TramIcon; <Icons.Interface.Tram />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

truck-01: Truck01Icon; <Icons.Interface.Truck01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

truck-02: Truck02Icon; <Icons.Interface.Truck02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

airplay: AirplayIcon; <Icons.Interface.Airplay />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

airpods: AirpodsIcon; <Icons.Interface.Airpods />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

battery-charging-01: BatteryCharging01Icon; <Icons.Interface.BatteryCharging01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

battery-charging-02: BatteryCharging02Icon; <Icons.Interface.BatteryCharging02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

battery-empty: BatteryEmptyIcon; <Icons.Interface.BatteryEmpty />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

battery-full: BatteryFullIcon; <Icons.Interface.BatteryFull />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

battery-low: BatteryLowIcon; <Icons.Interface.BatteryLow />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

battery-mid: BatteryMidIcon; <Icons.Interface.BatteryMid />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bluetooth-connect: BluetoothConnectIcon; <Icons.Interface.BluetoothConnect />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bluetooth-off: BluetoothOffIcon; <Icons.Interface.BluetoothOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bluetooth-on: BluetoothOnIcon; <Icons.Interface.BluetoothOn />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

bluetooth-signal: BluetoothSignalIcon; <Icons.Interface.BluetoothSignal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

chrome-cast: ChromeCastIcon; <Icons.Interface.ChromeCast />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clapperboard: ClapperboardIcon; <Icons.Interface.Clapperboard />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

disc-01: Disc01Icon; <Icons.Interface.Disc01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

disc-02: Disc02Icon; <Icons.Interface.Disc02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

fast-backward: FastBackwardIcon; <Icons.Interface.FastBackward />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

fast-forward: FastForwardIcon; <Icons.Interface.FastForward />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

gaming-pad-01: GamingPad01Icon; <Icons.Interface.GamingPad01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

gaming-pad-02: GamingPad02Icon; <Icons.Interface.GamingPad02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

google-chrome: GoogleChromeIcon; <Icons.Interface.GoogleChrome />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hard-drive: HardDriveIcon; <Icons.Interface.HardDrive />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

headphones-01: Headphones01Icon; <Icons.Interface.Headphones01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

headphones-02: Headphones02Icon; <Icons.Interface.Headphones02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

keyboard-01: Keyboard01Icon; <Icons.Interface.Keyboard01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

keyboard-02: Keyboard02Icon; <Icons.Interface.Keyboard02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

laptop-01: Laptop01Icon; <Icons.Interface.Laptop01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

laptop-02: Laptop02Icon; <Icons.Interface.Laptop02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

microphone-01: Microphone01Icon; <Icons.Interface.Microphone01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

microphone-02: Microphone02Icon; <Icons.Interface.Microphone02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

microphone-off-01: MicrophoneOff01Icon; <Icons.Interface.MicrophoneOff01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

microphone-off-02: MicrophoneOff02Icon; <Icons.Interface.MicrophoneOff02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

modem-01: Modem01Icon; <Icons.Interface.Modem01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

modem-02: Modem02Icon; <Icons.Interface.Modem02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

monitor-01: Monitor01Icon; <Icons.Interface.Monitor01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

monitor-02: Monitor02Icon; <Icons.Interface.Monitor02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

monitor-03: Monitor03Icon; <Icons.Interface.Monitor03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

monitor-04: Monitor04Icon; <Icons.Interface.Monitor04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

monitor-05: Monitor05Icon; <Icons.Interface.Monitor05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mouse: MouseIcon; <Icons.Interface.Mouse />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

music-note-01: MusicNote01Icon; <Icons.Interface.MusicNote01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

music-note-02: MusicNote02Icon; <Icons.Interface.MusicNote02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

music-note-plus: MusicNotePlusIcon; <Icons.Interface.MusicNotePlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pause-circle: PauseCircleIcon; <Icons.Interface.PauseCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pause-square: PauseSquareIcon; <Icons.Interface.PauseSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

play: PlayIcon; <Icons.Interface.Play />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

play-circle: PlayCircleIcon; <Icons.Interface.PlayCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

play-square: PlaySquareIcon; <Icons.Interface.PlaySquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

podcast: PodcastIcon; <Icons.Interface.Podcast />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

power-01: Power01Icon; <Icons.Interface.Power01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

power-02: Power02Icon; <Icons.Interface.Power02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

power-03: Power03Icon; <Icons.Interface.Power03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

printer: PrinterIcon; <Icons.Interface.Printer />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

recording-01: Recording01Icon; <Icons.Interface.Recording01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

recording-02: Recording02Icon; <Icons.Interface.Recording02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

recording-03: Recording03Icon; <Icons.Interface.Recording03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rss-01: Rss01Icon; <Icons.Interface.Rss01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

rss-02: Rss02Icon; <Icons.Interface.Rss02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shuffle-01: Shuffle01Icon; <Icons.Interface.Shuffle01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shuffle-02: Shuffle02Icon; <Icons.Interface.Shuffle02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

signal-01: Signal01Icon; <Icons.Interface.Signal01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

signal-02: Signal02Icon; <Icons.Interface.Signal02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

signal-03: Signal03Icon; <Icons.Interface.Signal03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

simcard: SimcardIcon; <Icons.Interface.Simcard />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

skip-back: SkipBackIcon; <Icons.Interface.SkipBack />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

skip-forward: SkipForwardIcon; <Icons.Interface.SkipForward />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speaker-01: Speaker01Icon; <Icons.Interface.Speaker01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speaker-02: Speaker02Icon; <Icons.Interface.Speaker02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

speaker-03: Speaker03Icon; <Icons.Interface.Speaker03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stop: StopIcon; <Icons.Interface.Stop />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stop-circle: StopCircleIcon; <Icons.Interface.StopCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stop-square: StopSquareIcon; <Icons.Interface.StopSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tablet-01: Tablet01Icon; <Icons.Interface.Tablet01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tablet-02: Tablet02Icon; <Icons.Interface.Tablet02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tv-01: Tv01Icon; <Icons.Interface.Tv01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tv-02: Tv02Icon; <Icons.Interface.Tv02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

tv-03: Tv03Icon; <Icons.Interface.Tv03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

usb-flash-drive: UsbFlashDriveIcon; <Icons.Interface.UsbFlashDrive />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

video-recorder: VideoRecorderIcon; <Icons.Interface.VideoRecorder />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

video-recorder-off: VideoRecorderOffIcon; <Icons.Interface.VideoRecorderOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

volume-max: VolumeMaxIcon; <Icons.Interface.VolumeMax />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

volume-min: VolumeMinIcon; <Icons.Interface.VolumeMin />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

volume-minus: VolumeMinusIcon; <Icons.Interface.VolumeMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

volume-plus: VolumePlusIcon; <Icons.Interface.VolumePlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

volume-x: VolumeXIcon; <Icons.Interface.VolumeX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

watch-circle: WatchCircleIcon; <Icons.Interface.WatchCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

watch-square: WatchSquareIcon; <Icons.Interface.WatchSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

webcam-01: Webcam01Icon; <Icons.Interface.Webcam01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

webcam-02: Webcam02Icon; <Icons.Interface.Webcam02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wifi: WifiIcon; <Icons.Interface.Wifi />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wifi-off: WifiOffIcon; <Icons.Interface.WifiOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

youtube: YoutubeIcon; <Icons.Interface.Youtube />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

eye: EyeIcon; <Icons.Interface.Eye />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

eye-off: EyeOffIcon; <Icons.Interface.EyeOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

fingerprint-01: Fingerprint01Icon; <Icons.Interface.Fingerprint01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

fingerprint-02: Fingerprint02Icon; <Icons.Interface.Fingerprint02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

fingerprint-03: Fingerprint03Icon; <Icons.Interface.Fingerprint03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

fingerprint-04: Fingerprint04Icon; <Icons.Interface.Fingerprint04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

key-01: Key01Icon; <Icons.Interface.Key01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

key-02: Key02Icon; <Icons.Interface.Key02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-01: Lock01Icon; <Icons.Interface.Lock01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-02: Lock02Icon; <Icons.Interface.Lock02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-03: Lock03Icon; <Icons.Interface.Lock03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-04: Lock04Icon; <Icons.Interface.Lock04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-keyhole-circle: LockKeyholeCircleIcon; <Icons.Interface.LockKeyholeCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-keyhole-square: LockKeyholeSquareIcon; <Icons.Interface.LockKeyholeSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-unlocked-01: LockUnlocked01Icon; <Icons.Interface.LockUnlocked01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-unlocked-02: LockUnlocked02Icon; <Icons.Interface.LockUnlocked02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-unlocked-03: LockUnlocked03Icon; <Icons.Interface.LockUnlocked03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lock-unlocked-04: LockUnlocked04Icon; <Icons.Interface.LockUnlocked04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

passcode: PasscodeIcon; <Icons.Interface.Passcode />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

passcode-lock: PasscodeLockIcon; <Icons.Interface.PasscodeLock />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

scan: ScanIcon; <Icons.Interface.Scan />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-01: Shield01Icon; <Icons.Interface.Shield01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-02: Shield02Icon; <Icons.Interface.Shield02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-03: Shield03Icon; <Icons.Interface.Shield03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-dollar: ShieldDollarIcon; <Icons.Interface.ShieldDollar />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-off: ShieldOffIcon; <Icons.Interface.ShieldOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-plus: ShieldPlusIcon; <Icons.Interface.ShieldPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-tick: ShieldTickIcon; <Icons.Interface.ShieldTick />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

shield-zap: ShieldZapIcon; <Icons.Interface.ShieldZap />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

circle: CircleIcon; <Icons.Interface.Circle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

circle-cut: CircleCutIcon; <Icons.Interface.CircleCut />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hexagon-01: Hexagon01Icon; <Icons.Interface.Hexagon01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hexagon-02: Hexagon02Icon; <Icons.Interface.Hexagon02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

octagon: OctagonIcon; <Icons.Interface.Octagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pentagon: PentagonIcon; <Icons.Interface.Pentagon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

square: SquareIcon; <Icons.Interface.Square />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

triangle: TriangleIcon; <Icons.Interface.Triangle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alarm-clock: AlarmClockIcon; <Icons.Interface.AlarmClock />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alarm-clock-check: AlarmClockCheckIcon; <Icons.Interface.AlarmClockCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alarm-clock-minus: AlarmClockMinusIcon; <Icons.Interface.AlarmClockMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alarm-clock-off: AlarmClockOffIcon; <Icons.Interface.AlarmClockOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

alarm-clock-plus: AlarmClockPlusIcon; <Icons.Interface.AlarmClockPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar: CalendarIcon; <Icons.Interface.Calendar />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-check-01: CalendarCheck01Icon; <Icons.Interface.CalendarCheck01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-check-02: CalendarCheck02Icon; <Icons.Interface.CalendarCheck02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-date: CalendarDateIcon; <Icons.Interface.CalendarDate />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-heart-01: CalendarHeart01Icon; <Icons.Interface.CalendarHeart01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-heart-02: CalendarHeart02Icon; <Icons.Interface.CalendarHeart02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-minus-01: CalendarMinus01Icon; <Icons.Interface.CalendarMinus01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-minus-02: CalendarMinus02Icon; <Icons.Interface.CalendarMinus02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-plus-01: CalendarPlus01Icon; <Icons.Interface.CalendarPlus01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

calendar-plus-02: CalendarPlus02Icon; <Icons.Interface.CalendarPlus02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock: ClockIcon; <Icons.Interface.Clock />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-check: ClockCheckIcon; <Icons.Interface.ClockCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-fast-forward: ClockFastForwardIcon; <Icons.Interface.ClockFastForward />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-plus: ClockPlusIcon; <Icons.Interface.ClockPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-refresh: ClockRefreshIcon; <Icons.Interface.ClockRefresh />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-rewind: ClockRewindIcon; <Icons.Interface.ClockRewind />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-snooze: ClockSnoozeIcon; <Icons.Interface.ClockSnooze />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

clock-stopwatch: ClockStopwatchIcon; <Icons.Interface.ClockStopwatch />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hourglass-01: Hourglass01Icon; <Icons.Interface.Hourglass01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hourglass-02: Hourglass02Icon; <Icons.Interface.Hourglass02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hourglass-03: Hourglass03Icon; <Icons.Interface.Hourglass03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-content: FaceContentIcon; <Icons.Interface.FaceContent />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-frown: FaceFrownIcon; <Icons.Interface.FaceFrown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-happy: FaceHappyIcon; <Icons.Interface.FaceHappy />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-id: FaceIdIcon; <Icons.Interface.FaceId />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-id-square: FaceIdSquareIcon; <Icons.Interface.FaceIdSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-neutral: FaceNeutralIcon; <Icons.Interface.FaceNeutral />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-sad: FaceSadIcon; <Icons.Interface.FaceSad />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-smile: FaceSmileIcon; <Icons.Interface.FaceSmile />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

face-wink: FaceWinkIcon; <Icons.Interface.FaceWink />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hand: HandIcon; <Icons.Interface.Hand />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-01: User01Icon; <Icons.Interface.User01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-02: User02Icon; <Icons.Interface.User02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-03: User03Icon; <Icons.Interface.User03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-check-01: UserCheck01Icon; <Icons.Interface.UserCheck01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-check-02: UserCheck02Icon; <Icons.Interface.UserCheck02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-circle: UserCircleIcon; <Icons.Interface.UserCircle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-down-01: UserDown01Icon; <Icons.Interface.UserDown01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-down-02: UserDown02Icon; <Icons.Interface.UserDown02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-edit: UserEditIcon; <Icons.Interface.UserEdit />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-left-01: UserLeft01Icon; <Icons.Interface.UserLeft01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-left-02: UserLeft02Icon; <Icons.Interface.UserLeft02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-minus-01: UserMinus01Icon; <Icons.Interface.UserMinus01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-minus-02: UserMinus02Icon; <Icons.Interface.UserMinus02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-plus-01: UserPlus01Icon; <Icons.Interface.UserPlus01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-plus-02: UserPlus02Icon; <Icons.Interface.UserPlus02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-right-01: UserRight01Icon; <Icons.Interface.UserRight01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-right-02: UserRight02Icon; <Icons.Interface.UserRight02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-square: UserSquareIcon; <Icons.Interface.UserSquare />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-up-01: UserUp01Icon; <Icons.Interface.UserUp01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-up-02: UserUp02Icon; <Icons.Interface.UserUp02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-x01: UserX01Icon; <Icons.Interface.UserX01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

user-x02: UserX02Icon; <Icons.Interface.UserX02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-01: Users01Icon; <Icons.Interface.Users01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-02: Users02Icon; <Icons.Interface.Users02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-03: Users03Icon; <Icons.Interface.Users03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-check: UsersCheckIcon; <Icons.Interface.UsersCheck />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-down: UsersDownIcon; <Icons.Interface.UsersDown />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-edit: UsersEditIcon; <Icons.Interface.UsersEdit />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-left: UsersLeftIcon; <Icons.Interface.UsersLeft />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-minus: UsersMinusIcon; <Icons.Interface.UsersMinus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-plus: UsersPlusIcon; <Icons.Interface.UsersPlus />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-right: UsersRightIcon; <Icons.Interface.UsersRight />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-up: UsersUpIcon; <Icons.Interface.UsersUp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

users-x: UsersXIcon; <Icons.Interface.UsersX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-01: Cloud01Icon; <Icons.Interface.Cloud01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-02: Cloud02Icon; <Icons.Interface.Cloud02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-03: Cloud03Icon; <Icons.Interface.Cloud03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-blank-01: CloudBlank01Icon; <Icons.Interface.CloudBlank01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-blank-02: CloudBlank02Icon; <Icons.Interface.CloudBlank02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-lightning: CloudLightningIcon; <Icons.Interface.CloudLightning />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-moon: CloudMoonIcon; <Icons.Interface.CloudMoon />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-off: CloudOffIcon; <Icons.Interface.CloudOff />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-raining-01: CloudRaining01Icon; <Icons.Interface.CloudRaining01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-raining-02: CloudRaining02Icon; <Icons.Interface.CloudRaining02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-raining-03: CloudRaining03Icon; <Icons.Interface.CloudRaining03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-raining-04: CloudRaining04Icon; <Icons.Interface.CloudRaining04 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-raining-05: CloudRaining05Icon; <Icons.Interface.CloudRaining05 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-raining-06: CloudRaining06Icon; <Icons.Interface.CloudRaining06 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-snowing-01: CloudSnowing01Icon; <Icons.Interface.CloudSnowing01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-snowing-02: CloudSnowing02Icon; <Icons.Interface.CloudSnowing02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-sun-01: CloudSun01Icon; <Icons.Interface.CloudSun01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-sun-02: CloudSun02Icon; <Icons.Interface.CloudSun02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

cloud-sun-03: CloudSun03Icon; <Icons.Interface.CloudSun03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hurricane-01: Hurricane01Icon; <Icons.Interface.Hurricane01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hurricane-02: Hurricane02Icon; <Icons.Interface.Hurricane02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

hurricane-03: Hurricane03Icon; <Icons.Interface.Hurricane03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightning-01: Lightning01Icon; <Icons.Interface.Lightning01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

lightning-02: Lightning02Icon; <Icons.Interface.Lightning02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

moon-01: Moon01Icon; <Icons.Interface.Moon01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

moon-02: Moon02Icon; <Icons.Interface.Moon02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

moon-eclipse: MoonEclipseIcon; <Icons.Interface.MoonEclipse />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

moon-star: MoonStarIcon; <Icons.Interface.MoonStar />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

snowflake-01: Snowflake01Icon; <Icons.Interface.Snowflake01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

snowflake-02: Snowflake02Icon; <Icons.Interface.Snowflake02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sun: SunIcon; <Icons.Interface.Sun />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sun-setting-01: SunSetting01Icon; <Icons.Interface.SunSetting01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sun-setting-02: SunSetting02Icon; <Icons.Interface.SunSetting02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sun-setting-03: SunSetting03Icon; <Icons.Interface.SunSetting03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sunrise: SunriseIcon; <Icons.Interface.Sunrise />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

sunset: SunsetIcon; <Icons.Interface.Sunset />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thermometer-01: Thermometer01Icon; <Icons.Interface.Thermometer01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thermometer-02: Thermometer02Icon; <Icons.Interface.Thermometer02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thermometer-03: Thermometer03Icon; <Icons.Interface.Thermometer03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thermometer-cold: ThermometerColdIcon; <Icons.Interface.ThermometerCold />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

thermometer-warm: ThermometerWarmIcon; <Icons.Interface.ThermometerWarm />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

umbrella-01: Umbrella01Icon; <Icons.Interface.Umbrella01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

umbrella-02: Umbrella02Icon; <Icons.Interface.Umbrella02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

umbrella-03: Umbrella03Icon; <Icons.Interface.Umbrella03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

waves: WavesIcon; <Icons.Interface.Waves />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wind-01: Wind01Icon; <Icons.Interface.Wind01 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wind-02: Wind02Icon; <Icons.Interface.Wind02 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

wind-03: Wind03Icon; <Icons.Interface.Wind03 />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

agent-gimbal: AgentGimbalIcon; <Icons.Interface.AgentGimbal />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

pneuma: PneumaIcon; <Icons.Interface.Pneuma />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

commenda: CommendaIcon; <Icons.Interface.Commenda />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

commenda-brand: CommendaBrandIcon; <Icons.Interface.CommendaBrand />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

mcp: McpIcon; <Icons.Interface.Mcp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

drag-handle: DragHandleIcon; <Icons.Interface.DragHandle />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

signature: SignatureIcon; <Icons.Interface.Signature />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

plug: PlugIcon; <Icons.Interface.Plug />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

id-card: IdCardIcon; <Icons.Interface.IdCard />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

org-chart: OrgChartIcon; <Icons.Interface.OrgChart />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stamp: StampIcon; <Icons.Interface.Stamp />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

gavel: GavelIcon; <Icons.Interface.Gavel />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

stop-fill: StopFillIcon; <Icons.Interface.StopFill />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/icons

DZ: DZFlag; <Icons.Flags.DZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AO: AOFlag; <Icons.Flags.AO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AC: ACFlag; <Icons.Flags.AC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BJ: BJFlag; <Icons.Flags.BJ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BW: BWFlag; <Icons.Flags.BW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IO: IOFlag; <Icons.Flags.IO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BF: BFFlag; <Icons.Flags.BF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BI: BIFlag; <Icons.Flags.BI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CM: CMFlag; <Icons.Flags.CM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IC: ICFlag; <Icons.Flags.IC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CV: CVFlag; <Icons.Flags.CV />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CF: CFFlag; <Icons.Flags.CF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TD: TDFlag; <Icons.Flags.TD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KM: KMFlag; <Icons.Flags.KM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CG: CGFlag; <Icons.Flags.CG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CD: CDFlag; <Icons.Flags.CD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CI: CIFlag; <Icons.Flags.CI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

DJ: DJFlag; <Icons.Flags.DJ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

EG: EGFlag; <Icons.Flags.EG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GQ: GQFlag; <Icons.Flags.GQ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ER: ERFlag; <Icons.Flags.ER />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SZ: SZFlag; <Icons.Flags.SZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ET: ETFlag; <Icons.Flags.ET />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TF: TFFlag; <Icons.Flags.TF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GA: GAFlag; <Icons.Flags.GA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GM: GMFlag; <Icons.Flags.GM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GH: GHFlag; <Icons.Flags.GH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GN: GNFlag; <Icons.Flags.GN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GW: GWFlag; <Icons.Flags.GW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KE: KEFlag; <Icons.Flags.KE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LS: LSFlag; <Icons.Flags.LS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LR: LRFlag; <Icons.Flags.LR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LY: LYFlag; <Icons.Flags.LY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MG: MGFlag; <Icons.Flags.MG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MW: MWFlag; <Icons.Flags.MW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ML: MLFlag; <Icons.Flags.ML />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MR: MRFlag; <Icons.Flags.MR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MU: MUFlag; <Icons.Flags.MU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

YT: YTFlag; <Icons.Flags.YT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MA: MAFlag; <Icons.Flags.MA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MZ: MZFlag; <Icons.Flags.MZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NA: NAFlag; <Icons.Flags.NA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NE: NEFlag; <Icons.Flags.NE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NG: NGFlag; <Icons.Flags.NG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

RW: RWFlag; <Icons.Flags.RW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

RE: REFlag; <Icons.Flags.RE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SN: SNFlag; <Icons.Flags.SN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SC: SCFlag; <Icons.Flags.SC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SL: SLFlag; <Icons.Flags.SL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SO: SOFlag; <Icons.Flags.SO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ZA: ZAFlag; <Icons.Flags.ZA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SS: SSFlag; <Icons.Flags.SS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SH: SHFlag; <Icons.Flags.SH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SD: SDFlag; <Icons.Flags.SD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ST: STFlag; <Icons.Flags.ST />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TZ: TZFlag; <Icons.Flags.TZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TG: TGFlag; <Icons.Flags.TG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TA: TAFlag; <Icons.Flags.TA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TN: TNFlag; <Icons.Flags.TN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

UG: UGFlag; <Icons.Flags.UG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

EH: EHFlag; <Icons.Flags.EH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ZM: ZMFlag; <Icons.Flags.ZM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ZW: ZWFlag; <Icons.Flags.ZW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AI: AIFlag; <Icons.Flags.AI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AG: AGFlag; <Icons.Flags.AG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AR: ARFlag; <Icons.Flags.AR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AW: AWFlag; <Icons.Flags.AW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BS: BSFlag; <Icons.Flags.BS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BB: BBFlag; <Icons.Flags.BB />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BZ: BZFlag; <Icons.Flags.BZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BM: BMFlag; <Icons.Flags.BM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BO: BOFlag; <Icons.Flags.BO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BV: BVFlag; <Icons.Flags.BV />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BR: BRFlag; <Icons.Flags.BR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VG: VGFlag; <Icons.Flags.VG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CA: CAFlag; <Icons.Flags.CA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BQ: BQFlag; <Icons.Flags.BQ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KY: KYFlag; <Icons.Flags.KY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CL: CLFlag; <Icons.Flags.CL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CO: COFlag; <Icons.Flags.CO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CR: CRFlag; <Icons.Flags.CR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CU: CUFlag; <Icons.Flags.CU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CW: CWFlag; <Icons.Flags.CW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

DM: DMFlag; <Icons.Flags.DM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

DO: DOFlag; <Icons.Flags.DO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

EC: ECFlag; <Icons.Flags.EC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SV: SVFlag; <Icons.Flags.SV />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

FK: FKFlag; <Icons.Flags.FK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GF: GFFlag; <Icons.Flags.GF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GL: GLFlag; <Icons.Flags.GL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GD: GDFlag; <Icons.Flags.GD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GP: GPFlag; <Icons.Flags.GP />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GT: GTFlag; <Icons.Flags.GT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GY: GYFlag; <Icons.Flags.GY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

HT: HTFlag; <Icons.Flags.HT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

HN: HNFlag; <Icons.Flags.HN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

JM: JMFlag; <Icons.Flags.JM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MQ: MQFlag; <Icons.Flags.MQ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MX: MXFlag; <Icons.Flags.MX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MS: MSFlag; <Icons.Flags.MS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NI: NIFlag; <Icons.Flags.NI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PA: PAFlag; <Icons.Flags.PA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PY: PYFlag; <Icons.Flags.PY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PE: PEFlag; <Icons.Flags.PE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PR: PRFlag; <Icons.Flags.PR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SX: SXFlag; <Icons.Flags.SX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GS: GSFlag; <Icons.Flags.GS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BL: BLFlag; <Icons.Flags.BL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KN: KNFlag; <Icons.Flags.KN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LC: LCFlag; <Icons.Flags.LC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MF: MFFlag; <Icons.Flags.MF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PM: PMFlag; <Icons.Flags.PM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VC: VCFlag; <Icons.Flags.VC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SR: SRFlag; <Icons.Flags.SR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TT: TTFlag; <Icons.Flags.TT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TC: TCFlag; <Icons.Flags.TC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

UM: UMFlag; <Icons.Flags.UM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VI: VIFlag; <Icons.Flags.VI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

US: USFlag; <Icons.Flags.US />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

UY: UYFlag; <Icons.Flags.UY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VE: VEFlag; <Icons.Flags.VE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GE-AB: GEABFlag; <Icons.Flags.GEAB />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AF: AFFlag; <Icons.Flags.AF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AM: AMFlag; <Icons.Flags.AM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AZ: AZFlag; <Icons.Flags.AZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BH: BHFlag; <Icons.Flags.BH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BD: BDFlag; <Icons.Flags.BD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BT: BTFlag; <Icons.Flags.BT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BN: BNFlag; <Icons.Flags.BN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KH: KHFlag; <Icons.Flags.KH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CN: CNFlag; <Icons.Flags.CN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CY: CYFlag; <Icons.Flags.CY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GE: GEFlag; <Icons.Flags.GE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

HK: HKFlag; <Icons.Flags.HK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IN: INFlag; <Icons.Flags.IN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ID: IDFlag; <Icons.Flags.ID />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IR: IRFlag; <Icons.Flags.IR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IQ: IQFlag; <Icons.Flags.IQ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IL: ILFlag; <Icons.Flags.IL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

JP: JPFlag; <Icons.Flags.JP />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

JO: JOFlag; <Icons.Flags.JO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KZ: KZFlag; <Icons.Flags.KZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KW: KWFlag; <Icons.Flags.KW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KG: KGFlag; <Icons.Flags.KG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LA: LAFlag; <Icons.Flags.LA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LB: LBFlag; <Icons.Flags.LB />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MO: MOFlag; <Icons.Flags.MO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MY: MYFlag; <Icons.Flags.MY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MV: MVFlag; <Icons.Flags.MV />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MN: MNFlag; <Icons.Flags.MN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MM: MMFlag; <Icons.Flags.MM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NP: NPFlag; <Icons.Flags.NP />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KP: KPFlag; <Icons.Flags.KP />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

OM: OMFlag; <Icons.Flags.OM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PK: PKFlag; <Icons.Flags.PK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PS: PSFlag; <Icons.Flags.PS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PH: PHFlag; <Icons.Flags.PH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

QA: QAFlag; <Icons.Flags.QA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SA: SAFlag; <Icons.Flags.SA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SG: SGFlag; <Icons.Flags.SG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KR: KRFlag; <Icons.Flags.KR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GE-OS: GEOSFlag; <Icons.Flags.GEOS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LK: LKFlag; <Icons.Flags.LK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SY: SYFlag; <Icons.Flags.SY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TW: TWFlag; <Icons.Flags.TW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TJ: TJFlag; <Icons.Flags.TJ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TH: THFlag; <Icons.Flags.TH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TL: TLFlag; <Icons.Flags.TL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TM: TMFlag; <Icons.Flags.TM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TR: TRFlag; <Icons.Flags.TR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AE: AEFlag; <Icons.Flags.AE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

UZ: UZFlag; <Icons.Flags.UZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VN: VNFlag; <Icons.Flags.VN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

YE: YEFlag; <Icons.Flags.YE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AX: AXFlag; <Icons.Flags.AX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AL: ALFlag; <Icons.Flags.AL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AD: ADFlag; <Icons.Flags.AD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AT: ATFlag; <Icons.Flags.AT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BY: BYFlag; <Icons.Flags.BY />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BE: BEFlag; <Icons.Flags.BE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BA: BAFlag; <Icons.Flags.BA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

BG: BGFlag; <Icons.Flags.BG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

HR: HRFlag; <Icons.Flags.HR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CZ: CZFlag; <Icons.Flags.CZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

DK: DKFlag; <Icons.Flags.DK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

EE: EEFlag; <Icons.Flags.EE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

FO: FOFlag; <Icons.Flags.FO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

FI: FIFlag; <Icons.Flags.FI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

FR: FRFlag; <Icons.Flags.FR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

DE: DEFlag; <Icons.Flags.DE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GI: GIFlag; <Icons.Flags.GI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GR: GRFlag; <Icons.Flags.GR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GG: GGFlag; <Icons.Flags.GG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

HU: HUFlag; <Icons.Flags.HU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IS: ISFlag; <Icons.Flags.IS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IE: IEFlag; <Icons.Flags.IE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IM: IMFlag; <Icons.Flags.IM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

IT: ITFlag; <Icons.Flags.IT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

JE: JEFlag; <Icons.Flags.JE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

XK: XKFlag; <Icons.Flags.XK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LV: LVFlag; <Icons.Flags.LV />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LI: LIFlag; <Icons.Flags.LI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LT: LTFlag; <Icons.Flags.LT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

LU: LUFlag; <Icons.Flags.LU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MT: MTFlag; <Icons.Flags.MT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MD: MDFlag; <Icons.Flags.MD />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MC: MCFlag; <Icons.Flags.MC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ME: MEFlag; <Icons.Flags.ME />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NL: NLFlag; <Icons.Flags.NL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MK: MKFlag; <Icons.Flags.MK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NO: NOFlag; <Icons.Flags.NO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PL: PLFlag; <Icons.Flags.PL />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PT: PTFlag; <Icons.Flags.PT />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

RO: ROFlag; <Icons.Flags.RO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

RU: RUFlag; <Icons.Flags.RU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SM: SMFlag; <Icons.Flags.SM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

RS: RSFlag; <Icons.Flags.RS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SK: SKFlag; <Icons.Flags.SK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SI: SIFlag; <Icons.Flags.SI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

ES: ESFlag; <Icons.Flags.ES />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SJ: SJFlag; <Icons.Flags.SJ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SE: SEFlag; <Icons.Flags.SE />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CH: CHFlag; <Icons.Flags.CH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

UA: UAFlag; <Icons.Flags.UA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GB: GBFlag; <Icons.Flags.GB />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VA: VAFlag; <Icons.Flags.VA />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AS: ASFlag; <Icons.Flags.AS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AU: AUFlag; <Icons.Flags.AU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CX: CXFlag; <Icons.Flags.CX />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CC: CCFlag; <Icons.Flags.CC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

CK: CKFlag; <Icons.Flags.CK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

FJ: FJFlag; <Icons.Flags.FJ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PF: PFFlag; <Icons.Flags.PF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

GU: GUFlag; <Icons.Flags.GU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

HM: HMFlag; <Icons.Flags.HM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

KI: KIFlag; <Icons.Flags.KI />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MH: MHFlag; <Icons.Flags.MH />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

FM: FMFlag; <Icons.Flags.FM />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NR: NRFlag; <Icons.Flags.NR />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NC: NCFlag; <Icons.Flags.NC />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NZ: NZFlag; <Icons.Flags.NZ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NU: NUFlag; <Icons.Flags.NU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

NF: NFFlag; <Icons.Flags.NF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

MP: MPFlag; <Icons.Flags.MP />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PW: PWFlag; <Icons.Flags.PW />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PG: PGFlag; <Icons.Flags.PG />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

PN: PNFlag; <Icons.Flags.PN />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

WS: WSFlag; <Icons.Flags.WS />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

SB: SBFlag; <Icons.Flags.SB />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TK: TKFlag; <Icons.Flags.TK />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TO: TOFlag; <Icons.Flags.TO />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

TV: TVFlag; <Icons.Flags.TV />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

VU: VUFlag; <Icons.Flags.VU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

WF: WFFlag; <Icons.Flags.WF />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

AQ: AQFlag; <Icons.Flags.AQ />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

EU: EUFlag; <Icons.Flags.EU />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/flags

file-pdf: FilePdfIcon; <Icons.FileTypes.Pdf />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-doc: FileDocIcon; <Icons.FileTypes.Doc />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-xls: FileXlsIcon; <Icons.FileTypes.Xls />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-csv: FileCsvIcon; <Icons.FileTypes.Csv />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-ppt: FilePptIcon; <Icons.FileTypes.Ppt />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-txt: FileTxtIcon; <Icons.FileTypes.Txt />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-image: FileImageIcon; <Icons.FileTypes.Image />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-json: FileJsonIcon; <Icons.FileTypes.Json />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-xml: FileXmlIcon; <Icons.FileTypes.Xml />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-zip: FileZipIcon; <Icons.FileTypes.Zip />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

file-generic: FileGenericIcon; <Icons.FileTypes.Generic />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

folder: FolderIcon; <Icons.Folder status="closed" />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

folder-open: FolderOpenIcon; <Icons.Folder status="open" />; sizes: 16, 24, 40; import: @commenda/pathfinder/file-types

status-to-do: StatusToDoIcon; <Icons.Status status="to-do" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-scheduled: StatusScheduledIcon; <Icons.Status status="scheduled" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-in-progress: StatusInProgressIcon; <Icons.Status status="in-progress" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-in-review: StatusInReviewIcon; <Icons.Status status="in-review" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-completed: StatusCompletedIcon; <Icons.Status status="completed" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-canceled: StatusCanceledIcon; <Icons.Status status="canceled" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-blocking: StatusBlockingIcon; <Icons.Status status="blocking" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-blocked-by: StatusBlockedByIcon; <Icons.Status status="blocked-by" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-failed: StatusFailedIcon; <Icons.Status status="failed" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

status-needs-attention: StatusNeedsAttentionIcon; <Icons.Status status="needs-attention" label="Status name" />; sizes: 12, 16, 20, 24; import: @commenda/pathfinder/status-icons

progress-ring-0: Progress0Icon; <Icons.Progress.Percent0 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-10: Progress10Icon; <Icons.Progress.Percent10 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-25: Progress25Icon; <Icons.Progress.Percent25 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-33: Progress33Icon; <Icons.Progress.Percent33 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-50: Progress50Icon; <Icons.Progress.Percent50 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-66: Progress66Icon; <Icons.Progress.Percent66 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-75: Progress75Icon; <Icons.Progress.Percent75 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-90: Progress90Icon; <Icons.Progress.Percent90 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

progress-ring-100: Progress100Icon; <Icons.Progress.Percent100 />; sizes: 16, 24, 32; import: @commenda/pathfinder/status-icons

logo-quickbooks: QuickbooksLogo; <Icons.Logos.Integrations.Quickbooks />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-xero: XeroLogo; <Icons.Logos.Integrations.Xero />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-oracle-netsuite: OracleNetsuiteLogo; <Icons.Logos.Integrations.OracleNetsuite />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-sage: SageLogo; <Icons.Logos.Integrations.Sage />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-sage-intacct: SageIntacctLogo; <Icons.Logos.Integrations.SageIntacct />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-sage-business-cloud: SageBusinessCloudLogo; <Icons.Logos.Integrations.SageBusinessCloud />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-zoho-books: ZohoBooksLogo; <Icons.Logos.Integrations.ZohoBooks />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-zoho-invoice: ZohoInvoiceLogo; <Icons.Logos.Integrations.ZohoInvoice />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-dynamics-365: Dynamics365Logo; <Icons.Logos.Integrations.Dynamics365 />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-dynamics-business-central: DynamicsBusinessCentralLogo; <Icons.Logos.Integrations.DynamicsBusinessCentral />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-oracle-fusion: OracleFusionLogo; <Icons.Logos.Integrations.OracleFusion />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-oracle-ebs: OracleEbsLogo; <Icons.Logos.Integrations.OracleEbs />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-sap: SapLogo; <Icons.Logos.Integrations.Sap />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-odoo: OdooLogo; <Icons.Logos.Integrations.Odoo />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-tally: TallyLogo; <Icons.Logos.Integrations.Tally />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-freshbooks: FreshbooksLogo; <Icons.Logos.Integrations.Freshbooks />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-freeagent: FreeagentLogo; <Icons.Logos.Integrations.Freeagent />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-wave: WaveLogo; <Icons.Logos.Integrations.Wave />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-myob: MyobLogo; <Icons.Logos.Integrations.Myob />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-kashflow: KashflowLogo; <Icons.Logos.Integrations.Kashflow />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-clearbooks: ClearbooksLogo; <Icons.Logos.Integrations.Clearbooks />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-jurnal: JurnalLogo; <Icons.Logos.Integrations.Jurnal />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-qoyod: QoyodLogo; <Icons.Logos.Integrations.Qoyod />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-wafeq: WafeqLogo; <Icons.Logos.Integrations.Wafeq />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-rillet: RilletLogo; <Icons.Logos.Integrations.Rillet />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-puzzle: PuzzleLogo; <Icons.Logos.Integrations.Puzzle />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-busy: BusyLogo; <Icons.Logos.Integrations.Busy />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-epicor-prophet-21: EpicorProphet21Logo; <Icons.Logos.Integrations.EpicorProphet21 />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-campfire: CampfireLogo; <Icons.Logos.Integrations.Campfire />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-rootfi-sandbox: RootfiSandboxLogo; <Icons.Logos.Integrations.RootfiSandbox />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-shopify: ShopifyLogo; <Icons.Logos.Integrations.Shopify />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-amazon: AmazonLogo; <Icons.Logos.Integrations.Amazon />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-bigcommerce: BigcommerceLogo; <Icons.Logos.Integrations.Bigcommerce />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-woocommerce: WoocommerceLogo; <Icons.Logos.Integrations.Woocommerce />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-wix: WixLogo; <Icons.Logos.Integrations.Wix />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-squarespace: SquarespaceLogo; <Icons.Logos.Integrations.Squarespace />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-square: SquareLogo; <Icons.Logos.Integrations.Square />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-google-play: GooglePlayLogo; <Icons.Logos.Integrations.GooglePlay />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-stripe: StripeLogo; <Icons.Logos.Integrations.Stripe />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-paypal: PaypalLogo; <Icons.Logos.Integrations.Paypal />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-paddle: PaddleLogo; <Icons.Logos.Integrations.Paddle />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-mollie: MollieLogo; <Icons.Logos.Integrations.Mollie />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-razorpay: RazorpayLogo; <Icons.Logos.Integrations.Razorpay />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-chargebee: ChargebeeLogo; <Icons.Logos.Integrations.Chargebee />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-salesforce: SalesforceLogo; <Icons.Logos.Integrations.Salesforce />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-hubspot: HubspotLogo; <Icons.Logos.Integrations.Hubspot />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-pipedrive: PipedriveLogo; <Icons.Logos.Integrations.Pipedrive />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

logo-zoho-crm: ZohoCrmLogo; <Icons.Logos.Integrations.ZohoCrm />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/integrations

payment-affirm: AffirmPaymentLogo; <Icons.Logos.Payments.Affirm />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-alfa-bank: AlfaBankPaymentLogo; <Icons.Logos.Payments.AlfaBank />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-alipay: AlipayPaymentLogo; <Icons.Logos.Payments.Alipay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-amazon: AmazonPaymentLogo; <Icons.Logos.Payments.Amazon />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-american-express: AmericanExpressPaymentLogo; <Icons.Logos.Payments.AmericanExpress />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-amex: AmexPaymentLogo; <Icons.Logos.Payments.Amex />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-apple-pay: ApplePayPaymentLogo; <Icons.Logos.Payments.ApplePay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-bancontact: BancontactPaymentLogo; <Icons.Logos.Payments.Bancontact />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-bitcoin: BitcoinPaymentLogo; <Icons.Logos.Payments.Bitcoin />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-bitcoin-cash: BitcoinCashPaymentLogo; <Icons.Logos.Payments.BitcoinCash />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-bitpay: BitpayPaymentLogo; <Icons.Logos.Payments.Bitpay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-citadele: CitadelePaymentLogo; <Icons.Logos.Payments.Citadele />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-default: DefaultPaymentLogo; <Icons.Logos.Payments.Default />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-diners-club: DinersClubPaymentLogo; <Icons.Logos.Payments.DinersClub />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-direct-debit: DirectDebitPaymentLogo; <Icons.Logos.Payments.DirectDebit />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-discover: DiscoverPaymentLogo; <Icons.Logos.Payments.Discover />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-elo: EloPaymentLogo; <Icons.Logos.Payments.Elo />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-ethereum: EthereumPaymentLogo; <Icons.Logos.Payments.Ethereum />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-forbrugsforeningen: ForbrugsforeningenPaymentLogo; <Icons.Logos.Payments.Forbrugsforeningen />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-giropay: GiropayPaymentLogo; <Icons.Logos.Payments.Giropay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-google-pay: GooglePayPaymentLogo; <Icons.Logos.Payments.GooglePay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-ideal: IdealPaymentLogo; <Icons.Logos.Payments.Ideal />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-interac: InteracPaymentLogo; <Icons.Logos.Payments.Interac />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-jcb: JcbPaymentLogo; <Icons.Logos.Payments.Jcb />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-klarna: KlarnaPaymentLogo; <Icons.Logos.Payments.Klarna />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-lightcoin: LightcoinPaymentLogo; <Icons.Logos.Payments.Lightcoin />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-maestro: MaestroPaymentLogo; <Icons.Logos.Payments.Maestro />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-mastercard: MastercardPaymentLogo; <Icons.Logos.Payments.Mastercard />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-payoneer: PayoneerPaymentLogo; <Icons.Logos.Payments.Payoneer />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-paypal: PaypalPaymentLogo; <Icons.Logos.Payments.Paypal />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-paysafe: PaysafePaymentLogo; <Icons.Logos.Payments.Paysafe />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-qiwi: QiwiPaymentLogo; <Icons.Logos.Payments.Qiwi />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-sber-bank: SberBankPaymentLogo; <Icons.Logos.Payments.SberBank />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-sepa: SepaPaymentLogo; <Icons.Logos.Payments.Sepa />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-shop-pay: ShopPayPaymentLogo; <Icons.Logos.Payments.ShopPay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-shopify: ShopifyPaymentLogo; <Icons.Logos.Payments.Shopify />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-skrill: SkrillPaymentLogo; <Icons.Logos.Payments.Skrill />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-sofort: SofortPaymentLogo; <Icons.Logos.Payments.Sofort />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-stripe: StripePaymentLogo; <Icons.Logos.Payments.Stripe />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-swift: SwiftPaymentLogo; <Icons.Logos.Payments.Swift />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-tinkoff: TinkoffPaymentLogo; <Icons.Logos.Payments.Tinkoff />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-union-pay: UnionPayPaymentLogo; <Icons.Logos.Payments.UnionPay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-verifone: VerifonePaymentLogo; <Icons.Logos.Payments.Verifone />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-visa: VisaPaymentLogo; <Icons.Logos.Payments.Visa />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-we-chat: WeChatPaymentLogo; <Icons.Logos.Payments.WeChat />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-web-money: WebMoneyPaymentLogo; <Icons.Logos.Payments.WebMoney />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-western-union: WesternUnionPaymentLogo; <Icons.Logos.Payments.WesternUnion />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-world-pay: WorldPayPaymentLogo; <Icons.Logos.Payments.WorldPay />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-yandex: YandexPaymentLogo; <Icons.Logos.Payments.Yandex />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

payment-yandex-kassa: YandexKassaPaymentLogo; <Icons.Logos.Payments.YandexKassa />; sizes: 16, 24, 32; import: @commenda/pathfinder/logos/payments

logo-google: GoogleLogo; <Icons.Logos.Software.Google />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/software

logo-jira: JiraLogo; <Icons.Logos.Software.Jira />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/software

logo-pylon: PylonLogo; <Icons.Logos.Software.Pylon />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/software

logo-customer-default: CustomerDefaultLogo; <Icons.Logos.Software.CustomerDefault />; sizes: 16, 24, 32, 40; import: @commenda/pathfinder/logos/software

commenda-lockup: CommendaLockupLogo; <Icons.Logos.Commenda.Lockup />; sizes: 18; import: @commenda/pathfinder/logos/commenda