@nubisco/ui 2.0.1 → 2.1.0

package/dist/utils/anchorPosition.helper.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Viewport-aware placement for floating surfaces (hint popovers, walkthrough
+ * coach-marks) anchored to an element.
+ *
+ * Deliberately a pure function over plain rectangles rather than a method on a
+ * component: placement is the part of a popover that is easy to get subtly
+ * wrong and impossible to eyeball in a unit test, so it is kept free of DOM
+ * access. Callers pass `getBoundingClientRect()` output and the viewport size;
+ * everything else is arithmetic.
+ */
+export type TAnchorSide = 'top' | 'bottom' | 'left' | 'right';
+/** The subset of DOMRect this module needs. Any DOMRect satisfies it. */
+export interface IAnchorRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export interface IAnchorSize {
+    width: number;
+    height: number;
+}
+export interface IAnchorOptions {
+    /** Preferred side. Flipped only when it does not fit. */
+    side: TAnchorSide;
+    /** Distance between the anchor edge and the floating surface. */
+    gap?: number;
+    /** Minimum distance kept between the surface and the viewport edge. */
+    inset?: number;
+    viewport: IAnchorSize;
+}
+export interface IAnchorPlacement {
+    /** Viewport (`position: fixed`) coordinates. */
+    top: number;
+    left: number;
+    /** The side actually used, after any flip. Drives the arrow direction. */
+    side: TAnchorSide;
+    /**
+     * Where the anchor's centre sits along the surface's cross axis, as a
+     * percentage of the surface's size on that axis. After a viewport clamp the
+     * surface and the anchor are no longer centred on each other, so an arrow
+     * pinned at a fixed 50% points at nothing; consumers feed this into a CSS
+     * custom property to re-aim it.
+     */
+    arrowOffset: number;
+}
+export declare function placeAnchored(anchor: IAnchorRect, floating: IAnchorSize, { side, gap, inset, viewport }: IAnchorOptions): IAnchorPlacement;
+/** Live viewport size, guarded for SSR / non-DOM environments. */
+export declare function viewportSize(): IAnchorSize;
+//# sourceMappingURL=anchorPosition.helper.d.ts.map

package/dist/utils/anchorPosition.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchorPosition.helper.d.ts","sourceRoot":"","sources":["../../src/utils/anchorPosition.helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAA;AAE7D,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,IAAI,EAAE,WAAW,CAAA;IACjB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,IAAI,EAAE,WAAW,CAAA;IACjB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAA;CACpB;AAsDD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,EACrB,EAAE,IAAI,EAAE,GAAO,EAAE,KAAU,EAAE,QAAQ,EAAE,EAAE,cAAc,GACtD,gBAAgB,CAiDlB;AAED,kEAAkE;AAClE,wBAAgB,YAAY,IAAI,WAAW,CAG1C"}

package/dist/utils/tourTarget.helper.d.ts

@@ -0,0 +1,19 @@
+import type { TWalkthroughTarget } from '../components/Walkthrough.d';
+/**
+ * Attribute written by the `v-nb-tour-step` directive. Steps reference these
+ * ids instead of CSS selectors so a refactor of the markup cannot silently
+ * break a tour: the id travels with the element.
+ */
+export declare const TOUR_STEP_ATTRIBUTE = "data-nb-tour-step";
+/** Builds the selector for a tour-step id. Exported for host-side assertions. */
+export declare function tourStepSelector(id: string): string;
+/**
+ * Resolves a step's `target` to a live element, or null when it is not in the
+ * DOM right now (a collapsed sidebar, a route not yet visited). Null is a
+ * normal outcome, not an error: the walkthrough skips over steps whose target
+ * has gone missing rather than stranding the user on a blank spotlight.
+ */
+export declare function resolveTourTarget(target: TWalkthroughTarget | undefined, root?: Document | HTMLElement): HTMLElement | null;
+/** True when the element is rendered and has a non-zero box worth spotlighting. */
+export declare function isTargetVisible(element: HTMLElement | null): boolean;
+//# sourceMappingURL=tourTarget.helper.d.ts.map

