@fiestaboard/ui 5.9.0 → 5.11.0

package/dist/components/chrome/page-card.d.ts

@@ -0,0 +1,122 @@
+interface PageCardProps {
+    children: React.ReactNode;
+    className?: string;
+    /**
+     * Pins the card to its parent's height so one section can scroll inside it
+     * rather than the page scrolling as a whole — the schedule calendar's shape.
+     * Pair with `PageLayout`'s own `fillHeight`, and mark the scrolling block
+     * with `<PageSection fill>`.
+     */
+    fillHeight?: boolean;
+}
+/**
+ * THE WHOLE ROUTE, IN ONE CARD. The page title, the toolbar and the content
+ * are blocks inside a single surface whose border sits on `PageLayout`'s
+ * gutter.
+ *
+ * WHY, given that the three of them already shared a column. `Card` puts its
+ * border on the gutter and its words 24px inboard of it, and #270/#272 moved
+ * `PageHeader`, `PageToolbar` and bare content onto that same 24. The column
+ * was right. What was missing is that nothing DREW the border explaining it —
+ * so a reader met words indented from the page edge for no visible reason, and
+ * a route had two left edges of which only one was ever justified by something
+ * you could see. Three passes tried to align blocks to an invisible landmark.
+ * This makes the landmark visible instead, which is the one move that ends the
+ * argument rather than relocating it.
+ *
+ * BLOCKS THAT PAD THEMSELVES. The padding and the divider live on
+ * `PageSection`, not on a `[&>*]` rule here. That was the first shape and
+ * adoption killed it within a day: a settings route wraps its sections in
+ * `TabsContent`, an expandable one wraps its section in `Collapsible`, and a
+ * conditional wraps one in nothing at all — none of which are direct children,
+ * so every one of them lost its inset and its rule. A child selector can only
+ * see one level, and real routes nest.
+ *
+ * So this styles only what it must: `PageHeader` and `PageToolbar` predate the
+ * component and space themselves with a bottom margin, which is right on a
+ * page background and wrong inside a card. Those two get their margin swapped
+ * for block padding here, by slot. Everything else pads itself and composes to
+ * any depth.
+ *
+ * WHAT KEEPS ITS BORDER INSIDE. Sections flatten; items do not. A settings
+ * group or a Setup/Preview panel is a region of the page, so it loses its
+ * border and becomes a `PageSection`. A page tile, a collection tile or a
+ * plugin card is a thing you click to open, and its border IS the click
+ * target — flattening those removes the affordance, so they stay bordered
+ * inside whatever section holds them. That is a call-site judgement rather
+ * than a prop: a route swaps `Card`/`CardHeader`/`CardTitle` for
+ * `PageSection title=…` and leaves its tile grids alone.
+ *
+ * ADDITIVE ON PURPOSE. FiestaUI reaches FiestaBoard through npm, so the two
+ * repos cannot turn over in one commit. `PageHeader` and `PageToolbar` keep
+ * the standalone bottom margins they carry today and this zeroes them through
+ * their `data-slot`s, so a route that has not migrated renders exactly as it
+ * does now.
+ */
+export declare const PageCard: import("react").MemoExoticComponent<({ children, className, fillHeight }: PageCardProps) => import("react").JSX.Element>;
+/**
+ * Standard div props come along so a section can take an `id` (the settings
+ * screens deep-link to one), an `aria-*`, a `style`. `title` is omitted
+ * because the HTML attribute of that name is a string tooltip and this one is
+ * a heading node — leaving both in scope would let a typo silently render a
+ * browser tooltip instead of a heading.
+ */
+interface PageSectionProps extends Omit<React.ComponentProps<"div">, "title"> {
+    children: React.ReactNode;
+    /** Renders a `CardTitle` at the settings-card scale (#274). */
+    title?: React.ReactNode;
+    /**
+     * Leading glyph for the title, forwarded to `CardTitle`'s icon slot — so it
+     * is decorative and never announced, the title's text being the name.
+     *
+     * Exists because the settings screens this component replaces had already
+     * converged on it: 24 of FiestaBoard's section headers spell out
+     * `flex items-center gap-2 text-base` with an `h-4 w-4` glyph by hand, which
+     * is the exact pattern #274 added the slot for.
+     */
+    icon?: React.ReactNode;
+    /** Sits under the title, in `CardDescription`'s tone. */
+    description?: React.ReactNode;
+    /** Right-aligned slot on the title row — a section-level action. */
+    action?: React.ReactNode;
+    /**
+     * Makes this the block that scrolls under `PageCard fillHeight`. Exactly one
+     * section per card should take it.
+     */
+    fill?: boolean;
+    /**
+     * Accessible name for the scroll region `fill` creates. Only read when
+     * `fill` is set. Defaults to the section's `title` when that is a string.
+     */
+    scrollLabel?: string;
+    className?: string;
+    /**
+     * Classes for the CONTENT region, below the heading.
+     *
+     * This exists because the collapse costs something: `Card` split its
+     * heading and its body into two components a consumer could class
+     * separately, and `PageSection` is one node doing both. Nearly every
+     * settings section it replaces carries a `space-y-*` that belongs to the
+     * body alone — put on the root it would also space the heading away from
+     * the body, on top of the heading's own margin.
+     */
+    contentClassName?: string;
+}
+/**
+ * A BLOCK INSIDE A `PageCard`, optionally titled. This is what a content
+ * `Card` becomes once the route itself is the card — the same heading and the
+ * same words, with its border traded for the hairline above it.
+ *
+ * IT PADS ITSELF, and draws its own top rule when it is not the first thing in
+ * its container. That is what lets it sit inside a `TabsContent`, a
+ * `Collapsible` or a bare conditional and still land on the content column —
+ * the arrangement every real settings route turns out to need, and the one a
+ * parent's `[&>*]` rule cannot reach.
+ *
+ * REPLACES `PageInset`. That component existed to put bare body content on the
+ * content column of a route that had no card to explain the column. A route
+ * that IS a card does not need it: the block padding here does the same 24 and
+ * draws the rule as well.
+ */
+export declare const PageSection: import("react").MemoExoticComponent<({ children, title, icon, description, action, fill, scrollLabel, className, contentClassName, ...rest }: PageSectionProps) => import("react").JSX.Element>;
+export {};

