iter(g50): 新增 datePicker 日期选择组件

2026-10-26 12:13:56 +08:00
parent e5c7778de5
commit e270e09903
12 changed files with 460 additions and 10 deletions
@@ -0,0 +1,150 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { Signal } from '@ui-arch/frame';
+import { pushOverlay } from './overlay.js';
+import { flip } from './position.js';
+import type { DatePickerProps } from './types.js';
+
+const pad = (n: number): string => String(n).padStart(2, '0'); // 两位补零
+const fmt = (y: number, m: number, d: number): string => `${y}-${pad(m + 1)}-${pad(d)}`; // 拼成 YYYY-MM-DD
+const parse = (s: string): [number, number, number] | null => {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+  return m ? [Number(m[1]), Number(m[2]) - 1, Number(m[3])] : null; // 非法串返回 null，调用方回落到今天
+};
+const today = (): [number, number, number] => {
+  const d = new Date();
+  return [d.getFullYear(), d.getMonth(), d.getDate()];
+};
+const shiftDay = (key: string, delta: number): string => {
+  const p = parse(key) ?? today();
+  const d = new Date(p[0], p[1], p[2] + delta);
+  return fmt(d.getFullYear(), d.getMonth(), d.getDate());
+};
+
+/*** 日期选择：单月网格 + 上下月翻页 + 今天快捷键，value 信号双向绑定，方向键/PageUp/PageDown 可导航 ***/ 
+export function datePicker(props: DatePickerProps): HTMLElement {
+  // —— 状态集中声明 ——
+  const value: Signal<string> = props.value ?? signal(''); // 已选日期
+  const open = signal(false);                             // 弹层开合
+  const place = signal<'top' | 'bottom'>('bottom');       // 实际方位
+  const initial = parse(value()) ?? today();              // 初始视图：跟随已选，否则今天
+  const view = signal<[number, number]>([initial[0], initial[1]]); // 当前展示的年月
+  const focus = signal<string>(value() || fmt(...today()));        // 键盘焦点日
+  let releaseEsc: (() => void) | null = null;             // Esc 栈注销函数
+
+  const grid = h('div', { class: 'ua-datepicker-grid', role: 'grid' }) as HTMLElement;
+  const label = h('span', { class: 'ua-datepicker-label' }) as HTMLElement;
+  const head = h(
+    'div',
+    { class: 'ua-datepicker-head' },
+    h('button', { type: 'button', class: 'ua-datepicker-nav', 'aria-label': '上一月', onClick: () => turn(-1) }, '‹'),
+    label,
+    h('button', { type: 'button', class: 'ua-datepicker-nav', 'aria-label': '下一月', onClick: () => turn(1) }, '›'),
+  );
+  const pop = h(
+    'div',
+    { class: () => `ua-datepicker-pop${open() ? ' ua-open' : ''}${place() === 'top' ? ' is-flip' : ''}` },
+    head,
+    h('div', { class: 'ua-datepicker-week' }, ...['日', '一', '二', '三', '四', '五', '六'].map((w) => h('span', {}, w))),
+    grid,
+    h('div', { class: 'ua-datepicker-foot' }, h('button', { type: 'button', class: 'ua-datepicker-today', onClick: () => commit(fmt(...today())) }, '今天')),
+  ) as HTMLElement;
+
+  /*** 翻月：只改视图，不改已选值；跨年自动进位 ***/
+  function turn(delta: number): void {
+    const [y, m] = view();
+    const d = new Date(y, m + delta, 1);
+    view([d.getFullYear(), d.getMonth()]);
+  }
+
+  /*** 提交：写值 + 回调 + 收起 + 焦点归还触发器 ***/
+  function commit(date: string): void {
+    value(date);
+    props.onChange?.(date);
+    open(false);
+    trigger.focus();
+  }
+
+  /*** 是否越界：min / max 为闭区间，缺省视为不限制 ***/
+  const outOfRange = (date: string): boolean => (props.min ? date < props.min : false) || (props.max ? date > props.max : false);
+
+  /*** 重绘网格：前置空位对齐星期、今天/选中/焦点分别打标 ***/
+  function render(): void {
+    const [y, m] = view();
+    const lead = new Date(y, m, 1).getDay();              // 当月 1 号是周几
+    const total = new Date(y, m + 1, 0).getDate();        // 当月天数
+    const cells: HTMLElement[] = [];
+    for (let i = 0; i < lead; i++) cells.push(h('span', { class: 'ua-datepicker-blank' })); // 月初留白
+    for (let d = 1; d <= total; d++) {
+      const date = fmt(y, m, d);
+      const dead = outOfRange(date);
+      const cls = `ua-datepicker-day${date === value() ? ' is-selected' : ''}${date === fmt(...today()) ? ' is-today' : ''}${dead ? ' is-disabled' : ''}`;
+      cells.push(
+        h('button', {
+          type: 'button',
+          class: cls,
+          role: 'gridcell',
+          tabindex: date === focus() ? '0' : '-1', // 漫游 tabindex：只有焦点日可 Tab 进入
+          'aria-selected': String(date === value()),
+          disabled: dead,
+          'aria-label': date,
+          onClick: () => commit(date),
+        }, String(d)),
+      );
+    }
+    grid.replaceChildren(...cells);
+    label.textContent = `${y} 年 ${m + 1} 月`;
+    requestAnimationFrame(() => {
+      if (!open()) return; // 卫语句：收起时不抢焦点
+      (grid.querySelector('.ua-datepicker-day[tabindex="0"]') as HTMLElement | null)?.focus();
+    });
+  }
+
+  const trigger = h(
+    'button',
+    {
+      type: 'button',
+      class: 'ua-datepicker-trigger',
+      'aria-haspopup': 'dialog',
+      'aria-expanded': () => String(open()),
+      disabled: props.disabled,
+      onClick: () => {
+        if (!open()) {
+          const p = parse(value()) ?? today(); // 打开时视图对准已选日期（无选则今天）
+          view([p[0], p[1]]);
+          focus(value() || fmt(...p));
+        }
+        open(!open());
+      },
+    },
+    h('span', { class: () => `ua-datepicker-value${value() ? '' : ' is-empty'}` }, () => value() || props.placeholder || '请选择日期'),
+    h('span', { class: 'ua-datepicker-caret', 'aria-hidden': 'true' }, '▤'),
+  );
+  const root = h('div', { class: () => `ua-datepicker${open() ? ' ua-open' : ''}` }, trigger, pop) as HTMLElement;
+
+  // 键盘：←→ 逐日、↑↓ 逐周、PageUp/PageDown 逐月、Enter 提交，Esc 交给弹层栈
+  pop.addEventListener('keydown', (e: KeyboardEvent) => {
+    const step: Record<string, number> = { ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7 };
+    if (step[e.key]) {
+      e.preventDefault();
+      const next = shiftDay(focus(), step[e.key]);
+      const p = parse(next) ?? today();
+      focus(next);
+      if (p[0] !== view()[0] || p[1] !== view()[1]) view([p[0], p[1]]); // 跨月自动翻页
+      render();
+      return;
+    }
+    if (e.key === 'PageUp' || e.key === 'PageDown') { e.preventDefault(); turn(e.key === 'PageUp' ? -1 : 1); return; }
+    if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); if (!outOfRange(focus())) commit(focus()); }
+  });
+  document.addEventListener('click', (e) => {
+    if (root.contains(e.target as Node)) return; // 卫语句：组件内点击不处理
+    open(false);
+  });
+  effect(render); // 依赖 view / value / focus
+  effect(() => {
+    if (open()) releaseEsc ??= pushOverlay(() => { open(false); trigger.focus(); }); // 入栈逐层关闭
+    else { releaseEsc?.(); releaseEsc = null; }
+  });
+  effect(() => { if (open()) place(flip(trigger, pop, 'bottom')); }); // 空间不足自动翻转
+  return root;
+}
@@ -48,3 +48,4 @@ export { transfer } from './transfer.js';
 export { cascader } from './cascader.js';
 export { splitter } from './splitter.js';
 export { autoComplete } from './autoComplete.js';
