@coinbase/cds-common 0.0.0 → 8.13.1

package/esm/numbers/IntlNumberFormat.js

@@ -0,0 +1,204 @@
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { buildFractionPartsWithSubscript } from './subscript';
+const splitDigitsIntoParts = (digitsStr, type) => {
+  return digitsStr.split('').map(d => ({
+    type,
+    value: parseInt(d)
+  }));
+};
+const keyParts = (parts, generateKey, direction) => {
+  const seq = direction === 'rtl' ? [...parts].reverse() : parts;
+  const keyed = seq.map(p => _objectSpread(_objectSpread({}, p), {}, {
+    key: generateKey(p.type)
+  }));
+  return direction === 'rtl' ? keyed.reverse() : keyed;
+};
+
+/**
+ * Lightweight wrapper around the built-in Intl.NumberFormat that standardizes
+ * number formatting across CDS and provides a structure optimized for animated
+ * rendering in RollingNumber components.
+ *
+ * Responsibilities:
+ * - Create and cache an Intl.NumberFormat instance for given value, options, and locale
+ * - Expose a simple `format()` that returns the fully formatted string
+ * - Expose `formatToParts()` that returns logically grouped and keyed parts
+ *   (pre/integer/fraction/post) so UI layers can animate digits and symbols
+ * - Optionally supports subscript notation for leading fractional zeros
+ *
+ * Notes:
+ * - Keys produced by `formatToParts()` are stable and direction-aware so that
+ *   animations (e.g., per-digit transitions) can be deterministic
+ * - If the environment lacks `Intl.NumberFormat.prototype.formatToParts`, the
+ *   method will throw and callers should polyfill it.
+ */
+export class IntlNumberFormat {
+  constructor(props) {
+    this.value = props.value;
+    this.formatOptions = props.format;
+    this.locale = props.locale;
+    this.formatter = new Intl.NumberFormat(this.locale, this.formatOptions);
+  }
+
+  /**
+   * Returns the formatted string.
+   */
+  format() {
+    return this.formatter.format(this.value);
+  }
+
+  /**
+   * Returns the number parts for RollingNumber with groupings and keys for animations
+   * Examples
+   *
+   * Example 1 — basic currency
+   * Input:
+   * ```json
+   * {
+   *   "value": 98345.67,
+   *   "format": {
+   *     "style": "currency",
+   *     "currency": "USD",
+   *     "minimumFractionDigits": 2,
+   *     "maximumFractionDigits": 5
+   *   },
+   *   "locale": "en-US",
+   *   "prefix": "+",
+   *   "suffix": " BTC"
+   * }
+   * ```
+   *
+   * Output:
+   * ```json
+   * {
+   *   "pre": [
+   *     { "type": "currency", "value": "$", "key": "currency:0" }
+   *   ],
+   *   "integer": [
+   *     { "type": "integer", "value": 9, "key": "integer:4" },
+   *     { "type": "integer", "value": 8, "key": "integer:3" },
+   *     { "type": "group",   "value": ",", "key": "group:0" },
+   *     { "type": "integer", "value": 3, "key": "integer:2" },
+   *     { "type": "integer", "value": 4, "key": "integer:1" },
+   *     { "type": "integer", "value": 5, "key": "integer:0" }
+   *   ],
+   *   "fraction": [
+   *     { "type": "decimal",   "value": ".", "key": "decimal:0" },
+   *     { "type": "fraction",  "value": 6,   "key": "fraction:0" },
+   *     { "type": "fraction",  "value": 7,   "key": "fraction:1" }
+   *   ],
+   *   "post": [],
+   * }
+   * ```
+   *
+   * Example 2 — subscript notation enabled
+   * Input:
+   * ```json
+   * {
+   *   "value": 1e-10,
+   *   "format": {
+   *     "minimumFractionDigits": 2,
+   *     "maximumFractionDigits": 25
+   *   },
+   *   "locale": "en-US",
+   *   "enableSubscriptNotation": true
+   * }
+   * ```
+   *
+   * Output:
+   * ```json
+   * {
+   *   "pre": [],
+   *   "integer": [
+   *     { "type": "integer", "value": 0, "key": "integer:0" }
+   *   ],
+   *   "fraction": [
+   *     { "type": "decimal",   "value": ".", "key": "decimal:0" },
+   *     { "type": "fraction",  "value": 0,   "key": "fraction:0" },
+   *     { "type": "subscript", "value": "₉", "key": "subscript:0" },
+   *     { "type": "fraction",  "value": 1,   "key": "fraction:1" }
+   *   ],
+   *   "post": [],
+   * }
+   * ```
+   */
+  formatToParts() {
+    let {
+      enableSubscriptNotation
+    } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    if (!Intl.NumberFormat.prototype.formatToParts) {
+      throw new Error('Intl.NumberFormat.prototype.formatToParts is undefined, please ensure Intl.NumberFormat is polyfilled.');
+    }
+    const parts = this.formatter.formatToParts(this.value);
+    const pre = [];
+    const integerUnkeyed = [];
+    const fractionUnkeyed = [];
+    const post = [];
+    const counts = {};
+    const generateKey = type => {
+      var _counts$type;
+      return "".concat(type, ":").concat(counts[type] = ((_counts$type = counts[type]) !== null && _counts$type !== void 0 ? _counts$type : -1) + 1);
+    };
+    let didParseNumberPart = false;
+    for (const part of parts) {
+      const {
+        type,
+        value
+      } = part;
+      switch (type) {
+        case 'integer':
+          {
+            didParseNumberPart = true;
+            integerUnkeyed.push(...splitDigitsIntoParts(value, type));
+            break;
+          }
+        case 'fraction':
+          {
+            didParseNumberPart = true;
+            const fractionParts = enableSubscriptNotation ? buildFractionPartsWithSubscript(value) : splitDigitsIntoParts(value, type);
+            fractionUnkeyed.push(...fractionParts);
+            break;
+          }
+        case 'group':
+          {
+            didParseNumberPart = true;
+            integerUnkeyed.push({
+              type,
+              value
+            });
+            break;
+          }
+        case 'decimal':
+          {
+            didParseNumberPart = true;
+            fractionUnkeyed.push({
+              type,
+              value
+            });
+            break;
+          }
+        default:
+          {
+            (didParseNumberPart ? post : pre).push({
+              type,
+              value,
+              key: generateKey(type)
+            });
+            break;
+          }
+      }
+    }
+    const integer = keyParts(integerUnkeyed, generateKey, 'rtl');
+    const fraction = keyParts(fractionUnkeyed, generateKey, 'ltr');
+    return {
+      pre,
+      integer,
+      fraction,
+      post
+    };
+  }
+}

