prime-ui-kit 0.7.13 → 0.9.0

package/src/components/code-block/COMPONENT.md

@@ -1,103 +1,110 @@
 # CodeBlock
 
-## Canonical
+**Category:** data-display
 
-- **API:** `CodeBlock.Root` only. Required prop: **`code`** (string). Optional **`colorScheme`**: `"light"` (default) or `"dark"` for `data-theme` on the root `pre`.
-- **Rendering:** `pre` + inner `code` filled via **`highlightTsxHtml(code.trimEnd())`** and **`dangerouslySetInnerHTML`**. Do not pass **`children`** or **`dangerouslySetInnerHTML`** (omitted from props).
-- **Trust:** only **trusted** `code` strings (constants, vetted CMS, sanitized server output). Never pass raw user HTML/TSX here.
-- **Language:** heuristic **TS/TSX** highlighting — not a full grammar. JSON, stacks, and other text still render; token classes may be partial.
-- **Sizing:** no **`size`** prop; **`font-size`** / **`line-height`** inherit from the parent. Layout wrappers and typography tokens control rhythm.
-- **Extras:** **`className`** and native **`pre`** attributes ( **`id`**, ARIA, **`data-*`**, handlers) via **`…rest`**.
+> A static TypeScript / TSX snippet with syntax highlighting, on a sunken panel or bare inside a host.
 
-## Extended
+## When to use
+- Code samples in docs, settings ("API key usage") and onboarding.
+- Shell commands and config fragments (long lines scroll inside).
+- An API response sample next to its description.
 
-### About
+## When not to use
+- A keyboard key or shortcut → use [Kbd](../kbd/COMPONENT.md).
+- Editable code or text → use [Textarea](../textarea/COMPONENT.md).
+- An inline identifier inside a sentence → use a plain `<code>` element in text ([Typography](../typography/COMPONENT.md)).
+- A live preview with a code tab → use [ExampleFrame](../example-frame/COMPONENT.md).
 
