@hraness/design-kit 0.31.1

package/src/react/keyboard-shortcuts.ts

@@ -0,0 +1,228 @@
+"use client";
+
+import { useEffect, useRef, type RefObject } from "react";
+
+const interactiveTargetSelector = [
+  "a[href]",
+  "area[href]",
+  "button",
+  "input",
+  "select",
+  "summary",
+  "textarea",
+  "[contenteditable]:not([contenteditable='false'])",
+  "[role='button']",
+  "[role='checkbox']",
+  "[role='combobox']",
+  "[role='gridcell']",
+  "[role='link']",
+  "[role='menuitem']",
+  "[role='option']",
+  "[role='radio']",
+  "[role='slider']",
+  "[role='spinbutton']",
+  "[role='switch']",
+  "[role='tab']",
+  "[role='textbox']",
+  "[tabindex]:not([tabindex='-1'])",
+].join(",");
+
+const textEntryTargetSelector = [
+  "input:not([type='button']):not([type='checkbox']):not([type='color']):not([type='file']):not([type='hidden']):not([type='image']):not([type='radio']):not([type='range']):not([type='reset']):not([type='submit'])",
+  "select",
+  "textarea",
+  "[contenteditable]:not([contenteditable='false'])",
+  "[role='combobox']",
+  "[role='textbox']",
+].join(",");
+
+type ClosestEventTarget = EventTarget & {
+  closest(selectors: string): Element | null;
+};
+
+function hasClosest(target: EventTarget | null): target is ClosestEventTarget {
+  return target !== null && "closest" in target && typeof target.closest === "function";
+}
+
+export function isKeyboardInteractionTarget(target: EventTarget | null): boolean {
+  return hasClosest(target) && target.closest(interactiveTargetSelector) !== null;
+}
+
+export function isKeyboardTextEntryTarget(target: EventTarget | null): boolean {
+  return hasClosest(target) && target.closest(textEntryTargetSelector) !== null;
+}
+
+export type KeyboardShortcutEvent = Pick<
+  KeyboardEvent,
+  | "altKey"
+  | "ctrlKey"
+  | "defaultPrevented"
+  | "isComposing"
+  | "key"
+  | "metaKey"
+  | "repeat"
+  | "shiftKey"
+>;
+
+export interface KeyboardShortcutDefinition {
+  readonly allowRepeat?: boolean;
+  readonly allowWhenEditable?: boolean;
+  readonly allowWhenInteractive?: boolean;
+  /**
+   * Grants a matched shortcut to one explicitly recognized, non-editable
+   * interactive target without opening the shortcut to every control.
+   */
+  readonly allowWhenInteractiveTarget?: (
+    target: EventTarget | null,
+  ) => boolean;
+  readonly altKey?: boolean;
+  readonly ctrlKey?: boolean;
+  readonly id: string;
+  readonly isDisabled?: boolean;
+  readonly key: string;
+  readonly metaKey?: boolean;
+  readonly shiftKey?: boolean;
+}
+
+export interface KeyboardShortcutBinding extends KeyboardShortcutDefinition {
+  readonly onAction: (event: KeyboardEvent) => void;
+}
+
+export type KeyboardShortcutDecision =
+  | {
+      readonly bindingId: string;
+      readonly bindingIndex: number;
+      readonly kind: "handle";
+    }
+  | {
+      readonly kind: "ignore";
+      readonly reason:
+        | "composing"
+        | "default-prevented"
+        | "disabled"
+        | "editable-target"
+        | "interactive-target"
+        | "no-match"
+        | "repeat";
+    };
+
+export interface KeyboardShortcutContext {
+  readonly isDisabled?: boolean;
+  readonly isEditableTarget?: boolean;
+  readonly isInteractiveTarget?: boolean;
+  readonly target?: EventTarget | null;
+}
+
+function normalizedKey(key: string): string {
+  switch (key) {
+    case "Esc":
+      return "Escape";
+    case "Left":
+      return "ArrowLeft";
+    case "Right":
+      return "ArrowRight";
+    case "Up":
+      return "ArrowUp";
+    case "Down":
+      return "ArrowDown";
+    case "Space":
+    case "Spacebar":
+      return " ";
+    default:
+      return key.length === 1 ? key.toLocaleLowerCase("en-US") : key;
+  }
+}
+
+export function matchesKeyboardShortcut(
+  event: KeyboardShortcutEvent,
+  shortcut: KeyboardShortcutDefinition,
+): boolean {
+  return (
+    normalizedKey(event.key) === normalizedKey(shortcut.key) &&
+    event.altKey === (shortcut.altKey ?? false) &&
+    event.ctrlKey === (shortcut.ctrlKey ?? false) &&
+    event.metaKey === (shortcut.metaKey ?? false) &&
+    event.shiftKey === (shortcut.shiftKey ?? false)
+  );
+}
+
+export function decideKeyboardShortcut(
+  shortcuts: readonly KeyboardShortcutDefinition[],
+  event: KeyboardShortcutEvent,
+  context: KeyboardShortcutContext = {},
+): KeyboardShortcutDecision {
+  if (context.isDisabled === true) return { kind: "ignore", reason: "disabled" };
+  if (event.defaultPrevented) return { kind: "ignore", reason: "default-prevented" };
+  if (event.isComposing) return { kind: "ignore", reason: "composing" };
+
+  let suppressedReason: Extract<KeyboardShortcutDecision, { readonly kind: "ignore" }>["reason"] | null = null;
+  for (const [bindingIndex, shortcut] of shortcuts.entries()) {
+    if (shortcut.isDisabled === true || !matchesKeyboardShortcut(event, shortcut)) continue;
+    if (event.repeat && shortcut.allowRepeat !== true) {
+      suppressedReason ??= "repeat";
+      continue;
+    }
+    if (
+      context.isEditableTarget === true &&
+      shortcut.allowWhenEditable !== true
+    ) {
+      suppressedReason ??= "editable-target";
+      continue;
+    }
+    if (
+      context.isInteractiveTarget === true &&
+      context.isEditableTarget !== true &&
+      shortcut.allowWhenInteractive !== true &&
+      shortcut.allowWhenInteractiveTarget?.(context.target ?? null) !== true
+    ) {
+      suppressedReason ??= "interactive-target";
+      continue;
+    }
+    return { bindingId: shortcut.id, bindingIndex, kind: "handle" };
+  }
+
+  return { kind: "ignore", reason: suppressedReason ?? "no-match" };
+}
+
+export interface UseKeyboardShortcutsOptions {
+  readonly isDisabled?: boolean;
+  readonly scopeRef?: RefObject<HTMLElement | null>;
+}
+
+function isNode(target: EventTarget | null): target is Node {
+  return target !== null && typeof Node !== "undefined" && target instanceof Node;
+}
+
+/** Installs guarded document shortcuts without stealing keys from focused widgets by default. */
+export function useKeyboardShortcuts(
+  bindings: readonly KeyboardShortcutBinding[],
+  options: UseKeyboardShortcutsOptions = {},
+): void {
+  const latestRef = useRef({ bindings, isDisabled: options.isDisabled ?? false });
+  latestRef.current = { bindings, isDisabled: options.isDisabled ?? false };
+  const scopeRef = options.scopeRef;
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (scopeRef !== undefined) {
+        const scope = scopeRef.current;
+        if (scope === null || !isNode(event.target) || !scope.contains(event.target)) return;
+      }
+
+      const current = latestRef.current;
+      const decision = decideKeyboardShortcut(current.bindings, event, {
+        isDisabled: current.isDisabled,
+        isEditableTarget: isKeyboardTextEntryTarget(event.target),
+        isInteractiveTarget: isKeyboardInteractionTarget(event.target),
+        target: event.target,
+      });
+      if (decision.kind === "ignore") return;
+
+      event.preventDefault();
+      current.bindings[decision.bindingIndex]?.onAction(event);
+    };
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [scopeRef]);
+}

