@beyondwork/docx-react-component 1.0.52 → 1.0.53

package/src/ui-tailwind/theme/tokens.ts

@@ -0,0 +1,313 @@
+/**
+ * @beyondwork/docx-react-component — design-token manifest
+ *
+ * Single TypeScript surface that consumers import. Mirrors
+ * `docs/reference/designsystem.md` §3.1 (product token names) + §3.3/§3.4
+ * (values). Every key here has a CSS variable alias in
+ * `./tokens.css` — the pair is enforced by
+ * `test/ui-tailwind/token-coverage.test.ts`.
+ *
+ * Values below are the LIGHT-MODE hex values only. CSS variables own the
+ * light/dark fork; runtime reads resolve via `getComputedStyle`. Pure hex
+ * strings remain accessible for design-tool export, snapshot tests, and
+ * one-off cases where a consumer cannot enter the CSS cascade.
+ */
+
+export const BRAND_TOKENS = {
+  color: {
+    bg: {
+      app: "#F4F7F5",
+      chrome: "#FAFCFA",
+      sidebar: "#F1F6F2",
+      canvas: "#FFFFFF",
+      elevated: "#FFFFFF",
+      hover: "#EAF6EF",
+      selected: "#E2F2E8",
+      muted: "#F7FAF8",
+      overlay: "rgba(21, 26, 23, 0.08)",
+    },
+    border: {
+      subtle: "#E2EAE4",
+      default: "#D3DED6",
+      strong: "#BECDBF",
+      accent: "#8FC9AD",
+    },
+    text: {
+      primary: "#151A17",
+      secondary: "#5E6D63",
+      tertiary: "#8A978F",
+      quiet: "#A4AEA8",
+      inverse: "#F7FAF8",
+      onAccent: "#F7FAF8",
+      onSoftAccent: "#18563F",
+    },
+    accent: {
+      primary: "#1F6B4F",
+      primaryHover: "#18563F",
+      primaryActive: "#124432",
+      secondary: "#72D6AE",
+      secondaryHover: "#5FC79C",
+      secondaryActive: "#49B785",
+      soft: "#DDF1E4",
+      softHover: "#CEEAD8",
+    },
+    semantic: {
+      success: "#1F8A5B",
+      successSoft: "#DDF3E8",
+      warning: "#D58B1E",
+      warningSoft: "#FBEFD8",
+      error: "#D95C67",
+      errorSoft: "#FBE3E6",
+      info: "#2F8FCE",
+      infoSoft: "#DCEFFC",
+    },
+    field: {
+      fill: "#F6FAF7",
+      editable: "#EEF8F0",
+      focus: "#DDF1E4",
+      invalid: "#FBE3E6",
+      warning: "#FBEFD8",
+    },
+    status: {
+      ready: "#1F8A5B",
+      inProgress: "#2F8FCE",
+      paused: "#8A978F",
+      blocked: "#D95C67",
+      review: "#1F6B4F",
+      draft: "#72907E",
+    },
+    comment: {
+      marker: "#1F6B4F",
+      markerHover: "#18563F",
+      threadBg: "#F3FAF6",
+    },
+    change: {
+      insertion: "#DDF3E8",
+      deletion: "#FBE3E6",
+      comment: "#E8F4EC",
+      selection: "#DDF1E4",
+    },
+    scopeTint: {
+      blocked: "#FBE3E6",
+      inScope: "#E2F2E8",
+      suggest: "#FBEFD8",
+      comment: "#F3FAF6",
+      scheduled: "#DCEFFC",
+      proposed: "#EAF6EF",
+    },
+    chart: {
+      categorical: {
+        "1": "#1F6B4F",
+        "2": "#72D6AE",
+        "3": "#2F8FCE",
+        "4": "#D58B1E",
+        "5": "#7A6AF0",
+        "6": "#D95C67",
+        "7": "#5E8E7A",
+        "8": "#A7D9C1",
+      },
+      sequential: {
+        "1": "#EAF6EF",
+        "2": "#D4EEDD",
+        "3": "#B4DFC8",
+        "4": "#8FC9AD",
+        "5": "#5FA985",
+        "6": "#1F6B4F",
+      },
+      diverging: {
+        negStrong: "#C94B57",
+        neg: "#E9979F",
+        neutral: "#E9EFEA",
+        pos: "#97D1B3",
+        posStrong: "#1F6B4F",
+      },
+    },
+  },
+  shadow: {
+    soft: "0 6px 20px rgba(21, 26, 23, 0.06)",
+    float: "0 12px 32px rgba(21, 26, 23, 0.12)",
+    focus: "0 0 0 3px rgba(114, 214, 174, 0.28)",
+  },
+  radius: {
+    sm: "10px",
+    md: "12px",
+    lg: "14px",
+    xl: "16px",
+    pill: "9999px",
+  },
+  space: {
+    "1": "4px",
+    "2": "8px",
+    "3": "12px",
+    "4": "16px",
+    "5": "20px",
+    "6": "24px",
+    "8": "32px",
+    "10": "40px",
+    "12": "48px",
+    "16": "64px",
+  },
+  motion: {
+    fast: "120ms",
+    default: "160ms",
+    slow: "220ms",
+  },
+} as const;
+
+/**
+ * Dotted path tuple type used by the coverage test to enumerate every
+ * leaf of `BRAND_TOKENS`. Mirrors the `color.accent.primary` / `shadow.soft`
+ * form used throughout the spec.
+ */
+export type BrandTokens = typeof BRAND_TOKENS;
+export type BrandTokenPath =
+  | `color.bg.${keyof BrandTokens["color"]["bg"]}`
+  | `color.border.${keyof BrandTokens["color"]["border"]}`
+  | `color.text.${keyof BrandTokens["color"]["text"]}`
+  | `color.accent.${keyof BrandTokens["color"]["accent"]}`
+  | `color.semantic.${keyof BrandTokens["color"]["semantic"]}`
+  | `color.field.${keyof BrandTokens["color"]["field"]}`
+  | `color.status.${keyof BrandTokens["color"]["status"]}`
+  | `color.comment.${keyof BrandTokens["color"]["comment"]}`
+  | `color.change.${keyof BrandTokens["color"]["change"]}`
+  | `color.scopeTint.${keyof BrandTokens["color"]["scopeTint"]}`
+  | `color.chart.categorical.${keyof BrandTokens["color"]["chart"]["categorical"]}`
+  | `color.chart.sequential.${keyof BrandTokens["color"]["chart"]["sequential"]}`
+  | `color.chart.diverging.${keyof BrandTokens["color"]["chart"]["diverging"]}`
+  | `shadow.${keyof BrandTokens["shadow"]}`
+  | `radius.${keyof BrandTokens["radius"]}`
+  | `space.${keyof BrandTokens["space"]}`
+  | `motion.${keyof BrandTokens["motion"]}`;
+
+/**
+ * Converts a dotted product-token path into its CSS variable name.
+ *   productPathToCssVar("color.accent.primary") === "--color-accent-primary"
+ *   productPathToCssVar("color.chart.categorical.1") === "--color-chart-categorical-1"
+ *   productPathToCssVar("color.text.onAccent") === "--color-text-on-accent"
+ */
+export function productPathToCssVar(path: string): string {
+  const kebab = path
+    .split(".")
+    .join("-")
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .toLowerCase();
+  return `--${kebab}`;
+}
+
+/**
+ * Enumerates every leaf path in `BRAND_TOKENS`.
+ */
+export function enumerateBrandTokenPaths(): BrandTokenPath[] {
+  const out: string[] = [];
+  const walk = (node: unknown, prefix: string): void => {
+    if (node === null || typeof node !== "object") return;
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      const next = prefix === "" ? key : `${prefix}.${key}`;
+      if (typeof value === "string") out.push(next);
+      else walk(value, next);
+    }
+  };
+  walk(BRAND_TOKENS, "");
+  return out as BrandTokenPath[];
+}
+
+/**
+ * Host override contract (designsystem §8.5 / §9).
+ *
+ * Hosts MAY override these token families to match their brand / workspace.
+ */
+export const HOST_OVERRIDABLE_TOKENS = [
+  "color.accent.primary",
+  "color.accent.primaryHover",
+  "color.accent.primaryActive",
+  "color.accent.secondary",
+  "color.accent.secondaryHover",
+  "color.accent.secondaryActive",
+  "color.accent.soft",
+  "color.accent.softHover",
+  "color.bg.app",
+  "radius.sm",
+  "radius.md",
+  "radius.lg",
+  "radius.xl",
+  "radius.pill",
+  "motion.fast",
+  "motion.default",
+  "motion.slow",
+] as const satisfies readonly BrandTokenPath[];
+
+/**
+ * Hosts MUST NOT override these — semantic legibility, review markup,
+ * comment marker, canvas, and accessibility contract.
+ */
+export const HOST_LOCKED_TOKENS = [
+  "color.semantic.success",
+  "color.semantic.successSoft",
+  "color.semantic.warning",
+  "color.semantic.warningSoft",
+  "color.semantic.error",
+  "color.semantic.errorSoft",
+  "color.semantic.info",
+  "color.semantic.infoSoft",
+  "color.change.insertion",
+  "color.change.deletion",
+  "color.change.comment",
+  "color.change.selection",
+  "color.comment.marker",
+  "color.comment.markerHover",
+  "color.comment.threadBg",
+  "color.bg.canvas",
+  "shadow.focus",
+] as const satisfies readonly BrandTokenPath[];
+
+export type HostOverridableToken = (typeof HOST_OVERRIDABLE_TOKENS)[number];
+export type HostLockedToken = (typeof HOST_LOCKED_TOKENS)[number];
+
+/** Returns true if `path` is in the locked set (must not be overridden by hosts). */
+export function isTokenPathLocked(path: string): boolean {
+  return (HOST_LOCKED_TOKENS as readonly string[]).includes(path);
+}
+
+/**
+ * Dev-mode guard. Subscribes to attribute/style mutations on `document.documentElement`
+ * and emits `console.warn` if a host overrides a locked CSS variable.
+ *
+ * No-op in production (`process.env.NODE_ENV === "production"`) and in
+ * non-browser environments (SSR, test runners without DOM).
+ *
+ * Returns a teardown function. Call it to disconnect the observer.
+ */
+export function devGuardLockedTokens(
+  root: HTMLElement = typeof document !== "undefined"
+    ? document.documentElement
+    : (null as unknown as HTMLElement),
+): () => void {
+  if (
+    typeof document === "undefined" ||
+    root === null ||
+    (typeof (globalThis as Record<string, unknown>)["__WRE_DEV__"] !== "undefined" &&
+      !(globalThis as Record<string, unknown>)["__WRE_DEV__"])
+  ) {
+    return () => {};
+  }
+
+  const lockedVars = new Set(
+    (HOST_LOCKED_TOKENS as readonly string[]).map((p) => productPathToCssVar(p)),
+  );
+
+  const observer = new MutationObserver(() => {
+    const style = root.getAttribute("style") ?? "";
+    for (const v of lockedVars) {
+      if (style.includes(v)) {
+        console.warn(
+          `[docx-react-component] Host override of locked token "${v}" detected. ` +
+          `Overriding locked tokens may break review-workspace legibility contracts (§9.2). ` +
+          `See docs/reference/designsystem.md §9.`,
+        );
+      }
+    }
+  });
+
+  observer.observe(root, { attributes: true, attributeFilter: ["style"] });
+  return () => observer.disconnect();
+}

