DOC-0025 — DatePicker 操作・HTML Functional Class

0. 文書情報

DOC ID: DOC-0025
TOC ID: TOC-0025
対象UI: UI-025
Component: #025 DatePicker
Runtime Version: 1.0.10
HTML Functional Class: bf-datepicker
DOC Version: 1.0.4
DOC Type: html-functional-class
Status: active

このDOCは #025 DatePicker v1.0.10 の実Runtimeと実テスト画面だけを根拠に、通常操作、HTML Functional Class、18個のHTML宣言Property、3個のJavaScript専用callback、17 Public API、Security、#024/#022/#040/#002との責務境界を説明します。存在しない commit / invoke / OUT / DatePicker固有Delivery Channelは追加しません。

1. DatePickerの役割

#025 DatePickerは呼び出し元INPUTと#024 Calendarを接続するPrimitive UIです。INPUT直後へCalendar triggerを生成し、panelは document.body 配下へ置き、開いたときに#024 Calendarを生成・同期します。選択結果は bone-datepicker:select Eventまたは onSelect callbackで返します。

DatePicker自身は呼び出し元 INPUT.value をcommit・書換しません。 選択結果をINPUTへ入れる必要がある場合は、呼び出し元がRETURNを受けて明示的に適用します。

DatePicker自身は OUT、invoke、Delivery Channel、WAIT/FIFO/BLOCKEDを所有しません。

2. HTML Functional Class `bf-datepicker`

2.1 最小利用

<input class="bf-datepicker" value="2026-08-10">

bf-datepicker を呼び出し元INPUTへ付けると、#025 RuntimeのDatePicker triggerをINPUT直後へ接続します。通常利用Classはこの1個だけです。Public API名を大量のClassへ変換する旧方式は使用しません。

2.2 設定付き利用

<input class="bf-datepicker"
       value="2026-08-10"
       min="2026-08-01"
       max="2027-08-10"
       step="1"
       data-theme="dark"
       data-icon-visual="emoji"
       data-week-start="auto"
       data-locale="ja-JP"
       data-show-tasks="true"
       data-close-on-select="true"
       data-panel-width="360"
       data-calendar-height="430"
       data-gap="6"
       aria-label="日付を選択">

HTML属性は BoneDatePickerFunctionalClass が同名Runtime optionへ変換し、最終検証は BoneDatePicker.create() / normalizeOptions() が行います。data-annotations はJSON Object文字列として読み、JSON自体を読めない場合はFunctional Class側で拒否します。

2.3 設定 → 実表示サンプル

ここでは「何を設定するとDatePickerのどこがどう変わるか」を実例で確認します。実表示 / Live Runtime は画像ではなく、DOCを開いているページの実 BoneDatePicker v1.0.10 と bf-datepicker をその場でmountします。各サンプルの「Calendarを開く」で実際の#024 Calendarまで確認してください。

Sample 1 — 基本

<input class="bf-datepicker" value="2026-08-10">

INPUT直後にCalendar triggerが生成されます。
triggerを押すと#024 CalendarをINPUTの下へ開きます。
日付を選んでもINPUT.valueは自動変更されません。

[[BF-DATEPICKER-SAMPLE:basic]]

Sample 2 — `min / max / step`

<input class="bf-datepicker" value="2026-08-10" min="2026-08-01" max="2026-08-31" step="3">

minより前、maxより後は選択不可です。
step不一致日も表示はされますが選択不可です。
範囲内の月移動と範囲外月停止は#024 Calendar契約に従います。

[[BF-DATEPICKER-SAMPLE:range]]

Sample 3 — `theme` 全4値

default: [[BF-DATEPICKER-SAMPLE:themeDefault]]
dark: [[BF-DATEPICKER-SAMPLE:themeDark]]
light: [[BF-DATEPICKER-SAMPLE:themeLight]]
neon: [[BF-DATEPICKER-SAMPLE:themeNeon]]

Sample 4 — `iconVisual` 全2値

fontawesome: 内蔵SVG calendar icon。 [[BF-DATEPICKER-SAMPLE:iconFa]]
emoji: 📅を表示し、#024 Annotationの絵文字表示も確認しやすくなります。 [[BF-DATEPICKER-SAMPLE:iconEmoji]]

Sample 5 — `weekStart` 全3値

auto + ja-JP: [[BF-DATEPICKER-SAMPLE:weekAuto]]
monday: [[BF-DATEPICKER-SAMPLE:weekMonday]]
sunday: [[BF-DATEPICKER-SAMPLE:sunday]]

Sample 6 — Annotation / `showTasks`

祝日 🎌、独自休日 🏖️、記念日 ⭐、Task dot/Tooltipは#024 Calendarへ委譲します。 [[BF-DATEPICKER-SAMPLE:annotations]]
showTasks=false はTaskだけを非表示にします。 [[BF-DATEPICKER-SAMPLE:tasksOff]]

Sample 7 — `readonly` / `disabled`

readonly=true: 読取専用Callerとしてtriggerを開けません。 [[BF-DATEPICKER-SAMPLE:readonly]]
disabled=true: 無効状態でtriggerを開けません。 [[BF-DATEPICKER-SAMPLE:disabled]]

Sample 8 — `closeOnSelect=false`

日付選択後もpanelを開いたままにします。 [[BF-DATEPICKER-SAMPLE:manualClose]]

Sample 9 — `panelWidth / calendarHeight / gap`

panel幅、Calendar高さ、INPUTとの縦間隔が変わります。 [[BF-DATEPICKER-SAMPLE:sizeGap]]

2.4 HTML宣言Property 全18件「設定 → 表示結果」早見

