@pipelex/mthds-form 0.18.0 → 0.20.0

package/dist/core/sources.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The two optional host seams beside the upload: a **file source**, which lets
+ * a file field take a file the host already stores, and an **example source**,
+ * which lets a whole form take a set of values someone saved for the method.
+ *
+ * The kernel states the shapes and applies the answers; the host answers. It
+ * knows nothing of any platform's routes, records or permissions: a host maps
+ * its own list onto these shapes, and a host that gives neither seam gets the
+ * form it had before. The controls that use them are `./react`'s
+ * (`FilePicker`, `FillWithExample`), and docs/sources.md is the contract.
+ *
+ * Shapes and pure functions only, so a host's server can import the types it
+ * answers with, and the rules that write an answer into a value are tested in
+ * node. No React, no fetch.
+ */
+/** Whose files a file source lists: the person's own, or the whole team's. */
+type FileSourceScope = 'mine' | 'everyone';
+/** One page of a file source's list, as the picker asks for it. */
+interface FileSourceQuery {
+    /** What the person searched for, trimmed; empty when they searched for nothing. */
+    search: string;
+    /** Whose files to list. */
+    scope: FileSourceScope;
+    /**
+     * The MIME types the field accepts, after any narrowing a host applied
+     * (`narrowFileFormats`), in the field's own order. The list must hold only
+     * files of these types: the picker writes what is chosen straight into the
+     * field, and a field that refuses a dropped file of another type must not
+     * be handed one this way.
+     */
+    mediaTypes: readonly string[];
+    /** Where to continue: absent for the first page, else the previous page's `nextCursor`. */
+    cursor?: string;
+    /** Aborted when the answer is no longer wanted: a newer search, a closed picker. */
+    signal: AbortSignal;
+}
+/** One row of a file source's list: a file the host already stores. */
+interface SourceFile {
+    /** The row's identity in the host's list, which a choice is kept by. */
+    id: string;
+    /**
+     * The stored file's address, written into the field as its `url`, exactly as
+     * an upload's result is. Several rows may share one address.
+     */
+    url: string;
+    /** The file's name, shown on the row and written into the field as its `filename`. */
+    name: string;
+    /** The file's MIME type, which names its format on the row. */
+    mediaType?: string;
+    /** The file's size in bytes. */
+    size?: number;
+    /** How the file came to be. A `test` file is marked "Test file" at the head of its row's second line. */
+    kind?: 'uploaded' | 'generated' | 'test';
+    /** When the file was stored, as an ISO 8601 timestamp; the row says it as a date. */
+    createdAt?: string;
+    /**
+     * Where the file came from, in the host's own words ("Uploaded by Ana",
+     * "Made by Invoice extraction"), shown on the row's second line as it is.
+     */
+    origin?: string;
+}
+/** One page of a file source's answer. */
+interface FileSourcePage {
+    /** The page's files, newest first. A page may be empty and still carry a cursor. */
+    files: readonly SourceFile[];
+    /** Where the next page starts, or nothing when this page is the last. */
+    nextCursor?: string | null;
+}
+/**
+ * Where a file field can take a file the host already stores. When a form has
+ * one, every file field offers "Choose from your team's files", and a list of
+ * files offers it for several at once.
+ */
+interface FileSource {
+    /** Lists one page of files for a query. Rejecting shows the failure with Try again. */
+    list: (query: FileSourceQuery) => Promise<FileSourcePage>;
+    /** Which of Mine and Everyone the picker opens on. */
+    initialScope: FileSourceScope;
+}
+/** One example of a method: a name and the inputs a run of it sends. */
+interface FormExample {
+    /** The example's identity in the host's list. */
+    id: string;
+    /** The example's name, shown on its row. */
+    name: string;
+    /**
+     * The inputs as a run takes them: each input `{ concept, content }`, an
+     * optional input left out, an empty plural input a bare `[]`. It is the
+     * shape `apiInputsFromRunValues` produces, so a host saves an example from
+     * `form.inputs` and hands it back as it is.
+     */
+    inputs: Readonly<Record<string, unknown>>;
+}
+/** One page of an example source's list. */
+interface ExampleSourceQuery {
+    /** Where to continue: absent for the first page, else the previous page's `nextCursor`. */
+    cursor?: string;
+    /** Aborted when the answer is no longer wanted. */
+    signal: AbortSignal;
+}
+/** One page of an example source's answer. */
+interface ExampleSourcePage {
+    /** The page's examples, in the order the list shows them. */
+    examples: readonly FormExample[];
+    /** Where the next page starts, or nothing when this page is the last. */
+    nextCursor?: string | null;
+}
+/**
+ * Where a form can take a whole set of values. When a form has one, it offers
+ * "Fill with an example". `rename` and `delete` are capabilities: each is
+ * offered on a row's menu only when given, so a host gives them only to a
+ * person allowed to change examples.
+ */
+interface ExampleSource {
+    /** Lists one page of the method's examples. Rejecting shows the failure with Try again. */
+    list: (query: ExampleSourceQuery) => Promise<ExampleSourcePage>;
+    /**
+     * Renames an example. Resolving to the example as stored replaces the row;
+     * resolving to nothing keeps the row under the new name.
+     */
+    rename?: (example: FormExample, name: string) => Promise<FormExample | void>;
+    /** Deletes an example. Asked for only after the person confirmed it. */
+    delete?: (example: FormExample) => Promise<void>;
+    /**
+     * Whether "Fill with an example" is left out while the method has no
+     * example. `false` by default, when the empty list says how to make one.
+     * A host sets it for a person who cannot save an example, to whom an empty
+     * list has nothing to offer; the form then asks for the first page as it
+     * mounts, to know whether to offer the control.
+     */
+    hideWhenEmpty?: boolean;
+}
+/** What a chosen file writes into its field: the same `{ url, filename }` an upload writes. */
+declare function sourceFileValue(file: SourceFile): {
+    url: string;
+    filename: string;
+};
+/**
+ * A list of files with the chosen files written into it, in the order they
+ * were chosen: first into the rows that hold no file yet (a row the person
+ * added and left empty), then as new rows after the last. A file whose address
+ * the list already holds is not written again, and neither is a second choice
+ * of one address: two rows of a source may name the same stored file. Returns
+ * a new array and leaves `held` as it was.
+ */
+declare function addChosenFiles(held: readonly unknown[] | undefined, chosen: readonly SourceFile[]): unknown[];
+/**
+ * How many files a list may still take from a source: its bound less the files
+ * it holds, since `addChosenFiles` writes into its empty rows before adding
+ * any. `undefined` when the list has no bound.
+ */
+/**
+ * How many files `addChosenFiles` writes for `chosen` into `held`: the choices
+ * whose address the list does not hold yet, each address once. This is what a
+ * choice spends of `roomForChosenFiles`, so a held file chosen again, or a
+ * second row naming a chosen file, takes no room.
+ */
+declare function chosenFilesAdded(held: readonly unknown[] | undefined, chosen: readonly SourceFile[]): number;
+declare function roomForChosenFiles(held: readonly unknown[] | undefined, maxItemCount: number | undefined): number | undefined;
+
+export { type ExampleSource, type ExampleSourcePage, type ExampleSourceQuery, type FileSource, type FileSourcePage, type FileSourceQuery, type FileSourceScope, type FormExample, type SourceFile, addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue };

package/dist/core/sources.js

@@ -0,0 +1,3 @@
+export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-EQJBM3NS.js';
+//# sourceMappingURL=sources.js.map
+//# sourceMappingURL=sources.js.map

package/dist/core/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sources.js"}

package/dist/core/values.d.ts

@@ -55,6 +55,30 @@ declare function storeInputDataFromRunValues(values: Dict, fields: RunField[], i
  *   the envelope agree; the bare form runs today and stays correct after.)
  */
 declare function apiInputsFromRunValues(values: Dict, fields: RunField[], inputSchemas: InputSchemas): Record<string, unknown>;
+/**
+ * The form values a set of run inputs stands for: the inverse of
+ * `apiInputsFromRunValues`, for inputs saved from a form (an example) and
+ * handed back to one.
+ *
+ * Each input is read as a run sends it, `{ concept, content }`, or as its bare
+ * content (the empty plural `[]`), and its content is turned back into the
+ * control's own shape. Only an object naming its concept is read as that
+ * envelope: a structure sent bare may well have a property called `content`. An input the inputs do not hold is left empty, and an
+ * optional structure they do not hold stays closed: the inputs are the whole
+ * run, so an input they left out was left out of the run too. An input no
+ * field takes is ignored.
+ */
+declare function runValuesFromInputs(inputs: Readonly<Dict> | undefined, fields: RunField[]): Dict;
+/**
+ * Whether two sets of form values send the same run.
+ *
+ * Compared in the shape a run takes, so the differences a run cannot see do
+ * not count: a text typed and then erased is the blank it started as, and an
+ * optional structure opened and left empty is the closed one it was. What
+ * "Fill with an example" asks before replacing is the work a person did, and
+ * a value that sends nothing is no work to lose.
+ */
+declare function sameRunValues(a: Dict, b: Dict, fields: RunField[]): boolean;
 /** One named output pulled out of a run's working memory, ready to render. */
 interface OutputEntry {
     /** The output variable key (mono). */
@@ -96,4 +120,4 @@ declare function fieldsForContract(contract: PipeIOContract | undefined, descrip
  */
 declare function setValueAtPath(root: Dict, path: string[], value: unknown): Dict;
 
-export { type OutputEntry, apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues };
+export { type OutputEntry, apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromInputs, runValuesFromStore, sameRunValues, setValueAtPath, storeInputDataFromRunValues };

package/dist/core/values.js

@@ -1,11 +1,11 @@
-export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues } from '../chunk-PQ3ZX5MJ.js';
+export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromInputs, runValuesFromStore, sameRunValues, setValueAtPath, storeInputDataFromRunValues } from '../chunk-ZX52CQJ4.js';
+import '../chunk-ZB4RYUKV.js';
+import '../chunk-XCO6GTEC.js';
+import '../chunk-E6BIXJ6C.js';
 import '../chunk-XO5OENNF.js';
