themelia-react-ui 0.0.0-stage → 1.0.0

package/dist/components/features/data-view/data-view.types.d.ts

@@ -0,0 +1,191 @@
+import type { ReactNode } from 'react';
+import type { DataTableProps } from '../table';
+import type { ActiveFilter, FilterConfig, FilterErrorHandler, FilterStrings, FilterTab } from '../filters';
+import type { StringsProp } from '../../../lib/strings';
+import type { DataViewPaginationStrings } from './data-view.strings';
+export type DataViewSortDirection = 'asc' | 'desc';
+export interface DataViewSortState {
+    /** Stable identity for this entry. */
+    id: string;
+    direction: DataViewSortDirection;
+}
+export interface DataViewFilterState<TValue = unknown> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Current value. Controlled. */
+    value: TValue;
+    operator?: string;
+    /** Display label. */
+    label?: ReactNode;
+}
+export interface DataViewSelectionState {
+    selectedIds: readonly string[];
+}
+export interface DataViewShellProps {
+    children?: ReactNode;
+    /** Content above the toolbar. */
+    header?: ReactNode;
+    /** Search, filters, and view controls above the content. */
+    toolbar?: ReactNode;
+    /** Content below the data region. */
+    footer?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    emptySlot?: ReactNode;
+    /** Renders `emptySlot` in place of the content. */
+    empty?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Merged onto the content. */
+    contentClassName?: string;
+}
+export interface DataViewToolbarProps {
+    /** Content at the start of the toolbar. */
+    leading?: ReactNode;
+    /** Search control for the toolbar. */
+    search?: ReactNode;
+    /** Filter controls for the toolbar. */
+    filters?: ReactNode;
+    /** View switcher for the toolbar. */
+    views?: ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface DataViewTableFrameProps {
+    /** Integrated toolbar region, usually search, filters, saved views, and table utility actions. */
+    toolbar?: ReactNode;
+    /** Table or list content. Use `<DataTable surface="flat" />` for the cohesive index treatment. */
+    children?: ReactNode;
+    /** Optional footer for pagination or result counts. */
+    footer?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Merged onto the toolbar. */
+    toolbarClassName?: string;
+    /** Merged onto the content. */
+    contentClassName?: string;
+    /** Merged onto the footer. */
+    footerClassName?: string;
+}
+export interface DataViewTableFilterLayoutProps {
+    /** Merged onto the outermost node. */
+    className?: string;
+    dynamicFilterOptions?: Record<string, FilterConfig['options']>;
+    loadingFilters?: Record<string, boolean>;
+    /** Shell treatment. */
+    variant?: 'default' | 'compact';
+    /** Renders the clear filters. */
+    showClearFilters?: boolean;
+    tabs?: FilterTab[];
+}
+export interface DataViewFilterRowsArgs<TData extends object> {
+    /** Records to render. */
+    data: readonly TData[];
+    activeFilters: readonly ActiveFilter[];
+    /** Filter controls for the toolbar. */
+    filters: readonly FilterConfig[];
+}
+export type DataViewFilterRows<TData extends object> = (args: DataViewFilterRowsArgs<TData>) => TData[];
+export type DataViewFilterValueGetter<TData extends object> = (row: TData, filter: FilterConfig) => unknown;
+export interface DataViewFilteringConfig<TData extends object> {
+    /** Filter definitions rendered by the controlled Filters feature. */
+    filters: FilterConfig[];
+    /** Consumer-owned active filter state. */
+    activeFilters: ActiveFilter[];
+    /** Called with the next controlled filter state. */
+    onFilterChange: (filters: ActiveFilter[]) => void;
+    /** Optional consumer-owned row filtering implementation. */
+    filterRows?: DataViewFilterRows<TData>;
+    /** Optional accessor for nested or formatted row values. */
+    getFilterValue?: DataViewFilterValueGetter<TData>;
+    /** Optional saved-view/filter-tab presets. */
+    tabs?: FilterTab[];
+    /** Render tabs directly or in a compact select trigger. */
+    tabsDisplay?: 'tabs' | 'select';
+    /** Accessible label for the compact tab selector. */
+    tabsLabel?: string;
+    /** Advanced FilterLayout configuration. */
+    layout?: DataViewTableFilterLayoutProps;
+    /** Consumer string overrides for the Filters feature. */
+    strings?: StringsProp<FilterStrings>;
+    /** Explicit locale passed to the Filters feature. */
+    /** Consumer-owned navigation/loading state. */
+    isFiltering?: boolean;
+    /** Receives filtering, validation, and async-option failures. */
+    onError?: FilterErrorHandler;
+}
+export type DataViewTableOptions<TData extends object, TValue = unknown> = Omit<DataTableProps<TData, TValue>, 'columns' | 'data' | 'surface' | 'headerTransparent' | 'topbarContent' | 'topbarEnd' | 'footerContent'>;
+export interface DataViewSlots {
+    /** Content rendered above the filtering row inside the integrated topbar. */
+    topbarContent?: ReactNode;
+    /** Leading content in the auxiliary toolbar row. */
+    toolbarStart?: ReactNode;
+    /** Content rendered after compact saved-view controls. */
+    toolbarAfterFilters?: ReactNode;
+    /** Actions rendered at the end of the table topbar. */
+    toolbarEnd?: ReactNode;
+    /** Table utility content rendered after toolbar actions. */
+    topbarEnd?: ReactNode;
+    /** Footer rendered by the outer DataView frame. */
+    footer?: ReactNode;
+}
+export interface DataViewProps<TData extends object, TValue = unknown> {
+    /** Records to render. */
+    data: readonly TData[];
+    /** Column definitions, in display order. */
+    columns: DataTableProps<TData, TValue>['columns'];
+    /** Filter state and handlers driving the toolbar. */
+    filtering?: DataViewFilteringConfig<TData>;
+    /** Table configuration for the tabular view. */
+    table?: DataViewTableOptions<TData, TValue>;
+    /** Replaces individual regions of the shell. */
+    slots?: DataViewSlots;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface UseDataViewOptions<TData extends object> {
+    /** Records to render. */
+    data: readonly TData[];
+    /** Filter state and handlers driving the toolbar. */
+    filtering?: DataViewFilteringConfig<TData>;
+}
+export interface UseDataViewResult<TData extends object> {
+    /** Rows to render. */
+    rows: readonly TData[];
+    error: unknown | null;
+    failed: boolean;
+}
+export interface DataViewPaginationProps {
+    /** Current page, 1-based. */
+    page: number;
+    /** Total pages, for server-driven paging. */
+    pageCount?: number;
+    /** Result-count summary shown beside the pager. */
+    total?: ReactNode;
+    onPageChange?: (page: number) => void;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface's own copy. */
+    strings?: StringsProp<DataViewPaginationStrings>;
+}
+export interface SavedViewTab {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    count?: ReactNode;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+}
+export interface SavedViewTabsProps {
+    /** View switcher for the toolbar. */
+    views: readonly SavedViewTab[];
+    /** Current value. Controlled. */
+    value: string;
+    onValueChange: (value: string) => void;
+    /** Merged onto the outermost node. */
+    className?: string;
+}

package/dist/components/features/data-view/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useDataView } from './use-data-view';

package/dist/components/features/data-view/hooks/use-data-view.d.ts

@@ -0,0 +1,2 @@
+import type { UseDataViewOptions, UseDataViewResult } from '../data-view.types';
+export declare function useDataView<TData extends object>({ data, filtering, }: UseDataViewOptions<TData>): UseDataViewResult<TData>;

package/dist/components/features/data-view/index.d.ts

@@ -0,0 +1,4 @@
+export { DataView, DataViewPagination, DataViewShell, DataViewTableFrame, DataViewToolbar, SavedViewTabs, } from './data-view';
+export { useDataView } from './hooks';
+export { defaultDataViewFilterTabsLabel, defaultDataViewPaginationStrings, type DataViewPaginationStrings, } from './data-view.strings';
+export type { DataViewFilterState, DataViewFilterRows, DataViewFilterRowsArgs, DataViewFilterValueGetter, DataViewFilteringConfig, DataViewPaginationProps, DataViewProps, DataViewSelectionState, DataViewShellProps, DataViewSlots, DataViewTableOptions, DataViewTableFilterLayoutProps, DataViewSortDirection, DataViewSortState, DataViewTableFrameProps, DataViewToolbarProps, SavedViewTab, SavedViewTabsProps, UseDataViewOptions, UseDataViewResult, } from './data-view.types';

package/dist/components/features/email-composer/document.d.ts

@@ -0,0 +1,8 @@
+import type { JSONContent } from '@tiptap/react';
+import type { EmailBody } from './types';
+import { type EmailComposerStrings } from './strings';
+export declare const emptyDocument: JSONContent;
+export declare const escapeEmailHtml: (value: string) => string;
+export declare function documentHtml(node: JSONContent, strings?: EmailComposerStrings): string;
+export declare function bodyHtml(body: EmailBody, strings?: EmailComposerStrings): string;
+export declare function bodyMarkup(body: EmailBody, strings: EmailComposerStrings): string;

package/dist/components/features/email-composer/email-composer.d.ts

@@ -0,0 +1,2 @@
+import type { EmailComposerProps } from './types';
+export declare function EmailComposer<C = Record<string, never>, K extends string = string>(props: EmailComposerProps<C, K>): import("react").JSX.Element;

package/dist/components/features/email-composer/email-html.d.ts

@@ -0,0 +1,5 @@
+import type { Root, RootContent } from 'hast';
+export declare function parseEmailHtml(html: string): Root;
+export declare function sanitizeEmailTree(tree: Root): Root;
+export declare function sanitizeEmailHtml(html: string): string;
+export declare function emailHtmlText(tree: Root | RootContent): string;

package/dist/components/features/email-composer/engine.d.ts

@@ -0,0 +1,18 @@
+import { type EmailComposerStrings } from './strings';
+import type { ComposerDraft, ComposerIssue, EmailTemplate, PlaceholderDefinition, PlaceholderValue, PreparedEmail, Recipient } from './types';
+export declare function resolveValues<C, K extends string>(draft: ComposerDraft<K>, context: C, definitions: Partial<Record<K, PlaceholderDefinition<C>>>, template?: EmailTemplate<K>): Partial<Record<K, PlaceholderValue>>;
+export declare function renderEmail<C, K extends string>(draft: ComposerDraft<K>, context: C, definitions: Partial<Record<K, PlaceholderDefinition<C>>>, template?: EmailTemplate<K>, strings?: EmailComposerStrings): {
+    email: PreparedEmail<K>;
+    unresolved: string[];
+};
+export declare function inspectDraft<C, K extends string>(draft: ComposerDraft<K>, context: C, definitions: Partial<Record<K, PlaceholderDefinition<C>>>, template?: EmailTemplate<K>, strings?: EmailComposerStrings): {
+    rendered: {
+        email: PreparedEmail<K>;
+        unresolved: string[];
+    } | undefined;
+    renderError: string;
+    issues: ComposerIssue[];
+};
+export declare function validate<C, K extends string>(draft: ComposerDraft<K>, context: C, definitions: Partial<Record<K, PlaceholderDefinition<C>>>, template?: EmailTemplate<K>, strings?: EmailComposerStrings): ComposerIssue[];
+export declare function recipientLabel(recipient: Recipient): string;
+export declare function parseRecipient(value: string): Recipient;

package/dist/components/features/email-composer/http.d.ts

@@ -0,0 +1,6 @@
+import type { PreparedEmail } from './types';
+/** Optional sender adapter. The consuming application owns the endpoint and delivery. */
+export declare function createHttpSender(endpoint: string, options?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}): <K extends string>(email: PreparedEmail<K>) => Promise<void>;

