@cosxai/ui 0.1.0

package/src/terminal/AsciiBox.tsx

@@ -0,0 +1,65 @@
+import type { ReactNode, CSSProperties } from "react";
+
+// Bordered block with an ASCII-style title cut into the top
+// border — `╭─ logs ──╮`. Implementation uses a regular CSS
+// border + an absolutely-positioned title that masks a slice of
+// the border with the page background.
+//
+// Looks best under terminal chrome but works under any —
+// consumers can use it as a "labelled block" anywhere.
+
+export interface AsciiBoxProps {
+  // Title text shown cut into the top border.
+  title?: string;
+  children: ReactNode;
+  // px padding inside the body. Default 14.
+  padding?: number;
+  // Background colour to use for the title mask. Defaults to
+  // the surrounding canvas. Override to match a parent surface
+  // (e.g. when the box sits on a card).
+  maskBg?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function AsciiBox({
+  title,
+  children,
+  padding = 14,
+  maskBg = "var(--ck-bg-canvas)",
+  className,
+  style,
+}: AsciiBoxProps) {
+  return (
+    <div
+      className={className}
+      style={{
+        position: "relative",
+        border: "1px solid var(--ck-border-subtle)",
+        borderRadius: 2,
+        padding,
+        fontFamily: "var(--ck-font-mono)",
+        ...style,
+      }}
+    >
+      {title && (
+        <span
+          aria-hidden
+          style={{
+            position: "absolute",
+            top: -8,
+            left: 12,
+            padding: "0 6px",
+            background: maskBg,
+            color: "var(--ck-text-secondary)",
+            font: "500 11px/1 var(--ck-font-mono)",
+            letterSpacing: 0,
+          }}
+        >
+          ─ {title} ─
+        </span>
+      )}
+      {children}
+    </div>
+  );
+}

package/src/terminal/BrailleSpinner.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react";
+
+// Braille-pattern spinner — the canonical TUI activity indicator.
+// 10-frame cycle at 80 ms per frame ≈ 12.5 fps, which reads as
+// the same gentle rotation you see in `npm install` or
+// `gum spin`. Render inline anywhere you'd otherwise reach for a
+// CSS circular spinner — they don't belong under this chrome.
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface BrailleSpinnerProps {
+  // Frame interval in ms. Default 80.
+  intervalMs?: number;
+  // Stop / start cycling. Default true.
+  active?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export function BrailleSpinner({
+  intervalMs = 80,
+  active = true,
+  className,
+  style,
+}: BrailleSpinnerProps) {
+  const [i, setI] = useState(0);
+  useEffect(() => {
+    if (!active) return;
+    const t = setInterval(() => setI((x) => (x + 1) % FRAMES.length), intervalMs);
+    return () => clearInterval(t);
+  }, [intervalMs, active]);
+  return (
+    <span
+      aria-label="loading"
+      className={className}
+      style={{
+        fontFamily: "var(--ck-font-mono)",
+        display: "inline-block",
+        width: "1ch",
+        ...style,
+      }}
+    >
+      {FRAMES[i]}
+    </span>
+  );
+}

package/src/terminal/index.ts

@@ -0,0 +1,4 @@
+export { BrailleSpinner } from "./BrailleSpinner";
+export type { BrailleSpinnerProps } from "./BrailleSpinner";
+export { AsciiBox } from "./AsciiBox";
+export type { AsciiBoxProps } from "./AsciiBox";

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,93 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import { ThemeContext } from "./theme-context";
+import type { Theme, Chrome, ThemeContextValue } from "./types";
+
+const DEFAULT_THEME_KEY = "ck-theme";
+const DEFAULT_CHROME_KEY = "ck-chrome";
+
+function readStored<T extends string>(
+  key: string,
+  allowed: readonly T[],
+): T | null {
+  if (typeof window === "undefined") return null;
+  const v = window.localStorage.getItem(key);
+  return allowed.includes(v as T) ? (v as T) : null;
+}
+
+function preferredTheme(defaultTheme: Theme | "system"): Theme {
+  if (defaultTheme !== "system") return defaultTheme;
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function applyTheme(theme: Theme, storageKey: string) {
+  document.documentElement.setAttribute("data-ck-theme", theme);
+  window.localStorage.setItem(storageKey, theme);
+}
+
+function applyChrome(chrome: Chrome, storageKey: string) {
+  document.documentElement.setAttribute("data-ck-chrome", chrome);
+  window.localStorage.setItem(storageKey, chrome);
+}
+
+export interface ThemeProviderProps {
+  children: ReactNode;
+  // Initial theme if nothing's in localStorage. "system" reads
+  // `prefers-color-scheme`; explicit "light" / "dark" forces it.
+  defaultTheme?: Theme | "system";
+  defaultChrome?: Chrome;
+  // localStorage keys — override these per-consumer-app so a host
+  // page with multiple sub-apps doesn't collide.
+  themeStorageKey?: string;
+  chromeStorageKey?: string;
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = "system",
+  defaultChrome = "seamless",
+  themeStorageKey = DEFAULT_THEME_KEY,
+  chromeStorageKey = DEFAULT_CHROME_KEY,
+}: ThemeProviderProps) {
+  // Initial values match what getInlineThemeScript() would have
+  // painted on the <html> element pre-mount, so the React tree
+  // hydrates without a flash.
+  const [theme, setThemeState] = useState<Theme>(() => {
+    const stored = readStored<Theme>(themeStorageKey, ["light", "dark"]);
+    return stored ?? preferredTheme(defaultTheme);
+  });
+  const [chrome, setChromeState] = useState<Chrome>(() => {
+    const stored = readStored<Chrome>(chromeStorageKey, ["classic", "seamless"]);
+    return stored ?? defaultChrome;
+  });
+
+  // Mirror state → DOM. Inline script already set the attribute
+  // pre-mount; this useEffect handles subsequent runtime changes.
+  useEffect(() => {
+    applyTheme(theme, themeStorageKey);
+  }, [theme, themeStorageKey]);
+
+  useEffect(() => {
+    applyChrome(chrome, chromeStorageKey);
+  }, [chrome, chromeStorageKey]);
+
+  const setTheme = useCallback((next: Theme) => setThemeState(next), []);
+  const setChrome = useCallback((next: Chrome) => setChromeState(next), []);
+  const toggleTheme = useCallback(
+    () => setThemeState((t) => (t === "dark" ? "light" : "dark")),
+    [],
+  );
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({ theme, setTheme, toggleTheme, chrome, setChrome }),
+    [theme, setTheme, toggleTheme, chrome, setChrome],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}

package/src/theme/index.ts

@@ -0,0 +1,5 @@
+export { ThemeProvider } from "./ThemeProvider";
+export type { ThemeProviderProps } from "./ThemeProvider";
+export { useTheme } from "./useTheme";
+export { getInlineThemeScript } from "./inline-script";
+export type { Theme, Chrome, ThemeContextValue } from "./types";

package/src/theme/inline-script.ts

@@ -0,0 +1,36 @@
+import type { Theme, Chrome } from "./types";
+
+// Pre-mount inline script generator. Paste the returned string
+// into a <script> tag in your index.html <head> so the data-ck-*
+// attributes are set before React hydrates — prevents a white-
+// flash on dark sessions. Pass the same keys you pass to
+// <ThemeProvider> so localStorage stays in sync.
+//
+// Lives in its own file (not co-located with ThemeProvider) so
+// React Fast Refresh stays happy — Vite's plugin-react requires
+// modules to export only components, and mixing this helper into
+// the same file would silently degrade HMR into full reloads (and
+// take the data router's in-memory state with it on every save).
+
+export function getInlineThemeScript(opts: {
+  themeStorageKey?: string;
+  chromeStorageKey?: string;
+  defaultTheme?: Theme | "system";
+  defaultChrome?: Chrome;
+} = {}): string {
+  const t = JSON.stringify(opts.themeStorageKey ?? "ck-theme");
+  const c = JSON.stringify(opts.chromeStorageKey ?? "ck-chrome");
+  const dt = JSON.stringify(opts.defaultTheme ?? "system");
+  const dc = JSON.stringify(opts.defaultChrome ?? "seamless");
+  return `(function(){try{
+    var t=localStorage.getItem(${t});
+    if(t!=="light"&&t!=="dark"){
+      var d=${dt};
+      t=d==="system"?(matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"):d;
+    }
+    document.documentElement.setAttribute("data-ck-theme",t);
+    var c=localStorage.getItem(${c});
+    if(c!=="classic"&&c!=="seamless")c=${dc};
+    document.documentElement.setAttribute("data-ck-chrome",c);
+  }catch(e){}})();`;
+}

package/src/theme/theme-context.ts

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+import type { ThemeContextValue } from "./types";
+
+// React Fast Refresh requires component modules to export only
+// components. The context object + the hook must therefore live
+// in their own files; ThemeProvider.tsx imports from here.
+export const ThemeContext = createContext<ThemeContextValue | null>(null);

package/src/theme/types.ts

@@ -0,0 +1,22 @@
+// Theme axes. Light/dark is the conventional dark-mode toggle.
+// Chrome ("classic" vs "seamless") is an orthogonal style — classic
+// has visible borders + subtle dividers, seamless flattens them and
+// relies on background shifts for layering. Both axes are applied
+// as data attributes on <html>: data-ck-theme, data-ck-chrome.
+
+export type Theme = "light" | "dark";
+
+// Built-in chromes ship with the kit; custom strings are also
+// allowed at runtime (the kit just stamps the value onto
+// `data-ck-chrome`, your CSS supplies the overrides). The
+// `(string & {})` trick preserves autocomplete for the built-ins
+// while widening the union to any string for custom chromes.
+export type Chrome = "classic" | "seamless" | "editorial" | "neobrutalism" | "ambient" | "swiss" | "terminal" | "bento" | "frutiger" | "riso" | "sketch" | (string & {});
+
+export interface ThemeContextValue {
+  theme: Theme;
+  setTheme: (next: Theme) => void;
+  toggleTheme: () => void;
+  chrome: Chrome;
+  setChrome: (next: Chrome) => void;
+}

package/src/theme/useTheme.ts

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