package/dist/components/chrome/page-card.js

@@ -0,0 +1,46 @@
+import { cn as e } from "../../lib/utils.js";
+import { Card as t, CardDescription as n, CardTitle as r } from "../containment/card.js";
+import { memo as i } from "react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+//#region src/components/chrome/page-card.tsx
+var s = i(function({ children: n, className: r, fillHeight: i }) {
+	return /* @__PURE__ */ a(t, {
+		"data-slot": "page-card",
+		className: e("gap-0 overflow-hidden py-0", "[&>[data-slot=page-header]]:mb-0 [&>[data-slot=page-header]]:py-6", "[&>[data-slot=page-toolbar]]:mb-0 [&>[data-slot=page-toolbar]]:py-6", "[&>[data-slot=page-toolbar]]:border-t", i && "min-h-0 flex-1", r),
+		children: n
+	});
+}), c = i(function({ children: t, title: i, icon: s, description: c, action: l, fill: u, scrollLabel: d, className: f, contentClassName: p, ...m }) {
+	let h = i != null || c != null || l != null, g = d ?? (typeof i == "string" ? i : void 0);
+	return /* @__PURE__ */ o("div", {
+		"data-slot": "page-section",
+		className: e("px-6 py-6 [&:not(:first-child)]:border-t", u && "flex min-h-0 flex-1 flex-col overflow-hidden", f),
+		...m,
+		children: [h && /* @__PURE__ */ o("div", {
+			className: "mb-4 flex items-start justify-between gap-4",
+			children: [/* @__PURE__ */ o("div", {
+				className: "min-w-0",
+				children: [i != null && /* @__PURE__ */ a(r, {
+					size: "base",
+					icon: s,
+					children: i
+				}), c != null && /* @__PURE__ */ a(n, {
+					className: "mt-1.5",
+					children: c
+				})]
+			}), l]
+		}), u ? /* @__PURE__ */ a("div", {
+			className: e("min-h-0 flex-1 overflow-auto", p),
+			tabIndex: 0,
+			role: g ? "region" : void 0,
+			"aria-label": g,
+			children: t
+		}) : p ? /* @__PURE__ */ a("div", {
+			className: p,
+			children: t
+		}) : t]
+	});
+});
+//#endregion
+export { s as PageCard, c as PageSection };
+
+//# sourceMappingURL=page-card.js.map

package/dist/components/chrome/page-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-card.js","names":[],"sources":["../../../src/components/chrome/page-card.tsx"],"mappings":";;;;;AA6DA,IAAa,IAAW,EAAK,SAAkB,EAAE,aAAU,cAAW,iBAA6B;CACjG,OACE,kBAAC,GAAD;EACE,aAAU;EACV,WAAW,EAET,8BAKA,qEACA,uEACA,yCACA,KAAc,kBACd,CACF;EAEC;CACG,CAAA;AAEV,CAAC,GAmEY,IAAc,EAAK,SAAqB,EACnD,aACA,UACA,SACA,gBACA,WACA,SACA,gBACA,cACA,qBACA,GAAG,KACgB;CACnB,IAAM,IAAa,KAAS,QAAQ,KAAe,QAAQ,KAAU,MAQ/D,IAAQ,MAAgB,OAAO,KAAU,WAAW,IAAQ,KAAA;CAClE,OACE,kBAAC,OAAD;EACE,aAAU;EACV,WAAW,EAKT,4CACA,KAAQ,gDACR,CACF;EACA,GAAI;EAXN,UAAA,CAaG,KACC,kBAAC,OAAD;GAAK,WAAU;GAAf,UAAA,CACE,kBAAC,OAAD;IAAK,WAAU;IAAf,UAAA,CACG,KAAS,QACR,kBAAC,GAAD;KAAW,MAAK;KAAa;KAC1B,UAAA;IACQ,CAAA,GAEZ,KAAe,QAAQ,kBAAC,GAAD;KAAiB,WAAU;KAAU,UAAA;IAA6B,CAAA,CACvF;GACJ,CAAA,GAAA,CACE;EAEN,CAAA,GAAA,IACC,kBAAC,OAAD;GACE,WAAW,EAAG,gCAAgC,CAAgB;GAC9D,UAAU;GAIV,MAAM,IAAQ,WAAW,KAAA;GACzB,cAAY;GAEX;EACE,CAAA,IACH,IAEF,kBAAC,OAAD;GAAK,WAAW;GAAmB;EAAc,CAAA,IAEjD,CAEC;;AAET,CAAC"}

package/dist/components/chrome/page-header.js

