@pipelex/mthds-form 0.20.0 → 0.22.0

package/dist/field-renderer-lNhtw-Cz.d.ts

@@ -0,0 +1,215 @@
+import * as react from 'react';
+import { FileRunField, RunField } from './core/descriptor.js';
+import { FileSource } from './core/sources.js';
+
+/** The serializable value of a file field. URL is what the runner sends. */
+interface FileValue {
+    url?: string;
+    filename?: string;
+}
+/** What a host's upload resolves to: the stored file's URL, or its URL and name. */
+type UploadedFile = string | {
+    url: string;
+    filename?: string;
+};
+interface FileFieldProps {
+    field: FileRunField;
+    value: FileValue | undefined;
+    /**
+     * Called when a file is dropped/picked - the parent uploads and sets value.
+     *
+     * It may return the upload: a promise of what it stored, whose URL is the
+     * one the host writes into the value. The control then knows its upload's
+     * own result by that URL, so the dropped file's preview is kept for it
+     * whichever render the host writes it in, and a rejection retires the
+     * preview at once. Returning nothing leaves the control to judge the upload
+     * by when its value lands (docs/upload-seam.md).
+     *
+     * Absent means the host cannot store a file, and the control then offers no
+     * dropzone and no picker: the link input is open from the start, with a line
+     * saying a file cannot be uploaded here.
+     */
+    onDropFile?: (file: File) => void | PromiseLike<UploadedFile | void>;
+    /**
+     * Whether the link input is offered, `true` when absent. `false` removes the
+     * "paste a URL instead" toggle and the input behind it, and says nothing about
+     * which values are valid. With no `onDropFile` either, the control throws.
+     */
+    allowUrl?: boolean;
+    /** Manual URL paste / clear flows through here too. */
+    onChange: (value: FileValue | undefined) => void;
+    id: string;
+    /** Parent-driven async state. */
+    uploading?: boolean;
+    /**
+     * Why the host's upload of this field's file failed. Shown in the alert slot
+     * a refused format uses, until the host removes it. A clear or a typed link
+     * hides it until the host sends a different message or removes it; a refused
+     * pick shows its refusal in its place.
+     */
+    uploadError?: string;
+    /** Resolve a `pipelex-storage://` URI to a viewable URL (stored-file preview). */
+    resolveUrl?: (uri: string) => Promise<string | null>;
+    /**
+     * Where the field can take a file the host already stores. When given, the
+     * empty field offers "Choose from your team's files" under its own controls,
+     * and the chosen file is written through `onChange` as `{ url, filename }`,
+     * the value an upload writes. See docs/sources.md.
+     */
+    fileSource?: FileSource;
+    error?: string;
+    disabled?: boolean;
+}
+/** Document variant: a file shown as a PDF preview (or chip for other docs). */
+declare function DocumentField(props: FileFieldProps): react.JSX.Element;
+/** Image variant: a file shown as a real image preview. */
+declare function ImageField(props: FileFieldProps): react.JSX.Element;
+
+/**
+ * The moves a host makes to a list's rows, and what a move does to an id.
+ *
+ * A field's id is its value path, so a row's id is its position (`cvs.1`), and
+ * moving rows renumbers them. Two parties hold something by row and must move
+ * it when the rows move: the host, which keys what it knows about each upload
+ * by id, and the list control, which keys each row's React element by an
+ * identity of its own so the row's controls travel with it. `useMethodForm`
+ * makes every move itself (`removeItem`, `moveItem`), re-keys its own records
+ * as it does, and hands the list a log of those moves (`FieldEnv.rowMoves`),
+ * which the list replays on its row identities. One log, read by both, is what
+ * keeps them agreeing about which row is which. See docs/upload-seam.md, "What
+ * the form keeps by id moves with the rows it moves".
+ */
+/** One move of a list's rows, as a host records it for the list to replay. */
+interface RowMove {
+    /**
+     * The move's number: each move is numbered above the one before it, for as
+     * long as the host lives, so a list knows which moves it has replayed.
+     */
+    seq: number;
+    /** The list's id, the one its rows' ids extend (`cvs` for `cvs.1`). */
+    listId: string;
+    /**
+     * For each row of the list after the move, the index that row held before
+     * it. A row whose index is left out was removed.
+     */
+    order: readonly number[];
+}
+
+/**
+ * Ambient state that any field in the tree may need, threaded unchanged through
+ * the recursion so containers don't have to re-plumb it for every child.
+ */
+interface FieldEnv {
+    disabled?: boolean;
+    /**
+     * A file field asks its parent to upload; the parent sets the value later.
+     *
+     * It may return the upload: a promise of what it stored (`UploadedFile`),
+     * whose URL is the one the host writes at the id, rejected when the upload
+     * writes nothing. The field then knows its upload's own result by that URL,
+     * so the dropped file's preview is kept for it whichever render the host
+     * writes it in. A host that returns nothing must write the result in the
+     * render it takes the id out of `uploadingIds`. `useMethodForm`'s `dropFile`
+     * returns its upload. See docs/upload-seam.md, "The local preview belongs to
+     * the value it was made for".
+     *
+     * Its presence is the capability. A host that supplies it gets a dropzone on
+     * every file field; a host that does not gets no dropzone and no file picker,
+     * because a file taken with nowhere to go used to be dropped without a word.
+     * See docs/upload-seam.md, "Which ways into a file value a host offers".
+     */
+    onDropFile?: (id: string, file: File) => void | PromiseLike<UploadedFile | void>;
+    /**
+     * Whether a file field offers a link input, the way in that needs no upload.
+     * `true` when absent; `false` hides the "paste a URL instead" toggle and the
+     * input behind it on every file field.
+     *
+     * It governs that input and nothing else. A file value is a URL whichever way
+     * it arrived, so this says nothing about which values are valid: a web link
+     * the host writes is still shown on the field's card and can still be
+     * cleared. Setting it to `false` with no `onDropFile` leaves a file field no
+     * way in at all, and the field throws, naming its path, when it renders.
+     */
+    allowUrl?: boolean;
+    /**
+     * Removes a list's row on the host's side: `listId` is the list's id, the
+     * one its rows' ids extend (`cvs` for `cvs.1`), and `index` the row's.
+     *
+     * Its presence is the capability, and it is the host saying it follows
+     * rows. A list hands each removal to it instead of writing the shorter list
+     * through `onChange`, so the host removes the row and, in the same update,
+     * moves to its new id whatever it keeps by the id of a later row (an entry
+     * of `uploadErrors`, an upload in flight) and drops what it kept for the
+     * removed one. The list then holds back none of the host's `uploadErrors`,
+     * which it does for a host without this callback, since that host is
+     * handed only the shorter list and cannot re-key them. A host that also
+     * gives `rowMoves` records the removal there, and the list moves its rows'
+     * identities from that record alone. `useMethodForm`'s `removeItem` is this
+     * callback. See docs/upload-seam.md, "A list does not move a failure onto
+     * another row".
+     */
+    onRemoveItem?: (listId: string, index: number) => void;
+    /**
+     * Every move the host has made to a list's rows, oldest first, each
+     * numbered above the one before it (`RowMove`).
+     *
+     * A list keys each row's controls by an identity of its own, so that a row
+     * keeps them (a caret, a dropped file's preview, a dismissed failure) when
+     * an earlier row goes. It moves those identities itself for a removal it
+     * writes through `onChange`; for everything else a host does to the rows it
+     * would see only a new list, and match rows by position. Given this, a list
+     * replays every move made to it since it last rendered, the ones made to an
+     * outer list's rows included, which rename it, and moves no identity of its
+     * own accord: a host giving it records every move it makes here, a removal
+     * handed to `onRemoveItem` included. `useMethodForm`'s `rowMoves` is this
+     * log. See docs/upload-seam.md, "What the form keeps by id moves with the
+     * rows it moves".
+     */
+    rowMoves?: readonly RowMove[];
+    /** Ids currently mid-upload. */
+    uploadingIds?: ReadonlySet<string>;
+    /**
+     * Why an upload failed, keyed by the same id `onDropFile` was handed, so the
+     * message shows on the field that took the file rather than under the whole
+     * form, where only its wording could say which input failed.
+     *
+     * The map is the host's truth about each upload attempt: a host removes an
+     * entry when the next file is dropped at that id, and sets it again if that
+     * upload fails too. A clear or a typed link on the field hides the message
+     * until the host sends a different one or removes it, and a list holds back
+     * the entries a row removal left at a renumbered position, unless the host
+     * re-keys them itself through `onRemoveItem`. A host should
+     * also remove an entry once another file, or none, is written at its id, so
+     * that a control mounted there later shows no failure under it:
+     * `useMethodForm` does this for every write of its values.
+     */
+    uploadErrors?: ReadonlyMap<string, string>;
+    /** Resolve a `pipelex-storage://` URI to a browser-viewable URL (for previews
+     *  of already-stored files). */
+    resolveUrl?: (uri: string) => Promise<string | null>;
+    /**
+     * Where a file field can take a file the host already stores. Its presence
+     * is the capability, as `onDropFile`'s is: every empty file field then
+     * offers "Choose from your team's files", and a list of files offers it for
+     * several at once. The choice is written as `{ url, filename }`, exactly as
+     * an upload's result is. See docs/sources.md.
+     */
+    fileSource?: FileSource;
+}
+interface FieldRendererProps {
+    field: RunField;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    /** Unique, stable id used for label linkage and upload tracking. */
+    id: string;
+    error?: string;
+    env?: FieldEnv;
+}
+/**
+ * The single dispatch point: a normalized `RunField` → the matching control.
+ * Object and list fields recurse back through here, so the whole form is one
+ * data-driven tree with no per-type branching anywhere else.
+ */
+declare function FieldRenderer({ field, value, onChange, id, error, env }: FieldRendererProps): react.JSX.Element;
+
+export { DocumentField as D, type FieldEnv as F, ImageField as I, type RowMove as R, type UploadedFile as U, FieldRenderer as a, type FieldRendererProps as b, type FileValue as c };

