@hzblj/kara-sx 0.0.0-stage → 0.2.0

package/lib/module/view-sx-to-style.js

@@ -0,0 +1,159 @@
+"use strict";
+
+import { radii, spacing } from '@hzblj/kara-theme';
+import { createSxCache } from "./resolve-cache.js";
+import { SX_CORE_KEYS } from "./sx-keys.js";
+import { sxToStyle } from "./sx-to-style.js";
+/**
+ * `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
+};
+const CORNER_KEYS = Object.keys(CORNER_KEY_RECORD);
+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
+};
+const VIEW_ONLY_KEYS = Object.keys(VIEW_ONLY_KEY_RECORD);
+
+/**
+ * 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 = [...SX_CORE_KEYS, ...VIEW_ONLY_KEYS];
+const space = token => token === undefined ? undefined : spacing[token];
+const radius = token => 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 => {
+  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 => {
+  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 => ({
+  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 => ({
+  aspectRatio: sx.aspectRatio,
+  maxHeight: sx.maxH,
+  maxWidth: sx.maxW
+});
+const flexStyle = sx => ({
+  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 => ({
+  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, theme) => ({
+  ...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(VIEW_SX_KEYS, viewSxToStyle);
+//# sourceMappingURL=view-sx-to-style.js.map

package/lib/module/view-sx-to-style.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["radii","spacing","createSxCache","SX_CORE_KEYS","sxToStyle","CORNER_KEY_RECORD","borderBottomLeftRadius","borderBottomRadius","borderBottomRightRadius","borderLeftRadius","borderRightRadius","borderTopLeftRadius","borderTopRadius","borderTopRightRadius","CORNER_KEYS","Object","keys","VIEW_ONLY_KEY_RECORD","align","alignContent","alignSelf","aspectRatio","basis","borderBottomWidth","borderLeftWidth","borderRightWidth","borderStyle","borderTopWidth","bottom","columnGap","display","flex","flexDirection","gap","grow","justify","left","m","maxH","maxW","mb","ml","mr","mt","mx","my","overflow","position","right","rowGap","shrink","top","wrap","VIEW_ONLY_KEYS","VIEW_SX_KEYS","space","token","undefined","radius","cornerRadiiStyle","sx","some","key","all","borderRadius","marginStyle","x","y","marginBottom","marginLeft","marginRight","marginTop","sizingStyle","maxHeight","maxWidth","flexStyle","alignItems","flexBasis","flexGrow","flexShrink","flexWrap","justifyContent","layoutStyle","viewSxToStyle","theme","viewSxCache"],"sourceRoot":"../../src","sources":["view-sx-to-style.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/view-sx.types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=view-sx.types.js.map

package/lib/module/view-sx.types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../src","sources":["view-sx.types.ts"],"mappings":"","ignoreList":[]}

package/lib/module/with-sx.js

@@ -0,0 +1,50 @@
+"use strict";
+
+import { memo } from 'react';
+import { useSplitSx } from "./use-sx.js";
+
+/**
+ * `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.
+ */
+
+/** The wrapped component's own props — ref included — with the whole `sx` surface added. */
+import { jsx as _jsx } from "react/jsx-runtime";
+const nameOf = Component => {
+  if (typeof Component === 'string') {
+    return Component;
+  }
+  const {
+    displayName,
+    name
+  } = Component;
+  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 = Component => {
+  const Sxed = ({
+    style,
+    ...props
+  }) => {
+    const [resolved, rest] = useSplitSx(props);
+    const Styled = Component;
+    return /*#__PURE__*/_jsx(Styled, {
+      ...rest,
+      style: style ? [resolved, style] : resolved
+    });
+  };
+  Sxed.displayName = `sx(${nameOf(Component)})`;
+  return /*#__PURE__*/memo(Sxed);
+};
+//# sourceMappingURL=with-sx.js.map

package/lib/module/with-sx.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","useSplitSx","jsx","_jsx","nameOf","Component","displayName","name","sx","Sxed","style","props","resolved","rest","Styled"],"sourceRoot":"../../src","sources":["with-sx.tsx"],"mappings":";;AAAA,SAA0EA,IAAI,QAAO,OAAO;AAI5F,SAAQC,UAAU,QAAO,aAAU;;AAEnC;AACA;AACA;AACA;;AAGA;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAMA,MAAMC,MAAM,GAAIC,SAAsB,IAAa;EACjD,IAAI,OAAOA,SAAS,KAAK,QAAQ,EAAE;IACjC,OAAOA,SAAS;EAClB;EAEA,MAAM;IAACC,WAAW;IAAEC;EAAI,CAAC,GAAGF,SAAiC;EAE7D,OAAOC,WAAW,IAAIC,IAAI,IAAI,WAAW;AAC3C,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,EAAE,GAAoCH,SAAqB,IAAK;EAC3E,MAAMI,IAAI,GAAGA,CAAC;IAACC,KAAK;IAAE,GAAGC;EAAiD,CAAC,KAAK;IAC9E,MAAM,CAACC,QAAQ,EAAEC,IAAI,CAAC,GAAGZ,UAAU,CAACU,KAAgC,CAAC;IACrE,MAAMG,MAAM,GAAGT,SAAmD;IAElE,oBAAOF,IAAA,CAACW,MAAM;MAAA,GAAKD,IAAI;MAAEH,KAAK,EAAEA,KAAK,GAAG,CAACE,QAAQ,EAAEF,KAAK,CAAC,GAAGE;IAAS,CAAE,CAAC;EAC1E,CAAC;EAEDH,IAAI,CAACH,WAAW,GAAG,MAAMF,MAAM,CAACC,SAAS,CAAC,GAAG;EAE7C,oBAAOL,IAAI,CAACS,IAAI,CAAC;AACnB,CAAC","ignoreList":[]}

package/lib/typescript/flatten-sx.d.ts

@@ -0,0 +1,15 @@
+import { type ActiveBreakpoint } from '@hzblj/kara-theme';
+import type { ResponsiveOf } from './responsive.types';
+/**
+ * Collapses a responsive `sx` into the flat one the active breakpoint asks for.
+ *
+ * Deliberately upstream of the caches rather than inside them: `resolve-cache` and `sxKey` only ever
+ * see flat values, so neither their one-level key flattening nor their key space has to grow a
+ * breakpoint dimension — and two devices that land on the same flat `sx` still share its entry. A
+ * breakpoint folded into the cache key instead would have doubled the entries for every `sx` in the
+ * app, responsive or not.
+ *
+ * Hands back the very object it was given when nothing in it is responsive, which is the overwhelming
+ * case: `sx()` wraps every view, and those call sites paying nothing is what keeps it affordable.
+ */
+export declare const flattenSx: <TSx extends object, TKey extends keyof TSx & string>(sx: ResponsiveOf<TSx, TKey>, keys: readonly TKey[], active: ActiveBreakpoint) => TSx;

package/lib/typescript/index.d.ts

@@ -0,0 +1,16 @@
+export * from './flatten-sx';
+export * from './resolve-cache';
+export * from './responsive.types';
+export * from './responsive-sx';
+export * from './sx.types';
+export * from './sx-key';
+export * from './sx-keys';
+export * from './sx-padding';
+export * from './sx-to-modifiers';
+export * from './sx-to-style';
+export * from './use-sx';
+export * from './use-sx-modifiers';
+export * from './value-key';
+export * from './view-sx.types';
+export * from './view-sx-to-style';
+export * from './with-sx';

package/lib/typescript/resolve-cache.d.ts

@@ -0,0 +1,14 @@
+import type { Theme } from '@hzblj/kara-theme';
+type StyleResolver<TProps, TStyle> = (props: TProps, theme: Theme) => TStyle;
+/**
+ * `resolve` takes `TProps`, `split` hands back `TInput`. The same surface, except that props reach
+ * `split` straight off a component with responsive values still in them, and reach `resolve` only once
+ * `flattenSx` has collapsed those — so a caller who splits has to flatten before it can resolve.
+ * Defaults to `TProps`, for a cache whose surface has nothing responsive in it.
+ */
+export type SxCache<TProps, TStyle, TInput = TProps> = {
+    resolve: (props: TProps, theme: Theme) => TStyle;
+    split: <T extends Record<string, unknown>>(props: T) => [TInput, Record<string, unknown>];
+};
+export declare const createSxCache: <TProps extends Record<string, unknown>, TStyle, TInput = TProps>(keys: readonly (keyof TProps & string)[], resolver: StyleResolver<TProps, TStyle>) => SxCache<TProps, TStyle, TInput>;
+export {};

package/lib/typescript/responsive-sx.d.ts

@@ -0,0 +1,80 @@
+import type { ResponsiveOf } from './responsive.types';
+import type { Sx } from './sx.types';
+import type { ViewSx } from './view-sx.types';
+/**
+ * Layout keys only, and deliberately so: a wider screen wants a different gap, padding or column
+ * count — not a different colour. `bg`, `shadow`, the radii, `opacity`, the transforms and both
+ * platform buckets therefore stay scalar. Every key admitted here is one more that `flattenSx` walks
+ * on every render, for a kind of change a design system should not be making anyway.
+ *
+ * `Partial` because this is a subset by design; what the `satisfies` buys is the other direction — a
+ * key renamed in `SxCore` stops compiling here instead of silently going non-responsive.
+ */
+declare const SX_RESPONSIVE_KEY_RECORD: {
+    readonly h: true;
+    readonly minH: true;
+    readonly minW: true;
+    readonly p: true;
+    readonly pb: true;
+    readonly pl: true;
+    readonly pr: true;
+    readonly pt: true;
+    readonly px: true;
+    readonly py: true;
+    readonly tall: true;
+    readonly w: true;
+    readonly wide: true;
+};
+export type ResponsiveSxKey = keyof typeof SX_RESPONSIVE_KEY_RECORD;
+/** What `useSxModifiers` flattens before the SwiftUI and Compose paths see it. */
+export declare const SX_RESPONSIVE_KEYS: readonly ResponsiveSxKey[];
+/** The core keys plus what only the React Native style path has: margins, gaps, flex, sizing maxima. */
+declare const VIEW_RESPONSIVE_KEY_RECORD: {
+    readonly h: true;
+    readonly minH: true;
+    readonly minW: true;
+    readonly p: true;
+    readonly pb: true;
+    readonly pl: true;
+    readonly pr: true;
+    readonly pt: true;
+    readonly px: true;
+    readonly py: true;
+    readonly tall: true;
+    readonly w: true;
+    readonly wide: true;
+    readonly align: true;
+    readonly alignContent: true;
+    readonly alignSelf: true;
+    readonly basis: true;
+    readonly columnGap: true;
+    readonly display: true;
+    readonly flex: true;
+    readonly flexDirection: true;
+    readonly gap: true;
+    readonly grow: true;
+    readonly justify: true;
+    readonly m: true;
+    readonly maxH: true;
+    readonly maxW: true;
+    readonly mb: true;
+    readonly ml: true;
+    readonly mr: true;
+    readonly mt: true;
+    readonly mx: true;
+    readonly my: true;
+    readonly rowGap: true;
+    readonly shrink: true;
+    readonly wrap: true;
+};
+export type ResponsiveViewSxKey = keyof typeof VIEW_RESPONSIVE_KEY_RECORD;
+/** What `useSx` flattens before the style cache sees it. */
+export declare const VIEW_RESPONSIVE_KEYS: readonly ResponsiveViewSxKey[];
+/**
+ * The native modifier surface as a component takes it — `Sx` is the same surface once a breakpoint
+ * has been picked, which is what every resolver and cache downstream of `flattenSx` works with.
+ */
+export type ResponsiveSx = ResponsiveOf<Sx, ResponsiveSxKey>;
+/** `ViewSx` as a component takes it, standing to it as `ResponsiveSx` does to `Sx`. */
+export type ResponsiveViewSx = ResponsiveOf<ViewSx, ResponsiveViewSxKey>;
+export {};

package/lib/typescript/responsive.types.d.ts

@@ -0,0 +1,23 @@
+import type { Breakpoint } from '@hzblj/kara-theme';
+/**
+ * A value that may differ per breakpoint: the plain value, or one keyed by breakpoint.
+ *
+ * `base` is mandatory. Partly because the cascade needs a floor to fall back to, and partly because
+ * an `sx` that applies nothing on the narrowest phone is a bug rather than a style.
+ *
+ * The cascade runs mobile-first — a breakpoint holds until a wider one overrides it. So
+ * `{base: 's8', md: 's16'}` pads by 8 below `md` and by 16 from `md` up, `lg` and `xl` included.
+ */
+export type Responsive<TValue> = TValue | ({
+    base: TValue;
+} & Partial<Record<Breakpoint, TValue>>);
+/**
+ * Widens the named keys of a flat `sx` surface to `Responsive`, leaving the rest alone.
+ *
+ * A transform over the flat type rather than a hand-written twin, so a key added to `Sx` or `ViewSx`
+ * needs no second edit here — and `NonNullable`, so the optionality stays on the prop and cannot
+ * sneak into `base`, which would defeat the point of requiring it.
+ */
+export type ResponsiveOf<TSx, TKey extends keyof TSx> = Omit<TSx, TKey> & {
+    [K in TKey]?: Responsive<NonNullable<TSx[K]>>;
+};

package/lib/typescript/sx-key.d.ts

@@ -0,0 +1,7 @@
+import type { Sx } from './sx.types';
+/**
+ * A stable `useMemo` dependency for an `Sx`. Atoms take theirs from a rest spread, so the object is
+ * a fresh identity on every render even when nothing in it changed — the values flattened into one
+ * string say exactly as much as the object does.
+ */
+export declare const sxKey: (sx: Sx) => string;

package/lib/typescript/sx-keys.d.ts

@@ -0,0 +1,6 @@
+import type { Sx, SxCore } from './sx.types';
+/** The keys every target shares. The React Native style path takes these and none of the buckets. */
+export declare const SX_CORE_KEYS: readonly (keyof SxCore)[];
+/** Kept apart from `SX_CORE_KEYS` so the React Native path can take the core without them. */
+export declare const SX_BUCKET_KEYS: readonly Exclude<keyof Sx, keyof SxCore>[];
+export declare const SX_KEYS: readonly (keyof Sx)[];

package/lib/typescript/sx-padding.d.ts

@@ -0,0 +1,5 @@
+import type { Sx, SxPadding } from './sx.types';
+/** Padding is all this reads, so both `Sx` and the widened `StyleSx` satisfy it. */
+type SxPaddingInput = Pick<Sx, 'p' | 'pb' | 'pl' | 'pr' | 'pt' | 'px' | 'py'>;
+export declare const sxPadding: (sx: SxPaddingInput) => SxPadding | undefined;
+export {};

package/lib/typescript/sx-to-modifiers.d.ts

@@ -0,0 +1 @@
+export * from './sx-to-modifiers.ios';

package/lib/typescript/sx-to-modifiers.ios.d.ts

@@ -0,0 +1,4 @@
+import { type ModifierConfig } from '@expo/ui/swift-ui/modifiers';
+import { type Theme } from '@hzblj/kara-theme';
+import type { FrameAlignment, Sx } from './sx.types';
+export declare const sxToModifiers: (sx: Sx, theme: Theme, alignment?: FrameAlignment) => ModifierConfig[];

package/lib/typescript/sx-to-style.d.ts

@@ -0,0 +1,4 @@
+import { type Theme } from '@hzblj/kara-theme';
+import { type ViewStyle } from 'react-native';
+import type { StyleSx } from './sx.types';
+export declare const sxToStyle: (sx: StyleSx, theme: Theme) => ViewStyle;

package/lib/typescript/sx.types.d.ts

@@ -0,0 +1,182 @@
+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;
+};
+export {};

package/lib/typescript/use-sx-modifiers.d.ts

@@ -0,0 +1 @@
+export * from './use-sx-modifiers.ios';

package/lib/typescript/use-sx-modifiers.ios.d.ts

@@ -0,0 +1,14 @@
+import type { ModifierConfig } from '@expo/ui/swift-ui/modifiers';
+import { type ResponsiveSx } from './responsive-sx';
+import type { FrameAlignment } from './sx.types';
+/**
+ * `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 declare const useSxModifiers: (sx: ResponsiveSx, alignment?: FrameAlignment) => ModifierConfig[];

package/lib/typescript/use-sx.d.ts

@@ -0,0 +1,15 @@
+import type { ViewStyle } from 'react-native';
+import { type ResponsiveViewSx } from './responsive-sx';
+/**
+ * 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 declare const useSx: (sx: ResponsiveViewSx) => ViewStyle;
+/**
+ * `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 declare const useSplitSx: <TProps extends Record<string, unknown>>(props: TProps) => [ViewStyle, Record<string, unknown>];

package/lib/typescript/value-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 declare const valueKey: (value: unknown) => string;