@instruments/materia-ui 0.1.0

package/dist/compositions/prompt-panel/use-prompt-panel-keyboard.d.ts

@@ -0,0 +1,41 @@
+import type { KeyboardEvent } from "react";
+export interface UsePromptPanelKeyboardOptions {
+    /** Called when Backspace is pressed on an empty input - navigate back a step. */
+    onBack?: (() => void) | undefined;
+    /** Called when Escape is pressed. */
+    onEscape?: (() => void) | undefined;
+    /** Called with the zero-based option index when a digit 1–9 is pressed on an empty input. */
+    onSelectOption: (index: number) => void;
+    /** Called with the current value when Enter is pressed on a non-empty input. */
+    onSubmit: (value: string) => void;
+    /** Total number of selectable options; digits beyond this count are ignored. */
+    optionCount: number;
+}
+export interface UsePromptPanelKeyboardResult {
+    /** Attach to the freeform input's `onKeyDown` (e.g. `PromptPanelFreeform`'s `onKeyDown` prop). */
+    onKeyDown: (event: KeyboardEvent<HTMLInputElement>) => void;
+}
+/**
+ * Keyboard contract for a `PromptPanel`'s freeform input: digit keys 1–9
+ * select an option by index (only while the input is empty), Enter submits
+ * the freeform text (only while non-empty), Escape dismisses, and Backspace
+ * on an empty input navigates back a step. Never steals keys mid-sentence -
+ * every branch except Escape is gated on the input's empty state, so once the
+ * user starts typing, digits/Backspace fall through to normal text entry.
+ *
+ * @example
+ * ```tsx
+ * const { onKeyDown } = usePromptPanelKeyboard({
+ *   onBack: goBack,
+ *   onEscape: close,
+ *   onSelectOption: (index) => selectOption(options[index]),
+ *   onSubmit: runFreeform,
+ *   optionCount: options.length,
+ * });
+ *
+ * <PromptPanelFreeform onKeyDown={onKeyDown} />
+ * ```
+ *
+ * @bestPractice Attach the returned `onKeyDown` directly to the panel's freeform input rather than re-implementing this contract - `PromptPanelFreeform` forwards unrecognised props straight to its `<input>`.
+ */
+export declare const usePromptPanelKeyboard: ({ optionCount, onSelectOption, onSubmit, onEscape, onBack, }: UsePromptPanelKeyboardOptions) => UsePromptPanelKeyboardResult;

package/dist/compositions/prompt-panel/use-prompt-panel-keyboard.js

@@ -0,0 +1,55 @@
+import { useCallback } from "react";
+/**
+ * Keyboard contract for a `PromptPanel`'s freeform input: digit keys 1–9
+ * select an option by index (only while the input is empty), Enter submits
+ * the freeform text (only while non-empty), Escape dismisses, and Backspace
+ * on an empty input navigates back a step. Never steals keys mid-sentence -
+ * every branch except Escape is gated on the input's empty state, so once the
+ * user starts typing, digits/Backspace fall through to normal text entry.
+ *
+ * @example
+ * ```tsx
+ * const { onKeyDown } = usePromptPanelKeyboard({
+ *   onBack: goBack,
+ *   onEscape: close,
+ *   onSelectOption: (index) => selectOption(options[index]),
+ *   onSubmit: runFreeform,
+ *   optionCount: options.length,
+ * });
+ *
+ * <PromptPanelFreeform onKeyDown={onKeyDown} />
+ * ```
+ *
+ * @bestPractice Attach the returned `onKeyDown` directly to the panel's freeform input rather than re-implementing this contract - `PromptPanelFreeform` forwards unrecognised props straight to its `<input>`.
+ */
+export const usePromptPanelKeyboard = ({ optionCount, onSelectOption, onSubmit, onEscape, onBack, }) => {
+    const onKeyDown = useCallback((event) => {
+        const { value } = event.currentTarget;
+        const isEmpty = value.length === 0;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            onEscape?.();
+            return;
+        }
+        if (!isEmpty) {
+            if (event.key === "Enter") {
+                event.preventDefault();
+                onSubmit(value);
+            }
+            return;
+        }
+        if (event.key === "Backspace") {
+            event.preventDefault();
+            onBack?.();
+            return;
+        }
+        if (event.key >= "1" && event.key <= "9") {
+            const index = Number(event.key) - 1;
+            if (index < optionCount) {
+                event.preventDefault();
+                onSelectOption(index);
+            }
+        }
+    }, [onBack, onEscape, onSelectOption, onSubmit, optionCount]);
+    return { onKeyDown };
+};

package/dist/compositions/prompt-panel.d.ts

@@ -0,0 +1,17 @@
+export { promptPanelAnatomy } from "./prompt-panel/prompt-panel-anatomy.js";
+export { PromptPanelBody } from "./prompt-panel/prompt-panel-body.js";
+export type { PromptPanelBodyProps } from "./prompt-panel/prompt-panel-body.js";
+export { PromptPanelFreeform } from "./prompt-panel/prompt-panel-freeform.js";
+export type { PromptPanelFreeformProps } from "./prompt-panel/prompt-panel-freeform.js";
+export { PromptPanelHeader } from "./prompt-panel/prompt-panel-header.js";
+export type { PromptPanelHeaderProps } from "./prompt-panel/prompt-panel-header.js";
+export { PromptPanelOption } from "./prompt-panel/prompt-panel-option.js";
+export type { PromptPanelOptionProps } from "./prompt-panel/prompt-panel-option.js";
+export { PromptPanel } from "./prompt-panel/prompt-panel-root.js";
+export type { PromptPanelProps } from "./prompt-panel/prompt-panel-root.js";
+export { PromptPanelStage } from "./prompt-panel/prompt-panel-stage.js";
+export type { PromptPanelStageProps } from "./prompt-panel/prompt-panel-stage.js";
+export { PromptPanelView } from "./prompt-panel/prompt-panel-view.js";
+export type { PromptPanelViewOption, PromptPanelViewProps, } from "./prompt-panel/prompt-panel-view.js";
+export { usePromptPanelKeyboard } from "./prompt-panel/use-prompt-panel-keyboard.js";
+export type { UsePromptPanelKeyboardOptions, UsePromptPanelKeyboardResult, } from "./prompt-panel/use-prompt-panel-keyboard.js";

package/dist/compositions/prompt-panel.js

@@ -0,0 +1,9 @@
+export { promptPanelAnatomy } from "./prompt-panel/prompt-panel-anatomy.js";
+export { PromptPanelBody } from "./prompt-panel/prompt-panel-body.js";
+export { PromptPanelFreeform } from "./prompt-panel/prompt-panel-freeform.js";
+export { PromptPanelHeader } from "./prompt-panel/prompt-panel-header.js";
+export { PromptPanelOption } from "./prompt-panel/prompt-panel-option.js";
+export { PromptPanel } from "./prompt-panel/prompt-panel-root.js";
+export { PromptPanelStage } from "./prompt-panel/prompt-panel-stage.js";
+export { PromptPanelView } from "./prompt-panel/prompt-panel-view.js";
+export { usePromptPanelKeyboard } from "./prompt-panel/use-prompt-panel-keyboard.js";

package/dist/compositions/quick-view/quick-view-body.d.ts

@@ -0,0 +1,15 @@
+import { ScrollArea } from "@instruments/materia-ui/components/scroll-area";
+import type { ComponentProps } from "react";
+export type QuickViewBodyProps = Omit<ComponentProps<typeof ScrollArea>, "as" | "orientation" | "render"> & {
+    /** Names the scrolling region for assistive tech, e.g. "Product details". */
+    "aria-label": string;
+};
+/**
+ * The quick view's scrolling region, on the muted surface so the item's own
+ * cards and imagery stand forward. It takes the height left between the
+ * header and footer, and scrolling stops at its edges rather than moving the
+ * page behind. A named `<section>` holds the scroll area, whose own root is
+ * presentational.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export declare const QuickViewBody: ({ "aria-label": ariaLabel, className, viewportClassName, ...props }: QuickViewBodyProps) => import("react").JSX.Element;

package/dist/compositions/quick-view/quick-view-body.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { ScrollArea } from "@instruments/materia-ui/components/scroll-area";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * The quick view's scrolling region, on the muted surface so the item's own
+ * cards and imagery stand forward. It takes the height left between the
+ * header and footer, and scrolling stops at its edges rather than moving the
+ * page behind. A named `<section>` holds the scroll area, whose own root is
+ * presentational.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export const QuickViewBody = ({ "aria-label": ariaLabel, className, viewportClassName, ...props }) => (_jsx(Box, { "aria-label": ariaLabel, as: "section", className: cn("bg-muted min-h-0 flex-1", className), "data-component": "quick-view-body", "data-slot": "quick-view-body", children: _jsx(ScrollArea, { className: "size-full", viewportClassName: cn("overscroll-contain px-3 pt-3 pb-4 md:pb-6", viewportClassName), ...props }) }));

package/dist/compositions/quick-view/quick-view-content.d.ts

@@ -0,0 +1,16 @@
+import { DialogContent } from "@instruments/materia-ui/components/dialog";
+import type { ComponentProps } from "react";
+export type QuickViewContentProps = Omit<ComponentProps<typeof DialogContent>, "ref" | "showCloseButton" | "size">;
+/**
+ * The quick view's panel: a viewport-size `DialogContent` laid out as a column,
+ * so `QuickViewHeader` and `QuickViewFooter` hold still while `QuickViewBody`
+ * scrolls between them. Renders its own portal and backdrop, and closes
+ * through `QuickViewHeader`'s close button rather than a corner one. Pass
+ * `finalFocus` only to send focus somewhere other than the opener.
+ *
+ * Opened from the keyboard, focus lands on the first control; opened by a
+ * pointer or from application state, the panel itself takes focus, so no focus
+ * ring shows on first paint. Pass `initialFocus` to choose otherwise.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export declare const QuickViewContent: ({ className, finalFocus, initialFocus, ...props }: QuickViewContentProps) => import("react").JSX.Element;

package/dist/compositions/quick-view/quick-view-content.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DialogContent } from "@instruments/materia-ui/components/dialog";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useQuickViewContext } from "./quick-view-context.js";
+/**
+ * The quick view's panel: a viewport-size `DialogContent` laid out as a column,
+ * so `QuickViewHeader` and `QuickViewFooter` hold still while `QuickViewBody`
+ * scrolls between them. Renders its own portal and backdrop, and closes
+ * through `QuickViewHeader`'s close button rather than a corner one. Pass
+ * `finalFocus` only to send focus somewhere other than the opener.
+ *
+ * Opened from the keyboard, focus lands on the first control; opened by a
+ * pointer or from application state, the panel itself takes focus, so no focus
+ * ring shows on first paint. Pass `initialFocus` to choose otherwise.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export const QuickViewContent = ({ className, finalFocus, initialFocus, ...props }) => {
+    const { opener, popup } = useQuickViewContext("QuickViewContent");
+    const pointerSafeInitialFocus = (openType) => openType === "keyboard" ? true : popup.current;
+    return (_jsx(DialogContent, { className: cn(
+        // 32px corner: the header's 40px controls, 12px in, are concentric.
+        "flex flex-col gap-0 overflow-hidden rounded-4xl p-0 outline-none", className), "data-component": "quick-view-content", "data-slot": "quick-view-content", finalFocus: finalFocus ??
+            (() => {
+                const control = opener.current;
+                return control?.isConnected === true ? control : true;
+            }), initialFocus: initialFocus ?? pointerSafeInitialFocus, ref: popup, showCloseButton: false, size: "viewport", ...props }));
+};

package/dist/compositions/quick-view/quick-view-context.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from "react";
+/** What `QuickView` shares with its parts: the element focus returns to. */
+export interface QuickViewContextValue {
+    /** The control that opened the quick view, recorded as it opened. */
+    opener: RefObject<HTMLElement | null>;
+    /** The open panel, so interactions inside it never count as the opener. */
+    popup: RefObject<HTMLDivElement | null>;
+}
+export declare const QuickViewContext: import("react").Context<QuickViewContextValue | null>;
+/** Reads the enclosing `QuickView`; a part rendered outside one is a bug. */
+export declare const useQuickViewContext: (part: string) => QuickViewContextValue;

package/dist/compositions/quick-view/quick-view-context.js

@@ -0,0 +1,11 @@
+"use client";
+import { createContext, useContext } from "react";
+export const QuickViewContext = createContext(null);
+/** Reads the enclosing `QuickView`; a part rendered outside one is a bug. */
+export const useQuickViewContext = (part) => {
+    const context = useContext(QuickViewContext);
+    if (context === null) {
+        throw new Error(`${part} must be rendered inside <QuickView>.`);
+    }
+    return context;
+};

