@hzblj/kara-sx 0.0.0-stage → 0.2.0

package/src/sx.types.ts

@@ -0,0 +1,215 @@
+import type {ModifierConfig as AndroidModifier} from '@expo/ui/jetpack-compose/modifiers'
+import type {ModifierConfig as IosModifier} from '@expo/ui/swift-ui/modifiers'
+import type {ColorToken, OpacitySize, RadiiSize, ShadowName, SpaceSize, ZIndexSize} from '@hzblj/kara-theme'
+
+/** A length React Native accepts: absolute points, or a percentage of the parent. */
+export type SxDimension = `${number}%` | number
+
+/**
+ * The keys all three targets — SwiftUI modifiers, Compose modifiers and React Native styles — can
+ * express with the same meaning. A key only belongs here if all three honour it; anything one of them
+ * has to fake or ignore goes to `IosSx`, `AndroidSx` or `ViewSx` instead.
+ */
+export type SxCore = {
+  bg?: ColorToken
+  blur?: number
+  borderColor?: ColorToken
+  borderRadius?: RadiiSize
+  borderWidth?: number
+  h?: number
+  minH?: number
+  minW?: number
+  offsetX?: number
+  offsetY?: number
+  opacity?: OpacitySize
+  p?: SpaceSize
+  pb?: SpaceSize
+  pl?: SpaceSize
+  pr?: SpaceSize
+  pt?: SpaceSize
+  px?: SpaceSize
+  py?: SpaceSize
+  /** Clockwise, in degrees. */
+  rotate?: number
+  /** Uniform, or per axis — an omitted axis stays at 1. */
+  scale?: number | {x?: number; y?: number}
+  shadow?: ShadowName
+  tall?: boolean
+  w?: number
+  wide?: boolean
+  zIndex?: ZIndexSize
+}
+
+/** Liquid Glass, as SwiftUI's `glassEffect` names its variants. */
+export type GlassVariant = 'clear' | 'identity' | 'regular'
+
+/**
+ * Every declared value in a platform bucket is a primitive — or one flat object of primitives, for
+ * modifiers that take several settings at once — because `sxKey` identifies an `sx` by flattening
+ * its values into a string, one level deep. Anything deeper would collapse to `[object Object]` and
+ * two different configs would share a cache entry. `modifiers` is the sole exception, keyed by
+ * identity.
+ */
+export type SxBucketValue = boolean | number | string | undefined
+
+/** One modifier's settings: a single flat level, so `sxKey`'s one-level walk captures all of it. */
+export type SxBucketConfig = {[setting: string]: SxBucketValue}
+
+/** Holds a bucket to `SxBucketValue`/`SxBucketConfig`, so a key breaking that rule refuses to compile. */
+type Bucket<T extends {[K in keyof T]: K extends 'modifiers' ? T[K] : SxBucketConfig | SxBucketValue}> = T
+
+/** What gets redacted: skeleton placeholder, privacy blur, or the "pending update" restyle. */
+export type RedactionReason = 'invalidated' | 'placeholder' | 'privacy'
+
+/**
+ * SwiftUI modifiers with no honest Compose counterpart. Setting these on Android is inert rather than
+ * a type error — a design system degrades gracefully instead of forcing every call site to branch.
+ */
+export type IosSx = Bucket<{
+  /** Width over height, fitted within the proposed size. The escape hatch covers `fill`. */
+  aspectRatio?: number
+  brightness?: number
+  clipped?: boolean
+  colorInvert?: boolean
+  /**
+   * Sizes the box relative to the nearest container: split it into `count` columns `spacing` apart
+   * and span `span` of them — SwiftUI's stand-in for a fractional width, which its `frame` lacks.
+   */
+  containerRelativeFrame?: {
+    alignment?: FrameAlignment
+    axes: 'both' | 'horizontal' | 'vertical'
+    count?: number
+    span?: number
+    spacing?: number
+  }
+  /** How a content change animates when one is driven natively. `countsDown` is `numericText`'s. */
+  contentTransition?: {
+    countsDown?: boolean
+    type: 'identity' | 'interpolate' | 'numericText' | 'opacity'
+  }
+  /** Cascades to every control in the subtree, the SwiftUI environment way. */
+  controlSize?: 'extraLarge' | 'large' | 'mini' | 'regular' | 'small'
+  contrast?: number
+  fixedSize?: 'both' | 'horizontal' | 'vertical'
+  /**
+   * Liquid Glass: a bare variant, or the full config. `tint` takes a theme token, and without a
+   * `shape` the glass traces the box's own `borderRadius`, the way strokes and shadows do.
+   */
+  glass?:
+    | GlassVariant
+    | {
+        cornerRadius?: number
+        interactive?: boolean
+        shape?: 'capsule' | 'circle' | 'containerRelativeShape' | 'ellipse' | 'rectangle' | 'roundedRectangle'
+        tint?: ColorToken
+        variant: GlassVariant
+      }
+  grayscale?: number
+  /** Invisible, but still taking up its layout space — unlike not rendering the box at all. */
+  hidden?: boolean
+  /** In degrees. */
+  hueRotation?: number
+  /** The height SwiftUI prefers when nothing constrains it — what `fixedSize` resolves to. */
+  idealH?: number
+  /** The width SwiftUI prefers when nothing constrains it — what `fixedSize` resolves to. */
+  idealW?: number
+  /** `true` extends into every safe area; the config narrows which regions and edges. */
+  ignoreSafeArea?:
+    | boolean
+    | {
+        edges?: 'all' | 'bottom' | 'horizontal' | 'leading' | 'top' | 'trailing' | 'vertical'
+        regions?: 'all' | 'container' | 'keyboard'
+      }
+  /** Who gets space first when the parent runs short — *not* a proportional flex weight. */
+  layoutPriority?: number
+  luminanceToAlpha?: boolean
+  /** Escape hatch, appended last. Pass a stable array — a fresh one every render defeats the memo. */
+  modifiers?: IosModifier[]
+  /** Redacts only when an ancestor applies the `privacy` reason — inert on its own. */
+  privacySensitive?: boolean
+  /**
+   * Redacts this subtree — `placeholder` is SwiftUI's built-in skeleton. One reason here;
+   * combining several is escape-hatch territory.
+   */
+  redacted?: RedactionReason
+  saturation?: number
+  /** Cascades to the controls and icons in the subtree. */
+  tint?: ColorToken
+  /** Exempts this subtree from an ancestor's `redacted`. */
+  unredacted?: boolean
+}>
+
+/** Compose modifiers with no honest SwiftUI counterpart. Inert on iOS, by the same argument. */
+export type AndroidSx = Bucket<{
+  /** This box's own placement inside a `ZStack` parent — Compose's per-child `Modifier.align`. */
+  align?:
+    | 'bottom'
+    | 'bottomCenter'
+    | 'bottomEnd'
+    | 'bottomStart'
+    | 'center'
+    | 'centerEnd'
+    | 'centerHorizontally'
+    | 'centerStart'
+    | 'centerVertically'
+    | 'end'
+    | 'start'
+    | 'top'
+    | 'topCenter'
+    | 'topEnd'
+    | 'topStart'
+  animateContentSize?: boolean
+  /** Fraction of the parent's height (0–1). The whole of it is `tall`, which works on iOS too. */
+  fillMaxHeight?: number
+  /** Fraction of the parent's width (0–1). The whole of it is `wide`, which works on iOS too. */
+  fillMaxWidth?: number
+  imePadding?: boolean
+  matchParentSize?: boolean
+  /** Escape hatch, appended last. Pass a stable array — a fresh one every render defeats the memo. */
+  modifiers?: AndroidModifier[]
+  /** Proportional share of the leftover space in a Row or Column, the way `flexGrow` behaves. */
+  weight?: number
+  wrapContentHeight?: 'bottom' | 'centerVertically' | 'top' | boolean
+  wrapContentWidth?: 'centerHorizontally' | 'end' | 'start' | boolean
+}>
+
+/**
+ * The native modifier surface: what SwiftUI and Compose can both express, plus a bucket each for what
+ * only one of them can. Both buckets exist on both platforms so a component's shared `*.types.ts`
+ * contract — and the `contract.check.ts` that holds the two implementations to it — stays one type.
+ */
+export type Sx = SxCore & {
+  android?: AndroidSx
+  ios?: IosSx
+}
+
+/**
+ * `SxCore` for the React Native style path, which — unlike the SwiftUI/Compose modifiers, where a
+ * frame needs concrete points — can size a view as a percentage of its parent. Deliberately built
+ * from `SxCore` and not `Sx`: React Native styles are identical on both platforms, so the `ios` and
+ * `android` buckets would have nothing to resolve into and would silently swallow whatever was passed.
+ */
+export type StyleSx = Omit<SxCore, 'h' | 'minH' | 'minW' | 'w'> & {
+  h?: SxDimension
+  minH?: SxDimension
+  minW?: SxDimension
+  w?: SxDimension
+}
+
+export type FrameAlignment =
+  | 'bottom'
+  | 'bottomLeading'
+  | 'bottomTrailing'
+  | 'center'
+  | 'leading'
+  | 'top'
+  | 'topLeading'
+  | 'topTrailing'
+  | 'trailing'
+
+export type SxPadding = {
+  bottom?: number
+  leading?: number
+  top?: number
+  trailing?: number
+}

