svelte-kit-vice/src/uix/soma/COMPONENT_GUIDE.md

# Component Implementation Guide

Step-by-step guide for building soma headless components.

## Before You Start

### 1. Compare with reference libraries

**This step is mandatory. Do not skip it.**

Search ark-ui, bits-ui, and radix-ui for the same component. Create a feature table:

| Feature     | Radix | Ark | Bits | Soma | Decision      |
| ----------- | ----- | --- | ---- | ---- | ------------- |
| (each prop) | ...   | ... | ...  | ✓/✗  | justification |

Document what soma includes and what it skips (with reason).

### 2. Verify membership criteria

The component must have BOTH:

- Composition of parts (2+ sub-components communicating via context)
- Complex behavior (keyboard nav, focus management, floating, ARIA relationships, state machines, drag, or form integration)

If it only has one or neither → it's air-native, not soma.

## File Structure

```
components/{name}/
├── {name}-provider.svelte.ts   ← ALL state classes (Provider subclasses)
├── types.ts                     ← ALL prop types with JSDoc + canonical field shapes
├── langs.ts                     ← idlangref constants for translations
├── exports.ts                   ← barrel (Provider, Trigger, Content, etc.)
├── index.ts                     ← re-exports from exports.ts
└── components/
    ├── {name}.svelte            ← root wrapper
    ├── {name}-trigger.svelte    ← trigger wrapper
    ├── {name}-content.svelte    ← content wrapper
    └── ...
```

### File naming rules

- State class file: `{name}-provider.svelte.ts` (NOT `{name}.svelte.ts`)
  - Why: avoids Vite module resolution ambiguity with `{name}.svelte` wrapper
  - Contains ALL Provider subclasses for the component
- Wrapper files: `{name}.svelte`, `{name}-trigger.svelte`, etc.
- Types file: `types.ts` — public props + canonical field shapes for Opts
- Langs file: `langs.ts` — idlangref constants (see A3)
- Barrel: `exports.ts` + `index.ts`

## State Class Pattern ({name}-provider.svelte.ts)

```ts
import { Provider, context, type ProviderOpts, type WithRefOpts } from '../../provider';
import { createAttrs } from '../../attrs';
import { COMPONENT_LANGS } from './langs';

const attrs = createAttrs({
    component: '{name}',
    parts: ['root', 'trigger', 'content', ...] as const,
});

// Root provider (with or without DOM)
interface {Name}Opts extends ProviderOpts, ... {}  // ProviderOpts if no DOM
interface {Name}Opts extends WithRefOpts, ... {}    // WithRefOpts if renders element

export class {Name}Provider extends Provider<{Name}Opts> {
    static readonly ctx = context<{Name}Provider>('{Name}');
    static get() { return this.ctx.getOr(undefined) as {Name}Provider | undefined; }
    static require() { return this.ctx.get(); }

    static create(opts: {Name}Opts) {
        return new {Name}Provider(opts);
    }

    private constructor(opts: {Name}Opts) {
        super(opts, '{Name}', 'root', attrs.root, {Name}Provider.ctx);
    }

    readonly props = $derived.by(() =>
        this.assertProps({
            ...this.baseProps,
            // component-specific props
        } as const),
    );
}

// Sub-parts read parent context
export class {Name}TriggerProvider extends Provider<{Name}TriggerOpts> {
    static create(opts) { return new {Name}TriggerProvider(opts); }

    readonly provider: {Name}Provider;

    private constructor(opts) {
        super(opts, '{Name}', 'trigger', attrs.trigger);
        this.provider = {Name}Provider.require();
    }
}
```

### Static Method Convention

All classes that use Svelte context follow the same 3-method pattern:

| Method         | Behavior                        | When to use                                             |
| -------------- | ------------------------------- | ------------------------------------------------------- |
| `create(opts)` | Factory + context set           | Root wrapper creates the provider                       |
| `get()`        | Returns instance or `undefined` | Optional parent (e.g., Checkbox inside optional Group)  |
| `require()`    | Throws if not found             | Required parent (e.g., Trigger must be inside Provider) |

This applies consistently to:

- **Provider classes**: `XProvider.create()`, `XProvider.get()`, `XProvider.require()`
- **Soma**: `Soma.create()`, `Soma.get()`, `Soma.require()`
- **App**: `App.create()`, `App.get()`, `App.require()`

