@ringcentral/spring-base 1.11.2 → 1.13.0

package/index.js

@@ -1,16 +1,15 @@
-export { configure, rcConfiguration } from './config.js';
-export { RcResponsiveContext, WindowContext, breakpointList, getMatchDetail, useResponsiveContext, useWindowContext } from './contexts.js';
-export { createGlobalListener, globalListenerEventMap, isElmEqualOrContain, isTouchEvent, moveIndexInTwoDimension, teardown, useA11yKeyEvent, useActive, useAnnouncer, useAriaHideOutside, useAudio, useBodyScrollLock, useButton, useChange, useClickAway, useDebounce, useDepsChange, useEventCallback, useEventListener, useEver, useFocusVisible, useFontLoaded, useForceUpdate, useForkRef, useGlobalListener, useHiddenTabindex, useHover, useHoverDirty, useId, useImgLoaded, useInterval, useIsFocusVisible, useKeyDownOnce, useKeyboardMoveFocus, useLongPress, useMountState, useOnLayoutReRender, useOnReRender, useOnlyOneFocusable, useOverflow, usePrevious, useRefState, useResizeObserver, useResponsiveMatch, useResultRef, useRetry, useSleep, useTabOut, useTestRunnerDetection, useThrottle, useTimeout, useTouchMouseEvent, useVirtuosoExternalWindow, visuallyHiddenStyles } from './hooks.js';
-export { unstable_ownerDocument as ownerDocument, unstable_useControlled as useControlled } from '@mui/utils';
-export { a11yKeyboard, capitalize, checkDefaultPrevented, checkElementName, clearWindowSelection, getSelectionPosition, getTitle, globalStateClasses, isDeleteKeyboardEvent, isSuiElement, isUrl, isWebKit154, omit, outerSize, pick, preloadImg, removeClassName, runKeyHandler, setSelectionPosition, useClasses } from './utils.js';
-export { a as ariaHideOutside, b as combineClasses, c as combineProps, g as getRefElement, i as isRef, l as logInDev, o as ownerWindow, t as twMerge } from './chunks/twMerge.js';
-import 'react';
-import 'lodash/uniqueId';
-import '@mui/base/useButton';
-import 'lodash/omit';
-import 'lodash/pick';
-import 'lodash/isPlainObject';
-import 'lodash/debounce';
-import 'lodash/noop';
-import 'lodash/throttle';
-import 'tailwind-merge';
+
+
+
+
+
+
+
+
+var src_LIVEREGION_TIMEOUT_DELAY = (/* inlined export .LIVEREGION_TIMEOUT_DELAY */7000);
+export { src_LIVEREGION_TIMEOUT_DELAY as LIVEREGION_TIMEOUT_DELAY };
+export { RcResponsiveContext, WindowContext, breakpointList, getMatchDetail, useResponsiveContext, useWindowContext } from "./contexts.js";
+export { a11yKeyboard, ariaHideOutside, capitalize, checkDefaultPrevented, checkElementName, clearWindowSelection, combineClasses, combineProps, getRefElement, getSelectionPosition, getTitle, globalStateClasses, isDeleteKeyboardEvent, isRef, isSuiElement, isUrl, isWebKit154, logInDev, omit, outerSize, ownerDocument, ownerWindow, pick, preloadImg, removeClassName, runKeyHandler, setSelectionPosition, twMerge, useClasses } from "./utils.js";
+export { announce, clearAnnouncer, destroyAnnouncer } from "./liveAnnouncer.js";
+export { configure, rcConfiguration } from "./config.js";
+export { createGlobalListener, globalListenerEventMap, isElmEqualOrContain, isTouchEvent, moveIndexInTwoDimension, teardown, useA11yKeyEvent, useActive, useAnnouncer, useAriaHideOutside, useAudio, useBodyScrollLock, useButton, useChange, useClickAway, useControlled, useDebounce, useDepsChange, useEventCallback, useEventListener, useEver, useFocusVisible, useFontLoaded, useForceUpdate, useForkRef, useGlobalAnnouncer, useGlobalListener, useHiddenTabindex, useHover, useHoverDirty, useId, useImgLoaded, useInterval, useIsFocusVisible, useKeyDownOnce, useKeyboardMoveFocus, useLongPress, useMountState, useOnLayoutReRender, useOnReRender, useOnlyOneFocusable, useOverflow, usePrevious, useRefState, useResizeObserver, useResponsiveMatch, useResultRef, useRetry, useSleep, useTabOut, useTestRunnerDetection, useThrottle, useTimeout, useTouchMouseEvent, useVirtuosoExternalWindow } from "./hooks.js";

