@bento/focus-lock 0.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 GoDaddy Operating Company, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# FocusLock
+
+The `@bento/focus-lock` package provides focus management for containing and
+controlling keyboard focus within specific areas of your application. Built on
+top of React ARIA's FocusScope, it ensures focus remains trapped within
+designated boundaries, making it essential for modals, dialogs, drawers, select
+popovers, and other overlay components.
+
+## Installation
+
+```shell
+npm install --save @bento/focus-lock
+```
+
+## Props
+
+The following properties are available to be used on the `FocusLock` component:
+
+| Prop | Type | Required | Description |
+|------|------|----------|------------|
+| `contain` | `boolean` | No | Whether to contain focus within the scope.
+When true, focus will cycle between focusable elements within the scope. |
+| `restoreFocus` | `boolean` | No | Whether to restore focus to the previously focused element when the focus scope unmounts. |
+| `autoFocus` | `boolean` | No | Whether to automatically focus the first focusable element when the focus scope mounts. |
+| `children` | `ReactNode` | No | The content to render inside the focus lock.
+Can be a single element or multiple elements. |
+| `onFocusEnter` | `(e: FocusEvent<Element, Element>) => void` | No | Callback fired when focus enters the scope |
+| `onFocusLeave` | `(e: FocusEvent<Element, Element>) => void` | No | Callback fired when focus leaves the scope |
+| `className` | `string \| ((state: FocusLockState) => string)` | No | Render prop for className |
+| `style` | `((state: FocusLockState) => CSSProperties) \| CSSProperties` | No | Render prop for style |
+| `slot` | `string` | No | A named part of a component that can be customized. This is implemented by the consuming component.
+The exposed slot names of a component are available in the components documentation. |
+| `slots` | `Record<string, object \| Function>` | No | An object that contains the customizations for the slots.
+The main way you interact with the slot system as a consumer. |
+
+For all other properties specified on the `FocusLock` component, they will be
+passed down to the underlying React ARIA FocusScope component.
+
+## Examples
+
+The simplest use case is to wrap your modal or dialog content with `FocusLock`
+and enable focus containment.
+
+<Source language='tsx' code={ SourceBasic } />
+
+Focus scopes can be nested, allowing you to have multiple layers of focus
+containment. When a nested scope is active, focus is trapped within the
+innermost scope.
+
+<Source language='tsx' code={ SourceNested } />
+
+The `FocusLock` component applies data attributes directly to its children
+without introducing a wrapper element. This example demonstrates multiple
+children (backdrop and content).
+
+<Source language='tsx' code={ SourceOverlay } />
+
+When used with a single child, the focus lock applies data attributes to that child element.
+
+<Source language='tsx' code={ SourceSelect } />
+
+Focus lock is particularly useful for multi-step forms where you want to keep focus within the current step.
+
+<Source language='tsx' code={ SourceForm } />
+
+## Customization
+
+The `FocusLock` component is created using the `@bento/slots` package and allows
+assignment of the custom `slot` property for overrides. The component applies
+props to the underlying React ARIA `FocusScope` component and data attributes to
+its children.
+
+### Slots
+
+The `@bento/focus-lock` component is registered as `BentoFocusLock` and can be
+customized using the slot system. See the `@bento/slots` package for more
+information on how to use the `slot` and `slots` properties.
+
+Render prop function receives a state object with the following properties:
+
+```typescript
+interface FocusLockState {
+  hasFocus: boolean;      // Whether focus is currently within the scope
+  isContained: boolean;   // Whether focus is contained (same as contain prop)
+}
+```
+
+### Data Attributes
+
+The following data attributes are automatically applied to the children of the `FocusLock` component:
+
+| Attribute              | Description                                      | Example Values  |
+| ---------------------- | ------------------------------------------------ | --------------- |
+| `data-focus-contained` | Indicates whether focus is contained             | "true" / "false"|
+| `data-has-focus`       | Indicates whether the scope currently has focus  | "true" / "false"|
+
+These data attributes can be targeted using CSS selectors for styling. When
+using data attributes for styling, ensure you scope them properly with a
+className to avoid affecting unrelated elements:
+
+```css
+.my-modal[data-focus-contained="true"] {
+  outline: 2px solid blue;
+}
+
+.my-modal[data-has-focus="true"] {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+```
+
+Apply the scoping className to your FocusLock children:
+
+```tsx
+<FocusLock contain restoreFocus autoFocus>
+  <div className="my-modal">
+    Modal content
+  </div>
+</FocusLock>
+```
+
+## Accessibility
+
+Focus management is crucial for accessibility. The `FocusLock` component ensures
+that keyboard users can navigate within the focus scope using Tab and Shift+Tab,
+focus is trapped within the scope when `contain` is enabled, focus is
+automatically restored to the previously focused element when the scope is
+removed (when `restoreFocus` is enabled), and the first focusable element is
+automatically focused when the scope is mounted (when `autoFocus` is enabled).
+
+When using focus lock, follow these accessibility guidelines:
+
+- Always provide a way to exit the focus scope (e.g., a close button or escape key handler)
+- Use `restoreFocus` to ensure users return to their previous location when the scope is closed
+- Use `autoFocus` to immediately draw attention to important content like modals
+- Consider using `aria-modal` on modal dialogs to provide additional context to screen readers
+- Ensure all focusable elements within the scope are keyboard accessible

package/README.mdx