No standalone functions (`createApp`, `getApp`, `useApp`). No `from()`. The `ctx` field is `readonly` on the class but not exposed as public API — consumers use the static methods.

### Rules

- `getContext()` only works during component initialization (constructor called from script block). NEVER in event handlers, timeouts, or callbacks.
- If a handler needs a context reference, capture it in the constructor.
- Event handlers (onclick, onkeydown) must be included in `props`. Defining them as class methods without spreading them into props means they won't reach the DOM.
- Layers (Presence, FocusScope, Dismissal, Gesture, etc.) are instantiated in the constructor and their `.props` are spread into the component's `props`.
- For DropdownMenu: `interactOutsideBehavior` defaults to `'close'` (not inherited from `modal` like Dialog).

### Types: define once, reference in Opts

Canonical field shapes are defined once in `types.ts` and referenced by provider Opts via `StateProps<>` / `ActiveProps<>`:

```ts
// types.ts
export type DrawerStateFields = { open: boolean; activeSnapPoint: SnapPoint | null; };
export type DrawerActiveFields = { disabled: boolean; modal: boolean; direction: Direction; ... };

// provider
interface DrawerOpts extends ProviderOpts, StateProps<DrawerStateFields>, ActiveProps<DrawerActiveFields> {}
```

Do NOT redeclare field types in both `types.ts` and the Opts interface.

## Wrapper Pattern (components/{name}.svelte)

```svelte
<script lang="ts">
    import { readableActive, writableActive } from '../../reactive';
    import { mergeProps } from '../../props';
    import { createId } from '../../id';
    import { {Name}Provider } from '../{name}-provider.svelte';
    import type { {Name}Props } from '../types';
    const uid = $props.id();

    let {
        ref = $bindable(null),
        id = createId(uid, '{name}'),
        // ... props with defaults ...
        onOpenChange = () => {},
        children,
        child,
        ...restProps
    }: {Name}Props = $props();

    const state = {Name}Provider.create({
        id: readableActive(() => id),
        ref: writableActive(() => ref, (v) => (ref = v)),
        // ... wrap each prop ...
    });

    const mergedProps = $derived(mergeProps(restProps, state.props));
</script>

{#if child}
	{@render child({ props: mergedProps })}
{:else}
	<div {...mergedProps}>
		{@render children?.()}
	</div>
{/if}
```

### Rules

- Wrappers are thin: props → Active/State → Provider.create() → mergeProps → render
- No logic in wrappers. If you're writing more than prop conversion, the logic belongs in the Provider.
- IDs: `createId(uid, '{component}-{part}')` — descriptive and inspectable
- Callbacks default to `() => {}` inline — no `noop` import, soma does not depend on `$lib`
- Direction: `soma?.presentation.getDir() ?? 'ltr'` where Soma is available

## Exports Pattern (exports.ts)

```ts
export { default as Provider } from './components/{name}.svelte';    // ALWAYS "Provider", never "Root"
export { default as Trigger } from './components/{name}-trigger.svelte';
export { default as Content } from './components/{name}-content.svelte';

export type {
    {Name}Props as ProviderProps,       // ALWAYS "ProviderProps", never "RootProps"
    {Name}TriggerProps as TriggerProps,
    {Name}ContentProps as ContentProps,
} from './types';
```

## Types Pattern (types.ts)

ALL props documented with JSDoc. No exceptions.

```ts
export type {Name}Props = WithChild<{
    /** Unique identifier. Auto-generated if omitted. */
    id?: string;
    /** Whether open. Bindable. @default false */
    open?: boolean;
    /** Callback on open change. */
    onOpenChange?: OnChangeFn<boolean>;
    /**
     * Multi-line for complex behavior.
     * Inherits from X when not set.
     * @default 'close'
     */
    escapeKeydownBehavior?: DismissalBehavior;
}> & Without<PrimitiveDivAttributes, {}>;
```

### Rules

- One-line JSDoc for simple props
- Multi-line when there's conditional behavior or prop relationships
- `@default` on every prop that has a default in the wrapper
- Callbacks: document what `e.preventDefault()` does if applicable
- `value: string` for required props (no `?`)

## ID Generation

