@exxatdesignux/ui 0.2.19 → 0.3.0

package/template/components/ui/dot-pattern.tsx

@@ -1,183 +1 @@
-"use client"
-
-/**
- * DotPattern — dot grid revealed by a soft drifting "cloud" mask.
- *
- * Inspiration: Google/Apple AI loading states — a diffuse dot field that
- * softly fades in, drifts diagonally across the surface, then fades out.
- * No bright glow cores, no particles — just one or two large soft halos
- * sliding across the grid so the dots appear as an ambient cloud.
- */
-
-import * as React from "react"
-import { motion } from "motion/react"
-import { cn } from "@/lib/utils"
-
-interface DotPatternProps extends React.SVGProps<SVGSVGElement> {
-  width?: number
-  height?: number
-  x?: number
-  y?: number
-  cx?: number
-  cy?: number
-  cr?: number
-  className?: string
-  glow?: boolean
-  /** Number of drifting soft clouds (keep small: 1–2). */
-  glowCount?: number
-  /** Cloud radius — large values produce a wide, diffuse reveal. */
-  glowRadius?: number
-}
-
-type Cloud = {
-  key: number
-  xs: string[]
-  ys: string[]
-  duration: number
-  delay: number
-}
-
-/**
- * Tiny deterministic PRNG (mulberry32). We use a seeded RNG instead of
- * `Math.random()` so the SVG attributes emitted on the server match the
- * client's first paint — otherwise React reports a hydration mismatch and
- * has to re-paint every drifting `<motion.circle>` on mount, which is both
- * a perf cost and a visible jump.
- */
-function mulberry32(seed: number): () => number {
-  let s = seed >>> 0
-  return () => {
-    s = (s + 0x6d2b79f5) >>> 0
-    let t = s
-    t = Math.imul(t ^ (t >>> 15), t | 1)
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
-  }
-}
-
-function hashString(str: string): number {
-  // Cheap FNV-1a-style hash. Stable across SSR + CSR for the same input.
-  let h = 2166136261
-  for (let i = 0; i < str.length; i++) {
-    h ^= str.charCodeAt(i)
-    h = Math.imul(h, 16777619)
-  }
-  return h >>> 0
-}
-
-export function DotPattern({
-  width = 14,
-  height = 14,
-  x = 0,
-  y = 0,
-  cx = 1,
-  cy = 1,
-  cr = 0.8,
-  className,
-  glow = false,
-  glowCount = 2,
-  glowRadius = 240,
-  ...props
-}: DotPatternProps) {
-  const id = React.useId()
-  const maskId = `${id}-mask`
-  const gradId = `${id}-grad`
-
-  const clouds = React.useMemo<Cloud[]>(() => {
-    const rng = mulberry32(hashString(`${id}|${glowCount}`))
-    const rand = (min: number, max: number) => min + rng() * (max - min)
-    return Array.from({ length: glowCount }).map((_, i) => {
-      // Drift diagonally: bottom-right → top-left. Start/end partly off-canvas
-      // so the cloud enters and exits softly without a visible edge.
-      const startX = rand(85, 120)
-      const endX = rand(-20, 15)
-      const midX = (startX + endX) / 2 + rand(-6, 6)
-
-      const startY = rand(85, 115)
-      const endY = rand(-15, 10)
-      const midY = (startY + endY) / 2 + rand(-4, 4)
-
-      const duration = rand(8, 12)
-      // Offset clouds by half a cycle so one is arriving as the other leaves.
-      const delay = -(i / glowCount) * duration
-
-      return {
-        key: i,
-        xs: [`${startX}%`, `${midX}%`, `${endX}%`],
-        ys: [`${startY}%`, `${midY}%`, `${endY}%`],
-        duration,
-        delay,
-      }
-    })
-  }, [glowCount, id])
-
-  return (
-    <svg
-      aria-hidden="true"
-      className={cn(
-        "pointer-events-none absolute inset-0 h-full w-full fill-neutral-400/80",
-        className,
-      )}
-      {...props}
-    >
-      <defs>
-        <pattern
-          id={id}
-          width={width}
-          height={height}
-          patternUnits="userSpaceOnUse"
-          patternContentUnits="userSpaceOnUse"
-          x={x}
-          y={y}
-        >
-          <circle cx={cx} cy={cy} r={cr} />
-        </pattern>
-
-        {glow ? (
-          <>
-            {/* Very soft falloff — no visible ring edge, dots dissolve gradually. */}
-            <radialGradient id={gradId}>
-              <stop offset="0%"   stopColor="white" stopOpacity="0.9" />
-              <stop offset="40%"  stopColor="white" stopOpacity="0.55" />
-              <stop offset="75%"  stopColor="white" stopOpacity="0.18" />
-              <stop offset="100%" stopColor="white" stopOpacity="0" />
-            </radialGradient>
-
-            <mask id={maskId}>
-              {clouds.map((c) => (
-                <motion.circle
-                  key={`cloud-${c.key}`}
-                  r={glowRadius}
-                  fill={`url(#${gradId})`}
-                  initial={{ cx: c.xs[0], cy: c.ys[0], opacity: 0 }}
-                  animate={{
-                    cx: c.xs,
-                    cy: c.ys,
-                    // Long hold with soft fade at both ends.
-                    opacity: [0, 1, 1, 0],
-                  }}
-                  transition={{
-                    duration: c.duration,
-                    delay: c.delay,
-                    repeat: Infinity,
-                    ease: "linear",
-                    times: [0, 0.3, 0.7, 1],
-                  }}
-                />
-              ))}
-            </mask>
-          </>
-        ) : null}
-      </defs>
-
-      {/* Dot grid — only visible inside the drifting soft clouds when glow is on. */}
-      <rect
-        width="100%"
-        height="100%"
-        strokeWidth={0}
-        fill={`url(#${id})`}
-        mask={glow ? `url(#${maskId})` : undefined}
-      />
-    </svg>
-  )
-}
+export * from "@exxatdesignux/ui/components/dot-pattern"

