@xeplr/ui-utils 1.0.0 → 1.0.2

package/src/dataImport/useImportHistoryController.js

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * @param {object} options
+ * @param {() => Promise<{jobs: object[]}|object[]>} options.onList
+ * @param {(job: object) => Promise<any>} options.onRollback
+ * @param {(job: object) => Promise<any>} [options.onDelete]
+ *
+ * Job shape (generic — same part/target vocabulary as useDataImportController):
+ *   { id, originalFileName, part, target, rows, status, startedAt, error,
+ *     destination?, rowsLoaded?, rowsDropped?, createdByName? }
+ * status: 'completed' | 'failed' | 'rolled-back' — only 'completed' rows are
+ * rollback-able; the design decides how to render the others.
+ * The `?` fields are optional context (where it went beyond the target table,
+ * a loaded/dropped breakdown, who ran it) — apps that don't track them can
+ * omit them and the design falls back to '—'.
+ */
+export function useImportHistoryController(options = {}) {
+  var [jobs, setJobs] = useState([]);
+  var [loading, setLoading] = useState(false);
+  var [error, setError] = useState('');
+  var [rollingBackId, setRollingBackId] = useState(null);
+  var [deletingId, setDeletingId] = useState(null);
+
+  var load = useCallback(async function() {
+    setLoading(true);
+    setError('');
+    try {
+      var res = await options.onList();
+      setJobs((res && res.jobs) || res || []);
+    } catch (err) {
+      setError(err.message || 'Failed to load import history');
+    } finally {
+      setLoading(false);
+    }
+  }, [options.onList]);
+
+  useEffect(function() { load(); }, [load]);
+
+  async function handleRollback(job) {
+    setRollingBackId(job.id);
+    setError('');
+    try {
+      await options.onRollback(job);
+      await load();
+    } catch (err) {
+      setError(err.message || 'Rollback failed');
+    } finally {
+      setRollingBackId(null);
+    }
+  }
+
+  async function handleDelete(job) {
+    setDeletingId(job.id);
+    setError('');
+    try {
+      await options.onDelete(job);
+      await load();
+    } catch (err) {
+      setError(err.message || 'Delete failed');
+    } finally {
+      setDeletingId(null);
+    }
+  }
+
+  return { jobs, loading, error, rollingBackId, deletingId, reload: load, handleRollback, handleDelete };
+}

package/src/dataImport/validateDesign.js

@@ -0,0 +1,68 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Validates that required elements exist in the rendered design, and reports
+ * loudly when they don't — console.error plus a data-xeplr-design-invalid
+ * marker on the container.
+ *
+ * A rule matches by id, role or selector. `anyOf` takes a list of selectors
+ * and passes when ANY one is present — which is what a design with tabs or
+ * steps needs, since only the current one is mounted and demanding all of
+ * them at once can never pass.
+ *
+ * @param {string} componentName - Name of the page (for error messages)
+ * @param {Array<{id?: string, role?: string, selector?: string, anyOf?: string[], label: string}>} requiredElements
+ */
+export function useDesignValidator(componentName, requiredElements) {
+  var containerRef = useRef(null);
+
+  useEffect(function() {
+    if (!containerRef.current) return;
+
+    var missing = [];
+    for (var i = 0; i < requiredElements.length; i++) {
+      var rule = requiredElements[i];
+      var found = false;
+
+      if (rule.id) {
+        found = !!containerRef.current.querySelector('#' + rule.id);
+      } else if (rule.role) {
+        found = !!containerRef.current.querySelector('[role="' + rule.role + '"]');
+      } else if (rule.anyOf) {
+        for (var j = 0; j < rule.anyOf.length && !found; j++) {
+          found = !!containerRef.current.querySelector(rule.anyOf[j]);
+        }
+      } else if (rule.selector) {
+        found = !!containerRef.current.querySelector(rule.selector);
+      }
+
+      if (!found) {
+        var where = rule.id ? ' (id="' + rule.id + '")'
+          : rule.anyOf ? ' (one of: ' + rule.anyOf.join(', ') + ')'
+          : rule.selector ? ' (' + rule.selector + ')' : '';
+        missing.push(rule.label + where);
+      }
+    }
+
+    if (missing.length > 0) {
+      // Reported, not thrown. Throwing from an effect gives React nothing to
+      // catch, so a design rule — a development-time check — took the whole
+      // application down with it. The container is marked so the failure is
+      // visible on the page as well as in the console, which is what "fail
+      // loudly" was ever meant to buy.
+      var message = '[xeplr-ui-utils] ' + componentName + ' design is missing required elements:\n' +
+        missing.map(function(m) { return '  - ' + m; }).join('\n');
+      console.error(message);
+      containerRef.current.setAttribute('data-xeplr-design-invalid', componentName);
+      containerRef.current.setAttribute('title', message);
+    }
+  }, []);
+
+  return containerRef;
+}
+
+export var DATA_IMPORT_RULES = [
+  { selector: 'input[type="file"]', label: 'File input' }
+];
+
+export var IMPORT_HISTORY_RULES = [];

