@noxlovette/material 0.6.1 → 0.7.0

package/dist/components/nav/rail/Rail.mdx

@@ -18,8 +18,9 @@ import * as RailStories from './Rail.stories.svelte';
 
 ## Anatomy
 
-- **`Rail`** is the container: the sidebar, a spacer that reserves its width in the page, and the
-  scrim shown while it's expanded on medium windows.
+- **`Rail`** is the container: the sidebar, the room it takes in the page (see Layout), and the
+  scrim shown while it's expanded on medium windows. An optional header holds the menu toggle and
+  a FAB.
 - **`RailItem`** is one destination. It detects the active route, shows an optional `badge` (a
   count, or `-1` for a dot), and lays itself out for the collapsed or expanded rail.
 - **`railStore`** exposes the collapsed state to components outside the rail.
@@ -29,40 +30,79 @@ import * as RailStories from './Rail.stories.svelte';
 The rail shows from `md` up and is hidden below it. For small windows, mount a `Navbar` with the
 same destinations; it hides itself from `md` up, so the two never show together.
 
-| Window         | Collapsed rail | Expanded rail                                       |
-| -------------- | -------------- | --------------------------------------------------- |
-| Small (< `md`) | Hidden         | Hidden                                              |
-| Medium (`md`)  | 96dp           | Overlays content over a scrim; outside click closes |
-| Large (`lg`+)  | 96dp           | Pushes content aside                                |
+| Window         | Collapsed rail | Expanded rail                                                            |
+| -------------- | -------------- | ------------------------------------------------------------------------ |
+| Small (< `md`) | Hidden         | Hidden                                                                   |
+| Medium (`md`)  | 96dp           | **Modal**: over a scrim; closes on scrim click, Escape, or a destination |
+| Large (`lg`+)  | 96dp           | **Standard**: pushes content aside, stays open until toggled             |
+
+## Spec
+
+Values follow the M3 Expressive
+[navigation rail tokens](https://m3.material.io/components/navigation-rail/specs). The container
+uses the spec's optional `surface-container` role rather than the default `surface`: that's the
+window colour `App` paints, so the rail belongs to the window and `surface` panes sit beside it. The off-grid
+ones are `--md-comp-nav-rail-*` properties in `styles/components.css`, so a theme can override
+them.
+
+|                  | Collapsed                                                                         | Expanded                                                         |
+| ---------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Container        | 96dp, `surface`                                                                   | Hugs content, 220–360dp. Modal adds elevation 3 and 16dp corners |
+| Top space        | 44dp, then at least 40dp below the header                                         | Same                                                             |
+| Destination      | 64dp tall, 4dp apart                                                              | 56dp tall, touching, 20dp side padding                           |
+| Active indicator | 56×32dp around the icon, label 4dp below                                          | 56dp pill around icon and label, 16dp padding, 8dp gap           |
+| Label            | Label medium; active `secondary`                                                  | Label large; active `on-secondary-container`                     |
+| States           | `on-secondary-container` layer: 8% hover, 10% focus and pressed, on the indicator | Same                                                             |
+
+The whole row is the target, however narrow the indicator. The active icon fills; its weight
+stays the same.
+
+## Expanding
+
+Expanding is one spatial spring, following Compose's `WideNavigationRail`. The width, the gap
+between destinations (4dp → 0), each destination's height (64 → 56dp), and its indicator
+(56×32 → the full pill) all move together. The indicator stays anchored and the icon keeps its x,
+so nothing moves sideways. The label fades out, switches from under the icon to beside it at the
+halfway point (label medium → label large), then slides in as it fades back. An interrupted
+spring reverses from where it is. Under reduced motion the rail jumps to the end state.
+
+Selecting a destination grows its active indicator from the centre out to its edges on
+`fastSpatial`, fading in as it grows, and the one losing the selection shrinks back the same way
+(after Compose's `NavigationRailItem`). The state layer stays on top of it. Under reduced motion
+the indicator just appears.
 
 ## Layout
 
-The rail renders a spacer next to itself that takes the rail's width. Put the rail and your
-content in a flex row and the content moves aside on its own, with no `margin-left`:
+Mount the rail anywhere inside `App`; the page makes room for it on its own. A
+viewport-anchored rail publishes `--md-rail-inset` on `<html>`: 0 below `md`, the collapsed
+width on medium windows (the expanded rail is modal there and overlays), and the rail's live
+width from `lg`, so the content moves aside in step with the spring. `App`'s shell pads by it and
+`AppBar` starts at it, so there's no `md:ml-24` anywhere. A custom shell or another fixed surface
+uses `ps-(--md-rail-inset)` / `left-(--md-rail-inset)`.
 
 ```svelte
-<div class="flex min-h-dvh">
+<App>
   <Rail bind:collapsed>
     <RailItem label="Home" href="/" iconProps={{ name: 'house' }} />
     <RailItem label="Messages" href="/messages" iconProps={{ name: 'mail' }} badge={5} />
   </Rail>
-  <div class="min-w-spacing-0 flex-1">
-    {@render children()}
-  </div>
-</div>
-
-<Navbar>
-  <NavbarItem label="Home" href="/" iconProps={{ name: 'house' }} />
-  <NavbarItem label="Messages" href="/messages" iconProps={{ name: 'mail' }} badge={5} />
-</Navbar>
+  <AppBar title="Home" />
+  {@render children()}
+  <Navbar>
+    <NavbarItem label="Home" href="/" iconProps={{ name: 'house' }} />
+    <NavbarItem label="Messages" href="/messages" iconProps={{ name: 'mail' }} badge={5} />
+  </Navbar>
+</App>
 ```
 
 - **Under an app bar:** pass the bar's height in px to `railTop` so the rail starts below it.
 - **Anchoring:** `anchor="viewport"` (the default) fixes the rail to the window's leading edge.
   `anchor="parent"` positions it inside the nearest positioned ancestor, for embedded layouts
-  and demos.
-- **Extras:** the `fab` snippet places a FAB above the destinations. `expandable={false}` removes
-  the menu toggle.
+  and demos. It doesn't touch `--md-rail-inset`; instead it renders a spacer beside itself, so
+  put it and the content in a flex row.
+- **Extras:** the `fab` snippet places a FAB above the destinations, in the same 56dp column as
+  the indicators. `expandable={false}` removes the menu toggle; with no FAB either, the header
+  and its 40dp gap go too.
 
 <Canvas of={RailStories.WithFAB} />
 
@@ -70,4 +110,6 @@ content in a flex row and the content moves aside on its own, with no `margin-le
 
 - **Active item.** The active item gets `aria-current="page"`.
 - **Disabled items** set `aria-disabled` and leave the tab order but stay visible.
-- **Keyboard.** Every item is a link reachable with Tab; the menu toggle is a real button.
+- **Keyboard.** Every item is a link reachable with Tab; the focus ring goes around the
+  indicator. The menu toggle is a real button with `aria-expanded`, and Escape closes the modal
+  rail.

package/dist/components/nav/rail/Rail.stories.svelte

@@ -25,6 +25,17 @@
   });
 </script>
 
+<script lang="ts">
+  // Playground: clicking a destination selects it, to show the indicator growing from its centre.
+  const destinations = [
+    { label: 'Home', icon: 'house', badge: 0 },
+    { label: 'Inbox', icon: 'mail', badge: 4 },
+    { label: 'Chat', icon: 'chat', badge: -1 },
+    { label: 'Settings', icon: 'settings', badge: 0 }
+  ] as const;
+  let current = $state<string>('Home');
+</script>
+
 <Story name="Playground">
   {#snippet template(args)}
     <div class="bg-md-sys-color-surface-variant relative h-[420px] overflow-hidden rounded-2xl">
@@ -34,10 +45,19 @@
         expandable={args.expandable}
         rounded={args.rounded}
       >
-        <RailItem label="Home" href="/" iconProps={{ name: 'house' }} selected />
-        <RailItem label="Inbox" href="#" iconProps={{ name: 'mail' }} badge={4} />
-        <RailItem label="Chat" href="#" iconProps={{ name: 'chat' }} badge={-1} />
-        <RailItem label="Settings" href="#" iconProps={{ name: 'settings' }} />
+        {#each destinations as d (d.label)}
+          <RailItem
+            label={d.label}
+            href="#{d.label.toLowerCase()}"
+            iconProps={{ name: d.icon }}
+            badge={d.badge}
+            selected={current === d.label}
+            onclick={(e) => {
+              e.preventDefault();
+              current = d.label;
+            }}
+          />
+        {/each}
         <RailItem label="Disabled" href="#" iconProps={{ name: 'block' }} disabled />
       </Rail>
     </div>

package/dist/components/nav/rail/Rail.stories.svelte.d.ts

@@ -1,19 +1,4 @@
 import Rail from './Rail.svelte';
-interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
-        $$bindings?: Bindings;
-    } & Exports;
-    (internal: unknown, props: {
-        $$events?: Events;
-        $$slots?: Slots;
-    }): Exports & {
-        $set?: any;
-        $on?: any;
-    };
-    z_$$bindings?: Bindings;
-}
-declare const Rail: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
-type Rail = InstanceType<typeof Rail>;
+declare const Rail: import("svelte").Component<Record<string, never>, {}, "">;
+type Rail = ReturnType<typeof Rail>;
 export default Rail;

package/dist/components/nav/rail/Rail.svelte

@@ -2,17 +2,21 @@
 @component
 Material 3 Navigation Rail.
 
-Navigation rails provide access to primary destinations in apps when using tablet and desktop screens.
-On mobile (< md) it automatically renders as a bottom navigation bar.
+Navigation rails give access to primary destinations on medium and larger windows. Collapsed it's
+96dp wide; expanded it shows labels beside the icons. On large windows the expanded rail pushes
+the content aside (standard); on medium windows it opens over it, above a scrim (modal), and
+closes on a scrim click, Escape, or picking a destination. Below `md` it's hidden: mount a
+`Navbar` for small windows.
 
-@see https://m3.material.io/components/navigation-rail/overview
+@see https://m3.material.io/components/navigation-rail/specs
 -->
 <script lang="ts">
-  import { clickOutside } from '../../../attachments/index.js';
   import clsx from 'clsx';
   import { setContext, untrack } from 'svelte';
+  import { animate, type AnimationPlaybackControls } from 'motion';
   import type { RailProps } from './types';
   import ButtonIcon from '../../buttons/ButtonIcon.svelte';
+  import { springTokens, springTransition } from '../../../animation/spring.js';
   import { rail } from './theme';
   import { NavigationMenu } from 'bits-ui';
   import { railStore } from './railStore.svelte.js';
@@ -27,13 +31,19 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
     railTop = 0,
     expandLabel = 'Expand navigation',
     collapseLabel = 'Collapse navigation',
-    class: className
+    class: className,
+    showHelp: _showHelp,
+    withNavbar: _withNavbar,
+    ...restProps
   }: RailProps = $props();
 
   const expanded = $derived(!collapsed);
   const railCtx = {
     get collapsed() {
       return collapsed;
+    },
+    get progress() {
+      return progress;
     }
   };
   setContext('rail', railCtx);
@@ -42,64 +52,169 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
     railStore.collapsed = collapsed;
   });
 
-  const { base, items, ghost, scrim } = $derived(rail({ expanded, anchor, rounded }));
-  const railBaseClass = $derived(`${base({ class: clsx(className) })} rail-base`);
+  const styles = $derived(rail({ expanded, anchor, rounded, header: expandable || !!fab }));
   const toggleClass = $derived(collapsed ? 'cursor-e-resize' : 'cursor-w-resize');
-  const cssVars = $derived(`--rail-top: ${railTop}px;`);
+
+  let railEl = $state<HTMLElement>();
+  let ghostEl = $state<HTMLElement>();
+  let scrimEl = $state<HTMLElement>();
+
+  /* The scrim is only displayed while the expanded rail is modal (medium windows). */
+  const isModal = () => !!scrimEl && getComputedStyle(scrimEl).display !== 'none';
+
+  /*
+    Making room for the rail. A viewport-anchored rail publishes its drawn width on <html>
+    (--md-rail-width, every frame while it springs) plus --md-rail-rest, its collapsed width;
+    styles/components.css turns them into --md-rail-inset per window size, which App's shell and
+    AppBar use. A parent-anchored rail instead renders a ghost in the layout that holds its place
+    the same way: the rail's width from lg, the collapsed width on medium windows, where the
+    expanded rail overlays the content.
+  */
+  $effect(() => {
+    const el = railEl;
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    const target = anchor === 'viewport' ? document.documentElement : ghostEl;
+    if (!target) return;
+    if (anchor === 'viewport') {
+      target.style.setProperty(
+        '--md-rail-rest',
+        'var(--md-comp-nav-rail-collapsed-container-width)'
+      );
+    }
+    const property = anchor === 'viewport' ? '--md-rail-width' : '--rail-width';
+    const observer = new ResizeObserver(() => {
+      target.style.setProperty(property, `${el.offsetWidth}px`);
+    });
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      target.style.removeProperty(property);
+      if (anchor === 'viewport') target.style.removeProperty('--md-rail-rest');
+    };
+  });
+
+  /*
+    Expanding is one spring on `progress`, 0 collapsed to 1 expanded, on spatial: a container
+    reshaping, not a navigation transition, so no fastSpatial bounce. It's the choreography of
+    Compose's WideNavigationRail: `--rail-p` carries the progress to the destinations (their
+    height, indicator and icon interpolate on it; the label fades out, swaps sides at the halfway
+    point, and fades back in) and to the gap between them, and the width follows it here.
+
+    The classes hold each end state, so SSR and reduced motion need no JS. For the width, measure
+    where the rail is drawn before the change and where the new classes put it, and map the
+    progress onto that span; an interrupted spring picks up from where it's drawn.
+  */
+  const SPRING = springTransition(springTokens.spatial);
+  let progress = $state(untrack(() => (collapsed ? 0 : 1)));
+  let widthFrom: number | null = null;
+  let progressFrom = 0;
+  let spring: AnimationPlaybackControls | undefined;
+
+  const clearWidth = (el: HTMLElement) =>
+    Object.assign(el.style, { width: '', minWidth: '', maxWidth: '' });
+
+  $effect.pre(() => {
+    void expanded;
+    if (!railEl) return;
+    widthFrom = railEl.getBoundingClientRect().width;
+    progressFrom = untrack(() => progress);
+  });
+
+  $effect(() => {
+    const target = expanded ? 1 : 0;
+    const el = railEl;
+    const from = widthFrom;
+    widthFrom = null;
+    if (!el || from === null) return;
+
+    spring?.stop();
+    clearWidth(el);
+    const to = el.getBoundingClientRect().width;
+    if (progressFrom === target || matchMedia('(prefers-reduced-motion: reduce)').matches) {
+      progress = target;
+      return;
+    }
+
+    // Lift the expanded min/max for the ride, or the width would snap to 220dp at the start.
+    Object.assign(el.style, { width: `${from}px`, minWidth: '0', maxWidth: 'none' });
+    const start = progressFrom;
+    const controls = animate(start, target, {
+      ...SPRING,
+      onUpdate: (p) => {
+        progress = p;
+        el.style.width = `${from + ((to - from) * (p - start)) / (target - start)}px`;
+      },
+      onComplete: () => {
+        progress = target;
+        clearWidth(el);
+      }
+    });
+    spring = controls;
+  });
+
+  function onKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape' && expanded && isModal()) {
+      collapsed = true;
+    }
+  }
+
+  // Picking a destination closes the modal rail; the standard one stays as it is.
+  function onNavClick(event: MouseEvent) {
+    if (expanded && isModal() && (event.target as Element).closest('a[href]')) {
+      collapsed = true;
+    }
+  }
 </script>
 
-<!-- Push ghost: hidden on mobile, becomes flex item on md+ to push content -->
-<div class={ghost()}></div>
+<svelte:window onkeydown={onKeydown} />
+
+{#if anchor === 'parent'}
+  <div
+    bind:this={ghostEl}
+    class={styles.ghost()}
+    style="--rail-width: var(--md-comp-nav-rail-collapsed-container-width)"
+  ></div>
+{/if}
 
-<!-- Tablet scrim (md:block lg:hidden) — overlays content on expand -->
 <div
-  class={`${scrim()} rail-scrim`}
-  data-expanded={expanded}
+  bind:this={scrimEl}
+  class={styles.scrim()}
   onclick={() => (collapsed = true)}
   role="presentation"
 ></div>
 
-<!-- Desktop/tablet sidebar rail -->
 <div
-  class={railBaseClass}
-  style={cssVars}
+  bind:this={railEl}
+  {...restProps}
+  class={styles.base({ class: clsx(className) })}
+  style:--rail-top="{railTop}px"
+  style:--rail-p={progress}
   data-expanded={expanded}
-  {@attach expanded && clickOutside(() => (collapsed = true))}
 >
-  {#if expandable}
-    <ButtonIcon
-      variant="standard"
-      type="button"
-      tooltipContent={collapsed ? expandLabel : collapseLabel}
-      iconProps={{ name: `${collapsed ? 'menu' : 'menu_open'}` }}
-      class={toggleClass}
-      onclick={() => (collapsed = !collapsed)}
-    />
-  {/if}
+  {#if expandable || fab}
+    <div class={styles.header()}>
+      {#if expandable}
+        <div class={styles.menu()}>
+          <ButtonIcon
+            variant="standard"
+            type="button"
+            tooltipContent={collapsed ? expandLabel : collapseLabel}
+            iconProps={{ name: collapsed ? 'menu' : 'menu_open', transition: 'rotate' }}
+            aria-expanded={expanded}
+            class={toggleClass}
+            onclick={() => (collapsed = !collapsed)}
+          />
+        </div>
+      {/if}
 
-  {@render fab?.()}
+      {@render fab?.()}
+    </div>
+  {/if}
 
-  <NavigationMenu.Root orientation="vertical" class="w-full">
-    <NavigationMenu.List class={`${items()} rail-items`}>
+  <!-- The click is delegated from the links inside; Enter on a link fires it too. -->
+  <NavigationMenu.Root orientation="vertical" class={styles.nav()} onclick={onNavClick}>
+    <NavigationMenu.List class={styles.items()}>
       {@render children?.()}
     </NavigationMenu.List>
   </NavigationMenu.Root>
 </div>
-
-<style>
-  .rail-scrim {
-    opacity: 0;
-    pointer-events: none;
-    background-color: transparent;
-    z-index: -1;
-    transition: opacity var(--md-sys-motion-duration-effects-spring)
-      var(--md-sys-motion-timing-function-effects-spring);
-  }
-
-  .rail-scrim[data-expanded='true'] {
-    opacity: 1;
-    pointer-events: auto;
-    background-color: rgb(0 0 0 / 0.4);
-    z-index: var(--z-layer-rail);
-  }
-</style>

package/dist/components/nav/rail/Rail.svelte.d.ts

@@ -2,10 +2,13 @@ import type { RailProps } from './types';
 /**
  * Material 3 Navigation Rail.
  *
- * Navigation rails provide access to primary destinations in apps when using tablet and desktop screens.
- * On mobile (< md) it automatically renders as a bottom navigation bar.
+ * Navigation rails give access to primary destinations on medium and larger windows. Collapsed it's
+ * 96dp wide; expanded it shows labels beside the icons. On large windows the expanded rail pushes
+ * the content aside (standard); on medium windows it opens over it, above a scrim (modal), and
+ * closes on a scrim click, Escape, or picking a destination. Below `md` it's hidden: mount a
+ * `Navbar` for small windows.
  *
- * @see https://m3.material.io/components/navigation-rail/overview
+ * @see https://m3.material.io/components/navigation-rail/specs
  */
 declare const Rail: import("svelte").Component<RailProps, {}, "collapsed">;
 type Rail = ReturnType<typeof Rail>;