@oddkin/components 0.0.0-stage → 1.0.0-beta.1

package/agent/references/components/odd-textarea.md

@@ -0,0 +1,126 @@
+# `<odd-textarea>` (OddkinTextarea)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Forms. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A labelled multi-line text field that participates in forms like a native textarea, with a
+character count while `maxlength` is set.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/textarea';`
+- Class: `import { OddkinTextarea } from '@oddkin/components/textarea';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` (reflects) | string \| undefined | undefined | Name submitted with the form. Reflected: a form-associated element submits under its name attribute. |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents interaction and submission. |
+| `description` | `description` | string | '' | Help text below the label. |
+| `error` | `error` | string | '' | Error message; marks the field invalid (custom validity) while set. |
+| `label` | `label` | string | '' | Visible label; names the control. |
+| `defaultValue` | `value` | string | '' | Initial value; the `value` attribute, as on native inputs. |
+| `minLength` | `minlength` | number \| undefined | undefined | Fewest characters. |
+| `maxLength` | `maxlength` | number \| undefined | undefined | Most characters; typing stops there. |
+| `placeholder` | `placeholder` | string | '' | Placeholder; never a substitute for a label. |
+| `autocomplete` | `autocomplete` | string | '' | Autofill hint for the native field. |
+| `required` | `required` (reflects) | boolean | false | A value is required to submit. |
+| `readonly` | `readonly` (reflects) | boolean | false | Prevents editing; still submitted. |
+| `rows` | `rows` | number | 4 | Visible lines; the least the field shows while `resize` is `auto`. |
+| `resize` | `resize` (reflects) | "none" \| "vertical" \| "auto" | 'vertical' | How the field changes height: the user drags it (`vertical`), never (`none`), or it follows its content (`auto`). |
+| `strings` | none: assign as a property | Partial<{ count: string; }> \| undefined | undefined | Localized string overrides; `count` takes `{count}` and `{max}`. |
+| `form` | none (read-only) | HTMLFormElement \| null |  | The form this field belongs to, if any. |
+| `validity` | none (read-only) | ValidityState |  | The field's validity, as on a native form control. |
+| `validationMessage` | none (read-only) | string |  | The message the browser would show for the field's invalid state, or empty. |
+| `willValidate` | none (read-only) | boolean |  | Whether the field takes part in constraint validation (false while disabled or read-only). |
+| `value` | none: assign as a property | string |  | The current value. Setting it (or typing) detaches it from `defaultValue`. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `checkValidity()` | Whether the field is valid; when not, fires `invalid` at it, as on native controls. |
+| `reportValidity()` | As `checkValidity()`, and an invalid field also shows its error to the user. |
+| `setCustomValidity()` | As on native controls; the message is also shown, since it sets `error`. An empty string clears it. |
+| `formResetCallback()` | Native callback: the owning form was reset. |
+| `formStateRestoreCallback()` | Native callback: restore after navigation or autofill restore. |
+| `formDisabledCallback()` | Native callback: an ancestor fieldset's disabled state changed. |
+| `formAssociatedCallback()` | Native callback: the form owner changed (moved, `form` attribute, or the named form). |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | Native `input` events cross the shadow boundary once; declared here for metadata and sync. |
+| `change` | CustomEvent | user (authored) | Re-dispatched at the host when the user commits a change (native `change` is not composed). |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The native `<textarea>`. |
+| `count` | The character count under the field ("12 / 200 characters") while `maxlength` is set and no error shows; referenced by `aria-describedby`, not announced while typing. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, control, error, and count. |
+| `label` | The visible label. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-field-background` | Background colour. Shared by every form control and the field recipe. |
+| `--odd-field-border-color` | Border colour. Shared by every form control and the field recipe. |
+| `--odd-field-height` | Minimum height (never below the target-size token). Shared by every form control and the field recipe. |
+| `--odd-field-radius` | Corner radius. Shared by every form control and the field recipe. |
+| `--odd-textarea-max-height` | Tallest a `resize="auto"` field grows before it scrolls (default 40vh). |
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: Multi-line text in forms: descriptions, comments, messages. (src/textarea/textarea.ts:31)
+- Not for: A single line (use odd-input); rich text. (src/textarea/textarea.ts:32)
+- Accessibility: `label` names the native textarea inside the shadow root; a `<label for>` outside it cannot. Description, error, and count are announced through `aria-describedby`; `aria-invalid` is set for `error`, or for an invalid value after the user leaves the field or a validity check fails; reset clears it. (src/textarea/textarea.ts:28)
+- Keyboard: Native textarea behavior: Enter inserts a line break; Tab moves focus. (src/textarea/textarea.ts:29)
+- Limitations: `resize="auto"` grows with `field-sizing: content` where the engine has it; elsewhere the element measures the field as its value or width changes. iOS and Firefox for Android draw no resize handle. (src/textarea/textarea.ts:33)
+- Limitations: Validation bubbles anchor to the inner textarea. `formStateRestoreCallback` restores the value; autofill depends on the inner textarea's `autocomplete`. (src/textarea/textarea.ts:34)
+
+## Examples
+
+- `example:odd-textarea/autoGrow` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/count` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/default` in src/textarea/textarea.examples.ts (package source), preview roles role:textArea
+- `example:odd-textarea/description` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/disabled` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/fixedHeight` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/inForm` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/invalid` in src/textarea/textarea.examples.ts (package source)
+- `example:odd-textarea/readonly` in src/textarea/textarea.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-textarea/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-textarea/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-field-background`, `--odd-field-border-color`, `--odd-field-height`, `--odd-field-radius`, `--odd-textarea-max-height`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-toast.md

