@ashley-shrok/viewmodel-shell 3.3.0 → 3.4.0

package/dist/browser.d.ts

@@ -60,6 +60,11 @@ export declare class BrowserAdapter implements Adapter {
      *  When `action` is set, it fires on Enter (text-like) or change (select) —
      *  the new value is already in state by that point. */
     private field;
+    /** Forms-completeness (3.4.0) — apply disabled/readonly to the control and
+     *  render help + error text below it, wiring aria-describedby / aria-invalid.
+     *  Runs on the main field path (the hidden + checkbox-FieldNode variants
+     *  return before this). */
+    private decorateField;
     /** CheckboxNode (standalone, immediate-dispatch) — bound boolean; on toggle,
      *  write to state then dispatch the action name (if any). */
     private checkbox;

package/dist/browser.js

@@ -772,8 +772,61 @@ export class BrowserAdapter {
             }
             wrapper.appendChild(inp);
         }
+        this.decorateField(wrapper, n);
         parent.appendChild(wrapper);
     }
+    /** Forms-completeness (3.4.0) — apply disabled/readonly to the control and
+     *  render help + error text below it, wiring aria-describedby / aria-invalid.
+     *  Runs on the main field path (the hidden + checkbox-FieldNode variants
+     *  return before this). */
+    decorateField(wrapper, n) {
+        const control = wrapper.querySelector(".vms-field__input");
+        if (n.disabled) {
+            if (control)
+                control.disabled = true;
+            wrapper.classList.add("vms-field--disabled");
+        }
+        if (n.readonly && control && "readOnly" in control) {
+            control.readOnly = true;
+        }
+        // Native input constraints — min/max/step on <input>, maxLength on
+        // <input>/<textarea>. Strings pass straight to the attribute.
+        if (control instanceof HTMLInputElement) {
+            if (n.min != null)
+                control.min = n.min;
+            if (n.max != null)
+                control.max = n.max;
+            if (n.step != null)
+                control.step = n.step;
+        }
+        if (n.maxLength != null &&
+            (control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement)) {
+            control.maxLength = n.maxLength;
+        }
+        const describedBy = [];
+        if (n.help != null && n.help !== "") {
+            const helpEl = document.createElement("div");
+            helpEl.className = "vms-field__help";
+            helpEl.id = `vms-${n.name}-help`;
+            helpEl.textContent = n.help;
+            wrapper.appendChild(helpEl);
+            describedBy.push(helpEl.id);
+        }
+        if (n.error != null && n.error !== "") {
+            wrapper.classList.add("vms-field--error");
+            const errEl = document.createElement("div");
+            errEl.className = "vms-field__error";
+            errEl.id = `vms-${n.name}-error`;
+            errEl.setAttribute("role", "alert");
+            errEl.textContent = n.error;
+            wrapper.appendChild(errEl);
+            describedBy.push(errEl.id);
+            control?.setAttribute("aria-invalid", "true");
+        }
+        if (control && describedBy.length > 0) {
+            control.setAttribute("aria-describedby", describedBy.join(" "));
+        }
+    }
     /** CheckboxNode (standalone, immediate-dispatch) — bound boolean; on toggle,
      *  write to state then dispatch the action name (if any). */
     checkbox(n, parent, on) {
@@ -809,9 +862,16 @@ export class BrowserAdapter {
     button(n, parent, on) {
         const btn = document.createElement("button");
         btn.type = "button";
-        btn.className = `vms-button${n.emphasis ? ` vms-button--${n.emphasis}` : ""}${n.tone ? ` vms-button--${n.tone}` : ""}${n.size ? ` vms-button--${n.size}` : ""}${n.width === "full" ? " vms-button--full" : ""}`;
+        btn.className = `vms-button${n.emphasis ? ` vms-button--${n.emphasis}` : ""}${n.tone ? ` vms-button--${n.tone}` : ""}${n.size ? ` vms-button--${n.size}` : ""}${n.width === "full" ? " vms-button--full" : ""}${n.disabled ? " vms-button--disabled" : ""}`;
         btn.textContent = n.label;
+        if (n.disabled)
+            btn.disabled = true;
         btn.addEventListener("click", () => {
+            // Forms-completeness (3.4.0): a disabled button never dispatches. (Native
+            // `disabled` already suppresses the click, but guard anyway in case the
+            // attribute was cleared out-of-band.)
+            if (n.disabled)
+                return;
             // pendingLabel: instant client-side feedback. Swap text + add
             // .vms-button--pending BEFORE handing off to the dispatcher. On
             // success the next render replaces the button entirely. On dispatch

package/dist/index.d.ts

@@ -241,6 +241,35 @@ export interface FieldNode {
     label?: string;
     placeholder?: string;
     required?: boolean;
+    /** Disables the control (greys it out, blocks input, excludes it from form
+     *  submission). Server-owned. Emits `.vms-field--disabled` on the wrapper +
+     *  the native `disabled` attribute. Omitted = enabled. */
+    disabled?: boolean;
+    /** Read-only: the value is shown and submitted but the user can't edit it
+     *  (distinct from `disabled`, which also greys out + excludes from submit).
+     *  Text-like inputs + textarea only. Emits the native `readonly` attribute. */
+    readonly?: boolean;
+    /** Per-field validation error message, rendered inline below the control as
+     *  `.vms-field__error` (role="alert"); also sets the wrapper's
+     *  `.vms-field--error`, the control's `aria-invalid="true"`, and wires the
+     *  message into `aria-describedby`. The view-side complement to the
+     *  response-level `rejected` channel — set it on the offending field when you
+     *  build the tree. Omitted = no error shown. */
+    error?: string;
+    /** Hint/help text rendered below the control as `.vms-field__help` and wired
+     *  into the control's `aria-describedby`. Omitted = no hint. */
+    help?: string;
+    /** `min`/`max`/`step` passed through to the native input attribute for
+     *  `number`/`range`/date-time inputs. STRINGS (HTML-attribute semantics): a
+     *  numeric bound (`"0"`), a date bound (`"2020-01-01"`), and `step` also
+     *  accepts `"any"`. Typed as strings (not numbers) so the wire stays
+     *  byte-identical across backends. Omitted = no constraint. */
+    min?: string;
+    max?: string;
+    step?: string;
+    /** Maximum input length (characters) for text-like inputs + textarea →
+     *  native `maxlength`. Integer. Omitted = no cap. */
+    maxLength?: number;
     options?: Array<{
         value: string;
         label: string;
@@ -279,6 +308,10 @@ export interface ButtonNode {
      *  `block`, Chakra `width="full"`). Emits `.vms-button--full`. Omitted/`"auto"`
      *  = content-width (the default hug). Orthogonal to emphasis/tone/size. */
     width?: "auto" | "full";
+    /** Disables the button — greys it out (`.vms-button--disabled` + native
+     *  `disabled`) and the renderer will NOT dispatch its action on click.
+     *  Server-owned (e.g. a submit gated on a precondition). Omitted = enabled. */
+    disabled?: boolean;
     /** Transient label shown from click until the dispatch resolves (response
      *  arrives or dispatch errors). Mirrors `CopyButtonNode.copiedLabel`'s
      *  lifecycle pattern at a different beat: shown DURING the round-trip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",

package/styles/default.css

@@ -494,6 +494,27 @@ body {
 textarea.vms-field__input { min-height: 80px; }
 select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl); }
 
+/* Forms-completeness (3.4.0) — help/error text + disabled/readonly/error states.
+   help is the muted hint; error is the danger message (role="alert"). */
+.vms-field__help  { font-size: var(--vms-text-sm); color: var(--vms-text-muted); }
+.vms-field__error { font-size: var(--vms-text-sm); color: var(--vms-error); }
+.vms-field--error .vms-field__input { border-color: var(--vms-error); }
+.vms-field--error .vms-field__input:focus {
+  border-color: var(--vms-error);
+  box-shadow: 0 0 0 3px var(--vms-error-glow);
+}
+.vms-field__input:disabled,
+.vms-field--disabled .vms-field__input {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+.vms-field--disabled .vms-field__label { opacity: 0.7; }
+/* read-only: editable-looking but visibly inert background (not greyed like disabled). */
+.vms-field__input:read-only:not([type="file"]) {
+  background: color-mix(in srgb, var(--vms-surface) 70%, var(--vms-border));
+  cursor: default;
+}
+
 /* Code editor field — monospaced, tab-aware, no spell-check chrome.
    Apps add syntax highlighting via .vms-field--code-{language} hooks. */
 .vms-field__input--code {
@@ -617,6 +638,14 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   pointer-events: none;
 }
 
+/* Forms-completeness (3.4.0) — server-declared disabled button. */
+.vms-button:disabled,
+.vms-button--disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
 /* Inside a list item, a danger button is treated as the row's "X" affordance:
    muted and hidden until the row is hovered, then visible and red on hover. */
 .vms-list-item .vms-button--danger {