themelia-react-ui 0.0.0-stage → 1.0.1

package/dist/components/features/mentions/index.d.ts

@@ -0,0 +1,5 @@
+export { useMentions, useMentionsSearch, type MentionEditorHandle, type UseMentionsOptions, type UseMentionsReturn, type UseMentionsSearchOptions, type UseMentionsSearchReturn, } from './hooks';
+export { MentionChip, MentionContent, MentionPicker, MentionInlineSuggestions, type MentionChipProps, type MentionContentProps, type MentionPickerProps, type MentionInlineSuggestionsProps, } from './partials';
+export { defaultMentionPickerStrings, defaultMentionInlineSuggestionsStrings, type MentionPickerStrings, type MentionInlineSuggestionsStrings, } from './mentions.strings';
+export { buildMentionHtml, splitHtmlByMentions, parseMentionsFromHtml, type MentionHtmlSegment, } from './utils';
+export type { Mention, MentionResource, MentionSearchErrorContext, MentionSearchRequestContext, MentionSuggestion, MentionTone, MentionsConfig, MentionsResourceSearch, MentionsSearchErrorHandler, } from './mentions.types';

package/dist/components/features/mentions/mentions.strings.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Default user-facing strings for the `features/mentions` partials.
+ *
+ * Both `<MentionPicker>` and `<MentionInlineSuggestions>` consume their
+ * respective slice; `<MentionInlineSuggestions>` is a strict subset.
+ * Consumers wire backend i18n at the call site:
+ *
+ *   <MentionPicker strings={{ empty: t('mentions.empty') }} … />
+ */
+export interface MentionPickerStrings {
+    /** Surface title. */
+    title: string;
+    searchPlaceholder: string;
+    /** Shown in place of the collection when it has no entries. */
+    empty: string;
+    loading: string;
+}
+export declare const defaultMentionPickerStrings: MentionPickerStrings;
+export interface MentionInlineSuggestionsStrings {
+    /** Surface title. */
+    title: string;
+    /** Shown in place of the collection when it has no entries. */
+    empty: string;
+    loading: string;
+}
+export declare const defaultMentionInlineSuggestionsStrings: MentionInlineSuggestionsStrings;

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

