material-plus-ui 0.0.1 → 1.1.0

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/animate.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The machinery every `MPAnimate*` component runs on.
+ *
+ * It lives in `internal/` for the reason `menu.ts` and `button-group.ts` do:
+ * eleven components need it and none of them should have to import another.
+ *
+ * ## The shape of it
+ *
+ * Every effect is one `@keyframes` in `styles.css` running from a state written
+ * entirely in `--_mp-anim-*` custom properties to the element's natural one.
+ * Nothing here generates CSS: it fills slots, and the stylesheet decides what
+ * they mean. That is the same split `accentSlots()` makes for colour, for the
+ * same reason — Tailwind only ever sees class names that appear literally in
+ * the source, so a per-value class would not survive the first prop.
+ *
+ * Because the from-state is the *keyframe* rather than a second class, running
+ * an effect backwards is `animation-direction: reverse` and nothing else. That
+ * is what makes `mode="out"` free on all five of the effects that take one —
+ * the fade, the grow, the zoom, the slide and the rotate — and, as it happens,
+ * correct:
+ * CSS mirrors the timing function along with the keyframes, so an entrance
+ * eased on `emphasized-decelerate` comes out accelerating on the way back. The
+ * specification asks for exactly that pair, and the browser supplies it.
+ *
+ * ## Why the defaults are `var()` rather than numbers
+ *
+ * A duration nobody set resolves to `var(--mp-sys-motion-duration-medium4)`,
+ * not to `400ms`. Both would draw the same animation today; only one of them
+ * moves when a page retunes its motion tokens. Same rule as everywhere else in
+ * this library: the value a caller does not name is the *token*, so a theme can
+ * still reach it.
+ *
+ * ## What is deliberately not here
+ *
+ * An animation that has to know what its children *are* — a marquee that
+ * duplicates them, a headline that swaps between them, a typewriter that counts
+ * characters — cannot be a class name and a few numbers. Those are components,
+ * and their logic stays in their own files.
+ */
+import * as React from 'react';
+import type { MPAnimateMode, MPAnimateRepeat, MPAnimateTrigger, MPAnimation, MPEasing, MPSide } from '../types';
+/** The class that reads the slots. Always paired with one of the below. */
+export declare const ANIM_BASE = "mp-anim";
+/**
+ * Which keyframe an effect runs.
+ *
+ * `grow` and `zoom` share one: they are the same arithmetic at two strengths,
+ * and a second identical `@keyframes` would only be a second place to fix a
+ * bug. What separates them is their defaults and their origin, which is a
+ * property rather than a keyframe.
+ */
+export declare const ANIMATION_CLASS: Record<MPAnimation, string>;
+/** A curve, as the stylesheet spells it. */
+export declare function easingValue(easing: MPEasing): string;
+/**
+ * A duration, as the stylesheet spells it.
+ *
+ * A number is milliseconds and lands as milliseconds. Nothing at all lands as
+ * the effect's own Material token, so a page that retunes its motion moves this
+ * animation with it.
+ */
+export declare function durationValue(duration: number | undefined, effect: MPAnimation, mode?: MPAnimateMode): string;
+/** A number is pixels; a string is already a CSS length. */
+export declare function lengthValue(value: number | string): string;
+/** `'infinite'` reaches CSS as the word; a count reaches it as the number. */
+export declare function repeatValue(repeat: MPAnimateRepeat): string;
+export declare function isInfinite(repeat: MPAnimateRepeat | undefined): boolean;
+/**
+ * `normal`, `reverse`, `alternate`, `alternate-reverse` — the four CSS already
+ * has, assembled from the two props that mean something to a caller.
+ *
+ * `mode="out"` is a reversed run rather than a keyframe of its own, which is
+ * also why a reversed animation ends held on its own first frame: `fill-mode`
+ * is `both`, so a faded-out element stays faded out instead of snapping back.
+ */
+export declare function directionValue(mode: MPAnimateMode, alternate: boolean | undefined): string;
+export interface AnimationSlotOptions {
+    /** Which effect's tokens to fall back to, and which keyframe to run. */
+    effect: MPAnimation;
+    /** Milliseconds. Unset takes the effect's Material duration token. */
+    duration?: number;
+    /** Milliseconds. */
+    delay: number;
+    /** Unset takes the effect's Material easing token. */
+    easing?: MPEasing;
+    repeat: MPAnimateRepeat;
+    alternate?: boolean;
+    mode?: MPAnimateMode;
+    /** Where the animated properties start. Only the ones an effect reads. */
+    opacity?: number;
+    scale?: number;
+    x?: string;
+    y?: string;
+    angle?: string;
+    angleTo?: string;
+}
+/**
+ * The `--_mp-anim-*` slots, as an inline style object.
+ *
+ * Inline rather than utilities for the reason the accent slots are: these are
+ * per-instance numbers, and Tailwind cannot generate a class for a duration it
+ * has never seen written down.
+ */
+export declare function animationSlots(options: AnimationSlotOptions): React.CSSProperties;
+/**
+ * Which way a slide starts, given the edge it comes from.
+ *
+ * `MPSide` is physical everywhere in this library, and it stays physical here:
+ * something sliding in from the top of the window comes from the top in every
+ * writing direction.
+ */
+export declare function slideOffsets(from: MPSide, distance: number | string): {
+    x: string;
+    y: string;
+};
+export declare function usePrefersReducedMotion(): boolean;
+export interface AnimationRunOptions {
+    trigger: MPAnimateTrigger;
+    play?: boolean;
+    once: boolean;
+    threshold: number;
+    paused?: boolean;
+    /** An infinite effect stops when the pointer leaves; a finite one finishes. */
+    infinite: boolean;
+}
+export interface AnimationRun {
+    /** Goes on the animated element. */
+    ref: React.RefCallback<HTMLElement>;
+    /** `running` or `paused`, for `--_mp-anim-state`. */
+    state: 'running' | 'paused';
+    /** Whether the animation has been let go at all. */
+    started: boolean;
+    /** Spread onto the element when `trigger` is `hover`; empty otherwise. */
+    handlers: React.HTMLAttributes<HTMLElement>;
+}
+/**
+ * Starts, restarts and holds an animation.
+ *
+ * Two things here are less obvious than they look.
+ *
+ * **Waiting is `animation-play-state: paused`, not a second class.** An element
+ * that has not been triggered yet has to already look like its own first frame,
+ * or a `visible` fade would be fully drawn until it scrolled into view and then
+ * blink out to start. With `fill-mode: both` a paused animation shows exactly
+ * that frame, so waiting and running are one animation in two states rather
+ * than two states to keep in step.
+ *
+ * **Restarting reaches for the DOM.** There is no way to rewind a CSS animation
+ * from React: re-rendering with the same class changes nothing, and a `key`
+ * would restart the animation by unmounting the children, taking their state
+ * with it. Clearing `animation-name`, reading a layout property to force the
+ * style to settle, and putting it back is the one move that rewinds the element
+ * and leaves everything inside it alone.
+ */
+export declare function useAnimationRun({ trigger, play, once, threshold, paused, infinite }: AnimationRunOptions): AnimationRun;
+export interface AnimateElementParams extends AnimationSlotOptions, AnimationRunOptions {
+}
+export interface AnimateElement {
+    ref: React.RefCallback<HTMLElement>;
+    className: string;
+    style: React.CSSProperties;
+    /** The hover handlers and the two data attributes, ready to be spread. */
+    props: React.HTMLAttributes<HTMLElement> & Record<string, unknown>;
+}
+/**
+ * Everything an `MPAnimate*` root needs, in one call.
+ *
+ * The six effect components differ only in their defaults and in which slots
+ * they fill, so this is where the identical two-thirds of each of them lives.
+ * The ones that have to understand their children — Typing, Marquee, Headline,
+ * Appear — call `useAnimationRun` directly and put the classes where their own
+ * structure needs them.
+ *
+ * `data-mp-animation` and `data-mp-state` are here rather than in each
+ * component because they are the same two facts every time, and because a test
+ * that has to assert on a class name is a test that breaks when a class name
+ * changes.
+ */
+export declare function useAnimateElement(params: AnimateElementParams): AnimateElement;

