@hzblj/kara-components 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,76 @@
+import {Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {
+  foregroundStyle,
+  lineLimit,
+  lineSpacing,
+  type ModifierConfig,
+  multilineTextAlignment,
+  strikethrough,
+  textCase,
+  underline,
+} from '@expo/ui/swift-ui/modifiers'
+import {scaledFont} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {TextComponent, TextProps} from './text.types'
+
+const ALIGNMENT = {
+  center: 'center',
+  left: 'leading',
+  right: 'trailing',
+} as const
+
+export const Text: TextComponent = ({
+  align,
+  children,
+  color = 'content.primary',
+  decoration,
+  numberOfLines,
+  testID,
+  transform,
+  variant = 'body',
+}: TextProps) => {
+  useHostGuard('Text')
+  const theme = useAppTheme()
+  const style = theme.typography[variant]
+
+  const modifiers = useMemo(() => {
+    const list: ModifierConfig[] = [
+      // Not `@expo/ui`'s `font()`: for the platform's face it gives either Apple's size or a size that ignores Dynamic
+      // Type. `scaledFont` keeps the variant's exact size and scales it along `scalesWith`, either face.
+      scaledFont({family: style.fontFamily, size: style.fontSize, textStyle: style.scalesWith, weight: style.weight}),
+      lineSpacing(Math.max(0, style.lineHeight - style.fontSize)),
+      foregroundStyle(theme.color(color)),
+    ]
+
+    if (align) {
+      list.push(multilineTextAlignment(ALIGNMENT[align]))
+    }
+
+    if (transform) {
+      list.push(textCase(transform))
+    }
+
+    if (decoration === 'underline') {
+      list.push(underline({isActive: true, pattern: 'solid'}))
+    }
+
+    if (decoration === 'strikethrough') {
+      list.push(strikethrough({isActive: true, pattern: 'solid'}))
+    }
+
+    if (numberOfLines !== undefined) {
+      list.push(lineLimit(numberOfLines))
+    }
+
+    return list
+  }, [align, color, decoration, numberOfLines, style, theme, transform])
+
+  return (
+    <SwiftUIText modifiers={modifiers} testID={testID}>
+      {children}
+    </SwiftUIText>
+  )
+}

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

@@ -0,0 +1,21 @@
+import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+export type TextAlign = 'center' | 'left' | 'right'
+
+export type TextDecoration = 'none' | 'strikethrough' | 'underline'
+
+export type TextTransform = 'lowercase' | 'uppercase'
+
+export type TextProps = {
+  align?: TextAlign
+  children?: ReactNode
+  color?: ColorToken
+  decoration?: TextDecoration
+  numberOfLines?: number
+  testID?: string
+  transform?: TextTransform
+  variant?: TextVariant
+}
+
+export type TextComponent = (props: TextProps) => ReactNode

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

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

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

@@ -0,0 +1,47 @@
+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 {useHostGuard} from '../../host-context'
+import type {TextFieldComponent, TextFieldProps} from './text-field.types'
+
+export const TextField: TextFieldComponent = ({
+  defaultValue = '',
+  disabled = false,
+  error = false,
+  label,
+  multiline = false,
+  onChangeText,
+  secure = false,
+}: TextFieldProps) => {
+  useHostGuard('TextField')
+  const theme = useAppTheme()
+  const value = useNativeState(defaultValue)
+  const modifiers = useSxModifiers({wide: true})
+
+  return (
+    <Column verticalArrangement={{spacedBy: 4}}>
+      {label ? (
+        <ComposeText
+          color={theme.colorString(error ? 'content.destructive' : 'content.secondary')}
+          style={theme.typography.labelMedium}
+        >
+          {label}
+        </ComposeText>
+      ) : null}
+      <OutlinedTextField
+        enabled={!disabled}
+        isError={error}
+        modifiers={modifiers}
+        onValueChange={onChangeText}
+        singleLine={!multiline}
+        textStyle={{
+          color: theme.colorString('content.primary'),
+          fontFamily: theme.typography.body.fontFamily,
+          fontWeight: theme.typography.body.fontWeight,
+        }}
+        value={value}
+        visualTransformation={secure ? 'password' : 'none'}
+      />
+    </Column>
+  )
+}

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

@@ -0,0 +1,90 @@
+import {SecureField, TextField as SwiftUITextField, useNativeState, VStack} from '@expo/ui/swift-ui'
+import {disabled as disabledModifier, textFieldStyle} from '@expo/ui/swift-ui/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {type ColorToken, spacing} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import {Text} from '../text'
+import type {TextFieldComponent, TextFieldProps} from './text-field.types'
+
+type FieldTone = 'default' | 'disabled' | 'error'
+
+type FieldToneColors = {
+  bg: ColorToken
+  border: ColorToken
+  label: ColorToken
+}
+
+const TONE = {
+  default: {bg: 'surface.primary', border: 'border.secondary.muted', label: 'content.secondary'},
+  disabled: {bg: 'surface.depth', border: 'border.quinary', label: 'content.quaternary'},
+  error: {bg: 'surface.primary', border: 'border.destructive', label: 'content.destructive'},
+} as const satisfies Record<FieldTone, FieldToneColors>
+
+/**
+ * Disabled outranks error — a field nobody can edit should recede rather than shout. `.disabled` only
+ * dims the text, so the chrome has to carry the state itself.
+ */
+const toneOf = (disabled: boolean, error: boolean): FieldTone => {
+  if (disabled) {
+    return 'disabled'
+  }
+
+  return error ? 'error' : 'default'
+}
+
+export const TextField: TextFieldComponent = ({
+  defaultValue = '',
+  disabled = false,
+  error = false,
+  label,
+  multiline = false,
+  onChangeText,
+  secure = false,
+  testID,
+}: TextFieldProps) => {
+  useHostGuard('TextField')
+  const text = useNativeState(defaultValue)
+  const tone = TONE[toneOf(disabled, error)]
+
+  const sxModifiers = useSxModifiers({
+    bg: tone.bg,
+    borderColor: tone.border,
+    borderRadius: 'small',
+    borderWidth: 1,
+    px: 's12',
+    py: 's8',
+    wide: true,
+  })
+
+  const modifiers = useMemo(() => {
+    const list = [textFieldStyle('plain'), ...sxModifiers]
+
+    if (disabled) {
+      list.push(disabledModifier(true))
+    }
+
+    return list
+  }, [disabled, sxModifiers])
+
+  return (
+    <VStack alignment="leading" spacing={spacing.s4}>
+      {label ? (
+        <Text color={tone.label} variant="labelMedium">
+          {label}
+        </Text>
+      ) : null}
+      {secure ? (
+        <SecureField modifiers={modifiers} onTextChange={onChangeText} testID={testID} text={text} />
+      ) : (
+        <SwiftUITextField
+          axis={multiline ? 'vertical' : 'horizontal'}
+          modifiers={modifiers}
+          onTextChange={onChangeText}
+          testID={testID}
+          text={text}
+        />
+      )}
+    </VStack>
+  )
+}

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

@@ -0,0 +1,14 @@
+import type {ReactNode} from 'react'
+
+export type TextFieldProps = {
+  defaultValue?: string
+  disabled?: boolean
+  error?: boolean
+  label?: string
+  multiline?: boolean
+  onChangeText?: (text: string) => void
+  secure?: boolean
+  testID?: string
+}
+
+export type TextFieldComponent = (props: TextFieldProps) => ReactNode

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

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

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

@@ -0,0 +1,39 @@
+import {Column} 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 {VStackAlign, VStackComponent, VStackProps} from './v-stack.types'
+
+const ALIGNMENT = {
+  center: 'center',
+  end: 'end',
+  start: 'start',
+} as const satisfies Record<VStackAlign, string>
+
+export const VStack: VStackComponent = ({
+  align = 'start',
+  children,
+  onPress,
+  spacing: gap,
+  testID,
+  ...sx
+}: VStackProps) => {
+  useHostGuard('VStack')
+  const sxModifiers = useSxModifiers(sx)
+  const modifiers = useMemo(
+    () => [...sxModifiers, ...(testID ? [testIdModifier(testID)] : []), ...(onPress ? [clickable(onPress)] : [])],
+    [onPress, sxModifiers, testID]
+  )
+
+  return (
+    <Column
+      horizontalAlignment={ALIGNMENT[align]}
+      verticalArrangement={gap === undefined ? undefined : {spacedBy: spacing[gap]}}
+      modifiers={modifiers}
+    >
+      {children}
+    </Column>
+  )
+}

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

@@ -0,0 +1,40 @@
+import {VStack as SwiftUIVStack} 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 {VStackAlign, VStackComponent, VStackProps} from './v-stack.types'
+
+const ALIGNMENT = {
+  center: 'center',
+  end: 'trailing',
+  start: 'leading',
+} as const satisfies Record<VStackAlign, FrameAlignment>
+
+export const VStack: VStackComponent = ({
+  align = 'start',
+  children,
+  onPress,
+  spacing: gap,
+  testID,
+  ...sx
+}: VStackProps) => {
+  useHostGuard('VStack')
+  const sxModifiers = useSxModifiers(sx, ALIGNMENT[align])
+  const modifiers = useMemo(
+    () => (onPress ? [...sxModifiers, onTapGesture(onPress)] : sxModifiers),
+    [onPress, sxModifiers]
+  )
+
+  return (
+    <SwiftUIVStack
+      alignment={ALIGNMENT[align]}
+      modifiers={modifiers}
+      spacing={gap === undefined ? undefined : spacing[gap]}
+      testID={testID}
+    >
+      {children}
+    </SwiftUIVStack>
+  )
+}

package/src/atoms/v-stack/v-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 VStackAlign = 'center' | 'end' | 'start'
+
+export type VStackProps = ResponsiveSx & {
+  align?: VStackAlign
+  children?: ReactNode
+  onPress?: () => void
+  spacing?: SpaceSize
+  testID?: string
+}
+
+export type VStackComponent = (props: VStackProps) => ReactNode

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

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

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

@@ -0,0 +1,27 @@
+import {Box} from '@expo/ui/jetpack-compose'
+import {clickable, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import type {ZStackAlign, ZStackComponent, ZStackProps} from './z-stack.types'
+
+const ALIGNMENT = {
+  bottom: 'bottomCenter',
+  center: 'center',
+  top: 'topCenter',
+} as const satisfies Record<ZStackAlign, string>
+
+export const ZStack: ZStackComponent = ({align = 'center', children, onPress, testID, ...sx}: ZStackProps) => {
+  useHostGuard('ZStack')
+  const sxModifiers = useSxModifiers(sx)
+  const modifiers = useMemo(
+    () => [...sxModifiers, ...(testID ? [testIdModifier(testID)] : []), ...(onPress ? [clickable(onPress)] : [])],
+    [onPress, sxModifiers, testID]
+  )
+
+  return (
+    <Box contentAlignment={ALIGNMENT[align]} modifiers={modifiers}>
+      {children}
+    </Box>
+  )
+}

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

@@ -0,0 +1,27 @@
+import {ZStack as SwiftUIZStack} from '@expo/ui/swift-ui'
+import {onTapGesture} from '@expo/ui/swift-ui/modifiers'
+import {type FrameAlignment, useSxModifiers} from '@hzblj/kara-sx'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import type {ZStackAlign, ZStackComponent, ZStackProps} from './z-stack.types'
+
+const ALIGNMENT = {
+  bottom: 'bottom',
+  center: 'center',
+  top: 'top',
+} as const satisfies Record<ZStackAlign, FrameAlignment>
+
+export const ZStack: ZStackComponent = ({align = 'center', children, onPress, testID, ...sx}: ZStackProps) => {
+  useHostGuard('ZStack')
+  const sxModifiers = useSxModifiers(sx, ALIGNMENT[align])
+  const modifiers = useMemo(
+    () => (onPress ? [...sxModifiers, onTapGesture(onPress)] : sxModifiers),
+    [onPress, sxModifiers]
+  )
+
+  return (
+    <SwiftUIZStack alignment={ALIGNMENT[align]} modifiers={modifiers} testID={testID}>
+      {children}
+    </SwiftUIZStack>
+  )
+}

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

@@ -0,0 +1,13 @@
+import type {ResponsiveSx} from '@hzblj/kara-sx'
+import type {ReactNode} from 'react'
+
+export type ZStackAlign = 'bottom' | 'center' | 'top'
+
+export type ZStackProps = ResponsiveSx & {
+  align?: ZStackAlign
+  children?: ReactNode
+  onPress?: () => void
+  testID?: string
+}
+
+export type ZStackComponent = (props: ZStackProps) => ReactNode

package/src/host-context.tsx

@@ -0,0 +1,17 @@
+import {createContext, type ReactNode, useContext} from 'react'
+
+const HostContext = createContext(false)
+
+export const HostBoundary = ({children}: {children: ReactNode}) => (
+  <HostContext.Provider value>{children}</HostContext.Provider>
+)
+
+export const useHostGuard = (atom: string) => {
+  const insideHost = useContext(HostContext)
+
+  if (__DEV__ && !insideHost) {
+    console.warn(
+      `[kara-ui] <${atom}> renders a native view and must sit inside <Screen> or <Island>. Outside one it will not appear.`
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './atoms'
+export * from './molecules'
+export * from './organisms'
+export * from './templates'

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

@@ -0,0 +1,25 @@
+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 {useMemo} from 'react'
+import {Icon} from '../../atoms/icon'
+import {useHostGuard} from '../../host-context'
+import type {CollapsibleComponent, CollapsibleProps} from './collapsible.types'
+
+export const Collapsible: CollapsibleComponent = ({children, expanded, label, onExpandedChange}: CollapsibleProps) => {
+  useHostGuard('Collapsible')
+  const theme = useAppTheme()
+  const modifiers = useMemo(() => [clickable(() => onExpandedChange(!expanded))], [expanded, onExpandedChange])
+
+  return (
+    <Column>
+      <Row horizontalArrangement="spaceBetween" modifiers={modifiers} verticalAlignment="center">
+        <ComposeText color={theme.colorString('content.primary')} style={theme.typography.body}>
+          {label}
+        </ComposeText>
+        <Icon name={expanded ? 'chevronDown' : 'chevronRight'} size="s20" />
+      </Row>
+      <AnimatedVisibility visible={expanded}>{children}</AnimatedVisibility>
+    </Column>
+  )
+}

package/src/molecules/collapsible/collapsible.ios.tsx

@@ -0,0 +1,14 @@
+import {DisclosureGroup} from '@expo/ui/swift-ui'
+
+import {useHostGuard} from '../../host-context'
+import type {CollapsibleComponent, CollapsibleProps} from './collapsible.types'
+
+export const Collapsible: CollapsibleComponent = ({children, expanded, label, onExpandedChange}: CollapsibleProps) => {
+  useHostGuard('Collapsible')
+
+  return (
+    <DisclosureGroup isExpanded={expanded} label={label} onIsExpandedChange={onExpandedChange}>
+      {children}
+    </DisclosureGroup>
+  )
+}

package/src/molecules/collapsible/collapsible.types.ts

@@ -0,0 +1,10 @@
+import type {ReactNode} from 'react'
+
+export type CollapsibleProps = {
+  children: ReactNode
+  expanded: boolean
+  label: string
+  onExpandedChange: (expanded: boolean) => void
+}
+
+export type CollapsibleComponent = (props: CollapsibleProps) => ReactNode

package/src/molecules/collapsible/index.ts

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

package/src/molecules/empty-state/empty-state.tsx

@@ -0,0 +1,19 @@
+import {Icon} from '../../atoms/icon'
+import {Text} from '../../atoms/text'
+import {VStack} from '../../atoms/v-stack'
+import type {EmptyStateComponent, EmptyStateProps} from './empty-state.types'
+
+export const EmptyState: EmptyStateComponent = ({action, description, icon, testID, title}: EmptyStateProps) => (
+  <VStack align="center" p="s24" spacing="s8" testID={testID} wide>
+    {icon ? <Icon color="content.quaternary" name={icon} size="s48" /> : null}
+    <Text align="center" variant="headingXs">
+      {title}
+    </Text>
+    {description ? (
+      <Text align="center" color="content.secondary" variant="subheadline">
+        {description}
+      </Text>
+    ) : null}
+    {action}
+  </VStack>
+)

package/src/molecules/empty-state/empty-state.types.ts

@@ -0,0 +1,16 @@
+import type {ReactNode} from 'react'
+import type {IconName} from '../../atoms/icon'
+
+/**
+ * The "nothing here" placeholder for an empty list, a failed search or a cleared inbox.
+ * `action` takes a `Button` so the state can offer a way out.
+ */
+export type EmptyStateProps = {
+  action?: ReactNode
+  description?: string
+  icon?: IconName
+  testID?: string
+  title: string
+}
+
+export type EmptyStateComponent = (props: EmptyStateProps) => ReactNode

package/src/molecules/empty-state/index.ts

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

package/src/molecules/index.ts

@@ -0,0 +1,14 @@
+export * from './collapsible'
+export * from './empty-state'
+export * from './label'
+export * from './labeled-content'
+export * from './link'
+export * from './list-item'
+export * from './navigation-bar'
+export * from './pager'
+export * from './radio-group'
+export * from './rn-tooltip'
+export * from './scroll-edge-container'
+export * from './search-bar'
+export * from './stepper'
+export * from './tooltip'

package/src/molecules/label/index.ts

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

package/src/molecules/label/label.tsx

@@ -0,0 +1,20 @@
+import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Text} from '../../atoms/text'
+import type {LabelComponent, LabelProps} from './label.types'
+
+export const Label: LabelComponent = ({
+  color = 'content.primary',
+  icon,
+  iconSize = 's20',
+  testID,
+  title,
+  variant = 'body',
+}: LabelProps) => (
+  <HStack align="center" spacing="s8" testID={testID}>
+    <Icon color={color} name={icon} size={iconSize} />
+    <Text color={color} variant={variant}>
+      {title}
+    </Text>
+  </HStack>
+)

package/src/molecules/label/label.types.ts

@@ -0,0 +1,19 @@
+import type {ColorToken, SpaceSize, TextVariant} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+
+/**
+ * An inline icon + text pair — the thing you put inside a button, a menu row or a section
+ * header. For a full tappable row with a subtitle and chevron, use `ListItem`.
+ */
+export type LabelProps = {
+  color?: ColorToken
+  icon: IconName
+  iconSize?: SpaceSize
+  testID?: string
+  title: string
+  variant?: TextVariant
+}
+
+export type LabelComponent = (props: LabelProps) => ReactNode

package/src/molecules/labeled-content/index.ts

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

package/src/molecules/labeled-content/labeled-content.tsx

@@ -0,0 +1,28 @@
+import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Spacer} from '../../atoms/spacer'
+import {Text} from '../../atoms/text'
+import type {LabeledContentComponent, LabeledContentProps} from './labeled-content.types'
+
+const TrailingValue = ({value}: {value: string}) => (
+  <Text color="content.secondary" variant="body">
+    {value}
+  </Text>
+)
+
+export const LabeledContent: LabeledContentComponent = ({
+  children,
+  icon,
+  label,
+  onPress,
+  testID,
+  value,
+}: LabeledContentProps) => (
+  <HStack align="center" onPress={onPress} py="s8" spacing="s12" testID={testID} wide>
+    {icon ? <Icon color="content.secondary" name={icon} size="s20" /> : null}
+    <Text variant="body">{label}</Text>
+    <Spacer />
+    {children ?? (value === undefined ? null : <TrailingValue value={value} />)}
+    {onPress ? <Icon color="content.quaternary" name="chevronRight" size="s16" /> : null}
+  </HStack>
+)

package/src/molecules/labeled-content/labeled-content.types.ts

@@ -0,0 +1,17 @@
+import type {ReactNode} from 'react'
+import type {IconName} from '../../atoms/icon'
+
+/**
+ * A label on the leading edge and its value on the trailing edge — the settings/detail row.
+ * Pass `children` instead of `value` when the trailing side is a control rather than text.
+ */
+export type LabeledContentProps = {
+  children?: ReactNode
+  icon?: IconName
+  label: string
+  onPress?: () => void
+  testID?: string
+  value?: string
+}
+
+export type LabeledContentComponent = (props: LabeledContentProps) => ReactNode