@oxyhq/bloom 1.0.6 → 1.2.0

package/src/level-picker/LevelPicker.web.tsx

@@ -0,0 +1,374 @@
+/**
+ * `LevelPicker` — WEB. The same control as `LevelPicker.tsx`, built out of the
+ * three things a browser has and React Native does not, which is what makes
+ * this a fork rather than a branch:
+ *
+ *  1. **Pointer capture.** `setPointerCapture` keeps the drag on the rail once
+ *     the pointer leaves it, so a user can slam left or right past the end of
+ *     the track and still be steering. Nothing in the RN responder system is
+ *     equivalent on the platform where a pointer exists at all.
+ *  2. **`inert` and a real focus model.** A collapsed region is `inert` — its
+ *     rows leave the tab order and the accessibility tree together — and the
+ *     rail is a focusable `role="slider"` with arrow, Home and End keys, which
+ *     an `adjustable` on native exposes as increment/decrement ACTIONS instead.
+ *  3. **`calc()`.** A stop's position is a percentage of the rail plus a pixel
+ *     inset, which CSS resolves per frame; the native fork has to measure the
+ *     rail with `onLayout` and multiply. Both read {@link levelStopPosition}, so
+ *     the formula is one thing rendered two ways rather than two formulas.
+ *
+ * The rows themselves are NOT forked: the summary row is `floating/shared`'s
+ * `MenuRowShell`, the same one the sub-menu triggers in the details region are
+ * built from, so the disclosure and the rows it reveals cannot disagree about a
+ * row's inset, highlight or height.
+ */
+import React, { useCallback, useRef, useState, type PointerEvent } from 'react';
+
+import { PANEL_MOTION_DURATION, PANEL_MOTION_EASING, ROW_ICON_SIZE } from '../floating/constants';
+import { cx, MenuRowChevron, MenuRowShell, SUB_TRIGGER_CLASS } from '../floating/shared';
+import { useControllableState } from '../hooks/use-controllable-state';
+import { useInteractionState } from '../hooks/use-interaction-state';
+import { ChevronRight_Stroke2_Corner0_Rounded as ChevronRightIcon } from '../icons/Chevron';
+import { flattenWebStyle } from '../styles/flatten-web-style';
+import type { WebCssStyle } from '../styles/web-view-style';
+import { useTheme } from '../theme/use-theme';
+import {
+  LEVEL_CAPTION_CLASS,
+  LEVEL_FILL_CLASS,
+  LEVEL_ROW_INSET,
+  LEVEL_SEPARATOR_CLASS,
+  LEVEL_SLIDER_ROW_HEIGHT,
+  LEVEL_STOP_CLASS,
+  LEVEL_STOP_REACHED_CLASS,
+  LEVEL_STOP_SIZE,
+  LEVEL_THUMB_CLASS,
+  LEVEL_THUMB_SIZE,
+  LEVEL_TRACK_CLASS,
+  LEVEL_TRACK_HEIGHT,
+  levelFromOffset,
+  levelStopPosition,
+} from './constants';
+import type { LevelPickerProps } from './types';
+
+/**
+ * The menu's own motion, as CSS. `FloatingPanel` runs its enter and exit on the
+ * same duration and curve, so a picker changing shape inside a panel reads as
+ * one surface moving rather than two things animating at each other.
+ *
+ * Spelled inline from the constants rather than as `duration-200 ease-out`
+ * classes: a class would be a second copy of the number, free to drift from the
+ * one the panel uses.
+ */
+const MOTION = {
+  transitionDuration: `${PANEL_MOTION_DURATION}ms`,
+  transitionTimingFunction: `cubic-bezier(${PANEL_MOTION_EASING.join(', ')})`,
+} as const;
+
+/** The rail's own chrome — everything about it that is not a colour role. */
+const TRACK_CLASS =
+  'w-full touch-none cursor-pointer outline-none ' +
+  'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-popover';
+
+export function LevelPicker({
+  levels,
+  value,
+  onValueChange,
+  accessibilityLabel,
+  minLabel,
+  maxLabel,
+  detailsLabel = 'Details',
+  expanded,
+  defaultExpanded = false,
+  onExpandedChange,
+  children,
+  className,
+  style,
+  testID,
+}: LevelPickerProps) {
+  const theme = useTheme();
+  const [isExpanded, setExpanded] = useControllableState<boolean>({
+    value: expanded,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange,
+  });
+  const { state: pointerOver, onIn: enterPointer, onOut: leavePointer } = useInteractionState();
+  const { state: focused, onIn: focusTrack, onOut: blurTrack } = useInteractionState();
+  const [dragging, setDragging] = useState(false);
+  const [detailsHeight, setDetailsHeight] = useState(0);
+  const trackRef = useRef<HTMLDivElement | null>(null);
+
+  /** The slider is being WORKED — hovered, focused or dragged. */
+  const active = pointerOver || focused || dragging;
+
+  /**
+   * The details region's natural height, observed rather than read once: a
+   * sub-menu row inside it can change size after the reveal has already run,
+   * and a height measured only on mount would clip it.
+   *
+   * `ResizeObserver` is guarded because this fork also runs where there is no
+   * layout to observe — an SSR pass, and jsdom under jest. There the region
+   * falls back to its natural height (`maxHeight: undefined` below), which is
+   * the safe direction: unclipped rather than collapsed.
+   */
+  const measureDetails = useCallback((node: HTMLDivElement | null) => {
+    if (node === null) return;
+    const read = (): void => {
+      const next = node.offsetHeight;
+      setDetailsHeight((prev) => (Math.abs(prev - next) > 0.5 ? next : prev));
+    };
+    read();
+    if (typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(read);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  const commitPointer = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      const rect = trackRef.current?.getBoundingClientRect();
+      if (rect === undefined) return;
+      const next = levelFromOffset(event.clientX - rect.left, rect.width, levels.length);
+      if (next !== value) onValueChange(next);
+    },
+    [levels.length, onValueChange, value],
+  );
+
+  const step = useCallback(
+    (to: number) => {
+      const next = Math.max(0, Math.min(levels.length - 1, to));
+      if (next !== value) onValueChange(next);
+    },
+    [levels.length, onValueChange, value],
+  );
+
+  const onKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      switch (event.key) {
+        case 'ArrowRight':
+        case 'ArrowUp':
+          event.preventDefault();
+          step(value + 1);
+          break;
+        case 'ArrowLeft':
+        case 'ArrowDown':
+          event.preventDefault();
+          step(value - 1);
+          break;
+        case 'Home':
+          event.preventDefault();
+          step(0);
+          break;
+        case 'End':
+          event.preventDefault();
+          step(levels.length - 1);
+          break;
+        default:
+          break;
+      }
+    },
+    [levels.length, step, value],
+  );
+
+  /** A stop's centre: a share of the rail, plus the inset that keeps the knob on it. */
+  const positionOf = (index: number): string => {
+    const { percent, offset } = levelStopPosition(index, levels.length);
+    return `calc(${percent}% + ${offset}px)`;
+  };
+
+  const hasCaptions = minLabel !== undefined || maxLabel !== undefined;
+  /**
+   * The row's fade, on the ROW rather than on a wrapper around it: an inline
+   * style outranks a class on web whatever the order, so this is the one place
+   * the opacity can live without competing with `MenuRowShell`'s own chrome —
+   * and it is one fewer node between the caller's layout and the row.
+   *
+   * `pointerEvents` follows the POINTER, not `active`, and the difference is not
+   * a nicety. A rail keeps focus after it is clicked, so a row that stopped
+   * taking clicks whenever `active` was true would be unclickable for as long as
+   * the rail was focused — measured: the click falls through to the container,
+   * which blurs the rail, and only the SECOND click reaches the row. Fading a
+   * row the pointer is nowhere near is worth it; swallowing its click is not.
+   */
+  const pointerEngaged = pointerOver || dragging;
+  const summaryStyle: WebCssStyle = {
+    ...MOTION,
+    transitionProperty: 'opacity',
+    opacity: active ? 0 : 1,
+    pointerEvents: pointerEngaged ? 'none' : 'auto',
+  };
+  const childTestId = (part: string): string | undefined =>
+    testID === undefined ? undefined : `${testID}-${part}`;
+
+  return (
+    <div
+      className={cx('flex w-full flex-col', className)}
+      style={flattenWebStyle(style)}
+      data-testid={testID}>
+      {/* The rail, collapsing to nothing when the details take its place. */}
+      <div
+        inert={isExpanded}
+        aria-hidden={isExpanded}
+        className="overflow-hidden"
+        style={{
+          ...MOTION,
+          transitionProperty: 'max-height, opacity',
+          maxHeight: isExpanded ? 0 : LEVEL_SLIDER_ROW_HEIGHT,
+          opacity: isExpanded ? 0 : 1,
+        }}
+        data-testid={childTestId('slider')}>
+        <div
+          className="flex items-center"
+          style={{
+            height: LEVEL_SLIDER_ROW_HEIGHT,
+            paddingLeft: LEVEL_ROW_INSET,
+            paddingRight: LEVEL_ROW_INSET,
+          }}>
+          <div
+            ref={trackRef}
+            role="slider"
+            tabIndex={isExpanded ? -1 : 0}
+            aria-label={accessibilityLabel}
+            aria-valuemin={0}
+            aria-valuemax={levels.length - 1}
+            aria-valuenow={value}
+            aria-valuetext={levels[value]}
+            onPointerEnter={enterPointer}
+            onPointerLeave={() => {
+              if (!dragging) leavePointer();
+            }}
+            onPointerDown={(event) => {
+              event.currentTarget.setPointerCapture(event.pointerId);
+              setDragging(true);
+              enterPointer();
+              commitPointer(event);
+            }}
+            onPointerMove={(event) => {
+              if (dragging) commitPointer(event);
+            }}
+            onPointerUp={(event) => {
+              if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+                event.currentTarget.releasePointerCapture(event.pointerId);
+              }
+              setDragging(false);
+            }}
+            onPointerCancel={() => setDragging(false)}
+            onFocus={focusTrack}
+            onBlur={blurTrack}
+            onKeyDown={onKeyDown}
+            className={cx(LEVEL_TRACK_CLASS, TRACK_CLASS)}
+            style={{ height: LEVEL_TRACK_HEIGHT }}
+            data-testid={childTestId('track')}>
+            <span
+              aria-hidden="true"
+              className={LEVEL_FILL_CLASS}
+              style={{ top: 0, bottom: 0, width: positionOf(value) }}
+            />
+            {levels.map((label, index) => (
+              <span
+                key={label}
+                aria-hidden="true"
+                className={index <= value ? LEVEL_STOP_REACHED_CLASS : LEVEL_STOP_CLASS}
+                style={{
+                  width: LEVEL_STOP_SIZE,
+                  height: LEVEL_STOP_SIZE,
+                  top: '50%',
+                  left: positionOf(index),
+                  transform: 'translate(-50%, -50%)',
+                }}
+              />
+            ))}
+            <span
+              aria-hidden="true"
+              className={LEVEL_THUMB_CLASS}
+              style={{
+                width: LEVEL_THUMB_SIZE,
+                height: LEVEL_THUMB_SIZE,
+                top: '50%',
+                left: positionOf(value),
+                transform: 'translate(-50%, -50%)',
+              }}
+              data-testid={childTestId('thumb')}
+            />
+          </div>
+        </div>
+      </div>
+
+      {/* The summary row, with the end captions riding over it: one is showing
+          whenever the other is not. NOT `inert` while the captions are up —
+          the row is only out of the POINTER's way, and a screen-reader user is
+          not the one hovering the rail. */}
+      <div className="relative">
+        <MenuRowShell
+          role="menuitem"
+          expanded={isExpanded}
+          disabled={false}
+          title={detailsLabel}
+          trailing={
+            <MenuRowChevron>
+              <span
+                className="flex items-center justify-center"
+                style={{
+                  ...MOTION,
+                  transitionProperty: 'transform',
+                  transform: isExpanded ? 'rotate(90deg)' : 'rotate(0deg)',
+                }}>
+                <ChevronRightIcon
+                  width={ROW_ICON_SIZE}
+                  height={ROW_ICON_SIZE}
+                  fill={theme.colors.textSecondary}
+                />
+              </span>
+            </MenuRowChevron>
+          }
+          onPress={() => setExpanded(!isExpanded)}
+          className={SUB_TRIGGER_CLASS}
+          style={summaryStyle}
+          testID={childTestId('summary')}
+        />
+        {hasCaptions ? (
+          <div
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-0 flex flex-row items-center justify-between"
+            style={{
+              ...MOTION,
+              transitionProperty: 'opacity',
+              opacity: active ? 1 : 0,
+              paddingLeft: LEVEL_ROW_INSET,
+              paddingRight: LEVEL_ROW_INSET,
+            }}
+            data-testid={childTestId('captions')}>
+            <span className={LEVEL_CAPTION_CLASS}>{minLabel}</span>
+            <span className={LEVEL_CAPTION_CLASS}>{maxLabel}</span>
+          </div>
+        ) : null}
+      </div>
+
+      {/* The details. `inert` while collapsed, so a sub-menu row inside a
+          zero-height clip is not still tabbable. */}
+      <div
+        inert={!isExpanded}
+        aria-hidden={!isExpanded}
+        className="overflow-hidden"
+        style={{
+          ...MOTION,
+          transitionProperty: 'max-height, opacity',
+          maxHeight: isExpanded ? (detailsHeight === 0 ? undefined : detailsHeight) : 0,
+          opacity: isExpanded ? 1 : 0,
+        }}
+        data-testid={childTestId('details')}>
+        <div ref={measureDetails}>
+          <div
+            className={LEVEL_SEPARATOR_CLASS}
+            style={{
+              marginLeft: LEVEL_ROW_INSET,
+              marginRight: LEVEL_ROW_INSET,
+              marginBottom: 4,
+            }}
+          />
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+LevelPicker.displayName = 'LevelPicker';

