# gnome-ui complete documentation

> Consolidated, LLM-friendly documentation for gnome-ui. Generated from the repository's authoritative Markdown sources; do not edit this file directly.

Use public imports from the documented npm packages. Roadmap items are not released APIs. For a compact index, use https://gnome-ui.org/llms.txt.

---

Source: README.md

# gnome-ui

A React component library that faithfully implements the [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/), built on top of the [Adwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/) design language.

[![npm](https://img.shields.io/npm/v/@gnome-ui/react)](https://www.npmjs.com/package/@gnome-ui/react)
[![CI](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/gnome--ui-docs-3584e4)](https://gnome-ui.org/)
[![Storybook](https://img.shields.io/badge/Storybook-live-ff4785?logo=storybook&logoColor=white)](https://gnome-ui.org/react/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ElJijuna/gnome-ui/blob/main/LICENSE)

Read the guides, architecture, design guidelines, roadmap, and changelog at
**[gnome-ui.org](https://gnome-ui.org/)** — and
browse every component live, with real interactive previews, in each
package's own Storybook (linked throughout, and per-row in the tables
below).

## Packages

| Package | Description | Version |
|---------|-------------|---------|
| [`@gnome-ui/core`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/core) | Framework-agnostic design tokens (CSS custom properties) | [![npm](https://img.shields.io/npm/v/@gnome-ui/core)](https://www.npmjs.com/package/@gnome-ui/core) |
| [`@gnome-ui/icons`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/icons) | Framework-agnostic Adwaita symbolic icon definitions (SVG path data) | [![npm](https://img.shields.io/npm/v/@gnome-ui/icons)](https://www.npmjs.com/package/@gnome-ui/icons) |
| [`@gnome-ui/react`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/react) | React component library | [![npm](https://img.shields.io/npm/v/@gnome-ui/react)](https://www.npmjs.com/package/@gnome-ui/react) |
| [`@gnome-ui/layout`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/layout) | Full-page application shell and dashboard components | [![npm](https://img.shields.io/npm/v/@gnome-ui/layout)](https://www.npmjs.com/package/@gnome-ui/layout) |
| [`@gnome-ui/platform`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/platform) | TypeScript bridge to GNOME host APIs (GSettings, portals, notifications…) | [![npm](https://img.shields.io/npm/v/@gnome-ui/platform)](https://www.npmjs.com/package/@gnome-ui/platform) |
| [`@gnome-ui/hooks`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/hooks) | React hooks that surface `@gnome-ui/platform` APIs as idiomatic React state | [![npm](https://img.shields.io/npm/v/@gnome-ui/hooks)](https://www.npmjs.com/package/@gnome-ui/hooks) |
| [`@gnome-ui/charts`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/charts) | Data visualisation components (Line, Bar, Area) styled with Adwaita tokens | [![npm](https://img.shields.io/npm/v/@gnome-ui/charts)](https://www.npmjs.com/package/@gnome-ui/charts) |
| [`@gnome-ui/react-native`](https://github.com/ElJijuna/gnome-ui/tree/main/packages/react-native) | React Native components for iOS/Android/GNOME-mobile | [![npm](https://img.shields.io/npm/v/@gnome-ui/react-native)](https://www.npmjs.com/package/@gnome-ui/react-native) |

## Quick start

```bash
npm install @gnome-ui/react
```

```tsx
import { Button } from "@gnome-ui/react";
import "@gnome-ui/react/styles";

export default function App() {
  return (
    <Button variant="suggested" onClick={() => console.log("clicked")}>
      Save Changes
    </Button>
  );
}
```

### Locale & number formatting

Wrap your app in `GnomeProvider` to share locale, text direction, and default `Intl` options across `@gnome-ui/react`, `@gnome-ui/layout`, and `@gnome-ui/charts`.

```tsx
import { GnomeProvider } from "@gnome-ui/react";

<GnomeProvider
  locale="en-US"
  numberFormat={{ notation: "compact", compactDisplay: "short" }}
>
  <App />
</GnomeProvider>
```

Compact notation renders values like `1K`; standard notation renders values like `1,000`.

> **Tokens only** (framework-agnostic):
> ```bash
> npm install @gnome-ui/core
> ```
> ```css
> @import "@gnome-ui/core/styles";
> ```

## Components

Live examples and documentation: **[Storybook →](https://gnome-ui.org/react/)**

AI assistants and coding agents can use [`llms.txt`](https://gnome-ui.org/llms.txt)
for a compact documentation index or
[`llms-full.txt`](https://gnome-ui.org/llms-full.txt) for complete context.

The **React Native** and **Web Components** columns show each component's
port status in [`@gnome-ui/react-native`](https://github.com/ElJijuna/gnome-ui/blob/main/packages/react-native/ROADMAP.md)
and [`@gnome-ui/web-components`](https://github.com/ElJijuna/gnome-ui/blob/main/packages/web-components/ROADMAP.md):
✅ shipped · 🚧 in progress · ⬜ planned · 🚫 not planned · — not tracked
there (see that package's own `ROADMAP.md` for why — usually a
domain-specific or React-only component with no cross-platform target).
Generated by [`scripts/generate-component-tables.mjs`](https://github.com/ElJijuna/gnome-ui/blob/main/scripts/generate-component-tables.mjs)
from those two files — edit them, not this table, then run
`npm run tables:generate`.

<!-- component-table:react -->
| Component | Description | React Native | Web Components | Story |
|-----------|-------------|:------------:|:---------------:|-------|
| `AboutDialog` | Standard app info dialog with details, credits, and legal tabs. Mirrors `AdwAboutDialog`. | 🚫 | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-aboutdialog--docs) |
| `ActionRow` | Standard settings row with title, optional subtitle, leading icon, and trailing widget. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-actionrow--docs) |
| `AffectedPackage` |  | — | — | [Docs](https://gnome-ui.org/react/) |
| `AnimatedIcon` | Plays the CSS animation embedded in an `animated` icon from [`@gnome-ui/icons`](https://www.npmjs.com/package/@gnome-ui/icons) — `Syncing`, `Recording`, `Downloading`, `Connecting`. Rendered through plain `Icon` instead, these show a static frame; `AnimatedIcon` is what turns the animation on. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-animatedicon--docs) |
| `Avatar` | Circular avatar following the Adwaita `AdwAvatar` pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-avatar--docs) |
| `AvatarGroup` | Stack of avatars with overflow indicator. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-avatargroup--docs) |
| `AvatarRotator` | Single avatar surface that crossfades through multiple image sources. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-avatarrotator--docs) |
| `Badge` | Counter or status indicator, optionally overlaid on another element. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-badge--docs) |
| `Banner` | Persistent message strip displayed at the top of a view. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-banner--docs) |
| `Bin` | Single-child container with no visual styling. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-bin--docs) |
| `Blockquote` | Styled pull-quote with semantic `<blockquote>` markup. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-blockquote--docs) |
| `BottomSheet` | Slide-up panel that overlays content from the bottom edge. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-bottomsheet--docs) |
| `BoxedList` | Rounded bordered list — the most common container pattern in GNOME settings and detail views. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-boxedlist--docs) |
| `BreakpointBin` | Container that fires layout changes when **its own width** crosses defined thresholds — the CSS container-query equivalent of `AdwBreakpointBin` (libadwaita 1.9 / GNOME 50). | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/adaptive-breakpointbin--docs) |
| `Button` | Button component following the [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/patterns/controls/buttons.html). | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-button--docs) |
| `ButtonContent` | Icon + label layout helper for buttons that contain both an icon and text. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-buttoncontent--docs) |
| `ButtonRow` | Full-width activatable row styled as a button inside a `BoxedList`. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-buttonrow--docs) |
| `Calendar` | Month-grid date display with full keyboard navigation — mirrors [`GtkCalendar`](https://gnome.pages.gitlab.gnome.org/gtk/gtk4/class.Calendar.html). Usable standalone (settings, forms) or as the panel inside a `DatePicker`. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-calendar--docs) |
| `CalendarRange` | Start/end date-range selection driving the same grid engine as `Calendar` — roving `tabindex`, month/year drill-down, `min`/`max`, week numbers, localisation. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-calendarrange--docs) |
| `Callout` | Inline, dismissible admonition box for contextual help text within forms and cards. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-callout--docs) |
| `Card` | Card component following the [GNOME HIG containers](https://developer.gnome.org/hig/patterns/containers.html) and the Adwaita `.card` style class. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-card--docs) |
| `Carousel` | Swipeable content carousel. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-carousel--docs) |
| `Checkbox` | Checkbox for multi-selection, following the GNOME HIG and Adwaita style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-checkbox--docs) |
| `CheckRow` | Activatable row with an integrated checkbox. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-checkrow--docs) |
| `Chip` | Compact pill-shaped label for tags, filters, and selection states. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-chip--docs) |
| `ChoiceCardGroup` | Card-based single-choice selector — large selectable cards instead of radio buttons. | ⬜ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-choicecardgroup--docs) |
| `Clamp` | Constrains its child to a maximum width while allowing it to shrink freely on narrow screens — mirroring the Adwaita `AdwClamp` widget. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/adaptive-clamp--docs) |
| `CoachMark` | Onboarding **feature-discovery** pattern: spotlight a UI element and anchor a callout bubble (title, description, actions) beside it to teach a user one feature. Compose several with `CoachMarkTour`, or drive a single mark with `open`. | ✅ | — | [Docs](https://gnome-ui.org/react/) |
| `CodeBlock` | Static monospace code/config snippet display with optional line numbers and a trailing `CopyButton`. | ⬜ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-codeblock--docs) |
| `ColorPicker` | Color palette picker following the Adwaita `GtkColorButton` + swatch pattern. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-colorpicker--docs) |
| `ColumnView` | Multi-column sortable data table styled with Adwaita design tokens. | 🚫 | — | [Docs](https://gnome-ui.org/react/?path=/docs/data-display-columnview--docs) |
| `ComboRow` | Settings row with an inline combo selector at the trailing edge. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-comborow--docs) |
| `ContributionGraph` | A responsive activity heatmap calendar styled with Adwaita design tokens. Colour intensity represents activity count per day. | 🚫 | — | [Docs](https://gnome-ui.org/react/?path=/docs/data-display-contributiongraph--docs) |
| `CopyButton` | Icon button that copies a value to the clipboard, swapping to a checkmark and a "Copied!" tooltip as confirmation. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-copybutton--docs) |
| `CopyField` | Read-only `TextField` with a built-in trailing `CopyButton`, for displaying copyable values (API keys, tokens, IDs) outside the `CveIdentifier`/`CweIdentifier`-style specialised components. | ⬜ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-copyfield--docs) |
| `CountDownTimer` | Displays a countdown timer showing the remaining time until a specified end date. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-countdowntimer--docs) |
| `CveIdentifier` | Monospace CVE identifier for vulnerability tables, findings, and report references. | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-cveidentifier--docs) |
| `CvssScore` | Compact CVSS score display for vulnerability tables, finding summaries, and CVE detail surfaces. | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-cvssscore--docs) |
| `CvssVector` |  | — | — | [Docs](https://gnome-ui.org/react/) |
| `CweIdentifier` |  | — | — | [Docs](https://gnome-ui.org/react/) |
| `DatePicker` | A [`Popover`](../Popover)-anchored [`Calendar`](../Calendar) behind an entry-styled trigger — mirrors the `GtkCalendar` + `GtkPopover` composition GNOME apps use for date entry. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-datepicker--docs) |
| `DateRangePicker` | A [`Popover`](../Popover)-anchored [`CalendarRange`](../CalendarRange) behind an entry-styled trigger — the range counterpart of `DatePicker`, and the same `GtkCalendar` + `GtkPopover` composition GNOME apps use for date entry. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-daterangepicker--docs) |
| `Dialog` | Blocking modal dialog — two modes in one component. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-dialog--docs) |
| `Divider` | Horizontal rule with an optional centred label — common auth/login-form pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-divider--docs) |
| `Drawer` | Slide-over panel for supplementary React content. Use `side` to open from the left or right, `size` for classic or wide widths, and pass the body through `children` or the `content` prop. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-drawer--docs) |
| `Dropdown` | Expandable option list following the Adwaita combo-row / drop-down style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-dropdown--docs) |
| `EmojiPicker` | Searchable emoji grid in a `Popover`. Mirrors `GtkEmojiChooser`. | ⬜ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-emojipicker--docs) |
| `EntryRow` | Row with an inline text entry field. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-entryrow--docs) |
| `Expander` | Standalone disclosure triangle + collapsible content — mirrors `GtkExpander`. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-expander--docs) |
| `ExpanderRow` | Collapsible `ActionRow` that reveals nested rows on activation. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-expanderrow--docs) |
| `FieldGroup` | Generic form-field grouping with a shared label, help text, and error message, for arbitrary fields outside a `BoxedList`. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-fieldgroup--docs) |
| `FileDropZone` | Drag-and-drop file upload target with hover/active states, falling back to a `GtkFileDialog`-style click-to-browse trigger. | ⬜ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-filedropzone--docs) |
| `FileTypeIcon` | Small icon — optionally a thumbnail — resolved from a file's MIME type or name extension. Useful for file-manager-style listings. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-filetypeicon--docs) |
| `FilterableMultiSelectDropdown` | `MultiSelectDropdown` plus a filter field for narrowing long option lists. | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-filterablemultiselectdropdown--docs) |
| `FontPicker` | Button that opens a family/size/weight chooser. Mirrors `GtkFontDialogButton`: the trigger itself previews the current selection rendered in that font. | ⬜ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-fontpicker--docs) |
| `Footer` | Bottom bar with leading/trailing slots and optional center content. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-footer--docs) |
| `Frame` | Simple bordered surface with `border-radius` but no background fill. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-frame--docs) |
| `HeaderBar` | Title bar with centered title and leading/trailing action slots. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-headerbar--docs) |
| `Highlight` | Wraps every occurrence of `query` within `text` in a `<mark>` element. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-highlight--docs) |
| `Icon` | Renders an [`@gnome-ui/icons`](https://www.npmjs.com/package/@gnome-ui/icons) definition as an inline SVG. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-icon--docs) |
| `IconButton` | Icon-only action button composed from `Button`, `Icon`, and optionally `Tooltip`. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-iconbutton--docs) |
| `InlineViewSwitcher` | Compact inline view switcher for placing inside content areas, cards, or toolbars. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-inlineviewswitcher--docs) |
| `Kbd` | Standalone single key-cap for inline instructional text. | 🚫 | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-kbd--docs) |
| `LevelBar` | Discrete level indicator with colour-coded low/high offset zones — mirrors `GtkLevelBar`. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-levelbar--docs) |
| `Link` | Inline hyperlink following GNOME HIG. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-link--docs) |
| `LinkedGroup` | Renders children as a single visually-connected unit with no gap and merged borders. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-linkedgroup--docs) |
| `Modal` |  | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-modal--docs) |
| `MultiSelectDropdown` | Checkbox-list variant of `Dropdown` for selecting multiple values from a single trigger. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-multiselectdropdown--docs) |
| `NavigationSplitView` | Two-pane sidebar + content layout that collapses to a single navigable pane on narrow screens (≤ 400 px), mirroring `AdwNavigationSplitView`. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/adaptive-navigationsplitview--docs) |
| `NavigationView` | Single-pane push/pop navigation stack. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-navigationview--docs) |
| `OtpInput` | Segmented PIN/verification-code input — one cell per digit, with auto-advance on typing, backspace-to-previous-cell, and paste support. | ⬜ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-otpinput--docs) |
| `Overlay` | Standalone backdrop/scrim layer with a fade transition and click-to-dismiss — the shared building block behind `Modal`, `Dialog`, and `BottomSheet`'s backdrops, extracted for building custom overlay UI. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-overlay--docs) |
| `OverlaySplitView` | Sidebar + content layout where the sidebar becomes a slide-over **overlay** on narrow screens (≤ 400 px), mirroring `AdwOverlaySplitView`. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/adaptive-overlaysplitview--docs) |
| `PasswordEntryRow` | Password entry row with a built-in reveal/conceal toggle. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-passwordentryrow--docs) |
| `PasswordField` | Single-line password input with a peek toggle that reveals the value as plain text. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-passwordfield--docs) |
| `PathBar` | Breadcrumb path bar for navigating a hierarchical location. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-pathbar--docs) |
| `Popover` | Floating panel anchored to a trigger element, following the Adwaita `GtkPopover` pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-popover--docs) |
| `Portal` | Reusable `createPortal` wrapper — SSR-safe (renders `children` inline when `document` is unavailable) with optional mount-target support. | 🚫 | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-portal--docs) |
| `PreferencesDialog` | Multi-page settings dialog using `PreferencesPage` tabs. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-preferencesdialog--docs) |
| `PreferencesGroup` | Titled section that wraps a `BoxedList` with an optional description. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-preferencesgroup--docs) |
| `PreferencesPage` | Scrollable page composed of `PreferencesGroup` sections. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-preferencespage--docs) |
| `ProgressBar` | Determinate and indeterminate progress bar following the Adwaita style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-progressbar--docs) |
| `RadioButton` | Single-selection radio button following the GNOME HIG and Adwaita style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-radiobutton--docs) |
| `RangeSlider` | Dual-thumb slider for selecting a min/max range, following the Adwaita `GtkScale` pattern used by `Slider`. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-rangeslider--docs) |
| `RatingStars` | Star rating display and input. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-ratingstars--docs) |
| `ScrollToTop` | Fixed-position button that scrolls the page to the top on click, following the GNOME Human Interface Guidelines. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-scrolltotop--docs) |
| `SearchBar` | Collapsible search bar following the Adwaita `AdwSearchBar` pattern. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-searchbar--docs) |
| `SecurityMetric` |  | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-securitymetric--docs) |
| `SegmentedBar` | Horizontal bar split into proportional segments, one per category. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-segmentedbar--docs) |
| `Separator` | Thin dividing line that separates groups of content. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-separator--docs) |
| `SeverityBadge` | Pill-shaped label for vulnerability severities in security reports, CVE tables, dashboards, and scanner results. | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-severitybadge--docs) |
| `ShortcutLabel` | Read-only display of a keyboard shortcut with per-key key-cap styling. | 🚫 | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-shortcutlabel--docs) |
| `ShortcutsDialog` | Modal dialog listing keyboard shortcuts grouped in sections, with integrated search. | 🚫 | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-shortcutsdialog--docs) |
| `Sidebar` | Lateral navigation panel following the Adwaita `.navigation-sidebar` pattern. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-sidebar--docs) |
| `Skeleton` | Content-shaped loading placeholder for skeleton screens. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-skeleton--docs) |
| `Slider` | Draggable range control following the Adwaita `GtkScale` pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-slider--docs) |
| `SpinButton` | Numeric input with − and + buttons following the Adwaita `GtkSpinButton` style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-spinbutton--docs) |
| `Spinner` | Indeterminate loading indicator following the Adwaita spinner style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-spinner--docs) |
| `SpinRow` | Settings row with an integrated spin button for numeric values. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-spinrow--docs) |
| `SplitButton` | Primary action button with an attached dropdown arrow. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-splitbutton--docs) |
| `StatusBadge` | Pill-shaped text label for entity status. Use for human-readable state labels like `published`, `beta`, or `new` — not for numeric counts (use `Badge` for those). | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-statusbadge--docs) |
| `StatusPage` | Empty-state and status page following the Adwaita `AdwStatusPage` pattern. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-statuspage--docs) |
| `StepIndicator` | Numbered "Step X of Y" progress indicator for onboarding/wizard flows. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-stepindicator--docs) |
| `Switch` | On/off toggle following the Adwaita switch style. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-switch--docs) |
| `SwitchRow` | Activatable row with an integrated switch. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-switchrow--docs) |
| `Tabs` | Tab-based navigation following the Adwaita `AdwTabBar` pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-tabs--docs) |
| `TagInput` | Type-to-add multi-value input rendering entries as removable `Chip`s in a `WrapBox`. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-taginput--docs) |
| `TerminalView` | Scrollable terminal-style output area styled after GNOME Terminal. Intended for displaying logs, command output, or read-only text content. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-terminalview--docs) |
| `Text` | Typography component mirroring all [Adwaita text style classes](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html). | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-text--docs) |
| `TextField` | Single-line text input with label, helper text, and error state. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-textfield--docs) |
| `TextTruncate` | Single/multi-line text truncation with an automatic tooltip revealing the full content on overflow — mirrors `GtkLabel`'s `ellipsize` property. | ⬜ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-texttruncate--docs) |
| `Timeline` | Ordered sequence of events connected by a visual timeline. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-timeline--docs) |
| `TimePicker` | Hour/minute selection built from paired [`SpinButton`](../SpinButton)s inside a [`Popover`](../Popover), behind an entry-styled trigger — mirrors the `GtkSpinButton` + `GtkPopover` composition GNOME apps use for time entry, with 12- and 24-hour support. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-timepicker--docs) |
| `Toast` | Non-blocking temporary notification following the Adwaita `AdwToast` pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-toast--docs) |
| `ToggleGroup` | Mutually-exclusive group of toggle buttons for in-place option selection. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-togglegroup--docs) |
| `Toolbar` | Horizontal action bar following the libadwaita `.toolbar` pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-spacer--docs) |
| `ToolbarView` | Layout container that attaches bars at the top and/or bottom while scrolling only the middle content. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-toolbarview--docs) |
| `Tooltip` | Informational floating label following the GNOME HIG tooltip pattern. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-tooltip--docs) |
| `ViewSwitcher` | Segmented control for switching between major views, mirroring the Adwaita `AdwViewSwitcher`. | ✅ | ✅ | [Docs](https://gnome-ui.org/react/?path=/docs/components-viewswitcher--docs) |
| `ViewSwitcherBar` | Bottom navigation bar for `ViewSwitcher` items on narrow screens (≤ 550 px), mirroring `AdwViewSwitcherBar`. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/adaptive-viewswitcherbar--docs) |
| `ViewSwitcherSidebar` | Sidebar-style view switcher for apps with many top-level views or when the sidebar layout fits better than a header-bar `ViewSwitcher`. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-viewswitchersidebar--docs) |
| `VisuallyHidden` | Reusable "sr-only" utility — visually hides content while keeping it in the accessibility tree, so screen readers still announce it. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-visuallyhidden--docs) |
| `VulnerabilityFinding` |  | — | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-vulnerabilityfinding--docs) |
| `VulnerabilitySummary` |  | — | — | [Docs](https://gnome-ui.org/react/) |
| `WidgetManager` | Card that manages a controlled collection of "widgets" picked from a `catalog`, each rendering its own content via `render()`. The header's edit button toggles a dashed "add widget" trigger that opens a catalog picker — `Modal`, `BottomSheet`, or `Drawer`, chosen with `pickerSurface`. Adding and removing is staged inside the picker and only applied through `onChange` when the user confirms; canceling discards the staging. Widgets can only be removed through the picker, not inline in the card. | ✅ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-widgetmanager--docs) |
| `WindowTitle` | Two-line title + subtitle widget for use inside a `HeaderBar`. | ⬜ | — | [Docs](https://gnome-ui.org/react/?path=/docs/components-windowtitle--docs) |
| `WrapBox` | Flexible wrapping layout container. | ✅ | ⬜ | [Docs](https://gnome-ui.org/react/?path=/docs/components-wrapbox--docs) |
<!-- /component-table:react -->

### Layout shells & dashboard (`@gnome-ui/layout`)

Live examples and documentation: **[Storybook →](https://gnome-ui.org/layout/)**

<!-- component-table:layout -->
| Component | Description | Story |
|-----------|-------------|-------|
| `ActivityFeed` | Chronological list of recent events with relative timestamps, optional icons, skeleton loading state, and a "Show more" affordance. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-activityfeed--docs) |
| `AdaptiveLayout` | Full-page adaptive shell that switches navigation automatically based on viewport width. Use the **viewport toolbar** to preview each breakpoint: | [Docs](https://gnome-ui.org/layout/?path=/docs/adaptive-adaptivelayout--docs) |
| `AppHeader` | GNOME application header with named shell slots. | [Docs](https://gnome-ui.org/layout/) |
| `ApplicationCard` | App detail header with avatar, name, badge, description, stat row, and actions. Designed for the MyApps `AppDetail` view — use `EntityCard` for list rows. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-applicationcard--docs) |
| `Banner` | Persistent in-app message strip shown at the top of a view, following GNOME HIG banner guidelines. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-banner--docs) |
| `ChartCard` |  | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-chartcard--docs) |
| `CounterCard` | Metric card with an animated numeric counter. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-countercard--docs) |
| `DashboardGrid` | Responsive 12-column grid container for dashboard widgets and panels. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-dashboardgrid--docs) |
| `EmptyState` | Centered empty-state illustration for views with no data. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-emptystate--docs) |
| `EntityCard` | Avatar/icon + title + meta card. Covers both compact grid cards (Following screen) and full-width list rows (MyApps screen) via additive optional props. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-entitycard--docs) |
| `ErrorState` | Error state with four presets that set a default icon and title. All defaults can be overridden via `icon` and `title` props. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-errorstate--docs) |
| `FileManager` | GNOME Files (Nautilus)–style file browser assembled from **`@gnome-ui/layout`** and **`@gnome-ui/react`** components. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-filemanager--docs) |
| `IconBadge` | Rounded-square tinted icon container. Accepts the seven gnome-ui named colors or any hex value (`#rgb` / `#rrggbb`). In both cases the background is rendered at 15% opacity via `color-mix`. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-iconbadge--docs) |
| `Layout` | Full-page application shell from **`@gnome-ui/layout`** that composes four named zones following the GNOME Human Interface Guidelines. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-layout--docs) |
| `LoadingStatus` | Visually hidden live region announcing a skeleton loading state to screen readers. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-loadingstatus--docs) |
| `MasonryGrid` | Masonry layout that distributes variable-height items across columns using a **shortest-column-first** algorithm — each new item is placed in the column with the least accumulated height, minimising gaps. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-masonrygrid--docs) |
| `PageContent` | Page content container with GNOME spacing and optional width clamping. | [Docs](https://gnome-ui.org/layout/) |
| `PanelCard` | Card with a structured **header / body / footer** layout and built-in collapse/expand behaviour. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-panelcard--docs) |
| `ProfileCard` | Dashboard card for displaying a user profile — avatar, name, handle, optional status dot, optional stats row, and an optional decorative background chart. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-profilecard--docs) |
| `ProgressCard` | Resource usage card with a labeled progress bar. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-progresscard--docs) |
| `QuickActions` | Grid of shortcut action buttons for dashboards, file managers, and control panels. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-quickactions--docs) |
| `ResizablePanel` | Two or more panels separated by a draggable divider, based on the `GtkPaned` pattern. Foundational for user-resizable master-detail layouts (code editors, file explorers, analytics dashboards). | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-resizablepanel--docs) |
| `SectionHeader` | Title row for dashboard sections with optional subtitle and trailing action slot. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-sectionheader--docs) |
| `Settings` | GNOME Settings–style preferences app assembled from **`@gnome-ui/layout`** and **`@gnome-ui/react`**. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-settings--docs) |
| `SidebarShell` | Full-height GNOME sidebar with fixed header/footer and scrollable navigation area. | [Docs](https://gnome-ui.org/layout/) |
| `SidebarTrigger` | Header button that opens overlay sidebars on narrow screens and toggles rail collapse on wider screens. | [Docs](https://gnome-ui.org/layout/) |
| `SplitLayout` | List/master + detail shell following the Adwaita `AdwNavigationSplitView` pattern, with a `HeaderBar` for each pane — the way real Adwaita apps (Settings, Files, Contacts) actually look, rather than the bare pane-toggle mechanics of `@gnome-ui/react`'s `NavigationSplitView` that this composes. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-splitlayout--docs) |
| `StatCard` | Metric card for dashboards with optional unit, trend indicator, icon, background chart, and loading state. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-statcard--docs) |
| `StatusBar` | Compact footer/status bar for application shells. | [Docs](https://gnome-ui.org/layout/) |
| `StatusIndicator` | Status dot for communicating the health of a service, connection, or resource. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-statusindicator--docs) |
| `StickyToc` | Sticky table-of-contents side rail with scroll-spy: the link for the section currently nearest the top of the viewport is highlighted automatically as the user scrolls. For long docs/settings pages. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-stickytoc--docs) |
| `TeamCard` | Group identity card: avatar group, team name, and member count. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-teamcard--docs) |
| `Toast` | In-app notifications following the GNOME Human Interface Guidelines. | [Docs](https://gnome-ui.org/layout/) |
| `UserCard` | User identity panel for popovers, sidebar footers, and profile pages. | [Docs](https://gnome-ui.org/layout/?path=/docs/layout-usercard--docs) |
<!-- /component-table:layout -->

### Data visualization (`@gnome-ui/charts`)

Live examples and documentation: **[Storybook →](https://gnome-ui.org/charts/)**

<!-- component-table:charts -->
| Component | Description | Story |
|-----------|-------------|-------|
| `AreaChart` | Area chart built on Recharts with GNOME design tokens, supporting stacked areas and gradient fills. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-areachart--docs) |
| `BarChart` | Bar chart built on Recharts with GNOME design tokens for grouped comparisons across categories. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-barchart--docs) |
| `BoxPlot` | Box-and-whisker plot built with plain HTML/CSS — no Recharts (it has no native box-plot primitive). Shows the distribution of one or more groups: median, interquartile range (Q1–Q3), whiskers extending to the most extreme non-outlier value, and outliers beyond 1.5×IQR. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-boxplot--docs) |
| `BulletChart` | Bullet graph (Stephen Few) built with plain SVG-free HTML — no Recharts. Shows a performance measure against a target and qualitative ranges in a single compact horizontal track, for KPI rows in tables and dashboards where `GaugeChart` takes too much vertical space. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-bulletchart--docs) |
| `CloudChart` | Word/tag cloud that scales each term's font size proportionally to its numeric value. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-cloudchart--docs) |
| `ComposedChart` | Mixed chart combining bars, lines, and areas on shared axes. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-composedchart--docs) |
| `FunnelChart` | Funnel visualization for conversion rates and sales pipelines. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-funnelchart--docs) |
| `GaugeChart` | Single-value speedometer gauge built on Recharts. Renders a semicircular arc between `min` and `max`, with the current value shown as a label at its center — for KPI dashboards, alongside `StatCard` from `@gnome-ui/layout`. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-gaugechart--docs) |
| `Heatmap` | Generic matrix heatmap built in pure CSS/SVG (no Recharts dependency) — for correlation matrices, density grids, or any row × column value grid. For a calendar-shaped activity heatmap, use `ContributionGraph` from `@gnome-ui/react` instead. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-heatmap--docs) |
| `LineChart` | Line chart built on Recharts with GNOME design tokens for axes, grid, and tooltips. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-linechart--docs) |
| `PieChart` | Pie and donut chart built on Recharts for part-to-whole comparisons. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-piechart--docs) |
| `RadarChart` | Radar (spider) chart built on Recharts for comparing multiple attributes across one or more subjects. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-radarchart--docs) |
| `RadialBarChart` | Radial bar chart built on Recharts. Each data item renders as a circular arc, useful for showing multiple metrics as circular progress rings. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-radialbarchart--docs) |
| `SankeyChart` | Flow diagram built on Recharts. Renders named nodes as columns of rectangles connected by curved, proportionally-sized links — for multi-stage funnels, user journeys, or any flow between categories. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-sankeychart--docs) |
| `ScatterChart` | Scatter and bubble chart for visualizing correlation between two numeric variables. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-scatterchart--docs) |
| `TreeMap` | Tree map built on Recharts. Displays hierarchical data as nested rectangles; area is proportional to each item's value. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-treemap--docs) |
| `WaterfallChart` | Floating-bar chart built on Recharts for the cumulative effect of a sequence of increases and decreases — revenue bridges, budget breakdowns, cohort attrition. Each bar starts where the previous one ended; mark `isTotal` on start/end/subtotal bars to anchor them to zero instead. | [Docs](https://gnome-ui.org/charts/?path=/docs/charts-waterfallchart--docs) |
<!-- /component-table:charts -->

See [ROADMAP.md](https://github.com/ElJijuna/gnome-ui/blob/main/ROADMAP.md) for the full list of planned components.

## Development

### Prerequisites

- Node.js 22+
- npm 10+

### Setup

```bash
git clone https://github.com/your-org/gnome-react.git
cd gnome-react
npm install
```

### Commands

| Command | Description |
|---------|-------------|
| `npm run build` | Build all packages |
| `npm run storybook` | Start Storybook dev server at `localhost:6006` |
| `npm run build-storybook` | Build Storybook for production |
| `npm run typecheck` | Type-check all packages |
| `npm run lint` | Lint all packages |

### Project structure

```
gnome-ui/
├── packages/
│   ├── core/          # @gnome-ui/core     — CSS design tokens
│   ├── icons/         # @gnome-ui/icons    — Adwaita icon definitions (SVG path data)
│   ├── react/         # @gnome-ui/react    — React components
│   ├── layout/        # @gnome-ui/layout   — Application shell & dashboard components
│   ├── platform/      # @gnome-ui/platform — GNOME host bridge (GSettings, portals…)
│   ├── hooks/         # @gnome-ui/hooks    — React hooks for platform APIs
│   └── charts/        # @gnome-ui/charts   — Adwaita-styled chart components
├── GNOME_GUIDELINES.md
├── ROADMAP.md
└── turbo.json
```

## Contributing

Read [CONTRIBUTING.md](https://github.com/ElJijuna/gnome-ui/blob/main/CONTRIBUTING.md) before opening a pull request.

This project uses [Conventional Commits](https://www.conventionalcommits.org/). Your commit messages determine the next version automatically via semantic-release:

| Prefix | Release |
|--------|---------|
| `feat:` | minor |
| `fix:`, `perf:`, `refactor:` | patch |
| `feat!:` or `BREAKING CHANGE:` | major |
| `chore:`, `docs:`, `test:` | no release |

## License

[MIT](https://github.com/ElJijuna/gnome-ui/blob/main/LICENSE) © el_jijuna

---

Source: COMPONENT_INDEX.md

# Component Index

Snapshot: 2026-06-30.

Scope: `@gnome-ui/react`, `@gnome-ui/layout`, `@gnome-ui/charts`.

## Inventory

| Package | Public component dirs | Root index | Package subpath exports | Notes |
|---------|-----------------------|------------|--------------------------|-------|
| `@gnome-ui/react` | 84 | 84 | 84 component paths + 2 provider internals | Full root export parity. Added missing `ScrollToTop` subpath export. |
| `@gnome-ui/layout` | 28 | 28 | 28 | Added `ChartCard`; added missing `LoadingStatus` subpath export. |
| `@gnome-ui/charts` | 14 | 14 | 14 | Added missing `ComposedChart`, `FunnelChart`, `ScatterChart` subpath exports. |

Coverage/doc shape:

| Artifact | Count |
|----------|-------|
| Component `index.ts` files | 126 |
| Component READMEs | 123 |
| Component stories | 124 |
| Component tests | 101 |

## `@gnome-ui/react`

Foundation:

- Controls: `Button`, `IconButton`, `SplitButton`, `ButtonContent`, `Switch`, `Checkbox`, `RadioButton`, `TextField`, `SpinButton`, `Slider`, `Dropdown`, `SearchBar`, `Link`, `ToggleGroup`, `InlineViewSwitcher`, `PathBar`, `ScrollToTop`.
- Display: `Text`, `Icon`, `Avatar`, `AvatarGroup`, `AvatarRotator`, `Badge`, `StatusBadge`, `Blockquote`, `Spinner`, `ProgressBar`, `SegmentedBar`, `Skeleton`, `CountDownTimer`, `StatusPage`, `Separator`, `Chip`, `ShortcutLabel`, `WindowTitle`, `Timeline`, `ContributionGraph`, `TerminalView`.
- Layout/containers: `Box`, `Card`, `Frame`, `Bin`, `HeaderBar`, `Toolbar`, `Spacer`, `ToolbarView`, `LinkedGroup`, `Sidebar`, `SidebarSection`, `SidebarItem`, `BoxedList`, `ActionRow`, `ButtonRow`, `ExpanderRow`, `SwitchRow`, `CheckRow`, `ComboRow`, `EntryRow`, `PasswordEntryRow`, `SpinRow`, `WrapBox`, `TabBar`, `TabItem`, `TabPanel`, `ViewSwitcher`, `ViewSwitcherItem`, `ViewSwitcherBar`, `ViewSwitcherSidebar`, `ViewSwitcherSidebarItem`, `Carousel`, `ShortcutsDialog`.
- Overlays: `Toast`, `Toaster`, `Dialog`, `Modal`, `BottomSheet`, `Drawer`, `Tooltip`, `Popover`, `Banner`, `AboutDialog`.
- Preferences: `PreferencesGroup`, `PreferencesPage`, `PreferencesDialog`.
- Adaptive: `useBreakpoint`, `Clamp`, `BreakpointBin`, `NavigationView`, `NavigationPage`, `NavigationSplitView`, `OverlaySplitView`.
- Provider: `GnomeProvider`, `useLocale`, `useDir`, `useColorScheme`, `useResolvedColorScheme`, `useAccentColor`, `useNumberFormatter`, `useDateTimeFormatter`.

Assessment:

- Strong GNOME/libadwaita coverage. Most widget-gallery patterns already exist.
- Main risk now: API bloat without composition guidance. New low-level widgets should be rare.
- More useful next layer: app workflow components, data density, empty/loading/error consistency.

## `@gnome-ui/layout`

Application shell:

- `Layout`, `AppHeader`, `PageContent`, `SidebarShell`, `SidebarTrigger`, `StatusBar`, `AdaptiveLayout`.

Dashboard/application composition:

- `DashboardGrid`, `MasonryGrid`, `PanelCard`, `SectionHeader`, `ActivityFeed`, `QuickActions`, `StatCard`, `CounterCard`, `ProgressCard`, `ChartCard`, `StatusIndicator`, `LoadingStatus`.

Entity/state cards:

- `ApplicationCard`, `EntityCard`, `UserCard`, `ProfileCard`, `IconBadge`, `EmptyState`, `ErrorState`, `Banner`, `Toast`.

Assessment:

- Package duplicates some `react` primitives by intention (`Banner`, `Toast`, state components) but naming can confuse consumers.
- Best future work: higher-level shells where app teams otherwise hand-roll layout glue.
- Avoid moving data table here while `ColumnView` exists in `react`; build wrappers only when async/stateful needs justify it.

## `@gnome-ui/charts`

General charts:

- `LineChart`, `AreaChart`, `BarChart`, `ComposedChart`, `PieChart`, `RadarChart`, `RadialBarChart`, `TreeMap`, `CloudChart`, `ScatterChart`, `FunnelChart`.

Compact charts:

- `SparkLineChart`, `SparkAreaChart`, `SparkBarChart`.

Utilities:

- `GNOME_CHART_PALETTE`, `ChartLegendPosition`.

Assessment:

- Chart type coverage is broad enough for dashboards.
- Biggest missing piece is not more chart shapes; it is shared chart scaffolding: headers, summaries, loading/error/empty, accessibility, export actions.
- `ContributionGraph` currently lives in `react` as pure SVG/data display; keep it there unless chart package becomes umbrella for all visualizations.

## Recommended New Components

Priority 1:

| Component | Package | Why useful | Shape |
|-----------|---------|------------|-------|
| `ChartCard` | `@gnome-ui/layout` | Done. Every dashboard chart needs same shell: title, subtitle, metric, actions, loading, empty, error. Prevents repeated `Card` + `SectionHeader` + chart glue. | `title`, `subtitle`, `value`, `trend`, `actions`, `loading`, `error`, `empty`, `children`. |
| `MetricGrid` | `@gnome-ui/layout` | Common pattern: 2-6 `StatCard`/`CounterCard` blocks with responsive columns. Thin wrapper over `DashboardGrid`, but names intent. | `items`, `columns`, `loading`, `renderItem`. |
| `ResourceMeter` | `@gnome-ui/react` | `ProgressBar` + threshold label/status appears in CPU/memory/storage/settings. Smaller primitive than `ProgressCard`. | `value`, `max`, `label`, `format`, `thresholds`, `variant`. |
| `FilterBar` | `@gnome-ui/react` | Search + chips + dropdown filters + clear action is common across lists/tables. Current pieces exist, composition repeats. | `query`, `filters`, `activeFilters`, `onClear`, slots. |
| `PageHeader` | `@gnome-ui/layout` | App pages need consistent title/subtitle/actions above content; `AppHeader` is shell-level. | `title`, `subtitle`, `breadcrumbs`, `actions`, `metadata`. |

Priority 2:

| Component | Package | Why useful | Shape |
|-----------|---------|------------|-------|
| `DataState` | `@gnome-ui/react` | Standardizes loading/empty/error/success branching around content. Reduces repeated conditional UI. | `loading`, `error`, `empty`, `skeleton`, `children`. |
| `SelectionToolbar` | `@gnome-ui/react` | Lists/tables need bulk actions once items selected. GNOME apps use contextual bars often. | `selectedCount`, `actions`, `onClear`. |
| `DateRangePicker` | `@gnome-ui/react` | Charts/filtering need time ranges. Current controls lack date/range primitive. | `value`, `onChange`, `presets`, `locale`. |
| `Pagination` | `@gnome-ui/react` | `ColumnView`/cards need page controls when virtualization not desired. | `page`, `pageCount`, `onPageChange`, `totalItems`. |
| `DetailsList` | `@gnome-ui/react` | Read-only key/value metadata is common; `ActionRow variant="property"` helps but verbose. | `items`, `columns`, `copyable`, `orientation`. |

Priority 3:

| Component | Package | Why useful | Shape |
|-----------|---------|------------|-------|
| `ResizablePanel` | `@gnome-ui/layout` | Existing layout roadmap item; useful for editors/file managers/analytics. | `direction`, `defaultSizes`, `minSizes`, children. |
| `CommandPalette` | `@gnome-ui/layout` | Existing roadmap item; app-level nav/action search. High utility but bigger API. | `open`, `items`, `groups`, `onSelect`, `shortcut`. |
| `NotificationCenter` | `@gnome-ui/layout` | Complements `Toast`; useful for persistent notifications/history. | `items`, `groups`, `onDismiss`, `actions`. |
| `KpiChartCard` | `@gnome-ui/layout` | Opinionated combo: metric + spark chart + trend. Very dashboard-useful, but can be built after `ChartCard`. | `metric`, `trend`, `spark`, `period`. |
| `ExportMenu` | `@gnome-ui/react` | Charts/tables commonly expose CSV/PNG/copy actions. Generic menu avoids per-chart duplication. | `items`, `formats`, `onExport`. |

## Do Not Add Yet

- New primitive chart types before `ChartCard`/data-state exists. Current chart coverage already broad.
- More row variants unless direct libadwaita/HIG pattern exists. `ActionRow` + slots covers many.
- Another `DataTable` in `layout`; `ColumnView` exists in `react`. If async table needed, make `DataView` wrapper using `ColumnView`.
- Separate `DrawerPanel`; `Drawer`, `BottomSheet`, `OverlaySplitView` already cover most overlay panel needs. Add only if common filter/detail drawer API emerges.

## Implementation Rules For Next Components

- Package boundary: `react` = primitives, `layout` = app/workflow composition, `charts` = visualization primitives/utilities.
- Export parity: every public component needs root export, per-component `index.ts`, package subpath export, README, story, focused test.
- Accessibility: named controls, keyboard path, ARIA only where semantic HTML is insufficient.
- Intl: numbers/dates use `GnomeProvider` formatter hooks unless component receives explicit formatter.
- Motion: all transitions respect `prefers-reduced-motion`.
- Dependencies: avoid new runtime deps unless domain logic is hard and proven lib exists.

---

Source: GNOME_GUIDELINES.md

# GNOME Design System — Guidelines

Reference for building components that follow the [GNOME Human Interface Guidelines (HIG)](https://developer.gnome.org/hig/) and the [Adwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/css-variables.html) design language.

---

## 1. Design Principles

1. **Clarity** — Interfaces should be easy to understand at a glance.
2. **Consistency** — Use system patterns. Users learn the UI once; it must behave the same everywhere.
3. **Efficiency** — Minimize steps to complete tasks.
4. **Forgiveness** — Prefer reversible actions. Confirm destructive ones.
5. **Accessibility** — Use relative font sizes, sufficient contrast, and keyboard navigation.

---

## 2. Color

All colors are exposed as CSS custom properties via `tokens.css`.

### Palette

| Name     | Shade 1 (lightest) | Shade 3 (base)  | Shade 5 (darkest) |
|----------|--------------------|-----------------|-------------------|
| Blue     | `#99c1f1`          | `#3584e4`       | `#1a5fb4`         |
| Green    | `#8ff0a4`          | `#33d17a`       | `#26a269`         |
| Yellow   | `#f9f06b`          | `#f6d32d`       | `#e5a50a`         |
| Orange   | `#ffbe6f`          | `#ff7800`       | `#c64600`         |
| Red      | `#f66151`          | `#e01b24`       | `#a51d2d`         |
| Purple   | `#dc8add`          | `#9141ac`       | `#63452c`         |

### Semantic Tokens

| Token                        | Purpose                                     |
|------------------------------|---------------------------------------------|
| `--gnome-accent-color`       | Interactive elements (links, focus rings)   |
| `--gnome-accent-bg-color`    | Suggested action button background          |
| `--gnome-destructive-bg-color` | Destructive action button background      |
| `--gnome-success-bg-color`   | Positive feedback / success state           |
| `--gnome-warning-bg-color`   | Cautionary state                            |
| `--gnome-error-bg-color`     | Error state                                 |

### Rules

- **Never hard-code colors**. Always reference design tokens.
- Default accent color is **blue** (`--gnome-blue-3: #3584e4`). Users/distributions may override it.
- Always support **dark mode** via `@media (prefers-color-scheme: dark)` or a `.dark` data attribute.
- Minimum contrast ratio: **4.5:1** for text (WCAG AA).

---

## 3. Typography

Font family: **Adwaita Sans** (falls back to Cantarell → Inter → system-ui).

```css
font-family: var(--gnome-font-family);
```

### Scale

| Token                          | Size (rem) | Use case              |
|--------------------------------|------------|-----------------------|
| `--gnome-font-size-caption`    | 0.75rem    | Labels, captions      |
| `--gnome-font-size-body`       | 1rem       | Body text (base)      |
| `--gnome-font-size-title-4`    | 1.125rem   | Small headings        |
| `--gnome-font-size-title-3`    | 1.25rem    | Section headings      |
| `--gnome-font-size-title-2`    | 1.5rem     | Page headings         |
| `--gnome-font-size-title-1`    | 1.875rem   | Modal/dialog titles   |
| `--gnome-font-size-large-title`| 2.25rem    | Hero / welcome screens|

### Rules

- **Always use `rem`/`em`**, never `px` for font sizes — respects user accessibility settings.
- **Minimize font variants** — stick to normal (400) and semibold (600).
- Use **Header Capitalization** for button labels and headings (e.g. "Save Document").
- Use proper Unicode: `"` `"` (U+201C/201D), `…` (U+2026), `–` (U+2013).

---

## 4. Spacing

6 px base grid. All spacing tokens are multiples of 6 px.

| Token              | Value | Use case                                    |
|--------------------|-------|---------------------------------------------|
| `--gnome-space-1`  | 6px   | Icon-label gap, tight inline spacing        |
| `--gnome-space-2`  | 12px  | Label-to-component gap, button padding      |
| `--gnome-space-3`  | 18px  | Group separation (vertical)                 |
| `--gnome-space-4`  | 24px  | Section padding                             |
| `--gnome-space-5`  | 36px  | Dialog / page padding                       |
| `--gnome-space-6`  | 48px  | Large layout gaps                           |

---

## 5. Border Radius

| Token                  | Value    | Use case                          |
|------------------------|----------|-----------------------------------|
| `--gnome-radius-sm`    | 4px      | Small inline elements             |
| `--gnome-radius-md`    | 8px      | **Default** (buttons, inputs…)    |
| `--gnome-radius-lg`    | 12px     | Cards, popovers, dialogs          |
| `--gnome-radius-xl`    | 15px     | Windows                           |
| `--gnome-radius-pill`  | 9999px   | Pill buttons, circular buttons    |

---

## 6. Shadows

| Token                | Use case                       |
|----------------------|--------------------------------|
| `--gnome-shadow-sm`  | Subtle elevation (buttons)     |
| `--gnome-shadow-md`  | Popovers, dropdowns            |
| `--gnome-shadow-lg`  | Dialogs, floating windows      |

---

## 7. Transitions

| Token                     | Value  |
|---------------------------|--------|
| `--gnome-duration-fast`   | 100ms  |
| `--gnome-duration-normal` | 200ms  |
| `--gnome-duration-slow`   | 400ms  |
| `--gnome-easing-default`  | `cubic-bezier(0.25, 0.46, 0.45, 0.94)` |

Use `fast` for hover/active state changes. Use `normal` for appearing/disappearing elements.

---

## 8. Component Patterns

### 8.1 Buttons

| Variant       | When to use                                               |
|---------------|-----------------------------------------------------------|
| `default`     | Standard actions with no particular priority              |
| `suggested`   | The single primary / affirmative action in a view         |
| `flat`        | Actions inside header bars, toolbars, or dense UIs        |
| `destructive` | Irreversible or dangerous actions (Delete, Format…)       |

**Rules:**
- Use at most **one `suggested` button** per window/view.
- Use at most **one `destructive` button** per dialog.
- Labels must be **imperative verbs** with Header Capitalization.
- Avoid mixing icon + label on buttons outside header bars.
- Place **affirmative actions on the right**, cancel on the left (dialogs).

### 8.2 Forms & Inputs

- Group related controls with clear labels above or to the left.
- Use `12px` horizontal gap between label and its input.
- Show validation feedback inline, immediately after the control.

### 8.3 Dialogs

- Keep dialogs focused on a **single task**.
- Include a title, optional body text, and a button row.
- Button order: **[Cancel] [Destructive] [Suggested]** (left → right).
- Do not open dialogs from dialogs.

### 8.4 Header Bars

- Use `flat` buttons in header bars.
- Keep the title centered and concise.
- Place primary navigation controls (back, menu) on the left; secondary actions on the right.

---

## 9. Accessibility

- All interactive elements must be **keyboard navigable** (Tab, Enter, Space, Escape).
- Provide `aria-label` for icon-only buttons.
- Focus ring must be clearly visible (`--gnome-focus-ring-width: 3px`).
- Do not rely on color alone to convey meaning.
- Test with a screen reader (Orca on GNOME) and the `@storybook/addon-a11y` panel.

---

## 10. Dark Mode

Components must respond to `@media (prefers-color-scheme: dark)` automatically via the tokens defined in `tokens.css`. No additional logic needed in component code — simply reference CSS custom properties.

```css
/* ✅ correct — adapts automatically */
color: var(--gnome-window-fg-color);

/* ❌ wrong — breaks dark mode */
color: rgba(0, 0, 0, 0.8);
```

---

## 11. File & Component Conventions

```
src/
  components/
    ComponentName/
      ComponentName.tsx        # Component implementation
      ComponentName.module.css # Scoped styles (CSS Modules)
      ComponentName.stories.tsx # Storybook stories
      index.ts                 # Re-exports
  styles/
    tokens.css                 # All design tokens (single source of truth)
  index.ts                     # Library public API
```

- One component per directory.
- CSS Modules for all component styles — no global class names.
- All design values (color, spacing, radius…) **must** come from `tokens.css` variables.
- Props interface must be exported and documented with JSDoc.
- Every component must have a Storybook story with `autodocs` tag.

---

Source: ARCHITECTURE.md

# Architecture — @gnome-ui

This document describes the package dependency graph and the role of each workspace in the monorepo.

## Package dependency graph

```mermaid
graph TD
  GNOME["🖥️ GNOME / GJS runtime\nGSettings · Gio · Gtk · Notifications\nXDG Portals · GDK Clipboard"]

  subgraph "gnome-ui monorepo"
    CORE["@gnome-ui/core\nDesign tokens · CSS variables\n(Adwaita colours, radii, typography)"]
    ICONS["@gnome-ui/icons\nSVG icon components"]
    PLATFORM["@gnome-ui/platform\nTypeScript API layer\nsettings · notifications · fileChooser\ncolorScheme · window · portals · clipboard"]
    HOOKS["@gnome-ui/hooks\nReact hooks\nuseSettings · useNotification · useColorScheme\nuseFileChooser · useClipboard · useWindowState"]
    REACT["@gnome-ui/react\nUI components\n(Button, Dialog, Sidebar, …)"]
    CHARTS["@gnome-ui/charts\nChart components\n(AreaChart, BarChart, LineChart)"]
    WEB_COMPONENTS["@gnome-ui/web-components\nNative Custom Elements\n(Dialog, Toast, Popover)"]
  end

  APP["Your App (React, HTML, or htmx)"]

  GNOME -->|WebKit bridge / XDG Portals| PLATFORM
  PLATFORM --> HOOKS
  CORE --> REACT
  CORE --> CHARTS
  CORE --> HOOKS
  CORE --> WEB_COMPONENTS
  ICONS --> REACT
  REACT --> APP
  CHARTS --> APP
  HOOKS --> APP
  WEB_COMPONENTS --> APP
```

## Package roles

| Package | Role | React? | GNOME runtime? |
|---------|------|--------|----------------|
| `@gnome-ui/core` | Design tokens, CSS custom properties | No | No |
| `@gnome-ui/icons` | SVG icon components | Yes | No |
| `@gnome-ui/platform` | Low-level TypeScript bridge to GNOME APIs | No | Yes |
| `@gnome-ui/hooks` | React hooks that surface `platform` APIs | Yes | Via platform |
| `@gnome-ui/react` | Full Adwaita UI component library | Yes | No |
| `@gnome-ui/charts` | Recharts-based chart components styled with Adwaita tokens | Yes | No |
| `@gnome-ui/web-components` | Native, light-DOM Custom Elements for framework-agnostic apps | No | No |

## Communication model

`@gnome-ui/platform` communicates with the GNOME host process through one of two mechanisms, resolved at runtime:

```
┌─────────────────────────────────────────────────┐
│  React App (WebKitGTK WebView or browser)        │
│                                                   │
│  @gnome-ui/platform                              │
│       │                                           │
│       ├─ WebKit bridge  ──► window.webkit         │
│       │   (GJS host)        .messageHandlers.*    │
│       │                                           │
│       └─ XDG Portals    ──► org.freedesktop.*     │
│           (Flatpak /        via postMessage /      │
│            browser)         fetch proxy            │
└─────────────────────────────────────────────────┘
```

When neither bridge is available (unit tests, standard browsers) every call falls back to a no-op stub so the application renders without crashing.

## Build order

```
@gnome-ui/core  →  @gnome-ui/platform  →  @gnome-ui/hooks
                →  @gnome-ui/icons     →  @gnome-ui/react
                                        →  @gnome-ui/charts
                →  @gnome-ui/web-components
```

`@gnome-ui/hooks` depends on both `@gnome-ui/platform` (runtime) and `@gnome-ui/core` (tokens for any bundled UI).

---

Source: packages/core/README.md

# @gnome-ui/core

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

Framework-agnostic CSS design tokens for the GNOME UI design system, based on the [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/) and the [Adwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/css-variables.html) design language.

[![npm](https://img.shields.io/npm/v/@gnome-ui/core)](https://www.npmjs.com/package/@gnome-ui/core)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

## Installation

```bash
npm install @gnome-ui/core
```

## Usage

Import the tokens once at the root of your app:

```css
@import "@gnome-ui/core/styles";
```

```js
import "@gnome-ui/core/styles";
```

All tokens are then available as CSS custom properties:

```css
.my-button {
  background-color: var(--gnome-accent-bg-color);
  color: var(--gnome-accent-fg-color);
  border-radius: var(--gnome-radius-md);
  font-family: var(--gnome-font-family);
  padding: var(--gnome-space-1) var(--gnome-space-2);
}
```

Dark mode is handled automatically via `@media (prefers-color-scheme: dark)`.

## Token reference

### Colors

| Token | Light | Dark |
|-------|-------|------|
| `--gnome-accent-color` | `#3584e4` | `#78aeed` |
| `--gnome-accent-bg-color` | `#3584e4` | `#3584e4` |
| `--gnome-accent-fg-color` | `#ffffff` | `#ffffff` |
| `--gnome-destructive-bg-color` | `#e01b24` | `#e01b24` |
| `--gnome-destructive-fg-color` | `#ffffff` | `#ffffff` |
| `--gnome-success-bg-color` | `#2ec27e` | `#2ec27e` |
| `--gnome-warning-bg-color` | `#f6d32d` | `#f6d32d` |
| `--gnome-window-bg-color` | `#fafafa` | `#242424` |
| `--gnome-window-fg-color` | `rgba(0,0,0,.8)` | `rgba(255,255,255,.87)` |
| `--gnome-card-bg-color` | `#ffffff` | `#383838` |
| `--gnome-headerbar-bg-color` | `#ebebeb` | `#303030` |

### Spacing (6 px grid)

| Token | Value |
|-------|-------|
| `--gnome-space-1` | `6px` |
| `--gnome-space-2` | `12px` |
| `--gnome-space-3` | `18px` |
| `--gnome-space-4` | `24px` |
| `--gnome-space-5` | `36px` |
| `--gnome-space-6` | `48px` |

### Border radius

| Token | Value | Use |
|-------|-------|-----|
| `--gnome-radius-sm` | `4px` | Small elements |
| `--gnome-radius-md` | `8px` | Default (buttons, inputs) |
| `--gnome-radius-lg` | `12px` | Cards, popovers |
| `--gnome-radius-xl` | `15px` | Windows |
| `--gnome-radius-pill` | `9999px` | Pill/circular buttons |

### Typography

| Token | Value |
|-------|-------|
| `--gnome-font-family` | `"Adwaita Sans", Cantarell, "Inter", system-ui, sans-serif` |
| `--gnome-font-size-large-title` | `2.25rem` |
| `--gnome-font-size-title-1` | `1.875rem` |
| `--gnome-font-size-title-2` | `1.5rem` |
| `--gnome-font-size-title-3` | `1.25rem` |
| `--gnome-font-size-title-4` | `1.125rem` |
| `--gnome-font-size-body` | `1rem` |
| `--gnome-font-size-caption` | `0.75rem` |
| `--gnome-font-weight-normal` | `400` |
| `--gnome-font-weight-semibold` | `600` |
| `--gnome-font-weight-bold` | `700` |

### Focus ring

| Token | Value |
|-------|-------|
| `--gnome-focus-ring-color` | `var(--gnome-accent-color)` |
| `--gnome-focus-ring-width` | `3px` |
| `--gnome-focus-ring-offset` | `2px` |

### Motion

| Token | Value |
|-------|-------|
| `--gnome-duration-fast` | `100ms` |
| `--gnome-duration-normal` | `200ms` |
| `--gnome-duration-slow` | `400ms` |
| `--gnome-easing-default` | `cubic-bezier(0.25, 0.46, 0.45, 0.94)` |
| `--gnome-easing-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` |

### Shadows

| Token | Use |
|-------|-----|
| `--gnome-shadow-sm` | Subtle card/button shadow |
| `--gnome-shadow-md` | Popovers, dropdowns |
| `--gnome-shadow-lg` | Dialogs, modals |

### Layout

| Token | Value | Use |
|-------|-------|-----|
| `--gnome-layout-sidebar-min-width` | `180px` | Minimum GNOME sidebar width |
| `--gnome-layout-sidebar-default-width` | `240px` | Default standalone sidebar width |
| `--gnome-layout-sidebar-max-width` | `280px` | Maximum GNOME sidebar width |
| `--gnome-layout-sidebar-width` | `clamp(180px, 25%, 280px)` | Standard in-flow sidebar width |
| `--gnome-layout-sidebar-overlay-width` | `clamp(180px, 75%, 280px)` | Overlay sidebar width on narrow screens |
| `--gnome-layout-sidebar-rail-width` | `56px` | Collapsed icon-only sidebar rail |
| `--gnome-layout-breakpoint-narrow` | `400px` | Split-view collapse threshold |
| `--gnome-layout-breakpoint-medium` | `550px` | Bottom-navigation / compact shell threshold |
| `--gnome-layout-breakpoint-wide` | `860px` | Nested-layout outer-pane threshold |
| `--gnome-layout-content-padding` | `var(--gnome-space-4)` | Default page content padding |
| `--gnome-layout-content-padding-compact` | `var(--gnome-space-2)` | Compact page content padding |
| `--gnome-layout-content-padding-spacious` | `var(--gnome-space-5)` | Spacious page content padding |

The breakpoint tokens document the shared GNOME thresholds. CSS media queries
still use literal pixel values because custom properties are not valid in
standard `@media` conditions.

### Misc

| Token | Value |
|-------|-------|
| `--gnome-opacity-disabled` | `0.5` |

## License

[MIT](../../LICENSE)

---

Source: packages/icons/README.md

# @gnome-ui/icons

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

Framework-agnostic icon definitions for the [gnome-ui](https://github.com/ElJijuna/gnome-ui) design system.

Each icon is a plain JavaScript object (`IconDefinition`) containing SVG path data — no DOM, no React, no styles. UI framework adapters consume this shape to render inline SVGs.

The `Icon` React adapter also accepts icons from [`simple-icons`](https://simpleicons.org/) directly, without any conversion.

[![npm](https://img.shields.io/npm/v/@gnome-ui/icons)](https://www.npmjs.com/package/@gnome-ui/icons)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

## Installation

```bash
npm install @gnome-ui/icons
```

## Tree-shaking

This package is fully tree-shakeable. Importing a single icon only pulls that icon's module into your bundle — not the entire registry.

```ts
// Only `Add` and `Search` are included in the final bundle
import { Add, Search } from "@gnome-ui/icons";
```

Each icon is also available as a direct sub-path import for bundlers that prefer explicit paths:

```ts
import { Add } from "@gnome-ui/icons/icons";
import { GitHub } from "@gnome-ui/icons/third-party";
```

## Usage

### With `@gnome-ui/react`

```tsx
import { Icon } from "@gnome-ui/react";
import { Search, Settings, GoHome } from "@gnome-ui/icons";

<Icon icon={Search} size="md" aria-label="Search" />
<Icon icon={Settings} size="lg" aria-hidden />
```

### With `simple-icons`

The `Icon` component accepts any `simple-icons` icon directly — no adapter or conversion needed. `simple-icons` is not a dependency of this package; install it separately in your project.

```tsx
import { Icon } from "@gnome-ui/react";
import { siGithub, siNpm } from "simple-icons";

<Icon icon={siGithub} label="GitHub" />
<Icon icon={siNpm} size="lg" label="npm" />
```

You can also pass a plain `{ path }` object for any single-path SVG icon:

```tsx
import { Icon } from "@gnome-ui/react";

<Icon icon={{ path: "M12 0C5.37 0 0 5.37 0 12s5.37 12 12 12..." }} label="My icon" />
// Custom viewBox (defaults to "0 0 24 24"):
<Icon icon={{ path: "M0 0h32v32H0z", viewBox: "0 0 32 32" }} />
```

### Framework-agnostic (raw SVG)

```ts
import { Search } from "@gnome-ui/icons";
import type { IconDefinition } from "@gnome-ui/icons";

function renderIcon(icon: IconDefinition, size = 16) {
  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
  svg.setAttribute("viewBox", icon.viewBox);
  svg.setAttribute("width", String(size));
  svg.setAttribute("height", String(size));
  svg.setAttribute("fill", "currentColor");

  for (const path of icon.paths) {
    const el = document.createElementNS("http://www.w3.org/2000/svg", "path");
    el.setAttribute("d", path.d);
    if (path.fillRule) el.setAttribute("fill-rule", path.fillRule);
    if (path.clipRule) el.setAttribute("clip-rule", path.clipRule);
    svg.appendChild(el);
  }
  return svg;
}
```

### Animated icons

A handful of icons carry a small CSS animation instead of (or in addition to)
static path data — `animated: true`, with the SVG markup in `svg` instead of
`paths`. This mirrors GTK 4.22's `GtkSvg`: trusted, package-authored SVG (not
arbitrary user content) that can include `<style>`/`<animate>` structure a
flat path list can't express.

Rendered through plain `<Icon>`, animated icons are inert — they show a
static frame, matching how every other icon behaves by default. Wrap them in
`<AnimatedIcon>` (from `@gnome-ui/react`) to play the animation; it exposes a
`playing` prop and always enforces `prefers-reduced-motion`, regardless of
what `playing` is set to.

```tsx
import { Syncing } from "@gnome-ui/icons";
import { AnimatedIcon } from "@gnome-ui/react";

<AnimatedIcon icon={Syncing} playing={isSyncing} label="Syncing" />
```

| Export | Use case |
|--------|----------|
| `Syncing` | Sync in progress (animated `Refresh`) |
| `Recording` | Active recording (animated `MediaRecord`) |
| `Downloading` | Active download (animated arrow into a tray) |
| `Connecting` | Acquiring a connection (animated `NetworkWirelessAcquiring`) |

## Types

```ts
/** Icons from @gnome-ui/icons — multi-path, fixed viewBox, or raw animated SVG. */
interface IconDefinition {
  readonly viewBox: string;
  readonly paths?: ReadonlyArray<{
    readonly d: string;
    readonly fillRule?: "nonzero" | "evenodd" | "inherit";
    readonly clipRule?: "nonzero" | "evenodd" | "inherit";
    readonly transform?: string;
  }>;
  /** Raw trusted SVG markup, used instead of `paths` for animated icons. */
  readonly svg?: string;
  /** Marks the icon as carrying a CSS animation in `svg`. */
  readonly animated?: boolean;
}

/** Single-path icons from simple-icons or any { path } object. */
interface RawPathIconDefinition {
  readonly path: string;
  readonly viewBox?: string; // defaults to "0 0 24 24"
}

/** Union accepted by the Icon component. */
type AnyIconDefinition = IconDefinition | RawPathIconDefinition;
```

## Available icons

Most icons are Adwaita symbolic or Adwaita-style convenience glyphs — monochrome, `currentColor`-based, 16 × 16 viewBox.
Version Control icons follow GitHub Octicons and use a 24 × 24 viewBox.
Adwaita fullcolor assets are not bundled in this package yet; brand icons are listed separately under Third-party.

The full Adwaita symbolic set is exported from both `@gnome-ui/icons` and `@gnome-ui/icons/icons`, alongside the curated convenience names.

### Navigation

| Export | Symbolic name |
|--------|--------------|
| `GoPrevious` | `go-previous-symbolic` |
| `GoNext` | `go-next-symbolic` |
| `GoHome` | `go-home-symbolic` |
| `GoUp` | `go-up-symbolic` |
| `PanDown` | `pan-down-symbolic` |
| `PanUp` | `pan-up-symbolic` |
| `PanStart` | `pan-start-symbolic` |
| `PanEnd` | `pan-end-symbolic` |

### Actions

| Export | Symbolic name |
|--------|--------------|
| `Add` | `list-add-symbolic` |
| `Remove` | `list-remove-symbolic` |
| `Delete` | `edit-delete-symbolic` |
| `Edit` | `document-edit-symbolic` |
| `Copy` | `edit-copy-symbolic` |
| `Paste` | `edit-paste-symbolic` |
| `Cut` | `edit-cut-symbolic` |
| `Undo` | `edit-undo-symbolic` |
| `Redo` | `edit-redo-symbolic` |
| `Save` | `document-save-symbolic` |
| `Document` | Adwaita-style document glyph |
| `DocumentOpen` | `document-open-symbolic` |
| `Close` | `window-close-symbolic` |
| `Search` | `system-search-symbolic` |
| `Refresh` | `view-refresh-symbolic` |
| `Share` | Adwaita-style share glyph |
| `Attachment` | `mail-attachment-symbolic` |

### UI

| Export | Symbolic name |
|--------|--------------|
| `OpenMenu` | `open-menu-symbolic` |
| `ViewMore` | `view-more-symbolic` |
| `ViewSidebar` | `sidebar-show-symbolic` |
| `ViewReveal` | `view-reveal-symbolic` |
| `ViewConceal` | `view-conceal-symbolic` |
| `Settings` | `preferences-system-symbolic` |

### Status

| Export | Symbolic name |
|--------|--------------|
| `Information` | `dialog-information-symbolic` |
| `Warning` | `dialog-warning-symbolic` |
| `Error` | `dialog-error-symbolic` |
| `Check` | `object-select-symbolic` |

### People & Identity

| Export | Symbolic name |
|--------|--------------|
| `Person` | `system-users-symbolic` |
| `Accessibility` | `preferences-desktop-accessibility-symbolic` |

### System & Hardware

| Export | Symbolic name |
|--------|--------------|
| `Applications` | `view-app-grid-symbolic` |
| `Notifications` | Adwaita-style notification glyph |
| `InputMouse` | `input-mouse-symbolic` |
| `InputKeyboard` | `input-keyboard-symbolic` |
| `InputTablet` | `input-tablet-symbolic` |
| `ColorManagement` | `preferences-color-symbolic` |
| `Printer` | `printer-symbolic` |
| `Lock` | `changes-prevent-symbolic` |

### Files & Media

| Export | Symbolic name |
|--------|--------------|
| `Folder` | `folder-symbolic` |
| `Image` | `image-x-generic-symbolic` |

### Misc

| Export | Symbolic name |
|--------|--------------|
| `Star` | `starred-symbolic` |
| `StarOutline` | `non-starred-symbolic` |
| `Heart` | Adwaita-style heart glyph |

### Media

| Export | Symbolic name |
|--------|--------------|
| `MediaPlay` | `media-playback-start-symbolic` |
| `MediaPause` | `media-playback-pause-symbolic` |
| `MediaSkipForward` | `media-skip-forward-symbolic` |
| `MediaSkipBackward` | `media-skip-backward-symbolic` |

### Version Control

| Export | Description |
|--------|-------------|
| `GitCommit` | Commit node on a branch line |
| `GitBranch` | Branch topology |
| `GitCompare` | Compare branches |
| `GitMerge` | Branch merge |
| `GitMergeQueue` | Merge queue |
| `GitFork` | Forked repository topology |
| `GitPullRequest` | Open pull request |
| `GitPullRequestClosed` | Closed pull request |
| `GitPullRequestDraft` | Draft pull request |
| `GitIssueOpened` | Open issue |
| `GitIssueClosed` | Closed issue |
| `GitIssueDraft` | Draft issue |
| `GitIssueReopened` | Reopened issue |
| `GitCodeReview` | Code review |
| `GitDiff` | Diff |
| `GitMilestone` | Milestone |
| `GitProject` | GitHub project |
| `GitWorkflow` | GitHub workflow |
| `GitRepository` | Repository |
| `GitTag` | Tag label |

### Third-party brand icons

Available via `@gnome-ui/icons` or the `@gnome-ui/icons/third-party` sub-path.

| Export | Brand |
|--------|-------|
| `GitHub` | GitHub |
| `GitLab` | GitLab |
| `Bitbucket` | Bitbucket |
| `X` | X (Twitter) |

### Complete icon list

672 icon exports are available from `@gnome-ui/icons`.

| Export | Source |
|--------|--------|
| `GoPrevious` | Navigation |
| `GoNext` | Navigation |
| `GoHome` | Navigation |
| `GoUp` | Navigation |
| `PanDown` | Navigation |
| `PanUp` | Navigation |
| `PanStart` | Navigation |
| `PanEnd` | Navigation |
| `Add` | Actions |
| `Remove` | Actions |
| `Delete` | Actions |
| `Edit` | Actions |
| `Copy` | Actions |
| `Paste` | Actions |
| `Cut` | Actions |
| `Undo` | Actions |
| `Redo` | Actions |
| `Save` | Actions |
| `DocumentOpen` | Actions |
| `Close` | Actions |
| `Search` | Actions |
| `Refresh` | Actions |
| `Share` | Actions |
| `Attachment` | Actions |
| `OpenMenu` | UI |
| `ViewMore` | UI |
| `ViewSidebar` | UI |
| `ViewReveal` | UI |
| `ViewConceal` | UI |
| `Settings` | UI |
| `Information` | Status |
| `Warning` | Status |
| `Error` | Status |
| `Check` | Status |
| `Person` | People & Identity |
| `Accessibility` | People & Identity |
| `Applications` | System & Hardware |
| `Notifications` | System & Hardware |
| `InputMouse` | System & Hardware |
| `InputKeyboard` | System & Hardware |
| `InputTablet` | System & Hardware |
| `ColorManagement` | System & Hardware |
| `Printer` | System & Hardware |
| `Lock` | System & Hardware |
| `Folder` | Files |
| `Document` | Files |
| `Image` | Files |
| `Star` | Misc |
| `StarOutline` | Misc |
| `Heart` | Misc |
| `MediaPlay` | Media |
| `MediaPause` | Media |
| `MediaSkipForward` | Media |
| `MediaSkipBackward` | Media |
| `GitCommit` | Version Control |
| `GitBranch` | Version Control |
| `GitCompare` | Version Control |
| `GitMerge` | Version Control |
| `GitMergeQueue` | Version Control |
| `GitFork` | Version Control |
| `GitPullRequest` | Version Control |
| `GitPullRequestClosed` | Version Control |
| `GitPullRequestDraft` | Version Control |
| `GitIssueOpened` | Version Control |
| `GitIssueClosed` | Version Control |
| `GitIssueDraft` | Version Control |
| `GitIssueReopened` | Version Control |
| `GitCodeReview` | Version Control |
| `GitDiff` | Version Control |
| `GitMilestone` | Version Control |
| `GitProject` | Version Control |
| `GitWorkflow` | Version Control |
| `GitRepository` | Version Control |
| `GitTag` | Version Control |
| `ActionUnavailable` | Full Adwaita Symbolic |
| `AddressBookNew` | Full Adwaita Symbolic |
| `ApplicationExitRtl` | Full Adwaita Symbolic |
| `ApplicationExit` | Full Adwaita Symbolic |
| `AppointmentNew` | Full Adwaita Symbolic |
| `BookmarkNew` | Full Adwaita Symbolic |
| `CallStart` | Full Adwaita Symbolic |
| `CallStop` | Full Adwaita Symbolic |
| `CameraSwitch` | Full Adwaita Symbolic |
| `ChatMessageNew` | Full Adwaita Symbolic |
| `ColorSelect` | Full Adwaita Symbolic |
| `ContactNew` | Full Adwaita Symbolic |
| `DocumentEdit` | Full Adwaita Symbolic |
| `DocumentNew` | Full Adwaita Symbolic |
| `DocumentOpenRecent` | Full Adwaita Symbolic |
| `DocumentPageSetup` | Full Adwaita Symbolic |
| `DocumentPrintPreview` | Full Adwaita Symbolic |
| `DocumentPrint` | Full Adwaita Symbolic |
| `DocumentProperties` | Full Adwaita Symbolic |
| `DocumentRevertRtl` | Full Adwaita Symbolic |
| `DocumentRevert` | Full Adwaita Symbolic |
| `DocumentSaveAs` | Full Adwaita Symbolic |
| `DocumentSave` | Full Adwaita Symbolic |
| `DocumentSend` | Full Adwaita Symbolic |
| `EditClearAll` | Full Adwaita Symbolic |
| `EditClearRtl` | Full Adwaita Symbolic |
| `EditClear` | Full Adwaita Symbolic |
| `EditCopy` | Full Adwaita Symbolic |
| `EditCut` | Full Adwaita Symbolic |
| `EditDelete` | Full Adwaita Symbolic |
| `EditFindReplace` | Full Adwaita Symbolic |
| `EditFind` | Full Adwaita Symbolic |
| `EditPaste` | Full Adwaita Symbolic |
| `EditRedoRtl` | Full Adwaita Symbolic |
| `EditRedo` | Full Adwaita Symbolic |
| `EditSelectAll` | Full Adwaita Symbolic |
| `EditSelect` | Full Adwaita Symbolic |
| `EditUndoRtl` | Full Adwaita Symbolic |
| `EditUndo` | Full Adwaita Symbolic |
| `ErrorCorrect` | Full Adwaita Symbolic |
| `FindLocation` | Full Adwaita Symbolic |
| `FolderNew` | Full Adwaita Symbolic |
| `FontSelect` | Full Adwaita Symbolic |
| `FormatIndentLessRtl` | Full Adwaita Symbolic |
| `FormatIndentLess` | Full Adwaita Symbolic |
| `FormatIndentMoreRtl` | Full Adwaita Symbolic |
| `FormatIndentMore` | Full Adwaita Symbolic |
| `FormatJustifyCenter` | Full Adwaita Symbolic |
| `FormatJustifyFill` | Full Adwaita Symbolic |
| `FormatJustifyLeft` | Full Adwaita Symbolic |
| `FormatJustifyRight` | Full Adwaita Symbolic |
| `FormatTextBold` | Full Adwaita Symbolic |
| `FormatTextDirectionLtr` | Full Adwaita Symbolic |
| `FormatTextDirectionRtl` | Full Adwaita Symbolic |
| `FormatTextDirection` | Full Adwaita Symbolic |
| `FormatTextItalic` | Full Adwaita Symbolic |
| `FormatTextPlaintext` | Full Adwaita Symbolic |
| `FormatTextRich` | Full Adwaita Symbolic |
| `FormatTextStrikethrough` | Full Adwaita Symbolic |
| `FormatTextUnderline` | Full Adwaita Symbolic |
| `GoBottom` | Full Adwaita Symbolic |
| `GoDown` | Full Adwaita Symbolic |
| `GoFirstRtl` | Full Adwaita Symbolic |
| `GoFirst` | Full Adwaita Symbolic |
| `GoJumpRtl` | Full Adwaita Symbolic |
| `GoJump` | Full Adwaita Symbolic |
| `GoLastRtl` | Full Adwaita Symbolic |
| `GoLast` | Full Adwaita Symbolic |
| `GoNextRtl` | Full Adwaita Symbolic |
| `GoPreviousRtl` | Full Adwaita Symbolic |
| `GoTop` | Full Adwaita Symbolic |
| `HelpAbout` | Full Adwaita Symbolic |
| `InsertImage` | Full Adwaita Symbolic |
| `InsertLink` | Full Adwaita Symbolic |
| `InsertObject` | Full Adwaita Symbolic |
| `InsertText` | Full Adwaita Symbolic |
| `ListAdd` | Full Adwaita Symbolic |
| `ListRemoveAll` | Full Adwaita Symbolic |
| `ListRemove` | Full Adwaita Symbolic |
| `MailForwardRtl` | Full Adwaita Symbolic |
| `MailForward` | Full Adwaita Symbolic |
| `MailMarkImportant` | Full Adwaita Symbolic |
| `MailMarkJunk` | Full Adwaita Symbolic |
| `MailMarkNotjunk` | Full Adwaita Symbolic |
| `MailMessageNew` | Full Adwaita Symbolic |
| `MailReplyAllRtl` | Full Adwaita Symbolic |
| `MailReplyAll` | Full Adwaita Symbolic |
| `MailReplySenderRtl` | Full Adwaita Symbolic |
| `MailReplySender` | Full Adwaita Symbolic |
| `MailSendReceive` | Full Adwaita Symbolic |
| `MailSend` | Full Adwaita Symbolic |
| `MarkLocation` | Full Adwaita Symbolic |
| `MediaEject` | Full Adwaita Symbolic |
| `MediaPlaybackPause` | Full Adwaita Symbolic |
| `MediaPlaybackStart` | Full Adwaita Symbolic |
| `MediaPlaybackStop` | Full Adwaita Symbolic |
| `MediaRecord` | Full Adwaita Symbolic |
| `MediaSeekBackwardRtl` | Full Adwaita Symbolic |
| `MediaSeekBackward` | Full Adwaita Symbolic |
| `MediaSeekForwardRtl` | Full Adwaita Symbolic |
| `MediaSeekForward` | Full Adwaita Symbolic |
| `MediaSkipBackwardRtl` | Full Adwaita Symbolic |
| `MediaSkipForwardRtl` | Full Adwaita Symbolic |
| `MediaViewSubtitles` | Full Adwaita Symbolic |
| `ObjectFlipHorizontal` | Full Adwaita Symbolic |
| `ObjectFlipVertical` | Full Adwaita Symbolic |
| `ObjectRotateLeft` | Full Adwaita Symbolic |
| `ObjectRotateRight` | Full Adwaita Symbolic |
| `ObjectSelect` | Full Adwaita Symbolic |
| `ProcessStop` | Full Adwaita Symbolic |
| `SelectionMode` | Full Adwaita Symbolic |
| `SendTo` | Full Adwaita Symbolic |
| `SidebarShowRightRtl` | Full Adwaita Symbolic |
| `SidebarShowRight` | Full Adwaita Symbolic |
| `SidebarShowRtl` | Full Adwaita Symbolic |
| `SidebarShow` | Full Adwaita Symbolic |
| `StarNew` | Full Adwaita Symbolic |
| `SystemLogOutRtl` | Full Adwaita Symbolic |
| `SystemLogOut` | Full Adwaita Symbolic |
| `SystemReboot` | Full Adwaita Symbolic |
| `SystemRun` | Full Adwaita Symbolic |
| `SystemSearch` | Full Adwaita Symbolic |
| `SystemShutdown` | Full Adwaita Symbolic |
| `SystemSwitchUserRtl` | Full Adwaita Symbolic |
| `SystemSwitchUser` | Full Adwaita Symbolic |
| `TabNew` | Full Adwaita Symbolic |
| `ToolsCheckSpelling` | Full Adwaita Symbolic |
| `ValueDecrease` | Full Adwaita Symbolic |
| `ValueIncrease` | Full Adwaita Symbolic |
| `ViewAppGrid` | Full Adwaita Symbolic |
| `ViewContinuous` | Full Adwaita Symbolic |
| `ViewDual` | Full Adwaita Symbolic |
| `ViewFullscreen` | Full Adwaita Symbolic |
| `ViewGrid` | Full Adwaita Symbolic |
| `ViewListBulletRtl` | Full Adwaita Symbolic |
| `ViewListBullet` | Full Adwaita Symbolic |
| `ViewListOrderedRtl` | Full Adwaita Symbolic |
| `ViewListOrdered` | Full Adwaita Symbolic |
| `ViewListRtl` | Full Adwaita Symbolic |
| `ViewList` | Full Adwaita Symbolic |
| `ViewMirror` | Full Adwaita Symbolic |
| `ViewMoreHorizontal` | Full Adwaita Symbolic |
| `ViewPagedRtl` | Full Adwaita Symbolic |
| `ViewPaged` | Full Adwaita Symbolic |
| `ViewPin` | Full Adwaita Symbolic |
| `ViewRefresh` | Full Adwaita Symbolic |
| `ViewRestore` | Full Adwaita Symbolic |
| `ViewSortAscendingRtl` | Full Adwaita Symbolic |
| `ViewSortAscending` | Full Adwaita Symbolic |
| `ViewSortDescendingRtl` | Full Adwaita Symbolic |
| `ViewSortDescending` | Full Adwaita Symbolic |
| `ZoomFitBest` | Full Adwaita Symbolic |
| `ZoomIn` | Full Adwaita Symbolic |
| `ZoomOriginal` | Full Adwaita Symbolic |
| `ZoomOut` | Full Adwaita Symbolic |
| `ApplicationsEngineering` | Full Adwaita Symbolic |
| `ApplicationsGames` | Full Adwaita Symbolic |
| `ApplicationsGraphics` | Full Adwaita Symbolic |
| `ApplicationsMultimedia` | Full Adwaita Symbolic |
| `ApplicationsScience` | Full Adwaita Symbolic |
| `ApplicationsSystem` | Full Adwaita Symbolic |
| `ApplicationsUtilities` | Full Adwaita Symbolic |
| `EmojiActivities` | Full Adwaita Symbolic |
| `EmojiBody` | Full Adwaita Symbolic |
| `EmojiFlags` | Full Adwaita Symbolic |
| `EmojiFood` | Full Adwaita Symbolic |
| `EmojiNature` | Full Adwaita Symbolic |
| `EmojiObjects` | Full Adwaita Symbolic |
| `EmojiPeople` | Full Adwaita Symbolic |
| `EmojiRecent` | Full Adwaita Symbolic |
| `EmojiSymbols` | Full Adwaita Symbolic |
| `EmojiTravel` | Full Adwaita Symbolic |
| `PreferencesOther` | Full Adwaita Symbolic |
| `PreferencesSystem` | Full Adwaita Symbolic |
| `SystemHelp` | Full Adwaita Symbolic |
| `AcAdapter` | Full Adwaita Symbolic |
| `AudioCard` | Full Adwaita Symbolic |
| `AudioHeadphones` | Full Adwaita Symbolic |
| `AudioHeadset` | Full Adwaita Symbolic |
| `AudioInputMicrophone` | Full Adwaita Symbolic |
| `AudioSpeakersRtl` | Full Adwaita Symbolic |
| `AudioSpeakers` | Full Adwaita Symbolic |
| `AuthFace` | Full Adwaita Symbolic |
| `AuthFingerprint` | Full Adwaita Symbolic |
| `AuthSim` | Full Adwaita Symbolic |
| `AuthSmartcard` | Full Adwaita Symbolic |
| `Battery` | Full Adwaita Symbolic |
| `Bluetooth` | Full Adwaita Symbolic |
| `CameraPhoto` | Full Adwaita Symbolic |
| `CameraVideo` | Full Adwaita Symbolic |
| `CameraWeb` | Full Adwaita Symbolic |
| `ColorimeterColorhug` | Full Adwaita Symbolic |
| `ComputerAppleIpad` | Full Adwaita Symbolic |
| `Computer` | Full Adwaita Symbolic |
| `DisplayProjector` | Full Adwaita Symbolic |
| `DriveHarddiskIeee1394` | Full Adwaita Symbolic |
| `DriveHarddiskSolidstate` | Full Adwaita Symbolic |
| `DriveHarddisk` | Full Adwaita Symbolic |
| `DriveHarddiskSystem` | Full Adwaita Symbolic |
| `DriveHarddiskUsb` | Full Adwaita Symbolic |
| `DriveMultidisk` | Full Adwaita Symbolic |
| `DriveOptical` | Full Adwaita Symbolic |
| `DriveRemovableMedia` | Full Adwaita Symbolic |
| `InputDialpad` | Full Adwaita Symbolic |
| `InputGaming` | Full Adwaita Symbolic |
| `InputTouchpad` | Full Adwaita Symbolic |
| `MediaFlash` | Full Adwaita Symbolic |
| `MediaFloppy` | Full Adwaita Symbolic |
| `MediaOpticalBd` | Full Adwaita Symbolic |
| `MediaOpticalCdAudio` | Full Adwaita Symbolic |
| `MediaOpticalCd` | Full Adwaita Symbolic |
| `MediaOpticalDvd` | Full Adwaita Symbolic |
| `MediaOptical` | Full Adwaita Symbolic |
| `MediaRemovable` | Full Adwaita Symbolic |
| `MediaTape` | Full Adwaita Symbolic |
| `MediaZip` | Full Adwaita Symbolic |
| `Modem` | Full Adwaita Symbolic |
| `MultimediaPlayerAppleIpodTouch` | Full Adwaita Symbolic |
| `MultimediaPlayer` | Full Adwaita Symbolic |
| `NetworkCellular` | Full Adwaita Symbolic |
| `NetworkWired` | Full Adwaita Symbolic |
| `NetworkWireless` | Full Adwaita Symbolic |
| `Pda` | Full Adwaita Symbolic |
| `PhoneAppleIphone` | Full Adwaita Symbolic |
| `PhoneOld` | Full Adwaita Symbolic |
| `Phone` | Full Adwaita Symbolic |
| `PrinterNetwork` | Full Adwaita Symbolic |
| `Scanner` | Full Adwaita Symbolic |
| `Tablet` | Full Adwaita Symbolic |
| `Thunderbolt` | Full Adwaita Symbolic |
| `Tv` | Full Adwaita Symbolic |
| `UninterruptiblePowerSupply` | Full Adwaita Symbolic |
| `VideoDisplay` | Full Adwaita Symbolic |
| `VideoJoinedDisplays` | Full Adwaita Symbolic |
| `VideoSingleDisplay` | Full Adwaita Symbolic |
| `EmoteLove` | Full Adwaita Symbolic |
| `FaceAngel` | Full Adwaita Symbolic |
| `FaceAngry` | Full Adwaita Symbolic |
| `FaceConfused` | Full Adwaita Symbolic |
| `FaceCool` | Full Adwaita Symbolic |
| `FaceCrying` | Full Adwaita Symbolic |
| `FaceDevilish` | Full Adwaita Symbolic |
| `FaceEmbarrassed` | Full Adwaita Symbolic |
| `FaceGlasses` | Full Adwaita Symbolic |
| `FaceKiss` | Full Adwaita Symbolic |
| `FaceLaugh` | Full Adwaita Symbolic |
| `FaceMonkey` | Full Adwaita Symbolic |
| `FacePlain` | Full Adwaita Symbolic |
| `FaceRaspberry` | Full Adwaita Symbolic |
| `FaceSad` | Full Adwaita Symbolic |
| `FaceShutmouth` | Full Adwaita Symbolic |
| `FaceSick` | Full Adwaita Symbolic |
| `FaceSmileBig` | Full Adwaita Symbolic |
| `FaceSmile` | Full Adwaita Symbolic |
| `FaceSmirk` | Full Adwaita Symbolic |
| `FaceSurprise` | Full Adwaita Symbolic |
| `FaceTired` | Full Adwaita Symbolic |
| `FaceUncertain` | Full Adwaita Symbolic |
| `FaceWink` | Full Adwaita Symbolic |
| `FaceWorried` | Full Adwaita Symbolic |
| `FaceYawn` | Full Adwaita Symbolic |
| `AccessoriesCalculator` | Full Adwaita Symbolic |
| `AccessoriesCharacterMap` | Full Adwaita Symbolic |
| `AccessoriesDictionary` | Full Adwaita Symbolic |
| `AccessoriesTextEditor` | Full Adwaita Symbolic |
| `AppletsScreenshooter` | Full Adwaita Symbolic |
| `BatteryCautionCharging` | Full Adwaita Symbolic |
| `BatteryEmptyCharging` | Full Adwaita Symbolic |
| `BatteryEmpty` | Full Adwaita Symbolic |
| `BatteryFullCharged` | Full Adwaita Symbolic |
| `BatteryFullCharging` | Full Adwaita Symbolic |
| `BatteryFull` | Full Adwaita Symbolic |
| `BatteryGoodCharging` | Full Adwaita Symbolic |
| `BatteryGood` | Full Adwaita Symbolic |
| `BatteryLowCharging` | Full Adwaita Symbolic |
| `EmblemImportant` | Full Adwaita Symbolic |
| `EmblemSystem` | Full Adwaita Symbolic |
| `GnomePowerManager` | Full Adwaita Symbolic |
| `GoaPanel` | Full Adwaita Symbolic |
| `HelpBrowser` | Full Adwaita Symbolic |
| `HelpContents` | Full Adwaita Symbolic |
| `HelpFaq` | Full Adwaita Symbolic |
| `MultimediaVolumeControl` | Full Adwaita Symbolic |
| `PreferencesColor` | Full Adwaita Symbolic |
| `PreferencesDesktopAccessibility` | Full Adwaita Symbolic |
| `PreferencesDesktopAppearance` | Full Adwaita Symbolic |
| `PreferencesDesktopApps` | Full Adwaita Symbolic |
| `PreferencesDesktopDisplay` | Full Adwaita Symbolic |
| `PreferencesDesktopFont` | Full Adwaita Symbolic |
| `PreferencesDesktopKeyboardShortcuts` | Full Adwaita Symbolic |
| `PreferencesDesktopKeyboard` | Full Adwaita Symbolic |
| `PreferencesDesktopLocale` | Full Adwaita Symbolic |
| `PreferencesDesktopMultitasking` | Full Adwaita Symbolic |
| `PreferencesDesktopRemoteDesktop` | Full Adwaita Symbolic |
| `PreferencesDesktopScreensaver` | Full Adwaita Symbolic |
| `PreferencesDesktopWallpaper` | Full Adwaita Symbolic |
| `PreferencesSystemDetails` | Full Adwaita Symbolic |
| `PreferencesSystemDevices` | Full Adwaita Symbolic |
| `PreferencesSystemNetworkProxy` | Full Adwaita Symbolic |
| `PreferencesSystemNetwork` | Full Adwaita Symbolic |
| `PreferencesSystemNotifications` | Full Adwaita Symbolic |
| `PreferencesSystemParentalControls` | Full Adwaita Symbolic |
| `PreferencesSystemPrivacy` | Full Adwaita Symbolic |
| `PreferencesSystemSearch` | Full Adwaita Symbolic |
| `PreferencesSystemSharing` | Full Adwaita Symbolic |
| `PreferencesSystemTime` | Full Adwaita Symbolic |
| `SystemFileManager` | Full Adwaita Symbolic |
| `SystemSoftwareInstall` | Full Adwaita Symbolic |
| `SystemUsers` | Full Adwaita Symbolic |
| `TextEditor` | Full Adwaita Symbolic |
| `UserInfo` | Full Adwaita Symbolic |
| `UtilitiesTerminal` | Full Adwaita Symbolic |
| `WebBrowser` | Full Adwaita Symbolic |
| `ApplicationCertificate` | Full Adwaita Symbolic |
| `ApplicationRssPlusXml` | Full Adwaita Symbolic |
| `ApplicationXAddon` | Full Adwaita Symbolic |
| `ApplicationXAppliance` | Full Adwaita Symbolic |
| `ApplicationXExecutable` | Full Adwaita Symbolic |
| `ApplicationXFirmware` | Full Adwaita Symbolic |
| `ApplicationXSharedlib` | Full Adwaita Symbolic |
| `AudioXGeneric` | Full Adwaita Symbolic |
| `FontXGeneric` | Full Adwaita Symbolic |
| `ImageXGeneric` | Full Adwaita Symbolic |
| `InodeDirectory` | Full Adwaita Symbolic |
| `PackageXGeneric` | Full Adwaita Symbolic |
| `TextXGeneric` | Full Adwaita Symbolic |
| `VideoXGeneric` | Full Adwaita Symbolic |
| `XOfficeAddressBook` | Full Adwaita Symbolic |
| `XOfficeCalendar` | Full Adwaita Symbolic |
| `XOfficeDocument` | Full Adwaita Symbolic |
| `XOfficeDrawing` | Full Adwaita Symbolic |
| `XOfficePresentation` | Full Adwaita Symbolic |
| `XOfficeSpreadsheet` | Full Adwaita Symbolic |
| `FolderDocuments` | Full Adwaita Symbolic |
| `FolderDownload` | Full Adwaita Symbolic |
| `FolderMusic` | Full Adwaita Symbolic |
| `FolderPictures` | Full Adwaita Symbolic |
| `FolderProjects` | Full Adwaita Symbolic |
| `FolderPublicshare` | Full Adwaita Symbolic |
| `FolderRemote` | Full Adwaita Symbolic |
| `FolderSavedSearch` | Full Adwaita Symbolic |
| `FolderTemplates` | Full Adwaita Symbolic |
| `FolderVideos` | Full Adwaita Symbolic |
| `NetworkServer` | Full Adwaita Symbolic |
| `NetworkWorkgroup` | Full Adwaita Symbolic |
| `StartHere` | Full Adwaita Symbolic |
| `UserBookmarks` | Full Adwaita Symbolic |
| `UserDesktop` | Full Adwaita Symbolic |
| `UserHome` | Full Adwaita Symbolic |
| `UserTrash` | Full Adwaita Symbolic |
| `AirplaneModeDisabled` | Full Adwaita Symbolic |
| `AirplaneMode` | Full Adwaita Symbolic |
| `Alarm` | Full Adwaita Symbolic |
| `AppointmentMissed` | Full Adwaita Symbolic |
| `AppointmentSoon` | Full Adwaita Symbolic |
| `AudioVolumeHighRtl` | Full Adwaita Symbolic |
| `AudioVolumeHigh` | Full Adwaita Symbolic |
| `AudioVolumeLowRtl` | Full Adwaita Symbolic |
| `AudioVolumeLow` | Full Adwaita Symbolic |
| `AudioVolumeMediumRtl` | Full Adwaita Symbolic |
| `AudioVolumeMedium` | Full Adwaita Symbolic |
| `AudioVolumeMutedRtl` | Full Adwaita Symbolic |
| `AudioVolumeMuted` | Full Adwaita Symbolic |
| `AudioVolumeOveramplifiedRtl` | Full Adwaita Symbolic |
| `AudioVolumeOveramplified` | Full Adwaita Symbolic |
| `AuthSimLocked` | Full Adwaita Symbolic |
| `AuthSimMissing` | Full Adwaita Symbolic |
| `AvatarDefault` | Full Adwaita Symbolic |
| `BatteryAction` | Full Adwaita Symbolic |
| `BatteryCaution` | Full Adwaita Symbolic |
| `BatteryLevel0Charging` | Full Adwaita Symbolic |
| `BatteryLevel0PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel0` | Full Adwaita Symbolic |
| `BatteryLevel10Charging` | Full Adwaita Symbolic |
| `BatteryLevel10PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel10` | Full Adwaita Symbolic |
| `BatteryLevel100Charged` | Full Adwaita Symbolic |
| `BatteryLevel100PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel100` | Full Adwaita Symbolic |
| `BatteryLevel20Charging` | Full Adwaita Symbolic |
| `BatteryLevel20PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel20` | Full Adwaita Symbolic |
| `BatteryLevel30Charging` | Full Adwaita Symbolic |
| `BatteryLevel30PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel30` | Full Adwaita Symbolic |
| `BatteryLevel40Charging` | Full Adwaita Symbolic |
| `BatteryLevel40PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel40` | Full Adwaita Symbolic |
| `BatteryLevel50Charging` | Full Adwaita Symbolic |
| `BatteryLevel50PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel50` | Full Adwaita Symbolic |
| `BatteryLevel60Charging` | Full Adwaita Symbolic |
| `BatteryLevel60PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel60` | Full Adwaita Symbolic |
| `BatteryLevel70Charging` | Full Adwaita Symbolic |
| `BatteryLevel70PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel70` | Full Adwaita Symbolic |
| `BatteryLevel80Charging` | Full Adwaita Symbolic |
| `BatteryLevel80PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel80` | Full Adwaita Symbolic |
| `BatteryLevel90Charging` | Full Adwaita Symbolic |
| `BatteryLevel90PluggedIn` | Full Adwaita Symbolic |
| `BatteryLevel90` | Full Adwaita Symbolic |
| `BatteryLow` | Full Adwaita Symbolic |
| `BatteryMissing` | Full Adwaita Symbolic |
| `BluetoothAcquiring` | Full Adwaita Symbolic |
| `BluetoothActive` | Full Adwaita Symbolic |
| `BluetoothDisabled` | Full Adwaita Symbolic |
| `BluetoothDisconnected` | Full Adwaita Symbolic |
| `BluetoothHardwareDisabled` | Full Adwaita Symbolic |
| `CallIncoming` | Full Adwaita Symbolic |
| `CallMissed` | Full Adwaita Symbolic |
| `CallOutgoing` | Full Adwaita Symbolic |
| `CameraDisabled` | Full Adwaita Symbolic |
| `CameraHardwareDisabled` | Full Adwaita Symbolic |
| `ChangesAllow` | Full Adwaita Symbolic |
| `ChangesPrevent` | Full Adwaita Symbolic |
| `ChannelInsecure` | Full Adwaita Symbolic |
| `ChannelSecure` | Full Adwaita Symbolic |
| `ComputerFail` | Full Adwaita Symbolic |
| `ContentLoading` | Full Adwaita Symbolic |
| `DaytimeSunrise` | Full Adwaita Symbolic |
| `DaytimeSunset` | Full Adwaita Symbolic |
| `DialogError` | Full Adwaita Symbolic |
| `DialogInformation` | Full Adwaita Symbolic |
| `DialogPassword` | Full Adwaita Symbolic |
| `DialogQuestion` | Full Adwaita Symbolic |
| `DialogWarning` | Full Adwaita Symbolic |
| `DisplayBrightness` | Full Adwaita Symbolic |
| `FolderDragAccept` | Full Adwaita Symbolic |
| `FolderOpen` | Full Adwaita Symbolic |
| `FolderVisiting` | Full Adwaita Symbolic |
| `ImageLoading` | Full Adwaita Symbolic |
| `ImageMissing` | Full Adwaita Symbolic |
| `KeyboardBrightness` | Full Adwaita Symbolic |
| `LocationServicesActive` | Full Adwaita Symbolic |
| `LocationServicesDisabled` | Full Adwaita Symbolic |
| `MailAttachment` | Full Adwaita Symbolic |
| `MailRead` | Full Adwaita Symbolic |
| `MailRepliedRtl` | Full Adwaita Symbolic |
| `MailReplied` | Full Adwaita Symbolic |
| `MailUnread` | Full Adwaita Symbolic |
| `MediaPlaylistConsecutive` | Full Adwaita Symbolic |
| `MediaPlaylistRepeatSong` | Full Adwaita Symbolic |
| `MediaPlaylistRepeat` | Full Adwaita Symbolic |
| `MediaPlaylistShuffle` | Full Adwaita Symbolic |
| `MicrophoneDisabled` | Full Adwaita Symbolic |
| `MicrophoneHardwareDisabled` | Full Adwaita Symbolic |
| `MicrophoneSensitivityHigh` | Full Adwaita Symbolic |
| `MicrophoneSensitivityLow` | Full Adwaita Symbolic |
| `MicrophoneSensitivityMedium` | Full Adwaita Symbolic |
| `MicrophoneSensitivityMuted` | Full Adwaita Symbolic |
| `NetworkCellular2g` | Full Adwaita Symbolic |
| `NetworkCellular3g` | Full Adwaita Symbolic |
| `NetworkCellular4g` | Full Adwaita Symbolic |
| `NetworkCellular5g` | Full Adwaita Symbolic |
| `NetworkCellularAcquiringRtl` | Full Adwaita Symbolic |
| `NetworkCellularAcquiring` | Full Adwaita Symbolic |
| `NetworkCellularConnected` | Full Adwaita Symbolic |
| `NetworkCellularDisabledRtl` | Full Adwaita Symbolic |
| `NetworkCellularDisabled` | Full Adwaita Symbolic |
| `NetworkCellularEdge` | Full Adwaita Symbolic |
| `NetworkCellularGprs` | Full Adwaita Symbolic |
| `NetworkCellularHardwareDisabledRtl` | Full Adwaita Symbolic |
| `NetworkCellularHardwareDisabled` | Full Adwaita Symbolic |
| `NetworkCellularHspa` | Full Adwaita Symbolic |
| `NetworkCellularNoRouteRtl` | Full Adwaita Symbolic |
| `NetworkCellularNoRoute` | Full Adwaita Symbolic |
| `NetworkCellularOfflineRtl` | Full Adwaita Symbolic |
| `NetworkCellularOffline` | Full Adwaita Symbolic |
| `NetworkCellularSignalExcellentRtl` | Full Adwaita Symbolic |
| `NetworkCellularSignalExcellent` | Full Adwaita Symbolic |
| `NetworkCellularSignalGoodRtl` | Full Adwaita Symbolic |
| `NetworkCellularSignalGood` | Full Adwaita Symbolic |
| `NetworkCellularSignalNoneRtl` | Full Adwaita Symbolic |
| `NetworkCellularSignalNone` | Full Adwaita Symbolic |
| `NetworkCellularSignalOkRtl` | Full Adwaita Symbolic |
| `NetworkCellularSignalOk` | Full Adwaita Symbolic |
| `NetworkCellularSignalWeakRtl` | Full Adwaita Symbolic |
| `NetworkCellularSignalWeak` | Full Adwaita Symbolic |
| `NetworkError` | Full Adwaita Symbolic |
| `NetworkIdle` | Full Adwaita Symbolic |
| `NetworkNoRoute` | Full Adwaita Symbolic |
| `NetworkOffline` | Full Adwaita Symbolic |
| `NetworkReceiveRtl` | Full Adwaita Symbolic |
| `NetworkReceive` | Full Adwaita Symbolic |
| `NetworkTransmitReceive` | Full Adwaita Symbolic |
| `NetworkTransmitRtl` | Full Adwaita Symbolic |
| `NetworkTransmit` | Full Adwaita Symbolic |
| `NetworkVpnAcquiring` | Full Adwaita Symbolic |
| `NetworkVpnDisabled` | Full Adwaita Symbolic |
| `NetworkVpnDisconnected` | Full Adwaita Symbolic |
| `NetworkVpnNoRoute` | Full Adwaita Symbolic |
| `NetworkVpn` | Full Adwaita Symbolic |
| `NetworkWiredAcquiring` | Full Adwaita Symbolic |
| `NetworkWiredDisconnected` | Full Adwaita Symbolic |
| `NetworkWiredNoRoute` | Full Adwaita Symbolic |
| `NetworkWirelessAcquiring` | Full Adwaita Symbolic |
| `NetworkWirelessConnected` | Full Adwaita Symbolic |
| `NetworkWirelessDisabled` | Full Adwaita Symbolic |
| `NetworkWirelessEncrypted` | Full Adwaita Symbolic |
| `NetworkWirelessHardwareDisabled` | Full Adwaita Symbolic |
| `NetworkWirelessHotspot` | Full Adwaita Symbolic |
| `NetworkWirelessNoRoute` | Full Adwaita Symbolic |
| `NetworkWirelessOffline` | Full Adwaita Symbolic |
| `NetworkWirelessSignalExcellent` | Full Adwaita Symbolic |
| `NetworkWirelessSignalGood` | Full Adwaita Symbolic |
| `NetworkWirelessSignalNone` | Full Adwaita Symbolic |
| `NetworkWirelessSignalOk` | Full Adwaita Symbolic |
| `NetworkWirelessSignalWeak` | Full Adwaita Symbolic |
| `NightLightDisabled` | Full Adwaita Symbolic |
| `NightLight` | Full Adwaita Symbolic |
| `NonStarred` | Full Adwaita Symbolic |
| `NotificationsDisabled` | Full Adwaita Symbolic |
| `OrientationLandscapeInverse` | Full Adwaita Symbolic |
| `OrientationLandscape` | Full Adwaita Symbolic |
| `OrientationPortraitLeftRtl` | Full Adwaita Symbolic |
| `OrientationPortraitLeft` | Full Adwaita Symbolic |
| `OrientationPortraitRightRtl` | Full Adwaita Symbolic |
| `OrientationPortraitRight` | Full Adwaita Symbolic |
| `PowerProfileBalanced` | Full Adwaita Symbolic |
| `PowerProfilePerformance` | Full Adwaita Symbolic |
| `PowerProfilePowerSaver` | Full Adwaita Symbolic |
| `PrinterError` | Full Adwaita Symbolic |
| `PrinterPrinting` | Full Adwaita Symbolic |
| `PrinterWarning` | Full Adwaita Symbolic |
| `RotationAllowed` | Full Adwaita Symbolic |
| `RotationLocked` | Full Adwaita Symbolic |
| `ScreenShared` | Full Adwaita Symbolic |
| `SecurityHigh` | Full Adwaita Symbolic |
| `SecurityLow` | Full Adwaita Symbolic |
| `SecurityMediumRtl` | Full Adwaita Symbolic |
| `SecurityMedium` | Full Adwaita Symbolic |
| `SemiStarredRtl` | Full Adwaita Symbolic |
| `SemiStarred` | Full Adwaita Symbolic |
| `SoftwareUpdateAvailable` | Full Adwaita Symbolic |
| `SoftwareUpdateUrgent` | Full Adwaita Symbolic |
| `Starred` | Full Adwaita Symbolic |
| `SystemLockScreen` | Full Adwaita Symbolic |
| `TaskDue` | Full Adwaita Symbolic |
| `TaskPastDue` | Full Adwaita Symbolic |
| `ThunderboltAcquiring` | Full Adwaita Symbolic |
| `TouchDisabled` | Full Adwaita Symbolic |
| `TouchpadDisabled` | Full Adwaita Symbolic |
| `UserAvailable` | Full Adwaita Symbolic |
| `UserAway` | Full Adwaita Symbolic |
| `UserBusy` | Full Adwaita Symbolic |
| `UserIdle` | Full Adwaita Symbolic |
| `UserInvisible` | Full Adwaita Symbolic |
| `UserNotTracked` | Full Adwaita Symbolic |
| `UserOffline` | Full Adwaita Symbolic |
| `UserStatusPending` | Full Adwaita Symbolic |
| `UserTrashFull` | Full Adwaita Symbolic |
| `ViewWrappedRtl` | Full Adwaita Symbolic |
| `ViewWrapped` | Full Adwaita Symbolic |
| `WeatherClearNight` | Full Adwaita Symbolic |
| `WeatherClear` | Full Adwaita Symbolic |
| `WeatherFewCloudsNight` | Full Adwaita Symbolic |
| `WeatherFewClouds` | Full Adwaita Symbolic |
| `WeatherFog` | Full Adwaita Symbolic |
| `WeatherOvercast` | Full Adwaita Symbolic |
| `WeatherSevereAlert` | Full Adwaita Symbolic |
| `WeatherShowersScattered` | Full Adwaita Symbolic |
| `WeatherShowers` | Full Adwaita Symbolic |
| `WeatherSnow` | Full Adwaita Symbolic |
| `WeatherStorm` | Full Adwaita Symbolic |
| `WeatherTornado` | Full Adwaita Symbolic |
| `WeatherWindy` | Full Adwaita Symbolic |
| `CheckboxChecked` | Full Adwaita Symbolic |
| `CheckboxMixed` | Full Adwaita Symbolic |
| `Checkbox` | Full Adwaita Symbolic |
| `FocusLegacySystray` | Full Adwaita Symbolic |
| `FocusTopBar` | Full Adwaita Symbolic |
| `FocusWindows` | Full Adwaita Symbolic |
| `ListDragHandle` | Full Adwaita Symbolic |
| `PanEndRtl` | Full Adwaita Symbolic |
| `PanStartRtl` | Full Adwaita Symbolic |
| `RadioChecked` | Full Adwaita Symbolic |
| `RadioMixed` | Full Adwaita Symbolic |
| `Radio` | Full Adwaita Symbolic |
| `SelectionEndRtl` | Full Adwaita Symbolic |
| `SelectionEnd` | Full Adwaita Symbolic |
| `SelectionStartRtl` | Full Adwaita Symbolic |
| `SelectionStart` | Full Adwaita Symbolic |
| `WindowClose` | Full Adwaita Symbolic |
| `WindowMaximize` | Full Adwaita Symbolic |
| `WindowMinimize` | Full Adwaita Symbolic |
| `WindowNew` | Full Adwaita Symbolic |
| `WindowRestore` | Full Adwaita Symbolic |
| `GitHub` | Third-party brand icons |
| `GitLab` | Third-party brand icons |
| `Bitbucket` | Third-party brand icons |
| `X` | Third-party brand icons |
| `Npm` | Third-party brand icons |
| `Syncing` | Animated |
| `Recording` | Animated |
| `Downloading` | Animated |
| `Connecting` | Animated |

## License

[MIT](../../LICENSE)

---

Source: packages/react/README.md

# @gnome-ui/react

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

React component library following the [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/), built on the [Adwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/) design language.

[![npm](https://img.shields.io/npm/v/@gnome-ui/react)](https://www.npmjs.com/package/@gnome-ui/react)
[![CI](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml)
[![Storybook](https://img.shields.io/badge/Storybook-live-ff4785?logo=storybook&logoColor=white)](https://gnome-ui.org/react/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

Live documentation: **[Storybook →](https://gnome-ui.org/react/)**

## Installation

```bash
npm install @gnome-ui/react
```

## Setup

Import the stylesheet once at the root of your app:

```tsx
// main.tsx or App.tsx
import "@gnome-ui/react/styles";
```

## Quick example

```tsx
import { Button } from "@gnome-ui/react";

export default function App() {
  return (
    <Button variant="suggested" onClick={() => console.log("saved")}>
      Save Changes
    </Button>
  );
}
```

## Provider & formatting

`GnomeProvider` supplies locale, text direction, color scheme, and default `Intl` formatting options to gnome-ui components. When `locale` is omitted, the browser locale is used.

```tsx
import { GnomeProvider } from "@gnome-ui/react";

export default function App() {
  return (
    <GnomeProvider
      locale="en-US"
      numberFormat={{ notation: "compact", compactDisplay: "short" }}
      dateTimeFormat={{ dateStyle: "medium" }}
    >
      {/* CounterCard, StatCard, charts, CountDownTimer, etc. inherit this. */}
    </GnomeProvider>
  );
}
```

Use compact notation for values like `1K`; omit `numberFormat` or set `notation: "standard"` for full values like `1,000`.

```tsx
<GnomeProvider locale="en-US" numberFormat={{ notation: "standard" }}>
  {/* numbers render as 1,000 */}
</GnomeProvider>
```

Custom components can consume the same defaults:

```tsx
import { useNumberFormatter, useDateTimeFormatter } from "@gnome-ui/react";

function Metric({ value, date }: { value: number; date: Date }) {
  const number = useNumberFormatter({ maximumFractionDigits: 1 });
  const day = useDateTimeFormatter({ weekday: "short" });

  return `${number.format(value)} · ${day.format(date)}`;
}
```

## Color scheme

Pass `colorScheme` to `GnomeProvider` to control the app theme. The provider applies the `data-theme` attribute to `document.documentElement` automatically — no manual DOM manipulation needed.

| Value | Behavior |
|-------|----------|
| `"system"` (default) | Follows the OS `prefers-color-scheme` preference |
| `"light"` | Forces light theme |
| `"dark"` | Forces dark theme |

```tsx
import { GnomeProvider } from "@gnome-ui/react";

// Controlled by user preference stored in your app state/localStorage
export default function App({ colorScheme }) {
  return (
    <GnomeProvider colorScheme={colorScheme}>
      {/* all gnome-ui components respond automatically */}
    </GnomeProvider>
  );
}
```

Consume the current scheme in any component:

```tsx
import { useColorScheme, useResolvedColorScheme } from "@gnome-ui/react";

function ThemeAwareImage() {
  const resolvedColorScheme = useResolvedColorScheme(); // "light" | "dark"

  return (
    <img src={resolvedColorScheme === "dark" ? "/logo-dark.svg" : "/logo.svg"} />
  );
}
```

- `useColorScheme()` — returns the value passed to `GnomeProvider` (`"light"`, `"dark"`, or `"system"`).
- `useResolvedColorScheme()` — always returns `"light"` or `"dark"`, resolving `"system"` against the OS preference in real time.

## Accent color

Pass `accentColor` to `GnomeProvider` to set the app-wide accent color. The provider applies the correct CSS custom properties to `document.documentElement` automatically.

Two types of values are accepted:

| Value | Behavior |
|-------|----------|
| Named palette (`"blue"`, `"green"`, `"yellow"`, `"orange"`, `"red"`, `"purple"`, `"brown"`) | Theme-aware — uses the correct shade for light/dark mode automatically. Defaults to `"blue"`. |
| Any CSS color string (`"#ff0000"`, `"oklch(…)"`, etc.) | Applied directly; same value in light and dark mode. |

```tsx
import { GnomeProvider } from "@gnome-ui/react";

export default function App({ accentColor }) {
  return (
    <GnomeProvider accentColor={accentColor}>
      {/* "green", "#a020f0", or any CSS color */}
    </GnomeProvider>
  );
}
```

Consume the accent color in any component:

```tsx
import { useAccentColor } from "@gnome-ui/react";

function AccentDot() {
  const accent = useAccentColor(); // e.g. "green" or "#ff0000"
  return <span style={{ background: accent }} />;
}
```

- `useAccentColor()` — returns the raw value passed to `GnomeProvider` (named color or CSS string).

## Tree-shaking

The package ships per-component entry points, so bundlers (webpack, Rollup, esbuild, Vite) can eliminate unused components automatically. Named imports from the root entry work with any bundler that respects `"sideEffects"`:

```tsx
// Only Button is included in the bundle
import { Button } from "@gnome-ui/react";
```

Per-component paths are also available for explicit control:

```tsx
import { Button } from "@gnome-ui/react/components/Button";
```

## Components

### Controls

| Component | Description |
|-----------|-------------|
| [`Button`](https://gnome-ui.org/react/?path=/docs/components-button--docs) | Default, Suggested, Destructive, Flat, Raised variants; `osd` overlay modifier; sm/md/lg sizes; pill and circular shapes |
| [`IconButton`](https://gnome-ui.org/react/?path=/docs/components-iconbutton--docs) | Accessible icon-only action button composed from `Button`, `Icon`, and optional `Tooltip`; supports variants, sizes, disabled state, and refs |
| [`SplitButton`](https://gnome-ui.org/react/?path=/docs/components-splitbutton--docs) | Primary action button with attached dropdown arrow; Default, Suggested, Destructive variants |
| [`ButtonContent`](https://gnome-ui.org/react/?path=/docs/components-buttoncontent--docs) | Icon + label layout helper for buttons that contain both an icon and text |
| [`Switch`](https://gnome-ui.org/react/?path=/docs/components-switch--docs) | On/off toggle for settings that apply immediately |
| [`Checkbox`](https://gnome-ui.org/react/?path=/docs/components-checkbox--docs) | Multi-selection with checked, unchecked, and indeterminate states |
| [`RadioButton`](https://gnome-ui.org/react/?path=/docs/components-radiobutton--docs) | Single-selection within a group; keyboard arrow-key navigation |
| [`TextField`](https://gnome-ui.org/react/?path=/docs/components-textfield--docs) | Text input with label, helper text, and error state |
| [`SpinButton`](https://gnome-ui.org/react/?path=/docs/components-spinbutton--docs) | Numeric input with −/+ buttons, keyboard nav, decimal support |
| [`Slider`](https://gnome-ui.org/react/?path=/docs/components-slider--docs) | Draggable range control with tick marks, decimal steps, and keyboard nav |
| [`Dropdown`](https://gnome-ui.org/react/?path=/docs/components-dropdown--docs) | Expandable option list with keyboard nav, flip positioning, and descriptions |
| [`MultiSelectDropdown`](https://gnome-ui.org/react/?path=/docs/components-multiselectdropdown--docs) | Checkbox-list variant of `Dropdown` for selecting multiple values from a single trigger |
| [`FilterableMultiSelectDropdown`](https://gnome-ui.org/react/?path=/docs/components-filterablemultiselectdropdown--docs) | `MultiSelectDropdown` plus a filter field for narrowing long option lists |
| [`FontPicker`](https://gnome-ui.org/react/?path=/docs/components-fontpicker--docs) | Button that opens a family/size/weight chooser; trigger previews the current selection rendered in that font — mirrors `GtkFontDialogButton` |
| [`EmojiPicker`](https://gnome-ui.org/react/?path=/docs/components-emojipicker--docs) | Searchable emoji grid in a `Popover`, grouped by category with a jump-to-category tab bar — mirrors `GtkEmojiChooser` |
| [`FileDropZone`](https://gnome-ui.org/react/?path=/docs/components-filedropzone--docs) | Drag-and-drop file upload target with hover/active states and a click-to-browse fallback |
| [`ScrollToTop`](https://gnome-ui.org/react/?path=/docs/components-scrolltotop--docs) | Fixed-position OSD button that scrolls to the top; auto-hides below a scroll threshold (`visible="auto"`), six anchor positions, semi-transparent until hovered |
| [`SearchBar`](https://gnome-ui.org/react/?path=/docs/components-searchbar--docs) | Collapsible search bar with auto-focus, clear button, filter row, `inline` variant, and autocomplete popover (`suggestions` / `loadingSuggestions`) |
| [`Link`](https://gnome-ui.org/react/?path=/docs/components-link--docs) | Inline hyperlink with accent colour, animated underline, and external-URL variant |
| [`ToggleGroup`](https://gnome-ui.org/react/?path=/docs/components-togglegroup--docs) / `ToggleGroupItem` | Mutually-exclusive toggle buttons; icon-only, label-only, or icon + label |
| [`InlineViewSwitcher`](https://gnome-ui.org/react/?path=/docs/components-inlineviewswitcher--docs) / `InlineViewSwitcherItem` | Compact inline view switcher; `default`, `flat`, and `round` variants |
| [`PathBar`](https://gnome-ui.org/react/?path=/docs/components-pathbar--docs) | Breadcrumb path bar for hierarchical navigation; ancestor segments are interactive buttons, current segment is highlighted |

### Display

| Component | Description |
|-----------|-------------|
| [`Text`](https://gnome-ui.org/react/?path=/docs/components-text--docs) | 12 Adwaita type styles: large-title, title-1…4, heading, body, caption… |
| [`Icon`](https://gnome-ui.org/react/?path=/docs/components-icon--docs) | Inline SVG icon. Accepts `@gnome-ui/icons` definitions, [`simple-icons`](https://simpleicons.org/) icons, or any `{ path }` object; inherits `currentColor` |
| [`Avatar`](https://gnome-ui.org/react/?path=/docs/components-avatar--docs) | Circular user image with deterministic-color initials fallback |
| [`AvatarGroup`](https://gnome-ui.org/react/?path=/docs/components-avatargroup--docs) | Overlapping stack of avatars with configurable max visible count and `+N` overflow indicator |
| [`AvatarRotator`](https://gnome-ui.org/react/?path=/docs/components-avatarrotator--docs) | Single avatar surface that crossfades through multiple image sources |
| [`Badge`](https://gnome-ui.org/react/?path=/docs/components-badge--docs) | Counter or status dot, optionally anchored over another element |
| [`StatusBadge`](https://gnome-ui.org/react/?path=/docs/components-statusbadge--docs) | Pill-shaped text label for entity status — published, beta, new, etc.; 6 variants |
| [`Blockquote`](https://gnome-ui.org/react/?path=/docs/components-blockquote--docs) | Styled pull-quote with left-border accent; default, info, warning, error, success variants; optional icon and attribution |
| [`Spinner`](https://gnome-ui.org/react/?path=/docs/components-spinner--docs) | Indeterminate loading indicator; sm/md/lg sizes |
| [`ProgressBar`](https://gnome-ui.org/react/?path=/docs/components-progressbar--docs) | Determinate (0–1) and indeterminate progress indicator |
| [`SegmentedBar`](https://gnome-ui.org/react/?path=/docs/components-segmentedbar--docs) | Multi-segment horizontal bar for proportional distributions (e.g. language breakdown); hover tooltip and highlight; auto color palette from GNOME tokens |
| [`Skeleton`](https://gnome-ui.org/react/?path=/docs/components-skeleton--docs) | Content-shaped loading placeholder; rectangular, circular, and multi-line text variants with optional shimmer |
| [`CountDownTimer`](https://gnome-ui.org/react/?path=/docs/components-countdowntimer--docs) | Countdown timer showing remaining time until a specified date; `date`, `time`, or `datetime` formats; executes callback on completion |
| [`StatusPage`](https://gnome-ui.org/react/?path=/docs/components-statuspage--docs) | Empty-state page with icon, title, description, and optional actions; `compact` prop for sidebars/popovers |
| [`Separator`](https://gnome-ui.org/react/?path=/docs/components-separator--docs) | Horizontal/vertical dividing line between content groups |
| [`Chip`](https://gnome-ui.org/react/?path=/docs/components-chip--docs) | Compact pill-shaped label for tags, filters, and multi-select; static, removable, and selectable modes |
| [`ShortcutLabel`](https://gnome-ui.org/react/?path=/docs/components-shortcutlabel--docs) | Renders keyboard shortcut tokens (e.g. `Ctrl+S`) as individual key cap pills |
| [`WindowTitle`](https://gnome-ui.org/react/?path=/docs/components-windowtitle--docs) | Two-line title + subtitle widget for use inside a `HeaderBar` |
| [`Timeline`](https://gnome-ui.org/react/?path=/docs/components-timeline--docs) | Ordered sequence of events connected by a visual connector line; vertical (activity feed) and horizontal (stepper) orientations; solid, dotted, and none variants |
| [`ContributionGraph`](https://gnome-ui.org/react/?path=/docs/data-display-contributiongraph--docs) | Activity heatmap calendar (GitHub-style); pure SVG, keyboard-navigable grid, responsive week count, dark mode and accent-color aware |

### Layout & containers

| Component | Description |
|-----------|-------------|
| [`Box`](https://gnome-ui.org/react/?path=/docs/components-box--docs) | Flex layout primitive equivalent to `GtkBox` — vertical or horizontal, with GNOME HIG spacing scale |
| [`Card`](https://gnome-ui.org/react/?path=/docs/components-card--docs) | Elevated surface for grouping content; static or interactive (activatable) |
| [`Frame`](https://gnome-ui.org/react/?path=/docs/components-frame--docs) | Bordered surface without background fill — mirrors `GtkFrame` |
| [`Bin`](https://gnome-ui.org/react/?path=/docs/components-bin--docs) | Single-child transparent wrapper — mirrors `AdwBin` |
| [`HeaderBar`](https://gnome-ui.org/react/?path=/docs/components-headerbar--docs) | Title bar with centered title and leading/trailing action slots |
| [`Toolbar`](https://gnome-ui.org/react/?path=/docs/components-toolbar--docs) | Horizontal action bar with 6 px padding/gap for flat and raised buttons |
| [`Spacer`](https://gnome-ui.org/react/?path=/docs/components-spacer--docs) | Invisible `flex: 1` filler to push trailing items to the end of a `Toolbar` |
| [`ToolbarView`](https://gnome-ui.org/react/?path=/docs/components-toolbarview--docs) | Layout with pinned top/bottom bars and scrollable center content — mirrors `AdwToolbarView` |
| [`LinkedGroup`](https://gnome-ui.org/react/?path=/docs/components-linkedgroup--docs) | Renders children as a single connected unit with merged borders; horizontal and vertical |
| [`Sidebar`](https://gnome-ui.org/react/?path=/docs/components-sidebar--docs) / `SidebarSection` / `SidebarItem` | Lateral navigation panel with named sections, suffix widgets, and context menus |
| [`BoxedList`](https://gnome-ui.org/react/?path=/docs/components-boxedlist--docs) | Rounded bordered list of rows — canonical GNOME settings pattern |
| [`ActionRow`](https://gnome-ui.org/react/?path=/docs/components-actionrow--docs) | Settings row with title, subtitle, leading icon, and trailing widget |
| [`ButtonRow`](https://gnome-ui.org/react/?path=/docs/components-buttonrow--docs) | Full-width activatable row styled as a button inside a `BoxedList`; Default, Suggested, Destructive |
| [`ExpanderRow`](https://gnome-ui.org/react/?path=/docs/components-expanderrow--docs) | Collapsible `ActionRow` that reveals nested rows; controlled and uncontrolled |
| [`SwitchRow`](https://gnome-ui.org/react/?path=/docs/components-switchrow--docs) | `ActionRow` with a built-in `Switch` trailing widget |
| [`CheckRow`](https://gnome-ui.org/react/?path=/docs/components-checkrow--docs) | `ActionRow` with a built-in `Checkbox` trailing widget |
| [`ComboRow`](https://gnome-ui.org/react/?path=/docs/components-comborow--docs) | `ActionRow` with a built-in `Dropdown` for selecting a value |
| [`EntryRow`](https://gnome-ui.org/react/?path=/docs/components-entryrow--docs) | Inline text entry row — title doubles as floating label |
| [`PasswordEntryRow`](https://gnome-ui.org/react/?path=/docs/components-passwordentryrow--docs) | `EntryRow` variant with show/hide password toggle |
| [`SpinRow`](https://gnome-ui.org/react/?path=/docs/components-spinrow--docs) | `ActionRow` with a built-in `SpinButton` for numeric values |
| [`WrapBox`](https://gnome-ui.org/react/?path=/docs/components-wrapbox--docs) | Wrapping flex container for tag/chip lists that flows across multiple lines — mirrors `AdwWrapBox` |
| [`TabBar`](https://gnome-ui.org/react/?path=/docs/components-tabs--docs) / `TabItem` / `TabPanel` | Tab-based navigation with keyboard support, optional close buttons, `count` badge for unread indicators, and `inline` variant |
| [`ViewSwitcher`](https://gnome-ui.org/react/?path=/docs/components-viewswitcher--docs) / `ViewSwitcherItem` | Segmented pill control for switching between 2–4 top-level views |
| [`ViewSwitcherSidebar`](https://gnome-ui.org/react/?path=/docs/components-viewswitchersidebar--docs) / `ViewSwitcherSidebarItem` | Sidebar-based view switcher — replaces `GtkStackSidebar` |
| [`Carousel`](https://gnome-ui.org/react/?path=/docs/components-carousel--docs) / `CarouselIndicatorDots` / `CarouselIndicatorLines` | Swipeable page carousel with multi-slide viewports, peeking and de-emphasised neighbours, seamless infinite looping, optional edge arrows and dot or line indicators — mirrors `AdwCarousel` |
| [`ShortcutsDialog`](https://gnome-ui.org/react/?path=/docs/components-shortcutsdialog--docs) | Modal listing keyboard shortcuts with integrated search |
| [`WidgetManager`](https://gnome-ui.org/react/?path=/docs/components-widgetmanager--docs) | Card that manages a controlled collection of widgets picked from a catalog; edit-mode trigger opens a `Modal`/`BottomSheet`/`Drawer` picker with staged add/remove and confirm/cancel |

### Overlays

| Component | Description |
|-----------|-------------|
| [`Toast`](https://gnome-ui.org/react/?path=/docs/components-toast--docs) / `Toaster` | Non-blocking temporary notification with auto-dismiss, action, and queue support |
| [`Dialog`](https://gnome-ui.org/react/?path=/docs/components-dialog--docs) | Blocking modal with title, body, focus trap, and configurable buttons |
| [`Modal`](https://gnome-ui.org/react/?path=/docs/components-modal--docs) | Large overlay for rich content, forms, and settings; scrollable body, header bar with close button and optional primary/secondary actions |
| [`BottomSheet`](https://gnome-ui.org/react/?path=/docs/components-bottomsheet--docs) | Slide-up panel from the bottom of the viewport with drag handle and optional title |
| [`Drawer`](https://gnome-ui.org/react/?path=/docs/components-drawer--docs) | Slide-over panel that opens from the left or right with React content |
| [`Tooltip`](https://gnome-ui.org/react/?path=/docs/components-tooltip--docs) | Floating informational label on hover/focus with auto-flip positioning |
| [`Popover`](https://gnome-ui.org/react/?path=/docs/components-popover--docs) | Floating interactive panel with arrow and auto-flip positioning |
| [`Banner`](https://gnome-ui.org/react/?path=/docs/components-banner--docs) | Persistent message strip with optional action and dismiss |

### Preferences

| Component | Description |
|-----------|-------------|
| [`PreferencesGroup`](https://gnome-ui.org/react/?path=/docs/components-preferencesgroup--docs) | Titled `BoxedList` section with optional description and header suffix widget |
| [`PreferencesPage`](https://gnome-ui.org/react/?path=/docs/components-preferencespage--docs) | Named page that contains one or more `PreferencesGroup` sections |
| [`PreferencesDialog`](https://gnome-ui.org/react/?path=/docs/components-preferencesdialog--docs) | Tabbed preferences window — mirrors `AdwPreferencesDialog` |

### Adaptive layout

| Component | Description |
|-----------|-------------|
| [`useBreakpoint`](https://gnome-ui.org/react/?path=/docs/adaptive-usebreakpoint--docs) | Hook tracking viewport width against GNOME breakpoints (400 / 550 / 860 px) |
| [`Clamp`](https://gnome-ui.org/react/?path=/docs/adaptive-clamp--docs) | Constrains content to a max width, centering it — mirrors `AdwClamp` |
| [`NavigationSplitView`](https://gnome-ui.org/react/?path=/docs/adaptive-navigationsplitview--docs) | Two-pane layout that collapses to a single pane at ≤ 400 px; sidebar shown first (mobile-first default) |
| [`OverlaySplitView`](https://gnome-ui.org/react/?path=/docs/adaptive-overlaysplitview--docs) | Sidebar becomes slide-over overlay at ≤ 400 px; supports backdrop, Escape, and swipe-to-dismiss |
| [`NavigationView`](https://gnome-ui.org/react/?path=/docs/adaptive-navigationview--docs) / `NavigationPage` | Mobile-style navigation stack with forward/back slide transitions — mirrors `AdwNavigationView` |
| [`ViewSwitcherBar`](https://gnome-ui.org/react/?path=/docs/adaptive-viewswitcherbar--docs) | Bottom bar for `ViewSwitcher` items on narrow screens (≤ 550 px) |
| [`BreakpointBin`](https://gnome-ui.org/react/?path=/docs/adaptive-breakpointbin--docs) | Applies layout changes when the **component** crosses a size threshold — CSS container queries equivalent |

## Testing

Unit tests (Vitest + Testing Library, jsdom) cover component logic and
rendering. For behavior a simulated DOM can't verify faithfully — the real
OS clipboard, the real `prefers-reduced-motion` media query — real-browser
tests run against Storybook via Playwright:

```bash
npm run test:browser --workspace @gnome-ui/react
```

These also run in the repository CI workflow.

## License

[MIT](../../LICENSE)

---

Source: packages/layout/README.md

# @gnome-ui/layout

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

Full-page application shell components following the [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/), built on the [Adwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/) design language.

[![npm](https://img.shields.io/npm/v/@gnome-ui/layout)](https://www.npmjs.com/package/@gnome-ui/layout)
[![CI](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml)
[![Storybook](https://img.shields.io/badge/Storybook-live-ff4785?logo=storybook&logoColor=white)](https://gnome-ui.org/layout/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

Live documentation: **[Storybook →](https://gnome-ui.org/layout/)**

## Installation

```bash
npm install @gnome-ui/layout
```

## Setup

Import the stylesheet once at the root of your app:

```tsx
// main.tsx or App.tsx
import "@gnome-ui/layout/styles";
```

## Formatting

Numeric layout components such as `CounterCard` and `StatCard` inherit locale and default number formatting from `GnomeProvider` in `@gnome-ui/react`.

```tsx
import { GnomeProvider } from "@gnome-ui/react";
import { CounterCard } from "@gnome-ui/layout";

<GnomeProvider
  locale="en-US"
  numberFormat={{ notation: "compact", compactDisplay: "short" }}
>
  <CounterCard label="Downloads" value={12500} />
</GnomeProvider>
```

Use compact notation for values like `13K`; omit `numberFormat` or use `notation: "standard"` for full values like `12,500`. A component-level `format` prop, where available, still takes precedence.

## Tree-shaking

The package ships per-component entry points, so bundlers can eliminate unused components automatically:

```tsx
// Only Layout is included in the bundle
import { Layout } from "@gnome-ui/layout";
```

Per-component paths are also available:

```tsx
import { Layout } from "@gnome-ui/layout/components/Layout";
```

## Components

### `Layout`

Full-page application shell with four named, optional zones:

| Zone | Prop | Description |
|------|------|-------------|
| Header | `header` / `topBar` | Pinned header — typically a `Toolbar`, `HeaderBar`, or app header composition. Never scrolls when `scroll="content"`. |
| Sidebar | `sidebar` | Fixed-width lateral navigation — typically a `Sidebar`. |
| Content | `children` | Scrollable main area. Fills remaining space. |
| Footer | `footer` / `bottomBar` | Pinned footer — typically a status `Toolbar`. Never scrolls when `scroll="content"`. |

All props of `<div>` are forwarded to the root element.

`topBar` and `bottomBar` remain supported for existing apps. New code can use
the shell-style aliases `header` and `footer`; the legacy names take precedence
when both are provided.

#### Height and scroll modes

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `height` | `"viewport" \| "parent"` | `"viewport"` | `viewport` fills the browser viewport (`100vh`); `parent` fills the containing element (`100%`) for nested layouts. |
| `scroll` | `"content" \| "page" \| "none"` | `"content"` | `content` scrolls only the main area; `page` lets the whole shell scroll; `none` disables internal scrolling. |

#### Mobile sidebar overlay

On narrow viewports the sidebar becomes a slide-in overlay panel. The default
breakpoint is **400 px**, matching GNOME split-view behaviour.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sidebarOpen` | `boolean` | `false` | Whether the sidebar overlay is visible on mobile |
| `onSidebarClose` | `() => void` | — | Called when the user taps the backdrop — use it to set `sidebarOpen` back to `false` |
| `onSidebarOpenChange` | `(open, reason) => void` | — | Called for shell-driven open changes such as backdrop and Escape |
| `sidebarPlacement` | `"start" \| "end"` | `"start"` | Places the sidebar on the leading or trailing edge |
| `sidebarLabel` | `string` | — | Accessible label for the sidebar landmark wrapper |
| `sidebarBreakpoint` | `"narrow" \| "medium" \| "wide"` | `"narrow"` | Overlay threshold: `400`, `550`, or `860` px |
| `sidebarCollapseMode` | `"none" \| "rail" \| "overlay"` | `"none"` | Wide-layout collapse behaviour |
| `sidebarCollapsed` | `boolean` | `false` | Applies shell-level collapsed sidebar styling |
| `sidebarCollapsedWidth` | `number` | `56` | Rail width in pixels |

On wider viewports the sidebar stays in layout flow unless
`sidebarCollapseMode="overlay"` and `sidebarCollapsed` are both set.

When the sidebar overlay is open, focus moves into the sidebar, `Tab` and
`Shift+Tab` remain inside it, and `Escape` requests close through
`onSidebarOpenChange(false, "escape")`. Add `sidebarLabel` when the sidebar
content does not provide a labelled `nav`.

```tsx
import { useState } from "react";
import {
  AppHeader,
  Layout,
  PageContent,
  SidebarShell,
  SidebarTrigger,
  StatusBar,
} from "@gnome-ui/layout";
import "@gnome-ui/layout/styles";
import { SidebarSection, SidebarItem, Text } from "@gnome-ui/react";

export default function App() {
  const [sidebarOpen, setSidebarOpen] = useState(false);
  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);

  return (
    <Layout
      header={
        <AppHeader
          title="My App"
          leading={
            <SidebarTrigger
              sidebarOpen={sidebarOpen}
              sidebarCollapsed={sidebarCollapsed}
              onSidebarOpenChange={setSidebarOpen}
              onSidebarCollapsedChange={setSidebarCollapsed}
            />
          }
        />
      }
      sidebar={
        <SidebarShell
          header={<Text variant="heading">My App</Text>}
          collapsed={sidebarCollapsed}
        >
          <SidebarSection>
            <SidebarItem label="Home" active onClick={() => setSidebarOpen(false)} />
            <SidebarItem label="Settings" onClick={() => setSidebarOpen(false)} />
          </SidebarSection>
        </SidebarShell>
      }
      sidebarOpen={sidebarOpen}
      sidebarCollapsed={sidebarCollapsed}
      sidebarCollapseMode="rail"
      onSidebarClose={() => setSidebarOpen(false)}
      footer={
        <StatusBar>
          <Text variant="caption" color="dim">Ready</Text>
        </StatusBar>
      }
    >
      <PageContent as="section" maxWidth="lg">
        <Text variant="title-2">Welcome</Text>
      </PageContent>
    </Layout>
  );
}
```

#### Shell API improvements

The current shell API adds a few improvements over the original
`topBar`/`bottomBar` composition:

- `header` and `footer` aliases make shell regions read naturally while keeping
  `topBar` and `bottomBar` compatible with existing apps.
- `height="parent"` makes nested shells possible without accidental double
  `100vh` layouts.
- `scroll="content"` keeps header/footer/sidebar fixed while only the main area
  scrolls.
- `sidebarBreakpoint`, `sidebarPlacement`, and `sidebarCollapseMode` cover
  narrow overlays, right-side panels, and icon-only rail sidebars.
- `SidebarTrigger` coordinates the same button with overlay open state on
  narrow screens and rail collapse on wider screens.
- Overlay sidebars move focus inside, trap `Tab`/`Shift+Tab`, close with
  `Escape`, and restore focus to the previous trigger.

---

### `SidebarShell`

Full-height sidebar composition for `Layout.sidebar`. It wraps the GNOME
`Sidebar` with optional fixed header/footer areas and a scrollable navigation
middle.

| Prop | Type | Description |
|------|------|-------------|
| `header` | `ReactNode` | Fixed content above the navigation list. |
| `children` | `ReactNode` | Navigation content, usually `SidebarSection` children. |
| `footer` | `ReactNode` | Fixed content below the navigation list. |

All `Sidebar` props such as `collapsed`, `searchable`, `filter`, `mode`, and
`variant` pass through.

```tsx
import { SidebarShell } from "@gnome-ui/layout";
import { SidebarSection, SidebarItem, Text } from "@gnome-ui/react";

<SidebarShell header={<Text variant="heading">Files</Text>} searchable>
  <SidebarSection>
    <SidebarItem label="Home" active />
    <SidebarItem label="Starred" />
  </SidebarSection>
</SidebarShell>
```

---

### `SidebarTrigger`

Header button that toggles the sidebar using the current layout mode. On
overlay breakpoints it opens or closes the panel; on wider screens it toggles
rail collapse.

| Prop | Type | Description |
|------|------|-------------|
| `sidebarOpen` | `boolean` | Current overlay-open state. |
| `sidebarCollapsed` | `boolean` | Current rail-collapsed state. |
| `sidebarBreakpoint` | `"narrow" \| "medium" \| "wide"` | Same breakpoint used by `Layout`. |
| `onSidebarOpenChange` | `(open, reason) => void` | Called when the trigger changes overlay state. |
| `onSidebarCollapsedChange` | `(collapsed) => void` | Called when the trigger changes rail collapse. |

```tsx
import { SidebarTrigger } from "@gnome-ui/layout";

<SidebarTrigger
  sidebarOpen={sidebarOpen}
  sidebarCollapsed={sidebarCollapsed}
  onSidebarOpenChange={setSidebarOpen}
  onSidebarCollapsedChange={setSidebarCollapsed}
/>
```

---

### `AppHeader`

Opinionated application header for `Layout.header`. It keeps the GNOME
`HeaderBar` shape while exposing shell-friendly slots.

| Prop | Type | Description |
|------|------|-------------|
| `title` | `ReactNode` | Header title. String titles render with `WindowTitle`. |
| `subtitle` | `string` | Optional subtitle for string titles. |
| `leading` | `ReactNode` | Leading controls, usually sidebar/back buttons. |
| `navigation` | `ReactNode` | Optional top-level navigation such as `ViewSwitcher`. |
| `search` | `ReactNode` | Optional search control. |
| `actions` | `ReactNode` | Trailing actions, usually flat icon buttons or menus. |
| `flat` | `boolean` | Blend the header into the window chrome. |

```tsx
import { AppHeader } from "@gnome-ui/layout";
import { Button, SearchBar } from "@gnome-ui/react";

<AppHeader
  title="Files"
  subtitle="Home"
  leading={<Button variant="flat" aria-label="Toggle sidebar">☰</Button>}
  search={<SearchBar inline open aria-label="Search files" />}
  actions={<Button variant="flat">New Folder</Button>}
/>
```

---

### `PageContent`

Scrollable page body for `Layout.children`. It provides GNOME page padding and
optional Adwaita `Clamp` behaviour for readable widths.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `as` | `ElementType` | `"main"` | Element to render. Use `section` when nested inside another `main`. |
| `maxWidth` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| number` | `"none"` | Optional content clamp. |
| `padding` | `"none" \| "compact" \| "normal" \| "spacious"` | `"normal"` | Responsive page padding. |

```tsx
import { PageContent } from "@gnome-ui/layout";

<PageContent as="section" maxWidth="lg">
  ...
</PageContent>
```

---

### `StatusBar`

Compact footer/status bar for `Layout.footer`.

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Leading status content. |
| `trailing` | `ReactNode` | Optional trailing status or actions. |

```tsx
import { StatusBar } from "@gnome-ui/layout";

<StatusBar trailing="GNOME Files 48.0">
  1,248 items
</StatusBar>
```

---

### `IconBadge`

Rounded-square tinted icon container. Accepts the seven gnome-ui named colors or any hex value (`#rgb` / `#rrggbb`). In both cases the background is rendered at 15% opacity.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `color` | `"blue" \| "green" \| "yellow" \| "orange" \| "red" \| "purple" \| "brown" \| string` | — | Named color token or any hex value. Omit for a neutral grey background. |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Badge size |
| `children` | `ReactNode` | — | Icon, emoji, or any inline content |

All `<div>` props are forwarded to the root element.

```tsx
import { IconBadge } from "@gnome-ui/layout";
import { Icon } from "@gnome-ui/react";
import { GoHome } from "@gnome-ui/icons";

// Named color token
<IconBadge color="blue" size="lg">🚀</IconBadge>

// Arbitrary hex — same 15% tinted background
<IconBadge color="#6c8ebf" size="md"><Icon icon={GoHome} size="sm" /></IconBadge>
<IconBadge color="#ddd" size="sm">📄</IconBadge>

// No color — neutral grey overlay
<IconBadge size="md">📄</IconBadge>
```

---

### `CounterCard`

Metric card with an animated numeric counter. Counts from `0` (or from the previous value) to `value` using an ease-out cubic curve. Respects `prefers-reduced-motion`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Text label shown above the value |
| `value` | `number` | — | Numeric target value |
| `prefix` | `string` | — | String prepended to the number (e.g. `"$"`) |
| `suffix` | `string` | — | String appended to the number (e.g. `" files"`) |
| `decimals` | `number` | `0` | Decimal places to display |
| `format` | `(n: number) => string` | — | Custom formatter; overrides `decimals` |
| `animated` | `boolean` | `true` | Animate the counter on mount and value change |
| `duration` | `number` | `1000` | Animation duration in ms |
| `accent` | `boolean` | `false` | Render the value in the accent color |
| `interactive` | `boolean` | `false` | Make the card clickable |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

```tsx
import { CounterCard } from "@gnome-ui/layout";

<CounterCard label="Documents" value={1248} suffix=" files" />
<CounterCard label="Revenue"   value={9420} prefix="$" accent duration={1500} />
```

---

### `StatCard`

Key metric card with optional unit, trend indicator, icon, decorative background
chart, and loading state. Use it for dashboard metrics that need context beyond a
raw count.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Metric label |
| `value` | `number \| string` | — | Primary value |
| `unit` | `string` | — | Optional unit suffix |
| `trend` | `{ direction: "up" \| "down" \| "neutral"; value: number; period?: string }` | — | Optional trend indicator |
| `icon` | `ReactNode` | — | Optional visual element. Size and color are controlled by the node you pass in. |
| `backgroundChart` | `ReactNode` | — | Decorative background visual, such as a spark chart from `@gnome-ui/charts`. |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

```tsx
import { Person } from "@gnome-ui/icons";
import { Icon } from "@gnome-ui/react";
import { StatCard } from "@gnome-ui/layout";

<StatCard
  label="Active Users"
  value={1284}
  unit="users"
  icon={<Icon icon={Person} size="lg" />}
  trend={{ direction: "up", value: 12, period: "vs last week" }}
/>
```

`backgroundChart` stays behind the metric content and is treated as decorative.
Pass the spark chart you need rather than coupling `StatCard` to a specific
chart type:

```tsx
import { SparkAreaChart } from "@gnome-ui/charts";
import { StatCard } from "@gnome-ui/layout";

<StatCard
  label="Requests"
  value="24.8k"
  trend={{ direction: "up", value: 6, period: "today" }}
  backgroundChart={
    <SparkAreaChart
      data={[18, 24, 20, 32, 40, 36, 52]}
      height={96}
    />
  }
/>
```

Per-component path:

```tsx
import { StatCard } from "@gnome-ui/layout/components/StatCard";
```

---

### `ProgressCard`

Resource usage card with a labeled progress bar. Composes `Card` and
`ProgressBar` from `@gnome-ui/react`. The fill color shifts automatically at
usage thresholds: accent (< 75%), warning (≥ 75%), error (≥ 90%).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Resource name shown above the bar |
| `used` | `number` | — | Amount currently used |
| `total` | `number` | — | Total capacity |
| `unit` | `string` | — | Unit label appended to the usage text (e.g. `"GB"`, `"%"`) |
| `icon` | `ReactNode` | — | Optional leading icon (rendered as decorative) |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

```tsx
import { ProgressCard } from "@gnome-ui/layout";

<ProgressCard label="Storage" used={42.5} total={128} unit="GB" />
<ProgressCard label="Memory"  used={96}   total={128} unit="GB" icon={<MemoryIcon />} />
```

Per-component path:

```tsx
import { ProgressCard } from "@gnome-ui/layout/components/ProgressCard";
```

---

### `UserCard`

User identity panel for popovers, sidebar footers, and profile pages. Renders an `Avatar`, a display name, an optional sub-line, and a list of action buttons. A separator is automatically inserted before the first `"destructive"` action when non-destructive actions precede it.

The component has **no card chrome** — place it inside a `Popover` or wrap it in `<Card>`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Display name; also drives avatar initials and color |
| `email` | `string` | — | Optional secondary line |
| `avatarSrc` | `string` | — | Avatar image URL; falls back to initials |
| `avatarColor` | `AvatarColor` | — | Override the auto-derived avatar color |
| `avatarSize` | `AvatarSize` | `"md"` | Avatar size |
| `actions` | `UserCardAction[]` | `[]` | Action buttons; use `variant: "destructive"` for danger actions |
| `minWidth` | `number` | `200` | Minimum card width in px |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

```tsx
import { UserCard } from "@gnome-ui/layout";

<UserCard
  name="Ada Lovelace"
  email="ada@gnome.org"
  actions={[
    { label: "View Profile",     onClick: () => {} },
    { label: "Account Settings", onClick: () => {} },
    { label: "Sign Out",         onClick: () => {}, variant: "destructive" },
  ]}
/>
```

---

### `EntityCard`

Avatar/icon + title + optional badge, subtitle, description, trailing slot, and footer
meta. Covers both compact grid cards and full-width list rows via additive optional props.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `avatar` | `ReactNode` | — | Avatar slot — use `<IconBadge>` or `<Avatar>` |
| `title` | `string` | — | Primary label |
| `badge` | `ReactNode` | — | Inline node next to the title (e.g. status badge) |
| `trailing` | `ReactNode` | — | Node pinned to the far right |
| `subtitle` | `string` | — | Secondary line below the title |
| `description` | `string` | — | Third line — longer description text |
| `meta` | `[string?, string?]` | — | Up to two footer strings: first left-aligned, second right-aligned |
| `interactive` | `boolean` | `true` | Delegates hover/active behavior to `Card` |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

```tsx
import { EntityCard } from "@gnome-ui/layout";
import { IconBadge } from "@gnome-ui/layout";

<EntityCard
  avatar={<IconBadge color="blue" size="md">🌤</IconBadge>}
  title="GNOME Weather"
  subtitle="@alice_dev"
  meta={["v4.8.0", "⭐ 203"]}
/>
```

---

### `ApplicationCard`

App detail header with avatar, name, badge, description, stat row, and actions.
Designed for the MyApps `AppDetail` view — use `EntityCard` for list rows.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `avatar` | `ReactNode` | — | Avatar slot — use `<IconBadge size="xl">` |
| `name` | `string` | — | Application name |
| `badge` | `ReactNode` | — | Inline node next to the name (e.g. `<StatusBadge>`) |
| `description` | `string` | — | Short description below the name |
| `stats` | `ApplicationCardStat[]` | — | Horizontal key/value stat pairs |
| `actions` | `ReactNode` | — | Action buttons below the stats row |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

```tsx
import { ApplicationCard } from "@gnome-ui/layout";

<ApplicationCard
  avatar={<IconBadge color="blue" size="xl">⛅</IconBadge>}
  name="GNOME Weather"
  badge={<StatusBadge variant="success">published</StatusBadge>}
  description="The official weather app for the GNOME desktop."
  stats={[{ label: "Version", value: "v4.8.1" }]}
  actions={<Button variant="suggested">New Release</Button>}
/>
```

---

### `PanelCard`

Card with a structured **header / body / footer** layout and built-in collapse/expand behaviour.

The expanded state is managed internally. Control it imperatively via a `ref`:

```tsx
import { useRef } from "react";
import { PanelCard } from "@gnome-ui/layout";
import type { PanelCardHandle } from "@gnome-ui/layout";

const ref = useRef<PanelCardHandle>(null);

// Drive from anywhere in the parent:
ref.current?.expand();
ref.current?.collapse();
ref.current?.toggle();
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `ReactNode` | — | Primary title shown in the header |
| `icon` | `ReactNode` | — | Leading icon in the header |
| `headerActions` | `ReactNode` | — | Controls at the trailing edge of the header, before the chevron |
| `defaultExpanded` | `boolean` | `true` | Initial expanded state |
| `collapsible` | `boolean` | `true` | Show the chevron toggle; set `false` to lock the panel open |
| `onExpandedChange` | `(expanded: boolean) => void` | — | Notification callback — fires on every state transition |
| `children` | `ReactNode` | — | Body content (collapsed/expanded with the panel) |
| `footer` | `ReactNode` | — | Leading content in the footer bar (feedback text, badge…) |
| `footerActions` | `ReactNode` | — | Trailing controls in the footer bar |
| `loading` | `boolean` | `false` | Replace the body with a loading placeholder (header stays visible) |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

The footer bar is only rendered when at least one of `footer` or `footerActions` is provided.

#### Ref handle

| Method | Description |
|--------|-------------|
| `expand()` | Expand the panel |
| `collapse()` | Collapse the panel |
| `toggle()` | Toggle between expanded and collapsed |

```tsx
import { Icon, Button, Text } from "@gnome-ui/react";
import { FolderOpen } from "@gnome-ui/icons";
import { PanelCard } from "@gnome-ui/layout";
import type { PanelCardHandle } from "@gnome-ui/layout";

const panelRef = useRef<PanelCardHandle>(null);

<PanelCard
  ref={panelRef}
  icon={<Icon icon={FolderOpen} />}
  title="Project Files"
  headerActions={<Button variant="flat" size="sm">Rename</Button>}
  onExpandedChange={(open) => console.log("panel:", open)}
  footer={<Text variant="caption" color="dim">Last modified: 2 min ago</Text>}
  footerActions={<Button variant="suggested" size="sm">Save</Button>}
>
  <p>Panel body content here</p>
</PanelCard>
```

---

### `DashboardGrid`

Responsive 12-column CSS Grid container for dashboard widgets and panels.

#### Breakpoints

| Key | Min-width |
|-----|-----------|
| `xs` | — (base) |
| `sm` | 576 px |
| `md` | 768 px |
| `lg` | 992 px |
| `xl` | 1200 px |
| `xxl` | 1600 px |

#### `DashboardGrid` props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `1–12 \| "auto" \| Partial<Record<Breakpoint, 1–12>>` | `"auto"` | Column count. `"auto"` fills columns with `minmax(280px, 1fr)`. An object maps breakpoints to explicit counts. |
| `gap` | `"sm" \| "md" \| "lg" \| Partial<Record<Breakpoint, "sm" \| "md" \| "lg">>` | `"md"` | Gap between items — fixed or responsive. Uses `--gnome-space-2/3/4`. |
| `layout` | `"grid" \| "column"` | `"grid"` | Render as a grid or as a vertical stack. |

#### `DashboardGrid.Item` props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `span` | `1–12 \| Partial<Record<Breakpoint, 1–12>>` | `1` | Column span — fixed or responsive per breakpoint. |
| `offset` | `0–11` | `0` | Columns to skip before the item. |

Both `DashboardGrid` and `DashboardGrid.Item` forward all `<div>` props
to their root element.

```tsx
import { DashboardGrid } from "@gnome-ui/layout";

// Responsive columns + responsive span
<DashboardGrid columns={{ xs: 1, sm: 2, md: 3, lg: 4 }} gap="md">
  <DashboardGrid.Item span={{ xs: 12, md: 8 }}>
    <Chart />
  </DashboardGrid.Item>
  <DashboardGrid.Item span={{ xs: 12, md: 4 }}>
    <Sidebar />
  </DashboardGrid.Item>
</DashboardGrid>

// Fixed 12-column layout with offset
<DashboardGrid columns={12} gap="md">
  <DashboardGrid.Item span={8} offset={2}>
    <CenteredPanel />
  </DashboardGrid.Item>
</DashboardGrid>

// Vertical stack
<DashboardGrid layout="column" gap="md">
  <DashboardGrid.Item><StatCard /></DashboardGrid.Item>
  <DashboardGrid.Item><ActivityFeed /></DashboardGrid.Item>
</DashboardGrid>
```

---

### `MasonryGrid`

Masonry layout that distributes variable-height items across columns using a
**shortest-column-first** algorithm — each new item is placed in the column
with the least accumulated height, minimising gaps. Layout is computed in
JavaScript via `ResizeObserver` and adapts automatically when the container
or any item changes size.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `number \| Partial<Record<Breakpoint, number>>` | `3` | Column count — fixed or per breakpoint. |
| `gap` | `"sm" \| "md" \| "lg" \| Partial<Record<Breakpoint, "sm" \| "md" \| "lg">>` | `"md"` | Gap between items — fixed or responsive. |
| `fresh` | `boolean` | `false` | Attach a `ResizeObserver` to every child so the layout recomputes when any item grows or shrinks. |

Uses the same breakpoints as `DashboardGrid` (xs / sm / md / lg / xl / xxl).

```tsx
import { MasonryGrid } from "@gnome-ui/layout";

<MasonryGrid columns={{ xs: 1, sm: 2, md: 3 }} gap="md">
  <Card height={180} />
  <Card height={260} />
  <Card height={120} />
</MasonryGrid>
```

---

### `QuickActions`

Grid of shortcut action buttons for dashboards, file managers, and control panels.
Actions are keyboard navigable with arrow keys, and disabled actions are skipped
and cannot be activated.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `actions` | `QuickAction[]` | — | Shortcut action definitions |
| `columns` | `number` | `4` | Number of grid columns |

#### `QuickAction`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Stable action id |
| `label` | `string` | Visible button label |
| `icon` | `ReactNode` | Icon or visual element. Size and color are controlled by the node you pass in. |
| `disabled` | `boolean` | Visually disables the action and blocks activation |
| `onActivate` | `() => void` | Called when the action is clicked or activated from the keyboard |

```tsx
import { Add, Save, Share } from "@gnome-ui/icons";
import { Icon } from "@gnome-ui/react";
import { QuickActions } from "@gnome-ui/layout";

<QuickActions
  columns={3}
  actions={[
    {
      id: "new-file",
      label: "New File",
      icon: <Icon icon={Add} size="lg" />,
      onActivate: () => {},
    },
    {
      id: "save",
      label: "Save",
      icon: <Icon icon={Save} size="lg" />,
      onActivate: () => {},
    },
    {
      id: "share",
      label: "Share",
      icon: <Icon icon={Share} size="lg" />,
      disabled: true,
      onActivate: () => {},
    },
  ]}
/>
```

---

### `ActivityFeed`

Chronological list of recent events with relative timestamps, optional icons,
skeleton loading state, and a "Show more" affordance.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `ActivityFeedItem[]` | — | Feed entries |
| `maxItems` | `number` | — | Truncate after N items; a "Show more" button reveals the rest |
| `loading` | `boolean` | `false` | Render a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |
| `emptyState` | `ReactNode` | — | Content shown when `items` is empty |

#### `ActivityFeedItem`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Stable item key |
| `label` | `string` | Event description |
| `description` | `string` | Optional supporting text |
| `timestamp` | `Date` | Event time; displayed as relative time ("2 minutes ago") |
| `icon` | `ReactNode` | Optional icon rendered in a circular badge |

```tsx
import { ActivityFeed } from "@gnome-ui/layout";

<ActivityFeed
  items={[
    {
      id: "1",
      label: "User logged in",
      description: "admin@example.com",
      timestamp: new Date(),
    },
  ]}
  maxItems={5}
  emptyState={<p>No recent activity</p>}
/>
```

Per-component path:

```tsx
import { ActivityFeed } from "@gnome-ui/layout/components/ActivityFeed";
```

---

### `SectionHeader`

Title row for dashboard sections with optional subtitle and trailing action slot.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Section title |
| `subtitle` | `string` | — | Optional supporting text shown below the title |
| `action` | `ReactNode` | — | Optional trailing action — button, link, or menu trigger |

```tsx
import { SectionHeader } from "@gnome-ui/layout";

<SectionHeader
  title="Recent Activity"
  subtitle="Last 24 hours"
  action={<Button variant="flat" size="sm">View all</Button>}
/>
```

Per-component path:

```tsx
import { SectionHeader } from "@gnome-ui/layout/components/SectionHeader";
```

---

### `ToastProvider` / `useToast`

Transient in-app notifications shown at the bottom-center of the screen, following GNOME HIG toast guidelines. Toasts auto-dismiss after a configurable timeout and are shown one at a time (queue-based).

Wrap your app (or the relevant subtree) with `<ToastProvider>`, then call `useToast()` to show messages from any component.

| Method | Signature | Description |
|--------|-----------|-------------|
| `show` | `(options: ToastOptions) => string` | Enqueues a toast and returns its id |
| `dismiss` | `(id?: string) => void` | Dismisses the toast with the given id (or the current one if omitted) |
| `dismissAll` | `() => void` | Clears the entire queue immediately |

#### `ToastOptions`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `title` | `string` | — | Toast message text |
| `type` | `"default" \| "info" \| "success" \| "warning" \| "error"` | `"default"` | Visual variant |
| `timeout` | `number` | `4000` | Auto-dismiss delay in ms. `0` = no auto-dismiss |
| `action` | `{ label: string; onClick: () => void }` | — | Optional inline action button |
| `id` | `string` | auto | Stable id for deduplication |

```tsx
import { ToastProvider, useToast } from "@gnome-ui/layout";

// Wrap your app:
<ToastProvider>
  <App />
</ToastProvider>

// Inside any component:
function SaveButton() {
  const { show } = useToast();
  return (
    <button onClick={() => show({ title: "File saved", type: "success" })}>
      Save
    </button>
  );
}
```

---

### `Banner`

Persistent in-app message strip shown at the top of a view, following GNOME HIG banner guidelines. Use banners to communicate ongoing states — offline mode, read-only access, pending updates. They do not auto-dismiss. For individual events and short-lived messages, use `Toast` instead.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `"default" \| "info" \| "success" \| "warning" \| "error"` | `"default"` | Visual variant |
| `action` | `{ label: string; onClick: () => void }` | — | Optional inline action button |
| `onDismiss` | `() => void` | — | Shows a close button; parent controls visibility |
| `children` | `ReactNode` | — | Banner message content |

```tsx
import { Banner } from "@gnome-ui/layout";

<Banner
  type="warning"
  action={{ label: "Reconnect", onClick: retry }}
  onDismiss={() => setVisible(false)}
>
  Working offline — changes will sync when you reconnect
</Banner>
```

## License

[MIT](../../LICENSE)

---

Source: packages/charts/README.md

# @gnome-ui/charts

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

Chart components for [@gnome-ui/react](../react/README.md), styled with GNOME Adwaita
design tokens.

[![npm](https://img.shields.io/npm/v/@gnome-ui/charts)](https://www.npmjs.com/package/@gnome-ui/charts)
[![CI](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml)
[![Storybook](https://img.shields.io/badge/Storybook-live-ff4785?logo=storybook&logoColor=white)](https://gnome-ui.org/charts/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

## Installation

```bash
npm install @gnome-ui/charts
```

Requires `@gnome-ui/core` for design tokens and `react` ≥ 19 as peer dependencies.

## Setup

Import the stylesheet once at the root of your app:

```tsx
// main.tsx or App.tsx
import "@gnome-ui/core/styles";
import "@gnome-ui/charts/styles";
```

## Components

| Component | Description |
|-----------|-------------|
| `AreaChart` | Filled area chart with optional stacking, grid, and legend |
| `BarChart` | Vertical or horizontal bar chart with rounded bars, optional stacking, grid, and legend |
| `LineChart` | Line chart with dots, grid, and legend |
| `RadialBarChart` | Concentric arc chart with optional labels, legend, and inner radius control |
| `CloudChart` | Word/tag cloud with linear font-size scaling and per-word color support |
| `PieChart` | Pie or donut chart with optional slice labels and legend |
| `RadarChart` | Spider/radar chart with single or multiple series and optional fill |
| `TreeMap` | Proportional tile chart with optional group coloring and labels |
| `GaugeChart` | Single-value speedometer gauge with optional status color thresholds |
| `BulletChart` | Compact bullet graph: performance value vs. target with qualitative range bands |
| `Heatmap` | Row × column matrix heatmap for correlation and density data |
| `SankeyChart` | Flow diagram for multi-stage funnels and user journeys |
| `WaterfallChart` | Floating-bar chart for cumulative increases/decreases — revenue bridges, budget breakdowns |
| `BoxPlot` | Box-and-whisker plot for distribution, quartiles, and outliers across one or more groups |

### Spark charts

Minimal inline charts — no axes, no grid, no legend, no tooltip. Designed to be embedded inside Cards, table cells, list items, or any layout component.

| Component | Description |
|-----------|-------------|
| `SparkAreaChart` | Compact area chart with optional gradient fill |
| `SparkLineChart` | Compact line chart, no fill |
| `SparkBarChart` | Compact bar chart with rounded bars |
| `SparkGaugeChart` | Compact single-value progress ring |
| `SparkPieChart` | Compact pie or donut for part-to-whole composition |
| `SparkBulletChart` | Compact bullet graph: value vs. target in a single row |

`SparkAreaChart`, `SparkLineChart`, and `SparkBarChart` accept `data: number[]`
directly or `Record<string, unknown>[]` with a `dataKey`. The default color is
`var(--gnome-accent-color)` so it inherits the active accent automatically.

`SparkGaugeChart` is the exception — it takes a single `value` (plus `min`,
`max`, and optional `thresholds`) instead of a data array, mirroring
`GaugeChart`'s API.

`SparkPieChart` takes `data: { value: number; color?: string }[]` — one entry
per slice — plus `size` (diameter, default 40) and `donut` (hollow center,
default `false`), mirroring `PieChart`'s API. Colors fall back to
`GNOME_CHART_PALETTE` by index.

`SparkBulletChart` takes `value` (plus optional `target`, `min`, `max`, and
`ranges`) instead of a data array, mirroring `BulletChart`'s API at a compact
scale (`height`, default 16, instead of `BulletChart`'s `label`/`showValue`).

See [`src/README.md`](src/README.md) for full spark chart docs.

```tsx
import { SparkAreaChart, SparkLineChart, SparkBarChart } from "@gnome-ui/charts";
import { Card, Text } from "@gnome-ui/react";

// Simplest form — plain number array
<SparkAreaChart data={[42, 58, 35, 72, 88, 93]} height={48} />

// Embedded in a Card
<Card>
  <Text variant="caption" color="dim">Downloads</Text>
  <Text variant="title-2">12,430</Text>
  <SparkAreaChart
    data={[42, 58, 35, 72, 88, 93]}
    height={48}
    aria-label="Downloads trend"
  />
</Card>

// Object array with explicit dataKey
<SparkLineChart
  data={weeklyData}
  dataKey="sessions"
  color="var(--gnome-green-3)"
  height={32}
/>
```

All components use the Adwaita color palette (`GNOME_CHART_PALETTE`) and CSS custom
properties for theming, and adapt automatically to light/dark mode.

## Formatting

Charts inherit locale and default number formatting from `GnomeProvider` in
`@gnome-ui/react`. This affects axis ticks, tooltips, and generated accessible
labels.

```tsx
import { GnomeProvider } from "@gnome-ui/react";
import { BarChart } from "@gnome-ui/charts";

<GnomeProvider
  locale="en-US"
  numberFormat={{ notation: "compact", compactDisplay: "short" }}
>
  <BarChart
    data={[{ month: "Jan", downloads: 12500 }]}
    series={[{ dataKey: "downloads", name: "Downloads" }]}
  />
</GnomeProvider>
```

Use compact notation for values like `13K`; omit `numberFormat` or use
`notation: "standard"` for full values like `12,500`.

## Imports

### Standard import (barrel)

Import any component from the package root. Works with every bundler and is
the simplest option. Modern bundlers that respect the `sideEffects` field in
`package.json` will still tree-shake unused components automatically.

```tsx
import { AreaChart, BarChart, CloudChart, LineChart, PieChart, RadarChart, RadialBarChart, TreeMap } from "@gnome-ui/charts";
```

### Per-component import (explicit tree-shaking)

Each component is also exposed as its own sub-path export. Use this form if
your bundler does not perform tree-shaking, or when you want to be explicit
about what you pull in.

```tsx
import { BarChart } from "@gnome-ui/charts/components/BarChart";
import { LineChart } from "@gnome-ui/charts/components/LineChart";
import { AreaChart } from "@gnome-ui/charts/components/AreaChart";
import { PieChart } from "@gnome-ui/charts/components/PieChart";
import { CloudChart } from "@gnome-ui/charts/components/CloudChart";
import { RadarChart } from "@gnome-ui/charts/components/RadarChart";
import { RadialBarChart } from "@gnome-ui/charts/components/RadialBarChart";
import { TreeMap } from "@gnome-ui/charts/components/TreeMap";
```

Both forms are fully typed and produce identical runtime behavior.

## Quick example

```tsx
import { AreaChart, BarChart, CloudChart, LineChart, PieChart, RadarChart, RadialBarChart, TreeMap } from "@gnome-ui/charts";

const data = [
  { month: "Jan", sales: 400, returns: 80 },
  { month: "Feb", sales: 600, returns: 120 },
  { month: "Mar", sales: 500, returns: 90 },
];

// Area chart
<AreaChart
  data={data}
  xAxisKey="month"
  series={[
    { dataKey: "sales", name: "Sales" },
    { dataKey: "returns", name: "Returns" },
  ]}
  showLegend
/>

// Bar chart
<BarChart
  data={data}
  xAxisKey="month"
  series={[{ dataKey: "sales", name: "Sales" }]}
/>

// Line chart
<LineChart
  data={data}
  xAxisKey="month"
  series={[
    { dataKey: "sales", name: "Sales" },
    { dataKey: "returns", name: "Returns" },
  ]}
  showGrid
  showLegend
/>

// Word cloud
<CloudChart
  data={[
    { text: "TypeScript", value: 95 },
    { text: "React", value: 80 },
    { text: "CSS", value: 60 },
    { text: "Docker", value: 40 },
  ]}
/>

// Pie / donut chart
<PieChart
  data={[
    { label: "Chrome", value: 62 },
    { label: "Firefox", value: 18 },
    { label: "Safari", value: 11 },
    { label: "Other", value: 9 },
  ]}
  donut
  showLegend
/>

// Radar chart
<RadarChart
  data={[
    { skill: "TypeScript", alice: 90, bob: 70 },
    { skill: "React", alice: 85, bob: 80 },
    { skill: "CSS", alice: 60, bob: 75 },
  ]}
  angleKey="skill"
  series={[
    { dataKey: "alice", name: "Alice" },
    { dataKey: "bob", name: "Bob" },
  ]}
  filled
  showLegend
/>

// Radial bar chart
<RadialBarChart
  data={[
    { label: "CPU", value: 72 },
    { label: "Memory", value: 58 },
    { label: "Disk", value: 41 },
  ]}
  showLegend
/>

// TreeMap
<TreeMap
  data={[
    { label: "React", value: 4200, group: "Frontend" },
    { label: "Vue", value: 2100, group: "Frontend" },
    { label: "Node.js", value: 3800, group: "Backend" },
  ]}
  height={400}
/>
```

## Props

`AreaChart`, `BarChart`, and `LineChart` share a common set of props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Array of data objects |
| `series` | `{ dataKey, name?, color? }[]` | — | Series definitions |
| `xAxisKey` | `string` | `"name"` | Key to use for the X axis |
| `height` | `number` | `300` | Chart height in px |
| `showGrid` | `boolean` | `true` | Show horizontal grid lines |
| `showLegend` | `boolean` | `false` | Show legend below chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`AreaChart` also accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `stacked` | `boolean` | `false` | Stack all series on top of each other |
| `gradient` | `boolean` | `false` | Fill areas with a top-to-transparent gradient |

`BarChart` also accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `stacked` | `boolean` | `false` | Stack series on top of each other |
| `layout` | `"vertical" \| "horizontal"` | `"vertical"` | Bar orientation |
| `yAxisFormatter` | `(value: number) => string` | — | Custom Y-axis tick formatter |

`CloudChart` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `CloudChartDataItem[]` | — | Array of `{ text, value, color? }` |
| `height` | `number` | `300` | Minimum height of the cloud container in px |
| `minFontSize` | `number` | `12` | Font size in px for the lowest-value word |
| `maxFontSize` | `number` | `48` | Font size in px for the highest-value word |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`PieChart` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `PieChartDataItem[]` | — | Array of `{ label, value, color? }` |
| `height` | `number` | `400` | Chart height in px |
| `donut` | `boolean` | `false` | Render as a donut chart with a center hole |
| `showLabels` | `boolean` | `false` | Show slice labels outside the chart |
| `showLegend` | `boolean` | `false` | Show legend below chart |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`RadarChart` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Array of data objects |
| `series` | `{ dataKey, name?, color? }[]` | — | Series definitions |
| `angleKey` | `string` | `"name"` | Key used for the angle axis labels |
| `height` | `number` | `400` | Chart height in px |
| `filled` | `boolean` | `false` | Fill radar polygons with a semi-transparent color |
| `showLegend` | `boolean` | `false` | Show legend below chart |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`RadialBarChart` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `RadialBarChartDataItem[]` | — | Array of `{ label, value, color? }` |
| `height` | `number` | `400` | Chart height in px |
| `innerRadius` | `number \| string` | `"20%"` | Inner radius of the donut gap |
| `showLabels` | `boolean` | `false` | Show category name inside each arc |
| `showLegend` | `boolean` | `false` | Show legend below chart |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`GaugeChart` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current value; shown as-is even outside `min`/`max`, the arc is clamped |
| `min` | `number` | `0` | Minimum of the gauge range |
| `max` | `number` | `100` | Maximum of the gauge range |
| `height` | `number` | `220` | Chart height in px |
| `color` | `string` | — | Explicit arc color; overrides `thresholds` |
| `thresholds` | `{ value, color }[]` | — | Ascending value/color bands for status-style gauges |
| `showValue` | `boolean` | `true` | Show the numeric value and `label` centered on the gauge |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for the displayed value |
| `label` | `string` | — | Caption rendered under the value |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`Heatmap` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `HeatmapDataItem[]` | — | `{ row: string; column: string; value: number }[]` |
| `rows` | `string[]` | first-seen order | Explicit row order, top to bottom |
| `columns` | `string[]` | first-seen order | Explicit column order, left to right |
| `color` | `string` | accent blue | Base color for the intensity scale |
| `min` | `number` | lowest value in `data` | Explicit domain minimum |
| `max` | `number` | highest value in `data` | Explicit domain maximum |
| `cellSize` | `number` | `40` | Cell side length in px |
| `showValues` | `boolean` | `false` | Show the formatted value inside each cell |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for cell values and the legend |
| `showLegend` | `boolean` | `false` | Show a min→max color scale below the grid |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`SankeyChart` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `nodes` | `SankeyChartNode[]` | — | `{ name: string; color?: string }[]` |
| `links` | `SankeyChartLink[]` | — | `{ source: string; target: string; value: number }[]`, referencing node names |
| `height` | `number` | `400` | Chart height in px |
| `nodeWidth` | `number` | `12` | Node rectangle thickness in px |
| `nodePadding` | `number` | `24` | Vertical gap between stacked nodes in the same column |
| `showValues` | `boolean` | `false` | Append the formatted value to each node label |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for labels and the tooltip |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

`TreeMap` accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TreeMapDataItem[]` | — | Array of `{ label, value, group? }` |
| `height` | `number` | `400` | Chart height in px |
| `showLabels` | `boolean` | `true` | Show name and value inside each tile |
| `className` | `string` | — | Extra CSS class on the wrapper |

`SparkAreaChart`, `SparkLineChart`, and `SparkBarChart` share these props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `number[] \| Record<string, unknown>[]` | — | Values to plot |
| `dataKey` | `string` | `"value"` | Key to read when data is an object array |
| `color` | `string` | `var(--gnome-accent-color)` | Stroke / fill color |
| `height` | `number` | `40` | Chart height in px |
| `strokeWidth` | `number` | `1.5` | Stroke width |
| `className` | `string` | — | Extra CSS class on the wrapper |
| `aria-label` | `string` | — | Sets `role="img"` and an accessible label |

`SparkAreaChart` also accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `gradient` | `boolean` | `true` | Gradient fill from color to transparent |
| `fillOpacity` | `number` | `0.2` | Fill opacity when `gradient` is false |

`SparkBarChart` also accepts:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `barSize` | `number` | auto | Bar width in px |
| `fillOpacity` | `number` | `0.85` | Bar fill opacity |

## Utilities

| Export | Description |
|--------|-------------|
| `GNOME_CHART_PALETTE` | Array of GNOME Adwaita accent colors used as the default series palette |

## License

[MIT](../../LICENSE)

---

Source: packages/platform/README.md

# @gnome-ui/platform

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

TypeScript API layer for communicating with the GNOME host process from a
React app running inside a WebKitGTK WebView.

[![npm](https://img.shields.io/npm/v/@gnome-ui/platform)](https://www.npmjs.com/package/@gnome-ui/platform)
[![npm downloads](https://img.shields.io/npm/dm/@gnome-ui/platform)](https://www.npmjs.com/package/@gnome-ui/platform)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
[![GitHub last commit](https://img.shields.io/github/last-commit/ElJijuna/gnome-react)](https://github.com/ElJijuna/gnome-react/commits/main)
[![GitHub issues](https://img.shields.io/github/issues/ElJijuna/gnome-react)](https://github.com/ElJijuna/gnome-react/issues)

> **Status:** all 7 feature modules are implemented, each with a real
> browser/PWA fallback where a genuine web equivalent exists (and an honest
> rejection where one doesn't — see [Modules](#modules)). This package is the
> **web side** of the bridge; it assumes a GJS host that implements the
> matching `window.webkit.messageHandlers` channels and dispatches the
> `gnome:*` response/signal events documented per module below.

## How it works

`@gnome-ui/platform` communicates with the GNOME host process through one
of two mechanisms, resolved at runtime:

| Environment | Bridge |
| --- | --- |
| WebKitGTK WebView (GJS host) | `window.webkit.messageHandlers.*` |
| Flatpak / sandboxed app | XDG Desktop Portals (via `portals`) |
| Browser / PWA / test | real browser APIs where one exists, otherwise rejects |

## Installation

```bash
npm install @gnome-ui/platform
```

## Modules

| Module | Browser / PWA fallback |
| --- | --- |
| [`clipboard`](#clipboard) | Text and images: real `navigator.clipboard`. Files: none — no browser API exposes real filesystem paths. |
| [`settings`](#settings) | None — no web equivalent of an app-schema-scoped `GSettings` store. |
| [`notifications`](#notifications) | Real `Notification` API (single click only — no action buttons). |
| [`fileChooser`](#file-chooser) | None — File System Access API only hands back opaque handles, never real paths. |
| [`colorScheme`](#color-scheme) | Read/subscribe: real `matchMedia('(prefers-color-scheme: dark)')`. Write: none. |
| [`window`](#window) | Partial — see the [window](#window) section for exactly which state/actions have a real equivalent. |
| [`portals`](#portals) | None — portals are meaningless outside a sandboxed GNOME host. |

### Clipboard

```ts
import {
  readText, writeText,
  readImage, writeImage,
  readFiles, writeFiles,
} from "@gnome-ui/platform";

await writeText("hello");
const text = await readText();

// Images cross the bridge as data: URLs either way.
await writeImage(dataUrl);
const image = await readImage(); // string | null — null when nothing's there

// Paths only — WebKitGTK-only, rejects in a browser.
await writeFiles(["/home/user/report.pdf"]);
const paths = await readFiles(); // string[] — [] when nothing's there
```

### Settings

Reads/writes a `GSettings` key. WebKitGTK-only.

```ts
import { getSetting, setSetting, onSettingChanged } from "@gnome-ui/platform";

const scheme = await getSetting<string>("color-scheme");
await setSetting("color-scheme", "prefer-dark");

// Fires for writes from this window AND external changes (another app,
// dconf-editor, `gsettings set` from a terminal).
const off = onSettingChanged<string>("color-scheme", (value) => {
  console.log("color-scheme is now", value);
});
off(); // unsubscribe
```

### Notifications

```ts
import {
  sendNotification, withdrawNotification, onNotificationAction,
} from "@gnome-ui/platform";

const id = await sendNotification({
  title: "Download complete",
  body: "report.pdf",
  actions: [{ id: "open", label: "Open" }], // WebKitGTK only
});

onNotificationAction(id, (actionId) => {
  // actionId is "open" (WebKitGTK) or "default" (a click on the browser
  // fallback's plain Notification — it has no separate action buttons)
});

await withdrawNotification(id);
```

### File chooser

WebKitGTK-only — every function rejects in a browser (see [Modules](#modules)
for why). Each resolves `{ canceled: true, ... }` rather than throwing when
the user dismisses the dialog.

```ts
import { openFile, saveFile, selectFolder } from "@gnome-ui/platform";

const { canceled, paths } = await openFile({ multiple: true });
const { path } = await saveFile({ currentName: "export.csv" });
const { path: folder } = await selectFolder();
```

### Color scheme

**`setColorScheme` only ever overrides this app's own rendering** (maps to
`Adw.StyleManager.set_color_scheme()`), never the desktop-wide preference — a
well-behaved app shouldn't be able to flip the user's whole desktop into dark
mode. In a browser, use `GnomeProvider`'s `colorScheme` prop instead — there
is no JS API to force the browser's own rendering into a scheme.

```ts
import { getColorScheme, setColorScheme, onColorSchemeChanged } from "@gnome-ui/platform";

const scheme = await getColorScheme(); // "light" | "dark" — the resolved scheme
await setColorScheme("dark");          // "light" | "dark" | "system"

const off = onColorSchemeChanged((scheme) => {
  console.log("now rendering", scheme);
});
```

### Window

```ts
import {
  getWindowState, setMaximized, setFullscreen,
  minimizeWindow, closeWindow, onWindowStateChanged,
} from "@gnome-ui/platform";

const { maximized, fullscreen, focused } = await getWindowState();

await setFullscreen(true);  // real Fullscreen API fallback in a browser
await setMaximized(true);   // WebKitGTK only — no browser fallback
await minimizeWindow();     // WebKitGTK only — no browser fallback
await closeWindow();        // real window.close() fallback (browsers only
                             // honor it for windows opened by script)

onWindowStateChanged(({ maximized, fullscreen, focused }) => { /* … */ });
```

`maximized` has no browser equivalent at all — there is no standard way for
page script to ask whether the OS window chrome is maximized, so it is
always reported as `false` outside WebKitGTK.

### Portals

The generic escape hatch behind the other portal-backed modules — reach for
it when the app needs a portal interface this package doesn't wrap in a
dedicated module (`OpenURI`, `Email`, `Print`, `Account`, `Background`,
`Inhibit`, `Location`, `ScreenCast`, …). WebKitGTK-only.

```ts
import { callPortal, onPortalSignal } from "@gnome-ui/platform";

await callPortal({
  interface: "org.freedesktop.portal.OpenURI",
  method: "OpenURI",
  args: { uri: "https://example.com" },
});

const off = onPortalSignal(
  "org.freedesktop.portal.Settings",
  "SettingChanged",
  (payload) => { /* … */ },
);
```

## Bridge utilities

The typed modules above are all built on these — reach for them directly to
talk to a bridge channel this package doesn't wrap yet.

### Fire-and-forget

Send a message to a named GJS handler without waiting for a reply — resolves
once dispatched, not once the host finishes handling it:

```ts
import { isWebKitBridge, postMessage } from "@gnome-ui/platform";

if (isWebKitBridge()) {
  console.log("Running in GNOME app context");
}

await postMessage("notifications", { action: "send", title: "Hello" });
```

### Request/response

Several host operations are inherently asynchronous (a GDK clipboard read, a
GSettings read, a portal call…) and need their reply matched back to the
specific call that triggered it, especially with several calls in flight at
once. `postMessageAndWait` tags the outgoing message with a `requestId` and
resolves once the host dispatches a `gnome:<responseEvent>` carrying that
same id back — every module above that needs a value back from the host is
built on this:

```ts
import { postMessageAndWait } from "@gnome-ui/platform";

const { value } = await postMessageAndWait<{ requestId: string; value: string }>(
  "settings",
  { action: "get", key: "color-scheme" },
  "settings-get-result",
);
```

Rejects after 5s (configurable via a 4th argument) if no matching response
arrives — e.g. because the WebView shell hasn't implemented that channel yet.

### Native → Web events

Subscribe to events dispatched by the GJS host. The host fires them by
evaluating a `CustomEvent` in the WebView:

```js
// GJS side — dispatch an event to the web layer
webView.evaluate_javascript(
  `window.dispatchEvent(new CustomEvent("gnome:open-modal", { detail: { id: "settings" } }))`,
  -1, null, null, null, null
);
```

```ts
// Web side — subscribe (returns an unsubscribe function)
import { onNativeEvent } from "@gnome-ui/platform";

const off = onNativeEvent("open-modal", (payload) => {
  console.log("open modal:", payload.id);
});

// later, clean up:
off();
```

All native events use the `gnome:` prefix internally — pass only the
unprefixed name to `onNativeEvent`.

> **Security note:** events arrive as plain DOM `CustomEvent`s, so any script
> running in the page can forge them — there is no way to verify the sender.
> Treat payloads as untrusted input, and never gate a privileged action
> solely on receiving one.

## Runtime detection

```ts
import { getRuntime } from "@gnome-ui/platform";

const { shell, engine, browser, os } = getRuntime();

if (shell === "webkitgtk-webview") // running inside a GNOME native app
if (shell === "pwa")               // installed PWA
if (browser.epiphany)              // running inside GNOME Web (Epiphany)
if (os.linux)                      // Linux host
```

## License

[MIT](../../LICENSE)

---

Source: packages/hooks/README.md

# @gnome-ui/hooks

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

React hooks that expose [@gnome-ui/platform](../platform/README.md) APIs
as idiomatic React state.

[![npm](https://img.shields.io/npm/v/@gnome-ui/hooks)](https://www.npmjs.com/package/@gnome-ui/hooks)
[![CI](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

## Installation

```bash
npm install @gnome-ui/hooks
```

Requires `@gnome-ui/platform` and `react` ≥ 19 as peer dependencies.

The package is fully tree-shakeable (`sideEffects: false`). Each hook has its
own deep entry point so bundlers can eliminate unused hooks:

```ts
// barrel import — all hooks
import { useBreakpoint } from "@gnome-ui/hooks";

// deep import — only useBreakpoint in the bundle
import { useBreakpoint } from "@gnome-ui/hooks/useBreakpoint";
```

## Hooks

### Viewport

| Hook | Returns | Description |
| --- | --- | --- |
| `useBreakpoint()` | `BreakpointInfo` | Reactive `isMobile`, `isTablet`, `isDesktop` flags based on GNOME HIG breakpoints |
| `useElementSize(ref)` | `ElementSize` | Reactive `{ width, height }` of an element via `ResizeObserver` — the container-level sibling of `useBreakpoint` |
| `usePrefersReducedMotion()` | `boolean` | Tracks the OS-level `prefers-reduced-motion` accessibility setting |

### Platform & runtime

| Hook | Returns | Description |
| --- | --- | --- |
| `usePlatform()` | `PlatformInfo` | Convenience booleans for the current shell context |
| `useRuntime()` | `RuntimeInfo` | Full runtime snapshot: shell, engine, browser, OS |
| `useNativeEvent(type, handler)` | `void` | Subscribe to an event dispatched by the GJS host |
| `usePortalSignal(interface, signal, handler)` | `void` | Subscribe to an XDG Desktop Portal D-Bus signal (e.g. `Settings`'s `SettingChanged`) |

### GNOME integrations

| Hook | Returns | Description |
| --- | --- | --- |
| `useSettings(key, defaultValue)` | `UseSettingsResult<T>` | Read/write a GSettings key; re-renders on external changes |
| `useNotification()` | `{ send, dismiss }` | Send and dismiss desktop notifications, scoped to the component's lifetime |
| `useColorScheme()` | `UseColorSchemeResult` | Reactive resolved `"light"`/`"dark"` scheme, with a `"light"`/`"dark"`/`"system"` setter |
| `useFileChooser()` | `UseFileChooserResult` | Trigger file open/save/folder dialogs; tracks the resolved path as reactive state |
| `useClipboard()` | `{ value, copy, paste }` | Reactive clipboard with copy/paste helpers |
| `useWindowState()` | `UseWindowStateResult` | Reactive window state (`maximized`, `fullscreen`, `focused`) with matching actions |
| `useHapticFeedback()` | `{ trigger, isSupported, ... }` | Haptic feedback via feedbackd (native) or Vibration API (browser/PWA) |

## Examples

### Adapt layout to viewport size

```tsx
import { useBreakpoint } from "@gnome-ui/hooks";

export function AdaptiveLayout() {
  const { isMobile, isDesktop } = useBreakpoint();

  return isDesktop ? <SidebarLayout /> : <StackedLayout />;
}
```

Breakpoints follow the GNOME HIG adaptive layout recommendations:

| Flag | Range |
| --- | --- |
| `isMobile` | `width < 480 px` |
| `isTablet` | `480 px ≤ width < 1024 px` |
| `isDesktop` | `width ≥ 1024 px` |

SSR-safe: defaults to `isDesktop: true` when `window` is not available.

### Adapt layout to a container's own size

```tsx
import { useElementSize } from "@gnome-ui/hooks";
import { useRef } from "react";

export function AdaptiveCard() {
  const ref = useRef<HTMLDivElement>(null);
  const { width } = useElementSize(ref);

  return <div ref={ref}>{width < 400 ? <CompactLayout /> : <WideLayout />}</div>;
}
```

Unlike `useBreakpoint` (which watches the viewport), `useElementSize` uses
`ResizeObserver` to watch the element itself — the same widget can behave
differently depending on how much space its parent gives it, regardless of
the window size. Returns `{ width: 0, height: 0 }` until the ref is attached
and the first measurement lands.

### Detect GNOME WebView context

```tsx
import { usePlatform } from "@gnome-ui/hooks";

export function NativeOnlyBanner() {
  const { isGnomeWebView } = usePlatform();

  if (!isGnomeWebView) return null;
  return <Banner>Running inside a GNOME app</Banner>;
}
```

### Listen to a native event from the GJS host

```tsx
import { useNativeEvent } from "@gnome-ui/hooks";

export function SettingsModal() {
  const [open, setOpen] = useState(false);

  useNativeEvent("open-modal", (payload: { id: string }) => {
    if (payload.id === "settings") setOpen(true);
  });

  return <Modal open={open} onClose={() => setOpen(false)} />;
}
```

The GJS host dispatches the event by evaluating JS in the WebView:

```js
webView.evaluate_javascript(
  `window.dispatchEvent(new CustomEvent("gnome:open-modal", {
    detail: { id: "settings" }
  }))`,
  -1, null, null, null, null
);
```

### Subscribe to an XDG Desktop Portal signal

```tsx
import { usePortalSignal } from "@gnome-ui/hooks";

export function SystemSettingsWatcher() {
  usePortalSignal(
    "org.freedesktop.portal.Settings",
    "SettingChanged",
    (payload: { namespace: string; key: string; value: unknown }) => {
      console.log(`${payload.namespace}.${payload.key} changed to`, payload.value);
    },
  );

  return null;
}
```

For one-off calls to a portal interface (not a subscription), use
`callPortal` from `@gnome-ui/platform` directly — it's request/response, so
it doesn't need a hook.

### Read and write a GSettings key

```tsx
import { useSettings } from "@gnome-ui/hooks";

export function DarkModeToggle() {
  const { value: darkMode, setValue: setDarkMode, loading } = useSettings("prefer-dark", false);

  return <Switch checked={darkMode} onChange={setDarkMode} disabled={loading} label="Dark mode" />;
}
```

`value` starts at the given default and updates once the initial read
completes, then stays in sync with external changes too — another app,
`dconf-editor`, or `gsettings set` from a terminal. `setValue` updates
`value` immediately (optimistic) and persists the write in the background;
if the write fails, `error` is set (and cleared again on the next
successful write).

Outside a WebKitGTK environment (a browser, Storybook, tests) there is no
GSettings equivalent — `value` stays at the default forever and `error` is
set. See [`@gnome-ui/platform`'s `settings` module](../platform/README.md#settings)
for details.

| Return value | Type | Description |
| --- | --- | --- |
| `value` | `T` | Current value — the default until the first successful read |
| `setValue(value)` | `(value: T) => void` | Writes a new value (optimistic) |
| `loading` | `boolean` | `true` until the first read completes |
| `error` | `Error \| null` | Set when reading or writing failed |

### Send and dismiss desktop notifications

```tsx
import { useNotification } from "@gnome-ui/hooks";

export function DownloadButton() {
  const { send, dismiss } = useNotification();

  async function onDownloadComplete() {
    const id = await send({
      title: "Download complete",
      body: "report.pdf",
      actions: [{ id: "open", label: "Open" }],
      onAction: (actionId) => {
        if (actionId === "open") openFile("report.pdf");
      },
    });

    setTimeout(() => dismiss(id), 5000);
  }

  return <button onClick={onDownloadComplete}>Download</button>;
}
```

Every notification sent through `send` — and every `onAction` listener
attached to it — is automatically withdrawn/unsubscribed when the component
unmounts. `@gnome-ui/platform`'s `sendNotification`/`onNotificationAction`
don't do that for you on their own, since they have no concept of a React
component's lifetime.

| Return value | Type | Description |
| --- | --- | --- |
| `send(options)` | `(options: UseNotificationSendOptions) => Promise<string>` | Sends a notification, resolves with its id |
| `dismiss(id)` | `(id: string) => Promise<void>` | Withdraws a previously sent notification |

`options` accepts everything `@gnome-ui/platform`'s `SendNotificationOptions`
does (`title`, `body`, `icon`, `priority`, `actions`), plus an optional
`onAction(actionId)` callback.

### Toggle color scheme

```tsx
import { useColorScheme } from "@gnome-ui/hooks";

export function ThemeToggle() {
  const { scheme, setScheme } = useColorScheme();

  return (
    <button onClick={() => setScheme(scheme === "dark" ? "light" : "dark")}>
      Switch to {scheme === "dark" ? "light" : "dark"} mode
    </button>
  );
}
```

> **Not the same hook as `@gnome-ui/react`'s `useColorScheme`.** That one
> reads the `colorScheme`/`resolvedColorScheme` set by the nearest
> `GnomeProvider` — a plain `matchMedia` read that drives your CSS theme and
> works everywhere. *This* hook talks to `Adw.StyleManager` through
> `@gnome-ui/platform`'s bridge, so `setScheme` forces this app's own
> Adwaita rendering independently of your CSS. Reach for it only if you
> specifically need that — outside a WebKitGTK environment `setScheme` has
> no effect (see `error` below).

| Return value | Type | Description |
| --- | --- | --- |
| `scheme` | `"light" \| "dark"` | Current resolved scheme — defaults to `"light"` until the first read completes |
| `setScheme(preference)` | `(preference: "light" \| "dark" \| "system") => void` | Sets this app's color scheme preference |
| `loading` | `boolean` | `true` until the first read completes |
| `error` | `Error \| null` | Set when reading or writing failed |

### Choose a file, save destination, or folder

```tsx
import { useFileChooser } from "@gnome-ui/hooks";

export function AttachmentPicker() {
  const { path, open, loading } = useFileChooser();

  return (
    <Button
      onClick={() => open({ filters: [{ name: "Images", extensions: ["png", "jpg"] }] })}
      disabled={loading}
    >
      {path ?? "Choose a file…"}
    </Button>
  );
}
```

`path`/`paths` hold the most recently chosen result and are left unchanged
if the user cancels the dialog — canceling doesn't blank out a prior
selection. WebKitGTK only, same as `@gnome-ui/platform`'s `fileChooser`
module: browsers never expose real filesystem paths to page scripts, so
every trigger rejects outside that environment (see `error`).

| Return value | Type | Description |
| --- | --- | --- |
| `path` | `string \| null` | Most recently chosen file, save destination, or folder |
| `paths` | `string[]` | All paths from the most recent `open({ multiple: true })` call |
| `open(options)` | `(options?) => Promise<OpenFileResult>` | Opens a file picker |
| `save(options)` | `(options?) => Promise<SaveFileResult>` | Opens a save dialog |
| `selectFolder(options)` | `(options?) => Promise<SelectFolderResult>` | Opens a folder picker |
| `loading` | `boolean` | `true` while a dialog is open and awaiting the user |
| `error` | `Error \| null` | Set when the last dialog call failed |

### Copy and paste clipboard text

```tsx
import { useState } from "react";
import { useClipboard } from "@gnome-ui/hooks";

export function ShareLink({ url }: { url: string }) {
  const { value, copy, paste } = useClipboard();
  const [text, setText] = useState("");

  return (
    <>
      <button onClick={() => copy(url)}>{value === url ? "Copied!" : "Copy link"}</button>

      <TextField value={text} onChange={setText} />
      <button onClick={async () => setText(await paste())}>Paste</button>
    </>
  );
}
```

Text only — `@gnome-ui/platform`'s `clipboard` module also has
`readImage`/`writeImage`/`readFiles`/`writeFiles` for images and file
references, but those return a different enough shape (a `data:` URL, a
list of paths) that folding them into this hook's single `value` would
just make the common case harder to use. Reach for the platform functions
directly for those.

There is no "clipboard changed" signal to subscribe to — `value` only
updates when you call `copy`/`paste` through this hook, not when the
clipboard changes externally (another app, another window).

| Return value | Type | Description |
| --- | --- | --- |
| `value` | `string \| null` | Last text copied or pasted through this hook |
| `copy(text)` | `(text: string) => Promise<void>` | Writes text to the clipboard and updates `value` |
| `paste()` | `() => Promise<string>` | Reads text from the clipboard and updates `value` |
| `loading` | `boolean` | `true` while a copy/paste call is pending |
| `error` | `Error \| null` | Set when the last copy/paste call failed |

### React to window state and trigger window actions

```tsx
import { useWindowState } from "@gnome-ui/hooks";

export function FullscreenToggle() {
  const { fullscreen, setFullscreen } = useWindowState();

  return (
    <button onClick={() => setFullscreen(!fullscreen)}>
      {fullscreen ? "Exit" : "Enter"} fullscreen
    </button>
  );
}
```

`setMaximized`/`minimize` are WebKitGTK-only — there is no browser
equivalent for either (see `error`). `setFullscreen`/`close` fall back to
the real Fullscreen API / `window.close()` in a browser. `maximized` is
always `false` outside WebKitGTK — no browser API exposes whether the OS
window chrome is maximized.

| Return value | Type | Description |
| --- | --- | --- |
| `maximized` | `boolean` | Always `false` outside WebKitGTK |
| `fullscreen` | `boolean` | Real Fullscreen API state in a browser |
| `focused` | `boolean` | Real `document.hasFocus()` state in a browser |
| `setMaximized(value)` | `(value: boolean) => void` | Maximizes or restores the window |
| `setFullscreen(value)` | `(value: boolean) => void` | Enters or exits fullscreen |
| `minimize()` | `() => void` | Minimizes the window |
| `close()` | `() => void` | Requests that the window close |
| `loading` | `boolean` | `true` until the first read completes |
| `error` | `Error \| null` | Set when the last read or action failed |

### Trigger haptic feedback

```tsx
import { useHapticFeedback } from "@gnome-ui/hooks";

export function SendButton() {
  const { trigger, isSupported } = useHapticFeedback();

  return (
    <button
      onClick={() => {
        trigger("button-pressed");
        sendMessage();
      }}
    >
      Send
    </button>
  );
}
```

Resolution order: **feedbackd** (via `window.webkit.messageHandlers` inside a
WebKitGTK WebView) → **Vibration API** (browser / PWA) → no-op.

Event names follow the [GNOME Event Naming Specification](https://honk.sigxcpu.org/projects/feedbackd/doc/Event-naming-spec-0.0.0.html).
App-specific events must use the `x-` prefix:

```ts
trigger("x-myapp-task-complete");
```

| Return value | Type | Description |
| --- | --- | --- |
| `trigger(event)` | `(event: GnomeHapticEvent) => void` | Fire haptic feedback for the given event name |
| `isSupported` | `boolean` | `true` if any haptic mechanism is available |
| `isNativeSupported` | `boolean` | `true` inside a WebKitGTK WebView (feedbackd) |
| `isVibrationApiSupported` | `boolean` | `true` when `navigator.vibrate` is available |

## License

[MIT](../../LICENSE)

---

Source: packages/cli/README.md

# @gnome-ui/cli

<p align="center">
  <img src="https://raw.githubusercontent.com/ElJijuna/gnome-ui/main/public/assets/gnome-ui.png" alt="gnome-ui" width="120" />
</p>

Command-line tools for keeping GNOME UI packages up to date in consuming projects.

[![npm](https://img.shields.io/npm/v/@gnome-ui/cli)](https://www.npmjs.com/package/@gnome-ui/cli)
[![npm downloads](https://img.shields.io/npm/dm/@gnome-ui/cli)](https://www.npmjs.com/package/@gnome-ui/cli)
[![CI](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/eljijuna/gnome-ui/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

## Installation

Install globally when you want the commands available from any project:

```bash
npm install -g @gnome-ui/cli
```

Or install it in a consuming project:

```bash
npm install --save-dev @gnome-ui/cli
```

Then run it through your package manager:

```bash
npx gnomeui verify
```

## Commands

Both binary names point to the same CLI:

```bash
gnomeui
gnomeui status
gui status

gnomeui verify
gui verify

gnomeui update
gui update
```

| Command | Description |
|---------|-------------|
| `gnomeui` / `gnomeui status` | Read-only: shows the comparison table and exits. No confirmation, no update. This is what runs when no command is given |
| `gnomeui verify` | Reads the current project's `package.json`, compares installed `@gnome-ui/*` packages with npm `latest`, and asks whether to update outdated packages before letting you pick which ones |
| `gui verify` | Short alias for `gnomeui verify` |
| `gnomeui update` | Same comparison, but skips the confirmation — goes straight to picking which outdated packages to update |
| `gui update` | Short alias for `gnomeui update` |

All three commands share the same fetch-and-render-table step, and `verify`/
`update` additionally share the confirm → select → apply pipeline — the only
difference between them is whether a Yes/No confirmation runs before the
selection step. See [`src/cli.ts`](src/cli.ts).

## Interactive flow

All three commands open a terminal UI, built with
[`blessed-components`](https://www.npmjs.com/package/blessed-components):

1. A spinner shows while the latest version of each `@gnome-ui/*` package is
   fetched from npm.
2. A table compares every installed package against its npm `latest`.
3. If there are no `@gnome-ui/*` dependencies, an alert says so and the CLI
   exits — same for `status`, `verify`, and `update`.
4. `status` stops here: press any key to close the table and exit.
5. `verify`/`update` continue: if everything is already up to date, an alert
   says so and the CLI exits. Otherwise:
   - `verify` first asks **Yes/No**: update outdated packages now?
   - `update` skips that question.
6. If proceeding, a checklist lets you pick which outdated packages to
   update — **all of them are selected by default**.
7. A final **Yes/No** confirmation names the exact install command about to
   run (e.g. `Update 2 package(s) and run npm install?`) — this is the last
   point before anything on disk changes.
8. Once confirmed, the terminal UI closes, `package.json` is rewritten with
   the updated ranges (preserving `^`/`~` prefixes), and your package
   manager's install command runs with normal terminal output so you can
   watch it.
9. A plain-text summary is printed.

### Checklist keys

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move the cursor |
| `Space` / `Enter` | Toggle the highlighted package |
| `a` | Select all |
| `n` | Select none |
| `y` | Continue to the final install confirmation |
| `q` / `Escape` / `Ctrl+C` | Cancel — no changes are made |

### Non-interactive environments

When stdin/stdout isn't a TTY (CI, piped output, `NODE_ENV` scripts), the CLI
skips the terminal UI entirely and prints a plain comparison table instead:

- `gnomeui status` (or no command) just prints the table and a summary.
- `gnomeui verify` reports outdated packages but does not update them — there's
  no terminal to ask a question in.
- `gnomeui update` updates every outdated package automatically, same as the
  interactive flow's "select all" default.

## `blessed-components` usage

| Component | Where | Why |
|-----------|-------|-----|
| `renderTable` (pure) | [`ui/comparison-table.ts`](src/ui/comparison-table.ts) | Read-only comparison — no interactivity needed, so the pure renderer is enough |
| `renderStatus` (pure) | [`ui/comparison-table.ts`](src/ui/comparison-table.ts) | Latest/Outdated/Unknown marker embedded in the table's Status column |
| `spinner` | [`ui/spinner.ts`](src/ui/spinner.ts) | Shown while the npm registry calls resolve |
| `confirmDialog` | [`ui/confirm.ts`](src/ui/confirm.ts) | The Yes/No decision `verify` asks before updating |
| `multiSelect` | [`ui/select-dependencies.ts`](src/ui/select-dependencies.ts) | The "which packages to update" checklist, defaulting to all selected |
| `alert` | [`ui/alert.ts`](src/ui/alert.ts) | "No dependencies found" / "already up to date" messages |
| `createTheme` | [`ui/theme.ts`](src/ui/theme.ts) | Shared theme applied across the widgets above that accept one |

Every other command-line output (non-interactive mode, the final summary) is
plain `console.log`/`console.table` — `blessed-components` widgets only exist
while the interactive screen is open.

## Package Manager Detection

The CLI detects the package manager from lockfiles in the project root:

| Lockfile | Command |
|----------|---------|
| `pnpm-lock.yaml` | `pnpm install` |
| `yarn.lock` | `yarn install` |
| `bun.lock` or `bun.lockb` | `bun install` |
| none of the above | `npm install` |

## Version Resolution

Current versions are read from `package-lock.json` when available. If no npm
lockfile is present (pnpm/yarn/bun projects), the CLI falls back to the
version range declared in `package.json` — the resolved installed version
isn't visible without parsing each package manager's own lockfile format,
which isn't implemented yet.

Latest versions are resolved through
[`npmjs-api-client`](https://www.npmjs.com/package/npmjs-api-client), a typed
client for the npm Registry API.

## Requirements

`@gnome-ui/cli` is published as an ESM package and uses `commander` for
command parsing and `blessed`/`blessed-components` for its terminal UI.

Because `commander@14` requires Node.js 20 or newer, use:

```bash
node --version
```

and make sure the result is `v20.0.0` or newer.

## License

[MIT](../../LICENSE)

---

Source: packages/react/src/components/AboutDialog/README.md

Standard app info dialog with details, credits, and legal tabs.
Mirrors `AdwAboutDialog`.

Provide `applicationName` plus any combination of `version`, `comments`,
`developerName`, `website`, `developers`, `designers`, `artists`,
`copyright`, `licenseType`, and `licenseText`.
Credits and Legal tabs appear automatically when their content is supplied.

---

Source: packages/react/src/components/ActionRow/README.md

Standard settings row with title, optional subtitle, leading icon, and trailing widget.

Mirrors the Adwaita `AdwActionRow` pattern — the fundamental building block inside a `BoxedList`.

### Guidelines
- Always provide a `title`. Use `subtitle` for secondary context (current value, description).
- Use `trailing` for the primary control: `Switch`, `Button`, a value label, or a chevron icon.
- Use `interactive` for rows that navigate or trigger an action (renders as `<button>`).
- Avoid putting interactive elements inside an `interactive` row — they create nested buttons.
- Wrap in `BoxedList` for the canonical GNOME settings appearance.

---

Source: packages/react/src/components/AffectedPackage/README.md

# AffectedPackage

Package coordinate summary for vulnerability findings, SBOMs, dependency scans,
container image scans, and remediation reports.

```tsx
import { AffectedPackage } from "@gnome-ui/react";

<AffectedPackage
  ecosystem="npm"
  name="lodash"
  version="4.17.20"
  fixedVersion="4.17.21"
/>
```

The component displays the package ecosystem, name, vulnerable version, fixed
version, digest, and Package URL (PURL). When `purl` is omitted and the package
name/version are plain text, a PURL like `pkg:npm/lodash@4.17.20` is generated.

Use it inside `VulnerabilityFinding` or next to `CveIdentifier`, `CweIdentifier`,
`CvssScore`, and `CvssVector` to make affected assets explicit in reports.

---

Source: packages/react/src/components/AnimatedIcon/README.md

Plays the CSS animation embedded in an `animated` icon from
[`@gnome-ui/icons`](https://www.npmjs.com/package/@gnome-ui/icons) — `Syncing`,
`Recording`, `Downloading`, `Connecting`. Rendered through plain `Icon`
instead, these show a static frame; `AnimatedIcon` is what turns the
animation on.

Mirrors GTK 4.22's `GtkSvg` in spirit: the animated markup lives in
trusted, package-authored icon data (never arbitrary user-supplied SVG),
and this component is just the play/pause switch on top of it.

### Guidelines
- Good fits: sync status, active recording, an in-progress download, a
  connection attempt — anywhere a small inline indicator beats a full
  `Spinner`.
- Set `playing` from real state (`isSyncing`, `isRecording`, …) rather than
  leaving it `true` forever — stop the animation once the state ends.
- Cross-fade between icons by keeping `playing` constant and swapping
  `icon` (e.g. `Connecting` → a static "connected" icon once acquired).

### Reduced motion
Always honored, regardless of `playing` — when the OS `prefers-reduced-motion`
setting is on, the animation stays paused even if `playing` is `true`. You
don't need to check `prefers-reduced-motion` yourself before setting `playing`.

### Usage
```tsx
import { AnimatedIcon } from "@gnome-ui/react";
import { Syncing } from "@gnome-ui/icons";

<AnimatedIcon icon={Syncing} playing={isSyncing} label="Syncing" />
```

---

Source: packages/react/src/components/Avatar/README.md

Circular avatar following the Adwaita `AdwAvatar` pattern.

### Guidelines
- Provide a `name` whenever possible — it generates the initials fallback and a deterministic background color.
- Use `src` for a real photo; the initials layer is hidden automatically.
- Always ensure the `name` or `alt` prop conveys who the avatar represents for screen readers.
- Prefer `"md"` (32 px) in lists and `"lg"`/`"xl"` in profile headers.

---

Source: packages/react/src/components/AvatarGroup/README.md

Stack of avatars with overflow indicator.

### Guidelines

- Pass `avatars` as an array of `{ name, src, alt, color }` objects.
- Use `max` to cap visible avatars; excess shows a `+N` chip.
- Provide `name` on each item for accessible labels and initials fallback.
- `size` applies uniformly to all avatars and the overflow chip.

---

Source: packages/react/src/components/AvatarRotator/README.md

Single avatar surface that crossfades through multiple image sources.

### Guidelines
- Use when one person or entity has several possible avatar images and the UI should keep a single avatar footprint.
- Keep the rotation interval calm enough that it does not distract from adjacent content.
- Provide `name` or `alt` so the rotating surface has a stable accessible label.

---

Source: packages/react/src/components/Badge/README.md

Counter or status indicator, optionally overlaid on another element.

### Guidelines
- Use for unread counts, notification numbers, or status indicators.
- Keep the label to **1–3 characters** — use "99+" for large numbers.
- Use `dot` for binary presence (online, unread) when a count is not needed.
- Use `anchor` to overlay the badge on a button, avatar, or icon.
- Choose the `variant` that matches the meaning: counts → `accent`, errors → `error`, online → `success`.

---

Source: packages/react/src/components/Banner/README.md

Persistent message strip displayed at the top of a view.

Mirrors the Adwaita `AdwBanner` pattern.

### Guidelines
- Place at the very top of the content area, below the header bar.
- Keep the message short — one sentence. Use a **Dialog** for longer explanations.
- Provide an `actionLabel` only when there is a clear, single action the user can take.
- Use `dismissible` when the message is informational and non-critical.
- Choose the `variant` that matches the severity: `info` → `warning` → `error`.
- Don't stack multiple banners — show only the most important one at a time.

---

Source: packages/react/src/components/Bin/README.md

Single-child container with no visual styling.

A transparent wrapper that constrains its content to one child while
forwarding all HTML `div` attributes. Useful as a base for custom components
that need a neutral container without introducing visual chrome.

Mirrors `AdwBin`.

### Usage
- Use when you need to apply CSS classes, layout, or size constraints to a single child.
- Does not add any background, border, or padding.

---

Source: packages/react/src/components/Blockquote/README.md

Styled pull-quote with semantic `<blockquote>` markup.

Use it to highlight quoted text, callouts, or editorial notes inline within
content. Five visual variants map to the same severity scale used by
`Banner` and `Badge`.

### Guidelines
- Keep the quoted text short — one to three sentences.
- Provide a `cite` whenever the source is known.
- Use `variant="default"` for neutral quotations; reserve coloured variants
  for callouts that match a clear intent (tip, caution, error, confirmation).
- Supply an `icon` only when it meaningfully reinforces the variant intent.

---

Source: packages/react/src/components/BottomSheet/README.md

Slide-up panel that overlays content from the bottom edge.

Mirrors `AdwBottomSheet` (libadwaita 1.6+). Renders into a portal on
`document.body`. Traps focus, closes on Escape or backdrop click (configurable).

### Guidelines
- Use for actions or supplementary content on mobile/narrow viewports.
- Keep content concise — the sheet should not exceed ~90 % of the viewport height.
- Provide an `onClose` handler to close the sheet on Escape and backdrop tap.

---

Source: packages/react/src/components/BoxedList/README.md

Rounded bordered list — the most common container pattern in GNOME settings and detail views.

Mirrors the Adwaita `.boxed-list` style class on `GtkListBox`.

### Guidelines
- Use to group a set of related settings or items inside a view.
- Separators between rows are inserted automatically.
- Pair with `ActionRow` for the canonical GNOME settings pattern.
- Keep lists focused: 3–8 rows is typical. Split long lists into labelled sections.
- Don't nest `BoxedList` inside another `BoxedList`.

---

Source: packages/react/src/components/BreakpointBin/README.md

Container that fires layout changes when **its own width** crosses defined
thresholds — the CSS container-query equivalent of `AdwBreakpointBin`
(libadwaita 1.9 / GNOME 50).

### vs `useBreakpoint`
| | `useBreakpoint` | `BreakpointBin` |
|---|---|---|
| Watches | Viewport (`window.innerWidth`) | Container (`ResizeObserver`) |
| Use when | Layout depends on screen size | Layout depends on available space |
| Pattern | Hook — use inside components | Component — wraps content |

### How it works
- Breakpoints are sorted by `maxWidth` ascending.
- The **active breakpoint** is the smallest `maxWidth` ≥ the container's current width.
- Exposed as `data-breakpoint` on the wrapper `<div>` for CSS targeting.
- When wider than all thresholds, `activeBreakpoint` is `null`.

### CSS targeting
```css
.myCard[data-breakpoint="compact"] .layout { flex-direction: column; }
```

---

Source: packages/react/src/components/Button/README.md

Button component following the [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/patterns/controls/buttons.html).

### Guidelines
- Use **suggested** for the single primary/affirmative action in a view. Never use more than one per screen.
- Use **destructive** only for irreversible or dangerous actions (e.g. "Delete", "Format").
- Use **flat** inside header bars and toolbars where a border would add visual clutter.
- Button labels must use **imperative verbs** with **Header Capitalization** (e.g. "Save Changes", "Cancel").
- Avoid buttons that mix an icon and a label outside of header bars.

---

Source: packages/react/src/components/ButtonContent/README.md

Icon + label layout helper for buttons that contain both an icon and text.

Pass as the `children` of a `Button` to get the correct Adwaita spacing
between the icon and the label (6 px gap, icon vertically centred with the text).

Mirrors `AdwButtonContent`.

### Usage
- Use inside `<Button>` when you need both icon and text.
- Set `iconPosition="end"` to place the icon after the label.

---

Source: packages/react/src/components/ButtonRow/README.md

Full-width activatable row styled as a button inside a `BoxedList`.

Mirrors `AdwButtonRow` — use when an entire list row should trigger a single
action with a centered label. Supports `suggested` and `destructive` variants
that colour the title text accordingly.

### Guidelines
- Always wrap in `BoxedList` for the canonical GNOME settings appearance.
- Use `suggested` for primary affirmative actions (e.g. "Save", "Apply").
- Use `destructive` for irreversible or dangerous actions (e.g. "Delete Account").
- Use `leading` / `trailing` for optional icons flanking the label.
- Prefer `ActionRow` with `interactive` when the row needs title + subtitle layout.

---

Source: packages/react/src/components/Calendar/README.md

Month-grid date display with full keyboard navigation — mirrors
[`GtkCalendar`](https://gnome.pages.gitlab.gnome.org/gtk/gtk4/class.Calendar.html).
Usable standalone (settings, forms) or as the panel inside a `DatePicker`.

Implements the [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/):
the grid holds a roving `tabindex`, so a single <kbd>Tab</kbd> reaches the current
day. Then:

- <kbd>←</kbd> / <kbd>→</kbd> move one day; <kbd>↑</kbd> / <kbd>↓</kbd> move one week.
- <kbd>Home</kbd> / <kbd>End</kbd> jump to the start / end of the week.
- <kbd>PageUp</kbd> / <kbd>PageDown</kbd> page by month (hold <kbd>Shift</kbd> for a year).
- <kbd>Enter</kbd> / <kbd>Space</kbd> select the focused day.

Leading and trailing days from adjacent months are shown dimmed and remain
selectable — choosing one navigates to that month, matching `GtkCalendar`.

## Changing the year

The heading label is a button that drills down the way modern date pickers do,
so a distant year is two clicks away instead of twelve pages:

```
August 2026  →  month grid (2026)  →  year grid (2016 – 2027)  →  back to days
```

Picking a year drops to that year's month grid; picking a month drops to its day
grid. The step arrows follow the active view — a month at a time on the day grid,
a year on the month grid, twelve years on the year grid — and each grid keeps the
same roving-tabindex keyboard model (<kbd>←</kbd> <kbd>→</kbd> one cell,
<kbd>↑</kbd> <kbd>↓</kbd> one row of four, <kbd>Home</kbd> / <kbd>End</kbd> the
ends of the page, <kbd>Enter</kbd> to drill down, <kbd>Esc</kbd> back to days).
Months and years with no selectable day inside `[min, max]` are disabled.

Pass `showViewSwitcher={false}` for the plain `GtkCalendar` heading, or
`defaultView="years"` to open on the year grid — handy for date-of-birth entry:

```tsx
<Calendar defaultView="years" max={new Date()} onViewChange={(view) => console.log(view)} />
```

## Related

For start/end selection use [`CalendarRange`](../CalendarRange/README.md), which
drives the same grid engine (and takes the same `visibleMonths` prop to show
several month panels side by side).

## Usage

```tsx
import { Calendar } from '@gnome-ui/react/components/Calendar';

function Example() {
  const [date, setDate] = useState<Date | null>(null);
  return <Calendar value={date} onChange={setDate} />;
}
```

Restrict the selectable range and start weeks on Sunday:

```tsx
<Calendar
  min={new Date()}
  max={new Date(2027, 11, 31)}
  weekStartsOn={0}
  showWeekNumbers
/>
```

---

Source: packages/react/src/components/CalendarRange/README.md

Start/end date-range selection driving the same grid engine as `Calendar` —
roving `tabindex`, month/year drill-down, `min`/`max`, week numbers,
localisation.

The first click **anchors** the range and paints a live band up to the day under
the pointer (or under the roving keyboard focus); the second click commits it.
`onChange` therefore only ever fires with **both** ends filled in — there is no
half-emitted range to defend against downstream:

```tsx
import { CalendarRange } from '@gnome-ui/react/components/CalendarRange';

function Example() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return <CalendarRange value={range} onChange={setRange} />;
}
```

Picking backwards is fine — the pair is ordered before it is emitted — and
<kbd>Esc</kbd> cancels a half-made range. Inside a popover Escape is layered:
it closes the month/year drill-down first, then cancels the pending range, and
only then reaches the popover.

## More than one month

`visibleMonths` renders N month panels side by side, paged together by the
shared heading, so a range spanning months needs no navigation:

```tsx
<CalendarRange visibleMonths={2} />
```

The heading names the span (`August – September 2026`), each panel keeps its own
`role="grid"` and month caption, and the roving `tabindex` stays global: exactly
one day is tabbable across every panel, and walking off the last panel pages the
whole window by one month.

## Limiting the length

`minRange` / `maxRange` cap the range in days, counting both ends. While the
range is being drawn, days that could only produce an invalid range are disabled
rather than silently rejected on click:

```tsx
<CalendarRange minRange={2} maxRange={14} min={new Date()} />
```

## Keyboard

Identical to `Calendar` — <kbd>←</kbd>/<kbd>→</kbd>/<kbd>↑</kbd>/<kbd>↓</kbd>,
<kbd>Home</kbd>/<kbd>End</kbd>, <kbd>PageUp</kbd>/<kbd>PageDown</kbd> (hold
<kbd>Shift</kbd> for a year) — plus:

- <kbd>Enter</kbd> / <kbd>Space</kbd> anchor the range, then commit it.
- <kbd>Esc</kbd> cancels the range being drawn.

Moving the focus while anchoring updates the preview band, so the range is fully
selectable without a pointer. Every in-range cell carries `aria-selected`, the
ends and the days between them are named (`", start of range"`, `", in selected
range"`, `", end of range"`), and a polite live region announces both the
half-made state and the finished range.

## Props

Everything `Calendar` takes (`month`, `defaultMonth`, `onMonthChange`, `min`,
`max`, `weekStartsOn`, `locale`, `showHeading`, `showDayNames`,
`showWeekNumbers`, `showViewSwitcher`, `defaultView`, `onViewChange`,
`autoFocus`) plus `value` / `defaultValue` as a `DateRange`, `onChange`,
`onRangeStart`, `minRange`, `maxRange` and `visibleMonths`.

---

Source: packages/react/src/components/Callout/README.md

Inline, dismissible admonition box for contextual help text within forms and cards.

```tsx
import { Callout } from '@gnome-ui/react';

<Callout>Changes are saved automatically.</Callout>
<Callout variant="warning">This action can't be undone.</Callout>
<Callout variant="tip">Press Ctrl+K to open the command palette.</Callout>
```

### Callout vs Banner vs Toast

| | Placement | Lifetime |
|---|---|---|
| `Callout` | Inline, alongside the content it annotates | Persistent until dismissed |
| `Banner` | Edge-to-edge strip at the top of a view | Persistent until dismissed or the condition resolves |
| `Toast` | Floating, overlaid on content | Temporary — auto-dismisses |

Use `Callout` for documentation-style notes inside a form, dialog, or card. Use `Banner` for view-level conditions (an outage, an update available). Use `Toast` for a brief confirmation of something that just happened.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | The message content (required) |
| `variant` | `"info" \| "warning" \| "tip"` | `"info"` | Visual emphasis |
| `dismissible` | `boolean` | `false` | Shows a dismiss (×) button |
| `onDismiss` | `() => void` | — | Called when the dismiss button is clicked |

### Guidelines

- Renders as `role="note"` — a static annotation, not a live region. If the callout appears dynamically in response to a live event, consider `Banner` or `Toast` instead.
- `dismissible` only renders the button — you're responsible for removing the `Callout` from the tree in `onDismiss` (it doesn't manage its own visibility).

---

Source: packages/react/src/components/Card/README.md

Card component following the [GNOME HIG containers](https://developer.gnome.org/hig/patterns/containers.html) and the Adwaita `.card` style class.

### Guidelines
- Use cards to group related content on an elevated surface.
- Use `interactive` for clickable cards (grid items, settings shortcuts). They render as `<button>` for accessibility.
- Avoid nesting interactive elements (buttons, links) inside an `interactive` card — it creates nested interactive elements.
- Cards work at any width; let the layout dictate their size.
- Prefer `padding="md"` (24px) for most cases; `"sm"` for compact UIs.

---

Source: packages/react/src/components/Carousel/README.md

Swipeable content carousel.

Mirrors `AdwCarousel`. Uses CSS scroll-snapping for smooth, native-feeling
page transitions. Supports keyboard navigation (←/→ or ↑/↓), touch, and mouse drag.

Pair with `CarouselIndicatorDots` or `CarouselIndicatorLines` for pagination UI,
or let `indicator` render one for you.

### Layout
- `visibleSlides` — how many children fit inside the viewport at once. Paging moves a
  whole group, so 5 slides with `visibleSlides={2}` give 3 pages. Takes a breakpoint map too
  — see [Responsive](#responsive).
- `peek` — how much of the neighbouring slides shows at each edge, as a px number or any
  CSS length (`peek="10%"`, `peek={40}`). The active group shrinks to make room, so
  paging still advances exactly one group. `spacing` is added on top of it, so `peek` is
  the amount of the neighbour you actually see.
- `focusActiveSlides` — shrink everything outside the current page so the active slides
  read as the focus. `true` scales them to 80%; pass a number for a different ratio
  (`focusActiveSlides={0.92}`). It only shows when the neighbours are on screen, so pair
  it with `peek`. The scale is a transform on an element inside each slide, so layout,
  snap points and paging are all untouched.

### Responsive
`visibleSlides` and `peek` accept a breakpoint map as well as a plain value:

```tsx
<Carousel visibleSlides={{ base: 3, wide: 2, narrow: 1 }} peek={{ base: 32, narrow: 0 }} />
```

The buckets are the GNOME max-widths (`narrow` ≤ 400, `medium` ≤ 550, `wide` ≤ 860), so a map
reads like stacked media queries and the **narrowest matching entry wins**. Leave one out and
it falls outwards: with no `medium`, a 550 px width keeps the `wide` value.

They resolve against the **carousel's own width**, not the viewport — the `AdwBreakpointBin`
pattern, so a carousel in a sidebar adapts to the space it was given rather than to the
window. The width measured is the border box, so `peek` (which is padding on that element)
cannot feed back into the bucket that chose it.

Regrouping keeps the slide that was leading the view on screen, so the page index follows the
content: at 3-per-page, page 2 leads with slide 4; drop to 1-per-page and you land on page 4,
still looking at slide 4.

### Navigation chrome
- `indicator` — `'dots'`, `'lines'`, or `'none'` to hide the pagination entirely, and
  `indicatorPosition` puts it on any edge. At `'left'` or `'right'` the carousel stacks it
  for you, by handing the indicator its own `orientation="vertical"` — pass that yourself
  when you render `CarouselIndicatorDots` / `CarouselIndicatorLines` standalone beside a
  track. Stacked, the line segments turn with the indicator so the deck still reads as one
  track rather than a ladder of unrelated dashes.
- `arrows` — overlays previous/next buttons on the carousel edges. They go `aria-disabled`
  at the first/last page unless the carousel wraps, and disappear when there is only one
  page. Label them with `previousLabel` / `nextLabel`.
- `autoPlay` — overlays a play/pause button in the corner. Turn `autoPlayControl` off only
  when you render your own; automatically moving content must be stoppable.

### Right to left
Direction is read off the DOM, so a `dir="rtl"` anywhere up the tree is all it takes — there
is no prop. Everything mirrors: paging runs right to left, `peek` and the arrows follow the
inline axis, the chevrons flip, dragging is reversed, and the **left** arrow key is the one
that moves forward, because arrow keys follow what the eye sees rather than the index.

Internally the scroll position is kept in logical coordinates — 0 on page 0, growing as you
page forward — because a right-to-left scroller reports `scrollLeft` as 0 at its right edge
and counts *down* into negatives from there.

### Accessibility
- `label` names the carousel region (`'Carousel'` by default). `role="region"` is dropped
  from the landmark tree without a name, so give it something specific when the page holds
  more than one carousel.
- Every visible string is a prop: `label`, `indicatorLabel`, `pageLabel`, `slideLabel`,
  `statusLabel`, `previousLabel`, `nextLabel`, `pauseLabel`, `playLabel`. `pageLabel`,
  `slideLabel` and `statusLabel` are formatters — `(index, total) => string`, all
  zero-based on `index`.
- A visually hidden `role="status"` region announces the page on every move — *"Page 3 of
  5"*, or whatever `statusLabel` returns. Both cues for the change are invisible to a
  screen reader otherwise: the dot moving, and the track scrolling under slides that are
  all in the DOM whichever page you are on. It falls silent (`aria-live="off"`) while an
  `autoPlay` rotation is running — a carousel that talks every few seconds is unusable —
  and speaks again the moment the rotation stops, the automatic pause while the keyboard
  is inside the carousel included. A single-page deck gets no live region at all.
- The arrows carry `aria-disabled` and ignore the press, rather than being truly
  `disabled`. A real `disabled` leaves the tab order the instant you page onto the last
  slide, so the focus you were pressing Enter on falls to the body and the deck you were
  navigating is gone.
- Every slide stays reachable by Tab, on screen or not — a control you cannot reach is
  worse than one you have to page to. Tabbing to something in an off-screen slide scrolls
  it in, and the carousel reads the new page back off that scroll, so the indicator and
  the arrows follow the focus.
- Keyboard: ←/→ (or ↑/↓ when vertical) page by one, `Home` and `End` jump to the first and
  last page.
- `autoPlay` pauses while the pointer is over the carousel, while the keyboard is inside
  it, during a drag, while the tab is in the background, and whenever the pause button says
  so. Pressing play overrides the hover and focus pauses, so the button never reads as dead.
- The page indicators are a `role="group"` of ordinary buttons, and the current one carries
  `aria-current="true"`. They are deliberately **not** a `tablist`: there are no tabpanels
  behind them, and the role would promise roving-tabindex arrow navigation that a page
  picker does not have.

### Wrapping: `loop` vs `infinite`
Both wrap around past the ends; they differ in how they get there.

- `loop` rewinds: stepping forward from the last page scrolls all the way back to the
  first. Nothing is cloned, so your children render exactly once.
- `infinite` is seamless: a copy of the last page is rendered *before* the first one (and
  a copy of the first page after the last), so paging past either end keeps moving in the
  same direction. Once the animation settles the carousel silently repositions onto the
  real page. Implies `loop`.

`infinite` clones your children, so avoid it for slides that own uncloneable side effects
— autoplaying media, unique DOM ids, per-slide data fetches. The clones are `aria-hidden`
and `inert`, so assistive tech and the tab order still see the real slides only.

Motion is perfectly seamless when the slide count is a multiple of `visibleSlides`. With
a remainder the last group overlaps the first one (5 slides in groups of 2 give pages
`[1,2] [3,4] [5,1]`), so the wrap shifts by the leftover slides.

```tsx
<Carousel visibleSlides={2} spacing={16} peek={40} focusActiveSlides arrows infinite>
  {items.map((item) => (
    <Card key={item.id}>{item.title}</Card>
  ))}
</Carousel>
```

### Page state
Uncontrolled by default — pass `defaultPage` to start somewhere other than the first page.

Pass `page` to control it, and then you own the position: the carousel renders the page you
give it and reports every user-driven move through `onPageChanged`, but it does not force
the prop back. If you drop that callback on the floor, the track ends up on one page while
the indicator and the arrows still describe another. Feed `onPageChanged` straight back into
`page` — the same contract as a controlled `<input>`.

```tsx
const [page, setPage] = useState(0);

<Carousel page={page} onPageChanged={setPage} indicator="dots" />;
```

### Imperative control
Pass a `ref` to drive the carousel from outside — a toolbar, a keyboard shortcut, a step in
a wizard.

```tsx
const carousel = useRef<CarouselHandle>(null);

<Carousel ref={carousel} indicator="dots" loop>…</Carousel>;

carousel.current?.next();
carousel.current?.goToSlide(4);
carousel.current?.page; // 4
```

| | |
| --- | --- |
| `next()` / `previous()` | Page by one. Wraps when `loop` or `infinite` is on. |
| `goTo(page, { animate })` | Absolute jump. Clamped into range — it never wraps. |
| `goToSlide(slide, { animate })` | Jump to the page holding a slide. Not the page index once `visibleSlides` is above 1. |
| `focus()` | Move keyboard focus to the track. |
| `play()` / `pause()` | Start and stop the `autoPlay` rotation, exactly as the button does. |
| `page`, `pageCount`, `isPlaying` | Live getters. |
| `element` | The scrollable track, for measuring or positioning. `null` before mount. |

Every method takes the same path as the arrows and the indicator, so wrapping, travel across
cloned pages, reduced motion and the `onPageChanged`-once rule behave the same however the
move started. In particular the handle **reports** rather than seizes: with a controlled
`page`, `next()` calls `onPageChanged` and leaves the prop to you, just like the arrow does.

The readable members are getters, not a frozen snapshot, so `handle.page` is already right on
the line after `next()` instead of a render later.

### Behaviour notes
- `defaultPage` is clamped into range and ignored entirely once `page` is passed.
- `onPageChanged` fires once per actual page change. A swipe emits a scroll event per
  frame, and navigating past the end without `loop` clamps back onto the current page —
  neither re-notifies you of a page you are already on.
- Programmatic scrolls honour `prefers-reduced-motion: reduce` by jumping straight to the
  page. A `behavior: 'smooth'` scroll overrides the stylesheet, so this cannot be undone
  from CSS.

### Guidelines
- Keep page count low (3–6). More pages need a compact indicator like lines.
- Reserve inline padding inside slides when `arrows` is on so the buttons don't sit on
  top of text.
- Use `orientation="vertical"` for feed-style layouts — arrows move to the top and
  bottom edges automatically, and `peek` insets the block axis instead.
- Pair `peek` with `infinite` so the leading edge is never blank on the first page.
- Remember that `focusActiveSlides` eats into the peek: a slide scaled to 80% gives back
  a tenth of its width at each side, so raise `peek` to keep the same visible sliver.
- Use `infinite` for image galleries where wrap-around is expected, and `loop` when the
  slides must not be duplicated.

---

Source: packages/react/src/components/Checkbox/README.md

Checkbox for multi-selection, following the GNOME HIG and Adwaita style.

### Guidelines
- Use for multi-selection where multiple items can be active at once.
- Prefer `Switch` over `Checkbox` for settings that take effect immediately.
- Use the `indeterminate` state for "select all" controls when only some items are selected.
- Always pair with a visible label or supply `aria-label`.
- Changes should not take effect until the user confirms (e.g. a Save button).

---

Source: packages/react/src/components/CheckRow/README.md

Activatable row with an integrated checkbox.

The entire row is a button — clicking anywhere toggles the checkbox. Use inside a
`BoxedList` when a user must select or deselect individual items in a list.

### Guidelines
- Use for multi-select scenarios (e.g., selecting files, features, or permissions).
- For a single on/off setting, prefer `SwitchRow`.
- Supports controlled (`checked`) and uncontrolled (`defaultChecked`) modes.

---

Source: packages/react/src/components/Chip/README.md

Compact pill-shaped label for tags, filters, and selection states.

Three usage modes:

- **Static** — visual label only. No interaction.
- **Removable** — add `onRemove` to show a × button that removes the chip.
- **Selectable** — add `selectable` + `selected` + `onToggle` for toggle behaviour.

Pair with `WrapBox` for multi-chip layouts.

---

Source: packages/react/src/components/ChoiceCardGroup/README.md

Card-based single-choice selector — large selectable cards instead of radio buttons.

```tsx
import { useState } from 'react';
import { ChoiceCardGroup } from '@gnome-ui/react';

const [plan, setPlan] = useState('personal');

<ChoiceCardGroup
  label="Account type"
  value={plan}
  onChange={setPlan}
  options={[
    { value: 'personal', title: 'Personal', description: 'For individual use' },
    { value: 'team', title: 'Team', description: 'For small groups' },
    { value: 'enterprise', title: 'Enterprise', description: 'Advanced controls and support' },
  ]}
/>
```

Mirrors the pattern used in GNOME Initial Setup / welcome flows (e.g. choosing an account type or a starting template).

Implements the WAI-ARIA `radiogroup`/`radio` pattern with roving tabindex: only the selected card (or the first enabled one, if none is selected) is in the tab order; ←/→/↑/↓ move the selection between cards.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `ChoiceCardOption<V>[]` | — | The list of selectable cards |
| `value` | `V` | — | The currently selected value |
| `onChange` | `(value: V) => void` | — | Called when the user selects a card |
| `label` | `string` | — | Visible label, rendered as the group's `<legend>` |
| `helperText` | `string` | — | Helper text below the label, hidden when `error` is set |
| `error` | `string` | — | Error message shown in place of `helperText` |
| `disabled` | `boolean` | `false` | Disables every card |

Each `ChoiceCardOption` accepts `value`, `title`, an optional `description`, an optional `icon` (from `@gnome-ui/icons`), and an optional `disabled` flag for that specific card.

### Guidelines

- Use `ChoiceCardGroup` when each option benefits from a title, description, or icon that wouldn't fit a compact radio button row — for a short list of simple text-only options, prefer `RadioButton` instead.
- The radio dot in each card's corner is decorative — selection state is conveyed to assistive technology via `aria-checked` on the card itself, not the dot.

---

Source: packages/react/src/components/Clamp/README.md

Constrains its child to a maximum width while allowing it to shrink freely on narrow screens — mirroring the Adwaita `AdwClamp` widget.

### Guidelines
- Use on settings pages and forms so content never becomes too wide to read comfortably.
- The default `maximumSize` is **600 px** — the Adwaita recommended narrow-content width.
- The element is always centred horizontally.
- Does not add any padding — wrap content in its own padded container as needed.

---

Source: packages/react/src/components/CoachMark/README.md

Onboarding **feature-discovery** pattern: spotlight a UI element and anchor a
callout bubble (title, description, actions) beside it to teach a user one
feature. Compose several with `CoachMarkTour`, or drive a single mark with
`open`.

Not a GNOME HIG widget — a pragmatic web-app pattern built on the same design
tokens and primitives (`Button`, `Portal`) as the rest of the library. Renders
into a portal, positions with a viewport-aware flip, traps focus in the bubble,
closes on <kbd>Escape</kbd>, and honours `prefers-reduced-motion`.

## Single mark

```tsx
import { useRef, useState } from 'react';
import { CoachMark } from '@gnome-ui/react/components/CoachMark';

function Example() {
  const target = useRef<HTMLButtonElement>(null);
  const [open, setOpen] = useState(true);

  return (
    <>
      <button ref={target}>Sync</button>
      <CoachMark
        open={open}
        targetRef={target}
        title="Sync your files"
        description="Press this to keep every device up to date."
        primaryAction={{ label: 'Got it', onClick: () => setOpen(false) }}
        onDismiss={() => setOpen(false)}
      />
    </>
  );
}
```

## Guided tour

```tsx
import { CoachMarkTour } from '@gnome-ui/react/components/CoachMark';

<CoachMarkTour
  open={running}
  steps={[
    { targetRef: searchRef, title: 'Search', description: 'Find anything fast.' },
    { targetRef: addRef, title: 'Add', description: 'Create a new item here.', placement: 'left' },
    { targetRef: menuRef, title: 'Menu', description: 'Everything else lives here.' },
  ]}
  onFinish={() => setRunning(false)}
  onSkip={() => setRunning(false)}
/>
```

Each step shows **Next**/**Done** (primary) and **Skip**/**Back** (secondary),
plus an "X of N" counter. Labels are overridable via `labels` for i18n.

---

Source: packages/react/src/components/CodeBlock/README.md

Static monospace code/config snippet display with optional line numbers and a trailing `CopyButton`.

```tsx
import { CodeBlock } from '@gnome-ui/react';

<CodeBlock
  filename="config.yaml"
  language="YAML"
  lineNumbers
  code={`server:\n  port: 8080\n  host: 0.0.0.0`}
/>
```

Distinct from `TerminalView`, which is for live, scrolling terminal output — `CodeBlock` is for a fixed snippet (a config example, a command to run, a code sample in documentation).

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `code` | `string` | — | The code/config content to display |
| `filename` | `string` | — | Optional filename shown in the header |
| `language` | `string` | — | Optional language label shown in the header |
| `lineNumbers` | `boolean` | `false` | Show line numbers in a gutter |
| `copyable` | `boolean` | `true` | Show a trailing `CopyButton` in the header |
| `wrap` | `boolean` | `false` | Wrap long lines instead of scrolling horizontally |

### Guidelines

- `CodeBlock` does not perform syntax highlighting — `language` is a plain cosmetic label, not a highlighting mode. For colored syntax highlighting, pair the raw text with a dedicated highlighter in your app and pass the already-highlighted markup as `children` to your own wrapper instead.
- The header (filename/language/copy button) is omitted entirely when none of `filename`, `language`, or `copyable` apply, so a minimal snippet doesn't render an empty bar.
- Enable `wrap` for snippets meant to be read top-to-bottom without horizontal scrolling (e.g. prose-adjacent examples); leave it off for shell commands and tabular output where line breaks are meaningful.

---

Source: packages/react/src/components/ColorPicker/README.md

Color palette picker following the Adwaita `GtkColorButton` + swatch pattern.

Renders a row of circular `ColorSwatch` items backed by a `radiogroup`.
Arrow keys move focus and selection. Optionally adds a "Custom…" button
backed by a hidden native `<input type="color">`.

The default palette matches the 9 Adwaita named colors (also used by `Avatar`).

```tsx
import { ColorPicker, GNOME_PALETTE } from "@gnome-ui/react";

const [color, setColor] = useState("#3584e4");

<ColorPicker value={color} onChange={setColor} />
<ColorPicker value={color} onChange={setColor} allowCustom />
```

### Keyboard
| Key | Action |
|-----|--------|
| `Arrow Right / Down` | Next swatch |
| `Arrow Left / Up` | Previous swatch |
| `Space / Enter` | Select focused swatch |

---

Source: packages/react/src/components/ColumnView/README.md

Multi-column sortable data table styled with Adwaita design tokens.

Mirrors `GtkColumnView` / `AdwColumnView` — the canonical GNOME widget for tabular data in file managers, settings lists, and dashboards.

**Guidelines (GNOME HIG):**
- Use for datasets where users benefit from comparing values across columns.
- Prefer `selectionMode="single"` for navigation (open on click) and `"multiple"` for batch operations.
- Always provide an `ariaLabel` describing the data set.
- Set `height` when the dataset may exceed the viewport — this enables vertical scroll with a sticky header.

---

Source: packages/react/src/components/ComboRow/README.md

Settings row with an inline combo selector at the trailing edge.

Mirrors `AdwComboRow` — a standard row layout with a dropdown for choosing among a set of options.
Use when the current value of a setting should be visible at a glance in the row.

### Guidelines
- Keep option labels short so they fit inside the trailing button.
- Provide a `subtitle` to clarify what the setting controls when the title alone is ambiguous.
- Supports controlled (`value`) and uncontrolled (`defaultValue`) modes.

---

Source: packages/react/src/components/ContributionGraph/README.md

A responsive activity heatmap calendar styled with Adwaita design tokens.
Colour intensity represents activity count per day.

**Guidelines (GNOME HIG):**
- Use inside a `Card` to frame the graph on a dashboard or profile page.
- Cells use the named accent colour token family from `GnomeProvider`; CSS accent values without token variants fall back to green.
- Cells expand to use available width and narrow layouts show fewer recent weeks before cells become too small.
- Dark mode is handled automatically via CSS custom properties — no extra configuration needed.
- Keyboard users can navigate every cell with arrow keys (`role="grid"`).

---

Source: packages/react/src/components/CopyButton/README.md

Icon button that copies a value to the clipboard, swapping to a checkmark and a "Copied!" tooltip as confirmation.

```tsx
import { CopyButton } from '@gnome-ui/react';

<CopyButton value="CVE-2024-3094" label="Copy CVE ID" />
```

Built on `IconButton`, so it accepts the same `variant`, `size`, and other button props. Writes via `navigator.clipboard.writeText` — no `@gnome-ui/platform` dependency required.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Text copied to the clipboard (required) |
| `label` | `string` | `"Copy"` | Accessible label / tooltip before copying |
| `copiedLabel` | `string` | `"Copied!"` | Accessible label / tooltip after a successful copy |
| `resetDelay` | `number` | `2000` | Milliseconds before reverting to `label` |
| `onCopied` | `(value: string) => void` | — | Called after a successful copy |
| `onCopyError` | `(error: unknown) => void` | — | Called if the Clipboard API is unavailable or the write is rejected |

Plus any `IconButtonProps` other than `icon`, `label`, `onClick`, and `tooltip` (e.g. `variant`, `size`, `disabled`).

### Guidelines

- Pass a specific `label` (e.g. `"Copy CVE ID"`) when the copied value's context isn't obvious from surrounding content.
- The copied confirmation is also announced to screen readers via a live region, independent of hover/focus.

---

Source: packages/react/src/components/CopyField/README.md

Read-only `TextField` with a built-in trailing `CopyButton`, for displaying copyable values (API keys, tokens, IDs) outside the `CveIdentifier`/`CweIdentifier`-style specialised components.

```tsx
import { CopyField } from '@gnome-ui/react';

<CopyField label="API key" value="sk-live-4242424242424242" />
<CopyField label="Webhook URL" value="https://example.com/hooks/abc123" monospace={false} />
```

The field is `readOnly`, not `disabled` — its text remains selectable for manual copy in addition to the button.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | The value displayed in the field and copied to the clipboard |
| `label` | `string` | — | Visible label rendered above the field |
| `helperText` | `string` | — | Helper text below the field, hidden when `error` is set |
| `error` | `string` | — | Error message shown in place of `helperText`; also applies the error border |
| `copyLabel` | `string` | `"Copy"` | Accessible label and tooltip for the copy button before copying |
| `copiedLabel` | `string` | `"Copied!"` | Accessible label and tooltip after a successful copy |
| `monospace` | `boolean` | `true` | Render the value in a monospace font — useful for tokens, keys, and IDs |

### Guidelines

- Always provide a `label` — it is the primary accessible name for the field.
- Set `monospace={false}` for values that read better in a proportional font, such as URLs or plain identifiers with mixed casing intended for reading rather than character-by-character verification.
- Use `error` to communicate a revoked/expired value rather than a validation failure — since the field is read-only, there's nothing for the user to correct.

---

Source: packages/react/src/components/CountDownTimer/README.md

Displays a countdown timer showing the remaining time until a specified end date.

### Guidelines
- Use `format="time"` to display countdown in HH:MM:SS format.
- Use `format="date"` to display the target end date.
- Provide an `action` callback that executes when the countdown reaches zero.
- Choose the `variant` that matches the urgency: `accent` → neutral, `success` → positive, `warning` → caution, `destructive` → urgent.
- The component automatically switches to destructive styling when time runs out.

---

Source: packages/react/src/components/CveIdentifier/README.md

Monospace CVE identifier for vulnerability tables, findings, and report
references.

```tsx
import { CveIdentifier } from "@gnome-ui/react";

<CveIdentifier cveId="CVE-2024-3094" />
<CveIdentifier cveId="CVE-2024-3094" source="nvd" />
<CveIdentifier cveId="CVE-2024-3094" link={false} />
```

The component normalizes input to uppercase and marks invalid identifiers with
`data-valid="false"`. CVE IDs follow the `CVE-YYYY-NNNN` shape, with at least
four digits in the sequence number.

---

Source: packages/react/src/components/CvssScore/README.md

Compact CVSS score display for vulnerability tables, finding summaries, and CVE
detail surfaces.

```tsx
import { CvssScore } from "@gnome-ui/react";

<CvssScore score={9.8} />
<CvssScore score={0} severity="minimal" />
```

CVSS-derived ratings follow the official qualitative ranges:

`0.0 none`, `0.1–3.9 low`, `4.0–6.9 medium`, `7.0–8.9 high`,
`9.0–10.0 critical`.

Use the `severity` override when displaying a scanner-provided severity. This is
how `minimal` can appear alongside a score without treating it as an official
CVSS qualitative rating.

---

Source: packages/react/src/components/CvssVector/README.md

# CvssVector

Readable CVSS vector display for vulnerability reports, scan details, and CVE
analysis views.

```tsx
import { CvssVector } from "@gnome-ui/react";

<CvssVector vector="CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H" />
```

The component renders the raw vector and expands CVSS 3.0 / 3.1 base metrics
into labels such as Attack Vector, Attack Complexity, Privileges Required,
Confidentiality, Integrity, and Availability.

Use it next to `CvssScore` when a report needs both the qualitative score and
the underlying vector that produced it.

Unknown tokens are still rendered and marked with `data-known="false"` so
scanner-specific or future CVSS values remain visible instead of being dropped.

---

Source: packages/react/src/components/CweIdentifier/README.md

# CweIdentifier

Monospace CWE identifier for vulnerability reports, weakness taxonomies, and
scan result summaries.

```tsx
import { CweIdentifier } from "@gnome-ui/react";

<CweIdentifier cweId="CWE-79" />
```

The component normalizes numeric input such as `79` to `CWE-79`, validates the
identifier, and links to the matching MITRE CWE definition by default.

Use it alongside `CveIdentifier`, `CvssScore`, `CvssVector`, and
`VulnerabilityFinding` when a report needs to connect an issue to both a
specific vulnerability and its underlying weakness category.

Invalid values remain visible and are marked with `data-valid="false"` so
scanner output is not silently dropped.

---

Source: packages/react/src/components/DatePicker/README.md

A [`Popover`](../Popover)-anchored [`Calendar`](../Calendar) behind an
entry-styled trigger — mirrors the `GtkCalendar` + `GtkPopover` composition
GNOME apps use for date entry.

The trigger reads out the formatted selection (or a placeholder), opens the
calendar on click, <kbd>Enter</kbd>/<kbd>Space</kbd>, or <kbd>↓</kbd>, and
closes it once a day is chosen — returning focus to the trigger. All keyboard
navigation inside the panel is provided by `Calendar` (arrow keys, Home/End,
PageUp/PageDown, Enter to select).

## Usage

```tsx
import { DatePicker } from '@gnome-ui/react/components/DatePicker';

function Example() {
  const [date, setDate] = useState<Date | null>(null);
  return <DatePicker label="Start date" value={date} onChange={setDate} />;
}
```

Restrict the range and change the displayed format:

```tsx
<DatePicker
  min={new Date()}
  max={new Date(2027, 11, 31)}
  formatOptions={{ dateStyle: 'full' }}
  weekStartsOn={0}
/>
```

## Date and time

`showTime` adds `TimePicker`'s hour/minute columns under the calendar, turning
the emitted `Date` from a civil date into a point in time:

```tsx
<DatePicker label="Appointment" showTime hourCycle={12} minuteStep={15} />
```

Two behaviours change with it:

- **The popover no longer closes on a day click** — there is still a time to
  set. It closes on the Done button (`doneLabel`), or the usual Escape/outside
  click.
- **The time is carried across day clicks.** `Calendar` hands back local
  midnight, so each pick is merged with the clock currently shown. Before any
  day is chosen the columns start at 12:00, and editing them first attaches the
  reading to today.

`onChange` still fires on every change, so a controlled `value` follows the
calendar and the spinners live; Done only dismisses.

---

Source: packages/react/src/components/DateRangePicker/README.md

A [`Popover`](../Popover)-anchored [`CalendarRange`](../CalendarRange) behind an
entry-styled trigger — the range counterpart of `DatePicker`, and the same
`GtkCalendar` + `GtkPopover` composition GNOME apps use for date entry.

The trigger reads out both ends (`Aug 10, 2026 – Aug 19, 2026`) or a
placeholder, and opens on click, <kbd>Enter</kbd>/<kbd>Space</kbd> or
<kbd>↓</kbd>. Because `CalendarRange` only emits a finished range, the popover
stays open through the first click and closes on the second — returning focus to
the trigger.

## Usage

```tsx
import { DateRangePicker } from '@gnome-ui/react/components/DateRangePicker';

function Example() {
  const [range, setRange] = useState<DateRange | null>(null);
  return <DateRangePicker label="Stay" value={range} onChange={setRange} />;
}
```

`onChange` receives `{ start, end }` with both ends filled in — there is no
half-emitted range to guard against.

## Two months, or however many

The popover shows `visibleMonths={2}` panels by default, paged together, so a
range spanning months needs no navigation. Pass `1` for a compact picker, or
more for a wide one.

## Presets

`presets` adds one-click shortcuts beside the calendar. A preset's `range` may
be a literal or a function, so relative shortcuts are computed at click time:

```tsx
<DateRangePicker
  label="Report period"
  presets={[
    { label: 'Last 7 days', range: () => ({ start: addDays(new Date(), -6), end: new Date() }) },
    { label: 'This month', range: () => ({ start: startOfMonth(new Date()), end: new Date() }) },
  ]}
/>
```

Choosing a preset commits the range and closes the popover, exactly like a
second day click.

## Props

`value` / `defaultValue` (a `DateRange`), `onChange`, `min`, `max`, `minRange`,
`maxRange`, `visibleMonths`, `presets`, `weekStartsOn`, `locale`,
`formatOptions`, `placeholder`, `separator`, `label`, `aria-label`,
`showWeekNumbers`, `disabled`, `placement`, `id`, `className`.

## Date and time

`showTime` gives **each end its own** hour/minute columns — the shape bookings
need — plus a Done button, since the second day click no longer finishes the
selection:

```tsx
<DateRangePicker label="Stay" showTime hourCycle={12} minuteStep={15} />
```

The calendar keeps handing back civil dates, so both clock readings are merged
into the pair on every change. On a **single-day** range the two times can
invert; the end you just edited wins and the other follows it, so `start` is
never after `end`. Committing a fresh pair of day clicks with inverted times
collapses the end onto the start.

`startTimeLabel` / `endTimeLabel` name the two column groups (visibly and for
screen readers, as `"Start hours"`, `"End minutes"`…), and `doneLabel` renames
the closing button. Note that `minRange` / `maxRange` still count **calendar
days**, not elapsed hours.

---

Source: packages/react/src/components/Dialog/README.md

Blocking modal dialog — two modes in one component.

**Standard** — `title` + `children` + `buttons[]`.

**Alert** (`role="alertdialog"` + `responses[]` + `onResponse`) — for confirmations
and destructive-action warnings. Screen readers announce it immediately.
Escape / backdrop fire the first non-destructive response. Mirrors `AdwAlertDialog`.

For the app-info dialog, use `<AboutDialog />` instead.

---

Source: packages/react/src/components/Divider/README.md

Horizontal rule with an optional centred label — common auth/login-form pattern.

```tsx
import { Divider } from '@gnome-ui/react';

<Divider>OR</Divider>
<Divider>Continue with</Divider>
<Divider />
```

### Divider vs Separator

| | Content slot | Orientation |
|---|---|---|
| `Separator` | None — a bare dividing line | Horizontal or vertical |
| `Divider` | Optional centred label | Horizontal only |

Use `Separator` for structural dividers inside lists (`BoxedList`, `ExpanderRow`) or between toolbar sections. Use `Divider` specifically when you need a labelled break — most commonly "OR" between two sign-in methods.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Optional centred label |

### Guidelines

- Without `children`, renders as a single full-width line — functionally equivalent to a horizontal `Separator`. Prefer `Separator` in that case for clarity.
- The accessible name is set automatically from a string label; pass a non-string `children` (e.g. an icon + text) and it will still render visually, but consider adding your own `aria-label` in that case.

---

Source: packages/react/src/components/Drawer/README.md

Slide-over panel for supplementary React content. Use `side` to open from the
left or right, `size` for classic or wide widths, and pass the body through
`children` or the `content` prop.

`variant` controls how the drawer displaces the page. The default
`"overlay"` floats above the page behind a dismissible, focus-trapping
backdrop. `"push"` renders in normal document flow instead — no portal, no
backdrop, no focus trap, since the rest of the page stays visible and
interactive — so place it next to your main content inside a flex/grid
container and it shoulders that content aside as it opens.

Opening a second `Drawer` from inside a drawer's content (or `content` prop)
automatically makes it narrower than its parent — each nesting level scales
the preset width down until it hits a minimum, so stacked drawers read as a
drill-in hierarchy instead of identical overlapping panels.

Pass `rail` to render a narrow icon strip on the drawer's inner edge (the
edge facing the backdrop) for switching between related panels without
closing the drawer — for example, a fixed rail of related sections while the
drawer's own `content` swaps underneath it. The rail is presentational only:
each entry's `onClick` is the caller's responsibility, and `active` just
marks which entry looks pressed.

---

Source: packages/react/src/components/Dropdown/README.md

Expandable option list following the Adwaita combo-row / drop-down style.

### Guidelines
- Use when the user must pick exactly one option from a list of 4 or more.
- For 2–3 options prefer **Radio Buttons** (all choices visible at once).
- Keep labels short — one to three words.
- Provide a meaningful `placeholder` that describes what to select.
- The list flips above the trigger when there is not enough space below.
- Keyboard: Space / Enter / ↓ opens; ↑↓ navigates; Enter selects; Escape closes.

---

Source: packages/react/src/components/EmojiPicker/README.md

Searchable emoji grid in a `Popover`. Mirrors `GtkEmojiChooser`.

```tsx
import { EmojiPicker, IconButton } from '@gnome-ui/react';
import { EmojiObjects } from '@gnome-ui/icons';

<EmojiPicker onSelect={(emoji) => console.log(emoji)}>
  <IconButton icon={EmojiObjects} label="Insert emoji" tooltip="Insert emoji" />
</EmojiPicker>
```

A search field filters the flat emoji list by name; otherwise emoji are grouped by category with a jump-to-category tab bar at the bottom, matching the real Adwaita widget's clickable category strip.

Recently used emoji are tracked in memory for the current session only — they are **not** persisted across page reloads.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onSelect` | `(emoji: string) => void` | — | Called with the emoji character when the user picks one |
| `children` | `ReactElement` | — | The trigger element that opens the picker |
| `placement` | `PopoverPlacement` | `'bottom'` | Preferred popover placement relative to the trigger |
| `maxRecent` | `number` | `12` | Maximum number of recently used emoji shown |

### Guidelines

- The curated emoji set covers common entries per category — it is not an exhaustive Unicode dataset. For a full emoji keyboard, use the operating system's native picker (most OSes bind one to a system shortcut).
- The trigger is any single element (typically an `IconButton`) — `EmojiPicker` clones it the same way `Popover` does, so existing `onClick` handlers on the trigger keep working.

---

Source: packages/react/src/components/EntryRow/README.md

Row with an inline text entry field.

Mirrors `AdwEntryRow` — the `title` acts as a floating label that rises above the
input when the field is focused or has content. Use inside a `BoxedList` for
settings that require free-form text input.

### Guidelines
- Use `title` as the label, not as a placeholder — it is always visible.
- Add `trailing` widgets for actions like copy, clear, or reveal-password.
- For passwords, set `type="password"` and provide a trailing reveal button.
- Supports controlled (`value`) and uncontrolled (`defaultValue`) modes.

---

Source: packages/react/src/components/Expander/README.md

Standalone disclosure triangle + collapsible content — mirrors `GtkExpander`.

```tsx
import { Expander } from '@gnome-ui/react';

<Expander label="Show advanced options">
  <TextField label="Custom endpoint" />
</Expander>
```

A bare, unstyled counterpart to `ExpanderRow`, which is a `BoxedList`-row variant with title/subtitle/leading/trailing slots and a card look. Use `Expander` outside a settings-row context — e.g. "Show advanced options" in a form, or "Show details" under an error message.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `ReactNode` | — | Clickable header label (required) |
| `children` | `ReactNode` | — | Content revealed when expanded |
| `expanded` | `boolean` | — | Controlled expanded state |
| `defaultExpanded` | `boolean` | `false` | Initial expanded state when uncontrolled |
| `onExpandedChange` | `(expanded: boolean) => void` | — | Called when the expanded state changes |
| `disabled` | `boolean` | `false` | Disables the toggle |

### Guidelines

- Use for optional, secondary content that most users won't need — advanced settings, verbose error details, raw data.
- For a settings-list row with title/subtitle and nested rows, use `ExpanderRow` instead.
- Content stays mounted in the DOM while collapsed (revealed via a CSS grid-height animation), so state inside it isn't lost when toggled.

---

Source: packages/react/src/components/ExpanderRow/README.md

Collapsible `ActionRow` that reveals nested rows on activation.

Mirrors `AdwExpanderRow` — clicking the header row toggles a smooth reveal
animation exposing child rows. Supports both **controlled** and **uncontrolled**
expand state.

### Guidelines
- Always wrap in `BoxedList` for the canonical GNOME appearance.
- Use for settings groups where sub-options only make sense when a parent option is relevant.
- Nest `ActionRow`, `ButtonRow`, or any row-shaped element as children — separators are inserted automatically.
- Use `trailing` for a value label or status indicator; stop event propagation inside interactive trailing widgets.
- Do not nest `ExpanderRow` more than one level deep.

---

Source: packages/react/src/components/FieldGroup/README.md

Generic form-field grouping with a shared label, help text, and error message, for arbitrary fields outside a `BoxedList`.

```tsx
import { FieldGroup, RadioButton } from '@gnome-ui/react';

<FieldGroup label="Notification method" helperText="Choose how you want to be notified.">
  <label style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
    <RadioButton name="notify" value="email" /> Email
  </label>
  <label style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
    <RadioButton name="notify" value="sms" /> SMS
  </label>
</FieldGroup>
```

`PreferencesGroup` is scoped specifically to wrapping settings rows inside a `BoxedList` — use `FieldGroup` for a plain `<fieldset>`/`<legend>` grouping around any set of related form controls (e.g. a radio group or several checkboxes sharing one label and error), independent of the settings-page layout.

Renders a native `<fieldset>`, so `disabled` automatically disables every descendant form control for free — no need to thread it through manually.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Group heading, rendered as the `<legend>` (required) |
| `helperText` | `string` | — | Helper text below the label, hidden when `error` is set |
| `error` | `string` | — | Error message shown in place of `helperText`, announced via `role="alert"` |
| `disabled` | `boolean` | `false` | Disables the `<fieldset>` and every descendant form control |
| `children` | `ReactNode` | — | The grouped fields |

### Guidelines

- Prefer `FieldGroup` over a plain `<div>` wrapper whenever several related controls (radios, checkboxes, a custom composite field) need one shared label and error — it gives you correct `<fieldset>`/`<legend>` semantics for free.
- Show `error` only after the user has interacted with the group (on blur or on submit), not while they're still making a first selection.

---

Source: packages/react/src/components/FileDropZone/README.md

Drag-and-drop file upload target with hover/active states, falling back to a `GtkFileDialog`-style click-to-browse trigger.

```tsx
import { FileDropZone } from '@gnome-ui/react';

<FileDropZone
  onFilesSelected={(files) => upload(files)}
  onError={(message) => showToast(message)}
  accept="image/*"
  maxSize={5 * 1024 * 1024}
  helperText="PNG or JPG, up to 5 MB"
/>
```

The whole zone is a single clickable/keyboard-focusable region: click or press Enter/Space to open the native file browser, or drag a file over it to drop.

Native `accept` only restricts the browse dialog, not drag-and-drop — dropped files are re-validated against both `accept` and `maxSize` before `onFilesSelected` is called, so both paths enforce the same constraints.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onFilesSelected` | `(files: File[]) => void` | — | Called with the accepted files, whether dropped or picked |
| `onError` | `(message: string) => void` | — | Called once per rejected file, with a human-readable reason |
| `accept` | `string` | — | MIME types / extensions accepted, e.g. `"image/*"` or `".pdf,.docx"` |
| `multiple` | `boolean` | `false` | Allow selecting or dropping more than one file |
| `maxSize` | `number` | — | Maximum file size in bytes |
| `disabled` | `boolean` | `false` | Disables the drop zone and browse trigger |
| `label` | `string` | `'Drag files here or click to browse'` | Primary label |
| `helperText` | `string` | — | Helper text below the label (e.g. accepted formats or a size hint) |

### Guidelines

- Use `helperText` to state the accepted formats and size limit up front — it saves a round trip through `onError` for the common case.
- The icon swaps to `folder-drag-accept` (mirroring Nautilus's own drag-and-drop indicator) while a file is dragged over the zone, giving a clear "drop here" affordance beyond just the border color change.

---

Source: packages/react/src/components/FileTypeIcon/README.md

Small icon — optionally a thumbnail — resolved from a file's MIME type or name extension. Useful for file-manager-style listings.

```tsx
import { FileTypeIcon } from '@gnome-ui/react';

<FileTypeIcon name="report.pdf" />
<FileTypeIcon mimeType="image/png" />
<FileTypeIcon name="cover.jpg" thumbnail={thumbnailUrl} />
<FileTypeIcon isFolder />
```

Icons mirror the freedesktop.org icon-naming convention already shipped in `@gnome-ui/icons` (`image-x-generic`, `audio-x-generic`, `x-office-document`, etc.), falling back to the generic file icon (`text-x-generic`) when the type can't be resolved.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | File name (e.g. `"report.pdf"`) — resolves the icon from its extension |
| `mimeType` | `string` | — | MIME type (e.g. `"application/pdf"`, `"inode/directory"`) — takes precedence over `name` |
| `isFolder` | `boolean` | `false` | Renders the folder icon regardless of `name`/`mimeType` |
| `thumbnail` | `string` | — | Image URL. When provided, renders the image instead of the resolved icon |
| `label` | `string` | generated | Accessible label. Auto-generated from the resolved category (e.g. `"PDF document"`) when omitted |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Icon/thumbnail size |

### Resolved categories

`folder`, `image`, `audio`, `video`, `pdf`, `archive`, `document`, `spreadsheet`, `presentation`, `font`, `executable`, `text`, and `unknown` (fallback).

### Guidelines

- Prefer `mimeType` when you have a real MIME type (e.g. from the File API or a server response) — it's more reliable than guessing from a file name, and it's the only way to resolve `folder` via `"inode/directory"` without the explicit `isFolder` prop.
- Pass `thumbnail` for image/video files where a real preview is available; the layout doesn't shift since the thumbnail is sized to match the icon.

---

Source: packages/react/src/components/FilterableMultiSelectDropdown/README.md

`MultiSelectDropdown` plus a filter field for narrowing long option lists.

```tsx
import { useState } from 'react';
import { FilterableMultiSelectDropdown } from '@gnome-ui/react';

const [countries, setCountries] = useState<string[]>(['us']);

<FilterableMultiSelectDropdown
  aria-label="Countries"
  options={[
    { value: 'us', label: 'United States' },
    { value: 'gb', label: 'United Kingdom' },
    { value: 'de', label: 'Germany' },
  ]}
  value={countries}
  onChange={setCountries}
/>
```

Same overall shape as `MultiSelectDropdown` — a trigger summarizing the selection, opening a checkbox listbox — but opening it also focuses a filter field pinned above the list. Typing narrows `options` to those whose `label` or `description` contains the query (case-insensitive). Filtering only affects what's shown, never the underlying selection: values selected before a query hides their option stay selected, and the trigger keeps summarizing the real `value`.

Use this instead of plain `MultiSelectDropdown` once the option list is long enough that scanning it visually stops being the fastest way to find an entry (timezones, countries, package names, …). For short, fixed lists `MultiSelectDropdown` is simpler and needs no extra field.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `MultiSelectDropdownOption<V>[]` | — | The list of selectable options |
| `value` | `V[]` | — | The currently selected values |
| `onChange` | `(value: V[]) => void` | — | Called with the full updated selection whenever an option is toggled |
| `placeholder` | `string` | `'Select options'` | Shown on the trigger when no option is selected |
| `filterPlaceholder` | `string` | `'Filter options…'` | Placeholder for the filter field shown once the list is open |
| `aria-label` | `string` | — | Accessible label for the control |
| `disabled` | `boolean` | `false` | Disables the entire control |

### Guidelines

- Opening the list (click, Enter/Space/↑/↓ on the trigger) moves keyboard focus into the filter field so typing can start immediately — unlike `MultiSelectDropdown`, where focus stays on the trigger button.
- ↑/↓ move the active option among the *currently filtered* results; Home/End jump to the first/last filtered option; Enter toggles the active option without closing the list; Escape or Tab closes it and returns focus to the trigger.
- Space is ordinary filter text here, not a toggle shortcut — that's the one interaction that differs from `MultiSelectDropdown`'s listbox, since the listbox no longer holds keyboard focus while open.
- The query resets every time the list closes, so reopening always shows the full option list again.
- Selection state is conveyed via `aria-selected` on each `role="option"`, exactly as in `MultiSelectDropdown`.

---

Source: packages/react/src/components/FontPicker/README.md

Button that opens a family/size/weight chooser. Mirrors `GtkFontDialogButton`: the trigger itself previews the current selection rendered in that font.

```tsx
import { useState } from 'react';
import { FontPicker } from '@gnome-ui/react';

const [font, setFont] = useState({ family: 'Cantarell', size: 11, weight: 400 });

<FontPicker value={font} onChange={setFont} />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `FontValue` (`{ family, size, weight }`) | — | Current font selection |
| `onChange` | `(value: FontValue) => void` | — | Called whenever the family, size, or weight changes |
| `families` | `string[]` | `DEFAULT_FONT_FAMILIES` | Families offered in the family dropdown |
| `minSize` | `number` | `6` | Minimum selectable point size |
| `maxSize` | `number` | `96` | Maximum selectable point size |
| `placement` | `PopoverPlacement` | `'bottom'` | Preferred popover placement relative to the trigger |
| `disabled` | `boolean` | `false` | Disables the trigger and popover contents |
| `label` | `string` | `'Font'` | Accessible label prefix for the trigger button |

`weight` uses the standard 9-step scale (100 Thin – 900 Black); `FONT_WEIGHTS` is exported for building your own weight UI if needed.

### Guidelines

- Pass your app's actual available fonts via `families` — the default list is a small, representative placeholder (GNOME's default UI/document/monospace families plus the generic CSS keywords), not a real font enumeration.
- The trigger's own text renders in the selected family and weight, matching `GtkFontDialogButton`'s live-preview behavior — no separate preview area is needed.

---

Source: packages/react/src/components/Footer/README.md

Bottom bar with leading/trailing slots and optional center content.

Mirrors the `HeaderBar` pattern at the bottom of a view or window.

### Guidelines
- Use **flat** buttons (`variant="flat"`) for actions inside the footer.
- Keep content minimal — copyright, secondary links, status info.
- Place primary info (copyright, version) on the **leading** side.
- Place secondary actions (links, settings) on the **trailing** side.
- Use `flat` when the footer is visually separated from content by another boundary.

---

Source: packages/react/src/components/Frame/README.md

Simple bordered surface with `border-radius` but no background fill.

Use to visually delimit a region without adding the elevated appearance of a `Card`.
Mirrors `GtkFrame` default styling and the libadwaita `.frame` style class.

### Guidelines
- Use `Frame` when you need a visible boundary without a background (e.g. wrapping a media preview, a canvas area, or a list).
- Use `Card` when you need an elevated surface with its own background.
- `Frame` clips its children via `overflow: hidden`, so inner content respects the border radius.

---

Source: packages/react/src/components/HeaderBar/README.md

Title bar with centered title and leading/trailing action slots.

Mirrors the Adwaita `AdwHeaderBar` pattern.

### Guidelines
- Use **flat** buttons (`variant="flat"`) for all controls inside the header bar.
- Keep the title short and centered — it should name the current view, not the app.
- Place primary navigation controls (back, menu) on the **leading** side.
- Place secondary actions (add, share, overflow menu) on the **trailing** side.
- Use at most 2–3 actions per side; move the rest into an overflow menu.
- Use `flat` on the topmost bar of a full-window layout to blend with the window chrome.

---

Source: packages/react/src/components/Highlight/README.md

Wraps every occurrence of `query` within `text` in a `<mark>` element.

Pairs with `SearchBar`'s suggestion list and any filterable list/table to show users which part of a result matched what they typed.

```tsx
import { Highlight } from '@gnome-ui/react';

<Highlight text="Preferences for accessibility" query="access" />
<Highlight text="The quick brown fox" query={['quick', 'fox']} />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | `string` | — | Full text to render |
| `query` | `string \| string[]` | — | Term or terms to highlight. Pass an array to highlight multiple distinct terms at once |
| `caseSensitive` | `boolean` | `false` | Match case-sensitively |

### Guidelines

- Empty or whitespace-only terms are ignored automatically — safe to pass a `query` derived directly from a live search input without checking for blank strings first.
- Query terms are matched literally; regex special characters (e.g. `(`, `.`, `[`) are escaped internally, so they never need escaping by the caller.
- For a multi-word search (e.g. `"quick fox"`), split on whitespace and pass the array (`query={['quick', 'fox']}`) rather than the whole phrase, so each word highlights independently even when they don't appear adjacent in the result.

---

Source: packages/react/src/components/Icon/README.md

Renders an [`@gnome-ui/icons`](https://www.npmjs.com/package/@gnome-ui/icons) definition as an inline SVG.

Icons are **framework-agnostic** path data objects — the `Icon` component is the React adapter.
Uses `currentColor` so the icon automatically inherits the parent's text color.

### Guidelines
- Pass `label` only when the icon stands alone (no sibling text). Otherwise omit it — the icon is marked `aria-hidden`.
- Use `size="sm"` (12 px) for dense UIs, `"md"` (16 px, default) for inline icons, `"lg"` (20 px) for standalone icons.
- Pair with `<Button variant="flat">` for icon buttons in header bars.

### Color
Pass `color` to apply a named GNOME palette token. Omit it (or use
`"default"`) to inherit `currentColor` from the parent.

Accepted values:
`"blue"` · `"green"` · `"yellow"` · `"orange"` ·
`"red"` · `"purple"` · `"brown"` · `"default"`

```tsx
<Icon icon={Search} color="blue" />
<Icon icon={Search} color="red" size="lg" />
<Icon icon={Search} /> {/* inherits currentColor */}
```

### Usage
```tsx
import { Icon } from "@gnome-ui/react";
import { Search } from "@gnome-ui/icons";

<Icon icon={Search} size="md" label="Search" />
```

### Animated icons

Icons marked `animated: true` (e.g. `Syncing`, `Recording`) render as a
static frame through `Icon` — wrap them in
[`AnimatedIcon`](?path=/docs/components-animatedicon--docs) to play the
animation.

---

Source: packages/react/src/components/IconButton/README.md

Icon-only action button composed from `Button`, `Icon`, and optionally `Tooltip`.

`label` is required as the accessible name since the button has no visible text. Optionally pass `tooltip` to show it on hover/focus.

```tsx
import { Search, Settings } from '@gnome-ui/icons';
import { IconButton } from '@gnome-ui/react';

<IconButton icon={Search} label="Search" />
<IconButton icon={Settings} label="Settings" variant="flat" tooltip="Open settings" />
```

### Variants

| Variant | Use case |
|---------|----------|
| `default` | Standard toolbar action |
| `suggested` | Primary recommended action |
| `destructive` | Irreversible action (delete, remove) |
| `flat` | Low-emphasis, no background |
| `raised` | Elevated surface (floating button) |
| `osd` | On-screen display overlay (media controls) |

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `icon` | `IconDefinition` | — | Icon from `@gnome-ui/icons` |
| `label` | `string` | — | Accessible name (required) |
| `variant` | `IconButtonVariant` | `"default"` | Visual style |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Button size |
| `iconSize` | `IconSize` | matches `size` | Override icon size independently |
| `tooltip` | `string` | — | Tooltip text shown on hover/focus |
| `tooltipPlacement` | `TooltipPlacement` | `"top"` | Preferred tooltip position |
| `tooltipDelay` | `number` | — | Tooltip delay in ms |

### Guidelines

- Always provide a descriptive `label` — it is the only accessible name.
- Use `tooltip` to expose the label visually when context is ambiguous.
- Use `osd` variant for media overlays on dark or blurred backgrounds.

---

Source: packages/react/src/components/InlineViewSwitcher/README.md

Compact inline view switcher for placing inside content areas, cards, or toolbars.

Use when `ViewSwitcher` (header-bar sized) is too heavy — `InlineViewSwitcher` sits
comfortably inline with other content. Mirrors `AdwInlineViewSwitcher`
(libadwaita 1.7 / GNOME 48).

Compose with `InlineViewSwitcherItem`. Keyboard: **← →** cycle, **Home / End** jump.

### Variants
| Variant | When to use |
|---------|-------------|
| `default` | Standalone control with clear elevation — inside cards or content areas |
| `flat` | Inside a toolbar or header bar background — blends with the surface |
| `round` | Prominent pill shape with accent active indicator |
| `pill` | Segmented-control style — active item lifted, no accent color (Following tabs) |

### Guidelines
- Prefer `ViewSwitcher` in a `HeaderBar` for top-level navigation.
- Use `InlineViewSwitcher` for secondary, in-context view switching (e.g. chart type, layout mode).
- Always provide an `aria-label` on the container and `aria-label` on icon-only items.

---

Source: packages/react/src/components/Kbd/README.md

Standalone single key-cap for inline instructional text.

```tsx
import { Kbd } from '@gnome-ui/react';

<p>Press <Kbd>Enter</Kbd> to continue.</p>
<p>Hold <Kbd>Shift</Kbd> while dragging to select multiple files.</p>
```

Complements `ShortcutLabel`, which only renders full `+`-delimited combos (`"Ctrl+S"`) and doesn't expose its per-key styling on its own — use `Kbd` when referencing a single key outside of a shortcut combo.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `string` | — | The key name (e.g. `"Enter"`, `"Esc"`, `"A"`) |
| `symbols` | `boolean` | `true` | Normalise common key names to their Unicode symbol (e.g. `"Enter"` → `↵`). Matches `ShortcutLabel`'s mapping |

### Guidelines

- Set `symbols={false}` when the raw key name reads more clearly in prose than its glyph (e.g. `"Esc"` is often clearer than `⎋` in a help article).
- When a symbol is substituted, `Kbd` sets `aria-label` to the original key name so screen readers announce `"Enter"` rather than the glyph.

---

Source: packages/react/src/components/LevelBar/README.md

Discrete level indicator with colour-coded low/high offset zones — mirrors `GtkLevelBar`.

```tsx
import { LevelBar } from '@gnome-ui/react';

<LevelBar value={0.82} low={0.25} high={0.9} aria-label="Disk usage" />
```

### When to use which bar

| Component | Use for |
|-----------|---------|
| `ProgressBar` | Determinate/indeterminate task progress (a download, an install) |
| `LevelBar` | A scalar measurement or gauge (disk usage, battery, signal strength) |
| `SegmentedBar` | A proportional breakdown across categories that sum to a whole |

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current value, clamped to `[min, max]` (required) |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `1` | Maximum value |
| `low` | `number` | — | Threshold at or below which the bar renders in `lowVariant` |
| `lowVariant` | `LevelBarVariant` | `"warning"` | Colour used when `value <= low` |
| `high` | `number` | — | Threshold at or above which the bar renders in `highVariant` |
| `highVariant` | `LevelBarVariant` | `"error"` | Colour used when `value >= high` |
| `variant` | `LevelBarVariant` | `"accent"` | Colour used between `low` and `high` |
| `discrete` | `boolean` | `false` | Render as a row of blocks instead of a continuous fill |
| `numBlocks` | `number` | `10` | Number of blocks when `discrete` is `true` |

### Guidelines

- Set `low`/`high` when a value entering a zone is meaningful to the user — e.g. a disk-usage bar turning `error` above 90 %, or a battery bar turning `warning` below 20 %. Omit them for a plain single-colour gauge.
- Use `discrete` mode for signal-strength or step-count style indicators, where individual increments matter more than the exact fraction.
- Always provide an `aria-label` or `aria-labelledby` — the bar renders as `role="meter"`, the WAI-ARIA role for a scalar measurement, distinct from `role="progressbar"`.

---

Source: packages/react/src/components/Link/README.md

Inline hyperlink following GNOME HIG.

- Accent-coloured text with an animated underline on hover.
- `external` prop (or `target="_blank"`) opens in a new tab safely and appends a visual ↗ indicator.
- Fully keyboard accessible with a focus ring.

---

Source: packages/react/src/components/LinkedGroup/README.md

Renders children as a single visually-connected unit with no gap and merged borders.

The canonical GNOME pattern for button groups and segmented inputs — mirrors the
libadwaita `.linked` style class.

### How it works
- First child retains its outer border radius (left side or top side).
- Last child retains its outer border radius (right side or bottom side).
- All middle children have their border radius removed.
- Adjacent borders are collapsed to a single pixel via `margin: -1px`.
- Hovered and focused children are raised with `z-index` so their border stays visible.

### Guidelines
- Use for tightly related actions that form a logical group (Cut/Copy/Paste, Zoom −/+).
- Use `vertical` for stacked inputs or option lists.
- Prefer `ToggleGroup` for mutually-exclusive toggle buttons — `LinkedGroup` is for generic grouping.
- Avoid mixing very different widget types (e.g. a button and a text field) unless the UX warrants it.

---

Source: packages/react/src/components/Modal/README.md

# Modal

Large overlay for rich content, forms, and settings. Unlike `Dialog` (which targets confirmations and alerts), `Modal` provides a scrollable body and an integrated header bar with a close button plus optional primary and secondary actions.

Use `Dialog` for short confirmations. Use `Modal` for content-heavy flows.

---

Source: packages/react/src/components/MultiSelectDropdown/README.md

Checkbox-list variant of `Dropdown` for selecting multiple values from a single trigger.

```tsx
import { useState } from 'react';
import { MultiSelectDropdown } from '@gnome-ui/react';

const [languages, setLanguages] = useState<string[]>(['ts']);

<MultiSelectDropdown
  aria-label="Languages"
  options={[
    { value: 'js', label: 'JavaScript' },
    { value: 'ts', label: 'TypeScript' },
    { value: 'py', label: 'Python' },
  ]}
  value={languages}
  onChange={setLanguages}
/>
```

`Dropdown`/`ComboRow` are single-select only — use `MultiSelectDropdown` when more than one value can be chosen at once (e.g. filtering by several categories). Toggling an option keeps the list open so the user can pick several in a row; close it via Escape, Tab, or clicking outside.

The trigger shows the single option's label when exactly one is selected, or `"N selected"` once more than one is chosen.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `MultiSelectDropdownOption<V>[]` | — | The list of selectable options |
| `value` | `V[]` | — | The currently selected values |
| `onChange` | `(value: V[]) => void` | — | Called with the full updated selection whenever an option is toggled |
| `placeholder` | `string` | `'Select options'` | Shown when no option is selected |
| `aria-label` | `string` | — | Accessible label for the control |
| `disabled` | `boolean` | `false` | Disables the entire control |

### Guidelines

- Fully keyboard-navigable: Space/Enter opens the list; ↑/↓ move between options; Enter/Space toggles the active option without closing the list; Escape or Tab closes it.
- Selection state is conveyed via `aria-selected` on each `role="option"` — the checkbox square shown next to each option is decorative only, not a separate focusable control, so screen reader behavior matches the standard multi-selectable listbox pattern.

---

Source: packages/react/src/components/NavigationSplitView/README.md

Two-pane sidebar + content layout that collapses to a single navigable pane on narrow screens (≤ 400 px), mirroring `AdwNavigationSplitView`.

- **Wide (> 400 px):** sidebar and content are side-by-side. `showContent` is ignored.
- **Narrow (≤ 400 px):** only one pane is visible at a time. Use `showContent` to switch.

### Guidelines
- Use for apps with a list → detail navigation pattern (mail, files, contacts).
- The sidebar should contain a navigable list; the content pane shows the selected item.
- On narrow screens, add a **Back** button to the content header bar so users can return to the sidebar.
- The `showContent` prop is typically driven by whether a selection has been made.

---

Source: packages/react/src/components/NavigationView/README.md

Single-pane push/pop navigation stack.

Mirrors `AdwNavigationView` — the mobile-first counterpart to `NavigationSplitView`.
Compose `NavigationPage` children and use `useNavigation()` inside them to push/pop pages.

### Usage
- Each `NavigationPage` has a unique `tag` and a `title`.
- Call `navigate(tag)` to push a new page onto the stack.
- Call `pop()` to go back one page.
- `canGoBack` is `true` when there is a page to return to.

---

Source: packages/react/src/components/OtpInput/README.md

Segmented PIN/verification-code input — one cell per digit, with auto-advance on typing, backspace-to-previous-cell, and paste support.

```tsx
import { useState } from 'react';
import { OtpInput } from '@gnome-ui/react';

const [code, setCode] = useState('');

<OtpInput
  label="Verification code"
  value={code}
  onChange={setCode}
  onComplete={(fullCode) => verify(fullCode)}
/>
```

Common auth pattern, pairs naturally with `PasswordEntryRow`/`PasswordField` for a two-factor confirmation step following a password entry.

- Typing a digit advances focus to the next cell automatically.
- Backspace clears the current cell, or the previous cell (and moves focus back to it) if the current one is already empty.
- ←/→ move focus between cells without changing their value.
- Pasting a full code into any cell distributes its digits across that cell and the ones after it.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current value — a string of up to `length` digits |
| `onChange` | `(value: string) => void` | — | Called whenever the value changes |
| `onComplete` | `(value: string) => void` | — | Called once, when the value reaches `length` digits |
| `length` | `number` | `6` | Number of digit cells |
| `masked` | `boolean` | `false` | Obscure entered digits like a password field |
| `label` | `string` | — | Visible label, rendered as the group's `<legend>` |
| `helperText` | `string` | — | Helper text below the label, hidden when `error` is set |
| `error` | `string` | — | Error message shown in place of `helperText` |
| `disabled` | `boolean` | `false` | Disables every cell |
| `autoFocus` | `boolean` | `false` | Autofocus the first cell on mount |

### Guidelines

- Non-digit input is filtered automatically — only digits 0–9 are accepted, matching typical SMS/email verification codes.
- `onComplete` only fires on the transition into a complete value (e.g. right after the user types the last digit or pastes a full code) — it does not re-fire if the component re-renders with an already-complete `value`.
- Set `masked` for higher-sensitivity codes (e.g. a PIN used for account recovery) where the digits shouldn't be visible over someone's shoulder.

---

Source: packages/react/src/components/Overlay/README.md

Standalone backdrop/scrim layer with a fade transition and click-to-dismiss — the shared building block behind `Modal`, `Dialog`, and `BottomSheet`'s backdrops, extracted for building custom overlay UI.

```tsx
import { Overlay } from '@gnome-ui/react';

<Overlay open={open} onDismiss={() => setOpen(false)}>
  <MyCustomPanel />
</Overlay>
```

Deliberately minimal: no focus trap, no Escape handling, no dialog role. Use `Modal` or `Dialog` directly when you need a full modal — reach for `Overlay` when you're building something those don't cover (a lightbox, a custom dropdown panel, an image viewer).

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | Whether the overlay is visible (required) |
| `onDismiss` | `() => void` | — | Called when the backdrop itself — not its content — is clicked |
| `container` | `Element` | `document.body` | Portal mount target |
| `children` | `ReactNode` | — | Content positioned over the backdrop |

### Guidelines

- Clicks on `children` never trigger `onDismiss` — the check is `event.target === event.currentTarget`, so nested content doesn't need its own `stopPropagation()`.
- Locks body scroll while open and restores it on close.
- Respects `prefers-reduced-motion` — skips the fade and jumps straight to the open/closed state.
- Add your own `role`/`aria-*` attributes (via forwarded HTML attributes) and keyboard handling appropriate to what you're building — `Overlay` only manages the backdrop, not the semantics of its content.

---

Source: packages/react/src/components/OverlaySplitView/README.md

Sidebar + content layout where the sidebar becomes a slide-over **overlay** on narrow screens (≤ 400 px), mirroring `AdwOverlaySplitView`.

- **Wide (> 400 px):** sidebar and content are side-by-side. `showSidebar` is ignored.
- **Narrow (≤ 400 px):** content fills full width; sidebar slides in as an overlay when `showSidebar` is true.

### Guidelines
- Use when the sidebar is contextual and not always needed (e.g. document outline, filters).
- A hamburger / menu button in the HeaderBar typically toggles it on narrow screens.
- Backdrop click and Escape close the overlay. Provide an `onClose` handler.
- Prefer `NavigationSplitView` for primary list → detail navigation.

---

Source: packages/react/src/components/PasswordEntryRow/README.md

Password entry row with a built-in reveal/conceal toggle.

Mirrors `AdwPasswordEntryRow` — an `EntryRow` variant that defaults to
`type="password"` and provides a trailing icon button to show or hide the
entered text. Use inside a `BoxedList` for password settings fields.

### Guidelines
- Use `title` as the floating label (e.g. "Password", "Confirm Password").
- The reveal button is always present; do not replicate it via `trailing`.
- Supports controlled (`value`) and uncontrolled (`defaultValue`) modes.

---

Source: packages/react/src/components/PasswordField/README.md

Single-line password input with a peek toggle that reveals the value as plain text.

Mirrors `GtkPasswordEntry` (and its built-in peek icon), as opposed to `TextField` with `type="password"`, which has no reveal affordance.

```tsx
import { PasswordField } from '@gnome-ui/react';

<PasswordField label="Password" helperText="Must be at least 8 characters." />
<PasswordField label="Confirm password" error="Passwords do not match." />
<PasswordField label="PIN" revealable={false} />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Visible label rendered above the input |
| `helperText` | `string` | — | Helper text below the input, hidden when `error` is set |
| `error` | `string` | — | Error message shown in place of `helperText`; also applies the error border |
| `revealable` | `boolean` | `true` | Show the peek toggle button that reveals the password as plain text |
| `revealLabel` | `string` | `"Show password"` | Accessible label for the toggle while the password is hidden |
| `concealLabel` | `string` | `"Hide password"` | Accessible label for the toggle while the password is revealed |

### Guidelines

- Always provide a `label` — it is the primary accessible name for the input.
- The toggle button is `type="button"` so it never submits an enclosing `<form>`.
- Set `revealable={false}` for high-security fields (e.g. a PIN pad) where the value should never be displayable.
- Show errors only after the user has interacted (on blur or on submit), not while typing.

---

Source: packages/react/src/components/PathBar/README.md

Breadcrumb path bar for navigating a hierarchical location.

Mirrors the location bar in **GNOME Files (Nautilus)**. Segments are separated
by chevron dividers. All segments except the last are interactive — clicking
them calls `onNavigate`. The last segment represents the current location and
is rendered as a bold, non-interactive label.

```tsx
import { PathBar } from "@gnome-ui/react";

<PathBar
  segments={[
    { label: "Home",      path: "/home"                     },
    { label: "Documents", path: "/home/documents"           },
    { label: "Projects",  path: "/home/documents/projects"  },
  ]}
  onNavigate={(path) => navigate(path)}
/>
```

---

Source: packages/react/src/components/Popover/README.md

Floating panel anchored to a trigger element, following the Adwaita `GtkPopover` pattern.

Unlike **Tooltip**, a Popover can contain rich interactive content — menus, forms, sliders, toggles.

### Guidelines
- Use for secondary controls that are not important enough for permanent screen space.
- Keep content focused — one task or group of related settings.
- Prefer **Dialog** for actions that require confirmation or have significant consequences.
- Provide a clear way to close: Escape key, outside click, and a close/done button for longer panels.
- Supports both **uncontrolled** (toggle on trigger click) and **controlled** (`open` + `onClose`) modes.
- Content wider than the default 320px cap (a two-month calendar, a table) needs `panelClassName` with `max-width: none` — see `DateRangePicker`.

---

Source: packages/react/src/components/Portal/README.md

Reusable `createPortal` wrapper — SSR-safe (renders `children` inline when `document` is unavailable) with optional mount-target support.

```tsx
import { Portal } from '@gnome-ui/react';

<Portal>
  <div role="alert">Rendered at the end of document.body</div>
</Portal>

<Portal container={someElement}>
  <div>Rendered inside someElement instead</div>
</Portal>
```

Extracts the ad-hoc portal logic previously duplicated independently across `Dialog`, `Modal`, `Popover`, `Tooltip`, `BottomSheet`, and other floating-content components, each of which re-implemented the same `typeof document === 'undefined'` check inline.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Content to render into the target container |
| `container` | `Element \| DocumentFragment` | `document.body` | DOM node to portal into |

### Guidelines

- Use `Portal` for floating UI (dropdowns, tooltips, dialogs, toasts) that needs to escape an ancestor's `overflow: hidden` or `z-index` stacking context.
- During server-side rendering, `document` doesn't exist — `Portal` detects this and renders `children` inline instead of throwing, so components built on it stay SSR-safe without extra guards at the call site.

---

Source: packages/react/src/components/PreferencesDialog/README.md

Multi-page settings dialog using `PreferencesPage` tabs.

Renders a wide modal with a sidebar listing pages on the left. Each
`PreferencesPage` child becomes a navigation entry. When only one page
is provided the sidebar is hidden. Supports built-in search via the
`searchable` prop (default: `true`).

Mirrors `AdwPreferencesDialog`.

### Usage
```tsx
<PreferencesDialog open={open} onClose={() => setOpen(false)}>
  <PreferencesPage title="General" iconName="preferences-system-symbolic">
    <PreferencesGroup title="Appearance">
      <BoxedList>
        <SwitchRow title="Dark mode" />
      </BoxedList>
    </PreferencesGroup>
  </PreferencesPage>
</PreferencesDialog>
```

---

Source: packages/react/src/components/PreferencesGroup/README.md

Titled section that wraps a `BoxedList` with an optional description.

Use inside a `PreferencesPage` to group related settings under a named
heading. The group is purely a layout and labelling wrapper — pass a
`BoxedList` as `children`.

Mirrors `AdwPreferencesGroup`.

### Usage
- `title` labels the group (e.g. "Appearance", "Privacy").
- `description` adds a dimmed subtitle below the title.
- `headerSuffix` places a widget (e.g. a reset Button) at the trailing edge of the header.

---

Source: packages/react/src/components/PreferencesPage/README.md

Scrollable page composed of `PreferencesGroup` sections.

Use as a child of `PreferencesDialog`. Each page appears as a labelled
navigation entry in the dialog sidebar.

Mirrors `AdwPreferencesPage`.

### Usage
- `title` is used as the sidebar navigation label.
- `iconName` optionally places an icon next to the title in the sidebar.
- Put `PreferencesGroup` children inside to build the page layout.

---

Source: packages/react/src/components/ProgressBar/README.md

Determinate and indeterminate progress bar following the Adwaita style.

### Guidelines
- Use **determinate** (`value` 0–1) when you know the exact completion percentage.
- Use **indeterminate** (no `value`) when duration is unknown — prefer `Spinner` for short waits.
- Always provide an `aria-label` or `aria-labelledby` so screen readers can announce what is loading.
- Pair with a text label to show the percentage or description alongside the bar.
- Respects `prefers-reduced-motion` — the indeterminate animation is stopped and the bar shown at full width with reduced opacity.

---

Source: packages/react/src/components/RadioButton/README.md

Single-selection radio button following the GNOME HIG and Adwaita style.

### Guidelines
- Use radio buttons when only one option in a group can be active at a time.
- Always group with a shared `name` attribute so the browser enforces mutual exclusion and enables arrow-key navigation.
- Always pre-select a default option — never leave all options unselected.
- Use 2–5 options; for longer lists prefer a **Dropdown/Select**.
- Always pair each radio with a visible `<label>`.
- Label the group itself with a heading or `<fieldset>` + `<legend>`.

---

Source: packages/react/src/components/RangeSlider/README.md

Dual-thumb slider for selecting a min/max range, following the Adwaita `GtkScale` pattern used by `Slider`.

```tsx
import { useState } from 'react';
import { RangeSlider } from '@gnome-ui/react';

const [range, setRange] = useState<[number, number]>([20, 80]);

<RangeSlider value={range} onChange={setRange} minLabel="Minimum price" maxLabel="Maximum price" />
```

Distinct from `Slider`, which only supports a single value — use `RangeSlider` for range filters (price, date range, etc.) where both bounds are adjustable.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `[number, number]` | — | Current `[lower, upper]` values |
| `onChange` | `(value: [number, number]) => void` | — | Called when either thumb moves |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `100` | Maximum value |
| `step` | `number` | `1` | Granularity — arrow keys move by one step, Page Up/Down by 10 steps |
| `minDistance` | `number` | `0` | Minimum gap enforced between the two thumbs |
| `disabled` | `boolean` | `false` | Disables the control |
| `marks` | `Array<{ value: number; label?: string }>` | — | Tick marks along the track, with optional labels |
| `minLabel` | `string` | `'Minimum value'` | Accessible label for the lower-bound thumb |
| `maxLabel` | `string` | `'Maximum value'` | Accessible label for the upper-bound thumb |

### Guidelines

- Always pass descriptive `minLabel`/`maxLabel` (e.g. `"Minimum price"`/`"Maximum price"`) when more than one range slider appears on the same page — the defaults are generic and won't disambiguate them for screen reader users.
- Clicking the track jumps the **nearest** thumb to that position; dragging a thumb directly always moves that specific thumb, even if the pointer crosses over the other one.
- Use `minDistance` to keep the two thumbs from meeting — e.g. a date range that must span at least one day.

---

Source: packages/react/src/components/RatingStars/README.md

Star rating display and input.

```tsx
import { RatingStars } from '@gnome-ui/react';

// Read-only — omit onChange
<RatingStars value={4.2} max={5} aria-label="Average rating: 4.2 out of 5" />

// Interactive — pass onChange
<RatingStars value={rating} onChange={setRating} />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current rating, clamped to `[0, max]` (required) |
| `max` | `number` | `5` | Number of stars |
| `onChange` | `(value: number) => void` | — | Presence makes the component interactive; omit for a read-only display |
| `size` | `IconSize` | `"md"` | Star size |
| `disabled` | `boolean` | `false` | Renders as read-only even when `onChange` is provided |

### Guidelines

- Omit `onChange` for a read-only summary (e.g. an average rating from other users) — it renders as `role="img"` with a generated `"N out of M stars"` label.
- Pass `onChange` for a rating input — it renders as `role="radiogroup"` with roving-tabindex, arrow-key navigation (`←/→` or `↓/↑`, `Home`/`End`), and a hover preview that doesn't commit until clicked.
- Whole-star granularity only — there is no half-star display. Round an average rating with `Math.round()` before passing it as `value` in read-only mode.

---

Source: packages/react/src/components/ScrollToTop/README.md

Fixed-position button that scrolls the page to the top on click, following the GNOME Human Interface Guidelines.

### Guidelines

- Use `visible="auto"` (default) to show the button only after the user has scrolled far enough to benefit from it.
- Use `visible="always"` sparingly — only when continuous access to the top is part of the page's core interaction model.
- The button is semi-transparent at rest and fully opaque on hover or focus to avoid obscuring content beneath it.
- The default position is `"bottom-right"` with 24 px edge clearance matching `--gnome-space-4`.
- Pair with a `scrollTarget` when your scrollable container is an element other than `window` (e.g. a drawer or split-view pane).

---

Source: packages/react/src/components/SearchBar/README.md

Collapsible search bar following the Adwaita `AdwSearchBar` pattern.

### Guidelines
- Toggle visibility with the `open` prop — the bar slides in/out with a CSS transition.
- Place it directly below a `HeaderBar` (the canonical GNOME pattern).
- Pass `onClose` to handle Escape key and any "close search" trigger in your UI.
- Use `onClear` to reset the search query when the × button is clicked.
- The input auto-focuses when `open` becomes `true`.
- Optional `children` render a filter-chip row below the input.

---

Source: packages/react/src/components/SecurityMetric/README.md

# SecurityMetric

Compact KPI card for cybersecurity reports and vulnerability dashboards.

```tsx
import { SecurityMetric } from "@gnome-ui/react";

<SecurityMetric
  label="Critical findings"
  value={7}
  severity="critical"
  description="Require immediate triage"
  delta="+2 since last scan"
  trend="up"
/>
```

Use it for report-level summaries such as open CVEs, critical findings, average
CVSS, vulnerable assets, SLA breaches, or scanner-specific counts.

`severity` accepts the same values as `SeverityBadge`, including `minimal` for
external scanner compatibility.

Trend colors assume vulnerability-report semantics: `up` is unfavorable, `down`
is favorable, and `neutral` is informational.

---

Source: packages/react/src/components/SegmentedBar/README.md

Horizontal bar split into proportional segments, one per category.

Hover any segment to highlight it and reveal a tooltip with its label and percentage.
Values are automatically normalized if they don't sum to exactly 100.

Typical use case: repository language distribution (similar to GitHub's language bar).

```tsx
<SegmentedBar
  values={[
    { label: "TypeScript", value: 60, color: "#3178c6" },
    { label: "JavaScript", value: 30, color: "#f7df1e" },
    { label: "CSS",        value: 10, color: "#563d7c" },
  ]}
/>
```

---

Source: packages/react/src/components/Separator/README.md

Thin dividing line that separates groups of content.

### Guidelines
- Use to visually group related items without adding heavy structure.
- Prefer `horizontal` (default) between stacked sections.
- Use `vertical` inside flex rows — e.g. between toolbar actions or header bar buttons.
- Don't overuse separators; whitespace and headings are often enough.

---

Source: packages/react/src/components/SeverityBadge/README.md

Pill-shaped label for vulnerability severities in security reports, CVE tables,
dashboards, and scanner results.

```tsx
import { SeverityBadge } from "@gnome-ui/react";

<SeverityBadge severity="critical" />
<SeverityBadge severity="minimal" />
```

Supported severities are ordered as:

`none < minimal < low < medium < high < critical`

`minimal` is included for external scanner compatibility, such as Google
Artifact Registry / Grafeas. CVSS qualitative ratings should continue to use
the official `none`, `low`, `medium`, `high`, and `critical` levels.

---

Source: packages/react/src/components/ShortcutLabel/README.md

Read-only display of a keyboard shortcut with per-key key-cap styling.

Each token in the `shortcut` string (split by `+`) is rendered as a
separate `<kbd>` element. Modifier keys are normalised to their Unicode
symbols by default (`Ctrl` → `⌃`, `Shift` → `⇧`, etc.).

Mirrors `GtkShortcutLabel`.

### Usage
- Pass the shortcut as a `+`-separated string, e.g. `"Ctrl+S"`.
- Set `symbols={false}` to keep raw token names instead of symbols.
- Use as the `suffix` of an `ActionRow` in a `BoxedList`.

---

Source: packages/react/src/components/ShortcutsDialog/README.md

Modal dialog listing keyboard shortcuts grouped in sections, with integrated search.

Mirrors `AdwShortcutsDialog` (libadwaita 1.8 / GNOME 49) — the modern replacement for `GtkShortcutsWindow`.

- Search filters across all sections in real time (by description or key name).
- Renders into a portal; traps focus; Escape closes.
- Pass `sections` as a plain data array — no JSX needed for the shortcut entries.

---

Source: packages/react/src/components/Sidebar/README.md

Lateral navigation panel following the Adwaita `.navigation-sidebar` pattern.

Updated for **libadwaita 1.9 / GNOME 50**:

- **`SidebarSection`** — groups items under a named heading with a divider between sections.
- **`suffix`** — general trailing widget per item (button, badge, icon…); supersedes `badge`.
- **`tooltip`** — short label shown on hover, useful for truncated or icon-only rows.
- **`menuItems`** — per-item context menu on right-click or the `Menu` key.
- **`searchable`** — built-in search bar with automatic item filtering.
- **`mode`** — `"sidebar"` (default) or `"page"` (full-width boxed-list layout for narrow viewports).

All previous `Sidebar` / `SidebarItem` usage is fully backward compatible.

---

Source: packages/react/src/components/Skeleton/README.md

Content-shaped loading placeholder for skeleton screens.

GNOME HIG recommends `Spinner` and `ProgressBar` for loading states. `Skeleton`
is provided as a pragmatic web-style extension for dashboards and data-heavy
views where placeholders reduce layout shift.

---

Source: packages/react/src/components/Slider/README.md

Draggable range control following the Adwaita `GtkScale` pattern.

### Guidelines
- Use when the range is large or the exact value matters less than relative position (volume, zoom, brightness).
- Prefer **SpinButton** when the user needs to enter a precise value.
- Always set meaningful `min`, `max`, and `step`.
- Provide an `aria-label` or associate with a visible label via `aria-labelledby`.
- Keyboard: ← / → move by one step; Page Up/Down by 10 steps; Home/End jump to bounds.

---

Source: packages/react/src/components/SpinButton/README.md

Numeric input with − and + buttons following the Adwaita `GtkSpinButton` style.

### Guidelines
- Use for small bounded integer or decimal values (font size, quantity, opacity…).
- Always set meaningful `min`, `max`, and `step`.
- Prefer a **Slider** when the range is large or the exact value matters less than relative position.
- Keyboard: ↑/↓ step once, Page Up/Down step ×10, Home/End jump to min/max.
- The `−` button disables automatically at `min`; `+` at `max`.

---

Source: packages/react/src/components/Spinner/README.md

Indeterminate loading indicator following the Adwaita spinner style.

### Guidelines
- Use to communicate that something is loading with an unknown duration.
- For a known duration, prefer the **Progress Bar** component instead.
- Keep spinners small and close to the content they represent.
- Always provide an accessible `label` (default: `"Loading…"`). Set `label=""` only when a visible sibling label describes the action.
- Respects `prefers-reduced-motion` — slows the animation instead of stopping it.

---

Source: packages/react/src/components/SpinRow/README.md

Settings row with an integrated spin button for numeric values.

Mirrors `AdwSpinRow` — a standard row layout with − and + buttons at the trailing
edge. Use inside a `BoxedList` for settings with numeric ranges such as volume,
timeout durations, item counts, or font sizes.

### Guidelines
- Set `min`, `max`, and `step` to constrain the allowed range.
- Use `subtitle` to clarify the unit (e.g. "seconds", "pixels").
- Supports controlled (`value`) and uncontrolled (`defaultValue`) modes.
- Keyboard: ↑/↓ step by one, Page Up/Down step by 10×, Home/End jump to min/max.

---

Source: packages/react/src/components/SplitButton/README.md

Primary action button with an attached dropdown arrow.

Clicking the **label** half fires `onClick`. Clicking the **arrow** half opens a floating panel
with `dropdownContent` (menus, options, etc.).

Mirrors `AdwSplitButton` — supports `default`, `suggested`, and `destructive` variants.

### Guidelines
- Put the most common action in the primary half with a clear imperative label.
- Use `dropdownContent` for secondary variants of the same action (e.g. "Save as Template").
- Prefer `suggested` when this is the primary CTA in a dialog or toolbar.
- Never use `destructive` unless the primary action is irreversible.

---

Source: packages/react/src/components/StatusBadge/README.md

Pill-shaped text label for entity status. Use for human-readable state labels
like `published`, `beta`, or `new` — not for numeric counts (use `Badge` for those).

```tsx
import { StatusBadge } from "@gnome-ui/react";

<StatusBadge variant="success">published</StatusBadge>
<StatusBadge variant="warning">beta</StatusBadge>
<StatusBadge variant="new">new</StatusBadge>
```

---

Source: packages/react/src/components/StatusPage/README.md

Empty-state and status page following the Adwaita `AdwStatusPage` pattern.

Use to fill an empty view with context and a path forward.

### Guidelines
- Always explain **why** the view is empty and **what the user can do** about it.
- Keep the title to one short noun phrase — "No Results", "All Done", "Connection Lost".
- The description should be one or two sentences at most.
- Provide one primary action when there is a clear next step.
- Choose an icon that reinforces the message — do not use generic placeholders.
- Do not use for loading states — use `Spinner` or `ProgressBar` instead.

---

Source: packages/react/src/components/StepIndicator/README.md

Numbered "Step X of Y" progress indicator for onboarding/wizard flows.

Complements `CarouselIndicatorDots`/`CarouselIndicatorLines` with a labelled, linear alternative — steps are numbered circles connected by a progress line, with the completed portion tinted in the accent color.

```tsx
import { StepIndicator } from '@gnome-ui/react';

<StepIndicator steps={4} currentStep={1} />
<StepIndicator steps={['Account', 'Profile', 'Confirm']} currentStep={1} />
```

Pass a plain `number` for an unlabelled sequence — a "Step X of Y" caption is shown above the circles. Pass an array of strings to label each step instead; the caption is omitted since the labels already convey progress.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `steps` | `number \| string[]` | — | Total step count, or an array of per-step labels |
| `currentStep` | `number` | — | Zero-based index of the current/active step |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
| `onStepClick` | `(index: number) => void` | — | Called when a **completed** step's circle is clicked, to jump back |
| `label` | `string` | `'Progress'` | Accessible label for the `nav` landmark |

### Guidelines

- Only completed steps become clickable when `onStepClick` is provided — the current step is already there, and upcoming steps haven't been validated yet, so neither is clickable. This matches typical wizard back-navigation: users can revisit a finished step, but can't skip ahead.
- Use `orientation="vertical"` for a sidebar-style step list (e.g. a multi-section settings wizard); keep the default horizontal layout for top-of-page progress in a dialog or full-page flow.
- `currentStep` is clamped to a valid index automatically, so passing the step count (rather than the last valid index) after the final step completes won't throw or render out of bounds.

---

Source: packages/react/src/components/Switch/README.md

On/off toggle following the Adwaita switch style.

### Guidelines
- Use switches for settings that take effect immediately — no Save button needed.
- Prefer switches over checkboxes in settings UIs (GNOME HIG preference).
- Always pair with a visible label (via `<label>`) or supply `aria-label`.
- Place the switch at the trailing end of the row, aligned to the right.

---

Source: packages/react/src/components/SwitchRow/README.md

Activatable row with an integrated switch.

Mirrors `AdwSwitchRow` — the entire row is a button that toggles the switch when clicked.
This differs from `ActionRow` with a `trailing` switch: here the row itself carries the
`role="switch"` and clicking anywhere (title, subtitle, or the visual switch) toggles state.

### Guidelines
- Use when a single boolean setting should occupy a full list row.
- Prefer `SwitchRow` over `ActionRow + Switch trailing` when there is no other trailing widget needed.
- Supports controlled (`checked`) and uncontrolled (`defaultChecked`) modes.
- Wrap in `BoxedList` for the canonical GNOME settings appearance.

---

Source: packages/react/src/components/Tabs/README.md

Tab-based navigation following the Adwaita `AdwTabBar` pattern.

Three components work together:
- **`TabBar`** — the horizontal bar that holds `TabItem` elements; manages roving-tabindex keyboard navigation.
- **`TabItem`** — individual tab button with optional icon, close button, and ARIA wiring.
- **`TabPanel`** — content panel linked to its tab via `id` / `panelId`.

### Guidelines
- Use tabs for parallel views of the same data, not sequential steps (use a wizard for those).
- Keep labels short — one or two words.
- The active tab has an accent underline and higher contrast.
- Keyboard: ← / → cycle through tabs, Home / End jump to first / last.
- When tabs are closeable, always keep at least one tab open.

---

Source: packages/react/src/components/TagInput/README.md

Type-to-add multi-value input rendering entries as removable `Chip`s in a `WrapBox`.

```tsx
import { useState } from 'react';
import { TagInput } from '@gnome-ui/react';

const [tags, setTags] = useState(['react', 'gnome']);

<TagInput label="Tags" value={tags} onChange={setTags} placeholder="Add a tag…" />
```

`WrapBox`/`Chip` alone only support static, pre-populated display — `TagInput` adds interactive entry:

- Type and press **Enter** or **,** to commit the current draft as a tag.
- Press **Backspace** with an empty draft to remove the last tag.
- **Paste** a comma or newline-separated list to add several tags at once.
- Click a chip's **×** button to remove that specific tag.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string[]` | — | Current list of tags |
| `onChange` | `(value: string[]) => void` | — | Called when a tag is added or removed |
| `label` | `string` | — | Visible label rendered above the input |
| `helperText` | `string` | — | Helper text below the input, hidden when `error` is set |
| `error` | `string` | — | Error message shown in place of `helperText`; also applies the error border |
| `maxTags` | `number` | — | Maximum number of tags allowed. Once reached, the text input is hidden |
| `preventDuplicates` | `boolean` | `true` | Reject a new tag that already exists (case-insensitive) |

### Guidelines

- Always provide a `label` — it is the primary accessible name for the input.
- Clicking anywhere in the tag box focuses the draft input, matching the behavior of native multi-value fields (e.g. an email "To" field).
- Set `preventDuplicates={false}` only when duplicate entries are meaningful for your data (e.g. free-text notes) — for most tag/category use cases, leave it enabled.

---

Source: packages/react/src/components/TerminalView/README.md

Scrollable terminal-style output area styled after GNOME Terminal.
Intended for displaying logs, command output, or read-only text content.

```tsx
import { TerminalView } from "@gnome-ui/react";

<TerminalView lines={["$ npm install", "added 42 packages"]} />
```

---

Source: packages/react/src/components/Text/README.md

Typography component mirroring all [Adwaita text style classes](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html).

### Variants

| Variant | Element | Use case |
|---------|---------|----------|
| `large-title` | `h1` | Display heading with lots of whitespace |
| `title-1` | `h1` | Primary page/view title |
| `title-2` | `h2` | Section title |
| `title-3` | `h3` | Sub-section title |
| `title-4` | `h4` | Minor heading |
| `heading` | `h3` | UI labels, boxed list headers |
| `body` | `p` | Default UI text, descriptions |
| `document` | `p` | Reading content (chat, articles) |
| `caption` | `span` | Sub-text, metadata |
| `caption-heading` | `span` | Small group labels (uppercase) |
| `monospace` | `code` | Code, logs, shell commands |
| `numeric` | `span` | Aligned numbers, counters |

Use the `as` prop to override the rendered HTML element without changing the visual style.

---

Source: packages/react/src/components/TextField/README.md

Single-line text input with label, helper text, and error state.

Follows the Adwaita `GtkEntry` / `.entry` style class.

### Guidelines
- Always provide a `label` — it is the primary accessible name for the input.
- Use `helperText` for formatting hints or constraints (e.g. "Must be at least 8 characters").
- Replace `helperText` with `error` to communicate validation failure — never show both.
- Show errors only after the user has interacted (on blur or on submit), not while typing.
- Keep labels short and in sentence case ("Full name", not "Full Name").

---

Source: packages/react/src/components/TextTruncate/README.md

Single/multi-line text truncation with an automatic tooltip revealing the full content on overflow — mirrors `GtkLabel`'s `ellipsize` property.

```tsx
import { TextTruncate } from '@gnome-ui/react';

<TextTruncate>A very long file name that might not fit in the sidebar.txt</TextTruncate>
<TextTruncate lines={3}>A longer description that should clamp after three lines…</TextTruncate>
```

The tooltip only appears when the text is actually clipped — measured via `ResizeObserver`, so it stays accurate as the container is resized. Text that fits renders as plain, unwrapped content.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `string` | — | The text to display (required) |
| `lines` | `number` | `1` | Number of lines before truncating. `1` uses a single-line ellipsis; values above `1` clamp to that many lines |
| `tooltipPlacement` | `TooltipPlacement` | `"top"` | Tooltip placement when the text is truncated |

### Guidelines

- `children` must be a plain string — the same text is used both for display and as the tooltip's label.
- For a fixed-width container (e.g. a sidebar item, a table cell), wrap `TextTruncate` in an element with a defined `width`/`max-width`; truncation only kicks in once the content actually overflows its container.

---

Source: packages/react/src/components/Timeline/README.md

Ordered sequence of events connected by a visual timeline.

Supports two orientations — **vertical** (activity feed, history log) and
**horizontal** (stepper, progress indicator) — and three connector styles.

```tsx
import { Timeline } from "@gnome-ui/react";

<Timeline
  items={[
    {
      leading: <Text variant="caption" color="dim">10:32</Text>,
      icon: <Icon icon={Check} />,
      content: <Text variant="body">Document approved</Text>,
    },
  ]}
/>
```

---

Source: packages/react/src/components/TimePicker/README.md

Hour/minute selection built from paired [`SpinButton`](../SpinButton)s inside a
[`Popover`](../Popover), behind an entry-styled trigger — mirrors the
`GtkSpinButton` + `GtkPopover` composition GNOME apps use for time entry, with
12- and 24-hour support.

Each column cycles: stepping a minute past `59` rolls back to `00`, and hours
wrap `23 → 00` (or `12 → 01` with the AM/PM column). Columns are independently
keyboard-operable — <kbd>↑</kbd>/<kbd>↓</kbd> step, <kbd>PageUp</kbd>/<kbd>PageDown</kbd>
step by ten. Values update live as the spinners move.

## Usage

```tsx
import { TimePicker, type TimeValue } from '@gnome-ui/react/components/TimePicker';

function Example() {
  const [time, setTime] = useState<TimeValue | null>(null);
  return <TimePicker label="Start time" value={time} onChange={setTime} />;
}
```

12-hour presentation with a five-minute step:

```tsx
<TimePicker hourCycle={12} minuteStep={5} defaultValue={{ hours: 14, minutes: 30 }} />
```

---

Source: packages/react/src/components/Toast/README.md

Non-blocking temporary notification following the Adwaita `AdwToast` pattern.

Two components:
- **`Toast`** — the notification card. Manages its own auto-dismiss timer.
- **`Toaster`** — fixed-position portal container at bottom (or top) center that stacks toasts.

### Guidelines
- Keep messages short — one sentence.
- Use an action button for the single most relevant response (e.g. "Undo").
- Auto-dismiss after 3 s by default; set `duration={0}` for persistent toasts.
- The timer pauses while the user hovers or focuses the toast.
- Do not use for errors that require user action — use **Dialog** or **Banner** instead.

---

Source: packages/react/src/components/ToggleGroup/README.md

Mutually-exclusive group of toggle buttons for in-place option selection.

Mirrors `AdwToggleGroup` (libadwaita 1.7 / GNOME 48).

Use for formatting controls, alignment selectors, and toolbar view modes —
wherever a `ViewSwitcher` would be too heavy or doesn't belong in a HeaderBar.

- Items can be **icon-only**, **label-only**, or **icon + label**.
- For icon-only items, always provide an `aria-label` for screen readers.
- Keyboard: ← / → cycle through items, Home / End jump to first / last.

---

Source: packages/react/src/components/Toolbar/README.md

Horizontal action bar following the libadwaita `.toolbar` pattern.

Provides **6 px padding and gap** — the standard spacing for rows of flat buttons in
header bars, action bars, and tool rows. Use `<Spacer />` to push trailing items to the end.

### Guidelines
- Use `<Button variant="flat">` for buttons that blend into the bar background.
- Use `<Button variant="raised">` inside a Toolbar when a button needs explicit elevation.
- Place `<Spacer />` between leading and trailing button groups.
- Nest inside a surface (card, header bar, bottom bar) — Toolbar itself has no background.

---

Source: packages/react/src/components/ToolbarView/README.md

Layout container that attaches bars at the top and/or bottom while
scrolling only the middle content.

The top/bottom bars remain fixed; the inner content area gets
`overflow-y: auto` so it scrolls independently.

Mirrors `AdwToolbarView`.

### Usage
- Pass a `HeaderBar` or `Toolbar` to `topBar`.
- Pass a `Toolbar` or `ViewSwitcherBar` to `bottomBar`.
- Put scrollable page content in `children`.

---

Source: packages/react/src/components/Tooltip/README.md

Informational floating label following the GNOME HIG tooltip pattern.

Wraps a single trigger element and shows a label on hover or keyboard focus.

### Guidelines
- Use to clarify icon-only controls that have no visible label.
- Keep the text short — a noun phrase or brief description (< 10 words).
- Do not repeat information already visible on screen.
- Never put interactive content (links, buttons) inside a tooltip.
- Tooltips are not shown on touch — do not rely on them for critical information.
- The default delay is 500 ms to avoid flickering during normal mouse movement.

---

Source: packages/react/src/components/ViewSwitcher/README.md

Segmented control for switching between major views, mirroring the Adwaita `AdwViewSwitcher`.

Two components:
- **`ViewSwitcher`** — the pill-shaped container with `role="radiogroup"` and roving-tabindex keyboard navigation.
- **`ViewSwitcherItem`** — individual option with `role="radio"` and optional icon.

### Guidelines
- Use for 2–4 top-level views that are parallel (not sequential).
- Prefer placing it as the `title` of a `HeaderBar` — the canonical GNOME pattern.
- For more than 4 options, use **Tabs** or a **Sidebar** instead.
- Do not use for settings that have side-effects; use **Switch** for that.
- Keyboard: ← / → (or ↑ / ↓) cycle through items and activate them immediately.

---

Source: packages/react/src/components/ViewSwitcherBar/README.md

Bottom navigation bar for `ViewSwitcher` items on narrow screens (≤ 550 px), mirroring `AdwViewSwitcherBar`.

Use in tandem with a header-bar `ViewSwitcher`:
- **Wide (> 550 px):** show `ViewSwitcher` in the `HeaderBar`, hide the bar (`reveal={false}`).
- **Narrow (≤ 550 px):** hide the header switcher, set `reveal={true}`.

Pair with `useBreakpoint().isMedium` to automate the switch.

---

Source: packages/react/src/components/ViewSwitcherSidebar/README.md

Sidebar-style view switcher for apps with many top-level views or when the
sidebar layout fits better than a header-bar `ViewSwitcher`.

Mirrors `AdwViewSwitcherSidebar` (libadwaita 1.9 / GNOME 50) — the modern
replacement for `GtkStackSidebar`.

### When to use
- More than 4 top-level views (where `ViewSwitcher` in a HeaderBar becomes cramped).
- Apps whose primary navigation is already sidebar-shaped (mail, files, contacts).
- When views need additional metadata like unread counts (`count`) or custom widgets (`suffix`).

### vs `Sidebar`
| | `Sidebar` | `ViewSwitcherSidebar` |
|---|---|---|
| Semantics | `nav` + `aria-current` | `radiogroup` + `aria-checked` |
| Keyboard | Tab between items | ↑ / ↓ within group |
| Use for | App-level navigation | Switching between views/pages |

---

Source: packages/react/src/components/VisuallyHidden/README.md

Reusable "sr-only" utility — visually hides content while keeping it in the accessibility tree, so screen readers still announce it.

```tsx
import { VisuallyHidden } from '@gnome-ui/react';

<VisuallyHidden role="status" aria-live="polite">Copied to clipboard</VisuallyHidden>
<VisuallyHidden as="div" focusable>
  <a href="#main">Skip to content</a>
</VisuallyHidden>
```

Extracts the recipe previously duplicated inline inside `CopyButton`'s live-region announcement. Prefer this over `aria-hidden`/`display: none` when content should remain readable by assistive technology but not take up visual space — extra context for an icon-only control, a live-region status message, or a skip-link.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Content to hide visually while keeping it in the accessibility tree |
| `as` | `ElementType` | `'span'` | Override the rendered HTML element |
| `focusable` | `boolean` | `false` | Restore normal layout when the element (or a focusable descendant) receives keyboard focus — the standard "sr-only-focusable" pattern used by skip-links |

### Guidelines

- Use `role="status"`/`aria-live="polite"` alongside plain hidden text for one-off announcements (e.g. "Copied!"); reserve `focusable` for content meant to become visible on keyboard focus, like a skip-link.
- `focusable` doesn't add any visual styling for the revealed state (background, padding, positioning) — apply your own via `className` so the revealed content is legible against the page.

---

Source: packages/react/src/components/VulnerabilityFinding/README.md

# VulnerabilityFinding

Report-friendly vulnerability finding summary for security dashboards, CVE
reports, scan result reviews, and remediation workflows.

```tsx
import { VulnerabilityFinding } from "@gnome-ui/react";

<VulnerabilityFinding
  heading="XZ Utils backdoor"
  severity="critical"
  cveId="CVE-2024-3094"
  cvssScore={10}
  affected="xz 5.6.0"
  fixedVersion="5.6.1"
  description="Malicious build chain behavior detected in affected package versions."
/>
```

The component composes `SeverityBadge`, `CveIdentifier`, `CvssScore`, and
`StatusBadge`, so reports can use consistent severity, CVE, score, and workflow
labels.

`severity` accepts `none`, `minimal`, `low`, `medium`, `high`, and `critical`.
Use `minimal` for external scanner severities, such as Google Artifact Registry
/ Grafeas, rather than CVSS-derived qualitative ratings.

`status` supports `open`, `triaged`, `in-progress`, `fixed`, `accepted-risk`,
and `false-positive`.

---

Source: packages/react/src/components/VulnerabilitySummary/README.md

# VulnerabilitySummary

Executive severity-count summary for vulnerability reports, scan results, and
security dashboards.

```tsx
import { VulnerabilitySummary } from "@gnome-ui/react";

<VulnerabilitySummary
  counts={{
    critical: 3,
    high: 12,
    medium: 40,
    low: 8,
  }}
  description="Container image scan"
/>
```

The component accepts `none`, `minimal`, `low`, `medium`, `high`, and
`critical` counts. `minimal` is included for external scanner compatibility,
such as Google Artifact Registry / Grafeas.

Use `showZeroCounts` when a report needs a fixed severity layout even when some
severities have no findings. Negative counts are clamped to zero.

---

Source: packages/react/src/components/WidgetManager/README.md

Card that manages a controlled collection of "widgets" picked from a
`catalog`, each rendering its own content via `render()`. The header's edit
button toggles a dashed "add widget" trigger that opens a catalog picker —
`Modal`, `BottomSheet`, or `Drawer`, chosen with `pickerSurface`. Adding and
removing is staged inside the picker and only applied through `onChange`
when the user confirms; canceling discards the staging. Widgets can only be
removed through the picker, not inline in the card.

---

Source: packages/react/src/components/WindowTitle/README.md

Two-line title + subtitle widget for use inside a `HeaderBar`.

Pass as the `title` prop of `HeaderBar` to display a centred two-line header
with an app name and current document/view name.

Mirrors `AdwWindowTitle`.

### Usage
- `title` is the primary bold line (e.g. app name or current view).
- `subtitle` is the secondary dimmed line below (e.g. file path or context).
- Omit `subtitle` for a single-line header.

---

Source: packages/react/src/components/WrapBox/README.md

Flexible wrapping layout container.

Children flow horizontally and wrap to new lines when they don't fit,
like words in a paragraph — without locking them into a grid.

Mirrors `AdwWrapBox` (libadwaita 1.7 / GNOME 48).

Pair with `Chip` for tag lists and filter rows, or use standalone for
any collection of variable-width items.

---

Source: packages/layout/src/components/ActivityFeed/README.md

Chronological list of recent events with relative timestamps, optional icons,
skeleton loading state, and a "Show more" affordance.

```tsx
import { ActivityFeed } from "@gnome-ui/layout";

<ActivityFeed
  items={[
    { id: "1", label: "File uploaded", timestamp: new Date() },
  ]}
  maxItems={5}
/>
```

---

Source: packages/layout/src/components/AdaptiveLayout/README.md

Full-page adaptive shell that switches navigation automatically based on viewport width.
Use the **viewport toolbar** to preview each breakpoint:

- **Mobile** (< 480 px): `ViewSwitcherBar` pinned at the bottom.
- **Tablet** (480–1023 px): `ViewSwitcherSidebar` collapsed to icon-only.
- **Desktop** (≥ 1024 px): `ViewSwitcherSidebar` expanded with labels.

Pass `sidebarHeader` for the user card (expanded) and `sidebarHeaderCollapsed`
for the avatar-only version (collapsed). Grouped items (`group` field) become
sidebar sections on tablet/desktop and a single slot + `BottomSheet` on mobile.
When mobile bar slots exceed 4, the first 3 are shown and a **More** button handles
the rest.

Use `bgColor`, `bgShade` (1–5), and `bgOpacity` (0–1) to tint the shell background.

---

Source: packages/layout/src/components/AppHeader/README.md

GNOME application header with named shell slots.

Mirrors `AdwHeaderBar` — renders a sticky top bar with `leading`, `title`/`subtitle`, `navigation`, `search`, and `actions` slots. Place at the top of `Layout` or directly in a page shell.

```tsx
import { AppHeader } from '@gnome-ui/layout';
import { Button, SearchBar } from '@gnome-ui/react';

<AppHeader
  title="Files"
  subtitle="Home"
  leading={<Button variant="flat" aria-label="Toggle sidebar">☰</Button>}
  actions={<Button variant="flat">New Folder</Button>}
/>
```

### With navigation and search

```tsx
<AppHeader
  title="Documents"
  navigation={
    <ViewSwitcher aria-label="Document view">
      <ViewSwitcherItem label="Recent" active />
      <ViewSwitcherItem label="Starred" />
    </ViewSwitcher>
  }
  search={<SearchBar inline open placeholder="Search documents" aria-label="Search documents" />}
/>
```

### Props

| Prop | Type | Description |
|------|------|-------------|
| `title` | `string` | Primary window/page title |
| `subtitle` | `string` | Secondary label shown below title |
| `leading` | `ReactNode` | Left slot (back button, sidebar trigger) |
| `navigation` | `ReactNode` | Center slot (view switcher, tabs) |
| `search` | `ReactNode` | Inline search bar |
| `actions` | `ReactNode` | Right slot (action buttons, menu) |

### Guidelines

- Use `SidebarTrigger` in the `leading` slot to wire sidebar collapse/open.
- Place `ViewSwitcher` in `navigation` for multi-view apps.
- Avoid putting more than 2–3 actions in the `actions` slot; use a menu for overflow.

---

Source: packages/layout/src/components/ApplicationCard/README.md

App detail header with avatar, name, badge, description, stat row, and actions.
Designed for the MyApps `AppDetail` view — use `EntityCard` for list rows.

```tsx
import { ApplicationCard } from "@gnome-ui/layout";

<ApplicationCard
  avatar={<IconBadge color="blue" size="xl">⛅</IconBadge>}
  name="GNOME Weather"
  badge={<StatusBadge variant="success">published</StatusBadge>}
  description="The official weather app for the GNOME desktop."
  stats={[
    { label: "Version", value: "v4.8.1" },
    { label: "Builds",  value: "24" },
  ]}
  actions={<Button variant="suggested">New Release</Button>}
/>
```

---

Source: packages/layout/src/components/Banner/README.md

Persistent in-app message strip shown at the top of a view, following GNOME HIG banner guidelines.

Use banners to communicate **ongoing states** — offline mode, read-only access, pending updates.
They do not auto-dismiss. For individual events and short-lived messages, use `Toast` instead.

```tsx
import { Banner } from "@gnome-ui/layout";

<Banner type="warning" action={{ label: "Reconnect", onClick: retry }}>
  Working offline — changes will sync when you reconnect
</Banner>
```

---

Source: packages/layout/src/components/ChartCard/README.md

# ChartCard

Structured card shell for dashboard charts.

`ChartCard` provides a consistent header, optional metric/trend, action slot,
chart body, footer, and loading/empty/error states. It intentionally accepts
`children` for the visualization so it can wrap `@gnome-ui/charts` components,
SVGs, tables, or custom graphics without depending on a charting library.

```tsx
import { ChartCard } from '@gnome-ui/layout';
import { LineChart } from '@gnome-ui/charts';

<ChartCard
  title="Sessions"
  subtitle="Last 30 days"
  value={12840}
  trend={{ direction: 'up', value: 12, period: 'vs last month' }}
  actions={<button type="button">Export</button>}
>
  <LineChart data={data} series={series} xAxisKey="day" />
</ChartCard>;
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `ReactNode` | — | Card title |
| `subtitle` | `ReactNode` | — | Supporting text under the title |
| `value` | `number \| string` | — | Primary metric in the header |
| `unit` | `string` | — | Unit suffix next to `value` |
| `trend` | `StatCardTrend` | — | Directional percentage trend |
| `actions` | `ReactNode` | — | Header actions |
| `children` | `ReactNode` | — | Chart body |
| `footer` | `ReactNode` | — | Footer/status content |
| `loading` | `boolean` | `false` | Show loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading visual |
| `error` | `ReactNode` | — | Error content shown instead of chart |
| `empty` | `ReactNode` | — | Empty content shown instead of chart |
| `chartHeight` | `number \| string` | `220` | Minimum chart body height |

## Notes

- Numeric `value` and trend values use `GnomeProvider` number formatting.
- `error` takes precedence over `empty`.
- Keep chart-specific controls in `actions`; keep explanatory metadata in
  `footer`.

---

Source: packages/layout/src/components/CounterCard/README.md

Metric card with an animated numeric counter.

Wraps `Card` from `@gnome-ui/react` and counts up to `value` using an
ease-out cubic curve on mount and whenever `value` changes.
Respects `prefers-reduced-motion`.

```tsx
import { CounterCard } from "@gnome-ui/layout";

<CounterCard label="Documents" value={1248} suffix=" files" />
<CounterCard label="Revenue"   value={9420} prefix="$" accent duration={1500} />
```

---

Source: packages/layout/src/components/DashboardGrid/README.md

Responsive 12-column grid container for dashboard widgets and panels.

## Breakpoints

| Breakpoint | Min-width |
|---|---|
| xs | — (base) |
| sm | 576px |
| md | 768px |
| lg | 992px |
| xl | 1200px |
| xxl | 1600px |

## Usage

```tsx
import { DashboardGrid } from "@gnome-ui/layout";

// Static layout
<DashboardGrid columns={12} gap="md">
  <DashboardGrid.Item span={6} offset={3}>
    <Card />
  </DashboardGrid.Item>
</DashboardGrid>

// Responsive layout
<DashboardGrid columns={{ xs: 1, sm: 2, md: 3, lg: 4 }} gap={{ xs: "sm", md: "md" }}>
  <DashboardGrid.Item span={{ xs: 12, sm: 6, md: 4 }}>
    <StatCard />
  </DashboardGrid.Item>
</DashboardGrid>
```

---

Source: packages/layout/src/components/EmptyState/README.md

Centered empty-state illustration for views with no data.

No card background or border — intended to fill its parent container.

```tsx
import { EmptyState } from "@gnome-ui/layout";
import { Icon } from "@gnome-ui/react";
import { Folder } from "@gnome-ui/icons";

<EmptyState
  icon={<Icon icon={Folder} size="lg" />}
  title="No files yet"
  description="Files you add will appear here."
  action={<Button variant="suggested">Add File</Button>}
/>
```

---

Source: packages/layout/src/components/EntityCard/README.md

Avatar/icon + title + meta card. Covers both compact grid cards (Following screen)
and full-width list rows (MyApps screen) via additive optional props.

```tsx
import { EntityCard } from "@gnome-ui/layout";
import { IconBadge } from "@gnome-ui/layout";

<EntityCard
  avatar={<IconBadge color="blue" size="md">🌤</IconBadge>}
  title="GNOME Weather"
  subtitle="@alice_dev"
  meta={["v4.8.0", "⭐ 203"]}
/>
```

---

Source: packages/layout/src/components/ErrorState/README.md

Error state with four presets that set a default icon and title.
All defaults can be overridden via `icon` and `title` props.

Icon color uses `--gnome-warning-color` for `generic`/`network`
and `--gnome-error-color` for `permission`/`not-found`.

```tsx
import { ErrorState } from "@gnome-ui/layout";

<ErrorState
  type="network"
  description="Check your connection and try again."
  action={<Button variant="suggested" onClick={retry}>Try again</Button>}
/>
```

---

Source: packages/layout/src/components/FileManager/README.md

GNOME Files (Nautilus)–style file browser assembled from **`@gnome-ui/layout`**
and **`@gnome-ui/react`** components.

### Dual-headerbar pattern

The top bar is split into two sections that sit side-by-side:

| Section | Width | Contents |
|---------|-------|----------|
| Sidebar header | 240 px (56 px collapsed) | Search · Title · Toggle button |
| Content header | `flex: 1` | Back/Forward · **PathBar** · Refresh · More · Avatar |

This mirrors the `AdwOverlaySplitView` dual-`AdwHeaderBar` pattern used in GNOME Files.

**Closes:** [#16](https://github.com/ElJijuna/gnome-ui/issues/16)
**Depends on:** [#17 PathBar](https://github.com/ElJijuna/gnome-ui/issues/17)

---

Source: packages/layout/src/components/IconBadge/README.md

Rounded-square tinted icon container. Accepts the seven gnome-ui named colors or any hex value (`#rgb` / `#rrggbb`). In both cases the background is rendered at 15% opacity via `color-mix`.

```tsx
import { IconBadge } from "@gnome-ui/layout";

<IconBadge color="blue" size="lg">🚀</IconBadge>
<IconBadge color="#6c8ebf" size="md"><Icon icon={GoHome} /></IconBadge>
<IconBadge size="sm">📄</IconBadge>
```

---

Source: packages/layout/src/components/Layout/README.md

Full-page application shell from **`@gnome-ui/layout`** that composes four
named zones following the GNOME Human Interface Guidelines.

| Zone | Prop | Behaviour |
|------|------|-----------|
| Header | `header` / `topBar` | Pinned header — never scrolls |
| Sidebar | `sidebar` | Fixed-width lateral navigation, overlay, or rail |
| Content | `children` | Scrollable main area |
| Footer | `footer` / `bottomBar` | Pinned footer — never scrolls |

**Install:**
```bash
npm install @gnome-ui/layout
```

**Usage:**
```tsx
import { Layout } from "@gnome-ui/layout";
import "@gnome-ui/layout/styles";

<Layout header={<AppHeader />} sidebar={<AppSidebar />} footer={<AppStatusBar />}>
  <AppContent />
</Layout>
```

The shell supports pinned headers and footers, scroll-contained content,
sidebar overlays, rail collapse, right-side placement, GNOME breakpoints, and
the project's `--gnome-*` design tokens.

---

Source: packages/layout/src/components/LoadingStatus/README.md

Visually hidden live region announcing a skeleton loading state to screen readers.

`aria-busy` alone is not announced by most screen readers, and `Skeleton`
placeholders are intentionally `aria-hidden` (they're visual filler, not
content) — `LoadingStatus` is the part that actually communicates
"Loading…" to assistive technology. Used internally by `StatCard`,
`EntityCard`, `ProfileCard`, `ChartCard`, `ActivityFeed`, and other cards'
loading states; reach for it directly in your own skeleton layouts too.

```tsx
import { LoadingStatus } from "@gnome-ui/layout";
import { Card, Skeleton } from "@gnome-ui/react";

<Card aria-busy="true">
  <LoadingStatus />
  <Skeleton variant="rect" width={150} height={34} />
</Card>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `"Loading…"` | Announcement read by screen readers |

---

Source: packages/layout/src/components/MasonryGrid/README.md

Masonry layout that distributes variable-height items across columns using a
**shortest-column-first** algorithm — each new item is placed in the column
with the least accumulated height, minimising gaps.

Layout is computed in JavaScript via `ResizeObserver`, so it adapts automatically
when the container or any item changes size. Enable `fresh` to continuously
monitor individual item heights.

```tsx
import { MasonryGrid } from "@gnome-ui/layout";

<MasonryGrid columns={{ xs: 1, sm: 2, md: 3 }} gap="md">
  <Card />
  <Card />
  <Card />
</MasonryGrid>
```

---

Source: packages/layout/src/components/PageContent/README.md

Page content container with GNOME spacing and optional width clamping.

Centers content within the viewport, applies consistent horizontal padding, and optionally clamps the maximum content width. Use inside the main content area of `Layout`.

```tsx
import { PageContent } from '@gnome-ui/layout';
import { Text } from '@gnome-ui/react';

// Clamped to a readable width
<PageContent maxWidth="md">
  <Text variant="title-2">Settings</Text>
</PageContent>

// Full-width with spacious padding
<PageContent maxWidth="none" padding="spacious">
  <Text variant="title-2">Dashboard</Text>
</PageContent>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `maxWidth` | `"sm" \| "md" \| "lg" \| "xl" \| "none"` | `"lg"` | Maximum content width |
| `padding` | `"default" \| "spacious"` | `"default"` | Horizontal padding size |
| `as` | `ElementType` | `"div"` | Override the rendered HTML element |

### Guidelines

- Use `maxWidth="md"` for settings pages and forms — matches GNOME HIG readable line length.
- Use `maxWidth="none"` for dashboards and full-bleed data views.
- Nest inside `Layout`'s main area or directly inside a scrollable container.

---

Source: packages/layout/src/components/PanelCard/README.md

Card with a structured **header / body / footer** layout and built-in
collapse/expand behaviour.

The expanded state lives inside the component. Use a `ref` to drive it
imperatively from the outside:

```tsx
import { useRef } from "react";
import { PanelCard } from "@gnome-ui/layout";
import type { PanelCardHandle } from "@gnome-ui/layout";

const ref = useRef<PanelCardHandle>(null);

<button onClick={() => ref.current?.toggle()}>Toggle</button>

<PanelCard
  ref={ref}
  icon={<Icon icon={DocumentOpen} />}
  title="My Panel"
  headerActions={<Button variant="flat">Edit</Button>}
  onExpandedChange={(open) => console.log(open)}
  footer={<Text variant="caption" color="dim">Saved 2 min ago</Text>}
  footerActions={<Button variant="suggested">Save</Button>}
>
  Panel body content
</PanelCard>
```

---

Source: packages/layout/src/components/ProfileCard/README.md

Dashboard card for displaying a user profile — avatar, name, handle, optional status dot, optional stats row, and an optional decorative background chart.

```tsx
import { ProfileCard } from "@gnome-ui/layout";

<ProfileCard
  name="rcronald"
  username="@rcronald"
  status="online"
  stats={[
    { label: "posts", value: 127 },
    { label: "followers", value: "2.4k" },
  ]}
/>
```

Pass any `ReactNode` as `backgroundChart` — e.g. a `SparkAreaChart` from `@gnome-ui/charts`:

```tsx
<ProfileCard
  name="rcronald"
  username="@rcronald"
  backgroundChart={<SparkAreaChart data={activityData} height={80} />}
/>
```

---

Source: packages/layout/src/components/ProgressCard/README.md

Resource usage card with a labeled progress bar.

Composes `Card` and `ProgressBar` from `@gnome-ui/react`. The fill color shifts automatically at usage thresholds: accent (< 75%), warning (≥ 75%), error (≥ 90%).

```tsx
import { ProgressCard } from "@gnome-ui/layout";

<ProgressCard label="Storage" used={42.5} total={128} unit="GB" />
<ProgressCard label="Memory"  used={96}   total={128} unit="GB" icon={<MemoryIcon />} />
```

---

Source: packages/layout/src/components/QuickActions/README.md

Grid of shortcut action buttons for dashboards, file managers, and control panels.

```tsx
import { QuickActions } from "@gnome-ui/layout";

<QuickActions
  actions={[
    { id: "new-file", label: "New File", icon: <AddIcon />, onActivate: createFile },
    { id: "share", label: "Share", icon: <ShareIcon />, onActivate: share },
  ]}
/>
```

---

Source: packages/layout/src/components/ResizablePanel/README.md

Two or more panels separated by a draggable divider, based on the `GtkPaned`
pattern. Foundational for user-resizable master-detail layouts (code editors,
file explorers, analytics dashboards).

```tsx
import { ResizablePanel } from "@gnome-ui/layout";

<ResizablePanel direction="horizontal" defaultSizes={[30, 70]}>
  <FileTree />
  <Editor />
</ResizablePanel>
```

Implements the WAI-ARIA "window splitter" pattern: each divider is a
`role="separator"` with `aria-orientation` and `aria-valuenow`, focusable
and resizable with the arrow keys in addition to pointer drag.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Two or more panels, each rendered as one resizable region |
| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction |
| `defaultSizes` | `number[]` | equal split | Initial size of each panel as a percentage. Falls back to an equal split when its length doesn't match the number of panels |
| `minSize` | `number` | `10` | Minimum size any panel can be resized to, as a percentage |
| `onResize` | `(sizes: number[]) => void` | — | Called with the updated sizes while dragging |

### Guidelines

- Dragging a divider only ever resizes the two panels immediately adjacent to it — resizing one pair never affects panels further away.
- Sizes are uncontrolled — pass `defaultSizes` to set the initial split and read `onResize` if you need to persist the user's chosen layout.

---

Source: packages/layout/src/components/SectionHeader/README.md

Title row for dashboard sections with optional subtitle and trailing action slot.

```tsx
import { SectionHeader } from "@gnome-ui/layout";

<SectionHeader
  title="Recent Activity"
  subtitle="Last 24 hours"
  action={<Button variant="flat" size="sm">View all</Button>}
/>
```

---

Source: packages/layout/src/components/Settings/README.md

GNOME Settings–style preferences app assembled from **`@gnome-ui/layout`** and **`@gnome-ui/react`**.

Demonstrates the dual-headerbar + sidebar navigation pattern with sub-page drill-down.

| Component | Role |
|-----------|------|
| `Layout` | Full-page shell |
| `Sidebar` / `SidebarItem` | Category navigation |
| `PreferencesGroup` | Titled section wrapper |
| `BoxedList` | Rounded settings list |
| `SwitchRow` | Toggle setting row |
| `ActionRow` | Navigable / value row |

---

Source: packages/layout/src/components/SidebarShell/README.md

Full-height GNOME sidebar with fixed header/footer and scrollable navigation area.

Wraps `@gnome-ui/react`'s `Sidebar` with named slots for a sticky `header`, scrollable `children`, and a fixed `footer`. Supports collapsed rail mode and an optional search bar.

```tsx
import { SidebarShell } from '@gnome-ui/layout';
import { Button, SidebarItem, SidebarSection, Text } from '@gnome-ui/react';
import { GoHome, Settings, Star } from '@gnome-ui/icons';

<SidebarShell
  header={<Text variant="heading">Files</Text>}
  footer={<Button variant="flat" style={{ width: '100%' }}>Preferences</Button>}
  aria-label="Files navigation"
>
  <SidebarSection>
    <SidebarItem label="Home" icon={GoHome} active />
    <SidebarItem label="Starred" icon={Star} />
    <SidebarItem label="Settings" icon={Settings} />
  </SidebarSection>
</SidebarShell>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `header` | `ReactNode` | — | Sticky top area (app name, avatar…) |
| `footer` | `ReactNode` | — | Fixed bottom area (account, preferences…) |
| `collapsed` | `boolean` | `false` | Render as a narrow icon rail |
| `searchable` | `boolean` | `false` | Show an inline search bar to filter items |

### Guidelines

- Use with `SidebarTrigger` in `AppHeader` to wire open/collapse state.
- Wrap in `SidebarShellContext` if you need to share sidebar state across the layout.

---

Source: packages/layout/src/components/SidebarTrigger/README.md

Header button that opens overlay sidebars on narrow screens and toggles rail collapse on wider screens.

Renders the appropriate icon based on the current sidebar state (`open`, `collapsed`). Designed to be placed in the leading slot of `AppHeader`.

```tsx
import { SidebarTrigger } from '@gnome-ui/layout';

const [open, setOpen] = useState(false);
const [collapsed, setCollapsed] = useState(false);

<SidebarTrigger
  sidebarOpen={open}
  sidebarCollapsed={collapsed}
  onSidebarOpenChange={setOpen}
  onSidebarCollapsedChange={setCollapsed}
/>
```

### Guidelines

- Use inside `AppHeader`'s `leading` slot alongside a `SidebarShell`.
- On mobile breakpoints, `open/onSidebarOpenChange` controls an overlay drawer.
- On desktop breakpoints, `collapsed/onSidebarCollapsedChange` controls rail vs. full width.

---

Source: packages/layout/src/components/SplitLayout/README.md

List/master + detail shell following the Adwaita `AdwNavigationSplitView`
pattern, with a `HeaderBar` for each pane — the way real Adwaita apps
(Settings, Files, Contacts) actually look, rather than the bare pane-toggle
mechanics of `@gnome-ui/react`'s `NavigationSplitView` that this composes.

On narrow screens (≤ 400 px) the detail pane's header automatically grows a
Back button wired to `onBack`, so consumers don't have to hand-build that
chrome themselves.

```tsx
import { SplitLayout } from "@gnome-ui/layout";

const [selected, setSelected] = useState<string | null>(null);

<SplitLayout
  sidebarTitle="Mail"
  sidebar={<MailList selected={selected} onSelect={setSelected} />}
  detailTitle={selected ?? undefined}
  detail={selected ? <MailDetail id={selected} /> : <EmptyState title="No message selected" />}
  showDetail={selected !== null}
  onBack={() => setSelected(null)}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sidebar` | `ReactNode` | — | Sidebar / list pane body content |
| `sidebarTitle` | `ReactNode` | — | Title in the sidebar pane's header bar |
| `sidebarActions` | `ReactNode` | — | Trailing actions in the sidebar pane's header bar |
| `detail` | `ReactNode` | — | Detail / content pane body content |
| `detailTitle` | `ReactNode` | — | Title in the detail pane's header bar |
| `detailActions` | `ReactNode` | — | Trailing actions in the detail pane's header bar |
| `showDetail` | `boolean` | `false` | Shows the detail pane instead of the sidebar on narrow screens |
| `onBack` | `() => void` | — | Called by the automatic mobile Back button. The button only renders when this is provided |
| `minSidebarWidth` | `number` | `180` | Minimum sidebar width in px |
| `maxSidebarWidth` | `number` | `280` | Maximum sidebar width in px |
| `sidebarWidthFraction` | `number` | `0.25` | Fraction of total width given to the sidebar (0–1) |

### Guidelines

- A pane's header bar only renders when it has a title, actions, or (for the
  detail pane) a visible Back button — an empty sidebar list doesn't grow a
  blank header.
- `showDetail`/`onBack` only matter on narrow screens; on wide screens both
  panes are always visible side by side and neither prop has any effect.
- For the raw pane-toggle primitive without header chrome, use
  `NavigationSplitView` from `@gnome-ui/react` directly.

---

Source: packages/layout/src/components/StatCard/README.md

Metric card for dashboards with optional unit, trend indicator, icon, background chart, and loading state.

```tsx
import { StatCard } from "@gnome-ui/layout";

<StatCard
  label="Active Users"
  value={1284}
  unit="users"
  trend={{ direction: "up", value: 12, period: "vs last week" }}
/>
```

Pass a spark chart as a decorative background without coupling the card to a
specific chart type:

```tsx
<StatCard
  label="Requests"
  value="24.8k"
  backgroundChart={<SparkAreaChart data={requestTrend} height={96} />}
/>
```

---

Source: packages/layout/src/components/StatusBar/README.md

Compact footer/status bar for application shells.

Renders a thin bar at the bottom of the layout. Accepts arbitrary children for the leading side and a `trailing` slot for right-aligned content (version strings, connection status, etc.).

```tsx
import { StatusBar } from '@gnome-ui/layout';
import { Text } from '@gnome-ui/react';

<StatusBar
  trailing={
    <Text variant="caption" color="dim">
      GNOME Files 48.0
    </Text>
  }
>
  <Text variant="caption" color="dim">
    1,248 items
  </Text>
</StatusBar>
```

### Guidelines

- Place in the `footer` slot of `Layout`.
- Keep content concise — captions and short status strings only.
- Use `color="dim"` on `Text` to match the subtle status bar aesthetic.

---

Source: packages/layout/src/components/StatusIndicator/README.md

Status dot for communicating the health of a service, connection, or resource.

Colors follow Adwaita tokens (`--gnome-success-color`, `--gnome-warning-color`,
`--gnome-error-color`). The `loading` status pulses via CSS animation and
respects `prefers-reduced-motion`.

```tsx
import { StatusIndicator } from "@gnome-ui/layout";

<StatusIndicator status="online"  label="Database" />
<StatusIndicator status="warning" label="API Gateway" description="High latency" />
<StatusIndicator status="offline" label="Backup Service" />
```

---

Source: packages/layout/src/components/StickyToc/README.md

Sticky table-of-contents side rail with scroll-spy: the link for the section
currently nearest the top of the viewport is highlighted automatically as the
user scrolls. For long docs/settings pages.

Each `sections[].id` must match the `id` of a real heading element on the
page — `StickyToc` observes those elements directly via
`IntersectionObserver`, it does not render the headings itself.

```tsx
import { StickyToc } from "@gnome-ui/layout";

<StickyToc
  sections={[
    { id: "intro", label: "Introduction" },
    { id: "usage", label: "Usage" },
    { id: "props", label: "Props" },
  ]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sections` | `StickyTocSection[]` (`{ id, label }`) | — | Sections to link to, in document order |
| `label` | `string` | `"On this page"` | Heading rendered above the list, and the nav's accessible label |
| `onActiveChange` | `(id: string) => void` | — | Called whenever the active section changes, from either scrolling or clicking a link |

### Guidelines

- Once a section scrolls fully out of view with nothing else visible (e.g. mid-scroll between two sections), the last active link stays highlighted rather than flickering back to "none active".
- Clicking a link scrolls its target into view directly — it doesn't rely on the browser's native hash-jump, so it works even when the page uses a fixed header that would otherwise cover the heading.

---

Source: packages/layout/src/components/TeamCard/README.md

Group identity card: avatar group, team name, and member count.

Distinct from `UserCard`, which represents a single user's identity —
`TeamCard` is for teams, groups, or shared workspaces.

```tsx
import { TeamCard } from "@gnome-ui/layout";
import { Button } from "@gnome-ui/react";

<TeamCard
  name="Design"
  description="Product design and research"
  members={[{ name: "Ada Lovelace" }, { name: "Grace Hopper" }]}
  action={<Button size="sm">View team</Button>}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Team name |
| `description` | `string` | — | Optional secondary line describing the team's purpose |
| `members` | `AvatarGroupItem[]` | — | Members rendered in the `AvatarGroup` |
| `avatarSize` | `AvatarSize` | `"md"` | Avatar size within the group |
| `maxAvatars` | `number` | `5` | Max visible avatars before the overflow chip |
| `action` | `ReactNode` | — | Optional trailing action next to the member count (e.g. a "View team" button) |
| `interactive` | `boolean` | `true` | Delegates hover/active behavior to `Card`. Automatically forced to `false` whenever `action` is set, since `Card`'s interactive mode renders as a `<button>` and nesting a button inside it is invalid HTML |
| `loading` | `boolean` | `false` | Renders a loading placeholder |
| `loadingType` | `"skeleton" \| "spinner"` | `"skeleton"` | Loading placeholder style |

---

Source: packages/layout/src/components/Toast/README.md

In-app notifications following the GNOME Human Interface Guidelines.

Toasts are **transient** messages shown at the bottom-center of the window.
They auto-dismiss after a configurable delay and support a single action button.
Use them for individual events, not for persistent or ongoing states — for those, use `Banner`.

## Setup

Wrap your app (or the relevant subtree) with `ToastProvider` once, then call
`useToast().show()` from any descendant:

```tsx
// main.tsx
import { ToastProvider } from "@gnome-ui/layout";

<ToastProvider>
  <App />
</ToastProvider>

// Anywhere inside the tree
import { useToast } from "@gnome-ui/layout";

const { show, dismiss } = useToast();
show({ title: "File saved", action: { label: "Undo", onClick: undo } });
```

---

Source: packages/layout/src/components/UserCard/README.md

User identity panel for popovers, sidebar footers, and profile pages.

Renders an `Avatar`, a display name, an optional sub-line (e-mail, role…),
and a list of action buttons. A separator is automatically inserted before
any `"destructive"` action.

The component has **no card chrome** — place it inside a `Popover` or wrap
it in `<Card>` depending on context.

```tsx
import { UserCard } from "@gnome-ui/layout";

<UserCard
  name="Ada Lovelace"
  email="ada@gnome.org"
  actions={[
    { label: "View Profile",     onClick: () => {} },
    { label: "Account Settings", onClick: () => {} },
    { label: "Sign Out",         onClick: () => {}, variant: "destructive" },
  ]}
/>
```

---

Source: packages/charts/src/components/AreaChart/README.md

Area chart built on Recharts with GNOME design tokens, supporting stacked areas and gradient fills.

Each series renders as a filled area beneath a line. Enable `gradient` for a top-to-bottom opacity fade, and `stacked` to accumulate series vertically.

```tsx
import { AreaChart } from '@gnome-ui/charts';

<AreaChart
  data={[
    { week: 'W1', downloads: 320, installs: 210 },
    { week: 'W2', downloads: 480, installs: 310 },
  ]}
  series={[
    { dataKey: 'downloads', name: 'Downloads' },
    { dataKey: 'installs', name: 'Installs' },
  ]}
  xAxisKey="week"
  showLegend
  gradient
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Array of data points |
| `series` | `AreaChartSeries[]` | — | Series definitions (`dataKey`, `name?`, `color?`) |
| `xAxisKey` | `string` | `"name"` | Key used for the x-axis labels |
| `height` | `number` | `300` | Chart height in px |
| `showGrid` | `boolean` | `true` | Show horizontal grid lines |
| `showLegend` | `boolean` | `false` | Show series legend |
| `stacked` | `boolean` | `false` | Stack areas on top of each other |
| `gradient` | `boolean` | `false` | Apply top-to-bottom gradient fill |
| `aria-label` | `string` | auto | Accessible label for the chart |

### Guidelines

- Use when the area beneath the line carries meaning (volume, cumulative counts).
- `stacked + gradient` works well for dashboards showing part-to-whole relationships.
- For compact inline use, prefer `SparkAreaChart`.

---

Source: packages/charts/src/components/BarChart/README.md

Bar chart built on Recharts with GNOME design tokens for grouped comparisons across categories.

Renders vertical bars with optional grid lines and a legend for multi-series data.

```tsx
import { BarChart } from '@gnome-ui/charts';

<BarChart
  data={[
    { month: 'Jan', users: 420, sessions: 680 },
    { month: 'Feb', users: 380, sessions: 590 },
  ]}
  series={[
    { dataKey: 'users', name: 'Users' },
    { dataKey: 'sessions', name: 'Sessions' },
  ]}
  xAxisKey="month"
  showLegend
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Array of data points |
| `series` | `BarChartSeries[]` | — | Series definitions (`dataKey`, `name?`, `color?`) |
| `xAxisKey` | `string` | `"name"` | Key used for the x-axis labels |
| `height` | `number` | `300` | Chart height in px |
| `showGrid` | `boolean` | `true` | Show horizontal grid lines |
| `showLegend` | `boolean` | `false` | Show series legend |
| `aria-label` | `string` | auto | Accessible label for the chart |

### Guidelines

- Use for comparing discrete categories (months, items, groups).
- For compact inline use, prefer `SparkBarChart`.
- Pass `color` in each series to override the default GNOME palette.

---

Source: packages/charts/src/components/BoxPlot/README.md

Box-and-whisker plot built with plain HTML/CSS — no Recharts (it has no native box-plot primitive). Shows the distribution of one or more groups: median, interquartile range (Q1–Q3), whiskers extending to the most extreme non-outlier value, and outliers beyond 1.5×IQR.

Each item accepts either a raw `values` array (the component computes quartiles and outliers for you) or precomputed statistics — pick whichever fits how your data already arrives.

```tsx
import { BoxPlot } from '@gnome-ui/charts';

// Raw values — quartiles and outliers computed automatically (1.5×IQR rule)
<BoxPlot
  data={[
    { label: 'Team A', values: [12, 15, 14, 18, 22, 9, 31, 16] },
    { label: 'Team B', values: [8, 11, 10, 9, 14, 7, 12] },
  ]}
/>

// Precomputed statistics — e.g. aggregated server-side, or a non-IQR outlier rule
<BoxPlot
  data={[
    { label: 'Team A', min: 9, q1: 13, median: 15.5, q3: 19, max: 22, outliers: [31] },
    { label: 'Team B', min: 7, q1: 8.5, median: 10, q3: 11.5, max: 14 },
  ]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `BoxPlotDataItem[]` | — | `{ label, color? }` plus either `values: number[]` or `{ min, q1, median, q3, max, outliers? }` |
| `height` | `number` | `320` | Chart height in px |
| `showOutliers` | `boolean` | `true` | Render individual points beyond the whiskers |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for axis ticks and the tooltip title |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

### Quartile computation

When an item provides `values`, quartiles use linear interpolation (the common "R-7" method). Outliers are values outside `[Q1 − 1.5×IQR, Q3 + 1.5×IQR]`; the whiskers then extend only to the most extreme *non-outlier* value, not the raw min/max — the standard Tukey box plot convention.

### Guidelines

- Prefer the `values` form unless your data is already aggregated — it keeps the outlier rule consistent across every chart in the app.
- Each box shows a title tooltip with the full five-number summary on hover; individual outlier points are separately titled with their value.
- There is no spark/compact variant: a box-and-whisker glyph needs room for the whiskers, box, and outlier dots to read as a distribution at all — compressing it into a card-sized sparkline loses that entirely. For a compact distribution hint at that scale, `SparkAreaChart`/`SparkBarChart` over a sorted or binned series is a closer fit.

---

Source: packages/charts/src/components/BulletChart/README.md

Bullet graph (Stephen Few) built with plain SVG-free HTML — no Recharts. Shows a performance measure against a target and qualitative ranges in a single compact horizontal track, for KPI rows in tables and dashboards where `GaugeChart` takes too much vertical space.

```tsx
import { BulletChart } from '@gnome-ui/charts';

<BulletChart value={72} target={90} label="Revenue" />
```

### Qualitative ranges

Pass ascending `{ value, color? }` upper bounds to render background bands (e.g. poor/satisfactory/good). Colors default to a neutral grayscale ramp when omitted.

```tsx
<BulletChart
  value={72}
  target={90}
  label="CPU"
  ranges={[{ value: 50 }, { value: 80 }, { value: 100 }]}
/>
```

### Custom range and formatting

```tsx
<BulletChart
  value={4200}
  target={5000}
  min={0}
  max={6000}
  label="Revenue"
  valueFormatter={(v) => `$${v.toLocaleString()}`}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Performance measure — the current value |
| `target` | `number` | — | Comparative measure, rendered as a perpendicular tick |
| `min` | `number` | `0` | Minimum of the track range |
| `max` | `number` | `100` | Maximum of the track range |
| `ranges` | `{ value, color? }[]` | — | Ascending upper bounds for qualitative bands; falls back to a neutral grayscale ramp |
| `color` | `string` | accent color | Performance bar color |
| `height` | `number` | `32` | Track height in px |
| `label` | `string` | — | Caption rendered to the left of the track |
| `showValue` | `boolean` | `true` | Show the formatted value (and target, if set) to the right |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for the displayed value/target |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

### Guidelines

- Use `ranges` for status-style rows (capacity, SLA compliance) instead of a single flat track, so the bar communicates severity at a glance without needing a legend.
- Prefer `BulletChart` over `GaugeChart` when a target value matters and vertical space is tight — a table row, a list of KPIs stacked in a sidebar.
- Values are not required to be percentages — set `min`/`max` to match the metric's real range.

---

Source: packages/charts/src/components/CloudChart/README.md

Word/tag cloud that scales each term's font size proportionally to its numeric value.

Font size is linearly interpolated between `minFontSize` and `maxFontSize`. Items with equal values render at the midpoint. Colors cycle through the GNOME chart palette unless overridden per item.

```tsx
import { CloudChart } from '@gnome-ui/charts';

<CloudChart
  data={[
    { text: 'TypeScript', value: 95 },
    { text: 'React', value: 88 },
    { text: 'Node.js', value: 76 },
    { text: 'CSS', value: 70 },
  ]}
/>
```

### Custom colors

```tsx
<CloudChart
  data={[
    { text: 'Accessibility', value: 90, color: 'var(--gnome-blue-3, #3584e4)' },
    { text: 'Performance', value: 75, color: 'var(--gnome-green-4, #2ec27e)' },
  ]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `CloudChartDataItem[]` | — | `{ text: string; value: number; color?: string }[]` |
| `height` | `number` | `300` | Minimum container height in px |
| `minFontSize` | `number` | `12` | Font size for the lowest-value term |
| `maxFontSize` | `number` | `48` | Font size for the highest-value term |

### Guidelines

- Use for keyword frequency, tag weights, or skill matrices.
- Narrow the font range (`minFontSize=14, maxFontSize=28`) for more uniform visual weight.
- The cloud wraps naturally — the container grows vertically if terms overflow.

---

Source: packages/charts/src/components/ComposedChart/README.md

Mixed chart combining bars, lines, and areas on shared axes.

Each series declares its `type` — `"bar"`, `"line"`, or `"area"` — and all share the same x axis and y scale.

```tsx
import { ComposedChart } from '@gnome-ui/charts';

const data = [
  { month: 'Jan', revenue: 4200, expenses: 2400, profit: 1800 },
  { month: 'Feb', revenue: 3800, expenses: 2200, profit: 1600 },
  { month: 'Mar', revenue: 5100, expenses: 2600, profit: 2500 },
];

<ComposedChart
  data={data}
  xAxisKey="month"
  showLegend
  series={[
    { dataKey: 'revenue', type: 'bar', name: 'Revenue' },
    { dataKey: 'expenses', type: 'area', name: 'Expenses' },
    { dataKey: 'profit', type: 'line', name: 'Profit' },
  ]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Data rows |
| `series` | `ComposedChartSeries[]` | — | Series definitions |
| `xAxisKey` | `string` | `"name"` | Key used for the x axis |
| `height` | `number` | `300` | Container height in px |
| `showGrid` | `boolean` | `true` | Show background grid |
| `showLegend` | `boolean` | `false` | Show series legend |
| `className` | `string` | — | Extra CSS class |
| `aria-label` | `string` | auto | Accessible label for the chart |

### `ComposedChartSeries`

| Field | Type | Description |
|-------|------|-------------|
| `dataKey` | `string` | Key in each data row |
| `type` | `"bar" \| "line" \| "area"` | Visual encoding |
| `name` | `string` | Legend / tooltip label |
| `color` | `string` | Override series color |

### Guidelines

- Use `bar` for discrete categorical volumes, `line` for trends, `area` to show range/fill.
- Mixing too many series types adds visual noise — prefer 2–3 series maximum.

---

Source: packages/charts/src/components/FunnelChart/README.md

Funnel visualization for conversion rates and sales pipelines.

Each item in `data` represents one stage. Values are rendered as trapezoid segments from largest to smallest.

```tsx
import { FunnelChart } from '@gnome-ui/charts';

<FunnelChart
  data={[
    { name: 'Visits', value: 5000 },
    { name: 'Leads', value: 2400 },
    { name: 'Prospects', value: 1398 },
    { name: 'Customers', value: 980 },
  ]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `FunnelChartDataItem[]` | — | Funnel stages, top to bottom |
| `height` | `number` | `300` | Container height in px |
| `showLabels` | `boolean` | `true` | Show stage name labels inside segments |
| `className` | `string` | — | Extra CSS class |

### `FunnelChartDataItem`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Stage label |
| `value` | `number` | Stage count / amount |
| `color` | `string` | Override segment color |

### Guidelines

- Order stages from largest (top) to smallest (bottom).
- Use `showLabels={false}` and rely on the tooltip when segment names are long.

---

Source: packages/charts/src/components/GaugeChart/README.md

Single-value speedometer gauge built on Recharts. Renders a semicircular arc between `min` and `max`, with the current value shown as a label at its center — for KPI dashboards, alongside `StatCard` from `@gnome-ui/layout`.

```tsx
import { GaugeChart } from '@gnome-ui/charts';

<GaugeChart value={72} label="CPU" />
```

### Status thresholds

Pass ascending `{ value, color }` bands to color the arc based on where the current value falls (e.g. green/yellow/red). Ignored when `color` is set explicitly.

```tsx
<GaugeChart
  value={90}
  label="Disk usage"
  thresholds={[
    { value: 0, color: 'var(--gnome-green-4, #2ec27e)' },
    { value: 60, color: 'var(--gnome-yellow-5, #e5a50a)' },
    { value: 85, color: 'var(--gnome-red-3, #e01b24)' },
  ]}
/>
```

### Custom range and formatting

```tsx
<GaugeChart
  value={4200}
  min={0}
  max={5000}
  label="Revenue"
  valueFormatter={(v) => `$${v.toLocaleString()}`}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current value. Shown as-is even when it exceeds `min`/`max`; the arc itself is clamped to the range |
| `min` | `number` | `0` | Minimum of the gauge range |
| `max` | `number` | `100` | Maximum of the gauge range |
| `height` | `number` | `220` | Chart height in px |
| `color` | `string` | — | Explicit arc color; overrides `thresholds` |
| `thresholds` | `{ value, color }[]` | — | Ascending value/color bands; the arc uses the color of the highest band `<= value` |
| `showValue` | `boolean` | `true` | Show the numeric value and `label` centered on the gauge |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for the displayed value |
| `label` | `string` | — | Caption rendered under the value |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

### Guidelines

- Use `thresholds` for status-style gauges (capacity, health scores) instead of a single `color`, so the arc communicates severity at a glance.
- Values are not required to be percentages — set `min`/`max` to match the metric's real range.

---

Source: packages/charts/src/components/Heatmap/README.md

Generic matrix heatmap built in pure CSS/SVG (no Recharts dependency) — for correlation matrices, density grids, or any row × column value grid. For a calendar-shaped activity heatmap, use `ContributionGraph` from `@gnome-ui/react` instead.

```tsx
import { Heatmap } from '@gnome-ui/charts';

<Heatmap
  data={[
    { row: 'Mon', column: 'AM', value: 12 },
    { row: 'Mon', column: 'PM', value: 48 },
    { row: 'Tue', column: 'AM', value: 70 },
    { row: 'Tue', column: 'PM', value: 22 },
  ]}
  showValues
/>
```

### Explicit row/column order

By default, rows and columns appear in first-seen order in `data`. Pass `rows`/`columns` to control ordering — useful for sparse matrices where some combinations are missing (those cells render as empty).

```tsx
<Heatmap
  data={data}
  rows={['Mon', 'Tue', 'Wed', 'Thu', 'Fri']}
  columns={['AM', 'PM']}
/>
```

### Legend

```tsx
<Heatmap data={data} showLegend />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `HeatmapDataItem[]` | — | `{ row: string; column: string; value: number }[]` |
| `rows` | `string[]` | first-seen order | Explicit row order, top to bottom |
| `columns` | `string[]` | first-seen order | Explicit column order, left to right |
| `color` | `string` | accent blue | Base color for the intensity scale |
| `min` | `number` | lowest value in `data` | Explicit domain minimum |
| `max` | `number` | highest value in `data` | Explicit domain maximum |
| `cellSize` | `number` | `40` | Cell side length in px |
| `showValues` | `boolean` | `false` | Show the formatted value inside each cell |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for cell values and the legend |
| `showLegend` | `boolean` | `false` | Show a min→max color scale below the grid |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

### Guidelines

- Pass `min`/`max` explicitly to keep the color scale comparable across multiple `Heatmap` instances (e.g. one per dashboard tab).
- Each cell exposes its row, column, and value via `title` and `aria-label` — hover or use a screen reader for exact values even when `showValues` is off.

---

Source: packages/charts/src/components/LineChart/README.md

Line chart built on Recharts with GNOME design tokens for axes, grid, and tooltips.

Supports multiple series rendered as colored lines, an optional horizontal grid, and a legend.

```tsx
import { LineChart } from '@gnome-ui/charts';

<LineChart
  data={[
    { day: 'Mon', cpu: 42, memory: 68 },
    { day: 'Tue', cpu: 58, memory: 72 },
  ]}
  series={[
    { dataKey: 'cpu', name: 'CPU %' },
    { dataKey: 'memory', name: 'Memory %' },
  ]}
  xAxisKey="day"
  showLegend
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Array of data points |
| `series` | `LineChartSeries[]` | — | Series definitions (`dataKey`, `name?`, `color?`) |
| `xAxisKey` | `string` | `"name"` | Key used for the x-axis labels |
| `height` | `number` | `300` | Chart height in px |
| `showGrid` | `boolean` | `true` | Show horizontal grid lines |
| `showLegend` | `boolean` | `false` | Show series legend |
| `aria-label` | `string` | auto | Accessible label for the chart |

### Guidelines

- Use for continuous data over time (metrics, trends, telemetry).
- Pass `color` in each series to override the default GNOME palette.
- For compact inline use, prefer `SparkLineChart`.

---

Source: packages/charts/src/components/PieChart/README.md

Pie and donut chart built on Recharts for part-to-whole comparisons.

Each data item maps to a slice. Enable `donut` to render a ring with a hollow center, `showLabels` to add percentage labels outside each slice, and `showLegend` for a color key.

```tsx
import { PieChart } from '@gnome-ui/charts';

<PieChart
  data={[
    { label: 'Chrome', value: 62 },
    { label: 'Firefox', value: 18 },
    { label: 'Safari', value: 11 },
  ]}
  donut
  showLegend
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `PieChartDataItem[]` | — | `{ label: string; value: number; color?: string }[]` |
| `height` | `number` | `300` | Chart height in px |
| `donut` | `boolean` | `false` | Render as donut (hollow center) |
| `showLabels` | `boolean` | `false` | Show percentage labels outside slices |
| `showLegend` | `boolean` | `false` | Show color legend |

### Guidelines

- Use donut mode when you want to add a central summary value via a custom overlay.
- Slices smaller than 4 % suppress their label automatically to avoid clutter.
- Pass `color` per item to use brand or semantic colors (success, error, warning).

---

Source: packages/charts/src/components/RadarChart/README.md

Radar (spider) chart built on Recharts for comparing multiple attributes across one or more subjects.

Each axis corresponds to a dimension in the data; each series traces a polygon across those axes. Enable `filled` to shade the polygon interior.

```tsx
import { RadarChart } from '@gnome-ui/charts';

<RadarChart
  data={[
    { skill: 'TypeScript', alice: 90, bob: 70 },
    { skill: 'React', alice: 85, bob: 80 },
    { skill: 'CSS', alice: 60, bob: 75 },
  ]}
  series={[
    { dataKey: 'alice', name: 'Alice' },
    { dataKey: 'bob', name: 'Bob' },
  ]}
  angleKey="skill"
  filled
  showLegend
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `Record<string, unknown>[]` | — | Array of data points |
| `series` | `RadarChartSeries[]` | — | Series definitions (`dataKey`, `name?`, `color?`) |
| `angleKey` | `string` | `"name"` | Key for the angular dimension labels |
| `height` | `number` | `400` | Chart height in px |
| `filled` | `boolean` | `false` | Fill the polygon with a semi-transparent color |
| `showLegend` | `boolean` | `false` | Show series legend |

### Guidelines

- Best with 3–8 axes. Too many axes make labels unreadable.
- Use `filled` for single-subject charts; unfilled for multi-subject comparisons to avoid overlap.

---

Source: packages/charts/src/components/RadialBarChart/README.md

Radial bar chart built on Recharts. Each data item renders as a circular arc, useful for showing multiple metrics as circular progress rings.

Enable `showLabels` to overlay category names on each arc, and `showLegend` for a color key. Increase `innerRadius` to create a donut-like gap at the center.

```tsx
import { RadialBarChart } from '@gnome-ui/charts';

<RadialBarChart
  data={[
    { label: 'CPU', value: 72 },
    { label: 'Memory', value: 58 },
    { label: 'Disk', value: 41 },
  ]}
  showLegend
/>
```

### Custom colors

```tsx
<RadialBarChart
  data={[
    { label: 'Completed', value: 90, color: 'var(--gnome-green-4, #2ec27e)' },
    { label: 'In Progress', value: 60, color: 'var(--gnome-blue-3, #3584e4)' },
    { label: 'Blocked', value: 25, color: 'var(--gnome-red-3, #e01b24)' },
  ]}
  showLabels
  showLegend
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `RadialBarChartDataItem[]` | — | `{ label: string; value: number; color?: string }[]` |
| `height` | `number` | `300` | Chart height in px |
| `innerRadius` | `number \| string` | — | Inner radius of arcs (e.g. `"40%"`) |
| `showLabels` | `boolean` | `false` | Overlay category labels on arcs |
| `showLegend` | `boolean` | `false` | Show color legend |

### Guidelines

- Values are treated as percentages (0–100) — pass normalized numbers.
- Use semantic colors per item for status dashboards (green/red/yellow).

---

Source: packages/charts/src/components/SankeyChart/README.md

Flow diagram built on Recharts. Renders named nodes as columns of rectangles connected by curved, proportionally-sized links — for multi-stage funnels, user journeys, or any flow between categories.

```tsx
import { SankeyChart } from '@gnome-ui/charts';

<SankeyChart
  nodes={[
    { name: 'Visitors' },
    { name: 'Signups' },
    { name: 'Customers' },
    { name: 'Churn' },
  ]}
  links={[
    { source: 'Visitors', target: 'Signups', value: 1000 },
    { source: 'Signups', target: 'Customers', value: 600 },
    { source: 'Signups', target: 'Churn', value: 400 },
  ]}
/>
```

Node labels are placed to the right of each node, except for terminal nodes (those with no outgoing links), whose labels are placed to the left — so the last column reads inward rather than off the edge of the chart.

### Node colors and values

Each node cycles through `GNOME_CHART_PALETTE` unless given an explicit `color`. Links inherit their source node's color at reduced opacity. Enable `showValues` to append the formatted value to each node's label.

```tsx
<SankeyChart
  nodes={[
    { name: 'Organic', color: 'var(--gnome-green-4, #2ec27e)' },
    { name: 'Paid', color: 'var(--gnome-orange-3, #ff7800)' },
    { name: 'Converted' },
  ]}
  links={[
    { source: 'Organic', target: 'Converted', value: 320 },
    { source: 'Paid', target: 'Converted', value: 180 },
  ]}
  showValues
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `nodes` | `SankeyChartNode[]` | — | `{ name: string; color?: string }[]` |
| `links` | `SankeyChartLink[]` | — | `{ source: string; target: string; value: number }[]`, referencing node names |
| `height` | `number` | `400` | Chart height in px |
| `nodeWidth` | `number` | `12` | Node rectangle thickness in px |
| `nodePadding` | `number` | `24` | Vertical gap between stacked nodes in the same column |
| `showValues` | `boolean` | `false` | Append the formatted value to each node label |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for labels and the tooltip |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

### Guidelines

- Keep node names short — long labels can overlap the next column when a diagram has many stages.
- `source`/`target` reference node `name`s directly; there's no need to track array indices.

---

Source: packages/charts/src/components/ScatterChart/README.md

Scatter and bubble chart for visualizing correlation between two numeric variables.

Each series has its own `data` array with `x` and `y` keys. Add a `zKey` to encode a third dimension as bubble size.

```tsx
import { ScatterChart } from '@gnome-ui/charts';

<ScatterChart
  series={[
    {
      name: 'Product A',
      data: [
        { x: 10, y: 30 },
        { x: 40, y: 80 },
        { x: 70, y: 50 },
      ],
    },
  ]}
/>
```

### Bubble chart

Pass `zKey` on the series and a `bubbleRange` to scale bubble area:

```tsx
<ScatterChart
  series={[
    {
      name: 'Sales',
      data: [
        { x: 10, y: 30, z: 200 },
        { x: 40, y: 80, z: 800 },
      ],
      zKey: 'z',
    },
  ]}
  bubbleRange={[40, 600]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `series` | `ScatterChartSeries[]` | — | One entry per scatter group |
| `xLabel` | `string` | `"x"` | Tooltip label for the x axis |
| `yLabel` | `string` | `"y"` | Tooltip label for the y axis |
| `height` | `number` | `300` | Container height in px |
| `showGrid` | `boolean` | `true` | Show background grid |
| `showLegend` | `boolean` | `false` | Show series legend |
| `bubbleRange` | `[number, number]` | `[40, 400]` | Min/max bubble area (px²) |
| `className` | `string` | — | Extra CSS class |

### `ScatterChartSeries`

| Field | Type | Description |
|-------|------|-------------|
| `data` | `Record<string, unknown>[]` | Points with at least `x` and `y` |
| `name` | `string` | Series label |
| `color` | `string` | Dot fill color |
| `zKey` | `string` | Key to use for bubble size (`ZAxis`) |

---

Source: packages/charts/src/components/TreeMap/README.md

Tree map built on Recharts. Displays hierarchical data as nested rectangles; area is proportional to each item's value.

Items with the same `group` share a color. Items without a `group` are colored individually.

```tsx
import { TreeMap } from '@gnome-ui/charts';

// Flat (no grouping)
<TreeMap
  data={[
    { label: 'React', value: 4200 },
    { label: 'Vue', value: 2100 },
    { label: 'Angular', value: 1800 },
  ]}
  height={400}
/>

// Grouped
<TreeMap
  data={[
    { label: 'React', value: 4200, group: 'Frontend' },
    { label: 'Node.js', value: 3800, group: 'Backend' },
    { label: 'Python', value: 5100, group: 'Backend' },
  ]}
  height={400}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TreeMapDataItem[]` | — | `{ label: string; value: number; group?: string }[]` |
| `height` | `number` | — | Chart height in px |
| `showLabels` | `boolean` | `true` | Show label + value inside each tile |

### Guidelines

- Labels are suppressed automatically on tiles narrower than 40 px or shorter than 24 px.
- Use grouping to cluster related items under a shared color.
- Best for showing relative proportions in a space-efficient way (file sizes, budget breakdowns).

---

Source: packages/charts/src/components/WaterfallChart/README.md

Floating-bar chart built on Recharts for the cumulative effect of a sequence of increases and decreases — revenue bridges, budget breakdowns, cohort attrition. Each bar starts where the previous one ended; mark `isTotal` on start/end/subtotal bars to anchor them to zero instead.

```tsx
import { WaterfallChart } from '@gnome-ui/charts';

<WaterfallChart
  data={[
    { label: 'Starting revenue', value: 42000, isTotal: true },
    { label: 'New sales', value: 12000 },
    { label: 'Upsells', value: 4000 },
    { label: 'Churn', value: -6000 },
    { label: 'Refunds', value: -1500 },
    { label: 'Ending revenue', value: 50500, isTotal: true },
  ]}
/>
```

### Colors and value labels

```tsx
<WaterfallChart
  data={data}
  increaseColor="var(--gnome-green-4, #2ec27e)"
  decreaseColor="var(--gnome-red-3, #e01b24)"
  totalColor="var(--gnome-purple-3, #9141ac)"
  showValues
  valueFormatter={(v) => `$${v.toLocaleString()}`}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `WaterfallChartDataItem[]` | — | `{ label: string; value: number; isTotal?: boolean }[]`. Non-total bars float from the running cumulative total; `isTotal` bars are anchored to zero |
| `height` | `number` | `300` | Chart height in px |
| `increaseColor` | `string` | green | Color for positive delta bars |
| `decreaseColor` | `string` | red | Color for negative delta bars |
| `totalColor` | `string` | accent color | Color for `isTotal` bars |
| `showGrid` | `boolean` | `true` | Show the horizontal grid |
| `showValues` | `boolean` | `false` | Show the signed delta (or absolute value for totals) above each bar |
| `valueFormatter` | `(value: number) => string` | locale-aware | Custom formatter for values and axis ticks |
| `aria-label` | `string` | auto | Accessible label for the chart |
| `className` | `string` | — | Extra CSS class on the wrapper |

### Guidelines

- Put `isTotal: true` on the first and last bars (and any subtotal checkpoints) so they read as absolute values instead of floating deltas.
- The running total resets to a bar's own value whenever `isTotal` is set — the next non-total bar floats from that new baseline.
- There is no spark/compact variant: condensing multiple labeled steps into a card-sized sparkline loses the per-step readability that makes a waterfall useful in the first place. For a single value-vs-target summary at that scale, use `SparkBulletChart` or `SparkGaugeChart` instead.