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

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

@@ -0,0 +1,82 @@
+# `<odd-chip>` (OddkinChip)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Display. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A compact token for a value, filter, or tag, with an explicit remove button when `removable`.
+The chip itself is not focusable; only its remove button is.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/chip';`
+- Class: `import { OddkinChip } from '@oddkin/components/chip';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `removable` | `removable` (reflects) | boolean | false | Shows a remove button. |
+| `selected` | `selected` (reflects) | boolean | false | Selection look, as for a chosen value. |
+| `disabled` | `disabled` (reflects) | boolean | false | Dims the chip and disables its button. |
+| `strings` | none: assign as a property | Partial<{ remove: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-chip-remove` | CustomEvent<Record<string, never>> | user (authored) | The remove button was activated; the application removes the chip or its value. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The label. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The chip. |
+| `remove` | The remove button. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-chip-radius` | Corner radius. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Selected values, applied filters, and tags that can be removed. (src/chip/chip.ts:28)
+- Not for: Actions (use a button); status (use a badge). (src/chip/chip.ts:29)
+- Accessibility: The remove button is named "Remove {label}" from the chip's text (`strings.remove`). Backspace or Delete on it also removes. Move focus to a sensible place after removing the chip. (src/chip/chip.ts:25)
+- Keyboard: Tab reaches the remove button; Enter, Space, Backspace, or Delete removes. (src/chip/chip.ts:26)
+
+## Examples
+
+- `example:odd-chip/default` in src/chip/chip.examples.ts (package source), preview roles role:chip
+- `example:odd-chip/disabled` in src/chip/chip.examples.ts (package source)
+- `example:odd-chip/plain` in src/chip/chip.examples.ts (package source)
+- `example:odd-chip/selected` in src/chip/chip.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-chip/removableFalse` produces `usage.boolean.false`; correct: `example:odd-chip/plain`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-chip-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-color-picker.md

@@ -0,0 +1,124 @@
+# `<odd-color-picker>` (OddkinColorPicker)
+
+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.
+
+One colour, typed as hex or chosen in a popup: a saturation-and-brightness area, a hue slider,
+hex and opacity entry, the RGB values, and suggested swatches, applied or cancelled. The value is
+a native colour input's: `#rrggbb`, or with `alpha`, the CSS form color(srgb r g b / a); it is always a
+colour (black by default).
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/color-picker';`
+- Class: `import { OddkinColorPicker } from '@oddkin/components/color-picker';`
+
+## 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 field. |
+| `defaultValue` | `value` | string | '' | Initial colour; the `value` attribute, as on a native colour input. |
+| `alpha` | `alpha` (reflects) | boolean | false | The colour takes an opacity, as HTML’s `alpha` on a colour input. |
+| `options` | none: assign as a property | readonly OptionRecord[] \| undefined | undefined | Suggested colours; when set, `<option>` children are ignored. |
+| `strings` | none: assign as a property | Partial<{ choose: string; change: string; invalid: string; area: string; areaValue: string; hue: string; hex: string; opacity: string; rgb: string; swatches: string; cancel: string; apply: string; }> \| undefined | undefined | Localized string overrides: `choose`, `change` (`{color}`), `invalid`, `area`, `areaValue` (`{saturation}`, `{brightness}`), `hue`, `hex`, `opacity`, `rgb` (`{r}`, `{g}`, `{b}`), `swatches`, `cancel`, `apply`. |
+| `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 colour: `#rrggbb`, or with `alpha`, color(srgb r g b / a). Setting it 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) | Dispatched with `change` for each colour the user commits (typed, or applied in the popup). |
+| `change` | CustomEvent | user (authored) | Dispatched after `input` for each colour the user commits. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `apply` | Commits the popup's colour and closes it. |
+| `area` | Saturation (across) and brightness (up) for the hue. |
+| `area-thumb` | The area's handle (`role="slider"`); takes focus. |
+| `button` | Opens the popup. |
+| `cancel` | Closes the popup without a change. |
+| `control` | The text input with the colour as hex. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | The field: label, description, control box, and error. |
+| `hex` | The popup's hex input. |
+| `hue` | The hue slider's track. |
+| `hue-thumb` | The hue handle (`role="slider"`). |
+| `label` | The visible label. |
+| `opacity` | The opacity input, in percent (with `alpha`). |
+| `option-swatch` | One suggested colour: a radio, checked while it is the colour. |
+| `popup` | The popup (a non-modal dialog). |
+| `rgb` | The red, green, and blue values. |
+| `swatch` | The colour, at the start of the field. |
+| `swatches` | The suggested colours (`<option>` children or `options`). |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `open` | The popup is open. |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: A colour the user chooses for their own content: a layer, a label, a highlight. (src/color-picker/color-picker.ts:88)
+- Not for: Theme colours (use design tokens); one colour from a short fixed set (use odd-radio-group or odd-segmented-control). (src/color-picker/color-picker.ts:89)
+- Accessibility: The text input is named by the label. The button after it is named "Choose color", or "Change color," with the hex, and has `aria-haspopup="dialog"` and `aria-expanded`; it opens a non-modal dialog named "Choose color". The area is one `role="slider"` (WAI-ARIA has no two-axis slider) whose `aria-valuenow` is the saturation and whose `aria-valuetext` names saturation and brightness; the hue is a slider in degrees; the opacity input is a spinbutton; the suggested colours are native radios named by their labels. Typed text that is not a hex colour makes the field invalid. (src/color-picker/color-picker.ts:85)
+- Keyboard: The input and the button are Tab stops; in the popup, the area, the hue, the hex and opacity inputs, the suggested colours (one stop, arrow keys between them), Cancel, and Apply. Area: Left and Right saturation (swapped right to left), Up and Down brightness, Page Up and Page Down brightness by ten, Home and End saturation to 0 and 100. Hue: the slider keys, Page Up and Page Down by ten degrees. Opacity: Up and Down by one, Page Up and Page Down by ten. Escape closes without a change, as Cancel does. (src/color-picker/color-picker.ts:86)
+- Limitations: The value is sRGB, 8 bits per channel (HTML's limited-srgb colour space); HTML's display-p3 colour space is not offered. Typed colours are hex; the value also takes any CSS colour from script. (src/color-picker/color-picker.ts:90)
+
+## Examples
+
+- `example:odd-color-picker/alpha` in src/color-picker/color-picker.examples.ts (package source)
+- `example:odd-color-picker/children` in src/color-picker/color-picker.examples.ts (package source)
+- `example:odd-color-picker/default` in src/color-picker/color-picker.examples.ts (package source), preview roles role:colorPicker
+- `example:odd-color-picker/disabled` in src/color-picker/color-picker.examples.ts (package source)
+- `example:odd-color-picker/invalid` in src/color-picker/color-picker.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-color-picker/alphaFalse` produces `usage.boolean.false`; correct: `example:odd-color-picker/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-combobox.md

@@ -0,0 +1,140 @@
+# `<odd-combobox>` (OddkinCombobox)
+
+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.
+
+An editable input with a popup listbox (APG combobox, list autocomplete): typing filters the
+options and the first match becomes active; Enter or a click chooses. With `multiple`, chosen
+values are chips in the field, collapsed to "+N" while the field is not in use. Options come from
+`<option>` and `<optgroup>` children, written as for a native select, or from `options`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/combobox';`
+- Class: `import { OddkinCombobox } from '@oddkin/components/combobox';`
+- Dependency (avatar): `<odd-avatar>`
+
+## 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. |
+| `options` | none: assign as a property | readonly OptionRecord[] \| undefined | undefined | The choices; when set, `<option>` children are ignored. |
+| `value` | `value` | string | '' | Value of the selected option; the `value` attribute sets the default. |
+| `values` | none: assign as a property | readonly string[] \| undefined | undefined | Values of the selected options with `multiple`. |
+| `multiple` | `multiple` (reflects) | boolean | false | Several options can be selected. |
+| `required` | `required` (reflects) | boolean | false | An option must be selected to submit. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a busy row and marks the options busy. |
+| `view` | `view` (reflects) | "text" \| "chips" \| "count" \| "auto" \| "expandable" \| "avatars" \| "grouped" | 'chips' | With `multiple`, how the chosen values show in the field: chips ("+N" for those that do not fit), a count, a sentence (`text`), chips up to four and then the count (`auto`), two rows of chips with Show all (`expandable`), initials (`avatars`), or a count per group (`grouped`). |
+| `selectAll` | `select-all` | boolean | false | With `multiple` and options, a "Select all" check box above them: it chooses every usable option shown, or clears them when all are chosen. |
+| `review` | `review` | boolean | false | With `multiple`, the open popup starts with the chosen values: "Selected (N)", a disclosure of the first three, each removable, and View N more. |
+| `readonly` | `readonly` (reflects) | boolean | false | The value shows but cannot be changed; it is still submitted. |
+| `placeholder` | `placeholder` | string | '' | Text shown in the empty input. |
+| `noFilter` | `no-filter` (reflects) | boolean | false | The element does not filter: listen to `odd-query-change` and replace `options` with the matches. |
+| `strings` | none: assign as a property | Partial<{ loading: string; empty: string; clear: string; remove: string; selected: string; more: string; count: string; others: string; othersOne: string; group: string; total: string; showAll: string; showLess: string; selectAll: string; clearAll: string; selectedCount: string; viewMore: string; }> \| undefined | undefined | Localized string overrides; `remove` takes `{label}` and `more` takes `{count}`. |
+| `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). |
+| `query` | none (read-only) | string |  | The text in the input, as the user typed it (read-only). |
+
+## 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) | The user changed the selection. |
+| `change` | CustomEvent | user (authored) | Dispatched after `input` for each user change (native `change` is not composed). |
+| `odd-query-change` | CustomEvent<QueryChangeDetail> | user (authored) | The user typed: `detail.query` is the text in the input. With `no-filter`, replace the options or items with the matches. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `empty` | Shown when no option matches and nothing is loading (default `strings.empty`). |
+| `status` | Status content such as an error and a retry button, shown in the popup. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `chip` | Each chosen value with `multiple`. |
+| `chip-remove` | The button that removes a chip's value. |
+| `clear` | The button that clears the value, shown while there is one. |
+| `control` | The field box holding the input and, with `multiple`, the chips. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `empty` | The wrapper of the empty slot. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, control, and error. |
+| `group` | Each group's heading. |
+| `input` | The text input with `role="combobox"`. |
+| `label` | The visible label. |
+| `listbox` | The `role="listbox"` element. |
+| `loading` | The busy row while `loading`. |
+| `more` | The "+N" chip that stands for the chips not shown. |
+| `option` | Each option row. |
+| `popup` | The popup surface holding the listbox and the states. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: Choosing from a long list by typing: people, projects, countries; several values with `multiple`. (src/combobox/combobox.ts:56)
+- Not for: A short list (use odd-select or odd-radio-group); free text with suggestions only (use odd-input); commands (use odd-command-palette). (src/combobox/combobox.ts:57)
+- Accessibility: The input has `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-autocomplete="list"`, and names the active option with `aria-activedescendant`; `label` names it. Options carry `aria-selected`; with `multiple` they are drawn with a check box, and the listbox has `aria-multiselectable`. Chips are a list named by `strings.selected`; each remove button is named by `strings.remove`, and the "+N" chip reads "N more" (`strings.more`). (src/combobox/combobox.ts:52)
+- Accessibility: The global `inputmode`, `enterkeyhint`, `autocapitalize`, `autocorrect`, and `spellcheck` attributes on the host are forwarded to the search input; `spellcheck` defaults to `false`, as a query is not prose. (src/combobox/combobox.ts:54)
+- Keyboard: Typing filters the options and opens the popup with the first match active. Down and Up open the popup (on the selected or first option, or the last); in the popup they move the active option, and Enter chooses it (single: closes; multiple: toggles and stays open). Alt+Down opens without moving, Alt+Up closes. Escape closes the popup, or when it is closed clears the text and the value. With `multiple`, Backspace in an empty input removes the last value, and Left at the start of the input moves to the chips: Left and Right move between them, Backspace and Delete remove one, Escape returns to the input. (src/combobox/combobox.ts:53)
+
+## Examples
+
+- `example:odd-combobox/children` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/default` in src/combobox/combobox.examples.ts (package source), preview roles role:combobox
+- `example:odd-combobox/disabled` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/grouped` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/inForm` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/loading` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/multiple` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/readonly` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/selectAll` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/serverFiltered` in src/combobox/combobox.examples.ts (package source)
+- `example:odd-combobox/views` in src/combobox/combobox.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-combobox/optionsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-combobox/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-command-palette.md

@@ -0,0 +1,106 @@
+# `<odd-command-palette>` (OddkinCommandPalette)
+
+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 command palette: a modal dialog with a search input and the matching commands below it
+(APG combobox with a listbox popup that is always shown). Typing filters the commands by label
+and makes the first match active; Enter or a click runs it (`odd-action`) and closes the palette;
+Escape or a press on the backdrop closes it, and focus returns to where it was.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/command-palette';`
+- Class: `import { OddkinCommandPalette } from '@oddkin/components/command-palette';`
+- Dependency (icon): `<odd-icon>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the dialog. Required. |
+| `placeholder` | `placeholder` | string | '' | Text shown in the empty search input. |
+| `items` | none: assign as a property | readonly CommandRecord[] \| undefined | undefined | The commands: `{ id, label, description?, icon?, shortcut?, group?, disabled? }`. |
+| `open` | `open` (reflects) | boolean | false | Whether it is open. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a busy row and marks the results busy. |
+| `noFilter` | `no-filter` (reflects) | boolean | false | The element does not filter: listen to `odd-query-change` and replace `items` with the matches. |
+| `strings` | none: assign as a property | Partial<{ search: string; empty: string; loading: string; navigate: string; choose: string; close: string; }> \| undefined | undefined | Localized string overrides. |
+| `query` | none (read-only) | string |  | The text in the search input, as the user typed it (read-only). |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Opens it with the search input focused. |
+| `close()` | Closes it; focus returns to where it was when it opened. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-action` | CustomEvent<NavigationActionDetail> | user (authored) | A command was chosen: `detail.id` is its `id` and `detail.action` is `select`. Cancel it to keep the palette open. |
+| `odd-query-change` | CustomEvent<QueryChangeDetail> | user (authored) | The user typed: `detail.query` is the text in the input. With `no-filter`, replace the options or items with the matches. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `empty` | Shown when no command matches and nothing is loading (default `strings.empty`). |
+| `status` | Status content such as an error and a retry button. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `dialog` | The `<dialog>` surface. |
+| `empty` | The wrapper of the empty slot. |
+| `footer` | The keyboard hints under the results. |
+| `group` | Each group's heading. |
+| `input` | The search input (`role="combobox"`). |
+| `item` | Each command row. |
+| `listbox` | The `role="listbox"` of commands. |
+| `loading` | The busy row while `loading`. |
+| `search` | The search field around the input. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-command-palette-inline-size` | Its width, within the viewport (default 40rem). |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Finding and running any command or destination by name, from anywhere in an app (typically opened with Ctrl+K or Cmd+K). (src/command-palette/command-palette.ts:54)
+- Not for: A few actions behind a button (use odd-menu); choosing a value in a form (use odd-combobox); site search results (use a page). (src/command-palette/command-palette.ts:55)
+- Accessibility: A modal `dialog` named by `label`. Focus starts in the search input, a `combobox` named by `strings.search` that controls the `listbox` of commands and names the active one with `aria-activedescendant` (the active row also has `aria-selected`). Groups are named by their heading. Everything outside is inert while it is open, and closing returns focus to the element that had it. (src/command-palette/command-palette.ts:50)
+- Accessibility: The global `inputmode`, `enterkeyhint`, `autocapitalize`, `autocorrect`, and `spellcheck` attributes on the host are forwarded to the search input; `spellcheck` defaults to `false`, as a query is not prose. (src/command-palette/command-palette.ts:52)
+- Keyboard: Typing filters the commands; Up and Down move the active command (wrapping); Enter runs it. Escape closes the palette. (src/command-palette/command-palette.ts:51)
+
+## Examples
+
+- `example:odd-command-palette/default` in src/command-palette/command-palette.examples.ts (package source), preview roles role:commandPalette
+- `example:odd-command-palette/loading` in src/command-palette/command-palette.examples.ts (package source)
+- `example:odd-command-palette/open` in src/command-palette/command-palette.examples.ts (package source)
+- `example:odd-command-palette/serverSearch` in src/command-palette/command-palette.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-command-palette/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-command-palette/open`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-command-palette-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-container.md

@@ -0,0 +1,75 @@
+# `<odd-container>` (OddkinContainer)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Layout. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A content measure and an inline-size container: container queries and layout recipe conditions
+inside it resolve against its width, not the viewport's. `measure="constrained"` (the default)
+centres it with the theme's `layout.measure` as its maximum inline size; `fluid` fills the space.
+Insets are the page's: put an `.odd-box` inside or around it.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/container';`
+- Class: `import { OddkinContainer } from '@oddkin/components/container';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `measure` | `measure` (reflects) | "constrained" \| "fluid" | 'constrained' | Constrained: centred, at most the measure wide. Fluid: the full width. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The content. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The content wrapper. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-container-measure` | The maximum inline size when constrained (default the theme's `layout.measure`). |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A readable column of page content; a region whose children respond to its width with container queries. (src/container/container.ts:14)
+- Not for: Spacing alone (use `.odd-box`); a scrolling area (use `odd-scroll-region`). (src/container/container.ts:15)
+- Accessibility: Adds no role or landmark: wrap it in `main`, `section`, or another landmark as the page needs. (src/container/container.ts:12)
+
+## Examples
+
+- `example:odd-container/default` in src/container/container.examples.ts (package source), preview roles role:container
+- `example:odd-container/fluid` in src/container/container.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-container/measureWide` produces `usage.attribute.value`; correct: `example:odd-container/fluid`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-container-measure`
+
+## 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-copy-button.md

@@ -0,0 +1,87 @@
+# `<odd-copy-button>` (OddkinCopyButton)
+
+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 button that copies text to the clipboard: `value`, or the form value or text of the element
+named by `from`. It says the outcome in words, "Copied to clipboard." for two seconds or "Could
+not copy. Select the text." (announced as well), and when the browser refuses (no permission, an
+insecure page, no Clipboard API) it selects the text so the user can copy it by hand.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/copy-button';`
+- Class: `import { OddkinCopyButton } from '@oddkin/components/copy-button';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | string | '' | The text to copy; wins over `from`. |
+| `from` | `from` | string | '' | The id of the element whose text is copied (an input or textarea: its value), in the same document or shadow root. |
+| `label` | `label` | string | '' | The button text; default `strings.copy` ("Copy"). |
+| `disabled` | `disabled` (reflects) | boolean | false | Disables the button. |
+| `strings` | none: assign as a property | Partial<{ copy: string; copied: string; failed: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `copy()` | Copies the text; resolves `true` when the clipboard took it. Ignored while disabled or empty. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-copy` | CustomEvent<CopyDetail> | user (authored) | The text was written to the clipboard; `detail.value` is the text. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The row of the button and the status. |
+| `button` | The native button (the small secondary `odd-button` look). |
+| `fallback` | The read-only field holding `value` after a failure, selected for a manual copy. |
+| `status` | The outcome in words. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Copying an identifier, a code snippet, a link, or a key that people paste elsewhere. (src/copy-button/copy-button.ts:43)
+- Not for: Copying rich content or files; a share action (use the page's share flow). (src/copy-button/copy-button.ts:44)
+- Accessibility: A native button named by its text ("Copy"); the outcome is announced politely (assertively when it fails) and also shown. After a failure without `from`, focus moves to the selected fallback field, so Ctrl+C or Cmd+C copies. (src/copy-button/copy-button.ts:40)
+- Keyboard: Tab reaches the button; Enter or Space copies. (src/copy-button/copy-button.ts:41)
+
+## Examples
+
+- `example:odd-copy-button/default` in src/copy-button/copy-button.examples.ts (package source), preview roles role:copyButton
+- `example:odd-copy-button/disabled` in src/copy-button/copy-button.examples.ts (package source)
+- `example:odd-copy-button/labelled` in src/copy-button/copy-button.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-copy-button/disabledFalse` produces `usage.boolean.false`; correct: `example:odd-copy-button/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`