@factorialco/f0-react 7.29.0 → 7.31.0

package/dist/f0.d.ts

@@ -4775,6 +4775,8 @@ export declare type DatePeriodsDefinition = {
 
 declare type DatePickerCompareTo = Partial<Record<NavigationGranularityKey, CompareToDef[]>>;
 
+export declare const datePickerInlineDismissReasons: readonly ["blur", "escape", "commit", "popupClose"];
+
 declare interface DatePickerPopupProps {
     onSelect?: (value: DatePickerValue_2 | undefined) => void;
     value?: DatePickerValue_2;
@@ -5375,6 +5377,9 @@ export declare const defaultTranslations: {
     };
     readonly toc: {
         readonly search: "Search...";
+        readonly noResults: "No matches.";
+        readonly moreResults: "+{{count}} more";
+        readonly resultsCount: "{{count}} results";
     };
     readonly collections: {
         readonly sorting: {
@@ -6239,6 +6244,19 @@ export declare const defaultTranslations: {
                 readonly other: "{{count}} issues";
             };
         };
+        readonly sections: {
+            readonly search: {
+                readonly placeholder: "Search this record";
+                readonly noResults: "No field matches.";
+                readonly moreResults: "+{{count}} more";
+                readonly resultsCount: "{{count}} fields";
+            };
+        };
+        readonly inline: {
+            readonly edit: "Edit {{label}}";
+            readonly copy: "Copy {{label}}";
+            readonly copied: "Copied {{label}}";
+        };
         readonly file: {
             readonly dropzone: "Drag and drop a file, or click to select";
             readonly dropzoneActive: "Drop the file here";
@@ -6647,6 +6665,8 @@ export declare type DisplayToken = "block" | "flex" | "inline" | "inline-flex" |
  */
 declare type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 
+declare type DistributiveOmit_2<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
 /** Divider direction */
 export declare type DividerToken = "x" | "y";
 
@@ -8328,6 +8348,8 @@ export declare interface F0AnalyticsDashboardProps<Filters extends FiltersDefini
     navigationFilters?: NavigationFiltersDefinition;
 }
 
+export declare type F0AnySectionConfig = F0PerSectionSectionConfig | F0ContentSectionConfig;
+
 /**
  * Config for array fields (multi-select or multi-file)
  * @typeParam T - The value type (string or number)
@@ -8855,6 +8877,17 @@ export declare interface F0BaseConfig {
      * field-specific configuration (e.g. data source, options) or a custom component.
      */
     customFieldName?: string;
+    /**
+     * Allow editing in inline mode. Resolve viewer permissions when building the
+     * schema.
+     * @default true
+     */
+    editable?: boolean;
+    /**
+     * Add a plain-text copy action in inline mode.
+     * @default false
+     */
+    copyable?: boolean;
 }
 
 /**
@@ -8904,6 +8937,16 @@ export declare interface F0BaseField {
      * Used with the form-level `renderCustomField` callback.
      */
     customFieldName?: string;
+    /**
+     * Allow editing in inline mode.
+     * @default true
+     */
+    editable?: boolean;
+    /**
+     * Add a plain-text copy action in inline mode.
+     * @default false
+     */
+    copyable?: boolean;
 }
 
 /**
@@ -9437,6 +9480,16 @@ declare interface F0ClarifyingPanelProps {
     isSubmitDisabled?: boolean;
 }
 
+/**
+ * A section with content instead of fields: a `sections` key with no match in
+ * `schema`. It gets a heading and rail entry but no validation or dirty state.
+ */
+export declare interface F0ContentSectionConfig extends F0SectionConfig {
+    /** Rendered under the section heading. */
+    render: () => React.ReactNode;
+    submitConfig?: never;
+}
+
 /**
  * F0 config options specific to custom fields
  *
@@ -10369,6 +10422,21 @@ export declare const F0DatePicker: WithDataTestIdReturnType_3<typeof F0DatePicke
 
 declare function F0DatePicker_2({ onChange, value, presets, granularities, minDate, maxDate, open, showIcon, displayFormat, selectOnCellOnly, ...inputProps }: F0DatePickerProps): JSX_2.Element;
 
+export declare const F0DatePickerInline: WithDataTestIdReturnType_3<typeof F0DatePickerInline_2>;
+
+/** Renders the date as text at rest and the public date picker while editing. */
+declare function F0DatePickerInline_2({ editing, onDismiss, ...props }: F0DatePickerInlineProps): JSX_2.Element;
+
+export declare type F0DatePickerInlineDismissReason = (typeof datePickerInlineDismissReasons)[number];
+
+export declare interface F0DatePickerInlineProps extends Omit<F0DatePickerProps, "open" | "onOpenChange"> {
+    /** Mounts F0DatePicker with its calendar initially open. */
+    editing?: boolean;
+    onDismiss?: (reason: F0DatePickerInlineDismissReason) => void;
+    open?: never;
+    onOpenChange?: never;
+}
+
 export declare type F0DatePickerProps = Pick<DatePickerPopupProps, "minDate" | "maxDate" | "presets" | "open" | "onOpenChange" | "selectOnCellOnly"> & {
     /** The picker has no `periods` prop, so it can only offer the calendar granularities. */
     granularities?: GranularityDefinitionKey[];
@@ -11303,7 +11371,8 @@ export declare interface F0FormDefinitionPerSection<T extends F0PerSectionSchema
     /** Module associated with this form (for avatar display in canvas cards) */
     module?: ModuleId;
     schema: T;
-    sections?: Record<string, F0PerSectionSectionConfig>;
+    /** Keyed by section ID. A key with no schema entry is a content section. */
+    sections?: F0PerSectionSections<T>;
     defaultValues?: {
         [K in keyof T]?: Partial<z.infer<T[K]>>;
     };
@@ -11390,7 +11459,7 @@ export declare type F0FormErrorTriggerMode = "on-blur" | "on-change" | "on-submi
  * duration, select, checkbox, switch, date, time, datetime, daterange, richtext, custom,
  * and file.
  */
-export declare function F0FormField({ field, value, onChange, onBlur, error, errorMessage, status, loading, required, disabled, hideLabel: hideLabelProp, initialFiles, }: F0FormFieldProps): JSX_2.Element;
+export declare function F0FormField({ field, value, onChange, onBlur, error, errorMessage, status, loading, required, disabled, hideLabel: hideLabelProp, initialFiles, inline, }: F0FormFieldProps): JSX_2.Element;
 
 export declare namespace F0FormField {
     var displayName: string;
@@ -11796,6 +11865,12 @@ declare interface F0FormFieldCommonProps {
     disabled?: boolean;
     /** Whether to hide the label (useful when label is rendered externally) */
     hideLabel?: boolean;
+    /**
+     * Render an editable detail row. The row owns the label; edits still call
+     * onChange.
+     * @default false
+     */
+    inline?: boolean;
 }
 
 declare interface F0FormFieldFileProps extends F0FormFieldCommonProps {
@@ -11876,6 +11951,11 @@ declare interface F0FormPropsWithDefinition {
      * instead of replacing the entire form with skeleton placeholders.
      */
     isLoading?: boolean;
+    /**
+     * Render editable detail rows using the existing save action bar.
+     * @default false
+     */
+    inline?: boolean;
 }
 
 /**
@@ -11902,6 +11982,11 @@ export declare interface F0FormPropsWithPerSectionDefinition<T extends F0PerSect
      * instead of replacing the entire form with skeleton placeholders.
      */
     isLoading?: boolean;
+    /**
+     * Render editable detail rows. One action bar saves every dirty section.
+     * @default false
+     */
+    inline?: boolean;
 }
 
 /**
@@ -11914,16 +11999,22 @@ export declare interface F0FormPropsWithPerSectionSchema<T extends F0PerSectionS
     name: string;
     /** Record mapping section IDs to their Zod schemas. Each section is independently validated and submitted. */
     schema: T;
-    /** Section configurations keyed by section ID */
-    sections?: Record<string, F0PerSectionSectionConfig>;
+    /**
+     * Section configurations keyed by section ID. A key not in `schema` is a
+     * content section.
+     */
+    sections?: F0PerSectionSections<T>;
     /** Default values for each section, keyed by section ID */
     defaultValues?: {
         [K in keyof T]?: Partial<z.infer<T[K]>>;
     };
     /** Callback when a section is submitted. Receives the section ID and its validated data, both correctly typed. */
     onSubmit: PerSectionSubmitHandler<T>;
-    /** Global submit config applied to all sections (can be overridden per section) */
-    submitConfig?: F0PerSectionSubmitConfig;
+    /**
+     * Global submit config applied to all sections (overridable per section).
+     * With `inline`, pass an action-bar config; section overrides are ignored.
+     */
+    submitConfig?: F0PerSectionSubmitConfig | F0FormActionBarSubmitConfig;
     /** Additional class name for the form container */
     className?: string;
     /**
@@ -11965,6 +12056,11 @@ export declare interface F0FormPropsWithPerSectionSchema<T extends F0PerSectionS
      * instead of replacing the entire form with skeleton placeholders.
      */
     isLoading?: boolean;
+    /**
+     * Render editable detail rows. One action bar saves every dirty section.
+     * @default false
+     */
+    inline?: boolean;
 }
 
 /**
@@ -12002,6 +12098,11 @@ export declare interface F0FormPropsWithSingleSchema<TSchema extends F0FormSchem
      * Controls section sidebar visibility and box wrapping.
      */
     styling?: F0FormStylingConfig;
+    /**
+     * Render editable detail rows using the existing save action bar.
+     * @default false
+     */
+    inline?: boolean;
     /**
      * Ref to control the form programmatically from outside.
      * Use with the `useF0Form` hook to get a ref and submit/reset functions.
@@ -12064,6 +12165,11 @@ export declare interface F0FormPropsWithSingleSchemaDefinition<TSchema extends F
      * When a field has `customFieldName`, this function is called instead of the inline `render`.
      */
     renderCustomField?: RenderCustomFieldFunction;
+    /**
+     * Render editable detail rows using the existing save action bar.
+     * @default false
+     */
+    inline?: boolean;
 }
 
 /**
@@ -12077,19 +12183,23 @@ export declare interface F0FormRef {
      */
     submit: () => Promise<void>;
     /**
-     * Reset the form to its default values
+     * Reset the form to its default values.
+     * In inline per-section mode, resets every dirty section.
      */
     reset: () => void;
     /**
-     * Check if the form has unsaved changes
+     * Check if the form has unsaved changes.
+     * In inline per-section mode, true while any visible section is dirty.
      */
     isDirty: () => boolean;
     /**
-     * Get the current form values (including unsaved changes)
+     * Get the current form values (including unsaved changes).
+     * In inline per-section mode, keyed by section id.
      */
     getValues: () => Record<string, unknown>;
     /**
-     * Set a single field value programmatically
+     * Set a single field value programmatically.
+     * In inline per-section mode, the field is looked up in every section.
      */
     setValue: (fieldName: string, value: unknown, options?: F0FormSetValueOptions) => void;
     /**
@@ -12102,15 +12212,20 @@ export declare interface F0FormRef {
      */
     trigger: (fieldName?: string) => Promise<boolean>;
     /**
-     * Get current validation errors as a map of field name to error message
+     * Get current validation errors as a map of field name to error message.
+     * In inline per-section mode, the errors of every visible section.
      */
     getErrors: () => Record<string, string>;
     /**
-     * Get the list of field names in the form
+     * Get the list of field names in the form.
+     * In inline per-section mode, the field names of every visible section.
      */
     getFieldNames: () => string[];
     /**
-     * Access the action bar imperatively (e.g. to trigger a wiggle animation)
+     * Access the action bar imperatively, e.g. `actionBar.wiggle()` when
+     * navigation is blocked by unsaved changes. No-op when no bar is shown.
+     * `{ errorHighlight: true }` adds error styling only when there are
+     * validation errors.
      */
     actionBar: F0ActionBarRef;
     /* Excluded from this release type: _setStateCallback */
@@ -12150,11 +12265,23 @@ export declare interface F0FormStylingConfig {
      * @default false
      */
     showSectionsSidepanel?: boolean;
+    /**
+     * Pixels between the pinned sections rail and the top of the scroll area,
+     * to clear a sticky header. Inline forms only.
+     * @default 0
+     */
+    sectionsSidepanelOffset?: number;
     /**
      * Removes the default padding around the form content.
      * @default false
      */
     noPadding?: boolean;
+    /**
+     * Adds a search box to the sections rail that filters sections and fields by
+     * label. Requires `showSectionsSidepanel`.
+     * @default false
+     */
+    sectionsSearch?: boolean;
 }
 
 /**
@@ -12990,8 +13117,18 @@ declare type F0PerSectionSchema_2 = Record<string, F0FormSchema_2>;
 export declare interface F0PerSectionSectionConfig extends F0SectionConfig {
     /** Override submit config for this specific section */
     submitConfig?: F0PerSectionSubmitConfig;
+    /** Only content sections (no schema key) take `render`. */
+    render?: never;
 }
 
