prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/motion.md

@@ -0,0 +1,211 @@
+# Motion — animation and micro-animation on prime-ui-kit
+
+Motion is part of the screen, not polish added at the end. A screen built on the kit moves the way
+the kit's author would make it move: every state change is continuous, every press answers, nothing
+flips — and nothing moves without a reason. Most of it is already inside the components; your job is
+to use them so it can happen, and to add motion only where the kit leaves the choice to you.
+
+The full design contract lives in the kit repository (`docs/foundation.md`, «Motion»); this file is how
+to apply it on a screen and is enough on its own.
+
+## 1. What the kit already animates — do not rebuild it
+
+Use the component and the motion comes with it. Never re-animate these with your own CSS.
+
+| You need | The kit does it | How you get it |
+|---|---|---|
+| Press feedback | every pressable control scales to 0.98 (0.96 icon-only) | any `Button`, chip, item |
+| Icons that feel alive | every kit icon plays its own gesture once when its host (button, link, tab, menu item, option, row) is hovered or pressed; never on keyboard focus, disabled, or under reduced motion | `<Icon name>`, `prime-ui-kit/icons` glyphs, `createIcon` (a soft pop); `animated={false}` to keep one still |
+| A button whose label changes («Сохранить» → «Сохранено», «Продолжить» → «Подтвердить») | the new label flows in letter by letter, the width glides; digits-only changes stay in place | change the `Button.Root` text children |
+| A long action from a button (download, export) | a fill grows inside the button | `Button.Root progress={0…1}`, the number in the label |
+| One destructive action without a list or a dialog | a held press with a fill clock; early release rolls back | `Button.Root holdToConfirm onConfirm={…}` |
+| Loading inside a button | spinner over the kept label, width does not change | `loading` |
+| Check / uncheck | the check draws in with a stroke, leaves fast | `Checkbox`, `Checkbox.Indicator`, `ColorSwatches` |
+| Toggle | the thumb slides | `Switch` |
+| One of a few | the indicator glides to the choice | `SegmentedControl`, `Tabs` |
+| Disclosure | height through `grid-template-rows`, the chevron turns | `Accordion` |
+| A chat message changes size (a reaction comes or goes, a transcript opens, an edit, an upload state) | one stroke: the new layout is there at once and the bubble's box glides from the old size to the new one — width and height together, its parts gliding, fading in or out where they stand on the same clock (`--prime-message-morph-duration`); the time and the tail stay, and nothing travels across text (the time dips while text passes through its place, and cross-fades when it changes line): a reaction grows the message upward, the chat scrolling by the change while the rows above glide as one block (the rows below never move); a transcript grows it downward under a still player | `Message.Root` (built in) |
+| A counter or a count | digits roll like an odometer | `Badge` with a number child, the `counter` of `Input` / `Textarea` |
+| A field with an error | the control shakes once, sharply, when the error arrives or changes; the label stays, the message drops in | `error` (or `invalid`) on any field, `Checkbox.Root`, `Switch.Root`, `Radio.Group` — not for an error the field mounts with |
+| Password strength | stepped bar fills cell by cell, the level word flows in | `Input.Root strength` |
+| A one-time code | one focus ring glides between cells, digits fade in; while the server checks it the cells quiet down, success rolls across, a refused code clears and its reason shakes in | `DigitInput` (`onComplete` returns a Promise, or `success` / `error`) |
+| Steps of a whole | cells fill one after another | `ProgressBar steps value max` |
+| Progress | the fill slides | `ProgressBar`, `ProgressCircle` |
+| A trend card | scrub any point, the headline follows, the arrow turns, a new series cross-fades | `Sparkline` |
+| Overlays | grow from the trigger (menus, popovers, tooltip from its arrow), modals stay centred, drawers, sheets and toasts come from their edge; a dialog, drawer or sheet leaves faster than it came, a small floating panel opens and closes on the same quick `fast` clock; the last content stays on screen while the exit plays | `Dropdown`, `Popover`, `Tooltip`, `Modal`, `ConfirmDialog`, `Drawer`, `Sheet`, `MediaViewer`, notifications — the `Root` kept mounted |
+| Tooltips along a toolbar | the first waits, the next ones show at once | `Tooltip` (shared warm window) |
+| Toast stack | depth stack, expands on hover | `NotificationProvider` + `useNotifications` |
+| Loading → data → empty → error | the region cross-fades and glides its height; loading is a skeleton of the data | `Crossfade` around the region, `Skeleton` in the data's geometry |
+| Drag | the carried piece lifts, its neighbours glide apart, the drop glides into place; while its save runs the piece quiets under a spinner, and a refused save glides it back — across columns too | `Dnd`, `Kanban` cards and columns, DataTable `onReorder`, `FileUpload` tiles |
+| A setting saved on the server | the thumb moves at once and a spinner turns inside it (a slider thumb dims); a refused save glides it back | `Switch` (`onCheckedChange` returns a Promise, or `loading`), `Slider` (`onCommit`) |
+| A chip or a file row removed | it waits dimmed with a spinner on its ×; once gone it fades and closes up, the next ones glide into its place; refused, it stays | `Badge` `onRemove`, `FileUpload` `onValueChange`, TagSelect chips |
+| A schedule bar moved, stretched or drawn | the bar lifts and steps by whole days under the pointer with a dates tooltip; a drawn bar is a ghost that turns into a pulsing Skeleton while `onBarCreate` runs; a refused change glides back, a refused bar fades out; the zoom cross-fades around the day in the middle | `Gantt` (`onBarChange`, `onBarCreate`, `scale`) |
+| Messages | a message new at the end enters by itself — mine and theirs alike float up a little from below and fade in (`fast`), while the list is only pushed by layout and stays pinned to the end; nothing else moves, and nothing is ever moved by a transform computed from page geometry; the first render, history loaded above, rows the list renders as they scroll into view and a status change never move; «печатает…» is an incoming bubble of three dots rising in turn on the loading loop, opening its height as it comes and closing it as it goes — or gone at once when the reply takes its place; a jumped-to message (a reply, a search result, a pinned one) comes to the middle of the chat's own scroller and stays at full strength while the others step back and forth three times (opacity only, `base` each; a search keeps them back while the match is current) — nothing is drawn on it; the «к последним» button rises in while the reader is away from the end; delivery ticks cross-fade into the next status; a reaction new on the message fades and scales in from 0.9 once (never on the first render or a history load); a new chip takes its room at once and fades and scales in, a removed one fades out where it stood while the chips after it glide into its place; the first and the last reaction open and close the row as the message's one stroke, the message growing upward with the time and the tail still and the rows above gliding as one block; a count change rolls its digits only; the reaction bar grows from the bubble, its emoji pop in one after another, the picked one pops while the bar leaves on the same clock it opened with; in selection mode the checks enter at the start of the rows and the unselected messages step back (opacity and a slight desaturation, `fast`) while the selected stay as they are; a transcript opens and closes as one stroke, the player row still and the text fading over the whole stroke as the box opens or closes over it; the transcript button's glyph cross-fades into a chevron | `Chat` (`selected`, `search`, `typing`, `current`, `Chat.Pinned`), `Message` (`onReactionToggle`, `Message.Typing`, `Message.Reply target`) |
+| Writing a message | the send glyph turns into place as text appears; the reply / edit bar enters; a paused recording stills its dot into a pause glyph and freezes the timer and the waveform; the recording bar cross-fades over the field inside the row's height, the hint slides and fades with the finger, the dot breathes and the live waveform follows the voice; the formatting toolbar fades in over a selection | `Composer` |
+| Playing a voice message | the waveform fills as it plays and is the seek slider; play and pause cross-fade; the speed label flows into the next rate | `VoicePlayer` |
+| A rare milestone | a short confetti burst | `celebrate({ origin })` |
+
+## 2. Decide first: should it move at all?
+
+Ask by frequency, then by purpose.
+
+| How often a person does it | Motion |
+|---|---|
+| Hundreds of times a day, or from the keyboard (arrowing a list, row hover, command palette) | none — color / fill only, at most `xfast` |
+| Tens of times a day (hover, tabs, toggles) | small and quick |
+| Occasionally (dialogs, drawers, toasts) | the standard overlay motion |
+| Rarely (success, empty state, onboarding, a milestone) | may carry delight |
+
+Every motion has one of four purposes: feedback (a press answered), a state change (check, toggle,
+selection moving), spatial continuity (a panel grows out of its trigger, an indicator travels), or
+preventing a jump (items appearing, heights changing). «Looks nice» on a frequent element is not a
+purpose.
+
+Direct manipulation has no easing: while a finger or pointer drags, scrubs or resizes, the thing sits
+under it. Easing starts when the hand lets go.
+
+## 3. Tokens — the only durations and curves
+
+| Token | Value | Use |
+|---|---|---|
+| `--prime-motion-duration-xfast` | 150 ms | hover fill on dense rows |
+| `--prime-motion-duration-fast` | 230 ms | press, hover, small panels (in and out), the exit of a dialog |
+| `--prime-motion-duration-base` | 380 ms | dialogs, toggles, content swaps, things gliding into place |
+| `--prime-motion-duration-slow` | 570 ms | drawers, sheets, long fills |
+| `--prime-motion-easing-enter` | strong ease-out | appearing, responding |
+| `--prime-motion-easing-exit` | strong ease-out | leaving (with a shorter duration than enter) |
+| `--prime-motion-easing-standard` | ease-in-out | moving on screen, color and fill |
+| `--prime-motion-easing-emphasized` | decisive start, soft landing | a thumb, an indicator, a check gliding into place |
+| `--prime-motion-stagger` | 80 ms | step of a staggered first render |
+| `--prime-motion-loop` | 570 ms | period unit of a loading loop (Spinner); kept under reduced motion |
+| `--prime-motion-blur` | 2 px | hiding a change of shape while two states swap |
+| `--prime-motion-press-scale` / `-compact` | 0.98 / 0.96 | `:active` scale |
+
+Under `prefers-reduced-motion` the durations and stagger go to 0 and the press scale to 1 globally —
+token-based CSS honours it for free. `--prime-motion-loop` stays: a loading loop is information and
+keeps running, slower. Anything you drive from JS checks the media query itself.
+
+## 4. Rules for your own motion
+
+- Tokens only: never a raw `ms` or `cubic-bezier` in your CSS.
+- Animate `transform` and `opacity` (plus color, fill and shadow for state). Never `width`, `height`,
+  `top`, `left`, `margin`; for height use `grid-template-rows: 0fr → 1fr`. Never `transition: all`.
+- Enter on `enter`, leave on `exit`, and leave faster than you came. Never `ease-in`.
+- Nothing overshoots: no bounce, no spring past the target, no elastic.
+- Never from nothing: appear from `opacity: 0` plus a small offset (`--prime-space-1`/`-2`) or
+  `scale(0.96)`, never `scale(0)`.
+- State moves, it does not swap: a selection travels, a check draws, a counter rolls, two contents
+  cross-fade. A toggled state uses transitions (they retarget mid-flight); keyframes only for one-shot
+  appearance.
+- Hover movement only inside `@media (hover: hover)`; nothing is hover-only.
+- Stagger only the first render of a short group (≤ 6 items) and never block interaction with it.
+- A gesture clock (a hold, a countdown) is information, not motion: it keeps running under reduced
+  motion.
+
+## 5. Recipes
+
+**A button that does a long job.** Do not swap the button for a progress bar. Pass `progress`, put
+the number in the label, then a new label when it is done.
+
+```tsx
+import { Button, Icon } from "prime-ui-kit";
+
+export function ExportButton({ progress, ready }: { progress?: number; ready: boolean }) {
+  return (
+    <Button.Root variant={ready ? "soft" : "solid"} progress={progress}>
+      <Button.Icon>
+        <Icon name="action.download" />
+      </Button.Icon>
+      {progress !== undefined
+        ? `Экспорт ${Math.round(progress * 100)}%`
+        : ready
+          ? "Открыть файл"
+          : "Экспорт в CSV"}
+    </Button.Root>
+  );
+}
+```
+
+**Save → saved.** `loading` while the request runs, then change the label; the kit morphs it. Return
+to the idle label after about two seconds.
+
+**Delete without a dialog.** One destructive action that is not a row in a list and is easy to redo
+by hand (clear a draft, revoke a token) → `holdToConfirm` instead of a confirm dialog. A row in a list →
+the undo recipe below. Irreversible loss of work → a `ConfirmDialog`. (The rule:
+[choosing.md](choosing.md), «ConfirmDialog / Modal / `holdToConfirm` / undo».)
+
+```tsx
+import { Button, Icon } from "prime-ui-kit";
+
+export function DeleteDraft({ onDelete }: { onDelete: () => void }) {
+  return (
+    <Button.Root variant="soft" tone="danger" holdToConfirm onConfirm={onDelete}>
+      <Button.Icon>
+        <Icon name="action.delete" />
+      </Button.Icon>
+      Удерживайте, чтобы удалить черновик
+    </Button.Root>
+  );
+}
+```
+
+**A region that loads.** Wrap it in `Crossfade` keyed by the state and show a `Skeleton` in the shape
+of the data — never a spinner in the middle of an empty card, never a flip.
+
+**A metric that updates.** Put a number in a `Badge` or a `Sparkline` and change it: the digits roll.
+A number that changes by itself every frame (a running percentage) stays plain tabular text — rolling
+there is noise.
+
+**New password.** `Input.Root strength` — the meter and the level word come with it. Pair it with a
+hint that states the rule in words.
+
+**One-time code.** `DigitInput` with `onComplete` to verify, then `success` (accepted) or `error`
+(rejected). Never colour the cells green before the server answered.
+
+**Removing a row with undo.** Remove the row from the data, show a notification with an «Отменить»
+action, put the row back on undo — undo beats a confirm dialog for reversible deletes. When the delete
+reaches the server only after the chance to undo has passed, send it from the notification's
+`onDismiss`.
+
+**A rare achievement.** Say it in words (a `Banner`, the progress label turning success), then call
+`celebrate({ origin: element })` once. Only for something that happens rarely — a quarter closed, the
+first invoice paid, onboarding finished. Routine success is a notification.
+
+```tsx
+import { Button, celebrate } from "prime-ui-kit";
+
+export function CloseQuarter({ onClose }: { onClose: () => void }) {
+  return (
+    <Button.Root
+      onClick={(event) => {
+        onClose();
+        celebrate({ origin: event.currentTarget });
+      }}
+    >
+      Закрыть квартал
+    </Button.Root>
+  );
+}
+```
+
+## 6. Mistakes
+
+- `transition: all 0.3s ease` → list the properties, use tokens.
+- A spinner where the content's shape is known → `Skeleton` in that shape inside `Crossfade`.
+- Content that appears or disappears with no transition (`{loading ? <A/> : <B/>}`) → `Crossfade`.
+- Bounce, elastic or a spring that overshoots → `emphasized` lands without passing the target.
+- Animating the highlight of a list moved by arrow keys, or a command palette → keep it still.
+- Hover lift on table rows or list items → fill change only.
+- Your own hover rotate, spin or bounce on an icon, or an icon from another library that does not move
+  → a kit icon: it already plays its gesture with its host. A glyph repeated in every row of a long
+  list → `animated={false}`.
+- Your own fade-in keyframes on a whole page or every card → no; first render is still, except a
+  short staggered group.
+- Confetti for a saved form → «Сохранено» on the button when the form stays on screen, a notification
+  when it goes away; confetti only for rare milestones.
+- An overlay mounted conditionally (`{open && <Modal.Root>}`) or with a `key` that changes per record →
+  it vanishes without its exit. Keep the `Root` mounted and drive it with `open`; the kit holds the last
+  content on screen while the exit plays.
+- Re-implementing a check, a toggle or an indicator with your own CSS → use the kit component; it
+  already moves.
+- JS-driven animation without a `prefers-reduced-motion` check → check it, or use CSS tokens.

package/dist/skill/patterns/chat.module.css

@@ -0,0 +1,33 @@
+/* Chat: the page fills the app panel (`AppShell.Root fillViewport` + `PageContent.Root fill`); each
+   pane is a card with a scrolling region. */
+
+.paneCard {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.pane {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.dialogs {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+  margin: 0;
+  padding: var(--prime-space-2);
+  list-style: none;
+}
+
+/* A dialog row: avatar and name at the start, the unread count at the end. */
+.dialog {
+  justify-content: flex-start;
+}
+
+.dialogText {
+  display: grid;
+  flex: 1;
+  min-width: 0;
+}