themelia-react-ui 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,3 @@
+export { Questionnaire } from './questionnaire';
+export { defaultQuestionnaireStrings } from './questionnaire.types';
+export type { QuestionnaireAnswer, QuestionnaireAnswers, QuestionnaireOption, QuestionnaireQuestionBase, QuestionnaireTextQuestion, QuestionnaireChoiceQuestion, QuestionnaireBooleanQuestion, QuestionnaireCustomQuestion, QuestionnaireQuestion, QuestionnaireQuestionContext, QuestionnaireSubmitContext, QuestionnaireStrings, QuestionnaireProps } from './questionnaire.types';

package/dist/components/features/questionnaire/questionnaire-control.d.ts

@@ -0,0 +1,3 @@
+import type { QuestionnaireQuestionContext } from './questionnaire.types';
+/** All interactive behavior remains with public Base UI-backed field owners. */
+export declare function QuestionnaireControl({ question, answer, disabled, error, labelId, descriptionId, onAnswerChange, ...context }: QuestionnaireQuestionContext): string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;

package/dist/components/features/questionnaire/questionnaire.d.ts

@@ -0,0 +1,2 @@
+import { type QuestionnaireProps } from './questionnaire.types';
+export declare const Questionnaire: import("react").ForwardRefExoticComponent<QuestionnaireProps & import("react").RefAttributes<HTMLFormElement>>;

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

@@ -0,0 +1,98 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { StringsProp } from '../../../lib/strings';
+export type QuestionnaireAnswer = string | string[] | boolean | undefined;
+export type QuestionnaireAnswers = Record<string, QuestionnaireAnswer>;
+export interface QuestionnaireOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+}
+export interface QuestionnaireQuestionBase {
+    /** Unique stable key, used to retain answers across conditional visibility changes. */
+    id: string;
+    title: string;
+    description?: string;
+    required?: boolean;
+    disabled?: boolean;
+    /** Hidden answers are retained for editing, but excluded from validation/submission. */
+    when?: (answers: QuestionnaireAnswers) => boolean;
+    /** Return an error message, or undefined/true for a valid answer. */
+    validate?: (answer: QuestionnaireAnswer, answers: QuestionnaireAnswers) => string | true | undefined;
+}
+export interface QuestionnaireTextQuestion extends QuestionnaireQuestionBase {
+    type: 'text' | 'textarea';
+    placeholder?: string;
+    /** Native text input type. */
+    inputType?: 'text' | 'email' | 'url' | 'tel';
+    rows?: number;
+    maxLength?: number;
+}
+export interface QuestionnaireChoiceQuestion extends QuestionnaireQuestionBase {
+    type: 'single' | 'multiple' | 'select';
+    options: QuestionnaireOption[];
+}
+export interface QuestionnaireBooleanQuestion extends QuestionnaireQuestionBase {
+    type: 'boolean';
+    label?: string;
+}
+export interface QuestionnaireCustomQuestion extends QuestionnaireQuestionBase {
+    type: 'custom';
+    render: (context: QuestionnaireQuestionContext) => ReactNode;
+}
+export type QuestionnaireQuestion = QuestionnaireTextQuestion | QuestionnaireChoiceQuestion | QuestionnaireBooleanQuestion | QuestionnaireCustomQuestion;
+export interface QuestionnaireQuestionContext {
+    question: QuestionnaireQuestion;
+    answer: QuestionnaireAnswer;
+    answers: QuestionnaireAnswers;
+    disabled: boolean;
+    error?: string;
+    /** Connect custom controls to the visible title and description/error. */
+    labelId: string;
+    descriptionId?: string;
+    onAnswerChange: (answer: QuestionnaireAnswer) => void;
+}
+export interface QuestionnaireSubmitContext {
+    signal: AbortSignal;
+}
+export interface QuestionnaireStrings {
+    previous: string;
+    next: string;
+    submit: string;
+    retry: string;
+    cancel: string;
+    submitting: string;
+    submitted: string;
+    editAnswers: string;
+    empty: string;
+    required: string;
+    invalidChoice: string;
+    invalidFormat: string;
+    progress: string;
+    step: (current: number, total: number) => string;
+    submitError: string;
+}
+export declare const defaultQuestionnaireStrings: QuestionnaireStrings;
+export interface QuestionnaireProps extends Omit<ComponentPropsWithoutRef<'form'>, 'children' | 'onSubmit' | 'defaultValue' | 'onChange'> {
+    questions: readonly QuestionnaireQuestion[];
+    /** Controlled answers. */
+    value?: QuestionnaireAnswers;
+    /** Initial answers for uncontrolled use. */
+    defaultValue?: QuestionnaireAnswers;
+    onValueChange?: (answers: QuestionnaireAnswers) => void;
+    /** Controlled active question key. */
+    questionId?: string;
+    defaultQuestionId?: string;
+    onQuestionChange?: (id: string) => void;
+    disabled?: boolean;
+    /** Receives only visible, enabled questions. Respect signal to cancel application requests. */
+    onSubmit?: (answers: QuestionnaireAnswers, context: QuestionnaireSubmitContext) => void | Promise<void>;
+    onComplete?: (answers: QuestionnaireAnswers) => void;
+    onError?: (error: unknown) => void;
+    formatSubmitError?: (error: unknown) => string;
+    headerSlot?: ReactNode;
+    emptySlot?: ReactNode;
+    /** Replaces the completion state; default includes an edit-answers action. */
+    completionSlot?: ReactNode;
+    strings?: StringsProp<QuestionnaireStrings>;
+}

