From 6ced232eecaf3958b787685fe420f01f8c3e8bbe Mon Sep 17 00:00:00 2001 From: Rogin Farrer Date: Wed, 19 Jun 2024 13:17:59 -0700 Subject: [PATCH] fix readme --- packages/react/README.md | 93 +++++++++++++++++-------------- packages/react/src/useCollapse.ts | 4 +- 2 files changed, 53 insertions(+), 44 deletions(-) diff --git a/packages/react/README.md b/packages/react/README.md index cc02d4e..e9bea0a 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -77,50 +77,59 @@ function Demo() { ## API -```js -const { getCollapseProps, getToggleProps, isExpanded, setExpanded } = - useCollapse({ - isExpanded: boolean, - defaultExpanded: boolean, - expandStyles: {}, - collapseStyles: {}, - collapsedHeight: 0, - easing: string, - duration: number, - onCollapseStart: func, - onCollapseEnd: func, - onExpandStart: func, - onExpandEnd: func, - }); +`useCollapse` takes the following options: + +```ts +interface UseCollapseOptions { + /** If true, the disclosure is expanded. */ + isExpanded?: boolean; + /** + * If true, the disclosure is expanded when it initially mounts. + * @default false + */ + defaultExpanded?: boolean; + /** Handler called when the disclosure expands or collapses */ + onExpandedChange?: (state: boolean) => void; + /** Handler called at each stage of the animation. */ + onTransitionStateChange?: ( + state: + | "expandStart" + | "expanding" + | "expandEnd" + | "collapseStart" + | "collapsing" + | "collapseEnd", + ) => void; + /** Timing function for the transition */ + easing?: string; + /** + * Duration of the expand/collapse animation. + * If 'auto', the duration will be calculated based on the height of the collapse element + */ + duration?: "auto" | number; + /** Height in pixels that the collapse element collapses to */ + collapsedHeight?: number; + /** + * Unique identifier used to for associating elements appropriately for accessibility. + */ + id?: string; +} ``` -### `useCollapse` Config - -The following are optional properties passed into `useCollapse({ })`: - -| Prop | Type | Default | Description | -| -------------------- | -------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| isExpanded | boolean | `undefined` | If true, the Collapse is expanded | -| defaultExpanded | boolean | `false` | If true, the Collapse will be expanded when mounted | -| expandStyles | object | `{}` | Style object applied to the collapse panel when it expands | -| collapseStyles | object | `{}` | Style object applied to the collapse panel when it collapses | -| collapsedHeight | number | `0` | The height of the content when collapsed | -| easing | string | `cubic-bezier(0.4, 0, 0.2, 1)` | The transition timing function for the animation | -| duration | number | `undefined` | The duration of the animation in milliseconds. By default, the duration is programmatically calculated based on the height of the collapsed element | -| onCollapseStart | function | no-op | Handler called when the collapse animation begins | -| onCollapseEnd | function | no-op | Handler called when the collapse animation ends | -| onExpandStart | function | no-op | Handler called when the expand animation begins | -| onExpandEnd | function | no-op | Handler called when the expand animation ends | -| hasDisabledAnimation | boolean | `undefined` | If true, will disable the animation. If `undefined`, will fallback to media `prefers-reduced-animation` setting. | - -### What you get - -| Name | Description | -| ---------------- | ----------------------------------------------------------------------------------------------------------- | -| getCollapseProps | Function that returns a prop object, which should be spread onto the collapse element | -| getToggleProps | Function that returns a prop object, which should be spread onto an element that toggles the collapse panel | -| isExpanded | Whether or not the collapse is expanded (if not controlled) | -| setExpanded | Sets the hook's internal isExpanded state | +And returns the following API: + +```ts +interface CollapseAPI { + isExpanded: boolean; + setExpanded: (update: boolean | ((prev: boolean) => boolean)) => void; + getToggleProps: ( + props?: React.ComponentPropsWithoutRef & { refKey?: string }, + ) => React.ComponentPropsWithRef; + getCollapseProps: ( + props?: React.ComponentPropsWithoutRef & { refKey?: string }, + ) => React.ComponentPropsWithRef; +} +``` ## Alternative Solutions diff --git a/packages/react/src/useCollapse.ts b/packages/react/src/useCollapse.ts index e9890b9..1857aee 100644 --- a/packages/react/src/useCollapse.ts +++ b/packages/react/src/useCollapse.ts @@ -2,7 +2,7 @@ import * as React from "react"; import { Collapse, CollapseOptions } from "@collapsed/core"; import { AssignableRef, mergeRefs, useControlledState } from "./utils"; -export interface UseCollapseParams +export interface UseCollapseOptions extends Omit { /** * If true, the disclosure is expanded. @@ -30,7 +30,7 @@ export function useCollapse({ collapsedHeight = 0, onTransitionStateChange = () => {}, id: propId, -}: UseCollapseParams = {}) { +}: UseCollapseOptions = {}) { const reactId = React.useId(); const [isExpanded, setExpanded] = useControlledState( propExpanded,