@ssa-ui-kit/core 3.26.1 → 3.26.2

package/dist/ai/source-map.md

@@ -1584,9 +1584,11 @@ The app sidebar: a logo, a menu, and three layouts.
   - `subMenuMaxWidth?: Property.MaxWidth<string | number>` — Max width for submenu panels (e.g. 220).
   - `showIconTooltip?: boolean` — When true, show tooltips on nav icons when sidebar is collapsed.
   - `useMatchPattern?: (prefix: string) => string | PathPattern<string>` — Custom route matching for active state (e.g. for React Router): given a group's `prefix`, return the pattern…
-  - `onChange?: (isChecked: boolean) => void` — Called when the sidebar expand/collapse state changes.
+  - `onChange?: (isChecked: boolean) => void` — Called when the sidebar expand/collapse state changes — on user toggles, the collapse on viewport resize, and…
+  - `onToggle?: (isOpen: boolean) => void` — Called when the user opens or closes the panel with its toggle. Unlike `onChange`, it does not fire on mount,…
   - `exactMatch?: boolean` `= false` — If true, only exact path matches will be considered active. If false, sub-routes will also be considered…
   - `defaultExpanded?: boolean` `= false` — Initial expanded state (sidebar shows icon + text). When false, only icons are shown until the user toggles.
+  - `isOpen?: boolean` — Controlled expanded state. When passed, the sidebar renders from it and keeps no state of its own; toggles…
 
 #### CollapsibleNavBarCustomIconSVG
 

package/dist/components/CollapsibleNavBar/CollapsibleNavBar.d.ts

@@ -34,5 +34,8 @@ import { CollapsibleNavBarExtendedProps } from './types';
  *   onChange={(isExpanded) => console.log(isExpanded)}
  * />
  * ```
+ *
+ * Pass `isOpen` to own the expanded state (e.g. to persist it): the bar then
+ * renders from it and reports toggles through `onChange` for you to apply.
  */
-export declare const CollapsibleNavBar: ({ items, renderLogo, header, theme, activeColor, subMenuMaxWidth, showIconTooltip, className, useMatchPattern, onChange, exactMatch, defaultExpanded, }: CollapsibleNavBarExtendedProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const CollapsibleNavBar: (props: CollapsibleNavBarExtendedProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/CollapsibleNavBar/types.d.ts

@@ -63,8 +63,22 @@ export interface CollapsibleNavBarExtendedProps<T extends NavBarExtendedSubItem
      * loses a group.
      */
     useMatchPattern?: (prefix: string) => string | PathPattern<string>;
-    /** Called when the sidebar expand/collapse state changes. */
+    /**
+     * Called when the sidebar expand/collapse state changes — on user toggles,
+     * the collapse on viewport resize, and the mobile overlay closing on
+     * navigation.
+     *
+     * Uncontrolled, it also fires once on mount with the initial state.
+     * Controlled (`isOpen` passed), it never fires on mount and only reports a
+     * value that differs from `isOpen`.
+     */
     onChange?: (isChecked: boolean) => void;
+    /**
+     * Called when the user opens or closes the panel with its toggle. Unlike
+     * `onChange`, it does not fire on mount, on the resize collapse, on mobile
+     * navigation, or when `isOpen` changes from outside.
+     */
+    onToggle?: (isOpen: boolean) => void;
     /**
      * If true, only exact path matches will be considered active.
      * If false, sub-routes will also be considered active.
@@ -76,4 +90,13 @@ export interface CollapsibleNavBarExtendedProps<T extends NavBarExtendedSubItem
      * @default false
      */
     defaultExpanded?: boolean;
+    /**
+     * Controlled expanded state. When passed, the sidebar renders from it and
+     * keeps no state of its own; toggles are reported through `onChange` for the
+     * caller to apply. Omit it for the uncontrolled `defaultExpanded` behaviour.
+     *
+     * The bar still asks to collapse (`onChange(false)`) when the viewport
+     * resizes, as it does uncontrolled.
+     */
+    isOpen?: boolean;
 }

package/dist/index.js

@@ -70721,27 +70721,45 @@ const SCREEN_SIZES = {
  *   onChange={(isExpanded) => console.log(isExpanded)}
  * />
  * ```
+ *
+ * Pass `isOpen` to own the expanded state (e.g. to persist it): the bar then
+ * renders from it and reports toggles through `onChange` for you to apply.
  */
 
