# DOC-0026 — TimePicker 操作・HTML Functional Class ## 0. 文書情報 - DOC ID: `DOC-0026` - TOC ID: `TOC-0026` - UI: `UI-026` / `#026 TimePicker` - Runtime: `BoneTimePicker v1.0.23` - DOC Integration: `1.0.7` - 通常利用HTML Functional Class: `bf-timepicker` - Shared DOC: `bone-doc-loader.js / bone-doc-guide.js / bone-doc-guide.css`（#026固有都合で変更しない） ## 1. TimePickerの役割 #026はCaller INPUT近傍へ時刻選択Panelを表示する共通Picker UIです。下側にPanel全体が収まる場合は下、収まらない場合は上へ自動flipし、上下どちらにも収まらない場合はviewport内へclampします。選択した時刻だけをRETURNします。Caller INPUT.valueのcommit、Bone.value、OUT、Security Gate、Delivery、WAIT/FIFO/BLOCKEDはCaller側の責務です。 - 24時間制。秒非表示時 `HH:mm`、秒表示時 `HH:mm:ss`。 - TriggerはCaller INPUT直後、Panelは`document.body`所有。 - Hourは00–23、Minuteは`step`、Secondは00–59。 - `step`は分列だけに適用し、秒列を間引きません。 - #022 Hover Border EffectはCaller INPUT＋時計Trigger全体の外周Mouse Over効果だけを担当します。Picker Panel / Hour / Minute / Second optionには適用しません。 - #040 ColorPickerはEffect色のsolid-only選択を担当。 ## 2. HTML Functional Class `bf-timepicker` ### 2.1 最小利用 ```html ``` `bf-timepicker`を付けるとFunctional Class Bridgeが実`BoneTimePicker.create()`を呼びます。通常利用Classはこれ1個です。旧`bone-html-class-use`やAPI別Classは通常利用仕様ではありません。 [[BF-TIMEPICKER-SAMPLE:basic]] ### 2.2 設定付き利用 ```html ``` ### 2.3 設定 → 実表示サンプル #### Sample 1 — 基本 09:30を初期値として時計Triggerを生成します。 [[BF-TIMEPICKER-SAMPLE:basic]] #### Sample 2 — `min / max / step` 08:00～18:00、15分刻み。分列は00/15/30/45になります。 [[BF-TIMEPICKER-SAMPLE:range]] #### Sample 3 — `theme` 全4値以下4つは同じ時刻でThemeだけを変えます。 [[BF-TIMEPICKER-SAMPLE:themeDefault]] [[BF-TIMEPICKER-SAMPLE:themeDark]] [[BF-TIMEPICKER-SAMPLE:themeLight]] [[BF-TIMEPICKER-SAMPLE:themeNeon]] #### Sample 4 — `iconVisual` 全2値 Font Awesome互換SVGと🕒を切替えます。 [[BF-TIMEPICKER-SAMPLE:iconFa]] [[BF-TIMEPICKER-SAMPLE:iconEmoji]] #### Sample 5 — 秒列 `showSecond=true`で秒列00～59を表示します。step=15でも秒は1秒刻みです。 [[BF-TIMEPICKER-SAMPLE:seconds]] #### Sample 6 — 列表示時だけ、分だけ等を確認します。全列OFFはErrorです。 [[BF-TIMEPICKER-SAMPLE:hourOnly]] [[BF-TIMEPICKER-SAMPLE:minuteOnly]] #### Sample 7 — `locale` 英語LocaleではHour/Minute/Second、Select/Cancel表記になります。 [[BF-TIMEPICKER-SAMPLE:localeEn]] #### Sample 8 — `readonly / disabled` どちらもTriggerが無効になりopenを拒否します。 [[BF-TIMEPICKER-SAMPLE:readonly]] [[BF-TIMEPICKER-SAMPLE:disabled]] #### Sample 9 — `closeOnSelect=false` 選択確定後もPanelを開いたままにします。 [[BF-TIMEPICKER-SAMPLE:manualClose]] #### Sample 10 — `panelWidth / gap` Panel幅とINPUT下端からの間隔を変更します。 [[BF-TIMEPICKER-SAMPLE:sizeGap]] ### 2.4 HTML宣言Property 全22件「設定 → 表示結果」早見 - `value` — 初期選択値。秒列非表示は HH:mm、表示時は HH:mm:ss。Caller INPUT.valueが有効ならRuntimeはそちらも初期seedとして読みます。 HTML: `data-value` / Default: `null` - `theme` — 外観Theme。default / dark / light / neon の4値。 HTML: `data-theme` / Default: `default` - `iconVisual` — 時計Triggerの表示。fontawesome / emoji の2値。 HTML: `data-icon-visual` / Default: `fontawesome` - `locale` — 列見出し・ボタン文言のLocale。言語タグ形式。 HTML: `data-locale` / Default: `ja-JP` - `showHour` — 時列(00–23)を表示。 HTML: `data-show-hour` / Default: `true` - `showMinute` — 分列を表示。分候補はstepで間引かれます。 HTML: `data-show-minute` / Default: `true` - `showSecond` — 秒列(00–59)を表示。ONではvalue/min/maxはHH:mm:ss形式。 HTML: `data-show-second` / Default: `false` - `min` — 選択可能な最小時刻。 HTML: `data-min / min` / Default: `null` - `max` — 選択可能な最大時刻。 HTML: `data-max / max` / Default: `null` - `showOutOfRangeHours` — min/max範囲外の時候補を表示するか。OFFでは範囲外の時候補をDOMへ生成せず、ONでは00～23を表示し、その時内に選択可能な時刻が1つもないHourは選択不可にします。境界Hourは有効な分/秒へ進める場合は選択可能です。最終時刻は既存min/max Validationで判定します。 HTML: `data-show-out-of-range-hours` / Default: `false` - `step` — 分単位の選択間隔。Runtime許容1～1440。Property UI presetは1/5/10/15/30。秒列には適用しません。 HTML: `data-step / step` / Default: `1` - `disabled` — Triggerを無効化しopenを拒否。 HTML: `data-disabled / disabled` / Default: `false` - `readonly` — 読取専用。Triggerを無効化しopenを拒否。 HTML: `data-readonly / readonly` / Default: `false` - `closeOnSelect` — 選択確定後にPanelを閉じるか。 HTML: `data-close-on-select` / Default: `true` - `panelWidth` — Panel幅。240～1200px。 HTML: `data-panel-width` / Default: `360` - `gap` — Caller INPUT下端からPanel上端までの間隔。0～64px。 HTML: `data-gap` / Default: `6` - `className` — Runtime rootにcreate時追加する任意Class名。 HTML: `data-class-name` / Default: `""` - `ariaLabel` — 時計TriggerのARIA label。 HTML: `data-aria-label / aria-label` / Default: `時刻を選択` ## 3. Default Property 全22件 — 個別Reference ### 3.1 `value` - 型: `string/null` - Runtime Default: `null` - HTML指定: `data-value` - 表示/動作: 初期選択値。秒列非表示は HH:mm、表示時は HH:mm:ss。Caller INPUT.valueが有効ならRuntimeはそちらも初期seedとして読みます。 - 秒列OFF: `HH:mm`。秒列ON: `HH:mm:ss`。00:00:00～23:59:59。 ### 3.2 `theme` - 型: `enum` - Runtime Default: `default` - HTML指定: `data-theme` - 表示/動作: 外観Theme。default / dark / light / neon の4値。 - 許容値: `default` / `dark` / `light` / `neon`。その他は`TIMEPICKER_OPTION_ENUM_INVALID`。 ### 3.3 `iconVisual` - 型: `enum` - Runtime Default: `fontawesome` - HTML指定: `data-icon-visual` - 表示/動作: 時計Triggerの表示。fontawesome / emoji の2値。 - 許容値: `fontawesome` / `emoji`。その他は`TIMEPICKER_OPTION_ENUM_INVALID`。 ### 3.4 `locale` - 型: `string` - Runtime Default: `ja-JP` - HTML指定: `data-locale` - 表示/動作: 列見出し・ボタン文言のLocale。言語タグ形式。 - 許容形式: `ja-JP`, `en-US`等。`^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$`に一致する必要があります。 ### 3.5 `showHour` - 型: `boolean` - Runtime Default: `true` - HTML指定: `data-show-hour` - 表示/動作: 時列(00–23)を表示。 - Boolean: ON=`true` / OFF=`false`。3列すべてOFFは禁止。 ### 3.6 `showMinute` - 型: `boolean` - Runtime Default: `true` - HTML指定: `data-show-minute` - 表示/動作: 分列を表示。分候補はstepで間引かれます。 - Boolean: ON=`true` / OFF=`false`。3列すべてOFFは禁止。 ### 3.7 `showSecond` - 型: `boolean` - Runtime Default: `false` - HTML指定: `data-show-second` - 表示/動作: 秒列(00–59)を表示。ONではvalue/min/maxはHH:mm:ss形式。 - Boolean: ON=`true` / OFF=`false`。3列すべてOFFは禁止。 ### 3.8 `min` - 型: `string/null` - Runtime Default: `null` - HTML指定: `data-min / min` - 表示/動作: 選択可能な最小時刻。 - 秒列OFF: `HH:mm`。秒列ON: `HH:mm:ss`。00:00:00～23:59:59。 ### 3.9 `max` - 型: `string/null` - Runtime Default: `null` - HTML指定: `data-max / max` - 表示/動作: 選択可能な最大時刻。 - 秒列OFF: `HH:mm`。秒列ON: `HH:mm:ss`。00:00:00～23:59:59。 ### 3.10 `showOutOfRangeHours` - 型: `boolean` - Runtime Default: `false` - HTML指定: `data-show-out-of-range-hours` - OFF=`false`: `min` / `max`範囲外の時候補はPicker DOMへ生成しません。例: min=08:00 / max=18:00では08～18だけを表示します。 - ON=`true`: 00～23をすべて表示します。そのHour内に選択可能な時刻が1つもなければ選択不可です。境界Hourは有効な分/秒が存在すれば選択可能で、最終確定は既存min/max Validationに従います。 - 24 / 24:00を通常の時候補として追加しません。 ### 3.11 `step` - 型: `integer` - Runtime Default: `1` - HTML指定: `data-step / step` - 表示/動作: 分単位の選択間隔。Runtime許容1～1440。Property UI presetは1/5/10/15/30。秒列には適用しません。 - Runtime範囲: 1～1440の整数。単位は分。Property UI preset: 1 / 5 / 10 / 15 / 30。`showMinute=false`では分候補を表示しないため画面上の間引き効果はありません。 ### 3.12 `disabled` - 型: `boolean` - Runtime Default: `false` - HTML指定: `data-disabled / disabled` - 表示/動作: Triggerを無効化しopenを拒否。 - Boolean: ON=`true` / OFF=`false`。 ### 3.13 `readonly` - 型: `boolean` - Runtime Default: `false` - HTML指定: `data-readonly / readonly` - 表示/動作: 読取専用。Triggerを無効化しopenを拒否。 - Boolean: ON=`true` / OFF=`false`。 ### 3.14 `closeOnSelect` - 型: `boolean` - Runtime Default: `true` - HTML指定: `data-close-on-select` - 表示/動作: 選択確定後にPanelを閉じるか。 - Boolean: ON=`true` / OFF=`false`。 ### 3.15 `panelWidth` - 型: `integer px` - Runtime Default: `360` - HTML指定: `data-panel-width` - 表示/動作: Panel幅。240～1200px。 - 範囲: 240～1200pxの整数。Viewport右端を超える場合はleftを補正します。縦方向は下側優先、下に収まらなければ上側へflipし、上下とも不足する場合はviewport内へclampします。 ### 3.16 `gap` - 型: `integer px` - Runtime Default: `6` - HTML指定: `data-gap` - 表示/動作: Caller INPUT下端からPanel上端までの間隔。0～64px。 - 範囲: 0～64pxの整数。Panel top = Caller INPUT bottom + gap。 ### 3.17 `className` - 型: `string` - Runtime Default: `""` - HTML指定: `data-class-name` - 表示/動作: Runtime rootにcreate時追加する任意Class名。 ### 3.18 `ariaLabel` - 型: `string` - Runtime Default: `時刻を選択` - HTML指定: `data-aria-label / aria-label` - 表示/動作: 時計TriggerのARIA label。 ### 3.19 `transition` - HTML: `data-transition` - Default: `fade` - #118 BoneTransitionの正式23種カタログからPicker PanelのENTER / EXITを選択します。 ### 3.20 `transitionDirection` - HTML: `data-transition-direction` - Default: `down` - 値: `up / down / left / right` ### 3.21 `transitionSpeed` - HTML: `data-transition-speed` - Default: `normal` - 値: `slow / normal / fast` ### 3.22 `respectReducedMotion` - HTML: `data-respect-reduced-motion` - Default: `true` - OSのモーション低減設定を尊重します。 ## 4. JavaScript専用Callback 全3件 `onSelect / onOpen / onClose`はFunctionをHTML data属性へ文字列で埋め込むPropertyではありません。JavaScript APIの`create()` / `setOptions()`からFunctionまたはnullを渡します。 ### 4.1 `onSelect` - 選択確定時。payload.time/value/sourceを受け取ります。 - 型: `function | null`。文字列等は`TIMEPICKER_CALLBACK_INVALID`。 ### 4.2 `onOpen` - Panel open後。 - 型: `function | null`。文字列等は`TIMEPICKER_CALLBACK_INVALID`。 ### 4.3 `onClose` - Panel close後。 - 型: `function | null`。文字列等は`TIMEPICKER_CALLBACK_INVALID`。 ## 5. 時刻・範囲・step ### `value` 選択値は秒列OFFで`HH:mm`、ONで`HH:mm:ss`。`setValue()`は内部値だけを変更しCaller INPUT.valueは変更しません。 ### `min / max` `min <= max`必須。範囲外候補はdisabledになり、`validateTime()`は`valid=true / selectable=false / TIMEPICKER_RANGE_UNSELECTABLE`を返します。 `showOutOfRangeHours=false`では範囲外の時候補をDOMへ生成しません。`true`では00～23を表示し、Hour内に有効時刻がない場合だけHourを選択不可にします。最終確定は既存min/max Validationで判定します。 ### `step` 分単位。Minute列候補は0からstep加算で生成されます。Second列は常に00～59の1秒刻みです。 ## 6. Theme / Icon 全値 ### `theme` 全4値 - `default`: 標準。 - `dark`: Dark。 - `light`: Light。 - `neon`: Neon。 ### `iconVisual` 全2値 - `fontawesome`: 内蔵Font Awesome互換clock SVG。外部CDN不要。 - `emoji`: `🕒`。 ## 7. 列表示 `showHour / showMinute / showSecond` - `showHour=true`: 00～23。 - `showMinute=true`: stepに従う分候補。 - `showSecond=true`: 00～59。 - 少なくとも1列はON必須。全OFFは`TIMEPICKER_COLUMNS_EMPTY`。 - 秒列OFF時に秒≠00の値を渡すと`TIMEPICKER_SECOND_HIDDEN_VALUE_INVALID`。 ## 8. 表示・基本操作Property ### `disabled` Trigger disabled。`open()`は`{opened:false, reason:"not-editable"}`。 ### `readonly` Runtime上はdisabled同様にPanel openを拒否します。 ### `closeOnSelect` trueなら選択後close。falseならRETURN後もPanelを再描画して開いたまま。 ### `className` create時にRuntime rootへ追加。 ### `ariaLabel` 時計Triggerの`aria-label`へ反映。 ## 9. Panelサイズ・配置 ### `panelWidth` 240～1200px。 ### `gap` 0～64px。Caller INPUT下端からPanel上端まで。 ### `reposition()` open中のみ位置更新。resize / scroll時はRuntime自身も再配置します。 ## 10. #022 Hover Border Effect連携 #022はCaller INPUT＋時計Trigger全体の外周だけへ適用します。Picker Panel / #118 Motion Surface / Hour / Minute / Second value optionには適用しません。#026自身がEffectを再実装しません。 - Target: Caller INPUT＋時計Triggerを含むCaller Host。 - Trigger: #022の`mouseover`契約を使用。 - Effect全9値: `normal / neon / spin / blink / dash / corner / chase / double / wave`。 - Direction全2値: `clockwise / counterclockwise`。 - Speed全3値: `slow / normal / fast`。 - `spinWidth`: 1～24px。 - `spinGlow`: 0～40px。 - Panel再描画では#022をattachしません。#022はCaller Hostだけに保持します。 ## 11. #040 ColorPickerとの責務分離 Effect色の選択UIは#040 ColorPicker Caller APIの`allowedKinds:["solid"]`を使用します。Native `input[type=color]`を#026固有に追加しません。Gradient/transparentはEffect色経路では受理しません。 ## 12. 操作 ### Triggerクリック close→open / open→close。 ### 時・分・秒optionクリック draft値だけを更新してPanelを再描画します。まだCaller INPUTへcommitしません。 ### 「選択」ボタン draftがvalid/selectableなら内部selectedValueへ確定し、`bone-timepicker:select`と`onSelect`へRETURN。`closeOnSelect=true`なら閉じます。 ### 「閉じる」ボタン選択確定せずclose。 ### Escape open中Panelをclose。 ### 外側pointer Trigger/Panel/Caller INPUT外をpointerdownするとclose。 ### resize / scroll open中Panelを`reposition()`相当で追従。 ## 13. Security #026はSecurity Gateを所有しません。ただしHTML Functional Classは属性値をRuntimeの正式normalizeへ渡し、無効値はRuntime Errorとして拒否します。Callbackを文字列からeval生成しません。DOCサンプルも`eval`/外部CDNを使用しません。 ## 14. #002 Joint / WAIT / FIFO / BLOCKED #026はPickerなのでOUT配送を所有しません。接続イメージは#002 BoneJointの実判定/実描画を使用します。WAIT/FIFO/BLOCKEDはCaller UIがRETURN後にOUT配送する段階の責務で、TimePicker内部で擬似実装しません。 ## 15. Event / Callback ### `bone-timepicker:open` / `onOpen` Panel open後。payloadにcomponentId/name/version/value/time/anchorValue/source。 ### `bone-timepicker:close` / `onClose` Panel close後。 ### `bone-timepicker:select` / `onSelect` 選択確定時。`detail.time` / `detail.value`がRETURN値。Caller INPUT.valueは自動変更しません。 ## 16. Public API 全20件 ### 16.1 Public API 詳細 #### 1. `getPropertySchema()` - 用途: Runtime-owned Property Schema 全件を取得。 - 戻り値: `Array` - 使用例: ```js const schema = BoneTimePicker.getPropertySchema(); ``` #### 2. `getPropertyDefaults()` - 用途: Runtimeの正式Default Propertyを取得。 - 戻り値: `Object` - 使用例: ```js const defaults = BoneTimePicker.getPropertyDefaults(); ``` #### 3. `getPropertyDefinition(key)` - 用途: 指定Property 1件の正式定義を取得。不存在時はnull。 - 戻り値: `Object | null` - 使用例: ```js const step = BoneTimePicker.getPropertyDefinition("step"); ``` #### 4. `create(anchor, options)` - 用途: Caller INPUTへTimePickerを接続。TriggerをINPUT直後、Panelをdocument.bodyへ生成。 - 戻り値: `HTMLElement` - 引数: `anchor, options` - 状態/DOM: 実`BoneTimePicker.create()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js const result = BoneTimePicker.create(anchor, options); ``` #### 5. `destroy(picker)` - 用途: event listener、Panel、Trigger rootを破棄。 - 戻り値: `boolean` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.destroy()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.destroy(picker); ``` #### 6. `setOptions(picker, patch)` - 用途: 既存optionへpatchをmergeして正規化・再描画。現在値が新条件で選択不可なら内部値をnull化。 - 戻り値: `HTMLElement` - 引数: `picker, patch` - 状態/DOM: 実`BoneTimePicker.setOptions()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.setOptions(picker, patch); ``` #### 7. `getOptions(picker)` - 用途: 現在optionのfreeze済みcopyを取得。 - 戻り値: `Object` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.getOptions()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.getOptions(picker); ``` #### 8. `setValue(picker, value)` - 用途: Picker内部選択値を設定。Caller INPUT.valueは変更しない。 - 戻り値: `HTMLElement` - 引数: `picker, value` - 状態/DOM: 実`BoneTimePicker.setValue()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.setValue(picker, value); ``` #### 9. `getValue(picker)` - 用途: Picker内部選択値を取得。 - 戻り値: `string/null` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.getValue()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.getValue(picker); ``` #### 10. `getAnchor(picker)` - 用途: 接続元Caller INPUTを取得。 - 戻り値: `HTMLElement` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.getAnchor()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.getAnchor(picker); ``` #### 11. `getPanel(picker)` - 用途: body-owned Panelを取得。 - 戻り値: `HTMLElement` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.getPanel()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.getPanel(picker); ``` #### 12. `open(picker)` - 用途: Caller INPUT値を再同期してPanelを開く。disabled/readonlyならopened=false。 - 戻り値: `Object` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.open()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.open(picker); ``` #### 13. `close(picker)` - 用途: Panelを閉じる。既に閉じていればclosed=false。 - 戻り値: `Object` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.close()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.close(picker); ``` #### 14. `toggle(picker)` - 用途: open/closeを現在状態で切替。 - 戻り値: `Object` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.toggle()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.toggle(picker); ``` #### 15. `isOpen(picker)` - 用途: 現在open状態を返す。 - 戻り値: `boolean` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.isOpen()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.isOpen(picker); ``` #### 16. `reposition(picker)` - 用途: open中PanelをCaller INPUT近傍へ再配置。下側/上側/viewport clampを実Runtimeが再判定します。 - 戻り値: `boolean` - 引数: `picker` - 状態/DOM: 実`BoneTimePicker.reposition()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.reposition(picker); ``` #### 17. `validateTime(value, options)` - 用途: 形式・min/max・step選択可否を副作用なく検証。 - 戻り値: `Object` - 引数: `value, options` - 状態/DOM: 実`BoneTimePicker.validateTime()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js const result = BoneTimePicker.validateTime(value, options); ``` #### 18. `parseTime(value)` - 用途: HH:mm / HH:mm:ssを時分秒とtotalSecondsへparse。 - 戻り値: `Object/null` - 引数: `value` - 状態/DOM: 実`BoneTimePicker.parseTime()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js const result = BoneTimePicker.parseTime(value); ``` #### 19. `normalizeOptions(options)` - 用途: 全optionを正式Default/型/範囲へ正規化。 - 戻り値: `Object` - 引数: `options` - 状態/DOM: 実`BoneTimePicker.normalizeOptions()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js const result = BoneTimePicker.normalizeOptions(options); ``` #### 20. `isInstance(element)` - 用途: BoneTimePicker管理instanceか判定。 - 戻り値: `boolean` - 引数: `element` - 状態/DOM: 実`BoneTimePicker.isInstance()`の契約に従います。 - Error: 対象instance/option/valueが不正な場合は17章の`TIMEPICKER_*`を参照。 - 使用例: ```js BoneTimePicker.isInstance(element); ``` ## 17. Error Code ### 17.1 Runtime Error **`TIMEPICKER_OPTIONS_INVALID`** - 意味: options / setOptions patch がplain objectでない。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `create(input, [])` - 修正方法: plain object `{}` を渡す。 **`TIMEPICKER_OPTION_ENUM_INVALID`** - 意味: theme / iconVisual が許容値外。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `theme="cyber"` - 修正方法: themeはdefault/dark/light/neon、iconVisualはfontawesome/emojiを使用。 **`TIMEPICKER_OPTION_NUMBER_INVALID`** - 意味: step / panelWidth / gap が整数でない、または範囲外。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `panelWidth=100` - 修正方法: step 1–1440、panelWidth 240–1200、gap 0–64の整数にする。 **`TIMEPICKER_LOCALE_INVALID`** - 意味: localeが受理可能なlanguage-tag形式でない。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `locale=""` - 修正方法: ja-JP / en-US などを使用。 **`TIMEPICKER_CALLBACK_INVALID`** - 意味: onSelect/onOpen/onCloseがfunction/null以外。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `onSelect="x"` - 修正方法: Functionまたはnullを使用。 **`TIMEPICKER_TIME_TYPE_INVALID`** - 意味: 時刻値がstringでない。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `parseTime(930)` - 修正方法: "09:30" のようなstringを使用。 **`TIMEPICKER_TIME_FORMAT_INVALID`** - 意味: HH:mm / HH:mm:ss形式でない。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `"9:30"` - 修正方法: "09:30" / "09:30:15" を使用。 **`TIMEPICKER_TIME_RANGE_INVALID`** - 意味: 時・分・秒が実範囲外。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `"24:00"` - 修正方法: 00:00:00～23:59:59内にする。 **`TIMEPICKER_SECOND_HIDDEN_VALUE_INVALID`** - 意味: showSecond=falseなのに0以外の秒を含む。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `showSecond=false, value="09:30:15"` - 修正方法: HH:mmを使用するかshowSecond=trueにする。 **`TIMEPICKER_COLUMNS_EMPTY`** - 意味: showHour/showMinute/showSecondが全てfalse。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `all false` - 修正方法: 少なくとも1列をtrueにする。 **`TIMEPICKER_MIN_MAX_INVALID`** - 意味: minがmaxより後。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `min="18:00", max="08:00"` - 修正方法: min <= maxにする。 **`TIMEPICKER_RANGE_UNSELECTABLE`** - 意味: validateTime対象がmin/max外。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `07:00 with min=08:00` - 修正方法: 範囲内時刻を選ぶ。 **`TIMEPICKER_STEP_UNSELECTABLE`** - 意味: validateTime対象分がstepに一致しない。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `09:10 with step=15` - 修正方法: 00/15/30/45等stepに一致させる。 **`TIMEPICKER_ANCHOR_INVALID`** - 意味: create()に有効なElementを渡していない。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `create(null,{})` - 修正方法: Caller INPUT HTMLElementを渡す。 **`TIMEPICKER_INSTANCE_NOT_FOUND`** - 意味: instance必須APIへ管理外Elementを渡した。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `open(document.body)` - 修正方法: create()の戻りrootを渡す。 **`TIMEPICKER_VALUE_UNSELECTABLE`** - 意味: setValue()値が現在条件で選択不可。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `setValue(p,"07:00") with min=08:00` - 修正方法: min/max/step条件に合う値を指定。 **`TIMEPICKER_TIME_INVALID`** - 意味: validateTime()が捕捉した未分類時刻エラーのfallback code。 - 発生経路: `create / setOptions / setValue / validateTime / parseTime / normalizeOptions / instance API` のうち該当検証。 - 不正例: `—` - 修正方法: 返却messageと元入力を確認し正式形式へ修正。 ### 17.2 HTML Functional Class Integration Error **`TIMEPICKER_FUNCTIONAL_CLASS_RUNTIME_MISSING`** - 意味: bf-timepickerより先にBoneTimePicker Runtimeが読まれていない。 - 修正: Runtime読込順、`bf-timepicker` class、data属性値を確認し、Runtime正式Propertyへ直してください。 **`TIMEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID`** - 意味: data-show-* / data-disabled等Boolean属性値がtrue/false系でない。 - 修正: Runtime読込順、`bf-timepicker` class、data属性値を確認し、Runtime正式Propertyへ直してください。 **`TIMEPICKER_FUNCTIONAL_CLASS_ANCHOR_INVALID`** - 意味: mount/refresh対象にbf-timepicker classがない。 - 修正: Runtime読込順、`bf-timepicker` class、data属性値を確認し、Runtime正式Propertyへ直してください。 **`TIMEPICKER_FUNCTIONAL_CLASS_*_RUNTIME_ERROR`** - 意味: BridgeがRuntimeへ渡した値をRuntimeが拒否した場合は上記TIMEPICKER_* codeをそのまま保持。 - 修正: Runtime読込順、`bf-timepicker` class、data属性値を確認し、Runtime正式Propertyへ直してください。 ## 18. HTML Functional Class Lifecycle 1. `DOMContentLoaded`で`.bf-timepicker`をscan。 2. `mount()`で実`BoneTimePicker.create()`。 3. 属性変更はMutationObserverから`refresh()`し、`setValue/setOptions`へ正式変換。 4. classが外れたら`unmount()`し`destroy()`。 5. DOM追加要素もscanしてmount。 ## 19. トラブル時の確認 ### DOC-0026が開かない Shared DOC 3ファイルが既存Bone Flowへ正しく導入済みか、DOC-0026 Registry merge済みか確認。 ### 時計ボタンが出ない `bone-timepicker.js` → `bone-timepicker-functional-class.js`の読込順と`class="bf-timepicker"`を確認。 ### 開かない `disabled / readonly`、Runtime Error、全列OFFを確認。 ### 時刻を選べない `min / max / step / showSecond`と時刻形式を確認。 ### INPUT.valueが変わらない正常です。#026はRETURNのみ。Callerが`bone-timepicker:select`または`onSelect`でcommitします。 ### Effectが消える #022がCaller Hostだけにattachされ、Picker Panel / Motion Surfaceへattachされていないことを確認。 ## 20. 責務境界 #026 TimePickerは「時刻を選んでRETURNする」まで。Caller INPUT commit / Bone.value / OUT / Security / Delivery / WAIT/FIFO/BLOCKEDはCaller側。#022はHover Effect、#040はEffect色、#002は接続判定/線描画を担当します。 ## #118 Transition integration - Runtime Property: `transition`, `transitionDirection`, `transitionSpeed`, `respectReducedMotion` - Caller-relative Panel位置は#026が所有し、`left` / `top`を固定します。#118 `BoneTransition` / `bf-transition` は内側 `.bone-timepicker__motion` のENTER / EXITだけを補間します。 - Error codes: `TIMEPICKER_TRANSITION_CAPABILITY_MISSING`, `TIMEPICKER_TRANSITION_FUNCTIONAL_CLASS_MISSING`, `TIMEPICKER_TRANSITION_INSTANCE_INVALID`.