package/esm/numbers/subscript.js

@@ -0,0 +1,53 @@
+const numberSubscriptMap = {
+  '0': '₀',
+  '1': '₁',
+  '2': '₂',
+  '3': '₃',
+  '4': '₄',
+  '5': '₅',
+  '6': '₆',
+  '7': '₇',
+  '8': '₈',
+  '9': '₉'
+};
+export const toSubscriptNumber = n => String(n).split('').map(d => {
+  var _numberSubscriptMap$d;
+  return (_numberSubscriptMap$d = numberSubscriptMap[d]) !== null && _numberSubscriptMap$d !== void 0 ? _numberSubscriptMap$d : d;
+}).join('');
+
+/**
+ * Builds parts for the fractional digits with subscript applied to leading zeros.
+ */
+export function buildFractionPartsWithSubscript(fractionDigits) {
+  const match = /^(0+)(.*)$/.exec(fractionDigits);
+  if (!match) {
+    return fractionDigits.split('').map(d => ({
+      type: 'fraction',
+      value: parseInt(d, 10)
+    }));
+  }
+  const [, matchedZeros, restOfDigits] = match;
+  // no need to add subscript for single zero or no zeros, 0.0 -> 0.0, 0.912 -> 0.912
+  if (matchedZeros.length <= 1) {
+    return fractionDigits.split('').map(d => ({
+      type: 'fraction',
+      value: parseInt(d, 10)
+    }));
+  }
+  const parts = [];
+  parts.push({
+    type: 'fraction',
+    value: 0
+  });
+  parts.push({
+    type: 'subscript',
+    value: toSubscriptNumber(matchedZeros.length)
+  });
+  for (let i = 0; i < restOfDigits.length; i++) {
+    parts.push({
+      type: 'fraction',
+      value: parseInt(restOfDigits[i], 10)
+    });
+  }
+  return parts;
+}

