@instruments/materia-ui 0.1.0

package/dist/compositions/page-header/page-header-root.d.ts

@@ -0,0 +1,74 @@
+import type React from "react";
+import type { PageHeaderSlotProps } from "./page-header-slots.js";
+type PageHeaderProps = Omit<React.ComponentProps<"header">, "title"> & Partial<PageHeaderSlotProps> & {
+    /** Apply the shared page gutter. Set false when an enclosing shell owns it. */
+    gutter?: boolean;
+    /** When true, the header sticks to the top of the viewport when scrolling. */
+    sticky?: boolean;
+    /**
+     * Layout mode - "single" for one responsive title/actions composition,
+     * "stacked" for multiple explicit rows using `PageHeaderRow`.
+     */
+    layout?: "single" | "stacked";
+};
+/**
+ * Canonical page header - the top of a page, beneath the app's own header.
+ * Pass its parts and it lays them out: a breadcrumb or back link, the title
+ * with optional media, a count or badge and a subtitle, the page's actions,
+ * and a switcher beneath between views of what the page shows. Every part
+ * but the title is optional, and a row with nothing in it is not rendered.
+ * It says what the page is; the controls that narrow or order a list sit in
+ * a `PageToolbar` beneath it.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   actions={<Button icon={Download}>Export</Button>}
+ *   breadcrumb={<Breadcrumb>…</Breadcrumb>}
+ *   nav={<TabNavigation variant="pill">…</TabNavigation>}
+ *   subtitle="24 materials"
+ *   title="Harbour Street lobby"
+ * />
+ * ```
+ *
+ * Without `title` it lays out its children instead, composed from
+ * `PageHeaderLead`, `PageHeaderTitle`, `PageHeaderTabs`, `PageHeaderActions`
+ * and (for multi-row layouts) `PageHeaderRow`.
+ *
+ * For single-row layouts (default):
+ * @example
+ * ```tsx
+ * <PageHeader>
+ *   <PageHeaderLead>
+ *     <PageHeaderTitle>Saves</PageHeaderTitle>
+ *   </PageHeaderLead>
+ *   <PageHeaderActions>
+ *     <ViewToggle />
+ *   </PageHeaderActions>
+ * </PageHeader>
+ * ```
+ *
+ * For multi-row layouts:
+ * @example
+ * ```tsx
+ * <PageHeader layout="stacked">
+ *   <PageHeaderRow>
+ *     <PageHeaderTitle>Brands</PageHeaderTitle>
+ *     <PageHeaderActions><SearchInput /></PageHeaderActions>
+ *   </PageHeaderRow>
+ *   <PageHeaderRow>
+ *     <PageHeaderTabs><ViewToggle /></PageHeaderTabs>
+ *     <PageHeaderActions><FilterPills /></PageHeaderActions>
+ *   </PageHeaderRow>
+ * </PageHeader>
+ * ```
+ *
+ * @bestPractice Pass `title` and the parts the page has rather than composing rows by hand; the header owns wrapping, truncation and spacing, so every page reads the same.
+ * @bestPractice A count belongs in `meta` or `subtitle`, never in the title text; a back link belongs in `breadcrumb`, never in `actions`.
+ * @bestPractice `nav` switches between views of the thing the page shows (a pill `TabNavigation` of routes). Type switchers, filters, sort and view belong in a `PageToolbar`, each once.
+ * @bestPractice Set `layout="stacked"` and wrap each row in `PageHeaderRow` for multi-row headers; the default `"single"` wraps only when a narrow viewport needs to protect the title or actions.
+ * @bestPractice `PageHeader` is the sub-header below the app `HeaderBar`, not the app chrome itself - use `SidebarProvider` with `SidebarInset` or `HeaderBar` for the top-level frame; its `sticky` offset assumes that header is present.
+ * @category headers
+ */
+export declare const PageHeader: ({ actions, breadcrumb, children, className, gutter, layout, level, media, meta, nav, size, sticky, subtitle, title, ...props }: PageHeaderProps) => React.JSX.Element;
+export {};

