themelia-ui 2.0.0 → 3.0.0

package/dist/components/features/products/product-variants.d.ts

@@ -1,4 +1,8 @@
 import { ProductVariantActionMenuProps, ProductVariantsBulkTableProps, ProductVariantsManagerProps, ProductVariantsTableProps } from './products.types.js';
+/**
+ * A variant's verbs, built from one array so the overflow cannot offer what the button already
+ * does. A separate menu from an option's or a row's, because each answers to a different set.
+ */
 export declare function ProductVariantActionMenu({ variant, index, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, menuLabel, className, strings, }: ProductVariantActionMenuProps): import("react").JSX.Element | null;
 export declare function ProductVariantsTable({ variants, onCreateVariant, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, actions, footerSlot, empty, className, strings, }: ProductVariantsTableProps): import("react").JSX.Element;
 export declare function ProductVariantsBulkTable({ variants, optionGroups, groupByOptionId, visibleColumns, optionCombinationDisplay, cellDisplay, selectionMode, renderOptionCombination, selectedVariantIds, defaultSelectedVariantIds, onSelectedVariantIdsChange, onVariantFieldChange, onVariantFieldBlur, onCreateVariant, onGenerateVariants, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onSetVariantImage, onBulkEdit, onBulkDelete, renderVariantActions, renderBulkActions, actions, headerEnd, footerSlot, empty, surface, className, strings, }: ProductVariantsBulkTableProps): import("react").JSX.Element;

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

@@ -6,13 +6,22 @@ import { SemanticTone } from '../../../lib/component-vocabulary.js';
 import type * as Strings from "./products.strings.js";
 /** No `secondary`: it means "not this one" rather than a state a product can be in. */
 export type ProductTone = Exclude<SemanticTone, "secondary">;
