@cahyo-dimas/freeday 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -3,6 +3,76 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.26.0] — 2026-08-14
+Improvement note #43, found while chasing a "the upload is stuck" report on a 626 KB PDF: the
+transfer took about a second, the server then spent nearly a minute reading the document.
+### Added
+- **`row.waiting(label)`** — the state between `setProgress` and `done`: the bytes are gone, the
+  server has not answered. The row's only long-running state was named after the *transfer*, so it
+  kept saying "Mengunggah…" for the whole minute of server-side work — and `setProgress(100)` made it
+  worse, because a full bar that then sits still is the most convincing "hung" signal a UI can
+  produce. There was no way out within the row's API: `done()` claims success, `fail()` claims an
+  error, `ready()` walks backwards. Consumers were rendering a second status line outside the row and
+  leaving the row to contradict it.
+  The bar goes **indeterminate** and drops `aria-valuenow` — a progressbar with no value is exactly
+  what ARIA calls indeterminate, which is the contract `COMPONENTS.md` already stated for
+  `.fdy-progress`. The label is the consumer's, because only they know what the server is doing
+  (`Membaca PDF…`, `Memindai…`); it falls back to `Menunggu server…`.
+- `COMPONENTS.md` gains the state in the row table plus the sentence that would have saved the
+  round-trip: **if your request outlives the transfer, drive `waiting()`**.
+### Notes on the shape of the fix
+- The report's patch would have shipped the symptom it set out to remove. It put the modifier on the
+  **bar** (`.fdy-progress--indeterminate` styles `.fdy-progress__bar`, so it belongs on the
+  container — on the bar it matches nothing) and then set an inline `width:100%`, which beats the
+  modifier's own width anyway. Both mistakes render a full, frozen bar. The note also hedged that
+  `.fdy-progress--indeterminate` might not exist; it has all along.
+- **Leaving the state needs more care than entering it.** `.fdy-progress__bar` is a plain block div:
+  with no width it fills its track. So `uploading()`/`setProgress()` restore an explicit width when
+  they clear the modifier, or a retried row paints a *full* bar while meaning 0%. `done()`, `fail()`
+  and `ready()` need no counterpart — they drop the progress element outright, modifier and all
+  (contrary to the note, which expected a line in each).
+- **No `.fdy-file--waiting` class.** `uploading` has none either; only `--success`/`--error` do,
+  because they carry colour. A documented class with no rule is markup that looks like it does
+  something.
+- Under `prefers-reduced-motion: reduce` the kit's indeterminate treatment is a dimmed **full** bar
+  (no animation left to carry the meaning) — pre-existing behaviour for every indeterminate progress,
+  not introduced here. For those users the honest signal is the label, not the bar.
+### Added — guards
+- `browser/upload-states.mjs` gains a third spec, measuring what the **engine renders** rather than
+  what the source declares: both ways to get this wrong are invisible in a code read. Mutation-checked
+  against five defects, including the report's own two — modifier-on-bar, inline `width:100%`, no
+  width restored on return, `aria-valuenow` kept, and label ignored.
+
+## [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.

package/COMPONENTS.md

@@ -482,6 +482,10 @@ Click/Enter opens the file dialog; drop works too. Needs `freeday-upload.js`.
   — the kit fakes a transfer to `done()`; never set it in an app)
 - A11y: the dropzone is `role="button" tabindex="0"` + `aria-label`.
 
+**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.
@@ -491,11 +495,17 @@ transfer started; the kit never claims one it is not performing.
 | *(initial)* | **rest** — chosen, not sent. Size only, no progress bar. |
 | `.uploading()` | in flight — adds the progress bar |
 | `.setProgress(pct)` | moves the bar (0–100) |
