@usableapp/cardds 0.7.107 → 0.7.108

package/dist/choice/Calendar.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentProps, type ReactNode } from 'react';
+import { type Span } from './span.js';
 export interface CalendarProps extends Omit<ComponentProps<'div'>, 'title' | 'onSelect'> {
     /** the month shown ("June") */
     title: ReactNode;
@@ -12,6 +13,12 @@ export interface CalendarProps extends Omit<ComponentProps<'div'>, 'title' | 'on
     defaultSelected?: number;
     /** a day was tapped */
     onSelect?: (day: number) => void;
+    /** CONTROLLED, a run of days instead of one: `[first, last]` (the same day twice for one), or `null` for none; pair it with `onSpanChange`. Given (or `defaultSpan` / `onSpanChange`), the calendar is a span pick: a drag across the days covers them, or a tap on the first and a tap on the last; `selected` is not read */
+    span?: Span | null;
+    /** UNCONTROLLED: the run covered on arrival; the calendar then keeps its own */
+    defaultSpan?: Span;
+    /** the member covered a run: the finger lifted after a drag, or the second tap closed it */
+    onSpanChange?: (span: Span) => void;
     /** the previous-month button was tapped: the app turns the month (it owns `title`, `days`, `start`) */
     onPrev?: () => void;
     /** the next-month button was tapped: the app turns the month, as with `onPrev` */
@@ -24,7 +31,7 @@ export interface CalendarProps extends Omit<ComponentProps<'div'>, 'title' | 'on
     marks?: number[];
     /** strongly marked days */
     marks2?: number[];
-    /** days that cannot be picked */
+    /** days that cannot be picked (a span never covers one: the run stops before it) */
     disabled?: number[];
     /** weekday headers, 7 */
     weekdays?: string[];
@@ -32,5 +39,7 @@ export interface CalendarProps extends Omit<ComponentProps<'div'>, 'title' | 'on
     nav?: ReactNode;
 }
 /** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. It shows ONE month and knows no dates:
- *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`). On a sheet, never in a Card: the sheet is the paper the member fills in (Lh 2026-10-18). */
-export declare function Calendar({ title, days, start, selected, defaultSelected, onSelect, onPrev, onNext, prevLabel, nextLabel, marks, marks2, disabled, weekdays, nav, className, ...rest }: CalendarProps): import("react").JSX.Element;
+ *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`).
+ *  A run of days instead of one (the asker says from when to when, Lh 2026-10-21): `span` + `onSpanChange`, or `defaultSpan` — a drag across
+ *  the days covers them, or a tap on the first day and a tap on the last; the whole run is one highlight, as a finger drags over words. On a sheet, never in a Card: the sheet is the paper the member fills in (Lh 2026-10-18). */
+export declare function Calendar({ title, days, start, selected, defaultSelected, onSelect, span, defaultSpan, onSpanChange, onPrev, onNext, prevLabel, nextLabel, marks, marks2, disabled, weekdays, nav, className, ...rest }: CalendarProps): import("react").JSX.Element;

package/dist/choice/Calendar.js

@@ -4,12 +4,24 @@ import { cx } from '../cx.js';
 import { IconBtn } from '../actions/IconBtn.js';
 import { word } from '../words.js';
 import { calendarDay } from './calendarDay.js';
+import { useSpan } from './span.js';
 /** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. It shows ONE month and knows no dates:
- *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`). On a sheet, never in a Card: the sheet is the paper the member fills in (Lh 2026-10-18). */
-export function Calendar({ title, days = 30, start = 1, selected, defaultSelected, onSelect, onPrev, onNext, prevLabel = word('previous'), nextLabel = word('next'), marks = [], marks2 = [], disabled = [], weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], nav, className, ...rest }) {
+ *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`).
+ *  A run of days instead of one (the asker says from when to when, Lh 2026-10-21): `span` + `onSpanChange`, or `defaultSpan` — a drag across
+ *  the days covers them, or a tap on the first day and a tap on the last; the whole run is one highlight, as a finger drags over words. On a sheet, never in a Card: the sheet is the paper the member fills in (Lh 2026-10-18). */
+export function Calendar({ title, days = 30, start = 1, selected, defaultSelected, onSelect, span, defaultSpan, onSpanChange, onPrev, onNext, prevLabel = word('previous'), nextLabel = word('next'), marks = [], marks2 = [], disabled = [], weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], nav, className, ...rest }) {
     const [day, pick] = useControlled(selected, defaultSelected, onSelect);
-    return (_jsxs("div", { className: cx('calendar', className), ...rest, children: [_jsxs("div", { className: "calendar__head", children: [_jsx("span", { className: "t-title", children: title }), nav ?? (_jsxs("span", { className: "icon-row", children: [_jsx(IconBtn, { sm: true, icon: "chevron-left", label: prevLabel, onClick: onPrev }), _jsx(IconBtn, { sm: true, icon: "chevron-right", label: nextLabel, onClick: onNext })] }))] }), _jsxs("div", { className: "calendar__grid", children: [weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)), Array.from({ length: days }, (_, i) => i + 1).map((d) => (calendarDay({
-                        key: d, num: d, mark: marks.includes(d), mark2: marks2.includes(d), selected: d === day, disabled: disabled.includes(d),
-                        style: d === 1 ? { '--start': start } : undefined, onPick: () => pick(d),
+    const spanning = span !== undefined || defaultSpan !== undefined || onSpanChange !== undefined;
+    // the hook counts cells from 0; the app counts days from 1
+    const run = useSpan({
+        span: span ? [span[0] - 1, span[1] - 1] : span, defaultSpan: defaultSpan && [defaultSpan[0] - 1, defaultSpan[1] - 1],
+        onSpanChange: onSpanChange && ((s) => onSpanChange([s[0] + 1, s[1] + 1])),
+        blocked: (i) => i < 0 || i >= days || disabled.includes(i + 1),
+    });
+    return (_jsxs("div", { className: cx('calendar', spanning && 'calendar--span', className), ...rest, children: [_jsxs("div", { className: "calendar__head", children: [_jsx("span", { className: "t-title", children: title }), nav ?? (_jsxs("span", { className: "icon-row", children: [_jsx(IconBtn, { sm: true, icon: "chevron-left", label: prevLabel, onClick: onPrev }), _jsx(IconBtn, { sm: true, icon: "chevron-right", label: nextLabel, onClick: onNext })] }))] }), _jsxs("div", { className: "calendar__grid", ...(spanning ? run.box : {}), children: [weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)), Array.from({ length: days }, (_, i) => i + 1).map((d) => (calendarDay({
+                        key: d, num: d, mark: marks.includes(d), mark2: marks2.includes(d), selected: !spanning && d === day, disabled: disabled.includes(d),
+                        style: d === 1 ? { '--start': start } : undefined,
+                        onPick: () => (spanning ? run.tap(d - 1) : pick(d)),
+                        ...(spanning ? { index: d - 1, span: run.at(d - 1) } : {}),
                     })))] })] }));
 }

package/dist/choice/CalendarWeeks.d.ts

@@ -28,6 +28,12 @@ export interface CalendarWeeksProps extends Omit<ComponentProps<'div'>, 'onSelec
     defaultSelected?: string;
     /** a day was tapped: its `key` */
     onSelect?: (key: string) => void;
+    /** CONTROLLED, a run of days instead of one: `[first, last]` by `key` (the same key twice for one day), or `null` for none; pair it with `onSpanChange`. Given (or `defaultSpan` / `onSpanChange`), the weeks are a span pick: a tap on the first day and a tap on the last covers the days between, across the weeks; a drag along a row covers it too (up and down, the box scrolls); `selected` is not read */
+    span?: [string, string] | null;
+    /** UNCONTROLLED: the run covered on arrival; the weeks then keep their own */
+    defaultSpan?: [string, string];
+    /** the member covered a run: the finger lifted after a drag, or the second tap closed it */
+    onSpanChange?: (span: [string, string]) => void;
     /** weekday heads, 7 */
     weekdays?: string[];
     /** given, the label is a button: the app opens its own month / year pick. Not given, the label is plain words */
@@ -37,5 +43,7 @@ export interface CalendarWeeksProps extends Omit<ComponentProps<'div'>, 'onSelec
  *  the month · year of the first row in sight and the weekday heads. It knows no dates, as Calendar: the app builds `weeks` (each a `label` and 7 days
  *  with `key`, `num`, `today`, `disabled`, `mark`) and owns the day (`selected` + `onSelect`, or `defaultSelected`); a tap on the label (`onLabelClick`)
  *  is the app's to answer with its month / year pick. It opens at the week that holds today (Lh 2026-10-19): the first row in sight is the week
- *  whose day has `today`, at once and without a scroll to watch; with no `today` in the data it opens at the first week. For a day within the coming weeks on a step with little height. On a sheet, never in a Card. */
-export declare function CalendarWeeks({ weeks, show, selected, defaultSelected, onSelect, weekdays, onLabelClick, className, ref, ...rest }: CalendarWeeksProps): import("react").JSX.Element;
+ *  whose day has `today`, at once and without a scroll to watch; with no `today` in the data it opens at the first week. For a day within the coming weeks on a step with little height.
+ *  A run of days instead of one (the asker says from when to when, Lh 2026-10-21): `span` + `onSpanChange`, or `defaultSpan` — a tap on the first day
+ *  and a tap on the last covers the days between, across the weeks; a drag along a row covers it too, while a finger moving up or down still scrolls the box. On a sheet, never in a Card. */
+export declare function CalendarWeeks({ weeks, show, selected, defaultSelected, onSelect, span, defaultSpan, onSpanChange, weekdays, onLabelClick, className, ref, ...rest }: CalendarWeeksProps): import("react").JSX.Element;

package/dist/choice/CalendarWeeks.js

@@ -3,13 +3,20 @@ import { useLayoutEffect, useRef, useState } from 'react';
 import { useControlled, setRefs } from '../state.js';
 import { cx } from '../cx.js';
 import { calendarDay } from './calendarDay.js';
+import { useSpan, spanByKey } from './span.js';
 /** CalendarWeeks — a run of weeks that scrolls week by week, `show` rows in sight (2 by default), Calendar's own 44px round cells; a sticky head holds
  *  the month · year of the first row in sight and the weekday heads. It knows no dates, as Calendar: the app builds `weeks` (each a `label` and 7 days
  *  with `key`, `num`, `today`, `disabled`, `mark`) and owns the day (`selected` + `onSelect`, or `defaultSelected`); a tap on the label (`onLabelClick`)
  *  is the app's to answer with its month / year pick. It opens at the week that holds today (Lh 2026-10-19): the first row in sight is the week
- *  whose day has `today`, at once and without a scroll to watch; with no `today` in the data it opens at the first week. For a day within the coming weeks on a step with little height. On a sheet, never in a Card. */
-export function CalendarWeeks({ weeks, show = 2, selected, defaultSelected, onSelect, weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], onLabelClick, className, ref, ...rest }) {
+ *  whose day has `today`, at once and without a scroll to watch; with no `today` in the data it opens at the first week. For a day within the coming weeks on a step with little height.
+ *  A run of days instead of one (the asker says from when to when, Lh 2026-10-21): `span` + `onSpanChange`, or `defaultSpan` — a tap on the first day
+ *  and a tap on the last covers the days between, across the weeks; a drag along a row covers it too, while a finger moving up or down still scrolls the box. On a sheet, never in a Card. */
+export function CalendarWeeks({ weeks, show = 2, selected, defaultSelected, onSelect, span, defaultSpan, onSpanChange, weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], onLabelClick, className, ref, ...rest }) {
     const [day, pick] = useControlled(selected, defaultSelected, onSelect);
+    const spanning = span !== undefined || defaultSpan !== undefined || onSpanChange !== undefined;
+    const all = weeks.flatMap((w) => w.days);
+    const covered = useSpan({ ...spanByKey(all.map((d) => d.key), span, defaultSpan, onSpanChange), blocked: (i) => !all[i] || !!all[i].disabled });
+    let at = 0;
     const [first, setFirst] = useState(0);
     const box = useRef(null);
     // the box opens at today's week whenever the run itself is new (its days, not its identity: an app that rebuilds `weeks` on each render
@@ -58,7 +65,14 @@ export function CalendarWeeks({ weeks, show = 2, selected, defaultSelected, onSe
         return () => { watch.disconnect(); el.removeEventListener('scroll', onScroll); cancelAnimationFrame(frame); };
     }, [show, run, todayAt]);
     const label = weeks[Math.min(first, weeks.length - 1)]?.label;
-    return (_jsxs("div", { ref: setRefs(box, ref), className: cx('calendar', 'calendar--weeks', className), ...rest, children: [_jsxs("div", { className: "calendar__weeks-head", children: [onLabelClick
+    return (_jsxs("div", { ref: setRefs(box, ref), className: cx('calendar', 'calendar--weeks', spanning && 'calendar--span', className), ...rest, ...(spanning ? covered.box : {}), children: [_jsxs("div", { className: "calendar__weeks-head", children: [onLabelClick
                         ? _jsx("button", { type: "button", className: "calendar__label", onClick: onLabelClick, children: label })
-                        : _jsx("span", { className: "calendar__label", children: label }), _jsx("div", { className: "calendar__grid", children: weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)) })] }), weeks.map((w, i) => (_jsx("div", { className: "calendar__grid calendar__week", children: w.days.map((d) => calendarDay({ key: d.key, num: d.num, mark: d.mark === 'soft', mark2: d.mark === 'strong', selected: d.key === day, today: d.today, disabled: d.disabled, onPick: () => pick(d.key) })) }, w.days[0]?.key ?? i)))] }));
+                        : _jsx("span", { className: "calendar__label", children: label }), _jsx("div", { className: "calendar__grid", children: weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)) })] }), weeks.map((w, i) => (_jsx("div", { className: "calendar__grid calendar__week", children: w.days.map((d) => {
+                    const i = at++;
+                    return calendarDay({
+                        key: d.key, num: d.num, mark: d.mark === 'soft', mark2: d.mark === 'strong', selected: !spanning && d.key === day, today: d.today, disabled: d.disabled,
+                        onPick: () => (spanning ? covered.tap(i) : pick(d.key)),
+                        ...(spanning ? { index: i, span: covered.at(i) } : {}),
+                    });
+                }) }, w.days[0]?.key ?? i)))] }));
 }

package/dist/choice/HourGrid.d.ts

@@ -0,0 +1,36 @@
+import { type ComponentProps, type ReactNode } from 'react';
+export interface Hour {
+    /** the app's id for the hour ("09:00"): what `onSpanChange` and `onSelect` hand back */
+    key: string;
+    /** what the cell shows ("9", "๙") */
+    num: ReactNode;
+    /** the hour cannot be picked (already past, outside the asked span) */
+    disabled?: boolean;
+    /** a soft mark (the asked hours) or a strong one (booked) */
+    mark?: 'soft' | 'strong';
+}
+export interface HourGridProps extends Omit<ComponentProps<'div'>, 'onSelect'> {
+    /** the hours, in order; the app builds them (which hours, in whose numerals) */
+    hours: Hour[];
+    /** the words over the grid: what the numbers are ("hour of the day", "น.") */
+    label?: ReactNode;
+    /** CONTROLLED, from when to when: `[first, last]` by `key` (the same key twice for one hour), or `null` for none; pair it with `onSpanChange`. Given (or `defaultSpan` / `onSpanChange`), a drag across the hours covers them, or a tap on the first and a tap on the last; `selected` is not read */
+    span?: [string, string] | null;
+    /** UNCONTROLLED: the run covered on arrival; the grid then keeps its own */
+    defaultSpan?: [string, string];
+    /** the member covered a run: the finger lifted after a drag, or the second tap closed it */
+    onSpanChange?: (span: [string, string]) => void;
+    /** CONTROLLED, one hour: the picked hour's `key`, or `null` for none; pair it with `onSelect` */
+    selected?: string | null;
+    /** UNCONTROLLED: the hour picked on arrival */
+    defaultSelected?: string;
+    /** an hour was tapped: its `key` */
+    onSelect?: (key: string) => void;
+}
+/** HourGrid — the hours of a day as Calendar's own 44px round cells, `--hour-grid-cols` to a row (6 by default), with a label over them. From when
+ *  to when (the asker's hours, Lh 2026-10-21): `span` + `onSpanChange`, or `defaultSpan` — one drag across the hours covers them, or a tap on the
+ *  first and a tap on the last; the whole run is one highlight, and it never jumps a disabled hour.
+ *  One hour instead: `selected` + `onSelect`, or `defaultSelected`. The helper answers within the asked hours: the app marks them (`mark: 'soft'`)
+ *  and disables the rest, and the helper's own span stays inside. It knows no clock: the app builds `hours` (`key`, `num`, `disabled`, `mark`).
+ *  On a sheet, never in a Card. */
+export declare function HourGrid({ hours, label, span, defaultSpan, onSpanChange, selected, defaultSelected, onSelect, className, ...rest }: HourGridProps): import("react").JSX.Element;

package/dist/choice/HourGrid.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useControlled } from '../state.js';
+import { cx } from '../cx.js';
+import { calendarDay } from './calendarDay.js';
+import { useSpan, spanByKey } from './span.js';
+/** HourGrid — the hours of a day as Calendar's own 44px round cells, `--hour-grid-cols` to a row (6 by default), with a label over them. From when
+ *  to when (the asker's hours, Lh 2026-10-21): `span` + `onSpanChange`, or `defaultSpan` — one drag across the hours covers them, or a tap on the
+ *  first and a tap on the last; the whole run is one highlight, and it never jumps a disabled hour.
+ *  One hour instead: `selected` + `onSelect`, or `defaultSelected`. The helper answers within the asked hours: the app marks them (`mark: 'soft'`)
+ *  and disables the rest, and the helper's own span stays inside. It knows no clock: the app builds `hours` (`key`, `num`, `disabled`, `mark`).
+ *  On a sheet, never in a Card. */
+export function HourGrid({ hours, label, span, defaultSpan, onSpanChange, selected, defaultSelected, onSelect, className, ...rest }) {
+    const spanning = span !== undefined || defaultSpan !== undefined || onSpanChange !== undefined;
+    const [hour, pick] = useControlled(selected, defaultSelected, onSelect);
+    const run = useSpan({ ...spanByKey(hours.map((h) => h.key), span, defaultSpan, onSpanChange), blocked: (i) => !hours[i] || !!hours[i].disabled });
+    return (_jsxs("div", { className: cx('calendar', 'hour-grid', spanning && 'calendar--span', className), ...rest, children: [label != null && _jsx("span", { className: "calendar__label", children: label }), _jsx("div", { className: "calendar__grid", ...(spanning ? run.box : {}), children: hours.map((h, i) => calendarDay({
+                    key: h.key, num: h.num, mark: h.mark === 'soft', mark2: h.mark === 'strong', selected: !spanning && h.key === hour, disabled: h.disabled,
+                    onPick: () => (spanning ? run.tap(i) : pick(h.key)),
+                    ...(spanning ? { index: i, span: run.at(i) } : {}),
+                })) })] }));
+}

package/dist/choice/calendarDay.d.ts

@@ -1,6 +1,9 @@
 import { type CSSProperties, type ReactNode } from 'react';
-/** one `.calendar__day` cell: the button Calendar and CalendarWeeks both draw, so the cell and every `--calendar-day-*` knob are one */
-export declare function calendarDay({ key, num, mark, mark2, selected, today, disabled, style, onPick }: {
+import type { SpanAt } from './span.js';
+/** one `.calendar__day` cell: the button Calendar, CalendarWeeks and HourGrid all draw, so the cell and every `--calendar-day-*` knob are one.
+ *  In a span (`index` given): the cell carries its order for the span mechanic, and `span` says where it stands under the one highlight
+ *  (`aria-pressed` says whether it is covered); a key on the cell (not a pointer, which the grid handles) is a tap */
+export declare function calendarDay({ key, num, mark, mark2, selected, today, disabled, style, onPick, index, span }: {
     key: string | number;
     num: ReactNode;
     mark?: boolean;
@@ -10,4 +13,6 @@ export declare function calendarDay({ key, num, mark, mark2, selected, today, di
     disabled?: boolean;
     style?: CSSProperties;
     onPick: () => void;
+    index?: number;
+    span?: SpanAt;
 }): import("react").JSX.Element;

package/dist/choice/calendarDay.js

@@ -1,6 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
-/** one `.calendar__day` cell: the button Calendar and CalendarWeeks both draw, so the cell and every `--calendar-day-*` knob are one */
-export function calendarDay({ key, num, mark, mark2, selected, today, disabled, style, onPick }) {
-    return (_jsx("button", { type: "button", className: cx('calendar__day', mark && 'calendar__day--mark', mark2 && 'calendar__day--mark2'), "aria-selected": selected ? 'true' : undefined, "aria-current": today ? 'date' : undefined, onClick: onPick, disabled: disabled, style: style, children: num }, key));
+/** one `.calendar__day` cell: the button Calendar, CalendarWeeks and HourGrid all draw, so the cell and every `--calendar-day-*` knob are one.
+ *  In a span (`index` given): the cell carries its order for the span mechanic, and `span` says where it stands under the one highlight
+ *  (`aria-pressed` says whether it is covered); a key on the cell (not a pointer, which the grid handles) is a tap */
+export function calendarDay({ key, num, mark, mark2, selected, today, disabled, style, onPick, index, span }) {
+    return (_jsx("button", { type: "button", className: cx('calendar__day', mark && 'calendar__day--mark', mark2 && 'calendar__day--mark2', span && `calendar__day--span-${span}`), "aria-selected": selected ? 'true' : undefined, "aria-pressed": index === undefined ? undefined : span ? 'true' : 'false', "aria-current": today ? 'date' : undefined, onClick: index === undefined ? onPick : (e) => { if (e.detail === 0)
+            onPick(); }, disabled: disabled, style: style, "data-span": index, children: num }, key));
 }

package/dist/choice/span.d.ts

@@ -0,0 +1,34 @@
+import { type PointerEvent as ReactPointerEvent } from 'react';
+/** a run of cells, by their index in the holder's order: `[first, last]`, the same index twice for one cell */
+export type Span = [number, number];
+/** where a cell stands in the span: the one cell of a one-cell span, the first, one between, the last — or nowhere */
+export type SpanAt = 'one' | 'start' | 'in' | 'end' | undefined;
+/** the span mechanic, written once for Calendar, CalendarWeeks and HourGrid (Lh 2026-10-21: the asker says from when to when).
+ *  The holder numbers its cells in order (`data-span` = the index), spreads `box` on the grid, and asks `at(i)` for each cell's class.
+ *  One drag across the cells covers them: the first cell under the finger is one end, the last the other, whichever way the finger
+ *  went. Two taps do the same without a drag: a tap makes a one-cell span, a second tap on another cell closes it (a third starts over).
+ *  A cell that is `blocked` (disabled) is never covered: the run stops before it, so a span never jumps a day that cannot be picked.
+ *  Controlled like an input: `span` + `onSpanChange`, or `defaultSpan`; while the finger is down the cells show the live run and the
+ *  app is asked once, when it lifts. A pointer the browser takes away (the box scrolled instead) covers nothing. */
+export declare function useSpan({ span, defaultSpan, onSpanChange, blocked }: {
+    span: Span | null | undefined;
+    defaultSpan?: Span;
+    onSpanChange?: (span: Span) => void;
+    blocked: (i: number) => boolean;
+}): {
+    span: Span | null;
+    at: (i: number) => SpanAt;
+    tap: (i: number) => void;
+    box: {
+        onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
+        onPointerMove: (e: ReactPointerEvent<HTMLElement>) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+    };
+};
+/** the same span by the holder's keys (CalendarWeeks, HourGrid): useSpan's `span`, `defaultSpan` and `onSpanChange` from a `[key, key]` span, the ask handed back in keys */
+export declare function spanByKey(keys: string[], span: [string, string] | null | undefined, defaultSpan: [string, string] | undefined, onSpanChange: ((span: [string, string]) => void) | undefined): {
+    span: Span | null | undefined;
+    defaultSpan: Span | undefined;
+    onSpanChange: ((s: Span) => void) | undefined;
+};

package/dist/choice/span.js

@@ -0,0 +1,80 @@
+import { useRef, useState } from 'react';
+import { useControlled } from '../state.js';
+const sorted = (a, b) => (a <= b ? [a, b] : [b, a]);
+/** the span mechanic, written once for Calendar, CalendarWeeks and HourGrid (Lh 2026-10-21: the asker says from when to when).
+ *  The holder numbers its cells in order (`data-span` = the index), spreads `box` on the grid, and asks `at(i)` for each cell's class.
+ *  One drag across the cells covers them: the first cell under the finger is one end, the last the other, whichever way the finger
+ *  went. Two taps do the same without a drag: a tap makes a one-cell span, a second tap on another cell closes it (a third starts over).
+ *  A cell that is `blocked` (disabled) is never covered: the run stops before it, so a span never jumps a day that cannot be picked.
+ *  Controlled like an input: `span` + `onSpanChange`, or `defaultSpan`; while the finger is down the cells show the live run and the
+ *  app is asked once, when it lifts. A pointer the browser takes away (the box scrolled instead) covers nothing. */
+export function useSpan({ span, defaultSpan, onSpanChange, blocked }) {
+    const [held, request] = useControlled(span, defaultSpan ?? null, onSpanChange);
+    const [live, setLive] = useState(null);
+    const drag = useRef(null);
+    // the farthest cell toward `to` the run from `from` reaches before a blocked cell
+    const reach = (from, to) => {
+        const step = to < from ? -1 : 1;
+        let at = from;
+        while (at !== to && !blocked(at + step))
+            at += step;
+        return at;
+    };
+    const cellAt = (box, x, y) => {
+        const cell = document.elementFromPoint(x, y)?.closest('[data-span]');
+        return cell && box.contains(cell) ? Number(cell.dataset.span) : null;
+    };
+    // a tap on `i` (a finger that did not move, or a key on the cell): the second end of a one-cell span, else a new one-cell span
+    const tap = (i) => {
+        const one = held && held[0] === held[1] ? held[0] : null;
+        request(one !== null && one !== i ? sorted(one, reach(one, i)) : [i, i]);
+    };
+    const onPointerDown = (e) => {
+        const cell = e.target.closest('[data-span]');
+        if (!cell || !e.currentTarget.contains(cell))
+            return;
+        const i = Number(cell.dataset.span);
+        if (blocked(i))
+            return;
+        e.currentTarget.setPointerCapture(e.pointerId);
+        drag.current = { from: i, to: i, moved: false };
+        setLive([i, i]);
+    };
+    const onPointerMove = (e) => {
+        const d = drag.current;
+        if (!d)
+            return;
+        const i = cellAt(e.currentTarget, e.clientX, e.clientY);
+        if (i === null || i === d.to)
+            return;
+        d.moved = true;
+        d.to = reach(d.from, i);
+        setLive(sorted(d.from, d.to));
+    };
+    const onPointerUp = () => {
+        const d = drag.current;
+        if (!d)
+            return;
+        drag.current = null;
+        setLive(null);
+        if (d.moved)
+            request(sorted(d.from, d.to));
+        else
+            tap(d.from);
+    };
+    const onPointerCancel = () => { drag.current = null; setLive(null); };
+    const shown = live ?? held ?? null;
+    const at = (i) => {
+        if (!shown)
+            return undefined;
+        if (shown[0] === shown[1])
+            return i === shown[0] ? 'one' : undefined;
+        return i === shown[0] ? 'start' : i === shown[1] ? 'end' : i > shown[0] && i < shown[1] ? 'in' : undefined;
+    };
+    return { span: shown, at, tap, box: { onPointerDown, onPointerMove, onPointerUp, onPointerCancel } };
+}
+/** the same span by the holder's keys (CalendarWeeks, HourGrid): useSpan's `span`, `defaultSpan` and `onSpanChange` from a `[key, key]` span, the ask handed back in keys */
+export function spanByKey(keys, span, defaultSpan, onSpanChange) {
+    const of = (s) => (s ? [keys.indexOf(s[0]), keys.indexOf(s[1])] : s);
+    return { span: of(span), defaultSpan: of(defaultSpan) ?? undefined, onSpanChange: onSpanChange && ((s) => onSpanChange([keys[s[0]], keys[s[1]]])) };
+}

package/dist/index.d.ts

@@ -53,6 +53,8 @@ export * from './choice/Check.js';
 export * from './choice/DayStrip.js';
 export * from './choice/Calendar.js';
 export * from './choice/CalendarWeeks.js';
+export * from './choice/HourGrid.js';
+export type { Span, SpanAt } from './choice/span.js';
 export * from './choice/Mood.js';
 export * from './choice/Slider.js';
 export * from './numbers/Ring.js';

package/dist/index.js

@@ -57,6 +57,7 @@ export * from './choice/Check.js';
 export * from './choice/DayStrip.js';
 export * from './choice/Calendar.js';
 export * from './choice/CalendarWeeks.js';
+export * from './choice/HourGrid.js';
 export * from './choice/Mood.js';
 export * from './choice/Slider.js';
 export * from './numbers/Ring.js';

package/dist/journey/JourneyBadge.d.ts

@@ -8,7 +8,8 @@ export interface JourneyBadgeProps extends ComponentProps<'span'> {
     sub?: ReactNode;
     /** no fill: a date box beside a title (Jun / 18) */
     plain?: boolean;
-    /** pinned to a CardMedia's corner (rating, price) */
+    /** pinned to a CardMedia's corner (rating, price, a distance). On a CardMedia: the paper (`--card-1-bg`), its corner concentric with the media's;
+     *  a theme's `--tile-badge-bg` / `--tile-badge-radius` still win. Ruled (Lh 2026-10-21) */
     corner?: boolean;
     /** a date in a card's head: as tall as the title block beside it, no taller — two lines beside a one-line title (day over number · month),
      *  three beside a two-line title (day · number · month). Write it as the head's last child, after the title block */

package/dist/lists/Kv.d.ts

@@ -15,9 +15,11 @@ export interface KvRowProps extends ComponentProps<'div'> {
 /** KvRow — one key · value line (48px tall); the value may hold a Chip, an Avatar, an Icon. */
 export declare function KvRow({ label, className, children, ...rest }: KvRowProps): import("react").JSX.Element;
 export interface KvGridProps extends ComponentProps<'div'> {
+    /** the one number in the middle of the room it stands in (a turning card's back, a Centre): the grid takes its holder's height and stands its cells in the middle of it, each cell's value and caption centred */
+    centre?: boolean;
 }
-/** KvGrid — value-over-label cells split by a rule (Sex | Weight); children are KVCells. */
-export declare function KvGrid({ className, ...rest }: KvGridProps): import("react").JSX.Element;
+/** KvGrid — value-over-label cells split by a rule (Sex | Weight); children are KVCells. `centre`: one cell at the middle of a card's back (a code the member copies). */
+export declare function KvGrid({ centre, className, ...rest }: KvGridProps): import("react").JSX.Element;
 export interface KvCellProps extends ComponentProps<'div'> {
     /** an icon before the value */
     icon?: IconName;

package/dist/lists/Kv.js

@@ -9,9 +9,9 @@ export function Kv({ lined, className, ...rest }) {
 export function KvRow({ label, className, children, ...rest }) {
     return (_jsxs("div", { className: cx('kv__row', className), ...rest, children: [_jsx("dt", { className: "kv__key", children: label }), _jsx("dd", { className: "kv__val", children: children })] }));
 }
-/** KvGrid — value-over-label cells split by a rule (Sex | Weight); children are KVCells. */
-export function KvGrid({ className, ...rest }) {
-    return _jsx("div", { className: cx('kv-grid', className), ...rest });
+/** KvGrid — value-over-label cells split by a rule (Sex | Weight); children are KVCells. `centre`: one cell at the middle of a card's back (a code the member copies). */
+export function KvGrid({ centre, className, ...rest }) {
+    return _jsx("div", { className: cx('kv-grid', centre && 'kv-grid--centre', className), ...rest });
 }
 /** KvCell — an icon, a big value, a caption label. */
 export function KvCell({ icon, value, label, className, ...rest }) {

package/docs/reference.md

@@ -608,7 +608,7 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
   control the member fills in or picks stands on a sheet: a `Sheet`'s
   `Body`, a `SheetStep`, or a stack sheet. That is `Field`, `Composer`
   and `ComposerArea`, `Pin`, `Dropdown`, `Slider`, `Toggle`, `Check`,
-  `ChipPick`, `Calendar`, `DayStrip` and `Day`, `Picker`, `Mood`,
+  `ChipPick`, `Calendar`, `CalendarWeeks`, `HourGrid`, `DayStrip` and `Day`, `Picker`, `Mood`,
   `AvatarPick`, `FileBtn`, `AddRow`, `MapPick`, a `Tile pick` and a
   `Tile upload`. A card is for reading and pressing buttons only; never put
   a form, or one control of it, in a card. `cardds check` rule

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.107",
+  "version": "0.7.108",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",