@hzblj/kara-components 0.0.0-stage → 0.1.0

package/src/organisms/fab-menu/fab-menu.types.ts

@@ -0,0 +1,18 @@
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+import type {MenuAction} from '../menu'
+
+/**
+ * A floating action button that unfolds into its actions. Android: Material 3 Expressive's `FloatingActionButtonMenu`
+ * — the button turns into a close and the actions rise above it as labelled pills. iOS: the same button as the label
+ * of a SwiftUI `Menu`. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
+export type FabMenuProps = {
+  actions: MenuAction[]
+  /** The closed button's icon. `add` by default. */
+  icon?: IconName
+  testID?: string
+}
+
+export type FabMenuComponent = (props: FabMenuProps) => ReactNode

package/src/organisms/fab-menu/index.ts

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

package/src/organisms/form/form.android.tsx

@@ -0,0 +1,33 @@
+import {Card} from '../../atoms/card'
+import {Text} from '../../atoms/text'
+import {VStack} from '../../atoms/v-stack'
+import {useHostGuard} from '../../host-context'
+import type {FormComponent, FormProps, FormSectionProps} from './form.types'
+
+const FormRoot = ({children, testID}: FormProps) => {
+  useHostGuard('Form')
+
+  return (
+    <VStack spacing="s16" testID={testID} wide>
+      {children}
+    </VStack>
+  )
+}
+
+const FormSection = ({children, footer, title}: FormSectionProps) => (
+  <VStack spacing="s4" wide>
+    {title ? (
+      <Text color="content.secondary" transform="uppercase" variant="labelMedium">
+        {title}
+      </Text>
+    ) : null}
+    <Card>{children}</Card>
+    {footer ? (
+      <Text color="content.tertiary" variant="footnote">
+        {footer}
+      </Text>
+    ) : null}
+  </VStack>
+)
+
+export const Form: FormComponent = Object.assign(FormRoot, {Section: FormSection})

package/src/organisms/form/form.ios.tsx

@@ -0,0 +1,18 @@
+import {Section, Form as SwiftUIForm} from '@expo/ui/swift-ui'
+import {Text} from '../../atoms/text'
+import {useHostGuard} from '../../host-context'
+import type {FormComponent, FormProps, FormSectionProps} from './form.types'
+
+const FormRoot = ({children, testID}: FormProps) => {
+  useHostGuard('Form')
+
+  return <SwiftUIForm testID={testID}>{children}</SwiftUIForm>
+}
+
+const FormSection = ({children, footer, title}: FormSectionProps) => (
+  <Section footer={footer ? <Text variant="footnote">{footer}</Text> : undefined} title={title}>
+    {children}
+  </Section>
+)
+
+export const Form: FormComponent = Object.assign(FormRoot, {Section: FormSection})

package/src/organisms/form/form.types.ts

@@ -0,0 +1,16 @@
+import type {ReactNode} from 'react'
+
+export type FormProps = {
+  children: ReactNode
+  testID?: string
+}
+
+export type FormSectionProps = {
+  children: ReactNode
+  footer?: string
+  title?: string
+}
+
+export type FormComponent = ((props: FormProps) => ReactNode) & {
+  Section: (props: FormSectionProps) => ReactNode
+}

package/src/organisms/form/index.ts

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

package/src/organisms/index.ts

@@ -0,0 +1,10 @@
+export * from './action-sheet'
+export * from './alert'
+export * from './context-menu'
+export * from './fab-menu'
+export * from './form'
+export * from './menu'
+export * from './rn-context-menu'
+export * from './sheet'
+export * from './snackbar'
+export * from './swipe-actions'

package/src/organisms/menu/index.ts

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

package/src/organisms/menu/menu.android.tsx