package/src/level-picker/constants.ts

@@ -0,0 +1,131 @@
+/**
+ * The level picker's SPEC: the geometry both forks lay out from, the colour
+ * roles as Tailwind classes, and the two functions that map a stop to a
+ * position and a pointer back to a stop.
+ *
+ * ── WHY GEOMETRY IS NUMBERS HERE AND COLOUR IS CLASSES ───────────────────────
+ *
+ * `floating/constants.ts` states the menu vocabulary as class strings, so a
+ * consumer can restyle a row with a utility. That reasoning applies to the
+ * parts a consumer addresses — and none of these are: the rail, its stops and
+ * its knob are one control's internals, and the caller's `className` lands on
+ * the picker's ROOT.
+ *
+ * What it buys instead is the property that matters most for a two-fork
+ * component: the web fork positions a stop with `calc()` and the native fork
+ * with a measured pixel offset, and BOTH read the numbers below and call
+ * {@link levelStopPosition}. Two forks that agreed only by having the same
+ * literals typed into them is exactly the drift `MENU_SUB_SIDE_OFFSET` and
+ * `SUB_TRIGGER_CLASS` exist to prevent one level up.
+ *
+ * Colour stays in classes, because that is what the surrounding menu rows are
+ * painted with and because a token is never derived from — `bg-muted-foreground/25`
+ * is the opacity UTILITY (`color-mix`, resolved by the build), never an alpha
+ * appended to a resolved `rgb(...)`, which parses back opaque.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*  Geometry — numbers, because both forks compute with them                  */
+/* -------------------------------------------------------------------------- */
+
+/** The rail: a 24px pill, tall enough to read as a track rather than a line. */
+export const LEVEL_TRACK_HEIGHT = 24;
+
+/**
+ * The knob, LARGER than the rail on purpose (30 against 24), so it reads as a
+ * control riding the track rather than a dot inside it. It therefore overhangs
+ * the rail by 3px top and bottom, and by 2px past each end once
+ * {@link LEVEL_STOP_INSET} is applied — which is why nothing between the rail
+ * and the picker's root may clip.
+ */
+export const LEVEL_THUMB_SIZE = 30;
+
+/** A stop: a 4px dot, drawn under the knob. */
+export const LEVEL_STOP_SIZE = 4;
+
+/**
+ * How far the FIRST and LAST stop sit in from the rail's ends.
+ *
+ * Not a cosmetic margin: it is what stops the knob from hanging half off the
+ * rail at either extreme, so it is also the value {@link levelFromOffset} has
+ * to subtract before it can read a fraction — a hit map that ignores it snaps
+ * to the wrong stop for the first and last {@link LEVEL_STOP_INSET} pixels,
+ * which is precisely where a user aiming for "least" or "most" clicks.
+ */
+export const LEVEL_STOP_INSET = 13;
+
+/** The row the rail sits in — one Bloom row taller than the rail itself. */
+export const LEVEL_SLIDER_ROW_HEIGHT = 40;
+
+/**
+ * The horizontal inset of everything in the picker that is not a menu row,
+ * matching `floating/constants`' `ROW_CLASS` (`px-space-8`) so the rail and the
+ * end captions line up with the rows above and below them.
+ */
+export const LEVEL_ROW_INSET = 8;
+
+/* -------------------------------------------------------------------------- */
+/*  Colour roles — classes, as the surrounding menu rows are                  */
+/* -------------------------------------------------------------------------- */
+
+/** The unfilled rail. */
+export const LEVEL_TRACK_CLASS = 'relative rounded-full bg-muted-foreground/25';
+
+/** The filled part, which ends under the knob rather than at the rail's end. */
+export const LEVEL_FILL_CLASS = 'absolute left-0 rounded-full bg-primary';
+
+/** A stop the level has NOT reached: a dot on the bare rail. */
+export const LEVEL_STOP_CLASS = 'absolute rounded-full bg-muted-foreground/65';
+
+/** A stop the level HAS reached: the same dot, on the fill, in its on-colour. */
+export const LEVEL_STOP_REACHED_CLASS = 'absolute rounded-full bg-primary-foreground/35';
+
+/** The knob. `shadow-s` is Bloom's control-raise role, the same one `Slider` takes. */
+export const LEVEL_THUMB_CLASS = 'absolute rounded-full bg-background shadow-s';
+
+/** The two end captions, one de-emphasis step back, as a menu shortcut is. */
+export const LEVEL_CAPTION_CLASS = 'text-xs text-muted-foreground';
+
+/** The hairline between the summary row and the details region. */
+export const LEVEL_SEPARATOR_CLASS = 'h-px bg-border';
+
+/* -------------------------------------------------------------------------- */
+/*  The two mappings, written once for both forks                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Where a stop sits along the rail, as a PERCENTAGE of the rail plus a pixel
+ * OFFSET — the one form both forks can render from.
+ *
+ * The web fork spells it `calc(P% + Opx)` and never measures; the native fork
+ * multiplies the percentage by a laid-out width. Returning the pair rather than
+ * a finished value is what lets one formula serve both: a shared function that
+ * returned pixels would force the web fork to measure, and one that returned a
+ * CSS string would be unusable on native.
+ */
+export function levelStopPosition(
+  index: number,
+  count: number,
+): { percent: number; offset: number } {
+  const fraction = count <= 1 ? 0 : index / (count - 1);
+  return {
+    percent: fraction * 100,
+    offset: LEVEL_STOP_INSET - fraction * 2 * LEVEL_STOP_INSET,
+  };
+}
+
+/**
+ * Which stop a pointer at `offsetX` from the rail's left edge is asking for.
+ *
+ * The inverse of {@link levelStopPosition}, and it undoes the inset for the
+ * reason spelled out there. `trackWidth` is the rail's own width — the caller
+ * measures it (`getBoundingClientRect().width` on web, `onLayout` on native),
+ * so this stays pure and testable.
+ */
+export function levelFromOffset(offsetX: number, trackWidth: number, count: number): number {
+  if (count <= 1) return 0;
+  const usable = trackWidth - 2 * LEVEL_STOP_INSET;
+  const fraction = usable <= 0 ? 0 : (offsetX - LEVEL_STOP_INSET) / usable;
+  const index = Math.round(fraction * (count - 1));
+  return Math.max(0, Math.min(count - 1, index));
+}

