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

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

@@ -0,0 +1,145 @@
+# `<odd-picker>` (OddkinPicker)
+
+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 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`

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

@@ -0,0 +1,96 @@
+# `<odd-popover>` (OddkinPopover)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Overlays. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A 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`

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

@@ -0,0 +1,86 @@
+# `<odd-progress>` (OddkinProgress)
+
+Package `@oddkin/components` 1.0.0-beta.1 · 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`

package/agent/references/components/odd-radio-group.md

@@ -0,0 +1,113 @@
+# `<odd-radio-group>` (OddkinRadioGroup)
+
+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 value from a short set of visible options, each a native radio with its label and
+description. Options come from `<option>` and `<optgroup>` children, written as for a native
+select (`selected` marks the default, `title` is the description), or from `options`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/radio-group';`
+- Class: `import { OddkinRadioGroup } from '@oddkin/components/radio-group';`
+
+## 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 group. |
+| `options` | none: assign as a property | readonly OptionRecord[] \| undefined | undefined | The choices; when set, `<option>` children are ignored. |
+| `value` | `value` | string | '' | Value of the checked option; the `value` attribute sets the default. |
+| `required` | `required` (reflects) | boolean | false | An option must be checked to submit. |
+| `orientation` | `orientation` (reflects) | "vertical" \| "horizontal" | 'vertical' | Stacks the options, or lines them up and wraps them. |
+| `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) | 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 checks an option (native `change` is not composed). |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The options. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | The group: legend, description, options, and error. |
+| `group` | The heading of a group of options (`<optgroup label>`). |
+| `label` | The visible legend. |
+| `option` | One option: its radio and label. |
+| `option-description` | An option's description, referenced by its radio. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: One choice from a few options that should all stay visible, especially with descriptions: a visibility setting, a plan. (src/radio-group/radio-group.ts:24)
+- Not for: Several independent choices (use odd-checkbox-group); a long list (use odd-select or odd-combobox); a compact switch between a few short values (use odd-segmented-control). (src/radio-group/radio-group.ts:25)
+- Accessibility: A `role="radiogroup"` in the shadow root, named by the legend and described by the description and error, holds native radios; each radio is named by its option's label and described by its option's description. `label` names the group; a `<label for>` outside the shadow root cannot. (src/radio-group/radio-group.ts:21)
+- Keyboard: Native radio behavior: Tab enters the group at the checked radio (or the first, when none is checked) and leaves it; arrow keys move to the next or previous option and check it; Space checks the focused option. (src/radio-group/radio-group.ts:22)
+
+## Examples
+
+- `example:odd-radio-group/default` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/disabled` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/disabledOption` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/fromData` in src/radio-group/radio-group.examples.ts (package source), preview roles role:radioGroup
+- `example:odd-radio-group/groups` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/horizontal` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/inForm` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/invalid` in src/radio-group/radio-group.examples.ts (package source)
+- `example:odd-radio-group/required` in src/radio-group/radio-group.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-radio-group/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-radio-group/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-rating.md

@@ -0,0 +1,115 @@
+# `<odd-rating>` (OddkinRating)
+
+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 score from one to `max` stars (default five), with the chosen value beside the stars ("3 of
+5"): the radio-group behavior drawn as stars, each filled up to the chosen one. Without
+`<option>` children or `options`, the stars are named by `strings.star` ("3 stars"); options
+name them instead ("Good"), and their count replaces `max`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/rating';`
+- Class: `import { OddkinRating } from '@oddkin/components/rating';`
+
+## 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 group. |
+| `options` | none: assign as a property | readonly OptionRecord[] \| undefined | undefined | The choices; when set, `<option>` children are ignored. |
+| `value` | `value` | string | '' | Value of the checked option; the `value` attribute sets the default. |
+| `required` | `required` (reflects) | boolean | false | An option must be checked to submit. |
+| `max` | `max` (reflects) | number | 5 | How many stars, when the options are not given. |
+| `readonly` | `readonly` (reflects) | boolean | false | Shows the value without letting the user change it; still submitted and, as a native read-only field, barred from validation. |
+| `strings` | none: assign as a property | Partial<{ star: string; starOne: string; summary: string; empty: string; }> \| undefined | undefined | Localized string overrides: `star` and `starOne` (a star's name, "{count} stars"), `summary` ("{value} of {max}"), `empty` (nothing chosen). |
+| `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) | 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 checks an option (native `change` is not composed). |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The row of stars and the value. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, stars, value, and error. |
+| `label` | The visible label. |
+| `option` | One star. |
+| `value` | The chosen value, or `strings.empty` while nothing is chosen. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: A score the user gives on a short ordered scale: an opinion of an item, a satisfaction level. (src/rating/rating.ts:33)
+- Not for: A number on a long or continuous scale (use odd-slider); choices that are not ordered (use odd-radio-group). (src/rating/rating.ts:34)
+- Accessibility: A `role="radiogroup"` in the shadow root, named by `label` and described by the description and error, holds a native radio per star, named by its option's label ("3 stars"), as the WAI-ARIA rating radio group example. `readonly` adds `aria-readonly` and keeps the stars focusable. (src/rating/rating.ts:30)
+- Keyboard: Native radio behavior: Tab enters at the chosen star (or the first, when none is chosen) and leaves; arrow keys move to the next or previous star and choose it; Space chooses the focused star. While `readonly`, the keys and clicks change nothing. (src/rating/rating.ts:31)
+- Limitations: Whole stars only: no half values. The focus ring and the chosen value move together, as on native radios. (src/rating/rating.ts:35)
+
+## Examples
+
+- `example:odd-rating/default` in src/rating/rating.examples.ts (package source)
+- `example:odd-rating/disabled` in src/rating/rating.examples.ts (package source)
+- `example:odd-rating/inForm` in src/rating/rating.examples.ts (package source)
+- `example:odd-rating/invalid` in src/rating/rating.examples.ts (package source)
+- `example:odd-rating/named` in src/rating/rating.examples.ts (package source)
+- `example:odd-rating/readonly` in src/rating/rating.examples.ts (package source)
+- `example:odd-rating/selected` in src/rating/rating.examples.ts (package source), preview roles role:rating
+- `example:odd-rating/ten` in src/rating/rating.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-rating/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-rating/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-relative-time.md

@@ -0,0 +1,76 @@
+# `<odd-relative-time>` (OddkinRelativeTime)
+
+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 date and time said relative to now ("3 hours ago", "in 2 days", "now") in the page's language,
+as a `<time>` that keeps the exact value; the absolute date and time is its tooltip, and with
+`detail` it is shown as well. An empty or unparseable `datetime` says so in words.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/relative-time';`
+- Class: `import { OddkinRelativeTime } from '@oddkin/components/relative-time';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `datetime` | `datetime` | string | '' | When: an ISO 8601 date and time, as on `<time datetime>`. |
+| `detail` | `detail` (reflects) | boolean | false | Also shows the absolute date and time. |
+| `strings` | none: assign as a property | Partial<{ unavailable: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+None.
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The element's box. |
+| `detail` | The absolute date and time (with `detail`). |
+| `time` | The relative text: a `<time>`, or the unavailable text. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: When something happened or will happen, where closeness matters more than the exact time: activity, comments, updates. (src/relative-time/relative-time.ts:45)
+- Not for: Exact times that people compare or copy (show the absolute date); a running countdown. (src/relative-time/relative-time.ts:46)
+- Accessibility: Assistive technology reads the relative text; the absolute date and time is the native tooltip of the `<time>` (hover only), so show it with `detail` where it matters, as Figma's Absolute detail does. (src/relative-time/relative-time.ts:42)
+- Limitations: It does not update itself: the text is computed when it renders (Figma: not a live clock). Set `datetime` again to refresh it, or show the absolute date. (src/relative-time/relative-time.ts:43)
+
+## Examples
+
+- `example:odd-relative-time/default` in src/relative-time/relative-time.examples.ts (package source), preview roles role:relativeTime
+- `example:odd-relative-time/detail` in src/relative-time/relative-time.examples.ts (package source)
+- `example:odd-relative-time/future` in src/relative-time/relative-time.examples.ts (package source)
+- `example:odd-relative-time/unavailable` in src/relative-time/relative-time.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-relative-time/detailFalse` produces `usage.boolean.false`; correct: `example:odd-relative-time/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`