package/src/dateField/dateField.js

@@ -0,0 +1,71 @@
+/**
+ * DateField — pure model. No React.
+ *
+ * Three flavours:
+ *   - 'date'     → ISO date string (YYYY-MM-DD)
+ *   - 'datetime' → ISO datetime string (YYYY-MM-DDTHH:mm)
+ *   - 'age'      → input is a DOB (date), output value is the DOB but the
+ *                  age in years is computed and returned alongside.
+ */
+
+export var DATE_TYPES = ['date', 'datetime', 'age'];
+
+export function isValidISODate(s) {
+  if (typeof s !== 'string' || s.length === 0) return false;
+  var d = new Date(s);
+  return !isNaN(d.getTime());
+}
+
+/**
+ * Calculate completed years between dob and `now`. Returns null if dob is invalid.
+ */
+export function calculateAge(dob, now) {
+  if (!dob) return null;
+  var birth = dob instanceof Date ? dob : new Date(dob);
+  if (isNaN(birth.getTime())) return null;
+  var ref = now || new Date();
+  var years = ref.getFullYear() - birth.getFullYear();
+  var monthDiff = ref.getMonth() - birth.getMonth();
+  if (monthDiff < 0 || (monthDiff === 0 && ref.getDate() < birth.getDate())) {
+    years--;
+  }
+  return years < 0 ? null : years;
+}
+
+/**
+ * Map our public type to the underlying <input> type attribute.
+ */
+export function inputTypeFor(type) {
+  if (type === 'datetime') return 'datetime-local';
+  return 'date';
+}
+
+/**
+ * Normalise a Date or string into the format the <input> element expects.
+ */
+export function toInputValue(value, type) {
+  if (!value) return '';
+  var d = value instanceof Date ? value : new Date(value);
+  if (isNaN(d.getTime())) return '';
+  var pad = function(n) { return n < 10 ? '0' + n : '' + n; };
+  var ymd = d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate());
+  if (type === 'datetime') {
+    return ymd + 'T' + pad(d.getHours()) + ':' + pad(d.getMinutes());
+  }
+  return ymd;
+}
+
+export function validateBounds(value, min, max) {
+  if (!value) return { valid: true };
+  var d = value instanceof Date ? value : new Date(value);
+  if (isNaN(d.getTime())) return { valid: false, error: 'Invalid date' };
+  if (min) {
+    var dMin = min instanceof Date ? min : new Date(min);
+    if (d < dMin) return { valid: false, error: 'Date is before minimum' };
+  }
+  if (max) {
+    var dMax = max instanceof Date ? max : new Date(max);
+    if (d > dMax) return { valid: false, error: 'Date is after maximum' };
+  }
+  return { valid: true };
+}

package/src/dateField/designs/DateFieldSample.jsx

@@ -0,0 +1,30 @@
+import './dateField.css';
+
+export default function DateFieldSample({
+  type, inputType, raw, age, error, placeholder, disabled, min, max,
+  handleChange
+}) {
+  return (
+    <div className={'xeplr-datefield xeplr-datefield-' + type + (error ? ' xeplr-datefield-error' : '')}>
+      <div className="xeplr-datefield-row">
+        <input
+          type={inputType}
+          className="xeplr-datefield-input"
+          value={raw}
+          placeholder={placeholder}
+          disabled={disabled}
+          min={min}
+          max={max}
+          onChange={handleChange}
+        />
+        {type === 'age' && (
+          <div className="xeplr-datefield-age">
+            <span className="xeplr-datefield-age-label">Age</span>
+            <span className="xeplr-datefield-age-value">{age === null ? '—' : age + ' yrs'}</span>
+          </div>
+        )}
+      </div>
+      {error && <div className="xeplr-datefield-error-text">{error}</div>}
+    </div>
+  );
+}