package/dist/compositions/page-header/page-header-root.js

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { PageHeaderProvider } from "./page-header-context.js";
+import { PageHeaderSlots } from "./page-header-slots.js";
+/**
+ * Canonical page header - the top of a page, beneath the app's own header.
+ * Pass its parts and it lays them out: a breadcrumb or back link, the title
+ * with optional media, a count or badge and a subtitle, the page's actions,
+ * and a switcher beneath between views of what the page shows. Every part
+ * but the title is optional, and a row with nothing in it is not rendered.
+ * It says what the page is; the controls that narrow or order a list sit in
+ * a `PageToolbar` beneath it.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   actions={<Button icon={Download}>Export</Button>}
+ *   breadcrumb={<Breadcrumb>…</Breadcrumb>}
+ *   nav={<TabNavigation variant="pill">…</TabNavigation>}
+ *   subtitle="24 materials"
+ *   title="Harbour Street lobby"
+ * />
+ * ```
+ *
+ * Without `title` it lays out its children instead, composed from
+ * `PageHeaderLead`, `PageHeaderTitle`, `PageHeaderTabs`, `PageHeaderActions`
+ * and (for multi-row layouts) `PageHeaderRow`.
+ *
+ * For single-row layouts (default):
+ * @example
+ * ```tsx
+ * <PageHeader>
+ *   <PageHeaderLead>
+ *     <PageHeaderTitle>Saves</PageHeaderTitle>
+ *   </PageHeaderLead>
+ *   <PageHeaderActions>
+ *     <ViewToggle />
+ *   </PageHeaderActions>
+ * </PageHeader>
+ * ```
+ *
+ * For multi-row layouts:
+ * @example
+ * ```tsx
+ * <PageHeader layout="stacked">
+ *   <PageHeaderRow>
+ *     <PageHeaderTitle>Brands</PageHeaderTitle>
+ *     <PageHeaderActions><SearchInput /></PageHeaderActions>
+ *   </PageHeaderRow>
+ *   <PageHeaderRow>
+ *     <PageHeaderTabs><ViewToggle /></PageHeaderTabs>
+ *     <PageHeaderActions><FilterPills /></PageHeaderActions>
+ *   </PageHeaderRow>
+ * </PageHeader>
+ * ```
+ *
+ * @bestPractice Pass `title` and the parts the page has rather than composing rows by hand; the header owns wrapping, truncation and spacing, so every page reads the same.
+ * @bestPractice A count belongs in `meta` or `subtitle`, never in the title text; a back link belongs in `breadcrumb`, never in `actions`.
+ * @bestPractice `nav` switches between views of the thing the page shows (a pill `TabNavigation` of routes). Type switchers, filters, sort and view belong in a `PageToolbar`, each once.
+ * @bestPractice Set `layout="stacked"` and wrap each row in `PageHeaderRow` for multi-row headers; the default `"single"` wraps only when a narrow viewport needs to protect the title or actions.
+ * @bestPractice `PageHeader` is the sub-header below the app `HeaderBar`, not the app chrome itself - use `SidebarProvider` with `SidebarInset` or `HeaderBar` for the top-level frame; its `sticky` offset assumes that header is present.
+ * @category headers
+ */
+export const PageHeader = ({ actions, breadcrumb, children, className, gutter = true, layout = "single", level, media, meta, nav, size, sticky = false, subtitle, title, ...props }) => {
+    const slotted = title !== undefined;
+    const isStacked = layout === "stacked";
+    return (_jsx(PageHeaderProvider, { sticky: sticky, children: _jsx("header", { className: cn("overflow-x-clip", gutter && "px-page-gutter", slotted && "flex min-w-0 flex-col gap-5 py-4", !slotted && isStacked && "flex flex-col gap-6", !slotted &&
+                !isStacked &&
+                "flex min-h-16 min-w-0 flex-wrap items-center justify-between gap-x-6 gap-y-3 py-3 sm:flex-nowrap", 
+            // The mobile offset is the fixed app bar's height: 3.5rem of bar plus
+            // the top safe-area inset it grows by on notched devices - so the
+            // sticky header butts the bar with no see-through gap.
+            sticky && "bg-muted lg:top-header top-app-bar sticky z-40", className), "data-component": "page-header", "data-slot": "page-header", ...props, children: slotted ? (_jsx(PageHeaderSlots, { actions: actions, breadcrumb: breadcrumb, level: level, media: media, meta: meta, nav: nav, size: size, subtitle: subtitle, title: title })) : (children) }) }));
+};

