# fma-ds

> A personal component registry in the shadcn/ui format, built on react-aria-components: components, blocks, libs, hooks and themes copied into your project by the shadcn CLI (not an npm package).

Register the namespace in components.json:

```json
{
  "registries": {
    "@fma-ds": "https://ds.fmartinsandre.dev.br/r/{name}.json"
  }
}
```

Then add items by name: `pnpm dlx shadcn@latest add @fma-ds/button`. Dependencies between items resolve through the same namespace. Everything installs into `fma-ds` folders (`components/fma-ds/`, `hooks/fma-ds/`, `lib/fma-ds/`), so it never collides with the official shadcn components.

The APIs follow React Aria, not Radix: `isDisabled` instead of `disabled`, `onPress` instead of `onClick`, and no `asChild` (use `LinkButton` for a link that looks like a button). Wrap the app in React Aria's `RouterProvider` for client-side links (see the Routing guide).

License: MIT, except for themes adapted from tweakcn (Apache-2.0). Each registry item states its own in meta.license; upstream notices are in https://github.com/fmartins-andre/fma-ds/blob/main/THIRD_PARTY_NOTICES.md.

## Guides

### Compatibility

fma-ds is code you copy, so it runs on your project's toolchain. These are the versions it is built and tested against.

| Requirement | Version | How you get it |
| --- | --- | --- |
| React and React DOM | `>=19.0.0` | Your project |
| Tailwind CSS | `>=4.0.0` | Your project; v3 doesn't work, tokens are CSS-first |
| shadcn CLI | `^4.22.1` | Run with `npx`, or as a dev dependency |
| react-aria-components | `^1.22.1` | Installed by the CLI with each item |

Each item lists the rest of its npm dependencies in its registry file, and the CLI installs them.

Node.js only matters to the shadcn CLI, so use a version it supports. The Node and pnpm versions in this repository's `package.json` apply to working on the registry itself, not to using it.

## Project setup

You need a project initialized for shadcn/ui: a `components.json` and a stylesheet with Tailwind v4. Then follow the [installation steps](/docs).

### Dark mode

Dark mode is on by a `dark` class on an ancestor, usually `<html>`. Every theme defines both palettes, so adding the class is all it takes.

Your stylesheet needs this variant, which the shadcn setup adds. With it, the tokens switch by themselves:

```css
@custom-variant dark (&:is(.dark *));
```

fma-ds doesn't ship a toggle or a provider, and it doesn't read `prefers-color-scheme` by itself: which mode applies is your app's decision.

## Avoid a flash on load

Set the class in an inline script in `<head>`, before the first paint. This one follows the saved choice and falls back to the system preference:

```html
<script>
  try {
    const saved = localStorage.getItem("mode");
    const dark =
      saved === "dark" ||
      (!saved && matchMedia("(prefers-color-scheme: dark)").matches);
    document.documentElement.classList.toggle("dark", dark);
  } catch {}
</script>
```

If your framework renders on the server, add `suppressHydrationWarning` to `<html>`: the class is set before React hydrates.

## Add a toggle

```tsx
function setMode(mode: "light" | "dark") {
  document.documentElement.classList.toggle("dark", mode === "dark");
  localStorage.setItem("mode", mode);
}
```

Portaled overlays render under `<body>`, so keep the class on `<html>` or they will stay in the other mode.

### Routing

Links in fma-ds are react-aria links. Without a router they do a full page load, so wrap your app in React Aria's `RouterProvider` to send them through your router.

It takes `navigate`, called when a link is pressed, and `useHref`, which turns a path into the real `href` (needed when the app runs under a base path).

## TanStack Router

Put it in the root route, around the `<Outlet />`. This site runs this same code:

```tsx
import { Outlet, useRouter } from "@tanstack/react-router";
import { RouterProvider } from "react-aria-components";

// Links outside the app go through the browser.
const isPlainLink = (href: string) => /^([a-z][a-z\d+.-]*:|\/\/)/i.test(href);

function RootComponent() {
  const router = useRouter();
  return (
    <RouterProvider
      navigate={(href) => {
        if (isPlainLink(href)) window.location.assign(href);
        else void router.navigate({ href });
      }}
      useHref={(href) =>
        isPlainLink(href) ? href : router.buildLocation({ href } as never).href
      }
    >
      <Outlet />
    </RouterProvider>
  );
}
```

## React Router

Render it inside the router, because it uses the router's hooks:

```tsx
import { Outlet, useHref, useNavigate } from "react-router";
import { RouterProvider } from "react-aria-components";

export function RootLayout() {
  const navigate = useNavigate();
  return (
    <RouterProvider navigate={navigate} useHref={useHref}>
      <Outlet />
    </RouterProvider>
  );
}
```

## Current page

`RouterProvider` handles navigation only. For active states, pass `aria-current="page"` where the component takes it, or use components that already do, such as `TabNav` and `Pagination`.

### Offline and privacy

fma-ds makes no network requests at runtime, with one exception. There is no telemetry, and themes don't load fonts from a CDN.

This was audited against every published item, looking for `fetch`, `XMLHttpRequest`, `sendBeacon`, WebSockets, remote imports and hard-coded URLs.

## The exception: emoji-picker

`EmojiPicker` downloads its data from `cdn.jsdelivr.net` (a pinned `emojibase-data` release) the first time it opens. To avoid that, do one of these:

- **`data`**: pass the emoji you already have, bundled or loaded on your server. Nothing is fetched.
- **`dataUrl`**: point it at your own copy of `emojibase-data`.
- **`shortcodes={false}`**: skips the optional shortcode requests.

## Fonts

Themes with catalog fonts install them as `@fontsource` packages, imported into your CSS and bundled by your build. A theme using a font outside the catalog says so when installed, and loading that font is up to you.

## Images

`Avatar`, `FileUpload` and similar components only load the URLs you give them. Nothing points to an external image by default.

## Offline-first apps

With the emoji data handled, the components work with no connection. Component code is in your bundle, so it's cached the way the rest of your app is.

### Touch

Controls meet WCAG 2.2 AA for pointer targets (2.5.8): at least 24 by 24 CSS pixels, or spaced far enough apart that a 24px circle on one doesn't touch the next. They are sized for desktop density, so an app used mostly by touch should pick larger sizes.

This was measured in the browser across every Storybook story, counting the invisible hit areas below.

## Sizes

| Control | Hit area |
| --- | --- |
| `Button` | 32px tall; `lg` is 36px, `sm` 28px, `xs` 24px |
| `Input`, `Select` and other fields | 32px tall |
| `Checkbox`, `Radio` | 16px box, 40 by 32px hit area |
| `Slider` thumb | 12px thumb, 28px hit area |

The hit area of the small controls is an `::after` pseudo-element, so give them room: a neighboring control placed inside it takes the press.

## Spaced instead of sized

These stay under 24px and rely on spacing: `Carousel` dots, `CodeBlock` fold toggles, `ColorPicker` swatches and `EmojiPicker` category tabs. Links inside a sentence are exempt, as in `Breadcrumb`.

## Larger targets

For touch-first screens, aim for the 44px of WCAG 2.5.5 (AAA). No size prop reaches it, so set the height where you use the component:

```tsx
<Button className="h-11 px-4">Pay now</Button>
```

### Updating items

The code lives in your project, so nothing updates by itself: you choose when to pull changes and which ones to keep.

Items have no version numbers. Each one has a content hash, which changes whenever its published code does:

```bash
curl -s https://<registry>/r/button.json | jq -r .meta.contentHash
```

Save the hash when you install an item, in a comment or a commit message, and a different value later means there is something new. The CLI rewrites imports on install, so hashing your local copy won't match. To see what changed, open the **Changelog** link on the item's page: it is the Git history of that item.

## Check before overwriting

```bash
npx shadcn@latest add @fma-ds/button --dry-run
npx shadcn@latest add @fma-ds/button --diff
```

`--dry-run` lists what would change, and `--diff` shows the difference for a file. Neither writes anything.

## Apply an update

```bash
npx shadcn@latest add @fma-ds/button --overwrite
```

This replaces your copy, including local edits. Commit first, then review the diff in git and bring your changes back. Keeping customizations in wrapper components, instead of editing the files, makes updates much easier.

### Contributing

fma-ds is a personal registry, developed in the open. Issues are welcome, and new components start from a real need in an app.

## Proposing a change

