prime-ui-kit 0.3.1 → 0.4.0

package/src/components/button/examples/icon-composition.tsx

@@ -0,0 +1,63 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * `Button.Icon` left, right, and icon-only with `aria-label` on root; primary filled and neutral stroke rows
+ * (parity with `playground/snippets/button/composition.tsx`).
+ */
+export default function IconCompositionExample() {
+  const rowStyle = {
+    display: "flex" as const,
+    flexWrap: "wrap" as const,
+    gap: "var(--prime-sys-spacing-m)",
+    alignItems: "center" as const,
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <div style={rowStyle}>
+        <Button.Root variant="primary" mode="filled" size="m">
+          <Button.Icon>
+            <Icon name="field.email" size="s" />
+          </Button.Icon>
+          Button primary icon left
+        </Button.Root>
+        <Button.Root variant="primary" mode="filled" size="m">
+          Button primary icon right
+          <Button.Icon>
+            <Icon name="action.close" size="s" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root variant="primary" mode="filled" size="m" aria-label="Button primary icon only">
+          <Button.Icon>
+            <Icon name="action.close" size="s" />
+          </Button.Icon>
+        </Button.Root>
+      </div>
+      <div style={rowStyle}>
+        <Button.Root variant="neutral" mode="stroke" size="m">
+          <Button.Icon>
+            <Icon name="field.email" size="s" tone="subtle" />
+          </Button.Icon>
+          Button icon left
+        </Button.Root>
+        <Button.Root variant="neutral" mode="stroke" size="m">
+          Button icon right
+          <Button.Icon>
+            <Icon name="action.close" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root variant="neutral" mode="stroke" size="m" aria-label="Button icon only">
+          <Button.Icon>
+            <Icon name="action.close" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/button/examples/marketing-cta.tsx

@@ -0,0 +1,26 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * Marketing CTA stack: strong primary (`fancy` + `xl`), secondary outline with trailing icon.
+ */
+export default function MarketingCtaExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <Button.Root variant="primary" mode="fancy" size="xl" fullWidth>
+        Start free trial
+      </Button.Root>
+      <Button.Root variant="neutral" mode="stroke" size="l" fullWidth>
+        Compare plans
+        <Button.Icon>
+          <Icon name="nav.chevronRight" size="s" tone="subtle" />
+        </Button.Icon>
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button/examples/sizes-ladder.tsx

@@ -0,0 +1,30 @@
+import { Button } from "prime-ui-kit";
+
+/**
+ * Size ladder: `s`–`xl` at `variant="primary"` `mode="filled"` (parity with `playground/snippets/button/sizes.tsx`).
+ */
+export default function SizesLadderExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <Button.Root variant="primary" mode="filled" size="s">
+        Button s
+      </Button.Root>
+      <Button.Root variant="primary" mode="filled" size="m">
+        Button m
+      </Button.Root>
+      <Button.Root variant="primary" mode="filled" size="l">
+        Button l
+      </Button.Root>
+      <Button.Root variant="primary" mode="filled" size="xl">
+        Button xl
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button/examples/toolbar.tsx

@@ -0,0 +1,38 @@
+import { Button, Icon } from "prime-ui-kit";
+
+/**
+ * Dense toolbar: ghost neutrals for secondary actions, primary action with icon + label.
+ */
+export default function ToolbarExample() {
+  return (
+    <div
+      role="toolbar"
+      aria-label="Document actions"
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-s)",
+        alignItems: "center",
+      }}
+    >
+      <Button.Root variant="neutral" mode="ghost" size="m">
+        Bold
+      </Button.Root>
+      <Button.Root variant="neutral" mode="ghost" size="m">
+        Italic
+      </Button.Root>
+      <Button.Root variant="neutral" mode="ghost" size="m" aria-label="Insert link">
+        <Button.Icon>
+          <Icon name="field.email" size="s" tone="subtle" />
+        </Button.Icon>
+      </Button.Root>
+      <span style={{ flex: 1, minWidth: "var(--prime-sys-spacing-m)" }} aria-hidden />
+      <Button.Root variant="primary" mode="filled" size="m">
+        <Button.Icon>
+          <Icon name="action.upload" size="s" />
+        </Button.Icon>
+        Publish
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button-group/COMPONENT.md

@@ -2,7 +2,18 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
+
+- **What:** `ButtonGroup` groups native **`<button>`** segments that share one outline, inner dividers, and corner radius only on the outer shell; **`Root`** sets **`size`** and optional **`orientation`**, wraps **`ControlSizeProvider`**.
+- **Pieces:** namespace **`ButtonGroup.Root`**, **`ButtonGroup.Item`**, **`ButtonGroup.Icon`** (decorative wrapper, **`aria-hidden`**); **`Item`** must live inside **`Root`**.
+- **Selection look:** optional **`pressed`** on **`Item`** → **`data-state="on"`** and **`aria-pressed`** when boolean; mutual exclusivity is **parent state**, not enforced by the component.
+- **Forms:** **`Item`** supports **`type="button" | "submit" | "reset"`** (default **`"button"`**).
+- **Defaults:** **`size="m"`**, **`orientation="horizontal"`**; no **`variant`** or built-in **`fullWidth`** — widen via layout/`className` on **`Root`** and items if needed.
+- **Prefer something else:** true **one-of-N** field with radio semantics → [Radio](../radio/COMPONENT.md); kit segmented control API → [SegmentedControl](../segmented-control/COMPONENT.md); single CTA → [Button](../button/COMPONENT.md).
+
+## Extended
+
+### About
 
 A row or column of native buttons that share one bordered outline: one size tier for the whole group, internal dividers, and rounded corners only on the outer edges.
 
@@ -13,7 +24,31 @@ A row or column of native buttons that share one bordered outline: one size tier
 - **Do not use** when the kit’s segmented switcher API fits better — see [SegmentedControl](../segmented-control/COMPONENT.md).
 - **Do not use** for a single standalone call to action — use [Button](../button/COMPONENT.md) instead.
 
-## Composition
+### Scenarios (examples)
+
+Copy-ready demos live under **`examples/`** (same folder as this file):
+
+| Scenario | File | Idea |
+|----------|------|------|
+| Editor toolbar | [`examples/editor-toolbar.tsx`](examples/editor-toolbar.tsx) | Icon segments + optional **`pressed`** for active format; **`aria-label`** on icon-only **`Item`**. |
+| Form footer | [`examples/form-footer.tsx`](examples/form-footer.tsx) | **`type="submit"`** / **`type="reset"`** (or **`button`**) in one group; name **`Root`** with **`aria-label`**. |
+| View switcher | [`examples/view-switcher.tsx`](examples/view-switcher.tsx) | Single choice in React state; exactly one **`pressed={true}`** at a time. |
+| Wizard actions | [`examples/wizard-actions.tsx`](examples/wizard-actions.tsx) | Step **Back** / **Next** as a horizontal group; **`disabled`** on **Back** for the first step. |
+| Full width | [`examples/full-width.tsx`](examples/full-width.tsx) | **`Root`** `className` for container width (e.g. **`w-full`**); **`flex-1`** / **`min-w-0`** on **`Item`** to split the row (no built-in **`fullWidth`** prop). |
+
+Playground demos match `playground/sections/ButtonGroupSection.tsx` (order and `?raw` sources):
+
+| Snippet | File | Idea |
+|---------|------|------|
+| Sizes | [`playground/snippets/button-group/sizes.tsx`](../../../playground/snippets/button-group/sizes.tsx) | Four rows **`s`**, **`m`**, **`l`**, **`xl`**; each row is a real three-segment group. |
+| States | [`states.tsx`](../../../playground/snippets/button-group/states.tsx) | Default, **`pressed`**, **`disabled`** in one group. |
+| Orientation | [`orientation.tsx`](../../../playground/snippets/button-group/orientation.tsx) | Default horizontal vs **`orientation="vertical"`**. |
+| Controlled | [`controlled.tsx`](../../../playground/snippets/button-group/controlled.tsx) | Parent state; exactly one **`pressed={true}`** at a time (**day** / **week** / **month**). |
+| Composition | [`composition.tsx`](../../../playground/snippets/button-group/composition.tsx) | **`ButtonGroup.Icon`**, **`aria-label`** on icon-only **`Item`**, text + chevron, two toolbar rows. |
+| Full width | [`full-width.tsx`](../../../playground/snippets/button-group/full-width.tsx) | **`Root`** **`className="w-full"`**; items **`className="min-w-0 flex-1"`** inside a bounded container. |
+| Form features | [`form-features.tsx`](../../../playground/snippets/button-group/form-features.tsx) | Form with **`type="submit"`** and **`type="reset"`** segments. |
+
+### Composition
 
 - **`ButtonGroup`** is a namespace object: **`Root`**, **`Item`**, **`Icon`**.
 - **`ButtonGroup.Root`** — wrapper `div` with `data-size={size}`; for `orientation="vertical"` it sets `data-orientation="vertical"`. It provides group context and **`ControlSizeProvider`**, so nested controls inherit the same size tier.
@@ -35,7 +70,7 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
 - There is no `variant` prop: appearance is always the shared-outline segment style; vary **`size`**, **`orientation`**, **`pressed`**, and **`disabled`** instead.
 - **`pressed`**: when `true`, the segment gets `data-state="on"` and `aria-pressed="true"`; when `false`, you get `aria-pressed="false"`; when omitted, `aria-pressed` is not set.
@@ -45,9 +80,9 @@ export function Example() {
 - Segments always render as **`<button>`** (no `asChild`); there is no built-in **`fullWidth`** — widen the group with layout on the root and items if needed.
 - **`ButtonGroup.Item`** supports **`type="button" | "submit" | "reset"`** (default **`"button"`**) for correct form behavior.
 
-## API
+### API
 
-### ButtonGroup.Root
+#### ButtonGroup.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -57,7 +92,7 @@ export function Example() {
 | className | `string` | — | no | Additional class on the root element. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Other div attributes (e.g. `aria-label`, `role`, event handlers). |
 
-### ButtonGroup.Item
+#### ButtonGroup.Item
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -68,7 +103,7 @@ export function Example() {
 | className | `string` | — | no | Additional class on the button. |
 | …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | no | Other native button attributes. |
 
-### ButtonGroup.Icon
+#### ButtonGroup.Icon
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -76,8 +111,33 @@ export function Example() {
 | className | `string` | — | no | Additional class on the wrapper span. |
 | …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | no | Other span attributes (not `children`). |
 
-## Related
+### Related
 
 - [Button](../button/COMPONENT.md) — single actions, variants, loading.
 - [SegmentedControl](../segmented-control/COMPONENT.md) — alternative segmented switcher API.
 - [Radio](../radio/COMPONENT.md) — form “one of N” with radio semantics.
+
+## LLM note
+
+```yaml
+component: ButtonGroup
+exports: [ButtonGroup.Root, ButtonGroup.Item, ButtonGroup.Icon]
+defaults: { size: m, orientation: horizontal }
+behavior:
+  items_are: native button elements
+  pressed: optional boolean per Item; parent owns mutual exclusion for single-choice UX
+  no_variant: true
+  no_fullWidth_prop: true  # use layout / className on Root and Items
+forms:
+  Item_type: [button, submit, reset]
+a11y:
+  name_Root: aria-label or aria-labelledby when no visible label
+  icon_only_Item: aria-label on Item (not on Icon)
+anti_patterns:
+  - Using as native radio group for form submit semantics → Radio
+  - Single CTA → Button
+  - Prefer SegmentedControl when that composable API is a better fit
+doc_examples_dir: src/components/button-group/examples/
+playground_snippets: playground/snippets/button-group/
+playground_snippet_files: [sizes, states, orientation, controlled, composition, full-width, form-features]
+```

package/src/components/button-group/examples/editor-toolbar.tsx

@@ -0,0 +1,46 @@
+import { Bold, Italic, Underline } from "lucide-react";
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Editor toolbar: icon segments share one outline; active format uses `pressed`.
+ * Meaning for assistive tech: `aria-label` on each icon-only `Item`.
+ */
+export default function EditorToolbarExample() {
+  const [marks, setMarks] = React.useState({ bold: true, italic: false, underline: false });
+
+  return (
+    <ButtonGroup.Root aria-label="Text formatting" size="m">
+      <ButtonGroup.Item
+        aria-label="Bold"
+        pressed={marks.bold}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, bold: !m.bold }))}
+      >
+        <ButtonGroup.Icon>
+          <Bold />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        aria-label="Italic"
+        pressed={marks.italic}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, italic: !m.italic }))}
+      >
+        <ButtonGroup.Icon>
+          <Italic />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        aria-label="Underline"
+        pressed={marks.underline}
+        type="button"
+        onClick={() => setMarks((m) => ({ ...m, underline: !m.underline }))}
+      >
+        <ButtonGroup.Icon>
+          <Underline />
+        </ButtonGroup.Icon>
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/form-footer.tsx

