@hzblj/kara-components 0.7.0 → 0.8.0

package/lib/module/molecules/stepper/stepper.ios.js

@@ -1,8 +1,21 @@
 "use strict";
 
 import { Stepper as SwiftUIStepper } from '@expo/ui/swift-ui';
+import { labelsHidden } from '@expo/ui/swift-ui/modifiers';
+import { useRef } from 'react';
+import { HStack } from "../../atoms/h-stack/index.js";
+import { Spacer } from "../../atoms/spacer/index.js";
+import { Text } from "../../atoms/text/index.js";
 import { useHostGuard } from "../../host-context.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The label stays VoiceOver's, on the control; on screen it is the row's own text. */
+const LABEL_HIDDEN = [labelsHidden()];
+
+/**
+ * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
+ * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
+ * monospaced digits so the row does not jump.
+ */
 export const Stepper = ({
   label,
   max,
@@ -12,13 +25,37 @@ export const Stepper = ({
   value
 }) => {
   useHostGuard('Stepper');
-  return /*#__PURE__*/_jsx(SwiftUIStepper, {
-    label: label,
-    max: max,
-    min: min,
-    onValueChange: onValueChange,
-    step: step,
-    value: value
+  const previous = useRef(value);
+  const countsDown = value < previous.current;
+  previous.current = value;
+  return /*#__PURE__*/_jsxs(HStack, {
+    align: "center",
+    spacing: "s12",
+    wide: true,
+    children: [/*#__PURE__*/_jsx(Text, {
+      children: label
+    }), /*#__PURE__*/_jsx(Spacer, {}), /*#__PURE__*/_jsx(Text, {
+      color: "content.secondary",
+      ios: {
+        animation: {
+          value
+        },
+        contentTransition: {
+          countsDown,
+          type: 'numericText'
+        },
+        monospacedDigit: true
+      },
+      children: String(value)
+    }), /*#__PURE__*/_jsx(SwiftUIStepper, {
+      label: label,
+      max: max,
+      min: min,
+      modifiers: LABEL_HIDDEN,
+      onValueChange: onValueChange,
+      step: step,
+      value: value
+    })]
   });
 };
 //# sourceMappingURL=stepper.ios.js.map

package/lib/module/molecules/stepper/stepper.ios.js.map

@@ -1 +1 @@
-{"version":3,"names":["Stepper","SwiftUIStepper","useHostGuard","jsx","_jsx","label","max","min","onValueChange","step","value"],"sourceRoot":"../../../../src","sources":["molecules/stepper/stepper.ios.tsx"],"mappings":";;AAAA,SAAQA,OAAO,IAAIC,cAAc,QAAO,mBAAmB;AAE3D,SAAQC,YAAY,QAAO,uBAAoB;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAG/C,OAAO,MAAMJ,OAAyB,GAAGA,CAAC;EAACK,KAAK;EAAEC,GAAG;EAAEC,GAAG;EAAEC,aAAa;EAAEC,IAAI,GAAG,CAAC;EAAEC;AAAmB,CAAC,KAAK;EAC5GR,YAAY,CAAC,SAAS,CAAC;EAEvB,oBAAOE,IAAA,CAACH,cAAc;IAACI,KAAK,EAAEA,KAAM;IAACC,GAAG,EAAEA,GAAI;IAACC,GAAG,EAAEA,GAAI;IAACC,aAAa,EAAEA,aAAc;IAACC,IAAI,EAAEA,IAAK;IAACC,KAAK,EAAEA;EAAM,CAAE,CAAC;AACrH,CAAC","ignoreList":[]}
+{"version":3,"names":["Stepper","SwiftUIStepper","labelsHidden","useRef","HStack","Spacer","Text","useHostGuard","jsx","_jsx","jsxs","_jsxs","LABEL_HIDDEN","label","max","min","onValueChange","step","value","previous","countsDown","current","align","spacing","wide","children","color","ios","animation","contentTransition","type","monospacedDigit","String","modifiers"],"sourceRoot":"../../../../src","sources":["molecules/stepper/stepper.ios.tsx"],"mappings":";;AAAA,SAAQA,OAAO,IAAIC,cAAc,QAAO,mBAAmB;AAC3D,SAAQC,YAAY,QAAO,6BAA6B;AACxD,SAAQC,MAAM,QAAO,OAAO;AAE5B,SAAQC,MAAM,QAAO,8BAAqB;AAC1C,SAAQC,MAAM,QAAO,6BAAoB;AACzC,SAAQC,IAAI,QAAO,2BAAkB;AACrC,SAAQC,YAAY,QAAO,uBAAoB;AAAA,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AAG/C;AACA,MAAMC,YAAY,GAAG,CAACV,YAAY,CAAC,CAAC,CAAC;;AAErC;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMF,OAAyB,GAAGA,CAAC;EAACa,KAAK;EAAEC,GAAG;EAAEC,GAAG;EAAEC,aAAa;EAAEC,IAAI,GAAG,CAAC;EAAEC;AAAmB,CAAC,KAAK;EAC5GX,YAAY,CAAC,SAAS,CAAC;EACvB,MAAMY,QAAQ,GAAGhB,MAAM,CAACe,KAAK,CAAC;EAC9B,MAAME,UAAU,GAAGF,KAAK,GAAGC,QAAQ,CAACE,OAAO;EAC3CF,QAAQ,CAACE,OAAO,GAAGH,KAAK;EAExB,oBACEP,KAAA,CAACP,MAAM;IAACkB,KAAK,EAAC,QAAQ;IAACC,OAAO,EAAC,KAAK;IAACC,IAAI;IAAAC,QAAA,gBACvChB,IAAA,CAACH,IAAI;MAAAmB,QAAA,EAAEZ;IAAK,CAAO,CAAC,eACpBJ,IAAA,CAACJ,MAAM,IAAE,CAAC,eACVI,IAAA,CAACH,IAAI;MACHoB,KAAK,EAAC,mBAAmB;MACzBC,GAAG,EAAE;QAACC,SAAS,EAAE;UAACV;QAAK,CAAC;QAAEW,iBAAiB,EAAE;UAACT,UAAU;UAAEU,IAAI,EAAE;QAAa,CAAC;QAAEC,eAAe,EAAE;MAAI,CAAE;MAAAN,QAAA,EAEtGO,MAAM,CAACd,KAAK;IAAC,CACV,CAAC,eACPT,IAAA,CAACR,cAAc;MACbY,KAAK,EAAEA,KAAM;MACbC,GAAG,EAAEA,GAAI;MACTC,GAAG,EAAEA,GAAI;MACTkB,SAAS,EAAErB,YAAa;MACxBI,aAAa,EAAEA,aAAc;MAC7BC,IAAI,EAAEA,IAAK;MACXC,KAAK,EAAEA;IAAM,CACd,CAAC;EAAA,CACI,CAAC;AAEb,CAAC","ignoreList":[]}

package/lib/module/ripple-clip.js

@@ -8,6 +8,9 @@ const FILL = {
   flexGrow: 1
 };
 
+/** What gives the outer view a height of its own, rather than its content's. */
+const SIZING_KEYS = ['aspectRatio', 'flex', 'flexBasis', 'flexGrow', 'height', 'minHeight'];
+
 /**
  * Splits a resolved style for a pressable with an Android ripple. The ripple is drawn as the pressable's foreground,
  * which its own `overflow: hidden` does not clip — so it would spill past rounded corners. A parent clips its
@@ -28,8 +31,13 @@ export const splitForRipple = style => {
       outer[key] = value;
     }
   }
+
+  // Only a sized outer view needs the pressable stretched to it. Sized by its content it must not be: Yoga grows a
+  // `flexGrow` child of a fit-content parent to the most it may take — inside a row centred on its cross axis, the
+  // pressable would stretch to the row's full height and leave its content at the top.
+  const sized = SIZING_KEYS.some(key => flat[key] !== undefined) || flat.top !== undefined && flat.bottom !== undefined;
   return {
-    inner: [FILL, inner],
+    inner: sized ? [FILL, inner] : [inner],
     outer: outer
   };
 };

package/lib/module/ripple-clip.js.map

@@ -1 +1 @@
-{"version":3,"names":["StyleSheet","CONTENT_KEYS","Set","FILL","flexGrow","splitForRipple","style","flat","flatten","outer","overflow","inner","key","value","Object","entries","has"],"sourceRoot":"../../src","sources":["ripple-clip.ts"],"mappings":";;AAAA,SAAQA,UAAU,QAAuB,cAAc;;AAEvD;AACA,MAAMC,YAAY,GAAG,IAAIC,GAAG,CAAS,CACnC,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,KAAK,EACL,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,QAAQ,CACT,CAAC;AAEF,MAAMC,IAAe,GAAG;EAACC,QAAQ,EAAE;AAAC,CAAC;;AAErC;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,cAAc,GAAIC,KAA4B,IAA6C;EACtG,MAAMC,IAAI,GAAGP,UAAU,CAACQ,OAAO,CAACF,KAAK,CAAC,IAAI,CAAC,CAAC;EAC5C,MAAMG,KAA8B,GAAG;IAACC,QAAQ,EAAE;EAAQ,CAAC;EAC3D,MAAMC,KAA8B,GAAG,CAAC,CAAC;EAEzC,KAAK,MAAM,CAACC,GAAG,EAAEC,KAAK,CAAC,IAAIC,MAAM,CAACC,OAAO,CAACR,IAAI,CAAC,EAAE;IAC/C,IAAIN,YAAY,CAACe,GAAG,CAACJ,GAAG,CAAC,EAAE;MACzBD,KAAK,CAACC,GAAG,CAAC,GAAGC,KAAK;IACpB,CAAC,MAAM,IAAID,GAAG,KAAK,UAAU,EAAE;MAC7BH,KAAK,CAACG,GAAG,CAAC,GAAGC,KAAK;IACpB;EACF;EAEA,OAAO;IAACF,KAAK,EAAE,CAACR,IAAI,EAAEQ,KAAK,CAAc;IAAEF,KAAK,EAAEA;EAAkB,CAAC;AACvE,CAAC","ignoreList":[]}
+{"version":3,"names":["StyleSheet","CONTENT_KEYS","Set","FILL","flexGrow","SIZING_KEYS","splitForRipple","style","flat","flatten","outer","overflow","inner","key","value","Object","entries","has","sized","some","undefined","top","bottom"],"sourceRoot":"../../src","sources":["ripple-clip.ts"],"mappings":";;AAAA,SAAQA,UAAU,QAAuB,cAAc;;AAEvD;AACA,MAAMC,YAAY,GAAG,IAAIC,GAAG,CAAS,CACnC,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,KAAK,EACL,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,QAAQ,CACT,CAAC;AAEF,MAAMC,IAAe,GAAG;EAACC,QAAQ,EAAE;AAAC,CAAC;;AAErC;AACA,MAAMC,WAAW,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAU;;AAEpG;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,cAAc,GAAIC,KAA4B,IAA6C;EACtG,MAAMC,IAAI,GAAGR,UAAU,CAACS,OAAO,CAACF,KAAK,CAAC,IAAI,CAAC,CAAC;EAC5C,MAAMG,KAA8B,GAAG;IAACC,QAAQ,EAAE;EAAQ,CAAC;EAC3D,MAAMC,KAA8B,GAAG,CAAC,CAAC;EAEzC,KAAK,MAAM,CAACC,GAAG,EAAEC,KAAK,CAAC,IAAIC,MAAM,CAACC,OAAO,CAACR,IAAI,CAAC,EAAE;IAC/C,IAAIP,YAAY,CAACgB,GAAG,CAACJ,GAAG,CAAC,EAAE;MACzBD,KAAK,CAACC,GAAG,CAAC,GAAGC,KAAK;IACpB,CAAC,MAAM,IAAID,GAAG,KAAK,UAAU,EAAE;MAC7BH,KAAK,CAACG,GAAG,CAAC,GAAGC,KAAK;IACpB;EACF;;EAEA;EACA;EACA;EACA,MAAMI,KAAK,GACTb,WAAW,CAACc,IAAI,CAACN,GAAG,IAAIL,IAAI,CAACK,GAAG,CAAC,KAAKO,SAAS,CAAC,IAAKZ,IAAI,CAACa,GAAG,KAAKD,SAAS,IAAIZ,IAAI,CAACc,MAAM,KAAKF,SAAU;EAE3G,OAAO;IAACR,KAAK,EAAEM,KAAK,GAAG,CAACf,IAAI,EAAES,KAAK,CAAc,GAAG,CAACA,KAAK,CAAc;IAAEF,KAAK,EAAEA;EAAkB,CAAC;AACtG,CAAC","ignoreList":[]}

package/lib/typescript/atoms/activity-indicator/activity-indicator.d.ts

@@ -1,3 +1 @@
-import type { FC } from 'react';
-import { type ActivityIndicatorProps } from 'react-native';
-export declare const ActivityIndicator: FC<ActivityIndicatorProps>;
+export * from './activity-indicator.ios';

package/lib/typescript/atoms/activity-indicator/activity-indicator.ios.d.ts

@@ -0,0 +1,3 @@
+import type { ActivityIndicatorComponent } from './activity-indicator.types';
+/** React Native's spinner, which on iOS is UIKit's own `UIActivityIndicatorView`. */
+export declare const ActivityIndicator: ActivityIndicatorComponent;

package/lib/typescript/atoms/activity-indicator/activity-indicator.types.d.ts

@@ -0,0 +1,17 @@
+import type { ColorToken } from '@hzblj/kara-theme';
+import type { ReactNode } from 'react';
+export type ActivityIndicatorSize = 'large' | 'small';
+/**
+ * That something is loading, for as long as it takes — UIKit's spinner on iOS, Material 3's expressive
+ * `LoadingIndicator` on Android, its shapes morphing as it turns. A React Native view on iOS and a host of its own on
+ * Android, so it renders anywhere. For how far along something is, use `Progress`.
+ */
+export type ActivityIndicatorProps = {
+    /** Its colour. `fill.accent.primary` by default. */
+    color?: ColorToken;
+    /** `small` sits in a row or a button, `large` holds a screen that is loading. `small` by default. */
+    size?: ActivityIndicatorSize;
+    /** Test identifier, forwarded to the view. */
+    testID?: string;
+};
+export type ActivityIndicatorComponent = (props: ActivityIndicatorProps) => ReactNode;

package/lib/typescript/atoms/activity-indicator/index.d.ts

@@ -1 +1,2 @@
 export * from './activity-indicator';
+export * from './activity-indicator.types';

package/lib/typescript/atoms/blur-view/blur-view.d.ts

@@ -0,0 +1 @@
+export * from './blur-view.ios';

package/lib/typescript/atoms/blur-view/blur-view.ios.d.ts

@@ -0,0 +1,3 @@
+import type { BlurViewComponent } from './blur-view.types';
+/** `borderRadius` is the material's shape, so it goes to the effect view — the one that clips — not the layout box. */
+export declare const BlurView: BlurViewComponent;

package/lib/typescript/atoms/blur-view/blur-view.types.d.ts

@@ -0,0 +1,31 @@
+import type { BlurMaterial, BlurVibrancy } from '@hzblj/kara-native/swift-ui';
+import type { ResponsiveViewSx } from '@hzblj/kara-sx';
+import type { ReactNode } from 'react';
+export type { BlurMaterial, BlurVibrancy } from '@hzblj/kara-native/swift-ui';
+/**
+ * One of the system's materials behind React Native content — what sheets, bars, menus and HUDs are made of, in
+ * SwiftUI's five thicknesses. iOS: UIKit's `system*Material` blur, with optional vibrancy for the content. Android:
+ * what lies behind, blurred and saturated (Android 12+), under a Material tonal surface as thick as the material —
+ * `surface` at `ultraThin` up to `surfaceContainerHighest` at `ultraThick`; below Android 12 the surface alone. The
+ * React Native tier: it needs no host, so it suits a list cell. Shape it with `borderRadius`; it clips its children.
+ */
+export type BlurViewProps = ResponsiveViewSx & {
+    /**
+     * Pins the material to light or dark whatever the app's appearance — a dark HUD over a light screen. Unset, it follows
+     * the app theme. Android draws the opposite appearance with Material's inverse surface.
+     */
+    appearance?: 'dark' | 'light';
+    /** React Native content, over the material. */
+    children?: ReactNode;
+    /** How much of what lies behind shows through, from `ultraThin` (most) to `ultraThick` (least). `regular` by default. */
+    material?: BlurMaterial;
+    /** Test identifier, forwarded to the view. */
+    testID?: string;
+    /**
+     * iOS: draws the children vibrant at this level, the way iOS draws its own labels and fills on a material — their
+     * colour becomes the material's vibrant one and their alpha the mask. Android has no vibrancy: the children keep
+     * their colours there.
+     */
+    vibrancy?: BlurVibrancy;
+};
+export type BlurViewComponent = (props: BlurViewProps) => ReactNode;

package/lib/typescript/atoms/blur-view/index.d.ts

@@ -0,0 +1,2 @@
+export * from './blur-view';
+export * from './blur-view.types';

package/lib/typescript/atoms/box/a-box.d.ts

@@ -1,4 +1,4 @@
-export declare const ABox: import("react-native-reanimated/lib/typescript/createAnimatedComponent").AnimatedComponentType<Readonly<Omit<import("react-native").ViewProps & import("react").RefAttributes<import("react-native").View>, "align" | "alignContent" | "alignSelf" | "aspectRatio" | "basis" | "bg" | "blur" | "borderColor" | "borderRadius" | "borderWidth" | "bottom" | "columnGap" | "display" | "flex" | "flexDirection" | "gap" | "grow" | "h" | "justify" | "left" | "m" | "maxH" | "maxW" | "mb" | "minH" | "minW" | "ml" | "mr" | "mt" | "mx" | "my" | "offsetX" | "offsetY" | "opacity" | "overflow" | "p" | "pb" | "pl" | "position" | "pr" | "pt" | "px" | "py" | "right" | "rotate" | "rowGap" | "scale" | "shadow" | "shrink" | "style" | "tall" | "top" | "w" | "wide" | "wrap" | "zIndex" | keyof {
+export declare const ABox: import("react-native-reanimated/lib/typescript/createAnimatedComponent").AnimatedComponentType<Readonly<Omit<import("react-native").ViewProps & import("react").RefAttributes<import("react-native").View>, "align" | "alignContent" | "alignSelf" | "aspectRatio" | "basis" | "bg" | "blur" | "borderColor" | "borderRadius" | "borderWidth" | "bottom" | "columnGap" | "display" | "flex" | "flexDirection" | "gap" | "grow" | "h" | "inset" | "justify" | "left" | "m" | "maxH" | "maxW" | "mb" | "minH" | "minW" | "ml" | "mr" | "mt" | "mx" | "my" | "offsetX" | "offsetY" | "opacity" | "overflow" | "p" | "pb" | "pl" | "position" | "pr" | "pt" | "px" | "py" | "right" | "rotate" | "rowGap" | "scale" | "shadow" | "shrink" | "style" | "tall" | "top" | "w" | "wide" | "wrap" | "zIndex" | keyof {
     borderBottomWidth?: number;
     borderLeftWidth?: number;
     borderRightWidth?: number;

package/lib/typescript/atoms/glass-view/glass-view.types.d.ts

@@ -2,18 +2,25 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 /**
- * iOS 26 Liquid Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host
- * and costs next to nothing in a list cell. Where there is no Liquid Glass (Android, and iOS before 26) it draws a
- * capsule of `tint` instead, or of the glass buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ * Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host. iOS 26:
+ * Liquid Glass. Android: frosted glass — what lies behind, blurred on Android 12+, under a translucent tonal surface
+ * (or `tint`) and a hairline. iOS before 26 has no Liquid Glass and draws a capsule of `tint` instead, or of the glass
+ * buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ *
+ * On Android each glass re-records what lies behind it before every frame: a few buttons cost nothing, but keep it out
+ * of the cells of a long list — a plain `tint` reads as well there.
  */
 export type GlassViewProps = ResponsiveViewSx & {
     /** React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`. */
     children?: ReactNode;
-    /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
+    /**
+     * iOS 26: swells toward the finger on touch, carrying the children with it. Android has no swell: wrap the view in a
+     * `Pressable` with `borderRadius="full"`, whose ripple then keeps to the capsule. The press is always the `Pressable`'s.
+     */
     interactive?: boolean;
     /** Test identifier, forwarded to the view. */
     testID?: string;
-    /** Tints the material. Unset leaves it clear. */
+    /** Tints the material. Unset leaves it clear on iOS, and the translucent surface colour on Android. */
     tint?: ColorToken;
 };
 export type GlassViewComponent = (props: GlassViewProps) => ReactNode;

package/lib/typescript/atoms/image/image.d.ts

@@ -1,4 +1,12 @@
-import { ImageProps } from 'expo-image';
-import { FC } from 'react';
-declare const Image: FC<ImageProps>;
-export { Image };
+import { Image as ExpoImage, type ImageProps as ExpoImageProps } from 'expo-image';
+import type { Ref } from 'react';
+/**
+ * `expo-image` with the `sx` props, the way `Box` is a `View` with them, and the design system's 100 ms linear fade
+ * already applied, so a loaded image never pops in. An explicit `transition` wins, and so does an explicit `style`.
+ */
+export declare const Image: import("react").MemoExoticComponent<{
+    ({ style, ...props }: import("@hzblj/kara-sx").SxProps<ExpoImageProps & {
+        ref?: Ref<ExpoImage>;
+    }>): import("react").JSX.Element;
+    displayName: string;
+}>;

package/lib/typescript/atoms/image/image.types.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentProps } from 'react';
+import type { Image } from './image';
+/** Derived from the component itself, so it cannot drift from what `sx(Image)` actually accepts. */
+export type ImageProps = ComponentProps<typeof Image>;

package/lib/typescript/atoms/image/index.d.ts

@@ -1 +1,2 @@
 export * from './image';
+export * from './image.types';

package/lib/typescript/atoms/index.d.ts

@@ -1,6 +1,7 @@
 export * from './activity-indicator';
 export * from './avatar';
 export * from './badge';
+export * from './blur-view';
 export * from './box';
 export * from './button';
 export * from './card';

package/lib/typescript/atoms/island/island.types.d.ts

@@ -1,7 +1,11 @@
+import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
-/** A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. */
-export type IslandProps = {
+/**
+ * A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. It
+ * sits in that layout like a `Box`, and takes `Box`'s `sx` props for it: `h`, `flex`, margins.
+ */
+export type IslandProps = ResponsiveViewSx & {
     /** The native views it hosts. */
     children?: ReactNode;
     /**
@@ -10,13 +14,13 @@ export type IslandProps = {
      * width maps to `fixedSize(horizontal: true)`, so the native side ignores the proposed width and
      * resolves a `wide` stack's ideal width as unbounded.
      *
-     * Turn it off — and give the island an explicit size via `style` — when the subtree contains an
+     * Turn it off — and give the island an explicit height, `h` — when the subtree contains an
      * `RnView`: that host drives its SwiftUI frame from the child's Yoga-laid-out bounds while this one
      * writes its measured size back into the Yoga style, and the two together spin a layout loop that
      * hangs the main thread as soon as the views lay out on screen.
      */
     matchContents?: boolean;
-    /** A React Native style for the host view — its size and placement. It needs a height when `matchContents` is off. */
+    /** A React Native style for the host view, merged over the `sx` props — for what they cannot say. */
     style?: StyleProp<ViewStyle>;
     /** Test identifier, forwarded to the host view on iOS — Android ignores it. */
     testID?: string;

package/lib/typescript/atoms/pressable/pressable.types.d.ts

@@ -2,13 +2,15 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 import type { Haptic } from '../../haptics';
 /**
- * React Native's `Pressable`, styled through `sx` like a `Box`: it springs down to 96% while pressed and takes
- * touches 8 points past its edges. The React Native tier — it needs no host.
+ * React Native's `Pressable`, styled through `sx` like a `Box`, taking touches 8 points past its edges. The press is
+ * each platform's own: iOS springs it down to 96%; Android draws Material's ripple over the content, clipped to the
+ * pressable's shape — give it the `borderRadius` of what it wraps (`full` around a `GlassView`). The React Native
+ * tier — it needs no host.
  */
 export type PressableProps = ResponsiveViewSx & {
     /** The pressable content. */
     children?: ReactNode;
-    /** Ignores presses — no `onPress`, no haptic, no spring. */
+    /** Ignores presses — no `onPress`, no haptic, no spring or ripple. */
     disabled?: boolean;
     /** Played on press. `true` is a `light` impact; a name picks the haptic, e.g. `selection` for a choice. */
     haptic?: boolean | Haptic;

package/lib/typescript/atoms/rn-text/rn-text.types.d.ts

@@ -1,8 +1,13 @@
+import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ColorToken, TextVariant } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { TextProps as RNTextProps } from 'react-native';
-/** React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. */
-export type RnTextProps = Omit<RNTextProps, 'style'> & {
+/**
+ * React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. It takes
+ * `Box`'s `sx` surface for its own box — margins, flex, padding, a background — all but `align`, which here aligns the
+ * lines.
+ */
+export type RnTextProps = Omit<RNTextProps, 'style'> & Omit<ResponsiveViewSx, 'align'> & {
     /** Horizontal alignment, as React Native's `textAlign`. */
     align?: 'center' | 'left' | 'right';
     /** The text's colour. `content.primary` by default. */

package/lib/typescript/atoms/skeleton/skeleton.types.d.ts

@@ -1,14 +1,18 @@
+import type { SxDimension } from '@hzblj/kara-sx';
 import type { RadiiSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
-/** A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. */
+/**
+ * A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. Sized with the
+ * `sx` names: `w`, `h`, `borderRadius`.
+ */
 export type SkeletonProps = {
     /** The corner radius. `small` by default. */
     borderRadius?: RadiiSize;
     /** In points. */
-    height: number;
+    h: number;
     /** Test identifier, forwarded to the view. */
     testID?: string;
-    /** In points. Leave it unset and it fills the available width. */
-    width?: number;
+    /** In points, or a percentage of the row (`60%` for a line that ends early). Unset, it fills the row. */
+    w?: SxDimension;
 };
 export type SkeletonComponent = (props: SkeletonProps) => ReactNode;

package/lib/typescript/atoms/text/text.types.d.ts

@@ -1,10 +1,15 @@
+import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { ColorToken, TextVariant } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type TextAlign = 'center' | 'left' | 'right';
 export type TextDecoration = 'none' | 'strikethrough' | 'underline';
 export type TextTransform = 'lowercase' | 'uppercase';
-/** SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. */
-export type TextProps = {
+/**
+ * SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. It takes
+ * the native `sx` surface too: padding, a frame (`wide` lines it up by `align`), a background, and the `ios` bucket's
+ * `contentTransition`, `animation` and `monospacedDigit` for a number that changes in place.
+ */
+export type TextProps = ResponsiveSx & {
     /**
      * How its lines align. iOS reads `left` and `right` as leading and trailing, so they flip in a right-to-left
      * layout; Android keeps them as they are.

package/lib/typescript/molecules/scroll-edge-container/scroll-edge-container.types.d.ts

@@ -3,8 +3,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactElement, ReactNode } from 'react';
 export type { ScrollEdgeEffect, ScrollEdgeScrollableProps } from '@hzblj/kara-native/swift-ui';
 /**
- * Bars over one React Native scroll view, with the iOS 26 scroll edge effect under them — the system's progressive
- * blur where content scrolls past a bar. The React Native tier: it needs no host.
+ * Bars over one React Native scroll view, with each platform's scroll edge under them — on iOS 26 the system's
+ * progressive blur where content scrolls past a bar; on Android a Material top app bar's behaviour, the bars stacked
+ * around the scroll view and filling with `surface.secondary` once content scrolls under them. The React Native tier:
+ * it needs no host.
  *
  * A screen-level container: wrap the screen's scroll view with it. Mounted inside a cell of a virtualized list on iOS
  * it draws only its bottom bar — the hosted scroll view and the top bar stay blank.
@@ -15,7 +17,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
      * content begins below the top bar and scrolls under it. On by default.
      */
     automaticInsets?: boolean;
-    /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, where it wants a background. */
+    /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, filled while content continues below. */
     bottomBar?: ReactNode;
     /** Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`. */
     children: ReactElement<ScrollEdgeScrollableProps>;
@@ -23,7 +25,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
     effect?: ScrollEdgeEffect;
     /** Test identifier, forwarded to the container view. */
     testID?: string;
-    /** Laid over the scroll view's top edge on iOS; stacked above it on Android, where it wants a background. */
+    /** Laid over the scroll view's top edge on iOS; stacked above it on Android, filled once content scrolls under it. */
     topBar?: ReactNode;
 };
 export type ScrollEdgeContainerComponent = (props: ScrollEdgeContainerProps) => ReactNode;

package/lib/typescript/molecules/stepper/stepper.ios.d.ts

@@ -1,2 +1,7 @@
 import type { StepperComponent } from './stepper.types';
+/**
+ * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
+ * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
+ * monospaced digits so the row does not jump.
+ */
 export declare const Stepper: StepperComponent;

package/lib/typescript/molecules/stepper/stepper.types.d.ts

@@ -4,10 +4,7 @@ import type { ReactNode } from 'react';
  * two icon buttons in a row. A native atom — it renders inside `<Screen>` or `<Island>`.
  */
 export type StepperProps = {
-    /**
-     * The leading text. iOS shows only the label, not the value — put the value in it if it should be seen. Android
-     * shows the value between its buttons.
-     */
+    /** The leading text. The value is shown too — before the control on iOS, between the buttons on Android. */
     label: string;
     /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
     max?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/hzblj/kara-ui/issues"
   },
-  "homepage": "https://kara.janblazej.dev/docs/components",
+  "homepage": "https://www.kara.janblazej.dev/docs/components",
   "keywords": [
     "react-native",
     "expo",
@@ -59,9 +59,9 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-native": "^0.7.0",
-    "@hzblj/kara-sx": "^0.7.0",
-    "@hzblj/kara-theme": "^0.7.0",
+    "@hzblj/kara-native": "^0.8.0",
+    "@hzblj/kara-sx": "^0.8.0",
+    "@hzblj/kara-theme": "^0.8.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

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

@@ -0,0 +1,32 @@
+import {Host, LoadingIndicator} from '@expo/ui/jetpack-compose'
+import {fillMaxSize, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activity-indicator.types'
+
+/** Material's 48dp for a screen; half of it in a row, about where React Native's small spinner sat. */
+const styles = StyleSheet.create({
+  large: {height: 48, width: 48},
+  small: {height: 24, width: 24},
+})
+
+/**
+ * Material 3's expressive `LoadingIndicator` in a host of its own, sized here rather than measured, so it renders
+ * anywhere and takes its place in the first frame.
+ */
+export const ActivityIndicator: ActivityIndicatorComponent = ({
+  color = 'fill.accent.primary',
+  size = 'small',
+  testID,
+}: ActivityIndicatorProps) => {
+  const theme = useAppTheme()
+  const modifiers = useMemo(() => (testID ? [fillMaxSize(), testIdModifier(testID)] : [fillMaxSize()]), [testID])
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} seedColor={theme.materialSeed} style={styles[size]}>
+      <LoadingIndicator color={theme.color(color)} modifiers={modifiers} />
+    </Host>
+  )
+}

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

@@ -0,0 +1,15 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {ActivityIndicator as RNActivityIndicator} from 'react-native'
+
+import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activity-indicator.types'
+
+/** React Native's spinner, which on iOS is UIKit's own `UIActivityIndicatorView`. */
+export const ActivityIndicator: ActivityIndicatorComponent = ({
+  color = 'fill.accent.primary',
+  size = 'small',
+  testID,
+}: ActivityIndicatorProps) => {
+  const theme = useAppTheme()
+
+  return <RNActivityIndicator color={theme.color(color)} size={size} testID={testID} />
+}

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

@@ -0,0 +1,20 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+import type {ReactNode} from 'react'
+
+export type ActivityIndicatorSize = 'large' | 'small'
+
+/**
+ * That something is loading, for as long as it takes — UIKit's spinner on iOS, Material 3's expressive
+ * `LoadingIndicator` on Android, its shapes morphing as it turns. A React Native view on iOS and a host of its own on
+ * Android, so it renders anywhere. For how far along something is, use `Progress`.
+ */
+export type ActivityIndicatorProps = {
+  /** Its colour. `fill.accent.primary` by default. */
+  color?: ColorToken
+  /** `small` sits in a row or a button, `large` holds a screen that is loading. `small` by default. */
+  size?: ActivityIndicatorSize
+  /** Test identifier, forwarded to the view. */
+  testID?: string
+}
+
+export type ActivityIndicatorComponent = (props: ActivityIndicatorProps) => ReactNode

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

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

package/src/atoms/avatar/avatar.tsx

@@ -32,7 +32,7 @@ export const Avatar: AvatarComponent = ({initials, size = 'md', source, testID}:
       w={diameter}
     >
       {source ? (
-        <Image source={source} style={{height: diameter, width: diameter}} />
+        <Image h={diameter} source={source} w={diameter} />
       ) : (
         <RnText color="content.secondary" variant={VARIANT[size]}>
           {initials ?? ''}

package/src/atoms/blur-view/blur-view.android.tsx

@@ -0,0 +1,68 @@
+import {BackdropBlurView} from '@hzblj/kara-native/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
+import {type ColorToken, type OpacitySize, useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {BlurMaterial, BlurViewComponent, BlurViewProps} from './blur-view.types'
+
+type MaterialSpec = {
+  /** dp. */
+  blur: number
+  /** A Material tonal surface — the thicker the material, the higher the container. */
+  fill: ColorToken
+  /**
+   * How much of the surface covers the blur, light and dark. A dark material covers more, as iOS's do: a dark surface
+   * over a bright backdrop otherwise leaves light content on light colour.
+   */
+  opacity: {dark: OpacitySize; light: OpacitySize}
+  /** iOS's materials lift the colour of what they blur; a plain blur greys it into mud. */
+  saturation: number
+}
+
+const MATERIALS: Record<BlurMaterial, MaterialSpec> = {
+  regular: {blur: 28, fill: 'surface.secondary', opacity: {dark: 'o75', light: 'o60'}, saturation: 1.6},
+  thick: {blur: 30, fill: 'surface.secondary', opacity: {dark: 'o85', light: 'o80'}, saturation: 1.4},
+  thin: {blur: 24, fill: 'surface.primary', opacity: {dark: 'o60', light: 'o40'}, saturation: 1.7},
+  ultraThick: {blur: 32, fill: 'fill.quaternary', opacity: {dark: 'o90', light: 'o90'}, saturation: 1.2},
+  ultraThin: {blur: 20, fill: 'surface.base', opacity: {dark: 'o50', light: 'o25'}, saturation: 1.8},
+}
+
+/**
+ * The materials in Android's terms: kara's `BackdropBlurView` — what lies behind, blurred and saturated — under a
+ * Material tonal surface that gets higher and more opaque as the material thickens. Pinned to the appearance the app
+ * is not in, the surface is Material's inverse one. `vibrancy` has no Android counterpart and is left out.
+ */
+export const BlurView: BlurViewComponent = ({
+  appearance,
+  children,
+  material = 'regular',
+  testID,
+  vibrancy: _vibrancy,
+  ...sx
+}: BlurViewProps) => {
+  const theme = useAppTheme()
+  const resolved = useSx(sx)
+  const spec = MATERIALS[material]
+  const inverted = appearance !== undefined && (appearance === 'dark') !== theme.dark
+  const dark = appearance ? appearance === 'dark' : theme.dark
+  const base = String(theme.color(inverted ? 'surface.high.contrast' : spec.fill))
+  const {cornerRadius, style} = useMemo(() => {
+    const {borderRadius, ...rest} = StyleSheet.flatten(resolved) ?? {}
+    return {cornerRadius: typeof borderRadius === 'number' ? borderRadius : 0, style: rest}
+  }, [resolved])
+
+  return (
+    <BackdropBlurView
+      blurRadius={spec.blur}
+      cornerRadius={cornerRadius}
+      fallbackTint={withOpacity(base, 'o95')}
+      glassTint={withOpacity(base, spec.opacity[dark ? 'dark' : 'light'])}
+      saturation={spec.saturation}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </BackdropBlurView>
+  )
+}