@@ -0,0 +1,62 @@
+import {Text as ComposeText, DropdownMenu} from '@expo/ui/jetpack-compose'
+import {clickable} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo, useState} from 'react'
+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 {useHostGuard} from '../../host-context'
+import type {MenuAction, MenuComponent, MenuProps} from './menu.types'
+
+type MenuItemProps = {
+  action: MenuAction
+  onDismiss: () => void
+}
+
+/** A row's `clickable` closes over its own action, so memoising it needs a component per row. */
+const MenuItem = ({action, onDismiss}: MenuItemProps) => {
+  const theme = useAppTheme()
+  const modifiers = useMemo(
+    () => [
+      clickable(() => {
+        onDismiss()
+        action.onPress()
+      }),
+    ],
+    [action, onDismiss]
+  )
+
+  return (
+    <ComposeText
+      color={theme.colorString(action.destructive ? 'content.destructive' : 'content.primary')}
+      modifiers={modifiers}
+      style={theme.typography.body}
+    >
+      {action.label}
+    </ComposeText>
+  )
+}
+
+export const Menu: MenuComponent = ({actions, label}: MenuProps) => {
+  useHostGuard('Menu')
+
+  const [expanded, setExpanded] = useState(false)
+  const dismiss = useCallback(() => setExpanded(false), [])
+
+  return (
+    <VStack>
+      <HStack align="center" onPress={() => setExpanded(true)} spacing="s4">
+        <Text color="content.accent">{label}</Text>
+        <Icon color="content.accent" name="chevronDown" size="s16" />
+      </HStack>
+      <DropdownMenu expanded={expanded} onDismissRequest={dismiss}>
+        {actions.map(action => (
+          <MenuItem action={action} key={action.label} onDismiss={dismiss} />
+        ))}
+      </DropdownMenu>
+      <Spacer min="s0" />
+    </VStack>
+  )
+}

package/src/organisms/menu/menu.ios.tsx

@@ -0,0 +1,21 @@
+import {Button, Menu as SwiftUIMenu} from '@expo/ui/swift-ui'
+
+import {useHostGuard} from '../../host-context'
+import type {MenuComponent, MenuProps} from './menu.types'
+
+export const Menu: MenuComponent = ({actions, label}: MenuProps) => {
+  useHostGuard('Menu')
+
+  return (
+    <SwiftUIMenu label={label}>
+      {actions.map(action => (
+        <Button
+          key={action.label}
+          label={action.label}
+          onPress={action.onPress}
+          role={action.destructive ? 'destructive' : 'default'}
+        />
+      ))}
+    </SwiftUIMenu>
+  )
+}

package/src/organisms/menu/menu.types.ts

@@ -0,0 +1,17 @@
+import type {ReactNode} from 'react'
+
+import type {IconName} from '../../atoms/icon'
+
+export type MenuAction = {
+  destructive?: boolean
+  icon?: IconName
+  label: string
+  onPress: () => void
+}
+
+export type MenuProps = {
+  actions: MenuAction[]
+  label: string
+}
+
+export type MenuComponent = (props: MenuProps) => ReactNode

package/src/organisms/rn-context-menu/index.ts

@@ -0,0 +1,2 @@
+export * from './rn-context-menu'
+export * from './rn-context-menu.types'

package/src/organisms/rn-context-menu/rn-context-menu.android.tsx

