plass-ui 0.0.1 → 1.0.0

package/dist/components/text-field/PlTextField.js

@@ -0,0 +1,126 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { Field } from '@base-ui/react/field';
+import { Input } from '@base-ui/react/input';
+import { Spinner } from '../../internal/icons.js';
+import { controlHeightClasses, controlTextLeadingClasses, disabledClasses, fieldReadOnlyClasses, fieldRestClasses, focusWithinRingClasses, gapClasses, hasContent, iconClasses, metaTextClasses, paddingXClasses, radiusClasses, stackGapClasses, surfaceSlots, transitionClasses } from '../../internal/styles.js';
+/**
+ * Type scale and radius, shared by both modes. The line height is explicit here
+ * rather than `leading-none` as on PlButton, because in multiline mode it is what
+ * decides the height of a row — and it has to agree with the single-line
+ * heights below or a one-row textarea would not line up with an input.
+ */
+const sizeClasses = {
+    xs: `${gapClasses.xs} ${radiusClasses.xs} ${controlTextLeadingClasses.xs}`,
+    sm: `${gapClasses.sm} ${radiusClasses.sm} ${controlTextLeadingClasses.sm}`,
+    md: `${gapClasses.md} ${radiusClasses.md} ${controlTextLeadingClasses.md}`,
+    lg: `${gapClasses.lg} ${radiusClasses.lg} ${controlTextLeadingClasses.lg}`,
+    xl: `${gapClasses.xl} ${radiusClasses.xl} ${controlTextLeadingClasses.xl}`
+};
+/**
+ * Multiline cannot use a fixed height — `rows` decides it. Instead the vertical
+ * padding is `(height - border - line-height) / 2`, which makes a one-row
+ * textarea exactly as tall as the single-line field of the same size. The
+ * `min-h-*` catches the variants that carry no border.
+ *
+ * These are keyed by `size` and never by `density`: density is horizontal
+ * padding only, and letting it touch this would make the same `rows` produce
+ * two different heights.
+ */
+const multilineClasses = {
+    xs: 'min-h-6 py-[3px]',
+    sm: 'min-h-8 py-[6px]',
+    md: 'min-h-10 py-[9px]',
+    lg: 'min-h-12 py-[11px]',
+    xl: 'min-h-14 py-[13px]'
+};
+const resizeClasses = {
+    none: 'resize-none',
+    vertical: 'resize-y',
+    horizontal: 'resize-x',
+    both: 'resize'
+};
+const shellBaseClasses = /* @__PURE__ */ [
+    // `group` so the adornments can answer the control's focus; `cursor-text`
+    // because the whole shell behaves as the field, padding included.
+    'group relative flex w-full cursor-text',
+    '[-webkit-tap-highlight-color:transparent]',
+    transitionClasses,
+    // The ring belongs to the shell, not to the control inside it, so it traces
+    // the glass edge rather than a rectangle floating inside it.
+    focusWithinRingClasses,
+    iconClasses
+].join(' ');
+/**
+ * The shell, the read-only treatment and the disabled treatment are the ones
+ * `internal/styles` defines for every field-shaped control — a Select's trigger
+ * is drawn on exactly the same box, and the two have to be indistinguishable.
+ */
+const restClasses = fieldRestClasses;
+const readOnlyClasses = fieldReadOnlyClasses;
+export const PlTextField = /* @__PURE__ */ React.forwardRef(function PlTextField({ variant = 'glass', size = 'md', color = 'primary', density = 'default', elevation = 0, multiline = false, rows = 3, resize = 'vertical', label, description, error, invalid, startIcon, endIcon, loading = false, fullWidth = false, readOnly = false, disabled = false, type = 'text', 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,
+    // the caret and the message all turn over together and no state needs its own
+    // set of tokens.
+    const family = isInvalid ? 'danger' : color;
+    const controlRef = React.useRef(null);
+    const setControlRef = React.useCallback((node) => {
+        controlRef.current = node;
+        if (typeof ref === 'function') {
+            ref(node);
+        }
+        else if (ref) {
+            ref.current = node;
+        }
+    }, [ref]);
+    const shellClasses = [
+        shellBaseClasses,
+        sizeClasses[size],
+        multiline
+            ? `${multilineClasses[size]} items-start`
+            : `${controlHeightClasses[size]} items-center`,
+        paddingXClasses[density][size],
+        // An if/else rather than stacked `data-*` variants: two Tailwind variants
+        // of equal specificity resolve by their order in the generated stylesheet.
+        disabled ? disabledClasses[variant] : readOnly ? readOnlyClasses[variant] : restClasses[variant]
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const controlClasses = [
+        'min-w-0 flex-1 bg-transparent [font:inherit] text-inherit',
+        // Not `outline-none`: that utility zeroes `--tw-outline-style`, and the
+        // shell's focus ring is drawn with the same variable family. The shorthand
+        // takes the outline off this element and leaves the ring alone.
+        '[outline:none]',
+        'placeholder:text-(--plass-muted-fg)',
+        'caret-(--p-accent) selection:bg-(--p-soft-press)',
+        'disabled:cursor-not-allowed',
+        multiline ? `block ${resizeClasses[resize]}` : 'self-stretch'
+    ].join(' ');
+    // `1lh` keeps an adornment centred on the first line rather than on the whole
+    // box, which is the only way it stays put when the control grows to 5 rows.
+    const adornmentClasses = 'inline-flex h-[1lh] shrink-0 items-center text-(--plass-muted-fg) transition-[color] duration-(--plass-duration) group-focus-within:text-(--p-accent)';
+    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 }, children: [label ? (_jsx(Field.Label, { className: [
+                    metaTextClasses[size],
+                    'font-semibold',
+                    disabled ? 'text-(--plass-muted-fg)' : 'text-(--plass-fg)'
+                ].join(' '), children: label })) : null, _jsxs("span", { className: shellClasses, onPointerDown: (event) => {
+                    // Clicking the shell's own padding should put the caret in the field,
+                    // the way clicking anywhere inside a native input does. Only when the
+                    // shell itself was hit — a click on the control or on an adornment is
+                    // left alone so text selection still works.
+                    if (event.target === event.currentTarget && !disabled) {
+                        event.preventDefault();
+                        controlRef.current?.focus();
+                    }
+                }, children: [startIcon ? _jsx("span", { className: adornmentClasses, children: startIcon }) : null, _jsx(Input, { ref: setControlRef, className: controlClasses, disabled: disabled, readOnly: readOnly, "aria-busy": loading || undefined, "data-loading": loading || undefined, ...(multiline ? { render: _jsx("textarea", { rows: rows }) } : { type }), ...props }), loading ? (_jsx("span", { className: adornmentClasses, children: _jsx(Spinner, {}) })) : endIcon ? (_jsx("span", { className: adornmentClasses, children: endIcon })) : null] }), description ? (_jsx(Field.Description, { className: [metaTextClasses[size], 'text-(--plass-muted-fg)'].join(' '), children: description })) : null, hasError ? (_jsx(Field.Error, { match: true, className: [metaTextClasses[size], 'text-(--p-accent)'].join(' '), children: error })) : null] }));
+});