package/dist/compositions/quick-view/quick-view-footer.d.ts

@@ -0,0 +1,12 @@
+import { Flex } from "@instruments/materia-ui/components/flex";
+import type { ComponentProps } from "react";
+export type QuickViewFooterProps = Omit<ComponentProps<typeof Flex>, "as" | "render">;
+/**
+ * The quick view's bottom bar for the item's actions, such as adding a sample.
+ * Actions sit on the trailing edge by default; pass `justify` to move them.
+ * Use `size="lg"` buttons: 40px, 12px in from the 32px corner, like the
+ * header's controls. Optional: an item's own action (add a sample) usually
+ * belongs in its first details card instead.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export declare const QuickViewFooter: ({ className, ...props }: QuickViewFooterProps) => import("react").JSX.Element;

package/dist/compositions/quick-view/quick-view-footer.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * The quick view's bottom bar for the item's actions, such as adding a sample.
+ * Actions sit on the trailing edge by default; pass `justify` to move them.
+ * Use `size="lg"` buttons: 40px, 12px in from the 32px corner, like the
+ * header's controls. Optional: an item's own action (add a sample) usually
+ * belongs in its first details card instead.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export const QuickViewFooter = ({ className, ...props }) => (_jsx(Flex, { align: "center", as: "footer", className: cn("bg-card shrink-0 border-t p-3", className), "data-component": "quick-view-footer", "data-slot": "quick-view-footer", gap: "xs", justify: "flex-end", ...props }));

package/dist/compositions/quick-view/quick-view-header.d.ts

@@ -0,0 +1,24 @@
+import { Flex } from "@instruments/materia-ui/components/flex";
+import type { ComponentProps, ReactNode } from "react";
+export interface QuickViewHeaderProps extends Omit<ComponentProps<typeof Flex>, "as" | "children" | "render"> {
+    /** The item's name: the dialog's accessible name, and its visible title unless `hideTitle`. */
+    children: ReactNode;
+    /** Controls before the close button, such as a link to the full page. Use `size="lg"` buttons so they match the close button. */
+    actions?: ReactNode;
+    /** Accessible name of the close button. @default "Close quick view" */
+    closeLabel?: string;
+    /**
+     * Keep the title for assistive tech only, when the body already shows the
+     * item's name (in its first details card, say). @default false
+     */
+    hideTitle?: boolean;
+    /** Controls on the leading edge, such as back and forward through viewed items. */
+    leading?: ReactNode;
+}
+/**
+ * The quick view's top bar: the item's name as the dialog title, then any
+ * `actions` and a close button on the trailing edge. Its 40px controls sit
+ * 12px in from the panel's 32px corner, so the curves are concentric.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export declare const QuickViewHeader: ({ actions, children, className, closeLabel, hideTitle, leading, ...props }: QuickViewHeaderProps) => import("react").JSX.Element;

package/dist/compositions/quick-view/quick-view-header.js

@@ -0,0 +1,16 @@
+"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 { DialogClose, DialogTitle, } from "@instruments/materia-ui/components/dialog";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { X } from "@instruments/materia-ui/icons";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { OVERLAY_TITLE } from "../../tokens/overlay-styles.js";
+/**
+ * The quick view's top bar: the item's name as the dialog title, then any
+ * `actions` and a close button on the trailing edge. Its 40px controls sit
+ * 12px in from the panel's 32px corner, so the curves are concentric.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export const QuickViewHeader = ({ actions, children, className, closeLabel = "Close quick view", hideTitle = false, leading, ...props }) => (_jsxs(Flex, { align: "center", as: "header", className: cn("bg-card shrink-0 border-b p-3", className), "data-component": "quick-view-header", "data-slot": "quick-view-header", gap: "sm", ...props, children: [leading === undefined ? null : (_jsx(Flex, { align: "center", className: "shrink-0", gap: "xs", children: leading })), _jsx(DialogTitle, { className: cn(hideTitle ? "sr-only" : [OVERLAY_TITLE, "min-w-0 flex-1 truncate ps-3"]), children: children }), hideTitle ? _jsx(Box, { className: "flex-1" }) : null, actions === undefined ? null : (_jsx(Flex, { align: "center", className: "shrink-0", gap: "xs", children: actions })), _jsx(DialogClose, { render: _jsx(Button, { "aria-label": closeLabel, emphasis: "soft", icon: X, radius: "full", size: "icon-lg", tone: "neutral" }) })] }));

package/dist/compositions/quick-view/quick-view-layout.d.ts

@@ -0,0 +1,32 @@
+import { Box } from "@instruments/materia-ui/components/box";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { Stack } from "@instruments/materia-ui/components/stack";
+import type { ComponentProps } from "react";
+export type QuickViewLayoutProps = Omit<ComponentProps<typeof Grid>, "align" | "as" | "columns" | "gap" | "render">;
+export type QuickViewMediaProps = Omit<ComponentProps<typeof Box>, "as" | "render">;
+/**
+ * The quick view's two columns, mirroring a product page: media on the left,
+ * details on the right, from md up; stacked below md. Place a
+ * `QuickViewMedia` and a `QuickViewDetails` inside `QuickViewBody`.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ *
+ * @bestPractice Key the layout by the item's id, so swapping items inside an open quick view remounts its images instead of showing the previous bitmap while the next loads.
+ */
+export declare const QuickViewLayout: (props: QuickViewLayoutProps) => import("react").JSX.Element;
+/**
+ * The media column, clipped to the details cards' 24px corner. From md up it
+ * sticks 12px below the header while the details scroll past, the same gap as
+ * above it before scrolling.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export declare const QuickViewMedia: ({ className, ...props }: QuickViewMediaProps) => import("react").JSX.Element;
+export type QuickViewDetailsProps = Omit<ComponentProps<typeof Stack>, "as" | "gap" | "render">;
+/**
+ * The details column: a stack of flat cards on the body's muted surface.
+ * It is its own container, so cards adapt to the column's width rather than
+ * the dialog's.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ *
+ * @bestPractice Fill it with `Card shadow={false}` sections - the item's name and main action first, then specifications - so they stand forward of the muted body without a shadow each.
+ */
+export declare const QuickViewDetails: ({ className, ...props }: QuickViewDetailsProps) => import("react").JSX.Element;

package/dist/compositions/quick-view/quick-view-layout.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { Stack } from "@instruments/materia-ui/components/stack";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * The quick view's two columns, mirroring a product page: media on the left,
+ * details on the right, from md up; stacked below md. Place a
+ * `QuickViewMedia` and a `QuickViewDetails` inside `QuickViewBody`.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ *
+ * @bestPractice Key the layout by the item's id, so swapping items inside an open quick view remounts its images instead of showing the previous bitmap while the next loads.
+ */
+export const QuickViewLayout = (props) => (_jsx(Grid, { align: { base: "stretch", md: "flex-start" }, columns: { base: 1, md: 2 }, "data-component": "quick-view-layout", "data-slot": "quick-view-layout", gap: { base: "sm", md: "lg" }, ...props }));
+/**
+ * The media column, clipped to the details cards' 24px corner. From md up it
+ * sticks 12px below the header while the details scroll past, the same gap as
+ * above it before scrolling.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ */
+export const QuickViewMedia = ({ className, ...props }) => (_jsx(Box, { className: cn("@container overflow-hidden rounded-3xl md:sticky md:top-3", className), "data-component": "quick-view-media", "data-slot": "quick-view-media", ...props }));
+/**
+ * The details column: a stack of flat cards on the body's muted surface.
+ * It is its own container, so cards adapt to the column's width rather than
+ * the dialog's.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ *
+ * @bestPractice Fill it with `Card shadow={false}` sections - the item's name and main action first, then specifications - so they stand forward of the muted body without a shadow each.
+ */
+export const QuickViewDetails = ({ className, ...props }) => (_jsx(Stack, { className: cn("@container", className), "data-component": "quick-view-details", "data-slot": "quick-view-details", gap: "sm", ...props }));

package/dist/compositions/quick-view/quick-view-root.d.ts