package/liveAnnouncer.js

@@ -0,0 +1,303 @@
+/** Matches `[data-live-announcer="true"]` used by `ariaHideOutside`. */ const LIVE_ANNOUNCER_ATTR = 'data-live-announcer';
+/**
+ * Visually hidden styles for live-announcer regions.
+ * Matches `@react-aria/live-announcer` / React Aria VisuallyHidden so the
+ * region stays off-screen without depending on Tailwind `sr-only`.
+ */ const visuallyHiddenStyleProperties = {
+    border: '0',
+    clip: 'rect(0 0 0 0)',
+    clipPath: 'inset(50%)',
+    height: '1px',
+    margin: '-1px',
+    overflow: 'hidden',
+    padding: '0',
+    position: 'absolute',
+    width: '1px',
+    whiteSpace: 'nowrap'
+};
+const applyVisuallyHiddenStyles = (el)=>{
+    Object.assign(el.style, visuallyHiddenStyleProperties);
+};
+
+
+/**
+ * Screen reader will not re-speak an identical live-region addition. Alternate a
+ * leading zero-width space so a repeated string is a new change (same idea as
+ * `useAnnouncer`).
+ */ class RepeatStringText {
+    next(politeness, message) {
+        const useZwsp = this.last[politeness] === message ? !this.usedZwsp[politeness] : false;
+        this.last[politeness] = message;
+        this.usedZwsp[politeness] = useZwsp;
+        return useZwsp ? `\u200B${message}` : message;
+    }
+    reset(politeness) {
+        const channels = politeness ? [
+            politeness
+        ] : [
+            'assertive',
+            'polite'
+        ];
+        for (const channel of channels){
+            this.last[channel] = undefined;
+            this.usedZwsp[channel] = false;
+        }
+    }
+    constructor(){
+        this.last = {};
+        this.usedZwsp = {
+            assertive: false,
+            polite: false
+        };
+    }
+}
+/**
+ * Inspired by `@react-aria/live-announcer`.
+ * Extended for Spring multi-document / detached-window support.
+ *
+ * Vanilla DOM (not React): same rationale as React Aria — avoid ReactDOM
+ * render/createRoot coupling for a global imperative API.
+ */ class LiveAnnouncer {
+    constructor(doc){
+        this.node = null;
+        this.assertiveLog = null;
+        this.politeLog = null;
+        this.repeatText = new RepeatStringText();
+        this.ready = false;
+        this.pending = [];
+        this.firstDelayTimerId = null;
+        this.doc = doc;
+        if (typeof doc === 'undefined' || !doc.body) {
+            return;
+        }
+        this.node = doc.createElement('div');
+        this.node.setAttribute(LIVE_ANNOUNCER_ATTR, 'true');
+        applyVisuallyHiddenStyles(this.node);
+        this.assertiveLog = this.createLog('assertive');
+        this.node.appendChild(this.assertiveLog);
+        this.politeLog = this.createLog('polite');
+        this.node.appendChild(this.politeLog);
+        doc.body.prepend(this.node);
+    }
+    isAttached() {
+        return Boolean(this.node?.isConnected);
+    }
+    createLog(ariaLive) {
+        const node = this.doc.createElement('div');
+        node.setAttribute('role', 'log');
+        node.setAttribute('aria-live', ariaLive);
+        node.setAttribute('aria-relevant', 'additions');
+        return node;
+    }
+    destroy() {
+        this.cancelFirstDelay();
+        if (!this.node) {
+            return;
+        }
+        const parent = this.node.parentNode;
+        if (parent) {
+            parent.removeChild(this.node);
+        }
+        this.node = null;
+        this.assertiveLog = null;
+        this.politeLog = null;
+        this.repeatText.reset();
+    }
+    /**
+   * Queue until the first-announce delay elapses so later calls cannot
+   * overtake the first message.
+   */ schedule(message, politeness = 'assertive', timeout = LIVEREGION_TIMEOUT_DELAY) {
+        if (this.ready || isTestAnnounceEnvironment()) {
+            this.announce(message, politeness, timeout);
+            return;
+        }
+        this.pending.push({
+            message,
+            politeness,
+            timeout
+        });
+        if (this.firstDelayTimerId != null) {
+            return;
+        }
+        const win = this.doc.defaultView ?? globalThis;
+        this.firstDelayTimerId = win.setTimeout(()=>{
+            this.firstDelayTimerId = null;
+            this.ready = true;
+            const queued = this.pending;
+            this.pending = [];
+            for (const item of queued){
+                this.announce(item.message, item.politeness, item.timeout);
+            }
+        }, FIRST_ANNOUNCE_DELAY_MS);
+    }
+    announce(message, politeness = 'assertive', timeout = LIVEREGION_TIMEOUT_DELAY) {
+        if (!this.node) {
+            return;
+        }
+        const node = this.doc.createElement('div');
+        if (typeof message === 'object') {
+            // A generic `div` cannot take `aria-labelledby` (name-from prohibited).
+            // React Aria uses `role="img"` so assistive technology treats the node
+            // as a named object and reads the referenced accessible name.
+            node.setAttribute('role', 'img');
+            node.setAttribute('aria-labelledby', message['aria-labelledby']);
+        } else {
+            node.textContent = this.repeatText.next(politeness, message);
+        }
+        if (politeness === 'assertive') {
+            this.assertiveLog?.appendChild(node);
+        } else {
+            this.politeLog?.appendChild(node);
+        }
+        if (message !== '') {
+            const win = this.doc.defaultView ?? globalThis;
+            win.setTimeout(()=>{
+                node.remove();
+            }, timeout);
+        }
+    }
+    clear(politeness) {
+        this.pending = politeness ? this.pending.filter((item)=>item.politeness !== politeness) : [];
+        if (!this.node) {
+            return;
+        }
+        if ((!politeness || politeness === 'assertive') && this.assertiveLog) {
+            this.assertiveLog.innerHTML = '';
+            this.repeatText.reset('assertive');
+        }
+        if ((!politeness || politeness === 'polite') && this.politeLog) {
+            this.politeLog.innerHTML = '';
+            this.repeatText.reset('polite');
+        }
+    }
+    cancelFirstDelay() {
+        if (this.firstDelayTimerId != null) {
+            const win = this.doc.defaultView ?? globalThis;
+            win.clearTimeout(this.firstDelayTimerId);
+            this.firstDelayTimerId = null;
+        }
+        this.pending = [];
+    }
+}
+/** Clear announced nodes after this many ms (React Aria default). */ const LIVEREGION_TIMEOUT_DELAY = 7000;
+/** Delay before first message after creating regions (Safari consistency). */ const FIRST_ANNOUNCE_DELAY_MS = 100;
+const announcersByDocument = new WeakMap();
+const getLiveAnnouncer = (doc)=>{
+    return announcersByDocument.get(doc) ?? null;
+};
+const ensureLiveAnnouncer = (doc)=>{
+    const existing = announcersByDocument.get(doc);
+    if (existing?.isAttached()) {
+        return existing;
+    }
+    existing?.destroy();
+    const announcer = new LiveAnnouncer(doc);
+    announcersByDocument.set(doc, announcer);
+    return announcer;
+};
+const clearLiveAnnouncerRegistry = (doc)=>{
+    if (doc) {
+        const announcer = announcersByDocument.get(doc);
+        announcer?.destroy();
+        announcersByDocument.delete(doc);
+        return;
+    }
+};
+const isTestAnnounceEnvironment = ()=>{
+    // React Aria: skip first-announce delay under React act / Jest.
+    // https://github.com/reactwg/react-18/discussions/102
+    const globalObj = globalThis;
+    if (typeof globalObj.IS_REACT_ACT_ENVIRONMENT === 'boolean') {
+        return globalObj.IS_REACT_ACT_ENVIRONMENT;
+    }
+    return typeof jest !== 'undefined';
+};
+
+
+const resolveDocument = (doc)=>{
+    if (doc) {
+        return doc;
+    }
+    if (typeof document !== 'undefined') {
+        return document;
+    }
+    return undefined;
+};
+const resolveTimeoutAndDocument = (timeoutOrOptions)=>{
+    if (typeof timeoutOrOptions === 'number') {
+        return {
+            timeout: timeoutOrOptions
+        };
+    }
+    if (timeoutOrOptions && typeof timeoutOrOptions === 'object') {
+        return {
+            timeout: timeoutOrOptions.timeout ?? (/* inlined export .LIVEREGION_TIMEOUT_DELAY */7000),
+            document: timeoutOrOptions.document
+        };
+    }
+    return {
+        timeout: (/* inlined export .LIVEREGION_TIMEOUT_DELAY */7000)
+    };
+};
+/**
+ * Announces a message to screen readers via a document-scoped live region pair
+ * (polite + assertive). Prefer this over `useAnnouncer` so the page shares one
+ * pair per document.
+ *
+ * In a pop-out window, `useGlobalAnnouncer` is the more convenient way to
+ * automatically detect and target that window.
+ * Imperative callers can pass `{ document }` manually.
+ * Both should call `destroyAnnouncer(win.document)` on close.
+ *
+ * Based on `@react-aria/live-announcer`.
+ *
+ * @example
+ * ```ts
+ * import { announce, destroyAnnouncer } from '@ringcentral/spring-base';
+ *
+ * // Preferred for saved / completed / non-urgent status
+ * announce('Saved', 'polite');
+ * // Use for time-sensitive / critical / urgent status
+ * announce('Session expiring', 'assertive');
+ *
+ * // Pop-out window
+ * announce('Saved', 'polite', { document: externalWindow.document });
+ * externalWindow.addEventListener('beforeunload', () => {
+ *   destroyAnnouncer(externalWindow.document);
+ * });
+ * ```
+ */ function announce(message, politeness = 'assertive', timeoutOrOptions) {
+    const { timeout, document: optionDocument } = resolveTimeoutAndDocument(timeoutOrOptions);
+    const doc = resolveDocument(optionDocument);
+    if (!doc?.body) {
+        return;
+    }
+    const liveAnnouncer = ensureLiveAnnouncer(doc);
+    liveAnnouncer.schedule(message, politeness, timeout);
+}
+/**
+ * Clears pending announcement nodes for the given politeness (or both).
+ */ function clearAnnouncer(politeness, doc) {
+    const target = resolveDocument(doc);
+    if (!target) {
+        return;
+    }
+    getLiveAnnouncer(target)?.clear(politeness);
+}
+/**
+ * Removes the document-scoped live-region tree and cancels a pending
+ * first-announce delay. Does not clear per-message remove timeouts.
+ * Call this when closing a pop-out window that used
+ * `announce(..., { document })` or `useGlobalAnnouncer`.
+ */ function destroyAnnouncer(doc) {
+    const target = resolveDocument(doc);
+    if (!target) {
+        return;
+    }
+    clearLiveAnnouncerRegistry(target);
+}
+
+
+
+
+export { LIVEREGION_TIMEOUT_DELAY, LIVE_ANNOUNCER_ATTR, announce, applyVisuallyHiddenStyles, clearAnnouncer, destroyAnnouncer };

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "@ringcentral/spring-base",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "author": "RingCentral",
   "description": "Core utilities, hooks, and foundational functionality for Spring UI components, providing essential building blocks for React applications",
   "main": "./index.js",
   "module": "./index.js",
   "types": "./index.d.ts",
   "dependencies": {
+    "@mui/base": "5.0.0-beta.70",
     "@mui/utils": "^6.0.2",
     "@types/lodash": "^4.14.182",
-    "clsx": "^1.2.1",
     "framer-motion": "^6.5.1",
     "lodash": "^4.17.21",
     "tailwind-merge": "^2.5.4",
     "type-fest": "^2.12.2"
   },
   "peerDependencies": {
-    "@types/react": ">=17.0.3",
-    "react": ">=17.0.2",
-    "react-dom": ">=17.0.2"
+    "@types/react": "^17.0.3 || ^18.0.0 || ^19.0.0",
+    "react": "^17.0.2 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.2 || ^18.0.0 || ^19.0.0"
   },
   "sideEffects": false,
   "license": "MIT",

