@cahyo-dimas/freeday 3.10.0 → 3.12.0

package/dist/freeday.js

@@ -944,6 +944,11 @@
       if (!node) return;
       if (node.children) { drill(i); return; }
       selectedValue = node.value;
+      /* Mirror the value onto the ROOT, which until now only seeded it. `freeday-select.js` has
+         always done this, so this makes the family agree rather than inventing a second idea, and
+         it is what lets `freeday-form.js` require a kit control without knowing which control it
+         is: one attribute instead of five event names (#096). */
+      wrap.setAttribute('data-value', node.value);
       var labels = stack.map(function (n) { return n.label; }).concat([node.label]);
       valueSpan.textContent = labels.join(sep);
       valueSpan.classList.remove('fdy-cascade__value--placeholder');
@@ -2262,6 +2267,11 @@
     wrap.appendChild(panel);
 
     function updateDisplay() {
+      /* Mirror the value onto the ROOT, which until now only seeded it. `freeday-select.js` has
+         always done this, so this makes the family agree rather than inventing a second idea, and
+         it is what lets `freeday-form.js` require a kit control without knowing which control it
+         is: one attribute instead of five event names (#096). */
+      wrap.setAttribute('data-value', selected ? (monthOnly ? toISOMonth(selected) : toISO(selected)) : '');
       if (selected) {
         /* Through the same `Intl` formatter the month CELLS and the day grid's title already use,
            which is the whole reason this mode exists: <input type="month"> names the month in the
@@ -3011,6 +3021,36 @@
 
   function fieldOf(el) { return el.closest('.fdy-field') || el.parentElement; }
 
+  /* A kit control (combo, datepicker, monthpicker, timepicker, cascade) is NOT a form control.
+   * Its trigger is a <button>, so `willValidate` is false and `form.elements` never offers it --
+   * `required` on one meant nothing, and a form could not demand that it be filled (#096).
+   *
+   * Nothing here names a component. Two attributes carry it:
+   *   data-fdy-required  the app asking for it, on the control's ROOT
+   *   data-value         the live value, which every value-bearing kit control now mirrors
+   * and the element that takes aria-invalid and focus is found by `aria-haspopup`, which every
+   * popup-style kit trigger already sets. `FdyAutocomplete` and `FdyCfl` are absent on purpose:
+   * they render a real <input>, so the NATIVE `required` is what fits them, and routing them
+   * through here would give one field two sources of truth. No prop exposes that yet, which is a
+   * separate gap and is written down in NEXT-UP.md rather than half-closed here. */
+  function kitRoots(form) {
+    return Array.prototype.slice.call(form.querySelectorAll('[data-fdy-required]'));
+  }
+
+  /* The trigger, or the root itself if a control ever ships without one, so a missing trigger
+     degrades to a visible error rather than a thrown TypeError. */
+  function kitAria(root) {
+    return root.querySelector('[aria-haspopup]') || root;
+  }
+
+  function kitMessage(root) {
+    if ((root.getAttribute('data-value') || '') !== '') return '';
+    var form = root.closest('form');
+    return root.getAttribute('data-fdy-msg-required')
+      || root.getAttribute('data-fdy-msg')
+      || textOf(form, 'required');
+  }
+
   function ensureErrorEl(el) {
     var field = fieldOf(el);
     var errEl = field ? field.querySelector('[data-fdy-error]') : null;
@@ -3101,6 +3141,21 @@
     function controls() {
       return Array.prototype.filter.call(form.elements, isCandidate);
     }
+    function validateKit(root) {
+      var msg = kitMessage(root);
+      paint(kitAria(root), msg);
+      return !msg;
+    }
+    /* The value lives in an attribute, and each control changes it through its own event name
+       (fdy-change, fdy-datepicker-change, fdy-time-select, fdy-cascade-change). Observing the
+       attribute is what keeps this enhancer from having to know any of them. */
+    function kitLiveBind(root) {
+      if (root.dataset.fdyKitBound === '1') return;
+      root.dataset.fdyKitBound = '1';
+      new MutationObserver(function () {
+        if (submitted || eager) validateKit(root);
+      }).observe(root, { attributes: true, attributeFilter: ['data-value'] });
+    }
     function validateOne(el) {
       var msg = messageFor(el);
       paint(el, msg);
@@ -3115,6 +3170,7 @@
     }
 
     Array.prototype.forEach.call(controls(), liveBind);
+    kitRoots(form).forEach(kitLiveBind);
 
     form.addEventListener('submit', function (e) {
       submitted = true;
@@ -3123,6 +3179,18 @@
         liveBind(el);
         if (!validateOne(el)) invalid.push(el);
       });
+      kitRoots(form).forEach(function (root) {
+        kitLiveBind(root);
+        if (!validateKit(root)) invalid.push(kitAria(root));
+      });
+      /* DOM order, not native-then-kit: `invalid[0]` is what gets revealed and focused, and a
+         reader sent to the second field while the first is also red learns the wrong thing. */
+      invalid.sort(function (a, b) {
+        var rel = a.compareDocumentPosition(b);
+        if (rel & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+        if (rel & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+        return 0;
+      });
       if (invalid.length) {
         e.preventDefault();
         reveal(invalid[0]);
@@ -3139,11 +3207,13 @@
         submitted = true;
         var invalid = [];
         Array.prototype.forEach.call(controls(), function (el) { if (!validateOne(el)) invalid.push(el); });
+        kitRoots(form).forEach(function (root) { if (!validateKit(root)) invalid.push(kitAria(root)); });
         return invalid;
       },
       reset: function () {
         submitted = false;
         Array.prototype.forEach.call(controls(), function (el) { paint(el, ''); });
+        kitRoots(form).forEach(function (root) { paint(kitAria(root), ''); });
       }
     };
     form._fdyForm = api;
@@ -4945,6 +5015,14 @@
     trigger.setAttribute('aria-haspopup', 'listbox');
     trigger.setAttribute('aria-expanded', 'false');
     trigger.setAttribute('aria-label', label);
+    /* The trigger is a <button>, which is NOT a labelable element, so a form's own `<label for>`
+       can never activate it -- but an id is still what `aria-describedby` targets and what a host
+       needs to point at this control. Both were unreadable from the seed until now, so a Blazor
+       host could not name its own error text. Mirrors the datepicker's seed. */
+    var seedId = wrap.getAttribute('data-id');
+    if (seedId) trigger.id = seedId;
+    var describedby = wrap.getAttribute('data-describedby');
+    if (describedby) trigger.setAttribute('aria-describedby', describedby);
     var valueSpan = document.createElement('span');
     valueSpan.className = 'fdy-timepicker__value';
     trigger.appendChild(valueSpan);
@@ -4982,8 +5060,37 @@
     wrap.appendChild(panel);
 
     var active = -1;
+    /* A host that renders its seed ONCE and then never re-renders it (Blazor: ShouldRender is
+       false after hydration) still has to be able to disable, lock or invalidate the field
+       afterwards. Without this the parameter was there and nothing read it. Mirrors
+       FreedayDatepicker.setState so the two controls of one family answer the same call. */
+    var stateDisabled = wrap.hasAttribute('data-disabled');
+    var stateReadonly = wrap.hasAttribute('data-readonly');
+    var stateInvalid = wrap.hasAttribute('data-invalid');
+
+    function applyState() {
+      trigger.disabled = stateDisabled;
+      if (stateReadonly) trigger.setAttribute('aria-readonly', 'true');
+      else trigger.removeAttribute('aria-readonly');
+      if (stateInvalid) trigger.setAttribute('aria-invalid', 'true');
+      else trigger.removeAttribute('aria-invalid');
+      wrap.classList.toggle('fdy-timepicker--error', stateInvalid);
+      if ((stateDisabled || stateReadonly) && !panel.hidden) close(false);
+    }
+    function setState(next) {
+      if (!next) return;
+      if (next.disabled != null) stateDisabled = !!next.disabled;
+      if (next.readonly != null) stateReadonly = !!next.readonly;
+      if (next.invalid != null) stateInvalid = !!next.invalid;
+      applyState();
+    }
 
     function updateDisplay() {
+      /* Mirror the value onto the ROOT, which until now only seeded it. `freeday-select.js` has
+         always done this, so this makes the family agree rather than inventing a second idea, and
+         it is what lets `freeday-form.js` require a kit control without knowing which control it
+         is: one attribute instead of five event names (#096). */
+      wrap.setAttribute('data-value', value);
       if (value) {
         valueSpan.textContent = value;
         valueSpan.classList.remove('fdy-timepicker__value--placeholder');
@@ -5010,6 +5117,7 @@
     var _pop = null;
     function popCtl() { if (_pop === null && window.FreedayPopover) _pop = window.FreedayPopover.attach(panel, trigger); return _pop; }
     function open() {
+      if (stateDisabled || stateReadonly) return;
       if (!panel.hidden) return;
       var p = popCtl(); if (p) p.show(); else panel.hidden = false;
       trigger.setAttribute('aria-expanded', 'true');
@@ -5060,10 +5168,12 @@
     });
 
     updateDisplay();
+    applyState();
 
     var api = {
       wrap: wrap,
       getValue: function () { return value; },
+      setState: setState,
       clear: function () { value = ''; for (var i = 0; i < opts.length; i++) opts[i].setAttribute('aria-selected', 'false'); updateDisplay(); }
     };
     wrap._fdyTp = api;
@@ -5083,7 +5193,15 @@
     initAll();
   }
 
-  window.FreedayTimepicker = { init: initTime, initAll: initAll };
+  window.FreedayTimepicker = {
+    init: initTime,
+    initAll: initAll,
+    /* See api.setState above: the one call a render-once host needs. */
+    setState: function (root, state) {
+      var api = root && root._fdyTp ? root._fdyTp : null;
+      if (api && api.setState) api.setState(state);
+    }
+  };
 })();
 
 /* Freeday, toast API (optional, zero-dependency).

package/docs/agent-onboarding.md

@@ -33,9 +33,9 @@ and the code looks correct and fails later.**
 | Blazor (net8.0) | `@using Freeday.Blazor` (RCL) | `@bind-Value` |
 | Static HTML, Svelte, server-rendered templates… | no wrapper: raw markup + the enhancer script | `fdy-*` DOM events |
 
-The twelve: **FdyCombo · FdyDatepicker · FdyMonthpicker · FdyDateRange · FdyAutocomplete ·
-FdyCascade · FdyCfl · FdyChart · FdyTable · FdyModal · FdyDrawer · FdyAppShell**. In
-Vue/React/Blazor, **never hand-write the raw markup + enhancer for these twelve.** The raw path *appears* to work: the enhancer auto-initialises
+The thirteen: **FdyCombo · FdyDatepicker · FdyMonthpicker · FdyDateRange · FdyTimepicker ·
+FdyAutocomplete · FdyCascade · FdyCfl · FdyChart · FdyTable · FdyModal · FdyDrawer · FdyAppShell**. In
+Vue/React/Blazor, **never hand-write the raw markup + enhancer for these thirteen.** The raw path *appears* to work: the enhancer auto-initialises
 once on `DOMContentLoaded` and the first render is correct. Then it fails quietly: DOM your framework
 renders later is never hydrated, and the widget's state lives in the DOM instead of in your
 framework's state.

package/docs/getting-started.md

@@ -21,8 +21,8 @@ Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enh
    the enhancer owns the widget's DOM. You **listen for `fdy-*` events** (all bubbling
    `CustomEvent`s, data in `event.detail`) → store them in your framework state. Event/API contract
    table: [`integrations.md` §Event & API contract](integrations.md).
-   **On Vue, React or Blazor this is not the path to take for twelve of the components.** `FdyCombo`,
-   `FdyDatepicker`, `FdyMonthpicker`, `FdyDateRange`, `FdyAutocomplete`, `FdyCascade`, `FdyCfl`,
+   **On Vue, React or Blazor this is not the path to take for thirteen of the components.** `FdyCombo`,
+   `FdyDatepicker`, `FdyMonthpicker`, `FdyDateRange`, `FdyTimepicker`, `FdyAutocomplete`, `FdyCascade`, `FdyCfl`,
    `FdyChart`, `FdyTable`, `FdyModal`, `FdyDrawer`, `FdyAppShell` ship typed wrappers that own the state properly (Vue and
    React re-implement the interaction natively; Blazor wraps the enhancer over interop). Use them;
    the raw path is for the components without a wrapper, and for stacks without an adapter.
@@ -198,7 +198,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.10.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.12.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)
@@ -451,9 +451,9 @@ kit's CSS/enhancers), then bind:
 <FdyChart Type="donut" Values="_byCity" Labels="_cityLabels" AriaLabel="Revenue by city" />
 <FdyDrawer @bind-Open="_drawerOpen" Title="Detail" Side="right">…</FdyDrawer>
 ```
-Twelve components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
+Thirteen components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
 `Title`, `Size`/`Side`, `Dismissible`) · **`FdyCombo<TValue>`** · **`FdyDatepicker`** ·
-**`FdyMonthpicker`** (`@bind-Value` as `yyyy-MM`) · **`FdyAutocomplete`** · **`FdyCascade`** · **`FdyDateRange`** (`@bind-From`/`@bind-To`) ·
+**`FdyMonthpicker`** (`@bind-Value` as `yyyy-MM`) · **`FdyTimepicker`** (`@bind-Value` as `HH:MM`) · **`FdyAutocomplete`** · **`FdyCascade`** · **`FdyDateRange`** (`@bind-From`/`@bind-To`) ·
 **`FdyCfl<TRow>`** (async `LoadPage`) · **`FdyChart`** · **`FdyTable<TRow>`** (client sort/filter/page,
 or controlled `Sort`/`Filters`/`Page` for a server-paged table; `RowActivatable`, `RowDetail`) ·
 **`FdyAppShell`** (`@bind-NavOpen`). Each

package/docs/integrations.md

@@ -154,7 +154,7 @@ function Panel(): JSX.Element {
 ```
 > **Controlled alternative (parity with Vue's `v-model`):** `@cahyo-dimas/freeday/react` also exports
 > the typed components `FdyCombo` / `FdyDatepicker` / `FdyMonthpicker` / `FdyDateRange` /
-> `FdyAutocomplete` / `FdyCascade` / `FdyCfl` / `FdyChart` / `FdyTable` / `FdyModal` / `FdyDrawer` /
+> `FdyTimepicker` / `FdyAutocomplete` / `FdyCascade` / `FdyCfl` / `FdyChart` / `FdyTable` / `FdyModal` / `FdyDrawer` /
 > `FdyAppShell`, with plain
 > `value`/`onChange` (props in, events out), no `data-fdy-*` + manual event listener:
 > ```tsx
@@ -200,7 +200,7 @@ document.addEventListener('fdy-form-invalid', (e) =>
 
 > **Native components (parity with Vue's `v-model` / React's `value`/`onChange`):** the
 > **`Freeday.Blazor`** RCL (net8.0, `adapters/blazor/`) ships the typed components `FdyCombo<TValue>` /
-> `FdyDatepicker` / `FdyMonthpicker` / `FdyDateRange` / `FdyAutocomplete` / `FdyCascade` /
+> `FdyDatepicker` / `FdyMonthpicker` / `FdyDateRange` / `FdyTimepicker` / `FdyAutocomplete` / `FdyCascade` /
 > `FdyCfl<TRow>` / `FdyChart` / `FdyTable<TRow>` / `FdyModal` / `FdyDrawer` / `FdyAppShell` with `@bind`, no `@ref` / manual `initAll` / `[JSInvokable]`:
 > ```razor
 > @using Freeday.Blazor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Freeday: token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -96,7 +96,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test --test-concurrency=3 browser/color-mix.mjs browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/tabs-vertical.mjs browser/menu-align.mjs browser/cfl-narrow.mjs browser/form-reveal.mjs browser/confirm-search-copy.mjs browser/daterange-settled.mjs browser/display-parts.mjs browser/table-empty.mjs browser/table-footer-text.mjs browser/month-mode.mjs browser/monthpicker.mjs browser/page-columns.mjs browser/table-hover.mjs browser/typed-popover.mjs browser/filter-parity.mjs browser/filter-wrap.mjs browser/filter-stack.mjs browser/harness-contract.mjs",
+    "test:browser": "node --test --test-concurrency=3 browser/color-mix.mjs browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/tabs-vertical.mjs browser/menu-align.mjs browser/cfl-narrow.mjs browser/form-reveal.mjs browser/confirm-search-copy.mjs browser/daterange-settled.mjs browser/display-parts.mjs browser/table-empty.mjs browser/table-footer-text.mjs browser/month-mode.mjs browser/monthpicker.mjs browser/page-columns.mjs browser/table-hover.mjs browser/typed-popover.mjs browser/filter-parity.mjs browser/filter-wrap.mjs browser/filter-stack.mjs browser/timepicker.mjs browser/form-kit-required.mjs browser/harness-contract.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit",