@ringcentral/spring-base 1.7.0

package/src/typings/BaseSize.d.ts

@@ -0,0 +1,15 @@
+declare type BaseSizes = {
+    xxxsmall: any;
+    xxsmall: any;
+    xsmall: any;
+    small: any;
+    medium: any;
+    large: any;
+    inherit: any;
+    xlarge: any;
+    xxlarge: any;
+    xxxlarge: any;
+};
+export declare type BaseSizeKey = keyof BaseSizes;
+export declare type BaseSize<T extends BaseSizeKey = 'small' | 'medium' | 'large'> = keyof Pick<BaseSizes, T>;
+export {};

package/src/typings/ComponentTypes.d.ts

@@ -0,0 +1,50 @@
+import type { MotionProps } from 'framer-motion';
+import type { ComponentPropsWithRef, ElementType, HTMLAttributes, LegacyRef } from 'react';
+import type { GlobalStateClassesKey } from '../utils/classes/globalStateClasses';
+export declare type GroupedMotionProps<P = {}> = Pick<MotionProps, Extract<keyof HTMLAttributes<Element>, keyof MotionProps>> & Omit<P, Extract<keyof HTMLAttributes<Element>, keyof MotionProps>> & {
+    /** Override the motion applied to the component */
+    motionProps?: MotionProps | null;
+};
+export declare type ClassesProp<K extends string> = {
+    /** Override or extend the styles applied to the component */
+    classes?: Partial<Record<K | 'root' | GlobalStateClassesKey, string>>;
+};
+export declare type PropsWithRoot<P, R extends ElementType, O extends string = ''> = P & Omit<ComponentPropsWithRef<R>, keyof P | O>;
+export declare type StandardProps<P, C extends string, R extends ElementType | void = void, O extends string = '', ExtendAttributes = HTMLDataAttribute> = ClassesProp<C> & (R extends ElementType ? PropsWithRoot<P, R, 'classes' | O> : P & {
+    /** className for `root` slot */
+    className?: string;
+}) & ExtendAttributes;
+/**
+ * make props work with classes key type and add `root`
+ *
+ * @example
+ * ```tsx
+ * type ClassesKeys = 'foo' | 'bar';
+ *
+ * type MyComponentProps = WithClassesProps<{ example: string }, ClassesKeys>
+ *
+ * const props: MyComponentProps;
+ *
+ * props.classes = 'root';
+ * props.classes = 'bar';
+ * props.classes = 'foo';
+ * ```
+ */
+export declare type WithClassesProps<P, C extends string> = P & ClassesProp<C>;
+/**
+ * @deprecated use `WithClassesProps` instead, just rename
+ */
+export declare type BaseOverridableProps<P, C extends string> = WithClassesProps<P, C>;
+export declare type OverridableProps<B, T extends ElementType> = B & {
+    /**
+     * The component used for the root node.
+     * Either a string to use a HTML element or a component.
+     */
+    component?: T;
+} & Omit<ComponentPropsWithRef<T>, keyof B>;
+export declare type RefFromProps<P> = P extends {
+    ref?: LegacyRef<infer R> | undefined;
+} ? R : never;
+export declare type HTMLDataAttribute = {
+    [key: `data-${string}`]: unknown;
+};

package/src/typings/ExtractValue.d.ts

@@ -0,0 +1,2 @@
+export declare type ExtractArray<T> = T extends ReadonlyArray<infer U> ? U : never;
+export declare type ExtractRecord<T extends Record<string, unknown>> = T[keyof T];

package/src/typings/OverridableTypes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * This file copy from MUI
+ *
+ * https://github.com/mui/material-ui/blob/master/packages/mui-types/index.d.ts
+ */
+import type React from 'react';
+/**
+ * Remove properties `K` from `T`.
+ * Distributive for union types.
+ *
+ * @internal
+ */
+export declare type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+/**
+ * A component whose root component can be controlled via a `component` prop.
+ *
+ * Adjusts valid props based on the type of `component`.
+ */
+export interface OverridableComponent<M extends OverridableTypeMap> {
+    <C extends React.ElementType>(props: {
+        /**
+         * The component used for the root node.
+         * Either a string to use a HTML element or a component.
+         */
+        component: C;
+    } & OverrideProps<M, C>): JSX.Element | null;
+    (props: DefaultComponentProps<M>): JSX.Element | null;
+    displayName?: string;
+}
+/**
+ * Props of the component if `component={Component}` is used.
+ */
+export declare type OverrideProps<M extends OverridableTypeMap, C extends React.ElementType> = (BaseProps<M> & DistributiveOmit<React.ComponentPropsWithRef<C>, keyof BaseProps<M>>);
+/**
+ * Props if `component={Component}` is NOT used.
+ */
+export declare type DefaultComponentProps<M extends OverridableTypeMap> = BaseProps<M> & DistributiveOmit<React.ComponentPropsWithRef<M['defaultComponent']>, keyof BaseProps<M>>;
+/**
+ * Props defined on the component.
+ */
+export declare type BaseProps<M extends OverridableTypeMap> = M['props'];
+export interface OverridableTypeMap {
+    props: {};
+    defaultComponent: React.ElementType;
+}

package/src/typings/UnionOmit.d.ts

@@ -0,0 +1,3 @@
+export declare type UnionPick<T extends string, K extends T> = keyof Pick<Record<T, any>, K>;
+export declare type UnionOmit<T extends string, K extends T> = keyof Omit<Record<T, any>, K>;
+export declare type LiteralUnion<T> = T | (string & Record<never, never>);

package/src/typings/UnitMap.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @ignore
+ *
+ * fixed a map with unit key
+ */
+export declare type UnitMap<T extends string | number | symbol, K = any> = {
+    [key in T]: K;
+};
+/**
+ * @ignore
+ *
+ * convert `classes` type to `classes map` type
+ */
+export declare type ClassesMap<T extends {
+    classes?: any;
+} | undefined, K = any> = Partial<UnitMap<Classes<T>, K>>;
+declare type ClassesReturn<T extends {
+    classes?: any;
+} | undefined> = keyof NonNullable<NonNullable<T>['classes']>;
+/**
+ * get type of `classes` prop
+ *
+ * @returns classes type of prop
+ */
+export declare type Classes<T extends {
+    classes?: any;
+} | undefined> = ClassesReturn<T>;
+export {};

package/src/typings/index.d.ts

@@ -0,0 +1,7 @@
+export * from './BaseColor';
+export * from './BaseSize';
+export * from './ComponentTypes';
+export * from './ExtractValue';
+export * from './UnionOmit';
+export * from './UnitMap';
+export * from './OverridableTypes';

package/src/utils/a11yKeyboardCode.d.ts

@@ -0,0 +1,8 @@
+export declare const a11yKeyboard: {
+    ArrowLeft: string;
+    ArrowRight: string;
+    Space: string;
+    Escape: string;
+    Enter: string;
+    Tab: string;
+};

package/src/utils/ariaHideOutside.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export declare const ariaHideOutside: (targets: Element[], root?: HTMLElement) => () => void;

package/src/utils/capitalize.d.ts

@@ -0,0 +1 @@
+export declare function capitalize(string: string): string;

package/src/utils/checkDefaultPrevented.d.ts

@@ -0,0 +1,3 @@
+import { SyntheticEvent } from 'react';
+/** check is that event preventDefault */
+export declare const checkDefaultPrevented: (fc: (e: SyntheticEvent, ...args: any[]) => void) => (e: SyntheticEvent, ...args: any[]) => void;

package/src/utils/checkElementName.d.ts

@@ -0,0 +1,2 @@
+import { ReactElement } from 'react';
+export declare function checkElementName<T = any>(element: any, names: string[]): element is ReactElement<T>;

package/src/utils/checkKeyboardEvent.d.ts

@@ -0,0 +1,2 @@
+import { KeyboardEvent } from 'react';
+export declare const isDeleteKeyboardEvent: (keyboardEvent: KeyboardEvent) => boolean;

package/src/utils/classes/globalStateClasses.d.ts

@@ -0,0 +1,14 @@
+export declare const globalStateClasses: {
+    active: string;
+    checked: string;
+    completed: string;
+    disabled: string;
+    expanded: string;
+    focused: string;
+    focusVisible: string;
+    focusVisibleWithin: string;
+    required: string;
+    selected: string;
+    dragged: string;
+};
+export declare type GlobalStateClassesKey = keyof typeof globalStateClasses;

package/src/utils/classes/index.d.ts

@@ -0,0 +1,2 @@
+export * from './globalStateClasses';
+export * from './useClasses';

package/src/utils/classes/useClasses.d.ts