package/dist/components/features/questionnaire/questionnaire.utils.d.ts

@@ -0,0 +1,5 @@
+import type { QuestionnaireAnswers, QuestionnaireQuestion, QuestionnaireStrings } from './questionnaire.types';
+export declare function getVisibleQuestions(questions: readonly QuestionnaireQuestion[], answers: QuestionnaireAnswers): QuestionnaireQuestion[];
+export declare function getQuestionnaireAnswer(answers: QuestionnaireAnswers, id: string): import("./questionnaire.types").QuestionnaireAnswer;
+export declare function validateQuestion(question: QuestionnaireQuestion, answers: QuestionnaireAnswers, strings: QuestionnaireStrings): string | undefined;
+export declare function getSubmissionAnswers(questions: readonly QuestionnaireQuestion[], answers: QuestionnaireAnswers): QuestionnaireAnswers;

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

@@ -0,0 +1,3 @@
+export { ResourceActionBar, ResourceDetailsSection, ResourceEmptyState, ResourceHeader, ResourceIndexShell, ResourceShowShell, TabbedResourceShell, } from './resource';
+export type { ResourceActionBarProps, ResourceDetailsSectionProps, ResourceEmptyStateProps, ResourceHeaderProps, ResourceIndexShellProps, ResourceShellSlots, ResourceShowShellProps, TabbedResourceShellProps, } from './resource.types';
+export { defaultResourceStrings, type ResourceStrings, } from './resource.strings';

package/dist/components/features/resource/resource.d.ts

