@pipelex/mthds-form 0.27.0 → 0.29.0

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FieldEnv, R as RowMove, a as FilePickerSource, U as UploadedFile } from '../field-renderer-CH-biG8C.js';
-export { D as DocumentField, b as FieldRenderer, c as FieldRendererProps, d as FilePicker, e as FilePickerEntry, f as FilePickerEntryProps, g as FilePickerProps, h as FileValue, I as ImageField } from '../field-renderer-CH-biG8C.js';
+import { F as FieldEnv, R as RowMove, a as FilePickerSource, U as UploadedFile } from '../field-renderer-Dz03dpig.js';
+export { D as DocumentField, b as FieldRenderer, c as FieldRendererProps, d as FilePicker, e as FilePickerEntry, f as FilePickerEntryProps, g as FilePickerProps, h as FileValue, I as ImageField } from '../field-renderer-Dz03dpig.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { BooleanRunField, DateRunField, EnumRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, RunField, ConceptCategory } from '../core/descriptor.js';
@@ -7,6 +7,7 @@ import { PipeInputFormDescriptor, PipeIOContract } from 'mthds/protocol';
 import { Readiness } from '../core/readiness.js';
 import { ExampleSource, FormExample } from '../core/sources.js';
 export { ExampleSourcePage, ExampleSourceQuery, FileSource, FileSourcePage, FileSourceQuery, FileSourceScope, SourceFile } from '../core/sources.js';
+export { humanizeFieldName } from '../core/humanize.js';
 import { SaveFiles, SaveFile, SaveResult } from '../core/save-plan.js';
 import { StuffFileKind } from '../core/stuff-files.js';
 import { HtmlContentView } from '../core/native-content.js';
