@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/dist/vite/registry.js

@@ -0,0 +1,70 @@
+/// <reference types="node" />
+// `virtual:design-hub/registry`: the project's prototypes and walkthroughs as
+// a module the hub imports. The hub's own code lives in this package, so it
+// cannot glob the project; this plugin scans the project's folders instead
+// and writes the imports the browser index and the loader need, each on an
+// absolute path. A folder that appears or disappears invalidates the module
+// and reloads the page, so a new prototype shows without a restart.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { SLUG } from '../core/feature.js';
+const REGISTRY_ID = 'virtual:design-hub/registry';
+const RESOLVED = `\0${REGISTRY_ID}`;
+const dirs = (parent) => existsSync(parent)
+    ? readdirSync(parent, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && SLUG.test(d.name))
+        .map((d) => d.name)
+        .sort()
+    : [];
+/** The prototype folders: kebab-case, with a README. `guide` is the walkthrough route, never a prototype. */
+export const prototypeSlugs = (prototypes) => dirs(prototypes).filter((slug) => slug !== 'guide' && existsSync(join(prototypes, slug, 'README.md')));
+/** The features with a walkthrough at docs/sprints/<feature>/guide.md. */
+export const guideFeatures = (sprints) => dirs(sprints).filter((feature) => existsSync(join(sprints, feature, 'guide.md')));
+const entry = (key, path, query = '') => `  ${JSON.stringify(key)}: () => import(${JSON.stringify(path + query)}),`;
+export function registrySource(root) {
+    const prototypes = join(root, 'prototypes');
+    const sprints = join(root, 'docs', 'sprints');
+    const slugs = prototypeSlugs(prototypes);
+    const readmes = slugs.map((slug, i) => `import readme${i} from ${JSON.stringify(`${join(prototypes, slug, 'README.md')}?raw`)};`);
+    const modules = slugs
+        .filter((slug) => existsSync(join(prototypes, slug, 'index.tsx')))
+        .map((slug) => entry(slug, join(prototypes, slug, 'index.tsx')));
+    const guides = guideFeatures(sprints).map((feature) => entry(feature, join(sprints, feature, 'guide.md'), '?doc'));
+    return [
+        ...readmes,
+        `export const readmes = {\n${slugs.map((slug, i) => `  ${JSON.stringify(slug)}: readme${i},`).join('\n')}\n};`,
+        `export const modules = {\n${modules.join('\n')}\n};`,
+        `export const guideDocs = {\n${guides.join('\n')}\n};`,
+        '',
+    ].join('\n');
+}
+const REGISTRY_FILE = /\/(README\.md|index\.tsx|guide\.md)$/;
+export function registry(root) {
+    const prototypes = join(root, 'prototypes');
+    const sprints = join(root, 'docs', 'sprints');
+    return {
+        name: 'design-hub-registry',
+        resolveId(id) {
+            return id === REGISTRY_ID ? RESOLVED : null;
+        },
+        load(id) {
+            return id === RESOLVED ? registrySource(root) : null;
+        },
+        configureServer(server) {
+            server.watcher.add([prototypes, sprints]);
+            const refresh = (path) => {
+                if (!path.startsWith(prototypes) && !path.startsWith(sprints))
+                    return;
+                const mod = server.moduleGraph.getModuleById(RESOLVED);
+                if (mod)
+                    server.moduleGraph.invalidateModule(mod);
+                server.ws.send({ type: 'full-reload' });
+            };
+            // A folder coming or going, or one of the three files the registry lists, changes what the index shows.
+            server.watcher.on('addDir', refresh);
+            server.watcher.on('unlinkDir', refresh);
+            server.watcher.on('add', (path) => REGISTRY_FILE.test(path) && refresh(path));
+            server.watcher.on('unlink', (path) => REGISTRY_FILE.test(path) && refresh(path));
+        },
+    };
+}

package/kit/Icon.tsx

