@gnome-ui/react 1.12.0 → 1.14.0

package/README.md

@@ -3,6 +3,8 @@
 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://eljijuna.github.io/gnome-ui/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
 
 Live documentation: **[Storybook →](https://eljijuna.github.io/gnome-ui/)**
@@ -45,6 +47,7 @@ export default function App() {
 |-----------|-------------|
 | [`Button`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-button--docs) | Default, Suggested, Destructive, Flat, Raised variants; `osd` overlay modifier; sm/md/lg sizes; pill and circular shapes |
 | [`SplitButton`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-splitbutton--docs) | Primary action button with attached dropdown arrow; Default, Suggested, Destructive variants |
+| [`ButtonContent`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-buttoncontent--docs) | Icon + label layout helper for buttons that contain both an icon and text |
 | [`Switch`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-switch--docs) | On/off toggle for settings that apply immediately |
 | [`Checkbox`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-checkbox--docs) | Multi-selection with checked, unchecked, and indeterminate states |
 | [`RadioButton`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-radiobutton--docs) | Single-selection within a group; keyboard arrow-key navigation |
@@ -70,26 +73,38 @@ export default function App() {
 | [`StatusPage`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-statuspage--docs) | Empty-state page with icon, title, description, and optional actions; `compact` prop for sidebars/popovers |
 | [`Separator`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-separator--docs) | Horizontal/vertical dividing line between content groups |
 | [`Chip`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-chip--docs) | Compact pill-shaped label for tags, filters, and multi-select; static, removable, and selectable modes |
+| [`ShortcutLabel`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-shortcutlabel--docs) | Renders keyboard shortcut tokens (e.g. `Ctrl+S`) as individual key cap pills |
+| [`WindowTitle`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-windowtitle--docs) | Two-line title + subtitle widget for use inside a `HeaderBar` |
 
 ### Layout & containers
 
 | Component | Description |
 |-----------|-------------|
+| [`Box`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-box--docs) | Flex layout primitive equivalent to `GtkBox` — vertical or horizontal, with GNOME HIG spacing scale |
 | [`Card`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-card--docs) | Elevated surface for grouping content; static or interactive (activatable) |
 | [`Frame`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-frame--docs) | Bordered surface without background fill — mirrors `GtkFrame` |
+| [`Bin`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-bin--docs) | Single-child transparent wrapper — mirrors `AdwBin` |
 | [`HeaderBar`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-headerbar--docs) | Title bar with centered title and leading/trailing action slots |
 | [`Toolbar`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-toolbar--docs) | Horizontal action bar with 6 px padding/gap for flat and raised buttons |
 | [`Spacer`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-spacer--docs) | Invisible `flex: 1` filler to push trailing items to the end of a `Toolbar` |
+| [`ToolbarView`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-toolbarview--docs) | Layout with pinned top/bottom bars and scrollable center content — mirrors `AdwToolbarView` |
 | [`LinkedGroup`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-linkedgroup--docs) | Renders children as a single connected unit with merged borders; horizontal and vertical |
 | [`Sidebar`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-sidebar--docs) / `SidebarSection` / `SidebarItem` | Lateral navigation panel with named sections, suffix widgets, and context menus |
+| [`BoxedList`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-boxedlist--docs) | Rounded bordered list of rows — canonical GNOME settings pattern |
 | [`ActionRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-actionrow--docs) | Settings row with title, subtitle, leading icon, and trailing widget |
 | [`ButtonRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-buttonrow--docs) | Full-width activatable row styled as a button inside a `BoxedList`; Default, Suggested, Destructive |
 | [`ExpanderRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-expanderrow--docs) | Collapsible `ActionRow` that reveals nested rows; controlled and uncontrolled |
-| [`BoxedList`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-boxedlist--docs) | Rounded bordered list of rows — canonical GNOME settings pattern |
-| [`WrapBox`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-wrapbox--docs) | Flexible wrapping layout for tag/chip lists that flows across multiple lines |
+| [`SwitchRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-switchrow--docs) | `ActionRow` with a built-in `Switch` trailing widget |
+| [`CheckRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-checkrow--docs) | `ActionRow` with a built-in `Checkbox` trailing widget |
+| [`ComboRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-comborow--docs) | `ActionRow` with a built-in `Dropdown` for selecting a value |
+| [`EntryRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-entryrow--docs) | Inline text entry row — title doubles as floating label |
+| [`PasswordEntryRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-passwordentryrow--docs) | `EntryRow` variant with show/hide password toggle |
+| [`SpinRow`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-spinrow--docs) | `ActionRow` with a built-in `SpinButton` for numeric values |
+| [`WrapBox`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-wrapbox--docs) | Wrapping flex container for tag/chip lists that flows across multiple lines — mirrors `AdwWrapBox` |
 | [`TabBar`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-tabs--docs) / `TabItem` / `TabPanel` | Tab-based navigation with keyboard support, optional close buttons, and `inline` variant |
 | [`ViewSwitcher`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-viewswitcher--docs) / `ViewSwitcherItem` | Segmented pill control for switching between 2–4 top-level views |
 | [`ViewSwitcherSidebar`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-viewswitchersidebar--docs) / `ViewSwitcherSidebarItem` | Sidebar-based view switcher — replaces `GtkStackSidebar` |
+| [`Carousel`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-carousel--docs) / `CarouselIndicatorDots` / `CarouselIndicatorLines` | Swipeable page carousel with dot or line indicators — mirrors `AdwCarousel` |
 | [`ShortcutsDialog`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-shortcutsdialog--docs) | Modal listing keyboard shortcuts with integrated search |
 
 ### Overlays
@@ -98,10 +113,19 @@ export default function App() {
 |-----------|-------------|
 | [`Toast`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-toast--docs) / `Toaster` | Non-blocking temporary notification with auto-dismiss, action, and queue support |
 | [`Dialog`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-dialog--docs) | Blocking modal with title, body, focus trap, and configurable buttons |
+| [`BottomSheet`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-bottomsheet--docs) | Slide-up panel from the bottom of the viewport with drag handle and optional title |
 | [`Tooltip`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-tooltip--docs) | Floating informational label on hover/focus with auto-flip positioning |
 | [`Popover`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-popover--docs) | Floating interactive panel with arrow and auto-flip positioning |
 | [`Banner`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-banner--docs) | Persistent message strip with optional action and dismiss |
 
+### Preferences
+
+| Component | Description |
+|-----------|-------------|
+| [`PreferencesGroup`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-preferencesgroup--docs) | Titled `BoxedList` section with optional description and header suffix widget |
+| [`PreferencesPage`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-preferencespage--docs) | Named page that contains one or more `PreferencesGroup` sections |
+| [`PreferencesDialog`](https://eljijuna.github.io/gnome-ui/?path=/docs/components-preferencesdialog--docs) | Tabbed preferences window — mirrors `AdwPreferencesDialog` |
+
 ### Adaptive layout
 
 | Component | Description |
@@ -110,6 +134,7 @@ export default function App() {
 | [`Clamp`](https://eljijuna.github.io/gnome-ui/?path=/docs/adaptive-clamp--docs) | Constrains content to a max width, centering it — mirrors `AdwClamp` |
 | [`NavigationSplitView`](https://eljijuna.github.io/gnome-ui/?path=/docs/adaptive-navigationsplitview--docs) | Two-pane layout that collapses to a single pane at ≤ 400 px |
 | [`OverlaySplitView`](https://eljijuna.github.io/gnome-ui/?path=/docs/adaptive-overlaysplitview--docs) | Sidebar becomes slide-over overlay at ≤ 400 px |
+| [`NavigationView`](https://eljijuna.github.io/gnome-ui/?path=/docs/adaptive-navigationview--docs) / `NavigationPage` | Mobile-style navigation stack with forward/back slide transitions — mirrors `AdwNavigationView` |
 | [`ViewSwitcherBar`](https://eljijuna.github.io/gnome-ui/?path=/docs/adaptive-viewswitcherbar--docs) | Bottom bar for `ViewSwitcher` items on narrow screens (≤ 550 px) |
 | [`BreakpointBin`](https://eljijuna.github.io/gnome-ui/?path=/docs/adaptive-breakpointbin--docs) | Applies layout changes when the **component** crosses a size threshold — CSS container queries equivalent |
 

package/dist/components/Box/Box.d.ts

@@ -0,0 +1,65 @@
+import { HTMLAttributes, ReactNode } from 'react';
+/** GNOME HIG standard spacing values (matches GtkBox spacing tokens). */
+export type BoxSpacing = 3 | 6 | 12 | 18 | 24 | 32 | 48;
+export type BoxOrientation = "horizontal" | "vertical";
+export type BoxAlign = "start" | "center" | "end" | "stretch" | "baseline";
+export type BoxJustify = "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly";
+export interface BoxProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Direction children are arranged.
+     * `"vertical"` → `flex-direction: column` (default).
+     * `"horizontal"` → `flex-direction: row`.
+     */
+    orientation?: BoxOrientation;
+    /**
+     * Gap between children in pixels.
+     * Accepts any of the GNOME HIG standard spacing values or any CSS string.
+     * Defaults to `6` (the HIG "standard" inner spacing).
+     */
+    spacing?: BoxSpacing | number | string;
+    /**
+     * Cross-axis alignment (`align-items`).
+     * Defaults to `"stretch"` for vertical, `"center"` for horizontal.
+     */
+    align?: BoxAlign;
+    /**
+     * Main-axis distribution (`justify-content`).
+     * Defaults to `"start"`.
+     */
+    justify?: BoxJustify;
+    children?: ReactNode;
+}
+/**
+ * Fundamental flex layout primitive — the web equivalent of `GtkBox`.
+ *
+ * Arranges children in a single row or column with consistent spacing
+ * following the GNOME Human Interface Guidelines spacing scale:
+ *
+ * | Token | px | Use |
+ * |-------|----|-----|
+ * | tight | 3  | Dense UI, icon + label pairs |
+ * | standard | 6 | Default inner spacing |
+ * | medium | 12 | Between related groups |
+ * | large | 18 | Between loosely related sections |
+ * | section | 24 | Page-level section gaps |
+ * | loose | 32 | Large content separation |
+ * | jumbo | 48 | Hero / splash spacing |
+ *
+ * **Usage:**
+ * ```tsx
+ * // Vertical section (heading + content)
+ * <Box spacing={8}>
+ *   <Text variant="caption-heading" color="dim">Devices</Text>
+ *   <BoxedList>…</BoxedList>
+ * </Box>
+ *
+ * // Horizontal icon + label
+ * <Box orientation="horizontal" spacing={6} align="center">
+ *   <Icon name="folder" />
+ *   <Text>Documents</Text>
+ * </Box>
+ * ```
+ *
+ * @see https://developer.gnome.org/hig/guidelines/spacing.html
+ */
+export declare function Box({ orientation, spacing, align, justify, className, style, children, ...props }: BoxProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Box/index.d.ts

@@ -0,0 +1,2 @@
+export { Box } from './Box';
+export type { BoxProps, BoxOrientation, BoxAlign, BoxJustify, BoxSpacing } from './Box';

package/dist/components/ColorPicker/ColorPicker.d.ts

@@ -0,0 +1,70 @@
+import { HTMLAttributes } from 'react';
+export type ColorSwatchSize = "sm" | "md" | "lg";
+export interface ColorSwatchProps extends Omit<HTMLAttributes<HTMLButtonElement>, "onClick" | "onSelect"> {
+    /** CSS color value displayed as the swatch background. */
+    color: string;
+    /** Whether this swatch is the currently selected color. */
+    selected?: boolean;
+    /** Swatch diameter. Defaults to `"md"`. */
+    size?: ColorSwatchSize;
+    /** Called when the user clicks or activates the swatch. */
+    onSelect?: (color: string) => void;
+    /** Accessible label. Defaults to the color value. */
+    "aria-label"?: string;
+    disabled?: boolean;
+}
+/**
+ * Single circular color swatch button.
+ *
+ * Can be used standalone or composed inside `ColorPicker`.
+ * Shows a white checkmark when `selected`.
+ */
+export declare function ColorSwatch({ color, selected, size, onSelect, disabled, className, style, "aria-label": ariaLabel, ...props }: ColorSwatchProps): import("react/jsx-runtime").JSX.Element;
+export interface ColorPickerColor {
+    /** CSS color value (hex recommended). */
+    value: string;
+    /** Human-readable name shown as aria-label and tooltip. */
+    label?: string;
+}
+/** Default Adwaita-named palette (matches Avatar color set). */
+export declare const GNOME_PALETTE: ColorPickerColor[];
+export interface ColorPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Currently selected color value. */
+    value?: string;
+    /** Called when the user selects a color. */
+    onChange?: (value: string) => void;
+    /**
+     * Palette of colors to display.
+     * Defaults to `GNOME_PALETTE` (the 9 Adwaita named colors).
+     */
+    colors?: ColorPickerColor[];
+    /**
+     * Show a "Custom…" button at the end that opens a native color picker.
+     * When a custom color is chosen it is passed to `onChange` and shown
+     * as a selected swatch until another palette color is picked.
+     * Defaults to `false`.
+     */
+    allowCustom?: boolean;
+    /** Swatch size. Defaults to `"md"`. */
+    size?: ColorSwatchSize;
+}
+/**
+ * Color palette picker following the Adwaita `GtkColorButton` + swatch pattern.
+ *
+ * Renders a row of circular `ColorSwatch` items. Keyboard navigation uses
+ * arrow keys (roving tabindex). Optionally adds a "Custom…" button backed
+ * by a hidden `<input type="color">`.
+ *
+ * ```tsx
+ * <ColorPicker value={color} onChange={setColor} />
+ * <ColorPicker value={color} onChange={setColor} allowCustom />
+ * <ColorPicker
+ *   value={color}
+ *   onChange={setColor}
+ *   colors={[{ value: "#ff0000", label: "Red" }, …]}
+ * />
+ * ```
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.ColorButton.html
+ */
+export declare function ColorPicker({ value, onChange, colors, allowCustom, size, className, style, "aria-label": ariaLabel, ...props }: ColorPickerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ColorPicker/index.d.ts

@@ -0,0 +1,2 @@
+export { ColorPicker, ColorSwatch, GNOME_PALETTE } from './ColorPicker';
+export type { ColorPickerProps, ColorPickerColor, ColorSwatchProps, ColorSwatchSize } from './ColorPicker';