@pipelex/mthds-form 0.27.0 → 0.29.0

package/dist/core/gate.js

@@ -1,8 +1,8 @@
-export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-4DPYGNJ3.js';
+export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-IBBAJXIO.js';
 import '../chunk-E6BIXJ6C.js';
+import '../chunk-XO5OENNF.js';
 import '../chunk-Y2ND6W4W.js';
 import '../chunk-LBFZXYCY.js';
-import '../chunk-XO5OENNF.js';
 import '../chunk-OD3VYXUY.js';
 import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';

package/dist/core/humanize.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What a person reads in place of an identifier: a field's name, and the value
+ * of a choice. Headless, so a host that draws its own choice control, a server
+ * that writes a summary and the package's own controls all word a value the
+ * same way.
+ *
+ * The descriptor carries an enum's values and nothing else: the standard has no
+ * display label for an option, and none is wanted. Its label is derived from
+ * the value here, by rule, and only what a person reads changes: the value a
+ * form stores, the JSON view, the copy control and the download all keep the
+ * code.
+ */
+/**
+ * `full_name` → `Full name`. Only the first word is capitalised: these are
+ * labels, not titles, and Title Case on every word reads as a form from 2009.
+ * Takes IDENTIFIERS only - snake_case or kebab-case names, where a separator
+ * is structure. An authored `title` never goes through here: it is already
+ * human-facing, and its hyphens are spelling (`E-mail address`), not structure.
+ */
+declare function humanizeFieldName(name: string): string;
+/**
+ * An enum CODE as words: `keynote` → `Keynote`, `unit_price_differs_from_po`
+ * → `Unit price differs from po`, `HIGH_RISK` → `High risk`.
+ *
+ * It is `humanizeFieldName`, applied after an all-caps code of several words is
+ * lowercased. The capitals of `HIGH_RISK` are a convention of the code, not an
+ * emphasis its author meant, and "HIGH RISK" on a sentence-case page reads as
+ * an alarm.
+ *
+ * A single all-caps token is left exactly as written: `USD`, `EUR`, `OK` and
+ * `HIGH` hold no separator, and a lone capitalised word is far more often an
+ * acronym, a unit or a currency than a shouted word, so lowercasing it would
+ * misspell it ("Usd"). Only a code that is several words joined by `_` or `-`
+ * is taken to be capitalised by convention.
+ *
+ * Acronyms inside a longer code are not guessed: `po` stays `po` where a reader
+ * expects `PO`, just as a field name does. That is the price of deriving the
+ * label from the value rather than carrying one on the wire, and it is paid
+ * knowingly: a method's author who wants `PO` read writes the code so that it
+ * reads.
+ *
+ * Only a code is humanised. A value that is not an identifier is authored
+ * words already, and its separators are spelling rather than structure, so it
+ * is shown verbatim: `18-24`, `N/A` and `Very satisfied` do not start with a
+ * letter or hold something other than letters, digits, `_` and `-`. That is
+ * the line `humanizeFieldName` draws between an identifier and an authored
+ * title.
+ *
+ * This words ONE code, with no knowledge of the enum it belongs to. A choice
+ * control goes one step further: when two options of one enum would read the
+ * same, it shows that enum's codes instead (see `enumValueLabeler`).
+ */
+declare function humanizeEnumValue(code: string): string;
+/**
+ * How ONE enum's values read, as words: the labeler every choice control and
+ * every enum result goes through, so the options a form offers, the value a
+ * result shows and a host's own chips read alike. Built from the enum's
+ * options, it maps a value to what a person reads.
+ *
+ * A declared option reads as words (`humanizeEnumValue`), except in two cases,
+ * where the code is shown as written:
+ *
+ * - **Every option, when two of them would read the same.** `high_risk` and
+ *   `HIGH_RISK`, or `foo-bar` and `foo_bar`, are distinct codes that humanise
+ *   to one label, and a person offered two identical choices is choosing
+ *   blind. Wording the others while showing those two as codes would make one
+ *   enum read in two registers, so the whole enum falls back.
+ * - **A value the enum does not declare.** It is the payload disagreeing with
+ *   its descriptor, and worded it could pass for an option it is not.
+ *
+ * This is the wording, not the decision to word: a builder-facing surface that
+ * must show the code the bundle spells (the control set's `studio`
+ * presentation) does not call it.
+ */
+declare function enumValueLabeler(options: readonly string[]): (value: string) => string;
+
+export { enumValueLabeler, humanizeEnumValue, humanizeFieldName };

