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

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

@@ -0,0 +1,131 @@
+# `<odd-button>` (OddkinButton)
+
+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 for actions. Renders a native `<button>` in its shadow root, so keyboard
+activation, focus, and accessible naming come from the platform.
+
+In a form it submits or resets through a temporary native button (see the limitations).
+Where native submit-button semantics matter, style a native `<button class="odd-button">`
+with `@oddkin/components/css/button.css`, which looks the same.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/button';`
+- Class: `import { OddkinButton } from '@oddkin/components/button';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `appearance` | `appearance` (reflects) | "primary" \| "secondary" \| "ghost" | 'secondary' | Visual emphasis. |
+| `size` | `size` (reflects) | "sm" \| "md" \| "lg" | 'md' | Size. |
+| `type` | `type` | "button" \| "submit" \| "reset" | 'button' | Form behavior, as on a native button. |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents interaction and focus. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a spinner and ignores activation; the button stays focusable. |
+| `fullWidth` | `full-width` (reflects) | boolean | false | Fills the inline size of its container. |
+| `toggle` | `toggle` (reflects) | boolean | false | Keeps a pressed state that each activation flips (`aria-pressed`). |
+| `pressed` | `pressed` (reflects) | boolean | false | Whether a `toggle` button is pressed. |
+| `name` | `name` | string | '' | Name submitted with the form. |
+| `value` | `value` | string | '' | Value submitted with the form. |
+| `formAction` | `formaction` (reflects) | string \| undefined | undefined | URL this button submits to instead of the form's `action`. |
+| `formMethod` | `formmethod` (reflects) | string \| undefined | undefined | Method (`get`, `post`, `dialog`) this button submits with instead of the form's. |
+| `formEnctype` | `formenctype` (reflects) | string \| undefined | undefined | Encoding this button submits with instead of the form's `enctype`. |
+| `formTarget` | `formtarget` (reflects) | string \| undefined | undefined | Navigable this button submits to instead of the form's `target`. |
+| `formNoValidate` | `formnovalidate` (reflects) | boolean | false | Submits without constraint validation. |
+| `label` | `label` | string | '' | Accessible name when the content has no text (icon-only buttons). |
+| `form` | none (read-only) | HTMLFormElement \| null |  | The form this button belongs to, if any. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `formDisabledCallback()` | Native callback: an ancestor fieldset's disabled state changed. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | A toggle button was flipped by the user; `pressed` has its new value. |
+| `change` | CustomEvent | user (authored) | A toggle button was flipped by the user (after `input`). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The label. Its text is the button's accessible name. |
+| `end` | Content after the label. |
+| `start` | Content before the label, such as an icon. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The native button. |
+| `spinner` | The loading indicator. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-button-background` | Background colour. |
+| `--odd-button-border-color` | Border colour. |
+| `--odd-button-color` | Text colour. |
+| `--odd-button-height` | Minimum height (never below the target-size token). |
+| `--odd-button-padding-inline` | Inline padding. |
+| `--odd-button-radius` | Corner radius. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Triggering an action, or submitting or resetting the form it belongs to (its ancestor form or the one named by `form`). (src/button/button.ts:47)
+- Not for: Navigation to another page; use a link. (src/button/button.ts:48)
+- Accessibility: The slotted text names the button. Icon-only buttons must set `label`. (src/button/button.ts:41)
+- Accessibility: `loading` keeps the button focusable and sets `aria-disabled`; announce progress separately if it matters. (src/button/button.ts:42)
+- Accessibility: With `toggle`, the native button reports `aria-pressed`; keep the label the same in both states ("Bold", not "Bold on"). (src/button/button.ts:43)
+- Keyboard: Enter and Space activate the button (native behavior). (src/button/button.ts:44)
+- Limitations: In a form, submission and reset go through a temporary native button appended to the form during the click. `SubmitEvent.submitter` is that button (with `name`, `value`, and the `form*` overrides), not this element, and it is removed after dispatch, so build `new FormData(form, event.submitter)` synchronously in the `submit` listener. Mutation observers on the form see it added and removed. `form.requestSubmit(button)` rejects this element with a `TypeError`; call `button.click()` instead. (src/button/button.ts:49)
+- Limitations: Implicit submission: Enter in a text field never uses this element as the default button. The default button is the form's first native submit button; without one, Enter submits with no submitter, and only when the form has a single text field, so this element's `name`, `value`, and overrides are not sent. Use a native submit button where Enter must submit through it. (src/button/button.ts:50)
+- Limitations: `formAction`, `formMethod`, `formEnctype`, and `formTarget` return the attribute text: unlike a native button they neither resolve URLs nor report the form's values. The temporary button receives them unchanged, so missing and invalid values behave as on a native button. (src/button/button.ts:51)
+
+## Examples
+
+- `example:odd-button/default` in src/button/button.examples.ts (package source)
+- `example:odd-button/disabled` in src/button/button.examples.ts (package source)
+- `example:odd-button/fullWidth` in src/button/button.examples.ts (package source)
+- `example:odd-button/ghost` in src/button/button.examples.ts (package source)
+- `example:odd-button/inForm` in src/button/button.examples.ts (package source)
+- `example:odd-button/large` in src/button/button.examples.ts (package source)
+- `example:odd-button/loading` in src/button/button.examples.ts (package source)
+- `example:odd-button/pressed` in src/button/button.examples.ts (package source)
+- `example:odd-button/primary` in src/button/button.examples.ts (package source), preview roles role:primaryAction
+- `example:odd-button/secondary` in src/button/button.examples.ts (package source), preview roles role:secondaryAction
+- `example:odd-button/small` in src/button/button.examples.ts (package source)
+- `example:odd-button/toggle` in src/button/button.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-button/dangerAppearance` produces `usage.attribute.value`; correct: `example:odd-button/primary`
+- `example:odd-button/disabledFalse` produces `usage.boolean.false`; correct: `example:odd-button/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-button-background`, `--odd-button-border-color`, `--odd-button-color`, `--odd-button-height`, `--odd-button-padding-inline`, `--odd-button-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
+
+- 86 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-calendar.md

