@alfakit/react 0.0.0-stage → 0.1.0

package/src/create-alfakit.tsx

@@ -0,0 +1,300 @@
+import {
+  ActionRunner,
+  PANEL_TOAST_OFFSET,
+  Translator,
+  applyDocumentLocale,
+  applyPanelTheme,
+  configureCharts,
+  configureRealtime,
+  debugRecorder,
+  effectiveErrorNotifications,
+  initializeAppearance,
+  installErrorNotifications,
+  installPrefetchInvalidation,
+  installSpaUrlExceptions,
+  registerRichEditorExtensions,
+  reloadOnExpiredPage,
+  resolveRequestErrorNotification,
+  resolveToastPosition,
+  setRequestErrorReporter,
+  whenIdle,
+  type AlfakitOptions,
+  type AlfakitPageProps,
+  type ErrorNotificationsSchema,
+  type PanelSchema,
+} from '@alfakit/core'
+import type { InertiaAppSSRResponse, Page } from '@inertiajs/core'
+import { createInertiaApp, router, usePage } from '@inertiajs/react'
+import { Direction } from 'radix-ui'
+import {
+  StrictMode,
+  createElement,
+  useLayoutEffect,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { ActionModals } from './components/actions/action-modals'
+import { DevToolsSlot } from './components/dev-tools/dev-tools-slot'
+import { FlashToasts, showToast } from './components/notifications/flash-toasts'
+import { RealtimeNotifications } from './components/notifications/realtime-notifications'
+import { ImpersonationBanner } from './components/panel/impersonation-banner'
+import { PwaManager } from './components/panel/pwa'
+import { SchemaContractGuard } from './components/panel/schema-contract-guard'
+import { Toaster } from './components/ui/sonner'
+import { TooltipProvider } from './components/ui/tooltip'
+import { AlfakitProvider, useAlfakit, type AlfakitContextValue, type AnyComponent } from './context'
+import { discoverComponents } from './lib/discovery'
+import { preloadIcons } from './lib/icons'
+import { AlfakitPage } from './pages/page'
+import { builtInComponents, createDefaultRegistry } from './registry'
+
+/**
+ * Rendered inside Inertia's page tree, so it follows the current page: the reading
+ * direction for Radix primitives, modals and toasts.
+ */
+export function AlfakitRoot({
+  children,
+  toasterId,
+}: {
+  children: ReactNode
+  /** Starter kit mode: Alfakit's toaster gets an id so the host's id-less one never doubles its toasts. */
+  toasterId?: string
+}) {
+  const panel = usePage<AlfakitPageProps>().props.alfakit
+  const { translator, registry } = useAlfakit()
+  const localization = panel?.localization
+  const direction = localization?.direction ?? 'ltr'
+
+  // Every visit (including the redirect after a language switch) may carry new strings,
+  // so the translator is updated before children render.
+  if (panel) {
+    translator.setTranslations(panel.translations ?? {})
+    translator.setLocale(localization?.tag ?? 'en')
+  }
+
+  useLayoutEffect(() => {
+    applyDocumentLocale(localization)
+  }, [localization])
+
+  useLayoutEffect(() => {
+    applyPanelTheme(panel)
+  }, [panel])
+
+  return (
+    <Direction.Provider dir={direction}>
+      <TooltipProvider delayDuration={0}>
+        <SchemaContractGuard panel={panel}>{children}</SchemaContractGuard>
+        <ActionModals />
+        <FlashToasts />
+        <RealtimeNotifications />
+        {/* `Panel::pwa()`: service worker and the "new version" toast. */}
+        <PwaManager />
+        {/* Schema inspector: renders (and loads its code) only with `alfakitDevTools`. */}
+        <DevToolsSlot />
+        {/* Replace with createAlfakit({ components: { 'panel:impersonation-banner': … } }). */}
+        {panel?.impersonation &&
+          createElement(registry.resolve('panel:impersonation-banner') ?? ImpersonationBanner, {
+            impersonation: panel.impersonation,
+          })}
+        <Toaster
+          id={toasterId}
+          position={resolveToastPosition(panel?.toastPosition, direction)}
+          offset={PANEL_TOAST_OFFSET}
+          mobileOffset={PANEL_TOAST_OFFSET}
+          dir={direction}
+          richColors
+          closeButton
+        />
+      </TooltipProvider>
+    </Direction.Provider>
+  )
+}
+
+export interface CreateAlfakitOptions extends AlfakitOptions<AnyComponent> {
+  /** Wrap the whole app (e.g. with your own providers). */
+  withApp?: (app: ReactNode) => ReactNode
+  strictMode?: boolean
+}
+
+/** Renders one Inertia page to HTML: what `createInertiaApp` returns on the server. */
+export type AlfakitRenderFunction = (
+  page: Page,
+  renderToString: (element: ReactElement) => string,
+) => Promise<InertiaAppSSRResponse>
+
+/**
+ * The Inertia app shared by `createAlfakit()` (browser) and `createAlfakitServer()` (Node):
+ * the same registry, pages, layout and providers. In the browser it mounts, or hydrates
+ * server-rendered markup; on the server (no `window`) Inertia returns a render function.
+ */
+export function bootAlfakit(
+  options: CreateAlfakitOptions = {},
+): Promise<void | AlfakitRenderFunction> {
+  // Auto-registered files sit between the built-ins and the explicit `components` / `pages`.
+  const discovered = discoverComponents(options.discover)
+  const registry = createDefaultRegistry()
+    .registerMany(discovered.components)
+    .registerMany(options.components ?? {})
+  const pages: Record<string, AnyComponent> = {
+    'Alfakit/Page': AlfakitPage,
+    ...discovered.pages,
+    ...options.pages,
+  }
+  const isServer = typeof window === 'undefined'
+
+  // Every panel page draws named icons: fetch `lucide-react/dynamic` while booting.
+  preloadIcons()
+
+  // `'js:name'` chart option callbacks and Chart.js plugins for every chart widget.
+  configureCharts(options)
+  // `createAlfakit({ echo })`: Laravel Echo for `Panel::realtime()` without `window.Echo`.
+  if (options.echo !== undefined && !isServer) configureRealtime(null, { echo: options.echo })
+  // Rich content plugin extensions, loaded when an editor needs them.
+  registerRichEditorExtensions(options.richEditorExtensions ?? {})
+
+  // The browser's current panel, read by the SPA-exception and error-notification listeners.
+  let currentPanel: PanelSchema | null = null
+  // The open page's error notifications (its override, else the panel's).
+  let currentErrorNotifications: ErrorNotificationsSchema | false | undefined
+
+  // One translator and action runner for the browser session; a server render gets fresh
+  // ones per request so concurrent renders never share a locale or endpoints.
+  const createContext = (): AlfakitContextValue => {
+    const translator = new Translator()
+
+    return {
+      registry,
+      pages,
+      translator,
+      // The runner's endpoints are refreshed on every navigation from the shared props.
+      actions: new ActionRunner({
+        endpoints: { action: '', modal: '' },
+        // A failed action request is a toast, never a silent no-op.
+        onError: (error) => {
+          const notification = resolveRequestErrorNotification(
+            error,
+            currentErrorNotifications,
+            (key, replacements, fallback) => translator.t(key, replacements, fallback),
+          )
+
+          if (notification) showToast(notification)
+        },
+      }),
+    }
+  }
+
+  const browserContext = isServer ? null : createContext()
+
+  const sync = (context: AlfakitContextValue, page: Page, applyToDocument: boolean) => {
+    const props = page.props as unknown as AlfakitPageProps
+    const panel = props.alfakit
+
+    if (!panel) return
+
+    if (context === browserContext) {
+      currentPanel = panel
+      currentErrorNotifications = effectiveErrorNotifications(panel, props.page)
+    }
+
+    context.translator.setTranslations(panel.translations ?? {})
+    context.translator.setLocale(panel.localization?.tag ?? 'en')
+    context.actions.setEndpoints({
+      action: panel.endpoints.action ?? '',
+      modal: panel.endpoints.modal ?? '',
+    })
+
+    if (applyToDocument) {
+      applyDocumentLocale(panel.localization)
+      applyPanelTheme(panel)
+      // Internal requests and form stores are only recorded while the page carries the debug prop.
+      debugRecorder.setEnabled(props.alfakitDebug !== undefined)
+    }
+  }
+
+  if (browserContext) {
+    router.on('navigate', (event) => sync(browserContext, event.detail.page, true))
+    reloadOnExpiredPage()
+    // Prefetched pages and deferred table totals are dropped after every mutation.
+    installPrefetchInvalidation()
+    installSpaUrlExceptions(() => currentPanel)
+    installErrorNotifications(
+      () => ({ errorNotifications: currentErrorNotifications }),
+      (notification) => showToast(notification),
+    )
+    // Failed internal requests without their own handler (form live refreshes, step
+    // validation) show the configured error notification too.
+    setRequestErrorReporter((error) => {
+      const notification = resolveRequestErrorNotification(
+        error,
+        currentErrorNotifications,
+        (key, replacements, fallback) => browserContext.translator.t(key, replacements, fallback),
+      )
+
+      if (notification) showToast(notification)
+    })
+  }
+
+  return createInertiaApp<AlfakitPageProps>({
+    title: (title) => title,
+    progress: options.progress === undefined ? { color: 'var(--primary)' } : options.progress,
+    resolve: (name, page) => {
+      const component = pages[name]
+
+      if (!component) {
+        throw new Error(
+          `Alfakit: page component "${name}" is not registered. Pass it to createAlfakit({ pages }).`,
+        )
+      }
+
+      // The page's auto-registered components load first, so the server render and the
+      // hydration both show them (no flash, no mismatch).
+      // Built-ins split per type (`builtInComponents`) load the same way.
+      const pending = [
+        builtInComponents.preloadFor(page),
+        discovered.discovery.preloadFor(page),
+      ].filter((promise) => promise !== undefined)
+
+      return pending.length > 0 ? Promise.all(pending).then(() => component) : component
+    },
+    layout: () => AlfakitRoot,
+    strictMode: options.strictMode ?? true,
+    withApp: (app, { page, ssr }) => {
+      const context = browserContext ?? createContext()
+
+      sync(context, page as Page, !ssr)
+
+      // Panel pages only: other pages (`pages` option) follow the application's own dark
+      // mode, like standalone components do.
+      const panel = (page.props as unknown as Partial<AlfakitPageProps>).alfakit
+
+      if (!ssr && panel) {
+        initializeAppearance(panel)
+      }
+
+      const tree = <AlfakitProvider value={context}>{app}</AlfakitProvider>
+
+      const wrapped = options.withApp ? options.withApp(tree) : tree
+
+      return options.strictMode === false ? <>{wrapped}</> : <StrictMode>{wrapped}</StrictMode>
+    },
+  }) as Promise<void | AlfakitRenderFunction>
+}
+
+/**
+ * Boot the Alfakit panel frontend. Call once from your panel entry file. Markup rendered by
+ * `createAlfakitServer()` (`@alfakit/react/server`) is hydrated instead of re-rendered.
+ *
+ * ```tsx
+ * createAlfakit({
+ *   // Files in resources/js/alfakit/fields, columns, … register themselves.
+ *   discover: import.meta.glob('./{fields,columns,entries,widgets,pages,components,blocks}/**\/*.tsx'),
+ *   components: { 'map-picker': MapPicker },
+ * })
+ * ```
+ */
+export async function createAlfakit(options: CreateAlfakitOptions = {}): Promise<void> {
+  await bootAlfakit(options)
+
+  // After the first render: the remaining split built-ins (action modals' fields).
+  whenIdle(() => void builtInComponents.preloadAll())
+}

package/src/hooks/use-hydrated.ts

@@ -0,0 +1,16 @@
+import { useSyncExternalStore } from 'react'
+
+const subscribe = () => () => {}
+
+/**
+ * False during server rendering and hydration, true afterwards (and on a client-only
+ * render). Gate browser-dependent output on it, such as platform-specific shortcut hints,
+ * so server-rendered markup hydrates without a mismatch.
+ */
+export function useHydrated(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => true,
+    () => false,
+  )
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,29 @@
+import { useSyncExternalStore } from 'react'
+
+const MOBILE_BREAKPOINT = 768
+const QUERY = `(max-width: ${MOBILE_BREAKPOINT - 1}px)`
+
+function subscribe(onChange: () => void): () => void {
+  // Environments without matchMedia (some test runners) keep the desktop value.
+  if (typeof window.matchMedia !== 'function') {
+    return () => {}
+  }
+
+  const media = window.matchMedia(QUERY)
+
+  media.addEventListener('change', onChange)
+
+  return () => media.removeEventListener('change', onChange)
+}
+
+/**
+ * Whether the viewport is below the `md` breakpoint. Server rendering and hydration see
+ * `false` (desktop), so the markup matches; the browser value applies right after.
+ */
+export function useIsMobile(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => window.innerWidth < MOBILE_BREAKPOINT,
+    () => false,
+  )
+}

