prime-ui-kit 0.3.1 → 0.3.2

package/src/components/notification/examples/error-success.tsx

@@ -0,0 +1,70 @@
+import { Button, NotificationProvider, Typography, useNotifications } from "prime-ui-kit";
+
+/**
+ * error / warning → assertive alert; success / info → polite status.
+ */
+function ErrorSuccessDemo() {
+  const { notify } = useNotifications();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Typography.Root variant="body-small" tone="muted">
+        Types change icons, stack grouping, and live-region politeness — not just color.
+      </Typography.Root>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "center",
+        }}
+      >
+        <Button.Root
+          type="button"
+          variant="error"
+          mode="lighter"
+          size="m"
+          onClick={() =>
+            notify({
+              type: "error",
+              title: "Payment failed",
+              description: "The card was declined. Try another method.",
+            })
+          }
+        >
+          Error toast
+        </Button.Root>
+        <Button.Root
+          type="button"
+          variant="primary"
+          mode="filled"
+          size="m"
+          onClick={() =>
+            notify({
+              type: "success",
+              title: "Saved",
+              description: "Your changes are stored.",
+            })
+          }
+        >
+          Success toast
+        </Button.Root>
+      </div>
+    </div>
+  );
+}
+
+export default function ErrorSuccessExample() {
+  return (
+    <NotificationProvider>
+      <ErrorSuccessDemo />
+    </NotificationProvider>
+  );
+}

package/src/components/notification/examples/notification-store.tsx

@@ -0,0 +1,58 @@
+import { Button, NotificationProvider, Typography, useNotificationStore } from "prime-ui-kit";
+
+/**
+ * useNotificationStore exposes items (active only) for labels, badges, or bulk actions.
+ */
+function StoreDemo() {
+  const { items, notify, dismissAll } = useNotificationStore();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Typography.Root variant="body-default">
+        Active toasts: {items.length} (excludes cards in the exit animation)
+      </Typography.Root>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "center",
+        }}
+      >
+        <Button.Root
+          type="button"
+          variant="neutral"
+          mode="stroke"
+          size="m"
+          onClick={() =>
+            notify({
+              type: "info",
+              title: "Queued",
+              description: "The counter above updates while this toast is visible.",
+            })
+          }
+        >
+          Push info
+        </Button.Root>
+        <Button.Root type="button" variant="neutral" mode="ghost" size="s" onClick={dismissAll}>
+          dismissAll()
+        </Button.Root>
+      </div>
+    </div>
+  );
+}
+
+export default function NotificationStoreExample() {
+  return (
+    <NotificationProvider>
+      <StoreDemo />
+    </NotificationProvider>
+  );
+}

package/src/components/notification/examples/positions.tsx

@@ -0,0 +1,73 @@
+import {
+  Button,
+  type NotificationPosition,
+  NotificationProvider,
+  Typography,
+  useNotifications,
+} from "prime-ui-kit";
+
+const POSITIONS: NotificationPosition[] = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+];
+
+function PositionsDemo() {
+  const { notify } = useNotifications();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Typography.Root variant="body-small" tone="muted">
+        Each button sends a toast anchored to that corner or edge; override per notify or set a
+        provider default.
+      </Typography.Root>
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(3, minmax(0, auto))",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        {POSITIONS.map((position) => (
+          <Button.Root
+            key={position}
+            type="button"
+            size="s"
+            variant="neutral"
+            mode="stroke"
+            onClick={() =>
+              notify({
+                type: "info",
+                title: `Zone: ${position}`,
+                description: "Position comes from notify options or NotificationProvider.",
+                position,
+                size: "m",
+                duration: 4000,
+              })
+            }
+          >
+            {position}
+          </Button.Root>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default function PositionsExample() {
+  return (
+    <NotificationProvider position="top-right">
+      <PositionsDemo />
+    </NotificationProvider>
+  );
+}

package/src/components/notification/examples/toast-queue.tsx

@@ -0,0 +1,63 @@
+import { Button, NotificationProvider, Typography, useNotifications } from "prime-ui-kit";
+
+/**
+ * Same position + type share one stack; provider max caps depth and drops oldest items.
+ */
+function ToastQueueDemo() {
+  const { notify, dismissAll } = useNotifications();
+
+  const enqueueBurst = () => {
+    const types = ["info", "success"] as const;
+    for (let index = 0; index < 6; index += 1) {
+      window.setTimeout(() => {
+        notify({
+          type: types[index % 2],
+          title: `Toast ${index + 1} of 6`,
+          description:
+            "Hover the stack to expand it and pause timers until you move the pointer away.",
+          position: "bottom-right",
+          duration: 6000 + index * 400,
+          badge: index + 1,
+        });
+      }, index * 120);
+    }
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Typography.Root variant="body-small" tone="muted">
+        Provider uses max=5: the sixth notification in the same stack replaces the oldest.
+      </Typography.Root>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "center",
+        }}
+      >
+        <Button.Root type="button" variant="neutral" mode="stroke" size="m" onClick={enqueueBurst}>
+          Enqueue six toasts
+        </Button.Root>
+        <Button.Root type="button" variant="neutral" mode="ghost" size="s" onClick={dismissAll}>
+          dismissAll()
+        </Button.Root>
+      </div>
+    </div>
+  );
+}
+
+export default function ToastQueueExample() {
+  return (
+    <NotificationProvider max={5} position="top-right">
+      <ToastQueueDemo />
+    </NotificationProvider>
+  );
+}

