tempest-react-sdk 0.29.0 → 0.30.0

package/dist/tempest-react-sdk.d.ts

@@ -359,6 +359,27 @@ export declare interface ApplyThemeOptions {
     target?: Document | ShadowRoot | HTMLElement;
 }
 
+/**
+ * Apply a move and return the next value.
+ *
+ * Disabled rows are dropped here rather than at the call site, so no caller can
+ * move one by pressing the bulk button — the check has to live where the
+ * decision is made, not in each of the four places that trigger one.
+ *
+ * @param params.value - Current target ids.
+ * @param params.moving - Ids being moved.
+ * @param params.to - Destination pane.
+ * @param params.items - The catalogue, to look disabled rows up.
+ * @param params.order - Ids in catalogue order, so the result stays stable.
+ * @returns The next value, in catalogue order.
+ */
+export declare function applyTransferMove({ value, moving, to, items, }: {
+    value: readonly string[];
+    moving: readonly string[];
+    to: TransferSide;
+    items: readonly TransferItem[];
+}): string[];
+
 /**
  * Compose the Tempest app-wide providers in one place: error boundary →
  * TanStack Query → theme → i18n. Query and theme are on by default; i18n and
@@ -1095,6 +1116,177 @@ export declare const CEPInput: ForwardRefExoticComponent<Omit<InputProps, "value
 /** A `var(--tempest-chart-…)` reference, so the value follows the active theme. */
 export declare type ChartColorToken = string;
 
