@nubisco/ui 2.0.1 → 2.1.0

package/README.md

@@ -210,6 +210,13 @@ Most component libraries impose styling opinions that are hard to override. Nubi
 | :-------- | :-------------------------------------------------------- |
 | `NbTabs`  | Tab bar with optional panels, line and contained variants |
 
+### Onboarding
+
+| Component       | Description                                                                       |
+| :-------------- | :-------------------------------------------------------------------------------- |
+| `NbInfoHint`    | Discreet info affordance revealing a description on hover, focus or tap           |
+| `NbWalkthrough` | Guided product tour: spotlight, coach-mark popover, versioned per-user completion |
+
 ---
 
 ## Grid System

package/dist/components/InfoHint.d.ts

@@ -0,0 +1,47 @@
+import type { TAnchorSide } from '../utils/anchorPosition.helper'
+
+/**
+ * Side the hint popover prefers. It is a preference, not a guarantee: the
+ * popover flips and clamps itself to stay inside the viewport.
+ */
+type TInfoHintPlacement = `${TAnchorSide}`
+
+interface IInfoHintProps {
+  /**
+   * Plain-text description. Ignored when the default slot is used, which is
+   * the escape hatch for rich content (lists, formulas, inline code).
+   */
+  text?: string
+  /** Optional bold heading above the body. */
+  title?: string
+  /**
+   * Glossary / documentation identifier for the concept being explained. The
+   * library never resolves it — it is echoed back on the `activate` event and
+   * mirrored to `data-term`, so an app can map it to a central glossary or
+   * deep-link into its docs without the component knowing anything about
+   * either.
+   */
+  term?: string
+  /** Preferred popover side. Flipped automatically when it does not fit. */
+  placement?: TInfoHintPlacement
+  /** Icon size in pixels, matching NbIcon's numeric `size`. */
+  size?: number
+  /** Any icon name NbIcon accepts. Defaults to the Phosphor `info` glyph. */
+  icon?: string
+  /**
+   * Accessible name for the trigger button. Override it when the hint sits
+   * next to an ambiguous value so screen-reader users hear what it explains,
+   * e.g. `label="About the archived status"`.
+   */
+  label?: string
+  /** Delay in ms before a hover opens the popover. */
+  openDelay?: number
+  /** Delay in ms before leaving the trigger closes the popover. */
+  closeDelay?: number
+  /** Teleport target for the popover. */
+  teleportTo?: string
+  /** Renders the icon inert and suppresses the popover. */
+  disabled?: boolean
+}
+
+export type { TInfoHintPlacement, IInfoHintProps }

package/dist/components/InfoHint.vue.d.ts

@@ -0,0 +1,41 @@
+import type { IInfoHintProps } from './InfoHint.d';
+declare function open(): void;
+declare function close(): void;
+declare var __VLS_12: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_12) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<IInfoHintProps, {
+    open: typeof open;
+    close: typeof close;
+    isOpen: import("vue").Ref<boolean, boolean>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    close: () => any;
+    open: () => any;
+    activate: (term: string | undefined) => any;
+}, string, import("vue").PublicProps, Readonly<IInfoHintProps> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onOpen?: (() => any) | undefined;
+    onActivate?: ((term: string | undefined) => any) | undefined;
+}>, {
+    size: number;
+    label: string;
+    title: string;
+    text: string;
+    icon: string;
+    disabled: boolean;
+    term: string;
+    placement: import("./InfoHint.d").TInfoHintPlacement;
+    openDelay: number;
+    closeDelay: number;
+    teleportTo: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+//# sourceMappingURL=InfoHint.vue.d.ts.map

package/dist/components/InfoHint.vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InfoHint.vue.d.ts","sourceRoot":"","sources":["../../src/components/InfoHint.vue"],"names":[],"mappings":"AA0bA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAyFlD,iBAAS,IAAI,SAWZ;AAED,iBAAS,KAAK,SAMb;AA+PD,QAAA,IAAI,QAAQ,IAAY,CAAE;AAC1B,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAQhD,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;6EAKd,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AAWzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}

package/dist/components/UserMenu.vue.d.ts

