@smicolon/fasla-ui 0.6.0 → 0.7.0

package/registry/ui/breadcrumb/breadcrumb.test.tsx

@@ -0,0 +1,305 @@
+import * as React from "react"
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { beforeAll, describe, it, expect } from "vitest"
+import { act, fireEvent, render, screen, within } from "@testing-library/react"
+import { HouseIcon, SlashIcon } from "lucide-react"
+import {
+  Breadcrumb,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "./breadcrumb"
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "../dropdown-menu/dropdown-menu"
+
+const SOURCE = readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "breadcrumb.tsx"), "utf8")
+
+/** The name a screen reader would hear from the ellipsis: its visible (not display: none) runs. */
+function spokenName(el: HTMLElement) {
+  return Array.from(el.querySelectorAll<HTMLElement>(".sr-only"))
+    .filter((run) => getComputedStyle(run).display !== "none")
+    .map((run) => run.textContent)
+    .join("")
+}
+
+/*
+ * The ellipsis name is two hidden runs, and CSS keeps the one matching the
+ * nearest `lang`. jsdom loads no Tailwind, so inject exactly the compiled
+ * rules the name depends on.
+ */
+beforeAll(() => {
+  const style = document.createElement("style")
+  style.textContent = [
+    ".hidden { display: none }",
+    ".\\[\\&\\:lang\\(ar\\)\\]\\:hidden:lang(ar) { display: none }",
+    ".\\[\\&\\:lang\\(ar\\)\\]\\:inline:lang(ar) { display: inline }",
+  ].join("\n")
+  document.head.append(style)
+})
+
+/** Figma's Count=+4: the first item, the ellipsis, then the last two. */
+const Collapsed = ({ separator }: { separator?: React.ReactNode }) => (
+  <Breadcrumb>
+    <BreadcrumbList>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="/" icon={<HouseIcon data-testid="icon" />}>
+          Home
+        </BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbSeparator data-testid="separator">{separator}</BreadcrumbSeparator>
+      <BreadcrumbItem>
+        <BreadcrumbEllipsis data-testid="ellipsis" />
+      </BreadcrumbItem>
+      <BreadcrumbSeparator>{separator}</BreadcrumbSeparator>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="/documents">Documents</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbSeparator>{separator}</BreadcrumbSeparator>
+      <BreadcrumbItem>
+        <BreadcrumbPage>Add Document</BreadcrumbPage>
+      </BreadcrumbItem>
+    </BreadcrumbList>
+  </Breadcrumb>
+)
+
+/** The docs' collapsed trail: the ellipsis opens a Dropdown Menu of the steps it hides, as links. */
+const CollapsedWithMenu = () => (
+  <Breadcrumb>
+    <BreadcrumbList>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="/">Home</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbItem>
+        <DropdownMenu>
+          <DropdownMenuTrigger aria-label="Hidden steps">
+            <BreadcrumbEllipsis data-testid="ellipsis" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuItem render={<a href="/projects" />}>Projects</DropdownMenuItem>
+            <DropdownMenuItem render={<a href="/projects/website" />}>Website</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbItem>
+        <BreadcrumbPage>Add Document</BreadcrumbPage>
+      </BreadcrumbItem>
+    </BreadcrumbList>
+  </Breadcrumb>
+)
+
+describe("Breadcrumb", () => {
+  it("is a navigation landmark named Breadcrumb by default", () => {
+    render(<Collapsed />)
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toHaveAttribute("data-slot", "breadcrumb")
+  })
+
+  it("takes its accessible name from aria-label", () => {
+    render(<Breadcrumb aria-label="مسار التنقّل" />)
+    expect(screen.getByRole("navigation", { name: "مسار التنقّل" })).toBeTruthy()
+  })
+
+  it("is an ordered list whose items are only the steps", () => {
+    render(<Collapsed />)
+    const list = screen.getByRole("list")
+    expect(list.tagName).toBe("OL")
+    // Separators are presentation and hidden, so they are not list items.
+    expect(within(list).getAllByRole("listitem")).toHaveLength(4)
+  })
+
+  it("lays the trail out with Figma's 10px gap, in text-sm and muted-foreground", () => {
+    render(<Collapsed />)
+    expect(screen.getByRole("list")).toHaveClass(
+      "flex",
+      "flex-wrap",
+      "items-center",
+      "gap-x-2.5",
+      "text-sm",
+      "text-muted-foreground"
+    )
+  })
+})
+
+describe("BreadcrumbLink", () => {
+  it("is a muted link that turns foreground on hover", () => {
+    render(<Collapsed />)
+    const link = screen.getByRole("link", { name: "Documents" })
+    expect(link).toHaveAttribute("href", "/documents")
+    expect(link).toHaveClass("text-muted-foreground", "hover:text-foreground", "motion-reduce:transition-none")
+  })
+
+  it("shows a visible focus outline on the ring token", () => {
+    render(<Collapsed />)
+    expect(screen.getByRole("link", { name: "Home" })).toHaveClass(
+      "focus-visible:outline",
+      "focus-visible:outline-2",
+      "focus-visible:outline-ring"
+    )
+  })
+
+  it("renders a leading icon 4px from its label, hidden and on foreground", () => {
+    render(<Collapsed />)
+    const link = screen.getByRole("link", { name: "Home" })
+    expect(link).toHaveClass("gap-1")
+    const slot = screen.getByTestId("icon").parentElement!
+    expect(slot).toHaveAttribute("aria-hidden", "true")
+    expect(slot).toHaveAttribute("data-slot", "breadcrumb-icon")
+    expect(slot).toHaveClass("text-foreground", "[&>svg]:size-3.5", "[&>svg]:[stroke-width:1.5]")
+    // DOM order icon → label, so dir=rtl puts the icon at the start (the right).
+    expect(link.firstElementChild).toBe(slot)
+  })
+
+  it("renders no icon slot without an icon", () => {
+    render(<Collapsed />)
+    expect(screen.getByRole("link", { name: "Documents" }).querySelector("[data-slot=breadcrumb-icon]")).toBeNull()
+  })
+
+  it("renders its child as the link with asChild, keeping the icon", () => {
+    render(
+      <BreadcrumbLink asChild icon={<HouseIcon data-testid="icon" />}>
+        <a href="/home" data-router="">
+          Home
+        </a>
+      </BreadcrumbLink>
+    )
+    const link = screen.getByRole("link", { name: "Home" })
+    expect(link).toHaveAttribute("data-router")
+    expect(link).toHaveAttribute("data-slot", "breadcrumb-link")
+    expect(link).toHaveClass("text-muted-foreground")
+    expect(link).toContainElement(screen.getByTestId("icon"))
+  })
+
+  it("forwards its ref to the anchor", () => {
+    const ref = React.createRef<HTMLAnchorElement>()
+    render(<BreadcrumbLink ref={ref} href="/" />)
+    expect(ref.current?.tagName).toBe("A")
+  })
+})
+
+describe("BreadcrumbPage", () => {
+  it("marks the current page, on foreground, and is not a link", () => {
+    render(<Collapsed />)
+    const page = screen.getByText("Add Document")
+    expect(page.tagName).toBe("SPAN")
+    expect(page).toHaveAttribute("aria-current", "page")
+    expect(page).toHaveClass("text-foreground")
+    expect(screen.queryByRole("link", { name: "Add Document" })).toBeNull()
+  })
+
+  it("takes an icon too", () => {
+    render(<BreadcrumbPage icon={<HouseIcon data-testid="icon" />}>Home</BreadcrumbPage>)
+    expect(screen.getByText("Home")).toContainElement(screen.getByTestId("icon"))
+  })
+})
+
+describe("BreadcrumbSeparator", () => {
+  it("is hidden from assistive technology", () => {
+    render(<Collapsed />)
+    const separator = screen.getByTestId("separator")
+    expect(separator.tagName).toBe("LI")
+    expect(separator).toHaveAttribute("role", "presentation")
+    expect(separator).toHaveAttribute("aria-hidden", "true")
+  })
+
+  it("draws a 14px chevron on foreground by default, mirrored in RTL", () => {
+    render(<Collapsed />)
+    const separator = screen.getByTestId("separator")
+    expect(separator).toHaveClass("text-foreground", "[&>svg]:size-3.5")
+    const svg = separator.querySelector("svg")!
+    expect(svg).toHaveClass("lucide-chevron-right", "[&:dir(rtl)]:-scale-x-100")
+  })
+
+  it("draws a child icon in place of the chevron: Figma's Custom Separator", () => {
+    render(<Collapsed separator={<SlashIcon data-testid="slash" />} />)
+    const separator = screen.getByTestId("separator")
+    expect(separator).toContainElement(screen.getAllByTestId("slash")[0]!)
+    expect(separator.querySelector(".lucide-chevron-right")).toBeNull()
+  })
+})
+
+describe("BreadcrumbEllipsis", () => {
+  it("is a 14px glyph on foreground, the glyph hidden", () => {
+    render(<Collapsed />)
+    const ellipsis = screen.getByTestId("ellipsis")
+    expect(ellipsis).toHaveClass("size-3.5", "text-foreground")
+    expect(ellipsis.querySelector("svg")).toHaveAttribute("aria-hidden", "true")
+  })
+
+  it("is not interactive on its own: a trigger wrapped around it is the button", () => {
+    render(<Collapsed />)
+    expect(within(screen.getByRole("navigation")).queryByRole("button")).toBeNull()
+
+    render(<CollapsedWithMenu />)
+    const trigger = screen.getByRole("button", { name: "Hidden steps" })
+    expect(trigger).toContainElement(screen.getAllByTestId("ellipsis").at(-1)!)
+    expect(trigger).toHaveAttribute("aria-haspopup", "menu")
+    expect(trigger).toHaveAttribute("aria-expanded", "false")
+  })
+
+  it("opens a menu of the hidden steps, each a link", async () => {
+    render(<CollapsedWithMenu />)
+    const trigger = screen.getByRole("button", { name: "Hidden steps" })
+    await act(async () => {
+      fireEvent.click(trigger)
+    })
+    expect(trigger).toHaveAttribute("aria-expanded", "true")
+    const menu = screen.getByRole("menu")
+    const rows = within(menu).getAllByRole("menuitem")
+    expect(rows.map((row) => row.textContent)).toEqual(["Projects", "Website"])
+    expect(rows.map((row) => [row.tagName, row.getAttribute("href")])).toEqual([
+      ["A", "/projects"],
+      ["A", "/projects/website"],
+    ])
+  })
+
+  it("closes on Escape and returns focus to the ellipsis", async () => {
+    render(<CollapsedWithMenu />)
+    const trigger = screen.getByRole("button", { name: "Hidden steps" })
+    await act(async () => {
+      fireEvent.click(trigger)
+    })
+    await act(async () => {
+      fireEvent.keyDown(screen.getByRole("menu"), { key: "Escape" })
+    })
+    expect(screen.queryByRole("menu")).toBeNull()
+    expect(trigger).toHaveAttribute("aria-expanded", "false")
+    expect(trigger).toHaveFocus()
+  })
+
+  it.each([
+    ["en", "More"],
+    ["ar", "المزيد"],
+  ])("is read as the %s word for more", (lang, name) => {
+    render(
+      <div lang={lang}>
+        <BreadcrumbEllipsis data-testid="e" />
+      </div>
+    )
+    expect(spokenName(screen.getByTestId("e"))).toBe(name)
+  })
+})
+
+describe("Breadcrumb source", () => {
+  const classes = [...SOURCE.matchAll(/"([^"]*)"/g)].map((m) => m[1]!).join(" ")
+
+  it("uses logical properties only", () => {
+    expect(classes).not.toMatch(/(^|\s|:)-?(ml|mr|pl|pr|left|right|inset-l|inset-r|rounded-[lr]|border-[lr])-/)
+    expect(classes).not.toMatch(/text-(left|right)\b/)
+  })
+
+  it("flips only the chevron for RTL, with one icon, by its own direction", () => {
+    expect([...classes.matchAll(/:dir\(rtl\)\]:\S+/g)].map((m) => m[0])).toEqual([":dir(rtl)]:-scale-x-100"])
+    // `rtl:` matches any dir="rtl" ancestor, so an LTR island inside RTL would flip too.
+    expect(classes).not.toMatch(/(^|\s)rtl:/)
+    expect(SOURCE).not.toMatch(/ChevronLeft/)
+  })
+
+  it("leaves Arabic's taller line to the type ramp", () => {
+    expect(classes).not.toMatch(/\bleading-/)
+  })
+})