package/src/hooks/index.d.ts

@@ -1,6 +1,7 @@
 export * from './useA11yKeyEvent';
 export * from './useActive';
 export * from './useAnnouncer';
+export * from './useGlobalAnnouncer';
 export * from './useButton';
 export * from './useAriaHideOutside';
 export * from './useAudio';

package/src/hooks/useAnnouncer/useAnnouncer.d.ts

@@ -1,2 +1,5 @@
-export declare const visuallyHiddenStyles = "\n  clip-path: inset(100%);\n  clip: rect(1px, 1px, 1px, 1px);\n  height: 1px;\n  overflow: hidden;\n  position: absolute;\n  white-space: nowrap;\n  width: 1px;\n";
-export declare const useAnnouncer: (id?: string) => (message?: string) => void;
+import type { AnnouncerPoliteness } from '../../liveAnnouncer';
+export type UseAnnouncerOptions = {
+    politeness?: AnnouncerPoliteness;
+};
+export declare function useAnnouncer(idOrOptions?: string | UseAnnouncerOptions, maybeOptions?: UseAnnouncerOptions): (message?: string) => void;

package/src/hooks/useButton/useButton.d.ts

@@ -1,2 +1,2 @@
-import { UseButtonParameters, UseButtonReturnValue } from '@mui/base/useButton';
+import { UseButtonParameters, UseButtonReturnValue } from '@mui/base';
 export declare function useButton(parameters: UseButtonParameters): UseButtonReturnValue;

