@smicolon/fasla-ui 0.6.0 → 0.8.0

package/registry/blocks/blog-cards-browse.test.tsx

@@ -0,0 +1,367 @@
+import * as React from "react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { act, fireEvent, render, screen, within } from "@testing-library/react"
+import { BlogCardsFilterSidebarResults, blogCardsFilterSidebarResultsCopy } from "./blog-cards-filter-sidebar-results"
+import { BlogCardsSearchChipsResults, blogCardsSearchChipsResultsCopy } from "./blog-cards-search-chips-results"
+import { BlogCardsPostCarouselWithControls, blogCardsPostCarouselWithControlsCopy } from "./blog-cards-post-carousel-with-controls"
+
+// What these tests can and cannot prove: jsdom has no layout and no Web
+// Animations, so the heights, the cross-fade's look, the rolling number and the
+// scrolling were checked in a browser. Here `Element.animate` and `matchMedia`
+// are stubs, so the tests assert the contract around the motion: what starts it
+// (a press or typing, never the load), in what order, what stays in the DOM while
+// it plays, the timings handed to it, and what reduced motion does instead.
+
+type Animation = { el: Element; keyframes: Keyframe[]; options: KeyframeAnimationOptions; onfinish: (() => void) | null }
+let animations: Animation[] = []
+
+const setMotion = (reduced: boolean) => {
+  window.matchMedia = ((query: string) => ({
+    matches: reduced && query.includes("reduce"),
+    media: query,
+    addEventListener() {},
+    removeEventListener() {},
+    addListener() {},
+    removeListener() {},
+    onchange: null,
+    dispatchEvent: () => false,
+  })) as typeof window.matchMedia
+}
+
+beforeEach(() => {
+  animations = []
+  setMotion(false)
+  Element.prototype.animate = function (this: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions) {
+    const animation: Animation = { el: this, keyframes, options, onfinish: null }
+    animations.push(animation)
+    return animation as unknown as globalThis.Animation
+  } as typeof Element.prototype.animate
+  Element.prototype.getAnimations = (() => []) as typeof Element.prototype.getAnimations
+})
+afterEach(() => {
+  vi.useRealTimers()
+  // @ts-expect-error the stubs are removed again
+  delete window.matchMedia
+  // @ts-expect-error the stubs are removed again
+  delete Element.prototype.animate
+})
+
+const strings = (value: unknown): string[] =>
+  typeof value === "string" ? [value] : value && typeof value === "object" ? Object.values(value).flatMap(strings) : []
+
+describe("Filter Sidebar + Results", () => {
+  const rows = (container: HTMLElement) => Array.from(container.querySelectorAll("ul > li")).filter((li) => li.getAttribute("aria-hidden") !== "true")
+  const count = (container: HTMLElement) => container.querySelector("[role='status']")?.textContent
+
+  it("starts as Figma draws it: Design Systems and Field notes pressed, four rows, nothing animated", () => {
+    const { container } = render(<BlogCardsFilterSidebarResults />)
+    expect(screen.getByRole("button", { name: /Design Systems/ }).getAttribute("aria-pressed")).toBe("true")
+    expect(screen.getByRole("button", { name: /Field notes/ }).getAttribute("aria-pressed")).toBe("true")
+    expect(screen.getByRole("button", { name: /All posts/ }).getAttribute("aria-pressed")).toBe("false")
+    expect(rows(container)).toHaveLength(4)
+    expect(count(container)).toBe("4 results")
+    expect(container.textContent).toContain("Filtered by")
+    expect(animations).toHaveLength(0)
+  })
+
+  it("makes every result one link named by its title, and the count a polite status", () => {
+    const { container } = render(<BlogCardsFilterSidebarResults />)
+    const status = container.querySelector("[role='status']")
+    expect(status?.getAttribute("aria-live")).toBe("polite")
+    container.querySelectorAll("a[aria-labelledby]").forEach((link) => {
+      const title = container.querySelector(`[id="${link.getAttribute("aria-labelledby")}"]`)
+      expect(title?.tagName).toBe("H3")
+      expect(link.contains(title)).toBe(true)
+    })
+  })
+
+  it("filters for real: a topic, a format, both, and back to everything", () => {
+    vi.stubGlobal("matchMedia", undefined)
+    // @ts-expect-error no animations in this test
+    delete Element.prototype.animate
+    const { container } = render(<BlogCardsFilterSidebarResults defaultTopic={null} defaultFormat={null} />)
+    expect(count(container)).toBe("13 results")
+    fireEvent.click(screen.getByRole("button", { name: /Typography/ }))
+    expect(count(container)).toBe("1 result")
+    expect(rows(container)).toHaveLength(1)
+    fireEvent.click(screen.getByRole("button", { name: /Long reads/ }))
+    expect(count(container)).toBe("1 result")
+    fireEvent.click(screen.getByRole("button", { name: /Research/ }))
+    expect(count(container)).toBe("0 results")
+    expect(screen.getByText("No posts match these filters.")).toBeTruthy()
+    fireEvent.click(screen.getByRole("button", { name: /Research/ }))
+    fireEvent.click(screen.getByRole("button", { name: /All posts/ }))
+    expect(count(container)).toBe("13 results")
+    vi.unstubAllGlobals()
+  })
+
+  it("collapses leaving rows and expands arriving ones in 220ms, 30ms apart, and removes the leavers when done", () => {
+    const { container } = render(<BlogCardsFilterSidebarResults />)
+    expect(animations).toHaveLength(0)
+    fireEvent.click(screen.getByRole("button", { name: /All posts/ }))
+    // The topic cleared: the Field notes posts of other topics arrive, the four stay.
+    const arriving = animations.filter((a) => a.options.fill === "backwards")
+    expect(arriving.length).toBeGreaterThan(0)
+    arriving.forEach((a, i) => {
+      expect(a.options.duration).toBe(220)
+      expect(a.options.delay).toBe(i * 30)
+      expect(a.keyframes[0]).toMatchObject({ height: "0px", opacity: 0 })
+    })
+    fireEvent.click(screen.getByRole("button", { name: /Typography/ }))
+    const leaving = animations.filter((a) => a.options.fill === "forwards")
+    expect(leaving.length).toBeGreaterThan(0)
+    leaving.forEach((a) => {
+      expect(a.options.duration).toBe(220)
+      expect(a.keyframes[1]).toMatchObject({ height: "0px", opacity: 0 })
+      expect(a.el.getAttribute("aria-hidden")).toBe("true")
+    })
+    const before = container.querySelectorAll("ul > li").length
+    act(() => leaving.forEach((a) => a.onfinish?.()))
+    expect(container.querySelectorAll("ul > li").length).toBeLessThan(before)
+  })
+
+  it("rolls the count when it changes and not before", () => {
+    const { container } = render(<BlogCardsFilterSidebarResults />)
+    expect(animations).toHaveLength(0)
+    fireEvent.click(screen.getByRole("button", { name: /All posts/ }))
+    const roll = animations.filter((a) => a.options.duration === 300)
+    expect(roll).toHaveLength(2)
+    expect(container.querySelector("[role='status'] [aria-hidden='true']")).toBeTruthy()
+  })
+
+  it("changes everything at once when motion is reduced", () => {
+    setMotion(true)
+    const { container } = render(<BlogCardsFilterSidebarResults />)
+    fireEvent.click(screen.getByRole("button", { name: /Typography/ }))
+    expect(animations).toHaveLength(0)
+    expect(rows(container)).toHaveLength(0)
+    expect(container.querySelectorAll("ul > li")).toHaveLength(0)
+    expect(count(container)).toBe("0 results")
+  })
+
+  it("does not build the sticky rail", () => {
+    const { container } = render(<BlogCardsFilterSidebarResults />)
+    expect(container.innerHTML).not.toMatch(/sticky/)
+  })
+
+  it("shows its empty line when there are no posts, and keeps Arabic free of em dashes and middle dots", () => {
+    render(<BlogCardsFilterSidebarResults posts={[]} />)
+    expect(screen.getByText("No articles yet.")).toBeTruthy()
+    for (const text of strings(blogCardsFilterSidebarResultsCopy.ar)) expect(text, text).not.toMatch(/[—·]/)
+  })
+
+  it("counts in Arabic with the right plural forms", () => {
+    const { container } = render(<BlogCardsFilterSidebarResults locale="ar" />)
+    expect(count(container)).toBe("4 نتائج")
+  })
+})
+
+describe("Search + Chips + Results", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  const cards = (container: HTMLElement) => container.querySelectorAll("a[aria-labelledby]")
+  const showing = (container: HTMLElement) => container.querySelector("[aria-live='polite']")?.textContent
+  const type = (value: string) => fireEvent.change(screen.getByRole("searchbox"), { target: { value } })
+
+  it("shows three of eleven at first, with the count line polite and nothing animated", () => {
+    const { container } = render(<BlogCardsSearchChipsResults />)
+    expect(cards(container)).toHaveLength(3)
+    expect(showing(container)).toBe("Showing 3 of 11 posts")
+    expect(animations).toHaveLength(0)
+  })
+
+  it("makes the chips buttons with aria-pressed, All pressed at first, wearing the Badge's classes", () => {
+    render(<BlogCardsSearchChipsResults />)
+    const group = screen.getByRole("group", { name: "Topics" })
+    const chips = within(group).getAllByRole("button")
+    expect(chips).toHaveLength(8)
+    expect(chips[0]!.getAttribute("aria-pressed")).toBe("true")
+    expect(chips[0]!.className).toContain("bg-primary")
+    expect(chips[1]!.getAttribute("aria-pressed")).toBe("false")
+    expect(chips[1]!.className).toContain("ring-secondary")
+    expect(chips[1]!.className).toContain("duration-150")
+  })
+
+  it("debounces typing by 250ms, keeps focus in the field and then swaps the results", () => {
+    const { container } = render(<BlogCardsSearchChipsResults />)
+    const field = screen.getByRole("searchbox")
+    field.focus()
+    type("survey")
+    act(() => void vi.advanceTimersByTime(249))
+    expect(showing(container)).toBe("Showing 3 of 11 posts")
+    act(() => void vi.advanceTimersByTime(1))
+    // The cross-fade: the old results go out over 100ms, then the new come in.
+    expect(container.querySelector(".opacity-0")).toBeTruthy()
+    act(() => void vi.advanceTimersByTime(100))
+    expect(showing(container)).toBe("Showing 1 of 1 post")
+    expect(container.querySelector(".opacity-0")).toBeNull()
+    expect(document.activeElement).toBe(field)
+    expect(screen.getByRole("searchbox")).toBe(field)
+  })
+
+  it("gives each chip a 44px hit area while the chip keeps its Badge size", () => {
+    render(<BlogCardsSearchChipsResults />)
+    for (const chip of within(screen.getByRole("group", { name: "Topics" })).getAllByRole("button")) {
+      expect(chip.className).toContain("after:h-11")
+      expect(chip.className).toContain("after:w-[max(100%,2.75rem)]")
+      expect(chip.className).toContain("relative")
+      expect(chip.className).toContain("min-h-[1.375rem]")
+    }
+  })
+
+  it("applies a chip at once, narrowing with the text, and swaps with the cross-fade", () => {
+    const { container } = render(<BlogCardsSearchChipsResults />)
+    fireEvent.click(screen.getByRole("button", { name: "RTL & Arabic" }))
+    expect(screen.getByRole("button", { name: "RTL & Arabic" }).getAttribute("aria-pressed")).toBe("true")
+    act(() => void vi.advanceTimersByTime(100))
+    expect(showing(container)).toBe("Showing 3 of 3 posts")
+    type("kashida")
+    act(() => void vi.advanceTimersByTime(250 + 100))
+    expect(showing(container)).toBe("Showing 2 of 2 posts")
+  })
+
+  it("shows the empty line only after 400ms of no results", () => {
+    const { container } = render(<BlogCardsSearchChipsResults />)
+    type("zzzz")
+    act(() => void vi.advanceTimersByTime(250))
+    act(() => void vi.advanceTimersByTime(399))
+    expect(screen.queryByText("No posts match your search.")).toBeNull()
+    expect(cards(container)).toHaveLength(3)
+    act(() => void vi.advanceTimersByTime(1 + 100))
+    expect(screen.getByText("No posts match your search.")).toBeTruthy()
+    expect(showing(container)).toBe("Showing 0 of 0 posts")
+  })
+
+  it("never shows the empty line to a typist who passes through no results", () => {
+    render(<BlogCardsSearchChipsResults />)
+    type("zzzz")
+    act(() => void vi.advanceTimersByTime(250 + 200))
+    type("kashida")
+    act(() => void vi.advanceTimersByTime(250 + 100 + 500))
+    expect(screen.queryByText("No posts match your search.")).toBeNull()
+  })
+
+  it("swaps at once when motion is reduced", () => {
+    setMotion(true)
+    const { container } = render(<BlogCardsSearchChipsResults />)
+    type("zzzz")
+    act(() => void vi.advanceTimersByTime(250))
+    expect(screen.getByText("No posts match your search.")).toBeTruthy()
+    expect(container.querySelector(".opacity-0")).toBeNull()
+    expect(animations).toHaveLength(0)
+  })
+
+  it("searches title, excerpt, topic and author", () => {
+    const { container } = render(<BlogCardsSearchChipsResults />)
+    for (const [text, expected] of [["Noor", 3], ["accessibility", 1], ["x-height", 1], ["ramp", 1]] as const) {
+      type(text)
+      act(() => void vi.advanceTimersByTime(250 + 100))
+      expect(showing(container), text).toBe(`Showing ${Math.min(3, expected)} of ${expected} post${expected === 1 ? "" : "s"}`)
+    }
+  })
+
+  it("shows the empty line at once when there are no posts, and keeps Arabic free of em dashes and middle dots", () => {
+    render(<BlogCardsSearchChipsResults posts={[]} />)
+    expect(screen.getByText("No articles yet.")).toBeTruthy()
+    for (const text of strings(blogCardsSearchChipsResultsCopy.ar)) expect(text, text).not.toMatch(/[—·]/)
+  })
+})
+
+describe("Post Carousel with Controls", () => {
+  class StubObserver {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return []
+    }
+  }
+  let scrolled: Element[] = []
+  beforeEach(() => {
+    scrolled = []
+    vi.stubGlobal("IntersectionObserver", StubObserver)
+    Element.prototype.scrollIntoView = function (this: Element) {
+      scrolled.push(this)
+    }
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it("is a carousel of five cards, each a link named by its title, with a dot per view", () => {
+    const { container } = render(<BlogCardsPostCarouselWithControls />)
+    expect(container.querySelectorAll("[data-slot='carousel-item']")).toHaveLength(5)
+    expect(container.querySelectorAll("a[aria-labelledby]")).toHaveLength(5)
+    expect(container.querySelectorAll("[data-slot='carousel-dot']")).toHaveLength(5)
+    expect(screen.getByRole("heading", { level: 2 }).textContent).toBe("Keep scrolling sideways")
+  })
+
+  it("marks Previous at the start and Next at the end aria-disabled, and keeps them focusable", () => {
+    const { rerender } = render(<BlogCardsPostCarouselWithControls />)
+    const state = (name: string) => screen.getByRole("button", { name })
+    expect(state("Previous posts").getAttribute("aria-disabled")).toBe("true")
+    expect((state("Previous posts") as HTMLButtonElement).disabled).toBe(false)
+    expect(state("Next posts").getAttribute("aria-disabled")).toBeNull()
+    rerender(<BlogCardsPostCarouselWithControls key="end" defaultActiveIndex={4} />)
+    expect(state("Previous posts").getAttribute("aria-disabled")).toBeNull()
+    expect(state("Next posts").getAttribute("aria-disabled")).toBe("true")
+    expect((state("Next posts") as HTMLButtonElement).disabled).toBe(false)
+  })
+
+  it("does nothing when a disabled arrow is pressed, and focus stays on it", () => {
+    render(<BlogCardsPostCarouselWithControls defaultActiveIndex={4} />)
+    const next = screen.getByRole("button", { name: "Next posts" })
+    next.focus()
+    scrolled = [] // the carousel jumps to the starting card once on mount
+    fireEvent.click(next)
+    fireEvent.keyDown(next, { key: "Enter" })
+    expect(scrolled).toHaveLength(0)
+    expect(document.activeElement).toBe(next)
+    const previous = screen.getByRole("button", { name: "Previous posts" })
+    fireEvent.click(previous)
+    expect(scrolled.length).toBeGreaterThan(0)
+  })
+
+  it("moves one card when Next is pressed, and a dot jumps to its card", () => {
+    const { container } = render(<BlogCardsPostCarouselWithControls />)
+    const items = container.querySelectorAll("[data-slot='carousel-item']")
+    fireEvent.click(screen.getByRole("button", { name: "Next posts" }))
+    expect(scrolled.at(-1)).toBe(items[1])
+    fireEvent.click(container.querySelectorAll("[data-slot='carousel-dot']")[3]!)
+    expect(scrolled.at(-1)).toBe(items[3])
+  })
+
+  it("has no autoplay: nothing moves on a timer", () => {
+    vi.useFakeTimers()
+    render(<BlogCardsPostCarouselWithControls />)
+    act(() => void vi.advanceTimersByTime(120_000))
+    expect(scrolled).toHaveLength(0)
+    vi.useRealTimers()
+  })
+
+  it("draws arrow-left and arrow-right, each mirrored by the nearest dir, so Next points left in Arabic", () => {
+    const { container } = render(<BlogCardsPostCarouselWithControls locale="ar" />)
+    const previous = screen.getByRole("button", { name: "المقالات السابقة" })
+    const next = screen.getByRole("button", { name: "المقالات التالية" })
+    expect(previous.querySelector("svg.lucide-arrow-left")?.getAttribute("class")).toContain("[&:dir(rtl)]:-scale-x-100")
+    expect(next.querySelector("svg.lucide-arrow-right")?.getAttribute("class")).toContain("[&:dir(rtl)]:-scale-x-100")
+    // Previous comes first in the DOM, so a right-to-left page puts it at the right and Next at the left.
+    expect(previous.compareDocumentPosition(next) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+    expect(container.querySelector("[data-slot='carousel-content']")).toBeTruthy()
+  })
+
+  it("keeps the track a focusable, scrollable region with reduced motion jumping at once", () => {
+    const { container } = render(<BlogCardsPostCarouselWithControls />)
+    const track = container.querySelector("[data-slot='carousel-content']")!
+    expect(track.getAttribute("tabindex")).toBe("0")
+    expect(track.className).toContain("motion-reduce:scroll-auto")
+  })
+
+  it("shows its empty line, and no carousel, without posts, and keeps Arabic free of em dashes and middle dots", () => {
+    const { container } = render(<BlogCardsPostCarouselWithControls posts={[]} />)
+    expect(container.querySelector("[data-slot='carousel-content']")).toBeNull()
+    expect(screen.getByText("No articles yet.")).toBeTruthy()
+    for (const text of strings(blogCardsPostCarouselWithControlsCopy.ar)) expect(text, text).not.toMatch(/[—·]/)
+  })
+})

package/registry/blocks/blog-cards-classic-3-up-grid/BlogCardsClassic3UpGrid.tsx

@@ -0,0 +1,287 @@
+import * as React from "react"
+import { ArrowRightIcon } from "lucide-react"
+import { cn } from "../../../src/lib/utils"
+import { Avatar } from "../../ui/avatar/avatar"
+import { Badge } from "../../ui/badge/badge"
+import { buttonVariants } from "../../ui/button/button"
+
+/*
+ * Figma: `Blog Cards` (46368:243914), Type=Classic 3-Up Grid.
+ *
+ * A section header (an eyebrow and a heading, with an outline button at the
+ * end) over a row of three article cards. A card is a cover photo over a
+ * body: the category badge and the read time, the title, a three-line
+ * summary, and the author's initials with their name and the date. The whole
+ * card is the link, named by its title.
+ *
+ * Desktop (Figma 1440) puts the three cards in one row. Tablet (768) puts two
+ * side by side and the third across the full width, its cover cropped to a
+ * wider 720 by 302. Mobile (360) is one column, the button full width under
+ * the heading.
+ *
+ * Hover and keyboard focus scale the cover from 1.00 to 1.03 inside the
+ * card's rounded clip (240ms) and turn the title `info`. Nothing else on the
+ * card moves. On Mobile there is no hover; pressing a card dims it to 96% for
+ * 120ms. Reduced motion turns the scale and the dimming off, and nothing
+ * plays on load, on scroll or on a timer.
+ *
+ * Arabic mirrors by the page's `dir`: the card order, the button and the
+ * header. Photographs are never flipped.
+ *
+ * Mobile first, and sized by the block's own width, not the window's: the
+ * section is a query container. The base classes are Figma's Mobile (360);
+ * `[@container(min-width:40rem)]:` is its Tablet and
+ * `[@container(min-width:64rem)]:` its Desktop. The section's own padding
+ * still follows the window, since an element can't query itself.
+ */
+
+export interface BlogCardsClassic3UpGridPost {
+  /** The cover photo. Without one the cover is a `muted` placeholder of the same size. */
+  image?: { src: string; alt: string }
+  /** The category badge. */
+  category: React.ReactNode
+  /** The read time, as written: "9 min read". */
+  readTime: React.ReactNode
+  /** The title, an `h3`, and the card's link. */
+  title: React.ReactNode
+  /** The summary, three lines at most on Desktop. */
+  summary: React.ReactNode
+  /** The author's name. Their initials fill the avatar. */
+  author: string
+  /** The date, as written: "Aug 18, 2026". */
+  date: React.ReactNode
+  /** Where the card goes. */
+  href: string
+}
+
+export interface BlogCardsClassic3UpGridCopy {
+  /** The small line over the heading. Hidden when empty. */
+  eyebrow: React.ReactNode
+  /** The section heading, an `h2`. */
+  heading: React.ReactNode
+  /** The button at the end of the header. Hidden when there is no label. */
+  action: { label: React.ReactNode; href: string }
+  /** The articles, in reading order. */
+  posts: BlogCardsClassic3UpGridPost[]
+  /** Shown instead of the cards when `posts` is empty. */
+  emptyLabel: React.ReactNode
+}
+
+/** Figma's copy, English and Arabic. */
+const COPY: Record<"en" | "ar", BlogCardsClassic3UpGridCopy> = {
+  en: {
+    eyebrow: "LATEST FROM THE BLOG",
+    heading: "Notes on building Fasla",
+    action: { label: "View all posts", href: "#" },
+    posts: [
+      {
+        category: "Design Systems",
+        readTime: "9 min read",
+        title: "Why we rebuilt every token as a variable",
+        summary:
+          "Six months of drift taught us that a hex code in a style is a promise you cannot keep. Here is the migration, and what it cost.",
+        author: "Karim Nasser",
+        date: "Aug 18, 2026",
+        href: "#",
+      },
+      {
+        category: "RTL & Arabic",
+        readTime: "12 min read",
+        title: "Arabic type on the web: what breaks & why",
+        summary:
+          "Line height, kashida, and the quiet assumptions baked into most UI kits — a field guide from building Fasla's RTL layer.",
+        author: "Noor Al-Amin",
+        date: "Aug 11, 2026",
+        href: "#",
+      },
+      {
+        category: "Foundations",
+        readTime: "6 min read",
+        title: "The 8-point grid is not a religion",
+        summary:
+          "Where a strict spacing scale helps, where it fights the content, and how we decide which rule wins.",
+        author: "Lina Haddad",
+        date: "Aug 4, 2026",
+        href: "#",
+      },
+    ],
+    emptyLabel: "No articles yet.",
+  },
+  ar: {
+    eyebrow: "جديد المدونة",
+    heading: "ملاحظات من بناء فاصلة",
+    action: { label: "عرض كل المقالات", href: "#" },
+    posts: [
+      {
+        category: "أنظمة التصميم",
+        readTime: "قراءة 9 دقائق",
+        title: "لماذا أعدنا بناء كل رمز تصميمي كمتغيّر",
+        summary:
+          "ستة أشهر من الانحراف علّمتنا أن كود اللون داخل نمطٍ ما وعدٌ لا يمكن الوفاء به. إليكم قصة الترحيل وما كلّفنا.",
+        author: "كريم ناصر",
+        date: "18 أغسطس 2026",
+        href: "#",
+      },
+      {
+        category: "العربية وRTL",
+        readTime: "قراءة 12 دقيقة",
+        title: "الخط العربي على الويب: ما الذي ينكسر ولماذا",
+        summary:
+          "ارتفاع السطر، والكشيدة، والافتراضات الصامتة المخبوءة في معظم أطقم الواجهات، وهو دليل ميداني من بناء طبقة RTL في فاصلة.",
+        author: "نور الأمين",
+        date: "11 أغسطس 2026",
+        href: "#",
+      },
+      {
+        category: "الأساسيات",
+        readTime: "قراءة 6 دقائق",
+        title: "شبكة الثماني نقاط ليست عقيدة",
+        summary: "أين يفيد مقياس التباعد الصارم، وأين يصطدم بالمحتوى، وكيف نقرر أي قاعدة تنتصر.",
+        author: "لينا حدّاد",
+        date: "4 أغسطس 2026",
+        href: "#",
+      },
+    ],
+    emptyLabel: "لا توجد مقالات بعد.",
+  },
+}
+
+/** The block's English and Arabic copy, for stories and previews. */
+export const blogCardsClassic3UpGridCopy = COPY
+
+/*
+ * The hover and focus classes, from Tablet up (Mobile has none), written out
+ * whole: Tailwind finds a class by reading the source, so none is built from
+ * pieces.
+ */
+const COVER_HOVER =
+  "group-hover/card:[@container(min-width:40rem)]:motion-safe:scale-[1.03] group-focus-visible/card:[@container(min-width:40rem)]:motion-safe:scale-[1.03]"
+const TITLE_HOVER =
+  "group-hover/card:[@container(min-width:40rem)]:text-info group-focus-visible/card:[@container(min-width:40rem)]:text-info"
+/** Focus and the Mobile press, on the card's own link. */
+const CARD_STATE =
+  "[outline:none] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring active:[@container(max-width:39.99rem)]:opacity-[0.96]"
+
+export interface BlogCardsClassic3UpGridProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "title">,
+    Partial<BlogCardsClassic3UpGridCopy> {
+  /** Which language the default copy is in. The page's `dir` sets the direction. */
+  locale?: "en" | "ar"
+}
+
+export function BlogCardsClassic3UpGrid({
+  locale = "en",
+  eyebrow,
+  heading,
+  action,
+  posts,
+  emptyLabel,
+  className,
+  ...props
+}: BlogCardsClassic3UpGridProps) {
+  const copy = COPY[locale]
+  const headingId = React.useId()
+  const titleId = React.useId()
+  const list = posts ?? copy.posts
+  const header = { eyebrow: eyebrow ?? copy.eyebrow, action: action ?? copy.action }
+
+  return (
+    <section
+      aria-labelledby={headingId}
+      className={cn(
+        "[container-type:inline-size] bg-background px-4 py-8 md:px-6 md:py-16 lg:px-20 lg:py-24",
+        className
+      )}
+      {...props}
+    >
+      <div className="mx-auto flex w-full max-w-[1280px] flex-col gap-12">
+        <div className="flex flex-col gap-5 [@container(min-width:40rem)]:flex-row [@container(min-width:40rem)]:items-center [@container(min-width:40rem)]:justify-between [@container(min-width:40rem)]:gap-8">
+          <div className="flex min-w-0 flex-col gap-2">
+            {header.eyebrow ? (
+              <p className="text-xs font-medium uppercase text-muted-foreground">{header.eyebrow}</p>
+            ) : null}
+            <h2
+              id={headingId}
+              className="text-3xl font-semibold text-foreground [@container(min-width:40rem)]:text-4xl"
+            >
+              {heading ?? copy.heading}
+            </h2>
+          </div>
+          {header.action.label ? (
+            <a
+              href={header.action.href}
+              className={cn(
+                buttonVariants({ variant: "outline", size: "md" }),
+                "w-full shrink-0 [@container(min-width:40rem)]:w-auto"
+              )}
+            >
+              {header.action.label}
+              <ArrowRightIcon aria-hidden="true" className="size-4 rtl:-scale-x-100" />
+            </a>
+          ) : null}
+        </div>
+
+        {list.length === 0 ? (
+          <p className="text-center text-sm text-muted-foreground">{emptyLabel ?? copy.emptyLabel}</p>
+        ) : (
+          <ul className="grid grid-cols-1 gap-8 [@container(min-width:40rem)]:grid-cols-2 [@container(min-width:40rem)]:gap-6 [@container(min-width:64rem)]:grid-cols-3">
+            {list.map((post, index) => {
+              // An odd last card spans the row on Tablet, with a wider cover.
+              const wide = list.length % 2 === 1 && index === list.length - 1
+              return (
+                <li key={index} className={cn("flex", wide && "[@container(min-width:40rem)_and_(max-width:63.99rem)]:col-span-2")}>
+                  <a
+                    href={post.href}
+                    aria-labelledby={`${titleId}-${index}`}
+                    className={cn(
+                      "group/card flex w-full flex-col overflow-hidden rounded-lg border bg-card transition-opacity duration-[120ms] motion-reduce:transition-none",
+                      CARD_STATE
+                    )}
+                  >
+                    <div
+                      className={cn(
+                        "relative aspect-video w-full overflow-hidden bg-muted",
+                        wide && "[@container(min-width:40rem)_and_(max-width:63.99rem)]:aspect-[720/302]"
+                      )}
+                    >
+                      {post.image ? (
+                        // eslint-disable-next-line @next/next/no-img-element
+                        <img
+                          src={post.image.src}
+                          alt={post.image.alt}
+                          loading="lazy"
+                          className={cn(
+                            "absolute inset-0 size-full object-cover transition-transform duration-[240ms] ease-out motion-reduce:transition-none",
+                            COVER_HOVER
+                          )}
+                        />
+                      ) : null}
+                    </div>
+                    <div className="flex flex-1 flex-col gap-3 p-5">
+                      <div className="flex items-center gap-2">
+                        <Badge variant="outline" tone="secondary" size="sm" radius="rounded">
+                          {post.category}
+                        </Badge>
+                        <span className="text-xs text-muted-foreground">{post.readTime}</span>
+                      </div>
+                      <h3 id={`${titleId}-${index}`} className={cn("text-lg font-semibold text-foreground", TITLE_HOVER)}>
+                        {post.title}
+                      </h3>
+                      <p className="text-sm text-muted-foreground">{post.summary}</p>
+                      <div className="flex items-center gap-2">
+                        <Avatar variant="initials" size="24" radius="rounded" name={post.author} aria-hidden="true" />
+                        <span className="text-xs font-medium text-foreground">{post.author}</span>
+                        <span aria-hidden="true" className="size-[3px] rounded-full bg-muted-foreground" />
+                        <span className="text-xs text-muted-foreground">{post.date}</span>
+                      </div>
+                    </div>
+                  </a>
+                </li>
+              )
+            })}
+          </ul>
+        )}
+      </div>
+    </section>
+  )
+}

package/registry/blocks/blog-cards-classic-3-up-grid/index.ts

@@ -0,0 +1,7 @@
+export {
+  BlogCardsClassic3UpGrid,
+  blogCardsClassic3UpGridCopy,
+  type BlogCardsClassic3UpGridCopy,
+  type BlogCardsClassic3UpGridPost,
+  type BlogCardsClassic3UpGridProps,
+} from "./BlogCardsClassic3UpGrid"