package/template/components/ui/hover-card.tsx

@@ -0,0 +1 @@
+export * from "@exxatdesignux/ui/components/hover-card"

package/template/components/ui/resizable.tsx

@@ -1,68 +1 @@
-"use client"
-
-import * as React from "react"
-import { GripVertical } from "lucide-react"
-import { Group, Panel, Separator } from "react-resizable-panels"
-import type { GroupProps, PanelProps, SeparatorProps } from "react-resizable-panels"
-
-import { cn } from "@/lib/utils"
-
-// ─── ResizablePanelGroup ──────────────────────────────────────────────────────
-
-export type ResizablePanelGroupProps = Omit<GroupProps, "orientation"> & {
-  direction?: "horizontal" | "vertical"
-}
-
-export function ResizablePanelGroup({
-  direction = "horizontal",
-  className,
-  ...props
-}: ResizablePanelGroupProps) {
-  return (
-    <Group
-      orientation={direction}
-      className={cn(
-        "flex h-full w-full",
-        direction === "vertical" && "flex-col",
-        className,
-      )}
-      {...props}
-    />
-  )
-}
-
-// ─── ResizablePanel ───────────────────────────────────────────────────────────
-
-export type ResizablePanelProps = PanelProps
-
-export const ResizablePanel = Panel
-
-// ─── ResizableHandle ──────────────────────────────────────────────────────────
-
-export type ResizableHandleProps = Omit<SeparatorProps, "children"> & {
-  /** Render a visible grip icon on the handle. */
-  withHandle?: boolean
-}
-
-export function ResizableHandle({ withHandle, className, ...props }: ResizableHandleProps) {
-  return (
-    <Separator
-      className={cn(
-        // Base — horizontal handle (between side-by-side panels)
-        "relative flex w-1 shrink-0 cursor-col-resize items-center justify-center bg-border/60",
-        "transition-colors hover:bg-border active:bg-primary/30",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
-        // Vertical handle (between stacked panels)
-        "data-[orientation=vertical]:h-1 data-[orientation=vertical]:w-full data-[orientation=vertical]:cursor-row-resize data-[orientation=vertical]:flex-row",
-        className,
-      )}
-      {...props}
-    >
-      {withHandle && (
-        <div className="z-10 flex h-5 w-3.5 items-center justify-center rounded-sm border border-border bg-background shadow-sm">
-          <GripVertical className="h-3 w-3 text-muted-foreground" />
-        </div>
-      )}
-    </Separator>
-  )
-}
+export * from "@exxatdesignux/ui/components/resizable"

package/template/components/ui/scroll-area.tsx

@@ -0,0 +1 @@
+export * from "@exxatdesignux/ui/components/scroll-area"

package/template/components/ui/slider.tsx

@@ -0,0 +1 @@
+export * from "@exxatdesignux/ui/components/slider"

package/template/docs/blueprints/README.md