package/dist/components/features/email-composer/index.d.ts

@@ -0,0 +1,6 @@
+export { EmailComposer } from './email-composer';
+export { renderEmail, validate, resolveValues, recipientLabel, parseRecipient } from './engine';
+export { bodyHtml } from './document';
+export { createHttpSender } from './http';
+export { defaultEmailComposerStrings, type EmailComposerStrings } from './strings';
+export type * from './types';

package/dist/components/features/email-composer/partials/body-editor.d.ts

@@ -0,0 +1,11 @@
+import { type Ref } from 'react';
+import type { ComposerEditorAdapter } from '../use-composer';
+import type { EmailBody } from '../types';
+import type { EmailComposerStrings } from '../strings';
+export declare function BodyEditor({ body, disabled, onChange, adapterRef, strings }: {
+    body: EmailBody;
+    disabled: boolean;
+    onChange: (body: EmailBody) => void;
+    adapterRef: Ref<ComposerEditorAdapter>;
+    strings: EmailComposerStrings;
+}): import("react").JSX.Element;

package/dist/components/features/email-composer/partials/data-status.d.ts

@@ -0,0 +1,8 @@
+import type { ComposerDataState } from '../types';
+export declare function dataUnavailable(state?: ComposerDataState): boolean;
+export declare function ComposerDataStatus({ state, label, retryLabel, report }: {
+    state?: ComposerDataState;
+    label: string;
+    retryLabel: string;
+    report: (cause: unknown) => void;
+}): import("react").JSX.Element | null;

