@hzblj/kara-components 0.0.0-stage → 0.2.0

package/src/atoms/icon/icon.ios.tsx

@@ -0,0 +1,35 @@
+import {Image} from '@expo/ui/swift-ui'
+import {accessibilityHidden, frame, accessibilityLabel as labelModifier, resizable} from '@expo/ui/swift-ui/modifiers'
+import {iconResourceName} from '@hzblj/kara-native'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {IconComponent, IconProps} from './icon.types'
+
+/**
+ * The app's icon from its asset catalog — the template image set the config plugin generated from the SVG, vector data
+ * kept, so `resizable()` scales it crisply to the token size and the platform tints it.
+ */
+export const Icon: IconComponent = ({
+  accessibilityLabel,
+  color = 'content.primary',
+  name,
+  size = 's24',
+  testID,
+}: IconProps) => {
+  useHostGuard('Icon')
+  const theme = useAppTheme()
+  const side = spacing[size]
+
+  const modifiers = useMemo(
+    () => [
+      resizable(),
+      frame({height: side, width: side}),
+      accessibilityLabel ? labelModifier(accessibilityLabel) : accessibilityHidden(true),
+    ],
+    [accessibilityLabel, side]
+  )
+
+  return <Image assetName={iconResourceName(name)} color={theme.color(color)} modifiers={modifiers} testID={testID} />
+}

package/src/atoms/icon/icon.types.ts

@@ -0,0 +1,30 @@
+import type {ColorToken, SpaceSize} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+declare global {
+  /**
+   * The app's icon names, one key per SVG in its icon folder. Written by the config plugin
+   * (`plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}}]]`) into `kara-icons.d.ts`, or by
+   * `npx kara-icons`. Empty until then. Global, so the declaration reaches it without resolving any kara package.
+   */
+  interface KaraIcons {}
+}
+
+type DeclaredIconName = keyof KaraIcons & string
+
+/**
+ * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check — an icon removed
+ * from the folder fails at every call site. Before that, any string, so a project can adopt icons gradually.
+ */
+export type IconName = [DeclaredIconName] extends [never] ? string : DeclaredIconName
+
+export type IconProps = {
+  /** What a screen reader says. Unset, the icon is decorative and hidden from it. */
+  accessibilityLabel?: string
+  color?: ColorToken
+  name: IconName
+  size?: SpaceSize
+  testID?: string
+}
+
+export type IconComponent = (props: IconProps) => ReactNode

package/src/atoms/icon/index.ts

@@ -0,0 +1,2 @@
+export * from './icon'
+export * from './icon.types'

package/src/atoms/icon-button/icon-button.android.tsx

@@ -0,0 +1,15 @@
+import {IconButton as ComposeIconButton} from '@expo/ui/jetpack-compose'
+
+import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
+import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
+
+export const IconButton: IconButtonComponent = ({disabled = false, name, onPress}: IconButtonProps) => {
+  useHostGuard('IconButton')
+
+  return (
+    <ComposeIconButton enabled={!disabled} onClick={onPress}>
+      <Icon color={disabled ? 'btn.content.disabled' : 'content.primary'} name={name} />
+    </ComposeIconButton>
+  )
+}

package/src/atoms/icon-button/icon-button.ios.tsx

@@ -0,0 +1,27 @@
+import {Button} from '@expo/ui/swift-ui'
+import {buttonStyle, disabled as disabledModifier} from '@expo/ui/swift-ui/modifiers'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
+import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
+
+export const IconButton: IconButtonComponent = ({disabled = false, name, onPress, testID}: IconButtonProps) => {
+  useHostGuard('IconButton')
+
+  const modifiers = useMemo(() => {
+    const list = [buttonStyle('plain')]
+
+    if (disabled) {
+      list.push(disabledModifier(true))
+    }
+
+    return list
+  }, [disabled])
+
+  return (
+    <Button modifiers={modifiers} onPress={onPress} testID={testID}>
+      <Icon color={disabled ? 'btn.content.disabled' : 'content.primary'} name={name} />
+    </Button>
+  )
+}

package/src/atoms/icon-button/icon-button.types.ts

@@ -0,0 +1,12 @@
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../icon'
+
+export type IconButtonProps = {
+  disabled?: boolean
+  name: IconName
+  onPress?: () => void
+  testID?: string
+}
+
+export type IconButtonComponent = (props: IconButtonProps) => ReactNode

package/src/atoms/icon-button/index.ts

@@ -0,0 +1,2 @@
+export * from './icon-button'
+export * from './icon-button.types'

package/src/atoms/image/image.tsx

