@alfakit/react 0.1.10 → 0.1.12

package/src/components/fields/money-input.tsx

@@ -13,13 +13,6 @@ import { Input } from '../ui/input'
  * it, accepts the locale's separators and digits ("1.234,50", "١٢٫٥"), and rounds to
  * the currency's precision on blur. The form value is a plain decimal string ("1234.50").
  */
-export function clampAmount(amount: number, min?: number | null, max?: number | null): number {
-  const lower = min ?? Number.NEGATIVE_INFINITY
-  const upper = max ?? Number.POSITIVE_INFINITY
-
-  return Math.min(upper, Math.max(lower, amount))
-}
-
 export function MoneyInputField({ component }: { component: MoneyInputSchema }) {
   const { value, setValue, blur, error, id, disabled, aria } = useField<string | number | null>(
     component,
@@ -46,13 +39,9 @@ export function MoneyInputField({ component }: { component: MoneyInputSchema })
 
     const parsed = format.parseNumber(text)
 
-    // Unparseable input is kept as typed so server validation can explain the problem;
-    // amounts are brought inside `minValue()` / `maxValue()`.
-    setValue(
-      parsed === null
-        ? text
-        : clampAmount(parsed, component.min, component.max).toFixed(component.decimals),
-    )
+    // Unparseable input is kept as typed and out-of-range amounts are kept as well, so the
+    // server's `minValue()` / `maxValue()` rules report them (W-V3-11).
+    setValue(parsed === null ? text : parsed.toFixed(component.decimals))
   }
 
   const affix = (text: string, icon: string | undefined, side: 'start' | 'end') =>

package/src/components/fields/repeater.tsx

@@ -1,6 +1,5 @@
 import type { RepeaterSchema, SchemaComponent } from '@alfakit/core'
 import {
-  VIRTUAL_ESTIMATES,
   appendRepeaterItem,
   cloneIndexedState,
   cloneRepeaterItem,
@@ -8,12 +7,14 @@ import {
   fieldIds,
   gridColumnsClasses,
   isDeferredPlaceholder,
+  itemExtraActions,
   moveIndexedState,
   moveRepeaterItem,
   removeIndexedState,
   removeRepeaterItem,
   reorderedItemKeys,
   templateForIndex,
+  VIRTUAL_ESTIMATES,
   virtualizeOptions,
 } from '@alfakit/core'
 import { useState } from 'react'
@@ -165,7 +166,7 @@ function RepeaterFieldContent({ component }: { component: RepeaterSchema }) {
             virtual={virtual}
             context={context}
             resolve={(name, index) => resolve(name, component.items[index])}
-            extraActionsFor={(index) => component.items[index]?.actions}
+            extraActionsFor={(index) => itemExtraActions(component, component.items[index])}
           />
         ) : (
           <>
@@ -245,7 +246,9 @@ function RepeaterFieldContent({ component }: { component: RepeaterSchema }) {
                             index={index}
                             count={items.length}
                             resolve={(name) => resolve(name, serverItem)}
-                            extraActions={locked ? undefined : serverItem?.actions}
+                            extraActions={
+                              locked ? undefined : itemExtraActions(component, serverItem)
+                            }
                             buttons={buttons}
                             canClone={Boolean(component.cloneable) && canAdd}
                             canDelete={canDelete}

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

@@ -152,11 +152,15 @@ export function useRichEditorExtensions(
 
     if (!result || !editor || editor.isDestroyed) return
 
-    editor
-      .chain()
-      .focus()
-      .insertContent({ type: 'customBlock', attrs: { id: result.id, config: result.config } })
-      .run()
+    const block = { type: 'customBlock', attrs: { id: result.id, config: result.config } }
+    // A block inserted just before is still selected (a node selection): insert after it
+    // instead of replacing it (W-S2-05).
+    const { selection } = editor.state
+    const chain = editor.chain().focus()
+    ;('node' in selection && selection.node
+      ? chain.insertContentAt(selection.to, block)
+      : chain.insertContent(block)
+    ).run()
   }
 
   return { extensions, suggestions, insertBlock, context }

package/src/components/layout/wizard.tsx

@@ -21,6 +21,7 @@ import { cn } from '../../lib/utils'
 import { ActionButton } from '../actions/action-button'
 import { usePageActionContext } from '../actions/action-context'
 import { useOptionalFormStore } from '../form/form-context'
+import { useFieldActionContext } from '../schema/field-actions'
 import { SchemaRenderer } from '../schema/schema-renderer'
 import { Button } from '../ui/button'
 import { DeferredSchema } from './deferred'
@@ -52,6 +53,9 @@ export function WizardComponent({ component }: { component: WizardSchema }) {
     if (stepQueryKey) persistWizardStep(current, stepQueryKey)
   }, [current, stepQueryKey])
   const store = useOptionalFormStore()
+  // Inside a form the submit action runs as a field action, so `$get` / `$set` work (W-S2-09).
+  const fieldContext = useFieldActionContext(component)
+  const submitContext = store ? fieldContext : actionContext
 
   // An action modal around this wizard shows its submit button on the last step only.
   useEffect(() => {
@@ -229,7 +233,7 @@ export function WizardComponent({ component }: { component: WizardSchema }) {
             </Button>
           )
         ) : component.submitAction ? (
-          <ActionButton action={component.submitAction} context={actionContext} />
+          <ActionButton action={component.submitAction} context={submitContext} />
         ) : component.submitActionHtml ? (
           <div
             data-slot="wizard-submit"

package/src/components/notifications/flash-toasts.tsx

@@ -43,6 +43,14 @@ export function setToasterId(id: string | undefined): void {
   toasterId = id
 }
 
+/**
+ * Options for a direct `toast.*()` call: the starter kit toaster's id merged in, so PWA and
+ * notification messages reach AlfaKit's toaster in a starter kit too (W-S1-03).
+ */
+export function toastOptions<T extends object>(options?: T): T & { toasterId?: string } {
+  return { ...(options ?? ({} as T)), toasterId }
+}
+
 /** `closeNotification(id)` (or a `close-notification` event) dismisses that toast. */
 export function listenForClosedNotifications(): void {
   if (closeListening || typeof window === 'undefined') return

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

@@ -19,7 +19,7 @@ import { Button } from '../ui/button'
 import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
 import { ScrollArea } from '../ui/scroll-area'
 import { Spinner } from '../ui/spinner'
-import { NotificationActionButton } from './flash-toasts'
+import { NotificationActionButton, toastOptions } from './flash-toasts'
 
 export interface NotificationsMenuProps {
   /**
@@ -104,8 +104,8 @@ export function NotificationsMenu({ variant = 'topbar' }: NotificationsMenuProps
     const { message } = await togglePushNotifications()
     const text = t(message.key, {}, message.fallback)
 
-    if (message.error) toast.error(text)
-    else toast.success(text)
+    if (message.error) toast.error(text, toastOptions())
+    else toast.success(text, toastOptions())
   }
 
   const pushLabel =

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

@@ -1,5 +1,8 @@
-import { useT } from '../../context'
+import { widgetPollTarget, type LazyWidgetSchema } from '@alfakit/core'
+import { useState } from 'react'
+import { useRefreshComponents, useT } from '../../context'
 import { cn } from '../../lib/utils'
+import { Button } from '../ui/button'
 import { Skeleton } from '../ui/skeleton'
 
 /**
@@ -37,3 +40,40 @@ export function LazyPlaceholder({
     </div>
   )
 }
+
+/**
+ * A lazy widget's cell: the skeleton while its schema loads, or, when the request failed
+ * (outside panels: a refused or failed fetch), a message with a retry.
+ */
+export function LazyWidgetPlaceholder({ widget }: { widget: LazyWidgetSchema }) {
+  const t = useT()
+  const refresh = useRefreshComponents()
+  const [retrying, setRetrying] = useState(false)
+  const variant = widget.type === 'TableWidget' ? 'table' : 'widget'
+
+  if (!widget.failed) return <LazyPlaceholder variant={variant} />
+
+  const retry = () => {
+    if (!refresh) return
+
+    setRetrying(true)
+    void Promise.resolve(refresh([widgetPollTarget(widget)])).finally(() => setRetrying(false))
+  }
+
+  return (
+    <div
+      data-slot="lazy-placeholder"
+      data-variant={variant}
+      data-failed=""
+      role="alert"
+      className="bg-card text-muted-foreground flex min-h-28 flex-col items-center justify-center gap-3 rounded-xl border border-dashed p-6 text-center text-sm"
+    >
+      <p>{t('widget_failed', {}, 'This widget could not be loaded.')}</p>
+      {refresh && (
+        <Button type="button" variant="outline" size="sm" disabled={retrying} onClick={retry}>
+          {t('retry', {}, 'Retry')}
+        </Button>
+      )}
+    </div>
+  )
+}

package/src/components/panel/pwa.tsx

@@ -14,6 +14,7 @@ import { toast } from 'sonner'
 import { usePanel, useT } from '../../context'
 import { useStore } from '../../hooks/use-store'
 import { Icon } from '../../lib/icons'
+import { toastOptions } from '../notifications/flash-toasts'
 import { DropdownMenuItem } from '../ui/dropdown-menu'
 
 const UPDATE_TOAST_ID = 'alfakit-pwa-update'
@@ -27,7 +28,7 @@ export async function installPwa(t: Translator['t']): Promise<void> {
         {},
         'To install this app, tap the Share button and then “Add to Home Screen”.',
       ),
-      { duration: 10000 },
+      toastOptions({ duration: 10000 }),
     )
   }
 }
@@ -49,11 +50,14 @@ export function PwaManager() {
   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() },
-    })
+    toast(
+      t('pwa.update_available', {}, 'A new version is available'),
+      toastOptions({
+        id: UPDATE_TOAST_ID,
+        duration: Infinity,
+        action: { label: t('pwa.reload', {}, 'Reload'), onClick: () => applyPwaUpdate() },
+      }),
+    )
   }, [updateAvailable, t])
 
   return null
