@hzblj/kara-components 0.0.0-stage → 0.2.0

package/src/atoms/checkbox/checkbox.ios.tsx

@@ -0,0 +1,24 @@
+import {Toggle} from '@expo/ui/swift-ui'
+import {disabled as disabledModifier, tint} from '@expo/ui/swift-ui/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {CheckboxComponent, CheckboxProps} from './checkbox.types'
+
+export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, value}: CheckboxProps) => {
+  useHostGuard('Checkbox')
+  const theme = useAppTheme()
+
+  const modifiers = useMemo(() => {
+    const list = [tint(theme.color('fill.accent.primary'))]
+
+    if (disabled) {
+      list.push(disabledModifier(true))
+    }
+
+    return list
+  }, [disabled, theme])
+
+  return <Toggle isOn={value} label={label} modifiers={modifiers} onIsOnChange={onValueChange} />
+}

package/src/atoms/checkbox/checkbox.types.ts

@@ -0,0 +1,10 @@
+import type {ReactNode} from 'react'
+
+export type CheckboxProps = {
+  disabled?: boolean
+  label?: string
+  onValueChange?: (value: boolean) => void
+  value: boolean
+}
+
+export type CheckboxComponent = (props: CheckboxProps) => ReactNode

package/src/atoms/checkbox/index.ts

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

package/src/atoms/chip/chip.tsx

@@ -0,0 +1,23 @@
+import {Pressable} from '../pressable'
+import {RnText} from '../rn-text'
+import type {ChipComponent, ChipProps} from './chip.types'
+
+export const Chip: ChipComponent = ({label, onPress, selected = false, testID}: ChipProps) => (
+  <Pressable
+    align="center"
+    bg={selected ? 'fill.accent.base' : 'fill.tertiary'}
+    borderColor={selected ? 'border.accent' : 'border.tertiary'}
+    borderRadius="full"
+    borderWidth={1}
+    haptic
+    justify="center"
+    onPress={onPress}
+    px="s12"
+    py="s6"
+    testID={testID}
+  >
+    <RnText color={selected ? 'content.accent' : 'content.secondary'} variant="labelMedium">
+      {label}
+    </RnText>
+  </Pressable>
+)

package/src/atoms/chip/chip.types.ts

@@ -0,0 +1,10 @@
+import type {ReactNode} from 'react'
+
+export type ChipProps = {
+  label: string
+  onPress?: () => void
+  selected?: boolean
+  testID?: string
+}
+
+export type ChipComponent = (props: ChipProps) => ReactNode

package/src/atoms/chip/index.ts

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

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

@@ -0,0 +1,9 @@
+import {warnUnsupported} from '../../platform-support'
+import type {ColorPickerComponent} from './color-picker.types'
+
+/** Compose has no colour picker, and there is nothing sane to degrade a colour wheel into. */
+export const ColorPicker: ColorPickerComponent = () => {
+  warnUnsupported('ColorPicker', 'Android')
+
+  return null
+}

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

@@ -0,0 +1,24 @@
+import {ColorPicker as SwiftUIColorPicker} from '@expo/ui/swift-ui'
+
+import {useHostGuard} from '../../host-context'
+import type {ColorPickerComponent, ColorPickerProps} from './color-picker.types'
+
+export const ColorPicker: ColorPickerComponent = ({
+  label,
+  onValueChange,
+  supportsOpacity = false,
+  testID,
+  value,
+}: ColorPickerProps) => {
+  useHostGuard('ColorPicker')
+
+  return (
+    <SwiftUIColorPicker
+      label={label}
+      onSelectionChange={onValueChange}
+      selection={value}
+      supportsOpacity={supportsOpacity}
+      testID={testID}
+    />
+  )
+}

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

@@ -0,0 +1,16 @@
+import type {ReactNode} from 'react'
+
+/**
+ * The system colour picker. iOS only — Compose ships no equivalent, so on Android this
+ * renders nothing and says so in dev. Branch on `Platform.OS` if the screen needs a fallback.
+ */
+export type ColorPickerProps = {
+  label?: string
+  onValueChange?: (color: string) => void
+  supportsOpacity?: boolean
+  testID?: string
+  /** `#RRGGBB` or `#RRGGBBAA`. */
+  value: string | null
+}
+
+export type ColorPickerComponent = (props: ColorPickerProps) => ReactNode