+export { datePicker } from './datePicker.js';
@@ -541,4 +541,14 @@ export interface AutoCompleteProps {
  onSelect?: (option: AutoCompleteOption) => void; // 选中回调（点击或 Enter）
 }

+/*** 日期选择入参 ***/
+export interface DatePickerProps {
+  value?: Signal<string>;                 // 选中日期（YYYY-MM-DD）；不传则内部维护
+  placeholder?: string;                   // 未选时占位文案；缺省「请选择日期」
+  min?: string;                           // 最早可选日期（含）；早于此的日置灰
+  max?: string;                           // 最晚可选日期（含）；晚于此的日置灰
+  disabled?: boolean | Signal<boolean>;   // 禁用触发器
+  onChange?: (date: string) => void;      // 选中回调（点击或 Enter）
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
@@ -62,7 +62,8 @@
      "transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选",
      "cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作",
      "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号",
-      "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想"
+      "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想",
+      "datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -2123,6 +2124,51 @@
          "options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组",
          "value 传信号即受控：外部写入会同步回填输入框内容"
        ]
+      },
+      {
+        "id": "datePicker",
+        "title": "日期选择 DatePicker",
+        "demo": "sec-datepicker",
+        "props": [
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "选中日期（YYYY-MM-DD）信号；不传则内部维护"
+          },
+          {
+            "n": "placeholder",
+            "t": "string",
+            "d": "未选时占位文案；缺省「请选择日期」"
+          },
+          {
+            "n": "min",
+            "t": "string",
+            "d": "最早可选日期（含，YYYY-MM-DD）；更早的日置灰不可点"
+          },
+          {
+            "n": "max",
+            "t": "string",
+            "d": "最晚可选日期（含，YYYY-MM-DD）；更晚的日置灰不可点"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean | Signal<boolean>",
+            "d": "禁用触发器"
+          },
+          {
+            "n": "onChange",
+            "t": "(date: string) => void",
+            "d": "选中回调（点击日期或 Enter）"
+          }
+        ],
+        "example": "datePicker({ value: dateVal, min: '2026-10-20', max: '2026-10-31', onChange: (d) => toast.success(d) })",
+        "steps": [
+          "点触发器展开当月网格，打开时视图自动对准已选日期（无选中则今天）",
+          "‹ › 翻月，底部「今天」一键跳今天并提交；今天用描边标记、选中用实心底色",
+          "键盘：←→ 逐日、↑↓ 逐周、PageUp/PageDown 逐月、Enter 提交，跨月会自动翻页",
+          "min / max 为闭区间，越界日期置灰不可点也不可键盘选中",
+          "value 传信号即受控；Esc 收起（与弹窗/抽屉共用逐层关闭栈）"
+        ]
      }
    ]
  }
