@agent-native/core-corpus 0.216.0 → 0.218.0

package/corpus/templates/design/app/components/templates/DesignTemplateGrid.tsx

@@ -0,0 +1,163 @@
+import { Spinner } from "@agent-native/toolkit/design-system";
+import { useId, type ReactNode } from "react";
+
+import { Skeleton } from "@/components/ui/skeleton";
+
+import type { DesignLibraryTemplate } from "./DesignTemplateLibrary";
+import { TemplatePreview } from "./TemplatePreview";
+
+const GRID_CLASS =
+  "grid gap-x-4 gap-y-3 [grid-template-columns:repeat(auto-fill,minmax(min(100%,15rem),1fr))]";
+
+export const TEMPLATE_GRID_SKELETON_COUNT = 8;
+
+export function DesignTemplateGrid({
+  templates,
+  loading,
+  pendingId,
+  pendingLabel,
+  disabled,
+  selectedId,
+  loadingLabel,
+  emptyLabel,
+  onSelect,
+  renderActions,
+}: {
+  templates: readonly DesignLibraryTemplate[];
+  loading: boolean;
+  pendingId: string | null;
+  pendingLabel: string;
+  disabled: boolean;
+  selectedId?: string;
+  loadingLabel: string;
+  emptyLabel: string;
+  onSelect: (template: DesignLibraryTemplate, element: HTMLElement) => void;
+  renderActions?: (template: DesignLibraryTemplate) => ReactNode;
+}) {
+  if (templates.length === 0) {
+    return loading ? (
+      <div
+        className={GRID_CLASS}
+        role="status"
+        aria-label={loadingLabel}
+        aria-busy="true"
+      >
+        {Array.from({ length: TEMPLATE_GRID_SKELETON_COUNT }, (_, index) => (
+          <div
+            key={index}
+            className="overflow-hidden rounded-[10px] border border-border"
+          >
+            <Skeleton className="aspect-[2/1] w-full rounded-none" />
+            <div className="grid gap-1 px-3.5 py-[13px]">
+              <Skeleton className="h-4 w-3/5" />
+              <Skeleton className="h-3.5 w-4/5" />
+            </div>
+          </div>
+        ))}
+      </div>
+    ) : (
+      <div
+        role="status"
+        className="py-8 text-center text-sm text-muted-foreground"
+      >
+        {emptyLabel}
+      </div>
+    );
+  }
+  return (
+    <ul className={GRID_CLASS} aria-busy={loading || undefined}>
+      {templates.map((template) => (
+        <DesignTemplateCard
+          key={template.id}
+          template={template}
+          pending={template.id === pendingId}
+          pendingLabel={pendingLabel}
+          disabled={disabled}
+          selected={template.id === selectedId}
+          onSelect={onSelect}
+          actions={renderActions?.(template)}
+        />
+      ))}
+    </ul>
+  );
+}
+
+function DesignTemplateCard({
+  template,
+  pending,
+  pendingLabel,
+  disabled,
+  selected,
+  onSelect,
+  actions,
+}: {
+  template: DesignLibraryTemplate;
+  pending: boolean;
+  pendingLabel: string;
+  disabled: boolean;
+  selected: boolean;
+  onSelect: (template: DesignLibraryTemplate, element: HTMLElement) => void;
+  actions?: ReactNode;
+}) {
+  const titleId = useId();
+  const descriptionId = useId();
+  return (
+    <li
+      className="group/card relative min-w-0"
+      aria-busy={pending || undefined}
+    >
+      <button
+        type="button"
+        aria-labelledby={titleId}
+        aria-describedby={template.description ? descriptionId : undefined}
+        aria-pressed={selected}
+        aria-disabled={disabled || undefined}
+        onClick={(event) => {
+          if (!disabled) onSelect(template, event.currentTarget);
+        }}
+        className="block w-full overflow-hidden rounded-[10px] border border-border bg-background text-left transition-colors outline-none hover:border-foreground/30 focus-visible:ring-2 focus-visible:ring-ring aria-pressed:border-foreground/40 aria-disabled:cursor-default"
+      >
+        <span className="relative block aspect-[2/1] overflow-hidden bg-muted">
+          <TemplatePreview
+            html={template.previewHtml}
+            title={template.title}
+            width={template.width}
+            height={template.height}
+            fit="cover"
+            className="absolute inset-0 h-full w-full"
+          />
+        </span>
+        <span className="block px-3.5 py-[13px]">
+          <span
+            id={titleId}
+            className="block truncate text-[13px] leading-4 font-semibold text-foreground"
+          >
+            {template.title}
+          </span>
+          {template.description ? (
+            <span
+              id={descriptionId}
+              className="mt-1 block truncate text-[11px] leading-3.5 text-muted-foreground"
+            >
+              {template.description}
+            </span>
+          ) : null}
+        </span>
+      </button>
+      {actions ? (
+        <div className="absolute top-2 right-2 z-10 [@media(hover:hover)]:opacity-0 [@media(hover:hover)]:group-focus-within/card:opacity-100 [@media(hover:hover)]:group-hover/card:opacity-100">
+          {actions}
+        </div>
+      ) : null}
+      {pending ? (
+        <div
+          role="status"
+          className="absolute inset-0 z-20 flex items-center justify-center gap-2 rounded-[10px] bg-background/80 p-4 text-sm font-medium text-foreground backdrop-blur-sm"
+        >
+          <Spinner className="size-4" />
+          {pendingLabel}
+        </div>
+      ) : null}
+    </li>
+  );
+}