package/src/dateField/designs/dateField.css

@@ -0,0 +1,60 @@
+.xeplr-datefield {
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #e0e0e0;
+}
+
+.xeplr-datefield-row {
+  display: flex;
+  align-items: stretch;
+  gap: 10px;
+}
+
+.xeplr-datefield-input {
+  flex: 1;
+  background: #1a1a1a;
+  border: 1px solid #444;
+  border-radius: 6px;
+  padding: 9px 12px;
+  color: inherit;
+  font-size: 14px;
+  outline: none;
+  color-scheme: dark;
+}
+
+.xeplr-datefield-input:focus {
+  border-color: #646cff;
+  box-shadow: 0 0 0 2px rgba(100, 108, 255, 0.18);
+}
+
+.xeplr-datefield-error .xeplr-datefield-input {
+  border-color: #e25555;
+}
+
+.xeplr-datefield-age {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  background: #232540;
+  border-radius: 6px;
+  padding: 4px 14px;
+  min-width: 90px;
+}
+
+.xeplr-datefield-age-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: #888bbf;
+}
+
+.xeplr-datefield-age-value {
+  font-size: 14px;
+  font-weight: 600;
+  color: #e0e0e0;
+}
+
+.xeplr-datefield-error-text {
+  margin-top: 4px;
+  font-size: 12px;
+  color: #e25555;
+}

package/src/dateField/designs/index.js

@@ -0,0 +1 @@
+export { default as DateFieldSample } from './DateFieldSample.jsx';

package/src/dateField/pages.jsx

@@ -0,0 +1,10 @@
+import { useDateFieldController } from './useDateFieldController.js';
+import DateFieldSample from './designs/DateFieldSample.jsx';
+import { useDesignValidator } from '../fileUpload/validateDesign.js';
+import { DATE_FIELD_RULES } from './validateDesign.js';
+
+export function DateFieldPage(props) {
+  var controller = useDateFieldController(props);
+  var ref = useDesignValidator('DateFieldPage', DATE_FIELD_RULES);
+  return <div ref={ref}><DateFieldSample {...controller} /></div>;
+}

package/src/dateField/useDateFieldController.js

@@ -0,0 +1,77 @@
+import { useState, useEffect, useMemo } from 'react';
+import {
+  DATE_TYPES,
+  calculateAge,
+  inputTypeFor,
+  toInputValue,
+  validateBounds
+} from './dateField.js';
+
+/**
+ * @param {object} props
+ * @param {'date'|'datetime'|'age'} [props.type='date']
+ * @param {Date|string|null} [props.value]        — controlled value
+ * @param {Date|string|null} [props.defaultValue] — uncontrolled initial value
+ * @param {(value, meta) => void} [props.onChange] — meta.age included for age type
+ * @param {Date|string} [props.min]
+ * @param {Date|string} [props.max]
+ * @param {string} [props.placeholder]
+ * @param {boolean} [props.disabled]
+ */
+export function useDateFieldController(props) {
+  props = props || {};
+  var type = props.type || 'date';
+  if (DATE_TYPES.indexOf(type) === -1) {
+    throw new Error('[xeplr-ui-utils:DateField] Unknown type: ' + type + '. Expected one of ' + DATE_TYPES.join(', '));
+  }
+
+  var isControlled = props.value !== undefined;
+  var initial = isControlled ? props.value : (props.defaultValue !== undefined ? props.defaultValue : null);
+
+  var [raw, setRaw] = useState(toInputValue(initial, type === 'age' ? 'date' : type));
+  var [error, setError] = useState('');
+
+  useEffect(function() {
+    if (isControlled) {
+      setRaw(toInputValue(props.value, type === 'age' ? 'date' : type));
+    }
+  }, [props.value, isControlled, type]);
+
+  var inputType = useMemo(function() {
+    return inputTypeFor(type === 'age' ? 'date' : type);
+  }, [type]);
+
+  var age = useMemo(function() {
+    if (type !== 'age') return null;
+    return calculateAge(raw);
+  }, [type, raw]);
+
+  function emit(nextRaw) {
+    var bounds = validateBounds(nextRaw, props.min, props.max);
+    setError(bounds.valid ? '' : bounds.error);
+    if (props.onChange) {
+      var meta = {};
+      if (type === 'age') meta.age = calculateAge(nextRaw);
+      props.onChange(nextRaw || null, meta);
+    }
+  }
+
+  function handleChange(e) {
+    var v = e.target.value;
+    if (!isControlled) setRaw(v);
+    emit(v);
+  }
+
+  return {
+    type,
+    inputType,
+    raw,
+    age,
+    error,
+    placeholder: props.placeholder,
+    disabled: !!props.disabled,
+    min: props.min ? toInputValue(props.min, type === 'age' ? 'date' : type) : undefined,
+    max: props.max ? toInputValue(props.max, type === 'age' ? 'date' : type) : undefined,
+    handleChange
+  };
+}

