@cosxai/ui 0.1.0

package/src/dialogs/Modal.tsx

@@ -0,0 +1,204 @@
+import { useEffect, type ReactNode, type CSSProperties } from "react";
+import { createPortal } from "react-dom";
+
+// Modal base. Portals to document.body so it escapes ancestor
+// stacking contexts. Closes on Esc + backdrop click (both opt-out).
+// Caller owns open state and slots in the header/body/footer.
+//
+// Provides three sub-components for compositional layout:
+//   - <Modal>          — the host (backdrop + card + close binding)
+//   - <ModalHeader>    — sticky-ish top with title + optional close X
+//   - <ModalBody>      — scrollable middle region
+//   - <ModalFooter>    — sticky-ish bottom (buttons)
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  // Disables close on backdrop click + Escape. Useful for blocking
+  // dialogs that must be resolved via an explicit button.
+  dismissable?: boolean;
+  // Width preset OR raw px. Default "md" (440 px).
+  maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | number;
+  // Inline style override for the card.
+  cardStyle?: CSSProperties;
+  children: ReactNode;
+  // Optional aria-labelled-by for screen readers (point at the
+  // ModalHeader title's id).
+  labelledBy?: string;
+}
+
+const WIDTHS = { sm: 340, md: 440, lg: 560, xl: 720, "2xl": 880, "3xl": 1024, "4xl": 1200, "5xl": 1440 };
+
+export function Modal({
+  open,
+  onClose,
+  dismissable = true,
+  maxWidth = "md",
+  cardStyle,
+  children,
+  labelledBy,
+}: ModalProps) {
+  useEffect(() => {
+    if (!open || !dismissable) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onClose();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, dismissable, onClose]);
+
+  // Lock body scroll while open so the backdrop doesn't reveal
+  // a scrolling page underneath.
+  useEffect(() => {
+    if (!open) return;
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+
+  if (!open) return null;
+  const width = typeof maxWidth === "number" ? maxWidth : WIDTHS[maxWidth];
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={labelledBy}
+      style={{
+        position: "fixed",
+        inset: 0,
+        background: "rgba(10, 14, 26, 0.6)",
+        backdropFilter: "blur(2px)",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        padding: 16,
+        zIndex: 100,
+      }}
+      onMouseDown={(e) => {
+        // Backdrop click closes; clicks inside the card stopPropagation.
+        if (dismissable && e.target === e.currentTarget) onClose();
+      }}
+      className="ck-anim-fade"
+    >
+      <div
+        style={{
+          width: "100%",
+          maxWidth: width,
+          maxHeight: "calc(100vh - 32px)",
+          background: "var(--ck-bg-surface)",
+          border: "1px solid var(--ck-border-subtle)",
+          borderRadius: "var(--ck-radius-md)",
+          boxShadow: "var(--ck-shadow-3)",
+          display: "flex",
+          flexDirection: "column",
+          overflow: "hidden",
+          fontFamily: "var(--ck-font-sans)",
+          color: "var(--ck-text-primary)",
+          ...cardStyle,
+        }}
+        className="ck-anim-popover"
+      >
+        {children}
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+// ---------- Slot components ----------
+
+export interface ModalHeaderProps {
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  onClose?: () => void;
+  titleId?: string;
+}
+
+export function ModalHeader({ title, subtitle, onClose, titleId }: ModalHeaderProps) {
+  if (!title && !subtitle && !onClose) return null;
+  return (
+    <header
+      style={{
+        padding: "16px 20px",
+        borderBottom: "1px solid var(--ck-border-subtle)",
+        display: "flex",
+        alignItems: "flex-start",
+        gap: 12,
+      }}
+    >
+      <div style={{ flex: 1, minWidth: 0 }}>
+        {title && (
+          <h2
+            id={titleId}
+            style={{
+              font: "500 16px/1.3 var(--ck-font-sans)",
+              margin: 0,
+              color: "var(--ck-text-primary)",
+            }}
+          >
+            {title}
+          </h2>
+        )}
+        {subtitle && (
+          <p
+            style={{
+              font: "400 12px/1.4 var(--ck-font-sans)",
+              color: "var(--ck-text-tertiary)",
+              margin: "4px 0 0",
+            }}
+          >
+            {subtitle}
+          </p>
+        )}
+      </div>
+      {onClose && (
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close"
+          style={{
+            border: "none",
+            background: "transparent",
+            color: "var(--ck-text-tertiary)",
+            cursor: "pointer",
+            fontSize: 18,
+            lineHeight: 1,
+            padding: 2,
+          }}
+        >
+          ×
+        </button>
+      )}
+    </header>
+  );
+}
+
+export function ModalBody({ children }: { children: ReactNode }) {
+  return (
+    <div style={{ flex: 1, minHeight: 0, overflowY: "auto", padding: "20px" }}>
+      {children}
+    </div>
+  );
+}
+
+export function ModalFooter({ children }: { children: ReactNode }) {
+  return (
+    <footer
+      style={{
+        padding: "14px 20px",
+        borderTop: "1px solid var(--ck-border-subtle)",
+        display: "flex",
+        justifyContent: "flex-end",
+        gap: 8,
+        background: "var(--ck-bg-surface-2)",
+      }}
+    >
+      {children}
+    </footer>
+  );
+}

package/src/dialogs/Toast.tsx

@@ -0,0 +1,85 @@
+import { useEffect } from "react";
+import { createPortal } from "react-dom";
+import type { ToastOptions } from "./types";
+
+interface ToastItem extends ToastOptions {
+  id: number;
+}
+
+// Toast stack — fixed bottom-right corner. Each toast auto-dismisses
+// after durationMs (default 4000). Stack grows upward.
+
+const KIND_BG = {
+  info: "var(--ck-bg-surface)",
+  success: "var(--ck-success-muted)",
+  error: "var(--ck-critical-muted)",
+};
+const KIND_BORDER = {
+  info: "var(--ck-border-strong)",
+  success: "var(--ck-success)",
+  error: "var(--ck-critical)",
+};
+const KIND_TEXT = {
+  info: "var(--ck-text-primary)",
+  success: "var(--ck-success)",
+  error: "var(--ck-critical)",
+};
+
+export function ToastStack({
+  toasts,
+  onDismiss,
+}: {
+  toasts: ToastItem[];
+  onDismiss: (id: number) => void;
+}) {
+  return createPortal(
+    <div
+      style={{
+        position: "fixed",
+        bottom: 16,
+        right: 16,
+        zIndex: 110,
+        display: "flex",
+        flexDirection: "column",
+        gap: 8,
+        maxWidth: 360,
+        pointerEvents: "none",
+      }}
+    >
+      {toasts.map((t) => (
+        <ToastRow key={t.id} item={t} onDismiss={() => onDismiss(t.id)} />
+      ))}
+    </div>,
+    document.body,
+  );
+}
+
+function ToastRow({ item, onDismiss }: { item: ToastItem; onDismiss: () => void }) {
+  const kind = item.kind ?? "info";
+  const duration = item.durationMs ?? 4000;
+  useEffect(() => {
+    const timer = setTimeout(onDismiss, duration);
+    return () => clearTimeout(timer);
+  }, [duration, onDismiss]);
+  return (
+    <div
+      className="ck-anim-slide-left"
+      style={{
+        pointerEvents: "auto",
+        padding: "12px 14px",
+        background: KIND_BG[kind],
+        border: `1px solid ${KIND_BORDER[kind]}`,
+        borderRadius: "var(--ck-radius-md)",
+        boxShadow: "var(--ck-shadow-2)",
+        color: KIND_TEXT[kind],
+        font: "400 13px/1.4 var(--ck-font-sans)",
+        cursor: "pointer",
+      }}
+      onClick={onDismiss}
+    >
+      {item.message}
+    </div>
+  );
+}
+
+export type { ToastItem };

package/src/dialogs/dialogs-context.ts

@@ -0,0 +1,6 @@
+import { createContext } from "react";
+import type { DialogsApi } from "./types";
+
+// React Fast Refresh requires component modules to export only
+// components — same reason ThemeContext lives in its own file.
+export const DialogsContext = createContext<DialogsApi | null>(null);

package/src/dialogs/index.ts

@@ -0,0 +1,10 @@
+export { Modal, ModalHeader, ModalBody, ModalFooter } from "./Modal";
+export type { ModalProps, ModalHeaderProps } from "./Modal";
+export { DialogsProvider } from "./DialogsProvider";
+export { useDialogs } from "./useDialogs";
+export type {
+  ConfirmOptions,
+  PromptOptions,
+  ToastOptions,
+  DialogsApi,
+} from "./types";

package/src/dialogs/types.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+
+export interface ConfirmOptions {
+  title: string;
+  message?: ReactNode;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  // Renders the confirm button as the critical tone.
+  danger?: boolean;
+  // When set, the user must type this string into a confirmation
+  // field before confirm is enabled. Case-insensitive.
+  confirmationText?: string;
+}
+
+export interface PromptOptions {
+  title: string;
+  message?: ReactNode;
+  defaultValue?: string;
+  placeholder?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  // Returning a string treats it as a validation error message;
+  // returning null/undefined accepts the input.
+  validate?: (value: string) => string | null | undefined;
+}
+
+export interface ToastOptions {
+  kind?: "info" | "success" | "error";
+  message: ReactNode;
+  durationMs?: number;
+}
+
+export interface DialogsApi {
+  confirm: (opts: ConfirmOptions) => Promise<boolean>;
+  prompt: (opts: PromptOptions) => Promise<string | null>;
+  toast: (opts: ToastOptions) => void;
+}

package/src/dialogs/useDialogs.ts

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+import { DialogsContext } from "./dialogs-context";
+
+export function useDialogs() {
+  const ctx = useContext(DialogsContext);
+  if (!ctx) throw new Error("useDialogs must be used within <DialogsProvider>");
+  return ctx;
+}

package/src/editorial/EditorialSpotlight.tsx

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

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

@@ -0,0 +1,33 @@
+// "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

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

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

@@ -0,0 +1,10 @@
+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";