@pablo2410/shared-ui 0.20.0 → 0.22.0

package/dist/tour/index.d.ts

@@ -11,6 +11,26 @@ import { ReactNode } from 'react';
  * and content-authored separately before it gets an engine.
  */
 type TourStepKind = "intro" | "service" | "outro";
+/**
+ * Where a "service"-kind step should highlight a live element on the page,
+ * instead of rendering as a centered modal. Spotlighting is a rendering mode
+ * of a service step, not a distinct step kind — intro/outro never spotlight
+ * anything, and a service step authored without this still renders as the
+ * original centered modal.
+ *
+ * Deliberately same-origin only: the consumer's own DOM must contain an
+ * element carrying `data-tour-target="<selector>"`. A cross-origin tour (a
+ * subdomain spotlighting its own features) mints its own selector values —
+ * this type doesn't know or care which app is consuming it.
+ */
+interface TourSpotlightTarget {
+    /** Matches a `data-tour-target` attribute value in the consumer's DOM. */
+    selector: string;
+    /** Where to place the explanation panel relative to the highlighted
+     *  element. "auto" (default) picks based on available viewport space,
+     *  falling back bottom -> top -> right -> left. */
+    placement?: "top" | "bottom" | "left" | "right" | "auto";
+}
 interface TourStep {
     /** Stable id — used for progress persistence and analytics, not display. */
     id: string;
@@ -20,8 +40,17 @@ interface TourStep {
     /** Scripted fallback narration — always renders first; an AI narration
      *  pass (via ai.askOpi) may replace it once it resolves. Never blocks. */
     fallbackText: string;
-    /** 2-4 bullets shown under the narration. Empty for intro/outro steps. */
+    /** 2-4 bullets shown under the narration. Empty for intro/outro steps.
+     *  Superseded by `features` when both are present — kept for back-compat
+     *  with any step that hasn't been upgraded to the richer shape. */
     highlights?: string[];
+    /** Named feature call-outs, richer than a flat bullet — rendered instead
+     *  of `highlights` when present. Each `name` is also the natural spotlight
+     *  target label a later in-app tour (inside the service itself) can reuse. */
+    features?: {
+        name: string;
+        detail: string;
+    }[];
     /** The one action this step offers, if any. */
     action?: {
         label: string;
@@ -31,6 +60,9 @@ interface TourStep {
     };
     /** Which catalog service slug this step is about, for narration context / readiness lookups. Absent for intro/outro. */
     serviceSlug?: string;
+    /** Highlight a live element on the page instead of a centered modal. See
+     *  TourSpotlightTarget's own doc comment. Absent = today's centered modal. */
+    spotlight?: TourSpotlightTarget;
 }
 type TourStatus = "unseen" | "in-progress" | "done" | "dismissed";
 interface TourProgress {
@@ -69,12 +101,25 @@ interface TourShellProps {
     skin?: TourShellSkin;
     /** Orb / avatar mark shown in the header — pass OpiOrb from the consumer. */
     orb?: ReactNode;
+    /**
+     * Fires when the user activates the spotlighted element itself (a
+     * document-level capture-phase listener scoped to the resolved target —
+     * see useSpotlight.ts), alongside — never instead of — whatever the
+     * consumer's own element does on click. Only meaningful when the current
+     * step has `spotlight` and a target was found; ignored otherwise. Opt-in
+     * per step via the consumer wiring it up, not a built-in auto-advance —
+     * a later in-app spotlight (inside a subdomain) may want "just look
+     * here," no navigation expected.
+     */
+    onSpotlightTargetActivated?: () => void;
 }
 /**
- * Full-viewport dismissible overlay with a centered panel. Esc and the
- * backdrop both dismiss; focus is trapped to the panel while open.
+ * Full-viewport dismissible overlay. Esc always dismisses. In centered
+ * mode, clicking the backdrop dismisses too; in spotlight mode, each of the
+ * four backdrop segments independently dismisses on click, same behavior,
+ * just split across four elements instead of one.
  */
-declare function TourShell({ step, index, total, isFirst, isLast, onNext, onBack, onDismiss, narration, narrationPending, children, skin, orb, }: TourShellProps): React.JSX.Element;
+declare function TourShell({ step, index, total, isFirst, isLast, onNext, onBack, onDismiss, narration, narrationPending, children, skin, orb, onSpotlightTargetActivated, }: TourShellProps): React.JSX.Element;
 
 interface UseTourOptions {
     /** Called whenever the current step changes (not on initial mount). */
@@ -99,4 +144,68 @@ interface UseTourResult {
 }
 declare function useTour(steps: TourStep[], opts?: UseTourOptions): UseTourResult;
 
-export { type TourProgress, TourShell, type TourShellProps, type TourShellSkin, type TourStatus, type TourStep, type TourStepKind, type UseTourOptions, type UseTourResult, useTour };
+/**
+ * Pure geometry behind the spotlight rendering mode — no React, no DOM
+ * access, just numbers in and numbers out. Factored out so it's testable
+ * without jsdom (this package has none — see tourMachine.ts for the same
+ * split/precedent on the step-index state machine).
+ *
+ * TourShell is the consumer: given a target element's measured rect (from
+ * useSpotlight.ts) and the current viewport size, it needs to know (a) the
+ * four backdrop-frame rectangles that surround the target without ever
+ * covering it, and (b) where to place the explanation panel so it doesn't
+ * overflow the viewport, honoring a preferred placement when there's room.
+ */
+interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+type Placement = "top" | "bottom" | "left" | "right" | "auto";
+/** The four backdrop segments that frame a target rect without covering it.
+ *  Each is a plain rect in viewport (fixed-position) coordinates. A segment
+ *  with zero width or height (e.g. the target touches a viewport edge) is
+ *  still returned — the caller can skip rendering a degenerate rect, but
+ *  the geometry itself doesn't special-case it. */
+interface SpotlightFrame {
+    top: Rect;
+    bottom: Rect;
+    left: Rect;
+    right: Rect;
+}
+/** Frames `target` within a `viewport` sized 0,0 to width,height. */
+declare function computeSpotlightFrame(target: Rect, viewport: Size): SpotlightFrame;
+type ConcretePlacement = Exclude<Placement, "auto">;
+interface PanelPosition {
+    top: number;
+    left: number;
+    placement: ConcretePlacement;
+}
+/**
+ * Where to place a panel of `panelSize` next to `target`, preferring
+ * `placement` but falling back through the other three sides (then finally
+ * clamping into the viewport) if the preferred side doesn't have room.
+ */
+declare function computePanelPosition(target: Rect, panelSize: Size, viewport: Size, placement?: Placement): PanelPosition;
+
+interface UseSpotlightResult {
+    /** The target's current viewport-relative rect, or null while unresolved. */
+    rect: Rect | null;
+    /** False if no element in the DOM currently carries this selector —
+     *  callers must fall back to the non-spotlight rendering path, never
+     *  throw or render a spotlight around nothing. */
+    found: boolean;
+}
+/**
+ * @param selector The `data-tour-target` attribute value to look for
+ *   (e.g. "service-card-policy-deployment"). Pass `null` to disable
+ *   resolution entirely (e.g. the current step has no spotlight).
+ */
+declare function useSpotlight(selector: string | null): UseSpotlightResult;
+
+export { type PanelPosition, type Placement, type Rect, type Size, type SpotlightFrame, type TourProgress, TourShell, type TourShellProps, type TourShellSkin, type TourSpotlightTarget, type TourStatus, type TourStep, type TourStepKind, type UseSpotlightResult, type UseTourOptions, type UseTourResult, computePanelPosition, computeSpotlightFrame, useSpotlight, useTour };