package/dist/compositions/page-header/page-header-row.d.ts

@@ -0,0 +1,22 @@
+import type React from "react";
+type PageHeaderRowProps = React.ComponentProps<"div">;
+/**
+ * Row container for multi-row `PageHeader` layouts (`layout="stacked"`).
+ * Use when you need to stack multiple rows of content.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader layout="stacked">
+ *   <PageHeaderRow>
+ *     <PageHeaderTitle>Brands</PageHeaderTitle>
+ *     <PageHeaderActions><SearchInput /></PageHeaderActions>
+ *   </PageHeaderRow>
+ *   <PageHeaderRow>
+ *     <PageHeaderTabs><ViewToggle /></PageHeaderTabs>
+ *     <PageHeaderActions><FilterButton /></PageHeaderActions>
+ *   </PageHeaderRow>
+ * </PageHeader>
+ * ```
+ */
+export declare const PageHeaderRow: ({ children, className, ...props }: PageHeaderRowProps) => React.JSX.Element;
+export {};

package/dist/compositions/page-header/page-header-row.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../../components/flex.js";
+/**
+ * Row container for multi-row `PageHeader` layouts (`layout="stacked"`).
+ * Use when you need to stack multiple rows of content.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader layout="stacked">
+ *   <PageHeaderRow>
+ *     <PageHeaderTitle>Brands</PageHeaderTitle>
+ *     <PageHeaderActions><SearchInput /></PageHeaderActions>
+ *   </PageHeaderRow>
+ *   <PageHeaderRow>
+ *     <PageHeaderTabs><ViewToggle /></PageHeaderTabs>
+ *     <PageHeaderActions><FilterButton /></PageHeaderActions>
+ *   </PageHeaderRow>
+ * </PageHeader>
+ * ```
+ */
+export const PageHeaderRow = ({ children, className, ...props }) => (_jsx(Flex, { align: "center", className: cn(
+    // A floor, not a fixed height: a lead that stacks a breadcrumb over the
+    // title is taller than one control row and must not be clipped. Below
+    // `sm` the row wraps, so actions that do not fit beside the title drop
+    // under it.
+    "min-h-16 min-w-0 flex-wrap sm:flex-nowrap", className), "data-component": "page-header-row", "data-slot": "page-header-row", gap: "base", justify: "space-between", ...props, children: children }));

package/dist/compositions/page-header/page-header-slots.d.ts

@@ -0,0 +1,30 @@
+import type React from "react";
+import type { HeadingSize } from "../../components/heading/heading-root.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+/** The parts of a page header, each optional except the title. */
+export interface PageHeaderSlotProps {
+    /** Actions on the title's row, such as a primary button and a menu. They share the title's row; on a phone the title wraps first, and actions too wide to fit drop beneath it. */
+    actions?: React.ReactNode;
+    /** Where the page sits, above the title: a `Breadcrumb`, or a back link. Leave the current page out; the title names it. */
+    breadcrumb?: React.ReactNode;
+    /** Heading level of the title. @default "1" */
+    level?: "1" | "2" | "3" | "4" | "5" | "6" | undefined;
+    /** An image beside the title, such as an `Avatar` or a brand's logo. */
+    media?: React.ReactNode;
+    /** A count or badge on the title's baseline, such as "1,240 products". */
+    meta?: React.ReactNode;
+    /** A switcher between views of what the page shows, beneath the title, such as a pill `TabNavigation` of routes. Controls that narrow or order a list belong in a `PageToolbar`. */
+    nav?: React.ReactNode;
+    /** Title type role, or a role per breakpoint. @default "heading-sm" */
+    size?: ResponsiveValue<HeadingSize> | undefined;
+    /** One line under the title: a count, a date, or who it belongs to. */
+    subtitle?: React.ReactNode;
+    /** The page's name. A string, or a node such as a link. */
+    title: React.ReactNode;
+}
+/**
+ * The header laid out from its parts: the breadcrumb over the title row, the
+ * title row holding the media, title and actions, and the views switcher
+ * beneath. Each row renders only when it has something in it.
+ */
+export declare const PageHeaderSlots: ({ actions, breadcrumb, level, media, meta, nav, size, subtitle, title, }: PageHeaderSlotProps) => React.JSX.Element;

