# DOC-0026 — TimePicker Operation / HTML Functional Class

## 0. Document information

- DOC ID: `DOC-0026`
- TOC ID: `TOC-0026`
- UI: `UI-026` / `#026 TimePicker`
- Runtime: `BoneTimePicker v1.0.23`
- DOC Integration: `1.0.7`
- Normal-use HTML Functional Class: `bf-timepicker`
- Shared DOC files are referenced but not modified/bundled by #026.

## 1. Responsibility

TimePicker renders Hour/Minute/Second selection near a caller INPUT and RETURNS the selected time. It prefers below when the full Panel fits, flips above when below does not fit, and clamps inside the viewport when neither side fully fits. It does not commit caller INPUT.value, own OUT delivery, Security Gate, WAIT/FIFO/BLOCKED, or Bone.value.

## 2. HTML Functional Class `bf-timepicker`

### 2.1 Minimum use
```html
<input class="bf-timepicker" value="09:30">
```

[[BF-TIMEPICKER-SAMPLE:basic]]

### 2.2 Configured use
```html
<input class="bf-timepicker" value="09:30" data-min="08:00" data-max="18:00" data-step="15" data-theme="dark" data-icon-visual="emoji">
```

### 2.3 Setting → live result samples

#### Basic

[[BF-TIMEPICKER-SAMPLE:basic]]

#### min/max/step

[[BF-TIMEPICKER-SAMPLE:range]]

#### theme=default

[[BF-TIMEPICKER-SAMPLE:themeDefault]]

#### theme=dark

[[BF-TIMEPICKER-SAMPLE:themeDark]]

#### theme=light

[[BF-TIMEPICKER-SAMPLE:themeLight]]

#### theme=neon

[[BF-TIMEPICKER-SAMPLE:themeNeon]]

#### iconVisual=fontawesome

[[BF-TIMEPICKER-SAMPLE:iconFa]]

#### iconVisual=emoji

[[BF-TIMEPICKER-SAMPLE:iconEmoji]]

#### showSecond=true

[[BF-TIMEPICKER-SAMPLE:seconds]]

#### Hour only

[[BF-TIMEPICKER-SAMPLE:hourOnly]]

#### Minute only

[[BF-TIMEPICKER-SAMPLE:minuteOnly]]

#### locale=en-US

[[BF-TIMEPICKER-SAMPLE:localeEn]]

#### readonly

[[BF-TIMEPICKER-SAMPLE:readonly]]

#### disabled

[[BF-TIMEPICKER-SAMPLE:disabled]]

#### closeOnSelect=false

[[BF-TIMEPICKER-SAMPLE:manualClose]]

#### panelWidth/gap

[[BF-TIMEPICKER-SAMPLE:sizeGap]]

### 2.4 All 22 HTML-declarable Properties

- `value` — Initial selected value. Use HH:mm without seconds, or HH:mm:ss when seconds are shown. HTML: `data-value` / Default: `null`
- `theme` — Visual theme: default / dark / light / neon. HTML: `data-theme` / Default: `default`
- `iconVisual` — Clock trigger visual: fontawesome / emoji. HTML: `data-icon-visual` / Default: `fontawesome`
- `locale` — Locale for column/footer labels. Language-tag format. HTML: `data-locale` / Default: `ja-JP`
- `showHour` — Shows the Hour column (00–23). HTML: `data-show-hour` / Default: `true`
- `showMinute` — Shows the Minute column; minute options follow step. HTML: `data-show-minute` / Default: `true`
- `showSecond` — Shows the Second column (00–59). When true, value/min/max use HH:mm:ss. HTML: `data-show-second` / Default: `false`
- `min` — Minimum selectable time. HTML: `data-min / min` / Default: `null`
- `max` — Maximum selectable time. HTML: `data-max / max` / Default: `null`
- `showOutOfRangeHours` — Controls whether Hour candidates outside min/max are shown. OFF omits them from the DOM; ON shows 00–23; an Hour is navigable only when that hour contains at least one selectable time. Final selection still uses the existing min/max validation contract. HTML: `data-show-out-of-range-hours` / Default: `false`
- `step` — Minute selection interval. Runtime accepts 1–1440; Property UI presets 1/5/10/15/30. Does not thin seconds. HTML: `data-step / step` / Default: `1`
- `disabled` — Disables the trigger and rejects open. HTML: `data-disabled / disabled` / Default: `false`
- `readonly` — Read-only mode; disables trigger and rejects open. HTML: `data-readonly / readonly` / Default: `false`
- `closeOnSelect` — Whether the panel closes after selection. HTML: `data-close-on-select` / Default: `true`
- `panelWidth` — Panel width, 240–1200 px. HTML: `data-panel-width` / Default: `360`
- `gap` — Gap from caller INPUT bottom to panel top, 0–64 px. HTML: `data-gap` / Default: `6`
- `className` — Optional class name added to the Runtime root at create time. HTML: `data-class-name` / Default: `""`
- `ariaLabel` — ARIA label for the clock trigger. HTML: `data-aria-label / aria-label` / Default: `時刻を選択`

