panelui-native 0.65.0 → 0.68.0

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

@@ -209,6 +209,8 @@ export {
   type FlowControlsProps,
   type FlowMiniMapProps,
   type FlowConnection,
+  type FlowEndpoint,
+  type FlowEndpointReference,
   type FlowViewport,
   type FlowNodePosition,
   type FlowEdgeVariant,
@@ -483,10 +485,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,
@@ -740,6 +746,12 @@ export {
   type MenuItemVariant,
   type MenuRadioIndicator,
 } from './components/menu';
+export {
+  Meter,
+  type MeterProps,
+  type MeterColor,
+  type MeterThreshold,
+} from './components/meter';
 export {
   MessageScroller,
   useMessageScroller,
@@ -777,6 +789,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/scrim.tsx

@@ -10,17 +10,20 @@
  * that never blurs anything installs nothing. When it is asked for and the
  * package is missing, this falls back to a dim rather than failing: a blur you
  * cannot draw is better shown as a darkened screen than as a crash.
+ * Reduce Transparency replaces the blur with an opaque, tint-aware surface.
  *
  * It fills its parent and does not intercept touches itself — the overlay layers
  * its own dismiss `Pressable` over it — so it is purely the visual backdrop.
  */
-import { type ComponentType } from 'react';
-import { StyleSheet, View, type ViewProps } from 'react-native';
+import { useEffect, useState, type ComponentType } from 'react';
+import { AccessibilityInfo, StyleSheet, View, type ViewProps } from 'react-native';
 import Animated, { FadeIn, FadeOut } from 'react-native-reanimated';
 
+type BlurTint = 'light' | 'dark' | 'default' | 'systemMaterial';
+
 interface BlurViewProps {
   intensity?: number;
-  tint?: 'light' | 'dark' | 'default' | 'systemMaterial';
+  tint?: BlurTint;
   style?: unknown;
   children?: React.ReactNode;
 }
@@ -43,16 +46,112 @@ const BlurView: ComponentType<BlurViewProps> | null = (() => {
 /** True when a real blur can be drawn — for a caller that wants to know. */
 export const hasBlur = BlurView !== null;
 
+type ReduceTransparencySource = {
+  isReduceTransparencyEnabled?: () => Promise<boolean>;
+  addEventListener?: (
+    event: 'reduceTransparencyChanged',
+    listener: (enabled: boolean) => void
+  ) => { remove?: () => void } | undefined;
+};
+
+function observeReduceTransparency(
+  source: ReduceTransparencySource,
+  onChange: (enabled: boolean) => void
+) {
+  let active = true;
+  let changed = false;
+  const update = (enabled: boolean) => {
+    changed = true;
+    if (active) onChange(Boolean(enabled));
+  };
+  /*
+   * A platform that cannot report the preference has no preference to respect,
+   * so blur stays available. A platform that has the API and failed to answer
+   * might have it switched on, and that is the case worth being careful about.
+   */
+  const fallback = (queryable: boolean) => () => {
+    if (active && !changed) onChange(queryable);
+  };
+
+  let subscription: { remove?: () => void } | undefined;
+  try {
+    subscription = source.addEventListener?.('reduceTransparencyChanged', update);
+  } catch {
+    // Some web and test shims expose AccessibilityInfo without every event.
+  }
+
+  try {
+    if (typeof source.isReduceTransparencyEnabled !== 'function') fallback(false)();
+    else {
+      void source.isReduceTransparencyEnabled().then((enabled) => {
+        // A preference event that arrived while the query was pending is newer.
+        if (active && !changed) update(enabled);
+      }, fallback(true));
+    }
+  } catch {
+    fallback(true)();
+  }
+
+  return () => {
+    active = false;
+    try {
+      subscription?.remove?.();
+    } catch {
+      // Cleanup stays safe for partial platform shims.
+    }
+  };
+}
+
+/**
+ * The last answer the platform gave, shared by every scrim in the process.
+ *
+ * The query is asynchronous and the preference belongs to the device, not to
+ * any one overlay. Without this, each overlay opens not knowing it and draws
+ * opaque until the answer arrives — a flash on every dialog for the many people
+ * who have the preference off. Remembered here, only the first overlay of a
+ * launch can see it.
+ */
+let knownReduceTransparency: boolean | null = null;
+
+function useReduceTransparency() {
+  // Not knowing is deliberately conservative: draw opaque until the platform
+  // says blur is allowed, rather than flashing blur at someone who opted out.
+  const [enabled, setEnabled] = useState<boolean | null>(knownReduceTransparency);
+  useEffect(
+    () =>
+      observeReduceTransparency(AccessibilityInfo, (next) => {
+        knownReduceTransparency = next;
+        setEnabled(next);
+      }),
+    []
+  );
+  return enabled;
+}
+
+type ScrimMode = 'blur' | 'dim' | 'opaque';
+
+function scrimMode(blur: boolean, canBlur: boolean, reduceTransparency: boolean | null): ScrimMode {
+  if (!blur) return 'dim';
+  if (reduceTransparency !== false) return 'opaque';
+  return canBlur ? 'blur' : 'dim';
+}
+
+function opaqueClassName(tint: BlurTint) {
+  if (tint === 'light') return 'bg-white';
+  if (tint === 'dark') return 'bg-black';
+  return 'bg-background';
+}
+
 export interface ScrimProps extends Omit<ViewProps, 'children'> {
   /** Frost the backdrop instead of dimming it. Falls back to a dim if it can't. */
   blur?: boolean;
   /** Blur strength, 0–100. */
   intensity?: number;
   /** Which way the blur tints. */
-  tint?: 'light' | 'dark' | 'default' | 'systemMaterial';
+  tint?: BlurTint;
   /**
-   * The dim used when not blurring — and when blurring is asked for but
-   * unavailable. A popover passes a lighter one than a dialog.
+   * The dim used when not blurring, when blur is unavailable, and over the
+   * opaque Reduce Transparency fallback. A popover passes a lighter one than a dialog.
    */
   dimClassName?: string;
 }
@@ -65,7 +164,10 @@ export function Scrim({
   style,
   ...props
 }: ScrimProps) {
-  if (blur && BlurView) {
+  const reduceTransparency = useReduceTransparency();
+  const mode = scrimMode(blur, BlurView !== null, reduceTransparency);
+
+  if (mode === 'blur' && BlurView) {
     return (
       <Animated.View
         entering={FadeIn.duration(180)}
@@ -81,6 +183,24 @@ export function Scrim({
     );
   }
 
+  if (mode === 'opaque') {
+    return (
+      <Animated.View
+        entering={FadeIn.duration(180)}
+        exiting={FadeOut.duration(150)}
+        style={[StyleSheet.absoluteFill, style]}
+        {...props}
+      >
+        <View
+          pointerEvents="none"
+          style={StyleSheet.absoluteFill}
+          className={opaqueClassName(tint)}
+        />
+        <View pointerEvents="none" style={StyleSheet.absoluteFill} className={dimClassName} />
+      </Animated.View>
+    );
+  }
+
   return (
     <Animated.View
       entering={FadeIn.duration(150)}