package/src/hooks/useGlobalAnnouncer/index.d.ts

@@ -0,0 +1 @@
+export * from './useGlobalAnnouncer';

package/src/hooks/useGlobalAnnouncer/useGlobalAnnouncer.d.ts

@@ -0,0 +1,5 @@
+import type { AnnounceMessage, AnnouncerPoliteness } from '../../liveAnnouncer/types';
+export type GlobalAnnounceOptions = {
+    timeout?: number;
+};
+export declare function useGlobalAnnouncer(): (message: AnnounceMessage, politeness?: AnnouncerPoliteness, timeoutOrOptions?: number | GlobalAnnounceOptions) => void;

package/src/hooks/useId/useId.d.ts

@@ -1 +1,3 @@
-export declare function useId(id?: string, prefixMode?: boolean): string;
+declare function useReactId(id?: string, prefixMode?: boolean): string;
+export declare const useId: typeof useReactId;
+export {};

package/src/hooks/useKeyboardMoveFocus/useOnlyOneFocusable.d.ts

@@ -1,11 +1,14 @@
 /// <reference types="react" />
+import type { HTMLDataAttribute } from '../../typings';
 export type UseOnlyOneFocusableParams = {
     focusedIndexRef: React.MutableRefObject<number>;
     containerRef: React.RefObject<HTMLElement>;
 };
