@geomak/ui 2.0.0 → 4.0.0

package/dist/index.d.cts

@@ -928,34 +928,87 @@ interface ContextMenuPosition {
 }
 
 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 ─────────────────── */
 /**
@@ -1759,40 +1812,84 @@ interface AutoCompleteProps {
  */
 declare function AutoComplete({ disabled, label, placeholder, name, inputStyle, style, layout, items, onItemClick, emptyText, }: AutoCompleteProps): react_jsx_runtime.JSX.Element;
 
-interface TreeSelectItem {
+interface TreeSelectNode {
     key: string | number;
     label: React$1.ReactNode;
     icon?: React$1.ReactNode;
+    /** Nested children. If present, this node is treated as a parent (branch). */
+    children?: TreeSelectNode[];
+    /** Render the node disabled — visible but not selectable. */
+    disabled?: boolean;
 }
 interface TreeSelectProps {
-    hasSearch?: boolean;
-    label?: React$1.ReactNode;
-    name?: string;
-    value?: any;
+    /** Tree data. Each node may optionally carry `children` for sub-branches. */
+    items: TreeSelectNode[];
+    /** Currently selected key (single-select). Pass `undefined`/`null` for unset. */
+    value?: string | number | null;
+    /** Fires with the next selected key (and the corresponding event-like target). */
     onChange?: (e: {
         target: {
-            value: any;
+            value: string | number;
             id?: string;
             name?: string;
         };
     }) => void;
-    onBlur?: React$1.FocusEventHandler;
+    label?: React$1.ReactNode;
+    placeholder?: string;
+    /** Form control id linkage. */
+    htmlFor?: string;
+    name?: string;
+    /** Label/trigger orientation. Defaults to `'horizontal'`. */
+    layout?: 'horizontal' | 'vertical';
     disabled?: boolean;
-    /** 'horizontal' | 'vertical' */
-    layout?: string;
     errorMessage?: React$1.ReactNode;
     style?: React$1.CSSProperties;
-    htmlFor?: string;
-    items?: TreeSelectItem[];
+    /**
+     * Whether parent (branch) nodes can be selected. When `false`, parents
+     * only expand/collapse and only leaves are picked. Default `true`.
+     */
+    parentsSelectable?: boolean;
+    /** Keys of nodes that should start expanded. */
+    defaultExpandedKeys?: (string | number)[];
 }
 /**
- * Single-value select with a flat list, powered by Radix Popover.
- * Functionally similar to Dropdown (single-select only).
+ * Hierarchical single-select with expandable branches.
+ *
+ * Built on `@radix-ui/react-popover` for portal positioning and click-outside.
+ * Tree state (expanded keys) is local; selected value is controlled by the
+ * parent.
+ *
+ * **Keyboard model** (focus is on the trigger or any item):
+ * - `Enter` / `Space` / `↓` / `↑` on the trigger — open the popover
+ * - `↓` / `↑` — move active item through the visible (un-collapsed) list
+ * - `→` — expand a branch (or move into it if already expanded)
+ * - `←` — collapse a branch (or move to its parent if already collapsed)
+ * - `Enter` / `Space` — select the active item (if selectable)
+ * - `Esc` — close the popover, return focus to the trigger
  *
  * @example
- * <TreeSelect label="Fleet" items={fleets} value={form.fleet} onChange={handleChange} htmlFor="fleet" />
+ * ```tsx
+ * type FleetKey = number
+ * const [fleet, setFleet] = useState<FleetKey | null>(null)
+ *
+ * const tree: TreeSelectNode[] = [
+ *   { key: 'eu', label: 'Europe', children: [
+ *     { key: 1, label: 'Aegean Fleet' },
+ *     { key: 2, label: 'Adriatic Fleet' },
+ *   ]},
+ *   { key: 'asia', label: 'Asia', children: [{ key: 3, label: 'Pacific Fleet' }] },
+ * ]
+ *
+ * <TreeSelect
+ *   label="Fleet"
+ *   items={tree}
+ *   value={fleet}
+ *   onChange={({ target }) => setFleet(target.value as FleetKey)}
+ *   parentsSelectable={false}
+ * />
+ * ```
  */
-declare function TreeSelect({ label, name, value, onChange, disabled, layout, errorMessage, style, htmlFor, items, }: TreeSelectProps): react_jsx_runtime.JSX.Element;
+declare function TreeSelect({ label, name, value, onChange, disabled, layout, errorMessage, style, htmlFor, items, placeholder, parentsSelectable, defaultExpandedKeys, }: TreeSelectProps): react_jsx_runtime.JSX.Element;
 
 interface FileInputProps {
     allowMultiple?: boolean;

package/dist/index.d.ts

@@ -928,34 +928,87 @@ interface ContextMenuPosition {
 }
 
 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 ─────────────────── */
 /**
@@ -1759,40 +1812,84 @@ interface AutoCompleteProps {
  */
 declare function AutoComplete({ disabled, label, placeholder, name, inputStyle, style, layout, items, onItemClick, emptyText, }: AutoCompleteProps): react_jsx_runtime.JSX.Element;
 
-interface TreeSelectItem {
+interface TreeSelectNode {
     key: string | number;
     label: React$1.ReactNode;
     icon?: React$1.ReactNode;
+    /** Nested children. If present, this node is treated as a parent (branch). */
+    children?: TreeSelectNode[];
+    /** Render the node disabled — visible but not selectable. */
+    disabled?: boolean;
 }
 interface TreeSelectProps {
-    hasSearch?: boolean;
-    label?: React$1.ReactNode;
-    name?: string;
-    value?: any;
+    /** Tree data. Each node may optionally carry `children` for sub-branches. */
+    items: TreeSelectNode[];
+    /** Currently selected key (single-select). Pass `undefined`/`null` for unset. */
+    value?: string | number | null;
+    /** Fires with the next selected key (and the corresponding event-like target). */
     onChange?: (e: {
         target: {
-            value: any;
+            value: string | number;
             id?: string;
             name?: string;
         };
     }) => void;
-    onBlur?: React$1.FocusEventHandler;
+    label?: React$1.ReactNode;
+    placeholder?: string;
+    /** Form control id linkage. */
+    htmlFor?: string;
+    name?: string;
+    /** Label/trigger orientation. Defaults to `'horizontal'`. */
+    layout?: 'horizontal' | 'vertical';
     disabled?: boolean;
-    /** 'horizontal' | 'vertical' */
-    layout?: string;
     errorMessage?: React$1.ReactNode;
     style?: React$1.CSSProperties;
-    htmlFor?: string;
-    items?: TreeSelectItem[];
+    /**
+     * Whether parent (branch) nodes can be selected. When `false`, parents
+     * only expand/collapse and only leaves are picked. Default `true`.
+     */
+    parentsSelectable?: boolean;
+    /** Keys of nodes that should start expanded. */
+    defaultExpandedKeys?: (string | number)[];
 }
 /**
- * Single-value select with a flat list, powered by Radix Popover.
- * Functionally similar to Dropdown (single-select only).
+ * Hierarchical single-select with expandable branches.
+ *
+ * Built on `@radix-ui/react-popover` for portal positioning and click-outside.
+ * Tree state (expanded keys) is local; selected value is controlled by the
+ * parent.
+ *
+ * **Keyboard model** (focus is on the trigger or any item):
+ * - `Enter` / `Space` / `↓` / `↑` on the trigger — open the popover
+ * - `↓` / `↑` — move active item through the visible (un-collapsed) list
+ * - `→` — expand a branch (or move into it if already expanded)
+ * - `←` — collapse a branch (or move to its parent if already collapsed)
+ * - `Enter` / `Space` — select the active item (if selectable)
+ * - `Esc` — close the popover, return focus to the trigger
  *
  * @example
- * <TreeSelect label="Fleet" items={fleets} value={form.fleet} onChange={handleChange} htmlFor="fleet" />
+ * ```tsx
+ * type FleetKey = number
+ * const [fleet, setFleet] = useState<FleetKey | null>(null)
+ *
+ * const tree: TreeSelectNode[] = [
+ *   { key: 'eu', label: 'Europe', children: [
+ *     { key: 1, label: 'Aegean Fleet' },
+ *     { key: 2, label: 'Adriatic Fleet' },
+ *   ]},
+ *   { key: 'asia', label: 'Asia', children: [{ key: 3, label: 'Pacific Fleet' }] },
+ * ]
+ *
+ * <TreeSelect
+ *   label="Fleet"
+ *   items={tree}
+ *   value={fleet}
+ *   onChange={({ target }) => setFleet(target.value as FleetKey)}
+ *   parentsSelectable={false}
+ * />
+ * ```
  */
-declare function TreeSelect({ label, name, value, onChange, disabled, layout, errorMessage, style, htmlFor, items, }: TreeSelectProps): react_jsx_runtime.JSX.Element;
+declare function TreeSelect({ label, name, value, onChange, disabled, layout, errorMessage, style, htmlFor, items, placeholder, parentsSelectable, defaultExpandedKeys, }: TreeSelectProps): react_jsx_runtime.JSX.Element;
 
 interface FileInputProps {
     allowMultiple?: boolean;