@@ -74,15 +78,25 @@ export function PwaMenuItems() {
       state.push === 'subscribed' ? await unsubscribeFromPush() : await subscribeToPush()
 
     if (outcome === 'subscribed') {
-      toast.success(t('pwa.notifications.enabled', {}, 'Notifications are on for this device'))
+      toast.success(
+        t('pwa.notifications.enabled', {}, 'Notifications are on for this device'),
+        toastOptions(),
+      )
     } else if (outcome === 'unsubscribed') {
-      toast.success(t('pwa.notifications.disabled', {}, 'Notifications are off for this device'))
+      toast.success(
+        t('pwa.notifications.disabled', {}, 'Notifications are off for this device'),
+        toastOptions(),
+      )
     } else if (outcome === 'denied') {
       toast.error(
         t('pwa.notifications.blocked', {}, 'Notifications are blocked in your browser settings'),
+        toastOptions(),
       )
     } else {
-      toast.error(t('pwa.notifications.failed', {}, 'Couldn’t change notifications. Try again.'))
+      toast.error(
+        t('pwa.notifications.failed', {}, 'Couldn’t change notifications. Try again.'),
+        toastOptions(),
+      )
     }
   }
 

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

@@ -221,7 +221,7 @@ export function ShortcutsOverlay({
                               aria-label={t(
                                 'shortcuts.reset_label',
                                 { label: item.label },
-                                `Restore the default shortcut for ${item.label}`,
+                                `Reset the shortcut for ${item.label}`,
                               )}
                               onClick={() => void save(item.id, null)}
                             >

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),
@@ -240,7 +242,9 @@ function ImageCell({ column, cell }: CellProps) {
         <span
           data-slot="image-remaining"
           className={cn(
-            'text-muted-foreground ms-1',
+            'text-muted-foreground',
+            // The last image keeps the stack's negative end margin (W-S3-03).
+            schema.stacked && usesDefaultImageStack(schema) ? 'ms-3' : 'ms-1',
             remainingTextSizeClass(schema.limitedRemainingTextSize),
           )}
         >

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/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

@@ -281,7 +281,7 @@ export function ContentBlockRenderer({ block }: { block: ContentBlock }) {
         <div data-slot="infolist" className="contents">
           <SchemaRenderer
             components={(block as InfolistBlock).components}
-            columns={{ default: 1, lg: 2 }}
+            columns={(block as InfolistBlock).columns ?? { default: 1, lg: 2 }}
           />
         </div>
       )

package/src/standalone/alfakit-component.tsx

@@ -193,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>
               )}
@@ -206,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/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/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()