package/src/level-picker/index.ts

@@ -0,0 +1,2 @@
+export { LevelPicker } from './LevelPicker';
+export type { LevelPickerProps } from './types';

package/src/level-picker/index.web.ts

@@ -0,0 +1,2 @@
+export { LevelPicker } from './LevelPicker.web';
+export type { LevelPickerProps } from './types';

package/src/level-picker/types.ts

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export interface LevelPickerProps {
+  /**
+   * The levels, in order, low to high. Its LENGTH is the number of stops and
+   * each entry is that stop's own name — read out as the slider's value
+   * (`aria-valuetext`), so it is what a screen reader says instead of an index.
+   *
+   * Two levels is the floor at which the control means anything; one renders a
+   * rail with a single stop and no travel.
+   */
+  levels: readonly string[];
+  /** The selected level, as an index into {@link levels}. Controlled. */
+  value: number;
+  /** Fired with the new index as the user drags, clicks or steps the rail. */
+  onValueChange: (value: number) => void;
+  /**
+   * The slider's accessible NAME — WHAT the level applies to.
+   *
+   * Required, not optional. A rail with a knob renders no text of its own, so
+   * ARIA can compute no name from its contents and there is nothing for the
+   * value to be announced against: without this the control says "slider, High"
+   * and never what is High. The end captions and the summary row beside it are
+   * SIBLINGS, not labels.
+   */
+  accessibilityLabel: string;
+  /**
+   * Captions for the two ends of the rail, shown while the slider is active
+   * (hovered, focused or being dragged) and faded out otherwise, in the place
+   * the summary row occupies.
+   *
+   * Both are optional and independent of {@link levels}: they name the
+   * DIRECTION of the scale ("Cheaper"/"Sharper"), which is a different claim
+   * from what any one stop is called, and a picker whose levels speak for
+   * themselves can leave them off entirely.
+   */
+  minLabel?: string;
+  maxLabel?: string;
+  /**
+   * The summary row's label — the disclosure that reveals {@link children}.
+   * Defaults to `Details`, matching the `<details>`/`<summary>` vocabulary this
+   * is the same shape as.
+   */
+  detailsLabel?: string;
+  /** Whether the details region is showing. Controlled. */
+  expanded?: boolean;
+  /** Its initial state when uncontrolled. Defaults to `false`. */
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  /**
+   * The details region's contents — the rows the summary row reveals.
+   *
+   * Ordinary menu rows: `DropdownMenuSub` triggers, `DropdownMenuItem`s,
+   * anything the surrounding surface publishes. The picker owns the reveal, the
+   * spacing and the hairline above them, and nothing about what they are.
+   */
+  children?: ReactNode;
+  /** Appended to the root's own classes, never substituted for them. */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}