@geomak/ui 1.9.0 → 3.0.0

package/dist/index.d.cts

@@ -853,72 +853,162 @@ interface MenuBarProps {
  */
 declare function MenuBar({ items }: MenuBarProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * A single action in the context menu.
+ *
+ * - Leaf items (no `children`) call `onClick` when activated.
+ * - Parent items (with `children`) open a sub-menu on hover / arrow-right.
+ * - `disabled` items render but cannot be activated; screen readers
+ *   announce them as disabled.
+ */
 interface ContextMenuActionItem {
-    key: string | number;
+    key: React$1.Key;
+    /** Label shown for the item. May be plain text or a node. */
     value: React$1.ReactNode;
     icon?: React$1.ReactNode;
-    onClick?: (path?: string, reportType?: string) => void;
-    path?: string;
-    reportType?: string;
+    /** Fires when the item is activated. Ignored when `children` is set. */
+    onClick?: () => void;
+    /** Optional sub-menu items. */
     children?: ContextMenuActionItem[];
-}
-interface ContextMenuPosition {
-    x: number;
-    y: number;
+    /** Render as disabled — still visible but not activatable. */
+    disabled?: boolean;
 }
 interface ContextMenuProps {
+    /** Top-level items. Each may carry nested `children` for sub-menus. */
     items: ContextMenuActionItem[];
-    position: ContextMenuPosition;
-    visible: boolean;
-    onClose: () => void;
+    /**
+     * The element that should respond to right-click. The entire React
+     * subtree underneath becomes the trigger area. Wrap an existing
+     * component / div / image — anything you can right-click on.
+     */
+    children: React$1.ReactNode;
 }
 /**
- * Right-click context menu positioned at arbitrary screen coordinates.
+ * Right-click context menu, built on `@radix-ui/react-context-menu`.
  *
- * Decoupled from `useData()` — the app manages `visible`, `position`, and
- * `items` in its own state and passes them here.
+ * **Idiomatic usage**: wrap the element that should respond to right-click.
+ * Radix handles positioning (avoids viewport edges automatically), keyboard
+ * navigation (↑↓ to move, → to open sub-menu, ← to close, Enter to activate,
+ * Esc to dismiss), focus management, and portal-based stacking.
  *
- * @example
- * const [ctx, setCtx] = useState({ visible: false, items: [], position: { x: 0, y: 0 } })
- *
- * <div onContextMenu={(e) => {
- *   e.preventDefault()
- *   setCtx({ visible: true, items: menuItems, position: { x: e.clientX, y: e.clientY } })
- * }}>...</div>
+ * @example Basic — flat menu
+ * ```tsx
+ * <ContextMenu
+ *   items={[
+ *     { key: 'edit',   value: 'Edit',   onClick: () => openEditor() },
+ *     { key: 'delete', value: 'Delete', onClick: () => askDelete() },
+ *   ]}
+ * >
+ *   <Card vessel={vessel} />
+ * </ContextMenu>
+ * ```
  *
- * <ContextMenu {...ctx} onClose={() => setCtx(c => ({ ...c, visible: false }))} />
+ * @example With sub-menu
+ * ```tsx
+ * <ContextMenu
+ *   items={[
+ *     {
+ *       key: 'export', value: 'Export',
+ *       children: [
+ *         { key: 'csv',  value: 'as CSV',  onClick: () => exportCsv() },
+ *         { key: 'xlsx', value: 'as Excel', onClick: () => exportXlsx() },
+ *       ],
+ *     },
+ *   ]}
+ * >
+ *   <Table rows={rows} />
+ * </ContextMenu>
+ * ```
  */
-declare function ContextMenu({ items, position, visible, onClose }: ContextMenuProps): react_jsx_runtime.JSX.Element;
+declare function ContextMenu({ items, children }: ContextMenuProps): react_jsx_runtime.JSX.Element;
+/** @deprecated The Radix rewrite positions the menu automatically — no coordinates needed. */
+interface ContextMenuPosition {
+    x: number;
+    y: number;
+}
 
 interface WizardStep {
-    /** Ref to the DOM element to highlight */
-    stepRef: React$1.RefObject<HTMLElement>;
+    /** Ref to the DOM element to highlight for this step. */
+    stepRef: React$1.RefObject<HTMLElement | null>;
+    /** Tooltip body content. */
     description: React$1.ReactNode;
-    /** 'natural' | 'center' — controls tooltip position relative to target */
-    positioning?: 'natural' | 'center';
+    /**
+     * Tooltip placement relative to the highlighted element.
+     * - `'right'`  (default) — to the right of the highlight
+     * - `'left'`             — to the left of the highlight
+     * - `'top'`              — above the highlight
+     * - `'bottom'`           — below the highlight
+     */
+    placement?: 'right' | 'left' | 'top' | 'bottom';
+    /** Optional heading for the step's tooltip. */
+    title?: React$1.ReactNode;
 }
 interface WizardProps {
+    /** The wrapped subtree — refs in `steps` point into this tree. */
     children: React$1.ReactNode;
+    /** Ordered list of steps to walk the user through. */
     steps: WizardStep[];
-    /** localStorage key used to remember dismissal (default: 'oxygen_wizard') */
-    storageKey?: string;
+    /**
+     * `localStorage` key used to remember dismissal. When the user clicks
+     * "Done" (or "Skip" when dismissible), this key is set so the wizard
+     * won't reopen on subsequent mounts.
+     *
+     * Pass `null` to disable persistence entirely (useful for tests or
+     * tours that should always run).
+     *
+     * Default: `'oxygen.wizard.completed'`.
+     */
+    storageKey?: string | null;
+    /** Show a "Skip tour" button + Esc-to-dismiss. Default `true`. */
+    dismissible?: boolean;
+    /** Called when the user reaches the final step's "Done" button. */
+    onComplete?: () => void;
+    /** Called when the user skips (or presses Esc) before completing. */
+    onSkip?: () => void;
 }
 /**
- * Guided-tour overlay wizard.
+ * Guided-tour overlay that walks the user through a sequence of UI elements.
  *
- * Highlights a DOM element via a border, then shows a floating tooltip
- * adjacent to it. Remembers dismissal via localStorage.
+ * Highlights each step's target element with an outlined "spotlight", shows a
+ * tooltip with the description, and provides Prev / Next / Done navigation.
+ * The wrapped tree is rendered unchanged; the overlay sits on top of it via a
+ * portal so it always covers the real viewport regardless of where Wizard
+ * lives in the React tree.
+ *
+ * **What's improved over the previous version**
+ * - `localStorage` access is SSR-safe and try/catch-guarded (Safari private
+ *   mode, quota exceeded, no-storage browsers all degrade silently).
+ * - No more `classList.add(...)` on consumer-owned DOM. The spotlight is a
+ *   portaled outline rectangle that tracks the target's bbox via
+ *   `ResizeObserver` + scroll/resize listeners. The consumer's DOM is never
+ *   mutated, so unmounting Wizard mid-tour leaves no orphan classes.
+ * - Focus trap inside the tooltip — Tab and Shift+Tab cycle through the
+ *   tooltip's buttons. Esc dismisses (when `dismissible`).
+ * - Backdrop blocks click-through on the rest of the page so the user can't
+ *   stumble into unrelated UI mid-tour. The highlighted target itself stays
+ *   click-blocked too (use the "Next" button to advance).
+ * - Position recalculates on scroll / resize / target size changes via
+ *   `ResizeObserver`.
+ * - All `dark-cornflower-blue` / `prussian-blue` / `bg-white` swapped for
+ *   semantic tokens — both light and dark modes work out of the box.
  *
  * @example
- * const step1Ref = useRef<HTMLDivElement>(null)
- * const steps = [
- *   { stepRef: step1Ref, description: 'Click here to start.', positioning: 'natural' },
- * ]
- * <Wizard steps={steps}>
- *   <div ref={step1Ref}>...</div>
+ * ```tsx
+ * const dashRef = useRef<HTMLDivElement>(null)
+ * const sidebarRef = useRef<HTMLElement>(null)
+ *
+ * <Wizard
+ *   steps={[
+ *     { stepRef: dashRef,    title: 'Dashboard', description: 'Your fleet at a glance.' },
+ *     { stepRef: sidebarRef, title: 'Navigation', description: 'Jump between sections here.', placement: 'right' },
+ *   ]}
+ *   onComplete={() => track('onboarding_complete')}
+ * >
+ *   <Layout dashRef={dashRef} sidebarRef={sidebarRef} />
  * </Wizard>
+ * ```
  */
-declare function Wizard({ children, steps, storageKey }: WizardProps): react_jsx_runtime.JSX.Element;
+declare function Wizard({ children, steps, storageKey, dismissible, onComplete, onSkip, }: WizardProps): react_jsx_runtime.JSX.Element;
 
 /** ─────────────────── types ─────────────────── */
 /**

package/dist/index.d.ts

@@ -853,72 +853,162 @@ interface MenuBarProps {
  */
 declare function MenuBar({ items }: MenuBarProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * A single action in the context menu.
+ *
+ * - Leaf items (no `children`) call `onClick` when activated.
+ * - Parent items (with `children`) open a sub-menu on hover / arrow-right.
+ * - `disabled` items render but cannot be activated; screen readers
+ *   announce them as disabled.
+ */
 interface ContextMenuActionItem {
-    key: string | number;
+    key: React$1.Key;
+    /** Label shown for the item. May be plain text or a node. */
     value: React$1.ReactNode;
     icon?: React$1.ReactNode;
-    onClick?: (path?: string, reportType?: string) => void;
-    path?: string;
-    reportType?: string;
+    /** Fires when the item is activated. Ignored when `children` is set. */
+    onClick?: () => void;
+    /** Optional sub-menu items. */
     children?: ContextMenuActionItem[];
-}
-interface ContextMenuPosition {
-    x: number;
-    y: number;
+    /** Render as disabled — still visible but not activatable. */
+    disabled?: boolean;
 }
 interface ContextMenuProps {
+    /** Top-level items. Each may carry nested `children` for sub-menus. */
     items: ContextMenuActionItem[];
-    position: ContextMenuPosition;
-    visible: boolean;
-    onClose: () => void;
+    /**
+     * The element that should respond to right-click. The entire React
+     * subtree underneath becomes the trigger area. Wrap an existing
+     * component / div / image — anything you can right-click on.
+     */
+    children: React$1.ReactNode;
 }
 /**
- * Right-click context menu positioned at arbitrary screen coordinates.
+ * Right-click context menu, built on `@radix-ui/react-context-menu`.
  *
- * Decoupled from `useData()` — the app manages `visible`, `position`, and
- * `items` in its own state and passes them here.
+ * **Idiomatic usage**: wrap the element that should respond to right-click.
+ * Radix handles positioning (avoids viewport edges automatically), keyboard
+ * navigation (↑↓ to move, → to open sub-menu, ← to close, Enter to activate,
+ * Esc to dismiss), focus management, and portal-based stacking.
  *
- * @example
- * const [ctx, setCtx] = useState({ visible: false, items: [], position: { x: 0, y: 0 } })
- *
- * <div onContextMenu={(e) => {
- *   e.preventDefault()
- *   setCtx({ visible: true, items: menuItems, position: { x: e.clientX, y: e.clientY } })
- * }}>...</div>
+ * @example Basic — flat menu
+ * ```tsx
+ * <ContextMenu
+ *   items={[
+ *     { key: 'edit',   value: 'Edit',   onClick: () => openEditor() },
+ *     { key: 'delete', value: 'Delete', onClick: () => askDelete() },
+ *   ]}
+ * >
+ *   <Card vessel={vessel} />
+ * </ContextMenu>
+ * ```
  *
- * <ContextMenu {...ctx} onClose={() => setCtx(c => ({ ...c, visible: false }))} />
+ * @example With sub-menu
+ * ```tsx
+ * <ContextMenu
+ *   items={[
+ *     {
+ *       key: 'export', value: 'Export',
+ *       children: [
+ *         { key: 'csv',  value: 'as CSV',  onClick: () => exportCsv() },
+ *         { key: 'xlsx', value: 'as Excel', onClick: () => exportXlsx() },
+ *       ],
+ *     },
+ *   ]}
+ * >
+ *   <Table rows={rows} />
+ * </ContextMenu>
+ * ```
  */
-declare function ContextMenu({ items, position, visible, onClose }: ContextMenuProps): react_jsx_runtime.JSX.Element;
+declare function ContextMenu({ items, children }: ContextMenuProps): react_jsx_runtime.JSX.Element;
+/** @deprecated The Radix rewrite positions the menu automatically — no coordinates needed. */
+interface ContextMenuPosition {
+    x: number;
+    y: number;
+}
 
 interface WizardStep {
-    /** Ref to the DOM element to highlight */
-    stepRef: React$1.RefObject<HTMLElement>;
+    /** Ref to the DOM element to highlight for this step. */
+    stepRef: React$1.RefObject<HTMLElement | null>;
+    /** Tooltip body content. */
     description: React$1.ReactNode;
-    /** 'natural' | 'center' — controls tooltip position relative to target */
-    positioning?: 'natural' | 'center';
+    /**
+     * Tooltip placement relative to the highlighted element.
+     * - `'right'`  (default) — to the right of the highlight
+     * - `'left'`             — to the left of the highlight
+     * - `'top'`              — above the highlight
+     * - `'bottom'`           — below the highlight
+     */
+    placement?: 'right' | 'left' | 'top' | 'bottom';
+    /** Optional heading for the step's tooltip. */
+    title?: React$1.ReactNode;
 }
 interface WizardProps {
+    /** The wrapped subtree — refs in `steps` point into this tree. */
     children: React$1.ReactNode;
+    /** Ordered list of steps to walk the user through. */
     steps: WizardStep[];
-    /** localStorage key used to remember dismissal (default: 'oxygen_wizard') */
-    storageKey?: string;
+    /**
+     * `localStorage` key used to remember dismissal. When the user clicks
+     * "Done" (or "Skip" when dismissible), this key is set so the wizard
+     * won't reopen on subsequent mounts.
+     *
+     * Pass `null` to disable persistence entirely (useful for tests or
+     * tours that should always run).
+     *
+     * Default: `'oxygen.wizard.completed'`.
+     */
+    storageKey?: string | null;
+    /** Show a "Skip tour" button + Esc-to-dismiss. Default `true`. */
+    dismissible?: boolean;
+    /** Called when the user reaches the final step's "Done" button. */
+    onComplete?: () => void;
+    /** Called when the user skips (or presses Esc) before completing. */
+    onSkip?: () => void;
 }
 /**
- * Guided-tour overlay wizard.
+ * Guided-tour overlay that walks the user through a sequence of UI elements.
  *
- * Highlights a DOM element via a border, then shows a floating tooltip
- * adjacent to it. Remembers dismissal via localStorage.
+ * Highlights each step's target element with an outlined "spotlight", shows a
+ * tooltip with the description, and provides Prev / Next / Done navigation.
+ * The wrapped tree is rendered unchanged; the overlay sits on top of it via a
+ * portal so it always covers the real viewport regardless of where Wizard
+ * lives in the React tree.
+ *
+ * **What's improved over the previous version**
+ * - `localStorage` access is SSR-safe and try/catch-guarded (Safari private
+ *   mode, quota exceeded, no-storage browsers all degrade silently).
+ * - No more `classList.add(...)` on consumer-owned DOM. The spotlight is a
+ *   portaled outline rectangle that tracks the target's bbox via
+ *   `ResizeObserver` + scroll/resize listeners. The consumer's DOM is never
+ *   mutated, so unmounting Wizard mid-tour leaves no orphan classes.
+ * - Focus trap inside the tooltip — Tab and Shift+Tab cycle through the
+ *   tooltip's buttons. Esc dismisses (when `dismissible`).
+ * - Backdrop blocks click-through on the rest of the page so the user can't
+ *   stumble into unrelated UI mid-tour. The highlighted target itself stays
+ *   click-blocked too (use the "Next" button to advance).
+ * - Position recalculates on scroll / resize / target size changes via
+ *   `ResizeObserver`.
+ * - All `dark-cornflower-blue` / `prussian-blue` / `bg-white` swapped for
+ *   semantic tokens — both light and dark modes work out of the box.
  *
  * @example
- * const step1Ref = useRef<HTMLDivElement>(null)
- * const steps = [
- *   { stepRef: step1Ref, description: 'Click here to start.', positioning: 'natural' },
- * ]
- * <Wizard steps={steps}>
- *   <div ref={step1Ref}>...</div>
+ * ```tsx
+ * const dashRef = useRef<HTMLDivElement>(null)
+ * const sidebarRef = useRef<HTMLElement>(null)
+ *
+ * <Wizard
+ *   steps={[
+ *     { stepRef: dashRef,    title: 'Dashboard', description: 'Your fleet at a glance.' },
+ *     { stepRef: sidebarRef, title: 'Navigation', description: 'Jump between sections here.', placement: 'right' },
+ *   ]}
+ *   onComplete={() => track('onboarding_complete')}
+ * >
+ *   <Layout dashRef={dashRef} sidebarRef={sidebarRef} />
  * </Wizard>
+ * ```
  */
-declare function Wizard({ children, steps, storageKey }: WizardProps): react_jsx_runtime.JSX.Element;
+declare function Wizard({ children, steps, storageKey, dismissible, onComplete, onSkip, }: WizardProps): react_jsx_runtime.JSX.Element;
 
 /** ─────────────────── types ─────────────────── */
 /**