@elliemae/ds-pagination 3.80.0-next.51 → 3.80.0-next.53

package/dist/esm/parts/DSPaginator/DSPaginatorCTX.js

@@ -0,0 +1,8 @@
+import * as React from "react";
+import { createContext } from "react";
+const defaultContext = {};
+const DSPaginatorContext = createContext(defaultContext);
+export {
+  DSPaginatorContext
+};
+//# sourceMappingURL=DSPaginatorCTX.js.map

package/dist/esm/parts/DSPaginator/DSPaginatorCTX.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../scripts/build/transpile/react-shim.js", "../../../../src/parts/DSPaginator/DSPaginatorCTX.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { createContext } from 'react';\nimport type { usePaginator } from './config/usePaginator.js';\n\nexport interface DSPaginatorCTX extends ReturnType<typeof usePaginator> {}\n\nconst defaultContext = {} as DSPaginatorCTX;\n\n/** Single source of truth for the parts of DSPaginator: props, owner props, floating context, focus tracker. */\nexport const DSPaginatorContext = createContext<DSPaginatorCTX>(defaultContext);\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,qBAAqB;AAK9B,MAAM,iBAAiB,CAAC;AAGjB,MAAM,qBAAqB,cAA8B,cAAc;",
+  "names": []
+}

package/dist/esm/parts/DSPaginator/config/getAmountOfPages.js

@@ -0,0 +1,9 @@
+import * as React from "react";
+const getAmountOfPages = (pageCount, pageIndex) => {
+  const amount = typeof pageCount === "string" ? pageIndex + 1 : pageCount;
+  return Number.isFinite(amount) && amount > 0 ? Math.floor(amount) : 0;
+};
+export {
+  getAmountOfPages
+};
+//# sourceMappingURL=getAmountOfPages.js.map

package/dist/esm/parts/DSPaginator/config/getAmountOfPages.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/getAmountOfPages.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "// same rule as the existing DSPaginator: when the page count is not known (a string, e.g. \"many\"),\n// the user can only reach the pages up to the one after the current\nexport const getAmountOfPages = (pageCount: number | string, pageIndex: number): number => {\n  const amount = typeof pageCount === 'string' ? pageIndex + 1 : pageCount;\n  return Number.isFinite(amount) && amount > 0 ? Math.floor(amount) : 0;\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACEhB,MAAM,mBAAmB,CAAC,WAA4B,cAA8B;AACzF,QAAM,SAAS,OAAO,cAAc,WAAW,YAAY,IAAI;AAC/D,SAAO,OAAO,SAAS,MAAM,KAAK,SAAS,IAAI,KAAK,MAAM,MAAM,IAAI;AACtE;",
+  "names": []
+}

package/dist/esm/parts/DSPaginator/config/getInstanceIds.js

@@ -0,0 +1,10 @@
+import * as React from "react";
+const getHeaderId = (instanceUid) => `ds-paginator-header-${instanceUid}`;
+const getListId = (instanceUid) => `ds-paginator-list-${instanceUid}`;
+const getDialogId = (instanceUid) => `ds-paginator-dialog-${instanceUid}`;
+export {
+  getDialogId,
+  getHeaderId,
+  getListId
+};
+//# sourceMappingURL=getInstanceIds.js.map

package/dist/esm/parts/DSPaginator/config/getInstanceIds.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/getInstanceIds.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "// one place composes the ids so the parts and the aria relationships cannot drift apart\nexport const getHeaderId = (instanceUid: string) => `ds-paginator-header-${instanceUid}`;\nexport const getListId = (instanceUid: string) => `ds-paginator-list-${instanceUid}`;\nexport const getDialogId = (instanceUid: string) => `ds-paginator-dialog-${instanceUid}`;\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACChB,MAAM,cAAc,CAAC,gBAAwB,uBAAuB,WAAW;AAC/E,MAAM,YAAY,CAAC,gBAAwB,qBAAqB,WAAW;AAC3E,MAAM,cAAc,CAAC,gBAAwB,uBAAuB,WAAW;",
+  "names": []
+}

package/dist/esm/parts/DSPaginator/config/navigationKeys.js

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { PAGINATOR_PAGE_JUMP } from "../constants/index.js";
+const NAVIGATION_KEYS = {
+  ArrowDown: (currentPage) => currentPage + 1,
+  ArrowUp: (currentPage) => currentPage - 1,
+  PageDown: (currentPage) => currentPage + PAGINATOR_PAGE_JUMP,
+  PageUp: (currentPage) => currentPage - PAGINATOR_PAGE_JUMP,
+  Home: () => 1,
+  End: (_currentPage, amountOfPages) => amountOfPages
+};
+export {
+  NAVIGATION_KEYS
+};
+//# sourceMappingURL=navigationKeys.js.map

package/dist/esm/parts/DSPaginator/config/navigationKeys.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/navigationKeys.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { PAGINATOR_PAGE_JUMP } from '../constants/index.js';\n\ntype GetTargetPage = (currentPage: number, amountOfPages: number) => number;\n\n// the keys that only MOVE the focus through the options (APG listbox / select-only combobox navigation)\nexport const NAVIGATION_KEYS: Record<string, GetTargetPage> = {\n  ArrowDown: (currentPage) => currentPage + 1,\n  ArrowUp: (currentPage) => currentPage - 1,\n  PageDown: (currentPage) => currentPage + PAGINATOR_PAGE_JUMP,\n  PageUp: (currentPage) => currentPage - PAGINATOR_PAGE_JUMP,\n  Home: () => 1,\n  End: (_currentPage, amountOfPages) => amountOfPages,\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,2BAA2B;AAK7B,MAAM,kBAAiD;AAAA,EAC5D,WAAW,CAAC,gBAAgB,cAAc;AAAA,EAC1C,SAAS,CAAC,gBAAgB,cAAc;AAAA,EACxC,UAAU,CAAC,gBAAgB,cAAc;AAAA,EACzC,QAAQ,CAAC,gBAAgB,cAAc;AAAA,EACvC,MAAM,MAAM;AAAA,EACZ,KAAK,CAAC,cAAc,kBAAkB;AACxC;",
+  "names": []
+}

package/dist/esm/parts/DSPaginator/config/useFocusTracker.js

