@designtools/blocks 0.0.0-stage → 0.1.0

package/registry/pattern.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import Link from "next/link";
+import { CodeView } from "./code-view";
+import { Boundary } from "./lib/boundary";
+import { compositionsFor, Missing, renderExample } from "./lib/lookup";
+import { slugOf } from "./lib/manifest";
+import type { ComponentsManifest, PatternEntry } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+import { inline } from "./lib/text";
+
+/** A recurring screen composition: each composition live, with its code and the components it uses. */
+export function Pattern({
+  pattern,
+  manifest,
+  basePath = "/design/system",
+}: {
+  pattern: PatternEntry;
+  /** To link the components it uses to their pages. */
+  manifest?: ComponentsManifest;
+  basePath?: string;
+}) {
+  const module = compositionsFor(pattern);
+  const known = new Map((manifest?.components ?? []).map((c) => [c.name, c]));
+  return (
+    <div data-slot="pattern" className="flex flex-col gap-6">
+      <div className="flex flex-wrap items-center gap-2 text-sm">
+        <StatusBadge status={pattern.status} />
+        {pattern.components.length > 0 && <span className="text-muted-foreground">Composes</span>}
+        {pattern.components.map((name) => {
+          const c = known.get(name);
+          return c ? (
+            <Link key={name} href={`${basePath}/components/${slugOf(c)}`} className="rounded-sm bg-muted px-1.5 py-0.5 font-mono text-xs hover:underline">
+              {name}
+            </Link>
+          ) : (
+            <code key={name} className="rounded-sm bg-muted px-1.5 py-0.5 font-mono text-xs">
+              {name}
+            </code>
+          );
+        })}
+      </div>
+      {!module ? (
+        <Missing name={pattern.name} what="compositions" />
+      ) : (
+        pattern.examples.map((ex) => (
+          <figure key={ex.name} data-slot="pattern-composition" className="flex min-w-0 flex-col overflow-hidden rounded-lg border border-border">
+            <div className="flex min-h-48 items-center justify-center overflow-auto bg-surface p-6 text-surface-foreground">
+              <Boundary label={ex.name}>{renderExample(module[ex.name], ex.name)}</Boundary>
+            </div>
+            <figcaption className="flex flex-col gap-2 border-t border-border px-4 py-3 text-sm">
+              <code className="font-mono text-xs text-muted-foreground">{ex.name}</code>
+              {ex.description && <span className="text-muted-foreground">{inline(ex.description)}</span>}
+              {ex.code && (
+                <details>
+                  <summary className="cursor-pointer text-xs text-muted-foreground">Code</summary>
+                  <div className="mt-2">
+                    <CodeView code={ex.code} label={ex.name} />
+                  </div>
+                </details>
+              )}
+            </figcaption>
+          </figure>
+        ))
+      )}
+    </div>
+  );
+}

