@cahyo-dimas/freeday 1.25.0 → 1.27.0

package/CHANGELOG.md

@@ -3,6 +3,99 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.27.0] — 2026-08-14
+Improvement note #44, found while building a settings screen whose only numeric field looked like it
+belonged to a different application.
+### Fixed
+- **`.fdy-input[type="number"]` no longer shows the user agent's spin buttons.** They are OS widgets
+  in OS colours that no theme reaches, so on a dark surface they read as a light-grey artefact glued
+  to an otherwise themed field — the one unthemed control on a page where everything else is themed
+  to the last pixel. Both halves ship, because they cover different engines: `appearance: textfield`
+  (Firefox) and `::-webkit-outer/inner-spin-button { appearance: none }` (Blink/WebKit).
+### Added
+- **`[data-fdy-number]` + `freeday-number.js`** — the increment affordance back on the kit's terms,
+  since hiding the native buttons removes it. **Not a new block:** it is an `.fdy-input-group` with
+  two `__btn`s, so it inherits the shared border, `:focus-within` ring and `:has()` error promotion
+  that already existed. The reported `.fdy-number` block would have duplicated all of it.
+  - **No custom event.** Stepping dispatches native bubbling `input` + `change` on the input, so
+    `v-model` / `onChange` / `@bind` work with no adapter and no new API — the input stays the source
+    of truth. That is also why this needs no typed wrapper in any of the four stacks.
+  - `min`/`max`/`step` live on the input and the buttons never redo the arithmetic (`stepUp()`/
+    `stepDown()` clamp for free). They go `disabled` at a bound, on a `disabled`/`readonly` field,
+    and when `step="any"` — which has no defined increment and makes `stepUp()` throw, so a stepper
+    cannot honestly express it.
+  - A `MutationObserver` watches `disabled`/`readonly`/`min`/`max`/`step`: a framework changes those
+    without firing an event, and a button that still looks enabled while doing nothing is the exact
+    lie this state machine exists to prevent. (First observer in the kit — the alternative was a
+    button whose appearance silently drifts from its behaviour.)
+  - The buttons are **not tab stops** (`tabindex="-1"`): the input is already focusable and ↑/↓
+    already step it, so two extra stops per field cost every keyboard user and buy nothing. They keep
+    an `aria-label`, and `type="button"` so they cannot submit their form.
+- `.fdy-input-group__btn` gains a **leading-position** rule (divider on the correct side when the
+  button comes first) and a **`:disabled`** state — dim + `not-allowed`, with `:hover` withdrawn,
+  because a disabled button still matches `:hover`.
+- `COMPONENTS.md` now answers **which `type` `.fdy-input` covers**, which is the question that would
+  have prevented this note: every text-like type themes identically, and the two that keep a native
+  widget are named with what to do about each.
+### Notes on the shape of the fix
+- **`type="search"` deliberately left alone.** Its WebKit clear (×) button is unthemed too — and it
+  is on the kit's own docs pages, 10 of them — but it is the only way to empty the field. Stripping
+  it removes function, not chrome; the number arrows only removed a mouse-only increment that ↑/↓
+  still provides. `type="date"`/`time` likewise keep their picker indicator; the kit ships its own
+  datepicker/timepicker and the docs now say to use those instead.
+- **Why this was never caught:** `type="number"` appears **zero** times across `docs/index.html`,
+  `docs/reference-screen.html` and `examples/` (against `search` ×10, `text` ×12, `date` ×4). The kit
+  never used the input it shipped. The docs page now carries a real number field, in the input-group
+  section where it belongs.
+### Added — guards
+- `test/css.test.mjs` asserts both engine halves survive (each is invisible in review and each brings
+  the artefact back on one engine only), and states in-file why `search`/`date` are excluded.
+- `browser/number.mjs` drives real clicks and a real Tab: stepping fires native `input` + `change`,
+  bounds disable the right button, a disabled button changes nothing, `readonly` and `step="any"`
+  are inert without throwing, and Tab skips the buttons. Mutation-checked against five defects.
+- `browser/harness.mjs` gains `pressKey` — tab order only moves for a trusted key, so the claim is
+  measured rather than read off an attribute.
+
+## [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

