plass-ui 0.0.1 → 1.0.0

package/dist/components/segmented-button/PlSegmentedButton.js

@@ -0,0 +1,206 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { Radio as BaseUIRadio } from '@base-ui/react/radio';
+import { RadioGroup as BaseUIRadioGroup } from '@base-ui/react/radio-group';
+import { controlHeightClasses, controlSlots, controlTextClasses, focusRingInsetClasses, gapClasses, glassClasses, hasContent, iconClasses, paddingXClasses, transitionClasses } from '../../internal/styles.js';
+const SegmentedButtonContext = /* @__PURE__ */ React.createContext({
+    variant: 'glass',
+    size: 'md',
+    density: 'default',
+    fullWidth: false
+});
+/* ---------------------------------------------------------------------------
+ * The groove and the tile
+ * ------------------------------------------------------------------------- */
+/**
+ * The groove carries `--plass-well`, the one inset shadow in the library and
+ * the same one a `solid` field is drawn with. A segmented button, a slider's
+ * rail and a filled text field are the same idea: something recessed that holds
+ * a value.
+ */
+const troughClasses = {
+    solid: `${glassClasses} bg-(--plass-glass-press) p-1 [box-shadow:var(--p-elev),var(--plass-well)]`,
+    glass: `${glassClasses} border bg-(--plass-glass) p-1 [border-color:var(--plass-glass-line)] [box-shadow:var(--p-elev),var(--plass-well)]`,
+    ghost: ''
+};
+/**
+ * The tile that slides.
+ *
+ * `solid` makes it the family's gradient with that family's tinted shadow under
+ * it — a key of tinted glass riding in a groove, which is the design language's
+ * own sentence with nothing added. The other two lift a pane of clear glass
+ * instead and leave the label in the accent.
+ */
+const tileClasses = {
+    solid: '[background-image:var(--p-fill)] [box-shadow:var(--plass-shadow-1),var(--p-lift)]',
+    glass: `${glassClasses} bg-(--plass-glass-press) [box-shadow:var(--plass-shadow-1),var(--plass-gloss-glass)]`,
+    ghost: `${glassClasses} bg-(--plass-glass-press) [box-shadow:var(--plass-shadow-1),var(--plass-gloss-glass)]`
+};
+/** What the chosen label is written in, which is the other half of the tile. */
+const checkedTextClasses = {
+    solid: 'data-[checked]:text-(--p-on-solid)',
+    glass: 'data-[checked]:text-(--p-accent)',
+    ghost: 'data-[checked]:text-(--p-accent)'
+};
+/**
+ * One choice in a segmented button.
+ *
+ * It has no `size`, no `color` and no `variant` of its own: all three belong to
+ * the set, which is the only place they can be set once and mean the same thing
+ * for every segment.
+ */
+export const PlSegment = /* @__PURE__ */ React.forwardRef(function PlSegment({ value, startIcon, endIcon, disabled = false, className, children, ...props }, ref) {
+    const { variant, size, density, fullWidth } = React.useContext(SegmentedButtonContext);
+    return (_jsxs(BaseUIRadio.Root, { ref: ref, value: value, disabled: disabled, "data-segment": "", className: [
+            // `z-10` and a stacking context of its own: the tile is painted behind
+            // the segments, and without this it would cover the label it is under.
+            'relative z-10 inline-flex shrink-0 cursor-pointer items-center justify-center select-none',
+            'font-semibold whitespace-nowrap',
+            '[-webkit-tap-highlight-color:transparent] [touch-action:manipulation]',
+            controlHeightClasses[size],
+            controlTextClasses[size],
+            gapClasses[size],
+            paddingXClasses[density][size],
+            // Round, and one of only three places the library allows it — for the
+            // same reason a switch's track is: this is not a sheet lying on the
+            // page, it is a tile riding in a groove cut into one.
+            'rounded-full',
+            transitionClasses,
+            iconClasses,
+            'text-(--plass-muted-fg) hover:text-(--plass-fg)',
+            checkedTextClasses[variant],
+            // Inset rather than offset — an offset ring on a segment inside a groove
+            // is drawn on top of its neighbours.
+            focusRingInsetClasses,
+            'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
+            'data-[readonly]:cursor-default',
+            fullWidth ? 'flex-1' : '',
+            className ?? ''
+        ]
+            .filter(Boolean)
+            .join(' '), ...props, children: [hasContent(startIcon) ? (_jsx("span", { className: "flex h-[1lh] shrink-0 items-center", children: startIcon })) : null, children, hasContent(endIcon) ? (_jsx("span", { className: "flex h-[1lh] shrink-0 items-center", children: endIcon })) : null] }));
+});
+/**
+ * Two or more choices in one pill, exactly one of them taken.
+ *
+ * Underneath it is a radio group, and that is the whole accessibility argument:
+ * a segmented button *is* "exactly one of these", so it gets
+ * `role="radiogroup"`, one tab stop for the set, arrow keys within it, and
+ * `aria-checked` on the one that is taken. Building it out of `aria-pressed`
+ * toggles — which is what a row of buttons would give — would announce four
+ * independent switches, three of which happen to be off.
+ *
+ * The tile slides because its `left`, `top`, `width` and `height` are measured
+ * off the chosen segment and animated. Nothing is transformed: the tile is an
+ * empty box, and no label is resampled while it travels. That is what lets the
+ * house no-transform rule survive a component whose entire point is that
+ * something moves.
+ *
+ * `left`, not `inset-inline-start`: `offsetLeft` is a distance from the left
+ * edge and stays one under RTL, and pairing a physical measurement with a
+ * logical property is what would break the direction.
+ */
+export const PlSegmentedButton = /* @__PURE__ */ React.forwardRef(function PlSegmentedButton({ variant = 'glass', size = 'md', color = 'primary', density = 'default', elevation = 0, value: valueProp, defaultValue = null, onValueChange, disabled = false, readOnly = false, name, fullWidth = false, className, style, children, ...props }, ref) {
+    const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
+    const controlled = valueProp !== undefined;
+    const value = controlled ? valueProp : uncontrolled;
+    const rootRef = React.useRef(null);
+    const tileRef = React.useRef(null);
+    /**
+     * Writes the chosen segment's box onto the tile as four custom properties.
+     *
+     * Written straight to the element rather than held in state, the way
+     * PlButton writes the pointer position: a `setState` here would re-render
+     * the whole set on every resize, and nothing in the tree depends on the
+     * numbers except four CSS declarations.
+     *
+     * `animate` is what separates the two callers. A value change is the thing
+     * this component exists to animate; a resize is the container moving under a
+     * tile that was already in the right place, and animating that is a tile
+     * that lags behind the window being dragged.
+     */
+    const measure = React.useCallback((animate) => {
+        const root = rootRef.current;
+        const tile = tileRef.current;
+        if (!root || !tile) {
+            return;
+        }
+        const active = root.querySelector('[data-segment][data-checked]');
+        if (!active) {
+            return;
+        }
+        // A tile that has only just mounted has nowhere to travel *from*, so its
+        // first placement is instant however it was asked for — that is what makes
+        // the first choice of an empty set appear under the segment rather than
+        // fly in from the left edge.
+        const instant = !animate || !tile.hasAttribute('data-ready');
+        if (instant) {
+            tile.removeAttribute('data-ready');
+        }
+        // `offsetLeft`/`offsetTop` are measured from the offsetParent's padding
+        // edge, and `left`/`top` on an absolutely positioned child resolve against
+        // the same box — so the groove's own padding is already accounted for and
+        // must not be subtracted again.
+        tile.style.setProperty('--p-seg-x', `${active.offsetLeft}px`);
+        tile.style.setProperty('--p-seg-y', `${active.offsetTop}px`);
+        tile.style.setProperty('--p-seg-w', `${active.offsetWidth}px`);
+        tile.style.setProperty('--p-seg-h', `${active.offsetHeight}px`);
+        if (instant) {
+            // Reading a layout property commits the four writes above while the
+            // duration is still 0ms, so turning the transition back on cannot
+            // animate a move that has already happened.
+            void tile.offsetWidth;
+        }
+        tile.setAttribute('data-ready', '');
+    }, []);
+    // Before the browser paints, or the tile is visibly at nothing for a frame.
+    React.useLayoutEffect(() => {
+        measure(true);
+    }, [measure, value, variant, size, density, fullWidth, children]);
+    React.useEffect(() => {
+        const root = rootRef.current;
+        if (!root) {
+            return;
+        }
+        const observer = new ResizeObserver(() => measure(false));
+        observer.observe(root);
+        return () => observer.disconnect();
+    }, [measure]);
+    const context = React.useMemo(() => ({ variant, size, density, fullWidth }), [variant, size, density, fullWidth]);
+    return (_jsx(SegmentedButtonContext.Provider, { value: context, children: _jsxs(BaseUIRadioGroup, { ref: (node) => {
+                rootRef.current = node;
+                if (typeof ref === 'function') {
+                    ref(node);
+                }
+                else if (ref) {
+                    ref.current = node;
+                }
+            }, value: value, onValueChange: (next) => {
+                const chosen = (next ?? null);
+                if (!controlled) {
+                    setUncontrolled(chosen);
+                }
+                onValueChange?.(chosen);
+            }, disabled: disabled, readOnly: readOnly, name: name, className: [
+                // `relative` is load-bearing twice over: it is what makes the groove
+                // the segments' offsetParent, and what the tile is positioned in.
+                'relative inline-flex items-center rounded-full',
+                troughClasses[variant],
+                transitionClasses,
+                readOnly ? 'saturate-[0.55]' : '',
+                disabled ? 'opacity-50 saturate-[0.35]' : '',
+                fullWidth ? 'flex w-full' : '',
+                className ?? ''
+            ]
+                .filter(Boolean)
+                .join(' '), style: { ...controlSlots(color, elevation, variant), ...style }, ...props, children: [value !== null && value !== undefined ? (_jsx("span", { ref: tileRef, "aria-hidden": "true", className: [
+                        'pointer-events-none absolute rounded-full',
+                        'top-(--p-seg-y) left-(--p-seg-x) h-(--p-seg-h) w-(--p-seg-w)',
+                        tileClasses[variant],
+                        '[transition-property:left,top,width,height]',
+                        '[transition-timing-function:var(--plass-ease)]',
+                        // Nothing until the first measurement has landed; the house
+                        // duration from then on.
+                        '[transition-duration:0ms] data-[ready]:[transition-duration:var(--plass-duration)]'
+                    ].join(' ') })) : null, children] }) }));
+});