@@ -0,0 +1,41 @@
+import type { CamelCase } from 'type-fest';
+import { GlobalStateClassesKey } from './globalStateClasses';
+export declare type Cls<T extends {
+    name: string;
+    classes: string;
+}> = (...classValues: Array<T['classes'] | GlobalStateClassesKey | {
+    [key in T['classes'] | GlobalStateClassesKey]?: boolean | undefined | null;
+} | undefined | null | false>) => string;
+/**
+ * Custom hook for generating CSS classes based on input parameters.
+ *
+ * pick class from object with prefix of object like `sui-${prefix}-${key}`
+ *
+ * `className` will be apply to the `cls('root')` class.
+ *
+ * camelCase will be used for the key in the inputClasses object.
+ *
+ * and apply to kebabCase in the class name.
+ *
+ * ```tsx
+ * type BaseButtonClasses =
+ *   | 'root'
+ *   | 'content'
+ *   | 'start-slot';
+ *
+ * const cls = useClasses<BaseButtonClasses>('button', {
+ *    root: 'custom-button-root',
+ *    content: 'custom-button-content',
+ *    startSlot: 'custom-button-start-slot',
+ * }, 'custom-root-class');
+ *
+ * <button className={cls('root')}>Button</button> // 'sui-button-root custom-button-root custom-root-class'
+ * <button className={cls('content')}>Button</button> // 'sui-button-content custom-button-content'
+ *
+ * <button className={cls('start-slot')}>Button</button> // 'sui-button-start-slot custom-button-start-slot'
+ * ```
+ */
+export declare const useClasses: <T extends {
+    name: string;
+    classes: string;
+}>(prefix: T["name"], inputClasses?: Partial<Record<"disabled" | "active" | "checked" | "completed" | "expanded" | "focused" | "focusVisible" | "focusVisibleWithin" | "required" | "selected" | "dragged" | CamelCase<T["classes"]>, string>> | undefined, className?: string | undefined) => Cls<T>;

package/src/utils/combineProps.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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);
+    }
+  }
+ * ```
+ */
+export declare const combineProps: <T>(baseProps: T, newProps: T | Partial<T>, coverPropKeys?: (keyof T)[] | undefined) => NonNullable<T>;
+/**
+ * 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',
+  }
+ * ```
+ */
+export declare const combineClasses: <T>(baseClasses: T, newClasses: T | Partial<T>) => NonNullable<T>;

package/src/utils/devlog.d.ts

@@ -0,0 +1,7 @@
+export declare type DevlogArgs = {
+    condition?: boolean;
+    scope: string;
+    message: string;
+    level?: 'warn' | 'error';
+};
+export declare function logInDev({ scope, message, level, condition, }: DevlogArgs): void;

package/src/utils/getRefElement.d.ts

@@ -0,0 +1,6 @@
+import { MutableRefObject, RefObject } from 'react';
+export declare type RefOrElementOrCallback<T = HTMLElement> = RefObject<T> | (() => T) | T;
+/**
+ * get element from React ref or callback
+ */
+export declare const getRefElement: <T>(ref: T) => T extends () => infer R ? R : T extends RefObject<infer C> | MutableRefObject<infer C> ? C : T;

package/src/utils/getTitle.d.ts

@@ -0,0 +1 @@
+export declare const getTitle: (text: any) => string | undefined;

package/src/utils/index.d.ts

@@ -0,0 +1,25 @@
+export * from './a11yKeyboardCode';
+export * from './ariaHideOutside';
+export * from './capitalize';
+export * from './checkDefaultPrevented';
+export * from './checkElementName';
+export * from './checkKeyboardEvent';
+export * from './classes';
+export * from './combineProps';
+export * from './devlog';
+export * from './getRefElement';
+export * from './getTitle';
+export * from './isRef';
+export * from './isSuiElement';
+export * from './isUrl';
+export * from './isWebKit154';
+export * from './omit';
+export * from './outerSize';
+export * from './ownerDocument';
+export * from './ownerWindow';
+export * from './pick';
+export * from './preloadImg';
+export * from './removeClassName';
+export * from './runKeyHandler';
+export * from './selectionHandler';
+export * from './twMerge';

package/src/utils/isRef.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const isRef: <T = any>(obj: any) => obj is React.RefObject<T>;

package/src/utils/isSuiElement.d.ts

@@ -0,0 +1 @@
+export declare const isSuiElement: (element: any, suiNames: readonly string[]) => boolean;

package/src/utils/isUrl.d.ts

@@ -0,0 +1 @@
+export declare function isUrl(url: string): RegExpMatchArray | null;

package/src/utils/isWebKit154.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Conditionally apply a workaround for the CSS transition bug in Safari 15.4 / WebKit browsers.
+ * Remove this workaround once the WebKit bug fix is released.
+ *
+ * follow up:
+ * https://github.com/mui/material-ui/pull/31975/files
+ * https://github.com/mui/material-ui/pull/32202/files
+ */
+export declare const isWebKit154: boolean;