package/src/components/pagination/COMPONENT.md

@@ -1,23 +1,42 @@
 # Pagination
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the toolbar or table footer explicitly needs another tier.
 
-## About
+## Canonical
 
-Page navigation for chunked lists: previous and next controls with chevron icons, numeric page buttons, and ellipsis cells when there are many pages.
+- **`Pagination`** is a single compound export: **`Pagination.Root`** only (`Pagination = { Root }`).
+- **Controlled API:** **`page`**, **`totalPages`**, and **`onPageChange`** are all required; there is no uncontrolled mode.
+- **Semantics:** root is a **`nav`** with **`aria-label="Pagination"`**, **`data-size`**, previous/next **ghost** **`Button.Root`** cells with **`Button.Icon`**, numeric page **`Button.Root`** cells (current page **`primary`** **`filled`**), and ellipsis **`span`**s (**`aria-hidden`**).
+- **Range logic:** if **`totalPages ≤ 7`**, every page index is shown; otherwise the row is shortened with **`siblingCount`** (default **`1`**) and **`…`** segments while keeping first and last pages visible.
+- **Edge cases:** **`totalPages < 1`** renders **`null`**; **`page`** is clamped to **`1 … totalPages`** for display and clicks; previous/next are **`disabled`** on the first/last page.
+- **Copy:** arrow and **“Page N”** strings are fixed in the implementation (English); there are no i18n props on **`Pagination`**.
 
-- **Use** for server-driven or client-paged tables, search results, and any UI where the user moves between discrete page indices.
-- **Use** when you already know **`totalPages`** and can keep **`page`** in sync (controlled pattern).
-- **Do not use** as the only paging affordance when you rely on infinite scroll and never expose page numbers—this component assumes explicit pages.
-- **Do not use** when **`totalPages` is less than 1** and you still need a visible empty state; the root returns **`null`** in that case, so render a message or hide the bar in the parent.
-- **Do not use** expecting localized arrow or “Page N” strings from props; labels are fixed in the implementation (English).
-- **Do not use** if you must replace inner markup (custom arrows, slots); structure and **`Button`** wiring are fixed—extend or fork for deep customization.
+## Extended
 
-## Composition
+### About
 
-- **`Pagination`** is a single-part namespace: **`Pagination.Root`** only (exported as **`Pagination = { Root }`**).
-- **`Pagination.Root`** renders a **`nav`** with **`aria-label="Pagination"`**, **`data-size`**, and a row of controls: **previous** (ghost neutral **`Button`** with **`Button.Icon`**), a sequence of numeric page **`Button.Root`** cells or ellipsis **`span`**s (**`aria-hidden`**), then **next** (same as previous).
-- Page items use **`Button.Root`** with **`size`** from the root; the current page uses **`variant="primary"`** and **`mode="filled"`**; other numbers and arrows use **`variant="neutral"`** and **`mode="ghost"`**.
+Chunked navigation for lists and tables: chevron previous/next, numbered pages, and ellipses for long ranges.
+
+- **Use** when the dataset is split into discrete pages and **`totalPages`** is known (server-driven or client-side paging).
+- **Use** in table footers, list toolbars, or search result bars alongside a short range summary.
+- **Do not use** as the only paging affordance when the product is infinite-scroll-only with no page index.
+- **Do not use** when **`totalPages < 1`** and you still need chrome—**`Pagination.Root`** returns nothing; show an empty state or omit the bar in the parent.
+- **Do not use** when you must replace inner markup or strings; structure and **Button** wiring are fixed—fork or wrap at app level if you need deep customization.
+
+### Composition
+
+- **`Pagination.Root`** — the only public part. Renders the **`nav`** row; **`className`** merges onto that **`nav`** only.
+- Full-width or “meta left / pager right” layouts are parent responsibility (flex or grid around **`Pagination.Root`**)—there is no **`fullWidth`** prop on **`Pagination`**.
+
+### Scenarios (see `examples/`)
+
+| Scenario | Approach |
+|----------|----------|
+| Table footer | Pair a range summary with **`Pagination.Root`** in a footer row; keep **`page`** in sync with fetched rows. → [`examples/table-footer.tsx`](examples/table-footer.tsx) |
+| Compact toolbar | Set **`size="s"`** for denser toolbars or mobile-adjacent rows. → [`examples/compact.tsx`](examples/compact.tsx) |
+| Full-width list bar | **`display: flex`**, **`justify-content: space-between`**, **`flex-wrap`**: meta text + pager. → [`examples/full-width-list.tsx`](examples/full-width-list.tsx) |
+| Controlled page index | Store **`page`** in React state (or router); update from **`onPageChange`** and any other controls (e.g. jump to first/last). → [`examples/controlled-page.tsx`](examples/controlled-page.tsx) |
+| Canonical wiring | Minimal **`Pagination.Root`** with required props; reference for imports and props. → [`examples/canonical-composition.tsx`](examples/canonical-composition.tsx) |
 
 ### Minimal example
 