package/esm/overlays/ModalContext.js

@@ -0,0 +1,8 @@
+import { createContext, useContext } from 'react';
+export const ModalContext = /*#__PURE__*/createContext({
+  visible: false,
+  onRequestClose: () => {},
+  hideDividers: false,
+  hideCloseButton: false
+});
+export const useModalContext = () => useContext(ModalContext);

package/esm/overlays/OverlayContentContext.js

@@ -0,0 +1,24 @@
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { createContext, useContext, useMemo } from 'react';
+
+// WARNING: If you add a new key to this type, you should also update the
+// useOverlayContentContext hook's `derivedContext.isOverlay` expression!
+
+export const OverlayContentContext = /*#__PURE__*/createContext({});
+export const useOverlayContentContext = () => {
+  const context = useContext(OverlayContentContext);
+  // userOverlayContentContext does not throw an error when used outside a provider
+  // so that any component may check if it's being rendered as overlay content, even
+  // if it's not wrapped in an OverlayContentContext.Provider.
+
+  // If context.isOverlay was not explicitly defined then we derive it from the other values.
+  const derivedContext = useMemo(() => _objectSpread(_objectSpread({}, context), {}, {
+    isOverlay: context.isModal || context.isDrawer || context.isTour
+  }), [context]);
+  if ((context === null || context === void 0 ? void 0 : context.isOverlay) === undefined) return derivedContext;
+  return context;
+};

package/esm/overlays/PortalContext.js

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+export const PortalContext = /*#__PURE__*/createContext({
+  addNode: () => {},
+  removeNode: () => {},
+  nodes: []
+});

package/esm/overlays/ToastProvider.js

@@ -0,0 +1,51 @@
+import React, { cloneElement, createContext, isValidElement, useMemo } from 'react';
+import { useToastQueue } from './useToastQueue';
+
+/**
+ * The data structure managed by the ToastProvider.
+ * It composes together the Toast element requested to be rendered and the duration for which it should be displayed.
+ */
+import { jsxs as _jsxs } from "react/jsx-runtime";
+export const ToastContext = /*#__PURE__*/createContext({
+  activeToast: undefined,
+  addToast: () => {},
+  removeToast: () => {},
+  hideToast: () => {},
+  clearToastQueue: () => {},
+  pauseTimer: () => {},
+  resumeTimer: () => {}
+});
+export const ToastProvider = _ref => {
+  var _element$props$bottom;
+  let {
+    children,
+    toastBottomOffset
+  } = _ref;
+  const {
+    activeToast,
+    addToast,
+    removeToast,
+    hideToast,
+    clearToastQueue,
+    pauseTimer,
+    resumeTimer
+  } = useToastQueue();
+  const element = activeToast === null || activeToast === void 0 ? void 0 : activeToast.element;
+  const memoizedContextValue = useMemo(() => ({
+    addToast,
+    removeToast,
+    hideToast,
+    clearToastQueue,
+    pauseTimer,
+    resumeTimer
+  }), [addToast, removeToast, hideToast, clearToastQueue, pauseTimer, resumeTimer]);
+  return /*#__PURE__*/_jsxs(ToastContext.Provider, {
+    value: memoizedContextValue,
+    children: [children, /*#__PURE__*/isValidElement(element) && toastBottomOffset ?
+    /*#__PURE__*/
+    // props level offset should have higher specificity
+    cloneElement(element, {
+      bottomOffset: (_element$props$bottom = element.props.bottomOffset) !== null && _element$props$bottom !== void 0 ? _element$props$bottom : toastBottomOffset
+    }) : element]
+  });
+};