package/src/use-sx-modifiers.android.ts

@@ -0,0 +1,29 @@
+import type {ModifierConfig} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme, useBreakpoint} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {flattenSx} from './flatten-sx'
+import {type ResponsiveSx, type ResponsiveSxKey, SX_RESPONSIVE_KEYS} from './responsive-sx'
+import type {FrameAlignment, Sx} from './sx.types'
+import {sxKey} from './sx-key'
+import {sxToModifiers} from './sx-to-modifiers'
+
+/**
+ * `sxToModifiers` behind a `useMemo`, so a re-render hands the native view the modifier array it is
+ * already holding instead of an equal-but-new one to diff.
+ *
+ * The responsive flattening happens before `sxKey`, so the key describes the values actually applied
+ * at this breakpoint — a rotation to a wider window changes it, and nothing else does.
+ *
+ * `android.modifiers` is depended on by identity, because `sxKey` cannot flatten opaque modifier
+ * configs into a string. A call site that builds that array inline therefore re-resolves every render.
+ */
+export const useSxModifiers = (sx: ResponsiveSx, alignment?: FrameAlignment): ModifierConfig[] => {
+  const theme = useAppTheme()
+  const breakpoint = useBreakpoint()
+  const flat = flattenSx<Sx, ResponsiveSxKey>(sx, SX_RESPONSIVE_KEYS, breakpoint)
+  const key = sxKey(flat)
+  const escapeHatch = sx.android?.modifiers
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `key` stands in for `flat` — see `sxKey`
+  return useMemo(() => sxToModifiers(flat, theme, alignment), [alignment, escapeHatch, key, theme])
+}

