# Bone Flow #025 - DatePicker 操作ガイド

Runtime: **BoneDatePicker 1.0.12**  
HTML Functional Class: **`bf-datepicker`**  
状態: Development / Candidate

Guide UI: **BoneDocGuide / DOC-0025 の1系統のみ**。独自Guide Modalを追加しません。

## 1. DatePickerとは

#025 DatePicker は、呼び出し元の `input` と #024 Calendar を接続する Primitive UI です。Calendar Panel の表示・非表示時の視覚補間は #118 Transition の ENTER / EXIT に委譲し、Mouse Over の外周Effectは #022 Hover Border Effectへ委譲します。

DatePicker自身は呼び出し元 `input.value` を自動変更しません。選択値は `bone-datepicker:select` Event / `onSelect` callbackで返し、INPUTへ確定する処理は呼び出し元UIが所有します。

## 2. 最小HTML

```html
<input class="bf-datepicker" type="text" value="2026-08-10">
```

`class="bf-datepicker"` を指定すると HTML Functional Class bridge が #025 Runtimeをmountします。

## 3. HTML Functional Class

主な属性:

```html
<input
  class="bf-datepicker"
  type="text"
  value="2026-08-10"
  data-theme="dark"
  data-week-start="sunday"
  data-transition="fade"
  data-transition-direction="down"
  data-transition-speed="normal"
  data-respect-reduced-motion="true">
```

bridgeはINPUTを別要素へ置換せず、INPUTの直後へDatePicker triggerを接続します。

## 4. Runtime Default

- `theme`: `default`
- `iconVisual`: `fontawesome`
- `weekStart`: `auto`
- `step`: `1`
- `showTasks`: `true`
- `showCalendarManagerButtons`: `false`（タスク区分 / タスク / イベント / 🎌祝日CSV・Annotation管理ボタンをまとめて非表示）
- `disabled`: `false`
- `readonly`: `false`
- `closeOnSelect`: `true`
- `panelWidth`: `360`
- `calendarHeight`: `430`
- `gap`: `6`
- `transition`: `fade`
- `transitionDirection`: `down`
- `transitionSpeed`: `normal`
- `respectReducedMotion`: `true`

正式定義は `BoneDatePicker.getPropertySchema()`、Defaultは `getPropertyDefaults()`、1項目は `getPropertyDefinition(key)` で取得します。

## 5. #024 Calendarとの責務分離

DatePickerは `theme / iconVisual / locale / weekStart / min / max / step / annotations / showTasks / showCalendarManagerButtons / width / height` を #024 Calendarへ渡します。Calendarの日付計算、選択可能判定、日付セル描画は #024 の責務です。

Consumerは #024 の特定patch番号を固定契約にせず、必要なPublic API capabilityを確認します。

## 6. #118 Transitionで表示・非表示

DatePickerが `open / closed` の意味状態を所有し、#118はPanelの視覚補間だけを担当します。

```text
#025: Panelを表示可能状態にする
  ↓
#118: ENTER
  ↓
#025: open=true

#025: close開始
  ↓
#118: EXIT
  ↓
#025: Panelをhiddenへ戻す
```

#025側で独自のFade/Slide CSSを代用しません。`BoneTransitionFunctionalClass.mount / getInstance` が所有する同一instanceへ、`BoneTransition.setOptions / enter / exit / cancel / getState / getTarget` を使用します。#025自身は別instanceを `create / attach` せず、EXIT直後に `finish()` もしません。

## 7. #022 Hover Border Effect

正式Effectは #022 Public API `BoneHoverBorderEffect.effects` から取得します。現行 #022 v1.0.27 の正式値:

`normal / neon / spin / blink / dash / corner / chase / double / wave`



DatePicker外枠と #024 Calendar日付セルは別設定です。どちらも `trigger=mouseover` で #022 Runtimeへ委譲します。Calendar日付セルの再attach監視は `.bone-calendar__days` 直下の `childList` に限定し、Annotation / Tooltip内部更新では不要なdetach/re-attachを行いません。

## 8. #040 ColorPicker

#022 Effect色は #040 `BoneColorPicker.attachCaller()` のsolid-only Callerを使います。Consumer独自Palette、native `input[type=color]`、#040内部DOM操作、独自 `openCaller()` 二重登録は禁止です。

#040の正式ロード前提として #118 Runtimeと #118 Functional Class bridge が先に必要です。

## 9. 選択値RETURN

主なEvent:

- `bone-datepicker:open`
- `bone-datepicker:close`
- `bone-datepicker:select`