@@ -0,0 +1,86 @@
+# Exxat DS — Blueprints
+
+**Audience:** humans + AI agents.
+**Inspired by:** [SLDS Component Blueprints](https://www.lightningdesignsystem.com/components).
+
+A **blueprint** is a **framework-agnostic spec** for a UI pattern. It says
+*what* the pattern is, *what it must do*, and *what tokens it consumes* —
+**without committing to any one implementation**.
+
+A **component** is the React + Tailwind implementation that satisfies the
+blueprint inside this app.
+
+| Blueprint says… | Component does… |
+|---|---|
+| "A page header has a title, optional icon, optional meta line, optional action slot, optional `+ N collaborators` rail" | `PageHeader` renders that with `variant="object-home" / "record-home" / "collaboration"` etc. |
+| "A data list is a sortable, filterable, columnable grid of records with search, properties drawer, and view tabs" | `DataTable` + `ListPageTemplate` + `TablePropertiesDrawer` compose to satisfy this |
+
+---
+
+## Why blueprints exist
+
+1. **They survive framework changes.** If we ever ship a second consumer
+   (mobile, embed widget, design-token export to Figma), the blueprint stays
+   true; only the implementation changes.
+2. **They make the design language explicit.** New contributors can read a
+   single page that says "this is what a page header **is** at Exxat" without
+   spelunking through React props.
+3. **They let designers, engineers, and AI agents share one vocabulary.** The
+   blueprint is the contract; the React component is the receipt.
+
+---
+
+## Anatomy of a blueprint doc
+
+Each blueprint follows the same template. Copy it from
+[`_template.md`](./_template.md) when adding a new one.
+
+```
+# <Blueprint name>
+
+## 1. Intent          → What user need does this solve? When NOT to use it.
+## 2. Anatomy         → Required + optional slots, with an ASCII or markdown sketch.
+## 3. States          → Default, hover, active, disabled, loading, empty, error, RTL.
+## 4. Tokens consumed → Exact token names from `docs/token-taxonomy.md`.
+## 5. Accessibility   → Roles, focus order, keyboard, screen-reader.
+## 6. Variants        → Named families that share anatomy but swap layout/density.
+## 7. Implementation  → Table of frameworks → component(s); React is required.
+## 8. Do / Don't      → Anti-patterns + correct alternatives.
+## 9. References      → Linked AGENTS.md sections, cursor rules, related blueprints.
+```
+
+The React row in §7 is **required**; other frameworks are listed as `—` until
+they ship.
+
+---
+
+## Authoritative file pointers
+
+For most patterns, the blueprint complements an existing narrative doc — it
+does **not** replace it. The blueprint is the spec; the narrative is the deep
+dive.
+
+| Blueprint | Narrative doc | Cursor rule(s) | React component(s) |
+|---|---|---|---|
+| [page-header](./page-header.md) | `apps/web/docs/data-views-pattern.md` (Page header section) | `exxat-collaboration-access.mdc` (variant), `exxat-mono-ids.mdc` (subtitle IDs) | `PageHeader`, `PlacementsPageHeader`, `TeamPageHeader`, `QuestionBankPageHeader` |
+| [data-table](./data-table.md) | `apps/web/docs/data-views-pattern.md` | `exxat-data-tables.mdc`, `exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc` | `DataTable`, `DataTablePaginated`, `useTableState`, `TablePropertiesDrawer` |
+| [list-page-template](./list-page-template.md) | `apps/web/docs/data-views-pattern.md`, `kpi-flat-band-pattern.md` | `exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc`, `exxat-list-page-view-shells.mdc` | `ListPageTemplate`, `HubTable`, `useTableState`, `TablePropertiesDrawer` |
+| [board-card](./board-card.md) | `apps/web/docs/data-views-pattern.md` (board UI section) | `exxat-board-cards.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-card-vs-list-rows.mdc` | `ListPageBoardCard`, `ListPageBoardCardTitleRow`, `ListPageBoardCardBadgeRow`, `BoardCardTwoLineBlock`, `BoardCardIconRow`, `ListHubStatusBadge` |
+| [key-metrics](./key-metrics.md) | `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md` | `exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` | `KeyMetrics`, `MetricItem`, `MetricInsight`, `KeyMetricsProvider` |
+
+Future blueprints to write (open a PR when adding one):
+
+- `drawer-vs-dialog.md` — overlay decision (already in `docs/drawer-vs-dialog-pattern.md`, formalize as blueprint)
+- `command-menu.md` — global ⌘K palette + Ask Leo split
+- `dedicated-search.md` — landing vs results
+- `sidebar.md` — primary nav + secondary panel + product switcher
+- `coach-mark.md` — onboarding tours
+- `status-badge.md` — `ListHubStatusBadge` + `lib/list-status-badges.ts`
+
+---
+
+## See also
+
+- [`apps/web/docs/token-taxonomy.md`](../token-taxonomy.md) — the design-token namespace these blueprints reference
+- [`apps/web/docs/component-selection-guide.md`](../component-selection-guide.md) — decision tree across blueprints
+- [`apps/web/AGENTS.md`](../../AGENTS.md) §9 architecture pointers (component reuse table)

package/template/docs/blueprints/_template.md

@@ -0,0 +1,91 @@
+# Blueprint: <Name>
+
+> **Status:** Draft / Stable. **Owner:** <team or person>. **Implements:** <SC refs>.
+
+## 1. Intent
+
+What user need does this pattern solve? In one paragraph.
+
+**Use when:**
+- Bullet
+- Bullet
+
+**Do NOT use when:**
+- Bullet
+
+## 2. Anatomy
+
+ASCII / markdown sketch with labelled slots. List every named slot and whether
+it is required, optional, or conditional.
+
+```
+┌──────────────────────────────────────────┐
+│ [icon]  Title                  [actions] │  ← slot: title-row (required)
+│ ───────────────────────────────────────  │
+│ subtitle · ID · meta                     │  ← slot: meta (optional)
+└──────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `title` | required | Single H1 string |
+| `icon` | optional | FA glyph or product mark |
+| `actions` | optional | Primary CTA + optional `⋯` overflow |
+| `meta` | optional | Count · freshness · sort summary |
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Default | … |
+| Loading | … |
+| Empty | … |
+| Error | … |
+| RTL | … |
+
+## 4. Tokens consumed
+
+List every token the blueprint references from
+[`docs/token-taxonomy.md`](../token-taxonomy.md). Be precise — no "a brand
+color"; name `--brand-color`.
+
+| Token | Used for |
+|---|---|
+| `--background` / `--foreground` | Surface + ink |
+| … | … |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.1.1 Non-text content | Icons are decorative (Case A) when adjacent to text; standalone icons follow Case B (label + tooltip) |
+| 1.3.1 Info & relationships | … |
+| 2.1.1 Keyboard | Tab order: … |
+| 2.4.6 Headings / labels | The title slot is the `<h1>` for the route |
+| 2.4.11 Focus visible | Inherits `:focus-visible` ring (≥ 3:1) |
+
+## 6. Variants
+
+| Variant | When to use | Differences from default |
+|---|---|---|
+| `base` | … | — |
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `PrimaryComponent` + `RelatedComponent` | `apps/web/components/<file>.tsx` |
+| Mobile | — | — |
+| Figma | — | — |
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Bullet | Bullet |
+
+## 9. References
+
+- `apps/web/docs/<related-narrative>.md`
+- `.cursor/rules/<related-rule>.mdc`
+- `apps/web/AGENTS.md` §<section>

package/template/docs/blueprints/board-card.md

@@ -0,0 +1,123 @@
+# Blueprint: Board card
+
+> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.1.1, 1.3.1, 2.5.8, 4.1.2.
+
+## 1. Intent
+
+A **board card** is the kanban-tile presentation of a single hub record (e.g.
+one Placement, one Team member, one Question-bank item) when the active view
+is `board`. The card surfaces the most-scannable summary fields — title, owner
+avatar, status chip, 1-3 meta lines — and is sized so a column holds 6-10
+cards on a 1280-wide viewport.
+
+**Use when:**
+
+- The hub's `board` view tab is active.
+- The record has a **status** (or equivalent grouping) that drives column placement.
+- Users compare ~6-30 records side-by-side and would benefit from owner / status visibility.
+
+**Do NOT use when:**
+
+- The record needs ≥ 4 fields to be useful at a glance (use list / table).
+- The dataset has > ~100 records per column (board UX collapses; use table + filters).
+- The hub does not model status / lifecycle (use folder grid or list).
+
+## 2. Anatomy
+
+```
+┌──────────────────────────────────────────────┐
+│  Title row                       [avatar]    │  ← slot: title (required) + trailing (optional)
+│ ──────────────────────────────────────────── │
+│  [status chip]                               │  ← slot: badgeRow (optional, when status exists)
+│ ──────────────────────────────────────────── │
+│  Body — primary stat (large) + sub label     │  ← slot: body (optional)
+│  ▣ row icon · meta label · meta value        │
+│  ▣ row icon · meta label · meta value        │
+└──────────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `title` | required | `ListPageBoardCardTitleRow` — single-line truncated title |
+| `trailing` | optional | `ListPageBoardCardAvatar` (owner) or another single glyph |
+| `badgeRow` | optional | `ListPageBoardCardBadgeRow` + `ListHubStatusBadge surface="board"` |
+| `body` | optional | `ListPageBoardCardBody` containing `BoardCardTwoLineBlock` / `BoardCardIconRow` |
+| `footer` | optional | Counts, freshness, or a small CTA — kept low-emphasis |
+
+The shell is `ListPageBoardCard` (`Card size="sm"` treatment) — do NOT compose
+a bespoke `<button>` + border-class wrapper for the same pattern.
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Default | Surface 2 background, hairline border, no shadow |
+| Hover | Border deepens; subtle elevation shift (matches `Card size="sm"`) |
+| Focused | `:focus-visible` ring on the outer element (≥ 3:1) |
+| Selected (drag source / active drag target) | `data-selected` border + brand tint |
+| Loading | Skeleton shell mirroring title row + badge row + body |
+| Empty column | Column footer shows "+ Add" affordance with `aria-label` per column |
+| RTL | All trailing slots flip; status chip flips alignment |
+
+## 4. Tokens consumed
+
+| Token | Used for |
+|---|---|
+| `--exxat-color-surface-2` / `--card` | Card background |
+| `--exxat-color-border-1` / `--border` | Card hairline |
+| `--exxat-color-ink-1` / `--foreground` | Title text |
+| `--exxat-color-ink-2` / `--muted-foreground` | Meta label text |
+| `--exxat-color-focus-ring` / `--ring` | `:focus-visible` ring |
+| `--exxat-radius-2` / `--radius-md` | Card corners |
+| Status-tint variables (`LIST_HUB_STATUS_TINT_*`) | Status chip background + text |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.1.1 Non-text content | Icons in `BoardCardIconRow` are decorative when paired with a visible label (Case A); standalone glyphs get Case B label + tooltip |
+| 1.3.1 Info & relationships | The card is one `<article>` (or `role="listitem"` inside the column's `role="list"`); status, owner, and meta rows are programmatically related to the title |
+| 2.5.8 Target size | The whole card is the primary click target — ≥ 24×24 CSS px; small icon controls inside use `size-6` (≥ 24px) |
+| 4.1.2 Name / role / value | If the card is interactive (opens detail) it is rendered as `<button>` with an accessible name combining title + status |
+
+## 6. Variants
+
+| Variant | When to use | Differences from default |
+|---|---|---|
+| `base` | Most hubs | Title + status badge + body |
+| `no-status` | Hubs without lifecycle (Question bank items) | Omit `badgeRow`; body carries the differentiator |
+| `compact` | Dense boards (10+ cards visible) | Drop body; show title + status + avatar only |
+| `with-progress` | Workflow boards with completion bar | Add a `<Progress>` row in the body slot |
+
+## 6.1 List-row counterpart
+
+`ListPageBoardCard layout="row"` is the same component shape rendered as a
+horizontal row for the `list` view tab. Use one renderer for both views so the
+**title / status / owner / meta** mapping stays consistent — never define two
+parallel components for "card" and "row" of the same hub.
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `ListPageBoardCard` + `ListPageBoardCardTitleRow` + `ListPageBoardCardBadgeRow` + `ListPageBoardCardBody` + `BoardCardTwoLineBlock` + `BoardCardIconRow` + `ListHubStatusBadge` | `@exxatdesignux/ui/components/data-views` + `apps/web/lib/list-status-badges.ts` |
+| Board template | `ListPageBoardTemplate` (column shells + `renderCard`) | `@exxatdesignux/ui/components/data-views/list-page-board-template` |
+| Mobile | — | — |
+| Figma | "Board card – hub" component in DS library | — |
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Use `ListPageBoardCard` as the shell; compose primitives inside | Wrap a bespoke `<button>` with border / padding utility classes for the same pattern |
+| Status: `ListHubStatusBadge surface="board"` + entity-specific map from `lib/list-status-badges.ts` | Show status as plain body text when the hub uses `ListHubStatusBadge` elsewhere |
+| Pull rows from `tableState.rows` so board honors filters / search | Hydrate cards from a separate `BOARD_MOCK[]` array |
+| Match list-row + table-row + card field choices via one mapper per hub | Define a card-only field projection that diverges from the table |
+| Use `Tip` on any icon-only control inside the card | Rely on `aria-label` alone for icon-only affordances inside the card |
+
+## 9. References
+
+- `apps/web/docs/data-views-pattern.md` — board UI section
+- `.cursor/rules/exxat-board-cards.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-card-vs-list-rows.mdc`
+- `apps/web/AGENTS.md` §4.4 (board cards), §13 (checklist)
+- `apps/web/lib/list-status-badges.ts` — `LIST_HUB_STATUS_TINT_*` + entity maps