package/src/utils/omit.d.ts

@@ -0,0 +1,2 @@
+/** enhance lodash type */
+export declare const omit: <T extends Record<string, unknown>, K extends (keyof T)[]>(classes: T | undefined, keys: K) => Partial<{ [K2 in Exclude<keyof T, K[number]>]: T[K2]; }>;

package/src/utils/outerSize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * get that full height and margin with margin
+ * that will ignore transform animation
+ */
+export declare function outerSize(el: HTMLElement): {
+    readonly height: number;
+    readonly width: number;
+};

package/src/utils/ownerDocument.d.ts

@@ -0,0 +1 @@
+export { unstable_ownerDocument as ownerDocument } from '@mui/utils';

package/src/utils/ownerWindow.d.ts

@@ -0,0 +1 @@
+export declare const ownerWindow: (node: Node | undefined) => Window & typeof globalThis;

package/src/utils/pick.d.ts

@@ -0,0 +1,2 @@
+/** enhance lodash type */
+export declare const pick: <T extends Record<string, unknown>, K extends (keyof T)[]>(classes: T | undefined, keys: K) => { [K2 in Extract<keyof T, K[number]>]: T[K2]; };

package/src/utils/preloadImg.d.ts

@@ -0,0 +1,2 @@
+/** preload image file */
+export declare function preloadImg(url: string): Promise<void>;

package/src/utils/removeClassName.d.ts

@@ -0,0 +1,35 @@
+import { RefOrElementOrCallback } from './getRefElement';
+declare type RemoveClassNameOptions = {
+    /**
+     * make replace also scan child nodes
+     *
+     * @default false
+     */
+    scanChildren?: boolean;
+    /**
+     * is that should fullMatch class name
+     *
+     * @default false
+     */
+    fullMatch?: boolean;
+};
+/**
+ * remove className from element, default will not scan child nodes, if you want to scan child nodes, set `scanChildren` to `true`.
+ *
+ * @param target target element reference or element or callback
+ * @param removeClass className to remove, default will use class `includes` to check, if you want to use full match, set `fullMatch` to `true`
+ *
+ * @example
+ * ```js
+ * elm => <div class="abc bcd efg abc-def"></div>
+ *
+ * removeClassName(elmRef, 'bcd');
+ *
+ * elm => <div class="abc efg abc-def"></div>
+ *
+ * removeClassName(elmRef, 'abc');
+ * elm => <div class="efg"></div>
+ * ```
+ */
+export declare function removeClassName(target: RefOrElementOrCallback, removeClass: string, { scanChildren, fullMatch }?: RemoveClassNameOptions): void;
+export {};

package/src/utils/runKeyHandler.d.ts

@@ -0,0 +1,12 @@
+import { KeyboardEvent } from 'react';
+declare type KeyHandlers = Record<KeyboardEvent['key'], () => void>;
+/**
+ * Executes the corresponding key handler function based on the provided keyboard event.
+ * If a handler is found for the pressed key, it will be invoked.
+ * Additionally, it prevents any side effects caused by the event, such as page scrolling.
+ *
+ * @param e - The keyboard event.
+ * @param keyHandlers - An object containing key-handler mappings.
+ */
+export declare const runKeyHandler: (e: KeyboardEvent<unknown>, keyHandlers: KeyHandlers) => void;
+export {};

package/src/utils/selectionHandler.d.ts

@@ -0,0 +1,23 @@
+import { RefOrElementOrCallback } from './getRefElement';
+/**
+ * get current input element selection position and is that selectRange state
+ */
+export declare function getSelectionPosition<T extends HTMLInputElement | HTMLTextAreaElement>(sourceTarget: RefOrElementOrCallback<T>): {
+    isSelectRange: boolean;
+    position: {
+        start: number;
+        end: number;
+    };
+};
+/**
+ * set input element selection position position,
+ * if you need scroll that into view set `scrollIntoView` as true
+ */
+export declare function setSelectionPosition<T extends HTMLInputElement | HTMLTextAreaElement>(target: RefOrElementOrCallback<T>, options: {
+    start: number | null;
+    end: number | null;
+    direction?: 'forward' | 'backward' | 'none' | undefined;
+    scrollIntoView?: boolean;
+}): void;
+/** clean whole selection */
+export declare function clearWindowSelection(): void;

package/src/utils/twMerge.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Merge tailwind classes with additional class groups for spring-ui
+ */
+export declare const twMerge: (...classLists: import("tailwind-merge").ClassNameValue[]) => string;

package/typings.js

@@ -0,0 +1 @@
+