@xeplr/ui-utils 1.0.7 → 1.0.8

package/README.md

@@ -108,7 +108,7 @@ export default function SelectCompany() {
 | hook | takes | returns |
 |---|---|---|
 | `useDropdownController(props)` | DropdownPage props | `mode, source, keys {id,name,extras}, searchable, canCreate, createLabel, creating, createError, createItem(name?), placeholder, disabled, items, filteredItems, selectedItems, selection, loading, error, query, isOpen, rootRef, isSelected(id), open, close, toggle, selectItem(id), removeSelection(id), clearSelection, handleSearch(e), refresh` |
-| `useDateRangeController(props)` | DateRangePage props | `tab, setTab, presets, value, label, range, single, setSingle, singleParsed, suggestions, applySuggestion(text), selectPreset(key), setRangeFrom, setRangeTo, commitSingle(close), clear, allowClear, inheritedLabel` |
+| `useDateRangeController(props)` | DateRangePage props | `tab, setTab, presets, value, label, range, single, setSingle, singleParsed, suggestions, applySuggestion(text), selectPreset(key), setRangeFrom, setRangeTo (edit the draft), applyRange(), rangeProblem, rangeDirty, commitSingle(close), clear, allowClear, inheritedLabel` |
 | `useRangeFieldController(props)` | RangeFieldPage props | `fromLabel, toLabel, from, to`. `from` and `to` are each a `useDateFieldController` result. |
 | `useDateFieldController(props)` | DateFieldPage props | `type, inputType, raw, age, error, placeholder, disabled, min, max, handleChange` |
 | `useNumberFieldController(props)` | NumberFieldPage props | `type, raw, numeric, error, placeholder, disabled, decimals, formatDisplay, affix {list, selected, position, labelKey, valueKey} \| null, handleNumberChange, handleAffixChange, handleBlur` |
@@ -129,6 +129,7 @@ export default function SelectCompany() {
 | `resolveDateValue` | `(selection, now?, options?) → { from, to } \| null` | Resolves a `quick` / `range` / `single` selection. `null` means no constraint. |
 | `dateValueLabel` | `(selection) → string \| null` | "Last month", "2022-01-01 → 2022-03-31", "From …", "Until …" |
 | `dateValueIsSet` | `(selection, now?) → boolean` | True only if the selection resolves to a range |
+| `rangeProblem` | `({ from, to }) → string \| null` | Why a typed range cannot be applied yet ("Choose a From or a To date", "From is after To"), or `null` |
 | `RANGE_TYPES`, `emptyRange`, `normalizeRange`, `rangeIsSet` | `['date','datetime']`, `() → {from:'',to:''}`, `(r) → {from,to}`, `(r) → boolean` | From/to helpers. A range with one side set counts as set. |
 | `DATE_TYPES`, `isValidISODate`, `calculateAge`, `inputTypeFor`, `toInputValue`, `validateBounds` | `['date','datetime','age']`, `(s)`, `(dob, now?)`, `(type)`, `(value, type)`, `(value, min, max) → { valid, error? }` | Date field helpers |
 | `NUMBER_TYPES`, `sanitizeNumberInput`, `toNumeric`, `formatDisplay`, `validateRange`, `resolveAffixState` | `['float','currency','units']`, `(raw)`, `(raw) → number \| null`, `(value, decimals?)`, `(value, min, max) → { valid, error? }`, `(type, options)` | Number field helpers. `sanitizeNumberInput` keeps digits, the first `.`, and a leading `-`. |
@@ -189,12 +190,12 @@ export default function SelectCompany() {
 |---|---|---|---|
 | `value` | `{ kind: 'quick', preset } \| { kind: 'range', from, to } \| { kind: 'single', value } \| null` | `null` | The selection |
 | `onChange` | `(selection \| null) => void` | no-op | |
-| `onClose` | `() => void` | — | Called after a choice that ends the interaction: a preset, a suggestion, Enter in Single, or Clear |
+| `onClose` | `() => void` | — | Called after a choice that ends the interaction: a preset, a suggestion, Apply (or Enter) in Range or Single, or Clear |
 | `presets` | `[{ key, label }]` | `QUICK_PRESETS` | The Quick list. Only keys that `resolveQuickPreset` knows will resolve. |
 | `allowClear` | `boolean` | `true` | `false` removes the Clear button, and `clear()` refuses too |
 | `inheritedLabel` | `string` | — | Shows "Using …" when `value` is empty |
 
-**Every selection resolves to `{ from, to }`, including a single date.** "May 2022" becomes 1–31 May and "2022" becomes the whole year, so a consumer never has to ask which comparison was meant. The Range tab changes `onChange` on every edit, and one open side is allowed. The Single tab commits only once the text parses ("Not a date yet" otherwise), on blur or Enter. While you type, it suggests months and years, putting the committed year first. The financial-year presets use `fiscalStartMonth` (default April). The page itself does not pass that option, so change it by calling `resolveDateValue(value, now, { fiscalStartMonth })` where you consume the value.
+**Every selection resolves to `{ from, to }`, including a single date.** "May 2022" becomes 1–31 May and "2022" becomes the whole year, so a consumer never has to ask which comparison was meant. **The Range tab is applied, not taken as you type.** A browser date input holds a complete date while a year is half typed (`2` is `0002-01-01`), so committing each edit ran the host's query for the year 2. The inputs edit a draft, and `onChange` fires once, on **Apply** or Enter. Apply is disabled until the draft is valid (`rangeProblem`: something chosen, From not after To) and differs from what is applied. One open side is allowed. The Single tab commits only once the text parses ("Not a date yet" otherwise), on blur, Enter or Apply. While you type, it suggests months and years, putting the committed year first. The financial-year presets use `fiscalStartMonth` (default April). The page itself does not pass that option, so change it by calling `resolveDateValue(value, now, { fiscalStartMonth })` where you consume the value.
 
 ## RangeFieldPage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-utils",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "UI utility components: file upload with progress, snackbar, static data (countries/states)",
   "type": "module",
   "main": "src/index.js",

package/src/dateRange/dateRange.js

@@ -271,3 +271,22 @@ export function dateValueLabel(value) {
 export function dateValueIsSet(value, now) {
   return Boolean(resolveDateValue(value, now || new Date()))
 }
+
+/**
+ * Why a typed range cannot be applied yet, or null when it can.
+ *
+ * A browser date input holds a COMPLETE date while the year is still being
+ * typed ("2" is 0002-…), so a range is never taken as you type — it is
+ * applied (the Apply button, or Enter), and this is what Apply asks first.
+ * One side empty is fine: "everything since April" is a real range.
+ *
+ * @param {{from?: string, to?: string}} draft - ISO dates, either may be empty
+ * @returns {string|null}
+ */
+export function rangeProblem(draft) {
+  var from = (draft && draft.from) || '';
+  var to = (draft && draft.to) || '';
+  if (!from && !to) return 'Choose a From or a To date';
+  if (from && to && from > to) return 'From is after To';
+  return null;
+}

package/src/dateRange/designs/DateRangeSample.jsx

@@ -56,17 +56,30 @@ export default function DateRangeSample(props) {
 
       {props.tab === 'range' && (
         <div className="xeplr-daterange-body">
+          {/* Edited as a draft and applied — the inputs hold a full date while
+              a year is half typed, so taking each change ran the report for
+              the year 2. Enter in either input applies too. */}
           <label className="xeplr-daterange-field">
             <span>From</span>
-            <input type="date" value={props.range.from || ''} onChange={function(e) { props.setRangeFrom(e.target.value); }} />
+            <input type="date" value={props.range.from || ''} onChange={function(e) { props.setRangeFrom(e.target.value); }}
+              onKeyDown={function(e) { if (e.key === 'Enter') { e.preventDefault(); props.applyRange(); } }} />
           </label>
           <label className="xeplr-daterange-field">
             <span>To</span>
-            <input type="date" value={props.range.to || ''} onChange={function(e) { props.setRangeTo(e.target.value); }} />
+            <input type="date" value={props.range.to || ''} onChange={function(e) { props.setRangeTo(e.target.value); }}
+              onKeyDown={function(e) { if (e.key === 'Enter') { e.preventDefault(); props.applyRange(); } }} />
           </label>
           {/* One-sided is legitimate — "everything since April" is a real
               answer — so it is stated rather than blocked. */}
-          <div className="xeplr-daterange-note">Leave either side empty for an open-ended range.</div>
+          <div className="xeplr-daterange-note">
+            {props.rangeProblem && (props.range.from || props.range.to)
+              ? props.rangeProblem
+              : 'Leave either side empty for an open-ended range.'}
+          </div>
+          <div className="xeplr-daterange-actions">
+            <button type="button" className="xeplr-daterange-apply" data-xeplr-daterange-apply="range"
+              disabled={Boolean(props.rangeProblem) || !props.rangeDirty} onClick={props.applyRange}>Apply</button>
+          </div>
         </div>
       )}
 
@@ -117,6 +130,12 @@ export default function DateRangeSample(props) {
               ? (props.singleParsed ? props.singleParsed.from + ' → ' + props.singleParsed.to : 'Not a date yet')
               : 'A day, a whole month, or a whole year.'}
           </div>
+          <div className="xeplr-daterange-actions">
+            <button type="button" className="xeplr-daterange-apply" data-xeplr-daterange-apply="single"
+              disabled={!props.singleParsed}
+              // MOUSEDOWN: the input's onBlur would otherwise commit first.
+              onMouseDown={function(e) { e.preventDefault(); props.commitSingle(true); }}>Apply</button>
+          </div>
         </div>
       )}
 

package/src/dateRange/designs/dateRange.css

@@ -67,3 +67,15 @@
 }
 .xeplr-daterange-suggest button:hover { background: var(--xeplr-hover, #f4f5f8); }
 .xeplr-daterange-suggest-note { font-size: 11px; color: var(--xeplr-muted, #6b7280); }
+
+/* Apply — a typed range (or date) reaches the host only through this, or
+   Enter. Disabled while there is nothing new to apply, or it is not valid. */
+.xeplr-daterange-actions { display: flex; justify-content: flex-end; margin-top: 8px; }
+.xeplr-daterange-apply {
+  padding: 5px 14px; border-radius: 6px; cursor: pointer;
+  font-size: 12px; font-weight: 600;
+  border: 1px solid var(--xeplr-accent, #4f5fd6);
+  background: var(--xeplr-accent, #4f5fd6);
+  color: var(--xeplr-on-accent, #fff);
+}
+.xeplr-daterange-apply:disabled { opacity: 0.45; cursor: default; }

package/src/dateRange/useDateRangeController.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { QUICK_PRESETS, parseSingleDate, dateValueLabel, singleDateSuggestions } from './dateRange.js';
+import { QUICK_PRESETS, parseSingleDate, dateValueLabel, singleDateSuggestions, rangeProblem } from './dateRange.js';
 
 /**
  * DateRange — controller. Owns which tab is open and the half-typed text; the
@@ -37,7 +37,21 @@ export function useDateRangeController(props) {
     if (value && value.kind === 'single') setSingle(value.value || '');
   }, [value]);
 
-  var range = value && value.kind === 'range' ? value : { from: '', to: '' };
+  // THE RANGE IS A DRAFT until it is applied. It used to be committed on
+  // every change of either input — and a date input holds a complete date
+  // while the year is half typed ("2" is 0002-01-01), so typing 2026 ran the
+  // report for the year 2. Now the inputs edit this draft, and applyRange
+  // (the Apply button, or Enter) commits it.
+  var committedRange = value && value.kind === 'range' ? value : null;
+  var draftState = useState({ from: committedRange ? committedRange.from || '' : '', to: committedRange ? committedRange.to || '' : '' });
+  var range = draftState[0];
+  var setRange = draftState[1];
+  // A range chosen elsewhere (a reset, another record) replaces the draft.
+  useEffect(function() {
+    if (value && value.kind === 'range') setRange({ from: value.from || '', to: value.to || '' });
+  }, [value]);
+  var rangeIssue = rangeProblem(range);
+  var rangeDirty = !committedRange || (committedRange.from || '') !== range.from || (committedRange.to || '') !== range.to;
   // Parsed as you type, so "May 202" reads as not-a-date-yet rather than
   // silently saving as nothing.
   var singleParsed = single ? parseSingleDate(single) : null;
@@ -71,11 +85,19 @@ export function useDateRangeController(props) {
   }
 
   function setRangeFrom(from) {
-    onChange({ kind: 'range', from: from, to: range.to || '' });
+    setRange(function(r) { return { from: from || '', to: r.to }; });
   }
 
   function setRangeTo(to) {
-    onChange({ kind: 'range', from: range.from || '', to: to });
+    setRange(function(r) { return { from: r.from, to: to || '' }; });
+  }
+
+  // Commits the draft. Refused while it has a problem (rangeProblem), so a
+  // custom design cannot apply a range Apply would have been disabled for.
+  function applyRange() {
+    if (rangeIssue) return;
+    onChange({ kind: 'range', from: range.from, to: range.to });
+    if (onClose) onClose();
   }
 
   // Only committed once it parses — a partial entry must not overwrite a good
@@ -110,6 +132,9 @@ export function useDateRangeController(props) {
     selectPreset: selectPreset,
     setRangeFrom: setRangeFrom,
     setRangeTo: setRangeTo,
+    applyRange: applyRange,
+    rangeProblem: rangeIssue,
+    rangeDirty: rangeDirty,
     commitSingle: commitSingle,
     clear: clear,
     allowClear: allowClear,

package/src/index.js

@@ -92,7 +92,8 @@ export {
   resolveQuickPreset,
   resolveDateValue,
   dateValueLabel,
-  dateValueIsSet
+  dateValueIsSet,
+  rangeProblem
 } from './dateRange/dateRange.js';
 
 // DateRange — controller