@cahyo-dimas/freeday 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -3,6 +3,92 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.24.0] — 2026-08-13
+Improvement note #41: the upload row had no "chosen, not yet sent" state, so every consumer-driven
+integration showed a transfer that had not started.
+### Fixed
+- **A dropped file now rests until the consumer starts the transfer.** `handleFiles` called
+  `row.uploading()` unconditionally — and *before* dispatching `fdy-upload-add`, so a consumer could
+  not pre-empt it. Between the drop and the app's own submit button (which may be a minute, while the
+  user fills in the rest of the form) the row claimed to be uploading, with a progress bar that never
+  moved. A user watching that reasonably concludes the upload has hung and reports a bug against a
+  transfer that was never started. The state machine was missing its start state: `done()` claims
+  success, `fail()` claims an error, and `uploading()` was where it already was.
+  The demo path is unchanged — with `data-fdy-upload-simulate` the kit *is* performing a transfer, so
+  showing one stays correct. That attribute already marks the only place the old default was right,
+  which is why this changes the default rather than adding an opt-in: making correct integrations opt
+  in to correctness is backwards.
+- **`fdy-upload-add` no longer depends on rendering a row.** The guard was `if (!list || !fileList)
+  return;`, so a dropzone with no file list lost the event that tells the app a file arrived —
+  "bring your own row" silently cost you the notification. Rendering and announcing are now separate:
+  no list means no row is attached, and the event still fires with a working `detail.row`.
+  Deliberately **no new attribute** for this. The reporter proposed `data-rows="off"`; `list` is used
+  in exactly two places, so decoupling covers the same case without growing the API surface, and no
+  page can be relying on "no event".
+### Added
+- **`row.ready()`** — the rest state, and the way back to it (a failed attempt the user will retry).
+  It reuses the existing `dropProgress()`, so the bar is removed exactly as `done()`/`fail()` do it.
+### Docs
+- **`COMPONENTS.md` documents the row state machine at all.** `uploading()` / `setProgress()` /
+  `done()` / `fail()` had **zero** mentions anywhere in the shipped docs — a consumer holding
+  `detail.row` had no supported way to know they existed, which is a fair part of why the old default
+  went unquestioned. The section now carries the state table, a worked example, the
+  bring-your-own-row position, and `data-fdy-upload-simulate` marked demo-only.
+  Two corrections to the report while transcribing it: the function is `handleFiles` (not `addFiles`)
+  and the attribute is `data-fdy-upload-simulate` (not `data-simulate`) — the latter matters, since
+  documenting the wrong name would have consumers set an attribute that does nothing.
+### Added — guards
+- **`browser/upload-states.mjs`** — drops a real `File` and asserts the rest state shows no progress
+  bar, that `uploading()` → `setProgress()` → `done()` still chains, that the simulate path is
+  untouched, and that a listless dropzone still dispatches. Mutation-checked on both halves.
+  The fixture wraps the listless dropzone in its own container **on purpose**: with no
+  `data-filelist` the enhancer falls back to `parentNode.querySelector('.fdy-filelist')`, so a bare
+  dropzone sharing a parent with another list adopts it — the first version of this guard was
+  testing nothing, and the mutation run is what exposed that.
+
+## [1.23.0] — 2026-08-13
+Consumption round 6 (`improvement-notes/006`). The reporter filed two of the three as **their own**
+bugs rather than the kit's — and they were right about the code, but in both cases the kit had a way
+to make the mistake impossible and had not taken it. Those are the two most valuable findings here.
+### Fixed
+- **`initAll(ctx)` now enhances `ctx` itself, not just its descendants.** `querySelectorAll` never
+  matches its own root, so a framework ref placed **on** the widget — `<div ref="menu" data-fdy-menu>`,
+  which is the ordinary shape when a component's root element *is* the widget — meant the one element
+  that needed enhancing was the only one that could not be found. It failed with **no error, no
+  warning, and a UI that looked finished**: the markup rendered and simply never opened. Measured
+  before the fix: `data-fdy-menu-ready` stayed `null` and `aria-expanded` stayed `"false"` while
+  `initAll` was present and callable the whole time; `initAll(parent)` worked. One `matches()` line
+  per selector, in **all 21 enhancers** (`drawer` and `cfl` needed their inline trigger callbacks
+  hoisted first). Init was already idempotent via each widget's `-ready` flag, so a root that is also
+  matched by the descendant query costs nothing. `useFreeday` (Vue/React) and `FreedayBlazor.initAll`
+  delegate to these, so they inherit the fix with no change of their own.
+- **The stepper connector no longer draws through the markers when `__btn` is omitted.** The lift now
+  lives on `.fdy-step__marker` — the part that must always exist — instead of only on
+  `.fdy-step__btn`. The connector is `position:absolute; z-index:0`, and a positioned box paints
+  *after* in-flow inline content in the same stacking context, so a marker that was merely inline got
+  painted over: not for lack of a z-index, but for lack of being positioned at all. An
+  indicator-only stepper (no navigation, so no button) is a reasonable thing to write and it produced
+  a visible defect in shipped UI. Measured: hit-testing the marker's centre returned the connector's
+  own `.fdy-step` before, the marker after. `__btn` keeps its z-index for the navigable case.
+### Added
+- **`.fdy-avatar--xs`** (1.5rem, `--text-xs`) — an avatar inside a control had nothing to reach for:
+  `.fdy-btn--sm` is `calc(var(--control-h) - var(--space-2))` = **2rem**, exactly `--avatar--sm`'s
+  size, so the monogram filled a small button edge to edge and the ghost border crossed the circle
+  (measured: trigger 32px tall, avatar 32×32). 1.5rem inside 2rem leaves the ~4px the kit's other
+  controls give their icons. The report suggested `--text-2xs`; that token does not exist — `--text-xs`
+  is the smallest the kit has, and inventing a type step for one avatar size is not worth it.
+### Added — guards
+- **`browser/root-init.mjs`** — mounts a widget *after* load, initialises it through its own root, and
+  drives a **real click** to prove it opens; repeated for a second enhancer so the fix reads as the
+  shared pattern rather than a one-off. Mutation-checked on both. Being marked `-ready` is explicitly
+  not accepted as passing: an early version of this check reported success against markup the enhancer
+  had actually bailed on.
+### Docs
+- `COMPONENTS.md`: `initAll(root)` documents that the root may be the widget itself; the stepper
+  section states that `__btn` is **optional** and shows the read-only indicator markup (the parts list
+  never said which parts were optional); avatar gains its size table with the in-control guidance.
+- Both `useFreeday` docstrings now show the ref-on-the-widget shape alongside the wrapping one.
+
 ## [1.22.0] — 2026-08-12
 Two bodies of work. **(a)** three more findings from consumption round 5 — the report grew §5-§7
 after 1.21.0 was cut; **(b)** a **routing** failure found in the same adopted project, which had been

