@openreachtech/furo-vue 1.6.0 → 1.7.0

package/docs/furo-textarea.md

@@ -0,0 +1,214 @@
+# `<FuroTextarea>` Interface Specification
+
+## Overview
+
+Read [`<FuroTextField>`](./furo-text-field.md) first. This page describes the **textarea-specific** contract and the few behavioral differences that follow from using a multiline control.
+
+---
+
+## Differences from `<FuroTextField>`
+
+| Topic | `<FuroTextField>` | `<FuroTextarea>` |
+|--------|-------------------|------------------|
+| Native element | `<input type="text">` | `<textarea>` |
+| CSS root class | `.unit-form-control.text` | `.unit-form-control.textarea` |
+| `type` fallthrough | Excluded (always `text`) | N/A — `<textarea>` has no `type` |
+| `@commit-value` | `blur` **or** `Enter` | **`blur` only** — `Enter` inserts a newline in a `<textarea>` and must not be treated as “commit” by default |
+| `parcel.value` | `string \| number \| null` | `string \| null` only (multiline text; no numeric shortcut) |
+
+### Class and type naming
+
+| Role | Name |
+|------|------|
+| Component | `FuroTextarea` |
+| Context | `FuroTextareaContext` |
+| Emit payload | `TextareaEmitPayload` |
+| Parcel typedef | `FuroTextareaParcel` |
+
+`TextareaEmitPayload` is defined for `<FuroTextarea>` only. It extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js) and exposes the same helper surface as text-field payloads for consistency (`.value`, `.trimmedValue`, `.hasEmptyText()`, `.hasEmptyTrimmedText()`, `.hasEnteredText()`, `.hasEnteredTrimmedText()`). Trimming applies to the full string, including newlines; parent Context implements line-length or format rules if needed.
+
+---
+
+## Props
+
+Same **two mechanisms** as `<FuroTextField>`: `parcel` for Furo behavior, fallthrough for native attributes on the `<textarea>`.
+
+### Rule: `parcel` vs fallthrough attributes
+
+| Mechanism | When to use | Rendered as |
+|-----------|-------------|-------------|
+| `:parcel` | Value, invalid state, and other **component behavior** | Not direct public HTML attr names unless also bound internally |
+| Fallthrough attributes | Native **HTML** attributes for `<textarea>` | On the underlying `<textarea>` |
+
+```html
+<!-- ✅ Correct -->
+<FuroTextarea
+  :parcel="context.descriptionParcel"
+  :disabled="context.descriptionParcel.disabled"
+  rows="5"
+  name="description"
+/>
+```
+
+> **Why the same split as `<FuroTextField>`:** One reviewable `parcel` object for behavior; visible HTML attributes stay in the template where structure is clear.
+
+---
+
+### `parcel` shape
+
+| Key | Type | Required | Default | Description |
+|-----|------|----------|---------|-------------|
+| `value` | `string \| null` | No | `null` | Controlled value; synced to internal ref. |
+| `invalid` | `boolean` | No | `false` | Invalid / error visual state. |
+
+> All values must be **JSON-serializable** (no functions, no class instances).
+
+---
+
+### Fallthrough attributes (recommended usage)
+
+Vue forwards non-prop attributes to the underlying `<textarea>` (with `inheritAttrs: false`, the Context binds them explicitly — same pattern as other Furo atoms).
+
+Commonly used native attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `disabled` | `boolean` | Disables editing. |
+| `readonly` | `boolean` | Read-only display. |
+| `required` | `boolean` | Required for constraint validation. |
+| `placeholder` | `string` | Hint text (not a substitute for a visible label). |
+| `name` | `string` | Form field name. |
+| `rows` | `number` | Visible row hint (HTML `rows`). |
+| `cols` | `number` | Visible column hint (HTML `cols`). |
+| `maxlength` | `number` | Maximum character length. |
+| `minlength` | `number` | Minimum character length. |
+| `wrap` | `'soft' \| 'hard'` | Line wrapping behavior when submitting forms. |
+| `spellcheck` | `boolean \| 'true' \| 'false'` | Native spellcheck hint. |
+| `autocomplete` | `string` | Rare on `<textarea>` but valid when applicable (e.g. street address sections per HTML guidelines). |
+
+Attributes that are **out of scope for documentation examples** but remain valid when passed as fallthrough include `id`, `class`, `style`, `autofocus`, and form-associated attributes your project standardizes elsewhere.
+
+Do **not** rely on fallthrough for “resize handle” behavior — prefer scoped CSS on `.unit-form-control.textarea` (e.g. `resize: vertical`) so UX stays consistent across apps.
+
+---
+
+## Emits
+
+Same event names as `<FuroTextField>`. Payload instances are **`TextareaEmitPayload`** (not `TextFieldEmitPayload`):
+
+| Event | When |
+|-------|------|
+| `@change-value` | Every `input` event (each edit). |
+| `@commit-value` | **`blur` only** on `<textarea>`. |
+| `@update:value` | Alongside the above; raw string for `v-model:value`. |
+
+```html
+<FuroTextarea
+  :parcel="context.buildTextareaParcel()"
+  @change-value="context.onChangeValue({ payload: $event })"
+  @commit-value="context.onCommitValue({ payload: $event })"
+/>
+```
+
+> **Why no Enter-to-commit:** In a multiline field, `Enter` is content. Reusing `keypress.enter` from `<FuroTextField>` would break expected editing. If a product needs “submit on Ctrl+Enter” (or similar), that belongs in the **parent** Context or a higher-level form pattern, not in the default Atom contract.
+
+> **Emitter responsibility:** `<FuroTextarea>` **always emits** for the events above; the parent Context decides validation and side effects. The component does not suppress emits based on value state.
+
+---
+
+## Event handler style in parent Context
+
+Same as [`<FuroTextField>`](./furo-text-field.md#event-handler-style-in-context): **single object parameter** with `{ payload }` destructuring.
+
+```js
+onChangeValue ({
+  payload,
+}) {
+  this.statusReactive.isDescriptionInvalid = !this.validatesDescription({
+    payload,
+  })
+}
+```
+
+---
+
+## `TextareaEmitPayload` API
+
+`@change-value` and `@commit-value` pass a **`TextareaEmitPayload`** instance as `$event`. Members match the behavioral contract documented for [`TextFieldEmitPayload`](./furo-text-field.md#textfieldemitpayload-api), but the **runtime type** for this component is `TextareaEmitPayload` only.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `.value` | `string \| null` | Current raw string value of the `<textarea>`. |
+| `.trimmedValue` | `string \| null` | Whitespace-trimmed `.value` (multiline strings use normal string trim semantics). |
+| `.hasEmptyText()` | `boolean` | `true` if `.value` is empty or the control is missing. |
+| `.hasEmptyTrimmedText()` | `boolean` | `true` if `.trimmedValue` is empty or the control is missing. |
+| `.hasEnteredText()` | `boolean` | `true` if `.value` has at least one character (whitespace counts). |
+| `.hasEnteredTrimmedText()` | `boolean` | `true` if `.trimmedValue` has at least one non-whitespace character. |
+
+Inside `<FuroTextarea>`, emits use `TextareaEmitPayload.create({ rawEvent })` — parallel to `TextFieldEmitPayload` in `<FuroTextField>`, but a separate class so consumers and types stay textarea-specific.
+
+---
+
+## `v-model` Support
+
+Same contract as `<FuroTextField>`: `v-model:value` is sugar over `:parcel` / `@update:value`.
+
+```html
+<FuroTextarea v-model:value="context.descriptionRef.value" />
+```
+
+---
+
+## Controlled vs. uncontrolled state
+
+| Mode | How |
+|------|-----|
+| Controlled | `:parcel="{ value: ... }"` or `v-model:value` |
+| Uncontrolled | Omit `value` in `parcel` |
+
+Internal watcher order should match `<FuroTextField>`: prefer `parcel.value`, then fall back when documenting parity tests.
+
+---
+
+## Example
+
+```html
+<FuroTextarea
+  :parcel="{
+    value: context.descriptionRef.value,
+    invalid: context.statusReactive.isDescriptionInvalid,
+  }"
+  :required="true"
+  rows="6"
+  name="description"
+  placeholder="Describe the issue in detail"
+  @change-value="context.onChangeDescription({ payload: $event })"
+  @commit-value="context.onCommitDescription({ payload: $event })"
+/>
+```
+
+```js
+onChangeDescription ({
+  payload,
+}) {
+  if (payload.hasEmptyTrimmedText()) {
+    this.statusReactive.isDescriptionInvalid = true
+
+    return
+  }
+
+  this.statusReactive.isDescriptionInvalid = !this.validatesDescription({
+    payload,
+  })
+}
+```
+
+---
+
+## Implementation notes (non-normative)
+
+- **Height:** Use `rows` and/or CSS `min-height` on `.unit-form-control.textarea` so layouts do not collapse when `rows` is omitted.
+- **Accessibility:** Keep an associated `<label>` (or `aria-labelledby`) in the parent; pass `id` through fallthrough when wiring `for` / `id`.
+- **Testing:** Snapshot or e2e tests should assert that Enter **does not** fire `commit-value`, only `change-value` (input), whereas blur fires `commit-value`.
+
+---

package/docs/furo-time-field.md

@@ -0,0 +1,276 @@
+# FuroTimeField
+
+Single-time molecule built on a headless segmented time-field primitive. Renders an inline segmented time control (hour / minute, optionally seconds, optionally AM/PM). No popover or portal — segments are edited in place via type or arrow keys.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroTimeField/` |
+| **Base primitive** | Headless segmented time-field (`Root` + `Input`) |
+| **Value type** | `HH:MM:SS` string or `null` |
+| **Wire format** | Always `HH:MM:SS` (zero-padded via `Time#toString()`); accepts `HH:MM` on input |
+| **Granularity** | `minute` (default), `hour`, or `second` via `parcel.granularity` |
+| **Time format** | 12 or 24 via `parcel.timeFormat` (locale default when unset) |
+| **Step** | Step amount for arrow edits and the ▲/▼ buttons via `parcel.step` (default `1`); the unit follows `granularity` (the smallest visible segment) |
+| **Timezone** | Configurable via `parcel.timezone` (IANA); default `null` = naive wall-clock |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `TimeFieldParcel \| null` | `null` | Reactive data object. Furo-only keys are stripped before passthrough to the underlying primitive. |
+
+### Parcel keys
+
+| Key | Type | Description |
+|---|---|---|
+| `value` | `string \| null` | Current time as `HH:MM:SS` (or `HH:MM`) or `null`. Context also accepts `Date` / `Time` at the boundary. |
+| `invalid` | `boolean` | Forces error chrome and `aria-invalid` (external validation). |
+| `placeholder` | `string \| null` | Placeholder text for the time field. |
+| `disabled` | `boolean` | Disables all interaction. Also respected from fallthrough `disabled`, including the bare `<FuroTimeField disabled>` spelling. |
+| `readonly` | `boolean` | Segments are focusable but not editable. Also respected from fallthrough `readonly`, including the bare `<FuroTimeField readonly>` spelling. |
+| `decrementLabel` | `string` | Accessible name of the decrement button. Default `'Decrement time'`. |
+| `incrementLabel` | `string` | Accessible name of the increment button. Default `'Increment time'`. |
+| `minValue` | `string \| null` | Minimum time (`HH:MM:SS`). Out-of-range values are **flagged** (`aria-invalid` + error chrome), not clamped. |
+| `maxValue` | `string \| null` | Maximum time (`HH:MM:SS`). Out-of-range values are **flagged**, not clamped. |
+| `timeFormat` | `number \| null` | `12` or `24`. When unset, the locale default applies. |
+| `granularity` | `'hour' \| 'minute' \| 'second' \| null` | Controls visible segments. When unset, it defaults to `minute`. |
+| `step` | `number \| null` | Step amount for segment arrow edits and the ▲/▼ buttons. Default `1`. The button step unit follows `granularity` (`hour`→hours, `second`→seconds, otherwise minutes). Forwarded as the native `step`. |
+| `stepSnapping` | `boolean \| null` | Optional `stepSnapping`. Forwarded only when explicitly set. |
+| `timezone` | `string \| null` | IANA timezone identifier (e.g. `'Asia/Tokyo'`). When set, `Date` inputs are normalized to wall-clock parts in that zone. Default `null` = naive (local parts). **Furo-only — never forwarded to the underlying primitive.** |
+
+All parcel keys above are **Furo-only** — they are stripped before the root v-bind spread. `step` (and `stepSnapping` when set) are re-applied to the root after stripping; `timezone` is never forwarded. Pass additional native props via `parcel` to forward them.
+
+### Emits
+
+| Event | Payload | Description |
+|---|---|---|
+| `change-value` | `TimeFieldEmitPayload` | Fired when the user edits a segment. |
+| `commit-value` | `TimeFieldEmitPayload` | Fired on the same edit event (inline single-region UX). |
+| `update:value` | `string \| null` | `HH:MM:SS` string or `null`. Suitable for `v-model:value`. |
+
+---
+
+## Usage
+
+### Basic
+
+```vue
+<FuroTimeField
+  :parcel="{ placeholder: 'Pick a time' }"
+  @update:value="onValueChange"
+/>
+```
+
+### v-model binding
+
+```vue
+<FuroTimeField
+  v-model:value="selectedTime"
+  :parcel="{ placeholder: 'Pick a time' }"
+/>
+```
+
+### 12-hour cycle
+
+```vue
+<FuroTimeField
+  :parcel="{
+    timeFormat: 12,
+    value: '14:05:00',
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+`update:value` is always emitted as a 24-hour `HH:MM:SS` string regardless of `timeFormat`.
+
+### Second granularity
+
+```vue
+<FuroTimeField
+  :parcel="{
+    granularity: 'second',
+    value: '08:15:42',
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+### Min / Max bounds
+
+```vue
+<FuroTimeField
+  :parcel="{
+    minValue: '09:00:00',
+    maxValue: '17:00:00',
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+Bounds are **flag-only** for segment editing: out-of-range entries set `aria-invalid` and show error chrome. The control does not clamp or block out-of-range segments — combine with `parcel.invalid` for external validation. The increment/decrement buttons, however, **do clamp** their result to `[minValue, maxValue]`.
+
+### Customizable step + increment/decrement buttons
+
+```vue
+<FuroTimeField
+  :parcel="{
+    step: 5,
+    value: '09:00:00',
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+`parcel.step` (default `1`) controls both the segment arrow-key increment and the two native ▲/▼ stepper buttons rendered inside the field. The step **unit follows `granularity`** — the smallest visible segment: `granularity: 'hour'` steps hours, `'second'` steps seconds, otherwise (default) minutes. The buttons:
+
+- Add / subtract `step` of the smallest segment via `@internationalized/date` `Time.add` / `Time.subtract`.
+- **Clamp** the result to `[minValue, maxValue]` when bounds are set (no overflow past a bound).
+- Start from `00:00:00` when the current value is `null`.
+- Route through the same emit path as segment edits (`change-value` → `update:value` → `commit-value`).
+- Are disabled when `parcel.disabled` / `parcel.readonly`, when increment is at/over `maxValue`, or when decrement is at/under `minValue`.
+
+### Configurable timezone
+
+```vue
+<FuroTimeField
+  :parcel="{
+    timezone: 'Asia/Tokyo',
+    value: someDateObject,
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+When `parcel.timezone` is an IANA identifier, a `Date` input is normalized to wall-clock time parts **in that zone** (via `Intl.DateTimeFormat` with `hourCycle: 'h23'`, each part zero-padded). When `timezone` is `null` (default), `Date` inputs use local `getHours()` / `getMinutes()` / `getSeconds()` (naive). An invalid timezone identifier normalizes to `null`.
+
+The library stays **domain-agnostic** — it never hardcodes a default timezone. Consumers set the default: for example, CloudLink passes `timezone: 'Asia/Tokyo'` from its adapter.
+
+> **Controlled-value note.** `timezone` only affects how a `Date` **input** is read into wall-clock parts; edits emit a plain `HH:MM:SS` string. If you bind `value` to a **fixed** `Date` (not a `ref` updated by `@update:value`), every edit re-normalizes that same `Date` back and the field appears frozen. Bind a controlled value instead — feed the emitted string back, falling back to the `Date` only initially:
+>
+> ```vue
+> :parcel="{ timezone: 'Asia/Tokyo', value: emittedValueRef ?? initialDate }"
+> @update:value="value => { emittedValueRef = value }"
+> ```
+
+### Disabled / read-only
+
+```vue
+<FuroTimeField :parcel="{ disabled: true }" />
+<FuroTimeField :parcel="{ value: '11:20:00', readonly: true }" />
+```
+
+### Invalid state
+
+```vue
+<FuroTimeField
+  :parcel="{
+    placeholder: 'Required field',
+    invalid: isFieldInvalid,
+  }"
+/>
+```
+
+---
+
+## Value contract
+
+| Concern | Decision |
+|---|---|
+| Wire format | `HH:MM:SS` string — always serialized via `Time#toString()` (zero-pads). `HH:MM` accepted on input and padded to `HH:MM:SS`. |
+| Timezone | **Configurable** via `parcel.timezone` (IANA). Default `null` = naive wall-clock (`Date` inputs use local `getHours()` / `getMinutes()` / `getSeconds()`). When set, `Date` inputs are normalized to wall-clock parts in that zone. The library never hardcodes a default — consumers set it (e.g. CloudLink → `'Asia/Tokyo'`). |
+| Range | Single time only; time-range support out of scope. |
+| Clear | Pass `null` to `parcel.value`, or clear all segments via keyboard, to reset to `null`. |
+
+The context accepts these input shapes at the boundary and normalizes to an internal `@internationalized/date` `Time`:
+
+- `HH:MM` / `HH:MM:SS` string → `parseTime`
+- `Date` object (no `timezone`) → `new Time(hours, minutes, seconds)` (local parts)
+- `Date` object (with `timezone`) → wall-clock parts in that IANA zone via `Intl.DateTimeFormat`
+- `Time` instance → passthrough
+- `null` / invalid → `null`
+
+### Native mobile fallback
+
+This molecule does not render a native `<input type="time">`. On mobile, the segmented control is still keyboard- and tap-editable; a native fallback is documented here as a future consideration but is out of scope for v1.
+
+---
+
+## CSS classes
+
+```text
+.unit-form-control.time-field                  ← host div
+.unit-form-control.time-field > .field         ← root host element
+.unit-form-control.time-field > .field.invalid ← invalid state (parcel.invalid OR out-of-range)
+.unit-form-control.time-field > .field.disabled ← disabled state
+.unit-form-control.time-field > .field > .field-input            ← editable segment (hour/minute/second/dayPeriod)
+.unit-form-control.time-field > .field > .field-input[data-placeholder] ← placeholder segment
+.unit-form-control.time-field > .field > .field-input:focus-visible     ← keyboard-active segment
+```
+
+All CSS is scoped under `@layer furo` and uses semantic tokens only (`--color-*`, `--size-*`, `--font-size-*`).
+
+---
+
+## Context: `FuroTimeFieldContext`
+
+`FuroTimeFieldContext` (extends `BaseFuroContext`) holds all reactive state and computed logic. The Vue component is a thin template wrapper.
+
+Key methods:
+
+| Method | Description |
+|---|---|
+| `normalizeToTime({ raw })` | Converts `HH:MM` / `HH:MM:SS` / `Date` / `Time` / `null` → `Time \| null`. |
+| `normalizeStringToTime({ raw })` | Parses a time string via `parseTime`; returns `null` on failure. |
+| `normalizeDateToTime({ raw })` | Converts a `Date` → `Time`. Uses local wall-clock parts, or `parcel.timezone` parts when set. |
+| `normalizeDateToTimeInTimezone({ raw, timezone })` | Converts a `Date` → `Time` using wall-clock parts in a specific IANA timezone; `null` on invalid zone. |
+| `extractTimePartsInTimezone({ raw, timezone })` (static) | Pulls zero-padded `hour` / `minute` / `second` strings from a `Date` via `Intl.DateTimeFormat` (`hourCycle: 'h23'`). |
+| `normalizeToIsoString({ time })` | Converts `Time \| null` → `HH:MM:SS` string or `null` via `Time#toString()`. |
+| `normalizeMinValue()` / `normalizeMaxValue()` | Returns `Time` from `parcel.minValue` / `parcel.maxValue`. |
+| `extractRootAttributes()` | Builds the root attribute object (strips Furo-only keys, applies `modelValue`, `disabled`, `readonly`, `step`, and optional `stepSnapping` / `timeFormat` / `granularity` / `minValue` / `maxValue`). |
+| `stripFuroParcelKeys()` | Removes `FURO_TIME_FIELD_PARCEL_KEYS` from parcel before spreading to the underlying primitive. |
+| `onChangeValue({ time })` | Handles the primitive's `update:modelValue`; emits all three events. |
+| `onIncrementValue()` / `onDecrementValue()` | Steps the value by `step` minutes, clamps to bounds, then routes through the emit trio. |
+| `clampTime({ time })` | Clamps a `Time` into `[minValue, maxValue]`. |
+| `isLiteralPart({ part })` | Whether a segment part is a literal separator (e.g. `:`). |
+| `formatSegmentValue({ part, value })` | Zero-pads filled hour/minute/second segments to two digits (`9` → `09`); day period and literals pass through. With `tabular-nums` this keeps the field width constant as the value changes (no layout shift). |
+| `isTwoDigitSegmentPart({ part })` | Whether a segment part displays zero-padded to two digits (hour, minute, second). |
+
+---
+
+## Files
+
+```text
+lib/components/molecules/FuroTimeField/
+├── FuroTimeField.vue                 ← component
+├── FuroTimeFieldContext.js           ← context
+└── TimeFieldEmitPayload.js           ← typed emit payload
+
+pages/samples/components/playground/FuroTimeFieldPlayground/
+├── index.vue                         ← playground page
+└── FuroTimeFieldPlaygroundContext.js
+
+tests/__tests__/jsdom/lib/components/molecules/FuroTimeField/
+├── FuroTimeFieldContext.js           ← context tests
+└── TimeFieldEmitPayload.js           ← payload tests
+```
+
+---
+
+## Out of scope (v1)
+
+- Combined datetime molecule (`FuroDateTimePicker` — Story 1.5)
+- Time range (`TimeRangeField*`)
+- Native `<input type="time">` mobile fallback
+- i18n locale packs (prop-only)
+
+## Commit semantics note
+
+`change-value` and `commit-value` fire together on every segment edit and on every stepper button press — there is no separate blur/enter distinction (inline single-region UX, identical to `FuroDatePicker`). Treat them as equivalent until cross-component commit semantics are unified.