@factorialco/f0-react 6.24.0 → 6.26.0

package/dist/experimental.d.ts

@@ -4781,6 +4781,9 @@ export declare interface DeleteBlockNotesTextEditorPageDocumentPatch {
     targetId: string;
 }
 
+/** The row data a schema field demands, or merely allows under `rightOptional`. */
+declare type Demanded<T, Optional> = Optional extends true ? Partial<T> : T;
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
@@ -8184,6 +8187,46 @@ declare type HighlightBannerProps = {
     onClick?: () => void;
 };
 
+/**
+ * One of a row's hover actions: a button at the row's right that acts on THAT
+ * row.
+ *
+ * ICON-ONLY BY DEFAULT, because a row is a dense line of text and a strip of
+ * labelled buttons beside it would outweigh what it is about — `label` is then
+ * the accessible name and the tooltip rather than visible text.
+ *
+ * A row's PRIMARY action can say what it is (`showLabel`), and usually should
+ * when the glyph alone would be a guess: "Clock out" is a clock, and so is
+ * "Snooze". Keep it to ONE per row, leading, with the rest as glyphs — a strip
+ * of labelled buttons is a toolbar, not a row.
+ */
+declare type HomeListItemAction = {
+    /** What it DOES, in words: "Clock out", "Dismiss". Never "OK" or "Go". */
+    label: string;
+    /** Omit for a text-only button — then the label always shows. */
+    icon?: IconType;
+    /** A destructive one — it draws as the critical button. */
+    critical?: boolean;
+    /** Show the `label` beside the glyph instead of only in the tooltip. */
+    showLabel?: boolean;
+} & ({
+    onClick: () => void;
+    items?: never;
+} | {
+    /**
+     * The action OPENS A MENU instead of doing one thing — "Remind me" over
+     * Later today / Tomorrow / Next Monday. Ordinary `DropdownItem`s, so a
+     * `{ type: "label", text }` heads the group and `{ type: "separator" }`
+     * divides it.
+     *
+     * The button is the same button either way, glyph or label: what changes
+     * is that pressing it opens the menu, and the strip STAYS OPEN while the
+     * menu is (the pointer has to leave the row to reach it).
+     */
+    items: DropdownItem[];
+    onClick?: never;
+});
+
 export declare type HomePeriod = keyof typeof GRADIENTS;
 
 /**
@@ -8218,6 +8261,39 @@ export declare type HomeSkeletonCtx = HomeRenderCtx & {
  */
 export declare const homeSlot: <V extends keyof HomeSlotParamsMap>(visualization: V, params: HomeSlotParamsMap[V], options?: SlotOptions) => HomeWidgetSlot;
 
