@alfakit/react 0.1.9 → 0.1.10

package/src/components/fields/rich-editor-extensions.tsx

@@ -11,6 +11,7 @@ import {
   customBlockNodeConfig,
   EditorSuggestions,
   fieldActionContext,
+  fixedContainingBlockOffset,
   groupCustomBlocks,
   groupTriggerButton,
   isCustomBlockResult,
@@ -358,6 +359,9 @@ export function ToolbarGroupButton({
   onRun: (name: string) => void
 }) {
   const buttons = group.buttons.filter((name) => commands[name])
+  // After a pick, typing goes on in the editor (the command focused it); the menu would
+  // otherwise return focus to its trigger. Closing without a pick (Escape) still does.
+  const picked = useRef(false)
 
   if (buttons.length === 0) return null
 
@@ -385,6 +389,13 @@ export function ToolbarGroupButton({
         align="start"
         aria-label={group.label}
         className={cn(!group.textual && 'flex min-w-0 flex-row gap-0.5')}
+        onCloseAutoFocus={(event) => {
+          if (!picked.current) return
+
+          picked.current = false
+          event.preventDefault()
+          editor.commands.focus()
+        }}
       >
         {buttons.map((name) => {
           const label = commandLabel(name, commands, translate)
@@ -396,7 +407,10 @@ export function ToolbarGroupButton({
               aria-label={group.textual ? undefined : label}
               title={label}
               className={cn(pressed && 'bg-accent text-accent-foreground')}
-              onSelect={() => onRun(name)}
+              onSelect={() => {
+                picked.current = true
+                onRun(name)
+              }}
             >
               {icons(name)}
               {group.textual && <span>{label}</span>}
@@ -436,7 +450,15 @@ export function SuggestionPopup({
       data-slot="rich-editor-suggestions"
       className="bg-popover text-popover-foreground fixed z-50 min-w-48 overflow-hidden rounded-md border p-1 shadow-md"
       // Runtime coordinates cannot be Tailwind classes.
-      style={state.coords ? { left: state.coords.left, top: state.coords.bottom + 4 } : undefined}
+      // Inside a modal the dialog's transform is the containing block of this fixed list.
+      style={
+        state.coords
+          ? {
+              left: state.coords.left - fixedContainingBlockOffset(editor.view.dom).x,
+              top: state.coords.bottom + 4 - fixedContainingBlockOffset(editor.view.dom).y,
+            }
+          : undefined
+      }
     >
       {state.loading && state.items.length === 0 ? (
         <div className="text-muted-foreground px-2 py-1.5 text-sm">

package/src/components/file-manager/file-manager.tsx

@@ -1389,7 +1389,8 @@ function Dialogs({
         open={dialog?.type === 'createFolder' || dialog?.type === 'rename'}
         onOpenChange={(open) => !open && close()}
       >
-        <DialogContent data-slot="file-manager-dialog">
+        {/* The title and the labelled field say it all: no description. */}
+        <DialogContent data-slot="file-manager-dialog" aria-describedby={undefined}>
           <form
             className="flex flex-col gap-4"
             onSubmit={(event) => {
@@ -1763,6 +1764,7 @@ function Preview({
         <DialogContent
           className="flex max-h-[90vh] flex-col sm:max-w-4xl"
           data-slot="file-manager-preview"
+          aria-describedby={undefined}
           onKeyDown={onKeyDown}
         >
           <DialogHeader>

package/src/components/layout/elements.tsx

@@ -25,6 +25,8 @@ import { Icon } from '../../lib/icons'
 import { cn } from '../../lib/utils'
 import { usePageActionContext } from '../actions/action-context'
 import { ActionList } from '../actions/action-list'
+import { useOptionalFormStore } from '../form/form-context'
+import { useFieldActionContext } from '../schema/field-actions'
 import { RenderComponent } from '../schema/schema-renderer'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
 import { MixedContent } from './mixed-content'
@@ -67,7 +69,12 @@ const CALLOUT_ICON_SIZES: Record<string, string> = {
 }
 
 export function CalloutComponent({ component }: { component: CalloutSchema }) {
-  const context = usePageActionContext()
+  // Inside a form the actions run as field actions of this component, so `$get` / `$set`
+  // reach the form (like a section's header actions).
+  const form = useOptionalFormStore()
+  const pageContext = usePageActionContext()
+  const fieldContext = useFieldActionContext(component)
+  const context = form ? fieldContext : pageContext
   const tone = component.color ?? component.status
   // `iconColor()`, or the status colour once `color(null)` removed the background.
   const iconColor = component.iconColor ?? (component.color ? undefined : component.status)
@@ -113,19 +120,30 @@ export function CalloutComponent({ component }: { component: CalloutSchema }) {
             className={cn('mt-2', actionsAlignmentClass(component.footerActionsAlignment))}
           />
         )}
-        <MixedContent items={component.footer} name="callout-footer" className="mt-2" />
+        <MixedContent
+          items={component.footer}
+          name="callout-footer"
+          className="mt-2"
+          context={context}
+        />
       </div>
       <MixedContent
         items={component.controls}
         name="callout-controls"
         className="-me-1 -mt-1 shrink-0 gap-1"
+        context={context}
       />
     </div>
   )
 }
 
 export function EmptyStateComponent({ component }: { component: EmptyStateComponentSchema }) {
-  const context = usePageActionContext()
+  // Inside a form the actions run as field actions of this component, so `$get` / `$set`
+  // reach the form (like a section's header actions).
+  const form = useOptionalFormStore()
+  const pageContext = usePageActionContext()
+  const fieldContext = useFieldActionContext(component)
+  const context = form ? fieldContext : pageContext
 
   return (
     <div
@@ -158,7 +176,12 @@ export function EmptyStateComponent({ component }: { component: EmptyStateCompon
       {component.actions && component.actions.length > 0 && (
         <ActionList actions={component.actions} context={context} className="mt-2 justify-center" />
       )}
-      <MixedContent items={component.footer} name="empty-state-footer" className="justify-center" />
+      <MixedContent
+        items={component.footer}
+        name="empty-state-footer"
+        className="justify-center"
+        context={context}
+      />
     </div>
   )
 }

package/src/components/layout/mixed-content.tsx

@@ -1,4 +1,4 @@
-import type { AnyActionSchema, ContentSlotItem } from '@alfakit/core'
+import type { ActionContext, AnyActionSchema, ContentSlotItem } from '@alfakit/core'
 import type { ReactNode } from 'react'
 import { cn } from '../../lib/utils'
 import { usePageActionContext } from '../actions/action-context'
@@ -7,19 +7,23 @@ import { RenderComponent } from '../schema/schema-renderer'
 
 /**
  * Actions and components placed in a layout component's fixed spot (a section's
- * `afterHeader()`, a callout's `controls()`). Actions run in the page's action context,
- * like section header actions.
+ * `afterHeader()`, a callout's `controls()`). Actions run in the owner's action context
+ * (`context`: inside a form, the owner's field context, so `$get` / `$set` work), else the
+ * page's.
  */
 export function MixedContent({
   items,
   name,
   className,
+  context: ownerContext,
 }: {
   items: ContentSlotItem[] | undefined
   name: string
   className?: string
+  context?: ActionContext
 }) {
-  const context = usePageActionContext()
+  const pageContext = usePageActionContext()
+  const context = ownerContext ?? pageContext
 
   if (!items?.length) {
     return null

package/src/components/layout/section.tsx

@@ -86,7 +86,7 @@ export function SectionComponent({ component }: { component: SectionSchema }) {
       {component.headerActions && component.headerActions.length > 0 && (
         <ActionList actions={component.headerActions} context={context} size="sm" />
       )}
-      <MixedContent items={component.afterHeader} name="section-after-header" />
+      <MixedContent items={component.afterHeader} name="section-after-header" context={context} />
       {component.collapsible && (
         <CollapsibleTrigger asChild>
           <Button
@@ -123,7 +123,7 @@ export function SectionComponent({ component }: { component: SectionSchema }) {
             className={actionsAlignmentClass(component.footerActionsAlignment) || undefined}
           />
         )}
-        <MixedContent items={component.footer} name="section-footer-content" />
+        <MixedContent items={component.footer} name="section-footer-content" context={context} />
       </div>
     ) : null
 

package/src/components/notifications/notifications-menu.tsx

@@ -3,9 +3,13 @@ import {
   notificationTintStyles,
   onDatabaseNotificationsSent,
   onOpenDatabaseNotifications,
+  pwaStore,
+  startPwa,
+  togglePushNotifications,
 } from '@alfakit/core'
-import { BellIcon, CheckCheckIcon, Trash2Icon } from 'lucide-react'
+import { BellIcon, BellOffIcon, BellRingIcon, CheckCheckIcon, Trash2Icon } from 'lucide-react'
 import { useEffect, useMemo, useState } from 'react'
+import { toast } from 'sonner'
 import { useDirection, useFormatter, usePanel, useT } from '../../context'
 import { useStore } from '../../hooks/use-store'
 import { cssColor, textColorClasses } from '../../lib/colors'
@@ -86,6 +90,29 @@ export function NotificationsMenu({ variant = 'topbar' }: NotificationsMenuProps
     [center],
   )
 
+  // `pwa(push: true)` in a starter kit: the app's user menu has no AlfaKit entries, so Web
+  // Push is turned on or off from the bell's menu.
+  const pwa = useStore(pwaStore)
+  const kitPush = Boolean(panel.starterKit && panel.pwa?.push)
+  const pushToggle = kitPush && pwa.push !== 'unsupported'
+
+  useEffect(() => {
+    if (kitPush) startPwa(panel.pwa)
+  }, [kitPush, panel.pwa])
+
+  const togglePush = async () => {
+    const { message } = await togglePushNotifications()
+    const text = t(message.key, {}, message.fallback)
+
+    if (message.error) toast.error(text)
+    else toast.success(text)
+  }
+
+  const pushLabel =
+    pwa.push === 'subscribed'
+      ? t('pwa.notifications.disable', {}, 'Turn off notifications')
+      : t('pwa.notifications.enable', {}, 'Turn on notifications')
+
   if (!config || !center) {
     return null
   }
@@ -145,6 +172,20 @@ export function NotificationsMenu({ variant = 'topbar' }: NotificationsMenuProps
         <div className="flex items-center justify-between border-b px-3 py-2">
           <span className="text-sm font-semibold">{t('notifications', {}, 'Notifications')}</span>
           <div className="flex items-center gap-1">
+            {pushToggle && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-sm"
+                data-slot="pwa-push"
+                disabled={pwa.pushBusy || pwa.push === 'denied'}
+                title={pushLabel}
+                aria-label={pushLabel}
+                onClick={() => void togglePush()}
+              >
+                {pwa.push === 'subscribed' ? <BellOffIcon /> : <BellRingIcon />}
+              </Button>
+            )}
             {state.unreadCount > 0 && (
               <Button
                 type="button"

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

@@ -1,6 +1,6 @@
 import type { ShortcutListGroup, ShortcutListItem } from '@alfakit/core'
 import {
-  bindingFromEvent,
+  ShortcutRecorder,
   flattenActionGroup,
   saveShortcutOverrides,
   shortcutOverlayGroups,
@@ -52,50 +52,55 @@ export function ShortcutsOverlay({
     }
   }
 
-  // While recording, the next key press is the new binding (Escape cancels). Listening in the
-  // capture phase keeps the key from closing the dialog or running another shortcut.
+  // While recording, the keys pressed are the new binding: one key (with modifiers) or a
+  // sequence ("g o"), finished a second after the last key (Escape cancels). Listening in
+  // the capture phase keeps the keys from closing the dialog or running another shortcut.
   useEffect(() => {
     if (!recording) return
 
     shortcuts.setPaused(true)
 
-    const listener = (event: KeyboardEvent) => {
-      event.preventDefault()
-      event.stopPropagation()
-
-      if (event.key === 'Escape') {
+    const recorder = new ShortcutRecorder({
+      onDone: (binding) => {
         setRecording(null)
-        setMessage(t('shortcuts.cancelled', {}, 'Change cancelled.'))
 
-        return
-      }
+        const conflict = shortcuts.conflict([binding], recording)
 
-      const binding = bindingFromEvent(event)
+        if (conflict) {
+          setMessage(
+            t(
+              'shortcuts.conflict',
+              { label: conflict.label },
+              `Already used by “${conflict.label}”.`,
+            ),
+          )
 
-      if (!binding) return
+          return
+        }
 
-      const conflict = shortcuts.conflict([binding], recording)
+        void save(recording, [binding])
+      },
+    })
 
-      setRecording(null)
+    const listener = (event: KeyboardEvent) => {
+      event.preventDefault()
+      event.stopPropagation()
 
-      if (conflict) {
-        setMessage(
-          t(
-            'shortcuts.conflict',
-            { label: conflict.label },
-            `Already used by “${conflict.label}”.`,
-          ),
-        )
+      if (event.key === 'Escape') {
+        recorder.cancel()
+        setRecording(null)
+        setMessage(t('shortcuts.cancelled', {}, 'Change cancelled.'))
 
         return
       }
 
-      void save(recording, [binding])
+      recorder.press(event)
     }
 
     window.addEventListener('keydown', listener, true)
 
     return () => {
+      recorder.cancel()
       window.removeEventListener('keydown', listener, true)
       shortcuts.setPaused(false)
     }

package/src/components/table/column-manager.tsx

@@ -114,13 +114,13 @@ export function ColumnManager({
     }
   }
 
-  const save = async (order: string[]): Promise<boolean> => {
+  const save = async (order: string[], options: { reload?: boolean } = {}): Promise<boolean> => {
     if (!panel.endpoints.tableColumns) return false
 
     setSaving(true)
 
     try {
-      await saveColumnOrder(panel.endpoints.tableColumns, token, component, order)
+      await saveColumnOrder(panel.endpoints.tableColumns, token, component, order, options)
 
       return true
     } catch (error) {
@@ -203,7 +203,8 @@ export function ColumnManager({
     setAnnouncement('')
     setOpen(false)
 
-    if (orderDraft && orderChanged) await save(orderDraft)
+    // The visibility visit renders the new order too: no second reload racing it.
+    if (orderDraft && orderChanged) await save(orderDraft, { reload: !columns })
 
     if (columns) visitTable(table.identifier, { columns }, ['page'])
   }
@@ -212,7 +213,8 @@ export function ColumnManager({
   const reset = async () => {
     if (reorderable) {
       setOrderDraft(null)
-      await save([])
+      // The visibility visit below renders the defined order too.
+      await save([], { reload: !toggleable })
     }
 
     if (toggleable) {

package/src/components/table/spreadsheet.tsx

@@ -539,14 +539,25 @@ export function Spreadsheet({ table, token, component, onClose }: SpreadsheetPro
           <DialogHeader>
             <DialogTitle>{t('table.spreadsheet.paste_title', {}, 'Paste cells')}</DialogTitle>
             <DialogDescription>
-              {choice(
-                'table.spreadsheet.paste_summary',
-                preview?.plan.changes.length ?? 0,
-                {},
-                ':count cell will change|:count cells will change',
+              {/* One line per count: translations can't join two sentences. */}
+              <span className="block">
+                {choice(
+                  'table.spreadsheet.paste_summary',
+                  preview?.plan.changes.length ?? 0,
+                  {},
+                  ':count cell will change|:count cells will change',
+                )}
+              </span>
+              {(preview?.plan.skipped ?? 0) > 0 && (
+                <span className="block" data-slot="spreadsheet-paste-skipped">
+                  {choice(
+                    'table.spreadsheet.paste_skipped',
+                    preview?.plan.skipped ?? 0,
+                    {},
+                    ':count read-only cell is skipped|:count read-only cells are skipped',
+                  )}
+                </span>
               )}
-              {(preview?.plan.skipped ?? 0) > 0 &&
-                ` ${choice('table.spreadsheet.paste_skipped', preview?.plan.skipped ?? 0, {}, ':count read-only cell is skipped|:count read-only cells are skipped')}`}
             </DialogDescription>
           </DialogHeader>
           <div data-slot="spreadsheet-paste" className="flex flex-col gap-3">

package/src/components/translation-manager/translation-manager.tsx

@@ -330,7 +330,7 @@ function TranslationManagerView({ schema }: { schema: TranslationManagerSchema }
                 <tr>
                   <th
                     scope="col"
-                    className="bg-muted sticky start-0 z-10 min-w-56 border-b px-3 py-2 text-start font-medium"
+                    className="bg-card sticky start-0 z-10 min-w-56 border-b [background-image:linear-gradient(var(--muted),var(--muted))] px-3 py-2 text-start font-medium"
                   >
                     {t('translation-manager.key', {}, 'Key')}
                   </th>

package/src/components/widgets/stats-overview.tsx

@@ -71,7 +71,9 @@ function StatCard({ stat }: { stat: StatSchema }) {
     >
       <div className="flex items-start justify-between gap-3">
         <div className="flex flex-col gap-1">
-          <span className="text-muted-foreground text-sm font-medium">{stat.label}</span>
+          <span className="text-muted-foreground text-sm font-medium">
+            <bdi>{stat.label}</bdi>
+          </span>
           {(stat.value === null || stat.value === '') && stat.placeholder ? (
             <span
               className="text-muted-foreground text-2xl font-semibold tracking-tight"
@@ -86,7 +88,7 @@ function StatCard({ stat }: { stat: StatSchema }) {
                 stat.color && textColorClasses[stat.color],
               )}
             >
-              {stat.value}
+              <bdi>{stat.value}</bdi>
             </span>
           )}
           {stat.description && (
@@ -101,7 +103,8 @@ function StatCard({ stat }: { stat: StatSchema }) {
               {stat.descriptionIcon && stat.descriptionIconPosition !== 'after' && (
                 <Icon name={stat.descriptionIcon} className="size-3.5" />
               )}
-              {stat.description}
+              {/* Mixed-direction text (a Latin "-3% this month" in Arabic) keeps its order. */}
+              <bdi>{stat.description}</bdi>
               {stat.descriptionIcon && stat.descriptionIconPosition === 'after' && (
                 <Icon name={stat.descriptionIcon} className="size-3.5" />
               )}

package/src/pages/page.tsx

@@ -11,6 +11,7 @@ import type {
 } from '@alfakit/core'
 import {
   applyBodyAttributes,
+  customPageProps,
   hasRelationManagerTabs,
   isLazyPlaceholder,
   openDefaultAction,
@@ -102,9 +103,12 @@ export function AlfakitPage() {
     return (
       <PageActionProvider value={{ token: page.token, component: 'page' }}>
         <Head title={title} />
-        <PageShell page={page}>
-          <Custom {...page.view.props} page={page} />
-        </PageShell>
+        {/* The component brings its own PageShell (as in panel mode, where it is the Inertia
+            page itself) and takes the live props, so `reloadProps()` reaches it. */}
+        <Custom
+          {...customPageProps(page.view.props, props as Record<string, unknown>)}
+          page={page}
+        />
       </PageActionProvider>
     )
   }

package/src/standalone/alfakit-component.tsx

@@ -8,7 +8,7 @@ import {
 } from '@alfakit/core'
 import { usePage } from '@inertiajs/react'
 import { Direction } from 'radix-ui'
-import { useEffect, useMemo, useState, type ReactNode } from 'react'
+import { useEffect, useLayoutEffect, useMemo, useState, type ReactNode } from 'react'
 import { PageActionProvider } from '../components/actions/action-context'
 import { ActionList } from '../components/actions/action-list'
 import { ActionModals } from '../components/actions/action-modals'
@@ -55,6 +55,9 @@ export interface AlfakitComponentProps {
  * <AlfakitComponent component={orders} className="max-w-4xl" />
  * ```
  */
+// `useLayoutEffect` warns during a server render, where nothing registers anyway.
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect
+
 export function AlfakitComponent({
   component,
   components,
@@ -138,7 +141,9 @@ export function AlfakitComponent({
   // Partial reloads (sorting, paging, inline edits) request this component's own prop.
   const propName = findStandalonePropName(props, component)
 
-  useEffect(() => registerStandaloneProp(propName ?? null), [propName])
+  // A layout effect runs before the children's effects: a `deferLoading()` table's first
+  // reload must already ask for this component's prop, not the panel `page` prop.
+  useIsomorphicLayoutEffect(() => registerStandaloneProp(propName ?? null), [propName])
 
   useEffect(() => {
     void state.loadLazy(component)

package/src/standalone/runtime.ts

@@ -3,6 +3,7 @@ import {
   ComponentRegistry,
   FlashNotificationTracker,
   Translator,
+  installPrefetchInvalidation,
   reloadOnExpiredPage,
   resolveRequestErrorNotification,
   type NotificationSchema,
@@ -27,6 +28,8 @@ export function ensureStandaloneRuntime(): void {
 
   browserReady = true
   reloadOnExpiredPage()
+  // Pages restored by Back after a change are reloaded; shared with a surrounding panel.
+  installPrefetchInvalidation()
 }
 
 /**

package/src/starter-kit/navigation.ts

@@ -1,8 +1,10 @@
 import {
   starterKitNavigation,
   toStarterKitNavGroups,
+  toStarterKitUserMenuItems,
   type StarterKitNavGroup,
   type StarterKitNavigationSchema,
+  type StarterKitUserMenuItem,
 } from '@alfakit/core'
 import { usePage } from '@inertiajs/react'
 import { useMemo } from 'react'
@@ -12,6 +14,11 @@ export interface AlfakitNavigation {
   navigation: StarterKitNavigationSchema | null
   /** Its groups as plain items (`title`, `href`, `icon`, `isActive`, `badge`, `children`). */
   groups: StarterKitNavGroup[]
+  /**
+   * The panel's user menu links (`userMenuItems()`, Billing's entry…) for the kit's user
+   * menu: `<AlfakitUserMenuItems />` renders them with the app's dropdown items.
+   */
+  userMenuItems: StarterKitUserMenuItem[]
 }
 
 /**
@@ -28,7 +35,11 @@ export function useAlfakitNavigation(panelId?: string): AlfakitNavigation {
   const navigation = starterKitNavigation(props, panelId)
 
   return useMemo(
-    () => ({ navigation, groups: toStarterKitNavGroups(navigation?.groups) }),
+    () => ({
+      navigation,
+      groups: toStarterKitNavGroups(navigation?.groups),
+      userMenuItems: toStarterKitUserMenuItems(navigation?.userMenu),
+    }),
     [navigation],
   )
 }

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

@@ -185,8 +185,9 @@ export function AlfakitStarterKitRoot({
         <AlfakitRoot toasterId={STARTER_KIT_TOASTER_ID}>
           {children}
           {/* The debug panel's button lives in AlfaKit's top bar, which a starter kit doesn't
-              render: float it in the corner instead (nothing without `alfakitDebug`). */}
-          <div data-slot="starter-kit-debug-panel" className="fixed end-16 bottom-4 z-40">
+              render: float it in the corner instead (nothing without `alfakitDebug`). The corner is the
+              document's right: the kit's sidebar stays on the left in a right-to-left panel language. */}
+          <div data-slot="starter-kit-debug-panel" className="fixed right-16 bottom-16 z-40">
             <DebugPanelSlot />
           </div>
         </AlfakitRoot>

package/src/styles.css

@@ -289,7 +289,8 @@
 }
 /* Rich editor mentions, merge tags and custom blocks (RichEditor extensions) */
 .alfakit-prose :where(.alfakit-mention):not(:where(.alfakit-not-prose *)) {
-  @apply bg-primary/10 text-primary rounded px-1 font-medium;
+  /* Full-contrast text on the tint (WCAG AA); the ring marks it as a mention. */
+  @apply bg-primary/10 text-foreground ring-primary/30 rounded px-1 font-medium ring-1;
 }
 .alfakit-prose :where(.alfakit-merge-tag):not(:where(.alfakit-not-prose *)) {
   @apply bg-muted text-muted-foreground rounded px-1 font-mono text-xs;