-import '../chunk-HQMXXK5X.js';
-import '../chunk-HVWE3TTC.js';
 import '../chunk-OD3VYXUY.js';
 import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
-import '../chunk-XCO6GTEC.js';
 import '../chunk-GKV77RAS.js';
 //# sourceMappingURL=values.js.map
 //# sourceMappingURL=values.js.map

package/dist/core/wire-format.d.ts

@@ -40,6 +40,16 @@ declare function deflateInput(value: unknown, conceptCode: string): unknown;
  * - { concept, content } → content (for custom concepts)
  */
 declare function inflateInput(value: unknown, conceptCode: string): unknown;
+/**
+ * Detect the fully-qualified wrapper form `{ concept: "...", content: ... }`.
+ * pipelex accepts this for any concept (native or custom), and the mthds-inputs
+ * agent skill writes it by default for disambiguation. We unwrap before applying
+ * concept-specific inflation so the form populates correctly.
+ */
+declare function isWrappedForm(value: unknown): value is {
+    concept: string;
+    content: unknown;
+};
 interface InputSchema {
     concept_ref: string;
     json_schema?: Record<string, unknown>;
@@ -92,4 +102,4 @@ declare function pruneEmptyOptionals(value: unknown, rawSchema: Record<string, u
  */
 declare function inflateAllInputs(simplifiedData: Record<string, unknown>, inputSchemas: Record<string, InputSchema>): Record<string, unknown>;
 
-export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, pruneEmptyOptionals, resolveConceptCode };
+export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, isWrappedForm, pruneEmptyOptionals, resolveConceptCode };

package/dist/core/wire-format.js

@@ -1,4 +1,4 @@
-export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, pruneEmptyOptionals, resolveConceptCode } from '../chunk-HQMXXK5X.js';
+export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, isWrappedForm, pruneEmptyOptionals, resolveConceptCode } from '../chunk-E6BIXJ6C.js';
 import '../chunk-OD3VYXUY.js';
 import '../chunk-V3OV2XQT.js';
 import '../chunk-GKV77RAS.js';

package/dist/{field-renderer-C5Onx6qB.d.ts → field-renderer-B3g16qZT.d.ts}

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { RunField } from './core/descriptor.js';
+import { FileSource } from './core/sources.js';
 
 /**
  * Ambient state that any field in the tree may need, threaded unchanged through
@@ -45,6 +46,14 @@ interface FieldEnv {
     /** 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;

package/dist/generative/index.d.ts

@@ -9,11 +9,12 @@ 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-C5Onx6qB.js';
+import { F as FieldEnv } from '../field-renderer-B3g16qZT.js';
 export { seedInputs } from '../core/seed.js';
 import '../core/contracts.js';
 import 'mthds/protocol';
 import '../core/file-formats.js';
+import '../core/sources.js';
 
 /**
  * Whether a spec is one this catalog can render - the check every source

package/dist/generative/index.js

@@ -1,19 +1,20 @@
 "use client";
-import { cn, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-YY3JI6VI.js';
+import { cn, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-CSLDIWB6.js';
 import '../chunk-ICUEHNEH.js';
 export { seedInputs } from '../chunk-VH5CDQDR.js';
+import '../chunk-EQJBM3NS.js';
 import '../chunk-RRTI7AIR.js';
-import '../chunk-PQ3ZX5MJ.js';
-import '../chunk-XO5OENNF.js';
-import '../chunk-HQMXXK5X.js';
+import '../chunk-ZX52CQJ4.js';
 import { isNativeValueNode, readDateContent, formatDateContent, isNativeHtmlNode, isNativeDateNode, isNativeCompositeNode } from '../chunk-CM4KVG53.js';
 export { brandManifestSchema } from '../chunk-QFX332LE.js';
-import '../chunk-HVWE3TTC.js';
+import '../chunk-ZB4RYUKV.js';
+import '../chunk-FABY3DEY.js';
+import '../chunk-XCO6GTEC.js';
+import '../chunk-E6BIXJ6C.js';
+import '../chunk-XO5OENNF.js';
 import '../chunk-OD3VYXUY.js';
 import '../chunk-WYH56SOZ.js';
 import { hasOwnProp } from '../chunk-V3OV2XQT.js';
-import '../chunk-FABY3DEY.js';
-import '../chunk-XCO6GTEC.js';
 import '../chunk-GKV77RAS.js';
 import { defineSchema, defineCatalog, validateSpec, compileSpecStream } from '@json-render/core';
 import { z } from 'zod';