@12-apps/ui 6.19.0 → 6.20.0

package/dist/types-native/components/layout/Skeleton/Skeleton.native.d.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { type DimensionValue, type ViewStyle } from 'react-native';
+import type { SkeletonIntensity, SkeletonProps, SkeletonVariant } from './Skeleton.types.native';
+import type { UiTheme } from '../../../tokens/theme';
+/**
+ * A width or a height, as React Native accepts one. The web takes any CSS
+ * length; here a number is dp and a percentage is a percentage — anything else
+ * (`10rem`, `calc(...)`) has no equivalent and sizes the box from its content,
+ * which `NATIVE-NOTES.md` records.
+ */
+export declare function dimension(value: number | string | undefined): DimensionValue | undefined;
+/** The tint the web writes: the body ink at the intensity's alpha, white in dark mode. */
+export declare const skeletonTint: (theme: UiTheme, intensity: SkeletonIntensity) => string;
+/**
+ * The `text` variant's height. MUI gives it a `1.2em` line box and squashes the
+ * whole box to 60%; React Native's transforms do not change layout, so the two
+ * are multiplied out into the height the web actually shows.
+ */
+export declare function textBoxHeight(theme: UiTheme, height: number | string | undefined): DimensionValue | undefined;
+interface SkeletonBoxStyleArgs {
+    variant: SkeletonVariant;
+    intensity: SkeletonIntensity;
+    width?: number | string;
+    height?: number | string;
+    borderRadius?: number | string;
+    glassmorphism: boolean;
+    /** A box with a wash sliding over it clips, as MUI's `wave` and the shimmer do. */
+    clipped: boolean;
+}
+/** The box the web paints, in absolute numbers. */
+export declare function skeletonBoxStyle(theme: UiTheme, a: SkeletonBoxStyleArgs): ViewStyle;
+/**
+ * The native `Skeleton`: the same box, the same tint and the same default
+ * dimensions the MUI half draws, on a `View`.
+ */
+export declare const Skeleton: React.FC<SkeletonProps>;
+export {};
+//# sourceMappingURL=Skeleton.native.d.ts.map

package/dist/types-native/components/layout/Skeleton/Skeleton.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Skeleton.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/Skeleton/Skeleton.native.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAKL,KAAK,cAAc,EAGnB,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAkBtB,OAAO,KAAK,EAEV,iBAAiB,EACjB,aAAa,EACb,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAMrD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAGxF;AAED,0FAA0F;AAC1F,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,EAAE,WAAW,iBAAiB,KAAG,MAIzE,CAAC;AAQJ;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAClC,cAAc,GAAG,SAAS,CAI5B;AAiBD,UAAU,oBAAoB;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAWnF;AAmGD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,aAAa,CA6C3C,CAAC"}

package/dist/types-native/components/layout/Skeleton/Skeleton.types.native.d.ts

@@ -0,0 +1,8 @@
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+import type { SkeletonBaseProps } from './Skeleton.base';
+export type { SkeletonAnimation, SkeletonBaseProps, SkeletonIntensity, SkeletonVariant, } from './Skeleton.base';
+/** The native `Skeleton`: the shared contract, plus a `View`'s own props. */
+export type SkeletonProps = SkeletonBaseProps & Omit<ViewProps, keyof SkeletonBaseProps | 'style'> & {
+    style?: StyleProp<ViewStyle>;
+};
+//# sourceMappingURL=Skeleton.types.native.d.ts.map

package/dist/types-native/components/layout/Skeleton/Skeleton.types.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Skeleton.types.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/Skeleton/Skeleton.types.native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAC3C,IAAI,CAAC,SAAS,EAAE,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG;IACnD,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B,CAAC"}

package/dist/types-native/components/layout/Skeleton/index.native.d.ts

@@ -0,0 +1,3 @@
+export { Skeleton } from './Skeleton.native';
+export type { SkeletonAnimation, SkeletonBaseProps, SkeletonIntensity, SkeletonProps, SkeletonVariant, } from './Skeleton.types.native';
+//# sourceMappingURL=index.native.d.ts.map