package/COMPONENTS.md

@@ -65,7 +65,9 @@ Two consequences for you:
 ## Enhancers — hook, script, global, events
 
 Every enhancer is zero-dependency, auto-initialises once on `DOMContentLoaded`, and is idempotent:
-re-hydrate SPA-rendered DOM with `window.Freeday<X>.initAll(root)`. Events are bubbling
+re-hydrate SPA-rendered DOM with `window.Freeday<X>.initAll(root)`. **`root` may be the widget
+itself or an ancestor of it** — both work, so a framework ref placed directly on the enhanced
+element is fine. Events are bubbling
 `CustomEvent`s; the payload is in `event.detail`.
 
 | Markup hook | Script | Global | Emits |
@@ -476,9 +478,41 @@ Click/Enter opens the file dialog; drop works too. Needs `freeday-upload.js`.
   `<input type="file">`
 - List: `.fdy-filelist` (+`--grid`) of `.fdy-file` (+`--success`, `--error`) · `__icon` `__meta`
   `__name` `__sub` `__progress` `__remove`
-- Attributes: `data-max-size` (bytes), `data-filelist="#id"`
+- Attributes: `data-max-size` (bytes), `data-filelist="#id"`, `data-fdy-upload-simulate` (demo only
+  — the kit fakes a transfer to `done()`; never set it in an app)
 - A11y: the dropzone is `role="button" tabindex="0"` + `aria-label`.