value — Default null。DatePicker内部の選択日を設定し、panelを開いたとき#024 Calendarの選択日として表示します。caller INPUT.value は書き換えません。
theme — Default default。生成Trigger/PanelのThemeを切替え、開いた#024 Calendarにも同じThemeを渡します。
iconVisual — Default fontawesome。fontawesome は内蔵SVGのCalendar icon、emoji は 📅 をTriggerに表示します。#024 Calendarへも同じvisualを渡すためAnnotationはemoji時に 🎌 / 🏖️ / ⭐ で見えます。
locale — Default null。#024 CalendarのLocale表示と weekStart=auto の解決に影響します。日付値のcommitは行いません。
weekStart — Default auto。開いたCalendarで曜日列の左端が変わります。auto は#024がlocale/環境から解決します。
min — Default null。minより前の日付を選択不可にします。#024 Calendarでは許可されたmin/maxの月範囲内は月移動可能で、min月より前へは移動しません。
max — Default null。maxより後の日付を選択不可にし、#024 Calendarはmax月より先への月移動を停止します。max月内のmax以前の日付は通常表示/選択判定されます。
step — Default 1。選択可能日の間隔を#024 Calendarへ渡します。条件外の日は消えず、表示されたまま選択不可になります。
annotations — Default null。開いたCalendarへAnnotationを表示します。emoji時は祝日 🎌、独自休日 🏖️、記念日 ⭐。taskはdot/Tooltipです。
showTasks — Default true。true はtask dot/Tooltipを表示、false はtaskだけ非表示。holiday/customHoliday/anniversaryは残ります。
disabled — Default false。Triggerをdisabledにします。開いている最中にtrueへ変えるとRuntimeがpanelを閉じ、close Event/Callbackを発行します。open() は {opened:false, reason:"not-editable"}。
readonly — Default false。DatePickerからの編集開始を禁止し、Triggerをdisabled表示にします。open() は not-editable で拒否されます。
closeOnSelect — Default true。true は日付選択→select Event/Callback→panel close。false はselect返却後もpanelを開いたままにします。
panelWidth — Default 360。document.body 配下のDatePicker panel幅を変更し、#024 Calendarのwidthにも同じ値を渡します。
calendarHeight — Default 430。panel内の#024 Calendar高さを変更します。
gap — Default 6。caller INPUT下端とpanel上端の距離を変更します。
className — Default 空文字 ""。create() 時に生成 .bone-datepicker rootへ追加Classとして付与します。
ariaLabel — Default 日付を選択。生成Triggerの aria-label を変更します。通常は画面上のpixel表示は変わりません。

onSelect / onOpen / onClose はRuntime optionですが、HTML文字列から関数を実行しないため通常HTML宣言Propertyには含めません。第4章のJavaScript専用Callbackとして扱います。

3. Default Property 全18件 — 個別Reference

ここでは bf-datepicker から通常HTML宣言できる18 Propertyを、実Runtime/Functional Classに合わせて説明します。型・Default・HTML指定・許容値/範囲・拒否条件・画面/動作結果・依存/競合を省略しません。

3.1 `value`

型: string / null
Runtime Default: null
HTML指定: data-value。未指定時はcaller INPUT.value を初回seedとして参照
許容値 / 範囲: YYYY-MM-DD の実在日付、または空/null
無効値 / 拒否: 不正日付は DATEPICKER_DATE_INVALID。min/max/step に合わない caller INPUT値は内部選択値へ採用しません。
設定した結果: DatePicker内部の選択日を設定し、panelを開いたとき#024 Calendarの選択日として表示します。caller INPUT.value は書き換えません。
注意 / 依存: 値変更は setOptions() ではなく setValue() を使います。Functional Classの属性変更時はBridgeが setValue() を呼びます。
関連: min / max / step / setValue() / getValue() / bone-datepicker:select

3.2 `theme`

型: enum
Runtime Default: default
HTML指定: data-theme
許容値 / 範囲: default / dark / light / neon
無効値 / 拒否: 上記以外は DATEPICKER_OPTION_ENUM_INVALID。
設定した結果: 生成Trigger/PanelのThemeを切替え、開いた#024 Calendarにも同じThemeを渡します。
注意 / 依存: setOptions() で開閉中を含め再描画されます。Themeは#022 Hover Border Effectとは別責務です。
関連: setOptions() / #024 Calendar theme

3.3 `iconVisual`

型: enum
Runtime Default: fontawesome
HTML指定: data-icon-visual
許容値 / 範囲: fontawesome / emoji
無効値 / 拒否: 上記以外は DATEPICKER_OPTION_ENUM_INVALID。
設定した結果: fontawesome は内蔵SVGのCalendar icon、emoji は 📅 をTriggerに表示します。#024 Calendarへも同じvisualを渡すためAnnotationはemoji時に 🎌 / 🏖️ / ⭐ で見えます。
注意 / 依存: 外部CDNは使用しません。Runtime Defaultは互換性維持のため fontawesome です。
関連: theme / annotations / #024 iconVisual

3.4 `locale`

型: string / null
Runtime Default: null
HTML指定: data-locale
許容値 / 範囲: ja-JP / en-US 等。実Runtime正規表現 ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$ に一致、または空/null
無効値 / 拒否: 不正形式は DATEPICKER_LOCALE_INVALID。
設定した結果: #024 CalendarのLocale表示と weekStart=auto の解決に影響します。日付値のcommitは行いません。
注意 / 依存: weekStart=monday/sunday を明示した場合、開始曜日はlocaleでは変わりません。
関連: weekStart / #024 resolveWeekStart()

3.5 `weekStart`

型: enum
Runtime Default: auto
HTML指定: data-week-start
許容値 / 範囲: auto / monday / sunday
無効値 / 拒否: 上記以外は DATEPICKER_OPTION_ENUM_INVALID。
設定した結果: 開いたCalendarで曜日列の左端が変わります。auto は#024がlocale/環境から解決します。
注意 / 依存: monday / sunday 明示時はlocaleよりこちらを優先します。
関連: locale / #024 Calendar

3.6 `min`

型: string / null
Runtime Default: null
HTML指定: native min または data-min
許容値 / 範囲: YYYY-MM-DD の実在日付、または空/null
無効値 / 拒否: 日付不正は DATEPICKER_DATE_INVALID。min > max は DATEPICKER_MIN_MAX_INVALID。
設定した結果: minより前の日付を選択不可にします。#024 Calendarでは許可されたmin/maxの月範囲内は月移動可能で、min月より前へは移動しません。
注意 / 依存: caller INPUTのnative min と data-min が両方ある場合、Functional Classは data-min を優先します。
関連: max / step / validateDate() / #024月移動境界

