@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/panel/keyboard-shortcuts.tsx

@@ -0,0 +1,134 @@
+import type { CommandSchema } from '@alfakit/core'
+import {
+  COMMANDS_COMPONENT,
+  commandShortcutId,
+  focusTableSearch,
+  SHORTCUT_IDS,
+  shortcuts,
+} from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import { useEffect, useState } from 'react'
+import { useActionRunner, usePageSchema, usePanel, useT } from '../../context'
+import type { ShortcutsOverlay as Overlay } from './shortcuts-overlay'
+
+type OverlayComponent = typeof Overlay
+
+let loadedOverlay: OverlayComponent | undefined
+let loadingOverlay: Promise<OverlayComponent> | undefined
+
+/** The `?` overlay's code: loaded the first time it opens; the shortcuts register eagerly. */
+function loadOverlay(): Promise<OverlayComponent> {
+  loadingOverlay ??= import('./shortcuts-overlay').then(
+    (module) => (loadedOverlay = module.ShortcutsOverlay),
+    (error: unknown) => {
+      loadingOverlay = undefined
+      throw error
+    },
+  )
+
+  return loadingOverlay
+}
+
+/**
+ * Keyboard shortcuts of the panel: `/` (focus the table search), `g d` (dashboard), `?`
+ * (the overlay) and the panel commands' `shortcut()`, with the user's customised keys
+ * (`alfakit.keyboardShortcuts`). The overlay lists everything available on the page,
+ * grouped, and lets users change keys (stored on the server).
+ */
+export function KeyboardShortcuts() {
+  const t = useT()
+  const panel = usePanel()
+  const page = usePageSchema()
+  const runner = useActionRunner()
+  const config = panel.keyboardShortcuts
+  const [open, setOpen] = useState(false)
+  // Undefined on the server and during hydration (nothing loads there), so the markup matches.
+  const [ShortcutsOverlay, setOverlay] = useState<OverlayComponent | undefined>(() => loadedOverlay)
+  const overrides = JSON.stringify(config ? (config.overrides ?? {}) : {})
+  const token = page?.token ?? ''
+  const commands = panel.commandPalette?.commands
+  const home = panel.url
+  // Strings, so the effect below doesn't re-run on every render (`t` is a new function each time).
+  const overlayLabel = t('shortcuts.show_overlay', {}, 'Show keyboard shortcuts')
+  const searchLabel = t('shortcuts.focus_search', {}, 'Search the table')
+  const dashboardLabel = t('shortcuts.go_dashboard', {}, 'Go to the dashboard')
+
+  useEffect(() => {
+    shortcuts.setEnabled(config !== false)
+    shortcuts.setOverrides(JSON.parse(overrides) as Record<string, string[]>)
+  }, [config, overrides])
+
+  useEffect(() => {
+    if (!config) return
+
+    const disposers = [
+      shortcuts.register({
+        id: SHORTCUT_IDS.overlay,
+        keys: ['?'],
+        label: overlayLabel,
+        group: 'general',
+        handler: () => setOpen(true),
+      }),
+      // Declined (`false`) on pages without a table search, so `/` keeps its default.
+      shortcuts.register({
+        id: SHORTCUT_IDS.search,
+        keys: ['/'],
+        label: searchLabel,
+        group: 'general',
+        handler: () => focusTableSearch(),
+      }),
+      ...(home
+        ? [
+            shortcuts.register({
+              id: SHORTCUT_IDS.dashboard,
+              keys: ['g d'],
+              label: dashboardLabel,
+              group: 'navigation',
+              handler: () => router.visit(home),
+            }),
+          ]
+        : []),
+      ...(commands ?? [])
+        .filter((command: CommandSchema) => command.keyBindings?.length && !command.disabled)
+        .map((command: CommandSchema) =>
+          shortcuts.register({
+            id: commandShortcutId(command.name),
+            keys: command.keyBindings ?? [],
+            label: command.label ?? command.name,
+            group: command.url ? 'navigation' : 'commands',
+            handler: () => void runner.trigger(command, { token, component: COMMANDS_COMPONENT }),
+          }),
+        ),
+    ]
+
+    return () => disposers.forEach((dispose) => dispose())
+  }, [config, commands, home, runner, token, overlayLabel, searchLabel, dashboardLabel])
+
+  // `?` (or the palette's "Keyboard shortcuts") before the code has arrived keeps `open`
+  // set; the overlay mounts open once it has loaded.
+  useEffect(() => {
+    if (!open || ShortcutsOverlay) return
+
+    let active = true
+
+    loadOverlay().then(
+      (component) => active && setOverlay(() => component),
+      () => active && setOpen(false),
+    )
+
+    return () => {
+      active = false
+    }
+  }, [open, ShortcutsOverlay])
+
+  if (!config || !ShortcutsOverlay) return null
+
+  return (
+    <ShortcutsOverlay
+      open={open}
+      onOpenChange={setOpen}
+      customizable={Boolean(config.customizable && panel.endpoints.shortcuts)}
+      endpoint={panel.endpoints.shortcuts}
+    />
+  )
+}