package/src/atoms/color-picker/index.ts

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

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

@@ -0,0 +1,74 @@
+import {DateTimePicker} from '@expo/ui/community/datetime-picker'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useState} from 'react'
+
+import {Pressable} from '../pressable'
+import {RnText} from '../rn-text'
+import type {DatePickerComponent, DatePickerMode, DatePickerProps} from './date-picker.types'
+
+const formatted = (value: Date, mode: DatePickerMode): string => {
+  if (mode === 'time') {
+    return value.toLocaleTimeString(undefined, {hour: '2-digit', minute: '2-digit'})
+  }
+
+  const date = value.toLocaleDateString(undefined, {day: 'numeric', month: 'short', year: 'numeric'})
+
+  return mode === 'datetime'
+    ? `${date} ${value.toLocaleTimeString(undefined, {hour: '2-digit', minute: '2-digit'})}`
+    : date
+}
+
+/**
+ * The value as a field that opens Material's date picker dialog on a tap. Android's picker *is* a dialog — mounted, it
+ * opens — so it is mounted only while open, and unmounted on confirm or dismiss, as the component asks its caller to.
+ */
+export const DatePicker: DatePickerComponent = ({
+  max,
+  min,
+  mode = 'date',
+  onValueChange,
+  testID,
+  value,
+}: DatePickerProps) => {
+  const theme = useAppTheme()
+  const [open, setOpen] = useState(false)
+
+  const show = useCallback(() => setOpen(true), [])
+  const hide = useCallback(() => setOpen(false), [])
+
+  const onChange = useCallback(
+    (_event: unknown, date: Date) => {
+      setOpen(false)
+      onValueChange?.(date)
+    },
+    [onValueChange]
+  )
+
+  return (
+    <>
+      <Pressable
+        alignSelf="flex-start"
+        bg="fill.tertiary"
+        borderRadius="medium"
+        onPress={show}
+        px="s12"
+        py="s8"
+        testID={testID}
+      >
+        <RnText variant="body">{formatted(value, mode)}</RnText>
+      </Pressable>
+      {open ? (
+        <DateTimePicker
+          accentColor={theme.colorString('fill.accent.primary')}
+          maximumDate={max}
+          minimumDate={min}
+          mode={mode}
+          onDismiss={hide}
+          onValueChange={onChange}
+          presentation="dialog"
+          value={value}
+        />
+      ) : null}
+    </>
+  )
+}

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

@@ -0,0 +1,27 @@
+import {DateTimePicker} from '@expo/ui/community/datetime-picker'
+import {useCallback} from 'react'
+
+import type {DatePickerComponent, DatePickerProps} from './date-picker.types'
+
+/** The system's compact date picker, inline: a tap on it opens the calendar popover UIKit owns. */
+export const DatePicker: DatePickerComponent = ({
+  max,
+  min,
+  mode = 'date',
+  onValueChange,
+  testID,
+  value,
+}: DatePickerProps) => {
+  const onChange = useCallback((_event: unknown, date: Date) => onValueChange?.(date), [onValueChange])
+
+  return (
+    <DateTimePicker
+      maximumDate={max}
+      minimumDate={min}
+      mode={mode}
+      onValueChange={onChange}
+      testID={testID}
+      value={value}
+    />
+  )
+}

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

@@ -0,0 +1,14 @@
+import type {ReactNode} from 'react'
+
+export type DatePickerMode = 'date' | 'datetime' | 'time'
+
+export type DatePickerProps = {
+  max?: Date
+  min?: Date
+  mode?: DatePickerMode
+  onValueChange?: (date: Date) => void
+  testID?: string
+  value: Date
+}
+
+export type DatePickerComponent = (props: DatePickerProps) => ReactNode

package/src/atoms/date-picker/index.ts

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

package/src/atoms/divider/divider.android.tsx

@@ -0,0 +1,12 @@
+import {HorizontalDivider} from '@expo/ui/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import {useHostGuard} from '../../host-context'
+import type {DividerComponent, DividerProps} from './divider.types'
+
+export const Divider: DividerComponent = ({color = 'border.tertiary'}: DividerProps) => {
+  useHostGuard('Divider')
+  const theme = useAppTheme()
+
+  return <HorizontalDivider color={theme.color(color)} />
+}