3.7 `max`

型: string / null
Runtime Default: null
HTML指定: native max または data-max
許容値 / 範囲: YYYY-MM-DD の実在日付、または空/null
無効値 / 拒否: 日付不正は DATEPICKER_DATE_INVALID。min > max は DATEPICKER_MIN_MAX_INVALID。
設定した結果: maxより後の日付を選択不可にし、#024 Calendarはmax月より先への月移動を停止します。max月内のmax以前の日付は通常表示/選択判定されます。
注意 / 依存: data-max がnative max より優先されます。
関連: min / step / validateDate() / #024月移動境界

3.8 `step`

型: integer / any
Runtime Default: 1
HTML指定: native step または data-step
許容値 / 範囲: 整数 1..3660 または文字列 any
無効値 / 拒否: 0、負数、小数、3660超、その他文字列は DATEPICKER_STEP_INVALID。
設定した結果: 選択可能日の間隔を#024 Calendarへ渡します。条件外の日は消えず、表示されたまま選択不可になります。
注意 / 依存: 判定基準日は#024 Calendarの正式 validateDate() 契約に従います。DatePicker独自のstep計算は持ちません。
関連: min / max / validateDate()

3.9 `annotations`

型: object / null
Runtime Default: null
HTML指定: data-annotations にJSON文字列
許容値 / 範囲: DOC-0024 Annotation契約のobject/null。kindは holiday / customHoliday / anniversary / task
無効値 / 拒否: HTML JSON構文不正は DATEPICKER_FUNCTIONAL_CLASS_ANNOTATIONS_INVALID。内容契約不正はpanel生成/更新時に#024 Calendar側が拒否します。
設定した結果: 開いたCalendarへAnnotationを表示します。emoji時は祝日 🎌、独自休日 🏖️、記念日 ⭐。taskはdot/Tooltipです。
注意 / 依存: DatePickerはAnnotation仕様を複製せず#024へ委譲します。
関連: showTasks / iconVisual / DOC-0024

3.10 `showTasks`

型: boolean
Runtime Default: true
HTML指定: data-show-tasks="true|false"
許容値 / 範囲: Functional Class: true/1/yes/on または false/0/no/off。Runtimeはbooleanとして正規化
無効値 / 拒否: HTMLで解釈できない値は DATEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID。
設定した結果: true はtask dot/Tooltipを表示、false はtaskだけ非表示。holiday/customHoliday/anniversaryは残ります。
注意 / 依存: Annotation自体を削除する設定ではありません。
関連: annotations / #024 showTasks

3.11 `disabled`

型: boolean
Runtime Default: false
HTML指定: native disabled または data-disabled
許容値 / 範囲: true / false（HTML boolean表現は上記と同じ）
無効値 / 拒否: HTML不正値は DATEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID。
設定した結果: Triggerをdisabledにします。開いている最中にtrueへ変えるとRuntimeがpanelを閉じ、close Event/Callbackを発行します。open() は {opened:false, reason:"not-editable"}。
注意 / 依存: data-disabled がnative disabled より優先。caller INPUT値は変更しません。
関連: readonly / open() / close()

3.12 `readonly`

型: boolean
Runtime Default: false
HTML指定: native readonly または data-readonly
許容値 / 範囲: true / false
無効値 / 拒否: HTML不正値は DATEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID。
設定した結果: DatePickerからの編集開始を禁止し、Triggerをdisabled表示にします。open() は not-editable で拒否されます。
注意 / 依存: disabledとは意味が異なりますが、DatePicker開閉可否では両方とも編集不可として扱います。
関連: disabled / open()

3.13 `closeOnSelect`

型: boolean
Runtime Default: true
HTML指定: data-close-on-select="true|false"
許容値 / 範囲: true / false
無効値 / 拒否: HTML不正値は DATEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID。
設定した結果: true は日付選択→select Event/Callback→panel close。false はselect返却後もpanelを開いたままにします。
注意 / 依存: close時には bone-datepicker:close / onClose も発生します。
関連: onSelect / onClose / bone-datepicker:select / close()

3.14 `panelWidth`

型: integer px
Runtime Default: 360
HTML指定: data-panel-width
許容値 / 範囲: 整数 240..1200 px
無効値 / 拒否: 非整数/範囲外は DATEPICKER_OPTION_NUMBER_INVALID。
設定した結果: document.body 配下のDatePicker panel幅を変更し、#024 Calendarのwidthにも同じ値を渡します。
注意 / 依存: viewport右端を越える場合、positioning処理がleftを8px以上の範囲へ補正します。
関連: calendarHeight / gap / reposition()

3.15 `calendarHeight`

型: integer px
Runtime Default: 430
HTML指定: data-calendar-height
許容値 / 範囲: 整数 260..1200 px
無効値 / 拒否: 非整数/範囲外は DATEPICKER_OPTION_NUMBER_INVALID。
設定した結果: panel内の#024 Calendar高さを変更します。
注意 / 依存: DatePicker panel自身の横幅は panelWidth。縦方向のanchor間隔は gap。
関連: panelWidth / gap / #024 height

3.16 `gap`

型: integer px
Runtime Default: 6
HTML指定: data-gap
許容値 / 範囲: 整数 0..64 px
無効値 / 拒否: 非整数/範囲外は DATEPICKER_OPTION_NUMBER_INVALID。
設定した結果: caller INPUT下端とpanel上端の距離を変更します。
注意 / 依存: open時、resize/scroll時、reposition() 時に同じgapで再計算されます。
関連: panelWidth / reposition()

3.17 `className`

型: string
Runtime Default: 空文字 ""
HTML指定: data-class-name
許容値 / 範囲: 任意文字列。Runtimeでtrim
無効値 / 拒否: 専用Errorなし。
設定した結果: create() 時に生成 .bone-datepicker rootへ追加Classとして付与します。
注意 / 依存: 現Runtime v1.0.10ではcreate後に setOptions({className:...}) してもroot classは付け替わりません。 後から見た目を変える用途には使わず、mount前に指定してください。通常利用Class bf-datepicker を置き換えるものではありません。
関連: create() / Functional Class mount

