@ringcentral/spring-base 1.7.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 RingCentral, Inc.
+
+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,61 @@
+# @ringcentral/spring-base
+
+Core utilities and hooks for Spring UI.
+
+Note: If you already use `@ringcentral/spring-ui`, these utilities are re-exported there. You can import them directly from `@ringcentral/spring-ui` (recommended), or from `@ringcentral/spring-base` if you only use the base package.
+
+
+## Installation
+
+Using yarn:
+
+```bash
+yarn add @ringcentral/spring-base
+```
+
+Using npm:
+
+```bash
+npm i @ringcentral/spring-base
+```
+
+## Usage
+
+```ts
+// If your app already installs @ringcentral/spring-ui (recommended)
+import { twMerge } from '@ringcentral/spring-ui';
+
+// Or, when using the package directly
+import { twMerge } from '@ringcentral/spring-base';
+```
+
+## Utilities
+
+### twMerge
+Merge Tailwind classes with Spring UI class groups.
+
+```ts
+import { twMerge } from '@ringcentral/spring-base';
+
+twMerge('typography-label', 'typography-detailBold');
+// => 'typography-detailBold'
+```
+
+### Example Hook
+
+```tsx
+import * as React from 'react';
+import { useDebounce } from '@ringcentral/spring-base';
+
+function Search({ onQuery }: { onQuery: (q: string) => void }) {
+  const [value, setValue] = React.useState('');
+  const debounced = useDebounce(value, 300);
+  React.useEffect(() => onQuery(debounced), [debounced, onQuery]);
+  return <input value={value} onChange={e => setValue(e.target.value)} />;
+}
+```
+
+## License
+
+MIT
+

package/chunks/twMerge.js