@@ -0,0 +1,90 @@
+import {Text as ComposeText, DropdownMenu, DropdownMenuItem, Host} from '@expo/ui/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useState} from 'react'
+import {Pressable, StyleSheet, View} from 'react-native'
+import type {MenuAction} from '../menu'
+import type {RnContextMenuComponent, RnContextMenuExclusionProps, RnContextMenuProps} from './rn-context-menu.types'
+
+/**
+ * The menu's anchor: a point at the trigger's bottom start, so the dropdown opens just under it. The host lies outside
+ * the touch path — the dropdown is a popup window of its own, which takes its touches regardless.
+ */
+const styles = StyleSheet.create({
+  anchor: {bottom: 0, height: 1, left: 0, position: 'absolute', width: 1},
+})
+
+type MenuRowProps = {
+  action: MenuAction
+  onDismiss: () => void
+}
+
+/** A row's `onClick` closes over its own action, so memoising it needs a component per row. */
+const MenuRow = ({action, onDismiss}: MenuRowProps) => {
+  const theme = useAppTheme()
+
+  const onClick = useCallback(() => {
+    onDismiss()
+    action.onPress()
+  }, [action, onDismiss])
+
+  return (
+    <DropdownMenuItem onClick={onClick}>
+      <DropdownMenuItem.Text>
+        <ComposeText
+          color={theme.colorString(action.destructive ? 'content.destructive' : 'content.primary')}
+          style={theme.typography.body}
+        >
+          {action.label}
+        </ComposeText>
+      </DropdownMenuItem.Text>
+    </DropdownMenuItem>
+  )
+}
+
+/**
+ * The trigger stays a plain React Native subtree; a long press on it expands a Compose `DropdownMenu` anchored under
+ * it. The host behind the menu mounts on the first long press and stays — a list of triggers that are only scrolled
+ * past never builds one. `preview` and `onPreviewPress` are iOS-only: Material has no lifted preview.
+ */
+const RnContextMenuRoot = ({actions, children, testID, ...props}: RnContextMenuProps) => {
+  const {onPreviewPress: _onPreviewPress, preview: _preview, ...sx} = props
+  const theme = useAppTheme()
+  const style = useSx(sx)
+  const [isHostMounted, setIsHostMounted] = useState(false)
+  const [expanded, setExpanded] = useState(false)
+
+  const open = useCallback(() => {
+    setIsHostMounted(true)
+    setExpanded(true)
+  }, [])
+
+  const dismiss = useCallback(() => setExpanded(false), [])
+
+  return (
+    <Pressable onLongPress={open} style={style} testID={testID}>
+      {children}
+      {isHostMounted ? (
+        <Host
+          colorScheme={theme.dark ? 'dark' : 'light'}
+          pointerEvents="none"
+          seedColor={theme.materialSeed}
+          style={styles.anchor}
+        >
+          <DropdownMenu expanded={expanded} onDismissRequest={dismiss}>
+            <DropdownMenu.Items>
+              {actions.map(action => (
+                <MenuRow action={action} key={action.label} onDismiss={dismiss} />
+              ))}
+            </DropdownMenu.Items>
+          </DropdownMenu>
+        </Host>
+      ) : null}
+    </Pressable>
+  )
+}
+
+/** A touchable inside the trigger already claims its own long press on Android, so this only has to group. */
+const Exclusion = ({children}: RnContextMenuExclusionProps) => <View>{children}</View>
+
+export const RnContextMenu: RnContextMenuComponent = Object.assign(RnContextMenuRoot, {Exclusion})

package/src/organisms/rn-context-menu/rn-context-menu.ios.tsx

@@ -0,0 +1,47 @@
+import {
+  type ContextMenuItem,
+  ContextMenu as NativeContextMenu,
+  ContextMenuExclusion as NativeContextMenuExclusion,
+} from '@hzblj/kara-native/swift-ui'
+import {useSx} from '@hzblj/kara-sx'
+import {useCallback, useMemo} from 'react'
+import type {SFSymbol} from 'sf-symbols-typescript'
+import {SF_SYMBOLS} from '../../atoms/icon'
+import type {RnContextMenuComponent, RnContextMenuExclusionProps, RnContextMenuProps} from './rn-context-menu.types'
+
+const RnContextMenuRoot = ({actions, children, onPreviewPress, preview, testID, ...sx}: RnContextMenuProps) => {
+  const style = useSx(sx)
+
+  /** The native side hands back an id; the index is the one identity every action has. */
+  const items = useMemo<ContextMenuItem[]>(
+    () =>
+      actions.map((action, index) => ({
+        destructive: action.destructive,
+        id: String(index),
+        systemImage: action.icon ? (SF_SYMBOLS[action.icon] as SFSymbol) : undefined,
+        title: action.label,
+      })),
+    [actions]
+  )
+
+  const onSelectItem = useCallback((id: string) => actions[Number(id)]?.onPress(), [actions])
+
+  return (
+    <NativeContextMenu
+      items={items}
+      onPreviewPress={onPreviewPress}
+      onSelectItem={onSelectItem}
+      preview={preview}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </NativeContextMenu>
+  )
+}
+
+const Exclusion = ({children}: RnContextMenuExclusionProps) => (
+  <NativeContextMenuExclusion>{children}</NativeContextMenuExclusion>
+)
+
+export const RnContextMenu: RnContextMenuComponent = Object.assign(RnContextMenuRoot, {Exclusion})

package/src/organisms/rn-context-menu/rn-context-menu.types.ts

