@cahyo-dimas/freeday 1.23.0 → 1.25.0

package/CHANGELOG.md

@@ -3,6 +3,79 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.25.0] — 2026-08-13
+Improvement note #42, found while adopting 1.24.0 — the other half of the same integration.
+### Fixed
+- **`fdy-upload-remove` now fires on the dropzone**, the same element as `fdy-upload-add`. It was
+  dispatched on the *row*, which lives in the file list — and the kit's own markup contract puts that
+  list as a **sibling** of the dropzone, so the event never bubbled through the zone. A consumer
+  following the documentation got `add` and never got `remove`: no error, right event name, right
+  element, and the other event on that element working. Their state kept a file the user had already
+  taken away.
+  The kit's own header comment was the source of the mistake — it said both events are emitted "on the
+  dropzone" while the code dispatched one of them somewhere else. It now states the target for each,
+  and why (a row in a sibling list can never reach the zone). `COMPONENTS.md` says it once beside the
+  row state table, with the removal listener in the worked example.
+### Notes on the shape of the fix
+- The report proposed dispatching on **both** the row and the zone, for backward compatibility. Not
+  taken, and the guard proves why: when the file list is **nested inside** the dropzone — which
+  `data-filelist` permits — the row already bubbles through the zone, so a second dispatch makes a
+  plain zone listener fire **twice** per removal. Firing on both also leaves the pair asymmetric (one
+  `add`, two `remove`s for anyone delegating on a common ancestor), which is the same class of silent
+  bug this note is about. One canonical target is the honest fix.
+- Dispatching on the zone also fixes the **listless** case from 1.24.0: a row that was never attached
+  to the document bubbles to nothing at all, so its × was previously unobservable.
+- *Migration:* a consumer that worked around the old behaviour by listening on the file list must
+  move that listener to the dropzone. That position was never documented — it was the bug.
+### Added — guards
+- `browser/upload-states.mjs` gains a second spec: removal fires on the dropzone **exactly once**, in
+  both layouts (list as sibling, list nested inside the zone), and delegation on a shared ancestor
+  sees no duplicates. Mutation-checked against *both* rejected designs — reverting to the row target
+  fails it, and so does the report's dispatch-on-both.
+
+## [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

package/COMPONENTS.md

