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

package/agent/references/components/odd-one-time-code.md

@@ -0,0 +1,126 @@
+# `<odd-one-time-code>` (OddkinOneTimeCode)
+
+Package `@oddkin/components` 1.0.0-beta.0 · 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`
+
+## Verified
+
+- 76 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,91 @@
+# `<odd-pagination>` (OddkinPagination)
+
+Package `@oddkin/components` 1.0.0-beta.0 · 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`
+
+## Verified
+
+- 31 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,149 @@
+# `<odd-picker>` (OddkinPicker)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Forms. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A field that opens a list or a hierarchy to choose from (APG select-only combobox): a popup
+listbox of options, or, with `items`, a popup tree whose rows expand and collapse without
+selecting. Single: activating a row chooses it and closes. Multiple: rows toggle at once, the
+chosen values show in the field as `view` says (chips with "+N" by default, as on odd-combobox), and Done closes. Options
+come from `<option>` and `<optgroup>` children, written as for a native select, or from
+`options`; a hierarchy comes from `items`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/picker';`
+- Class: `import { OddkinPicker } from '@oddkin/components/picker';`
+- Dependency (avatar): `<odd-avatar>`
+- Dependency (icon): `<odd-icon>`
+
+## 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. |
+| `placeholder` | `placeholder` | string | '' | Text shown while nothing is chosen. |
+| `items` | none: assign as a property | readonly TreeItemRecord[] \| undefined | undefined | A hierarchy to choose from: when set, the popup is a tree, and `<option>` children and `options` are not shown. |
+| `expanded` | none: assign as a property | readonly string[] \| undefined | undefined | Ids of expanded items with `items`, owned by the caller. Omit it to let the element track expansion. |
+| `strings` | none: assign as a property | Partial<{ loading: string; empty: string; hint: string; close: string; done: string; path: string; clear: string; remove: string; selected: string; more: string; count: string; others: string; othersOne: string; ... 7 more ...; viewMore: string; }> \| undefined | undefined | Localized string overrides; `remove` takes `{label}`, `more` and `count` take `{count}`, `path` takes `{parent}` and `{label}`. |
+| `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). |
+| `odd-toggle` | CustomEvent<NavigationToggleDetail> | user (authored) | An item is about to expand or collapse; cancelable. Load the children of a lazy item here. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `empty` | Shown when there are no options or items 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. |
+| `clear-all` | The footer's Clear button with `multiple`. |
+| `close` | The footer's Close button, or Done with `multiple`. |
+| `control` | The field box holding the trigger 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. |
+| `footer` | The popup's footer: the summary and its actions. |
+| `group` | Each group's heading. |
+| `item` | Each tree row (`role="treeitem"`). |
+| `label` | The visible label. |
+| `listbox` | The `role="listbox"` element (without `items`). |
+| `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 list or tree, the states, and the footer. |
+| `summary` | "Choose one item" (`strings.hint`), or with `multiple` the count (`strings.count`). |
+| `tree` | The `role="tree"` element (with `items`). |
+| `trigger` | The `role="combobox"` element showing the chosen value or the placeholder; it keeps focus. |
+| `value` | The chosen item's text in the trigger (single). |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: Choosing from a fixed list or a hierarchy in a form: map layers, folders, categories, one or several. (src/picker/picker.ts:61)
+- Not for: A short list of plain options (use odd-select); a long list to search (use odd-combobox); browsing a hierarchy without a form value (use odd-tree). (src/picker/picker.ts:62)
+- Accessibility: The trigger has `role="combobox"`, `aria-haspopup="tree"` with `items`, `aria-expanded`, and `aria-controls`; it keeps focus and names the active row with `aria-activedescendant`; `label` names it. Rows carry `aria-selected`; the listbox or tree has `aria-multiselectable` with `multiple`; tree rows carry `aria-level`, `aria-setsize`, `aria-posinset`, and `aria-expanded`. The active row's ring is drawn apart from the selection, which is a surface and check (options) or a bar and weight (tree rows), not colour alone. Chips are a list named by `strings.selected`, each remove button named by `strings.remove`. (src/picker/picker.ts:58)
+- Keyboard: Tab reaches the trigger, then the footer while the popup is open. Down, Up, Enter, Space, and Alt+Down open the popup on the chosen (or first) row; Home and End open it on the first and last; typing opens it on the next row whose label starts with the typed characters. In the popup: Up, Down, Home, and End move the active row; Enter or Space chooses it (single: closes; multiple: toggles and stays open); Escape and Alt+Up close without changing the value, and focus stays on the trigger. In a tree, 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), and `*` expands every sibling. On the closed trigger, Backspace removes the last value; with `multiple`, Left moves to the chips: Left and Right move between them, Backspace and Delete remove one, Escape returns. (src/picker/picker.ts:59)
+
+## Examples
+
+- `example:odd-picker/default` in src/picker/picker.examples.ts (package source), preview roles role:picker
+- `example:odd-picker/disabled` in src/picker/picker.examples.ts (package source)
+- `example:odd-picker/empty` in src/picker/picker.examples.ts (package source)
+- `example:odd-picker/inForm` in src/picker/picker.examples.ts (package source)
+- `example:odd-picker/list` in src/picker/picker.examples.ts (package source)
+- `example:odd-picker/listMultiple` in src/picker/picker.examples.ts (package source)
+- `example:odd-picker/loading` in src/picker/picker.examples.ts (package source)
+- `example:odd-picker/multiple` in src/picker/picker.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-picker/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-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`
+
+## Verified
+
+- 101 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,100 @@
+# `<odd-popover>` (OddkinPopover)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Overlays. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A non-modal surface anchored to the control that opens it. The host is the popover
+(`popover="auto"`), so `<button popovertarget="id">` opens and closes it with no script; it also
+closes on Escape, on a press outside, and with its close button, and focus returns to the
+trigger. With `interest`, it is a hover card: it also opens while the pointer rests on its anchor
+or the anchor has focus.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/popover';`
+- Class: `import { OddkinPopover } from '@oddkin/components/popover';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the popover. |
+| `anchor` | `anchor` | string | '' | The ID of the element it is placed against, in the same document or shadow root. Default: the button whose `popovertarget` names it; with neither, it is centred. |
+| `side` | `side` | "inline-end" \| "inline-start" \| "block-end" \| "block-start" | 'block-end' | The side of the anchor it opens on, in the anchor's writing direction; it flips to the other side when there is more room there. |
+| `align` | `align` | "center" \| "start" \| "end" | 'start' | How it lines up with the anchor along that side. |
+| `noClose` | `no-close` | boolean | false | Hides the close button. Keep it wherever touch users need it: Safari on iOS before 18.3 does not close a popover on a tap outside. |
+| `open` | `open` (reflects) | boolean | false | Whether it is open. |
+| `interest` | `interest` | boolean | false | A hover card (HTML interest invokers): it also opens once the pointer has rested on its anchor, or the anchor has had focus, for half a second, and closes a quarter of a second after both have left the anchor and the popover. A touch keeps the anchor's own action. |
+| `strings` | none: assign as a property | Partial<{ close: string; }> \| undefined | undefined | Localized string overrides. |
+| `anchorElement` | none: assign as a property | Element \| null |  | The element it is placed against, when it is not found by `anchor` (another tree, or no ID). |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Opens it. |
+| `close()` | Closes it; focus inside returns to where it was before it opened. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The content. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The content and the close button, inside the surface. |
+| `close` | The close button. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-popover-max-inline-size` | The widest it grows before its content wraps. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Extra controls or details next to the control that shows them: a share form, settings, a definition. (src/popover/popover.ts:30)
+- Not for: Content that must be answered before going on (use odd-dialog); a list of actions (use odd-menu); a hint on hover or focus (use odd-tooltip). (src/popover/popover.ts:31)
+- Accessibility: A non-modal `dialog` named by `label`. Opening it leaves focus where it is; Tab moves from the trigger into it, as for any popover. When it closes with focus inside, focus returns to the element that had it, usually the trigger. The close button is named by `strings.close`. With `interest`, keep it supplementary: what it shows must also be at the anchor's destination, since touch users do not hover; place it right after the anchor so Tab moves from the anchor into it, and add a `popovertarget` button where touch users need the card itself. (src/popover/popover.ts:27)
+- Keyboard: Escape closes it. Tab from the trigger moves into it. With `interest`, focus on the anchor opens it after the delay, and it stays while focus is on the anchor or in it. (src/popover/popover.ts:28)
+
+## Examples
+
+- `example:odd-popover/default` in src/popover/popover.examples.ts (package source), preview roles role:popover
+- `example:odd-popover/hoverCard` in src/popover/popover.examples.ts (package source), preview roles role:popover
+- `example:odd-popover/inlineEnd` in src/popover/popover.examples.ts (package source)
+- `example:odd-popover/scripted` in src/popover/popover.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-popover/openFalse` produces `usage.boolean.false`; correct: `example:odd-popover/default`
+- `example:odd-popover/physicalSide` produces `usage.attribute.value`; correct: `example:odd-popover/inlineEnd`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-popover-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`
+
+## Verified
+
+- 41 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,90 @@
+# `<odd-progress>` (OddkinProgress)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Feedback. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Progress of a task. With a `value` it shows how much is done; without, it shows that work is
+under way and never a percentage.
+
+Drawn as an ARIA progress bar rather than a native `<progress>`, whose bar and indicator can
+only be styled through engine-prefixed pseudo-elements.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/progress';`
+- Class: `import { OddkinProgress } from '@oddkin/components/progress';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | number \| undefined | undefined | Work done, from 0 to `max`; absent: indeterminate. |
+| `max` | `max` | number | 1 | Value at completion, as on a native progress (1). |
+| `label` | `label` | string | '' | Visible label; names the progress bar. |
+| `description` | `description` | string | '' | Help text below the bar. |
+| `renderValue` | none: assign as a property | ProgressValueRenderer \| undefined |  | Formats the value text (default: a percentage in the element language). |
+| `strings` | none: assign as a property | Partial<{ label: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+None.
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | Label, bar, and description. |
+| `description` | Help text below the bar. |
+| `indicator` | The filled part of the bar. |
+| `label` | The visible label. |
+| `track` | The bar (`role="progressbar"`). |
+| `value-text` | The formatted value (determinate only). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-progress-height` | Bar thickness. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Uploads, imports, and other work with a measurable amount. (src/progress/progress.ts:25)
+- Not for: Work of unknown length in a small space (use odd-spinner); a measurement within a known range such as disk usage. (src/progress/progress.ts:26)
+- Accessibility: A progress bar named by `label` (default "Progress") and described by `description`; the value text is its `aria-valuetext`. Changes are not announced; announce completion separately if it matters. (src/progress/progress.ts:23)
+
+## Examples
+
+- `example:odd-progress/counted` in src/progress/progress.examples.ts (package source)
+- `example:odd-progress/default` in src/progress/progress.examples.ts (package source), preview roles role:progress
+- `example:odd-progress/fraction` in src/progress/progress.examples.ts (package source)
+- `example:odd-progress/indeterminate` in src/progress/progress.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-progress/percentAttribute` produces `usage.attribute.unknown`; correct: `example:odd-progress/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-progress-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`
+
+## Verified
+
+- 28 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)