@hzblj/kara-components 0.0.0-stage → 0.2.0

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/glyph/glyph-button.android.tsx

@@ -0,0 +1,25 @@
+import {IconButton as ComposeIconButton} from '@expo/ui/jetpack-compose'
+import {GLYPHS} from '@hzblj/kara-native'
+import {DrawableIcon} from '@hzblj/kara-native/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import type {GlyphButtonComponent, GlyphButtonProps} from './glyph-button.types'
+
+export const GlyphButton: GlyphButtonComponent = ({
+  accessibilityLabel,
+  disabled = false,
+  name,
+  onPress,
+}: GlyphButtonProps) => {
+  const theme = useAppTheme()
+
+  return (
+    <ComposeIconButton enabled={!disabled} onClick={onPress}>
+      <DrawableIcon
+        accessibilityLabel={accessibilityLabel}
+        iconColor={theme.color(disabled ? 'btn.content.disabled' : 'content.primary')}
+        resourceName={GLYPHS[name].android}
+      />
+    </ComposeIconButton>
+  )
+}

package/src/glyph/glyph-button.ios.tsx

@@ -0,0 +1,37 @@
+import {Button} from '@expo/ui/swift-ui'
+import {
+  buttonStyle,
+  disabled as disabledModifier,
+  accessibilityLabel as labelModifier,
+} from '@expo/ui/swift-ui/modifiers'
+import {useMemo} from 'react'
+
+import {Glyph} from './glyph'
+import type {GlyphButtonComponent, GlyphButtonProps} from './glyph-button.types'
+
+export const GlyphButton: GlyphButtonComponent = ({
+  accessibilityLabel,
+  disabled = false,
+  name,
+  onPress,
+}: GlyphButtonProps) => {
+  const modifiers = useMemo(() => {
+    const list = [buttonStyle('plain')]
+
+    if (disabled) {
+      list.push(disabledModifier(true))
+    }
+
+    if (accessibilityLabel) {
+      list.push(labelModifier(accessibilityLabel))
+    }
+
+    return list
+  }, [accessibilityLabel, disabled])
+
+  return (
+    <Button modifiers={modifiers} onPress={onPress}>
+      <Glyph color={disabled ? 'btn.content.disabled' : 'content.primary'} name={name} />
+    </Button>
+  )
+}

package/src/glyph/glyph-button.types.ts

@@ -0,0 +1,12 @@
+import type {GlyphName} from '@hzblj/kara-native'
+import type {ReactNode} from 'react'
+
+/** An icon button over one of kara's glyphs — for the controls its own components build (a stepper, a bar). */
+export type GlyphButtonProps = {
+  accessibilityLabel?: string
+  disabled?: boolean
+  name: GlyphName
+  onPress?: () => void
+}
+
+export type GlyphButtonComponent = (props: GlyphButtonProps) => ReactNode

package/src/glyph/glyph.android.tsx

@@ -0,0 +1,12 @@
+import {GLYPHS} from '@hzblj/kara-native'
+import {DrawableIcon} from '@hzblj/kara-native/jetpack-compose'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+
+import type {GlyphComponent, GlyphProps} from './glyph.types'
+
+/** The Material Symbol `@hzblj/kara-native` ships as a drawable — inside a Compose host. */
+export const Glyph: GlyphComponent = ({color = 'content.primary', name, size = 's24'}: GlyphProps) => {
+  const theme = useAppTheme()
+
+  return <DrawableIcon iconColor={theme.color(color)} iconSize={spacing[size]} resourceName={GLYPHS[name].android} />
+}

package/src/glyph/glyph.ios.tsx

@@ -0,0 +1,15 @@
+import {Image} from '@expo/ui/swift-ui'
+import {accessibilityHidden} from '@expo/ui/swift-ui/modifiers'
+import {GLYPHS} from '@hzblj/kara-native'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+
+import type {GlyphComponent, GlyphProps} from './glyph.types'
+
+const DECORATIVE = [accessibilityHidden(true)]
+
+/** The SF Symbol the system already has — inside a SwiftUI host. */
+export const Glyph: GlyphComponent = ({color = 'content.primary', name, size = 's24'}: GlyphProps) => {
+  const theme = useAppTheme()
+
+  return <Image color={theme.color(color)} modifiers={DECORATIVE} size={spacing[size]} systemName={GLYPHS[name].ios} />
+}

package/src/glyph/glyph.types.ts

@@ -0,0 +1,15 @@
+import type {GlyphName} from '@hzblj/kara-native'
+import type {ColorToken, SpaceSize} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+/**
+ * One of the few glyphs kara's own components draw — a search field's magnifier, a row's chevron. Internal: apps draw
+ * their own icons with `Icon` / `RnIcon`.
+ */
+export type GlyphProps = {
+  color?: ColorToken
+  name: GlyphName
+  size?: SpaceSize
+}
+
+export type GlyphComponent = (props: GlyphProps) => ReactNode

package/src/glyph/index.ts

@@ -0,0 +1,5 @@
+export * from './glyph'
+export * from './glyph.types'
+export * from './glyph-button'
+export * from './glyph-button.types'
+export * from './rn-glyph'

package/src/glyph/rn-glyph.android.tsx

@@ -0,0 +1,14 @@
+import {GLYPHS} from '@hzblj/kara-native'
+import {IconView} from '@hzblj/kara-native/jetpack-compose'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import type {GlyphComponent, GlyphProps} from './glyph.types'
+
+/** The Material Symbol drawable in an `ImageView` — the React Native tier. */
+export const RnGlyph: GlyphComponent = ({color = 'content.primary', name, size = 's24'}: GlyphProps) => {
+  const theme = useAppTheme()
+  const style = useMemo(() => ({height: spacing[size], width: spacing[size]}), [size])
+
+  return <IconView iconColor={theme.color(color)} resourceName={GLYPHS[name].android} style={style} />
+}

package/src/glyph/rn-glyph.ios.tsx

@@ -0,0 +1,16 @@
+import {GLYPHS} from '@hzblj/kara-native'
+import {IconView} from '@hzblj/kara-native/swift-ui'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import type {GlyphComponent, GlyphProps} from './glyph.types'
+
+/** The SF Symbol in a `UIImageView`, drawn at the size `Glyph` gives it inside a host — the React Native tier. */
+export const RnGlyph: GlyphComponent = ({color = 'content.primary', name, size = 's24'}: GlyphProps) => {
+  const theme = useAppTheme()
+  const style = useMemo(() => ({height: spacing[size], width: spacing[size]}), [size])
+
+  return (
+    <IconView iconColor={theme.color(color)} style={style} symbolSize={spacing[size]} systemName={GLYPHS[name].ios} />
+  )
+}

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 {Glyph} from '../../glyph'
+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>
+        <Glyph 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,29 @@
+import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Spacer} from '../../atoms/spacer'
+import {Text} from '../../atoms/text'
+import {Glyph} from '../../glyph'
+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 ? <Glyph 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

package/src/molecules/link/index.ts

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

package/src/molecules/link/link.tsx

@@ -0,0 +1,28 @@
+import {Linking} from 'react-native'
+
+import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Text} from '../../atoms/text'
+import type {LinkComponent, LinkProps} from './link.types'
+
+export const Link: LinkComponent = ({
+  color = 'content.accent',
+  icon,
+  label,
+  testID,
+  url,
+  variant = 'body',
+}: LinkProps) => {
+  const open = () => {
+    Linking.openURL(url).catch(() => undefined)
+  }
+
+  return (
+    <HStack align="center" onPress={open} spacing="s8" testID={testID}>
+      {icon ? <Icon color={color} name={icon} size="s20" /> : null}
+      <Text color={color} variant={variant}>
+        {label}
+      </Text>
+    </HStack>
+  )
+}

package/src/molecules/link/link.types.ts

@@ -0,0 +1,16 @@
+import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+
+/** Opens an external URL in the platform browser or the app that claims the scheme. */
+export type LinkProps = {
+  color?: ColorToken
+  icon?: IconName
+  label: string
+  testID?: string
+  url: string
+  variant?: TextVariant
+}
+
+export type LinkComponent = (props: LinkProps) => ReactNode

package/src/molecules/list-item/index.ts

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

package/src/molecules/list-item/list-item.tsx

@@ -0,0 +1,23 @@
+import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Spacer} from '../../atoms/spacer'
+import {Text} from '../../atoms/text'
+import {VStack} from '../../atoms/v-stack'
+import {Glyph} from '../../glyph'
+import type {ListItemComponent, ListItemProps} from './list-item.types'
+
+export const ListItem: ListItemComponent = ({icon, onPress, subtitle, testID, title}: ListItemProps) => (
+  <HStack align="center" onPress={onPress} py="s8" spacing="s12" testID={testID} wide>
+    {icon ? <Icon color="content.secondary" name={icon} size="s20" /> : null}
+    <VStack spacing="s2">
+      <Text variant="body">{title}</Text>
+      {subtitle ? (
+        <Text color="content.secondary" variant="footnote">
+          {subtitle}
+        </Text>
+      ) : null}
+    </VStack>
+    <Spacer />
+    {onPress ? <Glyph color="content.quaternary" name="chevronRight" size="s16" /> : null}
+  </HStack>
+)