package/dist/generative/index.d.ts

@@ -9,7 +9,7 @@ import { Components, Renderer } from '@json-render/react';
 import { B as BrandManifest } from '../manifest-DUeAWeqa.js';
 export { b as brandManifestSchema } from '../manifest-DUeAWeqa.js';
 import * as zod_v4_core from 'zod/v4/core';
-import { F as FieldEnv } from '../field-renderer-B3g16qZT.js';
+import { F as FieldEnv } from '../field-renderer-lNhtw-Cz.js';
 export { seedInputs } from '../core/seed.js';
 import '../core/contracts.js';
 import 'mthds/protocol';

package/dist/generative/index.js

@@ -1,5 +1,5 @@
 "use client";
-import { cn, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-CSLDIWB6.js';
+import { cn, brandInkClass, brandFillClass, brandFillInkClass, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, brandFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-5IZWP2X4.js';
 import '../chunk-ICUEHNEH.js';
 export { seedInputs } from '../chunk-VH5CDQDR.js';
 import '../chunk-EQJBM3NS.js';
@@ -2473,7 +2473,7 @@ function Steps({ props, children }) {
             {
               className: cn(
                 "flex h-6 w-6 items-center justify-center rounded-full text-[12px] font-semibold tabular-nums",
-                position < index ? "bg-primary/15 text-primary" : position === index ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"
+                position < index ? cn(brandFillStrongClass, brandFillInkClass) : position === index ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"
               ),
               children: position + 1
             }
@@ -2744,13 +2744,29 @@ function AppBar({ props }) {
         },
         link
       )) }) : null,