@@ -0,0 +1,36 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
+import type {ReactNode} from 'react'
+import type {MenuAction} from '../menu'
+
+/**
+ * A context menu on a React Native subtree — a card in a list, say — opened by a long press. iOS: a
+ * `UIContextMenuInteraction`, with an optional React Native `preview` lifted while the menu is open and a callback for
+ * a tap on it. Android: a Material dropdown under the subtree. The React Native tier, unlike `ContextMenu`, whose
+ * trigger is a native view inside a host.
+ */
+export type RnContextMenuProps = ResponsiveViewSx & {
+  actions: MenuAction[]
+  /** The trigger, laid out as usual. */
+  children: ReactNode
+  /** iOS: the user tapped the lifted preview, committing to it — open the detail the card stands for. */
+  onPreviewPress?: () => void
+  /**
+   * iOS: lifted in place of the trigger while the menu is open — a larger version of the card, say. A snapshot of the
+   * trigger when unset. Mounted only once a finger has rested on the trigger, so a list of cards does not pay for
+   * every preview up front.
+   */
+  preview?: ReactNode
+  testID?: string
+}
+
+export type RnContextMenuExclusionProps = {
+  children: ReactNode
+}
+
+export type RnContextMenuComponent = ((props: RnContextMenuProps) => ReactNode) & {
+  /**
+   * A region of the trigger that must not open the menu — a button inside the card. On iOS the interaction covers the
+   * whole trigger, so a long press on that button would otherwise open the card's menu.
+   */
+  Exclusion: (props: RnContextMenuExclusionProps) => ReactNode
+}

package/src/organisms/sheet/index.ts

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

package/src/organisms/sheet/sheet.android.tsx

@@ -0,0 +1,25 @@
+import {ModalBottomSheet} from '@expo/ui/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+
+import {useHostGuard} from '../../host-context'
+import type {SheetComponent, SheetProps} from './sheet.types'
+
+export const Sheet: SheetComponent = ({children, fitToContents = true, onDismiss, visible}: SheetProps) => {
+  useHostGuard('Sheet')
+  const theme = useAppTheme()
+
+  if (!visible) {
+    return null
+  }
+
+  return (
+    <ModalBottomSheet
+      containerColor={theme.color('surface.primary')}
+      contentColor={theme.color('content.primary')}
+      onDismissRequest={onDismiss}
+      skipPartiallyExpanded={fitToContents}
+    >
+      {children}
+    </ModalBottomSheet>
+  )
+}

package/src/organisms/sheet/sheet.ios.tsx

@@ -0,0 +1,23 @@
+import {BottomSheet} from '@expo/ui/swift-ui'
+
+import {useHostGuard} from '../../host-context'
+import type {SheetComponent, SheetProps} from './sheet.types'
+
+export const Sheet: SheetComponent = ({children, fitToContents = true, onDismiss, visible}: SheetProps) => {
+  useHostGuard('Sheet')
+
+  return (
+    <BottomSheet
+      fitToContents={fitToContents}
+      isPresented={visible}
+      onDismiss={onDismiss}
+      onIsPresentedChange={next => {
+        if (!next) {
+          onDismiss()
+        }
+      }}
+    >
+      {children}
+    </BottomSheet>
+  )
+}

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

@@ -0,0 +1,10 @@
+import type {ReactNode} from 'react'
+
+export type SheetProps = {
+  children: ReactNode
+  fitToContents?: boolean
+  onDismiss: () => void
+  visible: boolean
+}
+
+export type SheetComponent = (props: SheetProps) => ReactNode

package/src/organisms/snackbar/index.ts

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

package/src/organisms/snackbar/snackbar.tsx

@@ -0,0 +1,42 @@
+import {FadeInDown, FadeOutDown} from 'react-native-reanimated'
+
+import {ABox} from '../../atoms/box'
+import {Pressable} from '../../atoms/pressable'
+import {RnText} from '../../atoms/rn-text'
+import type {SnackbarComponent, SnackbarProps} from './snackbar.types'
+
+export const Snackbar: SnackbarComponent = ({actionLabel, message, onAction, visible}: SnackbarProps) => {
+  if (!visible) {
+    return null
+  }
+
+  return (
+    <ABox
+      align="center"
+      bg="surface.high.contrast"
+      borderRadius="medium"
+      bottom={24}
+      entering={FadeInDown}
+      exiting={FadeOutDown}
+      flexDirection="row"
+      gap="s12"
+      left={16}
+      position="absolute"
+      px="s16"
+      py="s12"
+      right={16}
+      shadow="snackbar"
+    >
+      <RnText color="content.on.high.contrast" variant="footnote">
+        {message}
+      </RnText>
+      {actionLabel ? (
+        <Pressable onPress={onAction}>
+          <RnText color="content.accent" variant="footnoteMedium">
+            {actionLabel}
+          </RnText>
+        </Pressable>
+      ) : null}
+    </ABox>
+  )
+}

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