package/dist/compositions/page-header/page-header-slots.js

@@ -0,0 +1,12 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "../../components/flex.js";
+import { PageHeaderActions } from "./page-header-actions.js";
+import { PageHeaderTitle } from "./page-header-title.js";
+const present = (node) => node !== undefined && node !== null && node !== false;
+/**
+ * The header laid out from its parts: the breadcrumb over the title row, the
+ * title row holding the media, title and actions, and the views switcher
+ * beneath. Each row renders only when it has something in it.
+ */
+export const PageHeaderSlots = ({ actions, breadcrumb, level, media, meta, nav, size, subtitle, title, }) => (_jsxs(_Fragment, { children: [_jsxs(Flex, { className: "min-w-0", direction: "column", gap: "xs", children: [present(breadcrumb) ? (_jsx("div", { className: "min-w-0", "data-slot": "page-header-breadcrumb", children: breadcrumb })) : null, _jsxs(Flex, { align: "center", className: "min-w-0 gap-x-6 gap-y-3 sm:flex-nowrap", justify: "space-between", wrap: "wrap", children: [_jsxs(Flex, { align: "center", className: "flex-1 sm:min-w-0", gap: "base", children: [present(media) ? (_jsx("div", { className: "shrink-0", "data-slot": "page-header-media", children: media })) : null, _jsx(PageHeaderTitle, { className: "flex-1", level: level, meta: meta, size: size, subtitle: subtitle, children: title })] }), present(actions) ? (_jsx(PageHeaderActions, { children: actions })) : null] })] }), present(nav) ? (_jsx("div", { className: "min-w-0", "data-slot": "page-header-nav", children: nav })) : null] }));

package/dist/compositions/page-header/page-header-tabs.d.ts

@@ -0,0 +1,16 @@
+import type React from "react";
+type PageHeaderTabsProps = React.ComponentProps<"div">;
+/**
+ * Tabs slot for `PageHeader`. Renders in the center area.
+ * Accepts any children (tab buttons, pill navigation, etc.).
+ *
+ * @example
+ * ```tsx
+ * <PageHeaderTabs>
+ *   <TabButton active>All Saves</TabButton>
+ *   <TabButton>My Folders</TabButton>
+ * </PageHeaderTabs>
+ * ```
+ */
+export declare const PageHeaderTabs: ({ children, className, ...props }: PageHeaderTabsProps) => React.JSX.Element;
+export {};

package/dist/compositions/page-header/page-header-tabs.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../../components/flex.js";
+/**
+ * Tabs slot for `PageHeader`. Renders in the center area.
+ * Accepts any children (tab buttons, pill navigation, etc.).
+ *
+ * @example
+ * ```tsx
+ * <PageHeaderTabs>
+ *   <TabButton active>All Saves</TabButton>
+ *   <TabButton>My Folders</TabButton>
+ * </PageHeaderTabs>
+ * ```
+ */
+export const PageHeaderTabs = ({ children, className, ...props }) => (_jsx(Flex, { align: "center", className: cn("min-w-0", className), "data-component": "page-header-tabs", "data-slot": "page-header-tabs", gap: "xs", ...props, children: children }));

package/dist/compositions/page-header/page-header-title.d.ts

