prime-ui-kit 0.3.1 → 0.4.0

package/src/components/badge/examples/ecommerce-inventory.tsx

@@ -0,0 +1,35 @@
+import { Badge, Icon } from "prime-ui-kit";
+import type { CSSProperties } from "react";
+
+const row: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--prime-sys-spacing-s)",
+  alignItems: "center",
+};
+
+/** Product shelf: stock emphasis with `filled` / `light` / `lighter` / `stroke`. */
+export default function BadgeEcommerceInventoryExample() {
+  return (
+    <div style={row}>
+      <Badge.Root color="green" variant="filled" size="m">
+        In stock
+      </Badge.Root>
+      <Badge.Root color="orange" variant="light" size="m">
+        Low stock · 3 left
+      </Badge.Root>
+      <Badge.Root color="red" variant="lighter" size="m">
+        Out of stock
+      </Badge.Root>
+      <Badge.Root color="purple" variant="stroke" size="m">
+        Sale · 20% off
+      </Badge.Root>
+      <Badge.Root color="teal" variant="filled" size="m">
+        <Badge.Icon>
+          <Icon name="status.locked" />
+        </Badge.Icon>
+        Secure checkout
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/badge/examples/inbox-labels.tsx

@@ -0,0 +1,36 @@
+import { Badge, Icon } from "prime-ui-kit";
+import type { CSSProperties } from "react";
+
+const row: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--prime-sys-spacing-s)",
+  alignItems: "center",
+};
+
+/** Thread metadata: priority, unread-style emphasis, and channel type with `Badge.Icon`. */
+export default function BadgeInboxLabelsExample() {
+  return (
+    <div style={row}>
+      <Badge.Root color="red" variant="filled" size="m">
+        Urgent
+      </Badge.Root>
+      <Badge.Root color="blue" variant="light" size="m">
+        Unread
+      </Badge.Root>
+      <Badge.Root color="gray" variant="stroke" size="m">
+        Archived
+      </Badge.Root>
+      <Badge.Root color="sky" variant="lighter" size="m">
+        <Badge.Icon>
+          <Icon name="field.email" />
+        </Badge.Icon>
+        Newsletter
+      </Badge.Root>
+      <Badge.Root color="purple" variant="light" size="m">
+        <Badge.Dot />
+        VIP list
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/badge/examples/status-presence.tsx

@@ -0,0 +1,32 @@
+import { Badge } from "prime-ui-kit";
+import type { CSSProperties } from "react";
+
+const row: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--prime-sys-spacing-s)",
+  alignItems: "center",
+};
+
+/**
+ * Presence row: `variant="status"` sets `role="status"` and a built-in dot.
+ * Use `label` when visible text is not enough for screen readers.
+ */
+export default function BadgeStatusPresenceExample() {
+  return (
+    <div style={row}>
+      <Badge.Root variant="status" status="online" label="Alex Morgan is online" size="m">
+        Online
+      </Badge.Root>
+      <Badge.Root variant="status" status="offline" label="Alex Morgan is offline" size="m">
+        Offline
+      </Badge.Root>
+      <Badge.Root variant="status" status="away" label="Alex Morgan is away" size="m">
+        Away
+      </Badge.Root>
+      <Badge.Root variant="status" status="busy" label="Alex Morgan is busy" size="m">
+        Busy
+      </Badge.Root>
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -1,26 +1,10 @@
 # Banner
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+## Canonical
 
-## About
+In-flow announcement strip: `Banner.Root` (grid + optional dismiss) wraps `Banner.Content` (icon, title, optional description, optional actions). Control visibility by mounting the root or parent state—there is no `open` prop.
 
-An in-flow announcement strip: a root grid with a central content column and an optional dismiss control on the right. Use `status` and `variant` for semantic color and density; optional slots cover icon, title, description, and actions.
-
-- **Use** for persistent page- or section-level messages (policy, incident, feature, validation summary) where the user should read the text in context.
-- **Use** when you need optional actions (`Banner.Actions`) or dismiss without leaving the page.
-- **Use** `size` to align spacing and typography with surrounding controls (`ControlSizeProvider` context applies to `Banner.CloseButton`).
-- **Do not use** for transient overlay feedback; prefer [Notification](../notification/COMPONENT.md) or similar patterns.
-- **Do not use** as a substitute for [Modal](../modal/COMPONENT.md) or [Drawer](../drawer/COMPONENT.md) when the user must complete a blocking task.
-- **Do not use** decorative icons without `aria-hidden` (or an accessible name) when the icon is not redundant with the title.
-
-## Composition
-
-- `Banner.Root` is the outer `div` and size provider; pass `variant`, `status`, `size`, and optionally `onDismiss`.
-- Put primary copy inside `Banner.Content`. Typical order: `Banner.Icon` (optional), `Banner.Title`, `Banner.Description` (optional), `Banner.Actions` (optional).
-- `Banner.CloseButton` must be a **direct child** of `Banner.Root` (a sibling of `Banner.Content`, not nested inside `Content`). The implementation only scans **direct** children to decide whether to inject a default close button when `onDismiss` is set; a close control placed only inside `Banner.Content` does not suppress injection.
-- If `onDismiss` is provided and no direct child is `Banner.CloseButton`, the root appends a default close button that calls `onDismiss`.
-
-### Minimal example
+**Defaults:** `variant="filled"`, `status="information"`, `size="m"`.
 
 ```tsx
 import { Banner } from "prime-ui-kit";
@@ -36,7 +20,63 @@ export function Example() {
 }
 ```
 
-## Rules
+| Piece | Role |
+|--------|------|
+| `Banner.Root` | `variant`, `status`, `size`, `onDismiss`, passes control size to `Banner.CloseButton` |
+| `Banner.Content` | Center column: slots below |
+| `Banner.Icon` | Optional; use `as={Icon}` and `aria-hidden` when decorative |
+| `Banner.Title` / `Banner.Description` | Primary and supporting copy (`span`) |
+| `Banner.Actions` | Buttons / `LinkButton` |
+| `Banner.CloseButton` | **Direct child of `Banner.Root`** (sibling of `Banner.Content`), not nested inside `Content` |
+
+### Playground snippets
+
+Order matches [`playground/sections/BannerSection.tsx`](../../../playground/sections/BannerSection.tsx). Snippets import from `@/components/banner/Banner`; consumers use **`import { … } from "prime-ui-kit"`**.
+
+| File | Scenario |
+|------|----------|
+| `playground/snippets/banner/sizes.tsx` | `size` `s`–`xl` with `variant="light"` and `status="information"`. |
+| `playground/snippets/banner/variants.tsx` | `variant` `filled`, `light`, `lighter`, `stroke` at `status="information"`. |
+| `playground/snippets/banner/statuses.tsx` | `status` `information`, `warning`, `error`, `success`, `feature` at `variant="light"`. |
+| `playground/snippets/banner/controlled.tsx` | Visibility from React state: hide removes the root; external button shows again (no root `onDismiss` required). |
+| `playground/snippets/banner/composition.tsx` | Slots: `Banner.Icon` with `as`, title, description, `Banner.Actions` (`LinkButton`, `Button`); `size="l"`, `variant="stroke"`. |
+| `playground/snippets/banner/full-width.tsx` | Root fills parent width; narrow wrapper illustrates a card column or sidebar. |
+| `playground/snippets/banner/dismiss-patterns.tsx` | `onDismiss` only (auto close) · `Banner.CloseButton` only · both without duplicate injected control. |
+
+### Scenario examples (English)
+
+| File | Scenario |
+|------|----------|
+| [`examples/billing-alert.tsx`](examples/billing-alert.tsx) | Billing failure: `error` + `filled`, `onDismiss`, actions, `role="region"`. |
+| [`examples/maintenance.tsx`](examples/maintenance.tsx) | Downtime: `warning` + `stroke`, actions, region label. |
+| [`examples/cookie-consent-row.tsx`](examples/cookie-consent-row.tsx) | Consent: `information` + `lighter`, `onDismiss`, actions. |
+| [`examples/feature-promo.tsx`](examples/feature-promo.tsx) | Promo: `feature` + `lighter`, `onDismiss`, actions. |
+| [`examples/controlled-visibility.tsx`](examples/controlled-visibility.tsx) | Controlled show/hide by conditional render (mirrors `controlled.tsx` snippet). |
+| [`examples/dismiss-close-button.tsx`](examples/dismiss-close-button.tsx) | `Banner.CloseButton` as direct root child without `onDismiss` (mirrors manual-dismiss branch of `dismiss-patterns.tsx`). |
+
+---
+
+## Extended
+
+### About
+
+An in-flow announcement strip: a root grid with a central content column and an optional dismiss control on the right. Use `status` and `variant` for semantic color and density; optional slots cover icon, title, description, and actions.
+
+- **Use** for persistent page- or section-level messages (policy, incident, feature, validation summary) where the user should read the text in context.
+- **Use** when you need optional actions (`Banner.Actions`) or dismiss without leaving the page.
+- **Use** `size` to align spacing and typography with surrounding controls (`ControlSizeProvider` context applies to `Banner.CloseButton`).
+- **Do not use** for transient overlay feedback; prefer [Notification](../notification/COMPONENT.md) or similar patterns.
+- **Do not use** as a substitute for [Modal](../modal/COMPONENT.md) or [Drawer](../drawer/COMPONENT.md) when the user must complete a blocking task.
+- **Do not use** decorative icons without `aria-hidden` (or an accessible name) when the icon is not redundant with the title.
+
+### Composition
+
+- `Banner.Root` is the outer `div` and size provider; pass `variant`, `status`, `size`, and optionally `onDismiss`.
+- Put primary copy inside `Banner.Content`. Typical order: `Banner.Icon` (optional), `Banner.Title`, `Banner.Description` (optional), `Banner.Actions` (optional).
+- `Banner.CloseButton` must be a **direct child** of `Banner.Root` (a sibling of `Banner.Content`, not nested inside `Content`). The implementation only scans **direct** children to decide whether to inject a default close button when `onDismiss` is set; a close control placed only inside `Banner.Content` does not suppress injection.
+- If `onDismiss` is provided and no direct child is `Banner.CloseButton`, the root appends a default close button that calls `onDismiss`.
+
+### Rules
 
 - There is no `open` / `visible` prop: mount or unmount the root (or hide it with parent state) to show or hide the strip.
 - `variant` defaults to `filled`; `status` to `information`; `size` to `m`. `stroke` uses a neutral surface with a status-colored bottom accent bar.
@@ -46,9 +86,9 @@ export function Example() {
 - `Banner.Title` and `Banner.Description` render as `span` elements; keep markup intentional if you nest interactive elements.
 - `Banner.Icon` is driven by the `as` prop (not `asChild` on the root).
 
-## API
+### API
 
-### Banner.Root
+#### Banner.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -60,7 +100,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Typically `Banner.Content` and optionally `Banner.CloseButton`. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the root `div` (e.g. `id`, `role`, ARIA). |
 
-### Banner.Content
+#### Banner.Content
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -68,7 +108,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Icon, title, description, and/or actions. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the inner `div`. |
 
-### Banner.Icon
+#### Banner.Icon
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -77,7 +117,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Content when using the default element or a custom wrapper. |
 | …rest | props of `T` without `as` and `className` | — | No | Forwarded to the element chosen by `as`. |
 
-### Banner.Title
+#### Banner.Title
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -85,7 +125,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Primary heading text. |
 | …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Native `span` attributes. |
 
-### Banner.Description
+#### Banner.Description
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -93,7 +133,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Supporting text. |
 | …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Native `span` attributes. |
 
-### Banner.Actions
+#### Banner.Actions
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -101,7 +141,7 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Action controls (e.g. `Button`, `LinkButton`). |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the row `div`. |
 
-### Banner.CloseButton
+#### Banner.CloseButton
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -110,9 +150,23 @@ export function Example() {
 | children | `React.ReactNode` | — | No | Button content; defaults to a cross icon when omitted. |
 | …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | No | Other button props; `size` is derived from banner context. |
 
-## Related
+### Playground alignment
+
+Matrix demos (`sizes`, `variants`, `statuses`, `controlled`, `composition`, `full-width`, `dismiss-patterns`) are maintained next to [`BannerSection.tsx`](../../../playground/sections/BannerSection.tsx); keep this doc table and snippet filenames in sync when the playground order or scenarios change.
+
+### Related
 
 - [Button](../button/COMPONENT.md) — actions inside `Banner.Actions`; `Banner.CloseButton` wraps `Button.Root` (ghost neutral).
 - [LinkButton](../link-button/COMPONENT.md) — text-style navigation actions in the strip.
 - [Typography](../typography/COMPONENT.md) — surrounding captions or body copy outside the banner slots.
 - [Notification](../notification/COMPONENT.md) — transient or stacked overlay messages instead of an in-flow strip.
+
+---
+
+## LLM note
+
+- **Dismiss:** `onDismiss` on `Banner.Root` injects a default close control only when there is **no** `Banner.CloseButton` among **direct** children of `Banner.Root`. Nesting `CloseButton` only under `Banner.Content` does **not** count—root may still inject a second close.
+- **Visibility:** no `open` prop; toggle with conditional render or parent state.
+- **Semantics:** map product tone to `status` (`error` billing failures, `warning` maintenance, `information` policy/cookies, `feature` promos). Pair `variant` with chrome: `filled` for urgent billing, `stroke` for calm operational notices, `lighter` / `light` for promos and consent rows.
+- **A11y:** prefer `role="region"` + `aria-labelledby` pointing at `Banner.Title`’s `id` (or `aria-label` when no visible title).
+- **Sizing:** default `size` is `m`; use `Banner`’s `size` for density—do not fake scale with ad-hoc CSS on kit nodes.

package/src/components/banner/examples/billing-alert.tsx

@@ -0,0 +1,35 @@
+import { AlertCircle } from "lucide-react";
+
+import { Banner, Button, LinkButton } from "prime-ui-kit";
+
+/** Past-due or failed payment: high emphasis, primary remediation + secondary help. */
+export default function BillingAlertExample() {
+  return (
+    <Banner.Root
+      aria-labelledby="billing-banner-title"
+      role="region"
+      status="error"
+      variant="filled"
+      onDismiss={() => {
+        /* product: hide after acknowledge */
+      }}
+    >
+      <Banner.Content>
+        <Banner.Icon as={AlertCircle} aria-hidden />
+        <Banner.Title id="billing-banner-title">Payment failed</Banner.Title>
+        <Banner.Description>
+          We could not charge your card ending in 4242. Update your payment method to avoid service
+          interruption.
+        </Banner.Description>
+        <Banner.Actions>
+          <Button.Root size="s" type="button" variant="primary">
+            Update payment method
+          </Button.Root>
+          <LinkButton.Root href="/billing/support" size="s">
+            Contact billing
+          </LinkButton.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/controlled-visibility.tsx

@@ -0,0 +1,42 @@
+import { Info } from "lucide-react";
+import { Banner, Button } from "prime-ui-kit";
+import { useState } from "react";
+
+/** Show and hide by mounting the root; external control restores the strip (no `open` prop). */
+export default function BannerControlledVisibilityExample() {
+  const [visible, setVisible] = useState(true);
+
+  return (
+    <>
+      {!visible ? (
+        <Button.Root size="s" type="button" variant="neutral" onClick={() => setVisible(true)}>
+          Show announcement
+        </Button.Root>
+      ) : null}
+      {visible ? (
+        <Banner.Root size="m" status="feature" variant="lighter">
+          <Banner.Content>
+            <Banner.Icon as={Info} aria-hidden />
+            <Banner.Title>Controlled visibility</Banner.Title>
+            <Banner.Description>
+              Removing the node from the tree hides the banner; use parent state to show it again.
+            </Banner.Description>
+            <Banner.Actions>
+              <Button.Root mode="ghost" size="s" type="button" variant="neutral">
+                Learn more
+              </Button.Root>
+              <Button.Root
+                size="s"
+                type="button"
+                variant="primary"
+                onClick={() => setVisible(false)}
+              >
+                Hide
+              </Button.Root>
+            </Banner.Actions>
+          </Banner.Content>
+        </Banner.Root>
+      ) : null}
+    </>
+  );
+}

package/src/components/banner/examples/cookie-consent-row.tsx

@@ -0,0 +1,36 @@
+import { Cookie } from "lucide-react";
+
+import { Banner, Button, LinkButton } from "prime-ui-kit";
+
+/** Inline consent row: actions for accept / preferences; optional dismiss defers to product policy. */
+export default function CookieConsentRowExample() {
+  return (
+    <Banner.Root
+      aria-labelledby="cookie-banner-title"
+      role="region"
+      status="information"
+      variant="lighter"
+      size="m"
+      onDismiss={() => {
+        /* product: defer / snooze — follow local privacy rules */
+      }}
+    >
+      <Banner.Content>
+        <Banner.Icon as={Cookie} aria-hidden />
+        <Banner.Title id="cookie-banner-title">Cookies and similar technologies</Banner.Title>
+        <Banner.Description>
+          We use cookies to run the site, remember preferences, and measure usage. See our policy
+          for details.
+        </Banner.Description>
+        <Banner.Actions>
+          <Button.Root size="s" type="button" variant="primary">
+            Accept essential
+          </Button.Root>
+          <LinkButton.Root href="/settings/cookies" size="s">
+            Manage preferences
+          </LinkButton.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/dismiss-close-button.tsx

@@ -0,0 +1,26 @@
+import { CheckCircle2 } from "lucide-react";
+
+import { Banner } from "prime-ui-kit";
+
+/**
+ * Explicit `Banner.CloseButton` as a direct child of `Banner.Root` (sibling of `Banner.Content`).
+ * No `onDismiss` on the root — the kit does not inject a second close control.
+ */
+export default function BannerDismissCloseButtonExample() {
+  return (
+    <Banner.Root status="success" variant="lighter">
+      <Banner.Content>
+        <Banner.Icon as={CheckCircle2} aria-hidden />
+        <Banner.Title>Changes saved</Banner.Title>
+        <Banner.Description>Your profile was updated successfully.</Banner.Description>
+      </Banner.Content>
+      <Banner.CloseButton
+        aria-label="Dismiss confirmation"
+        type="button"
+        onClick={() => {
+          /* product: hide banner */
+        }}
+      />
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/feature-promo.tsx

@@ -0,0 +1,36 @@
+import { Sparkles } from "lucide-react";
+
+import { Banner, Button } from "prime-ui-kit";
+
+/** Product promo: feature palette, lighter fill, compact actions. */
+export default function FeaturePromoExample() {
+  return (
+    <Banner.Root
+      aria-labelledby="feature-banner-title"
+      role="region"
+      status="feature"
+      variant="lighter"
+      size="m"
+      onDismiss={() => {
+        /* product: persist dismissal (localStorage / profile flag) */
+      }}
+    >
+      <Banner.Content>
+        <Banner.Icon as={Sparkles} aria-hidden />
+        <Banner.Title id="feature-banner-title">New: shared workspaces</Banner.Title>
+        <Banner.Description>
+          Invite teammates, assign roles, and keep projects in one place. Available on Pro and
+          Enterprise.
+        </Banner.Description>
+        <Banner.Actions>
+          <Button.Root size="s" type="button" variant="primary">
+            Try workspaces
+          </Button.Root>
+          <Button.Root mode="ghost" size="s" type="button" variant="neutral">
+            What&apos;s new
+          </Button.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/banner/examples/maintenance.tsx

@@ -0,0 +1,23 @@
+import { Wrench } from "lucide-react";
+
+import { Banner, LinkButton } from "prime-ui-kit";
+
+/** Scheduled downtime: visible but non-blocking; stroke keeps the bar calm on neutral chrome. */
+export default function MaintenanceBannerExample() {
+  return (
+    <Banner.Root aria-label="Scheduled maintenance" role="region" status="warning" variant="stroke">
+      <Banner.Content>
+        <Banner.Icon as={Wrench} aria-hidden />
+        <Banner.Title>Scheduled maintenance</Banner.Title>
+        <Banner.Description>
+          Brief downtime tonight, 02:00–03:00 UTC. APIs and the dashboard may be unavailable.
+        </Banner.Description>
+        <Banner.Actions>
+          <LinkButton.Root href="/status" size="s">
+            Status page
+          </LinkButton.Root>
+        </Banner.Actions>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}