@factorialco/f0-react 6.14.0 → 6.15.0

package/dist/experimental.d.ts

@@ -3350,15 +3350,32 @@ declare const daytimePageVariants: (props?: ({
     className?: ClassValue;
 })) | undefined) => string;
 
+/**
+ * How many placeholder items a slot draws when it doesn't say (its
+ * `expectedItemsCount`). Three: enough to read as a list, short enough that a
+ * widget which turns out to hold one item barely jumps.
+ */
+export declare const DEFAULT_EXPECTED_ITEMS_COUNT = 3;
+
 /**
  * Built-in renderers for the standard visualizations. `list` covers every
  * row-based slot through its schema; `event-list` and `indicators` spread
  * their params onto the matching f0 content component. Bespoke visualizations
  * (e.g. `clock-in`, `carousel`) are intentionally absent — supply them via
  * `slotRenderers`.
+ *
+ * Each ships its own `skeleton` beside its `render`, so a widget's loading
+ * state is drawn by the same thing that draws its content.
  */
 export declare const defaultSlotRenderers: SlotRenderers;
 
+/**
+ * What a slot draws while loading when its visualization brings no skeleton of
+ * its own — an unregistered one, or a bespoke renderer passed as a bare
+ * function. Deliberately shapeless: one bar per expected item.
+ */
+export declare const defaultSlotSkeleton: SlotSkeletonRenderer;
+
 declare const defaultTranslations: {
     readonly common: {
         readonly selectPlaceholder: "Select";
@@ -7922,6 +7939,14 @@ export declare interface HomeRenderCtx {
     isLastSlot?: boolean;
 }
 
+/**
+ * The ctx a SKELETON is drawn with: the render ctx plus how many placeholder
+ * items to draw — the slot's `expectedItemsCount`, already defaulted.
+ */
+export declare type HomeSkeletonCtx = HomeRenderCtx & {
+    expectedItemsCount: number;
+};
+
 /**
  * Builds a slot with its params CHECKED against its visualization.
  * `HomeWidgetSlot`'s `params` is `unknown` (bespoke slots need it to be), so a
@@ -7929,7 +7954,7 @@ export declare interface HomeRenderCtx {
  * the built-in vocabulary (and {@link listSlot} for `list` slots), keeping
  * literals for bespoke visualizations.
  */
-export declare const homeSlot: <V extends keyof HomeSlotParamsMap>(visualization: V, params: HomeSlotParamsMap[V]) => HomeWidgetSlot;
+export declare const homeSlot: <V extends keyof HomeSlotParamsMap>(visualization: V, params: HomeSlotParamsMap[V], options?: SlotOptions) => HomeWidgetSlot;
 
 /** The built-in slot vocabulary: each visualization and its params shape. */
 export declare interface HomeSlotParamsMap {
@@ -7974,12 +7999,24 @@ export declare type HomeWidgetItem = HomeWidgetChrome & {
      */
     hasUpdates?: boolean;
     slots: HomeWidgetSlot[];
+    /**
+     * The widget is waiting on its data: every slot draws its skeleton instead of
+     * its content (see `SlotWidget`'s `loading`).
+     */
+    loading?: boolean;
 };
 
 /** One slot of a widget: a visualization tag + its params (opaque to the layout). */
 export declare interface HomeWidgetSlot {
     visualization: string;
     params: unknown;
+    /**
+     * How many items this slot expects to hold — the number of PLACEHOLDER items
+     * its skeleton draws while the widget is `loading`, so the loading card is
+     * about as tall as the one that replaces it. Defaults to
+     * {@link DEFAULT_EXPECTED_ITEMS_COUNT}.
+     */
+    expectedItemsCount?: number;
 }
 
 declare type HTMLString = string;
@@ -8535,7 +8572,7 @@ export declare interface ListSchema {
  * CHECKED against it — a `left: "person"` slot only takes person data, a
  * `clickBehavior: "link"` slot demands an `href` on every row.
  */
-export declare const listSlot: <const S extends ListSchema>(schema: S, items: Array<ListItem<S>>) => HomeWidgetSlot;
+export declare const listSlot: <const S extends ListSchema>(schema: S, items: Array<ListItem<S>>, options?: SlotOptions) => HomeWidgetSlot;
 
 declare type ListTextData<S extends ListSchema> = {
     title: string;
@@ -10339,6 +10376,12 @@ declare type RequisitionProfile = {
 
 export declare type ResolvedRecordType<R> = R extends RecordType ? R : RecordType;
 
+/** A renderer entry in its full form — a bare function is just its `render`. */
+export declare const resolveSlotRenderer: (entry: SlotRendererEntry | undefined) => {
+    render: SlotRenderer;
+    skeleton?: SlotSkeletonRenderer;
+} | undefined;
+
 /**
  * Header for a resource detail page: avatar, title, description, status,
  * metadata and its primary, secondary and overflow actions.
@@ -11055,10 +11098,28 @@ declare const skeletonVariants: (props?: ({
  */
 export declare const SLOT_ROW_BLEED = "-m-2";
 
+/**
+ * Marks ONE placeholder item, whatever the visualization draws as an item — a
+ * list row, an event, an indicator. `expectedItemsCount` of these appear.
+ */
+export declare const SLOT_SKELETON_ITEM_TESTID = "slot-skeleton-item";
+
+/** What a slot carries beyond its params. Taken by both slot builders. */
+export declare type SlotOptions = Pick<HomeWidgetSlot, "expectedItemsCount">;
+
 /** Draws ONE slot from its params. Keyed by `visualization` in a renderer map. */
 export declare type SlotRenderer<P = unknown> = (params: P, ctx: HomeRenderCtx) => ReactNode;
 
-export declare type SlotRenderers = Record<string, SlotRenderer>;
+/**
+ * How a visualization is drawn: the render function on its own, or that
+ * function PAIRED with the skeleton to draw while the slot loads.
+ */
+export declare type SlotRendererEntry<P = unknown> = SlotRenderer<P> | {
+    render: SlotRenderer<P>;
+    skeleton?: SlotSkeletonRenderer<P>;
+};
+
+export declare type SlotRenderers = Record<string, SlotRendererEntry>;
 
 /**
  * The bleed a row-based slot applies to itself: `SLOT_ROW_BLEED` with its
@@ -11068,6 +11129,14 @@ export declare type SlotRenderers = Record<string, SlotRenderer>;
  */
 export declare const slotRowBleed: (ctx: HomeRenderCtx) => string;
 
+/**
+ * Draws the slot's PLACEHOLDER, before its data lands. It gets the same params
+ * the renderer will get — a loading slot still carries its static config (a
+ * `list`'s schema, say), just no items — so the placeholder can be shaped like
+ * what is coming.
+ */
+export declare type SlotSkeletonRenderer<P = unknown> = (params: P, ctx: HomeSkeletonCtx) => ReactNode;
+
 /**
  * Type helper to extract keys from a SortingsDefinition
  */
@@ -12621,9 +12690,16 @@ export declare interface WidgetProps {
         info?: string;
         canBeBlurred?: boolean;
         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.
+             */
             title: string;
             url?: string;
             onClick?: () => void;
+            /** Defaults to the external-link glyph. */
             icon?: IconType;
         };
         count?: number;
@@ -12849,9 +12925,11 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        fontSize: {
-            setFontSize: (fontSize: string) => ReturnType;
-            unsetFontSize: () => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number, options?: {
+                placeholder?: string;
+            }) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }
@@ -12859,11 +12937,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number, options?: {
-                placeholder?: string;
-            }) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
+        fontSize: {
+            setFontSize: (fontSize: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
         };
     }
 }