3.18 `ariaLabel`

型: string
Runtime Default: 日付を選択
HTML指定: data-aria-label または caller aria-label
許容値 / 範囲: 空でない文字列。空/未指定はRuntime Default
無効値 / 拒否: 専用Errorなし。値は文字列化されます。
設定した結果: 生成Triggerの aria-label を変更します。通常は画面上のpixel表示は変わりません。
注意 / 依存: setOptions() 後もrenderで更新されます。Functional Classは data-aria-label をcaller aria-label より優先します。
関連: Accessibility / setOptions()

4. JavaScript専用Callback 全3件

callbackはRuntime option 21件の一部ですが、HTML Functional ClassはHTML属性内の文字列を関数としてevalしません。通常HTML利用では対応するCustom Eventを使用します。

4.1 `onSelect`

型: function / null
Runtime Default: null
HTML指定: なし（JavaScript API専用）
発火時点: #024 Calendarで選択が成立し、DatePicker内部 selectedValue を更新した直後。
受取payload: componentId / componentName / version / value / anchorValue / date / previousValue / source / calendarDetail。frozen objectです。
画面/状態: closeOnSelect=true ならselect Event/Callbackの後にcloseします。caller INPUT.value は自動commitしません。
不正型: DATEPICKER_CALLBACK_INVALID
代替HTML経路: bone-datepicker:select Custom Event。

4.2 `onOpen`

型: function / null
Runtime Default: null
HTML指定: なし（JavaScript API専用）
発火時点: panelを表示し、#024 Calendar生成/同期・position計算が完了した後。
受取payload: 共通payload + source。APIなら api、Triggerなら trigger、toggle経路なら toggle。
画面/状態: disabled / readonly でopen拒否された場合は発火しません。
不正型: DATEPICKER_CALLBACK_INVALID
代替HTML経路: bone-datepicker:open Custom Event。

4.3 `onClose`

型: function / null
Runtime Default: null
HTML指定: なし（JavaScript API専用）
発火時点: 開いていたpanelをhiddenにし、is-open 状態を解除した後。
受取payload: 共通payload + source。api / toggle / outside / escape / select / not-editable 等、閉じた経路を識別できます。
画面/状態: 既にclosedの close() は {closed:false,reason:"already-closed"} を返し、Callback/Eventは発火しません。
不正型: DATEPICKER_CALLBACK_INVALID
代替HTML経路: bone-datepicker:close Custom Event。

5. 日付・範囲・step

`value`

value はDatePicker内部の選択値です。生成時は明示 options.value が優先され、無ければcaller INPUT.valueが実在かつmin/max/step上selectableの場合だけ初期値として採用されます。setValue() は内部値を変更しますがcaller INPUT.valueは変更しません。

`min / max`

min と max は#024 Calendarへ委譲されます。min <= max が必須です。範囲外日付は非selectableです。範囲内月の移動は可能で、min月より前・max月より後への移動停止は完成済み#024 Calendarの契約に従います。

`step`

step=1 は日単位、2以上はminまたは#024基準日からの間隔で選択可能日を絞り、any はstep制約を外します。許容範囲は1～3660またはanyです。

6. Theme / Icon 全値

`theme` 全4値

default: Runtime標準配色。
dark: 暗色配色。
light: 明色配色。
neon: ネオンaccent配色。

`iconVisual` 全2値

fontawesome: 外部CDNではなくRuntime内蔵SVG calendar icon。
emoji: DatePicker triggerは📅。#024 Annotationでは 🎌 / 🏖️ / ⭐ を使用できます。

7. 表示・基本操作Property

`disabled`

trueではtrigger無効。open中にtrueへ変えるとRuntimeが閉じます。

`readonly`

trueではread-only Callerとしてtrigger無効。DatePickerからの編集操作を開始しません。

`closeOnSelect`

trueは選択後にclose、falseは選択後もopen維持。どちらでも選択結果はEvent/callbackでRETURNし、INPUT.valueは自動commitしません。

`className`

生成 .bone-datepicker rootへ任意Classを追加します。通常利用Class bf-datepicker はcaller INPUT側に置くため役割が異なります。

`ariaLabel`

triggerのaria-label。視覚表示は通常変えず、支援技術向け名称を設定します。

8. `weekStart` と `locale`

`weekStart=auto`

locale を#024へ渡し、#024の開始曜日判定に従います。テスト契約では ja-JP は月曜、en-US は日曜を確認しています。

`weekStart=monday`

localeに関係なく月曜日を左端にします。

`weekStart=sunday`

localeに関係なく日曜日を左端にします。

`locale`

受理形式は英字2～3文字を先頭に、- 区切りの英数字subtagを続ける形式です。不正形式は DATEPICKER_LOCALE_INVALID。

9. Annotation と `showTasks`

DatePickerはAnnotationを独自描画せず、#024 Calendarへ委譲します。data-annotations はJSON Object文字列です。

祝日: kind="holiday" → emoji modeでは 🎌
独自休日: kind="customHoliday" → 🏖️
記念日: kind="anniversary" → ⭐
Task: kind="task" → dot / Tooltip。showTasks=falseでTaskだけ非表示。

Annotation構造、href Security、Tooltip等の正式詳細は DOC-0024 を参照します。

10. Panelサイズ・配置

`panelWidth`

240～1200px。body配下panelの幅。viewport右端を越える場合はRuntimeがleftを補正します。

`calendarHeight`

260～1200px。内部#024 Calendarのheightへ委譲します。

`gap`

0～64px。caller INPUTのbottomとpanel topの縦間隔です。

`reposition()`

open中だけcallerの最新 getBoundingClientRect()、panelWidth、gap、viewport幅を使ってleft/topを再計算します。Runtimeはwindow resizeとscrollでも再配置します。

11. #022 Hover Border Effect連携

