forked from sagnik/Project_Velocity
409 lines
15 KiB
TypeScript
409 lines
15 KiB
TypeScript
import { CSSProperties } from 'react';
|
||
import { Dispatch } from 'react';
|
||
import { HTMLAttributes } from 'react';
|
||
import { JSX } from 'react/jsx-runtime';
|
||
import { ReactNode } from 'react';
|
||
import { Ref } from 'react';
|
||
import { RefObject } from 'react';
|
||
import { SetStateAction } from 'react';
|
||
|
||
declare type BasePanelAttributes = Omit<HTMLAttributes<HTMLDivElement>, "onResize">;
|
||
|
||
declare type BaseSeparatorAttributes = Omit<HTMLAttributes<HTMLDivElement>, "role" | "tabIndex">;
|
||
|
||
/**
|
||
* A Group wraps a set of resizable Panel components.
|
||
* Group content can be resized _horizontally_ or _vertically_.
|
||
*
|
||
* Group elements always include the following attributes:
|
||
*
|
||
* ```html
|
||
* <div data-group data-testid="group-id-prop" id="group-id-prop">
|
||
* ```
|
||
*
|
||
* ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
||
*/
|
||
export declare function Group({ children, className, defaultLayout, disableCursor, disabled, elementRef: elementRefProp, groupRef, id: idProp, onLayoutChange: onLayoutChangeUnstable, orientation, style, ...rest }: GroupProps): JSX.Element;
|
||
|
||
export declare namespace Group {
|
||
var displayName: string;
|
||
}
|
||
|
||
/**
|
||
* Imperative Group API.
|
||
*
|
||
* ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
|
||
*/
|
||
export declare interface GroupImperativeHandle {
|
||
/**
|
||
* Get the Group's current layout as a map of Panel id to percentage (0..100)
|
||
*
|
||
* @return Map of Panel id to percentages (specified as numbers ranging between 0..100)
|
||
*/
|
||
getLayout: () => {
|
||
[panelId: string]: number;
|
||
};
|
||
/**
|
||
* Set a new layout for the Group
|
||
*
|
||
* @param layout Map of Panel id to percentage (a number between 0..100)
|
||
* @return Applied layout (after validation)
|
||
*/
|
||
setLayout: (layout: {
|
||
[panelId: string]: number;
|
||
}) => Layout;
|
||
}
|
||
|
||
export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
|
||
/**
|
||
* Panel and Separator components that comprise this group.
|
||
*/
|
||
children?: ReactNode | undefined;
|
||
/**
|
||
* CSS class name.
|
||
*/
|
||
className?: string | undefined;
|
||
/**
|
||
* Default layout for the Group.
|
||
*
|
||
* ℹ️ This value allows layouts to be remembered between page reloads.
|
||
*
|
||
* ⚠️ Refer to the documentation for how to avoid layout shift when using server components.
|
||
*/
|
||
defaultLayout?: Layout | undefined;
|
||
/**
|
||
* This library sets custom mouse cursor styles to indicate drag state.
|
||
* Use this prop to disable that behavior for Panels and Separators in this group.
|
||
*/
|
||
disableCursor?: boolean | undefined;
|
||
/**
|
||
* Disable resize functionality.
|
||
*/
|
||
disabled?: boolean | undefined;
|
||
/**
|
||
* Ref attached to the root `HTMLDivElement`.
|
||
*/
|
||
elementRef?: Ref<HTMLDivElement> | undefined;
|
||
/**
|
||
* Exposes the following imperative API:
|
||
* - `getLayout(): Layout`
|
||
* - `setLayout(layout: Layout): void`
|
||
*
|
||
* ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
|
||
*/
|
||
groupRef?: Ref<GroupImperativeHandle> | undefined;
|
||
/**
|
||
* Uniquely identifies this group within an application.
|
||
* Falls back to `useId` when not provided.
|
||
*
|
||
* ℹ️ This value will also be assigned to the `data-group` attribute.
|
||
*/
|
||
id?: string | number | undefined;
|
||
/**
|
||
* Called when panel sizes change; receives a map of Panel id to size.
|
||
*/
|
||
onLayoutChange?: (layout: Layout) => void | undefined;
|
||
/**
|
||
* Specifies the resizable orientation ("horizontal" or "vertical"); defaults to "horizontal"
|
||
*/
|
||
orientation?: "horizontal" | "vertical" | undefined;
|
||
/**
|
||
* CSS properties.
|
||
*
|
||
* ⚠️ The following styles cannot be overridden: `display`, `flex-direction`, `flex-wrap`, and `overflow`.
|
||
*/
|
||
style?: CSSProperties | undefined;
|
||
};
|
||
|
||
/**
|
||
* Map of Panel id to flexGrow value;
|
||
*/
|
||
export declare type Layout = {
|
||
[id: string]: number;
|
||
};
|
||
|
||
export declare type LayoutStorage = Pick<Storage, "getItem" | "setItem">;
|
||
|
||
export declare type OnGroupLayoutChange = GroupProps["onLayoutChange"];
|
||
|
||
export declare type OnPanelResize = PanelProps["onResize"];
|
||
|
||
/**
|
||
* Panel group orientation loosely relates to the `aria-orientation` attribute.
|
||
* It determines how panels are are laid out within the group group and the direction they can be resized in.
|
||
*/
|
||
export declare type Orientation = "horizontal" | "vertical";
|
||
|
||
/**
|
||
* A Panel wraps resizable content and can be configured with min/max size constraints and collapsible behavior.
|
||
*
|
||
* Panel size props can be in the following formats:
|
||
* - Percentage of the parent Group (0..100)
|
||
* - Pixels
|
||
* - Relative font units (em, rem)
|
||
* - Viewport relative units (vh, vw)
|
||
*
|
||
* ℹ️ Numeric values are assumed to be pixels.
|
||
* Strings without explicit units are assumed to be percentages (0%..100%).
|
||
* Percentages may also be specified as strings ending with "%" (e.g. "33%")
|
||
* Pixels may also be specified as strings ending with the unit "px".
|
||
* Other units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)
|
||
*
|
||
* Panel elements always include the following attributes:
|
||
*
|
||
* ```html
|
||
* <div data-panel data-testid="panel-id-prop" id="panel-id-prop">
|
||
* ```
|
||
*
|
||
* ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
||
*/
|
||
export declare function Panel({ children, className, collapsedSize, collapsible, defaultSize, elementRef: elementRefProp, id: idProp, maxSize, minSize, onResize: onResizeUnstable, panelRef, style, ...rest }: PanelProps): JSX.Element;
|
||
|
||
export declare namespace Panel {
|
||
var displayName: string;
|
||
}
|
||
|
||
/**
|
||
* Imperative Panel API
|
||
*
|
||
* ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
|
||
*/
|
||
export declare interface PanelImperativeHandle {
|
||
/**
|
||
* Collapse the Panel to it's `collapsedSize`.
|
||
*
|
||
* ⚠️ This method will do nothing if the Panel is not `collapsible` or if it is already collapsed.
|
||
*/
|
||
collapse: () => void;
|
||
/**
|
||
* Expand a collapsed Panel to its most recent size.
|
||
*
|
||
* ⚠️ This method will do nothing if the Panel is not currently collapsed.
|
||
*/
|
||
expand: () => void;
|
||
/**
|
||
* Get the current size of the Panel in pixels as well as a percentage of the parent group (0..100).
|
||
*
|
||
* @return Panel size (in pixels and as a percentage of the parent group)
|
||
*/
|
||
getSize: () => {
|
||
asPercentage: number;
|
||
inPixels: number;
|
||
};
|
||
/**
|
||
* The Panel is currently collapsed.
|
||
*/
|
||
isCollapsed: () => boolean;
|
||
/**
|
||
* Update the Panel's size.
|
||
*
|
||
* Size can be in the following formats:
|
||
* - Percentage of the parent Group (0..100)
|
||
* - Pixels
|
||
* - Relative font units (em, rem)
|
||
* - Viewport relative units (vh, vw)
|
||
*
|
||
* ℹ️ Numeric values are assumed to be pixels.
|
||
* Strings without explicit units are assumed to be percentages (0%..100%).
|
||
* Percentages may also be specified as strings ending with "%" (e.g. "33%")
|
||
* Pixels may also be specified as strings ending with the unit "px".
|
||
* Other units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)
|
||
*
|
||
* @param size New panel size
|
||
* @return Applied size (after validation)
|
||
*/
|
||
resize: (size: number | string) => void;
|
||
}
|
||
|
||
export declare type PanelProps = BasePanelAttributes & {
|
||
/**
|
||
* CSS class name.
|
||
*
|
||
* ⚠️ Class is applied to nested `HTMLDivElement` to avoid styles that interfere with Flex layout.
|
||
*/
|
||
className?: string | undefined;
|
||
/**
|
||
* Panel size when collapsed; defaults to 0%.
|
||
*/
|
||
collapsedSize?: number | string | undefined;
|
||
/**
|
||
* This panel can be collapsed.
|
||
*
|
||
* ℹ️ A collapsible panel will collapse when it's size is less than of the specified `minSize`
|
||
*/
|
||
collapsible?: boolean | undefined;
|
||
/**
|
||
* Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.
|
||
*/
|
||
defaultSize?: number | string | undefined;
|
||
/**
|
||
* Ref attached to the root `HTMLDivElement`.
|
||
*/
|
||
elementRef?: Ref<HTMLDivElement> | undefined;
|
||
/**
|
||
* Uniquely identifies this panel within the parent group.
|
||
* Falls back to `useId` when not provided.
|
||
*
|
||
* ℹ️ This prop is used to associate persisted group layouts with the original panel.
|
||
*
|
||
* ℹ️ This value will also be assigned to the `data-panel` attribute.
|
||
*/
|
||
id?: string | number | undefined;
|
||
/**
|
||
* Maximum size of Panel within its parent group; defaults to 100%.
|
||
*/
|
||
maxSize?: number | string | undefined;
|
||
/**
|
||
* Minimum size of Panel within its parent group; defaults to 0%.
|
||
*/
|
||
minSize?: number | string | undefined;
|
||
/**
|
||
* Called when panel sizes change.
|
||
*
|
||
* @param panelSize Panel size (both as a percentage of the parent Group and in pixels)
|
||
* @param id Panel id (if one was provided as a prop)
|
||
* @param prevPanelSize Previous panel size (will be undefined on mount)
|
||
*/
|
||
onResize?: ((panelSize: PanelSize, id: string | number | undefined, prevPanelSize: PanelSize | undefined) => void) | undefined;
|
||
/**
|
||
* Exposes the following imperative API:
|
||
* - `collapse(): void`
|
||
* - `expand(): void`
|
||
* - `getSize(): number`
|
||
* - `isCollapsed(): boolean`
|
||
* - `resize(size: number): void`
|
||
*
|
||
* ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
|
||
*/
|
||
panelRef?: Ref<PanelImperativeHandle> | undefined;
|
||
/**
|
||
* CSS properties.
|
||
*
|
||
* ⚠️ Style is applied to nested `HTMLDivElement` to avoid styles that interfere with Flex layout.
|
||
*/
|
||
style?: CSSProperties | undefined;
|
||
};
|
||
|
||
export declare type PanelSize = {
|
||
asPercentage: number;
|
||
inPixels: number;
|
||
};
|
||
|
||
/**
|
||
* Separators are not _required_ but they are _recommended_ as they improve keyboard accessibility.
|
||
*
|
||
* Separators should be rendered as the direct child of a Group component.
|
||
*
|
||
* Separator elements always include the following attributes:
|
||
*
|
||
* ```html
|
||
* <div data-separator data-testid="separator-id-prop" id="separator-id-prop" role="separator">
|
||
* ```
|
||
*
|
||
* ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
||
*
|
||
* ℹ️ In addition to the attributes shown above, separator also renders all required [WAI-ARIA properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role#associated_wai-aria_roles_states_and_properties).
|
||
*/
|
||
export declare function Separator({ children, className, elementRef: elementRefProp, id: idProp, style, ...rest }: SeparatorProps): JSX.Element;
|
||
|
||
export declare namespace Separator {
|
||
var displayName: string;
|
||
}
|
||
|
||
export declare type SeparatorProps = BaseSeparatorAttributes & {
|
||
/**
|
||
* CSS class name.
|
||
*
|
||
* ℹ️ Use the `data-separator` attribute for custom _hover_ and _active_ styles
|
||
*
|
||
* ⚠️ The following properties cannot be overridden: `flex-grow`, `flex-shrink`
|
||
*/
|
||
className?: string | undefined;
|
||
/**
|
||
* Ref attached to the root `HTMLDivElement`.
|
||
*/
|
||
elementRef?: Ref<HTMLDivElement> | undefined;
|
||
/**
|
||
* Uniquely identifies the separator within the parent group.
|
||
* Falls back to `useId` when not provided.
|
||
*
|
||
* ℹ️ This value will also be assigned to the `data-separator` attribute.
|
||
*/
|
||
id?: string | number | undefined;
|
||
/**
|
||
* CSS properties.
|
||
*
|
||
* ℹ️ Use the `data-separator` attribute for custom _hover_ and _active_ styles
|
||
*
|
||
* ⚠️ The following properties cannot be overridden: `flex-grow`, `flex-shrink`
|
||
*/
|
||
style?: CSSProperties | undefined;
|
||
};
|
||
|
||
export declare type SizeUnit = "px" | "%" | "em" | "rem" | "vh" | "vw";
|
||
|
||
/**
|
||
* Saves and restores group layouts between page loads.
|
||
* It can be configured to store values using `localStorage`, `sessionStorage`, cookies, or any other persistence layer that makes sense for your application.
|
||
*/
|
||
export declare function useDefaultLayout({ debounceSaveMs, panelIds, storage, ...rest }: {
|
||
/**
|
||
* Debounce save operation by the specified number of milliseconds; defaults to 100ms
|
||
*/
|
||
debounceSaveMs?: number;
|
||
/**
|
||
* For Groups that contain conditionally-rendered Panels, this prop can be used to save and restore multiple layouts.
|
||
*
|
||
* ℹ️ This prevents layout shift for server-rendered apps.
|
||
*
|
||
* ⚠️ Panel ids must match the Panels rendered within the Group during mount or the initial layout will be incorrect.
|
||
*/
|
||
panelIds?: string[] | undefined;
|
||
/**
|
||
* Storage implementation; supports localStorage, sessionStorage, and custom implementations
|
||
* Refer to documentation site for example integrations.
|
||
*
|
||
*/
|
||
storage?: LayoutStorage;
|
||
} & ({
|
||
/**
|
||
* Group id; must be unique in order for layouts to be saved separately.
|
||
* @deprecated Use the {@link id} param instead
|
||
*/
|
||
groupId: string;
|
||
} | {
|
||
/**
|
||
* Uniquely identifies a specific group/layout.
|
||
*/
|
||
id: string;
|
||
})): {
|
||
defaultLayout: Layout | undefined;
|
||
onLayoutChange: (layout: Layout) => void | undefined;
|
||
};
|
||
|
||
/**
|
||
* Convenience hook to return a properly typed ref callback for the Group component.
|
||
*
|
||
* Use this hook when you need to share the ref with another component or hook.
|
||
*/
|
||
export declare function useGroupCallbackRef(): [GroupImperativeHandle | null, Dispatch<SetStateAction<GroupImperativeHandle | null>>];
|
||
|
||
/**
|
||
* Convenience hook to return a properly typed ref for the Group component.
|
||
*/
|
||
export declare function useGroupRef(): RefObject<GroupImperativeHandle | null>;
|
||
|
||
/**
|
||
* Convenience hook to return a properly typed ref callback for the Panel component.
|
||
*
|
||
* Use this hook when you need to share the ref with another component or hook.
|
||
*/
|
||
export declare function usePanelCallbackRef(): [PanelImperativeHandle | null, Dispatch<SetStateAction<PanelImperativeHandle | null>>];
|
||
|
||
/**
|
||
* Convenience hook to return a properly typed ref for the Panel component.
|
||
*/
|
||
export declare function usePanelRef(): RefObject<PanelImperativeHandle | null>;
|
||
|
||
export { }
|