@@ -0,0 +1,44 @@
+import type React from "react";
+import type { HeadingSize } from "../../components/heading/heading-root.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+type HeadingLevel = "1" | "2" | "3" | "4" | "5" | "6";
+/**
+ * Event handlers that conflict between HTML div and motion's HTMLMotionProps
+ * (motion replaces drag/animation events with its own pan/gesture versions).
+ * Dropped from the forwarded-prop surface so both branches share one prop shape.
+ */
+type MotionIncompatibleProps = "onAnimationEnd" | "onAnimationIteration" | "onAnimationStart" | "onDrag" | "onDragEnd" | "onDragEnter" | "onDragExit" | "onDragLeave" | "onDragOver" | "onDragStart" | "onDrop";
+type PageHeaderTitleProps = Omit<React.ComponentProps<"div">, "children" | "title" | MotionIncompatibleProps> & {
+    /** Title content - a string or custom React nodes. */
+    children: React.ReactNode;
+    /**
+     * When true, the heading fades out and collapses as the page scrolls past it
+     * - useful for standalone page titles beneath a fixed app header. Defaults to
+     * false.
+     */
+    collapseOnScroll?: boolean;
+    /** Distance in px the page must scroll before the heading fully collapses. */
+    collapseOnScrollDistance?: number;
+    /** Heading level for semantic HTML (h1-h6). Defaults to "1". */
+    level?: HeadingLevel | undefined;
+    /** Optional inline metadata rendered beside the heading, such as a count. */
+    meta?: React.ReactNode;
+    /** Type role of the title - a single role or a responsive object. Defaults to "heading-sm". */
+    size?: ResponsiveValue<HeadingSize> | undefined;
+    /** Optional subtitle text displayed below the title. */
+    subtitle?: React.ReactNode;
+};
+/**
+ * Title slot for `PageHeader`. Renders the primary heading (left side in a
+ * single-row layout) with an optional inline `meta` badge, an optional
+ * `subtitle`, and optional scroll-linked fade/collapse.
+ *
+ * @example
+ * ```tsx
+ * <PageHeaderTitle>Saves</PageHeaderTitle>
+ * <PageHeaderTitle level="1" size="heading" subtitle="32 items">Dashboard</PageHeaderTitle>
+ * <PageHeaderTitle collapseOnScroll size="heading">Brands</PageHeaderTitle>
+ * ```
+ */
+export declare const PageHeaderTitle: ({ children, className, collapseOnScroll, collapseOnScrollDistance, level, meta, size, subtitle, ...props }: PageHeaderTitleProps) => React.JSX.Element;
+export {};

package/dist/compositions/page-header/page-header-title.js

@@ -0,0 +1,60 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useScroll, useTransform } from "motion/react";
+import * as m from "motion/react-m";
+import { Flex } from "../../components/flex.js";
+import { Heading } from "../../components/heading/heading-root.js";
+import { Text } from "../../components/text/text-root.js";
+import { isResponsiveValue } from "../../tokens/responsive.js";
+import { asMotionStyle } from "../../utils/motion-style.js";
+/** Line-height in px for each `size`, sourced from Heading's `SIZE_CLASSES`. */
+const HEADING_LINE_HEIGHT_PX = {
+    "paragraph-sm": 20,
+    "paragraph-lg": 24,
+    subheading: 28,
+    "subheading-lg": 32,
+    "heading-sm": 36,
+    heading: 44,
+    "heading-lg": 56,
+    title: 72,
+};
+/** Bottom padding contributes to the scroll-collapse height. Matches `pb-6`. */
+const BOTTOM_PADDING_PX = 24;
+/** Shared inner content: heading + optional inline meta + optional subtitle. */
+const TitleContent = ({ children, level, meta, size, subtitle, }) => (_jsxs(_Fragment, { children: [_jsxs(Flex, { align: "flex-end", className: "gap-x-3 gap-y-1.5", wrap: "wrap", children: [_jsx(Heading, { className: "min-w-0 basis-full text-pretty sm:basis-auto sm:truncate", level: level, size: size, children: children }), meta !== undefined && meta !== null ? (_jsx("div", { className: "shrink-0 pb-0.5", children: meta })) : null] }), subtitle !== undefined && subtitle !== null ? (_jsx(Text, { className: "text-foreground/70 mt-1 line-clamp-2 sm:truncate", variant: "muted", children: subtitle })) : null] }));
+/** Split out so `useScroll` is only called on the collapsing branch. */
+const CollapsingTitle = ({ children, className, collapseOnScrollDistance, level, meta, size, style, subtitle, ...divProps }) => {
+    const staticSize = isResponsiveValue(size)
+        ? (size.base ?? "heading-sm")
+        : size;
+    const totalHeightPx = HEADING_LINE_HEIGHT_PX[staticSize] + BOTTOM_PADDING_PX;
+    const { scrollY } = useScroll();
+    const opacity = useTransform(scrollY, [0, collapseOnScrollDistance], [1, 0]);
+    const height = useTransform(scrollY, [0, collapseOnScrollDistance], [totalHeightPx, 0]);
+    const motionStyle = asMotionStyle({
+        height,
+        opacity,
+        overflow: "hidden",
+        ...style,
+    });
+    return (_jsx(m.div, { className: cn("min-w-0 shrink pb-6", className), "data-component": "page-header-title", "data-slot": "page-header-title", style: motionStyle, ...divProps, children: _jsx(TitleContent, { level: level, meta: meta, size: size, subtitle: subtitle, children: children }) }));
+};
+/**
+ * Title slot for `PageHeader`. Renders the primary heading (left side in a
+ * single-row layout) with an optional inline `meta` badge, an optional
+ * `subtitle`, and optional scroll-linked fade/collapse.
+ *
+ * @example
+ * ```tsx
+ * <PageHeaderTitle>Saves</PageHeaderTitle>
+ * <PageHeaderTitle level="1" size="heading" subtitle="32 items">Dashboard</PageHeaderTitle>
+ * <PageHeaderTitle collapseOnScroll size="heading">Brands</PageHeaderTitle>
+ * ```
+ */
+export const PageHeaderTitle = ({ children, className, collapseOnScroll = false, collapseOnScrollDistance = 28, level = "1", meta, size = "heading-sm", subtitle, ...props }) => {
+    if (collapseOnScroll) {
+        return (_jsx(CollapsingTitle, { className: className, collapseOnScrollDistance: collapseOnScrollDistance, level: level, meta: meta, size: size, subtitle: subtitle, ...props, children: children }));
+    }
+    return (_jsx("div", { className: cn("min-w-0 shrink", className), "data-component": "page-header-title", "data-slot": "page-header-title", ...props, children: _jsx(TitleContent, { level: level, meta: meta, size: size, subtitle: subtitle, children: children }) }));
+};

