@ticatec/topside-elements 1.0.0

package/dist/form/date_picker/README.md

@@ -0,0 +1,341 @@
+# DatePicker & DateTimePicker
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `mandatory` were removed in 5.1.0 (no compatibility aliases are kept).
+
+Date and datetime selection components built on a shared popup picker. `DatePicker` selects a calendar date; `DateTimePicker` combines a calendar with a time panel and requires explicit confirmation.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import DatePicker from "@ticatec/topside-elements/DatePicker";
+import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+```
+
+## Features
+
+- **DatePicker**: date-only selection with calendar popup; closes on select
+- **DateTimePicker**: date + time selection with confirm bar; supports hour / minute / second precision
+- Visual variants: default, `plain`, `outlined`, `filled`
+- `min` / `max` date limits enforced in the calendar
+- `clearable={false}` hides the clear action
+- Read-only and disabled states
+- Error text and tooltip via the shared form editor shell
+- Day.js used internally; bound values accept `Date`, Day.js, or string
+
+---
+
+## DatePicker
+
+### Basic Usage
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let selectedDate = $state(/** @type {Date | string | undefined} */ (new Date()));
+</script>
+
+<DatePicker bind:value={selectedDate} placeholder="Select date" />
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `UniDate` | — | Selected date. Bindable via `bind:value`. Accepts `Date`, Day.js, string, or `undefined` |
+| `min` | `UniDate` | — | Earliest selectable date |
+| `max` | `UniDate` | — | Latest selectable date |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual style |
+| `compact` | `boolean` | `false` | Compact spacing |
+| `disabled` | `boolean` | `false` | Non-interactive, muted style |
+| `readonly` | `boolean` | `false` | Display-only; popup does not open |
+| `clearable` | `boolean` | `true` | Whether the value can be cleared (shows the clear button). The old `mandatory` prop meant the opposite (`mandatory={true}` = `clearable={false}`) and was removed in 5.1.0. |
+| `placeholder` | `string` | — | Placeholder when empty |
+| `tooltip` | `string` | — | Hover tooltip |
+| `error` | `string` | — | Error message shown by the field shell |
+| `style` | `string` | — | Inline styles on the root editor |
+| `onchange` | `(value?: Date) => void` | — | Called when a date is selected; receives a native `Date`, or is not called on clear |
+| `onfocus` | `(e: FocusEvent) => void` | — | Input gains focus |
+| `onblur` | `(e: FocusEvent) => void` | — | Input loses focus (after popup closes if it was open) |
+
+Display format is always `YYYY-MM-DD`.
+
+### Examples
+
+#### Outlined mandatory field
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let birthday = $state(new Date(1990, 5, 15));
+</script>
+
+<DatePicker
+  variant="outlined"
+  mandatory
+  bind:value={birthday}
+  placeholder="Date of birth (required)"
+/>
+```
+
+#### Min / max range
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let completedDate = $state(new Date());
+  let bookFrom = $state(/** @type {Date | undefined} */ (undefined));
+</script>
+
+<!-- Dates up to today -->
+<DatePicker
+  variant="filled"
+  max={new Date()}
+  bind:value={completedDate}
+  placeholder="Completion date"
+/>
+
+<!-- Dates from a lower bound -->
+<DatePicker
+  variant="filled"
+  min="2025-01-01"
+  max="2025-12-31"
+  bind:value={bookFrom}
+  placeholder="Booking date"
+/>
+```
+
+#### Disabled, read-only, and error
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let admissionDate = $state(new Date());
+</script>
+
+<DatePicker variant="filled" disabled bind:value={admissionDate} />
+<DatePicker variant="filled" readonly bind:value={admissionDate} />
+<DatePicker error="Invalid date" placeholder="Please select" />
+```
+
+#### Variants
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+</script>
+
+<DatePicker variant="plain" value="2025-01-15" />
+<DatePicker variant="outlined" value="2025-01-15" />
+<DatePicker variant="filled" value="2025-01-15" />
+```
+
+#### Change / focus handlers
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let selectedDate = $state(/** @type {Date | undefined} */ (new Date()));
+
+  function handleDateChange(date) {
+    console.log("Date selected:", date);
+  }
+</script>
+
+<DatePicker
+  bind:value={selectedDate}
+  onchange={handleDateChange}
+  onfocus={() => console.log("focused")}
+  onblur={() => console.log("blurred")}
+/>
+```
+
+### Behavior
+
+1. Click the field or calendar icon to open the popup (unless `readonly` / `disabled`).
+2. Selecting a day writes a native `Date` to `value`, calls `onchange`, and closes the popup.
+3. Clear (×) appears when there is a value and `clearable={false}` is false; clearing sets `value` to `undefined`.
+4. Display text is formatted with Day.js as `YYYY-MM-DD`.
+5. `min` / `max` are passed to the calendar and restrict selectable days.
+
+---
+
+## DateTimePicker
+
+### Basic Usage
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let selectedDateTime = $state(new Date());
+</script>
+
+<DateTimePicker bind:value={selectedDateTime} placeholder="Select date and time" />
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `UniDate` | — | Selected datetime. Bindable via `bind:value` |
+| `min` | `UniDate` | — | Earliest selectable **date** (calendar) |
+| `max` | `UniDate` | — | Latest selectable **date** (calendar) |
+| `precision` | `"H" \| "M" \| "S"` | `"M"` | Time granularity: hour, minute, or second |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual style |
+| `compact` | `boolean` | `false` | Compact spacing |
+| `disabled` | `boolean` | `false` | Non-interactive |
+| `readonly` | `boolean` | `false` | Display-only |
+| `clearable` | `boolean` | `true` | Whether the value can be cleared (shows the clear button). The old `mandatory` prop meant the opposite (`mandatory={true}` = `clearable={false}`) and was removed in 5.1.0. |
+| `placeholder` | `string` | — | Placeholder when empty |
+| `tooltip` | `string` | — | Hover tooltip |
+| `error` | `string` | — | Error message |
+| `theme` | `string` | — | Theme name (`data-theme` / picker chrome) |
+| `style` | `string` | — | Inline styles on the root editor |
+| `onchange` | `(value: Date) => void` | — | Called after **confirm**; receives a native `Date` |
+| `onfocus` | `(e: FocusEvent) => void` | — | Input gains focus |
+| `onblur` | `(e: FocusEvent) => void` | — | Input loses focus |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Focuses the picker input (slight delay for layout) |
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let picker;
+  let value = $state(new Date());
+</script>
+
+<button type="button" onclick={() => picker?.focus()}>Focus</button>
+<DateTimePicker bind:this={picker} bind:value={value} />
+```
+
+### Time Precision
+
+| `precision` | Columns shown | Display format | Normalization on open |
+|-------------|-----------------|----------------|------------------------|
+| `"H"` | Hour | `YYYY-MM-DD HH:mm` | Minutes and seconds set to `0` |
+| `"M"` | Hour + minute | `YYYY-MM-DD HH:mm` | Seconds set to `0` (default) |
+| `"S"` | Hour + minute + second | `YYYY-MM-DD HH:mm:ss` | Full time kept |
+
+### Examples
+
+#### Second precision, mandatory
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let releaseDate = $state(new Date());
+</script>
+
+<DateTimePicker
+  variant="outlined"
+  precision="S"
+  mandatory
+  bind:value={releaseDate}
+  placeholder="Release datetime (to seconds)"
+/>
+```
+
+#### Hour precision
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let appointmentTime = $state(new Date());
+</script>
+
+<DateTimePicker
+  variant="filled"
+  precision="H"
+  bind:value={appointmentTime}
+  placeholder="Appointment time (hour precision)"
+/>
+```
+
+#### States and variants
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+</script>
+
+<DateTimePicker variant="plain" value="2025-01-15 10:00" />
+<DateTimePicker variant="outlined" value="2025-01-15 10:00" />
+<DateTimePicker variant="filled" value="2025-01-15 10:00" />
+
+<DateTimePicker value="2025-03-20 10:00" readonly />
+<DateTimePicker disabled />
+```
+
+### Behavior
+
+1. Opening the popup shows a **calendar** (left) and **time scroll panel** (right).
+2. Changing the day or scrolling time updates a temporary `currentValue` only.
+3. Clicking **Confirm** commits `currentValue` to `value` as a native `Date`, calls `onchange` when the value actually changed, and closes the popup.
+4. Closing without confirm discards temporary edits (next open re-syncs from `value`).
+5. Clear sets `value` to `undefined` (when not `clearable={false}`).
+6. `min` / `max` apply to the calendar day selection, not to the time columns.
+
+---
+
+## Shared UI Notes
+
+### Variants
+
+| Variant | Description |
+|---------|-------------|
+| `""` | Default field chrome |
+| `"plain"` | Minimal styling |
+| `"outlined"` | Outlined border |
+| `"filled"` | Filled background |
+
+### Keyboard (shared picker shell)
+
+| Key | Action |
+|-----|--------|
+| **Space** | Open popup (when the input is read-only, which is the default for these pickers) |
+| **Backspace** / **Delete** | Clear value if not `mandatory` |
+| **Escape** / **Tab** | Close popup |
+
+DateTimePicker confirmation is done via the **Confirm** button in the popup footer (i18n key `calendar.confirmText`).
+
+### Type Definitions
+
+```typescript
+// From dateUtils
+type UniDate = dayjs.Dayjs | Date | string | undefined;
+
+type EditorVariant = "" | "plain" | "outlined" | "filled";
+type Precision = "H" | "M" | "S";
+```
+
+### Notes
+
+- Day.js is used for parsing and formatting.
+- `DatePicker` commits immediately on day click; `DateTimePicker` requires Confirm.
+- Outbound selected values are native `Date` objects (or `undefined` when cleared).
+- Inbound `value` may be a string (e.g. `"2025-07-06"` or `"2025-07-06 14:30"`), a `Date`, or Day.js.
+- Icons: calendar (`icon_google_event_available`) for DatePicker; clock (`icon_google_access_time`) for DateTimePicker.
+
+## Related Components
+
+- [DateRange](../date_range/README.md) — start/end date range
+- [TimeEditor](../time_editor/README.md) — standalone time input
+- [CommonPicker](../common_editor/) — shared popup field shell used by both pickers

package/dist/form/date_picker/README_CN.md

@@ -0,0 +1,341 @@
+# DatePicker 与 DateTimePicker
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `mandatory` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+基于共享弹层选择器的日期 / 日期时间组件。`DatePicker` 用于选择日历日期；`DateTimePicker` 在日历基础上增加时间面板，并需要显式确认后才会写回值。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import DatePicker from "@ticatec/topside-elements/DatePicker";
+import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+```
+
+## 功能特性
+
+- **DatePicker**：仅日期选择，带日历弹窗；选中后立即关闭
+- **DateTimePicker**：日期 + 时间选择，底部确认栏；支持时 / 分 / 秒精度
+- 视觉变体：默认、`plain`、`outlined`、`filled`
+- 日历内强制 `min` / `max` 日期范围
+- `clearable={false}` 时隐藏清除按钮
+- 只读与禁用状态
+- 通过表单编辑器外壳支持错误信息与 tooltip
+- 内部使用 Day.js；`value` 可接受 `Date`、Day.js 或字符串
+
+---
+
+## DatePicker
+
+### 基本用法
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let selectedDate = $state(/** @type {Date | string | undefined} */ (new Date()));
+</script>
+
+<DatePicker bind:value={selectedDate} placeholder="选择日期" />
+```
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `UniDate` | — | 选中日期，支持 `bind:value`。可为 `Date`、Day.js、字符串或 `undefined` |
+| `min` | `UniDate` | — | 可选最早日期 |
+| `max` | `UniDate` | — | 可选最晚日期 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式 |
+| `compact` | `boolean` | `false` | 紧凑间距 |
+| `disabled` | `boolean` | `false` | 禁用，不可交互 |
+| `readonly` | `boolean` | `false` | 只读，不打开弹层 |
+| `clearable` | `boolean` | `true` | 是否允许清空（显示清空按钮）。旧名 `mandatory` 语义相反（`mandatory={true}` = `clearable={false}`），5.1.0 已移除。 |
+| `placeholder` | `string` | — | 空值占位文本 |
+| `tooltip` | `string` | — | 悬停提示 |
+| `error` | `string` | — | 错误信息（由表单外壳展示） |
+| `style` | `string` | — | 根节点内联样式 |
+| `onchange` | `(value?: Date) => void` | — | 选中日期时回调，参数为原生 `Date`；清除时不一定触发 |
+| `onfocus` | `(e: FocusEvent) => void` | — | 获得焦点 |
+| `onblur` | `(e: FocusEvent) => void` | — | 失去焦点（若弹层打开，会在关闭后触发） |
+
+展示格式固定为 `YYYY-MM-DD`。
+
+### 示例
+
+#### 描边必填
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let birthday = $state(new Date(1990, 5, 15));
+</script>
+
+<DatePicker
+  variant="outlined"
+  mandatory
+  bind:value={birthday}
+  placeholder="出生日期（必填）"
+/>
+```
+
+#### 最小 / 最大日期
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let completedDate = $state(new Date());
+  let bookFrom = $state(/** @type {Date | undefined} */ (undefined));
+</script>
+
+<!-- 最晚到今天 -->
+<DatePicker
+  variant="filled"
+  max={new Date()}
+  bind:value={completedDate}
+  placeholder="完成日期"
+/>
+
+<!-- 限定区间 -->
+<DatePicker
+  variant="filled"
+  min="2025-01-01"
+  max="2025-12-31"
+  bind:value={bookFrom}
+  placeholder="预订日期"
+/>
+```
+
+#### 禁用、只读与错误
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let admissionDate = $state(new Date());
+</script>
+
+<DatePicker variant="filled" disabled bind:value={admissionDate} />
+<DatePicker variant="filled" readonly bind:value={admissionDate} />
+<DatePicker error="日期无效" placeholder="请选择" />
+```
+
+#### 样式变体
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+</script>
+
+<DatePicker variant="plain" value="2025-01-15" />
+<DatePicker variant="outlined" value="2025-01-15" />
+<DatePicker variant="filled" value="2025-01-15" />
+```
+
+#### 变更与焦点回调
+
+```svelte
+<script>
+  import DatePicker from "@ticatec/topside-elements/DatePicker";
+
+  let selectedDate = $state(/** @type {Date | undefined} */ (new Date()));
+
+  function handleDateChange(date) {
+    console.log("选中的日期：", date);
+  }
+</script>
+
+<DatePicker
+  bind:value={selectedDate}
+  onchange={handleDateChange}
+  onfocus={() => console.log("获得焦点")}
+  onblur={() => console.log("失去焦点")}
+/>
+```
+
+### 行为说明
+
+1. 点击输入区或日历图标打开弹层（`readonly` / `disabled` 除外）。
+2. 点击某一天会把原生 `Date` 写入 `value`，调用 `onchange`，并关闭弹层。
+3. 有值且非 `clearable={false}` 时显示清除（×）；清除后 `value` 为 `undefined`。
+4. 展示文本由 Day.js 格式化为 `YYYY-MM-DD`。
+5. `min` / `max` 传给日历，限制可选日期。
+
+---
+
+## DateTimePicker
+
+### 基本用法
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let selectedDateTime = $state(new Date());
+</script>
+
+<DateTimePicker bind:value={selectedDateTime} placeholder="选择日期和时间" />
+```
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `UniDate` | — | 选中的日期时间，支持 `bind:value` |
+| `min` | `UniDate` | — | 日历可选最早**日期** |
+| `max` | `UniDate` | — | 日历可选最晚**日期** |
+| `precision` | `"H" \| "M" \| "S"` | `"M"` | 时间精度：时 / 分 / 秒 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式 |
+| `compact` | `boolean` | `false` | 紧凑间距 |
+| `disabled` | `boolean` | `false` | 禁用 |
+| `readonly` | `boolean` | `false` | 只读 |
+| `clearable` | `boolean` | `true` | 是否允许清空（显示清空按钮）。旧名 `mandatory` 语义相反（`mandatory={true}` = `clearable={false}`），5.1.0 已移除。 |
+| `placeholder` | `string` | — | 空值占位 |
+| `tooltip` | `string` | — | 悬停提示 |
+| `error` | `string` | — | 错误信息 |
+| `theme` | `string` | — | 主题名（`data-theme` / 弹层样式） |
+| `style` | `string` | — | 根节点内联样式 |
+| `onchange` | `(value: Date) => void` | — | 点击**确认**且值变化后回调，参数为原生 `Date` |
+| `onfocus` | `(e: FocusEvent) => void` | — | 获得焦点 |
+| `onblur` | `(e: FocusEvent) => void` | — | 失去焦点 |
+
+### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 聚焦选择器输入框（内部有短延迟） |
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let picker;
+  let value = $state(new Date());
+</script>
+
+<button type="button" onclick={() => picker?.focus()}>聚焦</button>
+<DateTimePicker bind:this={picker} bind:value={value} />
+```
+
+### 时间精度
+
+| `precision` | 展示列 | 显示格式 | 打开时的规范化 |
+|-------------|--------|----------|----------------|
+| `"H"` | 时 | `YYYY-MM-DD HH:mm` | 分、秒置为 `0` |
+| `"M"` | 时 + 分 | `YYYY-MM-DD HH:mm` | 秒置为 `0`（默认） |
+| `"S"` | 时 + 分 + 秒 | `YYYY-MM-DD HH:mm:ss` | 保留完整时间 |
+
+### 示例
+
+#### 秒级精度 + 必填
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let releaseDate = $state(new Date());
+</script>
+
+<DateTimePicker
+  variant="outlined"
+  precision="S"
+  mandatory
+  bind:value={releaseDate}
+  placeholder="发布时间（精确到秒）"
+/>
+```
+
+#### 小时精度
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+
+  let appointmentTime = $state(new Date());
+</script>
+
+<DateTimePicker
+  variant="filled"
+  precision="H"
+  bind:value={appointmentTime}
+  placeholder="预约时间（精确到小时）"
+/>
+```
+
+#### 状态与变体
+
+```svelte
+<script>
+  import { DateTimePicker } from "@ticatec/topside-elements/DatePicker";
+</script>
+
+<DateTimePicker variant="plain" value="2025-01-15 10:00" />
+<DateTimePicker variant="outlined" value="2025-01-15 10:00" />
+<DateTimePicker variant="filled" value="2025-01-15 10:00" />
+
+<DateTimePicker value="2025-03-20 10:00" readonly />
+<DateTimePicker disabled />
+```
+
+### 行为说明
+
+1. 打开弹层后左侧为**日历**，右侧为**时间滚动面板**。
+2. 修改日期或滚动时间只更新临时的 `currentValue`。
+3. 点击**确认**后，将 `currentValue` 以原生 `Date` 写回 `value`；若与原值不同则调用 `onchange`，并关闭弹层。
+4. 未确认直接关闭会丢弃临时修改（下次打开会从 `value` 重新同步）。
+5. 清除会将 `value` 设为 `undefined`（非 `clearable={false}` 时）。
+6. `min` / `max` 仅约束日历日期，不约束时间列。
+
+---
+
+## 共用说明
+
+### 样式变体
+
+| 变体 | 说明 |
+|------|------|
+| `""` | 默认字段外观 |
+| `"plain"` | 极简样式 |
+| `"outlined"` | 描边 |
+| `"filled"` | 填充背景 |
+
+### 键盘（共用选择器外壳）
+
+| 按键 | 行为 |
+|------|------|
+| **Space** | 打开弹层（输入框默认只读时） |
+| **Backspace** / **Delete** | 非 `mandatory` 时清除值 |
+| **Escape** / **Tab** | 关闭弹层 |
+
+DateTimePicker 的确认通过弹层底部的**确认**按钮完成（文案来自 i18n：`calendar.confirmText`）。
+
+### 类型定义
+
+```typescript
+// 来自 dateUtils
+type UniDate = dayjs.Dayjs | Date | string | undefined;
+
+type EditorVariant = "" | "plain" | "outlined" | "filled";
+type Precision = "H" | "M" | "S";
+```
+
+### 注意事项
+
+- 内部使用 Day.js 解析与格式化。
+- `DatePicker` 点选日期即提交；`DateTimePicker` 必须点确认。
+- 对外提交的选中值为原生 `Date`（清除后为 `undefined`）。
+- 入参 `value` 可以是字符串（如 `"2025-07-06"`、`"2025-07-06 14:30"`）、`Date` 或 Day.js。
+- 图标：DatePicker 使用日历图标（`icon_google_event_available`）；DateTimePicker 使用时钟图标（`icon_google_access_time`）。
+
+## 相关组件
+
+- [DateRange](../date_range/README_CN.md) — 起止日期范围
+- [TimeEditor](../time_editor/README_CN.md) — 独立时间输入
+- [CommonPicker](../common_editor/) — 两个选择器共用的弹层字段外壳