@@ -0,0 +1,100 @@
+/**
+ * Mentions feature — type system.
+ *
+ * "Mention" is the umbrella term for any inline reference to a domain
+ * resource (user, order, booking, …) embedded inside rich-text content.
+ * Used by `features/comments` for `@user`/`#booking` style references,
+ * and by `features/activities` for inline links in activity descriptions.
+ *
+ * Generic in the resource-kind union so consumers can lock down their
+ * domain: `Mention<'user' | 'booking'>`.
+ */
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+import type { SemanticTone } from '../../../lib/component-vocabulary';
+export type MentionTone = Exclude<SemanticTone, 'neutral'>;
+/**
+ * A reference to a domain resource embedded inline in rich-text. Stored
+ * alongside the HTML payload so the surface can be re-rendered with
+ * rich chips even if the HTML markers are stripped or the resource
+ * shape changes.
+ */
+export interface Mention<TKind extends string = string, TData = unknown> {
+    /** Stable id — typically `"<kind>:<resourceId>"`. */
+    id: string;
+    /** Resource kind, must match a key registered in `resources` config. */
+    kind: TKind;
+    /** Human label rendered in the chip. */
+    label: string;
+    /** Optional permalink — chip becomes a link when set. */
+    href?: string;
+    /** Free-form consumer payload (the resource itself, analytics, …). */
+    data?: TData;
+}
+/** Suggestion item returned by a resource-type's `search()` callback. */
+export interface MentionSuggestion<TKind extends string = string, TData = unknown> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    /** Leading avatar. */
+    avatar?: string;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    /** Destination for the entry, when it navigates. */
+    href?: string;
+    /** Records to render. */
+    data?: TData;
+    /** Internal computed kind — set by the provider, do not pass manually. */
+    kind?: TKind;
+}
+export interface MentionSearchRequestContext<TKind extends string = string> {
+    kind: TKind;
+    /** Abort signal for cancelling superseded or unmounted searches. */
+    signal?: AbortSignal;
+}
+export interface MentionSearchErrorContext<TKind extends string = string> {
+    query: string;
+    kind: TKind;
+}
+export type MentionsSearchErrorHandler<TKind extends string = string> = (error: unknown, context: MentionSearchErrorContext<TKind>) => void;
+/**
+ * Configuration for a single resource kind (mention type) the picker
+ * exposes. Consumers register one per domain entity they want to link.
+ */
+export interface MentionResource<TKind extends string = string, TData = unknown> {
+    /** Lucide icon shown in the picker tab + (default) chip leading icon. */
+    icon?: LucideIcon;
+    /** Label shown in the picker tab ("Person", "Booking", …). */
+    label?: string;
+    /** Trigger character that auto-opens the picker (e.g. `@`, `#`). Optional. */
+    trigger?: string;
+    /** Async or sync per-kind search. Wins over `onResourceSearch`. */
+    search?: (query: string, context?: MentionSearchRequestContext<TKind>) => Promise<MentionSuggestion<TKind, TData>[]> | MentionSuggestion<TKind, TData>[];
+    /** Static suggestions (used when `search` is absent or query is empty). */
+    suggestions?: ReadonlyArray<MentionSuggestion<TKind, TData>>;
+    /** Build a permalink from a suggestion. */
+    buildHref?: (suggestion: MentionSuggestion<TKind, TData>) => string | undefined;
+    /** Custom chip renderer — overrides the default badge look. */
+    renderChip?: (mention: Mention<TKind, TData>) => ReactNode;
+    /** Tone applied to the default chip. */
+    tone?: MentionTone;
+}
+/**
+ * Global "rich suggestions" callback. Used when:
+ *   1. The user types one of the registered triggers (e.g. `@`, `#`)
+ *      — the picker opens automatically and calls this with the typed
+ *      needle + matched kind.
+ *   2. A `resources[kind]` entry is missing both `search` and `suggestions`.
+ *
+ * Per-kind `search` / `suggestions` always take precedence when present.
+ */
+export type MentionsResourceSearch<TResource extends string = string> = (needle: string, kind: TResource, context?: MentionSearchRequestContext<TResource>) => Promise<ReadonlyArray<MentionSuggestion<TResource>>> | ReadonlyArray<MentionSuggestion<TResource>>;
+export interface MentionsConfig<TResource extends string = string> {
+    /** Resource catalogue. */
+    resources?: Partial<Record<TResource, MentionResource<TResource>>>;
+    /** Global search fallback. */
+    onResourceSearch?: MentionsResourceSearch<TResource>;
+}

package/dist/components/features/mentions/partials/index.d.ts

@@ -0,0 +1,4 @@
+export { MentionChip, type MentionChipProps } from './mention-chip';
+export { MentionContent, type MentionContentProps, } from './mention-content';
+export { MentionPicker, type MentionPickerProps, type MentionPickerStrings, } from './mention-picker';
+export { MentionInlineSuggestions, type MentionInlineSuggestionsProps, type MentionInlineSuggestionsStrings, } from './mention-inline-suggestions';

