@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/file-manager/index.ts

@@ -0,0 +1,2 @@
+export { FileManager } from './file-manager-lazy'
+export { FileManagerPickerField } from './picker-field'

package/src/components/file-manager/picker-field.tsx

@@ -0,0 +1,169 @@
+import type {
+  FileManagerEntrySchema,
+  FileManagerPickedFileSchema,
+  FileManagerPickerSchema,
+} from '@alfakit/core'
+import { fileManagerSize } from '@alfakit/core'
+import { FileIcon, FolderOpenIcon, ImageIcon, TriangleAlertIcon, XIcon } from 'lucide-react'
+import { useState } from 'react'
+import { useChoice, useFormatter, useT } from '../../context'
+import { cn } from '../../lib/utils'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { Button } from '../ui/button'
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '../ui/dialog'
+import { FileManagerBrowser } from './file-manager-lazy'
+
+/**
+ * `FileManagerPicker` (alfasix/alfakit-file-manager): files picked from the file manager.
+ * The state is their paths on the disk; the browser runs through the file manager page, so
+ * it shows what the user may see there. The server checks every path again on save.
+ */
+export function FileManagerPickerField({ component }: { component: FileManagerPickerSchema }) {
+  const t = useT()
+  const choice = useChoice()
+  const formatter = useFormatter()
+  const { value, setValue, error, id, disabled, readOnly, aria } = useField<
+    string | string[] | null
+  >(component)
+  const [open, setOpen] = useState(false)
+  // Files picked in this session (the schema only knows the saved ones).
+  const [picked, setPicked] = useState<FileManagerPickedFileSchema[]>([])
+  const locked = disabled || readOnly
+  const values = (Array.isArray(value) ? value : value ? [value] : []).filter(
+    (item): item is string => typeof item === 'string',
+  )
+  const files = values.map(
+    (path) =>
+      [...picked, ...component.files].find((file) => file.value === path) ?? {
+        value: path,
+        name: path.split('/').pop() ?? path,
+      },
+  )
+  const max = component.multiple ? (component.maxFiles ?? Infinity) : 1
+
+  const choose = (entries: FileManagerEntrySchema[]) => {
+    const chosen = entries.filter(
+      (entry): entry is FileManagerEntrySchema & { value: string } =>
+        typeof entry.value === 'string',
+    )
+
+    setPicked((current) => [...current, ...chosen])
+
+    if (component.multiple) {
+      setValue([...new Set([...values, ...chosen.map((entry) => entry.value)])].slice(0, max))
+    } else {
+      setValue(chosen[0]?.value ?? null)
+    }
+
+    setOpen(false)
+  }
+
+  const remove = (path: string) => {
+    const next = values.filter((item) => item !== path)
+    setValue(component.multiple ? next : (next[0] ?? null))
+  }
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <div className="flex flex-col gap-2" data-slot="file-manager-picker">
+        {files.length > 0 ? (
+          <ul className="flex flex-col divide-y rounded-md border">
+            {files.map((file) => (
+              <li
+                key={file.value}
+                className="flex items-center gap-3 px-3 py-2 text-sm"
+                data-missing={file.missing ? '' : undefined}
+              >
+                {file.thumbnail ? (
+                  <img src={file.thumbnail} alt="" className="size-8 rounded object-cover" />
+                ) : file.missing ? (
+                  <TriangleAlertIcon className="text-destructive size-5" aria-hidden="true" />
+                ) : file.kind === 'image' ? (
+                  <ImageIcon className="text-muted-foreground size-5" aria-hidden="true" />
+                ) : (
+                  <FileIcon className="text-muted-foreground size-5" aria-hidden="true" />
+                )}
+                <div className="min-w-0 flex-1">
+                  <p
+                    className={cn(
+                      'truncate font-medium',
+                      file.missing && 'text-muted-foreground line-through',
+                    )}
+                  >
+                    {file.name}
+                  </p>
+                  <p className="text-muted-foreground truncate text-xs">
+                    {file.missing
+                      ? t('file-manager.picker_missing', {}, 'This file no longer exists')
+                      : fileManagerSize(file.size, formatter)}
+                  </p>
+                </div>
+                {!locked && (
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    onClick={() => remove(file.value)}
+                    aria-label={t(
+                      'file-manager.picker_remove',
+                      { name: file.name },
+                      'Remove :name',
+                    )}
+                  >
+                    <XIcon aria-hidden="true" />
+                  </Button>
+                )}
+              </li>
+            ))}
+          </ul>
+        ) : (
+          <p className="text-muted-foreground text-sm">
+            {t('file-manager.picker_empty', {}, 'No file chosen')}
+          </p>
+        )}
+        {!locked && files.length < max && (
+          <Button
+            id={id}
+            type="button"
+            variant="outline"
+            className="self-start"
+            onClick={() => setOpen(true)}
+            {...aria}
+            aria-label={t('file-manager.picker_browse', {}, 'Browse files')}
+          >
+            <FolderOpenIcon aria-hidden="true" />
+            {t('file-manager.picker_browse', {}, 'Browse files')}
+          </Button>
+        )}
+      </div>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent
+          className="max-h-[92vh] gap-3 overflow-hidden p-4 sm:max-w-5xl"
+          data-slot="file-manager-picker-dialog"
+        >
+          <DialogHeader>
+            <DialogTitle>
+              {choice(
+                'file-manager.picker_heading',
+                component.multiple ? 2 : 1,
+                {},
+                'Choose files',
+              )}
+            </DialogTitle>
+            <DialogDescription className="sr-only">
+              {t('file-manager.label', {}, 'File manager')}
+            </DialogDescription>
+          </DialogHeader>
+          {open && (
+            <FileManagerBrowser
+              schema={component.browser}
+              onChoose={choose}
+              onCancel={() => setOpen(false)}
+            />
+          )}
+        </DialogContent>
+      </Dialog>
+    </FieldWrapper>
+  )
+}