package/dist/components/features/email-composer/partials/html-preview.d.ts

@@ -0,0 +1,6 @@
+import type { EmailComposerStrings } from '../strings';
+export declare function HtmlPreview({ html, subject, strings }: {
+    html: string;
+    subject: string;
+    strings: EmailComposerStrings;
+}): import("react").JSX.Element;

package/dist/components/features/email-composer/partials/recipients.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import type { Recipient, RecipientOptions } from '../types';
+import type { EmailComposerStrings } from '../strings';
+export declare function RecipientField({ field, value, options, busy, strings, onChange, error, actions, report }: {
+    field: 'to' | 'cc' | 'bcc';
+    value: Recipient[];
+    options?: RecipientOptions;
+    busy: boolean;
+    strings: EmailComposerStrings;
+    onChange: (value: Recipient[]) => void;
+    error?: string;
+    actions?: ReactNode;
+    report: (cause: unknown) => void;
+}): import("react").JSX.Element;

package/dist/components/features/email-composer/partials/variables.d.ts

@@ -0,0 +1,11 @@
+import type { ComposerApi, ComposerDraft, PlaceholderDefinition, PlaceholderValue } from '../types';
+import type { EmailComposerStrings } from '../strings';
+export declare function Variables<C, K extends string>({ definitions, values, draft, api, strings, busy, editable }: {
+    definitions: Partial<Record<K, PlaceholderDefinition<C>>>;
+    values: Partial<Record<K, PlaceholderValue>>;
+    draft: ComposerDraft<K>;
+    api: ComposerApi<K>;
+    strings: EmailComposerStrings;
+    busy: boolean;
+    editable: boolean;
+}): import("react").JSX.Element;

