@alfakit/react 0.1.13 → 0.2.0

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}

package/src/pages/page.tsx

@@ -1,4 +1,5 @@
 import type {
+  AlfakitPageProps,
   ContentBlock,
   FormBlock as FormBlockSchema,
   InfolistBlock,
@@ -24,8 +25,10 @@ import {
 } from '@alfakit/core'
 import { Head, Link, usePage } from '@inertiajs/react'
 import {
+  createContext,
   createElement,
   Fragment,
+  useContext,
   useEffect,
   useId,
   useMemo,
@@ -155,13 +158,24 @@ function layout(registry: { resolve(key: string): AnyComponent | undefined }, ke
   return registry.resolve(key) ?? BlankLayout
 }
 
-export function PageShell({ page, children }: { page: PageSchema; children: ReactNode }) {
-  const { registry } = useAlfakit()
+type LayoutKind = 'app' | 'auth' | 'blank' | 'fullscreen'
 
-  useBodyAttributes(page.extraBodyAttributes)
+function layoutKind(page: PageSchema): LayoutKind {
+  return page.layout === 'auth' || page.layout === 'blank' || page.layout === 'fullscreen'
+    ? page.layout
+    : 'app'
+}
+
+/** The layout `PanelLayoutHost` already renders around the page, if any. */
+const HostedLayoutContext = createContext<LayoutKind | null>(null)
+
+/** The page's registered layout (`layout:app`, `layout:auth`…) around `children`. */
+function PanelLayout({ page, children }: { page: PageSchema; children: ReactNode }) {
+  const { registry } = useAlfakit()
+  const kind = layoutKind(page)
 
   // Each layout can be replaced: createAlfakit({ components: { 'layout:app': MyLayout } }).
-  if (page.layout === 'auth') {
+  if (kind === 'auth') {
     return createElement(
       layout(registry, 'layout:auth'),
       { heading: page.heading ?? page.title, subheading: page.subheading, page },
@@ -169,33 +183,77 @@ export function PageShell({ page, children }: { page: PageSchema; children: Reac
     )
   }
 
-  if (page.layout === 'blank') {
-    return createElement(layout(registry, 'layout:blank'), { page }, children)
+  if (kind === 'app') {
+    return createElement(
+      layout(registry, 'layout:app'),
+      { breadcrumbs: page.breadcrumbs, maxContentWidth: page.maxContentWidth, page },
+      children,
+    )
   }
 
-  if (page.layout === 'fullscreen') {
-    return createElement(layout(registry, 'layout:fullscreen'), { page }, children)
-  }
+  return createElement(layout(registry, `layout:${kind}`), { page }, children)
+}
 
-  return createElement(
-    layout(registry, 'layout:app'),
-    { breadcrumbs: page.breadcrumbs, maxContentWidth: page.maxContentWidth, page },
-    <>
-      {/* `?` overlay, `/`, `g d` and panel command shortcuts (`keyboardShortcuts()`). */}
-      <KeyboardShortcuts />
-      <Slot name="page.start" />
-      <PageHeader page={page} />
-      {/* Edit pages: somebody else saved the record (`detectConflicts()`, `Panel::realtime()`). */}
-      {page.conflicts &&
-        createElement(registry.resolve('page:conflict-banner') ?? ConflictBanner, { page })}
-      {page.subNavigation ? (
-        <SubNavigationLayout navigation={page.subNavigation}>{children}</SubNavigationLayout>
-      ) : (
-        children
-      )}
-      <Slot name="page.end" />
-    </>,
+/**
+ * Keeps the panel layout (sidebar, top bar) mounted while the user moves between Alfakit
+ * pages. Inertia remounts the page component on every visit; this sits in the persistent
+ * Inertia layout (`AlfakitRoot`) and renders the open page's layout from its props, so only
+ * the page part below it (heading, actions, content) is replaced. The `PageShell` inside
+ * the page then renders just that part. Custom page components (their own Inertia page or
+ * `page.view`) and starter kit pages render their layout through `PageShell` as before.
+ */
+export function PanelLayoutHost({ children }: { children: ReactNode }) {
+  const { component, props } = usePage<AlfakitPageProps>()
+  const page = useMemo(
+    () => (props.page ? resolveLazyComponents(props.page, props.alfakitLazy) : undefined),
+    [props.page, props.alfakitLazy],
   )
+  const hosted =
+    component === 'Alfakit/Page' && page && !page.view && props.alfakit?.starterKit !== true
+      ? page
+      : undefined
+
+  return (
+    <HostedLayoutContext.Provider value={hosted ? layoutKind(hosted) : null}>
+      {hosted ? <PanelLayout page={hosted}>{children}</PanelLayout> : children}
+    </HostedLayoutContext.Provider>
+  )
+}
+
+export function PageShell({ page, children }: { page: PageSchema; children: ReactNode }) {
+  const { registry } = useAlfakit()
+  const hosted = useContext(HostedLayoutContext)
+  const kind = layoutKind(page)
+
+  useBodyAttributes(page.extraBodyAttributes)
+
+  const content =
+    kind === 'app' ? (
+      <>
+        {/* `?` overlay, `/`, `g d` and panel command shortcuts (`keyboardShortcuts()`). */}
+        <KeyboardShortcuts />
+        <Slot name="page.start" />
+        <PageHeader page={page} />
+        {/* Edit pages: somebody else saved the record (`detectConflicts()`, `Panel::realtime()`). */}
+        {page.conflicts &&
+          createElement(registry.resolve('page:conflict-banner') ?? ConflictBanner, { page })}
+        {page.subNavigation ? (
+          <SubNavigationLayout navigation={page.subNavigation}>{children}</SubNavigationLayout>
+        ) : (
+          children
+        )}
+        <Slot name="page.end" />
+      </>
+    ) : (
+      children
+    )
+
+  // The persistent layout around the page already draws this layout.
+  if (hosted === kind) {
+    return content
+  }
+
+  return <PanelLayout page={page}>{content}</PanelLayout>
 }
 
 export function PageHeader({ page }: { page: PageSchema }) {

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

@@ -52,7 +52,10 @@ export function SearchTrigger({ source, onLoad }: WidgetProps & { onLoad?: () =>
       <SearchIcon className="size-4" aria-hidden="true" />
       <span className="sr-only sm:not-sr-only sm:flex-1 sm:text-start">{placeholder}</span>
       {hydrated && binding && (
-        <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(binding)}
         </kbd>
       )}