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

package/agent/references/components/odd-copy-button.md

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

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

@@ -0,0 +1,122 @@
+# `<odd-date-picker>` (OddkinDatePicker)
+
+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 date, typed in the page language's numeric order or chosen from a calendar in a popup: the
+WAI-ARIA date picker dialog. The value is a `YYYY-MM-DD` date, submitted under `name` as a
+native date input submits it; the field shows it as the language writes dates in digits
+(26/10/2026 in British English, 10/26/2026 in American English).
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/date-picker';`
+- Class: `import { OddkinDatePicker } from '@oddkin/components/date-picker';`
+- Dependency (calendar): `<odd-calendar>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` (reflects) | string \| undefined | undefined | Name submitted with the form. Reflected: a form-associated element submits under its name attribute. |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents interaction and submission. |
+| `description` | `description` | string | '' | Help text below the label. |
+| `error` | `error` | string | '' | Error message; marks the field invalid (custom validity) while set. |
+| `label` | `label` | string | '' | Visible label; names the field. |
+| `defaultValue` | `value` | string | '' | Initial date, `YYYY-MM-DD`; the `value` attribute, as on a native date input. |
+| `min` | `min` | string | '' | Earliest date, `YYYY-MM-DD`. |
+| `max` | `max` | string | '' | Latest date, `YYYY-MM-DD`. |
+| `required` | `required` (reflects) | boolean | false | A date is required to submit. |
+| `readonly` | `readonly` (reflects) | boolean | false | The date can be read and the calendar opened, not changed; still submitted. |
+| `placeholder` | `placeholder` | string | '' | Placeholder; never a substitute for a label. |
+| `firstDay` | `first-day` | number | 0 | The calendar's first day of the week, 1 (Monday) to 7 (Sunday); 0 follows the page language. |
+| `isDateDisabled` | none: assign as a property | CalendarDateFilter \| undefined |  | Returns `true` for a date (`YYYY-MM-DD`) the user may not choose in the calendar. |
+| `strings` | none: assign as a property | Partial<{ choose: string; change: string; invalid: string; day: string; month: string; year: string; previousMonth: string; nextMonth: string; today: string; clear: string; }> \| undefined | undefined | Localized string overrides: `choose`, `change` (`{date}`), `invalid` (`{format}`), `day`, `month`, `year`, and the calendar's `previousMonth`, `nextMonth`, `today`, `clear`. |
+| `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 chosen date, `YYYY-MM-DD`, or empty. Setting it detaches it from `defaultValue`. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `checkValidity()` | Whether the field is valid; when not, fires `invalid` at it, as on native controls. |
+| `reportValidity()` | As `checkValidity()`, and an invalid field also shows its error to the user. |
+| `setCustomValidity()` | As on native controls; the message is also shown, since it sets `error`. An empty string clears it. |
+| `formResetCallback()` | Native callback: the owning form was reset. |
+| `formStateRestoreCallback()` | Native callback: restore after navigation or autofill restore. |
+| `formDisabledCallback()` | Native callback: an ancestor fieldset's disabled state changed. |
+| `formAssociatedCallback()` | Native callback: the form owner changed (moved, `form` attribute, or the named form). |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | Dispatched when the user commits a date: typed and committed, or chosen in the calendar. |
+| `change` | CustomEvent | user (authored) | Dispatched with `input` for each date the user commits. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `button` | Opens the calendar. |
+| `control` | The text input. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | The field: label, description, control box, and error. |
+| `label` | The visible label. |
+| `popup` | The popup that holds the calendar (`odd-calendar`). |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `open` | The calendar is open. |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: One date the user may know and type, or prefer to find in a month: a booking, a due date, a publish date. (src/date-picker/date-picker.ts:54)
+- Not for: A memorable date such as a birth date (separate fields, or odd-input type="date"); a date and time (odd-input type="datetime-local"); a range of dates; an inline month to choose from (odd-calendar). (src/date-picker/date-picker.ts:55)
+- Accessibility: The text input is named by the label. The button after it is named "Choose date", or "Change date," with the chosen date in full, and has `aria-haspopup="dialog"` and `aria-expanded`; it opens a non-modal dialog named "Choose date" that holds an `odd-calendar`, which takes focus on the chosen date (or today). Choosing a date closes the dialog and returns focus to the button; Escape or a click outside closes it without a change. Text that is not a date makes the field invalid with a message that gives the expected order. (src/date-picker/date-picker.ts:51)
+- Keyboard: The input and the button are Tab stops. A typed date is committed when focus leaves the input or on Enter. Enter or Space on the button opens the calendar; there odd-calendar's keys apply, Enter or Space chooses and closes, and Escape closes. (src/date-picker/date-picker.ts:52)
+- Limitations: Typed dates are read as three groups of digits in the language's order with a four-digit year; month names are not read. (src/date-picker/date-picker.ts:56)
+
+## Examples
+
+- `example:odd-date-picker/default` in src/date-picker/date-picker.examples.ts (package source), preview roles role:datePicker
+- `example:odd-date-picker/disabled` in src/date-picker/date-picker.examples.ts (package source)
+- `example:odd-date-picker/invalid` in src/date-picker/date-picker.examples.ts (package source)
+- `example:odd-date-picker/restricted` in src/date-picker/date-picker.examples.ts (package source)
+- `example:odd-date-picker/selected` in src/date-picker/date-picker.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-date-picker/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-date-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
+
+- 74 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-dialog.md

@@ -0,0 +1,101 @@
+# `<odd-dialog>` (OddkinDialog)
+
+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 modal dialog: a native `<dialog>` shown modally, so the rest of the page is inert until it
+closes. Escape closes it unless `closedby="none"`; with `closedby="any"`, so does a press
+on the backdrop. A `<form method="dialog">` inside closes it with the value of the button that
+submitted it.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/dialog';`
+- Class: `import { OddkinDialog } from '@oddkin/components/dialog';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The title, which names the dialog. Required. |
+| `alert` | `alert` | boolean | false | Makes it an alert dialog: an urgent message that needs a response, such as confirming that something is deleted. Its body describes it. |
+| `closedBy` | `closedby` | "none" \| "closerequest" \| "any" | 'closerequest' | What closes it besides its controls: Escape (`closerequest`), also a press on the backdrop (`any`), or neither (`none`). The browser does it where it can; elsewhere the dialog does. |
+| `noClose` | `no-close` | boolean | false | Hides the close button. Keep another way out, such as a Cancel button. |
+| `open` | `open` (reflects) | boolean | false | Whether it is open. |
+| `strings` | none: assign as a property | Partial<{ close: string; }> \| undefined | undefined | Localized string overrides. |
+| `returnValue` | none: assign as a property | string |  | The `close()` argument, or the value of the button that submitted its form. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Opens it. |
+| `close()` | Closes it; `returnValue` becomes the argument when there is one. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The body. |
+| `footer` | The actions, at the inline end. |
+| `header` | Under the title: a subtitle or a status. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `body` | The body. |
+| `close` | The close button. |
+| `dialog` | The `<dialog>` surface. |
+| `footer` | The actions, under a divider; hidden while the slot is empty. |
+| `header` | The title, the header slot, and the close button. |
+| `title` | The title. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-dialog-inline-size` | Its width, within the viewport. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A task or decision that must be finished or dismissed before going on: a short form, a confirmation, a destructive action. (src/dialog/dialog.ts:31)
+- Not for: Extra detail next to its trigger (use odd-popover); a panel beside the page (use odd-drawer); a passing confirmation (use odd-toast). (src/dialog/dialog.ts:32)
+- Accessibility: A `dialog`, or an `alertdialog` with `alert`, named by `label` (the title); an alert dialog is also described by its body. Opening it moves focus to the slotted element with `autofocus`, else the first control in the body or footer, else the close button. Everything outside is inert while it is open. Closing it returns focus to the element that had it when it opened. The close button is named by `strings.close`. (src/dialog/dialog.ts:27)
+- Keyboard: Tab and Shift+Tab move through its controls only. Escape closes it unless `closedby="none"`. (src/dialog/dialog.ts:28)
+
+## Examples
+
+- `example:odd-dialog/alert` in src/dialog/dialog.examples.ts (package source), preview roles role:alertDialog
+- `example:odd-dialog/closedByAny` in src/dialog/dialog.examples.ts (package source)
+- `example:odd-dialog/default` in src/dialog/dialog.examples.ts (package source), preview roles role:dialog
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-dialog/closedByBackdrop` produces `usage.attribute.value`; correct: `example:odd-dialog/closedByAny`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-dialog-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
+
+- 37 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-disclosure.md

@@ -0,0 +1,95 @@
+# `<odd-disclosure>` (OddkinDisclosure)
+
+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.
+
+One trigger that shows or hides one related region: a native `<details>` and `<summary>`.
+Disclosures that share a `name` in the same tree form an accordion: opening one closes the
+others, and adjacent ones draw as one surface.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/disclosure';`
+- Class: `import { OddkinDisclosure } from '@oddkin/components/disclosure';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The summary text; names the disclosure button. |
+| `open` | `open` (reflects) | boolean | false | Shows the content. |
+| `name` | `name` (reflects) | string | '' | Exclusive group: opening one closes the others with the same name in the same tree, as native `<details name>` does. |
+| `disabled` | `disabled` (reflects) | boolean | false | The summary cannot be activated and leaves the Tab order. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `toggle` | CustomEvent | notification (authored) | A `ToggleEvent` (`oldState`, `newState`) once per change of `open`, whatever changed it, as native `<details>` reports it. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The content shown while open. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `content` | The region around the default slot. |
+| `label` | The summary text. |
+| `marker` | The chevron. |
+| `summary` | The native `<summary>`: the button that opens and closes it. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-disclosure-background` | Background of the surface. |
+| `--odd-disclosure-radius` | Corner radius of the surface. |
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `joined-end` | The next sibling is a disclosure of the same group. |
+| `joined-start` | The previous sibling is a disclosure of the same group; the two share a divider. |
+
+## Guidance (authored)
+
+- Use for: Optional detail, advanced settings, and frequently asked questions (an accordion with `name`). (src/disclosure/disclosure.ts:35)
+- Not for: Switching between views (use odd-tabs); navigation menus; content everyone needs to read. (src/disclosure/disclosure.ts:36)
+- Accessibility: The summary is a native disclosure button named by `label`; its expanded state comes from the platform. Content stays in the light DOM and in reading order, and find-in-page opens a closed disclosure that holds a match. Disabled: the summary leaves the Tab order and reports `aria-disabled`. (src/disclosure/disclosure.ts:32)
+- Keyboard: Tab reaches the summary; Enter or Space opens and closes it. (src/disclosure/disclosure.ts:33)
+
+## Examples
+
+- `example:odd-disclosure/accordion` in src/disclosure/disclosure.examples.ts (package source)
+- `example:odd-disclosure/default` in src/disclosure/disclosure.examples.ts (package source), preview roles role:disclosure
+- `example:odd-disclosure/disabled` in src/disclosure/disclosure.examples.ts (package source)
+- `example:odd-disclosure/open` in src/disclosure/disclosure.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-disclosure/openFalse` produces `usage.boolean.false`; correct: `example:odd-disclosure/default`
+- `example:odd-disclosure/summarySlot` produces `usage.slot.unknown`; correct: `example:odd-disclosure/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-disclosure-background`, `--odd-disclosure-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
+
+- 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)

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