-- Wire `fdy-upload-add` to your real upload; render explicit progress/success/error state.
+
+**The row is yours to drive.** `fdy-upload-add` carries `detail.row`, a small state machine over the
+rendered `.fdy-file`. A dropped file **rests** — it shows its size and nothing else — until you say a
+transfer started; the kit never claims one it is not performing.
+
+| `detail.row` | State it renders |
+|---|---|
+| *(initial)* | **rest** — chosen, not sent. Size only, no progress bar. |
+| `.uploading()` | in flight — adds the progress bar |
+| `.setProgress(pct)` | moves the bar (0–100) |
+| `.done()` | success — drops the bar, `.fdy-file--success` |
+| `.fail(msg)` | error — drops the bar, `.fdy-file--error`, `msg` replaces the sub-line |
+| `.ready()` | back to **rest** (e.g. after a failed attempt the user will retry) |
+| `.el` | the row element |
+
+```js
+zone.addEventListener('fdy-upload-add', (e) => {
+  if (e.detail.rejected) return;              // the kit already rendered the reason
+  const { file, row } = e.detail;             // row is at rest — nothing is in flight yet
+  submitBtn.onclick = async () => {
+    row.uploading();
+    await send(file, (pct) => row.setProgress(pct));
+    row.done();
+  };
+});
+```
+
+**Bring your own row:** omit the file list entirely (no `data-filelist`, and no `.fdy-filelist`
+sibling) and the enhancer renders nothing while still dispatching `fdy-upload-add` — `detail.row`
+still works, its element simply isn't attached. Note the fallback when `data-filelist` is absent is
+`parentNode.querySelector('.fdy-filelist')`, so a bare dropzone will adopt a list that happens to
+share its parent; give the dropzone its own container if you mean "no list".
 
 ## Form validation — `data-fdy-validate`
 Native Constraint Validation wired to accessible inline errors: `aria-invalid` +
@@ -526,6 +560,18 @@ Linear multi-step flow: marker → check, one panel at a time, back/next. Needs
 
 # Data
 
+**`__btn` is optional.** For a **read-only indicator** put `__marker` + `__label` straight in the
+`<li>`; for a **navigable** stepper wrap them in `<button class="fdy-step__btn">` (add `disabled`
+for a step that is not reachable yet). Both render identically — the marker carries its own lift
+over the connector line, so omitting `__btn` cannot make the connector draw through the numbers.
+
+```html
+<ol class="fdy-stepper">
+  <li class="fdy-step is-complete"><span class="fdy-step__marker">1</span><span class="fdy-step__label">Email</span></li>
+  <li class="fdy-step is-active"><span class="fdy-step__marker">2</span><span class="fdy-step__label">Verify</span></li>
+</ol>
+```
+
 ## Table — `.fdy-table`
 Semantic static table. Wrap in `.fdy-table-wrap` (bordered surface) or `.fdy-table-scroll`
 (horizontal scroll). Always a `<caption>` (use `.fdy-visually-hidden` if it shouldn't show) and
@@ -813,6 +859,10 @@ Initials or image. Sizes `--sm` / default / `--lg`; `.fdy-avatar-group` stacks t
 group). `--tone-1`…`--tone-8` are decorative tints (WCAG AA in both themes) to distinguish
 same-initial avatars — hash the index off the **full** name, not the initials.
 
