@multiplatform.one/components 6.7.0 → 7.0.0

package/src/layouts/AsyncBoundary.tsx

@@ -5,13 +5,20 @@
  * DG-ST-02: default loading uses a layout-matched skeleton (no layout jump).
  * DG-ST-04: counts/badges in the failure chrome are hidden (`hideBadges`).
  * DG-TBL-06: data views treat these as first-class states.
+ *
+ * Subsequent loads (React Query isFetching / SWR revalidate) keep the last
+ * settled data painted — skeleton and full-page error chrome are first-load
+ * only. A slim pending bar or inline error Alert rides on top of the rows.
  */
 
-import { Button } from "@multiplatform.one/forms";
+import { Button, Spinner } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { WarningCircleIcon } from "@phosphor-icons/react";
-import { createContext, useContext, useEffect, type ReactNode } from "react";
-import { useTranslation } from "react-i18next";
+import { createContext, useContext, useEffect, useRef, type ReactNode } from "react";
+import { useTranslation } from "../shared/i18n";
 import { Text, XStack, YStack, type YStackProps } from "tamagui";
+import { Alert } from "../Alert";
+import { componentColors } from "../componentColors";
 import { Skeleton } from "../Skeleton";
 import { EmptyState } from "./page";
 
@@ -29,6 +36,10 @@ export type AsyncBoundaryContextValue = {
   /** True when status is `error` — counts/badges must not render (DG-ST-04). */
   hideBadges: boolean;
   error: unknown;
+  /** Refetch in flight over previously settled content. */
+  pending: boolean;
+  /** Showing previously settled data despite a later error. */
+  stale: boolean;
 };
 
 const AsyncBoundaryContext = createContext<AsyncBoundaryContextValue | null>(null);
