material-plus-ui 1.0.0 → 1.2.0

package/dist/types.d.ts

@@ -96,6 +96,45 @@ export type MPCorner = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
  * Korea, Monday across most of Europe, Saturday in much of the Middle East.
  */
 export type MPWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * How something sits in the page's scroll.
+ *
+ * CSS's own four values, because this is CSS's own question and a second
+ * spelling for `fixed` would be a word a caller has to translate. `sticky` and
+ * `fixed` are what a bar pinned to an edge of the window wants; `absolute` pins
+ * a thing to a *region* instead — a button in a card, in a map, in a preview —
+ * and is the one that makes a floating control usable anywhere but the window.
+ */
+export type MPPosition = 'static' | 'absolute' | 'sticky' | 'fixed';
+/**
+ * How wide the window is, in Material's own words.
+ *
+ * MD3 does not describe a layout in pixels, it describes it in **window size
+ * classes**: `compact` below 600dp, `medium` from 600, `expanded` from 840,
+ * `large` from 1200, `extra-large` from 1600. They are the axis the
+ * specification's layout grid changes along — four columns in a compact window,
+ * twelve from medium up — and so they are the axis this library's grid changes
+ * along too.
+ *
+ * **They are deliberately not Tailwind's breakpoints.** Tailwind changes at
+ * 640/768/1024/1280, which are different numbers describing the same idea, and a
+ * `<MPGrid>` that reflowed at one set while the `md:` utility beside it reflowed
+ * at another would be a layout that is subtly wrong at exactly one width and
+ * impossible to reason about at every other. Given two ladders, the library
+ * takes the one the specification defines — see
+ * `docs/{locale}/components/layout/grid.md` for how to line the other one up
+ * with it.
+ */
+export type MPWindowClass = 'compact' | 'medium' | 'expanded' | 'large' | 'extra-large';
+/**
+ * A value, or the same value said differently at each window size class.
+ *
+ * `span={6}` is six columns at every width; `span={{ compact: 12, medium: 6 }}`
+ * is the whole row on a phone and half of it from 600dp up. Each entry applies
+ * from its own class **upward**, so a layout is usually two entries rather than
+ * five — anything not named keeps whatever the class below it said.
+ */
+export type MPResponsive<T> = T | Partial<Record<MPWindowClass, T>>;
 /**
  * The axes most components share.
  *
@@ -146,3 +185,119 @@ export interface MPIconGlyphProps {
  * caller passing `ICONS.close` would be told to pass `<ICONS.close />` instead.
  */
 export type MPIconGlyph = React.ComponentType<MPIconGlyphProps> | React.ReactElement;