package/esm/overlays/useAlert.js

@@ -0,0 +1,8 @@
+import { useOverlay } from './useOverlay';
+
+/**
+ * @deprecated Use the visible and onRequestClose props as outlined in the docs here https://cds.coinbase.com/components/modal#get-started
+ */
+export const useAlert = () => {
+  return useOverlay('alert_');
+};

package/esm/overlays/useModal.js

@@ -0,0 +1,16 @@
+import { useMemo } from 'react';
+import { useOverlay } from './useOverlay';
+
+/**
+ * @deprecated Use the visible and onRequestClose props as outlined in the docs here https://cds.coinbase.com/components/modal#get-started
+ */
+export const useModal = () => {
+  const {
+    open,
+    close
+  } = useOverlay('modal_');
+  return useMemo(() => ({
+    openModal: open,
+    closeModal: close
+  }), [open, close]);
+};

package/esm/overlays/useOverlay.js

@@ -0,0 +1,28 @@
+import { cloneElement, useCallback, useId, useMemo } from 'react';
+import { usePortal } from './usePortal';
+export const useOverlay = idPrefix => {
+  const {
+    addNode,
+    removeNode
+  } = usePortal();
+  const randomId = useId();
+  const id = useMemo(() => "".concat(idPrefix, "-").concat(randomId), [idPrefix, randomId]);
+  const open = useCallback(content => {
+    const element = /*#__PURE__*/cloneElement(content, {
+      // TODO react docs recommend _not_ using useId for keys
+      // follow up with a solution that doesn't use useId
+      // @link https://react.dev/reference/react/useId#usage
+      key: id,
+      visible: true
+    });
+    addNode(id, element);
+    return id;
+  }, [addNode, id]);
+  const close = useCallback(() => {
+    removeNode(id);
+  }, [removeNode, id]);
+  return useMemo(() => ({
+    open,
+    close
+  }), [open, close]);
+};

package/esm/overlays/usePortal.js

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { isProduction } from '@coinbase/cds-utils';
+import { PortalContext } from './PortalContext';
+export const usePortal = () => {
+  const context = useContext(PortalContext);
+  if (!isProduction() && !context) {
+    console.error('Cannot use `usePortal` outside of PortalProvider');
+  }
+  return context;
+};

package/esm/overlays/usePortalState.js

@@ -0,0 +1,55 @@
+import { cloneElement, useCallback, useMemo, useState } from 'react';
+
+/**
+ * This type defines the basic interface of a Component rendered through the PortalProvider.
+ */
+
+/**
+ * This hook is used to manage the state of a set of nodes rendered through the PortalProvider.
+ */
+export const usePortalState = () => {
+  const [nodes, setNodes] = useState([]);
+  const addNode = useCallback((id, element) => {
+    setNodes(prevNodes => {
+      const index = prevNodes.findIndex(item => item.id === id);
+      // if the id already exists, replace the element
+      if (index !== -1) {
+        const copy = [...prevNodes];
+        copy[index].element = element;
+        return copy;
+      }
+      return [...prevNodes, {
+        id,
+        element
+      }];
+    });
+  }, []);
+  const filterInvisibleNodes = useCallback(() => {
+    setNodes(prevNodes => prevNodes.filter(node => node.element.props.visible));
+  }, []);
+  const removeNode = useCallback(id => {
+    setNodes(prevNodes => {
+      const index = prevNodes.findIndex(item => item.id === id);
+      if (index === -1) return prevNodes;
+      const copy = [...prevNodes];
+      const nodeMatch = prevNodes[index].element;
+      const handleOnDidClose = () => {
+        var _nodeMatch$props, _nodeMatch$props$onDi;
+        (_nodeMatch$props = nodeMatch.props) === null || _nodeMatch$props === void 0 || (_nodeMatch$props$onDi = _nodeMatch$props.onDidClose) === null || _nodeMatch$props$onDi === void 0 || _nodeMatch$props$onDi.call(_nodeMatch$props);
+        filterInvisibleNodes();
+      };
+
+      // set the visible prop to false to trigger exit animation
+      copy[index].element = /*#__PURE__*/cloneElement(nodeMatch, {
+        visible: false,
+        onDidClose: handleOnDidClose
+      });
+      return copy;
+    });
+  }, [filterInvisibleNodes]);
+  return useMemo(() => ({
+    nodes,
+    addNode,
+    removeNode
+  }), [nodes, addNode, removeNode]);
+};