`bone-datepicker:select` には選択日、直前値、Caller INPUTの現在値等が含まれます。DatePicker自身はINPUTへcommitしません。

## 10. Public API 詳細

この章が #025 の **唯一の正式な API ガイド本文**です。テストページ側に別の独自Guide Modalは持ちません。画面上の「操作ガイド DOC-0025」から同じBoneDocGuide Viewerで参照します。

### 10.1 `BoneDatePicker.getPropertySchema()`

- 目的: 正式Property Schemaを取得
- 引数: `なし`
- 戻り値: `Array`
- いつ使うか: Runtime-owned Property定義をUIやDOCから参照するとき。

使用手順:
1. BoneDatePicker.getPropertySchema()を呼びます。

操作説明:
- 防御copyされたProperty配列を返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const schema = BoneDatePicker.getPropertySchema();
```

### 10.2 `BoneDatePicker.getPropertyDefaults()`

- 目的: 正式Defaultを取得
- 引数: `なし`
- 戻り値: `Object`
- いつ使うか: Runtime Default全件を取得するとき。

使用手順:
1. BoneDatePicker.getPropertyDefaults()を呼びます。

操作説明:
- Defaultのcopyを返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const defaults = BoneDatePicker.getPropertyDefaults();
```

### 10.3 `BoneDatePicker.getPropertyDefinition(key)`

- 目的: 1 Property定義を取得
- 引数: `key`
- 戻り値: `Object | null`
- いつ使うか: 1つのProperty定義を調べるとき。

使用手順:
1. Property keyを渡します。

操作説明:
- 存在しなければnullです。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const def = BoneDatePicker.getPropertyDefinition('transition');
```

### 10.4 `BoneDatePicker.create(input, options)`

- 目的: INPUTへDatePickerを接続
- 引数: `input, options`
- 戻り値: `HTMLElement`
- いつ使うか: 日付INPUTの横にPicker triggerを接続し、#024 Calendarで選択値だけ返したいとき。

使用手順:
1. 呼び出し元INPUT HTMLElementを用意します。
2. theme / min / max / step / locale / onSelect等のoptionsを用意します。
3. BoneDatePicker.create(input, options)を呼び、返ったpickerを保持します。

操作説明:
- INPUT直後にtriggerを配置し、Panelはdocument.bodyへ配置します。
- #024 Calendarはopen時に生成します。
- 選択結果はEvent/callbackで返しますがINPUT.valueは変更しません。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const picker = BoneDatePicker.create(input, {
  theme: 'dark',
  min: '2026-08-01',
  max: '2027-08-10',
  onSelect(e) { console.log(e.date); }
});
```

### 10.5 `BoneDatePicker.destroy(picker)`

- 目的: DatePicker instanceを破棄
- 引数: `picker`
- 戻り値: `boolean`
- いつ使うか: 画面破棄・再生成前にDatePickerとPanelを片付けるとき。

使用手順:
1. isInstanceで対象を確認できます。
2. BoneDatePicker.destroy(picker)を呼びます。

操作説明:
- event listenerを解除し、内部Calendarとbody-owned Panel、trigger rootを削除します。
- 未登録ならfalseを返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
if (BoneDatePicker.isInstance(picker)) {
  BoneDatePicker.destroy(picker);
}
```

### 10.6 `BoneDatePicker.setOptions(picker, patch)`

- 目的: Propertyを更新
- 引数: `picker, patch`
- 戻り値: `HTMLElement`
- いつ使うか: 生成後にTheme、min/max、step、disabled等を変更するとき。

使用手順:
1. 変更項目だけpatchへ入れます。
2. BoneDatePicker.setOptions(picker, patch)を呼びます。

操作説明:
- 既存optionsとmerge後normalizeし、triggerと開いているCalendarへ反映します。
- DatePicker自身はcommitしません。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
BoneDatePicker.setOptions(picker, {
  theme: 'neon',
  disabled: false
});
```

### 10.7 `BoneDatePicker.getOptions(picker)`

- 目的: 現在Propertyを取得
- 引数: `picker`
- 戻り値: `Object`
- いつ使うか: 現在のDatePicker Propertyを診断・保存したいとき。

使用手順:
1. BoneDatePicker.getOptions(picker)を呼びます。
2. 返ったfreeze済みObjectを参照します。

操作説明:
- 現在optionsのcopyを返します。
- 変更にはsetOptionsを使用します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const options = BoneDatePicker.getOptions(picker);
console.log(options.theme);
```

### 10.8 `BoneDatePicker.setValue(picker, value)`

- 目的: Picker内部選択値を設定
- 引数: `picker, value`
- 戻り値: `HTMLElement`
- いつ使うか: INPUTを変更せずPicker内部の選択値だけ同期したいとき。

使用手順:
1. YYYY-MM-DDまたはnullを指定します。
2. BoneDatePicker.setValue(picker, value)を呼びます。

操作説明:
- 内部selectedValueと生成済みCalendarのvalueを更新します。
- 呼び出し元INPUT.valueは変更しません。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
BoneDatePicker.setValue(picker, '2026-09-09');
```

### 10.9 `BoneDatePicker.getValue(picker)`

- 目的: Picker内部選択値を取得
- 引数: `picker`
- 戻り値: `string | null`
- いつ使うか: DatePickerが現在保持する選択値を読みたいとき。

使用手順:
1. BoneDatePicker.getValue(picker)を呼びます。

操作説明:
- YYYY-MM-DDまたはnullを返します。
- anchor INPUTの値とは独立しています。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const selected = BoneDatePicker.getValue(picker);
```

### 10.10 `BoneDatePicker.getAnchor(picker)`

- 目的: 呼び出し元INPUTを取得
- 引数: `picker`
- 戻り値: `HTMLElement`
- いつ使うか: DatePickerに接続した呼び出し元INPUTを取得したいとき。

使用手順:
1. BoneDatePicker.getAnchor(picker)を呼びます。

操作説明:
- create第1引数のHTMLElementを返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const input = BoneDatePicker.getAnchor(picker);
```

### 10.11 `BoneDatePicker.getPanel(picker)`

- 目的: body-owned Panelを取得
- 引数: `picker`
- 戻り値: `HTMLElement`
- いつ使うか: 配置確認や診断のためbody-owned Picker Panelを参照するとき。

使用手順:
1. BoneDatePicker.getPanel(picker)を呼びます。

操作説明:
- document.body配下のPanel HTMLElementを返します。
- 通常の開閉はopen/closeを使用し、内部DOMを直接改変しません。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const panel = BoneDatePicker.getPanel(picker);
```

### 10.12 `BoneDatePicker.getCalendar(picker)`

- 目的: 生成済み#024 Calendarを取得
- 引数: `picker`
- 戻り値: `HTMLElement | null`
- いつ使うか: open後の#024 Calendar instanceへ公開APIでアクセスするとき。

使用手順:
1. 先にopenしてCalendarを生成します。
2. BoneDatePicker.getCalendar(picker)を呼びます。

操作説明:
- 未生成ならnull、生成済みなら#024 Calendar HTMLElementを返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
BoneDatePicker.open(picker);
const calendar = BoneDatePicker.getCalendar(picker);
```

### 10.13 `BoneDatePicker.open(picker)`

- 目的: ピッカーを開く
- 引数: `picker`
- 戻り値: `Object`
- いつ使うか: APIからDatePicker Panelを開きたいとき。

使用手順:
1. BoneDatePicker.open(picker)を呼びます。
2. openedを確認できます。

操作説明:
- anchor値を再読込し、Calendarを生成/同期、PanelをINPUT直下へ配置します。
- disabled/readonlyならopened=falseです。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const result = BoneDatePicker.open(picker);
console.log(result.opened);
```

### 10.14 `BoneDatePicker.close(picker)`

- 目的: ピッカーを閉じる
- 引数: `picker`
- 戻り値: `Object`
- いつ使うか: APIからDatePicker Panelを閉じたいとき。

使用手順:
1. BoneDatePicker.close(picker)を呼びます。

操作説明:
- Panelをhiddenへ戻しclose Event/callbackを発行します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
BoneDatePicker.close(picker);
```

### 10.15 `BoneDatePicker.toggle(picker)`

- 目的: 開閉を切替
- 引数: `picker`
- 戻り値: `Object`
- いつ使うか: 現在状態に応じて開閉を1操作で切り替えたいとき。

使用手順:
1. BoneDatePicker.toggle(picker)を呼びます。

操作説明:
- open中ならclose、close中ならopenを呼びます。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
BoneDatePicker.toggle(picker);
```

### 10.16 `BoneDatePicker.isOpen(picker)`

- 目的: 開閉状態を取得
- 引数: `picker`
- 戻り値: `boolean`
- いつ使うか: Panelが現在開いているか判定するとき。

使用手順:
1. BoneDatePicker.isOpen(picker)を呼びます。

操作説明:
- 内部open Stateのbooleanを返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
if (BoneDatePicker.isOpen(picker)) {
  BoneDatePicker.close(picker);
}
```

### 10.17 `BoneDatePicker.reposition(picker)`

- 目的: INPUT直下へ再配置
- 引数: `picker`
- 戻り値: `boolean`
- いつ使うか: INPUT移動後に開いているPanel位置を即時再計算したいとき。

使用手順:
1. Panelがopenか確認します。
2. BoneDatePicker.reposition(picker)を呼びます。

操作説明:
- anchorのgetBoundingClientRectからbottom+gapを計算し、viewport右端も補正します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
if (BoneDatePicker.isOpen(picker)) {
  BoneDatePicker.reposition(picker);
}
```

### 10.18 `BoneDatePicker.validateDate(value, options)`

- 目的: DatePicker日付契約を検証
- 引数: `value, options`
- 戻り値: `Object`
- いつ使うか: Pickerを生成せず日付の形式・min/max/step選択可否を検証するとき。

使用手順:
1. valueと必要なmin/max/stepを指定します。
2. 返り値のvalid/selectable/codeを確認します。

操作説明:
- #024 Calendar.validateDateへ正式委譲します。
- 例外はvalid=falseのResultへ変換します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const r = BoneDatePicker.validateDate('2026-08-10', {
  min: '2026-08-01',
  max: '2027-08-10'
});
```

### 10.19 `BoneDatePicker.normalizeOptions(options)`

- 目的: optionsを正式normalize
- 引数: `options`
- 戻り値: `Object`
- いつ使うか: create/setOptions前と同じ正式規則でoptionsを事前検証したいとき。

使用手順:
1. plain objectを渡します。
2. freeze済みnormalized optionsを受け取ります。

操作説明:
- enum、日付、step、locale、数値範囲、callback型を検証します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
const normalized = BoneDatePicker.normalizeOptions({
  theme: 'dark',
  step: 1
});
```

### 10.20 `BoneDatePicker.isInstance(picker)`

- 目的: DatePicker instance判定
- 引数: `picker`
- 戻り値: `boolean`
- いつ使うか: 任意HTMLElementがBoneDatePicker instanceか安全に確認するとき。

使用手順:
1. BoneDatePicker.isInstance(element)を呼びます。

操作説明:
- 内部WeakMap登録の有無をbooleanで返します。

責務境界: #025はPicker表示・開閉・選択日のRETURNまでを所有します。INPUT commit / Bone.value / OUT / Deliveryは呼び出し元の責務です。

```js
if (BoneDatePicker.isInstance(picker)) {
  console.log('DatePicker');
}
```


## 11. Test / Validation

Test URL:

```text
http://localhost/boneflow/test/bone-datepicker.html
```

Smoke / Validationは自動実行しません。ページ表示時の初期状態は `NOT RUN` です。ユーザー操作で実行し、さらに #118 ENTER / EXIT、#022 Mouse Over、#040 ColorPicker、`bf-datepicker` を実画面で確認します。

## 12. Completion

Static QAやNode QAだけではCompletedになりません。localhostでのRuntime確認後、ユーザーが明示的に完了を確定した場合だけ Completed / Specification Frozenへ移行します。

## 13. トラブルシューティング

- Pickerが開かない: #024 / #118 capabilityとscript load orderを確認。
- #040が開かない: `bone-transition.js` と `bone-transition-functional-class.js` が #040より先に読まれているか確認。
- Hover Effectが出ない: #022 Public API `effects` と `normalizeOptions/attach/update/detach/setActive` capabilityを確認。
- INPUT値が変わらない: 正常です。#025はINPUTへ自動commitしません。


## Calendar管理ボタン表示
DatePickerは年月日選択を主目的とするため、#024 Calendar下部の「タスク区分 / タスク / イベント / 🎌祝日CSV・Annotation」管理ボタンは初期非表示です。`showCalendarManagerButtons:true` の時だけ表示します。

## #118 EXIT
閉じる・日付選択後の自動Close・Escape・外側クリックはいずれも同じClose経路を通り、#118 EXITを開始してからPanelを非表示にします。EXIT開始直後に `hidden=true` や `finish()` で視覚補間を打ち切りません。


## #002正式Delivery Channel テスト（Package 1.0.33）

テストページには #017 基準の `OUT WAIT / FIFO / BLOCKED — #002正式Delivery Channel` を表示します。これは BoneDatePicker RuntimeへOUT責務を追加するものではありません。DatePickerのRETURNを受けたCaller OUTを模擬し、`BoneJoint.createDeliveryChannel()`へ委譲して WAIT → READY → FIFO と BLOCKED時のTarget不達を確認します。Smoke / Validation PASSに加えて、WAIT/FIFOとBLOCKEDの目視確認がComponent完了条件です。