package/dist/types-native/components/layout/Skeleton/index.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/layout/Skeleton/index.native.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,yBAAyB,CAAC"}

package/dist/types-native/icons/paths.generated.d.ts

@@ -5,6 +5,8 @@ export declare const ICON_PATHS: {
     readonly ArrowDownward: readonly ["m20 12-1.41-1.41L13 16.17V4h-2v12.17l-5.58-5.59L4 12l8 8z"];
     readonly ArrowForward: readonly ["m12 4-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z"];
     readonly ArrowUpward: readonly ["m4 12 1.41 1.41L11 7.83V20h2V7.83l5.58 5.59L20 12l-8-8z"];
+    readonly BrokenImage: readonly ["M21 5v6.59l-3-3.01-4 4.01-4-4-4 4-3-3.01V5c0-1.1.9-2 2-2h14c1.1 0 2 .9 2 2m-3 6.42 3 3.01V19c0 1.1-.9 2-2 2H5c-1.1 0-2-.9-2-2v-6.58l3 2.99 4-4 4 4z"];
+    readonly Cancel: readonly ["M12 2C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m5 13.59L15.59 17 12 13.41 8.41 17 7 15.59 10.59 12 7 8.41 8.41 7 12 10.59 15.59 7 17 8.41 13.41 12z"];
     readonly Check: readonly ["M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"];
     readonly CheckCircle: readonly ["M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m-2 15-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8z"];
     readonly ChevronLeft: readonly ["M15.41 7.41 14 6l-6 6 6 6 1.41-1.41L10.83 12z"];

package/dist/types-native/icons/paths.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.generated.d.ts","sourceRoot":"","sources":["../../../src/icons/paths.generated.ts"],"names":[],"mappings":"AAOA,mDAAmD;AACnD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C,eAAO,MAAM,UAAU,EAA8B,SAAS,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"paths.generated.d.ts","sourceRoot":"","sources":["../../../src/icons/paths.generated.ts"],"names":[],"mappings":"AAOA,mDAAmD;AACnD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C,eAAO,MAAM,UAAU,EAA8B,SAAS,QAAQ,EAAE,CAAC"}

package/dist/types-native/platform/animation.d.ts

@@ -0,0 +1,14 @@
+import { Animated } from 'react-native';
+export interface LoopOptions {
+    durationMs: number;
+    /** The CSS animation's delay, run once before the first lap. */
+    delayMs?: number;
+    easing?: (value: number) => number;
+    /**
+     * Layout properties (`left`, `width`, `height`) cannot be driven natively;
+     * `opacity` and `transform` can. Defaults to native everywhere but the web.
+     */
+    useNativeDriver?: boolean;
+}
+export declare function useLoopedProgress(enabled: boolean, options: LoopOptions): Animated.Value;
+//# sourceMappingURL=animation.d.ts.map

package/dist/types-native/platform/animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.d.ts","sourceRoot":"","sources":["../../../src/platform/animation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAoB,MAAM,cAAc,CAAC;AAiB1D,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,QAAQ,CAAC,KAAK,CAsBxF"}

package/dist/types-native/platform/web-keys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * KEY EVENTS REACT NATIVE DOES NOT DECLARE.
+ *
+ * There is no `onKeyDown` on React Native's `ViewProps` or `PressableProps`,
+ * because there is no keyboard behind a `View` on a device. react-native-web
+ * DOES forward one to the DOM, and a component that stands in for a native
+ * control — a chip that removes on Delete, a listbox option that activates on
+ * Space — carries those conventions as part of its contract on the web.
+ *
+ * `webKeyDown` spreads the handler onto a react-native element without that
+ * element's props type having to know it, the way `./aria.ts` does for the
+ * `aria-*` attributes React Native leaves out. On a device it is simply never
+ * called, which is the honest outcome: the gesture is the input there.
+ *
+ * The event is typed structurally rather than as a DOM `KeyboardEvent`, because
+ * the native type program is checked WITHOUT the DOM lib.
+ */
+export interface WebKeyEvent {
+    key: string;
+    preventDefault: () => void;
+}
+export type WebKeyHandler = (event: WebKeyEvent) => void;
+/** `{ onKeyDown }` as something JSX can spread onto a react-native element. */
+export declare function webKeyDown(handler: WebKeyHandler | undefined): object;
+//# sourceMappingURL=web-keys.d.ts.map