+Sizes: `--xs` 1.5rem · *(base)* 2.5rem · `--sm` 2rem · `--lg` 3.5rem. Use **`--xs` inside a control**
+— `.fdy-btn--sm` is itself 2rem tall, so an `--sm` avatar fills a small button edge to edge and the
+ghost border cuts across the circle.
+
 ## Chip — `.fdy-chip`
 Three roles inside a `.fdy-chips` row:
 

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.22.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.22.0)
+[![Release](https://img.shields.io/badge/release-v1.24.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.24.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.22.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.22.0)
+[![Release](https://img.shields.io/badge/release-v1.24.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.24.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/adapters/react/useFreeday.js

@@ -9,6 +9,11 @@
  *   useFreeday(root);            // scopes init to this component's subtree
  *   // <div ref={root}> ...[data-fdy-*] markup... </div>
  *
+ * The ref may also sit ON the widget itself — <div ref={root} data-fdy-menu> — which is what you
+ * write when the component's root element IS the widget. initAll() matches its own root as
+ * well as descendants, so both shapes work. (Before 1.23.0 only the wrapping shape did, and
+ * the other failed silently: querySelectorAll never matches its root.)
+ *
  * Events are native bubbling CustomEvents — add listeners on the root (they
  * bubble) and read event.detail. See index.d.ts for the detail types.
  */

package/adapters/vue/useFreeday.js

@@ -10,6 +10,11 @@
  *   useFreeday(root);            // scopes init to this component's subtree
  *   // <div ref="root"> ...[data-fdy-*] markup... </div>
  *
+ * The ref may also sit ON the widget itself — <div ref="root" data-fdy-menu> — which is what you
+ * write when the component's root element IS the widget. initAll() matches its own root as
+ * well as descendants, so both shapes work. (Before 1.23.0 only the wrapping shape did, and
+ * the other failed silently: querySelectorAll never matches its root.)
+ *
  * Events come straight through as native bubbling CustomEvents — bind them with
  * plain v-on (e.g. @fdy-cascade-change) and read event.detail. See index.d.ts
  * for the detail types.

package/dist/freeday-autocomplete.js

@@ -122,7 +122,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-autocomplete]')) initAutocomplete(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-carousel.js

@@ -98,7 +98,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-carousel]'), initCarousel);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-carousel]')) initCarousel(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-carousel]'), initCarousel);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-cascade.js

@@ -243,7 +243,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-cascade]'), initCascade);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-cascade]')) initCascade(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-cascade]'), initCascade);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-cfl.js

@@ -179,28 +179,33 @@
     };
   }
 
-  function initTriggers(context) {
-    var ctx = context || document;
+  function bindGroup(group) {
+    if (group.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
+    if (!dialog) return;
+    initDialog(dialog);
+    var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
+    if (!opener) return;
+    group.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), function (group) {
-      if (group.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
-      if (!dialog) return;
-      initDialog(dialog);
-      var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
-      if (!opener) return;
-      group.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
-    });
+  function bindOpener(opener) {
+    if (opener.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
+    if (!dialog) return;
+    initDialog(dialog);
+    opener.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), function (opener) {
-      if (opener.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
-      if (!dialog) return;
-      initDialog(dialog);
-      opener.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
-    });
+  function initTriggers(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-cfl]')) bindGroup(ctx);
+    if (ctx.matches && ctx.matches('[data-fdy-cfl-open]')) bindOpener(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), bindGroup);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), bindOpener);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-chart.js

@@ -416,7 +416,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-chart]'), initChart);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chart]')) initChart(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chart]'), initChart);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-chip.js

@@ -69,6 +69,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chips]')) initGroup(root);
+    if (root.matches && root.matches('.fdy-chip__remove')) initRemove(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chips]'), initGroup);
     Array.prototype.forEach.call(root.querySelectorAll('.fdy-chip__remove'), initRemove);
   }

