@cueloop/client 0.1.0-alpha.3 → 0.1.0-alpha.30

package/src/components/primitives/Button.stories.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { DARK } from "../../theme";
+import type { Story, StoryMeta } from "../story";
+import { Button } from "./Button";
+import { Toolbar } from "./Toolbar";
+
+export const meta: StoryMeta = { title: "primitives/Button" };
+
+export const Variants: Story = {
+  render: () => (
+    <Toolbar>
+      <Button variant="solid" marginRight={2} onPress={() => {}}>
+        {" Save ⏎ "}
+      </Button>
+      <Button marginRight={2} onPress={() => {}}>
+        {" Cancel esc "}
+      </Button>
+      <Button variant="accent-text" onPress={() => {}}>
+        {"Submit review (2) ⏎"}
+      </Button>
+    </Toolbar>
+  ),
+  expectedColors: [DARK.accent, DARK.accentInk, DARK.textDim],
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <Button isDisabled onPress={() => {}}>
+      {" Edit "}
+    </Button>
+  ),
+};

package/src/components/primitives/Button.tsx

@@ -0,0 +1,44 @@
+/**
+ * Word-button: a pressable label. `onPress` unifies mouse and (future)
+ * keyboard activation; `isDisabled` swallows presses without changing the
+ * rendered label, so read-only affordances keep their place in the layout.
+ */
+
+import React from "react";
+import type { Theme } from "../../theme";
+import { useComponentTheme } from "../theme-context";
+
+export interface ButtonProps {
+  /** Unified activation: mouse release today, keyboard activation tomorrow. */
+  onPress: () => void;
+  isDisabled?: boolean;
+  /** solid = accent-filled call to action; plain = quiet word-button. */
+  variant?: "solid" | "plain" | "accent-text";
+  marginRight?: number;
+  theme?: Theme;
+  children: string;
+}
+
+export function Button({
+  onPress,
+  isDisabled = false,
+  variant = "plain",
+  marginRight,
+  theme,
+  children,
+}: ButtonProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const backgroundColor = variant === "solid" ? tokens.accent : undefined;
+  const foreground =
+    variant === "solid" ? tokens.accentInk : variant === "accent-text" ? tokens.accent : tokens.textDim;
+  return (
+    <box
+      style={{ backgroundColor, marginRight }}
+      onMouseUp={() => {
+        if (!isDisabled) onPress();
+      }}
+    >
+      <text fg={foreground}>{children}</text>
+    </box>
+  );
+}

package/src/components/primitives/Card.stories.tsx

@@ -0,0 +1,25 @@
+import React from "react";
+import { DARK } from "../../theme";
+import type { Story, StoryMeta } from "../story";
+import { Card } from "./Card";
+
+export const meta: StoryMeta = { title: "primitives/Card" };
+
+export const Titled: Story = {
+  render: () => (
+    <Card title=" a titled card " contentRows={2}>
+      <text>first content row</text>
+      <text>second content row</text>
+    </Card>
+  ),
+  expectedColors: [DARK.border, DARK.elevated],
+};
+
+export const AccentBorder: Story = {
+  render: () => (
+    <Card title=" accented " contentRows={1} borderColor={DARK.accent}>
+      <text>content</text>
+    </Card>
+  ),
+  expectedColors: [DARK.accent],
+};

package/src/components/primitives/Card.tsx

@@ -0,0 +1,59 @@
+/**
+ * Bordered rounded box with an optional title. The card owns the
+ * height-derivation rule: its height is always the declared content row
+ * count plus the two border rows, so layout math and the mounted box can
+ * never drift apart - border-collapse bugs die here.
+ */
+
+import React from "react";
+import type { Theme } from "../../theme";
+import { useComponentTheme } from "../theme-context";
+import { FRAME_BORDER_STYLE } from "./frame";
+
+export interface CardProps {
+  title?: string;
+  /** Number of content rows inside the border; the box adds the two border rows. */
+  contentRows: number;
+  borderColor?: string;
+  backgroundColor?: string;
+  marginLeft?: number;
+  marginRight?: number;
+  theme?: Theme;
+  children: React.ReactNode;
+}
+
+/** The one height rule: content rows plus the top and bottom border rows. */
+export function cardHeight(contentRows: number): number {
+  return contentRows + 2;
+}
+
+export function Card({
+  title,
+  contentRows,
+  borderColor,
+  backgroundColor,
+  marginLeft,
+  marginRight,
+  theme,
+  children,
+}: CardProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  return (
+    <box
+      style={{
+        height: cardHeight(contentRows),
+        marginLeft,
+        marginRight,
+        border: true,
+        borderStyle: FRAME_BORDER_STYLE,
+        borderColor: borderColor ?? tokens.border,
+        backgroundColor: backgroundColor ?? tokens.elevated,
+        flexDirection: "column",
+        paddingLeft: 1,
+      }}
+      title={title}
+    >
+      {children}
+    </box>
+  );
+}