package/dist/utils/tourTarget.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tourTarget.helper.d.ts","sourceRoot":"","sources":["../../src/utils/tourTarget.helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAStD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEnD;AAQD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,IAAI,GAAE,QAAQ,GAAG,WAEqB,GACrC,WAAW,GAAG,IAAI,CAyBpB;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAIpE"}

package/dist/utils/walkthroughStorage.helper.d.ts

@@ -0,0 +1,22 @@
+import type { IWalkthroughRecord, IWalkthroughStorage } from '../components/Walkthrough.d';
+export declare const WALKTHROUGH_STORAGE_PREFIX = "nb:walkthrough:";
+/**
+ * The default adapter: one localStorage entry per walkthrough id.
+ *
+ * Every access is wrapped, because localStorage throws rather than degrading
+ * in two situations a shipped app will meet: Safari in private mode (quota
+ * exceeded on write) and a cross-origin iframe with storage blocked (a
+ * SecurityError on mere property access). A tour failing to remember itself
+ * is a nuisance; a tour taking the host app down with it is not acceptable,
+ * so a broken store reads as "never seen" and writes become no-ops.
+ */
+export declare function createLocalStorageWalkthroughStorage(prefix?: string): IWalkthroughStorage;
+/**
+ * Non-persistent adapter. Useful in tests, in Storybook-style docs previews
+ * where every reload should show the tour again, and as a fallback in
+ * environments with no `window`.
+ */
+export declare function createMemoryWalkthroughStorage(seed?: Record<string, IWalkthroughRecord>): IWalkthroughStorage;
+/** Picks the persistent adapter when there is a DOM, memory otherwise (SSR). */
+export declare function createDefaultWalkthroughStorage(): IWalkthroughStorage;
+//# sourceMappingURL=walkthroughStorage.helper.d.ts.map

package/dist/utils/walkthroughStorage.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthroughStorage.helper.d.ts","sourceRoot":"","sources":["../../src/utils/walkthroughStorage.helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,4BAA4B,CAAA;AAEnC,eAAO,MAAM,0BAA0B,oBAAoB,CAAA;AAU3D;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,GAAE,MAAmC,GAC1C,mBAAmB,CA8BrB;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAM,GAC5C,mBAAmB,CAQrB;AAED,gFAAgF;AAChF,wBAAgB,+BAA+B,IAAI,mBAAmB,CAKrE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubisco/ui",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vue 3 UI component library",
   "packageManager": "pnpm@11.0.8",
   "repository": {

package/src/styles/_theme.scss

@@ -237,6 +237,25 @@
     // Focus ring — used by all interactive controls via :focus-visible
     --nb-c-focus-ring: var(--nb-c-primary);
 
+    // ── Scrim / overlay ───────────────────────────────────────────────────
+    // The dim laid over the page by anything that takes over the viewport:
+    // modals, drawers, and the walkthrough spotlight. Derived from
+    // --nb-c-black via color-mix so it stays a semantic token (no literal
+    // rgba() at the call site) and one override re-tunes every overlay.
+    // --nb-c-scrim-strong is the heavier variant for surfaces that must
+    // fully suppress the page behind them (coach-mark spotlights).
+    --nb-c-scrim: color-mix(in srgb, var(--nb-c-black) 45%, transparent);
+    --nb-c-scrim-strong: color-mix(in srgb, var(--nb-c-black) 62%, transparent);
+
+    // ── Radii ─────────────────────────────────────────────────────────────
+    // Corner scale, expressed against the 8px base unit so a change to
+    // --nb-base-unit rescales rounding with everything else.
+    --nb-radius-xs: calc(var(--nb-base-unit) / 4); // 2px
+    --nb-radius-sm: calc(var(--nb-base-unit) / 2); // 4px
+    --nb-radius-md: var(--nb-base-unit); // 8px
+    --nb-radius-lg: calc(var(--nb-base-unit) * 1.5); // 12px
+    --nb-radius-pill: 9999px;
+
     --nb-grid-max-width: #{grid.$grid-max-width}px;
     --nb-grid-columns: #{grid.$grid-columns};
     --nb-grid-gutter: #{grid.$grid-gutter}px;
@@ -494,5 +513,12 @@
     --nb-c-component-active: #{colors.get-color('nouveau-gray', 400)};
     --nb-c-component-disabled: #{colors.get-color('nouveau-gray', 700)};
     --nb-c-component-plain-border: #{colors.get-color('nouveau-gray', 600)};
+
+    // Scrim — a dark page needs a heavier dim to read as "the page behind
+    // this is out of play"; 45% over an already-dark background barely
+    // registers. Only the scrim tokens change; the radius scale is
+    // theme-independent and stays on the base.
+    --nb-c-scrim: color-mix(in srgb, var(--nb-c-black) 65%, transparent);
+    --nb-c-scrim-strong: color-mix(in srgb, var(--nb-c-black) 80%, transparent);
   }
 }