@@ -0,0 +1,132 @@
+# `<odd-calendar>` (OddkinCalendar)
+
+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 month of dates to choose one from: the WAI-ARIA date grid, with the month and buttons to the
+months before and after above it, and Today and Clear below. The value is a `YYYY-MM-DD` date,
+submitted under `name` as a native date input submits it. Weeks start on the page language's
+first day (`first-day` sets it); names come from `Intl.DateTimeFormat`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/calendar';`
+- Class: `import { OddkinCalendar } from '@oddkin/components/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 calendar. |
+| `defaultValue` | `value` | string | '' | Initial date, `YYYY-MM-DD`; the `value` attribute, as on a native date input. |
+| `min` | `min` | string | '' | Earliest date that can be chosen, `YYYY-MM-DD`. |
+| `max` | `max` | string | '' | Latest date that can be chosen, `YYYY-MM-DD`. |
+| `required` | `required` (reflects) | boolean | false | A date is required to submit. |
+| `readonly` | `readonly` (reflects) | boolean | false | The dates can be moved through but the value cannot change; still submitted, and not validated. |
+| `firstDay` | `first-day` | number | 0 | First day of the week, 1 (Monday) to 7 (Sunday) as in `Intl.Locale` week information; 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, such as a weekend or a booked day. |
+| `strings` | none: assign as a property | Partial<{ previousMonth: string; nextMonth: string; today: string; clear: string; }> \| undefined | undefined | Localized string overrides: `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). |
+| `focus()` | Focuses the date that holds the grid's Tab stop. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | Dispatched when the user chooses or clears a date, as on a native date input. |
+| `change` | CustomEvent | user (authored) | Dispatched with `input` for each date the user chooses or clears. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `actions` | The row of the Today and Clear buttons. |
+| `calendar` | The surface: month navigation, grid, and actions. |
+| `clear` | Clears the value. |
+| `day` | A date cell (`role="gridcell"`). |
+| `day-disabled` | A date outside `min` and `max` or disabled by `isDateDisabled`. |
+| `day-outside` | A date in the month before or after. |
+| `day-selected` | The chosen date. |
+| `day-today` | Today's date. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | The field: label, description, calendar, and error. |
+| `grid` | The date grid (`role="grid"`). |
+| `header` | The month navigation row. |
+| `heading` | The month and year shown. |
+| `label` | The visible label. |
+| `next` | The button to the month after. |
+| `previous` | The button to the month before. |
+| `today` | Chooses today. |
+| `weekday` | A column header: the day of the week. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: Choosing one date where the month view helps: a booking, a due date, a day in a schedule. (src/calendar/calendar.ts:123)
+- Not for: A memorable date such as a birth date (use odd-input type="date" or separate fields); a date and time (use odd-input type="datetime-local"); a range of dates. (src/calendar/calendar.ts:124)
+- Accessibility: A `group` named by the label holds the month buttons, a `grid` named by the month and year, and the Today and Clear buttons. Each date cell is named by the full date and marks the chosen date `aria-selected`, today `aria-current="date"`, and dates that cannot be chosen `aria-disabled`; a read-only grid is `aria-readonly`. The month and year are a polite live region, so the month buttons announce the new month. (src/calendar/calendar.ts:120)
+- Keyboard: The grid is one Tab stop. Left and Right move a day (swapped in right-to-left text), Up and Down a week; Home and End go to the first and last day of the week; Page Up and Page Down move a month, with Shift a year. Enter or Space chooses the date (not when read-only). Moving past `min` or `max` stops there. (src/calendar/calendar.ts:121)
+- Limitations: Where the browser has no week information (`Intl.Locale` without `getWeekInfo`), weeks start on Monday unless `first-day` is set. (src/calendar/calendar.ts:125)
+
+## Examples
+
+- `example:odd-calendar/default` in src/calendar/calendar.examples.ts (package source), preview roles role:calendar
+- `example:odd-calendar/disabled` in src/calendar/calendar.examples.ts (package source)
+- `example:odd-calendar/invalid` in src/calendar/calendar.examples.ts (package source)
+- `example:odd-calendar/required` in src/calendar/calendar.examples.ts (package source)
+- `example:odd-calendar/restricted` in src/calendar/calendar.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-calendar/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-calendar/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
+
+- 81 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-card.md