package/src/components/primitives/Dialog.stories.tsx

@@ -0,0 +1,24 @@
+import React from "react";
+import { DARK } from "../../theme";
+import type { Story, StoryMeta } from "../story";
+import { Dialog } from "./Dialog";
+
+export const meta: StoryMeta = { title: "primitives/Dialog" };
+
+export const Open: Story = {
+  render: () => (
+    <Dialog isOpen title=" a modal " width={40} height={8}>
+      <text>dialog body content</text>
+    </Dialog>
+  ),
+  expectedColors: [DARK.accent, DARK.backdrop],
+  size: { width: 60, height: 16 },
+};
+
+export const Closed: Story = {
+  render: () => (
+    <Dialog isOpen={false} title=" hidden " width={40} height={8}>
+      <text>never rendered</text>
+    </Dialog>
+  ),
+};

package/src/components/primitives/Dialog.tsx

@@ -0,0 +1,53 @@
+/**
+ * Centered modal over a dimmed backdrop. The dialog fills the terminal with
+ * the backdrop token and centers a bordered panel; content composes inside.
+ * `isOpen` keeps the mount decision with the caller-visible prop vocabulary.
+ */
+
+import React from "react";
+import type { Theme } from "../../theme";
+import { useComponentTheme } from "../theme-context";
+import { FRAME_BORDER_STYLE } from "./frame";
+
+export interface DialogProps {
+  isOpen: boolean;
+  title?: string;
+  width: number;
+  height: number;
+  theme?: Theme;
+  children: React.ReactNode;
+}
+
+export function Dialog({ isOpen, title, width, height, theme, children }: DialogProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  if (!isOpen) return null;
+  return (
+    <box
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: "100%",
+        height: "100%",
+        backgroundColor: tokens.backdrop,
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <box
+        style={{
+          width,
+          height,
+          border: true,
+          borderStyle: FRAME_BORDER_STYLE,
+          borderColor: tokens.accent,
+          backgroundColor: tokens.panel,
+          flexDirection: "column",
+        }}
+        title={title}
+      >
+        {children}
+      </box>
+    </box>
+  );
+}

package/src/components/primitives/StatusBar.stories.tsx

@@ -0,0 +1,11 @@
+import React from "react";
+import { DARK } from "../../theme";
+import type { Story, StoryMeta } from "../story";
+import { StatusBar } from "./StatusBar";
+
+export const meta: StoryMeta = { title: "primitives/StatusBar" };
+
+export const HintLine: Story = {
+  render: () => <StatusBar>j/k move · v span · c comment · q quit</StatusBar>,
+  expectedColors: [DARK.panel, DARK.textDim],
+};

package/src/components/primitives/StatusBar.tsx

@@ -0,0 +1,22 @@
+/**
+ * One-row panel bar for the status/hint line. Content renders as dim text;
+ * callers pass richer spans as children when a segment needs another tone.
+ */
+
+import React from "react";
+import type { Theme } from "../../theme";
+import { useComponentTheme } from "../theme-context";
+
+export interface StatusBarProps {
+  theme?: Theme;
+  children: React.ReactNode;
+}
+
+export function StatusBar({ theme, children }: StatusBarProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  return (
+    <box style={{ height: 1, backgroundColor: tokens.panel, paddingLeft: 1 }}>
+      <text fg={tokens.textDim}>{children}</text>
+    </box>
+  );
+}