package/src/use-sx-modifiers.ios.ts

@@ -0,0 +1,29 @@
+import type {ModifierConfig} from '@expo/ui/swift-ui/modifiers'
+import {useAppTheme, useBreakpoint} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {flattenSx} from './flatten-sx'
+import {type ResponsiveSx, type ResponsiveSxKey, SX_RESPONSIVE_KEYS} from './responsive-sx'
+import type {FrameAlignment, Sx} from './sx.types'
+import {sxKey} from './sx-key'
+import {sxToModifiers} from './sx-to-modifiers'
+
+/**
+ * `sxToModifiers` behind a `useMemo`, so a re-render hands the native view the modifier array it is
+ * already holding instead of an equal-but-new one to diff.
+ *
+ * The responsive flattening happens before `sxKey`, so the key describes the values actually applied
+ * at this breakpoint — a rotation to a wider window changes it, and nothing else does.
+ *
+ * `ios.modifiers` is depended on by identity, because `sxKey` cannot flatten opaque modifier configs
+ * into a string. A call site that builds that array inline therefore re-resolves every render.
+ */
+export const useSxModifiers = (sx: ResponsiveSx, alignment?: FrameAlignment): ModifierConfig[] => {
+  const theme = useAppTheme()
+  const breakpoint = useBreakpoint()
+  const flat = flattenSx<Sx, ResponsiveSxKey>(sx, SX_RESPONSIVE_KEYS, breakpoint)
+  const key = sxKey(flat)
+  const escapeHatch = sx.ios?.modifiers
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `key` stands in for `flat` — see `sxKey`
+  return useMemo(() => sxToModifiers(flat, theme, alignment), [alignment, escapeHatch, key, theme])
+}