package/dist/components/features/email-composer/strings.d.ts

@@ -0,0 +1,79 @@
+export declare const defaultEmailComposerStrings: {
+    toolbar: {
+        bold: string;
+        italic: string;
+        strike: string;
+        bulletList: string;
+        orderedList: string;
+        blockquote: string;
+        undo: string;
+        redo: string;
+        sourceCode: string;
+    };
+    title: string;
+    to: string;
+    cc: string;
+    bcc: string;
+    subject: string;
+    body: string;
+    recipientPlaceholder: string;
+    addRecipient: (field: string) => string;
+    recipientLabel: (field: string, index: number) => string;
+    removeRecipient: (email: string) => string;
+    newRecipient: (field: string) => string;
+    templates: string;
+    searchTemplates: string;
+    noTemplates: string;
+    importTemplate: string;
+    templatesUnavailable: string;
+    loadingTemplates: string;
+    loadingVariables: string;
+    loadingRecipients: (field: string) => string;
+    retry: string;
+    dataUnavailable: string;
+    variables: string;
+    variablesDescription: string;
+    insertVariable: (label: string) => string;
+    reset: string;
+    dynamic: string;
+    overridden: string;
+    choose: string;
+    editor: string;
+    preview: string;
+    previewLabel: string;
+    send: string;
+    discard: string;
+    working: string;
+    sent: string;
+    discarded: string;
+    close: string;
+    more: string;
+    link: string;
+    linkTitle: string;
+    linkUrl: string;
+    closeLink: string;
+    closeConversion: string;
+    apply: string;
+    cancel: string;
+    invalidLink: string;
+    convert: string;
+    convertTitle: string;
+    convertDescription: string;
+    missingRecipient: string;
+    invalidRecipients: (field: string) => string;
+    invalidSubject: string;
+    invalidResolvedSubject: string;
+    emptyBody: string;
+    missingVariables: (keys: readonly string[]) => string;
+    attributeVariables: string;
+    unknownVariable: (key: string) => string;
+    duplicateVariable: (key: string) => string;
+    unknownTemplate: (id: string) => string;
+    duplicateTemplate: string;
+    editableRequired: string;
+    editorNotReady: string;
+    unsupportedNode: (node: string) => string;
+    renderError: string;
+    errorTitle: string;
+};
+export type EmailComposerStrings = typeof defaultEmailComposerStrings;