package/src/components/primitives/Tabs.stories.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+import { DARK } from "../../theme";
+import type { Story, StoryMeta } from "../story";
+import { Tab, TabList, Tabs } from "./Tabs";
+
+export const meta: StoryMeta = { title: "primitives/Tabs" };
+
+export const TwoTabs: Story = {
+  render: () => (
+    <Tabs selectedKey="review" onSelectionChange={() => {}}>
+      <TabList>
+        <Tab id="review">Review (2)</Tab>
+        <Tab id="agent">Agent</Tab>
+      </TabList>
+    </Tabs>
+  ),
+  expectedColors: [DARK.accent, DARK.textDim],
+};
+
+export const SecondSelected: Story = {
+  render: () => (
+    <Tabs selectedKey="agent" onSelectionChange={() => {}}>
+      <TabList>
+        <Tab id="review">Review (0)</Tab>
+        <Tab id="agent">Agent</Tab>
+      </TabList>
+    </Tabs>
+  ),
+};

package/src/components/primitives/Tabs.tsx

@@ -0,0 +1,97 @@
+/**
+ * Tabs / TabList / Tab over the native tab-select renderable. The composition
+ * follows the ARIA tabs pattern: Tabs owns the controlled selection
+ * (`selectedKey` + `onSelectionChange`), TabList renders the strip, Tab
+ * declares one item. Selection stays controlled from outside so the keyboard
+ * grammar (not the strip) remains the key owner; clicks map through the
+ * native tab geometry.
+ */
+
+import React, { createContext, useContext, useEffect, useRef } from "react";
+import type { MouseEvent, TabSelectRenderable } from "@opentui/core";
+import type { Theme } from "../../theme";
+import { useComponentTheme } from "../theme-context";
+
+interface TabsContextValue {
+  selectedKey: string;
+  onSelectionChange: (key: string) => void;
+  /** Text color of the selected tab; defaults to the accent token. */
+  selectedColor?: string;
+  theme?: Theme;
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+export interface TabsProps {
+  selectedKey: string;
+  onSelectionChange: (key: string) => void;
+  selectedColor?: string;
+  theme?: Theme;
+  children: React.ReactNode;
+}
+
+export function Tabs({ selectedKey, onSelectionChange, selectedColor, theme, children }: TabsProps): React.ReactNode {
+  return (
+    <TabsContext.Provider value={{ selectedKey, onSelectionChange, selectedColor, theme }}>
+      {children}
+    </TabsContext.Provider>
+  );
+}
+
+export interface TabProps {
+  id: string;
+  children: string;
+}
+
+/** Declarative item: TabList collects Tab children into the native strip. */
+export function Tab(_props: TabProps): React.ReactNode {
+  return null;
+}
+
+export interface TabListProps {
+  children: React.ReactNode;
+}
+
+export function TabList({ children }: TabListProps): React.ReactNode {
+  const tabs = useContext(TabsContext);
+  if (!tabs) throw new Error("TabList must render inside Tabs");
+  const tokens = useComponentTheme(tabs.theme);
+  const items: { id: string; label: string }[] = [];
+  React.Children.forEach(children, (child) => {
+    if (React.isValidElement<TabProps>(child) && typeof child.props.id === "string") {
+      items.push({ id: child.props.id, label: child.props.children });
+    }
+  });
+  const tabWidth = Math.max(...items.map((item) => item.label.length)) + 2;
+  const selectedIndex = Math.max(
+    0,
+    items.findIndex((item) => item.id === tabs.selectedKey),
+  );
+  const stripRef = useRef<TabSelectRenderable | null>(null);
+  // selection is controlled: mirror the selected key into the native strip
+  useEffect(() => {
+    stripRef.current?.setSelectedIndex(selectedIndex);
+  }, [selectedIndex, items.length]);
+  const onMouseUp = (event: MouseEvent): void => {
+    const strip = stripRef.current;
+    if (!strip) return;
+    const index = Math.floor((event.x - strip.x) / tabWidth);
+    const item = items[index];
+    if (item) tabs.onSelectionChange(item.id);
+  };
+  return (
+    <tab-select
+      ref={stripRef}
+      options={items.map((item) => ({ name: item.label, description: "", value: item.id }))}
+      tabWidth={tabWidth}
+      showUnderline={false}
+      showDescription={false}
+      showScrollArrows={false}
+      textColor={tokens.textDim}
+      selectedTextColor={tabs.selectedColor ?? tokens.accent}
+      selectedBackgroundColor={tokens.elevated}
+      onMouseUp={onMouseUp}
+      style={{ height: 1, width: tabWidth * items.length }}
+    />
+  );
+}

package/src/components/primitives/Toolbar.stories.tsx

@@ -0,0 +1,17 @@
+import React from "react";
+import type { Story, StoryMeta } from "../story";
+import { Button } from "./Button";
+import { Toolbar } from "./Toolbar";
+
+export const meta: StoryMeta = { title: "primitives/Toolbar" };
+
+export const ActionRow: Story = {
+  render: () => (
+    <Toolbar>
+      <Button variant="solid" marginRight={2} onPress={() => {}}>
+        {" Submit "}
+      </Button>
+      <Button onPress={() => {}}>{" Cancel "}</Button>
+    </Toolbar>
+  ),
+};

package/src/components/primitives/Toolbar.tsx

@@ -0,0 +1,14 @@
+/**
+ * Horizontal action row: children flow left to right on one row. The classic
+ * home of Button groups (Save/Cancel, Submit/Cancel).
+ */
+
+import React from "react";
+
+export interface ToolbarProps {
+  children: React.ReactNode;
+}
+
+export function Toolbar({ children }: ToolbarProps): React.ReactNode {
+  return <box style={{ flexDirection: "row", height: 1 }}>{children}</box>;
+}

package/src/components/primitives/frame.test.ts

@@ -0,0 +1,12 @@
+/**
+ * Locks the single frame border rule: every bordered frame reads this token,
+ * so a regression to square corners (or any other style) fails here first,
+ * before the slower VRT snapshots catch it. Decision: rounded (issue #116).
+ */
+
+import { expect, test } from "bun:test";
+import { FRAME_BORDER_STYLE } from "./frame";
+
+test("frames use the rounded border style", () => {
+  expect(FRAME_BORDER_STYLE).toBe("rounded");
+});

package/src/components/primitives/frame.ts

@@ -0,0 +1,14 @@
+/**
+ * The one frame border rule for the design system. Every bordered frame -
+ * cards, dialogs, and the stories gallery chrome - reads its corner style
+ * from FRAME_BORDER_STYLE, so the rounded-corner decision lives in a single
+ * place and can never drift between frames. Buttons stay text-first and
+ * borderless: the frame they sit in carries the border, not the button.
+ *
+ * Decision: rounded on the frames, not on the buttons (issue #116).
+ */
+
+import type { BorderStyle } from "@opentui/core";
+
+/** Corner style shared by every bordered frame in the app. */
+export const FRAME_BORDER_STYLE: BorderStyle = "rounded";

package/src/components/stories-app.tsx

@@ -0,0 +1,95 @@
+/**
+ * The interactive stories catalog (`bun run stories`): a left list of
+ * component modules (j/k), h/l cycling through the module's stories, and the
+ * selected story rendered live in the preview pane. The same story objects
+ * back the snapshot harness - what this TUI shows is what the tests assert.
+ */
+
+import React, { useMemo, useState } from "react";
+import { createCliRenderer } from "@opentui/core";
+import { createRoot, useKeyboard } from "@opentui/react";
+import { DARK } from "../theme";
+import { ThemeProvider } from "./theme-context";
+import { loadStories, type LoadedStory } from "./story";
+import { FRAME_BORDER_STYLE } from "./primitives/frame";
+
+function StoriesApp({ stories, onExit }: { stories: LoadedStory[]; onExit: () => void }): React.ReactNode {
+  const moduleTitles = useMemo(() => [...new Set(stories.map((story) => story.moduleTitle))], [stories]);
+  const [moduleIndex, setModuleIndex] = useState(0);
+  const [storyIndex, setStoryIndex] = useState(0);
+  const moduleTitle = moduleTitles[moduleIndex]!;
+  const moduleStories = stories.filter((story) => story.moduleTitle === moduleTitle);
+  const current = moduleStories[Math.min(storyIndex, moduleStories.length - 1)]!;
+
+  useKeyboard((key) => {
+    if (key.name === "q") onExit();
+    else if (key.name === "j" || key.name === "down") {
+      setModuleIndex((index) => Math.min(moduleTitles.length - 1, index + 1));
+      setStoryIndex(0);
+    } else if (key.name === "k" || key.name === "up") {
+      setModuleIndex((index) => Math.max(0, index - 1));
+      setStoryIndex(0);
+    } else if (key.name === "l" || key.name === "right") {
+      setStoryIndex((index) => (index + 1) % moduleStories.length);
+    } else if (key.name === "h" || key.name === "left") {
+      setStoryIndex((index) => (index - 1 + moduleStories.length) % moduleStories.length);
+    }
+  });
+
+  return (
+    <ThemeProvider theme={DARK}>
+      <box style={{ flexDirection: "column", width: "100%", height: "100%", backgroundColor: DARK.bg }}>
+        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
+          <text fg={DARK.text}>
+            <span fg={DARK.accent}>cueloop stories</span>
+            <span fg={DARK.textDim}>
+              {" "}· {moduleTitle} / {current.storyName}
+            </span>
+          </text>
+        </box>
+        <box style={{ flexDirection: "row", flexGrow: 1 }}>
+          <box style={{ width: 28, backgroundColor: DARK.panel, flexDirection: "column", paddingLeft: 1, paddingTop: 1 }}>
+            {moduleTitles.map((title, index) => (
+              <text key={title} fg={index === moduleIndex ? DARK.accent : DARK.textMuted}>
+                {index === moduleIndex ? "▸ " : "  "}
+                {title}
+              </text>
+            ))}
+          </box>
+          <box
+            style={{
+              flexGrow: 1,
+              flexDirection: "column",
+              border: true,
+              borderStyle: FRAME_BORDER_STYLE,
+              borderColor: DARK.border,
+            }}
+            title={` ${current.storyName} (${moduleStories.indexOf(current) + 1}/${moduleStories.length}) `}
+          >
+            {/* remount per story so component-local state never leaks across */}
+            <box key={`${moduleTitle}/${current.storyName}`} style={{ flexGrow: 1, flexDirection: "column" }}>
+              {current.story.render()}
+            </box>
+          </box>
+        </box>
+        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
+          <text fg={DARK.textDim}>j/k component · h/l story · q quit</text>
+        </box>
+      </box>
+    </ThemeProvider>
+  );
+}
+
+if (import.meta.main) {
+  const stories = await loadStories();
+  const renderer = await createCliRenderer();
+  createRoot(renderer).render(
+    <StoriesApp
+      stories={stories}
+      onExit={() => {
+        renderer.destroy();
+        queueMicrotask(() => process.exit(0));
+      }}
+    />,
+  );
+}

package/src/components/stories.test.tsx

@@ -0,0 +1,56 @@
+/**
+ * The catalog IS the regression suite: every exported story renders in
+ * a virtual terminal, its char frame snapshots, and its declared colors must
+ * appear among the styled spans. A component file without a colocated
+ * stories file fails the harness, so the safety net cannot silently thin.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import { RGBA } from "@opentui/core";
+import { componentFilesMissingStories, loadStories } from "./story";
+
+const stories = await loadStories();
+
+function hexOf(color: RGBA): string {
+  const [red, green, blue] = color.toInts();
+  return "#" + [red, green, blue].map((part) => part!.toString(16).padStart(2, "0")).join("");
+}
+
+describe("stories catalog", () => {
+  test("every component file ships stories", () => {
+    expect(componentFilesMissingStories()).toEqual([]);
+  });
+
+  test("the catalog is not empty", () => {
+    expect(stories.length).toBeGreaterThan(0);
+  });
+
+  for (const { moduleTitle, storyName, story } of stories) {
+    test(`${moduleTitle}/${storyName} renders, snapshots, and carries its colors`, async () => {
+      // Arrange
+      const size = story.size ?? { width: 80, height: 24 };
+
+      // Act
+      const setup = await testRender(story.render(), size);
+      await setup.waitForVisualIdle();
+      const frame = setup.captureCharFrame();
+
+      // Assert
+      expect(frame).toMatchSnapshot(`${moduleTitle}/${storyName}`);
+      if (story.expectedColors?.length) {
+        const seenColors = new Set<string>();
+        for (const line of setup.captureSpans().lines) {
+          for (const span of line.spans) {
+            seenColors.add(hexOf(span.fg));
+            seenColors.add(hexOf(span.bg));
+          }
+        }
+        for (const expectedColor of story.expectedColors) {
+          expect(seenColors).toContain(expectedColor.toLowerCase());
+        }
+      }
+      setup.renderer.destroy();
+    });
+  }
+});