agentcss 0.0.0-stage → 0.11.2

package/02-primitives/date-range/README.md

@@ -0,0 +1,100 @@
+# date-range · 日期区间
+
+财务/成本场景刚需：**"看上季度"、"对比去年同期"**。
+
+## 🔴 三件容易做错的事（写在最前面）
+
+| # | 做什么 | 不做会怎样 |
+|---|---|---|
+| ① | **必须有「清除」按钮** | 日期填错了，用户只能一个个退格删 |
+| ② | **`min`/`max` 越界与"开始晚于结束"要明确报错** | 用户不知道自己填错了，还以为没生效 |
+| ③ | 快捷按钮必须能 `Tab` 到 | 键盘用户完全用不了"看上季度" |
+
+## 结构
+
+```html
+<div class="drange">
+  <label class="drange__label">
+    <span>开始</span>
+    <input class="drange__input" type="date" data-dr-from>
+  </label>
+  <span class="drange__sep" aria-hidden="true">→</span>
+  <label class="drange__label">
+    <span>结束</span>
+    <input class="drange__input" type="date" data-dr-to>
+  </label>
+  <button class="drange__clear" type="button" data-dr-clear>清除</button>
+  <div class="drange__presets">…上季度 / 上月 / 今年…</div>
+  <p data-dr-error role="alert"></p>
+  <p data-dr-summary></p>
+</div>
+```
+
+| 部件 | 说明 |
+|---|---|
+| `.drange` | 根，`flex-wrap` —— 窄屏自动换行 |
+| `[data-dr-from]` / `[data-dr-to]` | 两个日期输入，**缺任一个直接抛错** |
+| `[data-dr-error]` | 错误容器，`role="alert"` |
+| `[data-dr-summary]` | 选中区间的摘要（如「共 92 天」）|
+| `[data-dr-clear]` | 清除，**不可省** |
+| `.drange--disabled` | 整体禁用 |
+
+⚠️ 标记名是 **`data-dr-*`**（`dr` 缩写），不是 `data-drange-*`。
+
+## 启用
+
+```js
+const dr = DateRange.create(元素, {
+  presets: [{ label: '上季度', from: …, to: … }],
+  min: '2020-01-01', max: '2026-12-31',
+});
+```
+
+同时导出的一批**纯函数**（可单独用，很 handy）：
+
+```js
+DateRange.iso(date)              // → 'YYYY-MM-DD'
+DateRange.addDays(d, n)
+DateRange.addMonths(d, n)
+DateRange.quarterOf(d)           // → 0..3（0 = Q1）
+DateRange.quarterRange(y, q)     // 季度必须是 0-3，传别的直接抛错
+```
+
+⚠️ `quarterOf` 曾经是**内部函数但忘了导出** —— 使用者拿到了 `quarterRange`
+却无法从任意日期反推季度号。是单测抓出来的，补导出（纯函数，无副作用）。
+
+## 校验做了什么
+
+| 情况 | 行为 |
+|---|---|
+| 开始 > 结束 | 报「开始日期不能晚于结束日期（当前：…）」|
+| 早于 `min` | 报「开始日期不能早于 …」|
+| 晚于 `max` | 报「结束日期不能晚于 …」|
+| `quarterRange` 季度号越界 | 抛错并说明「季度必须是 0-3（0=Q1），收到 …」|
+
+### 🔴 错误要同时落到字段上，不只是显示一句话
+
+```js
+from.setAttribute('aria-invalid', msg ? 'true' : 'false');
+to.setAttribute('aria-invalid', msg ? 'true' : 'false');
+if (msg) {
+  errBox.id = 'dr-err-N';
+  from.setAttribute('aria-describedby', id);   // to 同理
+}
+```
+
+**为什么**：只显示一行红字，读屏用户**不知道是哪个字段错了**。
+`aria-invalid` 标记问题字段，`aria-describedby` 把错误挂到字段上，
+三件一起做才完整。
+
+`opt.min` / `opt.max` 会**同时**写到两个输入的原生 `min`/`max` 属性上
+（浏览器自带的日期选择器就会拦住越界值，不只是我们事后校验）。
+
+## 成熟度：stable（无行为债）
+
+契约里 `behaviorDebt` 为空 —— 清除、校验、preset 接线都有门禁覆盖
+（`05-audit/date-range-check.js`）。
+
+## 门禁
+
+`05-audit/date-range-check.js`

