@rific/auto-paper 0.12.3 → 0.13.0

package/dist/index.mjs

@@ -601,11 +601,13 @@ var BlurModuleContext = createContext2(void 0);
 var useBlurModule = () => useContext3(BlurModuleContext);
 var ReanimatedModuleContext = createContext2(void 0);
 var useReanimatedModule = () => useContext3(ReanimatedModuleContext);
-function Provider({ children, defaults, expoBlur, fontFamily, initialValue, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }) {
-  return /* @__PURE__ */ jsx4(ThemeSettingsProvider, { initialValue, onChange, children: /* @__PURE__ */ jsx4(ThemeProviderBody, { defaults, expoBlur, fontFamily, navigationBar, onNavBarChange, onReady, reanimated, statusBarProps, style, children }) });
+var MaskedViewModuleContext = createContext2(void 0);
+var useMaskedViewModule = () => useContext3(MaskedViewModuleContext);
+function Provider({ children, defaults, expoBlur, fontFamily, initialValue, maskedView, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }) {
+  return /* @__PURE__ */ jsx4(ThemeSettingsProvider, { initialValue, onChange, children: /* @__PURE__ */ jsx4(ThemeProviderBody, { defaults, expoBlur, fontFamily, maskedView, navigationBar, onNavBarChange, onReady, reanimated, statusBarProps, style, children }) });
 }
 var ThemeSettingsProvider = themeSettingsProvider;
-function ThemeProviderBody({ children, defaults, expoBlur, fontFamily, navigationBar, onNavBarChange, onReady, reanimated, statusBarProps, style }) {
+function ThemeProviderBody({ children, defaults, expoBlur, fontFamily, maskedView, navigationBar, onNavBarChange, onReady, reanimated, statusBarProps, style }) {
   const { settings } = useThemeSettingsInternal();
   const computedTheme = useComputedTheme(settings.appearance, settings.color, settings.harmony);
   const theme = useMemo(() => {
@@ -623,7 +625,7 @@ function ThemeProviderBody({ children, defaults, expoBlur, fontFamily, navigatio
   if (!theme) return null;
   return /* @__PURE__ */ jsxs2(PaperProvider, { theme, children: [
     /* @__PURE__ */ jsx4(StatusBar2, { backgroundColor: theme.colors.background, barStyle: theme.dark ? "light-content" : "dark-content", ...statusBarProps }),
-    /* @__PURE__ */ jsx4(PaperDefaultsContext.Provider, { value: defaults ?? {}, children: /* @__PURE__ */ jsx4(NavBarContext.Provider, { value: { navigationBar, onNavBarChange }, children: /* @__PURE__ */ jsx4(BlurModuleContext.Provider, { value: expoBlur, children: /* @__PURE__ */ jsx4(ReanimatedModuleContext.Provider, { value: reanimated, children: /* @__PURE__ */ jsx4(Portal.Host, { children: /* @__PURE__ */ jsx4(View, { style: [styles.flex, { backgroundColor: theme.colors.background }, style], children }) }) }) }) }) })
+    /* @__PURE__ */ jsx4(PaperDefaultsContext.Provider, { value: defaults ?? {}, children: /* @__PURE__ */ jsx4(NavBarContext.Provider, { value: { navigationBar, onNavBarChange }, children: /* @__PURE__ */ jsx4(BlurModuleContext.Provider, { value: expoBlur, children: /* @__PURE__ */ jsx4(ReanimatedModuleContext.Provider, { value: reanimated, children: /* @__PURE__ */ jsx4(MaskedViewModuleContext.Provider, { value: maskedView, children: /* @__PURE__ */ jsx4(Portal.Host, { children: /* @__PURE__ */ jsx4(View, { style: [styles.flex, { backgroundColor: theme.colors.background }, style], children }) }) }) }) }) }) })
   ] });
 }
 var styles = StyleSheet.create({
@@ -642,7 +644,12 @@ var blursOnAndroid = ({ blurMethod, blurTarget, experimentalBlurMethod }) => {
 };
 var ELEVATION_OPACITY = { 0: 0, 1: 0.05, 2: 0.08, 3: 0.11, 4: 0.12, 5: 0.14 };
 var VARIANT_TINT_OPACITY = { light: 0.12, dark: 0.18 };
-var BlurView = ({ blur = true, children, elevation, style, tintColor, tintOpacity, variant = "surface", ...props }) => {
+var getWebBlurStyle = (intensity, dark) => {
+  const amount = Math.min(intensity, 100);
+  const filter = `saturate(180%) blur(${amount * 0.2}px)`;
+  return { backdropFilter: filter, backgroundColor: `rgba(${dark ? "25,25,25" : "249,249,249"},${amount / 100 * 0.78})`, WebkitBackdropFilter: filter };
+};
+var BlurView = ({ blur = true, blurMethod, blurReductionFactor, blurTarget, children, elevation, experimentalBlurMethod, intensity, style, tint: _tint, tintColor, tintOpacity, variant = "surface", ...props }) => {
   const { dark, colors } = useTheme2();
   const { settings } = useContext4(ThemeSettingsContext);
   const expoBlur = useBlurModule();
@@ -651,13 +658,13 @@ var BlurView = ({ blur = true, children, elevation, style, tintColor, tintOpacit
   const resolvedTintColor = tintColor ?? variantColor ?? (elevation !== void 0 ? colors.primary : void 0);
   const resolvedTintOpacity = tintOpacity ?? (tintColor ? dark ? 0.24 : 0.16 : variantColor ? dark ? VARIANT_TINT_OPACITY.dark : VARIANT_TINT_OPACITY.light : elevation !== void 0 ? ELEVATION_OPACITY[elevation] : 0);
   const tint = resolvedTintColor && resolvedTintOpacity > 0 ? /* @__PURE__ */ jsx5(View2, { style: [StyleSheet2.absoluteFill, { backgroundColor: resolvedTintColor, opacity: resolvedTintOpacity }] }) : null;
-  if (blur && expoBlur && (Platform.OS !== "android" || blursOnAndroid(props)))
-    return /* @__PURE__ */ jsxs3(expoBlur.BlurView, { ...props, tint: dark ? "dark" : "light", style, children: [
-      /* @__PURE__ */ jsx5(View2, { style: [StyleSheet2.absoluteFill, { backgroundColor: surfaceColor, opacity: settings.blurTint }] }),
-      tint,
-      children
-    ] });
-  return /* @__PURE__ */ jsxs3(View2, { ...props, style: [{ backgroundColor: surfaceColor }, style], children: [
+  const blurProps = { blurMethod, blurReductionFactor, blurTarget, experimentalBlurMethod, intensity };
+  const blurs = blur && expoBlur !== void 0 && (Platform.OS !== "android" || blursOnAndroid(blurProps));
+  const web = Platform.OS === "web";
+  const containerStyle = !blurs ? [{ backgroundColor: surfaceColor }, style] : web ? [style, getWebBlurStyle(intensity ?? 50, dark)] : style;
+  return /* @__PURE__ */ jsxs3(View2, { ...props, style: containerStyle, children: [
+    blurs && !web ? /* @__PURE__ */ jsx5(expoBlur.BlurView, { ...blurProps, style: StyleSheet2.absoluteFill, tint: dark ? "dark" : "light" }) : null,
+    blurs ? /* @__PURE__ */ jsx5(View2, { style: [StyleSheet2.absoluteFill, { backgroundColor: surfaceColor, opacity: settings.blurTint }] }) : null,
     tint,
     children
   ] });
@@ -950,22 +957,104 @@ function FAB(props) {
   return /* @__PURE__ */ jsx14(PaperFAB, { ...defaults.FAB, ...props });
 }
 
+// src/components/FadingScrollView.tsx
+import { useCallback as useCallback2, useRef as useRef2, useState as useState6 } from "react";
+import { Platform as Platform4, ScrollView, StyleSheet as StyleSheet6, View as View6 } from "react-native";
+import { jsx as jsx15, jsxs as jsxs7 } from "react/jsx-runtime";
+var SCROLL_FADE_HEIGHT = 24;
+function FadingScrollView({ style, fadeHeight = SCROLL_FADE_HEIGHT, onScroll, onLayout, onContentSizeChange, scrollEventThrottle = 16, children, ...rest }) {
+  const MaskedView = useMaskedViewModule();
+  const sizes = useRef2({ viewport: 0, content: 0, offset: 0 });
+  const [edges, setEdges] = useState6(NO_EDGES);
+  const update = useCallback2(() => {
+    const { viewport, content, offset } = sizes.current;
+    const above = offset > 1;
+    const below = content - viewport - offset > 1;
+    setEdges((prev) => prev.above === above && prev.below === below ? prev : { above, below });
+  }, []);
+  const scroll = /* @__PURE__ */ jsx15(
+    ScrollView,
+    {
+      ...rest,
+      style: styles5.fill,
+      scrollEventThrottle,
+      onScroll: (e) => {
+        sizes.current.offset = e.nativeEvent.contentOffset.y;
+        update();
+        onScroll?.(e);
+      },
+      onLayout: (e) => {
+        sizes.current.viewport = e.nativeEvent.layout.height;
+        update();
+        onLayout?.(e);
+      },
+      onContentSizeChange: (width, height) => {
+        sizes.current.content = height;
+        update();
+        onContentSizeChange?.(width, height);
+      },
+      children
+    }
+  );
+  if (Platform4.OS === "web") return /* @__PURE__ */ jsx15(View6, { style: [styles5.box, style, (edges.above || edges.below) && webFadeStyle(fadeHeight, edges)], children: scroll });
+  if (!MaskedView) return /* @__PURE__ */ jsx15(View6, { style: [styles5.box, style], children: scroll });
+  return /* @__PURE__ */ jsx15(
+    MaskedView,
+    {
+      style: [styles5.box, style],
+      maskElement: /* @__PURE__ */ jsxs7(View6, { style: styles5.fill, children: [
+        /* @__PURE__ */ jsx15(View6, { style: [{ height: fadeHeight }, edges.above ? FADE_IN_BAND : styles5.opaque] }),
+        /* @__PURE__ */ jsx15(View6, { style: styles5.fillOpaque }),
+        /* @__PURE__ */ jsx15(View6, { style: [{ height: fadeHeight }, edges.below ? FADE_OUT_BAND : styles5.opaque] })
+      ] }),
+      children: scroll
+    }
+  );
+}
+var FADE_IN_BAND = { experimental_backgroundImage: "linear-gradient(transparent, #000)" };
+var FADE_OUT_BAND = { experimental_backgroundImage: "linear-gradient(#000, transparent)" };
+var NO_EDGES = { above: false, below: false };
+function webFadeStyle(fadeHeight, edges) {
+  const top = edges.above ? `transparent 0, #000 ${fadeHeight}px` : "#000 0";
+  const bottom = edges.below ? `#000 calc(100% - ${fadeHeight}px), transparent 100%` : "#000 100%";
+  const mask = `linear-gradient(to bottom, ${top}, ${bottom})`;
+  return { maskImage: mask, WebkitMaskImage: mask };
+}
+var styles5 = StyleSheet6.create({
+  // A plain ScrollView's own flex defaults, so it sizes the same in its parent.
+  box: {
+    flexGrow: 1,
+    flexShrink: 1
+  },
+  fill: {
+    flexGrow: 1,
+    flexShrink: 1
+  },
+  fillOpaque: {
+    backgroundColor: "#000",
+    flexGrow: 1
+  },
+  opaque: {
+    backgroundColor: "#000"
+  }
+});
+
 // src/components/IconButton.tsx
 import { IconButton as PaperIconButton, useTheme as useTheme8 } from "react-native-paper";
-import { jsx as jsx15 } from "react/jsx-runtime";
+import { jsx as jsx16 } from "react/jsx-runtime";
 function IconButton({ variant, iconColor, containerColor, ...props }) {
   const defaults = usePaperDefaults();
   const { colors } = useTheme8();
   const variantContainerColor = variant === "primary" ? colors.primaryContainer : variant === "secondary" ? colors.secondaryContainer : variant === "tertiary" ? colors.tertiaryContainer : variant === "surface" ? colors.surface : void 0;
   const variantIconColor = variant === "primary" ? colors.onPrimaryContainer : variant === "secondary" ? colors.onSecondaryContainer : variant === "tertiary" ? colors.onTertiaryContainer : variant === "surface" ? colors.onSurface : void 0;
-  return /* @__PURE__ */ jsx15(PaperIconButton, { ...defaults.IconButton, containerColor: containerColor ?? variantContainerColor, iconColor: iconColor ?? variantIconColor, ...props });
+  return /* @__PURE__ */ jsx16(PaperIconButton, { ...defaults.IconButton, containerColor: containerColor ?? variantContainerColor, iconColor: iconColor ?? variantIconColor, ...props });
 }
 
 // src/components/Menu.tsx
-import { useEffect as useEffect5, useState as useState6 } from "react";
-import { Animated as Animated2, Easing as Easing2, Platform as Platform4, StyleSheet as StyleSheet6 } from "react-native";
+import { useEffect as useEffect5, useState as useState7 } from "react";
+import { Animated as Animated2, Easing as Easing2, Platform as Platform5, StyleSheet as StyleSheet7 } from "react-native";
 import { Menu as PaperMenu, useTheme as useTheme9 } from "react-native-paper";
-import { jsx as jsx16 } from "react/jsx-runtime";
+import { jsx as jsx17 } from "react/jsx-runtime";
 var ANIMATION_DURATION2 = 250;
 var EASING = Easing2.bezier(0.4, 0, 0.2, 1);
 var DEFAULT_ELEVATION = 2;
@@ -974,24 +1063,24 @@ var SHADOW_RADIUS = [0, 3, 6, 8, 10, 12];
 var AnimatedBlurView2 = Animated2.createAnimatedComponent(BlurView);
 var FadingBlurView = ({ blur, children, elevation, theme: themeOverrides, visible }) => {
   const { animation, roundness } = useTheme9(themeOverrides);
-  const [opacity] = useState6(() => new Animated2.Value(0));
-  const [closing, setClosing] = useState6(false);
+  const [opacity] = useState7(() => new Animated2.Value(0));
+  const [closing, setClosing] = useState7(false);
   if (!visible && !closing) setClosing(true);
   useEffect5(() => {
     Animated2.timing(opacity, { duration: animation.scale * ANIMATION_DURATION2, easing: EASING, toValue: closing ? 0 : 1, useNativeDriver: false }).start();
   }, [animation.scale, closing, opacity]);
   const shadow = elevation > 0 ? { shadowColor: "#000000", shadowOffset: { height: SHADOW_HEIGHT[elevation], width: 0 }, shadowOpacity: 0.3, shadowRadius: SHADOW_RADIUS[elevation] } : null;
-  return /* @__PURE__ */ jsx16(AnimatedBlurView2, { blur, style: [{ borderRadius: roundness, opacity }, shadow], children });
+  return /* @__PURE__ */ jsx17(AnimatedBlurView2, { blur, style: [{ borderRadius: roundness, opacity }, shadow], children });
 };
 var MenuComponent = ({ blur: blurProp, children, ...props }) => {
   const blur = useBlur(blurProp);
-  const web = Platform4.OS === "web";
-  return /* @__PURE__ */ jsx16(PaperMenu, { ...props, contentStyle: [styles5.content, web && styles5.webSurface, props.contentStyle], children: web ? /* @__PURE__ */ jsx16(FadingBlurView, { blur, elevation: props.mode === "flat" ? 0 : props.elevation ?? DEFAULT_ELEVATION, theme: props.theme, visible: props.visible, children }) : /* @__PURE__ */ jsx16(BlurView, { blur, children }) });
+  const web = Platform5.OS === "web";
+  return /* @__PURE__ */ jsx17(PaperMenu, { ...props, contentStyle: [styles6.content, web && styles6.webSurface, props.contentStyle], children: web ? /* @__PURE__ */ jsx17(FadingBlurView, { blur, elevation: props.mode === "flat" ? 0 : props.elevation ?? DEFAULT_ELEVATION, theme: props.theme, visible: props.visible, children }) : /* @__PURE__ */ jsx17(BlurView, { blur, children }) });
 };
 var Menu = Object.assign(MenuComponent, {
   Item: PaperMenu.Item
 });
-var styles5 = StyleSheet6.create({
+var styles6 = StyleSheet7.create({
   content: { backgroundColor: "transparent", paddingVertical: 0 },
   webSurface: { opacity: 1, shadowOpacity: 0 }
 });
@@ -999,10 +1088,10 @@ var styles5 = StyleSheet6.create({
 // src/components/TextInput.tsx
 import { forwardRef } from "react";
 import { TextInput as PaperTextInput } from "react-native-paper";
-import { jsx as jsx17 } from "react/jsx-runtime";
+import { jsx as jsx18 } from "react/jsx-runtime";
 var TextInput = forwardRef(function TextInput2(props, ref) {
   const defaults = usePaperDefaults();
-  return /* @__PURE__ */ jsx17(PaperTextInput, { ref, ...defaults.TextInput, ...props });
+  return /* @__PURE__ */ jsx18(PaperTextInput, { ref, ...defaults.TextInput, ...props });
 });
 
 // src/redux/themeSlice.ts
@@ -1130,11 +1219,13 @@ export {
   ColorPicker,
   Dialog,
   FAB,
+  FadingScrollView,
   HarmonyPicker,
   IconButton,
   Menu,
   PalettePicker,
   Provider,
+  SCROLL_FADE_HEIGHT,
   SEMANTIC_BASE_COLORS,
   TextInput,
   ThemeSettingsContext,
@@ -1162,6 +1253,7 @@ export {
   useBlur,
   useBlurModule,
   useComputedTheme,
+  useMaskedViewModule,
   useNavBarContext,
   usePaperDefaults,
   useReanimatedModule,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rific/auto-paper",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Adaptive react-native-paper theming: triadic palette from a seed color + system/light/dark appearance",
   "keywords": [
     "react-native",
@@ -71,6 +71,7 @@
     "@infinitetoken/eslint-config": "0.2.0",
     "@infinitetoken/jest-config": "^0.4.0",
     "@infinitetoken/tsconfig": "^0.5.0",
+    "@react-native-masked-view/masked-view": "^0.3.2",
     "@reduxjs/toolkit": "^2.0.0",
     "@rific/core": "^0.2.0",
     "@testing-library/dom": "^10.4.1",
@@ -94,6 +95,7 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@react-native-masked-view/masked-view": ">=0.3.0",
     "@rific/core": ">=0.1.1",
     "expo-blur": ">=56.0.0",
     "expo-navigation-bar": ">=56.0.0",
@@ -103,6 +105,9 @@
     "react-native-safe-area-context": "*"
   },
   "peerDependenciesMeta": {
+    "@react-native-masked-view/masked-view": {
+      "optional": true
+    },
     "expo-blur": {
       "optional": true
     },

package/src/ThemeProvider.tsx

@@ -4,6 +4,7 @@ import { configureFonts, Portal, Provider as PaperProvider } from 'react-native-
 
 import type { ExpoBlurModule } from './components/BlurView'
 import type { ReanimatedModule } from './components/Dialog'
+import type { MaskedViewModule } from './components/FadingScrollView'
 import type { ExpoNavigationBarModule } from './navigation-bar'
 import { type PaperDefaults, PaperDefaultsContext } from './PaperDefaultsContext'
 import { type ThemeSettings, themeSettingsProvider, useThemeSettingsInternal } from './ThemeSettingsContext'
@@ -24,18 +25,23 @@ export const useBlurModule = () => useContext(BlurModuleContext)
 const ReanimatedModuleContext = createContext<ReanimatedModule | undefined>(undefined)
 export const useReanimatedModule = () => useContext(ReanimatedModuleContext)
 
+const MaskedViewModuleContext = createContext<MaskedViewModule | undefined>(undefined)
+export const useMaskedViewModule = () => useContext(MaskedViewModuleContext)
+
 export type ProviderProps = {
   children: ReactNode
   defaults?: PaperDefaults
   /** Injects expo-blur for `<BlurView>`. Pass `import * as ExpoBlur from 'expo-blur'`; omit to always render BlurView's solid fallback. */
   expoBlur?: ExpoBlurModule
   /** Applied to every Paper typography variant (bodyLarge, headlineMedium, labelSmall, ...) via
-   * `configureFonts`'s flat-config mode — each variant keeps its own MD3 fontSize/lineHeight/weight,
+   * `configureFonts`'s flat-config mode - each variant keeps its own MD3 fontSize/lineHeight/weight,
    * only fontFamily changes. The one-line way to reskin an app's whole text to a custom typeface,
    * instead of passing `fontFamily` to every individual Text/TextInput/Button across the app. Omit
    * to keep each platform's system font (MD3's own default). */
   fontFamily?: string
   initialValue?: Partial<ThemeSettings>
+  /** Injects @react-native-masked-view/masked-view so `<FadingScrollView>` can fade its content out above a pinned footer on iOS and Android. Pass `import MaskedView from '@react-native-masked-view/masked-view'`; omit to have it scroll without the fade there (web never needs it). */
+  maskedView?: MaskedViewModule
   /** Injects expo-navigation-bar so the Android nav bar icon style auto-syncs with the theme. Pass `import * as ExpoNavigationBar from 'expo-navigation-bar'`; omit (and don't pass onNavBarChange) to skip nav bar syncing entirely. */
   navigationBar?: ExpoNavigationBarModule
   onChange?: (settings: ThemeSettings) => void
@@ -48,15 +54,15 @@ export type ProviderProps = {
 }
 
 // createSettingsContext's generated Provider only exposes `settings` to descendants (via its
-// generated useSettings()) — it can't itself also compute the theme/gate mounting on it being
+// generated useSettings()) - it can't itself also compute the theme/gate mounting on it being
 // ready, since that logic needs `settings` in scope. Provider (below) is just this thin outer
 // wrapper for the settings half; ThemeProviderBody (an actual descendant, reached via
 // useThemeSettingsInternal()) does all the theme-computation/gating work the single combined
 // component used to do directly.
-export function Provider({ children, defaults, expoBlur, fontFamily, initialValue, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }: ProviderProps) {
+export function Provider({ children, defaults, expoBlur, fontFamily, initialValue, maskedView, navigationBar, onChange, onNavBarChange, onReady, reanimated, statusBarProps, style }: ProviderProps) {
   return (
     <ThemeSettingsProvider initialValue={initialValue} onChange={onChange}>
-      <ThemeProviderBody defaults={defaults} expoBlur={expoBlur} fontFamily={fontFamily} navigationBar={navigationBar} onNavBarChange={onNavBarChange} onReady={onReady} reanimated={reanimated} statusBarProps={statusBarProps} style={style}>
+      <ThemeProviderBody defaults={defaults} expoBlur={expoBlur} fontFamily={fontFamily} maskedView={maskedView} navigationBar={navigationBar} onNavBarChange={onNavBarChange} onReady={onReady} reanimated={reanimated} statusBarProps={statusBarProps} style={style}>
         {children}
       </ThemeProviderBody>
     </ThemeSettingsProvider>
@@ -67,11 +73,11 @@ const ThemeSettingsProvider = themeSettingsProvider
 
 type ThemeProviderBodyProps = Omit<ProviderProps, 'initialValue' | 'onChange'>
 
-function ThemeProviderBody({ children, defaults, expoBlur, fontFamily, navigationBar, onNavBarChange, onReady, reanimated, statusBarProps, style }: ThemeProviderBodyProps) {
+function ThemeProviderBody({ children, defaults, expoBlur, fontFamily, maskedView, navigationBar, onNavBarChange, onReady, reanimated, statusBarProps, style }: ThemeProviderBodyProps) {
   const { settings } = useThemeSettingsInternal()
 
   const computedTheme = useComputedTheme(settings.appearance, settings.color, settings.harmony)
-  // Layered on top of useComputedTheme's own output rather than folded into it — that hook only
+  // Layered on top of useComputedTheme's own output rather than folded into it - that hook only
   // ever recomputes for a color/appearance/harmony change, and fontFamily is a completely
   // independent axis; merging it there would mean either re-running the whole color computation on
   // every fontFamily change (wasteful) or threading fontFamily through as a fourth computeTheme
@@ -99,17 +105,19 @@ function ThemeProviderBody({ children, defaults, expoBlur, fontFamily, navigatio
         <NavBarContext.Provider value={{ navigationBar, onNavBarChange }}>
           <BlurModuleContext.Provider value={expoBlur}>
             <ReanimatedModuleContext.Provider value={reanimated}>
-              {/* PaperProvider's own PortalHost sits above every context provided here, and Paper's
+              <MaskedViewModuleContext.Provider value={maskedView}>
+                {/* PaperProvider's own PortalHost sits above every context provided here, and Paper's
                   Portal only carries its theme and settings across, so anything rendered through a
                   Portal (this package's Dialog, Paper's Menu and Tooltip, or anything an app wraps
-                  in <Portal> itself) would otherwise lose expoBlur, reanimated, defaults and the nav
+                  in <Portal> itself) would otherwise lose expoBlur, reanimated, maskedView, defaults and the nav
                   bar hooks: Dialog/Menu's blur silently fell back to solid. This nested host is the
                   nearest one for every Portal under Provider, so their content mounts inside all of
                   these contexts instead. It wraps the styled View, not the other way round, so
                   portals still cover the full area regardless of `style`. */}
-              <Portal.Host>
-                <View style={[styles.flex, { backgroundColor: theme.colors.background }, style]}>{children}</View>
-              </Portal.Host>
+                <Portal.Host>
+                  <View style={[styles.flex, { backgroundColor: theme.colors.background }, style]}>{children}</View>
+                </Portal.Host>
+              </MaskedViewModuleContext.Provider>
             </ReanimatedModuleContext.Provider>
           </BlurModuleContext.Provider>
         </NavBarContext.Provider>

package/src/components/AutoAppearancePicker.tsx

@@ -8,7 +8,7 @@ type Props = {
 
 // AppearancePicker wired straight to the Provider's own ThemeSettings, for the common case where
 // the appearance being edited IS the whole app's own theme. Takes neither `value` nor `onChange`
-// — reads/writes useThemeSettings() itself, so there's nothing for a consumer to wire up. Reach
+// - reads/writes useThemeSettings() itself, so there's nothing for a consumer to wire up. Reach
 // for the plain AppearancePicker instead when it needs to be controlled by something other than
 // the global theme (a local preview before committing, one-off UI unrelated to Provider).
 export const AutoAppearancePicker = (props: Props) => {

package/src/components/AutoPalettePicker.tsx

@@ -9,9 +9,9 @@ type Props = {
   blur?: boolean
 }
 
-// PalettePicker wired straight to the Provider's own ThemeSettings — both color AND harmony —
+// PalettePicker wired straight to the Provider's own ThemeSettings - both color AND harmony -
 // for the common case where the palette being edited IS the whole app's own theme. Takes none of
-// `value`/`onChange`/`harmony`/`onHarmonyChange` — reads/writes useThemeSettings() itself
+// `value`/`onChange`/`harmony`/`onHarmonyChange` - reads/writes useThemeSettings() itself
 // (resolveSeedColor narrows ThemeSettings.color's `string | TriadicPalette` down to the plain
 // string PalettePicker's own `value` wants). Reach for the plain PalettePicker instead when it
 // needs to be controlled by something other than the global theme.

package/src/components/BlurView.tsx

@@ -58,7 +58,16 @@ export type BlurViewProps = ExpoBlurViewProps & {
   variant?: 'primary' | 'secondary' | 'tertiary' | 'error' | 'surface' | 'surfaceVariant'
 }
 
-export const BlurView = ({ blur = true, children, elevation, style, tintColor, tintOpacity, variant = 'surface', ...props }: BlurViewProps) => {
+// The style expo-blur's web BlurView puts on its View (getBlurStyle in its src/BlurView.web.tsx, with
+// getBackgroundColor's 'dark' and 'light' tints, the only two this component uses): a CSS
+// backdrop-filter plus a translucent tint. On web BlurView applies it to its own View instead.
+const getWebBlurStyle = (intensity: number, dark: boolean) => {
+  const amount = Math.min(intensity, 100)
+  const filter = `saturate(180%) blur(${amount * 0.2}px)`
+  return { backdropFilter: filter, backgroundColor: `rgba(${dark ? '25,25,25' : '249,249,249'},${(amount / 100) * 0.78})`, WebkitBackdropFilter: filter } as ViewStyle
+}
+
+export const BlurView = ({ blur = true, blurMethod, blurReductionFactor, blurTarget, children, elevation, experimentalBlurMethod, intensity, style, tint: _tint, tintColor, tintOpacity, variant = 'surface', ...props }: BlurViewProps) => {
   const { dark, colors } = useTheme()
   const { settings } = useContext(ThemeSettingsContext)
   const expoBlur = useBlurModule()
@@ -67,16 +76,21 @@ export const BlurView = ({ blur = true, children, elevation, style, tintColor, t
   const resolvedTintColor = tintColor ?? variantColor ?? (elevation !== undefined ? colors.primary : undefined)
   const resolvedTintOpacity = tintOpacity ?? (tintColor ? (dark ? 0.24 : 0.16) : variantColor ? (dark ? VARIANT_TINT_OPACITY.dark : VARIANT_TINT_OPACITY.light) : elevation !== undefined ? ELEVATION_OPACITY[elevation] : 0)
   const tint = resolvedTintColor && resolvedTintOpacity > 0 ? <View style={[StyleSheet.absoluteFill, { backgroundColor: resolvedTintColor, opacity: resolvedTintOpacity }]} /> : null
-  if (blur && expoBlur && (Platform.OS !== 'android' || blursOnAndroid(props)))
-    return (
-      <expoBlur.BlurView {...props} tint={dark ? 'dark' : 'light'} style={style}>
-        <View style={[StyleSheet.absoluteFill, { backgroundColor: surfaceColor, opacity: settings.blurTint }]} />
-        {tint}
-        {children}
-      </expoBlur.BlurView>
-    )
+  const blurProps = { blurMethod, blurReductionFactor, blurTarget, experimentalBlurMethod, intensity }
+  const blurs = blur && expoBlur !== undefined && (Platform.OS !== 'android' || blursOnAndroid(blurProps))
+  const web = Platform.OS === 'web'
+  // The View holding the children is the same element whether or not blur applies, so flipping
+  // `blur` (a Dialog or Menu following the player's live settings.blur) never remounts them: their
+  // state, scroll offset, focus and ripples all survive. On iOS and Android the blur is an absoluteFill
+  // layer behind everything else, the same structure as expo-blur's own native BlurView. On web it
+  // can't be: Dialog and Menu fade this View's own opacity there, and an ancestor below opacity 1 cuts
+  // a CSS backdrop-filter off from the page behind it, so on web this View itself is the
+  // backdrop-filter element, styled the way expo-blur's web BlurView styles its own.
+  const containerStyle = !blurs ? [{ backgroundColor: surfaceColor }, style] : web ? [style, getWebBlurStyle(intensity ?? 50, dark)] : style
   return (
-    <View {...props} style={[{ backgroundColor: surfaceColor }, style]}>
+    <View {...props} style={containerStyle}>
+      {blurs && !web ? <expoBlur.BlurView {...blurProps} style={StyleSheet.absoluteFill} tint={dark ? 'dark' : 'light'} /> : null}
+      {blurs ? <View style={[StyleSheet.absoluteFill, { backgroundColor: surfaceColor, opacity: settings.blurTint }]} /> : null}
       {tint}
       {children}
     </View>

package/src/components/Dialog.tsx

@@ -7,11 +7,11 @@ import { useBlur } from '../BlurContext'
 import { useReanimatedModule } from '../ThemeProvider'
 import { BlurView } from './BlurView'
 
-// Minimal local mirror of react-native-reanimated's Animated.View — same reasoning as BlurView's
+// Minimal local mirror of react-native-reanimated's Animated.View - same reasoning as BlurView's
 // ExpoBlurModule: Metro doesn't rewrite a require()-in-try/catch call into its module graph inside
 // an ESM build, so the already-imported peer module is injected via <Provider reanimated={...}>
 // (see ThemeProvider.tsx) instead of required directly. Only `View` is needed here. `style: any`,
-// not a real style type — reanimated's actual AnimatedView only accepts its own branded
+// not a real style type - reanimated's actual AnimatedView only accepts its own branded
 // AnimatedStyle shape, which this package never imports (no reanimated dependency at all), so `any`
 // is the only type that both sides (this interface and the real component passed in) can agree on.
 export interface ReanimatedModule {
@@ -23,7 +23,7 @@ export type DialogProps = Omit<PaperDialogProps, 'style'> & {
   blur?: boolean
   style?: StyleProp<ViewStyle>
   // Applied to the card's outer wrapper instead of the card itself, and only takes effect once a
-  // reanimated module has been injected via <Provider reanimated={...}> — otherwise ignored. `style`
+  // reanimated module has been injected via <Provider reanimated={...}> - otherwise ignored. `style`
   // above is a plain object read once per render, so a fast-changing value (e.g. tracking the
   // keyboard height every frame) driven through it needs a full JS re-render per update to paint at
   // all; wiring the same value through `animatedStyle` (e.g. the result of Reanimated's

package/src/components/FadingScrollView.tsx

@@ -0,0 +1,127 @@
+import { type ComponentType, type ReactElement, type ReactNode, useCallback, useRef, useState } from 'react'
+import { type LayoutChangeEvent, type NativeScrollEvent, type NativeSyntheticEvent, Platform, ScrollView, type ScrollViewProps, type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native'
+
+import { useMaskedViewModule } from '../ThemeProvider'
+
+// Minimal local shape of @react-native-masked-view/masked-view's default export, the same way
+// ExpoBlurModule stands in for expo-blur: the optional peer's real types are never imported, so a
+// consumer that never installed it doesn't need them. <Provider maskedView={MaskedView}> hands it in.
+export type MaskedViewModule = ComponentType<{ children?: ReactNode; maskElement: ReactElement; style?: StyleProp<ViewStyle> }>
+
+// How far in from each edge a FadingScrollView's content fades out while there is more past that edge.
+export const SCROLL_FADE_HEIGHT = 24
+
+export type FadingScrollViewProps = Omit<ScrollViewProps, 'style'> & {
+  // Placed on the outer box (the flex item), so a caller's flexGrow/flexShrink/alignSelf work as they
+  // did on a plain ScrollView.
+  style?: StyleProp<ViewStyle>
+  fadeHeight?: number
+}
+
+// A vertical ScrollView whose content fades to transparent along an edge while there is more to scroll
+// past it: at the bottom, the cue that rows continue below a pinned footer, like a dialog's Done
+// button; at the top, the same once rows have scrolled up past the edge (Jay, 2026-10-15: one treatment
+// at both ends instead of a hard cut at the top). It masks
+// the content itself rather than painting anything over it, so whatever is behind (a blurred
+// Dialog/BlurView surface, a plain one, light or dark) shows through unchanged: no band, no seam. (A
+// second BlurView as a frosted footer was tried in @tastic/hud first and left a seam on iOS and web: a
+// blur nested in a blurred card can't frost the card's own content.) Once the end is reached the fade
+// goes away, and the top fade only shows once scrolled down, so neither the last row nor the first
+// (a dialog's header, say) is ever dimmed at rest.
+//
+// iOS/Android: a MaskedView (from <Provider maskedView={...}>) whose top and bottom bands are React
+// Native's native linear gradient (experimental_backgroundImage). Without one passed in, content just scrolls
+// with no fade. Web: react-native-masked-view's web build renders only the mask element (it doesn't
+// mask), so the outer box gets a CSS mask-image instead, which react-native-web passes through; no
+// module needed there.
+export function FadingScrollView({ style, fadeHeight = SCROLL_FADE_HEIGHT, onScroll, onLayout, onContentSizeChange, scrollEventThrottle = 16, children, ...rest }: FadingScrollViewProps) {
+  const MaskedView = useMaskedViewModule()
+  // Sizes live in a ref and only the yes/no answers are state, so scrolling re-renders nothing until a
+  // fade has to appear or go.
+  const sizes = useRef({ viewport: 0, content: 0, offset: 0 })
+  const [edges, setEdges] = useState(NO_EDGES)
+  const update = useCallback(() => {
+    const { viewport, content, offset } = sizes.current
+    const above = offset > 1
+    const below = content - viewport - offset > 1
+    setEdges((prev) => (prev.above === above && prev.below === below ? prev : { above, below }))
+  }, [])
+
+  const scroll = (
+    <ScrollView
+      {...rest}
+      style={styles.fill}
+      scrollEventThrottle={scrollEventThrottle}
+      onScroll={(e: NativeSyntheticEvent<NativeScrollEvent>) => {
+        sizes.current.offset = e.nativeEvent.contentOffset.y
+        update()
+        onScroll?.(e)
+      }}
+      onLayout={(e: LayoutChangeEvent) => {
+        sizes.current.viewport = e.nativeEvent.layout.height
+        update()
+        onLayout?.(e)
+      }}
+      onContentSizeChange={(width: number, height: number) => {
+        sizes.current.content = height
+        update()
+        onContentSizeChange?.(width, height)
+      }}
+    >
+      {children}
+    </ScrollView>
+  )
+
+  if (Platform.OS === 'web') return <View style={[styles.box, style, (edges.above || edges.below) && webFadeStyle(fadeHeight, edges)]}>{scroll}</View>
+  if (!MaskedView) return <View style={[styles.box, style]}>{scroll}</View>
+
+  return (
+    <MaskedView
+      style={[styles.box, style]}
+      maskElement={
+        <View style={styles.fill}>
+          <View style={[{ height: fadeHeight }, edges.above ? FADE_IN_BAND : styles.opaque]} />
+          <View style={styles.fillOpaque} />
+          <View style={[{ height: fadeHeight }, edges.below ? FADE_OUT_BAND : styles.opaque]} />
+        </View>
+      }
+    >
+      {scroll}
+    </MaskedView>
+  )
+}
+
+// React Native's native linear gradient (0.77+, the New Architecture; the fleet's apps are on 0.86), not
+// in this package's own 0.76 dev types, hence the cast. A mask's alpha is what shows: opaque keeps the
+// content, transparent hides it.
+const FADE_IN_BAND = { experimental_backgroundImage: 'linear-gradient(transparent, #000)' } as unknown as ViewStyle
+const FADE_OUT_BAND = { experimental_backgroundImage: 'linear-gradient(#000, transparent)' } as unknown as ViewStyle
+
+const NO_EDGES = { above: false, below: false }
+
+// mask-image isn't in React Native's style types, but react-native-web passes it to the DOM as is.
+function webFadeStyle(fadeHeight: number, edges: { above: boolean; below: boolean }): ViewStyle {
+  const top = edges.above ? `transparent 0, #000 ${fadeHeight}px` : '#000 0'
+  const bottom = edges.below ? `#000 calc(100% - ${fadeHeight}px), transparent 100%` : '#000 100%'
+  const mask = `linear-gradient(to bottom, ${top}, ${bottom})`
+  return { maskImage: mask, WebkitMaskImage: mask } as unknown as ViewStyle
+}
+
+const styles = StyleSheet.create({
+  // A plain ScrollView's own flex defaults, so it sizes the same in its parent.
+  box: {
+    flexGrow: 1,
+    flexShrink: 1
+  },
+  fill: {
+    flexGrow: 1,
+    flexShrink: 1
+  },
+  fillOpaque: {
+    backgroundColor: '#000',
+    flexGrow: 1
+  },
+  opaque: {
+    backgroundColor: '#000'
+  }
+})

package/src/components/HarmonyPicker.tsx

@@ -13,12 +13,12 @@ const HARMONIES: { label: string; value: ColorHarmony; icon: string }[] = [
 
 // Paper's own SegmentedButtonItem hardcodes `minWidth: 76` per segment (sized for a labeled text
 // button), which 6 of never fit inside PalettePicker's own dialog card (capped at 400, and
-// narrower still once its padding and safe-area margins are subtracted) — they just overflow past
+// narrower still once its padding and safe-area margins are subtracted) - they just overflow past
 // its `overflow: hidden` edge instead of shrinking. A fixed smaller guess (say 44) only moves the
-// breakpoint rather than removing it — 6x44 still exceeds the card's content width on an ordinary
+// breakpoint rather than removing it - 6x44 still exceeds the card's content width on an ordinary
 // ~360-375px phone. Zeroing the floor instead lets each segment's own `flex: 1` divide whatever
 // width IS available with nothing left to enforce a minimum, so 6 of them mathematically can never
-// exceed their container at any screen size — same "shrink to fit, never overflow" contract
+// exceed their container at any screen size - same "shrink to fit, never overflow" contract
 // useSwatchGrid.ts's own SWATCH_GRID_COLUMNS already uses for the swatches below this row. Left
 // untouched in labeled mode, where the wider floor is still doing its job of fitting the text.
 const COMPACT_MIN_WIDTH = 0
@@ -26,13 +26,13 @@ const COMPACT_MIN_WIDTH = 0
 type Props = {
   value: ColorHarmony
   onChange: (harmony: ColorHarmony) => void
-  // Hides text labels, leaving just the icon per segment — mirrors AppearancePicker's own
+  // Hides text labels, leaving just the icon per segment - mirrors AppearancePicker's own
   // showLabels, useful here since there are 6 segments to fit instead of 3.
   // accessibilityLabel is always set regardless, so screen readers still announce the full
   // harmony name either way.
   showLabels?: boolean
   // Per-segment fill, e.g. theme.colors.secondary/onSecondary for the checked segment and
-  // secondaryContainer/onSecondaryContainer for the rest — matches Paper's own checked/
+  // secondaryContainer/onSecondaryContainer for the rest - matches Paper's own checked/
   // unchecked + container color vocabulary. Omit to fall back to Paper's default segmented-
   // button styling.
   checkedColor?: string

package/src/components/PalettePicker.tsx

@@ -58,7 +58,7 @@ type Props = {
   harmony?: ColorHarmony
   // Opt-in: passing this turns on a compact, icon-only HarmonyPicker row inside the dialog, above
   // the swatch grid, so every swatch's own Pie preview reshapes live as harmony changes. Omit it
-  // and this renders exactly as a plain PalettePicker always has — same trigger, same dialog,
+  // and this renders exactly as a plain PalettePicker always has - same trigger, same dialog,
   // harmony fixed at whatever the `harmony` prop says. Gated on the callback itself rather than a
   // separate boolean so there's no way to pass one without the other.
   onHarmonyChange?: (harmony: ColorHarmony) => void