prime-ui-kit 0.9.0 → 0.9.1

package/README.md

@@ -6,7 +6,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
 **A calm, precise React 19 UI kit for product interfaces** — admin panels, dashboards, settings, forms
-and data tables. 50 components on one design contract, one API vocabulary and one set of tokens, so
+and data tables. 57 components on one design contract, one API vocabulary and one set of tokens, so
 every screen you build looks like it was drawn by the same hand.
 
 - **Graphite design language.** Depth from fill, not lines; a strict 4px grid; one size axis
@@ -15,7 +15,14 @@ every screen you build looks like it was drawn by the same hand.
 - **Light and dark as equals.** Full themes, WCAG AA text contrast, a focus ring that is never clipped.
 - **One API everywhere.** `size`, `variant`, `tone`, `color`, `invalid/hint/error`,
   `value/onValueChange`, `checked/onCheckedChange`, `open/onOpenChange`, `labels` — the same names in
-  every component, compound parts `X.Root` + `X.Part`, state in `data-*`.
+  every component, compound parts `X.Root` + `X.Part` for components with parts and a single export
+  for leaves (`<Kbd>`, `<Divider>`), state in `data-*`.
+- **Built from itself.** Components reuse the kit's own Button, Badge, Spinner, Icon, Checkbox,
+  EmptyPage and ScrollContainer instead of private copies, so a fix in one place lands everywhere.
+- **States flow, they never flip.** Controls move into their new state; a region that switches
+  between loading, data, empty and error cross-fades and glides to its new height (`Crossfade`),
+  and while it loads a `Skeleton` holds the shape of the coming content — so nothing on the page
+  jumps.
 - **Overlays that behave.** Modal, Drawer, Popover, Dropdown, Select, Tooltip and CommandMenu share
   one stack: one click or one Escape closes exactly the topmost layer, focus goes where it should.
 - **Accessible by default.** Keyboard support, ARIA roles, Russian default strings for every system
@@ -51,50 +58,36 @@ prime-ui-kit is built to be used by coding agents (Claude Code, Cursor, Codex,
 
 ---
 
-## What's new in 0.9.0
-
-- **API v1.** One vocabulary across the kit: `size`, `variant`, `tone`, `color`, `invalid/hint/error`,
-  `value/onValueChange`, `checked/onCheckedChange`, `open/onOpenChange`, `closeOnOutsideClick`,
-  `closeOnEscape`, `labels`. No aliases, no deprecated props.
-- **Graphite redesign.** Fill-based depth, borderless fields, lavender accent, soft badges and tags,
-  full dark theme, never-clipped focus ring, one overlay stack with shared dismiss and motion rules.
-- **Docs rewritten from the code.** Every component has a new `COMPONENT.md` (anatomy, every prop with
-  its default, every variant, states, a11y, mistakes) and one-scenario-per-file `examples/` that the
-  playground renders directly — one source for the playground, the npm package and the agent skill.
-- **Agent skill rebuilt** (`SKILL/`): process, design rules, API cheat sheet, choosing guide,
-  composition, page recipes, anti-slop rules and a review checklist — field-tested on real screens.
-- **Docs contract test** keeps docs, examples and the playground from drifting apart.
-- Kit fixes: `Popover.Trigger` keeps the child's `id` (field labels work for Datepicker and
-  ColorPresets), `Card.Title` / `Card.SectionTitle` take `as` for the heading level, FileUpload `solid`
-  keeps no outline on hover, more prop types exported.
-
 ## Install
 
 ```bash
-npm install prime-ui-kit react react-dom react-aria-components date-fns
+npm install prime-ui-kit react react-dom date-fns
+# using ColorPicker: also react-aria-components
 # or: pnpm add … · bun add …
 ```
 
 | Peer dependency | Version |
 |---|---|
 | `react`, `react-dom` | ^19.0.0 |
-| `react-aria-components` | ^1.16.0 |
 | `date-fns` | ^4.0.0 |
+| `react-aria-components` (optional, only for `prime-ui-kit/color-picker`) | ^1.16.0 |
 
