panelui-native 0.66.1 → 0.68.0

package/src/components/planner/planner-entries.ts

@@ -0,0 +1,146 @@
+/**
+ * The parts of a planner that are arithmetic rather than rendering: which
+ * entries fall on which day, which category an entry belongs to, what a day
+ * says to a screen reader, and what the month adds up to.
+ *
+ * Kept out of the component so they can be tested without a renderer, and so
+ * the day cell stays a function of its inputs rather than of when it ran.
+ *
+ * Nothing here imports anything. The tests run this file through `node --test`
+ * with type stripping rather than a bundler, so an extensionless import of a
+ * sibling module — which is how the rest of the library is written — does not
+ * resolve. That is why the one line of date arithmetic below is here instead
+ * of coming from `utils/date`.
+ */
+
+/** The minimum an entry has to be for the grid to place it. */
+export interface PlannerDatedEntry {
+  date: Date;
+  /** Matches a `PlannerCategory` id. An entry without one is uncategorised. */
+  category?: string;
+}
+
+export interface PlannerCountedCategory {
+  id: string;
+  label: string;
+  count: number;
+}
+
+/** A day's key: local midnight, so two times on the same day agree. */
+export function dayKey(date: Date): number {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+}
+
+/**
+ * Entries grouped by the day they fall on, each day in the order it was given.
+ *
+ * A map rather than a lookup per cell: a month draws 42 cells, and asking each
+ * of them to filter the whole list is 42 passes over it every render.
+ */
+export function bucketByDay<T extends PlannerDatedEntry>(
+  entries: readonly T[]
+): Map<number, T[]> {
+  const days = new Map<number, T[]>();
+  for (const entry of entries) {
+    const key = dayKey(entry.date);
+    const bucket = days.get(key);
+    if (bucket) bucket.push(entry);
+    else days.set(key, [entry]);
+  }
+  return days;
+}
+
+/** What falls on one day. Always an array, so a cell has nothing to guard. */
+export function entriesOn<T extends PlannerDatedEntry>(
+  days: Map<number, T[]>,
+  date: Date
+): T[] {
+  return days.get(dayKey(date)) ?? EMPTY;
+}
+
+/*
+ * One frozen array for every empty day, rather than a new `[]` each call. A
+ * month is mostly empty days, and a fresh array per cell per render defeats
+ * every memo below it for a day where nothing changed.
+ */
+const EMPTY: never[] = Object.freeze([]) as never[];
+
+/**
+ * How many entries a cell draws before it stops and says how many are left.
+ *
+ * `limit` of 0 means draw none of them — the day still carries its marker and
+ * its spoken label, which is the whole content of a compact planner.
+ */
+export function visibleEntries<T>(entries: readonly T[], limit: number): {
+  shown: T[];
+  overflow: number;
+} {
+  const cap = Math.max(0, Math.floor(limit));
+  if (entries.length <= cap) return { shown: [...entries], overflow: 0 };
+  return { shown: entries.slice(0, cap), overflow: entries.length - cap };
+}
+
+/**
+ * What a day says when it is read out.
+ *
+ * The date on its own is what a date picker says, and it is not enough here: a
+ * day in a planner differs from the one beside it by what is on it, and a
+ * marker that carries that difference in colour alone carries it to nobody who
+ * cannot see the colour. So the count and the categories are spoken.
+ *
+ * `dateLabel` is passed in rather than formatted here, so the grid and the
+ * label agree about the calendar system and the locale.
+ */
+export function dayAccessibilityLabel<T extends PlannerDatedEntry>(
+  dateLabel: string,
+  entries: readonly T[],
+  categoryLabels: ReadonlyMap<string, string>
+): string {
+  if (entries.length === 0) return `${dateLabel}, nothing planned`;
+
+  const named: string[] = [];
+  for (const entry of entries) {
+    const label = entry.category ? categoryLabels.get(entry.category) : undefined;
+    if (label && !named.includes(label)) named.push(label);
+  }
+
+  const count = `${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`;
+  return named.length > 0
+    ? `${dateLabel}, ${count}: ${named.join(', ')}`
+    : `${dateLabel}, ${count}`;
+}
+
+/**
+ * What the month adds up to, per category, in the order the categories were
+ * declared — so the legend and the totals beside it never disagree about which
+ * one comes first.
+ *
+ * Entries outside `month` are left out. The grid draws the days either side of
+ * the month it is showing, and counting those would make a total that changes
+ * with the week the month happens to start on.
+ */
+export function summariseMonth<T extends PlannerDatedEntry>(
+  entries: readonly T[],
+  categories: readonly { id: string; label: string }[],
+  isInMonth: (date: Date) => boolean
+): { total: number; categories: PlannerCountedCategory[] } {
+  const counts = new Map<string, number>();
+  let total = 0;
+
+  for (const entry of entries) {
+    if (!isInMonth(entry.date)) continue;
+    total += 1;
+    if (entry.category) {
+      counts.set(entry.category, (counts.get(entry.category) ?? 0) + 1);
+    }
+  }
+
+  return {
+    total,
+    categories: categories.map(({ id, label }) => ({
+      id,
+      label,
+      count: counts.get(id) ?? 0,
+    })),
+  };
+}

