@alfakit/react 0.1.12 → 0.2.0

package/src/components/fields/slider.tsx

@@ -101,7 +101,9 @@ export function SliderField({ component }: { component: SliderSchema }) {
   }
 
   return (
-    <FieldWrapper field={component} htmlFor={`${id}-thumb-0`} error={error}>
+    // The wrapper's label, hint and error ids derive from `id`, as `aria` does: a thumb is not
+    // labelable, so one thumb names itself through `aria-labelledby`.
+    <FieldWrapper field={component} htmlFor={id} error={error}>
       <div
         data-slot="slider"
         className={cn(

package/src/components/panel/app-sidebar.tsx

@@ -8,7 +8,7 @@ import {
 } from '@alfakit/core'
 import { Link } from '@inertiajs/react'
 import { ChevronRightIcon } from 'lucide-react'
-import type { ComponentProps, ReactNode } from 'react'
+import { useState, type ComponentProps, type ReactNode } from 'react'
 import { useDirection, usePanel, useT } from '../../context'
 import { extraProps } from '../../lib/attributes'
 import { badgeColorClasses, colorClass } from '../../lib/colors'
@@ -114,12 +114,32 @@ function NavLink({
   )
 }
 
+/**
+ * Open state of a collapsible menu entry: `defaultOpen` at first, and opened again when the
+ * entry becomes active. The sidebar stays mounted across visits, so it keeps what the user
+ * opened or closed, while a page reached from elsewhere still shows its menu entry.
+ */
+function useOpenWhenActive(defaultOpen: boolean, active: boolean) {
+  const [open, setOpen] = useState(defaultOpen)
+  const [wasActive, setWasActive] = useState(active)
+
+  if (active !== wasActive) {
+    setWasActive(active)
+
+    if (active) setOpen(true)
+  }
+
+  return { open, onOpenChange: setOpen }
+}
+
 /** Child items (any depth) with their own badges, new-tab links and nested children. */
 function NavSubItem({ item }: { item: NavigationItemSchema }) {
+  const collapsible = useOpenWhenActive(!!item.active, !!item.active)
+
   if (item.children && item.children.length > 0) {
     return (
       <SidebarMenuSubItem>
-        <Collapsible defaultOpen={item.active} className="group/nav-sub">
+        <Collapsible {...collapsible} className="group/nav-sub">
           <CollapsibleTrigger asChild>
             <SidebarMenuSubButton asChild isActive={item.active}>
               <button type="button" {...extraProps(item.extraAttributes, 'w-full')}>
@@ -156,9 +176,11 @@ function NavSubItem({ item }: { item: NavigationItemSchema }) {
 }
 
 function NavItem({ item }: { item: NavigationItemSchema }) {
+  const collapsible = useOpenWhenActive(!!item.active, !!item.active)
+
   if (item.children && item.children.length > 0) {
     return (
-      <Collapsible asChild defaultOpen={item.active} className="group/collapsible">
+      <Collapsible asChild {...collapsible} className="group/collapsible">
         <SidebarMenuItem>
           <CollapsibleTrigger asChild>
             <SidebarMenuButton
@@ -259,6 +281,8 @@ function NavGroup({ group }: { group: NavigationGroupSchema }) {
   const attributes = extraProps(group.extraSidebarAttributes)
   // A labelled group with an icon collapses into a flyout in the icon-only sidebar.
   const flyout = Boolean(group.label && group.icon)
+  const active = group.items.some((item) => item.active)
+  const collapsible = useOpenWhenActive(!group.collapsed || active, active)
   const content = (
     <SidebarGroupContent className={cn(flyout && 'group-data-[collapsible=icon]:hidden')}>
       <SidebarMenu>
@@ -288,10 +312,7 @@ function NavGroup({ group }: { group: NavigationGroupSchema }) {
   }
 
   return (
-    <Collapsible
-      defaultOpen={!group.collapsed || group.items.some((item) => item.active)}
-      className="group/nav-group"
-    >
+    <Collapsible {...collapsible} className="group/nav-group">
       <SidebarGroup {...attributes}>
         <CollapsibleTrigger asChild>
           <SidebarGroupLabel

package/src/components/panel/global-search.tsx

@@ -133,7 +133,10 @@ export function GlobalSearch({ variant = 'topbar' }: { variant?: 'topbar' | 'sid
           </span>
         )}
         {hydrated && suffix?.type === 'keyBinding' && (
-          <kbd dir="ltr" className="bg-muted hidden rounded px-1 font-mono text-[10px] sm:inline">
+          <kbd
+            dir="ltr"
+            className="bg-muted text-foreground/70 hidden rounded px-1 font-mono text-[10px] sm:inline"
+          >
             {formatKeyBinding(suffix.keyBinding)}
           </kbd>
         )}

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

@@ -26,7 +26,7 @@ export function ShortcutKeys({ binding, className }: { binding: string; classNam
           )}
           <kbd
             dir="ltr"
-            className="bg-muted text-muted-foreground rounded border px-1.5 font-mono text-[10px] leading-5"
+            className="bg-muted text-foreground/70 rounded border px-1.5 font-mono text-[10px] leading-5"
           >
             {step}
           </kbd>

package/src/components/table/list-tabs.tsx

@@ -69,7 +69,9 @@ export function ListTabs({
               cn(
                 'inline-flex h-[calc(100%-1px)] shrink-0 items-center justify-center gap-1.5 rounded-md border border-transparent px-2.5 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-none',
                 'focus-visible:border-ring focus-visible:ring-ring/50',
-                active ? 'bg-background text-foreground shadow-sm' : 'hover:text-foreground',
+                active
+                  ? 'bg-background text-foreground shadow-sm'
+                  : 'text-foreground/70 hover:text-foreground',
               ),
             )}
             ref={(element) => {

package/src/components/table/table-views.tsx

@@ -240,7 +240,9 @@ export function TableViews({
               className={cn(
                 'inline-flex h-[calc(100%-1px)] shrink-0 items-center justify-center gap-1.5 rounded-md border border-transparent px-2.5 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-none',
                 'focus-visible:border-ring focus-visible:ring-ring/50',
-                selected ? 'bg-background text-foreground shadow-sm' : 'hover:text-foreground',
+                selected
+                  ? 'bg-background text-foreground shadow-sm'
+                  : 'text-foreground/70 hover:text-foreground',
               )}
               onClick={() => !selected && visitTableView(table, item?.key ?? null)}
               onKeyDown={(event) => onTabKeyDown(event, index)}

package/src/context.tsx

@@ -12,7 +12,15 @@ import {
   type Translator,
 } from '@alfakit/core'
 import { usePage } from '@inertiajs/react'
-import { createContext, useContext, useMemo, type ComponentType, type ReactNode } from 'react'
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyComponent = ComponentType<any>
@@ -33,6 +41,14 @@ export interface AlfakitContextValue {
    * change). Panels leave it out (a partial reload); components outside panels fetch theirs.
    */
   refresh?: (targets: string[]) => Promise<void>
+  /**
+   * Whether every page is rendered only after the split built-ins and discovered components
+   * it names have loaded, on the server and before hydration (`createAlfakit()` resolves
+   * pages that way). Without it (starter kits, standalone components) those components show
+   * after hydration: a long-lived SSR server keeps code earlier requests loaded, a fresh
+   * browser has none of it, so rendering them early would make the markups differ.
+   */
+  preloadsPageComponents?: boolean
 }
 
 const AlfakitContext = createContext<AlfakitContextValue | null>(null)
@@ -52,6 +68,35 @@ function useOptionalPageProps(): AlfakitPageProps {
   }
 }
 
+/**
+ * The Inertia page URL, or undefined outside an Inertia app. Persistent chrome (the panel
+ * layout stays mounted across visits) closes its phone sheets when it changes.
+ */
+export function useOptionalPageUrl(): string | undefined {
+  try {
+    return usePage().url
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Calls `close` when the user moves to another page. The panel layout persists across
+ * visits, so menus and sheets that used to be reset by remounting close here instead.
+ * Partial reloads (deferred props, polling) keep the URL and leave them open.
+ */
+export function useCloseOnVisit(close: () => void): void {
+  const url = useOptionalPageUrl()
+  const previous = useRef(url)
+
+  useEffect(() => {
+    if (previous.current === url) return
+
+    previous.current = url
+    close()
+  }, [url, close])
+}
+
 /**
  * Outside panels there is no shared `alfakit` prop and no `page` prop: `<AlfakitComponent>`
  * provides both from its payload, and the hooks below read them first.

package/src/create-alfakit.tsx

@@ -32,6 +32,7 @@ import { Direction } from 'radix-ui'
 import {
   StrictMode,
   createElement,
+  useEffect,
   useLayoutEffect,
   type ReactElement,
   type ReactNode,
@@ -49,8 +50,9 @@ import { AlfakitProvider, useAlfakit, type AlfakitContextValue, type AnyComponen
 import { panelLayouts } from './layouts/panel-layouts'
 import { discoverComponents } from './lib/discovery'
 import { preloadIcons } from './lib/icons'
-import { AlfakitPage } from './pages/page'
+import { AlfakitPage, PanelLayoutHost } from './pages/page'
 import { builtInComponents, createDefaultRegistry } from './registry'
+import { claimToaster } from './standalone/toaster-claims'
 
 /**
  * Rendered inside Inertia's page tree, so it follows the current page: the reading
@@ -91,10 +93,17 @@ export function AlfakitRoot({
     applyPanelTheme(panel)
   }, [panel])
 
+  // This root renders the toaster: starter kit header components and standalone components
+  // on the same page don't mount a second one.
+  useEffect(() => claimToaster(), [])
+
   return (
     <Direction.Provider dir={direction}>
       <TooltipProvider delayDuration={0}>
-        <SchemaContractGuard panel={panel}>{children}</SchemaContractGuard>
+        {/* The panel layout stays mounted across visits between Alfakit pages. */}
+        <SchemaContractGuard panel={panel}>
+          <PanelLayoutHost>{children}</PanelLayoutHost>
+        </SchemaContractGuard>
         <ActionModals />
         <FlashToasts />
         <RealtimeNotifications />
@@ -181,6 +190,8 @@ export function bootAlfakit(
       registry,
       pages,
       translator,
+      // `resolve` below loads the page's split built-ins and discovered files first.
+      preloadsPageComponents: true,
       // The runner's endpoints are refreshed on every navigation from the shared props.
       actions: new ActionRunner({
         endpoints: { action: '', modal: '' },

package/src/layouts/app-layout.tsx

@@ -6,14 +6,14 @@ import {
   type BreadcrumbSchema,
   type Width,
 } from '@alfakit/core'
-import { createElement, type CSSProperties, type ReactNode } from 'react'
+import { createElement, useCallback, type CSSProperties, type ReactNode } from 'react'
 import { AppSidebar } from '../components/panel/app-sidebar'
 import { BottomNav } from '../components/panel/bottom-nav'
 import { TopbarLocaleSwitcher } from '../components/panel/locale-switcher'
 import { Slot } from '../components/panel/slot'
 import { Topbar } from '../components/panel/topbar'
-import { SidebarInset, SidebarProvider, SidebarTrigger } from '../components/ui/sidebar'
-import { useAlfakitProps, useRegistry } from '../context'
+import { SidebarInset, SidebarProvider, SidebarTrigger, useSidebar } from '../components/ui/sidebar'
+import { useAlfakitProps, useCloseOnVisit, useRegistry } from '../context'
 import { cn } from '../lib/utils'
 import { MAX_WIDTHS } from './max-widths'
 import { TopNavLayout } from './top-nav-layout'
@@ -48,6 +48,18 @@ export function MobileTopbar() {
   )
 }
 
+/**
+ * The layout stays mounted across visits: the phone sidebar sheet closes when the user
+ * moves to another page.
+ */
+function CloseMobileSidebarOnVisit() {
+  const { setOpenMobile } = useSidebar()
+
+  useCloseOnVisit(useCallback(() => setOpenMobile(false), [setOpenMobile]))
+
+  return null
+}
+
 export function AppLayout({ children, breadcrumbs, maxContentWidth }: AppLayoutProps) {
   const props = useAlfakitProps()
   const registry = useRegistry()
@@ -73,6 +85,7 @@ export function AppLayout({ children, breadcrumbs, maxContentWidth }: AppLayoutP
       defaultOpen={sidebarDefaultOpen(props.alfakitSidebarOpen, layout)}
       style={sidebarWidthStyle(props.alfakit) as CSSProperties | undefined}
     >
+      <CloseMobileSidebarOnVisit />
       <Slot name="body.start" />
       <Slot name="layout.start" />
       {createElement(Sidebar)}

package/src/lib/discovery.tsx

@@ -4,29 +4,44 @@ import {
   type DiscoveryModules,
   type DiscoveryOptions,
 } from '@alfakit/core'
-import { createElement, useEffect, useState } from 'react'
-import type { AnyComponent } from '../context'
+import { createElement, useEffect, useState, useSyncExternalStore } from 'react'
+import { useOptionalAlfakit, type AnyComponent } from '../context'
+
+const subscribe = () => () => {}
 
 /**
  * A discovered component: rendered straight away once its code has loaded (the pages that
  * use it preload it, see `ComponentDiscovery.preloadFor()`), else as soon as it arrives
  * (through state, not `<Suspense>`, whose reveal React throttles by up to 300 ms).
  * Each mount keeps the path it started with, so loading never remounts a field.
+ *
+ * Where pages are not preloaded (starter kits, standalone components), the server render
+ * and hydration leave it out even when its code is loaded: a long-lived SSR server keeps
+ * what earlier requests loaded, a fresh browser has none of it (OM-B06).
  */
 export function discoveredComponent(entry: DiscoveredEntry<AnyComponent>): AnyComponent {
   function Discovered(props: Record<string, unknown>) {
+    const preloaded = useOptionalAlfakit()?.preloadsPageComponents === true
+    // False on the server and while hydrating, true for every later render and mount.
+    const hydrated = useSyncExternalStore(
+      subscribe,
+      () => true,
+      () => false,
+    )
+    const ready = preloaded || hydrated
     const [state, setState] = useState<{ component?: AnyComponent; error?: unknown }>(() => ({
-      component: entry.current,
+      component: ready ? entry.current : undefined,
     }))
+    const component = state.component ?? (ready ? entry.current : undefined)
 
     useEffect(() => {
-      if (state.component) return
+      if (component) return
 
       let active = true
 
       entry.load().then(
-        (component) => {
-          if (active) setState({ component })
+        (loaded) => {
+          if (active) setState({ component: loaded })
         },
         (error: unknown) => {
           if (active) setState({ error: error ?? new Error(`Failed to load ${entry.key}`) })
@@ -36,11 +51,11 @@ export function discoveredComponent(entry: DiscoveredEntry<AnyComponent>): AnyCo
       return () => {
         active = false
       }
-    }, [state.component])
+    }, [component])
 
     if (state.error !== undefined) throw state.error
 
-    return state.component ? createElement(state.component, props) : null
+    return component ? createElement(component, props) : null
   }
 
   Discovered.displayName = `Discovered(${entry.key})`

package/src/lib/icons.tsx

@@ -1,61 +1,126 @@
 import { iconAlias, iconAliasOverride, iconSource, isIconAlias } from '@alfakit/core'
 import type { LucideProps } from 'lucide-react'
 import type { DynamicIcon, IconName as LucideIconName } from 'lucide-react/dynamic.mjs'
-import { createElement, useEffect, useState, type ComponentProps, type ComponentType } from 'react'
+import {
+  createElement,
+  useEffect,
+  useState,
+  type ComponentProps,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
 import { useOptionalRegistry } from '../context'
+import { useHydrated } from '../hooks/use-hydrated'
 import { cn } from './utils'
 
 type DynamicIconComponent = typeof DynamicIcon
+type LucideGlyph = ComponentType<LucideProps>
+type IconImports = Record<string, () => Promise<{ default: LucideGlyph }>>
 
 /**
  * `lucide-react/dynamic` carries a lazy import for every Lucide icon (~2,000 entries), so it
  * is not part of any entry chunk: panels (`createAlfakit()`, starter kit pages) start loading
  * it while they boot, since every page draws named icons, and elsewhere (a host's sidebar)
- * it loads with the first icon. Named icons render asynchronously either way.
+ * it loads with the first icon.
  */
-let dynamicIcon: DynamicIconComponent | undefined
-let pendingDynamicIcon: Promise<DynamicIconComponent> | undefined
+let pendingImports: Promise<IconImports> | undefined
 
-function loadDynamicIcon(): Promise<DynamicIconComponent> {
-  pendingDynamicIcon ??= import('lucide-react/dynamic.mjs').then(
-    (module) => (dynamicIcon = module.DynamicIcon),
+function loadIconImports(): Promise<IconImports> {
+  pendingImports ??= import('lucide-react/dynamic.mjs').then(
+    (module) => module.dynamicIconImports as unknown as IconImports,
     (error: unknown) => {
-      pendingDynamicIcon = undefined
+      pendingImports = undefined
 
       throw error
     },
   )
 
-  return pendingDynamicIcon
+  return pendingImports
+}
+
+/**
+ * Loaded icons by name (`null`: not a Lucide icon), shared by every `<Icon>`: an icon that
+ * loaded once draws synchronously in every later mount (the page after a visit, new table
+ * rows), instead of rendering empty for a frame on each mount as `DynamicIcon` does.
+ */
+const loadedIcons = new Map<string, LucideGlyph | null>()
+const pendingIcons = new Map<string, Promise<LucideGlyph | null>>()
+
+function loadIcon(name: string): Promise<LucideGlyph | null> {
+  const loaded = loadedIcons.get(name)
+
+  if (loaded !== undefined) return Promise.resolve(loaded)
+
+  let pending = pendingIcons.get(name)
+
+  if (!pending) {
+    pending = loadIconImports()
+      .then((imports) => {
+        const load = Object.prototype.hasOwnProperty.call(imports, name) ? imports[name] : undefined
+
+        return load ? load().then((module) => module.default) : null
+      })
+      .then(
+        (icon) => {
+          loadedIcons.set(name, icon)
+          pendingIcons.delete(name)
+
+          return icon
+        },
+        (error: unknown) => {
+          // A failed chunk is tried again by the next mount.
+          pendingIcons.delete(name)
+
+          throw error
+        },
+      )
+    pendingIcons.set(name, pending)
+  }
+
+  return pending
 }
 
 /** Start loading `lucide-react/dynamic` ahead of the first named icon (browser only). */
 export function preloadIcons(): void {
-  if (typeof window !== 'undefined') loadDynamicIcon().catch(() => undefined)
+  if (typeof window !== 'undefined') loadIconImports().catch(() => undefined)
+}
+
+type LucideIconProps = Omit<ComponentProps<DynamicIconComponent>, 'name' | 'fallback'> & {
+  name: string
+  fallback?: () => ReactNode
 }
 
-/** `DynamicIcon`, rendering its `fallback` (or nothing) until `lucide-react/dynamic` loads. */
-function LazyDynamicIcon(props: ComponentProps<DynamicIconComponent>) {
-  const [Dynamic, setDynamic] = useState(() => dynamicIcon)
+/**
+ * A Lucide icon by name, rendering `fallback` (or nothing) while it loads and for unknown
+ * names. An icon that has loaded renders at once, except during the server render and
+ * hydration: the server draws no named icons, so the hydrated markup matches it.
+ */
+function LucideIcon({ name, fallback, ...props }: LucideIconProps) {
+  const hydrated = useHydrated()
+  const [, setLoaded] = useState(0)
+  const Loaded = hydrated ? loadedIcons.get(name) : undefined
 
   useEffect(() => {
-    if (Dynamic) return
+    if (loadedIcons.has(name)) return
 
     let active = true
 
-    loadDynamicIcon().then(
-      (component) => active && setDynamic(() => component),
-      () => undefined,
+    loadIcon(name).then(
+      () => {
+        if (active) setLoaded((count) => count + 1)
+      },
+      (error: unknown) => console.error(error),
     )
 
     return () => {
       active = false
     }
-  }, [Dynamic])
+  }, [name])
 
-  if (Dynamic) return <Dynamic {...props} />
+  // A module-level cache entry (one component per icon name), not created during render.
+  if (Loaded) return createElement(Loaded, props as LucideProps)
 
-  return props.fallback ? createElement(props.fallback) : null
+  return fallback ? fallback() : null
 }
 
 /** A statically imported glyph (`SearchIcon` from `lucide-react`). */
@@ -72,7 +137,8 @@ export type IconProps = Omit<ComponentProps<DynamicIconComponent>, 'name' | 'fal
  * app's replacement (`Icons::register()`) or `fallback`. Unknown Lucide names fall back to
  * `fallback`, if any. `fallback` may also be a statically imported glyph
  * (`fallback={SearchIcon}`): renderer chrome uses it so an unreplaced alias draws at once,
- * without loading anything. Register a `panel:icon` component
+ * without loading anything. Named icons load on demand; once loaded, later mounts draw them
+ * synchronously. Register a `panel:icon` component
  * (`createAlfakit({ components: { 'panel:icon': MyIcon } })`) to render every named icon
  * with another icon set; it receives `name`, `fallback` and `className`.
  */
@@ -129,14 +195,14 @@ export function Icon({ name, fallback: fallbackProp, className, ...props }: Icon
   }
 
   return (
-    <LazyDynamicIcon
-      name={source.name as LucideIconName}
+    <LucideIcon
+      name={source.name}
       className={classes}
       fallback={
         Glyph
           ? () => <Glyph className={classes} />
           : fallback
-            ? () => <LazyDynamicIcon name={fallback} className={classes} />
+            ? () => <LucideIcon name={fallback} className={classes} />
             : undefined
       }
       {...props}