package/dist/core/humanize.js

@@ -0,0 +1,3 @@
+export { enumValueLabeler, humanizeEnumValue, humanizeFieldName } from '../chunk-GHVVULHY.js';
+//# sourceMappingURL=humanize.js.map
+//# sourceMappingURL=humanize.js.map

package/dist/core/humanize.js.map

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

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export { BooleanRunField, ConceptCategory, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, RunField, RunFieldCommon, RunFieldKind, TextConstraints, TextRunField, UnknownRunField, conceptCategory } from './descriptor.js';
+export { enumValueLabeler, humanizeEnumValue, humanizeFieldName } from './humanize.js';
 export { IOMultiplicity, InputForm, InputFormTopLevelField, OutputForm, PipeIOContract, PipeIOContracts, PipeInputContract, PipeInputFormDescriptor, PipeOutputContract, PipeOutputFormDescriptor } from 'mthds/protocol';
 export { buildResultField, buildRunFields, getPipeInputForm } from './derive.js';
 export { getPipeOutputForm } from './output-form.js';

package/dist/core/index.js

@@ -1,20 +1,21 @@
 export { planFileSave, planStuffSave } from '../chunk-4VAO6BDE.js';
 export { closeOptionalStructures, openOptionalStructures, seedInputs, seedObjectValue } from '../chunk-VH5CDQDR.js';
-export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-NSHGLM6A.js';
+export { addChosenFiles, chosenFilesAdded, roomForChosenFiles, sourceFileValue } from '../chunk-L23R3JNQ.js';
 export { collectStuffFiles } from '../chunk-56WECFBD.js';
 export { describeValidationError, displayValue, valueAtProperty } from '../chunk-RPA7DNSK.js';
 export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromInputs, runValuesFromStore, sameRunValues, setValueAtPath, storeInputDataFromRunValues } from '../chunk-ZX52CQJ4.js';
+export { enumValueLabeler, humanizeEnumValue, humanizeFieldName } from '../chunk-GHVVULHY.js';
 export { narrowFileFormats } from '../chunk-CAKQ5VFT.js';
 export { NATIVE_CHOICE_CONCEPT_REF, NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, NATIVE_PAGE_CONCEPT_REF, NATIVE_RATING_CONCEPT_REF, NATIVE_SEARCH_RESULT_CONCEPT_REF, NATIVE_YES_NO_CONCEPT_REF, TYPED_SCALAR_MARKERS, citedSource, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isNativePageNode, isNativeSearchResultNode, isViewableUrl, nativeVerdictOf, readChoiceContent, readCompositeContent, readDataUrl, readDateContent, readDocumentContent, readHtmlContent, readImageContent, readPageContent, readRatingContent, readSearchResultContent, readYesNoContent, splitCitations, viewableUrl } from '../chunk-QQK6Y55E.js';
 export { getPipeOutputForm } from '../chunk-JIGRWJTV.js';
 export { buildResultField, buildRunFields, getPipeInputForm } from '../chunk-ZB4RYUKV.js';
 export { conceptCategory } from '../chunk-FABY3DEY.js';
 export { DOCUMENT_FORMATS, IMAGE_FORMATS, acceptLabel, acceptMap, formatsForKind, isAcceptedFile } from '../chunk-XCO6GTEC.js';
-export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-4DPYGNJ3.js';
+export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-IBBAJXIO.js';
 export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, pruneEmptyOptionals, resolveConceptCode } from '../chunk-E6BIXJ6C.js';
+export { anyOptionalStructureOpen, computeReadiness, fieldFilled, foldsBehindOptionalDisclosure, isFilled, isFoldedOptional, isOptionalStructure, mustBeFilled, optionalStructureOpen, shownAsOptional } from '../chunk-XO5OENNF.js';
 import '../chunk-Y2ND6W4W.js';
 export { normalizeSchemaForRjsf, prepareSchemaForRjsf } from '../chunk-LBFZXYCY.js';