package/src/atoms/divider/divider.ios.tsx

@@ -0,0 +1,15 @@
+import {Divider as SwiftUIDivider} from '@expo/ui/swift-ui'
+import {background} from '@expo/ui/swift-ui/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {DividerComponent, DividerProps} from './divider.types'
+
+export const Divider: DividerComponent = ({color = 'border.tertiary', testID}: DividerProps) => {
+  useHostGuard('Divider')
+  const theme = useAppTheme()
+  const modifiers = useMemo(() => [background(theme.color(color))], [color, theme])
+
+  return <SwiftUIDivider modifiers={modifiers} testID={testID} />
+}

package/src/atoms/divider/divider.types.ts

@@ -0,0 +1,9 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+export type DividerProps = {
+  color?: ColorToken
+  testID?: string
+}
+
+export type DividerComponent = (props: DividerProps) => ReactNode

package/src/atoms/divider/index.ts

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

package/src/atoms/fab/fab.android.tsx

@@ -0,0 +1,21 @@
+import {FloatingActionButton} from '@expo/ui/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
+import type {FabComponent, FabProps} from './fab.types'
+
+export const Fab: FabComponent = ({name, onPress}: FabProps) => {
+  useHostGuard('Fab')
+
+  const theme = useAppTheme()
+
+  return (
+    <FloatingActionButton containerColor={theme.color('fill.accent.primary')} onClick={onPress}>
+      {/* `@expo/ui`'s FAB is slot-based: content outside `.Icon` is not composed at all. */}
+      <FloatingActionButton.Icon>
+        <Icon color="content.on.bg" name={name} />
+      </FloatingActionButton.Icon>
+    </FloatingActionButton>
+  )
+}

package/src/atoms/fab/fab.ios.tsx

@@ -0,0 +1,27 @@
+import {Button} from '@expo/ui/swift-ui'
+import {buttonStyle} from '@expo/ui/swift-ui/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
+import type {FabComponent, FabProps} from './fab.types'
+
+export const Fab: FabComponent = ({name, onPress, testID}: FabProps) => {
+  useHostGuard('Fab')
+
+  const sxModifiers = useSxModifiers({
+    bg: 'fill.accent.primary',
+    borderRadius: 'full',
+    h: 56,
+    p: 's16',
+    shadow: 'btn.accent',
+    w: 56,
+  })
+  const modifiers = useMemo(() => [buttonStyle('plain'), ...sxModifiers], [sxModifiers])
+
+  return (
+    <Button modifiers={modifiers} onPress={onPress} testID={testID}>
+      <Icon color="content.on.bg" name={name} />
+    </Button>
+  )
+}

package/src/atoms/fab/fab.types.ts

@@ -0,0 +1,11 @@
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../icon'
+
+export type FabProps = {
+  name: IconName
+  onPress?: () => void
+  testID?: string
+}
+
+export type FabComponent = (props: FabProps) => ReactNode

package/src/atoms/fab/index.ts

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

package/src/atoms/flash-list/flash-list.tsx

@@ -0,0 +1,28 @@
+import {useSplitSx, useSx} from '@hzblj/kara-sx'
+import {FlashList as ShopifyFlashList} from '@shopify/flash-list'
+
+import type {FlashListProps} from './flash-list.types'
+
+/** Stands in for an absent `content`, because a hook cannot be called conditionally. */
+const NO_SX = {}
+
+/**
+ * The default list in this codebase: recycles its rows, so it holds a long list at a steady cost.
+ *
+ * `RnFlatList` and `RnSectionList` are the alternatives, and only for rows that host native views —
+ * see either one for why recycling and absolute positioning cannot carry an `@expo/ui` host.
+ */
+export const FlashList = <TItem,>({content, data, renderItem, ...props}: FlashListProps<TItem>) => {
+  const [style, rest] = useSplitSx(props as Record<string, unknown>)
+  const contentStyle = useSx(content ?? NO_SX)
+
+  return (
+    <ShopifyFlashList
+      data={data}
+      renderItem={renderItem}
+      {...rest}
+      contentContainerStyle={content === undefined ? undefined : contentStyle}
+      style={style}
+    />
+  )
+}

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

