@exxatdesignux/ui 0.5.10 → 0.5.12

package/template/docs/voice-and-tone.md

@@ -1,262 +0,0 @@
-# Exxat DS — Voice and tone
-
-> The single biggest driver of "this feels like one product" — or "this feels random" — is **copy**. Empty states, errors, buttons, banners, validation, labels. This doc is the binding reference for all of it.
->
-> **Audience:** designers writing copy, engineers shipping strings, AI agents drafting UI text. Reviewed in PR alongside `.cursor/rules/exxat-accessibility.mdc`.
-
----
-
-## 1. Voice (the constant)
-
-Exxat copy is **clear, direct, and respectful**. We talk to grown professionals (faculty, admins) and to students. We never:
-
-- talk down (no "Oops!" / "Whoops" / "Uh-oh"),
-- over-celebrate ("Awesome!" / "Great job!" / 🎉),
-- guilt-trip ("You haven't… yet" / "Don't forget!"),
-- hide the cause behind metaphor ("Something went wrong" with no detail),
-- shout (sentence case everywhere; ALL CAPS only for system status acronyms).
-
-We **always**:
-
-- name the **thing**: the entity (placement, site, student), the action (Save, Invite, Export), the outcome (saved, sent, downloaded),
-- say what **changed** or what **the user can do next**,
-- use **present tense** (`Saving` / `Saved` / `Try again`), not past-aspirational (`We've saved your changes!`),
-- use **active voice** (`Exxat couldn't save the placement.` not `The placement could not be saved.`).
-
----
-
-## 2. Tone (the variable)
-
-Tone shifts by surface. Same voice, different temperature.
-
-| Surface | Tone | Example |
-|---|---|---|
-| Primary action label | Imperative, 1–3 words | "Save", "Invite people", "Export" |
-| Empty state (filtered) | Helpful, names the filter | "No placements match the current filters. Clear them to see all 247." |
-| Empty state (no data ever) | Welcoming, names the next step | "No placements yet. Add your first one to get started." |
-| Inline validation | Neutral, says the rule | "Use the format MM/DD/YYYY." |
-| Banner (informational) | Calm, explains why | "Read-only — this term has ended." |
-| Banner (warning) | Direct, says the consequence | "Saving will overwrite 3 students' assignments." |
-| Banner (error) | Honest, names the failure + next step | "Exxat couldn't reach the placement service. Try again, or check your network." |
-| Dialog (destructive confirm) | Specific, names the object | "Delete placement P-2026-014? This cannot be undone." |
-| Microcopy (helper, hints) | Brief, format-only | "Out of 4.0", "MM/DD/YYYY" |
-
----
-
-## 3. Buttons
-
-| Pattern | Use | Example |
-|---|---|---|
-| **Sentence case** | Always | `Save`, `Invite people`, `Export selection` |
-| **Title case** | Never | ~~`Save Changes`~~ → `Save changes` |
-| **Verb-first imperative** | Primary actions | `Save`, `Send invite`, `Create placement`, `Download CSV` |
-| **No "Please"** | The button is the request | ~~`Please save`~~ → `Save` |
-| **Don't repeat the field name** | Inline context is enough | ~~`Save changes to placement`~~ → `Save` |
-| **"Cancel" not "Discard"** | Cancel returns to a safe state; Discard is only for destructive draft loss | dialog primary = `Save changes`; cancel = `Cancel` |
-| **Loading verb** | When in-flight, swap to `…` form, preserve width | `Save` → `Saving…` |
-| **Disabled tooltip** | Always say why | "Add at least one collaborator first." |
-
-### Don't
-
-| ❌ Don't | ✅ Do |
-|---|---|
-| `Click here` | `Open placement` |
-| `OK` | `Save`, `Got it`, `Continue` (the actual outcome) |
-| `Submit` | `Send invite`, `Save changes`, `Create placement` |
-| `Yes` / `No` in destructive dialogs | `Delete placement`, `Cancel` |
-| `Loading…` for >2 s with no detail | `Loading placements…` (name the thing) |
-
----
-
-## 4. Empty states
-
-There are **three** kinds. The copy is different for each.
-
-### 4a. Filter-empty ("zero matches")
-
-The dataset has rows; the active filters hide all of them. Tell the user the filters are responsible and offer to clear them.
-
-```
-No placements match the current filters.
-[Clear filters]
-```
-
-Rules:
-
-- Name the entity ("placements", not "items").
-- Mention "the current filters" — not just "no results".
-- Surface a **Clear filters** action if the toolbar has any filters applied.
-- If the search box is the only filter, the message becomes `No placements match "<query>".` (quote the query exactly).
-
-### 4b. True-empty ("no data ever")
-
-The dataset is empty for this user / scope. Tell them what to do next.
-
-```
-No placements yet.
-Add your first one to start tracking student rotations.
-[New placement]
-```
-
-Rules:
-
-- One-line headline + one-line context.
-- The CTA is the same imperative used elsewhere in the app — don't invent "Start now" for an empty state.
-- If creation requires a precursor ("Add at least one site first"), say so and link to the precursor.
-
-### 4c. Permission-empty ("not allowed to see")
-
-The user can't see anything because of access. Don't show counts; don't suggest creating.
-
-```
-You don't have access to this hub.
-Ask a coordinator to invite you with Viewer or higher access.
-```
-
-Rules:
-
-- Name the access level required.
-- Don't show row counts the user can't see.
-- Don't expose the existence of restricted records by mentioning "0 of N hidden".
-
----
-
-## 5. Errors
-
-Errors must answer three questions: **What happened? Why? What can the user do?**
-
-| Element | Required? | Example |
-|---|---|---|
-| Subject | required | `Exxat couldn't save the placement.` |
-| Cause | when knowable | `The site was deleted while you were editing.` |
-| Next step | required | `Choose another site or refresh.` |
-
-### Don't
-
-- `Something went wrong.` — every word is empty. Replace with the subject + cause.
-- `Error 500: Internal Server Error.` — leak the trace ID to logs, not the user. User-facing: "Exxat had a problem. Try again in a moment."
-- Toasts for errors. Use `SystemBanner` (route-level) or inline `FormMessage` (field-level). See [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc).
-
-### Field-level (`FormMessage`)
-
-Match the rule, not the field name. Keep under 60 chars.
-
-| Rule | Message |
-|---|---|
-| Required | `This is required.` |
-| Format (date) | `Use MM/DD/YYYY.` |
-| Format (phone) | `Use +1 (555) 555-0100.` |
-| Range (number) | `Enter a number between 0 and 4.0.` |
-| Unique | `That ID is already in use.` |
-| Server | `Exxat couldn't save this field. Try again.` |
-
----
-
-## 6. Banners
-
-We use **persistent banners** (not toasts) for all product feedback. See [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) and `LocalBanner` / `SystemBanner` in `packages/ui`.
-
-| Variant | Use | Lead with |
-|---|---|---|
-| `info` | Read-only / scope notice / "you're viewing X" | The fact: "Read-only — this term has ended." |
-| `success` | Confirmed state change (long-lived; toasts forbidden) | The outcome: "Invite sent to 3 collaborators." |
-| `warning` | Action will cause consequence | The consequence: "Saving will overwrite 3 students' assignments." |
-| `error` | Recoverable failure | The subject + next step: "Exxat couldn't reach the placement service. Try again." |
-| `destructive` | Pending destructive change | The object + reversibility: "This term will be archived in 7 days. Restore now to keep it." |
-
-Rules:
-
-- One banner per region. If two compete, the higher-severity wins.
-- Pair a banner with an **action** when there's something the user can do (`[Restore]`, `[Try again]`, `[Open log]`).
-- No exclamation marks. The variant color carries the tone.
-
----
-
-## 7. Status badges
-
-Status labels live in [`lib/list-status-badges.ts`](../lib/list-status-badges.ts) and are shared across every surface (table, board card, list row). Don't fork labels per page.
-
-| Type | Conventions | Example |
-|---|---|---|
-| Lifecycle | Title case, single word where possible | `Active`, `Draft`, `Archived`, `Pending` |
-| Outcome | Past-tense verb when an action completed | `Approved`, `Rejected`, `Sent`, `Skipped` |
-| Risk | Plain language, no jargon | `On track`, `At risk`, `Blocked` |
-| Mandatory pairing | Color **AND** icon (WCAG 1.4.1 — never color alone) | green check, amber triangle, red circle-x |
-
-Never: `OK`, `N/A`, `?` as a status label. Show the actual lifecycle state or `Unknown` with a tooltip describing how to resolve it.
-
----
-
-## 8. KPI copy (the highest-stakes copy in the product)
-
-KPIs read top-down: **label → value → trend chip → description**. The reader is scanning, not reading. Each line earns its place.
-
-| Field | Rule | Example |
-|---|---|---|
-| `label` | Sentence case noun phrase. ≤ 24 chars. No "Total" prefix (the value is total by default). | `Active placements`, `New invites`, `Compliance issues` |
-| `value` | The number. Use `tabular-nums`. Round to a sensible precision. Suffix unit (`%`, `hrs`) without space when natural. | `247`, `12 %`, `38 hrs` |
-| `delta` | The **count** of change. Empty (`""` or `0`) hides the chip entirely. Never prose. | `+12`, `-3`, `+8 %` |
-| `description` | The caption beneath the value row. Prose explaining what the number is or how it splits. Never the delta. | `vs last week`, `across 4 sites`, `left + right` |
-
-See [`exxat-kpi-trends.mdc`](../../../.cursor/rules/exxat-kpi-trends.mdc) for the trend-polarity rules (when up means bad, set `trendPolarity: "lower_is_better"`).
-
-### Don't
-
-- `Total: 247` — drop "Total".
-- `247 placements` in `value` — put `247` in `value`, `placements` is in `label`.
-- `+5 (up 12 % from last week)` in `delta` — `delta = "+5"`, `description = "vs last week"`.
-
----
-
-## 9. Form labels and helper text
-
-| Element | Rule | Example |
-|---|---|---|
-| Label | Sentence case, no colon, no "*" — pair `*` decoration with `aria-required` only. | `Date of birth` |
-| Required marker | Visible `*` (`aria-hidden`), programmatic `aria-required="true"`. | `Date of birth *` |
-| Helper text | Persistent, format-first. Use `FormDescription`. Never placeholder-only. | `MM/DD/YYYY` |
-| Placeholder | May mirror the format. Never the sole carrier. | `MM/DD/YYYY` |
-| Inline error | Replaces helper while active. Match the rule, not the field name. | `Use MM/DD/YYYY.` |
-| Unit in label vs description | Units go in description when context-dependent (`Out of 4.0` under "GPA"), in label when fixed (`Hours per week`). | — |
-
-See [`exxat-accessibility.mdc`](../../../.cursor/rules/exxat-accessibility.mdc) §"Form fields — format hints MUST be persistent".
-
----
-
-## 10. Dates, times, numbers
-
-| Type | Format | Example |
-|---|---|---|
-| Date (UI) | Locale-aware, defaults to `MM/DD/YYYY` for en-US | `12/14/2025` |
-| Date range | Same format, en-dash with hair-thin spaces (or hyphen-minus in mono) | `12/14/2025 – 12/20/2025` |
-| Time | 12-hour with am/pm in lowercase | `2:30 pm` |
-| Relative time | Use sparingly; pair with absolute on hover/tooltip | `Updated 3 hours ago` (tip: `12/15/2025, 11:14 am`) |
-| Numbers | `tabular-nums`. Use thousands separator (`12,547`) for ≥ 4 digits | `12,547` |
-| Currency | Symbol-first, no space (`$1,200.00`) | `$1,200.00` |
-| Percent | No space (`12 %` is wrong, use `12%`) | `12%` |
-| Duration | Short form (`38 hrs`, `2 wks`) | `38 hrs` |
-
----
-
-## 11. Reviewer checklist (paste into PRs that touch copy)
-
-- [ ] Sentence case (not title case) everywhere.
-- [ ] No `Click here`, `Submit`, `OK`, `Loading…` without a noun.
-- [ ] No toasts; banners or inline status instead.
-- [ ] Empty state names the entity and surfaces a next action or "Clear filters".
-- [ ] Errors answer: what / why / what now.
-- [ ] Status labels come from `lib/list-status-badges.ts`, not new strings.
-- [ ] KPI `delta` is a count; KPI `description` is prose. Polarity matches the metric.
-- [ ] Form helper text is `FormDescription`, not placeholder-only.
-- [ ] No exclamation marks outside `success` banners (and even those rarely).
-- [ ] No emoji unless explicitly approved for that surface.
-
----
-
-## See also
-
-- [`HANDBOOK.md`](./HANDBOOK.md) — where this fits in the docs map
-- [`glossary.md`](./glossary.md) — vocabulary
-- [`.cursor/rules/exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) — why banners, not toasts
-- [`.cursor/rules/exxat-kpi-trends.mdc`](../../../.cursor/rules/exxat-kpi-trends.mdc) — KPI delta vs description
-- [`.cursor/rules/exxat-accessibility.mdc`](../../../.cursor/rules/exxat-accessibility.mdc) — format-hint persistence rule

package/template/ecosystem.config.cjs

@@ -1,32 +0,0 @@
-/**
- * PM2 — keep `next dev` running after the terminal closes; restarts on crash.
- * Start: `nvm use && npm run dev:daemon`
- * @see README.md — Development (daemon)
- * @see docs/perf-memory-pattern.md — Dev memory tuning
- */
-module.exports = {
-  apps: [
-    {
-      name: "exxat-ds",
-      script: "npm",
-      args: "run dev",
-      cwd: __dirname,
-      interpreter: "none",
-      autorestart: true,
-      max_restarts: 30,
-      min_uptime: "4s",
-      exp_backoff_restart_delay: 2000,
-      // Dev memory tuning. NODE_OPTIONS is inherited by the spawned Node
-      // process (`next-server`) — the npm parent doesn't read it but its
-      // children do. See docs/perf-memory-pattern.md §2.
-      env: {
-        NODE_OPTIONS: "--max-old-space-size=6144 --max-semi-space-size=64",
-        NEXT_TELEMETRY_DISABLED: "1",
-      },
-      // Recycle the daemon if the dev server's RSS climbs past 7GB rather
-      // than letting macOS swap. PM2 emits a `max_memory_restart` event so
-      // `pm2 logs` shows the restart cause.
-      max_memory_restart: "7G",
-    },
-  ],
-}

package/template/next.config.mjs

@@ -1,216 +0,0 @@
-import bundleAnalyzer from "@next/bundle-analyzer"
-
-const withBundleAnalyzer = bundleAnalyzer({
-  enabled: process.env.ANALYZE === "true",
-})
-
-const isDev = process.env.NODE_ENV !== "production"
-
-/**
- * Content Security Policy
- *
- * Allowlist matches the runtime third-party origins this app actually contacts
- * (see `app/layout.tsx` and `lib/{logo-dev,stock-portrait}.ts`):
- *
- *   • Font Awesome Pro Kit  — *.fontawesome.com (loader at kit.*, Pro CSS/font/telemetry
- *                             at ka-p.*, free fallback at ka-f.*). Wildcard is used
- *                             because FA rotates resource subdomains per kit tier and
- *                             every subdomain is FA-controlled.
- *   • Adobe Typekit         — use.typekit.net (CSS) + p.typekit.net (font files)
- *   • Avatars (mock)        — img.logo.dev (school logos), randomuser.me (mock portraits)
- *
- * `'unsafe-inline'` is kept for `style-src` because Tailwind injects inline styles
- * and the chart primitive uses one `<style dangerouslySetInnerHTML>` block for
- * per-instance CSS variables. `'unsafe-inline'` is kept for `script-src` because
- * Next.js inlines small bootstrap scripts (page data, RSC payload) on every
- * route; migrating to nonces is a separate refactor. `'unsafe-eval'` is only
- * permitted in development for HMR.
- *
- * If you add a new third-party origin (fonts, images, telemetry), update the
- * matching directive below before shipping.
- */
-function buildContentSecurityPolicy() {
-  // `https://*.fontawesome.com` covers every FA Kit subdomain (loader at
-  // `kit.fontawesome.com`, Pro resources at `ka-p.fontawesome.com`, free
-  // fallback at `ka-f.fontawesome.com`, telemetry, etc.) without us having to
-  // chase per-tier subdomain changes. Every subdomain is FA-controlled.
-  const FA_HOSTS = "https://*.fontawesome.com"
-
-  const scriptSrc = [
-    "'self'",
-    "'unsafe-inline'",
-    isDev ? "'unsafe-eval'" : "",
-    FA_HOSTS,
-  ]
-    .filter(Boolean)
-    .join(" ")
-
-  const styleSrc = [
-    "'self'",
-    "'unsafe-inline'",
-    "https://use.typekit.net",
-    "https://p.typekit.net",
-    FA_HOSTS,
-  ].join(" ")
-
-  const fontSrc = [
-    "'self'",
-    "data:",
-    "https://use.typekit.net",
-    "https://p.typekit.net",
-    FA_HOSTS,
-  ].join(" ")
-
-  const imgSrc = [
-    "'self'",
-    "data:",
-    "blob:",
-    "https://img.logo.dev",
-    "https://randomuser.me",
-    FA_HOSTS,
-  ].join(" ")
-
-  const connectSrc = [
-    "'self'",
-    "https://use.typekit.net",
-    FA_HOSTS,
-    // Next.js dev server uses websockets for HMR.
-    isDev ? "ws:" : "",
-    isDev ? "wss:" : "",
-  ]
-    .filter(Boolean)
-    .join(" ")
-
-  const directives = [
-    `default-src 'self'`,
-    `script-src ${scriptSrc}`,
-    `style-src ${styleSrc}`,
-    `font-src ${fontSrc}`,
-    `img-src ${imgSrc}`,
-    `connect-src ${connectSrc}`,
-    `frame-ancestors 'none'`,
-    `frame-src 'none'`,
-    `object-src 'none'`,
-    `base-uri 'self'`,
-    `form-action 'self'`,
-    `manifest-src 'self'`,
-    `worker-src 'self' blob:`,
-    // `upgrade-insecure-requests` is only meaningful on HTTPS responses.
-    isDev ? "" : "upgrade-insecure-requests",
-  ]
-    .filter(Boolean)
-    .join("; ")
-
-  return directives
-}
-
-const SECURITY_HEADERS = [
-  {
-    key: "Content-Security-Policy",
-    value: buildContentSecurityPolicy(),
-  },
-  // Defence-in-depth — `frame-ancestors 'none'` already blocks framing in
-  // modern browsers, but X-Frame-Options is still honoured by older clients
-  // and is required by some scanners.
-  { key: "X-Frame-Options", value: "DENY" },
-  { key: "X-Content-Type-Options", value: "nosniff" },
-  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
-  {
-    key: "Permissions-Policy",
-    value: [
-      "accelerometer=()",
-      "autoplay=()",
-      "camera=()",
-      "display-capture=()",
-      "encrypted-media=()",
-      "fullscreen=(self)",
-      "geolocation=()",
-      "gyroscope=()",
-      "magnetometer=()",
-      "microphone=()",
-      "midi=()",
-      "payment=()",
-      "picture-in-picture=()",
-      "publickey-credentials-get=()",
-      "screen-wake-lock=()",
-      "sync-xhr=()",
-      "usb=()",
-      "xr-spatial-tracking=()",
-      "interest-cohort=()",
-    ].join(", "),
-  },
-  // HSTS only takes effect over HTTPS; harmless on http://localhost during dev.
-  // Subdomain + preload opt-in — drop `; preload` if the apex domain is not
-  // ready for the HSTS preload list.
-  {
-    key: "Strict-Transport-Security",
-    value: "max-age=63072000; includeSubDomains; preload",
-  },
-  { key: "X-DNS-Prefetch-Control", value: "on" },
-  { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
-]
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  transpilePackages: ["@exxatdesignux/ui"],
-  // Hard cap on the Turbopack worker. Without this, the dev cache + module
-  // graph + mmap'd .meta files grow unbounded (we observed 3.2 GB on disk
-  // and 5+ GB RSS per process). 4 GiB is generous — Turbopack rarely needs
-  // more on apps with < ~1000 routes. See `docs/perf-memory-pattern.md` §6.
-  turbopack: {
-    memoryLimit: 4 * 1024 * 1024 * 1024,
-  },
-  // Dev memory tuning — see `docs/perf-memory-pattern.md` for rationale.
-  experimental: {
-    // Tree-shake heavy barrel re-exports. Every package here was identified by
-    // bundle analyzer as a re-export hot spot in the dev server's heap snapshot.
-    optimizePackageImports: [
-      "lucide-react",
-      "recharts",
-      "@exxatdesignux/ui",
-      "@tabler/icons-react",
-      "motion",
-      "@dnd-kit/core",
-      "@dnd-kit/sortable",
-      "@dnd-kit/modifiers",
-      "@dnd-kit/utilities",
-    ],
-    // Compile routes the user actually visits instead of pre-warming every
-    // entry on `next dev` start. The dev server reaches a usable state in
-    // ~2s instead of ~15s on this app and steady-state heap is ~30% lower.
-    preloadEntriesOnStart: false,
-    // Webpack fallback (`pnpm dev:webpack`) — drops large in-memory caches at
-    // the cost of slightly slower rebuilds. Ignored by Turbopack.
-    webpackMemoryOptimizations: true,
-  },
-  // Cap how long inactive routes stay compiled in the dev server's memory.
-  // Defaults (25s / 2 pages) are fine for small apps — keeping them explicit
-  // makes the trade-off discoverable when memory grows on a larger app.
-  onDemandEntries: {
-    maxInactiveAge: 25 * 1000,
-    pagesBufferLength: 2,
-  },
-  async headers() {
-    return [
-      {
-        // Apply to every route. Static assets under `/_next/static/*` get the
-        // same headers — that's fine since they are first-party.
-        source: "/:path*",
-        headers: SECURITY_HEADERS,
-      },
-    ]
-  },
-  async redirects() {
-    return [
-      // Legacy demo routes (placements, rotations, compliance, sites) were removed.
-      // Redirect anything pointing at them to Dashboard rather than 404.
-      { source: "/rotations", destination: "/dashboard", permanent: false },
-      { source: "/compliance", destination: "/dashboard", permanent: false },
-      { source: "/sites/all", destination: "/dashboard", permanent: false },
-      { source: "/sites/all/:path*", destination: "/dashboard", permanent: false },
-      { source: "/examples", destination: "/dashboard", permanent: false },
-    ]
-  },
-}
-
-export default withBundleAnalyzer(nextConfig)

