@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills-cursor/canvas/sdk/ui-primitives.d.ts

@@ -0,0 +1,549 @@
+/**
+ * UI primitives for `cursor/canvas`. Styling follows the Cursor dark theme; no extra packages required.
+ */
+import { type CSSProperties, type JSX, type ReactNode } from "react";
+/**
+ * Shallow-merge style objects with `override` taking precedence.
+ *
+ * Use for small tweaks on built-in components (e.g. extra padding or width).
+ * **Do not** use this to build elaborate custom chrome — prefer the built-in
+ * components and flat solid token colors. No gradients, no box-shadows.
+ *
+ * @example
+ * ```tsx
+ * // Good — minor override on a built-in component
+ * <CardBody style={mergeStyle({ padding: 16 })}>…</CardBody>
+ *
+ * // Bad — hand-rolled decorative styling
+ * <div style={mergeStyle(base, { background: "linear-gradient(…)" })}>…</div>
+ * ```
+ */
+export declare function mergeStyle(base: CSSProperties, override?: CSSProperties): CSSProperties;
+export type StackProps = {
+    children?: ReactNode;
+    gap?: number;
+    style?: CSSProperties;
+};
+/**
+ * Vertical flex column. Use as the top-level page wrapper or to stack cards/sections.
+ *
+ * @example
+ * ```tsx
+ * <Stack gap={16}>
+ *   <H1>Dashboard</H1>
+ *   <Card>…</Card>
+ *   <Card>…</Card>
+ * </Stack>
+ * ```
+ */
+export declare function Stack({ children, gap, style }: StackProps): JSX.Element;
+export type RowProps = {
+    children?: ReactNode;
+    gap?: number;
+    align?: "start" | "center" | "end" | "stretch";
+    justify?: "start" | "center" | "end" | "space-between";
+    wrap?: boolean;
+    style?: CSSProperties;
+};
+/**
+ * Horizontal flex row. Use for inline groups of buttons, badges, or metadata.
+ *
+ * @example
+ * ```tsx
+ * <Row gap={8} align="center">
+ *   <Button variant="primary">Save</Button>
+ *   <Button variant="ghost">Cancel</Button>
+ * </Row>
+ * ```
+ */
+export declare function Row({ children, gap, align, justify, wrap, style }: RowProps): JSX.Element;
+/**
+ * CSS Grid with tokenized gap. Prefer this over `Row` + `wrap` when you need a
+ * fixed number of equal-width columns: wrapped flex items can land on their
+ * own row and grow to full width (`flex-grow`), which is often surprising for
+ * boards and dashboards.
+ */
+export type GridProps = {
+    children?: ReactNode;
+    /**
+     * Equal columns: pass a number (uses `repeat(n, minmax(0, 1fr))`), or a CSS
+     * `grid-template-columns` string (e.g. `"1fr 2fr"` or `"minmax(0, 200px) 1fr"`).
+     */
+    columns: number | string;
+    gap?: number;
+    align?: "start" | "center" | "end" | "stretch";
+    style?: CSSProperties;
+};
+export declare function Grid({ children, columns, gap, align, style }: GridProps): JSX.Element;
+export type DividerProps = {
+    style?: CSSProperties;
+};
+/**
+ * Horizontal line for visually separating sections. Uses `stroke.tertiary`
+ * to match the Card/Table hairline weight.
+ *
+ * @example
+ * ```tsx
+ * <Stack>
+ *   <Text>Section one</Text>
+ *   <Divider />
+ *   <Text>Section two</Text>
+ * </Stack>
+ * ```
+ */
+export declare function Divider({ style }: DividerProps): JSX.Element;
+/**
+ * Flex spacer that pushes siblings apart. Place inside a `Row` to push
+ * trailing content to the right edge.
+ *
+ * @example
+ * ```tsx
+ * <Row>
+ *   <Text>Title</Text>
+ *   <Spacer />
+ *   <Button variant="primary">Save</Button>
+ * </Row>
+ * ```
+ */
+export declare function Spacer(): JSX.Element;
+/** Horizontal alignment for a table column. */
+export type TableColumnAlign = "left" | "center" | "right";
+/** Semantic tone for a table row — renders a translucent tinted background. */
+export type TableRowTone = "success" | "danger" | "warning" | "info" | "neutral";
+export type TableProps = {
+    /** Column titles, left to right. Column count is fixed by this array. */
+    headers: ReactNode[];
+    /**
+     * Body rows. Each row is an array of cells in the same order as `headers`.
+     * Shorter rows are padded with empty cells; extra cells are ignored.
+     */
+    rows: ReactNode[][];
+    /** Optional alignment per column index (headers/rows). Defaults to left. */
+    columnAlign?: Array<TableColumnAlign | undefined>;
+    /**
+     * Optional semantic tone per row index. Applies a translucent tinted
+     * background — use for status highlighting (e.g. failing services, warnings).
+     * Sparse: `undefined` entries are uncolored.
+     */
+    rowTone?: Array<TableRowTone | undefined>;
+    /** When true (default), bordered rounded shell with horizontal scroll if needed. */
+    framed?: boolean;
+    /** Alternate subtle fill on even rows for easier scanning in large tables. */
+    striped?: boolean;
+    /** Stick the header row when the framed container scrolls vertically. */
+    stickyHeader?: boolean;
+    style?: CSSProperties;
+    /** Shown in a single spanning cell when `rows` is empty. */
+    emptyMessage?: ReactNode;
+};
+/**
+ * Data table with column headers and rows. Framed by default with its own
+ * bordered container — **do not wrap in a Card** unless the card itself is
+ * a named entity that happens to contain a table. Render directly under a
+ * heading in the normal case.
+ *
+ * @example
+ * ```tsx
+ * // Good — table directly under a heading
+ * <H2>Active services</H2>
+ * <Table
+ *   headers={["Service", "Status", "RPS"]}
+ *   rows={[
+ *     ["api-gateway", "Steady", "3.2k"],
+ *     ["workers", "Hot", "8.1k"],
+ *   ]}
+ *   columnAlign={["left", "left", "right"]}
+ * />
+ *
+ * // Allowed — table inside a named-entity card
+ * <Card>
+ *   <CardHeader>billing-service</CardHeader>
+ *   <CardBody><Table headers={…} rows={…} /></CardBody>
+ * </Card>
+ * ```
+ */
+export declare function Table({ headers, rows, columnAlign, rowTone, framed, striped, stickyHeader, style, emptyMessage }: TableProps): JSX.Element;
+export type TextWeight = "normal" | "medium" | "semibold" | "bold";
+export type TextProps = {
+    children?: ReactNode;
+    tone?: "primary" | "secondary" | "tertiary" | "quaternary";
+    size?: "body" | "small";
+    /**
+     * Element tag to render. Defaults to `"p"` for top-level body copy and
+     * automatically switches to `"span"` when nested inside another typography
+     * container so inline emphasis stays valid HTML.
+     */
+    as?: "p" | "span";
+    /** Font weight. Default is `"normal"` (400). Use `"semibold"` or `"bold"` for emphasis. */
+    weight?: TextWeight;
+    /** Render as italic. */
+    italic?: boolean;
+    /**
+     * Truncate overflowing text with an ellipsis on a single line.
+     * - `true` / `"end"` — ellipsis at the end (default truncation).
+     * - `"start"` — ellipsis at the start. Useful for file paths where the
+     *   filename matters more than the directory prefix.
+     *
+     * Requires the parent to have a bounded width (flex child with
+     * `minWidth: 0`, fixed width, etc.) — otherwise the text just expands
+     * and never overflows.
+     */
+    truncate?: boolean | "start" | "end";
+    style?: CSSProperties;
+};
+/**
+ * Body text with tone, size, weight, and italic variants.
+ *
+ * Top-level `Text` renders a `<p>`. Nested `Text` automatically renders a
+ * `<span>` so inline emphasis like `<Text>Use <Text weight="semibold">this</Text></Text>`
+ * does not emit invalid nested paragraphs. Use `as` to override when needed.
+ *
+ * Compose with `<Code>` for inline code and `<Link>` for hyperlinks inside
+ * the text flow.
+ *
+ * @example
+ * ```tsx
+ * <Text>Primary body text.</Text>
+ * <Text weight="semibold">Important note.</Text>
+ * <Text italic tone="secondary">Supplementary remark.</Text>
+ * <Text>Run <Code>npm install</Code> to get started.</Text>
+ * <Text>See the <Link href="https://example.com">docs</Link> for details.</Text>
+ * ```
+ */
+export declare function Text({ children, tone, size, as, weight, italic, truncate, style }: TextProps): JSX.Element;
+export type H1Props = {
+    children?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Page-level heading. Use once at the top of a canvas.
+ * **Do not** place inside `CardHeader` — card headers use their own label.
+ *
+ * @example
+ * ```tsx
+ * <Stack>
+ *   <H1>Performance Report</H1>
+ *   <Card>…</Card>
+ * </Stack>
+ * ```
+ */
+export declare function H1({ children, style }: H1Props): JSX.Element;
+export type H2Props = {
+    children?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Section heading. Use between groups of cards or sections.
+ * **Do not** place inside `CardHeader` — card headers use their own label.
+ *
+ * @example
+ * ```tsx
+ * <Stack>
+ *   <H2>Recent activity</H2>
+ *   <Card>…</Card>
+ *   <Card>…</Card>
+ * </Stack>
+ * ```
+ */
+export declare function H2({ children, style }: H2Props): JSX.Element;
+export type H3Props = {
+    children?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Sub-section heading. Use below `H2` for finer hierarchy.
+ *
+ * @example
+ * ```tsx
+ * <Stack>
+ *   <H2>API Reference</H2>
+ *   <H3>Authentication</H3>
+ *   <Text>All requests require a bearer token.</Text>
+ * </Stack>
+ * ```
+ */
+export declare function H3({ children, style }: H3Props): JSX.Element;
+export type CodeProps = {
+    children?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Inline `<code>` span for identifiers, file names, or short snippets.
+ * Uses `0.92em` so it scales with surrounding text (headings, body, etc.).
+ *
+ * Prefer writing backtick markdown inside `Text` — e.g. `` <Text>Run `npm install`</Text> `` —
+ * which is automatically parsed. Use `<Code>` only when you need an explicit element.
+ *
+ * @example
+ * ```tsx
+ * <Text>Run <Code>npm install</Code> to get started.</Text>
+ * ```
+ */
+export declare function Code({ children, style }: CodeProps): JSX.Element;
+export type LinkProps = {
+    children?: ReactNode;
+    href: string;
+    style?: CSSProperties;
+};
+/**
+ * Inline link that opens in the user's default browser.
+ *
+ * Prefer writing markdown links inside `Text` — e.g. `<Text>See the [docs](url)</Text>` —
+ * which are automatically parsed. Use `<Link>` when you need an explicit anchor
+ * outside of a text flow or when composing with other elements.
+ *
+ * @example
+ * ```tsx
+ * <Link href="https://docs.example.com">View documentation</Link>
+ * ```
+ */
+export declare function Link({ children, href, style }: LinkProps): JSX.Element;
+export type CardSize = "base" | "lg";
+export type CardVariant = "default" | "borderless";
+/**
+ * Inline chevron SVG used by disclosure-style controls (collapsible cards,
+ * expandable list items, etc.). Shared by `Card` and `todo-list.tsx` so
+ * every disclosure in the canvas SDK uses the same glyph.
+ */
+export declare function CanvasChevron({ expanded }: {
+    expanded: boolean;
+}): JSX.Element;
+export type CardProps = {
+    children?: ReactNode;
+    /** Default: bordered surface with radius; `borderless` removes both. */
+    variant?: CardVariant;
+    /** `lg` uses a taller header and roomier title padding (matches packages/ui). */
+    size?: CardSize;
+    /**
+     * When true, the header uses `position: sticky` so it stays visible while
+     * the card body scrolls. Requires the card (or a parent) to have a
+     * constrained height and `overflow: auto` — the canvas host controls this,
+     * so sticky behavior depends on the host viewport.
+     */
+    stickyHeader?: boolean;
+    /**
+     * Make the card collapsible. The header becomes a clickable toggle with
+     * a leading chevron; `CardBody` renders nothing while the card is closed.
+     */
+    collapsible?: boolean;
+    /** Initial open state in uncontrolled mode. Ignored when `open` is set. */
+    defaultOpen?: boolean;
+    /** Controlled open state. Pair with `onOpenChange`. */
+    open?: boolean;
+    /** Fires on every toggle with the next open state. */
+    onOpenChange?: (open: boolean) => void;
+    style?: CSSProperties;
+};
+/**
+ * Bordered surface for a **labeled, self-contained unit** — a file, a service,
+ * a config block, or a table with a title. Compose with `CardHeader` + `CardBody`.
+ *
+ * **When to use Card:**
+ * - Displaying a named entity (file path, service name, resource).
+ * - Wrapping a `<Table>` or `<DiffView>` that needs a title.
+ * - A distinct, bounded section the user might scan by header label.
+ *
+ * **When NOT to use Card:**
+ * - General text sections — use `<H2>` + `<Text>` instead. Not every section
+ *   needs a border.
+ * - Page-level layout — use `<Stack>` with headings. A canvas should not be a
+ *   wall of stacked cards.
+ * - Nesting — do not put cards inside cards. Use `<Divider>` within a card body.
+ *
+ * Pass **plain text** as `CardHeader` children — the header provides its own
+ * 12px font. Do **not** put `<H1>` or `<H2>` inside a card header.
+ *
+ * Set `collapsible` to make the header a toggle that shows/hides `CardBody`.
+ *
+ * @example
+ * ```tsx
+ * // Card wraps a titled diff
+ * <Card>
+ *   <CardHeader trailing={<DiffStats additions={5} deletions={2} />}>
+ *     src/utils.ts
+ *   </CardHeader>
+ *   <CardBody style={{ padding: 0 }}>
+ *     <DiffView path="src/utils.ts" lines={lines} />
+ *   </CardBody>
+ * </Card>
+ *
+ * // Collapsible card
+ * <Card collapsible defaultOpen={false}>
+ *   <CardHeader>deploy-service.ts</CardHeader>
+ *   <CardBody>Service handles rolling deployments across regions.</CardBody>
+ * </Card>
+ *
+ * // Bad — card wrapping plain text that should just be a heading
+ * // Use <H2>Overview</H2><Text>…</Text> instead.
+ * ```
+ */
+export declare function Card({ children, variant, size, stickyHeader, collapsible, defaultOpen, open: openProp, onOpenChange, style }: CardProps): JSX.Element;
+export type CardHeaderProps = {
+    /** Plain text title. Do **not** pass headings, buttons, pills, or layout rows. */
+    children?: ReactNode;
+    /** Small trailing content aligned to the right edge — a status label, a
+     *  single pill, or a short metadata string. Keep it compact. */
+    trailing?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * 28px header row (32px at `size="lg"`). A compact label for the card.
+ *
+ * **`children`** — plain text only. This is a 12px label, not a toolbar.
+ * Do **not** pass `<H1>`, `<H2>`, `<Text weight="bold">`, `<Pill>`,
+ * `<Button>`, `<Row>`, or any interactive/layout elements as children.
+ *
+ * **`trailing`** — optional right-aligned slot for small status indicators
+ * (a short label, a single `<Pill>`, a metadata string like a timestamp).
+ *
+ * @example
+ * ```tsx
+ * // Good — plain title
+ * <CardHeader>config.yaml</CardHeader>
+ *
+ * // Good — title with trailing status
+ * <CardHeader trailing={<Pill active>Healthy</Pill>}>
+ *   billing-service
+ * </CardHeader>
+ *
+ * // Bad — heading in header (use CardHeader text, not H2)
+ * // Bad — buttons in header (no room, wrong context)
+ * // Bad — multiple pills in header (use trailing for one, or move to CardBody)
+ * ```
+ */
+export declare function CardHeader({ children, trailing, style }: CardHeaderProps): JSX.Element;
+export type CardBodyProps = {
+    children?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Padded content area inside a Card.
+ * Override `style` to adjust padding for custom layouts.
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   <CardHeader>Overview</CardHeader>
+ *   <CardBody>This service is currently healthy.</CardBody>
+ * </Card>
+ * ```
+ */
+export declare function CardBody({ children, style }: CardBodyProps): JSX.Element | null;
+export type ButtonProps = {
+    children?: ReactNode;
+    variant?: "primary" | "secondary" | "ghost";
+    disabled?: boolean;
+    type?: "button" | "submit" | "reset";
+    style?: CSSProperties;
+    onClick?: () => void;
+};
+/**
+ * Action button (24px height, sized to its label). **Never stretch to full
+ * width** — buttons are always inline and hug their text.
+ *
+ * @example
+ * ```tsx
+ * <Row gap={8}>
+ *   <Button variant="primary" onClick={handleSave}>Save</Button>
+ *   <Button variant="secondary">Export</Button>
+ *   <Button variant="ghost">Cancel</Button>
+ * </Row>
+ * ```
+ */
+export declare function Button({ children, variant, disabled, type, style, onClick }: ButtonProps): JSX.Element;
+export type PillTone = "neutral" | "added" | "deleted" | "renamed" | "success" | "warning" | "info";
+export type PillSize = "sm" | "md";
+export type PillProps = {
+    children?: ReactNode;
+    /** Whether the pill is in its selected/active state (filled background). */
+    active?: boolean;
+    /**
+     * Semantic tone. Recolors the border and text. When `active` is also
+     * set, fills the background with the tone color at low opacity.
+     * Defaults to `neutral` (current stroke/text tokens).
+     */
+    tone?: PillTone;
+    /**
+     * Visual size. `"md"` (default) is the standard pill. `"sm"` is a
+     * compact variant with smaller text, tighter padding, and no border —
+     * designed for tight spaces like `CardHeader` trailing slots.
+     */
+    size?: PillSize;
+    /** Shown before the label (icon, emoji, etc.). */
+    leadingContent?: ReactNode;
+    /** e.g. shortcut hint — matches ui `Pill` ghost keyboard hint (muted primary). */
+    keyboardHint?: string;
+    disabled?: boolean;
+    title?: string;
+    style?: CSSProperties;
+    onClick?: () => void;
+};
+/**
+ * Pill-shaped label or toggle button. Use for tab bars, filter groups, or
+ * action suggestions. Set `active` for the selected state (filled background).
+ *
+ * @example
+ * ```tsx
+ * // Tab-style selector
+ * <Row gap={8}>
+ *   {tabs.map(tab => (
+ *     <Pill key={tab} active={tab === selected} onClick={() => setSelected(tab)}>
+ *       {tab}
+ *     </Pill>
+ *   ))}
+ * </Row>
+ *
+ * // Action suggestion with shortcut hint
+ * <Pill onClick={handlePlan} keyboardHint="⇧Tab">Plan new idea</Pill>
+ * ```
+ */
+export declare function Pill({ children, active, tone, size, leadingContent, keyboardHint, disabled, title, style, onClick }: PillProps): JSX.Element;
+export type StatTone = "success" | "danger" | "warning" | "info";
+export type StatProps = {
+    /** The primary metric value (number, percentage, short string). */
+    value: ReactNode;
+    /** Label below the value. */
+    label: string;
+    /** Semantic color for the value. Omit for default primary text. */
+    tone?: StatTone;
+    style?: CSSProperties;
+};
+/**
+ * Single metric display — a large value with a compact label beneath it.
+ * Use inside `<Grid>` for dashboard summary strips.
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={3} gap={16}>
+ *   <Stat value="4" label="Healthy" tone="success" />
+ *   <Stat value="1" label="Degraded" tone="warning" />
+ *   <Stat value="99.2%" label="Avg Uptime" />
+ * </Grid>
+ * ```
+ */
+export declare function Stat({ value, label, tone, style }: StatProps): JSX.Element;
+export type CalloutTone = "info" | "success" | "warning" | "danger" | "neutral";
+export type CalloutProps = {
+    /** Body content. Plain strings, `<Text>`, `<Code>`, `<Link>`, or short lists. */
+    children?: ReactNode;
+    /** Semantic tone. Recolors the border, background tint, and title text. */
+    tone?: CalloutTone;
+    /** Optional bold title line, shown above the body in the tone color. */
+    title?: ReactNode;
+    /** Optional leading icon (emoji, inline SVG, or short text glyph). */
+    icon?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Tinted, bordered notice block for warnings, tips, or short status messages
+ * inline within a section.
+ *
+ * @example
+ * ```tsx
+ * <Callout tone="warning" title="Heads up">
+ *   Rolling deploy is in progress. Metrics may be noisy for 10 minutes.
+ * </Callout>
+ * ```
+ */
+export declare function Callout({ children, tone, title, icon, style }: CalloutProps): JSX.Element;
+//# sourceMappingURL=ui-primitives.d.ts.map

package/skills-cursor/canvas/sdk/ui-primitives.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ui-primitives.test.d.ts.map