@@ -0,0 +1,409 @@
+import { unstable_ownerWindow } from '@mui/utils';
+import { isValidElement } from 'react';
+import isPlainObject from 'lodash/isPlainObject';
+import { rcConfiguration } from '../config.js';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+const ownerWindow = unstable_ownerWindow;
+
+// Copy from https://github.com/adobe/react-spectrum/blob/main/packages/%40react-aria/overlays/src/ariaHideOutside.ts
+// And support multiple window
+const ARIA_HIDDEN = 'aria-hidden';
+const REF_COUNT_MAP = '__SUI_ARIA_HIDE_OUTSIDE_REF_COUNT_MAP__';
+const getRefCountMap = (window) => {
+    // @ts-ignore
+    if (!window[REF_COUNT_MAP]) {
+        // @ts-ignore
+        window[REF_COUNT_MAP] = new WeakMap();
+    }
+    // @ts-ignore
+    return window[REF_COUNT_MAP];
+};
+const OBSERVER_STACK = '__SUI_ARIA_HIDE_OUTSIDE_OBSERVER_STACK__';
+const getObserverStack = (window) => {
+    // @ts-ignore
+    if (!window[OBSERVER_STACK]) {
+        // @ts-ignore
+        window[OBSERVER_STACK] = [];
+    }
+    // @ts-ignore
+    return window[OBSERVER_STACK];
+};
+const isHTMLOrSVGElement = (node) => {
+    return 'dataset' in node;
+};
+const isElement = (node) => {
+    return node.nodeType === Node.ELEMENT_NODE;
+};
+/**
+ * Hides all elements in the DOM outside the given targets from screen readers using aria-hidden,
+ * and returns a function to revert these changes. In addition, changes to the DOM are watched
+ * and new elements outside the targets are automatically hidden.
+ * @param targets - The elements that should remain visible.
+ * @param root - Nothing will be hidden above this element.
+ * @returns - A function to restore all hidden elements.
+ */
+const ariaHideOutside = (targets, root = document.body) => {
+    const currentWindow = ownerWindow(root);
+    if (!currentWindow) {
+        // Current JS environment doesn't have a window object, do nothing.
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        return () => { };
+    }
+    const visibleNodes = new Set(targets);
+    const hiddenNodes = new Set();
+    // Keeps a ref count of all hidden elements. Added to when hiding an element, and
+    // subtracted from when showing it again. When it reaches zero, aria-hidden is removed.
+    const refCountMap = getRefCountMap(currentWindow);
+    const observerStack = getObserverStack(currentWindow);
+    const walker = currentWindow.document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
+        acceptNode(node) {
+            // If this node is a live announcer, add it to the set of nodes to keep visible.
+            if (isHTMLOrSVGElement(node) &&
+                node.dataset['liveAnnouncer'] === 'true') {
+                visibleNodes.add(node);
+            }
+            // Skip this node and its children if it is one of the target nodes, or a live announcer.
+            // Also skip children of already hidden nodes, as aria-hidden is recursive. An exception is
+            // made for elements with role="row" since VoiceOver on iOS has issues hiding elements with role="row".
+            // For that case we want to hide the cells inside as well (https://bugs.webkit.org/show_bug.cgi?id=222623).
+            if (visibleNodes.has(node) ||
+                (node.parentElement &&
+                    hiddenNodes.has(node.parentElement) &&
+                    node.parentElement.getAttribute('role') !== 'row')) {
+                return NodeFilter.FILTER_REJECT;
+            }
+            // Skip this node but continue to children if one of the targets is inside the node.
+            if (targets.some((target) => node.contains(target))) {
+                return NodeFilter.FILTER_SKIP;
+            }
+            return NodeFilter.FILTER_ACCEPT;
+        },
+    });
+    const hide = (node) => {
+        const refCount = refCountMap.get(node) ?? 0;
+        // If already aria-hidden, and the ref count is zero, then this element
+        // was already hidden and there's nothing for us to do.
+        if (node.getAttribute(ARIA_HIDDEN) === 'true' && refCount === 0) {
+            return;
+        }
+        if (refCount === 0) {
+            node.setAttribute(ARIA_HIDDEN, 'true');
+        }
+        hiddenNodes.add(node);
+        refCountMap.set(node, refCount + 1);
+    };
+    // If there is already a MutationObserver listening from a previous call,
+    // disconnect it so the new on takes over.
+    if (observerStack.length) {
+        observerStack[observerStack.length - 1].disconnect();
+    }
+    let node = walker.nextNode();
+    while (node != null) {
+        hide(node);
+        node = walker.nextNode();
+    }
+    const observer = new currentWindow.MutationObserver((changes) => {
+        for (const change of changes) {
+            if (change.type !== 'childList' || change.addedNodes.length === 0) {
+                continue;
+            }
+            // If the parent element of the added nodes is not within one of the targets,
+            // and not already inside a hidden node, hide all of the new children.
+            if (![...visibleNodes, ...hiddenNodes].some((node) => node.contains(change.target))) {
+                for (const node of change.addedNodes) {
+                    if (isHTMLOrSVGElement(node) &&
+                        node.dataset['liveAnnouncer'] === 'true') {
+                        visibleNodes.add(node);
+                    }
+                    else if (isElement(node)) {
+                        hide(node);
+                    }
+                }
+            }
+        }
+    });
+    observer.observe(root, { childList: true, subtree: true });
+    const observerWrapper = {
+        observe() {
+            observer.observe(root, { childList: true, subtree: true });
+        },
+        disconnect() {
+            observer.disconnect();
+        },
+    };
+    observerStack.push(observerWrapper);
+    return () => {
+        observer.disconnect();
+        for (const node of hiddenNodes) {
+            const count = refCountMap.get(node);
+            if (count === 1) {
+                node.removeAttribute(ARIA_HIDDEN);
+                refCountMap.delete(node);
+            }
+            else if (typeof count === 'number') {
+                refCountMap.set(node, count - 1);
+            }
+        }
+        // Remove this observer from the stack, and start the previous one.
+        if (observerWrapper === observerStack[observerStack.length - 1]) {
+            observerStack.pop();
+            if (observerStack.length) {
+                observerStack[observerStack.length - 1].observe();
+            }
+        }
+        else {
+            observerStack.splice(observerStack.indexOf(observerWrapper), 1);
+        }
+    };
+};
+
+/**
+ * Combine props object together
+ *
+ * that will group className, classes together
+ * function will auto combine together,
+ * trigger order is `intoProps.someFn(e) => defaultProps.someFn(e)`
+ *
+ * @param baseProps base props you want to combine together
+ * @param newProps want to combine in to props
+ * @param coverPropKeys some prop key you want to cover, not combine when type is function, ex. `ComponentType`
+ *
+ *
+ * @example
+ * ```tsx
+ * combineProps(
+    {
+      children: <A />,
+      value: '1',
+      className: 'a1',
+      classes: {
+        root: 'root1'
+      },
+      count: 1,
+      size: 'large',
+      onClick: fn1
+    },
+    {
+      children: <B />,
+      value: '2',
+      className: 'a2',
+      classes: {
+        root: 'root2'
+      },
+      count: 2,
+      size: undefined,
+      onClick: fn2
+    },
+  )
+  // output result:
+  {
+    children: <B />,
+    value: '2',
+    className: 'a1 a2',
+    classes: {
+      root: 'root1 root2'
+    },
+    count: 2,
+    size: 'large',
+    onClick: (e) => {
+      fn2(e);
+      fn1(e);
+    }
+  }
+ * ```
+ */
+const combineProps = (baseProps, newProps, coverPropKeys) => innerCombineProps({
+    baseProps,
+    newProps,
+    coverPropKeys,
+});
+/**
+ * Combine two classes
+ *
+ * @param baseClasses base classes you want to combine together
+ * @param newClasses new classes want to combine in to props
+ *
+ * @example
+ * ```ts
+ * combineClasses(
+    {
+      root: 'a1',
+      input: 'a1',
+      un1: undefined,
+      un2: 'a4',
+    },
+    {
+      root: 'a1',
+      input: 'a2',
+      un1: 'a3',
+      un2: undefined,
+      un3: 'a5',
+    },
+  )
+  // output result:
+  {
+    root: 'a1 a1',
+    input: 'a1 a2',
+    un1: 'a3',
+    un2: 'a4',
+    un3: 'a5',
+  }
+ * ```
+ */
+const combineClasses = (baseClasses, newClasses) => innerCombineProps({
+    baseProps: baseClasses,
+    newProps: newClasses,
+    combineAllString: true,
+});
+const innerCombineProps = (params) => {
+    const { baseProps, newProps } = params;
+    if (!newProps || Object.keys(newProps).length === 0) {
+        return baseProps;
+    }
+    const outputProps = mergeChildProps(params);
+    return {
+        ...newProps,
+        ...outputProps,
+    };
+};
+function mergeChildProps({ baseProps, newProps, combineAllString, coverPropKeys, }) {
+    const result = Object.keys(baseProps || {}).reduce((output, curr) => {
+        const prop = baseProps[curr];
+        const propTo = newProps[curr];
+        if (propTo !== undefined) {
+            // * all typeof type below
+            // "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function"
+            switch (typeof prop) {
+                case 'undefined':
+                    output[curr] = propTo;
+                    break;
+                case 'object': {
+                    if (!isValidElement(propTo) &&
+                        !isValidElement(prop) &&
+                        isPlainObject(propTo) &&
+                        isPlainObject(prop)) {
+                        output[curr] = mergeChildProps({
+                            baseProps: prop,
+                            newProps: propTo || {},
+                            combineAllString: combineAllString || curr === 'classes',
+                        });
+                    }
+                    else {
+                        output[curr] = propTo;
+                    }
+                    break;
+                }
+                case 'string':
+                    if (combineAllString || curr === 'className') {
+                        output[curr] = [prop, propTo]
+                            .filter((x) => typeof x === 'string' && x)
+                            .join(' ');
+                    }
+                    else {
+                        output[curr] = propTo;
+                    }
+                    break;
+                case 'boolean':
+                case 'symbol':
+                case 'bigint':
+                case 'number':
+                    output[curr] = propTo;
+                    break;
+                case 'function':
+                    if (coverPropKeys && coverPropKeys.includes(curr) && propTo) {
+                        output[curr] = propTo;
+                    }
+                    else {
+                        output[curr] = (...args) => {
+                            // * exec outside first
+                            propTo?.(...args);
+                            prop?.(...args);
+                        };
+                    }
+                    break;
+            }
+        }
+        else {
+            output[curr] = prop;
+        }
+        return output;
+    }, {});
+    // if result is an empty {} reset that to undefined
+    if (Object.keys(result).length === 0) {
+        return undefined;
+    }
+    return {
+        ...newProps,
+        ...result,
+    };
+}
+
+/* eslint-disable no-console */
+function logInDev({ scope, message, level = 'warn', condition = true, }) {
+    if (process.env.NODE_ENV !== 'production' &&
+        condition &&
+        !rcConfiguration.WARNING_IGNORE) {
+        const log = `SPRING [${scope}]: ${message}`;
+        if (process.env.NODE_ENV === 'test' && level === 'error') {
+            throw Error(log);
+        }
+        console[level](log);
+    }
+}
+
+const isRef = (obj) => {
+    return obj && 'current' in obj;
+};
+
+/**
+ * get element from React ref or callback
+ */
+const getRefElement = (ref) => {
+    if (typeof ref === 'function') {
+        return ref();
+    }
+    if (typeof ref === 'object' && isRef(ref)) {
+        return ref.current;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return ref;
+};
+
+/**
+ * Merge tailwind classes with additional class groups for spring-ui
+ */
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            typography: [
+                {
+                    typography: [() => true],
+                },
+            ],
+            'focus-ring-rounded': [
+                'focus-ring-rounded',
+                {
+                    'focus-ring-rounded': [() => true],
+                },
+            ],
+            'focus-ring-border': [
+                'focus-ring-border',
+                {
+                    'focus-ring-border': [() => true],
+                },
+            ],
+            'focus-ring-border-recoup': [
+                'focus-ring-border-recoup',
+                'no-focus-ring-border-recoup',
+            ],
+            'focus-ring': [
+                {
+                    'focus-ring': [() => true],
+                },
+            ],
+        },
+    },
+});
+
+export { ariaHideOutside as a, combineClasses as b, combineProps as c, getRefElement as g, isRef as i, logInDev as l, ownerWindow as o, twMerge as t };

