plass-ui 0.0.1 → 1.0.0

package/dist/components/blockquote/PlBlockquote.d.ts

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import type { PlassElevation, PlassStyleProps } from '../../types.js';
+/**
+ * The props are a `<figure>`'s rather than a `<blockquote>`'s, which is a
+ * consequence of where the drawing happens: everything a caller passes lands on
+ * the wrapper, and the wrapper is a figure or a div. Both are `HTMLElement`, so
+ * an event handler written against one works on the other.
+ */
+export interface PlBlockquoteProps extends PlassStyleProps, Omit<React.ComponentPropsWithoutRef<'figure'>, 'color'> {
+    /**
+     * Drop shadow depth. `0` is the default — a quote is set *into* a page rather
+     * than floating over it, so it is raised even less often than a `PlCard`.
+     * @default 0
+     */
+    elevation?: PlassElevation;
+    /**
+     * Who said it. Its presence is what turns the quote into a `<figure>` with a
+     * `<figcaption>`, which is the markup the HTML spec asks for: an attribution
+     * is *about* the quote and is not part of what was said.
+     */
+    author?: React.ReactNode;
+    /**
+     * Where it is from — a book, a talk, a page. Rendered inside a `<cite>`, which
+     * is the element for the title of a work and, per the spec, never for the name
+     * of a person. That is what `author` is.
+     */
+    source?: React.ReactNode;
+    /**
+     * URL of the document the quote was taken from. Lands on the `<blockquote>`'s
+     * own `cite` attribute, which is machine-readable and shown to nobody — use
+     * `source` for the part a reader should see.
+     */
+    cite?: string;
+    /**
+     * The mark drawn before the quote. Omit it for the house glyph, pass a node to
+     * replace it, pass `false` to take it away — the same three-way spelling
+     * `PlAlert` uses for the same idea.
+     */
+    icon?: React.ReactNode | false;
+    /** What was said. */
+    children?: React.ReactNode;
+}
+/**
+ * Somebody else's words, set apart from your own.
+ *
+ * There is no Base UI primitive under this and there should not be: a quote has
+ * no state, no keyboard contract and nothing to interact with. What it has is
+ * markup that is easy to get wrong, and getting it right is most of the point.
+ *
+ * **Nothing is drawn on the `<blockquote>` itself.** The surface, the rule and
+ * the padding all belong to the element around it, and that is not tidiness —
+ * `blockquote` is one of the handful of tags a host stylesheet still styles by
+ * name. VitePress's `.vp-doc blockquote` sets a grey `border-left`, a
+ * `padding-left` and a `color`, all at a specificity a one-class utility cannot
+ * outrank, so a rule drawn on the quote itself would silently come out grey and
+ * a pixel too thin. Moving the drawing onto a wrapper is what lets the docs undo
+ * VitePress's version without also undoing this one.
+ *
+ * The wrapper is a `<figure>` when there is an attribution and a `<div>` when
+ * there is not, because the HTML spec is explicit that the attribution goes
+ * *outside* the blockquote — a name inside it claims the speaker said their own
+ * name — and a `<figure>` with no `<figcaption>` in it is a figure of nothing.
+ */
+export declare const PlBlockquote: React.ForwardRefExoticComponent<PlBlockquoteProps & React.RefAttributes<HTMLElement>>;

