@pipelex/mthds-form 0.3.0 → 0.4.0

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 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-DPrrfAjL.js';
+import { RunField, BooleanRunField, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, ConceptCategory } from '../core/descriptor.js';
 
 /**
  * Ambient state that any field in the tree may need, threaded unchanged through
@@ -114,6 +114,25 @@ interface ListFieldProps {
  * 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.
+ *
+ * **A row is a thing, not a slot.** Its React key is generated when the row
+ * appears and travels with it, so removing an earlier row moves the later ones
+ * instead of renumbering them into each other - which is what used to drop a
+ * half-typed value or a pending preview onto the neighbouring row. The row's
+ * field ID stays POSITIONAL (`cvs.1`), because that ID is a PATH: a host writes
+ * an upload back with `setValueAtPath(values, id.split('.'), value)`, and
+ * `setValueAtPath` is a pure function of the value tree. Handing out an opaque
+ * token instead would mean the kernel keeping a live token-to-index registry for
+ * that function to consult, which is exactly the kind of hidden state the
+ * headless core does not have.
+ *
+ * The positional ID is why removal is BLOCKED while a file is arriving anywhere
+ * in this list - see `listIsBusy`. Together those two are the whole fix: a
+ * generated key cannot rescue a write-back either, because the keys live in this
+ * control's state and not in the value, so a host that replaces `values`
+ * wholesale reconciles by length just as positions do. What a stable identity
+ * buys over a position is exactly the reorderings the KERNEL performs, and it
+ * performs one.
  */
 declare function ListField({ field, value, onChange, id, error, env }: ListFieldProps): react.JSX.Element;
 
