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

package/dist/glass/MenuStack.js

@@ -0,0 +1,371 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useRef, useState, } from 'react';
+import { ActionButton, ActionMenu } from '../actions/ActionMenu.js';
+import { focusFromFramework } from '../focus/programmaticFocus.js';
+import { holdPresentationForGlass } from '../presentation/glassReady.js';
+import { SymbolImage } from '../symbols/Symbol.js';
+import { animateElement } from '../motion/animate.js';
+import { GlassEffect } from './GlassEffect.js';
+import { MaterialEffectContext } from './liquidContext.js';
+import { ancestorScale, animateSubmenuFrame, chevronKeyframes, holdSubmenuFrame, padSubmenuFrame, phoneSubmenuFrame, springKeyframes, submenuContentPlace, submenuVisibleFrame, SUBMENU_GEOMETRY, SUBMENU_SPRINGS, titleOnRow, } from './submenuMotion.js';
+/** What leaving a whole open menu looks like: the platters shrink toward the top of the menu and
+ * fade out within a quarter second (native trace, dismissal from a submenu: opacity 0.78, 0.33,
+ * 0.09, 0.01 at 35, 102, 168 and 235 ms; width 82, 47, 27, 21 % at the same times). */
+const CHAIN_DISMISSAL = [
+    { offset: 0, opacity: 1, transform: 'scale(1)' },
+    { offset: 35 / 235, opacity: 0.78, transform: 'scale(0.82)' },
+    { offset: 102 / 235, opacity: 0.33, transform: 'scale(0.47)' },
+    { offset: 168 / 235, opacity: 0.09, transform: 'scale(0.27)' },
+    { offset: 1, opacity: 0, transform: 'scale(0.21)' },
+];
+const CHAIN_DISMISSAL_MS = 235;
+let nextLevelKey = 0;
+/**
+ * A menu and the submenus open above it, drawn as one stack. The root level is drawn inside the
+ * menu's own glass (`children` receives its rows); each submenu is a platter of its own. On
+ * iPhone a submenu covers its parent, which shrinks and dims behind it; its title row leads back.
+ * On iPad submenus cascade beside their parents, which stay live: choosing the open row again
+ * closes its submenu, and choosing another row of the parent replaces it.
+ */
+export function MenuStack({ actions, select, idiom, closing, cornerRadius, readBounds, backRef, children, }) {
+    const [levels, setLevels] = useState([]);
+    const [leaving, setLeaving] = useState([]);
+    const rootLevel = useRef(null);
+    const platters = useRef(new Map());
+    /** The row to focus once a back transition has re-rendered its level. */
+    const returnFocus = useRef(undefined);
+    /** The stack's coordinate origin: the top-left corner of the root platter's layout box. */
+    const origin = () => {
+        const root = rootGlass();
+        const rect = root?.getBoundingClientRect();
+        if (!root || !rect)
+            return { x: 0, y: 0 };
+        // The root may be shrunk about its top edge while it is covered; its layout box is not.
+        return { x: rect.left - (root.offsetWidth - rect.width) / 2, y: rect.top };
+    };
+    const rootGlass = () => rootLevel.current?.closest('[data-satin-glass-effect]') ?? undefined;
+    const levelElement = (depth) => depth === 0 ? rootGlass() : platters.current.get(levels[depth - 1]?.key ?? -1);
+    const open = (parentDepth) => (action, row) => {
+        const current = levels[parentDepth];
+        if (current?.action.id === action.id) {
+            // iPad: choosing the open row again closes its submenu.
+            back(parentDepth);
+            return;
+        }
+        const start = origin();
+        const rect = row.getBoundingClientRect();
+        const level = {
+            key: ++nextLevelKey,
+            action,
+            parentDepth,
+            row: {
+                x: rect.left - start.x,
+                y: rect.top - start.y,
+                width: rect.width,
+                height: rect.height,
+            },
+        };
+        setLeaving(previous => [...previous, ...levels.slice(parentDepth)]);
+        setLevels([...levels.slice(0, parentDepth), level]);
+    };
+    /** Close every submenu above `depth`, returning focus to the row that opened the first. */
+    const back = (depth) => {
+        const closed = levels.slice(depth);
+        if (!closed.length)
+            return;
+        returnFocus.current = { depth, id: closed[0].action.id };
+        setLeaving(previous => [...previous, ...closed]);
+        setLevels(levels.slice(0, depth));
+    };
+    backRef.current = () => {
+        if (!levels.length)
+            return false;
+        back(levels.length - 1);
+        return true;
+    };
+    useLayoutEffect(() => {
+        const target = returnFocus.current;
+        if (!target)
+            return;
+        returnFocus.current = undefined;
+        const level = target.depth === 0 ? rootLevel.current : levelElement(target.depth);
+        const row = [
+            ...(level?.querySelectorAll('[data-satin-action-id]') ?? []),
+        ].find(element => element.dataset.satinActionId === target.id);
+        if (row)
+            focusFromFramework(row, { preventScroll: true });
+    });
+    // iPhone: every level below the top submenu shrinks and dims behind it.
+    const covering = (depth) => (idiom === 'phone' ? levels.length - depth : 0);
+    useAncestorPresentation(rootGlass, rootLevel, covering(0), closing);
+    const frameOf = (depth, element) => {
+        if (!element)
+            return undefined;
+        if (depth === 0)
+            return { x: 0, y: 0, width: element.offsetWidth, height: element.offsetHeight };
+        const visible = submenuVisibleFrame(element);
+        if (visible)
+            return visible;
+        const style = element.style;
+        return {
+            x: parseFloat(style.left),
+            y: parseFloat(style.top),
+            width: element.offsetWidth,
+            height: element.offsetHeight,
+        };
+    };
+    const settleFrame = (level, size) => {
+        const parent = frameOf(level.parentDepth, levelElement(level.parentDepth));
+        const start = origin();
+        const viewport = readBounds();
+        const bounds = { ...viewport, x: viewport.x - start.x, y: viewport.y - start.y };
+        if (!parent)
+            return { ...level.row, width: size.width, height: size.height };
+        return idiom === 'phone'
+            ? phoneSubmenuFrame(parent, level.row, ancestorScale(1), size, bounds)
+            : padSubmenuFrame(parent, level.row, { ...size, firstRowOffset: size.firstRow }, bounds);
+    };
+    const rootRows = (_jsx("div", { ref: rootLevel, "data-satin-menu-level": "0", inert: (covering(0) > 0 && !closing) || undefined, children: _jsx(ActionMenu, { actions: actions, select: select, openSubmenu: open(0), expandedId: levels[0]?.action.id }) }));
+    return (_jsxs(_Fragment, { children: [children(rootRows), [
+                ...levels.map((level, index) => ({ level, depth: index + 1 })),
+                ...leaving.map(level => ({ level, depth: -1 })),
+            ].map(({ level, depth }) => (_jsx(SubmenuPlatter, { level: level, idiom: idiom, cornerRadius: cornerRadius, covering: depth < 0 ? 0 : covering(depth), leaving: depth < 0, closing: closing, register: element => {
+                    if (element)
+                        platters.current.set(level.key, element);
+                    else
+                        platters.current.delete(level.key);
+                }, settleFrame: size => settleFrame(level, size), select: select, openSubmenu: depth < 0 ? undefined : open(depth), expandedId: depth < 0 ? undefined : levels[depth]?.action.id, onBack: () => back(depth - 1), onFailure: () => {
+                    returnFocus.current = { depth: level.parentDepth, id: level.action.id };
+                    setLevels(previous => {
+                        const index = previous.findIndex(entry => entry.key === level.key);
+                        return index < 0 ? previous : previous.slice(0, index);
+                    });
+                }, onLeft: () => setLeaving(previous => previous.filter(entry => entry !== level)) }, level.key)))] }));
+}
+/** Shrink and dim a level while submenus cover it, on the measured springs; restore it after. */
+function useAncestorPresentation(glass, rows, covering, closing) {
+    const previous = useRef(0);
+    useLayoutEffect(() => {
+        const element = glass();
+        const ink = rows.current;
+        const target = closing ? 0 : covering;
+        const from = previous.current;
+        previous.current = target;
+        if (!element || !ink || from === target)
+            return;
+        const springs = target > from ? SUBMENU_SPRINGS.open : SUBMENU_SPRINGS.back;
+        const currentScale = readScale(element);
+        const currentInk = Number.parseFloat(getComputedStyle(ink).opacity) || 1;
+        for (const animation of [...element.getAnimations(), ...ink.getAnimations()])
+            if (animation.id === 'satin-submenu-ancestor')
+                animation.cancel();
+        const scale = ancestorScale(target);
+        const opacity = target > 0 ? SUBMENU_GEOMETRY.parentInk : 1;
+        element.style.transformOrigin = '50% 0';
+        const scaling = springKeyframes(springs.parentScale, progress => ({
+            transform: `scale(${currentScale + (scale - currentScale) * progress})`,
+        }));
+        const dimming = springKeyframes(springs.parentInk, progress => ({
+            opacity: currentInk + (opacity - currentInk) * progress,
+        }));
+        const delay = 'delay' in springs.parentInk ? springs.parentInk.delay : 0;
+        const scaleAnimation = animateElement(element, scaling.keyframes, {
+            duration: scaling.duration,
+            fill: 'forwards',
+            id: 'satin-submenu-ancestor',
+        });
+        const inkAnimation = animateElement(ink, dimming.keyframes, {
+            duration: dimming.duration,
+            delay,
+            fill: 'both',
+            id: 'satin-submenu-ancestor',
+        });
+        if (target === 0) {
+            // Restored levels drop their fills, so nothing outlives the transition.
+            void scaleAnimation.finished.then(() => scaleAnimation.cancel(), () => { });
+            void inkAnimation.finished.then(() => inkAnimation.cancel(), () => { });
+        }
+    });
+}
+function readScale(element) {
+    const transform = getComputedStyle(element).transform;
+    if (!transform || transform === 'none')
+        return 1;
+    const matrix = new DOMMatrixReadOnly(transform);
+    return Math.hypot(matrix.a, matrix.b);
+}
+/** One submenu: its own glass platter, which grows out of the row that opened it. */
+function SubmenuPlatter({ level, idiom, cornerRadius, covering, leaving, closing, register, settleFrame, select, openSubmenu, expandedId, onBack, onLeft, onFailure, }) {
+    const liquid = useContext(MaterialEffectContext);
+    const frame = useRef(null);
+    const clip = useRef(null);
+    const content = useRef(null);
+    const rows = useRef(null);
+    const settled = useRef(undefined);
+    const [shown, setShown] = useState(false);
+    const lifecycle = useRef({ leaving, closing, onFailure });
+    lifecycle.current = { leaving, closing, onFailure };
+    const retireEntrance = useRef(() => { });
+    const glass = () => frame.current?.querySelector('[data-satin-glass-effect]') ?? undefined;
+    useAncestorPresentation(glass, rows, covering, closing);
+    const phone = idiom === 'phone';
+    const movingParts = () => {
+        const platter = frame.current;
+        const glassElement = glass();
+        if (!platter || !glassElement || !clip.current || !content.current)
+            return undefined;
+        return {
+            platter,
+            glass: glassElement,
+            clip: clip.current,
+            content: content.current,
+            cornerRadius,
+        };
+    };
+    /** Where the content must sit for its title row to cover the row that opened it. On iPad the
+     * cascade has no title: its content starts where its glass does. */
+    const contentAtRow = () => {
+        const measured = content.current;
+        const title = measured?.querySelector('[data-satin-submenu-title]');
+        if (!phone || !measured || !title)
+            return { x: level.row.x, y: level.row.y };
+        const outer = measured.getBoundingClientRect();
+        const inner = title.getBoundingClientRect();
+        return titleOnRow(level.row, { x: inner.left - outer.left, y: inner.top - outer.top });
+    };
+    // Enter: measure the platter's own size, then grow out of the row once its glass is drawn.
+    useLayoutEffect(() => {
+        const element = frame.current;
+        const measured = content.current;
+        if (!element || !measured)
+            return;
+        const firstRow = measured.querySelector('[data-satin-action-id]');
+        const to = settleFrame({
+            width: measured.offsetWidth,
+            height: measured.offsetHeight,
+            firstRow: firstRow?.offsetTop ?? 0,
+        });
+        settled.current = to;
+        const from = level.row;
+        const held = movingParts();
+        if (held)
+            holdSubmenuFrame(held, from, to, contentAtRow(), 'open');
+        let retired = false;
+        let stop = () => { };
+        const canReveal = () => !retired && !lifecycle.current.leaving && !lifecycle.current.closing;
+        const enter = () => {
+            const moving = movingParts();
+            if (!canReveal() || !moving)
+                return;
+            setShown(true);
+            crossfadeTitle(element, 'open');
+            turnChevron(element, 'open');
+            stop = animateSubmenuFrame(moving, from, to, contentAtRow(), to, 'open');
+            const first = [...measured.querySelectorAll('[data-satin-action-id]')].find(row => !row.matches(':disabled, [aria-disabled="true"]'));
+            if (first)
+                focusFromFramework(first, { preventScroll: true });
+        };
+        const regions = liquid?.regions;
+        const release = regions
+            ? holdPresentationForGlass(element, null, [], () => regions.invalidate(), enter, canReveal, {
+                onFailure: () => lifecycle.current.onFailure(),
+            })
+            : (enter(), () => { });
+        const retire = () => {
+            retired = true;
+            release();
+            stop();
+        };
+        retireEntrance.current = retire;
+        return retire;
+        // The platter enters once, when it mounts.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Back: collapse into the row that opened it while its rows fade, then leave.
+    useLayoutEffect(() => {
+        const element = frame.current;
+        const moving = movingParts();
+        if (!leaving || closing || !element || !moving)
+            return;
+        retireEntrance.current();
+        const from = submenuVisibleFrame(element) ?? {
+            x: parseFloat(element.style.left),
+            y: parseFloat(element.style.top),
+            width: element.offsetWidth,
+            height: element.offsetHeight,
+        };
+        const contentFrom = submenuContentPlace(element) ?? from;
+        const fade = springKeyframes(SUBMENU_SPRINGS.back.fade, progress => ({
+            opacity: 1 - progress,
+        }));
+        // Everything but the title fades: the title becomes the parent's row again.
+        const parts = element.querySelectorAll('[data-satin-action-menu] > :not([data-satin-submenu-title])');
+        const fading = [...parts].map(part => animateElement(part, fade.keyframes, { duration: fade.duration, fill: 'forwards' }));
+        crossfadeTitle(element, 'back');
+        turnChevron(element, 'back');
+        const stop = animateSubmenuFrame(moving, from, level.row, contentFrom, contentAtRow(), 'back', onLeft);
+        return () => {
+            stop();
+            for (const animation of fading)
+                animation.cancel();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [leaving, closing]);
+    // The whole menu closing takes every platter with it.
+    useLayoutEffect(() => {
+        const element = frame.current;
+        if (!closing || !element)
+            return;
+        retireEntrance.current();
+        element.style.transformOrigin = '50% 0';
+        const animation = animateElement(element, CHAIN_DISMISSAL, {
+            duration: CHAIN_DISMISSAL_MS,
+            easing: 'linear',
+            fill: 'forwards',
+        });
+        return () => animation.cancel();
+    }, [closing]);
+    const action = level.action;
+    const title = phone ? (_jsxs(_Fragment, { children: [_jsxs(ActionButton, { role: "menuitem", "aria-expanded": "true", "aria-haspopup": "menu", "data-satin-submenu-title": "true", onPress: onBack, children: [action.icon ?? (action.symbol ? _jsx(SymbolImage, { name: action.symbol }) : null), _jsxs("span", { "data-satin-action-label": "true", "data-satin-submenu-title-label": "true", children: [_jsx("span", { "data-satin-submenu-title-bold": "true", children: action.label }), _jsx("span", { "data-satin-submenu-title-regular": "true", "aria-hidden": "true", children: action.label })] }), _jsx("span", { role: "presentation", "data-satin-submenu-chevron": "true", children: _jsx(SymbolImage, { name: "chevron.down" }) })] }), _jsx("div", { "data-satin-submenu-separator": "true" })] })) : undefined;
+    return (_jsx("div", { ref: element => {
+            frame.current = element;
+            register(element);
+        }, "data-satin-submenu-frame": "true", "data-satin-submenu-leaving": leaving || undefined, style: { visibility: shown ? undefined : 'hidden' }, inert: leaving || covering > 0 || undefined, children: _jsx(GlassEffect, { touchLight: true, role: "menu", "aria-label": action.label, shape: { kind: 'roundedRectangle', cornerRadius }, "data-satin-general-menu": "true", "data-satin-submenu-platter": "true", "data-satin-keep-keyboard": "true", "data-satin-menu-idiom": idiom, style: { position: 'absolute', inset: 0 }, children: _jsx("div", { ref: clip, "data-satin-submenu-clip": "true", style: { borderRadius: cornerRadius }, children: _jsx("div", { ref: content, "data-satin-submenu-content": "true", children: _jsx("div", { ref: rows, "data-satin-menu-level": level.parentDepth + 1, children: _jsx(ActionMenu, { actions: action.submenu, select: select, openSubmenu: openSubmenu, expandedId: expandedId, onBack: onBack, header: title }) }) }) }) }) }));
+}
+/** The title's label is bold while it heads its submenu and regular while it is the parent's row:
+ * the two cross-fade as the platter grows out of the row and collapses back into it. */
+function crossfadeTitle(platter, direction) {
+    const bold = platter.querySelector('[data-satin-submenu-title-bold]');
+    const regular = platter.querySelector('[data-satin-submenu-title-regular]');
+    if (!bold || !regular)
+        return;
+    const springs = direction === 'open' ? SUBMENU_SPRINGS.open.frame : SUBMENU_SPRINGS.back.fade;
+    const fade = (from, to) => springKeyframes(springs, progress => ({ opacity: from + (to - from) * progress }));
+    const showBold = direction === 'open';
+    const boldFade = fade(showBold ? 0 : 1, showBold ? 1 : 0);
+    const regularFade = fade(showBold ? 1 : 0, showBold ? 0 : 1);
+    animateElement(bold, boldFade.keyframes, { duration: boldFade.duration, fill: 'forwards' });
+    animateElement(regular, regularFade.keyframes, {
+        duration: regularFade.duration,
+        fill: 'forwards',
+    });
+}
+/** Turn the title's chevron between forward (the parent row's) and down (the open title's), from
+ * wherever an interrupted turn left it. */
+function turnChevron(platter, direction) {
+    const chevron = platter.querySelector('[data-satin-submenu-chevron]');
+    if (!chevron)
+        return;
+    const current = chevron.getAnimations().length ? readRotation(chevron) : undefined;
+    for (const animation of chevron.getAnimations())
+        animation.cancel();
+    const turn = chevronKeyframes(direction, current);
+    animateElement(chevron, turn.keyframes, { duration: turn.duration, fill: 'forwards' });
+}
+function readRotation(element) {
+    const transform = getComputedStyle(element).transform;
+    if (!transform || transform === 'none')
+        return 0;
+    const matrix = new DOMMatrixReadOnly(transform);
+    return (Math.atan2(matrix.b, matrix.a) * 180) / Math.PI;
+}

package/dist/glass/MenuSymbol.d.ts

@@ -0,0 +1,7 @@
+import type { MenuSymbolName } from './menuSymbolMasks.js';
+/** The menu keeps ownership of its leading aperture; artwork belongs to SymbolImage. In a selection
+ * row the checkmark keeps the aperture and the symbol follows it. */
+export declare function MenuSymbol({ name, followsCheckmark, }: {
+    name: MenuSymbolName;
+    followsCheckmark?: boolean;
+}): import("react").JSX.Element;

package/dist/glass/MenuSymbol.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SymbolImage } from '../symbols/Symbol.js';
+/* Where a selection row's icon starts when its checkmark holds the leading aperture (iOS 27
+ * native reference menu Picker of Labels: checkmark at 12 pt, icon 35-55 pt, title at 71 pt). */
+const ICON_AFTER_CHECKMARK_LEFT_PT = 32;
+/** The menu keeps ownership of its leading aperture; artwork belongs to SymbolImage. In a selection
+ * row the checkmark keeps the aperture and the symbol follows it. */
+export function MenuSymbol({ name, followsCheckmark = false, }) {
+    return (_jsx(SymbolImage, { name: name, "data-satin-menu-symbol": name, "data-satin-menu-symbol-follows-check": followsCheckmark ? 'true' : undefined, style: {
+            position: 'absolute',
+            pointerEvents: 'none',
+            left: followsCheckmark ? ICON_AFTER_CHECKMARK_LEFT_PT : 20,
+            top: 9,
+            fontSize: 20,
+        } }));
+}

package/dist/glass/MorphEllipsisArtwork.d.ts

@@ -0,0 +1,2 @@
+/** The enclosing control owns the accessible label. */
+export declare function MorphEllipsisArtwork(): import("react").JSX.Element;

package/dist/glass/MorphEllipsisArtwork.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SymbolImage } from '../symbols/Symbol.js';
+/** The enclosing control owns the accessible label. */
+export function MorphEllipsisArtwork() {
+    return _jsx(SymbolImage, { name: "ellipsis", "data-satin-icon": "ellipsis", style: { fontSize: 22 } });
+}

package/dist/glass/TabBar.d.ts

@@ -0,0 +1,29 @@
+import { type SymbolName } from '../symbols/Symbol.js';
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type GlassVariant } from './tokens.js';
+export type TabBarItem = Readonly<{
+    accessibilityLabel?: string;
+    panelId?: string;
+    tabId?: string;
+    badge?: number | 'dot';
+    disabled?: boolean;
+    icon?: ReactNode;
+    symbol?: SymbolName;
+    role?: 'search';
+    id: string;
+    label: ReactNode;
+}>;
+export type TabBarProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'onSelect'> & Readonly<{
+    items: readonly TabBarItem[];
+    onSelect: (id: string) => void;
+    selected: string;
+    adaptive?: boolean;
+    onShowSidebar?: () => void;
+    variant?: GlassVariant;
+}>;
+/** An item's horizontal extent inside the tab bar host, in CSS pixels from its left edge. */
+export type TabItemFrame = Readonly<{
+    x: number;
+    width: number;
+}>;
+export declare function TabBar({ className, adaptive, onShowSidebar, items: declaredItems, onSelect, selected, style, variant, ...props }: TabBarProps): import("react").JSX.Element | null;

package/dist/glass/TabBar.js

@@ -0,0 +1,169 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { orderedTabItems, TopTabLabel } from '../tabs/presentation.js';
+import { handleTabKeyDown } from '../tabs/keyboard.js';
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
+import { SymbolImage, SymbolSelectionContext } from '../symbols/Symbol.js';
+import { focusFromFramework } from '../focus/programmaticFocus.js';
+import { GlassBackground } from './GlassEffect.js';
+import { Glass } from './regions.js';
+import { MaterialEffectContext } from './liquidContext.js';
+import { sidebarCssTokens } from '../settings/tokens.js';
+import { AdaptiveTabsContext } from '../layout/adaptiveTabsContext.js';
+import { useSafeAreaMetrics } from '../safe-area/useSafeAreaMetrics.js';
+import { GLASS_DOCK_HEIGHT_PX, glassDockHeight, glassDockWidth } from './lens/Scene.js';
+import { useLayoutClass } from '../root/runtimeContext.js';
+import { useId, useMemo, useContext, useLayoutEffect, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { Pressable } from '../press/Pressable.js';
+import { useGlassMaterialContext } from './context.js';
+import { resolveTabBarModel, TabBarAccessoryContext } from './tabBarModel.js';
+import {} from './tokens.js';
+export function TabBar({ className, adaptive = true, onShowSidebar, items: declaredItems, onSelect, selected, style, variant = 'regular', ...props }) {
+    const liquid = useContext(MaterialEffectContext);
+    const layoutClass = useLayoutClass();
+    const metrics = useSafeAreaMetrics();
+    const { register, unregister } = useContext(AdaptiveTabsContext);
+    const sidebar = adaptive && readDeviceIdiom() === 'pad' && layoutClass.horizontal === 'regular';
+    const items = useMemo(() => (sidebar ? orderedTabItems(declaredItems, 'top') : declaredItems), [declaredItems, sidebar]);
+    // The regular-width iPad bar runs on the same glass tab engine as the phone dock (lens on
+    // press, drag to select). This bar only lays out and measures the items; the engine draws
+    // the material, the selection, the lens and the accessible tab buttons on top of it.
+    // A bar that also carries the Show Tab Sidebar control keeps the DOM bar for now.
+    const liquidTop = sidebar && liquid !== null && !onShowSidebar;
+    const [itemFrames, setItemFrames] = useState();
+    const { selectedIndex } = resolveTabBarModel(items, selected, sidebar && !!onShowSidebar);
+    const { chromeLayer, registerRegion } = useGlassMaterialContext();
+    const regionId = useId();
+    const elementRef = useRef(null);
+    const hasAccessory = useContext(TabBarAccessoryContext);
+    const compact = readDeviceIdiom() === 'phone' && metrics.layoutViewport.width > metrics.layoutViewport.height;
+    const intrinsicWidth = readDeviceIdiom() === 'phone' && !compact && items.length < 4 && !hasAccessory;
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element || sidebar)
+            return;
+        return registerRegion({ element, id: regionId, radius: 30, variant });
+    }, [chromeLayer, regionId, registerRegion, variant, sidebar]);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element || !sidebar)
+            return;
+        const update = () => register(regionId, element.getBoundingClientRect().height);
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+            unregister(regionId);
+        };
+    }, [chromeLayer, register, unregister, regionId, sidebar]);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element || !liquidTop)
+            return;
+        const measure = () => {
+            const host = element.getBoundingClientRect();
+            const frames = [...element.querySelectorAll('[data-satin-tab-item]')].map(item => {
+                const rect = item.getBoundingClientRect();
+                return { x: rect.left - host.left, width: rect.width };
+            });
+            setItemFrames(previous => previous && JSON.stringify(previous) === JSON.stringify(frames) ? previous : frames);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [chromeLayer, liquidTop, items]);
+    useLayoutEffect(() => {
+        if (!liquidTop || !itemFrames)
+            return;
+        liquid?.registerTabs(regionId, {
+            items,
+            selected,
+            onSelect,
+            adaptive,
+            variant,
+            insetHost: elementRef.current ?? undefined,
+            placement: 'top',
+            itemFrames,
+        });
+        return () => liquid?.registerTabs(regionId, undefined);
+    }, [
+        liquid?.registerTabs,
+        regionId,
+        items,
+        selected,
+        onSelect,
+        adaptive,
+        variant,
+        liquidTop,
+        itemFrames,
+    ]);
+    useLayoutEffect(() => {
+        if (sidebar)
+            return;
+        liquid?.registerTabs(regionId, {
+            items,
+            selected,
+            onSelect,
+            adaptive,
+            variant,
+            insetHost: elementRef.current ?? undefined,
+            intrinsicWidth,
+        });
+        return () => liquid?.registerTabs(regionId, undefined);
+    }, [
+        liquid?.registerTabs,
+        regionId,
+        items,
+        selected,
+        onSelect,
+        adaptive,
+        variant,
+        sidebar,
+        intrinsicWidth,
+    ]);
+    if (!sidebar)
+        return (_jsx("div", { ref: element => {
+                elementRef.current = element;
+            }, "data-satin-tab-inset": "true", style: {
+                height: compact
+                    ? glassDockHeight(metrics.layoutViewport.width, metrics.layoutViewport.height)
+                    : metrics.layoutViewport.width > metrics.layoutViewport.height
+                        ? 48
+                        : GLASS_DOCK_HEIGHT_PX,
+                width: compact || intrinsicWidth
+                    ? 'max-content'
+                    : glassDockWidth(metrics.layoutViewport.width, metrics.screen, metrics.insets, metrics.layoutViewport.height),
+                maxWidth: glassDockWidth(metrics.layoutViewport.width, metrics.screen, metrics.insets, metrics.layoutViewport.height),
+                transform: `translateX(${(metrics.insets.left - metrics.insets.right) / 2}px)`,
+            }, children: (compact || intrinsicWidth) && (_jsx("div", { "data-satin-tab-size-probe": compact ? 'true' : 'portrait', style: { '--satin-tab-count': items.length }, "aria-hidden": "true", inert: true, children: items.map(item => (_jsxs("span", { children: [compact &&
+                            (item.symbol ? (_jsx(SymbolImage, { name: item.symbol, style: { fontSize: 20 } })) : (item.icon)), _jsx("small", { children: item.label })] }, item.id))) })) }));
+    if (!chromeLayer)
+        return null;
+    if (liquidTop)
+        return createPortal(_jsx("nav", { ref: elementRef, "aria-hidden": "true", inert: true, className: className, "data-satin-tab-placement": "top", "data-satin-tab-bar": "true", "data-satin-tab-sizing": "true", style: { ...style, ...sidebarCssTokens }, children: _jsx("div", { "data-satin-tab-items": "true", children: items.map(item => (_jsx("span", { "data-satin-tab-item": "true", children: _jsx("span", { "data-satin-tab-label": "true", children: _jsx(TopTabLabel, { item: item }) }) }, item.id))) }) }), chromeLayer);
+    const tabBarStyle = {
+        ...style,
+        ...(sidebar ? sidebarCssTokens : {}),
+        '--satin-tab-count': items.length,
+        '--satin-tab-selection-offset': `${selectedIndex * 100}%`,
+        '--satin-tab-selected-index': selectedIndex,
+    };
+    return createPortal(_jsxs("nav", { ...props, ref: elementRef, role: "tablist", onKeyDown: handleTabKeyDown, "aria-label": props['aria-label'] ?? 'App tabs', className: className, "data-satin-glass-region": sidebar ? undefined : regionId, "data-satin-tab-placement": sidebar ? 'top' : 'bottom', "data-satin-glass-variant": variant, "data-satin-role": "chrome", "data-satin-tab-bar": "true", style: tabBarStyle, children: [_jsx(GlassBackground, { glass: variant === 'clear' ? Glass.clear : Glass.regular }), _jsxs("div", { "data-satin-tab-items": "true", children: [onShowSidebar && (_jsx(Pressable, { "data-satin-tab-sidebar-show": "true", "aria-label": "Show Tab Sidebar", onPress: onShowSidebar, children: _jsx(SymbolImage, { name: "sidebar.left" }) })), items.map((item, index) => {
+                        const isSelected = item.id === selected;
+                        return (_jsxs(Pressable, { role: "tab", id: item.tabId, "aria-controls": item.panelId, "aria-selected": isSelected, tabIndex: isSelected || (selectedIndex < 0 && index === 0) ? 0 : -1, "aria-label": item.accessibilityLabel ??
+                                (sidebar && item.role === 'search'
+                                    ? typeof item.label === 'string'
+                                        ? item.label
+                                        : 'Search'
+                                    : undefined), "data-satin-tab-item": "true", "data-satin-tab-selected": isSelected || undefined, disabled: item.disabled, onPress: () => {
+                                // VoiceOver activation can reach onPress before DOM focus follows
+                                // its cursor. Establish tab ownership before mounting the panel.
+                                const button = elementRef.current?.querySelectorAll('[data-satin-tab-item]')[index];
+                                if (button)
+                                    focusFromFramework(button, { preventScroll: true });
+                                onSelect(item.id);
+                            }, children: [_jsxs("span", { "aria-hidden": "true", "data-satin-tab-icon": "true", children: [_jsx(SymbolSelectionContext, { value: isSelected, children: item.symbol ? (_jsx(SymbolImage, { name: item.symbol, style: { fontSize: 23.4 } })) : (item.icon) }), item.badge !== undefined && (_jsx("span", { "data-satin-tab-badge": item.badge === 'dot' ? 'dot' : 'number', children: item.badge === 'dot' ? null : item.badge }))] }), _jsx("span", { "data-satin-tab-label": "true", children: sidebar ? _jsx(TopTabLabel, { item: item }) : item.label })] }, item.id));
+                    })] })] }), chromeLayer);
+}