@@ -0,0 +1,47 @@
+import * as React from "react";
+import { useCallback, useMemo, useState } from "react";
+import { PAGINATOR_REGION_FOCUSES } from "../constants/index.js";
+const getOptionRegionId = (page) => `${PAGINATOR_REGION_FOCUSES.OPTION_PREFIX}${page}`;
+const getPageFromRegion = (region) => {
+  if (!region.startsWith(PAGINATOR_REGION_FOCUSES.OPTION_PREFIX)) return null;
+  return Number(region.slice(PAGINATOR_REGION_FOCUSES.OPTION_PREFIX.length));
+};
+const useFocusTracker = ({ amountOfPages, pageIndex }) => {
+  const [focusRegion, setFocusRegion] = useState(PAGINATOR_REGION_FOCUSES.RESET);
+  const focusedPage = useMemo(() => getPageFromRegion(focusRegion), [focusRegion]);
+  const clampPage = useCallback((page) => Math.min(Math.max(page, 1), amountOfPages), [amountOfPages]);
+  const trackFocusRegionReset = useCallback(() => setFocusRegion(PAGINATOR_REGION_FOCUSES.RESET), []);
+  const trackFocusTrigger = useCallback(() => setFocusRegion(PAGINATOR_REGION_FOCUSES.TRIGGER), []);
+  const trackFocusOption = useCallback(
+    (page) => {
+      if (amountOfPages > 0) setFocusRegion(getOptionRegionId(clampPage(page)));
+    },
+    [amountOfPages, clampPage]
+  );
+  const trackFocusSelectedOption = useCallback(() => trackFocusOption(pageIndex), [pageIndex, trackFocusOption]);
+  return useMemo(
+    () => ({
+      focusRegion,
+      focusedPage,
+      clampPage,
+      trackFocusRegionReset,
+      trackFocusTrigger,
+      trackFocusOption,
+      trackFocusSelectedOption
+    }),
+    [
+      focusRegion,
+      focusedPage,
+      clampPage,
+      trackFocusRegionReset,
+      trackFocusTrigger,
+      trackFocusOption,
+      trackFocusSelectedOption
+    ]
+  );
+};
+export {
+  getOptionRegionId,
+  useFocusTracker
+};
+//# sourceMappingURL=useFocusTracker.js.map

package/dist/esm/parts/DSPaginator/config/useFocusTracker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/useFocusTracker.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { useCallback, useMemo, useState } from 'react';\nimport { PAGINATOR_REGION_FOCUSES } from '../constants/index.js';\n\ntype FocusTrackerConfigT = {\n  amountOfPages: number;\n  pageIndex: number;\n};\n\n// the identity of an option is the page it represents: stable, never the position in the (virtualized) DOM\nexport const getOptionRegionId = (page: number) => `${PAGINATOR_REGION_FOCUSES.OPTION_PREFIX}${page}`;\n\nconst getPageFromRegion = (region: string): number | null => {\n  if (!region.startsWith(PAGINATOR_REGION_FOCUSES.OPTION_PREFIX)) return null;\n  return Number(region.slice(PAGINATOR_REGION_FOCUSES.OPTION_PREFIX.length));\n};\n\n/**\n * Focus tracker (see .github/memories/project_focus_tracker.md): the handlers declare WHAT must receive focus\n * (a semantic identity), each part checks whether it IS that identity, and only the matching part focuses itself\n * from its ref callback. Nothing in here calls `.focus()`.\n */\nexport const useFocusTracker = ({ amountOfPages, pageIndex }: FocusTrackerConfigT) => {\n  const [focusRegion, setFocusRegion] = useState<string>(PAGINATOR_REGION_FOCUSES.RESET);\n\n  const focusedPage = useMemo(() => getPageFromRegion(focusRegion), [focusRegion]);\n\n  const clampPage = useCallback((page: number) => Math.min(Math.max(page, 1), amountOfPages), [amountOfPages]);\n\n  const trackFocusRegionReset = useCallback(() => setFocusRegion(PAGINATOR_REGION_FOCUSES.RESET), []);\n  const trackFocusTrigger = useCallback(() => setFocusRegion(PAGINATOR_REGION_FOCUSES.TRIGGER), []);\n  const trackFocusOption = useCallback(\n    (page: number) => {\n      if (amountOfPages > 0) setFocusRegion(getOptionRegionId(clampPage(page)));\n    },\n    [amountOfPages, clampPage],\n  );\n  const trackFocusSelectedOption = useCallback(() => trackFocusOption(pageIndex), [pageIndex, trackFocusOption]);\n\n  return useMemo(\n    () => ({\n      focusRegion,\n      focusedPage,\n      clampPage,\n      trackFocusRegionReset,\n      trackFocusTrigger,\n      trackFocusOption,\n      trackFocusSelectedOption,\n    }),\n    [\n      focusRegion,\n      focusedPage,\n      clampPage,\n      trackFocusRegionReset,\n      trackFocusTrigger,\n      trackFocusOption,\n      trackFocusSelectedOption,\n    ],\n  );\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,aAAa,SAAS,gBAAgB;AAC/C,SAAS,gCAAgC;AAQlC,MAAM,oBAAoB,CAAC,SAAiB,GAAG,yBAAyB,aAAa,GAAG,IAAI;AAEnG,MAAM,oBAAoB,CAAC,WAAkC;AAC3D,MAAI,CAAC,OAAO,WAAW,yBAAyB,aAAa,EAAG,QAAO;AACvE,SAAO,OAAO,OAAO,MAAM,yBAAyB,cAAc,MAAM,CAAC;AAC3E;AAOO,MAAM,kBAAkB,CAAC,EAAE,eAAe,UAAU,MAA2B;AACpF,QAAM,CAAC,aAAa,cAAc,IAAI,SAAiB,yBAAyB,KAAK;AAErF,QAAM,cAAc,QAAQ,MAAM,kBAAkB,WAAW,GAAG,CAAC,WAAW,CAAC;AAE/E,QAAM,YAAY,YAAY,CAAC,SAAiB,KAAK,IAAI,KAAK,IAAI,MAAM,CAAC,GAAG,aAAa,GAAG,CAAC,aAAa,CAAC;AAE3G,QAAM,wBAAwB,YAAY,MAAM,eAAe,yBAAyB,KAAK,GAAG,CAAC,CAAC;AAClG,QAAM,oBAAoB,YAAY,MAAM,eAAe,yBAAyB,OAAO,GAAG,CAAC,CAAC;AAChG,QAAM,mBAAmB;AAAA,IACvB,CAAC,SAAiB;AAChB,UAAI,gBAAgB,EAAG,gBAAe,kBAAkB,UAAU,IAAI,CAAC,CAAC;AAAA,IAC1E;AAAA,IACA,CAAC,eAAe,SAAS;AAAA,EAC3B;AACA,QAAM,2BAA2B,YAAY,MAAM,iBAAiB,SAAS,GAAG,CAAC,WAAW,gBAAgB,CAAC;AAE7G,SAAO;AAAA,IACL,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/esm/parts/DSPaginator/config/usePaginator.js

@@ -5,12 +5,16 @@ import {
   useMemoMergePropsWithDefault,
   useOwnerProps
 } from "@elliemae/ds-props-helpers";
-import React2, { useEffect, useMemo, useRef, useState } from "react";
+import React2, { useMemo, useRef, useState } from "react";
+import { uid } from "uid";
 import { DSPaginatorPropTypesSchema, defaultProps } from "../react-desc-prop-types.js";
+import { getAmountOfPages } from "./getAmountOfPages.js";
+import { getDialogId, getHeaderId, getListId } from "./getInstanceIds.js";
+import { useFocusTracker } from "./useFocusTracker.js";
+import { usePaginatorFloatingContext } from "./usePaginatorFloatingContext.js";
+import { usePaginatorInteractions } from "./usePaginatorInteractions.js";
+import { usePaginatorSizing } from "./usePaginatorSizing.js";
 import { useValidateProps } from "./useValidateProps.js";
