UNPKG

eve

Version:

Filesystem-first framework for durable backend AI agents that run anywhere.

908 lines (901 loc) 27.9 kB
/** * Card elements for cross-platform rich messaging. * * Provides a builder API for creating rich cards that automatically * convert to platform-specific formats: * - Slack: Block Kit * - Teams: Adaptive Cards * - Google Chat: Card v2 * * Supports both function-call and JSX syntax: * * @example Function API * ```ts * import { Card, Text, Actions, Button } from "chat"; * * await thread.post( * Card({ * title: "Order #1234", * children: [ * Text("Total: $50.00"), * Actions([ * Button({ id: "approve", label: "Approve", style: "primary" }), * Button({ id: "reject", label: "Reject", style: "danger" }), * ]), * ], * }) * ); * ``` * * @example JSX API (requires jsxImportSource: "chat" in tsconfig) * ```tsx * /** @jsxImportSource chat *\/ * import { Card, Text, Actions, Button } from "chat"; * * await thread.post( * <Card title="Order #1234"> * <Text>Total: $50.00</Text> * <Actions> * <Button id="approve" style="primary">Approve</Button> * <Button id="reject" style="danger">Reject</Button> * </Actions> * </Card> * ); * ``` */ /** Button style options */ type ButtonStyle = "primary" | "danger" | "default"; /** Text style options */ type TextStyle = "plain" | "bold" | "muted"; /** Button element for interactive actions */ interface ButtonElement { /** Whether this button triggers a regular action or opens a modal dialog. Default: "action" */ actionType?: "action" | "modal"; /** URL to POST action data to when this button is clicked */ callbackUrl?: string; /** If true, the button is displayed in an inactive state and doesn't respond to user actions */ disabled?: boolean; /** Unique action ID for callback routing */ id: string; /** Button label text */ label: string; /** Visual style */ style?: ButtonStyle; type: "button"; /** Optional payload value sent with action callback */ value?: string; } /** Link button element that opens a URL */ interface LinkButtonElement { /** Optional action identifier emitted by platforms that report link clicks */ id?: string; /** Button label text */ label: string; /** Visual style */ style?: ButtonStyle; type: "link-button"; /** URL to open when clicked */ url: string; } /** Text content element */ interface TextElement { /** Text content (supports markdown in some platforms) */ content: string; /** Text style */ style?: TextStyle; type: "text"; } /** Image element */ interface ImageElement { /** Alt text for accessibility */ alt?: string; type: "image"; /** Image URL */ url: string; } /** Visual divider/separator */ interface DividerElement { type: "divider"; } /** Container for action buttons and selects */ interface ActionsElement { /** Button, link button, select, and radio select elements */ children: (ButtonElement | LinkButtonElement | SelectElement | RadioSelectElement)[]; type: "actions"; } /** Section container for grouping elements */ interface SectionElement { /** Section children */ children: CardChild[]; type: "section"; } /** Inline hyperlink element */ interface LinkElement { /** Link label text */ label: string; type: "link"; /** URL to link to */ url: string; } /** Field for key-value display */ interface FieldElement { /** Field label */ label: string; type: "field"; /** Field value */ value: string; } /** Fields container for multi-column layout */ interface FieldsElement { /** Field elements */ children: FieldElement[]; type: "fields"; } /** Column alignment for table elements */ type TableAlignment = "left" | "center" | "right"; /** Table element for structured data display */ interface TableElement { /** Column alignment */ align?: TableAlignment[]; /** Accessible table caption (used by platforms with native table support) */ caption?: string; /** Column header labels */ headers: string[]; /** Rows per page on platforms that paginate tables (Slack: 1-100, default 5) */ pageSize?: number; /** Data rows (each row is an array of cell strings) */ rows: string[][]; type: "table"; } /** Chart segment for pie charts */ interface ChartSegment { /** Legend label (Slack: max 20 characters) */ label: string; /** Segment value; must be greater than 0. Rendered as a percentage of the total. */ value: number; } /** A single data point within a chart series */ interface ChartDataPoint { /** Category label; must match an entry in the chart's `categories` */ label: string; /** Y-axis value (negative values are permitted) */ value: number; } /** A named data series for bar, area, and line charts */ interface ChartSeries { /** One data point per category */ data: ChartDataPoint[]; /** Legend label; must be unique within the chart (Slack: max 20 characters) */ name: string; } /** Pie chart definition */ interface PieChartDefinition { /** Pie segments (Slack: 1-12) */ segments: ChartSegment[]; type: "pie"; } /** Bar, area, or line chart definition */ interface SeriesChartDefinition { /** X-axis category labels in display order (Slack: max 20 characters each) */ categories: string[]; /** Data series (Slack: 1-12); each series needs one point per category */ series: ChartSeries[]; type: "area" | "bar" | "line"; /** X-axis title (Slack: max 50 characters) */ xLabel?: string; /** Y-axis title (Slack: max 50 characters) */ yLabel?: string; } /** Chart definition, discriminated by chart type */ type ChartDefinition = PieChartDefinition | SeriesChartDefinition; /** Chart element for data visualization */ interface ChartElement { /** Chart definition */ chart: ChartDefinition; /** Chart title (Slack: max 50 characters) */ title: string; type: "chart"; } /** Union of all card child element types */ type CardChild = TextElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | LinkElement | TableElement | ChartElement; /** Union of all element types (including nested children) */ type AnyCardElement = CardChild | CardElement | ButtonElement | LinkButtonElement | LinkElement | FieldElement | SelectElement | RadioSelectElement; /** Root card element */ interface CardElement { /** Card content */ children: CardChild[]; /** Header image URL */ imageUrl?: string; /** Card subtitle */ subtitle?: string; /** Card title */ title?: string; type: "card"; } /** Type guard for CardElement */ declare function isCardElement(value: unknown): value is CardElement; /** Options for Card */ interface CardOptions { children?: CardChild[]; imageUrl?: string; subtitle?: string; title?: string; } /** * Create a Card element. * * @example * ```ts * Card({ * title: "Welcome", * children: [Text("Hello!")], * }) * ``` */ declare function Card(options?: CardOptions): CardElement; /** * Create a Text element. * * @example * ```ts * Text("Hello, world!") * Text("Important", { style: "bold" }) * ``` */ declare function Text(content: string, options?: { style?: TextStyle; }): TextElement; /** * Create an Image element. * * @example * ```ts * Image({ url: "https://example.com/image.png", alt: "Description" }) * ``` */ declare function Image(options: { url: string; alt?: string; }): ImageElement; /** * Create a Divider element. * * @example * ```ts * Divider() * ``` */ declare function Divider(): DividerElement; /** * Create a Section container. * * @example * ```ts * Section([ * Text("Grouped content"), * Image({ url: "..." }), * ]) * ``` */ declare function Section(children: CardChild[]): SectionElement; /** * Create an Actions container for buttons and selects. * * @example * ```ts * Actions([ * Button({ id: "ok", label: "OK" }), * Button({ id: "cancel", label: "Cancel" }), * LinkButton({ url: "https://example.com", label: "Learn More" }), * Select({ id: "priority", label: "Priority", options: [...] }), * RadioSelect({ id: "status", label: "Status", options: [...] }), * ]) * ``` */ declare function Actions(children: (ButtonElement | LinkButtonElement | SelectElement | RadioSelectElement)[]): ActionsElement; /** Options for Button */ interface ButtonOptions { /** Whether this button triggers a regular action or opens a modal dialog. Default: "action" */ actionType?: "action" | "modal"; /** URL to POST action data to when this button is clicked */ callbackUrl?: string; /** If true, the button is displayed in an inactive state and doesn't respond to user actions */ disabled?: boolean; /** Unique action ID for callback routing */ id: string; /** Button label text */ label: string; /** Visual style */ style?: ButtonStyle; /** Optional payload value sent with action callback */ value?: string; } /** * Create a Button element. * * @example * ```ts * Button({ id: "submit", label: "Submit", style: "primary" }) * Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" }) * ``` */ declare function Button(options: ButtonOptions): ButtonElement; /** Options for LinkButton */ interface LinkButtonOptions { /** Optional action identifier emitted by platforms that report link clicks */ id?: string; /** Button label text */ label: string; /** Visual style */ style?: ButtonStyle; /** URL to open when clicked */ url: string; } /** * Create a LinkButton element that opens a URL when clicked. * * @example * ```ts * LinkButton({ url: "https://example.com", label: "View Docs" }) * LinkButton({ url: "https://example.com", label: "Learn More", style: "primary" }) * ``` */ declare function LinkButton(options: LinkButtonOptions): LinkButtonElement; /** * Create a Field element for key-value display. * * @example * ```ts * Field({ label: "Status", value: "Active" }) * ``` */ declare function Field(options: { label: string; value: string; }): FieldElement; /** * Create a Fields container for multi-column layout. * * @example * ```ts * Fields([ * Field({ label: "Name", value: "John" }), * Field({ label: "Email", value: "john@example.com" }), * ]) * ``` */ declare function Fields(children: FieldElement[]): FieldsElement; /** Options for Table */ interface TableOptions { /** Column alignment */ align?: TableAlignment[]; /** Accessible table caption (used by platforms with native table support) */ caption?: string; /** Column header labels */ headers: string[]; /** Rows per page on platforms that paginate tables (Slack: 1-100, default 5) */ pageSize?: number; /** Data rows */ rows: string[][]; } /** * Create a Table element for structured data display. * * @example * ```ts * Table({ * headers: ["Name", "Age", "Role"], * rows: [ * ["Alice", "30", "Engineer"], * ["Bob", "25", "Designer"], * ], * }) * ``` */ declare function Table(options: TableOptions): TableElement; /** Options for Chart */ interface ChartOptions { /** Chart definition (pie segments, or bar/area/line series with categories) */ chart: ChartDefinition; /** Chart title (Slack: max 50 characters) */ title: string; } /** * Create a Chart element for data visualization. * * @example Pie chart * ```ts * Chart({ * title: "My Favorite Candy Bars", * chart: { * type: "pie", * segments: [ * { label: "Kit Kat", value: 45 }, * { label: "Twix", value: 28 }, * ], * }, * }) * ``` * * @example Line chart * ```ts * Chart({ * title: "Weekly Sales", * chart: { * type: "line", * categories: ["Week 1", "Week 2"], * xLabel: "Week", * yLabel: "Sales", * series: [ * { * name: "Scranton", * data: [ * { label: "Week 1", value: 120 }, * { label: "Week 2", value: 135 }, * ], * }, * ], * }, * }) * ``` */ declare function Chart(options: ChartOptions): ChartElement; /** * Create a CardLink element for inline hyperlinks. * * @example * ```ts * CardLink({ url: "https://example.com", label: "Visit Site" }) * ``` */ declare function CardLink(options: { url: string; label: string; }): LinkElement; /** * Convert a React element tree to a CardElement tree. * This allows using React's JSX with our card components. * * @example * ```tsx * import React from "react"; * import { Card, Text, fromReactElement } from "chat"; * * const element = ( * <Card title="Hello"> * <Text>World</Text> * </Card> * ); * * const card = fromReactElement(element); * await thread.post(card); * ``` */ declare function fromReactElement(element: unknown): AnyCardElement | null; /** * Generate fallback text from a card child element. * Exported so adapter card converters can call it for unknown types. */ declare function cardChildToFallbackText(child: CardChild): string | null; /** * Modal elements for form dialogs. */ type ModalChild = TextInputElement | SelectElement | ExternalSelectElement | RadioSelectElement | TextElement | FieldsElement; interface ModalElement { callbackId: string; /** URL to POST form values to when this modal is submitted */ callbackUrl?: string; children: ModalChild[]; closeLabel?: string; notifyOnClose?: boolean; /** Arbitrary string passed through the modal lifecycle (e.g., JSON context). */ privateMetadata?: string; submitLabel?: string; title: string; type: "modal"; } interface TextInputElement { id: string; initialValue?: string; label: string; maxLength?: number; multiline?: boolean; optional?: boolean; placeholder?: string; type: "text_input"; } interface SelectElement { id: string; initialOption?: string; label: string; optional?: boolean; options: SelectOptionElement[]; placeholder?: string; type: "select"; } interface ExternalSelectElement { id: string; initialOption?: SelectOptionElement; label: string; minQueryLength?: number; optional?: boolean; placeholder?: string; type: "external_select"; } interface SelectOptionElement { description?: string; label: string; value: string; } interface RadioSelectElement { id: string; initialOption?: string; label: string; optional?: boolean; options: SelectOptionElement[]; type: "radio_select"; } declare function isModalElement(value: unknown): value is ModalElement; interface ModalOptions { callbackId: string; /** URL to POST form values to when this modal is submitted */ callbackUrl?: string; children?: ModalChild[]; closeLabel?: string; notifyOnClose?: boolean; /** Arbitrary string passed through the modal lifecycle (e.g., JSON context). */ privateMetadata?: string; submitLabel?: string; title: string; } declare function Modal(options: ModalOptions): ModalElement; interface TextInputOptions { id: string; initialValue?: string; label: string; maxLength?: number; multiline?: boolean; optional?: boolean; placeholder?: string; } declare function TextInput(options: TextInputOptions): TextInputElement; interface SelectOptions { id: string; initialOption?: string; label: string; optional?: boolean; options: SelectOptionElement[]; placeholder?: string; } declare function Select(options: SelectOptions): SelectElement; interface ExternalSelectOptions { id: string; initialOption?: SelectOptionElement; label: string; minQueryLength?: number; optional?: boolean; placeholder?: string; } declare function ExternalSelect(options: ExternalSelectOptions): ExternalSelectElement; declare function SelectOption(options: { label: string; value: string; description?: string; }): SelectOptionElement; interface RadioSelectOptions { id: string; initialOption?: string; label: string; optional?: boolean; options: SelectOptionElement[]; } declare function RadioSelect(options: RadioSelectOptions): RadioSelectElement; type AnyModalElement = ModalElement | ModalChild | SelectOptionElement; declare function fromReactModalElement(element: unknown): AnyModalElement | null; /** * Custom JSX runtime for chat cards. * * This allows using JSX syntax without React. Configure your bundler: * * tsconfig.json: * { * "compilerOptions": { * "jsx": "react-jsx", * "jsxImportSource": "chat" * } * } * * Or per-file: * /** @jsxImportSource chat *\/ * * Usage: * ```tsx * import { Card, Text, Button, Actions } from "chat"; * * const card = ( * <Card title="Order #1234"> * <Text>Your order is ready!</Text> * <Actions> * <Button id="pickup" style="primary">Schedule Pickup</Button> * </Actions> * </Card> * ); * ``` */ declare const JSX_ELEMENT: unique symbol; /** Props for Card component in JSX */ interface CardProps { children?: unknown; imageUrl?: string; subtitle?: string; title?: string; } /** Props for Text component in JSX */ interface TextProps { children?: string | number | (string | number | undefined)[]; style?: TextStyle; } /** Props for Button component in JSX */ interface ButtonProps { actionType?: "action" | "modal"; callbackUrl?: string; children?: string | number | (string | number | undefined)[]; disabled?: boolean; id: string; label?: string; style?: ButtonStyle; value?: string; } /** Props for LinkButton component in JSX */ interface LinkButtonProps { children?: string | number | (string | number | undefined)[]; id?: string; label?: string; style?: ButtonStyle; url: string; } /** Props for CardLink component in JSX */ interface CardLinkProps { children?: string | number | (string | number | undefined)[]; label?: string; url: string; } /** Props for Image component in JSX */ interface ImageProps { alt?: string; url: string; } /** Props for Field component in JSX */ interface FieldProps { label: string; value: string; } /** Props for container components (Section, Actions, Fields) */ interface ContainerProps { children?: unknown; } /** Props for Divider component (no props) */ type DividerProps = Record<string, never>; /** Props for Modal component in JSX */ interface ModalProps { callbackId: string; callbackUrl?: string; children?: unknown; closeLabel?: string; notifyOnClose?: boolean; privateMetadata?: string; submitLabel?: string; title: string; } /** Props for TextInput component in JSX */ interface TextInputProps { id: string; initialValue?: string; label: string; maxLength?: number; multiline?: boolean; optional?: boolean; placeholder?: string; } /** Props for Select component in JSX */ interface SelectProps { children?: unknown; id: string; initialOption?: string; label: string; optional?: boolean; placeholder?: string; } /** Props for ExternalSelect component in JSX */ interface ExternalSelectProps { id: string; initialOption?: { label: string; value: string; }; label: string; minQueryLength?: number; optional?: boolean; placeholder?: string; } /** Props for SelectOption component in JSX */ interface SelectOptionProps { description?: string; label: string; value: string; } /** Props for Table component in JSX */ interface TableProps { caption?: string; headers: string[]; pageSize?: number; rows: string[][]; } /** Props for Chart component in JSX */ interface ChartProps { chart: ChartDefinition; title: string; } /** Union of all valid JSX props */ type CardJSXProps = CardProps | TextProps | ButtonProps | LinkButtonProps | CardLinkProps | ImageProps | FieldProps | ContainerProps | DividerProps | ModalProps | TextInputProps | SelectProps | ExternalSelectProps | SelectOptionProps | TableProps | ChartProps; /** Component function type with proper overloads */ type CardComponentFunction = typeof Card | typeof Text | typeof Button | typeof LinkButton | typeof CardLink | typeof Image | typeof Field | typeof Divider | typeof Section | typeof Actions | typeof Fields | typeof Modal | typeof TextInput | typeof Select | typeof ExternalSelect | typeof RadioSelect | typeof SelectOption | typeof Table | typeof Chart; /** * Represents a JSX element from the chat JSX runtime. * This is the type returned when using JSX syntax with chat components. */ interface CardJSXElement<P extends CardJSXProps = CardJSXProps> { $$typeof: typeof JSX_ELEMENT; children: unknown[]; props: P; type: CardComponentFunction; } /** Union of all element types that can be produced by chat components */ type ChatElement = CardJSXElement | CardElement | TextElement | ButtonElement | LinkButtonElement | LinkElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | FieldElement | ModalElement | TextInputElement | SelectElement | ExternalSelectElement | SelectOptionElement | RadioSelectElement | TableElement | ChartElement; interface CardComponent { (options?: CardOptions): CardElement; (props: CardProps): ChatElement; } interface TextComponent { (content: string, options?: { style?: TextStyle; }): TextElement; (props: TextProps): ChatElement; } interface ButtonComponent { (options: ButtonOptions): ButtonElement; (props: ButtonProps): ChatElement; } interface LinkButtonComponent { (options: LinkButtonOptions): LinkButtonElement; (props: LinkButtonProps): ChatElement; } interface CardLinkComponent { (options: { url: string; label: string; }): LinkElement; (props: CardLinkProps): ChatElement; } interface ImageComponent { (options: { url: string; alt?: string; }): ImageElement; (props: ImageProps): ChatElement; } interface FieldComponent { (options: { label: string; value: string; }): FieldElement; (props: FieldProps): ChatElement; } interface DividerComponent { (): DividerElement; (props: DividerProps): ChatElement; } interface SectionComponent { (children: CardChild[]): SectionElement; (props: ContainerProps): ChatElement; } interface ActionsComponent { (children: (ButtonElement | LinkButtonElement | SelectElement | RadioSelectElement)[]): ActionsElement; (props: ContainerProps): ChatElement; } interface FieldsComponent { (children: FieldElement[]): FieldsElement; (props: ContainerProps): ChatElement; } interface ModalComponent { (options: ModalOptions): ModalElement; (props: ModalProps): ChatElement; } interface TextInputComponent { (options: TextInputOptions): TextInputElement; (props: TextInputProps): ChatElement; } interface SelectComponent { (options: SelectOptions): SelectElement; (props: SelectProps): ChatElement; } interface ExternalSelectComponent { (options: ExternalSelectOptions): ExternalSelectElement; (props: ExternalSelectProps): ChatElement; } interface SelectOptionComponent { (options: { label: string; value: string; description?: string; }): SelectOptionElement; (props: SelectOptionProps): ChatElement; } interface RadioSelectComponent { (options: RadioSelectOptions): RadioSelectElement; (props: SelectProps): ChatElement; } interface TableComponent { (options: { caption?: string; headers: string[]; pageSize?: number; rows: string[][]; }): TableElement; (props: TableProps): ChatElement; } interface ChartComponent { (options: { chart: ChartDefinition; title: string; }): ChartElement; (props: ChartProps): ChatElement; } /** * Type guard to check if props match CardLinkProps */ declare function isCardLinkProps(props: CardJSXProps): props is CardLinkProps; /** * JSX factory function (used by the JSX transform). * Creates a lazy JSX element that will be resolved when needed. */ declare function jsx<P extends CardJSXProps>(type: CardComponentFunction, props: P & { children?: unknown; }, _key?: string): CardJSXElement<P>; /** * JSX factory for elements with multiple children. */ declare function jsxs<P extends CardJSXProps>(type: CardComponentFunction, props: P & { children?: unknown; }, _key?: string): CardJSXElement<P>; /** * Development JSX factory (same as jsx, but called in dev mode). */ declare const jsxDEV: typeof jsx; /** * Fragment support (flattens children). */ declare function Fragment(props: { children?: unknown; }): CardChild[]; /** * Convert a JSX element tree to a CardElement. * Call this on the root JSX element to get a usable CardElement. */ declare function toCardElement(jsxElement: unknown): CardElement | null; declare function toModalElement(jsxElement: unknown): ModalElement | null; /** * Check if a value is a JSX element (from our runtime or React). */ declare function isJSX(value: unknown): boolean; declare namespace JSX { type Element = ChatElement; type IntrinsicElements = {}; interface IntrinsicAttributes { key?: string | number; } interface ElementChildrenAttribute { children: {}; } } export { type FieldProps as $, type ActionsComponent as A, type ButtonComponent as B, type CardElement as C, type DividerComponent as D, type ExternalSelectComponent as E, type FieldComponent as F, type CardOptions as G, type CardProps as H, type ImageComponent as I, type ChartDataPoint as J, type ChartDefinition as K, type LinkButtonComponent as L, type ModalComponent as M, type ChartOptions as N, type ChartSegment as O, type ChartSeries as P, type ChatElement as Q, type RadioSelectComponent as R, type SectionComponent as S, type TextComponent as T, type ContainerProps as U, type DividerElement as V, type DividerProps as W, type ExternalSelectElement as X, type ExternalSelectOptions as Y, type ExternalSelectProps as Z, type FieldElement as _, type CardChild as a, type FieldsElement as a0, type ImageElement as a1, type ImageProps as a2, type LinkButtonElement as a3, type LinkButtonOptions as a4, type LinkButtonProps as a5, type LinkElement as a6, type ModalChild as a7, type ModalElement as a8, type ModalOptions as a9, jsx as aA, jsxDEV as aB, jsxs as aC, type ModalProps as aa, type PieChartDefinition as ab, type RadioSelectElement as ac, type RadioSelectOptions as ad, type SectionElement as ae, type SelectElement as af, type SelectOptionElement as ag, type SelectOptionProps as ah, type SelectOptions as ai, type SelectProps as aj, type SeriesChartDefinition as ak, type TableAlignment as al, type TableElement as am, type TableOptions as an, type TextElement as ao, type TextInputElement as ap, type TextInputOptions as aq, type TextInputProps as ar, type TextProps as as, type TextStyle as at, type ChartProps as au, Fragment as av, JSX as aw, type TableComponent as ax, type TableProps as ay, isCardLinkProps as az, type ChartElement as b, type CardComponent as c, type CardLinkComponent as d, type ChartComponent as e, type FieldsComponent as f, type SelectComponent as g, type SelectOptionComponent as h, Table as i, type TextInputComponent as j, cardChildToFallbackText as k, fromReactElement as l, fromReactModalElement as m, isCardElement as n, isJSX as o, isModalElement as p, toModalElement as q, type ActionsElement as r, type ButtonElement as s, toCardElement as t, type ButtonOptions as u, type ButtonProps as v, type ButtonStyle as w, type CardJSXElement as x, type CardJSXProps as y, type CardLinkProps as z };