@stonedogcode/style 0.9.0

package/src/components/TitleLogo.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import { log } from "../config/logger";
+import React from "react";
+import { styled } from "styled-system/jsx";
+import type { HTMLStyledProps } from "styled-system/types";
+
+/**
+ * A mark beside a wordmark, at one of three sizes.
+ *
+ * Copyright (C) 2026 StoneDogCode L.L.C. All rights reserved.
+ *
+ * ## Why this exists
+ *
+ * HopperGuard carries **nine** logo files — `logos/{elder,hopperguard,kids}/
+ * logo-{large,medium,small}-*.tsx` — that are ~95% identical markup differing
+ * only in size constants and colour tokens. NEH-287 names the consequence: the
+ * per-size numbers drifted apart, so the logo's proportions were not stable
+ * across breakpoints, and a fix had to be applied nine times or not at all.
+ * Optima Filings Cloud was about to become the tenth.
+ *
+ * So the *structure* lives here once and the *content* is passed in. This
+ * package owns shape and knows nothing about any brand — no artwork, no
+ * colours, no product names. `logo` and `title` are both `ReactNode`, which is
+ * what lets HopperGuard pass its two-part `HOPPER`+`Guard` wordmark (two fonts,
+ * two colour tokens, one letter-spacing) while Optima passes a plain string.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * **No trademark glyph.** The previous implementation nudged a `™` into place
+ * with hand-tuned pixel offsets that were different at every size — three magic
+ * pairs whose only job was to make one glyph land, and which a screen reader
+ * announced as "trade mark sign" on every page. NEH-287 moves that notice to
+ * the footer, where it is a stronger notice and read once. A caller that wants
+ * a symbol can put one in `title`; nothing here positions it.
+ *
+ * **No by-line.** Same issue: only one brand had one, and centring the column
+ * that held it pushed the wordmark visibly above the mark's optical centre.
+ * Provenance belongs beside the copyright, not in the chrome on every screen.
+ *
+ * With both gone the row is a mark and a single line of text, so
+ * `alignItems: center` centres it correctly with no compensating offset — which
+ * is the whole reason those offsets existed.
+ */
+
+/** The three rungs. Named, not numeric, so a caller cannot invent a tenth. */
+export const TITLE_LOGO_SIZES = ["small", "medium", "large"] as const;
+export type TitleLogoSize = (typeof TITLE_LOGO_SIZES)[number];
+
+export function isTitleLogoSize(value: unknown): value is TitleLogoSize {
+  return TITLE_LOGO_SIZES.includes(value as TitleLogoSize);
+}
+
+interface SizeMetrics {
+  /** Box the mark is given. Square: every mark here is a round or square badge. */
+  readonly mark: string;
+  /** Wordmark size. */
+  readonly title: string;
+  readonly subtitle: string;
+  readonly gap: string;
+}
+
+/**
+ * Every value is real CSS, applied inline — NOT a Panda token key.
+ *
+ * These are consumed as `style={{ … }}` because Panda cannot statically resolve
+ * a runtime Record lookup (see the render below). A token key like `"lg"` would
+ * be meaningless as an inline value, so the type scale is reached through the
+ * host's own custom properties instead, exactly as `fontSizeMap` does: the host
+ * that defines `--font-sizes-lg` gets its scale, and the fallback covers a host
+ * that defines nothing.
+ *
+ * rem throughout, never px. A logo pinned in px ignores the browser's own
+ * font-size setting — the affordance people with low vision actually reach for
+ * — and this is the one piece of chrome on every page.
+ */
+export const TITLE_LOGO_METRICS: Record<TitleLogoSize, SizeMetrics> = {
+  small: {
+    mark: "2rem",
+    title: "var(--font-sizes-lg, 1.125rem)",
+    subtitle: "var(--font-sizes-xs, 0.75rem)",
+    gap: "0.5rem",
+  },
+  medium: {
+    mark: "3rem",
+    title: "var(--font-sizes-2xl, 1.5rem)",
+    subtitle: "var(--font-sizes-sm, 0.875rem)",
+    gap: "0.75rem",
+  },
+  large: {
+    mark: "4.5rem",
+    title: "var(--font-sizes-4xl, 2.25rem)",
+    subtitle: "var(--font-sizes-md, 1rem)",
+    gap: "1rem",
+  },
+};
+
+const Row = styled("span", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    minWidth: 0,
+  },
+});
+
+const Mark = styled("span", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    flexShrink: 0,
+    // Anything handed in — an <img>, an <svg>, a self-sizing component — is
+    // contained rather than allowed to set the row's height. Without this a
+    // logo with its own intrinsic size silently drives the header's height and
+    // the three rungs stop meaning anything.
+    "& > *": { maxWidth: "100%", maxHeight: "100%" },
+    "& img, & svg": { width: "100%", height: "100%", objectFit: "contain" },
+  },
+});
+
+const TextColumn = styled("span", {
+  base: {
+    display: "inline-flex",
+    flexDirection: "column",
+    justifyContent: "center",
+    minWidth: 0,
+  },
+});
+
+export interface TitleLogoProps extends Omit<HTMLStyledProps<"span">, "title"> {
+  /** The wordmark. A string, or nodes when the brand styles it in parts. */
+  title: React.ReactNode;
+  /** The mark. Omit for a text-only lockup. */
+  logo?: React.ReactNode | undefined;
+  /** Optional second line. Prefer the footer for provenance — see the header. */
+  subtitle?: React.ReactNode | undefined;
+  size?: TitleLogoSize | undefined;
+  /**
+   * Accessible name for the lockup as a whole.
+   *
+   * Given, the row becomes a single labelled image to assistive tech and the
+   * decorative mark is hidden — otherwise a screen reader announces the mark
+   * and the wordmark as two separate things, which is one thing too many for a
+   * logo. Defaults to `title` when that is a plain string.
+   */
+  label?: string | undefined;
+}
+
+export const TitleLogo = React.forwardRef<HTMLSpanElement, TitleLogoProps>(
+  function TitleLogo(
+    { title, logo, subtitle, size = "medium", label, ...rest },
+    ref,
+  ) {
+    log.trace("TitleLogo rendered");
+
+    const metrics = TITLE_LOGO_METRICS[isTitleLogoSize(size) ? size : "medium"];
+    const accessibleName = label ?? (typeof title === "string" ? title : undefined);
+
+    return (
+      <Row
+        ref={ref}
+        // INLINE STYLE, not a Panda prop, and this is load-bearing.
+        //
+        // Panda finds styles by STATICALLY parsing source at the consumer's
+        // build. `gap={metrics.gap}` is a runtime lookup on a Record — Panda
+        // sees a non-literal, cannot resolve it, and emits no rule. The class
+        // still lands in the DOM, so it fails completely silently.
+        //
+        // Caught in optima-cloud-saas: the row rendered `gap: normal` and the
+        // mark at its natural 512px instead of 2rem, blowing the masthead out
+        // to 612px tall — while the literal styles in the `base` blocks below
+        // (display, alignItems, flexShrink, objectFit) all applied correctly.
+        // That split is the tell: literals extract, variables do not.
+        //
+        // Anything size-dependent is therefore inline. It also means this
+        // component cannot be broken by a consumer's `include` glob, which for
+        // a published design-system component is worth more than the styling
+        // indirection it gives up.
+        style={{ gap: metrics.gap, ...(rest.style ?? {}) }}
+        data-testid="title-logo"
+        data-size={size}
+        {...(accessibleName ? { role: "img", "aria-label": accessibleName } : {})}
+        {...rest}
+      >
+        {logo ? (
+          <Mark
+            data-testid="title-logo-mark"
+            style={{ width: metrics.mark, height: metrics.mark }}
+            // Hidden when the row already carries the name: announcing the mark
+            // separately would repeat it.
+            {...(accessibleName ? { "aria-hidden": true } : {})}
+          >
+            {logo}
+          </Mark>
+        ) : null}
+
+        <TextColumn>
+          <styled.span
+            data-testid="title-logo-title"
+            style={{ fontSize: metrics.title }}
+            fontWeight="600"
+            lineHeight="1.1"
+            letterSpacing="-0.01em"
+          >
+            {title}
+          </styled.span>
+          {subtitle ? (
+            <styled.span
+              data-testid="title-logo-subtitle"
+              style={{ fontSize: metrics.subtitle }}
+              lineHeight="1.2"
+              opacity={0.75}
+            >
+              {subtitle}
+            </styled.span>
+          ) : null}
+        </TextColumn>
+      </Row>
+    );
+  },
+);
+
+export default TitleLogo;

