@hzblj/kara-components 0.7.0 → 0.9.0

package/src/atoms/pressable/pressable.types.ts

@@ -4,13 +4,15 @@ import type {ReactNode} from 'react'
 import type {Haptic} from '../../haptics'
 
 /**
- * React Native's `Pressable`, styled through `sx` like a `Box`: it springs down to 96% while pressed and takes
- * touches 8 points past its edges. The React Native tier — it needs no host.
+ * React Native's `Pressable`, styled through `sx` like a `Box`, taking touches 8 points past its edges. The press is
+ * each platform's own: iOS springs it down to 96%; Android draws Material's ripple over the content, clipped to the
+ * pressable's shape — give it the `borderRadius` of what it wraps (`full` around a `GlassView`). The React Native
+ * tier — it needs no host.
  */
 export type PressableProps = ResponsiveViewSx & {
   /** The pressable content. */
   children?: ReactNode
-  /** Ignores presses — no `onPress`, no haptic, no spring. */
+  /** Ignores presses — no `onPress`, no haptic, no spring or ripple. */
   disabled?: boolean
   /** Played on press. `true` is a `light` impact; a name picks the haptic, e.g. `selection` for a choice. */
   haptic?: boolean | Haptic

package/src/atoms/progress/progress.ios.tsx

@@ -1,5 +1,5 @@
-import {ProgressView} from '@expo/ui/swift-ui'
-import {progressViewStyle, tint} from '@expo/ui/swift-ui/modifiers'
+import {Gauge, ProgressView} from '@expo/ui/swift-ui'
+import {gaugeStyle, progressViewStyle, tint} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -10,10 +10,19 @@ export const Progress: ProgressComponent = ({circular = false, value}: ProgressP
   useHostGuard('Progress')
   const theme = useAppTheme()
 
+  const ring = circular && value !== undefined
   const modifiers = useMemo(
-    () => [progressViewStyle(circular ? 'circular' : 'linear'), tint(theme.color('fill.accent.primary'))],
-    [circular, theme]
+    () => [
+      ring ? gaugeStyle('circularCapacity') : progressViewStyle(circular ? 'circular' : 'linear'),
+      tint(theme.color('fill.accent.primary')),
+    ],
+    [circular, ring, theme]
   )
 
-  return <ProgressView modifiers={modifiers} value={value ?? null} />
+  // SwiftUI's circular `ProgressView` ignores its value on iOS and spins; a ring that fills is a capacity `Gauge`.
+  return ring ? (
+    <Gauge modifiers={modifiers} value={value} />
+  ) : (
+    <ProgressView modifiers={modifiers} value={value ?? null} />
+  )
 }

package/src/atoms/progress/progress.types.ts

@@ -1,8 +1,8 @@
 import type {ReactNode} from 'react'
 
 /**
- * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` / Compose's
- * `LinearProgressIndicator` and `CircularProgressIndicator`.
+ * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
+ * value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and `CircularProgressIndicator`.
  */
 export type ProgressProps = {
   /** A circular indicator instead of a bar. Off by default. */

package/src/atoms/rn-text/rn-text.tsx

@@ -1,5 +1,6 @@
+import {useSplitSx} from '@hzblj/kara-sx'
 import {MAX_FONT_SCALE, useAppTheme} from '@hzblj/kara-theme'
-import {Text as RNText, useWindowDimensions} from 'react-native'
+import {Text as RNText, type TextStyle, useWindowDimensions} from 'react-native'
 
 import type {RnTextComponent, RnTextProps} from './rn-text.types'
 
@@ -10,6 +11,8 @@ export const RnText: RnTextComponent = ({
   ...props
 }: RnTextProps) => {
   const theme = useAppTheme()
+  // A view style, which a text accepts whole — only React Native's types disagree, on `userSelect`'s width.
+  const [sx, rest] = useSplitSx(props) as [TextStyle, Record<string, unknown>]
   const {fontScale} = useWindowDimensions()
   const style = theme.typography[variant]
 
@@ -26,8 +29,8 @@ export const RnText: RnTextComponent = ({
   return (
     <RNText
       maxFontSizeMultiplier={MAX_FONT_SCALE}
-      style={[style, {color: theme.color(color), lineHeight, textAlign: align}]}
-      {...props}
+      style={[style, sx, {color: theme.color(color), lineHeight, textAlign: align}]}
+      {...rest}
     />
   )
 }

package/src/atoms/rn-text/rn-text.types.ts

@@ -1,15 +1,21 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
 import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 import type {TextProps as RNTextProps} from 'react-native'
 
-/** React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. */
-export type RnTextProps = Omit<RNTextProps, 'style'> & {
-  /** Horizontal alignment, as React Native's `textAlign`. */
-  align?: 'center' | 'left' | 'right'
-  /** The text's colour. `content.primary` by default. */
-  color?: ColorToken
-  /** The typography variant. `body` by default. */
-  variant?: TextVariant
-}
+/**
+ * React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. It takes
+ * `Box`'s `sx` surface for its own box — margins, flex, padding, a background — all but `align`, which here aligns the
+ * lines.
+ */
+export type RnTextProps = Omit<RNTextProps, 'style'> &
+  Omit<ResponsiveViewSx, 'align'> & {
+    /** Horizontal alignment, as React Native's `textAlign`. */
+    align?: 'center' | 'left' | 'right'
+    /** The text's colour. `content.primary` by default. */
+    color?: ColorToken
+    /** The typography variant. `body` by default. */
+    variant?: TextVariant
+  }
 
 export type RnTextComponent = (props: RnTextProps) => ReactNode

package/src/atoms/skeleton/skeleton.tsx

@@ -5,7 +5,7 @@ import {useAnimatedStyle, useSharedValue, withRepeat, withTiming} from 'react-na
 import {ABox} from '../box'
 import type {SkeletonComponent, SkeletonProps} from './skeleton.types'
 
-export const Skeleton: SkeletonComponent = ({borderRadius = 'small', height, testID, width}: SkeletonProps) => {
+export const Skeleton: SkeletonComponent = ({borderRadius = 'small', h, testID, w}: SkeletonProps) => {
   const pulse = useSharedValue<number>(opacity.o40)
 
   useEffect(() => {
@@ -18,11 +18,11 @@ export const Skeleton: SkeletonComponent = ({borderRadius = 'small', height, tes
     <ABox
       bg="fill.quaternary"
       borderRadius={borderRadius}
-      h={height}
+      h={h}
       style={rStyle}
       testID={testID}
-      w={width}
-      wide={width === undefined}
+      w={w}
+      wide={w === undefined}
     />
   )
 }

package/src/atoms/skeleton/skeleton.types.ts

@@ -1,16 +1,20 @@
+import type {SxDimension} from '@hzblj/kara-sx'
 import type {RadiiSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-/** A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. */
+/**
+ * A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. Sized with the
+ * `sx` names: `w`, `h`, `borderRadius`.
+ */
 export type SkeletonProps = {
   /** The corner radius. `small` by default. */
   borderRadius?: RadiiSize
   /** In points. */
-  height: number
+  h: number
   /** Test identifier, forwarded to the view. */
   testID?: string
-  /** In points. Leave it unset and it fills the available width. */
-  width?: number
+  /** In points, or a percentage of the row (`60%` for a line that ends early). Unset, it fills the row. */
+  w?: SxDimension
 }
 
 export type SkeletonComponent = (props: SkeletonProps) => ReactNode

package/src/atoms/surface/surface.ios.tsx

@@ -6,7 +6,8 @@ import type {SurfaceComponent, SurfaceProps} from './surface.types'
 export const Surface: SurfaceComponent = ({children, glass = false, testID, ...sx}: SurfaceProps) => {
   useHostGuard('Surface')
 
-  const modifiers = useSxModifiers({borderRadius: 'large', p: 's16', ...sx})
+  // `surface.primary` unless told otherwise, as Material's `Surface` is on Android — without it a plain one drew nothing.
+  const modifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', ...sx})
   const content = (
     <VStack alignment="leading" modifiers={modifiers} testID={testID}>
       {children}

package/src/atoms/surface/surface.types.ts

@@ -2,8 +2,8 @@ import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
 /**
- * A container padded `s16` and rounded `large` unless told otherwise — a SwiftUI `VStack` on iOS, Material's
- * `Surface` around a `Column` on Android.
+ * A container on `surface.primary`, padded `s16` and rounded `large` unless told otherwise — a SwiftUI `VStack` on
+ * iOS, Material's `Surface` around a `Column` on Android.
  */
 export type SurfaceProps = ResponsiveSx & {
   /** Stacked vertically, from the leading edge. */

package/src/atoms/text/text.android.tsx

@@ -1,5 +1,6 @@
 import {Text as ComposeText} from '@expo/ui/jetpack-compose'
 import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -32,11 +33,16 @@ export const Text: TextComponent = ({
   testID,
   transform,
   variant = 'body',
+  ...sx
 }: TextProps) => {
   useHostGuard('Text')
   const theme = useAppTheme()
   const style = theme.typography[variant]
-  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
+  const sxModifiers = useSxModifiers(sx)
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
 
   return (
     <ComposeText

package/src/atoms/text/text.ios.tsx

@@ -10,11 +10,12 @@ import {
   underline,
 } from '@expo/ui/swift-ui/modifiers'
 import {scaledFont} from '@hzblj/kara-native/swift-ui'
+import {type FrameAlignment, useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
-import type {TextComponent, TextProps} from './text.types'
+import type {TextAlign, TextComponent, TextProps} from './text.types'
 
 const ALIGNMENT = {
   center: 'center',
@@ -22,6 +23,13 @@ const ALIGNMENT = {
   right: 'trailing',
 } as const
 
+/** Where a frame larger than the text — `wide`, `w`, `h` — puts it: on the side its lines align to, centred vertically. */
+const FRAME_ALIGNMENT = {
+  center: 'center',
+  left: 'leading',
+  right: 'trailing',
+} as const satisfies Record<TextAlign, FrameAlignment>
+
 export const Text: TextComponent = ({
   align,
   children,
@@ -31,10 +39,13 @@ export const Text: TextComponent = ({
   testID,
   transform,
   variant = 'body',
+  ...sx
 }: TextProps) => {
   useHostGuard('Text')
   const theme = useAppTheme()
   const style = theme.typography[variant]
+  // After the text's own modifiers: the font and colour belong to the glyphs, the padding and frame to the box around.
+  const sxModifiers = useSxModifiers(sx, FRAME_ALIGNMENT[align ?? 'left'])
 
   const modifiers = useMemo(() => {
     const list: ModifierConfig[] = [
@@ -65,8 +76,8 @@ export const Text: TextComponent = ({
       list.push(lineLimit(numberOfLines))
     }
 
-    return list
-  }, [align, color, decoration, numberOfLines, style, theme, transform])
+    return [...list, ...sxModifiers]
+  }, [align, color, decoration, numberOfLines, style, sxModifiers, theme, transform])
 
   return (
     <SwiftUIText modifiers={modifiers} testID={testID}>

package/src/atoms/text/text.types.ts

@@ -1,3 +1,4 @@
+import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
@@ -7,8 +8,12 @@ export type TextDecoration = 'none' | 'strikethrough' | 'underline'
 
 export type TextTransform = 'lowercase' | 'uppercase'
 
-/** SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. */
-export type TextProps = {
+/**
+ * SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. It takes
+ * the native `sx` surface too: padding, a frame (`wide` lines it up by `align`), a background, and the `ios` bucket's
+ * `contentTransition`, `animation` and `monospacedDigit` for a number that changes in place.
+ */
+export type TextProps = ResponsiveSx & {
   /**
    * How its lines align. iOS reads `left` and `right` as leading and trailing, so they flip in a right-to-left
    * layout; Android keeps them as they are.

package/src/atoms/text-field/text-field.android.tsx

@@ -1,6 +1,7 @@
 import {Column, Text as ComposeText, OutlinedTextField, useNativeState} from '@expo/ui/jetpack-compose'
 import {useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
 import type {TextFieldComponent, TextFieldProps} from './text-field.types'
 
@@ -17,12 +18,14 @@ export const TextField: TextFieldComponent = ({
   const theme = useAppTheme()
   const value = useNativeState(defaultValue)
   const modifiers = useSxModifiers({wide: true})
+  const invalid = Boolean(error)
+  const message = typeof error === 'string' && error ? error : undefined
 
   return (
     <Column verticalArrangement={{spacedBy: 4}}>
       {label ? (
         <ComposeText
-          color={theme.colorString(error ? 'content.destructive' : 'content.secondary')}
+          color={theme.colorString(invalid ? 'content.destructive' : 'content.secondary')}
           style={theme.typography.labelMedium}
         >
           {label}
@@ -30,7 +33,7 @@ export const TextField: TextFieldComponent = ({
       ) : null}
       <OutlinedTextField
         enabled={!disabled}
-        isError={error}
+        isError={invalid}
         modifiers={modifiers}
         onValueChange={onChangeText}
         singleLine={!multiline}
@@ -41,7 +44,20 @@ export const TextField: TextFieldComponent = ({
         }}
         value={value}
         visualTransformation={secure ? 'password' : 'none'}
-      />
+      >
+        {invalid ? (
+          <OutlinedTextField.TrailingIcon>
+            <Glyph color="content.destructive" name="error" />
+          </OutlinedTextField.TrailingIcon>
+        ) : null}
+        {message ? (
+          <OutlinedTextField.SupportingText>
+            <ComposeText color={theme.colorString('content.destructive')} style={theme.typography.footnote}>
+              {message}
+            </ComposeText>
+          </OutlinedTextField.SupportingText>
+        ) : null}
+      </OutlinedTextField>
     </Column>
   )
 }

package/src/atoms/text-field/text-field.ios.tsx

@@ -45,7 +45,8 @@ export const TextField: TextFieldComponent = ({
 }: TextFieldProps) => {
   useHostGuard('TextField')
   const text = useNativeState(defaultValue)
-  const tone = TONE[toneOf(disabled, error)]
+  const tone = TONE[toneOf(disabled, Boolean(error))]
+  const message = tone === TONE.error && typeof error === 'string' && error ? error : undefined
 
   const sxModifiers = useSxModifiers({
     bg: tone.bg,
@@ -85,6 +86,11 @@ export const TextField: TextFieldComponent = ({
           text={text}
         />
       )}
+      {message ? (
+        <Text color="content.destructive" variant="footnote">
+          {message}
+        </Text>
+      ) : null}
     </VStack>
   )
 }

package/src/atoms/text-field/text-field.types.ts

@@ -9,8 +9,12 @@ export type TextFieldProps = {
   defaultValue?: string
   /** Stops editing and dims the field. On iOS it outranks `error`. */
   disabled?: boolean
-  /** Marks the field invalid: a destructive outline and label. */
-  error?: boolean
+  /**
+   * Marks the field invalid: a destructive outline and label. A message is shown under the field as well — on Android
+   * as Material's supporting text, beside its error icon — so the error never rests on colour alone; Material's error
+   * colour is a pale red in dark mode. `true` marks it without a message.
+   */
+  error?: boolean | string
   /** Shown above the field, in `labelMedium`. */
   label?: string
   /** Wraps the text and grows the field to fit it. iOS ignores it when `secure`. */

package/src/molecules/collapsible/collapsible.android.tsx

@@ -1,25 +1,65 @@
-import {AnimatedVisibility, Column, Text as ComposeText, Row} from '@expo/ui/jetpack-compose'
-import {clickable} from '@expo/ui/jetpack-compose/modifiers'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {
+  AnimatedVisibility,
+  Box,
+  Column,
+  Text as ComposeText,
+  EnterTransition,
+  ExitTransition,
+  Row,
+} from '@expo/ui/jetpack-compose'
+import {
+  animated,
+  clickable,
+  defaultMinSize,
+  fillMaxWidth,
+  graphicsLayer,
+  tween,
+} from '@expo/ui/jetpack-compose/modifiers'
+import {duration, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
 import type {CollapsibleComponent, CollapsibleProps} from './collapsible.types'
 
+/** Material's standard easing, at the length a disclosure takes. */
+const TURN = tween({durationMillis: duration.d200, easing: 'fastOutSlowIn'})
+
+/** Down from the row, fading in — Compose's default grows from a corner, sideways as well as down. */
+const ENTER = EnterTransition.expandVertically().plus(EnterTransition.fadeIn())
+const EXIT = ExitTransition.shrinkVertically().plus(ExitTransition.fadeOut())
+
+const WIDE = [fillMaxWidth()]
+
+/** Material's least touch target. */
+const ROW_HEIGHT = 48
+
+/**
+ * A pressable row and an animated reveal: the content expands down from the row, and the chevron turns a quarter
+ * toward it, as a Material disclosure does — it used to jump between two glyphs. The row spans its parent, the chevron
+ * at the far end, and is never shorter than a touch target.
+ */
 export const Collapsible: CollapsibleComponent = ({children, expanded, label, onExpandedChange}: CollapsibleProps) => {
   useHostGuard('Collapsible')
   const theme = useAppTheme()
-  const modifiers = useMemo(() => [clickable(() => onExpandedChange(!expanded))], [expanded, onExpandedChange])
+  const modifiers = useMemo(
+    () => [fillMaxWidth(), defaultMinSize({minHeight: ROW_HEIGHT}), clickable(() => onExpandedChange(!expanded))],
+    [expanded, onExpandedChange]
+  )
+  const turn = useMemo(() => [graphicsLayer({rotationZ: animated(expanded ? 90 : 0, TURN)})], [expanded])
 
   return (
-    <Column>
+    <Column modifiers={WIDE}>
       <Row horizontalArrangement="spaceBetween" modifiers={modifiers} verticalAlignment="center">
         <ComposeText color={theme.colorString('content.primary')} style={theme.typography.body}>
           {label}
         </ComposeText>
-        <Glyph name={expanded ? 'chevronDown' : 'chevronRight'} size="s20" />
+        <Box modifiers={turn}>
+          <Glyph name="chevronRight" size="s20" />
+        </Box>
       </Row>
-      <AnimatedVisibility visible={expanded}>{children}</AnimatedVisibility>
+      <AnimatedVisibility enterTransition={ENTER} exitTransition={EXIT} visible={expanded}>
+        {children}
+      </AnimatedVisibility>
     </Column>
   )
 }

package/src/molecules/navigation-bar/navigation-bar.android.tsx

@@ -2,17 +2,12 @@ import {iconResourceName} from '@hzblj/kara-native'
 import {TopAppBar, type TopAppBarItem} from '@hzblj/kara-native/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
-import {StyleSheet} from 'react-native'
 import {Island} from '../../atoms/island'
 import type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
 /** Material's small top app bar. */
 const BAR_HEIGHT = 64
 
-const styles = StyleSheet.create({
-  bar: {height: BAR_HEIGHT, width: '100%'},
-})
-
 const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
 
 const toNativeItem = ({onPress, testID, ...item}: NavigationBarItem): TopAppBarItem =>
@@ -38,7 +33,7 @@ export const NavigationBar: NavigationBarComponent = ({
   const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
 
   return (
-    <Island matchContents={false} style={styles.bar} testID={testID}>
+    <Island h={BAR_HEIGHT} matchContents={false} testID={testID} w="100%">
       <TopAppBar
         fontFamily={font.fontFamily}
         fontSize={font.fontSize}

package/src/molecules/pager/pager.android.tsx

@@ -4,15 +4,17 @@ import {spacing} from '@hzblj/kara-theme'
 import {Children, useCallback, useEffect, useMemo, useRef, useState} from 'react'
 
 import {HStack} from '../../atoms/h-stack'
+import {Spacer} from '../../atoms/spacer'
 import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import type {PagerComponent, PagerProps} from './pager.types'
 
 const DOT_SIZE = 6
 
-/** Compose ships no page indicator, so the dots are composed out of atoms. */
+/** Compose ships no page indicator, so the dots are composed out of atoms — centred between two spacers. */
 const PagerDots = ({count, current}: {count: number; current: number}) => (
   <HStack align="center" py="s12" spacing="s6" wide>
+    <Spacer />
     {Array.from({length: count}, (_, index) => (
       <VStack
         bg={index === current ? 'content.primary' : 'fill.tertiary'}
@@ -22,6 +24,7 @@ const PagerDots = ({count, current}: {count: number; current: number}) => (
         w={DOT_SIZE}
       />
     ))}
+    <Spacer />
   </HStack>
 )
 

package/src/molecules/scroll-edge-container/scroll-edge-container.android.tsx

@@ -1,9 +1,49 @@
-import {Box} from '../../atoms/box'
+import {duration, opacity} from '@hzblj/kara-theme'
+import {cloneElement, type ReactNode, useCallback, useRef} from 'react'
+import type {LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent} from 'react-native'
+import {type SharedValue, useAnimatedStyle, useSharedValue, withTiming} from 'react-native-reanimated'
+
+import {ABox, Box} from '../../atoms/box'
 import type {ScrollEdgeContainerComponent, ScrollEdgeContainerProps} from './scroll-edge-container.types'
 
+/** Less than a pixel scrolled is not scrolled — a fling settles a fraction away from the edge. */
+const EDGE_SLOP = 0.5
+
+const FILL = {duration: duration.d200}
+
+type Bar = {children: ReactNode; filled: SharedValue<number>}
+
+/** A bar, and behind it the container colour it fills with — faded in and out, not switched. */
+const EdgeBar = ({children, filled}: Bar) => {
+  const fill = useAnimatedStyle(() => ({opacity: filled.value}), [])
+
+  if (!children) {
+    return null
+  }
+
+  return (
+    <Box>
+      <ABox
+        bg="surface.secondary"
+        bottom={0}
+        left={0}
+        pointerEvents="none"
+        position="absolute"
+        right={0}
+        style={fill}
+        top={0}
+      />
+      {children}
+    </Box>
+  )
+}
+
 /**
- * Android has no scroll edge effect, and a React Native scroll view there has no `contentInset` to slide content under
- * a bar with — so the bars stack above and below the scroll view instead of over it. Give them a background.
+ * Material's take on the scroll edge: a React Native scroll view has no `contentInset` to slide content under a bar on
+ * Android, so the bars stack above and below it, and do what a Material top app bar does on scroll — transparent at
+ * rest, filled with `surface.secondary` (the scrolled container colour, `surfaceContainer`) once content has scrolled
+ * under it. The bottom bar mirrors it: filled while there is more content below. The scroll view keeps its own
+ * `onScroll`, `onLayout` and `onContentSizeChange`.
  */
 export const ScrollEdgeContainer: ScrollEdgeContainerComponent = ({
   automaticInsets: _automaticInsets,
@@ -13,10 +53,63 @@ export const ScrollEdgeContainer: ScrollEdgeContainerComponent = ({
   testID,
   topBar,
   ...sx
-}: ScrollEdgeContainerProps) => (
-  <Box {...sx} testID={testID}>
-    {topBar}
-    <Box flex={1}>{children}</Box>
-    {bottomBar}
-  </Box>
-)
+}: ScrollEdgeContainerProps) => {
+  const topFilled = useSharedValue<number>(opacity.o0)
+  const bottomFilled = useSharedValue<number>(opacity.o0)
+  const metrics = useRef({content: 0, offset: 0, viewport: 0})
+  const state = useRef({bottom: false, top: false})
+  const {flex, onContentSizeChange, onLayout, onScroll, scrollEventThrottle} = children.props as {
+    flex?: number
+    onContentSizeChange?: (width: number, height: number) => void
+    onLayout?: (event: LayoutChangeEvent) => void
+    onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void
+    scrollEventThrottle?: number
+  }
+
+  // Only a change of state animates; a scroll event restating the same one would restart the fade.
+  const update = useCallback(() => {
+    const {content, offset, viewport} = metrics.current
+    const top = offset > EDGE_SLOP
+    const bottom = viewport > 0 && offset + viewport < content - EDGE_SLOP
+
+    if (top !== state.current.top) {
+      state.current.top = top
+      topFilled.value = withTiming(top ? opacity.o100 : opacity.o0, FILL)
+    }
+
+    if (bottom !== state.current.bottom) {
+      state.current.bottom = bottom
+      bottomFilled.value = withTiming(bottom ? opacity.o100 : opacity.o0, FILL)
+    }
+  }, [bottomFilled, topFilled])
+
+  // `flex` so the scroll view takes the room between the bars — left to its content, it grew to the content's height,
+  // ran under the bottom bar and had nothing to scroll.
+  const scrollable = cloneElement(children, {
+    flex: flex ?? 1,
+    onContentSizeChange: (width: number, height: number) => {
+      metrics.current.content = height
+      update()
+      onContentSizeChange?.(width, height)
+    },
+    onLayout: (event: LayoutChangeEvent) => {
+      metrics.current.viewport = event.nativeEvent.layout.height
+      update()
+      onLayout?.(event)
+    },
+    onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      metrics.current.offset = event.nativeEvent.contentOffset.y
+      update()
+      onScroll?.(event)
+    },
+    scrollEventThrottle: scrollEventThrottle ?? 16,
+  } as Partial<typeof children.props>)
+
+  return (
+    <Box {...sx} testID={testID}>
+      <EdgeBar filled={topFilled}>{topBar}</EdgeBar>
+      <Box flex={1}>{scrollable}</Box>
+      <EdgeBar filled={bottomFilled}>{bottomBar}</EdgeBar>
+    </Box>
+  )
+}