#025 DatePicker Runtime自体は#022を内包しません。テストUIでは次の2系統を独立設定します。

11.1 DatePicker外枠Effect

caller INPUTと生成triggerを含む #caller-host へ #022 trigger=mouseover をattachします。

11.2 #024 Calendar日付セルEffect

DatePickerを開いた後の .bone-calendar__day 各セルへ #022 trigger=mouseover をattachします。#024が月移動等で日付セルを再描画するため、再描画後は新しいセルへ再attachします。

11.3 #022設定値

effect: normal / neon / spin / cross / blink
direction: clockwise / counterclockwise
speed: slow / normal / fast
spinWidth: 1～24px
spinGlow: 0～40px
color: #040 ColorPickerのsolid-only Callerから受ける色

これらは#025 DatePickerのRETURN契約とは別責務です。#022 Runtimeを#025へ複製しません。

12. #040 ColorPickerとの責務分離

#025テストUIのDatePicker外枠Effect色とCalendar日付Effect色は#040 ColorPicker Caller APIを使用します。Consumer側はsolid-onlyで、Native <input type="color"> を追加しません。#040は「色を選ぶ」責務、#025は「返された色を#022設定へ渡す」テストUI責務です。DatePicker Runtime optionには色Propertyはありません。

13. 操作

Triggerクリック

closedならopen、openならcloseします。disabled/readonlyでは開きません。

日付選択

#024 Calendarで選択するとDatePicker内部selectedValueを更新し、bone-datepicker:select / onSelect を発行します。closeOnSelect=trueならその後closeします。

Escape

open中にEscapeでcloseし、生成triggerへfocusを戻します。

外側pointer

caller INPUT、DatePicker root、panelの外側をpointerdownするとcloseします。

resize / scroll

open中ならpanelをcaller INPUT直下へ再配置します。

RETURNをINPUTへ反映

DatePickerはINPUT.valueを変更しません。呼び出し元が bone-datepicker:select の detail.date またはonSelect payloadを受けて明示的に適用します。

14. Security

options / patchはplain objectだけを受理します。
theme/iconVisual/weekStartは列挙値検証。
value/min/maxは#024を利用して実在日付検証。
localeは形式検証。
panelWidth/calendarHeight/gapは整数範囲検証。
callbackはfunction/nullだけ。HTML文字列をevalしません。
data-annotations はJSON parseし、不正JSONを拒否します。
Annotation href等のCalendar内部Securityは#024契約へ委譲します。

15. #002 Joint / WAIT / FIFO / BLOCKED

#025自身はOUT Deliveryを所有しません。したがってDatePicker内部にWAIT Queue、FIFO Delivery、BLOCKED配送はありません。テスト画面の接続イメージは#002 Bone Jointの実判定/実描画を使用し、選択RETURNをConsumerがcommit/Deliveryする場合の接続責務はConsumer + #002側です。

DatePickerへ見た目だけのWAIT/BLOCKED実装を追加しません。

16. Event / Callback

`bone-datepicker:open` / `onOpen`

panel open後に発行。payloadにはcomponent情報、DatePicker内部value、callerのanchorValue、sourceを含みます。

`bone-datepicker:close` / `onClose`

panel close後に発行。sourceはapi/select/escape/outside等の経路を示します。

`bone-datepicker:select` / `onSelect`

日付選択後に発行。date、previousValue、anchorValue、#024からのcalendarDetailを含みます。caller INPUT.valueはこの発行だけでは変更されません。

17. Public API 全17件

通常HTML利用は bf-datepicker を使用します。以下17 APIは高度なJavaScript操作・診断用の正式Public APIです。内部DOMを直接変更する代わりにPublic APIを使用します。個別APIはTOCを過密にしないため第4階層見出しにしています。

17.1 Public API 詳細

1. `create(input, options)`

用途: caller要素の直後にTrigger rootを生成し、panelを document.body 配下へ準備します。
引数: input: getBoundingClientRect() を持つElement。options: plain object（省略可）。
戻り値: 生成した .bone-datepicker root Element。
状態 / DOM変化: Trigger/root生成。panelはbodyへ追加されますが、#024 Calendar本体は最初のopen時に生成されます。caller INPUT.valueは変更しません。
Event / Callback: 作成だけではEvent/Callbackを発火しません。
Error / 拒否: 依存#024が無い/非互換、DOM無し、anchor不正、options/各Property不正で対応Errorをthrow。
関連: destroy() / open() / bf-datepicker mount
使用例:

const picker = BoneDatePicker.create(input, { theme: 'dark', min: '2026-08-01', max: '2027-08-10' });

2. `destroy(picker)`

用途: DatePickerを破棄し、listener、内部#024 Calendar、body-owned panel、DatePicker rootを除去します。
引数: picker: create() が返した登録rootそのもの。
戻り値: 登録rootなら true、未登録なら false。
状態 / DOM変化: インスタンスをWeakMapから削除し、関連DOMを除去します。caller INPUT自体は残します。
Event / Callback: 破棄Eventは定義されていません。
Error / 拒否: 未登録rootは例外ではなく false。descendantを渡してもdestroy対象にはなりません。
関連: create() / Functional Class unmount()
使用例:

BoneDatePicker.destroy(picker);

3. `setOptions(picker, patch)`

用途: 既存optionへpatchをマージ・正規化し、Trigger/Panel/既存Calendarへ反映します。
引数: picker: rootまたはそのdescendant。patch: plain object。
戻り値: 同じDatePicker root。
状態 / DOM変化: Theme/disabled/readonly/panelWidth等を再描画。disabled/readonlyをtrueにしてopen中ならcloseします。
Event / Callback: open中にnot-editableへ変えた場合はclose Event/Callbackが発生します。
Error / 拒否: instance不明、patch非plain object、各option不正。patch.value は内部selectedValueで上書きされるため値変更には setValue() を使用。
関連: getOptions() / setValue() / render
使用例:

BoneDatePicker.setOptions(picker, { theme: 'neon', closeOnSelect: false });

4. `getOptions(picker)`