package/dist/compositions/page-header.d.ts

@@ -0,0 +1,8 @@
+export { PageHeaderActions } from "./page-header/page-header-actions.js";
+export { usePageHeader } from "./page-header/page-header-context.js";
+export { PageHeaderLead } from "./page-header/page-header-lead.js";
+export { PageHeader } from "./page-header/page-header-root.js";
+export type { PageHeaderSlotProps } from "./page-header/page-header-slots.js";
+export { PageHeaderRow } from "./page-header/page-header-row.js";
+export { PageHeaderTabs } from "./page-header/page-header-tabs.js";
+export { PageHeaderTitle } from "./page-header/page-header-title.js";

package/dist/compositions/page-header.js

@@ -0,0 +1,8 @@
+"use client";
+export { PageHeaderActions } from "./page-header/page-header-actions.js";
+export { usePageHeader } from "./page-header/page-header-context.js";
+export { PageHeaderLead } from "./page-header/page-header-lead.js";
+export { PageHeader } from "./page-header/page-header-root.js";
+export { PageHeaderRow } from "./page-header/page-header-row.js";
+export { PageHeaderTabs } from "./page-header/page-header-tabs.js";
+export { PageHeaderTitle } from "./page-header/page-header-title.js";

package/dist/compositions/page-toolbar/page-toolbar-applied.d.ts

@@ -0,0 +1,45 @@
+import { Button } from "@instruments/materia-ui/components/button";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import type { ComponentProps, ReactNode } from "react";
+export interface PageToolbarFiltersButtonProps extends Omit<ComponentProps<typeof Button>, "children" | "emphasis" | "icon" | "tone"> {
+    /** How many filters are applied, shown muted after the label. */
+    count?: number;
+    /** @default "Filters" */
+    children?: ReactNode;
+}
+/**
+ * The button that opens the full set of filters. It leads the toolbar and
+ * says how many filters are applied, so the count is in view even when the
+ * chips have scrolled away.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export declare const PageToolbarFiltersButton: ({ children, className, count, ...props }: PageToolbarFiltersButtonProps) => import("react").JSX.Element;
+export interface PageToolbarAppliedProps extends ComponentProps<typeof Flex> {
+    /** The applied filters, each a pressed `PageToolbarFilter`. */
+    children?: ReactNode;
+    /** Removes every applied filter. */
+    onClear: () => void;
+    /** @default "Clear all" */
+    clearLabel?: string;
+    /**
+     * Draw a short rule after the group, before the suggestions that follow.
+     * Set false when nothing follows. @default true
+     */
+    separator?: boolean;
+}
+/**
+ * The filters in force, straight after the Filters button: each one pressed
+ * with a cross to remove it, then Clear all. It renders nothing while no
+ * filter is applied, so the suggestions move up into its place.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbarApplied onClear={clear}>
+ *   {applied.map((name) => (
+ *     <PageToolbarFilter key={name} onPressedChange={() => remove(name)} pressed>
+ *       {name}
+ *     </PageToolbarFilter>
+ *   ))}
+ * </PageToolbarApplied>
+ */
+export declare const PageToolbarApplied: ({ children, className, clearLabel, onClear, separator, ...props }: PageToolbarAppliedProps) => import("react").JSX.Element | null;