@@ -31,16 +50,27 @@ export function Example() {
 }
 ```
 
-## Rules
+### Canonical composition (reference)
+
+For **default wiring**, **long ranges**, and **`siblingCount`**, open **`examples/canonical-composition.tsx`** next to this file. Imports use **`"prime-ui-kit"`** so snippets work in an app after installing the package.
 
-- **Controlled only:** **`page`**, **`totalPages`**, and **`onPageChange`** are required; there is no uncontrolled mode.
+### Example files in `examples/`
+
+| File | Scenario |
+|------|----------|
+| `canonical-composition.tsx` | Required props, default size, long range + `siblingCount` |
+| `table-footer.tsx` | English table footer: row range + pager |
+| `compact.tsx` | English compact row: `size="s"` |
+| `full-width-list.tsx` | English full-width bar: summary + pager |
+| `controlled-page.tsx` | English controlled state + jump buttons |
+
+### Rules
+
+- **Controlled only:** **`page`**, **`totalPages`**, and **`onPageChange`** are required.
 - **`page`** is clamped internally to **`1 … totalPages`** before rendering and when handling clicks.
-- If **`totalPages < 1`**, the component returns **`null`** (render nothing).
-- With **`totalPages ≤ 7`**, every page number is shown. With more pages, the row is shortened using **`siblingCount`** (default **`1`**) and ellipsis segments (**`…`**).
-- **First page:** previous control is **`disabled`**. **Last page:** next is **`disabled`**. **Single page:** both arrows are **`disabled`**.
-- The active page button sets **`aria-current="page"`**; other page buttons use **`aria-label={`Page ${n}`}`**; arrows use **“Previous page”** / **“Next page”**.
-- **`className`** merges onto the root **`nav`** only.
-- Syncing **`page`** to the URL, router, or query params is the responsibility of the parent.
+- If **`totalPages < 1`**, the component returns **`null`**.
+- The active page button sets **`aria-current="page"`**; other page buttons use **`aria-label`** of the form **`Page {n}`**; arrows use **“Previous page”** / **“Next page”**.
+- Syncing **`page`** to the URL, router, or query params is the parent’s responsibility.
 
 ## API
 
@@ -57,5 +87,15 @@ export function Example() {
 
 ## Related
 
-- [Button](../button/COMPONENT.md)
-- [DataTable](../data-table/COMPONENT.md)
+- [Button](../button/COMPONENT.md) — page and arrow cells are **`Button.Root`** + **`Button.Icon`**.
+- [DataTable](../data-table/COMPONENT.md) — typical host for a footer pager.
+
+## LLM note
+
+- **Imports:** **`import { Pagination } from "prime-ui-kit"`** — use **`Pagination.Root`** only; there is no flat **`Pagination`** element.
+- **Props:** **`page`**, **`totalPages`**, **`onPageChange`** required; optional **`siblingCount`**, **`size`**, **`className`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**; maps to **`data-size`** on the root **`nav`**.
+- **`totalPages < 1`:** render is **`null`** — parent must handle empty data or hide the footer.
+- **No uncontrolled mode** — always pass **`page`** and **`onPageChange`**; lift state to the parent or router.
+- **Layout:** no **`fullWidth`** on **`Pagination`**; wrap in flex/grid and align in the parent.
+- **Strings:** labels are English and built-in; do not assume i18n props exist on **`Pagination`**.

package/src/components/pagination/examples/canonical-composition.tsx

@@ -0,0 +1,20 @@
+import { Pagination } from "prime-ui-kit";
+
+/**
+ * Canonical wiring: required props on Pagination.Root only. Long ranges use siblingCount to widen the numeric window.
+ */
+export default function CanonicalCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Pagination.Root page={2} totalPages={5} onPageChange={() => {}} />
+      <Pagination.Root page={10} totalPages={40} onPageChange={() => {}} siblingCount={2} />
+    </div>
+  );
+}

package/src/components/pagination/examples/compact.tsx

@@ -0,0 +1,32 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/** Dense toolbar row: Pagination.Root with size="s". */
+export default function CompactExample() {
+  const [page, setPage] = React.useState(3);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-x2)",
+        padding: "var(--prime-sys-spacing-x2) var(--prime-sys-spacing-x3)",
+        borderRadius: "var(--prime-sys-radius-m)",
+        background: "var(--prime-sys-color-surface-default)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+      }}
+    >
+      <span
+        style={{
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Compact
+      </span>
+      <Pagination.Root page={page} totalPages={12} onPageChange={setPage} size="s" />
+    </div>
+  );
+}

package/src/components/pagination/examples/controlled-page.tsx

@@ -0,0 +1,57 @@
+import { Button, Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+const TOTAL = 12;
+
+/** Page index lives in parent state; Pagination.Root and buttons share the same setter. */
+export default function ControlledPageExample() {
+  const [page, setPage] = React.useState(4);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x3)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p
+        style={{
+          margin: 0,
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Open page {page} of {TOTAL} — updates via <code>page</code> and <code>onPageChange</code>.
+      </p>
+      <Pagination.Root page={page} totalPages={TOTAL} onPageChange={setPage} />
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-x2)",
+        }}
+      >
+        <Button.Root
+          size="s"
+          variant="neutral"
+          mode="stroke"
+          onClick={() => setPage(1)}
+          disabled={page <= 1}
+        >
+          First
+        </Button.Root>
+        <Button.Root
+          size="s"
+          variant="neutral"
+          mode="stroke"
+          onClick={() => setPage(TOTAL)}
+          disabled={page >= TOTAL}
+        >
+          Last
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/full-width-list.tsx

@@ -0,0 +1,37 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/** Full-width bar: meta on the left, Pagination.Root on the right (parent layout). */
+export default function FullWidthListExample() {
+  const [page, setPage] = React.useState(2);
+  const totalPages = 21;
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        width: "100%",
+        maxWidth: "36rem",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: "var(--prime-sys-spacing-x3)",
+        flexWrap: "wrap",
+        padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+        borderRadius: "var(--prime-sys-radius-m)",
+        background: "var(--prime-sys-color-surface-raised)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+      }}
+    >
+      <span
+        style={{
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+          lineHeight: "var(--prime-sys-typography-body-lineHeight)",
+        }}
+      >
+        Showing 21–40 of 412
+      </span>
+      <Pagination.Root page={page} totalPages={totalPages} onPageChange={setPage} />
+    </div>
+  );
+}

package/src/components/pagination/examples/table-footer.tsx

@@ -0,0 +1,74 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+const PAGE_SIZE = 10;
+const TOTAL_ROWS = 247;
+
+function rangeLabel(page: number, pageSize: number, total: number) {
+  const start = (page - 1) * pageSize + 1;
+  const end = Math.min(page * pageSize, total);
+  return `Showing ${start}–${end} of ${total}`;
+}
+
+/** Table-style footer: row summary plus Pagination.Root aligned on one row. */
+export default function TableFooterExample() {
+  const [page, setPage] = React.useState(1);
+  const totalPages = Math.max(1, Math.ceil(TOTAL_ROWS / PAGE_SIZE));
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        borderRadius: "var(--prime-sys-radius-m)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+        background: "var(--prime-sys-color-surface-raised)",
+        overflow: "hidden",
+        maxWidth: "42rem",
+      }}
+    >
+      <div
+        style={{
+          padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+          borderBottom: "1px solid var(--prime-sys-color-border-subtle)",
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Sample rows (page {page} of {totalPages})
+      </div>
+      <div
+        style={{
+          padding: "var(--prime-sys-spacing-x4)",
+          minHeight: "6rem",
+          color: "var(--prime-sys-color-content-muted)",
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+        }}
+      >
+        …
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: "var(--prime-sys-spacing-x3)",
+          padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+          borderTop: "1px solid var(--prime-sys-color-border-subtle)",
+        }}
+      >
+        <span
+          style={{
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+            lineHeight: "var(--prime-sys-typography-body-lineHeight)",
+          }}
+        >
+          {rangeLabel(page, PAGE_SIZE, TOTAL_ROWS)}
+        </span>
+        <Pagination.Root page={page} totalPages={totalPages} onPageChange={setPage} />
+      </div>
+    </div>
+  );
+}