@hzblj/kara-components 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The atoms, molecules, organisms and templates of @hzblj/kara-ui — real SwiftUI and Jetpack Compose views through @expo/ui.",
+  "author": "Jan Blazej",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hzblj/kara-ui.git",
+    "directory": "packages/components"
+  },
+  "bugs": {
+    "url": "https://github.com/hzblj/kara-ui/issues"
+  },
+  "homepage": "https://github.com/hzblj/kara-ui/tree/main/packages/components#readme",
+  "keywords": [
+    "react-native",
+    "expo",
+    "kara-ui"
+  ],
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!**/*.stories.tsx",
+    "!**/contract.check.ts",
+    "!**/story-decorators.tsx",
+    "!**/__tests__"
+  ],
+  "scripts": {
+    "build": "bob build && tsc -p ./tsconfig.build.json && node ../../scripts/fallback-declarations.mjs",
+    "clean": "rm -rf lib",
+    "prepack": "yarn run -T turbo run build --filter=$npm_package_name...",
+    "lint": "yarn run -T concurrently \"yarn biome:check\" \"yarn tsc:check\"",
+    "lint:fix": "yarn run -T biome check --write .",
+    "biome:check": "yarn run -T biome check .",
+    "tsc:check": "yarn run -T concurrently \"tsc -p ./tsconfig.ios.json\" \"tsc -p ./tsconfig.android.json\""
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "exclude": "{**/__tests__/**,**/__fixtures__/**,**/__mocks__/**,**/*.stories.tsx,**/contract.check.ts,**/story-decorators.tsx}",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ]
+    ]
+  },
+  "dependencies": {
+    "@hzblj/kara-native": "workspace:^",
+    "@hzblj/kara-sx": "workspace:^",
+    "@hzblj/kara-theme": "workspace:^",
+    "sf-symbols-typescript": "^2.2.0"
+  },
+  "peerDependencies": {
+    "@expo/ui": "~57.0.0",
+    "@shopify/flash-list": ">=2.0.0",
+    "expo": "~57.0.0",
+    "expo-haptics": "*",
+    "expo-image": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-reanimated": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@expo/ui": "~57.0.18",
+    "@shopify/flash-list": "^2.3.2",
+    "@storybook/react-native": "^10.6.0",
+    "@types/react": "~19.2.18",
+    "expo": "~57.0.22",
+    "expo-haptics": "~57.0.3",
+    "expo-image": "~57.0.5",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-builder-bob": "^0.43.0",
+    "react-native-reanimated": "4.5.1",
+    "react-native-worklets": "0.10.1",
+    "storybook": "^10.6.0",
+    "typescript": "~7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/atoms/activity-indicator/activity-indicator.tsx

@@ -0,0 +1,9 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import type {FC} from 'react'
+import {type ActivityIndicatorProps, ActivityIndicator as RNActivityIndicator} from 'react-native'
+
+export const ActivityIndicator: FC<ActivityIndicatorProps> = props => {
+  const theme = useAppTheme()
+
+  return <RNActivityIndicator color={theme.color('fill.accent.primary')} size="small" {...props} />
+}

package/src/atoms/activity-indicator/index.ts

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

package/src/atoms/avatar/avatar.tsx

@@ -0,0 +1,43 @@
+import {spacing} from '@hzblj/kara-theme'
+
+import {Box} from '../box'
+import {Image} from '../image'
+import {RnText} from '../rn-text'
+import type {AvatarComponent, AvatarProps, AvatarSize} from './avatar.types'
+
+const DIAMETER = {
+  lg: spacing.s64,
+  md: spacing.s40,
+  sm: spacing.s24,
+} as const satisfies Record<AvatarSize, number>
+
+const VARIANT = {
+  lg: 'headingXs',
+  md: 'labelMedium',
+  sm: 'caption',
+} as const
+
+export const Avatar: AvatarComponent = ({initials, size = 'md', source, testID}: AvatarProps) => {
+  const diameter = DIAMETER[size]
+
+  return (
+    <Box
+      align="center"
+      bg="fill.tertiary"
+      borderRadius="full"
+      h={diameter}
+      justify="center"
+      overflow="hidden"
+      testID={testID}
+      w={diameter}
+    >
+      {source ? (
+        <Image source={source} style={{height: diameter, width: diameter}} />
+      ) : (
+        <RnText color="content.secondary" variant={VARIANT[size]}>
+          {initials ?? ''}
+        </RnText>
+      )}
+    </Box>
+  )
+}

package/src/atoms/avatar/avatar.types.ts

@@ -0,0 +1,13 @@
+import type {ReactNode} from 'react'
+import type {ImageSourcePropType} from 'react-native'
+
+export type AvatarSize = 'lg' | 'md' | 'sm'
+
+export type AvatarProps = {
+  initials?: string
+  size?: AvatarSize
+  source?: ImageSourcePropType
+  testID?: string
+}
+
+export type AvatarComponent = (props: AvatarProps) => ReactNode

package/src/atoms/avatar/index.ts

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

package/src/atoms/badge/badge-tokens.ts

@@ -0,0 +1,10 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+
+import type {BadgeTone} from './badge.types'
+
+export const BADGE_TOKENS = {
+  accent: {content: 'content.accent', fill: 'fill.accent.base'},
+  destructive: {content: 'content.destructive', fill: 'fill.destructive.base'},
+  neutral: {content: 'content.secondary', fill: 'fill.tertiary'},
+  success: {content: 'content.success', fill: 'fill.success.base'},
+} as const satisfies Record<BadgeTone, {content: ColorToken; fill: ColorToken}>

package/src/atoms/badge/badge.android.tsx

@@ -0,0 +1,20 @@
+import {Badge as ComposeBadge, Text as ComposeText} from '@expo/ui/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useHostGuard} from '../../host-context'
+import type {BadgeComponent, BadgeProps} from './badge.types'
+import {BADGE_TOKENS} from './badge-tokens'
+
+/** Material's badge. Its content is a Compose `Text` — `@expo/ui`'s badge takes composable content, not a string. */
+export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+  useHostGuard('Badge')
+  const theme = useAppTheme()
+  const tokens = BADGE_TOKENS[tone]
+
+  return (
+    <ComposeBadge containerColor={theme.color(tokens.fill)} contentColor={theme.color(tokens.content)}>
+      <ComposeText color={theme.colorString(tokens.content)} style={theme.typography.captionMedium}>
+        {label}
+      </ComposeText>
+    </ComposeBadge>
+  )
+}