@@ -0,0 +1,20 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
+import type {FlashListRef, FlashListProps as ShopifyFlashListProps} from '@shopify/flash-list'
+import type {Ref} from 'react'
+
+/**
+ * Top-level `sx` styles the viewport; `content` styles the scrolling content container — the same split
+ * as `RnScrollView` and the React Native lists.
+ *
+ * Padding belongs in `content` here and nowhere else. FlashList measures its rows against its own
+ * `style`, and padding there throws that measurement off; its docs put it as "margin is okay but padding
+ * is not". `content` has no such limit, because it lands on the scroll view's content container.
+ *
+ * `ref` is declared because this is a wrapper rather than the re-export it used to be — React 19 passes
+ * it as a plain prop, and a `FlashListRef` is how a caller reaches `scrollToIndex` and friends.
+ */
+export type FlashListProps<TItem> = ResponsiveViewSx &
+  Omit<ShopifyFlashListProps<TItem>, 'contentContainerStyle' | 'style'> & {
+    content?: ResponsiveViewSx
+    ref?: Ref<FlashListRef<TItem>>
+  }

package/src/atoms/flash-list/index.ts

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

package/src/atoms/glass-view/glass-fallback.tsx

@@ -0,0 +1,12 @@
+import {Box} from '../box'
+import type {GlassViewProps} from './glass-view.types'
+
+/**
+ * The capsule drawn where there is no Liquid Glass to draw: the glass buttons' own translucent fill, so whatever sits
+ * on the glass — usually content meant for a colourful backdrop — stays readable, the way it would on real glass.
+ */
+export const GlassFallback = ({children, interactive: _interactive, tint, ...props}: GlassViewProps) => (
+  <Box borderRadius="full" {...props} bg={tint ?? 'btn.bg.glass.base'}>
+    {children}
+  </Box>
+)

package/src/atoms/glass-view/glass-view.android.tsx

@@ -0,0 +1,5 @@
+import {GlassFallback} from './glass-fallback'
+import type {GlassViewComponent, GlassViewProps} from './glass-view.types'
+
+/** Android has no Liquid Glass, so this is always the fallback capsule. */
+export const GlassView: GlassViewComponent = (props: GlassViewProps) => <GlassFallback {...props} />

package/src/atoms/glass-view/glass-view.ios.tsx

@@ -0,0 +1,30 @@
+import {isLiquidGlassAvailable} from '@hzblj/kara-native'
+import {GlassView as NativeGlassView} from '@hzblj/kara-native/swift-ui'
+import {useSx} from '@hzblj/kara-sx'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {GlassFallback} from './glass-fallback'
+import type {GlassViewComponent, GlassViewProps} from './glass-view.types'
+
+/**
+ * The native view is a capsule by construction — its corner radius follows its bounds — so `borderRadius` is the
+ * fallback's business only.
+ */
+const LiquidGlass = ({children, interactive = false, testID, tint, ...sx}: GlassViewProps) => {
+  const theme = useAppTheme()
+  const style = useSx(sx)
+
+  return (
+    <NativeGlassView
+      colorScheme={theme.dark ? 'dark' : 'light'}
+      glassTint={tint ? theme.color(tint) : undefined}
+      isInteractive={interactive}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </NativeGlassView>
+  )
+}
+
+export const GlassView: GlassViewComponent = (props: GlassViewProps) =>
+  isLiquidGlassAvailable() ? <LiquidGlass {...props} /> : <GlassFallback {...props} />

package/src/atoms/glass-view/glass-view.types.ts

@@ -0,0 +1,20 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
+import type {ColorToken} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+/**
+ * iOS 26 Liquid Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host
+ * and costs next to nothing in a list cell. Where there is no Liquid Glass (Android, and iOS before 26) it draws a
+ * capsule of `tint` instead, or of the glass buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ */
+export type GlassViewProps = ResponsiveViewSx & {
+  /** React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`. */
+  children?: ReactNode
+  /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
+  interactive?: boolean
+  testID?: string
+  /** Tints the material. Unset leaves it clear. */
+  tint?: ColorToken
+}
+
+export type GlassViewComponent = (props: GlassViewProps) => ReactNode

package/src/atoms/glass-view/index.ts

@@ -0,0 +1,3 @@
+export {isLiquidGlassAvailable} from '@hzblj/kara-native'
+export * from './glass-view'
+export * from './glass-view.types'

