chati-dev 4.3.1 → 4.4.0

package/framework/scaffold/saas-dashboard/README.md

@@ -0,0 +1,58 @@
+# saas-dashboard scaffold preset
+
+A premium SaaS dashboard and app-shell starting point. Where the motion-premium
+presets target animated showcase sites, this preset targets the build-me-a-tool
+category: a data-dense application shell that looks designed, not generated.
+
+## What it ships
+
+29 templates across foundation, primitives, shell, data, interaction, and a
+composed sample page:
+
+- **Foundation**: `app/globals.css` (the full token system, fluid type scale,
+  reduced-motion handling, the `xl` breakpoint override), `lib/brand.ts` (typed
+  tokens), and the single `Container` authority for max-width and padding.
+- **Primitives**: `Button`, `Card`, `Input`, `Badge`, `Spinner`, each with full
+  resting, hover, active, disabled, and focus states.
+- **Shell**: `AppShell`, `Sidebar` (collapsible, keyboard-accessible, responsive
+  drawer), `Topbar` (search trigger, breadcrumb, user menu), `NavItem`,
+  `ThemeToggle`, `Breadcrumb`.
+- **Data**: `DataTable` (typed, sortable, sticky header, selection, empty and
+  loading states), `StatCard` and `StatCardGrid` (KPI with delta semantics and a
+  sparkline), `Chart` (a self-contained SVG area chart, no chart dependency).
+- **Interaction**: `CommandPalette` (Cmd+K, fuzzy filter, keyboard nav, hand
+  rolled, no extra dependency), `Field` and `Form` (labeled inputs, validation
+  states, never placeholder-only labels).
+- **Feedback**: `EmptyState`.
+- **Sample**: `app/dashboard/page.tsx` composes the shell, stat cards, a chart,
+  and a data table to demonstrate the preset.
+
+## Design system
+
+- **Color**: a calibrated dark palette built from a single neutral hue with even
+  perceptual luminance steps, a 6-color data-viz series, and a designed light
+  theme via `[data-theme="light"]` (never `filter: invert`). Every color is a
+  CSS custom property; components never carry a raw hex.
+- **Type**: a 1.25 modular scale with fluid `clamp()` values, role-differentiated
+  line-heights, and optical tracking.
+- **Space**: a 4px base unit tuned for data density.
+- **Motion**: cubic-bezier easing matched to the metaphor, a duration scale, and
+  full reduced-motion support. No linear easing, no `transition: all`.
+
+## Quality contract
+
+This preset is built to clear the QA-Visual rubric
+(`chati.dev/data/qa-rubrics.yaml`) on every dimension: layout, typography, color,
+spacing, interaction, motion, accessibility (WCAG 2.1 AA), and performance
+(animate only `transform` and `opacity`).
+
+## Dependencies
+
+`lucide-react` (icons) and `framer-motion` (micro-interactions). The chart and
+the command palette are hand-rolled, so there is no chart library and no command
+menu dependency.
+
+## Brandable
+
+The accent color (`ACCENT_HEX`, `ACCENT_HOVER_HEX`) is resolved at apply time
+from your brand source. The neutral and semantic scales are the designed system.

package/framework/scaffold/saas-dashboard/app/dashboard/page.tsx.template