@@ -0,0 +1,39 @@
+import { type IconName, icons } from './icons';
+
+export type { IconName };
+
+type Props = { name: IconName; size?: number; className?: string; label?: string };
+
+function geometry(name: IconName, size: number) {
+  const icon = icons[name];
+  const [, , w, h] = icon.vb.split(' ').map(Number);
+  return { icon, width: size, height: Math.round((size * h) / w), stroked: Boolean(icon.rootStroke) };
+}
+
+export function Icon({ name, size = 20, className, label }: Props) {
+  const { icon, width, height, stroked } = geometry(name, size);
+  const stroke = stroked ? { stroke: 'currentColor', strokeWidth: 2 } : {};
+  return (
+    <svg
+      className={className ? `icon ${className}` : 'icon'}
+      width={width}
+      height={height}
+      viewBox={icon.vb}
+      fill="none"
+      {...stroke}
+      role={label ? 'img' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      focusable="false"
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted, inlined from @kit/icons
+      dangerouslySetInnerHTML={{ __html: icon.inner }}
+    />
+  );
+}
+
+// The same decorative icon as markup, for the few places the kit writes DOM outside React.
+export function iconMarkup(name: IconName, size = 20) {
+  const { icon, width, height, stroked } = geometry(name, size);
+  const stroke = stroked ? ' stroke="currentColor" stroke-width="2"' : '';
+  return `<svg class="icon" width="${width}" height="${height}" viewBox="${icon.vb}" fill="none"${stroke} aria-hidden="true" focusable="false">${icon.inner}</svg>`;
+}

package/kit/Space.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+import './space.css';
+import { ViewTools } from './ViewTools';
+
+type Props = {
+  title: string;
+  lede?: ReactNode;
+  width?: 'narrow' | 'wide' | 'full';
+  tools?: boolean;
+  children: ReactNode;
+};
+
+// The low-gravity space: one thing on a quiet canvas, no product around it.
+export function Space({ title, lede, width = 'wide', tools = true, children }: Props) {
+  return (
+    <main className="space" data-width={width}>
+      <header className="space-head">
+        <h1 className="space-title">{title}</h1>
+        {lede ? <p className="space-lede">{lede}</p> : null}
+      </header>
+      {children}
+      {tools ? <ViewTools /> : null}
+    </main>
+  );
+}

package/kit/Variants.tsx

@@ -0,0 +1,134 @@
+import { type ComponentType, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import './harness.css';
+
+type Props = {
+  options: Record<string, ComponentType>;
+  replay?: boolean;
+  onReplay?: () => void;
+  position?: 'bottom' | 'top';
+};
+
+const POPUPS = '[role="menu"], [role="listbox"], [role="dialog"]';
+const OWNS_KEYS = `input, textarea, select, [contenteditable=""], [contenteditable="true"], ${POPUPS}`;
+const HARNESS = '.dialkit-root, [data-harness], [data-lapse-panel]';
+
+const popupOpen = () =>
+  [...document.querySelectorAll(POPUPS)].some((el) => !el.closest(HARNESS) && el.getClientRects().length > 0);
+
+function initialIndex(count: number) {
+  const v = Number(new URLSearchParams(location.search).get('v'));
+  return Number.isInteger(v) && v >= 1 && v <= count ? v - 1 : 0;
+}
+
+const modified = (e: KeyboardEvent) => e.metaKey || e.ctrlKey || e.altKey || e.shiftKey;
+
+/** A bare key the page has not handled, outside any control or popup that owns keys. */
+const pickerOwns = (e: KeyboardEvent) =>
+  !modified(e) && !e.defaultPrevented && !(e.target as Element | null)?.closest?.(OWNS_KEYS) && !popupOpen();
+
+/** What a key does: 1 to N picks a variant, arrows step and wrap, R replays. */
+function keyTarget(key: string, index: number, count: number): number | 'again' | null {
+  const n = Number.parseInt(key, 10);
+  if (n >= 1 && n <= count) return n - 1;
+  if (key === 'ArrowRight') return (index + 1) % count;
+  if (key === 'ArrowLeft') return (index - 1 + count) % count;
+  return key.toLowerCase() === 'r' ? 'again' : null;
+}
+
+export function Variants({ options, replay = true, onReplay, position = 'bottom' }: Props) {
+  const names = Object.keys(options);
+  const [index, setIndex] = useState(() => initialIndex(names.length));
+  const [take, setTake] = useState(0);
+  const [ready, setReady] = useState(false);
+  const items = useRef<(HTMLButtonElement | null)[]>([]);
+  const highlight = useRef<HTMLSpanElement>(null);
+
+  const select = useCallback(
+    (i: number) => {
+      if (i < 0 || i >= names.length) return;
+      setIndex(i);
+      const url = new URL(location.href);
+      url.searchParams.set('v', String(i + 1));
+      history.replaceState(history.state, '', url);
+    },
+    [names.length],
+  );
+
+  const again = useCallback(() => (onReplay ? onReplay() : setTake((t) => t + 1)), [onReplay]);
+
+  useLayoutEffect(() => {
+    const move = () => {
+      const el = items.current[index];
+      if (!el || !highlight.current) return;
+      highlight.current.style.width = `${el.offsetWidth}px`;
+      highlight.current.style.transform = `translateX(${el.offsetLeft}px)`;
+    };
+    move();
+    addEventListener('resize', move);
+    return () => removeEventListener('resize', move);
+  }, [index]);
+
+  useEffect(() => {
+    const id = requestAnimationFrame(() => requestAnimationFrame(() => setReady(true)));
+    return () => cancelAnimationFrame(id);
+  }, []);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!pickerOwns(e)) return;
+      const next = keyTarget(e.key, index, names.length);
+      if (next === 'again') again();
+      else if (next !== null) select(next);
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [index, names.length, select, again]);
+
+  const Current = options[names[index]];
+
+  return (
+    <>
+      <Current key={`${index}:${take}`} />
+      {createPortal(
+        <nav
+          className="proto-picker"
+          aria-label="Prototype variants"
+          data-ready={ready ? '' : undefined}
+          data-position={position === 'top' ? 'top' : undefined}
+        >
+          <span ref={highlight} className="proto-picker-highlight" aria-hidden="true" />
+          {names.map((name, i) => (
+            <button
+              key={name}
+              ref={(el) => {
+                items.current[i] = el;
+              }}
+              type="button"
+              className="proto-picker-item"
+              data-active={i === index ? '' : undefined}
+              aria-current={i === index ? 'true' : undefined}
+              onClick={() => select(i)}
+            >
+              {name}
+            </button>
+          ))}
+          {replay && (
+            <>
+              <span className="proto-picker-divider" aria-hidden="true" />
+              <button
+                type="button"
+                className="proto-picker-item proto-picker-replay"
+                aria-label="Replay animation (R)"
+                onClick={again}
+              >
+                ↻
+              </button>
+            </>
+          )}
+        </nav>,
+        document.body,
+      )}
+    </>
+  );
+}