package/dist/components/segmented-button/index.d.ts

@@ -0,0 +1,2 @@
+export { PlSegment, PlSegmentedButton } from './PlSegmentedButton.js';
+export type { PlSegmentProps, PlSegmentValue, PlSegmentedButtonProps } from './PlSegmentedButton.js';

package/dist/components/segmented-button/index.js

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

package/dist/components/select/PlSelect.d.ts

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import type { PlassElevation, PlassStyleProps } from '../../types.js';
+/**
+ * What a select's value may be.
+ *
+ * Deliberately not generic over arbitrary objects. A select is a form control,
+ * its value is what a form submits, and every escape from that — object values,
+ * custom equality, a stringifier for the trigger — buys flexibility by making
+ * the common case harder to write. Keep the identifier here and look the object
+ * up on the other side.
+ */
+export type PlSelectValue = string | number;
+export interface PlSelectOption {
+    /** Submitted, and what `value` / `onValueChange` speak in. */
+    value: PlSelectValue;
+    /** Shown in the list and in the trigger. Defaults to the value itself. */
+    label?: React.ReactNode;
+    /** Unavailable, but still listed — the option exists, it just cannot be picked. */
+    disabled?: boolean;
+}
+export interface PlSelectProps extends PlassStyleProps, Omit<React.ComponentPropsWithoutRef<'div'>, 'color' | 'defaultValue' | 'children'> {
+    /**
+     * The options, as data. There is no `<PlSelect.Option>` to compose: what a
+     * caller has is almost always an array already, and the list has to be
+     * available to the trigger before the popup has ever been opened.
+     */
+    items: readonly PlSelectOption[];
+    /** The chosen value. Use with `onValueChange` for a controlled select. */
+    value?: PlSelectValue | null;
+    /** The initially chosen value, for an uncontrolled select. */
+    defaultValue?: PlSelectValue | null;
+    onValueChange?: (value: PlSelectValue | null) => void;
+    /** Shown in the trigger while nothing is chosen. */
+    placeholder?: React.ReactNode;
+    /**
+     * Drop shadow depth of the *trigger*. `0`, like a PlTextField: a field is cut
+     * into the sheet rather than resting on it. The popup has its own, fixed at
+     * `3` — it genuinely floats above the page, which is the one case elevation
+     * is for.
+     * @default 0
+     */
+    elevation?: PlassElevation;
+    /** Label above the trigger, wired to it by Base UI's Field. */
+    label?: React.ReactNode;
+    /** Helper text below the trigger. */
+    description?: React.ReactNode;
+    /** Error message below. Its presence also turns the select invalid. */
+    error?: React.ReactNode;
+    /** Forces the invalid state without a message. Defaults to whether `error` has content. */
+    invalid?: boolean;
+    /** Content placed before the value. Sized in `em`, so it tracks the text. */
+    startIcon?: React.ReactNode;
+    /** Stretches to the width of the container. */
+    fullWidth?: boolean;
+    /** Unavailable. */
+    disabled?: boolean;
+    /** The value is shown but cannot be changed. */
+    readOnly?: boolean;
+    /** Whether a value must be chosen before the form is submitted. */
+    required?: boolean;
+    /** Identifies the field when a form is submitted. */
+    name?: string;
+    id?: string;
+}
+/**
+ * One value chosen from a list of them.
+ *
+ * The trigger is a PlTextField's shell wearing a chevron, on purpose: a form
+ * where the select is a different height, radius or material from the fields
+ * around it is a form that looks assembled rather than designed. That is why
+ * `fieldRestClasses` lives in `internal/styles` and not in either component.
+ *
+ * Base UI owns everything hard about this — the popup's positioning and
+ * flipping, the focus trap, typeahead, the hidden input that makes it submit —
+ * and the work here is the surface it all wears.
+ */
+export declare const PlSelect: React.ForwardRefExoticComponent<PlSelectProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/select/PlSelect.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { Select as BaseUISelect } from '@base-ui/react/select';
+import { Field } from '@base-ui/react/field';
+import { CheckIcon, ChevronIcon } from '../../internal/icons.js';
+import { WidthSizer } from '../../internal/sizer.js';
+import { controlHeightClasses, controlTextLeadingClasses, disabledClasses, fieldReadOnlyClasses, fieldRestClasses, focusWithinRingClasses, gapClasses, glassClasses, hasContent, iconClasses, metaTextClasses, paddingXClasses, radiusClasses, stackGapClasses, surfaceSlots, transitionClasses } from '../../internal/styles.js';
+/** The trigger is a PlTextField's shell, to the pixel. */
+const triggerBaseClasses = /* @__PURE__ */ [
+    'group relative flex w-full cursor-pointer items-center select-none',
+    '[-webkit-tap-highlight-color:transparent] [touch-action:manipulation]',
+    transitionClasses,
+    focusWithinRingClasses,
+    iconClasses
+].join(' ');
+/**
+ * The popup is the one surface in the library that is *supposed* to float, so
+ * unlike everything else it carries a shadow by default — at level 3.
+ *
+ * It is the glass at its most opaque, because it has a page under it rather
+ * than a sheet: a 62%-translucent pane over arbitrary body copy is a pane you
+ * read the body copy through.
+ *
+ * Every `--p-*` it reads is set on the popup itself rather than inherited from
+ * the Field around it. A portalled popup renders at the end of `<body>`, so it
+ * is outside the element the slots were declared on, and a `var()` with nothing
+ * to resolve to is not a fallback — `border-color` collapses to `currentColor`
+ * (a black hairline) and `background-color` to transparent.
+ */
+const popupClasses = /* @__PURE__ */ [
+    glassClasses,
+    'max-h-[min(20rem,var(--available-height))] overflow-y-auto overscroll-contain',
+    'min-w-[var(--anchor-width)] border bg-(--plass-glass-press) p-1',
+    '[border-color:var(--plass-glass-line)]',
+    '[box-shadow:var(--plass-shadow-3),var(--plass-gloss-glass)]',
+    '[outline:none]'
+].join(' ');
+const itemClasses = /* @__PURE__ */ [
+    'relative flex cursor-pointer items-center gap-2 select-none',
+    'rounded-(--plass-radius-xs) py-1.5 pe-2 ps-7',
+    transitionClasses,
+    // `data-highlighted` rather than `:hover`: it is also what the arrow keys
+    // move, so the mouse and the keyboard light the same row.
+    'data-[highlighted]:bg-(--p-soft-hover) data-[highlighted]:text-(--p-accent)',
+    'data-[selected]:font-semibold data-[selected]:text-(--p-accent)',
+    'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
+    '[outline:none]'
+].join(' ');
+/**
+ * One value chosen from a list of them.
+ *
+ * The trigger is a PlTextField's shell wearing a chevron, on purpose: a form
+ * where the select is a different height, radius or material from the fields
+ * around it is a form that looks assembled rather than designed. That is why
+ * `fieldRestClasses` lives in `internal/styles` and not in either component.
+ *
+ * Base UI owns everything hard about this — the popup's positioning and
+ * flipping, the focus trap, typeahead, the hidden input that makes it submit —
+ * and the work here is the surface it all wears.
+ */
+export const PlSelect = /* @__PURE__ */ React.forwardRef(function PlSelect({ variant = 'glass', size = 'md', color = 'primary', density = 'default', elevation = 0, items, value, defaultValue, onValueChange, placeholder, label, description, error, invalid, startIcon, fullWidth = false, disabled = false, readOnly = false, required = false, name, id, className, style, ...props }, ref) {
+    const hasError = hasContent(error);
+    const isInvalid = invalid ?? hasError;
+    // Invalid re-points the whole slot family at `danger`, so the edge, the ring
+    // and the message all turn over together.
+    const family = isInvalid ? 'danger' : color;
+    // Base UI reads this to render the chosen option's *label* in the trigger
+    // rather than its raw value, which is the only way `<Select.Value>` can show
+    // "Seoul" for `value="kr-11"` before the popup has ever been mounted.
+    const baseItems = React.useMemo(() => items.map((item) => ({ label: item.label ?? String(item.value), value: item.value })), [items]);
+    // Holds the trigger open at the width of the longest thing it could say, so
+    // choosing a shorter option does not shrink the field out from under the
+    // pointer that chose it.
+    const sizerSamples = React.useMemo(() => [
+        ...items.map((item) => item.label ?? String(item.value)),
+        ...(hasContent(placeholder) ? [placeholder] : [])
+    ], [items, placeholder]);
+    return (_jsxs(Field.Root, { disabled: disabled, invalid: isInvalid, className: [
+            'flex-col align-top',
+            stackGapClasses[size],
+            fullWidth ? 'flex w-full' : 'inline-flex',
+            className ?? ''
+        ]
+            .filter(Boolean)
+            .join(' '), style: { ...surfaceSlots(family, elevation), ...style }, ...props, children: [label ? (_jsx(Field.Label, { className: [
+                    metaTextClasses[size],
+                    'font-semibold',
+                    disabled ? 'text-(--plass-muted-fg)' : 'text-(--plass-fg)'
+                ].join(' '), children: label })) : null, _jsxs(BaseUISelect.Root, { id: id, name: name, items: baseItems, value: value, defaultValue: defaultValue, onValueChange: (next) => onValueChange?.(next), disabled: disabled, readOnly: readOnly, required: required, children: [_jsxs(BaseUISelect.Trigger, { ref: ref, className: [
+                            triggerBaseClasses,
+                            controlHeightClasses[size],
+                            controlTextLeadingClasses[size],
+                            radiusClasses[size],
+                            gapClasses[size],
+                            paddingXClasses[density][size],
+                            // An if/else rather than stacked variants: two Tailwind classes of
+                            // equal specificity resolve by their order in the generated sheet.
+                            disabled
+                                ? disabledClasses[variant]
+                                : readOnly
+                                    ? `${fieldReadOnlyClasses[variant]} cursor-default`
+                                    : fieldRestClasses[variant]
+                        ].join(' '), children: [startIcon ? (_jsx("span", { className: "flex h-[1lh] shrink-0 items-center text-(--plass-muted-fg)", children: startIcon })) : null, _jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx(BaseUISelect.Value, { className: [
+                                            'w-full truncate text-start',
+                                            // The placeholder is muted the same way a PlTextField's is, so
+                                            // an empty select and an empty field read as equally empty.
+                                            'data-[placeholder]:text-(--plass-muted-fg)'
+                                        ].join(' '), placeholder: placeholder }), _jsx(WidthSizer, { samples: sizerSamples })] }), _jsx(BaseUISelect.Icon, { className: [
+                                    'flex h-[1lh] shrink-0 items-center text-(--plass-muted-fg)',
+                                    // The chevron is the one thing here that may turn: it is a glyph,
+                                    // not a label, and nothing about it resamples.
+                                    '[transition:rotate_var(--plass-duration)_var(--plass-ease)]',
+                                    'data-[popup-open]:rotate-180'
+                                ].join(' '), children: _jsx(ChevronIcon, {}) })] }), _jsx(BaseUISelect.Portal, { children: _jsx(BaseUISelect.Positioner, { className: "plass-portal z-50 [outline:none]", sideOffset: 6, alignItemWithTrigger: false, children: _jsx(BaseUISelect.Popup, { className: `${popupClasses} ${radiusClasses[size]} ${controlTextLeadingClasses[size]}`, style: surfaceSlots(family, 3), children: items.map((item) => (_jsxs(BaseUISelect.Item, { value: item.value, disabled: item.disabled, className: itemClasses, children: [_jsx(BaseUISelect.ItemIndicator, { className: "absolute start-1.5 flex size-4 items-center justify-center", children: _jsx(CheckIcon, {}) }), _jsx(BaseUISelect.ItemText, { className: "truncate", children: item.label ?? String(item.value) })] }, String(item.value)))) }) }) })] }), description ? (_jsx(Field.Description, { className: `${metaTextClasses[size]} text-(--plass-muted-fg)`, children: description })) : null, hasError ? (_jsx(Field.Error, { match: true, className: `${metaTextClasses[size]} text-(--p-accent)`, children: error })) : null] }));
+});

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

