@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/search/SearchDrawer.js

@@ -0,0 +1,421 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { NavigationSearchRow, navigationSearchRowOf } from '../navigation/NavigationSearchRow.js';
+import { animateElement } from '../motion/animate.js';
+import { beginSearchBackdrop, endSearchBackdrop, refreshSearchBackdrop } from './searchBackdrop.js';
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, } from 'react';
+import { GlassBackground } from '../glass/GlassEffect.js';
+import { MaterialEffectContext } from '../glass/liquidContext.js';
+import { SearchScopesBar } from './SearchScopesBar.js';
+import { Pressable } from '../press/Pressable.js';
+import { contactTarget, MENU_CONTACT_CLICK_WINDOW_MS, ownPhysicalContact, } from '../press/contactReceipt.js';
+import { focusFromFramework } from '../focus/programmaticFocus.js';
+import { NavigatorContext, ScreenContext } from '../navigation/navigationContext.js';
+import { SymbolImage } from '../symbols/Symbol.js';
+import { TextField } from '../text-input/TextField.js';
+import { validateSearchPresentation } from './searchable.js';
+import { SEARCH_FIELD_SPRING, SEARCH_SCOPES_IN_SPRING, SEARCH_TITLE_IN_SPRING, sampledKeyframes, searchSpring, springTrack, springVelocity, titleFadeOpacity, barItemsFadeOpacity, } from './searchMotion.js';
+/** Scroll distance over which a pinned field turns from its grey fill to glass, like the bar's
+ * scroll edge (navigation/scrollEdge.ts). */
+const PIN_RAMP_PX = 8;
+const TITLE_SELECTOR = ':scope > :is([data-satin-list-title], [data-satin-scroll-title])';
+/**
+ * The navigation bar drawer of a screen's primary scroll view: the search field under the title,
+ * its close button and scope bar, and the suggestions that stand in for the content.
+ *
+ * Every element keeps its place in the DOM in both states, so presenting or dismissing never
+ * inserts or removes chrome. The two layouts are CSS states of the scroll view
+ * (`data-satin-search-presented`), and the change between them is animated from the measured
+ * visual state of each part (FLIP), on the native springs (searchMotion.ts). A retarget mid-way
+ * starts from where everything is on screen, keeping the field's velocity.
+ */
+export function SearchDrawer({ configuration, scroller, }) {
+    validateSearchPresentation(configuration);
+    const liquid = useContext(MaterialEffectContext);
+    const navigator = useContext(NavigatorContext);
+    const screenKey = useContext(ScreenContext)?.key;
+    const stacked = useSyncExternalStore(navigator?.subscribe ?? subscribeNever, () => stackedOver(navigator, screenKey, scroller.current));
+    const drawerRef = useRef(null);
+    const inputRef = useRef(null);
+    const [ownPresented, setOwnPresented] = useState(false);
+    const presented = configuration.isPresented ?? ownPresented;
+    const [submittedText, setSubmittedText] = useState(null);
+    const [animating, setAnimating] = useState(false);
+    const running = useRef(null);
+    const appliedPresented = useRef(null);
+    const configurationRef = useRef(configuration);
+    const liquidRef = useRef(liquid);
+    useLayoutEffect(() => {
+        configurationRef.current = configuration;
+        liquidRef.current = liquid;
+    });
+    const setPresented = useCallback((next) => {
+        const current = configurationRef.current;
+        if (current.isPresented === undefined)
+            setOwnPresented(next);
+        current.onPresentedChange?.(next);
+    }, []);
+    const present = () => {
+        if (!presented)
+            setPresented(true);
+    };
+    const dismiss = () => {
+        inputRef.current?.blur();
+        setSubmittedText(null);
+        if (configurationRef.current.text)
+            configurationRef.current.onTextChange('');
+        setPresented(false);
+    };
+    const change = (text) => {
+        setSubmittedText(null);
+        configuration.onTextChange(text);
+    };
+    const submit = () => {
+        setSubmittedText(configuration.text);
+        inputRef.current?.blur();
+        configuration.onSubmit?.();
+    };
+    const complete = (suggestion) => {
+        change(suggestion.text);
+        if (inputRef.current)
+            focusFromFramework(inputRef.current, { preventScroll: true });
+    };
+    // Native presents the field focused, including a programmatic `isPresented`.
+    useEffect(() => {
+        const input = inputRef.current;
+        if (presented && input && document.activeElement !== input && appliedPresented.current) {
+            focusFromFramework(input, { preventScroll: true });
+        }
+    }, [presented]);
+    useLayoutEffect(() => {
+        const element = scroller.current;
+        const drawer = drawerRef.current;
+        if (!element || !drawer || appliedPresented.current === presented)
+            return;
+        const animate = appliedPresented.current !== null;
+        appliedPresented.current = presented;
+        if (animate) {
+            beginSearchBackdrop(element);
+            element.setAttribute('data-satin-search-moving', '');
+        }
+        const result = transition(element, drawer, presented, animate, running.current);
+        running.current = result;
+        if (!result) {
+            endSearchBackdrop(element);
+            element.removeAttribute('data-satin-search-moving');
+            return;
+        }
+        setAnimating(true);
+        let frame = 0;
+        // The glass renderer follows CSS motion by itself; WAAPI motion needs its regions refreshed.
+        const refresh = () => {
+            refreshSearchBackdrop(element);
+            element.dispatchEvent(new Event('satin:search-geometry'));
+            liquidRef.current?.regions?.invalidate();
+            frame = requestAnimationFrame(refresh);
+        };
+        frame = requestAnimationFrame(refresh);
+        let cancelled = false;
+        void Promise.all(result.animations.map(animation => animation.finished)).then(() => {
+            if (cancelled || running.current !== result)
+                return;
+            running.current = null;
+            element.removeAttribute('data-satin-search-moving');
+            cancelAnimationFrame(frame);
+            endSearchBackdrop(element);
+            element.dispatchEvent(new Event('satin:search-geometry'));
+            liquidRef.current?.regions?.invalidate();
+            setAnimating(false);
+        }, () => { });
+        return () => {
+            cancelled = true;
+            endSearchBackdrop(element);
+            element.removeAttribute('data-satin-search-moving');
+            cancelAnimationFrame(frame);
+        };
+    }, [presented, scroller]);
+    // The bar's own title and items give way to the field while search is presented. The rest of
+    // the shared bar (back control, scroll edge) gives way only while no screen is stacked over this
+    // one: a screen pushed over it draws its bar from the push's first frame, and a pop keeps the
+    // popped screen's bar until that screen is gone (native; owner recording 2026-10-09 04:18).
+    useLayoutEffect(() => {
+        const element = scroller.current;
+        if (!element)
+            return;
+        const { header, edge } = navigationChromeOf(element);
+        const parts = ownBarParts(header, screenKey);
+        for (const part of parts)
+            part.toggleAttribute('data-satin-search-presented', presented);
+        for (const node of [header, edge]) {
+            if (!node)
+                continue;
+            node.toggleAttribute('data-satin-search-presented', presented && !stacked);
+            if (node === header)
+                node.inert = presented && !stacked;
+        }
+        return () => {
+            for (const part of parts)
+                part.removeAttribute('data-satin-search-presented');
+            header?.removeAttribute('data-satin-search-presented');
+            edge?.removeAttribute('data-satin-search-presented');
+            if (header)
+                header.inert = false;
+        };
+    }, [presented, scroller, screenKey, stacked]);
+    // Content scrolled under the pinned field draws its edge material. The field itself is glass
+    // whenever it sits in the bar: from the start when the drawer is fixed under an inline title,
+    // otherwise once it pins (fieldGlassProgress).
+    const fixedDrawer = configuration.placement === 'navigationBarDrawer';
+    useLayoutEffect(() => {
+        const element = scroller.current;
+        const drawer = drawerRef.current;
+        if (!element || !drawer)
+            return;
+        let appliedPin = -1;
+        let appliedGlass = -1;
+        const update = () => {
+            if (running.current)
+                return;
+            const pin = fixedDrawer || presented ? pinProgress(drawer) : 0;
+            const glass = fieldGlassProgress(element, pin, fixedDrawer);
+            if (pin === appliedPin && glass === appliedGlass)
+                return;
+            appliedPin = pin;
+            appliedGlass = glass;
+            drawer.toggleAttribute('data-satin-search-pinned', glass > 0);
+            drawer.style.setProperty('--satin-search-pin', String(pin));
+            drawer.style.setProperty('--satin-search-glass', String(glass));
+            drawer.nextElementSibling?.setAttribute('style', `--satin-search-pin: ${pin}`);
+        };
+        update();
+        element.addEventListener('scroll', update, { passive: true });
+        const resize = new ResizeObserver(update);
+        resize.observe(element);
+        return () => {
+            drawer.removeAttribute('data-satin-search-pinned');
+            element.removeEventListener('scroll', update);
+            resize.disconnect();
+        };
+    }, [scroller, animating, fixedDrawer, presented]);
+    const prompt = configuration.prompt ?? 'Search';
+    const scopes = configuration.scopes;
+    const suggestions = presented && submittedText !== configuration.text ? (configuration.suggestions ?? []) : [];
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: drawerRef, role: "search", "data-satin-search": "", "data-satin-search-automatic": !fixedDrawer || undefined, "data-satin-search-scoped": scopes ? 'true' : undefined, children: [_jsxs(NavigationSearchRow, { children: [_jsxs("div", { "data-satin-search-field": "", children: [_jsx("span", { "data-satin-search-fill": "", "aria-hidden": "true" }), _jsx(GlassBackground, { shape: "capsule", recipe: "searchField" }), _jsx(SymbolImage, { name: "magnifyingglass", weight: "medium", "data-satin-search-magnifier": "" }), _jsx(TextField, { ref: inputRef, label: prompt, labelVisibility: "hidden", variant: "plain", placeholder: prompt, kind: "search", submitLabel: "search", value: configuration.text, onChange: change, onFocus: present, onSubmit: submit, onKeyDown: event => {
+                                            if (event.key !== 'Escape' || event.nativeEvent.isComposing)
+                                                return;
+                                            event.preventDefault();
+                                            dismiss();
+                                        } }), configuration.text && (_jsx(Pressable, { iconOnly: true, "aria-label": "Clear text", "data-satin-search-clear": "", onPress: () => {
+                                            change('');
+                                            if (inputRef.current)
+                                                focusFromFramework(inputRef.current);
+                                        }, children: _jsx(SymbolImage, { name: "xmark.circle.fill" }) }))] }), _jsxs(Pressable, { iconOnly: true, "aria-label": "Close", "data-satin-search-close": "", "data-satin-glass-press": "true", disabled: !presented, onPress: () => {
+                                    // The field widens under the finger as the button leaves. WebKit's synthesized
+                                    // mouse events for this same touch would then focus the field and reopen search
+                                    // (owner, Music, Oct 9): this touch ends here.
+                                    ownPhysicalContact(contactTarget(), closeContactOwner, MENU_CONTACT_CLICK_WINDOW_MS, {
+                                        suppressTouchEnd: true,
+                                    });
+                                    dismiss();
+                                }, children: [_jsx(GlassBackground, { shape: "circle", interactive: true }), _jsx(SymbolImage, { name: "xmark", weight: "medium" })] })] }), scopes && _jsx(SearchScopesBar, { scopes: scopes, presented: presented })] }), _jsx("div", { "data-satin-search-edge": "", "aria-hidden": "true" }), _jsx("div", { "data-satin-search-suggestions": "", role: "list", "aria-label": "Suggestions", hidden: suggestions.length === 0, children: suggestions.map(suggestion => (_jsx(Pressable, { role: "listitem", feedback: "row", "data-satin-search-suggestion": "", onPress: () => complete(suggestion), children: suggestion.label ?? suggestion.text }, suggestion.id))) })] }));
+}
+const closeContactOwner = {};
+function navigationChromeOf(element) {
+    for (let node = element.parentElement; node; node = node.parentElement) {
+        const header = node.querySelector(':scope > [data-satin-navigation-chrome]');
+        if (header) {
+            const edge = node.querySelector(':scope > [data-satin-navigation-edge-host]');
+            return { header, edge };
+        }
+    }
+    return { header: null, edge: null };
+}
+const subscribeNever = () => () => { };
+/** A screen entering, settled or leaving over this one in its pane (a split sidebar has none). */
+function stackedOver(navigator, key, scroller) {
+    if (!navigator || !key)
+        return false;
+    const pane = scroller?.closest('[data-satin-screen-container]')?.dataset.satinPane;
+    if (pane === 'sidebar')
+        return false;
+    const entries = navigator.getState().entries;
+    const index = entries.findIndex(entry => entry.key === key);
+    return index >= 0 && index < entries.length - 1;
+}
+/** This screen's own title layer and toolbar in the shared bar. */
+function ownBarParts(header, key) {
+    if (!header || !key)
+        return [];
+    const parts = header.querySelectorAll('[data-satin-navigation-title-key], [data-satin-entry-toolbar]');
+    return [...parts].filter(part => (part.dataset.satinNavigationTitleKey ?? part.dataset.satinEntryToolbar) === key);
+}
+/** How far content has scrolled under the drawer, as 0 to 1 over PIN_RAMP_PX. */
+function pinProgress(drawer) {
+    const content = contentElements(drawer)[0];
+    if (!content)
+        return 0;
+    const covered = drawer.getBoundingClientRect().bottom - content.getBoundingClientRect().top;
+    return Math.min(1, Math.max(0, covered / PIN_RAMP_PX));
+}
+/* How far the resting field has turned from its grey fill to glass. The field is glass from
+ * scroll 0 only when the drawer is fixed in the bar: an explicit `navigationBarDrawer` placement
+ * (SwiftUI's `displayMode: .always`) under an inline or inlineLarge title (native reference reference and reference
+ * B/H, iOS 27.0: light 251 with a darker rim, dark 32 with a light rim). Under a large title the
+ * field belongs to the content header, and an automatic placement's drawer scrolls away with the
+ * content; both are a grey fill until content scrolls under the field (reference A/C/D/G: light 228-239,
+ * dark 28). */
+function fieldGlassProgress(scroller, pin, fixedDrawer) {
+    const navigation = scroller.dataset.satinListNavigation ?? scroller.dataset.satinScrollNavigation;
+    return fixedDrawer && navigation === 'inline' ? 1 : pin;
+}
+/** The scroll view's content after the drawer: the suggestions, or the app's own content. */
+function contentElements(drawer) {
+    const elements = [];
+    for (let node = drawer.nextElementSibling; node; node = node.nextElementSibling) {
+        if (node.hasAttribute('data-satin-search-edge'))
+            continue;
+        if (node instanceof HTMLElement && node.getClientRects().length > 0)
+            elements.push(node);
+    }
+    return elements;
+}
+const box = (element) => {
+    const rect = element.getBoundingClientRect();
+    return { top: rect.top, left: rect.left, width: rect.width };
+};
+const opacityOf = (element) => Number(getComputedStyle(element).opacity);
+function transition(scroller, drawer, presented, animate, previous) {
+    if (!animate && !presented)
+        return null;
+    const row = navigationSearchRowOf(drawer);
+    const field = row.querySelector('[data-satin-search-field]');
+    const fill = row.querySelector('[data-satin-search-fill]');
+    const material = field.querySelector('[data-satin-glass-region-canvas]');
+    const close = row.querySelector('[data-satin-search-close]');
+    const scopes = drawer.querySelector('[data-satin-search-scopes]');
+    const title = drawer.parentElement?.querySelector(TITLE_SELECTOR) ?? null;
+    const edge = drawer.nextElementSibling?.matches('[data-satin-search-edge]')
+        ? drawer.nextElementSibling
+        : null;
+    const { header } = navigationChromeOf(scroller);
+    // 1. Where everything is on screen now, including any motion still running.
+    const before = {
+        drawer: box(drawer),
+        edge: edge ? box(edge) : undefined,
+        field: box(field),
+        close: box(close),
+        title: title ? box(title) : undefined,
+        content: new Map(contentElements(drawer).map(element => [element, box(element).top])),
+        opacity: {
+            fill: opacityOf(fill),
+            material: material ? opacityOf(material) : 0,
+            close: opacityOf(close),
+            scopes: scopes ? opacityOf(scopes) : 0,
+            title: title ? opacityOf(title) : 0,
+            header: header ? opacityOf(header) : 1,
+        },
+    };
+    const pixelVelocity = previous ? fieldPixelVelocity(previous) : 0;
+    for (const animation of previous?.animations ?? [])
+        animation.cancel();
+    // 2. Switch layouts, keeping the content where it is unless the list rests at its top.
+    const anchor = contentElements(drawer)[0];
+    const anchorBefore = anchor ? box(anchor).top : 0;
+    const scrollBefore = scroller.scrollTop;
+    scroller.toggleAttribute('data-satin-search-presented', presented);
+    drawer.toggleAttribute('data-satin-search-presented', presented);
+    const anchorAfter = anchor?.isConnected ? box(anchor).top : anchorBefore;
+    const keepContent = presented || scrollBefore > 1;
+    scroller.scrollTop = keepContent ? Math.max(0, scrollBefore + anchorAfter - anchorBefore) : 0;
+    if (!animate)
+        return null;
+    // 3. Animate every part from where it was to its new place.
+    const after = { drawer: box(drawer), field: box(field), close: box(close) };
+    const travel = before.drawer.top - after.drawer.top;
+    const spring = searchSpring(SEARCH_FIELD_SPRING, travel ? pixelVelocity / travel : 0);
+    const track = springTrack(spring);
+    const animations = [];
+    const run = (element, keyframes, duration = track.duration) => animations.push(animateElement(element, keyframes, { duration, easing: 'linear' }));
+    run(drawer, translateFrames(track, 0, travel));
+    if (edge && before.edge)
+        run(edge, translateFrames(track, 0, before.edge.top - box(edge).top));
+    run(field, sampledKeyframes(track, progress => ({
+        width: `${before.field.width + (after.field.width - before.field.width) * progress}px`,
+    })));
+    const closeX = before.close.left - after.close.left;
+    const closeY = before.close.top - after.close.top - travel;
+    run(close, sampledKeyframes(track, progress => ({
+        transform: `translate(${closeX * (1 - progress)}px, ${closeY * (1 - progress)}px)`,
+        opacity: mix(before.opacity.close, presented ? 1 : 0, progress),
+        visibility: 'inherit',
+    })));
+    run(fill, fadeFrames(track, before.opacity.fill, opacityOf(fill)));
+    if (material)
+        run(material, fadeFrames(track, before.opacity.material, opacityOf(material)));
+    for (const [element, top] of before.content) {
+        if (!element.isConnected || element.getClientRects().length === 0)
+            continue;
+        run(element, translateFrames(track, 0, top - box(element).top));
+    }
+    // Suggestions that appear with the change start where the content started.
+    const firstBefore = [...before.content.values()][0];
+    for (const element of contentElements(drawer)) {
+        if (before.content.has(element) || firstBefore === undefined)
+            continue;
+        run(element, translateFrames(track, 0, firstBefore - box(element).top));
+    }
+    if (presented) {
+        // The title rides up with the field and fades with its travel; the bar's own title and items
+        // fade with it, faster (native exp(-travel / 9.5 pt)).
+        if (title && before.title) {
+            const offset = before.title.top - box(title).top;
+            run(title, sampledKeyframes(track, progress => ({
+                transform: `translateY(${offset - travel * progress}px)`,
+                opacity: before.opacity.title * titleFadeOpacity(travel * progress),
+            })));
+        }
+        if (header) {
+            run(header, sampledKeyframes(track, progress => ({
+                opacity: before.opacity.header * barItemsFadeOpacity(travel * progress),
+            })));
+        }
+        if (scopes) {
+            const scopesTrack = springTrack(searchSpring(SEARCH_SCOPES_IN_SPRING));
+            run(scopes, sampledKeyframes(scopesTrack, progress => ({
+                opacity: mix(before.opacity.scopes, 1, progress),
+                visibility: 'inherit',
+            })), scopesTrack.duration);
+        }
+    }
+    else {
+        // The scope bar is gone on the first frame; the title rides down with the field and fades
+        // in on its own delayed spring, as do the bar's items.
+        const titleTrack = springTrack(searchSpring(SEARCH_TITLE_IN_SPRING));
+        if (title) {
+            const fade = sampledKeyframes(titleTrack, progress => ({
+                opacity: mix(before.opacity.title, 1, progress),
+            }));
+            run(title, fade, titleTrack.duration);
+            run(title, translateFrames(track, 0, travel), track.duration);
+        }
+        if (header) {
+            run(header, sampledKeyframes(titleTrack, progress => ({
+                opacity: mix(before.opacity.header, 1, progress),
+            })), titleTrack.duration);
+        }
+    }
+    return { animations, spring, startedAt: performance.now(), travel };
+}
+/** The field's vertical velocity on screen (points per second) in a running transition. */
+function fieldPixelVelocity(previous) {
+    const elapsed = performance.now() - previous.startedAt;
+    return previous.travel * springVelocity(previous.spring, elapsed);
+}
+function translateFrames(track, from, delta) {
+    return sampledKeyframes(track, progress => ({
+        transform: `translateY(${from + delta * (1 - progress)}px)`,
+    }));
+}
+function fadeFrames(track, from, to) {
+    return sampledKeyframes(track, progress => ({ opacity: mix(from, to, progress) }));
+}
+const mix = (from, to, progress) => from + (to - from) * progress;

