@noxlovette/material 0.7.1 → 0.8.1

package/dist/components/forms/search/SearchView.svelte

@@ -0,0 +1,269 @@
+<!--
+@component
+Material 3 search view (contained, M3 Expressive): where a search bar's suggestions and results go.
+
+`Search` and the search `AppBar` render it for you when given `results`; use it directly only to
+open a view from a bar of your own, passing that bar as `anchor`.
+
+- **Layouts.** `fullScreen` covers the window; `docked` widens the bar in place (its margins go
+  from 24dp to 12dp) with results in a container 2dp below. `layout` takes one per window tier and
+  defaults to full-screen on compact windows, docked from medium up. Switched in CSS.
+- **Motion.** Opening and closing are an M3 container transform between the bar and the view, on
+  the `spatial` spring; a crossfade under reduced motion.
+- **Behavior.** A bits-ui `Dialog`: focus stays in the view, the page doesn't scroll, and Esc, the
+  back button or a click outside closes it. The field is a combobox over the `results` listbox:
+  arrow keys move through the `role="option"` items and Enter picks one.
+
+@see https://m3.material.io/components/search/specs
+-->
+<script lang="ts">
+  import { tick, untrack } from 'svelte';
+  import { Dialog } from 'bits-ui';
+  import clsx from 'clsx';
+  import { containerTransform } from '../../../animation/index.js';
+  import ButtonIcon from '../../buttons/ButtonIcon.svelte';
+  import { defaultSearchLayout, searchView, searchViewLayout } from './theme.js';
+  import type { SearchViewProps } from './types.js';
+
+  const uid = $props.id();
+
+  let {
+    open = $bindable(false),
+    value = $bindable(),
+    anchor,
+    results,
+    layout = defaultSearchLayout,
+    placeholder = 'Search',
+    resultsLabel,
+    backLabel = 'Back',
+    clearLabel = 'Clear search',
+    trailing,
+    inputProps,
+    inputRef = $bindable()
+  }: SearchViewProps = $props();
+
+  const listboxId = `${uid}-listbox`;
+  const label = $derived(resultsLabel ?? placeholder ?? 'Search');
+  const s = $derived(searchView({ hasTrailing: !!value || !!trailing }));
+  const placed = $derived(searchViewLayout(layout));
+
+  /*
+    `open` is what was asked for; `shown` is what's on screen. The container transform flips
+    `shown` inside its update, so the View Transition API snapshots the bar before and the view
+    after (or the reverse). One transform at a time: a request made mid-flight is picked up when
+    the running one settles, so a quick open-close never strands the view.
+  */
+  let shown = $state(untrack(() => open));
+  let view = $state<HTMLElement>();
+  let busy = false;
+
+  const sync = () => {
+    if (busy || open === shown) return;
+    const opening = open;
+    if (opening) measure();
+    const update = async () => {
+      // The view takes the bar's place: hidden, the bar isn't left behind in the page's snapshot
+      // (a second, static bar under the morph). Shown again first on close, so focus can return.
+      hideAnchor(opening);
+      shown = opening;
+      await tick();
+    };
+    const from = opening ? anchor : view;
+    const to = opening ? `[data-search-view="${uid}"]` : anchor;
+    busy = true;
+    const settle = () => {
+      busy = false;
+      sync();
+    };
+    if (!from || !to) update().then(settle, settle);
+    else containerTransform(update, { from, to }).then(settle, settle);
+  };
+
+  $effect(() => {
+    void open;
+    untrack(sync);
+  });
+
+  const hideAnchor = (hidden: boolean) => {
+    if (anchor) anchor.style.visibility = hidden ? 'hidden' : '';
+  };
+
+  // Covers a view that starts open, and a bar swapped while it's open.
+  $effect(() => {
+    if (!anchor) return;
+    hideAnchor(untrack(() => shown));
+    return () => hideAnchor(false);
+  });
+
+  /*
+    Docked: the view's bar is the search bar widened by the 12dp contained margin on each side,
+    held to 360–720dp and to the window; results may grow to ⅔ of the window, stopping 16dp
+    above its bottom edge. Read in px from the bar and the --md-comp-search-view-* tokens.
+  */
+  let pos = $state({ top: 0, left: 0, width: 0, room: 0 });
+
+  function measure() {
+    if (!anchor) return;
+    const r = anchor.getBoundingClientRect();
+    const root = getComputedStyle(document.documentElement);
+    const rem = parseFloat(root.fontSize) || 16;
+    const token = (name: string, fallback: number) =>
+      parseFloat(
+        root.getPropertyValue(`--md-comp-search-view-contained-docked-container-width-${name}`)
+      ) * rem || fallback;
+    const margin = 0.75 * rem;
+    const width = Math.min(
+      Math.max(r.width + 2 * margin, token('minimum', 0)),
+      token('maximum', Infinity),
+      innerWidth
+    );
+    const left = Math.max(0, Math.min(r.left - margin, innerWidth - width));
+    pos = { top: r.top, left, width, room: innerHeight - r.top - rem };
+  }
+
+  $effect(() => {
+    if (!shown) return;
+    addEventListener('resize', measure);
+    return () => removeEventListener('resize', measure);
+  });
+
+  /* Combobox: the input keeps focus; aria-activedescendant points at the highlighted option. */
+  let resultsEl = $state<HTMLElement>();
+  let active = $state<HTMLElement | null>(null);
+  let optionIds = 0;
+
+  const options = () =>
+    [...(resultsEl?.querySelectorAll<HTMLElement>('[role="option"]') ?? [])].filter(
+      (o) => o.getAttribute('aria-disabled') !== 'true' && !o.hasAttribute('disabled')
+    );
+
+  const highlight = (el: HTMLElement | null) => {
+    active?.removeAttribute('data-highlighted');
+    if (el) {
+      el.id ||= `${uid}-option-${optionIds++}`;
+      el.setAttribute('data-highlighted', '');
+      el.scrollIntoView?.({ block: 'nearest' });
+    }
+    active = el;
+  };
+
+  // A new query means new results: start over from the field.
+  $effect(() => {
+    void value;
+    void shown;
+    untrack(() => highlight(null));
+  });
+
+  function onkeydown(e: KeyboardEvent & { currentTarget: HTMLInputElement }) {
+    inputProps?.onkeydown?.(e);
+    if (e.defaultPrevented) return;
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      const list = options();
+      if (!list.length) return;
+      e.preventDefault();
+      const i = active ? list.indexOf(active) : -1;
+      const next = e.key === 'ArrowDown' ? (i + 1) % list.length : i <= 0 ? list.length - 1 : i - 1;
+      highlight(list[next]);
+    } else if (e.key === 'Enter' && active?.isConnected) {
+      e.preventDefault();
+      active.click();
+    }
+  }
+
+  function focusInput(e: Event) {
+    e.preventDefault();
+    const end = inputRef?.value.length ?? 0;
+    inputRef?.focus();
+    inputRef?.setSelectionRange(end, end);
+  }
+
+  // Back to the bar's field. The bar opens on click or typing, never on focus, so this is safe.
+  function focusBar(e: Event) {
+    e.preventDefault();
+    const field = anchor instanceof HTMLInputElement ? anchor : anchor?.querySelector('input');
+    field?.focus();
+  }
+
+  function clear() {
+    value = '';
+    inputRef?.focus();
+  }
+</script>
+
+<!--
+  forceMount + {#if shown}: the view mounts and unmounts in the same tick as `shown`, inside the
+  transform's update. bits-ui's own presence would unmount a frame later, after the snapshot.
+-->
+<Dialog.Root
+  bind:open={
+    () => shown,
+    (next) => {
+      if (!next) open = false;
+    }
+  }
+>
+  <Dialog.Portal>
+    <Dialog.Content forceMount onOpenAutoFocus={focusInput} onCloseAutoFocus={focusBar}>
+      {#snippet child({ props })}
+        {#if shown}
+          <div
+            {...props}
+            bind:this={view}
+            data-search-view={uid}
+            class={s.base({ class: placed.base })}
+            style:--sv-top="{pos.top}px"
+            style:--sv-left="{pos.left}px"
+            style:--sv-width="{pos.width}px"
+            style:--sv-max-height="min(var(--md-comp-search-view-contained-docked-container-height-maximum),
+            {pos.room}px)"
+          >
+            <Dialog.Title class="sr-only">{label}</Dialog.Title>
+            <div class={s.bar()}>
+              <span class={s.leading()}>
+                <ButtonIcon
+                  variant="standard"
+                  type="button"
+                  iconProps={{ name: 'arrow_back' }}
+                  aria-label={backLabel}
+                  onclick={() => (open = false)}
+                />
+              </span>
+              <input
+                {...inputProps}
+                bind:this={inputRef}
+                bind:value
+                type="search"
+                role="combobox"
+                aria-autocomplete="list"
+                aria-expanded="true"
+                aria-controls={listboxId}
+                aria-activedescendant={active?.id}
+                aria-label={inputProps?.['aria-label'] ?? placeholder}
+                {placeholder}
+                class={s.input({ class: clsx(inputProps?.class) })}
+                {onkeydown}
+              />
+              {#if value || trailing}
+                <span class={s.trailing()}>
+                  {#if value}
+                    <ButtonIcon
+                      variant="standard"
+                      type="button"
+                      iconProps={{ name: 'close' }}
+                      aria-label={clearLabel}
+                      onclick={clear}
+                    />
+                  {/if}
+                  {@render trailing?.()}
+                </span>
+              {/if}
+            </div>
+            <div bind:this={resultsEl} class={s.results({ class: placed.results })}>
+              {@render results({ id: listboxId, role: 'listbox', 'aria-label': label })}
+            </div>
+          </div>
+        {/if}
+      {/snippet}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>

package/dist/components/forms/search/SearchView.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { SearchViewProps } from './types.js';
+/**
+ * Material 3 search view (contained, M3 Expressive): where a search bar's suggestions and results go.
+ *
+ * `Search` and the search `AppBar` render it for you when given `results`; use it directly only to
+ * open a view from a bar of your own, passing that bar as `anchor`.
+ *
+ * - **Layouts.** `fullScreen` covers the window; `docked` widens the bar in place (its margins go
+ * from 24dp to 12dp) with results in a container 2dp below. `layout` takes one per window tier and
+ * defaults to full-screen on compact windows, docked from medium up. Switched in CSS.
+ * - **Motion.** Opening and closing are an M3 container transform between the bar and the view, on
+ * the `spatial` spring; a crossfade under reduced motion.
+ * - **Behavior.** A bits-ui `Dialog`: focus stays in the view, the page doesn't scroll, and Esc, the
+ * back button or a click outside closes it. The field is a combobox over the `results` listbox:
+ * arrow keys move through the `role="option"` items and Enter picks one.
+ *
+ * @see https://m3.material.io/components/search/specs
+ */
+declare const SearchView: import("svelte").Component<SearchViewProps, {}, "value" | "open" | "inputRef">;
+type SearchView = ReturnType<typeof SearchView>;
+export default SearchView;

package/dist/components/forms/search/index.d.ts

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

package/dist/components/forms/search/index.js

@@ -4,3 +4,4 @@ export * from './theme.js';
 export * from './types.js';
 // default exports for components in this folder
 export { default as Search } from './Search.svelte';
+export { default as SearchView } from './SearchView.svelte';

package/dist/components/forms/search/theme.d.ts

@@ -1,10 +1,15 @@
 import { type VariantProps } from '../../../utils/tv.js';
+import type { Responsive } from '../../containers/pane/theme.js';
+import type { SearchLayout } from './types.js';
 export type SearchVariants = VariantProps<typeof search>;
 /**
  * M3 Expressive contained search bar (https://m3.material.io/components/search/specs):
  * 56dp, circular, surface-container-high, flat. 48dp leading/trailing targets at a 4dp inset,
  * 4dp between the leading element and the label, 0 between trailing actions; 16dp at an edge
- * with no action. Hover 8% / pressed 10% on-surface; focus 3dp secondary outline, 2dp offset.
+ * with no action. Circular as `rounded-xl` (28dp, half the height), not `rounded-full`: the
+ * search view's container transform interpolates the corner radius, and an infinite one balloons
+ * the bar into a circle mid-morph. The focus ring is dropped while a view transition runs: it's
+ * outside the bar's box, and a snapshot of it would trail the morph as a stray arc. Hover 8% / pressed 10% on-surface; focus 3dp secondary outline, 2dp offset.
  */
 export declare const search: import("tailwind-variants").TVReturnType<{
     hasLeading: {
@@ -64,3 +69,65 @@ export declare const search: import("tailwind-variants").TVReturnType<{
     input: string;
     trailing: string;
 }>>;
+export type SearchViewVariants = VariantProps<typeof searchView>;
+/**
+ * M3 Expressive search view, contained style (https://m3.material.io/components/search/specs).
+ * In both layouts the bar is a 56dp circular surface-container-high field with a back button,
+ * 12dp from the view's edges (`search-view.contained.leading/trailing-margin`). The layout table
+ * below places the view and colours its container.
+ */
+export declare const searchView: import("tailwind-variants").TVReturnType<{
+    hasTrailing: {
+        true: "";
+        false: {
+            input: string;
+        };
+    };
+}, {
+    base: string;
+    bar: string;
+    leading: string;
+    input: string;
+    trailing: string;
+    results: string;
+}, undefined, {
+    hasTrailing: {
+        true: "";
+        false: {
+            input: string;
+        };
+    };
+}, {
+    base: string;
+    bar: string;
+    leading: string;
+    input: string;
+    trailing: string;
+    results: string;
+}, import("tailwind-variants").TVReturnTypeLike<{
+    hasTrailing: {
+        true: "";
+        false: {
+            input: string;
+        };
+    };
+}, {
+    base: string;
+    bar: string;
+    leading: string;
+    input: string;
+    trailing: string;
+    results: string;
+}>>;
+type ViewSlot = 'base' | 'results';
+/** M3's layout guidance: full-screen on compact windows, docked from medium up. */
+export declare const defaultSearchLayout: {
+    readonly small: "fullScreen";
+    readonly medium: "docked";
+};
+/**
+ * Resolves a responsive search view layout into classes for the view's slots. Tiers left out
+ * inherit from the one below; below the first given tier the view is full-screen.
+ */
+export declare function searchViewLayout(layout: Responsive<SearchLayout>): Record<ViewSlot, string>;
+export {};

package/dist/components/forms/search/theme.js

@@ -3,11 +3,14 @@ import { tv } from '../../../utils/tv.js';
  * M3 Expressive contained search bar (https://m3.material.io/components/search/specs):
  * 56dp, circular, surface-container-high, flat. 48dp leading/trailing targets at a 4dp inset,
  * 4dp between the leading element and the label, 0 between trailing actions; 16dp at an edge
- * with no action. Hover 8% / pressed 10% on-surface; focus 3dp secondary outline, 2dp offset.
+ * with no action. Circular as `rounded-xl` (28dp, half the height), not `rounded-full`: the
+ * search view's container transform interpolates the corner radius, and an infinite one balloons
+ * the bar into a circle mid-morph. The focus ring is dropped while a view transition runs: it's
+ * outside the bar's box, and a snapshot of it would trail the morph as a stray arc. Hover 8% / pressed 10% on-surface; focus 3dp secondary outline, 2dp offset.
  */
 export const search = tv({
     slots: {
-        base: 'state-layer relative flex h-spacing-700 w-full max-w-[720px] grow cursor-text items-center rounded-full bg-md-sys-color-surface-container-high ps-spacing-50 pe-spacing-50 before:rounded-full hover:before:bg-md-sys-color-on-surface/8 active:before:bg-md-sys-color-on-surface/10 has-[input:focus-visible]:outline-3 has-[input:focus-visible]:outline-offset-2 has-[input:focus-visible]:outline-md-sys-color-secondary',
+        base: 'state-layer relative flex h-spacing-700 w-full max-w-[720px] cursor-text items-center rounded-xl bg-md-sys-color-surface-container-high ps-spacing-50 pe-spacing-50 before:rounded-xl hover:before:bg-md-sys-color-on-surface/8 active:before:bg-md-sys-color-on-surface/10 has-[input:focus-visible]:outline-3 has-[input:focus-visible]:outline-offset-2 has-[input:focus-visible]:outline-md-sys-color-secondary [:root:active-view-transition_&]:outline-0',
         leading: 'text-md-sys-color-on-surface relative flex shrink-0 items-center',
         leadingIcon: 'text-md-sys-color-on-surface grid size-spacing-600 shrink-0 place-items-center',
         input: 'md-sys-typescale-body-large text-md-sys-color-on-surface placeholder:text-md-sys-color-on-surface-variant relative ms-spacing-50 me-spacing-50 w-full min-w-spacing-0 bg-transparent outline-none [&::-webkit-search-cancel-button]:hidden',
@@ -18,3 +21,89 @@ export const search = tv({
         hasTrailing: { true: '', false: { input: 'me-spacing-150' } }
     }
 });
+/**
+ * M3 Expressive search view, contained style (https://m3.material.io/components/search/specs).
+ * In both layouts the bar is a 56dp circular surface-container-high field with a back button,
+ * 12dp from the view's edges (`search-view.contained.leading/trailing-margin`). The layout table
+ * below places the view and colours its container.
+ */
+export const searchView = tv({
+    slots: {
+        base: 'fixed z-layer-modal flex flex-col outline-none',
+        bar: 'flex h-spacing-700 w-full shrink-0 items-center rounded-xl bg-md-sys-color-surface-container-high ps-spacing-50 pe-spacing-50',
+        leading: 'text-md-sys-color-on-surface flex shrink-0 items-center',
+        input: 'md-sys-typescale-body-large text-md-sys-color-on-surface placeholder:text-md-sys-color-on-surface-variant ms-spacing-50 me-spacing-50 w-full min-w-spacing-0 bg-transparent outline-none [&::-webkit-search-cancel-button]:hidden',
+        trailing: 'text-md-sys-color-on-surface-variant flex shrink-0 items-center',
+        // Options sit on the view's container colour, not the list's own surface. The one the arrow
+        // keys are on gets the M3 focus indicator, drawn inside the item.
+        results: 'min-h-spacing-0 overflow-y-auto overscroll-contain [&_[role=option]:not([aria-disabled=true])]:bg-transparent [&_[data-highlighted]]:outline-3 [&_[data-highlighted]]:-outline-offset-3 [&_[data-highlighted]]:outline-md-sys-color-secondary'
+    },
+    variants: {
+        hasTrailing: { true: '', false: { input: 'me-spacing-150' } }
+    }
+});
+/*
+  Every class is a literal so the Tailwind scanner sees it; `searchViewLayout` picks one row per
+  tier. Each row restates every property a tier changes, so a smaller tier never leaks upward.
+
+  Full-screen: the whole window, surface-container-low, 0 radius; the bar sits 12dp in from the
+  sides and 8dp from the top, so it lines up with a 64dp app bar. The results run edge to edge.
+  Docked: the bar widened over the search bar (JS measures it into --sv-*), results 2dp below in
+  a 12dp-radius surface-container-high container. The transparent wrapper takes their corners
+  (28dp top, 12dp bottom) only so the container transform morphs into the right shape. 360–720dp wide, 240dp to ⅔ of the window tall.
+*/
+const layoutClasses = {
+    small: {
+        fullScreen: {
+            base: 'top-spacing-0 left-spacing-0 w-full min-w-spacing-0 max-w-none h-dvh min-h-spacing-0 max-h-none gap-spacing-100 px-spacing-150 pt-spacing-100 rounded-none bg-md-sys-color-surface-container-low',
+            results: 'flex-1 -mx-spacing-150 rounded-none bg-transparent'
+        },
+        docked: {
+            base: 'top-(--sv-top) left-(--sv-left) w-(--sv-width) min-w-(--md-comp-search-view-contained-docked-container-width-minimum) max-w-(--md-comp-search-view-contained-docked-container-width-maximum) h-auto min-h-(--md-comp-search-view-contained-docked-container-height-minimum) max-h-(--sv-max-height) gap-spacing-25 px-spacing-0 pt-spacing-0 rounded-t-xl rounded-b-md bg-transparent',
+            results: 'flex-1 mx-spacing-0 rounded-md bg-md-sys-color-surface-container-high'
+        }
+    },
+    medium: {
+        fullScreen: {
+            base: 'md:top-spacing-0 md:left-spacing-0 md:w-full md:min-w-spacing-0 md:max-w-none md:h-dvh md:min-h-spacing-0 md:max-h-none md:gap-spacing-100 md:px-spacing-150 md:pt-spacing-100 md:rounded-none md:bg-md-sys-color-surface-container-low',
+            results: 'md:flex-1 md:-mx-spacing-150 md:rounded-none md:bg-transparent'
+        },
+        docked: {
+            base: 'md:top-(--sv-top) md:left-(--sv-left) md:w-(--sv-width) md:min-w-(--md-comp-search-view-contained-docked-container-width-minimum) md:max-w-(--md-comp-search-view-contained-docked-container-width-maximum) md:h-auto md:min-h-(--md-comp-search-view-contained-docked-container-height-minimum) md:max-h-(--sv-max-height) md:gap-spacing-25 md:px-spacing-0 md:pt-spacing-0 md:rounded-t-xl md:rounded-b-md md:bg-transparent',
+            results: 'md:flex-1 md:mx-spacing-0 md:rounded-md md:bg-md-sys-color-surface-container-high'
+        }
+    },
+    large: {
+        fullScreen: {
+            base: 'lg:top-spacing-0 lg:left-spacing-0 lg:w-full lg:min-w-spacing-0 lg:max-w-none lg:h-dvh lg:min-h-spacing-0 lg:max-h-none lg:gap-spacing-100 lg:px-spacing-150 lg:pt-spacing-100 lg:rounded-none lg:bg-md-sys-color-surface-container-low',
+            results: 'lg:flex-1 lg:-mx-spacing-150 lg:rounded-none lg:bg-transparent'
+        },
+        docked: {
+            base: 'lg:top-(--sv-top) lg:left-(--sv-left) lg:w-(--sv-width) lg:min-w-(--md-comp-search-view-contained-docked-container-width-minimum) lg:max-w-(--md-comp-search-view-contained-docked-container-width-maximum) lg:h-auto lg:min-h-(--md-comp-search-view-contained-docked-container-height-minimum) lg:max-h-(--sv-max-height) lg:gap-spacing-25 lg:px-spacing-0 lg:pt-spacing-0 lg:rounded-t-xl lg:rounded-b-md lg:bg-transparent',
+            results: 'lg:flex-1 lg:mx-spacing-0 lg:rounded-md lg:bg-md-sys-color-surface-container-high'
+        }
+    },
+    extraLarge: {
+        fullScreen: {
+            base: 'xl:top-spacing-0 xl:left-spacing-0 xl:w-full xl:min-w-spacing-0 xl:max-w-none xl:h-dvh xl:min-h-spacing-0 xl:max-h-none xl:gap-spacing-100 xl:px-spacing-150 xl:pt-spacing-100 xl:rounded-none xl:bg-md-sys-color-surface-container-low',
+            results: 'xl:flex-1 xl:-mx-spacing-150 xl:rounded-none xl:bg-transparent'
+        },
+        docked: {
+            base: 'xl:top-(--sv-top) xl:left-(--sv-left) xl:w-(--sv-width) xl:min-w-(--md-comp-search-view-contained-docked-container-width-minimum) xl:max-w-(--md-comp-search-view-contained-docked-container-width-maximum) xl:h-auto xl:min-h-(--md-comp-search-view-contained-docked-container-height-minimum) xl:max-h-(--sv-max-height) xl:gap-spacing-25 xl:px-spacing-0 xl:pt-spacing-0 xl:rounded-t-xl xl:rounded-b-md xl:bg-transparent',
+            results: 'xl:flex-1 xl:mx-spacing-0 xl:rounded-md xl:bg-md-sys-color-surface-container-high'
+        }
+    }
+};
+/** M3's layout guidance: full-screen on compact windows, docked from medium up. */
+export const defaultSearchLayout = { small: 'fullScreen', medium: 'docked' };
+/**
+ * Resolves a responsive search view layout into classes for the view's slots. Tiers left out
+ * inherit from the one below; below the first given tier the view is full-screen.
+ */
+export function searchViewLayout(layout) {
+    const tiers = typeof layout === 'string' ? { small: layout } : { small: 'fullScreen', ...layout };
+    const pick = (slot) => Object.entries(tiers)
+        .map(([bp, value]) => layoutClasses[bp][value][slot])
+        .join(' ');
+    return { base: pick('base'), results: pick('results') };
+}

package/dist/components/forms/search/types.d.ts

@@ -1,10 +1,78 @@
 import type { IconProps } from '../../../utils/index.js';
 import type { Snippet } from 'svelte';
 import type { HTMLInputAttributes } from 'svelte/elements';
+import type { Responsive } from '../../containers/pane/theme.js';
+/**
+ * Where the search view puts its suggestions and results
+ * (https://m3.material.io/components/search/guidelines).
+ * - `fullScreen`: the view covers the window; for compact windows.
+ * - `docked`: the bar widens in place and results open in a container below it.
+ */
+export type SearchLayout = 'fullScreen' | 'docked';
+/**
+ * Handed to the `results` snippet. Spread it onto the `List` that holds the suggestions, and give
+ * each item `role="option"`, so the field can drive it as a combobox.
+ *
+ * ```svelte
+ * {#snippet results(listbox)}
+ *   <List {...listbox}>
+ *     <ListItem role="option" asChild headline="Material" onclick={pick} />
+ *   </List>
+ * {/snippet}
+ * ```
+ */
+export interface SearchResultsProps {
+    id: string;
+    role: 'listbox';
+    'aria-label': string;
+}
+/** Props shared by the search view and the components that open it. */
+export interface SearchViewOptions {
+    /**
+     * Suggestions and results, shown in the search view. Setting it gives the bar a search view,
+     * opened by clicking or typing in the bar.
+     */
+    results?: Snippet<[SearchResultsProps]>;
+    /**
+     * The search view's layout, one value or one per window tier.
+     * @default { small: 'fullScreen', medium: 'docked' }
+     */
+    layout?: Responsive<SearchLayout>;
+    /** Accessible label for the back button that closes the search view. */
+    backLabel?: string;
+    /** Accessible name of the search view and its suggestion list. Defaults to the placeholder. */
+    resultsLabel?: string;
+}
+/**
+ * Props for the SearchView component.
+ */
+export interface SearchViewProps extends Omit<SearchViewOptions, 'results'> {
+    /** Whether the view is open. Opening and closing morph between `anchor` and the view. */
+    open?: boolean;
+    /** The search query, shared with the bar that opened the view. */
+    value?: string | null;
+    /**
+     * The search bar the view opens from: the container transform starts there, the docked layout
+     * is placed over it, and focus returns to its input on close.
+     */
+    anchor: HTMLElement | undefined;
+    /** Suggestions and results. */
+    results: Snippet<[SearchResultsProps]>;
+    /** Hint text in the view's field. */
+    placeholder?: string;
+    /** Actions after the clear button in the view's bar, e.g. a mic icon button. */
+    trailing?: Snippet;
+    /** Accessible label for the clear button. */
+    clearLabel?: string;
+    /** Extra props for the view's `<input>`. */
+    inputProps?: HTMLInputAttributes;
+    /** Reference to the view's `<input>` while it is open. */
+    inputRef?: HTMLInputElement;
+}
 /**
  * Props for the Search component.
  */
-export interface SearchProps extends Omit<HTMLInputAttributes, 'size'> {
+export interface SearchProps extends Omit<HTMLInputAttributes, 'size' | 'results'>, SearchViewOptions {
     /**
      * The current value of the search input.
      */
@@ -13,12 +81,17 @@ export interface SearchProps extends Omit<HTMLInputAttributes, 'size'> {
      * Reference to the HTML input element.
      */
     elementRef?: HTMLInputElement;
+    /**
+     * Whether the search view is open. Only has an effect with `results`.
+     */
+    open?: boolean;
     /**
      * A leading action, e.g. a menu or back icon button. Replaces the leading icon.
      */
     leading?: Snippet;
     /**
-     * Trailing actions and/or an avatar, e.g. a mic icon button. Rendered after the clear button.
+     * Trailing actions and/or an avatar, e.g. a mic icon button. Rendered after the clear button,
+     * in the bar and in the search view.
      */
     trailing?: Snippet;
     /**

package/dist/components/nav/appbar/AppBar.mdx

@@ -24,12 +24,16 @@ The props form a union, so the bar is one of two kinds:
   `{ small: 'small', large: 'large' }` to grow the bar on wider windows. The switch happens in CSS,
   so server rendering needs no JS.
 - **Search bar.** Pass `search` (the hint text) instead. The bar is always 64dp. `title` then
-  becomes a screen-reader-only heading.
+  becomes a screen-reader-only heading. Per M3, selecting the field should open the search view:
+  pass `searchResults` (and optionally `bind:searchOpen`, `searchLayout`) and it opens the same
+  view as `Search`, with a container transform from the field. See Forms/Search for the view.
 
 <Canvas of={AppBarStories.MediumFlexible} />
 
 <Canvas of={AppBarStories.Search} />
 
+<Canvas of={AppBarStories.SearchView} />
+
 ## Placement
 
 The bar is fixed at the top at every window size. Pass `ghost` to render a same-height spacer

package/dist/components/nav/appbar/AppBar.stories.svelte

@@ -2,6 +2,8 @@
   import { defineMeta } from '@storybook/addon-svelte-csf';
   import AppBar from './AppBar.svelte';
   import ButtonIcon from '../../buttons/ButtonIcon.svelte';
+  import List from '../../containers/list/List.svelte';
+  import ListItem from '../../containers/list/ListItem.svelte';
 
   const { Story } = defineMeta({
     title: 'Navigation/App Bar',
@@ -30,6 +32,11 @@
 
 <script lang="ts">
   let scroller = $state<HTMLElement | null>(null);
+
+  const products = ['Headphones', 'Keyboard', 'Laptop stand', 'Monitor', 'Mouse', 'Webcam'];
+  let query = $state('');
+  let searchOpen = $state(false);
+  const found = $derived(products.filter((p) => p.toLowerCase().includes(query.toLowerCase())));
 </script>
 
 <Story name="Playground">
@@ -125,6 +132,37 @@
   </AppBar>
 </Story>
 
+<!-- Selecting the search field opens the search view: full-screen here, docked from medium up. -->
+<Story
+  name="Search view"
+  asChild
+  parameters={{ docs: { story: { inline: false, height: '560px' } } }}
+>
+  <AppBar search="Search products" title="Products" bind:query bind:searchOpen ghost>
+    {#snippet leading()}
+      <ButtonIcon variant="standard" iconProps={{ name: 'menu' }} aria-label="Menu" />
+    {/snippet}
+    {#snippet searchTrailing()}
+      <ButtonIcon variant="standard" iconProps={{ name: 'mic' }} aria-label="Voice search" />
+    {/snippet}
+    {#snippet searchResults(listbox)}
+      <List {...listbox}>
+        {#each found as product (product)}
+          <ListItem
+            role="option"
+            asChild
+            headline={product}
+            onclick={() => {
+              query = product;
+              searchOpen = false;
+            }}
+          />
+        {/each}
+      </List>
+    {/snippet}
+  </AppBar>
+</Story>
+
 <Story name="Scroll container" asChild>
   <div bind:this={scroller} class="h-[480px] overflow-y-auto">
     <AppBar title="Scroll this box" scrollContainer={scroller} ghost />