package/src/components/panel/lazy-placeholder.tsx

@@ -0,0 +1,39 @@
+import { useT } from '../../context'
+import { cn } from '../../lib/utils'
+import { Skeleton } from '../ui/skeleton'
+
+/**
+ * Stands in for a lazy widget or relation manager until the `alfakitLazy` deferred prop
+ * brings its schema. `table` mimics a table (relation managers, table widgets).
+ */
+export function LazyPlaceholder({
+  variant = 'widget',
+  className,
+}: {
+  variant?: 'widget' | 'table'
+  className?: string
+}) {
+  const t = useT()
+
+  return (
+    <div
+      data-slot="lazy-placeholder"
+      data-variant={variant}
+      role="status"
+      aria-busy="true"
+      className={cn('bg-card flex flex-col gap-3 rounded-xl border p-6', className)}
+    >
+      <span className="sr-only">{t('loading', {}, 'Loading…')}</span>
+      <Skeleton className="h-5 w-1/3" />
+      {variant === 'table' ? (
+        <>
+          <Skeleton className="h-9 w-full" />
+          <Skeleton className="h-9 w-full" />
+          <Skeleton className="h-9 w-full" />
+        </>
+      ) : (
+        <Skeleton className="h-20 w-full" />
+      )}
+    </div>
+  )
+}

package/src/components/panel/locale-switcher.tsx

@@ -0,0 +1,144 @@
+import { collapsesLanguageSwitcher, showsLanguageSwitcher, switchLocale } from '@alfakit/core'
+import { LanguagesIcon } from 'lucide-react'
+import { createElement } from 'react'
+import { useLocalization, useOptionalRegistry, usePanel, useT } from '../../context'
+import { Button } from '../ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu'
+
+function useSwitch() {
+  const panel = usePanel()
+
+  return (code: string) => {
+    if (panel.endpoints.locale && code !== panel.localization.code) {
+      switchLocale(panel.endpoints.locale, code)
+    }
+  }
+}
+
+function LocaleOptions() {
+  const localization = useLocalization()
+  const change = useSwitch()
+
+  return (
+    <DropdownMenuRadioGroup value={localization.code} onValueChange={change}>
+      {localization.locales.map((locale) => (
+        <DropdownMenuRadioItem
+          key={locale.code}
+          value={locale.code}
+          lang={locale.tag}
+          data-current={locale.code === localization.code ? 'true' : undefined}
+          className="data-[current=true]:font-medium"
+        >
+          <span lang={locale.tag} dir={locale.direction}>
+            {locale.label}
+          </span>
+        </DropdownMenuRadioItem>
+      ))}
+    </DropdownMenuRadioGroup>
+  )
+}
+
+/**
+ * Stand-alone language menu: a languages button listing each language in its own name
+ * (auth pages, top bar). Renders nothing without a switcher.
+ */
+export function LocaleSwitcher() {
+  const t = useT()
+  const localization = useLocalization()
+
+  if (!showsLanguageSwitcher(localization, 'auth')) {
+    return null
+  }
+
+  return (
+    <div data-slot="language-switcher" className="flex">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            aria-label={t('change_language', {}, 'Change language')}
+            title={t('change_language', {}, 'Change language')}
+          >
+            <LanguagesIcon />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="min-w-40">
+          <LocaleOptions />
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  )
+}
+
+/** Whether the panel has a user menu that can hold the language entry on phones. */
+function useHasUserMenu(): boolean {
+  const panel = usePanel()
+
+  return Boolean(panel?.user && panel.userMenu)
+}
+
+/**
+ * The top bars' language button (`languageSwitcher('topbar' | 'both')`): the registered
+ * `panel:language-switcher` component or the built-in menu. Below `sm` it moves into the
+ * user menu when there is one (`collapsesLanguageSwitcher()`).
+ */
+export function TopbarLocaleSwitcher() {
+  const localization = usePanel()?.localization
+  const registry = useOptionalRegistry()
+  const collapses = collapsesLanguageSwitcher(localization, useHasUserMenu())
+
+  if (!showsLanguageSwitcher(localization, 'topbar')) {
+    return null
+  }
+
+  const button = createElement(registry?.resolve('panel:language-switcher') ?? LocaleSwitcher)
+
+  return collapses ? (
+    <div className="hidden sm:contents" data-slot="topbar-language">
+      {button}
+    </div>
+  ) : (
+    button
+  )
+}
+
+/**
+ * "Language" submenu for the user menu (`languageSwitcher('user-menu' | 'both')`, and
+ * below `sm` for `'topbar'`).
+ */
+export function LocaleSubMenu() {
+  const t = useT()
+  const localization = useLocalization()
+  const hasUserMenu = useHasUserMenu()
+  const inMenu = showsLanguageSwitcher(localization, 'user-menu')
+  // `languageSwitcher('topbar')`: the top bar's button is hidden on phones, so it's here.
+  const onPhones = !inMenu && collapsesLanguageSwitcher(localization, hasUserMenu)
+
+  if (!inMenu && !onPhones) {
+    return null
+  }
+
+  return (
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger className={onPhones ? 'sm:hidden' : undefined}>
+        <LanguagesIcon />
+        <span>{t('language', {}, 'Language')}</span>
+        <span className="text-muted-foreground ms-auto ps-2 text-xs">{localization.label}</span>
+      </DropdownMenuSubTrigger>
+      <DropdownMenuSubContent className="min-w-40">
+        <LocaleOptions />
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+  )
+}