package/02-primitives/date-range/date-range.css

@@ -0,0 +1,206 @@
+/* ============================================================================
+   date-range.css — 日期区间（E3 /
+   ============================================================================
+   财务/成本场景刚需（"看上季度" "对比去年同期"）。
+
+   ⭐ 三件容易做错的事：
+     ① **必须有「清除」**：日期填错了要能一键清空
+        （没有清除按钮 = 用户只能一个个退格删日期）
+     ② **min/max 约束**：开始晚于结束、或超出范围时要**明确报错**
+     ③ **键盘可达**：三个快捷按钮（上季度/上月/今年）必须能 Tab 到
+   ============================================================================ */
+
+.drange {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: var(--sp-3);
+}
+
+.drange__field { flex: 1 1 10rem; min-width: 0; }
+
+.drange__label {
+  display: block;
+  margin-bottom: var(--sp-1);
+  font-size: var(--fs-xs);
+  color: var(--text-secondary);
+}
+
+.drange__input {
+  display: block;
+  width: 100%;
+  /* 🔴 必须：input 的 UA 盒模型是 content-box，width:100% 只是内容宽，
+     加 padding+border 实际比容器宽 26px ⇒ 393px 视口横向溢出。 */
+  box-sizing: border-box;
+  min-height: 44px;                    /* 🔴 命中区达标 */
+  padding: 0 var(--sp-3);
+  background: var(--surface);
+  color: var(--text-primary);
+  border: 1px solid var(--border-control);
+  border-radius: var(--r-sm);
+  font: inherit;
+  font-size: var(--fs-sm);
+  font-family: var(--mono);
+  font-variant-numeric: tabular-nums;
+  color-scheme: light dark;             /* ⭐ 让原生日期选择器跟随主题 */
+}
+
+.drange__input:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+  outline-offset: var(--focus-ring-offset);
+}
+
+/* ⭐ 错误态：边框 + 图标（**不能只改颜色**）*/
+.drange__input[aria-invalid="true"] {
+  border-color: var(--danger);
+  border-width: 2px;
+  background: var(--surface-sunken);
+}
+
+.drange__input[aria-invalid="true"]::after { content: " ⚠"; }
+
+.drange__sep {
+  flex: 0 0 auto;
+  padding-bottom: var(--sp-3);
+  color: var(--text-tertiary);
+  font-size: var(--fs-sm);
+}
+
+/* ---------- 快捷按钮 ---------- */
+.drange__presets {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--sp-2);
+  margin-top: var(--sp-3);
+}
+
+.drange__preset {
+  min-height: 32px;                     /* 密集数据表惯例（非 44）*/
+  padding: 0 var(--sp-3);
+  background: var(--surface);
+  color: var(--text-secondary);
+  border: 1px solid var(--border-control);
+  border-radius: var(--r-pill);
+  font: inherit;
+  font-size: var(--fs-xs);
+  cursor: pointer;
+}
+
+.drange__preset:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+  outline-offset: var(--focus-ring-offset);
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .drange__preset:hover { background: var(--surface-sunken); }
+}
+
+.drange__preset[aria-pressed="true"] {
+  background: var(--accent-soft);
+  border-color: var(--accent);
+  color: var(--text-primary);
+  font-weight: 600;
+}
+
+/* ---------- 错误提示 ---------- */
+/* 🔴 为什么这里保留彩色竖条（0.8.4 · 全库竖条政策）
+   本库整体立场是去掉纯装饰竖条（理由见 typography.css / form-validation.css）。
+   但**错误提示**是例外：竖条在这里承担的是**状态语义** ——
+   "这个字段错了"，与红色底色、`aria-invalid` 是同一份信息的三个出口
+   （视觉 / 颜色 / 无障碍）。
+   ⚠️ 和 form-validation 的区别：那里原本也是靠竖条提示错误，
+     被判为「理由对、手段错」⇒ 改用**图标**；这里保留是因为
+     它同时已有 `role="alert"` + `aria-invalid`，竖条只是**第三重冗余**，
+     拿掉之后单色 / 色弱用户仍可靠图标与 aria 察觉，
+     ⇒ 不构成"唯一信息出口"。 */
+.drange__error {
+  flex: 1 1 100%;
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sp-2);
+  padding: var(--sp-2) var(--sp-3);
+  background: var(--surface-sunken);
+  border-inline-start: 3px solid var(--danger);
+  border-radius: var(--r-sm);
+  color: var(--danger);
+  font-size: var(--fs-xs);
+  line-height: 1.5;
+}
+
+.drange__error[hidden] { display: none; }
+
+/* ---------- 摘要 ---------- */
+.drange__summary {
+  flex: 1 1 100%;
+  margin-top: var(--sp-2);
+  color: var(--text-secondary);
+  font-size: var(--fs-xs);
+}
+
+.drange__summary b {
+  font-family: var(--mono);
+  font-variant-numeric: tabular-nums;
+  color: var(--text-primary);
+}
+
+/* ---------- 清除按钮：44px 命中区 ---------- */
+.drange__clear {
+  flex: 0 0 auto;
+  min-height: 44px;
+  padding: 0 var(--sp-4);
+  background: var(--surface);
+  color: var(--text-secondary);
+  border: 1px solid var(--border-control);
+  border-radius: var(--r-sm);
+  font: inherit;
+  font-size: var(--fs-sm);
+  cursor: pointer;
+}
+
+.drange__clear:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+  outline-offset: var(--focus-ring-offset);
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .drange__clear:hover { background: var(--surface-sunken); color: var(--text-primary); }
+}
+
+.drange__clear[disabled] {
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);
+  cursor: not-allowed;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .drange * { transition: none; }
+}
+
+/* ---------- 禁用态（states 门禁要求：HIGH 级形态不能缺）---------- */
+.drange__input:disabled {
+  background: var(--surface-sunken);
+  border-color: var(--border-decor);
+  color: var(--text-tertiary);
+  cursor: not-allowed;
+  /* ⛔ 不写 opacity —— 那会把文字对比度一起拉低 */
+}
+
+.drange__input:disabled:focus-visible {
+  outline: none;          /* 禁用态不该有焦点环 */
+}
+
+.drange--disabled .drange__preset,
+.drange--disabled .drange__clear {
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);
+  border-color: var(--border-decor);
+  cursor: not-allowed;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .drange--disabled .drange__preset:hover,
+  .drange--disabled .drange__clear:hover {
+    background: var(--surface-sunken);
+    color: var(--text-tertiary);
+  }
+}