+/**
+ * One item inside a {@link HomeSlotItems}. MUST carry the item's stable id as
+ * its `key` — that key is the only thing telling the list which items are the
+ * same ones between two renders, and a positional key would animate every row
+ * below a removal as though it had been replaced.
+ */
+export declare const HomeSlotItem: ({ className, animated, children, }: HomeSlotItemProps) => JSX_2.Element;
+
+declare interface HomeSlotItemProps {
+    className?: string;
+    /**
+     * `false` puts the item straight where it belongs, with no enter or exit —
+     * for a render that is replacing the list rather than changing one item of it
+     * (see {@link useIsBulkChange}).
+     */
+    animated?: boolean;
+    children: ReactNode;
+}
+
+/**
+ * The list an item's arrival and departure is animated in. Wrap the items of
+ * ANY slot in it — `list` rows, `event-list` events, a bespoke renderer's own —
+ * and give each {@link HomeSlotItem} the item's stable id as its key.
+ *
+ * `initial={false}`: the items already there when the widget mounts have not
+ * arrived, they simply are. The widget's own entrance (`HomeEntrance`) is what
+ * brings the whole card in; without this every list would replay a row-by-row
+ * arrival inside it.
+ */
+export declare const HomeSlotItems: ({ children }: {
+    children: ReactNode;
+}) => JSX_2.Element;
+
 /** The built-in slot vocabulary: each visualization and its params shape. */
 export declare interface HomeSlotParamsMap {
     "event-list": EventListParams;
@@ -8788,17 +8864,55 @@ declare type ListClickData<C> = C extends "link" ? {
  */
 declare type ListCollectionProps<Record extends RecordType, Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Summaries extends SummariesDefinition, ItemActions extends ItemActionsDefinition<Record>, NavigationFilters extends NavigationFiltersDefinition, Grouping extends GroupingDefinition<Record>> = CollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping, ListVisualizationOptions<Record, Filters, Sortings>>;
 
+/**
+ * A row's glyph tint: one of {@link listIconColors}, or a HEX of your own.
+ *
+ * Prefer a palette name. Those eleven hues were picked to sit beside each other
+ * in one column and to hold up in both themes, which is the whole job here — a
+ * feed's glyphs are read as a SET, and a colour chosen per row without seeing
+ * the others is how a card ends up with two greens that mean different things.
+ *
+ * The hex is for the case the palette genuinely cannot serve: a colour that is
+ * already data — a calendar's own colour, a module's brand, a category a user
+ * picked themselves. It is treated exactly like a palette hue (a tenth of it as
+ * the tile, the hue itself as the icon), so a bespoke colour and a named one
+ * still draw the same glyph. `#RGB` and `#RRGGBB` both parse; anything else
+ * falls back to the plain, untinted glyph rather than drawing nothing.
+ */
+export declare type ListIconColor = ListIconPaletteColor | `#${string}`;
+
+/**
+ * The tint a row's ICON glyph can carry. f0's NAMED palette — the same hues
+ * `ui/Avatar` colours initials with — deliberately, rather than the semantic
+ * families (`critical`, `warning`, `positive`): a colour here says which KIND
+ * of thing the row is, so a feed can give every category its own without any of
+ * them reading as an alert. For "this is urgent", the left kind is `alert`.
+ */
+export declare const listIconColors: readonly ["viridian", "malibu", "yellow", "purple", "lilac", "barbie", "smoke", "army", "flubber", "indigo", "camel"];
+
+export declare type ListIconPaletteColor = (typeof listIconColors)[number];
+
 /** One row of a `list` slot — its shape FOLLOWS from the slot's schema. */
 export declare type ListItem<S extends ListSchema = ListSchema> = {
     id: string | number;
     /** An accent dot on the left glyph — unseen/pending. */
     unread?: boolean;
-} & ListTextData<S> & ListLeftData<S["left"]> & ListRightData<S["right"]> & ListClickData<S["clickBehavior"]>;
+    /**
+     * What can be DONE to this row, revealed on hover (and on focus, so they are
+     * reachable by keyboard) behind a fade over whatever the row trails. Keep it
+     * to two: the strip covers the row's right-hand side while it shows.
+     */
+    actions?: ListRowAction[];
+} & ListTextData<S> & ListLeftData<S["left"]> & ListRightData<S["right"], S["rightOptional"]> & ListClickData<S["clickBehavior"]>;
 
 declare type ListLeftData<L> = L extends "module" ? {
     module: ModuleId;
 } : L extends "alert" ? {
     alert: AlertType;
+} : L extends "icon" ? {
+    avatar: AvatarData<"icon"> & {
+        color?: ListIconColor;
+    };
 } : L extends AvatarVariant["type"] ? {
     avatar: AvatarData<L>;
 } : object;
@@ -8814,14 +8928,15 @@ export declare interface ListParams<S extends ListSchema = ListSchema> {
 
 declare type ListPropertyDefinition<R, Sortings extends SortingsDefinition> = WithOptionalSorting_2<R, Sortings> & PropertyDefinition_2<R>;
 
-declare type ListRightData<R> = R extends "counter" ? {
+declare type ListRightData<R, Optional> = R extends "counter" ? Demanded<{
     count: number;
-} : R extends `${infer T extends F0AvatarListProps["type"]}-list` ? {
+}, Optional> : R extends `${infer T extends F0AvatarListProps["type"]}-list` ? Demanded<{
     avatars: Array<AvatarData<T>>;
+}, Optional> & {
     remainingCount?: number;
-} : R extends AvatarVariant["type"] ? {
+} : R extends AvatarVariant["type"] ? Demanded<{
     rightAvatar: AvatarData<R>;
-} : object;
+}, Optional> : object;
 
 /**
  * What every row draws on its RIGHT: a counter, one avatar (e.g. the sender),
@@ -8829,6 +8944,14 @@ declare type ListRightData<R> = R extends "counter" ? {
  */
 export declare type ListRightKind = "counter" | AvatarVariant["type"] | `${F0AvatarListProps["type"]}-list`;
 
+/**
+ * One HOVER ACTION on a `list` row: an icon button over the row's right edge
+ * that acts on that row alone — "Clock out", "Dismiss". Per ROW rather than per
+ * schema, because unlike everything else about a row what you can do to it is
+ * genuinely its own: a feed mixes items you can dismiss with items you can't.
+ */
+export declare type ListRowAction = HomeListItemAction;
+
 /**
  * A `list` slot's SCHEMA: declared once for the whole slot, it decides what
  * every row looks like — the rows are CONSISTENT by construction, and the item
@@ -8841,10 +8964,29 @@ export declare interface ListSchema {
     left?: ListLeftKind;
     /** The one right treatment every row draws. Omit for none. */
     right?: ListRightKind;
+    /**
+     * The `right` treatment is ALLOWED but not demanded: rows that carry its data
+     * draw it and the rest trail nothing — a feed where only some items came from
+     * a person. Without this every row must supply it, which is what keeps an
+     * ordinary list even.
+     */
+    rightOptional?: boolean;
     /** Every row carries an inline subtitle (on the title's line, after a dot). */
     subtitleRequired?: boolean;
     /** Every row carries a second line — this is what makes rows two-line. */
     descriptionRequired?: boolean;
+    /**
+     * A second line is ALLOWED but not demanded: some rows carry a `description`
+     * and others don't — a feed where only a few items have a due date or a
+     * sender. The list is still a two-line list (the glyphs stay `md`, so the
+     * column of them lines up); the rows without one are simply shorter.
+     *
+     * `descriptionRequired` wins when both are set: demanding it already allows it.
+     *
+     * Such a list does NOT auto-compact past {@link LIST_COMPACT_AFTER} rows —
+     * see {@link listCompacts}. `compact: true` still forces it.
+     */
+    descriptionOptional?: boolean;
     /**
      * `"link"` rows each carry an `href` and render as REAL anchors (role
      * `link`, routed through the app's `LinkProvider`) — never an onClick;
@@ -8882,6 +9024,8 @@ declare type ListTextData<S extends ListSchema> = {
     subtitle?: never;
 }) & (S["descriptionRequired"] extends true ? {
     description: string;
+} : S["descriptionOptional"] extends true ? {
+    description?: string;
 } : {
     description?: never;
 });
@@ -9340,6 +9484,30 @@ export declare interface NewHomeLayoutProps {
      * dragging and the add placeholder; the others stay put. Both by default.
      */
     editableWidgetContainers?: WidgetContainerSide[];
+    /**
+     * Which containers keep ONLY THE WIDGETS YOU CAN SEE in the DOM. None by
+     * default: for a Home of a dozen widgets, mounting them all is what keeps a
+     * card's data, clock and animation alive across everything this layout does to
+     * it, and virtualizing would trade that away for nothing.
+     *
+     * Name a side once its widgets can outnumber a screen — a hundred cards is a
+     * hundred fetches and a hundred charts, and all but the three in view are work
+     * nobody asked for. Below `virtualization.threshold` widgets (12 by default) the
+     * column still renders them all, so naming a side here is a CEILING rather than
+     * a switch. What it costs is on `WidgetVirtualization`; in short, a widget that
+     * scrolls out is unmounted and comes back new, and only the cards in view get
+     * out of a dragged one's way.
+     *
+     * STACKED (below `md`) the rail's widgets belong to the main column, so "main"
+     * is what virtualizes them there.
+     */
+    virtualizedWidgetContainers?: WidgetContainerSide[];
+    /**
+     * Tuning for the above — the height a card is guessed at before it is measured,
+     * how many are kept past each edge, and the count it starts at. The scroll
+     * region is this layout's own, per side, and is not yours to set.
+     */
+    virtualization?: Omit<WidgetVirtualization, "scrollElement">;
     /**
      * Called with a widget id when its "Remove widget" menu item is used — the
      * three-dots menu in the widget's own header.
@@ -12520,6 +12688,13 @@ export declare const useInfiniteScrollPagination: (paginationInfo: PaginationInf
     loadingIndicatorRef: RefObject<HTMLTableCellElement>;
 };
 
+/**
+ * Whether the item count changed by more than {@link ITEM_CHURN_BULK_AFTER}
+ * since the last render — i.e. whether THIS render is a bulk replacement rather
+ * than an item coming or going. Feed it to {@link HomeSlotItem}'s `animated`.
+ */
+export declare const useIsBulkChange: (count: number, threshold?: number) => boolean;
+
 /**
  * Converts an item-navigation result into the `NavigationProps` shape that
  * `PageHeader` and `F0Dialog` accept (directly or via
@@ -12583,6 +12758,8 @@ export declare const useSidebarChatActions: () => SidebarChatActions;
 /** Read the chat state (groups, active chat) and the imperative store API. */
 export declare const useSidebarChats: () => SidebarChatStore;
 
+export declare const useWidgetIsWide: () => boolean;
+
 /**
  * Profile data for a vacancy entity (ATS vacancy/position), resolved asynchronously
  * and displayed in the entity reference hover card.
@@ -13210,6 +13387,45 @@ export declare const widgetTitle: (widget: {
     params?: WidgetParams;
 }) => string;
 
+/**
+ * VIRTUALIZATION — what a column does when it has more widgets than a screen.
+ *
+ * A widget is not a row: it is a card with its own data, its own chart, its own
+ * list of rows inside it. A hundred of them mounted is a hundred fetches, a
+ * hundred charts laid out and a DOM the browser spends every frame on, and all
+ * but the three you can see are work nobody asked for. So a virtualized column
+ * mounts ONLY the widgets in view (plus `overscan` past each edge) and holds the
+ * space of the rest open, so the scrollbar still describes the whole column.
+ *
+ * WHAT IT COSTS, and why it is opt-in rather than the default:
+ *
+ * - A widget that scrolls out is UNMOUNTED. Whatever it had loaded, timed or
+ *   animated is gone, and it starts again when it comes back — the opposite of
+ *   what the collapsed rail is built to guarantee. For a column of a few widgets
+ *   that trade is a bad one, which is what `threshold` is for.
+ * - Dragging still reorders correctly, but only the widgets that are MOUNTED
+ *   shuffle out of the way as you go: dnd-kit can't move a card that isn't
+ *   there. The dragged card itself is pinned into the DOM for the whole gesture.
+ * - `fullHeight` means nothing here. A virtualized column's height is the sum of
+ *   its cards, so there is no column height for a card to fill.
+ */
+export declare interface WidgetVirtualization {
+    /**
+     * Below this many widgets the column simply renders them all. Defaults to 12.
+     */
+    threshold?: number;
+    /** First guess at a card's height in px, before it is measured. */
+    estimateHeight?: number;
+    /** How many cards stay mounted past each edge of the viewport. */
+    overscan?: number;
+    /**
+     * The scroll region to virtualize against. Defaults to the column's nearest
+     * scrollable ancestor — pass it when you already have the element (it saves
+     * the walk, and it is exact).
+     */
+    scrollElement?: HTMLElement | null;
+}
+
 declare type WidgetWidth = "sm" | "md" | "lg";
 
 declare interface WiggleOptions {
@@ -13382,10 +13598,8 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        indent: {
-            setIndent: (level: number) => ReturnType;
-            unsetIndent: () => ReturnType;
-            outdent: () => ReturnType;
+        moodTracker: {
+            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
         };
     }
 }
@@ -13393,8 +13607,10 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        moodTracker: {
-            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
+        indent: {
+            setIndent: (level: number) => ReturnType;
+            unsetIndent: () => ReturnType;
+            outdent: () => ReturnType;
         };
     }
 }