@@ -0,0 +1,142 @@
+import { Meta, Story, ArgTypes, Controls, Source } from '@storybook/addon-docs/blocks';
+import * as Stories from './focus-lock.stories.tsx';
+
+import SourceBasic from './examples/basic.tsx?raw';
+import SourceNested from './examples/nested.tsx?raw';
+import SourceOverlay from './examples/overlay.tsx?raw';
+import SourceSelect from './examples/select.tsx?raw';
+import SourceForm from './examples/form.tsx?raw';
+
+<Meta of={Stories} name="Overview" />
+
+# FocusLock
+
+The `@bento/focus-lock` package provides focus management for containing and
+controlling keyboard focus within specific areas of your application. Built on
+top of React ARIA's FocusScope, it ensures focus remains trapped within
+designated boundaries, making it essential for modals, dialogs, drawers, select
+popovers, and other overlay components.
+
+## Installation
+
+```shell
+npm install --save @bento/focus-lock
+```
+
+## Props
+
+The following properties are available to be used on the `FocusLock` component:
+
+<ArgTypes of={Stories.Props} />
+
+For all other properties specified on the `FocusLock` component, they will be
+passed down to the underlying React ARIA FocusScope component.
+
+## Examples
+
+The simplest use case is to wrap your modal or dialog content with `FocusLock`
+and enable focus containment.
+
+<Source language='tsx' code={ SourceBasic } />
+<Story of={Stories.Basic} inline />
+<Controls of={Stories.Basic} />
+
+Focus scopes can be nested, allowing you to have multiple layers of focus
+containment. When a nested scope is active, focus is trapped within the
+innermost scope.
+
+<Source language='tsx' code={ SourceNested } />
+<Story of={Stories.Nested} inline />
+<Controls of={Stories.Nested} />
+
+The `FocusLock` component applies data attributes directly to its children
+without introducing a wrapper element. This example demonstrates multiple
+children (backdrop and content).
+
+<Source language='tsx' code={ SourceOverlay } />
+<Story of={Stories.Overlay} inline />
+<Controls of={Stories.Overlay} />
+
+When used with a single child, the focus lock applies data attributes to that child element.
+
+<Source language='tsx' code={ SourceSelect } />
+<Story of={Stories.Select} inline />
+<Controls of={Stories.Select} />
+
+Focus lock is particularly useful for multi-step forms where you want to keep focus within the current step.
+
+<Source language='tsx' code={ SourceForm } />
+<Story of={Stories.Form} inline />
+<Controls of={Stories.Form} />
+
+## Customization
+
+The `FocusLock` component is created using the `@bento/slots` package and allows
+assignment of the custom `slot` property for overrides. The component applies
+props to the underlying React ARIA `FocusScope` component and data attributes to
+its children.
+
+### Slots
+
+The `@bento/focus-lock` component is registered as `BentoFocusLock` and can be
+customized using the slot system. See the `@bento/slots` package for more
+information on how to use the `slot` and `slots` properties.
+
+Render prop function receives a state object with the following properties:
+
+```typescript
+interface FocusLockState {
+  hasFocus: boolean;      // Whether focus is currently within the scope
+  isContained: boolean;   // Whether focus is contained (same as contain prop)
+}
+```
+
+### Data Attributes
+
+The following data attributes are automatically applied to the children of the `FocusLock` component:
+
+| Attribute              | Description                                      | Example Values  |
+| ---------------------- | ------------------------------------------------ | --------------- |
+| `data-focus-contained` | Indicates whether focus is contained             | "true" / "false"|
+| `data-has-focus`       | Indicates whether the scope currently has focus  | "true" / "false"|
+
+These data attributes can be targeted using CSS selectors for styling. When
+using data attributes for styling, ensure you scope them properly with a
+className to avoid affecting unrelated elements:
+
+```css
+.my-modal[data-focus-contained="true"] {
+  outline: 2px solid blue;
+}
+
+.my-modal[data-has-focus="true"] {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+```
+
+Apply the scoping className to your FocusLock children:
+
+```tsx
+<FocusLock contain restoreFocus autoFocus>
+  <div className="my-modal">
+    Modal content
+  </div>
+</FocusLock>
+```
+
+## Accessibility
+
+Focus management is crucial for accessibility. The `FocusLock` component ensures
+that keyboard users can navigate within the focus scope using Tab and Shift+Tab,
+focus is trapped within the scope when `contain` is enabled, focus is
+automatically restored to the previously focused element when the scope is
+removed (when `restoreFocus` is enabled), and the first focusable element is
+automatically focused when the scope is mounted (when `autoFocus` is enabled).
+
+When using focus lock, follow these accessibility guidelines:
+
+- Always provide a way to exit the focus scope (e.g., a close button or escape key handler)
+- Use `restoreFocus` to ensure users return to their previous location when the scope is closed
+- Use `autoFocus` to immediately draw attention to important content like modals
+- Consider using `aria-modal` on modal dialogs to provide additional context to screen readers
+- Ensure all focusable elements within the scope are keyboard accessible