package/src/ui-tailwind/theme/use-density.ts

@@ -0,0 +1,60 @@
+/**
+ * Density mode hook — reads and writes `document.documentElement.dataset.density`
+ * and persists the preference in `localStorage["wre.density"]`.
+ *
+ * Components that use spacing gaps / paddings should multiply by
+ * `var(--space-density-multiplier)` in their CSS; this hook owns the
+ * attribute that drives the CSS override blocks in `tokens.css`.
+ *
+ * No component consumer lands in Lane 6a — Lane 6b.U5 / 6c.U9 own the
+ * opt-in plumbing. This module ships the hook so downstream lanes can
+ * import without a dependency on 6a being in-progress.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+export type DensityMode = "compact" | "standard" | "comfortable";
+
+const STORAGE_KEY = "wre.density";
+const DEFAULT_DENSITY: DensityMode = "standard";
+
+function readPersistedDensity(): DensityMode {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === "compact" || stored === "standard" || stored === "comfortable") {
+      return stored;
+    }
+  } catch {
+    // localStorage unavailable (SSR, sandboxed iframe, etc.)
+  }
+  return DEFAULT_DENSITY;
+}
+
+function applyDensity(mode: DensityMode): void {
+  document.documentElement.dataset.density = mode;
+  try {
+    localStorage.setItem(STORAGE_KEY, mode);
+  } catch {
+    // ignore
+  }
+}
+
+export function useDensity(): {
+  density: DensityMode;
+  setDensity: (mode: DensityMode) => void;
+} {
+  const [density, setDensityState] = useState<DensityMode>(DEFAULT_DENSITY);
+
+  useEffect(() => {
+    const initial = readPersistedDensity();
+    applyDensity(initial);
+    setDensityState(initial);
+  }, []);
+
+  const setDensity = useCallback((mode: DensityMode) => {
+    applyDensity(mode);
+    setDensityState(mode);
+  }, []);
+
+  return { density, setDensity };
+}