prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/ux.md

@@ -27,7 +27,7 @@ adds text that explains what the layout failed to show.
 |---|---|---|
 | One record, read | label · value pairs | `DescriptionList` |
 | One record, edited | a form: fields 20 apart, groups 32 apart | `Fieldset`, fields |
-| One record of 2–4 short fields in a form | one row of fields | an `auto-fit` grid |
+| One record of 2–4 short fields in a form | one row of fields | an [intrinsic grid](responsive.md#intrinsic-grids) |
 | Records of one shape a person adds, edits, removes | one row per record, the headings once above | `FieldList` |
 | Records of one shape a person reads, sorts, filters | a table | `DataTable` |
 | One value in several units or currencies (a deposit in ₽, $, ฿) | the fields side by side in one row under one heading, the unit in each field | `Input.InlineAffix` |
@@ -35,10 +35,13 @@ adds text that explains what the layout failed to show.
 | Small attributes of a record (an icon, a color, a flag) | compact controls in the record's row, not fields of their own | icon-only `Select`, `ColorPresets`, `Checkbox` |
 | Short texts in an order the person sets | one column, a handle per row | `FieldList` `reorderable` |
 | Settings that most people never touch | behind a disclosure, after the common ones | `Accordion`, a «Дополнительно» section |
-| A choice of 2–5 options | all visible | `Radio.Group`, `SegmentedControl` |
-| A choice of 6+ options | a list that opens | `Select` |
+| One of a few options, sent with a form | all visible | `Radio.Group` |
+| One of a few modes of what the screen shows | all visible | `SegmentedControl` |
+| One of many options | a list that opens | `Select` |
 | Many values picked from options | tags | `TagSelect` |
 
+How many options count as «a few» and the other selection cases: [choosing.md](choosing.md#2-inside-a-category).
+
 One record is one row or one block, never half a record per line. If a record does not fit one
 row, it is not a row: open it in a `Drawer`.
 
@@ -67,8 +70,9 @@ The kit's UI language is Russian; these are the rules of its copy.
 
 - **Buttons say the verb and the object:** «Выставить счёт», «Добавить позицию», «Удалить проект».
   Never «ОК», «Да», «Подтвердить», «Отправить» without an object when the object is not obvious.
-- **A confirm names the thing and the loss:** «Удалить проект «Север»? Задачи и файлы удалятся
-  без возможности восстановления.» — not «Вы уверены?».
+- **A confirm names the thing and the consequence:** «Удалить проект «Север»? Задачи и файлы
+  удалятся без возможности восстановления.», «Выставить счёт на 48 000 ₽ ООО «Север»? Счёт уйдёт
+  клиенту на почту.» — not «Вы уверены?».
 - **An error says how to fix it:** «Формат: +7 912 404-18-20», «Не больше 2 000 символов» — not
   «Неверное значение», «Ошибка».
 - **An empty state says what to do next** and offers it: «Счетов пока нет» + «Выставить счёт». A
@@ -91,17 +95,24 @@ Pick the lightest step that keeps the person safe ([choosing.md](choosing.md) ha
 |---|---|
 | Reversible, frequent (remove a row, archive, move) | do it at once, «Отменить» in a `Notification` (`action`, commit in `onDismiss`) |
 | One standalone action that is easy to redo by hand | `Button.Root holdToConfirm` |
-| Irreversible loss of work, or a weighty outward action (send an invoice) | `ConfirmDialog` that names the thing and the loss |
+| Irreversible loss of work, or an outward action that cannot be called back once it leaves the product (an invoice or a message sent to a client, a payment) | `ConfirmDialog` that names the thing and the consequence |
 | Bulk destructive | `ConfirmDialog` that names the count («Удалить 12 счетов?») |
 | Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty` |
 
 A confirm on every action trains people to click through it; the one that mattered is then missed.
+Which button starts each step and how the confirm behaves:
+[api-contract.md](api-contract.md#destructive-actions).
 
 ## 6. Nothing to guess
 
 - **A disabled control says why** when the reason is not on screen: a `hint` under the field, a
-  line beside the button («Не больше 3», as `FieldList` does at `max`), a `Tooltip` on a wrapper.
-  An action a person may never take (no permission) is hidden, not disabled.
+  line beside the button («Не больше 3», as `FieldList` does at `max`), or the disabled control
+  itself in `Tooltip.Trigger`. An action a person may never take (no permission) is hidden, not
+  disabled.
+- **The screen answers the latest question.** A request a value starts (a search, a filter, a page,
+  a period) is cancelled when the value changes again — abort it (`AbortController`) or drop its
+  answer — so a slow answer never replaces a newer one. A simulated request (a `setTimeout` standing
+  in for the server) is cancelled the same way, in the effect's cleanup.
 - **The state of a screen is in the URL:** the tab, the filters, the search, the page, the open
   record. A link copied from the address bar opens the same view; Back undoes the last navigation.
 - **Visible status for every action** (the kit does it when you use it): `loading` on the button,
@@ -137,7 +148,8 @@ A confirm on every action trains people to click through it; the one that matter
 
 Code that passes every check can still read badly. Open the screen in a browser and look:
 
-- **Both themes**, **1280 px and 375 px** wide, and the narrow container of every panel.
+- **Both themes**, every width of [the responsive checklist](responsive.md#checklist-before-handing-a-screen-over),
+  and the narrow container of every panel.
 - **Count:** labels on a form of rows (§3), primary buttons per area (one), sizes per row (one).
 - **Read every text aloud:** a word that repeats its neighbour, a hint that explains the layout, a
   button without an object — remove or rewrite it.

package/dist/theme/applyTheme.d.ts

@@ -1,14 +1,15 @@
 export type ThemeScheme = "light" | "dark";
-/** Attribute that turns transitions off while a theme switch is painted (see globals.css). */
+/** Attribute that sets every motion clock to 0 while a theme switch is painted (see globals.css). */
 export declare const THEME_SWITCHING_ATTRIBUTE = "data-theme-switching";
 /**
- * Freezes transitions on `element` and its subtree for the frame in which the theme changes.
- * Without it every element with a color transition would interpolate from the old theme's
- * colors and visibly blink. Call it right before the theme attribute changes.
+ * Paints a theme change on `element` and its subtree with no transition: every motion clock is 0
+ * while `change` runs and the styles are flushed, then the clocks come back in the same task, so
+ * nothing interpolates from the old theme's colors. `change` sets the theme attribute; without it,
+ * call this right after the attribute changed (before the browser paints).
  */
-export declare function suspendTransitions(element: HTMLElement): void;
+export declare function suspendTransitions(element: HTMLElement, change?: () => void): void;
 /**
  * Switches the theme instantly: sets `data-theme` on `element` (default `<html>`) with transitions
- * suspended for that frame. Use it instead of setting the attribute by hand.
+ * suspended. Use it instead of setting the attribute by hand.
  */
 export declare function applyTheme(scheme: ThemeScheme, element?: HTMLElement): void;

package/dist/tokens/hues.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Palette hues (`color` props of Badge, Avatar, Tag…) and the primitive ramp each one is drawn
+ * from. One list for both themes: `semantic.ts` and `themes/dark.ts` build their palette from it.
+ */
+export declare const hues: readonly ["blue", "green", "orange", "red", "yellow", "purple", "sky", "pink", "teal"];
+export type Hue = (typeof hues)[number];
+/** Hue → primitive ramp (`color.<ramp>.<step>`): blue is the brand cobalt. */
+export declare const hueRef: Record<Hue, string>;

package/dist/tokens/layers.d.ts

@@ -1,8 +1,4 @@
-/** ΔL in OKLab between neighbouring layers. */
-export declare const LAYER_STEP = 0.03;
-/** Layers 0…4: the page and four nested surfaces. */
-export declare const LAYER_DEPTH = 4;
-export type LayerTheme = {
+type LayerTheme = {
     /** The page color (layer 0). */
     page: string;
     /** Lightness window: no color goes outside it. */
@@ -10,16 +6,12 @@ export type LayerTheme = {
     hi: number;
     /** Direction of control fills from their host: −1 darker, +1 lighter. */
     control: 1 | -1;
+    /** Steps from a track up to its selected segment (thumb). */
+    selected: number;
 };
 export declare const LIGHT_LAYERS: LayerTheme;
 export declare const DARK_LAYERS: LayerTheme;
-export declare const lightnessOf: (hex: string) => number;
-/**
- * `steps` steps from L towards `dir`. Reflects when less than half a step of room is left (unless
- * `reflect` is off), snaps to the edge when less than half a step would remain after the move.
- */
-export declare function move(theme: LayerTheme, L: number, dir: 1 | -1, steps?: number, reflect?: boolean): number;
-export type LayerColors = {
+type LayerColors = {
     /** The layer itself. */
     bg: string;
     /** Fields, chips, segmented tracks, neutral buttons on this layer. */
@@ -29,9 +21,6 @@ export type LayerColors = {
     /** The selected segment (thumb) on a track of this layer. */
     selected: string;
 };
-/** Layers 0…LAYER_DEPTH of a theme, each one step from its parent. */
-export declare function layerLadder(theme: LayerTheme): LayerColors[];
-/** Floating layers (popovers, menus, modals, drawers) sit one step above a card and never reflect. */
-export declare function floatingLayer(theme: LayerTheme): LayerColors;
 /** Token tree for `color.layer`: `0`…`4` plus `floating` and the two layers nested in it. */
 export declare function layerTokens(theme: LayerTheme): Record<string, LayerColors>;
+export {};

package/dist/tokens/offGrid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The deliberate exceptions to the 4px grid (foundation §1 rule 2), each with its reason: the one
+ * source of the list. `bun run tokens:build` fails on a length named here that lands on the grid
+ * or on one off the grid missing from here, and writes the list into foundation §1 rule 2;
+ * `src/styles/tokens.test.ts` allows exactly the lengths foundation lists.
+ */
+export declare const OFF_GRID: Record<string, string>;

package/dist/tokens/primitives.d.ts

@@ -6,14 +6,17 @@
 export declare const primitiveTokens: {
     readonly color: {
         readonly white: "#ffffff";
-        /** Graphite: cool neutral, slight blue bias. 0–100 light surfaces, 750–950 dark surfaces. */
+        /** The ink of the dark theme's scrim, washes and shadows. */
+        readonly black: "#000000";
+        /** Graphite: cool neutral, slight blue bias. White and 50–100 light surfaces, 750–950 dark. */
         readonly gray: {
-            readonly 0: "#ffffff";
             readonly 50: "#f3f4f6";
             readonly 75: "#eef0f3";
             readonly 100: "#e8eaee";
             readonly 150: "#e0e3e8";
             readonly 300: "#b9bec8";
+            /** Dark muted text: AA on the hovered fill of the deepest layer. */
+            readonly 350: "#a1a8b6";
             readonly 400: "#949bab";
             readonly 500: "#636a79";
             readonly 600: "#575e6d";
@@ -97,8 +100,9 @@ export declare const primitiveTokens: {
         /**
          * Categorical chart hues: not ramps but one set, validated together (dataviz checks — OKLCH
          * lightness band, chroma floor, CVD and normal-vision separation of neighbours in the
-         * `color.chart` order, ≥ 3:1 on the layer grounds). Light steps for gray.0–50 grounds, dark steps
-         * for gray.950–850. Blue is cobalt (600 light, 500 dark). Change one only by re-running the checks.
+         * `color.chart` order, ≥ 3:1 on every layer ground — `src/theme/chartColors.test.ts` keeps the
+         * contrast). Light steps for the light ladder, dark steps for the dark one. Blue is cobalt (600
+         * light, 500 dark). Change one only by re-running the checks.
          */
         readonly chart: {
             readonly light: {
@@ -115,7 +119,8 @@ export declare const primitiveTokens: {
                 readonly teal: "#199e70";
                 readonly yellow: "#c98500";
                 readonly pink: "#d55181";
-                readonly green: "#008300";
+                /** A step lighter than light's green: 3:1 holds up to the deepest layer (4). */
+                readonly green: "#008a00";
                 readonly purple: "#9085e9";
                 readonly red: "#e66767";
             };
@@ -128,9 +133,12 @@ export declare const primitiveTokens: {
             readonly 700: "#be185d";
         };
     };
-    /** 4px grid. Key = number of 4px steps (`4` → 16px). */
+    /**
+     * 4px grid. Key = number of 4px steps (`4` → 16px). `0` carries a unit: a unitless `0` is a
+     * number inside `calc()` / `max()`, and `calc(100% + 0)` is invalid (the declaration drops).
+     */
     readonly space: {
-        readonly 0: "0";
+        readonly 0: "0rem";
         readonly 1: "0.25rem";
         readonly 2: "0.5rem";
         readonly 3: "0.75rem";
@@ -159,8 +167,14 @@ export declare const primitiveTokens: {
     };
     readonly font: {
         readonly family: {
-            readonly sans: "\"Golos Text\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
-            readonly mono: "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+            /** `… Fallback`: the metric-matched local faces of the opt-in `fonts.css`. */
+            readonly sans: "\"Golos Text\", \"Golos Text Fallback\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
+            readonly mono: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+            /**
+             * Key caps: the mono faces for letters and digits, then the system UI face before the mono
+             * fallbacks — the mono faces have no ⇧ ⌥ ⌃ or ⌘, and Menlo draws them small and light.
+             */
+            readonly key: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, system-ui, -apple-system, \"Segoe UI Symbol\", Menlo, Consolas, monospace";
         };
         /** Modular scale, ~1.2 in the body range, ~1.25 for headings. */
         readonly size: {
@@ -212,12 +226,15 @@ export declare const primitiveTokens: {
         readonly 32: "2rem";
     };
     readonly duration: {
+        readonly 0: "0ms";
         readonly 80: "80ms";
         readonly 150: "150ms";
         readonly 230: "230ms";
         readonly 300: "300ms";
         readonly 380: "380ms";
         readonly 570: "570ms";
+        readonly 1200: "1200ms";
+        readonly never: "600000s";
     };
     readonly easing: {
         /**
@@ -235,8 +252,16 @@ export declare const primitiveTokens: {
      * Stacking order. Every overlay (modal, drawer, popover, menu, listbox, tooltip) portals to
      * `<body>` when it opens and shares one level: the DOM order is the open order, so a layer opened
      * later — a Select inside a Modal, a Tooltip inside a Popover — is on top without its own number.
+     * `below`, `0`…`5` order the parts stacked inside one component (a mark over a picture).
      */
     readonly zIndex: {
+        readonly below: "-1";
+        readonly 0: "0";
+        readonly 1: "1";
+        readonly 2: "2";
+        readonly 3: "3";
+        readonly 4: "4";
+        readonly 5: "5";
         readonly sticky: "100";
         readonly overlay: "1000";
         readonly toast: "10000";