-`CodeBlock` is a static, read-only presentation component: it shows a source string with kit-aligned monospace and a light or dark token palette.
-
-- **Use** for partner docs, marketing, in-app help, API reference cards, integration guides, or internal tools when the snippet is **trusted** and TS/TSX-oriented highlighting is enough.
-- **Use** with surrounding copy ([Typography](../typography/COMPONENT.md), headings, captions) for documentation-style layouts.
-- **Do not use** for **untrusted** input (inner HTML is injected).
-- **Do not use** when you need another language grammar, line numbers, copy-to-clipboard, or tabs — implement those in the app layer.
-- **Do not use** for an editable or primary focus target for typing (use inputs or an editor).
-
-### Composition
-
-- Public API: **`CodeBlock`** object with **`Root`**.
-- **`Root`** renders a **`pre`**; highlighted markup is a single inner **`code`** (do not supply **`children`**).
-- Pass source as **`code`**. Optional **`colorScheme`** sets highlighting palette / **`data-theme`** on **`pre`**.
-
-### Scenarios (playground)
-
-Same order as `playground/sections/CodeBlockSection.tsx`. Snippets use the `@/` alias and may use `usePlaygroundTheme` for `colorScheme`.
-
-| Scenario | Snippet |
-|----------|---------|
-| Sizes — wrapper `font-size` / `line-height`; no `size` prop | [`sizes.tsx`](../../../playground/snippets/code-block/sizes.tsx) |
-| Variants — `colorScheme` light and dark side by side | [`variants.tsx`](../../../playground/snippets/code-block/variants.tsx) |
-| Controlled — `code` from parent state; switch between snippets | [`controlled.tsx`](../../../playground/snippets/code-block/controlled.tsx) |
-| Composition — documentation-style card (Typography + code) | [`composition.tsx`](../../../playground/snippets/code-block/composition.tsx) |
-| Full width — narrow column, `codeBlockFullBleed`, horizontal scroll | [`full-width.tsx`](../../../playground/snippets/code-block/full-width.tsx) |
-| Features — `id`, `aria-label`, `data-*`, trailing spaces + `trimEnd` | [`features.tsx`](../../../playground/snippets/code-block/features.tsx) |
-
-### Package examples (`examples/`)
-
-Recipes import **`prime-ui-kit`** (no playground path alias).
-
-| Scenario | File |
-|----------|------|
-| Minimal usage | [`minimal.tsx`](./examples/minimal.tsx) |
-| Controlled — `code` из состояния (рецепт на `ButtonGroup`) | [`controlled.tsx`](./examples/controlled.tsx) |
-| API response preview (JSON body) | [`api-response-preview.tsx`](./examples/api-response-preview.tsx) |
-| Config snippet (TS config) | [`config-snippet.tsx`](./examples/config-snippet.tsx) |
-| Error stack / log | [`error-stack.tsx`](./examples/error-stack.tsx) |
-| Tutorial step (copy + snippet) | [`tutorial-step.tsx`](./examples/tutorial-step.tsx) |
-
-### Minimal example
+## Import
+```tsx
+import { CodeBlock } from "prime-ui-kit";
+```
+Exported types: `CodeBlockRootProps`, `CodeBlockVariant`, `CodeBlockColorScheme`.
+
+## API
+
+### CodeBlock.Root
+Renders `<pre><code>…</code></pre>`. Forwards `ref` to the `<pre>`. No `asChild`. Leaf component.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` | — (required) | TS/TSX source; trailing whitespace is trimmed, then highlighted (the source is escaped). |
+| `variant` | `"soft" \| "ghost"` (`CodeBlockVariant`) | `"soft"` | Treatment. |
+| `colorScheme` | `"light" \| "dark"` (`CodeBlockColorScheme`) | — (follows the page theme) | Forces a theme for this block only (`data-theme` on the `<pre>`). |
+| `tabIndex` | `number` | `0` for `soft`, none for `ghost` | Keeps a scrolling soft block reachable from the keyboard; pass `-1` when it never overflows. |
+| `className` | `string` | — | Extra class on the `<pre>`. |
+
++ native `<pre>` props except `children` and `dangerouslySetInnerHTML` (the markup is produced by the component).
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | `fill-muted` panel, radius 8, padding 12 × 16, `code` text role (13/20 mono), horizontal scroll, Tab stop | Standalone snippets anywhere | yes |
+| `ghost` | Bare `pre`: no padding, transparent, font size and line height inherited from the host | Inside a host that draws its own panel (a tinted callout, a custom card) | |
+
+### colorScheme
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| unset | Token colors and fill follow the page theme | Normal case | yes |
+| `light` | Light palette for the block; soft fill switches to `bg-raised` of that scheme | A light code sample inside a dark page | |
+| `dark` | Dark palette for the block; soft fill switches to `bg-raised` of that scheme | A dark "terminal" sample inside a light page | |
+
+Syntax tokens: keywords purple (weight 500), strings teal, numbers orange, JSX tags blue, comments muted italic — all from palette text tokens, so they pass contrast in both themes.
+
+**Combinations**
+- Recommended: `soft` with no `colorScheme`; `aria-label` on blocks that are the only content of a region.
+- Allowed but rare: `soft` + `colorScheme="dark"` for a terminal look; `ghost` inside a custom panel.
+- Avoid: `ghost` on a bare page (no box, no padding, nothing separates the code); several forced schemes on one screen.
+
+**Sizes**
+CodeBlock has no `size`: `soft` uses the `code` text role, `ghost` inherits the host's type.
+
+## States
+| State / attribute | Driven by | Notes |
+|---|---|---|
+| `data-variant` | `variant` | Always set (default `soft`). |
+| `data-theme="light" \| "dark"` | `colorScheme` | Re-scopes the palette for the block. |
+| focus-visible | keyboard focus on a `soft` block | Inset focus ring. |
+
+No interactive state; `code` is the only content and can come from state (re-highlighted on change).
+
+## Layout & spacing
+- `max-width: 100%`; the block takes the column width and long lines scroll horizontally (`white-space: pre`, tab size 2).
+- Heading / text → code block: `--prime-space-2` to `--prime-space-4`.
+- Width comes from the layout; constrain the column (`max-width: var(--prime-layout-reading-max-width)` for docs), not the block.
+
+## Accessibility
+- Native `<pre>` / `<code>`; screen readers read the text.
+- A `soft` block is focusable (`tabIndex=0`) so overflowing content can be scrolled with arrow keys; pass `tabIndex={-1}` when it never overflows.
+- Give standalone blocks an `aria-label` ("Команда установки").
+- No `labels` keys.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [variants.tsx](examples/variants.tsx) | `soft` vs `ghost` inside a host panel | Choosing the treatment |
+| [color-scheme.tsx](examples/color-scheme.tsx) | `colorScheme="light"` and `"dark"` | A fixed-scheme sample |
+| [surfaces.tsx](examples/surfaces.tsx) | One-line command on canvas, card and floating layer | Checking contrast on any surface |
+| [controlled.tsx](examples/controlled.tsx) | `code` from state switched by a ButtonGroup | Alternative snippets |
+| [long-lines.tsx](examples/long-lines.tsx) | Long shell command scrolling inside a narrow column | Commands and configs |
+| [api-docs.tsx](examples/api-docs.tsx) | Heading, description and response sample | Docs and integration guides |
 
 ```tsx
 import { CodeBlock } from "prime-ui-kit";
 