package/dist/search/SearchScopesBar.d.ts

@@ -0,0 +1,6 @@
+import type { SearchScopes } from './searchable.js';
+/** The same controlled scope bar is available under either navigation search placement. */
+export declare function SearchScopesBar({ scopes, presented, }: {
+    scopes: SearchScopes;
+    presented: boolean;
+}): import("react").JSX.Element;

package/dist/search/SearchScopesBar.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { GlassBackground } from '../glass/GlassEffect.js';
+import { SegmentedControl } from '../list-form/ListForm.js';
+/** The same controlled scope bar is available under either navigation search placement. */
+export function SearchScopesBar({ scopes, presented, }) {
+    return (_jsxs("div", { "data-satin-search-scopes": "", inert: !presented, style: { '--satin-search-scope-count': scopes.options.length }, children: [_jsx(GlassBackground, { shape: "capsule", selection: {
+                    index: Math.max(0, scopes.options.findIndex(option => option.id === scopes.selection)),
+                    count: scopes.options.length,
+                    // A released drag of the thumb selects the nearest scope; taps stay with the buttons.
+                    onSelect: index => scopes.onSelectionChange(scopes.options[index].id),
+                } }), _jsx(SegmentedControl, { label: "Search Scope", options: scopes.options, value: scopes.selection, onChange: scopes.onSelectionChange })] }));
+}