@@ -0,0 +1,8 @@
+import type { ResourceActionBarProps, ResourceDetailsSectionProps, ResourceEmptyStateProps, ResourceHeaderProps, ResourceIndexShellProps, ResourceShowShellProps, TabbedResourceShellProps } from './resource.types';
+export declare function ResourceHeader({ title, description, eyebrow, media, avatarUrl, avatarAlt, avatarFallback, icon, iconTone, badges, metadata, actions, className, contentClassName, mediaClassName, }: ResourceHeaderProps): import("react").JSX.Element;
+export declare function ResourceActionBar({ children, leading, trailing, sticky, className }: ResourceActionBarProps): import("react").JSX.Element;
+export declare function ResourceEmptyState(props: ResourceEmptyStateProps): import("react").JSX.Element;
+export declare function ResourceIndexShell(props: ResourceIndexShellProps): import("react").JSX.Element;
+export declare function ResourceShowShell(props: ResourceShowShellProps): import("react").JSX.Element;
+export declare function TabbedResourceShell({ tabs, activeTab, onTabChange, tabsClassName, moreLabel, tabsAriaLabel, toolbar, slots, className, strings: stringsProp, ...props }: TabbedResourceShellProps): import("react").JSX.Element;
+export declare function ResourceDetailsSection({ metadata, metadataColumns, metadataDense, body, help, children, contentClassName, ...props }: ResourceDetailsSectionProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+/** Default copy for state-aware resource workspace replacement states. */
+export interface ResourceStrings {
+    loadingLabel: string;
+    loadingDescription: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    errorTitle: string;
+    errorDescription: string;
+    retryLabel: string;
+    tabsAriaLabel: string;
+}
+export declare const defaultResourceStrings: ResourceStrings;

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

@@ -0,0 +1,161 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { IconBadgeTone } from '../../base/display';
+import type { EmptyStateProps, MetadataListItem } from '../../blocks/data-display';
+import type { ActionMenuAction } from '../../base/action-menu';
+import type { OverflowTabItem } from '../../base/navigation';
+import type { StringsProp } from '../../../lib/strings';
+import type { CardSurface, ComponentScale } from '../../../lib/component-vocabulary';
+import type { ResourceStrings } from './resource.strings';
+/** Structural padding preset for resource content blocks. */
+export type ResourceBlockPadding = ComponentScale;
+/** Chrome treatment for resource content blocks. */
+export type ResourceBlockSurface = CardSurface;
+export interface ResourceShellSlots {
+    /** Replaces the generated identity header. */
+    header?: ReactNode;
+    /** Replaces the toolbar region, including the default tab toolbar. */
+    toolbar?: ReactNode;
+    /** Related context rendered beside the primary column when the container is wide enough. */
+    aside?: ReactNode;
+    /** Content rendered after the primary workspace body. */
+    footer?: ReactNode;
+    /** Replaces the default loading panel. */
+    loading?: ReactNode;
+    /** Replaces the default empty state. */
+    empty?: ReactNode;
+    /** Replaces the default error state. */
+    error?: ReactNode;
+}
+export interface ResourceIndexShellProps {
+    /** Primary workspace content. Replaced by loading, error, or empty state when active. */
+    children?: ReactNode;
+    /** Generated header title. Omit when supplying `slots.header`. */
+    title?: ReactNode;
+    /** Generated header description. */
+    description?: ReactNode;
+    /** Generated header actions. */
+    actions?: ReactNode;
+    /** Content between the header and primary workspace body. */
+    toolbar?: ReactNode;
+    /** Empty-state override. Prefer `slots.empty` when configuring several regions together. */
+    emptySlot?: ReactNode;
+    /** Replaces the primary content with the empty state. */
+    empty?: boolean;
+    /** Replaces the primary content with the loading panel. */
+    loading?: boolean;
+    /** Error content, value, or Error object. Truthy values replace the primary content. */
+    error?: ReactNode | Error;
+    /** Retry callback used by the default error state. */
+    onRetry?: () => void;
+    /** Replaceable workspace regions for consumer-owned composition. */
+    slots?: ResourceShellSlots;
+    /** Class name for the outer named container. */
+    className?: string;
+    /** Class name for the generated header. */
+    headerClassName?: string;
+    /** Class name for the primary body region. */
+    contentClassName?: string;
+    /** Copy overrides for loading, empty, error, retry, and tab labels. */
+    strings?: StringsProp<ResourceStrings>;
+}
+export interface ResourceShowShellProps extends ResourceIndexShellProps {
+    /** Class name for `slots.aside`. */
+    asideClassName?: string;
+}
+export interface ResourceHeaderProps {
+    /** Primary resource identity. */
+    title: ReactNode;
+    /** Supporting resource summary. */
+    description?: ReactNode;
+    /** Quiet context rendered above the title. */
+    eyebrow?: ReactNode;
+    /** Full media override. Takes precedence over avatar and icon props. */
+    media?: ReactNode;
+    /** Avatar image URL used when `media` is omitted. */
+    avatarUrl?: string;
+    /** Accessible alternative text for the avatar image. */
+    avatarAlt?: string;
+    /** Avatar fallback. Defaults to initials derived from a string title. */
+    avatarFallback?: ReactNode;
+    /** Icon rendered in an IconBadge when no media or avatar is supplied. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Semantic tone for the generated IconBadge. */
+    iconTone?: IconBadgeTone;
+    /** Status or identity badges rendered beside the title. */
+    badges?: ReactNode;
+    /** Compact resource facts rendered below the description. */
+    metadata?: ReactNode;
+    /** Primary and secondary header actions. */
+    actions?: ReactNode;
+    /** Class name for the page-header root. */
+    className?: string;
+    /** Class name for the page-header content region. */
+    contentClassName?: string;
+    /** Class name for generated avatar or icon media. */
+    mediaClassName?: string;
+}
+export interface ResourceActionBarProps {
+    /** Default leading content when `leading` is omitted. */
+    children?: ReactNode;
+    /** Filters, selection summary, or primary workspace controls. */
+    leading?: ReactNode;
+    /** Trailing actions. */
+    trailing?: ReactNode;
+    /** Pins the bar below the configured shell header. */
+    sticky?: boolean;
+    /** Class name for the action-bar root. */
+    className?: string;
+}
+export interface ResourceEmptyStateProps extends EmptyStateProps {
+}
+interface ResourceSectionFrameProps {
+    /** Block title. */
+    title?: ReactNode;
+    /** Supporting block description. */
+    description?: ReactNode;
+    /** Overflow actions rendered by ContentBlock. */
+    actions?: ActionMenuAction[];
+    /** Custom action rendered directly in the header. */
+    headerAction?: ReactNode;
+    /** Primary block content. */
+    children?: ReactNode;
+    /** Footer content rendered after the body. */
+    footer?: ReactNode;
+    /** Structural padding preset. */
+    padding?: ResourceBlockPadding;
+    /** Surface chrome. Use `flat` when embedding inside an existing frame. */
+    surface?: ResourceBlockSurface;
+    /** Class name for the block root. */
+    className?: string;
+    /** Class name for the block content region. */
+    contentClassName?: string;
+}
+export interface ResourceDetailsSectionProps extends ResourceSectionFrameProps {
+    /** Structured resource facts rendered before free-form body content. */
+    metadata?: MetadataListItem[];
+    /** Maximum fact columns. The list reduces columns from its actual container width. */
+    metadataColumns?: 1 | 2 | 3 | 4;
+    /** Uses the compact metadata rhythm. */
+    metadataDense?: boolean;
+    /** Structured body content rendered after metadata. */
+    body?: ReactNode;
+    /** Quiet guidance rendered after the section content. */
+    help?: ReactNode;
+}
+export interface TabbedResourceShellProps extends ResourceShowShellProps {
+    /** Workspace tabs, including optional overflow metadata. */
+    tabs: OverflowTabItem[];
+    /** Controlled active tab identifier. */
+    activeTab?: string;
+    /** Called when a visible or overflow tab is selected. */
+    onTabChange?: (id: string) => void;
+    /** Class name for the overflow tab bar. */
+    tabsClassName?: string;
+    /** Label for the overflow-tabs trigger. */
+    moreLabel?: string;
+    /** Accessible label for the tab list. */
+    tabsAriaLabel?: string;
+}
+export {};

package/dist/components/features/resource-assignment/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useSharedResourceCard } from './use-shared-resource-card';
+export type { UseSharedResourceCardOptions, UseSharedResourceCardResult, } from './use-shared-resource-card';