package/src/atoms/badge/badge.ios.tsx

@@ -0,0 +1,20 @@
+import {HStack} from '@expo/ui/swift-ui'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {useHostGuard} from '../../host-context'
+import {Text} from '../text'
+import type {BadgeComponent, BadgeProps} from './badge.types'
+import {BADGE_TOKENS} from './badge-tokens'
+
+export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+  useHostGuard('Badge')
+  const tokens = BADGE_TOKENS[tone]
+  const modifiers = useSxModifiers({bg: tokens.fill, borderRadius: 'full', px: 's8', py: 's2'})
+
+  return (
+    <HStack modifiers={modifiers}>
+      <Text color={tokens.content} variant="labelMedium">
+        {label}
+      </Text>
+    </HStack>
+  )
+}

package/src/atoms/badge/badge.types.ts

@@ -0,0 +1,10 @@
+import type {ReactNode} from 'react'
+
+export type BadgeTone = 'accent' | 'destructive' | 'neutral' | 'success'
+
+export type BadgeProps = {
+  label: string
+  tone?: BadgeTone
+}
+
+export type BadgeComponent = (props: BadgeProps) => ReactNode

package/src/atoms/badge/index.ts

@@ -0,0 +1,3 @@
+export * from './badge'
+export * from './badge.types'
+export * from './badge-tokens'

package/src/atoms/box/a-box.ts

@@ -0,0 +1,5 @@
+import Animated from 'react-native-reanimated'
+
+import {Box} from './box'
+
+export const ABox = Animated.createAnimatedComponent(Box)

package/src/atoms/box/box.tsx

@@ -0,0 +1,8 @@
+import {sx} from '@hzblj/kara-sx'
+import {View} from 'react-native'
+
+/**
+ * A React Native `View` that takes the design system's `sx` props. The `sx()` HOC is the whole
+ * implementation — Box is just its first caller, and any other style-taking component gets the same.
+ */
+export const Box = sx(View)

package/src/atoms/box/box.types.ts

@@ -0,0 +1,6 @@
+import type {ComponentProps} from 'react'
+
+import type {Box} from './box'
+
+/** Derived from the component itself, so it cannot drift from what `sx(View)` actually accepts. */
+export type BoxProps = ComponentProps<typeof Box>

package/src/atoms/box/index.ts

@@ -0,0 +1,3 @@
+export * from './a-box'
+export * from './box'
+export * from './box.types'

package/src/atoms/button/button-tokens.ts