package/dist/search/SearchToolbarField.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+import type { Searchable } from './searchable.js';
+export declare function SearchToolbarField({ configuration, scroller, host, navigation, }: {
+    configuration: Searchable;
+    scroller: RefObject<HTMLDivElement | null>;
+    host: HTMLElement;
+    navigation?: boolean;
+}): import("react").JSX.Element;

package/dist/search/SearchToolbarField.js

@@ -0,0 +1,115 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useRef, useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
+import { GlassBackground } from '../glass/GlassEffect.js';
+import { MaterialEffectContext } from '../glass/liquidContext.js';
+import { NavigatorContext, ScreenContext } from '../navigation/navigationContext.js';
+import { Pressable } from '../press/Pressable.js';
+import { contactTarget, MENU_CONTACT_CLICK_WINDOW_MS, ownPhysicalContact, } from '../press/contactReceipt.js';
+import { focusFromFramework } from '../focus/programmaticFocus.js';
+import { SymbolImage } from '../symbols/Symbol.js';
+import { TextField } from '../text-input/TextField.js';
+import { SearchScopesBar } from './SearchScopesBar.js';
+import { navigationChromeOf, ownBarParts, stackedOver, subscribeNever } from './searchChrome.js';
+import { useSearchPresentation } from './useSearchPresentation.js';
+/*
+ * A `searchable` field in the bottom toolbar (iOS 27.0 native reference, iPhone 17 Pro Max):
+ * - at rest, a 48 pt glass capsule in the bottom bar (28,880 384x48 alone; 324x48 beside a compose
+ *   circle), the magnifier 12 pt in and the prompt 40.67 pt in;
+ * - presented, the field rides 8 pt above the keyboard (8,551 364x48) with a 48 pt glass close
+ *   circle 12 pt after it; the screen's title and bar items, including its other bottom items,
+ *   give way, and the content starts at the safe area top.
+ *
+ * `host` is the screen's bottom toolbar slot, or the element a `DefaultToolbarItem kind="search"`
+ * placed among the bottom items. Suggestions stand in for the scroll view's content, as in the
+ * drawer. Presentation is not animated yet: native's motion is not measured (spec notes, reference).
+ */
+export function SearchToolbarField({ configuration, scroller, host, navigation = false, }) {
+    const liquid = useContext(MaterialEffectContext);
+    const navigator = useContext(NavigatorContext);
+    const screenKey = useContext(ScreenContext)?.key;
+    const stacked = useSyncExternalStore(navigator?.subscribe ?? subscribeNever, () => stackedOver(navigator, screenKey, scroller.current));
+    const inputRef = useRef(null);
+    const rowRef = useRef(null);
+    const search = useSearchPresentation(configuration, inputRef);
+    const { presented } = search;
+    // The bar's title and items give way while search is presented; its back control too, unless a
+    // screen is stacked over this one (as the drawer, SearchDrawer.tsx).
+    useLayoutEffect(() => {
+        const element = scroller.current;
+        if (!element || navigation)
+            return;
+        element.toggleAttribute('data-satin-search-presented', presented);
+        const { header } = navigationChromeOf(element);
+        const parts = ownBarParts(header, screenKey);
+        for (const part of parts)
+            part.toggleAttribute('data-satin-search-presented', presented);
+        const hidesBar = presented && !stacked;
+        if (header) {
+            if (hidesBar)
+                header.setAttribute('data-satin-search-presented', 'toolbar');
+            else
+                header.removeAttribute('data-satin-search-presented');
+        }
+        return () => {
+            element.removeAttribute('data-satin-search-presented');
+            for (const part of parts)
+                part.removeAttribute('data-satin-search-presented');
+            header?.removeAttribute('data-satin-search-presented');
+        };
+    }, [presented, scroller, screenKey, stacked, navigation]);
+    // The field moves with the keyboard on the keyboard's own curve (styles.css). Glass regions
+    // follow a moving element only when told: refresh them while it moves.
+    useLayoutEffect(() => {
+        const row = rowRef.current?.closest('[data-satin-navigation-toolbar-slot]');
+        if (!row || !liquid?.regions)
+            return;
+        const regions = liquid.regions;
+        let frame = 0;
+        let moving = 0;
+        const tick = () => {
+            regions.invalidate();
+            frame = moving > 0 ? requestAnimationFrame(tick) : 0;
+        };
+        const start = () => {
+            moving++;
+            if (!frame)
+                frame = requestAnimationFrame(tick);
+        };
+        const end = () => {
+            moving = Math.max(0, moving - 1);
+            regions.invalidate();
+        };
+        regions.invalidate();
+        row.addEventListener('transitionrun', start);
+        row.addEventListener('transitionend', end);
+        row.addEventListener('transitioncancel', end);
+        return () => {
+            cancelAnimationFrame(frame);
+            row.removeEventListener('transitionrun', start);
+            row.removeEventListener('transitionend', end);
+            row.removeEventListener('transitioncancel', end);
+        };
+    }, [liquid?.regions, presented]);
+    const prompt = configuration.prompt ?? 'Search';
+    const ownsItem = !host.hasAttribute('data-satin-search-toolbar-host');
+    const row = (_jsxs("div", { ref: rowRef, role: "search", "data-satin-search-toolbar": "", "data-satin-search-navigation": navigation || undefined, "data-satin-search-toolbar-presented": presented || undefined, children: [_jsxs("div", { "data-satin-search-toolbar-field": "", children: [_jsx(GlassBackground, { shape: "capsule" }), _jsx(SymbolImage, { name: "magnifyingglass", weight: "medium", "data-satin-search-toolbar-magnifier": "" }), _jsx(TextField, { ref: inputRef, label: prompt, labelVisibility: "hidden", variant: "plain", placeholder: prompt, kind: "search", submitLabel: "search", value: configuration.text, onChange: search.change, onFocus: search.present, onSubmit: search.submit, onKeyDown: event => {
+                            if (event.key !== 'Escape' || event.nativeEvent.isComposing)
+                                return;
+                            event.preventDefault();
+                            search.dismiss();
+                        } }), configuration.text && (_jsx(Pressable, { iconOnly: true, "aria-label": "Clear text", "data-satin-search-toolbar-clear": "", onPress: () => {
+                            search.change('');
+                            if (inputRef.current)
+                                focusFromFramework(inputRef.current);
+                        }, children: _jsx(SymbolImage, { name: "xmark.circle.fill" }) }))] }), presented && (_jsxs(Pressable, { iconOnly: true, "aria-label": "Close", "data-satin-search-toolbar-close": "", "data-satin-glass-press": "true", onPress: () => {
+                    // The touch ends here: WebKit's synthesized mouse events must not refocus the field
+                    // that moves under the finger (as the drawer's close button).
+                    ownPhysicalContact(contactTarget(), closeContactOwner, MENU_CONTACT_CLICK_WINDOW_MS, {
+                        suppressTouchEnd: true,
+                    });
+                    search.dismiss();
+                }, children: [_jsx(GlassBackground, { shape: "circle", interactive: true }), _jsx(SymbolImage, { name: "xmark", weight: "medium" })] }))] }));
+    return (_jsxs(_Fragment, { children: [createPortal(ownsItem ? _jsx("div", { "data-satin-toolbar-item": "search", children: row }) : row, host), navigation && configuration.scopes && presented && (_jsx("div", { "data-satin-search-navigation-scopes": "", "data-satin-search-presented": "", children: _jsx(SearchScopesBar, { scopes: configuration.scopes, presented: presented }) })), search.suggestions.length > 0 && (_jsx("div", { "data-satin-search-suggestions": "", role: "list", "aria-label": "Suggestions", children: search.suggestions.map(suggestion => (_jsx(Pressable, { role: "listitem", feedback: "row", "data-satin-search-suggestion": "", onPress: () => search.complete(suggestion), children: suggestion.label ?? suggestion.text }, suggestion.id))) }))] }));
+}
+const closeContactOwner = {};