@@ -91,6 +91,7 @@ element is fine. Events are bubbling
 | `data-fdy-tree` | `freeday-tree.js` | `FreedayTree` | — |
 | `data-fdy-rating` | `freeday-rating.js` | `FreedayRating` | — (native `change`) |
 | `data-fdy-slider` | `freeday-slider.js` | `FreedaySlider` | — (native `input`) |
+| `data-fdy-number` | `freeday-number.js` | `FreedayNumber` | — (native `input`, `change`) |
 | `data-fdy-drawer="id"` | `freeday-drawer.js` | `FreedayDrawer` | — |
 | `data-fdy-chart="type"` | `freeday-chart.js` | `FreedayChart` | — (`.update(el)` to repaint) |
 | — (imperative) | `freeday-toast.js` | `Freeday.toast()` / `Freeday.dismiss()` | — |
@@ -307,6 +308,17 @@ native control, otherwise a `<div>` + explicitly associated label.
 </label>
 ```
 
+**Which `type` does `.fdy-input` cover?** Every text-like type — `text` `email` `password` `tel`
+`url` `search` `number` — themes identically. Two carry a native widget the kit does *not* override:
+
+| Type | What the UA still draws | What to do |
+|---|---|---|
+| `search` | WebKit's clear (×) button, in OS colours | **Left alone on purpose** — it is the only way to empty the field. Want it themed? Drop the type back to `text` and add a `.fdy-input-group__btn` that clears. |
+| `date` `time` `datetime-local` | the picker indicator glyph, and the whole native picker | Use `.fdy-datepicker` / `.fdy-timepicker` / `.fdy-datetimepicker` instead — the kit ships its own. |
+
+`number` used to be a third: the UA spin buttons are unthemeable, so `.fdy-input[type="number"]`
+now hides them and `[data-fdy-number]` below gives the affordance back.
+
 ## Input group — `.fdy-input-group`
 Prefix/suffix addons around an input: text (`Rp`, `%`), a decorative icon
 (`__addon--icon`), or an action button (`__btn`).
@@ -320,6 +332,31 @@ Prefix/suffix addons around an input: text (`Rp`, `%`), a decorative icon
 </div>
 ```
 
+## Number field — `[data-fdy-number]`
+A number input with its increment/decrement affordance back, after `.fdy-input` removed the
+browser's own. **Not a new block** — it is an `.fdy-input-group` with two `__btn`s, so it inherits
+the shared border, focus ring and error promotion. Needs `freeday-number.js`.
+
+```html
+<div class="fdy-input-group" data-fdy-number>
+  <button type="button" class="fdy-input-group__btn" data-fdy-number-step="-1"
+          tabindex="-1" aria-label="Kurangi">−</button>
+  <input class="fdy-input" type="number" min="0" max="10" step="1" value="1" aria-label="Konfirmasi">
+  <button type="button" class="fdy-input-group__btn" data-fdy-number-step="1"
+          tabindex="-1" aria-label="Tambah">+</button>
+</div>
+```
+
+- **No custom event.** Stepping fires native bubbling `input` + `change` on the input, so `v-model`,
+  `onChange` and `@bind` work with no adapter — the input stays the source of truth.
+- `min` / `max` / `step` live on the **input**; the buttons never do the arithmetic themselves
+  (`stepUp()`/`stepDown()` clamp for free) and go `disabled` at a bound, on a `disabled`/`readonly`
+  field, and when `step="any"` (a stepper cannot express "no defined increment").
+- The buttons are **not tab stops** (`tabindex="-1"`): the input is already focusable and ↑/↓
+  already step it, so extra stops would cost every keyboard user and buy nothing. Keep the
+  `aria-label` — pointer and browse-mode users still get a named control.
+- `type="button"` is required. Inside a `<form>`, a bare `<button>` submits it.
+
 ## Checkbox · radio · switch
 Native inputs, styled. `.fdy-check` · `.fdy-radio` · `.fdy-switch` on the wrapping `<label>`;
 `.fdy-checkbox` on a bare `<input type="checkbox">` used inside tables/trees.
