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

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

@@ -0,0 +1,79 @@
+# `<odd-icon>` (OddkinIcon)
+
+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.
+
+An icon drawn in the current text colour: an SVG file by URL (`src`), or an inline `<svg>`
+placed inside. Oddkin ships no icon set; bring your own, and pay only for the icons you use.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/icon';`
+- Class: `import { OddkinIcon } from '@oddkin/components/icon';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `src` | `src` | string | '' | URL of an SVG, drawn in the current text colour; empty uses the slotted `<svg>`. |
+| `label` | `label` | string | '' | Accessible name; empty marks the icon decorative. |
+| `size` | `size` (reflects) | "sm" \| "md" \| "lg" | 'md' | Edge length: 16, 20, or 24 px (the icon size tokens). |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | An inline `<svg>`, used when `src` is empty. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The icon box. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-icon-size` | Edge length; overrides `size`. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Pictograms beside text, or alone with `label`. (src/icon/icon.ts:14)
+- Not for: The only name of a control (give the control its own label); decoration that belongs in CSS. (src/icon/icon.ts:15)
+- Accessibility: With `label` the icon is an image named by it; without, it is hidden from assistive technology. Beside text that already says the same, leave `label` empty. (src/icon/icon.ts:11)
+- Limitations: `src` is drawn as a CSS mask, so the page's Content-Security-Policy must allow the URL in `img-src`, and the file's own colours are ignored (one colour, `currentColor`). (src/icon/icon.ts:12)
+
+## Examples
+
+- `example:odd-icon/default` in src/icon/icon.examples.ts (package source), preview roles role:icon
+- `example:odd-icon/fromUrl` in src/icon/icon.examples.ts (package source)
+- `example:odd-icon/labelled` in src/icon/icon.examples.ts (package source)
+- `example:odd-icon/large` in src/icon/icon.examples.ts (package source)
+- `example:odd-icon/small` in src/icon/icon.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-icon/altAttribute` produces `usage.attribute.unknown`; correct: `example:odd-icon/labelled`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-icon-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-input.md

@@ -0,0 +1,141 @@
+# `<odd-input>` (OddkinInput)
+
+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 single-line text field that participates in forms like a native input.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/input';`
+- Class: `import { OddkinInput } from '@oddkin/components/input';`
+
+## 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. |
+| `type` | `type` (reflects) | "number" \| "search" \| "time" \| "text" \| "url" \| "email" \| "password" \| "tel" \| "date" \| "datetime-local" \| "month" \| "week" | 'text' | Native input type. |
+| `min` | `min` | string \| undefined | undefined | Lowest value (number and date types), as on native inputs. |
+| `max` | `max` | string \| undefined | undefined | Highest value (number and date types), as on native inputs. |
+| `step` | `step` | string \| undefined | undefined | Step between values (number and date types); `any` allows every value. |
+| `pattern` | `pattern` | string \| undefined | undefined | A regular expression the whole value must match (text types). |
+| `strings` | none: assign as a property | Partial<{ clear: string; decrement: string; increment: string; badInput: string; }> \| undefined | undefined | Localized string overrides. |
+| `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`. |
+| `valueAsNumber` | none: assign as a property | number |  | The value as a number (a date or time as milliseconds), as on native inputs; `NaN` when empty. |
+
+## 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). |
+| `stepUp()` | Steps the value up `n` steps (default 1), as on native inputs; dispatches no events. |
+| `stepDown()` | Steps the value down `n` steps (default 1), as on native inputs; dispatches no events. |
+
+## 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 |
+| --- | --- |
+| `clear` | The button that clears a search value (`type="search"`), shown while there is a value to clear. |
+| `control` | The native `<input>`. |
+| `decrement` | The button that steps a number down, disabled where a step down cannot move the value (`type="number"`). |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, control, and error. |
+| `icon` | The search glyph at the start (`type="search"`). |
+| `increment` | The button that steps a number up, disabled where a step up cannot move the value (`type="number"`). |
+| `label` | The visible label. |
+| `stepper` | The segment at the end of a number field holding its two buttons (`type="number"`). |
+
+## 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. |
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: Short values in forms: names, email addresses, search terms, numbers, dates, and times. (src/input/input.ts:41)
+- Not for: Multi-line text (use odd-textarea); choices from a fixed list (use odd-select or odd-radio-group). (src/input/input.ts:42)
+- Accessibility: `label` names the native input inside the shadow root; a `<label for>` outside it cannot. Description and error 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 (any `invalid` event, including `checkValidity()`, unlike native `:user-invalid`); reset clears it. (src/input/input.ts:37)
+- Accessibility: A number field is the WAI-ARIA spinbutton: a text input with `role="spinbutton"`, the decimal input mode (unless the host sets `inputmode`), `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` (and `aria-valuetext` when the text is not the plain number). Its decrement and increment buttons are named by `strings` and are not Tab stops; pressing one keeps focus in the field. (src/input/input.ts:38)
+- Accessibility: The global `inputmode`, `enterkeyhint`, `autocapitalize`, `autocorrect`, and `spellcheck` attributes on the host are forwarded to the inner input (`enterkeyhint` defaults to `search` in a search field). (src/input/input.ts:43)
+- Keyboard: Native text-input behavior; arrow keys step a date. In a number field, Up and Down step by `step`, Page Up and Page Down by ten steps, and Home and End go to the lowest and highest values on the grid when `min` and `max` are set; each step that moves the value dispatches `input` and `change`, as a native number field's arrow keys do. In a search field, Escape clears the value (and then reaches outer handlers, such as a dialog, when empty). (src/input/input.ts:39)
+- Limitations: A number field reads HTML number syntax (a full stop before decimals, an optional exponent), not the page language's format; other text is bad input, which the value and the submission leave out, as in a native number field. Holding a stepper button steps once. (src/input/input.ts:44)
+- Limitations: Validation bubbles anchor to the inner input. `formStateRestoreCallback` restores the value; autofill depends on the inner input's `autocomplete`. (src/input/input.ts:45)
+- Limitations: Enter in the field does not submit the form (no implicit submission): the native input inside the shadow root has no form owner. Give the form a submit button. (src/input/input.ts:46)
+
+## Examples
+
+- `example:odd-input/constraints` in src/input/input.examples.ts (package source)
+- `example:odd-input/date` in src/input/input.examples.ts (package source)
+- `example:odd-input/default` in src/input/input.examples.ts (package source), preview roles role:textInput
+- `example:odd-input/description` in src/input/input.examples.ts (package source)
+- `example:odd-input/disabled` in src/input/input.examples.ts (package source)
+- `example:odd-input/inForm` in src/input/input.examples.ts (package source)
+- `example:odd-input/invalid` in src/input/input.examples.ts (package source)
+- `example:odd-input/number` in src/input/input.examples.ts (package source)
+- `example:odd-input/password` in src/input/input.examples.ts (package source)
+- `example:odd-input/readonly` in src/input/input.examples.ts (package source)
+- `example:odd-input/required` in src/input/input.examples.ts (package source)
+- `example:odd-input/search` in src/input/input.examples.ts (package source)
+- `example:odd-input/time` in src/input/input.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-input/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-input/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-field-background`, `--odd-field-border-color`, `--odd-field-height`, `--odd-field-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-listbox.md

