@gunkin/uiify 0.0.24-alpha → 0.0.26-alpha

package/skills/uiify/references/elements/accordion.md

@@ -14,7 +14,7 @@ Do not hide the page's main explanation or an action that is the only way to con
 
 ## Structure
 
-`Accordion` takes an `id`, `items` with a `value`, `label`, and `panel`, and `type="single"` or `"multiple"`. The visible summary is the question or section title; make it describe the revealed content. Single mode uses native `<details name>` grouping, so opening one section closes the other.
+`Accordion` takes an `id`, `items` with a `value`, `label`, and `panel`, and `type="single"` or `"multiple"`. The id is placed on the root and names the native `<details>` group in single mode. Use `slotProps.item`, `slotProps.trigger`, and `slotProps.panel` to pass native props, `className`, `style`, refs, events or `data-*` to each generated element; use `byItemValue` to customize one item. Put Tailwind utilities on the slot they style. When composing custom markup, use public `Details.Root`, `Details.Summary`, and `Details.Content` parts directly. The visible summary is the question or section title; make it describe the revealed content.
 
 ## Responsive
 

package/skills/uiify/references/elements/aspect-ratio.md

@@ -23,7 +23,7 @@ import "@gunkin/uiify/components/behavior.css";
 </AspectRatio>
 ```
 
-Direct import: `@gunkin/uiify/components/aspect-ratio`. This reusable layout Component is Tier 0. It renders two wrappers: root `data-uiify-aspect-ratio`, then `data-part="content"` around children. Root forwards native props, events, `className`, `style`, `ref`, `as` and `render`; custom renderers must forward props/ref. Owned markers cannot be overridden.
+Direct import: `@gunkin/uiify/components/aspect-ratio`. This reusable layout Component is Tier 0. It renders two wrappers: root `data-uiify-aspect-ratio`, then `data-part="content"` around children. Root forwards native props, events, `className`, `style`, `ref`, `as` and `render`; custom renderers must forward props/ref. Consumer props replace its default markers.
 
 `ratio?: number` accepts a positive finite number (width/height). Square default: `1`; invalid numbers fall back to `1`. Omission leaves the stylesheet default and permits a CSS `--uiify-aspect-ratio` override; an explicit ratio writes that property.
 

package/skills/uiify/references/elements/breadcrumb.md

@@ -15,6 +15,7 @@ Do not use breadcrumbs as the only way to navigate or show unrelated destination
 ## Structure
 
 Use BreadcrumbRoot, BreadcrumbList, BreadcrumbItem, and BreadcrumbLink inside a labelled navigation landmark. Keep items in ancestor order, use current to identify the current page, and use links for ancestors.
+When BreadcrumbList renders its data-driven `items`, use `slotProps.item` and `slotProps.link` for each generated item and link. Address a specific item with `byItemValue[item.key]`. Collapsed lists also accept `slotProps.ellipsisItem`, `ellipsis`, `ellipsisTrigger`, and `ellipsisContent`. The standalone `Breadcrumb.Ellipsis` uses `slotProps.item` and `slotProps.ellipsis`.
 
 ## Responsive
 

package/skills/uiify/references/elements/checkbox.md

@@ -14,7 +14,7 @@ Use a radio group when exactly one option can be selected. Use a switch for a si
 
 ## Structure
 
-Use the documented Checkbox with a stable id and a visible, descriptive label. For form submission, provide its native `name` and `value`. Group related choices in a fieldset with a legend; use the indeterminate state only for an aggregate that represents mixed child selections.
+Use the documented Checkbox with a stable id and a visible, descriptive label. For form submission, provide its native `name` and `value`. Use `slotProps.input` and `slotProps.label` to style or annotate the generated native input and wrapping label. The top-level `className` remains a label shortcut. Group related choices in a fieldset with a legend; use the indeterminate state only for an aggregate that represents mixed child selections.
 
 ## Responsive
 

package/skills/uiify/references/elements/color-picker.md

@@ -14,7 +14,7 @@ Do not use color as the only way to choose or identify a required category. Use
 
 ## Structure
 
-Use the documented ColorPicker with its required visible label. Choose the documented colorSpace and alpha options to match the stored value; show the current color value as text as well as a swatch.
+Use the documented ColorPicker with its required visible label. Choose the documented colorSpace and alpha options to match the stored value; show the current color value as text as well as a swatch. The component's `slotProps.field`, `slotProps.label`, `slotProps.surface`, `slotProps.control`, and `slotProps.input` accept native props for the generated field, label, swatch surface, value control, and native picker input respectively. The component's own `className` and `style` still target the field.
 
 ## Responsive
 

package/skills/uiify/references/elements/combobox.md

@@ -14,7 +14,7 @@ Do not use a combobox when people need to compare all options at once or when ty
 
 ## Structure
 
-`Combobox.Root` receives `items` with `label` and `value`. Give `Combobox.Input` a visible associated label or accessible name. Render filtered items with `Combobox.Content` and `Combobox.Item`; render `Combobox.Empty` only when the filtered list is empty. The multi-value mode uses `multiple` and supports tags.
+`Combobox.Root` receives `items` with `label` and `value`. Give `Combobox.Input` a visible associated label or accessible name. Render filtered items with `Combobox.Content` and `Combobox.Item`; render `Combobox.Empty` only when the filtered list is empty. The multi-value mode uses `multiple` and supports tags. Style the generated tags and remove buttons, or add native attributes such as `data-testid`, with `Combobox.Tags` `slotProps`; address repeated nodes by selected item value.
 
 ## Responsive
 

package/skills/uiify/references/elements/context-menu.md

@@ -14,7 +14,7 @@ Do not make right-click the only way to reach an action, or use this for general
 
 ## Structure
 
-Wrap the object with `ContextMenu` Root, Trigger, Content, and concise action items. Use checkbox/radio items only for state choices and provide clear labels that make sense without pointer coordinates.
+Wrap the object with `ContextMenu` Root, Trigger, Content, and concise action items. Use checkbox/radio items only for state choices and provide clear labels that make sense without pointer coordinates. `Root.id` sets the popup id. Use `slotProps.virtualAnchor` to pass classes, styles, refs, events, and native attributes to the generated anchor; the component retains ownership of its position and accessibility markers.
 
 ## Responsive
 

package/skills/uiify/references/elements/dropdown-menu.md

@@ -14,7 +14,7 @@ Do not use a menu for site navigation; use ordinary links and navigation landmar
 
 ## Structure
 
-Compose `DropdownMenu` Root, Trigger, Content, and named items. Give the trigger an action-oriented accessible name; group related actions with labels and separators, and use checkbox/radio items only for their matching state model.
+Compose `DropdownMenu` Root, Trigger, Content, and named items. Give the trigger an action-oriented accessible name; group related actions with labels and separators, and use checkbox/radio items only for their matching state model. `Root.id` sets the popup id and trigger relationship. `Bar` forwards native div props to its menubar element.
 
 ## Responsive
 

package/skills/uiify/references/elements/field.md

@@ -22,7 +22,7 @@ Keep labels and help text close to the control at narrow widths. Let long instru
 
 ## States
 
-Native required validation works without JavaScript. For application validation, set `invalid` on Root and Control and render `Field.Error` with the same state after validation. Keep `Field.Description` mounted alongside the conditional Error: Control always references its derived description ID. Parts own their IDs and Control's ARIA relationships; omit manual `id`/`aria-describedby` overrides. The error is included while invalid.
+Native required validation works without JavaScript. For application validation, set `invalid` on Root and Control and render `Field.Error` with the same state after validation. Keep `Field.Description` mounted alongside the conditional Error: Control always references its derived description ID. Parts write their IDs and Control's ARIA relationships by default; overriding `id`/`aria-describedby` breaks those links, so omit manual overrides. The error is included while invalid.
 
 ## Verify
 

package/skills/uiify/references/elements/form-error-summary.md

@@ -16,6 +16,11 @@ Do not expect this static component to validate fields, announce dynamic updates
 
 `FormErrorSummary` takes required `title: ReactNode` and `errors: readonly { href: string; message: ReactNode }[]`. It renders a `section`, heading, and list of links. Name the section with native `aria-label` when useful. Each `href` must target a unique field ID in the same form instance. Use the published `Input` or `Field.Control` for matching fields, and associate matching inline error text with the control using caller-owned `aria-describedby`. An empty error array renders `null`.
 
+Use `slotProps.title` and `slotProps.list` for the heading and list. Use
+`slotProps.item` and `slotProps.link` for each error row and link. Repeated
+slots accept common native props or `byItemValue` keyed by each error's
+unique `href`; the component keeps the field link target and anatomy markers.
+
 ## Responsive
 
 Keep error links readable and allow long messages to wrap. Preserve the document order between the summary and form.

package/skills/uiify/references/elements/pagination.md

@@ -16,7 +16,7 @@ Do not paginate a small result set that is easier to scan as one list, or imply
 
 ## Structure
 
-Use Pagination.Root with a specific navigation label and the documented count. Provide descriptive names for previous/next controls, expose the current page with selected, and use getPageHref when pages are navigable URLs.
+Use Pagination.Root with a specific navigation label and the documented count. Provide descriptive names for previous/next controls, expose the current page with selected, and use getPageHref when pages are navigable URLs. To style or annotate its generated markup, pass native props through `slotProps.list`, `item`, `link`, `control`, and `ellipsis`; repeated parts use `byItemValue` keys such as `page:5`, `previous`, or `ellipsis:2`.
 
 ## Responsive
 

package/skills/uiify/references/elements/radio-group.md

@@ -15,6 +15,7 @@ Use checkboxes for independent options and a select when the choice set is too l
 ## Structure
 
 Use RadioGroup with a stable id, a name, and items that each have a value and descriptive label. Give the group a visible legend or an accessible name that describes the question.
+Style generated item wrappers, radios, and labels with `slotProps.item`, `slotProps.input`, and `slotProps.label`. Use `byItemValue` when one option needs its own props or `data-testid`.
 
 ## Responsive
 

package/skills/uiify/references/elements/rating.md

@@ -14,7 +14,7 @@ Do not use stars for a binary choice or as the only way to report a detailed eva
 
 ## Structure
 
-Use the documented Rating with a stable id, a group name in aria-label, and an appropriate max. Each radio option exposes its star count as text; pair the scale with visible instructions that explain what low and high values mean.
+Use the documented Rating with a stable id, a group name in aria-label, and an appropriate max. Each radio option exposes its star count as text; pair the scale with visible instructions that explain what low and high values mean. Use slotProps.item, slotProps.input, and slotProps.label to style or add native attributes to generated parts; byItemValue targets the item's numeric string, such as "3".
 
 ## Responsive
 

package/skills/uiify/references/elements/segmented-control.md

@@ -15,6 +15,7 @@ Use ordinary links for navigation and Tabs only when each choice opens a corresp
 ## Structure
 
 Use SegmentedControl with a stable id and items that each have a value and label. Give the group an accessible name, and show the selected option with the component's native radio semantics.
+Style generated item wrappers, radios, and labels with `slotProps.item`, `slotProps.input`, and `slotProps.label`. Use `byItemValue` when one segment needs its own props or `data-testid`.
 
 ## Responsive
 

package/skills/uiify/references/elements/spinner.md

@@ -22,7 +22,7 @@ Keep the indicator near the task it describes, reserve enough space to prevent l
 
 ## States
 
-The delay prop writes a delayed state marker; shipped CSS disables animation in that state, but does not hide the element or schedule a timer. The component supports sm/md/lg sizes and center/fixed/absolute alignment. Motion respects reduced-motion preferences in UIify styles.
+The value prop (0–100) renders a static arc with role=progressbar instead of the animation. The delay prop writes a delayed state marker; shipped CSS disables animation in that state, but does not hide the element or schedule a timer. The component supports sm/md/lg sizes and center/fixed/absolute alignment. Motion respects reduced-motion preferences in UIify styles.
 
 ## Verify
 

package/skills/uiify/references/elements/table.md

@@ -22,7 +22,7 @@ Preserve the table's row and column relationships. If columns need horizontal sc
 
 ## States
 
-Distinguish an empty dataset from a filter with no matches. Communicate loading and errors, and keep selection or sort state visible when requested. The native table is Tier 0; row selection, sorting, and expansion require the `/client` entry.
+Distinguish an empty dataset from a filter with no matches. Communicate loading and errors, and keep selection or sort state visible when requested. The native table is Tier 0; row selection, sorting, and expansion require the `/client` entry. In that entry, use `TableClient.ColumnHeader.slotProps.sortButton` for the sortable control and `slotProps.input/label` on `TableClient.SelectAll` or `TableClient.RowSelect` for generated checkbox parts.
 
 ## Verify
 

package/skills/uiify/references/elements/tabs.md

@@ -14,7 +14,7 @@ Use links for navigation, a stepper for sequential tasks, and side-by-side conte
 
 ## Structure
 
-UIify `Tabs` takes an `id`, `items` with a `value`, `label`, and `panel`, and an optional `defaultValue` and `orientation`. It renders a native radio group with one label and panel per item; it does not implement the ARIA tablist pattern. Set `defaultValue` so a useful panel is selected initially. Keep labels short and make each panel's content match its label.
+UIify `Tabs` takes an `id`, `items` with a `value`, `label`, and `panel`, and an optional `defaultValue` and `orientation`. It renders a native radio group with one label and panel per item; it does not implement the ARIA tablist pattern. Use `slotProps.item`, `slotProps.input`, `slotProps.trigger`, and `slotProps.panel` to pass native props, `className`, `style`, refs, events or `data-*` to generated nodes; `slotProps.append` targets the wrapper around optional appended content. Repeated slots support `byItemValue`. Put Tailwind utilities on the slot they style. For custom markup, compose public `Choice.Group` and `Choice.Item` parts directly. Set `defaultValue` so a useful panel is selected initially. Keep labels short and make each panel's content match its label.
 
 ## Responsive
 

package/skills/uiify/references/elements/tags-input.md

@@ -14,7 +14,7 @@ Use a select or checkbox group for a fixed choice set. Do not add suggestion-lis
 
 ## Structure
 
-Use TagsInput.Root with the documented List, Tag, TagRemove, and Input parts. Give the text input a clear accessible name and keep each remove control adjacent to its tag. UIify currently names each one “Remove tag”; verify that the tag context is announced when moving among removal controls.
+Use TagsInput.Root with the documented List, Tag, TagRemove, and Input parts. Root, List and TagRemove accept native DOM props. List's generated tag entries accept `slotProps.tag`, addressed by list index through `byItemIndex`; its generated input wrapper accepts `slotProps.input`. Give the text input a clear accessible name and keep each remove control adjacent to its tag. UIify currently names each one “Remove tag”; verify that the tag context is announced when moving among removal controls.
 
 ## Responsive
 

package/skills/uiify/references/elements/toast.md

@@ -15,6 +15,7 @@ Do not use a timed toast for errors that require correction, critical informatio
 ## Structure
 
 Place a live `ToastViewport` beside the client provider and enqueue a concise title/description. Include an explicit close control; add one short action only when undo or a direct follow-up is useful.
+Style generated queue nodes with `Toast.Viewport`'s `slotProps` (`item`, `title`, `description`, `action`, `close`). Repeated slots accept `byItemValue`, keyed by the toast record id. Configure the provider's generated polite and assertive announcement elements with `Toast.Provider`'s `slotProps` (`politeLiveRegion`, `assertiveLiveRegion`).
 
 ## Responsive
 

package/skills/uiify/references/elements/toggle-group.md

@@ -15,6 +15,7 @@ Use ordinary links for navigation, Tabs for switching associated panels, and che
 ## Structure
 
 Use ToggleGroup with a stable id, a group name, and items with values and labels. Set type to single for one choice or multiple for independent choices.
+Style generated item wrappers, inputs, and labels with `slotProps.item`, `slotProps.input`, and `slotProps.label`. Use `byItemValue` when one toggle needs its own props or `data-testid`.
 
 ## Responsive
 

package/skills/uiify/references/elements/toggle.md

@@ -15,6 +15,7 @@ Use a switch for a persistent on/off setting and ordinary buttons for one-time a
 ## Structure
 
 Use the documented Toggle with its required id and label. It is backed by a native checkbox; keep the label stable so the checked state conveys the change.
+Use `defaultPressed` for browser-owned state that must keep working without JavaScript. For React-controlled state, pass `pressed` together with `onPressedChange`; update `pressed` from that callback so the input stays in sync with the caller.
 
 ## Responsive