material-plus-ui 0.0.1 → 1.0.0

package/dist/internal/Picker.d.ts

@@ -0,0 +1,110 @@
+import * as React from 'react';
+import type { MPPickerLabels } from './Calendar';
+import type { MPColor, MPSize, MPStyleProps } from '../types';
+/**
+ * The props a picker takes from its shell rather than inventing.
+ *
+ * Written out here rather than left to `MPStyleProps` alone because these are
+ * the rows a reader of the docs is actually looking at — every one of the four
+ * pickers lists them, and they mean the same thing on all four.
+ */
+export interface MPPickerShellProps extends MPStyleProps {
+    /**
+     * Which accent family the popup reads: the chosen day's fill, the band across
+     * a range, today's outline, the footer's confirm button.
+     * @default 'primary'
+     */
+    color?: MPColor;
+    /**
+     * Label in the outline's notch. Always drawn there rather than floating over
+     * the value, so a picker with a label and one without sit at the same height
+     * in a form.
+     */
+    label?: React.ReactNode;
+    /** The line under the control. Replaced by `errorMessage` when there is one. */
+    description?: React.ReactNode;
+    /**
+     * The message under the control. Its presence is also what puts the picker
+     * into its error state — there is no separate `error` boolean, so there is no
+     * way to render a control that is visibly wrong with no explanation of why.
+     */
+    errorMessage?: React.ReactNode;
+    /** Content placed before the value. Defaults to the picker's own glyph. */
+    startIcon?: React.ReactNode;
+    /** Marks the picker required, both to assistive technology and to the label. */
+    required?: boolean;
+    /** Greys the picker out and stops it opening. */
+    disabled?: boolean;
+    /**
+     * Shows the value without allowing it to be changed, and stays focusable.
+     *
+     * The popup does not open either. What a read-only picker holds is something
+     * to read, and a calendar whose every cell was inert would be a menu of
+     * nothing.
+     */
+    readOnly?: boolean;
+    /**
+     * The id put on the trigger and pointed at by the label. Derived from `name`
+     * when omitted, and generated when there is no name either.
+     */
+    id?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+interface InternalShellProps extends MPPickerShellProps {
+    /** Which component this is, for the class hook and the generated id. */
+    slug: string;
+    /** What the trigger reads. A placeholder when `empty`. */
+    display: React.ReactNode;
+    /**
+     * Every string the display could hold, so the trigger stops changing width
+     * with its value. `displaySamples` in `internal/date` produces them and
+     * `MPWidthSizer` is what lays them out.
+     */
+    samples?: string[];
+    /** Nothing has been chosen yet, so the display is muted. */
+    empty: boolean;
+    /** Offers the × that empties the control. */
+    clearable?: boolean;
+    onClear: () => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    labels: MPPickerLabels;
+    /** `<input type="hidden">` rows, so the control submits with a form. */
+    hiddenValues?: Array<{
+        name: string;
+        value: string;
+    }>;
+    name?: string;
+    children: React.ReactNode;
+    triggerRef?: React.Ref<HTMLButtonElement>;
+}
+/**
+ * A trigger, a label, the line of text under it, and a popup.
+ *
+ * Everything about it that is visible is a decision already made elsewhere: the
+ * notched outline, the label in the notch, the supporting text, the disabled
+ * treatment, and the popup's `surface-container` at elevation 2 — which is the
+ * same floating sheet a menu and a select's list are drawn on.
+ */
+export declare function MPPickerShell({ slug, size, color, fullWidth, label, description, errorMessage, startIcon, required, disabled, readOnly, id, className, style, display, samples, empty, clearable, onClear, open, onOpenChange, labels, hiddenValues, name, children, triggerRef }: InternalShellProps): React.JSX.Element;
+/**
+ * The row of shortcuts under a picker's panel.
+ *
+ * A hairline above it rather than a gap, because the actions act on the panel
+ * and a gap would read as a second popup stacked under the first.
+ */
+export declare function MPPickerFooter({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The vertical hairline between a calendar and the clock beside it. */
+export declare function MPPickerDivider(): React.JSX.Element;
+/**
+ * What a picker's footer buttons are drawn at.
+ *
+ * The same rung the calendar's header uses, for the same reason: a `md` picker's
+ * footer sitting at the control ladder's 56px would be taller than two rows of
+ * the calendar above it.
+ */
+export declare const FOOTER_SIZE: Record<MPSize, MPSize>;
+export {};

package/dist/internal/Picker.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as r}from"react/jsx-runtime";import*as i from"react";import{Field as t}from"@base-ui/react/field";import{Popover as n}from"@base-ui/react/popover";import{MPIcon as a}from"../components/icon/MPIcon";import{CloseIcon as o}from"../constants/icons";import{accentSlots as l}from"./accent";import{MPFieldLabel as s,MPFieldOutline as p}from"./FieldOutline";import{MPStateLayer as c}from"./StateLayer";import{MPSupportingText as m}from"./SupportingText";import{MPWidthSizer as d}from"./WidthSizer";import{CONTROL_ICON as u,hasContent as f,PROSE_TEXT as h}from"./scale";import{FADE as x,PORTAL_LAYER as g}from"./surface";const b={xs:{padding:"px-2",height:"h-8"},sm:{padding:"px-3",height:"h-10"},md:{padding:"px-4",height:"h-14"},lg:{padding:"px-4",height:"h-16"},xl:{padding:"px-5",height:"h-18"}},v={xs:"p-1.5",sm:"p-2",md:"p-2.5",lg:"p-3",xl:"p-3.5"};export function MPPickerShell({slug:y,size:N="md",color:j="primary",fullWidth:P=!1,label:w,description:O,errorMessage:z,startIcon:M,required:k=!1,disabled:F=!1,readOnly:S=!1,id:B,className:C,style:I,display:R,samples:$,empty:q,clearable:T=!1,onClear:_,open:E,onOpenChange:W,labels:D,hiddenValues:L,name:V,children:Z,triggerRef:A}){const G=f(z),H=b[N],J=i.useId(),K=B??`mp-${y}-${V??J}`,Q=T&&!q&&!(F||S);return r(t.Root,{disabled:F,invalid:G,"data-mp-size":N,className:[`mp-${y} group flex-col align-top`,P?"flex w-full":"inline-flex w-fit",C??""].filter(Boolean).join(" "),style:{...l(j),...I},children:[r(n.Root,{open:E,onOpenChange:W,children:[r("div",{className:"relative w-full",children:[r(n.Trigger,{id:K,ref:A,disabled:F,nativeButton:!0,className:["relative flex w-full items-center gap-2 select-none","appearance-none bg-transparent font-[inherit] outline-none",H.padding,Q?"pe-10":"",H.height,h[N],F?"text-mp-on-surface/38 cursor-default":"text-mp-on-surface "+(S?"cursor-default":"cursor-pointer")].filter(Boolean).join(" "),children:[M?e("span",{className:["flex shrink-0 items-center",F?"text-mp-on-surface/38":"text-mp-on-surface-variant"].join(" "),children:M}):null,r("span",{className:"flex min-w-0 flex-1 flex-col",children:[e("span",{className:["w-full truncate text-start",q&&!F?"text-mp-on-surface-variant":""].filter(Boolean).join(" "),children:R}),e(d,{samples:$??[]})]})]}),Q?r("button",{type:"button","aria-label":D.clear,onClick:_,className:["group/clear rounded-mp-full text-mp-on-surface-variant absolute inset-y-0","end-1 my-auto flex size-8 cursor-pointer items-center justify-center","appearance-none border-0 bg-transparent font-[inherit]","outline-mp-secondary focus-visible:outline-2 focus-visible:outline-offset-1","focus-visible:outline-solid outline-none"].join(" "),children:[e(c,{className:"group-hover/clear:opacity-8 group-focus-visible/clear:opacity-10"}),e(a,{icon:o,size:u[N]})]}):null,e(p,{label:w,required:k}),f(w)?e(s,{size:N,label:w,required:k,htmlFor:K}):null]}),e(n.Portal,{children:e(n.Positioner,{className:g,sideOffset:4,align:"start",children:e(n.Popup,{initialFocus:!1,className:[`mp-${y}__popup rounded-mp-md shadow-mp-2 bg-mp-surface-container`,"text-mp-on-surface outline-none",v[N],h[N],x].join(" "),children:Z})})})]}),e(m,{description:O,errorMessage:z,className:H.padding}),L?.map((r,i)=>e("input",{type:"hidden",name:r.name,value:r.value},i))]})}export function MPPickerFooter({children:r}){return e("div",{className:"border-mp-outline-variant flex items-center justify-end gap-1 border-t pt-1.5",children:r})}export function MPPickerDivider(){return e("div",{"aria-hidden":"true",className:"bg-mp-outline-variant w-px self-stretch"})}export const FOOTER_SIZE={xs:"xs",sm:"xs",md:"sm",lg:"sm",xl:"md"};

package/dist/internal/StateLayer.d.ts

@@ -0,0 +1,45 @@
+import * as React from 'react';
+/**
+ * Material's state layer.
+ *
+ * MD3 does not express hover, focus and press as three more colours. It puts a
+ * translucent wash of the *content* colour over the container — 8% hovered, 10%
+ * focused or pressed — so one rule covers a filled button, an outlined one and a
+ * bare text one without any of them naming a second background.
+ *
+ * That is the whole reason this is an element rather than a `hover:bg-…` on the
+ * control itself. A background can only be replaced, and replacing it is what
+ * makes a text button's hover state opaque and an outlined button's hover state
+ * cover its own border. A layer composites instead, so whatever was underneath —
+ * a fill, a hairline, nothing at all — is still there under the wash.
+ *
+ * `bg-current` is what makes it one rule: the layer takes the colour of the
+ * label it sits behind, which is already the right ink for the surface. A caller
+ * that needs a different one sets `text-…` on the layer.
+ *
+ * ## How it is wired
+ *
+ * The control carries `group` and `relative`; this carries `group-hover:` and
+ * friends. It cannot key off its own `:hover` because it covers the control and
+ * has to be `pointer-events-none` for clicks to reach it — and an element that
+ * takes no pointer events is never hovered.
+ *
+ * `rounded-[inherit]` rather than a radius of its own: the layer is the control's
+ * shape, and a pill with a square wash in it is worse than no wash.
+ *
+ * ## `layer` replaces the appearance rather than adding to it
+ *
+ * The shape and the colour arrive as one string because a tick's layer is
+ * neither. MD3 draws it as a 40dp circle *around* an 18dp box, in `on-surface`
+ * rather than in the ink — which for a ticked checkbox is white, and a white
+ * halo is not a state. Appending those classes to the defaults would leave two
+ * `background-color` declarations of equal specificity fighting, and which one
+ * wins is decided by their order in the generated stylesheet. So the caller
+ * replaces the set rather than adding to it, and only the opacity ladder — the
+ * part that is genuinely the same everywhere — is fixed here.
+ */
+export declare function MPStateLayer({ layer, className }: {
+    /** Shape, position and colour. Replaces the defaults; it does not extend them. */
+    layer?: string;
+    className?: string;
+}): React.JSX.Element;

package/dist/internal/StateLayer.js

@@ -0,0 +1 @@
+import{jsx as o}from"react/jsx-runtime";export function MPStateLayer({layer:t="inset-0 rounded-[inherit] bg-current",className:a}){return o("span",{"aria-hidden":"true",className:["pointer-events-none absolute opacity-0",t,"transition-opacity duration-(--mp-sys-motion-duration-short4)","group-hover:opacity-8","group-active:opacity-10","group-focus-visible:opacity-10","group-disabled:opacity-0 group-data-disabled:opacity-0",a??""].filter(Boolean).join(" ")})}

package/dist/internal/SupportingText.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+/**
+ * The line under a control.
+ *
+ * Material calls it supporting text and gives it one slot, not two — which is
+ * why this renders *either* the description or the error rather than stacking
+ * them. An error is not additional information about a field, it is the field's
+ * current problem, and pushing the description down a line to make room leaves
+ * the reader reading a sentence that has just stopped applying.
+ *
+ * Both parts come from Base UI's `Field`, so whichever one is showing is wired
+ * to the control by `aria-describedby` without anybody generating an id.
+ * `Field.Error` needs `match` because it normally waits for the browser's own
+ * validity state; here the message's presence *is* the state, which is the same
+ * bargain `MPTextField.errorMessage` makes — there is no way to render a control
+ * that is visibly wrong with no explanation of why.
+ */
+export declare function MPSupportingText({ description, errorMessage, className }: {
+    description?: React.ReactNode;
+    errorMessage?: React.ReactNode;
+    /** Whatever inset lines the text up with the control it belongs to. */
+    className?: string;
+}): React.JSX.Element | null;

package/dist/internal/SupportingText.js

@@ -0,0 +1 @@
+import{jsx as r}from"react/jsx-runtime";import{Field as e}from"@base-ui/react/field";import{META_TEXT as t,hasContent as o}from"./scale";export function MPSupportingText({description:a,errorMessage:s,className:i}){const n=["mp-supporting-text block",t,"data-disabled:text-mp-on-surface/38",i??""].filter(Boolean).join(" ");return o(s)?r(e.Error,{match:!0,className:`${n} text-mp-error`,children:s}):o(a)?r(e.Description,{className:`${n} text-mp-on-surface-variant`,children:a}):null}

package/dist/internal/WidthSizer.d.ts

@@ -0,0 +1,31 @@
+import type * as React from 'react';
+/**
+ * Holds a control open at the width of the widest thing it could ever say.
+ *
+ * A control that is not `fullWidth` is sized by what it is *currently* saying,
+ * which for anything whose value changes means the box changes with it. A date
+ * picker on the 1st is a dozen pixels narrower than the same picker on the 28th,
+ * and `Sep` is wider than `May`. Either way the field moves under the pointer
+ * that just used it, and the whole row of controls beside it shuffles along.
+ *
+ * So the alternatives are laid out too, stacked in a box clipped to no height.
+ * The control's intrinsic width becomes the widest of them and stops depending
+ * on the value.
+ *
+ * Three things it deliberately is not:
+ *
+ * - **Not `hidden`, and not `display: none`.** Both take the box out of layout,
+ *   and a box that is not laid out reserves nothing.
+ * - **Not read out.** `aria-hidden`, or a screen reader would announce every
+ *   date the control might hold before the one it does.
+ * - **Not text.** A sample is drawn as generated content off a data attribute
+ *   rather than as a text node. `content: attr(…)` lays out exactly like text,
+ *   so it reserves the same width — but it leaves nothing for `getByText` or a
+ *   browser's find-in-page to trip over, so a caller's test asking for the date
+ *   they chose keeps finding one element rather than two.
+ */
+export declare function MPWidthSizer({ samples }: {
+    samples: readonly string[];
+}): React.JSX.Element | null;
+/** The props a component hands over when it wants one of these. */
+export type MPWidthSizerProps = React.ComponentProps<typeof MPWidthSizer>;

package/dist/internal/WidthSizer.js

@@ -0,0 +1 @@
+import{jsx as e}from"react/jsx-runtime";export function MPWidthSizer({samples:a}){return 0===a.length?null:e("span",{"aria-hidden":"true",className:"invisible h-0 min-h-0 overflow-hidden",children:a.map((a,n)=>e("span",{"data-sample":a,className:"block whitespace-nowrap before:content-[attr(data-sample)]"},`${n}:${a}`))})}

package/dist/internal/accent.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The `color` prop, made available to a stylesheet.
+ *
+ * `color="tertiary"` has to reach a `background-color`, and there is no way for
+ * it to do that through a class name: Tailwind finds classes by scanning source
+ * text, so `bg-mp-${color}` generates nothing at all. The alternative — a table
+ * of every variant crossed with every colour, written out — is twenty literal
+ * strings per component that all say the same thing.
+ *
+ * So the family is a *value* rather than a name. Four custom properties are set
+ * on the component's root and the classes read those, which means one set of
+ * classes covers all four families and the ladder of roles inside each of them
+ * stays intact: `filled` is always the accent under its own ink, whichever accent
+ * that turns out to be.
+ *
+ * The names are `--_mp-*` because they are private, in the same sense the derived
+ * colours in `styles.css` are: read by components, not a name to set. What a
+ * consumer sets is the *role* — `--mp-sys-color-tertiary` — and it arrives here
+ * on its own, because these are indirections through the role rather than copies
+ * of its value.
+ *
+ * ## Why an inline style rather than a class
+ *
+ * A custom property's `var()` references are substituted at the element the
+ * property is declared on. Declaring these on the component's own root is what
+ * makes the substitution happen *there* — so a family set on a wrapper, or a
+ * source colour scoped to a section, is what the component resolves against.
+ */
+import type * as React from 'react';
+import type { MPColor } from '../types';
+/**
+ * The four roles an accent family has, pointed at one of the four families.
+ *
+ * `error` is a family like any other here. That is deliberate: a destructive
+ * button and a primary one differ only in which palette they read, and a
+ * component that special-cased the error colour would need a second code path
+ * for the one case that most needs to look like all the others.
+ */
+export declare function accentSlots(color: MPColor): React.CSSProperties;

package/dist/internal/accent.js

@@ -0,0 +1 @@
+export function accentSlots(n){return{"--_mp-accent":`var(--_mp-color-${n})`,"--_mp-on-accent":`var(--_mp-color-on-${n})`,"--_mp-accent-container":`var(--_mp-color-${n}-container)`,"--_mp-on-accent-container":`var(--_mp-color-on-${n}-container)`}}

package/dist/internal/button-group.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a button inherits from the group around it.
+ *
+ * Its own module rather than a file `MPButtonGroup` exports, because both sides
+ * import it: the group provides the context and the button reads it. Putting it
+ * in either component would make one of them import the other, and a `<Button>`
+ * that pulls in a `<ButtonGroup>` nobody used is dead weight in every bundle.
+ *
+ * Every field is optional and every one of them may legitimately be `undefined`.
+ * A button reads the group as a *fallback*, so "not set on the group" has to keep
+ * meaning "use the button's own default" rather than turning into one.
+ */
+import * as React from 'react';
+import type { MPColor, MPSize, MPVariant } from '../types';
+export interface MPButtonGroupContextValue {
+    variant?: MPVariant;
+    size?: MPSize;
+    color?: MPColor;
+    disabled?: boolean;
+}
+export declare const MPButtonGroupContext: React.Context<MPButtonGroupContextValue | null>;

package/dist/internal/button-group.js

@@ -0,0 +1 @@
+import*as t from"react";export const MPButtonGroupContext=t.createContext(null);

package/dist/internal/color.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Colour arithmetic, written out rather than installed.
+ *
+ * `MPColorPicker` is the only component in the library that has to *compute* a
+ * colour rather than name one, and the whole of what it needs is here: three
+ * representations, the conversions between them, one parser and one formatter.
+ * It is a hundred lines of arithmetic, which is the entire reason the package
+ * still has one runtime dependency.
+ *
+ * Two decisions worth knowing before reading:
+ *
+ * - **HSV is the model the panel is drawn in, and it never leaves.** A
+ *   saturation/value square with a hue rail beside it *is* HSV, so the picker
+ *   keeps its state that way and converts on the way out. Round-tripping through
+ *   RGB instead would lose the hue of every greyscale colour — black is `#000` at
+ *   every hue — and the rail would jump to red the moment the pointer reached a
+ *   corner.
+ * - **`alpha` is 0–1, everything else is what CSS says it is.** `h` is degrees,
+ *   `s`/`v`/`l` are percentages, `r`/`g`/`b` are 0–255. Nothing here invents a
+ *   normalised unit, because every one of these numbers is eventually written
+ *   into a string a human reads.
+ *
+ * ## Why this is not OKLCh, when the token sheet is
+ *
+ * `styles.css` derives the scheme in OKLCh because it is generating *related*
+ * colours, and a perceptual space is what makes "the same lightness" mean the
+ * same thing across hues. A picker is not generating anything. It is showing a
+ * reader a square and asking them to point at a colour, and the square every
+ * design tool draws — saturation across, brightness down — is HSV. Drawing it in
+ * a perceptual space would give a square with unreachable corners.
+ *
+ * Nothing here is exported from `src/index.ts`. It is the library talking to
+ * itself, in the sense `internal/` always means.
+ */
+/** 0–255 per channel, the way a hex triplet and `rgb()` both spell it. */
+export interface MPRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** `h` in degrees, `s` and `v` as percentages. The panel's own model. */
+export interface MPHsv {
+    h: number;
+    s: number;
+    v: number;
+}
+/** `h` in degrees, `s` and `l` as percentages. Only ever an output format. */
+export interface MPHsl {
+    h: number;
+    s: number;
+    l: number;
+}
+/** A colour and how much of it there is. `alpha` is 0–1. */
+export interface MPColorValue {
+    hsv: MPHsv;
+    alpha: number;
+}
+/** The three ways the picker will write a colour back out. */
+export type MPColorFormat = 'hex' | 'rgb' | 'hsl';
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function hsvToRgb({ h, s, v }: MPHsv): MPRgb;
+export declare function rgbToHsv({ r, g, b }: MPRgb): MPHsv;
+export declare function rgbToHsl({ r, g, b }: MPRgb): MPHsl;
+export declare function hslToRgb({ h, s, l }: MPHsl): MPRgb;
+/**
+ * A CSS colour string, or `null` if it is not one this understands.
+ *
+ * Hex in all four lengths, `rgb()`/`rgba()` and `hsl()`/`hsla()` in both the
+ * comma and the space syntax. Named colours and `color()` are deliberately out:
+ * a picker has to be able to write every value it can read, and there is no
+ * honest way back from `rebeccapurple` to a point on the panel.
+ */
+export declare function parseColor(input: string): MPColorValue | null;
+export declare function rgbToHex({ r, g, b }: MPRgb, alpha?: number): string;
+/**
+ * The value the component hands back, in whichever notation was asked for.
+ *
+ * `hex` drops the alpha pair when the colour is opaque, and the two functional
+ * forms drop the fourth argument for the same reason — a caller who never turned
+ * `alpha` on should never see `rgba(…, 1)` come out of a control they only used
+ * three channels of.
+ */
+export declare function formatColor(hsv: MPHsv, alpha: number, format: MPColorFormat): string;
+/** A plain `rgb()` for the swatches and rails, where alpha is drawn separately. */
+export declare function cssColor(hsv: MPHsv, alpha?: number): string;
+/**
+ * Black or white, whichever can be read on top of this colour.
+ *
+ * The tick on a chosen swatch is the only thing the picker draws *on* an
+ * arbitrary colour, and a fixed white tick disappears on yellow. The threshold
+ * is relative luminance rather than plain lightness, because the eye weighs green
+ * about six times as heavily as blue and a colour model that pretends otherwise
+ * puts the tick the wrong way round on both.
+ */
+export declare function readableInk(hsv: MPHsv): string;
+/**
+ * The swatches a picker shows when it was given none.
+ *
+ * Deliberately not the library's own four accent families: those are *roles* —
+ * `primary` means "the most important thing on this screen" — and a picker is
+ * being asked for a colour, not for a meaning. Offering the scheme here would
+ * also be offering four colours that change under the reader when somebody edits
+ * `--mp-source-color`, which is not what a tag colour should do.
+ *
+ * So this is a plain spectrum plus the greys: the row somebody reaches for when
+ * they are labelling a calendar, a tag or a project, which is what a colour
+ * picker in an application is nearly always for.
+ */
+export declare const DEFAULT_SWATCHES: readonly string[];
+/**
+ * The chequerboard behind a translucent colour, as a background shorthand.
+ *
+ * Two conic gradients would be one declaration fewer, but a chequer drawn with
+ * conic gradients has a seam down the middle of every tile at a fractional device
+ * pixel ratio. Four linear stops at 45° do not.
+ *
+ * It reads `--mp-sys-color-outline-variant`'s computed value through the same
+ * `--_mp-*` indirection everything else does, so the chequer follows the scheme
+ * rather than being a fixed grey that vanishes in dark mode.
+ */
+export declare const CHECKER_BACKGROUND: {
+    readonly backgroundImage: "linear-gradient(45deg, var(--_mp-color-outline-variant) 25%, transparent 25%), linear-gradient(-45deg, var(--_mp-color-outline-variant) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, var(--_mp-color-outline-variant) 75%), linear-gradient(-45deg, transparent 75%, var(--_mp-color-outline-variant) 75%)";
+    readonly backgroundSize: "8px 8px";
+    readonly backgroundPosition: "0 0, 0 4px, 4px -4px, -4px 0";
+};

package/dist/internal/color.js

@@ -0,0 +1 @@
+export function clamp(r,t,n){return r<t?t:r>n?n:r}function r(r){const t=r%360;return t<0?t+360:t}export function hsvToRgb({h:t,s:n,v:o}){const e=r(t)/60,a=clamp(n,0,100)/100,s=clamp(o,0,100)/100,c=s*a,l=c*(1-Math.abs(e%2-1)),u=s-c,i=Math.floor(e)%6,[g,h,f]=[[c,l,0],[l,c,0],[0,c,l],[0,l,c],[l,0,c],[c,0,l]][i];return{r:Math.round(255*(g+u)),g:Math.round(255*(h+u)),b:Math.round(255*(f+u))}}export function rgbToHsv({r:t,g:n,b:o}){const e=clamp(t,0,255)/255,a=clamp(n,0,255)/255,s=clamp(o,0,255)/255,c=Math.max(e,a,s),l=c-Math.min(e,a,s);let u=0;return 0!==l&&(u=c===e?(a-s)/l%6:c===a?(s-e)/l+2:(e-a)/l+4),{h:r(60*u),s:0===c?0:l/c*100,v:100*c}}export function rgbToHsl({r:r,g:t,b:n}){const{h:o,s:e,v:a}=rgbToHsv({r:r,g:t,b:n}),s=a/100,c=s*(1-e/100/2),l=Math.min(c,1-c);return{h:o,s:0===l?0:(s-c)/l*100,l:100*c}}export function hslToRgb({h:r,s:t,l:n}){const o=clamp(n,0,100)/100,e=o+clamp(t,0,100)/100*Math.min(o,1-o);return hsvToRgb({h:r,s:0===e?0:2*(1-o/e)*100,v:100*e})}const t=/^#?([0-9a-f]{3,8})$/i;export function parseColor(r){const n=r.trim().toLowerCase();if(!n)return null;if(n.startsWith("#")||t.test(n))return function(r){const n=t.exec(r.trim());if(!n)return null;const o=n[1],e=3===o.length||4===o.length?[...o].map(r=>r+r).join(""):o;if(6!==e.length&&8!==e.length)return null;const a=r=>parseInt(e.slice(2*r,2*r+2),16);return{hsv:rgbToHsv({r:a(0),g:a(1),b:a(2)}),alpha:8===e.length?a(3)/255:1}}(n);const o=/^(rgba?|hsla?)\((.*)\)$/.exec(n);if(!o)return null;const[,e,a]=o,s=function(r){return r.match(/-?[\d.]+%?/g)??[]}(a),c=s.map(r=>parseFloat(r));if(c.length<3||c.some(Number.isNaN))return null;const l=function(r,t){return t.length<=3?1:clamp(r[3]?.endsWith("%")?t[3]/100:t[3],0,1)}(s,c);return e.startsWith("rgb")?{hsv:rgbToHsv({r:c[0],g:c[1],b:c[2]}),alpha:l}:{hsv:rgbToHsv(hslToRgb({h:c[0],s:c[1],l:c[2]})),alpha:l}}function n(r){return clamp(Math.round(r),0,255).toString(16).padStart(2,"0")}export function rgbToHex({r:r,g:t,b:o},e=1){const a=`#${n(r)}${n(t)}${n(o)}`;return e>=1?a:`${a}${n(255*e)}`}function o(r){return String(Math.round(100*clamp(r,0,1))/100)}export function formatColor(r,t,n){const e=hsvToRgb(r);if("hex"===n)return rgbToHex(e,t);if("rgb"===n){const r=`${e.r}, ${e.g}, ${e.b}`;return t>=1?`rgb(${r})`:`rgba(${r}, ${o(t)})`}const{h:a,s:s,l:c}=rgbToHsl(e),l=`${Math.round(a)}, ${Math.round(s)}%, ${Math.round(c)}%`;return t>=1?`hsl(${l})`:`hsla(${l}, ${o(t)})`}export function cssColor(r,t=1){const{r:n,g:e,b:a}=hsvToRgb(r);return t>=1?`rgb(${n}, ${e}, ${a})`:`rgba(${n}, ${e}, ${a}, ${o(t)})`}export function readableInk(r){const{r:t,g:n,b:o}=hsvToRgb(r),e=r=>{const t=r/255;return t<=.03928?t/12.92:((t+.055)/1.055)**2.4};return.2126*e(t)+.7152*e(n)+.0722*e(o)>.42?"#000000":"#ffffff"}export const DEFAULT_SWATCHES=["#000000","#4b5563","#9ca3af","#ffffff","#ef4444","#f97316","#f59e0b","#84cc16","#22c55e","#14b8a6","#06b6d4","#3b82f6","#6366f1","#8b5cf6","#d946ef","#ec4899"];export const CHECKER_BACKGROUND={backgroundImage:"linear-gradient(45deg, var(--_mp-color-outline-variant) 25%, transparent 25%), linear-gradient(-45deg, var(--_mp-color-outline-variant) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, var(--_mp-color-outline-variant) 75%), linear-gradient(-45deg, transparent 75%, var(--_mp-color-outline-variant) 75%)",backgroundSize:"8px 8px",backgroundPosition:"0 0, 0 4px, 4px -4px, -4px 0"};

package/dist/internal/date.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The arithmetic and the naming the four pickers share.
+ *
+ * No date library under it, deliberately. This package has one runtime
+ * dependency and it is an icon set; a component library that quietly adds
+ * `date-fns` — or worse, picks a side in the dayjs/luxon/Temporal argument on
+ * its consumer's behalf — has made a decision that was not its to make.
+ * Everything here is either `Date` arithmetic, which is a dozen lines, or
+ * `Intl`, which the platform already ships and which knows more about month
+ * names in more languages than any bundled table ever will.
+ *
+ * Two rules hold everywhere below:
+ *
+ * - **Local time, always.** A calendar day is a thing a person is looking at on
+ *   a wall, not an instant on a line. `new Date(2026, 6, 27)` is midnight local
+ *   and every comparison here is made on the local Y/M/D triple, so a picker in
+ *   Seoul and a picker in São Paulo both light up the cell that says 27.
+ * - **Nothing is mutated.** `Date` is mutable and every method on it that sounds
+ *   like a question is actually a command. Each function here copies first, so a
+ *   `value` handed in by a caller is never the object that comes back out.
+ *
+ * Nothing here is exported from `src/index.ts`. It is the library talking to
+ * itself, in the sense `internal/` always means.
+ */
+import type { MPWeekday } from '../types';
+/** Which unit the calendar is currently letting you pick. */
+export type MPCalendarView = 'day' | 'month' | 'year';
+/** How many years one page of the year grid holds. Four columns of three. */
+export declare const YEAR_PAGE_SIZE = 12;
+/**
+ * A local midnight on the given Y/M/D, with out-of-range parts normalised —
+ * month `12` rolls into January, day `0` into the last day of the month before.
+ *
+ * Built through `setFullYear` rather than `new Date(year, month, day)` because
+ * the two-argument constructor maps years 0–99 onto 1900–1999. Nobody is going
+ * to pick a date in the year 47, but a component that silently rewrites the year
+ * it was handed is a component that will eventually be blamed for something
+ * else.
+ */
+export declare function makeDate(year: number, month: number, day: number): Date;
+/** Is this a `Date` that stands for a real instant? `new Date('nope')` is not. */
+export declare function isValidDate(value: unknown): value is Date;
+/** The same day with the clock wound back to midnight. */
+export declare function startOfDay(date: Date): Date;
+/** The first day of the month this date is in, at midnight. */
+export declare function startOfMonth(date: Date): Date;
+/** How many days a month has, leap years included. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Today, at midnight. The one place the pickers read the clock for a *date*. */
+export declare function today(): Date;
+export declare function addDays(date: Date, amount: number): Date;
+/**
+ * Months, with the day of the month clamped rather than allowed to overflow.
+ *
+ * 31 January plus one month is 28 February, not 3 March. The naive
+ * `setMonth(getMonth() + 1)` gives the second answer, which is why stepping a
+ * calendar forward from a 31st with it skips February entirely.
+ */
+export declare function addMonths(date: Date, amount: number): Date;
+export declare function addYears(date: Date, amount: number): Date;
+/** Negative, zero or positive, the way a sort comparator wants it. */
+export declare function compareDay(a: Date, b: Date): number;
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+export declare function isSameMonth(a: Date | null | undefined, b: Date | null | undefined): boolean;
+/**
+ * Is this calendar *day* outside the allowed span?
+ *
+ * Day-granular on purpose. A `maxDate` of 27 July at 09:00 still leaves the 27th
+ * pickable — the bound is about which days exist, and the time of day is the
+ * clock's problem. `MPDateTimePicker` re-checks at full precision once an hour
+ * has been chosen.
+ */
+export declare function isDayOutside(date: Date, min?: Date | null, max?: Date | null): boolean;
+/** Seconds since local midnight — what `minTime`/`maxTime` are compared on. */
+export declare function secondsOfDay(date: Date): number;
+/** Which column of a clock a candidate time is being offered for. */
+export type MPTimeUnit = 'hour' | 'minute' | 'second' | 'meridiem';
+/**
+ * The span of the day one row of one column covers, in seconds since midnight.
+ *
+ * This is the detail that separates a working time picker from a frustrating
+ * one. A bound has to be checked against the *span* a row stands for, not
+ * against one instant inside it: with a `minTime` of 09:30, the hour `9` covers
+ * 09:00:00–09:59:59, which overlaps what is allowed, so it stays available and
+ * the minute column is where `00` through `25` grey out. Comparing the whole
+ * candidate instead hides the 9 and makes half past nine unreachable.
+ */
+export declare function timeUnitSpan(unit: MPTimeUnit, at: Date): [number, number];
+/** The same instant with one or more clock fields replaced. */
+export declare function withTime(date: Date, parts: {
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}): Date;
+/** `date`'s calendar day wearing `time`'s clock. */
+export declare function mergeDateAndTime(date: Date, time: Date): Date;
+/**
+ * Six weeks of seven days, always — including the leading and trailing days that
+ * belong to the neighbouring months.
+ *
+ * Six rows whatever the month, and that is the whole point. A February that
+ * starts on a Sunday needs four rows and a 31-day month starting on a Saturday
+ * needs six; a grid that renders only the rows it needs is a grid that changes
+ * height when you step a month forward, moving every cell out from under the
+ * pointer that just pressed one.
+ */
+export declare function calendarWeeks(month: Date, weekStartsOn: MPWeekday): Date[][];
+/** The first year on the page a given year falls on. 2026 → 2016 at 12 a page. */
+export declare function yearPageStart(year: number): number;
+/** A memoised `Intl.DateTimeFormat`. `undefined` locale means the runtime's own. */
+export declare function dateFormatter(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+/** Formats a date, tolerating the `null` a cleared picker holds. */
+export declare function formatDate(date: Date | null | undefined, locale: string | undefined, options: Intl.DateTimeFormatOptions): string;
+/**
+ * Every distinct string those instants format to. Deduplicated, because a
+ * date-only format collapses twenty-four of them into a handful.
+ */
+export declare function displaySamples(locale: string | undefined, options: Intl.DateTimeFormatOptions): string[];
+/**
+ * The samples plus the placeholder, when the placeholder is a string.
+ *
+ * An empty picker shows the placeholder, which can easily be longer than any
+ * date — "Pick a departure date" against "3 Aug 2026" — and a trigger that
+ * shrinks the moment the first date is chosen is the same jump from the other
+ * direction. A `ReactNode` placeholder is left out: there is nothing to measure
+ * without rendering it twice.
+ */
+export declare function withPlaceholder(samples: string[], placeholder: unknown): string[];
+/**
+ * The three machine-readable spellings, for the hidden input that makes a picker
+ * submit with a form.
+ *
+ * Local, not UTC, and that is the whole point: `toISOString()` on a `Date`
+ * standing for 27 July in Seoul gives `2026-07-26T15:00:00Z`, and a form field
+ * that quietly reports the day before the one on screen is the single most
+ * expensive bug a date picker can ship. The shapes are the ones the native
+ * `<input type="date">`, `type="time"` and `type="datetime-local"` submit, so a
+ * server that already parses those needs no new code.
+ */
+export declare function toISODate(date: Date): string;
+export declare function toISOTime(date: Date, withSeconds?: boolean): string;
+export declare function toISODateTime(date: Date, withSeconds?: boolean): string;
+/**
+ * The seven column headers, rotated so the first one is `weekStartsOn`.
+ *
+ * `narrow` is what MD3's own calendar draws — one character per column, which is
+ * what keeps a 40dp cell a cell rather than a word. English narrow names collide
+ * (`S`, `M`, `T`, `W`, `T`, `F`, `S`), so the full name goes on the header's
+ * `aria-label` and a screen reader hears "Monday" rather than "M".
+ */
+export declare function weekdayLabels(locale: string | undefined, weekStartsOn: MPWeekday, weekday?: 'narrow' | 'short' | 'long'): string[];
+/** The twelve month names, January first, in the locale's own words. */
+export declare function monthLabels(locale: string | undefined, month?: 'short' | 'long'): string[];
+/**
+ * Does this locale write the month before the year?
+ *
+ * The calendar's header is two separate buttons — one that opens the month grid
+ * and one that opens the year grid — so it cannot just print what `Intl` gives
+ * it. Asking `formatToParts` which part came first is how the two buttons end up
+ * in the order the reader expects: `July 2026` in English, `2026년 7월` in
+ * Korean. Getting this wrong is subtle and reads as broken to exactly the people
+ * it is wrong for.
+ */
+export declare function isMonthBeforeYear(locale: string | undefined): boolean;
+/** Does this locale put a clock on a 12-hour dial? */
+export declare function isHour12(locale: string | undefined): boolean;
+/** What this locale calls AM and PM. */
+export declare function meridiemLabels(locale: string | undefined): [string, string];
+/**
+ * Which day the week starts on here — Sunday in the US and Korea, Monday across
+ * most of Europe, Saturday in much of the Middle East.
+ *
+ * `Intl.Locale`'s week info is the right source and is also the least evenly
+ * implemented corner of `Intl`: it is a getter in some engines, a method in
+ * others, and absent in the rest. All three are handled, and the fallback is
+ * Sunday rather than a throw — a calendar that renders starting on the wrong day
+ * is a small annoyance, and a calendar that renders nothing is not.
+ */
+export declare function localeWeekStart(locale: string | undefined): MPWeekday;

package/dist/internal/date.js

@@ -0,0 +1 @@
+export const YEAR_PAGE_SIZE=12;export function makeDate(t,e,r){const n=new Date(0);return n.setFullYear(t,e,r),n.setHours(0,0,0,0),n}export function isValidDate(t){return t instanceof Date&&!Number.isNaN(t.getTime())}export function startOfDay(t){const e=new Date(t.getTime());return e.setHours(0,0,0,0),e}export function startOfMonth(t){return makeDate(t.getFullYear(),t.getMonth(),1)}export function daysInMonth(t,e){return makeDate(t,e+1,0).getDate()}export function today(){return startOfDay(new Date)}export function addDays(t,e){const r=new Date(t.getTime());return r.setDate(r.getDate()+e),r}export function addMonths(t,e){const r=new Date(t.getTime()),n=makeDate(t.getFullYear(),t.getMonth()+e,1);return r.setFullYear(n.getFullYear(),n.getMonth(),Math.min(t.getDate(),daysInMonth(n.getFullYear(),n.getMonth()))),r}export function addYears(t,e){return addMonths(t,12*e)}export function compareDay(t,e){return startOfDay(t).getTime()-startOfDay(e).getTime()}export function isSameDay(t,e){return isValidDate(t)&&isValidDate(e)&&0===compareDay(t,e)}export function isSameMonth(t,e){return isValidDate(t)&&isValidDate(e)&&t.getFullYear()===e.getFullYear()&&t.getMonth()===e.getMonth()}export function isDayOutside(t,e,r){return!!(isValidDate(e)&&compareDay(t,e)<0)||isValidDate(r)&&compareDay(t,r)>0}export function secondsOfDay(t){return 3600*t.getHours()+60*t.getMinutes()+t.getSeconds()}export function timeUnitSpan(t,e){const r=secondsOfDay(e);if("hour"===t){const t=3600*Math.floor(r/3600);return[t,t+3599]}if("minute"===t){const t=60*Math.floor(r/60);return[t,t+59]}if("second"===t)return[r,r];const n=e.getHours()<12?0:43200;return[n,n+43200-1]}export function withTime(t,e){const r=new Date(t.getTime());return r.setHours(e.hours??r.getHours(),e.minutes??r.getMinutes(),e.seconds??r.getSeconds(),0),r}export function mergeDateAndTime(t,e){return withTime(startOfDay(t),{hours:e.getHours(),minutes:e.getMinutes(),seconds:e.getSeconds()})}export function calendarWeeks(t,e){const r=startOfMonth(t),n=(r.getDay()-e+7)%7,o=addDays(r,-n);return Array.from({length:6},(t,e)=>Array.from({length:7},(t,r)=>addDays(o,7*e+r)))}export function yearPageStart(t){return t-(t%12+12)%12}const t=new Map;export function dateFormatter(e,r){const n=`${e??""}\0${JSON.stringify(r)}`;let o=t.get(n);return o||(o=new Intl.DateTimeFormat(e,r),t.set(n,o)),o}export function formatDate(t,e,r){return isValidDate(t)?dateFormatter(e,r).format(t):""}const e=Array.from({length:24},(t,e)=>new Date(2027,e%12,21+e%7,e,58,58));export function displaySamples(t,r){const n=dateFormatter(t,r);return[...new Set(e.map(t=>n.format(t)))]}export function withPlaceholder(t,e){return"string"==typeof e&&""!==e?[...t,e]:t}export function toISODate(t){const e=t=>String(t).padStart(2,"0");return`${String(t.getFullYear()).padStart(4,"0")}-${e(t.getMonth()+1)}-${e(t.getDate())}`}export function toISOTime(t,e=!1){const r=t=>String(t).padStart(2,"0"),n=`${r(t.getHours())}:${r(t.getMinutes())}`;return e?`${n}:${r(t.getSeconds())}`:n}export function toISODateTime(t,e=!1){return`${toISODate(t)}T${toISOTime(t,e)}`}const r=makeDate(2021,7,1);export function weekdayLabels(t,e,n="narrow"){const o=dateFormatter(t,{weekday:n});return Array.from({length:7},(t,n)=>o.format(addDays(r,(e+n)%7)))}export function monthLabels(t,e="short"){const r=dateFormatter(t,{month:e});return Array.from({length:12},(t,e)=>r.format(makeDate(2021,e,1)))}export function isMonthBeforeYear(t){const e=dateFormatter(t,{year:"numeric",month:"long"}).formatToParts(r);return e.findIndex(t=>"month"===t.type)<e.findIndex(t=>"year"===t.type)}export function isHour12(t){const e=dateFormatter(t,{hour:"numeric"}).resolvedOptions();return e.hourCycle?"h11"===e.hourCycle||"h12"===e.hourCycle:!0===e.hour12}export function meridiemLabels(t){const e=dateFormatter(t,{hour:"numeric",hour12:!0}),n=t=>{const n=e.formatToParts(withTime(r,{hours:t})).find(t=>"dayPeriod"===t.type);return n?.value??(t<12?"AM":"PM")};return[n(9),n(21)]}export function localeWeekStart(t){try{const e=t??(new Intl.DateTimeFormat).resolvedOptions().locale,r=new Intl.Locale(e),n="function"==typeof r.getWeekInfo?r.getWeekInfo():r.weekInfo;if("number"==typeof n?.firstDay)return n.firstDay%7}catch{}return 0}