package/dist/components/features/resource-assignment/hooks/use-shared-resource-card.d.ts

@@ -0,0 +1,32 @@
+import type { SharedResourceCardContext } from '../resource-assignment.types';
+export type UseSharedResourceCardOptions<TResource, TSuggestion> = {
+    /** Persisted assignment. `null` is the only empty state. */
+    resource: TResource | null;
+    /** Map persisted data when neither `value` nor first-open `defaultValue` supplies selection. */
+    mapInitialSelected: (resource: TResource | null) => TSuggestion | null;
+    /** Persist a confirmed suggestion. Returned promises are awaited. */
+    onConfirmSelection: (selection: TSuggestion) => void | Promise<void>;
+    /** Disable confirmation for a pending candidate. */
+    isConfirmDisabled?: (selection: TSuggestion | null) => boolean;
+    /** Called once per closed-to-open cycle, including an initially open selector. */
+    onDialogOpen?: (selection: TSuggestion | null) => void;
+    /** Called after selection mode closes or confirmation succeeds. */
+    onDialogClose?: () => void;
+    /** Called when `onConfirmSelection` throws. Library DEV-logs the error;
+     *  consumer wires telemetry. */
+    onError?: (error: unknown, selection: TSuggestion) => void;
+    /** Controlled selector visibility. An initial `true` value initializes selection. */
+    open?: boolean;
+    /** Initial selector visibility; `true` initializes selection after mount. */
+    defaultOpen?: boolean;
+    /** Controlled visibility callback and uncontrolled visibility observer. */
+    onOpenChange?: (open: boolean) => void;
+    /** Controlled pending suggestion; authoritative over mapping on every open. */
+    value?: TSuggestion | null;
+    /** Initial uncontrolled suggestion; authoritative over mapping on the first open. */
+    defaultValue?: TSuggestion | null;
+    /** Controlled selection callback and uncontrolled selection observer. */
+    onValueChange?: (selection: TSuggestion | null) => void;
+};
+export type UseSharedResourceCardResult<TResource, TSuggestion> = SharedResourceCardContext<TResource, TSuggestion>;
+export declare function useSharedResourceCard<TResource, TSuggestion>({ resource, mapInitialSelected, onConfirmSelection, isConfirmDisabled, onDialogOpen, onDialogClose, onError, open, defaultOpen, onOpenChange, value, defaultValue, onValueChange, }: UseSharedResourceCardOptions<TResource, TSuggestion>): UseSharedResourceCardResult<TResource, TSuggestion>;