package/dist/components/text-field/index.d.ts

@@ -1,2 +1,2 @@
-export { TextField } from './TextField';
-export type { TextFieldProps, TextFieldResize } from './TextField';
+export { PlTextField } from './PlTextField.js';
+export type { PlTextFieldProps, PlTextFieldResize } from './PlTextField.js';

package/dist/components/text-field/index.js

@@ -1 +1 @@
-export{TextField}from"./TextField";
+export { PlTextField } from './PlTextField.js';

package/dist/components/text-link/PlTextLink.d.ts

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassColor, PlassSize } from '../../types.js';
+/**
+ * When the line under a link is drawn.
+ *
+ * `always` is the default, and the reason is `color`: a link takes no colour
+ * family unless one is asked for, so with the line off there would be nothing
+ * at all distinguishing it from the sentence it sits in. That is also why this
+ * is not a boolean — "no underline" is a real choice for a link in a nav bar or
+ * a footer, where position already says what it is, and it should have to be
+ * spelled out rather than fallen into.
+ */
+export type PlTextLinkUnderline = 'always' | 'hover' | 'none';
+export interface PlTextLinkProps extends Omit<React.ComponentPropsWithoutRef<'a'>, 'color'> {
+    /** Where the link goes. */
+    href: string;
+    /**
+     * When the underline is drawn.
+     * @default 'always'
+     */
+    underline?: PlTextLinkUnderline;
+    /**
+     * Semantic colour role. Unlike every control in the library this has **no
+     * default** — a link in a paragraph is usually the paragraph's own colour
+     * with a line under it, and a component that arrived pre-dyed is one a page
+     * has to undo.
+     */
+    color?: PlassColor;
+    /**
+     * The type scale. Also no default: a link inside a sentence is the size of
+     * the sentence. Set it for a link that stands on its own.
+     */
+    size?: PlassSize;
+    /**
+     * Opens the link in a new tab, with the `rel` that keeps the new page from
+     * reaching back into this one.
+     *
+     * A window changing under the reader is the one thing about a link that
+     * cannot be seen before it happens, so this also turns `icon` on by default
+     * and adds a line for a screen reader.
+     * @default false
+     */
+    newTab?: boolean;
+    /**
+     * The mark after the label. `true` draws the arrow leaving its box when
+     * `newTab` is on and the chain otherwise, `false` draws nothing, and a node
+     * of your own replaces the glyph.
+     *
+     * Left out, it follows `newTab`.
+     */
+    icon?: React.ReactNode | boolean;
+    /**
+     * What a screen reader hears after the label on a `newTab` link. Never drawn.
+     * @default '(opens in a new tab)'
+     */
+    newTabLabel?: string;
+    /**
+     * Renders something other than an `<a>` — the `Link` a router brings, most of
+     * the time. `href` still goes through, so `render={<NextLink href="…" />}`
+     * needs it written once, on the `PlTextLink`.
+     */
+    render?: useRender.RenderProp;
+    /** The label. */
+    children?: React.ReactNode;
+}
+/**
+ * A link, in a sentence or on its own.
+ *
+ * Everything about it is deliberately smaller than a PlButton. It has no
+ * surface, no height of its own and no colour unless asked — what it has is a
+ * line under it, which is the one mark a reader already knows means "this goes
+ * somewhere".
+ *
+ * The three things it does that a bare `<a>` does not: it draws that line on a
+ * schedule (`always`, or only under the pointer), it marks a link that opens a
+ * new tab both visibly and for a screen reader, and it takes `render`, so the
+ * `Link` a router brings can wear all of it.
+ */
+export declare const PlTextLink: React.ForwardRefExoticComponent<PlTextLinkProps & React.RefAttributes<HTMLAnchorElement>>;