package/config.js

@@ -0,0 +1,78 @@
+// TODO: refactor config
+/* eslint-disable no-console */
+const SPRING_WARNING_IGNORE_KEY = '__SPRING_WARNING_IGNORE__';
+// * use that way to avoid that code be exist in production code base
+/**
+ * config global setting
+ *
+ * ```ts
+ * configure({
+ *   warning: false
+ * })
+ * ```
+ * ## WARNING related method and  only work in `development mode`
+ *
+ * `WARNING_IGNORE`:  only work in `development mode`
+ * `WARNING_FUNCTION` only work in `development mode`
+ */
+let rcConfiguration = {};
+if (process.env.NODE_ENV !== 'production') {
+    class RcConfig {
+        _WARNING_IGNORE = false;
+        _WARNING_FUNCTION = (message, options) => {
+            console[options?.level || 'warn'](message);
+        };
+        constructor() {
+            if (typeof window !== 'undefined') {
+                // SSR support
+                // * get value once when init
+                this._WARNING_IGNORE =
+                    window?.localStorage?.getItem(SPRING_WARNING_IGNORE_KEY) === 'true';
+                // * also provide user to set variable from window
+                window.__SPRING__ = this;
+            }
+        }
+        set WARNING_IGNORE(value) {
+            if (value) {
+                console.log('---------------- [Spring] ----------------');
+                console.log(`Don't recommended you close it, we should avoid use any deprecated props or methods.`);
+                console.log('---------------- [Spring] ----------------');
+            }
+            this._WARNING_IGNORE = !!value;
+            window?.localStorage?.setItem(SPRING_WARNING_IGNORE_KEY, `${this._WARNING_IGNORE}`);
+        }
+        get WARNING_IGNORE() {
+            return this._WARNING_IGNORE;
+        }
+        set WARNING_FUNCTION(func) {
+            if (typeof func === 'function') {
+                this._WARNING_FUNCTION = func;
+            }
+            else {
+                console.warn('[Spring] config warningFunction is not a function.');
+            }
+        }
+        get WARNING_FUNCTION() {
+            return this._WARNING_FUNCTION;
+        }
+    }
+    rcConfiguration = new RcConfig();
+}
+/**
+ * set config with Spring
+ *
+ * ## WARNING method only work in `development mode`
+ */
+const configure = (options) => {
+    if (process.env.NODE_ENV !== 'production') {
+        const { warning, warningFunction } = options;
+        if (warning !== undefined) {
+            rcConfiguration.WARNING_IGNORE = !warning;
+        }
+        if (warningFunction !== undefined) {
+            rcConfiguration.WARNING_FUNCTION = warningFunction;
+        }
+    }
+};
+
+export { configure, rcConfiguration };