+type MoveFocusedItemProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & HTMLDataAttribute;
 export declare const useOnlyOneFocusable: ({ focusedIndexRef, containerRef, }: UseOnlyOneFocusableParams) => {
     moveFocusedId: string;
     focusIndex: (toIndex: number) => void;
     setIndexTabIndex: (toIndex: number) => void;
-    getItemProps: (index: number, options?: Omit<React.HTMLAttributes<HTMLElement>, 'children'>) => Omit<import("react").HTMLAttributes<HTMLElement>, "children">;
+    getItemProps: (index: number, options?: Omit<React.HTMLAttributes<HTMLElement>, 'children'>) => NonNullable<MoveFocusedItemProps>;
 };
+export {};

package/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './config';
 export * from './contexts';
 export * from './hooks';
+export * from './liveAnnouncer';
 export * from './typings';
 export * from './utils';

package/src/liveAnnouncer/LiveAnnouncer.d.ts

@@ -0,0 +1,25 @@
+import type { AnnounceMessage, AnnouncerPoliteness } from './types';
+export declare class LiveAnnouncer {
+    node: HTMLElement | null;
+    assertiveLog: HTMLElement | null;
+    politeLog: HTMLElement | null;
+    private readonly doc;
+    private readonly repeatText;
+    private ready;
+    private pending;
+    private firstDelayTimerId;
+    constructor(doc: Document);
+    isAttached(): boolean;
+    createLog(ariaLive: AnnouncerPoliteness): HTMLElement;
+    destroy(): void;
+    schedule(message: AnnounceMessage, politeness?: AnnouncerPoliteness, timeout?: number): void;
+    announce(message: AnnounceMessage, politeness?: AnnouncerPoliteness, timeout?: number): void;
+    clear(politeness?: AnnouncerPoliteness): void;
+    private cancelFirstDelay;
+}
+export declare const LIVEREGION_TIMEOUT_DELAY = 7000;
+export declare const FIRST_ANNOUNCE_DELAY_MS = 100;
+export declare const getLiveAnnouncer: (doc: Document) => LiveAnnouncer | null;
+export declare const ensureLiveAnnouncer: (doc: Document) => LiveAnnouncer;
+export declare const clearLiveAnnouncerRegistry: (doc?: Document) => void;
+export declare const isTestAnnounceEnvironment: () => boolean;