@@ -0,0 +1,123 @@
+# `<odd-listbox>` (OddkinListbox)
+
+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.
+
+Persistent choices in a form (APG listbox): the listbox keeps focus and the active option is its
+`aria-activedescendant`. Options come from `<option>` and `<optgroup>` children, written as for a
+native select (`selected` marks the default), or from `options`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/listbox';`
+- Class: `import { OddkinListbox } from '@oddkin/components/listbox';`
+
+## 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. |
+| `strings` | none: assign as a property | Partial<{ loading: string; empty: string; }> \| undefined | undefined | Localized string overrides. |
+| `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). |
+
+## 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). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `empty` | Shown when there are no options and nothing is loading (default `strings.empty`). |
+| `status` | Status content such as an error and a retry button. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface holding the options and the states. |
+| `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, surface, and error. |
+| `group` | Each group's heading. |
+| `label` | The visible label. |
+| `listbox` | The `role="listbox"` element, which takes focus. |
+| `loading` | The busy row while `loading`. |
+| `option` | Each option row. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-listbox-max-height` | Height beyond which the options scroll (default: none). |
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: A visible list of a few to a few dozen choices, one or several, in a form. (src/listbox/listbox.ts:44)
+- Not for: A compact choice (use odd-select); a long list to search (use odd-combobox); actions (use odd-menu). (src/listbox/listbox.ts:45)
+- Accessibility: A `listbox` named by `label`, with `aria-multiselectable`, `aria-required`, `aria-invalid`, and `aria-busy` while loading; options carry `aria-selected`, and groups are named by their heading. The selection is marked by a check and a surface, not colour alone. (src/listbox/listbox.ts:41)
+- Keyboard: Tab focuses the listbox. Up and Down move the active option; Home and End go to the first and last. Typing moves to the next option whose label starts with the typed characters. Single: the selection follows the active option. Multiple: Space toggles the active option, Shift with Up or Down extends the selection, Ctrl+A selects every option. (src/listbox/listbox.ts:42)
+
+## Examples
+
+- `example:odd-listbox/default` in src/listbox/listbox.examples.ts (package source), preview roles role:listbox
+- `example:odd-listbox/disabledOption` in src/listbox/listbox.examples.ts (package source)
+- `example:odd-listbox/empty` in src/listbox/listbox.examples.ts (package source)
+- `example:odd-listbox/fromData` in src/listbox/listbox.examples.ts (package source)
+- `example:odd-listbox/groups` in src/listbox/listbox.examples.ts (package source)
+- `example:odd-listbox/inForm` in src/listbox/listbox.examples.ts (package source)
+- `example:odd-listbox/loading` in src/listbox/listbox.examples.ts (package source)
+- `example:odd-listbox/multiple` in src/listbox/listbox.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-listbox/optionsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-listbox/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-listbox-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-menu.md

@@ -0,0 +1,96 @@
+# `<odd-menu>` (OddkinMenu)
+
+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 menu button (APG): a button that opens a menu of actions, with groups, separators, and
+submenus. Items come from `<option value>` (the value is the item's `id`), `<optgroup label>`,
+and `<hr>` children, or from `items`. With `context`, it is also the context menu of another
+element.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/menu';`
+- Class: `import { OddkinMenu } from '@oddkin/components/menu';`
+- Dependency (icon): `<odd-icon>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the trigger when it shows only a glyph or icon. |
+| `items` | none: assign as a property | readonly MenuItemRecord[] \| undefined | undefined | The entries; when set, `<option>`, `<optgroup>`, and `<hr>` children are ignored. |
+| `appearance` | `appearance` (reflects) | "primary" \| "secondary" \| "ghost" | 'secondary' | The trigger's emphasis, as on odd-button. |
+| `size` | `size` (reflects) | "sm" \| "md" \| "lg" | 'md' | The trigger's size, as on odd-button. |
+| `disabled` | `disabled` (reflects) | boolean | false | Disables the trigger. |
+| `context` | `context` | string | '' | The ID of an element, in the same document or shadow root, whose context menu it also is: a right-click or long press on it opens the menu at the pointer, and Shift+F10 or the Menu key while focus is in it opens the menu beside the focused element. The browser keeps its own menu while the trigger is disabled. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Opens the menu below its trigger and focuses its first item. |
+| `close()` | Closes the menu and every submenu; focus inside returns to the trigger. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-action` | CustomEvent<NavigationActionDetail> | user (authored) | An item was chosen: `detail.id` is its `id` and `detail.action` is `select`. Cancel it to keep the menu open. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The trigger's content. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `group` | Each group's heading. |
+| `item` | Each menu item. |
+| `menu` | Every menu surface: the menu and its submenus. |
+| `separator` | Each separator. |
+| `submenu` | Each submenu surface. |
+| `trigger` | The button that opens the menu. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A short list of actions behind one button: row actions, "more" actions, create menus. (src/menu/menu.ts:59)
+- Not for: Choosing a value in a form (use odd-select or odd-listbox); navigation between pages (use links or odd-side-nav); a searchable list of commands (use odd-command-palette). (src/menu/menu.ts:60)
+- Accessibility: The trigger has `aria-haspopup="menu"` and `aria-expanded`, and names the menu; `label` names a trigger that shows only a glyph. Items are `menuitem`s (disabled ones stay focusable, as APG recommends), groups are named by their heading, and an item with a submenu has `aria-haspopup` and `aria-expanded`. The danger tone is colour only: let the label say what the action does ("Delete project"). A context menu is hidden from people who cannot right-click or do not know Shift+F10: keep the trigger visible as the way to the same actions. (src/menu/menu.ts:56)
+- Keyboard: On the trigger: Enter, Space, and Down open the menu on its first item, Up on its last. With `context`, Shift+F10 or the Menu key while focus is in that element opens the menu on its first item. In the menu: Up and Down move (wrapping), Home and End go to the first and last item, typing moves to the next item starting with the typed characters, Enter and Space choose. Right opens a submenu on its first item; Left and Escape close one level and return focus to its item; Escape on the menu returns focus to the trigger, or to where it was when a context menu opened; Tab and Shift+Tab close every level as focus leaves. (src/menu/menu.ts:57)
+
+## Examples
+
+- `example:odd-menu/contextMenu` in src/menu/menu.examples.ts (package source), preview roles role:menu
+- `example:odd-menu/default` in src/menu/menu.examples.ts (package source), preview roles role:menu
+- `example:odd-menu/disabled` in src/menu/menu.examples.ts (package source)
+- `example:odd-menu/fromData` in src/menu/menu.examples.ts (package source)
+- `example:odd-menu/glyphOnly` in src/menu/menu.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-menu/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-menu/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-one-time-code.md