package/kit/ViewTools.tsx

@@ -0,0 +1,34 @@
+import { useDialKitController } from 'dialkit';
+import { useEffect, useLayoutEffect, useState } from 'react';
+import { ensureDialRoot } from './dials';
+import {
+  type Appearance,
+  prefersReducedMotion,
+  setAppearance,
+  setForceReduce,
+  setSpeed,
+  useAppearance,
+} from './prefs';
+
+const SPEEDS: Record<string, number> = { '1×': 1, '0.5×': 0.5, '0.25×': 0.25, '0.1×': 0.1 };
+
+// The View dials every prototype gets, in the Space and the app shell alike.
+// Theme mirrors @kit/prefs both ways, so a product setting or ?theme= moves the dial too.
+export function ViewTools() {
+  const appearance = useAppearance();
+  const [config] = useState(() => ({
+    theme: { type: 'select' as const, options: ['system', 'light', 'dark'], default: appearance },
+    reduceMotion: prefersReducedMotion(),
+    speed: { type: 'select' as const, options: Object.keys(SPEEDS), default: '1×' },
+  }));
+  useLayoutEffect(ensureDialRoot, []);
+  const { values: v, setValue } = useDialKitController('View', config, {
+    id: 'view',
+    defaultCollapsed: true,
+  });
+  useEffect(() => setAppearance(v.theme as Appearance), [v.theme]);
+  useEffect(() => setValue('theme', appearance), [appearance, setValue]);
+  useEffect(() => setForceReduce(v.reduceMotion), [v.reduceMotion]);
+  useEffect(() => setSpeed(SPEEDS[v.speed] ?? 1), [v.speed]);
+  return null;
+}

