@pipelex/mthds-form 0.1.0

package/dist/descriptor-X6MwFIWu.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The `RunField` descriptor - the consumer-facing currency of the form kernel.
+ *
+ * A method's inputs arrive from the API as a map of variable name →
+ * `PipeInputContract` ({ concept_ref, json_schema }). That JSON Schema is rich
+ * (Pydantic-generated) and not pleasant to render directly. `buildRunFields`
+ * (in `derive.ts`) normalizes it once into a flat, recursive `RunField[]`
+ * descriptor that the presentational field components consume - so the
+ * components never touch raw JSON Schema, and stories can describe any input
+ * shape declaratively.
+ *
+ * Pure module: no React, no API calls. Trivially unit-testable.
+ */
+type RunFieldKind = 'text' | 'prose' | 'date' | 'number' | 'boolean' | 'enum' | 'document' | 'image' | 'object' | 'list' | 'unknown';
+interface RunFieldCommon {
+    /** The variable identifier as written in the method (rendered in mono). */
+    name: string;
+    /** Human label; falls back to `name` when absent. */
+    title?: string;
+    /** The concept this input carries, e.g. `native.Document`, `demo.Invoice`. */
+    conceptRef?: string;
+    /** One-line helper text shown under the label. */
+    description?: string;
+    /** Required inputs always show; optional ones can collapse. */
+    required: boolean;
+    /**
+     * Whether Run waits for this input - set on TOP-LEVEL fields only, straight
+     * from `inputMustBeFilled` (see `mustBeFilled` in `readiness.ts` for why this
+     * is not the same question as `required`). Nested fields leave it undefined;
+     * they are gated through their parent's `fieldFilled`.
+     */
+    gating?: boolean;
+}
+interface TextRunField extends RunFieldCommon {
+    kind: 'text';
+    placeholder?: string;
+}
+interface ProseRunField extends RunFieldCommon {
+    kind: 'prose';
+    placeholder?: string;
+}
+interface DateRunField extends RunFieldCommon {
+    kind: 'date';
+    /**
+     * True when the backing schema is `format: date-time`: the stored value is a
+     * full RFC 3339 timestamp (`2026-07-06T00:00:00Z`) so it passes the API's
+     * `date-time` validation, even though the control only asks for a day. False
+     * for a bare `format: date`, where the value stays `YYYY-MM-DD`.
+     */
+    datetime: boolean;
+}
+interface NumberRunField extends RunFieldCommon {
+    kind: 'number';
+    integer: boolean;
+    min?: number;
+    max?: number;
+}
+interface BooleanRunField extends RunFieldCommon {
+    kind: 'boolean';
+}
+interface EnumRunField extends RunFieldCommon {
+    kind: 'enum';
+    options: string[];
+}
+interface FileRunField extends RunFieldCommon {
+    kind: 'document' | 'image';
+    /** Accept hint shown to the user, e.g. "PDF, PNG, JPG". */
+    accept?: string;
+}
+interface ObjectRunField extends RunFieldCommon {
+    kind: 'object';
+    fields: RunField[];
+}
+interface ListRunField extends RunFieldCommon {
+    kind: 'list';
+    /** The element descriptor (its `name` is unused; the index labels items). */
+    item: RunField;
+}
+interface UnknownRunField extends RunFieldCommon {
+    kind: 'unknown';
+}
+type RunField = TextRunField | ProseRunField | DateRunField | NumberRunField | BooleanRunField | EnumRunField | FileRunField | ObjectRunField | ListRunField | UnknownRunField;
+/** The short, friendly category label for a concept_ref (drives the pill dot). */
+type ConceptCategory = 'text' | 'date' | 'document' | 'image' | 'number' | 'boolean' | 'choice' | 'structured' | 'list';
+declare function conceptCategory(field: RunField): ConceptCategory;
+
+export { type BooleanRunField as B, type ConceptCategory as C, type DateRunField as D, type EnumRunField as E, type FileRunField as F, type ListRunField as L, type NumberRunField as N, type ObjectRunField as O, type ProseRunField as P, type RunField as R, type TextRunField as T, type UnknownRunField as U, type RunFieldCommon as a, type RunFieldKind as b, conceptCategory as c };

package/dist/react/index.d.ts

