@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/panel/app-sidebar.tsx

@@ -0,0 +1,439 @@
+import {
+  PREFETCH_CACHE_FOR,
+  flattenNavigationItems,
+  hasActiveNavigationItem,
+  navigationItemText,
+  type NavigationGroupSchema,
+  type NavigationItemSchema,
+} from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import { ChevronRightIcon } from 'lucide-react'
+import type { ComponentProps, ReactNode } from 'react'
+import { useDirection, usePanel, useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { badgeColorClasses, colorClass } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { NewTabHint } from '../../lib/new-tab-hint'
+import { cn } from '../../lib/utils'
+import { NotificationsMenu } from '../notifications/notifications-menu'
+import { Badge } from '../ui/badge'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarRail,
+} from '../ui/sidebar'
+import { GlobalSearch } from './global-search'
+import { NavLabel } from './nav-label'
+import { Slot } from './slot'
+import { TenantMenu } from './tenant-menu'
+import { UserMenu } from './user-menu'
+
+export function Brand({ className }: { className?: string }) {
+  const panel = usePanel()
+
+  return (
+    <Link
+      href={panel.url ?? '/'}
+      className={cn('flex items-center gap-2 overflow-hidden', className)}
+    >
+      {panel.brandLogo ? (
+        <>
+          <img
+            src={panel.brandLogo}
+            alt={panel.brandName}
+            style={{ height: panel.brandLogoHeight ?? '1.75rem' }}
+            className={cn('max-w-full object-contain', panel.darkModeBrandLogo && 'dark:hidden')}
+          />
+          {panel.darkModeBrandLogo && (
+            <img
+              src={panel.darkModeBrandLogo}
+              alt={panel.brandName}
+              style={{ height: panel.brandLogoHeight ?? '1.75rem' }}
+              className="hidden max-w-full object-contain dark:block"
+            />
+          )}
+        </>
+      ) : (
+        <>
+          <span className="bg-primary text-primary-foreground flex size-8 shrink-0 items-center justify-center rounded-lg text-sm font-bold">
+            {panel.brandName.charAt(0)}
+          </span>
+          <span className="truncate text-sm font-semibold group-data-[collapsible=icon]:hidden">
+            {panel.brandName}
+          </span>
+        </>
+      )}
+    </Link>
+  )
+}
+
+function NavBadge({ item }: { item: NavigationItemSchema }) {
+  const t = useT()
+
+  // `deferNavigationBadges()`: a placeholder until the deferred badges arrive.
+  if (item.badgePending) {
+    return (
+      <span
+        data-slot="badge"
+        aria-busy="true"
+        aria-label={t('loading', {}, 'Loading')}
+        className="bg-muted-foreground/20 ms-auto inline-block h-4 w-5 animate-pulse rounded-md"
+      />
+    )
+  }
+
+  if (item.badge === undefined || item.badge === null) return null
+
+  return (
+    <Badge
+      variant="outline"
+      className={cn('ms-auto px-1.5 py-0', colorClass(badgeColorClasses, item.badgeColor, 'gray'))}
+      title={item.badgeTooltip}
+    >
+      {item.badge}
+    </Badge>
+  )
+}
+
+/**
+ * A navigation link: an Inertia link, or a plain anchor for `openUrlInNewTab()`. Used as an
+ * `asChild` target, so it must pass on the classes, data attributes and handlers it receives.
+ */
+function NavLink({
+  item,
+  children,
+  ...props
+}: { item: NavigationItemSchema; children: ReactNode } & Omit<
+  ComponentProps<'a'>,
+  'href' | 'children'
+>) {
+  // `NavigationItem::extraAttributes()`; `class` is merged with the link's own.
+  const attributes = {
+    ...props,
+    ...extraProps(item.extraAttributes, props.className),
+  } as ComponentProps<'a'>
+
+  return item.openInNewTab ? (
+    <a {...attributes} href={item.url} target="_blank" rel="noopener noreferrer">
+      {children}
+      <NewTabHint />
+    </a>
+  ) : (
+    // Slot passes DOM props; Inertia's Link redefines a few event names, so pass them through untyped.
+    <Link
+      {...(attributes as Record<string, unknown>)}
+      href={item.url ?? '#'}
+      prefetch
+      cacheFor={PREFETCH_CACHE_FOR}
+    >
+      {children}
+    </Link>
+  )
+}
+
+/** Child items (any depth) with their own badges, new-tab links and nested children. */
+function NavSubItem({ item }: { item: NavigationItemSchema }) {
+  if (item.children && item.children.length > 0) {
+    return (
+      <SidebarMenuSubItem>
+        <Collapsible defaultOpen={item.active} className="group/nav-sub">
+          <CollapsibleTrigger asChild>
+            <SidebarMenuSubButton asChild isActive={item.active}>
+              <button type="button" {...extraProps(item.extraAttributes, 'w-full')}>
+                {item.icon && <Icon name={item.icon} />}
+                <NavLabel item={item} />
+                <NavBadge item={item} />
+                <ChevronRightIcon className="ms-auto transition-transform duration-200 group-data-[state=open]/nav-sub:rotate-90 rtl:rotate-180 rtl:group-data-[state=open]/nav-sub:rotate-90" />
+              </button>
+            </SidebarMenuSubButton>
+          </CollapsibleTrigger>
+          <CollapsibleContent>
+            <SidebarMenuSub>
+              {item.children.map((child) => (
+                <NavSubItem key={child.label} item={child} />
+              ))}
+            </SidebarMenuSub>
+          </CollapsibleContent>
+        </Collapsible>
+      </SidebarMenuSubItem>
+    )
+  }
+
+  return (
+    <SidebarMenuSubItem>
+      <SidebarMenuSubButton asChild isActive={item.active}>
+        <NavLink item={item}>
+          {item.icon && <Icon name={item.icon} />}
+          <NavLabel item={item} />
+          <NavBadge item={item} />
+        </NavLink>
+      </SidebarMenuSubButton>
+    </SidebarMenuSubItem>
+  )
+}
+
+function NavItem({ item }: { item: NavigationItemSchema }) {
+  if (item.children && item.children.length > 0) {
+    return (
+      <Collapsible asChild defaultOpen={item.active} className="group/collapsible">
+        <SidebarMenuItem>
+          <CollapsibleTrigger asChild>
+            <SidebarMenuButton
+              tooltip={navigationItemText(item)}
+              isActive={item.active}
+              {...extraProps(item.extraAttributes)}
+            >
+              {item.icon && <Icon name={item.icon} />}
+              <NavLabel item={item} />
+              <NavBadge item={item} />
+              <ChevronRightIcon className="ms-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90 rtl:rotate-180 rtl:group-data-[state=open]/collapsible:rotate-90" />
+            </SidebarMenuButton>
+          </CollapsibleTrigger>
+          <CollapsibleContent>
+            <SidebarMenuSub>
+              {item.children.map((child) => (
+                <NavSubItem key={child.label} item={child} />
+              ))}
+            </SidebarMenuSub>
+          </CollapsibleContent>
+        </SidebarMenuItem>
+      </Collapsible>
+    )
+  }
+
+  return (
+    <SidebarMenuItem>
+      <SidebarMenuButton asChild isActive={item.active} tooltip={navigationItemText(item)}>
+        <NavLink item={item}>
+          {item.icon && <Icon name={item.icon} />}
+          <NavLabel item={item} />
+          <NavBadge item={item} />
+        </NavLink>
+      </SidebarMenuButton>
+    </SidebarMenuItem>
+  )
+}
+
+/** A group's items in its flyout menu, children indented under their parent. */
+function FlyoutItems({ items }: { items: NavigationItemSchema[] }) {
+  return flattenNavigationItems(items).map(({ item, depth }, index) => (
+    <DropdownMenuItem
+      key={`${depth}-${item.label}-${index}`}
+      asChild
+      data-active={item.active ? 'true' : undefined}
+    >
+      <NavLink
+        item={item}
+        aria-current={item.active ? 'page' : undefined}
+        className={cn(
+          'data-[active=true]:bg-accent data-[active=true]:font-medium',
+          depth === 1 && 'ps-6',
+          depth > 1 && 'ps-9',
+        )}
+      >
+        {item.icon && <Icon name={item.icon} />}
+        <NavLabel item={item} className="truncate" />
+        <NavBadge item={item} />
+      </NavLink>
+    </DropdownMenuItem>
+  ))
+}
+
+/**
+ * In the icon-only (collapsed) sidebar, a group with an icon is one button that opens its
+ * items in a flyout menu, like Filament. Hidden while the sidebar is expanded.
+ */
+function NavGroupFlyout({ group }: { group: NavigationGroupSchema }) {
+  const direction = useDirection()
+  const active = hasActiveNavigationItem(group.items)
+
+  return (
+    <SidebarMenu className="hidden group-data-[collapsible=icon]:flex" data-nav-flyout="">
+      <SidebarMenuItem>
+        <DropdownMenu dir={direction}>
+          <DropdownMenuTrigger asChild>
+            <SidebarMenuButton isActive={active}>
+              <Icon name={group.icon!} />
+              <span>{group.label}</span>
+            </SidebarMenuButton>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            side={direction === 'rtl' ? 'left' : 'right'}
+            align="start"
+            className="min-w-56"
+          >
+            <DropdownMenuLabel>{group.label}</DropdownMenuLabel>
+            <FlyoutItems items={group.items} />
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  )
+}
+
+function NavGroup({ group }: { group: NavigationGroupSchema }) {
+  // `NavigationGroup::extraSidebarAttributes()`; `class` is merged with the group's own.
+  const attributes = extraProps(group.extraSidebarAttributes)
+  // A labelled group with an icon collapses into a flyout in the icon-only sidebar.
+  const flyout = Boolean(group.label && group.icon)
+  const content = (
+    <SidebarGroupContent className={cn(flyout && 'group-data-[collapsible=icon]:hidden')}>
+      <SidebarMenu>
+        {group.items.map((item) => (
+          <NavItem key={item.label} item={item} />
+        ))}
+      </SidebarMenu>
+    </SidebarGroupContent>
+  )
+  const flyoutMenu = flyout ? <NavGroupFlyout group={group} /> : null
+
+  if (!group.label) {
+    return <SidebarGroup {...attributes}>{content}</SidebarGroup>
+  }
+
+  if (!group.collapsible) {
+    return (
+      <SidebarGroup {...attributes}>
+        <SidebarGroupLabel>
+          {group.icon && <Icon name={group.icon} className="me-1.5" />}
+          {group.label}
+        </SidebarGroupLabel>
+        {content}
+        {flyoutMenu}
+      </SidebarGroup>
+    )
+  }
+
+  return (
+    <Collapsible
+      defaultOpen={!group.collapsed || group.items.some((item) => item.active)}
+      className="group/nav-group"
+    >
+      <SidebarGroup {...attributes}>
+        <CollapsibleTrigger asChild>
+          <SidebarGroupLabel
+            asChild
+            className="hover:bg-sidebar-accent w-full cursor-pointer justify-between"
+          >
+            <button type="button">
+              <span className="flex items-center gap-1.5">
+                {group.icon && <Icon name={group.icon} />}
+                {group.label}
+              </span>
+              <Icon
+                name="alfakit::panels.sidebar.group.collapse-button"
+                fallback={ChevronRightIcon}
+                className="size-3.5 transition-transform group-data-[state=open]/nav-group:rotate-90 rtl:rotate-180 rtl:group-data-[state=open]/nav-group:rotate-90"
+              />
+            </button>
+          </SidebarGroupLabel>
+        </CollapsibleTrigger>
+        <CollapsibleContent>{content}</CollapsibleContent>
+        {flyoutMenu}
+      </SidebarGroup>
+    </Collapsible>
+  )
+}
+
+export function AppSidebar() {
+  const panel = usePanel()
+  const direction = useDirection()
+  const t = useT()
+
+  return (
+    <Sidebar
+      side={direction === 'rtl' ? 'right' : 'left'}
+      collapsible={
+        panel.theme?.design?.layout === 'rail'
+          ? 'icon'
+          : panel.sidebarFullyCollapsibleOnDesktop
+            ? 'offcanvas'
+            : panel.sidebarCollapsibleOnDesktop
+              ? 'icon'
+              : 'none'
+      }
+      variant={panel.theme?.sidebar === 'flush' ? 'sidebar' : (panel.theme?.sidebar ?? 'inset')}
+    >
+      <SidebarHeader>
+        <Slot name="sidebar.start" />
+        <Slot name="sidebar.logo.before" />
+        <SidebarMenu>
+          <SidebarMenuItem>
+            {panel.tenancy?.current ? (
+              <>
+                <Slot name="tenant-menu.before" />
+                <TenantMenu />
+                <Slot name="tenant-menu.after" />
+              </>
+            ) : (
+              <SidebarMenuButton size="lg" asChild>
+                <div>
+                  <Brand />
+                </div>
+              </SidebarMenuButton>
+            )}
+          </SidebarMenuItem>
+        </SidebarMenu>
+        <Slot name="sidebar.logo.after" />
+        {/* `databaseNotifications(position: 'sidebar')` or `topbar(false)`. */}
+        {panel.databaseNotifications?.position === 'sidebar' && (
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <NotificationsMenu variant="sidebar" />
+            </SidebarMenuItem>
+          </SidebarMenu>
+        )}
+        {/* `globalSearch(position: GlobalSearchPosition::Sidebar)` or `topbar(false)`. */}
+        {panel.globalSearch?.position === 'sidebar' && (
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <GlobalSearch variant="sidebar" />
+            </SidebarMenuItem>
+          </SidebarMenu>
+        )}
+        <Slot name="sidebar.header" />
+      </SidebarHeader>
+      <SidebarContent>
+        <Slot name="sidebar.nav.start" />
+        <nav aria-label={t('sidebar', {}, 'Sidebar')} className="contents">
+          {panel.navigation.map((group, index) => (
+            <NavGroup key={group.label ?? `group-${index}`} group={group} />
+          ))}
+        </nav>
+        <Slot name="sidebar.nav.end" />
+      </SidebarContent>
+      <SidebarFooter>
+        <Slot name="sidebar.footer" />
+        {/* `userMenu(position: UserMenuPosition::Topbar)` shows it in the top bar instead. */}
+        {panel.userMenu?.position !== 'topbar' && (
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <UserMenu />
+            </SidebarMenuItem>
+          </SidebarMenu>
+        )}
+        <Slot name="sidebar.end" />
+      </SidebarFooter>
+      <SidebarRail />
+    </Sidebar>
+  )
+}

