# Bone Flow #026 TimePicker Specification v1.0

## Formal scope

1. Time selection Picker UI.
2. Hour / Minute / Second columns are shown according to caller settings.
3. Picker is positioned near the caller INPUT: below when it fits, otherwise above; if neither side fully fits, it is clamped inside the viewport. Horizontal position is also clamped to the viewport.
4. Clock icon opens and closes the Picker.
5. Font Awesome-compatible / Emoji icon visual switching.
6. Theme applies to the whole Picker.
7. `step` is a minute increment. It affects the minute column only; hour and second columns are not thinned by `step`.
8. Selected time is returned to the caller.
9. commit / OUT remain the caller UI responsibility.

## Explicit non-responsibilities

- Parent-element inheritance / parent snapping.
- Security Test / Security Gate.
- OUT WAIT / BLOCKED.
- Bone Joint Delivery Channel.
- Caller INPUT automatic commit.
- Date selection.

## Default options

- `showHour: true`
- `showMinute: true`
- `showSecond: false`
- `step: 1`
- `theme: default`
- `iconVisual: fontawesome`
- `locale: ja-JP`
- `closeOnSelect: true`

At least one of Hour / Minute / Second columns must be enabled.


## v1.0.4 QA
- 基本UI / 接続イメージ / OUT WAIT-FIFO-BLOCKED / Smoke-Validation / Completion の表示構成は #017 Text を正式基準とする。
- #001 / #002 の正式モジュール読込順を使用する。
- TimePicker 固有責務（時/分/秒、step、選択時刻RETURN）のみ保持する。

- Property UI step list: `1 / 5 / 10 / 15 / 30` (select). `step` is minutes, aligned with #031 TimeBox. When the minute column is hidden, `step` does not thin the hour column; the second column always remains 00–59.

## v1.0.5 scoped revision

This revision does not change the formal TimePicker Runtime scope. It updates only the consumer/test UI required by the current cross-component UI contract.

1. Outer trigger hover: #022 Hover Border Effect (formal Public API capability), `trigger=mouseover`, target = Caller INPUT + clock trigger root.
2. Effect color: #040 ColorPicker (formal Caller API capability) Caller API, solid-only. Native ColorPicker is not used.
3. Class/Public API: display the actual `BoneTimePicker` Public Object / Factory API. Class = none.
4. Guide: three sections (Class/Public API, Usage, Operation), with per-API usage and behavior for all 17 public functions.
5. Locale: Japanese / English presentation is extended across the added UI and QA presentation.
6. No #022 Loop Property.
7. No change to Hour 00-23, minute step, Second 00-59, selected time RETURN, or caller-owned commit/OUT boundaries.


## v1.0.8 scoped revision
Dependency checks in the Runtime QA page use component identity + required Public API capability for #022 and #040, without fixed dependency version gates. TimePicker Runtime responsibilities and selection behavior are unchanged.



## DOC Integration v1.0.1 (2026-08-29)
- This historical DOC integration introduced Runtime-owned Property Schema APIs while preserving the existing #026 semantics; the current rebuilt Runtime is BoneTimePicker 1.0.23.
- Normal-use HTML Functional Class is `bf-timepicker` only.
- DOC-0026 / TOC-0026 use the shared Bone DOC guide runtime.
- Legacy API-per-class `bone-html-class-use` is not the normal-use contract.
- Shared DOC files are not modified or bundled.
## v1.0.16 scoped revision
1. Hour candidates remain `00` through `23`; `24` / `24:00` is not added as a normal candidate.
2. Add Boolean option `showOutOfRangeHours`; default is `false`.
3. `false`: Hour candidates whose hour does not overlap `min` / `max` are not created in the Picker DOM.
4. `true`: all Hour candidates `00` through `23` are rendered. An Hour is navigable when that hour contains at least one time allowed by min/max and minute step; hours with no selectable time remain disabled. Final time selection continues to use existing `validateTime()`.
5. Existing minute `step`, Second `00` through `59`, RETURN, Public API, and Error contracts are unchanged.
6. This behavior is implemented by #026 Runtime. Caller/DOC code must not post-process candidate DOM.