package/registry/playground.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+import { Select } from "@base-ui/react/select";
+import { Switch } from "@base-ui/react/switch";
+import { Toggle } from "@base-ui/react/toggle";
+import { ToggleGroup } from "@base-ui/react/toggle-group";
+import { useId, useState } from "react";
+import { CodeView } from "./code-view";
+import { Boundary } from "./lib/boundary";
+import { cx } from "./lib/cx";
+import { toJSX } from "./lib/jsx";
+import { coerce, componentFor, Missing } from "./lib/lookup";
+import type { ComponentEntry, VariantAxis } from "./lib/manifest-types";
+
+/**
+ * The component, live, with controls generated from its variants and its own
+ * boolean props, and the JSX for exactly what is showing. Pass `props` for what
+ * it needs to render at all; the controls change everything else.
+ */
+export function Playground({
+  entry,
+  props: base = {},
+  children: initialText = entry.name,
+}: {
+  entry: ComponentEntry;
+  props?: Record<string, unknown>;
+  /** Text content, editable in the playground. Pass "" for a component without children. */
+  children?: string;
+}) {
+  const Component = componentFor(entry);
+  const axes = entry.variants?.axes ?? [];
+  const axisNames = new Set(axes.map((a) => a.name));
+  const flags = Object.entries(entry.props)
+    .filter(([name, p]) => !p.from && !axisNames.has(name) && p.type === "boolean" && p.deprecated === undefined)
+    .map(([name]) => name);
+
+  const [variants, setVariants] = useState<Record<string, string>>({});
+  const [on, setOn] = useState<Record<string, boolean>>({});
+  const [text, setText] = useState(initialText);
+
+  if (!Component) return <Missing name={entry.name} />;
+
+  const chosen = { ...coerce(variants), ...Object.fromEntries(Object.entries(on).filter(([, v]) => v)) };
+  const code = toJSX(entry.export, { ...visible(base), ...chosen }, text || undefined);
+
+  return (
+    <div data-slot="playground" className="flex flex-col gap-4">
+      <div className="grid overflow-hidden rounded-lg border border-border md:grid-cols-[minmax(0,1fr)_16rem]">
+        <div data-slot="playground-preview" className="flex min-h-48 min-w-0 items-center justify-center overflow-auto bg-surface p-8 text-surface-foreground">
+          <Boundary label={entry.name}>
+            <Component {...base} {...chosen}>
+              {text || undefined}
+            </Component>
+          </Boundary>
+        </div>
+        <div data-slot="playground-controls" className="flex flex-col gap-4 border-t border-border p-4 md:border-t-0 md:border-l">
+          {axes.map((axis) => (
+            <AxisControl
+              key={axis.name}
+              axis={axis}
+              value={variants[axis.name] ?? axis.default ?? ""}
+              onChange={(v) => setVariants((s) => ({ ...s, [axis.name]: v }))}
+            />
+          ))}
+          {flags.map((name) => (
+            <FlagControl key={name} name={name} checked={!!on[name]} onChange={(v) => setOn((s) => ({ ...s, [name]: v }))} />
+          ))}
+          {initialText !== "" && <TextControl value={text} onChange={setText} />}
+        </div>
+      </div>
+      <CodeView code={code} label="JSX" />
+    </div>
+  );
+}
+
+/** Props passed only so the component renders (handlers, data) are left out of the snippet unless they are short. */
+function visible(props: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(props).filter(([, v]) => typeof v !== "function" && JSON.stringify(v ?? "").length <= 40));
+}
+
+const label = "text-xs font-medium text-muted-foreground";
+
+function AxisControl({ axis, value, onChange }: { axis: VariantAxis; value: string; onChange: (v: string) => void }) {
+  const id = useId();
+  if (axis.options.length <= 5) {
+    return (
+      <div className="flex flex-col gap-1.5">
+        <span id={id} className={cx(label, "font-mono")}>
+          {axis.name}
+        </span>
+        <ToggleGroup
+          aria-labelledby={id}
+          value={value ? [value] : []}
+          onValueChange={(next) => next[0] && onChange(String(next[0]))}
+          className="flex flex-wrap gap-1"
+        >
+          {axis.options.map((o) => (
+            <Toggle
+              key={o.name}
+              value={o.name}
+              title={o.description}
+              className="rounded-md border border-border px-2 py-1 font-mono text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring data-[pressed]:bg-primary data-[pressed]:text-primary-foreground"
+            >
+              {o.name}
+            </Toggle>
+          ))}
+        </ToggleGroup>
+      </div>
+    );
+  }
+  return (
+    <div className="flex flex-col gap-1.5">
+      <span id={id} className={cx(label, "font-mono")}>
+        {axis.name}
+      </span>
+      <Select.Root value={value} onValueChange={(v) => typeof v === "string" && onChange(v)}>
+        <Select.Trigger
+          aria-labelledby={id}
+          className="flex items-center justify-between rounded-md border border-border px-2 py-1 font-mono text-xs focus-visible:outline-2 focus-visible:outline-ring"
+        >
+          <Select.Value />
+          <Select.Icon aria-hidden>▾</Select.Icon>
+        </Select.Trigger>
+        <Select.Portal>
+          <Select.Positioner sideOffset={4} className="z-50">
+            <Select.Popup className="rounded-md border border-border bg-overlay p-1 text-overlay-foreground shadow-md">
+              <Select.List>
+                {axis.options.map((o) => (
+                  <Select.Item
+                    key={o.name}
+                    value={o.name}
+                    className="cursor-default rounded-sm px-2 py-1 font-mono text-xs outline-none data-[highlighted]:bg-muted"
+                  >
+                    <Select.ItemText>{o.name}</Select.ItemText>
+                  </Select.Item>
+                ))}
+              </Select.List>
+            </Select.Popup>
+          </Select.Positioner>
+        </Select.Portal>
+      </Select.Root>
+    </div>
+  );
+}
+
+function FlagControl({ name, checked, onChange }: { name: string; checked: boolean; onChange: (v: boolean) => void }) {
+  const id = useId();
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <label htmlFor={id} className={cx(label, "font-mono")}>
+        {name}
+      </label>
+      <Switch.Root
+        id={id}
+        checked={checked}
+        onCheckedChange={onChange}
+        className="relative h-5 w-9 shrink-0 rounded-full border border-border bg-canvas outline-offset-2 focus-visible:outline-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary"
+      >
+        <Switch.Thumb className="block size-3.5 translate-x-0.5 rounded-full bg-muted-foreground transition-transform data-[checked]:translate-x-[1.0625rem] data-[checked]:bg-primary-foreground motion-reduce:transition-none" />
+      </Switch.Root>
+    </div>
+  );
+}
+
+function TextControl({ value, onChange }: { value: string; onChange: (v: string) => void }) {
+  const id = useId();
+  return (
+    <div className="flex flex-col gap-1.5">
+      <label htmlFor={id} className={label}>
+        Content
+      </label>
+      <input
+        id={id}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="rounded-md border border-border bg-canvas px-2 py-1 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+      />
+    </div>
+  );
+}