package/dist/components/text-link/PlTextLink.js

@@ -0,0 +1,136 @@
+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 { ExternalLinkIcon, LinkIcon } from '../../internal/icons.js';
+import { controlTextLeadingClasses, focusRingClasses, srOnlyClasses } from '../../internal/styles.js';
+/**
+ * Whether the line is drawn, and — with the colour below — the only two things
+ * about a link that a prop changes. Everything else about the line is in
+ * `styles.css`, under `.plass-link`.
+ *
+ * Every utility here is written through `[&.plass-link]`, which doubles the
+ * component's own class into the selector and takes it to two classes. That is
+ * not decoration: `<a>` is, with `<td>`, one of the two tags a host stylesheet
+ * still styles by name — `.prose a`, `.vp-doc a`, every CSS framework — and all
+ * of those are a class plus a type, which outranks a plain utility. A link that
+ * lost its colour and its line inside a `.prose` block would have lost the only
+ * two things it is.
+ *
+ * Hover deliberately leaves the *text* colour alone. A link inside running
+ * prose that changes colour under the pointer drags the reader's eye off the
+ * line they were reading — the same rule the library applies to a control's
+ * label, on the one component that lives inside a sentence.
+ */
+const underlineClasses = {
+    always: '[&.plass-link]:underline',
+    hover: '[&.plass-link]:no-underline [&.plass-link]:hover:underline',
+    // Nothing to hover, on purpose. A link with no line and no colour is a link
+    // whose surroundings are saying what it is.
+    none: '[&.plass-link]:no-underline'
+};
+/**
+ * Only two properties move, so this is written out rather than taken from
+ * `transitionClasses` — the house list has no `text-decoration-color` in it,
+ * and adding one there would put a property on every control in the library
+ * that no control draws.
+ */
+const transition = /* @__PURE__ */ [
+    '[transition-property:color,text-decoration-color]',
+    '[transition-duration:var(--plass-duration)]',
+    '[transition-timing-function:var(--plass-ease)]'
+].join(' ');
+const baseClasses = /* @__PURE__ */ [
+    // Both a style hook and the specificity. `styles.css` doubles this class to
+    // write the parts of the line that never vary — its thickness, its offset,
+    // its colour — above whatever the host page says about an `<a>`, and every
+    // utility that *does* vary is written through it for the same reason.
+    'plass-link',
+    'cursor-pointer',
+    // The glyph rides on the label at just under its cap height, rather than at
+    // the `1.2em` an icon inside a control takes: this one sits in a sentence,
+    // and an icon as tall as the line spaces the words around it apart.
+    '[&_svg]:pointer-events-none [&_svg]:inline [&_svg]:size-[0.95em] [&_svg]:shrink-0',
+    transition,
+    focusRingClasses,
+    'focus-visible:rounded-[0.25rem]'
+].join(' ');
+/**
+ * A link, in a sentence or on its own.
+ *
+ * Everything about it is deliberately smaller than a PlButton. It has no
+ * surface, no height of its own and no colour unless asked — what it has is a
+ * line under it, which is the one mark a reader already knows means "this goes
+ * somewhere".
+ *
+ * The three things it does that a bare `<a>` does not: it draws that line on a
+ * schedule (`always`, or only under the pointer), it marks a link that opens a
+ * new tab both visibly and for a screen reader, and it takes `render`, so the
+ * `Link` a router brings can wear all of it.
+ */
+export const PlTextLink = /* @__PURE__ */ React.forwardRef(function PlTextLink({ href, underline = 'always', color, size, newTab = false, icon, newTabLabel = '(opens in a new tab)', render, className, style, children, ...props }, ref) {
+    // `icon` left out follows `newTab`, which is the whole reason it is not a
+    // plain boolean with a `false` default: a link that takes over the window
+    // should say so, and a caller should have to ask for the silent version.
+    const mark = icon ?? newTab;
+    const glyph = mark === true ? newTab ? _jsx(ExternalLinkIcon, {}) : _jsx(LinkIcon, {}) : mark;
+    const classNames = [
+        baseClasses,
+        size ? controlTextLeadingClasses[size] : '',
+        underlineClasses[underline],
+        color ? '[&.plass-link]:text-(--p-accent)' : '[&.plass-link]:text-inherit',
+        className ?? ''
+    ]
+        .filter(Boolean)
+        .join(' ');
+    /*
+     * The two line colours and the focus ring, as slots.
+     *
+     * `--p-ring` is set even when no family was asked for, because the ring is
+     * written as the `outline` shorthand and an undefined `var()` inside it
+     * makes the browser drop the whole declaration — an uncoloured link would
+     * lose its focus ring entirely rather than fall back to something plainer.
+     *
+     * The line rests at 45% of whatever the text is and goes to the full colour
+     * on hover, so it works the same on an inherited colour as on an accent one.
+     */
+    const slots = {
+        '--p-underline': 'color-mix(in oklab, currentColor 45%, transparent)',
+        '--p-underline-hover': 'currentColor',
+        '--p-ring': `var(--plass-${color ?? 'primary'}-ring)`,
+        ...(color ? { '--p-accent': `var(--plass-${color}-accent)` } : null)
+    };
+    /*
+     * `rel` is the one thing here a caller's own value is merged with rather
+     * than replaced by, and the reason is that the two purposes of the
+     * attribute have nothing to do with each other.
+     *
+     * `noopener` is what stops the new page reaching back through
+     * `window.opener`; `noreferrer` sits beside it for the browsers that still
+     * need the pair. The common reason to write a `rel` by hand is `nofollow`
+     * or `sponsored`, which is an SEO decision — and spelled as a plain
+     * override it would silently take the protection off a link that still
+     * opens in a new tab. Whatever was asked for is kept, with the two tokens
+     * added if they are not already there.
+     */
+    const { rel: askedFor, ...rest } = props;
+    const rel = newTab
+        ? [
+            ...new Set([...(askedFor ?? '').split(/\s+/).filter(Boolean), 'noopener', 'noreferrer'])
+        ].join(' ')
+        : askedFor;
+    return useRender({
+        render: render ?? _jsx("a", {}),
+        ref,
+        props: {
+            href,
+            target: newTab ? '_blank' : undefined,
+            className: classNames,
+            style: { ...slots, ...style },
+            children: (_jsxs(_Fragment, { children: [children, glyph ? _jsx("span", { className: "ms-[0.25em]", children: glyph }) : null, newTab ? (_jsxs(_Fragment, { children: [' ', _jsx("span", { className: srOnlyClasses, children: newTabLabel })] })) : null] })),
+            ...rest,
+            // After the spread on purpose: this is the merge above, not an override
+            // for a caller to win.
+            rel
+        }
+    });
+});

