@stonedogcode/style 0.9.0

package/src/config/can-hover.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+/**
+ * Can the primary input on this device hover?
+ *
+ * Exists because a hover-triggered tooltip is not merely *degraded* on a touch
+ * screen — it is **unreachable**. There is no hover event to fire, and tapping
+ * a tooltipped control activates the control rather than explaining it. The
+ * help is rendered, correct, and impossible to see.
+ *
+ * That was a documented gap in this package for as long as `StyledTooltip` has
+ * existed, and it stopped being cosmetic when HopperGuard shipped an icon-only
+ * navigation rail: on a tablet the icons had no visible names *and* no way to
+ * ask for one.
+ *
+ * ## `(hover: none)`, not `(pointer: coarse)`
+ *
+ * They are different questions and only the first one is ours. `pointer:
+ * coarse` asks how *precise* the input is — a stylus and a TV remote are
+ * coarse, and both can hover perfectly well. `hover: none` asks whether the
+ * primary input can hover at all, which is exactly the capability a hover
+ * trigger depends on.
+ *
+ * ## Why it defaults to "can hover"
+ *
+ * `matchMedia` does not exist on the server, and a component that rendered one
+ * thing during SSR and another after hydration would produce a mismatch — and
+ * a control that appears a moment after the page settles, which for this
+ * audience is worse than one that was always there. So the server and the
+ * first client render both assume hover, and a device that cannot hover
+ * corrects itself on mount.
+ *
+ * The direction of that default matters: assuming hover means a touch device
+ * briefly renders what it has always rendered, then gains the control.
+ * Assuming *no* hover would make every desktop render an unnecessary control
+ * first and then remove it, which is a visible flicker on the majority case.
+ */
+
+const QUERY = "(hover: none)";
+
+function subscribe(onChange: () => void): () => void {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return () => {};
+  }
+  const list = window.matchMedia(QUERY);
+
+  // `addEventListener` where it exists, `addListener` where it does not. Safari
+  // gained the modern form late, and this package's audience skews towards
+  // older devices — exactly the population still on a browser that only has the
+  // deprecated one.
+  if (typeof list.addEventListener === "function") {
+    list.addEventListener("change", onChange);
+    return () => list.removeEventListener("change", onChange);
+  }
+  list.addListener(onChange);
+  return () => list.removeListener(onChange);
+}
+
+function getSnapshot(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return true;
+  return !window.matchMedia(QUERY).matches;
+}
+
+/** The server's answer: assume hover, and let the client correct it. */
+function getServerSnapshot(): boolean {
+  return true;
+}
+
+export function useCanHover(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+export default useCanHover;

package/src/config/density.ts

@@ -0,0 +1,138 @@
+import { DENSITY_PROFILES, type DensityProfile } from "./types";
+
+/**
+ * How tightly the UI packs — **one ladder, read from two places** (NEH-251).
+ *
+ * The proposal that led here had two vocabularies: an app-level preset
+ * (`Compact | Standard | Spacious`) and the user-facing profile this package
+ * already shipped (`compact | normal | comfortable`). Two axes sharing the word
+ * "compact" is how a call site ends up asking for one and getting the other.
+ *
+ * They are not two axes. They are a position and an offset on the same scale:
+ *
+ * ```
+ *   tight ── compact ── standard ── spacious ── airy
+ *     0         1           2          3         4
+ *
+ *   the APP picks a rung           (densityBase)
+ *   the USER shifts it by one      (density: compact -1 / normal 0 / comfortable +1)
+ * ```
+ *
+ * So HopperGuard sits at `spacious` and its density button moves a user between
+ * `standard`, `spacious` and `airy`; Optima sits at `compact` and the same
+ * button moves between `tight`, `compact` and `standard`. One control, one
+ * scale, and the app's choice of baseline is the only thing that differs.
+ *
+ * ## The numbers are not new
+ *
+ * HopperGuard already shipped `compact: 4px`, `normal: 8px`, `comfortable: 16px`.
+ * Those are exactly the `compact`, `standard` and `spacious` rungs below — the
+ * ladder was extracted from what the product already did, then extended by one
+ * step at each end, rather than invented.
+ *
+ * `standard` is also this package's long-standing fallback (`8px`), which is why
+ * `DEFAULT_STYLE_CONFIG.densityBase` is `"standard"`: a host that says nothing
+ * gets exactly what it got before.
+ */
+export const DENSITY_STEPS = [
+  "tight",
+  "compact",
+  "standard",
+  "spacious",
+  "airy",
+] as const;
+export type DensityStep = (typeof DENSITY_STEPS)[number];
+
+/**
+ * The rungs an application may sit on.
+ *
+ * Deliberately the middle three, not all five: `tight` and `airy` exist so that
+ * a user at either extreme still has somewhere to go. An app based at `airy`
+ * would give its "comfortable" users nothing, which is a worse failure than not
+ * offering the rung at all.
+ */
+export const DENSITY_BASES = ["compact", "standard", "spacious"] as const;
+export type DensityBase = (typeof DENSITY_BASES)[number];
+
+/** How far each user profile shifts the app's baseline. */
+const PROFILE_OFFSET: Record<DensityProfile, number> = {
+  compact: -1,
+  normal: 0,
+  comfortable: 1,
+};
+
+/**
+ * Spacing per rung, in the two custom properties the recipes read.
+ *
+ * `--panda-density-padding` and `--panda-density-margin` are an existing seam:
+ * six recipes already fold them into their own padding
+ * (`calc(.2rem + var(--panda-density-padding, 8px))`). This table gives hosts a
+ * single source for what to write into them, instead of each one keeping its
+ * own copy — which is what HopperGuard was doing.
+ *
+ * These do **not** affect the tap-target floor. That is a `min-height` stated in
+ * the recipes, so no density can push a control under it; the two compose
+ * rather than compete.
+ */
+export const DENSITY_METRICS: Record<
+  DensityStep,
+  { readonly padding: string; readonly margin: string }
+> = {
+  tight: { padding: "2px", margin: "2px" },
+  compact: { padding: "4px", margin: "4px" },
+  standard: { padding: "8px", margin: "8px" },
+  spacious: { padding: "16px", margin: "16px" },
+  airy: { padding: "24px", margin: "24px" },
+};
+
+export function isDensityStep(value: unknown): value is DensityStep {
+  return DENSITY_STEPS.includes(value as DensityStep);
+}
+
+export function isDensityBase(value: unknown): value is DensityBase {
+  return DENSITY_BASES.includes(value as DensityBase);
+}
+
+/**
+ * Where the app's baseline and the user's preference land, together.
+ *
+ * Clamped at both ends rather than wrapping or throwing: a user at the bottom
+ * of the scale choosing "compact" again should stay put, not silently jump to
+ * the loosest setting. Both inputs are validated, because at least one of them
+ * usually arrives from storage or an API and may predate a rename.
+ */
+export function resolveDensityStep(
+  base: DensityBase,
+  profile: DensityProfile,
+): DensityStep {
+  const safeBase: DensityBase = isDensityBase(base) ? base : "standard";
+  const safeProfile: DensityProfile = DENSITY_PROFILES.includes(profile)
+    ? profile
+    : "normal";
+
+  const index = DENSITY_STEPS.indexOf(safeBase);
+  const shifted = index + (PROFILE_OFFSET[safeProfile] ?? 0);
+  const clamped = Math.min(Math.max(shifted, 0), DENSITY_STEPS.length - 1);
+
+  // The index is clamped into range, so this cannot miss — returning the base
+  // rather than asserting keeps the function total.
+  return DENSITY_STEPS[clamped] ?? safeBase;
+}
+
+/**
+ * The custom properties a host should write for a given rung.
+ *
+ * Returned as data rather than applied here on purpose: this package does not
+ * touch the document. Where those properties get written — `documentElement`, a
+ * wrapper's inline style, a server-rendered `<style>` — is a host decision, and
+ * a library that reaches for `document` breaks server rendering for everyone.
+ */
+export function densityCustomProperties(
+  step: DensityStep,
+): Record<string, string> {
+  const metrics = DENSITY_METRICS[step];
+  return {
+    "--panda-density-padding": metrics.padding,
+    "--panda-density-margin": metrics.margin,
+  };
+}

package/src/config/font-size.ts

@@ -0,0 +1,113 @@
+import type { FontSizeKey } from "./types";
+
+/**
+ * Size key → CSS font-size.
+ *
+ * Every value is a `var(--font-sizes-*)` reference with a **rem** fallback, and
+ * both halves matter. The custom property lets a host retune the scale without
+ * touching this package; rem (never px) is what makes the whole UI respond to
+ * the browser's own font-size setting, which is the accessibility affordance
+ * that users with low vision actually reach for.
+ *
+ * ## The fallbacks are a conventional web scale, and that is a recent change
+ *
+ * `md` is `1rem` (16px), and the rest is the familiar Tailwind/Panda ramp.
+ * Until NEH-251 the fallbacks encoded HopperGuard's elder-sized scale instead —
+ * `md` was `1.375rem` (~22px) — because this package was extracted from that
+ * product and nothing else consumed it yet.
+ *
+ * That was the wrong default for a shared library. It is not a scale anyone
+ * *chose*; it was what a host got for saying nothing, and every new consumer
+ * inherited an eldercare product's typography by accident.
+ *
+ * **A host that needs a different scale defines the custom properties.**
+ * HopperGuard does exactly that now (its `globals.css` pins all thirteen tiers
+ * at the elder values), which is what made this change invisible there — and
+ * that pinning landed and was verified BEFORE this, deliberately, because
+ * flipping the fallback first would have shrunk every piece of text in that app
+ * with nothing failing anywhere.
+ *
+ * So: change these only with the same care. A fallback change is silent in
+ * every host that has not named its own scale.
+ */
+export const fontSizeMap: Record<string, string> = {
+  xs: "var(--font-sizes-xs, 0.75rem)",
+  sm: "var(--font-sizes-sm, 0.875rem)",
+  md: "var(--font-sizes-md, 1rem)",
+  lg: "var(--font-sizes-lg, 1.125rem)",
+  xl: "var(--font-sizes-xl, 1.25rem)",
+  // Heading-only tiers. Not offerable as a global preference — see
+  // FONT_SIZE_PROFILES — so they ramp faster than the body range above.
+  "2xl": "var(--font-sizes-2xl, 1.5rem)",
+  "3xl": "var(--font-sizes-3xl, 1.875rem)",
+  "4xl": "var(--font-sizes-4xl, 2.25rem)",
+  "5xl": "var(--font-sizes-5xl, 3rem)",
+  "6xl": "var(--font-sizes-6xl, 3.75rem)",
+  "7xl": "var(--font-sizes-7xl, 4.5rem)",
+  "8xl": "var(--font-sizes-8xl, 6rem)",
+  "9xl": "var(--font-sizes-9xl, 8rem)",
+};
+
+/** Human-readable names for the five selectable profiles. */
+const fontSizeLabelMap: Record<string, string> = {
+  xs: "Extra Small",
+  sm: "Small",
+  md: "Medium",
+  lg: "Large",
+  xl: "Extra Large",
+};
+
+/** Friendly name for a font-size profile (falls back to the raw key). */
+export function getFontSizeLabel(size: string): string {
+  return fontSizeLabelMap[size] ?? size;
+}
+
+/**
+ * The literal fallback inside a `fontSizeMap` entry, e.g. `"1rem"`.
+ *
+ * Used where a real length is needed rather than a CSS reference — measuring,
+ * or a context that cannot resolve custom properties. Returns `"unknown"` for
+ * an unrecognised key rather than throwing, because this feeds display code.
+ */
+export function getFontSizeValue(size: string): string {
+  const sizeString = fontSizeMap[size];
+  if (!sizeString) {
+    return "unknown";
+  }
+  const parts = sizeString.split(",");
+  // `parts.length > 1` does not narrow `parts[1]` under noUncheckedIndexedAccess,
+  // and destructuring says what we actually mean: take the fallback if there is one.
+  const [, fallback] = parts;
+  if (fallback !== undefined) {
+    return fallback.replace(")", "").trim();
+  }
+  return sizeString;
+}
+
+/** Order used to step a heading one tier above its base size. */
+export const FONT_SIZE_ORDER: readonly FontSizeKey[] = [
+  "xs",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+  "3xl",
+  "4xl",
+  "5xl",
+  "6xl",
+  "7xl",
+  "8xl",
+  "9xl",
+] as const;
+
+/** The next size up, clamped at the top of the scale. */
+export function stepUpFontSize(size: FontSizeKey, steps = 1): FontSizeKey {
+  const index = FONT_SIZE_ORDER.indexOf(size);
+  if (index === -1) return size;
+  const next = FONT_SIZE_ORDER[Math.min(index + steps, FONT_SIZE_ORDER.length - 1)];
+  // The index is clamped into range, so this cannot miss — but returning `size`
+  // rather than asserting keeps the function total, and a future change to the
+  // clamp fails safe instead of returning undefined to a caller typed otherwise.
+  return next ?? size;
+}

package/src/config/intent-icons.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import React, { createContext, useContext } from "react";
+
+/**
+ * The intent icon registry.
+ *
+ * This is what lets one `StyledDeleteButton` serve three products that draw a
+ * trash can differently. The component knows it needs "the delete icon"; the
+ * host says what that *is*, once, at the root:
+ *
+ * ```tsx
+ * // HopperGuard — Font Awesome Pro, via hopper-icons
+ * <StonedogStyleProvider icons={{ delete: <StyledTrash />, save: <StyledSave /> }}>
+ *
+ * // optima-filings — Lucide, via the same seam
+ * <StonedogStyleProvider icons={{ delete: <Trash2 />, save: <Save /> }}>
+ * ```
+ *
+ * ## Why a registry rather than an `icon` prop on every call site
+ *
+ * A prop would work, but it moves the decision to ~500 call sites and loses the
+ * thing an intent button exists for: that *every* delete button in the product
+ * looks the same. Registering once keeps that guarantee while leaving the
+ * artwork entirely with the host — which is what allows this package to stay
+ * public and Apache-2.0 while HopperGuard uses a per-seat licensed icon set.
+ *
+ * A per-call-site `icon` prop still overrides, for the rare one-off.
+ *
+ * ## Nothing is required
+ *
+ * An unregistered intent renders no icon rather than throwing — a missing icon
+ * should not take down a page. `missingIntentIcons()` exists so a host can
+ * assert it registered the ones it uses, the same way
+ * `requiredCssCustomProperties()` works for the token contract.
+ */
+
+/**
+ * Every intent the shared buttons ask for.
+ *
+ * Named for what the button DOES, not what the glyph looks like — `delete`, not
+ * `trash`. A host that maps `delete` to a broom is free to; the components only
+ * care about the meaning.
+ *
+ * **Exactly the intents the shipped buttons use — no more.** `missingIntentIcons`
+ * is only meaningful if this list means "what a host must register for the
+ * components to draw"; padding it with intents nothing renders would make that
+ * function report work nobody needs to do. `close`, `copy`, `favorite` and
+ * `help` are absent for that reason: those buttons stayed in the app, because
+ * each carries app state or a stateful toggle rather than being a plain intent.
+ */
+export const ICON_INTENTS = [
+  "add",
+  "analytics",
+  "back",
+  "cancel",
+  "clone",
+  "delete",
+  // Dictation. Only used by the text inputs, and only when a host passes them
+  // a `dictation` adapter — a product with no speech support registers neither
+  // and never renders either.
+  "dictate",
+  "edit",
+  "emoji",
+  "home",
+  "load",
+  "menu",
+  "new",
+  "next",
+  "play",
+  "redo",
+  "rename",
+  "resume",
+  "save",
+  "settings",
+  "url",
+] as const;
+
+export type IconIntent = (typeof ICON_INTENTS)[number];
+export type IntentIcons = Partial<Record<IconIntent, React.ReactNode>>;
+
+const IntentIconContext = createContext<IntentIcons>({});
+
+export function IntentIconProvider({
+  icons,
+  children,
+}: {
+  icons: IntentIcons;
+  children: React.ReactNode;
+}) {
+  return (
+    <IntentIconContext.Provider value={icons}>
+      {children}
+    </IntentIconContext.Provider>
+  );
+}
+
+/** The whole registry. Empty outside a provider — never throws. */
+export function useIntentIcons(): IntentIcons {
+  return useContext(IntentIconContext);
+}
+
+/** One icon, or `undefined` if the host did not register it. */
+export function useIntentIcon(intent: IconIntent): React.ReactNode {
+  return useIntentIcons()[intent];
+}
+
+/**
+ * Intents a host has not registered.
+ *
+ * For a startup assertion or a test. A missing icon is silent by design — the
+ * button still renders and still works — so this is the only way to notice.
+ */
+export function missingIntentIcons(icons: IntentIcons): IconIntent[] {
+  return ICON_INTENTS.filter((intent) => icons[intent] === undefined);
+}

package/src/config/logger.ts

@@ -0,0 +1,60 @@
+/**
+ * The logging seam.
+ *
+ * The components this package was extracted from called `hopper-logger`
+ * directly — a private package, and the single biggest reason the library could
+ * not be shared. Rather than swap one hard dependency for another, the library
+ * logs through an interface that **does nothing by default**.
+ *
+ * Silence is the right default for a UI library: a component rendering a few
+ * hundred times a second must not decide on the host's behalf that its console
+ * should fill up. A host that wants the traces calls `setStyleLogger` once at
+ * startup — HopperGuard passes `hopper-logger`'s `log` straight in, since the
+ * shape matches.
+ */
+
+export interface StyleLogger {
+  trace(message: string, meta?: unknown): void;
+  debug(message: string, meta?: unknown): void;
+  info(message: string, meta?: unknown): void;
+  warn(message: string, meta?: unknown): void;
+  error(message: string, meta?: unknown): void;
+}
+
+const noop = () => {};
+
+const NOOP_LOGGER: StyleLogger = {
+  trace: noop,
+  debug: noop,
+  info: noop,
+  warn: noop,
+  error: noop,
+};
+
+let current: StyleLogger = NOOP_LOGGER;
+
+/**
+ * Route this library's logging into the host's logger.
+ *
+ * Call once, before rendering. Passing `null` restores silence, which is what
+ * test teardown wants.
+ */
+export function setStyleLogger(logger: StyleLogger | null): void {
+  current = logger ?? NOOP_LOGGER;
+}
+
+/**
+ * The library's logger.
+ *
+ * Deliberately a getter-backed object rather than the bare `current` reference:
+ * modules capture `log` at import time, so handing out the value directly would
+ * freeze whichever logger happened to be installed first — and in practice that
+ * is always the no-op, making `setStyleLogger` appear to do nothing.
+ */
+export const log: StyleLogger = {
+  trace: (message, meta) => current.trace(message, meta),
+  debug: (message, meta) => current.debug(message, meta),
+  info: (message, meta) => current.info(message, meta),
+  warn: (message, meta) => current.warn(message, meta),
+  error: (message, meta) => current.error(message, meta),
+};