@cosxai/ui 0.25.0 → 1.0.0-alpha.0

package/src/editorial/EditorialSpotlight.tsx

@@ -1,63 +0,0 @@
-import type { ReactNode, CSSProperties } from "react";
-
-// Local "spotlight" inversion for editorial chrome — the
-// dark-canvas-with-cream-cards pattern from the brief, scoped to
-// a single section rather than the whole page.
-//
-// Sets local CSS vars on a wrapper so every descendant component
-// re-reads its tokens from the inverted palette. Pure CSS variable
-// re-binding; no JS or context needed. Used inside any chrome —
-// the kit doesn't require editorial to be active for the wrapper
-// to work — but the visual lineage (cream surface + coral accent)
-// reads most strongly under editorial.
-
-export interface EditorialSpotlightProps {
-  children: ReactNode;
-  // Optional inner padding. Default 32 px.
-  padding?: number | string;
-  className?: string;
-  style?: CSSProperties;
-}
-
-export function EditorialSpotlight({
-  children,
-  padding = 32,
-  className,
-  style,
-}: EditorialSpotlightProps) {
-  return (
-    <div
-      className={className}
-      data-ck-spotlight
-      style={
-        {
-          // Dark canvas surrounding cream-paper cards.
-          background: "#0E0E0E",
-          color: "#F4EFE0",
-          padding,
-          borderRadius: "var(--ck-radius-md)",
-          // Rebind tokens so descendant components (Button, Card,
-          // Tag, etc.) read inverted values. Card surface stays
-          // cream; everything else flips to dark.
-          ["--ck-bg-canvas"]: "#0E0E0E",
-          ["--ck-bg-surface"]: "#F4EFE0",
-          ["--ck-bg-surface-2"]: "#E5DECB",
-          ["--ck-bg-muted"]: "#1F1F1F",
-          ["--ck-text-primary"]: "#F4EFE0",
-          ["--ck-text-secondary"]: "#C9C3B5",
-          ["--ck-text-tertiary"]: "#8F897D",
-          ["--ck-text-inverse"]: "#0F0F0F",
-          ["--ck-border-subtle"]: "rgba(244, 239, 224, 0.18)",
-          ["--ck-border-strong"]: "rgba(244, 239, 224, 0.32)",
-          ...style,
-        } as CSSProperties
-      }
-    >
-      {/* Inner wrapper re-binds the text colour back to dark
-          ink so anything sitting on the cream cards inside reads
-          correctly. <Card> children get this for free via the
-          token rebinding on .ck-card. */}
-      {children}
-    </div>
-  );
-}

package/src/editorial/Folio.tsx

@@ -1,52 +0,0 @@
-import type { ReactNode } from "react";
-
-// Folio bar — thin hairline rule above a row of editorial
-// metadata. Sits at the top of every section in the editorial
-// chrome ("SECTION TITLE · CROSSREF · PLATE 0X" on the left,
-// "00X / 008" page number on the right).
-//
-// Renders fine under any chrome but only feels "right" under
-// editorial — the hairline + tracked metadata pair are the
-// editorial language, neutral in other chromes.
-
-export interface FolioProps {
-  // Left-aligned metadata fragments. Joined with the editorial
-  // separator (" · ").
-  left: (string | ReactNode)[];
-  // Right-aligned fragment (typically the page number).
-  right?: string | ReactNode;
-  className?: string;
-}
-
-export function Folio({ left, right, className }: FolioProps) {
-  return (
-    <header
-      className={className}
-      style={{
-        display: "flex",
-        alignItems: "center",
-        gap: 12,
-        padding: "10px 0",
-        borderTop: "1px solid var(--ck-text-primary)",
-        borderBottom: "1px solid var(--ck-text-primary)",
-        margin: "0 0 24px",
-        font: "500 10px/1.2 var(--ck-font-sans)",
-        letterSpacing: "0.16em",
-        textTransform: "uppercase",
-        color: "var(--ck-text-primary)",
-      }}
-    >
-      <div style={{ flex: 1, minWidth: 0, display: "flex", flexWrap: "wrap", gap: "0 8px" }}>
-        {left.map((seg, i) => (
-          <span key={i} style={{ display: "inline-flex", alignItems: "center", gap: 8 }}>
-            {i > 0 && <span style={{ color: "var(--ck-text-tertiary)" }}>·</span>}
-            <span>{seg}</span>
-          </span>
-        ))}
-      </div>
-      {right && (
-        <div style={{ flex: "none", color: "var(--ck-text-secondary)" }}>{right}</div>
-      )}
-    </header>
-  );
-}