## 3. Default Property reference — 22 items

### 3.1 `value`

- Type: `string/null`
- Runtime Default: `null`
- HTML: `data-value`
- Behavior: Initial selected value. Use HH:mm without seconds, or HH:mm:ss when seconds are shown.

### 3.2 `theme`

- Type: `enum`
- Runtime Default: `default`
- HTML: `data-theme`
- Behavior: Visual theme: default / dark / light / neon.

### 3.3 `iconVisual`

- Type: `enum`
- Runtime Default: `fontawesome`
- HTML: `data-icon-visual`
- Behavior: Clock trigger visual: fontawesome / emoji.

### 3.4 `locale`

- Type: `string`
- Runtime Default: `ja-JP`
- HTML: `data-locale`
- Behavior: Locale for column/footer labels. Language-tag format.

### 3.5 `showHour`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-show-hour`
- Behavior: Shows the Hour column (00–23).

### 3.6 `showMinute`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-show-minute`
- Behavior: Shows the Minute column; minute options follow step.

### 3.7 `showSecond`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-show-second`
- Behavior: Shows the Second column (00–59). When true, value/min/max use HH:mm:ss.

### 3.8 `min`

- Type: `string/null`
- Runtime Default: `null`
- HTML: `data-min / min`
- Behavior: Minimum selectable time.

### 3.9 `max`

- Type: `string/null`
- Runtime Default: `null`
- HTML: `data-max / max`
- Behavior: Maximum selectable time.

### 3.10 `showOutOfRangeHours`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-show-out-of-range-hours`
- OFF=`false`: Hour candidates outside min/max are not created in the Picker DOM. Example: min=08:00 / max=18:00 shows only 08 through 18.
- ON=`true`: all Hour candidates 00 through 23 are shown. An Hour is enabled only when it contains at least one selectable time; final confirmation still follows existing min/max validation.
- `24` / `24:00` is not added as a normal Hour candidate.

### 3.11 `step`

- Type: `integer`
- Runtime Default: `1`
- HTML: `data-step / step`
- Behavior: Minute selection interval. Runtime accepts 1–1440; Property UI presets 1/5/10/15/30. Does not thin seconds.

### 3.12 `disabled`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-disabled / disabled`
- Behavior: Disables the trigger and rejects open.

### 3.13 `readonly`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-readonly / readonly`
- Behavior: Read-only mode; disables trigger and rejects open.

### 3.14 `closeOnSelect`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-close-on-select`
- Behavior: Whether the panel closes after selection.

### 3.15 `panelWidth`

- Type: `integer px`
- Runtime Default: `360`
- HTML: `data-panel-width`
- Behavior: Panel width, 240–1200 px.

### 3.16 `gap`

- Type: `integer px`
- Runtime Default: `6`
- HTML: `data-gap`
- Behavior: Gap from caller INPUT bottom to panel top, 0–64 px.

### 3.17 `className`

- Type: `string`
- Runtime Default: `""`
- HTML: `data-class-name`
- Behavior: Optional class name added to the Runtime root at create time.

### 3.18 `ariaLabel`

- Type: `string`
- Runtime Default: `時刻を選択`
- HTML: `data-aria-label / aria-label`
- Behavior: ARIA label for the clock trigger.