package/dist/search/searchBackdrop.d.ts

@@ -0,0 +1,12 @@
+/** Source captures remember a logical content origin. Only the drawer's motion loop
+ * measures that origin; unrelated source preparation (including sheets) never does. */
+export type SearchBackdropAnchor = {
+    offset: number;
+};
+/** Called before changing the drawer layout, including when retargeting a running spring. */
+export declare function beginSearchBackdrop(host: HTMLElement): void;
+/** Called on drawer animation frames and once at completion, never on unrelated frames. */
+export declare function refreshSearchBackdrop(host: HTMLElement): void;
+export declare function endSearchBackdrop(host: HTMLElement): void;
+export declare function searchBackdropAnchor(host: HTMLElement): SearchBackdropAnchor | undefined;
+export declare function searchBackdropScroll(host: HTMLElement, anchor?: SearchBackdropAnchor): number;

package/dist/search/searchBackdrop.js

@@ -0,0 +1,45 @@
+const origins = new WeakMap();
+function contentTop(host, element) {
+    return element.getBoundingClientRect().top - host.getBoundingClientRect().top + host.scrollTop;
+}
+/** Called before changing the drawer layout, including when retargeting a running spring. */
+export function beginSearchBackdrop(host) {
+    refreshSearchBackdrop(host);
+    const drawer = host.querySelector('[data-satin-search]');
+    for (let node = drawer?.nextElementSibling; node; node = node.nextElementSibling) {
+        if (!(node instanceof HTMLElement) || node.hasAttribute('data-satin-search-edge'))
+            continue;
+        if (node.hidden || getComputedStyle(node).display === 'none')
+            continue;
+        origins.set(host, {
+            active: true,
+            element: node,
+            top: contentTop(host, node),
+            offset: origins.get(host)?.offset ?? 0,
+        });
+        return;
+    }
+}
+/** Called on drawer animation frames and once at completion, never on unrelated frames. */
+export function refreshSearchBackdrop(host) {
+    const origin = origins.get(host);
+    if (!origin?.active || !origin.element.isConnected || !host.contains(origin.element))
+        return;
+    const top = contentTop(host, origin.element);
+    origin.offset += top - origin.top;
+    origin.top = top;
+}
+export function endSearchBackdrop(host) {
+    refreshSearchBackdrop(host);
+    const origin = origins.get(host);
+    if (origin)
+        origin.active = false;
+}
+export function searchBackdropAnchor(host) {
+    if (!host.hasAttribute('data-satin-searchable'))
+        return;
+    return { offset: origins.get(host)?.offset ?? 0 };
+}
+export function searchBackdropScroll(host, anchor) {
+    return host.scrollTop - (anchor ? (origins.get(host)?.offset ?? 0) - anchor.offset : 0);
+}

package/dist/search/searchChrome.d.ts

@@ -0,0 +1,13 @@
+import type { NavigatorStore } from '../navigation/store.js';
+export declare function navigationChromeOf(element: HTMLElement): {
+    header: HTMLElement;
+    edge: HTMLElement | null;
+} | {
+    header: null;
+    edge: null;
+};
+export declare const subscribeNever: () => () => void;
+/** A screen entering, settled or leaving over this one in its pane (a split sidebar has none). */
+export declare function stackedOver(navigator: NavigatorStore | undefined, key: string | undefined, scroller: HTMLElement | null): boolean;
+/** This screen's own title layer and toolbar in the shared bar. */
+export declare function ownBarParts(header: HTMLElement | null, key: string | undefined): HTMLElement[];