package/src/utils/anchorPosition.helper.ts

@@ -0,0 +1,164 @@
+/**
+ * Viewport-aware placement for floating surfaces (hint popovers, walkthrough
+ * coach-marks) anchored to an element.
+ *
+ * Deliberately a pure function over plain rectangles rather than a method on a
+ * component: placement is the part of a popover that is easy to get subtly
+ * wrong and impossible to eyeball in a unit test, so it is kept free of DOM
+ * access. Callers pass `getBoundingClientRect()` output and the viewport size;
+ * everything else is arithmetic.
+ */
+
+export type TAnchorSide = 'top' | 'bottom' | 'left' | 'right'
+
+/** The subset of DOMRect this module needs. Any DOMRect satisfies it. */
+export interface IAnchorRect {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
+export interface IAnchorSize {
+  width: number
+  height: number
+}
+
+export interface IAnchorOptions {
+  /** Preferred side. Flipped only when it does not fit. */
+  side: TAnchorSide
+  /** Distance between the anchor edge and the floating surface. */
+  gap?: number
+  /** Minimum distance kept between the surface and the viewport edge. */
+  inset?: number
+  viewport: IAnchorSize
+}
+
+export interface IAnchorPlacement {
+  /** Viewport (`position: fixed`) coordinates. */
+  top: number
+  left: number
+  /** The side actually used, after any flip. Drives the arrow direction. */
+  side: TAnchorSide
+  /**
+   * Where the anchor's centre sits along the surface's cross axis, as a
+   * percentage of the surface's size on that axis. After a viewport clamp the
+   * surface and the anchor are no longer centred on each other, so an arrow
+   * pinned at a fixed 50% points at nothing; consumers feed this into a CSS
+   * custom property to re-aim it.
+   */
+  arrowOffset: number
+}
+
+/**
+ * Order in which sides are tried when the requested one does not fit: the
+ * opposite side first (visually the least surprising fallback), then the
+ * orthogonal pair, which is what rescues anchors sitting in a viewport corner
+ * where both sides of the requested axis overflow.
+ */
+const FALLBACK_ORDER: Record<TAnchorSide, readonly TAnchorSide[]> = {
+  top: ['bottom', 'right', 'left'],
+  bottom: ['top', 'right', 'left'],
+  left: ['right', 'bottom', 'top'],
+  right: ['left', 'bottom', 'top'],
+}
+
+const ARROW_MARGIN = 10
+
+function placeFor(
+  side: TAnchorSide,
+  anchor: IAnchorRect,
+  floating: IAnchorSize,
+  gap: number,
+): { top: number; left: number } {
+  const centerX = anchor.left + anchor.width / 2 - floating.width / 2
+  const centerY = anchor.top + anchor.height / 2 - floating.height / 2
+
+  switch (side) {
+    case 'top':
+      return { top: anchor.top - floating.height - gap, left: centerX }
+    case 'bottom':
+      return { top: anchor.top + anchor.height + gap, left: centerX }
+    case 'left':
+      return { top: centerY, left: anchor.left - floating.width - gap }
+    case 'right':
+    default:
+      return { top: centerY, left: anchor.left + anchor.width + gap }
+  }
+}
+
+function fits(
+  top: number,
+  left: number,
+  floating: IAnchorSize,
+  inset: number,
+  viewport: IAnchorSize,
+): boolean {
+  return (
+    left >= inset &&
+    top >= inset &&
+    left + floating.width <= viewport.width - inset &&
+    top + floating.height <= viewport.height - inset
+  )
+}
+
+export function placeAnchored(
+  anchor: IAnchorRect,
+  floating: IAnchorSize,
+  { side, gap = 8, inset = 12, viewport }: IAnchorOptions,
+): IAnchorPlacement {
+  let chosen = side
+  let placed = placeFor(side, anchor, floating, gap)
+
+  // Zero-size floating surfaces show up on the first frame, before layout has
+  // measured them. Flipping on those numbers would pick a side at random, so
+  // the preferred side is kept until a real measurement arrives.
+  if (
+    floating.width > 0 &&
+    floating.height > 0 &&
+    !fits(placed.top, placed.left, floating, inset, viewport)
+  ) {
+    for (const candidate of FALLBACK_ORDER[side]) {
+      const next = placeFor(candidate, anchor, floating, gap)
+      if (fits(next.top, next.left, floating, inset, viewport)) {
+        chosen = candidate
+        placed = next
+        break
+      }
+    }
+  }
+
+  // Backstop for the case where no side fits at all (tiny viewport, long
+  // body copy): keep the surface onscreen even if it now overlaps the anchor.
+  let { top, left } = placed
+  if (floating.width > 0 && floating.height > 0) {
+    left = Math.min(
+      Math.max(left, inset),
+      Math.max(inset, viewport.width - floating.width - inset),
+    )
+    top = Math.min(
+      Math.max(top, inset),
+      Math.max(inset, viewport.height - floating.height - inset),
+    )
+  }
+
+  const horizontal = chosen === 'top' || chosen === 'bottom'
+  const extent = horizontal ? floating.width : floating.height
+  const anchorCenter = horizontal
+    ? anchor.left + anchor.width / 2 - left
+    : anchor.top + anchor.height / 2 - top
+  const arrowOffset =
+    extent > 0
+      ? (Math.min(Math.max(anchorCenter, ARROW_MARGIN), extent - ARROW_MARGIN) /
+          extent) *
+        100
+      : 50
+
+  return { top, left, side: chosen, arrowOffset }
+}
+
+/** Live viewport size, guarded for SSR / non-DOM environments. */
+export function viewportSize(): IAnchorSize {
+  if (typeof window === 'undefined') return { width: 0, height: 0 }
+  return { width: window.innerWidth, height: window.innerHeight }
+}

package/src/utils/tourTarget.helper.ts

@@ -0,0 +1,71 @@
+import type { TWalkthroughTarget } from '@/components/Walkthrough.d'
+
+/**
+ * Attribute written by the `v-nb-tour-step` directive. Steps reference these
+ * ids instead of CSS selectors so a refactor of the markup cannot silently
+ * break a tour: the id travels with the element.
+ */
+export const TOUR_STEP_ATTRIBUTE = 'data-nb-tour-step'
+
+function escapeAttributeValue(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(value)
+  }
+  return value.replace(/["\\]/g, '\\$&')
+}
+
+/** Builds the selector for a tour-step id. Exported for host-side assertions. */
+export function tourStepSelector(id: string): string {
+  return `[${TOUR_STEP_ATTRIBUTE}="${escapeAttributeValue(id)}"]`
+}
+
+function isRefLike(
+  value: unknown,
+): value is { value: HTMLElement | null | undefined } {
+  return !!value && typeof value === 'object' && 'value' in value
+}
+
+/**
+ * Resolves a step's `target` to a live element, or null when it is not in the
+ * DOM right now (a collapsed sidebar, a route not yet visited). Null is a
+ * normal outcome, not an error: the walkthrough skips over steps whose target
+ * has gone missing rather than stranding the user on a blank spotlight.
+ */
+export function resolveTourTarget(
+  target: TWalkthroughTarget | undefined,
+  root: Document | HTMLElement = typeof document !== 'undefined'
+    ? document
+    : (undefined as unknown as Document),
+): HTMLElement | null {
+  if (!target || !root) return null
+
+  if (typeof target === 'function') return target() ?? null
+  if (typeof target === 'object') {
+    if (target instanceof HTMLElement) return target
+    if (isRefLike(target)) {
+      const value = target.value
+      return value instanceof HTMLElement ? value : null
+    }
+    return null
+  }
+
+  // Tour-step id first, CSS selector second. Trying the id form even for
+  // strings that look like selectors costs one failed query and means an id
+  // like `nav` is never shadowed by the `<nav>` element.
+  const byId = root.querySelector<HTMLElement>(tourStepSelector(target))
+  if (byId) return byId
+
+  try {
+    return root.querySelector<HTMLElement>(target)
+  } catch {
+    // Not a valid selector either (a bare id containing spaces, say).
+    return null
+  }
+}
+
+/** True when the element is rendered and has a non-zero box worth spotlighting. */
+export function isTargetVisible(element: HTMLElement | null): boolean {
+  if (!element || !element.isConnected) return false
+  const rect = element.getBoundingClientRect()
+  return rect.width > 0 && rect.height > 0
+}

package/src/utils/walkthroughStorage.helper.ts

@@ -0,0 +1,83 @@
+import type {
+  IWalkthroughRecord,
+  IWalkthroughStorage,
+} from '@/components/Walkthrough.d'
+
+export const WALKTHROUGH_STORAGE_PREFIX = 'nb:walkthrough:'
+
+function isRecord(value: unknown): value is IWalkthroughRecord {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    typeof (value as IWalkthroughRecord).version === 'number'
+  )
+}
+
+/**
+ * The default adapter: one localStorage entry per walkthrough id.
+ *
+ * Every access is wrapped, because localStorage throws rather than degrading
+ * in two situations a shipped app will meet: Safari in private mode (quota
+ * exceeded on write) and a cross-origin iframe with storage blocked (a
+ * SecurityError on mere property access). A tour failing to remember itself
+ * is a nuisance; a tour taking the host app down with it is not acceptable,
+ * so a broken store reads as "never seen" and writes become no-ops.
+ */
+export function createLocalStorageWalkthroughStorage(
+  prefix: string = WALKTHROUGH_STORAGE_PREFIX,
+): IWalkthroughStorage {
+  const key = (id: string) => `${prefix}${id}`
+
+  return {
+    get(id) {
+      try {
+        const raw = window.localStorage.getItem(key(id))
+        if (!raw) return null
+        const parsed = JSON.parse(raw)
+        return isRecord(parsed) ? parsed : null
+      } catch {
+        return null
+      }
+    },
+    set(id, record) {
+      try {
+        window.localStorage.setItem(key(id), JSON.stringify(record))
+      } catch {
+        // Storage unavailable or full: the tour still runs, it just will not
+        // be remembered across reloads.
+      }
+    },
+    remove(id) {
+      try {
+        window.localStorage.removeItem(key(id))
+      } catch {
+        // See above.
+      }
+    },
+  }
+}
+
+/**
+ * Non-persistent adapter. Useful in tests, in Storybook-style docs previews
+ * where every reload should show the tour again, and as a fallback in
+ * environments with no `window`.
+ */
+export function createMemoryWalkthroughStorage(
+  seed: Record<string, IWalkthroughRecord> = {},
+): IWalkthroughStorage {
+  const store = new Map<string, IWalkthroughRecord>(Object.entries(seed))
+
+  return {
+    get: (id) => store.get(id) ?? null,
+    set: (id, record) => void store.set(id, record),
+    remove: (id) => void store.delete(id),
+  }
+}
+
+/** Picks the persistent adapter when there is a DOM, memory otherwise (SSR). */
+export function createDefaultWalkthroughStorage(): IWalkthroughStorage {
+  if (typeof window === 'undefined' || !('localStorage' in window)) {
+    return createMemoryWalkthroughStorage()
+  }
+  return createLocalStorageWalkthroughStorage()
+}