package/dist/components/features/resource-assignment/index.d.ts

@@ -0,0 +1,6 @@
+export { SharedResourceCard } from './resource-assignment';
+export { useSharedResourceCard } from './hooks';
+export type { UseSharedResourceCardOptions, UseSharedResourceCardResult, } from './hooks';
+export { DefaultDialogSummary, DefaultResourceContent, DefaultEmptyContent, DefaultDialogContent, } from './partials';
+export type { SharedResourceCardProps, SharedResourceCardContext, SharedResourceCardContentProps, SharedResourceCardSectionProps, SharedResourceCardSection, SharedResourceCardDialogContentProps, SharedResourceCardDialogSummaryProps, SharedResourceCardSelectorConfig, SharedResourceSelectorComponentProps, } from './resource-assignment.types';
+export { defaultSharedResourceCardStrings, type SharedResourceCardStrings, } from './resource-assignment.strings';

package/dist/components/features/resource-assignment/partials/default-shared-resource-partials.d.ts

@@ -0,0 +1,31 @@
+import { type StringsProp } from '../../../../lib/strings';
+import type { ReactNode } from 'react';
+import { type SharedResourceCardStrings } from '../resource-assignment.strings';
+import type { SharedResourceCardContentProps, SharedResourceCardDialogContentProps, SharedResourceCardDialogSummaryProps } from '../resource-assignment.types';
+type DefaultStrings = StringsProp<SharedResourceCardStrings>;
+export declare function DefaultDialogSummary<TResource, TSuggestion>({ context, strings, getSelectionLabel, }: SharedResourceCardDialogSummaryProps<TResource, TSuggestion> & {
+    /** Overrides this surface's own copy. */
+    strings?: DefaultStrings;
+    /** Builds the summary shown for the current selection. */
+    getSelectionLabel?: (selection: TSuggestion) => ReactNode;
+}): import("react").JSX.Element | null;
+export declare namespace DefaultDialogSummary {
+    var displayName: string;
+}
+export declare function DefaultResourceContent<TResource, TSuggestion>({ context: _context, strings, }: SharedResourceCardContentProps<TResource, TSuggestion> & {
+    strings?: DefaultStrings;
+}): import("react").JSX.Element;
+export declare namespace DefaultResourceContent {
+    var displayName: string;
+}
+export declare function DefaultEmptyContent<TResource, TSuggestion>({ context, strings, }: SharedResourceCardContentProps<TResource, TSuggestion> & {
+    strings?: DefaultStrings;
+}): import("react").JSX.Element;
+export declare namespace DefaultEmptyContent {
+    var displayName: string;
+}
+export declare function DefaultDialogContent<TResource, TSuggestion, TSelectorProps extends object = Record<never, never>>({ SelectorComponent, selectorProps, context, }: SharedResourceCardDialogContentProps<TResource, TSuggestion, TSelectorProps>): import("react").JSX.Element;
+export declare namespace DefaultDialogContent {
+    var displayName: string;
+}
+export {};

package/dist/components/features/resource-assignment/partials/index.d.ts

@@ -0,0 +1 @@
+export { DefaultDialogSummary, DefaultResourceContent, DefaultEmptyContent, DefaultDialogContent, } from './default-shared-resource-partials';

package/dist/components/features/resource-assignment/resource-assignment.d.ts