package/src/components/panel/bottom-nav.tsx

@@ -0,0 +1,130 @@
+import {
+  PREFETCH_CACHE_FOR,
+  bottomNavigationItems,
+  isNavigationItemActive,
+  navigationItemUrl,
+  type NavigationItemSchema,
+} from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import { MenuIcon } from 'lucide-react'
+import { useState } from 'react'
+import { usePanel, useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Sheet, SheetContent, SheetHeader, SheetTitle } from '../ui/sheet'
+import { NavLabel } from './nav-label'
+
+function BottomNavLink({
+  item,
+  onNavigate,
+}: {
+  item: NavigationItemSchema
+  onNavigate?: () => void
+}) {
+  const active = isNavigationItemActive(item)
+  const url = navigationItemUrl(item) ?? '#'
+
+  if (item.openInNewTab) {
+    return (
+      <a
+        {...extraProps(item.extraAttributes, 'min-w-0')}
+        href={url}
+        target="_blank"
+        rel="noopener noreferrer"
+        data-slot="bottom-nav-item"
+      >
+        {item.icon && <Icon name={item.icon} />}
+        <NavLabel item={item} className="max-w-full truncate" />
+      </a>
+    )
+  }
+
+  return (
+    <Link
+      {...extraProps(item.extraAttributes, 'min-w-0')}
+      href={url}
+      prefetch
+      cacheFor={PREFETCH_CACHE_FOR}
+      data-slot="bottom-nav-item"
+      data-active={active ? 'true' : undefined}
+      aria-current={active ? 'page' : undefined}
+      onClick={onNavigate}
+    >
+      {item.icon && <Icon name={item.icon} />}
+      <NavLabel item={item} className="max-w-full truncate" />
+    </Link>
+  )
+}
+
+/**
+ * The mobile preset's bottom navigation bar (`Panel::mobile()`): the top-level items, with
+ * the rest behind a "More" button that opens a sheet. Hidden from `md` up; replace it
+ * everywhere with `createAlfakit({ components: { 'panel:bottom-nav': … } })`.
+ */
+export function BottomNav() {
+  const panel = usePanel()
+  const t = useT()
+  const [open, setOpen] = useState(false)
+  const { primary, overflow } = bottomNavigationItems(panel.navigation)
+
+  if (primary.length === 0 && overflow.length === 0) {
+    return null
+  }
+
+  const overflowActive = overflow.some(isNavigationItemActive)
+
+  return (
+    <nav
+      data-slot="bottom-nav"
+      aria-label={t('navigation', {}, 'Navigation')}
+      className="md:hidden"
+    >
+      {primary.map((item) => (
+        <BottomNavLink key={item.label} item={item} />
+      ))}
+      {overflow.length > 0 && (
+        <Sheet open={open} onOpenChange={setOpen}>
+          <button
+            type="button"
+            data-slot="bottom-nav-item"
+            data-active={overflowActive ? 'true' : undefined}
+            aria-haspopup="dialog"
+            aria-expanded={open}
+            className="min-w-0 bg-transparent"
+            onClick={() => setOpen(true)}
+          >
+            <Icon name="alfakit::panels.topbar.open-sidebar-button" fallback={MenuIcon} />
+            <span className="max-w-full truncate">{t('more', {}, 'More')}</span>
+          </button>
+          <SheetContent side="bottom" className="max-h-[80dvh] overflow-y-auto rounded-t-xl p-0">
+            <SheetHeader className="border-b">
+              <SheetTitle>{t('more', {}, 'More')}</SheetTitle>
+            </SheetHeader>
+            <nav
+              aria-label={t('navigation', {}, 'Navigation')}
+              className="flex flex-col gap-1 p-3 text-sm"
+            >
+              {overflow
+                .flatMap((item) => [item, ...(item.children ?? [])])
+                .map((item) => (
+                  <Link
+                    key={item.label}
+                    href={navigationItemUrl(item) ?? '#'}
+                    onClick={() => setOpen(false)}
+                    data-active={isNavigationItemActive(item) ? 'true' : undefined}
+                    className={cn(
+                      'hover:bg-accent data-[active=true]:bg-accent flex min-h-11 items-center gap-3 rounded-md px-3 font-medium [&_svg]:size-4',
+                    )}
+                  >
+                    {item.icon && <Icon name={item.icon} />}
+                    <NavLabel item={item} />
+                  </Link>
+                ))}
+            </nav>
+          </SheetContent>
+        </Sheet>
+      )}
+    </nav>
+  )
+}

package/src/components/panel/debug-panel-slot.tsx

@@ -0,0 +1,25 @@
+import { createElement } from 'react'
+import { useAlfakitProps, useOptionalRegistry } from '../../context'
+import { lazyComponent } from '../../lib/lazy'
+
+// The drawer's code loads only on pages that carry `alfakitDebug` (`Panel::debugPanel()`
+// with `app.debug` on), never with the panel's entry.
+const DebugPanel = lazyComponent<object>(
+  () => import('./debug-panel').then((module) => module.DebugPanel),
+  () => null,
+)
+
+/**
+ * Where the top bars put the debug panel: nothing unless the page carries `alfakitDebug`,
+ * otherwise the registered `panel:debug-panel` component or the built-in drawer.
+ */
+export function DebugPanelSlot() {
+  const props = useAlfakitProps()
+  const registry = useOptionalRegistry()
+
+  if (!props.alfakitDebug) {
+    return null
+  }
+
+  return createElement(registry?.resolve('panel:debug-panel') ?? DebugPanel)
+}