@factorialco/f0-react 6.85.0 → 6.86.1

package/dist/experimental.d.ts

@@ -791,6 +791,15 @@ declare type AlertVariant = (typeof alertVariantOptions)[number];
 
 declare const alertVariantOptions: readonly ["info", "warning", "critical", "neutral", "positive"];
 
+/**
+ * The attribute a guidance's `anchor()` writes, and the one its steps are
+ * resolved through. A data attribute rather than the `id` attribute: an id is
+ * the page's own namespace — one per document, handed out by whatever renders
+ * the element — and a walkthrough that claimed ids would collide with the app's
+ * own the first time two of them named the same thing.
+ */
+declare const ANCHOR_ATTRIBUTE = "data-f0-coachmark";
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
@@ -2839,17 +2848,33 @@ export declare type CoachmarkAction = {
     onClick?: () => void;
 };
 
-declare type CoachmarkBase = CoachmarkPlacement & {
+declare type CoachmarkBase = CoachmarkPlacement & CoachmarkFocus & {
     /**
      * 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;
+    /**
+     * HOW IT ENDED, IN ONE PLACE — reached the end, left part-way through, or
+     * pressed past until it gave up, and how far the reader got either way. The
+     * callback to reach for when tracking a walkthrough: every ending comes
+     * through here exactly once, so a funnel is one event carrying a `reason`
+     * rather than two callbacks to join up afterwards.
+     *
+     * NOT called when the app itself closes the coachmark (`coachmarks.close`, a
+     * guidance's `stop()`, the page unmounting): nobody ended it, so there is no
+     * outcome to report.
+     */
+    onEnd?: (end: CoachmarkEnd) => void;
     /**
      * 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.
+     *
+     * Also fires when a walkthrough gives up after too many presses on the
+     * dimmed page, which is a dismissal by any other name. `onEnd` is what tells
+     * those two apart.
      */
     onDismiss?: () => void;
     /**
@@ -2857,6 +2882,26 @@ declare type CoachmarkBase = CoachmarkPlacement & {
      * — the coachmark closes itself either way.
      */
     onComplete?: () => void;
+    /**
+     * SPOTLIGHT THE TARGET: dims the whole page except the element this step
+     * points at, and swallows every press on the page while the coachmark is up
+     * (see `skipAfterOutsideClicks` for how a user who keeps pressing gets out).
+     *
+     * Off by default — one coachmark pointing something out should not take the
+     * page hostage. Turn it on for a walkthrough that has to be followed in order.
+     */
+    overlay?: boolean;
+    /**
+     * HOW MANY PRESSES ON THE DIMMED PAGE END THE COACHMARK. The panel wiggles at
+     * each one to say the press went nowhere, and gives up at this many: a user
+     * pressing outside over and over is telling us they want out, and the way out
+     * cannot be the button they are ignoring. Reported to `onDismiss` like any
+     * other abandonment. Defaults to 5; `0` never gives up.
+     *
+     * Only has an effect alongside `overlay` — without the shield there are no
+     * presses to count, because they reach the page.
+     */
+    skipAfterOutsideClicks?: number;
 };
 
 declare type CoachmarkContent = {
@@ -2868,6 +2913,144 @@ declare type CoachmarkContent = {
     action?: CoachmarkAction;
 };
 
+/** What `onEnd` is told. */
+export declare type CoachmarkEnd = {
+    reason: CoachmarkEndReason;
+    /**
+     * The step it ended on, 1-based — how far the reader got. `0` when it never
+     * opened (`unavailable`).
+     */
+    step: number;
+    /**
+     * How many steps the reader was actually offered. Not necessarily how many
+     * were declared: a guidance leaves out the steps whose element was not there.
+     */
+    totalSteps: number;
+    /**
+     * Presses on the dimmed page over the whole coachmark — the wiggles. A tour
+     * that completed with six of these was fought with; one that completed with
+     * none was followed. Always `0` without `overlay`, which has no shield to
+     * press.
+     */
+    outsidePresses: number;
+};
+
+/**
+ * HOW A COACHMARK ENDED. One value per way out, so a funnel can be read off it
+ * without joining two callbacks together:
+ *
+ * - `completed` — the action on the last step. The reader saw the whole thing.
+ * - `dismissed` — the close button or Escape, before the last step. They left
+ *   part-way through, and `step` says where.
+ * - `skipped` — it gave up after `skipAfterOutsideClicks` presses on the dimmed
+ *   page. Not the same as dismissing: the reader never used the way out they
+ *   were offered, they pressed past it until it went away.
+ * - `unavailable` — it never opened, because nothing it points at was on the
+ *   page (only `defineStepByStepCoachmarkGuidance` reports this). The reason a
+ *   funnel can be missing readers who were never shown anything.
+ */
+export declare type CoachmarkEndReason = "completed" | "dismissed" | "skipped" | "unavailable";
+
+declare type CoachmarkFocus = {
+    /**
+     * PUT THE CARET WHERE THE STEP IS POINTING. Focus goes to the target — or to
+     * the first field inside it — instead of to the panel, so the element the
+     * coachmark is explaining lights up the way it does when the reader lands on
+     * it themselves: a composer with its cursor in it and its own focus glow,
+     * rather than a box being described.
+     *
+     * OFF BY DEFAULT, and worth being deliberate about. The panel takes focus
+     * precisely so a screen reader reads the step out and so Enter cannot fire
+     * the action unread; handing focus to a field instead trades that away —
+     * the step is no longer announced, and typing goes into the page. Use it on a
+     * step whose whole point is the field (a composer, a search box), and leave
+     * every other step to the panel.
+     *
+     * Escape still closes the coachmark from anywhere, and the action button is
+     * still one Tab away.
+     */
+    focusTarget?: boolean;
+};
+
+export declare type CoachmarkGuidance<TElement extends string> = {
+    /** The id every `start()` opens under, and the one `stop()` closes. */
+    id: CoachmarkId;
+    /**
+     * MARKS AN ELEMENT AS A STEP'S TARGET. Spread onto the element (or onto any
+     * component that forwards unknown props to its DOM node):
+     *
+     * `<section {...guidance.anchor("needs-you")}>`
+     *
+     * Only names declared by a step type-check, so a renamed step breaks at the
+     * anchor rather than at run time — where a missing target is a coachmark that
+     * silently waits for an element that is never coming.
+     */
+    anchor: (element: TElement) => Record<typeof ANCHOR_ATTRIBUTE, TElement>;
+    /** The selector `anchor(element)` is found by. For tests and edge cases. */
+    selector: (element: TElement) => string;
+    /**
+     * Start the walkthrough — once the elements it points at are actually on the
+     * page (see `lookForTargetsMs`). Steps whose element never turns up are left
+     * out, and a walkthrough with nothing left to point at never opens at all.
+     * Returns the id it will open under, whether it has opened yet or not.
+     */
+    start: () => CoachmarkId;
+    /** End it wherever it is. Reports nothing: nobody dismissed it. */
+    stop: () => void;
+};
+
+export declare type CoachmarkGuidanceOptions<TElement extends string> = {
+    /**
+     * Stable identity, so starting the same guidance twice shows ONE walkthrough.
+     * Defaults to a generated id.
+     */
+    id?: CoachmarkId;
+    /** The walkthrough, in order. */
+    steps: readonly CoachmarkGuidanceStep<TElement>[];
+    /**
+     * Spotlight each step's element and shield the page from the pointer.
+     * Defaults to `true` — a walkthrough is a sequence, and a page you can act on
+     * mid-sequence is a sequence the user has already left.
+     */
+    overlay?: boolean;
+    /** Presses on the dimmed page that end the walkthrough. Defaults to 5. */
+    skipAfterOutsideClicks?: number;
+    /**
+     * HOW LONG `start()` KEEPS LOOKING for the steps whose elements are not on the
+     * page yet, before running the walkthrough without them. Defaults to 2000ms.
+     *
+     * A walkthrough is started on mount, and the things it walks arrive over the
+     * next few hundred milliseconds — a rail that is still measuring itself, a
+     * widget waiting on its data. Opening on the first frame would drop those
+     * steps; waiting forever on one that is genuinely absent (a control this user
+     * has no permission for) would mean no walkthrough at all.
+     */
+    lookForTargetsMs?: number;
+    /**
+     * HOW IT ENDED, IN ONE PLACE: finished, left part-way through, pressed past
+     * until it gave up — or never opened at all, because nothing it points at was
+     * on the page. One event with a `reason`, which is what a funnel wants.
+     */
+    onEnd?: (end: CoachmarkEnd) => void;
+    /** Abandoned: closed, escaped, or skipped by pressing past it. */
+    onDismiss?: () => void;
+    /** Finished: the action on the last step. */
+    onComplete?: () => void;
+};
+
+/**
+ * One step of a walkthrough. It points either at a NAME the guidance knows —
+ * marked on the element with `anchor()` — or, for an element you cannot put
+ * props on (something a library renders), straight at a selector or an element.
+ */
+export declare type CoachmarkGuidanceStep<TElement extends string> = Omit<CoachmarkStep, "targetElement"> & ({
+    element: TElement;
+    targetElement?: never;
+} | {
+    element?: never;
+    targetElement: CoachmarkTarget;
+});
+
 export declare type CoachmarkId = string;
 
 /**
@@ -2977,15 +3160,25 @@ export declare type CoachmarkSingleOptions = CoachmarkBase & CoachmarkContent &
  * its own placement; anything it leaves out falls back to the value passed
  * alongside `steps`.
  */
-export declare type CoachmarkStep = CoachmarkContent & CoachmarkPlacement & {
+export declare type CoachmarkStep = CoachmarkContent & CoachmarkPlacement & CoachmarkFocus & {
     /** 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.
+ * What the coachmark points at: ANY CSS SELECTOR, or the element itself.
+ *
+ * An id (`"#filters-button"`), a class (`".js-filters"`), an attribute
+ * (`'[data-add-widget="right"]'`), or anything else `querySelector` takes — the
+ * string is handed straight to the DOM, so the choice is about what the page
+ * can promise to keep stable, not about what this accepts. It must match
+ * exactly ONE element: a selector that matches several anchors to the first and
+ * warns in development, because a coachmark pointing at "one of these six
+ * cards" is pointing at nothing in particular.
+ *
+ * A selector is re-resolved while the coachmark is queued, so it may point at
+ * something that mounts later. An ELEMENT is not re-resolved (there is nothing
+ * to re-run), so one that unmounts takes its coachmark off screen with it.
  */
 export declare type CoachmarkTarget = string | HTMLElement;
 
@@ -5235,6 +5428,48 @@ declare const defaultTranslations: {
     };
 };
 
+/**
+ * A STEP-BY-STEP WALKTHROUGH OF A PAGE, declared in one place.
+ *
+ * `coachmarks.open({ steps })` already shows steps one at a time; what it takes
+ * is a CSS selector per step, which means every walkthrough invents its own
+ * convention for marking the elements it walks — and a selector written against
+ * someone else's markup breaks the next time that markup is refactored, without
+ * a single type error to say so.
+ *
+ * This closes that loop: the steps name their targets, `anchor()` marks them,
+ * and the names are a union the compiler holds both sides to. The walkthrough
+ * also arrives with the manners a walkthrough needs — the page dimmed to the
+ * step's element, the pointer shielded, and a way out for the user who keeps
+ * pressing past it — because those are properties of walking someone through a
+ * page rather than of one coachmark.
+ *
+ * @example
+ * const tour = defineStepByStepCoachmarkGuidance({
+ *   id: "home-tour",
+ *   steps: [
+ *     { element: "composer", title: "Let One do it for you", side: "bottom" },
+ *     { element: "needs-you", title: "What needs you", side: "right" },
+ *     // Something f0 renders: point at it directly.
+ *     { targetElement: '[data-add-widget="right"]', title: "Add a widget" },
+ *   ],
+ *   // Finished, dropped out at step N, pressed past it, or never shown.
+ *   onEnd: ({ reason, step, totalSteps }) =>
+ *     track("home-tour-ended", { reason, step, totalSteps }),
+ * })
+ *
+ * // In the page
+ * <div {...tour.anchor("composer")}>…</div>
+ * <section {...tour.anchor("needs-you")}>…</section>
+ *
+ * // Whenever it should run
+ * useEffect(() => {
+ *   tour.start()
+ *   return () => tour.stop()
+ * }, [tour])
+ */
+export declare const defineStepByStepCoachmarkGuidance: <const TElement extends string>(options: CoachmarkGuidanceOptions<TElement>) => CoachmarkGuidance<TElement>;
+
 export declare interface DeleteBlockNotesTextEditorPageDocumentPatch {
     type: "delete_block";
     targetId: string;
@@ -15714,18 +15949,6 @@ declare module "@tiptap/core" {
 }
 
 
-declare module "@tiptap/core" {
-    interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number, options?: {
-                placeholder?: string;
-            }) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
-        };
-    }
-}
-
-
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         fontSize: {
@@ -15747,6 +15970,18 @@ declare module "@tiptap/core" {
 }
 
 
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number, options?: {
+                placeholder?: string;
+            }) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
+        };
+    }
+}
+
+
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         moodTracker: {