@@ -0,0 +1,12 @@
+import { type SharedResourceCardProps } from './resource-assignment.types';
+/**
+ * Stateful, card-free relationship assignment workflow.
+ *
+ * Consumers own persisted resources, selector data, mutations, routing, and
+ * translations. The feature owns pending selection, confirmation state,
+ * failure handling, and the default assignment presentation.
+ */
+export declare function SharedResourceCard<TResource, TSuggestion, TSelectorProps extends object = Record<never, never>>({ icon, title, description, className, contentClassName, alert, alertTone, actions, headerAction, footerText, resource, selector, sections, sectionsClassName, viewAction, viewLink, ResourceContentComponent, EmptyContentComponent, renderResourceContent, renderEmptyContent, strings: stringsProp, }: SharedResourceCardProps<TResource, TSuggestion, TSelectorProps>): import("react").JSX.Element;
+export declare namespace SharedResourceCard {
+    var displayName: string;
+}

package/dist/components/features/resource-assignment/resource-assignment.strings.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default user-facing strings for the resource-assignment feature.
+ *
+ * Consumers wire backend i18n at the call site:
+ *
+ *   <SharedResourceCard
+ *     strings={{ noResourceSelected: t('resourceAssignment.empty') }}
+ *     …
+ *   />
+ */
+export interface SharedResourceCardStrings {
+    currentlySelected: string;
+    noResourceContent: string;
+    noResourceSelected: string;
+    changeAction: string;
+}
+export declare const defaultSharedResourceCardStrings: SharedResourceCardStrings;

package/dist/components/features/resource-assignment/resource-assignment.types.d.ts