@@ -0,0 +1,2 @@
+export { PlSelect } from './PlSelect.js';
+export type { PlSelectOption, PlSelectProps, PlSelectValue } from './PlSelect.js';

package/dist/components/select/index.js

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

package/dist/components/skeleton/PlSkeleton.d.ts

@@ -0,0 +1,73 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassColor, PlassSize } from '../../types.js';
+/**
+ * What the placeholder is standing in for.
+ *
+ * - `line` — a run of text. Sized off the type scale, so a `md` line is exactly
+ *   as tall as the `md` type it will be replaced by.
+ * - `rect` — a block: an image, a chart, a card, a map.
+ * - `circle` — an avatar, or anything else round.
+ */
+export type PlSkeletonShape = 'line' | 'rect' | 'circle';
+export interface PlSkeletonProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'color'> {
+    /** @default 'line' */
+    shape?: PlSkeletonShape;
+    /**
+     * How many lines to draw, for `shape="line"`. The last one is drawn short, the
+     * way the last line of a paragraph is, so a block of them reads as prose
+     * rather than as a barcode. Ignored by the other two shapes.
+     * @default 1
+     */
+    lines?: number;
+    /**
+     * The scale of the thing being stood in for: the type scale for a `line`, the
+     * diameter for a `circle`, the default block height for a `rect`.
+     * @default 'md'
+     */
+    size?: PlassSize;
+    /**
+     * Colour family. `secondary` by default, and it is worth leaving there: a
+     * placeholder that carries a semantic colour is saying something about content
+     * that has not arrived yet.
+     * @default 'secondary'
+     */
+    color?: PlassColor;
+    /** An explicit width. Numbers are pixels. */
+    width?: number | string;
+    /** An explicit height. Numbers are pixels. */
+    height?: number | string;
+    /**
+     * The travelling highlight. Turn it off for a page holding dozens of them, or
+     * where the wait is expected to be long enough that motion becomes noise.
+     *
+     * A reduced-motion preference already replaces the sweep with a colour pulse
+     * without being asked, so this is not the accessibility switch.
+     * @default true
+     */
+    animated?: boolean;
+    /**
+     * What a screen reader is told, if anything.
+     *
+     * Unset — the default — the placeholder is `aria-hidden`, because a dozen
+     * boxes each announcing themselves is worse than silence. Give the *one*
+     * skeleton that stands for the whole region a label and it becomes a live
+     * `status` instead.
+     */
+    label?: string;
+    /** Renders something other than a `<div>`. Base UI's own escape hatch. */
+    render?: useRender.RenderProp;
+}
+/**
+ * The shape of something that has not loaded yet.
+ *
+ * It reserves the space the real thing will take, which is the whole job: a card
+ * that grows by 200px when its image arrives has moved everything below it while
+ * somebody was reading. A spinner cannot do that.
+ *
+ * The three shapes are the three things a layout is made of — a run of text, a
+ * block and a circle — and each is sized off the ladder the real component uses,
+ * so a `md` line is as tall as `md` type and a `md` circle is exactly a
+ * `PlAvatar` at `md`.
+ */
+export declare const PlSkeleton: React.ForwardRefExoticComponent<PlSkeletonProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/skeleton/PlSkeleton.js