package/src/editorial/PlateMarker.tsx

@@ -1,33 +0,0 @@
-// "N° 01" / "N° 02" plate numbering — sits in the top-left of
-// editorial cards and stat blocks. Uses small caps for the prefix
-// and a tabular numeral so a column of plates aligns visually.
-
-export interface PlateMarkerProps {
-  // The numeral, 1-indexed. Zero-padded to 2 digits ("01").
-  n: number;
-  // "N°" by default. Override to "Plate", "Vol.", "Issue", etc.
-  prefix?: string;
-  className?: string;
-}
-
-export function PlateMarker({ n, prefix = "N°", className }: PlateMarkerProps) {
-  const padded = n < 10 ? `0${n}` : String(n);
-  return (
-    <span
-      className={className}
-      style={{
-        display: "inline-flex",
-        alignItems: "baseline",
-        gap: 4,
-        font: "500 10px/1 var(--ck-font-sans)",
-        letterSpacing: "0.18em",
-        textTransform: "uppercase",
-        color: "var(--ck-text-tertiary)",
-        fontVariantNumeric: "tabular-nums",
-      }}
-    >
-      <span style={{ fontStyle: "italic" }}>{prefix}</span>
-      <span style={{ color: "var(--ck-text-primary)" }}>{padded}</span>
-    </span>
-  );
-}

package/src/editorial/RomanSection.tsx

@@ -1,65 +0,0 @@
-import type { ReactNode } from "react";
-
-// Section break with a Roman-numeral marker. "I.", "II.", ...
-// in oversized serif italic, followed by a thin hairline rule.
-// Use to delimit major content slabs inside an editorial page.
-
-const ROMAN = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X", "XI", "XII"];
-
-export interface RomanSectionProps {
-  // 1-indexed numeral. Anything above XII falls back to the
-  // arabic numeral so we don't have to ship a full converter.
-  n: number;
-  title: ReactNode;
-  // Optional eyebrow (rendered above the numeral).
-  eyebrow?: string;
-}
-
-export function RomanSection({ n, title, eyebrow }: RomanSectionProps) {
-  const numeral = n >= 1 && n <= ROMAN.length ? ROMAN[n - 1] : String(n);
-  return (
-    <section style={{ margin: "56px 0 32px" }}>
-      {eyebrow && (
-        <div
-          style={{
-            font: "500 10px/1 var(--ck-font-sans)",
-            letterSpacing: "0.18em",
-            textTransform: "uppercase",
-            color: "var(--ck-text-tertiary)",
-            marginBottom: 8,
-          }}
-        >
-          — {eyebrow}
-        </div>
-      )}
-      <div style={{ display: "flex", alignItems: "baseline", gap: 16, marginBottom: 12 }}>
-        <span
-          style={{
-            font: "500 italic 64px/1 var(--ck-font-serif)",
-            color: "var(--ck-text-primary)",
-            letterSpacing: "-0.02em",
-          }}
-        >
-          {numeral}.
-        </span>
-        <h2
-          style={{
-            font: "500 28px/1.1 var(--ck-font-display)",
-            color: "var(--ck-text-primary)",
-            margin: 0,
-            letterSpacing: "-0.01em",
-          }}
-        >
-          {title}
-        </h2>
-      </div>
-      <hr
-        style={{
-          border: "none",
-          borderTop: "1px solid var(--ck-text-primary)",
-          margin: 0,
-        }}
-      />
-    </section>
-  );
-}

package/src/editorial/RunningMarginalia.tsx

