@elabs-ai/components-ui 4.0.0

package/src/templates-screen-states.stories.tsx

@@ -0,0 +1,306 @@
+/**
+ * Screen States — the full state grid the templates omit.
+ *
+ * `design-first` requires that empty, loading, error and first-run states are
+ * designed WITH the happy path, never retrofitted — yet every existing
+ * `Patterns/Templates/*` ships only a populated "Ready" variant. This scenario
+ * fixes that: ONE representative data screen (Customers), rendered across the
+ * complete state grid as separate stories, with the SAME chrome and the real
+ * state primitives wired in:
+ *
+ *   • Ready     — populated Table (the happy path).
+ *   • Loading   — Skeleton rows (never a bare spinner on a data screen).
+ *   • Empty     — StatePanel kind="empty" after a filter returns nothing.
+ *   • Error     — StatePanel kind="error" with a retry action (role="alert").
+ *   • FirstRun  — onboarding empty: illustration slot + one sentence + one CTA.
+ *
+ * Compose-only from @elabs-ai/components-* primitives; semantic tokens only; reads in all
+ * three themes. Verify with globals=theme:<slug>.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Inbox, Plus, RotateCcw, Search, UploadCloud, UserPlus } from "lucide-react";
+import {
+  Badge,
+  Button,
+  Input,
+  PageShell,
+  SectionHeader,
+  Skeleton,
+  StatePanel,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Toaster,
+  toast,
+} from "./index";
+
+type ScreenState = "ready" | "loading" | "empty" | "error" | "first-run";
+
+type CustomerStatus = "active" | "trialing" | "past_due";
+
+interface Customer {
+  id: string;
+  name: string;
+  plan: string;
+  status: CustomerStatus;
+  mrr: string;
+  joined: string;
+}
+
+const STATUS_VARIANT: Record<CustomerStatus, "success" | "secondary" | "destructive"> = {
+  active: "success",
+  trialing: "secondary",
+  past_due: "destructive",
+};
+
+const STATUS_LABEL: Record<CustomerStatus, string> = {
+  active: "Active",
+  trialing: "Trialing",
+  past_due: "Past due",
+};
+
+const CUSTOMERS: Customer[] = [
+  {
+    id: "1",
+    name: "Northwind Traders",
+    plan: "Enterprise",
+    status: "active",
+    mrr: "$4,200",
+    joined: "Jan 2024",
+  },
+  {
+    id: "2",
+    name: "Globex Corp",
+    plan: "Business",
+    status: "active",
+    mrr: "$1,800",
+    joined: "Mar 2024",
+  },
+  { id: "3", name: "Initech", plan: "Business", status: "trialing", mrr: "$0", joined: "Jun 2026" },
+  {
+    id: "4",
+    name: "Hooli",
+    plan: "Enterprise",
+    status: "past_due",
+    mrr: "$6,500",
+    joined: "Sep 2023",
+  },
+  {
+    id: "5",
+    name: "Soylent Inc",
+    plan: "Starter",
+    status: "active",
+    mrr: "$240",
+    joined: "Feb 2025",
+  },
+];
+
+/* -------------------------------------------------------------------------- */
+/*  Chrome shared by every state                                               */
+/* -------------------------------------------------------------------------- */
+
+function Toolbar({ count }: { count: number }) {
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <div className="relative w-full max-w-xs">
+        <Search
+          className="pointer-events-none absolute start-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
+          aria-hidden="true"
+        />
+        <Input
+          type="search"
+          placeholder="Search customers…"
+          aria-label="Search customers"
+          className="ps-8"
+        />
+      </div>
+      <span className="shrink-0 text-meta tabular-nums text-muted-foreground">
+        {count} customers
+      </span>
+    </div>
+  );
+}
+
+function CustomersTable() {
+  return (
+    <div className="overflow-hidden rounded-xl border bg-card">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Customer</TableHead>
+            <TableHead>Plan</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead className="text-end">MRR</TableHead>
+            <TableHead>Joined</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {CUSTOMERS.map((c) => (
+            <TableRow key={c.id}>
+              <TableCell className="font-medium">{c.name}</TableCell>
+              <TableCell className="text-muted-foreground">{c.plan}</TableCell>
+              <TableCell>
+                <Badge variant={STATUS_VARIANT[c.status]}>{STATUS_LABEL[c.status]}</Badge>
+              </TableCell>
+              <TableCell className="text-end tabular-nums">{c.mrr}</TableCell>
+              <TableCell className="text-muted-foreground">{c.joined}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
+
+function LoadingTable() {
+  return (
+    <div className="overflow-hidden rounded-xl border bg-card" aria-busy="true">
+      <div className="border-b px-4 py-3">
+        <Skeleton className="h-4 w-40" />
+      </div>
+      <ul>
+        {Array.from({ length: 5 }).map((_, i) => (
+          <li key={i} className="flex items-center gap-4 px-4 py-3 [&:not(:first-child)]:border-t">
+            <Skeleton className="h-4 flex-1" />
+            <Skeleton className="h-4 w-20" />
+            <Skeleton className="h-5 w-16 rounded-full" />
+            <Skeleton className="h-4 w-14" />
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  The screen — one body per state                                            */
+/* -------------------------------------------------------------------------- */
+
+function CustomersScreen({ state = "ready" }: { state?: ScreenState }) {
+  return (
+    <div className="min-h-dvh bg-background text-foreground">
+      <PageShell
+        header={
+          <SectionHeader
+            eyebrow="Billing"
+            title="Customers"
+            description="Everyone with an active or trialing subscription."
+            actions={
+              state === "first-run" ? undefined : (
+                <Button size="sm" onClick={() => toast.success("New-customer form opened")}>
+                  <Plus className="size-4" aria-hidden="true" />
+                  New customer
+                </Button>
+              )
+            }
+          />
+        }
+      >
+        {(state === "ready" || state === "empty") && (
+          <Toolbar count={state === "ready" ? CUSTOMERS.length : 0} />
+        )}
+
+        {state === "ready" && <CustomersTable />}
+
+        {state === "loading" && <LoadingTable />}
+
+        {state === "error" && (
+          <StatePanel
+            kind="error"
+            title="Couldn't load customers"
+            description="The billing service didn't respond. Your data is safe — this is a display error."
+            actions={
+              <Button variant="outline" size="sm" onClick={() => toast.success("Retrying…")}>
+                <RotateCcw className="size-4" aria-hidden="true" />
+                Try again
+              </Button>
+            }
+          />
+        )}
+
+        {state === "empty" && (
+          <StatePanel
+            kind="empty"
+            icon={<Inbox aria-hidden="true" />}
+            title="No customers match"
+            description="No customers match your current search or filters."
+            actions={
+              <Button variant="outline" size="sm">
+                Clear filters
+              </Button>
+            }
+          />
+        )}
+
+        {state === "first-run" && (
+          <StatePanel
+            kind="empty"
+            icon={<UserPlus aria-hidden="true" />}
+            title="Add your first customer"
+            description="Customers appear here once they start a subscription. Add one manually or import an existing book of business."
+            actions={
+              <>
+                <Button size="sm" onClick={() => toast.success("New-customer form opened")}>
+                  <Plus className="size-4" aria-hidden="true" />
+                  New customer
+                </Button>
+                <Button variant="outline" size="sm">
+                  <UploadCloud className="size-4" aria-hidden="true" />
+                  Import CSV
+                </Button>
+              </>
+            }
+          />
+        )}
+      </PageShell>
+      <Toaster />
+    </div>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Stories — one per state                                                     */
+/* -------------------------------------------------------------------------- */
+
+const meta = {
+  title: "Patterns/Templates/Screen States",
+  component: CustomersScreen,
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          'One representative data screen (Customers) rendered across the FULL state grid — Ready, Loading, Empty, Error, FirstRun — with the same chrome and the real state primitives (Table, Skeleton, StatePanel kind="empty"|"error"). This is the design-first state grid that the Patterns/Templates examples omit. Semantic tokens only; reads in all three themes.',
+      },
+    },
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    state: {
+      control: "inline-radio",
+      options: ["ready", "loading", "empty", "error", "first-run"],
+      description: "Which screen state to render.",
+    },
+  },
+} satisfies Meta<typeof CustomersScreen>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Populated happy path. */
+export const Ready: Story = { args: { state: "ready" } };
+
+/** In-flight load — Skeleton rows, not a bare spinner. */
+export const Loading: Story = { args: { state: "loading" } };
+
+/** A search/filter returned nothing — a real empty state with a way out. */
+export const Empty: Story = { args: { state: "empty" } };
+
+/** Recoverable failure — StatePanel kind="error" (role="alert") + retry. */
+export const Errored: Story = { name: "Error", args: { state: "error" } };
+
+/** Never-used screen — onboarding empty with one primary action. */
+export const FirstRun: Story = { args: { state: "first-run" } };

package/src/templates-settings.stories.tsx

@@ -0,0 +1,245 @@
+/**
+ * Settings template — the canonical full-screen settings composition
+ * (app-shell + Descriptions + Wizard). This story is the single source of
+ * truth: `pnpm gen:templates` derives the consumer template source
+ * (`docs/playbooks/templates/settings.tsx`) from it.
+ * Verify across all three themes with globals=theme:<slug>.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Descriptions,
+  DescriptionsItem,
+  Input,
+  Label,
+  Separator,
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+  Wizard,
+  WizardNav,
+  WizardStep,
+  WizardSteps,
+  type WizardStepMeta,
+} from "./index";
+import { Bell, Home, Shield, User } from "lucide-react";
+
+const WIZARD_STEPS: WizardStepMeta[] = [
+  { id: "profile", title: "Profile", description: "Your details" },
+  { id: "notifications", title: "Notifications", description: "Alert prefs" },
+  { id: "confirm", title: "Confirm", description: "Review & finish" },
+];
+
+const nav = [
+  { id: "profile", label: "Profile", icon: User },
+  { id: "notifications", label: "Notifications", icon: Bell },
+  { id: "security", label: "Security", icon: Shield },
+  { id: "home", label: "Home", icon: Home },
+];
+
+function ProfileView() {
+  return (
+    <div className="flex flex-col gap-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>Your profile</CardTitle>
+          <CardDescription>Visible to other members of your workspace.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Descriptions columns={2} layout="vertical">
+            <DescriptionsItem label="Full name">Alex Johnson</DescriptionsItem>
+            <DescriptionsItem label="Email">alex@example.com</DescriptionsItem>
+            <DescriptionsItem label="Role">Admin</DescriptionsItem>
+            <DescriptionsItem label="Member since">Jan 2024</DescriptionsItem>
+          </Descriptions>
+        </CardContent>
+      </Card>
+      <Separator />
+      <Card>
+        <CardHeader>
+          <CardTitle>Setup wizard</CardTitle>
+          <CardDescription>
+            Complete the steps below to finish configuring your account.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Wizard steps={WIZARD_STEPS} defaultStep={0} className="flex flex-col gap-6">
+            <WizardSteps />
+            <WizardStep step={0}>
+              <div className="flex flex-col gap-4">
+                <div className="flex flex-col gap-1.5">
+                  <Label htmlFor="display-name">Display name</Label>
+                  <Input id="display-name" defaultValue="Alex Johnson" autoComplete="name" />
+                </div>
+                <div className="flex flex-col gap-1.5">
+                  <Label htmlFor="job-title">Job title</Label>
+                  <Input
+                    id="job-title"
+                    placeholder="e.g. Data Engineer"
+                    autoComplete="organization-title"
+                  />
+                </div>
+              </div>
+            </WizardStep>
+            <WizardStep step={1}>
+              <div className="flex flex-col gap-4">
+                <p className="text-body text-muted-foreground">
+                  Choose which notifications you&apos;d like to receive.
+                </p>
+                <div className="flex flex-col gap-2 text-body">
+                  {["Alerts & incidents", "Weekly digests", "Product updates"].map((item) => (
+                    <label key={item} className="flex cursor-pointer items-center gap-2">
+                      <input type="checkbox" defaultChecked className="accent-primary" />
+                      <span>{item}</span>
+                    </label>
+                  ))}
+                </div>
+              </div>
+            </WizardStep>
+            <WizardStep step={2}>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-muted-foreground">
+                  Your account is ready. Review your settings and click Finish.
+                </p>
+                <Descriptions layout="vertical">
+                  <DescriptionsItem label="Display name">Alex Johnson</DescriptionsItem>
+                  <DescriptionsItem label="Notifications">Alerts, Digests</DescriptionsItem>
+                </Descriptions>
+              </div>
+            </WizardStep>
+            <WizardNav finishLabel="Finish setup" />
+          </Wizard>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+function NotificationsView() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Notification preferences</CardTitle>
+        <CardDescription>Control how and when you receive alerts.</CardDescription>
+      </CardHeader>
+      <CardContent className="flex flex-col gap-4 text-body">
+        {[
+          { label: "Alerts & incidents", checked: true },
+          { label: "Weekly digest", checked: true },
+          { label: "Product updates", checked: false },
+          { label: "Marketing emails", checked: false },
+        ].map((item) => (
+          <label key={item.label} className="flex cursor-pointer items-center gap-2">
+            <input type="checkbox" defaultChecked={item.checked} className="accent-primary" />
+            <span>{item.label}</span>
+          </label>
+        ))}
+        <div className="mt-2">
+          <Button size="sm">Save preferences</Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function SecurityView() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Security</CardTitle>
+        <CardDescription>Manage your password and two-factor authentication.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Descriptions layout="vertical">
+          <DescriptionsItem label="Password">Last changed 3 months ago</DescriptionsItem>
+          <DescriptionsItem label="Two-factor auth">Enabled (Authenticator app)</DescriptionsItem>
+          <DescriptionsItem label="Active sessions" numeric>
+            2
+          </DescriptionsItem>
+        </Descriptions>
+        <div className="mt-4 flex gap-2">
+          <Button variant="outline" size="sm">
+            Change password
+          </Button>
+          <Button variant="outline" size="sm">
+            Manage 2FA
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function SettingsTemplate() {
+  const [active, setActive] = useState("profile");
+
+  const views: Record<string, React.ReactNode> = {
+    profile: <ProfileView />,
+    notifications: <NotificationsView />,
+    security: <SecurityView />,
+    home: (
+      <p className="text-body text-muted-foreground">
+        Navigate to a settings section using the sidebar.
+      </p>
+    ),
+  };
+
+  return (
+    <SidebarProvider>
+      <Sidebar collapsible="icon">
+        <SidebarHeader className="px-3 py-2 font-semibold">Settings</SidebarHeader>
+        <SidebarContent>
+          <SidebarGroup>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {nav.map((n) => (
+                  <SidebarMenuItem key={n.id}>
+                    <SidebarMenuButton
+                      isActive={active === n.id}
+                      tooltip={n.label}
+                      onClick={() => setActive(n.id)}
+                    >
+                      <n.icon aria-hidden="true" />
+                      <span>{n.label}</span>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                ))}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        </SidebarContent>
+      </Sidebar>
+      <SidebarInset>
+        <header className="flex h-14 items-center gap-2 border-b px-4">
+          <SidebarTrigger />
+          <h1 className="text-body font-medium capitalize">{active}</h1>
+        </header>
+        <main className="max-w-2xl p-6">{views[active]}</main>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+
+const meta = {
+  title: "Patterns/Templates/Settings",
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+} satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { render: () => <SettingsTemplate /> };