@@ -0,0 +1,276 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { R as RunField, B as BooleanRunField, D as DateRunField, E as EnumRunField, F as FileRunField, L as ListRunField, N as NumberRunField, O as ObjectRunField, P as ProseRunField, T as TextRunField, U as UnknownRunField, C as ConceptCategory } from '../descriptor-X6MwFIWu.js';
+
+/**
+ * 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. */
+    onDropFile?: (id: string, file: File) => void;
+    /** Ids currently mid-upload. */
+    uploadingIds?: ReadonlySet<string>;
+    /** Resolve a `pipelex-storage://` URI to a browser-viewable URL (for previews
+     *  of already-stored files). */
+    resolveUrl?: (uri: string) => Promise<string | null>;
+}
+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;
+
+interface BooleanFieldProps {
+    field: BooleanRunField;
+    value: boolean | undefined;
+    onChange: (value: boolean) => void;
+    id: string;
+    disabled?: boolean;
+}
+/**
+ * A toggle. Unlike the other fields the label sits inline with the control on a
+ * single hairline row - a boolean reads better as a switchable statement than as
+ * a labelled box.
+ */
+declare function BooleanField({ field, value, onChange, id, disabled }: BooleanFieldProps): react.JSX.Element;
+
+interface DateFieldProps {
+    field: DateRunField;
+    value: string | undefined;
+    onChange: (value: string | undefined) => void;
+    id: string;
+    error?: string;
+    disabled?: boolean;
+}
+/**
+ * A calendar-date input. The control only asks for a day (no hand-typed
+ * hours/seconds); for a `date-time` concept it stores midnight-UTC so the value
+ * still satisfies the API's `date-time` format.
+ */
+declare function DateField({ field, value, onChange, id, error, disabled }: DateFieldProps): react.JSX.Element;
+
+interface EnumFieldProps {
+    field: EnumRunField;
+    value: string | undefined;
+    onChange: (value: string | undefined) => void;
+    id: string;
+    error?: string;
+    disabled?: boolean;
+}
+/**
+ * Pick-one. A short option set (≤4, each label brief) renders as a segmented
+ * control - every choice visible at a glance - and falls back to a select once
+ * the set grows past what fits on a row.
+ */
+declare function EnumField({ field, value, onChange, id, error, disabled }: EnumFieldProps): react.JSX.Element;
+
+/** The serializable value of a file field. URL is what the runner sends. */
+interface FileValue {
+    url?: string;
+    filename?: string;
+}
+interface FileFieldProps {
+    field: FileRunField;
+    value: FileValue | undefined;
+    /** Called when a file is dropped/picked - the parent uploads and sets value. */
+    onDropFile: (file: File) => void;
+    /** Manual URL paste / clear flows through here too. */
+    onChange: (value: FileValue | undefined) => void;
+    id: string;
+    /** Parent-driven async state. */
+    uploading?: boolean;
+    /** Resolve a `pipelex-storage://` URI to a viewable URL (stored-file preview). */
+    resolveUrl?: (uri: string) => Promise<string | null>;
+    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;
+
+interface ListFieldProps {
+    field: ListRunField;
+    value: unknown[] | undefined;
+    onChange: (value: unknown[]) => void;
+    id: string;
+    error?: string;
+    env?: FieldEnv;
+}
+/**
+ * A repeatable list of one element type. Each item is an indexed row with its
+ * own remove control; "Add" appends a fresh entry. The element renders through
+ * the same `FieldRenderer`, so a list of documents gets dropzones and a list of
+ * structured concepts gets nested cards - no special-casing per element type.
+ */
+declare function ListField({ field, value, onChange, id, error, env }: ListFieldProps): react.JSX.Element;
+
+interface NumberFieldProps {
+    field: NumberRunField;
+    value: number | undefined;
+    onChange: (value: number | undefined) => void;
+    id: string;
+    error?: string;
+    disabled?: boolean;
+}
+/** Numeric input with steppers and min/max clamping. */
+declare function NumberField({ field, value, onChange, id, error, disabled }: NumberFieldProps): react.JSX.Element;
+
+interface ObjectFieldProps {
+    field: ObjectRunField;
+    value: Record<string, unknown> | undefined;
+    onChange: (value: Record<string, unknown>) => void;
+    id: string;
+    error?: string;
+    env?: FieldEnv;
+}
+/**
+ * A structured concept: its sub-fields rendered inside one hairline-grouped
+ * card so nesting stays legible. Empty optional sub-fields collapse behind a
+ * "+ N optional" toggle - required and already-filled fields always show.
+ */
+declare function ObjectField({ field, value, onChange, id, error, env }: ObjectFieldProps): react.JSX.Element;
+
+interface TextFieldProps {
+    field: TextRunField;
+    value: string | undefined;
+    onChange: (value: string | undefined) => void;
+    id: string;
+    error?: string;
+    disabled?: boolean;
+}
+/** Single-line string input (short native.Text or a plain string property). */
+declare function TextField({ field, value, onChange, id, error, disabled }: TextFieldProps): react.JSX.Element;
+interface ProseFieldProps {
+    field: ProseRunField;
+    value: string | undefined;
+    onChange: (value: string | undefined) => void;
+    id: string;
+    error?: string;
+    disabled?: boolean;
+}
+/**
+ * Multi-line free text. Auto-grows with content (`field-sizing-content`) so long
+ * prompts don't trap the user in a tiny scrollbox - the field that carries most
+ * of a method's intent should feel roomy.
+ */
+declare function ProseField({ field, value, onChange, id, error, disabled }: ProseFieldProps): react.JSX.Element;
+
+interface UnknownFieldProps {
+    field: UnknownRunField;
+    value: string | undefined;
+    onChange: (value: string | undefined) => void;
+    id: string;
+    error?: string;
+    disabled?: boolean;
+}
+/**
+ * Escape hatch for a concept whose shape we can't map to a known control. Rather
+ * than block the run, we let the user hand-write the value as JSON - rare, but it
+ * keeps every method runnable instead of dead-ending on an unusual input.
+ */
+declare function UnknownField({ field, value, onChange, id, error, disabled }: UnknownFieldProps): react.JSX.Element;
+
+interface FieldShellProps {
+    name: string;
+    title?: string;
+    conceptRef?: string;
+    category: ConceptCategory;
+    description?: string;
+    required: boolean;
+    /** Validation message; renders in danger text under the control. */
+    error?: string;
+    /** Links the rendered name to the control for screen readers. */
+    htmlFor?: string;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * The label / type / description / error chrome around a single input control.
+ * Every field type composes this so the form reads as one consistent column -
+ * the control itself is the only thing that varies.
+ */
+declare function FieldShell({ name, title, conceptRef, category, description, required, error, htmlFor, children, className, }: FieldShellProps): react.JSX.Element;
+
+interface ConceptPillProps {
+    /** The concept identifier, e.g. `native.Document`, `demo.Invoice`. */
+    conceptRef?: string;
+    category: ConceptCategory;
+    className?: string;
+}
+/**
+ * The small monospace type tag shown beside an input's name. Mono + a line icon
+ * (never a colored chip) keeps the technical Pipelex voice without spending a
+ * chromatic accent - the concept *type* is information, not a status.
+ */
+declare function ConceptPill({ conceptRef, category, className }: ConceptPillProps): react.JSX.Element;
+
+interface OptionalToggleProps {
+    /** How many empty optional entries are currently hidden. */
+    count: number;
+    expanded: boolean;
+    onToggle: () => void;
+    /** "field" inside a concept, "input" at the top level. */
+    noun?: 'field' | 'input';
+}
+/**
+ * The disclosure for empty optional entries. Optional inputs stay hidden until
+ * the user asks for them - required (and already-filled) entries always show, so
+ * the form opens at its simplest and grows only on demand. Used at the top level
+ * and inside every structured concept, at any nesting depth.
+ */
+declare function OptionalToggle({ count, expanded, onToggle, noun }: OptionalToggleProps): react.JSX.Element;
+
+declare const fieldControlClass: string;
+
+interface FieldStrings {
+    /** Badge on an optional field's header row. */
+    optionalBadge: string;
+    selectPlaceholder: string;
+    typeValuePlaceholder: string;
+    writeHerePlaceholder: string;
+    /** Helper under the raw-JSON escape hatch. */
+    jsonHint: string;
+    decrease: string;
+    increase: string;
+    noItemsYet: string;
+    addItem: string;
+    removeItemAria: (index: number) => string;
+    itemsCount: (count: number) => string;
+    uploading: string;
+    dropToUpload: string;
+    dropOrBrowse: string;
+    pasteUrlInstead: string;
+    urlPlaceholder: string;
+    uploadedFile: string;
+    preview: string;
+    removeFileAria: string;
+    previewUnavailablePdf: string;
+    /** The optional-entries disclosure ("field" inside a concept, "input" at top level). */
+    hideOptionalFields: string;
+    hideOptionalInputs: string;
+    optionalFieldsCount: (count: number) => string;
+    optionalInputsCount: (count: number) => string;
+}
+declare const DEFAULT_FIELD_STRINGS: FieldStrings;
+/** Inject host-app strings over the English defaults for every control below. */
+declare function FieldStringsProvider({ strings, children, }: {
+    strings: Partial<FieldStrings>;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The strings the nearest provider supplies (English defaults when none does). */
+declare function useFieldStrings(): FieldStrings;
+
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, type FieldEnv, FieldRenderer, type FieldRendererProps, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, ImageField, ListField, NumberField, ObjectField, OptionalToggle, ProseField, TextField, UnknownField, fieldControlClass, useFieldStrings };