package/src/components/create-icon.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import React from "react";
+import StyledIcon, { type StyledIconProps } from "./StyledIcon";
+
+/**
+ * Build a named icon component from any node.
+ *
+ * An icon set is a few hundred near-identical wrappers, and hand-writing them
+ * is how a set drifts — one forgets to forward `size`, another hardcodes a
+ * colour, a third omits `displayName` and shows up as `Unknown` in every stack
+ * trace. This makes each one a single line and forces them to agree.
+ *
+ * ```tsx
+ * import { Home } from "lucide-react";
+ * export const StyledHome = createIcon("StyledHome", <Home />);
+ * ```
+ *
+ * The artwork stays yours: nothing about the icon set reaches this package, so
+ * a commercially licensed set can be wrapped in a private package while the
+ * components that lay it out stay open.
+ */
+export function createIcon(
+  displayName: string,
+  node: React.ReactNode,
+): React.FC<Omit<StyledIconProps, "icon" | "children">> {
+  const Icon: React.FC<Omit<StyledIconProps, "icon" | "children">> = (props) => (
+    <StyledIcon {...props} icon={node} />
+  );
+  Icon.displayName = displayName;
+  return Icon;
+}
+
+/**
+ * The same, for sets whose icons are components taking their own props —
+ * Lucide, Heroicons, react-icons, and anything else exporting one component per
+ * glyph.
+ *
+ * ```tsx
+ * import { Home } from "lucide-react";
+ * export const StyledHome = createIconFromComponent("StyledHome", Home);
+ * ```
+ *
+ * The wrapped component is rendered with `width`/`height` at 100% so it fills
+ * the box `size` establishes rather than fighting it — most sets default to
+ * 24px and would otherwise ignore the size prop entirely.
+ */
+export function createIconFromComponent<P extends object>(
+  displayName: string,
+  Component: React.ComponentType<P>,
+  componentProps?: P,
+): React.FC<Omit<StyledIconProps, "icon" | "children">> {
+  const Icon: React.FC<Omit<StyledIconProps, "icon" | "children">> = (props) => (
+    <StyledIcon
+      {...props}
+      icon={
+        <Component
+          {...({ width: "100%", height: "100%" } as unknown as P)}
+          {...(componentProps ?? ({} as P))}
+        />
+      }
+    />
+  );
+  Icon.displayName = displayName;
+  return Icon;
+}

