@factorialco/f0-react 6.22.1 → 6.23.1

package/dist/experimental.d.ts

@@ -128,6 +128,9 @@ import { WithDataTestIdReturnType as WithDataTestIdReturnType_2 } from './experi
 import { WithDataTestIdReturnType as WithDataTestIdReturnType_3 } from './experimental';
 import { WithDataTestIdReturnType as WithDataTestIdReturnType_4 } from './experimental';
 import { WithDataTestIdReturnType as WithDataTestIdReturnType_5 } from './experimental';
+import { z } from 'zod';
+import { ZodEffects } from 'zod';
+import { ZodRawShape } from 'zod';
 
 declare type Action = {
     label: string;
@@ -4714,6 +4717,21 @@ declare const defaultTranslations: {
         readonly submit: "Submit";
         readonly stepOf: "Step {{current}} of {{total}}";
     };
+    readonly widgets: {
+        /** Turns a widget over to read what it is telling you (Home's `info`). */
+        readonly whatThisMeans: "What this info means?";
+        /** The button on that other side, which turns it back. */
+        readonly gotIt: "Got it";
+        /** The widget menu's own items, and the dialogs they open. */
+        readonly editParams: "Edit params";
+        readonly editParamsTitle: "Edit widget params";
+        readonly removeWidget: "Remove widget";
+        readonly addWidget: "Add widget";
+        /** Heads the widgets a Home suggests, at the top of the picker. */
+        readonly recommended: "Recommended";
+        /** Why a drop onto a pinned widget was refused. `{{title}}` is its name. */
+        readonly cannotMoveHere: "You can't move a widget here — {{title}} is locked.";
+    };
     readonly pdfViewer: {
         readonly toolbar: "Document toolbar";
         readonly previousPage: "Previous page";
@@ -5458,8 +5476,16 @@ declare type F0AvatarListProps = {
      */
     noTooltip?: boolean;
     /**
-     * The maximum number of avatars to display.
-     * @default 3
+     * The exact number of avatars to keep visible; the rest collapse into the
+     * `+N` counter. Not a soft cap — a provided `max` is forwarded as
+     * `OverflowList`'s `min` as well, so exactly this many avatars render even in
+     * a container too narrow to fit them (see `F0AvatarList.tsx`).
+     *
+     * There is no numeric default. Left unset, the visible count is
+     * container-driven: `OverflowList` measures the available width and shows as
+     * many avatars as fit, collapsing the remainder into the counter. So passing
+     * a number opts into a fixed footprint, and omitting it opts into filling
+     * the row.
      */
     max?: number;
     /**
@@ -5467,10 +5493,17 @@ declare type F0AvatarListProps = {
      */
     remainingCount?: number;
     /**
-     * The layout of the avatar list.
-     * - "fill" - Avatars will expand to fill the available width, with overflow items shown in a counter
-     * - "compact" - Avatars will be stacked tightly together up to the max limit, with remaining shown in counter
-     * @default "compact"
+     * @deprecated Never implemented — `F0AvatarList` has always ignored this
+     * prop — and not needed, because `max` already selects between the two
+     * layouts it described. Omit `max` for what this called `"fill"`:
+     * `OverflowList` measures the row and shows as many avatars as fit. Pass a
+     * `max` for `"compact"`: it doubles as `min`, so exactly that many stay
+     * visible. A separate switch could only contradict `max` — `layout="fill"`
+     * with `max={3}` has no coherent meaning — which is why this is going rather
+     * than getting an implementation.
+     * @removeIn 7.0.0
+     * @migration Remove the prop. If you were passing `layout="compact"` to cap
+     * the row, add `max={n}`: `"compact"` never capped anything.
      */
     layout?: "fill" | "compact";
     /**
@@ -6592,6 +6625,11 @@ declare type F0FormEditableTableRowAction<R extends RecordType> = {
     onClick: (item: R, index: number) => void | Promise<void>;
 };
 
+/**
+ * Type for F0Form schemas - can be a plain ZodObject or a refined ZodObject (ZodEffects)
+ */
+declare type F0FormSchema<T extends ZodRawShape = ZodRawShape> = z.ZodObject<T> | ZodEffects<z.ZodObject<T>>;
+
 /**
  * A tag rendered in a node's metadata row. Its visual is driven by the
  * `TagVariant` `type`; its column identity — which toggle/label/default-
@@ -7665,6 +7703,29 @@ declare interface FrameContextType {
     setForceFloat: (force: boolean) => void;
 }
 
+/**
+ * A params-driven value, TYPED against the widget's own schema — how to write a
+ * `title` or an `info` that reads its params without casting at every access:
+ *
+ * ```tsx
+ * title: fromParams(HOURS_PARAMS, (p) => `Hours · ${p.period ?? "this week"}`)
+ * ```
+ *
+ * The params arrive `Partial`, and that is not a formality: a widget exists
+ * before it is configured (the moment it is added, or while its dialog is open
+ * on an incomplete form), so every field has to be treated as possibly unset.
+ * The schema argument is there only to carry the type.
+ */
+export declare const fromParams: <S extends WidgetParamsSchema, T>(_schema: S, compute: (params: Partial<z.infer<S>>) => T) => (params: WidgetParams) => T;
+
+/**
+ * A widget property that may be COMPUTED FROM ITS PARAMS instead of fixed — the
+ * title that says which team it is showing, the info that explains the period
+ * you picked. It gets the params the widget has now (`{}` when it has none), so
+ * the same function serves a widget before and after it is configured.
+ */
+export declare type FromWidgetParams<T> = T | ((params: WidgetParams) => T);
+
 declare interface GaugeComputation {
     datasetId: string;
     aggregation: AggregationType;
@@ -8178,10 +8239,47 @@ export declare type HomeWidgetChrome = Pick<WidgetProps, "action" | "summaries">
     alert?: never;
 });
 
+/**
+ * A Home widget's header. The frame's, except that the two things a user reads
+ * to know WHAT they are looking at may follow the params they set.
+ */
+export declare type HomeWidgetHeader = Omit<NonNullable<WidgetProps["header"]>, "title" | "info"> & {
+    title?: FromWidgetParams<string>;
+    /**
+     * The `i` beside the title: hovering it explains the widget. Takes the params
+     * too, so it can say what the numbers actually cover.
+     */
+    info?: FromWidgetParams<string>;
+};
+
 /** A widget as handed to the layout: header + an ordered list of slots. */
 export declare type HomeWidgetItem = HomeWidgetChrome & {
     id: string;
-    header?: WidgetProps["header"];
+    header?: HomeWidgetHeader;
+    /**
+     * THIS WIDGET'S OWN menu items — "Mark all as read", "Export as CSV", whatever
+     * it can do that no other widget can. They go in the widget's three-dots menu,
+     * FIRST: the column adds what every widget carries (what its info means, its
+     * params, removing it) after them, and removing it sits behind a separator.
+     *
+     * Ordinary `DropdownItem`s, so they take an `icon`, a `description`, `critical`
+     * for a destructive one, `disabled`, or a `type: "separator"` of your own to
+     * group them. A `locked` widget still shows them.
+     */
+    actions?: WidgetProps["actions"];
+    /**
+     * The widget is CONFIGURABLE: these are the params the user may set, as an
+     * F0Form schema. Declaring it — together with the layout's
+     * `onChangeWidgetParams` — is what puts "Edit params" in the widget's menu.
+     */
+    paramsSchema?: WidgetParamsSchema;
+    /**
+     * The params it is configured with right now. They drive whatever the widget
+     * derives from them (its `title`, its `info`) and are the dialog's starting
+     * point; rebuilding the SLOTS for new params is the app's own job, since only
+     * it knows where their data comes from.
+     */
+    params?: WidgetParams;
     fullHeight?: boolean;
     /**
      * The widget's catalog glyph — shown for it in the collapsed rail and in the
@@ -8189,9 +8287,9 @@ export declare type HomeWidgetItem = HomeWidgetChrome & {
      */
     icon?: IconType;
     /**
-     * PINNED: the widget stays put. In edit mode it shows no remove control and
-     * does not wiggle (nor drag, once dragging lands) — for widgets a user must
-     * always have, like Clock in.
+     * PINNED: the widget stays put. It offers no "Remove widget" in its menu, it
+     * cannot be dragged, and no other widget can displace it — for widgets a user
+     * must always have, like Clock in.
      */
     locked?: boolean;
     /**
@@ -8751,7 +8849,8 @@ export declare interface ListSchema {
      * `"link"` rows each carry an `href` and render as REAL anchors (role
      * `link`, routed through the app's `LinkProvider`) — never an onClick;
      * that's the only click behavior rows have. Omit for inert rows.
-     * Same-tab for relative and `#` hrefs, `target="_blank"` for other domains.
+     * Same-tab for paths, `#` fragments and this host under any scheme;
+     * `target="_blank"` only for ANOTHER host (see `isExternalHref`).
      */
     clickBehavior?: "link";
     /**
@@ -9237,19 +9336,30 @@ export declare interface NewHomeLayoutProps {
     /** Full override of how a whole widget is drawn. Defaults to `SlotWidget`. */
     renderWidget?: (widget: HomeWidgetItem, ctx: HomeRenderCtx) => ReactNode;
     /**
-     * Edit mode. Omit it and the layout owns the state itself, toggled by its own
-     * edit button; pass it to drive edit mode from outside.
+     * Which containers a user may arrange. Only these offer "Remove widget",
+     * dragging and the add placeholder; the others stay put. Both by default.
      */
-    editing?: boolean;
-    /** Called when the layout's edit button is pressed. */
-    onEditingChange?: (editing: boolean) => void;
+    editableWidgetContainers?: WidgetContainerSide[];
     /**
-     * Which containers a user may actually edit. In edit mode only these show
-     * remove controls and the add placeholder; the others stay put. Both by default.
+     * Called with a widget id when its "Remove widget" menu item is used — the
+     * three-dots menu in the widget's own header.
      */
-    editableWidgetContainers?: WidgetContainerSide[];
-    /** Called with a widget id when its remove control is clicked (edit mode only). */
     onRemoveWidget?: (id: string) => void;
+    /**
+     * Called with a widget id and its new params when its "Edit params" dialog is
+     * saved. Providing it is what offers that item, in the same menu, for every
+     * widget that declares a `paramsSchema`. PERSIST what it hands you and pass it
+     * back as the widget's `params` — rebuilding the widget's slots for the new
+     * params is the app's own job, since only it knows where their data comes from.
+     */
+    onChangeWidgetParams?: (id: string, params: WidgetParams) => void;
+    /**
+     * Draws a widget for params being tried out in that dialog, before they are
+     * saved. Defaults to the widget with those params swapped in — which is
+     * already live for everything they derive (title, info); supply this to
+     * rebuild its slots as well.
+     */
+    renderWidgetPreview?: (widget: HomeWidgetItem, params: WidgetParams) => ReactNode;
     /** When set, renders a "+ Add widget" affordance at the bottom of each column. */
     onClickAddNewWidget?: (side: WidgetContainerSide) => void;
     /** Called with a side and its widget ids in their new order after a drag. */
@@ -10584,6 +10694,9 @@ export declare const resolveSlotRenderer: (entry: SlotRendererEntry | undefined)
     skeleton?: SlotSkeletonRenderer;
 } | undefined;
 
+/** Resolves a header's params-driven parts against the params in hand. */
+export declare const resolveWidgetHeader: (header: HomeWidgetHeader | undefined, params?: WidgetParams) => WidgetProps["header"];
+
 /**
  * Header for a resource detail page: avatar, title, description, status,
  * metadata and its primary, secondary and overflow actions.
@@ -12838,14 +12951,30 @@ export declare type WidgetAvatarsListItemProps = {
  * WidgetCatalog — the "Add widget" dialog, mirroring the custom-home prototype:
  * a searchable picker on the left (icon + title rows, the selected row tinted),
  * a LIVE preview of the highlighted widget on the right at the width it will
- * really get, and the "Add widget" CTA in the dialog footer. `width="xl"`
- * rather than fullscreen.
+ * really get, and the "Add widget" CTA in the dialog footer. FULLSCREEN off a
+ * large display, and the two columns stack on a narrow screen
+ * (`useWidgetDialogLayout`).
  *
  * Selection follows the filter: if the selected row is filtered out, the first
  * remaining row takes over, so the preview always shows something the CTA can
  * actually add.
  */
-export declare function WidgetCatalog({ isOpen, onClose, widgets, onAdd, previewWidth, title, }: WidgetCatalogProps): JSX_2.Element;
+export declare function WidgetCatalog({ isOpen, onClose, widgets, onAdd, groups, previewWidth, title, }: WidgetCatalogProps): JSX_2.Element;
+
+/**
+ * One DOMAIN in the picker: a heading the widgets under it belong to.
+ *
+ * The label is the app's own words because f0's `modules` registry maps ids to
+ * ICONS ONLY — there are no module names to borrow, and a domain may well cover
+ * two modules or none.
+ */
+export declare interface WidgetCatalogGroup {
+    /** What an item's `group` points at. */
+    id: string;
+    label: string;
+    /** The domain's module: its glyph heads the group. */
+    module?: ModuleId;
+}
 
 /** One entry in the widget catalog dialog. */
 export declare interface WidgetCatalogItem {
@@ -12857,6 +12986,23 @@ export declare interface WidgetCatalogItem {
      * `SlotWidget`), so the preview can't drift from what gets added.
      */
     preview: ReactNode;
+    /**
+     * What this widget is telling you — the widget's own `header.info`, shown under
+     * the preview. Deciding whether to add a widget is exactly the moment that
+     * sentence is worth reading, so the picker says it without being asked.
+     */
+    info?: string;
+    /**
+     * Which `groups` entry this widget belongs under. A widget whose group isn't
+     * declared (or which has none) is listed after the groups, without a heading.
+     */
+    group?: string;
+    /**
+     * LIFTS IT to a "Recommended" section at the very top, and out of its group —
+     * a widget offered twice reads as two widgets. Optional in every sense: with
+     * nothing recommended there is no section.
+     */
+    recommended?: boolean;
 }
 
 export declare interface WidgetCatalogProps {
@@ -12866,6 +13012,11 @@ export declare interface WidgetCatalogProps {
     widgets: WidgetCatalogItem[];
     /** Called with the chosen widget id when the CTA is pressed. */
     onAdd: (id: string) => void;
+    /**
+     * The DOMAINS the picker is organised into, in the order to show them. Omit it
+     * and the list is flat — grouping is an offer, not a requirement.
+     */
+    groups?: WidgetCatalogGroup[];
     /**
      * Content width of the column this was opened from — the preview is capped
      * to it, so a rail-bound widget previews at rail width.
@@ -12901,6 +13052,45 @@ export declare type WidgetInboxListItemProps<Id extends string | number = string
 
 export declare type WidgetInboxListProps = Props_9;
 
+/**
+ * What a user has CONFIGURED about a widget — the values of the fields its
+ * `paramsSchema` declares, keyed by field name. Dates arrive as `Date`s, a
+ * multi-select as an array: whatever the schema's zod types say.
+ */
+export declare type WidgetParams = Record<string, unknown>;
+
+/**
+ * Whether every REQUIRED param of a schema is set — what "this widget can't be
+ * shown until you configure it" comes down to. Use it to send a freshly added
+ * widget straight into its params dialog.
+ */
+export declare const widgetParamsAreComplete: (schema: WidgetParamsSchema | undefined, params: WidgetParams | undefined) => boolean;
+
+/**
+ * A widget's params SCHEMA: an F0Form schema, so the fields are declared once —
+ * in zod, with their f0 field config — and F0Form draws and validates them.
+ *
+ * That buys the whole vocabulary rather than a bespoke one: `z.string()`,
+ * `z.number()`, `z.date()` (`fieldType: "datetime"` for a time as well),
+ * `z.enum()`, and a select fed by a DATASOURCE (`source` + `mapOptions`, with
+ * `multiple` for many) — `z.array()` for the multi-select's value. A field is
+ * REQUIRED unless its zod type is `.optional()`, so "the user must set this"
+ * needs nothing new either.
+ *
+ * ```tsx
+ * paramsSchema: z.object({
+ *   since: f0FormField(z.date(), { label: "Since" }),
+ *   team: f0FormField(z.array(z.string()), {
+ *     label: "Teams",
+ *     source: teamsDataSource,
+ *     mapOptions: (team) => ({ value: team.id, label: team.name }),
+ *     multiple: true,
+ *   }),
+ * })
+ * ```
+ */
+export declare type WidgetParamsSchema = F0FormSchema;
+
 export declare interface WidgetProps {
     header?: {
         title?: string;
@@ -12908,22 +13098,37 @@ export declare interface WidgetProps {
         comment?: string;
         info?: string;
         canBeBlurred?: boolean;
+        /**
+         * The way out of the widget: it makes the TITLE ITSELF the link — the title
+         * with a chevron after it, one ghost-button-shaped target that lights up on
+         * hover. Nothing sits in the header's top-right (that is the overflow menu's)
+         * and nothing sits in the footer (that is `action`'s): the name of the widget
+         * IS the way into it.
+         */
         link?: {
             /**
-             * What following the link DOES, in words — "Go to Communities". The
-             * control is icon-only, so this is the only thing that says where it
-             * goes: it is its tooltip and its accessible name, and it is required
-             * for exactly that reason.
+             * What following it DOES, in words — "Go to Communities". The visible text
+             * is the widget's title, so this is what a screen reader announces
+             * instead: it names the DESTINATION, which a title alone cannot.
              */
             title: string;
             url?: string;
             onClick?: () => void;
-            /** Defaults to the external-link glyph. */
+            /** Defaults to the chevron. */
             icon?: IconType;
         };
         count?: number;
     };
+    /** The card's footer button — its call to action. `neutral`/`sm` by default. */
     action?: F0ButtonProps;
+    /**
+     * Extra classes for the FOOTER row that `action` draws in. For content that
+     * BLEEDS past the card's content box and wants the footer brought onto its
+     * line — Home's row-based slots bleed 8px, which eats the gap above the footer
+     * and offsets it from the rows (see `SlotWidget`). Spacing only; `F0Button`
+     * takes no className of its own, so this is the seam for it.
+     */
+    footerClassName?: string;
     summaries?: Array<{
         label: string;
         value: string | number;
@@ -12994,6 +13199,17 @@ export declare const WidgetStrip: ForwardRefExoticComponent<DashboardProps_2 & R
     Skeleton: () => JSX_2.Element;
 };
 
+/**
+ * A widget's title as TEXT — resolved against its own params, and falling back
+ * to its id so there is always something to name it by (an aria-label on the
+ * collapsed rail's glyph, a row in the catalog).
+ */
+export declare const widgetTitle: (widget: {
+    id: string;
+    header?: HomeWidgetHeader;
+    params?: WidgetParams;
+}) => string;
+
 declare type WidgetWidth = "sm" | "md" | "lg";
 
 declare interface WiggleOptions {
@@ -13134,9 +13350,11 @@ declare namespace Calendar {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        aiBlock: {
-            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
-            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number, options?: {
+                placeholder?: string;
+            }) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }
@@ -13144,11 +13362,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number, options?: {
-                placeholder?: string;
-            }) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
+        aiBlock: {
+            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
+            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
         };
     }
 }
@@ -13186,10 +13402,8 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        videoEmbed: {
-            setVideoEmbed: (options: {
-                src: string;
-            }) => ReturnType;
+        transcript: {
+            insertTranscript: (data: TranscriptData) => ReturnType;
         };
     }
 }
@@ -13197,8 +13411,10 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        transcript: {
-            insertTranscript: (data: TranscriptData) => ReturnType;
+        videoEmbed: {
+            setVideoEmbed: (options: {
+                src: string;
+            }) => ReturnType;
         };
     }
 }