package/src/dateField/validateDesign.js

@@ -0,0 +1,3 @@
+export var DATE_FIELD_RULES = [
+  { selector: 'input[type="date"], input[type="datetime-local"], input.xeplr-datefield-input', label: 'Date input element' }
+];

package/src/dateRange/dateRange.js

@@ -0,0 +1,273 @@
+// DateRange — model. A date SELECTION, and how it becomes a real from/to
+// range. Pure: no React, no DOM.
+//
+// One shape covers every way a person names a span of time, which is the
+// point. A default set once, a preset that keeps moving, and a range typed by
+// hand are all the same value, so an app can fall back between them without
+// three different mechanisms.
+//
+//   { kind: 'quick',  preset: 'current_month' }
+//   { kind: 'range',  from: '2022-01-01', to: '2022-03-31' }
+//   { kind: 'single', value: '2022-05' }        // a day, a month, or a year
+//   null                                         // not set — inherit
+//
+// EVERYTHING RESOLVES TO A RANGE, including a single date. "May 2022" is the
+// range 1–31 May; "2022" is the whole year; "1/1/2022" is that one day. A
+// consumer therefore always gets {from, to} and never has to ask which
+// comparison was meant — the selection already says.
+
+// April. Overridable per call — a financial year starts in a different month
+// in most of the world, and hardcoding one is how a report quietly reports
+// the wrong year.
+var DEFAULT_FISCAL_START_MONTH = 4
+
+function pad(n) { return String(n).padStart(2, '0') }
+function iso(y, m, d) { return `${y}-${pad(m + 1)}-${pad(d)}` }
+function lastDay(y, m) { return new Date(y, m + 1, 0).getDate() }
+
+/**
+ * The presets people actually ask for. Each resolves against `now`, so a
+ * report saved with one stays current instead of freezing on the day it was
+ * built — the whole reason to prefer a preset over a literal date.
+ */
+export const QUICK_PRESETS = [
+  { key: 'today', label: 'Today' },
+  { key: 'yesterday', label: 'Yesterday' },
+  { key: 'dby', label: 'Day before yesterday' },
+  { key: 'last_7_days', label: 'Last 7 days' },
+  { key: 'last_30_days', label: 'Last 30 days' },
+  { key: 'current_month', label: 'Current month' },
+  { key: 'current_mtd', label: 'Current month-to-date' },
+  { key: 'last_month', label: 'Last month' },
+  { key: 'current_quarter', label: 'Current quarter' },
+  { key: 'current_qtd', label: 'Current quarter-to-date' },
+  { key: 'last_quarter', label: 'Last quarter' },
+  { key: 'current_calendar_year', label: 'Current calendar year' },
+  { key: 'current_ytd', label: 'Current year-to-date' },
+  { key: 'last_calendar_year', label: 'Last calendar year' },
+  { key: 'current_financial_year', label: 'Current financial year' },
+  { key: 'current_fytd', label: 'Current financial year-to-date' },
+  { key: 'last_financial_year', label: 'Last financial year' }
+]
+
+const PRESET_LABEL = new Map(QUICK_PRESETS.map((p) => [p.key, p.label]))
+
+const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june',
+  'july', 'august', 'september', 'october', 'november', 'december']
+
+/**
+ * Parses the free text a Single selection accepts: a full date, a month, or a
+ * year. Returns a {from, to} range, since a month or a year IS a range.
+ *
+ * Day-first for the ambiguous slash form (1/2/2022 is 1 February), matching
+ * where this is used rather than the American reading.
+ */
+export function parseSingleDate(text) {
+  const raw = String(text || '').trim()
+  if (!raw) return null
+
+  // 2022
+  let m = /^(\d{4})$/.exec(raw)
+  if (m) {
+    const y = Number(m[1])
+    return { from: iso(y, 0, 1), to: iso(y, 11, 31) }
+  }
+
+  // 2022-05 or 2022/05
+  m = /^(\d{4})[-/](\d{1,2})$/.exec(raw)
+  if (m) {
+    const y = Number(m[1]); const mo = Number(m[2]) - 1
+    if (mo < 0 || mo > 11) return null
+    return { from: iso(y, mo, 1), to: iso(y, mo, lastDay(y, mo)) }
+  }
+
+  // 2022-05-17
+  m = /^(\d{4})[-/](\d{1,2})[-/](\d{1,2})$/.exec(raw)
+  if (m) {
+    const y = Number(m[1]); const mo = Number(m[2]) - 1; const d = Number(m[3])
+    if (mo < 0 || mo > 11) return null
+    return { from: iso(y, mo, d), to: iso(y, mo, d) }
+  }
+
+  // May 2022 / may 2022
+  m = /^([A-Za-z]+)\s+(\d{4})$/.exec(raw)
+  if (m) {
+    const idx = MONTHS.findIndex((name) => name.startsWith(m[1].toLowerCase()))
+    if (idx === -1) return null
+    const y = Number(m[2])
+    return { from: iso(y, idx, 1), to: iso(y, idx, lastDay(y, idx)) }
+  }
+
+  // 17/5/2022 — day first.
+  m = /^(\d{1,2})[-/](\d{1,2})[-/](\d{4})$/.exec(raw)
+  if (m) {
+    const d = Number(m[1]); const mo = Number(m[2]) - 1; const y = Number(m[3])
+    if (mo < 0 || mo > 11) return null
+    return { from: iso(y, mo, d), to: iso(y, mo, d) }
+  }
+
+  return null
+}
+
+function shift(now, days) {
+  const d = new Date(now.getFullYear(), now.getMonth(), now.getDate() - days)
+  return iso(d.getFullYear(), d.getMonth(), d.getDate())
+}
+
+function monthRange(y, m) {
+  return { from: iso(y, m, 1), to: iso(y, m, lastDay(y, m)) }
+}
+
+/**
+ * What somebody might mean, as they type — months and years, never days.
+ *
+ * A day is faster to finish typing than to pick out of a list, and there are
+ * thirty of them. A MONTH is the opposite: "j" is three different months, and
+ * each of those is a different year depending on what you were just looking
+ * at. That ambiguity is the whole reason to suggest anything.
+ *
+ * ANCHORED to the year already in play — if the filter currently says
+ * Feb 2025, typing "j" offers Jan/Jun/Jul 2025 first, because somebody
+ * comparing months is almost always comparing them within a year. Other years
+ * follow, so the less common case is one click rather than more typing.
+ *
+ * @param {string} text     what has been typed so far
+ * @param {number} anchor   the year to offer first
+ * @param {number} years    how many additional years to offer per month
+ */
+export function singleDateSuggestions(text, anchor, years) {
+  const q = String(text || '').trim().toLowerCase()
+  const year = Number(anchor) || new Date().getFullYear()
+  const depth = years == null ? 2 : years
+  if (!q) return []
+
+  // A year on its own — "202" is a prefix of several, and a whole year is a
+  // legitimate answer in its own right.
+  if (/^\d{1,4}$/.test(q)) {
+    const out = []
+    for (let y = year + 1; y >= year - 6; y--) {
+      if (String(y).startsWith(q)) out.push({ value: String(y), label: String(y), note: 'the whole year' })
+    }
+    return out.slice(0, 8)
+  }
+
+  // "jan 20", "june 2024" — the month is settled, so only years are open.
+  const withYear = /^([a-z]+)\s+(\d{1,4})$/.exec(q)
+  const monthQuery = withYear ? withYear[1] : q
+  const yearQuery = withYear ? withYear[2] : null
+  if (!/^[a-z]+$/.test(monthQuery)) return []
+
+  const hits = []
+  MONTHS.forEach((name, i) => {
+    if (!name.startsWith(monthQuery)) return
+    hits.push({ name: name.charAt(0).toUpperCase() + name.slice(1), index: i })
+  })
+  if (!hits.length) return []
+
+  // The anchor year first for every match, THEN the other years — so a list
+  // of three months reads Jan/Jun/Jul 2025 before it reads Jan 2024, rather
+  // than burying two of this year's months under last year's January.
+  const out = []
+  const push = (m, y) => {
+    if (yearQuery && !String(y).startsWith(yearQuery)) return
+    out.push({ value: m.name + ' ' + y, label: m.name + ' ' + y, note: null })
+  }
+  hits.forEach((m) => push(m, year))
+  for (let d = 1; d <= depth; d++) {
+    hits.forEach((m) => push(m, year - d))
+  }
+  hits.forEach((m) => push(m, year + 1))
+  return out.slice(0, 10)
+}
+
+export function resolveQuickPreset(preset, now, options) {
+  const fiscalStart = ((options && options.fiscalStartMonth) || DEFAULT_FISCAL_START_MONTH) - 1
+  const y = now.getFullYear()
+  const m = now.getMonth()
+  const today = iso(y, m, now.getDate())
+  const q = Math.floor(m / 3)
+  // The fiscal year containing `now` began this calendar year only if we're
+  // already past its start month — same rule as shared/params.js.
+  const fy = m >= fiscalStart ? y : y - 1
+
+  switch (preset) {
+    case 'today': return { from: today, to: today }
+    case 'yesterday': return { from: shift(now, 1), to: shift(now, 1) }
+    case 'dby': return { from: shift(now, 2), to: shift(now, 2) }
+    case 'last_7_days': return { from: shift(now, 6), to: today }
+    case 'last_30_days': return { from: shift(now, 29), to: today }
+
+    case 'current_month': return monthRange(y, m)
+    case 'current_mtd': return { from: iso(y, m, 1), to: today }
+    case 'last_month': return m === 0 ? monthRange(y - 1, 11) : monthRange(y, m - 1)
+
+    case 'current_quarter': return { from: iso(y, q * 3, 1), to: iso(y, q * 3 + 2, lastDay(y, q * 3 + 2)) }
+    case 'current_qtd': return { from: iso(y, q * 3, 1), to: today }
+    case 'last_quarter': {
+      const ly = q === 0 ? y - 1 : y
+      const lq = q === 0 ? 3 : q - 1
+      return { from: iso(ly, lq * 3, 1), to: iso(ly, lq * 3 + 2, lastDay(ly, lq * 3 + 2)) }
+    }
+
+    case 'current_calendar_year': return { from: iso(y, 0, 1), to: iso(y, 11, 31) }
+    case 'current_ytd': return { from: iso(y, 0, 1), to: today }
+    case 'last_calendar_year': return { from: iso(y - 1, 0, 1), to: iso(y - 1, 11, 31) }
+
+    case 'current_financial_year': {
+      const end = new Date(fy + 1, fiscalStart, 0)
+      return { from: iso(fy, fiscalStart, 1), to: iso(end.getFullYear(), end.getMonth(), end.getDate()) }
+    }
+    case 'current_fytd': return { from: iso(fy, fiscalStart, 1), to: today }
+    case 'last_financial_year': {
+      const end = new Date(fy, fiscalStart, 0)
+      return { from: iso(fy - 1, fiscalStart, 1), to: iso(end.getFullYear(), end.getMonth(), end.getDate()) }
+    }
+
+    default: return null
+  }
+}
+
+/**
+ * A selection -> { from, to }, or null when it resolves to nothing.
+ *
+ * A null result is "no constraint", never "match nothing" — an unresolvable
+ * selection must widen rather than silently empty the report.
+ */
+export function resolveDateValue(value, now, options) {
+  if (!value) return null
+  if (value.kind === 'quick') return resolveQuickPreset(value.preset, now || new Date(), options)
+  if (value.kind === 'single') return parseSingleDate(value.value)
+  if (value.kind === 'range') {
+    const from = value.from || null
+    const to = value.to || null
+    if (!from && !to) return null
+    return { from, to }
+  }
+  return null
+}
+
+/** What the chip and the panel read. */
+export function dateValueLabel(value) {
+  if (!value) return null
+  if (value.kind === 'quick') return PRESET_LABEL.get(value.preset) || value.preset
+  if (value.kind === 'single') return value.value || null
+  if (value.kind === 'range') {
+    if (value.from && value.to) return `${value.from} → ${value.to}`
+    if (value.from) return `From ${value.from}`
+    if (value.to) return `Until ${value.to}`
+    return null
+  }
+  return null
+}
+
+/**
+ * True when a selection would actually constrain anything.
+ *
+ * Defined as "resolves to a range", NOT "has something typed in it". A Single
+ * holding unparseable text has a label but no range — treating that as set
+ * would let it pass a "do we have a default?" check and then silently apply no
+ * filter at all, which is the worst of both.
+ */
+export function dateValueIsSet(value, now) {
+  return Boolean(resolveDateValue(value, now || new Date()))
+}