### 3.19 `transition`
- HTML: `data-transition`
- Default: `fade`
- Selects the Picker Panel ENTER / EXIT motion from the formal #118 BoneTransition 23-transition catalog.

### 3.20 `transitionDirection`
- HTML: `data-transition-direction`
- Default: `down`
- Values: `up / down / left / right`

### 3.21 `transitionSpeed`
- HTML: `data-transition-speed`
- Default: `normal`
- Values: `slow / normal / fast`

### 3.22 `respectReducedMotion`
- HTML: `data-respect-reduced-motion`
- Default: `true`
- Respects the operating system reduced-motion preference.

## 4. JavaScript-only callbacks — 3 items

### 4.1 `onSelect`

- On confirmed selection; receives payload.time/value/source.
- Type: `function | null`.

### 4.2 `onOpen`

- After the panel opens.
- Type: `function | null`.

### 4.3 `onClose`

- After the panel closes.
- Type: `function | null`.

## 5. Time / range / step

- Value/min/max use HH:mm when seconds are hidden and HH:mm:ss when shown.
- `min <= max`. Out-of-range values are valid-format but unselectable.
- `showOutOfRangeHours=false` omits out-of-range Hour candidates from the DOM; `true` shows 00–23, enables only Hours containing at least one selectable time, and preserves existing min/max validation for final confirmation.
- `step` is minutes, Runtime range 1–1440; seconds remain 1-second options.

## 6. Theme / Icon values

- theme: `default / dark / light / neon`.
- iconVisual: `fontawesome / emoji`.

## 7. Column visibility

`showHour / showMinute / showSecond` are Boolean. At least one must be true.

## 8. Display/basic Properties

disabled/readonly reject open; closeOnSelect controls post-select close; className applies to Runtime root; ariaLabel applies to trigger.

## 9. Panel sizing/positioning

panelWidth 240–1200 px; gap 0–64 px; reposition() follows the caller INPUT and recalculates below/above/viewport-clamped placement.

## 10. #022 Hover Border Effect

#022 applies only to the outer Caller Host that contains the caller INPUT and clock Trigger. It is not attached to the Picker Panel, the #118 Motion Surface, or individual Hour/Minute/Second value options. Effect values: normal/neon/spin/blink/dash/corner/chase/double/wave; direction clockwise/counterclockwise; speed slow/normal/fast; spinWidth 1–24 px; spinGlow 0–40 px.

## 11. #040 ColorPicker boundary

Effect color uses #040 solid-only Caller API; #026 does not add a native color input.

## 12. Operation

Trigger toggles panel; option clicks update draft; Select returns time; Escape/outside closes; resize/scroll repositions.

## 13. Security

No eval/callback-string construction. Invalid HTML values are passed through Runtime normalization and rejected with formal codes.

## 14. #002 Joint / WAIT / FIFO / BLOCKED

#002 owns connection evaluation/rendering. TimePicker does not own delivery, WAIT, FIFO or BLOCKED.

## 15. Events / callbacks

`bone-timepicker:open/onOpen`, `bone-timepicker:close/onClose`, `bone-timepicker:select/onSelect`. Select RETURN does not commit caller INPUT.value.

## 16. Public API — all 20

### 16.1 Detailed API reference

#### 1. `getPropertySchema()`

- Purpose: Returns the complete Runtime-owned Property Schema.
- Return: `Array`

#### 2. `getPropertyDefaults()`

- Purpose: Returns the formal Runtime default properties.
- Return: `Object`

#### 3. `getPropertyDefinition(key)`

- Purpose: Returns one formal property definition, or null when unknown.
- Return: `Object | null`

#### 4. `create(anchor, options)`

- Purpose: Attaches TimePicker to the caller INPUT. Creates trigger after INPUT and panel under document.body.
- Return: `HTMLElement`
- Arguments: `anchor, options`
- Errors: see Runtime Error section.

#### 5. `destroy(picker)`

- Purpose: Removes listeners, panel, and trigger root.
- Return: `boolean`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 6. `setOptions(picker, patch)`

- Purpose: Merges/normalizes a patch and rerenders. Clears internal value if it becomes unselectable.
- Return: `HTMLElement`
- Arguments: `picker, patch`
- Errors: see Runtime Error section.