package/dist/types-native/platform/web-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-keys.d.ts","sourceRoot":"","sources":["../../../src/platform/web-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AAEzD,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAErE"}

package/dist/types-native/tokens/mui-type.d.ts

@@ -14,7 +14,7 @@ import type { UiTheme } from './theme';
  * halves and not these; each component that reads this records that as a
  * known gap in its `NATIVE-NOTES.md`.
  */
-export type MuiTypeVariantName = 'h6' | 'body1' | 'body2';
+export type MuiTypeVariantName = 'h6' | 'body1' | 'body2' | 'caption';
 export interface MuiTypeVariant {
     fontSize: number;
     lineHeight: number;

package/dist/types-native/tokens/mui-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mui-type.d.ts","sourceRoot":"","sources":["../../../src/tokens/mui-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,kBAAkB,EAAE,cAAc,CAI/D,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,mGAAmG;AACnG,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,GAAG,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAClC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,GAAE,MAAmC,GAC5C,YAAY,CASd"}
+{"version":3,"file":"mui-type.d.ts","sourceRoot":"","sources":["../../../src/tokens/mui-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAEtE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,kBAAkB,EAAE,cAAc,CAK/D,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,mGAAmG;AACnG,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,GAAG,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAClC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,GAAE,MAAmC,GAC5C,YAAY,CASd"}

package/dist/user-avatar.js

@@ -1,10 +1,12 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-HKZHEK3Z.js";
+} from "./chunk-7JWXLDRH.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-QIV73V2X.js";
-import "./chunk-LYNJJV2X.js";
+import "./chunk-7BYFC2MR.js";
+import "./chunk-3ZVUNSFF.js";
+import "./chunk-4SQFO4GW.js";
+import "./chunk-FAITHWIO.js";
 import "./chunk-XRMZMBE3.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
@@ -12,10 +14,10 @@ import "./chunk-D2IASECY.js";
 import "./chunk-VMF3UXM4.js";
 import "./chunk-RI5JZLZL.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-SL4NFGOL.js";
-import "./chunk-TAMIZE4Q.js";
+import "./chunk-24BUCMQA.js";
 import "./chunk-JT6TERQL.js";
 import "./chunk-ITGG5OKP.js";
+import "./chunk-TAMIZE4Q.js";
 import "./chunk-2PCOC3PT.js";
 import "./chunk-V3PLFYKO.js";
 import "./chunk-QLWBQQW7.js";

package/dist/utility/InstallPrompt.js

@@ -1,7 +1,8 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-JE6RZ5L6.js";
+} from "../chunk-5ZOJLYD2.js";
+import "../chunk-GY62N32G.js";
 import {
   usePwaInstall
 } from "../chunk-5GMHJ7Y5.js";
@@ -13,7 +14,6 @@ import {
   readPwaInstallStash,
   resetPwaInstallStash
 } from "../chunk-UUL44SUX.js";
-import "../chunk-GY62N32G.js";
 import "../chunk-PZ5AY32C.js";
 export {
   InstallPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.19.0",
+  "version": "6.20.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -149,10 +149,18 @@
       "default": "./dist/data-display/AlertDialog.js"
     },
     "./data-display/Avatar": {
+      "react-native": {
+        "types": "./dist/types-native/components/data-display/Avatar/index.native.d.ts",
+        "default": "./dist/native/data-display/Avatar.js"
+      },
       "types": "./dist/types/components/data-display/Avatar/index.d.ts",
       "default": "./dist/data-display/Avatar.js"
     },
     "./data-display/Badge": {
+      "react-native": {
+        "types": "./dist/types-native/components/data-display/Badge/index.native.d.ts",
+        "default": "./dist/native/data-display/Badge.js"
+      },
       "types": "./dist/types/components/data-display/Badge/index.d.ts",
       "default": "./dist/data-display/Badge.js"
     },
