@noxlovette/material 0.5.1 → 0.6.1

package/dist/components/nav/appbar/theme.js

@@ -1,38 +1,174 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
+/*
+  M3 Expressive app bar (https://m3.material.io/components/app-bars/specs), laid out on one
+  3-column grid (leading · text · trailing) so the size can change per breakpoint in CSS alone:
+  - small: 64dp, one row, title between the buttons.
+  - medium/large flexible: an actions row (8dp top, 48dp) above a headline block spanning all
+    columns (16dp inset, 12dp bottom) that wraps and grows; min height 112/120dp, or 136/152dp
+    with a subtitle.
+  4dp container padding and 0 gap between 48dp icon buttons throughout. Every class below is a
+  literal so the Tailwind scanner sees it; `appbarSize` picks them per breakpoint.
+*/
+const sizeClasses = {
+    small: {
+        small: {
+            row: 'grid-rows-[4rem] pt-spacing-0 min-h-spacing-800',
+            rowSubtitle: '',
+            textContainer: 'col-start-2 col-span-1 row-start-1 self-center ps-(--lead) pe-(--trail) pt-spacing-0 pb-spacing-0',
+            title: 'md-sys-typescale-title-large line-clamp-1',
+            subtitle: 'md-sys-typescale-label-medium line-clamp-1'
+        },
+        medium: {
+            row: 'grid-rows-[3rem_1fr] pt-spacing-100 min-h-28',
+            rowSubtitle: 'min-h-34',
+            textContainer: 'col-start-1 col-span-3 row-start-2 self-end ps-spacing-200 pe-spacing-200 pt-spacing-50 pb-spacing-150',
+            title: 'md-sys-typescale-headline-medium line-clamp-none',
+            subtitle: 'md-sys-typescale-title-small line-clamp-none'
+        },
+        large: {
+            row: 'grid-rows-[3rem_1fr] pt-spacing-100 min-h-30',
+            rowSubtitle: 'min-h-38',
+            textContainer: 'col-start-1 col-span-3 row-start-2 self-end ps-spacing-200 pe-spacing-200 pt-spacing-50 pb-spacing-150',
+            title: 'md-sys-typescale-display-small line-clamp-none',
+            subtitle: 'md-sys-typescale-title-medium line-clamp-none'
+        }
+    },
+    medium: {
+        small: {
+            row: 'md:grid-rows-[4rem] md:pt-spacing-0 md:min-h-spacing-800',
+            rowSubtitle: '',
+            textContainer: 'md:col-start-2 md:col-span-1 md:row-start-1 md:self-center md:ps-(--lead) md:pe-(--trail) md:pt-spacing-0 md:pb-spacing-0',
+            title: 'md:md-sys-typescale-title-large md:line-clamp-1',
+            subtitle: 'md:md-sys-typescale-label-medium md:line-clamp-1'
+        },
+        medium: {
+            row: 'md:grid-rows-[3rem_1fr] md:pt-spacing-100 md:min-h-28',
+            rowSubtitle: 'md:min-h-34',
+            textContainer: 'md:col-start-1 md:col-span-3 md:row-start-2 md:self-end md:ps-spacing-200 md:pe-spacing-200 md:pt-spacing-50 md:pb-spacing-150',
+            title: 'md:md-sys-typescale-headline-medium md:line-clamp-none',
+            subtitle: 'md:md-sys-typescale-title-small md:line-clamp-none'
+        },
+        large: {
+            row: 'md:grid-rows-[3rem_1fr] md:pt-spacing-100 md:min-h-30',
+            rowSubtitle: 'md:min-h-38',
+            textContainer: 'md:col-start-1 md:col-span-3 md:row-start-2 md:self-end md:ps-spacing-200 md:pe-spacing-200 md:pt-spacing-50 md:pb-spacing-150',
+            title: 'md:md-sys-typescale-display-small md:line-clamp-none',
+            subtitle: 'md:md-sys-typescale-title-medium md:line-clamp-none'
+        }
+    },
+    large: {
+        small: {
+            row: 'lg:grid-rows-[4rem] lg:pt-spacing-0 lg:min-h-spacing-800',
+            rowSubtitle: '',
+            textContainer: 'lg:col-start-2 lg:col-span-1 lg:row-start-1 lg:self-center lg:ps-(--lead) lg:pe-(--trail) lg:pt-spacing-0 lg:pb-spacing-0',
+            title: 'lg:md-sys-typescale-title-large lg:line-clamp-1',
+            subtitle: 'lg:md-sys-typescale-label-medium lg:line-clamp-1'
+        },
+        medium: {
+            row: 'lg:grid-rows-[3rem_1fr] lg:pt-spacing-100 lg:min-h-28',
+            rowSubtitle: 'lg:min-h-34',
+            textContainer: 'lg:col-start-1 lg:col-span-3 lg:row-start-2 lg:self-end lg:ps-spacing-200 lg:pe-spacing-200 lg:pt-spacing-50 lg:pb-spacing-150',
+            title: 'lg:md-sys-typescale-headline-medium lg:line-clamp-none',
+            subtitle: 'lg:md-sys-typescale-title-small lg:line-clamp-none'
+        },
+        large: {
+            row: 'lg:grid-rows-[3rem_1fr] lg:pt-spacing-100 lg:min-h-30',
+            rowSubtitle: 'lg:min-h-38',
+            textContainer: 'lg:col-start-1 lg:col-span-3 lg:row-start-2 lg:self-end lg:ps-spacing-200 lg:pe-spacing-200 lg:pt-spacing-50 lg:pb-spacing-150',
+            title: 'lg:md-sys-typescale-display-small lg:line-clamp-none',
+            subtitle: 'lg:md-sys-typescale-title-medium lg:line-clamp-none'
+        }
+    },
+    extraLarge: {
+        small: {
+            row: 'xl:grid-rows-[4rem] xl:pt-spacing-0 xl:min-h-spacing-800',
+            rowSubtitle: '',
+            textContainer: 'xl:col-start-2 xl:col-span-1 xl:row-start-1 xl:self-center xl:ps-(--lead) xl:pe-(--trail) xl:pt-spacing-0 xl:pb-spacing-0',
+            title: 'xl:md-sys-typescale-title-large xl:line-clamp-1',
+            subtitle: 'xl:md-sys-typescale-label-medium xl:line-clamp-1'
+        },
+        medium: {
+            row: 'xl:grid-rows-[3rem_1fr] xl:pt-spacing-100 xl:min-h-28',
+            rowSubtitle: 'xl:min-h-34',
+            textContainer: 'xl:col-start-1 xl:col-span-3 xl:row-start-2 xl:self-end xl:ps-spacing-200 xl:pe-spacing-200 xl:pt-spacing-50 xl:pb-spacing-150',
+            title: 'xl:md-sys-typescale-headline-medium xl:line-clamp-none',
+            subtitle: 'xl:md-sys-typescale-title-small xl:line-clamp-none'
+        },
+        large: {
+            row: 'xl:grid-rows-[3rem_1fr] xl:pt-spacing-100 xl:min-h-30',
+            rowSubtitle: 'xl:min-h-38',
+            textContainer: 'xl:col-start-1 xl:col-span-3 xl:row-start-2 xl:self-end xl:ps-spacing-200 xl:pe-spacing-200 xl:pt-spacing-50 xl:pb-spacing-150',
+            title: 'xl:md-sys-typescale-display-small xl:line-clamp-none',
+            subtitle: 'xl:md-sys-typescale-title-medium xl:line-clamp-none'
+        }
+    }
+};
+/**
+ * Resolves `size` (one value, or one per breakpoint like `PaneGrid`'s props) into per-slot
+ * classes. Sizes cascade upward from the smallest breakpoint given, like Tailwind prefixes.
+ */
+export function appbarSize(size, hasSubtitle) {
+    const tiers = typeof size === 'string' ? { small: size } : { small: 'small', ...size };
+    const pick = (slot) => Object.entries(tiers)
+        .map(([bp, s]) => sizeClasses[bp][s][slot])
+        .join(' ');
+    return {
+        row: `${pick('row')} ${hasSubtitle ? pick('rowSubtitle') : ''}`,
+        textContainer: pick('textContainer'),
+        title: pick('title'),
+        subtitle: pick('subtitle')
+    };
+}
 export const appbar = tv({
     slots: {
-        base: 'fixed top-0 left-0 w-full flex flex-col z-30',
-        row: 'h-16 py-1 flex w-full items-center justify-between',
-        childrenRow: 'w-full px-2 pb-2',
+        base: 'fixed top-spacing-0 left-spacing-0 w-full flex flex-col z-layer-bar transition-colors md-sys-motion-effects',
+        row: 'grid w-full items-center px-spacing-50',
+        childrenRow: 'w-full px-spacing-100 pb-spacing-100',
         ghost: 'w-full shrink-0 pointer-events-none',
-        textContainer: 'flex flex-col items-start gap-0.5 grow',
-        title: 'text-md-sys-color-on-surface md-sys-typescale-title-large line-clamp-1   capitalize ',
-        subtitle: 'text-md-sys-color-on-surface-variant md-sys-typescale-label-medium',
-        leading: 'text-md-sys-color-on-surface ml-0.5',
-        trailing: 'text-md-sys-color-on-surface-variant mr-4 md:mr-6 lg:mr-8'
+        textContainer: 'flex min-w-spacing-0 flex-col gap-spacing-25 [--lead:0.25rem] [--trail:0.25rem]',
+        title: 'text-md-sys-color-on-surface',
+        subtitle: 'text-md-sys-color-on-surface-variant',
+        leading: 'text-md-sys-color-on-surface col-start-1 row-start-1 flex shrink-0 items-center justify-self-start',
+        trailing: 'text-md-sys-color-on-surface-variant col-start-3 row-start-1 flex shrink-0 items-center justify-self-end',
+        search: 'state-layer relative flex h-spacing-700 w-full min-w-spacing-0 cursor-text items-center rounded-full ps-spacing-200 pe-spacing-200 transition-colors md-sys-motion-effects before:rounded-full hover:before:bg-md-sys-color-on-surface/8 focus-within:outline-3 focus-within:outline-offset-2 focus-within:outline-md-sys-color-secondary',
+        searchInput: 'md-sys-typescale-body-large text-md-sys-color-on-surface placeholder:text-md-sys-color-on-surface-variant w-full min-w-spacing-0 bg-transparent text-start outline-none placeholder-shown:text-center [&::-webkit-search-cancel-button]:hidden',
+        searchTrailing: 'text-md-sys-color-on-surface-variant flex shrink-0 items-center'
     },
     variants: {
-        scrolled: {
-            true: { base: 'shadow-elevation-1 bg-md-sys-color-surface-container' },
-            false: {
-                base: 'shadow-elevation-0 bg-md-sys-color-surface md:bg-md-sys-color-surface-container'
-            }
-        },
-        searchContainer: {
-            true: '',
-            false: ''
+        align: {
+            start: { row: 'grid-cols-[auto_1fr_auto]', textContainer: 'items-start text-start' },
+            // 1fr side columns centre a small bar's title on the bar, not between uneven button groups.
+            center: { row: 'grid-cols-[1fr_auto_1fr]', textContainer: 'items-center text-center' }
         },
-        noTrailing: {
+        scrolled: {
             true: {
-                textContainer: 'pr-4 md:pr-6 lg:pr-8'
+                base: 'bg-md-sys-color-surface-container',
+                search: 'bg-md-sys-color-surface-container-highest'
             },
-            false: ''
+            false: { base: 'bg-md-sys-color-surface', search: 'bg-md-sys-color-surface-container' }
         },
-        noLeading: {
+        // Search app bar: the search container fills the text column, 8dp from the buttons.
+        searchContainer: {
             true: {
-                textContainer: 'pl-4 md:pl-6 lg:pl-8'
+                row: 'grid-cols-[auto_1fr_auto]',
+                textContainer: '[--lead:0.5rem] [--trail:0.5rem]'
             },
             false: ''
-        }
+        },
+        hasSearchTrailing: { true: { search: 'pe-spacing-50' }, false: '' },
+        noTrailing: { true: '', false: '' },
+        noLeading: { true: '', false: '' }
+    },
+    compoundVariants: [
+        // A title with no button beside it sits at the 16dp inset.
+        { align: 'start', noLeading: true, class: { textContainer: '[--lead:1rem]' } },
+        { align: 'start', noTrailing: true, class: { textContainer: '[--trail:1rem]' } },
+        { searchContainer: true, noLeading: true, class: { textContainer: '[--lead:0.75rem]' } },
+        { searchContainer: true, noTrailing: true, class: { textContainer: '[--trail:0.75rem]' } }
+    ],
+    defaultVariants: {
+        align: 'start',
+        scrolled: false,
+        searchContainer: false
     }
 });

package/dist/components/nav/appbar/types.d.ts

@@ -1,14 +1,10 @@
 import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-import type { AppbarVariants } from './theme.js';
-/**
- * Props for the AppBar component.
- */
-export type AppBarProps = AppbarVariants & HTMLAttributes<HTMLElementTagNameMap['nav']> & {
+import type { HTMLAttributes, HTMLInputAttributes } from 'svelte/elements';
+import type { Responsive } from '../../containers/pane/theme.js';
+import type { AppBarSize, AppbarVariants } from './theme.js';
+type AppBarBaseProps = Pick<AppbarVariants, 'align'> & HTMLAttributes<HTMLElementTagNameMap['nav']> & {
     /** Extra content rendered in a full-width row below the title, e.g. a Breadcrumb trail. */
     children?: Snippet;
-    /** The main title of the app bar. */
-    title: string;
     /** An optional subtitle displayed below the title. */
     subtitle?: string;
     /** Additional props for the title `<h1>` element (e.g. `data-cy`). */
@@ -19,10 +15,51 @@ export type AppBarProps = AppbarVariants & HTMLAttributes<HTMLElementTagNameMap[
     leading?: Snippet;
     /** A snippet to be rendered on the right side (e.g., action icons). */
     trailing?: Snippet;
-    /** Whether to show a back button in the leading section. */
+    /** Renders a back button in the leading section (ignored when `leading` is set). */
     showBack?: boolean;
+    /** Called by the back button. Defaults to `history.back()`. */
+    onback?: () => void;
+    /**
+     * The element whose scroll switches the bar to its on-scroll color. Defaults to the page
+     * (`window`); pass a scrolling container, e.g. a `Pane`'s element, when content scrolls there.
+     */
+    scrollContainer?: HTMLElement | null;
     /** Renders an invisible same-height spacer after the fixed bar so page content isn't obscured. */
     ghost?: boolean;
     /** Additional classes passed onto the row element */
     rowClass?: string;
 };
+/** A titled app bar: small, or the Expressive medium/large flexible bars. */
+export type TitleAppBarProps = AppBarBaseProps & {
+    /** The main title of the app bar. */
+    title: string;
+    /**
+     * `small` (64dp, one line), `medium` or `large` (flexible, wrapping headline). Pass one per
+     * breakpoint to adapt to the window, e.g. `{ small: 'small', large: 'large' }`; tiers you
+     * leave out inherit from the one below, and below the first given tier the bar is `small`.
+     */
+    size?: Responsive<AppBarSize>;
+    search?: never;
+    query?: never;
+    searchProps?: never;
+    searchTrailing?: never;
+};
+/** A search app bar: a search field in place of the title, always 64dp. */
+export type SearchAppBarProps = AppBarBaseProps & {
+    /** Hint text in the search field. Setting it makes this a search app bar. */
+    search: string;
+    /** The search query. */
+    query?: string;
+    /** Screen title; rendered for assistive tech only. */
+    title?: string;
+    /** Props for the search `<input>`, e.g. `onfocus` to open a search view. */
+    searchProps?: HTMLInputAttributes;
+    /** An action inside the search field, e.g. a mic icon button. */
+    searchTrailing?: Snippet;
+    size?: never;
+};
+/**
+ * Props for the AppBar component.
+ */
+export type AppBarProps = TitleAppBarProps | SearchAppBarProps;
+export {};

package/dist/components/nav/breadcrumb/Breadcrumb.stories.svelte

@@ -5,6 +5,7 @@
 
   const { Story } = defineMeta({
     title: 'Navigation/Breadcrumb',
+    tags: ['autodocs'],
     component: Breadcrumb,
     argTypes: {
       color: { control: 'select', options: ['primary', 'secondary', 'tertiary', 'surface'] }

package/dist/components/nav/breadcrumb/theme.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../../utils/tv.js';
 export type BreadcrumbVariants = VariantProps<typeof breadcrumb>;
 export declare const breadcrumb: import("tailwind-variants").TVReturnType<{
     color: {

package/dist/components/nav/breadcrumb/theme.js

@@ -1,12 +1,12 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const breadcrumb = tv({
     slots: {
         base: 'flex',
-        list: 'flex flex-wrap items-center gap-1',
-        item: 'flex items-center gap-1',
-        link: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant md-sys-state-focus-indicator relative inline-flex min-h-12 items-center rounded-full px-3 transition-colors md-sys-motion-fast-effects',
-        text: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant px-1 py-0.5',
-        current: 'md-sys-typescale-label-large font-bold px-1 py-0.5',
+        list: 'flex flex-wrap items-center gap-spacing-50',
+        item: 'flex items-center gap-spacing-50',
+        link: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant md-sys-state-focus-indicator relative inline-flex min-h-spacing-600 items-center rounded-full px-spacing-150 transition-colors md-sys-motion-fast-effects',
+        text: 'md-sys-typescale-label-large text-md-sys-color-on-surface-variant px-spacing-50 py-spacing-25',
+        current: 'md-sys-typescale-emphasized-label-large px-spacing-50 py-spacing-25',
         separator: 'text-md-sys-color-on-surface-variant inline-flex shrink-0'
     },
     variants: {

package/dist/components/nav/navbar/Navbar.mdx

@@ -0,0 +1,38 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as NavbarStories from './Navbar.stories.svelte';
+
+<Meta of={NavbarStories} />
+
+<Title />
+
+<Subtitle>
+  Navigation bars give access to 3–5 primary destinations at the bottom of small windows.
+</Subtitle>
+
+[M3 spec](https://m3.material.io/components/navigation-bar/specs) ·
+`import { Navbar, NavbarItem } from '@noxlovette/material';`
+
+<Canvas of={NavbarStories.Playground} />
+
+<Controls of={NavbarStories.Playground} />
+
+## Pairing with Rail
+
+The bar is fixed to the bottom of the window and hides itself from `md` up, where a `Rail` takes
+over. Give both the same destinations. `ghost` adds a spacer the height of the bar, so the end of
+the page isn't hidden behind it.
+
+```svelte
+<Navbar ghost>
+  <NavbarItem label="Home" href="/" iconProps={{ name: 'house' }} />
+  <NavbarItem label="Messages" href="/messages" iconProps={{ name: 'mail' }} badge={5} />
+  <NavbarItem label="Settings" href="/settings" iconProps={{ name: 'settings' }} />
+</Navbar>
+```
+
+## Accessibility
+
+- **Landmark.** The bar is a navigation list, so assistive tech announces it as navigation.
+- **Active item.** The active item gets `aria-current="page"`.
+- **Badges.** A `badge` isn't announced on its own; put the count in the item's label if it
+  matters.

package/dist/components/nav/navbar/Navbar.svelte

@@ -44,7 +44,7 @@ This component takes NavbarItems as its children
     </NavigationMenu.List>
   </NavigationMenu.Root>
   {#if trailing}
-    <div class="shrink-0 px-2">
+    <div class="px-spacing-100 shrink-0">
       {@render trailing()}
     </div>
   {/if}

package/dist/components/nav/navbar/NavbarItem.svelte

@@ -48,15 +48,18 @@ A single destination within a navigation bar.
         <div class={content()}>
           <div class={iconContainer()}>
             <Layer />
-            <Icon
-              {...iconProps}
-              class={icon()}
-              wght={isActive ? 600 : 400}
-              fill={isActive ? 1 : 0}
-            />
-            {#if badge}
-              <Badge size={badge === -1 ? 'sm' : 'lg'} number={badge}></Badge>
-            {/if}
+            <!-- Badge offsets are measured from the icon's corner, not the indicator's. -->
+            <span class="relative inline-flex">
+              <Icon
+                {...iconProps}
+                class={icon()}
+                wght={isActive ? 600 : 400}
+                fill={isActive ? 1 : 0}
+              />
+              {#if badge}
+                <Badge size={badge === -1 ? 'sm' : 'lg'} number={badge} />
+              {/if}
+            </span>
           </div>
           <span class={labelClass()}>
             {label}

package/dist/components/nav/navbar/theme.d.ts

@@ -1,19 +1,19 @@
 export declare const navbar: import("tailwind-variants").TVReturnType<{
     [key: string]: {
         [key: string]: import("tailwind-variants").ClassValue | {
+            fab?: import("tailwind-variants").ClassValue;
             base?: import("tailwind-variants").ClassValue;
             items?: import("tailwind-variants").ClassValue;
             ghost?: import("tailwind-variants").ClassValue;
-            fab?: import("tailwind-variants").ClassValue;
         };
     };
 } | {
     [x: string]: {
         [x: string]: import("tailwind-variants").ClassValue | {
+            fab?: import("tailwind-variants").ClassValue;
             base?: import("tailwind-variants").ClassValue;
             items?: import("tailwind-variants").ClassValue;
             ghost?: import("tailwind-variants").ClassValue;
-            fab?: import("tailwind-variants").ClassValue;
         };
     };
 } | {}, {
@@ -24,10 +24,10 @@ export declare const navbar: import("tailwind-variants").TVReturnType<{
 }, undefined, {
     [key: string]: {
         [key: string]: import("tailwind-variants").ClassValue | {
+            fab?: import("tailwind-variants").ClassValue;
             base?: import("tailwind-variants").ClassValue;
             items?: import("tailwind-variants").ClassValue;
             ghost?: import("tailwind-variants").ClassValue;
-            fab?: import("tailwind-variants").ClassValue;
         };
     };
 } | {}, {

package/dist/components/nav/navbar/theme.js

@@ -1,18 +1,18 @@
-import { tv } from 'tailwind-variants';
+import { tv } from '../../../utils/tv.js';
 export const navbar = tv({
     slots: {
-        base: 'shadow-elevation-2 bg-md-sys-color-surface-container relative z-20 flex h-20 fixed bottom-0 w-full left-0 justify-around py-3 md:hidden',
+        base: 'shadow-elevation-2 bg-md-sys-color-surface-container z-layer-bar flex h-20 fixed bottom-spacing-0 w-full left-spacing-0 justify-around py-spacing-150 md:hidden',
         items: 'flex justify-around w-full',
-        fab: 'bottom-24 right-4 absolute',
+        fab: 'bottom-24 right-spacing-200 absolute',
         ghost: 'h-20 w-full shrink-0 md:hidden pointer-events-none'
     }
 });
 export const navitem = tv({
     slots: {
-        base: 'group relative flex flex-1 flex-col items-center justify-center min-w-0 max-w-[168px] h-full transition-colors md-sys-motion-fast-effects',
-        content: 'flex flex-col items-center justify-center gap-1 w-full',
-        iconContainer: 'relative flex items-center justify-center h-8 w-16 rounded-full transition-colors md-sys-motion-effects',
-        icon: 'text-[24px] size-6',
+        base: 'group relative flex flex-1 flex-col items-center justify-center min-w-spacing-0 max-w-[168px] h-full transition-colors md-sys-motion-fast-effects',
+        content: 'flex flex-col items-center justify-center gap-spacing-50 w-full',
+        iconContainer: 'relative flex items-center justify-center h-spacing-400 w-spacing-800 rounded-full transition-colors md-sys-motion-effects',
+        icon: 'text-[24px] size-spacing-300',
         label: 'md-sys-typescale-label-medium truncate w-full text-center'
     },
     variants: {

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

@@ -0,0 +1,73 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as RailStories from './Rail.stories.svelte';
+
+<Meta of={RailStories} />
+
+<Title />
+
+<Subtitle>
+  Navigation rails give access to 3–7 primary destinations on medium and larger windows.
+</Subtitle>
+
+[M3 spec](https://m3.material.io/components/navigation-rail/specs) ·
+`import { Rail, RailItem } from '@noxlovette/material';`
+
+<Canvas of={RailStories.Playground} />
+
+<Controls of={RailStories.Playground} />
+
+## 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.
+- **`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.
+
+## Window sizes
+
+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                                |
+
+## 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`:
+
+```svelte
+<div class="flex min-h-dvh">
+  <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>
+```
+
+- **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.
+
+<Canvas of={RailStories.WithFAB} />
+
+## Accessibility
+
+- **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.

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

@@ -14,15 +14,13 @@
       anchor: {
         control: 'select',
         options: ['viewport', 'parent']
-      },
-      withNavbar: { control: 'boolean' }
+      }
     },
     args: {
       collapsed: true,
       expandable: true,
       rounded: false,
-      anchor: 'parent',
-      withNavbar: false
+      anchor: 'parent'
     }
   });
 </script>
@@ -35,7 +33,6 @@
         collapsed={args.collapsed}
         expandable={args.expandable}
         rounded={args.rounded}
-        withNavbar={args.withNavbar}
       >
         <RailItem label="Home" href="/" iconProps={{ name: 'house' }} selected />
         <RailItem label="Inbox" href="#" iconProps={{ name: 'mail' }} badge={4} />
@@ -55,10 +52,9 @@
         collapsed={args.collapsed}
         expandable={args.expandable}
         rounded={args.rounded}
-        withNavbar={args.withNavbar}
       >
         {#snippet fab()}
-          <FAB size="small" iconProps={{ name: 'add' }} label="New" />
+          <FAB iconProps={{ name: 'add' }} label="New" />
         {/snippet}
         <RailItem label="Home" href="/" iconProps={{ name: 'house' }} selected />
         <RailItem label="Inbox" href="#" iconProps={{ name: 'mail' }} badge={4} />

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

@@ -25,6 +25,8 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
     collapsed = $bindable(true),
     anchor = 'viewport',
     railTop = 0,
+    expandLabel = 'Expand navigation',
+    collapseLabel = 'Collapse navigation',
     class: className
   }: RailProps = $props();
 
@@ -66,8 +68,9 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
 >
   {#if expandable}
     <ButtonIcon
+      variant="standard"
       type="button"
-      tooltipContent={collapsed ? 'Открыть' : 'Закрыть'}
+      tooltipContent={collapsed ? expandLabel : collapseLabel}
       iconProps={{ name: `${collapsed ? 'menu' : 'menu_open'}` }}
       class={toggleClass}
       onclick={() => (collapsed = !collapsed)}
@@ -97,6 +100,6 @@ On mobile (< md) it automatically renders as a bottom navigation bar.
     opacity: 1;
     pointer-events: auto;
     background-color: rgb(0 0 0 / 0.4);
-    z-index: 30;
+    z-index: var(--z-layer-rail);
   }
 </style>

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

@@ -99,15 +99,18 @@ In mobile (navbar) mode the same item renders as a bottom-bar tab.
         <div class={content()}>
           <div class={iconContainer()}>
             <Layer />
-            <Icon
-              {...iconProps}
-              class={icon()}
-              wght={isActive ? 600 : 400}
-              fill={isActive ? 1 : 0}
-            />
-            {#if badge}
-              <Badge size={badge === -1 ? 'sm' : 'lg'} number={badge}></Badge>
-            {/if}
+            <!-- Badge offsets are measured from the icon's corner, not the indicator's. -->
+            <span class="relative inline-flex">
+              <Icon
+                {...iconProps}
+                class={icon()}
+                wght={isActive ? 600 : 400}
+                fill={isActive ? 1 : 0}
+              />
+              {#if badge}
+                <Badge size={badge === -1 ? 'sm' : 'lg'} number={badge} />
+              {/if}
+            </span>
           </div>
           <p class={labelClass()}>
             {label}

package/dist/components/nav/rail/theme.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from 'tailwind-variants';
+import { type VariantProps } from '../../../utils/tv.js';
 export type RailVariants = VariantProps<typeof rail>;
 export type RailItemVariants = VariantProps<typeof railElement>;
 export declare const rail: import("tailwind-variants").TVReturnType<{