package/dist/internal/animate.js

@@ -0,0 +1 @@
+import*as e from"react";export const ANIM_BASE="mp-anim";export const ANIMATION_CLASS={fade:"mp-anim-fade",grow:"mp-anim-scale",slide:"mp-anim-slide",zoom:"mp-anim-scale",rotate:"mp-anim-rotate",blink:"mp-anim-blink"};const n={fade:{in:"medium2",out:"short4"},grow:{in:"medium4",out:"short4"},slide:{in:"medium4",out:"short4"},zoom:{in:"medium4",out:"short4"},rotate:{in:"long2",out:"medium2"},blink:{in:"extra-long4",out:"extra-long4"}},t={fade:"emphasized-decelerate",grow:"emphasized-decelerate",slide:"emphasized-decelerate",zoom:"emphasized-decelerate",rotate:"emphasized-decelerate",blink:"standard"};export function easingValue(e){return`var(--mp-sys-motion-easing-${e})`}export function durationValue(e,t,i="in"){return void 0!==e?`${e}ms`:`var(--mp-sys-motion-duration-${n[t][i]})`}export function lengthValue(e){return"number"==typeof e?`${e}px`:e}export function repeatValue(e){return"infinite"===e?"infinite":String(e)}export function isInfinite(e){return"infinite"===e}export function directionValue(e,n){return"out"===e?n?"alternate-reverse":"reverse":n?"alternate":"normal"}export function animationSlots(e){const n=e.mode??"in",i={"--_mp-anim-duration":durationValue(e.duration,e.effect,n),"--_mp-anim-delay":`${e.delay}ms`,"--_mp-anim-ease":easingValue(e.easing??t[e.effect]),"--_mp-anim-repeat":repeatValue(e.repeat),"--_mp-anim-direction":directionValue(n,e.alternate)};return void 0!==e.opacity&&(i["--_mp-anim-opacity"]=String(e.opacity)),void 0!==e.scale&&(i["--_mp-anim-scale"]=String(e.scale)),void 0!==e.x&&(i["--_mp-anim-x"]=e.x),void 0!==e.y&&(i["--_mp-anim-y"]=e.y),void 0!==e.angle&&(i["--_mp-anim-angle"]=e.angle),void 0!==e.angleTo&&(i["--_mp-anim-angle-to"]=e.angleTo),i}export function slideOffsets(e,n){const t=lengthValue(n),i="number"==typeof n?-n+"px":`calc(-1 * ${t})`;switch(e){case"top":return{x:"0px",y:i};case"bottom":return{x:"0px",y:t};case"left":return{x:i,y:"0px"};default:return{x:t,y:"0px"}}}const i="(prefers-reduced-motion: reduce)";function a(e){if("undefined"==typeof window||!window.matchMedia)return()=>{};const n=window.matchMedia(i);return n.addEventListener("change",e),()=>n.removeEventListener("change",e)}function r(){return!("undefined"==typeof window||!window.matchMedia)&&window.matchMedia(i).matches}function o(){return!1}export function usePrefersReducedMotion(){return e.useSyncExternalStore(a,r,o)}export function useAnimationRun({trigger:n,play:t,once:i,threshold:a,paused:r,infinite:o}){const s=e.useRef(null),[u,m]=e.useState("mount"===n),[c,d]=e.useState(0),l=e.useCallback(()=>{m(!0),d(e=>e+1)},[]);e.useLayoutEffect(()=>{const e=s.current;if(!e||0===c)return;const n=[e,...e.querySelectorAll(".mp-anim, .mp-marquee-track")];for(const e of n)e.style.animationName="none";e.offsetWidth;for(const e of n)e.style.animationName=""},[c]),e.useEffect(()=>{if("visible"!==n)return;const e=s.current;if(!e||"undefined"==typeof IntersectionObserver)return void m(!0);const t=new IntersectionObserver(([e])=>{e.isIntersecting?(l(),i&&t.disconnect()):i||m(!1)},{threshold:a});return t.observe(e),()=>t.disconnect()},[n,i,a,l]),e.useEffect(()=>{"manual"===n&&(t?l():m(!1))},[n,t,l]);const p=e.useCallback(()=>{o&&m(!1)},[o]),f="hover"===n?{onPointerEnter:l,onFocus:l,onPointerLeave:p,onBlur:p}:{};return{ref:e.useCallback(e=>{s.current=e},[]),state:u&&!r?"running":"paused",started:u,handlers:f}}export function useAnimateElement(e){const{trigger:n,play:t,once:i,threshold:a,paused:r,infinite:o,...s}=e,u=useAnimationRun({trigger:n,play:t,once:i,threshold:a,paused:r,infinite:o});return{ref:u.ref,className:`mp-anim ${ANIMATION_CLASS[s.effect]}`,style:{...animationSlots(s),"--_mp-anim-state":u.state},props:{...u.handlers,"data-mp-animation":s.effect,"data-mp-state":u.state}}}

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'): readonly string[];
+/** The twelve month names, January first, in the locale's own words. */
+export declare function monthLabels(locale: string | undefined, month?: 'short' | 'long'): readonly 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),n=new Map;export function weekdayLabels(t,e,o="narrow"){const a=`w ${t??""} ${e} ${o}`;let s=n.get(a);if(!s){const i=dateFormatter(t,{weekday:o});s=Array.from({length:7},(t,n)=>i.format(addDays(r,(e+n)%7))),n.set(a,s)}return s}export function monthLabels(t,e="short"){const r=`m ${t??""} ${e}`;let o=n.get(r);if(!o){const a=dateFormatter(t,{month:e});o=Array.from({length:12},(t,e)=>a.format(makeDate(2021,e,1))),n.set(r,o)}return o}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}