+/**
+ * A message thread: grouped by author and by day, own messages on one side, with
+ * delivery state, a typing indicator and an optional composer.
+ *
+ * Presentational and controlled, like the rest of the SDK: it takes a list and
+ * emits intent (`onSend`, `onRetry`). Where messages come from — REST, the SDK's
+ * `createWebSocket`, an SSE stream — and how an optimistic insert is done stay with
+ * the app, because those differ per backend and a component that assumed one would
+ * be wrong for most.
+ *
+ * It works as a comment thread too: that is the same component with
+ * `currentUserId` set and no `typing`.
+ *
+ * @example
+ * <Chat
+ *     messages={messages}
+ *     currentUserId={me.id}
+ *     typing={typingNames}
+ *     onSend={(text) => send({ text })}
+ *     onRetry={(message) => resend(message.id)}
+ * />
+ */
+export declare function Chat({ messages, currentUserId, onSend, onRetry, typing, renderAvatar, header, emptyState, groupWindowMs, locale, now, placeholder, composerActions, composerDisabled, onSendError, className, ...rest }: ChatProps): JSX.Element;
+
+/**
+ * The message field of a thread: a textarea that grows with its content, sends on
+ * `Enter` and keeps `Shift+Enter` for a newline.
+ *
+ * Uncontrolled on purpose. A chat draft changes on every keystroke, and lifting
+ * that into app state re-renders the whole thread per character — the one place
+ * where "controlled by default" costs something visible. Apps that need the draft
+ * (a persisted composer, a slash-command menu) read it from `onChange` or drive it
+ * through the ref.
+ *
+ * @example
+ * <ChatComposer onSend={(text) => api.post("/messages", { body: { text } })} />
+ */
+export declare const ChatComposer: ForwardRefExoticComponent<ChatComposerProps & RefAttributes<ChatComposerHandle>>;
+
+/** Imperative handle, so a thread can focus the field after retrying a message. */
+export declare interface ChatComposerHandle {
+    focus: () => void;
+    /** Replace the draft — used to put a failed message back in the field. */
+    setValue: (text: string) => void;
+}
+
+export declare interface ChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_3> {
+    /** Called with the trimmed text. The field clears only when this does not throw. */
+    onSend: (text: string) => void | Promise<void>;
+    /** Locale for the placeholder and the send label. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Rendered to the left of the send button — an attach button, an emoji picker. */
+    actions?: ReactNode;
+    /** Largest height the field grows to, in lines. Default 6. */
+    maxRows?: number;
+    /** Send label. Defaults to the locale string. */
+    sendLabel?: string;
+    /**
+     * Called when `onSend` rejects. The draft is kept either way.
+     *
+     * Without it the rejection is swallowed after the draft is preserved, because
+     * the alternative is worse: re-throwing out of a DOM event handler surfaces as
+     * an unhandled promise rejection — console noise for the developer, a hit in
+     * whatever crash reporter the app runs, and nothing the user can act on. The
+     * visible signal is the text still sitting in the field; wire this to a toast
+     * to say why.
+     */
+    onError?: (error: unknown) => void;
+}
+
+/** A date heading between runs. */
+export declare interface ChatDay {
+    kind: "day";
+    key: string;
+    /** Midnight of that local day, epoch ms — the label is formatted by the view. */
+    date: number;
+}
+
+/** One entry in a thread. */
+export declare interface ChatMessage {
+    /** Stable identity. Used as the React key and by `onRetry`. */
+    id: string;
+    /** What was said. A node, so an app can render a link, an image or a quote. */
+    body: ReactNode;
+    /** Who said it. Compared against `currentUserId` to decide sides. */
+    authorId: string;
+    /** Display name. Falls back to `authorId` in the header of a run. */
+    authorName?: string;
+    /** Epoch milliseconds. */
+    sentAt: number;
+    /**
+     * Delivery state of an outgoing message.
+     *
+     * `"failed"` is the one that matters: without it an app has to invent its own
+     * way to say "this never left", and the user re-types a message that is
+     * sitting right there.
+     */
+    status?: "sending" | "sent" | "read" | "failed";
+    /** Anything the app wants to carry through to its own renderers. */
+    data?: Record<string, unknown>;
+}
+
+export declare interface ChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_2> {
+    /** The thread, **oldest first**. Never reordered by the component. */
+    messages: readonly ChatMessage[];
+    /** Author id treated as "own" — decides side, colour and status ticks. */
+    currentUserId?: string;
+    /** Renders the composer when given. Receives the trimmed text. */
+    onSend?: (text: string) => void | Promise<void>;
+    /** Enables the retry control on a `"failed"` message. */
+    onRetry?: (message: ChatMessage) => void;
+    /** Names currently typing. One, two or a count is phrased for you. */
+    typing?: readonly string[];
+    /** Avatar for the first message of a run — an `<Avatar>`, an `<Icon>`. */
+    renderAvatar?: (message: ChatMessage) => ReactNode;
+    /** Rendered above the thread, inside the panel. */
+    header?: ReactNode;
+    /** Shown when there are no messages. */
+    emptyState?: ReactNode;
+    /** Gap that still keeps consecutive messages in one run. Default 5 min. */
+    groupWindowMs?: number;
+    /** Locale for labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Reference instant for "Hoje"/"Ontem". Default: now, at render time. */
+    now?: number;
+    /** Placeholder for the composer. */
+    placeholder?: string;
+    /** Extra controls inside the composer, before the send button. */
+    composerActions?: ReactNode;
+    /** Disable the composer — no permission, thread archived, offline. */
+    composerDisabled?: boolean;
+    /** Called when `onSend` rejects. The draft stays in the field either way. */
+    onSendError?: (error: unknown) => void;
+}
+
+/** A run of consecutive messages from one author, under one day. */
+export declare interface ChatRun {
+    kind: "run";
+    /** `${authorId}-${first message id}` — stable across re-renders. */
+    key: string;
+    authorId: string;
+    authorName?: string;
+    /** Whether this run belongs to the current user. */
+    own: boolean;
+    messages: ChatMessage[];
+}
+
+export declare type ChatSection = ChatDay | ChatRun;
+
+/** Labels the thread needs, per locale. */
+declare interface ChatStrings {
+    thread: string;
+    today: string;
+    yesterday: string;
+    you: string;
+    typingOne: (name: string) => string;
+    typingTwo: (a: string, b: string) => string;
+    typingMany: (n: number) => string;
+    sending: string;
+    sent: string;
+    read: string;
+    failed: string;
+    retry: string;
+    empty: string;
+    placeholder: string;
+    send: string;
+}
+
+/** Locale strings for the thread. */
+export declare function chatStrings(locale: "pt-BR" | "en"): ChatStrings;
+
 /**
  * Accessible checkbox. Supports a tri-state via `indeterminate` and pairs the
  * input with a label/description column for forms.
@@ -2526,6 +2718,17 @@ export declare interface DateRangePickerProps extends Omit<HTMLAttributes<HTMLDi
     weekStartsOn?: WeekStart_2;
 }
 
+/**
+ * Label for a date heading: `"Hoje"`, `"Ontem"`, or the formatted date.
+ *
+ * @param date - Local midnight of the day being labelled.
+ * @param params.now - Reference instant, so tests and SSR-free renders are stable.
+ */
+export declare function dayLabel(date: number, { locale, now }?: {
+    locale?: "pt-BR" | "en";
+    now?: number;
+}): string;
+
 /** The visible time window of a day, in minutes from midnight. */
 export declare interface DayWindow {
     startMinute: number;
@@ -3575,6 +3778,33 @@ export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
  */
 export declare function groupBy<T, K extends PropertyKey>(items: T[], key: (item: T) => K): Record<K, T[]>;
 
+/**
+ * Turn a flat message list into the sections a thread renders: a date heading
+ * whenever the local day changes, and runs of consecutive messages from the same
+ * author.
+ *
+ * Grouping is what makes a thread readable — repeating the avatar and the name on
+ * every line of a five-line burst turns a conversation into a list of receipts.
+ * The run breaks on a different author, a different day, or a gap longer than
+ * `windowMs`: a reply an hour later is a new beat in the conversation even when
+ * nobody else spoke, and joining it to the earlier burst would put one timestamp
+ * on messages an hour apart.
+ *
+ * Order is taken as given, oldest first, and never sorted here: a thread that
+ * reorders what the server sent would fight optimistic inserts, where the
+ * pending message is deliberately last.
+ *
+ * @param params.messages - Oldest first.
+ * @param params.currentUserId - Author id treated as "own".
+ * @param params.windowMs - Gap that still keeps a run together. Default 5 min.
+ * @returns Sections in render order.
+ */
+export declare function groupMessages({ messages, currentUserId, windowMs, }: {
+    messages: readonly ChatMessage[];
+    currentUserId?: string;
+    windowMs?: number;
+}): ChatSection[];
+
 /**
  * Minimal subset of [`@growthbook/growthbook`](https://docs.growthbook.io/lib/js)
  * used by the adapter. Pass a `GrowthBook` instance directly.
@@ -4611,6 +4841,138 @@ export declare interface LongPressHandlers {
     onContextMenu: (event: MouseEvent_2) => void;
 }
 
+/**
+ * Rendered Markdown, from a node tree — never from an HTML string.
+ *
+ * `dangerouslySetInnerHTML` appears nowhere in this component. That is what makes
+ * rendering somebody else's Markdown safe by construction rather than by a promise
+ * about escaping: a `<script>` in a comment is four characters of text, because text
+ * is all a React child can be.
+ *
+ * Link and image URLs go through a scheme **allowlist** (`http`, `https`, `mailto`,
+ * `tel`, `sms`, plus relative), so `[click](javascript:alert(1))` renders as plain
+ * text. A blocklist would have to enumerate every spelling of `javascript:` and
+ * would miss one.
+ *
+ * @example
+ * <Markdown source={comentario.corpo} linkProps={{ target: "_blank", rel: "noreferrer" }} />
+ */
+export declare function Markdown({ source, headingOffset, highlightCode, showLineNumbers, linkProps, className, ...rest }: MarkdownProps): JSX.Element;
+
+/** Column alignment of a table, from the delimiter row. */
+export declare type MarkdownAlign = "left" | "center" | "right" | null;
+
+/** Block content. */
+export declare type MarkdownBlock = {
+    type: "heading";
+    level: number;
+    children: MarkdownInline[];
+} | {
+    type: "paragraph";
+    children: MarkdownInline[];
+} | {
+    type: "code";
+    language: string | null;
+    value: string;
+} | {
+    type: "quote";
+    children: MarkdownBlock[];
+} | {
+    type: "list";
+    ordered: boolean;
+    start: number;
+    items: MarkdownBlock[][];
+} | {
+    type: "table";
+    align: MarkdownAlign[];
+    head: MarkdownInline[][];
+    rows: MarkdownInline[][][];
+} | {
+    type: "rule";
+};
+
+/** Inline content. */
+export declare type MarkdownInline = {
+    type: "text";
+    value: string;
+} | {
+    type: "strong";
+    children: MarkdownInline[];
+} | {
+    type: "em";
+    children: MarkdownInline[];
+} | {
+    type: "del";
+    children: MarkdownInline[];
+} | {
+    type: "code";
+    value: string;
+} | {
+    type: "link";
+    href: string;
+    children: MarkdownInline[];
+} | {
+    type: "image";
+    src: string;
+    alt: string;
+} | {
+    type: "break";
+};
+
+export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
+    /** The Markdown source. */
+    source: string;
+    /**
+     * Heading level the document's `#` maps to. Default 2.
+     *
+     * A comment body rendered inside a page whose `<h1>` is the page title must not
+     * emit a second `<h1>`; shifting the whole scale keeps the outline valid.
+     */
+    headingOffset?: number;
+    /** Render fenced code with `CodeBlock` (copy button, line numbers). Default `true`. */
+    highlightCode?: boolean;
+    /** Show line numbers in fenced code. Default `false`. */
+    showLineNumbers?: boolean;
+    /** Extra props for every link — `target="_blank"`, an analytics handler. */
+    linkProps?: HTMLAttributes<HTMLAnchorElement> & {
+        target?: string;
+        rel?: string;
+    };
+}
+
+/**
+ * Masonry layout: cards of uneven height packed into columns with an even bottom
+ * edge.
+ *
+ * Measures the rendered cards and deals each one into the shortest column, rather
+ * than using CSS `columns` or `grid-auto-flow: dense`. Both of those are one line
+ * of CSS and neither does this job: CSS `columns` breaks a card across the column
+ * boundary, and a dense grid keeps every row the height of its tallest cell, which
+ * is the ragged bottom edge people reach for masonry to avoid.
+ *
+ * @example
+ * <Masonry items={fotos} itemKey={(foto) => foto.id} columns={{ 0: 1, 700: 2, 1100: 4 }}>
+ *     {(foto) => <img src={foto.url} alt={foto.alt} />}
+ * </Masonry>
+ */
+export declare function Masonry<T>({ items, children, itemKey, columns, gap, className, style, ...rest }: MasonryProps<T>): JSX.Element;
+
+export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_5> {
+    /** What to lay out. */
+    items: readonly T[];
+    /** Render one card. */
+    children: (item: T, index: number) => ReactNode;
+    /** Stable key per item. Index is a fallback nobody should rely on. */
+    itemKey?: (item: T, index: number) => string | number;
+    /**
+     * Column count: a fixed number, or a `width → columns` map read as
+     * "from this width up". Default `{ 0: 1, 640: 2, 1024: 3 }`.
+     */
+    columns?: number | Record<number, number>;
+    /** Gap between cards, any CSS length. Default `var(--tempest-space-4)`. */
+    gap?: string;
+}
+
 /**
  * The matrix as an SVG path, one `M…h…v…h…z` rectangle per dark module.
  *
@@ -5544,6 +5906,21 @@ export { Outlet }
  */
 declare type OverriddenDomProps = "children" | "title" | "onSelect";
 
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_2 = "children" | "onSubmit";
+
+/** DOM attributes the composer redefines. */
+declare type OverriddenDomProps_3 = "onSubmit" | "value" | "defaultValue" | "rows";
+
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_4 = "children" | "onChange" | "defaultValue";
+
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_5 = "children";
+
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_6 = "children";
+
 /**
  * Page wrapper with header + (optional) toolbar + content + footer. Pairs
  * with `Container` when you want a max-width content well.
@@ -5597,6 +5974,14 @@ export { Params }
 /** Query-param values accepted by the API client for a list request. */
 declare type ParamValue = string | number | boolean | undefined | null;
 