package/src/use-sx.ts

@@ -0,0 +1,34 @@
+import {useAppTheme, useBreakpoint} from '@hzblj/kara-theme'
+import type {ViewStyle} from 'react-native'
+
+import {flattenSx} from './flatten-sx'
+import {type ResponsiveViewSx, type ResponsiveViewSxKey, VIEW_RESPONSIVE_KEYS} from './responsive-sx'
+import type {ViewSx} from './view-sx.types'
+import {viewSxCache} from './view-sx-to-style'
+
+/**
+ * Resolves an `sx` object into a React Native style. Needs no `useMemo`: the cache keys on the
+ * flattened sx values, so the same sx at the same breakpoint hands back the very same object every
+ * render — and across components.
+ */
+export const useSx = (sx: ResponsiveViewSx): ViewStyle => {
+  const theme = useAppTheme()
+  const breakpoint = useBreakpoint()
+
+  return viewSxCache.resolve(flattenSx<ViewSx, ResponsiveViewSxKey>(sx, VIEW_RESPONSIVE_KEYS, breakpoint), theme)
+}
+
+/**
+ * `useSx` for a component whose own props arrive mixed in with the `sx` ones: the `sx` keys are split
+ * off and resolved, and the rest is handed back untouched. What `sx()` does internally, exposed for the
+ * components that cannot be built on it because they own their `style` prop — an animated one, or a
+ * `ScrollView` styling two boxes at once.
+ */
+export const useSplitSx = <TProps extends Record<string, unknown>>(
+  props: TProps
+): [ViewStyle, Record<string, unknown>] => {
+  const [own, rest] = viewSxCache.split(props)
+  const style = useSx(own)
+
+  return [style, rest]
+}

package/src/value-key.ts

@@ -0,0 +1,18 @@
+/**
+ * Flattens a value into a cache-key fragment. Objects are walked one level — with keys sorted, so
+ * two configs holding the same values key alike — rather than left to `String`, which turns every
+ * object into the same `[object Object]` and would have two different ones share a cache entry.
+ * One level is all the `Bucket` constraint admits, so deeper nesting cannot reach this.
+ */
+export const valueKey = (value: unknown): string => {
+  if (typeof value !== 'object' || value === null) {
+    return String(value)
+  }
+
+  const entries = value as Record<string, unknown>
+
+  return `{${Object.keys(entries)
+    .sort()
+    .map(name => `${name}:${String(entries[name])}`)
+    .join(',')}}`
+}

package/src/view-sx-to-style.ts