package/src/components/create-intent-button.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import React from "react";
+import StyledButton, { type StyledButtonProps } from "./StyledButton";
+import { useDensity } from "../config/style-config";
+import { useIntentIcon, type IconIntent } from "../config/intent-icons";
+
+/**
+ * Builds an "intent button" — Save, Delete, Edit and the rest.
+ *
+ * Each is a `StyledButton` that already knows three things a caller would
+ * otherwise repeat: which icon to draw, what the label says, and what the
+ * spinner says while it works. The point is not to save typing; it is that
+ * every Delete button in a product is the same Delete button.
+ *
+ * The icon comes from the **intent registry**, not from a prop, so this package
+ * ships no artwork and each host supplies its own set — Font Awesome in
+ * HopperGuard, Lucide in optima-filings. A per-call-site `icon` prop still
+ * wins for the rare one-off.
+ *
+ * ## Compact density drops the label — and that used to lose the name
+ *
+ * At `compact`, these render icon-only. In the originating app that produced a
+ * button with **no text and no `aria-label`**, so a screen reader announced it
+ * as "button" — the same defect as NEH-226, except this one appeared and
+ * disappeared with a user preference, which is worse: it passes review at
+ * `normal` and fails for the user who chose `compact`.
+ *
+ * So when the label is hidden it becomes the accessible name. The visible text
+ * and the announced name are the same string either way, which is the point of
+ * WCAG 2.5.3 (Label in Name).
+ */
+
+export interface IntentButtonProps
+  extends Omit<StyledButtonProps, "leftIcon" | "children"> {
+  children?: React.ReactNode;
+  /**
+   * Force icon-only, or force the label on. Defaults to icon-only at `compact`
+   * density.
+   */
+  iconOnly?: boolean;
+  /** Override the registry for this one call site. */
+  icon?: React.ReactNode;
+}
+
+export interface IntentButtonSpec {
+  /** Component name — shows in React DevTools and stack traces. */
+  displayName: string;
+  /** Which registry entry to draw. */
+  intent: IconIntent;
+  /** Visible text, and the accessible name when the label is hidden. */
+  defaultLabel: string;
+  /** What the spinner says while `loading`. Prefer naming the action. */
+  loadText?: string;
+  /**
+   * Default hover/focus explanation.
+   *
+   * Deliberately more than the label repeated: "Delete" is the label, "Delete
+   * the item" is what the tooltip adds. A caller's own `tooltip` overrides.
+   */
+  tooltip?: string;
+}
+
+export function createIntentButton({
+  displayName,
+  intent,
+  defaultLabel,
+  loadText,
+  tooltip: defaultTooltip,
+}: IntentButtonSpec) {
+  const IntentButton = React.forwardRef<HTMLButtonElement, IntentButtonProps>(
+    function IntentButton(
+      { children = defaultLabel, iconOnly, icon, tooltip = defaultTooltip, ...props },
+      ref,
+    ) {
+      const density = useDensity();
+      const registered = useIntentIcon(intent);
+      const glyph = icon ?? registered;
+
+      /**
+       * Bound to the USER's profile, not the resolved density step (NEH-251).
+       *
+       * The obvious reading of the ladder is "collapse the label when spacing
+       * gets tight", i.e. test `useDensityStep()`. That is wrong, and the
+       * counter-example is Optima: it bases at `compact`, so a user who has
+       * expressed no preference at all resolves to the `compact` rung and every
+       * intent button in the product would silently lose its text.
+       *
+       * Dropping a visible label is a change to what a control *says*. It
+       * should answer "did this user ask for tighter?", which is exactly what
+       * the profile means — it is relative to whatever the app chose. An app
+       * that wants dense spacing has not thereby asked for unlabelled buttons.
+       */
+      const isIconOnly = iconOnly ?? density === "compact";
+
+      // The label as a string, for the accessible name. A node child cannot be
+      // flattened reliably, so fall back to the intent's own label rather than
+      // rendering `[object Object]` into aria-label.
+      const label = typeof children === "string" ? children : defaultLabel;
+
+      if (isIconOnly) {
+        return (
+          <StyledButton
+            ref={ref}
+            loadText={loadText}
+            // Without this the button has no text and no name at all — see the
+            // note above. An explicit aria-label from the caller still wins,
+            // because `props` is spread after.
+            aria-label={label}
+            tooltip={tooltip}
+            {...props}
+          >
+            {glyph}
+          </StyledButton>
+        );
+      }
+
+      return (
+        <StyledButton
+          ref={ref}
+          loadText={loadText}
+          leftIcon={glyph}
+          tooltip={tooltip}
+          {...props}
+        >
+          {children}
+        </StyledButton>
+      );
+    },
+  );
+
+  IntentButton.displayName = displayName;
+  return IntentButton;
+}