package/kit/base.css

@@ -0,0 +1,27 @@
+/* The floor every prototype stands on. Reduced motion and theme are
+   attributes on <html> (see prefs.ts), so CSS and JS read one source. */
+
+*, *::before, *::after { box-sizing: border-box; }
+/* The platform layer on a phone: no tap flash (every control has its own
+   press state), no pull-to-refresh or rubber band on an app shell. */
+html { height: 100%; -webkit-text-size-adjust: 100%; -webkit-tap-highlight-color: transparent; overscroll-behavior: none; }
+body { margin: 0; min-height: 100%; font-family: var(--font); font-size: 14px; line-height: 20px; color: var(--text-primary); background: var(--bg-primary); -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; overscroll-behavior: none; }
+h1, h2, h3, h4, h5, h6, p, dl, dd, ul, ol, figure, blockquote { margin: 0; }
+button, input, select, textarea { font: inherit; color: inherit; }
+a { color: inherit; }
+/* No 300ms tap wait on a control; a long press never selects a control's label. */
+button, a, input, select, textarea, [role="button"], [role="tab"], [role="menuitem"] { touch-action: manipulation; }
+button, [role="button"], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="option"] { user-select: none; -webkit-user-select: none; -webkit-touch-callout: none; }
+/* iOS zooms into any field under 16px and never zooms back: the type steps up where the pointer is a finger. */
+@media (pointer: coarse), (max-width: 767px) { input:not([type="checkbox"]):not([type="radio"]), select, textarea { font-size: 16px; } }
+.icon { display: inline-block; flex: none; vertical-align: middle; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+.num, .tabular { font-variant-numeric: tabular-nums; }
+
+/* A transparent outline still paints in forced-colors mode, where box-shadow does not. */
+:focus-visible { outline: 2px solid transparent; outline-offset: 2px; box-shadow: var(--focus-ring); }
+
+/* Theme swaps land in one frame instead of every fill easing at once. */
+.no-tx, .no-tx *, .no-tx *::before, .no-tx *::after { transition: none !important; }
+
+:root[data-motion="reduce"] { scroll-behavior: auto; }

package/kit/dials.css

@@ -0,0 +1,98 @@
+/* DialKit is harness chrome: the hub's Geist and Geist Mono, not the
+   library's system-ui and not the project's face. */
+.dialkit-root, .dialkit-shortcut-pill, .dialkit-version-overlay { font-family: var(--sys-font); }
+.dialkit-image-control, .dialkit-image-popover { font-family: var(--sys-font); }
+:is(.dialkit-slider-value, .dialkit-slider-input, .dialkit-pad-value, .dialkit-color-value, .dialkit-color-css-input, .dialkit-shortcuts-row-key, .dialkit-timeline-time, .dialkit-timeline-tick-label, .dialkit-timeline-loop-infinity, .dialkit-timeline-clip-duration, .dialkit-timeline-playhead-flag) { font-family: var(--sys-font-mono); }
+
+/* The dial hint: one tooltip for every DialKit row that has one, drawn in the
+   panel's own dark material. Fixed under the row, fades and settles 2px. */
+.dial-hint {
+  position: fixed;
+  z-index: 2147483647;
+  max-width: 260px;
+  padding: 6px 10px;
+  border-radius: 6px;
+  background: var(--harness-bg);
+  color: var(--harness-fg);
+  border: 1px solid var(--harness-border);
+  box-shadow: var(--harness-shadow);
+  font: 500 12px/16px var(--sys-font);
+  letter-spacing: 0;
+  text-wrap: pretty;
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(-2px) scale(0.98);
+  transition: opacity 125ms var(--ease-out), transform 125ms var(--ease-out);
+}
+.dial-hint.is-on { opacity: 1; transform: none; }
+.dial-hint:not(.is-on) { transition-duration: 90ms; }
+:root[data-motion="reduce"] .dial-hint { transform: none; transition: opacity 120ms var(--ease-hover); }
+
+/* The walkthrough link: the panel's last row, drawn as one of DialKit's own
+   buttons so it reads as part of the panel, with the arrow that says new tab. */
+.dial-guide {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin: 12px 0 0;
+  padding: 10px 16px;
+  border-radius: var(--dial-radius);
+  background: var(--dial-surface);
+  color: var(--dial-text-secondary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  font-family: inherit;
+  text-decoration: none;
+  transition: background-color var(--dur-hover) var(--ease-hover), color var(--dur-hover) var(--ease-hover), transform var(--dur-press-out) var(--ease-press);
+}
+.dial-guide:hover { background: var(--dial-surface-hover); color: var(--dial-text-primary); }
+.dial-guide:active { transform: scale(0.97); }
+.dial-guide:focus-visible { outline: 2px solid var(--dial-focus-ring); outline-offset: -2px; }
+:root[data-motion="reduce"] .dial-guide:active { transform: none; }
+/* The panel has no bottom padding, so the last row brings its own. */
+.dialkit-folder-root > .dialkit-folder-content:has(> .dial-guide) { padding-bottom: 12px; }
+
+/* DialKit draws Copy parameters and Save version at the top of every group,
+   inside its sticky header. Here they close the group instead: the header
+   gives up its box so its title and the toolbar can be ordered around the
+   controls, the title keeps the sticky job, and DialKit's own fold still
+   finds the toolbar where it left it. */
+.dialkit-panel .dialkit-folder.dialkit-folder-section { display: flex; flex-direction: column; }
+.dialkit-panel .dialkit-folder.dialkit-folder-section > .dialkit-folder-header { display: contents; }
+.dialkit-panel .dialkit-folder.dialkit-folder-section > .dialkit-folder-header > .dialkit-folder-header-top {
+  order: 0;
+  position: sticky;
+  top: var(--dial-panel-header-height, 0px);
+  z-index: 2;
+  background: var(--dial-glass-bg);
+  cursor: pointer;
+  user-select: none;
+}
+.dialkit-panel .dialkit-folder.dialkit-folder-section > .dialkit-folder-header > .dialkit-folder-header-top::before {
+  content: '';
+  position: absolute;
+  inset: 0 -12px;
+  z-index: -1;
+  background: var(--dial-glass-bg);
+  pointer-events: none;
+}
+.dialkit-panel .dialkit-folder.dialkit-folder-section > .dialkit-folder-content { order: 1; }
+.dialkit-panel .dialkit-folder.dialkit-folder-section > .dialkit-folder-header > .dialkit-panel-section-toolbar-clip { order: 2; }
+.dialkit-panel .dialkit-folder-section > .dialkit-folder-header > .dialkit-panel-section-toolbar-clip > .dialkit-panel-section-toolbar {
+  padding-top: 0;
+  padding-bottom: 4px;
+}
+.dialkit-panel .dialkit-folder-section { --dial-section-header-height: 44px; }
+/* Save version (the version gallery) is the group's first control; it goes
+   last, with its divider turned over to sit above it. */
+.dialkit-panel .dialkit-folder-section .dialkit-folder-inner > .dialkit-versions-host { order: 1; }
+.dialkit-panel .dialkit-folder-section .dialkit-versions {
+  padding-bottom: 0;
+  margin-bottom: 0;
+  border-bottom: 0;
+  padding-top: 12px;
+  margin-top: 4px;
+  border-top: 1px solid var(--dial-border);
+}