package/dist/compositions/page-toolbar/page-toolbar-applied.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Separator } from "@instruments/materia-ui/components/separator";
+import { SlidersHorizontal } from "@instruments/materia-ui/icons";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * The button that opens the full set of filters. It leads the toolbar and
+ * says how many filters are applied, so the count is in view even when the
+ * chips have scrolled away.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export const PageToolbarFiltersButton = ({ children = "Filters", className, count, ...props }) => (_jsxs(Button, { className: cn("shrink-0", className), "data-component": "page-toolbar-filters-button", "data-slot": "page-toolbar-filters-button", emphasis: "outline", icon: SlidersHorizontal, tone: "neutral", ...props, children: [children, count === undefined || count === 0 ? null : (_jsx("span", { className: "text-muted-foreground tabular-nums", children: count }))] }));
+/** Nothing to show: no children, or an empty list mapped from no filters. */
+const isEmpty = (children) => children === undefined ||
+    children === null ||
+    children === false ||
+    (Array.isArray(children) && children.length === 0);
+/**
+ * The filters in force, straight after the Filters button: each one pressed
+ * with a cross to remove it, then Clear all. It renders nothing while no
+ * filter is applied, so the suggestions move up into its place.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbarApplied onClear={clear}>
+ *   {applied.map((name) => (
+ *     <PageToolbarFilter key={name} onPressedChange={() => remove(name)} pressed>
+ *       {name}
+ *     </PageToolbarFilter>
+ *   ))}
+ * </PageToolbarApplied>
+ */
+export const PageToolbarApplied = ({ children, className, clearLabel = "Clear all", onClear, separator = true, ...props }) => {
+    if (isEmpty(children)) {
+        return null;
+    }
+    return (_jsxs(Flex, { align: "center", className: cn("shrink-0", className), "data-component": "page-toolbar-applied", "data-slot": "page-toolbar-applied", gap: "xs", ...props, children: [children, _jsx(Button, { className: "shrink-0", emphasis: "ghost", onClick: onClear, tone: "neutral", children: clearLabel }), separator ? (_jsx(Box, { className: "mx-1 h-5 shrink-0", children: _jsx(Separator, { orientation: "vertical" }) })) : null] }));
+};

package/dist/compositions/page-toolbar/page-toolbar-filter.d.ts

