@alfakit/react 0.0.0-stage → 0.1.1

package/src/starter-kit/starter-kit.tsx

@@ -0,0 +1,196 @@
+import {
+  ActionRunner,
+  STARTER_KIT_TOASTER_ID,
+  Translator,
+  configureCharts,
+  installStarterKitRuntime,
+  registerRichEditorExtensions,
+  resolveRequestErrorNotification,
+  starterKitBreadcrumbsFromProps,
+  syncStarterKitPage,
+  type AlfakitOptions,
+  type AlfakitPageProps,
+  type StarterKitBreadcrumb,
+} from '@alfakit/core'
+import { usePage } from '@inertiajs/react'
+import { useEffect, useState, type ComponentType, type ReactNode } from 'react'
+import { setToasterId, showToast } from '../components/notifications/flash-toasts'
+import { Slot } from '../components/panel/slot'
+import {
+  AlfakitProvider,
+  useAlfakitProps,
+  type AlfakitContextValue,
+  type AnyComponent,
+} from '../context'
+import { AlfakitRoot } from '../create-alfakit'
+import { MAX_WIDTHS, type AppLayoutProps } from '../layouts/app-layout'
+import { preloadIcons } from '../lib/icons'
+import { cn } from '../lib/utils'
+import { AlfakitPage } from '../pages/page'
+import { createDefaultRegistry } from '../registry'
+
+/** The host's layout, as the starter kits' `AppLayout` takes its props. */
+export type StarterKitLayout = ComponentType<{
+  breadcrumbs?: StarterKitBreadcrumb[]
+  children: ReactNode
+}>
+
+export interface StarterKitPageOptions extends Pick<
+  AlfakitOptions<AnyComponent>,
+  'components' | 'pages' | 'chartFormatters' | 'chartPlugins' | 'richEditorExtensions'
+> {
+  /**
+   * The host layout Alfakit pages render in, usually the starter kit's `AppLayout`
+   * (`@/layouts/app-layout`). It receives the page's breadcrumbs as `{ title, href }`.
+   * `null` renders the pages without a host layout.
+   */
+  layout?: StarterKitLayout | null
+}
+
+/**
+ * The content area of an Alfakit page inside the host layout: what `layout:app` renders in
+ * starter kit mode instead of Alfakit's sidebar and top bar. Replace it with
+ * `createStarterKitPage({ components: { 'layout:app': MyContent } })`.
+ */
+export function StarterKitContentLayout({ children, maxContentWidth }: AppLayoutProps) {
+  const props = useAlfakitProps()
+  // The host's pages fill the content area, so starter kit pages default to the full width.
+  const width = maxContentWidth ?? props.alfakit.maxContentWidth ?? 'full'
+
+  return (
+    <div
+      data-slot="content"
+      data-alfakit-embedded=""
+      className={cn(
+        'mx-auto flex w-full min-w-0 flex-1 flex-col gap-6 p-4 md:p-6',
+        MAX_WIDTHS[width] ?? 'max-w-full',
+      )}
+    >
+      <Slot name="content.start" />
+      {children}
+      <Slot name="content.end" />
+    </div>
+  )
+}
+
+// One context for the browser session (it survives navigations between host and Alfakit
+// pages); a server render builds one per request so concurrent renders never share a locale.
+let browserContext: AlfakitContextValue | null = null
+
+function createStarterKitContext(options: StarterKitPageOptions): AlfakitContextValue {
+  const registry = createDefaultRegistry()
+    .register('layout:app', StarterKitContentLayout)
+    .registerMany(options.components ?? {})
+  const translator = new Translator()
+
+  return {
+    registry,
+    pages: { 'Alfakit/Page': AlfakitPage, ...options.pages },
+    translator,
+    actions: new ActionRunner({
+      endpoints: { action: '', modal: '' },
+      // A failed action request is a toast, never a silent no-op.
+      onError: (error) => {
+        const notification = resolveRequestErrorNotification(
+          error,
+          null,
+          (key, replacements, fallback) => translator.t(key, replacements, fallback),
+        )
+
+        if (notification) showToast(notification)
+      },
+    }),
+  }
+}
+
+function starterKitContext(options: StarterKitPageOptions): AlfakitContextValue {
+  if (typeof window === 'undefined') return createStarterKitContext(options)
+
+  browserContext ??= createStarterKitContext(options)
+
+  return browserContext
+}
+
+/**
+ * The Inertia layout around every Alfakit page in starter kit mode, inside the host layout:
+ * Alfakit's context, modals, toasts and the reading direction. It stays mounted while the
+ * user moves between Alfakit pages.
+ */
+export function AlfakitStarterKitRoot({
+  options,
+  children,
+}: {
+  options?: StarterKitPageOptions
+  children?: ReactNode
+}) {
+  const [context] = useState(() => starterKitContext(options ?? {}))
+  const props = usePage<AlfakitPageProps>().props
+  const panel = props.alfakit
+
+  // Endpoints and error notifications follow the open page.
+  if (panel) {
+    context.actions.setEndpoints({
+      action: panel.endpoints.action ?? '',
+      modal: panel.endpoints.modal ?? '',
+    })
+  }
+
+  useEffect(() => {
+    syncStarterKitPage(props)
+  }, [props])
+
+  useEffect(() => {
+    installStarterKitRuntime(
+      (notification) => showToast(notification),
+      (key, replacements, fallback) => context.translator.t(key, replacements, fallback),
+    )
+    setToasterId(STARTER_KIT_TOASTER_ID)
+
+    return () => {
+      // A host page is open: its errors and toasts are the host's again.
+      syncStarterKitPage(null)
+      setToasterId(undefined)
+    }
+  }, [context])
+
+  return (
+    <AlfakitProvider value={context}>
+      <AlfakitRoot toasterId={STARTER_KIT_TOASTER_ID}>{children}</AlfakitRoot>
+    </AlfakitProvider>
+  )
+}
+
+/**
+ * The page component for `Alfakit/Page` in a starter kit app: the host's
+ * `resources/js/pages/Alfakit/Page.tsx` (written by `alfakit:install --starter-kit`) exports it,
+ * so Inertia's page resolution, the root view's page preload and SSR all find it like any
+ * other host page.
+ *
+ * ```tsx
+ * import { createStarterKitPage } from '@alfakit/react'
+ * import AppLayout from '@/layouts/app-layout'
+ *
+ * export default createStarterKitPage({ layout: AppLayout })
+ * ```
+ */
+export function createStarterKitPage(options: StarterKitPageOptions = {}) {
+  // Panel pages draw named icons: fetch `lucide-react/dynamic` with the page.
+  preloadIcons()
+  // `'js:name'` chart option callbacks, Chart.js plugins and rich editor extensions.
+  configureCharts(options)
+  registerRichEditorExtensions(options.richEditorExtensions ?? {})
+
+  function AlfakitStarterKitPage() {
+    return <AlfakitPage />
+  }
+
+  // A layout callback: the host layout (with the page's breadcrumbs), then Alfakit's root.
+  AlfakitStarterKitPage.layout = (props: Record<string, unknown>) => [
+    ...(options.layout
+      ? [[options.layout, { breadcrumbs: starterKitBreadcrumbsFromProps(props) }] as const]
+      : []),
+    [AlfakitStarterKitRoot, { options }] as const,
+  ]
+
+  return AlfakitStarterKitPage
+}