package/src/liveAnnouncer/announce.d.ts

@@ -0,0 +1,4 @@
+import type { AnnounceMessage, AnnounceOptions, AnnouncerPoliteness } from './types';
+export declare function announce(message: AnnounceMessage, politeness?: AnnouncerPoliteness, timeoutOrOptions?: number | AnnounceOptions): void;
+export declare function clearAnnouncer(politeness?: AnnouncerPoliteness, doc?: Document): void;
+export declare function destroyAnnouncer(doc?: Document): void;

package/src/liveAnnouncer/index.d.ts

@@ -0,0 +1,3 @@
+export type { AnnounceMessage, AnnounceOptions, AnnouncerPoliteness, } from './types';
+export { announce, clearAnnouncer, destroyAnnouncer } from './announce';
+export { LIVEREGION_TIMEOUT_DELAY } from './LiveAnnouncer';

package/src/liveAnnouncer/types.d.ts

@@ -0,0 +1,8 @@
+export type AnnouncerPoliteness = 'assertive' | 'polite';
+export type AnnounceMessage = string | {
+    'aria-labelledby': string;
+};
+export type AnnounceOptions = {
+    timeout?: number;
+    document?: Document;
+};

package/src/liveAnnouncer/visuallyHidden.d.ts

@@ -0,0 +1,3 @@
+export declare const LIVE_ANNOUNCER_ATTR = "data-live-announcer";
+export declare const visuallyHiddenStyleProperties: Partial<CSSStyleDeclaration>;
+export declare const applyVisuallyHiddenStyles: (el: HTMLElement) => void;

package/typings.js

@@ -1 +1,8 @@
 
+
+
+
+
+
+
+