@@ -0,0 +1,15 @@
+import { Toggle } from "@instruments/materia-ui/components/toggle";
+import type { ComponentProps, ReactNode } from "react";
+export interface PageToolbarFilterProps extends Omit<ComponentProps<typeof Toggle>, "children" | "icon" | "iconPlacement" | "radius"> {
+    /** The filter's name. */
+    children: ReactNode;
+    /** How many results it would leave, shown muted after the name. */
+    count?: number;
+}
+/**
+ * A quick filter: a pill that is on or off. When on, it shows a cross, so it
+ * reads as applied and as the way to remove it. Control it with `pressed` and
+ * `onPressedChange`, or leave it to track itself with `defaultPressed`.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export declare const PageToolbarFilter: ({ children, className, count, ...props }: PageToolbarFilterProps) => import("react").JSX.Element;

package/dist/compositions/page-toolbar/page-toolbar-filter.js

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Toggle } from "@instruments/materia-ui/components/toggle";
+import { X } from "@instruments/materia-ui/icons";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * A quick filter: a pill that is on or off. When on, it shows a cross, so it
+ * reads as applied and as the way to remove it. Control it with `pressed` and
+ * `onPressedChange`, or leave it to track itself with `defaultPressed`.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export const PageToolbarFilter = ({ children, className, count, ...props }) => (_jsxs(Toggle, { className: cn("group/filter shrink-0", className), "data-component": "page-toolbar-filter", "data-slot": "page-toolbar-filter", radius: "full", ...props, children: [children, count === undefined ? null : (_jsx("span", { className: "text-muted-foreground tabular-nums", children: count })), _jsx(X, { "aria-hidden": true, className: "hidden group-data-pressed/filter:block" })] }));

package/dist/compositions/page-toolbar/page-toolbar-root.d.ts

@@ -0,0 +1,64 @@
+import { Flex } from "@instruments/materia-ui/components/flex";
+import type { ComponentProps, ReactNode } from "react";
+export interface PageToolbarProps extends ComponentProps<typeof Flex> {
+    /** Names the toolbar's region, such as "Filters". */
+    "aria-label": string;
+    /**
+     * Reach across the page gutter, so the bar's fill and rule meet the column's
+     * edges and nothing shows past it as the page scrolls beneath. Set false
+     * when the column it sits in has no gutter. @default true
+     */
+    gutter?: boolean;
+}
+/**
+ * A page's filter and view bar. It sits beneath the page header and holds to
+ * the top of the window, under the app's header, while the page scrolls: the
+ * filters on one side, scrolling sideways when there are more than fit, and
+ * the sort and view controls on the other. At rest it reads as part of the
+ * page; once it is holding, a hairline separates it from the content passing
+ * beneath.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbar aria-label="Filters">
+ *   <PageToolbarFilters button={<PageToolbarFiltersButton count={applied.length} />}>
+ *     <PageToolbarApplied onClear={clear}>
+ *       <PageToolbarFilter pressed>Tile</PageToolbarFilter>
+ *     </PageToolbarApplied>
+ *     <PageToolbarFilter count={31}>Stone</PageToolbarFilter>
+ *   </PageToolbarFilters>
+ *   <PageToolbarActions>
+ *     <PageToolbarSort onValueChange={setSort} options={SORTS} value={sort} />
+ *   </PageToolbarActions>
+ * </PageToolbar>
+ *
+ * @bestPractice Place it straight after the `PageHeader`, in the column that holds the page's content; the title scrolls away and the toolbar stays.
+ * @bestPractice Order the leading side the same on every page: `PageToolbarFiltersButton` first, in the `button` slot so it holds still carrying the applied count; then `PageToolbarApplied`, the filters in force with Clear all; then the suggestions.
+ * @bestPractice Applied filters always lead, so they never scroll out of view behind suggestions. Pressing a suggestion moves it into the applied group; it is never shown twice.
+ * @bestPractice When a filter rail holds the facets, the toolbar still shows what the rail has applied, with no suggestions after it (`separator={false}`).
+ * @bestPractice Each facet appears once. A `SegmentedControl` when the facet splits the set and one part is viewed at a time (its counts sum to the total); `PageToolbarFilter` chips when several combine. Never both for the same facet.
+ * @bestPractice Keep the actions to `PageToolbarSort`, which names the current order, and a view toggle. Page actions such as export belong in the `PageHeader`.
+ * @category navigation
+ */
+export declare const PageToolbar: ({ "aria-label": ariaLabel, children, className, gutter, ...props }: PageToolbarProps) => import("react").JSX.Element;
+export interface PageToolbarFiltersProps extends ComponentProps<typeof Flex> {
+    /**
+     * The `PageToolbarFiltersButton`. It holds still while the filters after it
+     * scroll, so its applied count stays in view.
+     */
+    button?: ReactNode;
+}
+/**
+ * The toolbar's leading side: the Filters button, then the applied filters
+ * and suggestions. When those outgrow the bar they scroll sideways beside
+ * the button, with a fade at whichever edge has more to show.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export declare const PageToolbarFilters: ({ button, children, className, ...props }: PageToolbarFiltersProps) => import("react").JSX.Element;
+export type PageToolbarActionsProps = ComponentProps<typeof Flex>;
+/**
+ * The toolbar's trailing side: sort and a view toggle. It never scrolls or
+ * shrinks.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export declare const PageToolbarActions: ({ className, ...props }: PageToolbarActionsProps) => import("react").JSX.Element;