@@ -0,0 +1,15 @@
+import {duration} from '@hzblj/kara-theme'
+import {Image as ExpoImage, ImageProps} from 'expo-image'
+import {FC} from 'react'
+
+const Image: FC<ImageProps> = props => (
+  <ExpoImage
+    transition={{
+      duration: duration.d100,
+      timing: 'linear',
+    }}
+    {...props}
+  />
+)
+
+export {Image}

package/src/atoms/image/index.ts

@@ -0,0 +1 @@
+export * from './image'

package/src/atoms/index.ts

@@ -0,0 +1,40 @@
+export * from './activity-indicator'
+export * from './avatar'
+export * from './badge'
+export * from './box'
+export * from './button'
+export * from './card'
+export * from './checkbox'
+export * from './chip'
+export * from './color-picker'
+export * from './date-picker'
+export * from './divider'
+export * from './fab'
+export * from './flash-list'
+export * from './glass-view'
+export * from './h-stack'
+export * from './icon'
+export * from './icon-button'
+export * from './image'
+export * from './island'
+export * from './list'
+export * from './picker'
+export * from './pressable'
+export * from './progress'
+export * from './rn-flat-list'
+export * from './rn-icon'
+export * from './rn-scroll-view'
+export * from './rn-section-list'
+export * from './rn-text'
+export * from './rn-view'
+export * from './scroll-view'
+export * from './segmented-control'
+export * from './skeleton'
+export * from './slider'
+export * from './spacer'
+export * from './surface'
+export * from './switch'
+export * from './text'
+export * from './text-field'
+export * from './v-stack'
+export * from './z-stack'

package/src/atoms/island/index.ts

@@ -0,0 +1,2 @@
+export * from './island'
+export * from './island.types'

package/src/atoms/island/island.android.tsx

@@ -0,0 +1,24 @@
+import {Host} from '@expo/ui/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import {HostBoundary} from '../../host-context'
+import type {IslandComponent, IslandProps} from './island.types'
+
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
+const MATCH_NEITHER = {horizontal: false, vertical: false}
+
+export const Island: IslandComponent = ({children, matchContents = true, style}: IslandProps) => {
+  const theme = useAppTheme()
+
+  return (
+    <Host
+      colorScheme={theme.dark ? 'dark' : 'light'}
+      matchContents={matchContents ? MATCH_HEIGHT_ONLY : MATCH_NEITHER}
+      seedColor={theme.materialSeed}
+      style={style}
+    >
+      <HostBoundary>{children}</HostBoundary>
+    </Host>
+  )
+}

package/src/atoms/island/island.ios.tsx

@@ -0,0 +1,29 @@
+import {Host} from '@expo/ui/swift-ui'
+import {dynamicTypeSize} from '@expo/ui/swift-ui/modifiers'
+import {MAX_DYNAMIC_TYPE_SIZE, useAppTheme} from '@hzblj/kara-theme'
+
+import {HostBoundary} from '../../host-context'
+import type {IslandComponent, IslandProps} from './island.types'
+
+const DYNAMIC_TYPE_CAP = [dynamicTypeSize({max: MAX_DYNAMIC_TYPE_SIZE})]
+
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
+const MATCH_NEITHER = {horizontal: false, vertical: false}
+
+export const Island: IslandComponent = ({children, matchContents = true, style, testID}: IslandProps) => {
+  const theme = useAppTheme()
+
+  return (
+    <Host
+      colorScheme={theme.dark ? 'dark' : 'light'}
+      matchContents={matchContents ? MATCH_HEIGHT_ONLY : MATCH_NEITHER}
+      modifiers={DYNAMIC_TYPE_CAP}
+      seedColor={theme.materialSeed}
+      style={style}
+      testID={testID}
+    >
+      <HostBoundary>{children}</HostBoundary>
+    </Host>
+  )
+}

package/src/atoms/island/island.types.ts

@@ -0,0 +1,22 @@
+import type {ReactNode} from 'react'
+import type {StyleProp, ViewStyle} from 'react-native'
+
+export type IslandProps = {
+  children?: ReactNode
+  /**
+   * Sizes the island's height to its native content while the width still comes from the parent, which
+   * is what a full-width card wants. On by default. Only the height is ever measured: auto-sizing the
+   * width maps to `fixedSize(horizontal: true)`, so the native side ignores the proposed width and
+   * resolves a `wide` stack's ideal width as unbounded.
+   *
+   * Turn it off — and give the island an explicit size via `style` — when the subtree contains an
+   * `RnView`: that host drives its SwiftUI frame from the child's Yoga-laid-out bounds while this one
+   * writes its measured size back into the Yoga style, and the two together spin a layout loop that
+   * hangs the main thread as soon as the views lay out on screen.
+   */
+  matchContents?: boolean
+  style?: StyleProp<ViewStyle>
+  testID?: string
+}
+
+export type IslandComponent = (props: IslandProps) => ReactNode