package/registry/preview-frame.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { useEffect, useState, type ReactNode } from "react";
+import { Boundary } from "./lib/boundary";
+import { cx } from "./lib/cx";
+import { compositionsFor, examplesFor, Missing, renderExample } from "./lib/lookup";
+import type { ComponentEntry, PatternEntry } from "./lib/manifest-types";
+
+type Theme = "light" | "dark";
+
+/**
+ * A preview route in an iframe, at set widths and in either mode, so a
+ * component is seen at a phone's width and its media queries actually fire.
+ */
+export function PreviewFrame({
+  src,
+  title,
+  widths = [375, 768, 1280],
+  height = 360,
+}: {
+  /** The preview route, e.g. `/design/system/preview/badge/canonical`. */
+  src: string;
+  title: string;
+  widths?: number[];
+  height?: number;
+}) {
+  const [width, setWidth] = useState(widths[0]);
+  const [theme, setTheme] = useState<Theme>("light");
+  const url = `${src}${src.includes("?") ? "&" : "?"}theme=${theme}`;
+  const button = "rounded-md px-2 py-1 font-mono text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring";
+
+  return (
+    <figure data-slot="preview-frame" className="flex flex-col gap-2">
+      <figcaption className="flex flex-wrap items-center justify-between gap-2">
+        <span className="text-sm font-medium">{title}</span>
+        <span className="flex flex-wrap items-center gap-1" role="group" aria-label="Preview width and mode">
+          {widths.map((w) => (
+            <button key={w} type="button" aria-pressed={width === w} onClick={() => setWidth(w)} className={cx(button, width === w && "bg-muted")}>
+              {w}
+            </button>
+          ))}
+          <button
+            type="button"
+            aria-pressed={theme === "dark"}
+            onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+            className={cx(button, theme === "dark" && "bg-muted")}
+          >
+            dark
+          </button>
+          <a href={url} target="_blank" rel="noreferrer" className={button}>
+            open ↗
+          </a>
+        </span>
+      </figcaption>
+      <div className="overflow-x-auto rounded-lg border border-border bg-muted p-2">
+        <iframe
+          title={`${title}, ${width}px wide, ${theme} mode`}
+          src={url}
+          data-slot="preview-iframe"
+          className="block resize-y rounded-md border border-border bg-canvas"
+          style={{ width, height, maxWidth: "none" }}
+        />
+      </div>
+    </figure>
+  );
+}
+
+/**
+ * What the preview route renders around a state: the page's canvas in the
+ * requested mode, set on the document too, so popups in portals match.
+ */
+export function PreviewSurface({ theme, children }: { theme?: string; children: ReactNode }) {
+  const mode: Theme | undefined = theme === "dark" || theme === "light" ? theme : undefined;
+  useEffect(() => {
+    if (!mode) return;
+    const root = document.documentElement;
+    const previous = root.dataset.theme;
+    root.dataset.theme = mode;
+    return () => {
+      if (previous === undefined) delete root.dataset.theme;
+      else root.dataset.theme = previous;
+    };
+  }, [mode]);
+
+  return (
+    <div data-slot="preview-surface" data-theme={mode} className="min-h-dvh bg-canvas p-6 text-canvas-foreground">
+      {children}
+    </div>
+  );
+}
+
+/** One example on its own, for the preview route to render inside a PreviewSurface. */
+export function PreviewExample({ entry, example }: { entry: ComponentEntry; example: string }) {
+  const module = examplesFor(entry);
+  if (!module) return <Missing name={entry.name} what="examples" />;
+  if (!(example in module)) return <p className="text-sm">{entry.name} has no example called {example}.</p>;
+  return <Boundary label={example}>{renderExample(module[example], example)}</Boundary>;
+}
+
+/** One pattern composition on its own. */
+export function PreviewComposition({ pattern, composition }: { pattern: PatternEntry; composition: string }) {
+  const module = compositionsFor(pattern);
+  if (!module) return <Missing name={pattern.name} what="compositions" />;
+  if (!(composition in module)) return <p className="text-sm">{pattern.name} has no composition called {composition}.</p>;
+  return <Boundary label={composition}>{renderExample(module[composition], composition)}</Boundary>;
+}