package/contexts.js

@@ -0,0 +1,71 @@
+import { createContext, useContext } from 'react';
+
+const WindowContext = createContext({
+    document: typeof window !== 'undefined'
+        ? window.document
+        : globalThis.window?.document
+            ? globalThis.window.document
+            : undefined,
+    globalThis: globalThis,
+    externalWindow: typeof window !== 'undefined' ? window : globalThis.window,
+});
+const useWindowContext = () => useContext(WindowContext);
+
+/** small to large */
+const breakpointList = ['xs', 'sm', 'md', 'lg', 'xl'];
+
+const matchCache = new Map();
+const getMatchGroups = (breakpoint) => {
+    const ltMatchGroup = [];
+    const gtMatchGroup = [];
+    if (breakpoint === null) {
+        for (let i = 0; i < breakpointList.length; i++) {
+            ltMatchGroup.push(`lt-${breakpointList[i]}`);
+        }
+    }
+    else {
+        const bpIndex = breakpointList.indexOf(breakpoint);
+        for (let i = 0; i < bpIndex; i++) {
+            gtMatchGroup.unshift(`gt-${breakpointList[i]}`);
+        }
+        for (let i = bpIndex + 1; i < breakpointList.length; i++) {
+            ltMatchGroup.push(`lt-${breakpointList[i]}`);
+        }
+    }
+    return { ltMatchGroup, gtMatchGroup };
+};
+const getMatchMap = ({ ltMatchGroup, gtMatchGroup }, matchBP) => {
+    const matchMap = {};
+    if (matchBP !== null)
+        matchMap[matchBP] = true;
+    for (const ltBP of ltMatchGroup) {
+        const [, bp] = ltBP.split('-');
+        matchMap[`lt${bp.toUpperCase()}`] = true;
+        matchMap[ltBP] = true;
+    }
+    for (const gtBP of gtMatchGroup) {
+        const [, bp] = gtBP.split('-');
+        matchMap[`gt${bp.toUpperCase()}`] = true;
+        matchMap[gtBP] = true;
+    }
+    return matchMap;
+};
+const getMatchDetail = (breakpoint) => {
+    if (!matchCache.has(breakpoint)) {
+        const matchGroups = getMatchGroups(breakpoint);
+        const matchMap = getMatchMap(matchGroups, breakpoint);
+        matchCache.set(breakpoint, {
+            ...matchGroups,
+            matchBP: breakpoint,
+            matchMap,
+        });
+    }
+    return matchCache.get(breakpoint);
+};
+
+const RcResponsiveContext = createContext(undefined);
+const useResponsiveContext = () => {
+    return useContext(RcResponsiveContext);
+};
+
+export { RcResponsiveContext, WindowContext, breakpointList, getMatchDetail, useResponsiveContext, useWindowContext };