-const CollapsibleNavBar = ({
-  items,
-  renderLogo,
-  header,
-  theme = 'default',
-  activeColor,
-  subMenuMaxWidth,
-  showIconTooltip = false,
-  className,
-  useMatchPattern,
-  onChange,
-  exactMatch = false,
-  defaultExpanded = false
-}) => {
+const CollapsibleNavBar = props => {
+  const {
+    items,
+    renderLogo,
+    header,
+    theme = 'default',
+    activeColor,
+    subMenuMaxWidth,
+    showIconTooltip = false,
+    className,
+    useMatchPattern,
+    onChange,
+    onToggle,
+    exactMatch = false,
+    defaultExpanded = false,
+    isOpen
+  } = props;
   const toggleId = (0,external_react_.useId)();
   const {
     width
   } = (0,hooks_namespaceObject.useWindowSize)();
-  const [isChecked, onToggle] = (0,external_react_.useState)(defaultExpanded);
+  // Controlled by the prop's presence, per the kit convention — see
+  // `useControllableState`. Uncontrolled mode reports through the effect below
+  // (which also fires on mount, as it always has), so the hook only notifies
+  // when controlled.
+  const controlled = 'isOpen' in props;
+  const [rawChecked, setChecked] = (0,hooks_namespaceObject.useControllableState)({
+    controlled,
+    value: isOpen,
+    defaultValue: defaultExpanded,
+    finalValue: false,
+    onChange: controlled ? onChange : undefined
+  });
+  const isChecked = Boolean(rawChecked);
   const isMobile = width < SCREEN_SIZES['900'].width;
   const treeItems = (0,external_react_.useMemo)(() => toTreeItems(items), [items]);
   const [expandedIds, setExpandedIds] = (0,external_react_.useState)([]);
@@ -70757,14 +70775,16 @@ const CollapsibleNavBar = ({
       hasMeasured.current = true;
       return;
     }
-    onToggle(false);
+    setChecked(false);
   }, [width]);
   (0,external_react_.useEffect)(() => {
-    onChange?.(isChecked);
+    if (!controlled) {
+      onChange?.(isChecked);
+    }
   }, [isChecked]);
   const handleCloseMobileMenu = () => {
     if (isMobile) {
-      onToggle(!isChecked);
+      setChecked(!isChecked);
     }
   };
   return (0,jsx_runtime_namespaceObject.jsx)(CollapsibleNavBarProvider, {
@@ -70780,7 +70800,8 @@ const CollapsibleNavBar = ({
         id: toggleId,
         checked: isChecked,
         onChange: () => {
-          onToggle(!isChecked);
+          setChecked(!isChecked);
+          onToggle?.(!isChecked);
         }
       }), (0,jsx_runtime_namespaceObject.jsx)(CollapsibleNavToggle, {
         id: toggleId

package/dist/index.mjs

@@ -70381,27 +70381,45 @@ const SCREEN_SIZES = {
  *   onChange={(isExpanded) => console.log(isExpanded)}
  * />
  * ```
+ *
+ * Pass `isOpen` to own the expanded state (e.g. to persist it): the bar then
+ * renders from it and reports toggles through `onChange` for you to apply.
  */
 
-const CollapsibleNavBar = ({
-  items,
-  renderLogo,
-  header,
-  theme = 'default',
-  activeColor,
-  subMenuMaxWidth,
-  showIconTooltip = false,
-  className,
-  useMatchPattern,
-  onChange,
-  exactMatch = false,
-  defaultExpanded = false
-}) => {
+const CollapsibleNavBar = props => {
+  const {
+    items,
+    renderLogo,
+    header,
+    theme = 'default',
+    activeColor,
+    subMenuMaxWidth,
+    showIconTooltip = false,
+    className,
+    useMatchPattern,
+    onChange,
+    onToggle,
+    exactMatch = false,
+    defaultExpanded = false,
+    isOpen
+  } = props;
   const toggleId = (0,external_react_.useId)();
   const {
     width
   } = __WEBPACK_EXTERNAL_MODULE__ssa_ui_kit_hooks_615bc432_useWindowSize__();
-  const [isChecked, onToggle] = (0,external_react_.useState)(defaultExpanded);
+  // Controlled by the prop's presence, per the kit convention — see
+  // `useControllableState`. Uncontrolled mode reports through the effect below
+  // (which also fires on mount, as it always has), so the hook only notifies
+  // when controlled.
+  const controlled = 'isOpen' in props;
+  const [rawChecked, setChecked] = __WEBPACK_EXTERNAL_MODULE__ssa_ui_kit_hooks_615bc432_useControllableState__({
+    controlled,
+    value: isOpen,
+    defaultValue: defaultExpanded,
+    finalValue: false,
+    onChange: controlled ? onChange : undefined
+  });
+  const isChecked = Boolean(rawChecked);
   const isMobile = width < SCREEN_SIZES['900'].width;
   const treeItems = (0,external_react_.useMemo)(() => toTreeItems(items), [items]);
   const [expandedIds, setExpandedIds] = (0,external_react_.useState)([]);
@@ -70417,14 +70435,16 @@ const CollapsibleNavBar = ({
       hasMeasured.current = true;
       return;
     }
-    onToggle(false);
+    setChecked(false);
   }, [width]);
   (0,external_react_.useEffect)(() => {
-    onChange?.(isChecked);
+    if (!controlled) {
+      onChange?.(isChecked);
+    }
   }, [isChecked]);
   const handleCloseMobileMenu = () => {
     if (isMobile) {
-      onToggle(!isChecked);
+      setChecked(!isChecked);
     }
   };
   return __WEBPACK_EXTERNAL_MODULE__emotion_react_jsx_runtime_ea06233c_jsx__(CollapsibleNavBarProvider, {
@@ -70440,7 +70460,8 @@ const CollapsibleNavBar = ({
         id: toggleId,
         checked: isChecked,
         onChange: () => {
-          onToggle(!isChecked);
+          setChecked(!isChecked);
+          onToggle?.(!isChecked);
         }
       }), __WEBPACK_EXTERNAL_MODULE__emotion_react_jsx_runtime_ea06233c_jsx__(CollapsibleNavToggle, {
         id: toggleId