package/registry/props-table.tsx

@@ -0,0 +1,110 @@
+import { cx } from "./lib/cx";
+import { inline } from "./lib/text";
+import type { ComponentEntry, PropEntry } from "./lib/manifest-types";
+
+/**
+ * A component's props: its own first, then those of the primitive it wraps,
+ * folded away. Deprecated props are struck through with the reason; what it
+ * inherits from an element or primitive is named underneath rather than listed.
+ */
+export function PropsTable({ entry }: { entry: ComponentEntry }) {
+  const rows = Object.entries(entry.props);
+  const own = rows.filter(([, p]) => !p.from);
+  const byPackage = new Map<string, [string, PropEntry][]>();
+  for (const row of rows.filter(([, p]) => p.from)) {
+    byPackage.set(row[1].from!, [...(byPackage.get(row[1].from!) ?? []), row]);
+  }
+
+  return (
+    <div data-slot="props-table" className="flex flex-col gap-4">
+      {own.length > 0 ? <Table rows={own} /> : <p className="text-sm text-muted-foreground">No props of its own.</p>}
+      {[...byPackage.entries()].map(([pkg, inherited]) => (
+        <details key={pkg} data-slot="props-inherited" className="rounded-md border border-border">
+          <summary className="cursor-pointer px-3 py-2 text-sm">
+            {inherited.length} props from <span className="font-mono">{pkg}</span>
+          </summary>
+          <div className="border-t border-border p-3">
+            <Table rows={inherited} />
+          </div>
+        </details>
+      ))}
+      {entry.inherits && entry.inherits.length > 0 && (
+        <p data-slot="props-inherits" className="text-sm text-muted-foreground">
+          Also accepts every prop of{" "}
+          {entry.inherits.map((x, i) => (
+            <span key={x}>
+              {i > 0 && ", "}
+              <code className="font-mono text-xs">{/^[a-z][\w-]*$/.test(x) ? `<${x}>` : x}</code>
+            </span>
+          ))}
+          .
+        </p>
+      )}
+    </div>
+  );
+}
+
+function Table({ rows }: { rows: [string, PropEntry][] }) {
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full min-w-[36rem] border-collapse text-left text-sm">
+        <thead>
+          <tr className="border-b border-border text-xs text-muted-foreground">
+            <th scope="col" className="py-2 pr-4 font-medium">
+              Prop
+            </th>
+            <th scope="col" className="py-2 pr-4 font-medium">
+              Type
+            </th>
+            <th scope="col" className="py-2 pr-4 font-medium">
+              Default
+            </th>
+            <th scope="col" className="py-2 font-medium">
+              Description
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map(([name, prop]) => (
+            <tr key={name} data-slot="props-row" className="border-b border-border align-top">
+              <th scope="row" className="py-2 pr-4 font-normal">
+                <span className="flex flex-col items-start gap-1">
+                  <code className={cx("font-mono text-xs font-medium", prop.deprecated !== undefined && "line-through")}>{name}</code>
+                  {prop.required && (
+                    <span data-slot="props-required" className="rounded-sm bg-muted px-1 text-[0.625rem] text-muted-foreground">
+                      required
+                    </span>
+                  )}
+                </span>
+              </th>
+              <td className="py-2 pr-4">
+                {prop.values ? (
+                  <span className="flex flex-wrap gap-1">
+                    {prop.values.map((v) => (
+                      <code key={v} className="rounded-sm bg-muted px-1 font-mono text-xs">
+                        {v}
+                      </code>
+                    ))}
+                  </span>
+                ) : (
+                  <code className="font-mono text-xs break-words">{prop.type}</code>
+                )}
+              </td>
+              <td className="py-2 pr-4">{prop.default !== undefined && <code className="font-mono text-xs">{prop.default}</code>}</td>
+              <td className="py-2 text-muted-foreground">
+                {prop.deprecated !== undefined && (
+                  <p className="font-medium text-canvas-foreground">Deprecated{prop.deprecated ? <>: {inline(prop.deprecated)}</> : "."}</p>
+                )}
+                {prop.description?.split("\n\n").map((p) => (
+                  <p key={p} className="whitespace-pre-line">
+                    {inline(p)}
+                  </p>
+                ))}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/registry/registry.generated.tsx

@@ -0,0 +1,9 @@
+"use client";
+// A placeholder so the blocks typecheck in the registry. `designtools-blocks map` writes
+// the real one into a project, from its manifest.
+import type { ComponentType } from "react";
+
+export const components: Record<string, ComponentType<any>> = {};
+export const examples: Record<string, Record<string, unknown>> = {};
+export const patterns: Record<string, Record<string, unknown>> = {};
+export const assets: Record<string, string | { src: string }> = {};

package/registry/rule.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+import { Tabs } from "@base-ui/react/tabs";
+import type { ReactNode } from "react";
+import { CodeView } from "./code-view";
+import { ruleMarkdown } from "./lib/markdown";
+import type { RuleEntry } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+import { inline, Prose } from "./lib/text";
+
+const tab =
+  "-mb-px border-b-2 border-transparent px-1 pb-2 text-sm text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-[active]:border-primary data-[active]:font-medium data-[active]:text-canvas-foreground";
+
+/**
+ * One rule, brand or interface, written for people: the statement, the line it
+ * draws, what it applies to, the check that proves it. The second tab is the
+ * same rule as an agent reads it. Pass a demonstration as children where the
+ * rule needs persuading.
+ */
+export function Rule({ rule, children }: { rule: RuleEntry; children?: ReactNode }) {
+  const facts: [string, ReactNode][] = [];
+  if (rule.threshold) facts.push(["Threshold", rule.threshold]);
+  if (rule.appliesTo?.length) facts.push(["Applies to", rule.appliesTo.join(", ")]);
+  if (rule.exceptions?.length) facts.push(["Exceptions", rule.exceptions.join("; ")]);
+  if (rule.tokens?.length)
+    facts.push([
+      "Tokens",
+      rule.tokens.map((t) => (
+        <code key={t} className="mr-1 font-mono text-xs">
+          {t}
+        </code>
+      )),
+    ]);
+  if (rule.check)
+    facts.push([
+      "Checked by",
+      <>
+        {rule.check.kind}
+        {rule.check.ref && (
+          <>
+            {" "}
+            <code className="font-mono text-xs">{rule.check.ref}</code>
+          </>
+        )}
+        {rule.check.description && <>. {inline(rule.check.description)}</>}
+      </>,
+    ]);
+
+  return (
+    <article id={rule.id} data-slot="rule" className="flex scroll-mt-8 flex-col gap-4 rounded-lg border border-border p-5">
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <h3 className="text-lg font-semibold">
+          <a href={`#${rule.id}`} className="hover:underline">
+            {rule.title}
+          </a>
+        </h3>
+        <span className="flex items-center gap-2">
+          <span className="text-xs text-muted-foreground">{rule.kind}</span>
+          <StatusBadge status={rule.status} />
+        </span>
+      </header>
+      <Tabs.Root defaultValue="rendered" className="flex flex-col gap-4">
+        <Tabs.List aria-label={`${rule.title}, two ways`} className="flex gap-6 border-b border-border">
+          <Tabs.Tab value="rendered" className={tab}>
+            Rendered
+          </Tabs.Tab>
+          <Tabs.Tab value="agent" className={tab}>
+            As an agent reads it
+          </Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="rendered" className="flex flex-col gap-4">
+          <p data-slot="rule-statement" className="text-base">
+            {inline(rule.statement)}
+          </p>
+          {facts.length > 0 && (
+            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[8rem_1fr]">
+              {facts.map(([term, detail]) => (
+                <div key={term} className="contents">
+                  <dt className="font-medium">{term}</dt>
+                  <dd className="text-muted-foreground">{detail}</dd>
+                </div>
+              ))}
+            </dl>
+          )}
+          {rule.rationale && (
+            <div className="flex max-w-prose flex-col gap-2 text-sm text-muted-foreground">
+              <Prose text={rule.rationale} />
+            </div>
+          )}
+          {children && <div data-slot="rule-demonstration">{children}</div>}
+        </Tabs.Panel>
+        <Tabs.Panel value="agent">
+          <CodeView code={ruleMarkdown(rule)} lang="markdown" label="As an agent reads it" wrap />
+        </Tabs.Panel>
+      </Tabs.Root>
+    </article>
+  );
+}