@@ -495,11 +532,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 +550,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.27.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.27.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`.
@@ -130,6 +130,7 @@ Semua auto-init `[data-fdy-*]` saat `DOMContentLoaded` — idempotent, progressi
 | `freeday-datetime` | `[data-fdy-datetimepicker]` | `fdy-datetime-change` `{date,time,value}` · `window.FreedayDatetime` |
 | `freeday-cascade` | `[data-fdy-cascade]` (model `<ul>` bersarang) | `fdy-cascade-change` `{value,path,labels}` · `window.FreedayCascade` |
 | `freeday-mask` | `[data-fdy-mask]`, `[data-fdy-password]` | `fdy-mask` `{value,raw}` · `window.FreedayMask` |
+| `freeday-number` | `[data-fdy-number]` | — (native `input`/`change`) · `window.FreedayNumber` |
 | `freeday-form` | `[data-fdy-validate]` (form) | `fdy-form-invalid`/`-valid` · `window.FreedayForm` |
 | `freeday-chip` | `[data-fdy-chips]`, `.fdy-chip__remove` | `fdy-chip-change`/`fdy-chip-remove` · `window.FreedayChip` |
 | `freeday-upload` | `[data-fdy-dropzone]` | `fdy-upload-add`/`-remove` · `window.FreedayUpload` |

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.27.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.27.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`.
@@ -129,6 +129,7 @@ Each one auto-inits `[data-fdy-*]` on `DOMContentLoaded` — idempotent, progres
 | `freeday-datetime` | `[data-fdy-datetimepicker]` | `fdy-datetime-change` `{date,time,value}` · `window.FreedayDatetime` |
 | `freeday-cascade` | `[data-fdy-cascade]` (nested `<ul>` model) | `fdy-cascade-change` `{value,path,labels}` · `window.FreedayCascade` |
 | `freeday-mask` | `[data-fdy-mask]`, `[data-fdy-password]` | `fdy-mask` `{value,raw}` · `window.FreedayMask` |
+| `freeday-number` | `[data-fdy-number]` | — (native `input`/`change`) · `window.FreedayNumber` |
 | `freeday-form` | `[data-fdy-validate]` (form) | `fdy-form-invalid`/`-valid` · `window.FreedayForm` |
 | `freeday-chip` | `[data-fdy-chips]`, `.fdy-chip__remove` | `fdy-chip-change`/`fdy-chip-remove` · `window.FreedayChip` |
 | `freeday-upload` | `[data-fdy-dropzone]` | `fdy-upload-add`/`-remove` · `window.FreedayUpload` |

package/dist/freeday-number.js

