@slipstream-ui/core 0.3.0 → 0.4.0

package/dist/manifests/timeline.manifest.json

@@ -0,0 +1,69 @@
+{
+  "id": "timeline",
+  "name": "Timeline",
+  "tier": "molecule",
+  "description": "Vertical chronology for experience, activity and audit trails, built on an ordered list.",
+  "designIntent": "Chronologies communicate order. Rendering them as an ordered list keeps the sequence structural for assistive tech, while the connector rule and dots provide the visual rhythm.",
+  "props": [
+    {
+      "name": "items",
+      "type": "{ title: string; period?: string; description?: string; icon?: ReactNode; muted?: boolean }[]",
+      "required": true,
+      "description": "Ordered timeline entries."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Experience",
+      "code": "<Timeline\n  items={[\n    { title: 'Senior Engineer', period: '2023 — Present', description: 'Platform team' },\n    { title: 'Engineer', period: '2020 — 2023' },\n  ]}\n/>",
+      "description": "Period label, title and supporting line per entry."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't reverse the DOM order for newest-first",
+      "explanation": "Reverse the array instead so reading order matches visual order.",
+      "example": "// Avoid: flex-col-reverse\n// Prefer: items={items.slice().reverse()}"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Sequence",
+      "implementation": "Ordered list semantics",
+      "userRequirements": "Keep entries in chronological order in the array"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Periods",
+      "guidelines": [
+        "Use a consistent format",
+        "State Present for ongoing"
+      ],
+      "goodExamples": [
+        "2023 — Present",
+        "Jan 2024"
+      ],
+      "badExamples": [
+        "Some time ago"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Card",
+      "relationship": "Often embedded in profile/about cards",
+      "example": "<Card><CardContent><Timeline items={roles} /></CardContent></Card>"
+    }
+  ],
+  "relatedComponents": [
+    "List",
+    "Card",
+    "Separator"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "timeline",
+  "exportName": "Timeline"
+}

package/dist/manifests/toast.manifest.json

@@ -2,47 +2,99 @@
   "id": "toast",
   "name": "Toast",
   "tier": "molecule",
-  "description": "Accessible app-level notifications announced through a polite live region, with auto-dismiss, stacking and optional actions",
-  "designIntent": "Applications need lightweight feedback that does not steal focus. Toasts render into a labelled polite live region so screen readers announce them, stack newest-first, auto-dismiss on a timer, and support one optional action (typically undo).",
+  "description": "Accessible notifications: tree-scoped provider/hook plus an imperative toast() API rendered by <Toaster />.",
+  "designIntent": "Toasts announce status changes without stealing focus. The provider/useToast pair covers tree-scoped usage; the module-level toast() + <Toaster /> covers event handlers and data layers where threading a hook is impossible (e.g. 1000+ call sites). A polite live region and auto-dismiss keep the queue quiet.",
   "props": [
     {
       "name": "title",
       "type": "string",
       "required": true,
-      "description": "Short heading announced with the toast"
+      "description": "Toast heading.",
+      "examples": [
+        "Saved",
+        "Upload failed"
+      ]
     },
     {
       "name": "description",
       "type": "string",
       "required": false,
-      "description": "Optional supporting detail"
+      "description": "Supporting line under the title."
+    },
+    {
+      "name": "variant",
+      "type": "'default' | 'success' | 'error' | 'warning' | 'info'",
+      "required": false,
+      "defaultValue": "default",
+      "description": "Status accent (dot + optional rich tint).",
+      "enum": [
+        "default",
+        "success",
+        "error",
+        "warning",
+        "info"
+      ],
+      "examples": [
+        "success",
+        "error"
+      ]
     },
     {
       "name": "action",
       "type": "{ label: string; onClick: () => void }",
       "required": false,
-      "description": "Optional inline action; invoking it dismisses the toast"
+      "description": "Single inline action; dismisses the toast after running."
     },
     {
       "name": "duration",
       "type": "number",
-      "defaultValue": 5000,
       "required": false,
-      "description": "Auto-dismiss delay in ms; 0 keeps the toast until dismissed",
-      "enum": ["0", "5000"],
-      "examples": [0, 3000, 5000]
+      "defaultValue": "5000",
+      "description": "Auto-dismiss delay in ms; 0 keeps the toast until dismissed."
+    },
+    {
+      "name": "position",
+      "type": "'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'",
+      "required": false,
+      "defaultValue": "bottom-right",
+      "description": "Toaster placement (Toaster component).",
+      "enum": [
+        "top-left",
+        "top-center",
+        "top-right",
+        "bottom-left",
+        "bottom-center",
+        "bottom-right"
+      ],
+      "examples": [
+        "top-right"
+      ]
+    },
+    {
+      "name": "richColors",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Tint the toast surface with its status color (Toaster component)."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Notifications",
+      "description": "Accessible name of the live region (Toaster component)."
     }
   ],
   "examples": [
     {
-      "title": "Basic toast with useToast",
-      "code": "'use client';\n\nimport { ToastProvider, useToast } from '@/components/slipstream/toast';\n\nfunction SaveButton() {\n  const { toast } = useToast();\n  return (\n    <button onClick={() => toast({ title: 'Saved', description: 'Your changes are live.' })}>\n      Save\n    </button>\n  );\n}\n\nexport function App() {\n  return (\n    <ToastProvider>\n      <SaveButton />\n    </ToastProvider>\n  );\n}",
-      "description": "Wrap your app in ToastProvider once; call toast() anywhere below it."
+      "title": "Imperative API",
+      "code": "import { Toaster, toast } from '@slipstream-ui/core';\n\n<Toaster position=\"bottom-right\" richColors />\n\ntoast.success('Saved', 'Your changes are live');\ntoast.error('Upload failed', 'Check your connection');\ntoast({ title: 'Heads up', duration: 0 });",
+      "description": "Fire from event handlers or data layers — no hook needed."
     },
     {
-      "title": "Undo action",
-      "code": "toast({\n  title: 'License revoked',\n  action: { label: 'Undo', onClick: restore },\n  duration: 0,\n});",
-      "description": "duration: 0 keeps the toast until the user acts or dismisses it."
+      "title": "Tree-scoped provider",
+      "code": "<ToastProvider>\n  <App />\n</ToastProvider>;\n\nconst { toast, dismiss } = useToast();\ntoast({ title: 'Saved' });",
+      "description": "Existing provider/hook pair for component-scoped usage."
     }
   ],
   "antiPatterns": [
@@ -53,29 +105,53 @@
   ],
   "accessibility": [
     {
-      "feature": "Screen reader announcements",
-      "implementation": "Each toast renders inside role=status (implicit aria-live=polite) within a labelled list container."
+      "feature": "Polite live region",
+      "implementation": "Each toast renders role=status inside a labelled list; announcements never steal focus",
+      "userRequirements": "Keep messages short and actionable"
     },
     {
-      "feature": "Keyboard dismiss",
-      "implementation": "Toast content is regular DOM; buttons inside toasts are reachable and activatable with the keyboard."
+      "feature": "Dismiss control",
+      "implementation": "Every toast has a labelled dismiss button (Dismiss <title>)",
+      "userRequirements": "Don't remove the dismiss button"
+    },
+    {
+      "feature": "Auto-dismiss timing",
+      "implementation": "5s default; duration 0 keeps sticky toasts",
+      "userRequirements": "Use duration 0 for errors that need a decision"
     }
   ],
   "contentGuidelines": [
     {
       "contentType": "toast title",
-      "guidelines": ["State what happened in past tense", "Keep under ~60 characters"],
-      "goodExamples": ["Saved", "License revoked"],
-      "badExamples": ["Oops!"]
+      "guidelines": [
+        "State what happened in past tense",
+        "Keep under ~60 characters"
+      ],
+      "goodExamples": [
+        "Saved",
+        "License revoked"
+      ],
+      "badExamples": [
+        "Oops!"
+      ]
     }
   ],
   "compositionRules": [
     {
-      "component": "Confirmation",
-      "relationship": "Use Confirmation for destructive actions before they happen; use Toast to report the result after."
+      "component": "Toaster",
+      "relationship": "Mount once near the app root next to your router; keep it outside transforms so fixed positioning is not affected",
+      "example": "<App><Toaster /></App>"
+    },
+    {
+      "component": "ToastProvider",
+      "relationship": "Use the provider/hook pair when the call site is inside the React tree",
+      "example": "<ToastProvider><App /></ToastProvider>"
     }
   ],
-  "relatedComponents": ["Confirmation", "Button"],
+  "relatedComponents": [
+    "Confirmation",
+    "Button"
+  ],
   "package": "@slipstream-ui/core",
   "importPath": "@slipstream-ui/core",
   "version": "0.0.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slipstream-ui/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/michaelmcshinsky/slipstream-ui.git",

package/src/components/app-shell/AppShell.test.tsx

@@ -0,0 +1,100 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { AppShell, Sidebar, type SidebarSection } from './AppShell';
+
+const sections: SidebarSection[] = [
+  {
+    title: 'Workspace',
+    items: [
+      { href: '/dashboard', label: 'Dashboard' },
+      { href: '/classes', label: 'Classes', badge: '4' },
+    ],
+  },
+  {
+    items: [{ href: '/settings', label: 'Settings' }],
+  },
+];
+
+describe('Sidebar', () => {
+  it('renders sections, headings and marks the active route', () => {
+    render(<Sidebar sections={sections} activeHref="/classes" />);
+    expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument();
+    expect(screen.getByText('Workspace')).toBeInTheDocument();
+    const active = screen.getByRole('link', { name: /Classes/ });
+    expect(active).toHaveAttribute('aria-current', 'page');
+    expect(screen.getByRole('link', { name: 'Dashboard' })).not.toHaveAttribute('aria-current');
+    expect(screen.getByText('4')).toBeInTheDocument();
+  });
+
+  it('uses a custom router link component', () => {
+    function RouterLink({ href, children, ...props }: React.ComponentProps<'a'>) {
+      return (
+        <a data-router href={href} {...props}>
+          {children}
+        </a>
+      );
+    }
+    render(<Sidebar sections={sections} linkComponent={RouterLink} />);
+    expect(screen.getByRole('link', { name: 'Dashboard' })).toHaveAttribute('data-router');
+  });
+
+  it('honours an explicit active flag', () => {
+    render(
+      <Sidebar
+        sections={[{ items: [{ href: '/x', label: 'X', active: true }] }]}
+        activeHref="/elsewhere"
+      />
+    );
+    expect(screen.getByRole('link', { name: 'X' })).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Sidebar sections={sections} activeHref="/dashboard" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe('AppShell', () => {
+  it('renders the rail, sticky header and main content', () => {
+    render(
+      <AppShell sidebar={<Sidebar sections={sections} />} header={<span>Top bar</span>}>
+        <p>Page body</p>
+      </AppShell>
+    );
+    expect(screen.getByText('Page body')).toBeInTheDocument();
+    expect(screen.getAllByRole('link', { name: 'Dashboard' }).length).toBeGreaterThan(0);
+    expect(screen.getByText('Top bar')).toBeInTheDocument();
+  });
+
+  it('opens the sidebar in a drawer on mobile', async () => {
+    const user = userEvent.setup();
+    render(
+      <AppShell sidebar={<Sidebar sections={sections} />}>
+        <p>Body</p>
+      </AppShell>
+    );
+    await user.click(screen.getByRole('button', { name: 'Open navigation' }));
+    expect(screen.getByRole('dialog', { name: 'Navigation' })).toBeInTheDocument();
+  });
+
+  it('hides the built-in menu button when requested', () => {
+    render(
+      <AppShell sidebar={<Sidebar sections={sections} />} hideMobileMenu>
+        <p>Body</p>
+      </AppShell>
+    );
+    expect(screen.queryByRole('button', { name: 'Open navigation' })).not.toBeInTheDocument();
+  });
+
+  it('can render without a sidebar', () => {
+    render(
+      <AppShell header={<span>Only header</span>}>
+        <p>Body</p>
+      </AppShell>
+    );
+    expect(screen.queryByRole('button', { name: 'Open navigation' })).not.toBeInTheDocument();
+    expect(screen.getByText('Only header')).toBeInTheDocument();
+  });
+});

package/src/components/app-shell/AppShell.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+import { Drawer } from '../drawer/Drawer';
+
+export type SidebarItem = {
+  href: string;
+  label: string;
+  icon?: React.ReactNode;
+  /** Trailing slot — count, status dot, shortcut. */
+  badge?: React.ReactNode;
+  /** Force the active state (otherwise activeHref is compared). */
+  active?: boolean;
+};
+
+export type SidebarSection = {
+  title?: string;
+  items: SidebarItem[];
+};
+
+export type SidebarProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  sections: SidebarSection[];
+  /** Brand/mark rendered at the top. */
+  heading?: React.ReactNode;
+  /** Rendered at the bottom (user menu, upgrade CTA). */
+  footer?: React.ReactNode;
+  /** Current route — items with a matching href get aria-current="page". */
+  activeHref?: string;
+  /** Custom link element for routers (react-router `Link`, Next `Link`). */
+  linkComponent?: React.ElementType;
+  /** Accessible name of the nav landmark. Default 'Primary'. */
+  label?: string;
+};
+
+/**
+ * Sectioned navigation rail. Purely presentational: you pass the active
+ * route and a router link component, so it stays stateless and works with
+ * any routing library.
+ */
+export function Sidebar({
+  sections,
+  heading,
+  footer,
+  activeHref,
+  linkComponent,
+  label = 'Primary',
+  className,
+  ...props
+}: SidebarProps) {
+  const Link = linkComponent ?? 'a';
+
+  return (
+    <div className={cn('flex h-full min-h-0 flex-col gap-6 p-4', className)} {...props}>
+      {heading && <div className="px-2">{heading}</div>}
+      <nav aria-label={label} className="flex min-h-0 flex-1 flex-col gap-5 overflow-y-auto">
+        {sections.map((section, index) => (
+          <div key={section.title ?? `section-${index}`}>
+            {section.title && (
+              <p className="mb-1.5 px-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                {section.title}
+              </p>
+            )}
+            <ul className="space-y-0.5">
+              {section.items.map((item) => {
+                const active = item.active ?? (activeHref !== undefined && item.href === activeHref);
+                return (
+                  <li key={item.href}>
+                    <Link
+                      href={item.href}
+                      aria-current={active ? 'page' : undefined}
+                      className={cn(
+                        'flex items-center gap-2.5 rounded-md px-2.5 py-2 text-sm transition-colors',
+                        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                        active
+                          ? 'bg-primary/10 font-medium text-primary'
+                          : 'text-muted-foreground hover:bg-accent hover:text-accent-foreground'
+                      )}
+                    >
+                      {item.icon && <span className="shrink-0 [&_svg]:size-4">{item.icon}</span>}
+                      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+                      {item.badge && <span className="shrink-0 text-xs">{item.badge}</span>}
+                    </Link>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer && <div className="border-t border-border pt-4">{footer}</div>}
+    </div>
+  );
+}
+
+export type AppShellProps = React.HTMLAttributes<HTMLDivElement> & {
+  /** Desktop rail; also rendered inside a mobile drawer. */
+  sidebar?: React.ReactNode;
+  /** Sticky top bar content. */
+  header?: React.ReactNode;
+  /** Hide the built-in mobile menu button (e.g. when the header owns one). */
+  hideMobileMenu?: boolean;
+  /** Tailwind width class for the desktop rail. Default 'w-64'. */
+  sidebarWidth?: string;
+};
+
+/**
+ * Application frame: fixed-height sidebar, sticky header, scrolling main.
+ * On small screens the sidebar becomes a left Drawer opened by a burger
+ * button, so pages never need their own responsive nav wiring.
+ */
+export function AppShell({
+  sidebar,
+  header,
+  hideMobileMenu = false,
+  sidebarWidth = 'w-64',
+  className,
+  children,
+  ...props
+}: AppShellProps) {
+  const [mobileOpen, setMobileOpen] = React.useState(false);
+
+  return (
+    <div className={cn('flex min-h-screen bg-background text-foreground', className)} {...props}>
+      {sidebar && (
+        <aside className={cn('hidden shrink-0 border-r border-border md:block', sidebarWidth)}>
+          {sidebar}
+        </aside>
+      )}
+      <div className="flex min-w-0 flex-1 flex-col">
+        {(header || (sidebar && !hideMobileMenu)) && (
+          <header className="sticky top-0 z-30 flex h-14 items-center gap-3 border-b border-border bg-background/80 px-4 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+            {sidebar && !hideMobileMenu && (
+              <button
+                type="button"
+                onClick={() => setMobileOpen(true)}
+                aria-label="Open navigation"
+                className="rounded-md border border-border p-2 text-muted-foreground hover:bg-muted md:hidden"
+              >
+                <span aria-hidden="true">☰</span>
+              </button>
+            )}
+            <div className="min-w-0 flex-1">{header}</div>
+          </header>
+        )}
+        <main className="min-w-0 flex-1">{children}</main>
+      </div>
+      {sidebar && (
+        <Drawer
+          open={mobileOpen}
+          onOpenChange={setMobileOpen}
+          title="Navigation"
+          side="left"
+          size="sm"
+          animate
+        >
+          {sidebar}
+        </Drawer>
+      )}
+    </div>
+  );
+}

package/src/components/app-shell/index.ts

@@ -0,0 +1 @@
+export * from './AppShell';

package/src/components/auth-layout/AuthLayout.test.tsx

@@ -0,0 +1,34 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { AuthLayout } from './AuthLayout';
+
+describe('AuthLayout', () => {
+  it('renders brand, heading, description and footer', () => {
+    render(
+      <AuthLayout
+        title="Sign in"
+        description="Welcome back."
+        brand={<span>Acme</span>}
+        footer={<a href="/signup">Create account</a>}
+      >
+        <form aria-label="Sign in form" />
+      </AuthLayout>
+    );
+    expect(screen.getByText('Acme')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Sign in' })).toBeInTheDocument();
+    expect(screen.getByText('Welcome back.')).toBeInTheDocument();
+    expect(screen.getByRole('form', { name: 'Sign in form' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Create account' })).toBeInTheDocument();
+  });
+
+  it('supports size presets', () => {
+    const { container } = render(<AuthLayout size="lg" title="Reset"><span /></AuthLayout>);
+    expect(container.querySelector('.max-w-lg')).not.toBeNull();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<AuthLayout title="Sign up"><input aria-label="Email" /></AuthLayout>);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/auth-layout/AuthLayout.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+
+export type AuthLayoutProps = React.HTMLAttributes<HTMLDivElement> & {
+  title: string;
+  description?: string;
+  /** Brand/mark above the card. */
+  brand?: React.ReactNode;
+  /** Links or legal copy under the card. */
+  footer?: React.ReactNode;
+  /** Rendered inside the card under the heading. */
+  children?: React.ReactNode;
+  /** Card width preset (default 'md'). */
+  size?: 'sm' | 'md' | 'lg';
+};
+
+const sizeClasses: Record<NonNullable<AuthLayoutProps['size']>, string> = {
+  sm: 'max-w-sm',
+  md: 'max-w-md',
+  lg: 'max-w-lg',
+};
+
+/**
+ * Centered auth surface: brand mark, title/description, the form card and a
+ * footer slot. Keeps sign-in, sign-up, reset and verify screens visually
+ * identical without each page re-deriving the layout.
+ */
+export const AuthLayout = React.forwardRef<HTMLDivElement, AuthLayoutProps>(function AuthLayout(
+  { title, description, brand, footer, children, size = 'md', className, ...props },
+  ref
+) {
+  return (
+    <div
+      ref={ref}
+      className={cn('flex min-h-screen flex-col items-center justify-center bg-muted/30 px-4 py-12', className)}
+      {...props}
+    >
+      {brand && <div className="mb-6">{brand}</div>}
+      <div className={cn('w-full rounded-xl border border-border bg-card p-6 shadow-sm sm:p-8', sizeClasses[size])}>
+        <h1 className="text-xl font-semibold tracking-tight">{title}</h1>
+        {description && <p className="mt-1 text-sm text-muted-foreground">{description}</p>}
+        <div className="mt-6">{children}</div>
+      </div>
+      {footer && <div className="mt-6 text-center text-sm text-muted-foreground">{footer}</div>}
+    </div>
+  );
+});

package/src/components/auth-layout/index.ts

@@ -0,0 +1 @@
+export * from './AuthLayout';