@@ -177,6 +178,67 @@ interface UnknownFieldProps {
  */
 declare function UnknownField({ field, value, onChange, id, error, disabled }: UnknownFieldProps): react.JSX.Element;
 
+/**
+ * An example source as the control set takes it: the kernel's `ExampleSource`,
+ * which lists the examples and says what may be done with them, and what a
+ * row says under the example's name, which only a renderer can draw. Every
+ * `ExampleSource` is one, so a host that describes nothing passes its source
+ * as it is.
+ */
+interface ExamplePickerSource extends ExampleSource {
+    /**
+     * Draws a line under a row's name: what the example holds, say, or that it
+     * no longer fits the form. It receives the example as `list` returned it and
+     * the fields the control reads examples back against, the form's own. What
+     * it returns is drawn inside the row's button, under the name, in the list's
+     * small muted type unless it styles itself, and is read with the name as the
+     * row's accessible name, so it is phrasing content with nothing interactive
+     * in it: text, a `<span>`, a decorative icon. It wraps within the row and
+     * never widens it; a host wanting one line truncates its own element. A row
+     * it returns what React renders nothing for stays the one line of its name:
+     * `null`, `undefined`, `true`, `false` or `''`, or an array of nothing but
+     * those, an empty one included. It is declared as a method,
+     * as `FilePickerSource.renderGlyph` is, so a source whose `renderDetail`
+     * takes the host's own example type, the type its `list` answers with, is
+     * still accepted.
+     */
+    renderDetail?(example: FormExample, fields: readonly RunField[]): ReactNode;
+}
+interface FillWithExampleProps {
+    /** The host's examples of this method, and what each row says under its name. */
+    source: ExamplePickerSource;
+    /** The form's fields, which an example's inputs are read back against. */
+    fields: RunField[];
+    /**
+     * Whether the form holds a value the person typed or attached. An untouched
+     * form fills at once; a touched one asks "Replace what you entered?" first.
+     * `useMethodForm` reports it as `touched`; a host holding its own values
+     * compares them with the ones it last set (`sameRunValues`).
+     */
+    touched: boolean;
+    /**
+     * Sets the whole form's values to the example's, read back into the
+     * controls' shape (`runValuesFromInputs`). Never a run.
+     */
+    onFill: (values: Record<string, unknown>, example: FormExample) => void;
+    /** Holds the control shut, as a host does while a run is in flight. */
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * "Fill with an example", and everything behind it.
+ *
+ * With `hideWhenEmpty`, the control reads the list as it mounts and again each
+ * time the list closes (a delete may have taken the last example), and is
+ * offered once the method is known to have an example, or when the list could
+ * not be read, so a failure is shown rather than hidden. That read follows the
+ * list past empty pages, and while it is under way the control keeps the last
+ * answer rather than blinking out. The list itself never vanishes while it is
+ * open. Without `hideWhenEmpty`, the control is always offered and an empty
+ * list says how to make one.
+ */
+declare function FillWithExample({ source, fields, touched, onFill, disabled, className, }: FillWithExampleProps): react.JSX.Element | null;
+
 /**
  * How a field's LABEL chrome, and the enum values a person reads, should read.
  * What a control stores never changes.
@@ -189,17 +251,19 @@ declare function UnknownField({ field, value, onChange, id, error, disabled }: U
  * - `app`: the field's name as a human question in sans, no concept pill. Inside
  *   a method app, `full_name` and `native.Text` are implementation detail; the
  *   person filling the form has never seen the method's source. An enum value
- *   follows the label and reads as words.
+ *   follows the label and reads as words, worded by the kernel's rule
+ *   (`enumValueLabeler` in the core entry).
  *
  * An enum value is the only value the two presentations show differently. A
  * number, a text, a date and every other value render the same in both.
  *
  * Deliberately a context rather than a prop or a `FieldEnv` flag: only the
  * components that own label chrome or an enum value's wording read it -
- * `FieldShell`, `ObjectField`, `BooleanField`, `ListField`, `EnumField` and the
- * result view - plus the file control, whose card hides a storage reference in
- * `app`, and threading a prop would have meant editing every field control and
- * both recursive containers.
+ * `FieldShell`, `ObjectField`, `BooleanField`, `ListField`, `EnumField`, the
+ * result view and the generative layer's choice controls (`Select`, `Radio`,
+ * `Segmented`) - plus the file control, whose card hides a storage reference
+ * in `app`, and threading a prop would have meant editing every field control
+ * and both recursive containers.
  */
 type FieldPresentation = 'studio' | 'app';
 declare function FieldPresentationProvider({ presentation, children, }: {
@@ -207,14 +271,6 @@ declare function FieldPresentationProvider({ presentation, children, }: {
     children: ReactNode;
 }): react.JSX.Element;
 declare function useFieldPresentation(): FieldPresentation;
-/**
- * `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;
 
 interface FieldStrings {
     /** Badge on an optional field's header row. */
@@ -518,6 +574,8 @@ interface FieldStrings {
     replaceEnteredConfirm: string;
     /** The accessible name of an example row's menu, given the example's name. */
     exampleActions: (name: string) => string;
+    /** The row menu's items, in its order: Open, offered when the source opens examples, then Rename and Delete. */
+    openExample: string;
     renameExample: string;
     deleteExample: string;
     /** The rename dialog: its title, the name field's label, and its button while it works. */
@@ -636,9 +694,11 @@ interface UseMethodFormOptions {
      * Where the form can take a saved example of the method. When given,
      * `MethodForm` offers "Fill with an example" above the fields, which sets
      * every value at once (as `reset` does) and never starts a run; a touched
-     * form asks before it replaces what was entered. See docs/sources.md.
+     * form asks before it replaces what was entered. Its `open`, when given,
+     * hands a row's example to the host's own surface, and its `renderDetail`
+     * draws a line under each row's name. See docs/sources.md.
      */
-    exampleSource?: ExampleSource;
+    exampleSource?: ExamplePickerSource;
 }
 /** What the form says to its consumer: the values, the run inputs, the gate. */
 interface MethodFormState {
@@ -761,7 +821,7 @@ interface MethodFormController extends MethodFormState {
     /** The host's file source, which `MethodForm` hands its file fields. */
     fileSource: FilePickerSource | undefined;
     /** The host's example source, which `MethodForm` offers above the fields. */
-    exampleSource: ExampleSource | undefined;
+    exampleSource: ExamplePickerSource | undefined;
 }
 /**
  * The state of one method's input form. See `UseMethodFormOptions` for what it
@@ -814,41 +874,6 @@ interface MethodFormProps {
  */
 declare function MethodForm({ locale, strings, presentation, ...props }: MethodFormProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-interface FillWithExampleProps {
-    /** The host's examples of this method. */
-    source: ExampleSource;
-    /** The form's fields, which an example's inputs are read back against. */
-    fields: RunField[];
-    /**
-     * Whether the form holds a value the person typed or attached. An untouched
-     * form fills at once; a touched one asks "Replace what you entered?" first.
-     * `useMethodForm` reports it as `touched`; a host holding its own values
-     * compares them with the ones it last set (`sameRunValues`).
-     */
-    touched: boolean;
-    /**
-     * Sets the whole form's values to the example's, read back into the
-     * controls' shape (`runValuesFromInputs`). Never a run.
-     */
-    onFill: (values: Record<string, unknown>, example: FormExample) => void;
-    /** Holds the control shut, as a host does while a run is in flight. */
-    disabled?: boolean;
-    className?: string;
-}
-/**
- * "Fill with an example", and everything behind it.
- *
- * With `hideWhenEmpty`, the control reads the list as it mounts and again each
- * time the list closes (a delete may have taken the last example), and is
- * offered once the method is known to have an example, or when the list could
- * not be read, so a failure is shown rather than hidden. That read follows the
- * list past empty pages, and while it is under way the control keeps the last
- * answer rather than blinking out. The list itself never vanishes while it is
- * open. Without `hideWhenEmpty`, the control is always offered and an empty
- * list says how to make one.
- */
-declare function FillWithExample({ source, fields, touched, onFill, disabled, className, }: FillWithExampleProps): react.JSX.Element | null;
-
 interface ResultFieldProps {
     field: RunField;
     value: unknown;
@@ -1741,4 +1766,4 @@ declare function FieldDomIdProvider({ prefix, children, }: {
  */
 declare function useFieldDomId(path: string): string;
 
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, ExampleSource, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, FilePickerSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, type MarkdownCitation, type MarkdownProps, type MarkupResolvers, MethodForm, type MethodFormController, type MethodFormProps, type MethodFormState, type MethodFormUploadContext, type MethodFormValues, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, type PdfDownloadButtonProps, type PdfPage, ProseField, type ProseImages, type RenderPdf, type RenditionRequest, type ResolveRendition, type ResolveShareUrl, type ResolveUrl, type ResolveUrls, ResultEnvProvider, ResultField, type ResultFieldProps, RowMove, SUPPORTED_LOCALES, StuffViewer, type StuffViewerProps, type StuffViewerView, type TableLayout, TextField, UnknownField, UploadedFile, type UseMethodFormOptions, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, type ExamplePickerSource, ExampleSource, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, FilePickerSource, FillWithExample, type FillWithExampleProps, FormExample, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, JsonView, ListField, Markdown, type MarkdownCitation, type MarkdownProps, type MarkupResolvers, MethodForm, type MethodFormController, type MethodFormProps, type MethodFormState, type MethodFormUploadContext, type MethodFormValues, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, type PdfDownloadButtonProps, type PdfPage, ProseField, type ProseImages, type RenderPdf, type RenditionRequest, type ResolveRendition, type ResolveShareUrl, type ResolveUrl, type ResolveUrls, ResultEnvProvider, ResultField, type ResultFieldProps, RowMove, SUPPORTED_LOCALES, StuffViewer, type StuffViewerProps, type StuffViewerView, type TableLayout, TextField, UnknownField, UploadedFile, type UseMethodFormOptions, fieldControlClass, fieldStringsFor, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl };

package/dist/react/index.js

@@ -1,10 +1,11 @@
 "use client";
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EN_FIELD_STRINGS, EnumField, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldPresentationProvider, FieldRenderer, FieldShell, FieldStringsProvider, FilePicker, FilePickerEntry, FillWithExample, HtmlPreview, ImageField, JsonView, ListField, Markdown, MethodForm, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, ProseField, ResultEnvProvider, ResultField, SUPPORTED_LOCALES, StuffViewer, TextField, UnknownField, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-AZIUFSIQ.js';
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EN_FIELD_STRINGS, EnumField, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldPresentationProvider, FieldRenderer, FieldShell, FieldStringsProvider, FilePicker, FilePickerEntry, FillWithExample, HtmlPreview, ImageField, JsonView, ListField, Markdown, MethodForm, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, ProseField, ResultEnvProvider, ResultField, SUPPORTED_LOCALES, StuffViewer, TextField, UnknownField, fieldControlClass, fieldStringsFor, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveRendition, useResolveShareUrl, useResolveUrl, useResolvedUrl } from '../chunk-RHX7LQRL.js';
 import '../chunk-4VAO6BDE.js';
 import '../chunk-VH5CDQDR.js';
-import '../chunk-NSHGLM6A.js';
+import '../chunk-L23R3JNQ.js';
 import '../chunk-56WECFBD.js';
 import '../chunk-ZX52CQJ4.js';
+export { humanizeFieldName } from '../chunk-GHVVULHY.js';
 import '../chunk-QQK6Y55E.js';
 import '../chunk-ZB4RYUKV.js';
 import '../chunk-FABY3DEY.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/mthds-form",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Headless form kernel and control set for MTHDS method inputs",
   "license": "MIT",
   "repository": {