1. Open an [issue](https://github.com/fmartins-andre/fma-ds/issues) describing the need: what the app has to do, not how it should look.
2. Check that no existing item covers it. Prefer a variant or a prop over a new component.
3. Wait for agreement before opening a pull request, unless it's a small fix.

## Scope of the blocks

Blocks come from what real apps needed, mostly SaaS screens such as sign-in, pricing, billing and settings. They are not a general application kit, so a block enters when an app needs it, not to complete the catalog. Components stay general.

## What a new item needs

- A folder in `packages/ds/src/core/<name>/` with the component, `meta.json` and a story.
- React Aria for interaction, and the existing tokens: hover, focus and selection use `accent`.
- English default text, overridable through props.
- Stories that show real usage, because they are the examples on this site, with `play` functions for interaction tests.
- Accessible names, keyboard support and no automated accessibility violations.

The generated registry files are committed with the change. Before opening a pull request, run:

```bash
pnpm lint && pnpm type-check && pnpm test && pnpm --filter @fma-ds/ds build
```

## Going deeper

[`CONTRIBUTING.md`](https://github.com/fmartins-andre/fma-ds/blob/main/CONTRIBUTING.md) covers the environment, the anatomy of a component, themes and the Git workflow.

## Components

### Accordion

A vertically stacked set of headers that expand to reveal or hide associated content. Supports single or multiple items open at once.

- Install: `pnpm dlx shadcn@latest add @fma-ds/accordion`
- Registry item: https://ds.fmartinsandre.dev.br/r/accordion.json
- Docs: https://ds.fmartinsandre.dev.br/components/accordion
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/fma-ds/accordion";

export function AccordionDemo() {
  return (
    <div className="w-96">
      <Accordion>
        <AccordionItem id="item-1">
          <AccordionTrigger>Is it accessible?</AccordionTrigger>
          <AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
        </AccordionItem>
        <AccordionItem id="item-2">
          <AccordionTrigger>Is it styled?</AccordionTrigger>
          <AccordionContent>
            Yes. It comes with default styles that match the other components' aesthetic.
          </AccordionContent>
        </AccordionItem>
        <AccordionItem id="item-3">
          <AccordionTrigger>Is it animated?</AccordionTrigger>
          <AccordionContent>
            Yes. It's animated by default via CSS height transitions.
          </AccordionContent>
        </AccordionItem>
      </Accordion>
    </div>
  );
}
```

### Alert

A callout for important, static information — supports an icon, title, description, and an optional action, with semantic variants (destructive/info/success/warning/invert) and a `brand` variant for announcements and promos in the theme's second identity color.

- Install: `pnpm dlx shadcn@latest add @fma-ds/alert`
- Registry item: https://ds.fmartinsandre.dev.br/r/alert.json
- Docs: https://ds.fmartinsandre.dev.br/components/alert
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { Alert, AlertDescription, AlertTitle } from "@/components/fma-ds/alert";

export function AlertDemo() {
  return (
    <Alert>
      <AlertTitle>Heads up!</AlertTitle>
      <AlertDescription>You can add components to your app using the CLI.</AlertDescription>
    </Alert>
  );
}
```

### Alert Dialog

A modal dialog that interrupts the user with important content and expects an explicit response (e.g. confirming a destructive action) — unlike Dialog, it can't be dismissed by clicking outside or pressing Escape.

- Install: `pnpm dlx shadcn@latest add @fma-ds/alert-dialog`
- Registry item: https://ds.fmartinsandre.dev.br/r/alert-dialog.json
- Docs: https://ds.fmartinsandre.dev.br/components/alert-dialog
- npm: cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/fma-ds/alert-dialog";
import { Button } from "@/components/fma-ds/button";

export function AlertDialogDemo() {
  return (
    <AlertDialogTrigger>
      <Button variant="outline">Open</Button>
      <AlertDialog>
        <AlertDialogHeader>
          <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
          <AlertDialogDescription>
            This action cannot be undone. This will permanently delete your account and remove your
            data from our servers.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction>Continue</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialog>
    </AlertDialogTrigger>
  );
}
```

### Aspect Ratio

Constrains content (typically an image or video) to a fixed width/height ratio, so it scales without distortion or layout shift.

- Install: `pnpm dlx shadcn@latest add @fma-ds/aspect-ratio`
- Registry item: https://ds.fmartinsandre.dev.br/r/aspect-ratio.json
- Docs: https://ds.fmartinsandre.dev.br/components/aspect-ratio
- npm: cn@^0.5.0

```tsx
import { AspectRatio } from "@/components/fma-ds/aspect-ratio";

export function AspectRatioDemo() {
  return (
    <div className="w-80">
      <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-md bg-muted">
        <img
          src="https://images.unsplash.com/photo-1576075796033-848c2a5f3696?w=800&dpr=2&q=80"
          alt="Landscape"
          className="size-full object-cover"
        />
      </AspectRatio>
    </div>
  );
}
```

### Attachment

A file/attachment chip for chat-style UIs — shows a name, optional upload progress or error state, and an independently clickable remove action.

- Install: `pnpm dlx shadcn@latest add @fma-ds/attachment`
- Registry item: https://ds.fmartinsandre.dev.br/r/attachment.json
- Docs: https://ds.fmartinsandre.dev.br/components/attachment
- npm: class-variance-authority@^0.7.1, cn@^0.5.0
- Registry: @fma-ds/button

```tsx
import { FileTextIcon, XIcon } from "lucide-react";
import type * as React from "react";
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/fma-ds/attachment";

function FileAttachment({
  name = "sales-dashboard.pdf",
  description = "PDF · 2.4 MB",
  icon = <FileTextIcon />,
  ...props
}: React.ComponentProps<typeof Attachment> & {
  name?: string;
  description?: string;
  icon?: React.ReactNode;
}) {
  return (
    <Attachment {...props}>
      <AttachmentMedia>{icon}</AttachmentMedia>
      <AttachmentContent>
        <AttachmentTitle>{name}</AttachmentTitle>
        <AttachmentDescription>{description}</AttachmentDescription>
      </AttachmentContent>
      <AttachmentActions>
        <AttachmentAction aria-label={`Remove ${name}`}>
          <XIcon />
        </AttachmentAction>
      </AttachmentActions>
    </Attachment>
  );
}

export function AttachmentDemo() {
  return (
    <div className="w-full min-w-sm max-w-md">
      <FileAttachment state="done" orientation="horizontal" />
    </div>
  );
}
```

### Avatar

A user/entity image with a text or icon fallback for when the image fails to load. Composes into overlapping groups for showing multiple participants.

- Install: `pnpm dlx shadcn@latest add @fma-ds/avatar`
- Registry item: https://ds.fmartinsandre.dev.br/r/avatar.json
- Docs: https://ds.fmartinsandre.dev.br/components/avatar
- npm: cn@^0.5.0

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/fma-ds/avatar";

export function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  );
}
```

### Badge

A small label for status, count, or category — inline with text or attached to another element.

- **Semantic variants**: info, success, warning, destructive and invert, in solid, `-light` and `-outline` styles.
- **Neutral**: `muted`/`muted-outline` for inactive or pending states.
- **Brand**: `brand`, `brand-light`, `brand-outline` and `brand-dot` in the theme's second identity color, for identity labels ("New", "AI", "Pro"), never for status.
- **Dots**: a `*-dot` family (primary, secondary, brand, success, warning, info, destructive, muted) that shows a colored dot before plain text, for select items and dense lists.
- **Shape**: size and radius options.

Can also render as a link.

- Install: `pnpm dlx shadcn@latest add @fma-ds/badge`
- Registry item: https://ds.fmartinsandre.dev.br/r/badge.json
- Docs: https://ds.fmartinsandre.dev.br/components/badge
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { Badge } from "@/components/fma-ds/badge";

export function BadgeDemo() {
  return <Badge>Badge</Badge>;
}
```

### Breadcrumb

Shows the user's current location within a hierarchy, as a trail of links back to parent pages, with an ellipsis for collapsing long paths.

- Install: `pnpm dlx shadcn@latest add @fma-ds/breadcrumb`
- Registry item: https://ds.fmartinsandre.dev.br/r/breadcrumb.json
- Docs: https://ds.fmartinsandre.dev.br/components/breadcrumb
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
} from "@/components/fma-ds/breadcrumb";

export function BreadcrumbDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbItem>
          <BreadcrumbLink href="/components">Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}
```

### Bubble

A single chat message bubble — start/end alignment for sent vs. received, several color variants, and an optional reactions pill overlaid on a corner.

- Install: `pnpm dlx shadcn@latest add @fma-ds/bubble`
- Registry item: https://ds.fmartinsandre.dev.br/r/bubble.json
- Docs: https://ds.fmartinsandre.dev.br/components/bubble
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { Bubble, BubbleContent } from "@/components/fma-ds/bubble";

export function BubbleDemo() {
  return (
    <Bubble>
      <BubbleContent>Hey, how's the new design system coming along?</BubbleContent>
    </Bubble>
  );
}
```

### Button

Displays a button, or a component that looks like one, with a set of visual variants and sizes. Also exports LinkButton (react-aria-components' Link, same variants) for link-as-button use cases.

- Install: `pnpm dlx shadcn@latest add @fma-ds/button`
- Registry item: https://ds.fmartinsandre.dev.br/r/button.json
- Docs: https://ds.fmartinsandre.dev.br/components/button
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Button } from "@/components/fma-ds/button";

export function ButtonDemo() {
  return <Button>Button</Button>;
}
```

### Button Group

Visually joins a row (or column) of buttons into one connected control, with shared borders and rounded end corners. Can include a separator or a plain text segment.

- Install: `pnpm dlx shadcn@latest add @fma-ds/button-group`
- Registry item: https://ds.fmartinsandre.dev.br/r/button-group.json
- Docs: https://ds.fmartinsandre.dev.br/components/button-group
- npm: class-variance-authority@^0.7.1, cn@^0.5.0
- Registry: @fma-ds/separator

```tsx
import { Button } from "@/components/fma-ds/button";
import { ButtonGroup } from "@/components/fma-ds/button-group";

export function ButtonGroupDemo() {
  return (
    <ButtonGroup>
      <Button variant="outline">Copy</Button>
      <Button variant="outline">Paste</Button>
      <Button variant="outline">Cut</Button>
    </ButtonGroup>
  );
}
```

### Calendar

A date grid for selecting a single date, multiple dates or a range.

- **Navigation**: the header opens month and year grids for fast navigation.
- **Granularity**: `granularity` switches the selection to whole months or years.
- **Availability**: `unavailableRanges` blocks booked spans, and an already-selected value that becomes blocked travels to the nearest available date.

- Install: `pnpm dlx shadcn@latest add @fma-ds/calendar`
- Registry item: https://ds.fmartinsandre.dev.br/r/calendar.json
- Docs: https://ds.fmartinsandre.dev.br/components/calendar
- npm: @internationalized/date@^3.12.4, class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/select, @fma-ds/use-available-date-correction, @fma-ds/date-granularity, @fma-ds/interval-helpers, @fma-ds/types

```tsx
import { Calendar } from "@/components/fma-ds/calendar";

export function CalendarDemo() {
  return <Calendar aria-label="Event date" />;
}
```

### Card

A container for grouping related content, with header, title, description, action, content, and footer slots. Supports a compact size="sm" variant.

- Install: `pnpm dlx shadcn@latest add @fma-ds/card`
- Registry item: https://ds.fmartinsandre.dev.br/r/card.json
- Docs: https://ds.fmartinsandre.dev.br/components/card
- npm: cn@^0.5.0

```tsx
import { Button } from "@/components/fma-ds/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/fma-ds/card";

export function CardDemo() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Project alpha</CardTitle>
        <CardDescription>Last updated 2 hours ago</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-muted-foreground">Card content goes here.</p>
      </CardContent>
      <CardFooter>
        <Button size="sm">Open</Button>
      </CardFooter>
    </Card>
  );
}
```

### Carousel

A carousel for cycling through slides (images, cards, or any content) with keyboard, swipe, and button navigation.

Built on embla-carousel-react; `CarouselPrevious`/`CarouselNext` are `Button`s wired to the carousel API.

- **Autoplay**: `autoplay` (`true` or `{ delay }`, 5000 ms by default) advances on its own and wraps to the first slide. Rotation pauses while the pointer is over the carousel or focus is inside it, and starts paused under reduced motion.
- **`CarouselAutoplayToggle`**: pause/resume — required for moving content by WCAG 2.2.2; a dev warning flags its absence.
- **`CarouselDots`**: one dot per slide; marks the current one and goes to a slide on press.
- **Announcements**: slide changes are announced (`aria-live`) only when not rotating.

The toggle and dots are not positioned; place them where they fit.

Built-in labels are in English; translate them with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/carousel`
- Registry item: https://ds.fmartinsandre.dev.br/r/carousel.json
- Docs: https://ds.fmartinsandre.dev.br/components/carousel
- npm: cn@^0.5.0, embla-carousel-react@^8.6.0, lucide-react@^1.61.0
- Registry: @fma-ds/button

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/fma-ds/carousel";

export function CarouselDemo() {
  return (
    <Carousel className="w-full max-w-xs">
      <CarouselContent>
        {Array.from({ length: 5 }, (_, index) => (
          // biome-ignore lint/suspicious/noArrayIndexKey: fixed-length demo slides, index IS the identity
          <CarouselItem key={index}>
            <div className="flex aspect-square items-center justify-center rounded border bg-card p-6">
              <span className="font-semibold text-4xl">{index + 1}</span>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

### Chart

Composable chart primitives (ChartContainer, ChartTooltip, ChartLegend) wrapping Recharts, themed via CSS custom properties from a ChartConfig. Supports area, bar, line, and pie charts.

- Install: `pnpm dlx shadcn@latest add @fma-ds/chart`
- Registry item: https://ds.fmartinsandre.dev.br/r/chart.json
- Docs: https://ds.fmartinsandre.dev.br/components/chart
- npm: cn@^0.5.0, recharts@3.10.1

```tsx
import { Area, AreaChart, CartesianGrid, XAxis } from "recharts";
import {
  type ChartConfig,
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/fma-ds/chart";

const multiSeriesData = [
  { month: "January", desktop: 186, mobile: 80 },
  { month: "February", desktop: 305, mobile: 200 },
  { month: "March", desktop: 237, mobile: 120 },
  { month: "April", desktop: 73, mobile: 190 },
  { month: "May", desktop: 209, mobile: 130 },
  { month: "June", desktop: 214, mobile: 140 },
];

const multiSeriesConfig = {
  desktop: { label: "Desktop", color: "var(--chart-1)" },
  mobile: { label: "Mobile", color: "var(--chart-2)" },
} satisfies ChartConfig;

export function ChartStackedAreaChart() {
  return (
    <ChartContainer config={multiSeriesConfig}>
      <AreaChart accessibilityLayer data={multiSeriesData} margin={{ left: 12, right: 12 }}>
        <CartesianGrid vertical={false} />
        <XAxis
          dataKey="month"
          tickLine={false}
          axisLine={false}
          tickMargin={8}
          tickFormatter={(value) => value.slice(0, 3)}
        />
        <ChartTooltip cursor={false} content={<ChartTooltipContent indicator="dot" />} />
        <Area
          dataKey="mobile"
          type="natural"
          fill="var(--color-mobile)"
          fillOpacity={0.4}
          stroke="var(--color-mobile)"
          stackId="a"
        />
        <Area
          dataKey="desktop"
          type="natural"
          fill="var(--color-desktop)"
          fillOpacity={0.4}
          stroke="var(--color-desktop)"
          stackId="a"
        />
      </AreaChart>
    </ChartContainer>
  );
}
```

### Checkbox

A control for a single on/off/indeterminate value.

Pair it with an external `Label` (via `id`/`htmlFor`) laid out as a flex row, rather than passing label text as children.

- **`CheckboxGroup`**: gathers several under one label and a `value` array (react-aria `CheckboxGroup`; each `Checkbox` takes a `value`).
- **`CheckboxCard`**: a choice card — the whole card is the checkbox, its children are the content (an `IconTile`, `FieldContent` with `FieldTitle` and `FieldDescription`) and a square indicator sits at the end. Selected cards take a `primary` tint, hovered ones `accent`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/checkbox`
- Registry item: https://ds.fmartinsandre.dev.br/r/checkbox.json
- Docs: https://ds.fmartinsandre.dev.br/components/checkbox
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/field

```tsx
import { Checkbox } from "@/components/fma-ds/checkbox";
import { Label } from "@/components/fma-ds/label";

export function CheckboxDemo() {
  return (
    <div className="flex items-center gap-2">
      <Checkbox id="terms" />
      <Label htmlFor="terms">Accept terms and conditions</Label>
    </div>
  );
}
```

### Code Block

A code block with shiki syntax highlighting, for docs and AI chat UIs. `<CodeBlock code={code} language="tsx" />` is complete on its own.

### Parts

- **`CodeBlockHeader`**: the chrome — `CodeBlockTitle`, `CodeBlockLanguage`, `CodeBlockWrapToggle`, `CodeBlockCopyButton`, `CodeBlockDownloadButton`.
- **`CodeBlockExpandButton`**: with `maxLines`.
- **`CodeBlockContent`**: to place inside your own scroll container.
- **`CodeBlockLineActions`**: one action group on the hovered or focused line.

A pinned copy button stays put while the code scrolls.

### Highlighting

shiki loads lazily on the first highlight (JavaScript regex engine, no WebAssembly) through the `code-block-highlight` lib. Pass `lines` from `highlightCode()` in a server loader, or `highlight={false}`, to never load it. Light and dark token colors switch with the theme.

### Lines

- **Marking**: `showLineNumbers`/`startLine`, `highlightedLines`/`highlightedWords`/`focusedLines` (line specs like `"2-4,7"`), `diff` and `lineLevels` — or shiki `transformers`.
- **`streaming`**: grows the code with a caret and stick-to-bottom, re-rendering only changed lines.
- **`foldable`**: folds by indentation.
- **`selectable`**: turns lines into a multi-select listbox.

- Install: `pnpm dlx shadcn@latest add @fma-ds/code-block`
- Registry item: https://ds.fmartinsandre.dev.br/r/code-block.json
- Docs: https://ds.fmartinsandre.dev.br/components/code-block
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button, @fma-ds/copy-button, @fma-ds/code-block-highlight

```tsx
import { CodeBlock, CodeBlockCopyButton } from "@/components/fma-ds/code-block";

const CODE = `import { useMemo } from "react";

type Item = { price: number; quantity: number };

export function useTotals(items: Item[]) {
  return useMemo(() => {
    const subtotal = items.reduce((sum, item) => {
      return sum + item.price * item.quantity;
    }, 0);
    const tax = subtotal * 0.08;
    return { subtotal, tax, total: subtotal + tax };
  }, [items]);
}`;

export function CodeBlockDemo() {
  return (
    <CodeBlock code={CODE} language="tsx" className="max-w-2xl">
      <CodeBlockCopyButton />
    </CodeBlock>
  );
}
```

### Collapsible

Shows or hides a single section of content behind a trigger. A thin wrapper around react-aria-components' Disclosure — for several mutually-exclusive sections, use Accordion instead.

- Install: `pnpm dlx shadcn@latest add @fma-ds/collapsible`
- Registry item: https://ds.fmartinsandre.dev.br/r/collapsible.json
- Docs: https://ds.fmartinsandre.dev.br/components/collapsible
- npm: react-aria-components@^1.22.1

```tsx
import { InfoIcon } from "lucide-react";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/fma-ds/collapsible";

export function CollapsibleDemo() {
  return (
    <Collapsible className="w-96">
      <CollapsibleTrigger className="flex gap-2">
        <h3 className="font-semibold">Can I use this in my project?</h3>
        <InfoIcon className="size-6" />
      </CollapsibleTrigger>
      <CollapsibleContent>
        Yes. Free to use for personal and commercial projects. No attribution required.
      </CollapsibleContent>
    </Collapsible>
  );
}
```

### Color Picker

A composable color picker: `ColorPicker` holds the color and shares it with parts laid out in any way.

Without children, `ColorPicker` is a swatch that opens the default panel in a popover.

### Parts

- **`ColorPickerTrigger`** + **`ColorPickerContent`**: a popover.
- **`ColorPickerPanel`**: a column of controls, or a standalone inline picker.
- **`ColorPickerArea`**: OKLCH chroma × lightness at the hue (the part sRGB can't show is left blank), or HSB saturation × brightness.
- **`ColorPickerWheel`**: a hue ring whose children fill the square inside it.
- **`ColorPickerSlider`**: any channel of OKLCH, HSL, HSB or RGB, or alpha; horizontal or vertical, painted with the colors it reaches.
- **`ColorPickerFields`**: a format menu with hex or per-channel fields; `ColorPickerChannelInput` for a single channel.
- **`ColorPickerInput`**: a text field taking any CSS color (Escape reverts), with a swatch that opens the popover against it.
- **`ColorPickerSwatches`**: presets, Tailwind's palette by default; `ColorPickerSwatch` for one.
- **Extras**: `ColorPickerValue`, `ColorPickerCopy`, `ColorPickerEyeDropper`, `ColorPickerPreview` and `ColorPickerFixContrast`.
- **`useColorPicker`**: reads and sets the color from custom parts.

### Value

- **Events**: `onChange` fires while dragging and `onChangeEnd` once an interaction ends.
- **`format`**: what they emit — `oklch` by default, `hex`, `rgb` or `hsl`; `alpha` adds opacity controls.
- **Forms**: `name` submits the value with a form (a hidden input), and a form reset restores the starting color.

### Contrast

Given a background (`contrastWith`), every part shows contrast: the area hatches what fails AA and draws the AA and AAA thresholds across it, tracks hatch and mark them, presets failing AA are hatched, the preview shows the WCAG ratio, and "Fix to AA/AAA" jumps to the nearest passing lightness keeping the hue.

`labels` translates every text it shows or announces.

- Install: `pnpm dlx shadcn@latest add @fma-ds/color-picker`
- Registry item: https://ds.fmartinsandre.dev.br/r/color-picker.json
- Docs: https://ds.fmartinsandre.dev.br/components/color-picker
- npm: cn@^0.5.0, culori@^4.0.2, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/copy-button, @fma-ds/input, @fma-ds/input-group, @fma-ds/popover, @fma-ds/select, @fma-ds/color-contrast

```tsx
import { useState } from "react";
import { ColorPicker } from "@/components/fma-ds/color-picker";

export function ColorPickerDemo() {
  const [value, setValue] = useState("oklch(0.6 0.2 260)");
  return (
    <div className="flex items-center gap-3">
      <ColorPicker label="Primary color" value={value} onChange={setValue} />
      <code className="text-xs">{value}</code>
    </div>
  );
}
```

### Combobox

A searchable, filterable select combining a text input with a listbox popover. Supports single selection (ComboboxValue) or a multi-select tag/chip input (ComboboxChips + ComboboxChip).

- Install: `pnpm dlx shadcn@latest add @fma-ds/combobox`
- Registry item: https://ds.fmartinsandre.dev.br/r/combobox.json
- Docs: https://ds.fmartinsandre.dev.br/components/combobox
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/input-group

```tsx
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/fma-ds/combobox";

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"];

export function ComboboxDemo() {
  return (
    <Combobox>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList items={frameworks.map((item) => ({ id: item, name: item }))}>
          {(item) => <ComboboxItem id={item.id}>{item.name}</ComboboxItem>}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}
```

### Command

A searchable list of commands or actions, filtered live as you type.

- **`CommandDialog`**: wraps it in a `Dialog` for a full command-palette (⌘K) pattern.
- **Empty state**: pass `CommandEmpty` through `CommandList`'s `renderEmptyState`, not as a child — the list only accepts items, groups and separators.

- Install: `pnpm dlx shadcn@latest add @fma-ds/command`
- Registry item: https://ds.fmartinsandre.dev.br/r/command.json
- Docs: https://ds.fmartinsandre.dev.br/components/command
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/dialog, @fma-ds/input-group

```tsx
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
} from "@/components/fma-ds/command";

export function CommandDemo() {
  return (
    <Command className="w-96 rounded-lg border shadow-md">
      <CommandInput placeholder="Type a command or search..." />
      {/* The empty state goes through renderEmptyState: a plain child in the
          collection would empty the whole list. */}
      <CommandList renderEmptyState={() => <CommandEmpty>No results found.</CommandEmpty>}>
        <CommandGroup heading="Suggestions">
          <CommandItem id="calendar">Calendar</CommandItem>
          <CommandItem id="search-emoji">Search Emoji</CommandItem>
          <CommandItem id="calculator" isDisabled>
            Calculator
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Settings">
          <CommandItem id="profile">Profile</CommandItem>
          <CommandItem id="billing">Billing</CommandItem>
          <CommandItem id="settings">Settings</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  );
}
```

### Confirm Dialog

A ready-made yes/no dialog on top of the `use-dialog-promise` hook.

`const ask = useDialogPromise<D>()`, render `<ConfirmDialog controller={ask} title=… />` once, then `const result = await ask.open(data)` and check `result.status`: `confirmed`, `cancelled`, or `dismissed` by Escape.

- **Content**: `title` and `description` take the opened `data` when given as functions; `media` adds an icon.
- **Actions**: `tone="destructive"` marks a destructive action; `cancelLabel={null}` leaves a single action.
- **`onConfirm`**: runs with the dialog open and the button pending; if it throws, the dialog stays open with `errorMessage`.

For dialogs that collect a value or hold a form, render your own dialog with the same hook and call `confirm(value)`.

Labels default to English; pass translations through the label props.

- Install: `pnpm dlx shadcn@latest add @fma-ds/confirm-dialog`
- Registry item: https://ds.fmartinsandre.dev.br/r/confirm-dialog.json
- Docs: https://ds.fmartinsandre.dev.br/components/confirm-dialog
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/alert-dialog, @fma-ds/button, @fma-ds/use-dialog-promise

```tsx
import { BanIcon } from "lucide-react";
import * as React from "react";
import { Button } from "@/components/fma-ds/button";
import { ConfirmDialog } from "@/components/fma-ds/confirm-dialog";
import { useDialogPromise } from "@/hooks/fma-ds/use-dialog-promise";

export function ConfirmDialogDemo() {
  const block = useDialogPromise<{ name: string }>();
  const [status, setStatus] = React.useState("Ativo");

  async function handleBlock() {
    const result = await block.open({ name: "Padaria Pão Quente" });
    if (result.status === "confirmed") setStatus("Bloqueado");
  }

  return (
    <div className="flex flex-col items-center gap-3">
      <p className="text-sm">Situação: {status}</p>
      <Button variant="outline" onPress={handleBlock}>
        Bloquear cliente
      </Button>
      <ConfirmDialog
        controller={block}
        tone="destructive"
        media={<BanIcon />}
        title={(data) => `Bloquear ${data?.name}?`}
        description="O cliente perde o acesso ao gestor de pedidos até ser reativado."
        confirmLabel="Bloquear"
        cancelLabel="Cancelar"
      />
    </div>
  );
}
```

### Context Menu

A menu that opens on right-click (or long-press on touch) instead of a regular trigger click. Supports nested submenus, separators, and keyboard shortcut display.

- Install: `pnpm dlx shadcn@latest add @fma-ds/context-menu`
- Registry item: https://ds.fmartinsandre.dev.br/r/context-menu.json
- Docs: https://ds.fmartinsandre.dev.br/components/context-menu
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import { Pressable } from "react-aria-components";
import { ContextMenu, ContextMenuItem, ContextMenuTrigger } from "@/components/fma-ds/context-menu";

export function ContextMenuDemo() {
  return (
    <ContextMenuTrigger>
      <Pressable>
        <div
          role="button"
          className="flex h-48 w-96 items-center justify-center rounded-md border border-dashed bg-accent text-sm"
        >
          Right click here
        </div>
      </Pressable>
      <ContextMenu className="w-32">
        <ContextMenuItem id="profile">Profile</ContextMenuItem>
        <ContextMenuItem id="billing">Billing</ContextMenuItem>
        <ContextMenuItem id="team">Team</ContextMenuItem>
        <ContextMenuItem id="subscription">Subscription</ContextMenuItem>
      </ContextMenu>
    </ContextMenuTrigger>
  );
}
```

### Copy Button

An icon button that copies a value too long to type (protocol, tracking code, Pix code, token) to the clipboard.

- **Feedback**: the icon turns into a check, or a cross on failure, for a moment, and the outcome is announced in a separate live region.
- **Labels**: translatable; an optional tooltip shows them.
- **`useCopyToClipboard`**: also exported, for other triggers such as a menu item.

- Install: `pnpm dlx shadcn@latest add @fma-ds/copy-button`
- Registry item: https://ds.fmartinsandre.dev.br/r/copy-button.json
- Docs: https://ds.fmartinsandre.dev.br/components/copy-button
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button, @fma-ds/tooltip

```tsx
import { CopyButton } from "@/components/fma-ds/copy-button";

export function CopyButtonDemo() {
  return <CopyButton value="PROT-2025-000184273" />;
}
```

### Credit Card

A payment card drawn from its data, to show a saved card or preview one while it's typed.

- **Front**: the chip, the issuer's logo and color, the number padded with `•` and grouped by issuer (Amex 4-6-5), the holder and the expiry.
- **Back**: the stripe, the signature panel and the security code.

### Props

- **Data**: `number`, `name`, `expiry` (`MM/YY`, `MM/YYYY` or digits only) and `cvc` are plain strings. `*` or `x` in `number` hide digits of a saved card.
- **`issuer`**: `visa`, `mastercard`, `amex`… — pass it for a saved card; by default it is detected from the number.
- **`focused`**: `number`, `name`, `expiry` or `cvc` highlights the field being typed, and `cvc` turns the card over (Amex keeps its code on the front). With reduced motion it turns without the 3D spin.
- **Size**: its width sets its size (`w-72` by default) and the text scales with it.
- **`labels`**: translates the captions and the accessible name. The card is one `role="img"` ("Visa card ending in 4242, expires 12/28").

Logos for Visa, Mastercard, Elo, American Express, Hipercard, Diners Club, Discover and JCB; other issuers show their name on the theme gray.

Issuer detection and the form's validation (number, expiry, security code) live in the `credit-card-validation` lib, usable without the card. Pair the number field with the `credit-card` mask, which follows the issuer too.

- Install: `pnpm dlx shadcn@latest add @fma-ds/credit-card`
- Registry item: https://ds.fmartinsandre.dev.br/r/credit-card.json
- Docs: https://ds.fmartinsandre.dev.br/components/credit-card
- npm: cn@^0.5.0
- Registry: @fma-ds/credit-card-validation

```tsx
import { CreditCard } from "@/components/fma-ds/credit-card";

export function CreditCardDemo() {
  return <CreditCard number="4111 1111 1111 1111" name="Maria Silva" expiry="12/28" cvc="123" />;
}
```

### Data Grid

A data grid driven by a TanStack Table v9 instance and rendered with react-aria's `Table`, which brings cell keyboard navigation, `aria-sort`, selection, column resizing, row drag and drop and virtualization.

### Table

Create the table with `useTable({ features: dataGridFeatures, ... })`. The exported features cover sorting, filtering with facets, pagination, selection, row expanding (tree rows from `getSubRows`), row and column pinning, ordering, visibility and sizing, with client-side row models. For server-side data (or to show every row), set `manualSorting`/`manualFiltering`/`manualPagination`.

Column `meta` takes:

- **`headerTitle`**, **`headerClassName`** and **`cellClassName`**.
- **`skeleton`**: the cell shown in loading rows.
- **`autoSize`**: the column takes the remaining width (not measured from content).
- **`headerColSpan`**: the header spans the next visible columns on its pin side, e.g. "Quantity" over the amount and its unit. Covered headers take its accessible name and the last one keeps the resize handle.

### Parts

Wrap them in `DataGrid table={table} recordCount={…}`:

- **`DataGridTable`** and **`DataGridPagination`**.
- **`DataGridColumnHeader`**: sort indicator, plus a menu for pinning, moving and visibility when `tableLayout` enables them.
- **`DataGridColumnVisibility`**: a column visibility menu.
- **`DataGridColumnFilter`**: faceted; use `filterFn: "arrHas"`.
- **`DataGridRowSelect`**: a row checkbox, with `enableRowSelection`.
- **`DataGridRowPin`**: pins to the top, or the bottom with `position="bottom"`.
- **`DataGridRowActions`**: a row's actions as `DropdownMenuItem`s behind a menu button, named from `rowLabel`. It doesn't trigger `onRowClick`, and with no items it shows a disabled "no actions" entry.
- **`DataGridRowDragHandle`**: with `onRowsReorder`.
- **`DataGridRowExpand`**: shows `getSubRows` children, indented by depth — or, with `getRowCanExpand` and `DataGridTable`'s `renderExpandedRow`, a full-width details row.
- **`DataGridSelectionBar`**: shows while rows are selected — the count (announced, with how many are on other pages), your bulk actions as children and "Clear selection".

### Rows

- **`onRowClick`**: makes rows actionable (click or Enter).
- **`onRowHover`**: fires when the pointer enters a row, e.g. to prefetch its details.
- **`isLoading`**: shows skeleton rows (`meta.skeleton`) or a spinner.
- **Footer**: `DataGridTable`'s `footerContent` takes footer rows (`DataGridTableFootRow` with `DataGridTableFootRowCell`, `colSpan` to span columns); `tableLayout.footerBackground` tints them.

### Infinite scroll

`DataGridTable`'s `onFetchMore` fires near the end of the loaded rows (`fetchMoreScrollOffset`, in viewport heights), `isFetchingMore` shows a loading row and `hasMore={false}` stops it with `allRowsLoadedMessage`. Works with `isVirtualized`.

### Layout and styling

- **`tableLayout.columnsDraggable`**: lets users drag headers to reorder columns; keyboard users use the header menu's move actions, and pinned columns stay put.
- **`tableLayout`**: also takes `rowRounded`, `headerBorder` and `columnsResizeMode` (`"onEnd"` commits the width on release and draws a line at the pointer while dragging).
- **`tableClassNames`**: adds classes to parts of the table (`base`, `header`, `headerSticky`, `body`, `bodyRow`, `footer`, `edgeCell`).
- **Surfaces**: pinned cells and sticky headers paint `--data-grid-surface` (else `--card` inside a `Card`, else `--background`) and carry `data-pinned`/`data-last-col`.

### i18n

The `i18n` prop on `DataGrid` replaces every built-in string (`{ labels: { sortAscending, rowsPerPage, paginationInfo: ({ from, to, count }) => …, goToPage: (page) => …, … } }`, defaults in `defaultDataGridI18n`). Specific props like `emptyMessage` or the pagination labels still win.

- Install: `pnpm dlx shadcn@latest add @fma-ds/data-grid`
- Registry item: https://ds.fmartinsandre.dev.br/r/data-grid.json
- Docs: https://ds.fmartinsandre.dev.br/components/data-grid
- npm: @tanstack/react-table@^9.3.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/badge, @fma-ds/button, @fma-ds/checkbox, @fma-ds/dropdown-menu, @fma-ds/input, @fma-ds/popover, @fma-ds/select, @fma-ds/skeleton, @fma-ds/spinner

```tsx
import {
  type ColumnDef,
  type ColumnFiltersState,
  type ColumnOrderState,
  type ColumnPinningState,
  type ColumnVisibilityState,
  type PaginationState,
  type RowPinningState,
  type RowSelectionState,
  type SortingState,
  type Table,
  useTable,
} from "@tanstack/react-table";
import * as React from "react";
import { Badge } from "@/components/fma-ds/badge";
import {
  DataGrid,
  DataGridColumnHeader,
  DataGridContainer,
  type DataGridFeatures,
  type DataGridI18nOverrides,
  type DataGridLayout,
  DataGridPagination,
  DataGridRowExpand,
  DataGridRowSelect,
  DataGridTable,
  type DataGridTableClassNames,
  dataGridFeatures,
} from "@/components/fma-ds/data-grid";
import { Skeleton } from "@/components/fma-ds/skeleton";

type User = {
  id: string;
  name: string;
  role: string;
  status: "Active" | "Inactive" | "Pending";
  joined: string;
};

const USERS: User[] = [
  {
    id: "USR-001",
    name: "Alice Martin",
    role: "Frontend Engineer",
    status: "Active",
    joined: "2023-01-15",
  },
  {
    id: "USR-002",
    name: "Bob Chen",
    role: "Product Manager",
    status: "Active",
    joined: "2022-07-08",
  },
  {
    id: "USR-003",
    name: "Carol Smith",
    role: "UX Designer",
    status: "Inactive",
    joined: "2021-11-22",
  },
  {
    id: "USR-004",
    name: "David Kim",
    role: "Backend Engineer",
    status: "Active",
    joined: "2023-05-03",
  },
  {
    id: "USR-005",
    name: "Eva Brown",
    role: "Data Analyst",
    status: "Pending",
    joined: "2024-02-14",
  },
  {
    id: "USR-006",
    name: "Frank Lee",
    role: "DevOps Engineer",
    status: "Active",
    joined: "2022-03-19",
  },
  {
    id: "USR-007",
    name: "Grace Liu",
    role: "QA Engineer",
    status: "Inactive",
    joined: "2023-09-01",
  },
  {
    id: "USR-008",
    name: "Henry Park",
    role: "Engineering Manager",
    status: "Active",
    joined: "2020-06-30",
  },
];

type UserColumn = ColumnDef<DataGridFeatures, User>;

const header =
  (title: string): UserColumn["header"] =>
  ({ column }) => <DataGridColumnHeader column={column} title={title} visibility />;

const COLUMNS: UserColumn[] = [
  { accessorKey: "id", header: header("ID"), size: 110, meta: { headerTitle: "ID" } },
  {
    accessorKey: "name",
    header: header("Name"),
    size: 180,
    meta: { headerTitle: "Name", autoSize: true },
  },
  { accessorKey: "role", header: header("Role"), size: 190, meta: { headerTitle: "Role" } },
  {
    accessorKey: "status",
    header: header("Status"),
    size: 120,
    filterFn: "arrHas",
    cell: ({ row }) => (
      <Badge variant={row.original.status === "Active" ? "success-light" : "secondary"}>
        {row.original.status}
      </Badge>
    ),
    meta: { headerTitle: "Status", skeleton: <Skeleton className="h-5 w-16 rounded-full" /> },
  },
  { accessorKey: "joined", header: header("Joined"), size: 130, meta: { headerTitle: "Joined" } },
];

const SELECT_COLUMN: UserColumn = {
  id: "select",
  size: 48,
  enableSorting: false,
  enableResizing: false,
  enableHiding: false,
  header: () => <DataGridRowSelect />,
  cell: () => <DataGridRowSelect />,
  meta: { headerTitle: "Select" },
};

type UsersDataGridProps = {
  data?: User[];
  columns?: UserColumn[];
  isLoading?: boolean;
  loadingMode?: "skeleton" | "spinner";
  emptyMessage?: React.ReactNode;
  onRowClick?: (user: User) => void;
  layout?: DataGridLayout;
  selectable?: boolean;
  pageSize?: number;
  toolbar?: (table: Table<DataGridFeatures, User>) => React.ReactNode;
  /** Adds an expand column and a details row under expanded rows. */
  expandable?: boolean;
  initialPinning?: ColumnPinningState;
  i18n?: DataGridI18nOverrides;
  tableClassNames?: DataGridTableClassNames;
  /** Footer rows for `footerContent`. */
  footer?: (table: Table<DataGridFeatures, User>) => React.ReactNode;
};

const EXPAND_COLUMN: UserColumn = {
  id: "expand",
  size: 48,
  enableSorting: false,
  enableResizing: false,
  enableHiding: false,
  header: () => <span className="sr-only">Details</span>,
  cell: ({ row }) => <DataGridRowExpand row={row} />,
  meta: { headerTitle: "Details" },
};

function UsersDataGrid({
  data = USERS,
  columns = COLUMNS,
  isLoading,
  loadingMode,
  emptyMessage,
  onRowClick,
  layout,
  selectable,
  pageSize = 5,
  toolbar,
  expandable,
  initialPinning = { start: [], end: [] },
  i18n,
  footer,
  tableClassNames,
}: UsersDataGridProps) {
  const [pagination, setPagination] = React.useState<PaginationState>({ pageIndex: 0, pageSize });
  const [sorting, setSorting] = React.useState<SortingState>([]);
  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({});
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>([]);
  const [columnVisibility, setColumnVisibility] = React.useState<ColumnVisibilityState>({});
  const [columnOrder, setColumnOrder] = React.useState<ColumnOrderState>([]);
  const [columnPinning, setColumnPinning] = React.useState<ColumnPinningState>(initialPinning);
  const [rowPinning, setRowPinning] = React.useState<RowPinningState>({ top: [], bottom: [] });

  const table = useTable({
    features: dataGridFeatures,
    data,
    columns: [
      ...(expandable ? [EXPAND_COLUMN] : []),
      ...(selectable ? [SELECT_COLUMN] : []),
      ...columns,
    ],
    getRowCanExpand: () => !!expandable,
    getRowId: (row: User) => row.id,
    state: {
      pagination,
      sorting,
      rowSelection,
      columnFilters,
      columnVisibility,
      columnOrder,
      columnPinning,
      rowPinning,
    },
    onPaginationChange: setPagination,
    onSortingChange: setSorting,
    onRowSelectionChange: setRowSelection,
    onColumnFiltersChange: setColumnFilters,
    onColumnVisibilityChange: setColumnVisibility,
    onColumnOrderChange: setColumnOrder,
    onColumnPinningChange: setColumnPinning,
    onRowPinningChange: setRowPinning,
    enableRowSelection: selectable,
    keepPinnedRows: true,
  });

  return (
    <DataGrid
      table={table}
      recordCount={table.getFilteredRowModel().rows.length}
      isLoading={isLoading}
      loadingMode={loadingMode}
      emptyMessage={emptyMessage}
      onRowClick={onRowClick}
      tableLayout={layout}
      i18n={i18n}
      tableClassNames={tableClassNames}
      className="w-[760px]"
    >
      {toolbar?.(table)}
      <DataGridContainer>
        <DataGridTable<User>
          aria-label="Users"
          footerContent={footer?.(table)}
          renderExpandedRow={
            expandable
              ? (row) => (
                  <p className="text-muted-foreground">
                    {row.original.name} has been a {row.original.role} since {row.original.joined}.
                  </p>
                )
              : undefined
          }
        />
      </DataGridContainer>
      <DataGridPagination />
    </DataGrid>
  );
}

export function DataGridDemo() {
  return <UsersDataGrid />;
}
```

### Date Field

A segmented, keyboard-editable date input.

- **Granularity**: `granularity` also accepts `"month"` and `"year"` for month- or year-only fields.
- **Availability**: values blocked by `minValue`/`maxValue` or `unavailableRanges` move to the nearest available date once the field loses focus, so typing is never interrupted.
- **`DateInput`**: exported for composing date pickers.

- Install: `pnpm dlx shadcn@latest add @fma-ds/date-field`
- Registry item: https://ds.fmartinsandre.dev.br/r/date-field.json
- Docs: https://ds.fmartinsandre.dev.br/components/date-field
- npm: @internationalized/date@^3.12.4, cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/use-available-date-correction, @fma-ds/date-granularity, @fma-ds/interval-helpers, @fma-ds/types

```tsx
import { DateField } from "@/components/fma-ds/date-field";

export function DateFieldDemo() {
  return <DateField aria-label="Event date" />;
}
```

### Date Picker

A typed date input paired with a calendar popover over one value, for single dates (`DatePicker`) or ranges (`DateRangePicker`).

- **Granularity**: month- and year-only, as well as days.
- **Availability**: `unavailableRanges` blocks dates.
- **Non-modal popover**: the input stays editable while the calendar is open, and the calendar follows what is typed.

- Install: `pnpm dlx shadcn@latest add @fma-ds/date-picker`
- Registry item: https://ds.fmartinsandre.dev.br/r/date-picker.json
- Docs: https://ds.fmartinsandre.dev.br/components/date-picker
- npm: @internationalized/date@^3.12.4, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/calendar, @fma-ds/date-field, @fma-ds/input-group, @fma-ds/popover, @fma-ds/date-granularity, @fma-ds/types

```tsx
import { DatePicker } from "@/components/fma-ds/date-picker";

export function DatePickerDemo() {
  return <DatePicker aria-label="Event date" />;
}
```

### Description List

Term/value pairs on a semantic `<dl>`: `DescriptionList` > `DescriptionItem` > `DescriptionTerm` + `DescriptionDetails`.

- **`layout="inline"`** (default): each value at the end of its row, right-aligned with tabular numbers — for order summaries, totals and plan details.
- **`layout="stacked"`**: the value under a smaller term, in a grid whose columns you set with `className` — for record details.
- **`divided`**: draws rules between rows.
- **Icons**: an icon inside `DescriptionTerm` sits before the label.

- Install: `pnpm dlx shadcn@latest add @fma-ds/description-list`
- Registry item: https://ds.fmartinsandre.dev.br/r/description-list.json
- Docs: https://ds.fmartinsandre.dev.br/components/description-list
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { Badge } from "@/components/fma-ds/badge";
import {
  DescriptionDetails,
  DescriptionItem,
  DescriptionList,
  DescriptionTerm,
} from "@/components/fma-ds/description-list";

export function DescriptionListDemo() {
  return (
    <DescriptionList className="w-72">
      <DescriptionItem>
        <DescriptionTerm>Valor mensal</DescriptionTerm>
        <DescriptionDetails>R$ 189,90</DescriptionDetails>
      </DescriptionItem>
      <DescriptionItem>
        <DescriptionTerm>Valor anual</DescriptionTerm>
        <DescriptionDetails>R$ 2.278,80</DescriptionDetails>
      </DescriptionItem>
      <DescriptionItem>
        <DescriptionTerm>Validade</DescriptionTerm>
        <DescriptionDetails>
          <Badge variant="secondary">12 meses</Badge>
        </DescriptionDetails>
      </DescriptionItem>
    </DescriptionList>
  );
}
```

### Dialog

A modal window layered over the page, requiring explicit action (or Escape) to dismiss. Pair with react-aria-components' DialogTrigger to wire up the trigger and open state.

- Install: `pnpm dlx shadcn@latest add @fma-ds/dialog`
- Registry item: https://ds.fmartinsandre.dev.br/r/dialog.json
- Docs: https://ds.fmartinsandre.dev.br/components/dialog
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button

```tsx
import { Button } from "@/components/fma-ds/button";
import {
  Dialog,
  DialogClose,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/fma-ds/dialog";

export function DialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline">Open</Button>
      <Dialog>
        <DialogHeader>
          <DialogTitle>Are you absolutely sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone. This will permanently delete your account and remove your
            data from our servers.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <Button>Continue</Button>
        </DialogFooter>
      </Dialog>
    </DialogTrigger>
  );
}
```

### Direction

Sets LTR/RTL text-direction context for descendant react-aria-components — a compatibility shim so a Radix/Base UI-style `direction` prop keeps working via react-aria's locale system.

- Install: `pnpm dlx shadcn@latest add @fma-ds/direction`
- Registry item: https://ds.fmartinsandre.dev.br/r/direction.json
- Docs: https://ds.fmartinsandre.dev.br/components/direction
- npm: react-aria-components@^1.22.1

```tsx
import { DirectionProvider } from "@/components/fma-ds/direction";

export function DirectionLeftToRight() {
  return (
    <DirectionProvider direction="ltr">
      <p dir="ltr" className="max-w-sm text-sm">
        This text and any react-aria-components descendants (menus, sliders, etc.) read their text
        direction from this provider.
      </p>
    </DirectionProvider>
  );
}
```

### Drawer

A panel that slides in from an edge of the screen, with swipe-to-dismiss and snap-point support. Uses @base-ui/react (not react-aria-components), so its API and data attributes differ from this repo's other overlays.

- Install: `pnpm dlx shadcn@latest add @fma-ds/drawer`
- Registry item: https://ds.fmartinsandre.dev.br/r/drawer.json
- Docs: https://ds.fmartinsandre.dev.br/components/drawer
- npm: @base-ui/react@^1.9.0, cn@^0.5.0

```tsx
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/fma-ds/drawer";

export function DrawerDemo() {
  return (
    <Drawer>
      <DrawerTrigger>Open</DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Are you absolutely sure?</DrawerTitle>
          <DrawerDescription>This action cannot be undone.</DrawerDescription>
        </DrawerHeader>
        <DrawerFooter>
          <DrawerClose className="rounded bg-primary px-4 py-2 text-primary-foreground">
            Submit
          </DrawerClose>
          <DrawerClose className="hover:underline">Cancel</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}
```

### Dropdown Menu

A menu of actions or options triggered by clicking a button. Supports nested submenus, separators, labels, and a shortcut-display slot for each item.

- Install: `pnpm dlx shadcn@latest add @fma-ds/dropdown-menu`
- Registry item: https://ds.fmartinsandre.dev.br/r/dropdown-menu.json
- Docs: https://ds.fmartinsandre.dev.br/components/dropdown-menu
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import { Button } from "@/components/fma-ds/button";
import {
  DropdownMenu,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@/components/fma-ds/dropdown-menu";

export function DropdownMenuDemo() {
  return (
    <DropdownMenuTrigger>
      <Button variant="outline">Open menu</Button>
      <DropdownMenu className="w-56">
        <DropdownMenuLabel>My Account</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem id="profile">
          Profile
          <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem id="billing">
          Billing
          <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem id="settings">
          Settings
          <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenu>
    </DropdownMenuTrigger>
  );
}
```

### Emoji Picker

An emoji picker with search, skin tones, recently used emoji, custom emoji and a virtualized grid.

`<EmojiPicker />` alone renders a trigger and a popover. Compose `EmojiPickerTrigger` + `EmojiPickerContent`, or `EmojiPickerPanel` in place, from `EmojiPickerSearch`, `EmojiPickerCategories`, `EmojiPickerList`, `EmojiPickerPreview` and `EmojiPickerSkinTone`.

- **Search**: names, keywords and shortcodes.
- **Categories**: a category bar that follows the scroll, plus a frequently or recently used section.
- **Data**: emojibase, fetched once per page from jsDelivr (`dataUrl` to self-host, `locale` for 28 languages) or passed as `data`. `emojiVersion="auto"` hides emoji the device can't draw.
- **Value**: `value`/`defaultValue`/`onChange` hold the native emoji (or `:shortcode:` for a custom one). `selectionMode="multiple"` toggles a list (with `max`), and `onEmojiSelect` fires on every pick, for inserting into text.
- **Keyboard**: focus stays in the search while the arrows move through the grid (a combobox over an `aria-activedescendant` listbox); Enter picks.
- **Persistence**: recent picks and the tone persist in localStorage (`recentStorageKey`, `skinToneStorageKey`; `null` keeps them in memory).
- **Forms**: `name` submits with a native form.

Every string comes from `i18n`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/emoji-picker`
- Registry item: https://ds.fmartinsandre.dev.br/r/emoji-picker.json
- Docs: https://ds.fmartinsandre.dev.br/components/emoji-picker
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/dropdown-menu, @fma-ds/empty, @fma-ds/input-group, @fma-ds/popover, @fma-ds/skeleton, @fma-ds/tabs

```tsx
import { EmojiPicker } from "@/components/fma-ds/emoji-picker";

export function EmojiPickerDemo() {
  return <EmojiPicker />;
}
```

### Empty

A placeholder for empty states — no data, no search results, nothing configured yet. Composes an icon/media, title, description, and optional call-to-action content.

- Install: `pnpm dlx shadcn@latest add @fma-ds/empty`
- Registry item: https://ds.fmartinsandre.dev.br/r/empty.json
- Docs: https://ds.fmartinsandre.dev.br/components/empty
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { InboxIcon } from "lucide-react";
import { Button } from "@/components/fma-ds/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/components/fma-ds/empty";

export function EmptyDemo() {
  return (
    <Empty className="w-96">
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <InboxIcon />
        </EmptyMedia>
        <EmptyTitle>No projects yet</EmptyTitle>
        <EmptyDescription>Get started by creating your first project.</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button size="sm">Create project</Button>
      </EmptyContent>
    </Empty>
  );
}
```

### Field

Layout primitives for building form fields. Pairs with `Label`, `Input`, and friends.

- **`Field`**: the field wrapper.
- **`FieldSet`/`FieldLegend`**: for grouping.
- **`FieldLabel`/`FieldDescription`/`FieldError`**: the usual label + hint + error stack.
- **`FieldSeparator`**: splits a group.
- **`FieldHelp`**: an ⓘ button beside a label or column header that opens help in a popover (touch and keyboard, unlike a tooltip); its required `label` names the subject.
- **`choiceCardClassName`**: the choice-card surface shared by `CheckboxCard` and `RadioCard`; hover uses `accent`. With react-aria the control is the card, instead of shadcn's `FieldLabel` wrapping a `Field`, which would nest labels.

- Install: `pnpm dlx shadcn@latest add @fma-ds/field`
- Registry item: https://ds.fmartinsandre.dev.br/r/field.json
- Docs: https://ds.fmartinsandre.dev.br/components/field
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/label, @fma-ds/popover, @fma-ds/separator

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/fma-ds/field";
import { Input } from "@/components/fma-ds/input";

export function FieldDemo() {
  return (
    <Field className="w-80">
      <FieldLabel htmlFor="email">Email</FieldLabel>
      <Input id="email" type="email" placeholder="you@example.com" />
      <FieldDescription>We'll never share your email.</FieldDescription>
    </Field>
  );
}
```

### File Type

A file type icon: a page with a folded corner and the extension label, in the format's brand or family color (Word blue, Excel green, the GitHub language colors).

- **`type`**: one of 171 extensions (documents, certificates, code, config, archives…), one of 13 families (`image`, `folder`… drawn as a glyph) or any other string (a neutral labelled page).
- **`getFileType()`**: resolves a file name, path, URL or MIME type, including well-known names without an extension (Dockerfile, `.env.local`, `go.mod`, LICENSE) and aliases such as `.cer`. `getFileTypeCategory()` returns the family.
- **`variant`**: `outline`, `solid`, `light` or `mono` (theme gray). A `text-*` class recolors it.
- **`size`**: from `mini` (18px, for table rows) to `xl`; a Tailwind `size-*` class scales the label and stroke with the box (container units).
- **Content**: `label` replaces the text, `glyph` shows the family glyph and `icon` draws a custom icon.

Renders a `span` with `role="img"` named after the type. It has no state, so it works in Server Components.

- Install: `pnpm dlx shadcn@latest add @fma-ds/file-type`
- Registry item: https://ds.fmartinsandre.dev.br/r/file-type.json
- Docs: https://ds.fmartinsandre.dev.br/components/file-type
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { FileType } from "@/components/fma-ds/file-type";

export function FileTypeDemo() {
  return <FileType type="pdf" />;
}
```

### File Upload

Picks files by dragging them in, pasting them or browsing, and lists them; it doesn't upload.

`FileUpload` holds the `use-file-upload` state — `accept` (`.pdf,.docx`, `image/*`), `maxSize`, `multiple` + `maxFiles`, uncontrolled (`defaultValue`) or controlled (`value`/`onChange`), `isDisabled` — and the parts read it:

- **`FileUploadDropzone`**: a react-aria `DropZone`, with keyboard and paste support. By default an icon, title, `description` and a trigger, highlighted with `accent` while a drag is over it.
- **`FileUploadTrigger`**: a `FileTrigger` button.
- **`FileUploadList`**: renders each file with a function.
- **`FileUploadItem`**: a file-type icon or image thumbnail, name, size, optional `progress`, `error`, extra `actions` such as retry, and a remove button that keeps focus in the widget.
- **`FileUploadError`**: a `FieldError` with the validation errors (type, size, count).

Upload progress and retries stay with the app, keyed by file id.

Built-in text is in English; translate labels and error messages with `i18n`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/file-upload`
- Registry item: https://ds.fmartinsandre.dev.br/r/file-upload.json
- Docs: https://ds.fmartinsandre.dev.br/components/file-upload
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/field, @fma-ds/file-type, @fma-ds/icon-tile, @fma-ds/progress, @fma-ds/use-file-upload

```tsx
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadError,
  type FileUploadI18n,
  FileUploadItem,
  FileUploadList,
} from "@/components/fma-ds/file-upload";

const PT_BR: FileUploadI18n = {
  labels: {
    dropzone: "Arraste o arquivo para cá",
    dropzoneMultiple: "Arraste os arquivos para cá",
    browse: "Selecionar arquivo",
    browseMultiple: "Selecionar arquivos",
    remove: (name) => `Remover ${name}`,
    progress: (name) => `Enviando ${name}`,
  },
  messages: {
    fileInvalidType: (file) => `"${file.name}" não é um formato aceito.`,
    fileTooLarge: (file) => `"${file.name}" passa do tamanho máximo.`,
    tooManyFiles: (maxFiles) => `Envie no máximo ${maxFiles} arquivos.`,
  },
};

export function FileUploadDemo() {
  return (
    <FileUpload i18n={PT_BR} accept=".pdf,.docx" maxSize={5 * 1024 * 1024} className="w-96">
      <FileUploadDropzone description="PDF ou DOCX, até 5 MB" />
      <FileUploadError />
      <FileUploadList>{(file) => <FileUploadItem file={file} />}</FileUploadList>
    </FileUpload>
  );
}
```

### Glance

A quick piece of information that opens more context one click away — an account notice, a balance, a count of pending items.

`Glance` wraps react-aria's `DialogTrigger` and shares a `tone` (`default`, `info`, `success`, `warning`, `destructive`) with its parts.

- **`GlanceTrigger`**: the compact button — an icon plus `GlanceText` (a `GlanceLabel` caption over a `GlanceValue`), or icon-only with `size="icon"` and an `aria-label`.
- **`GlanceIndicator`**: pins a dot or count to the trigger's corner.
- **`GlanceContent`**: a popover holding a dialog (focus moves in, Escape closes, focus returns), laid out with `GlanceHeader`, `GlanceMedia` (an `IconTile` in the tone), `GlanceTitle`, `GlanceDescription` and `GlanceFooter`. Its children can be a function of `{ close }`, to close it from an action.

Tone tints the trigger like `Alert`, with no motion — urgency comes from tone and wording.

- Install: `pnpm dlx shadcn@latest add @fma-ds/glance`
- Registry item: https://ds.fmartinsandre.dev.br/r/glance.json
- Docs: https://ds.fmartinsandre.dev.br/components/glance
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/icon-tile, @fma-ds/popover

```tsx
import { CircleDollarSignIcon } from "lucide-react";
import { LinkButton } from "@/components/fma-ds/button";
import {
  Glance,
  GlanceContent,
  GlanceDescription,
  GlanceFooter,
  GlanceHeader,
  GlanceLabel,
  GlanceMedia,
  GlanceText,
  GlanceTitle,
  GlanceTrigger,
  GlanceValue,
} from "@/components/fma-ds/glance";

export function GlanceDemo() {
  return (
    <Glance>
      <GlanceTrigger>
        <CircleDollarSignIcon />
        <GlanceText>
          <GlanceLabel>Saldo de cashback</GlanceLabel>
          <GlanceValue>R$ 1.250,00</GlanceValue>
        </GlanceText>
      </GlanceTrigger>
      <GlanceContent>
        <GlanceHeader>
          <GlanceMedia>
            <CircleDollarSignIcon />
          </GlanceMedia>
          <div>
            <GlanceTitle>R$ 1.250,00 disponíveis</GlanceTitle>
            <GlanceDescription>Acumulados nos últimos 30 dias.</GlanceDescription>
          </div>
        </GlanceHeader>
        <GlanceDescription>R$ 80,00 expiram nos próximos 5 dias.</GlanceDescription>
        <GlanceFooter>
          <LinkButton href="#cashback" variant="outline">
            Ver detalhes
          </LinkButton>
        </GlanceFooter>
      </GlanceContent>
    </Glance>
  );
}
```

### Hover Card

A popover that shows on hover or focus instead of click, for previewing content (a profile card, a link preview) without navigating away. Unlike a tooltip, it can contain interactive content.

- Install: `pnpm dlx shadcn@latest add @fma-ds/hover-card`
- Registry item: https://ds.fmartinsandre.dev.br/r/hover-card.json
- Docs: https://ds.fmartinsandre.dev.br/components/hover-card
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Button } from "@/components/fma-ds/button";
import { HoverCard, HoverCardTrigger } from "@/components/fma-ds/hover-card";

export function HoverCardDemo() {
  return (
    <HoverCardTrigger>
      <Button variant="link">@ada</Button>
      <HoverCard placement="bottom">
        <div className="flex flex-col gap-1">
          <p className="font-medium">@ada</p>
          <p className="text-muted-foreground">Mathematician, and the first programmer.</p>
        </div>
      </HoverCard>
    </HoverCardTrigger>
  );
}
```

### Icon Stack

A layered icon illustration for empty states: three receding cards drawn from `currentColor`, with an optional glyph (`children`) laid flat on the front card.

Pairs with `EmptyMedia`. Decorative: the SVG is hidden from assistive tech, so give the glyph `aria-hidden` too.

- Install: `pnpm dlx shadcn@latest add @fma-ds/icon-stack`
- Registry item: https://ds.fmartinsandre.dev.br/r/icon-stack.json
- Docs: https://ds.fmartinsandre.dev.br/components/icon-stack
- npm: cn@^0.5.0

```tsx
import { CalendarIcon } from "lucide-react";
import { IconStack } from "@/components/fma-ds/icon-stack";

export function IconStackDemo() {
  return (
    <IconStack>
      <CalendarIcon className="size-5" aria-hidden="true" />
    </IconStack>
  );
}
```

### Icon Tile

A square surface that gives icons a consistent footprint.

- **`variant`**: `outline` (bordered), `elevated` (raised chip), `soft` (tinted double container), `solid` (filled) or `frame` (double container matching `Card`). `soft` and `solid` follow `currentColor`, so a text color class retints them.
- **`size`**: from `xs` to `xl`.
- **`radius`**: `default` (clamped to the tile) or `full` (circular).

Renders a `<span>`; wrap it in a `Button` or `Link` to make it interactive.

- Install: `pnpm dlx shadcn@latest add @fma-ds/icon-tile`
- Registry item: https://ds.fmartinsandre.dev.br/r/icon-tile.json
- Docs: https://ds.fmartinsandre.dev.br/components/icon-tile
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { SparklesIcon } from "lucide-react";
import { IconTile } from "@/components/fma-ds/icon-tile";

export function IconTileDemo() {
  return (
    <IconTile variant="outline">
      <SparklesIcon />
    </IconTile>
  );
}
```

### Input

A single-line text input, styled to match the rest of the registry. Plain native attributes (disabled, not isDisabled) since it wraps react-aria-components' bare Input rather than a higher-level field primitive.

- Install: `pnpm dlx shadcn@latest add @fma-ds/input`
- Registry item: https://ds.fmartinsandre.dev.br/r/input.json
- Docs: https://ds.fmartinsandre.dev.br/components/input
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Input } from "@/components/fma-ds/input";

export function InputDemo() {
  return <Input placeholder="you@example.com" />;
}
```

### Input Group

Wraps an Input or Textarea with leading/trailing addons (icons, text, or buttons) inside one bordered container, so the whole group shares a single focus ring and border.

- Install: `pnpm dlx shadcn@latest add @fma-ds/input-group`
- Registry item: https://ds.fmartinsandre.dev.br/r/input-group.json
- Docs: https://ds.fmartinsandre.dev.br/components/input-group
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/input, @fma-ds/textarea

```tsx
import { SearchIcon } from "lucide-react";
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/fma-ds/input-group";

export function InputGroupDemo() {
  return (
    <InputGroup className="w-72">
      <InputGroupAddon>
        <SearchIcon />
      </InputGroupAddon>
      <InputGroupInput placeholder="Search components..." />
    </InputGroup>
  );
}
```

### Input Otp

A one-time-password / verification-code input rendered as individual boxed slots, backed by a single hidden text input for real typing, paste, and autofill behavior.

- Install: `pnpm dlx shadcn@latest add @fma-ds/input-otp`
- Registry item: https://ds.fmartinsandre.dev.br/r/input-otp.json
- Docs: https://ds.fmartinsandre.dev.br/components/input-otp
- npm: cn@^0.5.0, input-otp@^1.5.0, lucide-react@^1.61.0

```tsx
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@/components/fma-ds/input-otp";

export function InputOtpDemo() {
  return (
    <InputOTP maxLength={6}>
      <InputOTPGroup>
        <InputOTPSlot index={0} />
        <InputOTPSlot index={1} />
        <InputOTPSlot index={2} />
      </InputOTPGroup>
      <InputOTPSeparator />
      <InputOTPGroup>
        <InputOTPSlot index={3} />
        <InputOTPSlot index={4} />
        <InputOTPSlot index={5} />
      </InputOTPGroup>
    </InputOTP>
  );
}
```

### Item

A generic row layout for lists of things — media/icon, title, description, and trailing actions.

- **Rendering**: a `<div>` or, when given an `href`, a real link (hovered with the theme's `accent`).
- **`ItemGroup`**: stacks several with consistent spacing.

- Install: `pnpm dlx shadcn@latest add @fma-ds/item`
- Registry item: https://ds.fmartinsandre.dev.br/r/item.json
- Docs: https://ds.fmartinsandre.dev.br/components/item
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/separator

```tsx
import { UserIcon } from "lucide-react";
import { Button } from "@/components/fma-ds/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@/components/fma-ds/item";

export function ItemDemo() {
  return (
    <Item variant="outline" className="w-96">
      <ItemMedia variant="icon">
        <UserIcon />
      </ItemMedia>
      <ItemContent>
        <ItemTitle>Ada Lovelace</ItemTitle>
        <ItemDescription>ada@example.com</ItemDescription>
      </ItemContent>
      <ItemActions>
        <Button size="sm" variant="outline">
          Edit
        </Button>
      </ItemActions>
    </Item>
  );
}
```

### Kbd

Displays a keyboard key or shortcut (e.g. ⌘K) inline, styled as a small pill. KbdGroup lays out several keys side by side for combos like ⌘+Shift+P.

- Install: `pnpm dlx shadcn@latest add @fma-ds/kbd`
- Registry item: https://ds.fmartinsandre.dev.br/r/kbd.json
- Docs: https://ds.fmartinsandre.dev.br/components/kbd
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Kbd } from "@/components/fma-ds/kbd";

export function KbdDemo() {
  return <Kbd>⌘</Kbd>;
}
```

### Label

A form field label.

Pair it with a control via `id`/`htmlFor` rather than passing label text as the control's own children: several toggle-style primitives (`Checkbox`, `Switch`, `RadioGroupItem`) render their children inside a small fixed-size box meant for a custom indicator, not prose.

- Install: `pnpm dlx shadcn@latest add @fma-ds/label`
- Registry item: https://ds.fmartinsandre.dev.br/r/label.json
- Docs: https://ds.fmartinsandre.dev.br/components/label
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Label } from "@/components/fma-ds/label";

export function LabelDemo() {
  return <Label htmlFor="email">Email</Label>;
}
```

### Loading Overlay

Blocks interaction while an operation runs. No brand animation: just a spinner.

- **`LoadingOverlay`**: wraps a region. While `isLoading`, its children stay visible under a veil with a spinner and `label` (default "Loading…", announced via `role="status"`), become `inert`, and the region is `aria-busy`.
- **`LoadingScreen`**: the same for the whole app, as a non-dismissable modal (focus held, page hidden from assistive tech, scroll locked) — for operations that must finish before anything else, like saving a status change.

Pass a translated `label` as needed.

- Install: `pnpm dlx shadcn@latest add @fma-ds/loading-overlay`
- Registry item: https://ds.fmartinsandre.dev.br/r/loading-overlay.json
- Docs: https://ds.fmartinsandre.dev.br/components/loading-overlay
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import { Button } from "@/components/fma-ds/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/fma-ds/card";
import { LoadingOverlay } from "@/components/fma-ds/loading-overlay";

export function LoadingOverlayDemo() {
  return (
    <LoadingOverlay isLoading label="Salvando alterações…" className="w-80 rounded-xl">
      <Card>
        <CardHeader>
          <CardTitle>Módulos do cliente</CardTitle>
          <CardDescription>Gestor de pedidos e análise de vendas.</CardDescription>
        </CardHeader>
        <CardContent>
          <Button>Salvar alterações</Button>
        </CardContent>
      </Card>
    </LoadingOverlay>
  );
}
```

### Marker

A small inline label used in chat/message timelines — a date separator, a status note, or similar metadata — rendered in muted text with an optional icon.

- Install: `pnpm dlx shadcn@latest add @fma-ds/marker`
- Registry item: https://ds.fmartinsandre.dev.br/r/marker.json
- Docs: https://ds.fmartinsandre.dev.br/components/marker
- npm: class-variance-authority@^0.7.1, cn@^0.5.0

```tsx
import { CheckIcon } from "lucide-react";
import { Marker, MarkerContent, MarkerIcon } from "@/components/fma-ds/marker";

export function MarkerDemo() {
  return (
    <Marker>
      <MarkerIcon>
        <CheckIcon />
      </MarkerIcon>
      <MarkerContent>Deployed 2 minutes ago</MarkerContent>
    </Marker>
  );
}
```

### Masked Input

An `Input` with live Maskito formatting. Works inside a react-aria `TextField`.

- **`mask`**: a preset name (`"cpf"`, `"cnpj"`, `"cpf-cnpj"`, `"cep"`, `"phone"`, `"credit-card"`, `"date"`, `"time"`, `"date-time"`, `"date-range"`, `"decimal"`), a parameterized preset such as `{ type: "decimal", prefix: "R$ " }` or `{ type: "date", mode: "mm/yy" }` for a card expiry (safe to write inline), or custom Maskito options.
- **Presets**: set `inputMode`, `autoComplete` and a placeholder.
- **Value**: `onValueChange` receives the raw value (digits, ISO date, dot-decimal) and the masked text. `value` may be either, so a form can store only the raw value.

For other inputs, such as `InputGroupInput`, spread `useMask(...).inputProps` instead.

- Install: `pnpm dlx shadcn@latest add @fma-ds/masked-input`
- Registry item: https://ds.fmartinsandre.dev.br/r/masked-input.json
- Docs: https://ds.fmartinsandre.dev.br/components/masked-input
- Registry: @fma-ds/input, @fma-ds/use-mask

```tsx
import { MaskedInput } from "@/components/fma-ds/masked-input";

export function MaskedInputDemo() {
  return <MaskedInput mask="cpf" aria-label="CPF" className="w-64" />;
}
```

### Menubar

An app-style menu bar (File, Edit, View…).

- **Structure**: `Menubar` is a react-aria `Toolbar`, so arrow keys move between menus. Each `MenubarMenu` pairs a `MenubarTrigger` with a `MenubarContent` built on `DropdownMenu`, including submenus (`MenubarSub`).
- **Checkable items**: come from react-aria selection — give a `MenubarGroup` a `selectionMode` (`"multiple"` or `"single"`) and `selectedKeys`/`onSelectionChange`, and its items show a check when selected.
- **Opening**: menus open on press or Enter/Space/ArrowDown. While one is open, hovering another trigger or pressing ArrowLeft/ArrowRight opens the neighbouring menu.

- Install: `pnpm dlx shadcn@latest add @fma-ds/menubar`
- Registry item: https://ds.fmartinsandre.dev.br/r/menubar.json
- Docs: https://ds.fmartinsandre.dev.br/components/menubar
- npm: cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/dropdown-menu

```tsx
import * as React from "react";
import type { Selection } from "react-aria-components";
import {
  Menubar,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarLabel,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@/components/fma-ds/menubar";

function ViewMenu() {
  const [panels, setPanels] = React.useState<Selection>(new Set(["sidebar"]));
  const [zoom, setZoom] = React.useState<Selection>(new Set(["100"]));
  return (
    <MenubarMenu>
      <MenubarTrigger>View</MenubarTrigger>
      <MenubarContent>
        <MenubarGroup
          aria-label="Panels"
          selectionMode="multiple"
          selectedKeys={panels}
          onSelectionChange={setPanels}
        >
          <MenubarItem id="sidebar">Sidebar</MenubarItem>
          <MenubarItem id="minimap">Minimap</MenubarItem>
        </MenubarGroup>
        <MenubarSeparator />
        <MenubarGroup selectionMode="single" selectedKeys={zoom} onSelectionChange={setZoom}>
          <MenubarLabel>Zoom</MenubarLabel>
          <MenubarItem id="75">75%</MenubarItem>
          <MenubarItem id="100">100%</MenubarItem>
          <MenubarItem id="150">150%</MenubarItem>
        </MenubarGroup>
      </MenubarContent>
    </MenubarMenu>
  );
}

export function MenubarDemo() {
  return (
    <Menubar aria-label="Editor">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem id="new-tab">
            New Tab <MenubarShortcut>⌘T</MenubarShortcut>
          </MenubarItem>
          <MenubarItem id="new-window">New Window</MenubarItem>
          <MenubarSeparator />
          <MenubarSub>
            <MenubarSubTrigger>Share</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem id="email">Email link</MenubarItem>
              <MenubarItem id="messages">Messages</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem id="print" isDisabled>
            Print
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem id="undo">
            Undo <MenubarShortcut>⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem id="redo">
            Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <ViewMenu />
    </Menubar>
  );
}
```

### Message

Layout for one message row in a chat UI — avatar, header, footer, and a content column that aligns to the start or end depending on who sent it. Pairs with Bubble for the actual message content.

- Install: `pnpm dlx shadcn@latest add @fma-ds/message`
- Registry item: https://ds.fmartinsandre.dev.br/r/message.json
- Docs: https://ds.fmartinsandre.dev.br/components/message
- npm: cn@^0.5.0

```tsx
import { Bubble, BubbleContent } from "@/components/fma-ds/bubble";
import {
  Message,
  MessageAvatar,
  MessageContent,
  MessageFooter,
  MessageHeader,
} from "@/components/fma-ds/message";

export function MessageDemo() {
  return (
    <Message align="start" className="w-96">
      <MessageAvatar className="size-8 bg-primary text-primary-foreground">AI</MessageAvatar>
      <MessageContent>
        <MessageHeader>Assistant</MessageHeader>
        <Bubble>
          <BubbleContent>Every registry item now has its dependencies verified.</BubbleContent>
        </Bubble>
        <MessageFooter>2:14 PM</MessageFooter>
      </MessageContent>
    </Message>
  );
}
```

### Message Scroller

An auto-scrolling viewport for chat message lists: sticks to the latest message as new ones arrive, and shows a jump-to-end/start button once the user scrolls away.

**Experimental**: it doesn't sit on react-aria-components like the rest of this registry, and `@shadcn/react` is still pre-1.0.

- Install: `pnpm dlx shadcn@latest add @fma-ds/message-scroller`
- Registry item: https://ds.fmartinsandre.dev.br/r/message-scroller.json
- Docs: https://ds.fmartinsandre.dev.br/components/message-scroller
- npm: @shadcn/react@^0.3.1, cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button

```tsx
import { Message, MessageContent } from "@/components/fma-ds/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@/components/fma-ds/message-scroller";

export function MessageScrollerDemo() {
  return (
    <MessageScrollerProvider>
      <MessageScroller className="h-72 w-96 rounded-lg border">
        <MessageScrollerViewport>
          <MessageScrollerContent>
            {Array.from({ length: 8 }, (_, i) => (
              // biome-ignore lint/suspicious/noArrayIndexKey: fixed-length demo messages, i IS the identity
              <MessageScrollerItem key={`message-${i}`}>
                <Message>
                  <MessageContent>Message {i + 1}</MessageContent>
                </Message>
              </MessageScrollerItem>
            ))}
          </MessageScrollerContent>
        </MessageScrollerViewport>
        <MessageScrollerButton />
      </MessageScroller>
    </MessageScrollerProvider>
  );
}
```

### Native Select

A styled wrapper around the real, native <select> — use it when you need actual native select behavior (mobile OS pickers, form autofill, no JS dependency) instead of react-aria-components' custom Select.

- Install: `pnpm dlx shadcn@latest add @fma-ds/native-select`
- Registry item: https://ds.fmartinsandre.dev.br/r/native-select.json
- Docs: https://ds.fmartinsandre.dev.br/components/native-select
- npm: cn@^0.5.0, lucide-react@^1.61.0

```tsx
import { NativeSelect, NativeSelectOption } from "@/components/fma-ds/native-select";

export function NativeSelectDemo() {
  return (
    <NativeSelect>
      <NativeSelectOption value="next">Next.js</NativeSelectOption>
      <NativeSelectOption value="tanstack">TanStack Start</NativeSelectOption>
      <NativeSelectOption value="remix">Remix</NativeSelectOption>
    </NativeSelect>
  );
}
```

### Navigation Menu

Site-header navigation: a `<nav>` list of top-level links and disclosure dropdowns. For app command menus use `Menubar` or `DropdownMenu`.

- **Items**: a `NavigationMenuItem` holds either a `NavigationMenuLink` or a `NavigationMenuTrigger` (a button with `aria-expanded`) plus its `NavigationMenuContent` (a popover).
- **Closing**: Escape or a click outside closes the dropdown and returns focus to the trigger; following a link closes it too.
- **Links**: style plain links like triggers with `navigationMenuTriggerStyle()`, and mark the current page with `aria-current="page"`.
- **Hover**: dropdowns open on press; with `openOnHover` they also open when the pointer rests on a trigger (`delay`, `closeDelay`). That's a non-modal "peek" that leaves focus alone, switches at once to another trigger and closes when the pointer leaves or on Escape. Pressing a peeked trigger keeps it open as a regular dropdown.
- **`NavigationMenuIndicator`**: add it after the list for an arrow that slides under the open trigger.

- Install: `pnpm dlx shadcn@latest add @fma-ds/navigation-menu`
- Registry item: https://ds.fmartinsandre.dev.br/r/navigation-menu.json
- Docs: https://ds.fmartinsandre.dev.br/components/navigation-menu
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import { BookOpenIcon, CodeIcon, RocketIcon } from "lucide-react";
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuIndicator,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/fma-ds/navigation-menu";

const DOCS = [
  {
    href: "#getting-started",
    title: "Getting started",
    icon: RocketIcon,
    text: "Install and set up.",
  },
  { href: "#guides", title: "Guides", icon: BookOpenIcon, text: "Step-by-step walkthroughs." },
  { href: "#api", title: "API reference", icon: CodeIcon, text: "Every prop, documented." },
];

export function NavigationMenuDemo() {
  return (
    <NavigationMenu aria-label="Main">
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuLink
            href="#overview"
            aria-current="page"
            className={navigationMenuTriggerStyle()}
          >
            Overview
          </NavigationMenuLink>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Documentation</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-80 gap-1">
              {DOCS.map(({ href, title, icon: Icon, text }) => (
                <li key={href}>
                  <NavigationMenuLink href={href} className="items-start">
                    <Icon className="mt-0.5" aria-hidden="true" />
                    <span className="flex flex-col gap-0.5">
                      <span className="font-medium">{title}</span>
                      <span className="text-muted-foreground">{text}</span>
                    </span>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Company</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-48 gap-1">
              <li>
                <NavigationMenuLink href="#about">About</NavigationMenuLink>
              </li>
              <li>
                <NavigationMenuLink href="#careers">Careers</NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink
            href="https://react-spectrum.adobe.com/react-aria/"
            target="_blank"
            className={navigationMenuTriggerStyle()}
          >
            External
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
      <NavigationMenuIndicator />
    </NavigationMenu>
  );
}
```

### Pagination

Page-number navigation built from LinkButton — previous/next controls, numbered links, and an ellipsis for collapsed ranges.

- Install: `pnpm dlx shadcn@latest add @fma-ds/pagination`
- Registry item: https://ds.fmartinsandre.dev.br/r/pagination.json
- Docs: https://ds.fmartinsandre.dev.br/components/pagination
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/fma-ds/pagination";

export function PaginationDemo() {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="#" />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#" isActive>
            2
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="#" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}
```

### Password Input

A password field with a show/hide toggle, built on `InputGroup`. Pair it with `password-rules` when creating a password.

- **Toggle**: a button named by `toggleLabel` (default "Show password"; pass a translation as needed) whose `aria-pressed` reports whether the text is revealed.
- **Visibility**: uncontrolled (`defaultRevealed`) or controlled (`isRevealed`/`onRevealedChange`).
- **Input**: the rest of the props go to the input, so it works inside a react-aria `TextField` (label, description, validation) and takes `autoComplete="current-password"` or `"new-password"`.

Hides Edge's built-in reveal button.

- Install: `pnpm dlx shadcn@latest add @fma-ds/password-input`
- Registry item: https://ds.fmartinsandre.dev.br/r/password-input.json
- Docs: https://ds.fmartinsandre.dev.br/components/password-input
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/input-group

```tsx
import { PasswordInput } from "@/components/fma-ds/password-input";

export function PasswordInputDemo() {
  return (
    <PasswordInput
      aria-label="Senha"
      toggleLabel="Mostrar senha"
      placeholder="Digite sua senha"
      autoComplete="current-password"
      groupClassName="w-64"
    />
  );
}
```

### Password Rules

The rules a new password must follow, each marked pending, met or unmet as the user types — by icon and a screen-reader state label (`stateLabels`), not color alone.

- **`rules`**: takes `PasswordRule` objects (`id`, `label`, `test(value, confirmation)`).
- **`passwordRules`**: builds the usual ones — `minLength(n)`, `maxLength(n)`, `uppercase()`, `lowercase()`, `number()`, `special()`, `match()` against `confirmation` — each taking a `label` to translate it. Defaults to 8+ characters, upper, lower and a number.
- **Neutral start**: rules stay neutral until there's something to judge.
- **Validation**: the pure helpers `evaluatePasswordRules` and `isPasswordValid` share the same rules for form validation.

Give it an `id` and point the input's `aria-describedby` at it.

- Install: `pnpm dlx shadcn@latest add @fma-ds/password-rules`
- Registry item: https://ds.fmartinsandre.dev.br/r/password-rules.json
- Docs: https://ds.fmartinsandre.dev.br/components/password-rules
- npm: cn@^0.5.0, lucide-react@^1.61.0

```tsx
import { PasswordRules, passwordRules } from "@/components/fma-ds/password-rules";

/** The rules with pt-BR labels: every built-in rule takes a `label`. */
function ptBrRules() {
  return [
    passwordRules.minLength(8, "Ter pelo menos 8 caracteres"),
    passwordRules.uppercase("Conter uma letra maiúscula"),
    passwordRules.lowercase("Conter uma letra minúscula"),
    passwordRules.number("Conter um número"),
  ];
}

const PT_BR_STATES = { neutral: "pendente", met: "atendido", unmet: "não atendido" };

export function PasswordRulesDemo() {
  return <PasswordRules value="" rules={ptBrRules()} stateLabels={PT_BR_STATES} />;
}
```

### Popover

A non-modal floating panel anchored to a trigger — for supplementary controls or content (e.g. a settings form) that shouldn't block the rest of the page.

- Install: `pnpm dlx shadcn@latest add @fma-ds/popover`
- Registry item: https://ds.fmartinsandre.dev.br/r/popover.json
- Docs: https://ds.fmartinsandre.dev.br/components/popover
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Button } from "@/components/fma-ds/button";
import {
  Popover,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/fma-ds/popover";

export function PopoverDemo() {
  return (
    <PopoverTrigger>
      <Button variant="outline">Open popover</Button>
      <Popover>
        <PopoverHeader>
          <PopoverTitle>Dimensions</PopoverTitle>
          <PopoverDescription>Set the dimensions for the layer.</PopoverDescription>
        </PopoverHeader>
      </Popover>
    </PopoverTrigger>
  );
}
```

### Progress

A horizontal progress bar communicating the completion of a task, determinate or indeterminate, with optional label/value slots.

- Install: `pnpm dlx shadcn@latest add @fma-ds/progress`
- Registry item: https://ds.fmartinsandre.dev.br/r/progress.json
- Docs: https://ds.fmartinsandre.dev.br/components/progress
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Progress } from "@/components/fma-ds/progress";

export function ProgressDemo() {
  return <Progress value={40} className="w-64" />;
}
```

### Questionnaire

A multi-step form/survey block (progress, choices, text input, previous/skip/next/submit) for chat-kit style conversational flows.

**Experimental**: built on `@shadcn/react`, not react-aria-components — upstream hasn't ported it to the aria base yet, and `@shadcn/react` is still pre-1.0.

- Install: `pnpm dlx shadcn@latest add @fma-ds/questionnaire`
- Registry item: https://ds.fmartinsandre.dev.br/r/questionnaire.json
- Docs: https://ds.fmartinsandre.dev.br/components/questionnaire
- npm: @shadcn/react@^0.3.1, cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button

```tsx
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@/components/fma-ds/questionnaire";

const items = [
  { name: "role", required: true },
  { name: "feedback", required: false },
] as const;

export function QuestionnaireDemo() {
  return (
    <Questionnaire items={items} defaultItem="role" className="w-96">
      <QuestionnaireProgress />
      <QuestionnaireItem name="role">
        <QuestionnaireTitle>What&apos;s your role?</QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="developer">Developer</QuestionnaireChoice>
          <QuestionnaireChoice value="designer">Designer</QuestionnaireChoice>
          <QuestionnaireChoice value="manager">Manager</QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireActions>
          <QuestionnairePrevious />
          <QuestionnaireNext />
        </QuestionnaireActions>
      </QuestionnaireItem>
      <QuestionnaireItem name="feedback">
        <QuestionnaireTitle>Any feedback?</QuestionnaireTitle>
        <QuestionnaireInput placeholder="Optional" />
        <QuestionnaireActions>
          <QuestionnairePrevious />
          <QuestionnaireSubmit />
        </QuestionnaireActions>
      </QuestionnaireItem>
    </Questionnaire>
  );
}
```

### Radio Group

A set of mutually-exclusive radio options.

Pair each `RadioGroupItem` with an external `Label` via `id`/`htmlFor` — its own children slot is for a custom indicator, not label text.

- **`RadioCard`**: a choice card — the whole card is the radio, its children are the content (an `IconTile`, `FieldContent` with `FieldTitle` and `FieldDescription`) and a round indicator sits at the end. Selected cards take a `primary` tint, hovered ones `accent`.
- **Layout**: lay several out with a `className` grid on the group.

- Install: `pnpm dlx shadcn@latest add @fma-ds/radio-group`
- Registry item: https://ds.fmartinsandre.dev.br/r/radio-group.json
- Docs: https://ds.fmartinsandre.dev.br/components/radio-group
- npm: cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/field

```tsx
import { Label } from "@/components/fma-ds/label";
import { RadioGroup, RadioGroupItem } from "@/components/fma-ds/radio-group";

export function RadioGroupDemo() {
  return (
    <RadioGroup>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="default" id="r-default" />
        <Label htmlFor="r-default">Default</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="comfortable" id="r-comfortable" />
        <Label htmlFor="r-comfortable">Comfortable</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="compact" id="r-compact" />
        <Label htmlFor="r-compact">Compact</Label>
      </div>
    </RadioGroup>
  );
}
```

### Resizable

Resizable split panes (panel group, panel, drag handle) built on react-resizable-panels — for layouts like a sidebar/editor split the user can drag to resize.

- Install: `pnpm dlx shadcn@latest add @fma-ds/resizable`
- Registry item: https://ds.fmartinsandre.dev.br/r/resizable.json
- Docs: https://ds.fmartinsandre.dev.br/components/resizable
- npm: cn@^0.5.0, react-resizable-panels@^4.14.8

```tsx
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@/components/fma-ds/resizable";

export function ResizableHorizontal() {
  return (
    <ResizablePanelGroup orientation="horizontal" className="h-48 w-96 rounded-lg border">
      <ResizablePanel defaultSize={50}>
        <div className="flex h-full items-center justify-center p-6">One</div>
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize={50}>
        <div className="flex h-full items-center justify-center p-6">Two</div>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}
```

### Scroll Area

A scrollable container with a themeable, always-consistent-looking scrollbar via native scrollbar-width/scrollbar-color — no JS scrollbar emulation.

- Install: `pnpm dlx shadcn@latest add @fma-ds/scroll-area`
- Registry item: https://ds.fmartinsandre.dev.br/r/scroll-area.json
- Docs: https://ds.fmartinsandre.dev.br/components/scroll-area
- npm: cn@^0.5.0

```tsx
import { ScrollArea } from "@/components/fma-ds/scroll-area";

const items = Array.from({ length: 20 }, (_, i) => `Item ${i + 1}`);

export function ScrollAreaDemo() {
  return (
    <ScrollArea className="h-48 w-64 rounded-lg border p-4">
      <div className="flex flex-col gap-2">
        {items.map((item) => (
          <p key={item}>{item}</p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### Select

A listbox-style picker (react-aria-components' Select) with a trigger, popover, groups, and an optional search input — richer than the native <select> (see native-select for that).

- Install: `pnpm dlx shadcn@latest add @fma-ds/select`
- Registry item: https://ds.fmartinsandre.dev.br/r/select.json
- Docs: https://ds.fmartinsandre.dev.br/components/select
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/input-group

```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@/components/fma-ds/select";

export function SelectDemo() {
  return (
    <Select placeholder="Select a fruit" aria-label="Fruit">
      <SelectTrigger>
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          <SelectLabel>Fruits</SelectLabel>
          <SelectItem id="apple">Apple</SelectItem>
          <SelectItem id="banana">Banana</SelectItem>
          <SelectItem id="blueberry">Blueberry</SelectItem>
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}
```

### Separator

A thin visual divider between content, horizontal or vertical.

- Install: `pnpm dlx shadcn@latest add @fma-ds/separator`
- Registry item: https://ds.fmartinsandre.dev.br/r/separator.json
- Docs: https://ds.fmartinsandre.dev.br/components/separator
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Separator } from "@/components/fma-ds/separator";

export function SeparatorHorizontal() {
  return (
    <div className="w-64">
      <p className="text-sm">Above</p>
      <Separator className="my-4" />
      <p className="text-sm">Below</p>
    </div>
  );
}
```

### Sheet

A modal panel that slides in from an edge of the screen (top/right/bottom/left) — for navigation drawers, filters, or forms that need more room than a popover.

- **`size`**: `sm` (384px, default), `md` (448px) or `lg` (672px) caps a left/right sheet from the `sm` breakpoint up; a width in `className` replaces it.

- Install: `pnpm dlx shadcn@latest add @fma-ds/sheet`
- Registry item: https://ds.fmartinsandre.dev.br/r/sheet.json
- Docs: https://ds.fmartinsandre.dev.br/components/sheet
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button

```tsx
import { Button } from "@/components/fma-ds/button";
import {
  Sheet,
  SheetClose,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/fma-ds/sheet";

export function SheetDemo() {
  return (
    <SheetTrigger>
      <Button variant="outline">Open sheet</Button>
      <Sheet>
        <SheetHeader>
          <SheetTitle>Edit profile</SheetTitle>
          <SheetDescription>Make changes to your profile here.</SheetDescription>
        </SheetHeader>
        <SheetFooter>
          <SheetClose>Save</SheetClose>
        </SheetFooter>
      </Sheet>
    </SheetTrigger>
  );
}
```

### Sidebar

A collapsible application sidebar with a mobile drawer fallback, a Cmd/Ctrl+B keyboard shortcut, and composable header/content/footer/menu slots.

- Install: `pnpm dlx shadcn@latest add @fma-ds/sidebar`
- Registry item: https://ds.fmartinsandre.dev.br/r/sidebar.json
- Docs: https://ds.fmartinsandre.dev.br/components/sidebar
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/input, @fma-ds/separator, @fma-ds/sheet, @fma-ds/skeleton, @fma-ds/tooltip, @fma-ds/use-mobile

```tsx
import { HomeIcon, SettingsIcon } from "lucide-react";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/fma-ds/sidebar";

export function SidebarDemo() {
  return (
    <SidebarProvider className="h-96">
      <Sidebar>
        <SidebarHeader>fma-ds</SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Navigation</SidebarGroupLabel>
            <SidebarGroupContent>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton isActive>
                    <HomeIcon />
                    <span>Home</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
                <SidebarMenuItem>
                  <SidebarMenuButton>
                    <SettingsIcon />
                    <span>Settings</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>v0.1.0</SidebarFooter>
      </Sidebar>
      <SidebarInset className="p-4">
        <SidebarTrigger />
        <p className="mt-4 text-sm text-muted-foreground">Page content goes here.</p>
      </SidebarInset>
    </SidebarProvider>
  );
}
```

### Skeleton

A pulsing placeholder block for content that's still loading — size and shape it with className to match whatever it stands in for.

- Install: `pnpm dlx shadcn@latest add @fma-ds/skeleton`
- Registry item: https://ds.fmartinsandre.dev.br/r/skeleton.json
- Docs: https://ds.fmartinsandre.dev.br/components/skeleton
- npm: cn@^0.5.0

```tsx
import { Skeleton } from "@/components/fma-ds/skeleton";

export function SkeletonDemo() {
  return (
    <div className="flex items-center gap-4">
      <Skeleton className="size-12 rounded-full" />
      <div className="flex flex-col gap-2">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </div>
    </div>
  );
}
```

### Slider

A draggable single- or range-value slider, horizontal or vertical. Pass an array default/value to get one thumb per value.

- **`label`**: names it above the track.
- **`showValue`**: prints the value (or range) beside it, formatted by `formatValue` ("200 pedidos") or `formatOptions` (currency, percent — also what screen readers announce).
- **`marks`**: labelled stops under the track (`number` or `{ value, label }`). Clicking one moves the nearest thumb there and fires `onChangeEnd`, while the keyboard keeps using the thumb.
- **`limit`**: caps the value below `maxValue` (stock left, plan quota). The scale and marks still run to `maxValue`, the track above the limit is drawn as unavailable and its marks are disabled.
- **`description`**: under the track, says why, and is read with the value.

- Install: `pnpm dlx shadcn@latest add @fma-ds/slider`
- Registry item: https://ds.fmartinsandre.dev.br/r/slider.json
- Docs: https://ds.fmartinsandre.dev.br/components/slider
- npm: cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/label

```tsx
import { Slider } from "@/components/fma-ds/slider";

export function SliderDemo() {
  return (
    <div className="w-64">
      <Slider defaultValue={33} />
    </div>
  );
}
```

### Sonner

A themed wrapper around the sonner toast library. Renders the toast viewport (Toaster); call toast() from "sonner" anywhere to actually show one.

- Install: `pnpm dlx shadcn@latest add @fma-ds/sonner`
- Registry item: https://ds.fmartinsandre.dev.br/r/sonner.json
- Docs: https://ds.fmartinsandre.dev.br/components/sonner
- npm: lucide-react@^1.61.0, next-themes@^0.4.6, sonner@^2.0.8

```tsx
import { toast } from "sonner";
import { Button } from "@/components/fma-ds/button";
import { Toaster } from "@/components/fma-ds/sonner";

export function SonnerDemo() {
  return (
    <div className="flex min-h-64 items-center justify-center">
      <Button onPress={() => toast("Event has been created", { description: "Just now" })}>
        Show Toast
      </Button>
      <Toaster position="bottom-right" />
    </div>
  );
}
```

### Sortable

A reorderable list, row or grid (`layout`: `vertical`, `horizontal`, `grid`).

Give it the items as `value` (or `defaultValue`) with `onChange`, and one `SortableItem` per item whose `id` matches `getKey(item)` (defaults to `item.id`) — as static children or a render function.

- **Pointer**: items drag from anywhere; a line marks the drop position.
- **`SortableItemHandle`**: required on every item — the visible grip and its keyboard / screen-reader drag button. Enter starts, arrows pick the drop position, Enter drops; arrows reach it in a vertical list, Tab in a row or grid.
- **`isDisabled`**: pins an item in place.
- **`selectionMode`**: lets several selected items move together.
- **`renderDragPreview`**: replaces the browser's drag snapshot.
- **Events**: `onChange` also gets the moved keys and the drop target; `onDragStart`/`onDragEnd` follow react-aria.

- Install: `pnpm dlx shadcn@latest add @fma-ds/sortable`
- Registry item: https://ds.fmartinsandre.dev.br/r/sortable.json
- Docs: https://ds.fmartinsandre.dev.br/components/sortable
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1

```tsx
import * as React from "react";
import { Sortable, SortableItem, SortableItemHandle } from "@/components/fma-ds/sortable";

interface Task {
  id: string;
  title: string;
}

const TASKS: Task[] = [
  { id: "design", title: "Design review" },
  { id: "api", title: "API contract" },
  { id: "tests", title: "Write tests" },
  { id: "ship", title: "Ship it" },
];

function TaskList({ disabled }: { disabled?: string }) {
  const [tasks, setTasks] = React.useState(TASKS);
  return (
    <Sortable aria-label="Tasks" value={tasks} onChange={setTasks} className="w-72">
      {(task) => (
        <SortableItem
          id={task.id}
          textValue={task.title}
          isDisabled={task.id === disabled}
          className="border bg-card p-1 pe-3 text-sm"
        >
          <SortableItemHandle />
          {task.title}
        </SortableItem>
      )}
    </Sortable>
  );
}

export function SortableDemo() {
  return <TaskList />;
}
```

### Spinner

A spinning loading indicator icon (role="status"), sized via className — drop it inside a disabled button or empty state while something loads.

- Install: `pnpm dlx shadcn@latest add @fma-ds/spinner`
- Registry item: https://ds.fmartinsandre.dev.br/r/spinner.json
- Docs: https://ds.fmartinsandre.dev.br/components/spinner
- npm: cn@^0.5.0, lucide-react@^1.61.0

```tsx
import { Spinner } from "@/components/fma-ds/spinner";

export function SpinnerDemo() {
  return <Spinner />;
}
```

### Stepper

Multi-step navigation, horizontal or vertical, built on react-aria `Tabs`.

- **Keyboard**: arrow keys, Home and End move between steps; Enter or Space selects one (manual activation).
- **Value**: `value`/`defaultValue`/`onValueChange` hold the current step.
- **`StepperItem`**: a tab whose `data-state` is `completed` (before the current step, or `isCompleted`), `active` or `inactive`. `isDisabled` skips it and `isLoading` shows the loading indicator.
- **`indicators`**: swaps an indicator's content per state.
- **`StepperContent`**: panels with the current step's content.

- Install: `pnpm dlx shadcn@latest add @fma-ds/stepper`
- Registry item: https://ds.fmartinsandre.dev.br/r/stepper.json
- Docs: https://ds.fmartinsandre.dev.br/components/stepper
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import {
  Stepper,
  StepperDescription,
  StepperIndicator,
  StepperItem,
  StepperNav,
  StepperSeparator,
  StepperTitle,
  StepperTrigger,
} from "@/components/fma-ds/stepper";

const STEPS = [
  { step: 1, title: "Account", description: "Create your account" },
  { step: 2, title: "Profile", description: "Set up your profile" },
  { step: 3, title: "Review", description: "Confirm your details" },
];

const nav = (
  <StepperNav aria-label="Sign-up steps">
    {STEPS.map(({ step, title, description }) => (
      <StepperItem key={step} step={step}>
        <StepperTrigger className="flex flex-col">
          <StepperIndicator>{step}</StepperIndicator>
          <StepperTitle>{title}</StepperTitle>
          <StepperDescription>{description}</StepperDescription>
        </StepperTrigger>
        {step < STEPS.length && <StepperSeparator />}
      </StepperItem>
    ))}
  </StepperNav>
);

export function StepperDemo() {
  return (
    <Stepper defaultValue={2} className="w-md">
      {nav}
    </Stepper>
  );
}
```

### Switch

A two-state on/off toggle switch, in default and compact sizes.

- Install: `pnpm dlx shadcn@latest add @fma-ds/switch`
- Registry item: https://ds.fmartinsandre.dev.br/r/switch.json
- Docs: https://ds.fmartinsandre.dev.br/components/switch
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Label } from "@/components/fma-ds/label";
import { Switch } from "@/components/fma-ds/switch";

export function SwitchDemo() {
  return (
    <div className="flex items-center gap-2">
      <Switch id="airplane-mode" />
      <Label htmlFor="airplane-mode">Airplane Mode</Label>
    </div>
  );
}
```

### Tab Nav

Navigation between the pages of an area that looks like tabs: a `<nav>` of react-aria links where the current page carries `aria-current="page"`.

Unlike `Tabs` there are no panels — each item is a route — so use it for sub-pages and `Tabs` for in-page views.

- **`variant`**: matches the tab styles — `default` (segmented on `muted`, the current page raised) or `line` (underlined).
- **Current item**: when `isCurrent` is set or its `href` matches `TabNav`'s `currentHref` (exactly, or with `matchPrefix` also on sub-paths).
- **`TabNavItem`**: takes an icon before its label; **`TabNavSeparator`** divides groups.
- **Overflow**: when items don't fit, the strip scrolls sideways and keeps the current page in view.

Wrap the app in react-aria's `RouterProvider` for client routing.

- Install: `pnpm dlx shadcn@latest add @fma-ds/tab-nav`
- Registry item: https://ds.fmartinsandre.dev.br/r/tab-nav.json
- Docs: https://ds.fmartinsandre.dev.br/components/tab-nav
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { TabNav, TabNavItem } from "@/components/fma-ds/tab-nav";

export function TabNavDemo() {
  return (
    <TabNav aria-label="Contratos">
      <TabNavItem href="/contratos/comprar">Comprar contrato</TabNavItem>
      <TabNavItem href="/contratos">Contratos adquiridos</TabNavItem>
    </TabNav>
  );
}
```

### Table

Semantic table primitives (header, body, rows, cells, footer, caption) built on react-aria-components' Table for accessible, sorting/selection-ready markup.

- Install: `pnpm dlx shadcn@latest add @fma-ds/table`
- Registry item: https://ds.fmartinsandre.dev.br/r/table.json
- Docs: https://ds.fmartinsandre.dev.br/components/table
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/fma-ds/table";

const invoices = [
  { invoice: "INV001", status: "Paid", method: "Credit Card", amount: "$250.00" },
  { invoice: "INV002", status: "Pending", method: "PayPal", amount: "$150.00" },
  { invoice: "INV003", status: "Unpaid", method: "Bank Transfer", amount: "$350.00" },
];

export function TableDemo() {
  return (
    <Table aria-label="Invoices">
      <TableCaption>A list of your recent invoices.</TableCaption>
      {/* react-aria: columns go straight into TableHeader, with no TableRow around them. */}
      <TableHeader>
        <TableHead isRowHeader>Invoice</TableHead>
        <TableHead>Status</TableHead>
        <TableHead>Method</TableHead>
        <TableHead>Amount</TableHead>
      </TableHeader>
      <TableBody>
        {invoices.map((row) => (
          <TableRow key={row.invoice} id={row.invoice}>
            <TableCell>{row.invoice}</TableCell>
            <TableCell>{row.status}</TableCell>
            <TableCell>{row.method}</TableCell>
            <TableCell>{row.amount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  );
}
```

### Tabs

A tab list and its panels for switching between related views, with default and line visual variants, horizontal or vertical orientation.

- Install: `pnpm dlx shadcn@latest add @fma-ds/tabs`
- Registry item: https://ds.fmartinsandre.dev.br/r/tabs.json
- Docs: https://ds.fmartinsandre.dev.br/components/tabs
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/fma-ds/tabs";

export function TabsDemo() {
  return (
    <Tabs defaultSelectedKey="account" className="w-96">
      <TabsList aria-label="Settings">
        <TabsTrigger id="account">Account</TabsTrigger>
        <TabsTrigger id="password">Password</TabsTrigger>
      </TabsList>
      <TabsContent id="account">Make changes to your account here.</TabsContent>
      <TabsContent id="password">Change your password here.</TabsContent>
    </Tabs>
  );
}
```

### Textarea

A multi-line text input that auto-sizes to its content by default (field-sizing-content), rather than staying a fixed number of rows.

- Install: `pnpm dlx shadcn@latest add @fma-ds/textarea`
- Registry item: https://ds.fmartinsandre.dev.br/r/textarea.json
- Docs: https://ds.fmartinsandre.dev.br/components/textarea
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Textarea } from "@/components/fma-ds/textarea";

export function TextareaDemo() {
  return <Textarea placeholder="Type your message here." />;
}
```

### Time Picker

A composable time picker: hour, minute, second and AM/PM columns, in a popover or in place.

- **Layouts**: in a popover (`TimePickerTrigger` + `TimePickerContent`), behind a typable field (`TimePickerInput`, which reads `930`, `14h30`, `2:30 pm`…) or in place (`TimePickerPanel`). `<TimePicker />` alone renders a trigger and a popover.
- **Value**: `@internationalized/date` `Time` objects (`value`/`defaultValue`/`onChange`, `null` when empty).
- **Columns**: `hourCycle`, `granularity` and `periodPosition` shape them.
- **Choices**: `hourStep`/`minuteStep`/`secondStep`, `minValue`/`maxValue` (an overnight window when min > max) and `isTimeUnavailable` narrow them, and a pick moves to the nearest selectable time.
- **`requireConfirm`**: keeps picks as a draft until OK.
- **Keyboard**: each column is an `aria-activedescendant` listbox — arrows, Home/End, PageUp/PageDown and typed digits pick, Left/Right move between columns, Enter commits and closes.
- **Forms**: `name` submits `HH:mm` (or `HH:mm:ss`) with a native form; `isRequired`, `isInvalid`, `isReadOnly` and `isDisabled` work as in react-aria.
- **`useTimePicker()`**: exposes the state inside a picker.

Every string comes from `i18n`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/time-picker`
- Registry item: https://ds.fmartinsandre.dev.br/r/time-picker.json
- Docs: https://ds.fmartinsandre.dev.br/components/time-picker
- npm: @internationalized/date@^3.12.4, cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/input-group, @fma-ds/popover

```tsx
import { Time } from "@internationalized/date";
import { TimePicker } from "@/components/fma-ds/time-picker";

export function TimePickerDemo() {
  return <TimePicker aria-label="Start time" defaultValue={new Time(9, 30)} className="w-36" />;
}
```

### Timeline

A vertical or horizontal timeline rendered as an ordered list.

- **`value`**: the current step. Items with `step <= value` get `data-completed` (filled indicator and separator), and the current one gets `aria-current="step"`.
- **`TimelineItem`**: composed from `TimelineHeader` (`TimelineDate`, `TimelineTitle`, `TimelineIndicator`), `TimelineSeparator` and `TimelineContent`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/timeline`
- Registry item: https://ds.fmartinsandre.dev.br/r/timeline.json
- Docs: https://ds.fmartinsandre.dev.br/components/timeline
- npm: cn@^0.5.0

```tsx
import {
  Timeline,
  TimelineContent,
  TimelineDate,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from "@/components/fma-ds/timeline";

const STEPS = [
  {
    step: 1,
    date: "Mar 2024",
    title: "Project kickoff",
    content: "Repository and architecture set up.",
  },
  { step: 2, date: "Apr 2024", title: "Beta release", content: "Beta shipped to early testers." },
  { step: 3, date: "Jun 2024", title: "Launch", content: "Platform available to everyone." },
];

const items = STEPS.map(({ step, date, title, content }) => (
  <TimelineItem key={step} step={step}>
    <TimelineHeader>
      <TimelineDate>{date}</TimelineDate>
      <TimelineTitle>{title}</TimelineTitle>
      <TimelineIndicator />
    </TimelineHeader>
    <TimelineSeparator />
    <TimelineContent>{content}</TimelineContent>
  </TimelineItem>
));

export function TimelineDemo() {
  return (
    <Timeline value={2} className="w-sm">
      {items}
    </Timeline>
  );
}
```

### Toggle

A single two-state pressable button (on/off) — the single-button counterpart to `ToggleGroup`.

- **Styles**: `default` and `outline` variants, in three sizes.
- **States**: pressed uses `accent` (the theme's selected surface); hover stays `muted`, as in shadcn, so hovering and pressed look different.

- Install: `pnpm dlx shadcn@latest add @fma-ds/toggle`
- Registry item: https://ds.fmartinsandre.dev.br/r/toggle.json
- Docs: https://ds.fmartinsandre.dev.br/components/toggle
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { Bold } from "lucide-react";
import { Toggle } from "@/components/fma-ds/toggle";

export function ToggleDemo() {
  return (
    <Toggle aria-label="Toggle bold">
      <Bold />
    </Toggle>
  );
}
```

### Toggle Group

A connected row (or column) of Toggle buttons sharing one visual variant/size/spacing, for grouped single- or multi-select controls (e.g. text formatting).

- Install: `pnpm dlx shadcn@latest add @fma-ds/toggle-group`
- Registry item: https://ds.fmartinsandre.dev.br/r/toggle-group.json
- Docs: https://ds.fmartinsandre.dev.br/components/toggle-group
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/toggle

```tsx
import { Bold, Italic, Underline } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/fma-ds/toggle-group";

export function ToggleGroupDemo() {
  return (
    <ToggleGroup selectionMode="multiple" aria-label="Text formatting">
      <ToggleGroupItem id="bold" aria-label="Toggle bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem id="italic" aria-label="Toggle italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem id="underline" aria-label="Toggle underline">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

### Tooltip

A short, non-interactive hint that appears on hover or keyboard focus of its trigger.

- Install: `pnpm dlx shadcn@latest add @fma-ds/tooltip`
- Registry item: https://ds.fmartinsandre.dev.br/r/tooltip.json
- Docs: https://ds.fmartinsandre.dev.br/components/tooltip
- npm: cn@^0.5.0, react-aria-components@^1.22.1

```tsx
import { PlusIcon } from "lucide-react";
import { Button } from "@/components/fma-ds/button";
import { Tooltip, TooltipTrigger } from "@/components/fma-ds/tooltip";

export function TooltipDemo() {
  return (
    <TooltipTrigger>
      <Button variant="outline" size="icon">
        <PlusIcon />
        <span className="sr-only">Add</span>
      </Button>
      <Tooltip placement="top">Add to library</Tooltip>
    </TooltipTrigger>
  );
}
```

### Trace

A compact activity log for AI agents.

- **`Trace`**: stacks `TraceLine`s — an optional `TraceIcon`, a `TraceTitle` and a `TraceDescription` — each with a `status` of running (shimmering title), pending or error.
- **`TraceCollapsible`**: wrap a line in it, with `TraceCollapsibleTrigger` and `TraceCollapsibleContent`, to reveal the details of a step.

- Install: `pnpm dlx shadcn@latest add @fma-ds/trace`
- Registry item: https://ds.fmartinsandre.dev.br/r/trace.json
- Docs: https://ds.fmartinsandre.dev.br/components/trace
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/collapsible

```tsx
import { FileTextIcon, SearchIcon, TerminalIcon } from "lucide-react";
import {
  Trace,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/fma-ds/trace";

export function TraceDemo() {
  return (
    <Trace className="max-w-md">
      <TraceLine>
        <TraceIcon>
          <SearchIcon />
        </TraceIcon>
        <TraceTitle>Searched the codebase</TraceTitle>
        <TraceDescription>12 results</TraceDescription>
      </TraceLine>
      <TraceLine status="running">
        <TraceIcon>
          <FileTextIcon />
        </TraceIcon>
        <TraceTitle>Reading badge.tsx</TraceTitle>
      </TraceLine>
      <TraceLine status="pending">
        <TraceIcon>
          <TerminalIcon />
        </TraceIcon>
        <TraceTitle>Running tests</TraceTitle>
      </TraceLine>
      <TraceLine status="error">
        <TraceIcon>
          <TerminalIcon />
        </TraceIcon>
        <TraceTitle>Type check failed</TraceTitle>
      </TraceLine>
    </Trace>
  );
}
```

## Blocks

### App Sidebar

An app-shell sidebar block, collapsible to icons: a team switcher (or a static logo), one navigation section per `data.nav` entry and a user menu.

Driven by an `AppSidebarData` object, so teams, sections and items are data. Render it inside a `SidebarProvider`.

- **Sub-items**: expand inline (`variant: "collapse"`) or open a menu (`"dropdown"`, and always while collapsed to icons).
- **Links**: react-aria `Link`s; wrap the app in `RouterProvider` for client-side routing.
- **Menus**: `onTeamChange`, `onAddTeam` and `onUserAction` handle them.

- Install: `pnpm dlx shadcn@latest add @fma-ds/app-sidebar`
- Registry item: https://ds.fmartinsandre.dev.br/r/app-sidebar.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/app-sidebar
- npm: lucide-react@^1.61.0
- Registry: @fma-ds/sidebar, @fma-ds/collapsible, @fma-ds/dropdown-menu, @fma-ds/avatar

```tsx
import {
  BookOpenIcon,
  BotIcon,
  BuildingIcon,
  FrameIcon,
  GalleryVerticalEndIcon,
  HomeIcon,
  Settings2Icon,
} from "lucide-react";
import { AppSidebar, type AppSidebarData } from "@/components/fma-ds/app-sidebar/app-sidebar";
import { SidebarInset, SidebarProvider, SidebarTrigger } from "@/components/fma-ds/sidebar";

const NAV: AppSidebarData["nav"] = [
  {
    title: "Platform",
    items: [
      { title: "Home", url: "/home", icon: <HomeIcon />, isActive: true },
      {
        title: "Models",
        url: "/models",
        icon: <BotIcon />,
        isActive: true,
        items: [
          { title: "Genesis", url: "/models/genesis" },
          { title: "Explorer", url: "/models/explorer" },
        ],
      },
      {
        title: "Docs",
        url: "/docs",
        icon: <BookOpenIcon />,
        variant: "dropdown",
        items: [
          { title: "Introduction", url: "/docs/intro" },
          { title: "Changelog", url: "/docs/changelog" },
        ],
      },
      {
        title: "Settings",
        url: "/settings",
        icon: <Settings2Icon />,
        items: [
          { title: "General", url: "/settings/general" },
          { title: "Billing", url: "/settings/billing" },
        ],
      },
    ],
  },
  {
    title: "Projects",
    items: [{ title: "Design Engineering", url: "/projects/design", icon: <FrameIcon /> }],
  },
];

const USER = { name: "Ada Lovelace", email: "ada@example.com", avatar: "" };

const TEAMS_DATA: AppSidebarData = {
  user: USER,
  nav: NAV,
  teams: [
    { name: "Acme Inc", plan: "Enterprise", logo: <GalleryVerticalEndIcon className="size-4" /> },
    { name: "Acme Corp.", plan: "Startup", logo: <BuildingIcon className="size-4" /> },
  ],
};

export function AppSidebarDemo() {
  return (
    <SidebarProvider className="h-[560px] min-h-0">
      <AppSidebar data={TEAMS_DATA} />
      <SidebarInset className="p-4">
        <SidebarTrigger />
        <p className="mt-4 text-sm text-muted-foreground">Page content goes here.</p>
      </SidebarInset>
    </SidebarProvider>
  );
}
```

### Auth

The frame of sign-in, sign-up and password recovery screens. The fields are the app's (`TextField`, `password-input`, `input-otp`, `password-rules`).

- **`AuthLayout`**: puts the `logo` on top and the content centered. With `brand` (product message, illustration) the page splits in two on wide screens, the brand area on a muted surface or, with `brandSurface="brand"`, the theme's brand color; without it, the column sits on a muted page.
- **`AuthCard`**: the form's card — `title` as the page's `h1`, `description`, your fields, and a centered `footer` for the links between screens.
- **`AuthSubmit`**: the full-width submit button, with a spinner while `isPending`.
- **`ResendCode`**: "Resend code" behind a cooldown (`cooldown` seconds, 60 by default, started on mount). It's disabled with an `m:ss` countdown, then `onResend` (pending while its promise runs) restarts it.

The stories show sign-in, forgot password and a two-step reset (the server checks the code, then the new password follows the rules).

Built-in text is in English; translate `ResendCode` with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/auth`
- Registry item: https://ds.fmartinsandre.dev.br/r/auth.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/auth
- npm: cn@^0.5.0
- Registry: @fma-ds/button, @fma-ds/card, @fma-ds/spinner, @fma-ds/brand

```tsx
import { CalculatorIcon } from "lucide-react";
import { useState } from "react";
import { FieldError, Form, Link, TextField } from "react-aria-components";
import { Alert, AlertDescription } from "@/components/fma-ds/alert";
import { AuthCard, AuthLayout, AuthSubmit } from "@/components/fma-ds/auth/auth";
import { IconTile } from "@/components/fma-ds/icon-tile";
import { Input } from "@/components/fma-ds/input";
import { Label } from "@/components/fma-ds/label";
import { PasswordInput } from "@/components/fma-ds/password-input";

const linkClass =
  "font-medium text-primary underline-offset-4 outline-none hover:underline focus-visible:underline";

function Logo() {
  return (
    <span className="flex items-center gap-2 font-medium">
      <IconTile variant="solid" size="sm">
        <CalculatorIcon />
      </IconTile>
      Orbita
    </span>
  );
}

/** The brand area: a product message on a quiet surface. */
function BrandPanel() {
  return (
    <div className="flex flex-1 flex-col justify-end gap-3 p-10">
      <p className="max-w-md text-2xl font-semibold text-balance">
        Pedidos, contratos e relatórios dos seus clientes num lugar só.
      </p>
      <p className="max-w-md text-muted-foreground">
        Acompanhe pendências e gere documentos sem trocar de sistema.
      </p>
    </div>
  );
}

/** Stands in for the app's sign-in request: resolves with an error message, if any. */
const signIn = (_email: string, password: string) =>
  new Promise<string | undefined>((resolve) =>
    setTimeout(
      () => resolve(password === "Segredo123" ? undefined : "E-mail ou senha incorretos."),
      500,
    ),
  );

export function AuthLogin() {
  const [error, setError] = useState<string>();
  const [isPending, setIsPending] = useState(false);

  return (
    <AuthLayout logo={<Logo />} brand={<BrandPanel />}>
      <AuthCard
        title="Entrar"
        description="Acesse sua conta com seu e-mail e senha."
        footer={
          <>
            Ainda não tem conta?{" "}
            <Link href="#cadastro" className={linkClass}>
              Criar conta
            </Link>
          </>
        }
      >
        <Form
          className="flex flex-col gap-4"
          onSubmit={async (event) => {
            event.preventDefault();
            const data = new FormData(event.currentTarget);
            setIsPending(true);
            setError(await signIn(String(data.get("email")), String(data.get("password"))));
            setIsPending(false);
          }}
        >
          {error && (
            <Alert variant="destructive">
              <AlertDescription>{error}</AlertDescription>
            </Alert>
          )}
          <TextField name="email" type="email" isRequired className="flex flex-col gap-2">
            <Label>E-mail</Label>
            <Input autoComplete="email" />
            <FieldError className="text-sm text-destructive" />
          </TextField>
          <TextField name="password" isRequired className="flex flex-col gap-2">
            <div className="flex items-center">
              <Label>Senha</Label>
              <Link href="#esqueci-a-senha" className={`ml-auto text-sm ${linkClass}`}>
                Esqueci minha senha
              </Link>
            </div>
            <PasswordInput autoComplete="current-password" toggleLabel="Mostrar senha" />
            <FieldError className="text-sm text-destructive" />
          </TextField>
          <AuthSubmit isPending={isPending}>Entrar</AuthSubmit>
        </Form>
      </AuthCard>
    </AuthLayout>
  );
}
```

### Collection Field

A list edited in place inside a form: the user adds an item and fills it right there (payment methods, lots, recipients).

Rows, state and validation stay in the app (`useFieldArray`'s `fields`, `append`, `remove`).

- **`CollectionField`**: takes the `label` (a legend), `description`, the list's `error`, `itemCount`, `onAdd` and `addLabel`. `minItems` removes the remove buttons at the minimum, `maxItems` swaps the add button for a note once reached, and an empty list shows `emptyMessage`.
- **`CollectionFieldItem`**: `label` is numbered ("Lot 2") and also names its remove button; `onRemove` removes it. Two layouts: `row` for a few fields side by side on wide screens, with the remove button at the end; `group` for many fields under a visible legend with a static border, so items stay apart when fields stack on small screens.
- **`CollectionFieldSummary`** with **`CollectionFieldSummaryItem`**: the total, what is allocated and what remains (`isEmphasized`: by size and weight, with the state in words).
- **Focus**: adding announces the new item and focuses its first field; removing announces it and focuses the add button.

Lists filled elsewhere and only shown here (edited in a dialog, listed in a table) are a composition of `data-grid`/`item` and `dialog`, not this block.

Built-in text is in English; translate it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/collection-field`
- Registry item: https://ds.fmartinsandre.dev.br/r/collection-field.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/collection-field
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button, @fma-ds/description-list, @fma-ds/empty, @fma-ds/field

```tsx
import { zodResolver } from "@hookform/resolvers/zod";
import { Controller, useFieldArray, useForm } from "react-hook-form";
import * as z from "zod";
import { Button } from "@/components/fma-ds/button";
import {
  CollectionField,
  type CollectionFieldI18n,
  CollectionFieldItem,
  CollectionFieldSummary,
  CollectionFieldSummaryItem,
} from "@/components/fma-ds/collection-field/collection-field";
import { Field, FieldError, FieldLabel } from "@/components/fma-ds/field";
import { MaskedInput } from "@/components/fma-ds/masked-input";
import { NativeSelect, NativeSelectOption } from "@/components/fma-ds/native-select";

const PT_BR: CollectionFieldI18n = {
  labels: {
    remove: (item) => `Remover ${item.toLocaleLowerCase("pt-BR")}`,
    removeText: "Remover",
    added: (item) => `${item} adicionado`,
    removed: (item) => `${item} removido`,
    maxReached: (max) => `Até ${max} itens.`,
    empty: "Nada adicionado ainda.",
  },
};

const brl = (value: number) =>
  new Intl.NumberFormat("pt-BR", { style: "currency", currency: "BRL" }).format(value);

const ORDER_TOTAL = 150;

const paymentsSchema = z
  .object({
    payments: z.array(
      z.object({
        method: z.string().min(1, "Escolha a forma."),
        amount: z.string().refine((value) => Number(value) > 0, "Informe o valor."),
      }),
    ),
  })
  .refine(
    ({ payments }) =>
      Math.abs(payments.reduce((sum, item) => sum + Number(item.amount || 0), 0) - ORDER_TOTAL) <
      0.005,
    { path: ["payments"], message: "As formas de pagamento precisam somar o total do pedido." },
  );

type PaymentsValues = z.infer<typeof paymentsSchema>;

export function CollectionFieldPaymentMethods() {
  const form = useForm<PaymentsValues>({
    resolver: zodResolver(paymentsSchema),
    defaultValues: { payments: [{ method: "pix", amount: "" }] },
  });
  const { fields, append, remove } = useFieldArray({ control: form.control, name: "payments" });
  const payments = form.watch("payments");
  const paid = payments.reduce((sum, item) => sum + Number(item.amount || 0), 0);
  const remaining = Math.round((ORDER_TOTAL - paid) * 100) / 100;
  const listError = form.formState.errors.payments;

  return (
    <form
      onSubmit={form.handleSubmit(() => {})}
      className="flex w-full max-w-[30rem] flex-col gap-4"
      noValidate
    >
      <CollectionField
        i18n={{
          labels: {
            ...PT_BR.labels,
            added: (item) => `${item} adicionada`,
            removed: (item) => `${item} removida`,
          },
        }}
        label="Formas de pagamento"
        itemCount={fields.length}
        minItems={1}
        maxItems={4}
        // A new method starts with what is left to pay.
        onAdd={() => append({ method: "", amount: remaining > 0 ? remaining.toFixed(2) : "" })}
        addLabel="Adicionar forma"
        error={listError?.message ?? listError?.root?.message}
        summary={
          <CollectionFieldSummary>
            <CollectionFieldSummaryItem label="Total do pedido" value={brl(ORDER_TOTAL)} />
            <CollectionFieldSummaryItem label="Pago" value={brl(paid)} />
            <CollectionFieldSummaryItem
              label="Restante"
              value={
                remaining > 0
                  ? `Faltam ${brl(remaining)}`
                  : remaining < 0
                    ? `${brl(-remaining)} a mais`
                    : "Valor fechado"
              }
              isEmphasized
            />
          </CollectionFieldSummary>
        }
      >
        {fields.map((item, index) => (
          <CollectionFieldItem
            key={item.id}
            label={`Forma de pagamento ${index + 1}`}
            onRemove={() => remove(index)}
          >
            <Controller
              control={form.control}
              name={`payments.${index}.method`}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid} className="sm:w-44">
                  <FieldLabel htmlFor={`${item.id}-method`}>Forma</FieldLabel>
                  <NativeSelect
                    id={`${item.id}-method`}
                    aria-invalid={fieldState.invalid}
                    className="w-full"
                    {...field}
                  >
                    <NativeSelectOption value="">Escolha</NativeSelectOption>
                    <NativeSelectOption value="pix">Pix</NativeSelectOption>
                    <NativeSelectOption value="cash">Dinheiro</NativeSelectOption>
                    <NativeSelectOption value="card">Cartão</NativeSelectOption>
                  </NativeSelect>
                  {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
                </Field>
              )}
            />
            <Controller
              control={form.control}
              name={`payments.${index}.amount`}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid} className="flex-1">
                  <FieldLabel htmlFor={`${item.id}-amount`}>Valor</FieldLabel>
                  <MaskedInput
                    id={`${item.id}-amount`}
                    mask={{ type: "decimal", prefix: "R$ " }}
                    name={field.name}
                    ref={field.ref}
                    value={field.value}
                    onValueChange={field.onChange}
                    onBlur={field.onBlur}
                    aria-invalid={fieldState.invalid}
                  />
                  {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
                </Field>
              )}
            />
          </CollectionFieldItem>
        ))}
      </CollectionField>
      <Button type="submit" className="self-end">
        Registrar
      </Button>
    </form>
  );
}
```

### Error Pages

Error screens on top of `empty` and `icon-stack`: `NotFound` (404), `Forbidden` (403) and `UnexpectedError`, plus the bare `ErrorPage` for other cases (maintenance, expired link).

Each shows an icon, the status `code` as a small label, the title as the page's `h1`, a description and your `actions` (home, back, support).

- **Layout**: `layout="page"` fills the viewport; `layout="inline"` fills the content area of the app's layout.
- **`UnexpectedError`**: puts a "Try again" button first with `onRetry` (pending while its promise runs). With `error`, it adds a collapsible `ErrorDetails` with the message and stack and a button that copies them — leave `error` out where users shouldn't see it.
- **In the app**: wiring to the router (error and not-found routes), reporting and automatic reloads.

Built-in text is in English; translate it with `i18n.labels`, or override `title` and `description`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/error-pages`
- Registry item: https://ds.fmartinsandre.dev.br/r/error-pages.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/error-pages
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button, @fma-ds/collapsible, @fma-ds/copy-button, @fma-ds/empty, @fma-ds/icon-stack

```tsx
import { HouseIcon } from "lucide-react";
import { LinkButton } from "@/components/fma-ds/button";
import { NotFound } from "@/components/fma-ds/error-pages/error-pages";

export function ErrorPagesNotFoundPage() {
  return (
    <NotFound
      i18n={{
        labels: {
          title: "Página não encontrada",
          description: "A página que você procura não existe ou mudou de endereço.",
        },
      }}
      actions={
        <LinkButton href="/">
          <HouseIcon data-icon="inline-start" aria-hidden="true" />
          Voltar ao início
        </LinkButton>
      }
    />
  );
}
```

### Event Calendar

A headless-first event calendar: month, week, day, N-day, agenda and resource views, with recurring events, time zones and drag and drop.

- **Recurrence**: structured rules or RRULE strings.
- **Drag and drop**: drag to move, resize and create; keyboard users create through `showDayAddButton`'s per-day buttons.
- **i18n**: with RTL support.
- **State**: a subscribable store (`useEventCalendar`, `useEventCalendarSelector`).

Compose `<EventCalendar>` with `EventCalendarNav` and `EventCalendarContent`, or build your own parts from the hooks. Events are controlled (`events`/`onEventsChange`) or not (`defaultEvents`); `onEventUpdate` accepts, rejects or adjusts each drag.

The nav, view switcher, date picker and "+N more" popover use the registry's react-aria `Button`, `Tooltip`, `DropdownMenu`, `Popover` and `Calendar`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/event-calendar`
- Registry item: https://ds.fmartinsandre.dev.br/r/event-calendar.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/event-calendar
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1, @internationalized/date@^3.12.4
- Registry: @fma-ds/icon-stack, @fma-ds/scroll-area, @fma-ds/tooltip, @fma-ds/popover, @fma-ds/button, @fma-ds/calendar, @fma-ds/dropdown-menu, @fma-ds/date-fns-compat

```tsx
import { EventCalendar } from "@/components/fma-ds/event-calendar/event-calendar";
import { EventCalendarContent } from "@/components/fma-ds/event-calendar/event-calendar-content";
import { EventCalendarNav } from "@/components/fma-ds/event-calendar/event-calendar-nav";
import type {
  CalendarEvent,
  EventCalendarResource,
} from "@/components/fma-ds/event-calendar/event-calendar-types";

// A fixed week (Sun 8 - Sat 14 March 2026, UTC) keeps the stories deterministic.
const at = (day: number, hour = 0, minute = 0) => new Date(Date.UTC(2026, 2, day, hour, minute));

const TODAY = at(11, 12);

const TEAM: EventCalendarResource[] = [
  { id: "alex", title: "Alex", color: "var(--color-blue-500)" },
  { id: "mia", title: "Mia", color: "var(--color-violet-500)" },
  { id: "sam", title: "Sam", color: "var(--color-emerald-500)" },
];

const EVENTS: CalendarEvent[] = [
  { id: "sync", title: "Team sync", start: at(9, 9), end: at(9, 9, 30), resourceId: "alex" },
  {
    id: "review",
    title: "Design review",
    start: at(10, 11),
    end: at(10, 12),
    resourceId: "mia",
    color: "var(--color-violet-500)",
  },
  {
    id: "demo",
    title: "Product demo",
    start: at(11, 15),
    end: at(11, 16),
    resourceId: "sam",
    color: "var(--color-emerald-500)",
  },
  {
    id: "offsite",
    title: "Team offsite",
    start: at(12),
    end: at(14),
    allDay: true,
    color: "var(--color-rose-500)",
  },
  {
    id: "standup",
    title: "Standup",
    start: at(9, 8, 30),
    end: at(9, 8, 45),
    recurrence: "RRULE:FREQ=DAILY;COUNT=5",
    resourceId: "alex",
  },
];

export function EventCalendarWeek() {
  return (
    <div className="flex h-[640px] w-[960px] flex-col rounded-lg border">
      <EventCalendar
        defaultEvents={EVENTS}
        defaultView="week"
        defaultDate={TODAY}
        resources={TEAM}
        dayStartHour={7}
        className="flex min-h-0 flex-1 flex-col"
      >
        <EventCalendarNav />
        <EventCalendarContent />
      </EventCalendar>
    </div>
  );
}
```

### Feature Promo

A locked feature or an offer on a card: why it matters, what it gives and the call to action.

Inside `FeaturePromo`, put:

- **`FeaturePromoContent`**: with `FeaturePromoTitle`, one or more `FeaturePromoDescription`, `FeaturePromoBenefits` of `FeaturePromoBenefit` (with an `icon` tile) and `FeaturePromoActions`.
- **`FeaturePromoMedia`** (optional): a framed panel — no background images or gradients.
- **`FeaturePromoGrid`** (optional): spans the full width with one to three columns — choice cards, `Item`s with `href` for shortcuts, or cards that explain options.

`variant="brand"` frames the card with a primary → brand gradient border.

`layout="split"` puts the media beside the content and hides it when the card is narrow; `layout="centered"` stacks everything in the middle.

With a `FeaturePromoAcceptance` (a checkbox card), the buttons in `FeaturePromoActions` stay disabled until it is checked — uncontrolled (`defaultAccepted`) or controlled (`isAccepted` + `onAcceptedChange`).

- Install: `pnpm dlx shadcn@latest add @fma-ds/feature-promo`
- Registry item: https://ds.fmartinsandre.dev.br/r/feature-promo.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/feature-promo
- npm: cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/checkbox, @fma-ds/icon-tile, @fma-ds/brand

```tsx
import { ChartPieIcon, ShieldCheckIcon, ShoppingCartIcon } from "lucide-react";
import { LinkButton } from "@/components/fma-ds/button";
import {
  FeaturePromo,
  FeaturePromoActions,
  FeaturePromoBenefit,
  FeaturePromoBenefits,
  FeaturePromoContent,
  FeaturePromoDescription,
  FeaturePromoMedia,
  FeaturePromoTitle,
} from "@/components/fma-ds/feature-promo/feature-promo";
import { Progress, ProgressLabel, ProgressValue } from "@/components/fma-ds/progress";

export function FeaturePromoLockedFeature() {
  return (
    <FeaturePromo>
      <FeaturePromoContent>
        <FeaturePromoTitle>Ative o gestor e compre pedidos adicionais</FeaturePromoTitle>
        <FeaturePromoDescription>
          Para comprar pedidos adicionais é preciso ter um plano ativo do gestor de pedidos.
        </FeaturePromoDescription>
        <FeaturePromoDescription>
          Com o plano, você registra produtos e serviços e compra pedidos avulsos sempre que
          precisar.
        </FeaturePromoDescription>
        <FeaturePromoBenefits>
          <FeaturePromoBenefit icon={<ShieldCheckIcon />}>
            Registro de pedidos com histórico completo
          </FeaturePromoBenefit>
          <FeaturePromoBenefit icon={<ChartPieIcon />}>
            Acompanhamento do saldo de pedidos do mês
          </FeaturePromoBenefit>
          <FeaturePromoBenefit icon={<ShoppingCartIcon />}>
            Compra avulsa de pedidos conforme a demanda
          </FeaturePromoBenefit>
        </FeaturePromoBenefits>
        <FeaturePromoActions>
          <LinkButton href="/planos" size="lg">
            Quero contratar agora
          </LinkButton>
        </FeaturePromoActions>
      </FeaturePromoContent>
      <FeaturePromoMedia className="flex flex-col justify-center gap-4 p-8">
        <div className="rounded-lg bg-card p-4 shadow-xs ring-1 ring-foreground/10">
          <Progress value={184} maxValue={240}>
            <ProgressLabel>Pedidos do mês</ProgressLabel>
            <ProgressValue />
          </Progress>
        </div>
        <div className="rounded-lg bg-card p-4 shadow-xs ring-1 ring-foreground/10">
          <Progress value={12} maxValue={50}>
            <ProgressLabel>Pedidos adicionais</ProgressLabel>
            <ProgressValue />
          </Progress>
        </div>
      </FeaturePromoMedia>
    </FeaturePromo>
  );
}
```

### Filter Toolbar

The controls above a list or `DataGrid`, composed from parts that are each controlled (`value`/`onChange`), so every filter maps to a search param.

- **`FilterToolbar`**: lays the parts out, wrapping on narrow screens; its `i18n.labels` reaches every part.
- **`FilterSearch`**: a react-aria `SearchField` that commits the term on Enter and when cleared — and, with `debounceMs`, after the user stops typing.
- **`FilterQuickToggles`**: an outlined `ToggleGroup` for one-press filters.
- **`FilterToolbarActions`**: holds the trailing actions, `FilterSheet` and `FilterRefresh`.
- **`FilterSheet`**: a "Filters" button with the active count, opening a side `Sheet`. Its children are the `Field`s of a draft the app keeps: `onApply` commits it (return `false` to stay open), `onClear` empties it, and Enter applies.
- **`FilterRefresh`**: spins while `isPending`.
- **`FilterChips`**: the applied filters as a react-aria `TagGroup`, each removable with its × or Backspace/Delete, plus "Clear filters". Renders nothing when empty.

- Install: `pnpm dlx shadcn@latest add @fma-ds/filter-toolbar`
- Registry item: https://ds.fmartinsandre.dev.br/r/filter-toolbar.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/filter-toolbar
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/badge, @fma-ds/button, @fma-ds/input, @fma-ds/input-group, @fma-ds/sheet, @fma-ds/toggle-group, @fma-ds/tooltip

```tsx
import { CalendarDate } from "@internationalized/date";
import * as React from "react";
import { type RangeValue } from "react-aria-components";
import { Badge } from "@/components/fma-ds/badge";
import { DateInput } from "@/components/fma-ds/date-field";
import {
  DatePickerContent,
  DatePickerTrigger,
  DateRangePicker,
} from "@/components/fma-ds/date-picker";
import { FieldLabel } from "@/components/fma-ds/field";
import {
  type FilterChip,
  FilterChips,
  FilterQuickToggles,
  FilterRefresh,
  FilterSearch,
  FilterSheet,
  FilterToolbar,
  FilterToolbarActions,
  type FilterToolbarI18n,
} from "@/components/fma-ds/filter-toolbar/filter-toolbar";
import { InputGroup, InputGroupAddon } from "@/components/fma-ds/input-group";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/fma-ds/select";
import { ToggleGroupItem } from "@/components/fma-ds/toggle-group";

const ptBR: FilterToolbarI18n = {
  labels: {
    search: "Buscar",
    searchPlaceholder: "Buscar…",
    clearSearch: "Limpar busca",
    quickFilters: "Filtros rápidos",
    filters: "Filtros",
    filtersTrigger: (active) => (active > 0 ? `Filtros, ${active} ativos` : "Filtros"),
    filtersTitle: "Filtrar resultados",
    apply: "Aplicar",
    clear: "Limpar",
    activeFilters: "Filtros ativos",
    clearAll: "Limpar filtros",
    refresh: "Atualizar lista",
  },
};

type Client = {
  name: string;
  document: string;
  status: "ativo" | "bloqueado";
  size: "pequena" | "media" | "grande";
  modules: ("pedidos" | "vendas")[];
  createdAt: CalendarDate;
};

const CLIENTS: Client[] = [
  {
    name: "Padaria Pão Quente Ltda",
    document: "12.345.678/0001-90",
    status: "ativo",
    size: "media",
    modules: ["pedidos", "vendas"],
    createdAt: new CalendarDate(2026, 2, 10),
  },
  {
    name: "João Silva",
    document: "45.987.321/0001-12",
    status: "ativo",
    size: "pequena",
    modules: ["pedidos"],
    createdAt: new CalendarDate(2026, 5, 3),
  },
  {
    name: "Oficina Duas Rodas",
    document: "08.112.443/0001-55",
    status: "bloqueado",
    size: "media",
    modules: [],
    createdAt: new CalendarDate(2025, 11, 21),
  },
  {
    name: "Clínica Bem Estar S/A",
    document: "33.004.876/0001-07",
    status: "ativo",
    size: "grande",
    modules: ["vendas"],
    createdAt: new CalendarDate(2026, 8, 18),
  },
  {
    name: "Maria Souza",
    document: "123.456.789-09",
    status: "ativo",
    size: "pequena",
    modules: [],
    createdAt: new CalendarDate(2026, 9, 1),
  },
];

const STATUS_LABELS = { ativo: "Ativo", bloqueado: "Bloqueado" };

const SIZE_LABELS = { pequena: "Pequena", media: "Média", grande: "Grande" };

/** What the app would keep in the route's search params. */
type ClientFilters = {
  search: string;
  modules: string[];
  status: keyof typeof STATUS_LABELS | null;
  size: keyof typeof SIZE_LABELS | null;
  createdAt: RangeValue<CalendarDate> | null;
};

const NO_FILTERS: ClientFilters = {
  search: "",
  modules: [],
  status: null,
  size: null,
  createdAt: null,
};

function applyFilters(clients: Client[], filters: ClientFilters) {
  const term = filters.search.toLowerCase();
  return clients.filter(
    (client) =>
      (!term || `${client.name} ${client.document}`.toLowerCase().includes(term)) &&
      filters.modules.every((module) =>
        module === "nenhum"
          ? client.modules.length === 0
          : client.modules.includes(module as "pedidos" | "vendas"),
      ) &&
      (!filters.status || client.status === filters.status) &&
      (!filters.size || client.size === filters.size) &&
      (!filters.createdAt ||
        (client.createdAt.compare(filters.createdAt.start) >= 0 &&
          client.createdAt.compare(filters.createdAt.end) <= 0)),
  );
}

const formatDate = (date: CalendarDate) =>
  date.toDate("UTC").toLocaleDateString("pt-BR", { timeZone: "UTC" });

/** The applied advanced filters, formatted for the chips. */
function activeChips(filters: ClientFilters): FilterChip[] {
  const chips: FilterChip[] = [];
  if (filters.status) {
    chips.push({ id: "status", label: "Situação", value: STATUS_LABELS[filters.status] });
  }
  if (filters.size) {
    chips.push({ id: "size", label: "Porte", value: SIZE_LABELS[filters.size] });
  }
  if (filters.createdAt) {
    const { start, end } = filters.createdAt;
    chips.push({
      id: "createdAt",
      label: "Cadastro",
      value: `${formatDate(start)} – ${formatDate(end)}`,
    });
  }
  return chips;
}

/** "Sem módulos" can't be combined with a module, and vice versa. */
function nextModules(previous: string[], selected: string[]) {
  const added = selected.filter((key) => !previous.includes(key));
  if (added.includes("nenhum")) return ["nenhum"];
  return added.length ? selected.filter((key) => key !== "nenhum") : selected;
}

export function FilterToolbarDemo() {
  const [filters, setFilters] = React.useState(NO_FILTERS);
  const [draft, setDraft] = React.useState(NO_FILTERS);
  const [isRefreshing, setIsRefreshing] = React.useState(false);
  const chips = activeChips(filters);
  const clients = applyFilters(CLIENTS, filters);

  function refresh() {
    setIsRefreshing(true);
    setTimeout(() => setIsRefreshing(false), 800);
  }

  return (
    <div className="flex w-full max-w-4xl flex-col gap-4">
      <FilterToolbar i18n={ptBR}>
        <FilterSearch
          value={filters.search}
          onChange={(search) => setFilters({ ...filters, search })}
          placeholder="Nome, CNPJ ou CPF"
          maxLength={120}
        />
        <FilterQuickToggles
          selectionMode="multiple"
          size="sm"
          selectedKeys={filters.modules}
          onSelectionChange={(keys) =>
            setFilters({
              ...filters,
              modules: nextModules(filters.modules, [...keys].map(String)),
            })
          }
        >
          <ToggleGroupItem id="pedidos">Pedidos</ToggleGroupItem>
          <ToggleGroupItem id="vendas">Vendas</ToggleGroupItem>
          <ToggleGroupItem id="nenhum">Sem módulos</ToggleGroupItem>
        </FilterQuickToggles>
        <FilterToolbarActions>
          <FilterSheet
            activeCount={chips.length}
            onOpenChange={(isOpen) => isOpen && setDraft(filters)}
            onApply={() => {
              setFilters({ ...filters, ...draft, search: filters.search });
              return undefined;
            }}
            onClear={() => setDraft({ ...draft, status: null, size: null, createdAt: null })}
          >
            <Select
              placeholder="Todas"
              selectedKey={draft.status}
              onSelectionChange={(status) =>
                setDraft({ ...draft, status: status as ClientFilters["status"] })
              }
              className="flex w-full flex-col gap-2"
            >
              <FieldLabel>Situação</FieldLabel>
              <SelectTrigger className="w-full">
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                <SelectItem id="ativo">Ativo</SelectItem>
                <SelectItem id="bloqueado">Bloqueado</SelectItem>
              </SelectContent>
            </Select>
            <Select
              placeholder="Todos"
              selectedKey={draft.size}
              onSelectionChange={(size) =>
                setDraft({ ...draft, size: size as ClientFilters["size"] })
              }
              className="flex w-full flex-col gap-2"
            >
              <FieldLabel>Porte da empresa</FieldLabel>
              <SelectTrigger className="w-full">
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                <SelectItem id="pequena">Pequena</SelectItem>
                <SelectItem id="media">Média</SelectItem>
                <SelectItem id="grande">Grande</SelectItem>
              </SelectContent>
            </Select>
            <DateRangePicker
              value={draft.createdAt}
              onChange={(createdAt) =>
                setDraft({
                  ...draft,
                  createdAt: createdAt as RangeValue<CalendarDate> | null,
                })
              }
            >
              <FieldLabel>Data de cadastro</FieldLabel>
              <InputGroup>
                <DateInput slot="start" />
                <span aria-hidden="true" className="text-muted-foreground">
                  –
                </span>
                <DateInput slot="end" />
                <InputGroupAddon align="inline-end" className="ml-auto">
                  <DatePickerTrigger />
                </InputGroupAddon>
              </InputGroup>
              <DatePickerContent />
            </DateRangePicker>
          </FilterSheet>
          <FilterRefresh onRefresh={refresh} isPending={isRefreshing} />
        </FilterToolbarActions>
        <FilterChips
          items={chips}
          onRemove={(id) => setFilters({ ...filters, [id]: null })}
          onClearAll={() => setFilters(NO_FILTERS)}
        />
      </FilterToolbar>
      <p className="text-sm text-muted-foreground">{clients.length} clientes</p>
      <ul className="divide-y rounded-lg border">
        {clients.map((client) => (
          <li key={client.document} className="flex items-center justify-between gap-3 p-3">
            <div className="flex min-w-0 flex-col">
              <span className="truncate font-medium">{client.name}</span>
              <span className="text-sm text-muted-foreground">{client.document}</span>
            </div>
            <Badge variant={client.status === "ativo" ? "success-dot" : "destructive-dot"}>
              {STATUS_LABELS[client.status]}
            </Badge>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### Form Wizard

A form in steps, in a dialog or on a page (a new customer, an onboarding).

`FormWizard` takes `steps` (`{ title, description }` per step) and the current step, controlled (`step`/`onStepChange`) or not (`defaultStep`).

- **Navigation**: it's a react-aria `Form` whose submit is Next, so Enter advances and the current step's fields validate natively (only that step is mounted). Then `onNext(step)` runs — validate or save there (react-hook-form's `trigger`). Returning `false` or throwing keeps the user on the step, and a promise shows Next as pending. Finish runs `onNext` of the last step and then `onComplete`.
- **`FormWizardSteps`**: the `stepper` list. Earlier steps are reachable, later ones only through Next. Titles show when the wizard is wide enough for that many steps; narrower, only the numbers, with the current title under them (container query).
- **`FormWizardStep`**: holds a step's fields; after Back or Next, focus moves to its first field.
- **`FormWizardFooter`**: the progress ("Step 2 of 4", announced politely), `children` before Back (a dialog's Cancel), Back and Next/Finish.

The values stay in the app; with react-hook-form, keep `shouldUnregister` off.

Built-in text is in English; translate it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/form-wizard`
- Registry item: https://ds.fmartinsandre.dev.br/r/form-wizard.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/form-wizard
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/spinner, @fma-ds/stepper

```tsx
import { useState } from "react";
import { FieldError, TextField, type TextFieldProps } from "react-aria-components";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/fma-ds/card";
import {
  DescriptionDetails,
  DescriptionItem,
  DescriptionList,
  DescriptionTerm,
} from "@/components/fma-ds/description-list";
import {
  FormWizard,
  FormWizardFooter,
  type FormWizardI18n,
  FormWizardStep,
  FormWizardSteps,
} from "@/components/fma-ds/form-wizard/form-wizard";
import { Input } from "@/components/fma-ds/input";
import { Label } from "@/components/fma-ds/label";

const PT_BR: FormWizardI18n = {
  labels: {
    steps: "Etapas",
    back: "Voltar",
    next: "Próximo",
    finish: "Concluir",
    progress: (step, total) => `Etapa ${step} de ${total}`,
  },
};

/** A text field with label and validation message. */
function TextInput({ label, ...props }: TextFieldProps & { label: string }) {
  return (
    <TextField className="flex flex-col gap-2" {...props}>
      <Label>{label}</Label>
      <Input />
      <FieldError className="text-sm text-destructive" />
    </TextField>
  );
}

const CLIENT_STEPS = [
  { title: "Identificação", description: "Nome e documento" },
  { title: "Endereço", description: "Onde fica a empresa" },
  { title: "Contato", description: "Quem recebe os avisos" },
  { title: "Revisão", description: "Confira antes de salvar" },
];

type Client = { name: string; document: string; zip: string; city: string; email: string };

const EMPTY_CLIENT: Client = { name: "", document: "", zip: "", city: "", email: "" };

/** Stands in for the app's API: is the document already registered? */
const isRegistered = (document: string) =>
  new Promise<boolean>((resolve) => setTimeout(() => resolve(document === "00000000000"), 500));

export function FormWizardDemo() {
  const [client, setClient] = useState(EMPTY_CLIENT);
  const [serverErrors, setServerErrors] = useState<Record<string, string>>({});
  const set = (patch: Partial<Client>) => setClient((current) => ({ ...current, ...patch }));

  return (
    <Card className="max-w-2xl">
      <CardHeader>
        <CardTitle>Novo cliente</CardTitle>
      </CardHeader>
      <CardContent>
        <FormWizard
          i18n={PT_BR}
          steps={CLIENT_STEPS}
          validationErrors={serverErrors}
          onNext={async (step) => {
            if (step !== 1) return true;
            if (await isRegistered(client.document)) {
              setServerErrors({ document: "Já existe um cliente com este documento." });
              return false;
            }
            setServerErrors({});
            return true;
          }}
        >
          <FormWizardSteps />
          <FormWizardStep step={1}>
            <TextInput
              label="Nome ou razão social"
              isRequired
              value={client.name}
              onChange={(name) => set({ name })}
            />
            <TextInput
              label="CPF ou CNPJ"
              name="document"
              isRequired
              value={client.document}
              onChange={(document) => set({ document })}
            />
          </FormWizardStep>
          <FormWizardStep step={2}>
            <TextInput label="CEP" isRequired value={client.zip} onChange={(zip) => set({ zip })} />
            <TextInput
              label="Cidade"
              isRequired
              value={client.city}
              onChange={(city) => set({ city })}
            />
          </FormWizardStep>
          <FormWizardStep step={3}>
            <TextInput
              label="E-mail"
              type="email"
              isRequired
              value={client.email}
              onChange={(email) => set({ email })}
            />
          </FormWizardStep>
          <FormWizardStep step={4}>
            <DescriptionList divided>
              <DescriptionItem>
                <DescriptionTerm>Nome</DescriptionTerm>
                <DescriptionDetails>{client.name}</DescriptionDetails>
              </DescriptionItem>
              <DescriptionItem>
                <DescriptionTerm>Documento</DescriptionTerm>
                <DescriptionDetails>{client.document}</DescriptionDetails>
              </DescriptionItem>
              <DescriptionItem>
                <DescriptionTerm>Cidade</DescriptionTerm>
                <DescriptionDetails>{client.city}</DescriptionDetails>
              </DescriptionItem>
              <DescriptionItem>
                <DescriptionTerm>E-mail</DescriptionTerm>
                <DescriptionDetails>{client.email}</DescriptionDetails>
              </DescriptionItem>
            </DescriptionList>
          </FormWizardStep>
          <FormWizardFooter />
        </FormWizard>
      </CardContent>
    </Card>
  );
}
```

### Notification Center

Notifications in the header and on their own page, driven by props and callbacks (no server state).

- **`NotificationMenu`**: the bell — an icon `GlanceTrigger` whose `GlanceIndicator` shows the unread count (also in the button's name). It opens a panel with the recent items, "Mark all as read" (`onMarkAllAsRead`), loading and empty states and a "View all" link (`viewAllHref`).
- **`NotificationList`**: every notification as cards with a read/unread `Badge`, for a page paired with `Pagination`.
- **`NotificationItem`**: an unread dot (or an `icon`), the title — a link when it has `href`, calling `onOpen` — the message, the date (formatted in the `I18nProvider` locale) and icon buttons for `onMarkAsRead` and `onDelete`, described by the title.

Urgent notifications are a `ConfirmDialog` opened with `useDialogPromise`.

Built-in text is in English; override it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/notification-center`
- Registry item: https://ds.fmartinsandre.dev.br/r/notification-center.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/notification-center
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/badge, @fma-ds/button, @fma-ds/empty, @fma-ds/glance, @fma-ds/skeleton, @fma-ds/tooltip

```tsx
import * as React from "react";
import {
  type NotificationData,
  type NotificationI18n,
  NotificationMenu,
} from "@/components/fma-ds/notification-center/notification-center";

const ptBR: NotificationI18n = {
  labels: {
    title: "Notificações",
    trigger: (unread) =>
      unread === 0
        ? "Notificações, nenhuma não lida"
        : `Notificações, ${unread} ${unread === 1 ? "não lida" : "não lidas"}`,
    unread: "Não lida",
    read: "Lida",
    markAsRead: "Marcar como lida",
    markAllAsRead: "Marcar todas como lidas",
    delete: "Apagar",
    empty: "Nenhuma notificação",
    emptyDescription: "Você está em dia.",
    loading: "Carregando notificações…",
    viewAll: "Ver todas as notificações",
  },
};

const initialNotifications: NotificationData[] = [
  {
    id: "1",
    title: "Contrato de serviço vence em 7 dias",
    message: "Renove o contrato da Padaria Pão Quente para continuar registrando pedidos.",
    date: new Date("2026-10-19T13:20:00Z"),
    href: "/contratos",
  },
  {
    id: "2",
    title: "Fatura de outubro disponível",
    message: "A fatura vence em 25/10. Pague por boleto ou Pix.",
    date: new Date("2026-10-18T09:05:00Z"),
  },
  {
    id: "3",
    title: "Nova versão do gestor",
    message: "Agora dá para duplicar pedidos com um clique.",
    date: new Date("2026-10-12T17:40:00Z"),
    isRead: true,
  },
];

/** Notifications held in state, with the actions the panel and the page call. */
function useNotifications(initial: NotificationData[]) {
  const [notifications, setNotifications] = React.useState(initial);
  return {
    notifications,
    markAsRead: (id: string) =>
      setNotifications((list) =>
        list.map((item) => (item.id === id ? { ...item, isRead: true } : item)),
      ),
    markAllAsRead: () =>
      setNotifications((list) => list.map((item) => ({ ...item, isRead: true }))),
    remove: (id: string) => setNotifications((list) => list.filter((item) => item.id !== id)),
  };
}

export function NotificationCenterDemo() {
  const { notifications, markAsRead, markAllAsRead, remove } =
    useNotifications(initialNotifications);
  return (
    <NotificationMenu
      notifications={notifications}
      onMarkAsRead={markAsRead}
      onMarkAllAsRead={markAllAsRead}
      onDelete={remove}
      onOpen={(notification) => markAsRead(notification.id)}
      viewAllHref="/notificacoes"
      i18n={ptBR}
    />
  );
}
```

### Order Summary

What the user is about to confirm before buying: lines, an applicable benefit, discounts, the total and the action.

`OrderSummary` takes the `title`, `totalLabel`, `total` and optional `totalDescription` (values formatted by the app) and the `action` button.

- **Large screens**: a card that sticks while the page scrolls — put it in the side column.
- **Smaller screens**: a bar fixed to the bottom with the total and the action; the total opens the lines in a bottom sheet. Leave room under the page, e.g. `pb-28 lg:pb-0`.

Its children sit in a `description-list`:

- **`OrderSummaryLine`**: `label`, `value` and a `description` under the label — an item, a fee, who the order is for. `tone="discount"` for a negative value.
- **`OrderSummaryOption`**: a benefit behind a `Switch`, such as the account balance, its amount struck through while off.

The total stands apart by size and weight, not only color.

Built-in text is in English; translate it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/order-summary`
- Registry item: https://ds.fmartinsandre.dev.br/r/order-summary.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/order-summary
- npm: cn@^0.5.0, lucide-react@^1.61.0
- Registry: @fma-ds/button, @fma-ds/card, @fma-ds/description-list, @fma-ds/separator, @fma-ds/sheet, @fma-ds/switch

```tsx
import { useState } from "react";
import { Button } from "@/components/fma-ds/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/fma-ds/card";
import {
  OrderSummary,
  type OrderSummaryI18n,
  OrderSummaryLine,
  OrderSummaryOption,
} from "@/components/fma-ds/order-summary/order-summary";
import { Spinner } from "@/components/fma-ds/spinner";

const PT_BR: OrderSummaryI18n = { labels: { details: "Ver detalhes" } };

const brl = (value: number) =>
  new Intl.NumberFormat("pt-BR", { style: "currency", currency: "BRL" }).format(value);

/** Stands in for the app's purchase request. */
const purchase = () => new Promise<void>((resolve) => setTimeout(resolve, 800));

const PLAN = 1990;

const ANNUAL_DISCOUNT = 398;

const CASHBACK = 32;

export function OrderSummaryDemo() {
  const [useCashback, setUseCashback] = useState(false);
  const [isPending, setIsPending] = useState(false);
  const total = PLAN - ANNUAL_DISCOUNT - (useCashback ? CASHBACK : 0);

  return (
    <div className="mx-auto grid max-w-5xl gap-6 p-6 pb-28 lg:grid-cols-[minmax(0,1fr)_22rem] lg:items-start lg:pb-6">
      <Card>
        <CardHeader>
          <CardTitle>Plano Pro</CardTitle>
          <CardDescription>
            Até 500 pedidos por mês, 5 usuários e análise de vendas.
          </CardDescription>
        </CardHeader>
        <CardContent className="text-muted-foreground">
          O pagamento anual vence todo dia 10 de outubro. Você pode cancelar a renovação a qualquer
          momento nas configurações da conta.
        </CardContent>
      </Card>
      <OrderSummary
        i18n={PT_BR}
        title="Resumo da compra"
        totalLabel="Total"
        total={brl(total)}
        totalDescription="cobrado anualmente"
        action={
          <Button
            size="lg"
            isPending={isPending}
            onPress={async () => {
              setIsPending(true);
              await purchase();
              setIsPending(false);
            }}
          >
            {isPending && <Spinner data-icon="inline-start" aria-hidden="true" />}
            Confirmar compra
          </Button>
        }
      >
        <OrderSummaryLine label="Plano Pro anual" value={brl(PLAN)} />
        <OrderSummaryLine
          label="Desconto do plano anual"
          description="20% sobre o mensal"
          value={`− ${brl(ANNUAL_DISCOUNT)}`}
          tone="discount"
        />
        <OrderSummaryOption
          label="Usar saldo de cashback"
          description={`Disponível: ${brl(CASHBACK)}`}
          value={`− ${brl(CASHBACK)}`}
          isSelected={useCashback}
          onChange={setUseCashback}
        />
      </OrderSummary>
    </div>
  );
}
```

### Page Header

The top of a page, composed from parts: breadcrumbs, the title with its description and actions, and an optional sub-page nav.

- **`PageHeaderBreadcrumbs`**: an `items` trail whose last entry is the current page.
- **`PageHeaderContent`**: heading on one side, actions on the other, stacked on narrow screens.
- **`PageHeaderHeading`**: `PageHeaderTitle` (the `<h1>`, with an `isLoading` skeleton) and `PageHeaderDescription`. Anything that belongs beside the title, like a status select, goes inside it too.
- **`PageHeaderActions`**: buttons that stretch on mobile.
- **`PageHeaderNav`**: an area's sub-pages, usually a `TabNav`.

Wrap the app in react-aria's `RouterProvider` so breadcrumb and tab links route client-side.

- Install: `pnpm dlx shadcn@latest add @fma-ds/page-header`
- Registry item: https://ds.fmartinsandre.dev.br/r/page-header.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/page-header
- npm: cn@^0.5.0
- Registry: @fma-ds/breadcrumb, @fma-ds/skeleton

```tsx
import { RefreshCwIcon, UserPlusIcon } from "lucide-react";
import { Button } from "@/components/fma-ds/button";
import {
  PageHeader,
  PageHeaderActions,
  PageHeaderContent,
  PageHeaderDescription,
  PageHeaderHeading,
  PageHeaderTitle,
} from "@/components/fma-ds/page-header/page-header";

export function PageHeaderDemo() {
  return (
    <PageHeader>
      <PageHeaderContent>
        <PageHeaderHeading>
          <PageHeaderTitle>Meus clientes</PageHeaderTitle>
          <PageHeaderDescription>
            Todos os clientes cadastrados na plataforma.
          </PageHeaderDescription>
        </PageHeaderHeading>
        <PageHeaderActions>
          <Button variant="outline" size="icon" aria-label="Atualizar lista">
            <RefreshCwIcon />
          </Button>
          <Button>
            <UserPlusIcon />
            Cadastrar cliente
          </Button>
        </PageHeaderActions>
      </PageHeaderContent>
    </PageHeader>
  );
}
```

### Panel Card

A panel on a `Card` — a dashboard chart or table, or one resource and its status (a contract, the current plan) — with a standard header and a body that handles its own states.

### `PanelCardHeader`

- **`title`**: a heading, `headingLevel` 2 by default.
- **`icon`**: shown in a `soft` `IconTile`.
- **`description`** and **`status`**: a `Badge` next to the title.
- **`help`**: opened by an ⓘ button in a popover, so it works with touch and keyboard.
- **`updatedAt`**: a `Date` or timestamp, formatted with `Intl` in the react-aria locale; `isRefreshing` shows a spinner next to it while the content stays on screen.
- **`toolbar`**: a slot for the card's own controls, which wraps below the title on narrow cards.

### `PanelCardBody`

Shows the first state that applies — `isLoading` (skeleton, first load only), `isError` (message plus "Try again" with `onRetry`), `isEmpty` (`Empty`) — or its children. `emptyState`/`errorState` replace the built-in messages (e.g. a missing resource with the action that adds it).

### What goes where

- **Body**: charts, tables, `stat-cards` and `description-list`; problems with the resource go in an `Alert` there, not in the card colors.
- **`CardFooter`**: actions.

`PanelCard`'s `i18n.labels` reaches every built-in text.

- Install: `pnpm dlx shadcn@latest add @fma-ds/panel-card`
- Registry item: https://ds.fmartinsandre.dev.br/r/panel-card.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/panel-card
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/card, @fma-ds/empty, @fma-ds/field, @fma-ds/icon-tile, @fma-ds/skeleton, @fma-ds/spinner

```tsx
import { FilesIcon } from "lucide-react";
import * as React from "react";
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
import {
  type ChartConfig,
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/fma-ds/chart";
import {
  PanelCard,
  PanelCardBody,
  PanelCardHeader,
  type PanelCardI18n,
} from "@/components/fma-ds/panel-card/panel-card";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/fma-ds/select";
import { Stat, StatLabel, StatValue } from "@/components/fma-ds/stat-cards/stat-cards";

const ptBR: PanelCardI18n = {
  labels: {
    help: "Mais informações",
    updatedAt: (formatted) => `Atualizado em ${formatted}`,
    refreshing: "Atualizando",
    loading: "Carregando",
    empty: "Nenhum dado",
    emptyDescription: "Ainda não há nada para mostrar neste período.",
    error: "Não foi possível carregar os dados",
    errorDescription: "Verifique sua conexão e tente novamente.",
    retry: "Tentar novamente",
  },
};

const UPDATED_AT = new Date(2026, 9, 20, 9, 45);

const ORDERS = [
  { month: "mai", products: 186, services: 80 },
  { month: "jun", products: 205, services: 112 },
  { month: "jul", products: 237, services: 120 },
  { month: "ago", products: 173, services: 190 },
  { month: "set", products: 209, services: 130 },
  { month: "out", products: 214, services: 140 },
];

const ordersConfig = {
  products: { label: "Produtos", color: "var(--chart-1)" },
  services: { label: "Serviços", color: "var(--chart-2)" },
} satisfies ChartConfig;

type OrderType = "todos" | "products" | "services";

export function PanelCardDemo() {
  const [type, setType] = React.useState<OrderType>("todos");
  const series = type === "todos" ? (["products", "services"] as const) : ([type] as const);
  const total = ORDERS.reduce(
    (sum, month) => sum + series.reduce((acc, key) => acc + month[key], 0),
    0,
  );
  return (
    <PanelCard i18n={ptBR} className="max-w-2xl">
      <PanelCardHeader
        icon={<FilesIcon />}
        title="Pedidos registrados"
        help="Quantidade mensal de pedidos registrados pelos seus clientes, por tipo."
        updatedAt={UPDATED_AT}
        toolbar={
          <Select
            aria-label="Tipo de pedido"
            selectedKey={type}
            onSelectionChange={(key) => setType(key as OrderType)}
          >
            <SelectTrigger size="sm" className="w-32">
              <SelectValue />
            </SelectTrigger>
            <SelectContent>
              <SelectItem id="todos">Todos</SelectItem>
              <SelectItem id="products">Produtos</SelectItem>
              <SelectItem id="services">Serviços</SelectItem>
            </SelectContent>
          </Select>
        }
      />
      <PanelCardBody className="gap-4">
        <Stat>
          <StatLabel>Total no semestre</StatLabel>
          <StatValue>{total.toLocaleString("pt-BR")}</StatValue>
        </Stat>
        <ChartContainer config={ordersConfig} className="aspect-auto h-56 w-full">
          <BarChart accessibilityLayer data={ORDERS}>
            <CartesianGrid vertical={false} />
            <XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
            <ChartTooltip content={<ChartTooltipContent />} />
            {series.map((key) => (
              <Bar key={key} dataKey={key} stackId="a" fill={`var(--color-${key})`} />
            ))}
          </BarChart>
        </ChartContainer>
      </PanelCardBody>
    </PanelCard>
  );
}
```

### Payment Card

The payment card screens: the saved card and the form to add one.

### Saved card

- **`PaymentCardDetails`**: draws the saved card (`credit-card`) beside a `description-list` (issuer, last digits, holder, expiry) from the gateway's data (`number` with hidden digits, `issuer`, `name`, `expiry`), with `actions` under it.
- **`PaymentCardRemove`**: the destructive button that asks through a `ConfirmDialog` and runs `onRemove` with the dialog pending, showing an error if it throws.

### Adding a card

`PaymentCardForm` is a react-aria `Form` that lays `PaymentCardPreview` beside `PaymentCardFields` (stacked when narrow). The fields are ready-made react-aria `TextField`s that feed the live preview with their value and focus (the code field turns the card):

- **`PaymentCardNumberField`**: masked by issuer.
- **`PaymentCardNameField`**: `part="first"`/`"last"` split it for gateways that take them apart.
- **`PaymentCardExpiryField`**: `MM/YY`.
- **`PaymentCardCodeField`**: digits, sized by the issuer.

Each takes `value`/`onChange` or `defaultValue`, `name`, `validate`, `isInvalid` and `errorMessage` (for react-hook-form's `Controller`), `label` and `description`. Validate with the `credit-card-validation` lib.

Built-in text is in English; translate it with `label`, `placeholder` and `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/payment-card`
- Registry item: https://ds.fmartinsandre.dev.br/r/payment-card.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/payment-card
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/confirm-dialog, @fma-ds/credit-card, @fma-ds/description-list, @fma-ds/input, @fma-ds/label, @fma-ds/masked-input, @fma-ds/use-dialog-promise, @fma-ds/credit-card-validation

```tsx
import { CreditCardIcon } from "lucide-react";
import { useState } from "react";
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/components/fma-ds/empty";
import {
  PaymentCardDetails,
  PaymentCardRemove,
} from "@/components/fma-ds/payment-card/payment-card";

/** Stands in for the app's request to the payment gateway. */
const request = () => new Promise<void>((resolve) => setTimeout(resolve, 600));

const CARD_LABELS = {
  validThru: "válido até",
  namePlaceholder: "NOME DO TITULAR",
  card: ({ issuer, lastDigits }: { issuer?: string; lastDigits?: string }) =>
    `Cartão ${issuer ?? ""}${lastDigits ? ` final ${lastDigits}` : ""}`.replace(/\s+/g, " ").trim(),
};

export function PaymentCardSavedCard() {
  const [isRemoved, setIsRemoved] = useState(false);

  if (isRemoved) {
    return (
      <Empty>
        <EmptyHeader>
          <EmptyMedia variant="icon">
            <CreditCardIcon />
          </EmptyMedia>
          <EmptyTitle>Nenhum cartão cadastrado</EmptyTitle>
          <EmptyDescription>Cadastre um cartão para pagar suas faturas.</EmptyDescription>
        </EmptyHeader>
      </Empty>
    );
  }

  return (
    <PaymentCardDetails
      number="XXXX-XXXX-XXXX-4242"
      issuer="visa"
      name="Maria Silva"
      expiry="12/2028"
      i18n={{
        labels: { issuer: "Bandeira", number: "Número", holder: "Titular", expiry: "Validade" },
        card: CARD_LABELS,
      }}
      actions={
        <PaymentCardRemove
          onRemove={async () => {
            await request();
            setIsRemoved(true);
          }}
          i18n={{
            labels: {
              remove: "Remover cartão",
              confirmTitle: "Remover este cartão?",
              confirmDescription: "Para pagar com cartão, você precisará cadastrar outro.",
              confirm: "Remover cartão",
              cancel: "Cancelar",
              pending: "Removendo…",
              error: "Não foi possível remover o cartão. Tente novamente.",
            },
          }}
        />
      }
    />
  );
}
```

### Plan Builder

Build what the user is about to buy by choosing quantities, with the price in real time: a custom plan with several resources, or a quantity of one item (extra notes, credits).

- **`PlanBuilder`**: lays out the resources and its `summary` (an `OrderSummary`: a sticky card on large screens, a bar fixed to the bottom on smaller ones). `isCalculating` turns every `PlanPrice` (a price formatted by the app) into a skeleton while the app recalculates.
- **`PlanResource`**: a card with `icon`, `title`, `description` and a controlled `Slider` named by `label` (`value`/`onChange`, `minValue`/`maxValue`/`step`, `marks`, `formatValue`, `limit` for stock or quota left, `isDisabled`). A `hint` under the slider says why it stops or is disabled, and an optional `included` accordion lists what comes with it.
- **`PlanResourceAddon`**: an add-on as a child of the resource — a switch with label and description.

The price, debouncing, limits and notices stay in the app.

Built-in text is in English; translate it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/plan-builder`
- Registry item: https://ds.fmartinsandre.dev.br/r/plan-builder.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/plan-builder
- npm: cn@^0.5.0
- Registry: @fma-ds/accordion, @fma-ds/card, @fma-ds/icon-tile, @fma-ds/skeleton, @fma-ds/slider, @fma-ds/switch

```tsx
import { FileSearchIcon, FileTextIcon, ReceiptTextIcon, UsersIcon } from "lucide-react";
import * as React from "react";
import { Alert, AlertDescription, AlertTitle } from "@/components/fma-ds/alert";
import { Button } from "@/components/fma-ds/button";
import { ConfirmDialog } from "@/components/fma-ds/confirm-dialog";
import {
  DescriptionDetails,
  DescriptionItem,
  DescriptionList,
  DescriptionTerm,
} from "@/components/fma-ds/description-list";
import { OrderSummary, OrderSummaryLine } from "@/components/fma-ds/order-summary/order-summary";
import {
  PlanBuilder,
  type PlanBuilderI18n,
  PlanPrice,
  PlanResource,
  PlanResourceAddon,
} from "@/components/fma-ds/plan-builder/plan-builder";
import { useDialogPromise } from "@/hooks/fma-ds/use-dialog-promise";

const PT_BR: PlanBuilderI18n = { labels: { included: "O que está incluso" } };

const brl = (value: number) =>
  new Intl.NumberFormat("pt-BR", { style: "currency", currency: "BRL" }).format(value);

/** Six evenly spaced marks from `min` to `max`. */
const marksFor = (min: number, max: number) =>
  Array.from({ length: 6 }, (_, index) => min + ((max - min) / 5) * index);

/** Stands in for the app's purchase request. */
const purchase = () => new Promise<void>((resolve) => setTimeout(resolve, 600));

type CustomPlan = {
  orders: number;
  inbox: number;
  dataValidator: boolean;
  monthlyCustomers: number;
  registry: number;
};

const PRICES = {
  orders: 0.4,
  inbox: 0.05,
  dataValidator: 0.02,
  monthlyCustomers: 2,
  registry: 1.5,
};

const linePrices = (plan: CustomPlan) => ({
  orders: plan.orders * PRICES.orders,
  inbox: plan.inbox * PRICES.inbox,
  dataValidator: plan.dataValidator ? plan.inbox * PRICES.dataValidator : 0,
  monthlyCustomers: plan.monthlyCustomers * PRICES.monthlyCustomers,
  registry: plan.registry * PRICES.registry,
});

const monthly = (plan: CustomPlan) =>
  Object.values(linePrices(plan)).reduce((total, value) => total + value, 0);

/** Stands in for the app's price request: settles a moment after the last change. */
function useMonthlyPrice(plan: CustomPlan) {
  const [price, setPrice] = React.useState(() => monthly(plan));
  const [isCalculating, setIsCalculating] = React.useState(false);
  React.useEffect(() => {
    setIsCalculating(true);
    const timer = setTimeout(() => {
      setPrice(monthly(plan));
      setIsCalculating(false);
    }, 400);
    return () => clearTimeout(timer);
  }, [plan]);
  return { price, isCalculating };
}

export function PlanBuilderCustomPlan() {
  const [plan, setPlan] = React.useState<CustomPlan>({
    orders: 120,
    inbox: 400,
    dataValidator: false,
    monthlyCustomers: 10,
    registry: 0,
  });
  const [isSubscribed, setIsSubscribed] = React.useState(false);
  const { price, isCalculating } = useMonthlyPrice(plan);
  const lines = linePrices(plan);
  const confirmation = useDialogPromise();
  const set = (patch: Partial<CustomPlan>) => setPlan((current) => ({ ...current, ...patch }));

  async function subscribe() {
    const result = await confirmation.open();
    if (result.status === "confirmed") setIsSubscribed(true);
  }

  return (
    <div className="mx-auto max-w-6xl p-6">
      <PlanBuilder
        i18n={PT_BR}
        isCalculating={isCalculating}
        summary={
          <OrderSummary
            i18n={{ labels: { details: "Ver detalhes" } }}
            title="Resumo do plano"
            totalLabel="Mensal"
            total={<PlanPrice>{brl(price)}</PlanPrice>}
            totalDescription={<PlanPrice>{brl(price * 12)} por ano</PlanPrice>}
            action={
              <Button size="lg" isDisabled={isCalculating || isSubscribed} onPress={subscribe}>
                {isSubscribed ? "Plano assinado" : "Assinar plano"}
              </Button>
            }
          >
            <OrderSummaryLine
              label="Pedidos"
              description={`${plan.orders} por mês`}
              value={<PlanPrice>{brl(lines.orders)}</PlanPrice>}
            />
            <OrderSummaryLine
              label="Análise de vendas"
              description={`${plan.inbox} por mês`}
              value={<PlanPrice>{brl(lines.inbox)}</PlanPrice>}
            />
            {plan.dataValidator && (
              <OrderSummaryLine
                label="Validador de dados"
                value={<PlanPrice>{brl(lines.dataValidator)}</PlanPrice>}
              />
            )}
            <OrderSummaryLine
              label="Clientes mensais"
              description={`${plan.monthlyCustomers} clientes`}
              value={<PlanPrice>{brl(lines.monthlyCustomers)}</PlanPrice>}
            />
            <OrderSummaryLine
              label="Cadastro Certo"
              description={`${plan.registry} clientes`}
              value={<PlanPrice>{brl(lines.registry)}</PlanPrice>}
            />
          </OrderSummary>
        }
      >
        <Alert variant="success">
          <AlertTitle>Primeira fatura com desconto</AlertTitle>
          <AlertDescription>
            Os dias que restam do plano atual são abatidos da primeira fatura.
          </AlertDescription>
        </Alert>
        <PlanResource
          icon={<FileTextIcon />}
          title="Pedidos"
          description="Registro de pedidos de produtos e serviços para os seus clientes."
          label="Pedidos por mês"
          formatValue={(value) => `${value} pedidos`}
          minValue={0}
          maxValue={300}
          step={10}
          marks={marksFor(0, 300)}
          value={plan.orders}
          onChange={(orders) => set({ orders })}
          included={
            <ul className="list-disc space-y-1 pl-4">
              <li>Cancelamentos e correções ilimitados</li>
              <li>Envio automático do recibo ao cliente</li>
            </ul>
          }
        />
        <PlanResource
          icon={<FileSearchIcon />}
          title="Análise de vendas"
          description="Captura automática dos pedidos feitos pelos seus clientes."
          label="Pedidos por mês"
          formatValue={(value) => `${value} pedidos`}
          minValue={0}
          maxValue={1000}
          step={50}
          marks={marksFor(0, 1000)}
          value={plan.inbox}
          onChange={(inbox) => set({ inbox, dataValidator: inbox > 0 && plan.dataValidator })}
          included={<p>Download de relatórios, confirmação do cliente e alertas de divergência.</p>}
        >
          {plan.inbox > 0 && (
            <PlanResourceAddon
              label="Validador de dados"
              description={`Validação automática dos dados até o limite de ${plan.inbox} pedidos.`}
              isSelected={plan.dataValidator}
              onChange={(dataValidator) => set({ dataValidator })}
            />
          )}
        </PlanResource>
        <PlanResource
          icon={<ReceiptTextIcon />}
          title="Clientes mensais"
          description="Mensalidades geradas e enviadas todo mês."
          label="Clientes"
          formatValue={(value) => `${value} clientes`}
          minValue={0}
          maxValue={100}
          step={5}
          marks={marksFor(0, 100)}
          value={plan.monthlyCustomers}
          onChange={(monthlyCustomers) => set({ monthlyCustomers })}
        />
        <PlanResource
          icon={<UsersIcon />}
          title="Cadastro Certo"
          description="Consulta e atualização cadastral dos clientes."
          label="Clientes"
          formatValue={(value) => `${value} clientes`}
          minValue={0}
          maxValue={50}
          step={5}
          marks={marksFor(0, 50)}
          value={plan.registry}
          onChange={(registry) => set({ registry })}
        />
      </PlanBuilder>
      <ConfirmDialog
        controller={confirmation}
        title="Confirmar assinatura"
        description={`Você passa a pagar ${brl(price)} por mês, a partir da próxima fatura.`}
        confirmLabel="Assinar"
        cancelLabel="Voltar"
        pendingLabel="Assinando…"
        onConfirm={purchase}
      >
        <DescriptionList>
          <DescriptionItem>
            <DescriptionTerm>Pedidos</DescriptionTerm>
            <DescriptionDetails>{plan.orders} por mês</DescriptionDetails>
          </DescriptionItem>
          <DescriptionItem>
            <DescriptionTerm>Análise de vendas</DescriptionTerm>
            <DescriptionDetails>
              {plan.inbox} por mês{plan.dataValidator && " + validador"}
            </DescriptionDetails>
          </DescriptionItem>
          <DescriptionItem>
            <DescriptionTerm>Clientes mensais</DescriptionTerm>
            <DescriptionDetails>{plan.monthlyCustomers}</DescriptionDetails>
          </DescriptionItem>
          <DescriptionItem>
            <DescriptionTerm>Cadastro Certo</DescriptionTerm>
            <DescriptionDetails>{plan.registry}</DescriptionDetails>
          </DescriptionItem>
        </DescriptionList>
      </ConfirmDialog>
    </div>
  );
}
```

### Pricing Plans

Choose one of a few fixed plans, then confirm. For a plan built from quantities and add-ons, use `plan-builder`.

- **`PricingPlans`**: lays out the options and an optional `summary` (an `OrderSummary` with the chosen plan and a "Continue" action: a sticky card on large screens, a bar fixed to the bottom on smaller ones).
- **`PricingPeriod`**: the billing period as a segmented toggle that always has one selected (`value`/`onChange`; `PricingPeriodOption` with an `id`, and a `Badge` inside for the saving).
- **`PricingPlanGroup`**: a radio group of `PricingPlan` cards, stacked in one list on small screens and side by side in equal columns once its own width fits them.
- **`PricingPlan`**: `name`, `badge` ("Most popular"), `description`, `price` and `period` formatted by the app, `priceNote` (the equivalent, "R$ 718,80 per year") and `isFeatured` for a brand glow and a `brand` badge (the border is left to the selected plan). The radio is named by the plan and described by its price.
- **`PricingPlanFeature`**: what the plan has; `isIncluded={false}` shows a dash, muted text and "Not included" read before it.

Built-in text is in English; translate it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/pricing-plans`
- Registry item: https://ds.fmartinsandre.dev.br/r/pricing-plans.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/pricing-plans
- npm: cn@^0.5.0, lucide-react@^1.61.0, react-aria-components@^1.22.1
- Registry: @fma-ds/badge, @fma-ds/radio-group, @fma-ds/toggle-group, @fma-ds/brand

```tsx
import { useState } from "react";
import { Badge } from "@/components/fma-ds/badge";
import { Button } from "@/components/fma-ds/button";
import { OrderSummary, OrderSummaryLine } from "@/components/fma-ds/order-summary";
import {
  PricingPeriod,
  PricingPeriodOption,
  PricingPlan,
  PricingPlanFeature,
  PricingPlanGroup,
  PricingPlans,
  type PricingPlansI18n,
} from "@/components/fma-ds/pricing-plans/pricing-plans";

const PT_BR: PricingPlansI18n = { labels: { included: "Incluído", notIncluded: "Não incluído" } };

const brl = (value: number) =>
  new Intl.NumberFormat("pt-BR", { style: "currency", currency: "BRL" }).format(value);

const PLANS = [
  {
    id: "basic",
    name: "Básico",
    description: "Para quem está começando a registrar.",
    monthly: 69.9,
    annual: 59.9,
    features: [
      { label: "Até 100 pedidos por mês", isIncluded: true },
      { label: "1 usuário", isIncluded: true },
      { label: "Análise de vendas", isIncluded: false },
      { label: "Suporte por telefone", isIncluded: false },
    ],
  },
  {
    id: "pro",
    name: "Pro",
    description: "Para a empresa que vende todo dia.",
    monthly: 129.9,
    annual: 109.9,
    isFeatured: true,
    features: [
      { label: "Até 500 pedidos por mês", isIncluded: true },
      { label: "5 usuários", isIncluded: true },
      { label: "Análise de vendas", isIncluded: true },
      { label: "Suporte por telefone", isIncluded: false },
    ],
  },
  {
    id: "premium",
    name: "Premium",
    description: "Para empresas com vários clientes.",
    monthly: 249.9,
    annual: 209.9,
    features: [
      { label: "Pedidos ilimitados", isIncluded: true },
      { label: "Usuários ilimitados", isIncluded: true },
      { label: "Análise de vendas", isIncluded: true },
      { label: "Suporte por telefone", isIncluded: true },
    ],
  },
];

export function PricingPlansDemo() {
  const [period, setPeriod] = useState("annual");
  const [planId, setPlanId] = useState("pro");
  const plan = PLANS.find((item) => item.id === planId) ?? PLANS[1];
  const isAnnual = period === "annual";

  return (
    <div className="mx-auto max-w-6xl p-6">
      <PricingPlans
        i18n={PT_BR}
        summary={
          plan && (
            <OrderSummary
              title="Resumo"
              totalLabel="Total"
              total={brl(isAnnual ? plan.annual * 12 : plan.monthly)}
              totalDescription={isAnnual ? "cobrado uma vez por ano" : "cobrado todo mês"}
              action={<Button size="lg">Continuar</Button>}
            >
              <OrderSummaryLine
                label={`Plano ${plan.name}`}
                description={isAnnual ? "Anual" : "Mensal"}
                value={`${brl(isAnnual ? plan.annual : plan.monthly)}/mês`}
              />
            </OrderSummary>
          )
        }
      >
        <PricingPeriod aria-label="Período de pagamento" value={period} onChange={setPeriod}>
          <PricingPeriodOption id="monthly">Mensal</PricingPeriodOption>
          <PricingPeriodOption id="annual">
            Anual
            <Badge variant="success-light">2 meses grátis</Badge>
          </PricingPeriodOption>
        </PricingPeriod>
        <PricingPlanGroup aria-label="Plano" value={planId} onChange={setPlanId}>
          {PLANS.map((item) => (
            <PricingPlan
              key={item.id}
              value={item.id}
              name={item.name}
              description={item.description}
              badge={item.isFeatured ? "Mais popular" : undefined}
              isFeatured={item.isFeatured}
              price={brl(isAnnual ? item.annual : item.monthly)}
              period="/mês"
              priceNote={isAnnual ? `${brl(item.annual * 12)} por ano` : "Sem fidelidade"}
            >
              {item.features.map((feature) => (
                <PricingPlanFeature key={feature.label} isIncluded={feature.isIncluded}>
                  {feature.label}
                </PricingPlanFeature>
              ))}
            </PricingPlan>
          ))}
        </PricingPlanGroup>
      </PricingPlans>
    </div>
  );
}
```

### Settings Form

A long edit form in sections, saved as a whole (account, company, preferences).

- **`SettingsForm`**: a react-aria `Form` that only shows state the app owns, so react-hook-form or any other form state fits: `isDirty` (enables Save and Discard), `isPending` (spinner on Save, `aria-busy`) and `onReset` (adds a Discard button that should restore the saved values).
- **`SettingsSection`**: groups fields under a `title` and `description` (a labelled group) stacked above them, leaving the width to the fields next to an app sidebar. The fields fall into a two-column grid when there's room (container query); `col-span-full` takes the whole row.
- **`SettingsFormFooter`**: a save bar stuck to the bottom of the viewport with a polite status line (no changes / unsaved / saving), optional children before the buttons, Discard and Save.

Warning before leaving with unsaved changes stays in the app, since it depends on the router; use `confirm-dialog`.

Built-in text is in English; translate it with `i18n.labels`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/settings-form`
- Registry item: https://ds.fmartinsandre.dev.br/r/settings-form.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/settings-form
- npm: cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/button, @fma-ds/spinner

```tsx
import { useState } from "react";
import { TextField } from "react-aria-components";
import { Field, FieldContent, FieldDescription } from "@/components/fma-ds/field";
import { Input } from "@/components/fma-ds/input";
import { Label } from "@/components/fma-ds/label";
import { MaskedInput } from "@/components/fma-ds/masked-input";
import {
  SettingsForm,
  SettingsFormFooter,
  type SettingsFormI18n,
  SettingsSection,
} from "@/components/fma-ds/settings-form/settings-form";
import { Switch } from "@/components/fma-ds/switch";

const PT_BR: SettingsFormI18n = {
  labels: {
    save: "Salvar alterações",
    discard: "Descartar",
    saving: "Salvando…",
    unsaved: "Há alterações não salvas",
    saved: "Nenhuma alteração",
  },
};

type Company = {
  legalName: string;
  tradeName: string;
  cnpj: string;
  email: string;
  phone: string;
  emailAlerts: boolean;
  dueDateReminders: boolean;
};

const SAVED_COMPANY: Company = {
  legalName: "Silva & Souza Arquitetura Ltda.",
  tradeName: "Silva Estúdio",
  cnpj: "12345678000195",
  email: "contato@silvaestudio.com.br",
  phone: "11987654321",
  emailAlerts: true,
  dueDateReminders: false,
};

/** Stands in for the app's save request. */
const saveCompany = (company: Company) =>
  new Promise<Company>((resolve) => setTimeout(() => resolve(company), 800));

export function SettingsFormDemo() {
  const [saved, setSaved] = useState(SAVED_COMPANY);
  const [values, setValues] = useState(SAVED_COMPANY);
  const [isPending, setIsPending] = useState(false);
  const isDirty = JSON.stringify(values) !== JSON.stringify(saved);
  const set = (patch: Partial<Company>) => setValues((current) => ({ ...current, ...patch }));

  return (
    <SettingsForm
      i18n={PT_BR}
      isDirty={isDirty}
      isPending={isPending}
      onReset={() => setValues(saved)}
      onSubmit={async (event) => {
        event.preventDefault();
        setIsPending(true);
        setSaved(await saveCompany(values));
        setIsPending(false);
      }}
      className="max-w-4xl"
    >
      <SettingsSection
        title="Dados da empresa"
        description="Aparecem nos pedidos registrados e nos documentos enviados aos clientes."
      >
        <TextField
          value={values.legalName}
          onChange={(legalName) => set({ legalName })}
          isRequired
          className="col-span-full flex flex-col gap-2"
        >
          <Label>Razão social</Label>
          <Input />
        </TextField>
        <TextField
          value={values.tradeName}
          onChange={(tradeName) => set({ tradeName })}
          className="flex flex-col gap-2"
        >
          <Label>Nome fantasia</Label>
          <Input />
        </TextField>
        <TextField isReadOnly className="flex flex-col gap-2">
          <Label>CNPJ</Label>
          <MaskedInput mask="cnpj" value={values.cnpj} readOnly />
        </TextField>
      </SettingsSection>
      <SettingsSection title="Contato" description="Para onde enviamos avisos e faturas.">
        <TextField
          type="email"
          value={values.email}
          onChange={(email) => set({ email })}
          className="flex flex-col gap-2"
        >
          <Label>E-mail</Label>
          <Input />
        </TextField>
        <TextField className="flex flex-col gap-2">
          <Label>Telefone</Label>
          <MaskedInput
            mask="phone"
            value={values.phone}
            onValueChange={(phone) => set({ phone })}
          />
        </TextField>
      </SettingsSection>
      <SettingsSection title="Notificações">
        <Field orientation="horizontal" className="col-span-full">
          <FieldContent>
            <Label htmlFor="email-alerts">Alertas por e-mail</Label>
            <FieldDescription>Pedidos recusados e contratos perto de vencer.</FieldDescription>
          </FieldContent>
          <Switch
            id="email-alerts"
            isSelected={values.emailAlerts}
            onChange={(emailAlerts) => set({ emailAlerts })}
          />
        </Field>
        <Field orientation="horizontal" className="col-span-full">
          <FieldContent>
            <Label htmlFor="due-date-reminders">Lembretes de vencimento</Label>
            <FieldDescription>Relatórios e faturas, três dias antes.</FieldDescription>
          </FieldContent>
          <Switch
            id="due-date-reminders"
            isSelected={values.dueDateReminders}
            onChange={(dueDateReminders) => set({ dueDateReminders })}
          />
        </Field>
      </SettingsSection>
      <SettingsFormFooter />
    </SettingsForm>
  );
}
```

### Stat Cards

Totals above a list or on a dashboard: figures on their own or on cards that are static, pressable, links or filters.

### `Stat`

A label (`StatLabel`), a value (`StatValue`, formatted by the app, with `isLoading` and `isUnavailable` states), an optional `StatIcon` (a `soft` `IconTile`) and a `StatDescription`.

- **`tone`**: `default`, `success`, `warning`, `info`, `destructive` or `muted`; tints the icon and the value.
- **`size="lg"`**: enlarges the value.

On its own, `Stat` has no surface, for several figures inside one card.

### Cards

- **`StatCard`**: static.
- **`StatCardButton`**: runs `onPress`, or opens a dialog as the child of a `DialogTrigger`.
- **`StatCardLink`**: navigates, e.g. to the list already filtered.
- **`StatCardToggle`**: the selectable cards of a `StatCardGroup`, a react-aria `ToggleButtonGroup` that filters a list. `selectionMode="single"` behaves like radios and `"multiple"` like checkboxes, controlled by `selectedKeys`/`onSelectionChange` so it maps to a search param.

`StatGrid` and `StatCardGroup` lay cards out in as many columns as fit, and their `i18n.labels` reach every value inside.

- Install: `pnpm dlx shadcn@latest add @fma-ds/stat-cards`
- Registry item: https://ds.fmartinsandre.dev.br/r/stat-cards.json
- Docs: https://ds.fmartinsandre.dev.br/blocks/stat-cards
- npm: class-variance-authority@^0.7.1, cn@^0.5.0, react-aria-components@^1.22.1
- Registry: @fma-ds/icon-tile, @fma-ds/skeleton

```tsx
import { CircleCheckIcon, CircleXIcon, FileTextIcon } from "lucide-react";
import {
  StatCard,
  StatGrid,
  type StatI18n,
  StatIcon,
  StatLabel,
  StatValue,
} from "@/components/fma-ds/stat-cards/stat-cards";

const ptBR: StatI18n = { labels: { loading: "Carregando", unavailable: "Indisponível" } };

export function StatCardsDemo() {
  return (
    <StatGrid i18n={ptBR} className="max-w-4xl">
      <StatCard>
        <StatLabel>Total de pedidos</StatLabel>
        <StatValue>1.284</StatValue>
        <StatIcon>
          <FileTextIcon />
        </StatIcon>
      </StatCard>
      <StatCard tone="success">
        <StatLabel>Pedidos validados</StatLabel>
        <StatValue>1.197</StatValue>
        <StatIcon>
          <CircleCheckIcon />
        </StatIcon>
      </StatCard>
      <StatCard tone="destructive">
        <StatLabel>Pedidos cancelados</StatLabel>
        <StatValue>87</StatValue>
        <StatIcon>
          <CircleXIcon />
        </StatIcon>
      </StatCard>
    </StatGrid>
  );
}
```

## Libs

### Brand

Class strings for the theme's second identity color (`brand`) on surfaces and decoration. Identity only: never for hover, focus, selection or status.

- **`brandSurface`**: a solid brand surface whose focus ring follows the text.
- **`brandGradient`**: a primary → brand gradient fill.
- **`brandGradientBorder`**: a primary → brand gradient border; set the surface underneath with `--brand-border-fill`.
- **`brandGlow`**: a soft brand glow (replaces the element's shadow).
- **`brandSpinningBorder`**: a wrapper with a spinning gradient edge for something in progress, static with reduced motion.

- Install: `pnpm dlx shadcn@latest add @fma-ds/brand`
- Registry item: https://ds.fmartinsandre.dev.br/r/brand.json

### Code Block Highlight

The code block's shiki engine and pure helpers, with no `"use client"`, so a server loader can call it.

- **`highlightCode(code, options)`**: returns plain-JSON `CodeBlockLine[]` — dual light/dark token colors, line state from props or shiki transformers, and unchanged lines reused so streaming re-renders one row.
- **Loading**: shiki loads lazily on the JavaScript regex engine (no WebAssembly), one chunk per language from the static `codeBlockLanguages` map and per theme from `codeBlockThemes` (`github-light`/`github-dark`, or `css-variables` for design-token colors).
- **Helpers**: `parseLineSpec` (`"2-4,7"`), `markdownFences`/`markdownCodeProps` for AI transcripts, `ansiToLines` for terminal output, `parseUnifiedDiff` for git patches and `stripNotationComments`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/code-block-highlight`
- Registry item: https://ds.fmartinsandre.dev.br/r/code-block-highlight.json
- npm: shiki@^4.5.0

### Color Contrast

WCAG 2 contrast helpers over OKLCH. Results are oklch strings clamped to sRGB.

- **Ratio**: contrast ratio and level.
- **`passingRanges`**: the ranges of any OKLCH, HSL, HSB or RGB channel where a color passes against a background.
- **`passingRegion`**: the passing part of a 2D color area, such as chroma × lightness.
- **`nearestContrastColor`**: the nearest passing color that keeps its hue.

- Install: `pnpm dlx shadcn@latest add @fma-ds/color-contrast`
- Registry item: https://ds.fmartinsandre.dev.br/r/color-contrast.json
- npm: culori@^4.0.2

### Credit Card Validation

Payment card helpers for forms, without React.

- **`getCreditCardIssuer(number)`**: detects the issuer from the first digits with `credit-card-type` (`null` while ambiguous).
- **`getCreditCardIssuerById`**: reads it from saved card data (`visa`, `Mastercard`, `amex`). Both return the name, valid lengths, digit groups and security-code size.
- **`isValidCreditCardNumber`**: checks the length for the issuer and the Luhn digit.
- **`isValidCreditCardExpiry`**: a real month not yet ended (`MM/YY`, `MM/YYYY` or digits only).
- **`isValidCreditCardCode`**: the code size for the issuer.
- **`getCreditCardNumberLayout`**: the digit groups for what's typed (Amex 4-6-5), used by the `credit-card` mask and component.

- Install: `pnpm dlx shadcn@latest add @fma-ds/credit-card-validation`
- Registry item: https://ds.fmartinsandre.dev.br/r/credit-card-validation.json
- npm: credit-card-type@^10.3.1

### Date Availability

Finds the nearest date that isn't blocked by min/max or unavailable ranges, and centralizes the travel-or-clear correction policy.

A blocked value moves to a valid neighbour instead of being discarded, and is cleared only when no available date exists.

- Install: `pnpm dlx shadcn@latest add @fma-ds/date-availability`
- Registry item: https://ds.fmartinsandre.dev.br/r/date-availability.json
- npm: @internationalized/date@^3.12.4
- Registry: @fma-ds/interval-helpers

### Date Fns Compat

A date-fns-shaped API (`addDays`, `format`, `isBefore`, `TZDate`, …) backed by `@internationalized/date`.

- **Same shape**: same names and argument order as date-fns/`@date-fns/tz`, taking and returning plain `Date` (or `TZDate`).
- **Arithmetic**: DST-safe calendar arithmetic.
- **Migration**: also exports `toZoned`/`fromZoned`, for moving call sites onto `ZonedDateTime` directly.

- Install: `pnpm dlx shadcn@latest add @fma-ds/date-fns-compat`
- Registry item: https://ds.fmartinsandre.dev.br/r/date-fns-compat.json
- npm: @internationalized/date@^3.12.4

### Date Granularity

Period helpers for month/year date selection: period start/end, same-period comparison, period-widened min/max bounds, and lifting a day-level isDateUnavailable predicate to whole months or years.

- Install: `pnpm dlx shadcn@latest add @fma-ds/date-granularity`
- Registry item: https://ds.fmartinsandre.dev.br/r/date-granularity.json
- npm: @internationalized/date@^3.12.4

### Input Masks

An input-mask system built on Maskito: mask option hooks, formatters and remover utilities for Brazilian documents and common formats.

- **Documents**: CPF, CNPJ, CPF-or-CNPJ, CEP.
- **Contact and payment**: phone; credit card, grouped by issuer (Amex 4-6-5, up to 19 digits).
- **Dates and numbers**: date, date range, date-time, time, decimal.

- Install: `pnpm dlx shadcn@latest add @fma-ds/input-masks`
- Registry item: https://ds.fmartinsandre.dev.br/r/input-masks.json
- npm: @maskito/core@^5.6.0, @maskito/kit@^5.6.0
- Registry: @fma-ds/credit-card-validation, @fma-ds/type-helper, @fma-ds/types

### Interval Helpers

Helpers for inclusive `Interval<T>` spans (e.g. unavailable date ranges), generic over any `T` with a `.compare()` method, such as `@internationalized/date`'s `DateValue`.

`createIsWithinAnyInterval` plugs straight into react-aria's `isDateUnavailable` prop.

- Install: `pnpm dlx shadcn@latest add @fma-ds/interval-helpers`
- Registry item: https://ds.fmartinsandre.dev.br/r/interval-helpers.json
- Registry: @fma-ds/types

### Type Helper

Runtime type-checking helpers (typeHelper.isString/isNumber/isArray/...) built on Object.prototype.toString, usable as TypeScript type guards.

- Install: `pnpm dlx shadcn@latest add @fma-ds/type-helper`
- Registry item: https://ds.fmartinsandre.dev.br/r/type-helper.json

### Types

Shared type utilities: Brand<T, B> for nominal typing of structurally-identical types, and Interval<T> for inclusive from/to spans.

- Install: `pnpm dlx shadcn@latest add @fma-ds/types`
- Registry item: https://ds.fmartinsandre.dev.br/r/types.json

## Hooks

### Use Available Date Correction

useAvailableDateCorrection: revalidates an already-committed date value against min/max/unavailable ranges whenever the value or constraints change, correcting it through the date-availability travel-or-clear policy.

- Install: `pnpm dlx shadcn@latest add @fma-ds/use-available-date-correction`
- Registry item: https://ds.fmartinsandre.dev.br/r/use-available-date-correction.json
- npm: @internationalized/date@^3.12.4
- Registry: @fma-ds/date-availability, @fma-ds/types

### Use Dialog Promise

`useDialogPromise<D, V>()`: state and promise for a dialog you render yourself.

- **`open(data)`**: opens it and returns a promise of a `DialogResult<V>` that never rejects — `{ status: "confirmed", value }`, `{ status: "cancelled" }` or `{ status: "dismissed" }` (Escape, outside click, a new open or unmount).
- **`dialogProps`**: spread `isOpen`/`onOpenChange` on any overlay (`AlertDialog`, `Dialog`, `Sheet`), and call `confirm(value)` or `cancel()` from it.
- **Async confirm**: `confirm(async () => value)` keeps the dialog open with `isPending` until it resolves, and open with `error` if it throws.
- **`data`**: holds what `open` passed (kept after closing for exit animations), so the dialog can be its own component that receives the controller.

- Install: `pnpm dlx shadcn@latest add @fma-ds/use-dialog-promise`
- Registry item: https://ds.fmartinsandre.dev.br/r/use-dialog-promise.json

### Use File Upload

`useFileUpload`: headless state for picking files, without uploading them.

- **`addFiles`**: validates each file against `accept` (extensions and MIME types, as in `<input accept>`), `maxSize` and, with `multiple`, `maxFiles` (a batch that goes over is rejected whole), and skips duplicates. Without `multiple`, a new file replaces the current one.
- **State**: uncontrolled (`defaultValue`) or controlled (`value`/`onChange`); takes `isDisabled`.
- **Returns**: `files` (`{ id, file }`, where `file` is a `File` or metadata of one already stored) plus `errors` as `{ code, message, file }`, with `messages` to translate them.
- **Helpers**: also exports `formatBytes` and `matchesAccept`.

Progress and retries stay with the caller, keyed by file id.

Based on reui's hook, with its batch, stale-state and StrictMode bugs fixed and its DOM drag handlers left to react-aria's `DropZone` (see `file-upload`).

- Install: `pnpm dlx shadcn@latest add @fma-ds/use-file-upload`
- Registry item: https://ds.fmartinsandre.dev.br/r/use-file-upload.json

### Use Mask

`useMask`: applies an `input-masks` preset (`"cpf"`, `"phone"`, `{ type: "decimal", prefix: "R$ " }`…) or custom Maskito options to any input.

- **`inputProps`**: spread onto `Input`, `InputGroupInput` or a native input; it carries the masked value, Maskito's ref, and per-preset `inputMode`, `autoComplete` and placeholder.
- **Value**: reports the raw value through `onValueChange`, and accepts a raw or masked controlled value.
- **`TextField`**: reads the value of an enclosing react-aria `TextField`.

- Install: `pnpm dlx shadcn@latest add @fma-ds/use-mask`
- Registry item: https://ds.fmartinsandre.dev.br/r/use-mask.json
- npm: @maskito/react@^5.6.0, react-aria-components@^1.22.1
- Registry: @fma-ds/input-masks

### Use Mobile

useIsMobile: reports whether the viewport is below the 768px mobile breakpoint, updating on resize. Used by sidebar.

- Install: `pnpm dlx shadcn@latest add @fma-ds/use-mobile`
- Registry item: https://ds.fmartinsandre.dev.br/r/use-mobile.json

## Themes

### Amber Minimal

Amber accents on white and near-black, Inter and tight 0.375rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-amber-minimal`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-amber-minimal.json
- npm: @fontsource/inter@^5.3.0, @fontsource/source-serif-4@^5.3.0, @fontsource/jetbrains-mono@^5.3.0

### Caffeine

Coffee-brown primary with a latte-colored secondary; the dark mode inverts to a cream primary.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-caffeine`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-caffeine.json

### Catppuccin

Catppuccin's Latte and Mocha pastels: mauve primary, sky accent, Montserrat and Fira Code.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-catppuccin`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-catppuccin.json
- npm: @fontsource/montserrat@^5.3.0, @fontsource/fira-code@^5.3.0

### Claude

Claude's warm palette: terracotta primary on cream and warm charcoal, system fonts and 0.5rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-claude`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-claude.json

### Clean Slate

Slate grays with an indigo primary, Inter and a navy dark mode.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-clean-slate`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-clean-slate.json
- npm: @fontsource/inter@^5.3.0, @fontsource/merriweather@^5.3.0, @fontsource/jetbrains-mono@^5.3.0

### Cobalt

Deep blue primary and sidebar, green brand, Inter and 0.5rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-cobalt`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-cobalt.json
- npm: @fontsource/inter@^5.3.0

### Cosmic Night

Lavender and indigo, with a deep navy-black dark mode and Inter.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-cosmic-night`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-cosmic-night.json
- npm: @fontsource/inter@^5.3.0, @fontsource/jetbrains-mono@^5.3.0

### Default

The stock fma-ds theme from styles.css: neutral grays, Geist and 0.625rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-default`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-default.json

### Elegant Luxury

Burgundy primary with cream and gold accents, Poppins and Libre Baskerville.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-elegant-luxury`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-elegant-luxury.json
- npm: @fontsource/poppins@^5.3.0, @fontsource/libre-baskerville@^5.3.0, @fontsource/ibm-plex-mono@^5.3.0

### Graphite

Monochrome graphite grays from light to charcoal, Montserrat and soft shadows.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-graphite`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-graphite.json
- npm: @fontsource/montserrat@^5.3.0, @fontsource/fira-code@^5.3.0

### Indigo

Indigo primary and sidebar, violet brand, DM Sans and 0.625rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-indigo`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-indigo.json
- npm: @fontsource/dm-sans@^5.3.0

### Kodama Grove

Parchment and olive greens with Merriweather throughout; a warm forest dark mode.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-kodama-grove`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-kodama-grove.json
- npm: @fontsource/merriweather@^5.3.0, @fontsource/source-serif-4@^5.3.0, @fontsource/jetbrains-mono@^5.3.0

### Modern Minimal

White surfaces with a bright blue primary, Inter and tight 0.375rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-modern-minimal`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-modern-minimal.json
- npm: @fontsource/inter@^5.3.0, @fontsource/source-serif-4@^5.3.0, @fontsource/jetbrains-mono@^5.3.0

### Mono

Stark grayscale with Geist Mono everywhere and square corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-mono`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-mono.json
- npm: @fontsource/geist-mono@^5.3.0

### Nature

Forest greens over warm off-white, with Montserrat for UI and Merriweather for serif text.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-nature`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-nature.json
- npm: @fontsource/montserrat@^5.3.0, @fontsource/merriweather@^5.3.0, @fontsource/source-code-pro@^5.3.0

### Northern Lights

Aurora greens and blues on light gray with Plus Jakarta Sans; dark slate mode.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-northern-lights`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-northern-lights.json
- npm: @fontsource/plus-jakarta-sans@^5.3.0, @fontsource/source-serif-4@^5.3.0, @fontsource/jetbrains-mono@^5.3.0

### Ocean Breeze

Sea-green primary over a pale sky-blue background with DM Sans and Lora; navy dark mode.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-ocean-breeze`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-ocean-breeze.json
- npm: @fontsource/dm-sans@^5.3.0, @fontsource/lora@^5.3.0, @fontsource/ibm-plex-mono@^5.3.0

### Plum

Deep purple primary and sidebar, pink brand, Manrope and 0.5rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-plum`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-plum.json
- npm: @fontsource/manrope@^5.3.0

### Soft Pop

Indigo, teal and amber pops on a soft off-white, DM Sans and round 1rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-soft-pop`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-soft-pop.json
- npm: @fontsource/dm-sans@^5.3.0, @fontsource/space-mono@^5.3.0

### Starry Night

Deep night blue with a golden secondary and Libre Baskerville, after Van Gogh.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-starry-night`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-starry-night.json
- npm: @fontsource/libre-baskerville@^5.3.0

### Supabase

Supabase's emerald green on near-white and near-black, Outfit with loose tracking and 0.5rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-supabase`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-supabase.json
- npm: @fontsource/outfit@^5.3.0

### Vintage Paper

Parchment backgrounds, brown ink and Libre Baskerville for an old-print feel.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-vintage-paper`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-vintage-paper.json
- npm: @fontsource/libre-baskerville@^5.3.0, @fontsource/lora@^5.3.0, @fontsource/ibm-plex-mono@^5.3.0

### Violet Bloom

Vivid violet primary on near-white, Plus Jakarta Sans and very round 1.4rem corners.

- Install: `pnpm dlx shadcn@latest add @fma-ds/theme-violet-bloom`
- Registry item: https://ds.fmartinsandre.dev.br/r/theme-violet-bloom.json
- npm: @fontsource/plus-jakarta-sans@^5.3.0, @fontsource/lora@^5.3.0, @fontsource/ibm-plex-mono@^5.3.0