package/dist/index.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+var React = require('react');
+var useDataAttributes = require('@bento/use-data-attributes');
+var interactions = require('@react-aria/interactions');
+var slots = require('@bento/slots');
+var focus = require('@react-aria/focus');
+var useProps = require('@bento/use-props');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+// src/index.tsx
+var FocusLock = slots.withSlots("BentoFocusLock", function FocusLock2(args) {
+  const { contain = false, restoreFocus = false, autoFocus = false, children, onFocusEnter, onFocusLeave } = args;
+  const [hasFocus, setHasFocus] = React.useState(false);
+  const { focusWithinProps } = interactions.useFocusWithin({
+    onFocusWithinChange: function onFocusWithinChange(isFocusWithin) {
+      setHasFocus(isFocusWithin);
+    },
+    onFocusWithin: onFocusEnter,
+    onBlurWithin: onFocusLeave
+  });
+  const state = {
+    hasFocus,
+    isContained: contain
+  };
+  const { apply } = useProps.useProps(args, state);
+  const data = useDataAttributes.useDataAttributes({
+    "focus-contained": contain,
+    "has-focus": hasFocus
+  });
+  if (!children) return null;
+  const spread = apply({ contain, restoreFocus, autoFocus }, ["children", "onFocusEnter", "onFocusLeave"]);
+  const kids = { ...focusWithinProps, ...data };
+  return /* @__PURE__ */ React__default.default.createElement(focus.FocusScope, { ...spread }, React.Children.map(children, function applyDataAttributes(child) {
+    return React.isValidElement(child) ? React.cloneElement(child, kids) : child;
+  }));
+});
+
+exports.FocusLock = FocusLock;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["withSlots","FocusLock","useState","useFocusWithin","useProps","useDataAttributes","React","FocusScope","Children","isValidElement","cloneElement"],"mappings":";;;;;;;;;;;;;;AAiIO,IAAM,SAAA,GAAYA,eAAA,CAAU,gBAAA,EAAkB,SAASC,WAAU,IAAA,EAAsB;AAC5F,EAAA,MAAM,EAAE,OAAA,GAAU,KAAA,EAAO,YAAA,GAAe,KAAA,EAAO,YAAY,KAAA,EAAO,QAAA,EAAU,YAAA,EAAc,YAAA,EAAa,GAAI,IAAA;AAC3G,EAAA,MAAM,CAAC,QAAA,EAAU,WAAW,CAAA,GAAIC,eAAS,KAAK,CAAA;AAG9C,EAAA,MAAM,EAAE,gBAAA,EAAiB,GAAIC,2BAAA,CAAe;AAAA,IAC1C,mBAAA,EAAqB,SAAS,mBAAA,CAAoB,aAAA,EAAe;AAC/D,MAAA,WAAA,CAAY,aAAa,CAAA;AAAA,IAC3B,CAAA;AAAA,IACA,aAAA,EAAe,YAAA;AAAA,IACf,YAAA,EAAc;AAAA,GACf,CAAA;AAGD,EAAA,MAAM,KAAA,GAAwB;AAAA,IAC5B,QAAA;AAAA,IACA,WAAA,EAAa;AAAA,GACf;AAGA,EAAA,MAAM,EAAE,KAAA,EAAM,GAAIC,iBAAA,CAAS,MAAM,KAAK,CAAA;AAGtC,EAAA,MAAM,OAAOC,mCAAA,CAAkB;AAAA,IAC7B,iBAAA,EAAmB,OAAA;AAAA,IACnB,WAAA,EAAa;AAAA,GACd,CAAA;AAED,EAAA,IAAI,CAAC,UAAU,OAAO,IAAA;AAKtB,EAAA,MAAM,MAAA,GAAS,KAAA,CAAM,EAAE,OAAA,EAAS,YAAA,EAAc,SAAA,EAAU,EAAG,CAAC,UAAA,EAAY,cAAA,EAAgB,cAAc,CAAC,CAAA;AAKvG,EAAA,MAAM,IAAA,GAAO,EAAE,GAAG,gBAAA,EAAkB,GAAG,IAAA,EAAK;AAE5C,EAAA,uBACEC,sBAAA,CAAA,aAAA,CAACC,oBAAY,GAAG,MAAA,EAAA,EACbC,eAAS,GAAA,CAAI,QAAA,EAAU,SAAS,mBAAA,CAAoB,KAAA,EAAO;AAC1D,IAAA,OAAOC,qBAAe,KAAK,CAAA,GAAIC,kBAAA,CAAa,KAAA,EAA6B,IAAI,CAAA,GAAI,KAAA;AAAA,EACnF,CAAC,CACH,CAAA;AAEJ,CAAC","file":"index.cjs","sourcesContent":["import React, { Children, cloneElement, isValidElement, type ReactNode, useState } from 'react';\nimport { useDataAttributes } from '@bento/use-data-attributes';\nimport { useFocusWithin } from '@react-aria/interactions';\nimport { withSlots, type Slots } from '@bento/slots';\nimport { FocusScope } from '@react-aria/focus';\nimport { useProps } from '@bento/use-props';\n\n/**\n * State object passed to render prop functions\n * @public\n */\nexport interface FocusLockState {\n  /**\n   * Whether focus is currently within the scope\n   */\n  hasFocus: boolean;\n\n  /**\n   * Whether focus is contained within the scope\n   */\n  isContained: boolean;\n}\n\nexport interface FocusLockProps extends Slots {\n  /**\n   * Whether to contain focus within the scope.\n   * When true, focus will cycle between focusable elements within the scope.\n   *\n   * @default false\n   */\n  contain?: boolean;\n\n  /**\n   * Whether to restore focus to the previously focused element when the focus scope unmounts.\n   *\n   * @default false\n   */\n  restoreFocus?: boolean;\n\n  /**\n   * Whether to automatically focus the first focusable element when the focus scope mounts.\n   *\n   * @default false\n   */\n  autoFocus?: boolean;\n\n  /**\n   * The content to render inside the focus lock.\n   * Can be a single element or multiple elements.\n   */\n  children?: ReactNode;\n\n  /**\n   * Callback fired when focus enters the scope\n   */\n  onFocusEnter?: (e: React.FocusEvent) => void;\n\n  /**\n   * Callback fired when focus leaves the scope\n   */\n  onFocusLeave?: (e: React.FocusEvent) => void;\n\n  /**\n   * Render prop for className\n   */\n  className?: ((state: FocusLockState) => string) | string;\n\n  /**\n   * Render prop for style\n   */\n  style?: ((state: FocusLockState) => React.CSSProperties) | React.CSSProperties;\n}\n\n/**\n * FocusLock manages focus within a scope, preventing focus from escaping and optionally\n * restoring focus when the scope is removed. Built on top of React ARIA's FocusScope.\n *\n * The FocusLock primitive provides essential focus management for modals, dialogs, drawers,\n * select popovers, and other overlay components that need to trap focus within their boundaries.\n *\n * This component does not add any wrapper elements - it applies data attributes directly to\n * its children, allowing for flexible composition with multiple elements or single elements.\n *\n * @component\n * @param args - The properties {@link FocusLockProps} passed to the FocusLock component.\n *\n * @example\n * ```tsx\n * // Overlay with multiple children (backdrop + content)\n * <FocusLock contain restoreFocus autoFocus>\n *   <div slot=\"backdrop\" />\n *   <div slot=\"content\">\n *     <h2>Modal Title</h2>\n *     <button>Close</button>\n *   </div>\n * </FocusLock>\n * ```\n *\n * @example\n * ```tsx\n * // Select popover with single child\n * <FocusLock contain restoreFocus autoFocus>\n *   <div className=\"popover\">\n *     <ListBox>\n *       <ListBoxItem>Option 1</ListBoxItem>\n *       <ListBoxItem>Option 2</ListBoxItem>\n *     </ListBox>\n *   </div>\n * </FocusLock>\n * ```\n *\n * @example\n * ```tsx\n * // With render props for dynamic styling\n * <FocusLock\n *   contain\n *   className={({ hasFocus, isContained }) =>\n *     `modal ${isContained ? 'contained' : ''} ${hasFocus ? 'focused' : ''}`\n *   }\n *   style={({ hasFocus }) => ({\n *     opacity: hasFocus ? 1 : 0.8\n *   })}\n * >\n *   <div>Content</div>\n * </FocusLock>\n * ```\n *\n * @public\n */\nexport const FocusLock = withSlots('BentoFocusLock', function FocusLock(args: FocusLockProps) {\n  const { contain = false, restoreFocus = false, autoFocus = false, children, onFocusEnter, onFocusLeave } = args;\n  const [hasFocus, setHasFocus] = useState(false);\n\n  // Track focus within the scope using React ARIA\n  const { focusWithinProps } = useFocusWithin({\n    onFocusWithinChange: function onFocusWithinChange(isFocusWithin) {\n      setHasFocus(isFocusWithin);\n    },\n    onFocusWithin: onFocusEnter,\n    onBlurWithin: onFocusLeave\n  });\n\n  // Create state object for render props\n  const state: FocusLockState = {\n    hasFocus,\n    isContained: contain\n  };\n\n  // Pass state to useProps so render props can access it\n  const { apply } = useProps(args, state);\n\n  // Generate data attributes for focus lock state\n  const data = useDataAttributes({\n    'focus-contained': contain,\n    'has-focus': hasFocus\n  });\n\n  if (!children) return null;\n\n  //\n  // Apply props to FocusScope for slot inheritance\n  //\n  const spread = apply({ contain, restoreFocus, autoFocus }, ['children', 'onFocusEnter', 'onFocusLeave']);\n\n  //\n  // Merge focus tracking props with data attributes to apply to children\n  //\n  const kids = { ...focusWithinProps, ...data };\n\n  return (\n    <FocusScope {...spread}>\n      {Children.map(children, function applyDataAttributes(child) {\n        return isValidElement(child) ? cloneElement(child as React.ReactElement, kids) : child;\n      })}\n    </FocusScope>\n  );\n}) as (props: FocusLockProps) => React.ReactElement | null;\n"]}

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+import React, { ReactNode } from 'react';
+import { Slots } from '@bento/slots';
+
+/**
+ * State object passed to render prop functions
+ * @public
+ */
+interface FocusLockState {
+    /**
+     * Whether focus is currently within the scope
+     */
+    hasFocus: boolean;
+    /**
+     * Whether focus is contained within the scope
+     */
+    isContained: boolean;
+}
+interface FocusLockProps extends Slots {
+    /**
+     * Whether to contain focus within the scope.
+     * When true, focus will cycle between focusable elements within the scope.
+     *
+     * @default false
+     */
+    contain?: boolean;
+    /**
+     * Whether to restore focus to the previously focused element when the focus scope unmounts.
+     *
+     * @default false
+     */
+    restoreFocus?: boolean;
+    /**
+     * Whether to automatically focus the first focusable element when the focus scope mounts.
+     *
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * The content to render inside the focus lock.
+     * Can be a single element or multiple elements.
+     */
+    children?: ReactNode;
+    /**
+     * Callback fired when focus enters the scope
+     */
+    onFocusEnter?: (e: React.FocusEvent) => void;
+    /**
+     * Callback fired when focus leaves the scope
+     */
+    onFocusLeave?: (e: React.FocusEvent) => void;
+    /**
+     * Render prop for className
+     */
+    className?: ((state: FocusLockState) => string) | string;
+    /**
+     * Render prop for style
+     */
+    style?: ((state: FocusLockState) => React.CSSProperties) | React.CSSProperties;
+}
+/**
+ * FocusLock manages focus within a scope, preventing focus from escaping and optionally
+ * restoring focus when the scope is removed. Built on top of React ARIA's FocusScope.
+ *
+ * The FocusLock primitive provides essential focus management for modals, dialogs, drawers,
+ * select popovers, and other overlay components that need to trap focus within their boundaries.
+ *
+ * This component does not add any wrapper elements - it applies data attributes directly to
+ * its children, allowing for flexible composition with multiple elements or single elements.
+ *
+ * @component
+ * @param args - The properties {@link FocusLockProps} passed to the FocusLock component.
+ *
+ * @example
+ * ```tsx
+ * // Overlay with multiple children (backdrop + content)
+ * <FocusLock contain restoreFocus autoFocus>
+ *   <div slot="backdrop" />
+ *   <div slot="content">
+ *     <h2>Modal Title</h2>
+ *     <button>Close</button>
+ *   </div>
+ * </FocusLock>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Select popover with single child
+ * <FocusLock contain restoreFocus autoFocus>
+ *   <div className="popover">
+ *     <ListBox>
+ *       <ListBoxItem>Option 1</ListBoxItem>
+ *       <ListBoxItem>Option 2</ListBoxItem>
+ *     </ListBox>
+ *   </div>
+ * </FocusLock>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With render props for dynamic styling
+ * <FocusLock
+ *   contain
+ *   className={({ hasFocus, isContained }) =>
+ *     `modal ${isContained ? 'contained' : ''} ${hasFocus ? 'focused' : ''}`
+ *   }
+ *   style={({ hasFocus }) => ({
+ *     opacity: hasFocus ? 1 : 0.8
+ *   })}
+ * >
+ *   <div>Content</div>
+ * </FocusLock>
+ * ```
+ *
+ * @public
+ */
+declare const FocusLock: (props: FocusLockProps) => React.ReactElement | null;
+
+export { FocusLock, type FocusLockProps, type FocusLockState };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import React, { ReactNode } from 'react';
+import { Slots } from '@bento/slots';
+
+/**
+ * State object passed to render prop functions
+ * @public
+ */
+interface FocusLockState {
+    /**
+     * Whether focus is currently within the scope
+     */
+    hasFocus: boolean;
+    /**
+     * Whether focus is contained within the scope
+     */
+    isContained: boolean;
+}
+interface FocusLockProps extends Slots {
+    /**
+     * Whether to contain focus within the scope.
+     * When true, focus will cycle between focusable elements within the scope.
+     *
+     * @default false
+     */
+    contain?: boolean;
+    /**
+     * Whether to restore focus to the previously focused element when the focus scope unmounts.
+     *
+     * @default false
+     */
+    restoreFocus?: boolean;
+    /**
+     * Whether to automatically focus the first focusable element when the focus scope mounts.
+     *
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * The content to render inside the focus lock.
+     * Can be a single element or multiple elements.
+     */
+    children?: ReactNode;
+    /**
+     * Callback fired when focus enters the scope
+     */
+    onFocusEnter?: (e: React.FocusEvent) => void;
+    /**
+     * Callback fired when focus leaves the scope
+     */
+    onFocusLeave?: (e: React.FocusEvent) => void;
+    /**
+     * Render prop for className
+     */
+    className?: ((state: FocusLockState) => string) | string;
+    /**
+     * Render prop for style
+     */
+    style?: ((state: FocusLockState) => React.CSSProperties) | React.CSSProperties;
+}
+/**
+ * FocusLock manages focus within a scope, preventing focus from escaping and optionally
+ * restoring focus when the scope is removed. Built on top of React ARIA's FocusScope.
+ *
+ * The FocusLock primitive provides essential focus management for modals, dialogs, drawers,
+ * select popovers, and other overlay components that need to trap focus within their boundaries.
+ *
+ * This component does not add any wrapper elements - it applies data attributes directly to
+ * its children, allowing for flexible composition with multiple elements or single elements.
+ *
+ * @component
+ * @param args - The properties {@link FocusLockProps} passed to the FocusLock component.
+ *
+ * @example
+ * ```tsx
+ * // Overlay with multiple children (backdrop + content)
+ * <FocusLock contain restoreFocus autoFocus>
+ *   <div slot="backdrop" />
+ *   <div slot="content">
+ *     <h2>Modal Title</h2>
+ *     <button>Close</button>
+ *   </div>
+ * </FocusLock>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Select popover with single child
+ * <FocusLock contain restoreFocus autoFocus>
+ *   <div className="popover">
+ *     <ListBox>
+ *       <ListBoxItem>Option 1</ListBoxItem>
+ *       <ListBoxItem>Option 2</ListBoxItem>
+ *     </ListBox>
+ *   </div>
+ * </FocusLock>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With render props for dynamic styling
+ * <FocusLock
+ *   contain
+ *   className={({ hasFocus, isContained }) =>
+ *     `modal ${isContained ? 'contained' : ''} ${hasFocus ? 'focused' : ''}`
+ *   }
+ *   style={({ hasFocus }) => ({
+ *     opacity: hasFocus ? 1 : 0.8
+ *   })}
+ * >
+ *   <div>Content</div>
+ * </FocusLock>
+ * ```
+ *
+ * @public
+ */
+declare const FocusLock: (props: FocusLockProps) => React.ReactElement | null;
+
+export { FocusLock, type FocusLockProps, type FocusLockState };