@@ -36,11 +36,11 @@ declare const __VLS_base: import("vue").DefineComponent<IUserMenuProps, {
     "onSign-out"?: (() => any) | undefined;
 }>, {
     disabled: boolean;
+    placement: import("./UserMenu.d").TUserMenuPlacement;
     accounts: IUserMenuAccount[];
     accountsUnknown: boolean;
     showAccountActions: boolean;
     showProfile: boolean;
-    placement: import("./UserMenu.d").TUserMenuPlacement;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/Walkthrough.d.ts

@@ -0,0 +1,156 @@
+import type { ComputedRef, Ref } from 'vue'
+import type { TAnchorSide } from '../utils/anchorPosition.helper'
+
+/**
+ * Preferred side for the step popover. `auto` lets the placement algorithm
+ * pick, which is the sane default for targets whose position depends on
+ * viewport size (a sidebar that collapses, a toolbar that wraps).
+ */
+type TWalkthroughPlacement = `${TAnchorSide}` | 'auto'
+
+/** How a run ended. Recorded alongside the version in storage. */
+type TWalkthroughOutcome = 'finish' | 'skip'
+
+/**
+ * Anything that can resolve to the element a step points at.
+ *
+ * A bare string is looked up as a tour-step id first (`v-nb-tour-step` /
+ * `data-nb-tour-step`) and only then as a CSS selector, so the stable-id
+ * convention wins over brittle structural selectors without needing a
+ * separate prop.
+ */
+type TWalkthroughTarget =
+  | string
+  | HTMLElement
+  | (() => HTMLElement | null | undefined)
+  | Ref<HTMLElement | null | undefined>
+
+interface IWalkthroughStep {
+  /**
+   * Element to spotlight. Omit it for an intro or outro step: the popover is
+   * then centred on the viewport with no cut-out.
+   */
+  target?: TWalkthroughTarget
+  title?: string
+  /** Plain-text body. The component's `step` slot overrides it for rich content. */
+  body?: string
+  placement?: TWalkthroughPlacement
+  /** Extra pixels of breathing room between the target and the cut-out edge. */
+  padding?: number
+  /** Optional stable identifier, echoed on `step-change` for analytics. */
+  id?: string
+}
+
+interface IWalkthrough {
+  /** Stable identifier for this tour. Used as the storage key. */
+  id: string
+  /**
+   * Bump when the tour's content changes materially. A user who completed
+   * version 1 is shown version 2 again; a user who completed version 2 is not.
+   */
+  version: number
+  steps: IWalkthroughStep[]
+}
+
+interface IWalkthroughRecord {
+  version: number
+  outcome: TWalkthroughOutcome
+  /** ISO-8601 timestamp. */
+  completedAt: string
+}
+
+/**
+ * Persistence seam. The default implementation is localStorage-backed; an app
+ * can hand in one that talks to its own API without changing a single call
+ * site, which is the point of keeping reads async-tolerant.
+ */
+interface IWalkthroughStorage {
+  get(
+    id: string,
+  ): IWalkthroughRecord | null | Promise<IWalkthroughRecord | null>
+  set(id: string, record: IWalkthroughRecord): void | Promise<void>
+  remove(id: string): void | Promise<void>
+}
+
+interface IWalkthroughOptions {
+  storage?: IWalkthroughStorage
+  /** Callbacks mirror the component's events, for imperative (non-template) use. */
+  onFinish?: (walkthrough: IWalkthrough) => void
+  onSkip?: (walkthrough: IWalkthrough, stepIndex: number) => void
+  onStepChange?: (step: IWalkthroughStep, index: number) => void
+}
+
+interface IWalkthroughController {
+  active: Ref<boolean>
+  stepIndex: Ref<number>
+  step: ComputedRef<IWalkthroughStep | undefined>
+  steps: ComputedRef<IWalkthroughStep[]>
+  stepCount: ComputedRef<number>
+  isFirst: ComputedRef<boolean>
+  isLast: ComputedRef<boolean>
+  walkthrough: ComputedRef<IWalkthrough>
+  /** Start at step 0 regardless of stored completion. */
+  start: () => void
+  /** Clear the stored record, then start. Use from a "replay the tour" menu item. */
+  restart: () => Promise<void>
+  next: () => void
+  back: () => void
+  goTo: (index: number) => void
+  /** End the run as completed and persist it. */
+  finish: () => Promise<void>
+  /** End the run as skipped and persist it. */
+  skip: () => Promise<void>
+  /** Start only when no record exists for the current version. */
+  maybeAutoStart: () => Promise<boolean>
+  /** True when a stored record covers the current version or newer. */
+  isCompleted: () => Promise<boolean>
+  /** Forget the stored record without starting. */
+  reset: () => Promise<void>
+}
+
+interface IWalkthroughLabels {
+  back: string
+  next: string
+  skip: string
+  done: string
+  /** Progress line. Receives the 1-based step number and the total. */
+  progress: (current: number, total: number) => string
+  /** Accessible name for the overlay dialog. */
+  dialog: string
+}
+
+interface IWalkthroughProps {
+  /** The tour definition. Required unless a `controller` is supplied. */
+  walkthrough?: IWalkthrough
+  /**
+   * A controller from `useWalkthrough()`. Pass one when the tour must be
+   * started from outside the template (a help menu, a router guard); omit it
+   * and the component creates its own.
+   */
+  controller?: IWalkthroughController
+  /** Run `maybeAutoStart()` on mount. Ignored when `controller` is provided. */
+  autoStart?: boolean
+  /** Storage adapter. Ignored when `controller` is provided. */
+  storage?: IWalkthroughStorage
+  /** Partial label overrides, for localisation. */
+  labels?: Partial<IWalkthroughLabels>
+  teleportTo?: string
+  /** Clicking the dimmed area skips the tour. Off by default: too easy to hit by accident. */
+  closeOnScrim?: boolean
+  /** Default cut-out padding, overridable per step. */
+  padding?: number
+}
+
+export type {
+  TWalkthroughPlacement,
+  TWalkthroughOutcome,
+  TWalkthroughTarget,
+  IWalkthroughStep,
+  IWalkthrough,
+  IWalkthroughRecord,
+  IWalkthroughStorage,
+  IWalkthroughOptions,
+  IWalkthroughController,
+  IWalkthroughLabels,
+  IWalkthroughProps,
+}

package/dist/components/Walkthrough.vue.d.ts

@@ -0,0 +1,66 @@
+import type { IWalkthrough, IWalkthroughLabels, IWalkthroughProps, IWalkthroughStep } from './Walkthrough.d';
+declare function onNext(): void;
+declare function onBack(): void;
+declare function handleFinish(): Promise<void>;
+declare function onSkip(): Promise<void>;
+declare var __VLS_7: {
+    step: IWalkthroughStep | undefined;
+    index: number;
+    total: number;
+}, __VLS_9: {
+    step: IWalkthroughStep | undefined;
+    index: number;
+    total: number;
+}, __VLS_11: {
+    step: IWalkthroughStep | undefined;
+    index: number;
+    total: number;
+    back: typeof onBack;
+    next: typeof onNext;
+    skip: typeof onSkip;
+};
+type __VLS_Slots = {} & {
+    header?: (props: typeof __VLS_7) => any;
+} & {
+    step?: (props: typeof __VLS_9) => any;
+} & {
+    actions?: (props: typeof __VLS_11) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<IWalkthroughProps, {
+    start: () => void;
+    restart: () => Promise<void>;
+    next: () => void;
+    back: () => void;
+    skip: typeof onSkip;
+    finish: typeof handleFinish;
+    goTo: (index: number) => void;
+    active: import("vue").Ref<boolean, boolean>;
+    stepIndex: import("vue").Ref<number, number>;
+    controller: import("./Walkthrough.d").IWalkthroughController;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    finish: (walkthrough: IWalkthrough) => any;
+    skip: (walkthrough: IWalkthrough, index: number) => any;
+    "step-change": (step: IWalkthroughStep, index: number) => any;
+}, string, import("vue").PublicProps, Readonly<IWalkthroughProps> & Readonly<{
+    onFinish?: ((walkthrough: IWalkthrough) => any) | undefined;
+    onSkip?: ((walkthrough: IWalkthrough, index: number) => any) | undefined;
+    "onStep-change"?: ((step: IWalkthroughStep, index: number) => any) | undefined;
+}>, {
+    autoStart: boolean;
+    storage: import("./Walkthrough.d").IWalkthroughStorage;
+    teleportTo: string;
+    labels: Partial<IWalkthroughLabels>;
+    walkthrough: IWalkthrough;
+    controller: import("./Walkthrough.d").IWalkthroughController;
+    closeOnScrim: boolean;
+    padding: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+//# sourceMappingURL=Walkthrough.vue.d.ts.map

package/dist/components/Walkthrough.vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Walkthrough.vue.d.ts","sourceRoot":"","sources":["../../src/components/Walkthrough.vue"],"names":[],"mappings":"AAyrBA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AAiRxB,iBAAS,MAAM,SAOd;AAED,iBAAS,MAAM,SAGd;AAED,iBAAe,YAAY,kBAI1B;AAED,iBAAe,MAAM,kBAKpB;AAkWD,QAAA,IAAI,OAAO;;;;CAAU,EAAE,OAAO;;;;CAAU,EAAE,QAAQ;;;;;;;CAAY,CAAE;AAChE,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GAC3C;IAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,GACzC;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAOhD,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EAKd,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AAWzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}

package/dist/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;;iBAoIf,GAAG;;AADlB,wBAMC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;;iBAwIf,GAAG;;AADlB,wBAMC"}

package/dist/composables/useReducedMotion.composable.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reactive `prefers-reduced-motion` state.
+ *
+ * CSS media queries cover styling, but the walkthrough also has to choose a
+ * `scrollIntoView` behaviour and decide whether to animate the spotlight
+ * between targets, and those are script decisions. Reading the preference
+ * reactively (rather than once at setup) matters because the user can flip
+ * the OS setting while a tour is running.
+ */
+export declare function useReducedMotion(): Readonly<import("vue").Ref<boolean, boolean>>;
+/** One-shot check for code paths outside a reactive scope. */
+export declare function prefersReducedMotion(): boolean;
+//# sourceMappingURL=useReducedMotion.composable.d.ts.map

package/dist/composables/useReducedMotion.composable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReducedMotion.composable.d.ts","sourceRoot":"","sources":["../../src/composables/useReducedMotion.composable.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,kDAyB/B;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,OAAO,CAI9C"}

package/dist/composables/useWalkthrough.composable.d.ts

@@ -0,0 +1,19 @@
+import { type MaybeRefOrGetter } from 'vue';
+import type { IWalkthrough, IWalkthroughController, IWalkthroughOptions } from '../components/Walkthrough.d';
+/**
+ * The walkthrough state machine, with no rendering attached.
+ *
+ * Splitting it from `<NbWalkthrough>` is what makes a tour startable from
+ * places that have no template of their own — a help menu handler, a router
+ * guard, an onboarding checklist — and makes the interesting behaviour
+ * (version-gated auto-start, step advancement, persistence) testable without
+ * mounting anything.
+ *
+ * @example
+ * const tour = useWalkthrough(introTour)
+ * onMounted(() => tour.maybeAutoStart())
+ * // …later, from a "Show me around" menu item:
+ * tour.restart()
+ */
+export declare function useWalkthrough(source: MaybeRefOrGetter<IWalkthrough>, options?: IWalkthroughOptions): IWalkthroughController;
+//# sourceMappingURL=useWalkthrough.composable.d.ts.map

package/dist/composables/useWalkthrough.composable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWalkthrough.composable.d.ts","sourceRoot":"","sources":["../../src/composables/useWalkthrough.composable.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AACnE,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EAGpB,MAAM,4BAA4B,CAAA;AAKnC;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,CAAC,YAAY,CAAC,EACtC,OAAO,GAAE,mBAAwB,GAChC,sBAAsB,CAuHxB"}

package/dist/directives/TourStep.directive.d.ts

@@ -0,0 +1,4 @@
+import type { App } from 'vue';
+declare const tourStepDirective: (app: App) => void;
+export default tourStepDirective;
+//# sourceMappingURL=TourStep.directive.d.ts.map

package/dist/directives/TourStep.directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourStep.directive.d.ts","sourceRoot":"","sources":["../../src/directives/TourStep.directive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAoB,MAAM,KAAK,CAAA;AAoBhD,QAAA,MAAM,iBAAiB,GAAI,KAAK,GAAG,SAQlC,CAAA;AAED,eAAe,iBAAiB,CAAA"}

package/dist/global.d.ts

@@ -29,6 +29,7 @@ import GanttChart from './components/Charts/GanttChart.vue'
 import Grid from './components/Grid.vue'
 import Icon from './components/Icon.vue'
 import ImageCropper from './components/ImageCropper.vue'
+import InfoHint from './components/InfoHint.vue'
 import InterpolationChart from './components/Charts/InterpolationChart.vue'
 import JsonTree from './components/JsonTree.vue'
 import Label from './components/Label.vue'
@@ -66,6 +67,7 @@ import Toast from './components/Toast.vue'
 import Tree from './components/Tree.vue'
 import TreeNode from './components/TreeNode.vue'
 import UserMenu from './components/UserMenu.vue'
+import Walkthrough from './components/Walkthrough.vue'
 
 declare module 'vue' {
   interface GlobalComponents {
@@ -98,6 +100,7 @@ declare module 'vue' {
     NbGrid: typeof Grid
     NbIcon: typeof Icon
     NbImageCropper: typeof ImageCropper
+    NbInfoHint: typeof InfoHint
     NbInterpolationChart: typeof InterpolationChart
     NbJsonTree: typeof JsonTree
     NbLabel: typeof Label
@@ -135,6 +138,7 @@ declare module 'vue' {
     NbTree: typeof Tree
     NbTreeNode: typeof TreeNode
     NbUserMenu: typeof UserMenu
+    NbWalkthrough: typeof Walkthrough
   }
 }