@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/panel/topbar.tsx

@@ -0,0 +1,81 @@
+import type { BreadcrumbSchema } from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import { Fragment } from 'react'
+import { usePanel, useT } from '../../context'
+import { NotificationsMenu } from '../notifications/notifications-menu'
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '../ui/breadcrumb'
+import { Separator } from '../ui/separator'
+import { SidebarTrigger } from '../ui/sidebar'
+import { DebugPanelSlot } from './debug-panel-slot'
+import { GlobalSearch } from './global-search'
+import { TopbarLocaleSwitcher } from './locale-switcher'
+import { Slot } from './slot'
+import { ThemeToggle } from './theme-toggle'
+import { UserMenu } from './user-menu'
+
+export function Breadcrumbs({ items }: { items: BreadcrumbSchema[] }) {
+  const t = useT()
+
+  if (items.length === 0) return null
+
+  return (
+    <Breadcrumb className="min-w-0" aria-label={t('breadcrumbs', {}, 'Breadcrumb')}>
+      <BreadcrumbList className="flex-nowrap">
+        {items.map((item, index) => {
+          const last = index === items.length - 1
+
+          return (
+            <Fragment key={`${item.label}-${index}`}>
+              <BreadcrumbItem className={!last ? 'hidden md:inline-flex' : 'min-w-0'}>
+                {last || !item.url ? (
+                  <BreadcrumbPage className="block truncate">{item.label}</BreadcrumbPage>
+                ) : (
+                  <BreadcrumbLink asChild>
+                    <Link href={item.url}>{item.label}</Link>
+                  </BreadcrumbLink>
+                )}
+              </BreadcrumbItem>
+              {!last && <BreadcrumbSeparator className={'hidden md:block'} />}
+            </Fragment>
+          )
+        })}
+      </BreadcrumbList>
+    </Breadcrumb>
+  )
+}
+
+export function Topbar({ breadcrumbs }: { breadcrumbs?: BreadcrumbSchema[] }) {
+  const panel = usePanel()
+
+  return (
+    <header
+      data-slot="topbar"
+      className="bg-background/80 supports-[backdrop-filter]:bg-background/60 sticky top-0 z-20 flex h-14 min-w-0 shrink-0 items-center gap-2 border-b px-4 backdrop-blur"
+    >
+      <SidebarTrigger className="-ms-1" />
+      <Separator orientation="vertical" className="me-2 h-4" />
+      {panel.breadcrumbs && breadcrumbs && <Breadcrumbs items={breadcrumbs} />}
+      <Slot name="topbar.start" />
+      <div className="ms-auto flex items-center gap-1">
+        <Slot name="topbar.end" />
+        {/* `globalSearch(position: Sidebar)` moves the field to the sidebar header. */}
+        {(panel.topNavigation || panel.globalSearch?.position !== 'sidebar') && <GlobalSearch />}
+        {panel.databaseNotifications?.position !== 'sidebar' && <NotificationsMenu />}
+        <TopbarLocaleSwitcher />
+        <ThemeToggle />
+        <DebugPanelSlot />
+        {/* `userMenu(position: Topbar)` moves the menu out of the sidebar footer. */}
+        {(panel.topNavigation || panel.userMenu?.position === 'topbar') && (
+          <UserMenu variant="topbar" />
+        )}
+      </div>
+    </header>
+  )
+}

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

