@noxlovette/material 0.5.0 → 0.6.0

package/dist/animation/TransitionPatterns.stories.svelte

@@ -1,6 +1,8 @@
 <!--
   The six M3 transition patterns, each on its own M3 shape, driven by `src/lib/animation/`.
   https://m3.material.io/styles/motion/transitions/transition-patterns
+  Choosing and applying them: https://m3.material.io/styles/motion/transitions/applying-transitions
+  (summarized in .claude/skills/material-design/references/motion-guide.md → "Applying transitions").
 
   Every demo loops by default; "Replay" retriggers it on demand. The Overview plays the six in
   turn rather than all at once: container transform, forward/backward, lateral and top level run
@@ -201,27 +203,30 @@
       <button
         type="button"
         data-demo="ct-card"
-        class="bg-md-sys-color-primary-container text-md-sys-color-on-primary-container absolute top-4 left-4 flex items-center gap-3 rounded-lg p-3"
+        class="bg-md-sys-color-primary-container text-md-sys-color-on-primary-container top-spacing-200 left-spacing-200 gap-spacing-150 p-spacing-150 absolute flex items-center rounded-lg"
         onclick={runContainer}
       >
-        {@render shape(pathFourSidedCookie, 'size-10 text-md-sys-color-primary')}
+        {@render shape(pathFourSidedCookie, 'size-spacing-500 text-md-sys-color-primary')}
         <span class="md-sys-typescale-label-large">Open</span>
       </button>
     {:else}
       <div
         data-demo="ct-detail"
-        class="bg-md-sys-color-surface-container-highest text-md-sys-color-on-surface absolute inset-3 flex flex-col items-center justify-center gap-3 rounded-xl"
+        class="bg-md-sys-color-surface-container-highest text-md-sys-color-on-surface inset-spacing-150 gap-spacing-150 absolute flex flex-col items-center justify-center rounded-xl"
       >
         {@render shape(pathFourSidedCookie, 'size-24 text-md-sys-color-primary')}
         <span class="md-sys-typescale-title-medium">Detail</span>
       </div>
     {/if}
   {:else if pattern.id === 'axis'}