+/**
+ * The `sections` record of a per-section form. The plain-record branch lets
+ * forms typed against a generic schema compile, as their keys can't be proven.
+ */
+export declare type F0PerSectionSections<T extends F0PerSectionSchema> = ({
+    [K in keyof T & string]?: F0PerSectionSectionConfig;
+} & Record<string, F0AnySectionConfig>) | Record<string, F0PerSectionSectionConfig>;
+
 /**
  * Per-section submit configuration, extending the base submit config
  * with an optional per-section label override.
@@ -13489,7 +13626,40 @@ declare type F0SelectFieldProps<T extends string, R = unknown> = F0SelectPopupPr
     hideArrow?: boolean;
 } & Pick<InputFieldProps<T>, "required" | "loading" | "hideLabel" | "labelIcon" | "size" | "label" | "icon" | "placeholder" | "disabled" | "name" | "error" | "status" | "hint">;
 
-declare type F0SelectInlineProps<T extends string, R = unknown> = F0SelectPopupProps<T, R> & F0SelectSingleSelectionProps<T, R> & Pick<InputFieldProps<T>, "label" | "placeholder" | "disabled"> & {
+declare type F0SelectFieldVariantProps<T extends string, R> = Extract<F0SelectProps<T, R>, {
+    variant?: "field";
+}>;
+
+/**
+ * @experimental This is an experimental component use it at your own risk
+ */
+export declare const F0SelectInline: typeof F0SelectInline_2;
+
+/** The detail-row select owns its static reading and mounts F0Select for editing. */
+declare function F0SelectInline_2<T extends string = string, R = unknown>({ editing, onDismiss, ...props }: F0SelectInlineProps<T, R>): JSX_2.Element;
+
+export declare type F0SelectInlineDismissReason = (typeof selectInlineDismissReasons)[number];
+
+/** Field props that F0SelectInline draws or controls itself. */
+declare type F0SelectInlineOmittedProp = "variant" | "open" | "onOpenChange" | "children" | "className" | "asList" | "hideArrow" | "size" | "icon" | "labelIcon" | "required" | "name" | "error" | "status" | "hint";
+
+export declare type F0SelectInlineProps<T extends string = string, R = unknown> = WithClearableOnChange<DistributiveOmit_2<F0SelectFieldVariantProps<T, R>, F0SelectInlineOmittedProp>, T, R> & {
+    /**
+     * The parent owns the mode. While true, F0Select is mounted with its list
+     * initially open; F0Select then manages that list's open state. `disabled`
+     * wins and keeps the value at rest.
+     */
+    editing?: boolean;
+    /**
+     * Called once per gesture that ends the edit, on the next frame and after any
+     * `onChange` it caused. The parent sets the mode and restores focus.
+     */
+    onDismiss?: (reason: F0SelectInlineDismissReason) => void;
+} & {
+    [K in F0SelectInlineOmittedProp]?: never;
+};
+
+declare type F0SelectInlineProps_2<T extends string, R = unknown> = F0SelectPopupProps<T, R> & F0SelectSingleSelectionProps<T, R> & Pick<InputFieldProps<T>, "label" | "placeholder" | "disabled"> & {
     /**
      * Compact borderless presentation for single-value controls embedded in rows.
      * The required label is used as the accessible name and is not shown visually.
@@ -13645,7 +13815,7 @@ declare type F0SelectPopupProps<T extends string, R = unknown> = {
  * @template T - The type of the emitted value
  * @template R - The type of the record/item data (used with data source)
  */
-export declare type F0SelectProps<T extends string, R = unknown> = (F0SelectFieldProps<T, R> | F0SelectInlineProps<T, R>) & F0SelectDataProps<T, R>;
+export declare type F0SelectProps<T extends string, R = unknown> = (F0SelectFieldProps<T, R> | F0SelectInlineProps_2<T, R>) & F0SelectDataProps<T, R>;
 
 declare type F0SelectSelectionProps<T extends string, R = unknown> = F0SelectSingleSelectionProps<T, R> | {
     clearable: true;
@@ -13929,6 +14099,16 @@ export declare type F0TextareaField = F0BaseField & F0TextareaConfig & {
  */
 export declare const F0TextAreaInput: React.FC<F0TextAreaInputProps>;
 
+/** Wrapped text at rest; the standard textarea while the parent enables editing. */
+export declare const F0TextAreaInputInline: ForwardRefExoticComponent<F0TextAreaInputInlineProps & RefAttributes<HTMLTextAreaElement>>;
+
+export declare interface F0TextAreaInputInlineProps extends F0TextAreaInputProps {
+    /** Focuses the textarea when it opens. Defaults to true. */
+    autoFocus?: boolean;
+    editing?: boolean;
+    onDismiss?: (reason: InlineDismissReason) => void;
+}
+
 export declare type F0TextAreaInputProps = Pick<ComponentProps<typeof Textarea_2>, "disabled" | "onChange" | "value" | "placeholder" | "rows" | "cols" | "label" | "labelIcon" | "icon" | "hideLabel" | "maxLength" | "clearable" | "onBlur" | "onFocus" | "name" | "status" | "hint" | "error" | "size" | "loading" | "required" | "maxHeight">;
 
 /**
@@ -15858,6 +16038,64 @@ declare type InlineDismissReason = (typeof inlineDismissReasons)[number];
 
 declare const inlineDismissReasons: readonly ["blur", "escape", "commit"];
 
+/** Presentation-only row. The forwarded ref targets the activator for focus restoration. */
+export declare const InlineFieldRow: ForwardRefExoticComponent<InlineFieldRowProps & RefAttributes<HTMLDivElement>>;
+
+export declare type InlineFieldRowAction = {
+    key: string;
+    icon: IconType;
+    label: string;
+    onClick: () => void;
+    /** Draws the glyph in the positive token, for a state the row is confirming. */
+    positive?: boolean;
+};
+
+/**
+ * Alert props the row renders with `F0Alert`, so every row gets the same
+ * chrome.
+ */
+export declare type InlineFieldRowAlert = Omit<F0AlertProps, "variant"> & {
+    /** @default "info" */
+    variant?: F0AlertProps["variant"];
+};
+
+export declare const InlineFieldRowList: ({ children }: {
+    children: ReactNode;
+}) => JSX_2.Element;
+
+export declare type InlineFieldRowProps = {
+    /** Anchor the row so section navigation and error scrolling can reach it. */
+    anchorId?: string;
+    label: string;
+    /** Marks the label with a star. */
+    required?: boolean;
+    /** Hint shown beside the label. */
+    hint?: string;
+    value: ReactNode;
+    /** Fixed order, closest to the value first. Copy is appended after it. */
+    actions: InlineFieldRowAction[];
+    /** When set, the row appends a copy action that writes exactly this string. */
+    copyValue?: string;
+    /** Omit to disable activation. */
+    onActivate?: () => void;
+    /** Use a caret for text editors and a pointer for popup editors. */
+    activatorCursor?: "caret" | "pointer";
+    /**
+     * `"fixed"` pins the value box to 40px; `"auto"` grows from 40px with its
+     * content.
+     * @default "fixed"
+     */
+    valueHeight?: "fixed" | "auto";
+    editing: boolean;
+    /** Validation copy below the value; also marks the value box as critical. */
+    message?: string;
+    /**
+     * Contextual alert below the value in both modes; does not affect validity
+     * styling.
+     */
+    alert?: InlineFieldRowAlert;
+};
+
 /**
  * @deprecated Renamed to `F0TextInput` to match the F0 input vocabulary
  * (any component where the user types text in a box has the `Input` suffix
@@ -19086,6 +19324,12 @@ export declare type SelectedState = {
  */
 declare type SelectFieldRenderIf = SelectRenderIfCondition | CommonRenderIfCondition | F0BaseFieldRenderIfFunction;
 
+/**
+ * What ends an inline select edit. Any close of the list other than a pick or
+ * Escape is `"popupClose"`. There is no `"blur"`: focus stays in the list.
+ */
+export declare const selectInlineDismissReasons: readonly ["escape", "commit", "popupClose"];
+
 export declare type SelectionId = number | string;
 
 export declare type SelectionMeta<R extends RecordType> = {
@@ -19248,6 +19492,13 @@ export declare const StandardLayout: WithDataTestIdReturnType_2<ForwardRefExotic
 
 export declare interface StandardLayoutProps extends VariantProps<typeof layoutVariants> {
     children?: default_2.ReactNode;
+    /**
+     * Whether the layout is its own scroll container. Set `false` when the host
+     * scrolls the page, so sticky descendants pin against the host's scroller.
+     * An overflow box is a sticky scrollport even when it never scrolls.
+     * @default true
+     */
+    scrollable?: boolean;
 }
 
 export declare type Status = (typeof statuses_2)[number];
@@ -20375,7 +20626,37 @@ declare interface TOCProps {
     sortable?: boolean;
     onReorder?: (reorderedIds: IdStructure[]) => void;
     showSearchBox?: boolean;
+    /**
+     * @experimental
+     * Makes the search box a combobox whose results the arrow keys walk and Enter
+     * picks. Matching ignores accents and case and needs every term; a matching
+     * parent keeps its subtree; Escape clears. Has no effect without
+     * `showSearchBox`.
+     * @default false
+     */
+    navigableSearch?: boolean;
     searchPlaceholder?: string;
+    /**
+     * Results shown before the list is cut, with a line counting the rest.
+     * @default Infinity
+     */
+    searchResultLimit?: number;
+    /** Called with the query on every change. */
+    onSearchChange?: (query: string) => void;
+    /**
+     * Copy for a search that matches nothing. Defaults to `i18n.toc.noResults`.
+     */
+    searchEmptyLabel?: string;
+    /**
+     * Copy under a cut list; `{{count}}` is the hidden results. Defaults to
+     * `i18n.toc.moreResults`.
+     */
+    searchMoreResultsLabel?: string;
+    /**
+     * Copy announced when results change; `{{count}}` is the shown results.
+     * Defaults to `i18n.toc.resultsCount`.
+     */
+    searchResultsCountLabel?: string;
     hideChildrenCounter?: boolean;
     /** Enable vertical scrolling when content overflows (default: true) */
     scrollable?: boolean;
@@ -21737,10 +22018,18 @@ export declare type WelcomeSuggestionClickEvent = {
     prompt: string;
 };
 
-declare interface WiggleOptions {
+export declare interface WiggleOptions {
     errorHighlight?: boolean;
 }
 
+/** Clear hands a clearable single selection's `onChange` `undefined`. */
+declare type WithClearableOnChange<P, T extends string, R> = P extends {
+    clearable: true;
+    multiple?: false;
+} ? Omit<P, "onChange"> & {
+    onChange?: (value: T | undefined, originalItem?: ResolvedRecordType<R>, option?: F0SelectItemObject<T, ResolvedRecordType<R>>) => void;
+} : P;
+
 export declare const withDataTestId: <T extends default_2.ComponentType<any>>(component: T) => WithDataTestIdReturnType<T>;
 
 export declare type WithDataTestIdProps = {