@@ -0,0 +1,37 @@
+import { Dialog } from "@instruments/materia-ui/components/dialog";
+import type { ComponentProps } from "react";
+type DialogRootProps = ComponentProps<typeof Dialog>;
+export type QuickViewProps = Omit<DialogRootProps, "defaultOpen" | "open" | "onOpenChange"> & {
+    /** Whether the quick view is open. The application owns this state. */
+    open: boolean;
+    /** Called when Escape, the backdrop or a close control asks to close it. */
+    onOpenChange: NonNullable<DialogRootProps["onOpenChange"]>;
+};
+/**
+ * A centred, near-full-screen dialog that previews one item, typically a
+ * product, without leaving the page: a header with the item's name, a muted
+ * scrolling body and a footer for its actions. Controlled: the application
+ * decides what is shown and when it opens. Escape and a backdrop press close
+ * it, and focus returns to the control that opened it, even when a pointer
+ * press opened it without focusing that control.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ *
+ * @example
+ * <QuickView open={open} onOpenChange={setOpen}>
+ *   <QuickViewContent>
+ *     <QuickViewHeader actions={<Button>View full page</Button>}>
+ *       {product.name}
+ *     </QuickViewHeader>
+ *     <QuickViewBody aria-label="Product details">…</QuickViewBody>
+ *     <QuickViewFooter><Button>Add sample</Button></QuickViewFooter>
+ *   </QuickViewContent>
+ * </QuickView>
+ *
+ * @bestPractice Keep the last viewed item in state after closing, so the panel does not empty while it animates out.
+ * @bestPractice Put the item's name in `QuickViewHeader`; it is the dialog's accessible name.
+ * @bestPractice Offer a way to the full page in the header's `actions` - a quick view previews, it does not replace the detail page.
+ * @bestPractice A panel that docks beside the page (a cart) is a `Sidepanel`, not a quick view.
+ * @category catalogue
+ */
+export declare const QuickView: ({ open, onOpenChange, ...props }: QuickViewProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/quick-view/quick-view-root.js

@@ -0,0 +1,64 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Dialog } from "@instruments/materia-ui/components/dialog";
+import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { QuickViewContext } from "./quick-view-context.js";
+// What counts as the control that opened the quick view: the nearest
+// focusable ancestor of the pressed or focused element.
+const OPENER_SELECTOR = "button, a[href], input, select, textarea, [tabindex]:not([tabindex='-1'])";
+/**
+ * A centred, near-full-screen dialog that previews one item, typically a
+ * product, without leaving the page: a header with the item's name, a muted
+ * scrolling body and a footer for its actions. Controlled: the application
+ * decides what is shown and when it opens. Escape and a backdrop press close
+ * it, and focus returns to the control that opened it, even when a pointer
+ * press opened it without focusing that control.
+ * Import from "@instruments/materia-ui/compositions/quick-view".
+ *
+ * @example
+ * <QuickView open={open} onOpenChange={setOpen}>
+ *   <QuickViewContent>
+ *     <QuickViewHeader actions={<Button>View full page</Button>}>
+ *       {product.name}
+ *     </QuickViewHeader>
+ *     <QuickViewBody aria-label="Product details">…</QuickViewBody>
+ *     <QuickViewFooter><Button>Add sample</Button></QuickViewFooter>
+ *   </QuickViewContent>
+ * </QuickView>
+ *
+ * @bestPractice Keep the last viewed item in state after closing, so the panel does not empty while it animates out.
+ * @bestPractice Put the item's name in `QuickViewHeader`; it is the dialog's accessible name.
+ * @bestPractice Offer a way to the full page in the header's `actions` - a quick view previews, it does not replace the detail page.
+ * @bestPractice A panel that docks beside the page (a cart) is a `Sidepanel`, not a quick view.
+ * @category catalogue
+ */
+export const QuickView = ({ open, onOpenChange, ...props }) => {
+    const opener = useRef(null);
+    const popup = useRef(null);
+    const isOpen = useRef(open);
+    useLayoutEffect(() => {
+        isOpen.current = open;
+    }, [open]);
+    useEffect(() => {
+        const remember = (event) => {
+            const { target } = event;
+            if (isOpen.current ||
+                !(target instanceof Element) ||
+                popup.current?.contains(target) === true) {
+                return;
+            }
+            const control = target.closest(OPENER_SELECTOR);
+            if (control !== null) {
+                opener.current = control;
+            }
+        };
+        document.addEventListener("pointerdown", remember, true);
+        document.addEventListener("focusin", remember, true);
+        return () => {
+            document.removeEventListener("pointerdown", remember, true);
+            document.removeEventListener("focusin", remember, true);
+        };
+    }, []);
+    const context = useMemo(() => ({ opener, popup }), []);
+    return (_jsx(QuickViewContext.Provider, { value: context, children: _jsx(Dialog, { onOpenChange: onOpenChange, open: open, ...props }) }));
+};