package/dist/freeday-datepicker.js

@@ -306,9 +306,12 @@
   }
 
   function initAll(context) {
-    var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-daterange]'), initRange);
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-datepicker]'), initPicker);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-daterange]')) initRange(root);
+    if (root.matches && root.matches('[data-fdy-datepicker]')) initPicker(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-daterange]'), initRange);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datepicker]'), initPicker);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-datetime.js

@@ -70,7 +70,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-datetimepicker]')) initDatetime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-drawer.js

@@ -16,19 +16,24 @@
     });
   }
 
+  function bindTrigger(btn) {
+    if (btn.dataset.fdyDrawerBound === '1') return;
+    var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
+    if (!dialog) return;
+    initDrawer(dialog);
+    btn.dataset.fdyDrawerBound = '1';
+    btn.addEventListener('click', function () {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    });
+  }
+
   function initTriggers(context) {
     var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), function (btn) {
-      if (btn.dataset.fdyDrawerBound === '1') return;
-      var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
-      if (!dialog) return;
-      initDrawer(dialog);
-      btn.dataset.fdyDrawerBound = '1';
-      btn.addEventListener('click', function () {
-        if (typeof dialog.showModal === 'function') dialog.showModal();
-        else dialog.setAttribute('open', '');
-      });
-    });
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-drawer]')) bindTrigger(ctx);
+    if (ctx.matches && ctx.matches('.fdy-drawer')) initDrawer(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), bindTrigger);
     // Init any drawer dialogs even without a wired trigger (backdrop/close still work).
     Array.prototype.forEach.call(ctx.querySelectorAll('.fdy-drawer'), initDrawer);
   }

package/dist/freeday-form.js

@@ -168,7 +168,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-validate]'), initForm);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-validate]')) initForm(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-validate]'), initForm);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-mask.js

@@ -100,6 +100,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-mask]')) initMask(root);
+    if (root.matches && root.matches('[data-fdy-password]')) initReveal(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-mask]'), initMask);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-password]'), initReveal);
   }

package/dist/freeday-menu.js

@@ -80,7 +80,10 @@
   }
 
   function initAll(ctx) {
-    Array.prototype.forEach.call((ctx || document).querySelectorAll('[data-fdy-menu]'), initMenu);
+    var root = ctx || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-menu]')) initMenu(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-menu]'), initMenu);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-rating.js

@@ -37,7 +37,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-rating]'), initRating);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-rating]')) initRating(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-rating]'), initRating);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-select.js

@@ -189,11 +189,10 @@
   }
 
   function initAll(context) {
-    var scope = context || document;
-    Array.prototype.forEach.call(
-      scope.querySelectorAll('[data-fdy-combo]'),
-      initCombo
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-combo]')) initCombo(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-combo]'), initCombo);
   }
 
   // One global handler closes the open combo on an outside click.

package/dist/freeday-slider.js

@@ -21,7 +21,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-slider]'), initSlider);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-slider]')) initSlider(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-slider]'), initSlider);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-stepper.js

@@ -77,7 +77,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-stepper]'), initStepper);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-stepper]')) initStepper(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-stepper]'), initStepper);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-table.js

@@ -459,10 +459,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-table]'),
-      initTable
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-table]')) initTable(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-table]'), initTable);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-tabs.js

@@ -52,10 +52,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-tabs]'),
-      initTabs
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tabs]')) initTabs(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tabs]'), initTabs);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-timepicker.js

@@ -167,7 +167,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-timepicker]'), initTime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-timepicker]')) initTime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-timepicker]'), initTime);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-tree.js

@@ -81,7 +81,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-tree]'), initTree);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tree]')) initTree(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tree]'), initTree);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-upload.js