@@ -0,0 +1,122 @@
+# `<odd-one-time-code>` (OddkinOneTimeCode)
+
+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 one-time code (a verification code sent by text message or email) entered into `maxlength`
+cells (default six). It is one native input with `autocomplete="one-time-code"` and a numeric
+keyboard (the global `inputmode` attribute, `numeric` unless the host sets it) behind the drawn
+cells, so the platform's autofill, paste, and form value
+work as on any field: digits only, typed or pasted, the caret always after the last digit.
+`status` reports the verification the page runs: `pending` keeps the code read-only with a
+busy line, `complete` confirms it; a failure is `error`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/one-time-code';`
+- Class: `import { OddkinOneTimeCode } from '@oddkin/components/one-time-code';`
+
+## 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. |
+| `status` | `status` (reflects) | "idle" \| "pending" \| "complete" | 'idle' | The verification the page runs: `pending` makes the code read-only and shows `strings.pending`; `complete` shows `strings.complete`. |
+| `strings` | none: assign as a property | Partial<{ hint: string; pending: string; complete: string; }> \| undefined | undefined | Localized string overrides: `hint` (under the cells while idle), `pending`, `complete`. |
+| `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 |
+| --- | --- |
+| `cell` | One digit's cell. |
+| `control` | The native input over the cells. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, cells, status, and error. |
+| `label` | The visible label. |
+| `status` | The line under the cells: `strings.hint`, or the `pending` or `complete` text with its glyph. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: A short code the user copies from a message to confirm a sign-in, an address, or a payment. (src/one-time-code/one-time-code.ts:37)
+- Not for: Passwords and PINs the user chooses (use odd-input type="password"); long reference numbers (use odd-input). (src/one-time-code/one-time-code.ts:38)
+- Accessibility: One text input named by `label`, described by the description, the status line, and the error; the cells are drawn and hidden from assistive technology, so the code is read as one value. The status line is a `role="status"` region, so `pending` and `complete` are announced. (src/one-time-code/one-time-code.ts:34)
+- Keyboard: Typing enters digits and moves to the next cell; Backspace removes the last digit; paste enters the whole code. The arrow, Home, and End keys keep the caret after the last digit, and a click puts it there. Tab selects the code, as in any field, so typing then replaces it. (src/one-time-code/one-time-code.ts:35)
+- Limitations: Digits only. A digit in the middle cannot be selected alone: Backspace back to it. (src/one-time-code/one-time-code.ts:39)
+
+## Examples
+
+- `example:odd-one-time-code/complete` in src/one-time-code/one-time-code.examples.ts (package source)
+- `example:odd-one-time-code/default` in src/one-time-code/one-time-code.examples.ts (package source)
+- `example:odd-one-time-code/disabled` in src/one-time-code/one-time-code.examples.ts (package source)
+- `example:odd-one-time-code/entering` in src/one-time-code/one-time-code.examples.ts (package source), preview roles role:oneTimeCode
+- `example:odd-one-time-code/fourDigits` in src/one-time-code/one-time-code.examples.ts (package source)
+- `example:odd-one-time-code/inForm` in src/one-time-code/one-time-code.examples.ts (package source)
+- `example:odd-one-time-code/invalid` in src/one-time-code/one-time-code.examples.ts (package source)
+- `example:odd-one-time-code/pending` in src/one-time-code/one-time-code.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-one-time-code/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-one-time-code/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-pagination.md

@@ -0,0 +1,87 @@
+# `<odd-pagination>` (OddkinPagination)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Navigation. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Page navigation: the position as text, previous and next, and the first, last, and nearby pages
+with ellipses between. With `href`, pages are links; without it, buttons that report
+`odd-action` so the application can load the page.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/pagination';`
+- Class: `import { OddkinPagination } from '@oddkin/components/pagination';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the navigation; default `strings.label`. |
+| `current` | `current` | string | '1' | The current page number. |
+| `pageCount` | `page-count` | number | 1 | The number of pages (at least 1). |
+| `href` | `href` | string | '' | A link template with `{page}`, as in "?page={page}"; when set, pages are links. |
+| `strings` | none: assign as a property | Partial<{ label: string; previous: string; next: string; page: string; status: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-action` | CustomEvent<NavigationActionDetail> | user (authored) | A page button was activated (without `href`): `detail.id` is the page number and `detail.action` is "page". The application sets `current`. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The `<nav>` surface. |
+| `ellipsis` | The mark between distant pages. |
+| `list` | The list of controls. |
+| `next` | The next-page link or button. |
+| `page` | Each page link or button; the current one has `aria-current="page"`. |
+| `previous` | The previous-page link or button. |
+| `status` | The position text ("Page 3 of 12"). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-pagination-radius` | Corner radius of the surface. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Moving through a long list or result set one page at a time. (src/pagination/pagination.ts:46)
+- Not for: Steps of a process; switching views (use odd-tabs); short lists (show everything). (src/pagination/pagination.ts:47)
+- Accessibility: A `<nav>` landmark named by `label` (default `strings.label`). Pages are named "Page 3" (`strings.page`) and the current one has `aria-current="page"`. At the ends, previous or next is disabled (a disabled button, or a link without `href` with `aria-disabled`). Ellipses are hidden from assistive technology. (src/pagination/pagination.ts:43)
+- Keyboard: Tab moves through previous, the pages, and next; Enter (and Space on buttons) activates. (src/pagination/pagination.ts:44)
+
+## Examples
+
+- `example:odd-pagination/default` in src/pagination/pagination.examples.ts (package source), preview roles role:pagination
+- `example:odd-pagination/fewPages` in src/pagination/pagination.examples.ts (package source)
+- `example:odd-pagination/lastPage` in src/pagination/pagination.examples.ts (package source)
+- `example:odd-pagination/links` in src/pagination/pagination.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-pagination/currentPageAttribute` produces `usage.attribute.unknown`; correct: `example:odd-pagination/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-pagination-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`