@servicetitan/anvil2 3.15.0 → 3.15.2

package/dist/src/beta/components/Table/types.d.ts

@@ -7,13 +7,11 @@ import { MultiSelectMenuOption } from '../../../components/MultiSelectMenu';
 import { MultiSelectMenuSyncProps } from '../../../components/MultiSelectMenu/MultiSelectMenuSync';
 import { MultiSelectMenuProps } from '../../../components/MultiSelectMenu/types';
 /**
- * Column type literals for display configuration.
- * Each type maps to a default formatter and alignment.
+ * Built-in display treatments. Each maps to default formatting and alignment.
  */
 export type ColumnType = "text" | "number" | "currency" | "percent" | "date" | "dateTime" | "time" | "boolean" | "markdown" | "html";
 /**
- * Maps column types to their formatter options.
- * Used for type-safe formatter configuration.
+ * Formatter options accepted by each built-in column type.
  */
 export type ColumnTypeOptionsMap = {
     text: undefined;
@@ -28,15 +26,12 @@ export type ColumnTypeOptionsMap = {
     html: undefined;
 };
 /**
- * Column type configuration.
- * Can be a simple type string (uses defaults) or an object with custom options.
+ * Built-in type shorthand, or an object that customizes its formatter.
  *
  * @example
  * ```ts
- * // Simple - uses default formatter options
  * type: "currency"
  *
- * // With options - customizes formatter behavior
  * type: { type: "currency", options: { currency: "EUR", locale: "de-DE" } }
  * ```
  */
@@ -44,21 +39,10 @@ export type ColumnTypeConfig<T extends ColumnType = ColumnType> = T | {
     type: T;
     options: ColumnTypeOptionsMap[T];
 };
-/**
- * Edit mode literals for editable cells.
- */
+/** Supported `editConfig` discriminants. */
 export type EditMode = "text" | "number" | "select" | "select-async" | "multiselect" | "multiselect-async" | "boolean" | "custom";
-/**
- * Base edit configuration shared by all edit modes.
- * @template T - The row data type
- * @template K - The column key
- */
 type BaseEditConfig<T, K extends keyof T> = {
-    /**
-     * Callback fired when the cell value is saved.
-     * @param value - The new value
-     * @param rowId - The id of the row being edited
-     */
+    /** Persists the committed value for the identified row. */
     onChange: (value: T[K], rowId: string) => void;
 };
 type CustomEditInvalidPresentValue<TValue> = Extract<NonNullable<TValue>, readonly unknown[]> | Extract<NonNullable<TValue>, (...args: never[]) => unknown> | Exclude<NonNullable<TValue>, object>;
@@ -66,91 +50,75 @@ type CustomEditPresentObjectValueForValue<TValue> = [
     CustomEditInvalidPresentValue<TValue>
 ] extends [never] ? NonNullable<TValue> extends object ? NonNullable<TValue> : never : never;
 type CustomEditPartialPresentValue<TValue extends object> = TValue extends object ? Partial<TValue> : never;
+/** Nullish members explicitly allowed by a custom-edit value type. */
 export type CustomEditAllowedNullishValue<TValue> = Extract<TValue, null | undefined>;
+/**
+ * The non-null object accepted by custom edit mode, or `never` when the value
+ * also permits arrays, functions, or non-object members.
+ */
 export type CustomEditPresentObjectValue<T, K extends keyof T> = CustomEditPresentObjectValueForValue<T[K]>;
+/** A partial custom-edit object plus nullish members declared by the value type. */
 export type CustomEditDraftValueForValue<TValue> = [
     CustomEditPresentObjectValueForValue<TValue>
 ] extends [never] ? never : CustomEditPartialPresentValue<CustomEditPresentObjectValueForValue<TValue>> | CustomEditAllowedNullishValue<TValue>;
+/** Draft shape for a custom-edit column. */
 export type CustomEditDraftValue<T, K extends keyof T> = CustomEditDraftValueForValue<T[K]>;
+/** Committed row value captured when custom editing begins. */
 export type CustomEditInitialValue<T, K extends keyof T> = T[K];
+/** Direct field value or updater receiving the current field and full draft. */
 export type CustomEditFieldValueUpdater<TValue extends object, TField extends keyof TValue> = TValue[TField] | ((previousValue: TValue[TField] | undefined, draftValue: Partial<TValue>) => TValue[TField]);
+/** Events and commands that can request custom-editor closure. */
 export type CustomEditCloseReason = "submit" | "escape" | "outside-click" | "close-button" | "programmatic";
+/** Form- and field-level messages for a custom-editor draft. */
 export type CustomEditValidation<TValue extends object> = {
-    /**
-     * Form-level validation summary for the entire editor.
-     */
+    /** Editor-wide message shown independently of individual fields. */
     formError?: ReactNode;
-    /**
-     * Field-level validation messages keyed by draft field.
-     */
+    /** Messages keyed by draft field. */
     fieldErrors?: Partial<Record<keyof TValue, ReactNode>>;
 };
+/** Presentation and keyboard overrides for the custom-editor Surface. */
 export type CustomEditSurfaceConfig = {
-    /**
-     * Optional title rendered in the editor surface header.
-     */
+    /** Header content; omitting it removes the header title. */
     title?: ReactNode;
-    /**
-     * Optional surface width.
-     */
+    /** CSS width of the editor Surface. */
     width?: number | string;
-    /**
-     * Optional surface max height.
-     */
+    /** CSS max-height of the editor Surface. */
     maxHeight?: number | string;
-    /**
-     * Accessible label for the close button.
-     */
+    /** Accessible name for the header close button. */
     closeButtonLabel?: string;
-    /**
-     * Optional keydown handler forwarded to the surface.
-     */
+    /** Runs before built-in key handling; prevent default to skip that handling. */
     onKeyDown?: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
 };
+/** Draft state supplied when custom-editor closure is requested. */
 export type CustomEditCloseRequest<TValue extends object, TDraftValue = Partial<TValue>, TInitialValue = TValue> = {
-    /**
-     * Why the close was requested.
-     */
+    /** Trigger that initiated this request. */
     reason: CustomEditCloseReason;
-    /**
-     * Draft value at the time the request is evaluated.
-     */
+    /** Draft snapshot evaluated by the close policy. */
     draftValue: TDraftValue;
-    /**
-     * Original committed value when editing began.
-     */
+    /** Committed value captured when editing began. */
     initialValue: TInitialValue;
-    /**
-     * Whether the draft differs from the initial value.
-     */
+    /** Whether draft and initial values differ. */
     isDirty: boolean;
-    /**
-     * Current validation metadata.
-     */
+    /** Validation snapshot evaluated by the close policy. */
     validation: CustomEditValidation<TValue>;
 };
+/** Draft, validation, focus, and lifecycle controls for a custom editor. */
 export type CustomEditController<TValue extends object, TDraftValue = Partial<TValue>, TInitialValue = TValue> = {
     /**
      * Current local draft. Custom editors may hold a partial object, or a
      * row-type-supported nullish value.
      */
     draftValue: TDraftValue;
-    /**
-     * Original value before editing began.
-     */
+    /** Committed value captured when editing began. */
     initialValue: TInitialValue;
-    /**
-     * Whether the draft differs from the initial value.
-     */
+    /** Whether draft and initial values differ. */
     isDirty: boolean;
     /**
      * Ordered list of changed object fields. Whole-value nullish changes are
      * represented by `isDirty`, not by synthetic field names.
      */
     changedFields: ReadonlyArray<keyof TValue>;
-    /**
-     * Current validation metadata for the draft.
-     */
+    /** Validation metadata for the current draft. */
     validation: CustomEditValidation<TValue>;
     /**
      * Replace the entire draft value. Null and undefined are accepted only when
@@ -162,33 +130,29 @@ export type CustomEditController<TValue extends object, TDraftValue = Partial<TV
      * nullish, a partial object containing this field is synthesized.
      */
     setDraftField: <TField extends keyof TValue>(field: TField, nextValue: CustomEditFieldValueUpdater<TValue, TField>) => TDraftValue;
-    /**
-     * Submit the current draft and close the editor.
-     */
+    /** Commits the current draft and closes when policy allows. */
     submit: () => void;
-    /**
-     * Restore the initial value and close the editor.
-     */
+    /** Restores the initial value and closes without committing. */
     discard: () => void;
     /**
      * Request closure using the configured policy for the supplied reason.
      */
     requestClose: (reason: CustomEditCloseReason) => void;
-    /**
-     * Register the one preferred initial-focus action for the editor.
-     */
+    /** Registers the editor's one preferred initial-focus action. */
     setInitialFocus: (focus: (() => void) | null) => void;
-    /**
-     * Canonical submit handler for form-based editors.
-     */
+    /** Prevents native submission, then delegates to {@link submit}. */
     handleSubmit: (event?: {
         preventDefault?: () => void;
     }) => void;
 };
+/** Row data available to read-path renderers and text extractors. */
 export type ColumnReadRenderContext<T> = {
+    /** Full row for cross-field read rendering. */
     row: T;
+    /** Zero-based nesting depth. */
     depth: number;
 };
+/** Rich read content paired with optional sortable text. */
 export type ColumnReadRenderResult = {
     /**
      * Advanced read-path rendered content.
@@ -196,19 +160,14 @@ export type ColumnReadRenderResult = {
      * this shape when one hook should return both rendered content and sortable text.
      */
     content: ReactNode;
-    /**
-     * Optional sortable plain-text representation of the rendered content.
-     */
+    /** Sortable plain text for the rendered content. */
     rawString?: string;
 };
+/** Row and controller state supplied to a custom editor renderer. */
 export type CustomEditRenderContext<T, K extends keyof T> = {
-    /**
-     * Full row data for the cell being edited.
-     */
+    /** Full row for cross-field editor behavior. */
     row: T;
-    /**
-     * String row id for the cell being edited.
-     */
+    /** String-normalized id of the edited row. */
     rowId: string;
     /**
      * Committed value for the cell, exactly as declared by the row type.
@@ -220,47 +179,31 @@ export type CustomEditRenderContext<T, K extends keyof T> = {
     controller: CustomEditController<CustomEditPresentObjectValue<T, K>, CustomEditDraftValue<T, K>, CustomEditInitialValue<T, K>>;
 };
 /**
- * Edit configuration for custom mode cells.
- * Custom mode is for structured object-valued columns. The committed read
- * value remains `T[K]`; editable drafts may be partial objects, plus `null`
- * or `undefined` when those values are part of `T[K]`.
- *
- * @template T - The row data type
- * @template K - The column key
+ * Custom Surface editor for structured object columns. Drafts are partial
+ * objects plus any nullish members declared by the row value.
  */
 export type CustomEditConfig<T, K extends keyof T> = [
     CustomEditPresentObjectValue<T, K>
 ] extends [never] ? never : Omit<BaseEditConfig<T, K>, "onChange"> & {
-    /**
-     * Custom edit mode - renders a multi-field editor surface.
-     */
+    /** Opens a consumer-rendered multi-field Surface editor. */
     mode: "custom";
     /**
      * Callback fired when the current draft is committed. The value is the
      * exact draft state: partial object, full object, or allowed nullish value.
      */
     onCommit: (value: CustomEditDraftValue<T, K>, rowId: string) => void;
-    /**
-     * Callback fired on every local draft mutation with the exact draft state.
-     */
+    /** Observes every local draft mutation without committing it. */
     onDraftUpdate?: (value: CustomEditDraftValue<T, K>, rowId: string) => void;
-    /**
-     * Optional validation metadata derived from the current draft.
-     */
+    /** Derives form and field errors from the current draft. */
     validateDraft?: (draftValue: CustomEditDraftValue<T, K>, rowId: string) => CustomEditValidation<CustomEditPresentObjectValue<T, K>> | undefined;
     /**
      * When true, submit-style close requests are blocked while validation contains
      * a form error or any field error. Defaults to `false`.
      */
     blockOnValidationError?: boolean;
-    /**
-     * Optional close interception hook.
-     * Return `false` to keep the editor open.
-     */
+    /** Return `false` to reject the requested close. */
     onRequestClose?: (request: CustomEditCloseRequest<CustomEditPresentObjectValue<T, K>, CustomEditDraftValue<T, K>, CustomEditInitialValue<T, K>>) => boolean | void;
-    /**
-     * Optional surface presentation overrides.
-     */
+    /** Presentation and keyboard overrides for the editor Surface. */
     surface?: CustomEditSurfaceConfig;
     /**
      * Consumer-owned renderer for the custom editor contents. Editors should
@@ -268,121 +211,60 @@ export type CustomEditConfig<T, K extends keyof T> = [
      */
     renderEditor: (context: CustomEditRenderContext<T, K>) => ReactNode;
 };
-/**
- * Edit configuration for text mode cells.
- * @template T - The row data type
- * @template K - The column key
- */
+/** Inline text editor configuration. */
 export type TextEditConfig<T, K extends keyof T> = BaseEditConfig<T, K> & {
-    /**
-     * Text edit mode - renders an inline text input.
-     */
+    /** Renders an inline text field. */
     mode: "text";
 };
-/**
- * Edit configuration for number mode cells.
- * Renders an inline number input with increment/decrement support.
- *
- * @template T - The row data type
- * @template K - The column key
- */
+/** Inline numeric editor configuration. */
 export type NumberEditConfig<T, K extends keyof T> = BaseEditConfig<T, K> & {
-    /**
-     * Number edit mode - renders an inline number input with formatting and validation.
-     */
+    /** Renders an inline number field. */
     mode: "number";
-    /**
-     * The minimum value for the number field.
-     * @default 0
-     */
+    /** Inclusive minimum. Defaults to `0`. */
     minValue?: number;
-    /**
-     * The maximum value for the number field.
-     * @default 100000000000000
-     */
+    /** Inclusive maximum. Defaults to `100000000000000`. */
     maxValue?: number;
-    /**
-     * The step value for the number field.
-     * @default 1
-     */
+    /** Increment used by stepping controls. Defaults to `1`. */
     step?: number;
-    /**
-     * The maximum number of decimal places for the number field.
-     * @default 0
-     */
+    /** Maximum accepted fraction digits. Defaults to `0`. */
     maximumFractionDigits?: number;
-    /**
-     * The minimum number of decimal places for the number field.
-     * @default 0
-     */
+    /** Minimum displayed fraction digits. Defaults to `0`. */
     minimumFractionDigits?: number;
 };
 type SelectMenuCellPassthroughProps = Omit<SelectMenuSyncProps, "trigger" | "label" | "value" | "onSelectedOptionChange" | "options" | "onMenuKeyDown" | "onImplicitClose" | "onExplicitClose">;
 type MultiSelectMenuCellPassthroughProps = Omit<MultiSelectMenuSyncProps, "trigger" | "label" | "value" | "onSelectedOptionsChange" | "options" | "onMenuKeyDown" | "onImplicitClose" | "onExplicitClose">;
-/**
- * Edit configuration for select mode cells.
- * @template T - The row data type
- * @template K - The column key
- */
+/** Synchronous single-select editor configuration. */
 export type SelectEditConfig<T, K extends keyof T> = Omit<BaseEditConfig<T, K>, "onChange"> & {
-    /**
-     * Select edit mode - renders a SelectMenu popover.
-     */
+    /** Opens a SelectMenu popover. */
     mode: "select";
-    /**
-     * The options available for selection.
-     */
+    /** Complete option set shown by the menu. */
     options: SelectMenuOption[];
-    /**
-     * Callback fired when the selected option changes.
-     * @param option - The newly selected option, or null if cleared
-     * @param rowId - The id of the row being edited
-     */
+    /** Persists the selected option, or `null` after Clear, for the row. */
     onChange: (option: SelectMenuOption | null, rowId: string) => void;
 } & SelectMenuCellPassthroughProps;
-/**
- * Edit configuration for multiselect mode cells.
- * @template T - The row data type
- * @template K - The column key
- */
+/** Synchronous multi-select editor configuration. */
 export type MultiselectEditConfig<T, K extends keyof T> = Omit<BaseEditConfig<T, K>, "onChange"> & {
-    /**
-     * Multiselect edit mode - renders a searchable MultiSelectMenu popover.
-     */
+    /** Opens a searchable MultiSelectMenu popover. */
     mode: "multiselect";
-    /**
-     * The options available for selection.
-     */
+    /** Complete option set shown by the menu. */
     options: MultiSelectMenuOption[];
-    /**
-     * Callback fired when the selected options change.
-     * @param options - The newly selected options
-     * @param rowId - The id of the row being edited
-     */
+    /** Persists the selected option objects for the row. */
     onChange: (options: MultiSelectMenuOption[], rowId: string) => void;
 } & MultiSelectMenuCellPassthroughProps;
 type SelectMenuAsyncCellPassthroughProps = Omit<SelectMenuProps, "trigger" | "label" | "value" | "onSelectedOptionChange" | "loadOptions" | "lazy" | "lazyOptions" | "onMenuKeyDown" | "onImplicitClose" | "onExplicitClose">;
 type MultiSelectMenuAsyncCellPassthroughProps = Omit<MultiSelectMenuProps, "trigger" | "label" | "value" | "onSelectedOptionsChange" | "loadOptions" | "lazy" | "lazyOptions" | "onMenuKeyDown" | "onImplicitClose" | "onExplicitClose">;
 /**
- * Context passed to `loadOptions` for async edit configs.
- * Provides row data for per-row option loading.
- * @template T - The row data type
- * @property row - The full row data object
- * @property rowId - The string id of the row
+ * Row-specific context appended to async option-loader arguments.
  */
 export type AsyncCellContext<T> = {
     row: T;
     rowId: string;
 };
 /**
- * Eager loader for `mode: "select-async"` — returns all matching options at once.
- * @template T - The row data type
+ * Returns all matching single-select options for a query and row.
  */
 export type SelectAsyncCellEagerLoader<T> = (searchValue: string, context: AsyncCellContext<T>) => SelectMenuOption[] | Promise<SelectMenuOption[]>;
-/**
- * Page-based lazy loader for `mode: "select-async"`.
- * @template T - The row data type
- */
+/** Loads one numbered page of single-select options for a query and row. */
 export type SelectAsyncCellPageLoader<T> = (searchValue: string, pageNumber: number, pageSize: number, context: AsyncCellContext<T>) => {
     options: SelectMenuOption[];
     hasMore?: boolean;
@@ -390,10 +272,7 @@ export type SelectAsyncCellPageLoader<T> = (searchValue: string, pageNumber: num
     options: SelectMenuOption[];
     hasMore?: boolean;
 }>;
-/**
- * Offset-based lazy loader for `mode: "select-async"`.
- * @template T - The row data type
- */
+/** Loads one offset window of single-select options for a query and row. */
 export type SelectAsyncCellOffsetLoader<T> = (searchValue: string, offset: number, limit: number, context: AsyncCellContext<T>) => {
     options: SelectMenuOption[];
     hasMore?: boolean;
@@ -401,10 +280,7 @@ export type SelectAsyncCellOffsetLoader<T> = (searchValue: string, offset: numbe
     options: SelectMenuOption[];
     hasMore?: boolean;
 }>;
-/**
- * Group-based lazy loader for `mode: "select-async"`.
- * @template T - The row data type
- */
+/** Loads the single-select group after `previousGroupKey`. */
 export type SelectAsyncCellGroupLoader<T> = (searchValue: string, previousGroupKey: SelectMenuGroupByValue | null, context: AsyncCellContext<T>) => {
     options: SelectMenuOption[];
     hasMore?: boolean;
@@ -412,15 +288,9 @@ export type SelectAsyncCellGroupLoader<T> = (searchValue: string, previousGroupK
     options: SelectMenuOption[];
     hasMore?: boolean;
 }>;
-/**
- * Eager loader for `mode: "multiselect-async"` — returns all matching options at once.
- * @template T - The row data type
- */
+/** Returns all matching multi-select options for a query and row. */
 export type MultiselectAsyncCellEagerLoader<T> = (searchValue: string, context: AsyncCellContext<T>) => MultiSelectMenuOption[] | Promise<MultiSelectMenuOption[]>;
-/**
- * Page-based lazy loader for `mode: "multiselect-async"`.
- * @template T - The row data type
- */
+/** Loads one numbered page of multi-select options for a query and row. */
 export type MultiselectAsyncCellPageLoader<T> = (searchValue: string, pageNumber: number, pageSize: number, context: AsyncCellContext<T>) => {
     options: MultiSelectMenuOption[];
     hasMore?: boolean;
@@ -428,10 +298,7 @@ export type MultiselectAsyncCellPageLoader<T> = (searchValue: string, pageNumber
     options: MultiSelectMenuOption[];
     hasMore?: boolean;
 }>;
-/**
- * Offset-based lazy loader for `mode: "multiselect-async"`.
- * @template T - The row data type
- */
+/** Loads one offset window of multi-select options for a query and row. */
 export type MultiselectAsyncCellOffsetLoader<T> = (searchValue: string, offset: number, limit: number, context: AsyncCellContext<T>) => {
     options: MultiSelectMenuOption[];
     hasMore?: boolean;
@@ -439,10 +306,7 @@ export type MultiselectAsyncCellOffsetLoader<T> = (searchValue: string, offset:
     options: MultiSelectMenuOption[];
     hasMore?: boolean;
 }>;
-/**
- * Group-based lazy loader for `mode: "multiselect-async"`.
- * @template T - The row data type
- */
+/** Loads the multi-select group after `previousGroupKey`. */
 export type MultiselectAsyncCellGroupLoader<T> = (searchValue: string, previousGroupKey: SelectMenuGroupByValue | null, context: AsyncCellContext<T>) => {
     options: MultiSelectMenuOption[];
     hasMore?: boolean;
@@ -451,192 +315,133 @@ export type MultiselectAsyncCellGroupLoader<T> = (searchValue: string, previousG
     hasMore?: boolean;
 }>;
 type SelectAsyncEditConfigBase = {
-    /**
-     * Callback fired when the selected option changes.
-     * @param option - The newly selected option, or null if cleared
-     * @param rowId - The id of the row being edited
-     */
+    /** Persists the selected option, or `null` after Clear, for the row. */
     onChange: (option: SelectMenuOption | null, rowId: string) => void;
 } & SelectMenuAsyncCellPassthroughProps;
 /**
- * Edit configuration for async select mode cells.
- * Uses `SelectMenu` directly (not `SelectMenuSync`) to support server-side option loading.
- *
- * The `loadOptions` function receives a `context` argument as its last parameter,
- * containing the current row data and row id. This enables per-row option loading.
- *
- * By default, caching is disabled to prevent cross-row cache pollution when `loadOptions`
- * uses row context. Pass `cache={{ enabled: true }}` to override.
- *
- * Cell value is expected to be a primitive that matches a `SelectMenuOption.id`.
- *
- * @template T - The row data type
+ * Server-loaded single-select editor for primitive values matching option ids.
+ * Loaders receive row context, so caching defaults off to avoid sharing results
+ * across rows.
  */
 export type SelectAsyncEditConfig<T> = (SelectAsyncEditConfigBase & {
+    /** Opens a server-loaded SelectMenu. */
     mode: "select-async";
+    /** Eager loading. Defaults to `false`. */
     lazy?: false;
+    /** Returns all options matching the search. */
     loadOptions: SelectAsyncCellEagerLoader<T>;
+    /** Eager loading accepts no pagination settings. */
     lazyOptions?: never;
 }) | (SelectAsyncEditConfigBase & {
+    /** Opens a server-loaded SelectMenu. */
     mode: "select-async";
+    /** Loads options by page number. */
     lazy: "page";
+    /** Returns one page matching the search. */
     loadOptions: SelectAsyncCellPageLoader<T>;
+    /** Page-size override forwarded to the menu. */
     lazyOptions?: {
         pageSize?: number;
     };
 }) | (SelectAsyncEditConfigBase & {
+    /** Opens a server-loaded SelectMenu. */
     mode: "select-async";
+    /** Loads options by offset. */
     lazy: "offset";
+    /** Returns one offset window matching the search. */
     loadOptions: SelectAsyncCellOffsetLoader<T>;
+    /** Window-size override forwarded to the menu. */
     lazyOptions?: {
         limit?: number;
     };
 }) | (SelectAsyncEditConfigBase & {
+    /** Opens a server-loaded SelectMenu. */
     mode: "select-async";
+    /** Loads options one group at a time. */
     lazy: "group";
+    /** Returns the group after the supplied group key. */
     loadOptions: SelectAsyncCellGroupLoader<T>;
+    /** Group-loading settings forwarded to the menu. */
     lazyOptions?: object;
 });
 type MultiselectAsyncEditConfigBase = {
-    /**
-     * Callback fired when the selected options change.
-     * @param options - The newly selected options (full option objects)
-     * @param rowId - The id of the row being edited
-     */
+    /** Persists the selected full option objects for the row. */
     onChange: (options: MultiSelectMenuOption[], rowId: string) => void;
 } & MultiSelectMenuAsyncCellPassthroughProps;
 /**
- * Edit configuration for async multiselect mode cells.
- * Uses `MultiSelectMenu` directly (not `MultiSelectMenuSync`) to support server-side option loading.
- *
- * The `loadOptions` function receives a `context` argument as its last parameter,
- * containing the current row data and row id. This enables per-row option loading.
- *
- * By default, caching is disabled to prevent cross-row cache pollution when `loadOptions`
- * uses row context. Pass `cache={{ enabled: true }}` to override.
- *
- * **Value contract**: Unlike `mode: "multiselect"` (which stores ID arrays), the cell value
- * for `mode: "multiselect-async"` must be `MultiSelectMenuOption[]` — full option objects.
- * The `onChange` callback receives these objects directly and the consumer stores them wholesale.
- *
- * @template T - The row data type
+ * Server-loaded multi-select editor whose cell value is the full option-object
+ * array. Loaders receive row context, so caching defaults off to avoid sharing
+ * results across rows.
  */
 export type MultiselectAsyncEditConfig<T> = (MultiselectAsyncEditConfigBase & {
+    /** Opens a server-loaded MultiSelectMenu. */
     mode: "multiselect-async";
+    /** Eager loading. Defaults to `false`. */
     lazy?: false;
+    /** Returns all options matching the search. */
     loadOptions: MultiselectAsyncCellEagerLoader<T>;
+    /** Eager loading accepts no pagination settings. */
     lazyOptions?: never;
 }) | (MultiselectAsyncEditConfigBase & {
+    /** Opens a server-loaded MultiSelectMenu. */
     mode: "multiselect-async";
+    /** Loads options by page number. */
     lazy: "page";
+    /** Returns one page matching the search. */
     loadOptions: MultiselectAsyncCellPageLoader<T>;
+    /** Page-size override forwarded to the menu. */
     lazyOptions?: {
         pageSize?: number;
     };
 }) | (MultiselectAsyncEditConfigBase & {
+    /** Opens a server-loaded MultiSelectMenu. */
     mode: "multiselect-async";
+    /** Loads options by offset. */
     lazy: "offset";
+    /** Returns one offset window matching the search. */
     loadOptions: MultiselectAsyncCellOffsetLoader<T>;
+    /** Window-size override forwarded to the menu. */
     lazyOptions?: {
         limit?: number;
     };
 }) | (MultiselectAsyncEditConfigBase & {
+    /** Opens a server-loaded MultiSelectMenu. */
     mode: "multiselect-async";
+    /** Loads options one group at a time. */
     lazy: "group";
+    /** Returns the group after the supplied group key. */
     loadOptions: MultiselectAsyncCellGroupLoader<T>;
+    /** Group-loading settings forwarded to the menu. */
     lazyOptions?: object;
 });
 /**
- * Edit configuration for boolean mode cells.
- * Renders a dropdown menu with predefined true/false options and an optional null option.
- *
- * @template T - The row data type
- * @template K - The column key
+ * Boolean dropdown editor with an optional null choice.
  */
 export type BooleanEditConfig<T, K extends keyof T> = BaseEditConfig<T, K> & {
-    /**
-     * Boolean edit mode - renders a dropdown with true/false/null options.
-     */
+    /** Opens the boolean-options menu. */
     mode: "boolean";
-    /**
-     * The label displayed for the `true` option.
-     * @default "True"
-     */
+    /** Label for `true`. Defaults to `"True"`. */
     trueLabel?: string;
-    /**
-     * The label displayed for the `false` option.
-     * @default "False"
-     */
+    /** Label for `false`. Defaults to `"False"`. */
     falseLabel?: string;
-    /**
-     * Whether to include a null option in the dropdown.
-     * @default false
-     */
+    /** Adds a null choice. Defaults to `false`. */
     allowNull?: boolean;
-    /**
-     * The label displayed for the `null` option. Only used when `allowNull` is true.
-     * @default "Unset"
-     */
+    /** Label for the null choice. Defaults to `"Unset"`. */
     nullLabel?: string;
 };
 /**
- * Union of all edit configurations.
- * Use with `editConfig` property on column definitions.
- *
- * @template T - The row data type
- * @template K - The column key
- *
- * @example
- * ```ts
- * // Text editing
- * editConfig: { mode: "text", onChange: (value, rowId) => save(value, rowId) }
- *
- * // Number editing
- * editConfig: {
- *   mode: "number",
- *   minValue: 0,
- *   maxValue: 1000,
- *   step: 1,
- *   onChange: (value, rowId) => save(value, rowId)
- * }
- *
- * // Select editing
- * editConfig: {
- *   mode: "select",
- *   options: [{ id: "active", label: "Active" }],
- *   onChange: (option, rowId) => save(option?.id, rowId)
- * }
- *
- * // Boolean editing
- * editConfig: {
- *   mode: "boolean",
- *   trueLabel: "Yes",
- *   falseLabel: "No",
- *   onChange: (value, rowId) => save(value, rowId)
- * }
- *
- * // Custom editing keeps renderCell as the read path
- * editConfig: {
- *   mode: "custom",
- *   onCommit: (draft, rowId) => saveDraft(draft, rowId),
- *   onDraftUpdate: (draft, rowId) => previewDraft(draft, rowId),
- *   renderEditor: ({ controller }) => renderAddressEditor(controller)
- * }
- * ```
+ * Edit configurations available for a keyed row value. `createColumnHelper`
+ * narrows this union to modes compatible with that value type.
  */
 export type EditConfig<T, K extends keyof T> = TextEditConfig<T, K> | NumberEditConfig<T, K> | SelectEditConfig<T, K> | SelectAsyncEditConfig<T> | MultiselectEditConfig<T, K> | MultiselectAsyncEditConfig<T> | BooleanEditConfig<T, K> | CustomEditConfig<T, K>;
 /**
- * The type for a table row
- * @extends T
+ * Consumer row data plus the identity and optional status/expansion metadata
+ * required by DataTable.
  */
 export type TableRow<T> = T & {
-    /**
-     * The id of the row
-     */
+    /** Stable identity used for selection, editing, and React keys. */
     id: string | number;
-    /**
-     * Row metadata including errors
-     */
+    /** Cell- and row-level validation status. */
     meta?: {
         /**
          * Cell-level errors keyed by column id.
@@ -665,36 +470,31 @@ export type TableRow<T> = T & {
          */
         rowWarning?: boolean | string;
     };
-    /**
-     * The sub component displayed when the row is expanded
-     */
+    /** Detail content shown beneath an expanded row. */
     subComponent?: ReactNode;
-    /**
-     * The sub rows of the row when the row is expanded
-     */
+    /** Nested rows revealed by expansion. */
     subRows?: TableRow<T>[];
 };
+/** Read-only overflow treatment for a leaf column. */
 export type ColumnOverflowConfig = {
     /**
      * Disclosure behavior used when mounted read-only cell content is clipped.
      */
     mode: "surface";
 };
+/** Header, sizing, alignment, pinning, and footer options shared by columns. */
 export type ColumnBaseDef = ColumnHeaderConfig & {
     /**
-     * The alignment of the header and cell content.
-     * When using `type`, this is set automatically but can be overridden.
+     * On leaf columns, overrides the alignment inferred from `type`. Group
+     * headers stay start-aligned.
      */
     align?: "start" | "center" | "end";
     /**
-     * Custom content to display when a cell value is empty (null, undefined, or empty string).
-     * Overrides the default em dash. When set on both the column and the DataTable,
-     * the column-level value takes precedence.
+     * Replaces the table's empty-cell content for this column. Applies to `null`,
+     * `undefined`, and empty strings.
      */
     emptyCellContent?: ReactNode;
-    /**
-     * The content of the footer cell. An array will display multiple footer rows
-     */
+    /** One footer value, or one value per footer row. */
     footerContent?: ReactNode | ReactNode[];
     /**
      * The maximum width of the column, in pixels. Caps automatic growth when
@@ -708,39 +508,25 @@ export type ColumnBaseDef = ColumnHeaderConfig & {
      */
     minWidth?: number;
     /**
-     * The preferred starting width of the column, in pixels. Used as the basis
-     * for automatic growing/shrinking: the column renders at this width by
-     * default, grows toward `maxWidth` when the table has spare horizontal
-     * space, and never auto-shrinks below it — the table scrolls horizontally
-     * instead.
-     *
-     * Manual resize via the column's resize handle is still bounded by
-     * `minWidth`/`maxWidth`, so users can drag a column below `defaultWidth`
-     * down to `minWidth`.
-     *
-     * @remarks Values outside `minWidth`/`maxWidth` are not validated when
-     * provided. CSS grid clamps the rendered width at display time.
+     * Preferred starting width in pixels. Unpinned columns render at this width,
+     * grow toward `maxWidth` when the table has spare space, and never
+     * auto-shrink below it (the table scrolls instead). Pinned columns stay at
+     * this size. Manual resize is still bounded by `minWidth`/`maxWidth`.
      *
-     * Falls back to `minWidth` when not specified.
+     * Values outside `minWidth`/`maxWidth` are not validated when provided; CSS
+     * grid clamps at display time. Falls back to `minWidth` when omitted.
      */
     defaultWidth?: number;
-    /**
-     * The pinning location of the column
-     */
+    /** Keeps the column against the chosen edge while horizontally scrolling. */
     pinned?: "left" | "right";
-    /**
-     * Whether the column is resizable
-     */
+    /** Shows a pointer-driven resize handle. */
     resizable?: boolean;
 };
+/** Header group containing nested leaf or group columns. */
 export type ColumnGroupDef<T> = ColumnBaseDef & {
-    /**
-     * Group column id.
-     */
+    /** Stable id for the header group. */
     id: string;
-    /**
-     * Columns of a group column
-     */
+    /** Leaf or nested columns displayed beneath this group header. */
     columns: ColumnDef<T>[];
     editConfig?: never;
     overflow?: never;
@@ -749,155 +535,90 @@ export type ColumnGroupDef<T> = ColumnBaseDef & {
     type?: never;
 };
 type ColumnDataDefBase<T, K extends keyof T> = ColumnBaseDef & {
-    /**
-     * The id of the column - must be a key of T
-     */
+    /** Row key read by this column. */
     id: K;
-    /**
-     * Columns of a group column
-     */
     columns?: undefined;
     /**
-     * The function to customize how the cell content is rendered.
-     * When using `type`, a default renderer is provided but can be overridden.
-     * Custom edit columns continue to use this read-only render path.
+     * Overrides the renderer inferred from `type`. Custom edit columns continue
+     * to use this for their read-only state.
      */
     renderCell?: (value: T[K], context: ColumnReadRenderContext<TableRow<T>>) => ReactNode;
-    /**
-     * Optional plain-text extractor for the read path.
-     * Useful when `renderCell` returns JSX or multiline content but default sorting
-     * should still use a simple string.
-     */
+    /** Supplies sortable text when `renderCell` returns rich content. */
     getCellText?: (value: T[K], context: ColumnReadRenderContext<TableRow<T>>) => string;
     /**
-     * Optional advanced read-display extractor.
-     * Prefer `getCellText` for the common case where `renderCell` already handles
-     * display and sorting only needs a simple string. Use this when you want one
-     * hook to return both rendered read content and the sortable raw string.
+     * Supplies rendered content and sortable text together. When set, it wins
+     * over `renderCell` and `getCellText`. Prefer `getCellText` when only
+     * sorting needs an alternate representation.
      */
     getReadRenderResult?: (value: T[K], context: ColumnReadRenderContext<TableRow<T>>) => ColumnReadRenderResult;
-    /**
-     * Whether the column is sortable, or a function to customize the sorting logic.
-     * When a function, receives values of the column's value type.
-     */
+    /** Enables default sorting, or supplies a value comparator. */
     sortable?: boolean | ((valueA: T[K], valueB: T[K]) => number);
     /**
-     * The column type for automatic display configuration.
-     * Sets default `renderCell` (formatter) and `align` based on the data type.
+     * Supplies default formatting and alignment; explicit column options override
+     * those defaults.
      */
     type?: ColumnTypeConfig;
 };
 type ColumnReadOnlyDefForKey<T, K extends keyof T> = ColumnDataDefBase<T, K> & {
     editConfig?: undefined;
-    /**
-     * Shows full read-only cell content in a Surface when mounted content is clipped.
-     */
+    /** Shows clipped read-only content in a disclosure Surface. */
     overflow?: ColumnOverflowConfig;
 };
 type ColumnEditableDefForKey<T, K extends keyof T> = ColumnDataDefBase<T, K> & {
-    /**
-     * Configuration for cell editing. Presence enables editing for the column.
-     * Consolidates edit mode, options, and onChange into a single object.
-     */
+    /** Enables cell editing with the selected mode and persistence callback. */
     editConfig: EditConfig<T, K>;
     overflow?: never;
 };
+/** Read-only or editable leaf definition for one row key. */
 export type ColumnDefForKey<T, K extends keyof T> = ColumnReadOnlyDefForKey<T, K> | ColumnEditableDefForKey<T, K>;
 type ColumnLeafDef<T> = ColumnDataDefBase<T, keyof T> & ({
     editConfig?: undefined;
-    /**
-     * Shows full read-only cell content in a Surface when mounted content is clipped.
-     */
+    /** Shows clipped read-only content in a disclosure Surface. */
     overflow?: ColumnOverflowConfig;
 } | {
-    /**
-     * Configuration for cell editing. Presence enables editing for the column.
-     * Consolidates edit mode, options, and onChange into a single object.
-     */
+    /** Enables cell editing with the selected mode and persistence callback. */
     editConfig: EditConfig<T, keyof T>;
     overflow?: never;
 });
-/**
- * Column definition type for DataTable columns.
- *
- * Use `createColumnHelper<T>()` to create type-safe column definitions with
- * proper type inference for `type`, `editConfig`, and value types.
- *
- * @example
- * ```ts
- * type Data = { name: string; amount: number; tags: string[] };
- * const createColumn = createColumnHelper<Data>();
- *
- * const columns = [
- *   // Display-only column with type defaults
- *   createColumn("amount", { header: { label: "Amount" }, type: "currency" }),
- *
- *   // Editable column with editConfig
- *   createColumn("name", {
- *     header: { label: "Name" },
- *     type: "text",
- *     editConfig: { mode: "text", onChange: (value, rowId) => save(value, rowId) }
- *   }),
- *
- *   // Multiselect editing
- *   createColumn("tags", {
- *     header: { label: "Tags" },
- *     editConfig: {
- *       mode: "multiselect",
- *       options: [{ value: "urgent", label: "Urgent" }],
- *       onChange: (value, rowId) => save(value, rowId)
- *     }
- *   }),
- * ];
- * ```
- */
+/** Visible label and optional indicator/help content for a column header. */
 export type ColumnHeader = {
-    /**
-     * The visible header label text.
-     */
+    /** Text used as the visible and accessible column label. */
     label: string;
-    /**
-     * Whether the header should show a required indicator.
-     */
+    /** Shows the required indicator beside the label. */
     required?: boolean;
-    /**
-     * Additional contextual content rendered from a keyboard-accessible more-info trigger.
-     */
+    /** Content opened from the header's keyboard-accessible more-info trigger. */
     moreInfo?: ReactNode;
 };
+/**
+ * Requires either the current structured header or the deprecated label.
+ */
 export type ColumnHeaderConfig = {
-    /**
-     * The forward-looking header configuration.
-     */
+    /** Label and optional header adornments. */
     header: ColumnHeader;
     /**
-     * Legacy header label support during the transition to `header`.
+     * Deprecated string label used when `header` is omitted.
      * @deprecated Use `header.label` instead.
      */
     headerLabel?: string;
 } | {
-    /**
-     * The forward-looking header configuration.
-     */
+    /** Label and optional header adornments. */
     header?: ColumnHeader;
     /**
-     * Legacy header label support during the transition to `header`.
+     * Deprecated string label used when `header` is omitted.
      * @deprecated Use `header.label` instead.
      */
     headerLabel: string;
 };
-export type ColumnDef<T> = ColumnGroupDef<T> | ColumnLeafDef<T>;
 /**
- * The type for a custom table footer cell props
+ * Group or leaf definition consumed by DataTable. Prefer
+ * {@link createColumnHelper} for value-aware edit-mode inference.
  */
+export type ColumnDef<T> = ColumnGroupDef<T> | ColumnLeafDef<T>;
+/** Values passed to a custom footer-cell renderer. */
 export type CustomTableFooterCellProps = {
-    /**
-     * The content of the footer cell
-     */
+    /** Rendered footer content. */
     content: ReactNode;
-    /**
-     * The number of columns the footer cell should span
-     */
+    /** Grid columns occupied by this footer cell. */
     colSpan: number;
 };
 export {};