package/dist/components/features/email-composer/types.d.ts

@@ -0,0 +1,195 @@
+import type { ReactNode, Ref } from "react";
+import type { StringsProp } from "../../../lib/strings";
+import type { EmailComposerStrings } from "./strings";
+import type { JSONContent } from "@tiptap/react";
+export type Recipient = {
+    id?: string;
+    name?: string;
+    email: string;
+};
+export type EmailBody = {
+    kind: "rich";
+    document: JSONContent;
+} | {
+    kind: "html";
+    html: string;
+} | {
+    kind: "text";
+    text: string;
+};
+export type PlaceholderValue = string | number | boolean | null;
+export type PlaceholderDefinition<C> = {
+    label: string;
+    description?: string;
+    group?: string;
+    resolve: (context: C) => PlaceholderValue;
+    required?: boolean;
+    fallback?: string;
+    editable?: boolean;
+    input?: "text" | "textarea" | "number" | "date" | "select";
+    options?: readonly {
+        label: string;
+        value: string;
+    }[];
+};
+export type PlaceholderSet<C, K extends string> = {
+    id: string;
+    label: string;
+    definitions: Partial<Record<K, PlaceholderDefinition<C>>>;
+};
+export type EmailTemplate<K extends string = string> = {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    subject?: string;
+    body: EmailBody;
+    requiredPlaceholders?: readonly K[];
+    defaults?: Partial<Record<K, PlaceholderValue>>;
+};
+export type ComposerDraft<K extends string = string> = {
+    to: Recipient[];
+    cc: Recipient[];
+    bcc: Recipient[];
+    subject: string;
+    body: EmailBody;
+    templateId?: string;
+    placeholderOverrides: Partial<Record<K, PlaceholderValue>>;
+};
+export type PreparedEmail<K extends string = string> = {
+    to: Recipient[];
+    cc: Recipient[];
+    bcc: Recipient[];
+    subject: string;
+    html: string;
+    text: string;
+    templateId?: string;
+    resolvedPlaceholders: Partial<Record<K, PlaceholderValue>>;
+};
+export type ComposerIssue = {
+    field: "to" | "cc" | "bcc" | "subject" | "body" | "placeholders";
+    message: string;
+};
+export type ComposerSnapshot<K extends string = string> = {
+    draft: ComposerDraft<K>;
+    dirty: boolean;
+    busy: boolean;
+    issues: readonly ComposerIssue[];
+    unresolvedPlaceholders: readonly string[];
+};
+export type TemplateOptions = {
+    body?: "replace" | "append" | "insert";
+    subject?: "replace" | "preserve";
+    overrides?: "preserve" | "reset";
+};
+export type EditSource = "recipient" | "subject" | "body" | "placeholder" | "template" | "api";
+export type ComposerApi<K extends string = string> = {
+    getState(): ComposerSnapshot<K>;
+    update(updater: (draft: ComposerDraft<K>) => ComposerDraft<K>): void;
+    setSubject(value: string): void;
+    setRecipients(field: "to" | "cc" | "bcc", value: Recipient[]): void;
+    setBody(body: EmailBody): void;
+    setPlaceholder(key: K, value: PlaceholderValue): void;
+    clearPlaceholderOverride(key: K): void;
+    insertPlaceholder(key: K): void;
+    applyTemplate(id: string, options?: TemplateOptions): void;
+    importBody(body: EmailBody): void;
+    insertText(text: string): void;
+    focusBody(): void;
+    validate(): readonly ComposerIssue[];
+    /** Rejects invalid/unavailable data; does not deliver. */
+    prepare(): Promise<PreparedEmail<K>>;
+    /** Handles failures through onError and the alert; use onSent for success. */
+    send(): Promise<void>;
+    /** Handles failures through onError; reset/close follow successful discard only. */
+    discard(): Promise<void>;
+};
+export type ComposerAction<K extends string = string> = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    position?: "toolbar" | "footer-start" | "footer-end" | "overflow";
+    visible?: (state: ComposerSnapshot<K>) => boolean;
+    disabled?: (state: ComposerSnapshot<K>) => boolean;
+    onSelect(api: ComposerApi<K>): void | Promise<void>;
+};
+/** Application-owned async data. Loading/error replace stale data; retry does not start automatically. */
+export type ComposerDataState = {
+    loading?: boolean;
+    error?: ReactNode;
+    onRetry?: () => void | Promise<void>;
+};
+export type RecipientOptions = ComposerDataState & {
+    mode?: "editable" | "readonly" | "disabled";
+    allowAdd?: boolean;
+    allowRemove?: boolean;
+};
+export type EmailComposerProps<C = Record<string, never>, K extends string = string> = {
+    /** Overrides built-in visible and accessible copy. */
+    strings?: StringsProp<EmailComposerStrings>;
+    /** Root DOM hook and sizing/alignment customization; internal insets remain owned. */
+    className?: string;
+    /** Heading content owned by Card or the overlay header. */
+    title?: ReactNode;
+    /** Supporting heading copy using the shared normal text gap. */
+    description?: ReactNode;
+    /** Surface placement. Default: inline. Mount/unmount overlay placements with onClose. */
+    position?: "inline" | "dialog" | "sheet" | "floating";
+    /** Requests that the application unmount the composer. Pending work blocks dismissal. */
+    onClose?: () => void;
+    /** Immutable live context passed to pure variable resolvers; changing it does not edit the draft. */
+    context: C;
+    /** Authoritative controlled draft. onChange proposes changes for the parent to accept. */
+    value?: ComposerDraft<K>;
+    /** Initial uncontrolled draft and discard baseline; remount with a new key for another message. */
+    defaultValue?: Partial<ComposerDraft<K>>;
+    /** Receives a detached draft proposal; treat it immutably when persisting controlled state. */
+    onChange?: (draft: ComposerDraft<K>) => void;
+    /** Per-field editing mode and independent add/remove permissions. */
+    recipients?: Partial<Record<"to" | "cc" | "bcc", RecipientOptions>>;
+    /** Subject permissions; readOnly preserves selectable text. */
+    subject?: {
+        readOnly?: boolean;
+    };
+    /** Typed binding sets and the initial variable-editor disclosure state. */
+    placeholders?: ComposerDataState & {
+        sets: readonly PlaceholderSet<C, K>[];
+        showEditor?: boolean;
+    };
+    /** Application-supplied registry, async resource state, lazy-open callback and importer. */
+    templates?: ComposerDataState & {
+        items: readonly EmailTemplate<K>[];
+        onOpenChange?: (open: boolean) => void;
+        allowImport?: boolean;
+        onImport?: () => Promise<EmailTemplate<K> | null>;
+    };
+    /** Callback-driven toolbar, footer and overflow actions. Actions receive the current command API. */
+    actions?: readonly ComposerAction<K>[];
+    /** Hide send/discard or replace their labels; actions keep shared Button geometry. */
+    buttons?: {
+        send?: false | {
+            label?: string;
+        };
+        discard?: false | {
+            label?: string;
+        };
+    };
+    /** Receives a separate detached proposal with its edit source. */
+    onEdit?: (draft: ComposerDraft<K>, event: {
+        source: EditSource;
+    }) => void;
+    /** May transform the prepared payload or return false to cancel before delivery. */
+    onBeforeSend?: (email: PreparedEmail<K>, api: ComposerApi<K>) => Promise<PreparedEmail<K> | false>;
+    /** Required asynchronous delivery callback. Failure preserves the draft for retry. */
+    onSend: (email: PreparedEmail<K>) => Promise<void>;
+    /** Reports the reviewed delivery snapshot; does not automatically close or reset. */
+    onSent?: (email: PreparedEmail<K>) => void;
+    /** Awaited before reset/close. Rejection or a replaced controlled draft prevents completion. */
+    onDiscard?: (api: ComposerApi<K>) => void | Promise<void>;
+    /** Reports validation, delivery, import and custom-action failures. */
+    onError?: (error: Error) => void;
+    /** Stable command API for inspection, edits, templates, validation and delivery. */
+    apiRef?: Ref<ComposerApi<K>>;
+    /** Application-owned additional content receiving the same command API. */
+    children?: (api: ComposerApi<K>) => ReactNode;
+};