Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

7.7 KB
Raw Blame
// Adapted from interior.dev "Task Steps" (MIT). See ./THIRD_PARTY_LICENSES.md
"use client";

import { AnimatePresence, motion } from "framer-motion";
import { Check, X } from "lucide-react";
import { useExtracted } from "next-intl";
import { useEffect, useState } from "react";
import { INSTANT, SPRING_CELL, SPRING_POP } from "@/lib/motion";
import { cn } from "@/lib/utils";

export type TaskStep = {
  id: string;
  label: string;
  /** Secondary detail, revealed once the step is done. */
  meta?: string;
};

export type TaskStepStatus = "pending" | "active" | "done" | "error";

export type UseTaskStepsOptions = {
  steps: TaskStep[];
  /** Index of the step in progress: earlier steps are done, `steps.length` means all of them are. */
  current: number;
  failed?: boolean;
};

// Gap between the checks of steps that are already done when the list first renders with `appear`.
const APPEAR_STAGGER = 0.08;
// Upstream waits this long before speaking, so a burst of quick steps is announced once, not per step.
const ANNOUNCE_DELAY_MS = 500;

export function taskStepStatus(index: number, current: number, failed: boolean, stepCount: number): TaskStepStatus {
  if (index < current) return "done";
  if (index === current && failed) return "error";
  if (index === current && current < stepCount) return "active";
  return "pending";
}

export function useTaskSteps({ steps, current, failed = false }: UseTaskStepsOptions) {
  const t = useExtracted();
  const complete = !failed && current >= steps.length;
  const rows = steps.map((step, index) => ({ ...step, status: taskStepStatus(index, current, failed, steps.length) }));
  const active = rows.find(row => row.status === "active");

  const sentence = failed
    ? t("Failed at {step}", { step: steps[Math.min(current, steps.length - 1)]?.label ?? "" })
    : complete
      ? t("All {count, number} steps complete", { count: steps.length })
      : active
        ? t("{step}, step {current, number} of {total, number}", {
            step: active.label,
            current: current + 1,
            total: steps.length,
          })
        : "";

  return { rows, complete, failed, sentence };
}

const LABEL_TONE: Record<TaskStepStatus, string> = {
  done: "text-neutral-700 dark:text-neutral-200",
  active: "font-medium text-neutral-900 dark:text-neutral-50",
  pending: "text-neutral-600 dark:text-neutral-400",
  error: "font-medium text-red-600 dark:text-red-400",
};

function StepIcon({ status, delay }: { status: TaskStepStatus; delay: number }) {
  const cell = "col-start-1 row-start-1";

  if (status === "done" || status === "error") {
    const done = status === "done";
    return (
      <motion.span
        className={cn(
          cell,
          "grid size-4 place-items-center rounded-md",
          done
            ? "bg-emerald-500/15 text-emerald-600 dark:bg-emerald-400/15 dark:text-emerald-400"
            : "bg-red-500/15 text-red-600 dark:bg-red-400/15 dark:text-red-400"
        )}
        initial={{ opacity: 0, scale: 0.4 }}
        animate={{ opacity: 1, scale: 1 }}
        exit={{ opacity: 0, transition: INSTANT }}
        transition={{ ...SPRING_POP, delay }}
      >
        {done ? <Check className="size-3" strokeWidth={3} /> : <X className="size-3" strokeWidth={3} />}
      </motion.span>
    );
  }

  if (status === "active") {
    return (
      <motion.span
        className={cn(cell, "text-neutral-500 dark:text-neutral-400")}
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0, transition: INSTANT }}
        transition={SPRING_CELL}
      >
        {/* Upstream spun this with a JS animation that ignored reduced motion; a CSS spin gated on
            motion-safe simply stays still for those users. */}
        <svg viewBox="0 0 16 16" className="size-3 motion-safe:animate-spin">
          <circle cx="8" cy="8" r="6" fill="none" stroke="currentColor" strokeOpacity="0.25" strokeWidth="2" />
          <path d="M8 2 a6 6 0 0 1 6 6" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
        </svg>
      </motion.span>
    );
  }

  return (
    <motion.span
      className={cn(cell, "size-[5px] rounded-[1px] bg-neutral-300 dark:bg-neutral-600")}
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0, transition: INSTANT }}
      transition={INSTANT}
    />
  );
}

export type TaskStepsProps = UseTaskStepsOptions & {
  /** Accessible name of the list. */
  label?: string;
  /** Pop in the checks of steps that are already done on the first render, staggered. */
  appear?: boolean;
  /** Seconds before that first stagger starts, e.g. to wait for the surrounding card to fade in. */
  appearDelay?: number;
  /** Speak progress in a polite live region. Turn off when the caller announces the outcome itself. */
  announce?: boolean;
  className?: string;
};

export function TaskSteps({
  steps,
  current,
  failed = false,
  label,
  appear = false,
  appearDelay = 0,
  announce = true,
  className,
}: TaskStepsProps) {
  const t = useExtracted();
  const { rows, sentence } = useTaskSteps({ steps, current, failed });
  // Steps done at first render are the ones that stagger in; a step that finishes later pops at once.
  const [doneOnMount] = useState(() => new Set(rows.filter(row => row.status === "done").map(row => row.id)));

  // One live region, always mounted, fed after a short settle. Upstream flipped a second region's
  // aria-live on in the same update as its text, so completion was announced twice.
  const [spoken, setSpoken] = useState("");
  useEffect(() => {
    if (!announce || !sentence) return;
    const timeout = window.setTimeout(() => setSpoken(sentence), ANNOUNCE_DELAY_MS);
    return () => window.clearTimeout(timeout);
  }, [announce, sentence]);

  const statusText: Record<TaskStepStatus, string> = {
    done: t("Done:"),
    active: t("In progress:"),
    pending: t("Not started:"),
    error: t("Failed:"),
  };

  return (
    <div className={cn("w-full", className)}>
      <ol aria-label={label ?? t("Progress")} className="flex flex-col">
        {rows.map((row, index) => (
          // Hanging indent: when the detail doesn't fit beside the label it wraps under it, instead of
          // squeezing the label into an ellipsis on narrow screens.
          <li
            key={row.id}
            aria-current={row.status === "active" ? "step" : undefined}
            className="relative flex flex-wrap items-baseline gap-x-2 py-1 pl-6"
          >
            <span aria-hidden="true" className="absolute left-0 top-1.5 grid size-4 place-items-center">
              <AnimatePresence initial={appear}>
                <StepIcon
                  key={row.status}
                  status={row.status}
                  delay={appear && doneOnMount.has(row.id) ? appearDelay + index * APPEAR_STAGGER : 0}
                />
              </AnimatePresence>
            </span>
            <span
              className={cn("min-w-0 max-w-full truncate text-sm leading-5 transition-colors", LABEL_TONE[row.status])}
            >
              <span className="sr-only">{statusText[row.status]} </span>
              {row.label}
            </span>
            {/* Always mounted, so a detail that turns up after the step is done still fades in. */}
            <span
              aria-hidden={row.status !== "done" || !row.meta}
              className={cn(
                "min-w-0 max-w-full truncate text-xs leading-4 text-neutral-600 transition-opacity duration-200 dark:text-neutral-400",
                row.status === "done" && row.meta ? "opacity-100" : "opacity-0"
              )}
            >
              {row.meta}
            </span>
          </li>
        ))}
      </ol>
      {announce ? (
        <span role="status" className="sr-only">
          {spoken}
        </span>
      ) : null}
    </div>
  );
}