package/src/atoms/list/index.ts

@@ -0,0 +1,2 @@
+export * from './list'
+export * from './list.types'

package/src/atoms/list/list.android.tsx

@@ -0,0 +1,34 @@
+import {LazyColumn, PullToRefreshBox} from '@expo/ui/jetpack-compose'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {Children, Fragment, isValidElement} from 'react'
+import {useHostGuard} from '../../host-context'
+import {useRefreshState} from '../../use-refresh-state'
+import {Divider} from '../divider'
+import type {ListComponent, ListProps} from './list.types'
+
+/** A divider between rows, the separator SwiftUI's `List` draws on its own — so rows are written the same for both. */
+const withSeparators = (children: ListProps['children']) =>
+  Children.toArray(children).map((child, index) => (
+    <Fragment key={isValidElement(child) && child.key !== null ? child.key : index}>
+      {index > 0 ? <Divider /> : null}
+      {child}
+    </Fragment>
+  ))
+
+export const List: ListComponent = ({children, onRefresh}: ListProps) => {
+  useHostGuard('List')
+  const modifiers = useSxModifiers({wide: true})
+  const {isRefreshing, refresh} = useRefreshState(onRefresh)
+
+  const column = <LazyColumn modifiers={modifiers}>{withSeparators(children)}</LazyColumn>
+
+  if (!onRefresh) {
+    return column
+  }
+
+  return (
+    <PullToRefreshBox isRefreshing={isRefreshing} onRefresh={refresh}>
+      {column}
+    </PullToRefreshBox>
+  )
+}

package/src/atoms/list/list.ios.tsx

@@ -0,0 +1,18 @@
+import {List as SwiftUIList} from '@expo/ui/swift-ui'
+import {type ModifierConfig, refreshable} from '@expo/ui/swift-ui/modifiers'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {ListComponent, ListProps} from './list.types'
+
+export const List: ListComponent = ({children, onRefresh, testID}: ListProps) => {
+  useHostGuard('List')
+
+  const modifiers = useMemo<ModifierConfig[]>(() => (onRefresh ? [refreshable(onRefresh)] : []), [onRefresh])
+
+  return (
+    <SwiftUIList modifiers={modifiers} testID={testID}>
+      {children}
+    </SwiftUIList>
+  )
+}

package/src/atoms/list/list.types.ts

@@ -0,0 +1,22 @@
+import type {ReactNode} from 'react'
+
+/**
+ * A scrolling list — SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
+ * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
+ * Compose measures it against an infinite height and throws ("Vertically scrollable component was measured with an
+ * infinity maximum height"); SwiftUI shows nothing. For a handful of rows that should not scroll, use a `VStack`.
+ *
+ * Rows are separated for you — SwiftUI's own separators, a `Divider` between rows on Android — so a `Divider` among
+ * the children is one too many: on iOS it becomes an empty row of its own.
+ */
+export type ListProps = {
+  children: ReactNode
+  /**
+   * Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs
+   * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
+   */
+  onRefresh?: () => Promise<void>
+  testID?: string
+}
+
+export type ListComponent = (props: ListProps) => ReactNode

package/src/atoms/picker/index.ts

@@ -0,0 +1,2 @@
+export * from './picker'
+export * from './picker.types'

package/src/atoms/picker/picker.android.tsx