@@ -169,6 +177,10 @@
       "default": "./dist/data-display/Chart.js"
     },
     "./data-display/Chip": {
+      "react-native": {
+        "types": "./dist/types-native/components/data-display/Chip/index.native.d.ts",
+        "default": "./dist/native/data-display/Chip.js"
+      },
       "types": "./dist/types/components/data-display/Chip/index.d.ts",
       "default": "./dist/data-display/Chip.js"
     },
@@ -225,6 +237,10 @@
       "default": "./dist/data-display/Popover.js"
     },
     "./data-display/Progress": {
+      "react-native": {
+        "types": "./dist/types-native/components/data-display/Progress/index.native.d.ts",
+        "default": "./dist/native/data-display/Progress.js"
+      },
       "types": "./dist/types/components/data-display/Progress/index.d.ts",
       "default": "./dist/data-display/Progress.js"
     },
@@ -493,6 +509,10 @@
       "default": "./dist/layout/Sidebar.js"
     },
     "./layout/Skeleton": {
+      "react-native": {
+        "types": "./dist/types-native/components/layout/Skeleton/index.native.d.ts",
+        "default": "./dist/native/layout/Skeleton.js"
+      },
       "types": "./dist/types/components/layout/Skeleton/index.d.ts",
       "default": "./dist/layout/Skeleton.js"
     },

package/src/components/data-display/Avatar/Avatar.base.ts

@@ -0,0 +1,108 @@
+import type React from 'react';
+
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * This file imports no MUI and no react-native, on purpose: it is in BOTH
+ * declaration outputs (`dist/types` and `dist/types-native`), and a native
+ * consumer has no `@mui/material` to resolve a type import against.
+ */
+
+/**
+ * The house scale, EXTENDED by one stop rather than replacing it.
+ *
+ * `xxl` is real — an avatar is the one component with a portrait size above the
+ * scale's top — so it is added to `SizeValue` instead of the union being
+ * rewritten by hand. Spelling all six out again is how the copy drifts.
+ */
+export type AvatarSize = SizeValue | 'xxl';
+export type AvatarVariant = 'circle' | 'square' | 'rounded' | 'status';
+export type AvatarStatus = 'online' | 'offline' | 'away' | 'busy';
+
+/** Which of the four content sources won, and therefore which slot id it takes. */
+export type ContentType = 'children' | 'fallback' | 'icon' | 'default';
+
+export interface AvatarBaseProps {
+  /**
+   * The variant of the avatar
+   */
+  variant?: AvatarVariant;
+
+  /**
+   * The size of the avatar
+   */
+  size?: AvatarSize;
+
+  /**
+   * Whether the avatar should have a glow effect
+   */
+  glow?: boolean;
+
+  /**
+   * Whether the avatar should have a pulse animation
+   */
+  pulse?: boolean;
+
+  /**
+   * Status indicator (only applies when variant is 'status')
+   */
+  status?: AvatarStatus;
+
+  /**
+   * Fallback text when no src is provided (typically initials)
+   */
+  fallback?: string;
+
+  /**
+   * Custom icon to display
+   */
+  icon?: React.ReactNode;
+
+  /**
+   * Whether to show a border around the avatar
+   */
+  bordered?: boolean;
+
+  /**
+   * Color of the avatar background when no image is provided
+   */
+  color?: ColorValue;
+
+  /**
+   * Whether the avatar is in a loading state
+   */
+  loading?: boolean;
+
+  /**
+   * Whether the avatar should be interactive (show hover effects)
+   */
+  interactive?: boolean;
+
+  /**
+   * Whether to show fallback content on image error
+   */
+  showFallbackOnError?: boolean;
+
+  /**
+   * Animation delay in milliseconds
+   */
+  animationDelay?: number;
+
+  /** The portrait itself. */
+  src?: string;
+
+  /** The portrait's description, and the avatar's accessible name. */
+  alt?: string;
+
+  children?: React.ReactNode;
+
+  /**
+   * Test ID for automated testing
+   */
+  dataTestId?: string;
+
+  /** React Native's spelling of {@link AvatarBaseProps.dataTestId}. */
+  testID?: string;
+}

