panelui-native 0.89.0 → 0.91.0

package/src/hooks/index.ts

@@ -37,6 +37,7 @@ export {
 } from './use-skeleton-handoff';
 export {
   useScrollSections,
+  type ScrollSectionsPosition,
   type UseScrollSectionsOptions,
   type UseScrollSectionsResult,
 } from './use-scroll-sections';

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

@@ -23,6 +23,11 @@
  *
  * <SectionRail value={sections.active} onValueChange={sections.scrollTo}>…</SectionRail>
  * ```
+ *
+ * It also publishes the scroll position itself, as `scroll`, so a component
+ * that wants a percentage as well as a section name does not need a second
+ * scroll listener to get one. The three values are everything a fraction is
+ * made of, and they come out of the event this hook is already handling.
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type {
@@ -31,6 +36,7 @@ import type {
   NativeSyntheticEvent,
   ScrollView,
 } from 'react-native';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
 
 export interface UseScrollSectionsOptions {
   /** Section ids, in the order they appear down the page. */
@@ -46,15 +52,39 @@ export interface UseScrollSectionsOptions {
   scrollPadding?: number;
 }
 
+/**
+ * Where the scroller is, as shared values.
+ *
+ * Written from the scroll handler on the JavaScript thread, which is where the
+ * section tracking already runs — so they arrive at `scrollEventThrottle`
+ * rather than every frame, and anything reading them should ease towards the
+ * value rather than jumping to it.
+ */
+export interface ScrollSectionsPosition {
+  /** Distance scrolled, in points. */
+  offset: SharedValue<number>;
+  /** Height of the visible area. */
+  viewport: SharedValue<number>;
+  /** Total height of the content. */
+  content: SharedValue<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;
+  /**
+   * The scroll position, for anything that needs how far through the page the
+   * reader is rather than which part of it they are in.
+   */
+  scroll: ScrollSectionsPosition;
   /** Spread onto the ScrollView. */
   scrollProps: {
     onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     onMomentumScrollEnd: () => void;
+    onLayout: (event: LayoutChangeEvent) => void;
+    onContentSizeChange: (width: number, height: number) => void;
     scrollEventThrottle: number;
   };
   /** `onLayout` for a section's wrapper: `onLayout={measure(id)}`. */
@@ -81,6 +111,10 @@ export function useScrollSections({
   const settle = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [active, setActive] = useState<string | undefined>(ids[0]);
 
+  const scrollOffset = useSharedValue(0);
+  const viewport = useSharedValue(0);
+  const content = useSharedValue(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);
@@ -107,10 +141,24 @@ export function useScrollSections({
 
   const onScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
+
+      /*
+       * The position is published before the jump guard, not after it.
+       *
+       * A jump is still travel: the page really is moving under the reader, and
+       * a progress indicator that froze for the length of the animation would
+       * be reporting something that is not true. What the guard protects is the
+       * *section*, which the reader chose and which should not flicker through
+       * every heading the scroll passes on the way there.
+       */
+      scrollOffset.value = contentOffset.y;
+      viewport.value = layoutMeasurement.height;
+      content.value = contentSize.height;
+
       // Mid-jump, the position is the animation's and not the reader's.
       if (jumpingTo.current !== null) return;
 
-      const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
       const list = idsRef.current;
       if (!list.length) return;
 
@@ -129,7 +177,27 @@ export function useScrollSections({
       }
       setActive(current);
     },
-    [offset, endThreshold]
+    [offset, endThreshold, scrollOffset, viewport, content]
+  );
+
+  /*
+   * Seeded at layout as well as on scroll, so a page that has not been touched
+   * yet still reports a viewport and a content height. Without these the
+   * fraction is zero over zero until the first scroll event, and anything
+   * drawing it starts by being wrong rather than by being empty.
+   */
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      viewport.value = event.nativeEvent.layout.height;
+    },
+    [viewport]
+  );
+
+  const onContentSizeChange = useCallback(
+    (_width: number, height: number) => {
+      content.value = height;
+    },
+    [content]
   );
 
   const scrollTo = useCallback(
@@ -168,9 +236,20 @@ export function useScrollSections({
   );
 
   const scrollProps = useMemo(
-    () => ({ onScroll, onMomentumScrollEnd, scrollEventThrottle: 16 }),
-    [onScroll, onMomentumScrollEnd]
+    () => ({
+      onScroll,
+      onMomentumScrollEnd,
+      onLayout,
+      onContentSizeChange,
+      scrollEventThrottle: 16,
+    }),
+    [onScroll, onMomentumScrollEnd, onLayout, onContentSizeChange]
+  );
+
+  const scroll = useMemo<ScrollSectionsPosition>(
+    () => ({ offset: scrollOffset, viewport, content }),
+    [scrollOffset, viewport, content]
   );
 
-  return { ref, active, scrollProps, measure, scrollTo };
+  return { ref, active, scroll, scrollProps, measure, scrollTo };
 }

package/src/index.ts

@@ -22,7 +22,16 @@ export { Portal, PortalHost, PortalProvider } from './primitives/portal';
 export { Scrim, hasBlur, type ScrimProps } from './primitives/scrim';
 // The material iOS draws its floating controls in, with a solid fallback where
 // there is none. Public so a surface of your own gets the same treatment.
-export { Glass, hasGlass, type GlassProps, type GlassVariant, type GlassRadius } from './primitives/glass';
+export {
+  Glass,
+  GlassContainer,
+  hasGlass,
+  useGlassMaterial,
+  type GlassProps,
+  type GlassContainerProps,
+  type GlassVariant,
+  type GlassRadius,
+} from './primitives/glass';
 export { Text, type TextProps } from './primitives/text';
 export { Collapse, type CollapseProps } from './primitives/collapse';
 export {
@@ -218,6 +227,9 @@ export {
   type FabPlacement,
   type FabSize,
   type FabVariant,
+  type FabGroupLayout,
+  type FabMenuAppearance,
+  type FabMenuIconPlacement,
 } from './components/fab';
 export {
   Flow,
@@ -386,6 +398,14 @@ export {
   type SectionRailPlacement,
   type SectionRailAlign,
 } from './components/section-rail';
+export {
+  SectionProgress,
+  type SectionProgressProps,
+  type SectionProgressItemProps,
+  type SectionProgressPlacement,
+  type SectionProgressColor,
+  type SectionProgressScroll,
+} from './components/section-progress';
 export {
   Tabs,
   type TabsProps,

package/src/native/index.ts

@@ -182,6 +182,27 @@ interface SwiftUIModifiers {
    * changing any code on a report of "the colour did nothing".
    */
   presentationBackground: (color: string) => unknown;
+  /**
+   * Greys a control out and stops it answering.
+   *
+   * Optional because the module is cast whole rather than feature-checked, and
+   * an older `@expo/ui` without it would otherwise be a crash instead of a
+   * menu row that is merely still tappable. Call it through a guard.
+   */
+  disabled?: (disabled: boolean) => unknown;
+  /**
+   * Fires when the view is put on screen, and when it is taken off again.
+   *
+   * The way to find out that a menu has opened. SwiftUI builds a menu's
+   * content only once it is presented, so an item inside one appears exactly
+   * when the menu does — which is the only signal the control gives, since it
+   * owns its open state and reports nothing about it.
+   *
+   * Optional for the same reason as `disabled`: the module is cast whole, and
+   * a version without these should lose the backdrop rather than crash.
+   */
+  onAppear?: (handler: () => void) => unknown;
+  onDisappear?: (handler: () => void) => unknown;
 }
 
 /**
@@ -241,6 +262,131 @@ export function getSwiftUI(): SwiftUIComponents | null {
   return swiftUI;
 }
 
+/**
+ * A hosting boundary, as both toolkits declare it. The same three props matter
+ * on either side — see `NativeUIModule.Host` above for what each one costs.
+ */
+type NativeHostComponent = ComponentType<{
+  children?: ReactNode;
+  matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
+  ignoreSafeArea?: 'all' | 'container' | 'keyboard';
+  colorScheme?: 'light' | 'dark';
+  style?: unknown;
+}>;
+
+type RNHostComponent = ComponentType<{
+  children?: ReactNode;
+  matchContents?: boolean;
+  style?: unknown;
+}>;
+
+/**
+ * SwiftUI's menu, and the button that fills a row of it.
+ *
+ * Separate from `getSwiftUI` on purpose: that resolver refuses a module with no
+ * popover in it, and a version that ships one control but not the other would
+ * take the menu down with it. Each native path asks only for what it needs.
+ */
+interface SwiftUIMenuComponents {
+  Host: NativeHostComponent;
+  RNHostView: RNHostComponent;
+  /**
+   * `label` takes a React element as well as a string — the element is passed
+   * through a native slot and becomes the thing you press. That is what lets
+   * the trigger stay a real Fab rather than a platform button wearing its name.
+   */
+  Menu: ComponentType<{
+    label?: ReactNode;
+    children?: ReactNode;
+    modifiers?: unknown[];
+  }>;
+  Button: ComponentType<{
+    label?: string;
+    systemImage?: string;
+    role?: 'default' | 'cancel' | 'destructive';
+    onPress?: () => void;
+    modifiers?: unknown[];
+  }>;
+}
+
+let swiftUIMenuResolved = false;
+let swiftUIMenu: SwiftUIMenuComponents | null = null;
+
+export function getSwiftUIMenu(): SwiftUIMenuComponents | null {
+  if (swiftUIMenuResolved) return swiftUIMenu;
+  swiftUIMenuResolved = true;
+
+  if (Platform.OS !== 'ios') return null;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const module = require('@expo/ui/swift-ui') as Partial<SwiftUIMenuComponents>;
+    swiftUIMenu =
+      module.Host && module.RNHostView && module.Menu && module.Button
+        ? (module as SwiftUIMenuComponents)
+        : null;
+  } catch {
+    swiftUIMenu = null;
+  }
+
+  return swiftUIMenu;
+}
+
+/**
+ * Compose's dropdown menu — the same instruction, answered by a different
+ * control.
+ *
+ * It is not the shape SwiftUI's menu is. This one is controlled: it takes the
+ * open state rather than owning it, and it splits the trigger and the items
+ * into named slots instead of reading the label off a prop. Both differences
+ * reach the caller, so they are written out here rather than smoothed over.
+ */
+interface ComposeMenuComponents {
+  Host: NativeHostComponent;
+  RNHostView: RNHostComponent;
+  Text: ComponentType<{ children?: ReactNode; color?: string }>;
+  DropdownMenu: ComponentType<{
+    children?: ReactNode;
+    expanded?: boolean;
+    onDismissRequest?: () => void;
+  }> & {
+    Trigger: ComponentType<{ children?: ReactNode }>;
+    Items: ComponentType<{ children?: ReactNode }>;
+  };
+  DropdownMenuItem: ComponentType<{
+    children?: ReactNode;
+    enabled?: boolean;
+    onClick?: () => void;
+    elementColors?: { textColor?: string; disabledTextColor?: string };
+  }> & {
+    Text: ComponentType<{ children?: ReactNode }>;
+    LeadingIcon: ComponentType<{ children?: ReactNode }>;
+  };
+}
+
+let composeMenuResolved = false;
+let composeMenu: ComposeMenuComponents | null = null;
+
+export function getComposeMenu(): ComposeMenuComponents | null {
+  if (composeMenuResolved) return composeMenu;
+  composeMenuResolved = true;
+
+  if (Platform.OS !== 'android') return null;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const module = require('@expo/ui/jetpack-compose') as Partial<ComposeMenuComponents>;
+    composeMenu =
+      module.Host && module.RNHostView && module.DropdownMenu && module.DropdownMenuItem
+        ? (module as ComposeMenuComponents)
+        : null;
+  } catch {
+    composeMenu = null;
+  }
+
+  return composeMenu;
+}
+
 let modifiersResolved = false;
 let modifiers: SwiftUIModifiers | null = null;
 

package/src/primitives/glass.tsx

@@ -36,13 +36,18 @@
  * its own corners — clipping a square one to a rounded parent throws away the
  * lit edge that makes it read as glass.
  *
+ * `interactive` is the one exception to the layer: the platform only animates
+ * the glass under a touch it can see, so with it on the material is the box
+ * and the children are hosted inside it, in normal flow. Reach for it when
+ * the glass *is* the button.
+ *
  * ## Do not fade it
  *
  * Setting `opacity` to `0` on the material or on anything above it stops it
  * rendering at all, and it does not come back when the opacity does. Move it,
  * or unmount it; never animate it out.
  */
-import type { ComponentType, ReactNode } from 'react';
+import { forwardRef, type ComponentType, type ReactNode } from 'react';
 import { Platform, StyleSheet, View, type StyleProp, type ViewProps, type ViewStyle } from 'react-native';
 import { useThemeMode } from '../theme/use-theme';
 import { cn } from '../utils/cn';
@@ -71,18 +76,27 @@ function shapeOf(radius: GlassRadius | undefined) {
   };
 }
 
-interface GlassViewProps {
+interface GlassViewProps extends ViewProps {
   glassEffectStyle?: GlassVariant | 'none';
   tintColor?: string;
+  isInteractive?: boolean;
   colorScheme?: 'auto' | 'light' | 'dark';
   style?: StyleProp<ViewStyle>;
-  pointerEvents?: ViewProps['pointerEvents'];
   children?: ReactNode;
 }
 
+interface GlassContainerViewProps extends ViewProps {
+  spacing?: number;
+  ref?: React.Ref<View>;
+}
+
+interface GlassModule {
+  GlassView: ComponentType<GlassViewProps>;
+  GlassContainer: ComponentType<GlassContainerViewProps>;
+}
+
 /**
- * `expo-glass-effect`'s GlassView, or null when the material cannot be drawn
- * here.
+ * `expo-glass-effect`, or null when the material cannot be drawn here.
  *
  * Resolved once at module load, behind three gates that all have to pass. The
  * package is optional, so the require can fail; the API is missing from some
@@ -91,7 +105,7 @@ interface GlassViewProps {
  * cheaper than a try/catch on every render, and there is no answer that can
  * change while the process is alive.
  */
-const GlassView: ComponentType<GlassViewProps> | null = (() => {
+const glassModule: GlassModule | null = (() => {
   if (Platform.OS !== 'ios') return null;
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -102,12 +116,15 @@ const GlassView: ComponentType<GlassViewProps> | null = (() => {
     if (typeof mod?.isLiquidGlassAvailable === 'function' && !mod.isLiquidGlassAvailable()) {
       return null;
     }
-    return (mod?.GlassView as ComponentType<GlassViewProps>) ?? null;
+    return mod?.GlassView ? (mod as GlassModule) : null;
   } catch {
     return null;
   }
 })();
 
+const GlassView = glassModule?.GlassView ?? null;
+const GlassContainerView = glassModule?.GlassContainer ?? null;
+
 /**
  * True when the real material can be drawn — for a caller that wants to know
  * before it commits to a look. It says nothing about Reduce Transparency, which
@@ -115,6 +132,21 @@ const GlassView: ComponentType<GlassViewProps> | null = (() => {
  */
 export const hasGlass = GlassView !== null;
 
+/**
+ * Whether the material will actually be drawn right now: the API is present
+ * *and* the user has not switched Reduce Transparency on.
+ *
+ * For a component that changes shape around the material — dropping a fill, a
+ * border or a shadow the glass replaces — so that it makes the same decision
+ * `Glass` makes and never strips the fill while leaving nothing behind it.
+ */
+export function useGlassMaterial(): boolean {
+  const reduceTransparency = useReduceTransparency();
+  // Not knowing yet counts as "do not draw it": the material arriving a frame
+  // late is invisible, and one flashing at somebody who opted out is not.
+  return hasGlass && reduceTransparency === false;
+}
+
 export interface GlassProps extends ViewProps {
   /**
    * How much of what is behind shows through. `regular` is the everyday
@@ -129,6 +161,16 @@ export interface GlassProps extends ViewProps {
    * to a rounded parent throws away the lit edge that makes it read as glass.
    */
   radius?: GlassRadius;
+  /**
+   * Let the material answer touch the way the platform's own controls do:
+   * it brightens and swells under the finger and the highlight follows it.
+   *
+   * For a material that *is* a button. The platform only tracks touches that
+   * land inside the glass view, so with this on the content is hosted inside
+   * the material rather than above it — a pressable written as a child still
+   * gets its press, and the glass reacts to the same touch.
+   */
+  interactive?: boolean;
   /** Applied only when the material cannot be drawn. Give it a real surface. */
   fallbackClassName?: string;
   className?: string;
@@ -138,13 +180,13 @@ export function Glass({
   variant = 'regular',
   tint,
   radius,
+  interactive = false,
   fallbackClassName = 'bg-card',
   className,
   children,
   style,
   ...props
 }: GlassProps) {
-  const reduceTransparency = useReduceTransparency();
   /*
    * Which appearance the material is drawn in, from the app's theme rather
    * than the phone's.
@@ -155,11 +197,33 @@ export function Glass({
    * appearance never moved.
    */
   const { mode } = useThemeMode();
-  // Not knowing yet counts as "do not draw it": the material arriving a frame
-  // late is invisible, and one flashing at somebody who opted out is not.
-  const material = GlassView !== null && reduceTransparency === false;
+  const material = useGlassMaterial();
   const shape = shapeOf(radius);
 
+  /*
+   * Interactive, the material is the box rather than a layer in it. The
+   * platform only tracks a touch that lands inside the glass view, so the
+   * content has to be hosted in it — and hosted in normal flow, so that a
+   * box sized by its content still is. A layer pinned to the box's edges
+   * could not size it, and a button as wide as its label would collapse to
+   * its minimum. The classes go on a view inside, because the native view is
+   * not a styled one; only the positional style stays on the outside.
+   */
+  if (material && GlassView && interactive) {
+    return (
+      <GlassView
+        glassEffectStyle={variant}
+        tintColor={tint}
+        isInteractive
+        colorScheme={mode}
+        style={[shape, style]}
+        {...props}
+      >
+        <View className={className}>{children}</View>
+      </GlassView>
+    );
+  }
+
   return (
     <View
       className={cn('overflow-hidden', material ? null : fallbackClassName, className)}
@@ -181,3 +245,44 @@ export function Glass({
 }
 
 Glass.displayName = 'Glass';
+
+export interface GlassContainerProps extends ViewProps {
+  /**
+   * How close two pieces of glass have to be before they merge, in points.
+   * Inside it their edges flow into one another; a piece moving past
+   * another blends with it and pulls free as it leaves.
+   */
+  spacing?: number;
+  className?: string;
+}
+
+/**
+ * Lets the glass inside it merge.
+ *
+ * On its own each piece of the material is a separate object with its own
+ * lit edge. Inside a container, pieces within `spacing` of each other flow
+ * together — which is what makes a button that opens into other buttons look
+ * like one thing dividing rather than several things arriving. A plain view
+ * wherever the material is not drawn, so it can be written unconditionally.
+ */
+export const GlassContainer = forwardRef<View, GlassContainerProps>(
+  ({ spacing, className, style, children, ...props }, ref) => {
+    const material = useGlassMaterial();
+    if (material && GlassContainerView) {
+      // The native container is not a styled view, so the classes go on a
+      // view inside it and only the positional style stays on the outside.
+      return (
+        <GlassContainerView ref={ref} spacing={spacing} style={style} {...props}>
+          <View className={className}>{children}</View>
+        </GlassContainerView>
+      );
+    }
+    return (
+      <View ref={ref} className={className} style={style} {...props}>
+        {children}
+      </View>
+    );
+  }
+);
+
+GlassContainer.displayName = 'GlassContainer';