@@ -0,0 +1,193 @@
+import type { OverlaySize } from '../overlays';
+import type { ComponentType, ReactNode } from 'react';
+import type { ActionMenuAction } from '../../base/action-menu';
+import type { AlertTone } from '../../base/feedback';
+import type { StringsProp } from '../../../lib/strings';
+import type { SharedResourceCardStrings } from './resource-assignment.strings';
+export type SharedResourceSelectorComponentProps<TSuggestion, TSelectorProps extends object = Record<never, never>> = {
+    /** Select the pending resource shown in the assignment dialog. */
+    onSelect: (resource: TSuggestion | null) => void;
+    /** Current pending selection. This is not persisted until confirmation. */
+    selected: TSuggestion | null;
+    /** Whether the selector is rendered inside modal chrome. */
+    inModal: boolean;
+    /** Consumer hint for selectors that optionally lock after a choice. */
+    lockOnSelect?: boolean;
+    /** Overlay context available to selector implementations. */
+    context?: 'dialog' | 'drawer';
+} & TSelectorProps;
+/** State and actions shared by the default assignment UI and headless consumers. */
+export type SharedResourceCardContext<TResource, TSuggestion> = {
+    /** Persisted resource supplied by the consumer. */
+    resource: TResource | null;
+    /** Derived from `resource !== null`; never controlled independently. */
+    hasResource: boolean;
+    /** Whether the assignment selector is open. */
+    isSelectorOpen: boolean;
+    /** Whether async confirmation is pending. */
+    isConfirming: boolean;
+    /** Candidate selection that has not yet been persisted. */
+    selectedSuggestion: TSuggestion | null;
+    /** Update the pending candidate selection. */
+    setSelectedSuggestion: (resource: TSuggestion | null) => void;
+    /** Initialize the pending selection from `resource` and open the selector. */
+    openSelector: () => void;
+    /** Close the selector and discard its pending selection. */
+    closeSelector: () => void;
+    /** Persist the pending selection through the consumer callback. */
+    confirmSelection: () => Promise<void>;
+    /** Whether the current candidate can be confirmed. */
+    canConfirmSelection: boolean;
+};
+/** Props passed to custom selected and empty content components. */
+export type SharedResourceCardContentProps<TResource, TSuggestion> = {
+    context: SharedResourceCardContext<TResource, TSuggestion>;
+};
+/** Props passed to a custom resource section component. */
+export type SharedResourceCardSectionProps<TResource, TSuggestion> = {
+    context: SharedResourceCardContext<TResource, TSuggestion>;
+};
+/** Declarative section rendered for an assigned resource. */
+export type SharedResourceCardSection<TResource, TSuggestion> = {
+    /** Stable section key. */
+    id: string;
+    /** Optional visibility predicate evaluated against assignment state. */
+    when?: (context: SharedResourceCardContext<TResource, TSuggestion>) => boolean;
+    /** Layout override for the section wrapper. */
+    className?: string;
+    /** Consumer-owned section implementation. */
+    Component: ComponentType<SharedResourceCardSectionProps<TResource, TSuggestion>>;
+};
+/** Props passed to a custom assignment-dialog body. */
+export type SharedResourceCardDialogContentProps<TResource, TSuggestion, TSelectorProps extends object = Record<never, never>> = {
+    /** Consumer-owned selector implementation. */
+    SelectorComponent: ComponentType<SharedResourceSelectorComponentProps<TSuggestion, TSelectorProps>>;
+    /** Extra props forwarded to `SelectorComponent`. */
+    selectorProps?: TSelectorProps;
+    /** Current assignment and pending-selection state. */
+    context: SharedResourceCardContext<TResource, TSuggestion>;
+};
+/** Props passed to a custom pending-selection summary. */
+export type SharedResourceCardDialogSummaryProps<TResource, TSuggestion> = {
+    context: SharedResourceCardContext<TResource, TSuggestion>;
+};
+/** Consumer-owned picker and persistence contract for resource assignment. */
+export type SharedResourceCardSelectorConfig<TResource, TSuggestion, TSelectorProps extends object = Record<never, never>> = {
+    /** Assignment-dialog title. */
+    title: string;
+    /** Optional supporting copy below the title. */
+    description?: string;
+    /** Label for the async confirmation action. */
+    confirmText: string;
+    /** Label for the discard/close action. */
+    cancelText: string;
+    /**
+     * Label for changing an existing assignment. It renders as a direct
+     * header action when it is the only action, and joins the overflow menu
+     * when other actions are present.
+     */
+    actionLabel?: string;
+    /** Map persisted data when neither `value` nor first-open `defaultValue` supplies selection. */
+    mapInitialSelected: (resource: TResource | null) => TSuggestion | null;
+    /** Resolve the consumer-owned suggestion shape for the default dialog summary. */
+    getSelectionLabel?: (selection: TSuggestion) => ReactNode;
+    /** Persist the confirmed suggestion. The card awaits returned promises. */
+    onConfirmSelection: (selection: TSuggestion) => void | Promise<void>;
+    /** Consumer-owned picker rendered inside the default dialog content. */
+    SelectorComponent: ComponentType<SharedResourceSelectorComponentProps<TSuggestion, TSelectorProps>>;
+    /** Extra domain props forwarded to `SelectorComponent`. */
+    selectorProps?: TSelectorProps;
+    /** Replace the default selector-dialog body. */
+    DialogContentComponent?: ComponentType<SharedResourceCardDialogContentProps<TResource, TSuggestion, TSelectorProps> & Record<string, unknown>>;
+    /** Extra props forwarded to `DialogContentComponent`. */
+    dialogContentProps?: Record<string, unknown>;
+    /** Replace the default pending-selection summary. */
+    DialogSummaryComponent?: ComponentType<SharedResourceCardDialogSummaryProps<TResource, TSuggestion>>;
+    /** Disable confirmation for a pending candidate. */
+    isConfirmDisabled?: (selection: TSuggestion | null) => boolean;
+    /** Called once per closed-to-open cycle, including an initially open selector. */
+    onDialogOpen?: (selection: TSuggestion | null) => void;
+    /** Called after the selector closes or confirmation succeeds. */
+    onDialogClose?: () => void;
+    /** Controlled selector visibility. An initial `true` value initializes selection. */
+    open?: boolean;
+    /** Initial selector visibility; `true` initializes selection after mount. */
+    defaultOpen?: boolean;
+    /** Controlled visibility callback and uncontrolled visibility observer. */
+    onOpenChange?: (open: boolean) => void;
+    /** Controlled in-dialog selection; authoritative over mapping on every open. */
+    value?: TSuggestion | null;
+    /** Initial uncontrolled selection; authoritative over mapping on the first open. */
+    defaultValue?: TSuggestion | null;
+    /** Controlled selection callback and uncontrolled selection observer. */
+    onValueChange?: (selection: TSuggestion | null) => void;
+    /** Called when `onConfirmSelection` rejects so consumers can wire telemetry/toasts. */
+    onError?: (error: unknown, selection: TSuggestion) => void;
+    /** Width preset for the assignment dialog. */
+    dialogSize?: OverlaySize;
+};
+/**
+ * Stateful relationship-assignment content.
+ *
+ * The consumer owns the persisted `resource`, selector data, mutations,
+ * navigation, and translations. The component owns assignment presentation,
+ * pending selection, confirmation state, and composition seams.
+ */
+export type SharedResourceCardProps<TResource, TSuggestion, TSelectorProps extends object = Record<never, never>> = {
+    /** Leading header media, usually an `IconBadge`. */
+    icon?: ReactNode;
+    /** Assignment relationship title, such as “Assigned venue”. */
+    title: ReactNode;
+    /** Supporting context for the relationship. */
+    description?: ReactNode;
+    /** Class applied to the outer content block. */
+    className?: string;
+    /** Class applied to the content region. */
+    contentClassName?: string;
+    /** Optional status or validation notice above the body. */
+    alert?: ReactNode | string;
+    /** Semantic treatment for `alert`. */
+    alertTone?: Extract<AlertTone, 'neutral' | 'destructive' | 'warning'>;
+    /**
+     * Additional overflow actions. When present, a configured selector change
+     * action joins this menu; otherwise that selector action remains visible.
+     */
+    actions?: ActionMenuAction[];
+    /** Custom node at the end of the header row. */
+    headerAction?: ReactNode;
+    /** Secondary footer content owned by the consumer. */
+    footerText?: ReactNode;
+    /** Persisted assignment. `null` is the only empty state. */
+    resource: TResource | null;
+    /** Optional picker and async persistence contract. */
+    selector?: SharedResourceCardSelectorConfig<TResource, TSuggestion, TSelectorProps>;
+    /** Declarative selected-resource sections used when no content renderer is supplied. */
+    sections?: SharedResourceCardSection<TResource, TSuggestion>[];
+    /** Layout override for the sections container. */
+    sectionsClassName?: string;
+    /**
+     * Router-neutral action slot shown only when a resource is assigned.
+     * Use this for a framework link or callback-driven action. It takes
+     * precedence over `viewLink`.
+     */
+    viewAction?: ReactNode;
+    /** Native-link convenience used when `viewAction` is not supplied. */
+    viewLink?: {
+        /** Native destination URL. */
+        href: string;
+        /** Action label. */
+        label: ReactNode;
+        /** Class applied to the separated action region. */
+        className?: string;
+    };
+    /** Component override for assigned-resource content. */
+    ResourceContentComponent?: ComponentType<SharedResourceCardContentProps<TResource, TSuggestion>>;
+    /** Component override for unassigned content. */
+    EmptyContentComponent?: ComponentType<SharedResourceCardContentProps<TResource, TSuggestion>>;
+    /** Render-prop override for assigned-resource content. */
+    renderResourceContent?: (context: SharedResourceCardContext<TResource, TSuggestion>) => ReactNode;
+    /** Render-prop override for unassigned content. */
+    renderEmptyContent?: (context: SharedResourceCardContext<TResource, TSuggestion>) => ReactNode;
+    /** Deep-partial copy overrides. */
+    strings?: StringsProp<SharedResourceCardStrings>;
+};

package/dist/components/features/rich-text-editor/form-rich-text-editor.d.ts

@@ -0,0 +1,6 @@
+import { type RichTextEditorProps } from './rich-text-editor';
+export interface FormRichTextEditorProps extends Omit<RichTextEditorProps, 'value' | 'onValueChange'> {
+    /** Form field name, forwarded for native submits. */
+    name: string;
+}
+export declare function FormRichTextEditor({ name, ...props }: FormRichTextEditorProps): import("react").JSX.Element;

package/dist/components/features/rich-text-editor/index.d.ts

@@ -0,0 +1,5 @@
+export { RichTextEditor } from './rich-text-editor';
+export { FormRichTextEditor, type FormRichTextEditorProps } from './form-rich-text-editor';
+export type { RichTextEditorProps, RichTextEditorHandle, RichTextEditorToolbarItem, RichTextCaretContext, ToolbarButtonConfig, } from './rich-text-editor.types';
+export { defaultRichTextEditorStrings, type RichTextEditorStrings, } from './rich-text-editor.strings';
+export { RichTextEditorToolbar, type RichTextEditorToolbarProps, CountsFooterText, type CountsFooterTextProps, } from './partials';