@cosxai/ui 0.1.0

package/src/frutiger/GlossyOrb.tsx

@@ -0,0 +1,79 @@
+import type { CSSProperties } from "react";
+
+// Pure CSS 3D glass orb — the "Aero" / Vista / iOS 6 marble.
+// Layered radial gradients: deep accent base, top white highlight,
+// bottom internal reflection, soft outer glow. Drop it anywhere
+// you want a hero / empty-state decoration.
+
+export interface GlossyOrbProps {
+  size?: number;
+  // Tint of the orb. Defaults to aqua (Aero blue). Pass any color.
+  tone?: "aqua" | "lime" | "rose" | "amber";
+  // Disable the slow rotation animation.
+  static?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const TONES: Record<NonNullable<GlossyOrbProps["tone"]>, { base: string; deep: string; glow: string }> = {
+  aqua:  { base: "#4FC3F7", deep: "#01579B", glow: "rgba(79, 195, 247, 0.55)" },
+  lime:  { base: "#DCFF66", deep: "#7CB342", glow: "rgba(198, 255, 0, 0.55)" },
+  rose:  { base: "#F48FB1", deep: "#AD1457", glow: "rgba(244, 143, 177, 0.55)" },
+  amber: { base: "#FFCA28", deep: "#E65100", glow: "rgba(255, 152, 0, 0.55)" },
+};
+
+export function GlossyOrb({
+  size = 96,
+  tone = "aqua",
+  static: noSpin,
+  className,
+  style,
+}: GlossyOrbProps) {
+  const t = TONES[tone];
+  return (
+    <div
+      className={className}
+      aria-hidden
+      style={{
+        width: size,
+        height: size,
+        borderRadius: "50%",
+        position: "relative",
+        background: `
+          radial-gradient(circle at 50% 28%, rgba(255,255,255,0.95) 0%, rgba(255,255,255,0.0) 32%),
+          radial-gradient(circle at 50% 95%, ${t.base} 0%, transparent 40%),
+          radial-gradient(circle at 50% 50%, ${t.base} 0%, ${t.deep} 100%)
+        `,
+        boxShadow: `
+          0 ${size * 0.12}px ${size * 0.28}px ${t.glow},
+          inset 0 ${size * 0.08}px ${size * 0.12}px rgba(255, 255, 255, 0.55),
+          inset 0 -${size * 0.08}px ${size * 0.16}px rgba(0, 0, 0, 0.22)
+        `,
+        animation: noSpin ? undefined : "ck-frutiger-orb-spin 18s linear infinite",
+        ...style,
+      }}
+    >
+      {/* Specular highlight — small bright cap top-left */}
+      <span
+        style={{
+          position: "absolute",
+          top: size * 0.1,
+          left: size * 0.22,
+          width: size * 0.36,
+          height: size * 0.22,
+          borderRadius: "50%",
+          background: "radial-gradient(ellipse, rgba(255,255,255,0.95) 0%, rgba(255,255,255,0) 70%)",
+        }}
+      />
+      <style>{`
+        @keyframes ck-frutiger-orb-spin {
+          0%   { transform: rotate(0deg); }
+          100% { transform: rotate(360deg); }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          [data-ck-glossy-orb] { animation: none !important; }
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/frutiger/SkyBackdrop.tsx

@@ -0,0 +1,114 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// Drop-in section backdrop. The frutiger chrome already paints the
+// page with a sky gradient — this component is for opt-in moments
+// inside other chromes (a hero banner under chrome="classic", a
+// preview area in the theming page) without flipping the whole app.
+
+export interface SkyBackdropProps {
+  children?: ReactNode;
+  // Add the floating sparkle particles. Defaults to true.
+  sparkles?: boolean;
+  // Add soft white cumulus blobs near the bottom. Defaults to true.
+  clouds?: boolean;
+  // Variant: dusk swaps the gradient for indigo→lavender→pink.
+  variant?: "day" | "dusk";
+  className?: string;
+  style?: CSSProperties;
+}
+
+const DAY_BG = "linear-gradient(180deg, #87CEEB 0%, #B3E5FC 45%, #E1F5FE 100%)";
+const DUSK_BG = "linear-gradient(180deg, #2E2280 0%, #6A4C93 40%, #F4A6CD 80%, #FFD8B1 100%)";
+
+export function SkyBackdrop({
+  children,
+  sparkles = true,
+  clouds = true,
+  variant = "day",
+  className,
+  style,
+}: SkyBackdropProps) {
+  return (
+    <div
+      className={className}
+      style={{
+        position: "relative",
+        overflow: "hidden",
+        background: variant === "dusk" ? DUSK_BG : DAY_BG,
+        ...style,
+      }}
+    >
+      {clouds && <Clouds variant={variant} />}
+      {sparkles && <Sparkles />}
+      <div style={{ position: "relative", zIndex: 2 }}>{children}</div>
+    </div>
+  );
+}
+
+function Clouds({ variant }: { variant: "day" | "dusk" }) {
+  const tint = variant === "dusk" ? "rgba(255, 220, 230, 0.5)" : "rgba(255, 255, 255, 0.6)";
+  return (
+    <div
+      aria-hidden
+      style={{
+        position: "absolute",
+        inset: 0,
+        background: `
+          radial-gradient(ellipse 280px 80px at 14% 78%, ${tint} 0%, transparent 70%),
+          radial-gradient(ellipse 360px 90px at 72% 86%, ${tint} 0%, transparent 70%),
+          radial-gradient(ellipse 200px 60px at 50% 92%, ${tint} 0%, transparent 70%)
+        `,
+        pointerEvents: "none",
+        zIndex: 1,
+      }}
+    />
+  );
+}
+
+function Sparkles() {
+  // 14 deterministic positions — random feels jittery on reload.
+  const dots = [
+    { x: 8, y: 22, s: 3, o: 0.85 },
+    { x: 18, y: 12, s: 2, o: 0.65 },
+    { x: 31, y: 32, s: 4, o: 0.9 },
+    { x: 44, y: 18, s: 2, o: 0.55 },
+    { x: 56, y: 42, s: 3, o: 0.7 },
+    { x: 68, y: 14, s: 2, o: 0.6 },
+    { x: 76, y: 30, s: 5, o: 0.8 },
+    { x: 88, y: 24, s: 2, o: 0.55 },
+    { x: 22, y: 56, s: 3, o: 0.55 },
+    { x: 38, y: 64, s: 2, o: 0.5 },
+    { x: 60, y: 60, s: 4, o: 0.7 },
+    { x: 82, y: 50, s: 2, o: 0.55 },
+    { x: 12, y: 42, s: 2, o: 0.5 },
+    { x: 50, y: 28, s: 2, o: 0.7 },
+  ];
+  return (
+    <div
+      aria-hidden
+      style={{
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        zIndex: 1,
+      }}
+    >
+      {dots.map((d, i) => (
+        <span
+          key={i}
+          style={{
+            position: "absolute",
+            left: `${d.x}%`,
+            top: `${d.y}%`,
+            width: d.s,
+            height: d.s,
+            borderRadius: "50%",
+            background: "#FFFFFF",
+            opacity: d.o,
+            boxShadow: `0 0 ${d.s * 4}px ${d.s * 1.5}px rgba(255, 255, 255, ${d.o * 0.55})`,
+          }}
+        />
+      ))}
+    </div>
+  );
+}

package/src/frutiger/index.ts

@@ -0,0 +1,2 @@
+export * from "./SkyBackdrop";
+export * from "./GlossyOrb";

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,80 @@
+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;
+        if (
+          tag === "INPUT" ||
+          tag === "TEXTAREA" ||
+          tag === "SELECT" ||
+          ae?.isContentEditable
+        ) {
+          return;
+        }
+      }
+      if (skipWhenModalOpen && document.querySelector('[role="dialog"]')) {
+        return;
+      }
+      handlerRef.current(e);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [key, mod, skipInputs, skipModifiers, skipWhenModalOpen, enabled]);
+}

package/src/hooks/useReducedMotion.ts

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,61 @@
+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/index.ts

@@ -0,0 +1,26 @@
+// Entry point — re-exports everything consumers need.
+// Components, hooks, theme, and helpers are organised under
+// /primitives, /layout, /actionbar, /command, /dialogs, /hooks,
+// /theme, /pwa, /lib. As the kit grows, each phase adds exports
+// here. Consumers pull individual modules (`import { Button }
+// from "@cosxai/ui"`) or copy source files directly per the
+// shadcn-style distribution model.
+
+export * from "./primitives";
+export * from "./lib/cn";
+export * from "./lib/time-utils";
+export * from "./theme";
+export * from "./hooks";
+export * from "./layout";
+export * from "./dialogs";
+export * from "./actionbar";
+export * from "./command";
+export * from "./pwa";
+export * from "./editorial";
+export * from "./neobrutalism";
+export * from "./ambient";
+export * from "./terminal";
+export * from "./bento";
+export * from "./frutiger";
+export * from "./riso";
+export * from "./sketch";

package/src/layout/Breadcrumb.tsx

@@ -0,0 +1,74 @@
+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>
+  );
+}

package/src/layout/LeftNavRail.tsx

@@ -0,0 +1,126 @@
+import { useEffect, type ReactNode, type CSSProperties } from "react";
+
+// Fixed-left vertical nav rail. Three slots — brand (top), children
+// (the nav body, scrollable), footer (avatar / collapse toggle).
+//
+// Owns the CSS var --ck-leftnav-width. Page content reads this var
+// to inset itself, so layouts react to the rail width changing
+// without prop-drilling.
+//
+// Stateless visually: collapsed is a boolean prop. State management
+// lives in useNavRailState(), which the parent owns; this keeps the
+// component pure and testable.
+
+export interface LeftNavRailProps {
+  brand?: ReactNode;
+  children: ReactNode;
+  footer?: ReactNode;
+  collapsed?: boolean;
+  // Expanded / collapsed widths in px. Defaults 256 / 56.
+  widthExpanded?: number;
+  widthCollapsed?: number;
+  className?: string;
+  // Hide entirely (e.g. on phone). When true, sets --ck-leftnav-width: 0.
+  hidden?: boolean;
+}
+
+export function LeftNavRail({
+  brand,
+  children,
+  footer,
+  collapsed = false,
+  widthExpanded = 256,
+  widthCollapsed = 56,
+  className,
+  hidden = false,
+}: LeftNavRailProps) {
+  const width = hidden ? 0 : collapsed ? widthCollapsed : widthExpanded;
+
+  // Stamp --ck-leftnav-width on documentElement so page-level
+  // layouts (Shell's marginLeft, fixed AgentRail, ActionBar's right
+  // inset) can read it without a context.
+  useEffect(() => {
+    document.documentElement.style.setProperty("--ck-leftnav-width", `${width}px`);
+    return () => {
+      // On unmount, clear to 0 so consumers without a rail don't inherit
+      // a stale inset.
+      document.documentElement.style.setProperty("--ck-leftnav-width", "0px");
+    };
+  }, [width]);
+
+  if (hidden) return null;
+
+  return (
+    <aside
+      data-ck-leftnav
+      className={className}
+      style={
+        {
+          position: "fixed",
+          left: 0,
+          top: 0,
+          bottom: 0,
+          width,
+          // Default to --ck-bg-surface so the rail blends seamlessly
+          // with the topbar + cards. Consumers wanting a tinted rail
+          // override via --ck-bg-sidebar in their own stylesheet or
+          // pass a className that sets background.
+          background: "var(--ck-bg-surface)",
+          borderRight: "1px solid var(--ck-border-subtle)",
+          display: "flex",
+          flexDirection: "column",
+          fontFamily: "var(--ck-font-sans)",
+          color: "var(--ck-text-primary)",
+          transition: "width var(--ck-dur-fast) var(--ck-ease), background-color 200ms var(--ck-ease)",
+          zIndex: 30,
+        } as CSSProperties
+      }
+    >
+      {brand && (
+        <div
+          style={{
+            // Match the topbar's height (Topbar stamps
+            // --ck-breadcrumb-height; default 64 px). Logo +
+            // crumbs sit on the same horizontal axis and the
+            // brand-area bottom rule aligns with the topbar's
+            // bottom rule — no per-app tuning.
+            height: "var(--ck-breadcrumb-height, 64px)",
+            padding: collapsed ? "0 4px" : "0 12px",
+            display: "flex",
+            alignItems: "center",
+            // Logo is brand mark, not nav item — centre it in both
+            // collapsed and expanded states so the visual anchor stays
+            // put across the width transition. Matches the centred
+            // favicon position when the rail is collapsed.
+            justifyContent: "center",
+            borderBottom: "1px solid var(--ck-border-subtle)",
+            transition: "padding var(--ck-dur-fast) var(--ck-ease)",
+            flexShrink: 0,
+          }}
+        >
+          {brand}
+        </div>
+      )}
+      <div
+        style={{
+          flex: 1,
+          minHeight: 0,
+          overflowY: "auto",
+          padding: collapsed ? "8px 4px" : "12px 8px",
+        }}
+      >
+        {children}
+      </div>
+      {footer && (
+        <div
+          style={{
+            padding: collapsed ? "8px 4px" : "12px 8px",
+            borderTop: "1px solid var(--ck-border-subtle)",
+          }}
+        >
+          {footer}
+        </div>
+      )}
+    </aside>
+  );
+}