@@ -0,0 +1,180 @@
+import {radii, spacing, type Theme} from '@hzblj/kara-theme'
+import type {ViewStyle} from 'react-native'
+
+import {createSxCache} from './resolve-cache'
+import type {ResponsiveViewSx} from './responsive-sx'
+import type {StyleSx} from './sx.types'
+import {SX_CORE_KEYS} from './sx-keys'
+import {sxToStyle} from './sx-to-style'
+import type {ViewRadiiSx, ViewSx} from './view-sx.types'
+
+/**
+ * `Record`s rather than bare arrays, for the same reason as `SX_CORE_KEY_RECORD`: `satisfies` on an
+ * array only checks membership, while these refuse to compile when a key is added to `ViewSx` but
+ * missing here — which `split` would then leak into the wrapped component's own props.
+ */
+const CORNER_KEY_RECORD = {
+  borderBottomLeftRadius: true,
+  borderBottomRadius: true,
+  borderBottomRightRadius: true,
+  borderLeftRadius: true,
+  borderRightRadius: true,
+  borderTopLeftRadius: true,
+  borderTopRadius: true,
+  borderTopRightRadius: true,
+} as const satisfies Record<keyof ViewRadiiSx, true>
+
+const CORNER_KEYS = Object.keys(CORNER_KEY_RECORD) as readonly (keyof ViewRadiiSx)[]
+
+type ViewOnlyKey = Exclude<keyof ViewSx, keyof StyleSx>
+
+const VIEW_ONLY_KEY_RECORD = {
+  ...CORNER_KEY_RECORD,
+  align: true,
+  alignContent: true,
+  alignSelf: true,
+  aspectRatio: true,
+  basis: true,
+  borderBottomWidth: true,
+  borderLeftWidth: true,
+  borderRightWidth: true,
+  borderStyle: true,
+  borderTopWidth: true,
+  bottom: true,
+  columnGap: true,
+  display: true,
+  flex: true,
+  flexDirection: true,
+  gap: true,
+  grow: true,
+  justify: true,
+  left: true,
+  m: true,
+  maxH: true,
+  maxW: true,
+  mb: true,
+  ml: true,
+  mr: true,
+  mt: true,
+  mx: true,
+  my: true,
+  overflow: true,
+  position: true,
+  right: true,
+  rowGap: true,
+  shrink: true,
+  top: true,
+  wrap: true,
+} as const satisfies Record<ViewOnlyKey, true>
+
+const VIEW_ONLY_KEYS = Object.keys(VIEW_ONLY_KEY_RECORD) as readonly ViewOnlyKey[]
+
+/**
+ * Every key the RN style engine owns — what `sx()` and `useSx` split off a component's props. Built
+ * from `SX_CORE_KEYS` rather than `SX_KEYS` on purpose: including the `ios`/`android` buckets would
+ * have `Box` strip them off its props and drop them, since a React Native style has nothing to
+ * resolve them into.
+ */
+export const VIEW_SX_KEYS: readonly (keyof ViewSx & string)[] = [...SX_CORE_KEYS, ...VIEW_ONLY_KEYS]
+
+type SpaceKey = NonNullable<ViewSx['m']>
+
+type RadiiToken = NonNullable<ViewSx['borderRadius']>
+
+const space = (token: SpaceKey | undefined) => (token === undefined ? undefined : spacing[token])
+
+const radius = (token: RadiiToken | undefined) => (token === undefined ? undefined : radii[token])
+
+/**
+ * Left to `sxToStyle`'s single `borderRadius` unless a corner or edge prop is present —
+ * emitting per-corner keys unconditionally would shadow it with `undefined`.
+ */
+const cornerRadiiStyle = (sx: ViewSx): ViewStyle => {
+  if (!CORNER_KEYS.some(key => sx[key] !== undefined)) {
+    return {}
+  }
+
+  const all = radius(sx.borderRadius)
+  const bottom = radius(sx.borderBottomRadius)
+  const left = radius(sx.borderLeftRadius)
+  const right = radius(sx.borderRightRadius)
+  const top = radius(sx.borderTopRadius)
+
+  return {
+    borderBottomLeftRadius: radius(sx.borderBottomLeftRadius) ?? bottom ?? left ?? all,
+    borderBottomRightRadius: radius(sx.borderBottomRightRadius) ?? bottom ?? right ?? all,
+    borderTopLeftRadius: radius(sx.borderTopLeftRadius) ?? top ?? left ?? all,
+    borderTopRightRadius: radius(sx.borderTopRightRadius) ?? top ?? right ?? all,
+  }
+}
+
+const marginStyle = (sx: ViewSx): ViewStyle => {
+  const all = space(sx.m)
+  const x = space(sx.mx)
+  const y = space(sx.my)
+
+  return {
+    marginBottom: space(sx.mb) ?? y ?? all,
+    marginLeft: space(sx.ml) ?? x ?? all,
+    marginRight: space(sx.mr) ?? x ?? all,
+    marginTop: space(sx.mt) ?? y ?? all,
+  }
+}
+
+const borderStyle = (sx: ViewSx): ViewStyle => ({
+  borderBottomWidth: sx.borderBottomWidth,
+  borderLeftWidth: sx.borderLeftWidth,
+  borderRightWidth: sx.borderRightWidth,
+  borderStyle: sx.borderStyle,
+  borderTopWidth: sx.borderTopWidth,
+})
+
+/** `minH`/`minW` are `sxToStyle`'s, and naming them here would shadow it with `undefined`. */
+const sizingStyle = (sx: ViewSx): ViewStyle => ({
+  aspectRatio: sx.aspectRatio,
+  maxHeight: sx.maxH,
+  maxWidth: sx.maxW,
+})
+
+const flexStyle = (sx: ViewSx): ViewStyle => ({
+  alignContent: sx.alignContent,
+  alignItems: sx.align,
+  alignSelf: sx.alignSelf,
+  columnGap: space(sx.columnGap),
+  flex: sx.flex,
+  flexBasis: sx.basis,
+  flexDirection: sx.flexDirection,
+  flexGrow: sx.grow,
+  flexShrink: sx.shrink,
+  flexWrap: sx.wrap,
+  gap: space(sx.gap),
+  justifyContent: sx.justify,
+  rowGap: space(sx.rowGap),
+})
+
+/** `zIndex` is `sxToStyle`'s too, for the same reason as `minH`/`minW` above. */
+const layoutStyle = (sx: ViewSx): ViewStyle => ({
+  bottom: sx.bottom,
+  display: sx.display,
+  left: sx.left,
+  overflow: sx.overflow,
+  position: sx.position,
+  right: sx.right,
+  top: sx.top,
+})
+
+export const viewSxToStyle = (sx: ViewSx, theme: Theme): ViewStyle => ({
+  ...sxToStyle(sx, theme),
+  ...cornerRadiiStyle(sx),
+  ...marginStyle(sx),
+  ...borderStyle(sx),
+  ...sizingStyle(sx),
+  ...flexStyle(sx),
+  ...layoutStyle(sx),
+})
+
+/**
+ * `split` hands back a `ResponsiveViewSx`, because that is what a component's props hold — `resolve`
+ * only accepts the flat `ViewSx` that `flattenSx` turns those into, so the two cannot be crossed.
+ */
+export const viewSxCache = createSxCache<ViewSx, ViewStyle, ResponsiveViewSx>(VIEW_SX_KEYS, viewSxToStyle)