package/esm/overlays/useToastQueue.js

@@ -0,0 +1,67 @@
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { cloneElement, useCallback, useEffect, useRef, useState } from 'react';
+import { useTimer } from '../hooks/useTimer';
+export const useToastQueue = () => {
+  const [activeToast, setActiveToast] = useState();
+  const toastQueue = useRef([]);
+  const activeToastRef = useRef(null);
+  const hasActiveToast = useRef(false);
+  const timer = useTimer();
+  hasActiveToast.current = !!activeToast;
+  const hideToast = useCallback(async () => {
+    var _activeToastRef$curre;
+    return (_activeToastRef$curre = activeToastRef.current) === null || _activeToastRef$curre === void 0 ? void 0 : _activeToastRef$curre.hide();
+  }, [activeToastRef]);
+  const removeToast = useCallback(() => {
+    timer.clear();
+    setActiveToast(undefined);
+  }, [timer, setActiveToast]);
+  const setToast = useCallback(toast => {
+    if (!toast) return;
+    activeToastRef.current = null;
+    setActiveToast(_objectSpread(_objectSpread({}, toast), {}, {
+      element: /*#__PURE__*/cloneElement(toast.element, {
+        ref: activeToastRef
+      })
+    }));
+
+    // remove toast after duration
+    timer.start(() => {
+      void hideToast();
+    }, toast.duration);
+  }, [timer, hideToast]);
+  const addToast = useCallback((element, duration) => {
+    const toast = {
+      element,
+      duration
+    };
+    if (hasActiveToast.current) {
+      toastQueue.current.push(toast);
+    } else {
+      setToast(toast);
+    }
+  }, [setToast]);
+  useEffect(() => {
+    // dequeue toast to active
+    if (activeToast === undefined && toastQueue.current.length > 0) {
+      setToast(toastQueue.current.shift());
+    }
+  }, [activeToast, setToast]);
+  const clearToastQueue = useCallback(async () => {
+    removeToast();
+    toastQueue.current.length = 0;
+  }, [removeToast]);
+  return {
+    activeToast,
+    addToast,
+    removeToast,
+    hideToast,
+    clearToastQueue,
+    pauseTimer: timer.pause,
+    resumeTimer: timer.resume
+  };
+};

package/esm/stepper/useStepper.js