@@ -0,0 +1,96 @@
+# `<odd-card>` (OddkinCard)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Containers. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A surface that groups related content, with optional header and footer.
+
+It is a plain container unless it has an accessible name: `label`, or (where the browser
+supports ARIA element reflection) a heading in the `header` slot. Then it is a named `region`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/card';`
+- Class: `import { OddkinCard } from '@oddkin/components/card';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `appearance` | `appearance` (reflects) | "outlined" \| "filled" \| "elevated" | 'outlined' | Surface treatment. |
+| `padding` | `padding` (reflects) | "none" \| "sm" \| "md" \| "lg" | 'md' | Inner padding step. |
+| `label` | `label` | string | '' | Accessible name; makes the card a region. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The body. |
+| `footer` | Actions or supplementary content. |
+| `header` | Heading and supporting content; a heading here names the card. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `body` | The body region. |
+| `footer` | The footer region (hidden when empty). |
+| `header` | The header region (hidden when empty). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-card-background` | Background colour. |
+| `--odd-card-border-color` | Border colour. |
+| `--odd-card-gap` | Space between header, body, and footer. |
+| `--odd-card-padding` | Inner padding with `padding="md"` (the default). Also the theme's `card.padding` role, so the theme sets it (density and profiles adjust it); `padding="none"`, `"sm"`, and `"lg"` replace it. |
+| `--odd-card-radius` | Corner radius. Also the theme's `card.radius` role, so the theme sets it. |
+| `--odd-card-shadow` | Shadow for `appearance="elevated"` (default `elevation.md`). |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Grouping related content and actions into one visual unit. (src/card/card.ts:28)
+- Not for: Page layout; use layout recipes. A whole clickable card; put a link or button inside. (src/card/card.ts:29)
+- Accessibility: Becomes a named region only with `label` or a slotted heading; otherwise it adds no landmark. (src/card/card.ts:26)
+- Limitations: Naming the region from a slotted heading needs `ElementInternals.ariaLabelledByElements` (newer than the browser baseline); without it, use `label`. (src/card/card.ts:30)
+
+## Examples
+
+- `example:odd-card/compact` in src/card/card.examples.ts (package source)
+- `example:odd-card/default` in src/card/card.examples.ts (package source), preview roles role:surface
+- `example:odd-card/elevated` in src/card/card.examples.ts (package source)
+- `example:odd-card/filled` in src/card/card.examples.ts (package source)
+- `example:odd-card/headed` in src/card/card.examples.ts (package source)
+- `example:odd-card/named` in src/card/card.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-card/bodySlot` produces `usage.slot.unknown`; correct: `example:odd-card/headed`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-card-background`, `--odd-card-border-color`, `--odd-card-gap`, `--odd-card-padding`, `--odd-card-radius`, `--odd-card-shadow`
+
+## 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
+
+- 23 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-carousel.md