#### 7. `getOptions(picker)`

- Purpose: Returns a frozen copy of current options.
- Return: `Object`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 8. `setValue(picker, value)`

- Purpose: Sets internal picker value without changing caller INPUT.value.
- Return: `HTMLElement`
- Arguments: `picker, value`
- Errors: see Runtime Error section.

#### 9. `getValue(picker)`

- Purpose: Returns internal selected time.
- Return: `string/null`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 10. `getAnchor(picker)`

- Purpose: Returns the caller INPUT.
- Return: `HTMLElement`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 11. `getPanel(picker)`

- Purpose: Returns the body-owned panel.
- Return: `HTMLElement`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 12. `open(picker)`

- Purpose: Resyncs caller INPUT and opens the panel; disabled/readonly returns opened=false.
- Return: `Object`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 13. `close(picker)`

- Purpose: Closes the panel; already closed returns closed=false.
- Return: `Object`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 14. `toggle(picker)`

- Purpose: Toggles open/close.
- Return: `Object`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 15. `isOpen(picker)`

- Purpose: Returns current open state.
- Return: `boolean`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 16. `reposition(picker)`

- Purpose: Repositions an open panel near the caller INPUT, recalculating below/above/viewport-clamped placement.
- Return: `boolean`
- Arguments: `picker`
- Errors: see Runtime Error section.

#### 17. `validateTime(value, options)`

- Purpose: Validates format/min/max/step selectability without side effects.
- Return: `Object`
- Arguments: `value, options`
- Errors: see Runtime Error section.

#### 18. `parseTime(value)`

- Purpose: Parses HH:mm / HH:mm:ss into parts and totalSeconds.
- Return: `Object/null`
- Arguments: `value`
- Errors: see Runtime Error section.

#### 19. `normalizeOptions(options)`

- Purpose: Normalizes all options against defaults/types/ranges.
- Return: `Object`
- Arguments: `options`
- Errors: see Runtime Error section.

#### 20. `isInstance(element)`

- Purpose: Checks whether an element is a managed instance.
- Return: `boolean`
- Arguments: `element`
- Errors: see Runtime Error section.

## 17. Error Code

### 17.1 Runtime Error

**`TIMEPICKER_OPTIONS_INVALID`**

- Meaning: options/patch is not a plain object.
- Invalid example: `create(input, [])`
- Fix: plain object `{}` を渡す。

**`TIMEPICKER_OPTION_ENUM_INVALID`**

- Meaning: theme/iconVisual is outside allowed values.
- Invalid example: `theme="cyber"`
- Fix: themeはdefault/dark/light/neon、iconVisualはfontawesome/emojiを使用。

**`TIMEPICKER_OPTION_NUMBER_INVALID`**

- Meaning: step/panelWidth/gap is noninteger or outside range.
- Invalid example: `panelWidth=100`
- Fix: step 1–1440、panelWidth 240–1200、gap 0–64の整数にする。

**`TIMEPICKER_LOCALE_INVALID`**

- Meaning: locale does not match accepted language-tag pattern.
- Invalid example: `locale="<ja>"`
- Fix: ja-JP / en-US などを使用。

**`TIMEPICKER_CALLBACK_INVALID`**

- Meaning: callback is not function/null.
- Invalid example: `onSelect="x"`
- Fix: Functionまたはnullを使用。

**`TIMEPICKER_TIME_TYPE_INVALID`**

- Meaning: time value is not a string.
- Invalid example: `parseTime(930)`
- Fix: "09:30" のようなstringを使用。

**`TIMEPICKER_TIME_FORMAT_INVALID`**

- Meaning: time does not match HH:mm or HH:mm:ss.
- Invalid example: `"9:30"`
- Fix: "09:30" / "09:30:15" を使用。

**`TIMEPICKER_TIME_RANGE_INVALID`**

- Meaning: hour/minute/second is outside its real range.
- Invalid example: `"24:00"`
- Fix: 00:00:00～23:59:59内にする。

**`TIMEPICKER_SECOND_HIDDEN_VALUE_INVALID`**

