@setsquare/ui 0.1.0

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@setsquare/ui",
+  "version": "0.1.0",
+  "description": "React Aria components, design tokens, a dashboard shell and a site shell, with a switch between WCAG 2.2 AA and AAA sizing, spacing and contrast.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Worktree-Amigos/setsquare-ui#readme",
+  "bugs": {
+    "url": "https://github.com/Worktree-Amigos/setsquare-ui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Worktree-Amigos/setsquare-ui.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./lint": {
+      "types": "./dist/lint/index.d.ts",
+      "default": "./dist/lint/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./styles.css": "./dist/styles/styles.css",
+    "./theme.css": "./dist/styles/theme.css",
+    "./tokens.css": "./dist/styles/tokens.css",
+    "./tokens.json": "./dist/tokens.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "react",
+    "react-aria",
+    "components",
+    "design-system",
+    "tailwindcss",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "nextjs"
+  ],
+  "peerDependencies": {
+    "@internationalized/date": "^3.12.4",
+    "react": ">=18.3.0",
+    "react-aria-components": "^1.21.1",
+    "react-dom": ">=18.3.0",
+    "tailwindcss": "^4.3.0"
+  },
+  "peerDependenciesMeta": {
+    "tailwindcss": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "clsx": "2.1.1",
+    "lucide-react": "1.48.0",
+    "tailwind-merge": "3.7.0"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "@internationalized/date": "3.12.4",
+    "@playwright/test": "1.63.0",
+    "@setsquare/review-sdk": "0.8.0",
+    "@tailwindcss/cli": "4.3.3",
+    "@types/node": "22.20.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "axe-core": "4.13.0",
+    "esbuild": "0.28.2",
+    "eslint": "10.11.0",
+    "next": "16.3.6",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
+    "react": "19.3.0",
+    "react-18": "npm:react@18.3.1",
+    "react-aria-components": "1.21.1",
+    "react-dom": "19.3.0",
+    "react-dom-18": "npm:react-dom@18.3.1",
+    "tailwindcss": "4.3.3",
+    "typescript": "7.0.2",
+    "vitest": "5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build-css.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "typecheck:react18": "node scripts/typecheck-react18.mjs",
+    "lint": "oxlint && node scripts/check-contrast.mjs",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "test": "vitest run",
+    "test:browser": "node test/browser/run.mjs",
+    "docs:build": "node scripts/build-docs.mjs",
+    "package:verify": "node scripts/verify-package.mjs",
+    "ci:local": "node scripts/ci-local.mjs",
+    "test:axe": "node test/browser/axe.mjs",
+    "docs:site": "pnpm --filter @setsquare/ui-docs dev",
+    "docs:site:build": "pnpm --filter @setsquare/ui-docs build",
+    "test:site": "node test/site/pages.mjs",
+    "test:setsquare": "node test/setsquare/run.mjs"
+  }
+}

package/templates/next/error.tsx

@@ -0,0 +1,32 @@
+// app/(portal)/error.tsx — catches errors in any portal page; the shell (layout) stays usable around it.
+'use client';
+
+import { useEffect } from 'react';
+import { ShellMain, ErrorState } from '@setsquare/ui';
+
+export default function Error({
+  error,
+  retry,
+}: {
+  error: Error & { digest?: string };
+  retry: () => void;
+}) {
+  useEffect(() => {
+    // Send to your error reporter here. Never show error.message to people: it can leak internals.
+    console.error(error);
+  }, [error]);
+
+  return (
+    <ShellMain>
+      {/* The page's content was replaced by this error: move focus to its heading so it is announced. */}
+      <ErrorState
+        kind="server"
+        headingLevel={1}
+        // oxlint-disable-next-line jsx-a11y/no-autofocus
+        autoFocus
+        onRetry={retry}
+        reference={error.digest}
+      />
+    </ShellMain>
+  );
+}

package/templates/next/loading.tsx

@@ -0,0 +1,19 @@
+// app/(portal)/loading.tsx — Next shows this while a portal page streams in. Shape it like the page that is coming.
+
+import { ShellMain, PageContent, LoadingState, Skeleton, TableSkeleton } from '@setsquare/ui';
+
+export default function Loading() {
+  return (
+    <ShellMain>
+      <div className="px-(--gutter) pt-5 pb-4">
+        <Skeleton className="h-8 w-56" />
+        <Skeleton className="mt-2 h-4 w-96 max-w-full" />
+      </div>
+      <PageContent>
+        <LoadingState label="Loading page">
+          <TableSkeleton />
+        </LoadingState>
+      </PageContent>
+    </ShellMain>
+  );
+}

package/templates/next/not-found.tsx

@@ -0,0 +1,18 @@
+// app/(portal)/not-found.tsx — call notFound() from a page for records that don't exist or aren't visible to this person.
+
+import { ShellMain, LinkButton, ErrorState } from '@setsquare/ui';
+export default function NotFound() {
+  return (
+    <ShellMain>
+      <ErrorState
+        kind="not-found"
+        headingLevel={1}
+        actions={
+          <LinkButton href="/" variant="primary">
+            Go to the overview
+          </LinkButton>
+        }
+      />
+    </ShellMain>
+  );
+}

