@hzblj/kara-components 0.7.0 → 0.8.0

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>
+  )
+}

package/src/molecules/scroll-edge-container/scroll-edge-container.types.ts

@@ -5,8 +5,10 @@ import type {ReactElement, ReactNode} from 'react'
 export type {ScrollEdgeEffect, ScrollEdgeScrollableProps} from '@hzblj/kara-native/swift-ui'
 
 /**
- * Bars over one React Native scroll view, with the iOS 26 scroll edge effect under them — the system's progressive
- * blur where content scrolls past a bar. The React Native tier: it needs no host.
+ * Bars over one React Native scroll view, with each platform's scroll edge under them — on iOS 26 the system's
+ * progressive blur where content scrolls past a bar; on Android a Material top app bar's behaviour, the bars stacked
+ * around the scroll view and filling with `surface.secondary` once content scrolls under them. The React Native tier:
+ * it needs no host.
  *
  * A screen-level container: wrap the screen's scroll view with it. Mounted inside a cell of a virtualized list on iOS
  * it draws only its bottom bar — the hosted scroll view and the top bar stay blank.
@@ -17,7 +19,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
    * content begins below the top bar and scrolls under it. On by default.
    */
   automaticInsets?: boolean
-  /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, where it wants a background. */
+  /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, filled while content continues below. */
   bottomBar?: ReactNode
   /** Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`. */
   children: ReactElement<ScrollEdgeScrollableProps>
@@ -25,7 +27,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
   effect?: ScrollEdgeEffect
   /** Test identifier, forwarded to the container view. */
   testID?: string
-  /** Laid over the scroll view's top edge on iOS; stacked above it on Android, where it wants a background. */
+  /** Laid over the scroll view's top edge on iOS; stacked above it on Android, filled once content scrolls under it. */
   topBar?: ReactNode
 }
 

package/src/molecules/stepper/stepper.ios.tsx

@@ -1,10 +1,46 @@
 import {Stepper as SwiftUIStepper} from '@expo/ui/swift-ui'
+import {labelsHidden} from '@expo/ui/swift-ui/modifiers'
+import {useRef} from 'react'
 
+import {HStack} from '../../atoms/h-stack'
+import {Spacer} from '../../atoms/spacer'
+import {Text} from '../../atoms/text'
 import {useHostGuard} from '../../host-context'
 import type {StepperComponent, StepperProps} from './stepper.types'
 
+/** The label stays VoiceOver's, on the control; on screen it is the row's own text. */
+const LABEL_HIDDEN = [labelsHidden()]
+
+/**
+ * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
+ * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
+ * monospaced digits so the row does not jump.
+ */
 export const Stepper: StepperComponent = ({label, max, min, onValueChange, step = 1, value}: StepperProps) => {
   useHostGuard('Stepper')
+  const previous = useRef(value)
+  const countsDown = value < previous.current
+  previous.current = value
 
-  return <SwiftUIStepper label={label} max={max} min={min} onValueChange={onValueChange} step={step} value={value} />
+  return (
+    <HStack align="center" spacing="s12" wide>
+      <Text>{label}</Text>
+      <Spacer />
+      <Text
+        color="content.secondary"
+        ios={{animation: {value}, contentTransition: {countsDown, type: 'numericText'}, monospacedDigit: true}}
+      >
+        {String(value)}
+      </Text>
+      <SwiftUIStepper
+        label={label}
+        max={max}
+        min={min}
+        modifiers={LABEL_HIDDEN}
+        onValueChange={onValueChange}
+        step={step}
+        value={value}
+      />
+    </HStack>
+  )
 }

package/src/molecules/stepper/stepper.types.ts

