@cahyo-dimas/freeday 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 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

package/COMPONENTS.md

@@ -495,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
@@ -507,6 +513,8 @@ 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();
   };
 });

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.25.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.25.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.25.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.25.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

@@ -20,8 +20,8 @@
  *   "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
+ *   .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.
  */
@@ -107,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
@@ -124,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');

package/dist/freeday.js

@@ -3595,8 +3595,8 @@
  *   "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
+ *   .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.
  */
@@ -3682,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
@@ -3699,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');

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.25.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.25.0",
+  "version": "1.26.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",