@@ -0,0 +1,93 @@
+# `<odd-toast>` (OddkinToast)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Overlays. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A short message about something that just happened, at the block-end and inline-end corner of
+the viewport: a tone glyph, a title, the message, an optional action, and a close button. It
+closes by itself after `duration` unless it has an action; no toast's time runs while the
+pointer or focus is on any open toast, or while the page is hidden (WCAG 2.2.1). Open toasts
+stack in document order, the last at the corner, so reading and Tab order follow the screen.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/toast';`
+- Class: `import { OddkinToast } from '@oddkin/components/toast';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `tone` (reflects) | "neutral" \| "info" \| "success" \| "warning" \| "danger" | 'neutral' | Meaning colour and glyph; `danger` is an `alert`, announced at once. |
+| `label` | `label` | string | '' | The title, shown above the message. |
+| `duration` | `duration` | number | 5000 | Milliseconds it stays open, counted only while no open toast has the pointer or focus and the page is visible; read at each opening. 0, or an action in the `end` slot, keeps it open until it is closed. |
+| `open` | `open` (reflects) | boolean | false | Whether it is shown. |
+| `strings` | none: assign as a property | Partial<{ close: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Shows it and starts its time. |
+| `close()` | Closes it; focus inside returns to where it was before it opened. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The message. |
+| `end` | One action, such as "Undo". A toast with an action stays until it is closed. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The glyph, the title, the message, the action, and the close button. |
+| `close` | The close button. |
+| `label` | The title. |
+| `marker` | The tone glyph. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-toast-inline-size` | Its width, within the viewport. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A passing result of the user's action: saved, sent, copied, with Undo or Retry. (src/toast/toast.ts:37)
+- Not for: A message that must stay with its region (use odd-alert); a decision (use odd-dialog); a field error (use the field's `error`). (src/toast/toast.ts:38)
+- Accessibility: A `status` live region, or an `alert` for `danger`, announced when it opens: its title and message join the region just after it shows. Opening it never moves focus; keep toasts after the controls that raise them, so Tab reaches an action. The close button is named by `strings.close`. (src/toast/toast.ts:34)
+- Keyboard: Tab reaches its action and its close button in document order. Focus in any open toast pauses them all. (src/toast/toast.ts:35)
+
+## Examples
+
+- `example:odd-toast/danger` in src/toast/toast.examples.ts (package source)
+- `example:odd-toast/default` in src/toast/toast.examples.ts (package source), preview roles role:toast
+- `example:odd-toast/timed` in src/toast/toast.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-toast/errorTone` produces `usage.attribute.value`; correct: `example:odd-toast/danger`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-toast-inline-size`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-toolbar.md

@@ -0,0 +1,77 @@
+# `<odd-toolbar>` (OddkinToolbar)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Actions. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A named group of controls with one Tab stop (APG toolbar): arrow keys move focus among the
+slotted controls, which stay the author's own elements. An `<hr>` child is drawn as a separator.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/toolbar';`
+- Class: `import { OddkinToolbar } from '@oddkin/components/toolbar';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the toolbar. |
+| `orientation` | `orientation` (reflects) | "vertical" \| "horizontal" | 'horizontal' | Controls in a row or a column; sets the arrow keys that move between them. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | Controls (buttons, odd-button, inputs, links), text, and `<hr>` separators. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-toolbar-background` | Background of the surface. |
+| `--odd-toolbar-radius` | Corner radius of the surface. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Several related actions or formatting controls used together, such as above a table or an editor. (src/toolbar/toolbar.ts:38)
+- Not for: A single action or two (place buttons directly); navigation (use links or odd-side-nav); a menu of commands (use odd-menu). (src/toolbar/toolbar.ts:39)
+- Accessibility: The host is a `toolbar` named by `label`, with `aria-orientation`. Only one control is in the Tab order; disabled and hidden controls are skipped. Text fields and sliders keep their own arrow keys. Give an `<hr>` separator `aria-orientation="vertical"` in a horizontal toolbar. (src/toolbar/toolbar.ts:35)
+- Keyboard: Tab reaches the last focused control. Left and Right (Up and Down when vertical; mirrored right to left) move between controls, wrapping; Home and End go to the first and last. In a text field or a slider, these keys move the caret or change the value. (src/toolbar/toolbar.ts:36)
+
+## Examples
+
+- `example:odd-toolbar/default` in src/toolbar/toolbar.examples.ts (package source), preview roles role:toolbar
+- `example:odd-toolbar/selection` in src/toolbar/toolbar.examples.ts (package source)
+- `example:odd-toolbar/vertical` in src/toolbar/toolbar.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-toolbar/orientationRow` produces `usage.attribute.value`; correct: `example:odd-toolbar/vertical`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-toolbar-background`, `--odd-toolbar-radius`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-tooltip.md

@@ -0,0 +1,86 @@
+# `<odd-tooltip>` (OddkinTooltip)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Overlays. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A short description of the control it is anchored to, shown while the pointer rests on the
+control or the control has focus. It stays while the pointer is over the control or the tooltip,
+and until Escape (WCAG 1.4.13). It describes the control and is never its name.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/tooltip';`
+- Class: `import { OddkinTooltip } from '@oddkin/components/tooltip';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `anchor` | `anchor` | string | '' | The ID of the element it describes and is placed against, in the same document or shadow root. |
+| `side` | `side` | "inline-end" \| "inline-start" \| "block-end" \| "block-start" | 'block-start' | The side of the anchor it shows on, in the anchor's writing direction; it flips when there is more room on the other side. |
+| `align` | `align` | "center" \| "start" \| "end" | 'center' | How it lines up with the anchor along that side. |
+| `open` | `open` (reflects) | boolean | false | Whether it is shown. |
+| `anchorElement` | none: assign as a property | Element \| null |  | The element it describes, when it is not found by `anchor` (another tree, or no ID). |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Shows it. |
+| `close()` | Hides it. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The text: a short phrase, nothing interactive. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The text, inside the surface. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-tooltip-max-inline-size` | The widest it grows before its text wraps. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A short hint about a control: what an icon button does, a keyboard shortcut. (src/tooltip/tooltip.ts:28)
+- Not for: Content to read at length or interact with (use odd-popover); a control's only name (use its label). (src/tooltip/tooltip.ts:29)
+- Accessibility: A `tooltip` that describes its anchor: a native anchor gets its `id` in `aria-describedby` (an `id` is generated when it has none); an Oddkin control adds its text to its inner control's description. Give the anchor its own name. It takes no focus. (src/tooltip/tooltip.ts:25)
+- Keyboard: Focus on the anchor shows it; Escape hides it until the anchor is hovered or focused again. (src/tooltip/tooltip.ts:26)
+
+## Examples
+
+- `example:odd-tooltip/default` in src/tooltip/tooltip.examples.ts (package source), preview roles role:tooltip
+- `example:odd-tooltip/inlineEnd` in src/tooltip/tooltip.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-tooltip/physicalSide` produces `usage.attribute.value`; correct: `example:odd-tooltip/inlineEnd`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-tooltip-max-inline-size`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-tree.md

@@ -0,0 +1,95 @@
+# `<odd-tree>` (OddkinTree)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Collections. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A hierarchy the user browses and selects in (APG tree view): rows of items that expand and
+collapse, from `items`. Items holding a selected item start expanded. Children of a `lazy` item
+load when it first expands: listen to `odd-toggle`, then assign new `items` in which that item
+has `children`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/tree';`
+- Class: `import { OddkinTree } from '@oddkin/components/tree';`
+- Dependency (icon): `<odd-icon>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the tree. |
+| `items` | none: assign as a property | readonly TreeItemRecord[] \| undefined | undefined | The top-level items; each may hold `children`, or be `lazy`. |
+| `expanded` | none: assign as a property | readonly string[] \| undefined | undefined | Ids of expanded items, owned by the caller. Omit it to let the element track expansion. |
+| `value` | `value` | string | '' | Id of the selected item. |
+| `values` | none: assign as a property | readonly string[] \| undefined | undefined | Ids of the selected items with `multiple`. |
+| `multiple` | `multiple` (reflects) | boolean | false | Several items can be selected. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a busy row and marks the tree busy. |
+| `strings` | none: assign as a property | Partial<{ loading: string; empty: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-toggle` | CustomEvent<NavigationToggleDetail> | user (authored) | An item is about to expand or collapse; cancelable. Load the children of a lazy item here. |
+| `input` | CustomEvent | user (authored) | The user selected an item (`value`, or `values` with `multiple`). |
+| `change` | CustomEvent | user (authored) | Dispatched after `input` for each user selection (native `change` is not composed). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `empty` | Shown when there are no items and nothing is loading (default `strings.empty`). |
+| `status` | Status content such as an error and a retry button. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `empty` | The wrapper of the empty slot. |
+| `item` | Each row (`role="treeitem"`). |
+| `loading` | The busy row while `loading`. |
+| `tree` | The `role="tree"` list of rows. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Browsing and choosing in nested data: files, folders, categories, an outline. (src/tree/tree.ts:49)
+- Not for: Site navigation (use odd-side-nav); a flat list of choices (use odd-listbox); content sections (use odd-disclosure). (src/tree/tree.ts:50)
+- Accessibility: A `tree` named by `label`, `aria-multiselectable` with `multiple`, `aria-busy` while loading. Each row is a `treeitem` with `aria-level`, `aria-setsize`, `aria-posinset`, `aria-expanded` when it has children, `aria-selected`, and `aria-busy` while its lazy children load. Selection is marked by a bar and weight, not colour alone. Disabled rows are skipped by the keyboard. (src/tree/tree.ts:46)
+- Keyboard: Tab reaches the selected row (or the first). Up and Down move between shown rows; Home and End go to the first and last. Right expands a closed row, or moves into an open one; Left collapses an open row, or moves to its parent (mirrored right to left). `*` expands every sibling. Enter or Space selects (with `multiple`, toggles). Typing moves to the next row whose label starts with the typed characters. (src/tree/tree.ts:47)
+
+## Examples
+
+- `example:odd-tree/collapsed` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/default` in src/tree/tree.examples.ts (package source), preview roles role:tree
+- `example:odd-tree/empty` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/error` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/lazy` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/loading` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/multiple` in src/tree/tree.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-tree/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-tree/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-validation-summary.md

@@ -0,0 +1,80 @@
+# `<odd-validation-summary>` (OddkinValidationSummary)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Forms. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Lists a form's problems after a submission that validation blocked: a heading with the count,
+then each invalid control's label and message as a link that moves focus to the control. It
+takes focus when it appears, shrinks as fields are fixed, and hides once the form is valid.
+Entered values are never cleared.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/validation-summary';`
+- Class: `import { OddkinValidationSummary } from '@oddkin/components/validation-summary';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The heading; default `strings.title`, "Please fix {count} fields". |
+| `form` | `form` | string | '' | ID of the form it reports on; default: the ancestor form. |
+| `strings` | none: assign as a property | Partial<{ title: string; titleOne: string; entry: string; }> \| undefined | undefined | Localized string overrides: `title`, `titleOne` (one problem), `entry`. |
+
+## Events
+
+None.
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface; takes focus when the summary appears. |
+| `label` | The heading. |
+| `link` | A problem: the control's label and message, linking to the control. |
+| `list` | The list of problems. |
+| `marker` | The danger glyph. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Forms with several fields, where a failed submission should say what to fix in one place. (src/validation-summary/validation-summary.ts:73)
+- Not for: One field's error (use the field's `error`); a failed save after a valid submission (use odd-alert). (src/validation-summary/validation-summary.ts:74)
+- Accessibility: A `role="group"` named by its heading. After a blocked submission it receives focus (`tabindex="-1"`), so the heading and the problems are read first; each link moves focus to its control. The browser's own validation bubbles are not shown while the summary reports the problems. (src/validation-summary/validation-summary.ts:70)
+- Keyboard: Tab moves through the links; Enter on a link moves focus to that control. (src/validation-summary/validation-summary.ts:71)
+- Limitations: It reports submissions the user starts inside the form (a click on a submit button there, or Enter in a field). `form.requestSubmit()` and `form.checkValidity()` called by a script, and a submit button outside the form (its `form` attribute), leave it hidden. A form with `novalidate` is never blocked, so the summary never shows. (src/validation-summary/validation-summary.ts:75)
+- Limitations: The form is found when the summary connects or its `form` attribute changes: the ancestor form, or the form with that ID in the same document or shadow root. (src/validation-summary/validation-summary.ts:76)
+
+## Examples
+
+- `example:odd-validation-summary/default` in src/validation-summary/validation-summary.examples.ts (package source), preview roles role:validationSummary
+- `example:odd-validation-summary/externalForm` in src/validation-summary/validation-summary.examples.ts (package source)
+- `example:odd-validation-summary/heading` in src/validation-summary/validation-summary.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-validation-summary/forAttribute` produces `usage.attribute.unknown`; correct: `example:odd-validation-summary/externalForm`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/composition.md

@@ -0,0 +1,97 @@
+# Interfaces as data: `@oddkin/components/composition`
+
+An interface described as data: published Oddkin elements and native text elements, their attributes and properties, text, and events mapped to action names. Rendered by renderComposition() from @oddkin/components/composition.
+
+## Entry
+
+- `import { validateComposition, renderComposition } from '@oddkin/components/composition';` (never imported by element entries).
+- `validateComposition(document: unknown, options?: { readonly limits?: CompositionLimits; }): CompositionValidation`: Check a composition document; `ok` is false when any diagnostic is an error.
+- `renderComposition(document: unknown, target: ParentNode, options: RenderCompositionOptions): RenderedComposition`: Validate `document`, then append it to `target`; refuse it whole if any check fails.
+
+## Types
+
+- `CompositionElement`: One element of a composition; text is a plain string.
+  - `element: string`
+  - `id?: string`: The element's `id`, unique in the document.
+  - `slot?: string`: A published slot of the parent element; the default slot when absent.
+  - `attributes?: Readonly<Record<string, JsonValue>>`
+  - `properties?: Readonly<Record<string, JsonValue>>`
+  - `children?: readonly CompositionNode[]`
+  - `actions?: Readonly<Record<string, string>>`: Published event names mapped to action names the host handles.
+- `CompositionNode = string | CompositionElement`
+- `CompositionDocument`
+  - `$schema?: string`
+  - `version: typeof COMPOSITION_VERSION`
+  - `root: readonly CompositionNode[]`
+- `CompositionDiagnostic = ModelDiagnostic`
+- `CompositionLimits`
+  - `depth?: number`: Deepest element nesting (default 16).
+  - `nodes?: number`: Most nodes, text included (default 500).
+- `CompositionValidation`
+  - `ok: boolean`
+  - `diagnostics: readonly CompositionDiagnostic[]`
+- `CompositionAction`: An event of a rendered element, mapped to an action name by the composition.
+  - `action: string`
+  - `event: Event`
+  - `element: Element`
+  - `id: string | undefined`: The element's composition `id`, if it has one.
+- `RenderCompositionOptions`
+  - `allow: readonly string[]`: Every tag the renderer may create, natives included; anything else is refused.
+  - `onAction?: (action: CompositionAction) => void`: Called for each mapped event; the composition never carries a handler.
+  - `limits?: CompositionLimits`
+- `RenderedComposition`
+  - `ok: boolean`: False when the document was refused; nothing was rendered then.
+  - `diagnostics: readonly CompositionDiagnostic[]`
+  - `nodes: readonly Node[]`: The top-level nodes appended to the target.
+  - `dispose(): void`: Removes the nodes and their action listeners.
+
+## Document
+
+- Schema: `@oddkin/components/schemas/composition/composition.v1.json` (`https://oddkin.dev/schemas/composition/composition.v1.json`). Required: `version`, `root`; `version` is `1`.
+- `root` and every `children`: an array of nodes. A node is a string (text) or an object with `element`: a published element (one schema each, below) or a native text element (`p`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `span`, `strong`, `em`, `a`, `ul`, `ol`, `li`).
+- An element object: `element`, optional `id` (The element's id, unique in the document.), `slot` (A named slot of the parent element.), `attributes` (published attributes and properties only), `children`, and `actions`: event name to action name (An action name the host handles, such as "settings.save"; never code.).
+- Values are data: no functions, no markup strings, no styles. The host maps action names to its own handlers.
+
+## Element schemas
+
+54 files in `@oddkin/components/schemas/composition/`: `odd-alert`, `odd-avatar`, `odd-badge`, `odd-breadcrumbs`, `odd-button`, `odd-calendar`, `odd-card`, `odd-carousel`, `odd-checkbox-group`, `odd-checkbox`, `odd-chip`, `odd-color-picker`, `odd-combobox`, `odd-command-palette`, `odd-container`, `odd-copy-button`, `odd-date-picker`, `odd-dialog`, `odd-disclosure`, `odd-drawer`, `odd-empty-state`, `odd-file-input`, `odd-icon`, `odd-input`, `odd-listbox`, `odd-menu`, `odd-one-time-code`, `odd-pagination`, `odd-picker`, `odd-popover`, `odd-progress`, `odd-radio-group`, `odd-rating`, `odd-relative-time`, `odd-scroll-region`, `odd-segmented-control`, `odd-select`, `odd-side-nav`, `odd-skeleton`, `odd-slider`, `odd-spinner`, `odd-split-button`, `odd-split-panel`, `odd-stat`, `odd-status-marker`, `odd-switch`, `odd-tab-panel`, `odd-tabs`, `odd-textarea`, `odd-toast`, `odd-toolbar`, `odd-tooltip`, `odd-tree`, `odd-validation-summary`. Each lists the element's attributes with their types, its slots, and its actions.
+
+A document sets only what an element's schema lists. A property the schema leaves out (it holds code, an element, or data the host owns) is the host's to set after rendering, and `validateComposition` reports it as `composition.property.notPortable`. Read an element's schema before writing it.
+
+## Example (validated when this kit was generated)
+
+```json
+{
+  "$schema": "https://oddkin.dev/schemas/composition/composition.v1.json",
+  "version": 1,
+  "root": [
+    {
+      "element": "odd-card",
+      "attributes": {
+        "label": "Settings"
+      },
+      "children": [
+        {
+          "element": "p",
+          "children": [
+            "Save your changes before leaving."
+          ]
+        },
+        {
+          "element": "odd-button",
+          "slot": "footer",
+          "attributes": {
+            "appearance": "primary"
+          },
+          "children": [
+            "Save"
+          ],
+          "actions": {
+            "click": "settings.save"
+          }
+        }
+      ]
+    }
+  ]
+}
+```

package/agent/references/models/oddkin.navigation.md

@@ -0,0 +1,5 @@
+# Model oddkin.navigation v1
+
+Id `model:oddkin.navigation`. JSON Schema: `@oddkin/components/schemas/oddkin.navigation.v1.json`.
+
+Kinds: `link`, `action`, `group`.