@@ -0,0 +1,124 @@
+import { useCallback, useMemo, useState } from 'react';
+import { flattenSteps } from './utils';
+/**
+ * A hook for managing StepperHorizontal or StepperVertical state.
+ * Both components can be used on their own, but this hook provides a convenient way to sync state changes to the component props.
+ *
+ * @param options - The options for the stepper.
+ * @param options.steps - The array of steps data.
+ * @param options.defaultActiveStepId - The default active step ID. If not provided, the first step will be used.
+ * @param options.skipParentSteps - If true, steps containing sub-steps will never be made active.
+ * @returns A tuple where the first element is the stepper state and the second element is an API for manipulating the stepper state.
+ */
+export const useStepper = _ref => {
+  let {
+    steps,
+    defaultActiveStepId,
+    skipParentSteps
+  } = _ref;
+  // Flatten the nested steps structure for internal processing
+  const flatSteps = useMemo(() => flattenSteps(steps), [steps]);
+  const findNextStep = useCallback(fromIndex => {
+    for (let i = fromIndex; i < flatSteps.length; i++) {
+      const step = flatSteps[i];
+      const isParentStep = step.subSteps && step.subSteps.length > 0;
+      const canUseStep = !skipParentSteps || !isParentStep;
+      if (canUseStep) {
+        return step;
+      }
+    }
+    return null;
+  }, [flatSteps, skipParentSteps]);
+  const findPreviousStep = useCallback(fromIndex => {
+    for (let i = fromIndex; i >= 0; i--) {
+      const step = flatSteps[i];
+      const isParentStep = step.subSteps && step.subSteps.length > 0;
+      const canUseStep = !skipParentSteps || !isParentStep;
+      if (canUseStep) {
+        return step;
+      }
+    }
+    return null;
+  }, [flatSteps, skipParentSteps]);
+  const getInitialActiveStepId = useCallback(() => {
+    if (flatSteps.length === 0 || defaultActiveStepId === null) {
+      return null;
+    }
+    if (defaultActiveStepId) {
+      const defaultStepInFlat = flatSteps.find(step => step.id === defaultActiveStepId);
+      if (defaultStepInFlat) {
+        const isParentStep = defaultStepInFlat.subSteps && defaultStepInFlat.subSteps.length > 0;
+        const canUseStep = !skipParentSteps || !isParentStep;
+        if (canUseStep) {
+          return defaultStepInFlat.id;
+        }
+
+        // If it's a parent step and we skip parent steps, find next valid step from this position
+        const defaultStepIndex = flatSteps.findIndex(step => step.id === defaultActiveStepId);
+        const nextValidStep = findNextStep(defaultStepIndex);
+        if (nextValidStep) {
+          return nextValidStep.id;
+        }
+      }
+    }
+
+    // Fallback to first valid step
+    const firstValidStep = findNextStep(0);
+    return firstValidStep ? firstValidStep.id : null;
+  }, [defaultActiveStepId, flatSteps, skipParentSteps, findNextStep]);
+  const [activeStepId, setActiveStepId] = useState(getInitialActiveStepId());
+  const goToStep = useCallback(stepId => {
+    const targetIndex = flatSteps.findIndex(step => step.id === stepId);
+    if (targetIndex === -1) {
+      return;
+    }
+    const targetStep = flatSteps[targetIndex];
+
+    // If skipParentSteps is enabled, don't allow navigation to parent steps
+    if (skipParentSteps && targetStep.subSteps && targetStep.subSteps.length > 0) {
+      return;
+    }
+    setActiveStepId(targetStep.id);
+  }, [flatSteps, setActiveStepId, skipParentSteps]);
+  const goNextStep = useCallback(() => {
+    setActiveStepId(currentActiveStepId => {
+      if (currentActiveStepId === null) {
+        const firstStep = findNextStep(0);
+        return firstStep ? firstStep.id : null;
+      }
+      const activeStepIndex = flatSteps.findIndex(step => step.id === currentActiveStepId);
+      const nextStep = findNextStep(activeStepIndex + 1);
+      if (nextStep) {
+        return nextStep.id;
+      } else {
+        return currentActiveStepId;
+      }
+    });
+  }, [flatSteps, findNextStep]);
+  const goPreviousStep = useCallback(() => {
+    setActiveStepId(currentActiveStepId => {
+      if (currentActiveStepId === null) {
+        return null;
+      }
+      const activeStepIndex = flatSteps.findIndex(step => step.id === currentActiveStepId);
+      const previousStep = findPreviousStep(activeStepIndex - 1);
+      if (previousStep) {
+        return previousStep.id;
+      }
+      return currentActiveStepId;
+    });
+  }, [flatSteps, findPreviousStep]);
+  const reset = useCallback(() => {
+    setActiveStepId(getInitialActiveStepId());
+  }, [getInitialActiveStepId, setActiveStepId]);
+  const state = useMemo(() => ({
+    activeStepId
+  }), [activeStepId]);
+  const api = useMemo(() => ({
+    goToStep,
+    goNextStep,
+    goPreviousStep,
+    reset
+  }), [goToStep, goNextStep, goPreviousStep, reset]);
+  return [state, api];
+};