@primer/behaviors 1.8.4 → 1.9.0

package/README.md

@@ -7,10 +7,10 @@ Shared behaviors for JavaScript components
 
 ## Documentation
 
-* [Anchored Position](/docs/anchored-position.md)
-* [Focus Trap](/docs/focus-trap.md)
-* [Focus Zone](/docs/focus-zone.md)
-* [Scroll Into View](/docs/scroll-into-view.md)
+- [Anchored Position](/docs/anchored-position.md)
+- [Focus Trap](/docs/focus-trap.md)
+- [Focus Zone](/docs/focus-zone.md)
+- [Scroll Into View](/docs/scroll-into-view.md)
 
 ## Installation
 
@@ -18,8 +18,14 @@ Shared behaviors for JavaScript components
 npm install @primer/behaviors
 ```
 
-or 
+or
 
 ```bash
 yarn add @primer/behaviors
 ```
+
+## Storybook
+
+```bash
+npm run storybook
+```

package/dist/cjs/focus-zone.d.ts

@@ -25,8 +25,9 @@ export type FocusZoneSettings = IterateFocusableElements & {
     abortSignal?: AbortSignal;
     activeDescendantControl?: HTMLElement;
     onActiveDescendantChanged?: (newActiveDescendant: HTMLElement | undefined, previousActiveDescendant: HTMLElement | undefined, directlyActivated: boolean) => void;
-    focusInStrategy?: 'first' | 'closest' | 'previous' | ((previousFocusedElement: Element) => HTMLElement | undefined);
+    focusInStrategy?: 'first' | 'closest' | 'previous' | 'initial' | ((previousFocusedElement: Element) => HTMLElement | undefined);
     preventScroll?: boolean;
+    ignoreHoverEvents?: boolean;
 };
 export declare const isActiveDescendantAttribute = "data-is-active-descendant";
 export declare const activeDescendantActivatedDirectly = "activated-directly";

package/dist/cjs/focus-zone.js

@@ -129,7 +129,7 @@ const activeDescendantActivatedDirectly = 'activated-directly';
 const activeDescendantActivatedIndirectly = 'activated-indirectly';
 const hasActiveDescendantAttribute = 'data-has-active-descendant';
 function focusZone(container, settings) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f;
     const focusableElements = [];
     const savedTabIndex = new WeakMap();
     const bindKeys = (_a = settings === null || settings === void 0 ? void 0 : settings.bindKeys) !== null && _a !== void 0 ? _a : ((settings === null || settings === void 0 ? void 0 : settings.getNextFocusable) ? exports.FocusKeys.ArrowAll : exports.FocusKeys.ArrowVertical) | exports.FocusKeys.HomeAndEnd;
@@ -137,8 +137,10 @@ function focusZone(container, settings) {
     const focusInStrategy = (_c = settings === null || settings === void 0 ? void 0 : settings.focusInStrategy) !== null && _c !== void 0 ? _c : 'previous';
     const activeDescendantControl = settings === null || settings === void 0 ? void 0 : settings.activeDescendantControl;
     const activeDescendantCallback = settings === null || settings === void 0 ? void 0 : settings.onActiveDescendantChanged;
+    const ignoreHoverEvents = (_d = settings === null || settings === void 0 ? void 0 : settings.ignoreHoverEvents) !== null && _d !== void 0 ? _d : false;
     let currentFocusedElement;
-    const preventScroll = (_d = settings === null || settings === void 0 ? void 0 : settings.preventScroll) !== null && _d !== void 0 ? _d : false;
+    const preventScroll = (_e = settings === null || settings === void 0 ? void 0 : settings.preventScroll) !== null && _e !== void 0 ? _e : false;
+    const preventInitialFocus = focusInStrategy === 'initial' && (settings === null || settings === void 0 ? void 0 : settings.activeDescendantControl);
     function getFirstFocusableElement() {
         return focusableElements[0];
     }
@@ -202,7 +204,7 @@ function focusZone(container, settings) {
             }
             element.setAttribute('tabindex', '-1');
         }
-        if (!currentFocusedElement) {
+        if (!currentFocusedElement && !preventInitialFocus) {
             updateFocusedElement(getFirstFocusableElement());
         }
     }
@@ -256,7 +258,8 @@ function focusZone(container, settings) {
     };
     beginFocusManagement(...iterateFocusableElements.iterateFocusableElements(container, iterateFocusableElementsOptions));
     const initialElement = typeof focusInStrategy === 'function' ? focusInStrategy(document.body) : getFirstFocusableElement();
-    updateFocusedElement(initialElement);
+    if (!preventInitialFocus)
+        updateFocusedElement(initialElement);
     const observer = new MutationObserver(mutations => {
         for (const mutation of mutations) {
             for (const removedNode of mutation.removedNodes) {
@@ -290,7 +293,7 @@ function focusZone(container, settings) {
         attributeOldValue: true,
     });
     const controller = new AbortController();
-    const signal = (_e = settings === null || settings === void 0 ? void 0 : settings.abortSignal) !== null && _e !== void 0 ? _e : controller.signal;
+    const signal = (_f = settings === null || settings === void 0 ? void 0 : settings.abortSignal) !== null && _f !== void 0 ? _f : controller.signal;
     signal.addEventListener('abort', () => {
         endFocusManagement(...focusableElements);
     });
@@ -307,18 +310,21 @@ function focusZone(container, settings) {
                 updateFocusedElement(event.target);
             }
         }, { signal });
-        container.addEventListener('mousemove', ({ target }) => {
-            if (!(target instanceof Node)) {
-                return;
-            }
-            const focusableElement = focusableElements.find(element => element.contains(target));
-            if (focusableElement) {
-                updateFocusedElement(focusableElement);
-            }
-        }, { signal, capture: true });
+        if (!ignoreHoverEvents) {
+            container.addEventListener('mousemove', ({ target }) => {
+                if (!(target instanceof Node)) {
+                    return;
+                }
+                const focusableElement = focusableElements.find(element => element.contains(target));
+                if (focusableElement) {
+                    updateFocusedElement(focusableElement);
+                }
+            }, { signal, capture: true });
+        }
         activeDescendantControl.addEventListener('focusin', () => {
             if (!currentFocusedElement) {
-                updateFocusedElement(getFirstFocusableElement());
+                if (!preventInitialFocus)
+                    updateFocusedElement(getFirstFocusableElement());
             }
             else {
                 setActiveDescendant(undefined, currentFocusedElement);
@@ -386,7 +392,7 @@ function focusZone(container, settings) {
     }
     function getCurrentFocusedIndex() {
         if (!currentFocusedElement) {
-            return 0;
+            return preventInitialFocus ? -1 : 0;
         }
         const focusedIndex = focusableElements.indexOf(currentFocusedElement);
         const fallbackIndex = currentFocusedElement === container ? -1 : 0;

package/dist/esm/focus-zone.d.ts

@@ -25,8 +25,9 @@ export type FocusZoneSettings = IterateFocusableElements & {
     abortSignal?: AbortSignal;
     activeDescendantControl?: HTMLElement;
     onActiveDescendantChanged?: (newActiveDescendant: HTMLElement | undefined, previousActiveDescendant: HTMLElement | undefined, directlyActivated: boolean) => void;
-    focusInStrategy?: 'first' | 'closest' | 'previous' | ((previousFocusedElement: Element) => HTMLElement | undefined);
+    focusInStrategy?: 'first' | 'closest' | 'previous' | 'initial' | ((previousFocusedElement: Element) => HTMLElement | undefined);
     preventScroll?: boolean;
+    ignoreHoverEvents?: boolean;
 };
 export declare const isActiveDescendantAttribute = "data-is-active-descendant";
 export declare const activeDescendantActivatedDirectly = "activated-directly";

package/dist/esm/focus-zone.mjs

@@ -127,7 +127,7 @@ const activeDescendantActivatedDirectly = 'activated-directly';
 const activeDescendantActivatedIndirectly = 'activated-indirectly';
 const hasActiveDescendantAttribute = 'data-has-active-descendant';
 function focusZone(container, settings) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f;
     const focusableElements = [];
     const savedTabIndex = new WeakMap();
     const bindKeys = (_a = settings === null || settings === void 0 ? void 0 : settings.bindKeys) !== null && _a !== void 0 ? _a : ((settings === null || settings === void 0 ? void 0 : settings.getNextFocusable) ? FocusKeys.ArrowAll : FocusKeys.ArrowVertical) | FocusKeys.HomeAndEnd;
@@ -135,8 +135,10 @@ function focusZone(container, settings) {
     const focusInStrategy = (_c = settings === null || settings === void 0 ? void 0 : settings.focusInStrategy) !== null && _c !== void 0 ? _c : 'previous';
     const activeDescendantControl = settings === null || settings === void 0 ? void 0 : settings.activeDescendantControl;
     const activeDescendantCallback = settings === null || settings === void 0 ? void 0 : settings.onActiveDescendantChanged;
+    const ignoreHoverEvents = (_d = settings === null || settings === void 0 ? void 0 : settings.ignoreHoverEvents) !== null && _d !== void 0 ? _d : false;
     let currentFocusedElement;
-    const preventScroll = (_d = settings === null || settings === void 0 ? void 0 : settings.preventScroll) !== null && _d !== void 0 ? _d : false;
+    const preventScroll = (_e = settings === null || settings === void 0 ? void 0 : settings.preventScroll) !== null && _e !== void 0 ? _e : false;
+    const preventInitialFocus = focusInStrategy === 'initial' && (settings === null || settings === void 0 ? void 0 : settings.activeDescendantControl);
     function getFirstFocusableElement() {
         return focusableElements[0];
     }
@@ -200,7 +202,7 @@ function focusZone(container, settings) {
             }
             element.setAttribute('tabindex', '-1');
         }
-        if (!currentFocusedElement) {
+        if (!currentFocusedElement && !preventInitialFocus) {
             updateFocusedElement(getFirstFocusableElement());
         }
     }
@@ -254,7 +256,8 @@ function focusZone(container, settings) {
     };
     beginFocusManagement(...iterateFocusableElements(container, iterateFocusableElementsOptions));
     const initialElement = typeof focusInStrategy === 'function' ? focusInStrategy(document.body) : getFirstFocusableElement();
-    updateFocusedElement(initialElement);
+    if (!preventInitialFocus)
+        updateFocusedElement(initialElement);
     const observer = new MutationObserver(mutations => {
         for (const mutation of mutations) {
             for (const removedNode of mutation.removedNodes) {
@@ -288,7 +291,7 @@ function focusZone(container, settings) {
         attributeOldValue: true,
     });
     const controller = new AbortController();
-    const signal = (_e = settings === null || settings === void 0 ? void 0 : settings.abortSignal) !== null && _e !== void 0 ? _e : controller.signal;
+    const signal = (_f = settings === null || settings === void 0 ? void 0 : settings.abortSignal) !== null && _f !== void 0 ? _f : controller.signal;
     signal.addEventListener('abort', () => {
         endFocusManagement(...focusableElements);
     });
@@ -305,18 +308,21 @@ function focusZone(container, settings) {
                 updateFocusedElement(event.target);
             }
         }, { signal });
-        container.addEventListener('mousemove', ({ target }) => {
-            if (!(target instanceof Node)) {
-                return;
-            }
-            const focusableElement = focusableElements.find(element => element.contains(target));
-            if (focusableElement) {
-                updateFocusedElement(focusableElement);
-            }
-        }, { signal, capture: true });
+        if (!ignoreHoverEvents) {
+            container.addEventListener('mousemove', ({ target }) => {
+                if (!(target instanceof Node)) {
+                    return;
+                }
+                const focusableElement = focusableElements.find(element => element.contains(target));
+                if (focusableElement) {
+                    updateFocusedElement(focusableElement);
+                }
+            }, { signal, capture: true });
+        }
         activeDescendantControl.addEventListener('focusin', () => {
             if (!currentFocusedElement) {
-                updateFocusedElement(getFirstFocusableElement());
+                if (!preventInitialFocus)
+                    updateFocusedElement(getFirstFocusableElement());
             }
             else {
                 setActiveDescendant(undefined, currentFocusedElement);
@@ -384,7 +390,7 @@ function focusZone(container, settings) {
     }
     function getCurrentFocusedIndex() {
         if (!currentFocusedElement) {
-            return 0;
+            return preventInitialFocus ? -1 : 0;
         }
         const focusedIndex = focusableElements.indexOf(currentFocusedElement);
         const fallbackIndex = currentFocusedElement === container ? -1 : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/behaviors",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "Shared behaviors for JavaScript components",
   "type": "commonjs",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,9 @@
     "prebuild": "npm run clean",
     "release": "npm run build && changeset publish",
     "size-limit": "npm run build && size-limit",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build"
   },
   "repository": {
     "type": "git",
@@ -75,17 +77,21 @@
     "@github/prettier-config": "^0.0.6",
     "@rollup/plugin-typescript": "^12.1.0",
     "@rollup/wasm-node": "^4.19.1",
-    "@size-limit/preset-small-lib": "^11.1.4",
+    "@size-limit/preset-small-lib": "^12.0.0",
+    "@storybook/react-vite": "^10.0.8",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.5.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.10",
     "@types/react": "^19.0.1",
-    "esbuild": "^0.25.0",
+    "@types/react-dom": "^19.2.3",
+    "clsx": "^2.1.1",
+    "esbuild": "^0.27.0",
     "esbuild-jest": "^0.5.0",
     "eslint": "^8.50.0",
     "eslint-plugin-github": "^5.0.0",
     "eslint-plugin-prettier": "^5.0.0",
+    "eslint-plugin-storybook": "^10.0.8",
     "jest": "^30.0.4",
     "jest-environment-jsdom": "^30.0.4",
     "prettier": "^3.0.3",
@@ -93,7 +99,8 @@
     "react-dom": "^19.0.0",
     "rimraf": "^6.0.1",
     "rollup": "^4.18.0",
-    "size-limit": "^11.1.4",
+    "size-limit": "^12.0.0",
+    "storybook": "^10.0.8",
     "tslib": "^2.8.1",
     "typescript": "^5.2.2"
   }