package/dist/components/features/mentions/partials/mention-chip.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MentionChip — default rendering for an inline mention/reference.
+ *
+ * Wraps the lib's `<Badge>` base component with the variant driven by
+ * the resource registry's `tone` field. The mapping between the
+ * mentions module's `MentionTone` and the badge's variant lives below
+ * (`TONE_TO_VARIANT`) so consumers can rebrand by editing one table.
+ *
+ * Override paths:
+ *   - `renderMention` on `<MentionContent>` — full takeover
+ *   - `resources.<kind>.renderChip(mention)` — per-kind takeover
+ *   - `resources.<kind>.tone` — quickest "just change the color" override
+ */
+import type { FC, ReactNode } from 'react';
+import type { Mention, MentionResource } from '../mentions.types';
+export interface MentionChipProps {
+    /** The mention this chip represents. */
+    mention: Mention;
+    /** The referenced resource. */
+    resource?: MentionResource<string>;
+    /** Force-disable the chip's link (useful inside the composer draft list). */
+    asLink?: boolean;
+    onClick?: () => void;
+    /** Trailing slot — typically a remove button when shown in the composer. */
+    trailing?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare const MentionChip: FC<MentionChipProps>;

package/dist/components/features/mentions/partials/mention-content.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import type { Mention, MentionsConfig } from '../mentions.types';
+export interface MentionContentProps<TResource extends string = string> {
+    /** HTML body to render. */
+    html: string;
+    /** Mentions resolved on the data — keyed by `data-ref-id`. */
+    mentions?: ReadonlyArray<Mention<TResource>>;
+    /** Resource registry — pass at the call site. */
+    resources?: MentionsConfig<TResource>['resources'];
+    /** Custom per-mention renderer — overrides resource.renderChip. */
+    renderMention?: (mention: Mention<TResource>) => ReactNode;
+    /** Optional sanitizer override. The package safe allowlist is the default. */
+    sanitizer?: (html: string) => string;
+    /** Outer wrapper class. Defaults to a tight prose surface. */
+    className?: string;
+    /**
+     * Set to `false` to skip the default prose wrapper — useful when
+     * embedding inside an existing typed surface (e.g. timeline rows).
+     */
+    prose?: boolean;
+}
+export declare function MentionContent<TResource extends string = string>(props: MentionContentProps<TResource>): ReactNode;

package/dist/components/features/mentions/partials/mention-inline-suggestions.d.ts

@@ -0,0 +1,36 @@
+import { type StringsProp } from '../../../../lib/strings';
+import { type MentionInlineSuggestionsStrings } from '../mentions.strings';
+import type { MentionResource, MentionSuggestion } from '../mentions.types';
+export type { MentionInlineSuggestionsStrings };
+export interface MentionInlineSuggestionsProps<TResource extends string = string> {
+    /** Whether the inline list is showing. */
+    open: boolean;
+    /** Resource kind currently being matched. */
+    activeKind: TResource | null;
+    /** Switches which resource kind is matched. */
+    setActiveKind: (kind: TResource | null) => void;
+    /** Resource kinds available to match. */
+    kinds: ReadonlyArray<TResource>;
+    /** Resource definitions supplying each kind's label and icon. */
+    resources?: Partial<Record<TResource, MentionResource<TResource>>>;
+    /** Per-kind suggestion buckets — used to render result counts on tabs. */
+    suggestionsByKind?: Readonly<Record<string, ReadonlyArray<MentionSuggestion<TResource>>>>;
+    /** Matches for the text typed after the trigger character. */
+    suggestions: ReadonlyArray<MentionSuggestion<TResource>>;
+    /** Replaces the content with the loading state. */
+    loading: boolean;
+    /** Live query the panel echoes in the header; the consumer owns the editor input. */
+    query?: string;
+    /**
+     * Notifies the consumer that the user manually picked a tab, so it
+     * can flip the `manualKindOverride` flag on `useMentionsSearch`.
+     */
+    onManualKindChange?: () => void;
+    /** Fired when an entry is activated. */
+    onSelect: (suggestion: MentionSuggestion<TResource>) => void;
+    /** Overrides this surface's own copy. */
+    strings?: StringsProp<MentionInlineSuggestionsStrings>;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function MentionInlineSuggestions<TResource extends string = string>({ open, activeKind, setActiveKind, kinds, resources, suggestionsByKind, suggestions, loading, query, onManualKindChange, onSelect, strings: stringsProp, className, }: MentionInlineSuggestionsProps<TResource>): import("react").JSX.Element | null;

package/dist/components/features/mentions/partials/mention-picker.d.ts

@@ -0,0 +1,31 @@
+import { type StringsProp } from '../../../../lib/strings';
+import { type MentionPickerStrings } from '../mentions.strings';
+import type { MentionResource, MentionSuggestion } from '../mentions.types';
+export type { MentionPickerStrings };
+export interface MentionPickerProps<TResource extends string = string> {
+    /** Whether the picker is showing. */
+    open: boolean;
+    /** Resource kind currently being browsed. */
+    activeKind: TResource | null;
+    /** Switches which resource kind is browsed. */
+    setActiveKind: (kind: TResource | null) => void;
+    /** Resource kinds offered as tabs. */
+    kinds: ReadonlyArray<TResource>;
+    /** Resource definitions supplying each kind's label and icon. */
+    resources?: Partial<Record<TResource, MentionResource<TResource>>>;
+    /** Current search text. */
+    query: string;
+    /** Updates the search text. */
+    setQuery: (query: string) => void;
+    /** Matches for the current query. */
+    suggestions: ReadonlyArray<MentionSuggestion<TResource>>;
+    /** Replaces the content with the loading state. */
+    loading: boolean;
+    /** Fired when an entry is activated. */
+    onSelect: (suggestion: MentionSuggestion<TResource>) => void;
+    /** Overrides this surface's own copy. */
+    strings?: StringsProp<MentionPickerStrings>;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function MentionPicker<TResource extends string = string>({ open, activeKind, setActiveKind, kinds, resources, query, setQuery, suggestions, loading, onSelect, strings: stringsProp, className, }: MentionPickerProps<TResource>): import("react").JSX.Element | null;

package/dist/components/features/mentions/utils/build-mention-html.d.ts

@@ -0,0 +1,24 @@
+import type { Mention, MentionTone } from '../mentions.types';
+/**
+ * Serialize a `Mention` into the HTML span that gets inserted into a
+ * rich-text body. The structure mirrors `<MentionChip>` so the editor
+ * can style it via the `.rsc-mention` / `[data-ref-tone]` rules (see
+ * mention-chip.css, co-located in this feature) and the read-time
+ * renderer (`<MentionContent>`) can find it again.
+ *
+ *   <span class="rsc-mention" data-ref-id="kind:id" data-ref-kind="kind"
+ *         data-ref-tone="info" contenteditable="false">@Maria Petrova</span>&nbsp;
+ *
+ * `data-ref-tone` is what drives the badge colour in both the editor
+ * (CSS-only, since contenteditable can't host React) and the read-time
+ * renderer (which respects it as a hint when the resource registry
+ * isn't available).
+ *
+ * `contenteditable="false"` tells the browser to treat the chip as an
+ * atomic glyph — backspace deletes the whole span, the cursor moves
+ * past it, and the inner label can't be edited character-by-character.
+ */
+export declare function buildMentionHtml<TKind extends string = string>(mention: Mention<TKind>, options?: {
+    triggerChar?: string;
+    tone?: MentionTone;
+}): string;

package/dist/components/features/mentions/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { buildMentionHtml } from './build-mention-html';
+export { splitHtmlByMentions, type MentionHtmlSegment, } from './split-html-by-mentions';
+export { parseMentionsFromHtml } from './parse-mentions-from-html';

package/dist/components/features/mentions/utils/parse-mentions-from-html.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Walk an HTML string and extract `data-ref-id="kind:id"` spans /
+ * anchors as a list of `Mention` records. Used by the comment composer
+ * to keep its `mentions` state in sync with what's actually present in
+ * the editor — when the user backspaces a chip out of the body, the
+ * draft's mentions list shrinks too.
+ *
+ * The output preserves first-occurrence order and deduplicates by id.
+ * Caller can merge the resulting Mentions with previously known ones to
+ * preserve `href` / `data` payloads that aren't expressible in HTML.
+ */
+import type { Mention } from '../mentions.types';
+export declare function parseMentionsFromHtml<TKind extends string = string>(html: string): Array<Mention<TKind>>;

package/dist/components/features/mentions/utils/split-html-by-mentions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Split an HTML string into a list of `html` chunks and `mention`
+ * placeholders, keyed by the `data-ref-id` attribute the writer set.
+ *
+ * Used by `<MentionContent>` to render the body once with React chips
+ * for the references and `dangerouslySetInnerHTML` for everything else.
+ */
+export type MentionHtmlSegment = {
+    kind: 'html';
+    value: string;
+} | {
+    kind: 'mention';
+    refId: string;
+    fallback: string;
+};
+export declare function splitHtmlByMentions(html: string): MentionHtmlSegment[];

package/dist/components/features/overlays/alert-dialog.d.ts

@@ -0,0 +1,4 @@
+import type { ConfirmDialogProps } from './overlays.types';
+declare function ConfirmDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, initialFocusRef, closeOnEscape, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, tone, showIcon, alertMessage, trigger, destructive, }: ConfirmDialogProps): import("react").JSX.Element;
+export declare const ConfirmDialog: import("react").MemoExoticComponent<typeof ConfirmDialogImpl>;
+export {};

package/dist/components/features/overlays/dialog.d.ts

@@ -0,0 +1,4 @@
+import type { ActionDialogProps } from './overlays.types';
+declare function ActionDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, showCloseButton, surfaceStyle, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, size, trigger, }: ActionDialogProps): import("react").JSX.Element;
+export declare const ActionDialog: import("react").MemoExoticComponent<typeof ActionDialogImpl>;
+export {};

