@alfakit/react 0.1.9 → 0.1.11

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/cells.tsx

@@ -220,7 +220,9 @@ function ImageCell({ column, cell }: CellProps) {
         <img
           key={index}
           src={url}
-          alt={cell.alt ?? ''}
+          // Without `alt()` the first image is named after the column, so a record link that
+          // wraps it has a name (W-V4-20).
+          alt={cell.alt ?? (index === 0 ? (column.label ?? '') : '')}
           style={{
             height: schema.height ?? size,
             width: schema.width ?? (schema.square || schema.circular ? size : undefined),

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/ui/calendar.tsx

@@ -1,6 +1,7 @@
 import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react'
 import type { ComponentProps } from 'react'
 import { DayPicker } from 'react-day-picker'
+import { useT } from '../../context'
 import { cn } from '../../lib/utils'
 import { buttonVariants } from './button'
 
@@ -10,9 +11,16 @@ function Calendar({
   showOutsideDays = true,
   ...props
 }: ComponentProps<typeof DayPicker>) {
+  const t = useT()
+
   return (
     <DayPicker
       showOutsideDays={showOutsideDays}
+      labels={{
+        labelPrevious: () => t('form.previous_month', {}, 'Previous month'),
+        labelNext: () => t('form.next_month', {}, 'Next month'),
+        ...props.labels,
+      }}
       className={cn('p-3', className)}
       classNames={{
         months: 'flex flex-col sm:flex-row gap-2',

package/src/components/widgets/dashboard-customizer.tsx

@@ -24,7 +24,7 @@ import { useEffect, useId, useMemo, type ReactNode } from 'react'
 import { useDirection, useT } from '../../context'
 import { useStore } from '../../hooks/use-store'
 import { cn } from '../../lib/utils'
-import { LazyPlaceholder } from '../panel/lazy-placeholder'
+import { LazyWidgetPlaceholder } from '../panel/lazy-placeholder'
 import { Button } from '../ui/button'
 
 /**
@@ -150,7 +150,7 @@ export function CustomizableWidgetGrid({
 
             const content = widget ? (
               isLazyPlaceholder(widget) ? (
-                <LazyPlaceholder variant={widget.type === 'TableWidget' ? 'table' : 'widget'} />
+                <LazyWidgetPlaceholder widget={widget} />
               ) : (
                 renderWidget(widget)
               )

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/components/widgets/widgets-block.tsx

@@ -10,7 +10,7 @@ import { createElement, type ComponentProps } from 'react'
 import { useRegistry, useT } from '../../context'
 import { lazyComponent } from '../../lib/lazy'
 import { cn } from '../../lib/utils'
-import { LazyPlaceholder } from '../panel/lazy-placeholder'
+import { LazyWidgetPlaceholder } from '../panel/lazy-placeholder'
 import { Slot } from '../panel/slot'
 import { DataTable } from '../table/table-block'
 import { ChartWidget } from './chart-lazy'
@@ -49,7 +49,7 @@ function StaticWidgetGrid({ block }: { block: WidgetsBlockSchema }) {
       {block.widgets.map((widget) => (
         <div key={widget.key} className={cn('min-w-0', columnSpanClasses(widget.columnSpan))}>
           {isLazyPlaceholder(widget) ? (
-            <LazyPlaceholder variant={widget.type === 'TableWidget' ? 'table' : 'widget'} />
+            <LazyWidgetPlaceholder widget={widget} />
           ) : (
             <WidgetRenderer widget={widget} />
           )}

package/src/create-alfakit.tsx

@@ -13,10 +13,12 @@ import {
   installErrorNotifications,
   installPrefetchInvalidation,
   installSpaUrlExceptions,
+  overlayPlacementDirection,
   registerRichEditorExtensions,
   reloadOnExpiredPage,
   resolveRequestErrorNotification,
   resolveToastPosition,
+  setIconAliases,
   setRequestErrorReporter,
   whenIdle,
   type AlfakitOptions,
@@ -72,6 +74,9 @@ export function AlfakitRoot({
   if (panel) {
     translator.setTranslations(panel.translations ?? {})
     translator.setLocale(localization?.tag ?? 'en')
+    // Chrome icons replaced with `Icons::register()`, also in a server render, so the server
+    // and the browser draw the same glyph (W-V3-28).
+    setIconAliases(panel.theme?.icons)
   }
 
   // Starter kit mode: the host app owns `<html lang dir>` (its own pages and layout are not
@@ -104,7 +109,10 @@ export function AlfakitRoot({
           })}
         <Toaster
           id={toasterId}
-          position={resolveToastPosition(panel?.toastPosition, direction)}
+          position={resolveToastPosition(
+            panel?.toastPosition,
+            overlayPlacementDirection(direction, panel?.starterKit),
+          )}
           offset={PANEL_TOAST_OFFSET}
           mobileOffset={PANEL_TOAST_OFFSET}
           dir={direction}

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)
@@ -188,7 +193,7 @@ export function AlfakitComponent({
             data-slot="page-header"
             className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between"
           >
-            <div className="min-w-0">
+            <div className="min-w-0 sm:max-w-[50%] sm:shrink-0">
               {page.heading && (
                 <h2 className="text-xl font-semibold tracking-tight">{page.heading}</h2>
               )}
@@ -201,7 +206,7 @@ export function AlfakitComponent({
                 actions={page.headerActions}
                 context={actionContext}
                 align="end"
-                className="max-w-full shrink-0"
+                className="max-w-full min-w-0"
               />
             )}
           </header>

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/index.ts

@@ -3,6 +3,7 @@ export { useAlfakitNavigation, type AlfakitNavigation } from './navigation'
 export {
   AlfakitStarterKitRoot,
   StarterKitContentLayout,
+  StarterKitFullscreenLayout,
   createStarterKitPage,
   type StarterKitLayout,
   type StarterKitPageOptions,

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

@@ -85,6 +85,27 @@ export function StarterKitContentLayout({ children, maxContentWidth }: AppLayout
   )
 }
 
+/**
+ * A `$layout = 'fullscreen'` page inside the host layout: what `layout:fullscreen` renders in
+ * starter kit mode. The host layout is the chrome, so there is no AlfaKit header (brand, top
+ * bar slots, user menu, Exit); the screen gets the whole content area. Replace it with
+ * `{ components: { 'layout:fullscreen': MyScreen } }`.
+ */
+export function StarterKitFullscreenLayout({ children }: { children: ReactNode }) {
+  return (
+    <div
+      data-slot="content"
+      data-layout="fullscreen"
+      data-alfakit-embedded=""
+      className="flex min-h-0 w-full min-w-0 flex-1 flex-col"
+    >
+      <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
@@ -98,6 +119,7 @@ function createStarterKitContext(options: StarterKitPageOptions): AlfakitContext
     .registerMany(lazyPanelLayouts)
     .register('layout:auth', AuthLayout)
     .register('layout:app', StarterKitContentLayout)
+    .register('layout:fullscreen', StarterKitFullscreenLayout)
     .registerMany(discovered.components)
     .registerMany(options.components ?? {})
   const translator = new Translator()
@@ -185,8 +207,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;