@databricks/appkit-ui 0.2.0 → 0.4.0

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

@@ -0,0 +1,338 @@
+# NavigationMenu
+
+Horizontal navigation menu with dropdown submenus
+
+## Example[​](#example "Direct link to Example")
+
+<!-- -->
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import {
+  cn,
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+  navigationMenuTriggerStyle,
+} from "@databricks/appkit-ui/react"
+
+const components: { title: string; href: string; description: string }[] = [
+  {
+    title: "Alert Dialog",
+    href: "/docs/primitives/alert-dialog",
+    description:
+      "A modal dialog that interrupts the user with important content and expects a response.",
+  },
+  {
+    title: "Hover Card",
+    href: "/docs/primitives/hover-card",
+    description:
+      "For sighted users to preview content available behind a link.",
+  },
+  {
+    title: "Progress",
+    href: "/docs/primitives/progress",
+    description:
+      "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.",
+  },
+  {
+    title: "Scroll-area",
+    href: "/docs/primitives/scroll-area",
+    description: "Visually or semantically separates content.",
+  },
+  {
+    title: "Tabs",
+    href: "/docs/primitives/tabs",
+    description:
+      "A set of layered sections of content—known as tab panels—that are displayed one at a time.",
+  },
+  {
+    title: "Tooltip",
+    href: "/docs/primitives/tooltip",
+    description:
+      "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.",
+  },
+]
+
+export default function NavigationMenuExample() {
+  return (
+    <NavigationMenu>
+      <NavigationMenuList>
+        <NavigationMenuItem>
+          <NavigationMenuTrigger>About</NavigationMenuTrigger>
+          <NavigationMenuContent>
+            <ul className="grid gap-3 p-6 md:w-[400px] lg:w-[500px] lg:grid-cols-[.75fr_1fr]">
+              <li className="row-span-3">
+                <NavigationMenuLink asChild>
+                  <a
+                    className="flex h-full w-full select-none flex-col justify-end rounded-md bg-gradient-to-b from-muted/50 to-muted p-6 no-underline outline-none focus:shadow-md"
+                    href="#"
+                  >
+                    <div className="mb-2 mt-4 text-lg font-medium">
+                      AppKit
+                    </div>
+                    <p className="text-sm leading-tight text-muted-foreground">
+                      Everything you need out-of-the-box.
+                    </p>
+                  </a>
+                </NavigationMenuLink>
+              </li>
+              <ListItem href="#" title="Extensible Plugins">
+               Extend at any level.
+              </ListItem>
+              <ListItem href="#" title="Type-Safe SQL Queries">
+                Full parameter type safety across your entire stack.
+              </ListItem>
+              <ListItem href="#" title="Built for Humans & AI">
+                 Designed for both developers and AI agents.
+              </ListItem>
+            </ul>
+          </NavigationMenuContent>
+        </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
+          <NavigationMenuContent>
+            <ul className="grid w-[400px] gap-3 p-4 md:w-[500px] md:grid-cols-2 lg:w-[600px] ">
+              {components.map((component) => (
+                <ListItem
+                  key={component.title}
+                  title={component.title}
+                  href={component.href}
+                >
+                  {component.description}
+                </ListItem>
+              ))}
+            </ul>
+          </NavigationMenuContent>
+        </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuLink asChild>
+            <a href="#" className={navigationMenuTriggerStyle()}>
+              Documentation
+            </a>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+      </NavigationMenuList>
+    </NavigationMenu>
+  )
+}
+
+const ListItem = React.forwardRef<
+  React.ElementRef<"a">,
+  React.ComponentPropsWithoutRef<"a">
+>(({ className, title, children, ...props }, ref) => {
+  return (
+    <li>
+      <NavigationMenuLink asChild>
+        <a
+          ref={ref}
+          className={cn(
+            "block select-none space-y-1 rounded-md p-3 leading-none no-underline outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground",
+            className
+          )}
+          {...props}
+        >
+          <div className="text-sm font-medium leading-none">{title}</div>
+          <p className="line-clamp-2 text-sm leading-snug text-muted-foreground">
+            {children}
+          </p>
+        </a>
+      </NavigationMenuLink>
+    </li>
+  )
+})
+ListItem.displayName = "ListItem"
+
+```
+
+## NavigationMenu[​](#navigationmenu-1 "Direct link to NavigationMenu")
+
+Horizontal navigation menu with dropdown submenus
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props "Direct link to Props")
+
+| Prop                | Type                        | Required | Default | Description                                                                                            |
+| ------------------- | --------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `value`             | `string`                    |          | -       | -                                                                                                      |
+| `defaultValue`      | `string`                    |          | -       | -                                                                                                      |
+| `onValueChange`     | `((value: string) => void)` |          | -       | -                                                                                                      |
+| `dir`               | `enum`                      |          | -       | -                                                                                                      |
+| `orientation`       | `enum`                      |          | -       | -                                                                                                      |
+| `delayDuration`     | `number`                    |          | -       | The duration from when the pointer enters the trigger until the tooltip gets opened. @defaultValue 200 |
+| `skipDelayDuration` | `number`                    |          | -       | How much time a user has to enter another trigger without incurring a delay again. @defaultValue 300   |
+| `asChild`           | `boolean`                   |          | -       | -                                                                                                      |
+| `viewport`          | `boolean`                   |          | `true`  | -                                                                                                      |
+
+### Usage[​](#usage "Direct link to Usage")
+
+```tsx
+import { NavigationMenu } from '@databricks/appkit-ui';
+
+<NavigationMenu /* props */ />
+
+```
+
+## NavigationMenuContent[​](#navigationmenucontent "Direct link to NavigationMenuContent")
+
+Dropdown content area for navigation submenu
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-1 "Direct link to Props")
+
+| Prop                   | Type                                                              | Required | Default | Description                                                                                                                                                                               |
+| ---------------------- | ----------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forceMount`           | `true`                                                            |          | -       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.                                                                     |
+| `asChild`              | `boolean`                                                         |          | -       | -                                                                                                                                                                                         |
+| `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. |
+
+### Usage[​](#usage-1 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuContent } from '@databricks/appkit-ui';
+
+<NavigationMenuContent /* props */ />
+
+```
+
+## NavigationMenuIndicator[​](#navigationmenuindicator "Direct link to NavigationMenuIndicator")
+
+Visual indicator for active navigation menu item
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-2 "Direct link to Props")
+
+| Prop         | Type      | Required | Default | Description                                                                                                           |
+| ------------ | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `forceMount` | `true`    |          | -       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
+| `asChild`    | `boolean` |          | -       | -                                                                                                                     |
+
+### Usage[​](#usage-2 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuIndicator } from '@databricks/appkit-ui';
+
+<NavigationMenuIndicator /* props */ />
+
+```
+
+## NavigationMenuItem[​](#navigationmenuitem "Direct link to NavigationMenuItem")
+
+Individual navigation menu item
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-3 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `value`   | `string`  |          | -       | -           |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-3 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuItem } from '@databricks/appkit-ui';
+
+<NavigationMenuItem /* props */ />
+
+```
+
+## NavigationMenuLink[​](#navigationmenulink "Direct link to NavigationMenuLink")
+
+Clickable link within navigation menu
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-4 "Direct link to Props")
+
+| Prop       | Type                       | Required | Default | Description |
+| ---------- | -------------------------- | -------- | ------- | ----------- |
+| `active`   | `boolean`                  |          | -       | -           |
+| `onSelect` | `((event: Event) => void)` |          | -       | -           |
+| `asChild`  | `boolean`                  |          | -       | -           |
+
+### Usage[​](#usage-4 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuLink } from '@databricks/appkit-ui';
+
+<NavigationMenuLink /* props */ />
+
+```
+
+## NavigationMenuList[​](#navigationmenulist "Direct link to NavigationMenuList")
+
+Container list for navigation menu items
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-5 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-5 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuList } from '@databricks/appkit-ui';
+
+<NavigationMenuList /* props */ />
+
+```
+
+## NavigationMenuTrigger[​](#navigationmenutrigger "Direct link to NavigationMenuTrigger")
+
+Button that opens a navigation submenu
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-6 "Direct link to Props")
+
+| Prop      | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `asChild` | `boolean` |          | -       | -           |
+
+### Usage[​](#usage-6 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuTrigger } from '@databricks/appkit-ui';
+
+<NavigationMenuTrigger /* props */ />
+
+```
+
+## NavigationMenuViewport[​](#navigationmenuviewport "Direct link to NavigationMenuViewport")
+
+Viewport container for navigation menu content
+
+**Source:** [`packages/appkit-ui/src/react/ui/navigation-menu.tsx`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/ui/navigation-menu.tsx)
+
+### Props[​](#props-7 "Direct link to Props")
+
+| Prop         | Type      | Required | Default | Description                                                                                                           |
+| ------------ | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `forceMount` | `true`    |          | -       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
+| `asChild`    | `boolean` |          | -       | -                                                                                                                     |
+
+### Usage[​](#usage-7 "Direct link to Usage")
+
+```tsx
+import { NavigationMenuViewport } from '@databricks/appkit-ui';
+
+<NavigationMenuViewport /* props */ />
+
+```