@sragatiping/cuboid 0.1.0 → 0.1.4

package/dist/components/ApiResponseViewer/ApiResponseViewer.d.ts

@@ -0,0 +1,24 @@
+import { JsonCodeViewProps } from '../CodeBlock';
+import { CubeTheme } from '../../theme/types';
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export type ApiResponseHeaders = Record<string, string> | ReadonlyArray<readonly [string, string]>;
+export interface ApiResponseViewerProps {
+    /** Parsed response body — rendered with {@link JsonCodeView}. */
+    body: unknown;
+    /** HTTP status code. */
+    status: number;
+    method?: HttpMethod;
+    url?: string;
+    headers?: ApiResponseHeaders;
+    /** Round-trip duration in milliseconds. */
+    durationMs?: number;
+    theme?: CubeTheme;
+    /** Props forwarded to the body {@link JsonCodeView} (except `data`). */
+    codeView?: Omit<JsonCodeViewProps, "data">;
+    "aria-label"?: string;
+}
+/**
+ * HTTP response shell — status summary, optional headers, JSON body via
+ * {@link JsonCodeView}. Intended for API debug panels and network inspectors.
+ */
+export declare function ApiResponseViewer({ body, status, method, url, headers, durationMs, theme, codeView, "aria-label": ariaLabel, }: ApiResponseViewerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ApiResponseViewer/ApiResponseViewer.stories.d.ts

@@ -0,0 +1,13 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { ApiResponseViewer } from './ApiResponseViewer';
+declare const meta: Meta<typeof ApiResponseViewer>;
+export default meta;
+type Story = StoryObj<typeof ApiResponseViewer>;
+/** Dev-server diagnostics returned from a local tooling endpoint. */
+export declare const DevServerDiagnostics: Story;
+/** Compact success payload without headers. */
+export declare const Success200: Story;
+/** Client error with minimal detail. */
+export declare const NotFound404: Story;
+/** Server error response. */
+export declare const ServerError500: Story;

package/dist/components/ApiResponseViewer/index.d.ts

@@ -0,0 +1,3 @@
+export { ApiResponseViewer } from './ApiResponseViewer';
+export type { ApiResponseHeaders, ApiResponseViewerProps, HttpMethod, } from './ApiResponseViewer';
+export { statusPillShade, statusReasonPhrase, methodPillShade } from './status';

package/dist/components/ApiResponseViewer/status.d.ts

@@ -0,0 +1,8 @@
+import { PillShade } from '../core/Pill';
+import { HttpMethod } from './ApiResponseViewer';
+/** Maps HTTP methods to pill shades — read vs write semantics (Postman-style). */
+export declare function methodPillShade(method: HttpMethod): PillShade;
+/** Maps HTTP status code ranges to pill shades for quick visual scanning. */
+export declare function statusPillShade(status: number): PillShade;
+/** Common reason phrase for a status code, or the numeric code as a string. */
+export declare function statusReasonPhrase(status: number): string;

package/dist/components/CodeBlock/CodeBlock.d.ts

@@ -0,0 +1,18 @@
+import { CodeSurfaceProps } from './CodeSurface';
+import { CodeBlockLanguage } from './highlight';
+export interface CodeBlockProps extends Pick<CodeSurfaceProps, "height" | "maxHeight" | "theme" | "linkify" | "onLinkClick" | "watchlist" | "defaultWatchlist" | "onWatchlistChange" | "surfaceVariant" | "aria-label"> {
+    /** Source text to display. */
+    code: string;
+    /**
+     * Highlighting grammar.
+     * @default "text"
+     */
+    language?: CodeBlockLanguage;
+}
+/**
+ * Generic source display — JavaScript, HTML, CSS, and plain text.
+ * Tokenizes source into lines and renders via {@link CodeSurface}.
+ *
+ * For JSON API payloads use {@link JsonCodeView} instead.
+ */
+export declare function CodeBlock({ code, language, height, maxHeight, theme, linkify, onLinkClick, watchlist, defaultWatchlist, onWatchlistChange, surfaceVariant, "aria-label": ariaLabel, }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/CodeBlock/CodeBlock.stories.d.ts

@@ -0,0 +1,12 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { CodeBlock } from './CodeBlock';
+declare const meta: Meta<typeof CodeBlock>;
+export default meta;
+type Story = StoryObj<typeof CodeBlock>;
+export declare const JavaScript: Story;
+export declare const TypeScript: Story;
+export declare const Html: Story;
+export declare const Css: Story;
+export declare const PlainText: Story;
+/** ~200 lines — windowed rendering inside a fixed height. */
+export declare const LargeVirtualised: Story;

package/dist/components/CodeBlock/CodeSurface.d.ts

@@ -0,0 +1,48 @@
+import { default as React } from 'react';
+import { CubeTheme } from '../../theme/types';
+import { SurfaceLine, SurfaceToken } from './types';
+export interface CodeSurfaceGutterIcons {
+    collapsed?: React.ReactNode;
+    expanded?: React.ReactNode;
+}
+export interface CodeSurfaceProps {
+    /** Visible lines to render (may be a window when virtualised). */
+    lines: SurfaceLine[];
+    /**
+     * Total line count used to size the line-number gutter.
+     * Often the fully-expanded count, which can differ from `lines.length`
+     * when nodes are collapsed.
+     */
+    gutterLineCount: number;
+    /**
+     * Optional per-token colour override. When omitted, syntax colours come from
+     * theme CSS variables via {@link CodeSurface.module.css}.
+     */
+    tokenColor?: (type: string) => string;
+    onToggleCollapse?: (collapseKey: string) => void;
+    gutterIcons?: CodeSurfaceGutterIcons;
+    indent?: string;
+    height?: string;
+    maxHeight?: string;
+    /** Render detected URLs and emails as clickable links. @default true */
+    linkify?: boolean;
+    onLinkClick?: (href: string, token: SurfaceToken, event: React.MouseEvent<HTMLAnchorElement>) => void;
+    /**
+     * 1-indexed line numbers on the watchlist (controlled).
+     * Pass with `onWatchlistChange` or use `defaultWatchlist` for uncontrolled mode.
+     */
+    watchlist?: ReadonlySet<number> | readonly number[];
+    /** Initial watchlist when uncontrolled. */
+    defaultWatchlist?: readonly number[];
+    /** Called when the user toggles a watchlist marker in the gutter. Enables watchlist UI. */
+    onWatchlistChange?: (watchlist: Set<number>) => void;
+    theme?: CubeTheme;
+    /**
+     * `embedded` omits border and radius — use when nesting inside a parent shell
+     * (e.g. {@link ApiResponseViewer}).
+     * @default "default"
+     */
+    surfaceVariant?: "default" | "embedded";
+    "aria-label"?: string;
+}
+export declare function CodeSurface({ lines, gutterLineCount, tokenColor, onToggleCollapse, gutterIcons, indent, height, maxHeight, linkify, onLinkClick, watchlist: watchlistProp, defaultWatchlist, onWatchlistChange, theme, surfaceVariant, "aria-label": ariaLabel, }: CodeSurfaceProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/CodeBlock/CodeSurface.stories.d.ts

@@ -0,0 +1,15 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { CodeSurface } from './CodeSurface';
+declare const meta: Meta<typeof CodeSurface>;
+export default meta;
+type Story = StoryObj<typeof CodeSurface>;
+/** Realistic JSON — URLs/emails in string values are clickable (`linkify` default). */
+export declare const ProjectMetadata: Story;
+/** 5 000 flat lines — windowed rendering */
+export declare const LargeVirtualised: Story;
+/** Collapse toggles in the gutter */
+export declare const WithCollapseToggles: Story;
+/** Click gutter dots to mark lines — watchMark dot when active, watchMarkHover preview on hover. */
+export declare const WithWatchlist: Story;
+/** Partial instance override — swaps surface tokens from the built theme (no ad-hoc hex). */
+export declare const InsetSurfaceOverride: Story;

package/dist/components/CodeBlock/CodeViewingDocs.d.ts

@@ -0,0 +1,7 @@
+export type CodeViewingDocsFocus = "overview" | "codeBlock" | "jsonCodeView" | "apiResponseViewer";
+export declare function CodeViewingDocsSubtitle({ focus }: {
+    focus: CodeViewingDocsFocus;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CodeViewingArchitectureSection({ focus, }: {
+    focus?: CodeViewingDocsFocus;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/CodeBlock/JsonCodeView.d.ts

@@ -0,0 +1,17 @@
+import { CodeSurfaceGutterIcons, CodeSurfaceProps } from './CodeSurface';
+export interface JsonCodeViewProps extends Pick<CodeSurfaceProps, "height" | "maxHeight" | "theme" | "linkify" | "onLinkClick" | "watchlist" | "defaultWatchlist" | "onWatchlistChange" | "indent" | "aria-label" | "surfaceVariant"> {
+    /** Any JSON-serialisable value to render as syntax-coloured code lines. */
+    data: unknown;
+    /**
+     * Start with all collapsible nodes collapsed.
+     * @default false
+     */
+    defaultCollapsed?: boolean;
+    /** Custom chevron icons for collapse toggles in the gutter. */
+    gutterIcons?: CodeSurfaceGutterIcons;
+}
+/**
+ * JSON → tokenized lines → {@link CodeSurface}.
+ * Use for API response bodies, debug panels, and large structured payloads.
+ */
+export declare function JsonCodeView({ data, defaultCollapsed, gutterIcons, height, maxHeight, theme, linkify, onLinkClick, watchlist, defaultWatchlist, onWatchlistChange, indent, surfaceVariant, "aria-label": ariaLabel, }: JsonCodeViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/CodeBlock/JsonCodeView.stories.d.ts

@@ -0,0 +1,19 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { JsonCodeView } from './JsonCodeView';
+declare const meta: Meta<typeof JsonCodeView>;
+export default meta;
+type Story = StoryObj<typeof JsonCodeView>;
+/** Dev-server diagnostics snapshot — all nodes expanded by default */
+export declare const DevServerDiagnostics: Story;
+/** Same snapshot starting fully collapsed — expand sections individually */
+export declare const DevServerCollapsed: Story;
+/** Build output with chunk list — array expand/collapse */
+export declare const BuildOutput: Story;
+/** TypeScript compiler options — nested config object */
+export declare const TypeScriptConfig: Story;
+/** Top-level project metadata — shallow object, includes clickable URLs */
+export declare const ProjectMetadata: Story;
+/** Full viewport height — simulates a page layout slot */
+export declare const FullViewportHeight: Story;
+/** Watchlist gutter — click dots to mark lines */
+export declare const WithWatchlist: Story;

package/dist/components/CodeBlock/__fixtures__/dev-server-diagnostics.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Fictional dev-server diagnostics snapshot — package manifest, Vite output,
+ * TypeScript config, and ESLint results. All package names and versions are
+ * illustrative.
+ */
+declare const devServerDiagnostics: {
+    project: {
+        name: string;
+        version: string;
+        private: boolean;
+        type: string;
+        repository: string;
+        license: string;
+        engines: {
+            node: string;
+            npm: string;
+        };
+    };
+    scripts: {
+        dev: string;
+        build: string;
+        preview: string;
+        lint: string;
+        "test:unit": string;
+        storybook: string;
+    };
+    devServer: {
+        host: string;
+        port: number;
+        https: boolean;
+        open: boolean;
+        hmr: {
+            protocol: string;
+            host: string;
+            port: number;
+            overlay: boolean;
+        };
+        config: {
+            root: string;
+            base: string;
+            resolve: {
+                alias: {
+                    "@": string;
+                    "@theme": string;
+                };
+            };
+            server: {
+                cors: boolean;
+                strictPort: boolean;
+            };
+        };
+    };
+    build: {
+        tool: string;
+        duration_ms: number;
+        mode: string;
+        sourcemap: boolean;
+        chunks: {
+            file: string;
+            size_kb: number;
+            modules: number;
+            isEntry: boolean;
+        }[];
+        warnings: string[];
+    };
+    dependencies: {
+        react: string;
+        "react-dom": string;
+        clsx: string;
+    };
+    devDependencies: {
+        vite: string;
+        typescript: string;
+        vitest: string;
+        eslint: string;
+        "@storybook/react-vite": string;
+        "@types/react": string;
+    };
+    typescript: {
+        version: string;
+        strict: boolean;
+        compilerOptions: {
+            target: string;
+            module: string;
+            moduleResolution: string;
+            jsx: string;
+            noEmit: boolean;
+            skipLibCheck: boolean;
+            paths: {
+                "@/*": string[];
+                "@theme/*": string[];
+            };
+        };
+        diagnostics: {
+            errors: number;
+            warnings: number;
+            files_checked: number;
+        };
+    };
+    eslint: {
+        version: string;
+        config: string;
+        results: {
+            file: string;
+            messages: {
+                ruleId: string;
+                severity: number;
+                message: string;
+                line: number;
+                column: number;
+            }[];
+            errorCount: number;
+            warningCount: number;
+        }[];
+        summary: {
+            errorCount: number;
+            warningCount: number;
+            fixableWarningCount: number;
+        };
+    };
+    vitest: {
+        version: string;
+        environment: string;
+        lastRun: string;
+        duration_ms: number;
+        suites: number;
+        tests: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        coverage: {
+            lines: number;
+            branches: number;
+            functions: number;
+            statements: number;
+        };
+    };
+    env: {
+        NODE_ENV: string;
+        VITE_API_BASE_URL: string;
+        VITE_ENABLE_MOCKS: string;
+        CI: null;
+    };
+};
+export default devServerDiagnostics;

package/dist/components/CodeBlock/__fixtures__/source-samples.d.ts

@@ -0,0 +1,10 @@
+/** Sample JavaScript for CodeBlock stories. */
+export declare const sampleJavaScript = "import { fetchUser } from \"./api\";\n\nexport async function loadProfile(userId) {\n  // Fetch the latest profile from the API\n  const response = await fetchUser(userId);\n\n  if (!response.ok) {\n    throw new Error(`Failed to load ${userId}`);\n  }\n\n  return {\n    id: response.id,\n    name: response.name,\n    active: true,\n  };\n}\n";
+/** Sample TypeScript for CodeBlock stories. */
+export declare const sampleTypeScript = "export interface UserProfile {\n  id: string;\n  name: string;\n  role: \"admin\" | \"member\";\n}\n\nexport async function getProfile(id: string): Promise<UserProfile | null> {\n  const rows = await db.query<UserProfile>(\"SELECT * FROM users WHERE id = $1\", [id]);\n  return rows[0] ?? null;\n}\n";
+/** Sample HTML for CodeBlock stories. */
+export declare const sampleHtml = "<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <title>Cube Docs</title>\n    <link rel=\"stylesheet\" href=\"/theme.css\" />\n  </head>\n  <body>\n    <main class=\"docs\">\n      <h1>Welcome</h1>\n      <p>Install with <code>npm install @sragatiping/cuboid</code>.</p>\n    </main>\n  </body>\n</html>\n";
+/** Sample CSS for CodeBlock stories. */
+export declare const sampleCss = ".docs {\n  max-width: 48rem;\n  margin-inline: auto;\n  padding: var(--cube-stack-gap-lg);\n}\n\n.docs h1 {\n  color: var(--cube-colors-functional-foreground-default);\n  font-size: 1.5rem;\n}\n\n.docs code {\n  font-family: var(--cube-typography-text-inline-code-fontFamily);\n  background: var(--cube-colors-functional-background-neutral-muted);\n}\n";
+/** Long sample for virtual-scroll demo. */
+export declare function buildLongJavaScript(lineCount?: number): string;

package/dist/components/CodeBlock/constants.d.ts

@@ -0,0 +1,11 @@
+/** Fixed row height — must match CodeSurface row styles (1.625rem at 16px root). */
+export declare const CODE_SURFACE_ROW_HEIGHT_PX = 26;
+/** Enable windowed rendering when line count exceeds this in a constrained container. */
+export declare const CODE_SURFACE_VIRTUAL_THRESHOLD = 80;
+/** Extra rows rendered above/below the visible window. */
+export declare const CODE_SURFACE_OVERSCAN = 8;
+export declare const CODE_SURFACE_SCROLL_CLASS = "cube-code-surface-scroll";
+export declare const CODE_SURFACE_SCROLL_STYLE_ID = "cube-code-surface-scroll-styles";
+export declare const CODE_SURFACE_INDENT = "1.5rem";
+export declare const CODE_SURFACE_WATCH_DOT_PX = 6;
+export declare const CODE_SURFACE_SCROLL_CSS = "\n  .cube-code-surface-scroll::-webkit-scrollbar { width: 4px; height: 4px; }\n  .cube-code-surface-scroll::-webkit-scrollbar-track { background: transparent; }\n  .cube-code-surface-scroll::-webkit-scrollbar-thumb {\n    background: rgba(0,0,0,0.18);\n    border-radius: 3px;\n  }\n  .cube-code-surface-scroll::-webkit-scrollbar-thumb:hover { background: rgba(0,0,0,0.32); }\n";

package/dist/components/CodeBlock/highlight/css.d.ts

@@ -0,0 +1 @@
+export declare function highlightCss(code: string): import('..').SurfaceLine[];

package/dist/components/CodeBlock/highlight/html.d.ts

@@ -0,0 +1 @@
+export declare function highlightHtml(code: string): import('..').SurfaceLine[];

package/dist/components/CodeBlock/highlight/index.d.ts

@@ -0,0 +1,5 @@
+import { SurfaceLine } from '../types';
+/** Languages supported by {@link highlightSource}. */
+export type CodeBlockLanguage = "javascript" | "typescript" | "jsx" | "tsx" | "html" | "css" | "text";
+/** Tokenize source text into {@link SurfaceLine}s for {@link CodeSurface}. */
+export declare function highlightSource(code: string, language?: CodeBlockLanguage): SurfaceLine[];

package/dist/components/CodeBlock/highlight/javascript.d.ts

@@ -0,0 +1,5 @@
+export declare function highlightJavaScript(code: string): import('..').SurfaceLine[];
+export declare function highlightTypeScript(code: string): import('..').SurfaceLine[];
+/** JSX/TSX v1 — same rules as JS/TS; tag highlighting comes in a later pass. */
+export declare const highlightJsx: typeof highlightJavaScript;
+export declare const highlightTsx: typeof highlightTypeScript;

package/dist/components/CodeBlock/highlight/shared.d.ts

@@ -0,0 +1,15 @@
+import { SurfaceLine, SurfaceToken } from '../types';
+export interface HighlightState {
+    /** True while inside an unclosed block comment (JS/CSS). */
+    inBlockComment: boolean;
+}
+export interface SourceRule {
+    type: string;
+    /** Must match from the start of the remaining slice (`^`). */
+    pattern: RegExp;
+    /** When matched, update highlight state before continuing. */
+    onMatch?: (state: HighlightState, value: string) => void;
+}
+export declare function coalesceAdjacent(tokens: SurfaceToken[], type: string): SurfaceToken[];
+export declare function tokenizeLine(line: string, rules: SourceRule[], state: HighlightState): SurfaceToken[];
+export declare function linesFromSource(code: string, highlightLine: (line: string, state: HighlightState) => SurfaceToken[]): SurfaceLine[];

package/dist/components/CodeBlock/index.d.ts

@@ -0,0 +1,14 @@
+export { CodeSurface } from './CodeSurface';
+export type { CodeSurfaceProps, CodeSurfaceGutterIcons } from './CodeSurface';
+export { CodeBlock } from './CodeBlock';
+export type { CodeBlockProps } from './CodeBlock';
+export { JsonCodeView } from './JsonCodeView';
+export type { JsonCodeViewProps } from './JsonCodeView';
+export { highlightSource } from './highlight';
+export type { CodeBlockLanguage } from './highlight';
+export { buildLines, getAllCollapsiblePaths, } from './tokenizer';
+export type { CodeLine, Token, TokenType } from './tokenizer';
+export type { SurfaceLine, SurfaceToken } from './types';
+export { CODE_SURFACE_ROW_HEIGHT_PX, CODE_SURFACE_VIRTUAL_THRESHOLD, } from './constants';
+export { annotateBracketDepth, BRACKET_DEPTH_CYCLE, classifyJsonString, isLinkifiableTokenType, JSON_STRING_EMAIL_PATTERN, JSON_STRING_URL_PATTERN, jsonTokenColor, JSON_SYNTAX_TOKEN, linkHrefForSurfaceToken, syntaxCssVar, syntaxTokenClass, unquoteJsonStringLiteral, } from './syntax';
+export type { JsonClassifiedStringType, JsonSyntaxKey, JsonSyntaxTokenType, } from './syntax';

package/dist/components/CodeBlock/syntax.d.ts

@@ -0,0 +1,37 @@
+import { SyntaxColors } from '../../theme/types';
+import { SurfaceLine, SurfaceToken } from './types';
+export type JsonSyntaxKey = keyof SyntaxColors | "foregroundMuted";
+export declare const JSON_SYNTAX_TOKEN: {
+    readonly key: "key";
+    readonly string: "string";
+    readonly string_url: "stringUrl";
+    readonly string_email: "stringEmail";
+    readonly string_uuid: "stringUuid";
+    readonly number: "numberLiteral";
+    readonly boolean: "booleanLiteral";
+    readonly null: "nullLiteral";
+    readonly bracket: "bracket";
+    readonly operator: "foregroundMuted";
+    readonly punctuation: "foregroundMuted";
+    readonly ellipsis: "foregroundMuted";
+};
+export type JsonSyntaxTokenType = keyof typeof JSON_SYNTAX_TOKEN;
+export declare function syntaxCssVar(key: Exclude<JsonSyntaxKey, "foregroundMuted">): string;
+/** Inline colour fallback when `tokenColor` prop is used (default path uses CSS classes). */
+export declare function jsonTokenColor(type: string, syntax: SyntaxColors, mutedForeground: string): string;
+/** Cycle length for alternating bracket colours (maps to `.tokenBracketDepthN` in CSS). */
+export declare const BRACKET_DEPTH_CYCLE = 2;
+/**
+ * Assign `bracketDepth` on each delimiter. Run on the full line list before
+ * virtual scroll slicing so depth stays correct across the file.
+ */
+export declare function annotateBracketDepth(lines: SurfaceLine[]): SurfaceLine[];
+export declare function syntaxTokenClass(token: SurfaceToken | string): string;
+/** Classified JSON string value token types. */
+export type JsonClassifiedStringType = "string" | "string_url" | "string_email" | "string_uuid";
+export declare const JSON_STRING_URL_PATTERN: RegExp;
+export declare const JSON_STRING_EMAIL_PATTERN: RegExp;
+export declare function classifyJsonString(raw: string): JsonClassifiedStringType;
+export declare function unquoteJsonStringLiteral(display: string): string;
+export declare function isLinkifiableTokenType(type: string): boolean;
+export declare function linkHrefForSurfaceToken(token: Pick<SurfaceToken, "type" | "value">): string | undefined;

package/dist/components/{CodeSnippet → CodeBlock}/tokenizer.d.ts

@@ -31,11 +31,6 @@ export interface CodeLine {
      * Drives which chevron is rendered (▶ vs ▼).
      */
     isCollapsed?: boolean;
-    /**
-     * "summary" rows are the `… N lines` placeholder emitted between the opening
-     * and closing bracket of a collapsed node. Rendered with a muted highlight.
-     */
-    kind?: "summary";
 }
 /**
  * Build the full list of visible CodeLines for the given data and collapse state.

package/dist/components/CodeBlock/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Language-agnostic line model for CodeSurface.
+ * Producers (JsonCodeView {@link buildLines}, CodeBlock highlighters) build these;
+ * CodeSurface only renders them.
+ */
+export interface SurfaceToken {
+    type: string;
+    value: string;
+    /**
+     * Nesting index for `{ } [ ] ( )` — set by {@link annotateBracketDepth} in `./syntax`.
+     * Drives alternating bracket colours in CodeSurface.
+     */
+    bracketDepth?: number;
+}
+export interface SurfaceLine {
+    /** 1-indexed line number shown in the gutter. */
+    lineNumber: number;
+    /** Nesting depth — drives visual indentation. */
+    depth: number;
+    tokens: SurfaceToken[];
+    /**
+     * When set, the gutter shows a collapse toggle for this line.
+     * The parent passes `onToggleCollapse` to handle clicks.
+     */
+    collapseKey?: string;
+    isCollapsed?: boolean;
+}

package/dist/components/CodeSnippet/CodeSnippet.d.ts

@@ -1,50 +1,9 @@
-import { default as React } from 'react';
-import { CubeTheme } from '../../theme/types';
-export interface CodeSnippetProps {
-    /** Any JSON-serialisable value */
-    data: unknown;
-    /**
-     * Start with all collapsible nodes collapsed.
-     * The user can then expand nodes individually.
-     * @default false
-     */
-    defaultCollapsed?: boolean;
-    /**
-     * Replace the built-in chevron icons with your own SVG components.
-     * You are responsible for sizing and coloring them.
-     *
-     * @example
-     * ```tsx
-     * import { ChevronRight, ChevronDown } from "lucide-react";
-     *
-     * <CodeSnippet
-     *   data={data}
-     *   icons={{
-     *     collapsed: <ChevronRight size={16} />,
-     *     expanded:  <ChevronDown size={16} />,
-     *   }}
-     * />
-     * ```
-     */
-    icons?: {
-        /** Shown when the node is collapsed. Defaults to a Material Design ChevronRight. */
-        collapsed?: React.ReactNode;
-        /** Shown when the node is expanded. Defaults to a Material Design ExpandMore. */
-        expanded?: React.ReactNode;
-    };
-    /**
-     * Fix the component to an exact height — content scrolls inside.
-     * Accepts any valid CSS value (e.g. "400px", "50vh", "20rem").
-     */
-    height?: string;
-    /**
-     * Cap the component height — content scrolls only when it exceeds this value.
-     * Accepts any valid CSS value (e.g. "400px", "50vh", "20rem").
-     */
-    maxHeight?: string;
-    /** Override any theme tokens for this instance */
-    theme?: CubeTheme;
-    /** Accessible label for the code region */
-    "aria-label"?: string;
-}
-export declare function CodeSnippet({ data, defaultCollapsed, icons, height, maxHeight, theme, "aria-label": ariaLabel, }: CodeSnippetProps): import("react/jsx-runtime").JSX.Element;
+import { JsonCodeViewProps } from '../CodeBlock/JsonCodeView';
+/**
+ * @deprecated Use {@link JsonCodeView} from `@sragatiping/cuboid` / `components/CodeBlock`.
+ */
+export type CodeSnippetProps = JsonCodeViewProps;
+/**
+ * @deprecated Use {@link JsonCodeView} — JSON data + collapse → {@link CodeSurface}.
+ */
+export declare function CodeSnippet(props: CodeSnippetProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/JsonViewer/JsonViewer.d.ts

@@ -9,7 +9,7 @@ export interface JsonViewerProps {
     theme?: CubeTheme;
 }
 /**
- * Top-level component that toggles between CodeSnippet and DataGrid views.
+ * Top-level component that toggles between JsonCodeView and DataGrid views.
  * Toggle UI and wiring TBD — requirements coming soon.
  */
 export declare function JsonViewer({ data, defaultMode }: JsonViewerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/core/Box/Box.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { StackProps } from '../Stack';
+import { BoxBackground, BoxBorder, BoxBorderRadius, BoxForeground, BoxOverflow } from './boxTypes';
+export type { BoxBackground, BoxBorder, BoxBorderRadius, BoxForeground, BoxOverflow, } from './boxTypes';
+export interface BoxProps extends StackProps {
+    /** Functional background role. */
+    background?: BoxBackground;
+    /** Border style — `none` (default), `default`, or `muted`. */
+    border?: BoxBorder;
+    /** Corner radius from `sizes.borderRadius`. */
+    borderRadius?: BoxBorderRadius;
+    /** Shorthand overflow — use `overflowX` / `overflowY` in `style` to override an axis. */
+    overflow?: BoxOverflow;
+    /** Functional foreground role for inherited text colour. */
+    foreground?: BoxForeground;
+}
+/**
+ * Generic styled surface + flex layout primitive.
+ *
+ * Surface styles use global `--cube-*` tokens via CSS module modifiers (same
+ * pattern as {@link Button}). Local `theme` overrides re-bind those `--cube-*`
+ * names on this element only.
+ */
+export declare const Box: React.ForwardRefExoticComponent<BoxProps & React.RefAttributes<HTMLElement>>;

package/dist/components/core/Box/Box.stories.d.ts

@@ -0,0 +1,9 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { Box } from './Box';
+declare const meta: Meta<typeof Box>;
+export default meta;
+type Story = StoryObj<typeof Box>;
+export declare const Playground: Story;
+export declare const InsetSurface: Story;
+export declare const HorizontalLayout: Story;
+export declare const NestedInStack: Story;

package/dist/components/core/Box/boxTypes.d.ts

@@ -0,0 +1,6 @@
+import { BackgroundColors, BorderRadiusTokens, ForegroundColors } from '../../../theme/types';
+export type BoxBackground = Exclude<keyof BackgroundColors, "neutral"> | "neutralMuted" | "neutralEmphasis";
+export type BoxBorder = "none" | "default" | "muted";
+export type BoxBorderRadius = keyof BorderRadiusTokens;
+export type BoxForeground = keyof ForegroundColors;
+export type BoxOverflow = "visible" | "hidden" | "auto" | "scroll";

package/dist/components/core/Box/index.d.ts

@@ -0,0 +1,2 @@
+export { Box } from './Box';
+export type { BoxProps, BoxBackground, BoxBorder, BoxBorderRadius, BoxForeground, BoxOverflow } from './Box';

package/dist/components/core/Callout/Callout.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { CubeTheme, GlobalColorPath } from '../../../theme/types';
+export type { GlobalColorPath as CalloutBackground };
+export interface CalloutProps {
+    /**
+     * Surface color from `colors.global` (dot-path), or any CSS color string.
+     * @default "canvas.inset"
+     * @example "canvas.inset" | "bg.gray.light.02" | "#eef6ff"
+     */
+    background?: GlobalColorPath;
+    theme?: CubeTheme;
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/** Inset block for blockquotes, notes, and asides. */
+export declare function Callout({ background, theme, className, style, children, }: CalloutProps): import("react/jsx-runtime").JSX.Element;