@@ -0,0 +1,88 @@
+import {
+  Text as ComposeText,
+  DropdownMenuItem,
+  ExposedDropdownMenu,
+  ExposedDropdownMenuBox,
+  Host,
+  OutlinedTextField,
+  useNativeState,
+} from '@expo/ui/jetpack-compose'
+import {fillMaxWidth, menuAnchor, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useEffect, useMemo, useState} from 'react'
+
+import {Glyph} from '../../glyph'
+import {HostBoundary} from '../../host-context'
+import type {PickerComponent, PickerProps} from './picker.types'
+
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
+/**
+ * Material's exposed dropdown: a read-only outlined field the width of its container, opening a menu of the options
+ * under it. Its own host, themed like an `Island`, so it drops into React Native layout like the iOS picker does.
+ */
+export const Picker: PickerComponent = ({disabled = false, onValueChange, options, testID, value}: PickerProps) => {
+  const theme = useAppTheme()
+  const [expanded, setExpanded] = useState(false)
+  const selectedLabel = options.find(option => option.value === value)?.label ?? ''
+  const label = useNativeState(selectedLabel)
+  const fieldModifiers = useMemo(() => {
+    const list = [fillMaxWidth(), menuAnchor('primaryNotEditable', !disabled)]
+
+    return testID ? [...list, testIdModifier(testID)] : list
+  }, [disabled, testID])
+
+  // `useNativeState` takes only its initial value; a new selection is pushed to the field.
+  useEffect(() => {
+    label.set(selectedLabel)
+  }, [label, selectedLabel])
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents={MATCH_HEIGHT_ONLY} seedColor={theme.materialSeed}>
+      <HostBoundary>
+        <ExposedDropdownMenuBox expanded={expanded} onExpandedChange={disabled ? undefined : setExpanded}>
+          <OutlinedTextField
+            enabled={!disabled}
+            modifiers={fieldModifiers}
+            readOnly
+            singleLine
+            textStyle={{
+              color: theme.colorString('content.primary'),
+              fontFamily: theme.typography.body.fontFamily,
+              fontWeight: theme.typography.body.fontWeight,
+            }}
+            value={label}
+          >
+            <OutlinedTextField.TrailingIcon>
+              <Glyph color="content.secondary" name="chevronDown" size="s20" />
+            </OutlinedTextField.TrailingIcon>
+          </OutlinedTextField>
+          <ExposedDropdownMenu
+            containerColor={theme.color('surface.primary')}
+            expanded={expanded}
+            onDismissRequest={() => setExpanded(false)}
+          >
+            {options.map(option => (
+              <DropdownMenuItem
+                key={option.value}
+                onClick={() => {
+                  setExpanded(false)
+                  onValueChange?.(option.value)
+                }}
+              >
+                <DropdownMenuItem.Text>
+                  <ComposeText
+                    color={theme.colorString(option.value === value ? 'content.accent' : 'content.primary')}
+                    style={theme.typography.body}
+                  >
+                    {option.label}
+                  </ComposeText>
+                </DropdownMenuItem.Text>
+              </DropdownMenuItem>
+            ))}
+          </ExposedDropdownMenu>
+        </ExposedDropdownMenuBox>
+      </HostBoundary>
+    </Host>
+  )
+}

package/src/atoms/picker/picker.ios.tsx

@@ -0,0 +1,24 @@
+import {Picker as NativePicker} from '@expo/ui/community/picker'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback} from 'react'
+
+import type {PickerComponent, PickerProps} from './picker.types'
+
+export const Picker: PickerComponent = ({disabled = false, onValueChange, options, testID, value}: PickerProps) => {
+  const theme = useAppTheme()
+
+  const onChange = useCallback((next: string | number | null) => onValueChange?.(String(next)), [onValueChange])
+
+  return (
+    <NativePicker enabled={!disabled} onValueChange={onChange} selectedValue={value} testID={testID}>
+      {options.map(option => (
+        <NativePicker.Item
+          color={theme.colorString('content.primary')}
+          key={option.value}
+          label={option.label}
+          value={option.value}
+        />
+      ))}
+    </NativePicker>
+  )
+}

package/src/atoms/picker/picker.types.ts

@@ -0,0 +1,16 @@
+import type {ReactNode} from 'react'
+
+export type PickerOption = {
+  label: string
+  value: string
+}
+
+export type PickerProps = {
+  disabled?: boolean
+  onValueChange?: (value: string) => void
+  options: PickerOption[]
+  testID?: string
+  value: string
+}
+
+export type PickerComponent = (props: PickerProps) => ReactNode

package/src/atoms/pressable/index.ts

@@ -0,0 +1,2 @@
+export * from './pressable'
+export * from './pressable.types'

package/src/atoms/pressable/pressable.tsx

@@ -0,0 +1,55 @@
+import {useSplitSx} from '@hzblj/kara-sx'
+import * as Haptics from 'expo-haptics'
+import {useCallback} from 'react'
+import {Pressable as RNPressable} from 'react-native'
+import Animated, {useAnimatedStyle, useSharedValue, withSpring} from 'react-native-reanimated'
+import type {PressableComponent, PressableProps} from './pressable.types'
+
+const SPRING = {damping: 20, stiffness: 400}
+
+const AnimatedPressable = Animated.createAnimatedComponent(RNPressable)
+
+export const Pressable: PressableComponent = ({
+  children,
+  disabled = false,
+  haptic = false,
+  onPress,
+  testID,
+  ...props
+}: PressableProps) => {
+  const [resolved, rest] = useSplitSx(props)
+  const scale = useSharedValue(1)
+
+  const rStyle = useAnimatedStyle(() => ({transform: [{scale: scale.value}]}), [])
+
+  const onPressIn = useCallback(() => {
+    scale.value = withSpring(0.96, SPRING)
+  }, [scale])
+
+  const onPressOut = useCallback(() => {
+    scale.value = withSpring(1, SPRING)
+  }, [scale])
+
+  const onPressWithHaptic = useCallback(() => {
+    if (haptic) {
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light).catch(() => undefined)
+    }
+
+    onPress?.()
+  }, [haptic, onPress])
+
+  return (
+    <AnimatedPressable
+      disabled={disabled}
+      hitSlop={8}
+      onPress={onPressWithHaptic}
+      onPressIn={onPressIn}
+      onPressOut={onPressOut}
+      style={[resolved, rStyle]}
+      testID={testID}
+      {...rest}
+    >
+      {children}
+    </AnimatedPressable>
+  )
+}

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

