@multiplatform.one/components 6.1.0 → 6.4.0

package/src/layouts/attachments.tsx

@@ -11,10 +11,12 @@ import {
 import { downloadFile } from "@multiplatform.one/platform";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import React, { useCallback, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
 import {
   Button,
   Dialog,
   Image,
+  isWeb,
   Label,
   ListItem,
   Text,
@@ -22,7 +24,9 @@ import {
   YStack,
   type YStackProps,
 } from "tamagui";
-import { componentColors } from "../componentColors";
+import { componentColors, sectionHeading } from "../componentColors";
+import { Skeleton } from "../Skeleton";
+import { AsyncBoundary, resolveAsyncStatus } from "./AsyncBoundary";
 
 // ---------------------------------------------------------------------------
 // Types  (generic -- no Frappe dependency)
@@ -60,6 +64,17 @@ export interface AttachmentsProps extends Omit<YStackProps, "children"> {
   /** Maximum number of attachments allowed (0 = unlimited) */
   maxAttachments?: number;
 
+  /** Whether attachment data is loading — renders a row-shaped skeleton twin (LC-20 / DG-ST-02) */
+  isLoading?: boolean;
+  /**
+   * Failed load (DG-ST-01 / Axiom 6). Wins over the empty chrome so a failed
+   * File load never masquerades as "no attachments". Pass a string, Error,
+   * custom node, or `true` for the default error UI.
+   */
+  error?: boolean | string | Error | React.ReactNode | null;
+  /** Retry handler for the default error chrome */
+  onRetry?: () => void;
+
   /** Called when an attachment is clicked */
   onAttachmentClick?: (attachment: AttachmentItem) => void;
   /** Called when the user wants to add/upload an attachment */
@@ -103,9 +118,12 @@ export interface AttachmentsProps extends Omit<YStackProps, "children"> {
     upload?: string;
     uploading?: string;
     noAttachments?: string;
+    preview?: string;
     download?: string;
+    remove?: string;
     close?: string;
     fileTooLarge?: string;
+    loadFailed?: string;
   };
 }
 
@@ -140,6 +158,68 @@ function getFileIcon(attachment: AttachmentItem): React.ReactNode {
   return <FileIcon size={20} />;
 }
 
+interface AttachmentThumbnailProps {
+  attachment: AttachmentItem;
+  size: number;
+  fallback: React.ReactNode;
+}
+
+/**
+ * Image thumbnail that falls back to the file-type icon when the image URL
+ * fails to load (auth-gated, relative, or broken URLs would otherwise render
+ * an empty square).
+ */
+function AttachmentThumbnail({ attachment, size, fallback }: AttachmentThumbnailProps) {
+  const [errored, setErrored] = useState(false);
+  if (errored) return <>{fallback}</>;
+  return (
+    <Image
+      // src (string) + objectFit, not source/resizeMode: the RN-only props
+      // leak onto the DOM <img> on web (React unknown-prop warning); tamagui
+      // maps src/objectFit back to source/resizeMode on native.
+      src={attachment.fileUrl}
+      alt={attachment.fileName}
+      width={size}
+      height={size}
+      objectFit="cover"
+      onError={() => setErrored(true)}
+    />
+  );
+}
+
+/**
+ * Skeleton twin of the attachment rows (LC-20 / DG-ST-02): the media square
+ * and the name + size text column mirror the live row anatomy so the layout
+ * doesn't jump when data lands.
+ */
+function AttachmentsSkeleton({
+  thumbSize,
+  loadingLabel,
+}: {
+  thumbSize: number;
+  loadingLabel: string;
+}) {
+  return (
+    <YStack
+      gap="$1"
+      width="100%"
+      data-async-skeleton="attachments"
+      aria-busy
+      aria-label={loadingLabel}
+    >
+      {Array.from({ length: 3 }).map((_, i) => (
+        <XStack key={i} gap="$3" alignItems="center" paddingVertical="$2">
+          <Skeleton variant="rounded" width={thumbSize} height={thumbSize} />
+          <YStack flex={1} gap="$1">
+            <Skeleton width="55%" height={14} />
+            <Skeleton width="25%" height={12} />
+          </YStack>
+        </XStack>
+      ))}
+    </YStack>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -154,6 +234,9 @@ export function Attachments({
   label,
   disabled = false,
   maxAttachments = 0,
+  isLoading = false,
+  error = null,
+  onRetry,
   onAttachmentClick,
   onAdd,
   onRemove,
@@ -170,6 +253,7 @@ export function Attachments({
   labels = {},
   ...stackProps
 }: AttachmentsProps) {
+  const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [previewFile, setPreviewFile] = useState<AttachmentItem | null>(null);
@@ -178,16 +262,25 @@ export function Attachments({
   const {
     upload: uploadLabel = "Upload",
     noAttachments: noAttachmentsLabel = "No attachments",
+    preview: previewLabel = "Preview",
     download: downloadLabel = "Download",
+    remove: removeLabel = "Remove",
     close: closeLabel = "Close",
     fileTooLarge: fileTooLargeLabel = "File too large",
+    loadFailed: loadFailedLabel = t("Couldn't load attachments"),
   } = labels;
 
+  // Error wins (DG-ST-01): a failed load must never look like "no attachments".
+  const hasError = resolveAsyncStatus({ error }) === "error";
+  const showSkeleton = !hasError && isLoading && items.length === 0;
+
   const canAdd = useMemo(() => {
-    if (disabled || !enableAdd || !onAdd) return false;
+    // Hide the upload affordance while the list is failed: the max-attachment
+    // guard can't be honestly evaluated against data that didn't load.
+    if (disabled || !enableAdd || !onAdd || hasError) return false;
     if (maxAttachments > 0 && items.length >= maxAttachments) return false;
     return true;
-  }, [disabled, enableAdd, onAdd, maxAttachments, items.length]);
+  }, [disabled, enableAdd, onAdd, maxAttachments, items.length, hasError]);
 
   const handleFileSelect = useCallback(
     (event: React.ChangeEvent<HTMLInputElement>) => {
@@ -243,6 +336,20 @@ export function Attachments({
     </YStack>
   );
 
+  // Shared by the live rows and their skeleton twin so geometry matches.
+  const sz = knobProps.sizeToken;
+  const thumbSize = compact
+    ? sz === "$3"
+      ? 24
+      : sz === "$5"
+        ? 40
+        : 32
+    : sz === "$3"
+      ? 32
+      : sz === "$5"
+        ? 48
+        : 40;
+
   const renderAttachmentItem = (attachment: AttachmentItem) => {
     const isImage = isImageFile(attachment);
     const actions = {
@@ -251,37 +358,28 @@ export function Attachments({
       onRemove: () => onRemove?.(attachment),
     };
 
-    const sz = knobProps.sizeToken;
-    const thumbSize = compact
-      ? sz === "$3"
-        ? 24
-        : sz === "$5"
-          ? 40
-          : 32
-      : sz === "$3"
-        ? 32
-        : sz === "$5"
-          ? 48
-          : 40;
-
-    const iconElement = isImage ? (
-      <Image
-        source={{ uri: attachment.fileUrl }}
-        width={thumbSize}
-        height={thumbSize}
-        borderRadius={4}
-        resizeMode="cover"
-      />
-    ) : (
+    // Shared media slot: icon and thumbnail live in the same fixed-size box so
+    // the text column starts at the same x in every row.
+    const mediaSlot = (
       <YStack
         width={thumbSize}
         height={thumbSize}
+        flexShrink={0}
+        overflow="hidden"
         {...{ backgroundColor: componentColors.surface.background }}
         {...knobProps.borderRadius}
         alignItems="center"
         justifyContent="center"
       >
-        {getFileIcon(attachment)}
+        {isImage ? (
+          <AttachmentThumbnail
+            attachment={attachment}
+            size={thumbSize}
+            fallback={getFileIcon(attachment)}
+          />
+        ) : (
+          getFileIcon(attachment)
+        )}
       </YStack>
     );
 
@@ -292,6 +390,7 @@ export function Attachments({
             size="$2"
             chromeless
             icon={EyeIcon}
+            aria-label={previewLabel}
             onPress={(e) => {
               e.stopPropagation();
               actions.onPreview();
@@ -303,6 +402,7 @@ export function Attachments({
             size="$2"
             chromeless
             icon={DownloadSimpleIcon}
+            aria-label={downloadLabel}
             onPress={(e) => {
               e.stopPropagation();
               actions.onDownload();
@@ -314,6 +414,7 @@ export function Attachments({
             size="$2"
             chromeless
             icon={TrashIcon}
+            aria-label={removeLabel}
             onPress={(e) => {
               e.stopPropagation();
               actions.onRemove();
@@ -323,18 +424,35 @@ export function Attachments({
       </XStack>
     );
 
+    // Explicit row anatomy (ListItem's icon prop spaces via a cloned style
+    // that function-component media drops, so image rows lost their gap):
+    // media slot + knob-gap + text column + actions, list-row vertical padding.
     const defaultContent = (
       <ListItem
-        title={attachment.fileName}
-        subTitle={attachment.formattedSize || formatFileSize(attachment.fileSize)}
-        icon={iconElement}
-        iconAfter={actionButtons}
         size={compact ? "$3" : knobProps.sizeToken}
+        paddingVertical="$2"
         hoverStyle={{ backgroundColor: componentColors.surface.background }}
         pressStyle={{ backgroundColor: componentColors.interactive.background }}
         onPress={() => onAttachmentClick?.(attachment)}
         cursor="pointer"
-      />
+      >
+        <XStack flex={1} alignItems="center" {...knobProps.gap}>
+          {mediaSlot}
+          <YStack flex={1} minWidth={0}>
+            <Text
+              {...knobProps.body}
+              fontSize={compact ? "$3" : (knobProps.sizeToken as "$3" | "$4" | "$5")}
+              numberOfLines={1}
+            >
+              {attachment.fileName}
+            </Text>
+            <Text fontSize="$2" color={componentColors.text.muted}>
+              {attachment.formattedSize || formatFileSize(attachment.fileSize)}
+            </Text>
+          </YStack>
+          {actionButtons}
+        </XStack>
+      </ListItem>
     );
 
     if (renderAttachment) {
@@ -349,9 +467,10 @@ export function Attachments({
       {(label || canAdd) && (
         <XStack alignItems="center" justifyContent="space-between">
           {label && (
-            <Label fontSize={compact ? "$3" : "$4"} fontWeight="500">
+            <Label {...(compact ? { fontSize: "$3", fontWeight: "500" } : sectionHeading)}>
               {label}
-              {maxAttachments > 0 && (
+              {/* Count hides on error so the badge can't lie (DG-ST-04) */}
+              {maxAttachments > 0 && !hasError && (
                 <Text color={componentColors.text.muted} fontSize="$2">
                   {" "}
                   ({items.length}/{maxAttachments})
@@ -367,14 +486,18 @@ export function Attachments({
         </XStack>
       )}
 
-      <input
-        ref={fileInputRef}
-        type="file"
-        accept={accept}
-        style={{ display: "none" }}
-        onChange={handleFileSelect}
-        disabled={disabled || !canAdd}
-      />
+      {/* DOM file input is web-only; on native the ref stays null and the
+          upload button no-ops (native picking needs a document-picker surface). */}
+      {isWeb && (
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept={accept}
+          style={{ display: "none" }}
+          onChange={handleFileSelect}
+          disabled={disabled || !canAdd}
+        />
+      )}
 
       {uploadError && (
         <XStack
@@ -391,15 +514,27 @@ export function Attachments({
         </XStack>
       )}
 
-      {items.length === 0 ? (
-        emptyState
-      ) : (
-        <YStack {...knobProps.gap}>
+      {/* Exactly one of: error → loading skeleton → empty → rows (W9 / DG-ST-01) */}
+      <AsyncBoundary
+        compact
+        error={error}
+        onRetry={onRetry}
+        errorTitle={loadFailedLabel}
+        loading={
+          showSkeleton ? (
+            <AttachmentsSkeleton thumbSize={thumbSize} loadingLabel={t("Loading")} />
+          ) : (
+            false
+          )
+        }
+        empty={!hasError && items.length === 0 ? emptyState : false}
+      >
+        <YStack gap="$1">
           {items.map((attachment) => (
             <React.Fragment key={attachment.id}>{renderAttachmentItem(attachment)}</React.Fragment>
           ))}
         </YStack>
-      )}
+      </AsyncBoundary>
 
       <Dialog open={!!previewFile} onOpenChange={(open) => !open && setPreviewFile(null)}>
         <Dialog.Portal>
@@ -417,10 +552,13 @@ export function Attachments({
             {previewFile && (
               <YStack {...knobProps.panelPadding} alignItems="center">
                 <Image
-                  source={{ uri: previewFile.fileUrl }}
+                  // src/objectFit, not source/resizeMode (RN-only props leak
+                  // onto the DOM <img> on web; tamagui maps these on native)
+                  src={previewFile.fileUrl}
+                  alt={previewFile.fileName}
                   width="100%"
                   height={400}
-                  resizeMode="contain"
+                  objectFit="contain"
                 />
                 <XStack gap="$2" marginTop="$4">
                   <Button icon={DownloadSimpleIcon} onPress={() => handleDownload(previewFile)}>

package/src/layouts/breadcrumbs.tsx

@@ -6,11 +6,19 @@
  * non-clickable bold text (current page).
  */
 
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  MIN_PRESS_TARGET,
+  pressTargetHitSlop,
+  useAccentOnSurface,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import React from "react";
-import { Text, XStack } from "tamagui";
+import { Anchor, Text, XStack } from "tamagui";
 import { componentColors } from "../componentColors";
 
+/** Approx medium body line box before press-target padding (DG-LAY-04). */
+const CRUMB_LINE_PX = 24;
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -31,21 +39,32 @@ export interface BreadcrumbsProps {
 
 export function Breadcrumbs({ items, onNavigate }: BreadcrumbsProps) {
   const { knobProps } = useResolvedKnobs();
+  // UX-P04 / Axiom 12: crumb links are accent-hued text on the PAGE, so they
+  // need the page-readable accent — `$accentColor` (the on-fill foreground)
+  // measured 1.94:1 as a dark-scheme link on the page.
+  const linkColor = useAccentOnSurface();
   if (items.length === 0) return null;
 
   const sz = knobProps.sizeToken;
   const textSize = sz === "$3" ? ("$2" as const) : sz === "$5" ? ("$4" as const) : ("$3" as const);
   const separatorSize =
     sz === "$3" ? ("$1" as const) : sz === "$5" ? ("$3" as const) : ("$2" as const);
+  // Tight trail: crumbs hug the "/" separators so the path reads as one unit.
+  // The space knob still scales the gap, but from a tight base — not the
+  // panel-level knobProps.gap (which is sized for stacked layout sections).
+  const spaceGap = knobProps.gap.gap;
+  const trailGap =
+    spaceGap === "$2" ? ("$1" as const) : spaceGap === "$5" ? ("$2" as const) : ("$1.5" as const);
+  // Vertical pad only (theme-propagation SP-FIXED / DG-LAY-04): grow the
+  // clickable box to ≥44 without horizontal width that would re-spread the trail.
+  const crumbPadY = Math.max(0, Math.ceil((MIN_PRESS_TARGET - CRUMB_LINE_PX) / 2));
 
   return (
-    <XStack
-      {...knobProps.gap}
-      {...knobProps.borderRadius}
-      {...knobProps.panelPadding}
-      alignItems="center"
-      flexWrap="wrap"
-    >
+    // Wayfinding is chromeless flush text (DF-20 / Axiom 14 LAYER ROLE):
+    // no border/radius/panel padding — a bordered box would claim the
+    // surface tier of a card or input, which a trail has not earned. The
+    // page column owns the alignment line; the trail sits on it.
+    <XStack gap={trailGap} alignItems="center" flexWrap="wrap">
       {items.map((item, i) => (
         <React.Fragment key={`${item.label}-${i}`}>
           {i > 0 && (
@@ -54,15 +73,47 @@ export function Breadcrumbs({ items, onNavigate }: BreadcrumbsProps) {
             </Text>
           )}
           {item.href && i < items.length - 1 ? (
-            <Text
-              color="$accentColor"
+            <Anchor
+              color={linkColor}
               cursor="pointer"
               fontSize={textSize}
+              // Crumbs are R-SCALE (spec Breadcrumbs): the interactive
+              // crumb surface (focus ring / hover box) rounds with the
+              // radius knob. Chromeless trail keeps no border, so only the
+              // scale radius applies — not the bordered fragment.
+              borderRadius={knobProps.borderRadius.borderRadius}
+              paddingVertical={crumbPadY}
+              marginVertical={-crumbPadY}
+              // Short labels (e.g. "Home") need a width floor too; long crumbs
+              // already exceed 44. No extra horizontal padding — that would
+              // re-spread the trail (theme-propagation breadcrumbs invariant).
+              minWidth={MIN_PRESS_TARGET}
+              minHeight={MIN_PRESS_TARGET}
+              justifyContent="center"
+              hitSlop={pressTargetHitSlop(CRUMB_LINE_PX)}
+              href={item.href}
+              textDecorationLine="none"
               hoverStyle={{ textDecorationLine: "underline" }}
-              onPress={() => item.href && onNavigate?.(item.href)}
+              focusVisibleStyle={{
+                outlineColor: "$outlineColor",
+                outlineWidth: 2,
+                outlineStyle: "solid",
+              }}
+              onPress={(e) => {
+                e.preventDefault();
+                if (item.href) onNavigate?.(item.href);
+              }}
+              onKeyDown={
+                ((e: React.KeyboardEvent) => {
+                  if (e.key === " ") {
+                    e.preventDefault();
+                    if (item.href) onNavigate?.(item.href);
+                  }
+                }) as unknown as () => void
+              }
             >
               {item.label}
-            </Text>
+            </Anchor>
           ) : (
             <Text
               color={componentColors.text.muted}

package/src/layouts/index.tsx

@@ -9,3 +9,18 @@ export * from "./attachments";
 export * from "./tags";
 export * from "./timeline";
 export * from "./page";
+export * from "./pageHeadingScope";
+export * from "./PageTemplates";
+export * from "./PaneScaffold";
+export {
+  AsyncBoundary,
+  AsyncSkeleton,
+  resolveAsyncStatus,
+  useAsyncBoundary,
+  useAsyncCount,
+  __resetAsyncDevWarnSeen,
+  type AsyncBoundaryProps,
+  type AsyncBoundaryLayout,
+  type AsyncBoundaryContextValue,
+  type AsyncStatus,
+} from "./AsyncBoundary";