@databricks/appkit 0.3.0 → 0.4.0

package/docs/docs/api/appkit-ui/ui/Drawer.md

@@ -0,0 +1,387 @@
+# Drawer
+
+Draggable panel that slides in from screen edges
+
+## Example[​](#example "Direct link to Example")
+
+<!-- -->
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { Minus, Plus } from "lucide-react"
+import { Bar, BarChart, ResponsiveContainer } from "recharts"
+
+import {
+  Button,
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+} from "@databricks/appkit-ui/react"
+
+const data = [
+  {
+    goal: 400,
+  },
+  {
+    goal: 300,
+  },
+  {
+    goal: 200,
+  },
+  {
+    goal: 300,
+  },
+  {
+    goal: 200,
+  },
+  {
+    goal: 278,
+  },
+  {
+    goal: 189,
+  },
+  {
+    goal: 239,
+  },
+  {
+    goal: 300,
+  },
+  {
+    goal: 200,
+  },
+  {
+    goal: 278,
+  },
+  {
+    goal: 189,
+  },
+  {
+    goal: 349,
+  },
+]
+
+export default function DrawerExample() {
+  const [goal, setGoal] = React.useState(350)
+
+  function onClick(adjustment: number) {
+    setGoal(Math.max(200, Math.min(400, goal + adjustment)))
+  }
+
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button variant="outline">Open Drawer</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <div className="mx-auto w-full max-w-sm">
+          <DrawerHeader>
+            <DrawerTitle>Move Goal</DrawerTitle>
+            <DrawerDescription>Set your daily activity goal.</DrawerDescription>
+          </DrawerHeader>
+          <div className="p-4 pb-0">
+            <div className="flex items-center justify-center space-x-2">
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8 shrink-0 rounded-full"
+                onClick={() => onClick(-10)}
+                disabled={goal <= 200}
+              >
+                <Minus />
+                <span className="sr-only">Decrease</span>
+              </Button>
+              <div className="flex-1 text-center">
+                <div className="text-7xl font-bold tracking-tighter">
+                  {goal}
+                </div>
+                <div className="text-[0.70rem] uppercase text-muted-foreground">
+                  Calories/day
+                </div>
+              </div>
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8 shrink-0 rounded-full"
+                onClick={() => onClick(10)}
+                disabled={goal >= 400}
+              >
+                <Plus />
+                <span className="sr-only">Increase</span>
+              </Button>
+            </div>
+            <div className="mt-3 h-[120px]">
+              <ResponsiveContainer width="100%" height="100%">
+                <BarChart data={data}>
+                  <Bar
+                    dataKey="goal"
+                    style={{
+                      fill: "hsl(var(--foreground))",
+                      opacity: 0.9,
+                    }}
+                  />
+                </BarChart>
+              </ResponsiveContainer>
+            </div>
+          </div>
+          <DrawerFooter>
+            <Button>Submit</Button>
+            <DrawerClose asChild>
+              <Button variant="outline">Cancel</Button>
+            </DrawerClose>
+          </DrawerFooter>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+
+```
+
+## Drawer[​](#drawer-1 "Direct link to Drawer")
+
+Draggable panel that slides in from screen edges
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop                        | Type                                                                         | Required | Default                                    | Description                                                                                                                                                                                                                               |
+| --------------------------- | ---------------------------------------------------------------------------- | -------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activeSnapPoint`           | `string \| number \| null`                                                   |          | -                                          | -                                                                                                                                                                                                                                         |
+| `setActiveSnapPoint`        | `((snapPoint: string \| number \| null) => void)`                            |          | -                                          | -                                                                                                                                                                                                                                         |
+| `open`                      | `boolean`                                                                    |          | -                                          | -                                                                                                                                                                                                                                         |
+| `closeThreshold`            | `number`                                                                     |          | `0.25`                                     | Number between 0 and 1 that determines when the drawer should be closed. Example: threshold of 0.5 would close the drawer if the user swiped for 50% of the height of the drawer or more.                                                 |
+| `noBodyStyles`              | `boolean`                                                                    |          | -                                          | When `true` the `body` doesn't get any styles assigned from Vaul                                                                                                                                                                          |
+| `onOpenChange`              | `((open: boolean) => void)`                                                  |          | -                                          | -                                                                                                                                                                                                                                         |
+| `shouldScaleBackground`     | `boolean`                                                                    |          | -                                          | -                                                                                                                                                                                                                                         |
+| `setBackgroundColorOnScale` | `boolean`                                                                    |          | `true`                                     | When `false` we don't change body's background color when the drawer is open.                                                                                                                                                             |
+| `scrollLockTimeout`         | `number`                                                                     |          | `500ms`                                    | Duration for which the drawer is not draggable after scrolling content inside of the drawer.                                                                                                                                              |
+| `fixed`                     | `boolean`                                                                    |          | -                                          | When `true`, don't move the drawer upwards if there's space, but rather only change it's height so it's fully scrollable when the keyboard is open                                                                                        |
+| `handleOnly`                | `boolean`                                                                    |          | `false`                                    | When `true` only allows the drawer to be dragged by the `&lt;Drawer.Handle /&gt;` component.                                                                                                                                              |
+| `dismissible`               | `boolean`                                                                    |          | `true`                                     | When `false` dragging, clicking outside, pressing esc, etc. will not close the drawer. Use this in comination with the `open` prop, otherwise you won't be able to open/close the drawer.                                                 |
+| `onDrag`                    | `((event: PointerEvent<HTMLDivElement>, percentageDragged: number) => void)` |          | -                                          | -                                                                                                                                                                                                                                         |
+| `onRelease`                 | `((event: PointerEvent<HTMLDivElement>, open: boolean) => void)`             |          | -                                          | -                                                                                                                                                                                                                                         |
+| `modal`                     | `boolean`                                                                    |          | `true`                                     | When `false` it allows to interact with elements outside of the drawer without closing it.                                                                                                                                                |
+| `nested`                    | `boolean`                                                                    |          | -                                          | -                                                                                                                                                                                                                                         |
+| `onClose`                   | `(() => void)`                                                               |          | -                                          | -                                                                                                                                                                                                                                         |
+| `direction`                 | `enum`                                                                       |          | `'bottom'`                                 | Direction of the drawer. Can be `top` or `bottom`, `left`, `right`.                                                                                                                                                                       |
+| `defaultOpen`               | `boolean`                                                                    |          | `false`                                    | Opened by default, skips initial enter animation. Still reacts to `open` state changes                                                                                                                                                    |
+| `disablePreventScroll`      | `boolean`                                                                    |          | `false`                                    | When set to `true` prevents scrolling on the document body on mount, and restores it on unmount.                                                                                                                                          |
+| `repositionInputs`          | `boolean`                                                                    |          | `true when {@link snapPoints } is defined` | When `true` Vaul will reposition inputs rather than scroll then into view if the keyboard is in the way. Setting it to `false` will fall back to the default browser behavior.                                                            |
+| `snapToSequentialPoint`     | `boolean`                                                                    |          | `false`                                    | Disabled velocity based swiping for snap points. This means that a snap point won't be skipped even if the velocity is high enough. Useful if each snap point in a drawer is equally important.                                           |
+| `container`                 | `HTMLElement \| null`                                                        |          | -                                          | -                                                                                                                                                                                                                                         |
+| `onAnimationEnd`            | `((open: boolean) => void)`                                                  |          | -                                          | Gets triggered after the open or close animation ends, it receives an `open` argument with the `open` state of the drawer by the time the function was triggered. Useful to revert any state changes for example.                         |
+| `preventScrollRestoration`  | `boolean`                                                                    |          | -                                          | -                                                                                                                                                                                                                                         |
+| `autoFocus`                 | `boolean`                                                                    |          | -                                          | -                                                                                                                                                                                                                                         |
+| `snapPoints`                | `(string \| number)[]`                                                       |          | -                                          | Array of numbers from 0 to 100 that corresponds to % of the screen a given snap point should take up. Should go from least visible. Example `[0.2, 0.5, 0.8]`. You can also use px values, which doesn't take screen height into account. |
+| `fadeFromIndex`             | `number`                                                                     |          | -                                          | Index of a `snapPoint` from which the overlay fade should be applied. Defaults to the last snap point.                                                                                                                                    |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { Drawer } from '@databricks/appkit-ui';
+
+<Drawer /* props */ />
+
+```
+
+## DrawerClose[​](#drawerclose "Direct link to DrawerClose")
+
+Button that closes the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-1 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-1 "Direct link to Usage")
+
+```tsx
+import { DrawerClose } from '@databricks/appkit-ui';
+
+<DrawerClose /* props */ />
+
+```
+
+## DrawerContent[​](#drawercontent "Direct link to DrawerContent")
+
+Main content area of the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-2 "Direct link to Props")
+
+| Prop                   | Type                                                              | Required | Default | Description                                                                                                                                                                               |
+| ---------------------- | ----------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asChild`              | `boolean`                                                         |          | -       | -                                                                                                                                                                                         |
+| `forceMount`           | `true`                                                            |          | -       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.                                                                     |
+| `onEscapeKeyDown`      | `((event: KeyboardEvent) => void)`                                |          | -       | Event handler called when the escape key is down. Can be prevented.                                                                                                                       |
+| `onPointerDownOutside` | `((event: PointerDownOutsideEvent) => void)`                      |          | -       | Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.                                                                          |
+| `onFocusOutside`       | `((event: FocusOutsideEvent) => void)`                            |          | -       | Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.                                                                                            |
+| `onInteractOutside`    | `((event: FocusOutsideEvent \| PointerDownOutsideEvent) => void)` |          | -       | Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. |
+| `onOpenAutoFocus`      | `((event: Event) => void)`                                        |          | -       | Event handler called when auto-focusing on open. Can be prevented.                                                                                                                        |
+| `onCloseAutoFocus`     | `((event: Event) => void)`                                        |          | -       | Event handler called when auto-focusing on close. Can be prevented.                                                                                                                       |
+
+### Usage[​](#usage-2 "Direct link to Usage")
+
+```tsx
+import { DrawerContent } from '@databricks/appkit-ui';
+
+<DrawerContent /* props */ />
+
+```
+
+## DrawerDescription[​](#drawerdescription "Direct link to DrawerDescription")
+
+Description text for the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-3 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-3 "Direct link to Usage")
+
+```tsx
+import { DrawerDescription } from '@databricks/appkit-ui';
+
+<DrawerDescription /* props */ />
+
+```
+
+## DrawerFooter[​](#drawerfooter "Direct link to DrawerFooter")
+
+Footer section of the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-4 "Direct link to Props")
+
+This component extends standard HTML element attributes.
+
+### Usage[​](#usage-4 "Direct link to Usage")
+
+```tsx
+import { DrawerFooter } from '@databricks/appkit-ui';
+
+<DrawerFooter /* props */ />
+
+```
+
+## DrawerHeader[​](#drawerheader "Direct link to DrawerHeader")
+
+Header section of the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-5 "Direct link to Props")
+
+This component extends standard HTML element attributes.
+
+### Usage[​](#usage-5 "Direct link to Usage")
+
+```tsx
+import { DrawerHeader } from '@databricks/appkit-ui';
+
+<DrawerHeader /* props */ />
+
+```
+
+## DrawerOverlay[​](#draweroverlay "Direct link to DrawerOverlay")
+
+Dimmed overlay behind the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-6 "Direct link to Props")
+
+| Prop         | Type      | Required | Default | Description                                                                                                           |
+| ------------ | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `asChild`    | `boolean` |          | -       | -                                                                                                                     |
+| `forceMount` | `true`    |          | -       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
+
+### Usage[​](#usage-6 "Direct link to Usage")
+
+```tsx
+import { DrawerOverlay } from '@databricks/appkit-ui';
+
+<DrawerOverlay /* props */ />
+
+```
+
+## DrawerPortal[​](#drawerportal "Direct link to DrawerPortal")
+
+Portal container for drawer content
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-7 "Direct link to Props")
+
+| Prop         | Type                                  | Required | Default | Description                                                                                                           |
+| ------------ | ------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `container`  | `Element \| DocumentFragment \| null` |          | -       | Specify a container element to portal the content into.                                                               |
+| `forceMount` | `true`                                |          | -       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
+
+### Usage[​](#usage-7 "Direct link to Usage")
+
+```tsx
+import { DrawerPortal } from '@databricks/appkit-ui';
+
+<DrawerPortal /* props */ />
+
+```
+
+## DrawerTitle[​](#drawertitle "Direct link to DrawerTitle")
+
+Title text for the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-8 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-8 "Direct link to Usage")
+
+```tsx
+import { DrawerTitle } from '@databricks/appkit-ui';
+
+<DrawerTitle /* props */ />
+
+```
+
+## DrawerTrigger[​](#drawertrigger "Direct link to DrawerTrigger")
+
+Button that opens the drawer
+
+**Source:** [`packages/appkit-ui/src/react/ui/drawer.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/drawer.tsx)
+
+### Props[​](#props-9 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-9 "Direct link to Usage")
+
+```tsx
+import { DrawerTrigger } from '@databricks/appkit-ui';
+
+<DrawerTrigger /* props */ />
+
+```