@alpic-ai/ui 0.0.0-dev.c660552 → 0.0.0-dev.c6b023d

package/src/components/form.tsx

@@ -14,8 +14,10 @@ import {
 } from "react-hook-form";
 
 import { cn } from "../lib/cn";
+import { Checkbox } from "./checkbox";
 import { Input, type InputProps } from "./input";
 import { Label } from "./label";
+import { RadioGroup, RadioGroupItem } from "./radio-group";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./select";
 import { Textarea, type TextareaProps } from "./textarea";
 import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip";
@@ -141,7 +143,7 @@ function FormDescription({ className, ...props }: React.ComponentProps<"p">) {
     <p
       data-slot="form-description"
       id={formDescriptionId}
-      className={cn("text-muted-foreground text-sm", className)}
+      className={cn("text-muted-foreground type-text-sm whitespace-pre-line", className)}
       {...props}
     />
   );
@@ -220,10 +222,10 @@ function InputField<TFieldValues extends FieldValues, TName extends FieldPath<TF
               {label}
             </FormLabel>
           )}
+          {description && <FormDescription>{description}</FormDescription>}
           <FormControl>
             <Input {...inputProps} {...field} />
           </FormControl>
-          {description && <FormDescription>{description}</FormDescription>}
           <FormMessage />
         </FormItem>
       )}
@@ -257,10 +259,10 @@ function TextareaField<TFieldValues extends FieldValues, TName extends FieldPath
               {label}
             </FormLabel>
           )}
+          {description && <FormDescription>{description}</FormDescription>}
           <FormControl>
             <Textarea {...textareaProps} {...field} />
           </FormControl>
-          {description && <FormDescription>{description}</FormDescription>}
           <FormMessage />
         </FormItem>
       )}
@@ -303,6 +305,7 @@ function SelectField<TFieldValues extends FieldValues, TName extends FieldPath<T
               {label}
             </FormLabel>
           )}
+          {description && <FormDescription>{description}</FormDescription>}
           <Select value={field.value} onValueChange={field.onChange}>
             <FormControl>
               <SelectTrigger>
@@ -317,7 +320,56 @@ function SelectField<TFieldValues extends FieldValues, TName extends FieldPath<T
               ))}
             </SelectContent>
           </Select>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
+
+interface RadioFieldProps<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>
+  extends FormFieldBaseProps<TFieldValues, TName> {
+  options: SelectFieldOption[];
+}
+
+function RadioField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>({
+  control,
+  name,
+  rules,
+  required,
+  label,
+  description,
+  tooltip,
+  options,
+}: RadioFieldProps<TFieldValues, TName>) {
+  return (
+    <FormField
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field }) => (
+        <FormItem>
+          {label && (
+            <FormLabel required={required} tooltip={tooltip}>
+              {label}
+            </FormLabel>
+          )}
           {description && <FormDescription>{description}</FormDescription>}
+          <FormControl>
+            <RadioGroup value={field.value ?? ""} onValueChange={field.onChange} onBlur={field.onBlur}>
+              {options.map((option) => {
+                const itemId = `${field.name}-${option.value}`;
+                return (
+                  <div key={option.value} className="flex items-center gap-2">
+                    <RadioGroupItem id={itemId} value={option.value} disabled={option.disabled} />
+                    <Label htmlFor={itemId} className="type-text-sm font-normal">
+                      {option.label}
+                    </Label>
+                  </div>
+                );
+              })}
+            </RadioGroup>
+          </FormControl>
           <FormMessage />
         </FormItem>
       )}
@@ -325,8 +377,116 @@ function SelectField<TFieldValues extends FieldValues, TName extends FieldPath<T
   );
 }
 