```ts
createId(uid, 'dialog'); // → "soma-dialog-c12"
createId(uid, 'dialog-trigger'); // → "soma-dialog-trigger-c13"
createId(uid, 'dialog-content'); // → "soma-dialog-content-c14"
```

Pattern: `soma-{component}-{part}-{uid}`. Always descriptive.

## Data Attributes

- Provider: `data-{component}` (no `-provider` suffix)
- Parts: `data-{component}-{part}`
- State: `data-state="open|closed"`, `data-state="checked|unchecked|indeterminate"`
- Flags: `data-disabled`, `data-readonly`, `data-checked`
- Floating: `data-side`, `data-align`
- Animation: `data-starting-style`, `data-ending-style`
- Nesting: `data-nested`, `data-nested-open`
- Drag: `data-dragging` (present during active gesture)

## Checklist

```
[ ] 1. Compare with ark-ui, bits-ui, radix-ui — feature table with decisions
[ ] 2. Verify membership criteria (composition + complex behavior)
[ ] 3. Define parts: Provider + sub-parts (root part uses 'root', not 'provider' — A2)
[ ] 4. Create {name}-provider.svelte.ts with all Provider subclasses
[ ] 5. Register data-* contract via registerContract() — A1
[ ] 6. Create types.ts with JSDoc on ALL props + canonical field shapes
[ ] 7. Create langs.ts with idlangref constants — A3
[ ] 8. Create wrapper .svelte files (thin: props → Active → Provider → mergeProps → render — A11)
[ ] 9. Verify: event handlers included in props (not just class methods)
[ ] 10. Verify: context captured in constructor, not in handlers
[ ] 11. Verify: ARIA relationships complete (aria-controls, aria-labelledby, aria-expanded — A4)
[ ] 12. Verify: accessible name via idlangref constant, not hardcoded string — A3
[ ] 13. Verify: keyboard navigation respects RTL via getDirectionalKeys() — A12
[ ] 14. Verify: timers/listeners cleaned up in $effect return — A6
[ ] 15. Verify: gesture cleanup on unmount if using Gesture layer — A6, A15
[ ] 16. Verify: .get() for optional parents, .require() for required — A7
[ ] 17. Verify: no visual styles in provider (A8), static methods follow create/get/require pattern
[ ] 18. Verify: roving tabindex has exactly one tabindex=0 item — A14
[ ] 19. Create exports.ts (Provider, not Root)
[ ] 20. Add to components/index.ts barrel
[ ] 21. Create demo page in /test/soma/{name}
[ ] 22. Add link to /test/soma/+page.svelte index
[ ] 23. svelte-check: 0 errors
[ ] 24. Test in browser
[ ] 25. Document gaps vs reference libraries
[ ] 26. Create README.md in the component folder — anatomy, props, data-attrs,
        keyboard, ARIA, and at least one composition example. Follow the
        format used by dialog/README.md and accordion/README.md.
[ ] 27. Verify data-attr naming is consistent across code, CSS, and docs.
        `createAttrs` emits `data-{component}` for root and
        `data-{component}-{part}` for sub-parts — NEVER `data-soma-*`.
        Grep the component folder for `data-soma-` and any other
        prefix: if any querySelector, CSS selector, README, or inline
        string uses a name that does not match what `createAttrs`
        emits, the reference is broken (selectors return null, CSS
        matches nothing) and the contract registration lies about
        what is on the DOM.
```

## Common Mistakes

1. **Event handlers not in props** — defining `onclick` as a class method but forgetting to include it in the `props` derived object. The handler exists but never reaches the DOM.

2. **getContext in event handler** — calling `ctx.get()` inside onclick/onkeydown. getContext only works during component initialization. Capture the reference in the constructor.

3. **Naming Root instead of Provider** — the export name is always `Provider`, never `Root`.

4. **State class file named same as wrapper** — `select.svelte.ts` + `components/select.svelte` can cause Vite module resolution issues. Always use `{name}-provider.svelte.ts`.

5. **Missing readonly prop on form components** — Switch, Checkbox, RadioGroup should have `readonly` alongside `disabled`. readonly prevents interaction but keeps the element focusable.

6. **Comments in Spanish** — all code comments must be in English.

7. **Skipping reference library comparison** — mandatory before implementation. No exceptions.