package/src/starter-kit/widgets-loaded.tsx

@@ -0,0 +1,217 @@
+import {
+  ActionRunner,
+  ComponentRegistry,
+  Translator,
+  initials,
+  isAlfakitPage,
+  loadStarterKitPanel,
+  loadedStarterKitPanel,
+  openRequestedStarterKitSearch,
+  starterKitWidgetsPage,
+  starterKitWidgetsPanel,
+  tenantNameText,
+  type PanelSchema,
+  type StarterKitWidgets,
+} from '@alfakit/core'
+import { router, usePage } from '@inertiajs/react'
+import { ChevronsUpDownIcon, PlusIcon } from 'lucide-react'
+import { Direction } from 'radix-ui'
+import { useEffect, useMemo, useState, type ReactNode } from 'react'
+import { NotificationsMenu } from '../components/notifications/notifications-menu'
+import { RealtimeNotifications } from '../components/notifications/realtime-notifications'
+import { GlobalSearch } from '../components/panel/global-search'
+import { TenantName } from '../components/panel/nav-label'
+import { TenantMenu } from '../components/panel/tenant-menu'
+import { Avatar, AvatarFallback, AvatarImage } from '../components/ui/avatar'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../components/ui/dropdown-menu'
+import { TooltipProvider } from '../components/ui/tooltip'
+import {
+  AlfakitProvider,
+  StandaloneProvider,
+  useT,
+  type AlfakitContextValue,
+  type AnyComponent,
+} from '../context'
+import { Icon } from '../lib/icons'
+import {
+  NotificationsTrigger,
+  SearchTrigger,
+  TenantSwitcherTrigger,
+  type WidgetProps,
+} from './widgets-triggers'
+
+/**
+ * The loaded header components of starter kit mode: the panel's own search palette,
+ * notifications menu and tenant menu, rendered outside Alfakit pages with the panel data
+ * from `widgets.endpoint`. This module only loads in the browser.
+ */
+
+// One context for the browser session: its own translator (the panel's strings), an empty
+// registry (only `panel:icon` overrides are looked up here) and an idle action runner.
+let widgetsContext: AlfakitContextValue | null = null
+
+function useWidgetsContext(panel: PanelSchema): AlfakitContextValue {
+  widgetsContext ??= {
+    registry: new ComponentRegistry<AnyComponent>(),
+    pages: {},
+    translator: new Translator(),
+    actions: new ActionRunner({ endpoints: { action: '', modal: '' } }),
+  }
+
+  widgetsContext.translator.setTranslations(panel.translations ?? {})
+  widgetsContext.translator.setLocale(panel.localization?.tag ?? 'en')
+
+  return widgetsContext
+}
+
+/** The panel the components render with, once its data has loaded (null until then). */
+function useWidgetsPanel(source: StarterKitWidgets): PanelSchema | null {
+  const endpoint = source.widgets.endpoint
+  const [loaded, setLoaded] = useState(() => loadedStarterKitPanel(endpoint))
+  const base = loadedStarterKitPanel(endpoint) ?? loaded
+
+  useEffect(() => {
+    let active = true
+
+    // Another endpoint (a tenant switch) loads its own panel data.
+    void loadStarterKitPanel(endpoint).then(
+      (panel) => active && setLoaded(panel),
+      () => {},
+    )
+
+    return () => {
+      active = false
+    }
+  }, [endpoint])
+
+  const { navigation, widgets } = source
+
+  return useMemo(
+    () => (base ? starterKitWidgetsPanel(base, { navigation, widgets }) : null),
+    [base, navigation, widgets],
+  )
+}
+
+function WidgetShell({ panel, children }: { panel: PanelSchema; children: ReactNode }) {
+  const context = useWidgetsContext(panel)
+  const page = useMemo(() => starterKitWidgetsPage(), [])
+
+  return (
+    <AlfakitProvider value={context}>
+      <StandaloneProvider value={{ panel, page }}>
+        <Direction.Provider dir={panel.localization?.direction ?? 'ltr'}>
+          <TooltipProvider delayDuration={0}>{children}</TooltipProvider>
+        </Direction.Provider>
+      </StandaloneProvider>
+    </AlfakitProvider>
+  )
+}
+
+/** The panel's command palette and global search. */
+export function LoadedSearch({ source }: WidgetProps) {
+  const panel = useWidgetsPanel(source)
+
+  // A click or the key bindings before the palette loaded open it now (after its own
+  // effects registered the shortcut).
+  useEffect(() => {
+    if (panel) openRequestedStarterKitSearch()
+  }, [panel])
+
+  if (!panel) return <SearchTrigger source={source} />
+
+  return (
+    <WidgetShell panel={panel}>
+      <GlobalSearch />
+    </WidgetShell>
+  )
+}
+
+/** The notifications bell, with realtime notifications on the host's own pages. */
+export function LoadedNotifications({ source }: WidgetProps) {
+  const panel = useWidgetsPanel(source)
+  // Alfakit pages subscribe to realtime notifications themselves.
+  const alfakitPage = isAlfakitPage(usePage().props)
+
+  if (!panel) return <NotificationsTrigger source={source} />
+
+  return (
+    <WidgetShell panel={panel}>
+      <NotificationsMenu />
+      {!alfakitPage && <RealtimeNotifications />}
+    </WidgetShell>
+  )
+}
+
+/** The panel's tenant menu inside a tenant, a menu to choose one elsewhere. */
+export function LoadedTenantSwitcher({ source }: WidgetProps) {
+  const panel = useWidgetsPanel(source)
+
+  if (!panel) return <TenantSwitcherTrigger source={source} />
+
+  return (
+    <WidgetShell panel={panel}>
+      {panel.tenancy?.current ? <TenantMenu variant="topbar" /> : <TenantChooser panel={panel} />}
+    </WidgetShell>
+  )
+}
+
+/** The user's tenants on a page outside the panel (no current tenant). */
+function TenantChooser({ panel }: { panel: PanelSchema }) {
+  const t = useT()
+  const tenancy = panel.tenancy
+
+  if (!tenancy || (tenancy.tenants.length === 0 && !tenancy.registrationUrl)) return null
+
+  const label = t('starter_kit.choose_tenant', {}, 'Choose a tenant')
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          data-slot="tenant-menu"
+          className="hover:bg-accent data-[state=open]:bg-accent inline-flex h-9 max-w-60 shrink-0 items-center gap-2 rounded-md px-2 text-sm font-medium"
+        >
+          <span className="sr-only lg:not-sr-only lg:truncate">{label}</span>
+          <Icon
+            name="alfakit::panels.tenant-menu.toggle-button"
+            fallback={ChevronsUpDownIcon}
+            className="text-muted-foreground size-4 shrink-0"
+          />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="min-w-56 rounded-lg" side="bottom" align="end" sideOffset={4}>
+        {tenancy.tenants.length > 0 && (
+          <DropdownMenuLabel className="text-muted-foreground text-xs">{label}</DropdownMenuLabel>
+        )}
+        {tenancy.tenants.map((tenant) => (
+          <DropdownMenuItem key={String(tenant.id)} onSelect={() => router.visit(tenant.url)}>
+            <Avatar className="size-6 rounded-sm">
+              {tenant.avatar && <AvatarImage src={tenant.avatar} alt="" />}
+              <AvatarFallback className="rounded-sm text-[10px]">
+                {initials(tenantNameText(tenant))}
+              </AvatarFallback>
+            </Avatar>
+            <TenantName tenant={tenant} className="flex-1 truncate" />
+          </DropdownMenuItem>
+        ))}
+        {tenancy.registrationUrl && (
+          <>
+            {tenancy.tenants.length > 0 && <DropdownMenuSeparator />}
+            <DropdownMenuItem onSelect={() => router.visit(tenancy.registrationUrl!)}>
+              <Icon name="alfakit::panels.tenant-menu.registration-button" fallback={PlusIcon} />
+              {t('tenancy.register', {}, 'New')}
+            </DropdownMenuItem>
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

package/src/starter-kit/widgets-triggers.tsx

@@ -0,0 +1,103 @@
+import {
+  formatKeyBinding,
+  initials,
+  registerStarterKitSearchShortcut,
+  requestStarterKitSearch,
+  tenantNameText,
+  type StarterKitWidgets,
+} from '@alfakit/core'
+import { BellIcon, ChevronsUpDownIcon, SearchIcon } from 'lucide-react'
+import { useEffect } from 'react'
+import { useHydrated } from '../hooks/use-hydrated'
+
+/**
+ * What the starter kit header components show until their code and the panel data have
+ * loaded: the same look as the loaded triggers, from the shared prop alone.
+ */
+export interface WidgetProps {
+  source: StarterKitWidgets
+}
+
+const triggerClasses =
+  'border-input bg-background hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 inline-flex h-8 shrink-0 items-center rounded-md border text-sm shadow-xs outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50'
+
+/** The search field until the palette has loaded: the same look, and it remembers a click. */
+export function SearchTrigger({ source, onLoad }: WidgetProps & { onLoad?: () => void }) {
+  const hydrated = useHydrated()
+  const search = source.widgets.search
+  const keys = JSON.stringify(search?.keyBindings ?? ['mod+k'])
+  const placeholder = search?.placeholder ?? ''
+  // `onLoad` is a stable function (it starts loading the palette's code).
+  useEffect(
+    () =>
+      registerStarterKitSearchShortcut(JSON.parse(keys) as string[], placeholder, () => onLoad?.()),
+    [keys, placeholder, onLoad],
+  )
+
+  const binding = search?.keyBindings[0]
+
+  return (
+    <button
+      type="button"
+      className={`${triggerClasses} text-muted-foreground size-8 justify-center gap-2 px-0 font-normal sm:w-56 sm:justify-start sm:px-2.5`}
+      onPointerEnter={() => onLoad?.()}
+      onClick={() => {
+        requestStarterKitSearch()
+        onLoad?.()
+      }}
+    >
+      <SearchIcon className="size-4" aria-hidden="true" />
+      <span className="sr-only sm:not-sr-only sm:flex-1 sm:text-start">{placeholder}</span>
+      {hydrated && binding && (
+        <kbd className="bg-muted hidden rounded px-1 font-mono text-[10px] sm:inline">
+          {formatKeyBinding(binding)}
+        </kbd>
+      )}
+    </button>
+  )
+}
+
+/** The bell and its unread count until the menu has loaded. */
+export function NotificationsTrigger({ source }: WidgetProps) {
+  const notifications = source.widgets.notifications
+  const count = notifications?.unreadCount ?? 0
+
+  return (
+    <button
+      type="button"
+      data-slot="notifications-trigger"
+      aria-label={notifications?.label}
+      className="hover:bg-accent hover:text-accent-foreground relative inline-flex size-9 items-center justify-center rounded-md"
+    >
+      <BellIcon className="size-4" aria-hidden="true" />
+      {count > 0 && (
+        <span className="bg-primary text-primary-foreground absolute -end-0.5 -top-0.5 flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[10px] font-medium">
+          {count > 99 ? '99+' : count}
+        </span>
+      )}
+    </button>
+  )
+}
+
+/** The current tenant (or an empty avatar) until the switcher has loaded: a placeholder. */
+export function TenantSwitcherTrigger({ source }: WidgetProps) {
+  const current = source.widgets.tenancy?.current
+
+  return (
+    <button
+      type="button"
+      data-slot="tenant-menu"
+      aria-hidden="true"
+      tabIndex={-1}
+      className="hover:bg-accent inline-flex h-9 max-w-60 shrink-0 items-center gap-2 rounded-md px-2 text-sm font-medium"
+    >
+      <span className="bg-muted flex size-6 items-center justify-center rounded-md text-[10px]">
+        {current ? initials(tenantNameText(current)) : ''}
+      </span>
+      {current && (
+        <span className="sr-only min-w-0 truncate lg:not-sr-only">{tenantNameText(current)}</span>
+      )}
+      <ChevronsUpDownIcon className="text-muted-foreground size-4 shrink-0" aria-hidden="true" />
+    </button>
+  )
+}

package/src/starter-kit/widgets.tsx

@@ -0,0 +1,103 @@
+import { starterKitWidgets, type StarterKitWidgets } from '@alfakit/core'
+import { usePage } from '@inertiajs/react'
+import { lazyComponent } from '../lib/lazy'
+import {
+  NotificationsTrigger,
+  SearchTrigger,
+  TenantSwitcherTrigger,
+  type WidgetProps,
+} from './widgets-triggers'
+
+/**
+ * Drop-in header components of starter kit mode (`Panel::starterKit()`): AlfaKit's search,
+ * notifications bell and tenant switcher in the host's own header, on every page of the
+ * application. They read the shared `alfakitNavigation` prop, render a lightweight trigger
+ * straight away, and load their code and the panel data the first time they render
+ * (in the browser, never during SSR).
+ *
+ * ```tsx
+ * import { AlfakitNotifications, AlfakitSearch } from '@alfakit/react'
+ *
+ * <AlfakitSearch />
+ * <AlfakitNotifications />
+ * ```
+ */
+export interface AlfakitHeaderWidgetProps {
+  /** The `starterKit()` panel to use (the first one by default). */
+  panel?: string
+}
+
+const load = () => import('./widgets-loaded')
+
+const LoadedSearch = lazyComponent<WidgetProps>(
+  () => load().then((module) => module.LoadedSearch),
+  (props) => <SearchTrigger {...props} onLoad={preloadSearch} />,
+)
+
+function preloadSearch() {
+  void LoadedSearch.preload()
+}
+
+const LoadedNotifications = lazyComponent<WidgetProps>(
+  () => load().then((module) => module.LoadedNotifications),
+  (props) => <NotificationsTrigger {...props} />,
+)
+
+const LoadedTenantSwitcher = lazyComponent<WidgetProps>(
+  () => load().then((module) => module.LoadedTenantSwitcher),
+  (props) => <TenantSwitcherTrigger {...props} />,
+)
+
+function useWidgets(panelId: string | undefined): StarterKitWidgets | null {
+  return starterKitWidgets(usePage().props, panelId)
+}
+
+/**
+ * AlfaKit's command palette and global search: the search field opens it, and so do the
+ * panel's key bindings (⌘K / Ctrl+K by default), registered once for the page. Renders
+ * nothing for guests or without global search and a command palette.
+ */
+export function AlfakitSearch({ panel }: AlfakitHeaderWidgetProps = {}) {
+  const source = useWidgets(panel)
+
+  if (!source?.widgets.search) return null
+
+  return (
+    <span data-slot="starter-kit-search" className="inline-flex">
+      <LoadedSearch source={source} />
+    </span>
+  )
+}
+
+/**
+ * The bell with the user's database notifications (`databaseNotifications()`), polling and
+ * realtime updates as in the panel. Renders nothing for guests or without database
+ * notifications.
+ */
+export function AlfakitNotifications({ panel }: AlfakitHeaderWidgetProps = {}) {
+  const source = useWidgets(panel)
+
+  if (!source?.widgets.notifications) return null
+
+  return (
+    <span data-slot="starter-kit-notifications" className="inline-flex">
+      <LoadedNotifications source={source} />
+    </span>
+  )
+}
+
+/**
+ * The tenant switcher of a tenancy panel: the current tenant inside the panel, or a menu
+ * to choose one on the host's own pages. Renders nothing for guests or other panels.
+ */
+export function AlfakitTenantSwitcher({ panel }: AlfakitHeaderWidgetProps = {}) {
+  const source = useWidgets(panel)
+
+  if (!source?.widgets.tenancy) return null
+
+  return (
+    <span data-slot="starter-kit-tenant-switcher" className="inline-flex">
+      <LoadedTenantSwitcher source={source} />
+    </span>
+  )
+}