package/dist/components/features/overlays/drawer.d.ts

@@ -0,0 +1,4 @@
+import type { ActionDrawerProps } from './overlays.types';
+declare function ActionDrawerImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, showCloseButton, className, contentClassName, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, direction, width, showFooter, modal, trigger, }: ActionDrawerProps): import("react").JSX.Element;
+export declare const ActionDrawer: import("react").MemoExoticComponent<typeof ActionDrawerImpl>;
+export {};

package/dist/components/features/overlays/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useOverlayActions, type UseOverlayActionsOptions, type UseOverlayActionsReturn, } from './use-overlay-actions';
+export { useOverlayVisibility, useOverlayVisibilityGroup, type OverlayOpenSetter, type OverlayVisibilityGroupState, type OverlayVisibilityProps, type UseOverlayVisibilityGroupOptions, type UseOverlayVisibilityGroupReturn, type UseOverlayVisibilityOptions, type UseOverlayVisibilityReturn, } from './use-overlay-visibility';

package/dist/components/features/overlays/hooks/use-overlay-actions.d.ts

@@ -0,0 +1,24 @@
+import { type StringsProp } from '../../../../lib/strings';
+import { type OverlayStrings } from '../overlays.strings';
+import type { OverlayButtonTone, OverlayActionProps, OverlayTone } from '../overlays.types';
+export interface UseOverlayActionsOptions extends Pick<OverlayActionProps, 'onConfirm' | 'onAsyncConfirm' | 'closeOnAsyncComplete' | 'confirmTone' | 'loading' | 'formId'> {
+    closeDialog: () => void;
+    onCancel?: () => void;
+    customStrings?: StringsProp<OverlayStrings>;
+    emphasis?: boolean;
+    tone?: OverlayTone;
+    /** Called when `onAsyncConfirm` throws. Library DEV-logs the error;
+     *  consumer wires telemetry. */
+    onError?: (error: unknown) => void;
+}
+export interface UseOverlayActionsReturn {
+    /** Overrides this surface's own copy. */
+    strings: OverlayStrings;
+    isExecuting: boolean;
+    handleConfirm: () => Promise<void>;
+    handleCancel: () => void;
+    finalConfirmTone: OverlayButtonTone;
+    confirmButtonOnClick: (() => Promise<void>) | undefined;
+    effectiveLoading: boolean;
+}
+export declare function useOverlayActions({ closeDialog, onConfirm, onAsyncConfirm, closeOnAsyncComplete, confirmTone, loading, formId, onCancel, customStrings, emphasis, tone, onError, }: UseOverlayActionsOptions): UseOverlayActionsReturn;