@@ -2809,3 +2809,157 @@ button.ua-step-dot:hover {
  .ua-autocomplete-input,
  .ua-autocomplete-opt { transition: none; }
 }
+.ua-datepicker {
+  position: relative;
+  display: inline-block;
+  min-width: 200px;
+}
+.ua-datepicker-trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-1);
+  width: 100%;
+  padding: 8px var(--ua-space-2);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text);
+  background: var(--ua-color-surface);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  cursor: pointer;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-datepicker-trigger:hover {
+  border-color: var(--ua-color-accent);
+}
+.ua-datepicker-trigger:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.ua-datepicker.ua-open .ua-datepicker-trigger {
+  border-color: var(--ua-color-accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 18%, transparent);
+}
+.ua-datepicker-value.is-empty {
+  color: var(--ua-color-text-muted);
+}
+.ua-datepicker-caret {
+  font-size: 11px;
+  color: var(--ua-color-text-muted);
+}
+.ua-datepicker-pop {
+  position: absolute;
+  z-index: 40;
+  display: none;
+  width: 264px;
+  margin-top: 6px;
+  padding: var(--ua-space-2);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  box-shadow: 0 12px 28px rgba(0, 0, 0, 0.18);
+}
+.ua-datepicker-pop.ua-open {
+  display: block;
+  animation: ua-dp-in 0.15s ease both;
+}
+.ua-datepicker-pop.is-flip {
+  margin-top: 0;
+  margin-bottom: 6px;
+}
+.ua-datepicker-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-1);
+  margin-bottom: var(--ua-space-1);
+}
+.ua-datepicker-label {
+  font-size: var(--ua-font-size-sm);
+  font-weight: 600;
+  color: var(--ua-color-text);
+}
+.ua-datepicker-nav {
+  width: 24px;
+  height: 24px;
+  font-size: 14px;
+  line-height: 1;
+  color: var(--ua-color-text);
+  background: transparent;
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  cursor: pointer;
+  transition: border-color 0.15s ease, color 0.15s ease;
+}
+.ua-datepicker-nav:hover {
+  color: var(--ua-color-accent);
+  border-color: var(--ua-color-accent);
+}
+.ua-datepicker-week {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text-muted);
+  text-align: center;
+}
+.ua-datepicker-grid {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  gap: 2px;
+  margin-top: 2px;
+}
+.ua-datepicker-blank {
+  height: 28px;
+}
+.ua-datepicker-day {
+  height: 28px;
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text);
+  background: transparent;
+  border: none;
+  border-radius: var(--ua-radius-sm);
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+.ua-datepicker-day:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--ua-color-accent) 10%, transparent);
+}
+.ua-datepicker-day.is-today {
+  box-shadow: inset 0 0 0 1px var(--ua-color-accent);
+}
+.ua-datepicker-day.is-selected {
+  color: var(--ua-color-accent-contrast);
+  background: var(--ua-color-accent);
+  font-weight: 600;
+}
+.ua-datepicker-day:disabled {
+  opacity: 0.35;
+  cursor: not-allowed;
+}
+.ua-datepicker-day:focus-visible {
+  outline: 2px solid var(--ua-color-accent);
+  outline-offset: -2px;
+}
+.ua-datepicker-foot {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: var(--ua-space-1);
+}
+.ua-datepicker-today {
+  padding: 4px var(--ua-space-1);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-accent);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+}
+@keyframes ua-dp-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-datepicker-pop.ua-open { animation: none; }
+  .ua-datepicker-trigger,
+  .ua-datepicker-day,
+  .ua-datepicker-nav { transition: none; }
+}