panelui-native 0.66.1 → 0.71.0

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';

package/src/hooks/use-breakpoint.ts

@@ -1,7 +1,14 @@
+import { createContext, createElement, useContext, type ReactNode } from 'react';
 import { useWindowDimensions } from 'react-native';
+import {
+  breakpointAt,
+  breakpointEntries,
+  type BreakpointDefinition,
+} from './breakpoint-contract';
 
 /** Tailwind's breakpoints, minus the ones no phone or tablet reaches. */
 export const BREAKPOINTS = { sm: 640, md: 768, lg: 1024, xl: 1280 } as const;
+const DEFAULT_ENTRIES = breakpointEntries(BREAKPOINTS);
 
 export type Breakpoint = keyof typeof BREAKPOINTS;
 
@@ -15,6 +22,59 @@ export interface UseBreakpointResult {
   isLandscape: boolean;
 }
 
+export interface BreakpointResult<Name extends string> {
+  current: Name | 'base';
+  isAtLeast: (breakpoint: Name) => boolean;
+  width: number;
+  height: number;
+  isLandscape: boolean;
+}
+
+export interface BreakpointProviderProps {
+  children?: ReactNode;
+}
+
+export interface BreakpointContract<Name extends string> {
+  Provider: (props: BreakpointProviderProps) => ReactNode;
+  useBreakpoint: () => BreakpointResult<Name>;
+  breakpoints: Readonly<Record<Name, number>>;
+}
+
+/**
+ * Create app-specific responsive names. One Provider owns the window
+ * subscription; every bound hook below it reads the same dimensions.
+ */
+export function createBreakpoints<const T extends BreakpointDefinition>(
+  definition: T
+): BreakpointContract<keyof T & string> {
+  type Name = keyof T & string;
+  const breakpoints = Object.freeze({ ...definition }) as Readonly<T>;
+  const entries = breakpointEntries(breakpoints);
+  const Context = createContext<{ width: number; height: number } | null>(null);
+
+  function Provider({ children }: BreakpointProviderProps) {
+    const dimensions = useWindowDimensions();
+    return createElement(Context.Provider, { value: dimensions }, children);
+  }
+
+  function useBoundBreakpoint(): BreakpointResult<Name> {
+    const dimensions = useContext(Context);
+    if (!dimensions) {
+      throw new Error('This breakpoint hook must be used inside its Breakpoint Provider.');
+    }
+    const { width, height } = dimensions;
+    return {
+      current: breakpointAt(entries, width),
+      isAtLeast: (name) => width >= breakpoints[name]!,
+      width,
+      height,
+      isLandscape: width > height,
+    };
+  }
+
+  return { Provider, useBreakpoint: useBoundBreakpoint, breakpoints };
+}
+
 /**
  * Responsive state from the window size — the React Native answer to a media
  * query, which has no equivalent here.
@@ -31,16 +91,7 @@ export interface UseBreakpointResult {
 export function useBreakpoint(): UseBreakpointResult {
   const { width, height } = useWindowDimensions();
 
-  const current: Breakpoint | 'base' =
-    width >= BREAKPOINTS.xl
-      ? 'xl'
-      : width >= BREAKPOINTS.lg
-        ? 'lg'
-        : width >= BREAKPOINTS.md
-          ? 'md'
-          : width >= BREAKPOINTS.sm
-            ? 'sm'
-            : 'base';
+  const current = breakpointAt(DEFAULT_ENTRIES, width);
 
   return {
     current,

package/src/index.ts

@@ -416,6 +416,14 @@ export {
   type ChipVariant,
   type ChipSize,
 } from './components/chip';
+export {
+  Collapsible,
+  type CollapsibleProps,
+  type CollapsibleTriggerProps,
+  type CollapsibleIndicatorProps,
+  type CollapsibleContentProps,
+  type CollapsibleVariant,
+} from './components/collapsible';
 export {
   ColorPicker,
   type ColorPickerProps,
@@ -485,10 +493,14 @@ export {
 } from './components/field';
 export {
   Form,
+  createForm,
   useForm,
   useField,
   type FormProps,
   type FormFieldProps,
+  type TypedForm,
+  type TypedFormProps,
+  type TypedFormFieldProps,
   type FormApi,
   type FieldErrors,
   type FieldTouched,
@@ -724,6 +736,11 @@ export {
   type MarkerIconProps,
   type MarkerContentProps,
 } from './components/marker';
+export {
+  Marquee,
+  type MarqueeProps,
+  type MarqueeDirection,
+} from './components/marquee';
 export {
   Menu,
   type MenuProps,
@@ -742,6 +759,12 @@ export {
   type MenuItemVariant,
   type MenuRadioIndicator,
 } from './components/menu';
+export {
+  Meter,
+  type MeterProps,
+  type MeterColor,
+  type MeterThreshold,
+} from './components/meter';
 export {
   MessageScroller,
   useMessageScroller,
@@ -779,6 +802,26 @@ export {
   type PopoverAnchorRect,
   type PopoverAnchorControls,
 } from './components/popover';
+export {
+  Planner,
+  type PlannerProps,
+  type PlannerEntry,
+  type PlannerCategory,
+  type PlannerHeaderProps,
+  type PlannerTitleProps,
+  type PlannerTodayProps,
+  type PlannerNavProps,
+  type PlannerActionProps,
+  type PlannerGridProps,
+  type PlannerDayProps,
+  type PlannerDayState,
+  type PlannerDayRenderer,
+  type PlannerLegendProps,
+  type PlannerSummaryProps,
+  type PlannerFooterProps,
+  type PlannerDetailsProps,
+  type PlannerCountedCategory,
+} from './components/planner';
 export {
   Post,
   type PostProps,

package/src/primitives/chart-accessibility.ts

@@ -0,0 +1,102 @@
+import { createElement } from 'react';
+
+export interface ChartAccessibilityProps<Datum> {
+  /** Spoken summary. Defaults to the chart family and number of data entries. */
+  accessibilityLabel?: string;
+  /** Additional guidance spoken after the chart summary. */
+  accessibilityHint?: string;
+  /** Overrides the spoken label for one data entry. */
+  accessibilityLabelForDatum?: (datum: Datum, index: number) => string;
+  /** Makes each data entry actionable without making the SVG geometry focusable. */
+  onAccessibilityDatumPress?: (datum: Datum, index: number) => void;
+}
+
+export interface ChartAccessibilityItem<Datum> {
+  datum: Datum;
+  index: number;
+  label: string;
+}
+
+function spoken(value: unknown): string | null {
+  if (value instanceof Date) return value.toLocaleDateString();
+  if (typeof value === 'string' || typeof value === 'number') return String(value);
+  return null;
+}
+
+/** Pure semantic projection, shared by tests and the native accessibility tree. */
+export function chartAccessibilityModel<Datum>(
+  chart: string,
+  data: Datum[],
+  valueOf: (datum: Datum) => [string, unknown][],
+  labelForDatum?: (datum: Datum, index: number) => string
+): { summary: string; items: ChartAccessibilityItem<Datum>[] } {
+  return {
+    summary: `${chart}, ${data.length} ${data.length === 1 ? 'data entry' : 'data entries'}`,
+    items: data.map((datum, index) => ({
+      datum,
+      index,
+      label:
+        labelForDatum?.(datum, index) ??
+        valueOf(datum)
+          .map(([label, value]) => {
+            const text = spoken(value);
+            return text === null ? null : `${label}, ${text}`;
+          })
+          .filter((part): part is string => part !== null)
+          .join('. '),
+    })),
+  };
+}
+
+export interface ChartAccessibilityDataProps<Datum>
+  extends ChartAccessibilityProps<Datum> {
+  chart: string;
+  data: Datum[];
+  valueOf: (datum: Datum) => [string, unknown][];
+  disabled?: boolean;
+}
+
+/**
+ * A compact semantic sibling to the visual plot. The SVG remains one
+ * decorative subtree while screen readers receive one summary and one entry
+ * per datum, rather than every path, grid line and marker.
+ */
+export function ChartAccessibilityData<Datum>({
+  chart,
+  data,
+  valueOf,
+  disabled = false,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityLabelForDatum,
+  onAccessibilityDatumPress,
+}: ChartAccessibilityDataProps<Datum>) {
+  if (disabled) return null;
+  // Keep the pure semantic projection importable by Node tests without asking
+  // Node to parse React Native's Flow entry point.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { Pressable, View } = require('react-native') as typeof import('react-native');
+  const model = chartAccessibilityModel(chart, data, valueOf, accessibilityLabelForDatum);
+
+  return createElement(
+    View,
+    { style: { position: 'absolute', left: -10_000, width: 1, height: 1 } },
+    createElement(View, {
+      accessible: true,
+      accessibilityRole: 'image',
+      accessibilityLabel: accessibilityLabel ?? model.summary,
+      accessibilityHint,
+    }),
+    ...model.items.map((item) =>
+      createElement(Pressable, {
+        key: item.index,
+        accessible: true,
+        accessibilityRole: onAccessibilityDatumPress ? 'button' : 'text',
+        accessibilityLabel: item.label,
+        onPress: onAccessibilityDatumPress
+          ? () => onAccessibilityDatumPress(item.datum, item.index)
+          : undefined,
+      })
+    )
+  );
+}