@@ -0,0 +1,12 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
+import type {ReactNode} from 'react'
+
+export type PressableProps = ResponsiveViewSx & {
+  children?: ReactNode
+  disabled?: boolean
+  haptic?: boolean
+  onPress?: () => void
+  testID?: string
+}
+
+export type PressableComponent = (props: PressableProps) => ReactNode

package/src/atoms/progress/index.ts

@@ -0,0 +1,2 @@
+export * from './progress'
+export * from './progress.types'

package/src/atoms/progress/progress.android.tsx

@@ -0,0 +1,17 @@
+import {CircularProgressIndicator, LinearProgressIndicator} from '@expo/ui/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import {useHostGuard} from '../../host-context'
+import type {ProgressComponent, ProgressProps} from './progress.types'
+
+export const Progress: ProgressComponent = ({circular = false, value}: ProgressProps) => {
+  useHostGuard('Progress')
+  const theme = useAppTheme()
+  const color = theme.color('fill.accent.primary')
+
+  if (circular) {
+    return <CircularProgressIndicator color={color} progress={value} />
+  }
+
+  return <LinearProgressIndicator color={color} progress={value} />
+}

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

@@ -0,0 +1,19 @@
+import {ProgressView} from '@expo/ui/swift-ui'
+import {progressViewStyle, tint} from '@expo/ui/swift-ui/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {ProgressComponent, ProgressProps} from './progress.types'
+
+export const Progress: ProgressComponent = ({circular = false, value}: ProgressProps) => {
+  useHostGuard('Progress')
+  const theme = useAppTheme()
+
+  const modifiers = useMemo(
+    () => [progressViewStyle(circular ? 'circular' : 'linear'), tint(theme.color('fill.accent.primary'))],
+    [circular, theme]
+  )
+
+  return <ProgressView modifiers={modifiers} value={value ?? null} />
+}

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

@@ -0,0 +1,8 @@
+import type {ReactNode} from 'react'
+
+export type ProgressProps = {
+  circular?: boolean
+  value?: number
+}
+
+export type ProgressComponent = (props: ProgressProps) => ReactNode

package/src/atoms/rn-flat-list/index.ts

@@ -0,0 +1,2 @@
+export * from './rn-flat-list'
+export * from './rn-flat-list.types'

package/src/atoms/rn-flat-list/rn-flat-list.tsx

@@ -0,0 +1,32 @@
+import {useSplitSx, useSx} from '@hzblj/kara-sx'
+import {FlatList as RNFlatList} from 'react-native'
+
+import type {RnFlatListProps} from './rn-flat-list.types'
+
+/** Stands in for an absent `content`, because a hook cannot be called conditionally. */
+const NO_SX = {}
+
+/**
+ * Flat list built on React Native's own `VirtualizedList` rather than FlashList.
+ *
+ * FlashList is the default for lists in this codebase and should stay that way for data rows — reach
+ * for this only for the case it cannot serve: content that hosts native views. FlashList positions its
+ * rows absolutely and recycles their cells, and an `@expo/ui` host survives neither — the hosted view
+ * ends up drawn where the layout no longer is. `VirtualizedList` renders its cells in normal flow
+ * inside a scroll view, using blank spacers for the range it has not rendered, so a hosted view stays
+ * exactly where the layout put it. This is `SectionList`'s reason to exist too, without the sections.
+ */
+export const RnFlatList = <TItem,>({content, data, renderItem, ...props}: RnFlatListProps<TItem>) => {
+  const [style, rest] = useSplitSx(props as Record<string, unknown>)
+  const contentStyle = useSx(content ?? NO_SX)
+
+  return (
+    <RNFlatList<TItem>
+      data={data}
+      renderItem={renderItem}
+      {...rest}
+      contentContainerStyle={content === undefined ? undefined : contentStyle}
+      style={style}
+    />
+  )
+}