@@ -95,6 +95,16 @@
     }
     return {
       el: el,
+      /* The state a row starts in: chosen, not yet sent. The size alone — it makes no claim about
+         a transfer, and no progress bar is shown, because nothing is in flight. Without this the
+         state machine had no start state: done() claims success, fail() claims an error, and
+         uploading() is a lie until the consumer actually sends the file. */
+      ready: function () {
+        el.classList.remove('fdy-file--error', 'fdy-file--success');
+        icon.innerHTML = FILE_ICON;
+        sub.textContent = fmtSize(file.size);
+        dropProgress();
+      },
       uploading: function () {
         el.classList.remove('fdy-file--error', 'fdy-file--success');
         icon.innerHTML = FILE_ICON;
@@ -171,19 +181,30 @@
     });
     if (input) input.addEventListener('change', function () { handleFiles(input.files); input.value = ''; });
 
+    /* The list is optional: rendering a row and announcing the file are separate jobs. A consumer
+       that wants its own markup simply provides no list — it still gets `fdy-upload-add`, and
+       `detail.row` still works (its element is just never attached). Gating the EVENT on the list
+       meant "bring your own row" silently cost you the notification that a file had arrived. */
     function handleFiles(fileList) {
-      if (!list || !fileList) return;
+      if (!fileList) return;
       Array.prototype.slice.call(fileList).forEach(function (file) {
         var reason = null;
         if (!accepts(file, acceptAttr)) reason = 'Tipe berkas tidak didukung.';
         else if (maxSize && file.size > maxSize) reason = 'Ukuran melebihi batas (' + fmtSize(maxSize) + ').';
         var row = makeRow(file);
-        list.appendChild(row.el);
+        if (list) list.appendChild(row.el);
         if (reason) {
           row.fail(reason);
-        } else {
+        } else if (simulate) {
+          /* The kit is driving (demo path): keep showing a transfer, because there is one. */
           row.uploading();
-          if (simulate) simulateUpload(row);
+          simulateUpload(row);
+        } else {
+          /* The CONSUMER owns the transfer. Rest until it says otherwise by calling row.uploading():
+             a file that has only been chosen must not claim to be uploading. A progress bar that
+             never moves reads as a hung upload, and gets reported as a bug against a transfer that
+             was never started. */
+          row.ready();
         }
         zone.dispatchEvent(new CustomEvent('fdy-upload-add', {
           bubbles: true, detail: { file: file, rejected: !!reason, reason: reason, row: row }
@@ -193,7 +214,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-dropzone]'), initDropzone);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-dropzone]')) initDropzone(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-dropzone]'), initDropzone);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday.bundle.css

@@ -586,6 +586,11 @@ a { color: var(--color-primary); }
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}
@@ -1457,7 +1462,12 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}

package/dist/freeday.css

@@ -216,6 +216,11 @@ a { color: var(--color-primary); }
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}
@@ -1087,7 +1092,12 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}

package/dist/freeday.js

@@ -124,7 +124,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-autocomplete]')) initAutocomplete(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
   }
 
   if (document.readyState === 'loading') {
@@ -288,7 +291,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-carousel]'), initCarousel);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-carousel]')) initCarousel(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-carousel]'), initCarousel);
   }
 
   if (document.readyState === 'loading') {
@@ -545,7 +551,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-cascade]'), initCascade);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-cascade]')) initCascade(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-cascade]'), initCascade);
   }
 
   if (document.readyState === 'loading') {
@@ -738,28 +747,33 @@
     };
   }
 
