@oxy.so/bloom 2.11.0 → 2.12.0

package/src/app-shell/types.ts

@@ -32,8 +32,14 @@ export type AppShellDrawer = 'overlay' | 'reveal';
  * - `focus` — a single centred column of `contentWidth` and NO nav: sign-in,
  *   onboarding, a reader. It keeps the header, `topBar`, `bottomBar` and
  *   `floatingAction` slots, so a sign-up flow still gets its footer CTA.
+ * - `canvas` — the content is the SCREEN: one edge-to-edge area with no reading
+ *   column, no max width and no padding, exactly one viewport tall, and the
+ *   chrome floats over it. A map, a board, an editor, a photo viewer. Each
+ *   region keeps its own inset (the nav is still a card with a gutter around
+ *   it) so only the canvas runs to the edge. Like `split`, it never scrolls the
+ *   document — the canvas owns its own panning and zooming.
  */
-export type AppShellVariant = 'dashboard' | 'feed' | 'split' | 'focus';
+export type AppShellVariant = 'dashboard' | 'feed' | 'split' | 'focus' | 'canvas';
 
 /** Which single pane a `split` shell shows below `splitFrom`. */
 export type AppShellPane = 'list' | 'detail' | 'info';
@@ -108,7 +114,11 @@ export interface AppShellProps {
   asideWidth?: number;
   /** The breakpoint the aside sits beside the content from. Defaults to `xl` (1280). */
   asideFrom?: AppShellBreakpoint;
-  /** Below `asideFrom`: `stack` (default) renders it after the content, `hidden` drops it. */
+  /**
+   * Below `asideFrom`: `stack` (default) renders it after the content, `hidden`
+   * drops it. `canvas` always drops it — the screen is the canvas, so there is
+   * no column underneath to stack into.
+   */
   asideCollapse?: 'stack' | 'hidden';
   children?: ReactNode;
   /** The content column's max width. Defaults to 1300. */

package/src/content-panel/ContentPanel.tsx

@@ -71,6 +71,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   children,
   framed,
   framedFrom = 768,
+  fill = false,
   surfaceClassName,
   surfaceStyle,
   surfaceColor,
@@ -97,7 +98,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
       : framed
         ? 'flex-1 overflow-hidden rounded-radius-28 border border-border'
         : 'flex-1';
-  const surfaceClass = [surfaceBase, surfaceClassName ?? 'bg-card'].join(' ');
+  const surfaceClass = [surfaceBase, fill ? 'min-h-0' : '', surfaceClassName ?? 'bg-card'].filter(Boolean).join(' ');
   // Native has no overlays: the surface itself carries the edge. `none` drops
   // both, `border` keeps the class-drawn hairline, `elevated` adds the lift.
   const chromeStyle =
@@ -106,7 +107,12 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
       : shadow || panelChrome
         ? { boxShadow: shadow ?? panelChrome?.shadow }
         : null;
-  const contentClass = ['flex-1', contentClassName].filter(Boolean).join(' ');
+  // `fill` is the panel's own height contract, and on native it is already
+  // met: both boxes are `flex: 1`, so in a bounded parent the panel reaches the
+  // bottom and a list inside it scrolls within it. What the prop adds here is
+  // `min-h-0`, so a tall child cannot push the panel past the box it was given
+  // — the same automatic-minimum-size trap as on web.
+  const contentClass = ['flex-1', fill ? 'min-h-0' : '', contentClassName].filter(Boolean).join(' ');
 
   return (
     <ContentPanelNestingContext.Provider value={true}>

package/src/content-panel/ContentPanel.web.tsx

@@ -148,6 +148,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   children,
   framed,
   framedFrom = 768,
+  fill = false,
   surfaceClassName,
   surfaceStyle,
   surfaceColor,
@@ -157,8 +158,8 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   chrome = 'elevated',
   shadow,
   maskColor,
-  overlaySizing = 'panel',
-  overlayTopOffset,
+  overlaySizing = 'viewport',
+  overlayInset,
 }) => {
   // Dev-only invariant — must run unconditionally (before deriving any
   // mode-specific branch) so the hook order stays stable (rules of hooks).
@@ -194,6 +195,15 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
     : framed
       ? 'flex-1 rounded-radius-28 web:overflow-x-clip'
       : 'flex-1';
+  // `fill`: the panel takes the height its parent gives it and the CONTENT
+  // scrolls inside. `min-h-0` on both boxes is the whole trick — a flex child's
+  // automatic minimum size is its content, so without it the panel grows past
+  // the box it was told to fit and the scroller never gets a height to scroll
+  // against. The overflow goes on the content wrapper, never the surface: the
+  // surface is what the frame and the mask are drawn to, and a scrolling
+  // surface would scroll the edge with it.
+  const fillSurface = fill ? 'min-h-0' : '';
+  const fillContent = fill ? 'min-h-0 web:[overflow-y:auto]' : '';
   // `overlaySizing="panel"`: the surface becomes a single-cell CSS Grid so the
   // overlays and the content wrapper below can all be placed in that ONE cell
   // (`web:[grid-area:1/1]`) and each fill it exactly — `minmax(0,1fr)` (not
@@ -204,32 +214,36 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   const gridStackClass = boundToPanel
     ? 'web:grid web:[grid-template-columns:minmax(0,1fr)] web:[grid-template-rows:minmax(0,1fr)]'
     : '';
-  const surfaceClass = [surfaceBase, gridStackClass, surfaceClassName ?? 'bg-card'].filter(Boolean).join(' ');
-  const contentClass = [contentBase, boundToPanel ? 'web:[grid-area:1/1]' : '', contentClassName]
+  const surfaceClass = [surfaceBase, fillSurface, gridStackClass, surfaceClassName ?? 'bg-card'].filter(Boolean).join(' ');
+  const contentClass = [contentBase, fillContent, boundToPanel ? 'web:[grid-area:1/1]' : '', contentClassName]
     .filter(Boolean)
     .join(' ');
 
-  // `overlayTopOffset`: the viewport-mode overlays are sized/positioned from
-  // literal Tailwind classes (`top-2`, `h-[calc(100dvh-16px)]`, a matching
-  // negative `margin-bottom`) because those values are constants known at
-  // build time. An offset is a runtime number (a consumer's measured header
-  // height), which a Tailwind arbitrary class can't express — content-scanning
-  // needs the literal class string in source, not a value computed later — so
-  // this shifts the same three properties via inline `style` instead, which
-  // has no such constraint. No-op in `panel` mode (already starts at the
-  // panel's own box) and when unset (0/undefined) — the className values are
-  // left standing on their own in both of those cases.
+  // The viewport-mode overlays are sized and positioned from literal Tailwind
+  // classes (`top-2`, `h-[calc(100dvh-16px)]`, the matching negative
+  // `margin-bottom`) because those values are constants known at build time.
+  // An INSET is a runtime number — a shell's gutter, a measured header — which
+  // a Tailwind arbitrary class cannot express (content-scanning needs the
+  // literal string in source, not a value computed later), so a non-default
+  // inset shifts the same three properties through inline `style` instead,
+  // which has no such constraint. The default (8/8) leaves the classes standing
+  // alone, and `panel` mode ignores the inset entirely — that mode already
+  // starts at the panel's own box.
+  //
   // RN's `ViewStyle.height`/`marginBottom` types only accept a number or a
-  // `${number}%` string (not an arbitrary CSS `calc()` string), because most
-  // of this type is shared with native, where `calc()` doesn't exist. This
-  // file is web-only, where it's a real, valid CSS value react-native-web
-  // passes straight through — the same reasoning `WebViewStyle`/`asViewStyle`
-  // document in OxyHQ/Mention's `types/webStyles.ts` for the identical need.
-  const topOffsetStyle = !boundToPanel && overlayTopOffset
+  // `${number}%` string, not an arbitrary CSS `calc()`, because most of that
+  // type is shared with native where `calc()` does not exist. This file is
+  // web-only, where it is a real value react-native-web passes straight
+  // through.
+  const insetTop = typeof overlayInset === 'number' ? overlayInset : (overlayInset?.top ?? PANEL_TOP_INSET);
+  const insetBottom =
+    typeof overlayInset === 'number' ? overlayInset : (overlayInset?.bottom ?? PANEL_BOTTOM_INSET);
+  const customInset = insetTop !== PANEL_TOP_INSET || insetBottom !== PANEL_BOTTOM_INSET;
+  const insetStyle = !boundToPanel && customInset
     ? ({
-        top: 8 + overlayTopOffset,
-        height: `calc(100dvh - ${16 + overlayTopOffset}px)`,
-        marginBottom: `calc(-100dvh + ${16 + overlayTopOffset}px)`,
+        top: insetTop,
+        height: `calc(100dvh - ${insetTop + insetBottom}px)`,
+        marginBottom: `calc(-100dvh + ${insetTop + insetBottom}px)`,
       } as unknown as ViewStyle)
     : undefined;
 
@@ -261,7 +275,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
                   ? `web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-radius-28 ${bp.overlayHidden} web:[margin-bottom:calc(-100dvh+16px)] web:[clip-path:inset(-12px)]`
                   : 'web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-radius-28 web:[margin-bottom:calc(-100dvh+16px)] web:[clip-path:inset(-12px)]'
             }