@@ -249,6 +268,8 @@ interface FieldStrings {
     addItem: string;
     removeItemAria: (index: number) => string;
     itemsCount: (count: number) => string;
+    /** The same badge for a list the method gave an exact count (`Concept[N]`). */
+    itemsCountOf: (count: number, total: number) => string;
     uploading: string;
     dropToUpload: string;
     dropOrBrowse: string;

package/dist/react/index.js

@@ -1,5 +1,7 @@
 "use client";
-import { toStoredDateValue, toDateInputValue, isFilled } from '../chunk-S6KOTTGD.js';
+import { isFilled } from '../chunk-PM55AHRO.js';
+import { ownProp } from '../chunk-V3OV2XQT.js';
+import { toStoredDateValue, toDateInputValue } from '../chunk-GKV77RAS.js';
 import { clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 import { ChevronDown, ChevronUp, Check, List, Braces, ListChecks, ToggleLeft, Hash, Image, FileText, CalendarDays, Type, Loader2, Upload, Link2, ImageOff, EyeOff, Eye, X, Minus, Plus, Trash2 } from 'lucide-react';
@@ -137,6 +139,7 @@ var DEFAULT_FIELD_STRINGS = {
   addItem: "Add item",
   removeItemAria: (index) => `Remove item ${index}`,
   itemsCount: (count) => count === 1 ? "1 item" : `${count} items`,
+  itemsCountOf: (count, total) => `${count} of ${total} ${total === 1 ? "item" : "items"}`,
   uploading: "Uploading\u2026",
   dropToUpload: "Drop to upload",
   dropOrBrowse: "Drop a file or click to browse",
@@ -239,6 +242,13 @@ function DateField({ field, value, onChange, id, error, disabled }) {
 }
 var IMAGE_EXT_RE = /\.(jpg|jpeg|png|gif|webp|bmp|svg|avif)(\?|$)/i;
 var PDF_EXT_RE = /\.pdf(\?|$)/i;
+var DATA_URL_MIME_RE = /^data:([^;,]+)/i;
+function isDirectlyViewable(url) {
+  return !!url && (/^https?:/i.test(url) || /^data:/i.test(url) || /^blob:/i.test(url));
+}
+function dataUrlMime(url) {
+  return DATA_URL_MIME_RE.exec(url)?.[1]?.toLowerCase();
+}
 function DocumentField(props) {
   return /* @__PURE__ */ jsx(FileField, { ...props, category: "document" });
 }
@@ -261,24 +271,31 @@ function FileField({
   const [showUrl, setShowUrl] = useState(false);
   const [previewOpen, setPreviewOpen] = useState(false);
   const [localPreview, setLocalPreview] = useState(null);
+  const [resolved, setResolved] = useState(null);
   const localUrlRef = useRef(null);
   const setLocal = useCallback((next) => {
     if (localUrlRef.current) URL.revokeObjectURL(localUrlRef.current);
-    localUrlRef.current = next?.url ?? null;
+    localUrlRef.current = next?.objectUrl ?? null;
     setLocalPreview(next);
   }, []);
   useEffect(() => () => setLocal(null), [setLocal]);
   const handleFile = useCallback(
     (file) => {
-      setLocal({ url: URL.createObjectURL(file), type: file.type });
+      setLocal({ objectUrl: URL.createObjectURL(file), type: file.type });
       onDropFile(file);
     },
     [setLocal, onDropFile]
   );
+  const busy = disabled || uploading;
   const { getRootProps, getInputProps, isDragActive } = useDropzone({
     maxFiles: 1,
     multiple: false,
-    disabled: disabled || uploading,
+    disabled: busy,
+    // The tab stop belongs on the INPUT, not on this div - see the root element
+    // below. Without this, react-dropzone puts `tabIndex: 0` and its own key
+    // handlers on a `role="presentation"` div, and the element a keyboard or
+    // voice-control user lands on is a generic with no role and no name.
+    noKeyboard: true,
     onDrop: (files) => {
       const file = files[0];
       if (file) handleFile(file);
@@ -286,28 +303,43 @@ function FileField({
   });
   const clear = useCallback(() => {
     setLocal(null);
-    setResolvedSrc(null);
+    setResolved(null);
     setPreviewOpen(false);
     onChange(void 0);
   }, [setLocal, onChange]);
+  const localIsCurrent = !!localPreview && (localPreview.boundUrl === void 0 || localPreview.boundUrl === value?.url);
+  useEffect(() => {
+    if (!localPreview) return;
+    if (localPreview.boundUrl === void 0) {
+      if (uploading || !value?.url) return;
+      setLocalPreview({ ...localPreview, boundUrl: value.url });
+      return;
+    }
+    if (value?.url !== localPreview.boundUrl) setLocal(null);
+  }, [localPreview, value?.url, uploading, setLocal]);
   const hasFile = !!value?.url;
-  const ref = `${value?.filename ?? ""} ${value?.url ?? ""}`;
-  const isImage = category === "image" || localPreview?.type.startsWith("image/") || IMAGE_EXT_RE.test(ref);
-  const isPdf = localPreview?.type === "application/pdf" || PDF_EXT_RE.test(ref);
+  const localType = localIsCurrent ? localPreview?.type : void 0;
+  const filename = value?.filename ?? "";
+  const url = value?.url ?? "";
+  const urlMime = dataUrlMime(url);
+  const isImage = category === "image" || localType?.startsWith("image/") === true || urlMime?.startsWith("image/") === true || IMAGE_EXT_RE.test(filename) || IMAGE_EXT_RE.test(url);
+  const isPdf = localType === "application/pdf" || urlMime === "application/pdf" || PDF_EXT_RE.test(filename) || PDF_EXT_RE.test(url);
   const canPreview = isImage || isPdf;
-  const [resolvedSrc, setResolvedSrc] = useState(null);
-  const storageUri = value?.url && !value.url.startsWith("http") ? value.url : null;
+  const storageUri = value?.url && !isDirectlyViewable(value.url) ? value.url : null;
   useEffect(() => {
-    if (!previewOpen || !storageUri || localPreview || !resolveUrl) return;
+    if (!previewOpen || !storageUri || localIsCurrent || !resolveUrl) return;
     let cancelled = false;
-    void resolveUrl(storageUri).then((url) => {
-      if (!cancelled) setResolvedSrc(url);
+    void resolveUrl(storageUri).then((src) => {
+      if (!cancelled) setResolved(src ? { uri: storageUri, src } : null);
+    }).catch(() => {
+      if (!cancelled) setResolved(null);
     });
     return () => {
       cancelled = true;
     };
-  }, [previewOpen, storageUri, localPreview, resolveUrl]);
-  const previewSrc = localPreview?.url ?? (value?.url?.startsWith("http") ? value.url : resolvedSrc ?? void 0);
+  }, [previewOpen, storageUri, localIsCurrent, resolveUrl]);
+  const resolvedSrc = resolved && resolved.uri === storageUri ? resolved.src : void 0;
+  const previewSrc = (localIsCurrent ? localPreview?.objectUrl : void 0) ?? (isDirectlyViewable(value?.url) ? value.url : resolvedSrc);
   return /* @__PURE__ */ jsxs(
     FieldShell,
     {
@@ -318,6 +350,7 @@ function FileField({
       description: field.description,
       required: field.required,
       error,
+      htmlFor: id,
       children: [
         hasFile && !uploading ? /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
           /* @__PURE__ */ jsx(
@@ -332,36 +365,53 @@ function FileField({
             }
           ),
           previewOpen && (previewSrc && isImage ? /* @__PURE__ */ jsx(ImagePreview, { src: previewSrc, filename: value?.filename }) : previewSrc && isPdf ? /* @__PURE__ */ jsx(PdfPreview, { src: previewSrc }) : /* @__PURE__ */ jsx("div", { className: "flex h-24 items-center justify-center rounded-md border border-border bg-muted", children: /* @__PURE__ */ jsx(Loader2, { className: "h-4 w-4 animate-spin text-muted-foreground" }) }))
-        ] }) : /* @__PURE__ */ jsxs(
-          "div",
-          {
-            ...getRootProps(),
-            className: cn(
-              "flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed px-4 py-6 text-center",
-              "cursor-pointer select-none transition-colors",
-              isDragActive ? "border-primary/60 bg-primary/5" : "border-border bg-input hover:border-border hover:bg-muted",
-              (disabled || uploading) && "cursor-not-allowed opacity-60"
-            ),
-            children: [
-              /* @__PURE__ */ jsx("input", { ...getInputProps(), id, "aria-invalid": !!error }),
-              uploading ? /* @__PURE__ */ jsxs(Fragment, { children: [
-                /* @__PURE__ */ jsx(Loader2, { className: "h-5 w-5 animate-spin text-muted-foreground" }),
-                /* @__PURE__ */ jsx("p", { className: "text-[12px] text-muted-foreground", children: s.uploading })
-              ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
-                /* @__PURE__ */ jsx(Upload, { className: "h-5 w-5 text-muted-foreground", strokeWidth: 1.75 }),
-                /* @__PURE__ */ jsxs("div", { className: "space-y-0.5", children: [
-                  /* @__PURE__ */ jsx("p", { className: "text-[13px] text-foreground", children: isDragActive ? s.dropToUpload : s.dropOrBrowse }),
-                  field.accept && /* @__PURE__ */ jsx("p", { className: "font-mono text-[10.5px] text-muted-foreground", children: field.accept })
+        ] }) : (
+          // `role="presentation"` and no tab stop: this div is the drop TARGET and
+          // the visual affordance, and the control inside it is a real
+          // `<input type="file">`, which already has the right role and now has a
+          // name. Giving the div a `role="button"` of its own would put a second
+          // named control in the accessibility tree for one value. The focus ring
+          // is `focus-within` because the element that takes focus is clip-hidden.
+          /* @__PURE__ */ jsxs(
+            "div",
+            {
+              ...getRootProps(),
+              className: cn(
+                "flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed px-4 py-6 text-center",
+                "cursor-pointer select-none transition-colors",
+                "focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background",
+                isDragActive ? "border-primary/60 bg-primary/5" : "border-border bg-input hover:border-border hover:bg-muted",
+                busy && "cursor-not-allowed opacity-60"
+              ),
+              children: [
+                /* @__PURE__ */ jsx(
+                  "input",
+                  {
+                    ...getInputProps({ tabIndex: 0 }),
+                    id,
+                    disabled: busy,
+                    "aria-invalid": !!error
+                  }
+                ),
+                uploading ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                  /* @__PURE__ */ jsx(Loader2, { className: "h-5 w-5 animate-spin text-muted-foreground" }),
+                  /* @__PURE__ */ jsx("p", { className: "text-[12px] text-muted-foreground", children: s.uploading })
+                ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+                  /* @__PURE__ */ jsx(Upload, { className: "h-5 w-5 text-muted-foreground", strokeWidth: 1.75 }),
+                  /* @__PURE__ */ jsxs("div", { className: "space-y-0.5", children: [
+                    /* @__PURE__ */ jsx("p", { className: "text-[13px] text-foreground", children: isDragActive ? s.dropToUpload : s.dropOrBrowse }),
+                    field.accept && /* @__PURE__ */ jsx("p", { className: "font-mono text-[10.5px] text-muted-foreground", children: field.accept })
+                  ] })
                 ] })
-              ] })
-            ]
-          }
+              ]
+            }
+          )
         ),
         !showUrl ? /* @__PURE__ */ jsxs(
           "button",
           {
             type: "button",
-            disabled,
+            disabled: busy,
             onClick: () => setShowUrl(true),
             className: "inline-flex items-center gap-1 font-mono text-[11px] text-muted-foreground transition-colors hover:text-foreground disabled:opacity-50",
             children: [
@@ -375,7 +425,7 @@ function FileField({
             type: "text",
             autoFocus: true,
             value: value?.url ?? "",
-            disabled,
+            disabled: busy,
             placeholder: s.urlPlaceholder,
             onChange: (e) => {
               setLocal(null);
@@ -842,8 +892,8 @@ function ObjectField({ field, value, onChange, id, error, env }) {
   const isApp = presentation === "app";
   const data = value ?? {};
   const setChild = (name, childValue) => onChange({ ...data, [name]: childValue });
-  const optionalEmpty = field.fields.filter((f) => !f.required && !isFilled(data[f.name]));
-  const visible = showOptional ? field.fields : field.fields.filter((f) => f.required || isFilled(data[f.name]));
+  const optionalEmpty = field.fields.filter((f) => !f.required && !isFilled(ownProp(data, f.name)));
+  const visible = showOptional ? field.fields : field.fields.filter((f) => f.required || isFilled(ownProp(data, f.name)));
   return /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
     /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-baseline gap-x-2 gap-y-1", children: [
       /* @__PURE__ */ jsx(
@@ -872,7 +922,7 @@ function ObjectField({ field, value, onChange, id, error, env }) {
             FieldRenderer,
             {
               field: child,
-              value: data[child.name],
+              value: ownProp(data, child.name),
               onChange: (v) => setChild(child.name, v),
               id: `${id}.${child.name}`,
               env
@@ -899,13 +949,19 @@ function ListField({ field, value, onChange, id, error, env }) {
   const presentation = useFieldPresentation();
   const isApp = presentation === "app";
   const items = value ?? [];
+  const [rowKeys, setRowKeys] = useRowKeys(items.length);
   const setItem = (index, itemValue) => {
     const next = items.slice();
     next[index] = itemValue;
     onChange(next);
   };
-  const removeItem = (index) => onChange(items.filter((_, i) => i !== index));
+  const removeItem = (index) => {
+    setRowKeys((prev) => prev.filter((_, i) => i !== index));
+    onChange(items.filter((_, i) => i !== index));
+  };
   const addItem = () => onChange([...items, emptyValue(field.item)]);
+  const busy = listIsBusy(id, env?.uploadingIds);
+  const isFull = field.maxItemCount !== void 0 && items.length >= field.maxItemCount;
   return /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
     /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-baseline gap-x-2 gap-y-1", children: [
       /* @__PURE__ */ jsx(
@@ -919,7 +975,7 @@ function ListField({ field, value, onChange, id, error, env }) {
         }
       ),
       !isApp && /* @__PURE__ */ jsx(ConceptPill, { conceptRef: field.conceptRef, category: "list" }),
-      /* @__PURE__ */ jsx("span", { className: "font-mono text-[10.5px] text-muted-foreground", children: s.itemsCount(items.length) }),
+      /* @__PURE__ */ jsx("span", { className: "font-mono text-[10.5px] text-muted-foreground", children: field.itemCount !== void 0 && field.maxItemCount === field.itemCount ? s.itemsCountOf(items.length, field.itemCount) : s.itemsCount(items.length) }),
       !field.required && /* @__PURE__ */ jsx("span", { className: "ml-auto font-mono text-[10px] uppercase tracking-wider text-muted-foreground/70", children: s.optionalBadge })
     ] }),
     field.description && /* @__PURE__ */ jsx("p", { className: "text-[12px] leading-relaxed text-muted-foreground", children: field.description }),
@@ -946,7 +1002,7 @@ function ListField({ field, value, onChange, id, error, env }) {
               {
                 type: "button",
                 onClick: () => removeItem(index),
-                disabled: env?.disabled,
+                disabled: env?.disabled || busy,
                 "aria-label": s.removeItemAria(index + 1),
                 className: "mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-destructive disabled:opacity-50",
                 children: /* @__PURE__ */ jsx(Trash2, { className: "h-3.5 w-3.5" })
@@ -954,14 +1010,14 @@ function ListField({ field, value, onChange, id, error, env }) {
             )
           ]
         },
-        index
+        rowKeys[index] ?? index
       )),
       /* @__PURE__ */ jsxs(
         "button",
         {
           type: "button",
           onClick: addItem,
-          disabled: env?.disabled,
+          disabled: env?.disabled || isFull,
           className: cn(
             "inline-flex h-9 w-full items-center justify-center gap-1.5 rounded-md border border-dashed border-border text-[13px] text-muted-foreground transition-colors",
             "hover:border-primary/40 hover:bg-muted hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50"
@@ -976,6 +1032,30 @@ function ListField({ field, value, onChange, id, error, env }) {
     error && /* @__PURE__ */ jsx("p", { className: "text-[11px] text-destructive", role: "alert", children: error })
   ] });
 }
+function listIsBusy(id, uploadingIds) {
+  if (!uploadingIds?.size) return false;
+  const prefix = `${id}.`;
+  for (const uploading of uploadingIds) if (uploading.startsWith(prefix)) return true;
+  return false;
+}
+function useRowKeys(length) {
+  const [state, setState] = useState(() => ({
+    keys: Array.from({ length }, (_, i) => i),
+    next: length
+  }));
+  if (state.keys.length !== length) {
+    setState((prev) => {
+      if (length <= prev.keys.length) return { keys: prev.keys.slice(0, length), next: prev.next };
+      const added = length - prev.keys.length;
+      return {
+        keys: [...prev.keys, ...Array.from({ length: added }, (_, i) => prev.next + i)],
+        next: prev.next + added
+      };
+    });
+  }
+  const update = (fn) => setState((prev) => ({ keys: fn(prev.keys), next: prev.next }));
+  return [state.keys, update];
+}
 function emptyValue(field) {
   switch (field.kind) {
     case "boolean":