@@ -0,0 +1,104 @@
+/* Freeday — number field enhancer (optional, zero-dependency).
+ * Gives a native <input type="number"> its increment/decrement affordance back, on the kit's terms:
+ * .fdy-input hides the user agent's own spin buttons (unthemeable OS widgets), so this puts two real
+ * buttons in an .fdy-input-group instead. No new block — the group already owns the shared border,
+ * :focus-within ring and error promotion.
+ *
+ * Markup contract:
+ *  <div class="fdy-input-group" data-fdy-number>
+ *    <button type="button" class="fdy-input-group__btn" data-fdy-number-step="-1"
+ *            tabindex="-1" aria-label="Kurangi">−</button>
+ *    <input class="fdy-input" type="number" min="0" max="10" step="1" value="1" aria-label="…">
+ *    <button type="button" class="fdy-input-group__btn" data-fdy-number-step="1"
+ *            tabindex="-1" aria-label="Tambah">+</button>
+ *  </div>
+ *
+ * No custom event: the input is the source of truth, so stepping dispatches native bubbling `input`
+ * and `change`. v-model / onChange / @bind bind to the input directly, exactly as they would without
+ * this enhancer.
+ *
+ * The buttons are deliberately OUT of the tab order (tabindex="-1"): the input is already focusable
+ * and ArrowUp/ArrowDown already step it, so two extra tab stops per field would cost every keyboard
+ * user something and buy nothing. They keep an aria-label, so pointer and browse-mode users still
+ * get a named control.
+ */
+(function () {
+  'use strict';
+
+  function initNumber(root) {
+    if (root.dataset.fdyNumberReady === '1') return;
+
+    var input = root.querySelector('input[type="number"]');
+    var buttons = Array.prototype.slice.call(root.querySelectorAll('[data-fdy-number-step]'));
+    if (!input || !buttons.length) return;
+    root.dataset.fdyNumberReady = '1';
+
+    /* step="any" means there is no defined increment, and stepUp()/stepDown() throw InvalidStateError
+       on such a field. A stepper cannot express it, so the buttons stay visibly disabled rather than
+       failing on click. Read live, not captured: `step` is one of the attributes watched below. */
+    function stepless() {
+      return (input.getAttribute('step') || '').toLowerCase() === 'any';
+    }
+
+    function frozen() {
+      return stepless() || input.disabled || input.readOnly;
+    }
+
+    /* Bounds are read from the input, never recomputed: stepUp()/stepDown() already clamp to
+       min/max/step, so these two only decide whether the button tells the truth about what it does. */
+    function atLimit(direction) {
+      var bound = direction > 0 ? input.max : input.min;
+      if (bound === '' || input.value === '') return false;
+      var value = Number(input.value);
+      var limit = Number(bound);
+      if (isNaN(value) || isNaN(limit)) return false;
+      return direction > 0 ? value >= limit : value <= limit;
+    }
+
+    function sync() {
+      buttons.forEach(function (btn) {
+        var direction = Number(btn.getAttribute('data-fdy-number-step')) < 0 ? -1 : 1;
+        btn.disabled = frozen() || atLimit(direction);
+      });
+    }
+
+    buttons.forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        if (frozen()) return;
+        if (Number(btn.getAttribute('data-fdy-number-step')) < 0) input.stepDown();
+        else input.stepUp();
+        /* The value changed without the user typing, so say so the way the platform does — frameworks
+           listen to these, not to a kit-specific event. */
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        sync();
+      });
+    });
+
+    input.addEventListener('input', sync);
+    input.addEventListener('change', sync);
+    /* Typing is not the only thing that moves a bound: a framework flips `disabled` or recomputes
+       `max` without any event firing, and a button that still looks enabled but no longer does
+       anything is the lie this state machine exists to avoid. */
+    new MutationObserver(sync).observe(input, {
+      attributes: true,
+      attributeFilter: ['disabled', 'readonly', 'min', 'max', 'step'],
+    });
+    sync();
+  }
+
+  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-number]')) initNumber(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-number]'), initNumber);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { initAll(); });
+  } else {
+    initAll();
+  }
+
+  window.FreedayNumber = { init: initNumber, initAll: initAll };
+})();

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.bundle.css

@@ -1230,6 +1230,12 @@ a { color: var(--color-primary); }
 .fdy-input-group__btn:hover{background:var(--color-surface-3);color:var(--color-text);}
 .fdy-input-group__btn:focus-visible{outline:none;color:var(--color-text);box-shadow:inset 0 0 0 2px var(--color-primary);}
 .fdy-input-group__btn svg{display:block;width:1.1rem;height:1.1rem;}
