# Bone Flow #025 - DatePicker Guide

Runtime: **BoneDatePicker 1.0.12**  
HTML Functional Class: **`bf-datepicker`**  
Status: Development / Candidate

Guide UI: **one shared BoneDocGuide / DOC-0025 path only**. No independent custom guide modal is allowed.

## 1. Purpose

#025 DatePicker connects a caller `input` to #024 Calendar. Visual ENTER / EXIT of the Calendar panel is delegated to #118 Transition, while mouse-over border effects are delegated to #022 Hover Border Effect.

DatePicker does **not** automatically commit to the caller `input.value`. The selected date is returned through `bone-datepicker:select` / `onSelect`; the caller owns the commit decision.

## 2. Minimal HTML

```html
<input class="bf-datepicker" type="text" value="2026-08-10">
```

The `bf-datepicker` HTML Functional Class mounts #025 Runtime without replacing the original INPUT.

## 3. HTML Functional Class

```html
<input class="bf-datepicker"
       type="text"
       data-theme="dark"
       data-week-start="sunday"
       data-transition="fade"
       data-transition-direction="down"
       data-transition-speed="normal"
       data-respect-reduced-motion="true">
```

## 4. Runtime Defaults and Schema

Defaults include `theme=default`, `weekStart=auto`, `step=1`, `closeOnSelect=true`, `panelWidth=360`, `calendarHeight=430`, `gap=6`, `transition=fade`, `transitionDirection=down`, `transitionSpeed=normal`, and `respectReducedMotion=true`.

Use `BoneDatePicker.getPropertySchema()`, `getPropertyDefaults()`, and `getPropertyDefinition(key)` for the formal Runtime-owned property contract.

## 5. #024 Calendar boundary

DatePicker delegates Calendar properties and date rendering/validation to #024. Consumers detect required #024 Public API capabilities rather than locking to a specific patch version.

## 6. #118 Transition

#025 owns semantic open/closed state. #118 owns only the visual ENTER / EXIT transition. The picker panel is a formal `bf-transition` host; #025 reuses the single instance owned by `BoneTransitionFunctionalClass.mount/getInstance` and calls `BoneTransition.setOptions / enter / exit / cancel / getState / getTarget` on that instance. #025 does not create/attach a second #118 instance and does not call `finish()` immediately after EXIT.

## 7. #022 Hover Border Effect

The effect inventory comes from the formal public `BoneHoverBorderEffect.effects` array. The inspected v1.0.27 current effects are:

`normal / neon / spin / blink / dash / corner / chase / double / wave`



Outer DatePicker hover and Calendar day-cell hover are separate settings. Calendar day-cell reattachment watches only direct `childList` changes under `.bone-calendar__days`.

## 8. #040 ColorPicker

Effect color uses the formal solid-only `BoneColorPicker.attachCaller()` path. Do not use native `input[type=color]`, copied palettes, direct #040 internal DOM access, or duplicate consumer-owned `openCaller()` handlers.

## 9. Return contract

Events:

- `bone-datepicker:open`
- `bone-datepicker:close`
- `bone-datepicker:select`

Date selection is returned to the caller, but INPUT commit remains caller-owned.

## 10. Public API details

This section is the **single formal API guide body** for #025. The test page does not own a second custom guide modal. The header “DOC-0025” action opens this same content through the shared BoneDocGuide viewer.

### 10.1 `BoneDatePicker.getPropertySchema()`

- Purpose: Read formal Runtime Property Schema
- Arguments: `none`
- Return: `Array`
- When to use: When reading Runtime-owned Property definitions.

Usage steps:
1. Call BoneDatePicker.getPropertySchema().

Operation details:
- Returns defensive copies of Property definitions.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const schema = BoneDatePicker.getPropertySchema();
```

### 10.2 `BoneDatePicker.getPropertyDefaults()`

- Purpose: Read formal Runtime defaults
- Arguments: `none`
- Return: `Object`
- When to use: When reading all Runtime defaults.

Usage steps:
1. Call BoneDatePicker.getPropertyDefaults().

Operation details:
- Returns a copy of Runtime defaults.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const defaults = BoneDatePicker.getPropertyDefaults();
```

### 10.3 `BoneDatePicker.getPropertyDefinition(key)`

- Purpose: Read one Property definition
- Arguments: `key`
- Return: `Object | null`
- When to use: When inspecting one Property definition.

Usage steps:
1. Pass a Property key.

Operation details:
- Returns null when the key does not exist.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const def = BoneDatePicker.getPropertyDefinition('transition');
```

### 10.4 `BoneDatePicker.create(input, options)`

- Purpose: Attach a DatePicker to an INPUT
- Arguments: `input, options`
- Return: `HTMLElement`
- When to use: When attaching a picker trigger beside a date INPUT and returning selection from #024 Calendar.

Usage steps:
1. Prepare the caller INPUT HTMLElement.
2. Prepare options such as theme, min, max, step, locale, and onSelect.
3. Call BoneDatePicker.create(input, options) and retain the returned picker.

Operation details:
- Places the trigger after the INPUT and the panel under document.body.
- Creates #024 Calendar when opened.
- Returns selection by event/callback without changing INPUT.value.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const picker = BoneDatePicker.create(input, {
  theme: 'dark',
  min: '2026-08-01',
  max: '2027-08-10',
  onSelect(e) { console.log(e.date); }
});
```

### 10.5 `BoneDatePicker.destroy(picker)`

- Purpose: Destroy a DatePicker instance
- Arguments: `picker`
- Return: `boolean`
- When to use: When cleaning up a DatePicker and its panel before teardown or rebuild.

Usage steps:
1. Optionally confirm with isInstance.
2. Call BoneDatePicker.destroy(picker).

Operation details:
- Unbinds events and removes internal Calendar, body-owned panel, and trigger root.
- Returns false for an unregistered picker.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
if (BoneDatePicker.isInstance(picker)) {
  BoneDatePicker.destroy(picker);
}
```

### 10.6 `BoneDatePicker.setOptions(picker, patch)`

- Purpose: Update DatePicker options
- Arguments: `picker, patch`
- Return: `HTMLElement`
- When to use: When changing theme, min/max, step, disabled, or other options after creation.

Usage steps:
1. Put only changed fields in patch.
2. Call BoneDatePicker.setOptions(picker, patch).

Operation details:
- Merges and normalizes options, then updates the trigger and open Calendar.
- DatePicker itself does not commit.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
BoneDatePicker.setOptions(picker, {
  theme: 'neon',
  disabled: false
});
```

### 10.7 `BoneDatePicker.getOptions(picker)`

- Purpose: Read current options
- Arguments: `picker`
- Return: `Object`
- When to use: When inspecting or persisting current DatePicker properties.

Usage steps:
1. Call BoneDatePicker.getOptions(picker).
2. Read the frozen returned object.

Operation details:
- Returns a copy of current options.
- Use setOptions for changes.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const options = BoneDatePicker.getOptions(picker);
console.log(options.theme);
```

### 10.8 `BoneDatePicker.setValue(picker, value)`

- Purpose: Set internal selected date
- Arguments: `picker, value`
- Return: `HTMLElement`
- When to use: When syncing only the picker selection without modifying the INPUT.

Usage steps:
1. Pass YYYY-MM-DD or null.
2. Call BoneDatePicker.setValue(picker, value).

Operation details:
- Updates internal selectedValue and any created Calendar value.
- Does not modify caller INPUT.value.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

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

### 10.9 `BoneDatePicker.getValue(picker)`

- Purpose: Read internal selected date
- Arguments: `picker`
- Return: `string | null`
- When to use: When reading the date currently retained by DatePicker.

Usage steps:
1. Call BoneDatePicker.getValue(picker).

Operation details:
- Returns YYYY-MM-DD or null.
- It is independent of the anchor INPUT value.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const selected = BoneDatePicker.getValue(picker);
```

### 10.10 `BoneDatePicker.getAnchor(picker)`

- Purpose: Read caller INPUT
- Arguments: `picker`
- Return: `HTMLElement`
- When to use: When retrieving the caller INPUT attached to DatePicker.

Usage steps:
1. Call BoneDatePicker.getAnchor(picker).

Operation details:
- Returns the HTMLElement passed as create first argument.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const input = BoneDatePicker.getAnchor(picker);
```

### 10.11 `BoneDatePicker.getPanel(picker)`

- Purpose: Read body-owned Panel
- Arguments: `picker`
- Return: `HTMLElement`
- When to use: When inspecting the body-owned picker panel for positioning or diagnostics.

Usage steps:
1. Call BoneDatePicker.getPanel(picker).

Operation details:
- Returns the panel HTMLElement owned by document.body.
- Use open/close instead of mutating internal DOM.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const panel = BoneDatePicker.getPanel(picker);
```

### 10.12 `BoneDatePicker.getCalendar(picker)`

- Purpose: Read created #024 Calendar
- Arguments: `picker`
- Return: `HTMLElement | null`
- When to use: When accessing the created #024 Calendar instance through public APIs after open.

Usage steps:
1. Open first so Calendar is created.
2. Call BoneDatePicker.getCalendar(picker).

Operation details:
- Returns null before creation or the #024 Calendar HTMLElement afterward.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

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

### 10.13 `BoneDatePicker.open(picker)`

- Purpose: Open the picker
- Arguments: `picker`
- Return: `Object`
- When to use: When opening the DatePicker panel via API.

Usage steps:
1. Call BoneDatePicker.open(picker).
2. Inspect opened in the result.

Operation details:
- Re-reads anchor value, creates/syncs Calendar, and positions panel below INPUT.
- Returns opened=false when disabled/readonly.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
const result = BoneDatePicker.open(picker);
console.log(result.opened);
```

### 10.14 `BoneDatePicker.close(picker)`

- Purpose: Close the picker
- Arguments: `picker`
- Return: `Object`
- When to use: When closing the DatePicker panel via API.

Usage steps:
1. Call BoneDatePicker.close(picker).

Operation details:
- Hides the panel and dispatches close event/callback.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
BoneDatePicker.close(picker);
```

### 10.15 `BoneDatePicker.toggle(picker)`

- Purpose: Toggle open/close
- Arguments: `picker`
- Return: `Object`
- When to use: When switching open/close in one call based on current state.

Usage steps:
1. Call BoneDatePicker.toggle(picker).

Operation details:
- Calls close when open, otherwise open.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
BoneDatePicker.toggle(picker);
```

### 10.16 `BoneDatePicker.isOpen(picker)`

- Purpose: Read open state
- Arguments: `picker`
- Return: `boolean`
- When to use: When checking whether the panel is currently open.

Usage steps:
1. Call BoneDatePicker.isOpen(picker).

Operation details:
- Returns the internal open-state boolean.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
if (BoneDatePicker.isOpen(picker)) {
  BoneDatePicker.close(picker);
}
```

### 10.17 `BoneDatePicker.reposition(picker)`

- Purpose: Reposition below INPUT
- Arguments: `picker`
- Return: `boolean`
- When to use: When immediately recalculating panel position after the INPUT moves.

Usage steps:
1. Confirm the panel is open.
2. Call BoneDatePicker.reposition(picker).

Operation details:
- Uses anchor getBoundingClientRect, bottom+gap, and viewport edge correction.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
if (BoneDatePicker.isOpen(picker)) {
  BoneDatePicker.reposition(picker);
}
```

### 10.18 `BoneDatePicker.validateDate(value, options)`

- Purpose: Validate a date for DatePicker
- Arguments: `value, options`
- Return: `Object`
- When to use: When validating date format and min/max/step selectability without creating a picker.

Usage steps:
1. Pass value and needed min/max/step.
2. Inspect valid/selectable/code.

Operation details:
- Delegates to #024 Calendar.validateDate.
- Converts thrown errors into a valid=false result.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

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

### 10.19 `BoneDatePicker.normalizeOptions(options)`

- Purpose: Normalize options
- Arguments: `options`
- Return: `Object`
- When to use: When pre-validating options with the same formal rules used by create/setOptions.

Usage steps:
1. Pass a plain object.
2. Receive frozen normalized options.

Operation details:
- Validates enums, dates, step, locale, number ranges, and callback types.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

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

### 10.20 `BoneDatePicker.isInstance(picker)`

- Purpose: Check DatePicker instance
- Arguments: `picker`
- Return: `boolean`
- When to use: When safely checking whether an HTMLElement is a BoneDatePicker instance.

Usage steps:
1. Call BoneDatePicker.isInstance(element).

Operation details:
- Returns whether the element is registered in the internal WeakMap.

Responsibility boundary: #025 owns picker display, open/close, and returning the selected date. Caller owns INPUT commit / Bone.value / OUT / Delivery.

```js
if (BoneDatePicker.isInstance(picker)) {
  console.log('DatePicker');
}
```


## 11. Test and completion

Test URL:

```text
http://localhost/boneflow/test/bone-datepicker.html
```

Smoke and Validation start as `NOT RUN`; they are not auto-executed. Static or Node QA does not establish completion. Completed / Specification Frozen requires localhost verification and the user's explicit completion decision.


## Calendar manager button visibility
`showCalendarManagerButtons` defaults to `false`. The Task Type / Task / Event / Holiday-Annotation manager buttons from #024 are shown only when this option is enabled.

## #118 EXIT
All close paths (Close button/API, selection auto-close, Escape, outside click) invoke #118 EXIT first. The panel is not hidden or force-finished immediately after EXIT starts.


## #118 Transition ownership

The picker panel is a formal `bf-transition` host. #025 obtains the single instance owned by `BoneTransitionFunctionalClass.mount/getInstance` and uses `BoneTransition.setOptions/enter/exit/cancel/getState/getTarget` on that instance. #025 does not create or attach a second #118 instance and does not call `finish()` immediately after EXIT. The panel remains visible until the Promise returned by `exit()` resolves with the formal completed state, then #025 applies `hidden=true`.


## Formal #002 Delivery Channel test (Package 1.0.33)

The test page includes the #017-baseline `OUT WAIT / FIFO / BLOCKED` verification panel. This does not add OUT ownership to the BoneDatePicker Runtime. It models Caller OUT after the DatePicker RETURN and delegates WAIT -> READY -> FIFO and BLOCKED non-delivery to `BoneJoint.createDeliveryChannel()`. Component completion requires Smoke/Validation pass plus both visual confirmations.