@@ -85,8 +96,15 @@ export interface AsyncBoundaryProps extends Omit<YStackProps, "children"> {
   /**
    * Optional chrome (filters, count badges, toolbars) rendered only for
    * `data` / `empty` / `loading`. Hidden on `error` so badges can't lie (DG-ST-04).
+   * Kept visible when a refetch error leaves previous data on screen.
    */
   chrome?: ReactNode;
+  /**
+   * Keep the last settled data (or empty chrome) painted while a later
+   * `loading`/`error` flag is set. Default true — first load with nothing
+   * settled still uses the layout skeleton / full error EmptyState.
+   */
+  keepPrevious?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -284,6 +302,89 @@ export function AsyncSkeleton({
   }
 }
 
+// ---------------------------------------------------------------------------
+// Pending bar (refetch over settled content)
+// ---------------------------------------------------------------------------
+
+function AsyncPendingBar() {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  return (
+    <XStack
+      data-async-pending="true"
+      role="status"
+      aria-live="polite"
+      aria-label={t("Updating...")}
+      alignItems="center"
+      {...knobProps.gap}
+    >
+      <Spinner size="small" aria-hidden />
+      <Text {...knobProps.label} color={componentColors.text.muted}>
+        {t("Updating...")}
+      </Text>
+    </XStack>
+  );
+}
+
+function defaultEmptyBody({
+  empty,
+  compact,
+  emptyTitle,
+  emptyDescription,
+}: {
+  empty: AsyncBoundaryProps["empty"];
+  compact: boolean;
+  emptyTitle: string;
+  emptyDescription?: string;
+}): ReactNode {
+  if (empty !== true && isReactNodeSlot(empty)) return empty;
+  return (
+    <EmptyState
+      compact={compact}
+      intent="neutral"
+      data-async-state="empty"
+      title={emptyTitle}
+      description={emptyDescription}
+    />
+  );
+}
+
+function defaultErrorBody({
+  error,
+  compact,
+  errorTitle,
+  errorDescription,
+  onRetry,
+  retryLabel,
+}: {
+  error: AsyncBoundaryProps["error"];
+  compact: boolean;
+  errorTitle: string;
+  errorDescription?: string;
+  onRetry?: () => void;
+  retryLabel: string;
+}): ReactNode {
+  if (isReactNodeSlot(error)) return error;
+  const copy = errorCopy(error, errorTitle, errorDescription);
+  return (
+    <EmptyState
+      compact={compact}
+      intent="error"
+      data-async-state="error"
+      title={copy.title}
+      description={copy.description}
+      icon={<WarningCircleIcon size={compact ? 24 : 32} />}
+      action={
+        onRetry ? (
+          <Button size={compact ? "$3" : "$4"} onPress={onRetry}>
+            {retryLabel}
+          </Button>
+        ) : undefined
+      }
+    />
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -291,9 +392,12 @@ export function AsyncSkeleton({
 /**
  * Renders exactly one of: error → loading → empty → data.
  *
+ * After a successful paint, a later `loading` or `error` keeps that paint
+ * (pending bar / inline Alert) unless `keepPrevious={false}`.
+ *
  * ```tsx
  * <AsyncBoundary
- *   loading={isLoading}
+ *   loading={isFetching}
  *   empty={items.length === 0}
  *   error={queryError}
  *   layout="list"
@@ -318,10 +422,23 @@ export function AsyncBoundary({
   errorDescription,
   compact = false,
   chrome,
+  keepPrevious = true,
   ...stackProps
 }: AsyncBoundaryProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact });
   const status = resolveAsyncStatus({ loading, empty, error });
-  const hideBadges = status === "error";
+  const content = data ?? children;
+  const retryLabel = t("Retry");
+
+  const emptyBody = defaultEmptyBody({ empty, compact, emptyTitle, emptyDescription });
+  const settledRef = useRef<{ kind: "data" | "empty"; body: ReactNode } | null>(null);
+  if (status === "data") {
+    settledRef.current = { kind: "data", body: content };
+  } else if (status === "empty") {
+    settledRef.current = { kind: "empty", body: emptyBody };
+  }
+  const settled = keepPrevious ? settledRef.current : null;
 
   useEffect(() => {
     if (status === "error" && isActiveFlag(empty)) {
@@ -332,67 +449,87 @@ export function AsyncBoundary({
     }
   }, [status, empty]);
 
-  const ctx: AsyncBoundaryContextValue = {
-    status,
-    hideBadges,
-    error: error ?? null,
-  };
-
+  let displayStatus: AsyncStatus = status;
+  let pending = false;
+  let stale = false;
   let body: ReactNode = null;
+  let showChrome = status !== "error";
 
   if (status === "error") {
     if (isReactNodeSlot(error)) {
       body = error;
-    } else {
+    } else if (settled?.kind === "data") {
+      stale = true;
+      displayStatus = "data";
+      showChrome = true;
       const copy = errorCopy(error, errorTitle, errorDescription);
       body = (
-        <EmptyState
-          compact={compact}
-          intent="error"
-          data-async-state="error"
-          title={copy.title}
-          description={copy.description}
-          icon={<WarningCircleIcon size={compact ? 24 : 32} />}
-          action={
-            onRetry ? (
-              <Button size={compact ? "$3" : "$4"} onPress={onRetry}>
-                Retry
-              </Button>
-            ) : undefined
-          }
-        />
+        <YStack width="100%" {...knobProps.gap}>
+          <Alert
+            compact={compact}
+            intent="error"
+            title={copy.title}
+            actionLabel={onRetry ? retryLabel : undefined}
+            onAction={onRetry}
+          >
+            {copy.description}
+          </Alert>
+          {content ?? settled.body}
+        </YStack>
       );
+    } else {
+      body = defaultErrorBody({
+        error,
+        compact,
+        errorTitle,
+        errorDescription,
+        onRetry,
+        retryLabel,
+      });
     }
   } else if (status === "loading") {
-    body =
-      loading !== true && isReactNodeSlot(loading) ? loading : <AsyncSkeleton layout={layout} />;
-  } else if (status === "empty") {
-    body =
-      empty !== true && isReactNodeSlot(empty) ? (
-        empty
-      ) : (
-        <EmptyState
-          compact={compact}
-          intent="neutral"
-          data-async-state="empty"
-          title={emptyTitle}
-          description={emptyDescription}
-        />
+    if (settled) {
+      pending = true;
+      displayStatus = settled.kind;
+      showChrome = true;
+      const kept = settled.kind === "data" ? (content ?? settled.body) : settled.body;
+      body = (
+        <YStack width="100%" {...knobProps.gap}>
+          <AsyncPendingBar />
+          {kept}
+        </YStack>
       );
+    } else {
+      body =
+        loading !== true && isReactNodeSlot(loading) ? loading : <AsyncSkeleton layout={layout} />;
+    }
+  } else if (status === "empty") {
+    body = emptyBody;
   } else {
-    body = data ?? children;
+    body = content;
   }
 
+  const hideBadges = displayStatus === "error";
+  const ctx: AsyncBoundaryContextValue = {
+    status: displayStatus,
+    hideBadges,
+    error: error ?? null,
+    pending,
+    stale,
+  };
+
   return (
     <AsyncBoundaryContext.Provider value={ctx}>
       <YStack
-        data-async-status={status}
+        data-async-status={displayStatus}
+        {...(pending ? { "data-async-pending": "true" } : {})}
+        {...(stale ? { "data-async-stale": "true" } : {})}
         width="100%"
-        {...(status === "loading" ? { "aria-busy": true } : {})}
+        {...(pending || status === "loading" ? { "aria-busy": true } : {})}
         {...stackProps}
       >
-        {/* Chrome (toolbars / badges) suppressed on error so counts can't lie */}
-        {status !== "error" ? chrome : null}
+        {/* Chrome (toolbars / badges) suppressed on blocking error so counts can't lie */}
+        {showChrome ? chrome : null}
         {body}
       </YStack>
     </AsyncBoundaryContext.Provider>

package/src/layouts/Attachments.stories.tsx

@@ -51,11 +51,14 @@ const sampleItems: AttachmentItem[] = [
 ];
 
 export const Default = () => (
-  <Attachments
-    items={sampleItems}
-    onAdd={(file) => console.log("Add:", file.name)}
-    onRemove={(item) => console.log("Remove:", item.id)}
-  />
+  <YStack width="100%" maxWidth={360}>
+    <Attachments
+      items={sampleItems}
+      label="Attachments"
+      onAdd={(file) => console.log("Add:", file.name)}
+      onRemove={(item) => console.log("Remove:", item.id)}
+    />
+  </YStack>
 );
 Default.storyName = "Main";
 Default.parameters = {
@@ -67,7 +70,9 @@ Default.parameters = {
 };
 
 export const ReadOnly = () => (
-  <Attachments items={sampleItems} enableAdd={false} enableRemove={false} />
+  <YStack width="100%" maxWidth={360}>
+    <Attachments items={sampleItems} label="Attachments" enableAdd={false} enableRemove={false} />
+  </YStack>
 );
 ReadOnly.parameters = {
   docs: {
@@ -78,12 +83,15 @@ ReadOnly.parameters = {
 };
 
 export const CompactMode = () => (
-  <Attachments
-    items={sampleItems}
-    compact
-    onAdd={(file) => console.log("Add:", file.name)}
-    onRemove={(item) => console.log("Remove:", item.id)}
-  />
+  <YStack width="100%" maxWidth={360}>
+    <Attachments
+      items={sampleItems}
+      label="Attachments"
+      compact
+      onAdd={(file) => console.log("Add:", file.name)}
+      onRemove={(item) => console.log("Remove:", item.id)}
+    />
+  </YStack>
 );
 CompactMode.parameters = {
   docs: {
@@ -94,7 +102,13 @@ CompactMode.parameters = {
 };
 
 export const Empty = () => (
-  <Attachments items={[]} onAdd={(file) => console.log("Add:", file.name)} />
+  <YStack width="100%" maxWidth={360}>
+    <Attachments
+      items={[]}
+      label="Attachments"
+      onAdd={(file) => console.log("Add:", file.name)}
+    />
+  </YStack>
 );
 Empty.parameters = {
   docs: {
@@ -133,7 +147,7 @@ Error.parameters = {
 };
 
 export const AllStates = () => (
-  <YStack gap="$6">
+  <YStack gap="$6" maxWidth={360}>
     <YStack gap="$2">
       <Text fontWeight="600">With Files</Text>
       <Attachments items={sampleItems} />

package/src/layouts/Breadcrumbs.stories.tsx

@@ -7,8 +7,18 @@ export default {
   parameters: { status: { type: "stable" } },
 };
 
+const deepItems = [
+  { label: "Home", href: "/" },
+  { label: "Workspace", href: "/ws" },
+  { label: "Projects", href: "/projects" },
+  { label: "multiplatform.one", href: "/projects/mp1" },
+  { label: "Apps", href: "/projects/mp1/apps" },
+  { label: "One", href: "/projects/mp1/apps/one" },
+  { label: "Settings" },
+];
+
 export const Default = () => (
-  <YStack gap="$4">
+  <YStack gap="$4" padding="$4">
     <Breadcrumbs
       items={[
         { label: "Home", href: "/" },
@@ -25,3 +35,14 @@ export const Default = () => (
   </YStack>
 );
 Default.storyName = "Main";
+
+export const Overflow = () => (
+  <YStack gap="$4" maxWidth={480} padding="$4">
+    <Breadcrumbs
+      items={deepItems}
+      maxVisible={4}
+      onNavigate={(href) => console.log("Navigate:", href)}
+    />
+  </YStack>
+);
+Overflow.storyName = "Overflow";

package/src/layouts/EmptyState.stories.tsx

@@ -2,9 +2,18 @@ import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 // Catalog Button (G-15 story honesty / LC-18): the raw tamagui action held a
 // 9px radius at borderRadius:none and ignored the size knob (UX-P06).
 import { Button } from "@multiplatform.one/forms";
+import { MagnifyingGlassIcon, TrayIcon, WarningCircleIcon } from "@phosphor-icons/react";
+import type { ReactNode } from "react";
 import { YStack } from "tamagui";
-import { CheckRegular } from "../icons/CheckRegular";
-import { EmptyState } from "./page";
+import { EmptyState } from "./EmptyState";
+
+function PageCanvas({ children }: { children: ReactNode }) {
+  return (
+    <YStack minHeight={520} width="100%" backgroundColor="$background">
+      {children}
+    </YStack>
+  );
+}
 
 const meta: Meta<typeof EmptyState> = {
   title: "Components/EmptyState",
@@ -14,17 +23,19 @@ const meta: Meta<typeof EmptyState> = {
     docs: {
       description: {
         component:
-          "Centered empty/error placeholder: circular icon well, H2 title, muted description, action slot. Prefer AsyncBoundary for async data views so empty chrome never renders on a failed load (DG-ST-01).",
+          "Centered empty/error placeholder: circular icon well, heading, muted description, action row. Prefer AsyncBoundary for async data views so empty chrome never renders on a failed load (DG-ST-01). First-use and filtered-empty are different states (Polaris); error is sober, one recovery action, no secondary (Primer).",
       },
     },
   },
   argTypes: {
     title: { control: "text" },
     description: { control: "text" },
+    intent: { control: "select", options: ["neutral", "error"] },
+    compact: { control: "boolean" },
   },
   args: {
-    title: "No records found",
-    description: "There is nothing to show here yet. Create your first record to get started.",
+    title: "Create your first record",
+    description: "Records you add will show up here. Create one to get started.",
   },
 };
 export default meta;
@@ -34,35 +45,43 @@ type Story = StoryObj<typeof EmptyState>;
 export const Default: Story = {
   name: "Main",
   render: (args) => (
-    <EmptyState
-      {...args}
-      icon={<CheckRegular size={32} />}
-      action={<Button>Create record</Button>}
-    />
+    <PageCanvas>
+      <EmptyState {...args} icon={<TrayIcon size={40} />} action={<Button>Create record</Button>} />
+    </PageCanvas>
   ),
 };
 
 export const TitleOnly: Story = {
   args: { description: undefined },
-  render: (args) => <EmptyState {...args} />,
+  render: (args) => (
+    <PageCanvas>
+      <EmptyState {...args} />
+    </PageCanvas>
+  ),
 };
 
 export const NoIcon: Story = {
-  render: (args) => <EmptyState {...args} action={<Button>Retry</Button>} />,
+  render: (args) => (
+    <PageCanvas>
+      <EmptyState {...args} action={<Button>Retry</Button>} />
+    </PageCanvas>
+  ),
 };
 
 export const MultipleActions: Story = {
   render: (args) => (
-    <EmptyState
-      {...args}
-      icon={<CheckRegular size={32} />}
-      action={
-        <>
-          <Button>Primary action</Button>
-          <Button variant="outlined">Secondary action</Button>
-        </>
-      }
-    />
+    <PageCanvas>
+      <EmptyState
+        {...args}
+        icon={<TrayIcon size={40} />}
+        action={
+          <>
+            <Button>Create record</Button>
+            <Button variant="outlined">Learn more</Button>
+          </>
+        }
+      />
+    </PageCanvas>
   ),
 };
 
@@ -70,21 +89,21 @@ export const LongCopyNarrow: Story = {
   args: {
     title: "Zusammengehörigkeitsgefühl-Konfigurationsproblem",
     description:
-      "A very long translated description that runs on and on to verify the copy stays centred, wraps within its 520px max width, and never overflows the narrow container horizontally.",
+      "A very long translated description that runs on and on to verify the copy stays centred, wraps within its reading width, and never overflows the narrow container horizontally.",
   },
   render: (args) => (
     <YStack width={300} borderWidth={1} borderColor="$color6" borderStyle="dashed">
-      <EmptyState {...args} icon={<CheckRegular size={32} />} action={<Button>Act</Button>} />
+      <EmptyState {...args} icon={<TrayIcon size={32} />} action={<Button>Act</Button>} />
     </YStack>
   ),
 };
 
 export const Compact: Story = {
-  args: { title: "No results found", description: undefined },
+  args: { title: "No matching records", description: undefined },
   parameters: {
     docs: {
       description: {
-        story: "Compact variant for inline use inside tables and kanban columns.",
+        story: "Compact variant for inline use inside tables and kanban columns (Primer narrow).",
       },
     },
   },
@@ -94,3 +113,52 @@ export const Compact: Story = {
     </YStack>
   ),
 };
+
+export const NoResults: Story = {
+  args: {
+    title: "No matching records",
+    description: "Try a different search, or clear filters to see everything.",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Filtered-empty is not first-use (Polaris resource list). Offer a way to clear filters, never 'create your first'.",
+      },
+    },
+  },
+  render: (args) => (
+    <PageCanvas>
+      <EmptyState
+        {...args}
+        icon={<MagnifyingGlassIcon size={40} />}
+        action={<Button variant="outlined">Clear filters</Button>}
+      />
+    </PageCanvas>
+  ),
+};
+
+export const Error: Story = {
+  args: {
+    title: "Couldn't load records",
+    description: "Check your connection, then try again.",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Sober failure chrome (Primer Blankslate error). Alert icon, one recovery action, no secondary.",
+      },
+    },
+  },
+  render: (args) => (
+    <PageCanvas>
+      <EmptyState
+        {...args}
+        intent="error"
+        icon={<WarningCircleIcon size={40} weight="fill" />}
+        action={<Button>Retry</Button>}
+      />
+    </PageCanvas>
+  ),
+};