@@ -1,65 +0,0 @@
-import type { CSSProperties } from "react";
-
-// Vertical tracked-uppercase tagline in a far-side gutter — pure
-// decoration that sets the magazine tone. Pin to either "left" or
-// "right" edge of the viewport. Repeats the tagline string so it
-// fills the column regardless of height.
-//
-// Skip on phones (the gutter doesn't exist on a 360-px-wide page).
-
-export interface RunningMarginaliaProps {
-  // The tagline to repeat. Don't include separators — the
-  // component injects "  ×  " between repetitions.
-  text: string;
-  // Which edge to pin to. Default left.
-  side?: "left" | "right";
-  // px offset from the edge. Default 24.
-  inset?: number;
-  // How many repetitions to print. Default 8 — plenty for any
-  // viewport at the default font size.
-  repeat?: number;
-  // Hide below this viewport width (px). Default 1024.
-  hideBelow?: number;
-  className?: string;
-}
-
-export function RunningMarginalia({
-  text,
-  side = "left",
-  inset = 24,
-  repeat = 8,
-  hideBelow = 1024,
-  className,
-}: RunningMarginaliaProps) {
-  const display: CSSProperties =
-    typeof window !== "undefined" && window.innerWidth < hideBelow
-      ? { display: "none" }
-      : {};
-  const fragments = new Array(repeat).fill(text).join("  ×  ");
-  return (
-    <aside
-      aria-hidden
-      className={className}
-      style={{
-        position: "fixed",
-        top: "50%",
-        [side]: inset,
-        transform:
-          side === "left"
-            ? "translateY(-50%) rotate(-90deg)"
-            : "translateY(-50%) rotate(90deg)",
-        transformOrigin: side === "left" ? "left center" : "right center",
-        font: "500 10px/1 var(--ck-font-sans)",
-        letterSpacing: "0.36em",
-        textTransform: "uppercase",
-        color: "var(--ck-text-tertiary)",
-        whiteSpace: "nowrap",
-        pointerEvents: "none",
-        zIndex: 5,
-        ...display,
-      }}
-    >
-      {fragments}
-    </aside>
-  );
-}

package/src/editorial/index.ts

@@ -1,10 +0,0 @@
-export { Folio } from "./Folio";
-export type { FolioProps } from "./Folio";
-export { PlateMarker } from "./PlateMarker";
-export type { PlateMarkerProps } from "./PlateMarker";
-export { RunningMarginalia } from "./RunningMarginalia";
-export type { RunningMarginaliaProps } from "./RunningMarginalia";
-export { RomanSection } from "./RomanSection";
-export type { RomanSectionProps } from "./RomanSection";
-export { EditorialSpotlight } from "./EditorialSpotlight";
-export type { EditorialSpotlightProps } from "./EditorialSpotlight";

package/src/hooks/index.ts

@@ -1,5 +0,0 @@
-export { useViewport } from "./useViewport";
-export type { Viewport, ViewportBreakpoints } from "./useViewport";
-export { useReducedMotion } from "./useReducedMotion";
-export { useKeyboardHotkey } from "./useKeyboardHotkey";
-export type { UseKeyboardHotkeyOptions } from "./useKeyboardHotkey";

package/src/hooks/useKeyboardHotkey.ts

