@suphark/ui 0.40.1 → 0.42.0

package/CHANGELOG.md

@@ -2,7 +2,34 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
-## [0.40.1] — 2026-10-07
+## [0.42.0] — 2026-10-07
+
+### Added
+
+- **`DatePicker` พิมพ์ลัด** (เจ้าของขอ): `t` = วันนี้, `t+3` / `t+3d` = อีก 3 วัน, `t-2` = 2 วันก่อน, `t+2w` สัปดาห์, `t+1m` เดือน, `t+1y` ปี (`today`/`วันนี้` และหน่วยไทย วัน/สัปดาห์/เดือน/ปี ก็ได้; ปลายเดือนตัดให้อยู่ในเดือนถัดไปแบบ date-fns) · ช่วง: `t-7..t`, `t ~ t+1m`, `t ถึง t+3` — ใช้ได้กับ `parseSmartDateInput` / `parseSmartDateRange` ทุกที่ (รวม `FormFieldDate`)
+- ปุ่ม (i) ท้ายช่องพิมพ์ เปิดตารางวิธีพิมพ์ในกล่องเดียวกัน (ไม่ใช่ tooltip — popup ซ้อน popup และจอสัมผัสเปิด tooltip ไม่ได้) · ข้อความจาก `UiText.datePicker.help*`
+
+### Changed
+
+- **เลิกปุ่มทางลัด** (วันนี้/พรุ่งนี้/+1 สัปดาห์ …) ทั้งแบบวันเดียวและช่วง — ใช้การพิมพ์ลัดแทนเพื่อลดพื้นที่ · `showPresets` ยังรับได้แต่ไม่มีผล (deprecated)
+- ช่วงวันที่: **ไม่ใส่ปี = ปีปัจจุบันเสมอ** (0.41.0 ยืมปีจากฝั่งขวา)
+- placeholder ช่องพิมพ์: "เช่น 15/3, t+3, t+1m" / ช่วง "เช่น 1/7-5/7, t-7..t"
+
+## [0.41.0] — 2026-10-07
+
+> ประกาศพร้อม publish แล้ว แต่ยังไม่ขึ้น npm — รวมอยู่ใน 0.42.0
+
+
+### Added
+
+- **`DatePicker mode="range"` — เลือกช่วงวันที่** (เจ้าของขอ): คลิกวันเริ่มแล้ววันสุดท้าย (มีบรรทัดบอก "เลือกวันสุดท้ายของช่วง" ระหว่างเลือก) หรือพิมพ์ **"1/7-5/7" = 1–5 ก.ค.** · รองรับ "1-5/7", "1/7 - 5/8/68", "1/7 ถึง 5/7", "1/7 to 5/7", "1/7–5/7" · ปีที่ไม่ได้พิมพ์ฝั่งซ้ายใช้ปีฝั่งขวา · ใส่กลับด้านแล้วสลับให้ · "1-7-2568" ยังเป็นวันเดียวเหมือนเดิม (`-` เป็นตัวคั่นช่วงเมื่อมี `/` หรือ `.`)
+  - แสดงด้วย `Intl.DateTimeFormat#formatRange` ตาม `locale`: "1–5 ก.ค. 2569" / en-GB "1–5 Jul 2026"
+  - ทางลัดของช่วง: วันนี้, 7/30 วันล่าสุด, เดือนนี้, เดือนที่แล้ว, 7/30 วันข้างหน้า
+  - ฟอร์ม: `name={["from", "to"]}` ส่ง `YYYY-MM-DD` สองช่อง (ใช้กับ `<form method="get">` ของตัวกรองได้ตรง ๆ) + `required` · `value`/`defaultValue` = `{ from, to }` (Date หรือ "YYYY-MM-DD") · `onChange(range | null)`
+- `parseSmartDateRange(input)` · types `DatePickerRange`, `DatePickerSingleProps`, `DatePickerRangeProps` (`DatePickerProps` เป็น union — ของเดิมที่ไม่ส่ง `mode` ใช้ได้เหมือนเดิม)
+- `UiText.datePicker`: `rangePlaceholder`, `rangeSmartPlaceholder`, `pickEnd`, ทางลัดของช่วง
+- showcase: `/components/date-picker` เพิ่มตัวอย่างช่วงวันที่
+
 
 ### Fixed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "private": false,
   "type": "module",
   "description": "Design system กลางของ Suphark apps: shadcn/ui (base-nova, Base UI, Tailwind v4) + shared components + token/ฟอนต์ Noto Sans Thai Looped — ส่งเป็น source ให้แอป Next transpile เอง",