package/src/components/radar-chart/index.tsx

@@ -59,6 +59,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
+import { ChartAccessibilityData, type ChartAccessibilityProps } from '../../primitives/chart-accessibility';
 import { cn } from '../../utils/cn';
 import {
   polarPoint,
@@ -212,6 +213,9 @@ export interface RadarChartProps extends Omit<ViewProps, 'children'> {
   /** Drop the room reserved for axis labels, for a radar with none. */
   compact?: boolean;
   children?: ReactNode;
+  /** Accessible data labels and optional activation for each axis row. */
+  accessibilityLabelForDatum?: ChartAccessibilityProps<RadarChartDatum>['accessibilityLabelForDatum'];
+  onAccessibilityDatumPress?: ChartAccessibilityProps<RadarChartDatum>['onAccessibilityDatumPress'];
 }
 
 /** Imperative handle: re-run the reveal on demand, for a "replay" control. */
@@ -231,6 +235,11 @@ const RadarChartRoot = forwardRef<RadarChartHandle, RadarChartProps>(
       domain,
       animationDuration = REVEAL_DURATION,
       compact = false,
+      accessible,
+      accessibilityLabel,
+      accessibilityHint,
+      accessibilityLabelForDatum,
+      onAccessibilityDatumPress,
       children,
       ...props
     },
@@ -393,6 +402,19 @@ const RadarChartRoot = forwardRef<RadarChartHandle, RadarChartProps>(
       <RadarChartContext.Provider value={context}>
         <View {...props} style={props.style} className={cn('w-full', className)}>
           {header}
+          <ChartAccessibilityData
+            chart="Radar chart"
+            data={data}
+            disabled={accessible === false || status === 'loading'}
+            accessibilityLabel={accessibilityLabel}
+            accessibilityHint={accessibilityHint}
+            accessibilityLabelForDatum={accessibilityLabelForDatum}
+            onAccessibilityDatumPress={onAccessibilityDatumPress}
+            valueOf={(datum) => [
+              [axisKey, datum[axisKey]],
+              ...series.map(([key]) => [key, datum[key]] as [string, unknown]),
+            ]}
+          />
           <View
             onLayout={onLayout}
             style={
@@ -407,6 +429,8 @@ const RadarChartRoot = forwardRef<RadarChartHandle, RadarChartProps>(
                 : { aspectRatio }
             }
             className={fixedSize ? 'self-center' : 'w-full'}
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
           >
             {radius > 0 ? (
               <>

package/src/components/scatter-chart/index.tsx

@@ -67,6 +67,7 @@ import Animated, {
 import Svg, { Circle, G, Line as SvgLine } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
+import { ChartAccessibilityData, type ChartAccessibilityProps } from '../../primitives/chart-accessibility';
 import { compactNumber, useSeriesColor, xAt, yOf, type Plot } from '../../utils/chart';
 import { cn } from '../../utils/cn';
 
@@ -191,7 +192,7 @@ export function useScatterChart() {
   return { activePoint, xDataKey };
 }
 
-export interface ScatterChartProps extends ViewProps {
+export interface ScatterChartProps extends ViewProps, ChartAccessibilityProps<ScatterChartDatum> {
   className?: string;
   /** The rows. Each one is a point, placed by two of its values. */
   data: ScatterChartDatum[];
@@ -244,6 +245,11 @@ const ScatterChartRoot = forwardRef<ScatterChartHandle, ScatterChartProps>(
       xDomain,
       yDomain,
       onActivePointChange,
+      accessible,
+      accessibilityLabel,
+      accessibilityHint,
+      accessibilityLabelForDatum,
+      onAccessibilityDatumPress,
       compact = false,
       children,
       ...props
@@ -476,7 +482,26 @@ const ScatterChartRoot = forwardRef<ScatterChartHandle, ScatterChartProps>(
       <ScatterChartContext.Provider value={context}>
         <View {...props} style={props.style} className={cn('w-full', className)}>
           {header}
-          <View onLayout={onLayout} style={{ aspectRatio }} className="w-full">
+          <ChartAccessibilityData
+            chart="Scatter chart"
+            data={data}
+            disabled={accessible === false || status === 'loading'}
+            accessibilityLabel={accessibilityLabel}
+            accessibilityHint={accessibilityHint}
+            accessibilityLabelForDatum={accessibilityLabelForDatum}
+            onAccessibilityDatumPress={onAccessibilityDatumPress}
+            valueOf={(datum) => [
+              [xDataKey, datum[xDataKey]],
+              ...series.map(([key]) => [key, datum[key]] as [string, unknown]),
+            ]}
+          />
+          <View
+            onLayout={onLayout}
+            style={{ aspectRatio }}
+            className="w-full"
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
+          >
             {plot.width > 0 ? (
               <>
                 <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>

package/src/components/skeleton/index.tsx

@@ -2,31 +2,85 @@ import { memo, useEffect } from 'react';
 import Animated, {
   cancelAnimation,
   useAnimatedStyle,
+  useReducedMotion,
   useSharedValue,
   withRepeat,
   withTiming,
 } from 'react-native-reanimated';
 import { cn } from '../../utils/cn';
 
+/** Milliseconds for one half of the pulse. */
+const PULSE_DURATION = 700;
+/** How far down the pulse goes. */
+const PULSE_FLOOR = 0.45;
+/**
+ * Where the pulse rests when it is not running. Between the two ends of it, so
+ * a still skeleton looks like the same placeholder rather than a solid block.
+ */
+const RESTING_OPACITY = 0.7;
+
 export interface SkeletonProps {
   className?: string;
+  /**
+   * What is loading, for a screen reader. Setting it makes this skeleton
+   * announce as a busy status; leaving it unset keeps the placeholder out of
+   * the accessibility tree entirely.
+   *
+   * A screen full of placeholders needs **one** of them labelled, not all of
+   * them — put it on the skeleton standing for the region and leave the rest
+   * silent.
+   */
+  label?: string;
 }
 
-/** Pulsing placeholder. Opacity animation runs on the UI thread. */
-export const Skeleton = memo(function Skeleton({ className }: SkeletonProps) {
-  const opacity = useSharedValue(1);
+/**
+ * Pulsing placeholder for content that has not arrived. The opacity animation
+ * runs on the UI thread.
+ *
+ * A placeholder is a picture of absent content, so it is hidden from assistive
+ * technology by default — an unlabelled grey box announces nothing worth
+ * hearing, and a screen of them announces it many times over. Pass `label` on
+ * the one skeleton that stands for the region to have the wait announced once.
+ *
+ * Under the platform's reduce-motion setting the pulse stops and the
+ * placeholder holds at a middle opacity. Unlike a spinner, a skeleton that
+ * stops moving does not read as hung: it is a shape where content will be, and
+ * the shape says that on its own.
+ */
+export const Skeleton = memo(function Skeleton({
+  className,
+  label,
+}: SkeletonProps) {
+  const reducedMotion = useReducedMotion();
+  const opacity = useSharedValue(reducedMotion ? RESTING_OPACITY : 1);
 
   useEffect(() => {
-    opacity.value = withRepeat(withTiming(0.45, { duration: 700 }), -1, true);
+    if (reducedMotion) {
+      opacity.value = RESTING_OPACITY;
+      return undefined;
+    }
+    opacity.value = 1;
+    opacity.value = withRepeat(
+      withTiming(PULSE_FLOOR, { duration: PULSE_DURATION }),
+      -1,
+      true
+    );
     return () => cancelAnimation(opacity);
-  }, [opacity]);
+  }, [opacity, reducedMotion]);
 
   const animatedStyle = useAnimatedStyle(() => ({
     opacity: opacity.value,
   }));
 
+  const announced = label != null;
+
   return (
     <Animated.View
+      accessibilityRole={announced ? 'progressbar' : undefined}
+      accessibilityLabel={label}
+      accessibilityState={announced ? { busy: true } : undefined}
+      accessibilityElementsHidden={!announced}
+      importantForAccessibility={announced ? 'auto' : 'no-hide-descendants'}
       style={animatedStyle}
       className={cn('rounded-md bg-skeleton', className)}
     />

package/src/components/spinner/index.tsx

@@ -1,14 +1,23 @@
 import { memo, useEffect } from 'react';
 import Animated, {
   Easing,
+  cancelAnimation,
+  interpolate,
   useAnimatedStyle,
+  useReducedMotion,
   useSharedValue,
   withRepeat,
   withTiming,
-  cancelAnimation,
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
 
+/** Milliseconds for one full turn. */
+const SPIN_DURATION = 800;
+/** Milliseconds for one half of the fade that stands in for the turn. */
+const PULSE_DURATION = 900;
+/** How far down the fade goes. Faint enough to read as a pulse, not a flicker. */
+const PULSE_FLOOR = 0.35;
+
 const spinnerVariants = tv({
   base: 'rounded-full border-2 border-muted border-t-primary',
   variants: {
@@ -25,27 +34,85 @@ const spinnerVariants = tv({
 
 export interface SpinnerProps extends VariantProps<typeof spinnerVariants> {
   className?: string;
+  /**
+   * What is loading, for a screen reader. Setting it makes the spinner
+   * announce as a busy status; leaving it unset keeps it out of the
+   * accessibility tree.
+   *
+   * Leave it unset wherever something around the spinner already says the
+   * wait is on — a loading button, a row with its own caption. Set it where
+   * the spinner is the only sign, or the wait passes in silence.
+   */
+  label?: string;
 }
 
-/** Rotating ring spinner. Animation runs entirely on the UI thread. */
-export const Spinner = memo(function Spinner({ className, size }: SpinnerProps) {
-  const rotation = useSharedValue(0);
+/**
+ * Rotating ring for work of unknown length. The animation runs entirely on the
+ * UI thread.
+ *
+ * A bare ring carries no words, so it is hidden from assistive technology
+ * unless `label` is given — an unnamed progress indicator announces its role
+ * and nothing else, which is noise standing in for information.
+ *
+ * Under the platform's reduce-motion setting the ring stops turning and fades
+ * in place instead. Stopping it dead is the other option and it is the wrong
+ * one: a spinner that holds still reads as one that has hung, which is the
+ * single thing a spinner exists to rule out. Reduce motion asks for less
+ * travel, not for less news.
+ */
+export const Spinner = memo(function Spinner({
+  className,
+  size,
+  label,
+}: SpinnerProps) {
+  const reducedMotion = useReducedMotion();
+  const progress = useSharedValue(0);
 
   useEffect(() => {
-    rotation.value = withRepeat(
-      withTiming(360, { duration: 800, easing: Easing.linear }),
-      -1
+    progress.value = 0;
+    progress.value = withRepeat(
+      withTiming(1, {
+        duration: reducedMotion ? PULSE_DURATION : SPIN_DURATION,
+        easing: reducedMotion ? Easing.inOut(Easing.ease) : Easing.linear,
+      }),
+      -1,
+      // The turn restarts where it began, because a full circle already ends
+      // where it started. The fade turns around, because a pulse that snapped
+      // back to full brightness would be the flicker the setting is there to
+      // avoid.
+      reducedMotion
     );
-    return () => cancelAnimation(rotation);
-  }, [rotation]);
+    return () => cancelAnimation(progress);
+  }, [progress, reducedMotion]);
+
+  /*
+   * One style sets both properties either case needs. The two are swapped on
+   * the same view when the setting changes under a mounted spinner, and an
+   * animated property that one case drops is not reset by the other — it is
+   * left at whatever it was last given, which would strand a half-faded ring
+   * at that opacity for the rest of its life.
+   */
+  const animatedStyle = useAnimatedStyle(() =>
+    reducedMotion
+      ? {
+          opacity: interpolate(progress.value, [0, 1], [1, PULSE_FLOOR]),
+          transform: [{ rotate: '0deg' }],
+        }
+      : {
+          opacity: 1,
+          transform: [{ rotate: `${progress.value * 360}deg` }],
+        }
+  );
 
-  const animatedStyle = useAnimatedStyle(() => ({
-    transform: [{ rotate: `${rotation.value}deg` }],
-  }));
+  const announced = label != null;
 
   return (
     <Animated.View
-      accessibilityRole="progressbar"
+      accessibilityRole={announced ? 'progressbar' : undefined}
+      accessibilityLabel={label}
+      accessibilityState={announced ? { busy: true } : undefined}
+      accessibilityElementsHidden={!announced}
+      importantForAccessibility={announced ? 'auto' : 'no-hide-descendants'}
       style={animatedStyle}
       className={spinnerVariants({ size, className })}
     />

package/src/components/time-picker/index.tsx

@@ -36,12 +36,11 @@
  *
  * ## Scroll offset, not gesture maths
  *
- * The wheel, the clock's list and the ruler are all scroll views with
- * `snapToOffsets`, and the selection is `Math.round(offset / itemSize)`. That
- * buys momentum, deceleration, edge bounce and platform-correct fling physics
- * for nothing, and none of it would be worth rebuilding on a pan gesture. The
- * per-item fade and the ruler's readout follow the offset on the UI thread, so
- * scrolling never round-trips through React — only the settled value does.
+ * The wheel, the clock's list and the ruler are snapping scroll views, and the
+ * selection is `Math.round(offset / itemSize)`. That buys momentum,
+ * deceleration, edge bounce and platform-correct fling physics for nothing,
+ * and none of it would be worth rebuilding on a pan gesture. The ruler keeps
+ * that full scroll range but mounts only an overscanned window of its ticks.
  */
 import {
   useCallback,
@@ -79,6 +78,7 @@ import {
   accessibilityValueForIndex,
   indexForAccessibilityAction,
 } from './accessibility';
+import { rulerWindow } from './ruler-window';
 import {
   clampTime,
   displayHour,
@@ -848,10 +848,20 @@ function RulerFace({
    */
   const [width, setWidth] = useState(0);
   const pad = Math.max(0, width / 2 - TICK_SPACING / 2);
+  const [windowIndex, setWindowIndex] = useState(index);
+  // A controlled/accessibility jump renders its destination before the effect
+  // moves the scroll view there; an in-flight gesture follows the scroll window.
+  const windowAnchor = index === resting.current ? windowIndex : index;
+  const window = rulerWindow(times.length, windowAnchor);
 
-  const snapToOffsets = useMemo(
-    () => times.map((_, i) => i * TICK_SPACING),
-    [times]
+  const showIndex = useCallback(
+    (next: number) => {
+      const nextStart = rulerWindow(times.length, next).start;
+      setWindowIndex((current) =>
+        rulerWindow(times.length, current).start === nextStart ? current : next
+      );
+    },
+    [times.length]
   );
 
   // The scale runs the same rest-and-resync machinery the wheel's columns do,
@@ -872,10 +882,14 @@ function RulerFace({
 
   // Unanimated, for the reason given on the wheel's columns: an animated
   // programmatic scroll reports itself as a gesture and the correction loops.
-  const snapTo = useCallback((to: number) => {
-    resting.current = to;
-    ref.current?.scrollTo({ x: to * TICK_SPACING, animated: false });
-  }, []);
+  const snapTo = useCallback(
+    (to: number) => {
+      resting.current = to;
+      showIndex(to);
+      ref.current?.scrollTo({ x: to * TICK_SPACING, animated: false });
+    },
+    [showIndex]
+  );
 
   useEffect(() => {
     if (index === resting.current) return;
@@ -934,6 +948,13 @@ function RulerFace({
     [atRest, cancelTimer, settleAt]
   );
 
+  const onScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      showIndex(Math.round(event.nativeEvent.contentOffset.x / TICK_SPACING));
+    },
+    [showIndex]
+  );
+
   useEffect(() => cancelTimer, [cancelTimer]);
 
   const stepsPerHour = Math.max(1, Math.round(60 / minuteStep));
@@ -985,9 +1006,11 @@ function RulerFace({
           contentOffset={{ x: index * TICK_SPACING, y: 0 }}
           scrollEnabled={!disabled}
           showsHorizontalScrollIndicator={false}
-          snapToOffsets={snapToOffsets}
+          snapToInterval={TICK_SPACING}
           disableIntervalMomentum
           decelerationRate="fast"
+          onScroll={onScroll}
+          scrollEventThrottle={16}
           onScrollBeginDrag={startMoving}
           onScrollEndDrag={onDragEnd}
           onMomentumScrollBegin={startMoving}
@@ -1009,22 +1032,27 @@ function RulerFace({
             at most — which is a legend, not a scale, and reads as clutter
             beside a number set at 36px.
           */}
-          {times.map((_, i) => (
-            <View
-              key={i}
-              style={{ width: TICK_SPACING }}
-              className="items-center justify-center"
-            >
+          <View style={{ width: window.start * TICK_SPACING }} />
+          {times.slice(window.start, window.end).map((_, offset) => {
+            const i = window.start + offset;
+            return (
               <View
-                className={cn(
-                  'w-0.5 rounded-full',
-                  // Taller and darker on the hour, so the scale reads as hours
-                  // rather than as an undifferentiated comb.
-                  i % stepsPerHour === 0 ? 'h-7 bg-muted-foreground' : 'h-4 bg-border'
-                )}
-              />
-            </View>
-          ))}
+                key={i}
+                style={{ width: TICK_SPACING }}
+                className="items-center justify-center"
+              >
+                <View
+                  className={cn(
+                    'w-0.5 rounded-full',
+                    // Taller and darker on the hour, so the scale reads as hours
+                    // rather than as an undifferentiated comb.
+                    i % stepsPerHour === 0 ? 'h-7 bg-muted-foreground' : 'h-4 bg-border'
+                  )}
+                />
+              </View>
+            );
+          })}
+          <View style={{ width: (times.length - window.end) * TICK_SPACING }} />
         </ScrollView>
 
         {/* Over the scale rather than in it: the indicator marks the centre of

package/src/components/time-picker/ruler-window.ts

@@ -0,0 +1,24 @@
+/** Maximum tick cells mounted by the ruler, regardless of the minute step. */
+export const RULER_WINDOW_SIZE = 121;
+
+const WINDOW_SHIFT = 40;
+
+export interface RulerWindow {
+  start: number;
+  end: number;
+}
+
+/**
+ * A chunked, overscanned slice around the visible tick. It moves only once per
+ * WINDOW_SHIFT ticks, leaving at least forty ticks ahead of a normal scroll.
+ */
+export function rulerWindow(itemCount: number, visibleIndex: number): RulerWindow {
+  const count = Math.max(0, Math.floor(itemCount));
+  if (count <= RULER_WINDOW_SIZE) return { start: 0, end: count };
+
+  const index = Math.min(Math.max(Math.round(visibleIndex), 0), count - 1);
+  const chunk = Math.floor(index / WINDOW_SHIFT) * WINDOW_SHIFT;
+  const before = Math.floor((RULER_WINDOW_SIZE - WINDOW_SHIFT) / 2);
+  const start = Math.min(Math.max(chunk - before, 0), count - RULER_WINDOW_SIZE);
+  return { start, end: start + RULER_WINDOW_SIZE };
+}

package/src/hooks/breakpoint-contract.ts

@@ -0,0 +1,31 @@
+export type BreakpointDefinition = Readonly<Record<string, number>>;
+
+/** Validate declaration order once, when an app creates its responsive contract. */
+export function breakpointEntries<const T extends BreakpointDefinition>(definition: T) {
+  const entries = Object.entries(definition) as [keyof T & string, number][];
+  if (!entries.length) throw new Error('Breakpoints must declare at least one threshold.');
+  let previous = -1;
+  for (const [name, threshold] of entries) {
+    if (!name || !Number.isFinite(threshold) || threshold < 0) {
+      throw new Error(`Breakpoint "${name}" must have a finite, non-negative threshold.`);
+    }
+    if (threshold <= previous) {
+      throw new Error('Breakpoint thresholds must be strictly ascending in declaration order.');
+    }
+    previous = threshold;
+  }
+  return entries;
+}
+
+/** Largest satisfied name, with `base` as the deterministic below-range fallback. */
+export function breakpointAt<Name extends string>(
+  entries: readonly (readonly [Name, number])[],
+  width: number
+): Name | 'base' {
+  let current: Name | 'base' = 'base';
+  for (const [name, threshold] of entries) {
+    if (width < threshold) break;
+    current = name;
+  }
+  return current;
+}

package/src/hooks/index.ts

@@ -10,8 +10,12 @@ export {
 } from './use-disclosure';
 export {
   useBreakpoint,
+  createBreakpoints,
   BREAKPOINTS,
   type Breakpoint,
+  type BreakpointContract,
+  type BreakpointProviderProps,
+  type BreakpointResult,
   type UseBreakpointResult,
 } from './use-breakpoint';
 export { useKeyboard, type UseKeyboardResult } from './use-keyboard';