package/src/primitives/focus-restoration-store.ts

@@ -0,0 +1,70 @@
+interface FocusDocument {
+  activeElement?: FocusTarget | null;
+  body?: FocusTarget | null;
+  documentElement?: FocusTarget | null;
+}
+
+interface FocusTarget {
+  disabled?: boolean;
+  isConnected?: boolean;
+  focus: (options?: { preventScroll?: boolean }) => void;
+  getAttribute?: (name: string) => string | null;
+}
+
+type RestoreFocus = () => boolean;
+
+interface FocusOwner {
+  owner: string;
+  released: boolean;
+  restore: RestoreFocus;
+}
+
+/** Restores nested overlays in last-opened order, even when parents close first. */
+export class FocusRestorationStore {
+  private owners: FocusOwner[] = [];
+
+  acquire(owner: string, restore: RestoreFocus): (() => void) {
+    const entry = { owner, released: false, restore };
+    this.owners.push(entry);
+
+    return () => {
+      if (entry.released) return;
+      entry.released = true;
+      this.restoreReleasedOwners();
+    };
+  }
+
+  private restoreReleasedOwners() {
+    const candidates: RestoreFocus[] = [];
+    while (this.owners.at(-1)?.released) {
+      const entry = this.owners.pop();
+      if (entry) candidates.push(entry.restore);
+    }
+    candidates.some((restore) => restore());
+  }
+}
+
+/** Captures the current browser focus without evaluating DOM APIs on native. */
+export function captureFocusRestore(
+  document = (globalThis as { document?: FocusDocument }).document
+): RestoreFocus {
+  const target = document?.activeElement;
+  if (!target || target === document?.body || target === document?.documentElement) {
+    return () => false;
+  }
+
+  return () => {
+    if (target.isConnected === false || target.disabled) return false;
+    if (target.getAttribute?.('aria-disabled') === 'true') return false;
+    try {
+      target.focus({ preventScroll: true });
+    } catch {
+      try {
+        target.focus();
+      } catch {
+        return false;
+      }
+    }
+    return document?.activeElement === target;
+  };
+}

