material-plus-ui 0.0.1 → 1.1.0

package/dist/types.d.ts

@@ -1,27 +1,157 @@
 /**
  * The prop vocabulary shared across Material Plus components.
  *
- * This library sits on top of Material UI rather than beside it, so the rule
- * here is the opposite of the usual one for a component library: **where MUI
- * already has a word, use MUI's word.** A `size` of `'small'`, a `color` of
- * `'primary'` and an `error` boolean mean on an `MP*` component exactly what
- * they mean on the `@mui/material` component next to it in the same form. A
- * second vocabulary would make a consumer translate between two libraries on
- * every line, which is the thing this package exists to avoid.
+ * This library implements the Material Design specification rather than wrapping
+ * somebody's implementation of it, so the rule is: **where the spec already has a
+ * word, use the spec's word.** A colour role is `primary` or `on-surface-variant`
+ * because that is what MD3 calls it, a corner is `extra-small`, a type role is
+ * `body-large`.
  *
- * What lives here is only what MUI has no word for.
+ * In particular they are *not* Material UI's words. MUI's palette is
+ * `main`/`light`/`dark`/`contrastText`, which is a different and earlier colour
+ * model; borrowing those names would describe a system this library does not
+ * implement. See `src/styles.css` for the token side of the same decision.
+ *
+ * What lives here is only what a component actually needs in its props.
  */
 import type * as React from 'react';
 /**
- * The size ladder for controls, spelled the way MUI spells it.
+ * The size ladder every control is drawn at.
+ *
+ * **This is the one place the library goes beyond the specification, knowingly.**
+ * Material defines a single size per component — a text field is 56dp, full
+ * stop — because it is describing a design system for whole products, where one
+ * height per control is the point. A component library gets used in places a
+ * design system does not plan for: a filter bar, a table's inline editor, a
+ * dense settings page, a marketing hero. Those need a ladder, and a consumer
+ * who cannot get one from the library builds it out of `!important`.
+ *
+ * So `md` **is** the spec's size, and the other four are ours. That is the whole
+ * rule, and it is why the ladder is centred rather than starting at the spec's
+ * value: `md` is what you get by saying nothing, and nobody has to know the
+ * scale exists to be given the Material size.
+ *
+ * `xs` and `xl` are deliberately at the edges of usable rather than merely
+ * smaller and larger — below `xs` a control stops meeting a 24px touch target,
+ * and there is no sixth step because a ladder long enough to need one is a sign
+ * the caller wants a custom control instead.
+ */
+export type MPSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * An accent colour role.
+ *
+ * MD3's four, not Material UI's six: there is no `info`, `success` or `warning`
+ * in the specification's colour system, and offering them would promise roles the
+ * token sheet has no way to derive.
+ */
+export type MPColor = 'primary' | 'secondary' | 'tertiary' | 'error';
+/**
+ * How much of a surface a component paints.
+ *
+ * These are Material's own five button styles, in the order they get louder, and
+ * the vocabulary is deliberately shared with the components that are not buttons
+ * — a `filled` segmented button and a `filled` button are the same statement
+ * about emphasis, made by two different controls.
+ *
+ * `elevated` is the odd one: it is a *tonal* surface that also casts a shadow,
+ * and MD3 keeps it separate from `filled` precisely because a raised surface and
+ * a saturated one solve the same problem two different ways. A component that has
+ * no meaningful raised state simply does not offer it.
+ */
+export type MPVariant = 'filled' | 'tonal' | 'elevated' | 'outlined' | 'text';
+/** Which way a set of controls runs. */
+export type MPOrientation = 'horizontal' | 'vertical';
+/**
+ * Where something sits along an axis.
+ *
+ * `start` and `end` rather than `left` and `right`, for the same reason the icon
+ * slots are `startIcon` and `endIcon`: the two words that name a physical side
+ * swap meaning under RTL, and a divider whose label was pinned `left` would move
+ * to the other end of the rule in Arabic without anybody asking it to.
+ */
+export type MPAlign = 'start' | 'center' | 'end';
+/**
+ * Which side of an anchor something is drawn on.
+ *
+ * These *are* physical sides, and deliberately so — this is the axis a popup
+ * travels along, and Base UI's positioner takes the same four words. A tooltip
+ * above its trigger is above it in every writing direction.
+ */
+export type MPSide = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Which corner of a box something is pinned to. Logical again: a badge sits at
+ * the reading-end corner, which is the left one under RTL.
+ */
+export type MPCorner = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+/**
+ * Which day a week is drawn as starting on. `0` is Sunday, the way `Date`
+ * counts.
+ *
+ * `Date`'s numbering rather than a nicer set of words, and rather than CLDR's —
+ * which counts Monday as 1 through Sunday as 7. Every calendar in this library
+ * is built out of `getDay()`, so a second numbering would be a conversion at
+ * every comparison, and an off-by-one there is a week drawn one column out.
+ *
+ * Left unset, a picker asks `Intl` what the locale does: Sunday in the US and
+ * 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.
  *
- * Re-declared rather than imported from `@mui/material` on purpose: it is two
- * string literals, and importing it would put a type-only dependency on a
- * peer's internal module path in every component's declaration file.
+ * **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 MPSize = 'small' | 'medium';
-/** A palette role. The same six names `@mui/material` uses. */
-export type MPColor = 'primary' | 'secondary' | 'success' | 'error' | 'info' | 'warning';
+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.
+ *
+ * A component extends this and adds only what is genuinely its own, which is what
+ * keeps `size="md"` meaning the same thing on every one of them. The rule for
+ * adding to this interface is the same as the rule for adding a token: an axis
+ * arrives when a second component needs it, not in anticipation of one.
+ */
+export interface MPStyleProps {
+    /**
+     * The control's height and type scale.
+     * @default 'md'
+     */
+    size?: MPSize;
+    /** Stretches the control to the width of its container. */
+    fullWidth?: boolean;
+}
 /**
  * The props a glyph component is handed when Material Plus renders one.
  *
@@ -47,7 +177,7 @@ export interface MPIconGlyphProps {
  *   lets `MPIcon` pass a size and a colour *into* the glyph rather than trying
  *   to style an element from the outside.
  * - **An element** — `<MPIcon icon={<svg>…</svg>} />`. A drawing of your own, a
- *   `@mui/icons-material` glyph already constructed, an `<img>`. It is sized by
+ *   glyph another set has already constructed, an `<img>`. It is sized by
  *   the box it is laid into.
  *
  * Note that this is *not* `React.ReactNode`. A component and an element are
@@ -55,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,7 +1,7 @@
 {
   "name": "material-plus-ui",
-  "version": "0.0.1",
-  "description": "A React component library that extends Material UI — the components MUI does not ship, and wider versions of the ones it does. Built on @mui/material, Base UI and Tailwind CSS v4. ESM only, types included.",
+  "version": "1.1.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",
   "author": "CDGet <jooy2.contact@gmail.com>",
@@ -63,9 +63,9 @@
   "keywords": [
     "material-plus-ui",
     "material-plus",
-    "material-ui",
-    "mui",
-    "mui-extensions",
+    "material-design",
+    "material-design-3",
+    "md3",
     "react",
     "reactjs",
     "react-components",
@@ -100,48 +100,43 @@
   ],
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
     "@eslint/js": "^9.39.1",
-    "@mui/material": "^9.3.0",
     "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
-    "@typescript-eslint/parser": "^8.66.0",
+    "@typescript-eslint/parser": "^8.67.0",
     "@vitejs/plugin-react": "^6.0.5",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-n": "^18.2.2",
-    "globals": "^17.9.0",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.10.0",
     "jiti": "^2.7.0",
     "playwright": "^1.62.1",
-    "postcss": "^8.5.25",
+    "postcss": "^8.5.26",
     "prettier": "^3.9.6",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "terser-glob": "^1.2.1",
-    "tsx": "^4.23.6",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.66.0",
-    "vite": "^8.2.0",
+    "typescript-eslint": "^8.67.0",
+    "vite": "^8.2.1",
     "vitepress": "^1.6.4",
     "vitepress-i18n": "^1.3.5",
-    "vitepress-sidebar": "^1.36.1",
+    "vitepress-sidebar": "^1.38.0",
     "vitest": "^4.1.10",
     "vitest-browser-react": "^2.2.0"
   },
   "dependencies": {
-    "lucide-react": "^1.28.0"
+    "lucide-react": "^1.31.0"
   },
   "peerDependencies": {
-    "@emotion/react": "^11.0.0",
-    "@emotion/styled": "^11.0.0",
-    "@mui/material": "^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0",
+    "@base-ui/react": "^1.7.0",
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"