package/src/components/panel/menu-item.tsx

@@ -0,0 +1,89 @@
+import type { MenuItemSchema } from '@alfakit/core'
+import { groupMenuItems, menuActionContext } from '@alfakit/core'
+import { Link, router } from '@inertiajs/react'
+import { Fragment } from 'react'
+import { useActionRunner, usePageSchema } from '../../context'
+import { colorClass, textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { NewTabHint } from '../../lib/new-tab-hint'
+import { cn } from '../../lib/utils'
+import { DropdownMenuItem, DropdownMenuSeparator } from '../ui/dropdown-menu'
+
+export type MenuName = 'userMenu' | 'tenantMenu'
+
+/**
+ * An entry in the user or tenant menu: colour, icon, new tab and POST links, or an
+ * `Action` (server logic, modals) run through the action endpoint as a menu action.
+ */
+export function MenuItemEntry({
+  item,
+  menu = 'userMenu',
+}: {
+  item: MenuItemSchema
+  menu?: MenuName
+}) {
+  const runner = useActionRunner()
+  const page = usePageSchema()
+  // Unknown values get no class (custom names get theirs).
+  const color = item.color ? colorClass(textColorClasses, item.color, item.color) : undefined
+
+  const content = (
+    <>
+      {item.icon && <Icon name={item.icon} className={cn(color)} />}
+      <span className={cn(color)}>{item.label}</span>
+    </>
+  )
+
+  if (item.action) {
+    const action = item.action
+
+    return (
+      <DropdownMenuItem
+        disabled={action.disabled}
+        title={action.tooltip}
+        onSelect={() => void runner.trigger(action, menuActionContext(page?.token ?? '', menu))}
+      >
+        {content}
+      </DropdownMenuItem>
+    )
+  }
+
+  if (item.method === 'post') {
+    return (
+      <DropdownMenuItem onSelect={() => item.url && router.post(item.url)}>
+        {content}
+      </DropdownMenuItem>
+    )
+  }
+
+  return (
+    <DropdownMenuItem asChild>
+      {item.openInNewTab ? (
+        <a href={item.url} target="_blank" rel="noopener noreferrer" className="w-full">
+          {content}
+          <NewTabHint />
+        </a>
+      ) : (
+        <Link href={item.url ?? '#'} className="w-full">
+          {content}
+        </Link>
+      )}
+    </DropdownMenuItem>
+  )
+}
+
+/** Menu entries with a separator between their groups. */
+export function MenuItemEntries({ items, menu }: { items: MenuItemSchema[]; menu?: MenuName }) {
+  return (
+    <>
+      {groupMenuItems(items).map((group, groupIndex) => (
+        <Fragment key={groupIndex}>
+          {groupIndex > 0 && <DropdownMenuSeparator />}
+          {group.map((item, index) => (
+            <MenuItemEntry key={index} item={item} menu={menu} />
+          ))}
+        </Fragment>
+      ))}
+    </>
+  )
+}

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

@@ -0,0 +1,34 @@
+import type { NavigationItemSchema } from '@alfakit/core'
+
+/**
+ * A navigation item's label: text, or the sanitised HTML of an `Htmlable` label
+ * (`labelHtml`, sanitised on the server like other HTML in the schema).
+ */
+export function NavLabel({
+  item,
+  className,
+}: {
+  item: Pick<NavigationItemSchema, 'label' | 'labelHtml'>
+  className?: string
+}) {
+  return item.labelHtml ? (
+    <span className={className} dangerouslySetInnerHTML={{ __html: item.label }} />
+  ) : (
+    <span className={className}>{item.label}</span>
+  )
+}
+
+/** A tenant's name: text, or the sanitised HTML of an `Htmlable` name (`nameHtml`). */
+export function TenantName({
+  tenant,
+  className,
+}: {
+  tenant: { name: string; nameHtml?: boolean }
+  className?: string
+}) {
+  return tenant.nameHtml ? (
+    <span className={className} dangerouslySetInnerHTML={{ __html: tenant.name }} />
+  ) : (
+    <span className={className}>{tenant.name}</span>
+  )
+}

package/src/components/panel/pwa.tsx

@@ -0,0 +1,118 @@
+import {
+  applyPwaUpdate,
+  canInstallPwa,
+  promptPwaInstall,
+  pwaStore,
+  startPwa,
+  subscribeToPush,
+  unsubscribeFromPush,
+  type Translator,
+} from '@alfakit/core'
+import { BellIcon, BellOffIcon, DownloadIcon } from 'lucide-react'
+import { useEffect } from 'react'
+import { toast } from 'sonner'
+import { usePanel, useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { Icon } from '../../lib/icons'
+import { DropdownMenuItem } from '../ui/dropdown-menu'
+
+const UPDATE_TOAST_ID = 'alfakit-pwa-update'
+
+/** Show the browser's install prompt, or the "Add to Home Screen" hint on iOS Safari. */
+export async function installPwa(t: Translator['t']): Promise<void> {
+  if ((await promptPwaInstall()) === 'ios') {
+    toast.info(
+      t(
+        'pwa.ios_hint',
+        {},
+        'To install this app, tap the Share button and then “Add to Home Screen”.',
+      ),
+      { duration: 10000 },
+    )
+  }
+}
+
+/**
+ * `Panel::pwa()`: registers the service worker and offers "Reload" when a new version
+ * waits. Renders nothing; does nothing without `pwa` or during a server render.
+ */
+export function PwaManager() {
+  const panel = usePanel()
+  const t = useT()
+  const pwa = panel?.pwa
+  const { updateAvailable } = useStore(pwaStore)
+
+  useEffect(() => {
+    startPwa(pwa)
+  }, [pwa])
+
+  useEffect(() => {
+    if (!updateAvailable) return
+
+    toast(t('pwa.update_available', {}, 'A new version is available'), {
+      id: UPDATE_TOAST_ID,
+      duration: Infinity,
+      action: { label: t('pwa.reload', {}, 'Reload'), onClick: () => applyPwaUpdate() },
+    })
+  }, [updateAvailable, t])
+
+  return null
+}
+
+/** User menu entries: "Install app" and turning Web Push on or off for this browser. */
+export function PwaMenuItems() {
+  const panel = usePanel()
+  const t = useT()
+  const state = useStore(pwaStore)
+
+  if (!panel?.pwa) return null
+
+  const push = panel.pwa.push && state.push !== 'unsupported'
+
+  const togglePush = async () => {
+    const outcome =
+      state.push === 'subscribed' ? await unsubscribeFromPush() : await subscribeToPush()
+
+    if (outcome === 'subscribed') {
+      toast.success(t('pwa.notifications.enabled', {}, 'Notifications are on for this device'))
+    } else if (outcome === 'unsubscribed') {
+      toast.success(t('pwa.notifications.disabled', {}, 'Notifications are off for this device'))
+    } else if (outcome === 'denied') {
+      toast.error(
+        t('pwa.notifications.blocked', {}, 'Notifications are blocked in your browser settings'),
+      )
+    } else {
+      toast.error(t('pwa.notifications.failed', {}, 'Couldn’t change notifications. Try again.'))
+    }
+  }
+
+  return (
+    <>
+      {canInstallPwa(state) && (
+        <DropdownMenuItem data-slot="pwa-install" onSelect={() => void installPwa(t)}>
+          <Icon name="alfakit::panels.user-menu.install-app-item" fallback={DownloadIcon} />{' '}
+          {t('pwa.install', {}, 'Install app')}
+        </DropdownMenuItem>
+      )}
+      {push && (
+        <DropdownMenuItem
+          data-slot="pwa-push"
+          disabled={state.pushBusy || state.push === 'denied'}
+          onSelect={() => void togglePush()}
+        >
+          {state.push === 'subscribed' ? (
+            <>
+              <Icon name="alfakit::panels.user-menu.push-off-item" fallback={BellOffIcon} />{' '}
+              {t('pwa.notifications.disable', {}, 'Turn off notifications')}
+            </>
+          ) : (
+            <>
+              <Icon name="alfakit::panels.user-menu.push-on-item" fallback={BellIcon} />{' '}
+              {t('pwa.notifications.enable', {}, 'Turn on notifications')}
+            </>
+          )}
+        </DropdownMenuItem>
+      )}
+    </>
+  )
+}

package/src/components/panel/schema-contract-guard.tsx

@@ -0,0 +1,50 @@
+import {
+  checkSchemaContract,
+  reportSchemaContractMismatch,
+  type PanelSchema,
+  type SchemaContractCheck,
+} from '@alfakit/core'
+import { useEffect, type ReactNode } from 'react'
+import { useT } from '../../context'
+
+/**
+ * Renders its children only when the page's schema contract (`alfakit.schemaContract`) has
+ * the major version this frontend understands; otherwise a translated message replaces the
+ * page and the mismatch is logged once, naming both versions.
+ */
+export function SchemaContractGuard({
+  panel,
+  children,
+}: {
+  panel: PanelSchema | undefined
+  children: ReactNode
+}) {
+  const check = checkSchemaContract(panel?.schemaContract)
+
+  useEffect(() => {
+    reportSchemaContractMismatch(check)
+  }, [check.compatible, check.server, check.client]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  if (check.compatible) {
+    return <>{children}</>
+  }
+
+  return <SchemaContractMismatch check={check} />
+}
+
+export function SchemaContractMismatch({ check }: { check: SchemaContractCheck }) {
+  const t = useT()
+
+  return (
+    <div
+      role="alert"
+      data-slot="schema-contract-mismatch"
+      className="bg-background text-foreground mx-auto flex min-h-svh w-full max-w-lg flex-col items-center justify-center gap-2 p-6 text-center"
+    >
+      <h1 className="text-lg font-semibold">{t('schema_contract.title')}</h1>
+      <p className="text-muted-foreground text-sm">
+        {t('schema_contract.body', { server: check.server ?? '?', client: check.client })}
+      </p>
+    </div>
+  )
+}

package/src/components/panel/shortcut-keys.tsx

@@ -0,0 +1,34 @@
+import { shortcutSteps } from '@alfakit/core'
+import { useT } from '../../context'
+import { useHydrated } from '../../hooks/use-hydrated'
+import { cn } from '../../lib/utils'
+
+/**
+ * A key binding as `<kbd>` keys (`G` then `D`, `⌘K`). The keys depend on the visitor's
+ * platform (⌘ or Ctrl), so they render after hydration.
+ */
+export function ShortcutKeys({ binding, className }: { binding: string; className?: string }) {
+  const t = useT()
+  const hydrated = useHydrated()
+
+  if (!hydrated) return null
+
+  const steps = shortcutSteps(binding)
+
+  return (
+    <span data-slot="shortcut-keys" className={cn('inline-flex items-center gap-1', className)}>
+      {steps.map((step, index) => (
+        <span key={index} className="inline-flex items-center gap-1">
+          {index > 0 && (
+            <span className="text-muted-foreground text-[10px]">
+              {t('shortcuts.then', {}, 'then')}
+            </span>
+          )}
+          <kbd className="bg-muted text-muted-foreground rounded border px-1.5 font-mono text-[10px] leading-5">
+            {step}
+          </kbd>
+        </span>
+      ))}
+    </span>
+  )
+}