@cahyo-dimas/freeday 1.23.0 → 1.24.0

package/CHANGELOG.md

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

package/COMPONENTS.md

@@ -478,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` +

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.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.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.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/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 }

package/dist/freeday.js

@@ -3670,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;
@@ -3746,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 }

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.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.23.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 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"