package/templates/next/page-transition.tsx

@@ -0,0 +1,33 @@
+// Next.js only (React 19.3+): not part of the design-system bundle, which runs on React 18.
+// Wrap each page.tsx's ShellMain — <PageTransition><ShellMain>…</ShellMain></PageTransition> — never the other way
+// round: a ViewTransition only enters and exits if it comes before every DOM node, and ShellMain is a <main>.
+// Never in a layout.tsx either, where enter and exit never fire.
+import { ViewTransition, type ReactNode } from 'react';
+
+/** Two classes, so the stylesheet can cover the old page's place while it leaves (see page-exit there). */
+export function PageTransition({ children }: { children: ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'page-enter', default: 'none' }}
+      exit={{ 'nav-forward': 'page-exit', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+
+/** Wrap the right panel's content, keyed by the selection, so a new selection crossfades in place. */
+export function PanelTransition({ id, children }: { id: string; children: ReactNode }) {
+  return (
+    <ViewTransition
+      key={id}
+      name="panel-content"
+      share="panel-swap"
+      enter="panel-swap"
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}

package/templates/next/portal-layout.tsx

@@ -0,0 +1,70 @@
+// app/(portal)/layout.tsx — the shell every portal page shares. Pages render <PageTransition><ShellMain>…</ShellMain></PageTransition> and, optionally, <RightPanel>.
+'use client';
+
+import type { ReactNode } from 'react';
+import { CircleHelp, Folder, House, SlidersHorizontal } from 'lucide-react';
+import { usePathname, useRouter } from 'next/navigation';
+import { RouterProvider } from 'react-aria-components';
+import {
+  AppHeader,
+  DashboardShell,
+  ShellBody,
+  ShellInset,
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarItem,
+  SidebarList,
+  OfflineAlert,
+  Toaster,
+} from '@setsquare/ui';
+import { usePrefetchOnIntent } from './prefetch-on-intent';
+
+const NAV = [
+  { href: '/', label: 'Overview', icon: House },
+  { href: '/projects', label: 'Projects', icon: Folder },
+  { href: '/settings', label: 'Settings', icon: SlidersHorizontal },
+];
+
+export default function PortalLayout({ children }: { children: ReactNode }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  usePrefetchOnIntent(router);
+  return (
+    // React Aria links and menu items navigate through Next's router, forward, so PageTransition animates.
+    <RouterProvider navigate={(href) => router.push(href, { transitionTypes: ['nav-forward'] })}>
+      <DashboardShell productName={process.env.NEXT_PUBLIC_PRODUCT_NAME ?? 'Product'}>
+        <Sidebar>
+          <SidebarContent>
+            <SidebarGroup label="Workspace">
+              {NAV.map((item) => (
+                <SidebarItem
+                  key={item.href}
+                  href={item.href}
+                  icon={item.icon}
+                  isCurrent={pathname === item.href}
+                >
+                  {item.label}
+                </SidebarItem>
+              ))}
+            </SidebarGroup>
+          </SidebarContent>
+          <SidebarFooter>
+            <SidebarList>
+              <SidebarItem href="/help" icon={CircleHelp}>
+                Help and support
+              </SidebarItem>
+            </SidebarList>
+          </SidebarFooter>
+        </Sidebar>
+        <ShellInset>
+          <AppHeader />
+          <OfflineAlert />
+          <ShellBody>{children}</ShellBody>
+        </ShellInset>
+        <Toaster />
+      </DashboardShell>
+    </RouterProvider>
+  );
+}

package/templates/next/prefetch-on-intent.ts

@@ -0,0 +1,31 @@
+// app/(portal)/prefetch-on-intent.ts — Next.js only: prefetches a page when someone is about to open it.
+'use client';
+
+import { useEffect } from 'react';
+import type { useRouter } from 'next/navigation';
+// router.prefetch's own options type names this enum, and Next exports it from nowhere public.
+import { PrefetchKind } from 'next/dist/client/components/router-reducer/router-reducer-types';
+
+/**
+ * Warms a page when a pointer moves over a link to it or the link takes focus, as Next's own <Link> does —
+ * React Aria's links (SidebarItem, LinkButton, TextLink, menu items) never prefetch. It also keeps the page
+ * transition: a navigation that has to wait for the server can have its `nav-forward` type claimed by a commit
+ * in between (React 19.3 queues transition types per root, not per transition), and the page then changes
+ * with no animation. From the prefetch cache it commits at once.
+ */
+export function usePrefetchOnIntent(router: ReturnType<typeof useRouter>) {
+  useEffect(() => {
+    const warm = (e: Event) => {
+      const link = e.target instanceof Element ? e.target.closest('a[href^="/"]') : null;
+      const href = link?.getAttribute('href')?.replace(/#.*$/, '');
+      if (href && href !== window.location.pathname)
+        router.prefetch(href, { kind: PrefetchKind.FULL });
+    };
+    document.addEventListener('pointerover', warm);
+    document.addEventListener('focusin', warm);
+    return () => {
+      document.removeEventListener('pointerover', warm);
+      document.removeEventListener('focusin', warm);
+    };
+  }, [router]);
+}

package/templates/next/root-layout.tsx

@@ -0,0 +1,16 @@
+// app/layout.tsx — the root layout, for every route group: <html>, <head> and the theme. ThemeScript puts the stored theme on <html> before the first paint; suppressHydrationWarning, because it changes <html> before React hydrates.
+import type { ReactNode } from 'react';
+import { ThemeScript } from '@setsquare/ui';
+import './globals.css';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        {/* With a strict Content-Security-Policy, list its hash (the package README) or pass nonce={…}. */}
+        <ThemeScript />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/next/site-layout.tsx

@@ -0,0 +1,58 @@
+// app/(site)/layout.tsx — the shell every public page shares: header, main and footer, with the navigation from site-nav.ts. A server component: only SiteRouter and the phone menu run in the browser.
+import type { ReactNode } from 'react';
+import {
+  LinkButton,
+  SiteFooter,
+  SiteFooterGroup,
+  SiteHeader,
+  SiteMain,
+  SiteMenu,
+  SiteNav,
+  SiteShell,
+  ThemeSwitcher,
+} from '@setsquare/ui';
+import { COMPANY, NAV, PRODUCT_NAME } from './site-nav';
+import { SiteRouter } from './site-router';
+
+// The root layout (app/layout.tsx, from root-layout.tsx) owns <html> and <head>, and ThemeScript there puts the
+// stored theme on <html> before the first paint. The ThemeSwitcher in the footer uses the same options.
+export default function SiteLayout({ children }: { children: ReactNode }) {
+  const lockup = (
+    <a
+      href="/"
+      className="inline-flex min-h-target min-w-target items-center rounded-md text-base font-bold text-foreground no-underline"
+    >
+      {PRODUCT_NAME}
+    </a>
+  );
+  return (
+    <SiteRouter>
+      <SiteShell>
+        <SiteHeader
+          lockup={lockup}
+          nav={<SiteNav items={NAV} />}
+          actions={
+            <LinkButton href="/start" variant="primary">
+              Get started
+            </LinkButton>
+          }
+          menu={<SiteMenu items={NAV} />}
+        />
+        <SiteMain>{children}</SiteMain>
+        <SiteFooter
+          lockup={lockup}
+          legal={
+            <div className="flex flex-wrap items-center justify-between gap-4">
+              <p>© {PRODUCT_NAME}</p>
+              <ThemeSwitcher />
+            </div>
+          }
+        >
+          {/* The group SiteMenu links to before hydration: it lists the whole navigation. */}
+          <SiteFooterGroup id="site-nav" title="Product" items={NAV} />
+          <SiteFooterGroup title="Company" items={COMPANY} />
+        </SiteFooter>
+      </SiteShell>
+    </SiteRouter>
+  );
+}

package/templates/next/site-nav.ts

@@ -0,0 +1,16 @@
+// app/(site)/site-nav.ts — the public site's navigation, once. The header, the phone menu and the footer all read
+// this list, so the order is the same everywhere.
+import type { SiteNavItem } from '@setsquare/ui';
+
+export const PRODUCT_NAME = 'Product';
+
+export const NAV: SiteNavItem[] = [
+  { href: '/', label: 'Home' },
+  { href: '/pricing', label: 'Pricing' },
+  { href: '/docs', label: 'Docs' },
+];
+
+export const COMPANY: SiteNavItem[] = [
+  { href: '/about', label: 'About' },
+  { href: '/privacy', label: 'Privacy' },
+];

package/templates/next/site-not-found.tsx

@@ -0,0 +1,21 @@
+// app/(site)/not-found.tsx — a public page that doesn't exist, in the site shell.
+import { LinkButton } from '@setsquare/ui';
+
+export default function NotFound() {
+  return (
+    <section className="section-band">
+      <div className="site-container-narrow">
+        <p className="eyebrow">Page not found</p>
+        <h1 className="text-display-page mt-3">We can’t find that page</h1>
+        <p className="text-lead mt-4 text-muted-foreground">
+          It may have moved, or the address may have a typo in it.
+        </p>
+        <div className="mt-8">
+          <LinkButton href="/" variant="primary" visualSize="lg">
+            Go to the home page
+          </LinkButton>
+        </div>
+      </div>
+    </section>
+  );
+}

package/templates/next/site-router.tsx

@@ -0,0 +1,17 @@
+// app/(site)/site-router.tsx — React Aria's links go through Next's router, and the site's navigation learns the current page from the path.
+'use client';
+
+import type { ReactNode } from 'react';
+import { usePathname, useRouter } from 'next/navigation';
+import { RouterProvider } from 'react-aria-components';
+import { SitePathProvider } from '@setsquare/ui';
+
+export function SiteRouter({ children }: { children: ReactNode }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  return (
+    <RouterProvider navigate={(href) => router.push(href)}>
+      <SitePathProvider path={pathname}>{children}</SitePathProvider>
+    </RouterProvider>
+  );
+}