package/dist/index.js

@@ -0,0 +1,38 @@
+import React, { useState, Children, cloneElement, isValidElement } from 'react';
+import { useDataAttributes } from '@bento/use-data-attributes';
+import { useFocusWithin } from '@react-aria/interactions';
+import { withSlots } from '@bento/slots';
+import { FocusScope } from '@react-aria/focus';
+import { useProps } from '@bento/use-props';
+
+// src/index.tsx
+var FocusLock = withSlots("BentoFocusLock", function FocusLock2(args) {
+  const { contain = false, restoreFocus = false, autoFocus = false, children, onFocusEnter, onFocusLeave } = args;
+  const [hasFocus, setHasFocus] = useState(false);
+  const { focusWithinProps } = useFocusWithin({
+    onFocusWithinChange: function onFocusWithinChange(isFocusWithin) {
+      setHasFocus(isFocusWithin);
+    },
+    onFocusWithin: onFocusEnter,
+    onBlurWithin: onFocusLeave
+  });
+  const state = {
+    hasFocus,
+    isContained: contain
+  };
+  const { apply } = useProps(args, state);
+  const data = useDataAttributes({
+    "focus-contained": contain,
+    "has-focus": hasFocus
+  });
+  if (!children) return null;
+  const spread = apply({ contain, restoreFocus, autoFocus }, ["children", "onFocusEnter", "onFocusLeave"]);
+  const kids = { ...focusWithinProps, ...data };
+  return /* @__PURE__ */ React.createElement(FocusScope, { ...spread }, Children.map(children, function applyDataAttributes(child) {
+    return isValidElement(child) ? cloneElement(child, kids) : child;
+  }));
+});
+
+export { FocusLock };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["FocusLock"],"mappings":";;;;;;;;AAiIO,IAAM,SAAA,GAAY,SAAA,CAAU,gBAAA,EAAkB,SAASA,WAAU,IAAA,EAAsB;AAC5F,EAAA,MAAM,EAAE,OAAA,GAAU,KAAA,EAAO,YAAA,GAAe,KAAA,EAAO,YAAY,KAAA,EAAO,QAAA,EAAU,YAAA,EAAc,YAAA,EAAa,GAAI,IAAA;AAC3G,EAAA,MAAM,CAAC,QAAA,EAAU,WAAW,CAAA,GAAI,SAAS,KAAK,CAAA;AAG9C,EAAA,MAAM,EAAE,gBAAA,EAAiB,GAAI,cAAA,CAAe;AAAA,IAC1C,mBAAA,EAAqB,SAAS,mBAAA,CAAoB,aAAA,EAAe;AAC/D,MAAA,WAAA,CAAY,aAAa,CAAA;AAAA,IAC3B,CAAA;AAAA,IACA,aAAA,EAAe,YAAA;AAAA,IACf,YAAA,EAAc;AAAA,GACf,CAAA;AAGD,EAAA,MAAM,KAAA,GAAwB;AAAA,IAC5B,QAAA;AAAA,IACA,WAAA,EAAa;AAAA,GACf;AAGA,EAAA,MAAM,EAAE,KAAA,EAAM,GAAI,QAAA,CAAS,MAAM,KAAK,CAAA;AAGtC,EAAA,MAAM,OAAO,iBAAA,CAAkB;AAAA,IAC7B,iBAAA,EAAmB,OAAA;AAAA,IACnB,WAAA,EAAa;AAAA,GACd,CAAA;AAED,EAAA,IAAI,CAAC,UAAU,OAAO,IAAA;AAKtB,EAAA,MAAM,MAAA,GAAS,KAAA,CAAM,EAAE,OAAA,EAAS,YAAA,EAAc,SAAA,EAAU,EAAG,CAAC,UAAA,EAAY,cAAA,EAAgB,cAAc,CAAC,CAAA;AAKvG,EAAA,MAAM,IAAA,GAAO,EAAE,GAAG,gBAAA,EAAkB,GAAG,IAAA,EAAK;AAE5C,EAAA,uBACE,KAAA,CAAA,aAAA,CAAC,cAAY,GAAG,MAAA,EAAA,EACb,SAAS,GAAA,CAAI,QAAA,EAAU,SAAS,mBAAA,CAAoB,KAAA,EAAO;AAC1D,IAAA,OAAO,eAAe,KAAK,CAAA,GAAI,YAAA,CAAa,KAAA,EAA6B,IAAI,CAAA,GAAI,KAAA;AAAA,EACnF,CAAC,CACH,CAAA;AAEJ,CAAC","file":"index.js","sourcesContent":["import React, { Children, cloneElement, isValidElement, type ReactNode, useState } from 'react';\nimport { useDataAttributes } from '@bento/use-data-attributes';\nimport { useFocusWithin } from '@react-aria/interactions';\nimport { withSlots, type Slots } from '@bento/slots';\nimport { FocusScope } from '@react-aria/focus';\nimport { useProps } from '@bento/use-props';\n\n/**\n * State object passed to render prop functions\n * @public\n */\nexport interface FocusLockState {\n  /**\n   * Whether focus is currently within the scope\n   */\n  hasFocus: boolean;\n\n  /**\n   * Whether focus is contained within the scope\n   */\n  isContained: boolean;\n}\n\nexport interface FocusLockProps extends Slots {\n  /**\n   * Whether to contain focus within the scope.\n   * When true, focus will cycle between focusable elements within the scope.\n   *\n   * @default false\n   */\n  contain?: boolean;\n\n  /**\n   * Whether to restore focus to the previously focused element when the focus scope unmounts.\n   *\n   * @default false\n   */\n  restoreFocus?: boolean;\n\n  /**\n   * Whether to automatically focus the first focusable element when the focus scope mounts.\n   *\n   * @default false\n   */\n  autoFocus?: boolean;\n\n  /**\n   * The content to render inside the focus lock.\n   * Can be a single element or multiple elements.\n   */\n  children?: ReactNode;\n\n  /**\n   * Callback fired when focus enters the scope\n   */\n  onFocusEnter?: (e: React.FocusEvent) => void;\n\n  /**\n   * Callback fired when focus leaves the scope\n   */\n  onFocusLeave?: (e: React.FocusEvent) => void;\n\n  /**\n   * Render prop for className\n   */\n  className?: ((state: FocusLockState) => string) | string;\n\n  /**\n   * Render prop for style\n   */\n  style?: ((state: FocusLockState) => React.CSSProperties) | React.CSSProperties;\n}\n\n/**\n * FocusLock manages focus within a scope, preventing focus from escaping and optionally\n * restoring focus when the scope is removed. Built on top of React ARIA's FocusScope.\n *\n * The FocusLock primitive provides essential focus management for modals, dialogs, drawers,\n * select popovers, and other overlay components that need to trap focus within their boundaries.\n *\n * This component does not add any wrapper elements - it applies data attributes directly to\n * its children, allowing for flexible composition with multiple elements or single elements.\n *\n * @component\n * @param args - The properties {@link FocusLockProps} passed to the FocusLock component.\n *\n * @example\n * ```tsx\n * // Overlay with multiple children (backdrop + content)\n * <FocusLock contain restoreFocus autoFocus>\n *   <div slot=\"backdrop\" />\n *   <div slot=\"content\">\n *     <h2>Modal Title</h2>\n *     <button>Close</button>\n *   </div>\n * </FocusLock>\n * ```\n *\n * @example\n * ```tsx\n * // Select popover with single child\n * <FocusLock contain restoreFocus autoFocus>\n *   <div className=\"popover\">\n *     <ListBox>\n *       <ListBoxItem>Option 1</ListBoxItem>\n *       <ListBoxItem>Option 2</ListBoxItem>\n *     </ListBox>\n *   </div>\n * </FocusLock>\n * ```\n *\n * @example\n * ```tsx\n * // With render props for dynamic styling\n * <FocusLock\n *   contain\n *   className={({ hasFocus, isContained }) =>\n *     `modal ${isContained ? 'contained' : ''} ${hasFocus ? 'focused' : ''}`\n *   }\n *   style={({ hasFocus }) => ({\n *     opacity: hasFocus ? 1 : 0.8\n *   })}\n * >\n *   <div>Content</div>\n * </FocusLock>\n * ```\n *\n * @public\n */\nexport const FocusLock = withSlots('BentoFocusLock', function FocusLock(args: FocusLockProps) {\n  const { contain = false, restoreFocus = false, autoFocus = false, children, onFocusEnter, onFocusLeave } = args;\n  const [hasFocus, setHasFocus] = useState(false);\n\n  // Track focus within the scope using React ARIA\n  const { focusWithinProps } = useFocusWithin({\n    onFocusWithinChange: function onFocusWithinChange(isFocusWithin) {\n      setHasFocus(isFocusWithin);\n    },\n    onFocusWithin: onFocusEnter,\n    onBlurWithin: onFocusLeave\n  });\n\n  // Create state object for render props\n  const state: FocusLockState = {\n    hasFocus,\n    isContained: contain\n  };\n\n  // Pass state to useProps so render props can access it\n  const { apply } = useProps(args, state);\n\n  // Generate data attributes for focus lock state\n  const data = useDataAttributes({\n    'focus-contained': contain,\n    'has-focus': hasFocus\n  });\n\n  if (!children) return null;\n\n  //\n  // Apply props to FocusScope for slot inheritance\n  //\n  const spread = apply({ contain, restoreFocus, autoFocus }, ['children', 'onFocusEnter', 'onFocusLeave']);\n\n  //\n  // Merge focus tracking props with data attributes to apply to children\n  //\n  const kids = { ...focusWithinProps, ...data };\n\n  return (\n    <FocusScope {...spread}>\n      {Children.map(children, function applyDataAttributes(child) {\n        return isValidElement(child) ? cloneElement(child as React.ReactElement, kids) : child;\n      })}\n    </FocusScope>\n  );\n}) as (props: FocusLockProps) => React.ReactElement | null;\n"]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@bento/focus-lock",
+  "version": "0.0.1",
+  "description": "Focus lock primitive for managing focus within a scope",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "scripts": {
+    "build": "tsup-node",
+    "lint": "biome lint && tsc",
+    "posttest": "npm run lint",
+    "prepublishOnly": "node ../../scripts/compile-readme.ts",
+    "pretest": "npm run build",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/godaddy/bento.git"
+  },
+  "keywords": [
+    "accessibility",
+    "aria",
+    "bento",
+    "component",
+    "focus",
+    "focus-lock",
+    "focus-scope",
+    "focus-trap",
+    "library",
+    "react"
+  ],
+  "author": "GoDaddy Operating Company, LLC",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/godaddy/bento/issues"
+  },
+  "homepage": "https://github.com/godaddy/bento#readme",
+  "files": [
+    "dist",
+    "src",
+    "package.json"
+  ],
+  "dependencies": {
+    "@bento/slots": "^0.2.0",
+    "@bento/use-data-attributes": "^0.1.1",
+    "@bento/use-props": "^0.2.0",
+    "@react-aria/focus": "^3.18.6",
+    "@react-aria/interactions": "^3.22.6"
+  },
+  "devDependencies": {
+    "@bento/button": "*",
+    "@bento/container": "*",
+    "@bento/heading": "*",
+    "@bento/listbox": "*",
+    "@bento/radio": "*",
+    "@bento/text": "*"
+  },
+  "peerDependencies": {
+    "react": "18.x || 19.x",
+    "react-dom": "18.x || 19.x"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,177 @@
+import React, { Children, cloneElement, isValidElement, type ReactNode, useState } from 'react';
+import { useDataAttributes } from '@bento/use-data-attributes';
+import { useFocusWithin } from '@react-aria/interactions';
+import { withSlots, type Slots } from '@bento/slots';
+import { FocusScope } from '@react-aria/focus';
+import { useProps } from '@bento/use-props';
+
+/**
+ * State object passed to render prop functions
+ * @public
+ */
+export interface FocusLockState {
+  /**
+   * Whether focus is currently within the scope
+   */
+  hasFocus: boolean;
+
+  /**
+   * Whether focus is contained within the scope
+   */
+  isContained: boolean;
+}
+
+export interface FocusLockProps extends Slots {
+  /**
+   * Whether to contain focus within the scope.
+   * When true, focus will cycle between focusable elements within the scope.
+   *
+   * @default false
+   */
+  contain?: boolean;
+
+  /**
+   * Whether to restore focus to the previously focused element when the focus scope unmounts.
+   *
+   * @default false
+   */
+  restoreFocus?: boolean;
+
+  /**
+   * Whether to automatically focus the first focusable element when the focus scope mounts.
+   *
+   * @default false
+   */
+  autoFocus?: boolean;
+
+  /**
+   * The content to render inside the focus lock.
+   * Can be a single element or multiple elements.
+   */
+  children?: ReactNode;
+
+  /**
+   * Callback fired when focus enters the scope
+   */
+  onFocusEnter?: (e: React.FocusEvent) => void;
+
+  /**
+   * Callback fired when focus leaves the scope
+   */
+  onFocusLeave?: (e: React.FocusEvent) => void;
+
+  /**
+   * Render prop for className
+   */
+  className?: ((state: FocusLockState) => string) | string;
+
+  /**
+   * Render prop for style
+   */
+  style?: ((state: FocusLockState) => React.CSSProperties) | React.CSSProperties;
+}
+
+/**
+ * FocusLock manages focus within a scope, preventing focus from escaping and optionally
+ * restoring focus when the scope is removed. Built on top of React ARIA's FocusScope.
+ *
+ * The FocusLock primitive provides essential focus management for modals, dialogs, drawers,
+ * select popovers, and other overlay components that need to trap focus within their boundaries.
+ *
+ * This component does not add any wrapper elements - it applies data attributes directly to
+ * its children, allowing for flexible composition with multiple elements or single elements.
+ *
+ * @component
+ * @param args - The properties {@link FocusLockProps} passed to the FocusLock component.
+ *
+ * @example
+ * ```tsx
+ * // Overlay with multiple children (backdrop + content)
+ * <FocusLock contain restoreFocus autoFocus>
+ *   <div slot="backdrop" />
+ *   <div slot="content">
+ *     <h2>Modal Title</h2>
+ *     <button>Close</button>
+ *   </div>
+ * </FocusLock>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Select popover with single child
+ * <FocusLock contain restoreFocus autoFocus>
+ *   <div className="popover">
+ *     <ListBox>
+ *       <ListBoxItem>Option 1</ListBoxItem>
+ *       <ListBoxItem>Option 2</ListBoxItem>
+ *     </ListBox>
+ *   </div>
+ * </FocusLock>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With render props for dynamic styling
+ * <FocusLock
+ *   contain
+ *   className={({ hasFocus, isContained }) =>
+ *     `modal ${isContained ? 'contained' : ''} ${hasFocus ? 'focused' : ''}`
+ *   }
+ *   style={({ hasFocus }) => ({
+ *     opacity: hasFocus ? 1 : 0.8
+ *   })}
+ * >
+ *   <div>Content</div>
+ * </FocusLock>
+ * ```
+ *
+ * @public
+ */
+export const FocusLock = withSlots('BentoFocusLock', function FocusLock(args: FocusLockProps) {
+  const { contain = false, restoreFocus = false, autoFocus = false, children, onFocusEnter, onFocusLeave } = args;
+  const [hasFocus, setHasFocus] = useState(false);
+
+  // Track focus within the scope using React ARIA
+  const { focusWithinProps } = useFocusWithin({
+    onFocusWithinChange: function onFocusWithinChange(isFocusWithin) {
+      setHasFocus(isFocusWithin);
+    },
+    onFocusWithin: onFocusEnter,
+    onBlurWithin: onFocusLeave
+  });
+
+  // Create state object for render props
+  const state: FocusLockState = {
+    hasFocus,
+    isContained: contain
+  };
+
+  // Pass state to useProps so render props can access it
+  const { apply } = useProps(args, state);
+
+  // Generate data attributes for focus lock state
+  const data = useDataAttributes({
+    'focus-contained': contain,
+    'has-focus': hasFocus
+  });
+
+  if (!children) return null;
+
+  //
+  // Apply props to FocusScope for slot inheritance
+  //
+  const spread = apply({ contain, restoreFocus, autoFocus }, ['children', 'onFocusEnter', 'onFocusLeave']);
+
+  //
+  // Merge focus tracking props with data attributes to apply to children
+  //
+  const kids = { ...focusWithinProps, ...data };
+
+  return (
+    <FocusScope {...spread}>
+      {Children.map(children, function applyDataAttributes(child) {
+        return isValidElement(child) ? cloneElement(child as React.ReactElement, kids) : child;
+      })}
+    </FocusScope>
+  );
+}) as (props: FocusLockProps) => React.ReactElement | null;