@@ -0,0 +1,84 @@
+import type {ColorToken, ShadowName, Theme} from '@hzblj/kara-theme'
+
+import type {ButtonVariant} from './button.types'
+
+type ButtonTokens = {
+  content: ColorToken
+  fill: ColorToken
+  shadow: ShadowName
+}
+
+const TOKENS = {
+  accent: {content: 'content.on.bg', fill: 'fill.accent.primary', shadow: 'btn.accent'},
+  destructive: {content: 'content.on.destructive', fill: 'fill.destructive.primary', shadow: 'btn.destructive'},
+  glass: {content: 'content.primary', fill: 'btn.bg.glass.base', shadow: 'btn.glass'},
+  secondary: {content: 'content.primary', fill: 'btn.bg.secondary.base', shadow: 'btn.secondary'},
+} as const satisfies Record<ButtonVariant, ButtonTokens>
+
+export const buttonTokens = (variant: ButtonVariant, disabled: boolean, theme: Theme) => {
+  const tokens = TOKENS[variant]
+
+  if (!disabled) {
+    return tokens
+  }
+
+  const disabledFill = {
+    accent: 'fill.accent.disabled',
+    destructive: 'fill.destructive.disabled',
+    glass: 'btn.bg.glass.disabled',
+    secondary: 'btn.bg.secondary.disabled',
+  } as const satisfies Record<ButtonVariant, ColorToken>
+
+  void theme
+
+  return {content: 'btn.content.disabled', fill: disabledFill[variant], shadow: tokens.shadow} as const
+}
+
+/** Relative luminance of a `#rrggbb` colour (any alpha ignored); `undefined` for anything else. */
+const luminance = (color: unknown): number | undefined => {
+  const hex = typeof color === 'string' ? /^#([0-9a-f]{6})/i.exec(color)?.[1] : undefined
+
+  if (!hex) {
+    return undefined
+  }
+
+  const [r, g, b] = [0, 2, 4].map(i => {
+    const channel = Number.parseInt(hex.slice(i, i + 2), 16) / 255
+
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+  })
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/**
+ * The hex behind a token in the current appearance. Android resolves an adaptive entry to one; iOS hands the platform
+ * a dynamic colour instead, so there the authored entry is read and its branch picked. A system colour has none.
+ */
+const currentHex = (token: ColorToken, theme: Theme): unknown => {
+  const resolved = theme.color(token)
+
+  if (typeof resolved === 'string') {
+    return resolved
+  }
+
+  const entry = token
+    .split(':')[0]
+    .split('.')
+    .reduce<unknown>((node, key) => (node as Record<string, unknown> | undefined)?.[key], theme)
+
+  if (entry && typeof entry === 'object' && 'adaptive' in entry) {
+    const {dark, light} = (entry as {adaptive: {dark: string; light: string}}).adaptive
+
+    return theme.dark ? dark : light
+  }
+
+  return entry
+}
+
+/**
+ * The label for a button filled with an arbitrary `tint`: the on-accent white over a strong colour, the primary
+ * content colour over a pale one (`fill.accent.base`) — the light container tokens pair with it in both appearances.
+ */
+export const contentOnTint = (tint: ColorToken, theme: Theme): ColorToken =>
+  (luminance(currentHex(tint, theme)) ?? 0) > 0.4 ? 'content.primary' : 'content.on.bg'

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

@@ -0,0 +1,70 @@
+import {Button as ComposeButton, Text as ComposeText, OutlinedButton} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import type {ButtonComponent, ButtonProps} from './button.types'
+import {buttonTokens, contentOnTint} from './button-tokens'
+
+/**
+ * Material's filled button, in its own stadium shape. No `borderRadius` or `shadow` from the tokens: those shape the
+ * SwiftUI button's glossy ring, and laid over a Compose button they clip and outline a rounded rectangle around the
+ * pill Material draws. The label is a Compose `Text` — `@expo/ui`'s button takes composable content, not a string.
+ *
+ * Material has no glass, so `glass` is its outlined button — and a `tint` makes any variant a filled button in that
+ * colour, as a prominent style does on iOS. `buttonStyle` and `controlSize` are SwiftUI's alone.
+ */
+export const Button: ButtonComponent = ({
+  disabled = false,
+  label,
+  onPress,
+  testID,
+  tint,
+  variant = 'accent',
+  wide = true,
+}: ButtonProps) => {
+  useHostGuard('Button')
+  const theme = useAppTheme()
+  const tokens = buttonTokens(variant, disabled, theme)
+  const sxModifiers = useSxModifiers({wide})
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
+  const style = theme.typography.body
+  const outlined = variant === 'glass' && !tint
+  const fill = tint && !disabled ? tint : tokens.fill
+  const content = tint && !disabled ? contentOnTint(tint, theme) : tokens.content
+  const MaterialButton = outlined ? OutlinedButton : ComposeButton
+
+  return (
+    <MaterialButton
+      colors={
+        outlined
+          ? {contentColor: theme.color(content), disabledContentColor: theme.color(content)}
+          : {
+              containerColor: theme.color(fill),
+              contentColor: theme.color(content),
+              disabledContainerColor: theme.color(fill),
+              disabledContentColor: theme.color(content),
+            }
+      }
+      enabled={!disabled}
+      modifiers={modifiers}
+      onClick={onPress}
+    >
+      <ComposeText
+        color={theme.colorString(content)}
+        style={{
+          fontFamily: style.fontFamily,
+          fontSize: style.fontSize,
+          fontWeight: style.fontWeight,
+          lineHeight: style.lineHeight,
+        }}
+      >
+        {label}
+      </ComposeText>
+    </MaterialButton>
+  )
+}

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

@@ -0,0 +1,89 @@
+import {Button as SwiftUIButton} from '@expo/ui/swift-ui'
+import {
+  buttonStyle as buttonStyleModifier,
+  controlSize as controlSizeModifier,
+  disabled as disabledModifier,
+  glassEffect as glassEffectModifier,
+  tint as tintModifier,
+} from '@expo/ui/swift-ui/modifiers'
+import {type ColorToken, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {useHostGuard} from '../../host-context'
+import {Text} from '../text'
+import {VStack} from '../v-stack'
+import type {ButtonComponent, ButtonProps, ButtonStyleName, ButtonVariant} from './button.types'
+import {buttonTokens, contentOnTint} from './button-tokens'
+
+const STYLE_BY_VARIANT = {
+  accent: 'borderedProminent',
+  destructive: 'borderedProminent',
+  glass: 'glass',
+  secondary: 'bordered',
+} as const satisfies Record<ButtonVariant, ButtonStyleName>
+
+const TINT_BY_VARIANT = {
+  accent: 'fill.accent.primary',
+  destructive: 'fill.destructive.primary',
+  glass: undefined,
+  secondary: undefined,
+} as const satisfies Record<ButtonVariant, ColorToken | undefined>
+
+export const Button: ButtonComponent = ({
+  buttonStyle,
+  controlSize = 'large',
+  disabled = false,
+  label,
+  onPress,
+  testID,
+  tint,
+  variant = 'accent',
+  wide = true,
+}: ButtonProps) => {
+  useHostGuard('Button')
+  const theme = useAppTheme()
+  const tokens = buttonTokens(variant, disabled, theme)
+  const resolvedTint = tint ?? TINT_BY_VARIANT[variant]
+  const style = buttonStyle ?? STYLE_BY_VARIANT[variant]
+
+  /**
+   * `.glass` ignores `.tint` — colouring the material is `.glassEffect(.regular.tint(…))`, a different
+   * modifier that only lands on a button once the style stops drawing its own material. So a tinted
+   * glass button is a plain one wearing the effect, and `interactive` is what buys back the press
+   * response the style would have given it.
+   *
+   * `plain` has no chrome for `controlSize` to size, so the label carries the padding that gives the
+   * button its height — without it a tinted glass button comes out shorter than every other variant.
+   */
+  const glassTint = style === 'glass' && resolvedTint ? theme.color(resolvedTint) : undefined
+  const filled = Boolean(glassTint) || style === 'borderedProminent' || style === 'glassProminent'
+  // A prominent style — and tinted glass — is coloured by the tint, so a caller's own tint picks the label on it.
+  const content = tint && filled && !disabled ? contentOnTint(tint, theme) : tokens.content
+
+  const modifiers = useMemo(() => {
+    const list = [buttonStyleModifier(glassTint ? 'plain' : style), controlSizeModifier(controlSize)]
+
+    if (glassTint) {
+      list.push(
+        glassEffectModifier({glass: {interactive: true, tint: glassTint, variant: 'regular'}, shape: 'capsule'})
+      )
+    } else if (resolvedTint) {
+      list.push(tintModifier(theme.color(resolvedTint)))
+    }
+
+    if (disabled) {
+      list.push(disabledModifier(true))
+    }
+
+    return list
+  }, [controlSize, disabled, glassTint, resolvedTint, style, theme])
+
+  return (
+    <SwiftUIButton modifiers={modifiers} onPress={onPress} testID={testID}>
+      <VStack align="center" py={glassTint ? 's16' : undefined} wide={wide}>
+        <Text color={content} variant="body">
+          {label}
+        </Text>
+      </VStack>
+    </SwiftUIButton>
+  )
+}

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

@@ -0,0 +1,42 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'secondary'
+
+/**
+ * SwiftUI `ButtonStyle`. iOS only — Compose has no equivalent, so Android ignores it and keeps
+ * rendering the variant's tokens.
+ */
+export type ButtonStyleName =
+  | 'automatic'
+  | 'bordered'
+  | 'borderedProminent'
+  | 'borderless'
+  | 'glass'
+  | 'glassProminent'
+  | 'plain'
+
+/**
+ * SwiftUI `ControlSize`. iOS only, and it has no `automatic` member — leave it unset to inherit
+ * whatever the surrounding SwiftUI environment provides.
+ */
+export type ButtonControlSize = 'extraLarge' | 'large' | 'mini' | 'regular' | 'small'
+
+export type ButtonProps = {
+  buttonStyle?: ButtonStyleName
+  controlSize?: ButtonControlSize
+  disabled?: boolean
+  label: string
+  onPress?: () => void
+  testID?: string
+  /**
+   * Overrides the variant's own tint. A prominent style takes it as the fill and picks a contrasting
+   * label. `glass` has to reach the material through `glassEffect` instead, so tinting one costs it
+   * the stock `.glass` style — see the iOS implementation.
+   */
+  tint?: ColorToken
+  variant?: ButtonVariant
+  wide?: boolean
+}
+
+export type ButtonComponent = (props: ButtonProps) => ReactNode

package/src/atoms/button/index.ts

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

package/src/atoms/card/card.android.tsx

@@ -0,0 +1,17 @@
+import {Column} from '@expo/ui/jetpack-compose'
+import {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 {CardComponent, CardProps} from './card.types'
+
+export const Card: CardComponent = ({children, testID, ...sx}: CardProps) => {
+  useHostGuard('Card')
+  const sxModifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', shadow: 'card', ...sx})
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
+
+  return <Column modifiers={modifiers}>{children}</Column>
+}

package/src/atoms/card/card.ios.tsx

@@ -0,0 +1,15 @@
+import {VStack} from '@expo/ui/swift-ui'
+import {useSxModifiers} from '@hzblj/kara-sx'
+import {useHostGuard} from '../../host-context'
+import type {CardComponent, CardProps} from './card.types'
+
+export const Card: CardComponent = ({children, testID, ...sx}: CardProps) => {
+  useHostGuard('Card')
+  const modifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', shadow: 'card', ...sx})
+
+  return (
+    <VStack alignment="leading" modifiers={modifiers} testID={testID}>
+      {children}
+    </VStack>
+  )
+}

package/src/atoms/card/card.types.ts

@@ -0,0 +1,9 @@
+import type {ResponsiveSx} from '@hzblj/kara-sx'
+import type {ReactNode} from 'react'
+
+export type CardProps = ResponsiveSx & {
+  children?: ReactNode
+  testID?: string
+}
+
+export type CardComponent = (props: CardProps) => ReactNode

package/src/atoms/card/index.ts

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

package/src/atoms/checkbox/checkbox.android.tsx

@@ -0,0 +1,41 @@
+import {Checkbox as ComposeCheckbox, Row, Text} from '@expo/ui/jetpack-compose'
+import {clickable, fillMaxWidth} from '@expo/ui/jetpack-compose/modifiers'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+
+import {useHostGuard} from '../../host-context'
+import type {CheckboxComponent, CheckboxProps} from './checkbox.types'
+
+/**
+ * Material's checkbox, tinted with the accent. With a label it is a full-width row that toggles as a whole; the gap is
+ * explicit because a checkbox without a handler drops Material's 48dp touch target, and with it the space around it.
+ */
+export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, value}: CheckboxProps) => {
+  useHostGuard('Checkbox')
+  const theme = useAppTheme()
+  const rowModifiers = useMemo(
+    () => (disabled || !onValueChange ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => onValueChange(!value))]),
+    [disabled, onValueChange, value]
+  )
+  const control = (
+    <ComposeCheckbox
+      colors={{checkedColor: theme.color('fill.accent.primary'), checkmarkColor: theme.color('content.on.bg')}}
+      enabled={!disabled}
+      onCheckedChange={onValueChange}
+      value={value}
+    />
+  )
+
+  if (!label) {
+    return control
+  }
+
+  return (
+    <Row horizontalArrangement={{spacedBy: spacing.s8}} modifiers={rowModifiers} verticalAlignment="center">
+      {control}
+      <Text color={theme.colorString(disabled ? 'content.tertiary' : 'content.primary')} style={theme.typography.body}>
+        {label}
+      </Text>
+    </Row>
+  )
+}