@netlify/spark-ui 1.26.0-alpha.6 → 1.26.0-alpha.8

package/packages/components/preact/DropZone/DropZone.tsx

@@ -1,29 +1,18 @@
-import { useRef, useState } from 'preact/hooks';
-import Icon from '../Icon';
-import {
-  AnonymousDropClient,
-  deployFiles,
-  getSingleNonIndexHtmlFileName,
-  hasMultipleHtmlFilesWithoutIndex,
-  readDataTransfer,
-  readFileList,
-  type DeployProgress,
-  type DropClient,
-  type ProcessedFile,
-} from './drop-core';
+import { useEffect, useRef, useState } from 'preact/hooks';
+import type { ComponentChildren } from 'preact';
+import { readDataTransfer, readFileList, type DropClient } from './drop-core';
+import { useDropDeploy, type DeployedSite, type DeployStatus, type TrackFn } from './useDropDeploy';
 
 import './DropZone.css';
 
-type Status =
-  | { kind: 'idle' }
-  | { kind: 'reading' }
-  | { kind: 'creating' }
-  | { kind: 'uploading'; uploaded: number; total: number }
-  | { kind: 'processing' }
-  | { kind: 'redirecting' }
-  | { kind: 'error'; message: string };
+/** How long after the last `dragover` event we consider the drag gone. */
+const DRAG_INACTIVE_MS = 120;
+
+const defaultClaimUrl = (siteName: string) => `https://app.netlify.com/drop/${siteName}`;
 
 interface Props {
+  /** Content the drop layer sits on top of. The zone is invisible until you drag over it. */
+  children?: ComponentChildren;
   /** Override the API base (e.g. for a staging environment). */
   apiBase?: string;
   /** Inject a custom client (e.g. for testing). Defaults to AnonymousDropClient. */
@@ -31,160 +20,189 @@ interface Props {
   /** Build the "claim this site" URL from the assigned site name (subdomain). */
   claimUrl?: (siteName: string) => string;
   /** Called once the deploy is live. */
-  onDeploy?: (result: { url: string; token: string; siteName: string; siteId: string }) => void;
+  onDeploy?: (result: DeployedSite) => void;
+  /**
+   * Render the built-in status overlay (drag tint, spinner, progress bar, error).
+   * Set to `false` to suppress it entirely and keep your children visible, then
+   * drive your own feedback from the `data-state` attribute on the root element.
+   * Note: in this mode you're responsible for surfacing errors yourself.
+   */
+  showStatus?: boolean;
+  /**
+   * Analytics hook. Called at each tracked moment with an event name and
+   * properties. Stays provider-agnostic — wire it to Segment/Amplitude/GA in the
+   * consuming app, e.g. `onTrack={(name, props) => new Analytics().track(name, props)}`.
+   * Emitted events (all include `dropzone_id` when `analyticsId` is set):
+   * - `dropzone_files_dropped`  — files dropped via drag  ({ method: 'drag', file_count })
+   * - `dropzone_browse_opened`  — file picker opened       ({ method: 'keyboard' | 'click' })
+   * - `dropzone_deploy_succeeded` — deploy went live       ({ method, site_name, file_count })
+   */
+  onTrack?: TrackFn;
+  /**
+   * Stable identifier for this instance, attached to every tracked event as
+   * `dropzone_id`. Set it when a page renders more than one Drop Zone so the
+   * events can be told apart in Amplitude.
+   */
+  analyticsId?: string;
   className?: string;
 }
 
-const defaultClaimUrl = (siteName: string) => `https://app.netlify.com/drop/${siteName}`;
-
-function progressPhaseToStatus(e: DeployProgress): Status {
-  switch (e.phase) {
-    case 'creating':
-      return { kind: 'creating' };
-    case 'uploading':
-      return { kind: 'uploading', uploaded: e.uploaded ?? 0, total: e.total ?? 0 };
-    case 'processing':
-    case 'ready':
-      return { kind: 'processing' };
-  }
-}
-
 export default function DropZone({
+  children,
   apiBase,
   client,
   claimUrl = defaultClaimUrl,
   onDeploy,
+  showStatus = true,
+  onTrack,
+  analyticsId,
   className,
 }: Props) {
-  const [status, setStatus] = useState<Status>({ kind: 'idle' });
-  const [warning, setWarning] = useState<string | null>(null);
-  const [active, setActive] = useState(false);
-  const dropClient = useRef(client ?? new AnonymousDropClient(apiBase)).current;
-
-  const busy = status.kind !== 'idle' && status.kind !== 'error';
-
-  async function run(read: () => Promise<ProcessedFile[]>) {
-    setWarning(null);
-    setStatus({ kind: 'reading' });
-    try {
-      const files = await read();
-      if (!files.length) {
-        setStatus({ kind: 'error', message: 'No files found to deploy.' });
-        return;
-      }
-
-      // Surface index.html warnings without blocking the deploy.
-      const singleNonIndex = getSingleNonIndexHtmlFileName(files);
-      if (singleNonIndex) {
-        setWarning(`No index.html found — "${singleNonIndex}" won’t be served at the site root.`);
-      } else if (hasMultipleHtmlFilesWithoutIndex(files)) {
-        setWarning('No index.html found — your site may not have a landing page.');
-      }
-
-      const { url, token, deploy } = await deployFiles(dropClient, files, {
-        onProgress: e => setStatus(progressPhaseToStatus(e)),
-      });
-
-      // 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.
-      try {
-        localStorage.setItem('drop-token', token);
-        localStorage.setItem('dropSiteName', deploy.subdomain);
-      } catch {
-        /* private mode / storage disabled — non-fatal */
-      }
-
-      setStatus({ kind: 'redirecting' });
-      onDeploy?.({ url, token, siteName: deploy.subdomain, siteId: deploy.id });
-
-      // 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(deploy.subdomain)}#drop_token=${token}`);
-    } catch (err) {
-      setStatus({ kind: 'error', message: err instanceof Error ? err.message : String(err) });
-    }
-  }
-
-  function reset() {
-    setWarning(null);
-    setStatus({ kind: 'idle' });
-  }
+  // Tag every event with this instance's id so multiple zones on a page can be
+  // told apart, then hand it off to the consumer's analytics.
+  const track: TrackFn = (event, properties = {}) =>
+    onTrack?.(event, analyticsId ? { dropzone_id: analyticsId, ...properties } : properties);
+
+  const { status, warning, busy, deploy, reset } = useDropDeploy({
+    apiBase,
+    client,
+    claimUrl,
+    onDeploy,
+    track,
+  });
+
+  const { active, keepActive, endDrag } = useDragActive();
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const openPicker = (method: 'keyboard' | 'click') => {
+    track('dropzone_browse_opened', { method });
+    inputRef.current?.click();
+  };
+
+  // The overlay only paints when there's something to show — dragging, deploying,
+  // or an error. With `showStatus` off, the consumer drives their own feedback.
+  const showOverlay = showStatus && (active || busy || status.kind === 'error');
+  const rootClass = [
+    'n-dropzone',
+    active && 'is-active',
+    busy && 'is-busy',
+    !showStatus && 'is-bare',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
 
   return (
     <div
-      class={`n-dropzone${active ? ' is-active' : ''}${busy ? ' is-busy' : ''}${className ? ` ${className}` : ''}`}
+      class={rootClass}
       data-state={status.kind}
+      role="button"
+      tabIndex={busy ? -1 : 0}
+      aria-label="Drop a site folder or zip here to deploy it, or press Enter to browse for files"
+      aria-busy={busy}
       onDragOver={e => {
         if (busy) return;
         e.preventDefault();
-        setActive(true);
-      }}
-      onDragLeave={e => {
-        // Ignore drag-leave bubbling from children.
-        if (e.currentTarget === e.target) setActive(false);
+        keepActive();
       }}
       onDrop={e => {
         e.preventDefault();
-        setActive(false);
+        endDrag();
         if (busy) return;
         const dt = e.dataTransfer;
         if (!dt) return;
         // Capture entries synchronously — readDataTransfer reads them before
         // its first await, so the DataTransfer isn't detached out from under us.
-        run(() => readDataTransfer(dt));
+        deploy(() => readDataTransfer(dt), 'drag');
+      }}
+      onClick={e => {
+        // Only the zone's own empty area opens the picker; clicks that land on
+        // children are left to those children so they stay interactive.
+        if (!busy && e.target === e.currentTarget) openPicker('click');
+      }}
+      onKeyDown={e => {
+        if (busy) return;
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          openPicker('keyboard');
+        }
       }}
     >
-      {/* keyed so each state change remounts and replays its enter animation */}
-      <div class="n-dropzone-panel" key={status.kind}>
-        <StatusView status={status} onReset={reset} onFiles={run} />
-      </div>
-
-      {warning && status.kind !== 'error' && (
-        <p class="n-dropzone-warning n-fadeIn" role="status">
-          <Icon name="lightbulb" className="n-dropzone-warning-icon" />
-          {warning}
-        </p>
+      <div class="n-dropzone-content">{children}</div>
+
+      {/* Invisible-but-present fallback: keyboard/click opens the file picker. */}
+      <input
+        ref={inputRef}
+        type="file"
+        hidden
+        multiple
+        // @ts-expect-error non-standard directory-picker attributes
+        webkitdirectory=""
+        directory=""
+        onChange={e => {
+          const input = e.currentTarget as HTMLInputElement;
+          if (input.files?.length) deploy(() => readFileList(input.files!), 'browse');
+          input.value = '';
+        }}
+      />
+
+      {showOverlay && (
+        <div
+          class="n-dropzone-overlay n-fadeIn"
+          key={status.kind === 'idle' ? 'active' : status.kind}
+        >
+          <StatusView status={status} active={active} onReset={reset} />
+          {warning && status.kind !== 'error' && busy && (
+            <p class="n-dropzone-warning" role="status">
+              {warning}
+            </p>
+          )}
+        </div>
       )}
     </div>
   );
 }
 
+/**
+ * Track whether a drag is currently over the zone. A drag has no reliable
+ * "cancelled" event — pressing Escape or dropping elsewhere just stops the
+ * stream of `dragover` events — so we stay active only while they keep arriving
+ * and clear shortly after they stop. This also handles drags over children,
+ * where `dragleave` targets a child rather than the zone.
+ */
+function useDragActive() {
+  const [active, setActive] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => () => clearTimeout(timer.current), []);
+
+  const keepActive = () => {
+    setActive(true);
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => setActive(false), DRAG_INACTIVE_MS);
+  };
+
+  const endDrag = () => {
+    clearTimeout(timer.current);
+    setActive(false);
+  };
+
+  return { active, keepActive, endDrag };
+}
+
 function StatusView({
   status,
+  active,
   onReset,
-  onFiles,
 }: {
-  status: Status;
+  status: DeployStatus;
+  active: boolean;
   onReset: () => void;
-  onFiles: (read: () => Promise<ProcessedFile[]>) => void;
 }) {
   switch (status.kind) {
+    // Idle-but-active means a drag is hovering the zone.
     case 'idle':
-      return (
-        <>
-          <UploadGlyph />
-          <p class="n-dropzone-title">Drag &amp; drop your site folder or zip</p>
-          <p class="n-dropzone-subtitle">Deploys instantly to a live URL — no account needed.</p>
-          <label class="n-dropzone-browse">
-            Browse files
-            <input
-              type="file"
-              hidden
-              multiple
-              // @ts-expect-error non-standard directory-picker attributes
-              webkitdirectory=""
-              directory=""
-              onChange={e => {
-                const input = e.currentTarget as HTMLInputElement;
-                if (input.files?.length) onFiles(() => readFileList(input.files!));
-              }}
-            />
-          </label>
-        </>
-      );
+      return active ? <p class="n-dropzone-hint">Drop to deploy</p> : null;
 
     case 'reading':
       return <Spinner label="Reading files…" />;
@@ -232,27 +250,3 @@ function Spinner({ label }: { label: string }) {
     </div>
   );
 }
-
-function UploadGlyph() {
-  return (
-    <span class="n-dropzone-glyph" aria-hidden="true">
-      <svg viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
-        <path
-          class="n-dropzone-glyph-tray"
-          d="M8 30v6a4 4 0 0 0 4 4h24a4 4 0 0 0 4-4v-6"
-          stroke="currentColor"
-          stroke-width="3"
-          stroke-linecap="round"
-        />
-        <path
-          class="n-dropzone-glyph-arrow"
-          d="M24 32V10m0 0-8 8m8-8 8 8"
-          stroke="currentColor"
-          stroke-width="3"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-        />
-      </svg>
-    </span>
-  );
-}

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

@@ -0,0 +1,149 @@
+import { useRef, useState } from 'preact/hooks';
+import {
+  AnonymousDropClient,
+  deployFiles,
+  getSingleNonIndexHtmlFileName,
+  hasMultipleHtmlFilesWithoutIndex,
+  type DeployProgress,
+  type DropClient,
+  type ProcessedFile,
+} from './drop-core';
+
+/** How the files reached the zone — carried through to analytics. */
+export type DeploySource = 'drag' | 'browse';
+
+/** The live site handed back once a deploy succeeds. */
+export interface DeployedSite {
+  url: string;
+  token: string;
+  siteName: string;
+  siteId: string;
+}
+
+/** Finite states of a single deploy attempt. */
+export type DeployStatus =
+  | { kind: 'idle' }
+  | { kind: 'reading' }
+  | { kind: 'creating' }
+  | { kind: 'uploading'; uploaded: number; total: number }
+  | { kind: 'processing' }
+  | { kind: 'redirecting' }
+  | { kind: 'error'; message: string };
+
+/** Provider-agnostic analytics sink. */
+export type TrackFn = (event: string, properties?: Record<string, unknown>) => void;
+
+interface UseDropDeployOptions {
+  apiBase?: string;
+  client?: DropClient;
+  claimUrl: (siteName: string) => string;
+  onDeploy?: (site: DeployedSite) => void;
+  track: TrackFn;
+}
+
+/** Map a low-level deploy progress event onto our UI status. */
+function progressToStatus(e: DeployProgress): DeployStatus {
+  switch (e.phase) {
+    case 'creating':
+      return { kind: 'creating' };
+    case 'uploading':
+      return { kind: 'uploading', uploaded: e.uploaded ?? 0, total: e.total ?? 0 };
+    case 'processing':
+    case 'ready':
+      return { kind: 'processing' };
+  }
+}
+
+/** Inspect the file set and return a non-blocking index.html warning, if any. */
+function indexHtmlWarning(files: ProcessedFile[]): string | null {
+  const singleNonIndex = getSingleNonIndexHtmlFileName(files);
+  if (singleNonIndex) {
+    return `No index.html found — "${singleNonIndex}" won’t be served at the site root.`;
+  }
+  if (hasMultipleHtmlFilesWithoutIndex(files)) {
+    return 'No index.html found — your site may not have a landing page.';
+  }
+  return null;
+}
+
+/**
+ * Owns the deploy state machine and its side effects (upload, local persistence,
+ * analytics, redirect), keeping DropZone a thin view over the returned `status`.
+ */
+export function useDropDeploy({
+  apiBase,
+  client,
+  claimUrl,
+  onDeploy,
+  track,
+}: UseDropDeployOptions) {
+  const [status, setStatus] = useState<DeployStatus>({ kind: 'idle' });
+  const [warning, setWarning] = useState<string | null>(null);
+  const dropClient = useRef(client ?? new AnonymousDropClient(apiBase)).current;
+
+  const busy = status.kind !== 'idle' && status.kind !== 'error';
+
+  async function deploy(read: () => Promise<ProcessedFile[]>, source: DeploySource) {
+    setWarning(null);
+    setStatus({ kind: 'reading' });
+    try {
+      const files = await read();
+      if (!files.length) {
+        setStatus({ kind: 'error', message: 'No files found to deploy.' });
+        return;
+      }
+
+      // 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', { method: source, file_count: files.length });
+      }
+
+      setWarning(indexHtmlWarning(files));
+
+      const {
+        url,
+        token,
+        deploy: result,
+      } = await deployFiles(dropClient, files, {
+        onProgress: e => setStatus(progressToStatus(e)),
+      });
+
+      // 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.
+      try {
+        localStorage.setItem('drop-token', token);
+        localStorage.setItem('dropSiteName', result.subdomain);
+      } catch {
+        /* private mode / storage disabled — non-fatal */
+      }
+
+      setStatus({ kind: 'redirecting' });
+      // 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).
+      track('dropzone_deploy_succeeded', {
+        method: source,
+        site_name: result.subdomain,
+        file_count: files.length,
+      });
+      onDeploy?.({ url, token, siteName: result.subdomain, siteId: result.id });
+
+      // 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}`);
+    } catch (err) {
+      setStatus({ kind: 'error', message: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  function reset() {
+    setWarning(null);
+    setStatus({ kind: 'idle' });
+  }
+
+  return { status, warning, busy, deploy, reset };
+}