- Meaning: seconds supplied while showSecond=false.
- Invalid example: `showSecond=false, value="09:30:15"`
- Fix: HH:mmを使用するかshowSecond=trueにする。

**`TIMEPICKER_COLUMNS_EMPTY`**

- Meaning: all three columns are hidden.
- Invalid example: `all false`
- Fix: 少なくとも1列をtrueにする。

**`TIMEPICKER_MIN_MAX_INVALID`**

- Meaning: min is later than max.
- Invalid example: `min="18:00", max="08:00"`
- Fix: min <= maxにする。

**`TIMEPICKER_RANGE_UNSELECTABLE`**

- Meaning: validated time is outside min/max.
- Invalid example: `07:00 with min=08:00`
- Fix: 範囲内時刻を選ぶ。

**`TIMEPICKER_STEP_UNSELECTABLE`**

- Meaning: minute does not align to step.
- Invalid example: `09:10 with step=15`
- Fix: 00/15/30/45等stepに一致させる。

**`TIMEPICKER_ANCHOR_INVALID`**

- Meaning: create() anchor is not a valid Element.
- Invalid example: `create(null,{})`
- Fix: Caller INPUT HTMLElementを渡す。

**`TIMEPICKER_INSTANCE_NOT_FOUND`**

- Meaning: instance API received an unmanaged element.
- Invalid example: `open(document.body)`
- Fix: create()の戻りrootを渡す。

**`TIMEPICKER_VALUE_UNSELECTABLE`**

- Meaning: setValue value is unselectable under current options.
- Invalid example: `setValue(p,"07:00") with min=08:00`
- Fix: min/max/step条件に合う値を指定。

**`TIMEPICKER_TIME_INVALID`**

- Meaning: fallback code for an otherwise unclassified validation error.
- Invalid example: `—`
- Fix: 返却messageと元入力を確認し正式形式へ修正。

### 17.2 HTML Functional Class Integration Error

**`TIMEPICKER_FUNCTIONAL_CLASS_RUNTIME_MISSING`**

- Meaning: BoneTimePicker Runtime was not loaded before bf-timepicker.
- Fix: verify Runtime load order, bf-timepicker class, and data attribute values.

**`TIMEPICKER_FUNCTIONAL_CLASS_BOOLEAN_INVALID`**

- Meaning: Boolean data attribute is not a supported true/false form.
- Fix: verify Runtime load order, bf-timepicker class, and data attribute values.

**`TIMEPICKER_FUNCTIONAL_CLASS_ANCHOR_INVALID`**

- Meaning: mount/refresh target does not have bf-timepicker.
- Fix: verify Runtime load order, bf-timepicker class, and data attribute values.

**`TIMEPICKER_FUNCTIONAL_CLASS_*_RUNTIME_ERROR`**

- Meaning: Runtime rejection is preserved as its TIMEPICKER_* code.
- Fix: verify Runtime load order, bf-timepicker class, and data attribute values.

## 18. HTML Functional Class Lifecycle

scan → mount/create → attribute refresh via setValue/setOptions → unmount/destroy.

## 19. Troubleshooting

If the DOC does not open, verify shared DOC runtime/registry. If trigger does not appear, verify script order and bf-timepicker. If selection is blocked, verify min/max/step/showSecond. INPUT.value not changing is the formal RETURN-only contract.

## 20. Responsibility boundary

#026 owns picker display/open-close/time RETURN. Caller owns INPUT commit/Bone.value/OUT/Security/Delivery/WAIT/FIFO/BLOCKED. #022 owns hover effect, #040 effect color, #002 connection evaluation/rendering.


## #118 Transition integration
- Runtime Property: `transition`, `transitionDirection`, `transitionSpeed`, `respectReducedMotion`
- #026 owns the caller-relative outer Panel position (`left` / `top`). #118 `BoneTransition` / `bf-transition` animates ENTER / EXIT only on the inner `.bone-timepicker__motion` surface.
- Error codes: `TIMEPICKER_TRANSITION_CAPABILITY_MISSING`, `TIMEPICKER_TRANSITION_FUNCTIONAL_CLASS_MISSING`, `TIMEPICKER_TRANSITION_INSTANCE_INVALID`.