-      props.tag ? /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate rounded-lg border border-primary/40 bg-primary/10 px-2.5 py-1 font-mono text-[11px] text-primary", children: props.tag }) : null
+      props.tag ? /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: cn(
+            "min-w-0 truncate rounded-lg border border-primary/40 px-2.5 py-1 font-mono text-[11px]",
+            brandFillClass,
+            brandFillInkClass
+          ),
+          children: props.tag
+        }
+      ) : null
     ] })
   ] }) });
 }
 function Hero({ props }) {
   return /* @__PURE__ */ jsxs("section", { className: "pt-12 pb-10 sm:pt-14 sm:pb-12", children: [
-    props.eyebrow ? /* @__PURE__ */ jsx("p", { className: "mb-4 text-[11px] font-medium tracking-[0.15em] text-primary uppercase", children: props.eyebrow }) : null,
+    props.eyebrow ? /* @__PURE__ */ jsx(
+      "p",
+      {
+        className: cn("mb-4 text-[11px] font-medium tracking-[0.15em] uppercase", brandInkClass),
+        children: props.eyebrow
+      }
+    ) : null,
     /* @__PURE__ */ jsx("h1", { className: "max-w-2xl text-4xl font-bold tracking-tight text-foreground sm:text-[44px] sm:leading-[1.15]", children: props.headline }),
     props.lede ? /* @__PURE__ */ jsx("p", { className: "mt-4 max-w-2xl text-[17px] leading-relaxed text-muted-foreground", children: props.lede }) : null
   ] });
@@ -2797,7 +2813,7 @@ function Section({ props, children }) {
   return /* @__PURE__ */ jsxs("section", { className: "border-t border-border py-9 first:border-t-0 first:pt-0", children: [
     /* @__PURE__ */ jsxs("div", { className: "mb-6", children: [
       /* @__PURE__ */ jsxs("div", { className: "flex items-baseline gap-3", children: [
-        props.number ? /* @__PURE__ */ jsx("span", { className: "font-mono text-[12px] text-primary", children: props.number }) : null,
+        props.number ? /* @__PURE__ */ jsx("span", { className: cn("font-mono text-[12px]", brandInkClass), children: props.number }) : null,
         /* @__PURE__ */ jsx("h2", { className: "text-xl font-semibold tracking-tight text-foreground", children: props.title })
       ] }),
       props.lede ? /* @__PURE__ */ jsx("p", { className: "mt-1.5 text-sm text-muted-foreground", children: props.lede }) : null