@@ -1,93 +0,0 @@
-import { useEffect, useRef } from "react";
-
-// Single-key hotkey listener with the standard conflict guards:
-//   - skipInputs (default true)        — ignore when an input /
-//     textarea / select / contenteditable is focused
-//   - skipModifiers (default true)     — let browser shortcuts
-//     (Cmd+S, Ctrl+W, etc.) through
-//   - skipWhenModalOpen (default true) — don't fire when a
-//     <Modal> (anything with role="dialog") is mounted
-//
-// `key` is a single character (case-insensitive) or a special key
-// name ("Escape", "Enter", "ArrowUp", etc.). For modifier
-// combinations use `mod: true` (Cmd on Mac, Ctrl elsewhere).
-//
-// Handler refs are kept fresh via a ref-mirror — call sites don't
-// need to memoise the callback.
-
-export interface UseKeyboardHotkeyOptions {
-  // Combine with Cmd (Mac) / Ctrl (other). Default false.
-  mod?: boolean;
-  skipInputs?: boolean;
-  skipModifiers?: boolean; // ignored when `mod: true`
-  skipWhenModalOpen?: boolean;
-  // Disable without unmounting (toggle off without remount).
-  enabled?: boolean;
-}
-
-const isMac = () =>
-  typeof navigator !== "undefined" &&
-  /Mac|iPhone|iPad|iPod/.test(navigator.platform);
-
-export function useKeyboardHotkey(
-  key: string,
-  handler: (e: KeyboardEvent) => void,
-  options: UseKeyboardHotkeyOptions = {},
-) {
-  const {
-    mod = false,
-    skipInputs = true,
-    skipModifiers = true,
-    skipWhenModalOpen = true,
-    enabled = true,
-  } = options;
-
-  const handlerRef = useRef(handler);
-  handlerRef.current = handler;
-
-  useEffect(() => {
-    if (!enabled) return;
-    const target = key.toLowerCase();
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key.toLowerCase() !== target) return;
-      if (mod) {
-        const wantedMod = isMac() ? e.metaKey : e.ctrlKey;
-        if (!wantedMod) return;
-        if (e.shiftKey || e.altKey) return;
-      } else if (skipModifiers && (e.metaKey || e.ctrlKey || e.altKey)) {
-        return;
-      }
-      if (skipInputs) {
-        const ae = document.activeElement as HTMLElement | null;
-        const tag = ae?.tagName;
-        // Containers marked data-hotkey-passthrough host editables
-        // the user never types into (e.g. a canvas spreadsheet's
-        // hidden cell-editor focus trap) — hotkeys stay live there.
-        // Mirrors the same convention in consumer apps.
-        const passthrough = !!ae?.closest?.('[data-hotkey-passthrough="true"]');
-        if (
-          !passthrough &&
-          (tag === "INPUT" ||
-            tag === "TEXTAREA" ||
-            tag === "SELECT" ||
-            ae?.isContentEditable)
-        ) {
-          return;
-        }
-      }
-      if (skipWhenModalOpen && document.querySelector('[role="dialog"]')) {
-        return;
-      }
-      // The key is OURS once every guard passed — swallow its default
-      // action. Without this, a hotkey that opens a dialog with an
-      // autofocused input sees the same keystroke land as text ("s"
-      // typed into the invite search, meta QA 2026-08-19): the
-      // browser's text-insertion runs AFTER keydown, by which time
-      // focus has moved into the new input.
-      e.preventDefault();
-      handlerRef.current(e);
-    };
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [key, mod, skipInputs, skipModifiers, skipWhenModalOpen, enabled]);
-}

package/src/hooks/useReducedMotion.ts

@@ -1,20 +0,0 @@
-import { useEffect, useState } from "react";
-
-// Boolean subscription to the OS-level `prefers-reduced-motion`
-// query. Use in component code that wants to short-circuit
-// non-essential animations (the kit's CSS already respects the
-// query via `@media (prefers-reduced-motion: reduce)` so most
-// components don't need this — only call sites that wrap their
-// own JS-driven motion (canvas animations, scroll-jacking, etc.)).
-
-export function useReducedMotion(): boolean {
-  const [prefers, setPrefers] = useState(false);
-  useEffect(() => {
-    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
-    setPrefers(mq.matches);
-    const onChange = (e: MediaQueryListEvent) => setPrefers(e.matches);
-    mq.addEventListener("change", onChange);
-    return () => mq.removeEventListener("change", onChange);
-  }, []);
-  return prefers;
-}

package/src/hooks/useViewport.ts

