@factorialco/f0-react 6.13.0 → 6.15.0

package/dist/experimental.d.ts

@@ -78,6 +78,7 @@ import { PersonCellValue } from './types/person';
 import { PersonCellValue as PersonCellValue_2 } from './experimental';
 import { PieChartProps } from './PieChart';
 import { PieChartProps as PieChartProps_2 } from './experimental';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
 import { PopoverProps } from '@radix-ui/react-popover';
 import { ProgressBarCellValue } from './types/progressBar';
 import { ProgressBarCellValue as ProgressBarCellValue_2 } from './experimental';
@@ -2399,6 +2400,169 @@ declare interface ClockInGraphProps {
 
 declare type ClockInStatus = "clocked-in" | "break" | "clocked-out";
 
+/**
+ * The single call to action at the bottom of the panel. Both fields are
+ * optional: the coachmark always advances to the next step (or closes on the
+ * last one) when the button is pressed, so `onClick` is only for side effects
+ * and `label` only for overriding the default wording.
+ */
+export declare type CoachmarkAction = {
+    /** Defaults to `Next` on every step but the last, `Got it` on the last. */
+    label?: string;
+    /** Extra side effect. Advancing and closing happen either way. */
+    onClick?: () => void;
+};
+
+declare type CoachmarkBase = CoachmarkPlacement & {
+    /**
+     * Stable identity. Opening again with the same id replaces that coachmark
+     * instead of queueing a second one, so an effect that runs twice shows one
+     * coachmark. Defaults to a generated id.
+     */
+    id?: CoachmarkId;
+    /**
+     * Called when the user closes the coachmark with the close button or Escape,
+     * before the last step is reached. For tracking only — the coachmark closes
+     * itself either way.
+     */
+    onDismiss?: () => void;
+    /**
+     * Called when the user presses the action on the last step. For tracking only
+     * — the coachmark closes itself either way.
+     */
+    onComplete?: () => void;
+};
+
+declare type CoachmarkContent = {
+    /** Headline. Also the accessible name of the panel. */
+    title: string;
+    /** Supporting copy under the title. */
+    description?: string;
+    /** The single call to action, rendered at the bottom right. */
+    action?: CoachmarkAction;
+};
+
+export declare type CoachmarkId = string;
+
+/**
+ * What `coachmarks.open` accepts: either one coachmark, or a sequence of steps
+ * shown one at a time. The two shapes are mutually exclusive.
+ */
+export declare type CoachmarkOptions = CoachmarkSingleOptions | CoachmarkSequenceOptions;
+
+/**
+ * Where the panel sits relative to its target. `side` is a preference: the
+ * panel flips and shifts on its own when it would overflow the viewport.
+ */
+declare type CoachmarkPlacement = {
+    /** Renders a triangle pointing at the target. Defaults to `true`. */
+    arrow?: boolean;
+    /** Preferred side of the target. Defaults to `"bottom"`. */
+    side?: PopoverContentProps["side"];
+    /** Alignment along the target's edge. Defaults to `"center"`. */
+    align?: PopoverContentProps["align"];
+    /** Distance in pixels between the target and the panel. */
+    sideOffset?: number;
+};
+
+/**
+ * Renders the coachmark at the head of the queue. Mounted by `F0Provider`, so
+ * `coachmarks.open` works from anywhere without a hook or a wrapper component.
+ */
+export declare const CoachmarkProvider: ({ children, portalTarget, }: CoachmarkProviderProps) => JSX_2.Element;
+
+declare type CoachmarkProviderProps = {
+    children: React.ReactNode;
+    /**
+     * Selector for the element the panel is portalled into. Defaults to the
+     * top-level overlay root, which keeps the coachmark above app content (the
+     * ApplicationFrame's `isolate`, the fullscreen AI chat) while staying inside
+     * `#f0-layout` so design tokens and the theme class still apply. Falls back to
+     * `document.body` when the element is absent.
+     */
+    portalTarget?: string;
+};
+
+/**
+ * Imperative API for coachmarks: a panel anchored to an element, pointing out a
+ * feature the user has not discovered yet. Can be called from anywhere — no hook
+ * required — as long as `<F0Provider>` (which mounts `CoachmarkProvider`) is in
+ * the tree.
+ *
+ * There is no `open` prop and no component to render: the coachmark closes
+ * itself when the user acknowledges it, and only one is ever on screen — a
+ * second `open` waits its turn.
+ *
+ * @example
+ * import { coachmarks } from "@factorialco/f0-react/experimental"
+ *
+ * coachmarks.open({
+ *   id: "smart-filters",
+ *   targetElement: "#filters-button",
+ *   title: "Filters got smarter",
+ *   description: "Stack filters, then save the combination as a view.",
+ *   action: { label: "Learn more", onClick: () => openDocs() },
+ * })
+ *
+ * @example A walkthrough, one step at a time
+ * coachmarks.open({
+ *   steps: [
+ *     { targetElement: "#filters-button", title: "Start with a filter" },
+ *     { targetElement: "#save-view", title: "Then save it as a view" },
+ *   ],
+ *   onComplete: () => track("tour-finished"),
+ * })
+ */
+export declare const coachmarks: {
+    /**
+     * Show a coachmark, or queue it behind the one already on screen.
+     * @param options One coachmark, or a sequence of `steps`
+     * @returns The id of the coachmark (pass it to `coachmarks.close`)
+     */
+    open: (options: CoachmarkOptions) => CoachmarkId;
+    /**
+     * Remove a coachmark by id, whether it is on screen or still queued. For
+     * closing it programmatically — the user does not need this.
+     * @param id The id returned by `coachmarks.open`
+     */
+    close: (id: CoachmarkId) => void;
+    /** Remove every coachmark, on screen and queued. */
+    closeAll: () => void;
+};
+
+/** A walkthrough: several steps, shown one at a time in order. */
+export declare type CoachmarkSequenceOptions = CoachmarkBase & {
+    /** Shared fallback target for steps that do not name their own. */
+    targetElement?: CoachmarkTarget;
+    steps: CoachmarkStep[];
+    title?: never;
+    description?: never;
+    action?: never;
+};
+
+/** One coachmark: its own copy, anchored to one element. */
+export declare type CoachmarkSingleOptions = CoachmarkBase & CoachmarkContent & {
+    targetElement: CoachmarkTarget;
+    steps?: never;
+};
+
+/**
+ * One step of a walkthrough. Each step can point at its own element and carry
+ * its own placement; anything it leaves out falls back to the value passed
+ * alongside `steps`.
+ */
+export declare type CoachmarkStep = CoachmarkContent & CoachmarkPlacement & {
+    /** Falls back to the `targetElement` passed alongside `steps`. */
+    targetElement?: CoachmarkTarget;
+};
+
+/**
+ * What the coachmark points at: a CSS selector that must match exactly one
+ * element, or the element itself. A selector is re-resolved while the coachmark
+ * is queued, so it may point at something that mounts later.
+ */
+export declare type CoachmarkTarget = string | HTMLElement;
+
 declare type ColId = string;
 
 declare interface CollectionComputation {
@@ -3186,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";
@@ -3542,6 +3723,10 @@ declare const defaultTranslations: {
         readonly join: "Join";
         readonly summary: "Summary";
     };
+    readonly coachmark: {
+        readonly next: "Next";
+        readonly done: "Got it";
+    };
     readonly actions: {
         readonly add: "Add";
         readonly edit: "Edit";
@@ -7754,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
@@ -7761,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 {
@@ -7806,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;
@@ -8367,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;
@@ -9727,6 +9932,10 @@ declare interface PieComputation {
     limit?: number;
 }
 
+declare type PopoverContentProps = React_2.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> & {
+    container?: HTMLElement | null;
+};
+
 declare type PostDescriptionProps = {
     content: HTMLString;
     collapsed?: boolean;
@@ -10167,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.
@@ -10883,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
@@ -10896,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
  */
@@ -12449,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;
@@ -12667,11 +12915,9 @@ declare namespace Calendar {
 
 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;
         };
     }
 }
@@ -12679,9 +12925,11 @@ declare module "@tiptap/core" {
 
 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;
         };
     }
 }