+interface ChecklistFieldProps<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>
+  extends FormFieldBaseProps<TFieldValues, TName> {
+  options: SelectFieldOption[];
+}
+
+function ChecklistField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>({
+  control,
+  name,
+  rules,
+  required,
+  label,
+  description,
+  tooltip,
+  options,
+}: ChecklistFieldProps<TFieldValues, TName>) {
+  return (
+    <FormField
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field }) => {
+        const selected: string[] = Array.isArray(field.value) ? field.value : [];
+        const toggle = (value: string, checked: boolean) => {
+          if (checked) {
+            field.onChange([...selected, value]);
+          } else {
+            field.onChange(selected.filter((existing) => existing !== value));
+          }
+        };
+        return (
+          <FormItem>
+            {label && (
+              <FormLabel required={required} tooltip={tooltip}>
+                {label}
+              </FormLabel>
+            )}
+            {description && <FormDescription>{description}</FormDescription>}
+            <FormControl>
+              <fieldset className="m-0 flex flex-col gap-2 border-0 p-0" onBlur={field.onBlur}>
+                {options.map((option) => {
+                  const itemId = `${field.name}-${option.value}`;
+                  const checked = selected.includes(option.value);
+                  return (
+                    <div key={option.value} className="flex items-start gap-2">
+                      <Checkbox
+                        id={itemId}
+                        checked={checked}
+                        onCheckedChange={(next) => toggle(option.value, Boolean(next))}
+                        disabled={option.disabled}
+                      />
+                      <Label htmlFor={itemId} className="type-text-sm font-normal leading-tight">
+                        {option.label}
+                      </Label>
+                    </div>
+                  );
+                })}
+              </fieldset>
+            </FormControl>
+            <FormMessage />
+          </FormItem>
+        );
+      }}
+    />
+  );
+}
+
+interface CheckboxFieldProps<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>
+  extends Omit<FormFieldBaseProps<TFieldValues, TName>, "required"> {}
+
+function CheckboxField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>({
+  control,
+  name,
+  rules,
+  label,
+  description,
+  tooltip,
+}: CheckboxFieldProps<TFieldValues, TName>) {
+  return (
+    <FormField
+      control={control}
+      name={name}
+      rules={rules}
+      render={({ field }) => (
+        <FormItem className="gap-1.5">
+          <div className="flex items-start gap-2">
+            <FormControl>
+              <Checkbox
+                checked={field.value ?? false}
+                onCheckedChange={(next) => field.onChange(Boolean(next))}
+                onBlur={field.onBlur}
+              />
+            </FormControl>
+            {label && (
+              <FormLabel tooltip={tooltip} className="font-normal">
+                {label}
+              </FormLabel>
+            )}
+          </div>
+          {description && <FormDescription className="ml-6">{description}</FormDescription>}
+          <FormMessage className="ml-6" />
+        </FormItem>
+      )}
+    />
+  );
+}
+
 export type { SelectFieldOption };
 export {
+  CheckboxField,
+  ChecklistField,
   Form,
   FormControl,
   FormDescription,
@@ -337,6 +497,7 @@ export {
   FormLabel,
   FormMessage,
   InputField,
+  RadioField,
   SelectField,
   TextareaField,
   useFormField,

package/src/components/github-button.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import type { ComponentProps } from "react";
+
+import { cn } from "../lib/cn";
+import { Button } from "./button";
+
+const GITHUB_ICON_PATH =
+  "M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12";
+
+function GitHubIcon() {
+  return (
+    <svg fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+      <path d={GITHUB_ICON_PATH} />
+    </svg>
+  );
+}
+
+type GitHubButtonProps = Omit<ComponentProps<typeof Button>, "variant" | "icon">;
+
+function GitHubButton({ className, children, ...props }: GitHubButtonProps) {
+  return (
+    <Button
+      {...props}
+      icon={<GitHubIcon />}
+      className={cn("bg-foreground text-background [@media(hover:hover)]:hover:bg-foreground/90", className)}
+    >
+      {children}
+    </Button>
+  );
+}
+
+export type { GitHubButtonProps };
+export { GitHubButton };

package/src/components/page-loader.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { cn } from "../lib/cn";
+
+const CABLE_CAR_SVG = (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 120 130"
+    width="240"
+    height="260"
+    aria-hidden="true"
+    className="block h-auto w-full"
+  >
+    <line x1="60" y1="3" x2="60" y2="58" stroke="#333" strokeWidth="4" />
+    <circle cx="60" cy="11" r="10" fill="#555" />
+    <rect x="5" y="58" width="110" height="64" rx="4" fill="#e90060" />
+    <rect x="5" y="58" width="110" height="20" rx="4" fill="#F5F0E8" />
+    <rect x="5" y="68" width="110" height="10" fill="#F5F0E8" />
+    <rect x="14" y="66" width="26" height="30" rx="2" fill="#5B8EC9" stroke="#C4B9A8" strokeWidth="1.5" />
+    <rect x="47" y="66" width="26" height="30" rx="2" fill="#5B8EC9" stroke="#C4B9A8" strokeWidth="1.5" />
+    <rect x="80" y="66" width="26" height="30" rx="2" fill="#5B8EC9" stroke="#C4B9A8" strokeWidth="1.5" />
+    <rect x="5" y="115" width="110" height="7" rx="3" fill="#9f0042" />
+  </svg>
+);
+
+interface PageLoaderProps {
+  className?: string;
+}
+
+function PageLoader({ className }: PageLoaderProps) {
+  return (
+    <div
+      className={cn("flex min-h-screen items-center justify-center bg-background", className)}
+      role="status"
+      aria-label="Loading Alpic…"
+    >
+      <div className="relative h-[120px] w-[200px]">
+        <div
+          className="absolute top-[30px] left-0 h-[3px] w-full rounded-sm bg-[#6c6c77]"
+          style={{ transform: "rotate(-15deg)", transformOrigin: "left center" }}
+        />
+        <div className="absolute top-[33px] -left-[45px] w-[45px] motion-safe:animate-[alpic-ride_4s_linear_infinite]">
+          {CABLE_CAR_SVG}
+        </div>
+        <div
+          className="pointer-events-none absolute -top-[40px] -left-[45px] z-10 h-[200px] w-[95px]"
+          style={{ background: "linear-gradient(to right, var(--color-background) 47%, transparent)" }}
+        />
+        <div
+          className="pointer-events-none absolute -top-[40px] left-[142px] z-10 h-[200px] w-[95px]"
+          style={{ background: "linear-gradient(to right, transparent, var(--color-background) 53%)" }}
+        />
+      </div>
+    </div>
+  );
+}
+
+export type { PageLoaderProps };
+export { PageLoader };

package/src/components/shimmer-text.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import type React from "react";
+
+import { cn } from "../lib/cn";
+
+const shimmerStyle: React.CSSProperties = {
+  background: `linear-gradient(90deg, #0000 calc(50% - 60px), var(--color-foreground), #0000 calc(50% + 60px)), linear-gradient(color-mix(in oklab, var(--color-muted-foreground) 70%, transparent), color-mix(in oklab, var(--color-muted-foreground) 70%, transparent))`,
+  backgroundSize: "250% 100%, auto",
+  backgroundRepeat: "no-repeat, padding-box",
+  WebkitBackgroundClip: "text",
+  WebkitTextFillColor: "transparent",
+  backgroundClip: "text",
+  animation: "shimmer-text 2.5s linear infinite",
+};
+
+export function ShimmerText({ children, className }: { children: string | number; className?: string }) {
+  return (
+    <span className={cn(className)} style={shimmerStyle}>
+      {children}
+    </span>
+  );
+}

package/src/components/sidebar.tsx

@@ -2,7 +2,6 @@
 
 import { Slot } from "@radix-ui/react-slot";
 import { cva, type VariantProps } from "class-variance-authority";
-import { PanelLeftClose, PanelLeftOpen } from "lucide-react";
 import * as React from "react";
 
 import { useIsMobile } from "../hooks/use-mobile";
@@ -20,6 +19,19 @@ const SIDEBAR_WIDTH_MOBILE = "16rem";
 const SIDEBAR_WIDTH_ICON = "3.5rem";
 const SIDEBAR_KEYBOARD_SHORTCUT = "b";
 
+const INTERACTIVE_SIDEBAR_ELEMENT_SELECTOR = [
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "[role='button']",
+  "[role='link']",
+  "[role='menuitem']",
+  "[contenteditable='true']",
+  "[tabindex]:not([tabindex='-1'])",
+].join(", ");
+
 type SidebarContextProps = {
   state: "expanded" | "collapsed";
   open: boolean;
@@ -143,13 +155,31 @@ function Sidebar({
   variant?: "sidebar" | "floating" | "inset";
   collapsible?: "offcanvas" | "icon" | "none";
 }) {
-  const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
+  const { isMobile, state, openMobile, setOpenMobile, open, setOpen } = useSidebar();
+
+  function handleSurfaceClickCapture(event: React.MouseEvent<HTMLDivElement>) {
+    const clickedInteractiveElement =
+      event.target instanceof Element && event.target.closest(INTERACTIVE_SIDEBAR_ELEMENT_SELECTOR);
+
+    if (clickedInteractiveElement) {
+      return;
+    }
+
+    if (!open) {
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(true);
+      return;
+    }
+
+    setOpen(false);
+  }
 
   if (collapsible === "none") {
     return (
       <div
         data-slot="sidebar"
-        className={cn("bg-sidebar text-sidebar-foreground flex h-full w-(--sidebar-width) flex-col", className)}
+        className={cn("bg-sidebar-surface text-sidebar-foreground flex h-full w-(--sidebar-width) flex-col", className)}
         {...props}
       >
         {children}
@@ -164,7 +194,7 @@ function Sidebar({
           data-sidebar="sidebar"
           data-slot="sidebar"
           data-mobile="true"
-          className="bg-sidebar text-sidebar-foreground w-(--sidebar-width) p-0 [&>button]:hidden"
+          className="bg-sidebar-surface text-sidebar-foreground w-(--sidebar-width) p-0 [&>button]:hidden"
           style={
             {
               "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
@@ -213,7 +243,7 @@ function Sidebar({
           // Adjust the padding for floating and inset variants.
           variant === "floating" || variant === "inset"
             ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
-            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+            : "border-sidebar-border group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
           className,
         )}
         {...props}
@@ -221,7 +251,8 @@ function Sidebar({
         <div
           data-sidebar="sidebar"
           data-slot="sidebar-inner"
-          className="bg-sidebar group-data-[variant=floating]:border-sidebar-border flex h-full w-full flex-col group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:shadow-sm"
+          className="bg-sidebar-surface group-data-[variant=floating]:border-sidebar-border flex h-full w-full cursor-pointer flex-col group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:shadow-sm"
+          onClickCapture={handleSurfaceClickCapture}
         >
           {children}
         </div>
@@ -231,9 +262,7 @@ function Sidebar({
 }
 
 function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<typeof Button>) {
-  const { state, isMobile, openMobile, toggleSidebar } = useSidebar();
-
-  const isOpen = isMobile ? openMobile : state === "expanded";
+  const { toggleSidebar } = useSidebar();
 
   return (
     <Button
@@ -248,12 +277,21 @@ function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<t
       }}
       {...props}
     >
-      {isOpen ? <PanelLeftClose className="size-4.5" /> : <PanelLeftOpen className="size-4.5" />}
+      <SidebarToggleIcon className="size-4.5" />
       <span className="sr-only">Toggle Sidebar</span>
     </Button>
   );
 }
 
+function SidebarToggleIcon({ className, ...props }: React.ComponentProps<"svg">) {
+  return (
+    <svg viewBox="0 0 20 20" fill="none" aria-hidden="true" className={className} {...props}>
+      <rect x="2.75" y="2.75" width="14.5" height="14.5" rx="4" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M10 4.75V15.25" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  );
+}
+
 function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
   const { toggleSidebar } = useSidebar();
 
@@ -266,9 +304,7 @@ function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
       onClick={toggleSidebar}
       title="Toggle Sidebar"
       className={cn(
-        "[@media(hover:hover)]:hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] sm:flex",
-        "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
-        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+        "absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] sm:flex",
         "[@media(hover:hover)]:hover:group-data-[collapsible=offcanvas]:bg-sidebar group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full",
         "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
         "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
@@ -316,16 +352,19 @@ function SidebarHeader({ className, icon, title, children, ...props }: SidebarHe
     <div
       data-slot="sidebar-header"
       data-sidebar="header"
-      className={cn("flex flex-col gap-2 p-2", className)}
+      className={cn("flex flex-col gap-2 py-2", className)}
       {...props}
     >
       <div className="flex h-8 items-center gap-2 px-3">
-        <div className="relative shrink-0">
-          <span className="transition-opacity group-data-[collapsible=icon]:group-hover:opacity-0">{icon}</span>
-          <div className="absolute inset-0 flex items-center justify-center opacity-0 transition-opacity group-data-[collapsible=icon]:group-hover:opacity-100">
-            <SidebarTrigger />
-          </div>
-        </div>
+        <span className="relative flex size-8 shrink-0 items-center justify-center">
+          <span className="transition-opacity duration-200 group-data-[collapsible=icon]:group-hover:opacity-0">
+            {icon}
+          </span>
+          <SidebarTrigger
+            tabIndex={-1}
+            className="absolute inset-0 opacity-0 transition-opacity duration-200 group-data-[collapsible=icon]:group-hover:opacity-100"
+          />
+        </span>
         <span className="text-foreground text-md min-w-0 truncate font-medium group-data-[collapsible=icon]:hidden">
           {title}
         </span>

package/src/components/table.tsx

@@ -44,7 +44,6 @@ function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
         "border-b border-border-secondary transition-colors",
         "data-[state=selected]:bg-muted",
         "[@media(hover:hover)]:hover:bg-background-hover dark:[@media(hover:hover)]:hover:bg-muted",
-        "[@media(hover:hover)]:[&:hover_button:hover]:bg-subtle",
         className,
       )}
       {...props}
@@ -58,7 +57,7 @@ function TableHead({ className, ...props }: React.ComponentProps<"th">) {
       data-slot="table-head"
       className={cn(
         "h-11 px-6 py-3 bg-muted text-left align-middle type-text-xs font-semibold text-placeholder dark:text-subtle-foreground whitespace-nowrap",
-        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:pr-3",
+        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:px-0",
         className,
       )}
       {...props}
@@ -66,11 +65,25 @@ function TableHead({ className, ...props }: React.ComponentProps<"th">) {
   );
 }
 
-function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+interface TableCellProps extends React.ComponentProps<"td"> {
+  /**
+   * When true, the cell renders edge-to-edge so the child can act as the
+   * interactive surface (e.g. a button or popover trigger filling the cell).
+   * Defaults to false (standard padded cell).
+   */
+  interactive?: boolean;
+}
+
+function TableCell({ className, interactive = false, ...props }: TableCellProps) {
   return (
     <td
       data-slot="table-cell"
-      className={cn("px-6 py-2 align-middle", "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:pr-3", className)}
+      className={cn(
+        "align-middle",
+        interactive ? "h-px p-0" : "px-6 py-2",
+        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:px-0",
+        className,
+      )}
       {...props}
     />
   );

package/src/components/tabs.tsx

@@ -44,10 +44,10 @@ const tabsTriggerVariants = cva(
           "data-[state=active]:border-b-2 data-[state=active]:border-foreground data-[state=active]:text-foreground",
         ],
         pill: [
-          "rounded-lg px-4 py-2",
-          "text-muted-foreground",
-          "[@media(hover:hover)]:hover:bg-accent [@media(hover:hover)]:hover:text-accent-foreground",
-          "data-[state=active]:bg-accent data-[state=active]:text-accent-foreground",
+          "rounded-md px-2 py-1.5",
+          "text-quaternary-foreground",
+          "[@media(hover:hover)]:hover:bg-accent [@media(hover:hover)]:hover:text-muted-foreground",
+          "data-[state=active]:bg-accent data-[state=active]:text-muted-foreground",
         ],
       },
     },

package/src/components/task-progress.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+/*
+ * TaskProgress — multi-step async progress primitive.
+ *
+ * Dumb component: the consumer owns orchestration (timer, websocket, polling) and
+ * passes `steps` with each step's status. Renders a percentage bar at the top
+ * and one row per step with done/running/pending state badges.
+ *
+ * `trailingLabel` is for "still working on something not in the step list" —
+ * shows after the last step as a running row that isn't counted in the percent.
+ */
+
+import { CheckIcon } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { Separator } from "./separator";
+
+type TaskProgressStatus = "pending" | "running" | "done";
+
+interface TaskProgressStep {
+  id: string;
+  label: string;
+  status: TaskProgressStatus;
+}
+
+interface TaskProgressProps extends Omit<React.ComponentProps<"div">, "children"> {
+  steps: readonly TaskProgressStep[];
+  trailingLabel?: string;
+  /**
+   * Optional mount-time stagger: each row fades + slides in with `animation-delay = index × stepRevealDelayMs`.
+   * Pure CSS, runs once on mount. Omit for no animation.
+   */
+  stepRevealDelayMs?: number;
+}
+
+const REVEAL_CLASSES = "animate-in fade-in slide-in-from-bottom-2 duration-300";
+
+function TaskProgress({ steps, trailingLabel, stepRevealDelayMs, className, ...props }: TaskProgressProps) {
+  const total = steps.length;
+  const doneCount = steps.filter((step) => step.status === "done").length;
+  const percent = total > 0 ? Math.round((doneCount / total) * 100) : 0;
+  const stagger = stepRevealDelayMs != null;
+
+  return (
+    <div className={cn("flex flex-col gap-4", className)} {...props}>
+      <div className="bg-muted h-2 w-full overflow-hidden rounded-full">
+        <div className="h-full rounded-full bg-success transition-all duration-500" style={{ width: `${percent}%` }} />
+      </div>
+      <div>
+        {steps.map((step, idx) => (
+          <div
+            key={step.id}
+            className={stagger ? REVEAL_CLASSES : undefined}
+            style={
+              stagger ? { animationDelay: `${idx * (stepRevealDelayMs ?? 0)}ms`, animationFillMode: "both" } : undefined
+            }
+          >
+            <TaskProgressRow label={step.label} status={step.status} />
+            {idx < steps.length - 1 && <Separator />}
+          </div>
+        ))}
+        {trailingLabel && (
+          <div className={stagger ? REVEAL_CLASSES : undefined}>
+            <Separator />
+            <TaskProgressRow label={trailingLabel} status="running" muted />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface TaskProgressRowProps {
+  label: string;
+  status: TaskProgressStatus;
+  muted?: boolean;
+}
+
+function TaskProgressRow({ label, status, muted }: TaskProgressRowProps) {
+  return (
+    <div className="flex items-center justify-between py-2">
+      <span className={cn("type-text-sm", muted && "text-muted-foreground")}>{label}</span>
+      {status === "done" && (
+        <span className="flex items-center gap-1 type-text-sm text-success">
+          <CheckIcon className="size-3.5" />
+          <span>done</span>
+        </span>
+      )}
+      {status === "running" && (
+        <span className="flex items-center gap-1.5 type-text-sm text-warning">
+          <span className="size-2 rounded-full bg-warning" />
+          <span>running…</span>
+        </span>
+      )}
+      {status === "pending" && (
+        <span className="flex items-center gap-1.5 type-text-sm text-muted-foreground">
+          <span className="size-2 rounded-full border border-muted-foreground" />
+          <span>pending</span>
+        </span>
+      )}
+    </div>
+  );
+}
+
+export type { TaskProgressStatus, TaskProgressStep };
+export { TaskProgress };