package/src/primitives/portal.tsx

@@ -8,6 +8,7 @@ import {
   type ReactNode,
 } from 'react';
 import { ModalIsolationStore } from './modal-isolation-store';
+import { captureFocusRestore, FocusRestorationStore } from './focus-restoration-store';
 
 type PortalMap = ReadonlyMap<string, ReactNode>;
 
@@ -41,16 +42,21 @@ class PortalStore {
 
 const PortalContext = createContext<PortalStore | null>(null);
 const ModalIsolationContext = createContext<ModalIsolationStore | null>(null);
+const FocusRestorationContext = createContext<FocusRestorationStore | null>(null);
 
 export function PortalProvider({ children }: { children: ReactNode }) {
   const portalStoreRef = useRef<PortalStore | null>(null);
   const modalStoreRef = useRef<ModalIsolationStore | null>(null);
+  const focusStoreRef = useRef<FocusRestorationStore | null>(null);
   portalStoreRef.current ??= new PortalStore();
   modalStoreRef.current ??= new ModalIsolationStore();
+  focusStoreRef.current ??= new FocusRestorationStore();
   return (
     <PortalContext.Provider value={portalStoreRef.current}>
       <ModalIsolationContext.Provider value={modalStoreRef.current}>
-        {children}
+        <FocusRestorationContext.Provider value={focusStoreRef.current}>
+          {children}
+        </FocusRestorationContext.Provider>
       </ModalIsolationContext.Provider>
     </PortalContext.Provider>
   );
@@ -80,9 +86,27 @@ export function Portal({ children }: { children: ReactNode }) {
 /** A portal that owns modal focus until it unmounts. */
 export function ModalPortal({ children }: { children: ReactNode }) {
   const store = useModalIsolationStore('ModalPortal');
+  const focusStore = useFocusRestorationStore('ModalPortal');
   const owner = useId();
 
-  useEffect(() => store.acquire(owner), [owner, store]);
+  useEffect(() => {
+    const releaseIsolation = store.acquire(owner);
+    const releaseFocus = focusStore.acquire(owner, captureFocusRestore());
+    return () => {
+      releaseIsolation();
+      releaseFocus();
+    };
+  }, [focusStore, owner, store]);
+
+  return <Portal>{children}</Portal>;
+}
+
+/** A non-isolating portal that returns browser focus to what opened it. */
+export function FocusRestorePortal({ children }: { children: ReactNode }) {
+  const store = useFocusRestorationStore('FocusRestorePortal');
+  const owner = useId();
+
+  useEffect(() => store.acquire(owner, captureFocusRestore()), [owner, store]);
 
   return <Portal>{children}</Portal>;
 }
@@ -101,6 +125,14 @@ function useModalIsolationStore(component: string): ModalIsolationStore {
   return store;
 }
 
+function useFocusRestorationStore(component: string): FocusRestorationStore {
+  const store = useContext(FocusRestorationContext);
+  if (!store) {
+    throw new Error(`${component} must be used within a <PanelUIProvider>`);
+  }
+  return store;
+}
+
 /** Mount point for portaled content. PanelUIProvider renders one automatically. */
 export function PortalHost() {
   const store = usePortalStore('PortalHost');