package/src/components/dictation.ts

@@ -0,0 +1,71 @@
+/**
+ * The dictation seam.
+ *
+ * `StyledInputText` and `StyledInputTextArea` can render a microphone, but this
+ * package contains no speech code and never will. Recognition is a product
+ * decision with product consequences — which engine, whether audio may leave
+ * the device, what a regulated deployment is allowed to send where — and none
+ * of that belongs in a component library.
+ *
+ * So the host builds the behaviour and hands it over as one object. The input
+ * owns the *presentation*: where the button sits, how much padding the text
+ * needs so it does not run underneath, what it is called, what it announces
+ * while recording. The host owns everything else.
+ *
+ * HopperGuard's `useDictation()` already returns this shape, so its call sites
+ * pass the hook's result straight through. That is the intended fit: an adapter
+ * that needs a translation layer is usually a sign the seam is in the wrong
+ * place.
+ *
+ * ## Why an object rather than a set of props
+ *
+ * These fields are meaningless apart — `showRedo` with no `redo`, `isListening`
+ * on an input with no `onMicClick` — and passing one bundle makes the
+ * all-or-nothing nature obvious at the call site. It also means adding a
+ * capability later does not widen the component's prop surface.
+ *
+ * ## What the input does NOT do
+ *
+ * It does not decide whether dictation is *appropriate*. A password field, a
+ * PIN, a card number — the host omits the adapter, and no mic renders. Putting
+ * that judgement here would mean guessing from `type`, which is exactly the
+ * kind of guess that puts a microphone on a field that should never have one.
+ *
+ * Errors are the host's too. They arrive asynchronously and belong wherever
+ * that product shows problems — a toast, an inline message, a live region —
+ * which the input cannot know.
+ */
+export interface Dictation {
+  /**
+   * Whether this browser/engine can dictate at all. `false` renders no mic —
+   * a control that cannot work is worse than an absent one, because the user
+   * has to press it to find out.
+   */
+  isSupported: boolean;
+  /** Recording now. Drives `aria-pressed` and the recording colour. */
+  isListening: boolean;
+  /** Offer "record again" — typically after a result the user may reject. */
+  showRedo?: boolean;
+  /** Start or stop recording. */
+  onMicClick: () => void;
+  /** Discard the last result and record again. Required when `showRedo`. */
+  redo?: () => void;
+
+  /**
+   * Ask what a new recording should do to text that is already there.
+   *
+   * Only meaningful for multi-entry fields, where prose is written in passes.
+   * Overwriting someone's paragraph because they pressed the mic a second time
+   * is a data-loss bug, not a UX preference — so when the host raises this, the
+   * field stops and asks instead of guessing.
+   *
+   * Requires `chooseContinue` and `chooseStartOver`. While it is raised the
+   * redo button is suppressed: three competing choices about the same text is
+   * not a decision anyone can make quickly.
+   */
+  continuePrompt?: boolean;
+  /** Append the new recording to what is already there. */
+  chooseContinue?: () => void;
+  /** Replace what is already there. */
+  chooseStartOver?: () => void;
+}