@@ -0,0 +1,166 @@
+import { initials } from '@alfakit/core'
+import { Link, router } from '@inertiajs/react'
+import { ChevronsUpDownIcon, LogInIcon, LogOutIcon, UserIcon } from 'lucide-react'
+import { useDirection, usePanel, useT } from '../../context'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Avatar, AvatarFallback, AvatarImage } from '../ui/avatar'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu'
+import { SidebarMenuButton } from '../ui/sidebar'
+import { LocaleSubMenu } from './locale-switcher'
+import { MenuItemEntries, MenuItemEntry } from './menu-item'
+import { PwaMenuItems } from './pwa'
+import { Slot } from './slot'
+
+export function UserAvatar({ className }: { className?: string }) {
+  const { user } = usePanel()
+
+  if (!user) return null
+
+  return (
+    <Avatar className={cn('size-8 rounded-lg', className)}>
+      {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
+      <AvatarFallback className="rounded-lg" aria-hidden="true">
+        {initials(user.name)}
+      </AvatarFallback>
+    </Avatar>
+  )
+}
+
+/**
+ * Shown instead of the user menu to guests (panels with `guestAccess()`) when the panel
+ * has a login page.
+ */
+export function SignInLink({ variant = 'sidebar' }: { variant?: 'sidebar' | 'topbar' }) {
+  const t = useT()
+  const { user, auth } = usePanel()
+
+  if (user || !auth?.login) {
+    return null
+  }
+
+  return (
+    <Link
+      href={auth.login}
+      data-slot="sign-in-link"
+      className={cn(
+        'focus-visible:ring-ring/50 flex items-center gap-2 rounded-md text-sm font-medium outline-none focus-visible:ring-[3px] [&_svg]:size-4 [&_svg]:shrink-0',
+        variant === 'sidebar'
+          ? 'hover:bg-sidebar-accent hover:text-sidebar-accent-foreground w-full p-2'
+          : 'hover:bg-accent hover:text-accent-foreground h-8 px-3',
+      )}
+    >
+      <LogInIcon className="rtl:rotate-180" aria-hidden="true" />
+      <span>{t('sign_in', {}, 'Sign in')}</span>
+    </Link>
+  )
+}
+
+export function UserMenu({ variant = 'sidebar' }: { variant?: 'sidebar' | 'topbar' }) {
+  const t = useT()
+  const panel = usePanel()
+  const direction = useDirection()
+  const { user, userMenu } = panel
+
+  if (!user) {
+    return <SignInLink variant={variant} />
+  }
+
+  if (!userMenu) {
+    return null
+  }
+
+  const trigger =
+    variant === 'sidebar' ? (
+      <SidebarMenuButton
+        size="lg"
+        className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
+      >
+        <UserAvatar />
+        <div className="grid flex-1 text-start text-sm leading-tight">
+          <span className="truncate font-medium">{user.name}</span>
+          {user.email && (
+            <span className="text-muted-foreground truncate text-xs">{user.email}</span>
+          )}
+        </div>
+        <Icon
+          name="alfakit::panels.user-menu.toggle-button"
+          fallback={ChevronsUpDownIcon}
+          className="ms-auto size-4"
+        />
+      </SidebarMenuButton>
+    ) : (
+      <button
+        type="button"
+        className="focus-visible:ring-ring/50 rounded-full outline-none focus-visible:ring-[3px]"
+        aria-label={user.name}
+      >
+        <UserAvatar className="rounded-full" />
+      </button>
+    )
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
+      <DropdownMenuContent
+        className="min-w-56 rounded-lg"
+        side={variant === 'sidebar' ? (direction === 'rtl' ? 'left' : 'right') : 'bottom'}
+        align="end"
+        sideOffset={4}
+      >
+        <DropdownMenuLabel className="p-0 font-normal">
+          <div className="flex items-center gap-2 px-1 py-1.5 text-start text-sm">
+            <UserAvatar />
+            <div className="grid flex-1 leading-tight">
+              <span className="truncate font-medium">{user.name}</span>
+              {user.email && (
+                <span className="text-muted-foreground truncate text-xs">{user.email}</span>
+              )}
+            </div>
+          </div>
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuGroup>
+          <Slot name="user-menu.before" />
+          <Slot name="user-menu.profile.before" />
+          {userMenu.profile ? (
+            <MenuItemEntry item={userMenu.profile} />
+          ) : (
+            userMenu.profileUrl && (
+              <DropdownMenuItem asChild>
+                <Link href={userMenu.profileUrl} className="w-full">
+                  <Icon name="alfakit::panels.user-menu.profile-item" fallback={UserIcon} />{' '}
+                  {t('profile', {}, 'Profile')}
+                </Link>
+              </DropdownMenuItem>
+            )
+          )}
+          <Slot name="user-menu.profile.after" />
+          <MenuItemEntries items={userMenu.items} />
+          <LocaleSubMenu />
+          <PwaMenuItems />
+          <Slot name="user-menu.after" />
+        </DropdownMenuGroup>
+        {userMenu.logout !== false && <DropdownMenuSeparator />}
+        {userMenu.logout ? (
+          <MenuItemEntry item={userMenu.logout} />
+        ) : (
+          userMenu.logout !== false && (
+            <DropdownMenuItem onSelect={() => router.post(userMenu.logoutUrl)}>
+              <Icon name="alfakit::panels.user-menu.logout-button" fallback={LogOutIcon} />{' '}
+              {t('logout', {}, 'Sign out')}
+            </DropdownMenuItem>
+          )
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

package/src/components/realtime/conflict-banner.tsx

@@ -0,0 +1,208 @@
+import {
+  ConflictMonitor,
+  PresenceRoom,
+  conflictMessage,
+  findPageFormBlock,
+  type PageSchema,
+} from '@alfakit/core'
+import { RefreshCwIcon, TriangleAlertIcon, XIcon } from 'lucide-react'
+import { useEffect, useMemo, useState } from 'react'
+import { useFormatter, usePanel, useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { Button } from '../ui/button'
+
+/**
+ * Edit pages (`detectConflicts()`): a non-blocking banner when somebody else saved the
+ * record ("Dana saved changes 10 seconds ago", over `Panel::realtime()`) or the server
+ * refused a save, with review (the changed fields against your unsaved values), reload
+ * and keep mine. Replace it with `components: { 'page:conflict-banner': … }`.
+ */
+export function ConflictBanner({ page }: { page: PageSchema }) {
+  const panel = usePanel()
+  const t = useT()
+  const formatter = useFormatter()
+  const version = page.conflicts?.version ?? ''
+  const channel = page.presence?.channel ?? null
+  const [reviewing, setReviewing] = useState(false)
+  const [, setTick] = useState(0)
+
+  const monitor = useMemo(
+    () =>
+      new ConflictMonitor({
+        version,
+        token: page.token,
+        endpoint: panel.endpoints.conflicts,
+        channel,
+        original: (findPageFormBlock(page)?.state as Record<string, unknown> | undefined) ?? {},
+        self: panel.user?.id ?? null,
+        resolveName: (id) =>
+          channel ? (PresenceRoom.find(channel)?.memberName(id) ?? null) : null,
+      }),
+    // A new version (after saving or reloading) starts over.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [version, channel],
+  )
+
+  useEffect(() => monitor.start(), [monitor])
+  useEffect(() => monitor.setToken(page.token), [monitor, page.token])
+
+  const state = useStore(monitor.store)
+  const conflict = state.conflict
+
+  // "10 seconds ago" keeps counting.
+  useEffect(() => {
+    if (!conflict) return
+
+    const timer = setInterval(() => setTick((tick) => tick + 1), 15_000)
+
+    return () => clearInterval(timer)
+  }, [conflict])
+
+  if (!conflict) return null
+
+  const message = conflictMessage(conflict)
+  const text = t(
+    message.key,
+    { name: conflict.name ?? '', time: formatter.relative(conflict.at) },
+    message.fallback,
+  )
+  const deleted = conflict.event === 'deleted'
+  const empty = t('realtime.conflict.empty', {}, 'Empty')
+
+  const close = (run: () => unknown) => {
+    setReviewing(false)
+    void run()
+  }
+
+  const review = () => {
+    setReviewing((open) => !open)
+
+    if (!reviewing && state.fields === null) void monitor.review()
+  }
+
+  return (
+    <div
+      data-slot="conflict-banner"
+      data-source={conflict.source}
+      role="status"
+      aria-live="polite"
+      className="flex flex-col gap-3 rounded-lg border border-amber-300 bg-amber-50 px-4 py-3 text-sm text-amber-950 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-100"
+    >
+      <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
+        <TriangleAlertIcon className="size-4 shrink-0" aria-hidden="true" />
+        <p className="min-w-0 flex-1 font-medium">{text}</p>
+        <div className="flex flex-wrap items-center gap-2">
+          {!deleted && (
+            <Button
+              type="button"
+              size="sm"
+              variant="outline"
+              aria-expanded={reviewing}
+              aria-controls="alfakit-conflict-review"
+              onClick={review}
+            >
+              {t('realtime.conflict.review', {}, 'Review changes')}
+            </Button>
+          )}
+          <Button
+            type="button"
+            size="sm"
+            variant="outline"
+            onClick={() => close(() => monitor.reload())}
+          >
+            <RefreshCwIcon aria-hidden="true" />
+            {t('realtime.conflict.reload', {}, 'Reload')}
+          </Button>
+          {!deleted && (
+            <Button type="button" size="sm" onClick={() => close(() => monitor.keepMine())}>
+              {t('realtime.conflict.keep_mine', {}, 'Keep mine')}
+            </Button>
+          )}
+          <Button
+            type="button"
+            size="icon-sm"
+            variant="ghost"
+            aria-label={t('realtime.conflict.dismiss', {}, 'Dismiss')}
+            onClick={() => close(() => monitor.dismiss())}
+          >
+            <XIcon aria-hidden="true" />
+          </Button>
+        </div>
+      </div>
+      {reviewing && (
+        <div
+          id="alfakit-conflict-review"
+          data-slot="conflict-review"
+          className="flex flex-col gap-2"
+        >
+          {state.loading ? (
+            <p className="text-muted-foreground">
+              {t('realtime.conflict.loading', {}, 'Loading changes…')}
+            </p>
+          ) : state.failed ? (
+            <p>{t('realtime.conflict.failed', {}, 'The changes could not be loaded.')}</p>
+          ) : (state.fields ?? []).length === 0 ? (
+            <p>{t('realtime.conflict.no_changes', {}, 'No field differs from what you loaded.')}</p>
+          ) : (
+            <table className="bg-background/60 text-foreground w-full overflow-hidden rounded-md text-start text-sm">
+              <caption className="sr-only">
+                {t('realtime.conflict.caption', {}, 'Fields changed since you opened the record')}
+              </caption>
+              <thead>
+                <tr className="border-b">
+                  <th scope="col" className="px-3 py-2 text-start font-medium">
+                    {t('realtime.conflict.field', {}, 'Field')}
+                  </th>
+                  <th scope="col" className="px-3 py-2 text-start font-medium">
+                    {t('realtime.conflict.theirs', {}, 'Saved')}
+                  </th>
+                  <th scope="col" className="px-3 py-2 text-start font-medium">
+                    {t('realtime.conflict.mine', {}, 'Yours')}
+                  </th>
+                  <th scope="col" className="px-3 py-2">
+                    <span className="sr-only">{t('realtime.conflict.actions', {}, 'Actions')}</span>
+                  </th>
+                </tr>
+              </thead>
+              <tbody>
+                {(state.fields ?? []).map((field) => (
+                  <tr
+                    key={field.path}
+                    data-conflicting={field.conflicting || undefined}
+                    className="border-b last:border-b-0"
+                  >
+                    <th scope="row" className="px-3 py-2 text-start font-medium">
+                      {field.label}
+                      {field.conflicting && (
+                        <span className="ms-2 rounded bg-amber-200 px-1.5 py-0.5 text-xs font-normal text-amber-950 dark:bg-amber-800 dark:text-amber-50">
+                          {t('realtime.conflict.both_changed', {}, 'Changed by both')}
+                        </span>
+                      )}
+                    </th>
+                    <td className="px-3 py-2 break-words">{field.theirs ?? empty}</td>
+                    <td className="px-3 py-2 break-words">{field.mine ?? empty}</td>
+                    <td className="px-3 py-2 text-end">
+                      <Button
+                        type="button"
+                        size="xs"
+                        variant="outline"
+                        aria-label={t(
+                          'realtime.conflict.use_theirs_label',
+                          { field: field.label },
+                          'Use the saved value of :field',
+                        )}
+                        onClick={() => monitor.useTheirs(field.path)}
+                      >
+                        {t('realtime.conflict.use_theirs', {}, 'Use saved value')}
+                      </Button>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/realtime/index.ts

@@ -0,0 +1,3 @@
+export { ConflictBanner } from './conflict-banner'
+export { LiveRecordsPill, useLiveUpdates } from './live-records-pill'
+export { RecordPresence } from './record-presence'

package/src/components/realtime/live-records-pill.tsx

@@ -0,0 +1,66 @@
+import { LiveUpdates, shownRecordKeys, type LiveUpdatesSchema, type RecordKey } from '@alfakit/core'
+import { ArrowUpIcon } from 'lucide-react'
+import { useEffect, useMemo } from 'react'
+import { useChoice, usePollComponent } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { Button } from '../ui/button'
+
+/**
+ * Follow `live()` updates of a table or widget: refresh it in place when its records
+ * change, polling instead without Echo. Returns the controller (its store counts created
+ * records for `<LiveRecordsPill>`), or null without `live()`.
+ */
+export function useLiveUpdates(
+  live: LiveUpdatesSchema | undefined,
+  target: string,
+  options: { polling?: boolean; records?: ReadonlyArray<{ key?: RecordKey }> | null } = {},
+): LiveUpdates | null {
+  const poll = usePollComponent()
+  const key = live ? JSON.stringify(live) : ''
+  const polling = options.polling
+  const records = options.records
+
+  const controller = useMemo(
+    () => (live ? new LiveUpdates({ live, target, polling, poll }) : null),
+    // `live` is compared by value (`key`): a reload brings a new object with the same settings.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key, target, polling, poll],
+  )
+
+  // Updates of records on other pages don't refresh the table.
+  useEffect(() => {
+    controller?.setShownKeys(records === undefined ? null : shownRecordKeys(records))
+  }, [controller, records])
+
+  useEffect(() => controller?.start(), [controller])
+
+  return controller
+}
+
+/** "3 new records — show": created records the table doesn't show yet. */
+export function LiveRecordsPill({ live }: { live: LiveUpdates }) {
+  const choice = useChoice()
+  const { pending } = useStore(live.store)
+
+  return (
+    <div data-slot="live-records" aria-live="polite" className="flex justify-center">
+      {pending > 0 && (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="rounded-full shadow-sm"
+          onClick={() => void live.showPending()}
+        >
+          <ArrowUpIcon aria-hidden="true" />
+          {choice(
+            'realtime.new_records',
+            pending,
+            {},
+            '{1} :count new record — show|[2,*] :count new records — show',
+          )}
+        </Button>
+      )}
+    </div>
+  )
+}

package/src/components/realtime/record-presence.tsx

@@ -0,0 +1,98 @@
+import {
+  PresenceRoom,
+  presenceInitials,
+  visiblePresenceMembers,
+  type PresenceSchema,
+} from '@alfakit/core'
+import { useEffect, useMemo } from 'react'
+import { useChoice, usePanel, useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { cn } from '../../lib/utils'
+import { Avatar, AvatarFallback, AvatarImage } from '../ui/avatar'
+
+/**
+ * Who else is on this record (`Panel::realtime()`): avatars of the other users on the
+ * record page, with a dot for those editing it. A labelled list with screen-reader text
+ * per user. Replace it with `components: { 'page:presence': … }`.
+ */
+export function RecordPresence({ presence }: { presence: PresenceSchema }) {
+  const panel = usePanel()
+  const t = useT()
+  const choice = useChoice()
+  const self = panel.user?.id ?? null
+
+  const room = useMemo(
+    () => new PresenceRoom({ channel: presence.channel, state: presence.state, self }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [presence.channel, self],
+  )
+
+  useEffect(() => room.start(), [room])
+  useEffect(() => room.setState(presence.state), [room, presence.state])
+
+  const { members } = useStore(room.store)
+
+  if (members.length === 0) return null
+
+  const { shown, overflow } = visiblePresenceMembers(members)
+
+  return (
+    <div data-slot="presence" className="flex items-center">
+      <ul
+        aria-label={t('realtime.presence.label', {}, 'Also on this record')}
+        className="flex items-center -space-x-2 rtl:space-x-reverse"
+      >
+        {shown.map((member) => {
+          const label =
+            member.state === 'editing'
+              ? t('realtime.presence.editing', { name: member.name }, ':name is editing')
+              : t('realtime.presence.viewing', { name: member.name }, ':name is viewing')
+
+          return (
+            <li
+              key={member.id}
+              data-state={member.state}
+              title={label}
+              className="relative inline-flex"
+            >
+              <Avatar
+                className={cn(
+                  'ring-background size-8 ring-2',
+                  member.state === 'editing' && 'ring-primary',
+                )}
+              >
+                {member.avatar && <AvatarImage src={member.avatar} alt="" />}
+                <AvatarFallback aria-hidden="true">{presenceInitials(member.name)}</AvatarFallback>
+              </Avatar>
+              {member.state === 'editing' && (
+                <span
+                  aria-hidden="true"
+                  className="bg-primary ring-background absolute -end-0.5 -bottom-0.5 size-2.5 rounded-full ring-2"
+                />
+              )}
+              <span className="sr-only">{label}</span>
+            </li>
+          )
+        })}
+        {overflow > 0 && (
+          <li className="relative inline-flex">
+            <span
+              aria-hidden="true"
+              className="bg-muted ring-background flex size-8 items-center justify-center rounded-full text-xs font-medium ring-2"
+            >
+              {`+${overflow}`}
+            </span>
+            <span className="sr-only">
+              {choice(
+                'realtime.presence.more',
+                overflow,
+                {},
+                '{1} and :count other person|[2,*] and :count other people',
+              )}
+            </span>
+          </li>
+        )}
+      </ul>
+    </div>
+  )
+}