-import { useOnElementResize } from "../../shared/useOnElementOnResize.js";
-import { getOptions } from "./getOptions.js";
-import { usePaginationSearch } from "./usePaginationSearch.js";
 const usePaginator = (propsFromUser) => {
   const propsWithDefault = useMemoMergePropsWithDefault(propsFromUser, defaultProps);
   useValidateProps(propsWithDefault, DSPaginatorPropTypesSchema);
@@ -19,66 +23,86 @@ const usePaginator = (propsFromUser) => {
     propsWithDefault
   );
   const ownerPropsConfig = useOwnerProps(propsWithDefault);
-  const { pageIndex, pageCount, pageDetails } = propsWithDefault;
-  const [isOpened, setIsOpened] = useState(false);
-  const btnRef = useRef(null);
-  const actionRef = useRef({});
-  const widestChildRef = React2.useRef(null);
-  const pageInfoRef = React2.useRef(null);
-  const checkMarkRef = useRef(null);
-  const { width: btnWidth } = useOnElementResize(btnRef);
-  const { width: checkMarkWidth } = useOnElementResize(checkMarkRef);
-  const { width: pageInfoWidth } = useOnElementResize(pageInfoRef);
-  const { width: detailWidth } = useOnElementResize(widestChildRef);
-  const options = useMemo(
-    () => getOptions({ pageCount, pageIndex, pageDetails, pageInfoWidth, checkMarkWidth }),
-    [pageCount, pageIndex, pageDetails, pageInfoWidth, checkMarkWidth]
+  const { pageIndex, pageCount, pageDetails, listWidth } = propsWithDefault;
+  const instanceUid = useMemo(() => uid(5), []);
+  const [isOpen, setIsOpen] = useState(false);
+  const amountOfPages = getAmountOfPages(pageCount, pageIndex);
+  const triggerRef = useRef(null);
+  const chevronRef = useRef(null);
+  const pageInfoRef = useRef(null);
+  const listActionRef = useRef({});
+  const sizing = usePaginatorSizing({
+    pageCount,
+    pageIndex,
+    pageDetails,
+    listWidth,
+    chevronRef,
+    pageInfoRef,
+    listActionRef
+  });
+  const focusTrackers = useFocusTracker({ amountOfPages, pageIndex });
+  const { floatingStyles, floatingContext, handleTriggerRef, floatingInnerRef, floatingNodeRef } = usePaginatorFloatingContext({
+    isOpen,
+    setIsOpen,
+    triggerRef,
+    trackFocusRegionReset: focusTrackers.trackFocusRegionReset,
+    chevronWidth: sizing.chevronWidth
+  });
+  const interactions = usePaginatorInteractions({
+    propsWithDefault,
+    globalAttributes,
+    isOpen,
+    setIsOpen,
+    amountOfPages,
+    focusTrackers,
+    triggerRef,
+    floatingNodeRef,
+    listActionRef
+  });
+  const ids = useMemo(
+    () => ({
+      headerId: getHeaderId(instanceUid),
+      listId: getListId(instanceUid),
+      dialogId: getDialogId(instanceUid)
+    }),
+    [instanceUid]
   );
-  const onKeyDown = usePaginationSearch(pageCount, actionRef);
-  useEffect(() => {
-    if (isOpened) {
-      actionRef.current.setActiveDescendant(pageIndex.toString());
-      actionRef.current.scrollOptionIntoView(pageIndex.toString());
-    }
-  }, [isOpened]);
   return React2.useMemo(
     () => ({
       propsWithDefault,
       xstyledProps,
       globalAttributes,
       ownerPropsConfig,
-      btnRef,
-      btnWidth,
-      pageInfoWidth,
+      isOpen,
+      amountOfPages,
+      focusTrackers,
+      triggerRef,
+      chevronRef,
       pageInfoRef,
-      options,
-      isOpened,
-      detailWidth,
-      actionRef,
-      widestChildRef,
-      checkMarkRef,
-      checkMarkWidth,
-      setIsOpened,
-      onKeyDown
+      listActionRef,
+      floatingStyles,
+      floatingContext,
+      handleTriggerRef,
+      floatingInnerRef,
+      ...sizing,
+      ...ids,
+      ...interactions
     }),
     [
       propsWithDefault,
       xstyledProps,
       globalAttributes,
       ownerPropsConfig,
-      btnRef,
-      btnWidth,
-      pageInfoWidth,
-      options,
-      isOpened,
-      detailWidth,
-      actionRef,
-      widestChildRef,
-      checkMarkRef,
-      checkMarkWidth,
-      pageInfoRef,
-      setIsOpened,
-      onKeyDown
+      isOpen,
+      amountOfPages,
+      focusTrackers,
+      floatingStyles,
+      floatingContext,
+      handleTriggerRef,
+      floatingInnerRef,
+      sizing,
+      ids,
+      interactions
     ]
   );
 };

package/dist/esm/parts/DSPaginator/config/usePaginator.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/usePaginator.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable max-statements */\nimport {\n  useGetGlobalAttributes,\n  useGetXstyledProps,\n  useMemoMergePropsWithDefault,\n  useOwnerProps,\n} from '@elliemae/ds-props-helpers';\nimport React, { useEffect, useMemo, useRef, useState } from 'react';\n\nimport type { DSButtonV3T } from '@elliemae/ds-button-v2';\nimport { type DSPaginatorT, DSPaginatorPropTypesSchema, defaultProps } from '../react-desc-prop-types.js';\nimport { useValidateProps } from './useValidateProps.js';\nimport { useOnElementResize } from '../../shared/useOnElementOnResize.js';\nimport { getOptions } from './getOptions.js';\nimport { usePaginationSearch } from './usePaginationSearch.js';\n\nexport const usePaginator = (propsFromUser: DSPaginatorT.Props) => {\n  // =============================================================================\n  // MERGE WITH DEFAULT AND VALIDATE PROPS\n  // =============================================================================\n  const propsWithDefault = useMemoMergePropsWithDefault<DSPaginatorT.InternalProps>(propsFromUser, defaultProps);\n  useValidateProps(propsWithDefault, DSPaginatorPropTypesSchema);\n  // =============================================================================\n  // XSTYLED PROPS\n  // =============================================================================\n  const xstyledProps = useGetXstyledProps(propsWithDefault);\n  // =============================================================================\n  // GLOBAL ATTRIBUTES\n  // =============================================================================\n  const globalAttributes = useGetGlobalAttributes<DSPaginatorT.InternalProps, HTMLButtonElement, DSButtonV3T.Props>(\n    propsWithDefault,\n  );\n  // =============================================================================\n  // OWNER PROPS\n  // =============================================================================\n  const ownerPropsConfig = useOwnerProps(propsWithDefault);\n  // =============================================================================\n  // AD HOC PER COMPONENT LOGIC\n  // =============================================================================\n\n  const { pageIndex, pageCount, pageDetails } = propsWithDefault;\n\n  const [isOpened, setIsOpened] = useState(false);\n\n  const btnRef = useRef<HTMLButtonElement>(null);\n  const actionRef = useRef<Record<string, (dsId: string) => void>>({});\n  const widestChildRef = React.useRef<HTMLDivElement | null>(null);\n  const pageInfoRef = React.useRef<HTMLDivElement | null>(null);\n  const checkMarkRef = useRef<HTMLDivElement>(null);\n\n  // btnWidth is used to calculate dropdown min-width when pageDetails are provided\n  const { width: btnWidth } = useOnElementResize(btnRef);\n\n  // checkMarkWidth is used to calculate dropdown offset so, when opening the dropdown,\n  // selected page is aligned properly with the available options.\n  // It is also used to calculate paginatorHeader and options custom render.\n  const { width: checkMarkWidth } = useOnElementResize(checkMarkRef);\n  // pageInfoWidth is used to calculate dropdown min-width when pageDetails are provided on segmented pagination\n  // pageInfoWidth || detailWidth\n  const { width: pageInfoWidth } = useOnElementResize(pageInfoRef);\n  // detailWidth is used to calculate dropdown min-width when pageDetails are provided on segmented pagination\n  // pageInfoWidth || detailWidth\n  const { width: detailWidth } = useOnElementResize(widestChildRef);\n  const options = useMemo(\n    () => getOptions({ pageCount, pageIndex, pageDetails, pageInfoWidth, checkMarkWidth }),\n    [pageCount, pageIndex, pageDetails, pageInfoWidth, checkMarkWidth],\n  );\n  // =============================================================================\n  // HELPERS HOOKS CONFIGS\n  // =============================================================================\n  // const eventHandlers = useEventHandlers({ propsWithDefault, instanceUid }); // <-- complex logic should be made atomics this way\n  const onKeyDown = usePaginationSearch(pageCount, actionRef);\n\n  useEffect(() => {\n    if (isOpened) {\n      actionRef.current.setActiveDescendant(pageIndex.toString());\n      actionRef.current.scrollOptionIntoView(pageIndex.toString());\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [isOpened]);\n\n  return React.useMemo(\n    () => ({\n      propsWithDefault,\n      xstyledProps,\n      globalAttributes,\n      ownerPropsConfig,\n      btnRef,\n      btnWidth,\n      pageInfoWidth,\n      pageInfoRef,\n      options,\n      isOpened,\n      detailWidth,\n      actionRef,\n      widestChildRef,\n      checkMarkRef,\n      checkMarkWidth,\n      setIsOpened,\n      onKeyDown,\n    }),\n    [\n      propsWithDefault,\n      xstyledProps,\n      globalAttributes,\n      ownerPropsConfig,\n      btnRef,\n      btnWidth,\n      pageInfoWidth,\n      options,\n      isOpened,\n      detailWidth,\n      actionRef,\n      widestChildRef,\n      checkMarkRef,\n      checkMarkWidth,\n      pageInfoRef,\n      setIsOpened,\n      onKeyDown,\n    ],\n  );\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACCvB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,OAAOA,UAAS,WAAW,SAAS,QAAQ,gBAAgB;AAG5D,SAA4B,4BAA4B,oBAAoB;AAC5E,SAAS,wBAAwB;AACjC,SAAS,0BAA0B;AACnC,SAAS,kBAAkB;AAC3B,SAAS,2BAA2B;AAE7B,MAAM,eAAe,CAAC,kBAAsC;AAIjE,QAAM,mBAAmB,6BAAyD,eAAe,YAAY;AAC7G,mBAAiB,kBAAkB,0BAA0B;AAI7D,QAAM,eAAe,mBAAmB,gBAAgB;AAIxD,QAAM,mBAAmB;AAAA,IACvB;AAAA,EACF;AAIA,QAAM,mBAAmB,cAAc,gBAAgB;AAKvD,QAAM,EAAE,WAAW,WAAW,YAAY,IAAI;AAE9C,QAAM,CAAC,UAAU,WAAW,IAAI,SAAS,KAAK;AAE9C,QAAM,SAAS,OAA0B,IAAI;AAC7C,QAAM,YAAY,OAA+C,CAAC,CAAC;AACnE,QAAM,iBAAiBA,OAAM,OAA8B,IAAI;AAC/D,QAAM,cAAcA,OAAM,OAA8B,IAAI;AAC5D,QAAM,eAAe,OAAuB,IAAI;AAGhD,QAAM,EAAE,OAAO,SAAS,IAAI,mBAAmB,MAAM;AAKrD,QAAM,EAAE,OAAO,eAAe,IAAI,mBAAmB,YAAY;AAGjE,QAAM,EAAE,OAAO,cAAc,IAAI,mBAAmB,WAAW;AAG/D,QAAM,EAAE,OAAO,YAAY,IAAI,mBAAmB,cAAc;AAChE,QAAM,UAAU;AAAA,IACd,MAAM,WAAW,EAAE,WAAW,WAAW,aAAa,eAAe,eAAe,CAAC;AAAA,IACrF,CAAC,WAAW,WAAW,aAAa,eAAe,cAAc;AAAA,EACnE;AAKA,QAAM,YAAY,oBAAoB,WAAW,SAAS;AAE1D,YAAU,MAAM;AACd,QAAI,UAAU;AACZ,gBAAU,QAAQ,oBAAoB,UAAU,SAAS,CAAC;AAC1D,gBAAU,QAAQ,qBAAqB,UAAU,SAAS,CAAC;AAAA,IAC7D;AAAA,EAEF,GAAG,CAAC,QAAQ,CAAC;AAEb,SAAOA,OAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import type { DSButtonV3T } from '@elliemae/ds-button-v2';\nimport type { DSFastListT } from '@elliemae/ds-fast-list';\nimport {\n  useGetGlobalAttributes,\n  useGetXstyledProps,\n  useMemoMergePropsWithDefault,\n  useOwnerProps,\n} from '@elliemae/ds-props-helpers';\nimport React, { useMemo, useRef, useState } from 'react';\nimport { uid } from 'uid';\nimport { DSPaginatorPropTypesSchema, defaultProps, type DSPaginatorT } from '../react-desc-prop-types.js';\nimport { getAmountOfPages } from './getAmountOfPages.js';\nimport { getDialogId, getHeaderId, getListId } from './getInstanceIds.js';\nimport { useFocusTracker } from './useFocusTracker.js';\nimport { usePaginatorFloatingContext } from './usePaginatorFloatingContext.js';\nimport { usePaginatorInteractions } from './usePaginatorInteractions.js';\nimport { usePaginatorSizing } from './usePaginatorSizing.js';\nimport { useValidateProps } from './useValidateProps.js';\n\nexport const usePaginator = (propsFromUser: DSPaginatorT.Props) => {\n  // =============================================================================\n  // MERGE WITH DEFAULT AND VALIDATE PROPS\n  // =============================================================================\n  const propsWithDefault = useMemoMergePropsWithDefault<DSPaginatorT.InternalProps>(propsFromUser, defaultProps);\n  useValidateProps(propsWithDefault, DSPaginatorPropTypesSchema);\n  // =============================================================================\n  // XSTYLED PROPS\n  // =============================================================================\n  const xstyledProps = useGetXstyledProps(propsWithDefault);\n  // =============================================================================\n  // GLOBAL ATTRIBUTES\n  // =============================================================================\n  const globalAttributes = useGetGlobalAttributes<DSPaginatorT.InternalProps, HTMLButtonElement, DSButtonV3T.Props>(\n    propsWithDefault,\n  );\n  // =============================================================================\n  // OWNER PROPS\n  // =============================================================================\n  const ownerPropsConfig = useOwnerProps(propsWithDefault);\n  // =============================================================================\n  // AD HOC PER COMPONENT LOGIC\n  // =============================================================================\n  const { pageIndex, pageCount, pageDetails, listWidth } = propsWithDefault;\n  const instanceUid = useMemo(() => uid(5), []);\n  const [isOpen, setIsOpen] = useState(false);\n  const amountOfPages = getAmountOfPages(pageCount, pageIndex);\n\n  const triggerRef = useRef<HTMLButtonElement | null>(null);\n  const chevronRef = useRef<HTMLElement>(null);\n  const pageInfoRef = useRef<HTMLDivElement>(null);\n  const listActionRef = useRef<DSFastListT.ActionRef>({});\n\n  const sizing = usePaginatorSizing({\n    pageCount,\n    pageIndex,\n    pageDetails,\n    listWidth,\n    chevronRef,\n    pageInfoRef,\n    listActionRef,\n  });\n\n  const focusTrackers = useFocusTracker({ amountOfPages, pageIndex });\n\n  const { floatingStyles, floatingContext, handleTriggerRef, floatingInnerRef, floatingNodeRef } =\n    usePaginatorFloatingContext({\n      isOpen,\n      setIsOpen,\n      triggerRef,\n      trackFocusRegionReset: focusTrackers.trackFocusRegionReset,\n      chevronWidth: sizing.chevronWidth,\n    });\n\n  const interactions = usePaginatorInteractions({\n    propsWithDefault,\n    globalAttributes,\n    isOpen,\n    setIsOpen,\n    amountOfPages,\n    focusTrackers,\n    triggerRef,\n    floatingNodeRef,\n    listActionRef,\n  });\n\n  const ids = useMemo(\n    () => ({\n      headerId: getHeaderId(instanceUid),\n      listId: getListId(instanceUid),\n      dialogId: getDialogId(instanceUid),\n    }),\n    [instanceUid],\n  );\n\n  return React.useMemo(\n    () => ({\n      propsWithDefault,\n      xstyledProps,\n      globalAttributes,\n      ownerPropsConfig,\n      isOpen,\n      amountOfPages,\n      focusTrackers,\n      triggerRef,\n      chevronRef,\n      pageInfoRef,\n      listActionRef,\n      floatingStyles,\n      floatingContext,\n      handleTriggerRef,\n      floatingInnerRef,\n      ...sizing,\n      ...ids,\n      ...interactions,\n    }),\n    [\n      propsWithDefault,\n      xstyledProps,\n      globalAttributes,\n      ownerPropsConfig,\n      isOpen,\n      amountOfPages,\n      focusTrackers,\n      floatingStyles,\n      floatingContext,\n      handleTriggerRef,\n      floatingInnerRef,\n      sizing,\n      ids,\n      interactions,\n    ],\n  );\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACEvB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,OAAOA,UAAS,SAAS,QAAQ,gBAAgB;AACjD,SAAS,WAAW;AACpB,SAAS,4BAA4B,oBAAuC;AAC5E,SAAS,wBAAwB;AACjC,SAAS,aAAa,aAAa,iBAAiB;AACpD,SAAS,uBAAuB;AAChC,SAAS,mCAAmC;AAC5C,SAAS,gCAAgC;AACzC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AAE1B,MAAM,eAAe,CAAC,kBAAsC;AAIjE,QAAM,mBAAmB,6BAAyD,eAAe,YAAY;AAC7G,mBAAiB,kBAAkB,0BAA0B;AAI7D,QAAM,eAAe,mBAAmB,gBAAgB;AAIxD,QAAM,mBAAmB;AAAA,IACvB;AAAA,EACF;AAIA,QAAM,mBAAmB,cAAc,gBAAgB;AAIvD,QAAM,EAAE,WAAW,WAAW,aAAa,UAAU,IAAI;AACzD,QAAM,cAAc,QAAQ,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5C,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAS,KAAK;AAC1C,QAAM,gBAAgB,iBAAiB,WAAW,SAAS;AAE3D,QAAM,aAAa,OAAiC,IAAI;AACxD,QAAM,aAAa,OAAoB,IAAI;AAC3C,QAAM,cAAc,OAAuB,IAAI;AAC/C,QAAM,gBAAgB,OAA8B,CAAC,CAAC;AAEtD,QAAM,SAAS,mBAAmB;AAAA,IAChC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,gBAAgB,gBAAgB,EAAE,eAAe,UAAU,CAAC;AAElE,QAAM,EAAE,gBAAgB,iBAAiB,kBAAkB,kBAAkB,gBAAgB,IAC3F,4BAA4B;AAAA,IAC1B;AAAA,IACA;AAAA,IACA;AAAA,IACA,uBAAuB,cAAc;AAAA,IACrC,cAAc,OAAO;AAAA,EACvB,CAAC;AAEH,QAAM,eAAe,yBAAyB;AAAA,IAC5C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,MAAM;AAAA,IACV,OAAO;AAAA,MACL,UAAU,YAAY,WAAW;AAAA,MACjC,QAAQ,UAAU,WAAW;AAAA,MAC7B,UAAU,YAAY,WAAW;AAAA,IACnC;AAAA,IACA,CAAC,WAAW;AAAA,EACd;AAEA,SAAOA,OAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAG;AAAA,MACH,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;",
   "names": ["React"]
 }

package/dist/esm/parts/DSPaginator/config/usePaginatorFloatingContext.js

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { useFloatingContext } from "@elliemae/ds-floating-context";
+import { useCallback, useMemo, useRef } from "react";
+const usePaginatorFloatingContext = ({
+  isOpen,
+  setIsOpen,
+  triggerRef,
+  trackFocusRegionReset,
+  chevronWidth
+}) => {
+  const floatingNodeRef = useRef(null);
+  const handleClickOutside = useCallback(() => {
+    setIsOpen(false);
+    trackFocusRegionReset();
+  }, [setIsOpen, trackFocusRegionReset]);
+  const handleScopedEscape = useCallback(() => {
+    setIsOpen(false);
+    trackFocusRegionReset();
+  }, [setIsOpen, trackFocusRegionReset]);
+  const floatingContextConfig = useMemo(
+    () => ({
+      // the existing DSPaginator opens upwards (it lives in a footer) and aligns the selected page with the trigger
+      placement: "top-start",
+      placementOrderPreference: ["top-start", "bottom-start"],
+      customOffset: [-(chevronWidth + 7), 2],
+      externallyControlledIsOpen: isOpen,
+      withoutAnimation: true,
+      onClickOutside: handleClickOutside,
+      closeOnEscape: true,
+      onEscape: handleScopedEscape,
+      returnFocusToReference: true,
+      externalReferenceElement: triggerRef.current
+    }),
+    [chevronWidth, handleClickOutside, handleScopedEscape, isOpen, triggerRef]
+  );
+  const { refs: floatingRefs, floatingStyles, context: floatingContext } = useFloatingContext(floatingContextConfig);
+  const handleTriggerRef = useCallback(
+    (node) => {
+      triggerRef.current = node;
+      floatingRefs.setReference(node);
+    },
+    [floatingRefs, triggerRef]
+  );
+  const floatingInnerRef = useCallback(
+    (node) => {
+      floatingNodeRef.current = node;
+      floatingRefs.setFloating(node);
+    },
+    [floatingRefs.setFloating]
+  );
+  return { floatingStyles, floatingContext, handleTriggerRef, floatingInnerRef, floatingNodeRef };
+};
+export {
+  usePaginatorFloatingContext
+};
+//# sourceMappingURL=usePaginatorFloatingContext.js.map

package/dist/esm/parts/DSPaginator/config/usePaginatorFloatingContext.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/usePaginatorFloatingContext.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { useFloatingContext, type DSHookFloatingContextT } from '@elliemae/ds-floating-context';\nimport type React from 'react';\nimport { useCallback, useMemo, useRef } from 'react';\n\ntype FloatingContextConfigT = {\n  isOpen: boolean;\n  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;\n  triggerRef: React.MutableRefObject<HTMLButtonElement | null>;\n  trackFocusRegionReset: () => void;\n  chevronWidth: number;\n};\n\n/**\n * The single point that wires DSPaginator to `useFloatingContext` (same shape as ds-app-picker's one).\n *\n * The open state is owned by the component, so the floating context is \"controlled\" by it\n * (`externallyControlledIsOpen`) and this hook only translates the closing intents of the floating context into it:\n *  - scoped Escape: the floating context routes it to `onEscape` and, because `returnFocusToReference` is on, it also\n *    returns the focus to the trigger. This is the ONLY close path where the floating context moves the focus.\n *  - click outside (panel + trigger): closes, the focus stays where the user clicked.\n * The other close paths (activation, Tab, trigger toggle) live in usePaginatorInteractions.\n */\nexport const usePaginatorFloatingContext = ({\n  isOpen,\n  setIsOpen,\n  triggerRef,\n  trackFocusRegionReset,\n  chevronWidth,\n}: FloatingContextConfigT) => {\n  const floatingNodeRef = useRef<HTMLDivElement | null>(null);\n\n  const handleClickOutside = useCallback(() => {\n    setIsOpen(false);\n    trackFocusRegionReset();\n  }, [setIsOpen, trackFocusRegionReset]);\n\n  const handleScopedEscape = useCallback(() => {\n    setIsOpen(false);\n    trackFocusRegionReset();\n  }, [setIsOpen, trackFocusRegionReset]);\n\n  const floatingContextConfig = useMemo(\n    () =>\n      ({\n        // the existing DSPaginator opens upwards (it lives in a footer) and aligns the selected page with the trigger\n        placement: 'top-start',\n        placementOrderPreference: ['top-start', 'bottom-start'],\n        customOffset: [-(chevronWidth + 7), 2],\n        externallyControlledIsOpen: isOpen,\n        withoutAnimation: true,\n        onClickOutside: handleClickOutside,\n        closeOnEscape: true,\n        onEscape: handleScopedEscape,\n        returnFocusToReference: true,\n        externalReferenceElement: triggerRef.current,\n      }) as DSHookFloatingContextT.Props,\n    [chevronWidth, handleClickOutside, handleScopedEscape, isOpen, triggerRef],\n  );\n\n  const { refs: floatingRefs, floatingStyles, context: floatingContext } = useFloatingContext(floatingContextConfig);\n\n  const handleTriggerRef = useCallback<React.RefCallback<HTMLButtonElement>>(\n    (node) => {\n      // eslint-disable-next-line no-param-reassign\n      triggerRef.current = node;\n      floatingRefs.setReference(node);\n    },\n    [floatingRefs, triggerRef],\n  );\n\n  const floatingInnerRef = useCallback<React.RefCallback<HTMLDivElement>>(\n    (node) => {\n      floatingNodeRef.current = node;\n      (floatingRefs.setFloating as React.RefCallback<HTMLDivElement>)(node);\n    },\n    [floatingRefs.setFloating],\n  );\n\n  return { floatingStyles, floatingContext, handleTriggerRef, floatingInnerRef, floatingNodeRef };\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,0BAAuD;AAEhE,SAAS,aAAa,SAAS,cAAc;AAoBtC,MAAM,8BAA8B,CAAC;AAAA,EAC1C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,kBAAkB,OAA8B,IAAI;AAE1D,QAAM,qBAAqB,YAAY,MAAM;AAC3C,cAAU,KAAK;AACf,0BAAsB;AAAA,EACxB,GAAG,CAAC,WAAW,qBAAqB,CAAC;AAErC,QAAM,qBAAqB,YAAY,MAAM;AAC3C,cAAU,KAAK;AACf,0BAAsB;AAAA,EACxB,GAAG,CAAC,WAAW,qBAAqB,CAAC;AAErC,QAAM,wBAAwB;AAAA,IAC5B,OACG;AAAA;AAAA,MAEC,WAAW;AAAA,MACX,0BAA0B,CAAC,aAAa,cAAc;AAAA,MACtD,cAAc,CAAC,EAAE,eAAe,IAAI,CAAC;AAAA,MACrC,4BAA4B;AAAA,MAC5B,kBAAkB;AAAA,MAClB,gBAAgB;AAAA,MAChB,eAAe;AAAA,MACf,UAAU;AAAA,MACV,wBAAwB;AAAA,MACxB,0BAA0B,WAAW;AAAA,IACvC;AAAA,IACF,CAAC,cAAc,oBAAoB,oBAAoB,QAAQ,UAAU;AAAA,EAC3E;AAEA,QAAM,EAAE,MAAM,cAAc,gBAAgB,SAAS,gBAAgB,IAAI,mBAAmB,qBAAqB;AAEjH,QAAM,mBAAmB;AAAA,IACvB,CAAC,SAAS;AAER,iBAAW,UAAU;AACrB,mBAAa,aAAa,IAAI;AAAA,IAChC;AAAA,IACA,CAAC,cAAc,UAAU;AAAA,EAC3B;AAEA,QAAM,mBAAmB;AAAA,IACvB,CAAC,SAAS;AACR,sBAAgB,UAAU;AAC1B,MAAC,aAAa,YAAkD,IAAI;AAAA,IACtE;AAAA,IACA,CAAC,aAAa,WAAW;AAAA,EAC3B;AAEA,SAAO,EAAE,gBAAgB,iBAAiB,kBAAkB,kBAAkB,gBAAgB;AAChG;",
+  "names": []
+}

package/dist/esm/parts/DSPaginator/config/usePaginatorInteractions.js

@@ -0,0 +1,140 @@
+import * as React from "react";
+import { useCallback, useMemo, useRef } from "react";
+import { PAGINATOR_TYPEAHEAD_RESET_MS } from "../constants/index.js";
+import { NAVIGATION_KEYS } from "./navigationKeys.js";
+const DIGIT_REGEXP = /^[0-9]$/;
+const usePaginatorInteractions = ({
+  propsWithDefault,
+  globalAttributes,
+  isOpen,
+  setIsOpen,
+  amountOfPages,
+  focusTrackers,
+  triggerRef,
+  floatingNodeRef,
+  listActionRef
+}) => {
+  const { pageIndex, pageCount, onPageChange } = propsWithDefault;
+  const {
+    focusedPage,
+    clampPage,
+    trackFocusOption,
+    trackFocusSelectedOption,
+    trackFocusTrigger,
+    trackFocusRegionReset
+  } = focusTrackers;
+  const typeaheadRef = useRef({ buffer: "", lastKeyTimestamp: 0 });
+  const moveFocusToPage = useCallback(
+    (page) => {
+      const targetPage = clampPage(page);
+      trackFocusOption(targetPage);
+      listActionRef.current.scrollTo?.(targetPage - 1, { align: "auto" });
+    },
+    [clampPage, listActionRef, trackFocusOption]
+  );
+  const commitPage = useCallback(
+    (page) => {
+      if (page !== pageIndex) onPageChange(page);
+      setIsOpen(false);
+      trackFocusTrigger();
+    },
+    [onPageChange, pageIndex, setIsOpen, trackFocusTrigger]
+  );
+  const handleTriggerClick = useCallback(
+    (e) => {
+      globalAttributes.onClick?.(e);
+      if (isOpen) {
+        setIsOpen(false);
+        trackFocusTrigger();
+        return;
+      }
+      if (amountOfPages === 0) return;
+      setIsOpen(true);
+      trackFocusSelectedOption();
+    },
+    [amountOfPages, globalAttributes.onClick, isOpen, setIsOpen, trackFocusSelectedOption, trackFocusTrigger]
+  );
+  const handleTriggerKeyDown = useCallback(
+    (e) => {
+      globalAttributes.onKeyDown?.(e);
+      if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+      if (isOpen || amountOfPages === 0) return;
+      e.preventDefault();
+      setIsOpen(true);
+      trackFocusSelectedOption();
+    },
+    [amountOfPages, globalAttributes.onKeyDown, isOpen, setIsOpen, trackFocusSelectedOption]
+  );
+  const handlePanelKeyDownCapture = useCallback(
+    (e) => {
+      if (e.key !== "Tab") return;
+      triggerRef.current?.focus();
+      trackFocusRegionReset();
+      if (focusedPage !== null && focusedPage !== pageIndex) onPageChange(focusedPage);
+      setIsOpen(false);
+    },
+    [focusedPage, onPageChange, pageIndex, setIsOpen, trackFocusRegionReset, triggerRef]
+  );
+  const handleDigitTypeahead = useCallback(
+    (digit) => {
+      if (typeof pageCount === "string") return;
+      const now = Date.now();
+      const typeahead = typeaheadRef.current;
+      if (now - typeahead.lastKeyTimestamp > PAGINATOR_TYPEAHEAD_RESET_MS) typeahead.buffer = "";
+      typeahead.buffer += digit;
+      typeahead.lastKeyTimestamp = now;
+      const targetPage = Number.parseInt(typeahead.buffer, 10);
+      if (targetPage >= 1 && targetPage <= amountOfPages) moveFocusToPage(targetPage);
+    },
+    [amountOfPages, moveFocusToPage, pageCount]
+  );
+  const handlePanelKeyDown = useCallback(
+    (e) => {
+      if (e.ctrlKey || e.metaKey || e.altKey) return;
+      const getTargetPage = NAVIGATION_KEYS[e.key];
+      if (getTargetPage) {
+        e.preventDefault();
+        moveFocusToPage(getTargetPage(focusedPage ?? pageIndex, amountOfPages));
+        return;
+      }
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        if (focusedPage !== null) commitPage(focusedPage);
+        return;
+      }
+      if (DIGIT_REGEXP.test(e.key)) handleDigitTypeahead(e.key);
+    },
+    [amountOfPages, commitPage, focusedPage, handleDigitTypeahead, moveFocusToPage, pageIndex]
+  );
+  const handleBlurOutOfWidget = useCallback(
+    (e) => {
+      const nextFocused = e.relatedTarget;
+      if (!nextFocused) return;
+      if (triggerRef.current?.contains(nextFocused) || floatingNodeRef.current?.contains(nextFocused)) return;
+      trackFocusRegionReset();
+    },
+    [floatingNodeRef, trackFocusRegionReset, triggerRef]
+  );
+  return useMemo(
+    () => ({
+      commitPage,
+      handleTriggerClick,
+      handleTriggerKeyDown,
+      handlePanelKeyDown,
+      handlePanelKeyDownCapture,
+      handleBlurOutOfWidget
+    }),
+    [
+      commitPage,
+      handleTriggerClick,
+      handleTriggerKeyDown,
+      handlePanelKeyDown,
+      handlePanelKeyDownCapture,
+      handleBlurOutOfWidget
+    ]
+  );
+};
+export {
+  usePaginatorInteractions
+};
+//# sourceMappingURL=usePaginatorInteractions.js.map

package/dist/esm/parts/DSPaginator/config/usePaginatorInteractions.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSPaginator/config/usePaginatorInteractions.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import type { DSFastListT } from '@elliemae/ds-fast-list';\nimport type React from 'react';\nimport { useCallback, useMemo, useRef } from 'react';\nimport { PAGINATOR_TYPEAHEAD_RESET_MS } from '../constants/index.js';\nimport { NAVIGATION_KEYS } from './navigationKeys.js';\nimport type { DSPaginatorT } from '../react-desc-prop-types.js';\nimport type { useFocusTracker } from './useFocusTracker.js';\n\ntype InteractionsConfigT = {\n  propsWithDefault: DSPaginatorT.InternalProps;\n  globalAttributes: { onClick?: unknown; onKeyDown?: unknown };\n  isOpen: boolean;\n  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;\n  amountOfPages: number;\n  focusTrackers: ReturnType<typeof useFocusTracker>;\n  triggerRef: React.MutableRefObject<HTMLButtonElement | null>;\n  floatingNodeRef: React.MutableRefObject<HTMLDivElement | null>;\n  listActionRef: React.MutableRefObject<DSFastListT.ActionRef>;\n};\n\nconst DIGIT_REGEXP = /^[0-9]$/;\n\n/**\n * Every user intent on the trigger and on the list. The selection model is the one of a native select:\n *  - moving through the options (arrows, Home/End, PageUp/PageDown, typing a page number) only moves the focus:\n *    `onPageChange` is NOT invoked while navigating, because committing a page is a costly side effect for a paginator\n *  - Enter, Space or a click on an option commits it, closes the list and returns the focus to the trigger\n *  - Tab (and Shift+Tab) commits the focused option, closes the list and continues from the trigger\n *  - Escape (see usePaginatorFloatingContext) and click outside close without committing\n * Handlers only declare focus intents through the focus tracker (see useFocusTracker), with ONE documented exception:\n * Tab (see handlePanelKeyDownCapture).\n */\nexport const usePaginatorInteractions = ({\n  propsWithDefault,\n  globalAttributes,\n  isOpen,\n  setIsOpen,\n  amountOfPages,\n  focusTrackers,\n  triggerRef,\n  floatingNodeRef,\n  listActionRef,\n}: InteractionsConfigT) => {\n  const { pageIndex, pageCount, onPageChange } = propsWithDefault;\n  const {\n    focusedPage,\n    clampPage,\n    trackFocusOption,\n    trackFocusSelectedOption,\n    trackFocusTrigger,\n    trackFocusRegionReset,\n  } = focusTrackers;\n  const typeaheadRef = useRef({ buffer: '', lastKeyTimestamp: 0 });\n\n  // the target option may not be mounted (virtualized): the focus intent is declared, the list is scrolled to it and\n  //   the option focuses itself from its ref callback as soon as it mounts\n  const moveFocusToPage = useCallback(\n    (page: number) => {\n      const targetPage = clampPage(page);\n      trackFocusOption(targetPage);\n      listActionRef.current.scrollTo?.(targetPage - 1, { align: 'auto' });\n    },\n    [clampPage, listActionRef, trackFocusOption],\n  );\n\n  const commitPage = useCallback(\n    (page: number) => {\n      if (page !== pageIndex) onPageChange(page);\n      setIsOpen(false);\n      trackFocusTrigger();\n    },\n    [onPageChange, pageIndex, setIsOpen, trackFocusTrigger],\n  );\n\n  const handleTriggerClick = useCallback(\n    (e: React.MouseEvent<HTMLButtonElement> | React.KeyboardEvent<HTMLButtonElement>) => {\n      (globalAttributes.onClick as ((event: typeof e) => void) | undefined)?.(e);\n      if (isOpen) {\n        setIsOpen(false);\n        trackFocusTrigger();\n        return;\n      }\n      if (amountOfPages === 0) return;\n      setIsOpen(true);\n      trackFocusSelectedOption();\n    },\n    [amountOfPages, globalAttributes.onClick, isOpen, setIsOpen, trackFocusSelectedOption, trackFocusTrigger],\n  );\n\n  // ArrowDown / ArrowUp on the trigger open the list (same as the select-only combobox and the menu button patterns)\n  //   Enter and Space are not handled here: the trigger is a native button and they arrive as a click\n  const handleTriggerKeyDown = useCallback(\n    (e: React.KeyboardEvent<HTMLButtonElement>) => {\n      (globalAttributes.onKeyDown as React.KeyboardEventHandler<HTMLButtonElement> | undefined)?.(e);\n      if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;\n      if (isOpen || amountOfPages === 0) return;\n      e.preventDefault();\n      setIsOpen(true);\n      trackFocusSelectedOption();\n    },\n    [amountOfPages, globalAttributes.onKeyDown, isOpen, setIsOpen, trackFocusSelectedOption],\n  );\n\n  /*\n   * Tab is handled in the CAPTURE phase and moves the focus from the handler: the one exception to \"the ref callbacks\n   * are the only place that calls .focus()\". Tab has a browser default action that runs right after the keydown\n   * handlers return and moves the focus from wherever it IS at that moment. The panel is portaled, so from an option\n   * the default would continue after the portal, not after the trigger: the trigger must hold the focus BEFORE the\n   * default runs, and a post-commit mechanism (tracker -> render -> ref callback) can never be ahead of it.\n   * Same decision as ds-menu-button's `handleMenuTabKeyDownCapture` (see its KNOWN_INTENTIONAL_DEVIATIONS.md).\n   * The tracker is reset (\"nothing to focus\") so nothing can steal the focus back.\n   */\n  const handlePanelKeyDownCapture = useCallback(\n    (e: React.KeyboardEvent<HTMLElement>) => {\n      if (e.key !== 'Tab') return;\n      triggerRef.current?.focus();\n      trackFocusRegionReset();\n      if (focusedPage !== null && focusedPage !== pageIndex) onPageChange(focusedPage);\n      setIsOpen(false);\n    },\n    [focusedPage, onPageChange, pageIndex, setIsOpen, trackFocusRegionReset, triggerRef],\n  );\n\n  const handleDigitTypeahead = useCallback(\n    (digit: string) => {\n      // an unknown page count (string) only exposes the pages up to the next one: nothing meaningful to type\n      if (typeof pageCount === 'string') return;\n      const now = Date.now();\n      const typeahead = typeaheadRef.current;\n      if (now - typeahead.lastKeyTimestamp > PAGINATOR_TYPEAHEAD_RESET_MS) typeahead.buffer = '';\n      typeahead.buffer += digit;\n      typeahead.lastKeyTimestamp = now;\n      const targetPage = Number.parseInt(typeahead.buffer, 10);\n      if (targetPage >= 1 && targetPage <= amountOfPages) moveFocusToPage(targetPage);\n    },\n    [amountOfPages, moveFocusToPage, pageCount],\n  );\n\n  const handlePanelKeyDown = useCallback(\n    (e: React.KeyboardEvent<HTMLElement>) => {\n      if (e.ctrlKey || e.metaKey || e.altKey) return;\n      const getTargetPage = NAVIGATION_KEYS[e.key];\n      if (getTargetPage) {\n        e.preventDefault(); // the list scrolls through the virtualizer, not through the browser\n        moveFocusToPage(getTargetPage(focusedPage ?? pageIndex, amountOfPages));\n        return;\n      }\n      if (e.key === 'Enter' || e.key === ' ') {\n        e.preventDefault();\n        if (focusedPage !== null) commitPage(focusedPage);\n        return;\n      }\n      if (DIGIT_REGEXP.test(e.key)) handleDigitTypeahead(e.key);\n    },\n    [amountOfPages, commitPage, focusedPage, handleDigitTypeahead, moveFocusToPage, pageIndex],\n  );\n\n  /*\n   * The tracker resets when the focus leaves the whole widget (trigger + portaled panel), not on every blur:\n   *  - a blur with no `relatedTarget` is ambiguous (the focused option unmounted because the list scrolled, the\n   *    window lost focus...) and must NOT reset, or an option that is about to mount for a pending focus intent\n   *    would find the intent erased\n   *  - a blur towards the trigger or the panel is internal\n   */\n  const handleBlurOutOfWidget = useCallback(\n    (e: React.FocusEvent<HTMLElement>) => {\n      const nextFocused = e.relatedTarget as Node | null;\n      if (!nextFocused) return;\n      if (triggerRef.current?.contains(nextFocused) || floatingNodeRef.current?.contains(nextFocused)) return;\n      trackFocusRegionReset();\n    },\n    [floatingNodeRef, trackFocusRegionReset, triggerRef],\n  );\n\n  return useMemo(\n    () => ({\n      commitPage,\n      handleTriggerClick,\n      handleTriggerKeyDown,\n      handlePanelKeyDown,\n      handlePanelKeyDownCapture,\n      handleBlurOutOfWidget,\n    }),\n    [\n      commitPage,\n      handleTriggerClick,\n      handleTriggerKeyDown,\n      handlePanelKeyDown,\n      handlePanelKeyDownCapture,\n      handleBlurOutOfWidget,\n    ],\n  );\n};\n"],
+  "mappings": "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",
+  "names": []
+}