prime-ui-kit 0.3.1 → 0.3.2

package/src/components/accordion/examples/02-settings-panels.tsx

@@ -0,0 +1,67 @@
+import { Bell, Lock, User } from "lucide-react";
+import { Accordion, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Account settings: compare several open sections at once with `type="multiple"` and card-like
+ * `layout="separate"`.
+ */
+export default function AccordionExampleSettingsPanels() {
+  return (
+    <Accordion.Root
+      type="multiple"
+      size="m"
+      layout="separate"
+      defaultValue={["profile", "notifications"]}
+    >
+      <Accordion.Item value="profile">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={User} />
+            <span>Profile</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <Typography.Root as="p" variant="body-default" className={styles.lead}>
+              Update your display name, avatar, and public contact details. Changes apply across all
+              signed-in devices after you save.
+            </Typography.Root>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="notifications">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Bell} />
+            <span>Notifications</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Choose email, push, and in-app channels. Digest mode bundles low-priority updates into
+            one daily summary.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="security">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Lock} />
+            <span>Security</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Manage passwords, two-factor authentication, and active sessions. We recommend enabling
+            an authenticator app for administrator roles.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/03-checkout-order-summary.tsx

@@ -0,0 +1,87 @@
+import { Minus, Plus } from "lucide-react";
+import { Accordion, LinkButton, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Checkout flow: custom open/close icons on the arrow, dense copy, and a policy link in the body.
+ */
+export default function AccordionExampleCheckoutOrderSummary() {
+  return (
+    <Accordion.Root type="single" size="m" layout="grouped" defaultValue="totals">
+      <Accordion.Item value="totals">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Order totals</span>
+            <Accordion.Arrow openIcon={Plus} closeIcon={Minus} />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-default">
+                Subtotal
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-default">
+                $124.00
+              </Typography.Root>
+            </div>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-default" tone="muted">
+                Estimated tax
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-default" tone="muted">
+                $9.92
+              </Typography.Root>
+            </div>
+            <div className={styles.row}>
+              <Typography.Root as="span" variant="body-small" weight="semibold">
+                Due today
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-small" weight="semibold">
+                $133.92
+              </Typography.Root>
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="delivery">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Delivery window</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Arrives Tuesday–Thursday depending on carrier volume. You can reschedule from the
+            confirmation email.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="terms">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <span>Terms &amp; privacy</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.stack}>
+            <Typography.Root as="p" variant="body-small" className={styles.lead}>
+              By placing this order you agree to our terms of sale and refund policy.
+            </Typography.Root>
+            <div className={styles.actions}>
+              <LinkButton.Root href="#" size="s">
+                Terms of sale
+              </LinkButton.Root>
+              <LinkButton.Root href="#" size="s">
+                Privacy policy
+              </LinkButton.Root>
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/04-api-docs-sections.tsx

@@ -0,0 +1,86 @@
+import { BookOpen, Code2, Webhook } from "lucide-react";
+import { Accordion, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Long-form API reference: controlled `value` / `onValueChange` so another part of the page (or
+ * deep link) can sync which section is open.
+ */
+export default function AccordionExampleApiDocsSections() {
+  const [open, setOpen] = React.useState<string>("auth");
+
+  return (
+    <Accordion.Root
+      type="single"
+      size="m"
+      layout="grouped"
+      value={open}
+      onValueChange={(value) => setOpen(typeof value === "string" ? value : (value[0] ?? ""))}
+    >
+      <Accordion.Item value="auth">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={BookOpen} />
+            <span>Authentication</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <div className={styles.bodyStack}>
+            <Typography.Root as="p" variant="body-default" className={styles.lead}>
+              Send a bearer token in the{" "}
+              <Typography.Root as="span" variant="caption" weight="medium">
+                Authorization
+              </Typography.Root>{" "}
+              header. Tokens expire after twelve hours; refresh using the endpoint described in the
+              session guide.
+            </Typography.Root>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="webhooks">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Webhook} />
+            <span>Webhooks</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Register HTTPS endpoints to receive signed event payloads. Retry policy uses exponential
+            backoff for non-2xx responses up to three days.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="errors">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={Code2} />
+            <span>Error format</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Errors return JSON with{" "}
+            <Typography.Root as="span" variant="caption" weight="medium">
+              code
+            </Typography.Root>
+            ,{" "}
+            <Typography.Root as="span" variant="caption" weight="medium">
+              message
+            </Typography.Root>
+            , and optional{" "}
+            <Typography.Root as="span" variant="caption" weight="medium">
+              details
+            </Typography.Root>{" "}
+            for validation issues.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/05-knowledge-base-categories.tsx

@@ -0,0 +1,65 @@
+import { FileQuestion, LifeBuoy, ShieldCheck } from "lucide-react";
+import { Accordion, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Support hub: `collapsible={false}` keeps one section pinned open once chosen, and a disabled item
+ * marks content that is not yet available for the user’s plan.
+ */
+export default function AccordionExampleKnowledgeBaseCategories() {
+  return (
+    <Accordion.Root
+      type="single"
+      size="m"
+      layout="separate"
+      defaultValue="basics"
+      collapsible={false}
+    >
+      <Accordion.Item value="basics">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={LifeBuoy} />
+            <span>Getting started</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            New here? Complete the workspace checklist, invite teammates, and connect your first
+            data source from the integrations directory.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="billing" disabled>
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={ShieldCheck} />
+            <span>Billing &amp; contracts (Enterprise)</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Contract terms and invoice history appear here when your organization upgrades.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="troubleshoot">
+        <Accordion.Header>
+          <Accordion.Trigger>
+            <Accordion.Icon as={FileQuestion} />
+            <span>Troubleshooting</span>
+            <Accordion.Arrow />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>
+          <Typography.Root as="p" variant="body-default" className={styles.lead}>
+            Common fixes: clear the local cache, verify outbound firewall rules for our API hosts,
+            and confirm your SDK is on a supported major version.
+          </Typography.Root>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}

package/src/components/accordion/examples/examples.module.css

@@ -0,0 +1,30 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.bodyStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.lead {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-m);
+  margin-top: var(--prime-sys-spacing-s);
+}
+
+.row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--prime-sys-spacing-m);
+}

package/src/components/avatar/COMPONENT.md

@@ -20,21 +20,73 @@ Circular avatar with an optional photo (`Avatar.Image`), a fallback layer (`Avat
 - **`Avatar.Group.Root`** — horizontal flex row; passes its **`size`** into child **`Avatar.Root`** and **`Avatar.Group.Overflow`** that omit their own **`size`** (including through **`React.Fragment`** children).
 - **`Avatar.Group.Overflow`** — cell matching avatar dimensions for text such as `+3`.
 
-### Minimal example
+### Canonical example
+
+Один фрагмент разметки: одиночный аватар (**`Image`** + **`Fallback`**), группа с **`Overflow`**, плюс **`Fallback`** с иконкой и подписи через **[Typography](../typography/COMPONENT.md)**. Импорт только из **`prime-ui-kit`**.
 
 ```tsx
-import { Avatar } from "prime-ui-kit";
+import { Avatar, Icon, Typography } from "prime-ui-kit";
+
+const sampleSrc =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
 
-export function Example() {
+export function CanonicalAvatarDemo() {
   return (
-    <Avatar.Root>
-      <Avatar.Image src="/avatar.png" alt="" />
-      <Avatar.Fallback>AB</Avatar.Fallback>
-    </Avatar.Root>
+    <>
+      <Typography as="p" variant="body-small" tone="muted">
+        Profile cell
+      </Typography>
+      <Avatar.Root size="l" aria-label="Jamie Chen, online">
+        <Avatar.Image src={sampleSrc} alt="" />
+        <Avatar.Fallback>JC</Avatar.Fallback>
+      </Avatar.Root>
+
+      <Typography as="p" variant="body-small" tone="muted">
+        Overlapping group + overflow
+      </Typography>
+      <Avatar.Group.Root size="m" aria-label="Reviewers: three faces, two not shown">
+        <Avatar.Root>
+          <Avatar.Image src={sampleSrc} alt="" />
+          <Avatar.Fallback>A</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root>
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root>
+          <Avatar.Fallback>C</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Group.Overflow aria-label="Two additional reviewers">+2</Avatar.Group.Overflow>
+      </Avatar.Group.Root>
+
+      <Typography as="p" variant="body-small" tone="muted">
+        Icon-only fallback
+      </Typography>
+      <Avatar.Root size="m" aria-label="Invitee, no photo yet">
+        <Avatar.Fallback>
+          <Icon name="field.email" size="l" tone="subtle" />
+        </Avatar.Fallback>
+      </Avatar.Root>
+    </>
   );
 }
 ```
 
+### Extended examples
+
+Готовые сценарии с раскладкой на **`--prime-sys-`* (см. [`examples/examples.module.css`](./examples/examples.module.css)):
+
+| Файл | Сценарий |
+|------|----------|
+| [`examples/team-list.tsx`](./examples/team-list.tsx) | Список команды: аватар + имя + роль |
+| [`examples/comment-thread.tsx`](./examples/comment-thread.tsx) | Ветка комментариев с аватаром у каждого сообщения |
+| [`examples/app-header-nav.tsx`](./examples/app-header-nav.tsx) | Шапка: навигация **[LinkButton](../link-button/COMPONENT.md)** и блок «аккаунт» с аватаром |
+| [`examples/group-overflow.tsx`](./examples/group-overflow.tsx) | **`Avatar.Group`** с **`Overflow`** (`+N`) |
+| [`examples/fallback-variants.tsx`](./examples/fallback-variants.tsx) | Фото, инициалы и иконка в **`Fallback`** в одном ряду |
+
+### Note for LLMs
+
+При генерации экранов опирайся на публичный API выше и на **исходники** в `src/components/avatar/examples/*.tsx`: там полные импорты **`prime-ui-kit`**, типичная композиция с **[Typography](../typography/COMPONENT.md)** / **[LinkButton](../link-button/COMPONENT.md)** / **`Icon`** (экспорт пакета) и семантическая вёрстка без обхода стилей кита. Не дублируй длинные листинги в ответе — укажи путь к файлу примера.
+
 ## Rules
 
 - Image lifecycle is **internal**: context status is `idle` \| `loading` \| `loaded` \| `error`; there is no prop to control it from outside—change **`src`** (or remove **`Avatar.Image`**) to reset behavior.

package/src/components/avatar/examples/app-header-nav.tsx

@@ -0,0 +1,41 @@
+import { Avatar, LinkButton, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * App chrome: product title, nav links, and a signed-in identity cluster (avatar + account link).
+ */
+export default function AvatarAppHeaderNavExample() {
+  return (
+    <header className={styles.navBar}>
+      <div className={styles.navCluster}>
+        <Typography.Root as="span" variant="heading-subsection" weight="semibold">
+          Prime Console
+        </Typography.Root>
+        <nav className={styles.row} aria-label="Primary">
+          <LinkButton.Root href="#overview" size="m">
+            Overview
+          </LinkButton.Root>
+          <LinkButton.Root href="#projects" size="m">
+            Projects
+          </LinkButton.Root>
+          <LinkButton.Root href="#settings" size="m">
+            Settings
+          </LinkButton.Root>
+        </nav>
+      </div>
+      <div className={styles.navUser}>
+        <Avatar.Root size="m" aria-label="Signed in as Jamie Chen">
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>JC</Avatar.Fallback>
+        </Avatar.Root>
+        <LinkButton.Root href="#account" size="m">
+          Account
+        </LinkButton.Root>
+      </div>
+    </header>
+  );
+}

package/src/components/avatar/examples/comment-thread.tsx

@@ -0,0 +1,57 @@
+import { Avatar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1527980965255-d3b416303d12?w=128&h=128&fit=crop";
+
+type Comment = { id: string; author: string; initials: string; body: string; src?: string };
+
+const comments: Comment[] = [
+  {
+    id: "c1",
+    author: "Casey Ng",
+    initials: "CN",
+    body: "Shipped the first cut of filters. Can you sanity-check the empty state?",
+    src: portrait,
+  },
+  {
+    id: "c2",
+    author: "Riley Park",
+    initials: "RP",
+    body: "Looks good. Let’s add a single-line skeleton for slow networks.",
+  },
+  {
+    id: "c3",
+    author: "Morgan Blake",
+    initials: "MB",
+    body: "+1 on skeleton. I’ll wire it in the list cell tomorrow.",
+    src: portrait,
+  },
+];
+
+/**
+ * Comment thread: avatar + stacked author line and body copy.
+ */
+export default function AvatarCommentThreadExample() {
+  return (
+    <ul className={styles.list} aria-label="Discussion">
+      {comments.map((c) => (
+        <li key={c.id} className={styles.rowStretch}>
+          <Avatar.Root size="m" aria-label={c.author}>
+            {c.src ? <Avatar.Image src={c.src} alt="" /> : null}
+            <Avatar.Fallback>{c.initials}</Avatar.Fallback>
+          </Avatar.Root>
+          <div className={styles.stack}>
+            <Typography.Root as="span" variant="body-small" weight="semibold">
+              {c.author}
+            </Typography.Root>
+            <Typography.Root as="p" variant="body-default" tone="muted">
+              {c.body}
+            </Typography.Root>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/avatar/examples/examples.module.css

@@ -0,0 +1,72 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.row {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.rowStretch {
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.listItem {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--prime-sys-spacing-m);
+  min-width: 0;
+}
+
+.listItemBody {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x1);
+  min-width: 0;
+}
+
+.navBar {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-sys-spacing-m);
+  padding: var(--prime-sys-spacing-m) var(--prime-sys-spacing-l);
+  border-radius: var(--prime-sys-shape-radius-m);
+  background: var(--prime-sys-color-surface-raised);
+  border: 1px solid var(--prime-sys-color-border-subtle);
+}
+
+.navCluster {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-sys-spacing-l);
+}
+
+.navUser {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--prime-sys-spacing-s);
+}

package/src/components/avatar/examples/fallback-variants.tsx

@@ -0,0 +1,33 @@
+import { Avatar, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * Side-by-side: loaded image, initials-only fallback, and icon-only fallback.
+ */
+export default function AvatarFallbackVariantsExample() {
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="caption" tone="muted">
+        Same size tier; different fallback strategies
+      </Typography.Root>
+      <div className={styles.row}>
+        <Avatar.Root size="xl" aria-label="User with photo">
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>PH</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root size="xl" aria-label="User with initials only">
+          <Avatar.Fallback>IN</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root size="xl" aria-label="Placeholder account">
+          <Avatar.Fallback>
+            <Icon name="field.email" size="xl" tone="subtle" />
+          </Avatar.Fallback>
+        </Avatar.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/avatar/examples/group-overflow.tsx

@@ -0,0 +1,32 @@
+import { Avatar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const portrait =
+  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+
+/**
+ * Overlapping group with an overflow cell for hidden participants.
+ */
+export default function AvatarGroupOverflowExample() {
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="body-small" tone="muted">
+        Design review — 5 invited, 2 faces shown
+      </Typography.Root>
+      <Avatar.Group.Root
+        size="l"
+        aria-label="Participants: two avatars visible, three more not shown"
+      >
+        <Avatar.Root>
+          <Avatar.Image src={portrait} alt="" />
+          <Avatar.Fallback>A</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Root>
+          <Avatar.Fallback>B</Avatar.Fallback>
+        </Avatar.Root>
+        <Avatar.Group.Overflow aria-label="Three additional participants">+3</Avatar.Group.Overflow>
+      </Avatar.Group.Root>
+    </div>
+  );
+}