package/src/view-sx.types.ts

@@ -0,0 +1,87 @@
+import type {RadiiSize, SpaceSize} from '@hzblj/kara-theme'
+import type {ViewStyle} from 'react-native'
+
+import type {StyleSx, SxDimension} from './sx.types'
+
+/**
+ * Corner radii cascade the way padding does: a single corner beats its edge pair,
+ * which beats `borderRadius`. So `borderRadius="medium" borderBottomRadius="none"`
+ * rounds the top two corners only.
+ *
+ * Exported so `CORNER_KEYS` can be held to exactly these keys.
+ */
+export type ViewRadiiSx = {
+  borderBottomLeftRadius?: RadiiSize
+  borderBottomRadius?: RadiiSize
+  borderBottomRightRadius?: RadiiSize
+  borderLeftRadius?: RadiiSize
+  borderRightRadius?: RadiiSize
+  borderTopLeftRadius?: RadiiSize
+  borderTopRadius?: RadiiSize
+  borderTopRightRadius?: RadiiSize
+}
+
+/** Per-side widths draw only the edges you name — a one-sided hairline divider needs just one. */
+type ViewBorderSx = {
+  borderBottomWidth?: number
+  borderLeftWidth?: number
+  borderRightWidth?: number
+  borderStyle?: ViewStyle['borderStyle']
+  borderTopWidth?: number
+}
+
+/** `minW`/`minH` live in `StyleSx` — every target can express those, so they are not view-only. */
+type ViewSizingSx = {
+  aspectRatio?: number
+  maxH?: SxDimension
+  maxW?: SxDimension
+}
+
+/**
+ * `grow` is deliberately React Native only. Compose's `weight` is the same proportional share of the
+ * leftover space, but SwiftUI has no per-child weight at all — its nearest move is an infinite `maxWidth`,
+ * which splits the space equally and ignores the ratio. So the modifier paths expose it as
+ * `android={{weight}}` and `ios={{layoutPriority}}`, which is what each of them actually does.
+ */
+type ViewFlexSx = {
+  align?: ViewStyle['alignItems']
+  alignContent?: ViewStyle['alignContent']
+  alignSelf?: ViewStyle['alignSelf']
+  basis?: SxDimension
+  columnGap?: SpaceSize
+  flex?: number
+  flexDirection?: ViewStyle['flexDirection']
+  gap?: SpaceSize
+  grow?: number
+  justify?: ViewStyle['justifyContent']
+  rowGap?: SpaceSize
+  shrink?: number
+  wrap?: ViewStyle['flexWrap']
+}
+
+/** Margins mirror the padding scale: `m` all round, `mx`/`my` per axis, `mt`/`mr`/`mb`/`ml` per side. */
+type ViewMarginSx = {
+  m?: SpaceSize
+  mb?: SpaceSize
+  ml?: SpaceSize
+  mr?: SpaceSize
+  mt?: SpaceSize
+  mx?: SpaceSize
+  my?: SpaceSize
+}
+
+type ViewLayoutSx = {
+  bottom?: SxDimension
+  display?: ViewStyle['display']
+  left?: SxDimension
+  overflow?: ViewStyle['overflow']
+  position?: ViewStyle['position']
+  right?: SxDimension
+  top?: SxDimension
+}
+
+/**
+ * The widest `sx` surface: everything a React Native view can be styled with. `Sx` is the subset the
+ * SwiftUI and Compose modifier paths can also express, so only this one reaches the RN style engine.
+ */
+export type ViewSx = StyleSx & ViewBorderSx & ViewFlexSx & ViewLayoutSx & ViewMarginSx & ViewRadiiSx & ViewSizingSx