+/**
+ * Parse a Markdown document into blocks.
+ *
+ * @param source - Raw Markdown.
+ * @returns Block nodes in document order.
+ */
+export declare function parseMarkdown(source: string): MarkdownBlock[];
+
 /**
  * Validate an unknown response payload against a zod schema.
  *
@@ -6645,6 +7030,28 @@ export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
+/**
+ * URL vetting for links and images in rendered Markdown.
+ *
+ * This is the security boundary of the whole component. Markdown that arrives from
+ * a user — a comment, a ticket description, a review — reaches the DOM as a real
+ * `href`, and `javascript:alert(1)` in a link is script execution on click. So the
+ * scheme is checked against an allowlist rather than a blocklist: a blocklist has
+ * to enumerate `javascript:`, `JaVaScRiPt:`, `java\tscript:`, `&#106;avascript:`
+ * and whatever comes next, and misses the one nobody thought of.
+ */
+/**
+ * The href to render, or `null` when the URL must not be linked.
+ *
+ * Relative URLs (`/docs`, `./x`, `#anchor`, `foo/bar`) are kept: they cannot carry
+ * a scheme, so they cannot execute anything, and dropping them would break every
+ * in-app link.
+ *
+ * @param raw - URL as written in the Markdown.
+ * @returns A safe href, or `null`.
+ */
+export declare function safeLinkUrl(raw: string): string | null;
+
 /** The ten steps of a Tempest tint scale, lightest to darkest. */
 export declare type ScaleStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 