@@ -5,10 +5,7 @@ import type {ReactNode} from 'react'
  * two icon buttons in a row. A native atom — it renders inside `<Screen>` or `<Island>`.
  */
 export type StepperProps = {
-  /**
-   * The leading text. iOS shows only the label, not the value — put the value in it if it should be seen. Android
-   * shows the value between its buttons.
-   */
+  /** The leading text. The value is shown too — before the control on iOS, between the buttons on Android. */
   label: string
   /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
   max?: number

package/src/ripple-clip.ts

@@ -23,6 +23,9 @@ const CONTENT_KEYS = new Set<string>([
 
 const FILL: ViewStyle = {flexGrow: 1}
 
+/** What gives the outer view a height of its own, rather than its content's. */
+const SIZING_KEYS = ['aspectRatio', 'flex', 'flexBasis', 'flexGrow', 'height', 'minHeight'] as const
+
 /**
  * Splits a resolved style for a pressable with an Android ripple. The ripple is drawn as the pressable's foreground,
  * which its own `overflow: hidden` does not clip — so it would spill past rounded corners. A parent clips its
@@ -43,5 +46,11 @@ export const splitForRipple = (style: ViewStyle | undefined): {inner: ViewStyle[
     }
   }
 
-  return {inner: [FILL, inner as ViewStyle], outer: outer as ViewStyle}
+  // Only a sized outer view needs the pressable stretched to it. Sized by its content it must not be: Yoga grows a
+  // `flexGrow` child of a fit-content parent to the most it may take — inside a row centred on its cross axis, the
+  // pressable would stretch to the row's full height and leave its content at the top.
+  const sized =
+    SIZING_KEYS.some(key => flat[key] !== undefined) || (flat.top !== undefined && flat.bottom !== undefined)
+
+  return {inner: sized ? [FILL, inner as ViewStyle] : [inner as ViewStyle], outer: outer as ViewStyle}
 }

package/lib/module/atoms/activity-indicator/activity-indicator.js

@@ -1,14 +0,0 @@
-"use strict";
-
-import { useAppTheme } from '@hzblj/kara-theme';
-import { ActivityIndicator as RNActivityIndicator } from 'react-native';
-import { jsx as _jsx } from "react/jsx-runtime";
-export const ActivityIndicator = props => {
-  const theme = useAppTheme();
-  return /*#__PURE__*/_jsx(RNActivityIndicator, {
-    color: theme.color('fill.accent.primary'),
-    size: "small",
-    ...props
-  });
-};
-//# sourceMappingURL=activity-indicator.js.map

package/lib/module/atoms/activity-indicator/activity-indicator.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["useAppTheme","ActivityIndicator","RNActivityIndicator","jsx","_jsx","props","theme","color","size"],"sourceRoot":"../../../../src","sources":["atoms/activity-indicator/activity-indicator.tsx"],"mappings":";;AAAA,SAAQA,WAAW,QAAO,mBAAmB;AAE7C,SAAqCC,iBAAiB,IAAIC,mBAAmB,QAAO,cAAc;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAElG,OAAO,MAAMH,iBAA6C,GAAGI,KAAK,IAAI;EACpE,MAAMC,KAAK,GAAGN,WAAW,CAAC,CAAC;EAE3B,oBAAOI,IAAA,CAACF,mBAAmB;IAACK,KAAK,EAAED,KAAK,CAACC,KAAK,CAAC,qBAAqB,CAAE;IAACC,IAAI,EAAC,OAAO;IAAA,GAAKH;EAAK,CAAG,CAAC;AACnG,CAAC","ignoreList":[]}

package/src/atoms/activity-indicator/activity-indicator.tsx

@@ -1,9 +0,0 @@
-import {useAppTheme} from '@hzblj/kara-theme'
-import type {FC} from 'react'
-import {type ActivityIndicatorProps, ActivityIndicator as RNActivityIndicator} from 'react-native'
-
-export const ActivityIndicator: FC<ActivityIndicatorProps> = props => {
-  const theme = useAppTheme()
-
-  return <RNActivityIndicator color={theme.color('fill.accent.primary')} size="small" {...props} />
-}