package/src/atoms/h-stack/h-stack.android.tsx

@@ -0,0 +1,39 @@
+import {Row} from '@expo/ui/jetpack-compose'
+import {clickable, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {spacing} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import type {HStackAlign, HStackComponent, HStackProps} from './h-stack.types'
+
+const ALIGNMENT = {
+  center: 'center',
+  end: 'bottom',
+  start: 'top',
+} as const satisfies Record<HStackAlign, string>
+
+export const HStack: HStackComponent = ({
+  align = 'start',
+  children,
+  onPress,
+  spacing: gap,
+  testID,
+  ...sx
+}: HStackProps) => {
+  useHostGuard('HStack')
+  const sxModifiers = useSxModifiers(sx)
+  const modifiers = useMemo(
+    () => [...sxModifiers, ...(testID ? [testIdModifier(testID)] : []), ...(onPress ? [clickable(onPress)] : [])],
+    [onPress, sxModifiers, testID]
+  )
+
+  return (
+    <Row
+      verticalAlignment={ALIGNMENT[align]}
+      horizontalArrangement={gap === undefined ? undefined : {spacedBy: spacing[gap]}}
+      modifiers={modifiers}
+    >
+      {children}
+    </Row>
+  )
+}

package/src/atoms/h-stack/h-stack.ios.tsx

@@ -0,0 +1,46 @@
+import {HStack as SwiftUIHStack} from '@expo/ui/swift-ui'
+import {onTapGesture} from '@expo/ui/swift-ui/modifiers'
+import {type FrameAlignment, useSxModifiers} from '@hzblj/kara-sx'
+import {spacing} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import type {HStackAlign, HStackComponent, HStackProps} from './h-stack.types'
+
+const ALIGNMENT = {
+  center: 'center',
+  end: 'bottom',
+  start: 'top',
+} as const satisfies Record<HStackAlign, string>
+
+const FRAME_ALIGNMENT = {
+  center: 'leading',
+  end: 'bottomLeading',
+  start: 'topLeading',
+} as const satisfies Record<HStackAlign, FrameAlignment>
+
+export const HStack: HStackComponent = ({
+  align = 'start',
+  children,
+  onPress,
+  spacing: gap,
+  testID,
+  ...sx
+}: HStackProps) => {
+  useHostGuard('HStack')
+  const sxModifiers = useSxModifiers(sx, FRAME_ALIGNMENT[align])
+  const modifiers = useMemo(
+    () => (onPress ? [...sxModifiers, onTapGesture(onPress)] : sxModifiers),
+    [onPress, sxModifiers]
+  )
+
+  return (
+    <SwiftUIHStack
+      alignment={ALIGNMENT[align]}
+      modifiers={modifiers}
+      spacing={gap === undefined ? undefined : spacing[gap]}
+      testID={testID}
+    >
+      {children}
+    </SwiftUIHStack>
+  )
+}

package/src/atoms/h-stack/h-stack.types.ts

@@ -0,0 +1,15 @@
+import type {ResponsiveSx} from '@hzblj/kara-sx'
+import type {SpaceSize} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+export type HStackAlign = 'center' | 'end' | 'start'
+
+export type HStackProps = ResponsiveSx & {
+  align?: HStackAlign
+  children?: ReactNode
+  onPress?: () => void
+  spacing?: SpaceSize
+  testID?: string
+}
+
+export type HStackComponent = (props: HStackProps) => ReactNode

package/src/atoms/h-stack/index.ts

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

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

@@ -0,0 +1,21 @@
+import {iconResourceName} from '@hzblj/kara-native'
+import {DrawableIcon} from '@hzblj/kara-native/jetpack-compose'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+
+import {useHostGuard} from '../../host-context'
+import type {IconComponent, IconProps} from './icon.types'
+
+/** The app's icon as the vector drawable the config plugin generated from the SVG, drawn by Material's `Icon`. */
+export const Icon: IconComponent = ({accessibilityLabel, color = 'content.primary', name, size = 's24'}: IconProps) => {
+  useHostGuard('Icon')
+  const theme = useAppTheme()
+
+  return (
+    <DrawableIcon
+      accessibilityLabel={accessibilityLabel}
+      iconColor={theme.color(color)}
+      iconSize={spacing[size]}
+      resourceName={iconResourceName(name)}
+    />
+  )
+}