@@ -7289,6 +7696,25 @@ export declare interface SpinnerProps {
 
 export declare type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
 
+/**
+ * Split the catalogue into the two panes.
+ *
+ * The selected ids are the single source of truth — the panes are derived, never
+ * stored. Two stored lists drift the moment the catalogue changes under them: a
+ * permission that is removed upstream lingers in whichever pane held it, and an
+ * id that appears in both is a bug nobody can see.
+ *
+ * Order follows `items`, so both panes read in the catalogue's order rather than
+ * in the order somebody happened to click.
+ *
+ * @param items - The whole catalogue.
+ * @param value - Ids currently on the target side.
+ */
+export declare function splitTransferSides(items: readonly TransferItem[], value: readonly string[]): {
+    source: TransferItem[];
+    target: TransferItem[];
+};
+
 /** Flex-based vertical or horizontal stack with a numeric `gap`. */
 export declare function Stack({ direction, gap, align, justify, wrap, className, style, children, ...props }: StackProps): JSX.Element;
 
@@ -7916,6 +8342,9 @@ export declare function throttle<A extends unknown[]>(fn: (...args: A) => void,
     cancel: () => void;
 };
 
+/** Clock label for a single message — the time, not a relative phrase. */
+export declare function timeLabel(timestamp: number, locale?: "pt-BR" | "en"): string;
+
 /**
  * Vertical event timeline — activity feeds, order trackers, audit logs.
  * Each entry has a marker (color or custom icon), title, optional
@@ -8227,6 +8656,67 @@ export declare interface TrajectoryMapProps extends Omit<HTMLAttributes<HTMLDivE
     onMarkerClick?: (marker: GeoMarker, index: number) => void;
 }
 
+/**
+ * Two panes and a set of move controls: pick a subset out of a catalogue.
+ *
+ * Controlled on **ids of the target side only**. The panes are derived on every
+ * render, never stored, because two stored lists drift the moment the catalogue
+ * changes under them — a permission removed upstream lingers in whichever pane
+ * held it, and an id in both panes is a bug nobody can see.
+ *
+ * @example
+ * const [roles, setRoles] = useState<string[]>([]);
+ *
+ * <Transfer
+ *     items={allRoles}
+ *     value={roles}
+ *     onChange={setRoles}
+ *     sourceTitle="Papéis disponíveis"
+ *     targetTitle="Papéis do usuário"
+ * />
+ */
+export declare function Transfer({ items, value, onChange, sourceTitle, targetTitle, searchable, renderItem, locale, height, disabled, className, ...rest }: TransferProps): JSX.Element;
+
+/** One movable entry. */
+export declare interface TransferItem {
+    /** Stable identity. What `value`/`onChange` carry. */
+    id: string;
+    /** What the row shows. */
+    label: ReactNode;
+    /** Text the search box matches against. Falls back to `label` when it is a string. */
+    searchText?: string;
+    /** Row that cannot move — a mandatory permission, a locked seat. */
+    disabled?: boolean;
+    /** Anything the app wants back in `renderItem`. */
+    data?: Record<string, unknown>;
+}
+
+export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_4> {
+    /** The whole catalogue. Both panes are derived from it. */
+    items: readonly TransferItem[];
+    /** Ids on the target side. Controlled. */
+    value: readonly string[];
+    /** Next value, always in catalogue order. */
+    onChange: (value: string[]) => void;
+    /** Heading of the left pane. Default `"Disponíveis"`. */
+    sourceTitle?: ReactNode;
+    /** Heading of the right pane. Default `"Selecionados"`. */
+    targetTitle?: ReactNode;
+    /** Show a search box above each pane. Default `true` past 8 items. */
+    searchable?: boolean;
+    /** Custom row body. Gets the item and which side it is on. */
+    renderItem?: (item: TransferItem, side: TransferSide) => ReactNode;
+    /** Locale for labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Height of each pane's scroll area, any CSS length. Default `"16rem"`. */
+    height?: string;
+    /** Block every move. */
+    disabled?: boolean;
+}
+
+/** Which pane an operation is about. */
+export declare type TransferSide = "source" | "target";
+
 /**
  * Estimated travel between two coordinates. Mirrors the `TravelEstimate`
  * schema from `tempest-fastapi-sdk` (`geo/schemas.py`), snake_case preserved so
@@ -8350,6 +8840,9 @@ export declare interface TruncateTextProps extends HTMLAttributes<HTMLDivElement
     children: ReactNode;
 }
 
+/** Sentence for the typing indicator, or `null` when nobody is typing. */
+export declare function typingLabel(names: readonly string[], locale?: "pt-BR" | "en"): string | null;
+
 /**
  * Remove duplicate items, keeping the first occurrence of each distinct key.
  *