@@ -0,0 +1,142 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { controlHeightClasses, controlSquareClasses, surfaceSlots } from '../../internal/styles.js';
+/**
+ * A line's height is the type scale itself — the same lengths
+ * `sheetBodyClasses` sets as a font size — so a placeholder occupies the em box
+ * of the text that replaces it. The leading around it is `lineGapClasses`, and
+ * the two together add up to that ladder's line box.
+ */
+const lineHeightClasses = {
+    xs: 'h-[0.6875rem]',
+    sm: 'h-[0.75rem]',
+    md: 'h-[0.8125rem]',
+    lg: 'h-[0.9375rem]',
+    xl: 'h-[1.0625rem]'
+};
+/** The leading: the body ladder's line box less the bar drawn in it. */
+const lineGapClasses = {
+    xs: 'gap-[0.3125rem]',
+    sm: 'gap-[0.375rem]',
+    md: 'gap-[0.5625rem]',
+    lg: 'gap-[0.5625rem]',
+    xl: 'gap-[0.6875rem]'
+};
+/**
+ * A bar's corner, at ~45% of its own height — held just short of the 50% that
+ * would make it a capsule.
+ *
+ * Not `radiusClasses`, which is ~30% of a *control's* height: 12px on a 13px bar
+ * is a capsule and a half. Not `tickRadiusClasses` either, which is sized
+ * against a box rather than against a run of text.
+ */
+const barRadiusClasses = {
+    xs: 'rounded-[0.3125rem]',
+    sm: 'rounded-[0.3125rem]',
+    md: 'rounded-[0.375rem]',
+    lg: 'rounded-[0.4375rem]',
+    xl: 'rounded-[0.5rem]'
+};
+/**
+ * What a `rect` is as tall as when nothing says otherwise: a thumbnail. Anything
+ * else wants `height`, and most uses of this shape pass one.
+ */
+const blockHeightClasses = {
+    xs: 'h-12',
+    sm: 'h-16',
+    md: 'h-20',
+    lg: 'h-28',
+    xl: 'h-36'
+};
+/** A block's corner is the sheet ladder, because a block stands for a sheet. */
+const blockRadiusClasses = {
+    xs: 'rounded-(--plass-radius-xs)',
+    sm: 'rounded-(--plass-radius-sm)',
+    md: 'rounded-(--plass-radius-md)',
+    lg: 'rounded-(--plass-radius-lg)',
+    xl: 'rounded-(--plass-radius-xl)'
+};
+/**
+ * The surface, and it is deliberately **not** glass.
+ *
+ * Every other sheet in the library is translucent over a blurred backdrop,
+ * because it is a thing sitting on the page. A skeleton is the opposite: it is
+ * the shape of something that is not there yet, so it is a flat tint and nothing
+ * else — no blur, no hairline, no gloss, no shadow. It also keeps a page of
+ * thirty placeholders from asking for thirty backdrop filters.
+ */
+const fillClasses = 'relative overflow-hidden bg-(--p-soft-hover)';
+/** Pixels for a bare number, and whatever was written for a string. */
+function length(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return typeof value === 'number' ? `${value}px` : value;
+}
+/**
+ * The shape of something that has not loaded yet.
+ *
+ * It reserves the space the real thing will take, which is the whole job: a card
+ * that grows by 200px when its image arrives has moved everything below it while
+ * somebody was reading. A spinner cannot do that.
+ *
+ * The three shapes are the three things a layout is made of — a run of text, a
+ * block and a circle — and each is sized off the ladder the real component uses,
+ * so a `md` line is as tall as `md` type and a `md` circle is exactly a
+ * `PlAvatar` at `md`.
+ */
+export const PlSkeleton = /* @__PURE__ */ React.forwardRef(function PlSkeleton({ shape = 'line', lines = 1, size = 'md', color = 'secondary', width, height, animated = true, label, render, className, style, ...props }, ref) {
+    // The sweep lives in `styles.css` rather than in an arbitrary variant for the
+    // reason `.plass-glow` does: a keyframe is not a Tailwind variant, so there is
+    // nothing to express one with.
+    const sweep = animated ? 'plass-skeleton' : '';
+    const shapeClasses = shape === 'circle'
+        ? `shrink-0 rounded-full ${controlHeightClasses[size]} ${controlSquareClasses[size]}`
+        : shape === 'rect'
+            ? `w-full ${blockRadiusClasses[size]} ${height === undefined ? blockHeightClasses[size] : ''}`
+            : `w-full ${barRadiusClasses[size]} ${lineHeightClasses[size]}`;
+    // Unlabelled it is scenery and says nothing; labelled it is the one element
+    // that reports the wait for the region around it.
+    const announce = label
+        ? { role: 'status', 'aria-busy': true, 'aria-label': label }
+        : { 'aria-hidden': true };
+    // A run of lines is a stack of bars rather than one box, so the gaps between
+    // them are real gaps: text has leading, and a striped gradient would not
+    // survive a caller putting the block in a flex row. The root then holds only
+    // the stacking, which is why it drops the fill and the sweep.
+    const stacked = shape === 'line' && lines > 1;
+    return useRender({
+        render,
+        ref,
+        props: {
+            className: (stacked
+                ? ['flex w-full flex-col', lineGapClasses[size], className ?? '']
+                : [fillClasses, sweep, shapeClasses, className ?? ''])
+                .filter(Boolean)
+                .join(' '),
+            style: {
+                ...surfaceSlots(color, 0),
+                width: length(width),
+                height: length(height),
+                ...style
+            },
+            ...announce,
+            ...(stacked
+                ? {
+                    children: Array.from({ length: lines }, (_, index) => (_jsx("div", { className: [
+                            fillClasses,
+                            sweep,
+                            barRadiusClasses[size],
+                            lineHeightClasses[size],
+                            // The last line of a paragraph does not reach the margin.
+                            index === lines - 1 ? 'w-3/5' : 'w-full'
+                        ]
+                            .filter(Boolean)
+                            .join(' ') }, index)))
+                }
+                : null),
+            ...props
+        }
+    });
+});

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

@@ -0,0 +1,2 @@
+export { PlSkeleton } from './PlSkeleton.js';
+export type { PlSkeletonProps, PlSkeletonShape } from './PlSkeleton.js';

package/dist/components/skeleton/index.js

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