package/src/molecules/list-item/list-item.types.ts

@@ -0,0 +1,13 @@
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+
+export type ListItemProps = {
+  icon?: IconName
+  onPress?: () => void
+  subtitle?: string
+  testID?: string
+  title: string
+}
+
+export type ListItemComponent = (props: ListItemProps) => ReactNode

package/src/molecules/navigation-bar/index.ts

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

package/src/molecules/navigation-bar/navigation-bar.android.tsx

@@ -0,0 +1,28 @@
+import {HStack} from '../../atoms/h-stack'
+import {Island} from '../../atoms/island'
+import {Spacer} from '../../atoms/spacer'
+import {Text} from '../../atoms/text'
+import {GlyphButton} from '../../glyph'
+import type {NavigationBarComponent, NavigationBarProps} from './navigation-bar.types'
+
+/**
+ * Material's top bar shape — navigation icon, start-aligned title, action at the end — built from the atoms in its own
+ * island. Compose's icon buttons take no accessibility identifier, so `backTestID`/`closeTestID` are iOS-only.
+ */
+export const NavigationBar: NavigationBarComponent = ({
+  backLabel = 'Back',
+  closeLabel = 'Close',
+  onBack,
+  onClose,
+  testID,
+  title,
+}: NavigationBarProps) => (
+  <Island testID={testID}>
+    <HStack align="center" px="s4" spacing="s4" wide>
+      {onBack ? <GlyphButton accessibilityLabel={backLabel} name="back" onPress={onBack} /> : null}
+      {title ? <Text variant="body">{title}</Text> : null}
+      <Spacer />
+      {onClose ? <GlyphButton accessibilityLabel={closeLabel} name="close" onPress={onClose} /> : null}
+    </HStack>
+  </Island>
+)

package/src/molecules/navigation-bar/navigation-bar.ios.tsx

@@ -0,0 +1,33 @@
+import {NavigationBar as NativeNavigationBar} from '@hzblj/kara-native/swift-ui'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {StyleSheet} from 'react-native'
+import type {NavigationBarComponent, NavigationBarProps} from './navigation-bar.types'
+
+/** UIKit's compact bar height. The bar centres itself vertically in whatever it is given. */
+const BAR_HEIGHT = 44
+
+const styles = StyleSheet.create({
+  bar: {height: BAR_HEIGHT, width: '100%'},
+})
+
+export const NavigationBar: NavigationBarComponent = ({
+  backLabel = 'Back',
+  closeLabel = 'Close',
+  ...props
+}: NavigationBarProps) => {
+  const theme = useAppTheme()
+  const title = theme.typography.body
+
+  return (
+    <NativeNavigationBar
+      {...props}
+      backLabel={backLabel}
+      closeLabel={closeLabel}
+      fontFamily={title.fontFamily}
+      fontSize={title.fontSize}
+      itemColor={theme.color('content.primary')}
+      style={styles.bar}
+      titleColor={theme.color('content.primary')}
+    />
+  )
+}

package/src/molecules/navigation-bar/navigation-bar.types.ts

@@ -0,0 +1,26 @@
+import type {ReactNode} from 'react'
+
+/**
+ * A title with back and close items, for a sheet that is not a navigation screen. On iOS a standalone
+ * `UINavigationBar`, so the items press and render exactly like a native-stack header's — on iOS 26 they share the
+ * bar's glass instead of swelling as standalone glass buttons do. On Android a Material row of icon buttons. The React
+ * Native tier: it needs no host.
+ */
+export type NavigationBarProps = {
+  /** The back item's accessibility label. `Back` by default. */
+  backLabel?: string
+  /** iOS: the back item's accessibility identifier. */
+  backTestID?: string
+  /** The close item's accessibility label. `Close` by default. */
+  closeLabel?: string
+  /** iOS: the close item's accessibility identifier. */
+  closeTestID?: string
+  /** Shows the back item. */
+  onBack?: () => void
+  /** Shows the close item. */
+  onClose?: () => void
+  testID?: string
+  title?: string
+}
+
+export type NavigationBarComponent = (props: NavigationBarProps) => ReactNode

package/src/molecules/pager/index.ts

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