@netlify/spark-ui 1.31.0-alpha.3 → 1.31.0-alpha.4

package/packages/components/preact/DropZone/useDropDeploy.ts

@@ -1,9 +1,15 @@
-import { useRef, useState } from 'preact/hooks';
+import { useEffect, useRef, useState } from 'preact/hooks';
 import {
   AnonymousDropClient,
+  clearDropStash,
+  deployZippedBuild,
+  DROPZONE_EVENTS,
+  hasDropStashMarker,
+  loadDropStash,
+  saveDropStash,
+  zipFiles,
   AuthenticatedBuildClient,
   AuthenticatedDropClient,
-  deployBuild,
   deployFiles,
   detectBuild,
   getSingleNonIndexHtmlFileName,
@@ -16,12 +22,17 @@ import {
   type DeployProgress,
   type DeployResult,
   type DropClient,
+  type DropMethod,
+  type DropZoneEventName,
+  type DropZoneEventProperties,
+  type TrackFn,
   type InferredBuildSettings,
   type ProcessedFile,
-} from './drop-core';
+  type ZipResult,
+} from '../../../drop-core';
 
 /** How the files reached the zone — carried through to analytics. */
-export type DeploySource = 'drag' | 'browse';
+export type DeploySource = DropMethod;
 
 /** The live site handed back once a deploy succeeds. */
 export interface DeployedSite {
@@ -77,8 +88,8 @@ export type DeployStatus =
   | { kind: 'redirecting'; target: 'claim' | 'dashboard' | 'signup' | 'build' }
   | { kind: 'error'; message: string };
 
-/** Provider-agnostic analytics sink. */
-export type TrackFn = (event: string, properties?: Record<string, unknown>) => void;
+/** Re-exported from the drop-core analytics contract, where the shape now lives. */
+export type { TrackFn };
 
 interface UseDropDeployOptions {
   apiBase?: string;
@@ -94,6 +105,8 @@ interface UseDropDeployOptions {
   buildDeployUrl: (build: DeployedBuild) => string;
   waitForBuild?: boolean;
   onBuildRequired?: (info: BuildDetection) => void;
+  onBuildSignupHandoff?: (info: { stashed: boolean; detection: BuildDetection }) => void;
+  resumeStashedBuilds?: boolean;
   onDeploy?: (site: DeployedSite) => void;
   onBuildDeploy?: (build: DeployedBuild) => void;
   onError?: (error: DeployError) => void;
@@ -129,6 +142,23 @@ function indexHtmlWarning(files: ProcessedFile[]): string | null {
   return null;
 }
 
+/**
+ * Best-effort local persistence of the anonymous claim handoff. Note this does
+ * NOT reach the dashboard: localStorage is per-origin, so a token written here
+ * (e.g. www.netlify.com) is invisible to app.netlify.com. The cross-origin
+ * handoff is the URL fragment on the claim redirect; this only helps if the
+ * drop and claim share an origin. Authenticated deploys never call this —
+ * there is no claim token, and the upload bearer must never be persisted.
+ */
+function persistAnonymousClaimLocally(token: string, siteName: string): void {
+  try {
+    localStorage.setItem('drop-token', token);
+    localStorage.setItem('dropSiteName', siteName);
+  } catch {
+    /* private mode / storage disabled — non-fatal */
+  }
+}
+
 /**
  * Owns the deploy state machine and its side effects (upload, local persistence,
  * analytics, redirect), keeping DropZone a thin view over the returned `status`.
@@ -147,11 +177,25 @@ export function useDropDeploy({
   buildDeployUrl,
   waitForBuild,
   onBuildRequired,
+  onBuildSignupHandoff,
+  resumeStashedBuilds = true,
   onDeploy,
   onBuildDeploy,
   onError,
   track,
 }: UseDropDeployOptions) {
+  /**
+   * Typed veneer over the consumer's `track`: event names come from the
+   * DROPZONE_EVENTS contract and each payload is checked against its shape,
+   * so a renamed property fails to compile instead of silently forking the
+   * analytics history.
+   */
+  const emit = <E extends DropZoneEventName>(event: E, props: DropZoneEventProperties[E]) =>
+    // The cast bridges to TrackFn's loose record: the interfaces have no index
+    // signature (so payloads stay closed for consumers), and the checking that
+    // matters happened against DropZoneEventProperties[E] above.
+    track(event, props as Record<string, unknown>);
+
   const [status, setStatus] = useState<DeployStatus>({ kind: 'idle' });
   const [warning, setWarning] = useState<string | null>(null);
   const dropClient = useRef(client ?? new AnonymousDropClient(apiBase)).current;
@@ -180,17 +224,17 @@ export function useDropDeploy({
   const busy = status.kind !== 'idle' && status.kind !== 'error';
 
   /**
-   * Zip the drop, create a site and enqueue a build. Returns `null` when the
-   * visitor turns out not to be logged in — nothing is created in that case, so
-   * the caller can still fall back to the signup hand-off. Every other failure
-   * throws and is reported by the caller's `catch`.
+   * Create a site and enqueue a build for an already-zipped drop. Returns
+   * `null` when the visitor turns out not to be logged in — nothing is created
+   * in that case, so the caller can still stash the archive and hand off to
+   * signup. Every other failure throws and is reported by the caller's `catch`.
    */
-  async function buildProject(
+  async function enqueueZippedBuild(
     client: BuildClient,
-    files: ProcessedFile[]
+    archive: ZipResult
   ): Promise<DeployedBuild | null> {
     try {
-      const { site, build, buildSettings, url } = await deployBuild(client, files, {
+      const { site, build, buildSettings, url } = await deployZippedBuild(client, archive, {
         onProgress: e => setStatus(progressToStatus(e)),
         waitForBuild,
       });
@@ -208,6 +252,14 @@ export function useDropDeploy({
     }
   }
 
+  /** One attempt's analytics context, threaded to the branch handlers below. */
+  interface AttemptContext {
+    source: DeploySource;
+    fileCount: number;
+    /** `{ file_types }` when the drop boundary captured any, `{}` otherwise — spread into every event. */
+    typeProps: { file_types?: string[] };
+  }
+
   /**
    * `fileTypes` is the MIME types of the selection, read at the drop boundary
    * (see `getFileTypes`) and passed in rather than derived here — it has to be
@@ -237,15 +289,10 @@ export function useDropDeploy({
     // the humanized message while keeping the raw reason for their own logging.
     const fail = (message: string, reason: string, extra?: Record<string, unknown>) => {
       setStatus({ kind: 'error', message });
-      track('dropzone_deploy_failed', { method: source, reason, ...typeProps, ...extra });
+      emit(DROPZONE_EVENTS.DEPLOY_FAILED, { method: source, reason, ...typeProps, ...extra });
       onError?.({ message, reason });
     };
 
-    const failFromError = (err: unknown, extra?: Record<string, unknown>) => {
-      const reason = err instanceof Error ? err.message : String(err);
-      fail(humanizeDropError(err), reason, extra);
-    };
-
     try {
       // Auto-rename a lone non-index HTML file to index.html so it is served at
       // the site root. Detection (getSingleNonIndexHtmlFileName) sits on the
@@ -260,140 +307,258 @@ export function useDropDeploy({
       // A drop is the "user provided files" signal; the browse path is already
       // tracked when the picker opens.
       if (source === 'drag') {
-        track('dropzone_files_dropped', {
+        emit(DROPZONE_EVENTS.FILES_DROPPED, {
           method: source,
           file_count: files.length,
           ...typeProps,
         });
       }
 
-      // Build-required projects can't deploy through the anonymous drop API —
-      // it only performs static deploys, so building one this way yields a
-      // broken site. Detect them up front and route them to the build path
-      // (which needs a logged-in user) or, failing that, hand off to the
-      // authenticated Drop page via signup. Consumers can override the hand-off
-      // entirely with `onBuildRequired`.
-      const build = detectBuild(files);
-      if (build.buildRequired) {
-        track('dropzone_build_required', {
+      const ctx: AttemptContext = { source, fileCount: files.length, typeProps };
+      const detection = detectBuild(files);
+      if (detection.buildRequired) {
+        await handleBuildRequiredDrop(files, detection, ctx);
+      } else {
+        await deployStaticDrop(files, ctx);
+      }
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      fail(humanizeDropError(err), reason);
+    }
+  }
+
+  /**
+   * A drop that needs a build. Build-required projects can't deploy through the
+   * anonymous drop API — it only performs static deploys, so building one this
+   * way yields a broken site. They're routed to the authenticated build path
+   * instead, or stashed and handed off to signup when there is no session.
+   * Consumers can take over entirely with `onBuildRequired`, or own just the
+   * signup hand-off with `onBuildSignupHandoff`.
+   */
+  async function handleBuildRequiredDrop(
+    files: ProcessedFile[],
+    detection: BuildDetection,
+    { source, fileCount, typeProps }: AttemptContext
+  ) {
+    emit(DROPZONE_EVENTS.BUILD_REQUIRED, {
+      method: source,
+      reason: detection.reason,
+      file_count: fileCount,
+      ...typeProps,
+    });
+
+    if (onBuildRequired) {
+      // The consumer owns the hand-off now; drop back to idle so the zone
+      // stays usable rather than sitting on a spinner.
+      setStatus({ kind: 'idle' });
+      onBuildRequired(detection);
+      return;
+    }
+
+    let stashed = false;
+    if (authedBuildClient) {
+      // Zip before anything is created: the archive serves whichever path
+      // runs — an authenticated build right now, or the stash that carries
+      // the drop across signup.
+      setStatus({ kind: 'zipping' });
+      const archive = await zipFiles(files);
+
+      const built = await enqueueZippedBuild(authedBuildClient, archive);
+      if (built) {
+        setStatus({ kind: 'redirecting', target: 'build' });
+        emit(DROPZONE_EVENTS.BUILD_DEPLOY_SUCCEEDED, {
           method: source,
-          reason: build.reason,
-          file_count: files.length,
+          reason: detection.reason,
+          site_name: built.siteName,
+          file_count: fileCount,
+          ...(built.buildSettings ? { framework: built.buildSettings.framework } : {}),
           ...typeProps,
         });
-        if (onBuildRequired) {
-          // The consumer owns the hand-off now; drop back to idle so the zone
-          // stays usable rather than sitting on a spinner.
-          setStatus({ kind: 'idle' });
-          onBuildRequired(build);
-          return;
-        }
-        if (authedBuildClient) {
-          const built = await buildProject(authedBuildClient, files);
-          // No session after all (the auth hint cookie can outlive the session).
-          // Nothing was created, so fall through to the signup hand-off rather
-          // than dead-ending on an error the visitor can't act on from here.
-          if (built) {
-            setStatus({ kind: 'redirecting', target: 'build' });
-            track('dropzone_build_deploy_succeeded', {
-              method: source,
-              reason: build.reason,
-              site_name: built.siteName,
-              file_count: files.length,
-              ...(built.buildSettings ? { framework: built.buildSettings.framework } : {}),
-              ...typeProps,
-            });
-            onBuildDeploy?.(built);
-            window.location.assign(buildDeployUrl(built));
-            return;
-          }
-        }
-        setStatus({ kind: 'redirecting', target: 'signup' });
-        window.location.assign(buildSignupUrl);
+        onBuildDeploy?.(built);
+        window.location.assign(buildDeployUrl(built));
         return;
       }
 
-      setWarning(indexHtmlWarning(files));
-
-      // Deploy into the visitor's account when we can. NotAuthenticatedError is
-      // the one failure that falls back to the anonymous flow — it's thrown
-      // before anything is created (the auth hint cookie can outlive the
-      // session), so retrying anonymously can't strand a half-made site. Any
-      // later failure is real and surfaces as an error instead: falling back
-      // then would leave an empty site in the account and deploy a duplicate.
-      let deployed: DeployResult | null = null;
-      let authenticated = false;
-      let authFallback = false;
-      if (authedDropClient) {
-        try {
-          deployed = await deployFiles(authedDropClient, files, {
-            onProgress: e => setStatus(progressToStatus(e)),
-          });
-          authenticated = true;
-        } catch (err) {
-          if (!(err instanceof NotAuthenticatedError)) throw err;
-          authFallback = true;
-        }
-      }
-      if (!deployed) {
-        deployed = await deployFiles(dropClient, files, {
-          onProgress: e => setStatus(progressToStatus(e)),
+      // No session after all (the auth hint cookie can outlive the session).
+      // Nothing was created — stash the archive so the drop survives the
+      // signup round-trip. When the visitor is back on this origin
+      // authenticated, the mount-time resume deploys it for them.
+      stashed = await saveDropStash(archive.file, archive.buildSettings);
+      if (stashed) {
+        emit(DROPZONE_EVENTS.PROJECT_STASHED, {
+          method: source,
+          reason: detection.reason,
+          file_count: fileCount,
+          ...typeProps,
         });
       }
-      const { url, token, deploy: result } = deployed;
-
-      if (!authenticated) {
-        // Best-effort local persistence. Note this does NOT reach the dashboard:
-        // localStorage is per-origin, so a token written here (e.g. www.netlify.com)
-        // is invisible to app.netlify.com. The cross-origin handoff is the URL
-        // fragment below; this only helps if the drop and claim share an origin.
-        // Authenticated deploys skip this entirely — there is no claim token,
-        // and the upload bearer must never be persisted.
-        try {
-          localStorage.setItem('drop-token', token);
-          localStorage.setItem('dropSiteName', result.subdomain);
-        } catch {
-          /* private mode / storage disabled — non-fatal */
-        }
-      }
+    }
+    // Without build wiring nothing here could deploy a stash later, so nothing
+    // is stashed — the hand-off is all that's left.
 
-      setStatus({ kind: 'redirecting', target: authenticated ? 'dashboard' : 'claim' });
-      // Fired before the redirect below. Note: the navigation can cut a
-      // fire-and-forget analytics request short — see the docs for delivery
-      // hardening (sendBeacon / deferring the redirect). `auth_fallback` is only
-      // sent when an authenticated attempt bounced (stale auth hint) — omitted
-      // otherwise, like `file_types`.
-      track('dropzone_deploy_succeeded', {
-        method: source,
-        site_name: result.subdomain,
-        file_count: files.length,
-        authenticated,
-        ...(authFallback ? { auth_fallback: true } : {}),
-        ...typeProps,
-      });
-      onDeploy?.({
-        url,
-        ...(authenticated ? {} : { token }),
-        siteName: result.subdomain,
-        siteId: result.id,
-        authenticated,
+    if (onBuildSignupHandoff) {
+      // The consumer owns the hand-off (e.g. an auth popup that keeps the
+      // visitor on this page); back to idle so the zone stays usable.
+      setStatus({ kind: 'idle' });
+      onBuildSignupHandoff({ stashed, detection });
+      return;
+    }
+    setStatus({ kind: 'redirecting', target: 'signup' });
+    window.location.assign(buildSignupUrl);
+  }
+
+  /**
+   * Try the authenticated static deploy, or report that the visitor has no
+   * session. NotAuthenticatedError is the one failure that returns null and
+   * lets the caller fall back to the anonymous flow — it's thrown before
+   * anything is created (the auth hint cookie can outlive the session), so
+   * retrying anonymously can't strand a half-made site. Any later failure is
+   * real and rethrows: falling back then would leave an empty site in the
+   * account and deploy a duplicate.
+   */
+  async function attemptAuthenticatedStaticDeploy(
+    client: DropClient,
+    files: ProcessedFile[]
+  ): Promise<DeployResult | null> {
+    try {
+      return await deployFiles(client, files, {
+        onProgress: e => setStatus(progressToStatus(e)),
       });
+    } catch (err) {
+      if (err instanceof NotAuthenticatedError) return null;
+      throw err;
+    }
+  }
 
-      if (authenticated) {
-        // The site already lives in the visitor's account — send them straight
-        // to its dashboard page. No claim step, no token in the URL.
-        window.location.assign(siteDashboardUrl(result.subdomain));
-      } else {
-        // Hand the drop token to the dashboard via the URL fragment — localStorage
-        // does not cross origins. The dashboard's /drop/:name page reads
-        // `#drop_token=` and persists it for the claim + post-signup steps.
-        window.location.assign(`${claimUrl(result.subdomain)}#drop_token=${token}`);
-      }
+  /** A static drop: into the visitor's account when possible, anonymous otherwise. */
+  async function deployStaticDrop(
+    files: ProcessedFile[],
+    { source, fileCount, typeProps }: AttemptContext
+  ) {
+    setWarning(indexHtmlWarning(files));
+
+    const authedResult = authedDropClient
+      ? await attemptAuthenticatedStaticDeploy(authedDropClient, files)
+      : null;
+    const authenticated = authedResult !== null;
+    // A fallback is an authed attempt that bounced — distinct from never trying.
+    const authFallback = authedDropClient !== null && !authenticated;
+
+    const deployed =
+      authedResult ??
+      (await deployFiles(dropClient, files, {
+        onProgress: e => setStatus(progressToStatus(e)),
+      }));
+    const { url, token, deploy: result } = deployed;
+
+    if (!authenticated) {
+      persistAnonymousClaimLocally(token, result.subdomain);
+    }
+
+    setStatus({ kind: 'redirecting', target: authenticated ? 'dashboard' : 'claim' });
+    // Fired before the redirect below. Note: the navigation can cut a
+    // fire-and-forget analytics request short — see the docs for delivery
+    // hardening (sendBeacon / deferring the redirect). `auth_fallback` is only
+    // sent when an authenticated attempt bounced (stale auth hint) — omitted
+    // otherwise, like `file_types`.
+    emit(DROPZONE_EVENTS.DEPLOY_SUCCEEDED, {
+      method: source,
+      site_name: result.subdomain,
+      file_count: fileCount,
+      authenticated,
+      ...(authFallback ? { auth_fallback: true } : {}),
+      ...typeProps,
+    });
+    onDeploy?.({
+      url,
+      ...(authenticated ? {} : { token }),
+      siteName: result.subdomain,
+      siteId: result.id,
+      authenticated,
+    });
+
+    redirectAfterStaticDeploy(authenticated, result.subdomain, token);
+  }
+
+  /** Hand the visitor to their new site: its dashboard page, or the claim page. */
+  function redirectAfterStaticDeploy(authenticated: boolean, siteName: string, token: string) {
+    if (authenticated) {
+      // The site already lives in the visitor's account — send them straight
+      // to its dashboard page. No claim step, no token in the URL.
+      window.location.assign(siteDashboardUrl(siteName));
+    } else {
+      // Hand the drop token to the dashboard via the URL fragment — localStorage
+      // does not cross origins. The dashboard's /drop/:name page reads
+      // `#drop_token=` and persists it for the claim + post-signup steps.
+      window.location.assign(`${claimUrl(siteName)}#drop_token=${token}`);
+    }
+  }
+
+  /**
+   * Deploy a drop stashed before the signup hand-off (see `buildStash`).
+   *
+   * The stash is consumed only once the visitor is provably authenticated —
+   * the marker (or the auth hint behind `getUploadToken`) can outlive the
+   * session, and consuming on a bounced attempt would quietly lose the drop.
+   * Once past that gate it is consumed whether the deploy succeeds or fails,
+   * so a broken project can never retry-loop.
+   */
+  async function resumeStashedBuild(client: BuildClient) {
+    const stash = await loadDropStash();
+    if (!stash) {
+      // Expired or unavailable — clear the dangling marker and stay idle.
+      await clearDropStash();
+      return;
+    }
+
+    emit(DROPZONE_EVENTS.RESUMED, {});
+    setStatus({ kind: 'creating' });
+
+    const archive: ZipResult = { file: stash.zipFile, buildSettings: stash.buildSettings };
+    let built: DeployedBuild | null;
+    try {
+      built = await enqueueZippedBuild(client, archive);
     } catch (err) {
-      failFromError(err);
+      await clearDropStash();
+      failResume(err instanceof Error ? err.message : String(err));
+      return;
+    }
+
+    if (!built) {
+      // Still no session — the visitor came back logged out. Keep the stash for
+      // their next authenticated visit and return to idle without fuss.
+      setStatus({ kind: 'idle' });
+      return;
     }
+
+    await clearDropStash();
+    setStatus({ kind: 'redirecting', target: 'build' });
+    onBuildDeploy?.(built);
+    window.location.assign(buildDeployUrl(built));
+  }
+
+  /** Resume failures re-use the normal error surface, with re-drop copy. */
+  function failResume(reason: string) {
+    const message =
+      'We couldn\u2019t automatically deploy your project. Drop it again to publish it.';
+    setStatus({ kind: 'error', message });
+    // No `method`: the failure comes from storage, not a live drop gesture.
+    emit(DROPZONE_EVENTS.DEPLOY_FAILED, { reason: 'resume_failed' });
+    onError?.({ message, reason });
   }
 
+  // Attempt a resume once per mount — guarded by the cheap synchronous marker
+  // check so ordinary page loads never open IndexedDB, and only when this zone
+  // has the wiring to build (a zone without it could not deploy the stash).
+  const resumeAttempted = useRef(false);
+  useEffect(() => {
+    if (resumeAttempted.current || !resumeStashedBuilds) return;
+    if (!authedBuildClient || !hasDropStashMarker()) return;
+    resumeAttempted.current = true;
+    void resumeStashedBuild(authedBuildClient);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- deliberately mount-only
+  }, []);
+
   function reset() {
     setWarning(null);
     setStatus({ kind: 'idle' });

package/packages/components/preact/index.ts

@@ -6,7 +6,24 @@ export { default as SearchHeading } from './SearchModal/components/SearchHeading
 export { default as SearchToggle } from './SearchModal/components/SearchToggle/SearchToggle';
 export { default as AskNetlify } from './AskNetlify/AskNetlify';
 export { SearchModal } from './SearchModal';
-export { DropZone, AuthenticatedBuildClient, AuthenticatedDropClient } from './DropZone';
-export type { BuildClient, DeployedBuild, DeployedSite, DropClient } from './DropZone';
+export {
+  DropZone,
+  AuthenticatedBuildClient,
+  AuthenticatedDropClient,
+  DROPZONE_EVENTS,
+  getFileTypes,
+  humanizeDropError,
+} from './DropZone';
+export type {
+  BuildClient,
+  DeployedBuild,
+  DeployedSite,
+  DeployError,
+  DeployStatus,
+  DropClient,
+  DropZoneEventName,
+  DropZoneEventProperties,
+  TrackFn,
+} from './DropZone';
 
 export { type IconName } from './Icon';

package/packages/drop-core/analytics.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { DROPZONE_EVENTS } from './analytics';
+
+describe('DROPZONE_EVENTS', () => {
+  it('pins the wire names — renaming one silently forks Amplitude/Segment history', () => {
+    expect(DROPZONE_EVENTS).toEqual({
+      FILES_DROPPED: 'dropzone_files_dropped',
+      BROWSE_OPENED: 'dropzone_browse_opened',
+      BUILD_REQUIRED: 'dropzone_build_required',
+      DEPLOY_SUCCEEDED: 'dropzone_deploy_succeeded',
+      BUILD_DEPLOY_SUCCEEDED: 'dropzone_build_deploy_succeeded',
+      DEPLOY_FAILED: 'dropzone_deploy_failed',
+      PROJECT_STASHED: 'dropzone_project_stashed',
+      RESUMED: 'dropzone_resumed',
+    });
+  });
+});