package/dist/glass/capability.d.ts

@@ -0,0 +1,25 @@
+export type GlassCapabilityState = 'baseline' | 'displacement';
+export type GlassRenderTestState = 'pending' | 'passed' | 'failed';
+export type GlassAccessibilityPreferences = Readonly<{
+    increasedContrast: boolean;
+    reducedMotion: boolean;
+    reducedTransparency: boolean;
+}>;
+export type GlassCapabilityDecision = Readonly<{
+    reason: 'renderer-required' | 'forced-baseline' | 'render-test-failed' | 'render-test-pending' | 'reduced-transparency' | 'raster-probe-passed';
+    state: GlassCapabilityState;
+}>;
+export declare function resolveGlassCapability({ forcedBaseline, reducedTransparency, renderTest, }: Readonly<{
+    forcedBaseline: boolean;
+    reducedTransparency: boolean;
+    renderTest: GlassRenderTestState;
+}>): GlassCapabilityDecision;
+/**
+ * Paints a deliberately displaced standalone SVG image into a readable canvas
+ * and verifies the resulting pixels. This is a raster-path prerequisite, not a
+ * live-compositor proof: WebKit can pass this Image -> canvas path while an SVG
+ * filter referenced by a live HTML element paints no displacement. JavaScript
+ * has no pixel-read API for the latter; installed-PWA capture and the lens-boost
+ * diagnostic remain the acceptance boundary.
+ */
+export declare function runForegroundSvgRenderTest(): Promise<boolean>;