@instructure/ui-drilldown 11.0.1 → 11.0.2-snapshot-1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.0.2-snapshot-1](https://github.com/instructure/instructure-ui/compare/v11.0.1...v11.0.2-snapshot-1) (2025-10-17)
+
+
+### Features
+
+* **ui-drilldown:** make Drilldown.Group controlled via selectedOptions prop. If provided, this prop fully drives the selection state instead of internal state ([3341639](https://github.com/instructure/instructure-ui/commit/33416395bf7d9a4d5649334d65cc9b599dbc2ec3))
+
+
+
+
+
 ## [11.0.1](https://github.com/instructure/instructure-ui/compare/v11.0.0...v11.0.1) (2025-10-13)
 
 **Note:** Version bump only for package @instructure/ui-drilldown

package/es/Drilldown/DrilldownGroup/props.js

@@ -22,5 +22,5 @@
  * SOFTWARE.
  */
 
-const allowedProps = ['id', 'children', 'renderGroupTitle', 'withoutSeparators', 'disabled', 'role', 'as', 'elementRef', 'selectableType', 'defaultSelected', 'onSelect'];
+const allowedProps = ['id', 'children', 'renderGroupTitle', 'withoutSeparators', 'disabled', 'role', 'as', 'elementRef', 'selectableType', 'defaultSelected', 'selectedOptions', 'onSelect'];
 export { allowedProps };

package/es/Drilldown/index.js

@@ -30,6 +30,7 @@ var _dec, _dec2, _class, _Drilldown, _IconArrowOpenEndSoli, _IconArrowOpenStartS
 import { Children, Component } from 'react';
 import { warn, error } from '@instructure/console';
 import { contains, containsActiveElement } from '@instructure/ui-dom-utils';
+import { deepEqual } from '@instructure/ui-utils';
 import { callRenderProp, matchComponentTypes, omitProps, safeCloneElement, withDeterministicId } from '@instructure/ui-react-utils';
 import { View } from '@instructure/ui-view';
 import { Options } from '@instructure/ui-options';
@@ -79,7 +80,6 @@ let Drilldown = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle,
     this._pageHistory = void 0;
     // Map of the active options on the page (includes header options too)
     this._activeOptionsMap = {};
-    // Map of the selected options in groups (grouped by group id)
     this.ref = null;
     this.handleRef = el => {
       // ref and elementRef have to be set together for the same element
@@ -389,7 +389,7 @@ let Drilldown = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle,
       activePageId: props.rootPageId,
       highlightedOptionId: void 0,
       lastSelectedId: void 0,
-      selectedGroupOptionsMap: this.setDefaultSelected()
+      selectedGroupOptionsMap: this.getSelectedGroupOptionsMap()
     };
     this._pageHistory = [props.rootPageId];
     this._id = props.id || props.deterministicId();
@@ -430,6 +430,47 @@ let Drilldown = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle,
         highlightedOptionId: void 0
       });
     }
