@stackone/malachite 2.15.0 → 2.16.0

package/dist/index.d.ts

@@ -305,7 +305,13 @@ export declare type ButtonRadius = 'md' | 'lg' | 'xl';
 
 export declare type ButtonSize = 'xsmall' | 'small' | 'medium' | 'large';
 
-export declare type ButtonVariant = 'filled' | 'outline' | 'destructive' | 'success' | 'warning' | 'error' | 'ghost' | 'no-style';
+export declare type ButtonVariant = 'filled' | 'outline'
+/**
+* `outline`'s geometry on a ground of its own. For a button sitting on a tinted or
+* patterned surface, where `outline`'s transparent background lets that surface through
+* and the control stops reading as a button.
+*/
+| 'surface' | 'destructive' | 'success' | 'warning' | 'error' | 'ghost' | 'no-style';
 
 export declare const Card: default_2.FC<CardProps>;
 
@@ -383,6 +389,362 @@ export declare interface CardStripProps {
 /** Palette for the strip's rule. Pass the tone of whatever card is selected. */
 export declare type CardStripTone = 'profile' | 'library' | 'editing';
 
+export declare type ChangeKind = 'changed' | 'added' | 'removed';
+
+/**
+ * Reviewing changes a machine made: one note per changed thing, a card for what it removed
+ * outright, a bar counting what is still outstanding, and a chip pointing at any of it from
+ * elsewhere on the page.
+ */
+export declare const ChangeReview: {
+    Item: FC<ChangeReviewItemProps>;
+    Summary: FC<ChangeReviewSummaryProps>;
+    Removed: FC<ChangeReviewRemovedProps>;
+    Jump: FC<ChangeReviewJumpProps>;
+};
+
+export declare interface ChangeReviewItemProps {
+    /**
+     * What changed — a field name, or the name of a group of them. Omit it when the field this
+     * item annotates already carries its own visible heading elsewhere on the page (so the name
+     * doesn't render twice) — pass `fieldName` instead, so the badge and actions still know what
+     * they belong to.
+     */
+    label?: string;
+    /**
+     * Names the field the badge and actions act on, for assistive tech. Defaults to `label`, so
+     * passing only `label` keeps working as before. Set it explicitly when `label` is omitted —
+     * otherwise "Accept"/"Revert" would have nothing telling a screen reader which field they act
+     * on.
+     */
+    fieldName?: string;
+    /** How it read before. A node, so a caller can show chips or code rather than a string. */
+    before?: default_2.ReactNode;
+    /** How it reads now. Usually omitted: the field itself is showing it. */
+    after?: default_2.ReactNode;
+    kind?: ChangeKind;
+    /** What made the change. Names the assistant by default. */
+    origin?: string;
+    /**
+     * The field the change is annotating. When given, the tag/label/actions form a header band
+     * above it and the before/after line moves below it, so "Was …" reads next to the value it
+     * describes instead of stacked with the header. Omit it for the standalone card.
+     */
+    children?: default_2.ReactNode;
+    onApprove: () => void;
+    onDeny: () => void;
+    /**
+     * Fires while the revert control is hovered or focused, and again when it stops being
+     * either. A callback rather than internal state because the thing being previewed — the
+     * field this change came from — lives elsewhere on the page, outside what `Item` renders;
+     * only the caller can swap what that field shows.
+     */
+    onPreviewRevert?: (previewing: boolean) => void;
+    disabled?: boolean;
+    className?: string;
+}
+
+export declare interface ChangeReviewJumpProps {
+    /** What the chip points at, e.g. a field or capability name. */
+    label: string;
+    /** Jumps the page to what changed. Without it the chip only names the change. */
+    onClick?: () => void;
+    disabled?: boolean;
+    className?: string;
+}
+
+export declare interface ChangeReviewRemovedDetail {
+    label: string;
+    /** A node, so a caller can show a chip or code rather than a string. */
+    value: default_2.ReactNode;
+}
+
+export declare interface ChangeReviewRemovedProps {
+    /** The noun for what was removed. Defaults to a capability, but the component isn't
+     *  policy-specific — a caller reviewing something else names it. */
+    title?: string;
+    /** Field/value pairs describing the removed thing, so the admin can see what they would
+     *  lose before deciding. */
+    details: ChangeReviewRemovedDetail[];
+    onRestore: () => void;
+    onDiscard: () => void;
+    /** What made the removal. Names the assistant by default. */
+    origin?: string;
+    disabled?: boolean;
+    className?: string;
+}
+
+export declare interface ChangeReviewSummaryProps {
+    /** How many changes are still undecided. */
+    count: number;
+    /** What made them. Names the assistant by default. */
+    origin?: string;
+    onApproveAll: () => void;
+    onDenyAll: () => void;
+    disabled?: boolean;
+    /**
+     * What to say once nothing is outstanding. Omit and the bar renders nothing, which is what
+     * a caller wants when the space should collapse rather than reassure.
+     */
+    settledMessage?: string;
+    className?: string;
+}
+
+export declare const Chat: ChatComponent;
+
+declare interface ChatComponent extends default_2.FC<ChatProps> {
+    Header: default_2.FC<ChatHeaderProps>;
+    Thread: default_2.FC<ChatThreadProps>;
+    Message: default_2.FC<ChatMessageProps>;
+    ToolCall: default_2.FC<ChatToolCallProps>;
+    Thinking: default_2.FC<ChatThinkingProps>;
+    Composer: default_2.FC<ChatComposerProps>;
+    ComposerChip: default_2.FC<ChatComposerChipProps>;
+    Context: default_2.FC<ChatContextProps>;
+    ContextMeter: default_2.FC<ChatContextMeterProps>;
+    ModelPicker: default_2.FC<ChatModelPickerProps>;
+    Suggestion: default_2.FC<ChatSuggestionProps>;
+}
+
+export declare interface ChatComposerChipProps {
+    label: string;
+    icon?: default_2.ReactNode;
+    /** Sits after the label — a caret on a chip that opens a menu. */
+    trailingIcon?: default_2.ReactNode;
+    /** Makes the chip a control. Without it, the chip reports rather than acts. */
+    onClick?: () => void;
+    disabled?: boolean;
+    className?: string;
+}
+
+export declare interface ChatComposerProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSend: () => void;
+    /** Offered in place of send while `busy`. Without it, send is simply disabled. */
+    onStop?: () => void;
+    /** A reply is streaming. */
+    busy?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    maxLength?: number;
+    rows?: number;
+    /**
+     * How many lines the field grows to before it scrolls internally instead of growing
+     * further. Defaults well above `rows` so the field grows by default rather than staying
+     * fixed at its starting height — a consumer that genuinely wants a static box passes
+     * `maxRows` equal to `rows`.
+     */
+    maxRows?: number;
+    /**
+     * `'in-field'` (the default, so no existing consumer moves) nests a round send button
+     * inside the field, trailing the text. `'beside'` matches the policy design instead: a
+     * plain field with a labelled `Send` button to its right. Either way the field stays a
+     * `TextArea` — the mock draws a single-line input, but a composer that cannot take a
+     * second line is a downgrade, and `TextArea` already owns the Enter-to-send convention.
+     */
+    sendPlacement?: 'in-field' | 'beside';
+    /**
+     * `'assistant'` marks the field itself as AI-owned chrome: its focus border recolours to
+     * the assistant violet instead of the default accent. Defaults to `'default'` — an AI
+     * surface (e.g. the playground) opts in deliberately rather than inheriting it silently.
+     */
+    tone?: 'default' | 'assistant';
+    /** Controls belonging with the composer — a model picker, a token meter. */
+    children?: default_2.ReactNode;
+    'aria-label'?: string;
+    className?: string;
+}
+
+export declare interface ChatContextItem {
+    id: string;
+    label: string;
+    /** Shows a remove control on the item. Without it, the item reports rather than can be dropped. */
+    onRemove?: () => void;
+}
+
+export declare interface ChatContextMeterProps {
+    /** Tokens spent. Absent reads as a dash: nothing has been measured yet. */
+    used?: number | null;
+    /** The model's context window. */
+    limit: number;
+    /** Tokens served from cache, when the provider reports them. */
+    cached?: number | null;
+    label?: string;
+    className?: string;
+}
+
+export declare interface ChatContextProps {
+    label?: string;
+    items: ChatContextItem[];
+    /** Renders the "Add context" control. Without it, the row only lists what is already in scope. */
+    onAdd?: () => void;
+    className?: string;
+}
+
+export declare type ChatFeedback = 'up' | 'down';
+
+export declare interface ChatHeaderProps {
+    /** Names the surface, e.g. "Policy chat". */
+    title: string;
+    /**
+     * Marks the surface as AI-owned: the title takes the assistant violet and a sparkle
+     * leads it. Defaults to `'default'`, so a chat that is not assistant-authored does not
+     * inherit the treatment.
+     */
+    tone?: 'default' | 'assistant';
+    /** Sits opposite the title — a model name, a token count. */
+    trailing?: default_2.ReactNode;
+    /** Rows travelling with the header, e.g. `Chat.Context`. Pinned along with it. */
+    children?: default_2.ReactNode;
+    className?: string;
+}
+
+export declare interface ChatMessageProps {
+    role: ChatRole;
+    /**
+     * `card` frames the turn with a header and a footer — for a surface where a reply carries
+     * its own status and cost. `plain` is the bare turn. `bubble` wraps the turn in a coloured,
+     * asymmetrically-rounded bubble instead — no header, no footer, just the shape.
+     */
+    variant?: ChatMessageVariant;
+    /** Markdown. Rendered through `Typography.MarkdownBlock`, so a reply may carry formatting. */
+    content?: string;
+    /** Anything belonging with the message — tool calls, reasoning, a busy indicator. */
+    children?: default_2.ReactNode;
+    /** Names a user turn and its avatar; labels an assistant turn's header. */
+    name?: string;
+    avatarSrc?: string;
+    /** Shown in a `card` header. Omitted means the turn reports no state. */
+    status?: ChatMessageStatus;
+    /**
+     * The reply has been asked for but nothing has arrived. Renders the same placeholder
+     * `Chat.Thinking` does, in the body's place, so the turn does not jump when text lands.
+     */
+    loading?: boolean;
+    /**
+     * Offers a copy control. The handler decides what to copy: a turn may hold tool calls and
+     * reasoning this component never sees, so it cannot honestly claim to know the text.
+     */
+    onCopy?: () => void;
+    /** Offers thumbs up and down. */
+    onFeedback?: (feedback: ChatFeedback) => void;
+    usage?: ChatMessageUsage;
+    className?: string;
+}
+
+export declare type ChatMessageStatus = 'streaming' | 'completed' | 'error';
+
+export declare interface ChatMessageUsage {
+    /** The model as a reader would name it, e.g. "Claude Haiku 4.5". */
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+
+/**
+ * Three distinct treatments, not two plus a repaint of one: `plain` is the bare turn, `card`
+ * frames a reply with its own status, copy/rating actions and a token line, and `bubble` is a
+ * message-app chat style with no chrome beyond the bubble itself. All three appear in the
+ * design-sync previews — keep them that way rather than folding `bubble` back into `card`.
+ */
+export declare type ChatMessageVariant = 'plain' | 'card' | 'bubble';
+
+export declare interface ChatModelOption {
+    value: string;
+    label: string;
+    /** The provider's mark. A URL, since providers ship logos rather than icon fonts. */
+    iconSrc?: string;
+    /** A second choice the model offers, e.g. how long it may think. */
+    options?: ChatModelSubOption[];
+}
+
+export declare interface ChatModelPickerProps {
+    models: ChatModelOption[];
+    value: string;
+    /** The chosen sub-option, when the current model offers them. */
+    optionValue?: string;
+    /** Called with the model, and its sub-option when it has them. */
+    onChange: (model: string, option?: string) => void;
+    disabled?: boolean;
+    /**
+     * Opens upward. On by default: this sits under a composer at the bottom of a column, so
+     * downward is almost always off-screen.
+     */
+    openUp?: boolean;
+    'aria-label'?: string;
+}
+
+export declare interface ChatModelSubOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+
+export declare interface ChatProps {
+    children?: default_2.ReactNode;
+    className?: string;
+}
+
+export declare type ChatRole = 'user' | 'assistant';
+
+export declare interface ChatSuggestionProps {
+    text: string;
+    /** Fills the composer — never sends. A suggestion is a starting point the reader edits,
+     *  not a message the component decides to submit on their behalf. */
+    onPick: (text: string) => void;
+    disabled?: boolean;
+    className?: string;
+}
+
+export declare interface ChatThinkingProps {
+    /** Names what is happening, when that is worth saying. Omitted, the bars speak alone. */
+    label?: string;
+    className?: string;
+}
+
+export declare interface ChatThreadProps {
+    children?: default_2.ReactNode;
+    /** Names the transcript for assistive tech, e.g. "Policy assistant conversation". */
+    'aria-label'?: string;
+    /** Shown, centred, while the transcript holds nothing. Ignored when `emptyContent` is
+     *  supplied. */
+    emptyTitle?: string;
+    /** The lines under the title. A node, because guidance is rarely one sentence. Ignored
+     *  when `emptyContent` is supplied. */
+    emptyDescription?: default_2.ReactNode;
+    /** Ignored when `emptyContent` is supplied. */
+    emptyIcon?: default_2.ReactNode;
+    /**
+     * Replaces the `emptyTitle`/`emptyDescription`/`emptyIcon` composition. Renders
+     * left-aligned at the bottom of the transcript, directly above the composer — an empty
+     * conversation should read as ready to start, not as a decorated void.
+     */
+    emptyContent?: default_2.ReactNode;
+    className?: string;
+}
+
+export declare interface ChatToolCallProps {
+    /** The tool the assistant called, e.g. `update_policy_draft`. */
+    name: string;
+    status?: ChatToolCallStatus;
+    /**
+     * The provider's id for this call. Shown once the card is expanded, not on the collapsed
+     * row: it is a long opaque string nobody reads at a glance, and beside the tool name it
+     * was taking two lines of the transcript to say nothing a reader wanted.
+     */
+    callId?: string;
+    /** Arguments the assistant sent. */
+    input?: object;
+    /** What the call returned. Absent while it is still running. */
+    output?: object;
+    defaultExpanded?: boolean;
+    className?: string;
+}
+
+export declare type ChatToolCallStatus = 'running' | 'completed' | 'error';
+
 export declare const Checkbox: default_2.FC<CheckboxProps>;
 
 export declare interface CheckboxProps {
@@ -454,6 +816,24 @@ declare interface CodeBlockProps {
     language?: 'yaml' | 'cedar';
     /** How much of a `json` tree starts collapsed: `true` all of it, a number below that depth. */
     collapsed?: boolean | number;
+    /**
+     * Renders the change between two texts rather than one text, and takes precedence over
+     * `code` and `json`. Only the changed lines are shown, with `context` unchanged ones either
+     * side, so a small edit to a long document reads as a few hunks instead of the whole thing.
+     */
+    diff?: {
+        before: string;
+        after: string;
+        /** Unchanged lines kept either side of each change. Three by convention. */
+        context?: number;
+        /**
+         * Swaps the `+`/`-` gutter and tinted rows for the palette a mock specified for
+         * AI-authored changes: star, minus-sign and middle-dot markers, and a struck-through
+         * removal. Omit to keep the neutral markers; there is no default consumer for the
+         * assistant look yet.
+         */
+        origin?: 'assistant';
+    };
 }
 
 export declare interface CodeTextProps {
@@ -571,6 +951,7 @@ export declare const CustomIcons: {
     ApiKeysIcon: FC<IconProps>;
     ArchiveIcon: FC<IconProps>;
     ArrowLeftIcon: FC<IconProps>;
+    ArrowUpIcon: FC<IconProps>;
     ArrowUpRightIcon: FC<IconProps>;
     AuthenticationIcon: FC<IconProps>;
     BellIcon: FC<IconProps>;
@@ -653,10 +1034,13 @@ export declare const CustomIcons: {
     SliderIcon: FC<IconProps>;
     SortIcon: FC<IconProps>;
     SourceIcon: FC<IconProps>;
+    SparkleIcon: FC<IconProps>;
     StarIcon: FC<IconProps>;
     StepCurrentIcon: FC<IconProps>;
     StepUpcomingIcon: FC<IconProps>;
     SyntheticWebhookIcon: FC<IconProps>;
+    ThumbsDownIcon: FC<IconProps>;
+    ThumbsUpIcon: FC<IconProps>;
     TrashIcon: FC<IconProps>;
     TriangleDownIcon: FC<IconProps>;
     TriangleRightIcon: FC<IconProps>;
@@ -1157,6 +1541,16 @@ export declare const MalachiteContext: default_2.FC<MalachiteContextProps>;
 declare interface MalachiteContextProps {
     children: default_2.ReactNode;
     className?: string;
+    /**
+     * Stretches the shadow host, and every plain div between it and `children`, to 100% of
+     * the height available from this component's own parent. Without it, the host sizes to
+     * its content: a percentage height set further down (inside `children`) has nothing
+     * non-`auto` to resolve against, and a chain of plain `<div>`s does not propagate a
+     * parent's height to its children on its own. Off by default: every existing consumer
+     * relies on the host hugging its content, and turning this on for all of them would
+     * change how much space they take up.
+     */
+    fillHeight?: boolean;
 }
 
 export declare interface MalachiteTheme {
@@ -1469,6 +1863,12 @@ export declare interface MalachiteTheme {
                 border: string;
                 shadow: string;
             };
+            assistant: {
+                background: string;
+                foreground: string;
+                border: string;
+                shadow: string;
+            };
         };
         numberTag: {
             background: string;
@@ -1557,6 +1957,33 @@ export declare interface MalachiteTheme {
             string: string;
             number: string;
             type: string;
+            diffAddedBackground: string;
+            diffRemovedBackground: string;
+            diffAssistantBackground: string;
+            diffAssistantForeground: string;
+            diffAssistantRemovedBackground: string;
+            diffRemovedForeground: string;
+            diffContextForeground: string;
+            diffContextText: string;
+        };
+        /** The conversation's own surfaces — message bubbles, not chrome around them. */
+        chat: {
+            userBubbleBackground: string;
+            userBubbleBorder: string;
+            assistantBubbleBackground: string;
+            assistantBubbleBorder: string;
+            assistantBubbleForeground: string;
+        };
+        /** Chrome marking machine-authored content outside the conversation itself
+         *  (badges, diff callouts) — distinct from `chat`, which is the conversation's
+         *  own bubbles. */
+        assistant: {
+            foreground: string;
+            surfaceBackground: string;
+            surfaceBorder: string;
+            /** Body text sitting on `surfaceBackground` — darker/muted so a run of it reads,
+             *  unlike `foreground`, which is the vivid accent. */
+            surfaceForeground: string;
         };
     };
 }
@@ -1852,6 +2279,8 @@ export declare interface PartialMalachiteTheme {
             rightSideText?: Partial<MalachiteTheme['colors']['text']['rightSideText']>;
         };
         codeBlock?: Partial<MalachiteTheme['colors']['codeBlock']>;
+        chat?: Partial<MalachiteTheme['colors']['chat']>;
+        assistant?: Partial<MalachiteTheme['colors']['assistant']>;
     };
 }
 
@@ -1871,10 +2300,26 @@ declare interface PillButtonProps {
     interactive?: boolean;
     size?: PillButtonSize;
     variant?: PillButtonVariant;
+    shape?: PillButtonShape;
+    tone?: PillButtonTone;
+    /** Sits after the label — a caret on a pill that opens a menu. */
+    trailingIcon?: default_2.ReactNode;
     onClick?: () => void;
 }
 
-declare type PillButtonSize = 'small' | 'medium';
+/**
+ * `tab` squares the top corners so the pill reads as attached to whatever sits above it —
+ * a row of controls hanging under an input, rather than free-floating pills.
+ */
+declare type PillButtonShape = 'pill' | 'tab';
+
+declare type PillButtonSize = 'xsmall' | 'small' | 'medium';
+
+/**
+ * `assistant` is the chrome for AI-authored chips (e.g. `ChangeReview.Jump`): a fixed
+ * violet-on-white look with its own border, independent of `variant`/`selected`.
+ */
+declare type PillButtonTone = 'default' | 'assistant';
 
 declare type PillButtonVariant = 'default' | 'inverted';
 
@@ -2701,7 +3146,9 @@ export declare interface TagProps {
     className?: string;
 }
 
-export declare type TagType = 'primary' | 'secondary' | 'default' | 'error' | 'warning' | 'success' | 'emphasis' | 'info';
+export declare type TagType = 'primary' | 'secondary' | 'default' | 'error' | 'warning' | 'success' | 'emphasis' | 'info'
+/** Marks content a machine produced rather than a person — provenance, not severity. */
+| 'assistant';
 
 declare interface TerminalTextProps {
     bold?: boolean;
@@ -2739,8 +3186,23 @@ declare interface TextAreaProps {
     onChange?: (value: string) => void;
     value?: string;
     onBlur?: () => void;
+    /** Key handling the control cannot own, e.g. Enter-to-submit in a chat composer. */
+    onKeyDown?: (event: default_2.KeyboardEvent<HTMLTextAreaElement>) => void;
+    /**
+     * A control that belongs inside the field, pinned bottom-right — a chat composer's send.
+     * The field reserves room for it, so text cannot run underneath.
+     */
+    inFieldAction?: default_2.ReactNode;
+    /** See `TextAreaTone`. Defaults to `'default'`, so no existing field changes. */
+    tone?: TextAreaTone;
     helperText?: string;
     rows?: number;
+    /**
+     * Grows the field from `rows` up to this many lines as content is typed, then scrolls
+     * internally rather than growing further. Omitted keeps the field at a fixed `rows`
+     * height, the pre-existing behaviour.
+     */
+    maxRows?: number;
     maxLength?: number;
     resize?: 'none' | 'vertical' | 'horizontal' | 'both';
     /**
@@ -2756,6 +3218,14 @@ declare interface TextAreaProps {
 
 declare type TextAreaSize = 'small' | 'medium' | 'large';
 
+/**
+ * `assistant` is the chrome for a field sitting in an AI context (e.g. `Chat.Composer`'s
+ * policy-assistant tone): the field's own focus border recolours to the assistant violet
+ * instead of the default accent — same indicator, different colour, not an extra one. Same
+ * naming precedent as `PillButton`'s own `tone`.
+ */
+declare type TextAreaTone = 'default' | 'assistant';
+
 export declare type TextColor = 'primary' | 'secondary' | 'dimmed' | 'placeholder' | 'emphasis' | 'muted' | 'destructive' | 'success' | 'highlight' | 'warning' | 'error' | 'info' | 'link' | 'inherit';
 
 export declare interface TextProps {