@databricks/appkit 0.2.0 → 0.4.0

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

@@ -0,0 +1,287 @@
+# Command
+
+Command palette for keyboard-driven navigation and actions
+
+## Example[​](#example "Direct link to Example")
+
+<!-- -->
+
+```tsx
+import {
+  Calculator,
+  Calendar,
+  CreditCard,
+  Settings,
+  Smile,
+  User,
+} from "lucide-react"
+
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+  CommandShortcut,
+} from "@databricks/appkit-ui/react"
+
+export default function CommandExample() {
+  return (
+    <Command className="rounded-lg border shadow-md md:min-w-[450px]">
+      <CommandInput placeholder="Type a command or search..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandGroup heading="Suggestions">
+          <CommandItem>
+            <Calendar />
+            <span>Calendar</span>
+          </CommandItem>
+          <CommandItem>
+            <Smile />
+            <span>Search Emoji</span>
+          </CommandItem>
+          <CommandItem disabled>
+            <Calculator />
+            <span>Calculator</span>
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Settings">
+          <CommandItem>
+            <User />
+            <span>Profile</span>
+            <CommandShortcut>⌘P</CommandShortcut>
+          </CommandItem>
+          <CommandItem>
+            <CreditCard />
+            <span>Billing</span>
+            <CommandShortcut>⌘B</CommandShortcut>
+          </CommandItem>
+          <CommandItem>
+            <Settings />
+            <span>Settings</span>
+            <CommandShortcut>⌘S</CommandShortcut>
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  )
+}
+
+```
+
+## Command[​](#command-1 "Direct link to Command")
+
+Command palette for keyboard-driven navigation and actions
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop                      | Type                        | Required | Default | Description                                                                                                                                                                                                                                        |
+| ------------------------- | --------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asChild`                 | `boolean`                   |          | -       | -                                                                                                                                                                                                                                                  |
+| `label`                   | `string`                    |          | -       | Accessible label for this command menu. Not shown visibly.                                                                                                                                                                                         |
+| `shouldFilter`            | `boolean`                   |          | -       | Optionally set to `false` to turn off the automatic filtering and sorting. If `false`, you must conditionally render valid items based on the search query yourself.                                                                               |
+| `filter`                  | `CommandFilter`             |          | -       | Custom filter function for whether each command menu item should matches the given search query. It should return a number between 0 and 1, with 1 being the best match and 0 being hidden entirely. By default, uses the `command-score` library. |
+| `value`                   | `string`                    |          | -       | Optional controlled state of the selected command menu item.                                                                                                                                                                                       |
+| `onValueChange`           | `((value: string) => void)` |          | -       | Event handler called when the selected item of the menu changes.                                                                                                                                                                                   |
+| `loop`                    | `boolean`                   |          | -       | Optionally set to `true` to turn on looping around when using the arrow keys.                                                                                                                                                                      |
+| `disablePointerSelection` | `boolean`                   |          | -       | Optionally set to `true` to disable selection via pointer events.                                                                                                                                                                                  |
+| `vimBindings`             | `boolean`                   |          | -       | Set to `false` to disable ctrl+n/j/p/k shortcuts. Defaults to `true`.                                                                                                                                                                              |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { Command } from '@databricks/appkit-ui';
+
+<Command /* props */ />
+
+```
+
+## CommandDialog[​](#commanddialog "Direct link to CommandDialog")
+
+Dialog wrapper for the command palette
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-1 "Direct link to Props")
+
+| Prop              | Type                        | Required | Default                          | Description |
+| ----------------- | --------------------------- | -------- | -------------------------------- | ----------- |
+| `open`            | `boolean`                   |          | -                                | -           |
+| `defaultOpen`     | `boolean`                   |          | -                                | -           |
+| `onOpenChange`    | `((open: boolean) => void)` |          | -                                | -           |
+| `modal`           | `boolean`                   |          | -                                | -           |
+| `title`           | `string`                    |          | `Command Palette`                | -           |
+| `description`     | `string`                    |          | `Search for a command to run...` | -           |
+| `className`       | `string`                    |          | -                                | -           |
+| `showCloseButton` | `boolean`                   |          | `true`                           | -           |
+
+### Usage[​](#usage-1 "Direct link to Usage")
+
+```tsx
+import { CommandDialog } from '@databricks/appkit-ui';
+
+<CommandDialog /* props */ />
+
+```
+
+## CommandEmpty[​](#commandempty "Direct link to CommandEmpty")
+
+Empty state displayed when no commands match the search
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-2 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-2 "Direct link to Usage")
+
+```tsx
+import { CommandEmpty } from '@databricks/appkit-ui';
+
+<CommandEmpty /* props */ />
+
+```
+
+## CommandGroup[​](#commandgroup "Direct link to CommandGroup")
+
+Group of related command items with an optional heading
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-3 "Direct link to Props")
+
+| Prop         | Type        | Required | Default | Description                                                                        |
+| ------------ | ----------- | -------- | ------- | ---------------------------------------------------------------------------------- |
+| `asChild`    | `boolean`   |          | -       | -                                                                                  |
+| `heading`    | `ReactNode` |          | -       | Optional heading to render for this group.                                         |
+| `value`      | `string`    |          | -       | If no heading is provided, you must provide a value that is unique for this group. |
+| `forceMount` | `boolean`   |          | -       | Whether this group is forcibly rendered regardless of filtering.                   |
+
+### Usage[​](#usage-3 "Direct link to Usage")
+
+```tsx
+import { CommandGroup } from '@databricks/appkit-ui';
+
+<CommandGroup /* props */ />
+
+```
+
+## CommandInput[​](#commandinput "Direct link to CommandInput")
+
+Search input field for filtering command items
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-4 "Direct link to Props")
+
+| Prop            | Type                         | Required | Default | Description                                                  |
+| --------------- | ---------------------------- | -------- | ------- | ------------------------------------------------------------ |
+| `asChild`       | `boolean`                    |          | -       | -                                                            |
+| `value`         | `string`                     |          | -       | Optional controlled state for the value of the search input. |
+| `onValueChange` | `((search: string) => void)` |          | -       | Event handler called when the search value changes.          |
+
+### Usage[​](#usage-4 "Direct link to Usage")
+
+```tsx
+import { CommandInput } from '@databricks/appkit-ui';
+
+<CommandInput /* props */ />
+
+```
+
+## CommandItem[​](#commanditem "Direct link to CommandItem")
+
+Individual selectable command item
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-5 "Direct link to Props")
+
+| Prop         | Type                        | Required | Default | Description                                                                                                                                                                                                           |
+| ------------ | --------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asChild`    | `boolean`                   |          | -       | -                                                                                                                                                                                                                     |
+| `disabled`   | `boolean`                   |          | -       | Whether this item is currently disabled.                                                                                                                                                                              |
+| `onSelect`   | `((value: string) => void)` |          | -       | Event handler for when this item is selected, either via click or keyboard selection.                                                                                                                                 |
+| `value`      | `string`                    |          | -       | A unique value for this item. If no value is provided, it will be inferred from `children` or the rendered `textContent`. If your `textContent` changes between renders, you *must* provide a stable, unique `value`. |
+| `keywords`   | `string[]`                  |          | -       | Optional keywords to match against when filtering.                                                                                                                                                                    |
+| `forceMount` | `boolean`                   |          | -       | Whether this item is forcibly rendered regardless of filtering.                                                                                                                                                       |
+
+### Usage[​](#usage-5 "Direct link to Usage")
+
+```tsx
+import { CommandItem } from '@databricks/appkit-ui';
+
+<CommandItem /* props */ />
+
+```
+
+## CommandList[​](#commandlist "Direct link to CommandList")
+
+Scrollable list container for command items
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-6 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description                                                       |
+| --------- | --------- | -------- | ------- | ----------------------------------------------------------------- |
+| `asChild` | `boolean` |          | -       | -                                                                 |
+| `label`   | `string`  |          | -       | Accessible label for this List of suggestions. Not shown visibly. |
+
+### Usage[​](#usage-6 "Direct link to Usage")
+
+```tsx
+import { CommandList } from '@databricks/appkit-ui';
+
+<CommandList /* props */ />
+
+```
+
+## CommandSeparator[​](#commandseparator "Direct link to CommandSeparator")
+
+Visual separator between command groups
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-7 "Direct link to Props")
+
+| Prop           | Type      | Required | Default | Description                                                                                  |
+| -------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
+| `asChild`      | `boolean` |          | -       | -                                                                                            |
+| `alwaysRender` | `boolean` |          | -       | Whether this separator should always be rendered. Useful if you disable automatic filtering. |
+
+### Usage[​](#usage-7 "Direct link to Usage")
+
+```tsx
+import { CommandSeparator } from '@databricks/appkit-ui';
+
+<CommandSeparator /* props */ />
+
+```
+
+## CommandShortcut[​](#commandshortcut "Direct link to CommandShortcut")
+
+Keyboard shortcut indicator displayed next to command items
+
+**Source:** [`packages/appkit-ui/src/react/ui/command.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/command.tsx)
+
+### Props[​](#props-8 "Direct link to Props")
+
+This component extends standard HTML element attributes.
+
+### Usage[​](#usage-8 "Direct link to Usage")
+
+```tsx
+import { CommandShortcut } from '@databricks/appkit-ui';
+
+<CommandShortcut /* props */ />
+
+```