@multiplatform.one/components 6.7.0 → 7.1.0

package/src/images/Image/index.tsx

@@ -1,20 +1,21 @@
-import { useMemo } from "react";
-import type { ImageURISource } from "react-native";
+import { useCallback, useEffect, useState } from "react";
 import { Image as TamaguiImage } from "tamagui";
-import { useAssets } from "../../hooks/useAssets";
+import { ImageFrame, mediaFillProps, type ImageStatus } from "./ImageFrame";
+import { isThumbnailSize, useResolvedImageSource } from "./shared";
 import type { ImageProps } from "./types";
 
 export type { ImageProps } from "./types";
 
 export function Image({
-  alt,
+  alt = "",
   blurRadius: _blurRadius,
   capInsets: _capInsets,
   crossOrigin,
   defaultSource: _defaultSource,
   fadeDuration: _fadeDuration,
   loadingIndicatorSource: _loadingIndicatorSource,
-  objectFit,
+  objectFit: objectFitProp,
+  objectPosition,
   onError,
   onLoad,
   onLoadEnd,
@@ -29,60 +30,111 @@ export function Image({
   srcSet,
   svg: _svg,
   tintColor: _tintColor,
+  fill = false,
+  sizes,
+  loading: loadingProp,
+  priority,
+  placeholder = "empty",
+  placeholderSrc,
+  fallback,
+  framed,
+  size,
+  compact = false,
+  groupPosition,
+  groupOrientation,
+  decoding = "async",
+  onPress,
+  disabled,
+  width,
+  height,
+  aspectRatio,
+  borderRadius,
   ...props
 }: ImageProps) {
-  const source = sourceProp || src;
-  const [asset] = useAssets(typeof source === "number" ? [source] : []);
+  const { source, resolvedSrc } = useResolvedImageSource(sourceProp, src);
+  const hasSource = Boolean(resolvedSrc) || typeof source === "number";
+  const thumbnail = size != null && (isThumbnailSize(size) || typeof size === "number");
+  const isFramed = framed ?? thumbnail;
+  const objectFit = objectFitProp ?? (fill || thumbnail ? "cover" : undefined);
+  const loading = priority ? "eager" : (loadingProp ?? "lazy");
 
-  const imageUriSource = useMemo(() => {
-    if (typeof source === "string") {
-      return { uri: source } satisfies ImageURISource;
-    }
-    if (typeof source === "number") return asset;
-    return (
-      (source as { default?: ImageURISource | ImageURISource[] })?.default ||
-      (source as ImageURISource | ImageURISource[])
-    );
-  }, [asset, source]);
+  const [status, setStatus] = useState<ImageStatus>(() => (hasSource ? "loading" : "error"));
+  useEffect(() => {
+    setStatus(hasSource ? "loading" : "error");
+  }, [hasSource, resolvedSrc]);
 
-  const resolvedSrc = useMemo(() => {
-    if (typeof source === "string") return source;
-    if (!imageUriSource || Array.isArray(imageUriSource)) return undefined;
-    return imageUriSource.uri;
-  }, [source, imageUriSource]);
-
-  if (!resolvedSrc && typeof source !== "number") return null;
+  const handleLoad = useCallback(
+    (event?: Parameters<NonNullable<ImageProps["onLoad"]>>[0]) => {
+      setStatus("loaded");
+      onLoad?.(event);
+    },
+    [onLoad],
+  );
+  const handleError = useCallback(
+    (error: Parameters<NonNullable<ImageProps["onError"]>>[0]) => {
+      setStatus("error");
+      onError?.(error);
+    },
+    [onError],
+  );
 
-  // Height-only images: without this, a stretch-aligned flex parent widens the
-  // <img> to the full container width and breaks the intrinsic aspect ratio.
-  // Deriving width from the aspect (width: auto + no cross-axis stretch)
-  // mirrors how the width-only path keeps its ratio.
-  const { width, height, aspectRatio } = props as {
-    width?: unknown;
-    height?: unknown;
-    aspectRatio?: unknown;
-  };
-  const heightOnly =
-    typeof height !== "undefined" &&
-    typeof width === "undefined" &&
-    typeof aspectRatio === "undefined";
+  if (!hasSource && !isFramed && fallback == null && !fill && size == null) {
+    return null;
+  }
 
   return (
-    <TamaguiImage
-      {...(props as any)}
-      {...(heightOnly && { width: "auto", alignSelf: "flex-start" })}
+    <ImageFrame
       alt={alt}
-      crossOrigin={crossOrigin}
+      fill={fill}
+      framed={isFramed}
+      compact={compact}
+      groupPosition={groupPosition}
+      groupOrientation={groupOrientation}
+      size={size}
+      width={width}
+      height={height}
+      aspectRatio={aspectRatio}
+      borderRadius={borderRadius}
       objectFit={objectFit}
-      onError={onError as any}
-      onLoad={onLoad as any}
-      onLoadEnd={onLoadEnd}
-      onLoadStart={onLoadStart}
-      onProgress={onProgress}
-      referrerPolicy={referrerPolicy}
-      source={imageUriSource}
-      src={resolvedSrc}
-      srcSet={srcSet}
-    />
+      objectPosition={objectPosition}
+      onPress={onPress}
+      disabled={disabled}
+      hasSource={hasSource}
+      status={status}
+      placeholder={placeholder}
+      placeholderSrc={placeholderSrc}
+      fallback={fallback}
+      {...props}
+    >
+      {hasSource && status !== "error" ? (
+        <TamaguiImage
+          alt={alt}
+          crossOrigin={crossOrigin}
+          decoding={decoding}
+          fetchPriority={priority ? "high" : undefined}
+          loading={loading}
+          objectFit={objectFit}
+          objectPosition={objectPosition}
+          onError={handleError as never}
+          onLoad={handleLoad as never}
+          onLoadEnd={onLoadEnd}
+          onLoadStart={onLoadStart}
+          onProgress={onProgress}
+          referrerPolicy={referrerPolicy}
+          sizes={sizes}
+          src={resolvedSrc}
+          srcSet={srcSet}
+          {...mediaFillProps({
+            fill,
+            thumbnail,
+            width,
+            height,
+            aspectRatio,
+            objectFit,
+            objectPosition,
+          })}
+        />
+      ) : null}
+    </ImageFrame>
   );
 }

package/src/images/Image/shared.ts

@@ -0,0 +1,88 @@
+import { useMemo } from "react";
+import type { ImageURISource } from "react-native";
+import { useAssets } from "../../hooks/useAssets";
+import type { ImageThumbnailSize } from "./types";
+
+export function isThumbnailSize(size: unknown): size is ImageThumbnailSize {
+  return size === "extraSmall" || size === "small" || size === "medium" || size === "large";
+}
+
+export function thumbnailPx(
+  size: ImageThumbnailSize | number,
+  nestedPx: number,
+  compact: boolean,
+): number {
+  if (typeof size === "number") return Math.max(0, size);
+  if (size === "extraSmall") return nestedPx;
+  if (compact) {
+    if (size === "small") return nestedPx;
+    if (size === "medium") return 40;
+    return 60;
+  }
+  if (size === "small") return 40;
+  if (size === "medium") return 60;
+  return 80;
+}
+
+export function isSvgUri(uri: string | undefined, svgFlag?: boolean): boolean {
+  if (svgFlag) return true;
+  if (!uri) return false;
+  return /\.svg([?#]|$)/.test(uri) || uri.startsWith("data:image/svg+xml");
+}
+
+export function useResolvedImageSource(sourceProp: unknown, src: unknown) {
+  const source = sourceProp || src;
+  const [asset] = useAssets(typeof source === "number" ? [source] : []);
+
+  const imageUriSource = useMemo(() => {
+    if (typeof source === "string") {
+      return { uri: source } satisfies ImageURISource;
+    }
+    if (typeof source === "number") return asset;
+    return (
+      (source as { default?: ImageURISource | ImageURISource[] })?.default ||
+      (source as ImageURISource | ImageURISource[])
+    );
+  }, [asset, source]);
+
+  const resolvedSrc = useMemo(() => {
+    if (typeof source === "string") return source;
+    if (!imageUriSource || Array.isArray(imageUriSource)) return undefined;
+    return imageUriSource.uri;
+  }, [source, imageUriSource]);
+
+  return { source, imageUriSource, resolvedSrc };
+}
+
+export function objectFitToResizeMode(
+  objectFit: string | undefined,
+): "cover" | "contain" | "stretch" | "center" | undefined {
+  switch (objectFit) {
+    case "cover":
+      return "cover";
+    case "contain":
+    case "scale-down":
+      return "contain";
+    case "fill":
+      return "stretch";
+    case "none":
+      return "center";
+    default:
+      return undefined;
+  }
+}
+
+export function svgPreserveAspectRatio(objectFit: string | undefined): string | undefined {
+  switch (objectFit) {
+    case "contain":
+    case "scale-down":
+      return "xMidYMid meet";
+    case "cover":
+      return "xMidYMid slice";
+    case "fill":
+    case "none":
+      return "none";
+    default:
+      return undefined;
+  }
+}

package/src/images/Image/types.ts

@@ -1,8 +1,39 @@
+import type { ReactNode } from "react";
 import type { ImageErrorEventData, ImageLoadEventData, NativeSyntheticEvent } from "react-native";
+import type { GroupOrientation, GroupPosition } from "@multiplatform.one/theme";
 import type { ImageProps as TamaguiImageProps } from "tamagui";
 
-export type ImageProps = Omit<TamaguiImageProps, "resizeMode" | "onLoad" | "onError"> & {
+/** Polaris Thumbnail sizes. `extraSmall` is the LC-73 nested control box. */
+export type ImageThumbnailSize = "extraSmall" | "small" | "medium" | "large";
+
+export type ImagePlaceholder = "empty" | "blur" | "skeleton" | ReactNode;
+
+export type ImageProps = Omit<
+  TamaguiImageProps,
+  "resizeMode" | "onLoad" | "onError" | "size" | "fill"
+> & {
   onLoad?: (event?: NativeSyntheticEvent<ImageLoadEventData>) => void;
   onError?: (error: NativeSyntheticEvent<ImageErrorEventData> | Error) => void;
   svg?: boolean;
+  /** Next.js `fill` — paint the positioned parent (absolute inset 0). */
+  fill?: boolean;
+  /** Responsive hint for `srcset` (Next.js `sizes`). */
+  sizes?: string;
+  loading?: "lazy" | "eager";
+  /** Above-the-fold: `loading=eager` + `fetchPriority=high`. */
+  priority?: boolean;
+  placeholder?: ImagePlaceholder;
+  /** Blur-up source (Next.js `blurDataURL` / Expo placeholder URI). */
+  placeholderSrc?: string;
+  /** LC-08: shown when the asset is missing or fails. */
+  fallback?: ReactNode;
+  objectPosition?: string;
+  /** Polaris Thumbnail chrome: surface + radius recipes, cover fit. */
+  framed?: boolean;
+  /** Square thumbnail. Number is px. `extraSmall` uses nestedControl (LC-73). */
+  size?: ImageThumbnailSize | number;
+  compact?: boolean;
+  groupPosition?: GroupPosition;
+  groupOrientation?: GroupOrientation;
+  decoding?: "async" | "auto" | "sync";
 };

package/src/index.ts

@@ -38,6 +38,8 @@ export type {
   AccordionTriggerProps,
   AccordionContentProps,
 } from "./Accordion";
+export { AnimateHeight, settleMs } from "./AnimateHeight";
+export type { AnimateHeightProps } from "./AnimateHeight";
 // Explicit named export wins over the `export * from "tamagui"` star export
 // (same pattern as Tooltip) so MP1 Tabs shadows the tamagui primitive.
 export { Tabs } from "./Tabs";
@@ -90,6 +92,22 @@ export type { AvatarProps, AvatarSize } from "./Avatar";
 export { Fieldset } from "@multiplatform.one/forms";
 export type { FieldsetProps } from "@multiplatform.one/forms";
 
+// Shadow tamagui Spinner with the knob-consuming forms Spinner (LC-70 census
+// 2026-08-13): raw Spinner keeps spinning at animation "none" /
+// prefers-reduced-motion and ignores the size knob; the forms house version
+// gates its motion on knobProps.transition, maps the size knob's top step to
+// "large", and carries role="status" a11y. The curated ./tamagui surface no
+// longer exports the bare name; raw stays reachable as TamaguiSpinner.
+export { Spinner } from "@multiplatform.one/forms";
+export type { SpinnerProps } from "@multiplatform.one/forms";
+
+// Shadow tamagui Button with the house wrapper over the forms Button
+// (knob fragments + LC-54 press floor + LC-53 icon slot, plus the raw
+// `variant="outlined"` prop-compat). The curated ./tamagui surface no
+// longer exports the bare name; raw stays reachable as TamaguiButton.
+export { Button } from "./Button";
+export type { ButtonProps } from "./Button";
+
 export type { ImageProps } from "./images/Image";
 export { Image } from "./images/Image";
 

package/src/knobImmuneExports.ts

@@ -0,0 +1,97 @@
+/**
+ * LC-70 CURATED-REEXPORT-IS-CATALOG registry — every bare-name export of the
+ * @multiplatform.one/components barrel that IS a raw framework re-export
+ * (value-identical to the tamagui / @tamagui/toast export of the same name)
+ * must have a row here declaring WHY it is knob-immune, or the export-surface
+ * spec (./export-surface.spec.tsx) fails the suite.
+ *
+ * A row is a declaration that the knob channel legitimately does not apply to
+ * this export — NOT an amnesty for knob-dead painted UI. If a raw primitive
+ * paints opinionated chrome (radius, padding, press states) it belongs behind
+ * a `Tamagui*` escape hatch or a house shadow (Button/Spinner precedent), not
+ * in this file. Rows marked ADJUDICATION-CANDIDATE are flagged for the
+ * rulebook owner; see the census report.
+ *
+ * Locked both directions by export-surface.spec.tsx:
+ *  - every raw bare export must be registered (or Tamagui*-prefixed);
+ *  - every row must correspond to a live raw bare export (no stale rows, no
+ *    laundering house implementations through the registry).
+ */
+export const knobImmuneExports: Readonly<Record<string, string>> = {
+  // ── Structural layout lego ────────────────────────────────────────────
+  // The knobs system is designed around these: house surfaces SPREAD
+  // knobProps.* fragments ONTO View/Stack/etc (knobs-system.md). The lego
+  // itself carries no opinionated chrome; a self-knobbing primitive would
+  // double-apply fragments under every house surface.
+  View: "unopinionated layout lego; knob fragments are spread onto it by composing surfaces",
+  XStack: "unopinionated layout lego; knob fragments are spread onto it by composing surfaces",
+  YStack: "unopinionated layout lego; knob fragments are spread onto it by composing surfaces",
+  XGroup: "layout grouping lego; knob fragments are spread onto it by composing surfaces",
+  YGroup: "layout grouping lego; knob fragments are spread onto it by composing surfaces",
+  Group: "layout grouping lego; knob fragments are spread onto it by composing surfaces",
+  Spacer: "pure whitespace; no paintable chrome for knobs to reach",
+  Square: "geometric lego (fixed aspect); consumers spread knob fragments onto it",
+  Circle: "geometric lego (identity circle by definition); radius knob story is N/A",
+  ScrollView: "scroll container lego; no opinionated chrome, fragments ride the content",
+  Separator:
+    "token-driven hairline ($borderColor / hairline width); no knob channel maps to it today. ADJUDICATION-CANDIDATE: should borderWidth knob drive separator weight?",
+  ListItem:
+    "raw list-row primitive consumed as lego by house list surfaces (List, sidebar, tags) which own the knob story. ADJUDICATION-CANDIDATE + BACKLOG: painted row with own padding/press states — deserves a house shadow or Tamagui* demotion once consumers migrate",
+
+  // ── Typography lego ───────────────────────────────────────────────────
+  // Text knobs (bodyFont, headingFont, fontWeight, textAccent) ride the
+  // knobProps.body / knobProps.heading fragments that composing surfaces
+  // spread; the primitives are the substrate those fragments land on.
+  Text: "typography substrate; font knobs ride knobProps.body/heading fragments spread by surfaces",
+  SizableText: "typography substrate; font knobs ride spread fragments",
+  Paragraph: "typography substrate; font knobs ride spread fragments",
+  Heading: "typography substrate; font knobs ride knobProps.heading fragments",
+  H1: "typography substrate; heading knobs ride knobProps.heading/pageTitle fragments",
+  H2: "typography substrate; heading knobs ride knobProps.heading fragments",
+  H3: "typography substrate; heading knobs ride knobProps.heading fragments",
+  H4: "typography substrate; heading knobs ride knobProps.heading fragments",
+  H5: "typography substrate; heading knobs ride knobProps.heading fragments",
+  H6: "typography substrate; heading knobs ride knobProps.heading fragments",
+  Anchor:
+    "text link substrate; typography knobs ride spread fragments. ADJUDICATION-CANDIDATE: link color/underline currently tamagui-default, no LC rule owns link chrome",
+
+  // ── Overlay composition roots ─────────────────────────────────────────
+  // Logic shells with no painted frame of their own; the knob channel lands
+  // on the house content surfaces designed to fill them (DialogContent,
+  // PopoverContent, SheetFrame, ConfirmDialog).
+  Dialog: "composition root (logic/portal shell); knobs land on house DialogContent",
+  AlertDialog:
+    "composition root; knobs land on house ConfirmDialog / DialogContent surfaces composed inside",
+  Popover: "composition root; knobs land on house PopoverContent",
+  Sheet: "composition root; knobs land on house SheetFrame",
+  Adapt: "platform adaptation control-flow component; renders nothing itself",
+  Portal: "reparenting utility; renders children elsewhere, paints nothing",
+  PortalProvider: "provider; paints nothing",
+
+  // ── Providers / theme / animation drivers ────────────────────────────
+  TamaguiProvider: "root provider (tamagui's own name, not an escape hatch); paints nothing",
+  Theme: "theme scoping provider; hue selection is the theme system, not a knob",
+  AnimatePresence:
+    "mount/unmount choreography wrapper; motion values come from knob-gated children",
+
+  // ── Hooks (non-visual) ────────────────────────────────────────────────
+  useControllableState: "state hook; no rendered output",
+  useDidFinishSSR: "SSR lifecycle hook; no rendered output",
+  useEvent: "callback identity hook; no rendered output",
+  useMedia: "media query hook; no rendered output",
+  usePropsAndStyle: "style resolution hook; no rendered output",
+  useTheme: "theme access hook; no rendered output",
+  useThemeName: "theme access hook; no rendered output",
+  useToastController: "imperative toast controller hook (@tamagui/toast); no rendered output",
+  useToastState: "toast state hook (@tamagui/toast); no rendered output",
+
+  // ── Styling / token utilities (non-visual) ────────────────────────────
+  styled: "component factory; output components consume knobs where house code applies them",
+  createStyledContext: "context factory utility; no rendered output",
+  withStaticProperties: "object composition utility; no rendered output",
+  getToken: "token lookup utility; no rendered output",
+  getTokens: "token lookup utility; no rendered output",
+  getTokenValue: "token lookup utility; no rendered output",
+  isClient: "environment boolean; not a component",
+  isWeb: "environment boolean; not a component",
+};

package/src/layouts/AsyncBoundary.spec.tsx

@@ -55,6 +55,83 @@ describe("AsyncBoundary", () => {
     expect(screen.queryByText("No items found")).toBeNull();
   });
 
+  it("keeps previous data on refetch instead of replacing it with a skeleton", () => {
+    const { rerender } = renderWithProviders(
+      <AsyncBoundary layout="list">
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+    expect(screen.getByText("Ready rows")).toBeInTheDocument();
+
+    rerender(
+      <AsyncBoundary loading layout="list">
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+
+    expect(screen.getByText("Ready rows")).toBeInTheDocument();
+    expect(document.querySelector("[data-async-skeleton]")).toBeNull();
+    expect(document.querySelector("[data-async-pending]")).toBeTruthy();
+    expect(document.querySelector('[data-async-status="data"]')).toBeTruthy();
+    expect(document.querySelector("[data-async-status]")).toHaveAttribute("aria-busy", "true");
+  });
+
+  it("keeps previous data when children unmount during a refetch", () => {
+    const { rerender } = renderWithProviders(
+      <AsyncBoundary layout="list">
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+
+    rerender(<AsyncBoundary loading layout="list" />);
+
+    expect(screen.getByText("Ready rows")).toBeInTheDocument();
+    expect(document.querySelector("[data-async-skeleton]")).toBeNull();
+  });
+
+  it("still blanks on refetch when keepPrevious is false", () => {
+    const { rerender } = renderWithProviders(
+      <AsyncBoundary layout="list">
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+
+    rerender(
+      <AsyncBoundary loading keepPrevious={false} layout="list">
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+
+    expect(screen.queryByText("Ready rows")).toBeNull();
+    expect(document.querySelector("[data-async-skeleton]")).toBeTruthy();
+  });
+
+  it("keeps previous data on a refetch error and still offers retry", () => {
+    const onRetry = vi.fn();
+    const { rerender } = renderWithProviders(
+      <AsyncBoundary layout="list" onRetry={onRetry}>
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+
+    rerender(
+      <AsyncBoundary
+        error="Network unreachable"
+        errorTitle="Couldn't load data"
+        layout="list"
+        onRetry={onRetry}
+      >
+        <Text>Ready rows</Text>
+      </AsyncBoundary>,
+    );
+
+    expect(screen.getByText("Ready rows")).toBeInTheDocument();
+    expect(screen.getByText("Couldn't load data")).toBeInTheDocument();
+    expect(document.querySelector("[data-async-stale]")).toBeTruthy();
+    fireEvent.click(screen.getByText("Retry"));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+  });
+
   it("shows empty chrome only when empty and not error (DG-ST-01)", () => {
     renderWithProviders(<AsyncBoundary empty emptyTitle="Nothing here" compact />);
     expect(screen.getByText("Nothing here")).toBeInTheDocument();

package/src/layouts/AsyncBoundary.stories.tsx

@@ -14,7 +14,7 @@ const meta: Meta<typeof AsyncBoundary> = {
     docs: {
       description: {
         component:
-          "Async-state wrapper for data views (W9 / DG-ST-01,02,04 / DG-TBL-06). Priority: error → loading → empty → data. Empty chrome is forbidden when `error` is set; loading uses a layout-matched skeleton; count badges hide on failure.",
+          "Async-state wrapper for data views (W9 / DG-ST-01,02,04 / DG-TBL-06). Priority: error → loading → empty → data. First load uses a layout-matched skeleton; later loads keep previous data (pending bar / inline error). Empty chrome is forbidden when `error` is set; count badges hide on a blocking failure.",
       },
     },
   },
@@ -23,6 +23,7 @@ const meta: Meta<typeof AsyncBoundary> = {
       control: "select",
       options: ["list", "table", "kanban", "dashboard", "generic"] satisfies AsyncBoundaryLayout[],
     },
+    keepPrevious: { control: "boolean" },
   },
 };
 export default meta;
@@ -145,3 +146,34 @@ export const InteractiveCycle: Story = {
     );
   },
 };
+
+/** Settled rows stay painted while a later load is in flight (default keepPrevious). */
+export const KeepPreviousOnRefetch: Story = {
+  render: () => {
+    const [phase, setPhase] = useState<"data" | "loading" | "error">("data");
+    return (
+      <YStack gap="$3" padding="$3" minHeight={320}>
+        <XStack gap="$2" flexWrap="wrap">
+          {(["data", "loading", "error"] as const).map((s) => (
+            <Button key={s} size="$3" onPress={() => setPhase(s)}>
+              {s}
+            </Button>
+          ))}
+        </XStack>
+        <AsyncBoundary
+          loading={phase === "loading"}
+          error={phase === "error" ? "Refresh did not complete." : null}
+          errorTitle="Couldn't refresh"
+          layout="list"
+          onRetry={() => setPhase("loading")}
+        >
+          <YStack gap="$2" padding="$3">
+            <Text>Loaded item 1</Text>
+            <Text>Loaded item 2</Text>
+            <Text>Loaded item 3</Text>
+          </YStack>
+        </AsyncBoundary>
+      </YStack>
+    );
+  },
+};