-export function Example() {
-  return <CodeBlock.Root code='export const n = 1;' />;
+export function InstallCommand() {
+  return <CodeBlock.Root code="bun add prime-ui-kit" aria-label="Команда установки" />;
 }
 ```
 
-### Rules
-
-- **`code`** is required. The implementation applies **`trimEnd()`** on the whole string before highlighting; per-line content is preserved except trailing whitespace at the end of the string.
-- **`colorScheme`** defaults to **`"light"`**; use **`"dark"`** on dark surfaces so tokens stay readable.
-- **Security:** HTML comes from **`highlightTsxHtml`** only as wrapped **`code`** content; treat **`code`** as trusted.
-- **Highlighting** is TS/TSX-oriented; edge syntax may not match expectations.
-- **Accessibility:** static prose; add **`aria-label`**, **`aria-describedby`**, or headings via **`…rest`** when assistive tech needs an explicit name.
-- **Focus:** no default **`tabIndex`**; add only if your UX requires a focusable static block.
-
-### API
-
-#### CodeBlock.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `code` | `string` | — | Yes | TS/TSX-oriented source; trailing whitespace trimmed with `trimEnd()` before highlighting. |
-| `colorScheme` | `CodeBlockColorScheme` (`"light" \| "dark"`) | `"light"` | No | Token palette / `data-theme` on the root `pre`. |
-| `className` | `string` | — | No | Additional class on the root `pre`. |
-| `…rest` | `Omit<React.HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | No | Other native `pre` attributes. `children` and `dangerouslySetInnerHTML` are omitted. |
-
-The package also exports **`CodeBlockColorScheme`** and **`CodeBlockRootProps`**.
-
-### Related
-
-- [Typography](../typography/COMPONENT.md) — headings and body around snippets.
-- [Button](../button/COMPONENT.md) — switching the active snippet from parent state (playground `controlled.tsx`).
-- [ButtonGroup](../button-group/COMPONENT.md) — segmented control for switching `code` ([`examples/controlled.tsx`](./examples/controlled.tsx)).
-- [Segmented control](../segmented-control/COMPONENT.md) — compact scenario switching.
-- [Kbd](../kbd/COMPONENT.md) — shortcut hints beside prose.
-
-## Note for LLM assistants
-
-- Recommend **`CodeBlock.Root`** only; **`code`** must be a **trusted** string — flag any pattern that pipes user or CMS content without sanitization.
-- Do not suggest **`children`**, **`dangerouslySetInnerHTML`**, or wrapping the kit block to replace inner HTML.
-- Prefer **`colorScheme="dark"`** when the parent surface uses dark **`data-theme`** or dark backgrounds so contrast stays valid.
-- If the user asks for copy button, line numbers, tabs, or non-TS languages, say these are **out of kit scope** and belong in the app (or a different library).
-- For JSON-only bodies, remind that highlighting is **TS/TSX heuristic**; formatting as a template or TS-adjacent string is fine.
-- **`trimEnd()`** applies to the **entire** `code` string once, not each line.
+## Mistakes
+- Passing JSX children → pass the source string to `code`.
+- `<pre style={{ background: … }}>` for code → use `CodeBlock.Root`.
+- `variant="ghost"` directly on the page → use `soft`, or wrap `ghost` in a panel.
+- Wrapping a soft block in another bordered box → the block is already a filled panel.
+## Related
+- [Kbd](../kbd/COMPONENT.md) — keys and shortcuts.
+- [ExampleFrame](../example-frame/COMPONENT.md) — live preview with source.
+- [Typography](../typography/COMPONENT.md) — headings and text around code.

package/src/components/code-block/examples/api-docs.tsx

@@ -0,0 +1,31 @@
+/** API documentation fragment: a Typography heading and description, then a response sample with `aria-label`. Use for docs and integration guides. */
+
+import { CodeBlock, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const RESPONSE = `{
+  "id": "ord_8f2a",
+  "total": 14990,
+  "currency": "RUB",
+  "items": [{ "sku": "sku-12", "qty": 2 }]
+}`;
+
+export default function CodeBlockApiDocsExample() {
+  const titleId = React.useId();
+
+  return (
+    <section className={styles.doc} aria-labelledby={titleId}>
+      <div className={styles.docText}>
+        <Typography.Root as="h3" variant="title-s" id={titleId}>
+          GET /orders/:id
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-m" tone="secondary">
+          Возвращает заказ со списком позиций. Сумма в копейках.
+        </Typography.Root>
+      </div>
+      <CodeBlock.Root code={RESPONSE} aria-label="Пример ответа GET /orders/:id" />
+    </section>
+  );
+}

package/src/components/code-block/examples/color-scheme.tsx

@@ -0,0 +1,27 @@
+/** Without `colorScheme` the block follows the page theme; `light` / `dark` fix the scheme for the block only. Use a fixed scheme for a code sample that must look the same in both themes. */
+
+import { CodeBlock, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SAMPLE = `const retries = 3; // повторы при ошибке сети
+export const isReady = (status: "idle" | "busy") => status === "idle";`;
+
+export default function CodeBlockColorSchemeExample() {
+  return (
+    <div className={styles.grid}>
+      <div className={styles.cell}>
+        <Typography.Root variant="caption" tone="muted">
+          colorScheme=&quot;light&quot;
+        </Typography.Root>
+        <CodeBlock.Root code={SAMPLE} colorScheme="light" />
+      </div>
+      <div className={styles.cell}>
+        <Typography.Root variant="caption" tone="muted">
+          colorScheme=&quot;dark&quot;
+        </Typography.Root>
+        <CodeBlock.Root code={SAMPLE} colorScheme="dark" />
+      </div>
+    </div>
+  );
+}

package/src/components/code-block/examples/controlled.tsx

@@ -1,43 +1,38 @@
-import { ButtonGroup, CodeBlock, Typography } from "prime-ui-kit";
+/** `code` comes from state: a ButtonGroup switches the shown snippet. Use for tabs of alternative snippets (utility / hook, npm / bun). */
+
+import { ButtonGroup, CodeBlock } from "prime-ui-kit";
 import { useState } from "react";
 
-const SNIPPETS: [string, string][] = [
-  [
-    "Утилита",
-    `export function clamp(n: number, min: number, max: number) {
+import styles from "./examples.module.css";
+
+const SNIPPETS = {
+  utility: `export function clamp(n: number, min: number, max: number) {
   return Math.min(max, Math.max(min, n));
-}
-`,
-  ],
-  [
-    "React",
-    `import { useMemo } from "react";
+}`,
+  hook: `import { useId } from "react";
 
-export function useStableId(prefix: string) {
-  return useMemo(() => \`\${prefix}-\${Math.random().toString(36).slice(2)}\`, [prefix]);
-}
-`,
-  ],
-];
+export function useFieldIds(prefix: string) {
+  const id = useId();
+  return { input: \`\${prefix}-\${id}\`, hint: \`\${prefix}-\${id}-hint\` };
+}`,
+} as const;
+
+type SnippetKey = keyof typeof SNIPPETS;
 
-/** Проп `code` из состояния родителя: сегменты переключают два разных фрагмента (как в playground `controlled.tsx`). */
 export default function CodeBlockControlledExample() {
-  const [index, setIndex] = useState(0);
-  const [label, code] = SNIPPETS[index] ?? SNIPPETS[0];
+  const [active, setActive] = useState<SnippetKey>("utility");
 
   return (
-    <div>
-      <Typography.Root variant="body-compact" tone="muted" as="p">
-        Активный фрагмент: <strong>{label}</strong> (проп <code>code</code> из состояния).
-      </Typography.Root>
-      <ButtonGroup.Root size="s" aria-label="Выбор фрагмента кода">
-        {SNIPPETS.map(([title], i) => (
-          <ButtonGroup.Item key={title} pressed={i === index} onClick={() => setIndex(i)}>
-            {title}
-          </ButtonGroup.Item>
-        ))}
+    <div className={styles.column}>
+      <ButtonGroup.Root size="s" aria-label="Фрагмент">
+        <ButtonGroup.Item pressed={active === "utility"} onClick={() => setActive("utility")}>
+          Утилита
+        </ButtonGroup.Item>
+        <ButtonGroup.Item pressed={active === "hook"} onClick={() => setActive("hook")}>
+          Хук
+        </ButtonGroup.Item>
       </ButtonGroup.Root>
-      <CodeBlock.Root code={code} colorScheme="light" />
+      <CodeBlock.Root code={SNIPPETS[active]} />
     </div>
   );
 }

package/src/components/code-block/examples/examples.module.css

@@ -0,0 +1,52 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
+  gap: var(--prime-space-4);
+  width: 100%;
+}
+
+.cell {
+  display: grid;
+  align-content: start;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}
+
+/* A host that draws its own panel (its type comes from Typography caption): a ghost CodeBlock
+ * inherits the host's type and background. */
+.host {
+  padding: var(--prime-space-3) var(--prime-space-4);
+  overflow-x: auto;
+  border-radius: var(--prime-radius-m);
+  background: var(--prime-color-accent-soft);
+}
+
+.column {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: 100%;
+  min-width: 0;
+}
+
+.narrow {
+  display: grid;
+  gap: var(--prime-space-2);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+  min-width: 0;
+}
+
+/* Heading → text 8, text → code 16: the code sits in its own row of the outer grid. */
+.doc {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: var(--prime-layout-reading-max-width);
+  min-width: 0;
+}
+
+.docText {
+  display: grid;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}

package/src/components/code-block/examples/long-lines.tsx

@@ -0,0 +1,15 @@
+/** The block takes the column width and a long line scrolls inside it (Tab, then arrow keys). Use for shell commands and configs that must not wrap. */
+
+import { CodeBlock } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LONG_LINE = `docker run --rm -e NODE_ENV=production -p 8080:8080 -v "$(pwd)/data:/app/data" registry.example.com/billing-api:latest --config /app/data/config.yml`;
+
+export default function CodeBlockLongLinesExample() {
+  return (
+    <div className={styles.narrow}>
+      <CodeBlock.Root code={LONG_LINE} aria-label="Команда запуска контейнера" />
+    </div>
+  );
+}

package/src/components/code-block/examples/surfaces.tsx

@@ -0,0 +1,7 @@
+/** A one-line install command with `aria-label`; the `soft` fill reads on canvas, card and floating layers. Use as-is on any surface. */
+
+import { CodeBlock } from "prime-ui-kit";
+
+export default function CodeBlockSurfacesExample() {
+  return <CodeBlock.Root code={`bun add prime-ui-kit`} aria-label="Команда установки" />;
+}

package/src/components/code-block/examples/variants.tsx

@@ -0,0 +1,30 @@
+/** `soft` (default) is a sunken panel with padding and the `code` text role; `ghost` is a bare `pre` that takes type and background from a host panel. Use `ghost` only inside your own panel. */
+
+import { CodeBlock, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SAMPLE = `export function formatPrice(value: number) {
+  return new Intl.NumberFormat("ru-RU", { style: "currency", currency: "RUB" }).format(value);
+}`;
+
+export default function CodeBlockVariantsExample() {
+  return (
+    <div className={styles.grid}>
+      <div className={styles.cell}>
+        <Typography.Root variant="caption" tone="muted">
+          variant=&quot;soft&quot;
+        </Typography.Root>
+        <CodeBlock.Root code={SAMPLE} />
+      </div>
+      <div className={styles.cell}>
+        <Typography.Root variant="caption" tone="muted">
+          variant=&quot;ghost&quot; внутри своей панели
+        </Typography.Root>
+        <Typography.Root as="div" variant="caption" className={styles.host}>
+          <CodeBlock.Root code={SAMPLE} variant="ghost" />
+        </Typography.Root>
+      </div>
+    </div>
+  );
+}