package/src/components/shared/date/date-picker.tsx

@@ -13,8 +13,8 @@ import { Popover, PopoverContent, PopoverTrigger } from "@suphark/ui/components/
 import { useMounted } from "@suphark/ui/hooks/use-mounted";
 import { formatRelativeThaiDate, formatThaiFullDate } from "@suphark/ui/lib/formatters";
 import { cn } from "@suphark/ui/lib/utils";
-import { addDays, addMonths, addWeeks, subDays, subMonths, subWeeks } from "date-fns";
-import { CalendarIcon, Check, Clock, X } from "lucide-react";
+import { addDays, addMonths, addWeeks, addYears } from "date-fns";
+import { CalendarIcon, Check, InfoIcon, X } from "lucide-react";
 import { useMemo, useState } from "react";
 
 /**
@@ -27,6 +27,8 @@ import { useMemo, useState } from "react";
 export function parseSmartDateInput(input: string): Date | null {
   if (!input?.trim()) return null;
   const clean = input.trim().replace(/\s+/g, "");
+  const shortcut = parseDateShortcut(clean);
+  if (shortcut) return shortcut;
 
   const parts = clean.split(/[/\-.]/);
   if (parts.length < 2 || parts.length > 3) return null;
@@ -66,6 +68,63 @@ export function parseSmartDateInput(input: string): Date | null {
   return null;
 }
 
+/**
+ * ตัวย่อวันที่: `t` = วันนี้ · `t+3` / `t+3d` = อีก 3 วัน · `t-2` = 2 วันก่อน · `t+2w` สัปดาห์ · `t+1m` เดือน · `t+1y` ปี
+ * (`today` / `วันนี้` แทน `t` ได้, หน่วยไทย วัน/สัปดาห์/เดือน/ปี ก็ได้)
+ */
+function parseDateShortcut(clean: string): Date | null {
+  const match = /^(?:t|today|วันนี้)(?:([+-])(\d{1,4})(d|w|m|y|วัน|สัปดาห์|อาทิตย์|เดือน|ปี)?)?$/i.exec(
+    clean,
+  );
+  if (!match) return null;
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  if (!match[1]) return today;
+  const amount = Number(match[2]) * (match[1] === "-" ? -1 : 1);
+  switch ((match[3] ?? "d").toLowerCase()) {
+    case "w":
+    case "สัปดาห์":
+    case "อาทิตย์":
+      return addWeeks(today, amount);
+    case "m":
+    case "เดือน":
+      return addMonths(today, amount);
+    case "y":
+    case "ปี":
+      return addYears(today, amount);
+    default:
+      return addDays(today, amount);
+  }
+}
+
+/**
+ * พิมพ์ช่วงวันที่: "1/7-5/7" (1–5 ก.ค.), "1-5/7", "1/7 - 5/8/68", "1/7 ถึง 5/7", "1/7 to 5/7", "1/7–5/7",
+ * ตัวย่อ "t-7..t", "t ~ t+1m" · ไม่ได้พิมพ์ปี = ปีปัจจุบัน · ใส่กลับด้านได้ (สลับให้)
+ * `-` เป็นตัวคั่นช่วงเมื่อมี `/` หรือ `.` อยู่ด้วยเท่านั้น ("1-7-2568" และ "t-3" ยังเป็นวันเดียว) — ตัวย่อใช้ `..`/`~`/`ถึง`/`to`
+ */
+export function parseSmartDateRange(input: string): { from: Date; to: Date } | null {
+  const raw = input?.trim();
+  if (!raw) return null;
+  let parts = raw.split(/\s*(?:–|—|~|\.\.|ถึง|\bto\b)\s*|\s+-\s+/i).filter((p) => p.trim() !== "");
+  if (parts.length !== 2) {
+    const dashes = raw.split("-");
+    if (dashes.length !== 2 || !/[/.]/.test(raw)) return null;
+    parts = dashes;
+  }
+  const left = (parts[0] ?? "").trim();
+  const right = (parts[1] ?? "").trim();
+  const to = parseSmartDateInput(right);
+  if (!to) return null;
+  let from = parseSmartDateInput(left);
+  if (!from) {
+    // "1-5/7" → ฝั่งซ้ายมีแค่วัน ใช้เดือน/ปีของฝั่งขวา
+    if (!/^\d{1,2}$/.test(left)) return null;
+    from = new Date(to.getFullYear(), to.getMonth(), Number(left));
+    if (from.getMonth() !== to.getMonth()) return null;
+  }
+  return from.getTime() <= to.getTime() ? { from, to } : { from: to, to: from };
+}
+
 type DateInput = Date | string | number | null | undefined;
 
 /**
@@ -107,18 +166,8 @@ function formatRelative(date: Date, locale: string | undefined): string {
   return new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(days, "day");
 }
 
-export interface DatePickerProps {
+interface DatePickerBaseProps {
   id?: string;
-  /** ควบคุมจากภายนอก (`"YYYY-MM-DD"` อ่านเป็นวันที่ local) — ใช้แบบไม่ควบคุมให้ส่ง `defaultValue` แทน */
-  value?: DateInput;
-  /** ค่าเริ่มต้นแบบไม่ควบคุม (ใช้คู่ `name` ใน `<form action>`) — `null` = เริ่มว่าง */
-  defaultValue?: DateInput;
-  onChange?: (date: Date | null) => void;
-  /**
-   * ชื่อฟิลด์ในฟอร์ม — ส่งค่า `YYYY-MM-DD` (วันที่ local) ไปกับ FormData ของ `<form action>`/server action
-   * ว่าง = ส่ง `""`
-   */
-  name?: string;
   /** ต้องเลือกวันที่ก่อนส่งฟอร์ม — ไม่เลือกแล้วกดส่ง เบราว์เซอร์บล็อกและตาข่ายฟอร์มบอกชื่อช่องให้ */
   required?: boolean;
   /**
@@ -131,13 +180,86 @@ export interface DatePickerProps {
   disabled?: boolean;
   className?: string;
   allowClear?: boolean;
+  /** @deprecated 0.42.0 — ปุ่มทางลัดถูกแทนด้วยการพิมพ์ลัด (`t`, `t+3`, `t+1m` …) ใส่ได้แต่ไม่มีผล */
   showPresets?: boolean;
   showSmartInput?: boolean;
