@canonical/react-components 3.5.1 → 3.7.0

package/dist/components/CustomSelect/CustomSelect.d.ts

@@ -19,10 +19,31 @@ export type Props = PropsWithSpread<FieldProps, {
     id?: string | null;
     name?: string;
     disabled?: boolean;
+    /**
+     * Toggle label when no option is selected
+     *
+     * @default - "Select an option"
+     */
+    defaultToggleLabel?: string;
     wrapperClassName?: ClassName;
     toggleClassName?: ClassName;
     dropdownClassName?: string;
-    searchable?: "auto" | "always" | "never";
+    /**
+     * Whether the select is searchable.
+     * - `auto`: the select will be searchable if it has 5 or more options.
+     * - `always`: the select will always be searchable if there is at least 1 option.
+     * - `async`: the select will always be searchable.
+     * - `never`: the select will never be searchable.
+     *
+     * @default - "auto"
+     */
+    searchable?: "auto" | "always" | "async" | "never";
+    /**
+     * Placeholder text for the search input when searchable is enabled.
+     *
+     * @default - "Search"
+     */
+    searchPlaceholder?: string;
     takeFocus?: boolean;
     header?: ReactNode;
     selectRef?: SelectRef;
@@ -33,5 +54,5 @@ export type Props = PropsWithSpread<FieldProps, {
  *
  * The aim of this component is to provide a select component with customisable options and a dropdown menu, whilst maintaining accessibility and usability.
  */
-declare const CustomSelect: ({ value, options, onChange, onSearch, id, name, disabled, success, error, help, wrapperClassName, toggleClassName, dropdownClassName, searchable, takeFocus, header, selectRef, initialPosition, ...fieldProps }: Props) => React.JSX.Element;
+declare const CustomSelect: ({ value, options, onChange, onSearch, id, name, disabled, success, error, help, wrapperClassName, toggleClassName, dropdownClassName, defaultToggleLabel, searchable, searchPlaceholder, takeFocus, header, selectRef, initialPosition, ...fieldProps }: Props) => React.JSX.Element;
 export default CustomSelect;

package/dist/components/CustomSelect/CustomSelect.js

@@ -35,7 +35,9 @@ const CustomSelect = _ref => {
     wrapperClassName,
     toggleClassName,
     dropdownClassName,
+    defaultToggleLabel = "Select an option",
     searchable = "auto",
+    searchPlaceholder = "Search",
     takeFocus,
     header,
     selectRef,
@@ -81,7 +83,7 @@ const CustomSelect = _ref => {
   const selectedOption = options.find(option => option.value === value);
   const toggleLabel = /*#__PURE__*/_react.default.createElement("span", {
     className: "toggle-label u-truncate"
-  }, selectedOption ? selectedOption.selectedLabel || (0, _CustomSelectDropdown.getOptionText)(selectedOption) : "Select an option");
+  }, selectedOption ? selectedOption.selectedLabel || (0, _CustomSelectDropdown.getOptionText)(selectedOption) : defaultToggleLabel);
   const handleSelect = value => {
     var _document$getElementB3;
     (_document$getElementB3 = document.getElementById(selectId)) === null || _document$getElementB3 === void 0 || _document$getElementB3.focus();
@@ -128,6 +130,7 @@ const CustomSelect = _ref => {
     position: initialPosition
   }, close => /*#__PURE__*/_react.default.createElement(_CustomSelectDropdown.default, {
     searchable: searchable,
+    searchPlaceholder: searchPlaceholder,
     onSearch: onSearch,
     name: name || "",
     options: options || [],

package/dist/components/CustomSelect/CustomSelect.stories.d.ts

@@ -32,3 +32,8 @@ export declare const AutoSearchable: Story;
  * Search can be enabled manually by setting `searchable` to `always`.
  */
 export declare const ManualSearchable: Story;
+/**
+ * Search can be enabled manually by setting `searchable` to `async`.
+ * This will always show the search input regardless of the number of options.
+ */
+export declare const AsyncSearchable: Story;

package/dist/components/CustomSelect/CustomSelect.stories.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = exports.StandardOptions = exports.ManualSearchable = exports.DisabledOptions = exports.CustomOptionsAndSelectedLabel = exports.CustomOptions = exports.AutoSearchable = void 0;
+exports.default = exports.StandardOptions = exports.ManualSearchable = exports.DisabledOptions = exports.CustomOptionsAndSelectedLabel = exports.CustomOptions = exports.AutoSearchable = exports.AsyncSearchable = void 0;
 var _CustomSelect = _interopRequireDefault(require("./CustomSelect"));
 var _react = _interopRequireWildcard(require("react"));
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
@@ -150,12 +150,14 @@ const meta = {
   args: {
     name: "customSelect",
     label: "Custom Select",
+    defaultToggleLabel: "Select an option",
     searchable: "auto",
+    searchPlaceholder: "Search",
     initialPosition: "left"
   },
   argTypes: {
     searchable: {
-      options: ["auto", "always", "never"],
+      options: ["auto", "always", "async", "never"],
       control: {
         type: "select"
       }
@@ -231,4 +233,15 @@ const ManualSearchable = exports.ManualSearchable = {
     options: generateStandardOptions(4),
     searchable: "always"
   }
+};
+
+/**
+ * Search can be enabled manually by setting `searchable` to `async`.
+ * This will always show the search input regardless of the number of options.
+ */
+const AsyncSearchable = exports.AsyncSearchable = {
+  args: {
+    options: generateStandardOptions(0),
+    searchable: "async"
+  }
 };

package/dist/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.d.ts

@@ -7,7 +7,8 @@ export type CustomSelectOption = LiHTMLAttributes<HTMLLIElement> & {
     selectedLabel?: ReactNode;
 };
 export type Props = {
-    searchable?: "auto" | "always" | "never";
+    searchable?: "auto" | "always" | "async" | "never";
+    searchPlaceholder?: string;
     name: string;
     options: CustomSelectOption[];
     onSelect: (value: string) => void;

package/dist/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.js

@@ -97,9 +97,28 @@ const getOptionText = option => {
   throw new Error("CustomSelect: options must have a string label or a text property");
 };
 exports.getOptionText = getOptionText;
+const getIsSearchable = (searchable, numberOfOptions) => {
+  if (searchable === "async") {
+    return true;
+  }
+  if (searchable === "never") {
+    return false;
+  }
+  if (numberOfOptions <= 1) {
+    return false;
+  }
+  if (searchable === "always") {
+    return true;
+  }
+  if (searchable === "auto" && numberOfOptions >= 5) {
+    return true;
+  }
+  return false;
+};
 const CustomSelectDropdown = _ref => {
   let {
     searchable,
+    searchPlaceholder,
     name,
     options,
     onSelect,
@@ -116,7 +135,7 @@ const CustomSelectDropdown = _ref => {
   const dropdownRef = (0, _react.useRef)(null);
   const searchRef = (0, _react.useRef)(null);
   const dropdownListRef = (0, _react.useRef)(null);
-  const isSearchable = searchable !== "never" && options.length > 1 && (searchable === "always" || searchable === "auto" && options.length >= 5);
+  const isSearchable = getIsSearchable(searchable, options.length);
   (0, _react.useEffect)(() => {
     if (dropdownRef.current) {
       var _toggle$getBoundingCl, _toggle$getBoundingCl2;
@@ -255,6 +274,7 @@ const CustomSelectDropdown = _ref => {
     name: "select-search-".concat(name),
     type: "text",
     "aria-label": "Search for ".concat(name),
+    placeholder: searchPlaceholder,
     className: "u-no-margin--bottom",
     onChange: handleSearch,
     value: search,
@@ -266,7 +286,8 @@ const CustomSelectDropdown = _ref => {
   }, optionItems));
 };
 CustomSelectDropdown.propTypes = {
-  searchable: _propTypes.default.oneOf(["auto", "always", "never"]),
+  searchable: _propTypes.default.oneOf(["auto", "always", "async", "never"]),
+  searchPlaceholder: _propTypes.default.string,
   name: _propTypes.default.string.isRequired,
   options: _propTypes.default.array.isRequired,
   onSelect: _propTypes.default.func.isRequired,

package/dist/components/Modal/Modal.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import type { HTMLProps, ReactNode } from "react";
+import type { HTMLProps, ReactNode, RefObject } from "react";
 import { ClassName, PropsWithSpread } from "../../types";
 export type Props = PropsWithSpread<{
     /**
@@ -18,6 +18,10 @@ export type Props = PropsWithSpread<{
      * Function to handle closing the modal.
      */
     close?: () => void | null;
+    /**
+     * The element that will be focused upon opening the modal.
+     */
+    focusRef?: RefObject<HTMLElement | null>;
     /**
      * The title of the modal.
      */
@@ -36,5 +40,5 @@ export type Props = PropsWithSpread<{
  *
  * The modal component can be used to overlay an area of the screen which can contain a prompt, dialog or interaction.
  */
-export declare const Modal: ({ buttonRow, children, className, close, title, shouldPropagateClickEvent, closeOnOutsideClick, ...wrapperProps }: Props) => React.JSX.Element;
+export declare const Modal: ({ buttonRow, children, className, close, focusRef, title, shouldPropagateClickEvent, closeOnOutsideClick, ...wrapperProps }: Props) => React.JSX.Element;
 export default Modal;

package/dist/components/Modal/Modal.js

@@ -21,6 +21,7 @@ const Modal = _ref => {
     children,
     className,
     close,
+    focusRef,
     title,
     shouldPropagateClickEvent = false,
     closeOnOutsideClick = true,
@@ -33,6 +34,7 @@ const Modal = _ref => {
   const titleId = (0, _react.useId)();
   const shouldClose = (0, _react.useRef)(false);
   const modalRef = (0, _react.useRef)(null);
+  const closeButtonRef = (0, _react.useRef)(null);
   const focusableModalElements = (0, _react.useRef)(null);
   const handleTabKey = event => {
     if (focusableModalElements.current.length > 0) {
@@ -60,24 +62,18 @@ const Modal = _ref => {
       close();
     }
   };
-  const keyListenersMap = new Map([["Escape", handleEscKey], ["Tab", handleTabKey]]);
   (0, _react.useEffect)(() => {
-    modalRef.current.focus();
-  }, [modalRef]);
-  const hasCloseButton = !!close;
-  (0, _react.useEffect)(() => {
-    var _focusableModalElemen;
-    focusableModalElements.current = modalRef.current.querySelectorAll(focusableElementSelectors);
-    let focusIndex = 0;
-    // when the close button is rendered, focus on the 2nd content element and not the close btn.
-    if (hasCloseButton && focusableModalElements.current.length > 1) {
-      focusIndex = 1;
+    if (focusRef !== null && focusRef !== void 0 && focusRef.current) {
+      focusRef.current.focus();
+    } else if (closeButtonRef.current) {
+      closeButtonRef.current.focus();
+    } else {
+      modalRef.current.focus();
     }
-    (_focusableModalElemen = focusableModalElements.current[focusIndex]) === null || _focusableModalElemen === void 0 || _focusableModalElemen.focus({
-      preventScroll: true
-    });
-  }, [hasCloseButton]);
+    focusableModalElements.current = modalRef.current.querySelectorAll(focusableElementSelectors);
+  }, [focusRef]);
   (0, _react.useEffect)(() => {
+    const keyListenersMap = new Map([["Escape", handleEscKey], ["Tab", handleTabKey]]);
     const keyDown = event => {
       const listener = keyListenersMap.get(event.code);
       return listener && listener(event);
@@ -130,11 +126,12 @@ const Modal = _ref => {
   }, /*#__PURE__*/_react.default.createElement("h2", {
     className: "p-modal__title",
     id: titleId
-  }, title), hasCloseButton && /*#__PURE__*/_react.default.createElement("button", {
+  }, title), close && /*#__PURE__*/_react.default.createElement("button", {
     type: "button",
     className: "p-modal__close",
     "aria-label": "Close active modal",
-    onClick: handleClose
+    onClick: handleClose,
+    ref: closeButtonRef
   }, "Close")), /*#__PURE__*/_react.default.createElement("div", {
     id: descriptionId
   }, children), !!buttonRow && /*#__PURE__*/_react.default.createElement("footer", {

package/dist/components/Modal/Modal.stories.d.ts

@@ -4,3 +4,4 @@ declare const meta: Meta<typeof Modal>;
 export default meta;
 type Story = StoryObj<typeof Modal>;
 export declare const Default: Story;
+export declare const Focus: Story;

package/dist/components/Modal/Modal.stories.js

@@ -3,8 +3,9 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = exports.Default = void 0;
+exports.default = exports.Focus = exports.Default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _Button = _interopRequireDefault(require("../Button"));
 var _Modal = _interopRequireDefault(require("./Modal"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
@@ -61,4 +62,35 @@ const Default = exports.Default = {
     }, /*#__PURE__*/_react.default.createElement("p", null, "This will permanently delete the user \"Simon\".", /*#__PURE__*/_react.default.createElement("br", null), "You cannot undo this action.")) : null);
   },
   name: "Default"
+};
+const Focus = exports.Focus = {
+  render: _ref2 => {
+    let {
+      closeOnOutsideClick
+    } = _ref2;
+    /* eslint-disable react-hooks/rules-of-hooks */
+    const [modalOpen, setModalOpen] = (0, _react.useState)(true);
+    const buttonRef = (0, _react.useRef)(null);
+    /* eslint-enable react-hooks/rules-of-hooks */
+
+    const closeHandler = () => setModalOpen(false);
+    return /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, /*#__PURE__*/_react.default.createElement("button", {
+      onClick: () => setModalOpen(true)
+    }, "Open modal"), modalOpen ? /*#__PURE__*/_react.default.createElement(_Modal.default, {
+      close: closeHandler,
+      title: "Confirm delete",
+      closeOnOutsideClick: closeOnOutsideClick,
+      buttonRow: /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, /*#__PURE__*/_react.default.createElement("button", {
+        className: "u-no-margin--bottom",
+        onClick: closeHandler
+      }, "Cancel"), /*#__PURE__*/_react.default.createElement("button", {
+        className: "p-button--negative u-no-margin--bottom"
+      }, "Delete")),
+      focusRef: buttonRef
+    }, /*#__PURE__*/_react.default.createElement("p", null, "This will permanently delete the user \"Simon\".", /*#__PURE__*/_react.default.createElement("br", null), "You cannot undo this action."), /*#__PURE__*/_react.default.createElement("p", null, /*#__PURE__*/_react.default.createElement(_Button.default, {
+      appearance: "link",
+      ref: buttonRef
+    }, "More information"))) : null);
+  },
+  name: "Focus"
 };

package/dist/esm/components/CustomSelect/CustomSelect.d.ts

@@ -19,10 +19,31 @@ export type Props = PropsWithSpread<FieldProps, {
     id?: string | null;
     name?: string;
     disabled?: boolean;
+    /**
+     * Toggle label when no option is selected
+     *
+     * @default - "Select an option"
+     */
+    defaultToggleLabel?: string;
     wrapperClassName?: ClassName;
     toggleClassName?: ClassName;
     dropdownClassName?: string;
-    searchable?: "auto" | "always" | "never";
+    /**
+     * Whether the select is searchable.
+     * - `auto`: the select will be searchable if it has 5 or more options.
+     * - `always`: the select will always be searchable if there is at least 1 option.
+     * - `async`: the select will always be searchable.
+     * - `never`: the select will never be searchable.
+     *
+     * @default - "auto"
+     */
+    searchable?: "auto" | "always" | "async" | "never";
+    /**
+     * Placeholder text for the search input when searchable is enabled.
+     *
+     * @default - "Search"
+     */
+    searchPlaceholder?: string;
     takeFocus?: boolean;
     header?: ReactNode;
     selectRef?: SelectRef;
@@ -33,5 +54,5 @@ export type Props = PropsWithSpread<FieldProps, {
  *
  * The aim of this component is to provide a select component with customisable options and a dropdown menu, whilst maintaining accessibility and usability.
  */
-declare const CustomSelect: ({ value, options, onChange, onSearch, id, name, disabled, success, error, help, wrapperClassName, toggleClassName, dropdownClassName, searchable, takeFocus, header, selectRef, initialPosition, ...fieldProps }: Props) => React.JSX.Element;
+declare const CustomSelect: ({ value, options, onChange, onSearch, id, name, disabled, success, error, help, wrapperClassName, toggleClassName, dropdownClassName, defaultToggleLabel, searchable, searchPlaceholder, takeFocus, header, selectRef, initialPosition, ...fieldProps }: Props) => React.JSX.Element;
 export default CustomSelect;

package/dist/esm/components/CustomSelect/CustomSelect.js

@@ -1,4 +1,4 @@
-var _excluded = ["value", "options", "onChange", "onSearch", "id", "name", "disabled", "success", "error", "help", "wrapperClassName", "toggleClassName", "dropdownClassName", "searchable", "takeFocus", "header", "selectRef", "initialPosition"];
+var _excluded = ["value", "options", "onChange", "onSearch", "id", "name", "disabled", "success", "error", "help", "wrapperClassName", "toggleClassName", "dropdownClassName", "defaultToggleLabel", "searchable", "searchPlaceholder", "takeFocus", "header", "selectRef", "initialPosition"];
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
@@ -29,7 +29,9 @@ var CustomSelect = _ref => {
       wrapperClassName,
       toggleClassName,
       dropdownClassName,
+      defaultToggleLabel = "Select an option",
       searchable = "auto",
+      searchPlaceholder = "Search",
       takeFocus,
       header,
       selectRef,
@@ -75,7 +77,7 @@ var CustomSelect = _ref => {
   var selectedOption = options.find(option => option.value === value);
   var toggleLabel = /*#__PURE__*/React.createElement("span", {
     className: "toggle-label u-truncate"
-  }, selectedOption ? selectedOption.selectedLabel || getOptionText(selectedOption) : "Select an option");
+  }, selectedOption ? selectedOption.selectedLabel || getOptionText(selectedOption) : defaultToggleLabel);
   var handleSelect = value => {
     var _document$getElementB3;
     (_document$getElementB3 = document.getElementById(selectId)) === null || _document$getElementB3 === void 0 || _document$getElementB3.focus();
@@ -122,6 +124,7 @@ var CustomSelect = _ref => {
     position: initialPosition
   }, close => /*#__PURE__*/React.createElement(CustomSelectDropdown, {
     searchable: searchable,
+    searchPlaceholder: searchPlaceholder,
     onSearch: onSearch,
     name: name || "",
     options: options || [],

package/dist/esm/components/CustomSelect/CustomSelect.stories.d.ts

@@ -32,3 +32,8 @@ export declare const AutoSearchable: Story;
  * Search can be enabled manually by setting `searchable` to `always`.
  */
 export declare const ManualSearchable: Story;
+/**
+ * Search can be enabled manually by setting `searchable` to `async`.
+ * This will always show the search input regardless of the number of options.
+ */
+export declare const AsyncSearchable: Story;

package/dist/esm/components/CustomSelect/CustomSelect.stories.js

@@ -145,12 +145,14 @@ var meta = {
   args: {
     name: "customSelect",
     label: "Custom Select",
+    defaultToggleLabel: "Select an option",
     searchable: "auto",
+    searchPlaceholder: "Search",
     initialPosition: "left"
   },
   argTypes: {
     searchable: {
-      options: ["auto", "always", "never"],
+      options: ["auto", "always", "async", "never"],
       control: {
         type: "select"
       }
@@ -225,4 +227,15 @@ export var ManualSearchable = {
     options: generateStandardOptions(4),
     searchable: "always"
   }
+};
+
+/**
+ * Search can be enabled manually by setting `searchable` to `async`.
+ * This will always show the search input regardless of the number of options.
+ */
+export var AsyncSearchable = {
+  args: {
+    options: generateStandardOptions(0),
+    searchable: "async"
+  }
 };

package/dist/esm/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.d.ts

@@ -7,7 +7,8 @@ export type CustomSelectOption = LiHTMLAttributes<HTMLLIElement> & {
     selectedLabel?: ReactNode;
 };
 export type Props = {
-    searchable?: "auto" | "always" | "never";
+    searchable?: "auto" | "always" | "async" | "never";
+    searchPlaceholder?: string;
     name: string;
     options: CustomSelectOption[];
     onSelect: (value: string) => void;

package/dist/esm/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.js

@@ -83,9 +83,28 @@ export var getOptionText = option => {
   }
   throw new Error("CustomSelect: options must have a string label or a text property");
 };
+var getIsSearchable = (searchable, numberOfOptions) => {
+  if (searchable === "async") {
+    return true;
+  }
+  if (searchable === "never") {
+    return false;
+  }
+  if (numberOfOptions <= 1) {
+    return false;
+  }
+  if (searchable === "always") {
+    return true;
+  }
+  if (searchable === "auto" && numberOfOptions >= 5) {
+    return true;
+  }
+  return false;
+};
 var CustomSelectDropdown = _ref => {
   var {
     searchable,
+    searchPlaceholder,
     name,
     options,
     onSelect,
@@ -102,7 +121,7 @@ var CustomSelectDropdown = _ref => {
   var dropdownRef = useRef(null);
   var searchRef = useRef(null);
   var dropdownListRef = useRef(null);
-  var isSearchable = searchable !== "never" && options.length > 1 && (searchable === "always" || searchable === "auto" && options.length >= 5);
+  var isSearchable = getIsSearchable(searchable, options.length);
   useEffect(() => {
     if (dropdownRef.current) {
       var _toggle$getBoundingCl, _toggle$getBoundingCl2;
@@ -241,6 +260,7 @@ var CustomSelectDropdown = _ref => {
     name: "select-search-".concat(name),
     type: "text",
     "aria-label": "Search for ".concat(name),
+    placeholder: searchPlaceholder,
     className: "u-no-margin--bottom",
     onChange: handleSearch,
     value: search,
@@ -252,7 +272,8 @@ var CustomSelectDropdown = _ref => {
   }, optionItems));
 };
 CustomSelectDropdown.propTypes = {
-  searchable: _pt.oneOf(["auto", "always", "never"]),
+  searchable: _pt.oneOf(["auto", "always", "async", "never"]),
+  searchPlaceholder: _pt.string,
   name: _pt.string.isRequired,
   options: _pt.array.isRequired,
   onSelect: _pt.func.isRequired,

package/dist/esm/components/Modal/Modal.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import type { HTMLProps, ReactNode } from "react";
+import type { HTMLProps, ReactNode, RefObject } from "react";
 import { ClassName, PropsWithSpread } from "../../types";
 export type Props = PropsWithSpread<{
     /**
@@ -18,6 +18,10 @@ export type Props = PropsWithSpread<{
      * Function to handle closing the modal.
      */
     close?: () => void | null;
+    /**
+     * The element that will be focused upon opening the modal.
+     */
+    focusRef?: RefObject<HTMLElement | null>;
     /**
      * The title of the modal.
      */
@@ -36,5 +40,5 @@ export type Props = PropsWithSpread<{
  *
  * The modal component can be used to overlay an area of the screen which can contain a prompt, dialog or interaction.
  */
-export declare const Modal: ({ buttonRow, children, className, close, title, shouldPropagateClickEvent, closeOnOutsideClick, ...wrapperProps }: Props) => React.JSX.Element;
+export declare const Modal: ({ buttonRow, children, className, close, focusRef, title, shouldPropagateClickEvent, closeOnOutsideClick, ...wrapperProps }: Props) => React.JSX.Element;
 export default Modal;

package/dist/esm/components/Modal/Modal.js

@@ -1,4 +1,4 @@
-var _excluded = ["buttonRow", "children", "className", "close", "title", "shouldPropagateClickEvent", "closeOnOutsideClick"];
+var _excluded = ["buttonRow", "children", "className", "close", "focusRef", "title", "shouldPropagateClickEvent", "closeOnOutsideClick"];
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
@@ -15,6 +15,7 @@ export var Modal = _ref => {
       children,
       className,
       close,
+      focusRef,
       title,
       shouldPropagateClickEvent = false,
       closeOnOutsideClick = true
@@ -27,6 +28,7 @@ export var Modal = _ref => {
   var titleId = useId();
   var shouldClose = useRef(false);
   var modalRef = useRef(null);
+  var closeButtonRef = useRef(null);
   var focusableModalElements = useRef(null);
   var handleTabKey = event => {
     if (focusableModalElements.current.length > 0) {
@@ -54,24 +56,18 @@ export var Modal = _ref => {
       close();
     }
   };
-  var keyListenersMap = new Map([["Escape", handleEscKey], ["Tab", handleTabKey]]);
   useEffect(() => {
-    modalRef.current.focus();
-  }, [modalRef]);
-  var hasCloseButton = !!close;
-  useEffect(() => {
-    var _focusableModalElemen;
-    focusableModalElements.current = modalRef.current.querySelectorAll(focusableElementSelectors);
-    var focusIndex = 0;
-    // when the close button is rendered, focus on the 2nd content element and not the close btn.
-    if (hasCloseButton && focusableModalElements.current.length > 1) {
-      focusIndex = 1;
+    if (focusRef !== null && focusRef !== void 0 && focusRef.current) {
+      focusRef.current.focus();
+    } else if (closeButtonRef.current) {
+      closeButtonRef.current.focus();
+    } else {
+      modalRef.current.focus();
     }
-    (_focusableModalElemen = focusableModalElements.current[focusIndex]) === null || _focusableModalElemen === void 0 || _focusableModalElemen.focus({
-      preventScroll: true
-    });
-  }, [hasCloseButton]);
+    focusableModalElements.current = modalRef.current.querySelectorAll(focusableElementSelectors);
+  }, [focusRef]);
   useEffect(() => {
+    var keyListenersMap = new Map([["Escape", handleEscKey], ["Tab", handleTabKey]]);
     var keyDown = event => {
       var listener = keyListenersMap.get(event.code);
       return listener && listener(event);
@@ -124,11 +120,12 @@ export var Modal = _ref => {
   }, /*#__PURE__*/React.createElement("h2", {
     className: "p-modal__title",
     id: titleId
-  }, title), hasCloseButton && /*#__PURE__*/React.createElement("button", {
+  }, title), close && /*#__PURE__*/React.createElement("button", {
     type: "button",
     className: "p-modal__close",
     "aria-label": "Close active modal",
-    onClick: handleClose
+    onClick: handleClose,
+    ref: closeButtonRef
   }, "Close")), /*#__PURE__*/React.createElement("div", {
     id: descriptionId
   }, children), !!buttonRow && /*#__PURE__*/React.createElement("footer", {

package/dist/esm/components/Modal/Modal.stories.d.ts

@@ -4,3 +4,4 @@ declare const meta: Meta<typeof Modal>;
 export default meta;
 type Story = StoryObj<typeof Modal>;
 export declare const Default: Story;
+export declare const Focus: Story;

package/dist/esm/components/Modal/Modal.stories.js

@@ -1,5 +1,6 @@
-import { useState } from "react";
+import { useRef, useState } from "react";
 import React from "react";
+import Button from "../Button";
 import Modal from "./Modal";
 var Template = args => {
   return /*#__PURE__*/React.createElement("div", {
@@ -53,4 +54,35 @@ export var Default = {
     }, /*#__PURE__*/React.createElement("p", null, "This will permanently delete the user \"Simon\".", /*#__PURE__*/React.createElement("br", null), "You cannot undo this action.")) : null);
   },
   name: "Default"
+};
+export var Focus = {
+  render: _ref2 => {
+    var {
+      closeOnOutsideClick
+    } = _ref2;
+    /* eslint-disable react-hooks/rules-of-hooks */
+    var [modalOpen, setModalOpen] = useState(true);
+    var buttonRef = useRef(null);
+    /* eslint-enable react-hooks/rules-of-hooks */
+
+    var closeHandler = () => setModalOpen(false);
+    return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("button", {
+      onClick: () => setModalOpen(true)
+    }, "Open modal"), modalOpen ? /*#__PURE__*/React.createElement(Modal, {
+      close: closeHandler,
+      title: "Confirm delete",
+      closeOnOutsideClick: closeOnOutsideClick,
+      buttonRow: /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("button", {
+        className: "u-no-margin--bottom",
+        onClick: closeHandler
+      }, "Cancel"), /*#__PURE__*/React.createElement("button", {
+        className: "p-button--negative u-no-margin--bottom"
+      }, "Delete")),
+      focusRef: buttonRef
+    }, /*#__PURE__*/React.createElement("p", null, "This will permanently delete the user \"Simon\".", /*#__PURE__*/React.createElement("br", null), "You cannot undo this action."), /*#__PURE__*/React.createElement("p", null, /*#__PURE__*/React.createElement(Button, {
+      appearance: "link",
+      ref: buttonRef
+    }, "More information"))) : null);
+  },
+  name: "Focus"
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonical/react-components",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "author": {
@@ -93,7 +93,7 @@
     "tsc-alias": "1.8.10",
     "typescript": "5.7.3",
     "typescript-eslint": "8.24.1",
-    "vanilla-framework": "4.35.0",
+    "vanilla-framework": "4.37.1",
     "wait-on": "8.0.2",
     "webpack": "5.98.0"
   },