package/src/hooks/use-store.ts

@@ -0,0 +1,18 @@
+import type { Store } from '@alfakit/core'
+import { useSyncExternalStore } from 'react'
+
+/** Subscribe a React component to a core store. */
+export function useStore<T>(store: Pick<Store<T>, 'get' | 'subscribe'>): T {
+  return useSyncExternalStore(store.subscribe, store.get, store.get)
+}
+
+export function useStoreSelector<T, U>(
+  store: Pick<Store<T>, 'get' | 'subscribe'>,
+  selector: (state: T) => U,
+): U {
+  return useSyncExternalStore(
+    store.subscribe,
+    () => selector(store.get()),
+    () => selector(store.get()),
+  )
+}

package/src/hooks/use-virtual-list.ts

@@ -0,0 +1,88 @@
+import type { VirtualListOptions, VirtualRange } from '@alfakit/core'
+import { VirtualList, firstErroredItemIndex, hasNewErrors } from '@alfakit/core'
+import { useCallback, useEffect, useMemo, useRef, type CSSProperties } from 'react'
+import { useOptionalFormStore } from '../components/form/form-context'
+import { useStore, useStoreSelector } from './use-store'
+
+export interface VirtualListBinding {
+  list: VirtualList
+  range: VirtualRange
+  /** The indexes to render, in order. */
+  indexes: number[]
+  /** Reserve the space of the items outside the window (for a `<ul>`; tables use spacer rows). */
+  style: CSSProperties | undefined
+  /** Ref callback for the list element (`<ul>`, `<tbody>`). */
+  attach: (element: HTMLElement | null) => void | (() => void)
+  /** Ref callback for an item element; the item's `data-index` attribute names its index. */
+  item: (element: HTMLElement | null) => void | (() => void)
+}
+
+/**
+ * Window a long list: render `indexes` only, give the list element `ref={attach}` and
+ * `style`, and each item `ref={item}` plus `data-index={index}`. Below the threshold
+ * everything renders as usual. Destructure the result: the React Compiler lint treats an
+ * object whose member is passed to `ref` as a ref, and refuses to read it during render.
+ */
+export function useVirtualList(count: number, options: VirtualListOptions): VirtualListBinding {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const list = useMemo(() => new VirtualList(options), [])
+
+  useStore(list.store)
+
+  useEffect(() => {
+    list.configure(options)
+  }, [list, options.threshold, options.estimateSize, options.overscan, options.gap]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const range = list.range(count)
+  const attach = useCallback(
+    (element: HTMLElement | null) => (element ? list.attach(element) : undefined),
+    [list],
+  )
+  const item = useCallback(
+    (element: HTMLElement | null) => {
+      if (!element) return undefined
+
+      const index = Number(element.dataset.index)
+      list.register(index, element)
+
+      return () => list.register(index, null)
+    },
+    [list],
+  )
+
+  return {
+    list,
+    range,
+    indexes: list.indexes(count),
+    style: range.active ? { paddingTop: range.before, paddingBottom: range.after } : undefined,
+    attach,
+    item,
+  }
+}
+
+/**
+ * When a submit or live validation adds errors inside a virtualised Repeater or Builder,
+ * scroll the first errored item into view (it may be outside the rendered window).
+ */
+export function useScrollToErroredItem(
+  list: VirtualList,
+  active: boolean,
+  statePath: string,
+): void {
+  const store = useOptionalFormStore()
+  const errors = useStoreSelector(store?.store ?? EMPTY_STORE, (state) => state.errors)
+  const previous = useRef(errors)
+
+  useEffect(() => {
+    if (active && hasNewErrors(previous.current, errors)) {
+      const index = firstErroredItemIndex(statePath, errors)
+
+      if (index !== null) list.scrollToIndex(index)
+    }
+
+    previous.current = errors
+  }, [errors, statePath, list, active])
+}
+
+const NO_ERRORS = { errors: {} as Record<string, string[]> }
+const EMPTY_STORE = { get: () => NO_ERRORS, subscribe: () => () => {} }

package/src/index.ts

@@ -0,0 +1,135 @@
+export * from '@alfakit/core'
+export {
+  AppPage,
+  PageBlock,
+  PageForm,
+  PageInfolist,
+  PageTable,
+  PageWidgets,
+  useAppPage,
+  usePageBlock,
+  type PageBlockProps,
+} from './app/components'
+export {
+  useLiveProps,
+  usePageForm,
+  usePageMethod,
+  usePageMethods,
+  useReloadProps,
+  useShortcut,
+  type PageMethodBinding,
+  type PageMethodMap,
+  type PageMethodsBinding,
+  type UsePageMethodOptions,
+} from './app/hooks'
+export {
+  ActionButton,
+  ActionGroupMenu,
+  ActionList,
+  ActionModals,
+  PageActionProvider,
+  usePageActionContext,
+} from './components/actions'
+export * from './components/ai'
+export * from './components/analytics'
+export * from './components/cms'
+export * from './components/entries'
+export * from './components/fields'
+export * from './components/file-manager'
+export { FormBlock } from './components/form/form-block'
+export {
+  FormProvider,
+  useField,
+  useFormState,
+  useFormStore,
+  useOptionalFormStore,
+  type FieldBinding,
+} from './components/form/form-context'
+export * from './components/helpdesk'
+export * from './components/kanban'
+export * from './components/layout'
+export * from './components/notifications'
+export * from './components/panel'
+export * from './components/realtime'
+export { FieldWrapper } from './components/schema/field-wrapper'
+export { RenderComponent, SchemaRenderer } from './components/schema/schema-renderer'
+export * from './components/table'
+export * from './components/translation-manager'
+export * from './components/tree'
+export { RecordVersionsComponent } from './components/versions/record-versions'
+export * from './components/widgets'
+export {
+  AlfakitProvider,
+  StandaloneProvider,
+  useActionRunner,
+  useAlfakit,
+  useAlfakitProps,
+  useChoice,
+  useDirection,
+  useFormatter,
+  useLocalization,
+  useOptionalAlfakit,
+  usePageSchema,
+  usePanel,
+  usePollComponent,
+  useRegistry,
+  useStandalone,
+  useT,
+  type AlfakitContextValue,
+  type AnyComponent,
+  type StandaloneContextValue,
+} from './context'
+export { createAlfakit, type CreateAlfakitOptions } from './create-alfakit'
+export { useHydrated } from './hooks/use-hydrated'
+export { useIsMobile } from './hooks/use-mobile'
+export { useStore, useStoreSelector } from './hooks/use-store'
+export {
+  useScrollToErroredItem,
+  useVirtualList,
+  type VirtualListBinding,
+} from './hooks/use-virtual-list'
+export { AppLayout } from './layouts/app-layout'
+export { AuthLayout } from './layouts/auth-layout'
+export { BlankLayout } from './layouts/blank-layout'
+export { FullscreenLayout, type FullscreenLayoutProps } from './layouts/fullscreen-layout'
+export { TopNavLayout } from './layouts/top-nav-layout'
+export { extraProps, parseStyle } from './lib/attributes'
+export * from './lib/colors'
+export { discoverComponents, discoveredComponent, type DiscoveredComponents } from './lib/discovery'
+export { Icon } from './lib/icons'
+export { cn } from './lib/utils'
+export { AlfakitPage, ContentBlockRenderer, PageContent, PageHeader, PageShell } from './pages/page'
+export { createDefaultRegistry } from './registry'
+export * from './standalone'
+export * from './starter-kit'
+
+// shadcn/ui primitives, so applications can build custom components in the same style.
+export * from './components/ui/alert'
+export * from './components/ui/avatar'
+export * from './components/ui/badge'
+export * from './components/ui/breadcrumb'
+export * from './components/ui/button'
+export * from './components/ui/calendar'
+export * from './components/ui/card'
+export * from './components/ui/checkbox'
+export * from './components/ui/collapsible'
+export * from './components/ui/command'
+export * from './components/ui/dialog'
+export * from './components/ui/dropdown-menu'
+export * from './components/ui/input'
+export * from './components/ui/label'
+export * from './components/ui/popover'
+export * from './components/ui/radio-group'
+export * from './components/ui/scroll-area'
+export * from './components/ui/select'
+export * from './components/ui/separator'
+export * from './components/ui/sheet'
+export * from './components/ui/sidebar'
+export * from './components/ui/skeleton'
+export * from './components/ui/sonner'
+export * from './components/ui/spinner'
+export * from './components/ui/switch'
+export * from './components/ui/table'
+export * from './components/ui/tabs'
+export * from './components/ui/textarea'
+export * from './components/ui/tooltip'