@designtools/blocks 0.0.0-stage → 0.2.0

package/registry/scale.tsx

@@ -0,0 +1,115 @@
+import type { ReactNode } from "react";
+import { shortName, tokensOfTier, withGroupDescriptions } from "./lib/manifest";
+import type { TokenEntry, TokenTier, TokensManifest } from "./lib/manifest-types";
+
+/** Steps drawn for a single `--spacing` multiplier, as Tailwind's p-1, p-2, … would use it. */
+const SPACING_STEPS = [1, 2, 3, 4, 6, 8, 12, 16, 24];
+
+/**
+ * Everything that is not colour or type: space, size, radius, elevation and
+ * motion, each tier drawn the way it is used. Hover a motion row to play it.
+ * Pass `tiers` to show only some, in your order.
+ */
+export function Scale({
+  tokens,
+  tiers = ["spacing", "size", "radius", "shadow", "duration", "ease"],
+}: {
+  tokens: TokensManifest;
+  tiers?: TokenTier[];
+}) {
+  return (
+    <div data-slot="scale" className="flex flex-col gap-10">
+      {tiers.map((tier) => {
+        const rows = tokensOfTier(tokens, tier);
+        if (rows.length === 0) return null;
+        return (
+          <div key={tier} data-slot="scale-tier" className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium capitalize">{tier}</h3>
+            {tier === "spacing" ? <Spacing rows={rows} /> : <Rows rows={rows} tier={tier} />}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function Spacing({ rows }: { rows: TokenEntry[] }) {
+  const multiplier = rows.find((t) => t.name === "--spacing");
+  const named = rows.filter((t) => t !== multiplier);
+  return (
+    <div className="flex flex-col gap-4">
+      {multiplier && (
+        <>
+          <p className="text-xs text-muted-foreground">
+            {multiplier.description ?? "One multiplier"}: <span className="font-mono">--spacing: {multiplier.values.default}</span>
+          </p>
+          <ul className="flex flex-col gap-1.5">
+            {SPACING_STEPS.map((n) => (
+              <li key={n} className="grid grid-cols-[4rem_1fr] items-center gap-3 font-mono text-xs">
+                <span className="text-muted-foreground">{n}</span>
+                <span data-slot="scale-bar" className="h-3 rounded-sm bg-primary" style={{ width: `calc(var(--spacing) * ${n})` }} />
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+      {named.length > 0 && <Rows rows={named} tier="spacing" />}
+    </div>
+  );
+}
+
+function Rows({ rows, tier }: { rows: TokenEntry[]; tier: TokenTier }) {
+  return (
+    <ul className="flex flex-col divide-y divide-border border-y border-border">
+      {withGroupDescriptions(rows).map((t) => (
+        <li key={t.name} data-slot="scale-row" className="group flex flex-col gap-2 py-3">
+          {t.groupDescription && <p className="text-xs text-muted-foreground">{t.groupDescription}</p>}
+          <div className="grid grid-cols-1 items-center gap-3 md:grid-cols-[10rem_minmax(0,1fr)]">
+            <span className="flex min-w-0 flex-col font-mono text-xs text-muted-foreground">
+              <span className="font-medium text-canvas-foreground">{shortName(t, tier)}</span>
+              <span className="truncate" title={t.values.default}>
+                {t.values.default}
+              </span>
+            </span>
+            <span className="min-w-0">{sample(t, tier)}</span>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function sample(t: TokenEntry, tier: TokenTier): ReactNode {
+  const v = `var(${t.name})`;
+  switch (tier) {
+    case "spacing":
+      return <span className="block h-3 rounded-sm bg-primary" style={{ width: v }} />;
+    case "size":
+      return <span className="block rounded-sm bg-primary" style={{ width: v, height: v }} />;
+    case "radius":
+      return <span className="block size-16 border-2 border-primary bg-primary-subdued" style={{ borderRadius: v }} />;
+    case "shadow":
+      return <span className="block h-16 w-32 rounded-md bg-surface" style={{ boxShadow: v }} />;
+    case "duration":
+      return <Motion duration={v} easing="var(--ease-out, ease-out)" />;
+    case "ease":
+      return <Motion duration="var(--duration-slow, 400ms)" easing={v} />;
+    default:
+      return <span className="font-mono text-xs">{t.values.default}</span>;
+  }
+}
+
+/** A dot that crosses its track on hover, with the token's duration or easing. Reduced motion jumps instead. */
+function Motion({ duration, easing }: { duration: string; easing: string }) {
+  return (
+    <span data-slot="scale-motion" className="relative block h-4 w-full max-w-sm rounded-full bg-muted">
+      {/* the runner is the track less the dot, so translating it by its own width lands the dot at the end */}
+      <span
+        className="absolute inset-y-0 right-4 left-0 block transition-transform group-hover:translate-x-full motion-reduce:transition-none"
+        style={{ transitionDuration: duration, transitionTimingFunction: easing }}
+      >
+        <span className="block size-4 rounded-full bg-primary" />
+      </span>
+    </span>
+  );
+}

package/registry/search.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import { Autocomplete } from "@base-ui/react/autocomplete";
+import { Dialog } from "@base-ui/react/dialog";
+import { useRouter } from "next/navigation";
+import { useEffect, useId, useMemo, useState } from "react";
+import { cx, target } from "./lib/cx";
+import { search, type SearchGroup, type SearchItem } from "./lib/search";
+
+const PLURAL: Record<SearchGroup["kind"], string> = { Component: "Components", Rule: "Rules", Pattern: "Patterns", Page: "Pages" };
+
+/**
+ * Find a component, a part, a rule, a pattern or a page by name, fuzzily, and go
+ * there. A wrong name finds the right thing ("Dropdown" finds Select, and says
+ * so). Opens with ⌘K or Ctrl+K anywhere, or / when you are not typing. Build the
+ * items with `searchIndex` from `lib/search`; the shell does, when you pass it the
+ * taxonomy. Navigation only: it does not search page text.
+ */
+export function DocsSearch({
+  items,
+  shortcuts = true,
+  className,
+}: {
+  items: SearchItem[];
+  /** Listen for ⌘K, Ctrl+K and /. Give one search on a page the shortcuts. */
+  shortcuts?: boolean;
+  className?: string;
+}) {
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [shortcut, setShortcut] = useState("Ctrl K");
+  const hintId = useId();
+  const groups = useMemo(() => search(items, query), [items, query]);
+
+  useEffect(() => {
+    if (/Mac|iPhone|iPad/.test(navigator.platform)) setShortcut("⌘K");
+    if (!shortcuts) return;
+    const onKey = (e: KeyboardEvent) => {
+      const typing = e.target instanceof HTMLElement && (e.target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName));
+      if ((e.key === "k" && (e.metaKey || e.ctrlKey)) || (e.key === "/" && !typing && !e.metaKey && !e.ctrlKey && !e.altKey)) {
+        e.preventDefault();
+        setOpen(true);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [shortcuts]);
+
+  const go = (item: SearchItem) => {
+    setOpen(false);
+    setQuery("");
+    router.push(item.href);
+  };
+
+  return (
+    <Dialog.Root open={open} onOpenChange={(next) => (setOpen(next), next || setQuery(""))}>
+      <Dialog.Trigger
+        data-slot="docs-search-trigger"
+        className={cx(
+          target,
+          "flex w-full items-center justify-between gap-3 rounded-md border border-input bg-canvas px-3 text-sm text-muted-foreground hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+          className,
+        )}
+      >
+        <span>Search</span>
+        <kbd className="font-mono text-xs pointer-coarse:hidden">{shortcut}</kbd>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 bg-canvas-foreground/30" />
+        <Dialog.Viewport className="fixed inset-0 flex items-start justify-center px-4 pt-[12dvh]">
+          <Dialog.Popup
+            data-slot="docs-search"
+            aria-label="Search the design system"
+            className="flex max-h-[min(36rem,80dvh)] w-full max-w-lg flex-col overflow-hidden rounded-lg border border-border bg-overlay text-overlay-foreground shadow-lg"
+          >
+            <Autocomplete.Root
+              open
+              inline
+              items={groups}
+              filter={null}
+              value={query}
+              onValueChange={(next) => setQuery(next)}
+              itemToStringValue={(item: SearchItem) => item.label}
+              autoHighlight="always"
+              keepHighlight
+            >
+              <Autocomplete.Input
+                aria-label="Search components, rules, patterns and pages"
+                aria-describedby={hintId}
+                placeholder="Search components, rules, patterns…"
+                className={cx(target, "w-full border-b border-border bg-transparent px-4 text-base outline-none placeholder:text-muted-foreground")}
+              />
+              <Dialog.Close className="sr-only">Close search</Dialog.Close>
+              <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain py-2">
+                <Autocomplete.Empty>
+                  <p className="px-4 py-6 text-sm text-muted-foreground">{query.trim() ? `Nothing called “${query.trim()}”.` : "Type a name, or a name you half remember."}</p>
+                </Autocomplete.Empty>
+                <Autocomplete.List>
+                  {(group: SearchGroup) => (
+                    <Autocomplete.Group key={group.kind} items={group.items} className="not-last:mb-2">
+                      <Autocomplete.GroupLabel className="px-4 py-1 text-xs font-medium text-muted-foreground">{PLURAL[group.kind]}</Autocomplete.GroupLabel>
+                      <Autocomplete.Collection>
+                        {(item: SearchGroup["items"][number]) => (
+                          <Autocomplete.Item
+                            key={item.href}
+                            value={item}
+                            onClick={() => go(item)}
+                            className={cx(
+                              target,
+                              "flex cursor-default items-center justify-between gap-3 px-4 py-2 text-sm outline-none select-none data-highlighted:bg-muted",
+                            )}
+                          >
+                            <span className="min-w-0 truncate font-medium">{item.label}</span>
+                            <span className="shrink-0 text-xs text-muted-foreground">
+                              {item.matched ? `for “${item.matched}”` : item.detail}
+                            </span>
+                          </Autocomplete.Item>
+                        )}
+                      </Autocomplete.Collection>
+                    </Autocomplete.Group>
+                  )}
+                </Autocomplete.List>
+              </div>
+              <p id={hintId} className="border-t border-border px-4 py-2 text-xs text-muted-foreground">
+                Arrow keys to move, Enter to go, Escape to close.
+              </p>
+            </Autocomplete.Root>
+          </Dialog.Popup>
+        </Dialog.Viewport>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}

package/registry/shell.tsx

@@ -0,0 +1,247 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { type ReactNode, useMemo } from "react";
+import { cx, target } from "./lib/cx";
+import { groupFamilies, slugOf } from "./lib/manifest";
+import { Prose } from "./lib/text";
+import type { ComponentsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./lib/manifest-types";
+import { searchIndex } from "./lib/search";
+import { DocsSearch } from "./search";
+
+export interface DocsLink {
+  label: string;
+  href: string;
+  /** Shown beneath it while you are on it or one of them: a component's parts. */
+  children?: DocsLink[];
+}
+
+/**
+ * The docs frame, in the site's order: brand, foundations, rules, patterns,
+ * components by `@category`, standards. Editorial pages are the links you pass;
+ * rules, patterns and components come from the manifest. On a narrow screen
+ * the navigation folds into a disclosure. Put it in the docs layout; it marks
+ * the page you are on.
+ */
+export function DocsShell({
+  manifest,
+  rules,
+  patterns,
+  terms,
+  search = true,
+  title = "Design system",
+  logo,
+  basePath = "/design/system",
+  brand = [],
+  foundations = [],
+  standards = [],
+  children,
+}: {
+  manifest: ComponentsManifest;
+  /** Listed under Rules, each linking to its anchor on `${basePath}/rules`. */
+  rules?: RulesManifest;
+  /** Listed under Patterns, each at `${basePath}/patterns/${id}`. */
+  patterns?: PatternsManifest;
+  /** The taxonomy, so search finds a component by a wrong name ("Dropdown" finds Select). */
+  terms?: TaxonomyManifest;
+  /** Search over components, parts, rules, patterns and pages, on ⌘K, Ctrl+K or /. On by default. */
+  search?: boolean;
+  title?: string;
+  /** The client's logo, shown beside the title: the site is theirs. */
+  logo?: ReactNode;
+  /** Component pages live at `${basePath}/components/${slug}`. */
+  basePath?: string;
+  /** Brand pages: principles, design language, voice, logo, imagery. */
+  brand?: DocsLink[];
+  /** Foundations pages: colour, type, scale. */
+  foundations?: DocsLink[];
+  /** Standards pages: budgets, accessibility, adherence. */
+  standards?: DocsLink[];
+  children: ReactNode;
+}) {
+  const current = usePathname();
+  const searchItems = useMemo(
+    () =>
+      searchIndex({
+        manifest,
+        rules: rules?.rules,
+        patterns: patterns?.patterns,
+        terms: terms?.terms,
+        pages: [...brand, ...foundations, ...(rules?.rules.length ? [{ label: "Rules", href: `${basePath}/rules` }] : []), ...standards],
+        basePath,
+      }),
+    [manifest, rules, patterns, terms, brand, foundations, standards, basePath],
+  );
+  const groups = [
+    ...(brand.length ? [{ heading: "Brand", links: brand }] : []),
+    ...(foundations.length ? [{ heading: "Foundations", links: foundations }] : []),
+    ...(rules?.rules.length
+      ? [{ heading: "Rules", links: [{ label: "All rules", href: `${basePath}/rules` }] }]
+      : []),
+    ...(patterns?.patterns.length
+      ? [{ heading: "Patterns", links: patterns.patterns.map((p) => ({ label: p.name, href: `${basePath}/patterns/${p.id}` })) }]
+      : []),
+    ...groupFamilies(manifest).map((g) => ({
+      heading: g.category,
+      links: g.families.map(({ head, parts }) => ({
+        label: head.name,
+        href: `${basePath}/components/${slugOf(head)}`,
+        children: parts.map((p) => ({ label: p.name, href: `${basePath}/components/${slugOf(p)}` })),
+      })),
+    })),
+    ...(standards.length ? [{ heading: "Standards", links: standards }] : []),
+  ];
+
+  const nav = (
+    <nav aria-label={title} data-slot="docs-nav" className="flex flex-col gap-6 p-4 text-sm">
+      {groups.map((group) => (
+        <div key={group.heading} data-slot="docs-nav-group" className="flex flex-col gap-1">
+          <p data-slot="docs-nav-heading" className="px-2 text-xs font-medium text-muted-foreground">
+            {group.heading}
+          </p>
+          <ul className="flex flex-col">
+            {group.links.map((link) => {
+              const open = current === link.href || link.children?.some((c) => c.href === current);
+              return (
+                <li key={link.href}>
+                  <NavLink link={link} current={current} />
+                  {open && link.children?.length ? (
+                    <ul data-slot="docs-nav-parts" aria-label={`${link.label} parts`} className="ml-3 flex flex-col border-l border-border pl-2">
+                      {link.children.map((child) => (
+                        <li key={child.href}>
+                          <NavLink link={child} current={current} />
+                        </li>
+                      ))}
+                    </ul>
+                  ) : null}
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      ))}
+    </nav>
+  );
+
+  return (
+    <div data-slot="docs-shell" className="min-h-dvh bg-canvas text-canvas-foreground md:grid md:grid-cols-[16rem_1fr]">
+      <aside
+        data-slot="docs-sidebar"
+        className="hidden border-r border-border bg-surface text-surface-foreground md:sticky md:top-0 md:block md:h-dvh md:overflow-y-auto"
+      >
+        <Link href={basePath} data-slot="docs-title" className={cx(target, "flex flex-col items-start gap-2 px-6 pt-6 pb-2 font-semibold")}>
+          {logo && <span data-slot="docs-logo">{logo}</span>}
+          <span>{title}</span>
+        </Link>
+        {search && (
+          <div className="px-4 pt-2">
+            <DocsSearch items={searchItems} />
+          </div>
+        )}
+        {nav}
+      </aside>
+      <details data-slot="docs-nav-disclosure" className="border-b border-border bg-surface text-surface-foreground md:hidden">
+        <summary className={cx(target, "flex cursor-pointer items-center gap-3 px-4 py-3 font-semibold")}>
+          {logo && <span data-slot="docs-logo">{logo}</span>}
+          <span>{title}</span>
+        </summary>
+        {nav}
+      </details>
+      {search && (
+        // outside the disclosure, so a phone can search without opening the navigation; the
+        // sidebar's search owns the keyboard shortcut, so one key press opens one dialog
+        <div className="border-b border-border bg-surface px-4 py-2 md:hidden">
+          <DocsSearch items={searchItems} shortcuts={false} />
+        </div>
+      )}
+      <main data-slot="docs-main" className="min-w-0 px-4 py-8 md:px-10 md:py-12">
+        <div className="mx-auto flex max-w-5xl flex-col gap-12">{children}</div>
+      </main>
+    </div>
+  );
+}
+
+/**
+ * A page's heading, lead and source, and where it comes from: a generated page
+ * names the version and commit it was built from; an editorial page names its
+ * author, when it was last reviewed, and whether it is settled. Never both, and
+ * never a review date on a generated page, which would be invented.
+ */
+export function DocsHeader({
+  title,
+  lead,
+  source,
+  provenance,
+  editorial,
+  children,
+}: {
+  title: string;
+  lead?: string;
+  /** Shown as the file the page documents. */
+  source?: string;
+  /** For a generated page: `Generated from acme-web@1.4.0 at 3f2a9c1`, from `designtools-manifest provenance`. */
+  provenance?: string;
+  /** For an editorial page. */
+  /** `reviewer` when the person who signs it off is not the author: the studio writes, the client's brand lead reviews. */
+  editorial?: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" };
+  children?: ReactNode;
+}) {
+  return (
+    <header data-slot="docs-header" className="flex flex-col gap-3">
+      {(provenance || editorial) && (
+        <p data-slot="docs-provenance" className="text-xs text-muted-foreground">
+          {editorial
+            ? `Written by ${editorial.author} · ${editorial.reviewer ? `reviewed by ${editorial.reviewer}, ` : "last reviewed "}${editorial.reviewed} · ${editorial.status}`
+            : `${provenance} · generated from the code`}
+        </p>
+      )}
+      <h1 className="text-3xl font-semibold">{title}</h1>
+      {lead && (
+        <div data-slot="docs-lead" className="flex max-w-prose flex-col gap-3 text-muted-foreground">
+          <Prose text={lead} />
+        </div>
+      )}
+      {source && (
+        <p data-slot="docs-source" className="font-mono text-xs text-muted-foreground">
+          {source}
+        </p>
+      )}
+      {children}
+    </header>
+  );
+}
+
+/** A titled section of a docs page. */
+export function DocsSection({ title, lead, children }: { title: string; lead?: string; children: ReactNode }) {
+  const id = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return (
+    <section data-slot="docs-section" aria-labelledby={id} className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <h2 id={id} className="text-xl font-semibold">
+          {title}
+        </h2>
+        {lead && <p className="max-w-prose text-sm text-muted-foreground">{lead}</p>}
+      </div>
+      {children}
+    </section>
+  );
+}
+
+function NavLink({ link, current }: { link: DocsLink; current: string }) {
+  const active = current === link.href;
+  return (
+    <Link
+      href={link.href}
+      aria-current={active ? "page" : undefined}
+      data-slot="docs-nav-link"
+      className={cx(
+        target,
+        "flex items-center rounded-md px-2 py-1.5 hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+        active && "bg-muted font-medium",
+      )}
+    >
+      {link.label}
+    </Link>
+  );
+}

package/registry/standards.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import { standardsSections } from "./lib/standards";
+
+/**
+ * The project's performance budgets, accessibility target and support baseline,
+ * rendered from the thresholds it already records (`.mxa/stack.json`
+ * `baselines`), so the docs and the checks cannot disagree. A value nobody has
+ * set is left out rather than shown as `null`; a note is shown as a sentence.
+ * Thresholds a client agrees beyond the schema (`textSize`, `touchTargets`) are
+ * titled from their keys.
+ */
+export function Standards({ baselines, children }: { baselines: Record<string, unknown>; children?: ReactNode }) {
+  return (
+    <div data-slot="standards" className="flex flex-col gap-8">
+      {standardsSections(baselines).map((section) => (
+        <section key={section.key} data-slot="standard" className="flex flex-col gap-2">
+          <h3 className="text-sm font-medium">{section.title}</h3>
+          {section.rows.length === 1 && !section.rows[0].label ? (
+            <p className="text-sm">{section.rows[0].value}</p>
+          ) : section.rows.length ? (
+            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[14rem_1fr]">
+              {section.rows.map((row) => (
+                <div key={row.label} className="contents">
+                  <dt className="text-muted-foreground">{row.label}</dt>
+                  <dd>{row.value}</dd>
+                </div>
+              ))}
+            </dl>
+          ) : null}
+          {section.notes.map((note) => (
+            <p key={note} className="max-w-prose text-sm text-muted-foreground">
+              {note}
+            </p>
+          ))}
+        </section>
+      ))}
+      {typeof baselines.$note === "string" && <p className="text-sm text-muted-foreground">{baselines.$note}</p>}
+      {children}
+    </div>
+  );
+}