@@ -0,0 +1,86 @@
+# `<odd-carousel>` (OddkinCarousel)
+
+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.
+
+A carousel (APG carousel, manual only): one slide at a time, with previous and next, the
+position, and a button per slide. It never moves by itself. Each element child is a slide; the
+element assigns each to a slide group inside its own shadow root (manual slot assignment), so the
+content stays in the light DOM.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/carousel';`
+- Class: `import { OddkinCarousel } from '@oddkin/components/carousel';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the carousel. |
+| `current` | `current` | string | '1' | The shown slide's number, from 1 (as odd-pagination's `current`); out of range, the nearest slide shows. |
+| `strings` | none: assign as a property | Partial<{ carousel: string; slide: string; position: string; previous: string; next: string; picker: string; goTo: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | The user showed another slide. |
+| `change` | CustomEvent | user (authored) | The user showed another slide (committed at once). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The slides, one per element child. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The carousel. |
+| `controls` | The row of controls. |
+| `next` | The next-slide button. |
+| `pick` | Each slide button; the shown slide's has `aria-current="true"`. |
+| `picker` | The group of slide buttons. |
+| `position` | The position text ("2 of 3"). |
+| `previous` | The previous-slide button. |
+| `slide` | Each slide group, around its child. |
+| `slides` | The live region around the slides. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A few related highlights in one place, one at a time: onboarding steps, featured items. (src/carousel/carousel.ts:51)
+- Not for: Content everyone must see (show it all); switching views (use odd-tabs); paging a long list (use odd-pagination). (src/carousel/carousel.ts:52)
+- Accessibility: A `region` with the role description "carousel", named by `label` (a `group` without one). Each slide is a `group` with the role description "slide", named by its position ("2 of 3"). The slides are a polite live region: a change the user makes is announced while focus stays on the control they used. At the ends, previous or next is `aria-disabled`, so focus stays on it. Slide buttons are named "Go to slide 2" (`strings.goTo`), their number being the visible text. (src/carousel/carousel.ts:48)
+- Keyboard: Tab moves through previous, the slide buttons, and next, then into the shown slide; Enter and Space activate. There are no arrow keys and no rotation to stop. (src/carousel/carousel.ts:49)
+
+## Examples
+
+- `example:odd-carousel/default` in src/carousel/carousel.examples.ts (package source), preview roles role:carousel
+- `example:odd-carousel/last` in src/carousel/carousel.examples.ts (package source)
+
+## 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
+
+- 26 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-checkbox-group.md

@@ -0,0 +1,111 @@
+# `<odd-checkbox-group>` (OddkinCheckboxGroup)
+
+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 named group of `odd-checkbox` choices with one legend, description, and error. Each choice
+keeps its own name, value, and checkedness; the group adds `required` (at least one checked)
+and `disabled` for all of them.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/checkbox-group';`
+- Class: `import { OddkinCheckboxGroup } from '@oddkin/components/checkbox-group';`
+- Dependency (choice): `<odd-checkbox>`
+
+## 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 legend; names the group. |
+| `required` | `required` (reflects) | boolean | false | At least one choice must be checked to submit. |
+| `orientation` | `orientation` (reflects) | "vertical" \| "horizontal" | 'vertical' | Stacks the choices, 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
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The `odd-checkbox` choices. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The choices. |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | The group: legend, description, choices, and error. |
+| `label` | The visible legend. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: Several independent choices under one question, such as notification channels. (src/checkbox-group/checkbox-group.ts:22)
+- Not for: One choice among several (use odd-radio-group); a single yes-or-no choice (use odd-checkbox). (src/checkbox-group/checkbox-group.ts:23)
+- Accessibility: A `role="group"` in the shadow root, named by the legend and described by the description and error, holds the slotted checkboxes, as a `<fieldset>` would. Each checkbox keeps its own name and state. (src/checkbox-group/checkbox-group.ts:19)
+- Keyboard: Tab moves through the checkboxes; Space toggles the focused one. (src/checkbox-group/checkbox-group.ts:20)
+- Limitations: `disabled` sets `disabled` on the choices that were enabled and clears it from those again when the group is enabled; a `<fieldset disabled>` around the group disables everything natively. (src/checkbox-group/checkbox-group.ts:24)
+- Limitations: A required group reports the browser's own message for an unselected set ("Please select one of these options." in English) at its first enabled choice; set `error` for your own wording. (src/checkbox-group/checkbox-group.ts:25)
+
+## Examples
+
+- `example:odd-checkbox-group/default` in src/checkbox-group/checkbox-group.examples.ts (package source), preview roles role:checkboxGroup
+- `example:odd-checkbox-group/disabled` in src/checkbox-group/checkbox-group.examples.ts (package source)
+- `example:odd-checkbox-group/horizontal` in src/checkbox-group/checkbox-group.examples.ts (package source)
+- `example:odd-checkbox-group/inForm` in src/checkbox-group/checkbox-group.examples.ts (package source)
+- `example:odd-checkbox-group/invalid` in src/checkbox-group/checkbox-group.examples.ts (package source)
+- `example:odd-checkbox-group/required` in src/checkbox-group/checkbox-group.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-checkbox-group/requiredFalse` produces `usage.boolean.false`; correct: `example:odd-checkbox-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
+
+- 41 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)