@noxlovette/material 0.5.1 → 0.6.0

package/dist/components/containers/side-sheet/SideSheet.mdx

@@ -0,0 +1,71 @@
+import { Meta, Title, Subtitle, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as SheetStories from './SideSheet.stories.svelte';
+
+<Meta of={SheetStories} />
+
+<Title />
+
+<Subtitle>Side sheets show secondary content anchored to the side of the screen.</Subtitle>
+
+[M3 spec](https://m3.material.io/components/side-sheets/specs) ·
+`import { SideSheet } from '@noxlovette/material';`
+
+<Canvas of={SheetStories.Modal} />
+
+<Controls of={SheetStories.Modal} />
+
+## Modal or standard
+
+- **`modal`** (default) opens at the window's end edge above a scrim, and blocks the app until
+  it's closed with its close button, Escape, or a scrim tap. Use it on compact and medium windows,
+  or when the content needs full attention. It is a native `<dialog>` opened with `showModal()`,
+  so the browser handles the focus trap, top-layer stacking and making the page behind it inert.
+- **`standard`** is part of the layout. Make it the last child of a full-height row. It opens by
+  widening, so the content beside it reflows instead of being covered, and everything stays
+  usable. Use it on expanded windows, for filters or details that people use alongside the main
+  content.
+
+```svelte
+<div class="flex h-dvh">
+  <main class="min-w-spacing-0 flex-1">…</main>
+  <SideSheet variant="standard" headline="Filters" bind:open>…</SideSheet>
+</div>
+```
+
+<Canvas of={SheetStories.Standard} />
+
+## Anatomy
+
+- **Header:** an optional back button (`onback`), the `headline`, and a close button. The headline
+  is `title-large` and names the sheet for assistive technology.
+- **Content:** your `children`, padded 24dp. It scrolls inside the sheet.
+- **Actions** (optional): the `actions` snippet, pinned to the bottom and left-aligned below a
+  divider. Put the most important action first, e.g. Save before Cancel.
+
+Show `onback` only when the sheet navigates within itself. The header's start padding then drops
+from 24dp to 16dp.
+
+<Canvas of={SheetStories.ModalWithBackButton} />
+
+## Size and shape
+
+Side sheets are 256dp wide by default and never wider than 400dp, and they span the full height.
+
+|          | Docked                                                               | `detached`                        |
+| -------- | -------------------------------------------------------------------- | --------------------------------- |
+| Modal    | `surface-container-low`, elevation 1, 16dp corners on the inner side | 16dp from the edges, 16dp corners |
+| Standard | `surface`, elevation 0, square, divider on the inner edge            | 16dp from the edges, 16dp corners |
+
+`divider={false}` removes the edge divider and the one above the actions.
+
+<Canvas of={SheetStories.StandardDetached} />
+
+## Motion
+
+A modal sheet slides in from the edge on the spatial spring, without fading, and stays mounted
+until it has slid out. A standard sheet animates its width on the same spring, so the content
+beside it reflows as it slides.
+
+## Not yet supported
+
+Right-to-left layouts: the modal sheet sits at the end edge, but always slides in from the right.

package/dist/components/containers/side-sheet/SideSheet.stories.svelte

@@ -1,41 +1,137 @@
 <!--
-  SideSheet is controlled with `bind:open`: it dismisses itself (close button, Esc, backdrop
-  click) by setting `open` to false, and stays mounted until its exit animation finishes.
+  SideSheet is controlled with `bind:open`. A modal sheet closes itself (close button, Esc,
+  scrim tap). A standard sheet sits in the layout: put it last in a full-height row and the
+  content beside it reflows as it opens and closes.
 -->
 <script module lang="ts">
   import { defineMeta } from '@storybook/addon-svelte-csf';
   import SideSheet from './SideSheet.svelte';
   import Button from '../../buttons/Button.svelte';
-  import { Body } from '../../../index.js';
+  import Checkbox from '../../forms/checkbox/Checkbox.svelte';
+  import List from '../list/List.svelte';
+  import ListItem from '../list/ListItem.svelte';
 
   const { Story } = defineMeta({
     title: 'Containers/Side Sheet',
     component: SideSheet,
     argTypes: {
-      headline: { control: 'text' }
+      headline: { control: 'text' },
+      width: { control: { type: 'range', min: 256, max: 400, step: 8 } },
+      detached: { control: 'boolean' },
+      divider: { control: 'boolean' }
     },
-    args: {
-      headline: 'Details'
-    }
+    args: { headline: 'Filters', width: 256, detached: false, divider: true }
   });
+
+  const filters = ['In stock', 'Free delivery', 'On sale', 'Recycled materials', 'Local sellers'];
 </script>
 
 <script lang="ts">
   let playgroundOpen = $state(false);
+  let detailOpen = $state(false);
+  let detailPage = $state<'list' | 'item'>('list');
+  let standardOpen = $state(true);
+  let detachedOpen = $state(true);
 </script>
 
-<Story name="Playground">
+{#snippet filterList()}
+  <div class="gap-spacing-200 flex flex-col">
+    {#each filters as f (f)}
+      <Checkbox labelText={f} />
+    {/each}
+  </div>
+{/snippet}
+
+{#snippet saveCancel(close: () => void)}
+  <Button onclick={close}>Save</Button>
+  <Button variant="outlined" onclick={close}>Cancel</Button>
+{/snippet}
+
+<Story name="Modal">
   {#snippet template(args)}
-    <div class="p-6">
-      <Button onclick={() => (playgroundOpen = true)}>Show side sheet</Button>
-      <SideSheet headline={args.headline} bind:open={playgroundOpen}>
-        <div class="flex flex-col gap-3 px-6 pb-6">
-          <Body class="text-md-sys-color-on-surface-variant">
-            Supplementary content and actions, anchored to the edge of the screen while the main
-            content stays visible.
-          </Body>
-        </div>
+    <div class="p-spacing-300">
+      <Button onclick={() => (playgroundOpen = true)}>Show filters</Button>
+      <SideSheet
+        headline={args.headline}
+        width={args.width}
+        detached={args.detached}
+        divider={args.divider}
+        bind:open={playgroundOpen}
+      >
+        {@render filterList()}
+        {#snippet actions()}
+          {@render saveCancel(() => (playgroundOpen = false))}
+        {/snippet}
       </SideSheet>
     </div>
   {/snippet}
 </Story>
+
+<Story name="Modal with back button" asChild>
+  <div class="p-spacing-300">
+    <Button
+      onclick={() => {
+        detailPage = 'list';
+        detailOpen = true;
+      }}>Show orders</Button
+    >
+    <SideSheet
+      headline={detailPage === 'list' ? 'Orders' : 'Order 1042'}
+      width={360}
+      bind:open={detailOpen}
+      onback={detailPage === 'item' ? () => (detailPage = 'list') : undefined}
+    >
+      {#if detailPage === 'list'}
+        <List class="-mx-spacing-300">
+          {#each [1042, 1041, 1040] as n (n)}
+            <ListItem
+              headline="Order {n}"
+              supporting="3 items · delivered"
+              onclick={() => (detailPage = 'item')}
+            />
+          {/each}
+        </List>
+      {:else}
+        <p class="md-sys-typescale-body-medium text-md-sys-color-on-surface-variant">
+          The back button appears when the sheet navigates within itself, and the header's start
+          padding drops from 24dp to 16dp.
+        </p>
+      {/if}
+    </SideSheet>
+  </div>
+</Story>
+
+<Story name="Standard" asChild>
+  <div class="bg-md-sys-color-surface flex h-[36rem] w-full">
+    <main class="min-w-spacing-0 gap-spacing-200 p-spacing-300 flex flex-1 flex-col items-start">
+      <p class="md-sys-typescale-body-large max-w-md">
+        The standard sheet is part of the layout: this column reflows as it opens and closes, and
+        stays usable while it's open.
+      </p>
+      <Button variant="tonal" onclick={() => (standardOpen = !standardOpen)}>
+        {standardOpen ? 'Hide filters' : 'Show filters'}
+      </Button>
+    </main>
+    <SideSheet variant="standard" headline="Filters" width={320} bind:open={standardOpen}>
+      {@render filterList()}
+      {#snippet actions()}
+        {@render saveCancel(() => (standardOpen = false))}
+      {/snippet}
+    </SideSheet>
+  </div>
+</Story>
+
+<Story name="Standard detached" asChild>
+  <div class="bg-md-sys-color-surface-container flex h-[36rem] w-full">
+    <main class="min-w-spacing-0 gap-spacing-200 p-spacing-300 flex flex-1 flex-col items-start">
+      <Button variant="tonal" onclick={() => (detachedOpen = !detachedOpen)}>
+        {detachedOpen ? 'Hide details' : 'Show details'}
+      </Button>
+    </main>
+    <SideSheet variant="standard" detached headline="Details" width={320} bind:open={detachedOpen}>
+      <p class="md-sys-typescale-body-medium text-md-sys-color-on-surface-variant">
+        Detached sheets float 16dp from the window edges with 16dp corners.
+      </p>
+    </SideSheet>
+  </div>
+</Story>

package/dist/components/containers/side-sheet/SideSheet.svelte

@@ -1,25 +1,59 @@
 <!--
 @component
-Side sheets are supplementary surfaces which are anchored to the edge of the screen.
+Side sheets show secondary content anchored to the side of the screen.
 
-Like BottomSheet, SideSheet owns its own overlay: it renders as a native `<dialog>` pinned to
-the right edge of the screen, dims the rest of the app behind a backdrop, and slides in/out.
-Visibility is controlled by `bind:open`; the sheet stays mounted until its exit animation
-finishes. Conditionally rendering it ({#if open}<SideSheet close={…} />{/if}) still works, but
-skips the exit animation.
+- **Modal** (default): a native `<dialog>` at the window's end edge above a scrim. It closes on
+  its close button, Esc, or a scrim tap, and stays mounted until its exit animation finishes.
+- **Standard**: part of the layout. Put it last in a full-height row; it opens by widening, so
+  the content beside it reflows, and nothing else is blocked.
 
-@see https://m3.material.io/components/side-sheets/guidelines
+Visibility is controlled with `bind:open`.
+
+@see https://m3.material.io/components/side-sheets/specs
 -->
 <script lang="ts">
-  import type { SideSheetProps } from './types.js';
+  import type { Attachment } from 'svelte/attachments';
+  import { untrack } from 'svelte';
+  import clsx from 'clsx';
   import ButtonIcon from '../../buttons/ButtonIcon.svelte';
+  import Divider from '../divider/Divider.svelte';
   import { enterExit, Presence } from '../../../animation/index.js';
+  import { sideSheet } from './theme.js';
+  import type { SideSheetProps } from './types.js';
 
-  let { headline, children, open = $bindable(true), close }: SideSheetProps = $props();
+  const MAX_WIDTH = 400;
 
-  const sheet = new Presence(() => open);
+  let {
+    headline,
+    children,
+    actions,
+    variant = 'modal',
+    open = $bindable(true),
+    width = 256,
+    detached = false,
+    divider = true,
+    onback,
+    close,
+    class: className
+  }: SideSheetProps = $props();
 
-  const showModal = (node: HTMLDialogElement) => node.showModal();
+  const id = $props.id();
+  const sheet = new Presence(() => open && variant === 'modal');
+  const cls = $derived(sideSheet({ variant, detached, divider, back: !!onback }));
+  const sheetWidth = $derived(Math.min(width, MAX_WIDTH));
+  // A detached standard sheet takes its 16dp margins with it.
+  const slotWidth = $derived(open ? sheetWidth + (detached ? 32 : 0) : 0);
+
+  // untrack: re-running this attachment would call showModal() on an open dialog. The dialog
+  // unmounts after its exit instead of calling close(), so focus is returned to the opener here.
+  const showModal: Attachment<HTMLDialogElement> = (node) =>
+    untrack(() => {
+      const opener = document.activeElement;
+      node.showModal();
+      return () => {
+        if (opener instanceof HTMLElement && opener.isConnected) opener.focus();
+      };
+    });
 
   const dismiss = () => {
     open = false;
@@ -27,61 +61,74 @@ skips the exit animation.
   };
 </script>
 
-{#if sheet.mounted}
-  <dialog
-    class="bg-md-sys-color-surface-container-low text-md-sys-color-on-surface fixed inset-y-0 right-0 left-auto m-0 h-full w-full max-w-sm rounded-l-md"
-    data-state={open ? 'open' : 'closed'}
-    {@attach showModal}
-    {@attach sheet.attach(enterExit.sideSheet)}
-    oncancel={(e) => {
-      e.preventDefault();
-      dismiss();
-    }}
-    onmousedown={(e) => {
-      if (e.target != e.currentTarget) return;
-      dismiss();
-    }}
-  >
-    <div class="flex h-full flex-col">
-      <div class="flex items-center justify-between p-6">
-        <span class="md-sys-typescale-title-large text-md-sys-color-on-surface-variant"
-          >{headline}</span
-        >
-        <ButtonIcon type="button" variant="text" iconProps={{ name: 'close' }} onclick={dismiss} />
+{#snippet surface()}
+  <div class={cls.header()}>
+    {#if onback}
+      <ButtonIcon
+        type="button"
+        variant="standard"
+        class={cls.iconButton()}
+        iconProps={{ name: 'arrow_back' }}
+        aria-label="Back"
+        onclick={onback}
+      />
+    {/if}
+    <h2 id="{id}-headline" class={cls.headline()}>{headline}</h2>
+    <ButtonIcon
+      type="button"
+      variant="standard"
+      class={cls.iconButton()}
+      iconProps={{ name: 'close' }}
+      aria-label="Close"
+      onclick={dismiss}
+    />
+  </div>
+  <div class={cls.body()}>
+    {@render children()}
+  </div>
+  {#if actions}
+    {#if divider}
+      <Divider />
+    {/if}
+    <div class={cls.actions()}>
+      {@render actions()}
+    </div>
+  {/if}
+{/snippet}
+
+{#if variant === 'modal'}
+  {#if sheet.mounted}
+    <dialog
+      class={cls.base({ class: clsx(className) })}
+      style:width="{sheetWidth}px"
+      aria-labelledby="{id}-headline"
+      data-state={open ? 'open' : 'closed'}
+      {@attach showModal}
+      {@attach sheet.attach(enterExit.sideSheet)}
+      oncancel={(e) => {
+        e.preventDefault();
+        dismiss();
+      }}
+      onmousedown={(e) => {
+        // Only the ::backdrop targets the dialog itself.
+        if (e.target === e.currentTarget) dismiss();
+      }}
+    >
+      <div class={cls.container()}>
+        {@render surface()}
       </div>
-      {@render children()}
+    </dialog>
+  {/if}
+{:else}
+  <aside
+    class={cls.base({ class: clsx(className) })}
+    style:width="{slotWidth}px"
+    aria-labelledby="{id}-headline"
+    aria-hidden={!open}
+    inert={!open}
+  >
+    <div class={cls.container()} style:width="{sheetWidth}px">
+      {@render surface()}
     </div>
-  </dialog>
+  </aside>
 {/if}
-
-<style>
-  dialog::backdrop {
-    background-color: rgba(0, 0, 0, 0.5);
-    animation: backdrop var(--md-sys-motion-duration-effects-spring)
-      var(--md-sys-motion-timing-function-effects-spring);
-  }
-  dialog[data-state='closed'] {
-    pointer-events: none;
-  }
-  dialog[data-state='closed']::backdrop {
-    background-color: transparent;
-    animation: backdropReverse var(--md-sys-motion-duration-fast-effects-spring)
-      var(--md-sys-motion-timing-function-fast-effects-spring);
-  }
-  @keyframes backdrop {
-    from {
-      background-color: transparent;
-    }
-    to {
-      background-color: rgba(0, 0, 0, 0.5);
-    }
-  }
-  @keyframes backdropReverse {
-    from {
-      background-color: rgba(0, 0, 0, 0.5);
-    }
-    to {
-      background-color: transparent;
-    }
-  }
-</style>

package/dist/components/containers/side-sheet/SideSheet.svelte.d.ts

@@ -1,14 +1,15 @@
 import type { SideSheetProps } from './types.js';
 /**
- * Side sheets are supplementary surfaces which are anchored to the edge of the screen.
+ * Side sheets show secondary content anchored to the side of the screen.
  *
- * Like BottomSheet, SideSheet owns its own overlay: it renders as a native `<dialog>` pinned to
- * the right edge of the screen, dims the rest of the app behind a backdrop, and slides in/out.
- * Visibility is controlled by `bind:open`; the sheet stays mounted until its exit animation
- * finishes. Conditionally rendering it ({#if open}<SideSheet close={…} />{/if}) still works, but
- * skips the exit animation.
+ * - **Modal** (default): a native `<dialog>` at the window's end edge above a scrim. It closes on
+ * its close button, Esc, or a scrim tap, and stays mounted until its exit animation finishes.
+ * - **Standard**: part of the layout. Put it last in a full-height row; it opens by widening, so
+ * the content beside it reflows, and nothing else is blocked.
  *
- * @see https://m3.material.io/components/side-sheets/guidelines
+ * Visibility is controlled with `bind:open`.
+ *
+ * @see https://m3.material.io/components/side-sheets/specs
  */
 declare const SideSheet: import("svelte").Component<SideSheetProps, {}, "open">;
 type SideSheet = ReturnType<typeof SideSheet>;

package/dist/components/containers/side-sheet/index.d.ts

@@ -1,2 +1,3 @@
+export * from './theme.js';
 export * from './types.js';
 export { default as SideSheet } from './SideSheet.svelte';

package/dist/components/containers/side-sheet/index.js

@@ -1,5 +1,6 @@
 // THIS FILE IS AUTO-GENERATED BY scripts/generate-components-index.ts - DO NOT EDIT MANUALLY
 // re-export TS/JS modules from this folder
+export * from './theme.js';
 export * from './types.js';
 // default exports for components in this folder
 export { default as SideSheet } from './SideSheet.svelte';

package/dist/components/containers/side-sheet/theme.d.ts

@@ -0,0 +1,108 @@
+import { type VariantProps } from 'tailwind-variants';
+export type SideSheetVariants = VariantProps<typeof sideSheet>;
+export declare const sideSheet: import("tailwind-variants").TVReturnType<{
+    variant: {
+        modal: {
+            base: string[];
+            container: string;
+        };
+        standard: {
+            base: string;
+            container: string;
+        };
+    };
+    detached: {
+        true: {
+            container: string;
+        };
+        false: {};
+    };
+    divider: {
+        true: {};
+        false: {};
+    };
+    back: {
+        true: {
+            header: string;
+        };
+        false: {};
+    };
+}, {
+    base: string;
+    container: string;
+    header: string;
+    iconButton: string;
+    headline: string;
+    body: string;
+    actions: string;
+}, undefined, {
+    variant: {
+        modal: {
+            base: string[];
+            container: string;
+        };
+        standard: {
+            base: string;
+            container: string;
+        };
+    };
+    detached: {
+        true: {
+            container: string;
+        };
+        false: {};
+    };
+    divider: {
+        true: {};
+        false: {};
+    };
+    back: {
+        true: {
+            header: string;
+        };
+        false: {};
+    };
+}, {
+    base: string;
+    container: string;
+    header: string;
+    iconButton: string;
+    headline: string;
+    body: string;
+    actions: string;
+}, import("tailwind-variants").TVReturnTypeLike<{
+    variant: {
+        modal: {
+            base: string[];
+            container: string;
+        };
+        standard: {
+            base: string;
+            container: string;
+        };
+    };
+    detached: {
+        true: {
+            container: string;
+        };
+        false: {};
+    };
+    divider: {
+        true: {};
+        false: {};
+    };
+    back: {
+        true: {
+            header: string;
+        };
+        false: {};
+    };
+}, {
+    base: string;
+    container: string;
+    header: string;
+    iconButton: string;
+    headline: string;
+    body: string;
+    actions: string;
+}>>;

package/dist/components/containers/side-sheet/theme.js

@@ -0,0 +1,72 @@
+import { tv } from 'tailwind-variants';
+/*
+  M3 side sheet (https://m3.material.io/components/side-sheets/specs). Full height, 256dp wide by
+  default and never wider than 400dp. 24dp start/end padding (16dp before a back button), 12dp
+  between the header's elements, `title-large` headline in `on-surface-variant`. Bottom actions
+  sit 16dp below a divider and 24dp above the bottom edge.
+
+  - Standard: `surface`, elevation 0, square, an `outline-variant` divider along its inner edge.
+    It sits in the layout and the content beside it reflows as it opens.
+  - Modal: `surface-container-low`, elevation 1, 16dp corners on its inner side, above a scrim.
+  - Detached (either): 16dp from the window edges, 16dp corners all round.
+
+  The header's icon buttons are 40dp around a 24dp icon; `-m-spacing-100` lines the icons (not the
+  buttons) up with the padding, as the spec measures it.
+*/
+export const sideSheet = tv({
+    slots: {
+        base: 'p-spacing-0',
+        container: 'flex h-full flex-col overflow-hidden',
+        header: 'flex shrink-0 items-center gap-spacing-150 ps-spacing-300 pe-spacing-300 pt-spacing-300',
+        iconButton: '-m-spacing-100 shrink-0',
+        headline: 'md-sys-typescale-title-large text-md-sys-color-on-surface-variant min-w-spacing-0 flex-1',
+        body: 'min-h-spacing-0 flex-1 overflow-y-auto overscroll-contain px-spacing-300 py-spacing-300',
+        actions: 'flex min-h-spacing-900 shrink-0 items-center justify-start gap-spacing-100 px-spacing-300 pt-spacing-200 pb-spacing-300'
+    },
+    variants: {
+        variant: {
+            modal: {
+                base: [
+                    'fixed inset-y-spacing-0 start-auto end-spacing-0 m-spacing-0 h-dvh max-h-none w-full overflow-visible bg-transparent outline-none',
+                    'backdrop:bg-md-sys-color-scrim/32 backdrop:transition-[background-color] backdrop:md-sys-motion-effects',
+                    'starting:backdrop:bg-transparent data-[state=closed]:pointer-events-none data-[state=closed]:backdrop:bg-transparent'
+                ],
+                container: 'bg-md-sys-color-surface-container-low text-md-sys-color-on-surface shadow-elevation-1 rounded-s-2xl'
+            },
+            standard: {
+                // The wrapper animates its width, so the content beside it reflows; the sheet itself
+                // keeps its width and stays pinned to the wrapper's end edge, so it appears to slide in.
+                base: 'md-sys-motion-spatial relative h-full shrink-0 overflow-clip transition-[width]',
+                container: 'bg-md-sys-color-surface text-md-sys-color-on-surface absolute inset-y-spacing-0 end-spacing-0'
+            }
+        },
+        detached: {
+            true: { container: 'rounded-2xl' },
+            false: {}
+        },
+        divider: { true: {}, false: {} },
+        back: { true: { header: 'ps-spacing-200' }, false: {} }
+    },
+    compoundVariants: [
+        {
+            variant: 'modal',
+            detached: true,
+            class: {
+                base: 'inset-y-spacing-200 end-spacing-200 h-[calc(100dvh-2rem)] max-w-[calc(100%-2rem)]'
+            }
+        },
+        { variant: 'modal', detached: false, class: { base: 'max-w-full' } },
+        {
+            variant: 'standard',
+            detached: true,
+            class: { container: 'inset-y-spacing-200 end-spacing-200' }
+        },
+        {
+            variant: 'standard',
+            detached: false,
+            divider: true,
+            class: { container: 'border-md-sys-color-outline-variant border-s' }
+        }
+    ],
+    defaultVariants: { variant: 'modal', detached: false, divider: true, back: false }
+});