package/template/postcss.config.mjs

@@ -1,8 +0,0 @@
-/** @type {import('postcss-load-config').Config} */
-const config = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
-}
-
-export default config

package/template/tests/setup.ts

@@ -1,26 +0,0 @@
-import "@testing-library/jest-dom/vitest"
-import { vi } from "vitest"
-
-// jsdom does not implement window.matchMedia — stub it for tests that use
-// useTableState (which calls useSyncExternalStore with a matchMedia listener)
-Object.defineProperty(window, "matchMedia", {
-  writable: true,
-  value: (query: string) => ({
-    matches: false,
-    media: query,
-    onchange: null,
-    addListener: vi.fn(),
-    removeListener: vi.fn(),
-    addEventListener: vi.fn(),
-    removeEventListener: vi.fn(),
-    dispatchEvent: vi.fn(),
-  }),
-})
-
-// jsdom does not implement ResizeObserver — stub it for components that use
-// Radix UI primitives (Sheet, Tooltip, etc.) which call it internally.
-globalThis.ResizeObserver = class {
-  observe = vi.fn()
-  unobserve = vi.fn()
-  disconnect = vi.fn()
-}

package/template/vitest.config.ts

@@ -1,18 +0,0 @@
-import path from "node:path"
-import { defineConfig } from "vitest/config"
-import react from "@vitejs/plugin-react"
-
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    environment: "jsdom",
-    setupFiles: ["./tests/setup.ts"],
-    include: ["**/*.{test,spec}.{ts,tsx}"],
-    exclude: ["node_modules", ".next", "out", "build"],
-  },
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./"),
-    },
-  },
-})