package/registry/ui/breadcrumb/breadcrumb.tsx

@@ -0,0 +1,205 @@
+import * as React from "react"
+import { Slot, Slottable } from "@radix-ui/react-slot"
+import { ChevronRightIcon, EllipsisIcon } from "lucide-react"
+import { cn } from "../../../src/lib/utils"
+
+/*
+ * Figma: `Breadcrumbs` (3771:68266), 32 variants: Direction × Style × Count,
+ * plus a `Has-Icon` boolean.
+ *
+ * Composable, as shadcn's Breadcrumb is: the developer writes the trail, so
+ * there is no `count` prop. Figma axis → code:
+ *  - `Count` 2 / 3 / 4 → that many `BreadcrumbItem`s. `+4` is the collapsed
+ *    trail: the first item, `BreadcrumbEllipsis`, then the last two.
+ *  - `Style` Default → the chevron `BreadcrumbSeparator` draws on its own.
+ *    Custom Separator → `<BreadcrumbSeparator><SlashIcon /></BreadcrumbSeparator>`.
+ *    With Badge and Outline Badge are compositions: a Soft or Outline `Badge`
+ *    inside each link and the page, not variants of this component.
+ *  - `Has-Icon` → the `icon` prop on `BreadcrumbLink` and `BreadcrumbPage`.
+ *  - `Direction` → the page's `dir`, never a prop. The row is in DOM order,
+ *    so `dir="rtl"` mirrors it, and the one chevron is flipped in CSS. The
+ *    flip reads the chevron's own direction (`:dir(rtl)`), not Tailwind's
+ *    `rtl:`, which matches any `dir="rtl"` ancestor: an English island on an
+ *    Arabic page would get a backwards chevron.
+ *
+ * Measurements, all Figma's: a 10px gap (`spacing/2,5`) between items and
+ * separators, 4px (`spacing/1`) between an icon and its label, 14px icons,
+ * separators and ellipsis. Labels are `text-sm`, so the type ramp gives
+ * Arabic its 24px line (English 20px) with no RTL class here.
+ *
+ * Colours, all bound in Figma: links `muted-foreground`, the current page
+ * `foreground`, and every icon, separator and the ellipsis `foreground`.
+ */
+
+/** Sizes any SVG icon passed in to Figma's 14px glyph, with its 1.5 stroke at that size. */
+const ICON = "[&>svg]:size-3.5 [&>svg]:shrink-0 [&>svg]:[stroke-width:1.5]"
+
+/** The navigation landmark. Name it in the page's language with `aria-label`. */
+const Breadcrumb = React.forwardRef<HTMLElement, React.ComponentPropsWithoutRef<"nav">>(
+  ({ "aria-label": ariaLabel = "Breadcrumb", ...props }, ref) => (
+    <nav ref={ref} aria-label={ariaLabel} data-slot="breadcrumb" {...props} />
+  )
+)
+Breadcrumb.displayName = "Breadcrumb"
+
+/**
+ * The trail, an ordered list. It wraps onto a second line when it runs out
+ * of room, rather than overflowing, and a label too long for one line breaks.
+ */
+const BreadcrumbList = React.forwardRef<HTMLOListElement, React.ComponentPropsWithoutRef<"ol">>(
+  ({ className, ...props }, ref) => (
+    <ol
+      ref={ref}
+      data-slot="breadcrumb-list"
+      className={cn(
+        "flex flex-wrap items-center gap-x-2.5 gap-y-1 break-words text-sm text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+)
+BreadcrumbList.displayName = "BreadcrumbList"
+
+/** One step of the trail: a link, the current page or the ellipsis. */
+const BreadcrumbItem = React.forwardRef<HTMLLIElement, React.ComponentPropsWithoutRef<"li">>(
+  ({ className, ...props }, ref) => (
+    <li ref={ref} data-slot="breadcrumb-item" className={cn("inline-flex min-w-0 items-center", className)} {...props} />
+  )
+)
+BreadcrumbItem.displayName = "BreadcrumbItem"
+
+/**
+ * The leading icon — Figma's `Has-Icon`. One text line tall, so it stays on
+ * the first line of a label that wraps; decorative, so hidden from assistive
+ * technology.
+ */
+const ItemIcon = ({ children }: { children: React.ReactNode }) => (
+  <span aria-hidden="true" data-slot="breadcrumb-icon" className={cn("inline-flex h-[1lh] shrink-0 items-center self-start text-foreground", ICON)}>
+    {children}
+  </span>
+)
+
+/** The parts the link and the page share: the icon slot and the 4px gap. */
+const item = "inline-flex min-w-0 items-center gap-1"
+
+export interface BreadcrumbLinkProps extends React.ComponentPropsWithoutRef<"a"> {
+  /**
+   * Render the child element — a router's `Link`, say — as the link, with
+   * these styles and props merged onto it.
+   */
+  asChild?: boolean
+  /**
+   * Leading icon (Figma `Has-Icon`). Sized to 14px and coloured with
+   * `currentColor` on `foreground`, so pass an SVG icon with no size or
+   * colour of its own. Decorative: hidden from assistive technology.
+   */
+  icon?: React.ReactNode
+}
+
+/** A step the reader can go back to. */
+const BreadcrumbLink = React.forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
+  ({ asChild = false, icon, className, children, ...props }, ref) => {
+    const Comp = asChild ? Slot : "a"
+    return (
+      <Comp
+        ref={ref}
+        data-slot="breadcrumb-link"
+        className={cn(
+          item,
+          // Colour and opacity, so a link that wraps a dimmed Badge fades up on hover too.
+          "rounded-[var(--radius-sm)] text-muted-foreground transition-[color,opacity] duration-150 hover:text-foreground motion-reduce:transition-none",
+          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+          className
+        )}
+        {...props}
+      >
+        {icon && <ItemIcon>{icon}</ItemIcon>}
+        <Slottable>{children}</Slottable>
+      </Comp>
+    )
+  }
+)
+BreadcrumbLink.displayName = "BreadcrumbLink"
+
+export interface BreadcrumbPageProps extends React.ComponentPropsWithoutRef<"span"> {
+  /** Leading icon (Figma `Has-Icon`), as on `BreadcrumbLink`. */
+  icon?: React.ReactNode
+}
+
+/** The page the reader is on: the last step, not a link, marked `aria-current="page"`. */
+const BreadcrumbPage = React.forwardRef<HTMLSpanElement, BreadcrumbPageProps>(
+  ({ icon, className, children, ...props }, ref) => (
+    <span
+      ref={ref}
+      aria-current="page"
+      data-slot="breadcrumb-page"
+      className={cn(item, "text-foreground", className)}
+      {...props}
+    >
+      {icon && <ItemIcon>{icon}</ItemIcon>}
+      {children}
+    </span>
+  )
+)
+BreadcrumbPage.displayName = "BreadcrumbPage"
+
+/**
+ * The mark between two steps. A chevron by default, pointing along the
+ * trail: right in LTR, left in RTL. Pass any icon as the child to replace it,
+ * a `SlashIcon` for Figma's Custom Separator; it is sized to 14px the same
+ * way. Hidden from assistive technology: the list already says where one
+ * step ends.
+ */
+const BreadcrumbSeparator = React.forwardRef<HTMLLIElement, React.ComponentPropsWithoutRef<"li">>(
+  ({ className, children, ...props }, ref) => (
+    <li
+      ref={ref}
+      role="presentation"
+      aria-hidden="true"
+      data-slot="breadcrumb-separator"
+      className={cn("inline-flex shrink-0 items-center text-foreground", ICON, className)}
+      {...props}
+    >
+      {children ?? <ChevronRightIcon className="[&:dir(rtl)]:-scale-x-100" />}
+    </li>
+  )
+)
+BreadcrumbSeparator.displayName = "BreadcrumbSeparator"
+
+/**
+ * Where collapsed steps would be. The glyph is hidden; screen readers hear
+ * "More", or "المزيد" under an Arabic `lang`, so they know the trail is
+ * shortened. To reach the hidden steps, put it inside a
+ * `DropdownMenuTrigger` that opens a menu of them, as links.
+ */
+const BreadcrumbEllipsis = React.forwardRef<HTMLSpanElement, React.ComponentPropsWithoutRef<"span">>(
+  ({ className, ...props }, ref) => (
+    <span
+      ref={ref}
+      data-slot="breadcrumb-ellipsis"
+      className={cn("inline-flex size-3.5 shrink-0 items-center justify-center text-foreground", ICON, className)}
+      {...props}
+    >
+      <EllipsisIcon aria-hidden="true" />
+      {/*
+       * Both runs are rendered and CSS keeps the one that matches the nearest
+       * `lang`, as Badge's close label does: right in the server HTML before
+       * any script runs, and it follows a live language change.
+       */}
+      <span className="sr-only [&:lang(ar)]:hidden">More</span>
+      <span className="sr-only hidden [&:lang(ar)]:inline">المزيد</span>
+    </span>
+  )
+)
+BreadcrumbEllipsis.displayName = "BreadcrumbEllipsis"
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+}

package/registry/ui/breadcrumb/index.ts

@@ -0,0 +1,11 @@
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+  type BreadcrumbLinkProps,
+  type BreadcrumbPageProps,
+} from "./breadcrumb"