package/src/components/data-display/Avatar/Avatar.helpers.ts

@@ -0,0 +1,54 @@
+import type { AvatarBaseProps, ContentType } from './Avatar.base';
+
+/** Applied via a single spread so no per-field default inflates cyclomatic complexity. */
+export const AVATAR_DEFAULTS = {
+  variant: 'circle',
+  size: 'md',
+  glow: false,
+  pulse: false,
+  bordered: false,
+  color: 'primary',
+  loading: false,
+  interactive: false,
+  showFallbackOnError: true,
+  animationDelay: 0,
+} satisfies Partial<AvatarBaseProps>;
+
+/** What wins the middle of the avatar. `broken` is the icon slot's error glyph. */
+export type AvatarContentPick = ContentType | 'broken';
+
+export interface AvatarContentArgs {
+  hasChildren: boolean;
+  hasFallback: boolean;
+  hasIcon: boolean;
+  imageError: boolean;
+  showFallbackOnError: boolean;
+}
+
+/**
+ * Pick what renders inside the avatar. On an image error (with fallback
+ * enabled) the fallback/icon/broken-image wins; otherwise children → fallback →
+ * icon → the default person glyph.
+ *
+ * The DECISION is shared; each renderer builds its own node from it, because
+ * the two draw a glyph with different things.
+ */
+export function pickAvatarContent(a: AvatarContentArgs): AvatarContentPick {
+  if (a.imageError && a.showFallbackOnError) {
+    if (a.hasFallback) return 'fallback';
+    return a.hasIcon ? 'icon' : 'broken';
+  }
+  if (a.hasChildren) return 'children';
+  if (a.hasFallback) return 'fallback';
+  return a.hasIcon ? 'icon' : 'default';
+}
+
+/** The slot id a pick takes; the broken-image glyph shares the icon slot's. */
+export const contentTypeOf = (pick: AvatarContentPick): ContentType =>
+  pick === 'broken' ? 'icon' : pick;
+
+/** `${dataTestId}-loading`, or nothing at all when the caller named nothing. */
+export const avatarTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string | undefined =>
+    dataTestId ? `${dataTestId}-${suffix}` : undefined;

package/src/components/data-display/Avatar/Avatar.look.native.ts

