@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/src/components/DateGrid/date-grid.stories.tsx

@@ -0,0 +1,195 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { zhTW } from 'date-fns/locale/zh-TW'
+import type { DateRange } from 'react-day-picker'
+import { DateGrid } from './date-grid'
+
+const meta: Meta = {
+  title: 'Design System/Internal/DateGrid/展示',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const Card = ({
+  title,
+  desc,
+  children,
+}: {
+  title: string
+  desc?: string
+  children: React.ReactNode
+}) => (
+  <div className="flex flex-col gap-3 mb-10">
+    <div className="flex flex-col gap-1">
+      <h3 className="text-body font-bold text-foreground">{title}</h3>
+      {desc && <p className="text-caption text-fg-muted max-w-[640px] leading-relaxed">{desc}</p>}
+    </div>
+    <div className="inline-flex bg-surface-raised border border-border rounded-lg p-4 w-fit">
+      {children}
+    </div>
+  </div>
+)
+
+const formatDate = (d: Date) =>
+  new Intl.DateTimeFormat('zh-TW', { year: 'numeric', month: 'short', day: 'numeric' }).format(d)
+
+const formatRange = (from?: Date, to?: Date) => {
+  if (!from) return '尚未選擇'
+  if (!to) return `${formatDate(from)} — 選擇結束日期`
+  return `${formatDate(from)} → ${formatDate(to)}`
+}
+
+// ── Stories ──────────────────────────────────────────────────────────────────
+
+/**
+ * Single mode — 生日 / 到期日等單日選擇(Google Calendar 新增事件日期、
+ * Stripe 發票到期日輸入)。最常用的 mode,DatePicker 消費此模式。
+ */
+export const Single: Story = {
+  name: '單日 — 生日 / 到期日',
+  render: () => {
+    const [date, setDate] = useState<Date | undefined>(new Date(1995, 5, 12))
+    return (
+      <div>
+        <Card
+          title="選擇生日"
+          desc="使用者設定頁填寫個人資料時的生日欄位,對標 Notion / Google Account。單日選擇,點新日取代舊選。"
+        >
+          <div className="flex flex-col gap-3">
+            <DateGrid
+              mode="single"
+              selected={date}
+              onSelect={setDate}
+              defaultMonth={date}
+              locale={zhTW}
+              autoFocus
+            />
+            <div className="text-caption text-fg-secondary px-1">
+              已選生日:<span className="font-medium text-foreground">{date ? formatDate(date) : '尚未選擇'}</span>
+            </div>
+          </div>
+        </Card>
+      </div>
+    )
+  },
+}
+
+/**
+ * Multiple mode — event 報名多日(Luma RSVP 活動可參加日、
+ * Notion project 可用日標記)。不連續多選。
+ */
+export const Multiple: Story = {
+  name: '多日 — 活動可參加日期',
+  render: () => {
+    const today = new Date()
+    const [dates, setDates] = useState<Date[]>([
+      new Date(today.getFullYear(), today.getMonth(), 8),
+      new Date(today.getFullYear(), today.getMonth(), 15),
+      new Date(today.getFullYear(), today.getMonth(), 22),
+    ])
+    return (
+      <div>
+        <Card
+          title="活動可參加日期"
+          desc="參考 Luma / Calendly — 受邀者勾選所有能參加的日期,主辦方彙整後決定最終日期。不連續多選,點已選日即取消。"
+        >
+          <div className="flex flex-col gap-3">
+            <DateGrid
+              mode="multiple"
+              selected={dates}
+              onSelect={(d) => setDates(d ?? [])}
+              defaultMonth={today}
+              locale={zhTW}
+            />
+            <div className="text-caption text-fg-secondary px-1">
+              已選 <span className="font-medium text-foreground">{dates.length}</span> 天:
+              <span className="ml-1 text-fg-secondary">
+                {dates.length ? dates.map(formatDate).join('、') : '尚未選擇'}
+              </span>
+            </div>
+          </div>
+        </Card>
+      </div>
+    )
+  },
+}
+
+/**
+ * Range mode — 訂單日期範圍(Stripe dashboard 分析時段、
+ * Vercel Analytics 報表期間、Airbnb 訂房 check-in/check-out)。
+ */
+export const Range: Story = {
+  name: '範圍 — 分析時段 / 訂單範圍',
+  render: () => {
+    const today = new Date()
+    const [range, setRange] = useState<DateRange | undefined>({
+      from: new Date(today.getFullYear(), today.getMonth(), 1),
+      to: new Date(today.getFullYear(), today.getMonth(), 14),
+    })
+    return (
+      <div>
+        <Card
+          title="營收報表時段"
+          desc="參考 Stripe Dashboard / Vercel Analytics — 選擇查詢的起訖日。第一次點擊設起日,第二次點擊設迄日,中間自動填滿。"
+        >
+          <div className="flex flex-col gap-3">
+            <DateGrid
+              mode="range"
+              selected={range}
+              onSelect={setRange}
+              defaultMonth={range?.from ?? today}
+              locale={zhTW}
+              numberOfMonths={2}
+            />
+            <div className="text-caption text-fg-secondary px-1">
+              查詢範圍:<span className="font-medium text-foreground">{formatRange(range?.from, range?.to)}</span>
+            </div>
+          </div>
+        </Card>
+      </div>
+    )
+  },
+}
+
+/**
+ * Inline widget — 直接嵌在 dashboard card 內(Linear project deadline widget、
+ * Notion sidebar 行事曆小卡)。不透過 popup,頁面常駐顯示。
+ */
+export const Inline: Story = {
+  name: '行內 — 儀表板小卡',
+  render: () => {
+    const today = new Date()
+    const [deadline, setDeadline] = useState<Date | undefined>(
+      new Date(today.getFullYear(), today.getMonth() + 1, 5),
+    )
+    return (
+      <div>
+        <Card
+          title="專案截止日 widget"
+          desc="參考 Linear / Height — 專案側欄的 deadline 選擇器,常駐顯示不需點開浮層。Calendar 是 inline primitive,不自包 Popover。"
+        >
+          <div className="flex flex-col gap-3 w-fit">
+            <div className="flex items-center justify-between px-1">
+              <span className="text-caption text-fg-muted">Project deadline</span>
+              <span className="text-caption font-medium text-foreground">
+                {deadline ? formatDate(deadline) : '未設定'}
+              </span>
+            </div>
+            <DateGrid
+              mode="single"
+              selected={deadline}
+              onSelect={setDeadline}
+              defaultMonth={deadline ?? today}
+              locale={zhTW}
+              disabled={{ before: today }}
+            />
+          </div>
+        </Card>
+      </div>
+    )
+  },
+}

package/src/components/DateGrid/date-grid.tsx

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 DatePicker wrap 消費,end-user app 請用 wrapper 元件。
+ */
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 // M22 retrofit DONE 2026-05-03 v11(real source URLs added inline at lines 38 + 111)
 import * as React from 'react'
@@ -17,34 +21,34 @@ import { Button } from '@/design-system/components/Button/button'
  * |------|------|
  * | Outer padding | `p-3`(12px 四邊對稱) |
  * | Nav + Month caption row | h-field-xs(24px)單行,chevron(xs)分居左右 / 月份置中垂直對齊 |
- * | Nav → Weekday gap | 12px(mt-3) |
- * | Weekday | text-body(14px)text-fg-secondary(neutral-8) |
+ * | Nav → Weekday gap | 12px(month_caption mb-3) |
+ * | Weekday | text-body(14px)text-foreground font-medium(neutral-9,同 caption 權重;撤銷 v3 fg-secondary) |
  * | Cell gap(水平 + 垂直)| 4px(gap-1) |
- * | Day cell size | h-field-md w-field-height-md(32×32 md / 36×36 lg) |
+ * | Day cell size | h-field-sm w-[var(--field-height-sm)](28×28 md / 32×32 lg) |
  * | Day button | rounded-full 填滿 cell |
  *
  * ── 五種 cell state canonical ──
  *
  * | State | 視覺 | Token |
  * |-------|------|-------|
- * | today | 文字下方藍色底線 | underline decoration-primary decoration-2 underline-offset-4 |
+ * | today | 數字下方藍色短桿 | `::after` pseudo bar(bg-primary,w-40% h-1.5px rounded-full,貼近數字底)|
  * | disabled | 灰底圓圈 + disabled 字色(跟 Button disabled 一致) | [&>button]:bg-disabled [&>button]:text-fg-disabled rounded-full |
  * | outside(非本月) | text-fg-muted(neutral-7) | [&>button]:text-fg-muted |
  * | selected / range 端點 | 藍底白字圓 | [&>button]:bg-primary [&>button]:text-on-emphasis rounded-full |
- * | range middle | 灰底矩形 track(neutral-3),**高度 = button 高度**(28×28 @ md) | before pseudo: `inset-y-0.5 inset-x-0` |
- * | range start/end 半圓 track | 左/右半圓 + selected 圓疊在上,**圓半徑 = button 半徑** | before pseudo: `rounded-l/r-full` 加 `left-0.5` / `right-0.5` |
- * | hover(未選中) | 藍圈 outline | hover:ring-1 hover:ring-primary |
+ * | range middle | 灰底矩形 track(bg-neutral-selected = neutral-2),**高度 = cell 高度**(28×28 @ md) | before pseudo: `inset-y-0 -inset-x-[2px]` |
+ * | range start/end 半圓 track | 左/右半圓 + selected 圓疊在上,**圓半徑 = button 半徑** | before pseudo: `rounded-l/r-full` + start `left-0 -right-[2px]` / end `-left-[2px] right-0`(向 middle 外擴 2px bridge gap)|
+ * | hover(未選中) | 藍圈 outline | hover:ring-[1.5px] hover:ring-primary |
  *
- * ── Range track 高度 canonical(2026-05-02 Q8 修正,M8 4 家對照)──
+ * ── Range track 高度 canonical(2026-05-03 v6,M8 4 家對照)──
  * Ant Design([picker source](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts))/ Material X DateRangePicker([mui-x source](https://github.com/mui/mui-x/tree/master/packages/x-date-pickers-pro/src/DateRangeCalendar))/ Apple Calendar `@benchmark-unverified`(closed-source)/ Google Calendar `@benchmark-unverified`(closed-source)共識:
- * **range track 高度 = button 高度**(不是 cell 高度)— track 跟 selected 圓緊貼,
- * 不留 2px「fat」邊距(舊版 cell-level bg 在 button 上下留 2px 空白看起來「胖」)。
- * 實作:bg 走 `before:` pseudo 走 `inset-y-0.5`(top/bottom 2px 內縮),`inset-x-0`
- * 維持完整 cell 寬度 → 相鄰 cell 的 pseudo 在 cell 邊界相接 = 橫向連貫。
+ * **range track 為連續 stadium**,跟 selected 圓緊貼成連續 pill。
+ * 實作:bg 走 `before:` pseudo 用 `inset-y-0`(滿 cell 高度)+ `-inset-x-[2px]`
+ * (左右各外擴 2px bridge 相鄰 cell gap)→ 相鄰 cell 的 pseudo 連續銜接 = 橫向連貫;
+ * day cell 本身就是 button 容器(L102-105 day = h-field-sm cell),故滿 cell 高 = 滿 button 高。
  *
- * ── 為什麼 neutral-3 不 neutral-2(AR 新版 canonical)──
- * neutral-2 在 light mode 太淡(OKLCH L≈0.97),range track 跟 white bg 幾乎無對比。
- * neutral-3(L≈0.94-0.95)在 Google / Ant / Apple DateRange track 視覺明顯,維持「可見 track」。
+ * ── Range track 色用 bg-neutral-selected(= neutral-2)──
+ * 對齊 TimePicker 選中項目樣式(semantic `--neutral-selected` = neutral-2,semantic.css L84/L340)。
+ * 同 DS 內「持續選中」語意 token,不自開 neutral-3 tier。
  *
  * ── 為什麼 nav 放頂部 + 年月垂直置中(不 separate 兩行)──
  * ref/datepicker.png:chevron prev / 月份 / chevron next 同一行,24px 高(xs field height)。
@@ -68,7 +72,7 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
   return (
     <DayPicker
       showOutsideDays={showOutsideDays}
-      // navLayout="around" = 每個 month caption 兩側渲染 prev / next 按鈕(inline row)
+      // navLayout="around" = prev 渲染在首月(displayIndex===0)caption 左、next 渲染在末月(displayIndex===numberOfMonths-1)caption 右;單月時兩鍵同 caption 兩側
       // 取代先前 absolute 定位覆蓋整個 months 容器導致箭頭垂直置中於中段的 bug
       navLayout="around"
       // p-3 = 12px 四邊對稱(canonical 不可動)
@@ -200,8 +204,8 @@ export const dateGridMeta = {
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-disabled', 'bg-neutral-hover', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],
-    fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
+    bg: ['bg-disabled', 'bg-neutral-selected', 'bg-on-emphasis', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],
+    fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground', 'text-on-emphasis'],
     ring: ['ring-primary', 'ring-ring'],
   },
 } as const

package/src/components/DateGrid/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './date-grid'