package/src/react/lantern-material-gallery.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+import { Button, TextField } from "@hraness/ui";
+import { useId, useState } from "react";
+
+import { getDesignPaletteTheme } from "../palette-themes.js";
+import { lanternControlStyles } from "./lantern-material.stylex.js";
+import { SyntaxCode } from "./syntax-code.js";
+import { TopBar } from "./surfaces.js";
+
+// Patterns are retired: every accepted value paints the flat palette plane.
+// The samples keep the finite vocabulary visible so existing markup can be
+// checked against it, and show that only the palette changes.
+const materialPatterns = [
+  { pattern: "cells", palette: "paper", label: "cells", description: "Retired. Renders as a flat Paper plane." },
+  { pattern: "weave", palette: "gruvbox", label: "weave", description: "Retired. Renders as a flat Gruvbox plane." },
+  { pattern: "contour", palette: "rose-pine", label: "contour", description: "Retired. Renders as a flat Rosé Pine plane." },
+  { pattern: "mesh", palette: "tokyo-night", label: "mesh", description: "Retired. Renders as a flat Tokyo Night plane." },
+  { pattern: "none", palette: "paper", label: "none", description: "The default: an uninterrupted surface." },
+] as const;
+
+const exampleNotes = [
+  { title: "A place for unfinished thoughts", detail: "Personal · edited today" },
+  { title: "What we learned on the walk", detail: "Shared · edited yesterday" },
+  { title: "Ideas for a slower morning", detail: "Personal · edited Monday" },
+] as const;
+
+function MaterialWorkspace({ mode }: Readonly<{ mode: "light" | "dark" }>) {
+  const id = useId();
+  const [query, setQuery] = useState("");
+  const [personalOnly, setPersonalOnly] = useState(false);
+  const [saved, setSaved] = useState(false);
+  const notes = exampleNotes.filter((note) =>
+    note.title.toLowerCase().includes(query.toLowerCase())
+      && (!personalOnly || note.detail.startsWith("Personal")),
+  );
+
+  return (
+    <div
+      className={`design-gallery__lantern-wall hraness-material-wall ${getDesignPaletteTheme("paper", mode).className}`}
+      data-hraness-material="lantern"
+      data-hraness-theme="paper"
+      data-palette="paper"
+      data-theme={mode}
+      data-gallery-lantern={mode}
+    >
+      <div className="design-gallery__lantern-caption">
+        <h3>{mode === "light" ? "Daylight" : "Lamplight"}</h3>
+        <p>The same notebook in the Paper palette, light and dark.</p>
+      </div>
+      <div className="hraness-material-terminal">
+        <div className="hraness-material-terminal__bar">notebook · terminal</div>
+        <pre className="hraness-material-code" aria-label="Illustrative notebook command" tabIndex={0}><SyntaxCode code={'notebook search "a slower morning" --format markdown\n# One matching note, on your computer.'} language="shell" /></pre>
+      </div>
+      <div className="design-gallery__lantern-workspace hraness-material-pane" data-depth="raised">
+        <TopBar
+          className="hraness-material-chrome"
+          position="static"
+          surface="glass"
+          title="Your notebook"
+          actions={<span className="design-gallery__lantern-local">Local workspace</span>}
+        />
+        <div className="design-gallery__lantern-content">
+          <TextField
+            controlXstyle={lanternControlStyles.inset}
+            inputProps={{ id: `${id}-search` }}
+            label="Find a note"
+            onChange={setQuery}
+            placeholder="Search your notes"
+            value={query}
+          />
+          <div className="design-gallery__lantern-filter">
+            <Button
+              aria-pressed={personalOnly}
+              controlXstyle={[lanternControlStyles.edge, personalOnly && lanternControlStyles.selected]}
+              data-gallery-lantern-filter=""
+              onPress={() => setPersonalOnly(!personalOnly)}
+              size="compact"
+            >
+              Personal only
+            </Button>
+            <span aria-live="polite">{notes.length} {notes.length === 1 ? "note" : "notes"}</span>
+          </div>
+          <ul className="hraness-material-rows design-gallery__lantern-notes">
+            {notes.map((note) => (
+              <li key={note.title}>
+                <details className="hraness-material-disclosure">
+                  <summary>{note.title}</summary>
+                  <p>Illustrative note. Your words and decisions stay together here.</p>
+                </details>
+                <span>{note.detail}</span>
+              </li>
+            ))}
+          </ul>
+          {notes.length === 0 ? <p role="status">No notes match. Try a shorter search or turn off the personal filter.</p> : null}
+          <div className="design-gallery__lantern-save">
+            <Button
+              controlXstyle={lanternControlStyles.edge}
+              onPress={() => setSaved(true)}
+              variant="primary"
+            >
+              Save this view
+            </Button>
+            <span aria-live="polite">{saved ? "View saved for this example." : "Example content. Nothing leaves this page."}</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** Executable reference, with product-neutral illustrative content. */
+export function LanternMaterialGallery() {
+  const [plainSelected, setPlainSelected] = useState(true);
+  const [removed, setRemoved] = useState(false);
+  return (
+    <section className="design-gallery__section" id="lantern">
+      <h2>Lantern material</h2>
+      <p className="design-gallery__lantern-intro">Lantern gives reading surfaces a glowing edge and selected controls a warm fill.</p>
+      <div className="design-gallery__lantern-pair">
+        <MaterialWorkspace mode="light" />
+        <MaterialWorkspace mode="dark" />
+      </div>
+      <h3>Patterns render as flat palette planes</h3>
+      <div className="design-gallery__lantern-pair">
+        {materialPatterns.map(({ pattern, palette, label, description }) => (
+          <div
+            className={`design-gallery__lantern-wall hraness-material-wall ${getDesignPaletteTheme(palette, "light").className}`}
+            data-gallery-pattern={pattern}
+            data-hraness-material="lantern"
+            data-hraness-pattern={pattern}
+            data-palette={palette}
+            data-theme="light"
+            key={pattern}
+          >
+            <div className="design-gallery__lantern-caption"><h4>{label}</h4><p>{description}</p></div>
+          </div>
+        ))}
+      </div>
+      <div
+        className={`design-gallery__lantern-states hraness-material-pane ${getDesignPaletteTheme("paper", "light").className}`}
+        data-hraness-material="lantern"
+        data-hraness-theme="paper"
+        data-palette="paper"
+        data-theme="light"
+      >
+        <h3>Controls keep their meaning</h3>
+        <p>Keyboard focus, errors, and unavailable actions stay clearly marked under Lantern.</p>
+        <div className="design-gallery__lantern-state-actions">
+          <Button controlXstyle={lanternControlStyles.edge} isDisabled>Unavailable action</Button>
+          <Button controlXstyle={lanternControlStyles.edge} isPending>Saving changes</Button>
+          <Button controlXstyle={lanternControlStyles.edge} onPress={() => setRemoved(true)} variant="danger">Remove example</Button>
+          <button className="design-gallery__lantern-plain hraness-material-choice" aria-pressed={plainSelected} onClick={() => setPlainSelected(!plainSelected)} type="button">HTML selection</button>
+        </div>
+        <p aria-live="polite">{removed ? "Example removed for this visit." : ""}</p>
+        <TextField
+          controlXstyle={lanternControlStyles.inset}
+          defaultValue=""
+          errorMessage="Give the notebook a name before saving."
+          isInvalid
+          label="Notebook name"
+        />
+      </div>
+    </section>
+  );
+}

package/src/react/lantern-material.stylex.ts

@@ -0,0 +1,39 @@
+import * as stylex from "@stylexjs/stylex";
+
+const forcedColors = "@media (forced-colors: active)";
+const disabled = ':is(:disabled, [data-disabled], [aria-disabled="true"])';
+const disabledField = ':has(input:disabled, textarea:disabled)';
+
+/** Paint adapters for the existing primitive's controlXstyle seam.
+ * Keep focus, geometry, error, pending and disabled behavior with @hraness/ui. */
+export const lanternControlStyles = stylex.create({
+  edge: {
+    backgroundImage: {
+      default: "linear-gradient(to bottom, var(--hraness-material-edge), transparent 2px)",
+      [disabled]: "none",
+      [forcedColors]: "none",
+    },
+  },
+  inset: {
+    backgroundImage: {
+      default: "linear-gradient(to bottom, var(--hraness-material-shade), transparent 4px)",
+      [disabledField]: "none",
+      [forcedColors]: "none",
+    },
+  },
+  selected: {
+    backgroundColor: {
+      default: "var(--hraness-material-warm-plane)",
+      [forcedColors]: "Highlight",
+    },
+    backgroundImage: {
+      default: "linear-gradient(to top, var(--hraness-material-warm), var(--hraness-material-warm) 2px, transparent 2px)",
+      [disabled]: "none",
+      [forcedColors]: "none",
+    },
+    color: {
+      default: "var(--hraness-material-ink)",
+      [forcedColors]: "HighlightText",
+    },
+  },
+});

package/src/react/launch-beats.tsx

@@ -0,0 +1,73 @@
+import type { ReactNode } from "react";
+import { assertLaunchBeats, type LaunchBeat } from "../launch.js";
+import { ArticleFigure, type ArticleFigureKind } from "./article.js";
+
+/*
+ * Server-safe launch post body: one section per beat, each with its own
+ * anchor, heading, paragraph, and visual. Styled by plain-publication.css
+ * inside a MarketingArticle.
+ */
+
+const HEADING_TAGS = { 2: "h2", 3: "h3", 4: "h4" } as const;
+
+function figureKind(beat: LaunchBeat): ArticleFigureKind {
+  switch (beat.visual.kind) {
+    case "mockup":
+      return "illustration";
+    case "clip":
+      return "recording";
+    case "diagram":
+      return "diagram";
+  }
+}
+
+/** The anchor id a beat renders, such as `beat-status`. Social posts can deep-link to it. */
+export function launchBeatAnchor(beat: Pick<LaunchBeat, "id">): string {
+  return `beat-${beat.id}`;
+}
+
+/**
+ * The beats of an "Introducing a product" post, in order. Each beat renders
+ * as a section with a `#beat-<id>` anchor, its headline, its post as the
+ * paragraph, and exactly one visual from `renderVisual`, captioned with the
+ * beat's alt text and labelled by kind. Pass beats already resolved against
+ * the launch facts.
+ */
+export function LaunchBeats({
+  beats,
+  className,
+  detailLabel = "More on this",
+  headingLevel = 2,
+  renderVisual,
+}: Readonly<{
+  beats: readonly LaunchBeat[];
+  className?: string;
+  /** Link text for a beat's `detailHref`. */
+  detailLabel?: string;
+  headingLevel?: 2 | 3 | 4;
+  /** Returns the one visual for a beat: a mockup, a video, or a diagram image. */
+  renderVisual: (beat: LaunchBeat) => ReactNode;
+}>) {
+  assertLaunchBeats(beats);
+  const Heading = HEADING_TAGS[headingLevel];
+  if (Heading === undefined) throw new RangeError("Launch beat heading level must be 2 to 4.");
+  return (
+    <div className={["plain-publication__beats", className].filter(Boolean).join(" ")} data-hraness-launch-beats="">
+      {beats.map((beat) => {
+        const anchor = launchBeatAnchor(beat);
+        const visual = renderVisual(beat);
+        if (visual === null || visual === undefined || visual === false) throw new RangeError(`Launch beat ${JSON.stringify(beat.id)} needs a visual.`);
+        return (
+          <section aria-labelledby={`${anchor}-heading`} className="plain-publication__beat" data-part={beat.part} id={anchor} key={beat.id}>
+            <Heading id={`${anchor}-heading`}>{beat.headline}</Heading>
+            <p>{beat.post}</p>
+            <ArticleFigure caption={beat.alt} kind={figureKind(beat)}>{visual}</ArticleFigure>
+            {beat.detailHref === undefined ? null : (
+              <p className="plain-publication__beat-detail"><a href={beat.detailHref}>{detailLabel}</a></p>
+            )}
+          </section>
+        );
+      })}
+    </div>
+  );
+}

package/src/react/navigation-rail.stylex.ts

@@ -0,0 +1,130 @@
+import * as stylex from "@stylexjs/stylex";
+
+const hovered = ":is([data-hovered], :hover)";
+const focusVisible = ":is([data-focus-visible], :focus-visible)";
+
+export const navigationRailStyles = stylex.create({
+  item: {
+    alignItems: "center",
+    borderRadius: "var(--control-radius)",
+    color: "var(--muted)",
+    display: "grid",
+    gap: "var(--space-2)",
+    gridTemplateColumns: "auto minmax(0, 1fr) auto",
+    "min-block-size": "var(--interactive-target-min)",
+    padding: "var(--space-2) var(--space-3)",
+    textDecoration: "none",
+  },
+  itemActive: {
+    backgroundAttachment: { default: "scroll", [hovered]: "scroll" },
+    backgroundClip: { default: "border-box", [hovered]: "border-box" },
+    backgroundImage: { default: "none", [hovered]: "none" },
+    backgroundOrigin: { default: "padding-box", [hovered]: "padding-box" },
+    backgroundPosition: { default: "0% 0%", [hovered]: "0% 0%" },
+    backgroundRepeat: { default: "repeat", [hovered]: "repeat" },
+    backgroundSize: { default: "auto auto", [hovered]: "auto auto" },
+    backgroundColor: {
+      default: "var(--secondary)",
+      [hovered]: "var(--secondary)",
+    },
+    color: {
+      default: "var(--secondary-foreground)",
+      [hovered]: "var(--secondary-foreground)",
+    },
+  },
+  itemCopy: {
+    display: "grid",
+    gap: "0.125rem",
+    "min-inline-size": 0,
+  },
+  itemDescription: {
+    color: "var(--muted)",
+    fontSize: "var(--text-caption)",
+    overflowWrap: "anywhere",
+  },
+  itemIcon: {
+    display: "inline-grid",
+    placeItems: "center",
+  },
+  itemLabel: {
+    fontWeight: "var(--font-weight-medium)",
+    overflowWrap: "anywhere",
+  },
+  itemNativeInteractionFallbacks: {
+    backgroundAttachment: { default: null, [hovered]: "scroll" },
+    backgroundClip: { default: null, [hovered]: "border-box" },
+    backgroundImage: { default: null, [hovered]: "none" },
+    backgroundOrigin: { default: null, [hovered]: "padding-box" },
+    backgroundPosition: { default: null, [hovered]: "0% 0%" },
+    backgroundRepeat: { default: null, [hovered]: "repeat" },
+    backgroundSize: { default: null, [hovered]: "auto auto" },
+    backgroundColor: {
+      default: null,
+      [hovered]: "var(--surface-hover)",
+    },
+    color: {
+      default: null,
+      [hovered]: "var(--foreground)",
+    },
+    outlineColor: {
+      default: null,
+      [focusVisible]: "var(--focus)",
+    },
+    outlineOffset: {
+      default: null,
+      [focusVisible]: 2,
+    },
+    outlineStyle: {
+      default: null,
+      [focusVisible]: "solid",
+    },
+    outlineWidth: {
+      default: null,
+      [focusVisible]: 3,
+    },
+  },
+  navigation: {
+    alignContent: "start",
+    display: "grid",
+    flex: "1 1 auto",
+    gap: "var(--space-4)",
+    "min-block-size": 0,
+    overflow: "auto",
+    padding: "var(--space-3)",
+  },
+  rail: {
+    backgroundAttachment: "scroll",
+    backgroundClip: "border-box",
+    backgroundImage: "none",
+    backgroundOrigin: "padding-box",
+    backgroundPosition: "0% 0%",
+    backgroundRepeat: "repeat",
+    backgroundSize: "auto auto",
+    backgroundColor: "var(--surface)",
+    "block-size": "100%",
+    display: "flex",
+    flexDirection: "column",
+    "min-block-size": 0,
+  },
+  railEdge: {
+    flex: "0 0 auto",
+    padding: "var(--space-4)",
+  },
+  section: {
+    display: "grid",
+    gap: "var(--space-2)",
+  },
+  sectionItems: {
+    display: "grid",
+    gap: "var(--space-1)",
+  },
+  sectionTitle: {
+    color: "var(--muted)",
+    fontSize: "var(--text-caption)",
+    fontWeight: "var(--font-weight-medium)",
+    letterSpacing: "0.04em",
+    margin: 0,
+    "padding-inline": "var(--space-2)",
+    textTransform: "uppercase",
+  },
+});