-  function initTriggers(context) {
-    var ctx = context || document;
+  function bindGroup(group) {
+    if (group.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
+    if (!dialog) return;
+    initDialog(dialog);
+    var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
+    if (!opener) return;
+    group.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), function (group) {
-      if (group.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
-      if (!dialog) return;
-      initDialog(dialog);
-      var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
-      if (!opener) return;
-      group.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
-    });
+  function bindOpener(opener) {
+    if (opener.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
+    if (!dialog) return;
+    initDialog(dialog);
+    opener.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), function (opener) {
-      if (opener.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
-      if (!dialog) return;
-      initDialog(dialog);
-      opener.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
-    });
+  function initTriggers(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-cfl]')) bindGroup(ctx);
+    if (ctx.matches && ctx.matches('[data-fdy-cfl-open]')) bindOpener(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), bindGroup);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), bindOpener);
   }
 
   if (document.readyState === 'loading') {
@@ -1189,7 +1203,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-chart]'), initChart);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chart]')) initChart(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chart]'), initChart);
   }
 
   if (document.readyState === 'loading') {
@@ -1272,6 +1289,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chips]')) initGroup(root);
+    if (root.matches && root.matches('.fdy-chip__remove')) initRemove(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chips]'), initGroup);
     Array.prototype.forEach.call(root.querySelectorAll('.fdy-chip__remove'), initRemove);
   }
@@ -1593,9 +1613,12 @@
   }
 
   function initAll(context) {
-    var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-daterange]'), initRange);
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-datepicker]'), initPicker);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-daterange]')) initRange(root);
+    if (root.matches && root.matches('[data-fdy-datepicker]')) initPicker(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-daterange]'), initRange);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datepicker]'), initPicker);
   }
 
   if (document.readyState === 'loading') {
@@ -1679,7 +1702,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-datetimepicker]')) initDatetime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
   }
 
   if (document.readyState === 'loading') {
@@ -1709,19 +1735,24 @@
     });
   }
 
+  function bindTrigger(btn) {
+    if (btn.dataset.fdyDrawerBound === '1') return;
+    var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
+    if (!dialog) return;
+    initDrawer(dialog);
+    btn.dataset.fdyDrawerBound = '1';
+    btn.addEventListener('click', function () {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    });
+  }
+
   function initTriggers(context) {
     var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), function (btn) {
-      if (btn.dataset.fdyDrawerBound === '1') return;
-      var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
-      if (!dialog) return;
-      initDrawer(dialog);
-      btn.dataset.fdyDrawerBound = '1';
-      btn.addEventListener('click', function () {
-        if (typeof dialog.showModal === 'function') dialog.showModal();
-        else dialog.setAttribute('open', '');
-      });
-    });
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-drawer]')) bindTrigger(ctx);
+    if (ctx.matches && ctx.matches('.fdy-drawer')) initDrawer(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), bindTrigger);
     // Init any drawer dialogs even without a wired trigger (backdrop/close still work).
     Array.prototype.forEach.call(ctx.querySelectorAll('.fdy-drawer'), initDrawer);
   }
@@ -1905,7 +1936,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-validate]'), initForm);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-validate]')) initForm(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-validate]'), initForm);
   }
 
   if (document.readyState === 'loading') {
@@ -2019,6 +2053,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-mask]')) initMask(root);
+    if (root.matches && root.matches('[data-fdy-password]')) initReveal(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-mask]'), initMask);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-password]'), initReveal);
   }
@@ -2114,7 +2151,10 @@
   }
 
   function initAll(ctx) {
-    Array.prototype.forEach.call((ctx || document).querySelectorAll('[data-fdy-menu]'), initMenu);
+    var root = ctx || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-menu]')) initMenu(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-menu]'), initMenu);
   }
 
   if (document.readyState === 'loading') {
@@ -2235,7 +2275,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-rating]'), initRating);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-rating]')) initRating(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-rating]'), initRating);
   }
 
   if (document.readyState === 'loading') {
@@ -2438,11 +2481,10 @@
   }
 
   function initAll(context) {
-    var scope = context || document;
-    Array.prototype.forEach.call(
-      scope.querySelectorAll('[data-fdy-combo]'),
-      initCombo
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-combo]')) initCombo(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-combo]'), initCombo);
   }
 
   // One global handler closes the open combo on an outside click.