用途: 現在の正規化済みoption状態を診断/保存用に取得します。
引数: picker: rootまたはdescendant。
戻り値: 現在optionのfrozen copy。
状態 / DOM変化: 状態変更なし。返却objectを変更してもRuntime内部には反映されません。
Event / Callback: なし。
Error / 拒否: instance不明で DATEPICKER_INSTANCE_NOT_FOUND。
関連: setOptions() / normalizeOptions()
使用例:

const options = BoneDatePicker.getOptions(picker);

5. `setValue(picker, value)`

用途: DatePicker内部選択値を変更し、Calendar生成済みなら#024側の値も同期します。
引数: picker: rootまたはdescendant。value: YYYY-MM-DD またはnull/空。
戻り値: 同じDatePicker root。
状態 / DOM変化: selectedValue を変更。caller INPUT.valueは変更しません。
Event / Callback: setValue単独ではselect Event/Callbackを発火しません。
Error / 拒否: instance不明、実在日付不正でError。min/max/stepの選択可否をこのAPI自体では再検査しません。
関連: getValue() / caller側commit責務
使用例:

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

6. `getValue(picker)`

用途: DatePickerが保持している内部選択値を取得します。
引数: picker: rootまたはdescendant。
戻り値: YYYY-MM-DD または null。
状態 / DOM変化: 状態変更なし。caller INPUT.valueとは別値として保持されます。
Event / Callback: なし。
Error / 拒否: instance不明でError。
関連: setValue() / bone-datepicker:select
使用例:

const selected = BoneDatePicker.getValue(picker);

7. `getAnchor(picker)`

用途: DatePicker作成時のcaller/anchor要素を取得します。
引数: picker: rootまたはdescendant。
戻り値: 元caller Element。
状態 / DOM変化: 状態変更なし。
Event / Callback: なし。
Error / 拒否: instance不明でError。
関連: create() / reposition()
使用例:

const input = BoneDatePicker.getAnchor(picker);

8. `getPanel(picker)`

用途: document.body 配下にあるDatePicker panelを診断用途で取得します。
引数: picker: rootまたはdescendant。
戻り値: panel Element。
状態 / DOM変化: 状態変更なし。
Event / Callback: なし。
Error / 拒否: instance不明でError。内部DOMの直接改変は通常利用契約外。
関連: open() / close() / reposition()
使用例:

const panel = BoneDatePicker.getPanel(picker);

9. `getCalendar(picker)`

用途: DatePicker内部の#024 Calendar Elementを取得します。
引数: picker: rootまたはdescendant。
戻り値: 初回open前は null、生成後は#024 Calendar Element。
状態 / DOM変化: 状態変更なし。
Event / Callback: なし。
Error / 拒否: instance不明でError。Calendarを必要とする高度連携は#024 Public API経由で行います。
関連: open() / DOC-0024
使用例:

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

10. `open(picker)`

用途: panelを開きます。caller INPUT.valueが前回snapshotから変化していれば、選択可能な日付だけ内部選択値へ再同期します。
引数: picker: rootまたはdescendant。
戻り値: 成功: frozen {opened:true,event}。disabled/readonly: {opened:false,reason:"not-editable"}。
状態 / DOM変化: #024 Calendarを必要なら生成/同期し、panel表示・位置計算・is-open状態を更新します。
Event / Callback: 成功時 bone-datepicker:open と onOpen。payload source="api"。
Error / 拒否: instance不明、Calendar依存不正等。disabled/readonlyはthrowせず結果で拒否。
関連: close() / toggle() / isOpen()
使用例:

const result = BoneDatePicker.open(picker);

11. `close(picker)`

用途: 開いているpanelを閉じます。
引数: picker: rootまたはdescendant。
戻り値: 成功: {closed:true,event}。既に閉: {closed:false,reason:"already-closed"}。
状態 / DOM変化: panel hidden、is-open解除。内部選択値/Calendarは保持します。
Event / Callback: 成功時 bone-datepicker:close と onClose。payload source="api"。
Error / 拒否: instance不明でError。既に閉はthrowしません。
関連: open() / toggle()
使用例:

BoneDatePicker.close(picker);

12. `toggle(picker)`

用途: 現在のopen状態に応じてopen/closeを切替えます。
引数: picker: rootまたはdescendant。
戻り値: open経路またはclose経路の結果object。
状態 / DOM変化: 閉→開、開→閉。
Event / Callback: 経路に応じてopen/close Event/Callback。sourceは toggle。
Error / 拒否: 各経路と同じ。
関連: open() / close() / isOpen()
使用例:

BoneDatePicker.toggle(picker);

13. `isOpen(picker)`

用途: panelが現在openか確認します。
引数: picker: rootまたはdescendant。
戻り値: boolean。
状態 / DOM変化: 状態変更なし。
Event / Callback: なし。
Error / 拒否: instance不明でError。
関連: open() / close()
使用例:

if (BoneDatePicker.isOpen(picker)) BoneDatePicker.close(picker);

14. `reposition(picker)`

用途: caller rectとviewport、panelWidth、gapからpanel位置を再計算します。
引数: picker: rootまたはdescendant。
戻り値: open中で再配置したら true、closedなら false。
状態 / DOM変化: panel left/top/width を更新。右端超過時はviewport内へ補正し、leftは最低8px。
Event / Callback: なし。
Error / 拒否: instance不明でError。closedはfalseで終了。
関連: gap / panelWidth / resize / scroll
使用例:

BoneDatePicker.reposition(picker);

15. `validateDate(value, options)`

用途: Pickerを生成せず日付形式とmin/max/step選択可否を検査します。最終判定は#024 validateDate() へ委譲します。
引数: value: 日付。options: min/max/step等の任意option。
戻り値: frozen {valid, selectable, value, code, message}。
状態 / DOM変化: 状態変更なし。
Event / Callback: なし。
Error / 拒否: このAPIは内部Errorをthrowせず、valid:false の code/message に変換して返します。
関連: #024 validateDate() / min / max / step
使用例:

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

16. `normalizeOptions(options)`