@@ -0,0 +1,546 @@
+/**
+ * app/dashboard/page.tsx
+ * SaaS Dashboard Preset -- D_interaction phase (composed sample page)
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A preset with only individual components is hard to evaluate. Teams adopting
+ * a scaffold need to see the components working together in a real layout:
+ * how tokens compose, how the grid breathes, how the type scale creates
+ * hierarchy across sections, and how the motion system feels at dashboard
+ * density.
+ *
+ * This file is the "show your work" page -- the proof that every design
+ * decision in the spec resolves coherently at the page level. It is ALSO
+ * the first thing a new developer opens, so it doubles as the definitive
+ * usage example for every component in the preset.
+ *
+ * LAYOUT ARCHITECTURE
+ * -------------------
+ * Section 1: StatCardGrid -- 4 KPI cards across, auto-fill responsive.
+ * Section 2: 2-column asymmetric grid -- Chart (wider) + secondary
+ *            metric card (narrower). The asymmetry creates visual weight:
+ *            the chart is the primary insight, the secondary card is context.
+ * Section 3: Full-width DataTable with realistic sample columns and
+ *            pagination. Demonstrates sort indicators, status badges, and
+ *            the empty state pattern.
+ *
+ * SPACING RATIONALE
+ * -----------------
+ * Sections are separated by --spacing-section (32px). Within sections,
+ * components are separated by --spacing-card-gap (20px). This two-level
+ * rhythm creates a clear hierarchy: sections are distinct regions,
+ * components within a section are related.
+ *
+ * The page wrapper uses padding-top to account for the sticky topbar
+ * (--spacing-topbar-h = 48px). This is set in AppShell's main scroll area,
+ * not here -- but it is documented here because the visual consequence
+ * (content not hiding behind topbar) is visible at this level.
+ *
+ * DATA
+ * ----
+ * All data is static TypeScript constants defined at the bottom of this
+ * file. No API calls, no SWR/React Query, no suspense boundaries for
+ * the sake of this demo. Replace with your data fetching layer.
+ *
+ * TOKEN USAGE
+ * -----------
+ * All spacing via CSS custom properties. No raw px values in JSX styles.
+ * Colors via semantic token layer (--color-text-*, --color-bg-*, etc.).
+ */
+
+'use client';
+
+import { Container } from '@/components/shell/Container';
+import { StatCard } from '@/components/data/StatCard';
+import { StatCardGrid } from '@/components/data/StatCardGrid';
+import { Chart } from '@/components/data/Chart';
+import { DataTable } from '@/components/data/DataTable';
+import { EmptyState } from '@/components/feedback/EmptyState';
+import { Badge } from '@/components/primitives/Badge';
+import { Button } from '@/components/primitives/Button';
+import {
+  DollarSign,
+  Users,
+  TrendingUp,
+  Activity,
+  FileText,
+  Plus,
+} from 'lucide-react';
+
+// ---------------------------------------------------------------------------
+// Mock data
+// ---------------------------------------------------------------------------
+
+const revenueSparkline = [12, 18, 14, 22, 19, 27, 24, 31, 28, 35, 33, 42];
+const userSparkline = [340, 382, 360, 410, 395, 440, 420, 475, 460, 510, 490, 540];
+const conversionSparkline = [3.1, 3.4, 3.2, 3.7, 3.5, 3.9, 3.8, 4.1, 3.9, 4.3, 4.2, 4.6];
+const mrrSparkline = [8200, 8600, 8400, 9100, 8900, 9600, 9400, 10200, 9900, 10800, 10500, 11200];
+
+const areaChartData = [
+  { month: 'Jan', revenue: 12400, users: 340 },
+  { month: 'Feb', revenue: 15200, users: 382 },
+  { month: 'Mar', revenue: 13800, users: 360 },
+  { month: 'Apr', revenue: 18100, users: 410 },
+  { month: 'May', revenue: 16900, users: 395 },
+  { month: 'Jun', revenue: 21400, users: 440 },
+  { month: 'Jul', revenue: 19800, users: 420 },
+  { month: 'Aug', revenue: 24200, users: 475 },
+  { month: 'Sep', revenue: 22100, users: 460 },
+  { month: 'Oct', revenue: 27800, users: 510 },
+  { month: 'Nov', revenue: 25400, users: 490 },
+  { month: 'Dec', revenue: 31600, users: 540 },
+];
+
+const chartSeries = [
+  { key: 'revenue', label: 'Revenue', color: 'var(--color-viz-1)' },
+  { key: 'users', label: 'Active Users', color: 'var(--color-viz-2)' },
+];
+
+export type TransactionRow = {
+  id: string;
+  customer: string;
+  email: string;
+  amount: number;
+  status: 'completed' | 'pending' | 'failed';
+  date: string;
+  plan: string;
+};
+
+const transactions: TransactionRow[] = [
+  { id: 'TXN-001', customer: 'Aria Nakamura', email: 'aria@synth.io', amount: 299, status: 'completed', date: '2026-06-07', plan: 'Pro' },
+  { id: 'TXN-002', customer: 'Luca Ferreira', email: 'luca@vela.co', amount: 99, status: 'completed', date: '2026-06-07', plan: 'Starter' },
+  { id: 'TXN-003', customer: 'Mira Osei', email: 'mira@datavault.com', amount: 899, status: 'pending', date: '2026-06-06', plan: 'Enterprise' },
+  { id: 'TXN-004', customer: 'Dev Patel', email: 'dev@cortex.ai', amount: 299, status: 'completed', date: '2026-06-06', plan: 'Pro' },
+  { id: 'TXN-005', customer: 'Soren Lindqvist', email: 'soren@nordic.se', amount: 99, status: 'failed', date: '2026-06-05', plan: 'Starter' },
+  { id: 'TXN-006', customer: 'Yuki Tanaka', email: 'yuki@flux.jp', amount: 299, status: 'completed', date: '2026-06-05', plan: 'Pro' },
+  { id: 'TXN-007', customer: 'Chiara Russo', email: 'chiara@bloom.it', amount: 899, status: 'completed', date: '2026-06-04', plan: 'Enterprise' },
+  { id: 'TXN-008', customer: 'Omar Hassan', email: 'omar@pulse.ae', amount: 99, status: 'pending', date: '2026-06-04', plan: 'Starter' },
+];
+
+const tableColumns = [
+  {
+    key: 'customer' as const,
+    header: 'Customer',
+    render: (row: TransactionRow) => (
+      <div>
+        <div
+          style={{
+            fontSize: 'var(--type-small)',
+            fontWeight: 500,
+            color: 'var(--color-text-primary)',
+          }}
+        >
+          {row.customer}
+        </div>
+        <div
+          style={{
+            fontSize: 'var(--type-caption)',
+            color: 'var(--color-text-muted)',
+            marginTop: '2px',
+          }}
+        >
+          {row.email}
+        </div>
+      </div>
+    ),
+  },
+  {
+    key: 'plan' as const,
+    header: 'Plan',
+    render: (row: TransactionRow) => (
+      <Badge
+        variant={
+          row.plan === 'Enterprise'
+            ? 'accent'
+            : row.plan === 'Pro'
+            ? 'info'
+            : 'default'
+        }
+        size="sm"
+      >
+        {row.plan}
+      </Badge>
+    ),
+  },
+  {
+    key: 'amount' as const,
+    header: 'Amount',
+    render: (row: TransactionRow) => (
+      <span
+        style={{
+          fontFamily: 'var(--font-mono)',
+          fontSize: 'var(--type-mono)',
+          color: 'var(--color-text-primary)',
+          fontWeight: 500,
+        }}
+      >
+        ${row.amount.toLocaleString()}
+      </span>
+    ),
+  },
+  {
+    key: 'status' as const,
+    header: 'Status',
+    render: (row: TransactionRow) => (
+      <Badge
+        variant={
+          row.status === 'completed'
+            ? 'success'
+            : row.status === 'pending'
+            ? 'warning'
+            : 'danger'
+        }
+        dot
+        size="sm"
+      >
+        {row.status.charAt(0).toUpperCase() + row.status.slice(1)}
+      </Badge>
+    ),
+  },
+  {
+    key: 'date' as const,
+    header: 'Date',
+    render: (row: TransactionRow) => (
+      <span
+        style={{
+          fontSize: 'var(--type-caption)',
+          color: 'var(--color-text-muted)',
+          fontFamily: 'var(--font-mono)',
+        }}
+      >
+        {row.date}
+      </span>
+    ),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
+export default function DashboardPage() {
+  return (
+    <Container>
+      {/* Page header */}
+      <header
+        style={{
+          paddingTop: 'var(--spacing-section)',
+          paddingBottom: 'var(--spacing-section)',
+          borderBottom: '1px solid var(--color-border-default)',
+          marginBottom: 'var(--spacing-section)',
+        }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'flex-start',
+            justifyContent: 'space-between',
+            gap: 'var(--spacing-card-gap)',
+            flexWrap: 'wrap',
+          }}
+        >
+          <div>
+            <h1
+              style={{
+                fontSize: 'var(--type-h1)',
+                lineHeight: 'var(--type-h1-lh)',
+                letterSpacing: 'var(--type-h1-ls)',
+                fontWeight: 700,
+                color: 'var(--color-text-primary)',
+                margin: 0,
+              }}
+            >
+              Dashboard
+            </h1>
+            <p
+              style={{
+                fontSize: 'var(--type-small)',
+                color: 'var(--color-text-secondary)',
+                margin: 'var(--space-2) 0 0',
+              }}
+            >
+              Welcome back. Here is what is happening with your product.
+            </p>
+          </div>
+
+          {/* Header actions */}
+          <div style={{ display: 'flex', gap: 'var(--space-3)', alignItems: 'center' }}>
+            <Button variant="secondary" iconLeft={<FileText size={16} aria-hidden="true" />}>
+              Export report
+            </Button>
+            <Button variant="primary" iconLeft={<Plus size={16} aria-hidden="true" />}>
+              New transaction
+            </Button>
+          </div>
+        </div>
+      </header>
+
+      {/* Section 1: KPI stat cards */}
+      <section aria-label="Key performance indicators">
+        <StatCardGrid>
+          <StatCard
+            label="Total Revenue"
+            value="$142,840"
+            delta="+11.2%"
+            previousValue="$128,400"
+            unit="USD"
+            icon={<DollarSign size={20} aria-hidden="true" />}
+            trend="up"
+            sparklineData={revenueSparkline}
+          />
+          <StatCard
+            label="Active Users"
+            value="5,420"
+            delta="+10.8%"
+            previousValue="4,890"
+            unit="users"
+            icon={<Users size={20} aria-hidden="true" />}
+            trend="up"
+            sparklineData={userSparkline}
+          />
+          <StatCard
+            label="Conversion Rate"
+            value="4.6%"
+            delta="+0.5pp"
+            previousValue="4.1%"
+            unit="percent"
+            icon={<TrendingUp size={20} aria-hidden="true" />}
+            trend="up"
+            sparklineData={conversionSparkline}
+          />
+          <StatCard
+            label="Monthly Recurring Revenue"
+            value="$11,200"
+            delta="+6.7%"
+            previousValue="$10,500"
+            unit="MRR"
+            icon={<Activity size={20} aria-hidden="true" />}
+            trend="up"
+            sparklineData={mrrSparkline}
+          />
+        </StatCardGrid>
+      </section>
+
+      {/* Section 2: Chart + secondary metric (asymmetric 2-col grid) */}
+      <section
+        aria-label="Revenue and users trend"
+        style={{ marginTop: 'var(--spacing-section)' }}
+      >
+        <div
+          style={{
+            display: 'grid',
+            gridTemplateColumns: 'repeat(auto-fit, minmax(min(100%, 340px), 1fr))',
+            gap: 'var(--spacing-card-gap)',
+            alignItems: 'start',
+          }}
+        >
+          {/* Area chart -- primary insight, wider column */}
+          <div
+            style={{
+              gridColumn: 'span 2',
+              // On wide viewports this naturally spans 2 of 3 grid columns
+              // On narrow viewports (single column) it fills full width
+            }}
+          >
+            <Chart
+              data={areaChartData}
+              series={chartSeries}
+              xKey="month"
+              ariaLabel="Revenue and subscriptions over the last 12 months"
+              formatX={(v: unknown) => String(v)}
+              formatY={(v: number) =>
+                v > 999 ? `$${(v / 1000).toFixed(0)}k` : String(v)
+              }
+              height={280}
+            />
+          </div>
+
+          {/* Secondary metric card -- narrower, contextual */}
+          <div
+            style={{
+              backgroundColor: 'var(--color-bg-raised)',
+              border: '1px solid var(--color-border-default)',
+              borderRadius: 'var(--radius-lg)',
+              padding: 'var(--spacing-card-pad)',
+              boxShadow: 'var(--shadow-1)',
+            }}
+          >
+            <h2
+              style={{
+                fontSize: 'var(--type-h4)',
+                lineHeight: 'var(--type-h4-lh)',
+                letterSpacing: 'var(--type-h4-ls)',
+                fontWeight: 600,
+                color: 'var(--color-text-primary)',
+                margin: '0 0 var(--space-5)',
+              }}
+            >
+              Plan breakdown
+            </h2>
+
+            <ul
+              style={{
+                listStyle: 'none',
+                margin: 0,
+                padding: 0,
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--space-4)',
+              }}
+            >
+              {[
+                { label: 'Enterprise', count: 12, pct: 18, color: 'var(--color-viz-1)' },
+                { label: 'Pro', count: 38, pct: 56, color: 'var(--color-viz-2)' },
+                { label: 'Starter', count: 18, pct: 26, color: 'var(--color-viz-3)' },
+              ].map((plan) => (
+                <li key={plan.label}>
+                  <div
+                    style={{
+                      display: 'flex',
+                      justifyContent: 'space-between',
+                      marginBottom: 'var(--space-1)',
+                    }}
+                  >
+                    <span
+                      style={{
+                        fontSize: 'var(--type-small)',
+                        color: 'var(--color-text-secondary)',
+                      }}
+                    >
+                      {plan.label}
+                    </span>
+                    <span
+                      style={{
+                        fontSize: 'var(--type-caption)',
+                        fontFamily: 'var(--font-mono)',
+                        color: 'var(--color-text-muted)',
+                      }}
+                    >
+                      {plan.count} ({plan.pct}%)
+                    </span>
+                  </div>
+                  {/* Progress bar -- animates only transform, not width */}
+                  <div
+                    style={{
+                      height: '6px',
+                      borderRadius: 'var(--radius-pill)',
+                      backgroundColor: 'var(--color-bg-sunken)',
+                      overflow: 'hidden',
+                    }}
+                    role="presentation"
+                    aria-hidden="true"
+                  >
+                    <div
+                      style={{
+                        height: '100%',
+                        width: '100%',
+                        borderRadius: 'var(--radius-pill)',
+                        backgroundColor: plan.color,
+                        transformOrigin: 'left center',
+                        transform: `scaleX(${plan.pct / 100})`,
+                        transition: `transform var(--duration-layout) var(--ease-out)`,
+                      }}
+                    />
+                  </div>
+                </li>
+              ))}
+            </ul>
+
+            <div
+              style={{
+                marginTop: 'var(--space-6)',
+                paddingTop: 'var(--space-5)',
+                borderTop: '1px solid var(--color-border-default)',
+                display: 'flex',
+                justifyContent: 'space-between',
+                alignItems: 'center',
+              }}
+            >
+              <span
+                style={{
+                  fontSize: 'var(--type-caption)',
+                  color: 'var(--color-text-muted)',
+                }}
+              >
+                Total customers
+              </span>
+              <span
+                style={{
+                  fontSize: 'var(--type-h3)',
+                  lineHeight: 'var(--type-h3-lh)',
+                  fontWeight: 700,
+                  color: 'var(--color-text-primary)',
+                  fontFamily: 'var(--font-mono)',
+                }}
+              >
+                68
+              </span>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      {/* Section 3: DataTable */}
+      <section
+        aria-label="Recent transactions"
+        style={{
+          marginTop: 'var(--spacing-section)',
+          paddingBottom: 'var(--spacing-section)',
+        }}
+      >
+        <div
+          style={{
+            marginBottom: 'var(--space-5)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 'var(--space-4)',
+          }}
+        >
+          <div>
+            <h2
+              style={{
+                fontSize: 'var(--type-h3)',
+                lineHeight: 'var(--type-h3-lh)',
+                letterSpacing: 'var(--type-h3-ls)',
+                fontWeight: 600,
+                color: 'var(--color-text-primary)',
+                margin: 0,
+              }}
+            >
+              Recent transactions
+            </h2>
+            <p
+              style={{
+                fontSize: 'var(--type-caption)',
+                color: 'var(--color-text-muted)',
+                margin: 'var(--space-1) 0 0',
+              }}
+            >
+              {transactions.length} transactions this week
+            </p>
+          </div>
+        </div>
+
+        <DataTable
+          caption="Recent transactions"
+          columns={tableColumns}
+          data={transactions}
+          emptyState={
+            <EmptyState
+              icon={<FileText size={28} aria-hidden="true" />}
+              title="No transactions yet"
+              description="When customers complete purchases, they will appear here."
+              primaryAction={{
+                label: 'Create test transaction',
+                onClick: () => {},
+                icon: <Plus size={16} aria-hidden="true" />,
+              }}
+            />
+          }
+        />
+      </section>
+    </Container>
+  );
+}