-            style={{ ...topOffsetStyle, boxShadow: `0 0 0 ${GUTTER_MASK_SPREAD}px ${maskColor ?? colors.background}` }}
+            style={{ ...insetStyle, boxShadow: `0 0 0 ${GUTTER_MASK_SPREAD}px ${maskColor ?? colors.background}` }}
           />
         )}
         {/* (2) Border-frame overlay — one continuous rounded border, above all.
@@ -274,7 +288,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
             // The shadow rides the SAME element as the hairline, so the lift and
             // the edge can never disagree about where the panel ends. It paints
             // outward, into the gutter the page background shows.
-            style={[topOffsetStyle, chrome === 'elevated' && (shadow || panelChrome)
+            style={[insetStyle, chrome === 'elevated' && (shadow || panelChrome)
                 ? { boxShadow: shadow ?? panelChrome?.shadow }
                 : null]}
             className={

package/src/content-panel/types.ts

@@ -52,6 +52,28 @@ export interface ContentPanelProps {
    * For an app that wants its own elevation without giving up the hairline.
    */
   shadow?: string;
+  /**
+   * The panel is the HEIGHT OF THE SPACE IT IS GIVEN, and its content scrolls
+   * inside it — instead of the panel growing with its content while the page
+   * scrolls underneath.
+   *
+   * This is what makes a framed column read as a panel: it reaches the bottom
+   * of the screen and closes there, the way the rail beside it does. Without
+   * it, a feed taller than the window gives a panel whose top edge you see and
+   * whose bottom edge is somewhere past the fold — an open-ended column, not a
+   * surface.
+   *
+   * It needs a parent that BOUNDS it (a flex column with a real height): an
+   * `AppShell` with `scroll="fixed"` or `scroll="container"`, or any screen
+   * that is `flex: 1`. In a document-scrolled page there is no height to fill
+   * and the panel keeps growing with its content — that page wants
+   * `scroll="document"`, not this prop.
+   *
+   * On web the content wrapper becomes the scroller. On native the panel and
+   * its content are already `flex: 1`, so a `FlatList`/`ScrollView` inside
+   * fills the panel and scrolls within it.
+   */
+  fill?: boolean;
   /** Override the surface background utility (defaults to `bg-card`). */
   surfaceClassName?: string;
   surfaceStyle?: StyleProp<ViewStyle>;
@@ -89,52 +111,38 @@ export interface ContentPanelProps {
    */
   maskColor?: string;
   /**
-   * How the WEB overlays (bleed-mask, border-frame) size themselves. No-op on
-   * native (there are no overlays to size).
-   * - `'viewport'` (DEFAULT) — sized to the dynamic viewport height (`100dvh`)
-   *   and `position: sticky`-pinned, so they read as a constant frame around
-   *   the visible slice of a panel whose own DOM height can exceed one screen
-   *   — the document-scroll case (e.g. a feed whose page grows with content).
-   *   Requires the panel to sit in a document that actually scrolls; see
-   *   `ContentPanel.web.tsx`'s doc comment.
-   * - `'panel'` — sized to the panel's own real box via CSS Grid layer-
-   *   stacking (the overlays and the content wrapper all occupy the same
-   *   grid cell) instead of viewport math. The right mode for a consumer
-   *   whose own shell already bounds the panel's height (no document
-   *   scroll — a fixed app shell with its own internal scroll containers),
-   *   where anything the consumer places outside the panel (e.g. a header
-   *   above it) must never be overlapped by an overlay sized to the whole
-   *   viewport.
-   */
-  /**
-   * DEFAULT `'panel'`. The edge describes the panel's OWN box, so it scrolls
-   * with the content like any other border: on a page taller than the screen
-   * you see the two side edges while scrolling and the rounded corners at the
-   * ends, which is what a long framed column looks like.
+   * How the WEB overlays (the bleed-mask and the border frame) size themselves.
+   * No-op on native (there are no overlays to size).
    *
-   * `'viewport'` is the older behaviour: the frame is a screen-tall sticky
-   * rectangle, so a rounded top and bottom edge follow the viewport down the
-   * page. It reads as the panel breathing — the frame holds still while the
-   * content moves inside it, and it jumps 8px on the first scroll — which is
-   * why it is no longer the default. It remains for a consumer that wants that
-   * constant frame.
+   * - `'viewport'` (DEFAULT) — the frame is a SCREEN-TALL sticky rectangle:
+   *   `100dvh` minus the insets, pinned at `overlayInset`. The panel's own box
+   *   grows with its content and the document scrolls it, while the edge stays
+   *   where the screen is — so the panel reads as a surface that occupies the
+   *   window from top to bottom and the content moves inside it. This is the
+   *   mode for a page that scrolls the document.
+   * - `'panel'` — the overlays are the panel's OWN box, through CSS Grid
+   *   layer-stacking (the overlays and the content wrapper share one grid
+   *   cell). The right mode when the panel's box already IS the visible area
+   *   (`fill`, inside a shell that bounds it) or when something the consumer
+   *   placed outside the panel — a header above it — must never be painted
+   *   over by an overlay sized to the whole viewport.
    */
   overlaySizing?: 'viewport' | 'panel';
   /**
-   * Pixels of REAL, persistent chrome the consumer has placed above the panel
-   * — outside it, in normal document flow — that the viewport-mode overlays
-   * (`overlaySizing="viewport"`, the default) do not otherwise know about.
-   * No-op when `overlaySizing="panel"` (that mode already starts at the
-   * panel's own box, wherever that is) and on native (no overlays there).
+   * The gap between the VIEWPORT's edge and the sticky frame, in `'viewport'`
+   * mode. Default 8.
+   *
+   * **It must equal the distance from the top of the screen to the panel's own
+   * top edge.** Sticky positioning leaves an element at its static position
+   * until scrolling would push it past the inset — so a panel that starts 16px
+   * down the page with an 8px inset draws its frame at 16, then SNAPS it to 8
+   * on the first scroll. That 8px jump is the whole bug, and it reads as the
+   * panel breathing. A shell passes its own gutter here.
    *
-   * The overlays are sized/positioned off the VIEWPORT (`top: 8px`,
-   * `height: calc(100dvh - 16px)`) on the assumption that the panel begins
-   * near the true top of the screen. A consumer with its own sticky chrome
-   * above the panel (a header, say, kept sticky-pinned the same way) shifts
-   * where the panel visually starts without moving the panel's own DOM
-   * position, so the overlays would still read from viewport 0 and paint
-   * over that chrome. This shifts their `top` down and shrinks their height
-   * by the same amount, so they begin exactly where the panel visually does.
+   * Takes a pair when the top and the bottom differ — persistent chrome above
+   * the panel (a sticky header the consumer keeps outside it) shifts where the
+   * panel visually starts without moving its DOM position, so the frame has to
+   * start lower without also ending higher.
    */
-  overlayTopOffset?: number;
+  overlayInset?: number | { top: number; bottom: number };
 }

package/src/date-picker/TimeField.tsx

@@ -0,0 +1,162 @@
+import React, { memo, useEffect, useMemo, useState } from 'react';
+import { Platform, TextInput, type TextStyle } from 'react-native';
+
+import { MENU_FONT_FAMILY } from '../floating/menu-type';
+import { DISABLED_OPACITY } from '../styles/tokens';
+import type { WebCssStyle } from '../styles/web-view-style';
+import { useTheme } from '../theme/use-theme';
+import { TYPE_SCALE } from '../typography';
+import { resolveCalendarPalette } from './palette';
+import { formatTime, parseTime, snapTime, stepTime } from './time';
+import type { TimeFieldProps, TimeFieldSize } from './types';
+
+/**
+ * A time of day, typed. `DatePicker` is the day; this is the hour and minute,
+ * and it is a FIELD rather than a fourth popover — a viewing at 18:30 is four
+ * keystrokes, and a popover is the wrong instrument for four keystrokes.
+ *
+ *              width   height   text             step arrows
+ *   small      96      32       body-2-medium    yes
+ *   medium     104     38       body-medium      yes
+ *
+ * Geometry, palette and focus behaviour are `DateChipInput`'s — the
+ * `DD/MM/YYYY` chip inside the pickers — so a date and a time typed beside each
+ * other line up: 1px `chipBorder` darkening to `chipBorderFocused` on focus
+ * (the border IS the focus indicator, `outline-none`), radius 10, shadow-xs,
+ * the panel fill.
+ *
+ * It keeps its own DRAFT while typing, so the text is not reformatted under the
+ * cursor, and commits on blur or submit; Escape reverts. A draft that does not
+ * parse reverts too, rather than reporting an error the field has no room to
+ * draw — `parseTime` is forgiving enough (`9`, `930`, `9.30`, `9pm`, `21:30`)
+ * that the remaining failures really are not times.
+ *
+ * ArrowUp / ArrowDown move by `step` and commit immediately, clamped at `min`
+ * and `max` rather than wrapping. They are a convenience on a text box, not a
+ * `spinbutton`: the control is a text field, it announces itself as one, and
+ * every value it can reach can also be typed. Its NAME is
+ * `accessibilityLabel` — required, because `"--:--"` names nothing.
+ *
+ * The VALUE is always 24h `"HH:mm"`, whatever `hourFormat` draws, so it drops
+ * straight into `MeetingScheduler`'s `timeSlots` and needs no locale from the
+ * caller.
+ */
+
+const SIZE_CONFIG: Record<TimeFieldSize, { width: number; height: number; type: 'body-medium' | 'body-2-medium' }> = {
+  small: { width: 96, height: 32, type: 'body-2-medium' },
+  medium: { width: 104, height: 38, type: 'body-medium' },
+};
+
+/** `transition-colors duration-100 ease-out` on the border. Web only. */
+const FIELD_TRANSITION: WebCssStyle | null =
+  Platform.OS === 'web'
+    ? { transitionProperty: 'border-color', transitionDuration: '100ms', transitionTimingFunction: 'ease-out' }
+    : null;
+
+function TimeFieldComponent({
+  value,
+  onChange,
+  min,
+  max,
+  step = 1,
+  hourFormat = '24h',
+  size = 'medium',
+  disabled = false,
+  accessibilityLabel,
+  placeholder,
+  width,
+  style,
+  testID,
+}: TimeFieldProps) {
+  const theme = useTheme();
+  const palette = useMemo(() => resolveCalendarPalette(theme), [theme]);
+  const config = SIZE_CONFIG[size];
+
+  const shown = value ? formatTime(value, hourFormat) : '';
+  const [text, setText] = useState(shown);
+  const [focused, setFocused] = useState(false);
+
+  // The committed value is the source of truth; a change from outside (or a
+  // format flip) rewrites the draft.
+  useEffect(() => {
+    setText(shown);
+  }, [shown]);
+
+  const commit = (draft: string) => {
+    if (draft.trim() === '') {
+      setText('');
+      if (value !== null) onChange(null);
+      return;
+    }
+    const parsed = parseTime(draft, hourFormat);
+    const next = parsed ? snapTime(parsed, { step, min, max }) : null;
+    if (!next) {
+      setText(shown);
+      return;
+    }
+    setText(formatTime(next, hourFormat));
+    if (next !== value) onChange(next);
+  };
+
+  const nudge = (direction: 1 | -1) => {
+    const next = stepTime(value, direction, { step, min, max });
+    if (!next) return;
+    setText(formatTime(next, hourFormat));
+    if (next !== value) onChange(next);
+  };
+
+  const fieldStyle: TextStyle = {
+    width: width ?? config.width,
+    height: config.height,
+    paddingLeft: 8,
+    paddingRight: 8,
+    borderWidth: 1,
+    borderRadius: 10,
+    borderColor: focused ? palette.chipBorderFocused : palette.chipBorder,
+    backgroundColor: palette.panel,
+    boxShadow: palette.shadowXs,
+    color: disabled ? palette.disabledText : palette.text,
+    opacity: disabled ? DISABLED_OPACITY : 1,
+    // A `TextInput` inherits no face.
+    ...TYPE_SCALE[config.type],
+    ...MENU_FONT_FAMILY,
+    // `outline-none`: the border change is the focus indicator.
+    outlineWidth: 0,
+  };
+
+  return (
+    <TextInput
+      value={text}
+      editable={!disabled}
+      onChangeText={setText}
+      onFocus={() => setFocused(true)}
+      onBlur={() => {
+        setFocused(false);
+        commit(text);
+      }}
+      onSubmitEditing={() => commit(text)}
+      onKeyPress={(event) => {
+        const key = event.nativeEvent.key;
+        if (key === 'Escape') {
+          setText(shown);
+        } else if (key === 'ArrowUp') {
+          (event as unknown as { preventDefault?: () => void }).preventDefault?.();
+          nudge(1);
+        } else if (key === 'ArrowDown') {
+          (event as unknown as { preventDefault?: () => void }).preventDefault?.();
+          nudge(-1);
+        }
+      }}
+      placeholder={placeholder ?? (hourFormat === '12h' ? '--:-- --' : '--:--')}
+      placeholderTextColor={palette.secondaryText}
+      inputMode={hourFormat === '12h' ? 'text' : 'numeric'}
+      accessibilityLabel={accessibilityLabel}
+      aria-disabled={disabled || undefined}
+      style={[FIELD_TRANSITION, fieldStyle, style]}
+      testID={testID}
+    />
+  );
+}
+
+export const TimeField = memo(TimeFieldComponent);
+TimeField.displayName = 'TimeField';

package/src/date-picker/index.ts

@@ -2,6 +2,9 @@ export { Calendar, RangeCalendar } from './Calendar';
 export { DatePicker } from './DatePicker';
 export { DateRangePicker } from './DateRangePicker';
 export { MeetingScheduler } from './MeetingScheduler';
+export { TimeField } from './TimeField';
+// `time.ts`'s pure helpers stay internal, as `calendar-grid.ts`'s already do:
+// `formatTime`/`parseTime` are names the root barrel cannot afford.
 
 export type {
   CalendarConstraintProps,
@@ -9,6 +12,7 @@ export type {
   DatePickerProps,
   DateRange,
   DateRangePickerProps,
+  HourFormat,
   MeetingSchedulerDetails,
   MeetingSchedulerHost,
   MeetingSchedulerHourFormat,
@@ -16,5 +20,7 @@ export type {
   MeetingSchedulerProps,
   MeetingSchedulerValue,
   RangeCalendarProps,
+  TimeFieldProps,
+  TimeFieldSize,
   WeekStart,
 } from './types';

package/src/date-picker/time.ts

@@ -0,0 +1,158 @@
+import type { HourFormat } from './types';
+
+/**
+ * Time of day as the family already spells it: a 24-hour `"HH:mm"` string.
+ * `MeetingScheduler`'s `timeSlots` and `MeetingSchedulerValue.time` are the same
+ * shape, so a `TimeField` value drops straight into one.
+ *
+ * Everything here is pure, exported, and where the parsing rules live — a field
+ * that keeps its own draft cannot be tested through the DOM for every spelling
+ * somebody might type.
+ */
+
+/** Minutes since midnight, `0..1439`. */
+export type Minutes = number;
+
+const HH_MM = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+
+/** `"14:30"` → 870. `null` for anything that is not a 24h `HH:mm`. */
+export function toMinutes(value: string): Minutes | null {
+  const match = HH_MM.exec(value.trim());
+  if (!match) return null;
+  return Number(match[1]) * 60 + Number(match[2]);
+}
+
+/** 870 → `"14:30"`. Wraps within the day, so 1440 is `"00:00"`. */
+export function fromMinutes(minutes: Minutes): string {
+  const wrapped = ((Math.round(minutes) % 1440) + 1440) % 1440;
+  const h = Math.floor(wrapped / 60);
+  const m = wrapped % 60;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+}
+
+/** `"14:30"` → `"14:30"` (24h) or `"2:30 PM"` (12h). */
+export function formatTime(value: string, hourFormat: HourFormat): string {
+  const minutes = toMinutes(value);
+  if (minutes == null) return value;
+  if (hourFormat === '24h') return fromMinutes(minutes);
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
+  const period = h < 12 ? 'AM' : 'PM';
+  const hour12 = h % 12 === 0 ? 12 : h % 12;
+  return `${hour12}:${String(m).padStart(2, '0')} ${period}`;
+}
+
+/**
+ * What somebody typed → `"HH:mm"`, or `null` when it is not a time.
+ *
+ * Deliberately forgiving, because a field that only accepts what it printed is
+ * a field people fight: `9`, `930`, `9.30`, `9:3`, `0930`, `9 30`, `9pm`,
+ * `9:30 p.m.` and `21:30` all parse. A bare number under 24 is an HOUR (`9` is
+ * 09:00), four digits are `HHMM` (`0930`); `AM`/`PM` decides the half of the
+ * day whatever `hourFormat` says, because somebody who typed `pm` means pm.
+ * Without a marker, 24h reads the hour as given and 12h keeps `1..12` in the
+ * morning — the value is still `"HH:mm"`, so a caller never has to know which.
+ */
+export function parseTime(text: string, hourFormat: HourFormat = '24h'): string | null {
+  const raw = text.trim().toLowerCase();
+  if (raw === '') return null;
+  const period = /(^|[^a-z])(a\.?m\.?|p\.?m\.?)\s*$/.exec(raw);
+  const meridiem = period ? (period[2]!.startsWith('a') ? 'am' : 'pm') : null;
+  const digits = (meridiem ? raw.slice(0, period!.index + period![1]!.length) : raw).trim();
+
+  let hour: number;
+  let minute: number;
+  const separated = /^(\d{1,2})\s*[:.\s]\s*(\d{1,2})$/.exec(digits);
+  if (separated) {
+    hour = Number(separated[1]);
+    minute = Number(separated[2]!.padEnd(2, '0'));
+  } else if (/^\d{3,4}$/.test(digits)) {
+    hour = Number(digits.slice(0, digits.length - 2));
+    minute = Number(digits.slice(-2));
+  } else if (/^\d{1,2}$/.test(digits)) {
+    hour = Number(digits);
+    minute = 0;
+  } else {
+    return null;
+  }
+
+  if (minute > 59) return null;
+  if (meridiem) {
+    if (hour < 1 || hour > 12) return null;
+    hour = meridiem === 'pm' ? (hour % 12) + 12 : hour % 12;
+  } else if (hour > 23) {
+    return null;
+  }
+  return fromMinutes(hour * 60 + minute);
+}
+
+/**
+ * The nearest multiple of `step` minutes (or the next one up/down, per
+ * `round`), at or after `min` and at or before `max`. `step` counts from
+ * MIDNIGHT, so 15 gives :00 :15 :30 :45 whatever the bounds are — a step
+ * measured from `min` would put the round times off the grid the moment a shop
+ * opened at 09:10. Never crosses the end of the day: 23:59 rounded up to a
+ * 30-minute grid stays inside it rather than wrapping to the other end.
+ */
+export function snapTime(
+  value: string,
+  {
+    step = 1,
+    min,
+    max,
+    round = 'nearest',
+  }: { step?: number; min?: string; max?: string; round?: 'nearest' | 'up' | 'down' } = {},
+): string | null {
+  const minutes = toMinutes(value);
+  if (minutes == null) return null;
+  const size = Math.max(1, Math.round(step));
+  const scaled = minutes / size;
+  let snapped =
+    (round === 'up' ? Math.ceil(scaled) : round === 'down' ? Math.floor(scaled) : Math.round(scaled)) *
+    size;
+  const low = min ? toMinutes(min) : null;
+  const high = max ? toMinutes(max) : null;
+  if (low != null && high != null && low > high) return null;
+  if (low != null && snapped < low) snapped = low;
+  if (high != null && snapped > high) snapped = high;
+  // Never past the end of the day: rounding 23:59 up to a 30-minute grid lands
+  // on 24:00, which `fromMinutes` would wrap to midnight — the other end.
+  if (snapped > 1439) snapped = high ?? 1439;
+  if (snapped < 0) snapped = low ?? 0;
+  return fromMinutes(snapped);
+}
+
+/**
+ * One arrow press: `direction * step` minutes from `value`, or the first time
+ * inside the bounds when there is no value yet. Clamps at the bounds rather
+ * than wrapping — a wrap past `max` back to `min` reads as the field refusing
+ * the key.
+ */
+export function stepTime(
+  value: string | null,
+  direction: 1 | -1,
+  { step = 1, min, max }: { step?: number; min?: string; max?: string } = {},
+): string | null {
+  const size = Math.max(1, Math.round(step));
+  const low = min ? toMinutes(min) : null;
+  const high = max ? toMinutes(max) : null;
+  if (low != null && high != null && low > high) return null;
+  const current = value ? toMinutes(value) : null;
+  if (current == null) {
+    // Into the range, not past it: up from the earliest allowed time rounds UP
+    // onto the grid, down from the latest rounds DOWN.
+    const start = direction === 1 ? (low ?? 0) : (high ?? 1439);
+    return snapTime(fromMinutes(start), {
+      step: size,
+      min,
+      max,
+      round: direction === 1 ? 'up' : 'down',
+    });
+  }
+  let next = current + direction * size;
+  if (low != null && next < low) next = low;
+  if (high != null && next > high) next = high;
+  if (next < 0) next = 0;
+  if (next > 1439) next = 1439;
+  return fromMinutes(next);
+}