# #031 TimeBox — Operation / HTML Functional Class

## 0. Scope

This document targets **UI-031 / BoneTimeBox v1.0.9**. DOC Integration does not replace the runtime. #031 retains input, value management, validation, commit, Security, OUT, WAIT/FIFO/BLOCKED and #002 delivery responsibilities. #026 TimePicker DOC Integration v1.0.6 / BoneTimePicker v1.0.17 is responsible for picker UI, candidate generation/display policy, candidate Validation, and returning the selected time.

`Runtime` means the actual BoneTimeBox JavaScript loaded in the browser. `root` is the TimeBox DOM returned by runtime creation. `commit` moves the editing value to the committed value. `WAIT/FIFO/BLOCKED` are real #002 Joint delivery states.

[[BF-TIMEBOX-SAMPLE:contract]]

The Runtime Contract sample reads `BoneTimeBox.defaults()` and the exported function inventory from the runtime currently loaded. It prevents this DOC from silently inventing a second contract.

## 1. Basic operation

Focus the TimeBox and edit a time. When the picker is used, #026 returns a selected time to #031. #031 then processes that candidate through its own editing, validation and commit rules. If OUT is connected, committed values are passed to the #002 delivery channel.

[[BF-TIMEBOX-SAMPLE:basic]]

## 2. Time value

The formal picker boundary uses hours 00–23, minute step values, and seconds 00–59. `bf-timebox` accepts empty, `HH:mm`, or `HH:mm:ss` and rejects out-of-range fields.

[[BF-TIMEBOX-SAMPLE:seconds]]

### min / max

`min` is the earliest allowed time and `max` is the latest. #031 does not duplicate the #026-only `showOutOfRangeHours` Property and uses the formal #026 default `false`. For `min=08:00 / max=18:00`, the **hour column** contains only `08` through `18`; `00`–`07` and `19`–`23` are absent from the hour DOM. The **minute column is generated by minute step only**, so boundary minute rows are not removed; #026 Validation disables a boundary minute when it cannot produce an in-range time. When seconds are shown, the second column remains `00`–`59`, with invalid boundary seconds disabled by #026 Validation. DOC Integration never post-processes candidate DOM using hidden/display/disabled changes. Guide auditing reads and compares #031 min/max/step, #026 `showOutOfRangeHours=false`, and the actual #026 columns. Because #026 portals its candidate Panel under `document.body`, the columns are resolved through the formal `BoneTimePicker.getPanel(picker)` API. Unreadable data is `UNRESOLVED`; a contract difference is `MISMATCH`.

[[BF-TIMEBOX-SAMPLE:minmax]]

### step

Formal minute step choices are **1 / 5 / 10 / 15 / 30**. Step is a **minute-unit** setting for the minute column; DOC code does not prune that sequence for min/max. Seconds remain 00–59 and minute step is never applied to seconds.

For the HTML Functional Class, **`data-step` is the formal Bone Flow attribute**. Guide Live Samples do not use the browser native `input[type=time]` picker. `bf-timebox` mounts the formal `BoneTimeBox v1.0.9`, and time selection is performed only by the **#026 TimePicker owned by BoneTimeBox**.

Live Runtime for every formal value. **Matching only `getOptions().step` is not a PASS. Open the formal #026 from the TimeBox clock icon and verify the visible minute candidates. DOC-0031 does not create another picker.**

- `step=1` → `00` through `59` (60 candidates)
- `step=5` → `00 / 05 / 10 / 15 / 20 / 25 / 30 / 35 / 40 / 45 / 50 / 55`
- `step=10` → `00 / 10 / 20 / 30 / 40 / 50`
- `step=15` → **`00 / 15 / 30 / 45`**
- `step=30` → `00 / 30`

Use the TimeBox clock icon itself. There are no DOC-owned open/close or fake-picker controls. If the formal #026 instance cannot be obtained from `BoneTimeBox.getTimePicker(root)`, the sample is a FAIL rather than falling back to DOM guessing.


[[BF-TIMEBOX-SAMPLE:step1]]
[[BF-TIMEBOX-SAMPLE:step5]]
[[BF-TIMEBOX-SAMPLE:step10]]
[[BF-TIMEBOX-SAMPLE:step15]]
[[BF-TIMEBOX-SAMPLE:step30]]

### Preview / Guide step synchronization check

Normal Guide Live Samples are **independent Functional Class examples with explicit attributes**, matching the completed #030 pattern and the original #031 DOC pattern. Basic, seconds, min/max, step 1/5/10/15/30, required, disabled, readonly, theme, position, and #026 RETURN must render and operate even when the original page Preview cannot be resolved. Preview discovery failure must not stop those samples.

Only the dedicated `previewLinked` sample depends on the original TimeBox Preview. It copies every property that the Functional Class can map—such as `value / step / min / max / theme / backgroundColor / appearance / position / width / height / inputAlign / font / pickerVisual / Boolean properties`—and compares the copied Guide instance against the Preview. Preview resolution probes Runtime `getOptions()` on real DOM roots and also uses `isInstance()` when that API exists; no Runtime CSS class name is required as the identity contract.

