bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbTimePicker.md

@@ -0,0 +1,231 @@
+# BbTimePicker
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Overlay**
+- Description: Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbTimePicker.md](./source/BbTimePicker.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbTimePicker` is a **picker popover**, not a form field. It renders an activator
+_you_ supply and opens floating time columns — with an adaptive bottom sheet on
+mobile and optional range selection. The value is a 24-hour string via `v-model`,
+the same contract as `BbTimePickerInput`.
+
+Choose between the two time components by _what the control is_:
+
+- A **typed field in a form** — a labelled row where the user reads and edits the
+  time as text, with validation and hint/error chrome → **`BbTimePickerInput`**
+  (`./BbTimePickerInput.md`). It embeds these exact columns and adds the whole
+  segmented text-input surface around them.
+- A time **assigned off your own trigger** — a cell in a schedule table, a chip, a
+  button — no text field, no wrapper chrome → **`BbTimePicker`** (here). Think
+  "set the opening time on this row", not "fill in this field".
+
+For the leanest case, skip the component entirely and use the
+[`v-bb-time` directive](#the-v-bb-time-directive).
+
+### The value: 24-hour in, 24-hour out
+
+`modelValue` is `null` (empty), a 24-hour `HH:mm` string (or `HH:mm:ss` with
+`seconds`), or a two-element `[start, end]` array when `range` is true. The
+`ampm` prop only changes the _display_ (12-hour columns plus an AM/PM column) —
+the emitted value stays 24-hour. `min`/`max` (both `HH:mm`) clamp a pick to the
+nearest bound and emit a `disabled_time` error.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTimePicker } from 'bitboss-ui';
+
+const opensAt = ref<string | null>(null);
+</script>
+
+<template>
+	<BbTimePicker v-model="opensAt">
+		<template #activator="{ props, value }">
+			<button v-bind="props" type="button">
+				{{ value ?? 'Set opening time' }}
+			</button>
+		</template>
+	</BbTimePicker>
+</template>
+```
+
+### The activator contract
+
+Provide your trigger through the `#activator` slot. The scope hands you
+everything to render and wire it:
+
+- `props` — **spread onto your clickable element** (`v-bind="props"`). This
+  registers the element as the popover reference and attaches the click handler
+  and ARIA (`aria-haspopup="dialog"`, `aria-expanded`, `aria-label`) to it.
+- `anchorProps` — spread onto a _wrapping_ element when the popover should align
+  to something larger than the click target. When unused, the activator is also
+  the anchor.
+- `open` — whether the columns are currently shown (read-only).
+- `value` — the current value, mirroring `modelValue`.
+- `disabled` — mirrors the `disabled` prop.
+
+Give it a `label`: it becomes the activator's `aria-label`, essential when your
+trigger is an unlabelled cell or icon.
+
+#### Attaching to an element you already have
+
+When the trigger is an existing element or component (not markup you author in
+the slot), pass it to the `activator` prop instead of using the slot — the same
+click and ARIA wiring is attached programmatically, mirroring `BbDatePicker`.
+`anchor` does the same for the positioning element.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTimePicker, BbButton } from 'bitboss-ui';
+
+const time = ref<string | null>('09:00');
+const triggerRef = ref();
+</script>
+
+<template>
+	<BbButton ref="triggerRef" variant="outline">Pick a time</BbButton>
+	<BbTimePicker v-model="time" :activator="triggerRef" />
+</template>
+```
+
+### Range, ampm, seconds, step
+
+`range` turns the value into `[start, end]`; a small toggle above the columns
+selects which end you are editing (`start` first by default, drivable via
+`v-model:active-segment`). `ampm` renders 12-hour columns plus an AM/PM column
+(the model stays 24-hour), `seconds` adds the third column, and `step` sets the
+minute-column granularity and arrow stepping.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTimePicker } from 'bitboss-ui';
+
+const shift = ref<string[] | null>(['09:00', '17:00']);
+</script>
+
+<template>
+	<BbTimePicker v-model="shift" range :step="15">
+		<template #activator="{ props, value }">
+			<button v-bind="props" type="button">
+				{{
+					Array.isArray(value) && value.length
+						? value.join(' → ')
+						: 'Pick a shift'
+				}}
+			</button>
+		</template>
+	</BbTimePicker>
+</template>
+```
+
+### Adaptive and positioning
+
+On mobile the columns open in a bottom off-canvas sheet instead of a floating
+popover (`adaptive`, on by default via `config.adaptive`; forward extra sheet
+props with `offCanvasProps`). Position the desktop popover with `placement`,
+`offset`, `padding`, `boundary`, and `disableFlip` — the same knobs as the other
+overlays. Escape and backdrop clicks close it; focus returns to the activator.
+
+### The `v-bb-time` directive
+
+For the leanest case — a time cell in a schedule table where you don't want a
+component wrapper per row — attach the `v-bb-time` directive to the element
+instead of importing `BbTimePicker`. It is registered globally by the plugin
+(`injectDirectives`, on by default) and renders no wrapper.
+
+The value is the picker's **props bag**, spread straight onto the component (same
+model as `v-bb-date` / `v-bb-color`). A directive has no `v-model`, so bind
+write-back with an `onUpdate:modelValue` callback. A directive argument sets
+placement (`v-bb-time:top`); a nullish value attaches nothing, so it is safe to
+bind conditionally.
+
+```vue
+<template>
+	<span
+		v-bb-time="{
+			modelValue: row.opensAt,
+			'onUpdate:modelValue': (t) => patch(row, { opensAt: t }),
+		}"
+	>
+		{{ row.opensAt ?? 'Set time' }}
+	</span>
+</template>
+```
+
+Reach for the **component** (slot or `activator` prop) when you want the
+`#activator` slot's scope or a separate `anchor`. Like the other value pickers,
+the directive is the shortcut for the bare-trigger cell case, not a replacement
+for the component's `v-model` in a form.
+
+### Relationship to BbTimePickerInput
+
+`BbTimePickerInput` _is_ these columns with a segmented text field wrapped around
+them: the input owns the typing/validation engine and drives the same popover.
+Anything you can select here you can also select there — pick `BbTimePicker` when
+there is no text field to type into, `BbTimePickerInput` when there is.
+
+### Accessibility
+
+The activator carries `aria-haspopup="dialog"`, `aria-expanded`, and an
+`aria-label` (from `label`, falling back to a localized "Open time picker"). The
+columns expose labelled `role="group"` scrollers with keyboard support and digit
+typeahead. Always pass a `label` when the trigger is an unlabelled cell or icon.
+
+## v-model
+
+- `v-model:activeSegment` — type: `BbTimePickerSegment \| undefined`
+- `v-model` — type: `string \| string[] \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click + ARIA are attached programmatically to the referenced element — mirroring `BbDatePicker`. |
+| `activeSegment` | `BbTimePickerSegment \| undefined` |  |  | Which end the columns edit in range mode (`v-model:active-segment`). Standalone use manages this internally via the in-panel toggle; a host can drive it. Ignored outside `range`. |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
+| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM column; emitted values stay 24-hour. |
+| `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the activator and the columns. |
+| `disableFlip` | `boolean \| undefined` |  |  | Disable the automatic flip to the opposite side on overflow. |
+| `eager` | `boolean \| undefined` |  |  | Render popover content before it is first shown. |
+| `label` | `string \| undefined` |  |  | Accessible label applied to the activator via `aria-label`. |
+| `max` | `string \| undefined` |  |  | Maximum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
+| `min` | `string \| undefined` |  |  | Minimum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
+| `modelValue` | `string \| string[] \| null` |  | yes | v-model value: `null` for empty, a 24-hour `HH:mm` (or `HH:mm:ss` with `seconds`) string, or a two-element `[start, end]` array when `range` is true. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when adaptive on mobile. |
+| `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
+| `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
+| `placement` | `Placement \| undefined` |  |  | Position of the popover relative to the activator/anchor. |
+| `range` | `boolean \| undefined` |  |  | Range selection: the value is a two-element `[start, end]` array. |
+| `readonly` | `boolean \| undefined` |  |  | Prevents opening while keeping the activator visible. |
+| `seconds` | `boolean \| undefined` |  |  | Adds the seconds column. |
+| `step` | `number \| undefined` |  |  | Minute-column granularity and arrow stepping. |
+| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Popover/sheet transition duration in milliseconds. |
+
+## Events
+
+- `error` — `(event: "error", error: TimePickerInputError): void`
+- `time-pick` — `(event: "time-pick", payload: { unit: TimeUnit; value: string; }): void`
+- `update:activeSegment` — `(event: "update:activeSegment", value: BbTimePickerSegment): void`
+- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
+
+## Slots
+
+- `activator` — scope: `BbTimePickerActivatorSlotProps` — Custom activator element. Apply `v-bind="props"` to your trigger.
+
+## See Also
+
+- [BbTimePickerInput](./BbTimePickerInput.md) — Segmented time field with hour/minute columns; 24-hour string model.
+- [BbDatePicker](./BbDatePicker.md) — Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
+- [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.

package/dist/ai/BbTimePickerInput.md

@@ -0,0 +1,200 @@
+# BbTimePickerInput
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: Segmented time field with hour/minute columns; 24-hour string model.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbTimePickerInput.md](./source/BbTimePickerInput.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbTimePickerInput` when the user picks a **time with no date attached** —
+opening hours, shift boundaries, a daily reminder, a recurring slot. It renders
+segmented hour/minute fields (auto-advance, paste distribution) plus a popover
+with scrollable hour/minute columns, and shares the input-family chrome
+(`label`, `description`, `hint`, `errors`, affixes, `clearable`, `loading`).
+
+If the time belongs to a specific calendar day, use
+[`BbDatePickerInput`](./BbDatePickerInput.md) with `datetime` instead —
+its `v-model:time` uses the exact same string contract as this component's
+`v-model`, so the two compose naturally.
+
+`v-model` holds `null` or a 24-hour **`HH:mm`** string (`HH:mm:ss` with
+`seconds`); set `range` and bind a `[start, end]` array for a window. `label`
+is required.
+
+**A plain time**
+
+```vue
+<BbTimePickerInput
+	v-model="state.opensAt"
+	label="Opens at"
+	prepend:icon="lucide:clock"
+/>
+```
+
+### Value contract
+
+- Always **24-hour strings**, zero-padded: `'09:05'`, `'14:30'`, `'14:30:45'`
+  with `seconds`. The `ampm` display never changes the model.
+- `null` (or `[]` in range mode) is the empty state.
+- A blank seconds segment commits as `:00`; without `seconds`, an incoming
+  value carrying seconds displays truncated and zeroes out on the next commit.
+
+### Display options
+
+- **`ampm`** — 12-hour display with an AM/PM segment. Type `A`/`P` or cycle
+  with ArrowUp/Down; the columns label hours `12 AM … 11 PM`.
+- **`seconds`** — adds the `:ss` segment and a seconds column.
+- **`step`** (minutes, default `1`) — shapes the minute column (`:step="15"` →
+  00/15/30/45) and constrains what the columns produce, never what typing
+  accepts: `10:07` typed under `step: 15` is emitted verbatim and no row
+  highlights for it.
+
+**12-hour display, quarter-hour slots**
+
+```vue
+<BbTimePickerInput v-model="state.slotAt" ampm :step="15" label="Pickup slot" />
+```
+
+### Bounds & ranges
+
+`min` / `max` (`HH:mm`) clamp typed times when interaction ends — the value
+snaps to the nearest bound and an `error` event with code `disabled_time`
+fires (`{ original, normalized }`). In `range` mode the model is `[start,
+end]`; typing an inverted pair swaps it on blur with the usual
+`end_before_start` error.
+
+**Business-hours bound**
+
+```vue
+<BbTimePickerInput
+	v-model="state.callAt"
+	min="09:00"
+	max="18:00"
+	label="Callback time"
+	hint="We call between 09:00 and 18:00."
+	persistentHint
+/>
+```
+
+### Platform behaviour
+
+The popover follows the family's adaptive pattern: on mobile (with the global
+`config.adaptive`, or the `adaptive` prop) the columns open in a bottom sheet
+(`offCanvasProps` forwards extras). `disableWriting` (`true` / `'mobile'` /
+`'desktop'`) turns off typing per platform — the columns then carry the
+interaction.
+
+### Events & v-model
+
+| Event               | Payload                      | When                                    |
+| ------------------- | ---------------------------- | --------------------------------------- |
+| `update:modelValue` | `string \| string[] \| null` | every committed change                  |
+| `error`             | `TimePickerInputError`       | clamped time, swapped range             |
+| `active`/`inactive` | —                            | focus enters / leaves the whole control |
+| `focus`             | `FocusEvent`                 | a native field gains focus              |
+
+### Gotchas & anti-patterns
+
+- **Don't parse the value with `new Date('14:30')`** — it's a wall-clock
+  string, not an instant. Prepend a date first (`dayjs(`2026-01-01T${t}`)`)
+  when you need date maths.
+- **`range` needs an array model** — seed and clear with `[]`, never `null`.
+- **The model is never 12-hour.** Render `h:mm A` yourself for display copy;
+  the field already does it with `ampm`.
+
+### Accessibility
+
+Each segment is a labelled input (`Hour`, `Minute`, `Second`, `AM/PM` — via
+the shared locale keys); the clock button announces the current selection and
+controls a dialog; the columns are labelled groups whose options expose
+`aria-pressed`. The format hint is linked via `aria-describedby`, merged with
+the ids the container contributes — `errors`, `warnings`, `description` and
+`hint`, in that order, each referenced only while it actually has copy — so the
+reason the field is invalid is spoken first when a segment regains focus.
+Messages _also_ render in an `aria-live="polite"` region.
+
+## v-model
+
+- `v-model` — type: `string \| string[] \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile the time columns open inside a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
+| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM segment. Purely a field-composition concern: the model stays 24-hour. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
+| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Always visible and linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
+| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Disables typing into the input. Use `'mobile'` / `'desktop'` to disable typing on one platform only. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the segment inputs' `aria-descr… |
+| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `max` | `string \| undefined` |  |  | Maximum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
+| `min` | `string \| undefined` |  |  | Minimum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
+| `modelValue` | `string \| string[] \| null` |  | yes | v-model value: `null` for empty, a 24-hour `HH:mm` (or `HH:mm:ss` with `seconds`) string, or a two-element array when `range` is true. |
+| `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
+| `range` | `boolean \| undefined` |  |  | Range selection: v-model expects a two-element array `[start, end]`. An inverted pair swaps on finalize with an `end_before_start` error. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` |  |  | Reverses the layout: the order of the label and the input is swapped. |
+| `seconds` | `boolean \| undefined` |  |  | Adds the seconds segment. Without it an incoming value carrying seconds displays truncated and zeroes out on the next user commit. |
+| `step` | `number \| undefined` |  |  | Minute granularity for the minute column and its arrow stepping. Constrains what the columns produce, never what typing accepts. |
+| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also… |
+
+## Events
+
+- `active` — `(event: "active"): void`
+- `error` — `(event: "error", error: TimePickerInputError): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `inactive` — `(event: "inactive"): void`
+- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the time fields (before the clock button).
+- `append-outer` — scope: `object` — Content rendered after the entire control, outside the input chrome.
+- `label` — scope: `BbTimePickerInputLabelSlotProps` — Replaces the default label text rendered above the input.
+- `prefix` — scope: `object` — Inline content at the start of the field area.
+- `prepend` — scope: `object` — Content rendered before the time fields, at the start of the inner container.
+- `prepend-outer` — scope: `object` — Content rendered before the entire control, outside the input chrome.
+- `suffix` — scope: `object` — Inline content at the end of the field area.
+
+## Validated variant
+
+Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `rules` | `RuleExpression<string \| string[] \| null>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
+| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+
+## See Also
+
+- [BbTimePicker](./BbTimePicker.md) — Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
+- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.
+- [BbTextInput](./BbTextInput.md) — Captures single-line text values.