+}
+
+export interface DatePickerSingleProps extends DatePickerBaseProps {
+  /** `"single"` (ค่าเริ่มต้น) = วันเดียว · `"range"` = ช่วงวันที่ */
+  mode?: "single";
+  /** ควบคุมจากภายนอก (`"YYYY-MM-DD"` อ่านเป็นวันที่ local) — ใช้แบบไม่ควบคุมให้ส่ง `defaultValue` แทน */
+  value?: DateInput;
+  /** ค่าเริ่มต้นแบบไม่ควบคุม (ใช้คู่ `name` ใน `<form action>`) — `null` / `""` = เริ่มว่าง */
+  defaultValue?: DateInput;
+  onChange?: (date: Date | null) => void;
+  /**
+   * ชื่อฟิลด์ในฟอร์ม — ส่งค่า `YYYY-MM-DD` (วันที่ local) ไปกับ FormData ของ `<form action>`/server action
+   * ว่าง = ส่ง `""`
+   */
+  name?: string;
   /** แสดงวันที่สัมพัทธ์ต่อท้าย เช่น "(พรุ่งนี้)" — ค่าเริ่มต้น true */
   showRelative?: boolean;
 }
 
-export function DatePicker({
+/** ช่วงวันที่ — ทั้งสองฝั่งรวมวันนั้นด้วย (`to` = วันสุดท้ายของช่วง) */
+export interface DatePickerRange {
+  from: Date;
+  to: Date;
+}
+
+export interface DatePickerRangeProps extends DatePickerBaseProps {
+  mode: "range";
+  /** ควบคุมจากภายนอก — แต่ละฝั่งรับ Date หรือ `"YYYY-MM-DD"` · `null` = ว่าง */
+  value?: { from: DateInput; to: DateInput } | null;
+  /** ค่าเริ่มต้นแบบไม่ควบคุม (ใช้คู่ `name`) */
+  defaultValue?: { from: DateInput; to: DateInput } | null;
+  onChange?: (range: DatePickerRange | null) => void;
+  /**
+   * ชื่อฟิลด์สองช่อง `[ชื่อวันเริ่ม, ชื่อวันสุดท้าย]` เช่น `["from", "to"]` — ส่ง `YYYY-MM-DD` แยกกัน
+   * (ใช้กับ `<form method="get">` ของตัวกรองได้ตรง ๆ) · ว่าง = `""` ทั้งคู่
+   */
+  name?: [string, string];
+}
+
+export type DatePickerProps = DatePickerSingleProps | DatePickerRangeProps;
+
+/**
+ * เลือกวันที่ — วันเดียว (ค่าเริ่มต้น) หรือ `mode="range"` เป็นช่วง (คลิกวันเริ่มแล้ววันสุดท้าย
+ * หรือพิมพ์ "1/7-5/7") · พิมพ์ "15/3", "15/3/69" ได้ · มีทางลัด · ใช้ในฟอร์มด้วย `name`
+ */
+export function DatePicker(props: DatePickerProps) {
+  return props.mode === "range" ? <RangeDatePicker {...props} /> : <SingleDatePicker {...props} />;
+}
+
+/** ช่องที่มองไม่เห็นสำหรับส่งค่าไปกับฟอร์ม — ไม่ใช้ type="hidden" เพราะ hidden ไม่ถูกตรวจ `required` */
+function FormValue({
+  name,
+  value,
+  required,
+  disabled,
+}: {
+  name: string;
+  value: string;
+  required: boolean;
+  disabled: boolean;
+}) {
+  // อยู่หลังปุ่มเสมอ: label ที่ครอบ (LabeledField) คลิกแล้วไปที่ปุ่ม ไม่ใช่ช่องนี้ · ตาข่ายฟอร์มอ่านชื่อจาก label เดียวกัน
+  return (
+    <input
+      name={name}
+      value={value}
+      onChange={() => {}}
+      required={required}
+      disabled={disabled}
+      tabIndex={-1}
+      aria-hidden
+      className="sr-only"
+    />
+  );
+}
+
+function SingleDatePicker({
   id,
   value,
   defaultValue,
@@ -149,10 +271,9 @@ export function DatePicker({
   disabled = false,
   className,
   allowClear = true,
-  showPresets = true,
   showSmartInput = true,
   showRelative = true,
-}: DatePickerProps) {
+}: DatePickerSingleProps) {
   const text = useUiText().datePicker;
   const mounted = useMounted();
   const [open, setOpen] = useState(false);
@@ -177,12 +298,6 @@ export function DatePicker({
     setSmartText("");
   };
 
-  const applyPreset = (date: Date | null) => {
-    change(date);
-    setOpen(false);
-    setSmartText("");
-  };
-
   const handleSmartSubmit = () => {
     if (parsedSmartDate) {
       change(parsedSmartDate);
@@ -191,17 +306,7 @@ export function DatePicker({
     }
   };
 
-  const today = new Date();
   const displayMonth = parsedSmartDate || selectedDate;
-  const presets: Array<[string, Date]> = [
-    [text?.today ?? "วันนี้", today],
-    [text?.yesterday ?? "เมื่อวาน", subDays(today, 1)],
-    [text?.tomorrow ?? "พรุ่งนี้", addDays(today, 1)],
-    [text?.nextWeek ?? "+1 สัปดาห์", addWeeks(today, 1)],
-    [text?.lastWeek ?? "-1 สัปดาห์", subWeeks(today, 1)],
-    [text?.nextMonth ?? "+1 เดือน", addMonths(today, 1)],
-    [text?.lastMonth ?? "-1 เดือน", subMonths(today, 1)],
-  ];
   // ปฏิทินใช้ locale เดียวกับช่อง (ชื่อเดือน/วัน/ปี) — ไม่ส่ง locale = ค่าเดิมของ Calendar
   const calendarFormatters = locale
     ? {
@@ -279,66 +384,15 @@ export function DatePicker({
         </PopoverTrigger>
         {/* กว้างพอดีปฏิทิน: ช่องวันที่ 40px × 7 + p-3 + ขอบ (เดิมกล่อง 320–340px แต่ช่อง 28px → ว่างซ้ายขวามาก) */}
         <PopoverContent className="w-[306px] border bg-background p-3 shadow-xl" align="start">
-          {/* Smart Date Text Input */}
           {showSmartInput && (
-            <div className="mb-3 flex flex-col gap-1.5 border-b pb-2.5">
-              <InputGroup className="h-8">
-                <InputGroupInput
-                  value={smartText}
-                  onChange={(e) => setSmartText(e.target.value)}
-                  onKeyDown={(event) => {
-                    if (event.key === "Enter") {
-                      event.preventDefault();
-                      event.stopPropagation();
-                      handleSmartSubmit();
-                    }
-                  }}
-                  placeholder={text?.smartPlaceholder ?? "เช่น 1/7, 1/7/25, 1-7-2568..."}
-                  className="h-8 text-xs"
-                />
-                <InputGroupAddon align="inline-end">
-                  <InputGroupButton
-                    type="button"
-                    variant="default"
-                    size="xs"
-                    onClick={handleSmartSubmit}
-                    disabled={!parsedSmartDate}
-                  >
-                    {text?.apply ?? "ตกลง"}
-                  </InputGroupButton>
-                </InputGroupAddon>
-              </InputGroup>
-              {parsedSmartDate && (
-                <span className="flex items-center gap-1 font-medium text-success text-xs">
-                  <Check className="size-3" />
-                  {formatDate(parsedSmartDate, locale)}
-                </span>
-              )}
-            </div>
-          )}
-
-          {/* Quick Presets Section (Flex Wrap & Clean Spacing) */}
-          {showPresets && (
-            <div className="mb-3 border-b pb-2.5">
-              <div className="mb-1.5 flex items-center gap-1 font-semibold text-muted-foreground text-xs">
-                <Clock className="h-3 w-3" />
-                {text?.presets ?? "ทางลัด"}
-              </div>
-              <div className="flex flex-wrap items-center gap-1.5">
-                {presets.map(([label, date]) => (
-                  <Button
-                    key={label}
-                    type="button"
-                    variant="outline"
-                    size="sm"
-                    className="h-6 px-2 font-normal text-xs hover:bg-muted"
-                    onClick={() => applyPreset(date)}
-                  >
-                    {label}
-                  </Button>
-                ))}
-              </div>
-            </div>
+            <SmartInput
+              value={smartText}
+              onChange={setSmartText}
+              onSubmit={handleSmartSubmit}
+              preview={parsedSmartDate ? formatDate(parsedSmartDate, locale) : null}
+              placeholder={text?.smartPlaceholder ?? "เช่น 15/3, t+3, t+1m"}
+              range={false}
+            />
           )}
 
           {/* Visual DayPicker Calendar */}
@@ -359,19 +413,290 @@ export function DatePicker({
         </PopoverContent>
       </Popover>
       {name !== undefined && (
-        // ค่าที่ส่งไปกับฟอร์ม — ใช้ input ข้อความที่มองไม่เห็นแทน type="hidden" เพราะ hidden ไม่ถูกตรวจ `required`
-        // อยู่หลังปุ่มเสมอ: label ที่ครอบ (LabeledField) คลิกแล้วไปที่ปุ่ม ไม่ใช่ช่องนี้ · ตาข่ายฟอร์มอ่านชื่อจาก label เดียวกัน
-        <input
+        <FormValue
           name={name}
           value={toDateInputValue(selectedDate)}
-          onChange={() => {}}
           required={required}
           disabled={disabled}
-          tabIndex={-1}
-          aria-hidden
-          className="sr-only"
         />
       )}
     </>
   );
 }
+
+/** "1 – 5 ก.ค. 2569" / "1–5 Jul 2026" — ใช้ formatRange ของ Intl (ย่อเดือน/ปีที่ซ้ำให้เอง) */
+function formatRange(range: DatePickerRange, locale: string | undefined): string {
+  const fmt = new Intl.DateTimeFormat(locale ?? "th-TH", {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+  });
+  return fmt.formatRange(range.from, range.to);
+}
+
+function toRange(value: { from: DateInput; to: DateInput } | null | undefined) {
+  const from = toDate(value?.from);
+  const to = toDate(value?.to);
+  if (!from || !to) return undefined;
+  return from.getTime() <= to.getTime() ? { from, to } : { from: to, to: from };
+}
+
+function RangeDatePicker({
+  id,
+  value,
+  defaultValue,
+  onChange,
+  name,
+  required = false,
+  locale,
+  placeholder,
+  disabled = false,
+  className,
+  allowClear = true,
+  showSmartInput = true,
+}: DatePickerRangeProps) {
+  const text = useUiText().datePicker;
+  const [open, setOpen] = useState(false);
+  const [smartText, setSmartText] = useState("");
+  const controlled = value !== undefined || (defaultValue === undefined && onChange !== undefined);
+  const [own, setOwn] = useState<DatePickerRange | null>(() => toRange(defaultValue) ?? null);
+  // ระหว่างคลิกเลือก: คลิกแรก = วันเริ่ม (ยังไม่ปิด) คลิกที่สอง = วันสุดท้าย แล้วปิด
+  const [start, setStart] = useState<Date | null>(null);
+
+  const selected = controlled ? toRange(value) : (own ?? undefined);
+  const parsed = useMemo(() => parseSmartDateRange(smartText), [smartText]);
+
+  const close = () => {
+    setOpen(false);
+    setSmartText("");
+    setStart(null);
+  };
+  const change = (range: DatePickerRange | null) => {
+    if (!controlled) setOwn(range);
+    onChange?.(range);
+  };
+  const commit = (range: DatePickerRange | null) => {
+    change(range);
+    close();
+  };
+
+  const calendarFormatters = locale
+    ? {
+        formatMonthDropdown: (d: Date) => d.toLocaleString(locale, { month: "short" }),
+        formatYearDropdown: (d: Date) => d.toLocaleString(locale, { year: "numeric" }),
+        formatWeekdayName: (d: Date) => d.toLocaleString(locale, { weekday: "narrow" }),
+        formatCaption: (d: Date) => d.toLocaleString(locale, { month: "long", year: "numeric" }),
+      }
+    : undefined;
+  const calendarSelected = start ? { from: start, to: undefined } : selected;
+
+  return (
+    <>
+      <Popover
+        open={open}
+        onOpenChange={(o) => {
+          if (o) setOpen(true);
+          else close();
+        }}
+      >
+        <PopoverTrigger
+          render={
+            <Button
+              id={id}
+              variant="outline"
+              disabled={disabled}
+              aria-required={required || undefined}
+              className={cn(
+                "h-8 w-full justify-between bg-background pr-2 pl-3 text-left font-normal text-xs",
+                !selected && "text-muted-foreground",
+                className,
+              )}
+            />
+          }
+        >
+          <div className="flex items-center gap-2 truncate">
+            <CalendarIcon className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+            <span className="truncate">
+              {selected ? (
+                <span className="font-medium text-foreground">{formatRange(selected, locale)}</span>
+              ) : (
+                <span>{placeholder ?? text?.rangePlaceholder ?? "เลือกช่วงวันที่"}</span>
+              )}
+            </span>
+          </div>
+          {allowClear && selected && !disabled && (
+            <span
+              role="button"
+              tabIndex={0}
+              aria-label={text?.clear ?? "ล้างวันที่"}
+              className="ml-1 cursor-pointer rounded p-0.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+              onClick={(e) => {
+                e.stopPropagation();
+                change(null);
+              }}
+              onKeyDown={(e) => {
+                if (e.key !== "Enter" && e.key !== " ") return;
+                e.preventDefault();
+                e.stopPropagation();
+                change(null);
+              }}
+            >
+              <X className="h-3.5 w-3.5" />
+            </span>
+          )}
+        </PopoverTrigger>
+        <PopoverContent className="w-[306px] border bg-background p-3 shadow-xl" align="start">
+          {showSmartInput && (
+            <SmartInput
+              value={smartText}
+              onChange={setSmartText}
+              onSubmit={() => parsed && commit(parsed)}
+              preview={parsed ? formatRange(parsed, locale) : null}
+              placeholder={text?.rangeSmartPlaceholder ?? "เช่น 1/7-5/7, t-7..t"}
+              range
+            />
+          )}
+
+          <div className="flex w-full justify-center">
+            <Calendar
+              mode="range"
+              selected={calendarSelected}
+              onSelect={(_range, day) => {
+                // คุมสองคลิกเอง: react-day-picker คลิกแรกให้ from = to (ช่วงหนึ่งวัน) จึงแยกคลิกแรกไม่ออก
+                if (!start) {
+                  setStart(day);
+                  return;
+                }
+                commit(
+                  day.getTime() < start.getTime()
+                    ? { from: day, to: start }
+                    : { from: start, to: day },
+                );
+              }}
+              disabled={disabled}
+              captionLayout="dropdown"
+              startMonth={new Date(1990, 0)}
+              endMonth={new Date(2040, 11)}
+              defaultMonth={parsed?.from ?? start ?? selected?.from}
+              formatters={calendarFormatters}
+              className="p-0 [--cell-size:--spacing(10)]"
+            />
+          </div>
+          {start && (
+            <p className="mt-2 text-center text-muted-foreground text-xs">
+              {text?.pickEnd ?? "เลือกวันสุดท้ายของช่วง"}
+            </p>
+          )}
+        </PopoverContent>
+      </Popover>
+      {name !== undefined && (
+        <>
+          <FormValue
+            name={name[0]}
+            value={toDateInputValue(selected?.from)}
+            required={required}
+            disabled={disabled}
+          />
+          <FormValue
+            name={name[1]}
+            value={toDateInputValue(selected?.to)}
+            required={required}
+            disabled={disabled}
+          />
+        </>
+      )}
+    </>
+  );
+}
+
+/**
+ * ช่องพิมพ์วันที่ + ปุ่ม (i) เปิดวิธีพิมพ์ — คำอธิบายแสดงในกล่องเดียวกัน (ไม่ใช่ tooltip: popup ซ้อน popup
+ * และจอสัมผัสเปิด tooltip ไม่ได้)
+ */
+function SmartInput({
+  value,
+  onChange,
+  onSubmit,
+  preview,
+  placeholder,
+  range,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  onSubmit: () => void;
+  preview: string | null;
+  placeholder: string;
+  range: boolean;
+}) {
+  const text = useUiText().datePicker;
+  const [help, setHelp] = useState(false);
+  const rows: Array<[string, string]> = [
+    ["15/3", text?.helpDate ?? "15 มี.ค. ปีนี้ (ไม่ใส่ปี = ปีปัจจุบัน)"],
+    ["15/3/69 · 15/3/2026", text?.helpYear ?? "ใส่ปี พ.ศ. หรือ ค.ศ. ได้ (2 หรือ 4 หลัก)"],
+    ["t", text?.helpToday ?? "วันนี้"],
+    ["t+3 · t-2", text?.helpDays ?? "อีก 3 วัน · 2 วันก่อน (d = วัน)"],
+    ["t+2w · t+1m · t+1y", text?.helpUnits ?? "สัปดาห์ · เดือน · ปี"],
+    ...(range
+      ? ([
+          ["1/7-5/7 · 1-5/7", text?.helpRange ?? "1–5 ก.ค."],
+          ["t-7..t · t ~ t+1m", text?.helpRangeShortcut ?? "ช่วงจากตัวย่อ (คั่นด้วย .. ~ ถึง to)"],
+        ] as Array<[string, string]>)
+      : []),
+  ];
+  return (
+    <div className="mb-3 flex flex-col gap-1.5 border-b pb-2.5">
+      <InputGroup className="h-8">
+        <InputGroupInput
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              event.preventDefault();
+              event.stopPropagation();
+              onSubmit();
+            }
+          }}
+          placeholder={placeholder}
+          className="h-8 text-xs"
+        />
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton
+            type="button"
+            size="icon-xs"
+            aria-label={text?.help ?? "วิธีพิมพ์วันที่"}
+            aria-expanded={help}
+            onClick={() => setHelp((v) => !v)}
+            className={help ? "text-foreground" : "text-muted-foreground"}
+          >
+            <InfoIcon />
+          </InputGroupButton>
+          <InputGroupButton
+            type="button"
+            variant="default"
+            size="xs"
+            onClick={onSubmit}
+            disabled={!preview}
+          >
+            {text?.apply ?? "ตกลง"}
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+      {preview && (
+        <span className="flex items-center gap-1 font-medium text-success text-xs">
+          <Check className="size-3" />
+          {preview}
+        </span>
+      )}
+      {help && (
+        <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 rounded-md bg-muted/60 p-2 text-xs">
+          {rows.map(([example, meaning]) => (
+            <div key={example} className="contents">
+              <dt className="font-mono text-foreground">{example}</dt>
+              <dd className="text-muted-foreground">{meaning}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+    </div>
+  );
+}

package/src/components/shared/ui-text.tsx

@@ -189,6 +189,25 @@ export interface UiText {
     nextMonth: string;
     lastMonth: string;
     clear: string;
+    /** โหมดช่วงวันที่ (`mode="range"`) */
+    rangePlaceholder: string;
+    rangeSmartPlaceholder: string;
+    /** ปุ่ม (i) และคำอธิบายวิธีพิมพ์ (0.42.0) */
+    help: string;
+    helpDate: string;
+    helpYear: string;
+    helpToday: string;
+    helpDays: string;
+    helpUnits: string;
+    helpRange: string;
+    helpRangeShortcut: string;
+    pickEnd: string;
+    last7Days: string;
+    last30Days: string;
+    thisMonth: string;
+    previousMonth: string;
+    next7Days: string;
+    next30Days: string;
   }>;
   /** TimePicker / DateTimePicker (optional) */
   time?: Partial<{
@@ -357,7 +376,7 @@ export const UI_TEXT_TH: UiText = {
   number: { increment: "เพิ่ม", decrement: "ลด" },
   datePicker: {
     placeholder: "เลือกวันที่",
-    smartPlaceholder: "เช่น 1/7, 1/7/25, 1-7-2568...",
+    smartPlaceholder: "เช่น 15/3, t+3, t+1m",
     apply: "ตกลง",
     presets: "ทางลัด",
     today: "วันนี้",
@@ -368,6 +387,23 @@ export const UI_TEXT_TH: UiText = {
     nextMonth: "+1 เดือน",
     lastMonth: "-1 เดือน",
     clear: "ล้างวันที่",
+    rangePlaceholder: "เลือกช่วงวันที่",
+    rangeSmartPlaceholder: "เช่น 1/7-5/7, t-7..t",
+    help: "วิธีพิมพ์วันที่",
+    helpDate: "15 มี.ค. ปีนี้ (ไม่ใส่ปี = ปีปัจจุบัน)",
+    helpYear: "ใส่ปี พ.ศ. หรือ ค.ศ. ได้ (2 หรือ 4 หลัก)",
+    helpToday: "วันนี้",
+    helpDays: "อีก 3 วัน · 2 วันก่อน (d = วัน)",
+    helpUnits: "สัปดาห์ · เดือน · ปี",
+    helpRange: "1–5 ก.ค.",
+    helpRangeShortcut: "ช่วงจากตัวย่อ (คั่นด้วย .. ~ ถึง to)",
+    pickEnd: "เลือกวันสุดท้ายของช่วง",
+    last7Days: "7 วันล่าสุด",
+    last30Days: "30 วันล่าสุด",
+    thisMonth: "เดือนนี้",
+    previousMonth: "เดือนที่แล้ว",
+    next7Days: "7 วันข้างหน้า",
+    next30Days: "30 วันข้างหน้า",
   },
   time: {
     choose: "เลือกเวลา",
@@ -542,7 +578,7 @@ export const UI_TEXT_EN: UiText = {
   number: { increment: "Increase", decrement: "Decrease" },
   datePicker: {
     placeholder: "Pick a date",
-    smartPlaceholder: "e.g. 1/7, 1/7/25, 1-7-2025…",
+    smartPlaceholder: "e.g. 15/3, t+3, t+1m",
     apply: "Apply",
     presets: "Shortcuts",
     today: "Today",
@@ -553,6 +589,23 @@ export const UI_TEXT_EN: UiText = {
     nextMonth: "+1 month",
     lastMonth: "-1 month",
     clear: "Clear date",
+    rangePlaceholder: "Pick a date range",
+    rangeSmartPlaceholder: "e.g. 1/7-5/7, t-7..t",
+    help: "How to type a date",
+    helpDate: "15 Mar this year (no year = current year)",
+    helpYear: "Year in CE or BE (2 or 4 digits)",
+    helpToday: "Today",
+    helpDays: "In 3 days · 2 days ago (d = days)",
+    helpUnits: "Weeks · months · years",
+    helpRange: "1–5 Jul",
+    helpRangeShortcut: "Range from shortcuts (separate with .. ~ to)",
+    pickEnd: "Pick the last day of the range",
+    last7Days: "Last 7 days",
+    last30Days: "Last 30 days",
+    thisMonth: "This month",
+    previousMonth: "Last month",
+    next7Days: "Next 7 days",
+    next30Days: "Next 30 days",
   },
   time: {
     choose: "Choose time",

package/src/components/ui/date-picker.tsx

@@ -5,6 +5,10 @@
 export {
   DatePicker,
   type DatePickerProps,
+  type DatePickerRange,
+  type DatePickerRangeProps,
+  type DatePickerSingleProps,
   parseSmartDateInput,
+  parseSmartDateRange,
   toDateInputValue,
 } from "@suphark/ui/components/shared/date/date-picker";

package/src/index.ts

@@ -79,7 +79,11 @@ export { DataList, DataRow } from "./components/shared/data-list";
 export {
   DatePicker,
   type DatePickerProps,
+  type DatePickerRange,
+  type DatePickerRangeProps,
+  type DatePickerSingleProps,
   parseSmartDateInput,
+  parseSmartDateRange,
   toDateInputValue,
 } from "./components/shared/date/date-picker";
 export { DateRangePicker } from "./components/shared/date/date-range-picker";