@factorialco/f0-react 6.13.0 → 6.14.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 {
@@ -3542,6 +3706,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";
@@ -9727,6 +9895,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;
@@ -12667,11 +12839,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 +12849,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        aiBlock: {
-            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
-            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
+        fontSize: {
+            setFontSize: (fontSize: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
         };
     }
 }
@@ -12689,9 +12859,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;
         };
     }
 }