package/src/with-sx.tsx

@@ -0,0 +1,51 @@
+import {type ComponentPropsWithRef, type ComponentType, type ElementType, memo} from 'react'
+import type {StyleProp, TextStyle, ViewStyle} from 'react-native'
+
+import type {ResponsiveViewSx} from './responsive-sx'
+import {useSplitSx} from './use-sx'
+
+/**
+ * `sx()` resolves a view style; React Native's text and image styles accept those keys too, so this
+ * covers every flavour of `style` a wrapped component might declare.
+ */
+type SxStyle = StyleProp<TextStyle | ViewStyle>
+
+/** The wrapped component's own props — ref included — with the whole `sx` surface added. */
+export type SxProps<TProps> = Omit<TProps, 'style' | keyof ResponsiveViewSx> &
+  ResponsiveViewSx & {
+    style?: SxStyle
+  }
+
+const nameOf = (Component: ElementType): string => {
+  if (typeof Component === 'string') {
+    return Component
+  }
+
+  const {displayName, name} = Component as ComponentType<never>
+
+  return displayName || name || 'Component'
+}
+
+/**
+ * Turns any style-taking component into an `sx` one: the `sx` props are split off, resolved against
+ * the theme and handed over as `style`. An explicit `style` still wins — it is merged on top.
+ *
+ * Props come from `ComponentPropsWithRef`, so a `ref` survives the wrapping. The component has to
+ * accept a `style`; that cannot be a constraint here, because narrowing `TComponent` past
+ * `ElementType` is what breaks the ref inference.
+ *
+ * Memoised because the point of the cache is a stable style object — without `memo` a parent
+ * re-render would walk the child anyway and throw that stability away.
+ */
+export const sx = <TComponent extends ElementType>(Component: TComponent) => {
+  const Sxed = ({style, ...props}: SxProps<ComponentPropsWithRef<TComponent>>) => {
+    const [resolved, rest] = useSplitSx(props as Record<string, unknown>)
+    const Styled = Component as ComponentType<Record<string, unknown>>
+
+    return <Styled {...rest} style={style ? [resolved, style] : resolved} />
+  }
+
+  Sxed.displayName = `sx(${nameOf(Component)})`
+
+  return memo(Sxed)
+}