@@ -0,0 +1,123 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+import type { AvatarSize, AvatarVariant } from './Avatar.base';
+import {
+  AVATAR_SIZES,
+  BORDER_HALO_ALPHA,
+  BORDER_WIDTH,
+  GLOW,
+  LOADING_OVERLAY,
+  ROUNDED_RADIUS_UNITS,
+  SPINNER,
+  STATUS_DOT,
+  avatarAccent,
+} from './Avatar.metrics';
+import { alpha } from '../../../tokens/color';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/** `square` is sharp, `rounded` takes a spacing unit, `circle` and `status` are round. */
+export function avatarRadius(theme: UiTheme, variant: AvatarVariant, box: number): number {
+  if (variant === 'square') return 0;
+  if (variant === 'rounded') return theme.spacing(ROUNDED_RADIUS_UNITS);
+  return box / 2;
+}
+
+export interface AvatarSurfaceArgs {
+  variant: AvatarVariant;
+  size: AvatarSize;
+  color: ColorValue;
+  glow: boolean;
+  bordered: boolean;
+  interactive: boolean;
+  hasError: boolean;
+}
+
+/** The avatar box: MUI's square, its radius, the accent behind the initials. */
+export function avatarSurfaceStyle(theme: UiTheme, a: AvatarSurfaceArgs): ViewStyle {
+  const { box } = AVATAR_SIZES[a.size];
+  const accent = avatarAccent(theme, a.color);
+  return {
+    width: box,
+    height: box,
+    borderRadius: avatarRadius(theme, a.variant, box),
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+    backgroundColor: a.hasError ? theme.palette.danger.main : accent.main,
+    cursor: a.interactive ? 'pointer' : 'auto',
+    ...(a.bordered
+      ? {
+          borderWidth: BORDER_WIDTH,
+          borderColor: theme.palette.background.paper,
+          boxShadow: `0 0 0 1px ${alpha(theme.palette.divider, BORDER_HALO_ALPHA)}`,
+        }
+      : {}),
+    ...(a.glow
+      ? { boxShadow: `0 0 ${GLOW.blur}px ${GLOW.spread}px ${alpha(accent.main, GLOW.alpha)}` }
+      : {}),
+  };
+}
+
+/** The initials, in the accent's contrast ink at the size's own step. */
+export function avatarTextStyle(
+  theme: UiTheme,
+  size: AvatarSize,
+  color: ColorValue,
+  hasError: boolean,
+): TextStyle {
+  const accent = avatarAccent(theme, color);
+  return {
+    fontFamily: theme.typography.fontFamily,
+    fontSize: AVATAR_SIZES[size].fontSize,
+    textAlign: 'center',
+    color: hasError ? theme.palette.danger.contrastText : accent.contrastText,
+  };
+}
+
+/** The wash over a loading avatar, and the ring spinning in it. */
+export function avatarLoadingStyle(theme: UiTheme, size: AvatarSize, radius: number): ViewStyle {
+  const { box } = AVATAR_SIZES[size];
+  return {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: box,
+    height: box,
+    borderRadius: radius,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: alpha(theme.palette.background.paper, LOADING_OVERLAY.paperAlpha),
+  };
+}
+
+export function avatarSpinnerStyle(theme: UiTheme, size: AvatarSize): ViewStyle {
+  const ring = AVATAR_SIZES[size].box * SPINNER.scale;
+  return {
+    width: ring,
+    height: ring,
+    borderRadius: ring / 2,
+    borderWidth: SPINNER.ringWidth,
+    borderColor: alpha(theme.palette.primary.main, SPINNER.trackAlpha),
+    borderTopColor: theme.palette.primary.main,
+  };
+}
+
+/** MUI's `Badge` dot, anchored bottom-right of a circular avatar. */
+export function avatarStatusDotStyle(theme: UiTheme, size: AvatarSize, color: string): ViewStyle {
+  const { box } = AVATAR_SIZES[size];
+  const dot = Math.max(STATUS_DOT.min, box * STATUS_DOT.scale);
+  // MUI's `overlap="circular"` puts the dot's centre 14% in from the corner.
+  const inset = box * STATUS_DOT.anchor - dot / 2;
+  return {
+    position: 'absolute',
+    right: inset,
+    bottom: inset,
+    width: dot,
+    height: dot,
+    borderRadius: dot / 2,
+    backgroundColor: color,
+    borderWidth: STATUS_DOT.borderWidth,
+    borderColor: theme.palette.background.paper,
+  };
+}

package/src/components/data-display/Avatar/Avatar.metrics.ts