+
+    // This block syncs the internal state if the selectedOptions prop changes
+    // selectedOptions prop values always win over internal state.
+    let shouldUpdateState = false;
+    const nextSelectionMap = {
+      ...this.state.selectedGroupOptionsMap
+    };
+    this.pages.forEach(page => {
+      this.getChildrenArray(page.props.children).forEach(child => {
+        if (matchComponentTypes(child, [DrilldownGroup])) {
+          var _this$getChildrenArra;
+          const _child$props = child.props,
+            groupId = _child$props.id,
+            selectableType = _child$props.selectableType,
+            selectedOptions = _child$props.selectedOptions,
+            groupChildren = _child$props.children;
+          if (!selectableType || !Array.isArray(selectedOptions)) return;
+          const newGroupMap = new Map();
+          (_this$getChildrenArra = this.getChildrenArray(groupChildren)) === null || _this$getChildrenArra === void 0 ? void 0 : _this$getChildrenArra.forEach(groupChild => {
+            if (matchComponentTypes(groupChild, [DrilldownOption])) {
+              const _groupChild$props = groupChild.props,
+                optionId = _groupChild$props.id,
+                optionValue = _groupChild$props.value;
+              if (selectedOptions.includes(optionValue)) {
+                newGroupMap.set(optionId, optionValue);
+              }
+            }
+          });
+          const currentGroupMapInState = this.state.selectedGroupOptionsMap[groupId] || new Map();
+          if (!deepEqual(this.getNormalizedMap(newGroupMap), this.getNormalizedMap(currentGroupMapInState))) {
+            nextSelectionMap[groupId] = newGroupMap;
+            shouldUpdateState = true;
+          }
+        }
+      });
+    });
+    if (shouldUpdateState) {
+      this.setState({
+        selectedGroupOptionsMap: nextSelectionMap
+      });
+    }
   }
   get makeStylesVariables() {
     return {
@@ -521,43 +562,75 @@ let Drilldown = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle,
   getPageChildById(id) {
     return id ? this._activeOptionsMap[id] : void 0;
   }
-  setDefaultSelected() {
+  getNormalizedMap(map) {
+    return Array.from(map.entries());
+  }
+
+  /**
+   * Initializes the map of selected options for each group on initial render.
+   *
+   * This function establishes the selection state based on a clear precedence:
+   * 1. **Controlled Mode**: If a `Drilldown.Group` has the `selectedOptions` prop
+   * (as an array), it is treated as the absolute source of truth.
+   *
+   * 2. **Uncontrolled Mode**: If `selectedOptions` is not provided, the selection
+   * is determined by `defaultSelected` props, with the following priority:
+   * a. The `defaultSelected` boolean on an individual `Drilldown.Option`.
+   * b. The `defaultSelected` array of values on the `Drilldown.Group`.
+   *
+   * It also validates that 'single' selection groups do not mistakenly receive
+   * multiple selected or default values.
+   *
+   * @returns {SelectedGroupOptionsMap} An object where keys are group IDs and
+   * values are Maps of the selected { optionId: optionValue } pairs for that group.
+   */
+  getSelectedGroupOptionsMap() {
     const selectedGroupOptionsMap = {};
     this.pages.forEach(page => {
       const children = page.props.children;
       this.getChildrenArray(children).forEach(child => {
         if (matchComponentTypes(child, [DrilldownGroup])) {
-          var _this$getChildrenArra;
-          const _child$props = child.props,
-            groupId = _child$props.id,
-            selectableType = _child$props.selectableType,
-            _child$props$defaultS = _child$props.defaultSelected,
-            groupDefaultSelected = _child$props$defaultS === void 0 ? [] : _child$props$defaultS,
-            groupChildren = _child$props.children;
-          if (!selectableType) {
-            return;
-          }
-          if (selectableType && !selectedGroupOptionsMap[groupId]) {
-            selectedGroupOptionsMap[groupId] = new Map();
-          }
-          if (selectableType === 'single' && groupDefaultSelected.length > 1) {
-            error(false, `Radio type selectable groups can have only one item selected! Group with id "${groupId}" cannot select multiple items: [${groupDefaultSelected.join(', ')}]!`);
-            return;
-          }
+          var _this$getChildrenArra2;
+          const _child$props2 = child.props,
+            groupId = _child$props2.id,
+            selectableType = _child$props2.selectableType,
+            selectedOptions = _child$props2.selectedOptions,
+            _child$props2$default = _child$props2.defaultSelected,
+            defaultSelected = _child$props2$default === void 0 ? [] : _child$props2$default,
+            groupChildren = _child$props2.children;
+          if (!selectableType) return;
           selectedGroupOptionsMap[groupId] = new Map();
-          (_this$getChildrenArra = this.getChildrenArray(groupChildren)) === null || _this$getChildrenArra === void 0 ? void 0 : _this$getChildrenArra.forEach(groupChild => {
+          if (selectableType === 'single') {
+            if (Array.isArray(selectedOptions) && selectedOptions.length > 1) {
+              error(false, `Radio type selectable groups can have only one item selected! Group "${groupId}" has multiple values: [${selectedOptions.join(', ')}]!`);
+              return;
+            }
+            if (defaultSelected.length > 1) {
+              error(false, `Radio type selectable groups can have only one default item selected! Group "${groupId}" has multiple values: [${defaultSelected.join(', ')}]!`);
+              return;
+            }
+          }
+          (_this$getChildrenArra2 = this.getChildrenArray(groupChildren)) === null || _this$getChildrenArra2 === void 0 ? void 0 : _this$getChildrenArra2.forEach(groupChild => {
             if (matchComponentTypes(groupChild, [DrilldownOption])) {
-              const _groupChild$props = groupChild.props,
-                optionId = _groupChild$props.id,
-                optionValue = _groupChild$props.value,
-                optionDefaultSelected = _groupChild$props.defaultSelected;
-
-              // if explicitly set to false, it should override the group's
-              if (optionDefaultSelected === false) {
-                return;
+              const _groupChild$props2 = groupChild.props,
+                optionId = _groupChild$props2.id,
+                optionValue = _groupChild$props2.value,
+                optionDefaultSelected = _groupChild$props2.defaultSelected;
+              if (optionValue == null) return;
+              let isSelected = false;
+              // If the group is controlled via the `selectedOptions` prop, it is the source of truth.
+              // `defaultSelected` values are ignored.
+              if (Array.isArray(selectedOptions)) {
+                isSelected = selectedOptions.includes(optionValue);
+                // Second strongest is the `defaultSelected` value on the option itself.
+              } else if (optionDefaultSelected === false) {
+                isSelected = false;
+              } else {
+                // Last is the `defaultSelected` array on the group.
+                const isGroupDefaultSelected = defaultSelected.includes(optionValue);
+                isSelected = optionDefaultSelected || isGroupDefaultSelected;
               }
-              const isGroupDefaultSelected = typeof optionValue !== 'undefined' && groupDefaultSelected.filter(value => typeof value !== 'undefined').includes(optionValue);
-              if (optionDefaultSelected || isGroupDefaultSelected) {
+              if (isSelected) {
                 selectedGroupOptionsMap[groupId].set(optionId, optionValue);
               }
             }
@@ -652,8 +725,8 @@ let Drilldown = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle,
     let containsDuplicate = false;
     const childMap = new Map();
     for (const child of children) {
-      var _child$props2;
-      if (child && typeof child === 'object' && (_child$props2 = child.props) !== null && _child$props2 !== void 0 && _child$props2.id) {
+      var _child$props3;
+      if (child && typeof child === 'object' && (_child$props3 = child.props) !== null && _child$props3 !== void 0 && _child$props3.id) {
         if (!childMap.has(child.props.id)) {
           childMap.set(child.props.id, true);
         } else {

package/lib/Drilldown/DrilldownGroup/props.js

@@ -28,4 +28,4 @@ exports.allowedProps = void 0;
  * SOFTWARE.
  */
 
-const allowedProps = exports.allowedProps = ['id', 'children', 'renderGroupTitle', 'withoutSeparators', 'disabled', 'role', 'as', 'elementRef', 'selectableType', 'defaultSelected', 'onSelect'];
+const allowedProps = exports.allowedProps = ['id', 'children', 'renderGroupTitle', 'withoutSeparators', 'disabled', 'role', 'as', 'elementRef', 'selectableType', 'defaultSelected', 'selectedOptions', 'onSelect'];

package/lib/Drilldown/index.js

@@ -10,6 +10,7 @@ var _react = require("react");
 var _console = require("@instructure/console");
 var _contains = require("@instructure/ui-dom-utils/lib/contains.js");
 var _containsActiveElement = require("@instructure/ui-dom-utils/lib/containsActiveElement.js");
+var _deepEqual = require("@instructure/ui-utils/lib/deepEqual.js");
 var _callRenderProp = require("@instructure/ui-react-utils/lib/callRenderProp.js");
 var _matchComponentTypes = require("@instructure/ui-react-utils/lib/matchComponentTypes.js");
 var _omitProps = require("@instructure/ui-react-utils/lib/omitProps.js");
@@ -88,7 +89,6 @@ let Drilldown = exports.Drilldown = (_dec = (0, _withDeterministicId.withDetermi
     this._pageHistory = void 0;
     // Map of the active options on the page (includes header options too)
     this._activeOptionsMap = {};
-    // Map of the selected options in groups (grouped by group id)
     this.ref = null;
     this.handleRef = el => {
       // ref and elementRef have to be set together for the same element
@@ -398,7 +398,7 @@ let Drilldown = exports.Drilldown = (_dec = (0, _withDeterministicId.withDetermi
       activePageId: props.rootPageId,
       highlightedOptionId: void 0,
       lastSelectedId: void 0,
-      selectedGroupOptionsMap: this.setDefaultSelected()
+      selectedGroupOptionsMap: this.getSelectedGroupOptionsMap()
     };
     this._pageHistory = [props.rootPageId];
     this._id = props.id || props.deterministicId();
@@ -439,6 +439,47 @@ let Drilldown = exports.Drilldown = (_dec = (0, _withDeterministicId.withDetermi
         highlightedOptionId: void 0
       });
     }
+
+    // This block syncs the internal state if the selectedOptions prop changes
+    // selectedOptions prop values always win over internal state.
+    let shouldUpdateState = false;
+    const nextSelectionMap = {
+      ...this.state.selectedGroupOptionsMap
+    };
+    this.pages.forEach(page => {
+      this.getChildrenArray(page.props.children).forEach(child => {
+        if ((0, _matchComponentTypes.matchComponentTypes)(child, [_DrilldownGroup.DrilldownGroup])) {
+          var _this$getChildrenArra;
+          const _child$props = child.props,
+            groupId = _child$props.id,
+            selectableType = _child$props.selectableType,
+            selectedOptions = _child$props.selectedOptions,
+            groupChildren = _child$props.children;
+          if (!selectableType || !Array.isArray(selectedOptions)) return;
+          const newGroupMap = new Map();
+          (_this$getChildrenArra = this.getChildrenArray(groupChildren)) === null || _this$getChildrenArra === void 0 ? void 0 : _this$getChildrenArra.forEach(groupChild => {
+            if ((0, _matchComponentTypes.matchComponentTypes)(groupChild, [_DrilldownOption.DrilldownOption])) {
+              const _groupChild$props = groupChild.props,
+                optionId = _groupChild$props.id,
+                optionValue = _groupChild$props.value;
+              if (selectedOptions.includes(optionValue)) {
+                newGroupMap.set(optionId, optionValue);
+              }
+            }
+          });
+          const currentGroupMapInState = this.state.selectedGroupOptionsMap[groupId] || new Map();
+          if (!(0, _deepEqual.deepEqual)(this.getNormalizedMap(newGroupMap), this.getNormalizedMap(currentGroupMapInState))) {
+            nextSelectionMap[groupId] = newGroupMap;
+            shouldUpdateState = true;
+          }
+        }
+      });
+    });
+    if (shouldUpdateState) {
+      this.setState({
+        selectedGroupOptionsMap: nextSelectionMap
+      });
+    }
   }
   get makeStylesVariables() {
     return {
@@ -530,43 +571,75 @@ let Drilldown = exports.Drilldown = (_dec = (0, _withDeterministicId.withDetermi
   getPageChildById(id) {
     return id ? this._activeOptionsMap[id] : void 0;
   }
-  setDefaultSelected() {
+  getNormalizedMap(map) {
+    return Array.from(map.entries());
+  }
+
+  /**
+   * Initializes the map of selected options for each group on initial render.
+   *
+   * This function establishes the selection state based on a clear precedence:
+   * 1. **Controlled Mode**: If a `Drilldown.Group` has the `selectedOptions` prop
+   * (as an array), it is treated as the absolute source of truth.
+   *
+   * 2. **Uncontrolled Mode**: If `selectedOptions` is not provided, the selection
+   * is determined by `defaultSelected` props, with the following priority:
+   * a. The `defaultSelected` boolean on an individual `Drilldown.Option`.
+   * b. The `defaultSelected` array of values on the `Drilldown.Group`.
+   *
+   * It also validates that 'single' selection groups do not mistakenly receive
+   * multiple selected or default values.
+   *
+   * @returns {SelectedGroupOptionsMap} An object where keys are group IDs and
+   * values are Maps of the selected { optionId: optionValue } pairs for that group.
+   */
+  getSelectedGroupOptionsMap() {
     const selectedGroupOptionsMap = {};
     this.pages.forEach(page => {
       const children = page.props.children;
       this.getChildrenArray(children).forEach(child => {
         if ((0, _matchComponentTypes.matchComponentTypes)(child, [_DrilldownGroup.DrilldownGroup])) {
-          var _this$getChildrenArra;
-          const _child$props = child.props,
-            groupId = _child$props.id,
-            selectableType = _child$props.selectableType,
-            _child$props$defaultS = _child$props.defaultSelected,
-            groupDefaultSelected = _child$props$defaultS === void 0 ? [] : _child$props$defaultS,
-            groupChildren = _child$props.children;
-          if (!selectableType) {
-            return;
-          }
-          if (selectableType && !selectedGroupOptionsMap[groupId]) {
-            selectedGroupOptionsMap[groupId] = new Map();
-          }
-          if (selectableType === 'single' && groupDefaultSelected.length > 1) {
-            (0, _console.error)(false, `Radio type selectable groups can have only one item selected! Group with id "${groupId}" cannot select multiple items: [${groupDefaultSelected.join(', ')}]!`);
-            return;
-          }
+          var _this$getChildrenArra2;
+          const _child$props2 = child.props,
+            groupId = _child$props2.id,
+            selectableType = _child$props2.selectableType,
+            selectedOptions = _child$props2.selectedOptions,
+            _child$props2$default = _child$props2.defaultSelected,
+            defaultSelected = _child$props2$default === void 0 ? [] : _child$props2$default,
+            groupChildren = _child$props2.children;
+          if (!selectableType) return;
           selectedGroupOptionsMap[groupId] = new Map();
-          (_this$getChildrenArra = this.getChildrenArray(groupChildren)) === null || _this$getChildrenArra === void 0 ? void 0 : _this$getChildrenArra.forEach(groupChild => {
+          if (selectableType === 'single') {
+            if (Array.isArray(selectedOptions) && selectedOptions.length > 1) {
+              (0, _console.error)(false, `Radio type selectable groups can have only one item selected! Group "${groupId}" has multiple values: [${selectedOptions.join(', ')}]!`);
+              return;
+            }
+            if (defaultSelected.length > 1) {
+              (0, _console.error)(false, `Radio type selectable groups can have only one default item selected! Group "${groupId}" has multiple values: [${defaultSelected.join(', ')}]!`);
+              return;
+            }
+          }
+          (_this$getChildrenArra2 = this.getChildrenArray(groupChildren)) === null || _this$getChildrenArra2 === void 0 ? void 0 : _this$getChildrenArra2.forEach(groupChild => {
             if ((0, _matchComponentTypes.matchComponentTypes)(groupChild, [_DrilldownOption.DrilldownOption])) {
-              const _groupChild$props = groupChild.props,
-                optionId = _groupChild$props.id,
-                optionValue = _groupChild$props.value,
-                optionDefaultSelected = _groupChild$props.defaultSelected;
-
-              // if explicitly set to false, it should override the group's
-              if (optionDefaultSelected === false) {
-                return;
+              const _groupChild$props2 = groupChild.props,
+                optionId = _groupChild$props2.id,
+                optionValue = _groupChild$props2.value,
+                optionDefaultSelected = _groupChild$props2.defaultSelected;
+              if (optionValue == null) return;
+              let isSelected = false;
+              // If the group is controlled via the `selectedOptions` prop, it is the source of truth.
+              // `defaultSelected` values are ignored.
+              if (Array.isArray(selectedOptions)) {
+                isSelected = selectedOptions.includes(optionValue);
+                // Second strongest is the `defaultSelected` value on the option itself.
+              } else if (optionDefaultSelected === false) {
+                isSelected = false;
+              } else {
+                // Last is the `defaultSelected` array on the group.
+                const isGroupDefaultSelected = defaultSelected.includes(optionValue);
+                isSelected = optionDefaultSelected || isGroupDefaultSelected;
               }
-              const isGroupDefaultSelected = typeof optionValue !== 'undefined' && groupDefaultSelected.filter(value => typeof value !== 'undefined').includes(optionValue);
-              if (optionDefaultSelected || isGroupDefaultSelected) {
+              if (isSelected) {
                 selectedGroupOptionsMap[groupId].set(optionId, optionValue);
               }
             }
@@ -661,8 +734,8 @@ let Drilldown = exports.Drilldown = (_dec = (0, _withDeterministicId.withDetermi
     let containsDuplicate = false;
     const childMap = new Map();
     for (const child of children) {
-      var _child$props2;
-      if (child && typeof child === 'object' && (_child$props2 = child.props) !== null && _child$props2 !== void 0 && _child$props2.id) {
+      var _child$props3;
+      if (child && typeof child === 'object' && (_child$props3 = child.props) !== null && _child$props3 !== void 0 && _child$props3.id) {
         if (!childMap.has(child.props.id)) {
           childMap.set(child.props.id, true);
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-drilldown",
-  "version": "11.0.1",
+  "version": "11.0.2-snapshot-1",
   "description": "A drilldown menu component",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -24,25 +24,25 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.27.6",
-    "@instructure/console": "11.0.1",
-    "@instructure/emotion": "11.0.1",
-    "@instructure/shared-types": "11.0.1",
-    "@instructure/ui-dom-utils": "11.0.1",
-    "@instructure/ui-icons": "11.0.1",
-    "@instructure/ui-options": "11.0.1",
-    "@instructure/ui-popover": "11.0.1",
-    "@instructure/ui-position": "11.0.1",
-    "@instructure/ui-react-utils": "11.0.1",
-    "@instructure/ui-selectable": "11.0.1",
-    "@instructure/ui-utils": "11.0.1",
-    "@instructure/ui-view": "11.0.1"
+    "@instructure/console": "11.0.2-snapshot-1",
+    "@instructure/emotion": "11.0.2-snapshot-1",
+    "@instructure/shared-types": "11.0.2-snapshot-1",
+    "@instructure/ui-dom-utils": "11.0.2-snapshot-1",
+    "@instructure/ui-icons": "11.0.2-snapshot-1",
+    "@instructure/ui-options": "11.0.2-snapshot-1",
+    "@instructure/ui-popover": "11.0.2-snapshot-1",
+    "@instructure/ui-position": "11.0.2-snapshot-1",
+    "@instructure/ui-react-utils": "11.0.2-snapshot-1",
+    "@instructure/ui-selectable": "11.0.2-snapshot-1",
+    "@instructure/ui-utils": "11.0.2-snapshot-1",
+    "@instructure/ui-view": "11.0.2-snapshot-1"
   },
   "devDependencies": {
-    "@instructure/ui-axe-check": "11.0.1",
-    "@instructure/ui-babel-preset": "11.0.1",
-    "@instructure/ui-color-utils": "11.0.1",
-    "@instructure/ui-scripts": "11.0.1",
-    "@instructure/ui-themes": "11.0.1",
+    "@instructure/ui-axe-check": "11.0.2-snapshot-1",
+    "@instructure/ui-babel-preset": "11.0.2-snapshot-1",
+    "@instructure/ui-color-utils": "11.0.2-snapshot-1",
+    "@instructure/ui-scripts": "11.0.2-snapshot-1",
+    "@instructure/ui-themes": "11.0.2-snapshot-1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "@testing-library/user-event": "^14.6.1",

package/src/Drilldown/DrilldownGroup/props.ts

@@ -88,6 +88,12 @@ type DrilldownGroupOwnProps = {
    */
   defaultSelected?: DrilldownOptionValue[]
 
+  /**
+   * An array of the values for the selected items. If defined, the component will act controlled and will not manage its own state. Works only with "selectableType" set.
+   * If "selectableType" is "single", the array has to have 1 item.
+   */
+  selectedOptions?: DrilldownOptionValue[]
+
   /**
    * Callback fired when an option within the `<Drilldown.Group />` is selected
    */
@@ -120,6 +126,7 @@ const allowedProps: AllowedPropKeys = [
   'elementRef',
   'selectableType',
   'defaultSelected',
+  'selectedOptions',
   'onSelect'
 ]