package/src/components/intent-buttons.ts

@@ -0,0 +1,154 @@
+/**
+ * The intent buttons.
+ *
+ * One line each, because that is genuinely all they are: a `StyledButton` that
+ * knows its icon, its label and its loading text. The behaviour lives in
+ * `createIntentButton`; this file is the vocabulary.
+ *
+ * `loadText` is set only where the action takes long enough to show a spinner
+ * and where naming it helps — "Saving" tells the user more than "Loading".
+ *
+ * Not every wrapper in the originating app belongs here. Ones that call an API,
+ * read a feature flag or drive app state (`StyledColorButton`,
+ * `StyledDensityButton`, `StyledThemeButton`, `StyledVariantButton`,
+ * `StyledStyleResetButton`, `StyledHelpButton`, `StyledCopyButton`) are
+ * application components that happen to be buttons, and they stay in the app.
+ */
+import { createIntentButton } from "./create-intent-button";
+
+export const StyledAddButton = createIntentButton({
+  displayName: "StyledAddButton",
+  intent: "add",
+  defaultLabel: "Add",
+  tooltip: "Add item",
+});
+
+export const StyledSaveButton = createIntentButton({
+  displayName: "StyledSaveButton",
+  intent: "save",
+  defaultLabel: "Save",
+  loadText: "Saving",
+});
+
+export const StyledDeleteButton = createIntentButton({
+  displayName: "StyledDeleteButton",
+  intent: "delete",
+  defaultLabel: "Delete",
+  loadText: "Deleting",
+  tooltip: "Delete the item",
+});
+
+export const StyledEditButton = createIntentButton({
+  displayName: "StyledEditButton",
+  intent: "edit",
+  defaultLabel: "Edit",
+  tooltip: "Modify this item.",
+});
+
+export const StyledCancelButton = createIntentButton({
+  displayName: "StyledCancelButton",
+  intent: "cancel",
+  defaultLabel: "Cancel",
+});
+
+export const StyledCloneButton = createIntentButton({
+  displayName: "StyledCloneButton",
+  intent: "clone",
+  defaultLabel: "Clone",
+  tooltip: "Create a copy of the item.",
+});
+
+export const StyledBackButton = createIntentButton({
+  displayName: "StyledBackButton",
+  intent: "back",
+  defaultLabel: "Back",
+});
+
+export const StyledNextButton = createIntentButton({
+  displayName: "StyledNextButton",
+  intent: "next",
+  defaultLabel: "Next",
+  tooltip: "Proceed to next step.",
+});
+
+export const StyledNewButton = createIntentButton({
+  displayName: "StyledNewButton",
+  intent: "new",
+  defaultLabel: "New",
+  tooltip: "Create a new item.",
+});
+
+export const StyledRenameButton = createIntentButton({
+  displayName: "StyledRenameButton",
+  intent: "rename",
+  defaultLabel: "Rename",
+  tooltip: "Rename the item",
+});
+
+export const StyledLoadButton = createIntentButton({
+  displayName: "StyledLoadButton",
+  intent: "load",
+  defaultLabel: "Load",
+  loadText: "Loading",
+  tooltip: "Load the item",
+});
+
+export const StyledResumeButton = createIntentButton({
+  displayName: "StyledResumeButton",
+  intent: "resume",
+  defaultLabel: "Resume",
+  tooltip: "Resume activity",
+});
+
+export const StyledPlayButton = createIntentButton({
+  displayName: "StyledPlayButton",
+  intent: "play",
+  defaultLabel: "Play",
+});
+
+// StyledFavoriteButton is deliberately absent. It is a stateful TOGGLE — its
+// icon colour and its tooltip both flip on `isFavorite` ("Mark as favorite" /
+// "Remove from favorites") — and the on-state colour is an app constant. That
+// is a different component from "a button with a star on it", so it stays in
+// the app rather than being bent into this factory.
+
+export const StyledSettingsButton = createIntentButton({
+  displayName: "StyledSettingsButton",
+  intent: "settings",
+  defaultLabel: "Settings",
+  tooltip: "Changes settings",
+});
+
+export const StyledHomeButton = createIntentButton({
+  displayName: "StyledHomeButton",
+  intent: "home",
+  defaultLabel: "Home",
+  tooltip: "Go to main page",
+});
+
+export const StyledMenuButton = createIntentButton({
+  displayName: "StyledMenuButton",
+  intent: "menu",
+  defaultLabel: "Menu",
+  tooltip: "Open menu with additional options",
+});
+
+export const StyledAnalyticsButton = createIntentButton({
+  displayName: "StyledAnalyticsButton",
+  intent: "analytics",
+  defaultLabel: "Analytics",
+  tooltip: "View data summary",
+});
+
+export const StyledEmojiButton = createIntentButton({
+  displayName: "StyledEmojiButton",
+  intent: "emoji",
+  defaultLabel: "Emoji",
+});
+
+export const StyledUrlButton = createIntentButton({
+  displayName: "StyledUrlButton",
+  intent: "url",
+  defaultLabel: "From URL",
+  tooltip: "Retrieve colors from external location.",
+});