## DOC Integration v1.0.4 (2026-08-30)
- At DOC Integration v1.0.4, Runtime was BoneTimePicker v1.0.16 with the scoped Hour visibility correction above.
- Normal-use HTML Functional Class remains `bf-timepicker`; it adds only `data-show-out-of-range-hours` for this Boolean option.
- DOC-0026 / TOC-0026 and the existing shared Bone DOC loader/guide route are preserved.
- Shared DOC runtime files are not modified or bundled.

## v1.0.19 viewport positioning correction
1. Panel placement is calculated by #026 Runtime itself; DOC/Caller code must not post-process Panel coordinates.
2. Below the caller INPUT is preferred when the full Panel fits in the viewport.
3. If the Panel does not fit below and does fit above, it flips above the INPUT.
4. If neither side fully fits, the side with more available space is chosen and the Panel top is clamped inside the viewport.
5. Existing horizontal clamp, scroll/resize `reposition()`, Hour 00–23, min/max visibility, minute step, Second 00–59, RETURN, Public API and Error contracts are unchanged.

## DOC Integration v1.0.5 (2026-08-30)
- Runtime: BoneTimePicker v1.0.23.
- Keeps the v1.0.4 formal DOC/TOC registry schema correction.
- Adds only the Runtime-owned viewport below/above/clamp placement correction and matching documentation/QA.
- Shared DOC runtime, CSS, existing Guide structure, #022 and #040 are unchanged.

## DOC Integration v1.0.6 test-condition correction
- This historical DOC-only correction did not change Runtime behavior at that revision; the current rebuilt Runtime is BoneTimePicker v1.0.22.
- S24 verifies the formal no-min/max hour domain (00..23) with min/max explicitly absent.
- Range behavior continues to be verified separately by S32/S33.


## v1.0.20 #118 / Installer correction
- #118 Transition is validated as the real picker-panel ENTER / EXIT owner.
- Validation enumerates all 23 formal Transition catalog entries and checks visible ENTER, visible EXIT, hidden-after-EXIT, close paths, rapid reopen, and animation residue.
- Installer index/cumulative insertion no longer depends on one exact #025 card markup; safe structural fallbacks are used without fixed dependency version gates.

## v1.0.21 #118 anchor / #022 responsibility correction
- Picker position ownership is separated from #118 visual interpolation. The fixed outer Picker Panel keeps the caller-relative `left` / `top`; #118 animates only the inner `.bone-timepicker__motion` surface.
- This prevents slide / scale / teleport and other transform-based #118 transitions from moving the anchor position itself.
- #022 Hover Border Effect remains Caller-only: target = Caller INPUT + clock Trigger host. #022 is not attached to the Picker Panel or the #118 motion surface.
- Validation checks all 23 #118 transitions for stable outer Panel coordinates during ENTER / EXIT and checks #022 exclusion from Picker DOM.



## v1.0.22 lifecycle / baseline correction

- Keeps the v1.0.21 responsibility split: the outer fixed Picker Panel owns caller-relative placement; #118 animates only the inner `.bone-timepicker__motion` surface.
- Keeps #022 attached only to the Caller INPUT + clock Trigger outer host; Picker Panel / Motion Surface remain excluded.
- Rapid Trigger close -> reopen now cancels the in-flight EXIT and re-enters through the same formal #118 Functional Class instance.
- EXIT finalization accepts the resolved #118 snapshot or the formal current `BoneTransition.getState(instance)` terminal state (`finished` / `reduced-motion`) before hiding the Panel.
- Destroy cancels an in-flight #118 motion before Functional Class unmount.
- Package UI/test structure is re-audited against completed #017 Text v1.0.14; no #017/#025/#022/#040/#118 runtime is modified.