用途: create/setOptionsと同じ正規化契約でoptionを検証・Default補完します。
引数: plain object、null/undefined。
戻り値: 21 optionを持つfrozen object（HTML宣言18 + callback3）。
状態 / DOM変化: DOM/instance状態は変更しません。
Event / Callback: なし。
Error / 拒否: options/enum/number/locale/date/step/callback/min-max不正をthrow。value/min/maxが非空なら日付検証のため#024依存も必要。
関連: create() / setOptions() / defaults
使用例:

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

17. `isInstance(element)`

用途: ElementがDatePickerの登録rootそのものか判定します。
引数: 任意値。
戻り値: boolean。
状態 / DOM変化: 状態変更なし。
Event / Callback: なし。
Error / 拒否: 例外なし。descendantはfalseで、getState系APIのようなclosest解決はしません。
関連: create() / destroy()
使用例:

if (BoneDatePicker.isInstance(picker)) { /* registered root */ }

Picker Panelのviewport配置

Picker Panelは通常INPUTの下へ表示します。下側にcalendarHeight分の表示領域がない場合はINPUTの上へ自動反転します。上側・下側のどちらにも完全に収まらない場合は、Panelの上端をviewport内へclampして、画面外へ完全に消えないようにします。scroll / resize 時も再計算します。

18. Error Code

Error Codeは「名前を列挙するだけ」ではなく、意味 / 発生条件 / 発生API / 不正例 / 正しい例 / 修正方法まで確認します。Runtime ErrorとHTML Functional Class Integration Errorを分離します。

18.1 Runtime Error

DATEPICKER_OPTIONS_INVALID

意味: optionsまたはsetOptions patchがplain objectではありません。
発生条件: normalizeOptions() / create() のoptions、setOptions() のpatchへ配列・文字列・Date等を渡した場合。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: BoneDatePicker.setOptions(picker, [])
正しい例: BoneDatePicker.setOptions(picker, { theme:"dark" })
修正方法: 設定を {...} のplain objectへ直します。

DATEPICKER_OPTION_ENUM_INVALID

意味: enum Propertyが許容値外です。
発生条件: theme / iconVisual / weekStart に未定義値を指定。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: { theme:"blue" }
正しい例: { theme:"default" }
修正方法: DOC記載の全許容値から選択します。

DATEPICKER_OPTION_NUMBER_INVALID

意味: サイズ/間隔の整数Propertyが範囲外です。
発生条件: panelWidth 240..1200、calendarHeight 260..1200、gap 0..64 の整数条件を外れた場合。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: { panelWidth:100, gap:1.5 }
正しい例: { panelWidth:360, gap:6 }
修正方法: 整数かつ各範囲内へ修正します。

DATEPICKER_LOCALE_INVALID

意味: locale形式がRuntimeの許容language-tag形式に一致しません。
発生条件: locale が ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$ に一致しない場合。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: { locale:"ja_JP" }
正しい例: { locale:"ja-JP" }
修正方法: ハイフン区切りの許容形式へ修正します。

DATEPICKER_DATE_INVALID

意味: value/min/maxが実在する YYYY-MM-DD 日付ではありません。
発生条件: 形式不正、存在しない日付をvalue/min/maxへ指定。
発生API / 経路: create() / setOptions() / setValue() / normalizeOptions()
不正例: { value:"2026-02-30" }
正しい例: { value:"2026-02-28" }
修正方法: 実在日付へ修正します。

DATEPICKER_STEP_INVALID

意味: stepが正式範囲外です。
発生条件: any 以外で、1..3660の整数ではない値を指定。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: { step:0 } / { step:1.5 }
正しい例: { step:1 } / { step:"any" }
修正方法: 1..3660整数または any を指定します。

DATEPICKER_CALLBACK_INVALID

意味: JavaScript callbackの型が不正です。
発生条件: onSelect / onOpen / onClose にfunction/null以外を指定。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: { onSelect:"handler" }
正しい例: { onSelect:(detail)=>{} }
修正方法: HTML属性へ関数文字列を書かず、JavaScriptからfunctionを渡します。

DATEPICKER_MIN_MAX_INVALID

意味: 日付範囲の前後関係が不正です。
発生条件: min > max。
発生API / 経路: create() / setOptions() / normalizeOptions()
不正例: { min:"2026-12-31", max:"2026-01-01" }
正しい例: { min:"2026-01-01", max:"2026-12-31" }
修正方法: min <= max に修正します。

DATEPICKER_DEPENDENCY_CALENDAR_MISSING

意味: #024 Calendarの正式Public APIが見つかりません。
発生条件: BoneCalendar が無い、componentIdが024でない、または必須 create/setOptions/setValue/getValue/destroy/validateDate が不足。
発生API / 経路: create()、日付正規化、初回open/Calendar同期など依存確認経路
不正例: DatePickerだけを先に読み込む
正しい例: #024 Calendar RuntimeをDatePickerより先に読み込む
修正方法: DOC-0024の正式Runtime/Public APIを配置し、読込順を確認します。

DATEPICKER_DEPENDENCY_CALENDAR_VERSION

意味: #024 Calendarのversion互換条件を満たしていません。
発生条件: minimum 1.0.13、同一major.minorでpatch >= 13 ではない場合。
発生API / 経路: create()、Calendar依存を必要とする各経路
不正例: BoneCalendar.version="1.0.12"
正しい例: 1.0.13 または互換上位patch（例: 1.0.15）
修正方法: #024を互換versionへ更新します。別major/minorはpatchが高くても受理しません。

DATEPICKER_DOM_REQUIRED

意味: DatePicker生成に必要なDOM環境がありません。
発生条件: document または document.createElement が利用できない環境で create()。
発生API / 経路: create()
不正例: DOM無しNode環境でUI生成
正しい例: Browser/DOM環境で create()
修正方法: 非DOM環境ではUI生成を行わず、必要なら純粋検証APIだけを使用します。

DATEPICKER_ANCHOR_INVALID