package/dist/components/text-link/index.d.ts

@@ -0,0 +1,2 @@
+export { PlTextLink } from './PlTextLink.js';
+export type { PlTextLinkProps, PlTextLinkUnderline } from './PlTextLink.js';

package/dist/components/text-link/index.js

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

package/dist/components/time-picker/PlTimePicker.d.ts

@@ -0,0 +1,88 @@
+import * as React from 'react';
+import { type PlassPickerLabels, type TimeUnit } from '../../internal/calendar.js';
+import { type PlassPickerShellProps } from '../../internal/picker.js';
+/**
+ * Which column of the clock a row belongs to. Re-exported so a caller writing a
+ * `shouldDisableTime` rule can name the argument it is handed.
+ */
+export type { TimeUnit };
+export interface PlTimePickerProps extends PlassPickerShellProps {
+    /** The chosen time. A `Date`, so it carries a day as well — see `referenceDate`. */
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onValueChange?: (value: Date | null) => void;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * The day a chosen time is written onto while there is no value yet.
+     * @default today
+     */
+    referenceDate?: Date;
+    /** The earliest time of day that may be chosen. Only the clock is read. */
+    minTime?: Date | null;
+    /** The latest time of day that may be chosen. */
+    maxTime?: Date | null;
+    /**
+     * Blocks individual rows. Called once per row per column with the instant that
+     * row would produce and the column it is in, so a rule may be as coarse as
+     * "no afternoons" or as fine as one minute.
+     */
+    shouldDisableTime?: (value: Date, unit: TimeUnit) => boolean;
+    /** A 12-hour dial with an AM/PM column. Defaults to whatever the locale does. */
+    hour12?: boolean;
+    /** Adds the seconds column. @default false */
+    showSeconds?: boolean;
+    /** How far apart the rows of each column are. @default 1 */
+    hourStep?: number;
+    minuteStep?: number;
+    secondStep?: number;
+    /**
+     * BCP 47 tag deciding whether the clock is on a 12-hour dial, what AM and PM
+     * are called, and how the trigger writes the time. Defaults to the browser's.
+     */
+    locale?: string;
+    /**
+     * How the trigger writes the chosen time. Passed straight to `Intl`.
+     * @default { hour: 'numeric', minute: '2-digit' }, plus seconds when shown
+     */
+    format?: Intl.DateTimeFormatOptions;
+    /** Shown in the trigger while nothing is chosen. */
+    placeholder?: React.ReactNode;
+    /** Offers the × that empties the control. @default false */
+    clearable?: boolean;
+    /** Offers the shortcut to the current time in the footer. @default true */
+    showNowButton?: boolean;
+    /**
+     * Closes the popup as soon as any column is touched. `false` by default and
+     * unlike `PlDatePicker`, because a time is two answers and closing after the
+     * first one would make choosing 9:30 a matter of opening the popup twice.
+     * @default false
+     */
+    closeOnSelect?: boolean;
+    /** The strings the picker says. Every one has an English default. */
+    labels?: Partial<PlassPickerLabels>;
+    /** Identifies the field when a form is submitted, as `HH:MM` (`HH:MM:SS`). */
+    name?: string;
+}
+/**
+ * A time of day, chosen from columns.
+ *
+ * Columns because they are the shape that answers what a time picker is actually
+ * asked: "half past nine" is two glances, and "any time at all, on the hour" is
+ * a column you never touch. A clock face is prettier and needs a `transform` to
+ * read, which this library does not have.
+ *
+ * The bounds are checked at the granularity of the column being drawn, which is
+ * the detail that separates a working time picker from a frustrating one. With a
+ * `minTime` of 09:30 the hour `9` stays available — the hour *contains* allowed
+ * minutes — and it is the minute column that greys out `00` through `25`. The
+ * naive check compares the whole candidate instant, hides the 9 entirely, and
+ * makes half past nine unreachable.
+ *
+ * The value is a `Date` rather than a string or a number of minutes, because
+ * everything else in this library that carries a moment is one, and because a
+ * time on its own has nowhere to record that it crossed a DST boundary.
+ * `referenceDate` is the day a bare time is written onto.
+ */
+export declare const PlTimePicker: React.ForwardRefExoticComponent<PlTimePickerProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/time-picker/PlTimePicker.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { PlButton } from '../button/PlButton.js';
+import { TimeGrid, usePickerLabels } from '../../internal/calendar.js';
+import { ClockIcon } from '../../internal/icons.js';
+import { PickerFooter, PickerShell } from '../../internal/picker.js';
+import { displaySamples, formatDate, isHour12, isValidDate, secondsOfDay, timeUnitSpan, toISOTime, withPlaceholder, withTime } from '../../internal/date.js';
+import { cx } from '../../internal/styles.js';
+/**
+ * A time of day, chosen from columns.
+ *
+ * Columns because they are the shape that answers what a time picker is actually
+ * asked: "half past nine" is two glances, and "any time at all, on the hour" is
+ * a column you never touch. A clock face is prettier and needs a `transform` to
+ * read, which this library does not have.
+ *
+ * The bounds are checked at the granularity of the column being drawn, which is
+ * the detail that separates a working time picker from a frustrating one. With a
+ * `minTime` of 09:30 the hour `9` stays available — the hour *contains* allowed
+ * minutes — and it is the minute column that greys out `00` through `25`. The
+ * naive check compares the whole candidate instant, hides the 9 entirely, and
+ * makes half past nine unreachable.
+ *
+ * The value is a `Date` rather than a string or a number of minutes, because
+ * everything else in this library that carries a moment is one, and because a
+ * time on its own has nowhere to record that it crossed a DST boundary.
+ * `referenceDate` is the day a bare time is written onto.
+ */
+export const PlTimePicker = /* @__PURE__ */ React.forwardRef(function PlTimePicker({ value: valueProp, defaultValue, onValueChange, open: openProp, defaultOpen, onOpenChange, referenceDate, minTime, maxTime, shouldDisableTime, hour12: hour12Prop, showSeconds = false, hourStep = 1, minuteStep = 1, secondStep = 1, locale, format, placeholder, clearable = false, showNowButton = true, closeOnSelect = false, labels: labelOverrides, name, size = 'md', color = 'primary', density = 'default', readOnly = false, disabled = false, startIcon, ...shell }, ref) {
+    const labels = usePickerLabels(labelOverrides);
+    const hour12 = hour12Prop ?? isHour12(locale);
+    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue ?? null);
+    const value = valueProp !== undefined ? valueProp : uncontrolledValue;
+    const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen ?? false);
+    const open = openProp ?? uncontrolledOpen;
+    // Held still for as long as the picker is mounted, so a popup left open
+    // across midnight does not quietly move the value it is writing onto a new
+    // day.
+    const [fallbackDay] = React.useState(() => referenceDate ?? new Date());
+    const setOpen = (next) => {
+        if (next && (readOnly || disabled)) {
+            return;
+        }
+        if (openProp === undefined) {
+            setUncontrolledOpen(next);
+        }
+        onOpenChange?.(next);
+    };
+    const commit = (next) => {
+        if (valueProp === undefined) {
+            setUncontrolledValue(next);
+        }
+        onValueChange?.(next);
+    };
+    const isBlocked = React.useCallback((candidate, unit) => {
+        const [from, to] = timeUnitSpan(unit, candidate);
+        if (isValidDate(minTime) && to < secondsOfDay(minTime)) {
+            return true;
+        }
+        if (isValidDate(maxTime) && from > secondsOfDay(maxTime)) {
+            return true;
+        }
+        return shouldDisableTime?.(candidate, unit) ?? false;
+    }, [minTime, maxTime, shouldDisableTime]);
+    /* Memoised because `samples` below is keyed on it, and the fallback is a
+       fresh object every render — which is the case that runs by default, since
+       `format` is optional. Left bare, the sizer re-formatted all twenty-four
+       sample instants on every render the picker saw. */
+    const displayFormat = React.useMemo(() => format ?? {
+        hour: 'numeric',
+        minute: '2-digit',
+        ...(showSeconds ? { second: '2-digit' } : {})
+    }, [format, showSeconds]);
+    const now = new Date();
+    const nowValue = withTime(referenceDate ?? fallbackDay, {
+        hours: now.getHours(),
+        minutes: now.getMinutes(),
+        seconds: showSeconds ? now.getSeconds() : 0
+    });
+    const hasFooter = showNowButton || clearable || !closeOnSelect;
+    // Holds the trigger open at the width of the longest time it could show.
+    const samples = React.useMemo(() => withPlaceholder(displaySamples(locale, displayFormat), placeholder), [locale, displayFormat, placeholder]);
+    return (_jsx(PickerShell, { ...shell, size: size, color: color, density: density, readOnly: readOnly, disabled: disabled, triggerRef: ref, startIcon: startIcon ?? _jsx(ClockIcon, {}), display: isValidDate(value) ? formatDate(value, locale, displayFormat) : (placeholder ?? ''), samples: samples, empty: !isValidDate(value), clearable: clearable, onClear: () => commit(null), open: open, onOpenChange: setOpen, labels: labels, hiddenValues: name
+            ? [{ name, value: isValidDate(value) ? toISOTime(value, showSeconds) : '' }]
+            : undefined, children: _jsxs("div", { className: cx('flex flex-col', hasFooter && 'gap-1.5'), children: [_jsx(TimeGrid, { size: size, density: density, locale: locale, value: isValidDate(value) ? value : null, referenceDate: referenceDate ?? fallbackDay, onChange: (next) => {
+                        commit(next);
+                        if (closeOnSelect) {
+                            setOpen(false);
+                        }
+                    }, hour12: hour12, showSeconds: showSeconds, hourStep: hourStep, minuteStep: minuteStep, secondStep: secondStep, shouldDisableTime: isBlocked, labels: labels, autoFocus: true }), hasFooter ? (_jsxs(PickerFooter, { size: size, children: [clearable ? (_jsx(PlButton, { variant: "ghost", size: size, color: color, density: "compact", onClick: () => {
+                                commit(null);
+                                setOpen(false);
+                            }, children: labels.clear })) : null, showNowButton ? (_jsx(PlButton, { variant: "ghost", size: size, color: color, density: "compact", disabled: isBlocked(nowValue, 'second'), onClick: () => {
+                                commit(nowValue);
+                                setOpen(false);
+                            }, children: labels.now })) : null, !closeOnSelect ? (_jsx(PlButton, { variant: "solid", size: size, color: color, density: "compact", onClick: () => setOpen(false), children: labels.done })) : null] })) : null] }) }));
+});