+/* Leading action button (the "−" of a number stepper): the divider belongs on the other side. */
+.fdy-input-group__btn:first-child{border-left:0;border-right:var(--bw) solid var(--color-border);}
+/* At a bound, or on a disabled/read-only field, the button must look as inert as it acts — same dim
+   + not-allowed as .fdy-input:disabled. :hover still matches a disabled button, so it is withdrawn. */
+.fdy-input-group__btn:disabled{opacity:.5;cursor:not-allowed;}
+.fdy-input-group__btn:disabled:hover{background:var(--color-surface-2);color:var(--color-text-muted);}
 /* Error state must win over the neutralizing rules above — promote to the wrapper. */
 .fdy-input-group:has(.fdy-input--error),.fdy-input-group:has(.fdy-combo--error),.fdy-input-group:has([aria-invalid="true"]){border-color:var(--color-danger);}
 .fdy-input-group:has(.fdy-input--error):focus-within,.fdy-input-group:has(.fdy-combo--error):focus-within,.fdy-input-group:has([aria-invalid="true"]):focus-within{border-color:var(--color-danger);box-shadow:inset 0 1px 2px rgba(16,14,30,.04),0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
@@ -1254,6 +1260,14 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[readonly],.fdy-textarea[readonly]{background:var(--color-surface-2);border-color:var(--color-border);color:var(--color-text);cursor:default;}
 .fdy-input[readonly]:hover,.fdy-textarea[readonly]:hover{border-color:var(--color-border);}
 .fdy-input[readonly]:focus-visible,.fdy-textarea[readonly]:focus-visible{border-color:var(--color-border-strong);box-shadow:none;}
+/* Numbers (#44): the user agent draws its own spin buttons inside the field, in OS widget colours no
+   theme reaches — on a dark surface they read as a light-grey artefact glued to a themed field, and
+   it is the only unthemed control on the page. Removed so .fdy-input looks the same whatever its
+   type. `appearance:textfield` is the Firefox half, the pseudo-element the Blink/WebKit half; both
+   are needed. This trades away the mouse-only increment — arrow keys on a focused number input still
+   work, and [data-fdy-number] gives the affordance back on the kit's terms. */
+.fdy-input[type="number"]{appearance:textfield;-webkit-appearance:textfield;}
+.fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}

package/dist/freeday.css

@@ -860,6 +860,12 @@ a { color: var(--color-primary); }
 .fdy-input-group__btn:hover{background:var(--color-surface-3);color:var(--color-text);}
 .fdy-input-group__btn:focus-visible{outline:none;color:var(--color-text);box-shadow:inset 0 0 0 2px var(--color-primary);}
 .fdy-input-group__btn svg{display:block;width:1.1rem;height:1.1rem;}
+/* Leading action button (the "−" of a number stepper): the divider belongs on the other side. */
+.fdy-input-group__btn:first-child{border-left:0;border-right:var(--bw) solid var(--color-border);}
+/* At a bound, or on a disabled/read-only field, the button must look as inert as it acts — same dim
+   + not-allowed as .fdy-input:disabled. :hover still matches a disabled button, so it is withdrawn. */
+.fdy-input-group__btn:disabled{opacity:.5;cursor:not-allowed;}
+.fdy-input-group__btn:disabled:hover{background:var(--color-surface-2);color:var(--color-text-muted);}
 /* Error state must win over the neutralizing rules above — promote to the wrapper. */
 .fdy-input-group:has(.fdy-input--error),.fdy-input-group:has(.fdy-combo--error),.fdy-input-group:has([aria-invalid="true"]){border-color:var(--color-danger);}
 .fdy-input-group:has(.fdy-input--error):focus-within,.fdy-input-group:has(.fdy-combo--error):focus-within,.fdy-input-group:has([aria-invalid="true"]):focus-within{border-color:var(--color-danger);box-shadow:inset 0 1px 2px rgba(16,14,30,.04),0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
@@ -884,6 +890,14 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[readonly],.fdy-textarea[readonly]{background:var(--color-surface-2);border-color:var(--color-border);color:var(--color-text);cursor:default;}
 .fdy-input[readonly]:hover,.fdy-textarea[readonly]:hover{border-color:var(--color-border);}
 .fdy-input[readonly]:focus-visible,.fdy-textarea[readonly]:focus-visible{border-color:var(--color-border-strong);box-shadow:none;}
+/* Numbers (#44): the user agent draws its own spin buttons inside the field, in OS widget colours no
+   theme reaches — on a dark surface they read as a light-grey artefact glued to a themed field, and
+   it is the only unthemed control on the page. Removed so .fdy-input looks the same whatever its
+   type. `appearance:textfield` is the Firefox half, the pseudo-element the Blink/WebKit half; both
+   are needed. This trades away the mouse-only increment — arrow keys on a focused number input still
+   work, and [data-fdy-number] gives the affordance back on the kit's terms. */
+.fdy-input[type="number"]{appearance:textfield;-webkit-appearance:textfield;}
+.fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}

