@hzblj/kara-components 0.9.0 → 0.11.0

package/src/organisms/sheet/sheet.types.ts

@@ -9,13 +9,13 @@ export type SheetDetent = 'auto' | number
 
 /**
  * `center` is iOS's own, `leading` Material's. `large` puts the title above the content in a large face, and once
- * that scrolls under the bar the bar's own title fades in — centred on iOS, leading on Android.
+ * that scrolls under the bar the bar's own title fades in (centred on iOS, leading on Android).
  */
 export type SheetTitleStyle = 'center' | 'large' | 'leading'
 
 /**
  * The sheet's header: a `NavigationBar` with the title and items, and anything else that should stay put above the
- * content (`children` — a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
+ * content (`children`: a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
  * with the system's scroll edge effect; elsewhere it sits above the content.
  */
 export type SheetHeaderProps = {
@@ -27,11 +27,11 @@ export type SheetHeaderProps = {
   leadingItems?: NavigationBarItem[]
   /** A search field in place of the title (iOS). */
   search?: NavigationBarSearch
-  /** The title — in the bar, or above the content with a `large` `titleStyle`. */
+  /** The title: in the bar, or above the content with a `large` `titleStyle`. */
   title?: string
   /** `center` by default. */
   titleStyle?: SheetTitleStyle
-  /** In screen order, toward the trailing edge — the close item, by convention. */
+  /** In screen order, toward the trailing edge: the close item, by convention. */
   trailingItems?: NavigationBarItem[]
 }
 
@@ -39,14 +39,14 @@ export type SheetHeaderProps = {
 export type SheetRef = {
   /** Dismisses it without calling `onDismiss`, which reports the user's dismissals only. */
   dismiss: () => Promise<void>
-  /** Presents at a detent — the first by default. */
+  /** Presents at a detent, the first by default. */
   present: (detentIndex?: number) => Promise<void>
   /** Moves to another detent. */
   resize: (detentIndex: number) => Promise<void>
 }
 
 /**
- * A native sheet — `UISheetPresentationController` on iOS, Material's bottom sheet on Android — with an optional
+ * A native sheet (`UISheetPresentationController` on iOS, Material's bottom sheet on Android) with an optional
  * native header (`<Sheet.Header>` as a direct child). The React Native tier: it needs no host, and must not sit inside
  * one; native atoms in its content go in an `Island`.
  */
@@ -55,7 +55,7 @@ export type SheetProps = {
   bg?: ColorToken
   /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
   children: ReactNode
-  /** Where the sheet can rest, smallest first. `['auto']` — fit the content — by default. */
+  /** Where the sheet can rest, smallest first. `['auto']` (fit the content) by default. */
   detents?: SheetDetent[]
   /** Dims what is behind. On by default. */
   dimmed?: boolean
@@ -67,9 +67,9 @@ export type SheetProps = {
   footer?: ReactElement
   /** The drag handle. On by default. */
   grabber?: boolean
-  /** The user dismissed it — `visible` going false does not call this. */
+  /** The user dismissed it; `visible` going false does not call this. */
   onDismiss: () => void
-  /** The sheet moved to another detent — its index in `detents`. */
+  /** The sheet moved to another detent: its index in `detents`. */
   onDetentChange?: (detentIndex: number) => void
   /** The sheet finished presenting. */
   onPresent?: () => void
@@ -77,7 +77,7 @@ export type SheetProps = {
   ref?: Ref<SheetRef>
   /**
    * The content is a scroll view (`<Sheet.ScrollView>`) the sheet drives: dragging past its top resizes the sheet,
-   * and a header scrolls with the iOS 26 edge effect. Off by default — set it with a scrolling body.
+   * and a header scrolls with the iOS 26 edge effect. Off by default; set it with a scrolling body.
    */
   scrollable?: boolean
   /** Test identifier, forwarded to the native sheet. */
@@ -92,7 +92,7 @@ export type SheetScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>
 export type SheetScrollContextValue = {
   /** Render it first in the content. `null` unless the header's `titleStyle` is `large`. */
   largeTitle: ReactNode
-  /** Forward the scroll view's scroll events to it — it tracks the large title. Unset when there is none. */
+  /** Forward the scroll view's scroll events to it; it tracks the large title. Unset when there is none. */
   onScroll?: SheetScrollHandler
   /** The room an overlaid header takes, to add to the content's top padding. `0` where the header sits above it. */
   topInset: number
@@ -105,7 +105,7 @@ export type SheetScrollContextValue = {
 export type SheetScrollViewProps = Pick<ScrollViewProps, 'keyboardShouldPersistTaps'> & {
   /** The scrolling content, after the large title if there is one. */
   children: ReactNode
-  /** Styles the scrolling content — padding and gap belong here, as with `RnScrollView`. */
+  /** Styles the scrolling content: padding and gap belong here, as with `RnScrollView`. */
   content?: ResponsiveViewSx
   /** Called on every scroll event, after the sheet's own listener. */
   onScroll?: SheetScrollHandler

package/src/organisms/snackbar/snackbar.tsx

@@ -1,41 +1,165 @@
-import {FadeInDown, FadeOutDown} from 'react-native-reanimated'
+import {duration as durations, easing, spacing, useReducedMotion} from '@hzblj/kara-theme'
+import {useEffect, useRef} from 'react'
+import {AccessibilityInfo, Platform} from 'react-native'
+import {
+  Easing,
+  type EntryExitAnimationFunction,
+  FadeIn,
+  FadeInDown,
+  FadeInUp,
+  FadeOut,
+  FadeOutDown,
+  FadeOutUp,
+  ReduceMotion,
+  withTiming,
+} from 'react-native-reanimated'
 
-import {ABox} from '../../atoms/box'
+import {ABox, Box} from '../../atoms/box'
 import {Pressable} from '../../atoms/pressable'
 import {RnText} from '../../atoms/rn-text'
-import type {SnackbarComponent, SnackbarProps} from './snackbar.types'
+import {RnGlyph} from '../../glyph'
+import {timing} from '../../motion'
+import type {SnackbarAnimation, SnackbarComponent, SnackbarDuration, SnackbarProps} from './snackbar.types'
+
+/** Material's `SnackbarDuration.Short` and `Long`. */
+const DURATIONS = {long: 10_000, short: 4_000} as const
+
+const PLATFORM_ANIMATION: SnackbarAnimation = Platform.OS === 'android' ? 'scale' : 'slide'
+
+/** The close glyph at the label's height: an SF Symbol fills its box, Material's icon sits inside a padded one. */
+const CLOSE_SIZE = Platform.OS === 'ios' ? 's12' : 's16'
+
+const SMOOTH_OUT = Easing.bezier(...easing.smoothOut)
+const GROW = timing('quick')
+
+/** Material's snackbar enter: it fades in while it grows from 80 %, in 150 ms. */
+const scaleIn: EntryExitAnimationFunction = () => {
+  'worklet'
+
+  return {
+    animations: {opacity: withTiming(1, GROW), transform: [{scale: withTiming(1, GROW)}]},
+    initialValues: {opacity: 0, transform: [{scale: 0.8}]},
+  }
+}
+
+/**
+ * The presets in and out: arriving in `fast`, leaving in `quick`, both on `smoothOut`. `ReduceMotion.Never`, because
+ * `useReducedMotion` has already picked the fade by then, and a fade is what should still run.
+ */
+const TRANSITIONS = {
+  fade: {
+    entering: FadeIn.duration(durations.fast).easing(SMOOTH_OUT).reduceMotion(ReduceMotion.Never),
+    exiting: FadeOut.duration(durations.quick).easing(SMOOTH_OUT).reduceMotion(ReduceMotion.Never),
+  },
+  // Material's exit is a 75 ms fade: `micro`.
+  scale: {entering: scaleIn, exiting: FadeOut.duration(durations.micro).reduceMotion(ReduceMotion.Never)},
+  // Slide: in from the edge it sits on, and back out toward it.
+  slideBottom: {
+    entering: FadeInDown.duration(durations.fast).easing(SMOOTH_OUT).reduceMotion(ReduceMotion.Never),
+    exiting: FadeOutDown.duration(durations.quick).easing(SMOOTH_OUT).reduceMotion(ReduceMotion.Never),
+  },
+  slideTop: {
+    entering: FadeInUp.duration(durations.fast).easing(SMOOTH_OUT).reduceMotion(ReduceMotion.Never),
+    exiting: FadeOutUp.duration(durations.quick).easing(SMOOTH_OUT).reduceMotion(ReduceMotion.Never),
+  },
+}
+
+const transitionsFor = (animation: SnackbarAnimation, position: 'bottom' | 'top') => {
+  if (animation === 'slide') {
+    return position === 'top' ? TRANSITIONS.slideTop : TRANSITIONS.slideBottom
+  }
+
+  return TRANSITIONS[animation]
+}
+
+const millisecondsOf = (duration: SnackbarDuration) =>
+  typeof duration === 'number' ? duration : duration === 'indefinite' ? undefined : DURATIONS[duration]
+
+export const Snackbar: SnackbarComponent = ({
+  actionLabel,
+  actionOnNewLine = false,
+  animation = PLATFORM_ANIMATION,
+  dismissible = false,
+  duration = 'indefinite',
+  entering,
+  exiting,
+  message,
+  offset = 's24',
+  onAction,
+  onDismiss,
+  position = 'bottom',
+  visible,
+}: SnackbarProps) => {
+  const reduced = useReducedMotion()
+  // A caller's inline `onDismiss` is a new function every render; the timer must not restart for it.
+  const dismiss = useRef(onDismiss)
+  dismiss.current = onDismiss
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a new `message` restarts the timer, as a new snackbar
+  useEffect(() => {
+    const milliseconds = millisecondsOf(duration)
+
+    if (!visible || milliseconds === undefined) {
+      return
+    }
+
+    const timer = setTimeout(() => dismiss.current?.(), milliseconds)
+
+    return () => clearTimeout(timer)
+  }, [duration, message, visible])
+
+  // Material's snackbar is announced; a React Native view is not unless asked.
+  useEffect(() => {
+    if (visible) {
+      AccessibilityInfo.announceForAccessibility(message)
+    }
+  }, [message, visible])
 
-export const Snackbar: SnackbarComponent = ({actionLabel, message, onAction, visible}: SnackbarProps) => {
   if (!visible) {
     return null
   }
 
+  const edge = position === 'top' ? {top: spacing[offset]} : {bottom: spacing[offset]}
+  const hasTrailing = Boolean(actionLabel) || dismissible
+  // With motion reduced it only fades: nothing slides or grows.
+  const preset = transitionsFor(reduced ? 'fade' : animation, position)
+
   return (
     <ABox
-      align="center"
+      align={actionOnNewLine ? 'stretch' : 'center'}
       bg="surface.high.contrast"
       borderRadius="medium"
-      bottom={24}
-      entering={FadeInDown}
-      exiting={FadeOutDown}
-      flexDirection="row"
-      gap="s12"
-      left={16}
+      flexDirection={actionOnNewLine ? 'column' : 'row'}
+      gap={actionOnNewLine ? 's8' : 's12'}
+      left={spacing.s16}
       position="absolute"
       px="s16"
       py="s12"
-      right={16}
+      right={spacing.s16}
       shadow="snackbar"
+      {...edge}
+      entering={entering ?? preset.entering}
+      exiting={exiting ?? preset.exiting}
     >
-      <RnText color="content.on.high.contrast" variant="footnote">
+      {/* It takes the room, so the action sits at the trailing end, as far in from it as the message is from the start. */}
+      <RnText color="content.on.high.contrast" flex={actionOnNewLine ? undefined : 1} variant="footnote">
         {message}
       </RnText>
-      {actionLabel ? (
-        <Pressable onPress={onAction}>
-          <RnText color="content.accent" variant="footnoteMedium">
-            {actionLabel}
-          </RnText>
-        </Pressable>
+      {hasTrailing ? (
+        <Box align="center" alignSelf={actionOnNewLine ? 'flex-end' : undefined} flexDirection="row" gap="s16">
+          {actionLabel ? (
+            <Pressable onPress={onAction} pressEffect="opacity" ripple={false}>
+              <RnText color="content.accent" variant="footnoteMedium">
+                {actionLabel}
+              </RnText>
+            </Pressable>
+          ) : null}
+          {dismissible ? (
+            <Pressable accessibilityLabel="Dismiss" onPress={onDismiss} pressEffect="opacity" ripple={false}>
+              <RnGlyph color="content.on.high.contrast" name="close" size={CLOSE_SIZE} />
+            </Pressable>
+          ) : null}
+        </Box>
       ) : null}
     </ABox>
   )

package/src/organisms/snackbar/snackbar.types.ts

@@ -1,17 +1,53 @@
-import type {ReactNode} from 'react'
+import type {SpaceSize} from '@hzblj/kara-theme'
+import type {ComponentProps, ReactNode} from 'react'
+import type Animated from 'react-native-reanimated'
+
+type LayoutAnimation = ComponentProps<typeof Animated.View>['entering']
+
+/** How it comes and goes. */
+export type SnackbarAnimation = 'fade' | 'scale' | 'slide'
+
+/** How long it stays: Material's short (4 s) and long (10 s), never, or a number of milliseconds. */
+export type SnackbarDuration = 'indefinite' | 'long' | 'short' | number
+
+/** The edge of its parent it sits on. */
+export type SnackbarPosition = 'bottom' | 'top'
 
 /**
- * A short message laid over the bottom of its parent, with an optional action. The React Native tier, drawn the same on
- * both platforms: it needs no host, and it never hides itself.
+ * A short message laid over an edge of its parent, with an optional action at its trailing end. The React Native tier,
+ * drawn the same on both platforms (iOS has no snackbar of its own), so it needs no host. Material's options are all
+ * here: a duration, a dismiss button, the action on a line of its own. It is announced to VoiceOver and TalkBack when
+ * it appears.
  */
 export type SnackbarProps = {
-  /** The action button's text, on the trailing side. No button without it. */
+  /** The action button's text, at the trailing end. No button without it. */
   actionLabel?: string
+  /** Puts the action under the message, at its trailing end: Material's layout for a long message or action. */
+  actionOnNewLine?: boolean
+  /**
+   * How it comes and goes. `scale` is Material's own (a fade and a scale from 80 %), `slide` rises from its edge as it
+   * fades in, `fade` only fades. `scale` on Android and `slide` on iOS by default. With motion reduced, it fades.
+   */
+  animation?: SnackbarAnimation
+  /** A close button at the trailing end, Material's dismiss action; it calls `onDismiss`. */
+  dismissible?: boolean
+  /** How long it stays up before `onDismiss` is called. `indefinite` by default: it never hides itself. */
+  duration?: SnackbarDuration
+  /** A Reanimated entering animation of your own, e.g. `FadeInDown.springify()`. It wins over `animation`. */
+  entering?: LayoutAnimation
+  /** A Reanimated exiting animation of your own. It wins over `animation`. */
+  exiting?: LayoutAnimation
   /** The message. */
   message: string
-  /** The action was pressed. The snackbar stays up — turn `visible` off to hide it. */
+  /** Between the snackbar and its edge, a space token. `s24` by default; raise it above a tab bar. */
+  offset?: SpaceSize
+  /** The action was pressed. The snackbar stays up; turn `visible` off to hide it. */
   onAction?: () => void
-  /** Shows the snackbar while true, fading it in and out. It sets no timer of its own. */
+  /** It asks to go: its `duration` ran out, or its dismiss button was pressed. Turn `visible` off to hide it. */
+  onDismiss?: () => void
+  /** The edge of its parent it sits on. `bottom` by default, Material's place for it. */
+  position?: SnackbarPosition
+  /** Shows the snackbar while true, animating it in and out. */
   visible: boolean
 }
 

package/src/organisms/swipe-actions/swipe-actions.android.tsx

@@ -49,7 +49,7 @@ type ActionButtonProps = {action: SwipeAction; onDone: () => void}
 const ActionButton = ({action, onDone}: ActionButtonProps) => {
   const theme = useAppTheme()
   const fill = action.tint ?? (action.destructive ? 'fill.destructive.primary' : 'fill.accent.primary')
-  const content = !action.tint && action.destructive ? 'content.on.destructive' : 'content.on.bg'
+  const content = !action.tint && action.destructive ? 'content.on.destructive' : 'content.on.accent'
 
   const onClick = useCallback(() => {
     onDone()

package/src/organisms/swipe-actions/swipe-actions.types.ts

@@ -7,26 +7,26 @@ import type {IconName} from '../../atoms/icon'
 export type SwipeAction = {
   /** Fills the button with `fill.destructive.primary` unless `tint` says otherwise. */
   destructive?: boolean
-  /** One of the app's icons, on the button — a round one on iOS 26, as in Mail, a filled stadium on Android. */
+  /** One of the app's icons, on the button: a round one on iOS 26, as in Mail, a filled stadium on Android. */
   icon: IconName
   /**
-   * The action's name, written under the button — before iOS 26 a row of the usual height shows the icon alone and
+   * The action's name, written under the button; before iOS 26 a row of the usual height shows the icon alone and
    * keeps the label for VoiceOver. Actions are keyed by it, so keep labels unique within one row.
    */
   label: string
   /** Called when the button is pressed. The row closes by itself. */
   onPress: () => void
   /**
-   * The button's fill — `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
+   * The button's fill: `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
    * on it is white, so pick a fill that holds white in both appearances.
    */
   tint?: ColorToken
 }
 
 /**
- * A list row with buttons behind it, uncovered by a swipe — SwiftUI's `swipeActions` on iOS, and on Android, where
+ * A list row with buttons behind it, uncovered by a swipe. SwiftUI's `swipeActions` on iOS, and on Android, where
  * Compose has none, kara's own: the row slides on an anchored drag and the buttons show in the strip it leaves. One
- * row is open at a time on both; a tap on an open row closes it. A native organism — it belongs inside a `List`.
+ * row is open at a time on both; a tap on an open row closes it. A native organism: it belongs inside a `List`.
  */
 export type SwipeActionsProps = {
   /**

package/src/templates/screen/screen.types.ts

@@ -2,7 +2,7 @@ import type {Sx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
 /**
- * The full-bleed native host a screen starts with — a SwiftUI or Compose `Host` filling its parent, so native atoms
+ * The full-bleed native host a screen starts with: a SwiftUI or Compose `Host` filling its parent, so native atoms
  * render anywhere inside it. The background runs to the edges; the content keeps clear of the status bar where the
  * screen covers it (no navigation bar above), on Android as SwiftUI's safe area does on iOS.
  */
@@ -13,7 +13,7 @@ export type ScreenProps = {
   children?: ReactNode
   /** Keeps the content where it is when the keyboard opens, instead of avoiding it. Android reads it once, on mount. */
   ignoreKeyboardInset?: boolean
-  /** Test identifier — on the host view on iOS, on the view around it on Android. */
+  /** Test identifier, on the host view on iOS and on the view around it on Android. */
   testID?: string
 }
 

package/src/use-stack-modifiers.ts

@@ -1,24 +1,37 @@
 import {clickable, type ModifierConfig, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
-import {type ResponsiveSx, useSxModifiers} from '@hzblj/kara-sx'
+import {
+  type AccessibilityProps,
+  type ResponsiveSx,
+  splitAccessibility,
+  useAccessibilityModifiers,
+  useSxModifiers,
+} from '@hzblj/kara-sx'
 import {useMemo} from 'react'
 
 /**
- * A Compose stack's modifiers in the order a pressable one needs: its frame, shape and background, then the press,
- * then its padding. Compose clips a `clickable` to what comes after it, so with the padding first the ripple would stop
- * at the padding and a row pressed by its edge would light up only in the middle.
+ * A Compose stack's modifiers in the order a pressable one needs: its frame, shape and background, then the press, its
+ * semantics, then its padding. Compose clips a `clickable` to what comes after it, so with the padding first the ripple
+ * would stop at the padding and a row pressed by its edge would light up only in the middle. The semantics come after
+ * the click, because a label that replaces the children's clears whatever semantics are inside it.
  */
-export const useStackModifiers = (sx: ResponsiveSx, onPress?: () => void, testID?: string): ModifierConfig[] => {
-  const {p, pb, pl, pr, pt, px, py, ...frame} = sx
+export const useStackModifiers = (
+  props: ResponsiveSx & AccessibilityProps,
+  onPress?: () => void,
+  testID?: string
+): ModifierConfig[] => {
+  const [accessibility, {p, pb, pl, pr, pt, px, py, ...frame}] = splitAccessibility(props)
   const frameModifiers = useSxModifiers(frame)
   const paddingModifiers = useSxModifiers({p, pb, pl, pr, pt, px, py})
+  const accessibilityModifiers = useAccessibilityModifiers(accessibility, onPress !== undefined)
 
   return useMemo(
     () => [
       ...frameModifiers,
       ...(testID ? [testIdModifier(testID)] : []),
       ...(onPress ? [clickable(onPress)] : []),
+      ...accessibilityModifiers,
       ...paddingModifiers,
     ],
-    [frameModifiers, onPress, paddingModifiers, testID]
+    [accessibilityModifiers, frameModifiers, onPress, paddingModifiers, testID]
   )
 }

package/lib/module/platform-support.js

@@ -1,19 +0,0 @@
-"use strict";
-
-const warned = new Set();
-
-/**
- * Announces an atom that only one platform can implement. The stub still satisfies the shared
- * component type, so `contract.check.ts` keeps both files honest — this just makes the gap loud
- * in dev instead of leaving a control that mysteriously never appears.
- *
- * Warns once per atom: the gap is permanent, so repeating it every render would be noise.
- */
-export const warnUnsupported = (atom, platform) => {
-  if (!__DEV__ || warned.has(atom)) {
-    return;
-  }
-  warned.add(atom);
-  console.error(`[kara-ui] <${atom}> has no ${platform} implementation and renders nothing there. Branch on Platform.OS at the call site.`);
-};
-//# sourceMappingURL=platform-support.js.map

package/lib/module/platform-support.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["warned","Set","warnUnsupported","atom","platform","__DEV__","has","add","console","error"],"sourceRoot":"../../src","sources":["platform-support.ts"],"mappings":";;AAAA,MAAMA,MAAM,GAAG,IAAIC,GAAG,CAAS,CAAC;;AAEhC;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGA,CAACC,IAAY,EAAEC,QAA2B,KAAK;EAC5E,IAAI,CAACC,OAAO,IAAIL,MAAM,CAACM,GAAG,CAACH,IAAI,CAAC,EAAE;IAChC;EACF;EAEAH,MAAM,CAACO,GAAG,CAACJ,IAAI,CAAC;EAEhBK,OAAO,CAACC,KAAK,CACX,cAAcN,IAAI,YAAYC,QAAQ,oFACxC,CAAC;AACH,CAAC","ignoreList":[]}

package/lib/typescript/platform-support.d.ts

@@ -1,8 +0,0 @@
-/**
- * Announces an atom that only one platform can implement. The stub still satisfies the shared
- * component type, so `contract.check.ts` keeps both files honest — this just makes the gap loud
- * in dev instead of leaving a control that mysteriously never appears.
- *
- * Warns once per atom: the gap is permanent, so repeating it every render would be noise.
- */
-export declare const warnUnsupported: (atom: string, platform: 'Android' | 'iOS') => void;

package/src/platform-support.ts

@@ -1,20 +0,0 @@
-const warned = new Set<string>()
-
-/**
- * Announces an atom that only one platform can implement. The stub still satisfies the shared
- * component type, so `contract.check.ts` keeps both files honest — this just makes the gap loud
- * in dev instead of leaving a control that mysteriously never appears.
- *
- * Warns once per atom: the gap is permanent, so repeating it every render would be noise.
- */
-export const warnUnsupported = (atom: string, platform: 'Android' | 'iOS') => {
-  if (!__DEV__ || warned.has(atom)) {
-    return
-  }
-
-  warned.add(atom)
-
-  console.error(
-    `[kara-ui] <${atom}> has no ${platform} implementation and renders nothing there. Branch on Platform.OS at the call site.`
-  )
-}