@@ -0,0 +1,103 @@
+# `<odd-drawer>` (OddkinDrawer)
+
+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 panel at an inline edge of the viewport: odd-dialog with a side-sheet layout. It is modal by
+default, so the rest of the page is inert until it closes; with `no-modal` the page stays usable
+beside it. `side` is logical, so it mirrors in right-to-left text.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/drawer';`
+- Class: `import { OddkinDrawer } from '@oddkin/components/drawer';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The title, which names the dialog. Required. |
+| `alert` | `alert` | boolean | false | Makes it an alert dialog: an urgent message that needs a response, such as confirming that something is deleted. Its body describes it. |
+| `closedBy` | `closedby` | "none" \| "closerequest" \| "any" | 'closerequest' | What closes it besides its controls: Escape (`closerequest`), also a press on the backdrop (`any`), or neither (`none`). The browser does it where it can; elsewhere the dialog does. |
+| `noClose` | `no-close` | boolean | false | Hides the close button. Keep another way out, such as a Cancel button. |
+| `open` | `open` (reflects) | boolean | false | Whether it is open. |
+| `strings` | none: assign as a property | Partial<{ close: string; }> \| undefined | undefined | Localized string overrides. |
+| `side` | `side` (reflects) | "inline-end" \| "inline-start" | 'inline-end' | The edge it opens at: `inline-end` is the right in left-to-right text and the left in right-to-left text. |
+| `noModal` | `no-modal` | boolean | false | Leaves the page usable while it is open: no backdrop, nothing inert, and focus may leave it. |
+| `returnValue` | none: assign as a property | string |  | The `close()` argument, or the value of the button that submitted its form. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Opens it. |
+| `close()` | Closes it; `returnValue` becomes the argument when there is one. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The body. |
+| `footer` | The actions, at the inline end. |
+| `header` | Under the title: a subtitle or a status. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `body` | The body. |
+| `close` | The close button. |
+| `dialog` | The `<dialog>` surface. |
+| `footer` | The actions, under a divider; hidden while the slot is empty. |
+| `header` | The title, the header slot, and the close button. |
+| `title` | The title. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-dialog-inline-size` | Its width, within the viewport. |
+| `--odd-drawer-inline-size` | Its width, within the viewport. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Details or a task beside the page that keeps its context: an item's properties, filters, settings. (src/drawer/drawer.ts:22)
+- Not for: A decision that must be made first (use odd-dialog); extra detail next to its trigger (use odd-popover); a passing confirmation (use odd-toast). (src/drawer/drawer.ts:23)
+- Accessibility: A `dialog`, or an `alertdialog` with `alert`, named by `label` (the title). Opening it moves focus to the slotted element with `autofocus`, else the first control in the body or footer, else the close button. Modal, everything outside is inert while it is open; with `no-modal`, focus may leave it. Closing it returns focus to the element that had it when it opened, unless focus has moved elsewhere. The close button is named by `strings.close`. (src/drawer/drawer.ts:19)
+- Keyboard: Escape closes it unless `closedby="none"`. Modal, Tab and Shift+Tab move through its controls only. (src/drawer/drawer.ts:20)
+
+## Examples
+
+- `example:odd-drawer/default` in src/drawer/drawer.examples.ts (package source), preview roles role:drawer
+- `example:odd-drawer/inlineStart` in src/drawer/drawer.examples.ts (package source)
+- `example:odd-drawer/nonModal` in src/drawer/drawer.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-drawer/physicalSide` produces `usage.attribute.value`; correct: `example:odd-drawer/inlineStart`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-dialog-inline-size`, `--odd-drawer-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
+
+- 47 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-empty-state.md

@@ -0,0 +1,80 @@
+# `<odd-empty-state>` (OddkinEmptyState)
+
+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.
+
+Explains why a region is empty and offers the next useful step: first use, no results, nothing
+left to do.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/empty-state';`
+- Class: `import { OddkinEmptyState } from '@oddkin/components/empty-state';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The title. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The explanation. |
+| `footer` | The next step, such as a button. |
+| `media` | An illustration or icon, drawn on a circle. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The centred column. |
+| `footer` | The footer region (hidden when empty). |
+| `label` | The title. |
+| `media` | The circle behind the media slot (hidden when empty). |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Empty lists, tables, and searches with no results. (src/empty-state/empty-state.ts:17)
+- Not for: Errors (use odd-alert); loading (use odd-skeleton or odd-spinner). (src/empty-state/empty-state.ts:18)
+- Accessibility: Plain text in place; it adds no role. When it replaces results after a search, announce the outcome separately (for example with a live region the page owns). (src/empty-state/empty-state.ts:15)
+
+## Examples
+
+- `example:odd-empty-state/default` in src/empty-state/empty-state.examples.ts (package source), preview roles role:emptyState
+- `example:odd-empty-state/noResults` in src/empty-state/empty-state.examples.ts (package source)
+- `example:odd-empty-state/textOnly` in src/empty-state/empty-state.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-empty-state/actionsSlot` produces `usage.slot.unknown`; correct: `example:odd-empty-state/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
+
+- 13 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)