+/**
+ * A Material easing curve, by the specification's own name.
+ *
+ * These are MD3's motion easing set and nothing else — no arbitrary
+ * `cubic-bezier()`, for the same reason `color` takes a family rather than a
+ * colour: to change what `emphasized` *is*, set
+ * `--mp-sys-motion-easing-emphasized` and every animation in the page moves
+ * together. A curve written into one component's props is a curve the theme
+ * cannot reach.
+ *
+ * The pairs are how Material describes a transition rather than four
+ * interchangeable options. Something **arriving** decelerates into place;
+ * something **leaving** accelerates away; `standard` is for a change that is
+ * neither, and `linear` for a loop that has no beginning to arrive at.
+ *
+ * A note on `emphasized`: the specification's own emphasized curve is two
+ * curves joined in the middle, which CSS has no single value for. MD3's web
+ * implementation publishes a one-curve stand-in, and that is what the token
+ * carries here. Where the halves matter — a line arriving as another leaves —
+ * the two `emphasized-*` names are the halves, and they are what the components
+ * reach for.
+ */
+export type MPEasing = 'linear' | 'standard' | 'standard-decelerate' | 'standard-accelerate' | 'emphasized' | 'emphasized-decelerate' | 'emphasized-accelerate';
+/**
+ * The six effects the `MPAnimate*` components are built out of.
+ *
+ * Named after what a reader sees rather than after the CSS property underneath:
+ * `zoom` and `grow` are both a change of scale, and they are two words because
+ * they are two *gestures* — one arrives from the middle of where it will end
+ * up, the other unfolds from an edge of it.
+ *
+ * Everything past these six is a component rather than a value. A marquee that
+ * duplicates its children, a headline that swaps between them, a typewriter
+ * that counts characters — none of those can be a class name and a few numbers.
+ */
+export type MPAnimation = 'fade' | 'grow' | 'slide' | 'zoom' | 'rotate' | 'blink';
+/**
+ * What makes an animation run.
+ *
+ * - `mount` — as soon as it is on the page. The default, and the only one that
+ *   needs nothing from the caller.
+ * - `visible` — when it is scrolled into view. Once, unless `once` is off.
+ * - `hover` — while the pointer is on it, starting again on each entry.
+ *   Keyboard focus counts, or the effect would be unreachable without a mouse.
+ * - `manual` — never on its own. `play` is what runs it.
+ */
+export type MPAnimateTrigger = 'mount' | 'visible' | 'hover' | 'manual';
+/**
+ * Whether an effect brings its content in or takes it away.
+ *
+ * The two are not the same length in Material: an entrance is given room to be
+ * read as an arrival, an exit gets out of the way. That asymmetry is what the
+ * default durations carry, so `mode="out"` is quicker than `mode="in"` without
+ * anybody having to know the numbers.
+ */
+export type MPAnimateMode = 'in' | 'out';
+/**
+ * How many times an animation runs. `'infinite'` rather than `Infinity`,
+ * because it is written into CSS as that word and a caller who typed the number
+ * would be surprised by which one worked.
+ */
+export type MPAnimateRepeat = number | 'infinite';
+/**
+ * The settings every `MPAnimate*` component takes, and the reason they are one
+ * interface: a `delay` of 200 has to mean the same thing on a fade and on a
+ * marquee, exactly as `size="md"` means one height everywhere.
+ *
+ * Durations and delays are milliseconds — numbers, not CSS strings. A prop
+ * typed `string` invites `'0.4s'`, and then two components on one screen are
+ * written in two units.
+ */
+export interface MPAnimateProps {
+    /**
+     * How long one run takes, in milliseconds. Left unset, the effect takes its
+     * own Material duration token — which is what a theme changes.
+     */
+    duration?: number;
+    /**
+     * How long before it starts, in milliseconds.
+     * @default 0
+     */
+    delay?: number;
+    /** Which Material easing curve it runs on. */
+    easing?: MPEasing;
+    /**
+     * How many times it runs.
+     * @default 1
+     */
+    repeat?: MPAnimateRepeat;
+    /** Runs every other pass backwards, so a repeat returns instead of jumping. */
+    alternate?: boolean;
+    /**
+     * Holds the animation where it is.
+     * @default false
+     */
+    paused?: boolean;
+    /**
+     * What starts it.
+     * @default 'mount'
+     */
+    trigger?: MPAnimateTrigger;
+    /** Runs it, when `trigger` is `manual`. Each `false` → `true` starts it over. */
+    play?: boolean;
+    /**
+     * With `trigger="visible"`, whether it runs only the first time. Off, it runs
+     * again every time the element comes back into view.
+     * @default true
+     */
+    once?: boolean;
+    /**
+     * With `trigger="visible"`, how much of the element has to be on screen
+     * before it counts as visible, from `0` to `1`.
+     * @default 0.2
+     */
+    threshold?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "material-plus-ui",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A React component library implementing Material Design 3 — the components other Material libraries do not ship, and wider versions of the ones they do. Built on Base UI and Tailwind CSS v4, themed with CSS custom properties so it can coexist with an existing Material setup. ESM only, types included.",
   "type": "module",
   "types": "dist/index.d.ts",
@@ -31,7 +31,7 @@
     "typecheck": "tsc --project tsconfig.prod.json --noEmit && tsc --project test/tsconfig.json && tsc --project docs/tsconfig.json"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "main": "dist/index.js",
   "exports": {
@@ -106,13 +106,13 @@
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "@typescript-eslint/parser": "^8.67.0",
-    "@vitejs/plugin-react": "^6.0.5",
-    "@vitest/browser": "^4.1.10",
-    "@vitest/browser-playwright": "^4.1.10",
+    "@vitejs/plugin-react": "^6.1.0",
+    "@vitest/browser": "^4.1.11",
+    "@vitest/browser-playwright": "^4.1.11",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.10.0",
+    "globals": "^17.11.0",
     "jiti": "^2.7.0",
     "playwright": "^1.62.1",
     "postcss": "^8.5.26",
@@ -125,15 +125,15 @@
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.67.0",
-    "vite": "^8.2.1",
+    "vite": "^8.2.2",
     "vitepress": "^1.6.4",
     "vitepress-i18n": "^1.3.5",
-    "vitepress-sidebar": "^1.38.0",
-    "vitest": "^4.1.10",
+    "vitepress-sidebar": "^1.39.0",
+    "vitest": "^4.1.11",
     "vitest-browser-react": "^2.2.0"
   },
   "dependencies": {
-    "lucide-react": "^1.31.0"
+    "lucide-react": "^1.33.0"
   },
   "peerDependencies": {
     "@base-ui/react": "^1.7.0",