@alfakit/react 0.1.12 → 0.2.0

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/standalone/runtime.ts

@@ -95,20 +95,8 @@ export function createStandaloneContext(
 
 // ---------------------------------------------------------------- Toaster ownership
 
-let toasters = 0
-
-/** An `<AlfakitToaster>` (or the component that took the role) is mounted; returns a release. */
-export function claimToaster(): () => void {
-  toasters++
-
-  return () => {
-    toasters--
-  }
-}
-
-export function hasToaster(): boolean {
-  return toasters > 0
-}
+// In a module of its own: the starter kit header components check it without loading this one.
+export { claimToaster, hasToaster } from './toaster-claims'
 
 // ---------------------------------------------------------------- Flashed notifications
 

package/src/standalone/toaster-claims.ts

@@ -0,0 +1,16 @@
+// Who renders AlfaKit's toaster on the page: `<AlfakitToaster>`, `AlfakitRoot`, the first
+// standalone component or the starter kit header components on the host's own pages.
+let toasters = 0
+
+/** An `<AlfakitToaster>` (or the component that took the role) is mounted; returns a release. */
+export function claimToaster(): () => void {
+  toasters++
+
+  return () => {
+    toasters--
+  }
+}
+
+export function hasToaster(): boolean {
+  return toasters > 0
+}

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

@@ -1,12 +1,15 @@
 import {
   ActionRunner,
   ComponentRegistry,
+  STARTER_KIT_TOASTER_ID,
   Translator,
   initials,
   isAlfakitPage,
   loadStarterKitPanel,
   loadedStarterKitPanel,
   openRequestedStarterKitSearch,
+  overlayPlacementDirection,
+  resolveToastPosition,
   showsLanguageSwitcher,
   starterKitCopilot,
   starterKitPanelLocale,
@@ -17,12 +20,15 @@ import {
   tenantNameText,
   type PanelSchema,
   type StarterKitWidgets,
+  type ToastPosition,
 } from '@alfakit/core'
 import { router, usePage } from '@inertiajs/react'
 import { ChevronsUpDownIcon, LanguagesIcon, PlusIcon } from 'lucide-react'
 import { Direction } from 'radix-ui'
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
 import { AiCopilot } from '../components/ai/copilot'
+import { setToasterId } from '../components/notifications/flash-toasts'
 import { NotificationsMenu } from '../components/notifications/notifications-menu'
 import { RealtimeNotifications } from '../components/notifications/realtime-notifications'
 import { GlobalSearch } from '../components/panel/global-search'
@@ -38,16 +44,20 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from '../components/ui/dropdown-menu'
+import { Toaster } from '../components/ui/sonner'
 import { TooltipProvider } from '../components/ui/tooltip'
 import {
   AlfakitProvider,
   StandaloneProvider,
   useLocalization,
+  useRegistry,
   useT,
   type AlfakitContextValue,
   type AnyComponent,
 } from '../context'
 import { Icon } from '../lib/icons'
+import { ensureFlashToasts } from '../standalone/runtime'
+import { claimToaster, hasToaster } from '../standalone/toaster-claims'
 import {
   CopilotTrigger,
   LanguageSwitcherTrigger,
@@ -117,16 +127,89 @@ function useWidgetsPanel(source: StarterKitWidgets): PanelSchema | null {
   )
 }
 
+/**
+ * AlfaKit's toaster on a host page (as `<AlfakitToaster>`, without its standalone context):
+ * Alfakit's toasts go to it, and so do flashed notifications.
+ */
+function HostToaster({ position, dir }: { position?: ToastPosition; dir: 'ltr' | 'rtl' }) {
+  const registry = useRegistry()
+
+  useEffect(() => {
+    ensureFlashToasts(registry)
+  }, [registry])
+
+  useEffect(() => {
+    setToasterId(STARTER_KIT_TOASTER_ID)
+
+    return () => setToasterId(undefined)
+  }, [])
+
+  return (
+    <Toaster
+      id={STARTER_KIT_TOASTER_ID}
+      position={resolveToastPosition(position, dir)}
+      dir={dir}
+      richColors
+      closeButton
+    />
+  )
+}
+
+/**
+ * On the host's own pages no AlfaKit toaster is mounted, so the first loaded header
+ * component renders one: the push toggle's and the PWA's messages show there too (W-S1-03).
+ * AlfaKit pages (`AlfakitRoot`) and standalone components claim it themselves; the check
+ * runs after every component's effects, and again after each visit.
+ */
+function useOwnsHostToaster(): boolean {
+  const alfakitPage = isAlfakitPage(usePage().props)
+  const [owns, setOwns] = useState(false)
+
+  useEffect(() => {
+    if (alfakitPage) return undefined
+
+    let release: (() => void) | null = null
+    let cancelled = false
+
+    queueMicrotask(() => {
+      if (cancelled || hasToaster()) return
+
+      release = claimToaster()
+      setOwns(true)
+    })
+
+    return () => {
+      cancelled = true
+      release?.()
+      setOwns(false)
+    }
+  }, [alfakitPage])
+
+  return owns && !alfakitPage
+}
+
 function WidgetShell({ panel, children }: { panel: PanelSchema; children: ReactNode }) {
   const context = useWidgetsContext(panel)
   const page = useMemo(() => starterKitWidgetsPage(), [])
+  const ownsToaster = useOwnsHostToaster()
+  const direction = panel.localization?.direction ?? 'ltr'
 
   return (
     <AlfakitProvider value={context}>
       <StandaloneProvider value={{ panel, page }}>
-        <Direction.Provider dir={panel.localization?.direction ?? 'ltr'}>
+        <Direction.Provider dir={direction}>
           <TooltipProvider delayDuration={0}>{children}</TooltipProvider>
         </Direction.Provider>
+        {/* In the body, not in the header (a header with a backdrop filter would hold its
+            fixed position), placed in the document's direction as on AlfaKit pages. */}
+        {ownsToaster &&
+          createPortal(
+            <HostToaster
+              position={panel.toastPosition}
+              dir={overlayPlacementDirection(direction, true)}
+            />,
+            document.body,
+          )}
       </StandaloneProvider>
     </AlfakitProvider>
   )

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>
       )}