prime-ui-kit 0.2.3 → 0.3.1

package/src/components/color-picker/COMPONENT.md

@@ -0,0 +1,149 @@
+# ColorPicker
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A composite color picker built on **react-aria-components**: it keeps a shared `Color` value across a 2D area, channel sliders, optional preset swatches, a standalone hex field, and a channel strip with an eyedropper control.
+
+- **When to use:** brand, theme, or accent color selection with a visual preview; editor-style fill, stroke, or text color; chart or legend colors persisted as strings or `Color`; forms where the stored value must stay a CSS-parseable color.
+- **When to use:** one shared `onChange` from many nested controls while the parent holds `value` / `parseColor` state.
+- **When to use:** combining fixed presets (`SwatchPicker`) with free adjustment (area and sliders).
+- **When not to use:** only a hex string is needed and no picker UI adds value — prefer a plain [Input](../input/COMPONENT.md) or another simple field.
+- **When not to use:** the full control surface must stay inline in a tight layout — mount the panel in an overlay ([Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md), or [Drawer](../drawer/COMPONENT.md)) instead.
+- **When not to use:** every user must rely on the system eyedropper — without the EyeDropper API the control is non-functional decoration only.
+
+## Composition
+
+- **`ColorPicker.Root`** wraps everything that should share one color value (trigger + panel). Put **`ColorPicker.TriggerSwatch`** on the same root as the panel so the swatch reflects the live color.
+- **Product layouts:** place the interactive surface (area, sliders, swatches, `HexInput`, `ChannelStrip`) inside **`Popover.Content`** (or modal/drawer), with a trigger such as [Button](../button/COMPONENT.md) + `TriggerSwatch`. `HexInput`-only flows still belong under a trigger if you want a compact field.
+- **`ColorPicker.FormatProvider`** is required for **`FormatSelect`** and **`ChannelStrip`** (the strip calls into format context; without the provider it throws at runtime). `FormatSelect` renders nothing if mounted outside `FormatProvider`.
+- **Typical panel order:** `FormatProvider` → optional `FormatSelect` → `Area` with `AreaThumb` → one or more `Slider` trees (`SliderMeta` optional, then `SliderTrack` → `Thumb`) → `ChannelStrip` (`pipetteIcon` required) → optional `SwatchPicker` with `SwatchPickerItem` children each wrapping `Swatch` → optional `HexInput` or RAC **`Field`** for custom channel inputs.
+- **`EyeDropperButton`** is used inside `ChannelStrip` by default; it can also be composed separately under the same `Root` if needed.
+- **`Output`** is the RAC slider value readout; the kit wires it inside **`SliderMeta`** (label + value row).
+
+### Minimal example
+
+```tsx
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+
+export function MinimalColorField() {
+  return (
+    <ColorPicker.Root defaultValue="#3b82f6">
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Color
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+            <ColorPicker.FormatProvider>
+              <ColorPicker.FormatSelect />
+              <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+                <ColorPicker.AreaThumb />
+              </ColorPicker.Area>
+              <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+            </ColorPicker.FormatProvider>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}
+```
+
+## Rules
+
+- Use **controlled** mode with `value` and `onChange` when the parent owns color state; use **`defaultValue`** for uncontrolled usage. Value types follow RAC: `string | Color`; `onChange` receives a **`Color`** instance.
+- Import **`Color`** for typing from **`react-aria-components`** (or use the kit re-export type **`ColorPickerColorValue`**). Use **`parseColor`** from **`prime-ui-kit`** to turn strings into `Color` for `useState` initial values.
+- **`children`** on `Root` may be a render function; it receives **`ColorPickerRenderProps`** (`{ color }`) from RAC.
+- There is **no** single `isDisabled` on `Root` — disable **`Area`**, **`Slider`**, **`SwatchPickerItem`**, or wrap groups in a disabled **`fieldset`** when appropriate.
+- **`ChannelStrip`** must receive **`pipetteIcon`** (usually [Button.Icon](../button/COMPONENT.md) wrapping an icon). Pass **`aria-label`** on **`EyeDropperButton`** if you use it standalone (default label is Russian “Пипетка” in code).
+- If **`window.EyeDropper`** is missing, the eyedropper renders as a disabled control with **`aria-hidden`** and **`tabIndex={-1}`** — do not rely on it as the only way to set a color.
+- **`FormatProvider`** owns HSL / RGB / hex strip mode (`defaultFormat`: `"hsl"` \| `"rgb"` \| `"hex"`). **`FormatSelect`** only appears when inside that provider.
+- **`HexInput`** and strip hex editing **revert** invalid input to the last committed color on **blur** or **Enter**. Channel cells in the strip **ignore** non-numeric input on commit (no color change).
+- **`TriggerSwatch`** is **`aria-hidden`**; expose the purpose on the trigger (visible button text or `aria-label` on the control).
+- **`SwatchPicker`** needs an accessible name (**`aria-label`** or an associated label).
+- Sliders use a **fixed** visual size tier (`data-size="m"` on the kit `Slider`); only **`HexInput`** exposes the kit **`size`** axis (`s` \| `m` \| `l` \| `xl`).
+- For **`SwatchPicker`** selection semantics and layout, follow RAC props (`value` / `defaultValue` / `onChange`, `layout`, etc.).
+
+## API
+
+### ColorPicker.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string \| Color` | — | No | Controlled color value |
+| defaultValue | `string \| Color` | — | No | Initial color when uncontrolled |
+| onChange | `(color: Color) => void` | — | No | Fires when any nested control changes the color |
+| children | `ReactNode \| (props: ColorPickerRenderProps) => ReactNode` | — | Yes | Pickers, triggers, and panels sharing state |
+| slot | `string \| null` | — | No | Slotted context name (RAC `SlotProps`) |
+| className | `string \| (values) => string` | — | No | Root element classes (RAC render props) |
+| …rest | RAC + DOM | — | No | Other **`ColorPickerRootProps`** / `AriaColorPickerProps` from react-aria-components |
+
+### ColorPicker.FormatProvider
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `ReactNode` | — | Yes | subtree that may use `FormatSelect` and `ChannelStrip` |
+| defaultFormat | `"hsl" \| "rgb" \| "hex"` | `"hsl"` | No | Initial format for the strip and format select |
+
+### ColorPicker.FormatSelect
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the wrapper around the kit [Select](../select/COMPONENT.md) |
+
+Renders `null` when not under `FormatProvider`.
+
+### ColorPicker.ChannelStrip
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| pipetteIcon | `ReactNode` | — | Yes | Icon for the embedded eyedropper ([Button.Icon](../button/COMPONENT.md) + icon) |
+| className | `string` | — | No | Class on the strip container |
+
+### ColorPicker.HexInput
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Passed to kit [Input](../input/COMPONENT.md) |
+| label | `ReactNode` | `"Hex"` | No | Field label |
+| className | `string` | — | No | Class on `Input.Root` |
+
+### ColorPicker.TriggerSwatch
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the preview square |
+
+### ColorPicker.SliderMeta
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| label | `ReactNode` | — | Yes | Left label; current channel value on the right via `Output` |
+
+### ColorPicker.EyeDropperButton
+
+Same props as **`Button.Root`** from the kit except **`variant`**, **`mode`**, and **`size`** are fixed (`neutral`, `stroke`, `m`). Forwarded ref: **`HTMLButtonElement`**. Children are usually **`Button.Icon`**.
+
+### ColorPicker.Area, AreaThumb, Slider, SliderTrack, Thumb, Output, Field, SwatchPicker, SwatchPickerItem, Swatch
+
+Styled wrappers around the matching **react-aria-components** primitives. Use their RAC prop surfaces (e.g. **`Area`**: `colorSpace`, `xChannel`, `yChannel`, `isDisabled`; **`Slider`**: `channel`, optional `colorSpace`, `orientation`, `isDisabled`; **`SwatchPicker`** / **`SwatchPickerItem`**: selection and `color` on items; **`Field`**: RAC `ColorField` props). **`Swatch`** and **`SliderTrack`** add checkerboard layering for transparency in the kit styles.
+
+### `parseColor(value: string): Color`
+
+Parses a CSS color string into a **`Color`**. **Throws** if the string cannot be parsed (RAC / `@react-stately/color` behavior).
+
+Exported types from this module include **`ColorPickerRootProps`**, **`ColorPickerHexInputProps`**, **`ColorPickerFormatProviderProps`**, **`ColorPickerTriggerSwatchProps`**, **`ColorValueFormat`**, **`ColorPickerRenderProps`**, and **`ColorPickerColorValue`** (alias of **`Color`**).
+
+## Related
+
+- [Popover](../popover/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [Modal](../modal/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)

package/src/components/command-menu/COMPONENT.md

@@ -0,0 +1,167 @@
+# CommandMenu
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A modal command palette: search field plus a filterable list of actions. Typing narrows visible options; users pick with pointer or keyboard while focus stays on the combobox input.
+
+**When to use**
+
+- **Dense navigation** — jump to sections, records, or actions without opening full menus (dashboards, CRM, admin).
+- **Power-user flows** — one surface for “go to…” and “do…” when labels map cleanly to filter strings and `keywords`.
+- **Keyboard-first desktops** — pair with your own global shortcut; arrow keys, Home, End, and Enter are handled from the search field.
+- **Grouped actions** — optional section headings and optional tag row under the search for scope chips.
+
+**When not to use**
+
+- **Multi-select or bulk pick** — only one active option; no built-in multi-value selection.
+- **Server-only search without a client list** — filtering is synchronous over registered items; huge lists need virtualization or a different pattern.
+- **Non-modal pickers** — use [Dropdown](../dropdown/COMPONENT.md) or [Select](../select/COMPONENT.md) for inline single choice.
+- **Built-in “no results” UX** — empty matches hide groups/items; you supply messaging or empty state markup yourself.
+
+## Composition
+
+- **`CommandMenu.Dialog`** wraps content in [Modal](../modal/COMPONENT.md) (`role="dialog"`) and mounts **`CommandMenuRootProvider`**: search string, active option, and item registry live here. Open state is controlled (`open` / `onOpenChange`) or uncontrolled (`defaultOpen`).
+- **Recommended top order:** optional **`DialogTitle`** / **`DialogDescription`** (same typography shell as modal headings) → **`InputRow`** (optional slots **`leading`** / **`trailing`**) → **`Input`** → optional **`TagSection`** → **`TagSectionLabel`** / **`TagRow`** → **`List`** → optional **`Footer`** (optional **`FooterKeyBox`** for key hints).
+- **`List`** is the **`listbox`** (`id` wired to the input’s **`aria-controls`**). **`Group`** wraps **`Item`** nodes; groups with no visible items get **`hidden`**. **`Item`** registers for filtering and keyboard activation; put **`ItemIcon`** and label text inside **`Item`**.
+- **`Input`** may sit directly under **`Dialog`** without **`InputRow`** (valid markup); **`InputRow`** is the styled search row when you need leading/trailing slots or density.
+
+### Minimal example
+
+```tsx
+import * as React from "react";
+import { CommandMenu } from "prime-ui-kit";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <CommandMenu.Dialog open={open} onOpenChange={setOpen}>
+      <CommandMenu.InputRow>
+        <CommandMenu.Input placeholder="Search" aria-label="Search commands" />
+      </CommandMenu.InputRow>
+      <CommandMenu.List>
+        <CommandMenu.Item value="action" onSelect={() => setOpen(false)}>
+          Action
+        </CommandMenu.Item>
+      </CommandMenu.List>
+    </CommandMenu.Dialog>
+  );
+}
+```
+
+## Rules
+
+- **Open state:** **`open`** + **`onOpenChange`** for controlled mode; **`defaultOpen`** (defaults to `false` via `Modal.Root`) for uncontrolled. Escape and overlay click close according to **`closeOnEscape`** and **`closeOnOverlayClick`** (both default `true`).
+- **Search state:** **`Input`** is uncontrolled by default (internal `search` drives filtering). Pass **`value`** / **`onChange`** for controlled input; when **`value`** is set, internal state tracks it via an effect. **`type`** is always **`search`**; **`size`** is not a valid prop on **`Input`**.
+- **Remount reset:** when the dialog content tree mounts, search and active item reset and the input is focused on the next animation frame—do not assume text persists across unmount.
+- **Filtering:** matches run against normalized **`value`** and **`keywords`** together; **`disabled`** items are excluded from matches and keyboard order. **`Item`** **`value`** is required.
+- **Selection:** Enter activates the active option; click and pointer move on an enabled, visible item updates the active option and can fire **`onSelect`**. **`Item`** renders **`type="button"`**; do not rely on **`type`** override.
+- **Panel styling:** **`className`** and **`contentClassName`** merge onto the dialog panel; width/height helpers (e.g. `dialogContentWide`, `dialogContentNarrow`, `dialogContentTight`) live in the component CSS module—import those classes in your app if you need them.
+- **Accessibility:** set **`aria-labelledby`** (and **`DialogTitle`** with a matching **`id`**) or an appropriate **`aria-label`** on the dialog surface; **`Input`** exposes **`role="combobox"`**, **`aria-controls`**, and **`aria-activedescendant`**; **`List`** is **`listbox`**, **`Item`** is **`option`** with **`aria-selected`**. Modal focus trap and scroll lock follow [Modal](../modal/COMPONENT.md) behavior.
+- **FooterKeyBox** wraps [Badge](../badge/COMPONENT.md) (`size="s"`, `color="gray"`); **`tone="muted"`** maps to badge variant **`lighter`**, default maps to **`stroke`**.
+
+## API
+
+### CommandMenu.Dialog
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Palette markup (provider runs inside the panel) |
+| open | `boolean` | — | no | Controlled open state |
+| defaultOpen | `boolean` | `false` | no | Initial open when uncontrolled |
+| onOpenChange | `(open: boolean) => void` | — | no | Open state change callback |
+| closeOnEscape | `boolean` | `true` | no | Close when Escape is pressed |
+| closeOnOverlayClick | `boolean` | `true` | no | Close when the overlay is clicked |
+| overlayClassName | `string` | — | no | Overlay wrapper class |
+| className | `string` | — | no | Panel class (merged with internal dialog layout) |
+| contentClassName | `string` | — | no | Additional panel class merged before `className` |
+| aria-labelledby | `string` | — | no | IDs of labelling element(s) |
+| aria-describedby | `string` | — | no | IDs of description element(s) |
+
+### CommandMenu.DialogTitle / CommandMenu.DialogDescription
+
+| Part | Element | Notes |
+|------|---------|--------|
+| DialogTitle | `h2` | `React.HTMLAttributes<HTMLHeadingElement>` and `className`; same title class stack as modal shell |
+| DialogDescription | `p` | `React.HTMLAttributes<HTMLParagraphElement>` and `className`; same description class stack as modal shell |
+
+### CommandMenu.InputRow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Typically **`Input`** |
+| leading | `React.ReactNode` | — | no | Start slot |
+| trailing | `React.ReactNode` | — | no | End slot |
+| density | `"compact" \| "comfortable"` | `"compact"` | no | Search row vertical padding |
+| className | `string` | — | no | Wrapper class |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Forwarded to the row `div` |
+
+### CommandMenu.Input
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` (and other input value types) | — | no | Controlled value; when set, filters sync from this value |
+| onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | no | Standard change handler; internal state updates when uncontrolled |
+| className | `string` | — | no | Input class |
+| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" \| "type">` | — | no | Other attributes except `size` and `type` (`type` is fixed to `search`) |
+
+### CommandMenu.List
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Groups and/or items |
+| className | `string` | — | no | List surface class |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Passed through to the scroll container root (`role="listbox"`, stable `id` for `aria-controls`) |
+
+### CommandMenu.Group
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| heading | `React.ReactNode` | — | no | Section label (string vs node pick different heading wrappers) |
+| children | `React.ReactNode` | — | no | **`Item`** elements |
+| className | `string` | — | no | Group container class |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Forwarded to the group `div`; container is **`hidden`** when no visible items belong to the group |
+
+### CommandMenu.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | yes | Text participating in filter matching |
+| keywords | `string` | `""` | no | Extra space for matching (not shown as the label) |
+| size | `CommandMenuItemSize` (`"s"` \| `"m"`) | `"s"` | no | Row density / type scale |
+| onSelect | `() => void` | — | no | Called when the item is chosen (click or keyboard activate) |
+| disabled | `boolean` | — | no | Excluded from filtering, visibility, and activation |
+| className | `string` | — | no | Button class |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "onSelect">` | — | no | Other button props; `type` is always `button` |
+
+### CommandMenu.ItemIcon
+
+Polymorphic icon slot: `as` (element type, default `"span"`), `className`, and remaining props forwarded to the chosen component (see `CommandMenuItemIconProps`).
+
+### CommandMenu.TagSection / TagSectionLabel / TagRow
+
+`React.HTMLAttributes<HTMLDivElement>` with `className` and `children` for the optional block between search and list.
+
+### CommandMenu.Footer
+
+`React.HTMLAttributes<HTMLDivElement>` with `className` and `children`; base styles from the module (e.g. footer layout tokens). Optional module classes such as `footerMuted` apply via `className` when you import the stylesheet.
+
+### CommandMenu.FooterKeyBox
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Key cap or icon (rendered inside `Badge.Icon`) |
+| tone | `"default" \| "muted"` | `"default"` | no | Badge visual variant (`stroke` vs `lighter`) |
+| className | `string` | — | no | Extra class on the badge root |
+| …rest | `Omit<React.HTMLAttributes<HTMLDivElement>, "color">` | — | no | Additional attributes except `color` |
+
+## Related
+
+- [Modal](../modal/COMPONENT.md) — dialog shell, focus trap, portal
+- [Badge](../badge/COMPONENT.md) — used inside **`FooterKeyBox`**
+- [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md) — triggers and links outside the palette
+- [Tag](../tag/COMPONENT.md) — common companion for **`TagRow`**
+- [Kbd](../kbd/COMPONENT.md) — shortcut hints in **`InputRow`** trailing slot
+- [Typography](../typography/COMPONENT.md) — titles, hints, footer copy
+- [Dropdown](../dropdown/COMPONENT.md), [Select](../select/COMPONENT.md) — non-modal single-choice lists

package/src/components/data-table/COMPONENT.md

@@ -0,0 +1,113 @@
+# DataTable
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+`DataTable.Root` renders a semantic `<table>` inside a scroll viewport, with optional client-side sorting, classic pagination or infinite-scroll slicing, sticky header and sticky first column, and a footer with row counts (and pagination or infinite-scroll hints).
+
+- **Use** when you need sortable tabular data with built-in pagination or “load more while scrolling” without building table chrome from scratch.
+- **Use** when row hover / column hover highlights or zebra striping should stay consistent with kit tokens via `size` and `ControlSizeProvider`.
+- **Use** when the first column must stay visible during horizontal scroll (`stickyFirstColumn`).
+- **Do not use** when you need arbitrary column pinning, resizable columns, or spreadsheet-style keyboard grid navigation — the table does not implement those.
+- **Do not use** when sorting or filtering must run on the server only without mirroring logic in the parent — sorting is applied in memory to the `rows` you pass; supply pre-sorted data or control `sort` yourself and replace `rows` accordingly.
+- **Do not use** when you need a loading overlay on top of already rendered rows — `loading` only affects the body when there are zero rows to display.
+
+## Composition
+
+- **Public API** — a single compound entry: `DataTable` with `Root` (`DataTableRoot`). There are no other exported subcomponents.
+- **Structure** — `ControlSizeProvider` wraps a root `div` (data attributes for size, dividers, header visibility, stickiness, table width mode, hover highlights, zebra). Inside: `ScrollContainer` viewport → `<table>`, optional `<thead>` (`<th>` per column), `<tbody>` with rows, and an `aria-hidden` sentinel at the bottom when `infiniteScroll` is on (for `IntersectionObserver` or scroll fallback).
+- **Footer** — always shows a “shown range / total” line; if not `infiniteScroll` and `showPagination` and there is more than one page, it renders `Pagination.Root`; in infinite mode it may show a short status when more rows can be revealed or loaded.
+
+### Minimal example
+
+```tsx
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+
+type Row = { id: string };
+
+const columns: DataTableColumn<Row>[] = [{ id: "id", header: "ID", accessor: "id" }];
+const rows: Row[] = [{ id: "1" }];
+
+export function Example() {
+  return <DataTable.Root columns={columns} rows={rows} />;
+}
+```
+
+## Rules
+
+- Pass **`columns`** with unique **`id`** and **`header`** for every column; **`accessor`** (key or function), **`cell`**, **`sortable`**, and the rest are optional.
+- **Sort** — controlled: `sort` + `onSortChange`. Uncontrolled initial order: `defaultSort` (default `null`). Clicking a sortable header cycles **asc → desc → none** for that column; changing sort sets the page to **1** in paginated mode.
+- **Page** — controlled: `page` + `onPageChange`. Uncontrolled: `defaultPage` (default `1`). Page index is clamped when row count changes. Toggling **`infiniteScroll`** resets the visible slice; leaving infinite mode resets page to **1** via internal effect.
+- **Infinite scroll** — set `infiniteScroll`. The visible slice grows by **`infiniteBatchSize`** up to the current **`rows.length`** first; when the slice shows all local rows and **`hasMore`**, **`onLoadMore`** runs when the sentinel intersects (or on near-bottom scroll if `IntersectionObserver` is missing). **`initialVisibleRows`** defaults to **`pageSize`** when omitted.
+- **`loading`** — shows **`loadingText`** in a single spanning row only when there are no displayed rows yet; it does not dim existing rows.
+- **Empty** — when not loading and there are no rows, **`emptyText`** is shown in a spanning row.
+- **Row keys** — provide **`getRowKey`** for stable identity; otherwise React **`key`** falls back to the row **index** (fragile if row order changes).
+- **Localization** — default **`loadingText`**, **`emptyText`**, footer range text, and infinite-scroll hints are **Russian** in the implementation; override with props where needed.
+- **Accessibility** — sortable headers use an inner control pattern inside **`th`** with **`scope="col"`**; sort icons are **`aria-hidden`**. Cells with **`onCellClick`** get **`role="button"`**, **`tabIndex={0}`**, and **Enter / Space**. There is no **`grid`** role or arrow-key cell navigation.
+
+## API
+
+### DataTable.Root
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| columns | `DataTableColumn<Row>[]` | — | Yes | Column definitions |
+| rows | `Row[]` | — | Yes | Data rows (sorted in memory when `sort` applies) |
+| size | `DataTableSize` | `"m"` | No | Row density; forwarded to nested `Pagination` unless `paginationSize` is set |
+| className | `string` | — | No | Class on the outer wrapper |
+| showHeader | `boolean` | `true` | No | Render `<thead>` |
+| stickyHeader | `boolean` | `false` | No | Sticky header row |
+| stickyFirstColumn | `boolean` | `false` | No | Sticky first column (and corner cell when header is sticky) |
+| getRowKey | `(row: Row, index: number) => React.Key` | — | No | Stable row key; default is index |
+| onRowClick | `(row: Row, index: number, event: React.MouseEvent<HTMLTableRowElement>) => void` | — | No | Row click handler |
+| loading | `boolean` | `false` | No | Loading state when no rows are displayed |
+| loadingText | `React.ReactNode` | `"Загрузка данных…"` | No | Message in loading state |
+| emptyText | `React.ReactNode` | `"Нет данных для отображения."` | No | Message when there are no rows |
+| dividerStyle | `DataTableDividerStyle` | `"standard"` | No | Cell border style: `standard`, `dashed`, `dotted`, `none` |
+| sort | `DataTableSortState` | — | No | Controlled sort (`null` or `{ columnId, order }`) |
+| defaultSort | `DataTableSortState` | `null` | No | Initial sort when uncontrolled |
+| onSortChange | `(sort: DataTableSortState) => void` | — | No | Sort change callback |
+| page | `number` | — | No | Controlled current page (1-based) |
+| defaultPage | `number` | `1` | No | Initial page when uncontrolled |
+| onPageChange | `(page: number) => void` | — | No | Page change callback |
+| pageSize | `number` | `10` | No | Rows per page in pagination mode; also default for `initialVisibleRows` in infinite mode |
+| showPagination | `boolean` | `true` | No | Show `Pagination` when not in infinite mode and `totalPages > 1` |
+| siblingCount | `number` | `1` | No | Page window size passed to `Pagination.Root` |
+| paginationSize | `DataTableSize` | — | No | Pagination size; defaults to root `size` |
+| infiniteScroll | `boolean` | `false` | No | Scroll viewport with growing slice / `onLoadMore` |
+| initialVisibleRows | `number` | `pageSize` | No | Initial number of rows shown in infinite mode |
+| infiniteBatchSize | `number` | `20` | No | Rows added per reach-end step before `onLoadMore` |
+| hasMore | `boolean` | `false` | No | Server has more data after current `rows` |
+| loadingMore | `boolean` | `false` | No | While an async `onLoadMore` is in progress |
+| onLoadMore | `() => void \| Promise<void>` | — | No | Fetch next chunk when local slice is exhausted |
+| scrollHeight | `number \| string` | `360` | No | Max height of the scroll viewport in infinite mode |
+| fillWidth | `boolean` | `true` | No | When `true`, table is full container width; extra space is distributed by the browser’s automatic table layout (`table-layout: auto`) from cell content and `width` / `minWidth` / `maxWidth`. When `false`, table width follows content (`max-content`) |
+| highlightRowOnHover | `boolean` | `true` | No | Row hover highlight |
+| highlightColumnOnHover | `boolean` | `false` | No | Column hover highlight (header + cells) |
+| striped | `boolean` | `false` | No | Alternating row backgrounds |
+
+### `DataTableColumn<Row>`
+
+| Field | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| id | `string` | — | Yes | Column id (used for sort state and DOM data attributes) |
+| header | `React.ReactNode` | — | Yes | Header content |
+| accessor | `keyof Row \| ((row: Row) => unknown)` | — | No | Value for default cell text and sort (unless `sortAccessor` / `sortComparator` override) |
+| cell | `(row: Row) => React.ReactNode` | — | No | Custom cell render |
+| sortable | `boolean` | `false` | No | Header toggles sort on click |
+| sortAccessor | `(row: Row) => unknown` | — | No | Value used for sorting (and default sort comparison) instead of `accessor` |
+| sortComparator | `(a: Row, b: Row, order: DataTableOrder) => number` | — | No | Custom comparator; when set, default primitive compare is not used |
+| align | `DataTableCellAlign` | `"start"` | No | `start`, `center`, or `end` |
+| width | `string` | — | No | Column width on `th` / `td` (CSS `width`) |
+| minWidth | `string` | — | No | Minimum column width on `th` / `td` |
+| maxWidth | `string` | — | No | Maximum column width on `th` / `td` |
+| onHeaderClick | `(event: React.MouseEvent<HTMLTableCellElement>) => void` | — | No | Fires on header click before sort handling |
+| onCellClick | `(row: Row, event: React.MouseEvent<HTMLTableCellElement> \| React.KeyboardEvent<HTMLTableCellElement>) => void` | — | No | Makes the cell focusable and keyboard-activable |
+
+Exported types: `DataTableSortState`, `DataTableOrder`, `DataTableSize`, `DataTableCellAlign`, `DataTableDividerStyle`, `DataTableRootProps`, `DataTableColumn`.
+
+## Related
+
+- [Pagination](../pagination/COMPONENT.md) — used under the table for page navigation.
+- [LinkButton](../link-button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Tag](../tag/COMPONENT.md) — common cell content; they pick up size from the table’s `ControlSizeProvider` unless overridden.

package/src/components/datepicker/COMPONENT.md

@@ -0,0 +1,137 @@
+# Datepicker
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Composite pieces for picking a calendar date or range: a size-aware shell, a day grid built on react-day-picker with kit styling, optional quick presets, optional time inputs, and a caption-sized text wrapper. Pass `locale` and formatting from **date-fns** (or compatible) so labels match your UI language.
+
+- **When to use** — booking, scheduling, or any task where users choose one day or a from–to range from a calendar grid.
+- **When to use** — filters and reports that pair the grid with quick presets and optional time fields in the same shell.
+- **When to use** — forms that need a short caption (`Datepicker.Value`) tied to picker scale and tone.
+- **When not to use** — free-text or partial dates (use a plain or masked [Input](../input/COMPONENT.md) instead).
+- **When not to use** — always-visible full calendars as default page chrome; open the shell from a trigger in [Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md), or [Drawer](../drawer/COMPONENT.md).
+- **When not to use** — month- or year-only picking without days (use a slimmer control or native inputs).
+
+## Composition
+
+- **`Datepicker.Shell`** — Root wrapper: sets `DatepickerSize` context, owns `requestedMonth` / `requestMonth` for syncing the grid month when presets fire. Optional **`presets`** renders a bottom row after **`children`**.
+- **`Datepicker.Calendar`** — Must live under `Shell` (directly or nested) so `size` context resolves. Forwards **react-day-picker** `DayPicker` props; kit adds `responsiveMonths`, `responsiveBreakpoints`, and `size`.
+- **`Datepicker.Presets`** — Optional; usually passed as `Shell`’s `presets` prop. Calls `requestMonth` when a preset is chosen so the visible month follows the selection.
+- **`Datepicker.Time`** — Optional; place as a child of `Shell` (e.g. under or beside `Calendar`). Single mode merges time into one `Date`; range mode uses `from` / `to` and separate change handlers.
+- **`Datepicker.Value`** — Optional caption: `Typography.Root` with picker-scale typography; default `tone` is `muted`.
+
+### Minimal example
+
+```tsx
+import { enUS } from "date-fns/locale";
+import { Datepicker } from "prime-ui-kit";
+
+export function DatepickerMinimal() {
+  return (
+    <Datepicker.Shell>
+      <Datepicker.Calendar locale={enUS} mode="single" />
+    </Datepicker.Shell>
+  );
+}
+```
+
+## Rules
+
+- Prefer **`Datepicker.Shell` inside [Popover](../popover/COMPONENT.md) `Content`** (often with `insetPadding="none"` on `Content`) opened from a trigger that shows the current value; the calendar is large and focus-heavy for inline page defaults.
+- **Controlled vs uncontrolled** — Drive selection with **`selected`** and **`onSelect`** from react-day-picker (and optional **`month`** / **`onMonthChange`**) when the parent must own state; otherwise rely on day-picker internal state where types allow.
+- **`responsiveMonths`** — When `true`, **`numberOfMonths` is ignored**; the kit measures the calendar viewport and switches between one and two columns using **`responsiveBreakpoints.twoColumns`** (default **500** px).
+- **Presets** — Use **`mode="single"`** or **`mode="range"`** per instance; do not mix range presets with single calendar mode in one `Presets`. The **`title`** prop exists on the type but **is not rendered** in the component.
+- **Time fields** — **`Datepicker.Time`** disables `input type="time"` until the anchor date exists (`value` in single mode; `from` / `to` in range mode). Default labels are Russian (**«Время»**, **«Начало»**, **«Конец»**); override via **`labels`**.
+- **Accessibility** — Day grid roles and keyboard navigation come from react-day-picker; month nav uses [Button](../button/COMPONENT.md) with English **`aria-label`** strings in the kit—replace via **`components`** / **`classNames`** on `Calendar` if your product language differs. Ensure the popover trigger has an accessible name. Time row uses **`useId`**-scoped labels on [Input](../input/COMPONENT.md).
+- **Styling and layout** — The module imports **`react-day-picker/style.css`**. **`responsiveMonths`** depends on container width; in tight flex layouts without **`min-width: 0`**, width can clip—check popover and grid CSS.
+- **Time zones** — Behavior follows local `Date` instances and how the browser shows **`type="time"`**; UTC shifts are the app’s responsibility.
+
+## API
+
+### Datepicker.Calendar
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | from `Shell` context, else `m` | No | Cell typography, nav buttons, and control scale. |
+| responsiveMonths | `boolean` | `false` | No | If `true`, `numberOfMonths` is ignored; column count follows viewport width. |
+| responsiveBreakpoints | `{ twoColumns: number }` | `{ twoColumns: 500 }` | No | Pixel width at which the layout uses two month columns. |
+| weekStartsOn | `0`–`6` | `1` | No | First weekday column (0 = Sunday). |
+| navLayout | `DayPicker` nav layout | `"after"` | No | Month navigation placement (react-day-picker). |
+| month | `Date` | — | No | Displayed month (controlled when set). |
+| onMonthChange | `(d: Date) => void` | — | No | Month changes; also notifies `Shell` month context. |
+| numberOfMonths | `number` | `1` | No | Fixed month count when `responsiveMonths` is not `true`. |
+| classNames, components, style | `DayPicker` props | — | No | Merged with kit defaults; custom `components` extend kit chevron and month caption. |
+| mode, selected, onSelect, disabled, locale, … | `DayPickerProps` | — | Varies | Other react-day-picker props are forwarded to `DayPicker`. |
+
+### Datepicker.Shell
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `m` | No | Size context for `Calendar`, `Presets`, `Time`, and `Value`. |
+| presets | `ReactNode` | — | No | Bottom bar (commonly `Datepicker.Presets`). |
+| children | `ReactNode` | — | Yes | Main panel content (`Calendar`, `Time`, `Value`, etc.). |
+| className | `string` | — | No | Root element class. |
+
+### Datepicker.Presets
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| mode | `"single" \| "range"` | — | Yes | Selects preset shape and `onSelect` signature. |
+| presets | `DatepickerPresetSingle[]` or `DatepickerPresetRange[]` | — | Yes | Quick actions; single items use `{ label, date }`, range items use `{ label, range }`. |
+| onSelect | `(date: Date \| undefined) => void` or `(range: DateRange \| undefined) => void` | — | Yes | Invoked when a preset button is pressed; updates shell month from the preset anchor. |
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | [ButtonGroup](../button-group/COMPONENT.md) segment size. |
+| className | `string` | — | No | Block wrapper class. |
+| title | `string` | — | No | Present in types only; not rendered. |
+
+### Datepicker.Time
+
+**Single** (default — `mode` omitted or `"single"`)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `Date \| undefined` | — | Yes | Anchor date; time field disabled when unset. |
+| onChange | `(next: Date) => void` | — | Yes | Called with date merged from `HH:mm` input. |
+| labels | `{ time?: string }` | — | No | Overrides default time label. |
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | Input size. |
+
+**Range** (`mode="range"`)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| mode | `"range"` | — | Yes | Enables two time fields. |
+| from | `Date \| undefined` | — | Yes | Start date; start time disabled when unset. |
+| to | `Date \| undefined` | — | Yes | End date; end time disabled when unset. |
+| onFromChange | `(next: Date) => void` | — | Yes | Merges time into `from`. |
+| onToChange | `(next: Date) => void` | — | Yes | Merges time into `to`. |
+| labels | `{ from?: string; to?: string }` | — | No | Overrides default range labels. |
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | Input size. |
+
+### Datepicker.Value
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | Масштаб пикера; внутри маппится на [Typography](../typography/COMPONENT.md) `variant`. |
+| tone | `Typography` tone | `muted` | No | Передаётся в `Typography.Root`. |
+| as, weight, tracking, italic, children, className, … | `Omit<TypographyRootProps, "variant">` | — | No | Как у `Typography.Root`, но кегль задаётся через `size` пикера (см. выше). |
+
+### Utilities
+
+| Name | Signature | Description |
+|------|-----------|-------------|
+| `formatTimeInputValue` | `(date?: Date) => string` | `HH:mm` for `input type="time"` `value`. |
+| `mergeTimeIntoDate` | `(date: Date, timeHHmm: string) => Date` | New `Date` with hours and minutes from the string. |
+
+### Exported types
+
+`DatepickerCalendarProps`, `DatepickerShellProps`, `DatepickerPresetsProps`, `DatepickerTimeProps`, `DatepickerTimeSingleProps`, `DatepickerTimeRangeProps`, `DatepickerValueProps`, `DatepickerSize`, `DatepickerPresetSingle`, `DatepickerPresetRange`, and **`DateRange`** (re-exported from react-day-picker) are exported from the package alongside the component and utilities.
+
+## Related
+
+- [Popover](../popover/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [ButtonGroup](../button-group/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)
+- [Modal](../modal/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)