@@ -1,61 +0,0 @@
-import { useEffect, useState } from "react";
-
-// Viewport size + named breakpoints. Layout components subscribe to
-// this to switch desktop ↔ mobile shells, force-collapse the nav
-// rail below a width threshold, etc.
-//
-// Single window listener for all consumers (mounted once per call
-// site — keep usage minimal). For pages with many consumers, lift
-// to a context if perf is ever an issue; not needed yet.
-
-export interface Viewport {
-  width: number;
-  height: number;
-  // Below this, render the mobile shell (bottom tab bar + slide-out nav).
-  isPhone: boolean;
-  // Below this, force-collapse the left nav rail to icon-only.
-  isNarrow: boolean;
-  // Below this, hide the right rail entirely.
-  hidesRightRail: boolean;
-}
-
-export interface ViewportBreakpoints {
-  phone: number;
-  narrow: number;
-  rightRail: number;
-}
-
-const DEFAULTS: ViewportBreakpoints = {
-  phone: 768,
-  narrow: 1100,
-  rightRail: 1280,
-};
-
-function snapshot(b: ViewportBreakpoints): Viewport {
-  if (typeof window === "undefined") {
-    return { width: 1440, height: 900, isPhone: false, isNarrow: false, hidesRightRail: false };
-  }
-  const w = window.innerWidth;
-  const h = window.innerHeight;
-  return {
-    width: w,
-    height: h,
-    isPhone: w < b.phone,
-    isNarrow: w < b.narrow,
-    hidesRightRail: w < b.rightRail,
-  };
-}
-
-export function useViewport(breakpoints: Partial<ViewportBreakpoints> = {}): Viewport {
-  const b: ViewportBreakpoints = { ...DEFAULTS, ...breakpoints };
-  const [vp, setVp] = useState<Viewport>(() => snapshot(b));
-  useEffect(() => {
-    const onResize = () => setVp(snapshot(b));
-    onResize();
-    window.addEventListener("resize", onResize);
-    return () => window.removeEventListener("resize", onResize);
-    // Breakpoints are stable across renders for any sane caller; stringify
-    // to avoid unstable-object-identity re-runs without losing reactivity.
-  }, [b.phone, b.narrow, b.rightRail]);
-  return vp;
-}

package/src/layout/Breadcrumb.tsx

@@ -1,74 +0,0 @@
-import { Fragment, type ReactNode } from "react";
-
-// Crumb item — either a label (terminal node, no link) or a label
-// with a click handler. The kit doesn't ship router integration —
-// consumers pass plain onClick or wrap children in their own router's
-// link primitive (e.g. <NavLink to={...}>{label}</NavLink>).
-
-export interface CrumbItem {
-  label: string;
-  onClick?: () => void;
-  // Custom render — escape hatch for "wrap this crumb in <Link>".
-  // When set, label/onClick are ignored.
-  render?: ReactNode;
-}
-
-export interface BreadcrumbProps {
-  items: ReadonlyArray<string | CrumbItem>;
-  // Slot to the right of the last crumb (e.g. doc-meta popover trigger).
-  accessory?: ReactNode;
-  className?: string;
-}
-
-function normalise(item: string | CrumbItem): CrumbItem {
-  return typeof item === "string" ? { label: item } : item;
-}
-
-// Phase-2 breadcrumb: simple chain with separator dots. The full
-// middle-collapse + narrow-viewport popover fallback from deck-kit
-// is deferred to a later iteration once the kit's surface stabilises.
-// For now, long chains wrap; consumers should avoid >4 crumbs.
-export function Breadcrumb({ items, accessory, className }: BreadcrumbProps) {
-  const list = items.map(normalise);
-  return (
-    <nav
-      aria-label="Breadcrumb"
-      className={className}
-      style={{
-        display: "flex",
-        alignItems: "center",
-        gap: 6,
-        font: "400 12px/1 var(--ck-font-mono)",
-        color: "var(--ck-text-tertiary)",
-        letterSpacing: "0.04em",
-        textTransform: "uppercase",
-        minWidth: 0,
-        flex: "1 1 auto",
-      }}
-    >
-      {list.map((crumb, i) => {
-        const isLast = i === list.length - 1;
-        return (
-          <Fragment key={i}>
-            {i > 0 && (
-              <span aria-hidden style={{ color: "var(--ck-text-disabled)" }}>·</span>
-            )}
-            <span
-              style={{
-                color: isLast ? "var(--ck-text-primary)" : "var(--ck-text-tertiary)",
-                whiteSpace: "nowrap",
-                overflow: "hidden",
-                textOverflow: "ellipsis",
-                cursor: crumb.onClick ? "pointer" : "default",
-              }}
-              onClick={crumb.onClick}
-            >
-              {crumb.render ?? crumb.label}
-            </span>
-          </Fragment>
-        );
-      })}
-      {accessory && <span style={{ marginLeft: 4 }}>{accessory}</span>}
-    </nav>
-  );
-}