@alfakit/react 0.0.0-stage → 0.1.1

package/src/standalone/alfakit-component.tsx

@@ -0,0 +1,222 @@
+import {
+  StandaloneComponentState,
+  findStandalonePropName,
+  registerStandaloneProp,
+  standalonePanelSchema,
+  type ContentBlock,
+  type StandaloneComponentSchema,
+} from '@alfakit/core'
+import { usePage } from '@inertiajs/react'
+import { Direction } from 'radix-ui'
+import { useEffect, 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'
+import { TooltipProvider } from '../components/ui/tooltip'
+import {
+  AlfakitProvider,
+  StandaloneProvider,
+  useOptionalAlfakit,
+  type AlfakitContextValue,
+  type AnyComponent,
+} from '../context'
+import { cn } from '../lib/utils'
+import { ContentBlockRenderer } from '../pages/page'
+import { AlfakitToaster } from './alfakit-toaster'
+import {
+  claimToaster,
+  createStandaloneContext,
+  createStandaloneRegistry,
+  ensureStandaloneRuntime,
+  hasToaster,
+} from './runtime'
+
+export interface AlfakitComponentProps {
+  /** The payload: `ContactForm::make()` passed as an Inertia prop. */
+  component: StandaloneComponentSchema
+  /** Renderer overrides for this instance (`{ TextInput: MyInput }`), on top of `configureAlfakit()`. */
+  components?: Record<string, AnyComponent>
+  className?: string
+  /** Rendered above the content blocks (after the heading and actions). */
+  header?: ReactNode
+  /** Rendered below the content blocks. */
+  footer?: ReactNode
+  /** Render each content block yourself (e.g. to lay a form and a table side by side). */
+  children?: (blocks: ContentBlock[], render: (block: ContentBlock) => ReactNode) => ReactNode
+}
+
+/**
+ * Renders an Alfakit component outside a panel: a form, table, infolist, widgets or any mix
+ * (`AlfaSix\Alfakit\Standalone\*`) in any Inertia page of the application. Needs no
+ * `createAlfakit()` and no panel layout: it provides its own translator, registry, action
+ * runner and modals, and inherits the application's shadcn tokens.
+ *
+ * ```tsx
+ * <AlfakitComponent component={orders} className="max-w-4xl" />
+ * ```
+ */
+export function AlfakitComponent({
+  component,
+  components,
+  className,
+  header,
+  footer,
+  children,
+}: AlfakitComponentProps) {
+  const parent = useOptionalAlfakit()
+  const props = useOptionalPageProps()
+  const [, setVersion] = useState(0)
+  // The registry overrides are an object literal in JSX: compare them by their keys.
+  const overrideKeys = Object.keys(components ?? {}).join(',')
+
+  // Lazy and polled schemas of this component, merged into the page it renders.
+  const state = useMemo(
+    () => new StandaloneComponentState(component, () => setVersion((value) => value + 1)),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+  state.setComponent(component)
+
+  const context = useMemo<AlfakitContextValue>(() => {
+    const poll = (target: string, interval: string | number | null | undefined) =>
+      state.poll(target, interval)
+
+    if (parent) {
+      return { ...parent, registry: createStandaloneRegistry(components, parent.registry), poll }
+    }
+
+    return createStandaloneContext(
+      { action: component.endpoints.action, modal: component.endpoints.modal },
+      components,
+      poll,
+    )
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [parent, state, overrideKeys])
+
+  // Endpoints follow the latest payload (they change per locale or path).
+  context.actions.setEndpoints({
+    action: component.endpoints.action,
+    modal: component.endpoints.modal,
+  })
+
+  // Inside `createAlfakit()` the panel feeds the shared translator; on a page without the
+  // `alfakit` prop (the rest of the app) the component's own translations apply.
+  const ownsTranslator = !parent || !props?.alfakit
+
+  if (ownsTranslator) {
+    context.translator.setTranslations(component.translations ?? {})
+    context.translator.setLocale(component.localization?.tag ?? 'en')
+  }
+
+  const panel = useMemo(() => standalonePanelSchema(component), [component])
+  const page = state.page
+  const direction = component.localization?.direction ?? 'ltr'
+
+  useEffect(() => {
+    ensureStandaloneRuntime()
+  }, [])
+
+  // Partial reloads (sorting, paging, inline edits) request this component's own prop.
+  const propName = findStandalonePropName(props, component)
+
+  useEffect(() => registerStandaloneProp(propName ?? null), [propName])
+
+  useEffect(() => {
+    void state.loadLazy()
+  }, [state, component.token])
+
+  // Toasts: use the layout's <AlfakitToaster /> when there is one, else the first component
+  // on the page renders one (checked after every component's effects ran).
+  const [ownsToaster, setOwnsToaster] = useState(false)
+
+  useEffect(() => {
+    if (parent) return
+
+    let release: (() => void) | null = null
+    let cancelled = false
+
+    queueMicrotask(() => {
+      if (cancelled || hasToaster()) return
+
+      release = claimToaster()
+      setOwnsToaster(true)
+    })
+
+    return () => {
+      cancelled = true
+      release?.()
+    }
+  }, [parent])
+
+  const render = (block: ContentBlock) => <ContentBlockRenderer key={block.key} block={block} />
+  const actionContext = useMemo(
+    () => ({ token: component.token, component: 'page' }),
+    [component.token],
+  )
+
+  const body = (
+    <PageActionProvider value={actionContext}>
+      <div
+        data-slot="standalone"
+        data-alfakit-component={component.class}
+        dir={direction}
+        className={cn('flex flex-col gap-6', className)}
+      >
+        {(page.heading || page.headerActions?.length) && (
+          <header
+            data-slot="page-header"
+            className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between"
+          >
+            <div className="min-w-0">
+              {page.heading && (
+                <h2 className="text-xl font-semibold tracking-tight">{page.heading}</h2>
+              )}
+              {page.subheading && (
+                <p className="text-muted-foreground mt-1 text-sm">{page.subheading}</p>
+              )}
+            </div>
+            {page.headerActions && page.headerActions.length > 0 && (
+              <ActionList
+                actions={page.headerActions}
+                context={actionContext}
+                align="end"
+                className="max-w-full shrink-0"
+              />
+            )}
+          </header>
+        )}
+        {header}
+        {children ? children(page.content, render) : page.content.map(render)}
+        {footer}
+      </div>
+      <ActionModals />
+      {ownsToaster && <AlfakitToaster claimed />}
+    </PageActionProvider>
+  )
+
+  return (
+    <AlfakitProvider value={context}>
+      <StandaloneProvider value={{ panel, page }}>
+        {parent ? (
+          body
+        ) : (
+          <Direction.Provider dir={direction}>
+            <TooltipProvider delayDuration={0}>{body}</TooltipProvider>
+          </Direction.Provider>
+        )}
+      </StandaloneProvider>
+    </AlfakitProvider>
+  )
+}
+
+/**
+ * The host page's Inertia props, or undefined when rendered outside an Inertia app (a
+ * component test, Storybook, a plain server render): partial reloads then reload every prop.
+ */
+function useOptionalPageProps(): Record<string, unknown> | undefined {
+  try {
+    return usePage().props as Record<string, unknown>
+  } catch {
+    return undefined
+  }
+}

package/src/standalone/alfakit-toaster.tsx

@@ -0,0 +1,52 @@
+import { resolveToastPosition, type ToastPosition } from '@alfakit/core'
+import { useEffect, useMemo } from 'react'
+import { Toaster } from '../components/ui/sonner'
+import { useOptionalAlfakit, type AlfakitContextValue } from '../context'
+import { claimToaster, createStandaloneContext, ensureFlashToasts } from './runtime'
+
+export interface AlfakitToasterProps {
+  /** Where toasts appear; `start`/`end` follow the reading direction. */
+  position?: ToastPosition
+  dir?: 'ltr' | 'rtl'
+  /**
+   * Render sonner's `<Toaster>` too (default). Pass `false` when your layout already mounts
+   * one: flashed Alfakit notifications are then shown through it.
+   */
+  toaster?: boolean
+  /** @internal Set by `<AlfakitComponent>` when it takes the toaster role. */
+  claimed?: boolean
+}
+
+/**
+ * Shows notifications flashed by standalone components (`Notification::make()->send()`
+ * from `submit()` or an action) as toasts. Place it once in your app layout; a page whose
+ * layout has none gets one from its first `<AlfakitComponent>`.
+ *
+ * ```tsx
+ * <AlfakitToaster />
+ * ```
+ */
+export function AlfakitToaster({
+  position,
+  dir = 'ltr',
+  toaster = true,
+  claimed = false,
+}: AlfakitToasterProps) {
+  const parent = useOptionalAlfakit()
+
+  // Outside <AlfakitComponent> the flash reader needs a registry for custom toast views.
+  const context = useMemo<AlfakitContextValue>(
+    () => parent ?? createStandaloneContext({ action: '', modal: '' }, undefined, undefined),
+    [parent],
+  )
+
+  useEffect(() => (claimed ? undefined : claimToaster()), [claimed])
+
+  useEffect(() => {
+    ensureFlashToasts(context.registry)
+  }, [context])
+
+  if (!toaster) return null
+
+  return <Toaster position={resolveToastPosition(position, dir)} dir={dir} richColors closeButton />
+}

package/src/standalone/configure.ts

@@ -0,0 +1,24 @@
+import type { StandaloneDefaults } from '@alfakit/core'
+import type { AnyComponent } from '../context'
+
+let defaults: StandaloneDefaults<AnyComponent> = {}
+
+/**
+ * Global defaults for every `<AlfakitComponent>` of the application, for pages outside a
+ * panel (no `createAlfakit()`). Call it once in your app entry:
+ *
+ * ```tsx
+ * configureAlfakit({ components: { TextInput: MyInput, 'map-picker': MapPicker } })
+ * ```
+ */
+export function configureAlfakit(options: StandaloneDefaults<AnyComponent>): void {
+  defaults = {
+    ...defaults,
+    ...options,
+    components: { ...defaults.components, ...options.components },
+  }
+}
+
+export function getStandaloneDefaults(): StandaloneDefaults<AnyComponent> {
+  return defaults
+}

package/src/standalone/index.ts

@@ -0,0 +1,3 @@
+export { AlfakitComponent, type AlfakitComponentProps } from './alfakit-component'
+export { AlfakitToaster, type AlfakitToasterProps } from './alfakit-toaster'
+export { configureAlfakit } from './configure'

package/src/standalone/runtime.ts

@@ -0,0 +1,153 @@
+import {
+  ActionRunner,
+  ComponentRegistry,
+  FlashNotificationTracker,
+  Translator,
+  reloadOnExpiredPage,
+  resolveRequestErrorNotification,
+  type NotificationSchema,
+} from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import { showToast } from '../components/notifications/flash-toasts'
+import type { AlfakitContextValue, AnyComponent } from '../context'
+import { createDefaultRegistry } from '../registry'
+import { getStandaloneDefaults } from './configure'
+
+const isServer = typeof window === 'undefined'
+
+// Translations are the same for every component of a page, so the browser shares one
+// translator; a server render gets its own so concurrent requests never share a locale.
+const browserTranslator = isServer ? null : new Translator()
+
+let browserReady = false
+
+/** Browser-wide listeners every panel app installs; once per page load. */
+export function ensureStandaloneRuntime(): void {
+  if (isServer || browserReady) return
+
+  browserReady = true
+  reloadOnExpiredPage()
+}
+
+/**
+ * The registry of a standalone component: the built-in renderers, the `configureAlfakit()`
+ * defaults (or the surrounding panel's registry), then the component's own overrides.
+ */
+export function createStandaloneRegistry(
+  overrides?: Record<string, AnyComponent>,
+  base?: ComponentRegistry<AnyComponent>,
+): ComponentRegistry<AnyComponent> {
+  if (!base) {
+    return createDefaultRegistry()
+      .registerMany(getStandaloneDefaults().components ?? {})
+      .registerMany(overrides ?? {})
+  }
+
+  if (!overrides || Object.keys(overrides).length === 0) {
+    return base
+  }
+
+  const registry = new ComponentRegistry<AnyComponent>()
+
+  for (const type of base.types()) {
+    const component = base.resolve(type)
+
+    if (component) registry.register(type, component)
+  }
+
+  return registry.registerMany(overrides)
+}
+
+/**
+ * The context value of one `<AlfakitComponent>` rendered outside `createAlfakit()`: its
+ * own registry and action runner (so its modals are its own), the shared translator.
+ */
+export function createStandaloneContext(
+  endpoints: { action: string; modal: string },
+  overrides: Record<string, AnyComponent> | undefined,
+  poll: AlfakitContextValue['poll'],
+): AlfakitContextValue {
+  const translator = browserTranslator ?? new Translator()
+
+  return {
+    registry: createStandaloneRegistry(overrides),
+    pages: {},
+    translator,
+    actions: new ActionRunner({
+      endpoints: { ...endpoints },
+      // Outside a panel there is no `errorNotifications` config: a generic toast.
+      onError: (error) => {
+        const notification = resolveRequestErrorNotification(
+          error,
+          null,
+          (key, replacements, fallback) => translator.t(key, replacements, fallback),
+        )
+
+        if (notification) showToast(notification)
+      },
+    }),
+    poll,
+  }
+}
+
+// ---------------------------------------------------------------- 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
+}
+
+// ---------------------------------------------------------------- Flashed notifications
+
+const flashTracker = new FlashNotificationTracker()
+let flashRegistry: ComponentRegistry<AnyComponent> | null = null
+let flashListening = false
+
+/**
+ * Show the notifications the server flashed (`Notification::make()->send()`), from the
+ * `flash` Inertia event after each visit and from the initial page (whose event fired
+ * before the app mounted). One listener per page load, so it survives layouts that remount
+ * between visits; the registry of the last mounted toaster renders custom toast views.
+ */
+export function ensureFlashToasts(registry: ComponentRegistry<AnyComponent>): void {
+  flashRegistry = registry
+
+  if (isServer || flashListening) return
+
+  flashListening = true
+
+  const show = (flash: unknown) => {
+    const flashed = (flash as { alfakitNotifications?: NotificationSchema[] } | undefined)
+      ?.alfakitNotifications
+
+    for (const notification of flashTracker.fresh(flashed)) {
+      showToast(notification, flashRegistry?.resolve(notification.view ?? ''))
+    }
+  }
+
+  show(initialFlash())
+  router.on('flash', (event) => show(event.detail.flash))
+}
+
+/** The initial page's flash data (fired as an event before the app mounted). */
+export function initialFlash(): unknown {
+  if (isServer) return undefined
+
+  try {
+    const page = document.querySelector<HTMLElement>('[data-page]')?.dataset.page
+
+    return page ? (JSON.parse(page) as { flash?: unknown }).flash : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/starter-kit/index.ts

@@ -0,0 +1,14 @@
+export { useAlfakitNavigation, type AlfakitNavigation } from './navigation'
+export {
+  AlfakitStarterKitRoot,
+  StarterKitContentLayout,
+  createStarterKitPage,
+  type StarterKitLayout,
+  type StarterKitPageOptions,
+} from './starter-kit'
+export {
+  AlfakitNotifications,
+  AlfakitSearch,
+  AlfakitTenantSwitcher,
+  type AlfakitHeaderWidgetProps,
+} from './widgets'

package/src/starter-kit/navigation.ts

@@ -0,0 +1,34 @@
+import {
+  starterKitNavigation,
+  toStarterKitNavGroups,
+  type StarterKitNavGroup,
+  type StarterKitNavigationSchema,
+} from '@alfakit/core'
+import { usePage } from '@inertiajs/react'
+import { useMemo } from 'react'
+
+export interface AlfakitNavigation {
+  /** The panel's navigation as the server shared it, or null for guests. */
+  navigation: StarterKitNavigationSchema | null
+  /** Its groups as plain items (`title`, `href`, `icon`, `isActive`, `badge`, `children`). */
+  groups: StarterKitNavGroup[]
+}
+
+/**
+ * The navigation of a `starterKit()` panel (the first one unless `panelId` is given), for the
+ * host's sidebar. Every Inertia page of the application carries it, so the host's own pages
+ * list the panel's resources too.
+ *
+ * ```tsx
+ * const { groups } = useAlfakitNavigation()
+ * ```
+ */
+export function useAlfakitNavigation(panelId?: string): AlfakitNavigation {
+  const props = usePage().props
+  const navigation = starterKitNavigation(props, panelId)
+
+  return useMemo(
+    () => ({ navigation, groups: toStarterKitNavGroups(navigation?.groups) }),
+    [navigation],
+  )
+}