package/02-primitives/date-range/date-range.js

@@ -0,0 +1,301 @@
+/**
+ * date-range.js — 日期区间（E3 /
+ *
+ * 财务/成本场景刚需：看上季度、对比去年同期。
+ *
+ * ⭐ 三个关键点（最容易漏）：
+ *   ① **必须有「清除」**：日期填错了要能一键清空
+ *      ⇒ 没有它 = 用户只能一个个退格删
+ *   ② **约束校验**：开始晚于结束、超出 min/max ⇒ **明确报错**（不静默）
+ *   ③ **无障碍**：每个 input 有 label；错误用 role=alert 播报
+ *
+ * ⭐ 为什么**基于原生 `<input type="date">`** 而不是自建日历：
+ *   原生自带：触屏日历面板、本地化、键盘输入、无障碍语义。
+ *   自建日历要重做这一切，且在移动端体验更差。
+ *   （与 combobox 的取舍相反 —— 那里原生 select 无法定制样式。）
+ *
+ * 无依赖 · ES5
+ */
+(function (global) {
+  'use strict';
+  /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
+  var flEmit = function (el, name, detail) {
+    if (!el || !el.dispatchEvent) return null;
+    var type = name.indexOf('fl-') === 0 ? name : 'fl-' + name;
+    var ev = null;
+    /* 老 WebView 没有 CustomEvent 构造函数 ⇒ 兜底走 createEvent（理由见文件头）*/
+    if (typeof window.CustomEvent === 'function') {
+      try {
+        ev = new window.CustomEvent(type, {
+          detail: detail || null, bubbles: true, cancelable: false
+        });
+      } catch (e) { ev = null; }
+    }
+    if (!ev) {
+      try {
+        ev = document.createEvent('CustomEvent');
+        ev.initCustomEvent(type, true, false, detail || null);
+      } catch (e2) { return null; }
+    }
+    el.dispatchEvent(ev);
+    return ev;
+  };
+  /* ==== BEHAVIOR INJECT END: emit ==== */
+  /* ---- 旧环境兼容：Element.closest 在老 WebView 上不存在 ----
+     直接调用会在真机上抛 `is not a function`（本地完全正常，
+     只在老环境炸 —— 属静默失效）。这里做模块内兜底，
+     不污染全局，也不需要使用者额外引入 polyfill。 */
+  function closest(el, sel) {
+    if (!el) return null;
+    if (el.closest) return el.closest(sel);
+    while (el && el.nodeType === 1) {
+      if (elMatches(el, sel)) return el;
+      el = el.parentElement;
+    }
+    return null;
+  }
+  function elMatches(el, sel) {
+    var m = sel.match(/^([a-zA-Z][\w-]*)/);
+    if (m && el.tagName.toLowerCase() !== m[1].toLowerCase()) return false;
+    var cls = sel.match(/\.([\w-]+)/g);
+    if (cls) {
+      for (var i = 0; i < cls.length; i++) {
+        var c = cls[i].slice(1);
+        if ((' ' + (el.className || '') + ' ').indexOf(' ' + c + ' ') < 0) return false;
+      }
+    }
+    var id = sel.match(/#([\w-]+)/);
+    if (id && el.id !== id[1]) return false;
+    var at = sel.match(/\[([\w-]+)(?:=["']?([^\]"']*)["']?)?\]/);
+    if (at) {
+      var v = el.getAttribute(at[1]);
+      if (v === null) return false;
+      if (at[2] !== undefined && v !== at[2]) return false;
+    }
+    return true;
+  }
+
+  var uid = 0;
+
+  function iso(d) {
+    if (!d) return '';
+    var m = String(d).match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (m) return m[1] + '-' + m[2] + '-' + m[3];
+    var dt = new Date(d);
+    if (isNaN(dt)) return '';
+    function p(n) { return (n < 10 ? '0' : '') + n; }
+    return dt.getFullYear() + '-' + p(dt.getMonth() + 1) + '-' + p(dt.getDate());
+  }
+  function addDays(isoStr, n) {
+    var d = new Date(isoStr + 'T00:00:00');
+    d.setDate(d.getDate() + n);
+    return iso(d);
+  }
+  function addMonths(isoStr, n) {
+    var d = new Date(isoStr + 'T00:00:00');
+    var day = d.getDate();
+    d.setDate(1);
+    d.setMonth(d.getMonth() + n);
+    /* ⚠️ 月末溢出防护：1/31 加一个月不该变成 3/3 */
+    var last = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
+    d.setDate(Math.min(day, last));
+    return iso(d);
+  }
+  function quarterOf(date) {
+    var q = Math.floor(date.getMonth() / 3);
+    return { y: date.getFullYear(), q: q };
+  }
+  function quarterRange(y, q) {
+    /* 🔴 加防呆（ H5 的单测逼出来的）：
+       `q` 是 **0-based**（0=Q1），这是内部约定，但很容易被当成 1-based 用。
+       原来传 1 会**静默返回 Q2**（不报错）—— 正是本库最厌恶的那类失效。
+       ⇒ 越界直接抛错，让误用在第一次就暴露。 */
+    if (q !== 0 && q !== 1 && q !== 2 && q !== 3) {
+      throw new Error('DateRange.quarterRange: 季度必须是 0-3（0=Q1），收到 ' + q);
+    }
+    var start = new Date(y, q * 3, 1);
+    var end = new Date(y, q * 3 + 3, 0);      /* 该季度最后一天 */
+    return { from: iso(start), to: iso(end) };
+  }
+
+  function create(root, opt) {
+    opt = opt || {};
+    var from = root.querySelector('[data-dr-from]');
+    var to = root.querySelector('[data-dr-to]');
+    var errBox = root.querySelector('[data-dr-error]');
+    var summary = root.querySelector('[data-dr-summary]');
+    var clearBtn = root.querySelector('[data-dr-clear]');
+    if (!from || !to) throw new Error('DateRange: 缺少 [data-dr-from] / [data-dr-to]');
+
+    /* 约束：min/max 由调用方给（或默认放开）*/
+    if (opt.min) { from.min = opt.min; to.min = opt.min; }
+    if (opt.max) { from.max = opt.max; to.max = opt.max; }
+
+    function setError(msg) {
+      if (errBox) {
+        errBox.textContent = msg || '';
+        errBox.hidden = !msg;
+      }
+      /* ⭐ 错误要同时标记到具体字段 + 关联描述（读屏才知道哪个错了）*/
+      from.setAttribute('aria-invalid', msg ? 'true' : 'false');
+      to.setAttribute('aria-invalid', msg ? 'true' : 'false');
+      if (msg) {
+        var id = 'dr-err-' + (++uid);
+        errBox.id = id;
+        from.setAttribute('aria-describedby', id);
+        to.setAttribute('aria-describedby', id);
+      } else {
+        from.removeAttribute('aria-describedby');
+        to.removeAttribute('aria-describedby');
+      }
+    }
+
+    function days(fromS, toS) {
+      var a = new Date(fromS + 'T00:00:00'), b = new Date(toS + 'T00:00:00');
+      return Math.round((b - a) / 86400000) + 1;
+    }
+
+    function validate() {
+      var f = from.value, t = to.value;
+      if (!f && !t) { setError(''); paintSummary(''); return true; }
+      if (f && !t) { setError('请填写结束日期。'); return false; }
+      if (!f && t) { setError('请填写开始日期。'); return false; }
+      if (f > t) {
+        setError('开始日期不能晚于结束日期（当前：' + f + ' → ' + t + '）。');
+        return false;
+      }
+      if (opt.min && f < opt.min) { setError('开始日期不能早于 ' + opt.min + '。'); return false; }
+      if (opt.max && t > opt.max) { setError('结束日期不能晚于 ' + opt.max + '。'); return false; }
+      setError('');
+      paintSummary(f + ' → ' + t + '（' + days(f, t) + ' 天）');
+      return true;
+    }
+
+    function paintSummary(s) {
+      if (summary) summary.innerHTML = s ? ('区间 <b>' + s + '</b>') : '';
+    }
+
+    function emit() {
+      var ok = validate();
+      flEmit(root, 'fl-change',
+             { value: { from: from.value, to: to.value }, valid: ok });
+      if (opt.onChange) {
+        opt.onChange({ from: from.value, to: to.value, valid: ok }, ok);
+      }
+    }
+
+    /* ---------- 快捷区间 ---------- */
+    function bindPresets() {
+      var now = new Date();
+      var q = quarterOf(now);
+      var presets = [
+        { key: 'thisQ',  label: '本季度', range: function () { return quarterRange(q.y, q.q); } },
+        { key: 'lastQ',  label: '上季度',
+          range: function () { return q.q === 0 ? quarterRange(q.y - 1, 3) : quarterRange(q.y, q.q - 1); } },
+        { key: 'lastM',  label: '上月',
+          range: function () {
+            var m = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+            return { from: iso(m), to: iso(new Date(m.getFullYear(), m.getMonth() + 1, 0)) };
+          } },
+        { key: 'thisY',  label: '今年',
+          range: function () {
+            return { from: iso(new Date(now.getFullYear(), 0, 1)),
+                     to: iso(new Date(now.getFullYear(), 11, 31)) };
+          } },
+        { key: 'yoy',    label: '去年同期',
+          range: function () {
+            var y = now.getFullYear() - 1;
+            return { from: iso(new Date(y, 0, 1)), to: iso(new Date(y, 11, 31)) };
+          } },
+      ];
+      if (opt.presets) {
+        presets = presets.filter(function (x) { return opt.presets.indexOf(x.key) >= 0; });
+      }
+      var box = root.querySelector('[data-dr-presets]');
+      if (!box) return;
+      box.innerHTML = presets.map(function (p) {
+        return '<button class="drange__preset" type="button" aria-pressed="false" ' +
+               'data-dr-preset="' + p.key + '">' + p.label + '</button>';
+      }).join('');
+      box.addEventListener('click', function (e) {
+        /* 🔴 同样是"兜底永远跑不到"的死代码（与 combobox 同一处）：
+           `e.target.closest ? closest(...) : null` ⇒ 没有原生 closest 时返回 null。
+           直接调 `closest()`，它内部自己判 `el.closest` 在不在。 */
+        var b = closest(e.target, '[data-dr-preset]');
+        if (!b) return;
+        var p = presets.filter(function (x) { return x.key === b.getAttribute('data-dr-preset'); })[0];
+        if (!p) return;
+        var r = p.range();
+        from.value = r.from;
+        to.value = r.to;
+        /* ⭐ 标记哪个快捷项是"当前"的（aria-pressed，非仅颜色）*/
+        box.querySelectorAll('[data-dr-preset]').forEach(function (x) {
+          x.setAttribute('aria-pressed', x === b ? 'true' : 'false');
+        });
+        emit();
+      });
+    }
+    bindPresets();
+
+    /* ---------- 清除（① 最容易漏的）---------- */
+    if (clearBtn) {
+      clearBtn.addEventListener('click', function () {
+        from.value = '';
+        to.value = '';
+        var box = root.querySelector('[data-dr-presets]');
+        if (box) {
+          box.querySelectorAll('[data-dr-preset]').forEach(function (x) {
+            x.setAttribute('aria-pressed', 'false');
+          });
+        }
+        setError('');
+        paintSummary('');
+        emit();
+        from.focus();                     /* 清完把焦点放回开始日期 */
+      });
+    }
+
+    /* ---------- 手动改日期 ---------- */
+    [from, to].forEach(function (el) {
+      el.addEventListener('change', function () {
+        var box = root.querySelector('[data-dr-presets]');
+        if (box) {
+          box.querySelectorAll('[data-dr-preset]').forEach(function (x) {
+            x.setAttribute('aria-pressed', 'false');
+          });
+        }
+        emit();
+      });
+      el.addEventListener('input', emit);
+    });
+
+    /* ---------- 便捷 API ---------- */
+    function setRange(a, b2) {
+      from.value = iso(a);
+      to.value = iso(b2);
+      emit();
+    }
+
+    validate();
+    return {
+      get from() { return from.value; },
+      get to() { return to.value; },
+      get valid() { return !errBox || errBox.hidden; },
+      set: setRange,
+      setPreset: function (key) {
+        var b = root.querySelector('[data-dr-preset="' + key + '"]');
+        if (b) b.click();
+      },
+      clear: function () { if (clearBtn) clearBtn.click(); },
+    };
+  }
+
+  global.DateRange = {
+    create: create,
+    /* 🔴 补上 quarterOf（ H5 的单测抓出来的）：
+       它一直是**内部函数但没导出** ⇒ 使用者拿到 quarterRange 也无法
+       从任意日期反推季度号。纯函数，导出无害且有用。 */
+    iso: iso, addDays: addDays, addMonths: addMonths,
+    quarterOf: quarterOf, quarterRange: quarterRange,
+  };
+})(window);