panelui-native 0.9.0 → 0.12.0

package/src/components/toggle-button/index.tsx

@@ -0,0 +1,374 @@
+/**
+ * ToggleButton — a button that stays down.
+ *
+ * The difference from Button is the whole point: a button does something and
+ * springs back, a toggle button *is* something afterwards. So the selected
+ * state is the loud one — a filled accent surface — and the resting state is
+ * quiet, either a soft fill or nothing at all.
+ *
+ * ```tsx
+ * <ToggleButton defaultSelected>Like</ToggleButton>
+ *
+ * <ToggleButton iconOnly accessibilityLabel="Bold">
+ *   <BoldIcon size={16} />
+ * </ToggleButton>
+ * ```
+ *
+ * `ToggleButtonGroup` takes over the state for a set of them — a segmented
+ * toolbar in `multiple` mode, an either-or choice in `single`. Inside a group
+ * each button needs an `id`, which is the value the group reports.
+ *
+ * ```tsx
+ * <ToggleButtonGroup selectionMode="multiple" value={marks} onValueChange={setMarks}>
+ *   <ToggleButton id="bold" iconOnly accessibilityLabel="Bold">…</ToggleButton>
+ *   <ToggleButton id="italic" iconOnly accessibilityLabel="Italic">…</ToggleButton>
+ * </ToggleButtonGroup>
+ * ```
+ */
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import { IconColorProvider } from '../../icons';
+import {
+  AnimatedPressable,
+  type AnimatedPressableProps,
+} from '../../primitives/animated-pressable';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+
+const toggleVariants = tv({
+  slots: {
+    root: 'flex-row items-center justify-center gap-2 rounded-lg border border-transparent',
+    label: 'font-medium',
+  },
+  variants: {
+    variant: {
+      /** A soft fill at rest, so the control is visible before you touch it. */
+      default: { root: 'bg-secondary' },
+      /** Nothing at rest — for a dense toolbar where six fills would be noise. */
+      ghost: { root: 'bg-transparent' },
+    },
+    size: {
+      sm: { root: 'h-9 gap-1.5 px-2.5', label: 'text-sm' },
+      md: { root: 'h-11 px-4', label: 'text-base' },
+      lg: { root: 'h-12 px-6', label: 'text-lg' },
+    },
+    selected: {
+      true: { root: 'border-primary/24 bg-accent', label: 'text-accent-foreground' },
+      false: { label: 'text-muted-foreground' },
+    },
+    iconOnly: {
+      true: { root: 'px-0' },
+    },
+    disabled: {
+      true: { root: 'opacity-[0.64]' },
+    },
+  },
+  compoundVariants: [
+    // Square, and sized from the height so the icon sits in the middle.
+    { iconOnly: true, size: 'sm', class: { root: 'w-9' } },
+    { iconOnly: true, size: 'md', class: { root: 'w-11' } },
+    { iconOnly: true, size: 'lg', class: { root: 'w-12' } },
+  ],
+  defaultVariants: {
+    variant: 'default',
+    size: 'md',
+  },
+});
+
+type ToggleVariantProps = VariantProps<typeof toggleVariants>;
+export type ToggleButtonSize = NonNullable<ToggleVariantProps['size']>;
+export type ToggleButtonVariant = NonNullable<ToggleVariantProps['variant']>;
+export type ToggleSelectionMode = 'single' | 'multiple';
+
+/* -------------------------------------------------------------------------- */
+/* Group                                                                      */
+/* -------------------------------------------------------------------------- */
+
+interface ToggleGroupContextValue {
+  isSelected: (id: string) => boolean;
+  toggle: (id: string) => void;
+  disabled: boolean;
+  variant?: ToggleButtonVariant;
+  size?: ToggleButtonSize;
+}
+
+const ToggleGroupContext = createContext<ToggleGroupContextValue | null>(null);
+
+export interface ToggleButtonGroupProps extends ViewProps {
+  className?: string;
+  /**
+   * `multiple` is a set of independent marks — bold *and* italic. `single` is
+   * an either-or choice where picking one clears the last.
+   */
+  selectionMode?: ToggleSelectionMode;
+  /** Selected ids. Controlled — pair with `onValueChange`. */
+  value?: string[];
+  /** Starting selection when uncontrolled. */
+  defaultValue?: string[];
+  onValueChange?: (value: string[]) => void;
+  /** Disables every button in the group. */
+  disabled?: boolean;
+  /** Applied to every button that does not set its own. */
+  variant?: ToggleButtonVariant;
+  size?: ToggleButtonSize;
+  children: ReactNode;
+}
+
+const ToggleButtonGroup = forwardRef<View, ToggleButtonGroupProps>(
+  (
+    {
+      className,
+      selectionMode = 'multiple',
+      value,
+      defaultValue = [],
+      onValueChange,
+      disabled = false,
+      variant,
+      size,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = useState<string[]>(defaultValue);
+    const selection = isControlled ? value : internal;
+
+    const toggle = useCallback(
+      (id: string) => {
+        const has = selection.includes(id);
+        const next =
+          selectionMode === 'single'
+            ? // Pressing the selected one again clears it. A toolbar filter you
+              // cannot turn off is a trap.
+              has
+              ? []
+              : [id]
+            : has
+              ? selection.filter((item) => item !== id)
+              : [...selection, id];
+
+        if (!isControlled) setInternal(next);
+        onValueChange?.(next);
+      },
+      [selection, selectionMode, isControlled, onValueChange]
+    );
+
+    const context = useMemo<ToggleGroupContextValue>(
+      () => ({
+        isSelected: (id) => selection.includes(id),
+        toggle,
+        disabled,
+        variant,
+        size,
+      }),
+      [selection, toggle, disabled, variant, size]
+    );
+
+    return (
+      <ToggleGroupContext.Provider value={context}>
+        <View
+          ref={ref}
+          // `radiogroup` for an either-or choice, `toolbar` for a set of
+          // independent marks — the two are read out differently, and which
+          // one applies is exactly what selectionMode says.
+          accessibilityRole={selectionMode === 'single' ? 'radiogroup' : 'toolbar'}
+          className={cn('flex-row items-center gap-1.5', className)}
+          {...props}
+        >
+          {children}
+        </View>
+      </ToggleGroupContext.Provider>
+    );
+  }
+);
+ToggleButtonGroup.displayName = 'ToggleButtonGroup';
+
+/* -------------------------------------------------------------------------- */
+/* Button                                                                     */
+/* -------------------------------------------------------------------------- */
+
+interface ToggleStateValue {
+  selected: boolean;
+  disabled: boolean;
+}
+
+const ToggleStateContext = createContext<ToggleStateValue | null>(null);
+
+/**
+ * The toggle's own state, for anything rendered inside it — an icon that
+ * changes shape when selected, a count that only shows when it is on.
+ */
+export function useToggleButton(): ToggleStateValue {
+  const state = useContext(ToggleStateContext);
+  if (!state) {
+    throw new Error('useToggleButton must be used within a <ToggleButton>');
+  }
+  return state;
+}
+
+export interface ToggleButtonProps
+  extends Omit<AnimatedPressableProps, 'children' | 'disabled'>,
+    Omit<ToggleVariantProps, 'selected' | 'disabled' | 'iconOnly'> {
+  children?: ReactNode;
+  className?: string;
+  /** Extra classes for the label when children is a string. */
+  labelClassName?: string;
+  /** Identifies this button within a `ToggleButtonGroup`. Required there. */
+  id?: string;
+  /** Controlled selection. Ignored inside a group, which owns the state. */
+  selected?: boolean;
+  /** Starting state when uncontrolled and outside a group. */
+  defaultSelected?: boolean;
+  onSelectedChange?: (selected: boolean) => void;
+  disabled?: boolean;
+  /** Square, with no horizontal padding — for a single icon. */
+  iconOnly?: boolean;
+  /** Extra classes applied only while selected. */
+  selectedClassName?: string;
+  /** Extra classes applied only while unselected. */
+  unselectedClassName?: string;
+}
+
+const ToggleButtonRoot = forwardRef<View, ToggleButtonProps>(
+  (
+    {
+      children,
+      className,
+      labelClassName,
+      id,
+      selected: selectedProp,
+      defaultSelected = false,
+      onSelectedChange,
+      disabled,
+      variant,
+      size,
+      iconOnly = false,
+      selectedClassName,
+      unselectedClassName,
+      onPress,
+      ...props
+    },
+    ref
+  ) => {
+    const group = useContext(ToggleGroupContext);
+    const [internal, setInternal] = useState(defaultSelected);
+
+    /*
+     * Three sources of truth, in order: the group owns it if there is one,
+     * then a `selected` prop, then local state. The group comes first because
+     * a button inside one that also took a `selected` prop would fight it, and
+     * the group is the thing that knows about the other buttons.
+     */
+    const selected = group && id ? group.isSelected(id) : (selectedProp ?? internal);
+    const isDisabled = disabled || (group?.disabled ?? false);
+
+    const slots = toggleVariants({
+      variant: variant ?? group?.variant,
+      size: size ?? group?.size,
+      selected,
+      iconOnly,
+      disabled: isDisabled,
+    });
+
+    // Icons inside inherit this, so they follow the surface they sit on
+    // instead of every caller hardcoding a hex that is wrong in one theme.
+    const onColor = useCSSVariable('--color-accent-foreground');
+    const offColor = useCSSVariable('--color-muted-foreground');
+    const tint = selected ? onColor : offColor;
+
+    const handlePress = useCallback<NonNullable<AnimatedPressableProps['onPress']>>(
+      (event) => {
+        onPress?.(event);
+        if (group && id) {
+          group.toggle(id);
+          return;
+        }
+        const next = !selected;
+        if (selectedProp === undefined) setInternal(next);
+        onSelectedChange?.(next);
+      },
+      [onPress, group, id, selected, selectedProp, onSelectedChange]
+    );
+
+    const state = useMemo(
+      () => ({ selected, disabled: isDisabled }),
+      [selected, isDisabled]
+    );
+
+    return (
+      <ToggleStateContext.Provider value={state}>
+        <IconColorProvider color={typeof tint === 'string' ? tint : undefined}>
+          <AnimatedPressable
+            ref={ref}
+            accessibilityRole="button"
+            // `checked` is what a screen reader reads out as "on"/"off"; the
+            // selected state is the entire point of this control, so it is
+            // not left to be inferred from the colour.
+            accessibilityState={{ checked: selected, disabled: isDisabled, selected }}
+            aria-pressed={selected}
+            disabled={isDisabled}
+            onPress={handlePress}
+            className={cn(
+              slots.root({ className }),
+              selected ? selectedClassName : unselectedClassName
+            )}
+            {...props}
+          >
+            {typeof children === 'string' ? (
+              <Text className={slots.label({ className: labelClassName })}>
+                {children}
+              </Text>
+            ) : (
+              children
+            )}
+          </AnimatedPressable>
+        </IconColorProvider>
+      </ToggleStateContext.Provider>
+    );
+  }
+);
+ToggleButtonRoot.displayName = 'ToggleButton';
+
+export interface ToggleButtonLabelProps {
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * The label, when the button holds more than a string — an icon beside text.
+ * It reads the selected state itself, so composing the two does not mean
+ * threading the colour through by hand.
+ */
+function ToggleButtonLabel({ className, children }: ToggleButtonLabelProps) {
+  const { selected } = useToggleButton();
+
+  return (
+    <Text
+      className={cn(
+        'font-medium',
+        selected ? 'text-accent-foreground' : 'text-muted-foreground',
+        className
+      )}
+    >
+      {children}
+    </Text>
+  );
+}
+ToggleButtonLabel.displayName = 'ToggleButton.Label';
+
+export const ToggleButton = Object.assign(ToggleButtonRoot, {
+  Label: ToggleButtonLabel,
+});
+
+export { ToggleButtonGroup };

package/src/hooks/index.ts

@@ -20,5 +20,10 @@ export {
   type UseKeyboardAvoidanceOptions,
   type UseKeyboardAvoidanceResult,
 } from './use-keyboard-avoidance';
+export {
+  useScrollSections,
+  type UseScrollSectionsOptions,
+  type UseScrollSectionsResult,
+} from './use-scroll-sections';
 export { useDebouncedValue } from './use-debounced-value';
 export { usePrevious } from './use-previous';

package/src/hooks/use-keyboard-avoidance.ts

@@ -31,10 +31,12 @@
  * </Animated.View>
  * ```
  */
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
 import { useWindowDimensions, type LayoutChangeEvent, type View } from 'react-native';
 import {
+  measure,
   useAnimatedKeyboard,
+  useAnimatedReaction,
   useAnimatedRef,
   useAnimatedStyle,
   useSharedValue,
@@ -45,6 +47,15 @@ import {
 export interface UseKeyboardAvoidanceOptions {
   /** Set false to leave the element where it is. */
   enabled?: boolean;
+  /**
+   * Whether this element is the one that should get out of the keyboard's way.
+   *
+   * Defaults to true, which suits a composer or a toolbar: it rides the
+   * keyboard whatever is focused. A *field* wants the opposite — pass its own
+   * focus state, or every field on the screen lifts whenever any one of them
+   * is tapped, and they all arrive at the same place on top of each other.
+   */
+  active?: boolean;
   /** Gap to keep between the element's bottom edge and the keyboard. */
   offset?: number;
 }
@@ -98,6 +109,7 @@ export function hasKeyboardController(): boolean {
 
 export function useKeyboardAvoidance({
   enabled = true,
+  active = true,
   offset = 16,
 }: UseKeyboardAvoidanceOptions = {}): UseKeyboardAvoidanceResult {
   const ref = useAnimatedRef<View>();
@@ -107,26 +119,80 @@ export function useKeyboardAvoidance({
   /** Window-space bottom edge of the element with no translation applied. */
   const restingBottom = useSharedValue(0);
 
-  const measure = useCallback(() => {
+  // `active` is a plain prop and the reaction below is a worklet, so it is
+  // mirrored rather than closed over — written in an effect, because touching
+  // a shared value during render is a Reanimated strict-mode violation.
+  const isActive = useSharedValue(active && enabled);
+  useEffect(() => {
+    isActive.value = active && enabled;
+  }, [active, enabled, isActive]);
+
+  /*
+   * The resting position is taken the moment this element becomes the one that
+   * should move, on the UI thread, rather than once at layout time.
+   *
+   * Measuring at layout is wrong in two ways that both show up as "avoidance
+   * does nothing". A field inside an overlay is laid out before the overlay
+   * knows where it goes — it is parked off-screen at that point, so the stored
+   * position is a large negative number that is nonetheless non-zero, and the
+   * arithmetic below happily concludes there is no overlap. And a field that
+   * has scrolled since it was laid out is measured where it used to be.
+   *
+   * Keying off "active and the keyboard is up" rather than off the keyboard
+   * alone matters for the second field you tap: moving straight from one field
+   * to another never closes the keyboard, so there is no opening to react to,
+   * and a hook watching only the keyboard would never measure it.
+   *
+   * At the instant it becomes active the element has no translation applied,
+   * so what is measured then is the honest resting position.
+   */
+  useAnimatedReaction(
+    () => isActive.value && Math.abs(rawHeight.value) > 0,
+    (shouldLift, wasLifting) => {
+      if (shouldLift === wasLifting) return;
+
+      if (!shouldLift) {
+        // Forget it, so the next time round measures wherever the element has
+        // got to in the meantime.
+        restingBottom.value = 0;
+        return;
+      }
+
+      const frame = measure(ref);
+      if (frame && frame.height > 0 && frame.pageY >= 0) {
+        restingBottom.value = frame.pageY + frame.height;
+      }
+    }
+  );
+
+  const seed = useCallback(() => {
+    // Skipped only when a position is already known and the keyboard is up —
+    // the element is lifted then, and this would store the lifted position as
+    // the resting one. With no position yet there is no translation to undo,
+    // so measuring is safe whatever the keyboard is doing.
+    if (restingBottom.value !== 0 && Math.abs(rawHeight.value) > 0) return;
+
     ref.current?.measureInWindow((_x, y, _width, height) => {
-      if (height > 0) restingBottom.value = y + height;
+      if (height > 0 && y >= 0) restingBottom.value = y + height;
     });
-  }, [ref, restingBottom]);
+  }, [ref, rawHeight, restingBottom]);
 
   const onLayout = useCallback(
     (_event: LayoutChangeEvent) => {
+      // Covers the case the reaction above cannot: a keyboard that is already
+      // up when this element mounts, where there is no transition to react to.
       // measureInWindow is only meaningful once the view is attached and
       // positioned, which is a frame later than onLayout on both platforms.
-      requestAnimationFrame(measure);
+      requestAnimationFrame(seed);
     },
-    [measure]
+    [seed]
   );
 
   const animatedStyle = useAnimatedStyle(() => {
     // Both sources are normalised to a positive height here.
     const keyboardHeight = Math.abs(rawHeight.value);
 
-    if (!enabled || keyboardHeight === 0 || restingBottom.value === 0) {
+    if (!isActive.value || keyboardHeight === 0 || restingBottom.value === 0) {
       return { transform: [{ translateY: 0 }] };
     }
 

package/src/hooks/use-scroll-sections.ts

@@ -0,0 +1,127 @@
+/**
+ * useScrollSections — tracks which section of a scroll view you are reading.
+ *
+ * The active section is the last one whose top has passed a reading line a
+ * little way down the viewport, so the heading you have just scrolled past
+ * still counts as the one you are in.
+ *
+ * That rule alone has a hole at the end, and it is the hole every hand-rolled
+ * scrollspy has: the final section's top may never reach the reading line,
+ * because the content runs out first. Its bar then only lights up if you
+ * over-scroll past the bottom. So being at the bottom of the scroll view is
+ * treated as being in the last section outright — there is no more scrolling
+ * left with which to get there.
+ *
+ * ```tsx
+ * const sections = useScrollSections({ ids: SECTIONS.map((s) => s.id) });
+ *
+ * <ScrollView ref={sections.ref} {...sections.scrollProps}>
+ *   {SECTIONS.map((section) => (
+ *     <View key={section.id} onLayout={sections.measure(section.id)}>…</View>
+ *   ))}
+ * </ScrollView>
+ *
+ * <SectionRail value={sections.active} onValueChange={sections.scrollTo}>…</SectionRail>
+ * ```
+ */
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type {
+  LayoutChangeEvent,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+  ScrollView,
+} from 'react-native';
+
+export interface UseScrollSectionsOptions {
+  /** Section ids, in the order they appear down the page. */
+  ids: string[];
+  /**
+   * How far down the viewport the reading line sits, in pixels. Larger values
+   * switch to the next section later.
+   */
+  offset?: number;
+  /** How close to the bottom counts as "at the bottom", in pixels. */
+  endThreshold?: number;
+  /** Extra gap left above a section when scrolling to it. */
+  scrollPadding?: number;
+}
+
+export interface UseScrollSectionsResult {
+  /** Attach to the ScrollView, so `scrollTo` has something to drive. */
+  ref: React.RefObject<ScrollView | null>;
+  /** The section being read. */
+  active: string | undefined;
+  /** Spread onto the ScrollView. */
+  scrollProps: {
+    onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    scrollEventThrottle: number;
+  };
+  /** `onLayout` for a section's wrapper: `onLayout={measure(id)}`. */
+  measure: (id: string) => (event: LayoutChangeEvent) => void;
+  /** Scroll a section to the top. Pass straight to a rail's `onValueChange`. */
+  scrollTo: (id: string) => void;
+}
+
+export function useScrollSections({
+  ids,
+  offset = 120,
+  endThreshold = 24,
+  scrollPadding = 0,
+}: UseScrollSectionsOptions): UseScrollSectionsResult {
+  const ref = useRef<ScrollView | null>(null);
+  const offsets = useRef<Record<string, number>>({});
+  const [active, setActive] = useState<string | undefined>(ids[0]);
+
+  // Read inside the scroll handler, which must not be re-created on every
+  // render — a new handler each frame would defeat the throttle.
+  const idsRef = useRef(ids);
+  idsRef.current = ids;
+
+  const measure = useCallback(
+    (id: string) => (event: LayoutChangeEvent) => {
+      offsets.current[id] = event.nativeEvent.layout.y;
+    },
+    []
+  );
+
+  const onScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
+      const list = idsRef.current;
+      if (!list.length) return;
+
+      const atEnd =
+        contentOffset.y + layoutMeasurement.height >= contentSize.height - endThreshold;
+      if (atEnd) {
+        setActive(list[list.length - 1]);
+        return;
+      }
+
+      const line = contentOffset.y + offset;
+      let current = list[0];
+      for (const id of list) {
+        const top = offsets.current[id];
+        if (top !== undefined && top <= line) current = id;
+      }
+      setActive(current);
+    },
+    [offset, endThreshold]
+  );
+
+  const scrollTo = useCallback(
+    (id: string) => {
+      const top = offsets.current[id];
+      if (top === undefined) return;
+      setActive(id);
+      ref.current?.scrollTo({ y: Math.max(top - scrollPadding, 0), animated: true });
+    },
+    [scrollPadding]
+  );
+
+  const scrollProps = useMemo(
+    () => ({ onScroll, scrollEventThrottle: 16 }),
+    [onScroll]
+  );
+
+  return { ref, active, scrollProps, measure, scrollTo };
+}