-/** `card` frames the surface; `embedded` renders it bare inside one that already exists. */
+/**
+ * How ProductOptionsMatrix and ProductVariantsBulkTable draw their frame: `card` frames the
+ * surface; `embedded` renders it bare inside one that already exists.
+ */
 export type ProductSurface = "card" | "embedded";
 export interface ProductReadinessItem {
     id: string;
     label: ReactNode;
     description?: ReactNode;
     value?: ReactNode;
+    /**
+     * The row's state colour: `neutral`, `primary`, `success`, `warning`, `destructive` or
+     * `info`. No `secondary`: it means “not this one”, which is not a state a product can be in.
+     * An item that is `completed` with no tone derives success, so ticking a box does not also
+     * mean remembering the colour.
+     */
     tone?: ProductTone;
     completed?: boolean;
     actionLabel?: ReactNode;
@@ -26,7 +35,10 @@ export interface ProductRowActionContext {
 }
 export interface ProductReadinessCardProps {
     items?: ProductReadinessItem[];
-    /** 0–100, clamped. */
+    /**
+     * 0–100, clamped — a percentage bar cannot show 140, and a NaN would render as an empty
+     * track.
+     */
     score?: number;
     scoreLabel?: ReactNode;
     summary?: ReactNode;
@@ -37,6 +49,10 @@ export interface ProductReadinessCardProps {
     renderReadinessItemActions?: (item: ProductReadinessItem, context: ProductRowActionContext) => ReactNode;
     actions?: ActionDefinition[];
     footerSlot?: ReactNode;
+    /**
+     * Replaces a whole row. The rows are one component with three wrappers, so a consumer
+     * replacing one is replacing the same shape everywhere it appears.
+     */
     renderItem?: (item: ProductReadinessItem, index: number) => ReactNode;
     empty?: ReactNode;
     className?: string;
@@ -88,7 +104,10 @@ export interface ProductOperationsCardProps {
 }
 export interface ProductDetailsCardProps {
     title?: ReactNode;
-    /** `false` suppresses the default description rather than showing it empty. */
+    /**
+     * `false` suppresses the default description rather than rendering it empty — which is the
+     * difference between a card with no subtitle and a card with a blank line where one was.
+     */
     description?: ReactNode | false;
     metadata?: MetadataListItem[];
     media?: ReactNode;
@@ -117,6 +136,10 @@ export interface ProductPolicySummary {
 }
 export interface ProductContractOverviewProps {
     metrics?: ProductMetricSummary[];
+    /**
+     * The contract's facts. They go through MetadataList, so an email or an SKU is rendered by
+     * the kind that knows how; this module does not restate it.
+     */
     terms?: MetadataListItem[];
     rules?: ProductPolicySummary[];
     onOpenContract?: () => void;
@@ -200,12 +223,22 @@ export interface ProductOptionsMatrixProps {
     onCreateOption?: () => void;
     onEditOption?: (option: ProductOptionGroup) => void;
     onDeleteOption?: (option: ProductOptionGroup) => void;
-    /** Off when the app already confirms, so nobody is asked twice. */
+    /**
+     * Asks before removing an option. Removing an option removes every variant generated from it
+     * — which is not visible from the option's own row. Off when the app already confirms, so
+     * nobody is asked twice.
+     * @default true
+     */
     confirmDelete?: boolean;
     onAddValue?: (option: ProductOptionGroup) => void;
     onDeleteValue?: (option: ProductOptionGroup, value: ProductOptionValue) => void;
     onOptionNameChange?: (option: ProductOptionGroup, value: string) => void;
     onValueLabelChange?: (option: ProductOptionGroup, value: ProductOptionValue, label: string) => void;
+    /**
+     * The staged name and values, committed together. Cancel discards them; the draft is
+     * re-seeded from the option each time editing opens, so a cancelled edit cannot leak into the
+     * next one.
+     */
     onSaveEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
     onCancelEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
     onToggleUsedForVariants?: (option: ProductOptionGroup, used: boolean) => void;
@@ -300,17 +333,34 @@ export interface ProductVariantFieldChangeContext {
 export interface ProductVariantsBulkTableProps {
     variants?: ProductVariantRow[];
     optionGroups?: ProductOptionGroup[];
-    /** Groups rows under the values of this option. `null` leaves the list flat. */
+    /**
+     * Groups rows under that option's values, in the order the option declares them — not
+     * alphabetically, and not by whichever variant was created first. `null` leaves the list
+     * flat.
+     */
     groupByOptionId?: string | null;
     visibleColumns?: readonly ProductVariantsBulkTableColumn[];
     optionCombinationDisplay?: ProductVariantOptionCombinationDisplay;
+    /**
+     * `text` or `field`, for every editable field or per field, so a table can make price
+     * editable and leave stock read-only — which is what a price update run actually needs.
+     */
     cellDisplay?: ProductVariantCellDisplayConfig;
     selectionMode?: ProductVariantSelectionMode;
     renderOptionCombination?: (variant: ProductVariantRow, values: ReactNode[]) => ReactNode;
     selectedVariantIds?: string[];
     defaultSelectedVariantIds?: string[];
     onSelectedVariantIdsChange?: (variantIds: string[], variants: ProductVariantRow[]) => void;
+    /**
+     * Fires on every edit of an in-place field. Both this and `onVariantFieldBlur` exist, and the
+     * consumer picks: change alone makes every keystroke a state update; blur alone loses the
+     * value if the row is removed mid-edit.
+     */
     onVariantFieldChange?: (variant: ProductVariantRow, field: ProductVariantEditableField, value: string, context: ProductVariantFieldChangeContext) => void;
+    /**
+     * Fires when an in-place field loses focus. Blur alone loses the value if the row is removed
+     * mid-edit; pair it with `onVariantFieldChange` where that matters.
+     */
     onVariantFieldBlur?: (variant: ProductVariantRow, field: ProductVariantEditableField, value: string, context: ProductVariantFieldChangeContext) => void;
     onCreateVariant?: () => void;
     onGenerateVariants?: () => void;
@@ -321,6 +371,11 @@ export interface ProductVariantsBulkTableProps {
     onBulkEdit?: (variants: ProductVariantRow[]) => void;
     onBulkDelete?: (variants: ProductVariantRow[]) => void;
     renderVariantActions?: (variant: ProductVariantRow, context: ProductVariantActionContext) => ReactNode;
+    /**
+     * Replaces the default pair of bulk actions. The context carries the selected rows, the
+     * counts, and both `clearSelection` and `setSelectedIds`, so a custom bar can act and then
+     * deselect.
+     */
     renderBulkActions?: (context: ProductVariantBulkActionContext) => ReactNode;
     /** Makes the picture slot pressable. Without it the slot is inert. */
     onSetVariantImage?: (variant: ProductVariantRow) => void;
@@ -333,7 +388,11 @@ export interface ProductVariantsBulkTableProps {
     strings?: Partial<Strings.ProductVariantBulkTableStrings>;
 }
 export interface ProductVariantsManagerProps extends Pick<ProductOptionsMatrixProps, "optionGroups" | "editingOptionId" | "defaultEditingOptionId" | "onEditingOptionIdChange" | "onCreateOption" | "onEditOption" | "onDeleteOption" | "onAddValue" | "onDeleteValue" | "onOptionNameChange" | "onValueLabelChange" | "onSaveEditingOption" | "onCancelEditingOption" | "onToggleUsedForVariants" | "onReorderOptions" | "confirmDelete">, Pick<ProductVariantsBulkTableProps, "variants" | "visibleColumns" | "optionCombinationDisplay" | "cellDisplay" | "selectionMode" | "selectedVariantIds" | "defaultSelectedVariantIds" | "onSelectedVariantIdsChange" | "onVariantFieldChange" | "onVariantFieldBlur" | "onCreateVariant" | "onGenerateVariants" | "onSelectVariant" | "onEditVariant" | "onDuplicateVariant" | "onDeleteVariant" | "onBulkEdit" | "onBulkDelete" | "renderVariantActions" | "renderBulkActions"> {
-    /** Controlled grouping. Uncontrolled, the manager's own Select drives it. */
+    /**
+     * Controlled grouping: groups rows under that option's values, in the order the option
+     * declares them — not alphabetically, and not by whichever variant was created first. `null`
+     * leaves the list flat. Uncontrolled, the manager's own Select drives it.
+     */
     groupByOptionId?: string | null;
     defaultGroupByOptionId?: string | null;
     onGroupByOptionIdChange?: (optionId: string | null) => void;
@@ -341,7 +400,15 @@ export interface ProductVariantsManagerProps extends Pick<ProductOptionsMatrixPr
     showGroupBy?: boolean;
     className?: string;
     strings?: Partial<Strings.ProductVariantsManagerStrings>;
+    /**
+     * The option matrix's own copy. The two children keep their own copy objects: one merged bag
+     * would collide on title, description and the create labels, which both of them have.
+     */
     optionsStrings?: Partial<Strings.ProductOptionsMatrixStrings>;
+    /**
+     * The variant table's own copy, kept apart from `optionsStrings` because both children have a
+     * title, a description and create labels.
+     */
     variantsStrings?: Partial<Strings.ProductVariantBulkTableStrings>;
 }
 export interface ProductOptionActionContext extends ProductRowActionContext {
@@ -360,7 +427,10 @@ export interface ProductOptionActionMenuProps {
     strings?: Partial<Strings.ProductOptionActionMenuStrings>;
 }
 export interface ProductVariantDetailsProps {
-    /** Absent renders the empty state (this surface is often bound to a selection). */
+    /**
+     * Optional. Absent renders the empty state — this panel is usually bound to a selection, and
+     * “nothing chosen yet” is a thing to say, not a reason to unmount.
+     */
     variant?: ProductVariantSummary;
     /** Replaces the derived facts. The default is built from the variant's own fields. */
     metadata?: MetadataListItem[];
@@ -413,6 +483,10 @@ export interface ProductVariantOptionField {
 export interface ProductVariantEditorProps {
     value?: ProductVariantEditorValues;
     defaultValue?: ProductVariantEditorValues;
+    /**
+     * A select when the field carries choices, a text input when it does not — an app with a
+     * free-text status should not have to invent a list to use this.
+     */
     optionFields?: ProductVariantOptionField[];
     statusOptions?: ProductChoice[];
     onValueChange?: (value: ProductVariantEditorValues) => void;
@@ -425,7 +499,12 @@ export interface ProductVariantEditorProps {
     headerEnd?: ReactNode;
     footerSlot?: ReactNode;
     disabled?: boolean;
-    /** Shows the pending state and blocks a repeat submit. */
+    /**
+     * Shows the pending state and blocks a repeat submit. OR-ed with an internal flag: a
+     * consumer holding the request already knows it is in flight; one that just handed over an
+     * async `onSubmit` does not, and a form that stays live during a save takes the same submit
+     * twice.
+     */
     submitting?: boolean;
     className?: string;
     strings?: Partial<Strings.ProductVariantEditorStrings>;
@@ -451,7 +530,10 @@ export interface ProductQuotePreviewLine {
     value: ReactNode;
     description?: ReactNode;
     tone?: ProductTone;
-    /** Ruled off and emphasised: the line the rest add up to. */
+    /**
+     * Rules the line off and weights it: the line the rest add up to. Not a tint — a filled band
+     * on the last line makes a total look like an alert, which is the one thing a total is not.
+     */
     emphasis?: boolean;
 }
 export interface ProductQuotePreviewCardProps {

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

@@ -1,8 +1,22 @@
 import { ResourceActionBarProps, ResourceDetailsSectionProps, ResourceEmptyStateProps, ResourceHeaderProps, ResourceIndexShellProps, ResourceShowShellProps, TabbedResourceShellProps } from './resource.types.js';
+/**
+ * The title block of an index or show screen, for a page that wants the shell's rhythm without
+ * its whole frame.
+ */
 export declare function ResourceHeader({ title, description, eyebrow, media, avatarUrl, avatarAlt, avatarFallback, icon: Icon, iconTone, badges, metadata, actions, className, contentClassName, mediaClassName, }: ResourceHeaderProps): import("react").JSX.Element;
+/**
+ * The verb row of an index or show screen, for a page that wants the shell's rhythm without its
+ * whole frame.
+ */
 export declare function ResourceActionBar({ children, leading, trailing, sticky, className, }: ResourceActionBarProps): import("react").JSX.Element;
+/**
+ * One of the three states the shells swap in for content. Loading, error and empty are
+ * replacements rather than overlays — they take the space the content will take, so nothing
+ * reflows when it arrives.
+ */
 export declare function ResourceEmptyState({ className, ...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;
+/** A show screen with a tab row in its toolbar. */
 export declare function TabbedResourceShell({ tabs, activeTab, onTabChange, tabsClassName, toolbar, slots, className, strings, ...props }: TabbedResourceShellProps): import("react").JSX.Element;
 export declare function ResourceDetailsSection({ metadata, metadataColumns, metadataDense, body, help, children, footer, padding, surface, className, contentClassName, ...props }: ResourceDetailsSectionProps): import("react").JSX.Element;

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

@@ -25,26 +25,40 @@ export interface ResourceShellSlots {
 export interface ResourceIndexShellProps {
     /** The screen's own content. Replaced while loading, failed, or empty. */
     children?: ReactNode;
-    /** Generated header title. Omit when supplying `slots.header`. */
+    /**
+     * Generated header title. With `description` and `actions` it feeds the generated header;
+     * omit them and pass `slots.header` when the header is not a title and a description.
+     */
     title?: ReactNode;
+    /** Generated header description. */
     description?: ReactNode;
     /** Generated header actions. */
     actions?: ReactNode;
     /** Between the header and the body. */
     toolbar?: ReactNode;
     /**
-     * Replaces the body with the empty state. Explicit rather than inferred from `children`:
-     * only the screen knows "no records" from "no records matching".
+     * Replaces the body with the empty state. A boolean rather than an inference from
+     * `children`: a screen with a header row and no data still has children, and only the screen
+     * knows "no records" from "no records MATCHING".
      */
     empty?: boolean;
+    /** Replaces the body with the loading state. */
     loading?: boolean;
     /**
      * Anything truthy replaces the body. An `Error`, string or number becomes the generated error
      * state's description; any other node is rendered as the error state itself.
      */
     error?: ReactNode | Error;
-    /** Wiring this puts a retry control on the generated error state. */
+    /**
+     * Wiring this puts a retry control on the generated error state. Without it there is nothing
+     * to offer.
+     */
     onRetry?: () => void;
+    /**
+     * `header`, `toolbar`, `aside`, `footer`, `loading`, `empty`, `error`. Every one has a
+     * generated default; the slot is for the screen where configuring that default prop by prop
+     * is worse than replacing it.
+     */
     slots?: ResourceShellSlots;
     className?: string;
     headerClassName?: string;
@@ -59,8 +73,13 @@ export interface ResourceHeaderProps {
     description?: ReactNode;
     /** Quiet context above the title: the parent record, the section. */
     eyebrow?: ReactNode;
-    /** The media, in full. Takes precedence over `avatarUrl`, which takes precedence over `icon`. */
+    /**
+     * The media, in full. Ordered, not exclusive: it takes precedence over `avatarUrl`, which
+     * takes precedence over `icon`. A screen knows one of the three, and which one depends on
+     * what the record is — a person has an avatar, a settings section has an icon.
+     */
     media?: ReactNode;
+    /** An avatar image, used when there is no `media`. */
     avatarUrl?: string;
     avatarAlt?: string;
     /** Defaults to initials derived from a string title. */
@@ -85,7 +104,11 @@ export interface ResourceActionBarProps {
     /** Filters, a selection summary, the controls that act on the body. */
     leading?: ReactNode;
     trailing?: ReactNode;
-    /** Pins the bar below the shell header as the body scrolls, for selection counts and bulk actions. */
+    /**
+     * Pins the bar below the shell header, not the viewport top, as the body scrolls — for a bar
+     * carrying a selection count or bulk actions, which is needed exactly when a static bar has
+     * scrolled away.
+     */
     sticky?: boolean;
     className?: string;
 }
@@ -102,14 +125,18 @@ interface ResourceSectionFrameProps {
     children?: ReactNode;
     /** After the body. */
     footer?: ReactNode;
+    /** Inner spacing: `sm`, `md` or `lg`. */
     padding?: ResourceBlockPadding;
-    /** `plain` when this sits inside a frame that already has chrome. */
+    /** A ContentBlock surface. `plain` when this sits inside a frame that already has chrome. */
     surface?: ResourceBlockSurface;
     className?: string;
     contentClassName?: string;
 }
 export interface ResourceDetailsSectionProps extends ResourceSectionFrameProps {
-    /** Structured facts, before any free-form body content. */
+    /**
+     * Structured facts, before any free-form body content. `metadataColumns` is a ceiling; the
+     * list steps down at narrow widths on its own.
+     */
     metadata?: MetadataListItem[];
     /** A ceiling. The list steps down at narrow widths on its own. */
     metadataColumns?: 1 | 2 | 3 | 4;
@@ -120,6 +147,7 @@ export interface ResourceDetailsSectionProps extends ResourceSectionFrameProps {
     help?: ReactNode;
 }
 export interface TabbedResourceShellProps extends ResourceShowShellProps {
+    /** The tab row. It goes into the toolbar slot, so `slots.toolbar` still wins outright. */
     tabs: OverflowTabItem[];
     /** Controlled active tab. */
     activeTab?: string;

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

@@ -1,14 +1,24 @@
 import { ReactNode } from 'react';
 import { defaultSharedResourceCardStrings } from './resource-assignment.strings.js';
 import { SharedResourceCardContentProps, SharedResourceCardDialogContentProps, SharedResourceCardProps } from './resource-assignment.types.js';
-/** The dialog body when not replaced: just the picker. */
+/**
+ * The picker the assignment dialog shows when a consumer supplies none — the dialog body when
+ * not replaced. Exported so a custom dialog can keep it and add to it, rather than starting
+ * from nothing.
+ */
 export declare function DefaultDialogContent<TResource, TSuggestion, TSelectorProps extends object = Record<never, never>>({ SelectorComponent, selectorProps, context, }: SharedResourceCardDialogContentProps<TResource, TSuggestion, TSelectorProps>): import("react").JSX.Element;
 /**
- * Restates the pending choice above the confirm, since the chosen row may have scrolled
- * out of sight. Falls back to a `label` field; pass `getSelectionLabel` to be exact.
+ * What is about to be committed, restated above the confirm. A picker can scroll, and the
+ * chosen row is often out of sight by the time the reader reaches the button. Falls back to a
+ * `label` field; pass `getSelectionLabel` to be exact.
  */
 export declare function DefaultDialogSummary<TResource, TSuggestion>({ context, strings, getSelectionLabel, }: SharedResourceCardContentProps<TResource, TSuggestion> & {
     strings?: Partial<typeof defaultSharedResourceCardStrings>;
     getSelectionLabel?: (selection: TSuggestion) => ReactNode;
 }): import("react").JSX.Element | null;
+/**
+ * Shows the resource assigned to a record and how to change it. The card owns the shape —
+ * panel, dialog, pending choice, awaited confirm; the picker is the consumer's, since every
+ * assignment searches differently.
+ */
 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, }: SharedResourceCardProps<TResource, TSuggestion, TSelectorProps>): import("react").JSX.Element;

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

@@ -49,18 +49,34 @@ export interface SharedResourceCardSelectorConfig<TResource, TSuggestion, TSelec
     cancelText: string;
     /** Names the change action. Alone it is a header button; with other actions it joins the overflow menu. */
     actionLabel?: string;
-    /** Turns the persisted resource into a starting choice for the picker. */
+    /**
+     * Turns the persisted resource into a starting choice for the picker, so “Change” opens on
+     * what the record holds.
+     */
     mapInitialSelected: (resource: TResource | null) => TSuggestion | null;
-    /** How the pending choice reads in the summary. */
+    /**
+     * How the pending choice reads in the summary above the buttons. Without it the card looks
+     * for a string `label` field, which is a guess — a cheap and usually right one.
+     */
     getSelectionLabel?: (selection: TSuggestion) => ReactNode;
-    /** Persists it. The card awaits a returned promise and shows the confirming state. */
+    /**
+     * Persists it. A returned promise is awaited and drives the confirming state; a rejection
+     * keeps the dialog open and reaches `onError`.
+     */
     onConfirmSelection: (selection: TSuggestion) => void | Promise<void>;
+    /**
+     * The picker. Yours: it receives `selected`, `onSelect`, and `inModal` — a picker that adapts
+     * inside a dialog can read the last one.
+     */
     SelectorComponent: ComponentType<SharedResourceSelectorProps<TSuggestion, TSelectorProps>>;
     selectorProps?: TSelectorProps;
     DialogContentComponent?: ComponentType<SharedResourceCardDialogContentProps<TResource, TSuggestion, TSelectorProps> & Record<string, unknown>>;
     dialogContentProps?: Record<string, unknown>;
     DialogSummaryComponent?: ComponentType<SharedResourceCardContentProps<TResource, TSuggestion>>;
-    /** Refuses a pending choice: an inactive venue, a full room. */
+    /**
+     * Refuses a pending choice — an inactive venue, a room that is full or too small. The confirm
+     * stays disabled rather than failing after the press.
+     */
     isConfirmDisabled?: (selection: TSuggestion | null) => boolean;
     /** Fires once per closed-to-open cycle, with the choice the dialog opened on. */
     onDialogOpen?: (selection: TSuggestion | null) => void;
@@ -84,14 +100,27 @@ export interface SharedResourceCardProps<TResource, TSuggestion, TSelectorProps
     contentClassName?: string;
     alert?: ReactNode;
     alertTone?: Extract<AlertTone, "neutral" | "destructive" | "warning">;
-    /** Extra overflow actions. The change action joins them when they exist. */
+    /**
+     * Extra overflow actions. Alone, the change action is a header button; alongside these it
+     * joins them — two triggers side by side is worse than one menu holding both.
+     */
     actions?: ActionDefinition[];
     headerAction?: ReactNode;
     footerText?: ReactNode;
-    /** The persisted assignment. `null` is the only empty state. */
+    /**
+     * The persisted assignment. `null` is the only empty state; `hasResource` is derived from it
+     * and never independently controlled.
+     */
     resource: TResource | null;
+    /**
+     * The picker, its copy, and the write. Omit it and the card is read-only — no change action,
+     * and an empty state that offers nothing.
+     */
     selector?: SharedResourceCardSelectorConfig<TResource, TSuggestion, TSelectorProps>;
-    /** Declarative body blocks, used when no content override is given. */
+    /**
+     * Declarative body blocks, used when no content override is given: the last rung of the
+     * assigned body's ladder, after `renderResourceContent` and `ResourceContentComponent`.
+     */
     sections?: SharedResourceCardSection<TResource, TSuggestion>[];
     sectionsClassName?: string;
     /**
@@ -99,14 +128,26 @@ export interface SharedResourceCardProps<TResource, TSuggestion, TSelectorProps
      * Takes precedence over `viewLink`.
      */
     viewAction?: ReactNode;
-    /** The native-anchor convenience, for an app with no router in the way. */
+    /**
+     * The native-anchor convenience, for an app with no router in the way. Like `viewAction`, it
+     * renders only when a resource is assigned.
+     */
     viewLink?: {
         href: string;
         label: ReactNode;
         className?: string;
     };
+    /**
+     * The assigned body as a component: the second rung of the ladder, after
+     * `renderResourceContent` and before `sections`. A component is reusable.
+     */
     ResourceContentComponent?: ComponentType<SharedResourceCardContentProps<TResource, TSuggestion>>;
     EmptyContentComponent?: ComponentType<SharedResourceCardContentProps<TResource, TSuggestion>>;
+    /**
+     * The assigned body, most specific first: this, then `ResourceContentComponent`, then
+     * `sections`. A render prop closes over local state, a component is reusable, and sections
+     * are data — each rung exists because the one below it is wrong for someone.
+     */
     renderResourceContent?: (context: SharedResourceCardContext<TResource, TSuggestion>) => ReactNode;
     renderEmptyContent?: (context: SharedResourceCardContext<TResource, TSuggestion>) => ReactNode;
     strings?: Partial<SharedResourceCardStrings>;

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

@@ -15,4 +15,8 @@ export interface UseSharedResourceCardOptions<TResource, TSuggestion> {
     onValueChange?: (selection: TSuggestion | null) => void;
 }
 export type UseSharedResourceCardResult<TResource, TSuggestion> = SharedResourceCardContext<TResource, TSuggestion>;
+/**
+ * The state machine without the card: open state, pending choice, `canConfirmSelection`, and a
+ * confirm that awaits.
+ */
 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/rich-text-editor/rich-text-editor-toolbar.d.ts

@@ -12,6 +12,10 @@ export interface RichTextEditorToolbarProps {
     strings: RichTextEditorStrings;
     className?: string;
 }
+/**
+ * The formatting row, exported so an editor can be mounted with the toolbar somewhere else — a
+ * sticky bar above a long document, or a shared bar over two editors.
+ */
 export declare function RichTextEditorToolbar({ buttons, extraToolbarItems, hideSourceToggle, sourceMode, toggleSourceMode, disabled, toolbarTrailing, strings, className, }: RichTextEditorToolbarProps): import("react").JSX.Element;
 export interface EditorCountsProps {
     /** The document as plain text. */
@@ -21,7 +25,8 @@ export interface EditorCountsProps {
     className?: string;
 }
 /**
- * Character and word counts. Over the limit the count turns error-toned; input is never
- * refused, so the form decides.
+ * The word and character counts under the editor. Over the limit the count turns error-toned;
+ * input is never refused, so the form decides. Separate because a limit is often shown beside a
+ * submit button rather than under the field it applies to.
  */
 export declare function EditorCounts({ text, maxLength, strings, className }: EditorCountsProps): import("react").JSX.Element;

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

@@ -1,5 +1,14 @@
 import { Ref } from 'react';
 import { RichTextEditorHandle, RichTextEditorProps } from './rich-text-editor.types.js';
+/**
+ * An editing surface with a toolbar and an imperative handle. Content is controlled through
+ * `value` and `onValueChange`; the handle covers what a prop cannot.
+ */
 export declare function RichTextEditor({ engine, value, onValueChange, placeholder, compact, minHeight, maxHeight, disabled, showCounts, maxLength, extraToolbarItems, toolbarTrailing, footerSlot, hideSourceToggle, autoFocus, className, onCaretChange, strings, ref, }: RichTextEditorProps & {
+    /**
+     * The imperative handle: `focus`, `getHTML`, `setHTML`, `insertHTML`, `isEmpty`, `clear`,
+     * `getCaretContext`, `replaceBeforeCaret`. A superset of MentionEditorHandle, so the two
+     * plug together with no adapter.
+     */
     ref?: Ref<RichTextEditorHandle>;
 }): import("react").JSX.Element;

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

@@ -12,6 +12,11 @@ export interface RichTextCaretContext {
         right: number;
     };
 }
+/**
+ * The editor's imperative handle, for what a prop cannot do: caret context, and replacing text
+ * before the caret. A superset of MentionEditorHandle, so the two plug together with no
+ * adapter.
+ */
 export interface RichTextEditorHandle {
     focus(): void;
     getHTML(): string;
@@ -22,8 +27,9 @@ export interface RichTextEditorHandle {
     clear(): void;
     getCaretContext(): RichTextCaretContext | null;
     /**
-     * Deletes the `length` characters before the caret and inserts `html` in their place,
-     * as one operation (one undo entry, no intermediate caret state).
+     * Deletes the `length` characters before the caret and inserts `html` in their place, as
+     * one operation, not a delete then an insert: the caret never visits an in-between state,
+     * and undo gets one entry for what the writer experienced as one act.
      */
     replaceBeforeCaret(length: number, html: string): void;
 }
@@ -51,36 +57,69 @@ export interface ToolbarButtonConfig {
 }
 export interface RichTextEditorProps {
     /**
-     * What edits the document. Defaults to TipTap with StarterKit and inline mentions; the
-     * chrome (toolbar, source view, counts, footer, strings) is engine-independent. Install
-     * the family's documented TipTap peers when importing the editor.
+     * What edits the document. Defaults to TipTap with StarterKit and inline, atomic mentions;
+     * supply a RichTextEngine for a custom schema or implementation, and the caller owns its
+     * destruction. The chrome (toolbar, source view, counts, footer, strings) is
+     * engine-independent. Install the family's documented TipTap peers when importing the
+     * editor.
+     * @default TipTap
      */
     engine?: RichTextEngine;
-    /** The document, as HTML. Controlled. */
+    /**
+     * The document, as HTML. Controlled: parent echoes preserve the selection, and actual
+     * external changes update the document, including while it is focused. Output is normalized
+     * to the active engine's schema.
+     */
     value: string;
+    /** Receives the document, as HTML, after every edit. */
     onValueChange: (html: string) => void;
-    /** Drawn over the empty document. */
+    /**
+     * Drawn over the first line of the empty document, because a contenteditable has no
+     * placeholder attribute. Sitting over it rather than replacing the document means the caret
+     * is already in the right place.
+     */
     placeholder?: string;
-    /** Tightens the toolbar and shortens the body, for a composer rather than a page. */
+    /**
+     * Tightens the toolbar and shortens the body, for a composer rather than a page: a line and a
+     * half instead of a page — enough to look like it takes more than a word, without claiming a
+     * screen for a one-sentence reply.
+     */
     compact?: boolean;
     minHeight?: string;
     /** Where the body starts scrolling instead of growing. */
     maxHeight?: string;
     disabled?: boolean;
+    /** Shows the word and character counts under the body. */
     showCounts?: boolean;
-    /** Shown as "n / max". Does not truncate: the count reports, the form decides. */
+    /**
+     * Shown as "n / max". Over the limit the count turns error-toned; input is NOT refused — a
+     * composer that stops accepting characters mid-word loses what the writer was in the middle
+     * of. The count reports, the form decides.
+     */
     maxLength?: number;
+    /**
+     * Appended after the built-ins, behind a rule. Each takes an icon, a label used for both the
+     * accessible name and the tooltip, and an optional `isActive`.
+     */
     extraToolbarItems?: ReadonlyArray<RichTextEditorToolbarItem>;
-    /** Pinned to the end of the toolbar, usually the submit control. */
+    /**
+     * Pinned to the end of the toolbar, usually the submit control. Inside the frame, like
+     * `footerSlot`, so the composer reads as one control.
+     */
     toolbarTrailing?: ReactNode;
-    /** Below the body: attachment chips, a hint. */
+    /**
+     * Below the body: attachment chips, a hint. Inside the frame, like `toolbarTrailing`, so the
+     * composer reads as one control.
+     */
     footerSlot?: ReactNode;
     hideSourceToggle?: boolean;
     autoFocus?: boolean;
     className?: string;
     /**
-     * Fires after every input and every selection change (the caret can move without the
-     * document changing); read `getCaretContext()` from the handle in response.
+     * Fires after every input AND every selection change; read `getCaretContext()` from the
+     * handle in response. Two events, because a caret moves without the document changing — and
+     * a trigger detector watching only input misses the writer moving back into a half-typed
+     * mention.
      */
     onCaretChange?: () => void;
     strings?: Partial<RichTextEditorStrings>;

package/dist/components/features/schema-form/schema-form-actions.d.ts

@@ -10,4 +10,9 @@ export interface SchemaFormActionsProps {
     onReset?: () => void;
     className?: string;
 }
+/**
+ * The form's submit row, generated from the same schema; reset renders only when there is an
+ * `onReset` for it to reach. Exported so a screen can place it somewhere the generated layout
+ * does not — a drawer footer, a sticky bar.
+ */
 export declare function SchemaFormActions({ submitLabel, resetLabel, showReset, disabled, submitDisabled, resetDisabled, submitting, onReset, className, }: SchemaFormActionsProps): import("react").JSX.Element;