package/dist/freeday.js

@@ -2166,6 +2166,111 @@
   window.FreedayMenu = { init: initMenu, initAll: initAll };
 })();
 
+/* Freeday — number field enhancer (optional, zero-dependency).
+ * Gives a native <input type="number"> its increment/decrement affordance back, on the kit's terms:
+ * .fdy-input hides the user agent's own spin buttons (unthemeable OS widgets), so this puts two real
+ * buttons in an .fdy-input-group instead. No new block — the group already owns the shared border,
+ * :focus-within ring and error promotion.
+ *
+ * Markup contract:
+ *  <div class="fdy-input-group" data-fdy-number>
+ *    <button type="button" class="fdy-input-group__btn" data-fdy-number-step="-1"
+ *            tabindex="-1" aria-label="Kurangi">−</button>
+ *    <input class="fdy-input" type="number" min="0" max="10" step="1" value="1" aria-label="…">
+ *    <button type="button" class="fdy-input-group__btn" data-fdy-number-step="1"
+ *            tabindex="-1" aria-label="Tambah">+</button>
+ *  </div>
+ *
+ * No custom event: the input is the source of truth, so stepping dispatches native bubbling `input`
+ * and `change`. v-model / onChange / @bind bind to the input directly, exactly as they would without
+ * this enhancer.
+ *
+ * The buttons are deliberately OUT of the tab order (tabindex="-1"): the input is already focusable
+ * and ArrowUp/ArrowDown already step it, so two extra tab stops per field would cost every keyboard
+ * user something and buy nothing. They keep an aria-label, so pointer and browse-mode users still
+ * get a named control.
+ */
+(function () {
+  'use strict';
+
+  function initNumber(root) {
+    if (root.dataset.fdyNumberReady === '1') return;
+
+    var input = root.querySelector('input[type="number"]');
+    var buttons = Array.prototype.slice.call(root.querySelectorAll('[data-fdy-number-step]'));
+    if (!input || !buttons.length) return;
+    root.dataset.fdyNumberReady = '1';
+
+    /* step="any" means there is no defined increment, and stepUp()/stepDown() throw InvalidStateError
+       on such a field. A stepper cannot express it, so the buttons stay visibly disabled rather than
+       failing on click. Read live, not captured: `step` is one of the attributes watched below. */
+    function stepless() {
+      return (input.getAttribute('step') || '').toLowerCase() === 'any';
+    }
+
+    function frozen() {
+      return stepless() || input.disabled || input.readOnly;
+    }
+
+    /* Bounds are read from the input, never recomputed: stepUp()/stepDown() already clamp to
+       min/max/step, so these two only decide whether the button tells the truth about what it does. */
+    function atLimit(direction) {
+      var bound = direction > 0 ? input.max : input.min;
+      if (bound === '' || input.value === '') return false;
+      var value = Number(input.value);
+      var limit = Number(bound);
+      if (isNaN(value) || isNaN(limit)) return false;
+      return direction > 0 ? value >= limit : value <= limit;
+    }
+
+    function sync() {
+      buttons.forEach(function (btn) {
+        var direction = Number(btn.getAttribute('data-fdy-number-step')) < 0 ? -1 : 1;
+        btn.disabled = frozen() || atLimit(direction);
+      });
+    }
+
+    buttons.forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        if (frozen()) return;
+        if (Number(btn.getAttribute('data-fdy-number-step')) < 0) input.stepDown();
+        else input.stepUp();
+        /* The value changed without the user typing, so say so the way the platform does — frameworks
+           listen to these, not to a kit-specific event. */
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        sync();
+      });
+    });
+
+    input.addEventListener('input', sync);
+    input.addEventListener('change', sync);
+    /* Typing is not the only thing that moves a bound: a framework flips `disabled` or recomputes
+       `max` without any event firing, and a button that still looks enabled but no longer does
+       anything is the lie this state machine exists to avoid. */
+    new MutationObserver(sync).observe(input, {
+      attributes: true,
+      attributeFilter: ['disabled', 'readonly', 'min', 'max', 'step'],
+    });
+    sync();
+  }
+
+  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-number]')) initNumber(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-number]'), initNumber);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { initAll(); });
+  } else {
+    initAll();
+  }
+
+  window.FreedayNumber = { init: initNumber, initAll: initAll };
+})();
+
 /* Freeday — popover positioning helper (optional, zero-dependency).
  * Lifts a dropdown panel into the top layer via the native Popover API so it escapes ANY
  * ancestor overflow clip (a .fdy-card with overflow:hidden, an app-shell main with
@@ -3595,8 +3700,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 +3787,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 +3811,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.27.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.27.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 browser/upload-states.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 browser/number.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/input-group.css

@@ -17,6 +17,12 @@
 .fdy-input-group__btn:hover{background:var(--color-surface-3);color:var(--color-text);}
 .fdy-input-group__btn:focus-visible{outline:none;color:var(--color-text);box-shadow:inset 0 0 0 2px var(--color-primary);}
 .fdy-input-group__btn svg{display:block;width:1.1rem;height:1.1rem;}
+/* Leading action button (the "−" of a number stepper): the divider belongs on the other side. */
+.fdy-input-group__btn:first-child{border-left:0;border-right:var(--bw) solid var(--color-border);}
+/* At a bound, or on a disabled/read-only field, the button must look as inert as it acts — same dim
+   + not-allowed as .fdy-input:disabled. :hover still matches a disabled button, so it is withdrawn. */
+.fdy-input-group__btn:disabled{opacity:.5;cursor:not-allowed;}
+.fdy-input-group__btn:disabled:hover{background:var(--color-surface-2);color:var(--color-text-muted);}
 /* Error state must win over the neutralizing rules above — promote to the wrapper. */
 .fdy-input-group:has(.fdy-input--error),.fdy-input-group:has(.fdy-combo--error),.fdy-input-group:has([aria-invalid="true"]){border-color:var(--color-danger);}
 .fdy-input-group:has(.fdy-input--error):focus-within,.fdy-input-group:has(.fdy-combo--error):focus-within,.fdy-input-group:has([aria-invalid="true"]):focus-within{border-color:var(--color-danger);box-shadow:inset 0 1px 2px rgba(16,14,30,.04),0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}

