@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/elements/Form.ts

@@ -1,416 +0,0 @@
-import { Element, type ElementMeta } from '../schema/Element.js'
-import type { Validator, ValidationErrors } from '../validation/index.js'
-import type { Notification, NotificationMeta } from '../notifications/index.js'
-
-export type FormMethod = 'get' | 'post' | 'put' | 'patch' | 'delete'
-
-export interface FormContext<R = unknown> {
-  values: Record<string, unknown>
-  record?: R
-  request?: unknown
-  /**
-   * The panel's mount path (e.g. `/admin`, `/new-admin`). Populated by
-   * the framework's POST handlers so user-supplied callbacks
-   * (`redirectAfterSave` / page `getRedirectUrl`) can build absolute
-   * URLs without hardcoding the base.
-   */
-  basePath?: string
-  [key: string]: unknown
-}
-
-export type SaveHandler<R = unknown> = (
-  data: Record<string, unknown>,
-  ctx: FormContext<R>,
-) => Promise<R> | R
-
-export type MutateDataHandler = (
-  data: Record<string, unknown>,
-  ctx: FormContext,
-) => Record<string, unknown> | Promise<Record<string, unknown>>
-
-export type LifecycleHandler<R = unknown> = (
-  data: Record<string, unknown>,
-  ctx: FormContext<R>,
-) => void | Promise<void>
-
-export type AfterSaveHandler<R = unknown> = (
-  record: R,
-  ctx: FormContext<R>,
-) => void | Promise<void>
-
-export type RedirectHandler<R = unknown> = (
-  record: R,
-  ctx: FormContext<R>,
-) => string
-
-export type LoadRecordHandler<R = unknown> = (
-  id: string,
-  ctx: FormContext<R>,
-) => Promise<R | null> | R | null
-
-export type FillFromRecordHandler<R = unknown> = (
-  record: R,
-) => Record<string, unknown>
-
-/**
- * Transform values during the edit-mode load path. `mutateFormDataBeforeFill`
- * runs before `fillFromRecord` (input is whatever was passed into the form);
- * `mutateFormDataAfterFill` runs after, on the values produced by
- * `fillFromRecord`. Both receive the loaded record on `ctx.record`.
- */
-export type FillMutator<R = unknown> = (
-  values: Record<string, unknown>,
-  ctx: FormContext<R>,
-) => Record<string, unknown> | Promise<Record<string, unknown>>
-
-/**
- * Resolve a saved-notification spec into a `Notification`/meta. `null`
- * means "skip" (notifications disabled for this mode). Strings shorthand
- * to a success notification with that title.
- */
-export type SavedNotificationHandler<R = unknown> =
-  | string
-  | Notification
-  | NotificationMeta
-  | null
-  | ((record: R, ctx: FormContext<R>) => string | Notification | NotificationMeta | null)
-
-export interface FormMeta extends ElementMeta {
-  type:    'form'
-  formId:  string
-  /** Plan #8 — wizard step-validate endpoint, when the form has a Wizard descendant. */
-  wizardUrl?: string
-  method:  FormMethod
-  action?: string
-  values?: Record<string, unknown>
-  errors?: ValidationErrors
-  /**
-   * Plan #5 partial-resolve endpoint URL. Emitted only when at least
-   * one descendant field has `live()` set; the client uses its presence
-   * to decide whether to switch into controlled-state mode and POST on
-   * `live` field changes.
-   */
-  stateUrl?: string
-}
-
-let _formIdSeq = 0
-function nextFormId(): string {
-  _formIdSeq += 1
-  return `form-${_formIdSeq}`
-}
-
-/**
- * Form container. Holds children (Fields, Sections, Tabs, Actions, …) plus
- * a server-side lifecycle: validate → mutateData → beforeSave → save →
- * afterSave → redirectAfterSave. Handlers stay on the server; `toMeta()`
- * emits only what the client needs to render the form (id, method, action
- * URL, current values, validation errors).
- *
- * Phase 2.1 ships the shape and serialization. Lifecycle dispatch on POST
- * is wired in 2.4.
- */
-export class Form<R = unknown> extends Element {
-  private _formId = nextFormId()
-  private _method: FormMethod = 'post'
-  private _action?: string
-
-  private _formValidators: Validator[] = []
-  private _mutateData?: MutateDataHandler
-  private _mutateDataBeforeCreate?: MutateDataHandler
-  private _mutateDataBeforeUpdate?: MutateDataHandler
-  private _beforeSave?: LifecycleHandler<R>
-  private _beforeCreate?: LifecycleHandler<R>
-  private _beforeUpdate?: LifecycleHandler<R>
-  private _save?: SaveHandler<R>
-  private _handleCreate?: SaveHandler<R>
-  private _handleUpdate?: SaveHandler<R>
-  private _afterSave?: AfterSaveHandler<R>
-  private _afterCreate?: AfterSaveHandler<R>
-  private _afterUpdate?: AfterSaveHandler<R>
-  private _redirectAfterSave?: RedirectHandler<R>
-  private _fillFromRecord?: FillFromRecordHandler<R>
-  private _mutateFormDataBeforeFill?: FillMutator<R>
-  private _mutateFormDataAfterFill?: FillMutator<R>
-  private _loadRecord?: LoadRecordHandler<R>
-
-  /**
-   * Saved-notification spec for the generic both-modes path. Mode-specific
-   * specs (`_createdNotification`) take precedence in their respective mode.
-   * `null` means "explicitly disabled" (different from undefined which means
-   * "use the framework default"). `false` (via `disableSavedNotification`)
-   * disables for both modes regardless of mode-specific spec.
-   */
-  private _savedNotification?: SavedNotificationHandler<R> | null
-  private _createdNotification?: SavedNotificationHandler<R> | null
-  private _savedNotificationDisabled = false
-
-  private _values?: Record<string, unknown>
-  private _errors?: ValidationErrors
-
-  /**
-   * Cascading `inlineLabel` default for every descendant `Field`. Read
-   * by the resolver in `deriveChildContext` and pushed down via
-   * `RenderContext.inlineLabelDefault`. Per-field `Field.inlineLabel(...)`
-   * overrides; nested `Section.inlineLabel(...)` overrides for its
-   * subtree.
-   */
-  private _inlineLabel?: boolean
-
-  // Plan #5 — partial-resolve endpoint. Stamped by the route handler at
-  // render time when any descendant field is `live()`; emits as
-  // (Plan #8) `wizardUrl` for step validation endpoint. Stamped only when
-  // the Form has a Wizard descendant.
-  private _wizardUrl?: string
-
-  // `stateUrl` on FormMeta. Undefined when no live fields → client
-  // skips the controlled-state path entirely.
-  private _stateUrl?: string
-
-  private constructor() { super() }
-
-  static make<R = unknown>(): Form<R> {
-    return new Form<R>()
-  }
-
-  // ─── Children ─────────────────────────────────────────
-
-  schema(elements: Element[]): this {
-    this._children = elements
-    return this
-  }
-
-  // ─── Static config ────────────────────────────────────
-
-  formId(id: string): this { this._formId = id; return this }
-  method(m: FormMethod): this { this._method = m; return this }
-  action(url: string): this { this._action = url; return this }
-
-  /**
-   * Cascade `inlineLabel` to every descendant `Field` whose own
-   * `.inlineLabel(...)` hasn't been called. Pass `false` explicitly to
-   * cascade label-above when a parent (rare) had set it. Read by the
-   * resolver and pushed down via `RenderContext.inlineLabelDefault`.
-   */
-  inlineLabel(v = true): this { this._inlineLabel = v; return this }
-  /** Internal — read by `resolveSchema.deriveChildContext`. */
-  getInlineLabel(): boolean | undefined { return this._inlineLabel }
-
-  // ─── Lifecycle setters ────────────────────────────────
-
-  /** Form-level validators run after field-level ones. Useful for cross-field rules. */
-  validate(...validators: Validator[]): this {
-    this._formValidators.push(...validators)
-    return this
-  }
-
-  /**
-   * Transform the validated payload before `save()`. Runs after validation
-   * passes, on **both** create and update. Pair with
-   * `mutateDataBeforeCreate` / `mutateDataBeforeUpdate` for mode-specific
-   * tweaks that layer on top.
-   */
-  mutateData(fn: MutateDataHandler): this {
-    this._mutateData = fn
-    return this
-  }
-
-  /** Create-only payload mutator. Runs after `mutateData` when `ctx.record` is undefined. */
-  mutateDataBeforeCreate(fn: MutateDataHandler): this {
-    this._mutateDataBeforeCreate = fn
-    return this
-  }
-
-  /** Update-only payload mutator. Runs after `mutateData` when `ctx.record` is set. */
-  mutateDataBeforeUpdate(fn: MutateDataHandler): this {
-    this._mutateDataBeforeUpdate = fn
-    return this
-  }
-
-  beforeSave(fn: LifecycleHandler<R>): this { this._beforeSave = fn; return this }
-
-  /** Create-only pre-save hook. Runs after `beforeSave` when `ctx.record` is undefined. */
-  beforeCreate(fn: LifecycleHandler<R>): this { this._beforeCreate = fn; return this }
-
-  /** Update-only pre-save hook. Runs after `beforeSave` when `ctx.record` is set. */
-  beforeUpdate(fn: LifecycleHandler<R>): this { this._beforeUpdate = fn; return this }
-
-  /**
-   * Persistence handler. Required for any form that accepts submits. No
-   * default implementation — Phase 3 ships an ORM adapter via
-   * `Resource.model`.
-   */
-  save(fn: SaveHandler<R>): this { this._save = fn; return this }
-
-  /**
-   * Create-only persistence override. Replaces `save()` for create mode.
-   * Use when create and update need distinct persistence paths (e.g.
-   * `Article.create(...)` vs `Article.update(id, ...)`).
-   */
-  handleCreate(fn: SaveHandler<R>): this { this._handleCreate = fn; return this }
-
-  /** Update-only persistence override. Replaces `save()` for update mode. */
-  handleUpdate(fn: SaveHandler<R>): this { this._handleUpdate = fn; return this }
-
-  afterSave(fn: AfterSaveHandler<R>): this { this._afterSave = fn; return this }
-
-  /** Create-only post-save hook. Runs after `afterSave` when `ctx.record` was undefined. */
-  afterCreate(fn: AfterSaveHandler<R>): this { this._afterCreate = fn; return this }
-
-  /** Update-only post-save hook. Runs after `afterSave` when `ctx.record` was set. */
-  afterUpdate(fn: AfterSaveHandler<R>): this { this._afterUpdate = fn; return this }
-
-  /** Where to redirect after a successful save. Receives the saved record. */
-  redirectAfterSave(fn: RedirectHandler<R>): this {
-    this._redirectAfterSave = fn
-    return this
-  }
-
-  /** Map a loaded record into form values for edit mode. Defaults to `{ ...record }`. */
-  fillFromRecord(fn: FillFromRecordHandler<R>): this {
-    this._fillFromRecord = fn
-    return this
-  }
-
-  /** Transform values BEFORE `fillFromRecord` runs. Edit mode only. */
-  mutateFormDataBeforeFill(fn: FillMutator<R>): this {
-    this._mutateFormDataBeforeFill = fn
-    return this
-  }
-
-  /** Transform values AFTER `fillFromRecord` runs. Edit mode only. */
-  mutateFormDataAfterFill(fn: FillMutator<R>): this {
-    this._mutateFormDataAfterFill = fn
-    return this
-  }
-
-  /** Load a record by id for edit mode. */
-  loadRecord(fn: LoadRecordHandler<R>): this {
-    this._loadRecord = fn
-    return this
-  }
-
-  /**
-   * Notification fired after a successful save (both modes). Pass a string
-   * for a default success toast with that title, a fully-built
-   * `Notification`/meta, or a function that builds one from the saved
-   * record. Pass `null` to suppress the framework's default toast for
-   * this mode.
-   */
-  savedNotification(spec: SavedNotificationHandler<R>): this {
-    this._savedNotification = spec
-    return this
-  }
-
-  /** Create-only notification override. Falls back to `savedNotification` if unset. */
-  createdNotification(spec: SavedNotificationHandler<R>): this {
-    this._createdNotification = spec
-    return this
-  }
-
-  /** Disable the success toast entirely (both modes). */
-  disableSavedNotification(): this {
-    this._savedNotificationDisabled = true
-    return this
-  }
-
-  // ─── Render-time state ────────────────────────────────
-
-  /**
-   * Set the current form values for rendering. Called by route handlers in
-   * edit mode (after `loadRecord` + `fillFromRecord`) and on validation
-   * errors (so the user's input is preserved).
-   */
-  withValues(values: Record<string, unknown>): this {
-    this._values = values
-    return this
-  }
-
-  /** Attach validation errors for re-render after a failed submit. */
-  withErrors(errors: ValidationErrors): this {
-    this._errors = errors
-    return this
-  }
-
-  /**
-   * Plan #5 — set the partial-resolve endpoint URL. Stamped at
-   * render-time by the route handler; the client POSTs `live` field
-   * changes here and receives a fresh re-resolved FormMeta back. Pass
-   * `undefined` to clear (e.g. forms with no live fields).
-   */
-  withStateUrl(url: string | undefined): this {
-    if (url === undefined) {
-      delete this._stateUrl
-    } else {
-      this._stateUrl = url
-    }
-    return this
-  }
-
-  getStateUrl(): string | undefined { return this._stateUrl }
-
-  /**
-   * Plan #8 — set the wizard step-validate endpoint URL. Stamped at
-   * render-time when the form has a Wizard descendant; the client
-   * POSTs `{ step, values }` here on each Next-button click and
-   * receives `{ ok }` (200) or `{ ok:false, errors }` (422).
-   */
-  withWizardUrl(url: string | undefined): this {
-    if (url === undefined) {
-      delete this._wizardUrl
-    } else {
-      this._wizardUrl = url
-    }
-    return this
-  }
-
-  getWizardUrl(): string | undefined { return this._wizardUrl }
-
-  // ─── Getters (used by route handlers) ────────────────
-
-  getFormId(): string { return this._formId }
-  getMethod(): FormMethod { return this._method }
-  getAction(): string | undefined { return this._action }
-  getFormValidators(): Validator[] { return this._formValidators }
-  getMutateData(): MutateDataHandler | undefined { return this._mutateData }
-  getMutateDataBeforeCreate(): MutateDataHandler | undefined { return this._mutateDataBeforeCreate }
-  getMutateDataBeforeUpdate(): MutateDataHandler | undefined { return this._mutateDataBeforeUpdate }
-  getBeforeSave(): LifecycleHandler<R> | undefined { return this._beforeSave }
-  getBeforeCreate(): LifecycleHandler<R> | undefined { return this._beforeCreate }
-  getBeforeUpdate(): LifecycleHandler<R> | undefined { return this._beforeUpdate }
-  getSave(): SaveHandler<R> | undefined { return this._save }
-  getHandleCreate(): SaveHandler<R> | undefined { return this._handleCreate }
-  getHandleUpdate(): SaveHandler<R> | undefined { return this._handleUpdate }
-  getAfterSave(): AfterSaveHandler<R> | undefined { return this._afterSave }
-  getAfterCreate(): AfterSaveHandler<R> | undefined { return this._afterCreate }
-  getAfterUpdate(): AfterSaveHandler<R> | undefined { return this._afterUpdate }
-  getRedirectAfterSave(): RedirectHandler<R> | undefined { return this._redirectAfterSave }
-  getFillFromRecord(): FillFromRecordHandler<R> | undefined { return this._fillFromRecord }
-  getMutateFormDataBeforeFill(): FillMutator<R> | undefined { return this._mutateFormDataBeforeFill }
-  getMutateFormDataAfterFill(): FillMutator<R> | undefined { return this._mutateFormDataAfterFill }
-  getLoadRecord(): LoadRecordHandler<R> | undefined { return this._loadRecord }
-  getSavedNotification(): SavedNotificationHandler<R> | null | undefined { return this._savedNotification }
-  getCreatedNotification(): SavedNotificationHandler<R> | null | undefined { return this._createdNotification }
-  isSavedNotificationDisabled(): boolean { return this._savedNotificationDisabled }
-
-  // ─── Serialization ────────────────────────────────────
-
-  getType(): string { return 'form' }
-
-  override toMeta(): FormMeta {
-    return {
-      type:   'form',
-      formId: this._formId,
-      method: this._method,
-      ...(this._action   !== undefined ? { action:   this._action   } : {}),
-      ...(this._values   !== undefined ? { values:   this._values   } : {}),
-      ...(this._errors   !== undefined ? { errors:   this._errors   } : {}),
-      ...(this._stateUrl  !== undefined ? { stateUrl:  this._stateUrl  } : {}),
-      ...(this._wizardUrl !== undefined ? { wizardUrl: this._wizardUrl } : {}),
-    }
-  }
-}
-
-/** @internal — reset the formId counter; tests use this to keep ids stable. */
-export function _resetFormIdSeq(): void {
-  _formIdSeq = 0
-}

package/src/elements/ListTabs.ts

@@ -1,28 +0,0 @@
-import { Element, type ElementMeta } from '../schema/Element.js'
-import type { ListTab } from '../Tab.js'
-
-/** Container element holding a strip of `ListTab` triggers above a Table.
- * Built by `ListPage.schema()` from `ListPage.getTabs()` — users typically
- * don't construct this directly. The renderer treats it like a flat row of
- * tab triggers (no body / no per-tab content), since each tab modifies the
- * shared Table query rather than swapping in different content. */
-export class ListTabs extends Element {
-  private constructor() { super() }
-
-  static make(): ListTabs {
-    return new ListTabs()
-  }
-
-  /** Set the tab list. Each entry is a `ListTab` instance with its own
-   * label/icon/badge/query modifier. */
-  tabs(tabs: ListTab[]): this {
-    this._children = tabs
-    return this
-  }
-
-  override getType(): string { return 'listTabs' }
-
-  override toMeta(): ElementMeta {
-    return { type: 'listTabs' }
-  }
-}