themelia-react-ui 2.0.5 → 3.0.0

package/dist/components/features/comments/comments.types.d.ts

@@ -15,7 +15,7 @@
  * (composer position, max attachments) come from `<UIProvider>` —
  * see `@/lib/ui-provider`.
  */
-import type { ComponentType, ReactNode } from 'react';
+import type { ReactNode } from 'react';
 import type { StringsProp } from '../../../lib/strings';
 import type { CommentsStrings } from './comments.strings';
 export interface CommentUser {
@@ -135,7 +135,7 @@ export interface CommentsAccessors {
 export interface CommentAttachmentUploadContext {
     /** The original file the user picked / dropped. */
     file: File;
-    /** Throttled progress callback the uploader can call. */
+    /** Progress callback (0–100) the uploader can call; every call updates the chip, so throttle upstream if needed. */
     onProgress: (progress: number) => void;
     /** AbortSignal — aborted when the user removes the chip mid-upload. */
     signal: AbortSignal;
@@ -143,7 +143,9 @@ export interface CommentAttachmentUploadContext {
 export interface CommentsAttachmentsConfig {
     /**
      * Async uploader. Resolves to a fully-formed `CommentAttachment` with
-     * a permanent `url`. Required to enable the attachment button.
+     * a permanent `url`. Required to enable the attachment button. The `id` it
+     * returns is the one submitted in `values.attachments`; an empty one
+     * falls back to the composer's local key.
      */
     onUpload?: (ctx: CommentAttachmentUploadContext) => Promise<CommentAttachment>;
     /** Maximum file size in bytes. */
@@ -188,6 +190,11 @@ export interface CommentsConfig<TUser extends CommentUser = CommentUser, TMeta =
     /** Receives rejected mutation callbacks without throwing through the DOM event. */
     onError?: (error: unknown) => void;
     onPinToggle?: (comment: CommentData<TUser, TMeta, TResource>) => void;
+    /**
+     * Toggles a reaction. Existing reaction chips pass their own emoji; the
+     * "Add reaction" control passes a thumbs-up, so open your own picker from
+     * `renderItem` when users should choose.
+     */
     onReact?: (commentId: string, emoji: string) => void;
     onReply?: (commentId: string) => void;
     /** Optional sanitizer — runs on HTML before render. */
@@ -232,17 +239,17 @@ export interface CommentsProps<TUser extends CommentUser = CommentUser, TMeta =
     canModerate?: boolean;
     /** Composer position — overrides provider's `composerPosition`. */
     composerPosition?: CommentsComposerPosition;
-    /** Maximum draft attachments for this Comments instance. */
-    maxAttachments?: number;
-    /** Whether attachment actions are available. Per-mount prop wins. */
-    allowAttachments?: boolean;
-    /** Whether reactions and their action are rendered. Per-mount prop wins. */
+    /**
+     * Whether reactions are rendered at all: the chips on each comment and the
+     * "Add reaction" control. Leaving out `onReact` only removes the control.
+     */
     allowReactions?: boolean;
-    /** Whether reply actions are rendered. Per-mount prop wins. */
+    /**
+     * Whether the reply control is rendered. Replying is built in whenever the
+     * viewer may comment, with or without `onReply`, so this is how to turn it off.
+     */
     allowReplies?: boolean;
-    /** Hide the card chrome (title, padding) — render bare list+composer. */
-    bare?: boolean;
-    /** Override card title via strings; passing false hides it entirely. */
+    /** Heading above the thread. Defaults to `strings.title`; `false` renders the thread with no heading. */
     title?: ReactNode;
     /** Lifecycle — overrides provider. */
     onSubmit?: CommentsConfig<TUser, TMeta, TResource>['onSubmit'];
@@ -275,11 +282,6 @@ export interface CommentsProps<TUser extends CommentUser = CommentUser, TMeta =
     strings?: StringsProp<CommentsStrings>;
     /** Optional className applied to the outer card. */
     className?: string;
-    /** Optional avatar fallback component (renders initials by default). */
-    avatarComponent?: ComponentType<{
-        user: TUser | undefined;
-        size: 'sm' | 'md' | 'lg';
-    }>;
 }
 export interface CommentTimelineProps<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors, Pick<CommentsSlots<TUser, TMeta, TResource>, 'renderItem' | 'renderAttachment' | 'renderReference' | 'emptySlot'> {
     /** Comments to render, in display order. */
@@ -287,8 +289,16 @@ export interface CommentTimelineProps<TUser extends CommentUser = CommentUser, T
     /** Whether the viewer may edit, delete, or pin others' comments. */
     canModerate?: boolean;
     onDelete?: (commentId: string) => void;
-    /** Removes an attachment from a posted comment; reveals the control when set. */
-    onAttachmentRemove?: (commentId: string, attachmentId: string) => void;
+    /** Ids whose delete is in flight; their delete control is disabled. */
+    pendingDeleteIds?: ReadonlySet<string>;
+    /**
+     * Removes an attachment from a posted comment; reveals the control when set.
+     * A returned promise holds the confirmation pending; a rejection keeps it
+     * open and is reported through `onError`.
+     */
+    onAttachmentRemove?: (commentId: string, attachmentId: string) => void | Promise<void>;
+    /** Receives a rejected attachment removal. */
+    onError?: (error: unknown) => void;
     onEdit?: (comment: CommentData<TUser, TMeta, TResource>) => void;
     onPinToggle?: (comment: CommentData<TUser, TMeta, TResource>) => void;
     onReact?: (commentId: string, emoji: string) => void;
@@ -309,8 +319,16 @@ export interface CommentItemProps<TUser extends CommentUser = CommentUser, TMeta
     /** Whether the viewer may edit, delete, or pin others' comments. */
     canModerate?: boolean;
     onDelete?: (commentId: string) => void;
-    /** Removes an attachment from a posted comment; reveals the control when set. */
-    onAttachmentRemove?: (commentId: string, attachmentId: string) => void;
+    /** The comment's delete is in flight; disables its delete control. */
+    deleting?: boolean;
+    /**
+     * Removes an attachment from a posted comment; reveals the control when set.
+     * A returned promise holds the confirmation pending; a rejection keeps it
+     * open and is reported through `onError`.
+     */
+    onAttachmentRemove?: (commentId: string, attachmentId: string) => void | Promise<void>;
+    /** Receives a rejected attachment removal. */
+    onError?: (error: unknown) => void;
     onEdit?: (comment: CommentData<TUser, TMeta, TResource>) => void;
     onPinToggle?: (comment: CommentData<TUser, TMeta, TResource>) => void;
     onReact?: (commentId: string, emoji: string) => void;
@@ -352,12 +370,8 @@ export interface CommentComposerProps<TResource extends string = string> {
     /** Resource definitions used to resolve mentions. */
     resources?: CommentsConfig<CommentUser, unknown, TResource>['resources'];
     onResourceSearch?: CommentsConfig<CommentUser, unknown, TResource>['onResourceSearch'];
-    /** Files staged on the draft. */
+    /** Attachment uploads: `onUpload` enables them, `maxFiles` caps the draft (default 5) and `disabled` turns them off. */
     attachments?: CommentsAttachmentsConfig;
-    /** Maximum draft attachments for this composer instance. */
-    maxAttachments?: number;
-    /** Whether the attachment action is available. Per-mount prop wins. */
-    allowAttachments?: boolean;
     /** Initial draft values. */
     initialValues?: Partial<CommentFormValues<TResource>>;
     /** Auto-focus the editor on mount. Default: false. */

package/dist/components/features/comments/hooks/use-attachment-upload.d.ts

@@ -15,7 +15,11 @@ export interface UseAttachmentUploadOptions extends CommentsAttachmentsConfig {
 export interface UseAttachmentUploadReturn {
     /** All attachments — uploading + uploaded + failed. */
     attachments: ReadonlyArray<CommentAttachment>;
-    /** Subset of attachments that finished uploading. Use this in the form payload. */
+    /**
+     * Subset of attachments that finished uploading, each under the `id` its
+     * uploader returned (the local chip key when it returned none). Use this in
+     * the form payload; address chips through `attachments`.
+     */
     uploadedAttachments: ReadonlyArray<CommentAttachment>;
     /** True while at least one upload is in flight. */
     isUploading: boolean;

package/dist/components/features/comments/hooks/use-comments.d.ts

@@ -25,7 +25,14 @@ export interface UseCommentsReturn<TUser extends CommentUser = CommentUser, TMet
     startEdit: (comment: CommentData<TUser, TMeta, TResource>) => void;
     cancelComposerMode: () => void;
     submit: (values: CommentFormValues<TResource>) => Promise<void>;
-    deleteComment: (id: string) => Promise<void>;
+    /**
+     * Runs `onDelete`. Never rejects: a failure is reported through `onError`
+     * and resolves `false`, success resolves `true`. A repeat for an id whose
+     * delete is still pending is ignored and resolves `false`.
+     */
+    deleteComment: (id: string) => Promise<boolean>;
+    /** Ids whose delete is in flight; disable their delete control. */
+    pendingDeleteIds: ReadonlySet<string>;
     /** Imperative reset — bumps `resetKey` so the composer clears itself. */
     resetComposer: () => void;
     /** Helpers exposed to onSubmit/onUpdate. */

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

@@ -1,9 +1,16 @@
 export interface DataViewPaginationStrings {
-    /** Current page, 1-based. */
+    /** Word before the current page number, as in "Page 2 / 10". */
     page: string;
     previous: string;
     next: string;
+    /** Accessible name of the pagination landmark. */
+    navigationLabel?: string;
 }
-export declare const defaultDataViewPaginationStrings: DataViewPaginationStrings;
+export declare const defaultDataViewPaginationStrings: {
+    page: string;
+    previous: string;
+    next: string;
+    navigationLabel: string;
+};
 /** Default for the directly overrideable `filterTabsLabel` control label. */
 export declare const defaultDataViewFilterTabsLabel = "View";

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

@@ -95,9 +95,22 @@ export interface DataViewFilteringConfig<TData extends object> {
     activeFilters: ActiveFilter[];
     /** Called with the next controlled filter state. */
     onFilterChange: (filters: ActiveFilter[]) => void;
-    /** Optional consumer-owned row filtering implementation. */
+    /**
+     * Optional consumer-owned row filtering implementation. Without it rows are
+     * filtered on the client:
+     * - A SEARCH filter whose `key` names a row field (or for which
+     *   `getFilterValue` returns a value) reads that field only. A key that
+     *   names no field, such as `q`, searches every value in the row.
+     * - A DATE filter with a date-only value compares calendar days in the
+     *   runtime's local timezone: BETWEEN includes the whole end day and AFTER
+     *   starts on the following day.
+     * - A RANGE filter compares numbers by value, so `19.90` equals `19.9`.
+     */
     filterRows?: DataViewFilterRows<TData>;
-    /** Optional accessor for nested or formatted row values. */
+    /**
+     * Optional accessor for nested or formatted row values. Return `undefined`
+     * to fall back to the value at the filter's `key`.
+     */
     getFilterValue?: DataViewFilterValueGetter<TData>;
     /** Optional saved-view/filter-tab presets. */
     tabs?: FilterTab[];

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

@@ -2,4 +2,9 @@ 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;
+/**
+ * Plain-text part of a prepared email. A link keeps its destination after the
+ * label, list items keep their bullet or number, and an image contributes its
+ * description, so a text-only reader can still follow the message.
+ */
 export declare function emailHtmlText(tree: Root | RootContent): string;

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

@@ -3,4 +3,6 @@ import type { PreparedEmail } from './types';
 export declare function createHttpSender(endpoint: string, options?: {
     headers?: Record<string, string>;
     timeoutMs?: number;
+    /** Message for a failed response that carries no `message` of its own. Receives the HTTP status; the composer shows the result in its error alert. */
+    formatError?: (status: number) => string;
 }): <K extends string>(email: PreparedEmail<K>) => Promise<void>;

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

@@ -1,3 +1,10 @@
+/** Copy for the `confirmClose` confirmation. Optional in `EmailComposerStrings`, so existing complete dictionaries stay valid. */
+declare const confirmCloseStrings: {
+    confirmCloseTitle: string;
+    confirmCloseDescription: string;
+    confirmCloseConfirm: string;
+    confirmCloseCancel: string;
+};
 export declare const defaultEmailComposerStrings: {
     toolbar: {
         bold: string;
@@ -64,7 +71,8 @@ export declare const defaultEmailComposerStrings: {
     invalidSubject: string;
     invalidResolvedSubject: string;
     emptyBody: string;
-    missingVariables: (keys: readonly string[]) => string;
+    /** Receives each missing variable's label, or its key when the token has no definition. */
+    missingVariables: (names: readonly string[]) => string;
     attributeVariables: string;
     unknownVariable: (key: string) => string;
     duplicateVariable: (key: string) => string;
@@ -75,5 +83,12 @@ export declare const defaultEmailComposerStrings: {
     unsupportedNode: (node: string) => string;
     renderError: string;
     errorTitle: string;
+    confirmCloseTitle: string;
+    confirmCloseDescription: string;
+    confirmCloseConfirm: string;
+    confirmCloseCancel: string;
 };
-export type EmailComposerStrings = typeof defaultEmailComposerStrings;
+export type EmailComposerStrings = Omit<typeof defaultEmailComposerStrings, keyof typeof confirmCloseStrings> & Partial<typeof confirmCloseStrings>;
+/** Default `createHttpSender` failure message, used when a failed response carries no message of its own. */
+export declare const defaultEmailRequestFailed: (status: number) => string;
+export {};

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

@@ -22,8 +22,18 @@ export type PlaceholderDefinition<C> = {
     label: string;
     description?: string;
     group?: string;
+    /**
+     * Reads the live value from context. Return `null` or an empty string when
+     * the context has no value: the template default and then `fallback` are
+     * tried in turn. Zero and false are values and are used as they are.
+     */
     resolve: (context: C) => PlaceholderValue;
     required?: boolean;
+    /**
+     * Used when the resolver and the template default both give `null` or an
+     * empty string. With no value from any source the variable stays unresolved,
+     * which blocks sending wherever it is used or `required`.
+     */
     fallback?: string;
     editable?: boolean;
     input?: "text" | "textarea" | "number" | "date" | "select";
@@ -137,14 +147,21 @@ export type EmailComposerProps<C = Record<string, never>, K extends string = str
     position?: "inline" | "dialog" | "sheet" | "floating";
     /** Requests that the application unmount the composer. Pending work blocks dismissal. */
     onClose?: () => void;
+    /**
+     * Asks before the close control or Escape dismisses a draft with unsent
+     * changes; `onClose` runs only once the user confirms. A draft that is
+     * unchanged, or unchanged since it was sent, closes at once. Discard is an
+     * explicit choice and is not asked again. Default: `false`.
+     */
+    confirmClose?: boolean;
     /** 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. */
+    /** Authoritative controlled draft. onValueChange 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;
+    onValueChange?: (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. */

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

@@ -11,84 +11,7 @@ export interface ComposerEditorAdapter {
 export declare function useComposer<C, K extends string>(props: EmailComposerProps<C, K>): {
     api: ComposerApi<K>;
     draft: ComposerDraft<K>;
-    strings: {
-        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;
-    };
+    strings: import("./strings").EmailComposerStrings;
     busy: boolean;
     dataPending: boolean;
     error: string;
@@ -110,6 +33,7 @@ export declare function useComposer<C, K extends string>(props: EmailComposerPro
         issues: ComposerIssue[];
         unresolvedPlaceholders: string[];
     };
+    unsent: boolean;
     report: (cause: unknown) => void;
     runAction: (action: ComposerAction<K>) => Promise<void>;
     importTemplate: () => Promise<void>;

package/dist/components/features/event-calendar/event-calendar-day-cell.d.ts

@@ -1,5 +1,5 @@
 import { type EventCalendarDayCellProps } from './event-calendar.types';
-export declare function EventCalendarDayCell({ data, categories, maxEvents, onClick, onEventClick, compact, strings: stringsProp, renderEvent, }: EventCalendarDayCellProps): import("react").JSX.Element;
+export declare function EventCalendarDayCell({ data, categories, maxEvents, onClick, onEventClick, compact, strings: stringsProp, renderEvent, disabled, locale, tabStop, }: EventCalendarDayCellProps): import("react").JSX.Element;
 export declare namespace EventCalendarDayCell {
     var displayName: string;
 }

package/dist/components/features/event-calendar/event-calendar-event-badge.d.ts

@@ -1,5 +1,5 @@
 import { type EventCalendarEventBadgeProps } from './event-calendar.types';
-export declare function EventCalendarEventBadge({ event, category, compact, onClick, }: EventCalendarEventBadgeProps): import("react").JSX.Element;
+export declare function EventCalendarEventBadge({ event, category, compact, onClick, disabled, locale, tabIndex, strings, }: EventCalendarEventBadgeProps): import("react").JSX.Element;
 export declare namespace EventCalendarEventBadge {
     var displayName: string;
 }

package/dist/components/features/event-calendar/event-calendar-header.d.ts

@@ -2,7 +2,7 @@ import { type EventCalendarHeaderProps } from './event-calendar.types';
 /**
  * Calendar header component
  */
-export declare function EventCalendarHeader({ currentDate, viewMode, displayLabel, onPrevious, onNext, onToday, onViewModeChange, onDateChange, locale, actions, strings: stringsProp, rangeMode: _rangeMode, minDate, maxDate, prevDisabled, nextDisabled, }: EventCalendarHeaderProps): import("react").JSX.Element;
+export declare function EventCalendarHeader({ currentDate, viewMode, displayLabel, onPrevious, onNext, onToday, onViewModeChange, onDateChange, locale, actions, strings: stringsProp, rangeMode: _rangeMode, minDate, maxDate, prevDisabled, nextDisabled, todayDisabled, }: EventCalendarHeaderProps): import("react").JSX.Element;
 export declare namespace EventCalendarHeader {
     var displayName: string;
 }

package/dist/components/features/event-calendar/event-calendar-legend.d.ts

@@ -1,5 +1,5 @@
-import type { EventCalendarLegendProps } from './event-calendar.types';
-export declare function EventCalendarLegend({ categories, visibleCategories, onToggleCategory, enableFiltering, }: EventCalendarLegendProps): import("react").JSX.Element | null;
+import { type EventCalendarLegendProps } from './event-calendar.types';
+export declare function EventCalendarLegend({ categories, visibleCategories, onToggleCategory, enableFiltering, strings, }: EventCalendarLegendProps): import("react").JSX.Element | null;
 export declare namespace EventCalendarLegend {
     var displayName: string;
 }

package/dist/components/features/event-calendar/event-calendar.d.ts

@@ -1,5 +1,5 @@
 import { type EventCalendarProps } from './event-calendar.types';
-export declare function EventCalendar({ events, categories, viewMode: controlledViewMode, defaultViewMode, onViewModeChange, date, defaultDate, onDateChange, onEventClick, onDayClick, maxEventsPerDay, showLegend, showHeader, showWeekends, weekStartsOn: weekStartsOnProp, locale, enableCategoryFilter, visibleCategories: controlledVisibleCategories, onVisibleCategoriesChange, loading, emptyStateMessage, className, compact, actions, strings: stringsProp, dayHeadingVariant, dayHeadingClassName, renderDayHeading, rangeMode, minDate, maxDate, disabledDates, filterEvent, renderEvent, renderDayCell, }: EventCalendarProps): import("react").JSX.Element;
+export declare function EventCalendar({ events, categories, viewMode: controlledViewMode, defaultViewMode, onViewModeChange, date, defaultDate, onDateChange, onEventClick, onDayClick, maxEventsPerDay, showLegend, showHeader, showWeekends, weekStartsOn: weekStartsOnProp, locale, enableCategoryFilter, visibleCategories: controlledVisibleCategories, onVisibleCategoriesChange, loading, error, onRetry, showViewSwitcher, className, compact, actions, strings: stringsProp, dayHeadingVariant, dayHeadingClassName, renderDayHeading, rangeMode, minDate, maxDate, disabledDates, filterEvent, renderEvent, renderDayCell, }: EventCalendarProps): import("react").JSX.Element;
 export declare namespace EventCalendar {
     var displayName: string;
 }