@exxatdesignux/ui 0.5.5 → 0.5.7

package/consumer-extras/patterns/jobs/record-detail.md

@@ -0,0 +1,177 @@
+# Job: Review a record's full state
+
+> **Surface type:** Standalone route OR side-panel sheet.
+> **Examples in product:** Student profile, Placement record, Library item,
+> Site profile, Team member profile.
+
+## 1. The job
+
+The user lands on a single record and needs to **understand its current
+state** in order to **decide what to do next**. Decisions can include:
+contact someone, edit a field, change status, place / unplace, archive,
+follow up later, or simply confirm correctness before another action.
+
+This job is **not**: edit (separate flow), bulk action (lives on the list),
+configure workspace settings.
+
+## 2. When this job applies
+
+- The record has > ~5 displayable fields.
+- The user reaches it from a list, search, deep link, or notification.
+- The user's next action depends on the record's state (status, ownership,
+  data freshness).
+- The record may have children (placements, attachments, comments) that
+  matter to the decision.
+
+## 3. Pattern: route vs sheet vs inline
+
+| Pattern | When | DS comp |
+|---------|------|---------|
+| **Standalone route** (`/students/[id]`) | Deep link from email / notifications / reports; user may keep tab open; record has > 10 fields | `PrimaryPageTemplate` + `PageHeader` |
+| **Sheet over hub** | User is triaging from a list and may open many records in sequence | `Sheet` over `ListPageTemplate` |
+| **Inline expansion** (`HoverCard`) | Read-only quick preview; < 5 fields | `HoverCard` on row hover |
+
+Pick **route** by default. Pick **sheet** if the user's primary path is
+triaging from a list and they typically open many in a single session.
+
+## 4. Information architecture
+
+```
+┌─ SiteHeader (breadcrumb only) ──────────────────────────────────┐
+│  Dashboard › Students › Jordan Lee                              │  ← ancestors + title (P1, P2)
+└──────────────────────────────────────────────────────────────────┘
+┌─ Identity row ──────────────────────────────────────────────────┐
+│  [Avatar] Jordan Lee                              [Edit] [⋯]    │  ← name, ID, primary action + overflow
+│          STU-2026-1042 · jordan.lee@example.edu                 │
+└──────────────────────────────────────────────────────────────────┘
+┌─ Status row (above the fold, P13) ──────────────────────────────┐
+│  ● Active   ✓ Compliant   ⊕ Placed at Sinai                     │
+└──────────────────────────────────────────────────────────────────┘
+┌─ Field groups (2-col card grid) ────────────────────────────────┐
+│  Program     │  Academic                                         │
+│  Placement   │  Compliance                                       │
+└──────────────────────────────────────────────────────────────────┘
+┌─ Activity timeline (M7, optional) ──────────────────────────────┐
+│  Today · Compliance status updated by Maria                      │
+│  Tue · Placement assigned · Sinai Hospital                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Layers, in priority order
+
+1. **Identity** — name, system ID (mono), avatar, primary contact link.
+2. **Status** — every status badge that drives a decision; visible without
+   scrolling (P13).
+3. **Field groups** — 2-column card grid by default. Group by **conceptual
+   coherence** (Program / Academic / Placement / Compliance), not by table
+   structure.
+4. **Activity timeline** — if the record changes over time and the history
+   matters (M7).
+5. **Related lists** — placements, comments, attachments — if they exist for
+   this entity.
+
+### When to use section tabs
+
+- **Don't tab** if total field count is ≤ ~20 and groups are ≤ 4. Single
+  scroll is faster.
+- **Do tab** if the record has rich children (placements history,
+  supervisors, contracts, conversation threads) and the user typically
+  deep-dives into one section.
+- Tabs use `Tabs` + `TabsList` `w-fit` `variant="line"` — never full-width
+  (`exxat-tabs-chrome.mdc`).
+
+## 5. Navigation — the way back
+
+**Exactly one path back** (P1).
+
+| Reached from | Way back |
+|--------------|----------|
+| List route | `SiteHeader` breadcrumb (`Students`) |
+| Deep link / email | `SiteHeader` breadcrumb to the canonical parent |
+| Sheet from hub | `Sheet` close (X / Esc) |
+| Notification | Breadcrumb to canonical parent (not "Back to notification") |
+
+**Never** add a body-level "Back to <parent>" button when the breadcrumb is
+present (`exxat-breadcrumbs-no-back.mdc`).
+
+## 6. Actions
+
+| Slot | Component | What goes here |
+|------|-----------|----------------|
+| Primary | `PageHeader.primaryAction` (`Button variant="default" size="lg"`) | The single most common next action — "Edit", "Place", "Approve" |
+| Overflow | `Button variant="outline" size="icon-lg"` → `DropdownMenu` | Export, Archive, Duplicate, Share, dangerous-but-rare actions |
+| Inline | Icon-only buttons with tooltip | Copy email, dial phone, open site |
+| Status flip | `Sheet` or inline `Select` | Status changes that are audited (multi-step) |
+
+Exactly **one** filled CTA per surface (P3).
+
+## 7. States
+
+| State | What to show |
+|-------|--------------|
+| **Loading** | `Skeleton` matching the IA shape (identity → status → cards) — M9 |
+| **Empty / not found** | `EmptyState` + "Return to <list>" outline button |
+| **Error** | `LocalBanner` inside the body; identity row still renders if available |
+| **Stale data** | Subtle "Updated <relative>" in identity meta |
+
+## 8. Accessibility
+
+- One `<h1>` (P2) — typically `PageHeader.title`.
+- Status row is a `role="list"`; each badge is `role="listitem"` (already in
+  `ListHubStatusBadge`).
+- Inline mailto / tel links are real `<a>`s, not buttons.
+- Tab order: breadcrumb → identity → primary action → overflow → status →
+  fields → activity → related.
+- Icon-only actions carry `aria-label` + a tooltip with the same text.
+
+## 9. Modern SaaS analogues
+
+| Product | What to study |
+|---------|---------------|
+| **Linear** issue detail | Identity + status + properties + activity; sheet variant for triage |
+| **Stripe Dashboard** customer / charge | Identity + status badges + grouped data + audit log |
+| **Notion** page-as-database row | Inline editing (M5), property panel |
+| **Plain / Pylon** ticket | Conversation-as-document for support records |
+
+Cite these in the design brief by name + Mx codes:
+`Linear issue detail (M1, M4, M7)`.
+
+## 10. Anti-patterns
+
+| Anti-pattern | Use instead |
+|--------------|-------------|
+| `<h1>` + `PageHeader title` + breadcrumb leaf all repeating the name | One carrier: `PageHeader title` + ancestors-only breadcrumb (P2) |
+| "Back to <parent>" button alongside the breadcrumb | Breadcrumb only (P1) |
+| Two filled CTAs in the header ("Save" + "Submit") | One filled, others outline (P3) |
+| Status only in detail (hidden on list / breadcrumb count) | Status visible everywhere the record appears (M4) |
+| Status communicated by color only | Color + icon + label (`ListHubStatusBadge`) |
+| Full-width section tab bar | `Tabs` `w-fit` (`exxat-tabs-chrome.mdc`) |
+| Centered modal for "Edit name" | Inline edit (M5) or `Sheet` (M3) |
+| Spinner overlay for initial load | `Skeleton` matched to IA (M9) |
+| Activity timeline buried in a tab nobody opens | Show inline below cards, or remove it |
+| New shared "ProfileHero" component invented per entity | Compose: `PageHeader` + identity-row primitives (P8) |
+| `toast()` on save | Inline button label change + `LocalBanner` if persistent |
+
+## 11. Quick checklist (post-build audit)
+
+- [ ] Breadcrumb shows ancestors + title; no duplicate name.
+- [ ] No body "Back to <parent>" button.
+- [ ] One H1.
+- [ ] Status row visible without scrolling.
+- [ ] One filled primary action; overflow has the rest.
+- [ ] 2-col card grid for fields (or tabs if ≥ 4 sections / 20+ fields).
+- [ ] `Skeleton` matches the IA on load; empty state designed for "not found".
+- [ ] Tab order: breadcrumb → identity → primary → overflow → fields.
+- [ ] All status chips use `ListHubStatusBadge` + `lib/list-status-badges.ts`.
+- [ ] No `toast()`, no Vaul, no pixel-copy of legacy.
+
+## 12. Reference
+
+- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md)
+- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc)
+- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc)
+- [`../../../.cursor/rules/exxat-breadcrumbs-no-back.mdc`](../../../.cursor/rules/exxat-breadcrumbs-no-back.mdc)
+- [`../../../.cursor/rules/exxat-tabs-chrome.mdc`](../../../.cursor/rules/exxat-tabs-chrome.mdc)
+- [`../modern-saas-patterns.md`](../modern-saas-patterns.md)
+- [`../blueprints/page-header.md`](../blueprints/page-header.md)
+- [`../component-selection-guide.md`](../component-selection-guide.md) §1

package/consumer-extras/patterns/modern-saas-patterns.md

@@ -0,0 +1,165 @@
+# Modern SaaS patterns — the canon Exxat DS works against
+
+> **Audience:** humans + AI agents.
+> **Companion to:** [`exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md),
+> [`exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc),
+> [`jobs/`](./jobs/).
+
+A senior designer recognizes the work. This doc names the patterns the best
+products converged on in 2024–2026, so the agent can pattern-match instead
+of inventing. **Cite by name + code** when you reference one in a design brief
+(e.g. `Linear issue detail (M1, M4, M7)`).
+
+## Canon products — cite by product, not by URL
+
+| Product | What to learn from it |
+|---------|-----------------------|
+| **Linear** | Issue detail, command palette spine, density, keyboard-first, presence, "less chrome" |
+| **Notion** | Inline editing, property panels, page-as-database, blocks, slash-commands |
+| **Stripe Dashboard** | Record home, status chips, activity log, money-grade precision |
+| **Figma** | Multiplayer, presence, side panel inspector, infinite-canvas chrome discipline |
+| **Vercel** | Type-first hierarchy, dark-first, minimal chrome, log streams |
+| **Height** | View tabs (table/board/timeline), custom fields, view parity |
+| **Plain / Pylon** | Support detail = identity + timeline + actions; conversation-as-document |
+| **Cron / Amie** | Keyboard-only flows, dense calendar, command surface |
+| **Raycast** | Command palette as full app, extension surface, deep keyboard |
+| **Arc Browser** | Control-stripped, content-first, sidebar as the only chrome |
+
+## The 12 patterns that make products feel modern
+
+### M1. Content-first chrome
+The data is the star. Sidebars collapse to icons. Headers stay 48–56px. Page
+surfaces are generous. No purple gradient on the top bar.
+
+- **In DS:** `SiteHeader` ~h-12; `PrimaryPageTemplate` body has generous
+  `max-w-[1440px]`; sidebar collapsible (`SidebarTrigger`).
+
+### M2. Command palette as the spine
+`⌘K` opens search + navigation + AI + recent. It is the primary navigation
+for power users. The sidebar exists for orientation, not speed.
+
+- **In DS:** `CommandMenu` (⌘K) + Ask Leo split (⌘⌥K).
+  Rule: `exxat-command-menu.mdc`.
+
+### M3. Side-panel detail over modal dialog
+For non-destructive context-keeping actions (properties, export, invite,
+preview, single-step compose), use a slide-in sheet — never a centered modal.
+
+- **In DS:** `Sheet` (no Vaul).
+  Rule: `exxat-drawer-vs-dialog.mdc`. Pattern:
+  `apps/web/docs/drawer-vs-dialog-pattern.md`.
+
+### M4. Status as a first-class citizen
+Colored dots, chips, counts visible everywhere data appears. Status isn't
+hidden in a detail page; it appears on rows, cards, headers, navigation.
+
+- **In DS:** `ListHubStatusBadge` + `lib/list-status-badges.ts`. Available per
+  row, board card, detail header, breadcrumb count slot.
+
+### M5. Inline editing where data is read
+Click the value, edit it. No bounce to forms for single-field changes.
+
+- **In DS:** Inline-edit primitive emerging; until then, use a `Sheet` for
+  multi-field, popover or contenteditable for single-field. Principle: P15.
+
+### M6. Optimistic UI + undo
+Low-risk actions (favorite, archive, status flip) feel instant; reconcile on
+error. Undo via banner or in-place affordance — **never** toast
+(`exxat-no-toast.mdc`).
+
+- **In DS:** Optimistic state in `useTableState` selection ops; undo via
+  `LocalBanner` with action.
+
+### M7. Activity timeline on every record
+Who did what when. The audit log is also a navigation device.
+
+- **In DS:** `ActivityTimeline` primitive emerging. Compose from
+  `lib/mock/activity` shape until then.
+
+### M8. Empty states with one CTA + one sentence
+Illustration optional. One sentence of context. One primary action. Never a
+wall of help text or a tutorial inline.
+
+- **In DS:** `EmptyState` primitive; voice from `docs/voice-and-tone.md`.
+
+### M9. Skeleton, not spinner
+Loading shapes content. Spinners only for indeterminate < 200ms.
+
+- **In DS:** `Skeleton` primitive; suspense boundaries shape the body.
+
+### M10. Type-first hierarchy
+Weight, size, color do the heavy lifting before borders, boxes, or tints.
+Ornament is rare and intentional.
+
+- **In DS:** Token scale; body in `Inter`; display in `Ivy Presto` (only on
+  `PageHeader` H1 by default).
+
+### M11. Real-time presence + collaboration as default
+If the product is shared, show who else is here — face rails, cursors,
+status. Inviting others is one click from the page.
+
+- **In DS:** `PageHeader variant="collaboration"` face rail +
+  `InviteCollaboratorsDrawer`.
+  Rule: `exxat-collaboration-access.mdc`.
+
+### M12. AI as opt-in sidecar
+Ask Leo style — never the primary path, never auto-runs on a record, always
+discoverable, always cancellable. Deterministic path still exists.
+
+- **In DS:** `AskLeoSidebar` + `⌘⌥K` toggle; never a "magic" button on a
+  destructive surface.
+
+---
+
+## The anti-modern signals (what NOT to do)
+
+| Signal | Why it's dated |
+|--------|----------------|
+| Toasts everywhere | Modern products use inline + banner + undo. Toasts get missed. |
+| Full-width tab bars stretched edge-to-edge | 2010s pattern. Modern uses `w-fit` segmented controls. |
+| Centered modals for everything | Sheets and routes carry more without breaking flow. |
+| Color-coded sidebar sections | Modern is monochrome chrome + status color on data. |
+| Modal wizards with progress bar | If it has > 3 steps, give it a route. |
+| Spinners on initial load | Skeleton the content shape instead. |
+| Hover-only affordances | Touch + keyboard need parity. |
+| Icons without text labels in primary nav | Recognition fails for new users. |
+| "Beautiful" gradients on chrome | Data should be beautiful; chrome should disappear. |
+| Aggressive empty-state illustrations | One sentence + one action beats illustration + 5 tips. |
+| Edit-takes-you-to-a-form for single fields | Inline edit (M5). |
+| "Back to <parent>" button alongside breadcrumb | P1 — choose one. |
+| Auto-running AI on record open | M12 — opt-in only. |
+
+---
+
+## Density layers (Linear / Vercel model)
+
+| Layer | When |
+|-------|------|
+| **Cozy** (default) | Most surfaces; balances scan + breathing room |
+| **Compact** | Power users on daily workflow; tables, command results |
+| **Comfortable** | Accessibility (low-vision, motor); marketing-adjacent |
+
+Provide a user-level setting where audiences differ; default to **cozy**.
+Don't fork stacks per density.
+
+---
+
+## How to use this doc in a design brief
+
+```
+Reference (modern): Linear issue detail (M1, M4, M7),
+                    Stripe customer record (M4, M11)
+```
+
+Cite the **patterns (Mx)** the agent applied, not just the product. Forces
+clear thinking and lets reviewers verify intent.
+
+## See also
+
+- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md) — persona
+- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc) — brief gate
+- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc) — principles + breaks
+- [`./jobs/`](./jobs/) — canonical reference per job type
+- [`./component-selection-guide.md`](./component-selection-guide.md) — picking the composition
+- [`./blueprints/`](./blueprints/) — framework-agnostic surface specs
+- [`./voice-and-tone.md`](./voice-and-tone.md) — copy rules

package/dist/components/data-table/index.js

@@ -1443,15 +1443,6 @@ function useTableState(data, columns, defaultSort, paginationOverride, syncedSea
     });
     return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, groupRows]) => ({ groupKey: key, groupLabel: key, rows: groupRows }));
   }, [rows, groupBy]);
-  const LOCKED_KEYS = React9.useMemo(() => new Set(Object.keys(lockedPins)), [lockedPins]);
-  const effectivePins = React9.useMemo(() => {
-    if (isReflowViewport || !isOverflowing) return {};
-    const result = {};
-    for (const [key, pin] of Object.entries(colPins)) {
-      result[key] = pin;
-    }
-    return result;
-  }, [colPins, isOverflowing, isReflowViewport]);
   const displayCols = React9.useMemo(() => {
     const leftPinned = [];
     const free = [];
@@ -1471,6 +1462,19 @@ function useTableState(data, columns, defaultSort, paginationOverride, syncedSea
     }
     return out;
   }, [colOrder, colPins, hiddenCols, columnsByKey]);
+  const totalWidth = React9.useMemo(
+    () => displayCols.reduce((s, c) => s + (colWidths[c.key] ?? c.width ?? 100), 0),
+    [displayCols, colWidths]
+  );
+  const LOCKED_KEYS = React9.useMemo(() => new Set(Object.keys(lockedPins)), [lockedPins]);
+  const effectivePins = React9.useMemo(() => {
+    if (isReflowViewport || !isOverflowing) return {};
+    const result = {};
+    for (const [key, pin] of Object.entries(colPins)) {
+      result[key] = pin;
+    }
+    return result;
+  }, [colPins, isOverflowing, isReflowViewport]);
   function startResize(key, e) {
     e.preventDefault();
     e.stopPropagation();
@@ -1531,18 +1535,21 @@ function useTableState(data, columns, defaultSort, paginationOverride, syncedSea
   function toggleWrap(key) {
     setColWrap((p) => ({ ...p, [key]: !p[key] }));
   }
-  function checkOverflow() {
+  const checkOverflow = React9.useCallback(() => {
     const el = scrollRef.current;
     if (!el) return;
-    setIsOverflowing(el.scrollWidth > el.clientWidth + 1);
-  }
+    setIsOverflowing(totalWidth > el.clientWidth + 1);
+  }, [totalWidth]);
   function handleScroll() {
     const el = scrollRef.current;
     if (!el) return;
     setScrolled(el.scrollLeft > 1);
     setScrollEnd(el.scrollLeft >= el.scrollWidth - el.clientWidth - 1);
-    setIsOverflowing(el.scrollWidth > el.clientWidth + 1);
+    setIsOverflowing(totalWidth > el.clientWidth + 1);
   }
+  React9.useLayoutEffect(() => {
+    checkOverflow();
+  }, [checkOverflow]);
   function getRowId(row, index, getIdFn) {
     return getIdFn ? getIdFn(row, index) : row.id ?? index;
   }
@@ -1595,10 +1602,6 @@ function useTableState(data, columns, defaultSort, paginationOverride, syncedSea
     },
     [effectivePins, isReflowViewport, stickyOffsets]
   );
-  const totalWidth = React9.useMemo(
-    () => displayCols.reduce((s, c) => s + (colWidths[c.key] ?? c.width ?? 100), 0),
-    [displayCols, colWidths]
-  );
   return {
     // Sort
     sortRules,
@@ -2338,7 +2341,7 @@ function DataTableInner({
     setSheetOpen,
     setSheetInitialPanel
   } = state;
-  React9.useEffect(() => {
+  React9.useLayoutEffect(() => {
     const syncScrollport = () => {
       const el2 = scrollRef.current;
       if (el2) {
@@ -2351,8 +2354,10 @@ function DataTableInner({
     if (!el) return;
     const ro = new ResizeObserver(syncScrollport);
     ro.observe(el);
+    const table = el.querySelector("table");
+    if (table) ro.observe(table);
     return () => ro.disconnect();
-  }, []);
+  }, [totalWidth, displayCols.length, checkOverflow, scrollRef]);
   const columnMenuPendingActionRef = React9.useRef(null);
   const pinnedScrollHintDoneRef = React9.useRef(false);
   React9.useEffect(() => {
@@ -2589,11 +2594,12 @@ function DataTableInner({
         children: /* @__PURE__ */ jsxs(
           "table",
           {
-            className: "w-full text-sm border-separate border-spacing-0",
+            className: "text-sm border-separate border-spacing-0",
             style: {
               tableLayout: "fixed",
-              minWidth: totalWidth,
-              width: headerIsStuck ? floatingHeaderTableWidth : void 0
+              // Explicit column-sum width — `w-full` made the grid stretch to the scrollport
+              // so scrollWidth === clientWidth and the overflow-gated pin rule never fired.
+              width: totalWidth
             },
             children: [
               /* @__PURE__ */ jsx("colgroup", { children: displayCols.map((col) => /* @__PURE__ */ jsx("col", { style: { width: colWidths[col.key] ?? col.width ?? 100 } }, col.key)) }),