@@ -0,0 +1,10 @@
+import type {ReactNode} from 'react'
+
+export type SnackbarProps = {
+  actionLabel?: string
+  message: string
+  onAction?: () => void
+  visible: boolean
+}
+
+export type SnackbarComponent = (props: SnackbarProps) => ReactNode

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

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

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

@@ -0,0 +1,14 @@
+import {warnUnsupported} from '../../platform-support'
+import type {SwipeActionsComponent, SwipeActionsProps} from './swipe-actions.types'
+
+/** Passes the row straight through, so losing the gesture never costs you the content. */
+const SwipeActionsRoot = ({children}: SwipeActionsProps) => {
+  warnUnsupported('SwipeActions', 'Android')
+
+  return children
+}
+
+/** The buttons belong to a gesture that does not exist here, so they are dropped. */
+const SwipeActionsGroup = () => null
+
+export const SwipeActions: SwipeActionsComponent = Object.assign(SwipeActionsRoot, {Actions: SwipeActionsGroup})

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

@@ -0,0 +1,18 @@
+import {SwipeActions as SwiftUISwipeActions} from '@expo/ui/swift-ui'
+
+import {useHostGuard} from '../../host-context'
+import type {SwipeActionsComponent, SwipeActionsGroupProps, SwipeActionsProps} from './swipe-actions.types'
+
+const SwipeActionsRoot = ({children, testID}: SwipeActionsProps) => {
+  useHostGuard('SwipeActions')
+
+  return <SwiftUISwipeActions testID={testID}>{children}</SwiftUISwipeActions>
+}
+
+const SwipeActionsGroup = ({allowsFullSwipe = true, children, edge = 'trailing'}: SwipeActionsGroupProps) => (
+  <SwiftUISwipeActions.Actions allowsFullSwipe={allowsFullSwipe} edge={edge}>
+    {children}
+  </SwiftUISwipeActions.Actions>
+)
+
+export const SwipeActions: SwipeActionsComponent = Object.assign(SwipeActionsRoot, {Actions: SwipeActionsGroup})

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

@@ -0,0 +1,24 @@
+import type {ReactNode} from 'react'
+
+export type SwipeActionsEdge = 'leading' | 'trailing'
+
+/**
+ * Swipe-to-reveal buttons on a row. iOS only — Compose ships no equivalent, so on Android the
+ * row renders exactly as it would without this wrapper and the action buttons are dropped.
+ * Degrading that way rather than to `null` keeps the content on screen.
+ */
+export type SwipeActionsProps = {
+  children: ReactNode
+  testID?: string
+}
+
+export type SwipeActionsGroupProps = {
+  /** Whether swiping all the way performs the first action in the group. */
+  allowsFullSwipe?: boolean
+  children: ReactNode
+  edge?: SwipeActionsEdge
+}
+
+export type SwipeActionsComponent = ((props: SwipeActionsProps) => ReactNode) & {
+  Actions: (props: SwipeActionsGroupProps) => ReactNode
+}

package/src/platform-support.ts

@@ -0,0 +1,20 @@
+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.`
+  )
+}

package/src/templates/index.ts

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

package/src/templates/screen/index.ts

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

package/src/templates/screen/screen.android.tsx

@@ -0,0 +1,24 @@
+import {Column, Host} from '@expo/ui/jetpack-compose'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {StyleSheet} from 'react-native'
+import {HostBoundary} from '../../host-context'
+import type {ScreenComponent, ScreenProps} from './screen.types'
+
+export const Screen: ScreenComponent = ({bg = 'surface.base', children, ignoreKeyboardInset, testID}: ScreenProps) => {
+  const theme = useAppTheme()
+  const modifiers = useSxModifiers({bg, tall: true, wide: true})
+
+  return (
+    <Host
+      colorScheme={theme.dark ? 'dark' : 'light'}
+      ignoreSafeAreaKeyboardInsets={ignoreKeyboardInset}
+      seedColor={theme.materialSeed}
+      style={StyleSheet.absoluteFill}
+    >
+      <Column modifiers={modifiers}>
+        <HostBoundary>{children}</HostBoundary>
+      </Column>
+    </Host>
+  )
+}