-`lucide-react` (icons) and `react-router-dom` come with the package.
+`lucide-react` (icons) comes with the package. The kit has no router dependency: pass your router's
+pathname to `AppShell.Template scrollResetKey` and use `asChild` for router links.
 
 ## Set up styles and theme
 
 ```tsx
-import "prime-ui-kit/styles.css"; // Golos Text + JetBrains Mono, reset, tokens, light and dark themes
-import "prime-ui-kit/bundle.css"; // component styles
+import "prime-ui-kit/bundle.css"; // tokens, light and dark themes, component styles
+import "prime-ui-kit/fonts.css"; // optional: Golos Text + JetBrains Mono from Google Fonts
+import "prime-ui-kit/reset.css"; // optional: minimal document reset (skip if the app has its own)
 import { applyTheme } from "prime-ui-kit";
 
 applyTheme("dark"); // sets data-theme on <html> without a transition flash
 ```
 
+`bundle.css` is everything the components need; it leaves the root font size to the browser.
 `data-theme="light" | "dark"` also works on any wrapper, so one page can show both themes.
-Fine-grained alternatives: `prime-ui-kit/tokens.css`, `theme-light.css`, `theme-dark.css`.
 
 ## Quick start
 
@@ -108,7 +101,7 @@ export function App() {
       nav={
         <Sidebar.Root>
           <Sidebar.Content>
-            <Sidebar.Item active>Clients</Sidebar.Item>
+            <Sidebar.Item current>Clients</Sidebar.Item>
           </Sidebar.Content>
         </Sidebar.Root>
       }
@@ -135,8 +128,10 @@ export function App() {
 
 Short rules that keep code correct — for people and for AI coding assistants:
 
-1. Import everything from the package root: `import { Button, Input } from "prime-ui-kit"`.
-2. Import styles once at the app root: `prime-ui-kit/styles.css` and `prime-ui-kit/bundle.css`.
+1. Import everything from the package root: `import { Button, Input } from "prime-ui-kit"`. The one
+   exception is `import { ColorPicker } from "prime-ui-kit/color-picker"`.
+2. Import styles once at the app root: `prime-ui-kit/bundle.css` (plus the optional `fonts.css` and
+   `reset.css`).
 3. Compound components are used through parts: `<Button.Root>`, `<Modal.Root>` + `<Modal.Content>`.
    `<Button>` alone is not a component.
 4. Default `size` is `m`; controls in one row share one size.
@@ -176,6 +171,7 @@ accessibility, examples and common mistakes.
 | [**Input**](https://github.com/esurkov1/prime-ui/blob/main/src/components/input/COMPONENT.md) | Single-line text field with label, hint, error and slots for icons, affixes, a badge, a clear button and a counter. |
 | [**Textarea**](https://github.com/esurkov1/prime-ui/blob/main/src/components/textarea/COMPONENT.md) | Multi-line text field with label, hint, error and a character counter; grows with its content by default. |
 | [**DigitInput**](https://github.com/esurkov1/prime-ui/blob/main/src/components/digit-input/COMPONENT.md) | A row of square single-digit cells for a fixed-length code (OTP from SMS, PIN, pickup code). |
+| [**LoginForm**](https://github.com/esurkov1/prime-ui/blob/main/src/components/login-form/COMPONENT.md) | A sign-in card with a logo, title, provider buttons and a form; covers sign-in, sign-up, password reset and code confirmation. |
 | [**FileUpload**](https://github.com/esurkov1/prime-ui/blob/main/src/components/file-upload/COMPONENT.md) | File picker zone with drag and drop, plus presentational parts for the list of selected files. |
 | [**Label**](https://github.com/esurkov1/prime-ui/blob/main/src/components/label/COMPONENT.md) | Field label (native `<label>`) with required and optional markers. |
 | [**Hint**](https://github.com/esurkov1/prime-ui/blob/main/src/components/hint/COMPONENT.md) | Help text or a validation error under a field. |
@@ -190,17 +186,20 @@ accessibility, examples and common mistakes.
 | [**SegmentedControl**](https://github.com/esurkov1/prime-ui/blob/main/src/components/segmented-control/COMPONENT.md) | A switch between 2–5 mutually exclusive options or modes that takes effect immediately. |
 | [**Slider**](https://github.com/esurkov1/prime-ui/blob/main/src/components/slider/COMPONENT.md) | A slider for picking an approximate numeric value within a range, with an optional label and value readout. |
 | [**Select**](https://github.com/esurkov1/prime-ui/blob/main/src/components/select/COMPONENT.md) | A dropdown field for choosing one value (or several with `multiple`) from a closed list. |
+| [**NativeSelect**](https://github.com/esurkov1/prime-ui/blob/main/src/components/native-select/COMPONENT.md) | The system `<select>` in the kit's field frame: plain text options, native picker on phones. |
 | [**TagSelect**](https://github.com/esurkov1/prime-ui/blob/main/src/components/tag-select/COMPONENT.md) | A multi-select field that shows the chosen values as coloured tags, filters as you type and can create new tags. |
+| [**SmartFilter**](https://github.com/esurkov1/prime-ui/blob/main/src/components/smart-filter/COMPONENT.md) | A filter bar for lists and tables: a filter button and search with a panel of values, applied filters as tags, and a show / hide choice for every value. |
 | [**Datepicker**](https://github.com/esurkov1/prime-ui/blob/main/src/components/datepicker/COMPONENT.md) | A calendar for picking a date or a date range: a field with a popover (`Datepicker.Root`) or an embedded panel (`Datepicker.Panel`). |
 | [**ColorPicker**](https://github.com/esurkov1/prime-ui/blob/main/src/components/color-picker/COMPONENT.md) | Color selection: a full picker (area, channel sliders, hex and channel fields, eyedropper, swatches) and `ColorPresets` for a quick color from a fixed palette. |
+| [**ColorSwatches**](https://github.com/esurkov1/prime-ui/blob/main/src/components/color-swatches/COMPONENT.md) | An inline color choice: a wrapping grid of preset swatches inside a form, without a popover. |
 
 ### Data display (`data-display`)
 
 | Component | What it is for |
 |---|---|
-| [**Badge**](https://github.com/esurkov1/prime-ui/blob/main/src/components/badge/COMPONENT.md) | A compact static label for a status, category or count, in a palette color. |
-| [**Tag**](https://github.com/esurkov1/prime-ui/blob/main/src/components/tag/COMPONENT.md) | A chip for a selected value, applied filter or keyword, with an optional remove button and a palette color. |
+| [**Badge**](https://github.com/esurkov1/prime-ui/blob/main/src/components/badge/COMPONENT.md) | The kit's one chip: a status, category or count label, a removable value or applied filter, and a pressable toggle with a hover action, in a palette color. |
 | [**Avatar**](https://github.com/esurkov1/prime-ui/blob/main/src/components/avatar/COMPONENT.md) | A round photo of a person or entity with an initials or icon fallback, presence dot and overlapping groups. |
+| [**Thumbnail**](https://github.com/esurkov1/prime-ui/blob/main/src/components/thumbnail/COMPONENT.md) | A preview of an object — product, vehicle, file, cover — at a fixed aspect ratio, with a colored icon fallback. |
 | [**Kbd**](https://github.com/esurkov1/prime-ui/blob/main/src/components/kbd/COMPONENT.md) | A key cap for a keyboard key or a shortcut, rendered as a native `<kbd>`. |
 | [**Card**](https://github.com/esurkov1/prime-ui/blob/main/src/components/card/COMPONENT.md) | A filled surface block with structural templates for metrics, charts, lists, calls to action and covers. |
 | [**DataTable**](https://github.com/esurkov1/prime-ui/blob/main/src/components/data-table/COMPONENT.md) | A data table with sorting, pagination or infinite scroll, row selection, nested rows and loading / empty / error states. |
@@ -213,9 +212,11 @@ accessibility, examples and common mistakes.
 |---|---|
 | [**Banner**](https://github.com/esurkov1/prime-ui/blob/main/src/components/banner/COMPONENT.md) | Full-width in-flow message for a page, section or card: status icon, title, description, actions and dismiss. |
 | [**Notification**](https://github.com/esurkov1/prime-ui/blob/main/src/components/notification/COMPONENT.md) | Pop-up toast notifications: `NotificationProvider` at the app root and `notify()` from any screen. |
-| [**ProgressBar**](https://github.com/esurkov1/prime-ui/blob/main/src/components/progress-bar/COMPONENT.md) | Linear progress indicator on a native `<progress>` with a label, a percentage and a status color. |
-| [**SegmentedProgressBar**](https://github.com/esurkov1/prime-ui/blob/main/src/components/segmented-progress-bar/COMPONENT.md) | One bar made of proportional segments: storage by type, task statuses, a funnel or quotas. |
-| [**ProgressCircle**](https://github.com/esurkov1/prime-ui/blob/main/src/components/progress-circle/COMPONENT.md) | Circular progress indicator: a track, a rounded arc and optional content in the center. |
+| [**ProgressBar**](https://github.com/esurkov1/prime-ui/blob/main/src/components/progress-bar/COMPONENT.md) | Linear progress: one value on a native `<progress>`, or `segments` that split a whole (storage by type, task statuses), with a label, a percentage and status colors. |
+| [**ProgressCircle**](https://github.com/esurkov1/prime-ui/blob/main/src/components/progress-circle/COMPONENT.md) | Circular progress — the ring version of ProgressBar: one value or `segments` that split a whole, with status colors and optional content in the center. |
+| [**Spinner**](https://github.com/esurkov1/prime-ui/blob/main/src/components/spinner/COMPONENT.md) | An indeterminate loading indicator: a ring with a gap that turns while a request runs. |
+| [**Skeleton**](https://github.com/esurkov1/prime-ui/blob/main/src/components/skeleton/COMPONENT.md) | A placeholder in the shape of the content that is loading — text lines, a control, an avatar, a block — so the layout is in place before the data arrives. |
+| [**Crossfade**](https://github.com/esurkov1/prime-ui/blob/main/src/components/crossfade/COMPONENT.md) | A region that cross-fades between its states (loading → data → empty → error) and glides to the new height, so the page below does not jump. |
 | [**EmptyPage**](https://github.com/esurkov1/prime-ui/blob/main/src/components/empty-page/COMPONENT.md) | Empty state of a page or a block: icon, title, explanation and an action. |
 
 ### Navigation (`navigation`)
@@ -248,6 +249,7 @@ accessibility, examples and common mistakes.
 | [**Accordion**](https://github.com/esurkov1/prime-ui/blob/main/src/components/accordion/COMPONENT.md) | Collapsible sections: FAQ, settings groups, checkout steps. |
 | [**Divider**](https://github.com/esurkov1/prime-ui/blob/main/src/components/divider/COMPONENT.md) | A hairline separator, horizontal or vertical, with or without a label. |
 | [**ScrollContainer**](https://github.com/esurkov1/prime-ui/blob/main/src/components/scroll-container/COMPONENT.md) | A scroll region with the kit's thin scrollbar that shrinks correctly inside flex and grid parents. |
+| [**Dnd**](https://github.com/esurkov1/prime-ui/blob/main/src/components/dnd/COMPONENT.md) | Pointer-driven drag and drop: reorderable lists, draggable items and drop zones, with touch and keyboard support. |
 
 ### Foundations (`foundations`)
 
@@ -268,9 +270,8 @@ accessibility, examples and common mistakes.
 | `NotificationProvider` + `useNotifications()` | Toast queue: `notify`, `dismiss`, `dismissAll`. Place the provider once at the app root. |
 | `ControlSizeProvider` | Default `size` for every control in a subtree (dense toolbars, compact forms). |
 | `Tooltip.Provider` | Shared open delay for a group of tooltips. |
-| `OverlayPortalLayerProvider` | Portal target for overlays rendered inside a custom layer. |
 | `applyTheme(scheme, element?)` | Switch the theme without transition flashes. |
-| `Icon`, `IconSearch`, `IconClose`, … | The kit icon set (built on lucide-react). |
+| `<Icon name="…" />`, `createIcon(glyph)` | The kit icon set (built on lucide-react); `createIcon` turns a domain glyph into a kit icon. |
 
 ## Docs inside the package
 
@@ -328,12 +329,11 @@ command again with `--force` (degit) or re-copy the folder.
 
 | Path | Purpose |
 |---|---|
-| `prime-ui-kit` | Main JS/TS API (includes global styles import). |
-| `prime-ui-kit/components` | Components entry without layout extras. |
-| `prime-ui-kit/styles.css` | Fonts, reset, tokens, both themes. |
-| `prime-ui-kit/tokens.css`, `theme-light.css`, `theme-dark.css` | Individual layers. |
-| `prime-ui-kit/bundle.css` | Component CSS for the main entry. |
-| `prime-ui-kit/components.css` | Component CSS for the `components` entry. |
+| `prime-ui-kit` | The JS/TS API: every component, layout, icon and helper (no CSS side effects). |
+| `prime-ui-kit/bundle.css` | Tokens, both themes, base rules (focus ring, reduced motion) and every component's CSS. |
+| `prime-ui-kit/fonts.css` | Optional: Golos Text and JetBrains Mono from Google Fonts. |
+| `prime-ui-kit/reset.css` | Optional: minimal document reset. |
+| `prime-ui-kit/tokens.css`, `theme-light.css`, `theme-dark.css` | The token layers alone (already inside `bundle.css`), for styling without components. |
 
 Type definitions ship with the package.