package/dist/components/blockquote/PlBlockquote.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { glassClasses, hasContent, metaTextClasses, radiusClasses, sheetPaddingXClasses, sheetPaddingYClasses, surfaceSlots, transitionClasses } from '../../internal/styles.js';
+/**
+ * The quote itself, one step above body copy with the leading opened up.
+ *
+ * The sizes are `sheetTitleClasses`', because a quote is set at a heading's
+ * scale — but the leading is not: a title is a line or two and a quote is a
+ * paragraph somebody has to read, so it gets the air a paragraph needs.
+ */
+const quoteTextClasses = {
+    xs: 'text-[0.75rem]/[1.25rem]',
+    sm: 'text-[0.8125rem]/[1.375rem]',
+    md: 'text-[0.9375rem]/[1.625rem]',
+    lg: 'text-[1.0625rem]/[1.875rem]',
+    xl: 'text-[1.25rem]/[2.125rem]'
+};
+/**
+ * The rule down the leading edge, and the one thing every variant has.
+ *
+ * `border-s`, not `border-l`: the rule belongs on the side the text starts on,
+ * which is the right edge under RTL. Its width is the one number here that does
+ * not come off a ladder — a quote rule is 2px at every size, because it is a
+ * mark in the margin rather than a part of the type.
+ */
+const ruleClasses = 'border-s-2 [border-inline-start-color:var(--p-accent)]';
+/**
+ * The three materials, said the way a *container* says them — the sheet is never
+ * dyed, exactly as on a `PlCard`. A quote holds somebody else's words, and words
+ * on a tinted pane are words on a background nobody chose them against. The
+ * family reaches the rule and stops.
+ *
+ * `ghost` is the default and the one that belongs in running prose: a rule in
+ * the margin and nothing else, which is what a quote has looked like since long
+ * before there were surfaces to put one on.
+ */
+const variantClasses = {
+    solid: /* @__PURE__ */ [
+        glassClasses,
+        'bg-(--plass-glass-press)',
+        '[box-shadow:var(--p-elev),var(--plass-gloss-glass)]'
+    ].join(' '),
+    // `border-s-2` again, after `border`, so the hairline on the other three edges
+    // does not flatten the rule back to a pixel.
+    glass: /* @__PURE__ */ [
+        glassClasses,
+        'border border-s-2 bg-(--plass-glass)',
+        '[border-color:var(--plass-glass-line)]',
+        '[box-shadow:var(--p-elev),var(--plass-gloss-glass)]'
+    ].join(' '),
+    ghost: 'bg-transparent'
+};
+/**
+ * The quotation mark: a pair of commas turned up, drawn rather than typed.
+ *
+ * A real `“` would be set in whatever face the page uses and would change shape,
+ * weight and baseline with it — and at 2em it is the largest single glyph in the
+ * component, so it changing is the most visible thing that could. This is one
+ * drawing at one weight, and it lives here rather than in `internal/icons.tsx`
+ * because exactly one component draws it.
+ */
+function QuoteMarkIcon() {
+    return (_jsx("svg", { viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M6.4 3.6c-2.3.9-3.7 2.8-3.7 5.1 0 2 1.2 3.3 2.8 3.3 1.4 0 2.5-1 2.5-2.4 0-1.3-.9-2.2-2.1-2.2-.2 0-.4 0-.6.1.3-1 1.1-1.8 2.2-2.3l-1.1-1.6ZM13.3 3.6c-2.3.9-3.7 2.8-3.7 5.1 0 2 1.2 3.3 2.8 3.3 1.4 0 2.5-1 2.5-2.4 0-1.3-.9-2.2-2.1-2.2-.2 0-.4 0-.6.1.3-1 1.1-1.8 2.2-2.3l-1.1-1.6Z", fill: "currentColor" }) }));
+}
+/**
+ * Somebody else's words, set apart from your own.
+ *
+ * There is no Base UI primitive under this and there should not be: a quote has
+ * no state, no keyboard contract and nothing to interact with. What it has is
+ * markup that is easy to get wrong, and getting it right is most of the point.
+ *
+ * **Nothing is drawn on the `<blockquote>` itself.** The surface, the rule and
+ * the padding all belong to the element around it, and that is not tidiness —
+ * `blockquote` is one of the handful of tags a host stylesheet still styles by
+ * name. VitePress's `.vp-doc blockquote` sets a grey `border-left`, a
+ * `padding-left` and a `color`, all at a specificity a one-class utility cannot
+ * outrank, so a rule drawn on the quote itself would silently come out grey and
+ * a pixel too thin. Moving the drawing onto a wrapper is what lets the docs undo
+ * VitePress's version without also undoing this one.
+ *
+ * The wrapper is a `<figure>` when there is an attribution and a `<div>` when
+ * there is not, because the HTML spec is explicit that the attribution goes
+ * *outside* the blockquote — a name inside it claims the speaker said their own
+ * name — and a `<figure>` with no `<figcaption>` in it is a figure of nothing.
+ */
+export const PlBlockquote = /* @__PURE__ */ React.forwardRef(function PlBlockquote({ variant = 'ghost', size = 'md', color = 'primary', density = 'default', elevation = 0, author, source, cite, icon, className, style, children, ...props }, ref) {
+    const attributed = hasContent(author) || hasContent(source);
+    const glyph = icon === undefined ? _jsx(QuoteMarkIcon, {}) : icon;
+    const shellClasses = [
+        'flex flex-col text-(--plass-fg)',
+        ruleClasses,
+        // The corners on the ruled edge stay square: a 2px rule that curves away
+        // from the text it marks is a bracket, not a margin rule.
+        variant === 'ghost' ? '' : `${radiusClasses[size]} rounded-s-none`,
+        variantClasses[variant],
+        sheetPaddingXClasses[density][size],
+        sheetPaddingYClasses[density][size],
+        transitionClasses,
+        className ?? ''
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const quote = (_jsxs("blockquote", { cite: cite, className: quoteTextClasses[size], children: [hasContent(glyph) ? (_jsx("span", { "aria-hidden": "true", className: "mb-1 block size-[2em] text-(--p-soft-press) [&>svg]:size-full", children: glyph })) : null, children] }));
+    const shellStyle = { ...surfaceSlots(color, elevation), ...style };
+    if (!attributed) {
+        return (_jsx("div", { ref: ref, className: shellClasses, style: shellStyle, ...props, children: quote }));
+    }
+    return (_jsxs("figure", { ref: ref, className: shellClasses, style: shellStyle, ...props, children: [quote, _jsxs("figcaption", { className: [
+                    'mt-2 flex flex-wrap items-baseline gap-x-1.5 text-(--plass-muted-fg)',
+                    metaTextClasses[size]
+                ].join(' '), children: [hasContent(author) ? (_jsxs("span", { className: "font-medium text-(--plass-fg)", children: [_jsx("span", { "aria-hidden": "true", children: "\u2014 " }), author] })) : null, hasContent(source) ? _jsx("cite", { className: "not-italic", children: source }) : null] })] }));
+});

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

@@ -0,0 +1,2 @@
+export { PlBlockquote } from './PlBlockquote.js';
+export type { PlBlockquoteProps } from './PlBlockquote.js';

package/dist/components/blockquote/index.js

@@ -0,0 +1 @@
+export { PlBlockquote } from './PlBlockquote.js';

package/dist/components/bottom-navigation/PlBottomNavigation.d.ts

@@ -0,0 +1,111 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassElevation, PlassPosition, PlassStyleProps } from '../../types.js';
+/** A destination's value. The same restraint `PlTabs` and `PlSegmentedButton` put on theirs. */
+export type PlBottomNavigationValue = string | number;
+/**
+ * Which names are drawn.
+ *
+ * - `all` — every destination is named. The default, and the only one that works
+ *   for a reader who has not used the app before.
+ * - `selected` — only the destination that is current. The bar keeps its height
+ *   either way, because the named one is always the tallest; what changes is how
+ *   much of the row is words. The names the other items lose are still in the
+ *   document for a screen reader.
+ * - `none` — glyphs only, with every name read out but never drawn.
+ */
+export type PlBottomNavigationLabels = 'all' | 'selected' | 'none';
+export interface PlBottomNavigationProps extends PlassStyleProps, Omit<React.ComponentPropsWithoutRef<'nav'>, 'color' | 'defaultValue' | 'onChange'> {
+    /** The destination the reader is on. Use with `onValueChange` for a controlled bar. */
+    value?: PlBottomNavigationValue | null;
+    /** Which starts current, for an uncontrolled bar. */
+    defaultValue?: PlBottomNavigationValue | null;
+    onValueChange?: (value: PlBottomNavigationValue) => void;
+    /**
+     * How the bar sits in the page's scroll.
+     *
+     * `fixed` — the default here, against the `static` a layout component would
+     * take — is what a bottom navigation *is*: held against the bottom edge of the
+     * window whatever the page does.
+     * @default 'fixed'
+     */
+    position?: PlassPosition;
+    /** Which names are drawn. @default 'all' */
+    labels?: PlBottomNavigationLabels;
+    /**
+     * Draws a hairline along the top edge, against the content the bar is over.
+     *
+     * On by default: a bar pinned over a scrolling page has content passing
+     * underneath it at every moment, and a translucent sheet with nothing marking
+     * its edge reads as part of that.
+     * @default true
+     */
+    divider?: boolean;
+    /**
+     * Keeps the bar clear of the home indicator on a phone, by adding
+     * `env(safe-area-inset-bottom)` under it. The sheet still reaches the bottom
+     * of the screen; only the items move up.
+     * @default true
+     */
+    safeArea?: boolean;
+    /**
+     * Drop shadow depth. `0` is the default and it is flat: the bar is attached to
+     * the edge of the window rather than floating over the middle of it, and
+     * `divider` is what separates it from the content.
+     * @default 0
+     */
+    elevation?: PlassElevation;
+    /** Every destination stops answering. */
+    disabled?: boolean;
+    /** The name the bar is announced by — "Main", "Sections". */
+    label?: string;
+    /**
+     * Renders something other than a `<nav>`. Base UI's own escape hatch, and
+     * rarely what you want here: a row of destinations is navigation.
+     */
+    render?: useRender.RenderProp;
+    /** The `PlBottomNavigationItem`s. */
+    children?: React.ReactNode;
+}
+export interface PlBottomNavigationItemProps extends Omit<React.ComponentPropsWithoutRef<'button'>, 'value' | 'color'> {
+    /** Identifies the destination. What `onValueChange` reports. */
+    value: PlBottomNavigationValue;
+    /** The glyph above the name. Sized on the standalone-glyph ladder. */
+    icon?: React.ReactNode;
+    /** Renders the item as a link rather than as a button. */
+    href?: string;
+    /** Unavailable, but still part of the set. */
+    disabled?: boolean;
+    /** The destination's name. Read out even when `labels` keeps it undrawn. */
+    children?: React.ReactNode;
+}
+/**
+ * A row of destinations held against the bottom edge of the window.
+ *
+ * It is a `<nav>` rather than a `role="tablist"`, and its items are ordinary
+ * links or buttons rather than tabs. That is a deliberate choice about what is
+ * being promised: a tab list owes a keyboard reader one tab stop for the whole
+ * set and arrow keys within it, and it owes a screen reader a panel per tab. A
+ * bottom navigation switches what the *page* is, not which panel of one is
+ * showing, and claiming the role without the behaviour is worse for a keyboard
+ * reader than never claiming it. What is claimed instead is `aria-current`,
+ * which is the honest statement: this is the destination you are on.
+ *
+ * The sheet is never dyed, exactly as on a `PlCard`. What carries the colour
+ * family is the one item that is current.
+ */
+export declare const PlBottomNavigation: React.ForwardRefExoticComponent<PlBottomNavigationProps & React.RefAttributes<HTMLElement>>;
+/**
+ * One destination.
+ *
+ * It has no `size`, no `color` and no `variant` of its own: all three belong to
+ * the bar, which is the only place they can be set once and mean the same thing
+ * for every item.
+ *
+ * With an `href` it is a real `<a>`, which is what makes a long press offer
+ * "open in a new tab" and what puts the destination in the status bar — neither
+ * of which a `<button>` that calls `router.push` can do. Without one it is a
+ * `<button>`, because a `<div>` carrying a click handler is invisible to a
+ * keyboard.
+ */
+export declare const PlBottomNavigationItem: React.ForwardRefExoticComponent<PlBottomNavigationItemProps & React.RefAttributes<HTMLElement>>;

package/dist/components/bottom-navigation/PlBottomNavigation.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { cx, focusRingInsetClasses, hasContent, iconSizeClasses, metaTextClasses, radiusClasses, sheetLineClasses, sheetRestClasses, srOnlyClasses, surfaceSlots, transitionClasses } from '../../internal/styles.js';
+const BottomNavigationContext = /* @__PURE__ */ React.createContext({
+    value: null,
+    change: () => { },
+    size: 'md',
+    density: 'default',
+    labels: 'all',
+    disabled: false
+});
+const positionClasses = {
+    static: '',
+    sticky: 'sticky bottom-0 z-20',
+    fixed: 'fixed inset-x-0 bottom-0 z-30'
+};
+/**
+ * The row's floor.
+ *
+ * `md` is 56px, which is the height a bottom navigation has had since the first
+ * one — tall enough for a glyph with a word under it, short enough that it is
+ * not competing with the page it is on. The ladder around it keeps the same
+ * proportion to the glyph and the name it holds.
+ */
+const rowMinHeightClasses = {
+    xs: 'min-h-10',
+    sm: 'min-h-12',
+    md: 'min-h-14',
+    lg: 'min-h-16',
+    xl: 'min-h-18'
+};
+/** The air inside the sheet, around the row of items. */
+const rowPaddingClasses = {
+    default: { xs: 'p-1', sm: 'p-1', md: 'p-1.5', lg: 'p-2', xl: 'p-2.5' },
+    compact: { xs: 'p-0.5', sm: 'p-0.5', md: 'p-1', lg: 'p-1', xl: 'p-1.5' }
+};
+/** Between the glyph and the name under it. */
+const itemGapClasses = {
+    xs: 'gap-0.5',
+    sm: 'gap-0.5',
+    md: 'gap-1',
+    lg: 'gap-1',
+    xl: 'gap-1.5'
+};
+/**
+ * A row of destinations held against the bottom edge of the window.
+ *
+ * It is a `<nav>` rather than a `role="tablist"`, and its items are ordinary
+ * links or buttons rather than tabs. That is a deliberate choice about what is
+ * being promised: a tab list owes a keyboard reader one tab stop for the whole
+ * set and arrow keys within it, and it owes a screen reader a panel per tab. A
+ * bottom navigation switches what the *page* is, not which panel of one is
+ * showing, and claiming the role without the behaviour is worse for a keyboard
+ * reader than never claiming it. What is claimed instead is `aria-current`,
+ * which is the honest statement: this is the destination you are on.
+ *
+ * The sheet is never dyed, exactly as on a `PlCard`. What carries the colour
+ * family is the one item that is current.
+ */
+export const PlBottomNavigation = /* @__PURE__ */ React.forwardRef(function PlBottomNavigation({ variant = 'glass', size = 'md', color = 'primary', density = 'default', elevation = 0, value: valueProp, defaultValue = null, onValueChange, position = 'fixed', labels = 'all', divider = true, safeArea = true, disabled = false, label, render, className, style, children, ...props }, ref) {
+    const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
+    const controlled = valueProp !== undefined;
+    const value = controlled ? valueProp : uncontrolled;
+    const change = React.useCallback((next) => {
+        if (!controlled) {
+            setUncontrolled(next);
+        }
+        onValueChange?.(next);
+    }, [controlled, onValueChange]);
+    const context = React.useMemo(() => ({ value: value ?? null, change, size, density, labels, disabled }), [value, change, size, density, labels, disabled]);
+    const classNames = cx('w-full min-w-0', 
+    // A bar spanning an edge of the window has nothing behind its corners, so
+    // only one sitting in the flow is a sheet with corners at all.
+    position === 'static' ? radiusClasses[size] : '', sheetRestClasses[variant], 
+    // A bar that is not in the flow has three edges against the window and one
+    // against the content, so only that one is ever drawn — a hairline down
+    // the left of the screen is a hairline nobody asked for. In the flow it is
+    // an ordinary sheet and keeps the whole outline `sheetRestClasses` gave it.
+    variant === 'glass' && position !== 'static' ? 'border-0' : '', divider ? sheetLineClasses : '', positionClasses[position], 
+    // The sheet keeps reaching the bottom of the screen; what the inset moves
+    // is the row inside it. A bar that stopped above the home indicator would
+    // leave a stripe of page showing under the glass.
+    safeArea ? 'pb-[env(safe-area-inset-bottom)]' : '', transitionClasses, className);
+    return useRender({
+        render: render ?? _jsx("nav", {}),
+        ref,
+        props: {
+            'aria-label': label,
+            className: classNames,
+            style: { ...surfaceSlots(color, elevation), ...style },
+            children: (_jsx(BottomNavigationContext.Provider, { value: context, children: _jsx("div", { className: cx('flex w-full items-stretch', rowMinHeightClasses[size], rowPaddingClasses[density][size]), children: children }) })),
+            ...props
+        }
+    });
+});
+/**
+ * One destination.
+ *
+ * It has no `size`, no `color` and no `variant` of its own: all three belong to
+ * the bar, which is the only place they can be set once and mean the same thing
+ * for every item.
+ *
+ * With an `href` it is a real `<a>`, which is what makes a long press offer
+ * "open in a new tab" and what puts the destination in the status bar — neither
+ * of which a `<button>` that calls `router.push` can do. Without one it is a
+ * `<button>`, because a `<div>` carrying a click handler is invisible to a
+ * keyboard.
+ */
+export const PlBottomNavigationItem = /* @__PURE__ */ React.forwardRef(function PlBottomNavigationItem({ value, icon, href, disabled: disabledProp = false, className, children, onClick, ...props }, ref) {
+    const bar = React.useContext(BottomNavigationContext);
+    const disabled = disabledProp || bar.disabled;
+    const selected = bar.value !== null && bar.value === value;
+    const named = bar.labels === 'all' || (bar.labels === 'selected' && selected);
+    const classNames = cx('flex min-w-0 flex-1 flex-col items-center justify-center px-1 py-1.5', itemGapClasses[bar.size], radiusClasses[bar.size], '[-webkit-tap-highlight-color:transparent] [touch-action:manipulation]', transitionClasses, 
+    // Inset rather than offset: the item is inside a sheet that clips, and a
+    // ring drawn outside it would have its top sliced off.
+    focusRingInsetClasses, 
+    // An if/else rather than stacked variants: two Tailwind classes of equal
+    // specificity resolve by their order in the generated stylesheet.
+    disabled
+        ? 'cursor-not-allowed opacity-50 saturate-[0.35] text-(--plass-muted-fg)'
+        : selected
+            ? 'cursor-pointer font-medium text-(--p-accent) bg-(--p-soft) hover:bg-(--p-soft-hover)'
+            : 'cursor-pointer text-(--plass-muted-fg) hover:text-(--plass-fg) hover:bg-(--plass-glass-hover)', className);
+    const body = (_jsxs(_Fragment, { children: [hasContent(icon) ? (_jsx("span", { className: cx('flex shrink-0 items-center justify-center', iconSizeClasses[bar.size]), children: icon })) : null, hasContent(children) ? (_jsx("span", { className: named
+                    ? cx('max-w-full truncate leading-tight', metaTextClasses[bar.size])
+                    : srOnlyClasses, children: children })) : null] }));
+    const press = (event) => {
+        if (disabled) {
+            event.preventDefault();
+            return;
+        }
+        bar.change(value);
+        onClick?.(event);
+    };
+    if (href) {
+        return (_jsx("a", { ref: ref, href: disabled ? undefined : href, "aria-current": selected ? 'page' : undefined, "aria-disabled": disabled || undefined, className: classNames, onClick: press, ...props, children: body }));
+    }
+    return (_jsx("button", { ref: ref, type: "button", disabled: disabled, "aria-current": selected ? 'page' : undefined, className: classNames, onClick: press, ...props, children: body }));
+});

package/dist/components/bottom-navigation/index.d.ts

@@ -0,0 +1,2 @@
+export { PlBottomNavigation, PlBottomNavigationItem } from './PlBottomNavigation.js';
+export type { PlBottomNavigationItemProps, PlBottomNavigationLabels, PlBottomNavigationProps, PlBottomNavigationValue } from './PlBottomNavigation.js';

package/dist/components/bottom-navigation/index.js

@@ -0,0 +1 @@
+export { PlBottomNavigation, PlBottomNavigationItem } from './PlBottomNavigation.js';

package/dist/components/box/PlBox.d.ts

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassElevation, PlassStyleProps } from '../../types.js';
+export interface PlBoxProps extends PlassStyleProps, Omit<React.ComponentPropsWithoutRef<'div'>, 'color'> {
+    /**
+     * Drop shadow depth. `0` is the default and it is flat — the glass edge is
+     * what separates the box from the page. Raise it only for a surface that
+     * genuinely floats above the content around it.
+     * @default 0
+     */
+    elevation?: PlassElevation;
+    /**
+     * Inner padding, on the `size` / `density` scale. Turn it off for full-bleed
+     * content — an image, a table, a list that draws its own rows.
+     * @default true
+     */
+    padded?: boolean;
+    /**
+     * Renders something other than a `<div>`: `render={<section />}`,
+     * `render={<li />}`, or a function for full control. Base UI's own escape
+     * hatch, so it behaves the same here as on every Base UI primitive.
+     */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+/**
+ * A sheet of glass with content on it. The plainest surface in the library: it
+ * groups things, and that is all it does.
+ *
+ * Everything structural — a title, a footer, hairlines between sections —
+ * belongs to `PlCard`, which is a box with those sections laid out on it. What
+ * is left here is the sheet itself, and the reason it is worth having on its own
+ * is that most of what a screen groups has no heading: a well behind a form, a
+ * tile in a shelf, a panel round a chart.
+ *
+ * `size` means something different here from what it means on a control, and
+ * this is the one place in the library where that is true. A box is as tall as
+ * what it holds, and its children bring their own typography — a container that
+ * reset the type scale would render the same paragraph at two sizes depending
+ * on what it was wrapped in. So `size` is the size of the **sheet**: its radius
+ * and its padding, and nothing else.
+ *
+ * The three materials say what they say everywhere else, read as a container's:
+ * the sheet is never dyed, because what a box holds arrives with its own
+ * colours and tinting the pane under them puts every one on a background it was
+ * not chosen against. The family reaches the hairline and the focus ring and
+ * stops. `ghost` is the one to reach for inside another surface, where a second
+ * bordered rectangle is a second rectangle.
+ */
+export declare const PlBox: React.ForwardRefExoticComponent<PlBoxProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/box/PlBox.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { cx, radiusClasses, sheetPaddingXClasses, sheetPaddingYClasses, sheetRestClasses, surfaceSlots, transitionClasses } from '../../internal/styles.js';
+/**
+ * A sheet of glass with content on it. The plainest surface in the library: it
+ * groups things, and that is all it does.
+ *
+ * Everything structural — a title, a footer, hairlines between sections —
+ * belongs to `PlCard`, which is a box with those sections laid out on it. What
+ * is left here is the sheet itself, and the reason it is worth having on its own
+ * is that most of what a screen groups has no heading: a well behind a form, a
+ * tile in a shelf, a panel round a chart.
+ *
+ * `size` means something different here from what it means on a control, and
+ * this is the one place in the library where that is true. A box is as tall as
+ * what it holds, and its children bring their own typography — a container that
+ * reset the type scale would render the same paragraph at two sizes depending
+ * on what it was wrapped in. So `size` is the size of the **sheet**: its radius
+ * and its padding, and nothing else.
+ *
+ * The three materials say what they say everywhere else, read as a container's:
+ * the sheet is never dyed, because what a box holds arrives with its own
+ * colours and tinting the pane under them puts every one on a background it was
+ * not chosen against. The family reaches the hairline and the focus ring and
+ * stops. `ghost` is the one to reach for inside another surface, where a second
+ * bordered rectangle is a second rectangle.
+ */
+export const PlBox = /* @__PURE__ */ React.forwardRef(function PlBox({ variant = 'glass', size = 'md', color = 'primary', density = 'default', elevation = 0, padded = true, render, className, style, children, ...props }, ref) {
+    const classNames = cx('block', radiusClasses[size], padded ? `${sheetPaddingXClasses[density][size]} ${sheetPaddingYClasses[density][size]}` : '', sheetRestClasses[variant], 
+    // The same property list and duration as everything else, so a box whose
+    // colour or elevation changes settles at the house pace. There is no
+    // `:active` treatment because a box is not pressed — it holds things that
+    // are.
+    transitionClasses, className);
+    return useRender({
+        render: render ?? _jsx("div", {}),
+        ref,
+        props: {
+            className: classNames,
+            style: { ...surfaceSlots(color, elevation), ...style },
+            children,
+            ...props
+        }
+    });
+});

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

@@ -0,0 +1,2 @@
+export { PlBox } from './PlBox.js';
+export type { PlBoxProps } from './PlBox.js';

package/dist/components/box/index.js

@@ -0,0 +1 @@
+export { PlBox } from './PlBox.js';