@@ -2489,7 +2531,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-slider]'), initSlider);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-slider]')) initSlider(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-slider]'), initSlider);
   }
 
   if (document.readyState === 'loading') {
@@ -2580,7 +2625,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-stepper]'), initStepper);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-stepper]')) initStepper(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-stepper]'), initStepper);
   }
 
   if (document.readyState === 'loading') {
@@ -3053,10 +3101,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-table]'),
-      initTable
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-table]')) initTable(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-table]'), initTable);
   }
 
   if (document.readyState === 'loading') {
@@ -3122,10 +3170,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-tabs]'),
-      initTabs
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tabs]')) initTabs(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tabs]'), initTabs);
   }
 
   if (document.readyState === 'loading') {
@@ -3306,7 +3354,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-timepicker]'), initTime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-timepicker]')) initTime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-timepicker]'), initTime);
   }
 
   if (document.readyState === 'loading') {
@@ -3507,7 +3558,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-tree]'), initTree);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tree]')) initTree(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tree]'), initTree);
   }
 
   if (document.readyState === 'loading') {
@@ -3616,6 +3670,16 @@
     }
     return {
       el: el,
+      /* The state a row starts in: chosen, not yet sent. The size alone — it makes no claim about
+         a transfer, and no progress bar is shown, because nothing is in flight. Without this the
+         state machine had no start state: done() claims success, fail() claims an error, and
+         uploading() is a lie until the consumer actually sends the file. */
+      ready: function () {
+        el.classList.remove('fdy-file--error', 'fdy-file--success');
+        icon.innerHTML = FILE_ICON;
+        sub.textContent = fmtSize(file.size);
+        dropProgress();
+      },
       uploading: function () {
         el.classList.remove('fdy-file--error', 'fdy-file--success');
         icon.innerHTML = FILE_ICON;
@@ -3692,19 +3756,30 @@
     });
     if (input) input.addEventListener('change', function () { handleFiles(input.files); input.value = ''; });
 
+    /* The list is optional: rendering a row and announcing the file are separate jobs. A consumer
+       that wants its own markup simply provides no list — it still gets `fdy-upload-add`, and
+       `detail.row` still works (its element is just never attached). Gating the EVENT on the list
+       meant "bring your own row" silently cost you the notification that a file had arrived. */
     function handleFiles(fileList) {
-      if (!list || !fileList) return;
+      if (!fileList) return;
       Array.prototype.slice.call(fileList).forEach(function (file) {
         var reason = null;
         if (!accepts(file, acceptAttr)) reason = 'Tipe berkas tidak didukung.';
         else if (maxSize && file.size > maxSize) reason = 'Ukuran melebihi batas (' + fmtSize(maxSize) + ').';
         var row = makeRow(file);
-        list.appendChild(row.el);
+        if (list) list.appendChild(row.el);
         if (reason) {
           row.fail(reason);
-        } else {
+        } else if (simulate) {
+          /* The kit is driving (demo path): keep showing a transfer, because there is one. */
           row.uploading();
-          if (simulate) simulateUpload(row);
+          simulateUpload(row);
+        } else {
+          /* The CONSUMER owns the transfer. Rest until it says otherwise by calling row.uploading():
+             a file that has only been chosen must not claim to be uploading. A progress bar that
+             never moves reads as a hung upload, and gets reported as a bug against a transfer that
+             was never started. */
+          row.ready();
         }
         zone.dispatchEvent(new CustomEvent('fdy-upload-add', {
           bubbles: true, detail: { file: file, rejected: !!reason, reason: reason, row: row }
@@ -3714,7 +3789,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-dropzone]'), initDropzone);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-dropzone]')) initDropzone(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-dropzone]'), initDropzone);
   }
 
   if (document.readyState === 'loading') {

package/docs/getting-started.md

@@ -184,7 +184,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.22.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.24.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`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs",
+    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit"

package/src/components/avatar.css

@@ -1,6 +1,11 @@
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}

package/src/components/stepper.css

@@ -7,7 +7,12 @@
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}