@@ -0,0 +1,19 @@
+import { ButtonGroup } from "prime-ui-kit";
+
+/**
+ * Form footer: native submit + reset in one segmented control.
+ */
+export default function FormFooterExample() {
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+      }}
+    >
+      <ButtonGroup.Root aria-label="Save or reset draft" size="m">
+        <ButtonGroup.Item type="submit">Save</ButtonGroup.Item>
+        <ButtonGroup.Item type="reset">Reset</ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </form>
+  );
+}

package/src/components/button-group/examples/full-width.tsx

@@ -0,0 +1,22 @@
+import { ButtonGroup } from "prime-ui-kit";
+
+/**
+ * Full width: no dedicated prop — width on Root, equal segments via flex-1 on Items.
+ */
+export default function FullWidthExample() {
+  return (
+    <div className="w-full max-w-md">
+      <ButtonGroup.Root aria-label="Plan tier" className="w-full" size="m">
+        <ButtonGroup.Item className="min-w-0 flex-1" type="button">
+          Basic
+        </ButtonGroup.Item>
+        <ButtonGroup.Item className="min-w-0 flex-1" pressed type="button">
+          Pro
+        </ButtonGroup.Item>
+        <ButtonGroup.Item className="min-w-0 flex-1" type="button">
+          Business
+        </ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </div>
+  );
+}

package/src/components/button-group/examples/view-switcher.tsx

@@ -0,0 +1,25 @@
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+type ViewMode = "list" | "grid" | "board";
+
+/**
+ * View switcher: one active segment; state lives in the parent.
+ */
+export default function ViewSwitcherExample() {
+  const [mode, setMode] = React.useState<ViewMode>("list");
+
+  return (
+    <ButtonGroup.Root aria-label="View layout" size="m">
+      <ButtonGroup.Item pressed={mode === "list"} type="button" onClick={() => setMode("list")}>
+        List
+      </ButtonGroup.Item>
+      <ButtonGroup.Item pressed={mode === "grid"} type="button" onClick={() => setMode("grid")}>
+        Grid
+      </ButtonGroup.Item>
+      <ButtonGroup.Item pressed={mode === "board"} type="button" onClick={() => setMode("board")}>
+        Board
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/wizard-actions.tsx

@@ -0,0 +1,30 @@
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+const STEP_LAST = 2;
+
+/**
+ * Wizard step actions: Back disabled on first step; Next advances (demo stops at last step).
+ */
+export default function WizardActionsExample() {
+  const [step, setStep] = React.useState(0);
+
+  return (
+    <ButtonGroup.Root aria-label="Wizard navigation" size="m">
+      <ButtonGroup.Item
+        disabled={step === 0}
+        type="button"
+        onClick={() => setStep((s) => Math.max(0, s - 1))}
+      >
+        Back
+      </ButtonGroup.Item>
+      <ButtonGroup.Item
+        disabled={step >= STEP_LAST}
+        type="button"
+        onClick={() => setStep((s) => Math.min(STEP_LAST, s + 1))}
+      >
+        Next
+      </ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}