-export { anyOptionalStructureOpen, computeReadiness, fieldFilled, foldsBehindOptionalDisclosure, isFilled, isFoldedOptional, isOptionalStructure, mustBeFilled, optionalStructureOpen, shownAsOptional } from '../chunk-XO5OENNF.js';
 export { collapseNullable, collectSchemaDefs, derefSchema, flattenAnyOf, hoistDefsToRoot, resolveSchemaIndirection, schemaTypeOf } from '../chunk-OD3VYXUY.js';
 export { buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';

package/dist/core/sources.d.ts

@@ -13,8 +13,9 @@
  * answers with, and the rules that write an answer into a value are tested in
  * node. No React, no fetch. What a row SAYS is data here (`SourceFile`'s
  * `typeLabel` and `origin` are the host's words); how a row DRAWS is a
- * rendering, so the glyph a host draws on a row is `./react`'s
- * (`FilePickerSource.renderGlyph`), never a field of these shapes.
+ * rendering, so the glyph a host draws on a file's row and the line it draws
+ * under an example's name are `./react`'s (`FilePickerSource.renderGlyph`,
+ * `ExamplePickerSource.renderDetail`), never a field of these shapes.
  */
 /** Whose files a file source lists: the person's own, or the whole team's. */
 type FileSourceScope = 'mine' | 'everyone';
@@ -121,20 +122,44 @@ interface ExampleSourcePage {
 }
 /**
  * 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.
+ * "Fill with an example". `open`, `rename` and `delete` are capabilities: each
+ * is offered on a row's menu only when given, Open first, so a host gives each
+ * only to a person it is for, and `rename` and `delete` only to a person
+ * allowed to change examples. A source with any one of them has a row menu.
+ *
+ * The three are declared as methods, as `./react`'s `renderDetail` is,
+ * because TypeScript compares a method's parameter in both directions: a
+ * source whose handlers take the host's own example type, the type its `list`
+ * answers with, is accepted. Declared as function-typed properties they would
+ * refuse it under `strictFunctionTypes`, which is why they must stay methods.
+ * The control calls each on its source, so a class's methods keep `this`.
  */
 interface ExampleSource {
     /** Lists one page of the method's examples. Rejecting shows the failure with Try again. */
     list: (query: ExampleSourceQuery) => Promise<ExampleSourcePage>;
+    /**
+     * Opens an example in the host's own surface, to show what it holds and
+     * what it produced. Choosing Open closes the list and gives focus back to
+     * "Fill with an example", then calls `open` once, so a surface the host
+     * opens over the form from there returns focus there as it closes.
+     *
+     * `fill` is the row's own choice of that example, made when it is called:
+     * the example's inputs read back against the form's fields as they are at
+     * that moment, "Replace what you entered?" asked first when the form holds
+     * the person's own values, and nothing at all while the form is held shut
+     * or once the control is gone, `hideWhenEmpty` having taken it away included.
+     * It fills through the same path a row's choice does, so a host's "Fill the
+     * form" calls it rather than setting the values itself. It may be called
+     * any number of times, or never.
+     */
+    open?(example: FormExample, fill: () => void): void;
     /**
      * 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>;
+    rename?(example: FormExample, name: string): Promise<FormExample | void>;
     /** Deletes an example. Asked for only after the person confirmed it. */
-    delete?: (example: FormExample) => Promise<void>;
+    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.

package/dist/core/sources.js

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

package/dist/{field-renderer-CH-biG8C.d.ts → field-renderer-Dz03dpig.d.ts}

@@ -28,8 +28,9 @@ interface FilePickerSource<F extends SourceFile = SourceFile> extends FileSource
      * (the row is at least 64px tall and grows with a larger glyph), and is
      * hidden from assistive technology, since the row's second line says the
      * type. A row it returns what React renders nothing for keeps the kernel's
-     * glyph: `null`, `undefined`, `true`, `false` or `''`, so a
-     * `cond && <Tile />` whose condition is false falls back as it reads. A
+     * glyph: `null`, `undefined`, `true`, `false` or `''`, or an array of
+     * nothing but those, an empty one included, so a `cond && <Tile />` whose
+     * condition is false, or a `.map()` over nothing, falls back as it reads. A
      * number is drawn, `0` included, because React draws it as text, so a
      * condition that is a count is the host's to turn into a boolean.
      */

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-CH-biG8C.js';
+import { F as FieldEnv } from '../field-renderer-Dz03dpig.js';
 export { seedInputs } from '../core/seed.js';
 import '../core/contracts.js';
 import 'mthds/protocol';

package/dist/generative/index.js

@@ -1,10 +1,11 @@
 "use client";
-import { cn, checkedAccentClass, focusOutlineClass, linkTextClass, selectedBorderClass, selectedFillClass, fieldControlClass, ResultRoot, ResultField, FieldRenderer, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-AZIUFSIQ.js';
+import { cn, checkedAccentClass, focusOutlineClass, linkTextClass, selectedBorderClass, selectedFillClass, fieldControlClass, ResultRoot, ResultField, FieldRenderer, enumLabeler, useFieldPresentation, ToggleGroup, ToggleGroupItem, selectedFillStrongClass, Switch, Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../chunk-RHX7LQRL.js';
 import '../chunk-4VAO6BDE.js';
 export { seedInputs } from '../chunk-VH5CDQDR.js';
-import '../chunk-NSHGLM6A.js';
+import '../chunk-L23R3JNQ.js';
 import '../chunk-56WECFBD.js';
 import '../chunk-ZX52CQJ4.js';
+import '../chunk-GHVVULHY.js';
 import { isNativeValueNode, readDateContent, formatDateContent, isNativeHtmlNode, isNativeDateNode, isNativeCompositeNode } from '../chunk-QQK6Y55E.js';
 export { brandManifestSchema } from '../chunk-QFX332LE.js';
 import '../chunk-ZB4RYUKV.js';
@@ -2123,6 +2124,7 @@ function Radio({
 }) {
   const id = useControlId(props.name);
   const field = useBoundField(props.value, bindings?.value, "", props);
+  const labelOf = enumLabeler(props.options ?? [], useFieldPresentation());
   return /* @__PURE__ */ jsxs("fieldset", { className: "space-y-2", "aria-invalid": field.error ? true : void 0, children: [
     /* @__PURE__ */ jsx("legend", { className: LABEL, children: props.label }),
     /* @__PURE__ */ jsx("div", { className: "space-y-2", children: (props.options ?? []).map((option, index) => /* @__PURE__ */ jsxs("label", { className: "flex items-center gap-2 text-sm", children: [
@@ -2141,7 +2143,7 @@ function Radio({
           }
         }
       ),
-      /* @__PURE__ */ jsx("span", { children: option })
+      /* @__PURE__ */ jsx("span", { children: labelOf(option) })
     ] }, `${index}-${option}`)) }),
     /* @__PURE__ */ jsx(FieldError, { message: field.error })
   ] });
@@ -2322,6 +2324,7 @@ function AccessibleSelect({ props, bindings, emit }) {
     hasValidation ? { checks: props.checks ?? [], validateOn } : void 0
   );
   const id = useControlId(props.name);
+  const labelOf = enumLabeler(props.options ?? [], useFieldPresentation());
   return /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
     /* @__PURE__ */ jsx("label", { htmlFor: id, className: "block text-sm leading-none font-medium", children: props.label }),
     /* @__PURE__ */ jsxs(
@@ -2335,7 +2338,7 @@ function AccessibleSelect({ props, bindings, emit }) {
         },
         children: [
           /* @__PURE__ */ jsx(SelectTrigger, { id, className: "w-full", children: /* @__PURE__ */ jsx(SelectValue, { placeholder: props.placeholder ?? "Select..." }) }),
-          /* @__PURE__ */ jsx(SelectContent, { children: (props.options ?? []).map((option, index) => /* @__PURE__ */ jsx(SelectItem, { value: option, children: option }, `${index}-${option}`)) })
+          /* @__PURE__ */ jsx(SelectContent, { children: (props.options ?? []).map((option, index) => /* @__PURE__ */ jsx(SelectItem, { value: option, children: labelOf(option) }, `${index}-${option}`)) })
         ]
       }
     ),
@@ -2591,6 +2594,7 @@ function Segmented({ props, bindings, emit }) {
   const value = isBound ? boundValue ?? "" : localValue;
   const setValue = isBound ? setBoundValue : setLocalValue;
   const labelId = useControlId(props.name);
+  const labelOf = enumLabeler(props.options ?? [], useFieldPresentation());
   return /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
     /* @__PURE__ */ jsx("span", { id: labelId, className: "block text-sm leading-none font-medium", children: props.label }),
     /* @__PURE__ */ jsx(
@@ -2612,7 +2616,7 @@ function Segmented({ props, bindings, emit }) {
             variant: "outline",
             size: "sm",
             className: "rounded-full px-3.5 data-[state=on]:border-primary data-[state=on]:bg-primary data-[state=on]:text-primary-foreground",
-            children: option
+            children: labelOf(option)
           },
           option
         ))