package/dist/components/features/overlays/hooks/use-overlay-visibility.d.ts

@@ -0,0 +1,36 @@
+import { type Dispatch, type SetStateAction } from 'react';
+export type OverlayOpenSetter = Dispatch<SetStateAction<boolean>>;
+export interface OverlayVisibilityProps {
+    open: boolean;
+    /** Fired when a change is opened. */
+    onOpenChange: (open: boolean) => void;
+}
+export interface UseOverlayVisibilityOptions {
+    defaultOpen?: boolean;
+    open?: boolean;
+    /** Fired when a change is opened. */
+    onOpenChange?: (open: boolean) => void;
+    /** Fired when an entry is opened. */
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+export interface UseOverlayVisibilityReturn {
+    open: boolean;
+    isOpen: boolean;
+    setOpen: OverlayOpenSetter;
+    show: () => void;
+    hide: () => void;
+    toggle: () => void;
+    overlayProps: OverlayVisibilityProps;
+}
+export type OverlayVisibilityGroupState<TKey extends string = string> = Record<TKey, boolean>;
+export interface UseOverlayVisibilityGroupOptions<TKey extends string = string> {
+    defaultOpen?: Partial<Record<TKey, boolean>>;
+    open?: Partial<Record<TKey, boolean>>;
+    /** Fired when a change is opened. */
+    onOpenChange?: (key: TKey, open: boolean, state: OverlayVisibilityGroupState<TKey>) => void;
+    closeOthersOnOpen?: boolean;
+}
+export type UseOverlayVisibilityGroupReturn<TKey extends string = string> = Record<TKey, UseOverlayVisibilityReturn>;
+export declare function useOverlayVisibility({ defaultOpen, open: controlledOpen, onOpenChange, onOpen, onClose, }?: UseOverlayVisibilityOptions): UseOverlayVisibilityReturn;
+export declare function useOverlayVisibilityGroup<const TKeys extends readonly string[]>(keys: TKeys, { defaultOpen, open: controlledOpen, onOpenChange, closeOthersOnOpen, }?: UseOverlayVisibilityGroupOptions<TKeys[number] & string>): UseOverlayVisibilityGroupReturn<TKeys[number] & string>;

package/dist/components/features/overlays/index.d.ts

@@ -0,0 +1,6 @@
+export { ActionDialog } from './dialog';
+export { ActionDrawer } from './drawer';
+export { ConfirmDialog } from './alert-dialog';
+export { useOverlayActions, type UseOverlayActionsOptions, type UseOverlayActionsReturn, useOverlayVisibility, useOverlayVisibilityGroup, type OverlayOpenSetter, type OverlayVisibilityGroupState, type OverlayVisibilityProps, type UseOverlayVisibilityGroupOptions, type UseOverlayVisibilityGroupReturn, type UseOverlayVisibilityOptions, type UseOverlayVisibilityReturn, } from './hooks';
+export type { OverlayTone, OverlaySize, DrawerDirection, OverlayButtonTone, OverlayButtonStyle, OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps, ActionDialogProps, ActionDrawerProps, ConfirmDialogProps, } from './overlays.types';
+export { defaultOverlayStrings, defaultAlertDialogStrings, type OverlayStrings, } from './overlays.strings';

package/dist/components/features/overlays/overlays.strings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Default user-facing strings shared by ActionDialog, ActionDrawer, and
+ * ConfirmDialog recipes.
+ *
+ * Consumers wire backend i18n at the call site:
+ *
+ *   <ActionDialog strings={{ confirm: t('common.confirm') }} … />
+ */
+export interface OverlayStrings {
+    confirm: string;
+    cancel: string;
+    close: string;
+    loading: string;
+    dialogLabel: string;
+    drawerLabel: string;
+    alertDialogLabel: string;
+}
+export declare const defaultOverlayStrings: OverlayStrings;
+export declare const defaultAlertDialogStrings: OverlayStrings;

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

@@ -0,0 +1,169 @@
+import type { ReactNode, RefObject, CSSProperties } from 'react';
+import type { ButtonStyle } from '../../base/buttons';
+import type { SemanticTone } from '../../../lib/component-vocabulary';
+import type { StringsProp } from '../../../lib/strings';
+import type { OverlayStrings } from './overlays.strings';
+export type OverlayTone = Extract<SemanticTone, 'neutral' | 'destructive' | 'warning' | 'info' | 'success'>;
+export type OverlayButtonTone = SemanticTone;
+export type OverlayButtonStyle = Exclude<ButtonStyle, 'ghost'>;
+export type OverlaySize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | 'full';
+export type DrawerDirection = 'left' | 'right' | 'top' | 'bottom';
+/** Presentation and lifecycle shared by every overlay in this family. */
+export interface OverlayBaseProps {
+    /** Visibility, for controlled use. Omit to let the overlay own it via `trigger`. */
+    open?: boolean;
+    /** Fired whenever the overlay wants to open or close. */
+    onOpenChange?: (open: boolean) => void;
+    /** Fired after the overlay closes, whatever dismissed it. */
+    onClose?: () => void;
+    /** Body content between the header and the footer. */
+    children?: ReactNode;
+    /** Heading. Supply one even with `visuallyHideHeader` so the dialog is named. */
+    title?: ReactNode;
+    /** Supporting line under the title. */
+    description?: ReactNode;
+    /**
+     * Keeps `title`/`description` for assistive technology but hides them
+     * visually, for overlays whose body already carries its own heading.
+     */
+    visuallyHideHeader?: boolean;
+    /** Merged onto the overlay root. */
+    className?: string;
+    /** Merged onto the scrollable content region. */
+    contentClassName?: string;
+    /**
+     * Renders the corner dismiss control. Default: `true`. Set `false` for
+     * overlays whose body is the whole surface — a command palette has nowhere
+     * to put a floating X without it landing on the content.
+     */
+    showCloseButton?: boolean;
+    /**
+     * Inline styles for the overlay surface. Exists for overlays that must carry
+     * CSS variables — the theme editor previews the edited theme by setting them
+     * on the dialog itself, which no className can express.
+     */
+    surfaceStyle?: CSSProperties;
+    /** Element to focus on open, instead of the first tabbable node. */
+    initialFocusRef?: RefObject<HTMLElement>;
+    /** Allows Escape to dismiss. Set `false` for destructive or in-progress work. */
+    closeOnEscape?: boolean;
+    /** Allows a backdrop click to dismiss. */
+    closeOnBackdropClick?: boolean;
+    /** Overrides the overlay's own copy (confirm/cancel labels). */
+    strings?: StringsProp<OverlayStrings>;
+}
+/**
+ * Footer buttons and what the confirm button does.
+ *
+ * Exactly one confirm path runs, resolved in this order:
+ *
+ * 1. `formId` — the button submits that form and neither callback fires.
+ * 2. `onConfirm` — runs, then the overlay closes immediately.
+ * 3. `onAsyncConfirm` — awaited with a spinner, closing on success.
+ * 4. none of the above — the overlay just closes.
+ *
+ * Because the list short-circuits, passing `onConfirm` alongside
+ * `onAsyncConfirm` silently skips the async one.
+ */
+export interface OverlayActionProps {
+    /** Renders the cancel button. */
+    showCancel?: boolean;
+    /** Renders the confirm button. */
+    showConfirm?: boolean;
+    /** Fired when cancel is chosen, just before the overlay closes. */
+    onCancel?: () => void;
+    /** Synchronous confirm. Takes precedence over `onAsyncConfirm`; closes on return. */
+    onConfirm?: () => void;
+    /**
+     * Awaited confirm. The confirm button shows a spinner and both buttons
+     * disable until it settles. A rejection leaves the overlay open and is
+     * reported through `onError`. Ignored when `onConfirm` is also set.
+     */
+    onAsyncConfirm?: () => Promise<void>;
+    /** Receives rejected async confirmations so consumers can report or toast them. */
+    onError?: (error: unknown) => void;
+    /**
+     * Closes the overlay once `onAsyncConfirm` resolves. Default: `true`. Set
+     * `false` to keep it open — for a multi-step flow, or to show a result.
+     */
+    closeOnAsyncComplete?: boolean;
+    /** Confirm button tone. Overridden by `tone` when `emphasis` is set. */
+    confirmTone?: OverlayButtonTone;
+    /** Confirm button fill treatment. */
+    confirmStyle?: OverlayButtonStyle;
+    /** Forces the pending presentation for confirm work owned outside the overlay. */
+    loading?: boolean;
+    /**
+     * `id` of a form elsewhere in the tree. The confirm button calls
+     * `requestSubmit()` on it, so native validation runs and the form's own
+     * `onSubmit` owns the outcome — `onConfirm` and `onAsyncConfirm` do not fire.
+     */
+    formId?: string;
+    /** Replaces the generated footer entirely. The props above no longer apply. */
+    footer?: ReactNode;
+}
+/** Semantic weight — the header icon and the confirm button's tone. */
+export interface OverlayEmphasisProps {
+    /**
+     * Lets `tone` drive the header icon and the confirm button colour. Without
+     * it the tone is presentational only and `confirmTone` decides the button.
+     */
+    emphasis?: boolean;
+    /** Semantic tone of the overlay. Default: `'neutral'`. */
+    tone?: OverlayTone;
+    /** Shows the tone's icon beside the title. */
+    showIcon?: boolean;
+    /** Inline notice between the header and the body — a warning or consequence. */
+    alertMessage?: string;
+}
+/** A modal dialog with a title, body, and generated action footer. */
+export interface ActionDialogProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
+    /** Maximum dialog width. Default: `md`. */
+    size?: OverlaySize;
+    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`. */
+    trigger?: ReactNode;
+}
+/** An edge-anchored panel for longer work than a dialog comfortably holds. */
+export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
+    /** Edge the drawer enters from. Default: `right`. */
+    direction?: DrawerDirection;
+    /** Panel measurement along its opening axis — width for left/right, height for top/bottom. */
+    width?: OverlaySize;
+    /** Renders the action footer. Set `false` when the body owns its own actions. */
+    showFooter?: boolean;
+    /**
+     * Whether the drawer takes the page hostage while it is open. Default: `true`.
+     *
+     * A modal drawer traps focus, locks scroll, paints the scrim, and makes the
+     * rest of the document inert — right for a decision the user must finish.
+     * Some side panels are the opposite: a theme editor, an inspector, a live
+     * filter rail, anything whose whole purpose is to sit beside the app while
+     * you keep working in it. Those need `false`, which drops the scrim and the
+     * inerting and leaves the page interactive.
+     *
+     * `'trap-focus'` is the middle setting — focus stays inside, but the page
+     * neither locks its scroll nor stops taking pointer events.
+     *
+     * Non-modal drawers are not announced as dialogs, so do not use one for a
+     * confirmation or anything the user must answer before continuing.
+     */
+    modal?: boolean | 'trap-focus';
+    /** Element that opens the drawer. Supply it for uncontrolled use instead of `open`. */
+    trigger?: ReactNode;
+}
+/**
+ * A short confirmation for a single decision. Prefer `ActionDialog` when the
+ * body needs real content — this one is sized for a question and two answers.
+ */
+export interface ConfirmDialogProps extends OverlayBaseProps, OverlayActionProps {
+    /** Semantic tone, driving the icon and confirm button. Default: `'neutral'`. */
+    tone?: OverlayTone;
+    /** Shows the tone's icon beside the title. */
+    showIcon?: boolean;
+    /** Inline notice explaining the consequence before the user commits. */
+    alertMessage?: string;
+    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`. */
+    trigger?: ReactNode;
+    /** Shorthand for the destructive presentation. */
+    destructive?: boolean;
+}