-    <div data-demo="axis" class="absolute inset-0 flex flex-col items-center justify-center gap-3">
+    <div
+      data-demo="axis"
+      class="inset-spacing-0 gap-spacing-150 absolute flex flex-col items-center justify-center"
+    >
       {@render shape(
         pathPentagon,
         [
-          'size-16 text-md-sys-color-primary',
+          'size-spacing-800 text-md-sys-color-primary',
           'size-20 text-md-sys-color-secondary',
           'size-24 text-md-sys-color-tertiary'
         ][level]
@@ -231,7 +236,9 @@
       </span>
     </div>
   {:else if pattern.id === 'lateral'}
-    <div class="absolute inset-x-0 top-0 flex justify-center gap-6 pt-3">
+    <div
+      class="inset-x-spacing-0 top-spacing-0 gap-spacing-300 pt-spacing-150 absolute flex justify-center"
+    >
       {#each tabs as name, i (name)}
         <span
           class={[
@@ -243,7 +250,7 @@
     </div>
     <div
       data-demo="lateral"
-      class="bg-md-sys-color-surface-container absolute inset-x-3 top-11 bottom-3 flex items-center justify-center rounded-lg"
+      class="bg-md-sys-color-surface-container inset-x-spacing-150 bottom-spacing-150 absolute top-11 flex items-center justify-center rounded-lg"
     >
       {@render shape(pathFourLeafClover, 'size-24 text-md-sys-color-primary')}
       <span
@@ -255,7 +262,7 @@
     <div
       data-demo="top"
       class={[
-        'absolute inset-3 flex flex-col items-center justify-center gap-3 rounded-lg',
+        'inset-spacing-150 gap-spacing-150 absolute flex flex-col items-center justify-center rounded-lg',
         destinations[destination].color
       ]}
     >
@@ -265,23 +272,25 @@
   {:else if pattern.id === 'enter-exit'}
     {#if pop.mounted}
       <div
-        class="bg-md-sys-color-surface-container-high shadow-elevation-3 absolute inset-x-8 inset-y-6 flex items-center justify-center rounded-xl"
+        class="bg-md-sys-color-surface-container-high shadow-elevation-3 inset-x-spacing-400 inset-y-spacing-300 absolute flex items-center justify-center rounded-xl"
         {@attach pop.attach(enterExit.scale)}
       >
         {@render shape(pathSoftBurst, 'size-24 text-md-sys-color-tertiary')}
       </div>
     {/if}
   {:else if pattern.id === 'skeleton'}
-    <div class="absolute inset-3 grid [&>*]:[grid-area:1/1]">
+    <div class="inset-spacing-150 absolute grid [&>*]:[grid-area:1/1]">
       {#if !loaded}
-        <div class="flex flex-col items-center justify-center gap-3" {@attach skeleton}>
+        <div class="gap-spacing-150 flex flex-col items-center justify-center" {@attach skeleton}>
           <div class="bg-md-sys-color-surface-container-highest size-24 rounded-full"></div>
-          <div class="bg-md-sys-color-surface-container-highest h-4 w-28 rounded-full"></div>
+          <div
+            class="bg-md-sys-color-surface-container-highest h-spacing-200 w-28 rounded-full"
+          ></div>
         </div>
       {/if}
       {#if content.mounted}
         <div
-          class="flex flex-col items-center justify-center gap-3"
+          class="gap-spacing-150 flex flex-col items-center justify-center"
           {@attach content.attach(enterExit.fade)}
         >
           {@render shape(pathGem, 'size-24 text-md-sys-color-secondary')}
@@ -294,10 +303,10 @@
 
 {#snippet demo(pattern: Pattern, tall = false)}
   <section
-    class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface flex flex-col gap-3 rounded-xl p-4"
+    class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface gap-spacing-150 p-spacing-200 flex flex-col rounded-xl"
   >
-    <header class="flex items-start justify-between gap-3">
-      <div class="flex flex-col gap-1">
+    <header class="gap-spacing-150 flex items-start justify-between">
+      <div class="gap-spacing-50 flex flex-col">
         <Title size="medium">{pattern.title}</Title>
         <Body size="small" class="text-md-sys-color-on-surface-variant">{pattern.summary}</Body>
       </div>
@@ -318,7 +327,7 @@
 {/snippet}
 
 {#snippet toolbar()}
-  <div class="flex items-center justify-between gap-4">
+  <div class="gap-spacing-200 flex items-center justify-between">
     <Title size="large">M3 transition patterns</Title>
     <Button variant={looping ? 'filled' : 'outlined'} onclick={() => (looping = !looping)}>
       {looping ? 'Pause loop' : 'Loop'}
@@ -327,9 +336,12 @@
 {/snippet}
 
 <Story name="Overview" asChild>
-  <div class="bg-md-sys-color-surface flex min-h-dvh flex-col gap-6 p-6" {@attach roundRobin}>
+  <div
+    class="bg-md-sys-color-surface gap-spacing-300 p-spacing-300 flex min-h-dvh flex-col"
+    {@attach roundRobin}
+  >
     {@render toolbar()}
-    <div class="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+    <div class="gap-spacing-200 grid md:grid-cols-2 xl:grid-cols-3">
       {#each all as pattern (pattern.id)}
         {@render demo(pattern)}
       {/each}
@@ -339,7 +351,7 @@
 
 {#snippet single(pattern: Pattern)}
   <div
-    class="bg-md-sys-color-surface flex min-h-dvh flex-col gap-6 p-6"
+    class="bg-md-sys-color-surface gap-spacing-300 p-spacing-300 flex min-h-dvh flex-col"
     {@attach loop(pattern.run)}
   >
     {@render toolbar()}

package/dist/animation/containerTransform.d.ts

@@ -13,10 +13,21 @@ export interface ContainerTransformOptions {
  * the outgoing content fades out and the incoming content fades in on top.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#container-transform
  *
+ * The most dramatic pattern (https://m3.material.io/styles/motion/transitions/applying-transitions).
+ * Use it for hero moments, shallow expand → collapse hierarchies and seamless element-to-element
+ * connections. Don't use it in deep hierarchies or utility-focused navigation, where it becomes
+ * excessive. Use `sharedAxis` there. Keep `spring` at `spatial`/`slowSpatial`, never the bouncy
+ * `fastSpatial`.
+ *
  * Built on Motion's `animateView()` (View Transition API), so `from` and `to` never have to be in
  * the DOM at the same time — `update` swaps one for the other. Browsers without the API just run
  * `update`. A second call while one is running is queued, not interrupted.
  *
+ * Not built into any component. FAB → sheet is the FAB's own morph (a clip-path on Motion, in
+ * `FAB.svelte`), because M3 keeps that container opaque and changes its colour, which a
+ * snapshot cross-fade can't. Card → detail is the app's own navigation, and `Search` is a plain
+ * field with no search view to expand into.
+ *
  * ```ts
  * containerTransform(
  *   async () => { expanded = true; await tick(); },

package/dist/animation/containerTransform.js

@@ -5,10 +5,21 @@ import { springTokens, springTransition } from './spring.js';
  * the outgoing content fades out and the incoming content fades in on top.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#container-transform
  *
+ * The most dramatic pattern (https://m3.material.io/styles/motion/transitions/applying-transitions).
+ * Use it for hero moments, shallow expand → collapse hierarchies and seamless element-to-element
+ * connections. Don't use it in deep hierarchies or utility-focused navigation, where it becomes
+ * excessive. Use `sharedAxis` there. Keep `spring` at `spatial`/`slowSpatial`, never the bouncy
+ * `fastSpatial`.
+ *
  * Built on Motion's `animateView()` (View Transition API), so `from` and `to` never have to be in
  * the DOM at the same time — `update` swaps one for the other. Browsers without the API just run
  * `update`. A second call while one is running is queued, not interrupted.
  *
+ * Not built into any component. FAB → sheet is the FAB's own morph (a clip-path on Motion, in
+ * `FAB.svelte`), because M3 keeps that container opaque and changes its colour, which a
+ * snapshot cross-fade can't. Card → detail is the app's own navigation, and `Search` is a plain
+ * field with no search view to expand into.
+ *
  * ```ts
  * containerTransform(
  *   async () => { expanded = true; await tick(); },

package/dist/animation/enterExit.d.ts

@@ -5,6 +5,15 @@ import type { AnimationOptions, DOMKeyframesDefinition } from 'motion';
  * layer detects to delay unmounting.
  *
  * https://m3.material.io/styles/motion/transitions/transition-patterns#enter-and-exit
+ *
+ * Introduces a component in the context of the current screen, modal or not
+ * (https://m3.material.io/styles/motion/transitions/applying-transitions). Never use it to navigate between hierarchical screens.
+ * Clean fades: opacity always runs on `fastEffects` so it never lingers over the content behind.
+ * Edge-anchored sheets slide without fading, as M3 asks.
+ *
+ * Required for every component that mounts a surface within the current screen: dialogs, sheets,
+ * menus, popovers, tooltips, pickers, snackbars, the FAB menu. See the ownership table in
+ * `.claude/skills/material-design/references/motion-guide.md`.
  */
 export interface PresenceTransition {
     /** Where the enter animation starts. */

package/dist/animation/enterExit.js

@@ -53,14 +53,17 @@ export const enterExit = {
         enter: enterWith(springTokens.spatial),
         exit
     },
-    /** Side sheet anchored to the inline-end edge. */
+    /**
+     * Side sheet anchored to the inline-end edge. Slides only: no opacity (M3: don't fade sheets).
+     * The extra 1rem clears a detached sheet's 16dp margin, so no sliver is left at the edge.
+     */
     sideSheet: {
-        hidden: { transform: 'translateX(100%)' },
+        hidden: { transform: 'translateX(calc(100% + 1rem))' },
         shown: { transform: 'translateX(0%)' },
         enter: springTransition(springTokens.spatial),
         exit: springTransition(springTokens.effects)
     },
-    /** Bottom sheet anchored to the bottom edge. */
+    /** Bottom sheet anchored to the bottom edge. Slides only: no opacity (M3: don't fade sheets). */
     bottomSheet: {
         hidden: { transform: 'translateY(100%)' },
         shown: { transform: 'translateY(0%)' },

package/dist/animation/index.d.ts

@@ -1,3 +1,4 @@
+export * from './shapeMorph.svelte.js';
 export * from './shapes.js';
 export * from './shapesAnimatable.js';
 export * from './shapesAnimatableSmall.js';

package/dist/animation/index.js

@@ -1,3 +1,4 @@
+export * from './shapeMorph.svelte.js';
 export * from './shapes.js';
 export * from './shapesAnimatable.js';
 export * from './shapesAnimatableSmall.js';

package/dist/animation/shapeMorph.svelte.d.ts

@@ -0,0 +1,52 @@
+import { type AnimationPlaybackControls } from 'motion';
+import type { Attachment } from 'svelte/attachments';
+import { type SpringToken } from './spring.js';
+/**
+ * The 35 shapes of the M3 Expressive shape library, in the order of the spec sheet.
+ * https://m3.material.io/styles/shape
+ */
+export declare const shapeNames: readonly ["circle", "square", "slanted", "arch", "semicircle", "oval", "pill", "triangle", "arrow", "fan", "diamond", "clamshell", "pentagon", "gem", "verySunny", "sunny", "fourSidedCookie", "sixSidedCookie", "sevenSidedCookie", "nineSidedCookie", "twelveSidedCookie", "fourLeafClover", "eightLeafClover", "burst", "softBurst", "boom", "softBoom", "flower", "puffy", "puffyDiamond", "ghostish", "pixelCircle", "pixelTriangle", "bun", "heart"];
+export type ShapeName = (typeof shapeNames)[number];
+/**
+ * Every shape as a 720-point path in a 380 × 380 viewBox (`<svg viewBox="0 0 380 380">`). All
+ * share one command structure, start point and winding, so any two morph cleanly. Use these for
+ * large, hero-sized shapes; for anything icon-sized prefer {@link animatableShapesSmall}.
+ *
+ * Importing the map pulls in all 35 paths (~315 KB unminified). To ship only a few, import the
+ * individual `pathAnimatable*` constants instead.
+ */
+export declare const animatableShapes: Record<"circle" | "square" | "slanted" | "arch" | "semicircle" | "oval" | "pill" | "triangle" | "arrow" | "fan" | "diamond" | "clamshell" | "pentagon" | "gem" | "verySunny" | "sunny" | "fourSidedCookie" | "sixSidedCookie" | "sevenSidedCookie" | "nineSidedCookie" | "twelveSidedCookie" | "fourLeafClover" | "eightLeafClover" | "burst" | "softBurst" | "boom" | "softBoom" | "flower" | "puffy" | "puffyDiamond" | "ghostish" | "pixelCircle" | "pixelTriangle" | "bun" | "heart", string>;
+/**
+ * Every shape as a 120-point path in a 48 × 48 viewBox (38 × 38 shape, centred). Same guarantees
+ * as {@link animatableShapes} at an eighth of the size: the set for icons, avatars, indicators and
+ * FABs. Never mix paths from the two sets in one morph — their point counts differ.
+ */
+export declare const animatableShapesSmall: Record<"circle" | "square" | "slanted" | "arch" | "semicircle" | "oval" | "pill" | "triangle" | "arrow" | "fan" | "diamond" | "clamshell" | "pentagon" | "gem" | "verySunny" | "sunny" | "fourSidedCookie" | "sixSidedCookie" | "sevenSidedCookie" | "nineSidedCookie" | "twelveSidedCookie" | "fourLeafClover" | "eightLeafClover" | "burst" | "softBurst" | "boom" | "softBoom" | "flower" | "puffy" | "puffyDiamond" | "ghostish" | "pixelCircle" | "pixelTriangle" | "bun" | "heart", string>;
+/**
+ * Morphs an SVG `<path>` from its current `d` to `to` on an M3 spring (default `fastSpatial`,
+ * the token for shape morphs). Both paths must come from the same animatable set. Motion drives
+ * the progress; the spring's overshoot carries through into the shape. Under
+ * `prefers-reduced-motion` the shape swaps instantly (M3: turn off shape morphing).
+ *
+ * Starting a new morph mid-flight picks up from the in-between shape on screen, so stop the
+ * previous controls first — {@link shapeMorph} does this for you.
+ *
+ * ```ts
+ * morphShape(path, animatableShapesSmall.heart);
+ * ```
+ */
+export declare const morphShape: (path: SVGPathElement, to: string, spring?: SpringToken) => AnimationPlaybackControls | undefined;
+/**
+ * Attachment that keeps a `<path>` on `shape()` and morphs whenever it changes. The first shape
+ * renders without animating.
+ *
+ * ```svelte
+ * <svg viewBox="0 0 48 48">
+ *   <path
+ *     fill="currentColor"
+ *     {@attach shapeMorph(() => animatableShapesSmall[selected ? 'sunny' : 'circle'])}
+ *   />
+ * </svg>
+ * ```
+ */
+export declare const shapeMorph: (shape: () => string, spring?: SpringToken) => Attachment<SVGPathElement>;

package/dist/animation/shapeMorph.svelte.js

@@ -0,0 +1,112 @@
+import { animate, mix } from 'motion';
+import { untrack } from 'svelte';
+import * as large from './shapesAnimatable.js';
+import * as small from './shapesAnimatableSmall.js';
+import { springTokens, springTransition } from './spring.js';
+/**
+ * The 35 shapes of the M3 Expressive shape library, in the order of the spec sheet.
+ * https://m3.material.io/styles/shape
+ */
+export const shapeNames = [
+    'circle',
+    'square',
+    'slanted',
+    'arch',
+    'semicircle',
+    'oval',
+    'pill',
+    'triangle',
+    'arrow',
+    'fan',
+    'diamond',
+    'clamshell',
+    'pentagon',
+    'gem',
+    'verySunny',
+    'sunny',
+    'fourSidedCookie',
+    'sixSidedCookie',
+    'sevenSidedCookie',
+    'nineSidedCookie',
+    'twelveSidedCookie',
+    'fourLeafClover',
+    'eightLeafClover',
+    'burst',
+    'softBurst',
+    'boom',
+    'softBoom',
+    'flower',
+    'puffy',
+    'puffyDiamond',
+    'ghostish',
+    'pixelCircle',
+    'pixelTriangle',
+    'bun',
+    'heart'
+];
+const byName = (paths, prefix) => Object.fromEntries(shapeNames.map((name) => [name, paths[prefix + name[0].toUpperCase() + name.slice(1)]]));
+/**
+ * Every shape as a 720-point path in a 380 × 380 viewBox (`<svg viewBox="0 0 380 380">`). All
+ * share one command structure, start point and winding, so any two morph cleanly. Use these for
+ * large, hero-sized shapes; for anything icon-sized prefer {@link animatableShapesSmall}.
+ *
+ * Importing the map pulls in all 35 paths (~315 KB unminified). To ship only a few, import the
+ * individual `pathAnimatable*` constants instead.
+ */
+export const animatableShapes = byName(large, 'pathAnimatable');
+/**
+ * Every shape as a 120-point path in a 48 × 48 viewBox (38 × 38 shape, centred). Same guarantees
+ * as {@link animatableShapes} at an eighth of the size: the set for icons, avatars, indicators and
+ * FABs. Never mix paths from the two sets in one morph — their point counts differ.
+ */
+export const animatableShapesSmall = byName(small, 'pathAnimatableSmall');
+const prefersReducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+/**
+ * Morphs an SVG `<path>` from its current `d` to `to` on an M3 spring (default `fastSpatial`,
+ * the token for shape morphs). Both paths must come from the same animatable set. Motion drives
+ * the progress; the spring's overshoot carries through into the shape. Under
+ * `prefers-reduced-motion` the shape swaps instantly (M3: turn off shape morphing).
+ *
+ * Starting a new morph mid-flight picks up from the in-between shape on screen, so stop the
+ * previous controls first — {@link shapeMorph} does this for you.
+ *
+ * ```ts
+ * morphShape(path, animatableShapesSmall.heart);
+ * ```
+ */
+export const morphShape = (path, to, spring = springTokens.fastSpatial) => {
+    const from = path.getAttribute('d');
+    if (!from || from === to || prefersReducedMotion()) {
+        path.setAttribute('d', to);
+        return;
+    }
+    const shape = mix(from, to);
+    return animate(0, 1, {
+        ...springTransition(spring),
+        onUpdate: (progress) => path.setAttribute('d', shape(progress))
+    });
+};
+/**
+ * Attachment that keeps a `<path>` on `shape()` and morphs whenever it changes. The first shape
+ * renders without animating.
+ *
+ * ```svelte
+ * <svg viewBox="0 0 48 48">
+ *   <path
+ *     fill="currentColor"
+ *     {@attach shapeMorph(() => animatableShapesSmall[selected ? 'sunny' : 'circle'])}
+ *   />
+ * </svg>
+ * ```
+ */
+export const shapeMorph = (shape, spring) => (path) => {
+    let controls;
+    $effect(() => {
+        const to = shape();
+        untrack(() => {
+            controls?.stop();
+            controls = morphShape(path, to, spring);
+        });
+    });
+    return () => controls?.stop();
+};