+| `.waiting(label)` | **sent, waiting on the server** — indeterminate bar, no `aria-valuenow`; `label` is yours (default *Menunggu server…*) |
 | `.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 |
 
+**If your request outlives the transfer, drive `waiting()`.** Server-side work after the last byte —
+OCR, extraction, virus scanning, transcoding — is not uploading, and `setProgress(100)` left standing
+is read as a hang. `waiting()` is the state for it: the label says what the server is doing, and the
+bar stops claiming a percentage it no longer has.
+
 ```js
 zone.addEventListener('fdy-upload-add', (e) => {
   if (e.detail.rejected) return;              // the kit already rendered the reason
@@ -503,9 +513,12 @@ zone.addEventListener('fdy-upload-add', (e) => {
   submitBtn.onclick = async () => {
     row.uploading();
     await send(file, (pct) => row.setProgress(pct));
+    row.waiting('Membaca dokumen…');            // bytes gone, server still working
+    await serverFinished();
     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`

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.24.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.24.0)
+[![Release](https://img.shields.io/badge/release-v1.26.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.26.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.24.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.24.0)
+[![Release](https://img.shields.io/badge/release-v1.26.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.26.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) /
+ *   .waiting(label) (sent, awaiting the server) / .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);
@@ -93,6 +107,13 @@
     function dropProgress() {
       if (progressWrap) { progressWrap.remove(); progressWrap = null; bar = null; progressEl = null; }
     }
+    /* Back to a measured bar. While the indeterminate modifier is on it owns the bar's width, so an
+       explicit one has to be restored when it comes off: .fdy-progress__bar is a plain block div, and
+       with no width at all it fills the track — a full bar, which is the opposite of what 0% means. */
+    function determinate() {
+      progressEl.classList.remove('fdy-progress--indeterminate');
+      if (!bar.style.width) bar.style.width = '0%';
+    }
     return {
       el: el,
       /* The state a row starts in: chosen, not yet sent. The size alone — it makes no claim about
@@ -110,13 +131,34 @@
         icon.innerHTML = FILE_ICON;
         sub.textContent = fmtSize(file.size) + ' · Mengunggah…';
         ensureProgress();
+        determinate();
       },
       setProgress: function (pct) {
         ensureProgress();
+        determinate();
         var v = Math.max(0, Math.min(100, pct));
         bar.style.width = v + '%';
         progressEl.setAttribute('aria-valuenow', String(Math.round(v)));
       },
+      /* The bytes are gone and the server has not answered yet — extraction, scanning, transcoding.
+         "Mengunggah…" turns false the moment the last byte leaves, and a determinate bar parked at
+         100% is the most convincing "hung" signal a UI can produce, so this state reports no
+         percentage: the bar goes indeterminate and the label belongs to the consumer, because only
+         they know what the server is doing ("Membaca PDF…", "Memindai…"). done()/fail()/ready() need
+         no counterpart here — they drop the progress element outright, modifier and all. */
+      waiting: function (label) {
+        el.classList.remove('fdy-file--error', 'fdy-file--success');
+        icon.innerHTML = FILE_ICON;
+        sub.textContent = fmtSize(file.size) + ' · ' + (label || 'Menunggu server…');
+        ensureProgress();
+        progressEl.classList.add('fdy-progress--indeterminate');
+        /* The modifier styles .fdy-progress__bar, so it must sit on the CONTAINER, and the inline
+           width setProgress wrote has to go — an inline style beats any rule the modifier brings.
+           aria-valuenow goes with it: a progressbar with no value is precisely what ARIA calls
+           indeterminate, which is the contract COMPONENTS.md already states for this component. */
+        bar.style.width = '';
+        progressEl.removeAttribute('aria-valuenow');
+      },
       done: function () {
         el.classList.add('fdy-file--success');
         el.classList.remove('fdy-file--error');
@@ -191,7 +233,7 @@
         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);
+        var row = makeRow(file, zone);
         if (list) list.appendChild(row.el);
         if (reason) {
           row.fail(reason);

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) /
+ *   .waiting(label) (sent, awaiting the server) / .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);
@@ -3668,6 +3682,13 @@
     function dropProgress() {
       if (progressWrap) { progressWrap.remove(); progressWrap = null; bar = null; progressEl = null; }
     }
+    /* Back to a measured bar. While the indeterminate modifier is on it owns the bar's width, so an
+       explicit one has to be restored when it comes off: .fdy-progress__bar is a plain block div, and
+       with no width at all it fills the track — a full bar, which is the opposite of what 0% means. */
+    function determinate() {
+      progressEl.classList.remove('fdy-progress--indeterminate');
+      if (!bar.style.width) bar.style.width = '0%';
+    }
     return {
       el: el,
       /* The state a row starts in: chosen, not yet sent. The size alone — it makes no claim about
@@ -3685,13 +3706,34 @@
         icon.innerHTML = FILE_ICON;
         sub.textContent = fmtSize(file.size) + ' · Mengunggah…';
         ensureProgress();
+        determinate();
       },
       setProgress: function (pct) {
         ensureProgress();
+        determinate();
         var v = Math.max(0, Math.min(100, pct));
         bar.style.width = v + '%';
         progressEl.setAttribute('aria-valuenow', String(Math.round(v)));
       },
+      /* The bytes are gone and the server has not answered yet — extraction, scanning, transcoding.
+         "Mengunggah…" turns false the moment the last byte leaves, and a determinate bar parked at
+         100% is the most convincing "hung" signal a UI can produce, so this state reports no
+         percentage: the bar goes indeterminate and the label belongs to the consumer, because only
+         they know what the server is doing ("Membaca PDF…", "Memindai…"). done()/fail()/ready() need
+         no counterpart here — they drop the progress element outright, modifier and all. */
+      waiting: function (label) {
+        el.classList.remove('fdy-file--error', 'fdy-file--success');
+        icon.innerHTML = FILE_ICON;
+        sub.textContent = fmtSize(file.size) + ' · ' + (label || 'Menunggu server…');
+        ensureProgress();
+        progressEl.classList.add('fdy-progress--indeterminate');
+        /* The modifier styles .fdy-progress__bar, so it must sit on the CONTAINER, and the inline
+           width setProgress wrote has to go — an inline style beats any rule the modifier brings.
+           aria-valuenow goes with it: a progressbar with no value is precisely what ARIA calls
+           indeterminate, which is the contract COMPONENTS.md already states for this component. */
+        bar.style.width = '';
+        progressEl.removeAttribute('aria-valuenow');
+      },
       done: function () {
         el.classList.add('fdy-file--success');
         el.classList.remove('fdy-file--error');
@@ -3766,7 +3808,7 @@
         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);
+        var row = makeRow(file, zone);
         if (list) list.appendChild(row.el);
         if (reason) {
           row.fail(reason);

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.24.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.26.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.24.0",
+  "version": "1.26.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",