package/dist/components/features/products/components/index.d.ts

@@ -0,0 +1,17 @@
+export { ProductContractOverview } from './product-contract-overview';
+export { ProductDetailsCard } from './product-details-card';
+export { ProductOptionActionMenu } from './product-option-action-menu';
+export { ProductOperationsCard } from './product-operations-card';
+export { ProductOptionsMatrix } from './product-options-matrix';
+export { ProductOptionsSummary } from './product-options-summary';
+export { ProductOverview } from './product-overview';
+export { ProductPoliciesCard } from './product-policies-card';
+export { ProductQuotePreviewCard } from './product-quote-preview-card';
+export { ProductReadinessCard } from './product-readiness-card';
+export { ProductStructureCard } from './product-structure-card';
+export { ProductVariantActionMenu } from './product-variant-action-menu';
+export { ProductVariantDetails } from './product-variant-details';
+export { ProductVariantEditor } from './product-variant-editor';
+export { ProductVariantsBulkTable } from './product-variants-bulk-table';
+export { ProductVariantsManager } from './product-variants-manager';
+export { ProductVariantsTable } from './product-variants-table';

package/dist/components/features/products/components/product-contract-overview.d.ts

@@ -0,0 +1,5 @@
+import type { ProductContractOverviewProps } from '../products.types';
+export declare function ProductContractOverview({ metrics, terms, rules, onOpenContract, onEditContract, onCreateRule, onSelectRule, onEditRule, onDeleteRule, renderRuleActions, actions, footerSlot, empty, className, strings: stringsProp, }: ProductContractOverviewProps): import("react").JSX.Element;
+export declare namespace ProductContractOverview {
+    var displayName: string;
+}

package/dist/components/features/products/components/product-details-card.d.ts

@@ -0,0 +1,5 @@
+import type { ProductDetailsCardProps } from '../products.types';
+export declare function ProductDetailsCard({ title, description, metadata, media, onEditDetails, actions, headerEnd, footerSlot, empty, className, strings: stringsProp, }: ProductDetailsCardProps): import("react").JSX.Element;
+export declare namespace ProductDetailsCard {
+    var displayName: string;
+}