package/src/components/input.css

@@ -18,6 +18,14 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-input[readonly],.fdy-textarea[readonly]{background:var(--color-surface-2);border-color:var(--color-border);color:var(--color-text);cursor:default;}
 .fdy-input[readonly]:hover,.fdy-textarea[readonly]:hover{border-color:var(--color-border);}
 .fdy-input[readonly]:focus-visible,.fdy-textarea[readonly]:focus-visible{border-color:var(--color-border-strong);box-shadow:none;}
+/* Numbers (#44): the user agent draws its own spin buttons inside the field, in OS widget colours no
+   theme reaches — on a dark surface they read as a light-grey artefact glued to a themed field, and
+   it is the only unthemed control on the page. Removed so .fdy-input looks the same whatever its
+   type. `appearance:textfield` is the Firefox half, the pseudo-element the Blink/WebKit half; both
+   are needed. This trades away the mouse-only increment — arrow keys on a focused number input still
+   work, and [data-fdy-number] gives the affordance back on the kit's terms. */
+.fdy-input[type="number"]{appearance:textfield;-webkit-appearance:textfield;}
+.fdy-input[type="number"]::-webkit-outer-spin-button,.fdy-input[type="number"]::-webkit-inner-spin-button{appearance:none;-webkit-appearance:none;margin:0;}
 .fdy-input--error,.fdy-input[aria-invalid="true"],.fdy-textarea[aria-invalid="true"]{border-color:var(--color-danger);}
 .fdy-input--error:focus,.fdy-input[aria-invalid="true"]:focus,.fdy-textarea[aria-invalid="true"]:focus{border-color:var(--color-danger);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-danger) 26%,transparent);}
 .fdy-help{font-size:var(--text-xs);color:var(--color-text-muted);}