@@ -25,6 +25,7 @@ function s(e) {
 var c = t(function({ icon: t, title: i, description: a, children: c, className: l, animationDelay: u = "0ms", hue: d }) {
 	let f = d ?? s(i);
 	return /* @__PURE__ */ r("div", {
+		"data-slot": "page-header",
 		className: e("mb-6 flex flex-wrap items-start justify-between gap-x-6 gap-y-3 px-6 animate-card-fade-in", l),
 		style: { animationDelay: u },
 		children: [/* @__PURE__ */ r("div", {

package/dist/components/chrome/page-header.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-header.js","names":[],"sources":["../../../src/components/chrome/page-header.tsx"],"mappings":";;;;AAMA,IAAM,IAAsC,EAAE,UAAU,WAAW,GAStD,IAAY;CAAC;CAAO;CAAU;CAAU;CAAS;CAAQ;AAAQ,GAIxE,IAAqC;CACzC,KAAK;CACL,QAAQ;CACR,QAAQ;CACR,OAAO;CACP,MAAM;CACN,QAAQ;AACV;AAqBA,SAAgB,EAAQ,GAAuB;CAC7C,IAAI,IAAI;CACR,KAAK,IAAI,IAAI,GAAG,IAAI,EAAK,QAAQ,KAE/B,AADA,KAAK,EAAK,WAAW,CAAC,GACtB,IAAI,KAAK,KAAK,GAAG,QAAU;CAE7B,OAAO,EAAU,KAAK,IAAI,CAAC,IAAI,EAAU;AAC3C;AA8DA,IAAa,IAAa,EAAK,SAAoB,EACjD,MAAM,GACN,UACA,gBACA,aACA,cACA,oBAAiB,OACjB,UACkB;CAClB,IAAM,IAAW,KAAO,EAAQ,CAAK;CACrC,OACE,kBAAC,OAAD;EACE,WAAW,EACT,6FACA,CACF;EACA,OAAO,EAAE,kBAAe;EAL1B,UAAA,CAOE,kBAAC,OAAD;GAAK,WAAU;GAAf,UAAA,CACE,kBAAC,MAAD;IAAI,WAAU;IAAd,UAAA,CACE,kBAAC,GAAD;KAAM,WAAW,EAAG,yBAAyB,EAAU,EAAS;KAAG,eAAY;IAAQ,CAAA,GACtF,CACC;GACJ,CAAA,GAAA,kBAAC,KAAD;IAAG,WAAU;IAAoB,UAAA;GAAe,CAAA,CAC7C;EACJ,CAAA,GAAA,CACE;;AAET,CAAC,GAcY,IAAuB,EAAK,WAAgC;CACvE,OACE,kBAAC,OAAD;EAAK,OAAM;EAAI,QAAO;EAAI,eAAY;EAAO,OAAO;EAClD,UAAA,kBAAC,QAAD,EAAA,UACE,kBAAC,kBAAD;GAAgB,IAAG;GAAqB,eAAc;GAAiB,IAAG;GAAI,IAAG;GAAI,IAAG;GAAK,IAAG;GAAhG,UAAA;IACE,kBAAC,QAAD;KAAM,QAAO;KAAK,WAAU;IAAkB,CAAA;IAC9C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAO,WAAU;IAAkB,CAAA;GAClC;EACZ,CAAA,EAAA,CAAA;CACH,CAAA;AAET,CAAC"}
+{"version":3,"file":"page-header.js","names":[],"sources":["../../../src/components/chrome/page-header.tsx"],"mappings":";;;;AAMA,IAAM,IAAsC,EAAE,UAAU,WAAW,GAStD,IAAY;CAAC;CAAO;CAAU;CAAU;CAAS;CAAQ;AAAQ,GAIxE,IAAqC;CACzC,KAAK;CACL,QAAQ;CACR,QAAQ;CACR,OAAO;CACP,MAAM;CACN,QAAQ;AACV;AAqBA,SAAgB,EAAQ,GAAuB;CAC7C,IAAI,IAAI;CACR,KAAK,IAAI,IAAI,GAAG,IAAI,EAAK,QAAQ,KAE/B,AADA,KAAK,EAAK,WAAW,CAAC,GACtB,IAAI,KAAK,KAAK,GAAG,QAAU;CAE7B,OAAO,EAAU,KAAK,IAAI,CAAC,IAAI,EAAU;AAC3C;AA8DA,IAAa,IAAa,EAAK,SAAoB,EACjD,MAAM,GACN,UACA,gBACA,aACA,cACA,oBAAiB,OACjB,UACkB;CAClB,IAAM,IAAW,KAAO,EAAQ,CAAK;CACrC,OACE,kBAAC,OAAD;EACE,aAAU;EACV,WAAW,EACT,6FACA,CACF;EACA,OAAO,EAAE,kBAAe;EAN1B,UAAA,CAQE,kBAAC,OAAD;GAAK,WAAU;GAAf,UAAA,CACE,kBAAC,MAAD;IAAI,WAAU;IAAd,UAAA,CACE,kBAAC,GAAD;KAAM,WAAW,EAAG,yBAAyB,EAAU,EAAS;KAAG,eAAY;IAAQ,CAAA,GACtF,CACC;GACJ,CAAA,GAAA,kBAAC,KAAD;IAAG,WAAU;IAAoB,UAAA;GAAe,CAAA,CAC7C;EACJ,CAAA,GAAA,CACE;;AAET,CAAC,GAcY,IAAuB,EAAK,WAAgC;CACvE,OACE,kBAAC,OAAD;EAAK,OAAM;EAAI,QAAO;EAAI,eAAY;EAAO,OAAO;EAClD,UAAA,kBAAC,QAAD,EAAA,UACE,kBAAC,kBAAD;GAAgB,IAAG;GAAqB,eAAc;GAAiB,IAAG;GAAI,IAAG;GAAI,IAAG;GAAK,IAAG;GAAhG,UAAA;IACE,kBAAC,QAAD;KAAM,QAAO;KAAK,WAAU;IAAkB,CAAA;IAC9C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAM,WAAU;IAAkB,CAAA;IAC/C,kBAAC,QAAD;KAAM,QAAO;KAAO,WAAU;IAAkB,CAAA;GAClC;EACZ,CAAA,EAAA,CAAA;CACH,CAAA;AAET,CAAC"}

package/dist/components/chrome/page-inset.d.ts

@@ -3,6 +3,12 @@ interface PageInsetProps {
     className?: string;
 }
 /**
+ * @deprecated Use `PageSection` inside a `PageCard`. This component exists to
+ * put bare body content on the content column of a route that has no card to
+ * explain that column — and the route is now the card, so the column explains
+ * itself and the section draws the divider too. Kept working for consumers
+ * mid-migration; removed no earlier than the next major.
+ *
  * THE CONTENT COLUMN, FOR BODY CONTENT THAT IS NOT A CARD. Wraps its children
  * in the same `px-6` that `PageHeader` and `PageToolbar` carry, so a tab strip,
  * a byline or a bare paragraph lands on the vertical the page title and every

package/dist/components/chrome/page-inset.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-inset.js","names":[],"sources":["../../../src/components/chrome/page-inset.tsx"],"mappings":";;;;AAwCA,IAAa,IAAY,EAAK,SAAmB,EAAE,aAAU,gBAA6B;CACxF,OAAO,kBAAC,OAAD;EAAK,WAAW,EAAG,QAAQ,CAAS;EAAI;CAAc,CAAA;AAC/D,CAAC"}
+{"version":3,"file":"page-inset.js","names":[],"sources":["../../../src/components/chrome/page-inset.tsx"],"mappings":";;;;AA8CA,IAAa,IAAY,EAAK,SAAmB,EAAE,aAAU,gBAA6B;CACxF,OAAO,kBAAC,OAAD;EAAK,WAAW,EAAG,QAAQ,CAAS;EAAI;CAAc,CAAA;AAC/D,CAAC"}

package/dist/components/chrome/page-toolbar.js

@@ -4,6 +4,7 @@ import { jsx as n, jsxs as r } from "react/jsx-runtime";
 //#region src/components/chrome/page-toolbar.tsx
 var i = { animationDelay: "50ms" }, a = t(function({ left: t, right: a, children: o, className: s }) {
 	return /* @__PURE__ */ n("div", {
+		"data-slot": "page-toolbar",
 		className: e("mb-4 px-6 animate-card-fade-in", s),
 		style: i,
 		children: o ?? /* @__PURE__ */ r("div", {

package/dist/components/chrome/page-toolbar.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-toolbar.js","names":[],"sources":["../../../src/components/chrome/page-toolbar.tsx"],"mappings":";;;;AAKA,IAAM,IAAqC,EAAE,gBAAgB,OAAO,GAmCvD,IAAc,EAAK,SAAqB,EAAE,SAAM,UAAO,aAAU,gBAA+B;CAC3G,OACE,kBAAC,OAAD;EAAK,WAAW,EAAG,kCAAkC,CAAS;EAAG,OAAO;EACrE,UAAA,KACC,kBAAC,OAAD;GACE,WAAW,EACT,qCACA,KAAQ,IAAQ,oBAAoB,IAAQ,gBAAgB,eAC9D;GAJF,UAAA,CAMG,KAAQ,kBAAC,OAAD;IAAK,WAAU;IAA2B,UAAA;GAAU,CAAA,GAC5D,KAAS,kBAAC,OAAD;IAAK,WAAU;IAA2B,UAAA;GAAW,CAAA,CAC5D;;CAEJ,CAAA;AAET,CAAC"}
+{"version":3,"file":"page-toolbar.js","names":[],"sources":["../../../src/components/chrome/page-toolbar.tsx"],"mappings":";;;;AAKA,IAAM,IAAqC,EAAE,gBAAgB,OAAO,GAmCvD,IAAc,EAAK,SAAqB,EAAE,SAAM,UAAO,aAAU,gBAA+B;CAC3G,OACE,kBAAC,OAAD;EAAK,aAAU;EAAe,WAAW,EAAG,kCAAkC,CAAS;EAAG,OAAO;EAC9F,UAAA,KACC,kBAAC,OAAD;GACE,WAAW,EACT,qCACA,KAAQ,IAAQ,oBAAoB,IAAQ,gBAAgB,eAC9D;GAJF,UAAA,CAMG,KAAQ,kBAAC,OAAD;IAAK,WAAU;IAA2B,UAAA;GAAU,CAAA,GAC5D,KAAS,kBAAC,OAAD;IAAK,WAAU;IAA2B,UAAA;GAAW,CAAA,CAC5D;;CAEJ,CAAA;AAET,CAAC"}

package/dist/components/chrome/pagination.d.ts

@@ -0,0 +1,75 @@
+import type * as React from "react";
+/** One slot in the rendered strip: a page number, or an elided run. */
+export type PaginationSlot = number | "ellipsis";
+export interface PaginationRangeOptions {
+    /** The 1-based current page. Clamped into `[1, totalPages]`. */
+    page: number;
+    /** How many pages exist. `<= 0` yields an empty range. */
+    totalPages: number;
+    /** Pages shown either side of the current one. @default 1 */
+    siblingCount?: number;
+    /** Pages pinned to each end of the strip. @default 1 */
+    boundaryCount?: number;
+}
+/**
+ * The slots to render for one page of a list: boundary pages, the current
+ * page and its siblings, and `"ellipsis"` wherever a run of two or more pages
+ * is elided.
+ *
+ * The returned length is stable for a given `totalPages`/`siblingCount`/
+ * `boundaryCount` (until the range is short enough to fit whole), which is
+ * what keeps the pager from resizing under the reader's cursor.
+ */
+export declare function paginationRange({ page, totalPages, siblingCount, boundaryCount, }: PaginationRangeOptions): PaginationSlot[];
+/** Localized copy. Required in full — the package ships no English defaults. */
+export interface PaginationLabels {
+    /** Accessible name for the `<nav>` landmark, e.g. "Blog pages". */
+    navigation: string;
+    /** Accessible name for the previous-page chevron, e.g. "Previous page". */
+    previous: string;
+    /** Accessible name for the next-page chevron, e.g. "Next page". */
+    next: string;
+    /** Accessible name for a numbered link, e.g. `(n) => \`Page ${n}\``. */
+    page: (page: number) => string;
+    /** Screen-reader-only announcement for an elided run, e.g. "More pages". */
+    ellipsis: string;
+}
+/** Which control `renderLink` is being asked for, and where it goes. */
+export interface PaginationLinkItem {
+    /** The 1-based page this control navigates to. */
+    page: number;
+    kind: "page" | "previous" | "next";
+    /** True only for the numbered link the reader is currently on. */
+    current: boolean;
+}
+/** Spread these onto your router's Link. `className` MUST land on it. */
+export interface PaginationLinkProps {
+    className: string;
+    children: React.ReactNode;
+    "data-slot": string;
+    "aria-label": string;
+    "aria-current"?: "page";
+    rel?: "prev" | "next";
+}
+export interface PaginationProps extends Omit<React.ComponentProps<"nav">, "aria-label" | "children"> {
+    /** The 1-based current page. Clamped into `[1, totalPages]`. */
+    page: number;
+    /** How many pages exist. `<= 1` renders nothing at all. */
+    totalPages: number;
+    labels: PaginationLabels;
+    /**
+     * Renders one navigating control — inject your router's Link here. Receives
+     * spreadable DOM props first and the semantic item second, the same
+     * signature as {@link "./sidebar".Sidebar}'s `renderLink`. There is
+     * deliberately no `href` shortcut: a bare string href renders a plain `<a>`
+     * that full-page-reloads inside an SPA, which is exactly the trap this prop
+     * exists to avoid.
+     */
+    renderLink: (props: PaginationLinkProps, item: PaginationLinkItem) => React.ReactNode;
+    /** Pages shown either side of the current one. @default 1 */
+    siblingCount?: number;
+    /** Pages pinned to each end of the strip. @default 1 */
+    boundaryCount?: number;
+}
+declare function Pagination({ page, totalPages, labels, renderLink, siblingCount, boundaryCount, className, ...props }: PaginationProps): React.JSX.Element | null;
+export { Pagination };

package/dist/components/chrome/pagination.js

@@ -0,0 +1,93 @@
+import { cn as e } from "../../lib/utils.js";
+import { buttonVariants as t } from "../forms/button.js";
+import { ChevronLeft as n, ChevronRight as r, MoreHorizontal as i } from "lucide-react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+//#region src/components/chrome/pagination.tsx
+function s(e, t) {
+	return Array.from({ length: Math.max(0, t - e + 1) }, (t, n) => e + n);
+}
+function c({ page: e, totalPages: t, siblingCount: n = 1, boundaryCount: r = 1 }) {
+	if (t <= 0) return [];
+	let i = Math.min(Math.max(Math.trunc(e), 1), t), a = s(1, Math.min(r, t)), o = s(Math.max(t - r + 1, r + 1), t), c = Math.max(Math.min(i - n, t - r - n * 2 - 1), r + 2), l = Math.min(Math.max(i + n, r + n * 2 + 2), o.length > 0 ? o[0] - 2 : t - 1);
+	return [
+		...a,
+		...c > r + 2 ? ["ellipsis"] : r + 1 < t - r ? [r + 1] : [],
+		...s(c, l),
+		...l < t - r - 1 ? ["ellipsis"] : t - r > r ? [t - r] : [],
+		...o
+	];
+}
+var l = "h-9 w-auto min-w-9 px-2 tabular-nums";
+function u({ page: s, totalPages: u, labels: d, renderLink: f, siblingCount: p = 1, boundaryCount: m = 1, className: h, ...g }) {
+	if (u <= 1) return null;
+	let _ = Math.min(Math.max(Math.trunc(s), 1), u), v = c({
+		page: _,
+		totalPages: u,
+		siblingCount: p,
+		boundaryCount: m
+	}), y = t({
+		variant: "ghost",
+		size: "icon"
+	}), b = (t) => {
+		let i = t === "previous" ? _ - 1 : _ + 1, o = a(t === "previous" ? n : r, { "aria-hidden": "true" }), s = `pagination-${t}`;
+		return i < 1 || i > u ? /* @__PURE__ */ a("span", {
+			"data-slot": s,
+			"aria-hidden": "true",
+			className: e(y, "pointer-events-none opacity-50"),
+			children: o
+		}) : f({
+			className: y,
+			children: o,
+			"data-slot": s,
+			"aria-label": t === "previous" ? d.previous : d.next,
+			rel: t === "previous" ? "prev" : "next"
+		}, {
+			page: i,
+			kind: t,
+			current: !1
+		});
+	};
+	return /* @__PURE__ */ a("nav", {
+		"data-slot": "pagination",
+		"aria-label": d.navigation,
+		className: h,
+		...g,
+		children: /* @__PURE__ */ o("ul", {
+			role: "list",
+			"data-slot": "pagination-list",
+			className: "flex list-none flex-wrap items-center gap-1 p-0",
+			children: [
+				/* @__PURE__ */ a("li", { children: b("previous") }),
+				v.map((n, r) => n === "ellipsis" ? /* @__PURE__ */ a("li", { children: /* @__PURE__ */ o("span", {
+					"data-slot": "pagination-ellipsis",
+					className: "flex h-9 min-w-9 items-center justify-center text-muted-foreground",
+					children: [/* @__PURE__ */ a(i, {
+						className: "size-4",
+						"aria-hidden": "true"
+					}), /* @__PURE__ */ a("span", {
+						className: "sr-only",
+						children: d.ellipsis
+					})]
+				}) }, `ellipsis-${r}`) : /* @__PURE__ */ a("li", { children: f({
+					className: e(t({
+						variant: n === _ ? "outline" : "ghost",
+						size: "icon"
+					}), l),
+					children: n,
+					"data-slot": "pagination-link",
+					"aria-label": d.page(n),
+					...n === _ ? { "aria-current": "page" } : {}
+				}, {
+					page: n,
+					kind: "page",
+					current: n === _
+				}) }, n)),
+				/* @__PURE__ */ a("li", { children: b("next") })
+			]
+		})
+	});
+}
+//#endregion
+export { u as Pagination, c as paginationRange };
+
+//# sourceMappingURL=pagination.js.map

package/dist/components/chrome/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","names":[],"sources":["../../../src/components/chrome/pagination.tsx"],"mappings":";;;;;AAmFA,SAAS,EAAM,GAAe,GAAuB;CACnD,OAAO,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAM,IAAQ,CAAC,EAAE,IAAI,GAAG,MAAU,IAAQ,CAAK;AACzF;AAsBA,SAAgB,EAAgB,EAC9B,SACA,eACA,kBAAe,GACf,mBAAgB,KAC2B;CAC3C,IAAI,KAAc,GAAG,OAAO,CAAC;CAC7B,IAAM,IAAU,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,CAAI,GAAG,CAAC,GAAG,CAAU,GAE5D,IAAa,EAAM,GAAG,KAAK,IAAI,GAAe,CAAU,CAAC,GACzD,IAAW,EAAM,KAAK,IAAI,IAAa,IAAgB,GAAG,IAAgB,CAAC,GAAG,CAAU,GAKxF,IAAgB,KAAK,IACzB,KAAK,IAAI,IAAU,GAAc,IAAa,IAAgB,IAAe,IAAI,CAAC,GAClF,IAAgB,CAClB,GACM,IAAc,KAAK,IACvB,KAAK,IAAI,IAAU,GAAc,IAAgB,IAAe,IAAI,CAAC,GACrE,EAAS,SAAS,IAAI,EAAS,KAAK,IAAI,IAAa,CACvD;CAEA,OAAO;EACL,GAAG;EAGH,GAAI,IAAgB,IAAgB,IAC/B,CAAC,UAAU,IACZ,IAAgB,IAAI,IAAa,IAC/B,CAAC,IAAgB,CAAC,IAClB,CAAC;EACP,GAAG,EAAM,GAAe,CAAW;EACnC,GAAI,IAAc,IAAa,IAAgB,IAC1C,CAAC,UAAU,IACZ,IAAa,IAAgB,IAC3B,CAAC,IAAa,CAAa,IAC3B,CAAC;EACP,GAAG;CACL;AACF;AAwDA,IAAM,IAAe;AAErB,SAAS,EAAW,EAClB,SACA,eACA,WACA,eACA,kBAAe,GACf,mBAAgB,GAChB,cACA,GAAG,KACe;CAGlB,IAAI,KAAc,GAAG,OAAO;CAE5B,IAAM,IAAU,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,CAAI,GAAG,CAAC,GAAG,CAAU,GAC5D,IAAQ,EAAgB;EAAE,MAAM;EAAS;EAAY;EAAc;CAAc,CAAC,GAElF,IAAY,EAAe;EAAE,SAAS;EAAS,MAAM;CAAO,CAAC,GAG7D,KAAQ,MAA8B;EAC1C,IAAM,IAAS,MAAS,aAAa,IAAU,IAAI,IAAU,GACvD,IAA8B,EAAtB,MAAS,aAAc,IAAqC,GAAtC,EAAa,eAAY,OAAQ,CAAsC,GACrG,IAAO,cAAc;EAU3B,OARI,IAAS,KAAK,IAAS,IAEvB,kBAAC,QAAD;GAAM,aAAW;GAAM,eAAY;GAAO,WAAW,EAAG,GAAW,gCAAgC;GAChG,UAAA;EACG,CAAA,IAIH,EACL;GACE,WAAW;GACX,UAAU;GACV,aAAa;GACb,cAAc,MAAS,aAAa,EAAO,WAAW,EAAO;GAC7D,KAAK,MAAS,aAAa,SAAS;EACtC,GACA;GAAE,MAAM;GAAQ;GAAM,SAAS;EAAM,CACvC;CACF;CAEA,OACE,kBAAC,OAAD;EAAK,aAAU;EAAa,cAAY,EAAO;EAAuB;EAAW,GAAI;EAQnF,UAAA,kBAAC,MAAD;GAAI,MAAK;GAAO,aAAU;GAAkB,WAAU;GAAtD,UAAA;IACE,kBAAC,MAAD,EAAA,UAAK,EAAK,UAAU,EAAM,CAAA;IACzB,EAAM,KAAK,GAAM,MAChB,MAAS,aAGP,kBAAC,MAAD,EAAA,UACE,kBAAC,QAAD;KACE,aAAU;KACV,WAAU;KAFZ,UAAA,CAIE,kBAAC,GAAD;MAAgB,WAAU;MAAS,eAAY;KAAQ,CAAA,GAOvD,kBAAC,QAAD;MAAM,WAAU;MAAW,UAAA,EAAO;KAAe,CAAA,CAC7C;IACJ,CAAA,EAAA,GAdK,YAAY,GAcjB,IAEJ,kBAAC,MAAD,EAAA,UACG,EACC;KACE,WAAW,EACT,EAAe;MAAE,SAAS,MAAS,IAAU,YAAY;MAAS,MAAM;KAAO,CAAC,GAChF,CACF;KACA,UAAU;KACV,aAAa;KACb,cAAc,EAAO,KAAK,CAAI;KAC9B,GAAI,MAAS,IAAU,EAAE,gBAAgB,OAAgB,IAAI,CAAC;IAChE,GACA;KAAE,MAAM;KAAM,MAAM;KAAQ,SAAS,MAAS;IAAQ,CACxD,EACE,GAdK,CAcL,CAER;IACA,kBAAC,MAAD,EAAA,UAAK,EAAK,MAAM,EAAM,CAAA;GACpB;;CACD,CAAA;AAET"}

package/dist/components/chrome/top-nav.d.ts

@@ -0,0 +1,102 @@
+import * as React from "react";
+export type TopNavProps = React.ComponentProps<"div"> & {
+    /**
+     * Render the caller's own element instead of the default `<div>`. This is
+     * how the bar becomes a landmark when it should be one —
+     * `<TopNav asChild><nav aria-label={t("Main")}>…</nav></TopNav>` — without
+     * adding a wrapper element, and without this package guessing at either the
+     * landmark or its localized name. See DECISION 1 above.
+     */
+    asChild?: boolean;
+};
+declare function TopNav({ className, asChild, children, ref, ...props }: TopNavProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export type TopNavBrandProps = React.ComponentProps<"a"> & {
+    /** Render the caller's own element — a router `Link`, usually. */
+    asChild?: boolean;
+};
+/**
+ * The bar's leading identity: a `FiestaLogo`, a wordmark, an icon plus a
+ * title. It is a link because it goes home; when it should not navigate,
+ * `asChild` a `<span>` and the geometry still applies.
+ *
+ * It is NOT `aria-current`-aware. The brand is the site's mark, not a row of
+ * the nav — painting a current-page pill on it (on the home page, where every
+ * visitor starts) would put two active-looking things in one bar.
+ */
+declare function TopNavBrand({ className, asChild, children, ref, ...props }: TopNavBrandProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+/**
+ * The row of destinations. A real `<ul>` of `<li>`s, exactly like `NavList`:
+ * that is what makes a screen reader announce "list, 5 items" and give
+ * per-item position, and it costs nothing visually.
+ *
+ * No landmark of its own — see DECISION 1 on {@link TopNav}.
+ */
+declare function TopNavList({ className, ...props }: React.ComponentProps<"ul">): React.JSX.Element;
+/** One destination's list item. */
+declare function TopNavItem({ className, ...props }: React.ComponentProps<"li">): React.JSX.Element;
+export type TopNavLinkProps = React.ComponentProps<"a"> & {
+    /**
+     * Render the caller's own element instead of an `<a>` — the same
+     * `useRender` mechanics as {@link "./nav-list".NavListLink}. This is how
+     * Docusaurus's `<Link>` (prefetch, base-path handling) or FiestaBoard's
+     * ViewTransitionLink keeps its behaviour while this component keeps owning
+     * the row's look and its ARIA.
+     */
+    asChild?: boolean;
+    /**
+     * Marks this row as the current destination: paints the pill AND sets
+     * `aria-current`. The app derives it from its router — the design system
+     * never guesses at routes.
+     */
+    active?: boolean;
+    /**
+     * Which kind of "current" this row is, when `active`. Defaults to `"page"`;
+     * a docs navbar whose row points at the section you are inside — rather
+     * than at the page you are on — passes `"location"`.
+     * @default "page"
+     */
+    current?: "page" | "step" | "location" | "date" | "time";
+};
+declare function TopNavLink({ className, asChild, active, current, children, ref, ...props }: TopNavLinkProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export type TopNavMenuTriggerProps = React.ComponentProps<"button"> & {
+    /**
+     * Paints the active pill when the current page lives inside this menu.
+     *
+     * It sets `data-active` and the fill, but NOT `aria-current`: the trigger
+     * opens a menu, it is not the current page. The page's `aria-current` goes
+     * on the item inside the menu that points at it.
+     */
+    active?: boolean;
+};
+/**
+ * The bar's dropdown row — a plain `<button>` wearing the link geometry, made
+ * to be handed to `DropdownMenuTrigger asChild`:
+ *
+ * ```tsx
+ * <DropdownMenu>
+ *   <DropdownMenuTrigger asChild>
+ *     <TopNavMenuTrigger>Versions</TopNavMenuTrigger>
+ *   </DropdownMenuTrigger>
+ *   <DropdownMenuContent align="start">
+ *     <DropdownMenuItem render={<a href="/v5" />}>v5</DropdownMenuItem>
+ *   </DropdownMenuContent>
+ * </DropdownMenu>
+ * ```
+ *
+ * Everything that makes it a menu button — `aria-haspopup`, `aria-expanded`,
+ * `aria-controls`, ArrowDown-to-open, typeahead, Escape-restores-focus — comes
+ * from Base UI through that trigger. This contributes the look and the caret,
+ * which is why it stays a bare button rather than a second Menu API.
+ */
+declare function TopNavMenuTrigger({ className, active, children, type, ...props }: TopNavMenuTriggerProps): React.JSX.Element;
+/**
+ * The bar's trailing slot: search, `ThemeToggle`, icon links (`Button`
+ * `size="icon"` `asChild` around an `<a>`). `ml-auto` pushes it to the end, so
+ * the caller never has to know that the row is a flex line.
+ *
+ * It is a plain `<div>`, not a list: these are controls of different kinds
+ * that happen to share an edge, and calling them a list would announce a
+ * "list, 3 items" that means nothing.
+ */
+declare function TopNavActions({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { TopNav, TopNavActions, TopNavBrand, TopNavItem, TopNavLink, TopNavList, TopNavMenuTrigger };

package/dist/components/chrome/top-nav.js

@@ -0,0 +1,91 @@
+import { cn as e } from "../../lib/utils.js";
+import { ChevronDown as t } from "lucide-react";
+import * as n from "react";
+import { jsx as r, jsxs as i } from "react/jsx-runtime";
+import { useRender as a } from "@base-ui/react/use-render";
+//#region src/components/chrome/top-nav.tsx
+var o = [
+	"inline-flex min-h-9 items-center gap-2 rounded-md px-3 py-2 text-sm font-medium whitespace-nowrap",
+	"transition-[color,background-color,border-color,box-shadow] duration-control focus-ring",
+	"[&>svg]:size-4 [&>svg]:shrink-0"
+], s = "nav-active font-semibold", c = "text-muted-foreground nav-active-hover hover:text-foreground";
+function l({ className: t, asChild: r = !1, children: i, ref: o, ...s }) {
+	return a({
+		defaultTagName: "div",
+		ref: o,
+		render: r ? n.Children.only(i) : void 0,
+		props: {
+			"data-slot": "top-nav",
+			className: e("flex min-h-14 w-full flex-wrap items-center gap-x-2 gap-y-1 border-b border-border bg-background px-4 py-2", t),
+			...r ? {} : { children: i },
+			...s
+		}
+	});
+}
+function u({ className: t, asChild: r = !1, children: i, ref: o, ...s }) {
+	return a({
+		defaultTagName: "a",
+		ref: o,
+		render: r ? n.Children.only(i) : void 0,
+		props: {
+			"data-slot": "top-nav-brand",
+			className: e("focus-ring mr-1 flex shrink-0 items-center gap-2 rounded-md px-1 py-1 font-semibold text-foreground", "transition-[color,background-color,border-color,box-shadow] duration-control", t),
+			...r ? {} : { children: i },
+			...s
+		}
+	});
+}
+function d({ className: t, ...n }) {
+	return /* @__PURE__ */ r("ul", {
+		role: "list",
+		"data-slot": "top-nav-list",
+		className: e("flex list-none flex-wrap items-center gap-1 p-0", t),
+		...n
+	});
+}
+function f({ className: t, ...n }) {
+	return /* @__PURE__ */ r("li", {
+		"data-slot": "top-nav-item",
+		className: e("shrink-0", t),
+		...n
+	});
+}
+function p({ className: t, asChild: r = !1, active: i = !1, current: l = "page", children: u, ref: d, ...f }) {
+	return a({
+		defaultTagName: "a",
+		ref: d,
+		render: r ? n.Children.only(u) : void 0,
+		props: {
+			"data-slot": "top-nav-link",
+			"data-active": i ? "" : void 0,
+			"aria-current": i ? l : void 0,
+			className: e(o, i ? s : c, t),
+			...r ? {} : { children: u },
+			...f
+		}
+	});
+}
+function m({ className: n, active: a = !1, children: l, type: u = "button", ...d }) {
+	return /* @__PURE__ */ i("button", {
+		type: u,
+		"data-slot": "top-nav-menu-trigger",
+		"data-active": a ? "" : void 0,
+		className: e(o, a ? s : c, "group/top-nav-menu-trigger", n),
+		...d,
+		children: [l, /* @__PURE__ */ r(t, {
+			"aria-hidden": "true",
+			className: "transition-transform duration-control group-data-[popup-open]/top-nav-menu-trigger:rotate-180"
+		})]
+	});
+}
+function h({ className: t, ...n }) {
+	return /* @__PURE__ */ r("div", {
+		"data-slot": "top-nav-actions",
+		className: e("ml-auto flex shrink-0 items-center gap-1", t),
+		...n
+	});
+}
+//#endregion
+export { l as TopNav, h as TopNavActions, u as TopNavBrand, f as TopNavItem, p as TopNavLink, d as TopNavList, m as TopNavMenuTrigger };
+
+//# sourceMappingURL=top-nav.js.map

package/dist/components/chrome/top-nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"top-nav.js","names":[],"sources":["../../../src/components/chrome/top-nav.tsx"],"mappings":";;;;;;AA6GA,IAAM,IAAc;CAClB;CACA;CACA;AACF,GAIM,IAAqB,4BACrB,IAAsB;AAiB5B,SAAS,EAAO,EAAE,cAAW,aAAU,IAAO,aAAU,QAAK,GAAG,KAAsB;CACpF,OAAO,EAAU;EACf,gBAAgB;EACX;EACL,QAAQ,IAAW,EAAM,SAAS,KAAK,CAAQ,IAA2B,KAAA;EAC1E,OAAO;GACL,aAAa;GACb,WAAW,EAGT,8GACA,CACF;GACA,GAAI,IAAU,CAAC,IAAI,EAAE,YAAS;GAC9B,GAAG;EACL;CACF,CAAC;AACH;AAoBA,SAAS,EAAY,EAAE,cAAW,aAAU,IAAO,aAAU,QAAK,GAAG,KAA2B;CAC9F,OAAO,EAAU;EACf,gBAAgB;EACX;EACL,QAAQ,IAAW,EAAM,SAAS,KAAK,CAAQ,IAA2B,KAAA;EAC1E,OAAO;GACL,aAAa;GACb,WAAW,EACT,uGACA,gFACA,CACF;GACA,GAAI,IAAU,CAAC,IAAI,EAAE,YAAS;GAC9B,GAAG;EACL;CACF,CAAC;AACH;AAaA,SAAS,EAAW,EAAE,cAAW,GAAG,KAAqC;CACvE,OAME,kBAAC,MAAD;EACE,MAAK;EACL,aAAU;EACV,WAAW,EAAG,mDAAmD,CAAS;EAC1E,GAAI;CACL,CAAA;AAEL;AAGA,SAAS,EAAW,EAAE,cAAW,GAAG,KAAqC;CACvE,OAAO,kBAAC,MAAD;EAAI,aAAU;EAAe,WAAW,EAAG,YAAY,CAAS;EAAG,GAAI;CAAQ,CAAA;AACxF;AA8BA,SAAS,EAAW,EAClB,cACA,aAAU,IACV,YAAS,IACT,aAAU,QACV,aACA,QACA,GAAG,KACe;CAClB,OAAO,EAAU;EACf,gBAAgB;EACX;EACL,QAAQ,IAAW,EAAM,SAAS,KAAK,CAAQ,IAA2B,KAAA;EAC1E,OAAO;GACL,aAAa;GAGb,eAAe,IAAS,KAAK,KAAA;GAC7B,gBAAgB,IAAS,IAAU,KAAA;GACnC,WAAW,EAAG,GAAa,IAAS,IAAqB,GAAqB,CAAS;GACvF,GAAI,IAAU,CAAC,IAAI,EAAE,YAAS;GAC9B,GAAG;EACL;CACF,CAAC;AACH;AAqCA,SAAS,EAAkB,EAAE,cAAW,YAAS,IAAO,aAAU,UAAO,UAAU,GAAG,KAAiC;CACrH,OACE,kBAAC,UAAD;EACQ;EACN,aAAU;EACV,eAAa,IAAS,KAAK,KAAA;EAC3B,WAAW,EACT,GACA,IAAS,IAAqB,GAC9B,8BACA,CACF;EACA,GAAI;EAVN,UAAA,CAYG,GASD,kBAAC,GAAD;GACE,eAAY;GACZ,WAAU;EACX,CAAA,CACK;;AAEZ;AAeA,SAAS,EAAc,EAAE,cAAW,GAAG,KAAsC;CAC3E,OACE,kBAAC,OAAD;EAAK,aAAU;EAAkB,WAAW,EAAG,4CAA4C,CAAS;EAAG,GAAI;CAAQ,CAAA;AAEvH"}