package/src/components/form/form-block.tsx

@@ -0,0 +1,237 @@
+import type { ActionContext, ActionSchema, FormBlock as FormBlockSchema } from '@alfakit/core'
+import {
+  FormStore,
+  applyFormRefresh,
+  formActionsVisible,
+  formIdentity,
+  formRefreshFor,
+  isImplicitSubmit,
+  isLeavingVisit,
+  pageFlash,
+  pageFormName,
+  registerConflictForm,
+  registerFormSubmitter,
+  registerPageForm,
+  resolvePartialProps,
+  wizardProgressStore,
+} from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import { useCallback, useEffect, useMemo, useRef } from 'react'
+import { useActionRunner, useAlfakitProps, usePageSchema, usePanel, useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { ActionList } from '../actions/action-list'
+import { showToast } from '../notifications/flash-toasts'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { FormProvider } from './form-context'
+
+/**
+ * A page form: its state lives in a FormStore, and its buttons are actions that post the
+ * current values through the action endpoint.
+ */
+export function FormBlock({ block }: { block: FormBlockSchema }) {
+  const panel = usePanel()
+  const page = usePageSchema()
+  const props = useAlfakitProps()
+  const runner = useActionRunner()
+  const t = useT()
+  const token = page?.token ?? ''
+
+  // The store survives reloads of the same form (table sorting/paging, polling,
+  // relation-manager actions all deliver a new `block` object); only a different form
+  // identity starts from server state again. The token is re-issued per response, so it
+  // is swapped in place instead of being part of the identity.
+  const identity = formIdentity(page, block)
+
+  const store = useMemo(
+    () =>
+      new FormStore(block, {
+        token,
+        component: block.component,
+        refreshUrl: panel.endpoints.schemaRefresh,
+        optionsUrl: panel.endpoints.schemaOptions,
+        validateUrl: panel.endpoints.schemaValidate,
+        // A halted wizard step shows what its hook sent.
+        onNotifications: (notifications) => notifications.forEach((n) => showToast(n)),
+        // Live dashboard filters are applied by the refresh; the widgets reload to follow.
+        onRefreshed: () => {
+          if (latestBlock.current.liveFilters)
+            router.reload({ only: resolvePartialProps(['page']) })
+        },
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [identity],
+  )
+
+  useEffect(() => () => store.destroy(), [store])
+
+  // Named forms of custom pages (`<PageForm name>`) publish their store for page method calls.
+  useEffect(() => {
+    const name = pageFormName(block.component)
+
+    return name ? registerPageForm(name, store) : undefined
+  }, [block.component, store])
+
+  // Edit pages: the conflict banner diffs and merges the main form (`detectConflicts()`).
+  useEffect(
+    () => (block.component === 'form' ? registerConflictForm(store) : undefined),
+    [block.component, store],
+  )
+
+  useEffect(() => {
+    store.setToken(token)
+  }, [store, token])
+
+  useEffect(() => {
+    store.setErrors((props.errors as Record<string, string>) ?? {})
+  }, [props.errors, store])
+
+  const state = useStore(store.store)
+  const context = useMemo<ActionContext>(() => ({ token, component: 'page' }), [token])
+  const submitting = useRef(false)
+  // After this form's own successful submit, refill from the server's new state. The new
+  // block may arrive before or after Inertia's `success` event, so handle both orders.
+  const latestBlock = useRef(block)
+  const submittedBlock = useRef<FormBlockSchema | null>(null)
+  const refillPending = useRef(false)
+
+  useEffect(() => {
+    latestBlock.current = block
+
+    if (refillPending.current) {
+      refillPending.current = false
+      store.fill(block)
+    }
+  }, [block, store])
+
+  const actions: ActionSchema[] = useMemo(
+    () => block.actions.map((action) => ({ ...action, hasModal: false })),
+    [block.actions],
+  )
+
+  const trigger = useCallback(
+    async (action: ActionSchema, ctx: ActionContext) => {
+      if (action.url && !action.hasAction) {
+        return runner.trigger(action, ctx)
+      }
+
+      submitting.current = true
+      submittedBlock.current = latestBlock.current
+      store.setProcessing(true)
+      runner.execute(action, ctx, store.state.values)
+    },
+    [runner, store],
+  )
+
+  // Buttons elsewhere with `formId('form')` (a header "Save") submit through this form.
+  useEffect(() => registerFormSubmitter(block.component, trigger), [block.component, trigger])
+
+  // `refreshFormData([...])`: an action changed the record; copy those fields in.
+  useEffect(
+    () =>
+      router.on('success', (event) => {
+        const refresh = formRefreshFor(pageFlash(event.detail.page), block.component)
+
+        if (refresh) applyFormRefresh(store, refresh)
+      }),
+    [block.component, store],
+  )
+
+  // Wizard forms (`HasWizard` pages) show their buttons on the last step only.
+  const progressStore = useMemo(() => wizardProgressStore(store), [store])
+  const progress = useStore(progressStore)
+  const showActions = formActionsVisible(block, progress)
+
+  // Track this form's own submit visit so unrelated reloads finishing meanwhile (polling,
+  // relation-manager paging) neither end its processing state nor count as its success.
+  const submitVisit = useRef<string | null>(null)
+
+  useEffect(() => {
+    const offStart = router.on('start', (event) => {
+      const visit = event.detail.visit
+
+      if (submitting.current && !submitVisit.current && visit.method !== 'get') {
+        submitVisit.current = visit.id
+      }
+    })
+
+    const offSuccess = router.on('success', (event) => {
+      const id = submitVisit.current
+
+      if (!id || (event.detail.visitId ?? id) !== id) return
+
+      // A halted action (rate limit, `halt()`) saved nothing: keep what the user typed.
+      if (pageFlash(event.detail.page).alfakitAction?.status === 'halted') return
+
+      if (latestBlock.current !== submittedBlock.current) {
+        store.fill(latestBlock.current)
+      } else {
+        refillPending.current = true
+      }
+    })
+
+    const offFinish = router.on('finish', (event) => {
+      if (submitVisit.current && event.detail.visit.id !== submitVisit.current) return
+
+      store.setProcessing(false)
+      submitting.current = false
+      submitVisit.current = null
+    })
+
+    return () => {
+      offStart()
+      offSuccess()
+      offFinish()
+    }
+  }, [store])
+
+  useEffect(() => {
+    if (!panel.unsavedChangesAlerts) {
+      return
+    }
+
+    return router.on('before', (event) => {
+      if (
+        store.isDirty &&
+        !submitting.current &&
+        isLeavingVisit(event.detail.visit) &&
+        !window.confirm(t('unsaved_changes', {}, 'You have unsaved changes. Leave anyway?'))
+      ) {
+        event.preventDefault()
+      }
+    })
+  }, [panel.unsavedChangesAlerts, store, t])
+
+  const primary = actions[0]
+
+  return (
+    <FormProvider store={store}>
+      <form
+        data-slot="form-block"
+        className="flex flex-col gap-6"
+        onSubmit={(event) => {
+          event.preventDefault()
+
+          if (primary && showActions) {
+            void trigger(primary, context)
+          }
+        }}
+        onKeyDown={(event) => {
+          // Enter in a text field runs the primary action (actions are type="button").
+          if (primary && showActions && isImplicitSubmit(event.nativeEvent, event.currentTarget)) {
+            event.preventDefault()
+            void trigger(primary, context)
+          }
+        }}
+      >
+        <fieldset disabled={state.processing || block.operation === 'view'} className="contents">
+          <SchemaRenderer components={state.components} columns={state.columns} />
+        </fieldset>
+        {actions.length > 0 && showActions && (
+          <div data-slot="form-actions" className="border-t pt-6">
+            <ActionList actions={actions} context={context} onTrigger={trigger} />
+          </div>
+        )}
+      </form>
+    </FormProvider>
+  )
+}

package/src/components/form/form-context.tsx

@@ -0,0 +1,95 @@
+import type { BaseField, FieldAriaAttributes, FormState, FormStore } from '@alfakit/core'
+import { fieldAria } from '@alfakit/core'
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react'
+import { useStore, useStoreSelector } from '../../hooks/use-store'
+
+const FormStoreContext = createContext<FormStore | null>(null)
+
+export function FormProvider({ store, children }: { store: FormStore; children: ReactNode }) {
+  return <FormStoreContext.Provider value={store}>{children}</FormStoreContext.Provider>
+}
+
+export function useFormStore(): FormStore {
+  const store = useContext(FormStoreContext)
+
+  if (!store) {
+    throw new Error('Form fields must be rendered inside a FormProvider.')
+  }
+
+  return store
+}
+
+export function useOptionalFormStore(): FormStore | null {
+  return useContext(FormStoreContext)
+}
+
+export function useFormState(): FormState {
+  return useStore(useFormStore().store)
+}
+
+export interface FieldBinding<T = unknown> {
+  value: T
+  setValue: (value: T) => void
+  blur: () => void
+  error: string | undefined
+  id: string
+  /** The field cannot be interacted with at all (`disabled()`). */
+  disabled: boolean
+  /** The field shows its value but the user cannot change it (`readOnly()`). */
+  readOnly: boolean
+  /** `aria-describedby` (hint, helper text, error), `aria-invalid` and `aria-required` for the control. */
+  aria: FieldAriaAttributes
+}
+
+/** Bind a field schema (a built-in or custom field) to the form store. */
+export function useField<T = unknown>(field: BaseField): FieldBinding<T> {
+  const store = useFormStore()
+  const path = field.statePath
+
+  const value = useStoreSelector(store.store, (state) => {
+    let current: unknown = state.values
+
+    for (const segment of path.split('.')) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return undefined as T
+      }
+
+      current = (current as Record<string, unknown>)[segment]
+    }
+
+    return current as T
+  })
+
+  const error = useStoreSelector(store.store, (state) => state.errors[path]?.[0])
+
+  const setValue = useCallback((next: T) => store.setValue(path, next), [store, path])
+  const blur = useCallback(() => store.blur(path), [store, path])
+
+  const id = useMemo(
+    () => field.id ?? `alfakit-${path.replace(/[^a-zA-Z0-9_-]/g, '-')}`,
+    [field.id, path],
+  )
+
+  const aria = useMemo(
+    () =>
+      fieldAria(
+        id,
+        { hint: field.hint, helperText: field.helperText, required: field.required },
+        error,
+      ),
+    [id, field.hint, field.helperText, field.required, error],
+  )
+
+  // Fields stay enabled during a live refresh: the store keeps edits made while the request
+  // is in flight, so locking inputs would only swallow keystrokes.
+  return {
+    value,
+    setValue,
+    blur,
+    error,
+    id,
+    disabled: Boolean(field.disabled),
+    readOnly: Boolean(field.readOnly),
+    aria,
+  }
+}