`previewLinked` also audits the **visible formal #026 minute candidates**, not only the step option. If Preview uses `step=15`, the #031→#026 handoff must match and the formal #026 minute column must be `00 / 15 / 30 / 45`. A user selection inside the Guide is audited without immediately forcing the Preview value back over the selected Guide value. Clicks inside the #026 body-portal Panel are treated as interactions belonging to that Guide Live Sample.

If the original Preview cannot be resolved, only `previewLinked` reports `TIMEBOX_DOC_PREVIEW_NOT_FOUND`; synchronization is not faked. **That error never blocks the independent Live Samples.**

[[BF-TIMEBOX-SAMPLE:previewLinked]]

## 3. HTML Functional Class `bf-timebox`

```html
<input class="bf-timebox" value="09:30">
```

The original input remains as an anchor. BoneTimeBox v1.0.9 supplies the real DOM/runtime. Committed values are mirrored back to the anchor.

Boolean attributes use true/false semantics. Invalid Boolean text produces `TIMEBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID`; invalid time text produces `TIMEBOX_FUNCTIONAL_CLASS_VALUE_INVALID`, `TIMEBOX_FUNCTIONAL_CLASS_STEP_INVALID`. Optional properties are passed only when `BoneTimeBox.defaults()` actually exposes them.

[[BF-TIMEBOX-SAMPLE:required]]
[[BF-TIMEBOX-SAMPLE:disabled]]
[[BF-TIMEBOX-SAMPLE:readonly]]

## 4. Display properties

Theme, backgroundColor, appearance, inputAlign, font sizing and active-border settings are delegated to the existing runtime only when the runtime exposes the corresponding property.

[[BF-TIMEBOX-SAMPLE:themeDark]]

### Position: all nine values

- `top-left`: start/start
- `top-center`: center/start
- `top-right`: end/start
- `middle-left`: start/center
- `center`: center/center
- `middle-right`: end/center
- `bottom-left`: start/end
- `bottom-center`: center/end
- `bottom-right`: end/end

When `inheritParent=true`, parent-follow behavior takes priority over explicit position.

[[BF-TIMEBOX-SAMPLE:position]]

> #031 min/max visibility contract: use formal #026 TimePicker v1.0.17 unchanged. #031 does not post-process candidate DOM. With `showOutOfRangeHours=false`, min=08:00 / max=18:00 generates hour DOM 08 through 18 only. The minute column is generated by step, so step=15 always generates 00 / 15 / 30 / 45; boundary minutes outside min/max are disabled by #026 Validation. The second column is 00 through 59 when shown.

## 5. #026 TimePicker integration

#026 owns picker UI, candidate generation/display, candidate Validation, and selected-time RETURN. It must not take over #031 value management, commit, Security, OUT or WAIT/FIFO/BLOCKED responsibilities.

[[BF-TIMEBOX-SAMPLE:picker]]

After a picker selection, verify #031 editingValue, committedValue and validation state; merely seeing the picker open is not enough.

## 6. Security

The actual v1.0.9 runtime is authoritative for untrusted input, accessor/proxy behavior, length/security limits and state preservation. DOC Integration never weakens Runtime Security. On rejection, inspect the error code, entry path, preserved committed value, OUT behavior and BLOCKED/delivery state.

## 7. WAIT / FIFO / BLOCKED

**WAIT** keeps the connection and queues committed data while the target is busy. **FIFO** delivers queued items in arrival order when the target becomes ready. **BLOCKED** keeps the connection but does not deliver the blocked data. These must be tested as #002 runtime states, not decorative labels.

## 8. Public API

The exact public function inventory is read from the live runtime by Runtime Contract. Typical areas to verify include creation, value/editing/committed getters, setValue/setOptions, validate/commit, Joint IN, output connection/readiness/block clearing, and destroy. If a named function is absent in v1.0.9, the live Runtime Contract wins.

## 9. DOC Integration error codes

- `TIMEBOX_FUNCTIONAL_CLASS_RUNTIME_MISSING`
- `TIMEBOX_FUNCTIONAL_CLASS_ANCHOR_INVALID`
- `TIMEBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID`
- `TIMEBOX_FUNCTIONAL_CLASS_VALUE_INVALID`, `TIMEBOX_FUNCTIONAL_CLASS_STEP_INVALID`

BoneTimeBox runtime errors are not guessed or renamed by this integration.

## 10. Regression boundary

Preserve the original TimeBox Preview/Property Editor, #026 RETURN, Security Test, connection image, WAIT/FIFO/BLOCKED, Smoke/Validation, Runtime Console, Completion and language switching. Regression requires all mapped Preview/Guide properties to match and the visible #026 minute list to match the step exactly (for example step=15 → 00 / 15 / 30 / 45). Shared DOC files are not changed for #031. Browser-native picker UI and #026-lookalike DOM are prohibited in Guide samples.