package/dist/components/time-picker/index.d.ts

@@ -0,0 +1,2 @@
+export { PlTimePicker } from './PlTimePicker.js';
+export type { PlTimePickerProps, TimeUnit } from './PlTimePicker.js';

package/dist/components/time-picker/index.js

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

package/dist/components/timeline/PlTimeline.d.ts

@@ -0,0 +1,98 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassColor, PlassDensity, PlassOrientation, PlassSize } from '../../types.js';
+/**
+ * How far along one item is.
+ *
+ * Three states rather than two, because "the one you are on" is not the same
+ * claim as "done", and a sequence that cannot say which step is current is a
+ * list. Each gets its own axis — a filled bullet, a filled bullet with a halo
+ * around it, an empty one — rather than three shades of the same thing.
+ */
+export type PlTimelineStatus = 'complete' | 'current' | 'upcoming';
+/** How the line between two items is drawn. `none` leaves the gap open. */
+export type PlTimelineConnector = 'solid' | 'dashed' | 'dotted' | 'none';
+export interface PlTimelineProps extends Omit<React.ComponentPropsWithoutRef<'ol'>, 'color'> {
+    /**
+     * How far the sequence has got: the index of the item being worked on now.
+     * Everything before it is complete, everything after it is still to come.
+     *
+     * An index rather than a value, because a timeline has no selection — nothing
+     * here is chosen, and the only question is how far down the list reality has
+     * reached. Omit it and every item is `upcoming` unless it says otherwise; pass
+     * the item count to mark the whole sequence done.
+     */
+    active?: number;
+    /** @default 'md' */
+    size?: PlassSize;
+    /** @default 'primary' */
+    color?: PlassColor;
+    /** Spacing between items. Never the type scale, never the bullet. */
+    density?: PlassDensity;
+    /**
+     * Which way the sequence runs. `vertical` is the default and the one that
+     * takes an arbitrary number of steps with an arbitrary amount to say about
+     * each; `horizontal` is the stepper across the top of a checkout, and it is
+     * only honest while every label is short.
+     * @default 'vertical'
+     */
+    orientation?: PlassOrientation;
+    /** Renders something other than an `<ol>` — Base UI's own escape hatch. */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+export interface PlTimelineItemProps extends Omit<React.ComponentPropsWithoutRef<'li'>, 'color' | 'title'> {
+    /** The heading of this step. */
+    title?: React.ReactNode;
+    /**
+     * When it happened — a date, a duration, a name. Set beside the title on a
+     * wide item and under it on a narrow one.
+     */
+    meta?: React.ReactNode;
+    /**
+     * What goes inside the bullet: a number, an icon, an avatar. Omit it and the
+     * bullet is a plain disc, which is what a step with nothing to say about
+     * itself should be.
+     */
+    bullet?: React.ReactNode;
+    /**
+     * Overrides what the timeline's `active` would have computed for this item — a
+     * step that failed and stopped the sequence, a step that was skipped.
+     */
+    status?: PlTimelineStatus;
+    /** Overrides the timeline's colour family for this item alone. */
+    color?: PlassColor;
+    /**
+     * How the line to the next item is drawn.
+     * @default 'solid'
+     */
+    connector?: PlTimelineConnector;
+    /** The body of the step. */
+    children?: React.ReactNode;
+}
+/**
+ * One step.
+ *
+ * Its index is not a prop and cannot be: an item that had to be told where it
+ * was in the list would be an item every caller could put in the wrong place,
+ * and `active={2}` would stop meaning anything. The `PlTimeline` numbers its
+ * children as it walks them, and hands each one its index through a context.
+ */
+export declare const PlTimelineItem: React.ForwardRefExoticComponent<PlTimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+/**
+ * A sequence of steps, in the order they happen in.
+ *
+ * There is no Base UI primitive under this and there should not be: a timeline
+ * has no selection, no roving focus and no keyboard contract — it is a list, and
+ * reaching for a composite primitive to draw one would hand every consumer's
+ * record of events the semantics of a widget.
+ *
+ * It is an `<ol>` for the reason it exists at all: the order *is* the content. A
+ * screen reader announcing "list of 5 items" over an unordered list would be
+ * describing something else.
+ *
+ * The children are numbered here rather than by a prop on each item, so `active`
+ * has something to count against and inserting a step in the middle does not
+ * mean renumbering the ones after it.
+ */
+export declare const PlTimeline: React.ForwardRefExoticComponent<PlTimelineProps & React.RefAttributes<HTMLOListElement>>;