@smicolon/fasla-ui 0.5.1 → 0.7.0

package/registry/blocks/how-it-works-photo-bento-steps/HowItWorksPhotoBentoSteps.tsx

@@ -0,0 +1,178 @@
+"use client"
+
+import * as React from "react"
+import {
+  enter,
+  HowItWorksHeader,
+  HowItWorksImage,
+  HowItWorksLtr,
+  HowItWorksScrim,
+  HowItWorksSection,
+  revealTargets,
+  useRevealOnEnter,
+  type HowItWorksLocale,
+  type HowItWorksPhoto,
+} from "../how-it-works/how-it-works"
+
+/*
+ * Figma: `How it Works` (42334:294272), Type=Photo Bento Steps.
+ *
+ * A left-aligned header, then a bento: one large photo card for the long first
+ * step (a numeral, a title and a line at its foot, on a dark scrim), and three
+ * small cards for the quick steps that follow, each a thumbnail beside a
+ * number, a title and a line. The feature card's scrim is a stack of flat
+ * `base-black` layers and its text `base-white`, the same in Light and in Dark.
+ *
+ * Desktop sets the feature card 616px wide beside a column of the small cards.
+ * Tablet puts the feature card full width above the small cards, three across
+ * with their thumbnails on top. Mobile keeps the feature card at 320px tall and
+ * turns each small card into a full-width row with a 96px thumbnail. The page's
+ * `dir` swaps the sides and the thumbnail's side in each row.
+ *
+ * Motion plays once, when the block comes into view: the feature card opens
+ * from its start edge (520ms) while its photo settles from 105% to 100%, then
+ * the small cards rise 14px, 70ms apart. Hovering a small card raises its shadow
+ * from `sm` to `md` and slides its thumbnail 4px (200ms). Under reduced motion
+ * the block is its finished state. Figma's Mobile fades the feature card in
+ * instead of opening it; here it opens at every width.
+ *
+ * Content limits: the heading up to 40 characters, the line up to 70. The
+ * feature card's title up to 56 characters and its line up to 150; a small
+ * card's title up to 26 and its line up to 50.
+ */
+
+export interface HowItWorksBentoStep {
+  /** Keys the step. */
+  id: string
+  title: React.ReactNode
+  description: React.ReactNode
+}
+
+export interface HowItWorksPhotoBentoStepsCopy {
+  eyebrow: React.ReactNode
+  /** The heading, an `h2`. */
+  heading: React.ReactNode
+  description: React.ReactNode
+  /** The long first step, on the feature card. */
+  feature: HowItWorksBentoStep
+  /** The quick steps after it, on the small cards. The numbers carry on from 02. */
+  steps: HowItWorksBentoStep[]
+}
+
+/** Figma's copy, English and Arabic. */
+const COPY: Record<HowItWorksLocale, HowItWorksPhotoBentoStepsCopy> = {
+  en: {
+    eyebrow: "How it works",
+    heading: "One long step, then three short ones",
+    description: "The first step takes a week. The three after it take a day each.",
+    feature: {
+      id: "sketch",
+      title: "Sketch the entire flow before opening the design file",
+      description: "Every screen, at low fidelity, in order. It is the one step where being fast matters more than being neat — and it is where most of the thinking happens.",
+    },
+    steps: [
+      { id: "cluster", title: "Cluster the research", description: "Notes grouped until the themes appear." },
+      { id: "design", title: "Design on a shared grid", description: "Real layouts carrying real content." },
+      { id: "handover", title: "Hand over to build", description: "Straight into the codebase, reasoning included." },
+    ],
+  },
+  ar: {
+    eyebrow: "كيف نعمل",
+    heading: "خطوة طويلة واحدة، ثم ثلاث قصيرة",
+    description: "الخطوة الأولى تستغرق أسبوعًا، والثلاث التي تليها يومًا لكل واحدة.",
+    feature: {
+      id: "sketch",
+      title: "ارسم المسار كاملًا قبل فتح ملف التصميم",
+      description: "كل شاشة، بدقة منخفضة، بالترتيب. هي الخطوة الوحيدة التي تُهمّ فيها السرعة أكثر من الإتقان، وفيها يحدث معظم التفكير.",
+    },
+    steps: [
+      { id: "cluster", title: "اجمع نتائج البحث", description: "ملاحظات مجمّعة حتى تظهر المحاور." },
+      { id: "design", title: "صمّم على شبكة مشتركة", description: "تخطيطات حقيقية تحمل محتوى حقيقيًا." },
+      { id: "handover", title: "سلّم إلى التنفيذ", description: "مباشرة إلى قاعدة الكود، مع المبرّرات." },
+    ],
+  },
+}
+
+export interface HowItWorksPhotoBentoStepsProps extends Omit<React.HTMLAttributes<HTMLElement>, "title">, Partial<HowItWorksPhotoBentoStepsCopy> {
+  /** Which language the default copy is in. The page's `dir` sets the direction. */
+  locale?: HowItWorksLocale
+  /**
+   * The photos, in order: the feature card's, then each small card's. A card
+   * without one shows a `muted` box.
+   * @default none: `muted` placeholders
+   */
+  photos?: HowItWorksPhoto[]
+}
+
+export function HowItWorksPhotoBentoSteps({ locale = "en", eyebrow, heading, description, feature, steps, photos, className, ...props }: HowItWorksPhotoBentoStepsProps) {
+  const copy = COPY[locale]
+  const headingId = React.useId()
+  const rootRef = React.useRef<HTMLElement>(null)
+  const big = feature ?? copy.feature
+  const small = steps ?? copy.steps
+
+  useRevealOnEnter(rootRef, (node) => {
+    const started: Animation[] = []
+    const rtl = getComputedStyle(node).direction === "rtl"
+    revealTargets(node, "feature").forEach((card) => {
+      started.push(enter(card, [{ clipPath: rtl ? "inset(0 0 0 100%)" : "inset(0 100% 0 0)" }, { clipPath: "inset(0 0 0 0)" }], { duration: 520, easing: "cubic-bezier(0.16, 1, 0.3, 1)" }))
+      const photo = card.querySelector<HTMLElement>('[data-reveal="feature-photo"]')
+      if (photo) started.push(enter(photo, [{ transform: "scale(1.05)" }, { transform: "scale(1)" }], { duration: 520 }))
+    })
+    revealTargets(node, "card").forEach((card, index) =>
+      started.push(enter(card, [{ opacity: 0, transform: "translateY(14px)" }, { opacity: 1, transform: "none" }], { duration: 400, delay: 450 + index * 70 }))
+    )
+    return started
+  })
+
+  return (
+    <HowItWorksSection ref={rootRef} labelledBy={headingId} className={className} {...props}>
+      <HowItWorksHeader headingId={headingId} eyebrow={eyebrow ?? copy.eyebrow} heading={heading ?? copy.heading} description={description ?? copy.description} headingClassName="text-2xl [@container(min-width:40rem)]:text-4xl [@container(min-width:64rem)]:text-4xl" descriptionClassName="max-w-none" />
+
+      <div className="flex flex-col gap-6 [@container(min-width:64rem)]:flex-row">
+        <article data-reveal="feature" className="group relative flex h-80 min-w-0 flex-col justify-end overflow-hidden rounded-[10px] bg-muted p-6 [@container(min-width:40rem)]:h-[400px] [@container(min-width:64rem)]:h-[520px] [@container(min-width:64rem)]:w-[616px] [@container(min-width:64rem)]:shrink-0">
+          <div data-reveal="feature-photo" className="absolute inset-0">
+            <HowItWorksImage photo={photos?.[0]} />
+          </div>
+          <HowItWorksScrim className="[&>span:first-child]:group-hover:bg-base-black/[0.28]" />
+          <div className="relative flex flex-col gap-2 text-base-white">
+            <span className="text-4xl font-semibold leading-none [@container(min-width:40rem)]:text-5xl">
+              <HowItWorksLtr>01</HowItWorksLtr>
+            </span>
+            <h3 className="text-lg font-semibold [@container(min-width:40rem)]:text-xl">{big.title}</h3>
+            <p className="max-w-[568px] text-sm text-base-white/85">{big.description}</p>
+          </div>
+        </article>
+
+        <ol className="grid min-w-0 flex-1 grid-cols-1 gap-4 [@container(min-width:40rem)]:grid-cols-3 [@container(min-width:40rem)]:gap-6 [@container(min-width:64rem)]:grid-cols-1">
+          {small.map((step, index) => (
+            <li
+              key={step.id}
+              data-reveal="card"
+              className="group flex gap-4 rounded-[10px] border border-border bg-card p-4 shadow-sm transition-shadow duration-200 hover:shadow-md motion-reduce:transition-none [@container(min-width:40rem)]:flex-col [@container(min-width:64rem)]:flex-row"
+            >
+              <div className="relative size-24 shrink-0 overflow-hidden rounded-lg bg-muted [@container(min-width:40rem)]:h-[123px] [@container(min-width:40rem)]:w-full [@container(min-width:64rem)]:w-[168px]">
+                <div className="absolute inset-0 transition-transform duration-200 group-hover:translate-x-1 group-hover:[&:dir(rtl)]:-translate-x-1 motion-reduce:transition-none group-hover:motion-reduce:translate-x-0">
+                  <HowItWorksImage photo={photos?.[index + 1]} className="scale-110" />
+                </div>
+              </div>
+              <div className="flex min-w-0 flex-1 flex-col justify-center gap-1">
+                <span className="text-xs font-medium text-primary">
+                  <HowItWorksLtr>{String(index + 2).padStart(2, "0")}</HowItWorksLtr>
+                </span>
+                <h3 className="text-base font-medium text-foreground">{step.title}</h3>
+                <p className="text-sm text-muted-foreground">{step.description}</p>
+              </div>
+            </li>
+          ))}
+        </ol>
+      </div>
+    </HowItWorksSection>
+  )
+}
+
+/**
+ * The default copy, English and Arabic, as `locale` picks it. Spread it to
+ * change a few strings and keep the rest.
+ */
+export const howItWorksPhotoBentoStepsCopy = COPY