8. **Redeclaring field types** — defining prop types in both `types.ts` and the provider Opts interface. Define canonical shapes once in `types.ts`, reference with `StateProps<>` / `ActiveProps<>`.

9. **Hardcoding aria strings** — use idlangref constants from `langs.ts`, never inline strings.

10. **Gesture capturing child clicks** — `setPointerCapture` must be deferred until moveBuffer is exceeded. Immediate capture on pointerdown steals click events from buttons inside the draggable area.

11. **`data-soma-*` prefix** — the framework never emits `data-soma-{component}-*`. `createAttrs` produces `data-{component}` for the root part and `data-{component}-{part}` for children. Writing a querySelector like `[data-soma-calendar-day]` returns `null` silently and the contract validator does NOT catch it (it only checks enum values, not attribute presence). Always grep the component folder for any `data-soma-` reference before completing the work — checklist item 27.

12. **Date types from the wrong module** — `DateValue`, `CalendarDate`, `CalendarDateTime`, `Time`, `ZonedDateTime`, `DateRange`, `Month`, etc. come from `$soma/external/dates` inside soma (which re-exports from `$lib/util/dias`). Never import from `$lib/util/dates` (the legacy vendored copy) or directly from `@internationalized/date`. Direct imports from `$lib/util/dias` are only acceptable from test pages outside the soma tree.

13. **Using `HourCycle` as `'12h' \| '24h'`** — the canonical form is numeric `12 \| 24`, matching `Intl.DateTimeFormat`'s `hour12` resolved option. The App-layer `ext/dates` service, `ext/app/types`, and the `dias` library all share this form. String forms are legacy.

## Audit-Derived Rules (mandatory for all components)

These rules were extracted from a full audit of all 25 soma components. Every issue below was found in multiple components. Follow these to avoid repeating them.

### A1. Register data-\* contracts

Every component MUST call `registerContract()` in its provider file. Without it, `assertContract()` in `assertProps()` is a no-op — data-\* values are never validated.

```ts
registerContract({
    name: 'dialog',
    version: 1,
    parts: {
        root: [
            { attr: 'data-state', values: ['open', 'closed'], description: 'Open state' }
        ],
        trigger: [
            { attr: 'data-state', values: ['open', 'closed'], description: 'Open state' }
        ],
        content: [
            { attr: 'data-state', values: ['open', 'closed'], description: 'Open state' }
        ]
    }
});
```

Add to checklist step 4, after `createAttrs`.

### A2. Root part must use 'root', not 'provider'

`createAttrs` only strips the suffix for `'root'` → `data-{component}`. Using `'provider'` produces `data-{component}-provider` which violates the naming convention. If the root provider has no DOM, it still uses `'root'` in the parts array.

```ts
// Correct
const attrs = createAttrs({
    component: 'collapsible',
    parts: ['root', 'trigger', 'content'] as const
});
// attrs.root → 'data-collapsible'

// Wrong
parts: ['provider', 'trigger', 'content'];
// attrs.provider → 'data-collapsible-provider' ← violates convention
```

### A3. Soma access, translations, and imports

**Soma access:** Declare `readonly soma = Soma.get()` in the root provider only if the component needs translations or presentation services. Sub-parts access soma via `this.provider.soma`.

**Translations:** Each component defines its idlangref constants in a `langs.ts` file:

```ts
// drawer/langs.ts
export const DRAWER_LANGS = {
    TRIGGER: '#?components.drawer.trigger|Open drawer',
    CLOSE: '#?common.buttons.close|Close',
} as const;
```

Providers import and use the constants:

```ts
import { DRAWER_LANGS } from './langs';

'aria-label': this.provider.soma?.langs.ts(DRAWER_LANGS.CLOSE),
```

**Translation namespace structure:**

```
common.buttons.close           ← project-wide, shared by soma + eidos + app
common.buttons.open
common.labels.*
components.drawer.trigger      ← component-specific
components.dialog.trigger
```

- Common keys live under `common.*` at the lang root — not under soma
- Component keys live under `components.{name}.*`
- Soma does NOT inject translations — it exports `componentLangs` from `core/langs.ts` which the consumer imports and extends into langs
- `langs.ts()` with idlangref for simple strings. `langs.t()` only for interpolated templates (e.g., `Page {{value}}`)

