@alfakit/react 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,131 @@
 {
   "name": "@alfakit/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React + shadcn/ui renderer for Alfakit, the Laravel admin panel builder by Alfa Six.",
+  "license": "MIT",
+  "author": "Alfa Six (https://alfasixbh.com)",
+  "homepage": "https://alfakit.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alfasixbh/alfakit",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/alfasixbh/alfakit/issues",
+  "keywords": [
+    "laravel",
+    "inertia",
+    "react",
+    "shadcn",
+    "admin",
+    "panel",
+    "alfakit"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./starter-kit": {
+      "types": "./dist/starter-kit/index.d.ts",
+      "import": "./dist/starter-kit/index.js"
+    },
+    "./kanban": {
+      "types": "./dist/components/kanban/index.d.ts",
+      "import": "./dist/components/kanban/index.js"
+    },
+    "./cms": {
+      "types": "./dist/components/cms/index.d.ts",
+      "import": "./dist/components/cms/index.js"
+    },
+    "./translation-manager": {
+      "types": "./dist/components/translation-manager/index.d.ts",
+      "import": "./dist/components/translation-manager/index.js"
+    },
+    "./ai": {
+      "types": "./dist/components/ai/index.d.ts",
+      "import": "./dist/components/ai/index.js"
+    },
+    "./tree": {
+      "types": "./dist/components/tree/index.d.ts",
+      "import": "./dist/components/tree/index.js"
+    },
+    "./realtime": {
+      "types": "./dist/components/realtime/index.d.ts",
+      "import": "./dist/components/realtime/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./standalone.css": "./dist/standalone.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@fullcalendar/core": "^6.1.21",
+    "@fullcalendar/daygrid": "^6.1.21",
+    "@fullcalendar/interaction": "^6.1.21",
+    "@fullcalendar/list": "^6.1.21",
+    "@fullcalendar/timegrid": "^6.1.21",
+    "@tiptap/extension-image": "^3.31.4",
+    "@tiptap/extension-link": "^3.31.4",
+    "@tiptap/extension-placeholder": "^3.31.4",
+    "@tiptap/extension-table": "^3.31.4",
+    "@tiptap/react": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4",
+    "chart.js": "^4.5.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "lucide-react": "^1.52.0",
+    "radix-ui": "^1.7.0",
+    "react-day-picker": "^10.0.2",
+    "sonner": "^2.0.8",
+    "tailwind-merge": "^3.7.0",
+    "@alfakit/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@inertiajs/react": "^3.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@inertiajs/react": "^3.8.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "jsdom": "^30.1.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.3.3",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown && node ../../scripts/eject-manifest.mjs .",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/app/components.tsx

@@ -0,0 +1,104 @@
+import { resolveLazyComponents, type ContentBlock, type PageSchema } from '@alfakit/core'
+import { Head } from '@inertiajs/react'
+import { useMemo, type ReactNode } from 'react'
+import { PageActionProvider } from '../components/actions/action-context'
+import { useAlfakitProps, usePageSchema, usePanel } from '../context'
+import { cn } from '../lib/utils'
+import { ContentBlockRenderer, PageShell } from '../pages/page'
+
+/**
+ * Building blocks for custom page components: the page shell with the panel layout, and the
+ * page's PHP-defined pieces rendered by name, with live fields, actions, uploads and polling
+ * working exactly as on schema-driven pages.
+ */
+
+/** The current page with its lazy components resolved. */
+export function useAppPage(): PageSchema | undefined {
+  const props = useAlfakitProps()
+  const page = usePageSchema()
+
+  return useMemo(
+    () => (page ? resolveLazyComponents(page, props.alfakitLazy) : undefined),
+    [page, props.alfakitLazy],
+  )
+}
+
+/** A content block of the page by key (`form:customer`, `table`, `headerWidgets`…). */
+export function usePageBlock(key: string): ContentBlock | undefined {
+  const page = useAppPage()
+
+  return page?.content.find((block) => block.key === key)
+}
+
+/**
+ * The page's layout (sidebar and topbar, `fullscreen`…), heading, header actions and
+ * document title around a custom component:
+ *
+ * ```tsx
+ * export default function Pos(props: PosProps) {
+ *   return <AppPage>…</AppPage>
+ * }
+ * ```
+ */
+export function AppPage({ children }: { children: ReactNode }) {
+  const page = useAppPage()
+  const panel = usePanel()
+
+  if (!page) return <>{children}</>
+
+  return (
+    <PageActionProvider value={{ token: page.token, component: 'page' }}>
+      <Head title={`${page.title} - ${panel.brandName}`} />
+      <PageShell page={page}>{children}</PageShell>
+    </PageActionProvider>
+  )
+}
+
+export interface PageBlockProps {
+  /** The block key: `form:customer`, `table:products`, `infolist:summary`, `form`, `table`, `content`… */
+  name: string
+  /** Rendered when the page has no such block (e.g. a hidden form). */
+  fallback?: ReactNode
+  className?: string
+}
+
+/** Render any content block of the page by key. */
+export function PageBlock({ name, fallback = null, className }: PageBlockProps) {
+  const page = useAppPage()
+  const block = page?.content.find((candidate) => candidate.key === name)
+
+  if (!page || !block) return <>{fallback}</>
+
+  return (
+    <PageActionProvider value={{ token: page.token, component: 'page' }}>
+      <div data-slot="page-block" data-block={name} className={cn('min-w-0', className)}>
+        <ContentBlockRenderer block={block} />
+      </div>
+    </PageActionProvider>
+  )
+}
+
+type NamedBlockProps = Omit<PageBlockProps, 'name'> & { name?: string }
+
+/** A form defined by `{name}Form(Schema $schema)` (or the page's `form()` without a name). */
+export function PageForm({ name, ...props }: NamedBlockProps) {
+  return <PageBlock name={name ? `form:${name}` : 'form'} {...props} />
+}
+
+/** A table defined by `{name}Table(Table $table)` (or the page's `table()` without a name). */
+export function PageTable({ name, ...props }: NamedBlockProps) {
+  return <PageBlock name={name ? `table:${name}` : 'table'} {...props} />
+}
+
+/** An infolist defined by `{name}Infolist(Schema $schema)` (or the page's `infolist()`). */
+export function PageInfolist({ name, ...props }: NamedBlockProps) {
+  return <PageBlock name={name ? `infolist:${name}` : 'infolist'} {...props} />
+}
+
+/** The page's header (default) or footer widgets. */
+export function PageWidgets({
+  position = 'header',
+  ...props
+}: Omit<PageBlockProps, 'name'> & { position?: 'header' | 'footer' }) {
+  return <PageBlock name={position === 'footer' ? 'footerWidgets' : 'headerWidgets'} {...props} />
+}

package/src/app/hooks.ts

@@ -0,0 +1,365 @@
+import {
+  firstErrors,
+  getPageForm,
+  onPageFormsChanged,
+  PageMethodError,
+  registerShortcut,
+  reloadPageProps,
+  runPageMethod,
+  watchPageProps,
+  type FormState,
+  type FormStore,
+  type LivePropsOptions,
+  type PageMethodArguments,
+  type PageMethodCallOptions,
+  type PageMethodRuntime,
+  type ShortcutOptions,
+} from '@alfakit/core'
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+import { showToast } from '../components/notifications/flash-toasts'
+import { usePageSchema, usePanel, useT } from '../context'
+
+/**
+ * Hooks for custom page components (`Page::$component`): call `#[Expose]` methods, reload
+ * and watch view data, keyboard shortcuts, and the state of embedded `<PageForm>`s.
+ */
+
+function useRuntime(): () => PageMethodRuntime {
+  const page = usePageSchema()
+  const panel = usePanel()
+  const t = useT()
+  const latest = useRef({ page, panel, t })
+
+  useEffect(() => {
+    latest.current = { page, panel, t }
+  })
+
+  // The token is re-issued with every response, so it is read when the call starts.
+  return useCallback(
+    () => ({
+      token: latest.current.page?.token ?? '',
+      panel: latest.current.panel,
+      page: latest.current.page,
+      showToast: (notification) => showToast(notification),
+      t: latest.current.t,
+    }),
+    [],
+  )
+}
+
+export interface UsePageMethodOptions<TResult, TArgs> extends PageMethodCallOptions<TArgs> {
+  onSuccess?: (result: TResult, args: TArgs | undefined) => void
+  onError?: (error: unknown, args: TArgs | undefined) => void
+}
+
+export interface PageMethodBinding<TResult, TArgs> {
+  /** Call the method. Resolves with its result, or `undefined` when it failed. */
+  call: (args?: TArgs, options?: PageMethodCallOptions<TArgs>) => Promise<TResult | undefined>
+  /** Like `call`, but rejects with the error (`PageMethodError`) when it fails. */
+  callOrThrow: (args?: TArgs, options?: PageMethodCallOptions<TArgs>) => Promise<TResult>
+  loading: boolean
+  result: TResult | undefined
+  error: unknown
+  /** Validation errors of the last call, first message per key (`{ sku: '…' }`). */
+  errors: Record<string, string>
+  reset: () => void
+}
+
+/**
+ * Call one `#[Expose]` method of the page:
+ *
+ * ```tsx
+ * const checkout = usePageMethod<Order, { items: CartLine[] }>('checkout', { forms: ['customer'] })
+ * <Button disabled={checkout.loading} onClick={() => checkout.call({ items })}>Charge</Button>
+ * ```
+ *
+ * Notifications are shown as toasts, redirects followed, `reloadProps()` applied.
+ */
+export function usePageMethod<
+  TResult = unknown,
+  TArgs extends PageMethodArguments = Record<string, unknown>,
+>(
+  method: string,
+  options: UsePageMethodOptions<TResult, TArgs> = {},
+): PageMethodBinding<TResult, TArgs> {
+  const runtime = useRuntime()
+  const [state, setState] = useState<{
+    loading: number
+    result: TResult | undefined
+    error: unknown
+    errors: Record<string, string>
+  }>({ loading: 0, result: undefined, error: null, errors: {} })
+  const optionsRef = useRef(options)
+
+  useEffect(() => {
+    optionsRef.current = options
+  })
+  const mounted = useRef(true)
+
+  useEffect(() => {
+    mounted.current = true
+
+    return () => {
+      mounted.current = false
+    }
+  }, [])
+
+  const callOrThrow = useCallback(
+    async (args?: TArgs, overrides: PageMethodCallOptions<TArgs> = {}): Promise<TResult> => {
+      const { onSuccess, onError, ...defaults } = optionsRef.current
+
+      setState((current) => ({ ...current, loading: current.loading + 1, error: null }))
+
+      try {
+        const result = await runPageMethod<TResult, TArgs>(method, args, runtime(), {
+          ...defaults,
+          ...overrides,
+        })
+
+        if (mounted.current) {
+          setState((current) => ({
+            loading: Math.max(0, current.loading - 1),
+            result,
+            error: null,
+            errors: {},
+          }))
+        }
+
+        onSuccess?.(result, args)
+
+        return result
+      } catch (error) {
+        if (mounted.current) {
+          setState((current) => ({
+            ...current,
+            loading: Math.max(0, current.loading - 1),
+            error,
+            errors:
+              error instanceof PageMethodError && error.isValidation
+                ? firstErrors(error.errors)
+                : {},
+          }))
+        }
+
+        onError?.(error, args)
+
+        throw error
+      }
+    },
+    [method, runtime],
+  )
+
+  const call = useCallback(
+    (args?: TArgs, overrides?: PageMethodCallOptions<TArgs>) =>
+      callOrThrow(args, overrides).catch(() => undefined),
+    [callOrThrow],
+  )
+
+  const reset = useCallback(
+    () => setState({ loading: 0, result: undefined, error: null, errors: {} }),
+    [],
+  )
+
+  return {
+    call,
+    callOrThrow,
+    loading: state.loading > 0,
+    result: state.result,
+    error: state.error,
+    errors: state.errors,
+    reset,
+  }
+}
+
+/** A map of method names to their arguments and results, for typed `usePageMethods()`. */
+export type PageMethodMap = Record<string, { args?: PageMethodArguments; result?: unknown }>
+
+export interface PageMethodsBinding<TMap extends PageMethodMap> {
+  call: <K extends keyof TMap & string>(
+    method: K,
+    args?: TMap[K]['args'],
+    options?: PageMethodCallOptions<TMap[K]['args']>,
+  ) => Promise<TMap[K]['result'] | undefined>
+  callOrThrow: <K extends keyof TMap & string>(
+    method: K,
+    args?: TMap[K]['args'],
+    options?: PageMethodCallOptions<TMap[K]['args']>,
+  ) => Promise<TMap[K]['result']>
+  /** True while any call is in flight; `isLoading('checkout')` for one method. */
+  loading: boolean
+  isLoading: (method: keyof TMap & string) => boolean
+  /** Validation errors of the last failed call, by method. */
+  errors: Partial<Record<keyof TMap & string, Record<string, string>>>
+}
+
+/**
+ * Call any `#[Expose]` method of the page by name. Type it with a map:
+ * `usePageMethods<{ addItem: { args: { sku: string }; result: CartLine } }>()`.
+ */
+export function usePageMethods<TMap extends PageMethodMap = PageMethodMap>(
+  defaults: PageMethodCallOptions = {},
+): PageMethodsBinding<TMap> {
+  const runtime = useRuntime()
+  const [pending, setPending] = useState<Record<string, number>>({})
+  const [errors, setErrors] = useState<Record<string, Record<string, string>>>({})
+  const defaultsRef = useRef(defaults)
+
+  useEffect(() => {
+    defaultsRef.current = defaults
+  })
+
+  const callOrThrow = useCallback(
+    async (method: string, args?: PageMethodArguments, options: PageMethodCallOptions = {}) => {
+      setPending((current) => ({ ...current, [method]: (current[method] ?? 0) + 1 }))
+
+      try {
+        const result = await runPageMethod(method, args, runtime(), {
+          ...defaultsRef.current,
+          ...options,
+        } as PageMethodCallOptions<PageMethodArguments>)
+
+        setErrors((current) => {
+          if (!current[method]) return current
+          const next = { ...current }
+          delete next[method]
+
+          return next
+        })
+
+        return result
+      } catch (error) {
+        if (error instanceof PageMethodError && error.isValidation) {
+          setErrors((current) => ({ ...current, [method]: firstErrors(error.errors) }))
+        }
+
+        throw error
+      } finally {
+        setPending((current) => ({ ...current, [method]: Math.max(0, (current[method] ?? 1) - 1) }))
+      }
+    },
+    [runtime],
+  )
+
+  // `call` and `callOrThrow` keep their identity, so they are safe effect dependencies.
+  const call = useCallback(
+    (method: string, args?: PageMethodArguments, options?: PageMethodCallOptions) =>
+      callOrThrow(method, args, options).catch(() => undefined),
+    [callOrThrow],
+  )
+
+  return useMemo(
+    () =>
+      ({
+        callOrThrow,
+        call,
+        loading: Object.values(pending).some((count) => count > 0),
+        isLoading: (method: string) => (pending[method] ?? 0) > 0,
+        errors,
+      }) as unknown as PageMethodsBinding<TMap>,
+    [callOrThrow, call, pending, errors],
+  )
+}
+
+/**
+ * Reload view data (`getViewData()` keys) with an Inertia partial reload:
+ * `const { reload, reloading } = useReloadProps(['cart'])`.
+ */
+export function useReloadProps(only?: string[]): {
+  reload: (props?: string[]) => Promise<void>
+  reloading: boolean
+} {
+  const [reloading, setReloading] = useState(0)
+  const key = JSON.stringify(only ?? null)
+
+  const reload = useCallback(
+    async (props?: string[]) => {
+      setReloading((count) => count + 1)
+
+      try {
+        await reloadPageProps(props ?? (JSON.parse(key) as string[] | null) ?? undefined)
+      } finally {
+        setReloading((count) => Math.max(0, count - 1))
+      }
+    },
+    [key],
+  )
+
+  return { reload, reloading: reloading > 0 }
+}
+
+/**
+ * Keep view data props fresh while the component is mounted: every `poll` interval, and/or
+ * when a Laravel Echo event arrives (`echo: { channel, events }`).
+ */
+export function useLiveProps(only: string[], options: LivePropsOptions): void {
+  const key = JSON.stringify([only, options])
+
+  useEffect(() => {
+    const [props, live] = JSON.parse(key) as [string[], LivePropsOptions]
+
+    return watchPageProps(props, live)
+  }, [key])
+}
+
+/**
+ * A keyboard shortcut while the component is mounted: `useShortcut('mod+k', openSearch)`.
+ * Shortcuts without a modifier are ignored while typing unless `allowInInputs` is set.
+ */
+export function useShortcut(
+  keys: string | string[],
+  handler: (event: KeyboardEvent) => void,
+  options: ShortcutOptions & { enabled?: boolean } = {},
+): void {
+  const handlerRef = useRef(handler)
+
+  useEffect(() => {
+    handlerRef.current = handler
+  })
+  const key = JSON.stringify([keys, options.allowInInputs, options.preventDefault])
+  const enabled = options.enabled !== false
+
+  useEffect(() => {
+    if (!enabled) return
+
+    const [bindings, allowInInputs, preventDefault] = JSON.parse(key) as [
+      string | string[],
+      boolean | undefined,
+      boolean | undefined,
+    ]
+
+    return registerShortcut(bindings, (event) => handlerRef.current(event), {
+      allowInInputs,
+      preventDefault,
+    })
+  }, [key, enabled])
+}
+
+const noopSubscribe = () => () => {}
+
+/**
+ * The store and state of an embedded `<PageForm name>`: read its values, or reset fields
+ * with `store.setValue()`. `store` is undefined until the form has mounted.
+ */
+export function usePageForm(name: string): {
+  store: FormStore | undefined
+  values: Record<string, unknown>
+  errors: Record<string, string[]>
+} {
+  const store = useSyncExternalStore(
+    onPageFormsChanged,
+    () => getPageForm(name),
+    () => undefined,
+  )
+
+  const subscribe = useCallback(
+    (listener: () => void) => (store ? store.store.subscribe(listener) : noopSubscribe()),
+    [store],
+  )
+  const state = useSyncExternalStore<FormState | undefined>(
+    subscribe,
+    () => store?.store.get(),
+    () => undefined,
+  )
+
+  return { store, values: state?.values ?? {}, errors: state?.errors ?? {} }
+}