package/registry/blocks/how-it-works-photo-bento-steps/index.ts

@@ -0,0 +1,7 @@
+export {
+  HowItWorksPhotoBentoSteps,
+  howItWorksPhotoBentoStepsCopy,
+  type HowItWorksBentoStep,
+  type HowItWorksPhotoBentoStepsCopy,
+  type HowItWorksPhotoBentoStepsProps,
+} from "./HowItWorksPhotoBentoSteps"

package/registry/blocks/how-it-works-photo-rail-progress/HowItWorksPhotoRailProgress.tsx

@@ -0,0 +1,231 @@
+"use client"
+
+import * as React from "react"
+import { ArrowLeft, ArrowRight } from "lucide-react"
+import { Badge } from "../../ui/badge/badge"
+import { Button } from "../../ui/button/button"
+import { Carousel, CarouselContent, CarouselItem, useCarousel } from "../../ui/carousel/carousel"
+import { Progress } from "../../ui/progress/progress"
+import {
+  enter,
+  HowItWorksHeader,
+  HowItWorksImage,
+  HowItWorksLtr,
+  HowItWorksSection,
+  revealTargets,
+  useRevealOnEnter,
+  type HowItWorksLocale,
+  type HowItWorksPhoto,
+} from "../how-it-works/how-it-works"
+
+/*
+ * Figma: `How it Works` (42334:294272), Type=Photo Rail + Progress.
+ *
+ * A header (an eyebrow, the heading) with two round arrow buttons at its end,
+ * a rail of four step cards (a 380 × 264 photo with a number badge, a title and
+ * a line), and a progress bar under it with a "01 / 04" count. The rail is the
+ * Carousel atom: a real scroll-snap scroller, so touch, trackpad and the arrow
+ * keys all move it. The rail runs out to the edge of the block, so the next card
+ * peeks past the content, which is the only cue that it scrolls.
+ *
+ * Desktop shows about three and a third cards (380px), Tablet 300px cards and
+ * Mobile 260px, the arrows moving under the heading on Tablet and going away on
+ * Mobile, where swiping is the control. The progress bar and the count follow
+ * where the rail is scrolled, continuously, from the first card to the last.
+ * The page's `dir` mirrors the rail, the bar (it fills from the start) and the
+ * arrows, whose glyphs turn with it, so Next is on the left in Arabic.
+ *
+ * Motion: the cards rise 12px and fade in once, 90ms apart, when the block comes
+ * into view. The browser's own scroll-snap moves the rail: Figma's card has a
+ * spring with momentum, and it dims cards outside the view to 55% and lifts
+ * them as they enter; the code has neither, so cards stay full strength.
+ * Under reduced motion the block is its finished state and the rail jumps.
+ *
+ * Content limits: the heading up to 46 characters. A card's title up to 18
+ * characters and its line up to 56.
+ */
+
+export interface HowItWorksRailStep {
+  /** Keys the card. */
+  id: string
+  title: React.ReactNode
+  description: React.ReactNode
+}
+
+export interface HowItWorksPhotoRailProgressCopy {
+  eyebrow: React.ReactNode
+  /** The heading, an `h2`. */
+  heading: React.ReactNode
+  /** The cards, in order. The numbers are drawn from 01. */
+  steps: HowItWorksRailStep[]
+  /** The rail's accessible name, such as "Steps". */
+  railLabel: string
+  /** The two arrows' accessible names. */
+  previousLabel: string
+  nextLabel: string
+  /** The progress bar's accessible name. */
+  progressLabel: string
+}
+
+/** Figma's copy, English and Arabic. */
+const COPY: Record<HowItWorksLocale, HowItWorksPhotoRailProgressCopy> = {
+  en: {
+    eyebrow: "Step by step",
+    heading: "Walk the whole process, one step at a time",
+    steps: [
+      { id: "align", title: "Align", description: "One room, one hour, every assumption written down." },
+      { id: "cluster", title: "Cluster", description: "Research notes grouped until the themes appear." },
+      { id: "design", title: "Design", description: "Screens built in the open on a shared board." },
+      { id: "build", title: "Build", description: "Handover straight into the codebase." },
+    ],
+    railLabel: "Steps",
+    previousLabel: "Previous step",
+    nextLabel: "Next step",
+    progressLabel: "Progress through the steps",
+  },
+  ar: {
+    eyebrow: "خطوة بخطوة",
+    heading: "اسلك العملية كاملة، خطوة بعد خطوة",
+    steps: [
+      { id: "align", title: "المواءمة", description: "غرفة واحدة، ساعة واحدة، وكل افتراض مكتوب." },
+      { id: "cluster", title: "التجميع", description: "ملاحظات البحث مجمّعة حتى تظهر المحاور." },
+      { id: "design", title: "التصميم", description: "شاشات تُبنى على المكشوف على لوح مشترك." },
+      { id: "build", title: "البناء", description: "تسليم مباشر إلى قاعدة الكود." },
+    ],
+    railLabel: "الخطوات",
+    previousLabel: "الخطوة السابقة",
+    nextLabel: "الخطوة التالية",
+    progressLabel: "التقدّم عبر الخطوات",
+  },
+}
+
+/** The two arrows. They sit inside the Carousel, which owns where the rail is. */
+function RailArrows({ previousLabel, nextLabel, className }: { previousLabel: string; nextLabel: string; className?: string }) {
+  const { activeIndex, lastIndex, scrollTo } = useCarousel()
+  const arrow = "[&:dir(rtl)]:-scale-x-100"
+  return (
+    <div className={className}>
+      <Button type="button" variant="outline" tone="secondary" size="icon-md" radius="rounded" aria-label={previousLabel} disabled={activeIndex <= 0} onClick={() => scrollTo(activeIndex - 1)}>
+        <ArrowLeft aria-hidden className={arrow} />
+      </Button>
+      <Button type="button" variant="outline" tone="secondary" size="icon-md" radius="rounded" aria-label={nextLabel} disabled={activeIndex >= lastIndex} onClick={() => scrollTo(activeIndex + 1)}>
+        <ArrowRight aria-hidden className={arrow} />
+      </Button>
+    </div>
+  )
+}
+
+/**
+ * How far the rail is scrolled, from 0 at the first card to 1 at the last, read
+ * from the scroller itself so a swipe, a key press and a button all move it. In
+ * Arabic the scroll position runs negative, so its size is what counts.
+ */
+function useRailFraction(track: React.RefObject<HTMLDivElement | null>) {
+  const [fraction, setFraction] = React.useState(0)
+  React.useEffect(() => {
+    const node = track.current
+    if (!node) return
+    let frame = 0
+    const read = () => {
+      const max = node.scrollWidth - node.clientWidth
+      setFraction(max > 0 ? Math.min(1, Math.abs(node.scrollLeft) / max) : 0)
+    }
+    const onScroll = () => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(read)
+    }
+    read()
+    node.addEventListener("scroll", onScroll, { passive: true })
+    window.addEventListener("resize", onScroll)
+    return () => {
+      cancelAnimationFrame(frame)
+      node.removeEventListener("scroll", onScroll)
+      window.removeEventListener("resize", onScroll)
+    }
+  }, [track])
+  return fraction
+}
+
+export interface HowItWorksPhotoRailProgressProps extends Omit<React.HTMLAttributes<HTMLElement>, "title">, Partial<HowItWorksPhotoRailProgressCopy> {
+  /** Which language the default copy is in. The page's `dir` sets the direction. */
+  locale?: HowItWorksLocale
+  /**
+   * One photo per card, in order. A card without one shows a `muted` box.
+   * @default none: `muted` placeholders
+   */
+  photos?: HowItWorksPhoto[]
+}
+
+export function HowItWorksPhotoRailProgress({ locale = "en", eyebrow, heading, steps, railLabel, previousLabel, nextLabel, progressLabel, photos, className, ...props }: HowItWorksPhotoRailProgressProps) {
+  const copy = COPY[locale]
+  const headingId = React.useId()
+  const rootRef = React.useRef<HTMLElement>(null)
+  const trackRef = React.useRef<HTMLDivElement>(null)
+  const list = steps ?? copy.steps
+  const fraction = useRailFraction(trackRef)
+  const count = list.length
+  const current = Math.round(1 + fraction * (count - 1))
+  const value = ((1 + fraction * (count - 1)) / count) * 100
+
+  useRevealOnEnter(rootRef, (node) =>
+    revealTargets(node, "card").map((card, index) =>
+      enter(card, [{ opacity: 0, transform: "translateY(12px)" }, { opacity: 1, transform: "none" }], { duration: 450, delay: index * 90 })
+    )
+  )
+
+  const arrows = (
+    <RailArrows previousLabel={previousLabel ?? copy.previousLabel} nextLabel={nextLabel ?? copy.nextLabel} className="hidden shrink-0 gap-2 [@container(min-width:40rem)]:flex" />
+  )
+  return (
+    <HowItWorksSection ref={rootRef} labelledBy={headingId} className={className} {...props}>
+      <Carousel aria-label={railLabel ?? copy.railLabel} className="flex flex-col gap-8">
+        <div className="flex flex-col gap-6 [@container(min-width:64rem)]:flex-row [@container(min-width:64rem)]:items-center [@container(min-width:64rem)]:justify-between [@container(min-width:64rem)]:gap-24">
+          <HowItWorksHeader
+            headingId={headingId}
+            eyebrow={eyebrow ?? copy.eyebrow}
+            heading={heading ?? copy.heading}
+            headingClassName="text-2xl [@container(min-width:40rem)]:text-3xl [@container(min-width:64rem)]:text-4xl"
+          />
+          {arrows}
+        </div>
+
+        <CarouselContent
+          ref={trackRef}
+          className="-me-8 gap-6 pe-8 md:-me-16 md:pe-16 lg:-me-24 lg:pe-24 [scroll-padding-inline-end:0]"
+        >
+          {list.map((step, index) => (
+            <CarouselItem key={step.id} data-reveal="card" className="flex basis-[260px] flex-col gap-4 [@container(min-width:40rem)]:basis-[300px] [@container(min-width:64rem)]:basis-[380px]">
+              <div className="relative h-[220px] overflow-hidden rounded-[10px] bg-muted [@container(min-width:64rem)]:h-[264px]">
+                <HowItWorksImage photo={photos?.[index]} />
+                <span className="absolute start-3 top-3">
+                  <Badge variant="solid" tone="primary" size="md" radius="rounded">
+                    <HowItWorksLtr>{String(index + 1).padStart(2, "0")}</HowItWorksLtr>
+                  </Badge>
+                </span>
+              </div>
+              <div className="flex flex-col gap-2">
+                <h3 className="text-lg font-medium text-foreground">{step.title}</h3>
+                <p className="text-sm text-muted-foreground">{step.description}</p>
+              </div>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+
+        <div className="flex items-center gap-4">
+          <div className="min-w-0 flex-1">
+            <Progress value={value} size="sm" showPercentage={false} aria-label={progressLabel ?? copy.progressLabel} />
+          </div>
+          <span className="shrink-0 text-xs text-muted-foreground">
+            <HowItWorksLtr>{`${String(current).padStart(2, "0")} / ${String(count).padStart(2, "0")}`}</HowItWorksLtr>
+          </span>
+        </div>
+      </Carousel>
+    </HowItWorksSection>
+  )
+}
+
+/**
+ * The default copy, English and Arabic, as `locale` picks it. Spread it to
+ * change a few strings and keep the rest.
+ */
+export const howItWorksPhotoRailProgressCopy = COPY

package/registry/blocks/how-it-works-photo-rail-progress/index.ts

@@ -0,0 +1,7 @@
+export {
+  HowItWorksPhotoRailProgress,
+  howItWorksPhotoRailProgressCopy,
+  type HowItWorksPhotoRailProgressCopy,
+  type HowItWorksPhotoRailProgressProps,
+  type HowItWorksRailStep,
+} from "./HowItWorksPhotoRailProgress"

package/registry/blocks/how-it-works-pill-timeline/HowItWorksPillTimeline.tsx

@@ -0,0 +1,181 @@
+"use client"
+
+import * as React from "react"
+import { ArrowUp, Droplets, Moon, Sun } from "lucide-react"
+import { cn } from "../../../src/lib/utils"
+import { Badge } from "../../ui/badge/badge"
+import { enter, HowItWorksSection, revealTargets, useRevealOnEnter, type HowItWorksLocale } from "../how-it-works/how-it-works"
+
+/*
+ * Figma: `How it Works` (42334:294272), Type=Pill Timeline.
+ *
+ * A centred header (a heading and a line), then three stages on one line: each a
+ * soft Badge over a prompt pill, with a caption under it. A 1px `border` line runs
+ * through every pill; the pill is a `card` capsule holding an icon, the prompt and
+ * a round send button in `accent`.
+ *
+ * Desktop and Tablet keep three columns. Mobile stacks the stages, each with its
+ * own line running edge to edge behind its pill. A pill's text is two words and
+ * never wraps. On Tablet the pill is tightened as in Figma: 8px between its icon,
+ * text and send button, 12px of padding on the icon side and 6px on the button
+ * side, and 12px of connector line on each side, so two pills are 24px apart with
+ * the line between them and never touch. Desktop has 16px of line on each side.
+ * The page's `dir` mirrors it: the morning stage is at the right in Arabic, the icon sits at the
+ * pill's right and the send button at its left. The send arrow points up and is
+ * not mirrored.
+ *
+ * Motion plays once, when the block comes into view: the line draws along the
+ * inline axis (700ms) through all the stages, then each stage rises 8px and fades
+ * in, 120ms apart, badge first, then the pill, then the caption. A pill's send
+ * button lifts 2px and fills with `primary` on hover and focus (140ms) and scales
+ * to 0.96 on press. Under reduced motion the block is its finished state.
+ *
+ * Content limits: the heading up to 32 characters, the line up to 70. A stage's
+ * badge up to 12 characters, its prompt two words on one line, up to 16, and its caption up to 80. Three
+ * stages in Figma; two to four work.
+ */
+
+export type HowItWorksStageTone = "warning" | "info" | "success"
+
+export interface HowItWorksStage {
+  /** Keys the stage. */
+  id: string
+  /** The Badge over the pill, such as "Morning". */
+  badge: string
+  tone: HowItWorksStageTone
+  /** The prompt in the pill. */
+  prompt: string
+  /** The caption under the pill. */
+  caption: React.ReactNode
+  /** The pill's leading icon. A water drop, a sun and a moon by default. */
+  icon?: React.ReactNode
+}
+
+export interface HowItWorksPillTimelineCopy {
+  /** The heading, an `h2`. */
+  heading: React.ReactNode
+  description: React.ReactNode
+  stages: HowItWorksStage[]
+  /** Names a pill's send button, such as "Ask: What needs water?": `{prompt}` stands for the prompt. */
+  sendLabel: string
+}
+
+/** Figma's copy, English and Arabic. The send label is written for the code. */
+const COPY: Record<HowItWorksLocale, HowItWorksPillTimelineCopy> = {
+  en: {
+    heading: "Looks after you all day",
+    description: "Small check-ins from sunrise to sunset, tuned to your space.",
+    stages: [
+      { id: "morning", badge: "Morning", tone: "warning", prompt: "Check water", caption: "Start the day knowing which plants need attention first." },
+      { id: "midday", badge: "Midday", tone: "info", prompt: "Check sunlight", caption: "Get quick advice when the light or the heat changes." },
+      { id: "evening", badge: "Evening", tone: "success", prompt: "Plan tomorrow", caption: "Wrap up the day and set a simple plan for the next one." },
+    ],
+    sendLabel: "Ask: {prompt}",
+  },
+  ar: {
+    heading: "يرافقك طوال اليوم",
+    description: "متابعات قصيرة من الشروق إلى الغروب، مصمّمة لمساحتك.",
+    stages: [
+      { id: "morning", badge: "الصباح", tone: "warning", prompt: "تفقّد السقي", caption: "ابدأ يومك وأنت تعرف أي النباتات تحتاج إلى عناية أولًا." },
+      { id: "midday", badge: "الظهيرة", tone: "info", prompt: "تفقّد الضوء", caption: "احصل على نصيحة سريعة عند تغيّر الضوء أو الحرارة." },
+      { id: "evening", badge: "المساء", tone: "success", prompt: "خطّط لغدك", caption: "أنهِ يومك وضع خطة بسيطة لليوم التالي." },
+    ],
+    sendLabel: "اسأل: {prompt}",
+  },
+}
+
+export interface HowItWorksPillTimelineProps extends Omit<React.HTMLAttributes<HTMLElement>, "title" | "onChange">, Partial<HowItWorksPillTimelineCopy> {
+  /** Which language the default copy is in. The page's `dir` sets the direction. */
+  locale?: HowItWorksLocale
+  /** Called with the stage's index when its pill is pressed. */
+  onStageSelect?: (index: number) => void
+}
+
+/** The stage columns from Tablet up, by how many stages there are: written out so each class is found. */
+const COLUMNS: Record<number, string> = {
+  2: "[@container(min-width:40rem)]:grid-cols-2",
+  3: "[@container(min-width:40rem)]:grid-cols-3",
+  4: "[@container(min-width:40rem)]:grid-cols-4",
+}
+
+const DEFAULT_ICONS = [<Droplets key="drop" aria-hidden="true" className="size-4 shrink-0" />, <Sun key="sun" aria-hidden="true" className="size-4 shrink-0" />, <Moon key="moon" aria-hidden="true" className="size-4 shrink-0" />]
+
+export function HowItWorksPillTimeline({ locale = "en", heading, description, stages, sendLabel, onStageSelect, className, ...props }: HowItWorksPillTimelineProps) {
+  const copy = COPY[locale]
+  const headingId = React.useId()
+  const rootRef = React.useRef<HTMLElement>(null)
+  const list = stages ?? copy.stages
+  const nameSend = sendLabel ?? copy.sendLabel
+
+  useRevealOnEnter(rootRef, (node) => {
+    const started: Animation[] = []
+    const lines = revealTargets(node, "line")
+    // In one row the lines draw as one, a share each in turn; stacked, each draws on its own.
+    const row = lines.length > 1 && lines[0]!.getBoundingClientRect().top === lines[1]!.getBoundingClientRect().top
+    lines.forEach((line, index) => {
+      const share = 700 / lines.length
+      started.push(enter(line, [{ transform: "scaleX(0)" }, { transform: "scaleX(1)" }], row ? { duration: share, delay: index * share, easing: "linear" } : { duration: 500, easing: "ease-out" }))
+    })
+    const rise = [{ opacity: 0, transform: "translateY(8px)" }, { opacity: 1, transform: "none" }]
+    revealTargets(node, "stage").forEach((stage, index) => {
+      const base = (row ? 700 : 300) + index * 120
+      const parts = ["badge", "pill", "caption"]
+      parts.forEach((part, step) => {
+        const target = stage.querySelector<HTMLElement>(`[data-reveal="${part}"]`)
+        if (target) started.push(enter(target, rise, { duration: 350, delay: base + step * 90 }))
+      })
+    })
+    return started
+  })
+
+  return (
+    <HowItWorksSection ref={rootRef} labelledBy={headingId} className={className} {...props}>
+      <header className="flex w-full flex-col items-center gap-4 text-center">
+        <h2 id={headingId} className="text-2xl font-medium text-foreground [@container(min-width:64rem)]:text-3xl">
+          {heading ?? copy.heading}
+        </h2>
+        <p className="max-w-[560px] text-base text-muted-foreground">{description ?? copy.description}</p>
+      </header>
+
+      <ol className={cn("grid grid-cols-1 gap-10 [@container(min-width:40rem)]:gap-0", COLUMNS[Math.min(Math.max(list.length, 2), 4)])}>
+        {list.map((stage, index) => (
+          <li key={stage.id} data-reveal="stage" className="flex min-w-0 flex-col items-center gap-4">
+            <div data-reveal="badge">
+              <Badge variant="soft" tone={stage.tone} size="md">
+                {stage.badge}
+              </Badge>
+            </div>
+            <div className="relative flex w-full items-center justify-center [@container(min-width:40rem)]:px-3 [@container(min-width:64rem)]:px-4">
+              <span aria-hidden="true" data-reveal="line" className="absolute inset-x-0 top-1/2 h-px origin-left bg-border [&:dir(rtl)]:origin-right" />
+              <button
+                type="button"
+                data-reveal="pill"
+                aria-label={nameSend.replace("{prompt}", stage.prompt)}
+                onClick={() => onStageSelect?.(index)}
+                className="group relative z-10 inline-flex max-w-full min-w-0 items-center gap-2 rounded-full border border-border bg-card py-2 ps-4 pe-2 text-sm font-medium [@container(min-width:40rem)]:ps-3 [@container(min-width:40rem)]:pe-1.5 [@container(min-width:64rem)]:ps-4 [@container(min-width:64rem)]:pe-2 text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background [@container(min-width:64rem)]:gap-4"
+              >
+                {stage.icon ?? DEFAULT_ICONS[index % DEFAULT_ICONS.length]}
+                <span className="min-w-0 whitespace-nowrap text-start">{stage.prompt}</span>
+                <span
+                  aria-hidden="true"
+                  className="flex size-8 shrink-0 items-center justify-center rounded-full bg-accent text-accent-foreground transition-[transform,background-color,color] duration-[140ms] group-hover:-translate-y-0.5 group-hover:bg-primary group-hover:text-primary-foreground group-focus-visible:-translate-y-0.5 group-focus-visible:bg-primary group-focus-visible:text-primary-foreground group-active:scale-[0.96] motion-reduce:transition-none motion-reduce:group-hover:translate-y-0 motion-reduce:group-focus-visible:translate-y-0 motion-reduce:group-active:scale-100"
+                >
+                  <ArrowUp className="size-5" />
+                </span>
+              </button>
+            </div>
+            <p data-reveal="caption" className="max-w-[352px] px-4 text-center text-sm text-muted-foreground [@container(min-width:40rem)]:px-8">
+              {stage.caption}
+            </p>
+          </li>
+        ))}
+      </ol>
+    </HowItWorksSection>
+  )
+}
+
+/**
+ * The default copy, English and Arabic, as `locale` picks it. Spread it to
+ * change a few strings and keep the rest.
+ */
+export const howItWorksPillTimelineCopy = COPY

package/registry/blocks/how-it-works-pill-timeline/index.ts

@@ -0,0 +1,8 @@
+export {
+  HowItWorksPillTimeline,
+  howItWorksPillTimelineCopy,
+  type HowItWorksPillTimelineCopy,
+  type HowItWorksPillTimelineProps,
+  type HowItWorksStage,
+  type HowItWorksStageTone,
+} from "./HowItWorksPillTimeline"