Do NOT:
- Create `translate()` helper methods in providers
- Use `?? 'fallback'` — the fallback belongs inside the langref (`#?path|fallback`)
- Hardcode aria strings — always use idlangref constants from the component's `langs.ts`
- Put common keys (close, open, cancel) under component namespaces — they belong in `common.*`

**Imports within soma:** Use relative paths, not `$soma/` aliases. Relative paths make the library portable without requiring alias configuration in the consumer's build. soma does not import from `$lib` — trivial utilities (like empty callbacks) are inline (`() => {}`).

```ts
// Inside soma — relative
import { DRAWER_LANGS } from './langs';
import type { DrawerSide } from './types';
import { Presence } from '../../layers/presence.svelte';

// Wrong — alias
import { DRAWER_LANGS } from '$soma/components/drawer/langs';
// Wrong — external dependency
import { noop } from '$lib/util/funcs';
```

Consumer code (layouts, test pages, app) uses `$soma/` alias — that's their build config, not soma's concern.

### A4. ARIA relationships are mandatory

Every component with trigger→content pattern MUST emit:

- **Trigger**: `aria-controls={contentId}`, `aria-expanded`
- **Content**: `aria-labelledby={triggerId}` (for dialogs, popovers, selects, drawers)
- **Form controls**: `aria-labelledby={labelId}` when a Label part exists
- **Groups**: `aria-label` or `aria-labelledby` on `role="group"`, `role="tablist"`, `role="toolbar"`, `role="radiogroup"`, `role="tree"`

Missing ARIA relationships = the component is broken for screen readers.

### A5. Feature flags are opt-in (`=== true`)

Per-item feature flags (Table columns, tree nodes) default to `false`. A feature only activates when the consumer explicitly sets it to `true`.

```ts
// Correct — opt-in
return col?.def.enableSorting === true;

// Wrong — opt-out (active by default)
return col?.def.enableSorting !== false;
```

Applies to Table: `enableSorting`, `enableFiltering`, `enableResizing`, `enablePinning`, `enableHiding` (exception: `enableHiding` defaults to `true` — documented in ColumnDef JSDoc).

### A6. Clean up timers, listeners, and observers

Every `setTimeout`, `setInterval`, `addEventListener`, `ResizeObserver`, or `MutationObserver` created in a provider MUST have cleanup in `$effect` return or explicit dispose. Uncleaned resources cause memory leaks.

```ts
// Correct
$effect(() => {
    const timer = setTimeout(fn, delay);
    return () => clearTimeout(timer);
});

// Wrong — leak
constructor() {
    setTimeout(fn, delay); // never cleared
    window.addEventListener('keydown', fn); // never removed
}
```

### A7. Use `.get()` for optional parents, `.require()` for required

| Method           | Returns                      | Use when                          |
| ---------------- | ---------------------------- | --------------------------------- |
| `X.create(opts)` | instance                     | Creating + registering in context |
| `X.get()`        | instance or `undefined`      | Parent is optional                |
| `X.require()`    | instance (throws if missing) | Parent is required                |

```ts
// Tooltip can work without Group — use get()
this.group = TooltipGroupProvider.get();

// Accordion Item MUST be inside Accordion — use require()
this.provider = AccordionProvider.require();
```

This convention applies to App, Soma, and all Provider classes. No standalone functions (`createApp`, `getSoma`). No `from()`.

### A8. No visual styles in headless providers

Headless providers MUST NOT emit visual CSS properties (`border-radius`, `background`, `color`, `overflow: auto`). Only functional CSS is allowed:

- `touch-action: none` — required for gesture drag
- `pointer-events: auto` — required for overlays and fixed-position content
- `transition: none` — required during active drag to disable CSS transitions
- `transform: translate3d(...)` — required during active drag for visual feedback
- CSS custom properties (`--drawer-progress`, `--drawer-offset-*`) — data for the visual layer

The visual layer (air/eidos) owns appearance. The provider owns behavior.

### A9. Dismissal behavior for drawers vs dialogs

A drawer is NOT a popover. `interactOutsideBehavior` should be `'ignore'` for drawers:

- **Modal drawer**: overlay `onclick` handles close. Dismissal layer only handles Escape.
- **Non-modal drawer**: background is interactive by definition. Dismissal layer disabled entirely. Escape handled via `onkeydown` on the content element.
- **Non-dismissible**: Dismissal layer fully disabled. Close button uses `forceClose()` (bypasses the `dismissible` guard).

### A10. DOM queries in providers must handle dynamism

`getItems()` patterns using `querySelectorAll` are fragile — they capture a snapshot, not a live reference. If items are added/removed dynamically, the query must re-run. For nested components (e.g., nested Accordion), filter results to only include elements whose closest root is the current root:

```ts
getTriggers(): HTMLButtonElement[] {
    const root = this.opts.ref?.current;
    if (!root) return [];
    const all = Array.from(root.querySelectorAll<HTMLButtonElement>(selector));
    return all.filter((el) => el.closest(`[${attrs.root}]`) === root);
}
```

### A11. Wrapper must be thin

Complex logic (effects, DOM manipulation, state machines, event coordination) belongs in the Provider, not the wrapper. The wrapper's job is: destructure props → wrap in Active/State → create Provider → mergeProps → render. If a wrapper has `$effect` blocks, `onMount`, or branching logic, the code belongs in the Provider.

### A12. Keyboard navigation must respect RTL

Components with arrow-key navigation MUST check `dir` and swap left/right keys. Use `getDirectionalKeys(dir, orientation)`.

```ts
const { nextKey, prevKey } = getDirectionalKeys(dir, orientation);
```

Do NOT hardcode `KEYS.ARROW_LEFT` / `KEYS.ARROW_RIGHT` for directional navigation.

### A13. Form components need hidden inputs

Components that participate in forms (Checkbox, RadioGroup, Switch, Select, TagsInput, NumberField) should render a hidden `<input>` with the current value and `name` prop. The `name` from a parent Group must propagate to children.

### A14. Roving tabindex: exactly one item gets tabindex=0

In roving tabindex patterns (RadioGroup, Toolbar, Tabs, ToggleGroup), exactly one item must have `tabindex=0` at all times — either the focused/selected item, or the first item when nothing is selected. Never all `-1` (group unreachable) and never multiple `0` (breaks single-tab-stop pattern).

### A15. Gesture layer integration

Components with drag behavior (Drawer, Slider, Splitter, ScrollArea, Toast) use the Gesture layer from `layers/gesture/`. Three specializations:

- `Gesture.base()` — pointer tracking + axis lock + velocity (Slider, ScrollArea)
- `Gesture.drag()` — base + progress + snap points + dismiss (Drawer, Toast)
- `Gesture.resize()` — base + delta + min/max constraints (Splitter)

Rules:
- `setPointerCapture` deferred until moveBuffer exceeded for containers with child buttons (Drawer, Slider). **Exception**: pure drag handles (Splitter resize trigger) capture immediately — the handle IS the drag target, no children to protect
- Gesture `.props` (only `onpointerdown`) must be spread into the component's `props`
- Gesture cleanup on unmount: `$effect(() => { return () => { this.gesture.cancel(); }; })`
- CSS vars (`--drawer-progress`, `--drawer-offset-x/y`) set by provider for visual layer
- During active drag: `transition: none` + inline `transform` for immediate feedback
- Scroll-drag guard: disable gesture via `enabled`, not by suppressing callback
- The gesture layer measures — the component decides what it means (dismiss, value, resize)

### A16. Non-modal overlay components

Components with `modal` prop (Dialog, Drawer) must adjust behavior when `modal=false`:

- **FocusScope**: `trap=false`, `enabled=false` — background must stay interactive
- **ScrollLock**: disabled — background scrolling must work
- **Dismissal**: disabled — no interactOutside, no focusOutside
- **Escape**: handled via `onkeydown` on the content element, not via Dismissal layer
- **Auto-focus**: prevented (`e.preventDefault()` in `onOpenAutoFocus`)
- **Content**: needs `tabindex=-1` to receive keyboard events without focus trap
- **Overlay**: not rendered (consumer should not include `<Overlay>` for non-modal)
- **Focus return**: non-modal close must return focus to trigger manually (FocusScope doesn't handle it)

### A17. Focus strategy: virtual vs DOM

Two focus strategies exist. Choose based on component type:

- **`aria-activedescendant` (virtual focus)**: focus stays on trigger/input, items highlighted via CSS `[data-highlighted]`. Used for **Select**, **Combobox** — the trigger owns keyboard, items are options.
- **Roving tabindex (DOM focus)**: items receive real DOM focus. Used for **DropdownMenu**, **RadioGroup**, **Toolbar**, **Tabs** — items are independent interactive elements.

Never mix both in the same component. If the trigger has `aria-activedescendant`, items must NOT call `.focus()`.

### A18. Registry pattern over DOM queries

Prefer registering sub-parts in a Map on mount/unmount over `querySelectorAll` for keyboard navigation:

```ts
// In root provider:
private triggerRegistry = new Map<number, HTMLElement>();
registerTrigger(index: number, el: HTMLElement) { this.triggerRegistry.set(index, el); }
unregisterTrigger(index: number) { this.triggerRegistry.delete(index); }

getRegisteredTriggers(): HTMLElement[] {
    return [...this.triggerRegistry.entries()]
        .sort((a, b) => a[0] - b[0])
        .map(([, el]) => el)
        .filter(el => el.getAttribute('aria-disabled') !== 'true');
}

// In sub-part constructor:
$effect(() => {
    const el = opts.ref.current;
    if (el) this.provider.registerTrigger(this.index, el);
    return () => this.provider.unregisterTrigger(this.index);
});
```

Benefits: no DOM queries, works with portaled/lazy-mounted elements, O(1) lookup.

Same pattern for value-to-label registries (Select, Combobox):

```ts
private labelRegistry = new Map<string, string>();
registerLabel(value: string, label: string) { this.labelRegistry.set(value, label); }
```

### A19. SafePolygon for hover-gap components

Components where pointer must traverse a gap between trigger and content (DropdownMenu submenus, Tooltip) integrate `SafePolygon` from `layers/floating/safe-polygon`:

```ts
import { SafePolygon } from '../../layers/floating/safe-polygon';

// In the provider that owns both trigger and content refs:
new SafePolygon({
    enabled: () => opts.open.current,
    triggerNode: () => this.triggerRef.current,
    contentNode: () => this.contentRef.current,
    onPointerExit: () => this.handleClose(),
    buffer: 2,
    transitIntentTimeout: 300
});
```

SafePolygon calculates a corridor polygon between trigger and content. The pointer can traverse the gap without closing. `onPointerExit` fires only when the pointer leaves the safe zone.

### A20. Exit animation via Presence

Components that dismiss/remove elements (Toast, Drawer) must integrate `Presence` for exit animations:

1. `dismiss()` marks the element as dismissing (state change, not removal)
2. `data-state` transitions from `'open'` to `'closed'`
3. Presence emits `data-ending-style` for CSS exit animation
4. Animation completes → Presence fires `onComplete(false)` → element removed from array

```ts
// In Toaster:
dismiss(id) { this.toasts = this.toasts.map(t => t.id === id ? { ...t, dismissing: true } : t); }
remove(id) { this.toasts = this.toasts.filter(t => t.id !== id); /* + onDismiss callback */ }

// In provider:
this.presence = new Presence({
    open: readableActive(() => this.isOpen),
    ref: opts.ref,
    onComplete: (open) => { if (!open) this.provider.toaster.remove(id); }
});
```

### A21. Contract case normalization

`registerContract()` and `assertContract()` normalize names to lowercase. Provider constructors pass TitleCase (`'Switch'`, `'Dialog'`), contracts register lowercase (`'switch'`, `'dialog'`). The normalization handles this transparently. No manual case matching needed.

### A22. Dismissal isValidEvent for complex widgets

Components with multiple interactive zones (Combobox, Select) must exclude their own elements from interact-outside detection. The `isValidEvent` callback should return `false` for clicks on trigger, input, and content:

```ts
isValidEvent: readableActive(() => (e: PointerEvent | FocusEvent) => {
    const target = e.target;
    if (!(target instanceof Node)) return true;
    if (inputEl?.contains(target)) return false;
    if (triggerEl?.contains(target)) return false;
    if (contentEl?.contains(target)) return false;
    return true;
})
```

Without this, clicking scrollbars inside the content, or clicking the trigger to close, triggers interact-outside and causes race conditions.