@@ -0,0 +1,111 @@
+import type { AvatarSize, AvatarStatus } from './Avatar.base';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `Avatar` RENDERERS DRAW WITH.
+ *
+ * `Avatar.view.tsx` (web, emotion over MUI's `Avatar` and `Badge`) and
+ * `Avatar.native.tsx` (React Native) read this one table: the six boxes and
+ * their type, the status dot, the glow, the shimmer and the spinner. The web
+ * turns the px into rem; native uses the numbers.
+ */
+export interface AvatarSizeMetrics {
+  /** The square the portrait fills, in px. */
+  box: number;
+  /** The initials' type size, in px. */
+  fontSize: number;
+}
+
+export const AVATAR_SIZES: Record<AvatarSize, AvatarSizeMetrics> = {
+  xs: { box: 24, fontSize: 12 },
+  sm: { box: 32, fontSize: 14 },
+  md: { box: 40, fontSize: 16 },
+  lg: { box: 48, fontSize: 18 },
+  xl: { box: 64, fontSize: 24 },
+  xxl: { box: 80, fontSize: 32 },
+};
+
+/** `rounded` takes one spacing unit; `circle` and `status` are round. */
+export const ROUNDED_RADIUS_UNITS = 1;
+
+/** The paper ring an avatar takes inside a group, and the hairline outside it. */
+export const BORDER_WIDTH = 2;
+export const BORDER_HALO_ALPHA = 0.2;
+
+/** `glow`: a 20px halo at five pixels of spread, and a brightness lift. */
+export const GLOW = { blur: 20, spread: 5, alpha: 0.4, brightness: 1.05 } as const;
+
+/** `pulse`: the `::after` ring, from nothing to 10px while it fades out. */
+export const PULSE = { durationMs: 2000, alpha: 0.3, spread: 10 } as const;
+
+/** The shimmer that runs across a loading avatar. */
+export const SHIMMER = { durationMs: 1500, fromAlpha: 0.6, toAlpha: 0.8 } as const;
+
+/** The overlay over a loading avatar, and the ring spinning in it. */
+export const LOADING_OVERLAY = { paperAlpha: 0.7, blur: 2 } as const;
+export const SPINNER = {
+  /** A share of the avatar's box. */
+  scale: 0.4,
+  ringWidth: 2,
+  trackAlpha: 0.3,
+  durationMs: 800,
+} as const;
+
+/**
+ * The status dot: a fifth of the box, never below 8px, inside a paper ring.
+ * `anchor` is MUI's `overlap="circular"` inset — the dot's CENTRE sits 14% of
+ * the box in from the bottom-right corner.
+ */
+export const STATUS_DOT = { scale: 0.2, min: 8, borderWidth: 2, anchor: 0.14 } as const;
+
+/**
+ * The default and broken-image glyphs are ordinary `SvgIcon`s here, not MUI's
+ * own `.MuiAvatar-fallback` (which is 75% of the box): this component passes
+ * them as CHILDREN, so they render at the icon default whatever the box is.
+ */
+export const GLYPH_SIZE = 24;
+
+/** MUI's `Fade` timeout on mount, and the scale-in behind it. */
+export const FADE_MS = 300;
+export const SCALE_IN_MS = 300;
+
+/** `transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1)`. */
+export const AVATAR_TRANSITION_MS = 300;
+export const AVATAR_TRANSITION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+
+/** The interactive lift, which is a `:hover` on the web. */
+export const HOVER = { scale: 1.1, lift: 2, shadowY: 8, shadowBlur: 20, shadowAlpha: 0.3, brightness: 1.1 } as const;
+export const ACTIVE_SCALE = 1.05;
+
+/** The focus ring `:focus-visible` draws. */
+export const FOCUS_RING = { width: 3, offset: 2, alpha: 0.5 } as const;
+
+/** An avatar group's default overlap, in px, and its hover lift. */
+export const GROUP_OVERLAP = 8;
+export const GROUP_MAX = 4;
+export const GROUP_HOVER = { scale: 1.1, lift: 4 } as const;
+
+/** The dot's colour per status. `offline` is the ramp, the rest are semantic. */
+export function statusColor(theme: UiTheme, status: AvatarStatus): string {
+  if (status === 'online') return theme.palette.success.main;
+  if (status === 'away') return theme.palette.warning.main;
+  if (status === 'busy') return theme.palette.danger.main;
+  return theme.palette.grey[500];
+}
+
+export interface AvatarAccent {
+  main: string;
+  contrastText: string;
+}
+
+/**
+ * The accent behind the initials. `danger`, NOT `error` — the web map was keyed
+ * on MUI's word while the prop took the house one, so `danger` matched nothing
+ * and fell through to primary: a red avatar rendering blue, silently.
+ */
+export function avatarAccent(theme: UiTheme, color: ColorValue): AvatarAccent {
+  if (color === 'neutral') return { main: theme.palette.grey[700], contrastText: '#fff' };
+  const accent = theme.palette[color];
+  return { main: accent.main, contrastText: accent.contrastText || '#fff' };
+}