@@ -478,9 +478,46 @@ 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.
+
+**Both events fire on the dropzone** — `fdy-upload-add` *and* `fdy-upload-remove`. One listener, one
+element. (The file list may be anywhere in the document; nothing is dispatched on the row, because a
+row in a sibling list would never bubble through the zone.)
+
+**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();
+  };
+});
+zone.addEventListener('fdy-upload-remove', (e) => forget(e.detail.file));   // same element
+```
+
+**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` +

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.23.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.23.0)
+[![Release](https://img.shields.io/badge/release-v1.25.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.25.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.23.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.23.0)
+[![Release](https://img.shields.io/badge/release-v1.25.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.25.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/dist/freeday-upload.js

@@ -15,8 +15,15 @@
  *  </div>
  *  <div class="fdy-filelist" id="dz-list"></div>
  *
- * Emits bubbling CustomEvents on the dropzone: "fdy-upload-add" {file, rejected, reason, row}
- * (row exposes .uploading()/.setProgress(pct)/.done()/.fail(msg)) and "fdy-upload-remove" {file}.
+ * Emits bubbling CustomEvents — BOTH on the dropzone element, which is the one target a consumer
+ * needs to listen on:
+ *   "fdy-upload-add"    {file, rejected, reason, row}
+ *   "fdy-upload-remove" {file}
+ * `row` is the state machine over the rendered .fdy-file:
+ *   .ready() (rest — where a dropped file starts) / .uploading() / .setProgress(pct) / .done() /
+ *   .fail(msg) / .el
+ * Note the file list is a SIBLING of the dropzone above, so nothing dispatched on a row would ever
+ * bubble through the zone — which is why removal fires on the zone and not on the row.
  */
 (function () {
   'use strict';
@@ -43,7 +50,7 @@
     });
   }
 
-  function makeRow(file) {
+  function makeRow(file, zone) {
     var el = document.createElement('div');
     el.className = 'fdy-file';
     var icon = document.createElement('span');
@@ -65,7 +72,14 @@
     remove.setAttribute('aria-label', 'Hapus ' + file.name);
     remove.innerHTML = '&times;';
     remove.addEventListener('click', function () {
-      el.dispatchEvent(new CustomEvent('fdy-upload-remove', { bubbles: true, detail: { file: file } }));
+      /* Dispatched on the ZONE, not on the row — the same target as fdy-upload-add, so one listener
+         on the dropzone gets both. The row lives in the file list, which the kit's own markup
+         contract puts as a SIBLING of the dropzone, so a row event never bubbles through the zone:
+         a consumer following the docs saw `add` arrive and `remove` never fire, with no error.
+         Firing on both would look safer, but it makes the pair asymmetric — one `add` and, for
+         anyone delegating on a common ancestor, two `remove`s — which is its own silent bug. It
+         also fixes the listless case: a row that was never attached bubbles to nothing at all. */
+      zone.dispatchEvent(new CustomEvent('fdy-upload-remove', { bubbles: true, detail: { file: file } }));
       el.remove();
     });
     el.appendChild(icon);
@@ -95,6 +109,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 +195,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);
+        var row = makeRow(file, zone);
+        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 }

package/dist/freeday.js

@@ -3590,8 +3590,15 @@
  *  </div>
  *  <div class="fdy-filelist" id="dz-list"></div>
  *
- * Emits bubbling CustomEvents on the dropzone: "fdy-upload-add" {file, rejected, reason, row}
- * (row exposes .uploading()/.setProgress(pct)/.done()/.fail(msg)) and "fdy-upload-remove" {file}.
+ * Emits bubbling CustomEvents — BOTH on the dropzone element, which is the one target a consumer
+ * needs to listen on:
+ *   "fdy-upload-add"    {file, rejected, reason, row}
+ *   "fdy-upload-remove" {file}
+ * `row` is the state machine over the rendered .fdy-file:
+ *   .ready() (rest — where a dropped file starts) / .uploading() / .setProgress(pct) / .done() /
+ *   .fail(msg) / .el
+ * Note the file list is a SIBLING of the dropzone above, so nothing dispatched on a row would ever
+ * bubble through the zone — which is why removal fires on the zone and not on the row.
  */
 (function () {
   'use strict';
@@ -3618,7 +3625,7 @@
     });
   }
 
-  function makeRow(file) {
+  function makeRow(file, zone) {
     var el = document.createElement('div');
     el.className = 'fdy-file';
     var icon = document.createElement('span');
@@ -3640,7 +3647,14 @@
     remove.setAttribute('aria-label', 'Hapus ' + file.name);
     remove.innerHTML = '&times;';
     remove.addEventListener('click', function () {
-      el.dispatchEvent(new CustomEvent('fdy-upload-remove', { bubbles: true, detail: { file: file } }));
+      /* Dispatched on the ZONE, not on the row — the same target as fdy-upload-add, so one listener
+         on the dropzone gets both. The row lives in the file list, which the kit's own markup
+         contract puts as a SIBLING of the dropzone, so a row event never bubbles through the zone:
+         a consumer following the docs saw `add` arrive and `remove` never fire, with no error.
+         Firing on both would look safer, but it makes the pair asymmetric — one `add` and, for
+         anyone delegating on a common ancestor, two `remove`s — which is its own silent bug. It
+         also fixes the listless case: a row that was never attached bubbles to nothing at all. */
+      zone.dispatchEvent(new CustomEvent('fdy-upload-remove', { bubbles: true, detail: { file: file } }));
       el.remove();
     });
     el.appendChild(icon);
@@ -3670,6 +3684,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;
@@ -3746,19 +3770,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);
+        var row = makeRow(file, zone);
+        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 }

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.23.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.25.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.23.0",
+  "version": "1.25.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 browser/root-init.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"