themelia-ui 1.0.0

package/.agents/skills/themelia-ui/references/components/base--date-pickers.md

@@ -0,0 +1,401 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `base/date-pickers`
+
+The user picks a date, range, month or time from a calendar surface.
+
+## Selection
+
+- **Use when:** The user picks a date, range, month or time from a calendar surface.
+- **Avoid when:** The date is typed as text, or you are only displaying a date.
+- **Consider instead:** `base/value-inputs`, `primitives`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { Calendar } from "themelia-ui/base/date-pickers"
+import "themelia-ui/base/date-pickers.css"
+```
+
+## Composition
+
+This family composes `base/buttons`, `base/display`, `base/popover`, `base/text-inputs`, `base/typography`.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `Calendar`
+
+Kind: callable.
+
+```text
+({ strings, mode, value, onValueChange, month: monthProp, onMonthChange, numberOfMonths, weekStartsOn, className, ...constraints }: CalendarProps) => import("react").JSX.Element
+```
+
+### `CalendarProps`
+
+Kind: interface.
+
+Extends: `CalendarConstraints`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `strings` | no | `Partial<CalendarStrings>` |
+| `mode` | no | `DateSelectionMode` |
+| `value` | no | `Date \| Date[] \| DateRangeValue` |
+| `onValueChange` | no | `(value: Date \| Date[] \| DateRangeValue \| undefined) => void` |
+| `month` | no | `Date` |
+| `onMonthChange` | no | `(month: Date) => void` |
+| `numberOfMonths` | no | `number` |
+| `weekStartsOn` | no | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
+| `className` | no | `string` |
+
+### `CalendarStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `previousMonth` | yes | `string` |
+| `nextMonth` | yes | `string` |
+| `chooseMonth` | yes | `string` |
+| `previousYear` | yes | `string` |
+| `nextYear` | yes | `string` |
+
+### `createRangePresets`
+
+Kind: callable.
+
+```text
+({ strings, weekStartsOn, now, }?: RangePresetOptions) => DatePreset[]
+```
+
+### `DatePicker`
+
+Kind: callable.
+
+```text
+({ id, mode, value, onValueChange, displayFormat, placeholder, disabled, invalid, clearable, strings, presets, numberOfMonths, closeOnSelect, header, footer, className, contentClassName, minDate, maxDate, disabledDates, ...aria }: DatePickerProps) => import("react").JSX.Element
+```
+
+### `DatePickerFooter`
+
+Kind: callable.
+
+```text
+({ summary, actions, className, children, ...props }: DatePickerFooterProps) => import("react").JSX.Element | null
+```
+
+### `DatePickerFooterProps`
+
+Kind: interface.
+
+Extends: `ComponentProps<"div">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `summary` | no | `ReactNode` |
+| `actions` | no | `ReactNode` |
+
+### `DatePickerHeader`
+
+Kind: callable.
+
+```text
+({ title, description, action, className, children, ...props }: DatePickerHeaderProps) => import("react").JSX.Element | null
+```
+
+### `DatePickerHeaderProps`
+
+Kind: interface.
+
+Extends: `Omit<ComponentProps<"div">, "title">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | no | `ReactNode` |
+| `description` | no | `ReactNode` |
+| `action` | no | `ReactNode` |
+
+### `DatePickerProps`
+
+Kind: interface.
+
+Extends: `CalendarConstraints`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `id` | no | `string` |
+| `mode` | no | `DateSelectionMode` |
+| `value` | no | `Date \| Date[] \| DateRangeValue` |
+| `onValueChange` | no | `(value: Date \| Date[] \| DateRangeValue \| undefined) => void` |
+| `displayFormat` | no | `string` |
+| `placeholder` | no | `string` |
+| `disabled` | no | `boolean` |
+| `invalid` | no | `boolean` |
+| `clearable` | no | `boolean` |
+| `strings` | no | `Partial<DatePickerStrings>` |
+| `presets` | no | `DatePreset[]` |
+| `numberOfMonths` | no | `number` |
+| `closeOnSelect` | no | `boolean` |
+| `header` | no | `ReactNode` |
+| `footer` | no | `ReactNode` |
+| `className` | no | `string` |
+| `contentClassName` | no | `string` |
+| `"aria-label"` | no | `string` |
+| `"aria-labelledby"` | no | `string` |
+| `"aria-describedby"` | no | `string` |
+
+### `DatePickerStrings`
+
+Kind: interface.
+
+Extends: `CalendarStrings`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `clear` | yes | `string` |
+| `placeholder` | yes | `string` |
+
+### `defaultCalendarStrings`
+
+Kind: const.
+
+```text
+CalendarStrings
+```
+
+### `defaultDatePickerStrings`
+
+Kind: const.
+
+```text
+DatePickerStrings
+```
+
+### `defaultRangePresetStrings`
+
+Kind: const.
+
+```text
+RangePresetStrings
+```
+
+### `defaultTimePickerStrings`
+
+Kind: const.
+
+```text
+TimePickerStrings
+```
+
+### `MonthYearPicker`
+
+Kind: callable.
+
+```text
+({ value, onValueChange, minYear, maxYear, disabledMonths, strings, className, ...props }: MonthYearPickerProps) => import("react").JSX.Element
+```
+
+### `MonthYearPickerProps`
+
+Kind: interface.
+
+Extends: `Omit<ComponentProps<"div">, "onChange" | "value">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `value` | no | `MonthYearValue` |
+| `onValueChange` | no | `(value: MonthYearValue) => void` |
+| `minYear` | no | `number` |
+| `maxYear` | no | `number` |
+| `disabledMonths` | no | `(value: MonthYearValue) => boolean` |
+| `strings` | no | `Partial<CalendarStrings>` |
+
+### `MonthYearValue`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `month` | yes | `number` |
+| `year` | yes | `number` |
+
+### `MultipleDatePicker`
+
+Kind: const.
+
+```text
+import('react').ForwardRefExoticComponent<MultipleDatePickerProps & import('react').RefAttributes<HTMLButtonElement>>
+```
+
+### `MultipleDatePickerProps`
+
+Kind: interface.
+
+Extends: `Base`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `value` | no | `Date[]` |
+| `onValueChange` | no | `(value: Date[]) => void` |
+
+### `RANGE_PRESETS`
+
+Kind: const.
+
+```text
+DatePreset[]
+```
+
+### `RangeDatePicker`
+
+Kind: const.
+
+```text
+import('react').ForwardRefExoticComponent<RangeDatePickerProps & import('react').RefAttributes<HTMLButtonElement>>
+```
+
+### `RangeDatePickerProps`
+
+Kind: interface.
+
+Extends: `Base`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `value` | no | `DateRangeValue` |
+| `onValueChange` | no | `(value: DateRangeValue) => void` |
+
+### `RangePresetOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `strings` | no | `Partial<RangePresetStrings>` |
+| `weekStartsOn` | no | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
+| `now` | no | `() => Date` |
+
+### `RangePresetStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `last7Days` | yes | `string` |
+| `last30Days` | yes | `string` |
+| `thisWeek` | yes | `string` |
+| `thisMonth` | yes | `string` |
+| `lastMonth` | yes | `string` |
+| `thisYear` | yes | `string` |
+| `lastYear` | yes | `string` |
+
+### `SingleDatePicker`
+
+Kind: const.
+
+```text
+import('react').ForwardRefExoticComponent<SingleDatePickerProps & import('react').RefAttributes<HTMLButtonElement>>
+```
+
+### `SingleDatePickerProps`
+
+Kind: interface.
+
+Extends: `Base`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `value` | no | `Date` |
+| `onValueChange` | no | `(value: Date \| undefined) => void` |
+
+### `TimePicker`
+
+Kind: callable.
+
+```text
+({ id, value, onValueChange, withSeconds, minuteStep, disabled, invalid, className, strings, }: TimePickerProps) => import("react").JSX.Element
+```
+
+### `TimePickerProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `id` | no | `string` |
+| `value` | no | `TimeValue` |
+| `onValueChange` | no | `(value: TimeValue) => void` |
+| `withSeconds` | no | `boolean` |
+| `minuteStep` | no | `number` |
+| `disabled` | no | `boolean` |
+| `invalid` | no | `boolean` |
+| `className` | no | `string` |
+| `strings` | no | `Partial<TimePickerStrings>` |
+
+### `TimePickerStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `label` | yes | `string` |
+| `hours` | yes | `string` |
+| `minutes` | yes | `string` |
+| `seconds` | yes | `string` |
+
+### `TimeValue`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `hours` | yes | `number` |
+| `minutes` | yes | `number` |
+| `seconds` | no | `number` |
+
+## Preview recipes
+
+Preview route: Calendar — `/calendar`
+
+### Calendar
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Calendar mode="range" value={range} onValueChange={setRange} numberOfMonths={2} />
+```
+
+### Another language, another week
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { de } from "date-fns/locale"
+
+<UIProvider config={{ dates: { locale: de, weekStartsOn: 0 } }}>
+  <Calendar mode="single" />
+</UIProvider>
+```
+
+### DatePicker
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<DatePicker value={day} onValueChange={setDay} clearable />
+<DatePicker mode="range" value={range} onValueChange={setRange} presets={RANGE_PRESETS} />
+```
+
+### One picker, four fixed modes
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<SingleDatePicker value={day} onValueChange={setDay} />
+<RangeDatePicker value={range} onValueChange={setRange} />
+<MonthYearPicker value={month} onValueChange={setMonth} />
+```
+
+### TimePicker and DateTimeInput
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<TimePicker value={time} onValueChange={setTime} minuteStep={15} />
+<DateTimeInput value={iso} onValueChange={setIso} />
+```

package/.agents/skills/themelia-ui/references/components/base--dialog.md

@@ -0,0 +1,164 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `base/dialog`
+
+Documenting or extending the dialog anatomy itself inside base.
+
+## Selection
+
+- **Use when:** Documenting or extending the dialog anatomy itself inside base.
+- **Avoid when:** You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.
+- **Consider instead:** `features/overlays`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { Dialog } from "themelia-ui/base/dialog"
+import "themelia-ui/base/dialog.css"
+```
+
+## Composition
+
+This family composes `base/overlay`.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `Dialog`
+
+Kind: const.
+
+```text
+typeof Overlay
+```
+
+### `DialogBody`
+
+Kind: const.
+
+```text
+React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>
+```
+
+### `DialogClose`
+
+Kind: const.
+
+```text
+typeof OverlayClose
+```
+
+### `DialogContent`
+
+Kind: callable.
+
+```text
+({ className, ...props }: DialogContentProps) => React.JSX.Element
+```
+
+### `DialogContentProps`
+
+Kind: type.
+
+```text
+Omit<OverlayContentProps, "placement"> & Omit<React.ComponentProps<"dialog">, "children" | "className" | "title">
+```
+
+### `DialogDescription`
+
+Kind: const.
+
+```text
+React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>
+```
+
+### `DialogDismissArea`
+
+Kind: const.
+
+```text
+typeof OverlayDismissArea
+```
+
+### `DialogFooter`
+
+Kind: callable.
+
+```text
+({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
+```
+
+### `DialogHeader`
+
+Kind: callable.
+
+```text
+({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
+```
+
+### `DialogProps`
+
+Kind: type.
+
+```text
+OverlayRootProps
+```
+
+### `DialogTitle`
+
+Kind: const.
+
+```text
+React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>
+```
+
+### `DialogTrigger`
+
+Kind: const.
+
+```text
+typeof OverlayTrigger
+```
+
+## Preview recipes
+
+Preview route: Dialog — `/dialog`
+
+### Dialog
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Dialog>
+  <DialogTrigger render={<Button>Open</Button>} />
+  <DialogContent>
+    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
+    <DialogBody>…</DialogBody>
+    <DialogFooter>
+      <DialogDismissArea>
+        <Button>Cancel</Button><Button>Save</Button>
+      </DialogDismissArea>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+
+{/* or per-action: */}
+<DialogClose render={<Button>Cancel</Button>} />
+```
+
+### Bare surface
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<DialogContent surface="bare" showCloseButton={false}>
+```
+
+### Where focus lands
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+const nameRef = useRef<HTMLInputElement>(null)
+
+<DialogContent initialFocusRef={nameRef}>
+  <Input ref={nameRef} />
+</DialogContent>
+```

package/.agents/skills/themelia-ui/references/components/base--direction.md

@@ -0,0 +1,105 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `base/direction`
+
+A subtree renders right-to-left and its primitives must follow.
+
+## Selection
+
+- **Use when:** A subtree renders right-to-left and its primitives must follow.
+- **Avoid when:** The whole document is RTL and the html element already declares it.
+- **Consider instead:** `ui-provider`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { DirectionProvider } from "themelia-ui/base/direction"
+```
+
+## Composition
+
+This family has no component-family dependencies.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `DirectionProvider`
+
+Kind: callable.
+
+```text
+({ direction, children }: DirectionProviderProps) => React.JSX.Element
+```
+
+### `DirectionProviderProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `direction` | no | `"ltr" \| "rtl"` |
+| `children` | no | `React.ReactNode` |
+
+## Preview recipes
+
+Preview route: Content block — `/content-block`
+
+### Four surfaces
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ContentBlock surface="card" title="Contract" description="…">
+  …
+</ContentBlock>
+```
+
+### flush
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ContentBlock surface="card" flush>
+  <ItemGroup ruled>…</ItemGroup>
+</ContentBlock>
+```
+
+### The header assembles itself
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ContentBlock
+  icon={<TruckIcon />}
+  title="Shipment"
+  titleSuffix={<Badge tone="info">In transit</Badge>}
+  headerEnd={<Button buttonStyle="ghost">Track</Button>}
+/>
+```
+
+### IconBadge
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<IconBadge icon={CreditCardIcon} tone="success" />
+<IconBadge icon={CreditCardIcon} tone="success" shape="circle" solid />
+```
+
+### DateBlock
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<DateBlock date="2026-08-16" />
+```
+
+### PlaceholderPattern
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<PlaceholderPattern style={{ height: "8rem" }} />
+```
+
+### DirectionProvider and Slot
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<DirectionProvider direction="rtl">
+  <Stack>…</Stack>
+</DirectionProvider>
+
+// render is Slot:
+<OverlayTrigger render={<Button>Open</Button>} />
+```