package/corpus/templates/design/app/components/templates/DesignTemplateLibrary.tsx

@@ -4,16 +4,13 @@ import {
   useActionQuery,
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
-import {
-  TemplateLibraryGrid,
-  TemplatePreviewDialog,
-} from "@agent-native/toolkit/app-shell";
+import { TemplatePreviewDialog } from "@agent-native/toolkit/app-shell";
 import { ShareButton } from "@agent-native/toolkit/app/sharing";
 import { designTemplateRetryKey } from "@shared/design-template-retry";
 import { IconDots } from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
 import { nanoid } from "nanoid";
-import { useRef, useState, type RefObject } from "react";
+import { useEffect, useMemo, useRef, useState, type RefObject } from "react";
 import { useNavigate, useSearchParams } from "react-router";
 import { toast } from "sonner";
 
@@ -36,6 +33,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 
+import { DesignTemplateGrid } from "./DesignTemplateGrid";
 import { TemplatePreview } from "./TemplatePreview";
 
 export interface DesignLibraryTemplate {
@@ -78,9 +76,11 @@ function previewFilenameForHref(
 export function DesignTemplateLibrary({
   templates,
   loading = false,
+  previewParam = "templateId",
 }: {
   templates: readonly DesignLibraryTemplate[];
   loading?: boolean;
+  previewParam?: string;
 }) {
   const t = useT();
   const navigate = useNavigate();
@@ -92,7 +92,7 @@ export function DesignTemplateLibrary({
   const pending = useRef(false);
   const retryIds = useRef(new Map<string, { key: string; id: string }>());
   const preview = templates.find(
-    (template) => template.id === params.get("templateId"),
+    (template) => template.id === params.get(previewParam),
   );
   const [deleting, setDeleting] = useState<DesignLibraryTemplate | null>(null);
   const restoreFocusRef = useRef<HTMLElement | null>(null);
@@ -100,8 +100,8 @@ export function DesignTemplateLibrary({
     setParams(
       (current) => {
         const next = new URLSearchParams(current);
-        if (id) next.set("templateId", id);
-        else next.delete("templateId");
+        if (id) next.set(previewParam, id);
+        else next.delete(previewParam);
         return next;
       },
       { replace: true },
@@ -158,41 +158,28 @@ export function DesignTemplateLibrary({
   };
   return (
     <>
-      <TemplateLibraryGrid
-        items={templates}
+      <DesignTemplateGrid
+        templates={templates}
         loading={loading}
         pendingId={pendingId}
         pendingLabel={t("templatesPage.opening")}
         disabled={Boolean(pendingId)}
         selectedId={preview?.id}
-        onSelect={(template) => void copy(template)}
-        labels={{
-          loading: t("templatesPage.loading"),
-          empty: t("promptDialog.noTemplatesFound"),
-          retry: t("homeContext.retry"),
+        loadingLabel={t("templatesPage.loading")}
+        emptyLabel={t("promptDialog.noTemplatesFound")}
+        onSelect={(template, element) => {
+          restoreFocusRef.current = element;
+          selectPreview(template.id);
         }}
-        renderPreview={(template) => (
-          <div className="design-library-card-preview">
-            <TemplatePreview
-              html={template.previewHtml}
-              title={template.title}
-              width={template.width}
-              height={template.height}
-              className="h-full w-full"
+        renderActions={(template) =>
+          !template.isBuiltIn && template.isOwner ? (
+            <TemplateMenu
+              template={template}
+              disabled={pendingId !== null}
+              onDelete={() => setDeleting(template)}
             />
-          </div>
-        )}
-        renderActions={(template) => (
-          <TemplateMenu
-            template={template}
-            disabled={pendingId !== null}
-            onDelete={() => setDeleting(template)}
-            onPreview={(trigger) => {
-              restoreFocusRef.current = trigger;
-              selectPreview(template.id);
-            }}
-          />
-        )}
+          ) : null
+        }
       />
       {preview ? (
         <DesignTemplatePreviewDialog
@@ -235,24 +222,19 @@ export function DesignTemplateLibrary({
 function TemplateMenu({
   template,
   disabled,
-  onPreview,
   onDelete,
 }: {
   template: DesignLibraryTemplate;
   disabled: boolean;
-  onPreview: (trigger: HTMLElement | null) => void;
   onDelete: () => void;
 }) {
   const t = useT();
-  const trigger = useRef<HTMLButtonElement>(null);
-  const openingPreview = useRef(false);
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild disabled={disabled}>
         <Button
-          ref={trigger}
-          variant="ghost"
-          size="icon"
+          variant="secondary"
+          size="icon-sm"
           disabled={disabled}
           aria-label={t("templatesPage.templateActions", {
             title: template.title,
@@ -261,39 +243,18 @@ function TemplateMenu({
           <IconDots />
         </Button>
       </DropdownMenuTrigger>
-      <DropdownMenuContent
-        align="end"
-        onCloseAutoFocus={(event) => {
-          if (openingPreview.current) {
-            event.preventDefault();
-            openingPreview.current = false;
-          }
-        }}
-      >
+      <DropdownMenuContent align="end">
         <DropdownMenuGroup>
-          <DropdownMenuItem
-            disabled={disabled}
-            onSelect={() => {
-              openingPreview.current = true;
-              onPreview(trigger.current);
-            }}
-          >
-            {t("creativeContext.preview")}
+          <ShareButton
+            resourceType="design-template"
+            resourceId={template.id}
+            allowedRoles={["viewer", "editor", "admin"]}
+            resourceTitle={template.title}
+            trigger="label"
+          />
+          <DropdownMenuItem disabled={disabled} onSelect={onDelete}>
+            {t("home.delete")}
           </DropdownMenuItem>
-          {!template.isBuiltIn && template.isOwner ? (
-            <>
-              <ShareButton
-                resourceType="design-template"
-                resourceId={template.id}
-                allowedRoles={["viewer", "editor", "admin"]}
-                resourceTitle={template.title}
-                trigger="label"
-              />
-              <DropdownMenuItem disabled={disabled} onSelect={onDelete}>
-                {t("home.delete")}
-              </DropdownMenuItem>
-            </>
-          ) : null}
         </DropdownMenuGroup>
       </DropdownMenuContent>
     </DropdownMenu>
@@ -321,12 +282,38 @@ function DesignTemplatePreviewDialog({
     { templateId: template.id },
   );
   const [selectedId, setSelectedId] = useState<string | null>(null);
-  const files =
-    data && "files" in data
-      ? data.files.filter((file) => file.fileType === "html")
-      : [];
+  const files = useMemo(
+    () =>
+      data && "files" in data
+        ? data.files.filter((file) => file.fileType === "html")
+        : [],
+    [data],
+  );
   const active =
     files.find((file) => file.templateFileId === selectedId) ?? files[0];
+  const activeId = active?.templateFileId;
+  useEffect(() => {
+    if (files.length < 2) return;
+    const step = (event: KeyboardEvent) => {
+      if (
+        event.defaultPrevented ||
+        event.altKey ||
+        event.metaKey ||
+        event.ctrlKey
+      )
+        return;
+      const offset =
+        event.key === "ArrowRight" ? 1 : event.key === "ArrowLeft" ? -1 : 0;
+      if (!offset) return;
+      const index = files.findIndex((file) => file.templateFileId === activeId);
+      const next = files[(index + offset + files.length) % files.length];
+      if (!next) return;
+      event.preventDefault();
+      setSelectedId(next.templateFileId);
+    };
+    window.addEventListener("keydown", step);
+    return () => window.removeEventListener("keydown", step);
+  }, [files, activeId]);
   return (
     <TemplatePreviewDialog
       open

package/corpus/templates/design/app/components/templates/TemplatePreview.tsx

@@ -33,6 +33,7 @@ function TemplatePreviewContent({
   width,
   height,
   className,
+  fit = "contain",
   interactive = false,
   recordSessionReplay = false,
   onNavigate,
@@ -44,6 +45,7 @@ function TemplatePreviewContent({
   width?: number | null;
   height?: number | null;
   className?: string;
+  fit?: "contain" | "cover";
   interactive?: boolean;
   recordSessionReplay?: boolean;
   onNavigate?: (href: string) => void;
@@ -140,8 +142,9 @@ function TemplatePreviewContent({
       const availableWidth = element.clientWidth;
       const availableHeight = element.clientHeight;
       if (availableWidth > 0 && availableHeight > 0) {
+        const fitScale = fit === "cover" ? Math.max : Math.min;
         setScale(
-          Math.min(
+          fitScale(
             availableWidth / naturalWidth,
             availableHeight / naturalHeight,
           ),
@@ -152,7 +155,7 @@ function TemplatePreviewContent({
     const observer = new ResizeObserver(update);
     observer.observe(element);
     return () => observer.disconnect();
-  }, [naturalHeight, naturalWidth]);
+  }, [fit, naturalHeight, naturalWidth]);
 
   useEffect(() => {
     const frame = frameRef.current;
@@ -289,6 +292,7 @@ function TemplatePreviewContent({
               designId,
             );
         }}
+        data-fit={fit}
         tabIndex={interactive ? 0 : -1}
         aria-hidden={!interactive || undefined}
         className={cn(

package/corpus/templates/design/app/global.css

@@ -22,6 +22,12 @@
   backface-visibility: hidden;
 }
 
+.design-template-preview-frame[data-fit="cover"] {
+  top: 0;
+  transform: translateX(-50%) scale(var(--design-template-scale));
+  transform-origin: top center;
+}
+
 .design-library-card-preview {
   position: absolute;
   inset: 0;

package/corpus/templates/design/app/i18n/en-US.ts

@@ -164,6 +164,23 @@ export default {
     expandSidebar: "Expand sidebar",
     collapseSidebar: "Collapse sidebar",
   },
+  gettingStarted: {
+    title: "Getting started",
+    progress: "{{completeCount}} of {{totalCount}} complete",
+    collapse: "Collapse",
+    expand: "Expand",
+    completed: "Completed",
+    loadError: "Couldn't load your checklist",
+    retry: "Retry",
+    steps: {
+      createDesign: "Create your first design",
+      addBrand: "Add your brand",
+      useRealData: "Use your real data",
+      shareFeedback: "Share for feedback",
+      inviteTeammate: "Invite a teammate",
+      saveTemplate: "Save a design as a template",
+    },
+  },
   settings: {
     agentTitle: "Manage agent",
     agentDescription:

package/corpus/templates/design/app/lib/canvas-load-outcome.ts

@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useRef } from "react";
+
+import {
+  clearCanvasOutcomeDesign,
+  recordCanvasOutcome,
+  type CanvasLoadReadyBucket,
+} from "./canvas-outcome-tracking";
+
+/** A canvas that is not ready by then counts as stalled. */
+export const CANVAS_LOAD_STALL_MS = 10_000;
+
+export function canvasLoadReadyBucket(
+  elapsedMs: number,
+): CanvasLoadReadyBucket {
+  if (elapsedMs < 1_000) return "lt_1s";
+  if (elapsedMs <= 4_000) return "1_to_4s";
+  return "gt_4s";
+}
+
+interface CanvasLoad {
+  designId: string;
+  startedAt: number;
+  settled: boolean;
+  hidden: boolean;
+  stallTimer: ReturnType<typeof setTimeout>;
+  onVisibilityChange: () => void;
+}
+
+// One load per design opened: a board mounts a canvas per screen, and screens
+// remount, so counting per canvas would inflate loads and stalls.
+let currentLoad: CanvasLoad | null = null;
+
+function startLoad(designId: string): CanvasLoad {
+  const load: CanvasLoad = {
+    designId,
+    startedAt: Date.now(),
+    settled: false,
+    hidden: document.visibilityState === "hidden",
+    stallTimer: setTimeout(
+      () => settleLoad(load, "stalled"),
+      CANVAS_LOAD_STALL_MS,
+    ),
+    // Hidden tabs throttle timers and frames, so their load time means nothing.
+    onVisibilityChange: () => {
+      if (document.visibilityState === "hidden") load.hidden = true;
+    },
+  };
+  document.addEventListener("visibilitychange", load.onVisibilityChange);
+  currentLoad = load;
+  return load;
+}
+
+function endLoad(load: CanvasLoad): void {
+  load.settled = true;
+  clearTimeout(load.stallTimer);
+  document.removeEventListener("visibilitychange", load.onVisibilityChange);
+}
+
+function settleLoad(load: CanvasLoad, outcome: "ready" | "stalled"): void {
+  if (load.settled) return;
+  endLoad(load);
+  const { designId } = load;
+  if (load.hidden) {
+    recordCanvasOutcome("canvas_load", "skipped", "hidden_during_load", {
+      designId,
+    });
+  } else if (outcome === "stalled") {
+    recordCanvasOutcome("canvas_load", "failed", "stalled", { designId });
+  } else {
+    recordCanvasOutcome("canvas_load", "succeeded", "none", {
+      designId,
+      readyBucket: canvasLoadReadyBucket(Date.now() - load.startedAt),
+    });
+  }
+}
+
+// A load still running when its design closes is not counted.
+function abandonLoad(): void {
+  const load = currentLoad;
+  currentLoad = null;
+  if (load && !load.settled) endLoad(load);
+}
+
+/**
+ * Counts one `canvas_load` per design opened: the first measured canvas of a
+ * design starts it and the first to report ready ends it. Pass
+ * `measure: false` for a canvas that may never report ready (a snapshot, a
+ * localhost or Fusion preview), or a missing bridge would count as a stall.
+ * Call the returned function when the iframe bridge reports ready.
+ */
+export function useCanvasLoadOutcome({
+  designId,
+  measure,
+}: {
+  designId: string | undefined;
+  measure: boolean;
+}): () => void {
+  const latest = useRef({ designId, measure });
+  latest.current = { designId, measure };
+  const startedLoad = useRef<CanvasLoad | null>(null);
+
+  useEffect(() => {
+    try {
+      if (!measure || !designId) {
+        // A canvas that stops being measured ends the load it started, or that
+        // load would only ever end as a stall.
+        if (startedLoad.current && startedLoad.current === currentLoad) {
+          abandonLoad();
+        }
+        startedLoad.current = null;
+        return;
+      }
+      if (currentLoad?.designId === designId) return;
+      abandonLoad();
+      startedLoad.current = startLoad(designId);
+    } catch {
+      // coercion-ok: load tracking must never break canvas mounting.
+    }
+  }, [designId, measure]);
+
+  // Stable, and reads the latest props: the bridge handlers that call it are
+  // registered once and keep whichever callback they first saw.
+  return useCallback(() => {
+    try {
+      const { designId: canvasDesign, measure: measuring } = latest.current;
+      if (measuring && canvasDesign && currentLoad?.designId === canvasDesign) {
+        settleLoad(currentLoad, "ready");
+      }
+    } catch {
+      // coercion-ok: load tracking must never break the bridge-ready path.
+    }
+  }, []);
+}
+
+/** The editor closed its design: end its load and send pending counts. */
+export function leaveCanvasOutcomeDesign(): void {
+  try {
+    abandonLoad();
+    clearCanvasOutcomeDesign();
+  } catch {
+    // coercion-ok: tracking teardown must never break navigation.
+  }
+}
+
+export function __resetCanvasLoadOutcomeForTests(): void {
+  abandonLoad();
+}