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

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

@@ -0,0 +1,117 @@
+# `<odd-radio-group>` (OddkinRadioGroup)
+
+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.
+
+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`
+
+## Verified
+
+- 53 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-rating.md

@@ -0,0 +1,119 @@
+# `<odd-rating>` (OddkinRating)
+
+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 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`
+
+## Verified
+
+- 58 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-relative-time.md

@@ -0,0 +1,80 @@
+# `<odd-relative-time>` (OddkinRelativeTime)
+
+Package `@oddkin/components` 1.0.0-beta.0 · 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`
+
+## Verified
+
+- 15 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-scroll-region.md

@@ -0,0 +1,81 @@
+# `<odd-scroll-region>` (OddkinScrollRegion)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Layout. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Content that scrolls on its own inside a page, reachable and scrollable from the keyboard
+(WCAG 2.1.1). Bound it with `block-size` or `max-block-size`; while its content overflows, the
+scroller is focusable and a region named by `label`. When the content fits it is neither, so it
+adds no tab stop.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/scroll-region';`
+- Class: `import { OddkinScrollRegion } from '@oddkin/components/scroll-region';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the region while it scrolls. |
+| `strings` | none: assign as a property | Partial<{ label: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The content, stacked with the layout gap. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The scroller. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-scroll-region-gap` | Space between children (default the theme's `layout.gap`). |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A bounded area that scrolls inside a page: a long list in a panel, a log, a preview pane. (src/scroll-region/scroll-region.ts:21)
+- Not for: The page itself (let the document scroll); a set of choices (use a listbox, which manages focus itself). (src/scroll-region/scroll-region.ts:22)
+- Accessibility: While the content overflows, the scroller is in the tab order as a `region` named by `label` (default `strings.label`, "Scrollable content"); name it after its content. When the content fits, it is not focusable and has no role. (src/scroll-region/scroll-region.ts:18)
+- Keyboard: While it overflows: Tab reaches it; arrow keys, Page Up, Page Down, Home, End, and Space scroll it. (src/scroll-region/scroll-region.ts:19)
+
+## Examples
+
+- `example:odd-scroll-region/default` in src/scroll-region/scroll-region.examples.ts (package source), preview roles role:scrollRegion
+- `example:odd-scroll-region/fits` in src/scroll-region/scroll-region.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-scroll-region/heightAttribute` produces `usage.attribute.unknown`; correct: `example:odd-scroll-region/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-scroll-region-gap`
+
+## 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
+
+- 9 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-segmented-control.md

@@ -0,0 +1,114 @@
+# `<odd-segmented-control>` (OddkinSegmentedControl)
+
+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.
+
+One value from a few short options, drawn as joined segments: the radio-group behavior with a
+segmented look. Options come from `<option>` children or from `options`; an option with an
+`icon` (`options` only) shows the icon alone, and its `label` names it.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/segmented-control';`
+- Class: `import { OddkinSegmentedControl } from '@oddkin/components/segmented-control';`
+- 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 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. |
+| `size` | `size` (reflects) | "sm" \| "md" \| "lg" | 'md' | Segment height and padding. |
+| `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 track holding the segments. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, segments, and error. |
+| `label` | The visible label. |
+| `option` | One segment. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: A compact choice among two to five short values that takes effect at once: a view mode, a preview size. (src/segmented-control/segmented-control.ts:22)
+- Not for: Switching between content panels (use odd-tabs); options that need descriptions (use odd-radio-group); actions (use odd-button or odd-toolbar). (src/segmented-control/segmented-control.ts:23)
+- Accessibility: A `role="radiogroup"` in the shadow root, named by `label` and described by the description and error, holds native radios, each named by its option's label (also for icon-only options) and described by its option's description (`title`). (src/segmented-control/segmented-control.ts:19)
+- Keyboard: Native radio behavior: Tab enters the control at the checked segment (or the first, when none is checked) and leaves it; arrow keys move to the next or previous segment and check it; Space checks the focused segment. (src/segmented-control/segmented-control.ts:20)
+- Limitations: Option descriptions are each segment's tooltip (`title`); groups (`<optgroup>`) are drawn as one run of segments. (src/segmented-control/segmented-control.ts:24)
+
+## Examples
+
+- `example:odd-segmented-control/default` in src/segmented-control/segmented-control.examples.ts (package source)
+- `example:odd-segmented-control/disabled` in src/segmented-control/segmented-control.examples.ts (package source)
+- `example:odd-segmented-control/fromData` in src/segmented-control/segmented-control.examples.ts (package source), preview roles role:segmented
+- `example:odd-segmented-control/iconOnly` in src/segmented-control/segmented-control.examples.ts (package source)
+- `example:odd-segmented-control/large` in src/segmented-control/segmented-control.examples.ts (package source)
+- `example:odd-segmented-control/small` in src/segmented-control/segmented-control.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-segmented-control/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-segmented-control/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
+
+- 51 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-select.md

@@ -0,0 +1,122 @@
+# `<odd-select>` (OddkinSelect)
+
+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 compact choice of one option in a form: a styled native `<select>`, so the engine's own picker,
+keyboard, and assistive-technology support come with it. Options come from `<option>` and
+`<optgroup>` children, written as for a native select (`selected` marks the default), or from
+`options`. Where `appearance: base-select` is supported, the open picker is drawn as Oddkin's
+raised listbox surface with option rows; elsewhere the engine draws it.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/select';`
+- Class: `import { OddkinSelect } from '@oddkin/components/select';`
+
+## 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 select. |
+| `options` | none: assign as a property | readonly OptionRecord[] \| undefined | undefined | The choices; when set, `<option>` children are ignored. |
+| `value` | `value` | string | '' | Value of the chosen option; the `value` attribute sets the default. |
+| `placeholder` | `placeholder` | string | '' | Shown, and submitted as an empty value, until an option is chosen; with `required`, it blocks submission. Never a substitute for a label. |
+| `required` | `required` (reflects) | boolean | false | An option must be chosen to submit. |
+| `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 commits a change (native `change` is not composed). |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The native `<select>`. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of label, description, control, and error. |
+| `label` | The visible label. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-field-background` | Background colour. Shared by every form control and the field recipe. |
+| `--odd-field-border-color` | Border colour. Shared by every form control and the field recipe. |
+| `--odd-field-height` | Minimum height (never below the target-size token). Shared by every form control and the field recipe. |
+| `--odd-field-radius` | Corner radius. Shared by every form control and the field recipe. |
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: One choice from a short, known list in a form: a role, a region, a sort order. (src/select/select.ts:45)
+- Not for: Several choices, or a list that should stay visible (use odd-listbox); a long list to search (use odd-combobox); actions (use odd-menu). (src/select/select.ts:46)
+- Accessibility: `label` names the native select 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 a missing choice after the user leaves the select or a validity check fails. The placeholder is a disabled first option, never a substitute for the label. (src/select/select.ts:42)
+- Keyboard: Native select behavior: Space, Enter, or Alt+Down opens the picker; Up and Down move; typing jumps to a matching option; Escape closes the picker. (src/select/select.ts:43)
+- Limitations: Option descriptions are each option's tooltip (`title`); the closed select shows the label only. (src/select/select.ts:47)
+- Limitations: Under a strict `style-src` Content Security Policy, WebKit reports a `style-src-attr` violation for each native `<select>` from its own rendering; nothing visible is blocked. Allow for it where violations are collected. (src/select/select.ts:48)
+
+## Examples
+
+- `example:odd-select/default` in src/select/select.examples.ts (package source), preview roles role:select
+- `example:odd-select/disabled` in src/select/select.examples.ts (package source)
+- `example:odd-select/fromData` in src/select/select.examples.ts (package source)
+- `example:odd-select/groups` in src/select/select.examples.ts (package source)
+- `example:odd-select/inForm` in src/select/select.examples.ts (package source)
+- `example:odd-select/placeholder` in src/select/select.examples.ts (package source)
+- `example:odd-select/withError` in src/select/select.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-select/optionsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-select/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`
+
+## Verified
+
+- 50 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)