意味: createのcaller/anchorが有効なElementではありません。
発生条件: nodeType=1かつ getBoundingClientRect() を持つElement以外を指定。
発生API / 経路: create()
不正例: BoneDatePicker.create(null,{})
正しい例: BoneDatePicker.create(document.querySelector("input"),{})
修正方法: 実DOM Elementを渡します。

DATEPICKER_INSTANCE_NOT_FOUND

意味: Public APIが登録DatePickerを解決できません。
発生条件: getStateを使うAPIへ、登録root/そのdescendantではない要素を渡した場合。
発生API / 経路: setOptions/getOptions/setValue/getValue/getAnchor/getPanel/getCalendar/open/close/toggle/isOpen/reposition
不正例: BoneDatePicker.open(document.body)
正しい例: BoneDatePicker.open(picker)
修正方法: create() が返したrootまたはその配下要素を使用します。destroy() / isInstance() はrootそのものを使用します。

18.2 HTML Functional Class Integration Error

DATEPICKER_FUNCTIONAL_CLASS_RUNTIME_MISSING

意味: bf-datepicker Bridgeが#025 Runtimeを見つけられません。
発生条件: BoneDatePicker が未読込、componentId不一致、create API不足。
発生API / 経路: Functional Class mount() / refresh() / unmount() のRuntime呼出し経路
不正例: Functional Class JSをRuntimeより先に実行
正しい例: #025 Runtimeを先に読み込み、その後Functional Class Bridgeを読み込む
修正方法: script読込順と BoneDatePicker.componentId="025" を確認します。

DATEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID

意味: HTML boolean属性を解釈できません。
発生条件: data-show-tasks / data-close-on-select / data-disabled / data-readonly が許容表現外。
発生API / 経路: Functional Class readOptions() / mount / refresh
不正例: data-disabled="maybe"
正しい例: data-disabled="true"
修正方法: true/1/yes/on または false/0/no/off を使用します。

DATEPICKER_FUNCTIONAL_CLASS_ANNOTATIONS_INVALID

意味: data-annotations がJSONとして解析できません。
発生条件: 属性文字列が JSON.parse() できない場合。
発生API / 経路: Functional Class readOptions() / mount / refresh
不正例: data-annotations="{'bad':1}"
正しい例: 有効なJSON（property名/文字列はダブルクォート）
修正方法: まずJSON構文を直します。JSON構文後のAnnotation内容契約は#024 Calendarが検証します。

DATEPICKER_FUNCTIONAL_CLASS_ANCHOR_INVALID

意味: Functional Class helperへ有効な bf-datepicker Elementが渡されていません。
発生条件: Elementでない、classList無し、または bf-datepicker Classを持たない対象をmount/refresh。
発生API / 経路: Functional Class mount() / refresh()
不正例: BoneDatePickerFunctionalClass.mount(document.body)
正しい例: BoneDatePickerFunctionalClass.mount(document.querySelector('.bf-datepicker'))
修正方法: caller INPUT等の対象Elementへ class="bf-datepicker" を付けてからmountします。

19. HTML Functional Class Lifecycle

bf-datepicker はDOMContentLoaded後に既存対象をscanし、後からDOMへ追加された対象もMutationObserverでmountします。対象属性が変わるとrefresh()し、Classが外れるとunmount()します。

補助APIは BoneDatePickerFunctionalClass.mount / refresh / unmount / getInstance / readOptions / scan ですが、通常利用HTML Classは bf-datepicker 1個のままです。

20. トラブル時の確認

DOC-0025が開かない

共有 bone-doc-loader.js / bone-doc-guide.js / bone-doc-guide.css が既存Bone Flow環境にあり、DOC/TOC Registryへpatchがmergeされているか確認します。#025パッケージは共有DOCファイルを上書きしません。

Calendarボタンが出ない

#024 Calendar、#025 DatePicker、bone-datepicker-functional-class.js の読込順と bf-datepicker Classを確認します。

開かない

disabled / readonly と open() のreasonを確認します。

日付を選べない

min / max / step と#024 Calendarのselectable判定を確認します。

INPUT.valueが変わらない

正常です。DatePickerはRETURNのみです。bone-datepicker:selectまたはonSelectの値を呼び出し元が明示的に適用します。

Annotationが表示されない

data-annotations JSON、showTasks、iconVisual、DOC-0024のAnnotation契約を確認します。

Effectが消える

DatePickerを開いた後に#024が日付セルを再描画した場合は、新しい日付セルへ#022を再attachする必要があります。

21. 責務境界

#025 DatePicker: caller INPUTとCalendar trigger/panel、open/close、DatePicker内部selectedValue、RETURN Event/callback、panel配置。
#024 Calendar: 日付grid、月移動、min/max/step、Theme、weekStart、Annotation、日付selectable。
#022 Hover Border Effect: Mouse Over枠Effect。
#040 ColorPicker: Effect色選択Caller。
#002 Joint / Consumer: 接続・Delivery・WAIT/FIFO/BLOCKED・最終commit。

#025 DatePickerは入力値の最終commitを所有しません。

#025 DatePicker

bf-datepicker

正式ガイド DOC-0025

DOC-0025 — DatePicker 操作・HTML Functional Class

0. 文書情報

1. DatePickerの役割

2. HTML Functional Class bf-datepicker

2.1 最小利用

2.2 設定付き利用

2.3 設定 → 実表示サンプル

Sample 1 — 基本

Sample 2 — min / max / step

Sample 3 — theme 全4値

Sample 4 — iconVisual 全2値

Sample 5 — weekStart 全3値

Sample 6 — Annotation / showTasks

Sample 7 — readonly / disabled

Sample 8 — closeOnSelect=false

Sample 9 — panelWidth / calendarHeight / gap

2.4 HTML宣言Property 全18件「設定 → 表示結果」早見

3. Default Property 全18件 — 個別Reference

3.1 value

3.2 theme

3.3 iconVisual

3.4 locale

3.5 weekStart

3.6 min

3.7 max

3.8 step

3.9 annotations

3.10 showTasks

3.11 disabled

3.12 readonly

3.13 closeOnSelect

3.14 panelWidth

3.15 calendarHeight

3.16 gap

3.17 className

3.18 ariaLabel