package/dist/compositions/quick-view.d.ts

@@ -0,0 +1,6 @@
+export { QuickViewBody, type QuickViewBodyProps, } from "./quick-view/quick-view-body.js";
+export { QuickViewContent, type QuickViewContentProps, } from "./quick-view/quick-view-content.js";
+export { QuickViewFooter, type QuickViewFooterProps, } from "./quick-view/quick-view-footer.js";
+export { QuickViewHeader, type QuickViewHeaderProps, } from "./quick-view/quick-view-header.js";
+export { QuickViewDetails, type QuickViewDetailsProps, QuickViewLayout, type QuickViewLayoutProps, QuickViewMedia, type QuickViewMediaProps, } from "./quick-view/quick-view-layout.js";
+export { QuickView, type QuickViewProps } from "./quick-view/quick-view-root.js";

package/dist/compositions/quick-view.js

@@ -0,0 +1,6 @@
+export { QuickViewBody, } from "./quick-view/quick-view-body.js";
+export { QuickViewContent, } from "./quick-view/quick-view-content.js";
+export { QuickViewFooter, } from "./quick-view/quick-view-footer.js";
+export { QuickViewHeader, } from "./quick-view/quick-view-header.js";
+export { QuickViewDetails, QuickViewLayout, QuickViewMedia, } from "./quick-view/quick-view-layout.js";
+export { QuickView } from "./quick-view/quick-view-root.js";

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

@@ -0,0 +1,67 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { ReactNode } from "react";
+import type { HeadingSize } from "../../components/heading.js";
+import type { LayoutElement } from "../../tokens/element.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+/** Semantic heading level rendered by {@link SectionHeader}. */
+type SectionHeaderLevel = "1" | "2" | "3" | "4" | "5" | "6";
+export interface SectionHeaderProps extends Omit<useRender.ComponentProps<"header">, "title"> {
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Ref
+     * and event-handler types remain the default element's.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <SectionHeader as="div" title="Brands" />
+     */
+    as?: LayoutElement;
+    /** Right-aligned slot for controls (buttons, menus) beside the title. */
+    actions?: ReactNode | undefined;
+    /** Muted supporting copy rendered below the title. */
+    description?: ReactNode | undefined;
+    /** Short label above the title, rendered using the `.eyebrow` utility. */
+    eyebrow?: ReactNode | undefined;
+    /**
+     * Semantic heading level for the title (`h1`–`h6`); independent of `size`.
+     * @default "2"
+     */
+    level?: SectionHeaderLevel | undefined;
+    /**
+     * Keep the fixed eyebrow-row height even when `eyebrow` is absent, so titles
+     * stay aligned across sibling columns.
+     * @default false
+     */
+    reserveEyebrowSpace?: boolean | undefined;
+    /**
+     * Title type role (responsive-capable); the description's role tracks it.
+     * @default "subheading-lg"
+     */
+    size?: ResponsiveValue<HeadingSize> | undefined;
+    /** The section title. */
+    title: ReactNode;
+}
+/**
+ * A generic section header: an optional eyebrow label, a `Heading` title,
+ * an optional muted description, and an optional right-aligned actions slot.
+ * Typography is delegated to `Heading` and `Text`; the `data-slot` hooks
+ * (`section-header-eyebrow` / `-body` / `-actions`) let adopters retune spacing
+ * without forking the component.
+ *
+ * @example
+ * ```tsx
+ * <SectionHeader
+ *   description="Choose how reps discover your brand."
+ *   eyebrow="Step 2"
+ *   title="Brand visibility"
+ * />
+ * ```
+ *
+ * @bestPractice Renders a `<header>`, which is a `banner` landmark only when it is a direct child of `<body>`. It is built for nested/section use - don't render more than one page-level `SectionHeader` directly under `<body>`, or you'll create duplicate `banner` landmarks.
+ * @bestPractice Set `level` for the document outline and `size` for visual scale independently - a visually small header can still be an `h2`. Use `reserveEyebrowSpace` to keep an eyebrow-less header aligned beside sibling headers that have an eyebrow.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category headers
+ */
+export declare const SectionHeader: ({ actions, as, className, description, eyebrow, level, ref, render, reserveEyebrowSpace, size, title, ...props }: SectionHeaderProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};