entasis 0.11.0 → 0.12.0

package/dist/i18n/zh.js

@@ -185,8 +185,6 @@ export const zh = {
     playVideo: '播放视频',
     imageLoadError: '图片无法加载',
     dataTableLabel: '数据表',
-    dataTableLoading: '正在加载表格数据',
-    dataTableSaving: '正在保存表格更改',
     dataTableLoadingRows: '正在加载行',
     dataTableErrorTitle: '无法加载数据',
     dataTableErrorDescription: '数据无法加载。',
@@ -493,6 +491,24 @@ export const zh = {
     aiComposerMentions: '提及与引用',
     aiComposerFiles: '文件',
     aiComposerReferences: '引用',
+    // AIComposer chrome and file notices
+    aiComposerQueue: '将消息加入队列',
+    aiComposerSteering: '正在引导',
+    aiComposerQueuedFiles: (count) => `${count} 个文件`,
+    aiComposerSubmitFailed: '无法发送消息。',
+    aiComposerStopFailed: '无法停止回复。',
+    aiComposerUploadFailed: (name) => `无法上传 ${name}。`,
+    aiComposerVoiceFailed: '无法处理语音输入。',
+    aiComposerFileUnsupported: (name, types) => `不支持 ${name}，请使用${types}`,
+    aiComposerFilesUnsupported: (count, types) => `不支持 ${count} 个文件，请使用${types}`,
+    aiComposerFileTooLarge: (name, size) => `${name} 太大，上限为 ${size}`,
+    aiComposerFileDuplicate: (name) => `${name} 已附加`,
+    aiComposerFileLimit: (max) => `最多可附加 ${max} 个文件`,
+    aiComposerFilesRejected: (count) => `${count} 个文件无法附加`,
+    aiComposerFileTypeImages: '图片',
+    aiComposerFileTypeVideos: '视频',
+    aiComposerFileTypeAudio: '音频',
+    aiComposerFileTypeText: '文本文件',
     // AI 模型选择器
     aiModelSelectorPlaceholder: '选择模型',
     aiModelSelectorSearch: '搜索模型...',
@@ -504,6 +520,16 @@ export const zh = {
     aiThreadTranscript: '对话记录',
     aiThreadScrollToLatest: '滚动到最新消息',
     aiChatConnecting: '正在连接聊天',
+    // AI thread rows, follow-ups and message action errors
+    aiThreadGreeting: '今天有什么可以帮你？',
+    aiThreadRetry: '重试',
+    aiThreadSources: '来源',
+    aiThreadFollowUps: '推荐的后续问题',
+    aiThreadQuestionFailed: '无法完成该提问请求。',
+    aiMessageCopyFailed: '无法复制此消息。',
+    aiMessageCopyCallbackFailed: '消息已复制，但复制操作失败。',
+    aiMessageEditFailed: '无法编辑此消息。',
+    aiMessageRetryFailed: '无法重试此消息。',
     // AI 向用户提问
     aiAskTitle: '回答请求',
     aiAskSubmitting: '正在提交...',
@@ -524,6 +550,53 @@ export const zh = {
     aiReasoningThinking: '思考中…',
     aiReasoningFewSeconds: '思考了几秒钟',
     aiReasoningDuration: (seconds) => `思考了 ${seconds} 秒`,
+    // AI 富文本对话块（工具状态、值、耗时、问题、对话目录）
+    aiToolStatusPending: '等待中',
+    aiToolStatusRunning: '运行中',
+    aiToolStatusStreaming: '准备中',
+    aiToolStatusSuccess: '已完成',
+    aiToolStatusError: '失败',
+    aiToolStatusCancelled: '已取消',
+    aiToolStatusAwaitingApproval: '等待批准',
+    aiToolStatusApproved: '已批准',
+    aiToolStatusDenied: '已拒绝',
+    aiToolGroupSummary: (titles, count) => `${titles} · ${count} 次调用`,
+    aiToolMoreTools: (count) => `另外 ${count} 个`,
+    aiToolShowAll: '显示全部',
+    aiToolShowLess: '收起',
+    aiToolValueItems: (count) => `${count} 项`,
+    aiToolValueKeys: (count) => `${count} 个键`,
+    aiToolValueMore: (count) => `还有 ${count} 项`,
+    aiToolValueEmptyArray: '空数组',
+    aiToolValueEmptyObject: '空对象',
+    aiToolValueCircular: '循环引用',
+    aiToolValueMaxDepth: '已达到最大深度',
+    aiToolValueInvalidDate: '无效日期',
+    aiToolValueUnreadable: '无法读取的值',
+    aiElapsedUnderSecond: '不到 1 秒',
+    aiElapsedSeconds: (seconds) => `${seconds} 秒`,
+    aiElapsedMinutes: (minutes, seconds) => `${minutes} 分 ${seconds} 秒`,
+    aiElapsedHours: (hours, minutes) => `${hours} 小时 ${minutes} 分`,
+    aiReasoningUnderSecond: '思考了不到 1 秒',
+    aiReasoningDurationLong: (elapsed) => `思考了 ${elapsed}`,
+    aiAskPlaceholder: '输入你的回答…',
+    aiAskOther: '其他…',
+    aiAskOtherPlaceholder: '描述你的回答',
+    aiAskSkip: '跳过',
+    aiAskRequiredMarker: '必填',
+    aiAskSkipped: '已跳过',
+    aiAskSummaryTitle: '你的回答',
+    aiAskSubmitFailed: '无法提交回答。',
+    aiAskDiscardFailed: '无法放弃这些问题。',
+    aiAskFileType: '部分文件不符合允许的类型。',
+    aiAskFileSize: '部分文件超过了允许的大小。',
+    aiAskFileLimit: '此问题选择的文件过多。',
+    aiAskFileDuplicate: '部分文件已被选择。',
+    aiAskFileRejected: '部分文件无法添加。',
+    aiThreadTocTurn: (turn, total) => `第 ${turn} 轮，共 ${total} 轮`,
+    aiThreadTocMoreFiles: (count) => `还有 ${count} 个`,
+    aiThreadTocScrollTo: (title) => `跳转到 ${title}`,
+    aiThreadTocFiles: (count) => `${count} 个文件`,
     // AI 上下文窗口
     aiContextTitle: '上下文窗口',
     aiContextRemaining: (tokens) => `剩余 ${tokens} 个 token`,
@@ -532,5 +605,30 @@ export const zh = {
     aiContextReasoning: '推理',
     aiContextCachedInput: '缓存输入',
     aiContextUsed: '已使用',
-    aiContextUsage: (used, maximum, remaining) => `上下文使用情况：已使用 ${used} / ${maximum} 个 token。剩余 ${remaining} 个 token。`
+    aiContextUsage: (used, maximum, remaining) => `上下文使用情况：已使用 ${used} / ${maximum} 个 token。剩余 ${remaining} 个 token。`,
+    // 密码输入
+    passwordTooShort: (min) => `密码至少需要 ${min} 个字符`,
+    // 计量器
+    meter: '计量器',
+    meterSegment: (index, count) => `第 ${index} 段，共 ${count} 段`,
+    progressIndeterminate: '进度不确定',
+    // 字段验证
+    fieldRequired: '此字段为必填项',
+    fieldMustBeChecked: '请勾选此框以继续',
+    fieldMustBeOn: '请开启此选项以继续',
+    fieldInvalid: '请输入有效的值',
+    fieldInvalidEmail: '请输入有效的电子邮件地址',
+    fieldInvalidUrl: '请输入有效的网址',
+    fieldTooShort: (min) => `请至少输入 ${min} 个字符`,
+    fieldTooLong: (max) => `最多只能输入 ${max} 个字符`,
+    fieldRangeUnderflow: (min) => `请输入大于或等于 ${min} 的值`,
+    fieldRangeOverflow: (max) => `请输入小于或等于 ${max} 的值`,
+    fieldIncomplete: (length) => `请输入全部 ${length} 个字符`,
+    // Combobox
+    resultsCount: (count) => `有 ${count} 个结果可用`,
+    tags: '标签',
+    // CheckboxesInput
+    selectAll: '全选',
+    // PinInput
+    oneTimeCode: '一次性验证码'
 };

package/dist/tailwind/geometry.js

@@ -39,6 +39,13 @@ export const applyGeometryEngine = ({ addBase, addUtilities }) => {
             md: 'var(--row-height-md)',
             lg: 'var(--row-height-lg)'
         }),
+        // A control height as a floor, for rows that may wrap (a small menu row: a control tall,
+        // growing with a description).
+        ...sizedUtilities('min-h-control', 'min-height', {
+            sm: 'var(--control-height-sm)',
+            md: 'var(--control-height-md)',
+            lg: 'var(--control-height-lg)'
+        }),
         ...sizedUtilities('min-h-row', 'min-height', {
             sm: 'var(--row-height-sm)',
             md: 'var(--row-height-md)',

package/dist/tailwind/global.js

@@ -160,6 +160,37 @@ export const applyGlobalEngine = (api, options) => {
         'border-selected': stateUtility('border-color', 'selected'),
         'ring-selected': stateUtility('--tw-ring-color', 'selected')
     }, stateOptions);
+    // SCROLL LOCK — dialogs and popovers lock the page by putting `data-entasis-scroll-lock` on
+    // `<html>`, never by writing inline styles, so a lock held by another library on the same
+    // element is neither restored over nor released early. The value is empty while the lock
+    // hides a classic scrollbar: `scrollbar-gutter: stable` then keeps its room and
+    // `--entasis-scrollbar-width` carries its width for `position: fixed` bars. `padding` is the
+    // same lock after the lock measured that the gutter did not hold (an unsupported property, or
+    // a viewport with a custom `::-webkit-scrollbar`): the scrollbar's width is padded instead.
+    // `uncompensated` marks a page that reserves the gutter itself or has no classic scrollbar,
+    // which would otherwise gain a gutter it never had.
+    const scrollLock = '[data-entasis-scroll-lock]';
+    const scrollLockGutter = `${scrollLock}:not([data-entasis-scroll-lock='uncompensated']):not([data-entasis-scroll-lock='padding'])`;
+    addBase({
+        // `!important`: base-layer rules lose to a page's unlayered `html { overflow-y: scroll }`
+        // and to an outside library's inline `overflow`, and the lock has to hold against both.
+        [scrollLock]: { overflow: 'hidden !important' },
+        [scrollLockGutter]: { 'scrollbar-gutter': 'stable !important' },
+        [`${scrollLock}[data-entasis-scroll-lock='padding']`]: {
+            'padding-inline-end': 'var(--entasis-scrollbar-width, 0px)'
+        },
+        // The keyboard overlap from the visual viewport (see Theme); `0px` until a Theme measures it.
+        html: { '--keyboard-inset': '0px' }
+    });
+    // DRAG AND DROP — the dragged item's dim and the empty-list drop tint, as plain rules rather
+    // than a `<style>` the list attachment would inject (a strict CSP would block it without a
+    // nonce). The tint sits in `:where()` (zero specificity) so any class on the container wins.
+    addBase({
+        '[data-dnd-dragging]': { opacity: '0.4' },
+        ':where([data-dnd-over="true"]:not(:has([data-dnd-item])))': {
+            'background-color': 'color-mix(in oklab, var(--color-primary, currentColor) 6%, transparent)'
+        }
+    });
     // DYNAMIC WINDOW UTILITIES
     addUtilities({
         '.h-window': {

package/dist/types/index.d.ts

@@ -1 +1,2 @@
 export * from './theme.js';
+export type { OpenChangeDetails, OpenChangeHandler, OpenChangeInteraction, OpenChangeReason } from '../utils/openChange.js';

package/dist/types/types.mcp.d.ts

@@ -1 +1 @@
-export declare const typesDescription = "\n# Shared theme types\n\nImport from `entasis/types`.\n\nColors names semantic palette roles. Sizes selects small, normal, or large component geometry. Density uses a separate compact/normal/comfortable scale for internal whitespace, so a density value can never be passed where a size is expected. The module also exports theme color paths, typography paths, transition easing, style types, and deepMerge for composing nested theme values.\n";
+export declare const typesDescription = "\n# Shared theme types\n\nImport from `entasis/types`.\n\nColors names semantic palette roles. Sizes selects small, normal, or large component geometry. Density uses a separate compact/normal/comfortable scale for internal whitespace, so a density value can never be passed where a size is expected. The module also exports theme color paths, typography paths, transition easing, style types, and deepMerge for composing nested theme values.\n\n## Open-change details\n\nEvery overlay's `onOpenChange(open, details)` receives `OpenChangeDetails` as its second argument, and runs before the state changes:\n\n- `reason` (`OpenChangeReason`): `'trigger-press'`, `'trigger-hover'`, `'trigger-focus'`, `'outside-press'`, `'escape-key'`, `'close-watcher'` (the Android Back gesture), `'close-press'`, `'item-press'`, `'list-navigation'`, `'input-change'` (typing in a combobox input), `'focus-out'`, `'swipe'`, `'trigger-unmount'`, `'find-in-page'` (the browser's find-in-page opened a disclosure that hides its content until found) or `'imperative-action'`.\n- `event`: the DOM event behind the change, when there is one.\n- `trigger`: the trigger element involved, when a trigger caused it.\n- `interaction` (`OpenChangeInteraction`): `'mouse'`, `'touch'`, `'pen'`, `'keyboard'` or `'programmatic'`.\n- `cancel()` keeps the overlay as it was and leaves the event untouched (a cancelled Escape is not `defaultPrevented`); `isCanceled` reports it.\n\n`OpenChangeHandler` is the `(open, details) => void` signature itself. Inside the callback, `open` still holds the previous state.\n\n```ts\nimport type { OpenChangeDetails } from 'entasis/types';\n\n// Keeps an editor open when the user presses outside it with unsaved text.\nexport function keepDraftOpen(draft: () => string) {\n\treturn (open: boolean, details: OpenChangeDetails) => {\n\t\tif (!open && details.reason === 'outside-press' && draft()) details.cancel();\n\t};\n}\n```\n";

package/dist/types/types.mcp.js

@@ -4,4 +4,27 @@ export const typesDescription = `
 Import from \`entasis/types\`.
 
 Colors names semantic palette roles. Sizes selects small, normal, or large component geometry. Density uses a separate compact/normal/comfortable scale for internal whitespace, so a density value can never be passed where a size is expected. The module also exports theme color paths, typography paths, transition easing, style types, and deepMerge for composing nested theme values.
+
+## Open-change details
+
+Every overlay's \`onOpenChange(open, details)\` receives \`OpenChangeDetails\` as its second argument, and runs before the state changes:
+
+- \`reason\` (\`OpenChangeReason\`): \`'trigger-press'\`, \`'trigger-hover'\`, \`'trigger-focus'\`, \`'outside-press'\`, \`'escape-key'\`, \`'close-watcher'\` (the Android Back gesture), \`'close-press'\`, \`'item-press'\`, \`'list-navigation'\`, \`'input-change'\` (typing in a combobox input), \`'focus-out'\`, \`'swipe'\`, \`'trigger-unmount'\`, \`'find-in-page'\` (the browser's find-in-page opened a disclosure that hides its content until found) or \`'imperative-action'\`.
+- \`event\`: the DOM event behind the change, when there is one.
+- \`trigger\`: the trigger element involved, when a trigger caused it.
+- \`interaction\` (\`OpenChangeInteraction\`): \`'mouse'\`, \`'touch'\`, \`'pen'\`, \`'keyboard'\` or \`'programmatic'\`.
+- \`cancel()\` keeps the overlay as it was and leaves the event untouched (a cancelled Escape is not \`defaultPrevented\`); \`isCanceled\` reports it.
+
+\`OpenChangeHandler\` is the \`(open, details) => void\` signature itself. Inside the callback, \`open\` still holds the previous state.
+
+\`\`\`ts
+import type { OpenChangeDetails } from './index.ts';
+
+// Keeps an editor open when the user presses outside it with unsaved text.
+export function keepDraftOpen(draft: () => string) {
+	return (open: boolean, details: OpenChangeDetails) => {
+		if (!open && details.reason === 'outside-press' && draft()) details.cancel();
+	};
+}
+\`\`\`
 `;

package/dist/utils/cspNonce.d.ts

@@ -0,0 +1,16 @@
+type NonceSource = () => string | undefined;
+/** Registers where the nonce comes from; the returned function removes the registration. */
+export declare function registerCspNonce(source: NonceSource): () => void;
+/**
+ * The nonce of the most recently mounted `<Theme>` that has one, or `undefined` without a Theme
+ * or a nonce. Client-only: on the server a module-level value would leak between requests.
+ */
+export declare function getCspNonce(): string | undefined;
+/**
+ * Stamps `nonce` (default: `getCspNonce()`) on a script, style or link element before it is
+ * attached, so a CSP that only allows nonced inline code accepts it. Returns the element.
+ */
+export declare function applyCspNonce<E extends Element>(element: E, nonce?: string | undefined): E;
+/** ` nonce="…"` for markup built as a string, or `''` without a nonce. */
+export declare const nonceAttribute: (nonce: string | undefined) => string;
+export {};

package/dist/utils/cspNonce.js

@@ -0,0 +1,39 @@
+// The Content-Security-Policy nonce of the page, for code that injects a `<script>` or `<style>`
+// outside a component (CDN loaders, runtime stylesheets). `<Theme nonce>` registers its value
+// here while it is mounted, the way `registerActiveTheme` exposes the Theme to plain modules;
+// components that render markup (BeforeHydratation) read it from the Theme directly.
+const sources = [];
+/** Registers where the nonce comes from; the returned function removes the registration. */
+export function registerCspNonce(source) {
+    sources.push(source);
+    return () => {
+        const index = sources.lastIndexOf(source);
+        if (index >= 0)
+            sources.splice(index, 1);
+    };
+}
+/**
+ * The nonce of the most recently mounted `<Theme>` that has one, or `undefined` without a Theme
+ * or a nonce. Client-only: on the server a module-level value would leak between requests.
+ */
+export function getCspNonce() {
+    for (let index = sources.length - 1; index >= 0; index -= 1) {
+        const nonce = sources[index]();
+        if (nonce)
+            return nonce;
+    }
+    return undefined;
+}
+/**
+ * Stamps `nonce` (default: `getCspNonce()`) on a script, style or link element before it is
+ * attached, so a CSP that only allows nonced inline code accepts it. Returns the element.
+ */
+export function applyCspNonce(element, nonce = getCspNonce()) {
+    if (nonce)
+        element.setAttribute('nonce', nonce);
+    return element;
+}
+/** Escapes a value for a double-quoted HTML attribute. */
+const escapeAttribute = (value) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** ` nonce="…"` for markup built as a string, or `''` without a nonce. */
+export const nonceAttribute = (nonce) => nonce ? ` nonce="${escapeAttribute(nonce)}"` : '';

package/dist/utils/cva/merge.d.ts

@@ -7,7 +7,7 @@
  * "last class wins" rule holds for them too:
  *   - `raised-*`      elevation (bordered) and `lift-*` (shadow only)
  *   - `h-control-*`   control heights
- *   - `h-row-*` / `min-h-row-*` row densities
+ *   - `h-row-*` / `min-h-row-*` row densities, `min-h-control-*` control-height floors
  *   - `size-icon-*`   icon sizes
  *   - `min-size-hit-*` minimum hit areas
  *   - `ps-indent-*`  nesting indents
@@ -53,6 +53,9 @@ export declare const mergeConfig: {
             'min-h-row': {
                 'min-h-row': string[];
             }[];
+            'min-h-control': {
+                'min-h-control': string[];
+            }[];
             'size-icon': {
                 'size-icon': string[];
             }[];
@@ -135,6 +138,7 @@ export declare const mergeConfig: {
             size: string[];
             'min-size-hit': string[];
             'min-h-row': string[];
+            'min-h-control': string[];
             'min-w': string[];
             'min-h': string[];
             'ps-indent': string[];

package/dist/utils/cva/merge.js

@@ -7,7 +7,7 @@
  * "last class wins" rule holds for them too:
  *   - `raised-*`      elevation (bordered) and `lift-*` (shadow only)
  *   - `h-control-*`   control heights
- *   - `h-row-*` / `min-h-row-*` row densities
+ *   - `h-row-*` / `min-h-row-*` row densities, `min-h-control-*` control-height floors
  *   - `size-icon-*`   icon sizes
  *   - `min-size-hit-*` minimum hit areas
  *   - `ps-indent-*`  nesting indents
@@ -64,6 +64,7 @@ export const mergeConfig = {
             'h-control': [{ 'h-control': ['sm', 'md', 'lg'] }],
             'h-row': [{ 'h-row': ['sm', 'md', 'lg'] }],
             'min-h-row': [{ 'min-h-row': ['sm', 'md', 'lg'] }],
+            'min-h-control': [{ 'min-h-control': ['sm', 'md', 'lg'] }],
             'size-icon': [{ 'size-icon': ['xs', 'sm', 'md', 'lg', 'xl'] }],
             'min-size-hit': [{ 'min-size-hit': ['sm', 'md', 'lg'] }],
             'ps-indent': [{ 'ps-indent': ['sm', 'md', 'lg', 'xl'] }],
@@ -105,10 +106,11 @@ export const mergeConfig = {
             w: ['size-icon'],
             size: ['h-control', 'h-row', 'size-icon'],
             // `min-size-hit-*` sets `min-width` + `min-height`, `min-h-row-*` only the height.
-            'min-size-hit': ['min-w', 'min-h', 'min-h-row'],
-            'min-h-row': ['min-h', 'min-size-hit'],
+            'min-size-hit': ['min-w', 'min-h', 'min-h-row', 'min-h-control'],
+            'min-h-row': ['min-h', 'min-size-hit', 'min-h-control'],
+            'min-h-control': ['min-h', 'min-size-hit', 'min-h-row'],
             'min-w': ['min-size-hit'],
-            'min-h': ['min-size-hit', 'min-h-row'],
+            'min-h': ['min-size-hit', 'min-h-row', 'min-h-control'],
             // `ps-indent-*` sets `padding-inline-start`.
             'ps-indent': ['ps', 'px', 'p'],
             ps: ['ps-indent'],

package/dist/utils/focus.d.ts

@@ -1,5 +1,30 @@
 export declare const focusableSelector: string;
+/**
+ * Whether the element can take focus right now: a focusable kind of element that is enabled,
+ * rendered and not inside an `inert`, `hidden` or `aria-hidden` subtree. Unlike `isTabbable` it
+ * accepts `tabindex="-1"`, the kind of target focus restoration may land on.
+ */
+export declare function isFocusable(element: HTMLElement): boolean;
 export declare function isTabbable(element: HTMLElement): boolean;
+/**
+ * The element that really has focus: `root.activeElement` stops at a shadow host, so this looks
+ * inside open shadow roots until it reaches the focused element. Like `activeElement`, it is
+ * `<body>` when nothing is focused. It is an `Element`, not only an `HTMLElement`: an SVG element
+ * with a `tabindex` takes focus too, and must not read as "nothing is focused".
+ */
+export declare function getDeepActiveElement(root?: Document | ShadowRoot): Element | null;
+/**
+ * `container.contains(node)` across shadow boundaries: an element inside a shadow root belongs to
+ * the container when its host does.
+ */
+export declare function composedContains(container: Node, node: Node | null): boolean;
+/**
+ * Whether the page runs in WebKit (Safari, and every browser on iOS) rather than Chromium or
+ * Gecko. Safari is the only engine whose `navigator.vendor` is Apple's.
+ */
+export declare function isWebKit(): boolean;
+/** Whether typing goes into the element: a text input, a textarea or an editable region. */
+export declare function isTextField(element: Element | null): element is HTMLElement;
 /** Tabbable descendants in tab order (positive tabindex first, one radio per group). */
 export declare function getTabbableElements(node: HTMLElement): HTMLElement[];
 export declare const getFirstTabbable: (node: HTMLElement) => HTMLElement;
@@ -8,3 +33,12 @@ export declare const getFirstTabbable: (node: HTMLElement) => HTMLElement;
  * `[data-autofocus]` target, else the first tabbable, else the container itself.
  */
 export declare function resolveInitialFocus(node: HTMLElement): HTMLElement;
+/**
+ * The first tabbable element that follows `reference` in document order, skipping its own
+ * descendants and everything inside `exclude`. `boundary` limits the search to one subtree (a
+ * parent popover's panel). `null` when nothing follows.
+ */
+export declare function getTabbableAfter(reference: HTMLElement, { exclude, boundary }?: {
+    exclude?: HTMLElement | null;
+    boundary?: HTMLElement | null;
+}): HTMLElement | null;

package/dist/utils/focus.js

@@ -16,6 +16,23 @@ export const focusableSelector = [
     '[contenteditable]:not([contenteditable="false"])',
     '[tabindex]'
 ].join(',');
+/**
+ * Whether the element can take focus right now: a focusable kind of element that is enabled,
+ * rendered and not inside an `inert`, `hidden` or `aria-hidden` subtree. Unlike `isTabbable` it
+ * accepts `tabindex="-1"`, the kind of target focus restoration may land on.
+ */
+export function isFocusable(element) {
+    if (!element.isConnected || !element.matches(focusableSelector))
+        return false;
+    if (element.matches(':disabled'))
+        return false;
+    if (element.closest('[inert], [hidden], [aria-hidden="true"]'))
+        return false;
+    if (element.getClientRects().length === 0)
+        return false;
+    const style = getComputedStyle(element);
+    return style.visibility !== 'hidden' && style.visibility !== 'collapse';
+}
 export function isTabbable(element) {
     if (element.tabIndex < 0 || element.matches(':disabled'))
         return false;
@@ -26,6 +43,59 @@ export function isTabbable(element) {
     const style = getComputedStyle(element);
     return style.visibility !== 'hidden' && style.visibility !== 'collapse';
 }
+/**
+ * The element that really has focus: `root.activeElement` stops at a shadow host, so this looks
+ * inside open shadow roots until it reaches the focused element. Like `activeElement`, it is
+ * `<body>` when nothing is focused. It is an `Element`, not only an `HTMLElement`: an SVG element
+ * with a `tabindex` takes focus too, and must not read as "nothing is focused".
+ */
+export function getDeepActiveElement(root = document) {
+    let active = root.activeElement;
+    while (active?.shadowRoot?.activeElement)
+        active = active.shadowRoot.activeElement;
+    return active;
+}
+/**
+ * `container.contains(node)` across shadow boundaries: an element inside a shadow root belongs to
+ * the container when its host does.
+ */
+export function composedContains(container, node) {
+    let current = node;
+    while (current) {
+        if (current === container)
+            return true;
+        current = current.parentNode ?? current.host ?? null;
+    }
+    return false;
+}
+/**
+ * Whether the page runs in WebKit (Safari, and every browser on iOS) rather than Chromium or
+ * Gecko. Safari is the only engine whose `navigator.vendor` is Apple's.
+ */
+export function isWebKit() {
+    return typeof navigator !== 'undefined' && /Apple/i.test(navigator.vendor ?? '');
+}
+const TEXT_INPUT_TYPES = new Set([
+    'text',
+    'search',
+    'email',
+    'url',
+    'tel',
+    'password',
+    'number',
+    ''
+]);
+/** Whether typing goes into the element: a text input, a textarea or an editable region. */
+export function isTextField(element) {
+    if (!(element instanceof HTMLElement))
+        return false;
+    if (element instanceof HTMLTextAreaElement)
+        return true;
+    if (element instanceof HTMLInputElement)
+        return TEXT_INPUT_TYPES.has(element.type);
+    return (element.isContentEditable === true ||
+        element.matches('[contenteditable]:not([contenteditable="false"])'));
+}
 /** Tabbable descendants in tab order (positive tabindex first, one radio per group). */
 export function getTabbableElements(node) {
     const visible = Array.from(node.querySelectorAll(focusableSelector)).filter(isTabbable);
@@ -63,3 +133,26 @@ export function resolveInitialFocus(node) {
     const tabbable = getTabbableElements(node);
     return (tabbable.find((element) => !element.closest('[data-autofocus-skip]')) ?? tabbable[0] ?? node);
 }
+/**
+ * The first tabbable element that follows `reference` in document order, skipping its own
+ * descendants and everything inside `exclude`. `boundary` limits the search to one subtree (a
+ * parent popover's panel). `null` when nothing follows.
+ */
+export function getTabbableAfter(reference, { exclude, boundary = reference.ownerDocument.body } = {}) {
+    if (!boundary)
+        return null;
+    let next = null;
+    for (const element of getTabbableElements(boundary)) {
+        if (exclude && composedContains(exclude, element))
+            continue;
+        const position = reference.compareDocumentPosition(element);
+        if (position & Node.DOCUMENT_POSITION_CONTAINED_BY)
+            continue;
+        if (!(position & Node.DOCUMENT_POSITION_FOLLOWING))
+            continue;
+        // The tabbable list puts positive tabindex first; the nearest one in the page wins here.
+        if (!next || next.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_PRECEDING)
+            next = element;
+    }
+    return next;
+}

package/dist/utils/focusHistory.d.ts

@@ -0,0 +1,21 @@
+/** How many elements are remembered per document. */
+export declare const FOCUS_HISTORY_SIZE = 20;
+/** Remembers an element as the newest entry of a document's history. */
+export declare function recordFocus(element: HTMLElement, doc?: Document): void;
+/**
+ * Starts remembering focus in `doc`. Calls nest: the listener stays until every caller has run
+ * the function this returns. Safe to call on the server, where it does nothing.
+ */
+export declare function installFocusHistory(doc?: Document | undefined): () => void;
+/** The remembered elements of `doc` that are still connected, newest first. */
+export declare function getFocusHistory(doc?: Document): HTMLElement[];
+/**
+ * The most recently focused element that can take focus again: connected, enabled, rendered and
+ * not inside `exclude` (the overlay that is closing) or an `inert` subtree. `null` when none is.
+ */
+export declare function findFocusFallback(doc: Document, { exclude, accept }?: {
+    exclude?: Node | null;
+    accept?: (element: HTMLElement) => boolean;
+}): HTMLElement | null;
+/** Forgets everything remembered for `doc`. For tests. */
+export declare function clearFocusHistory(doc?: Document): void;

package/dist/utils/focusHistory.js

@@ -0,0 +1,99 @@
+// A short memory of where focus has been, so an overlay whose opener is gone (a menu item that
+// opened a dialog and left with the menu) can hand focus to the most recent element that is still
+// on the page instead of dropping it on <body>. `<Theme>` installs the listener for its document;
+// a focus scope installs it for its own document too, so an overlay in an iframe is covered.
+import { composedContains, isFocusable } from './focus.js';
+/** How many elements are remembered per document. */
+export const FOCUS_HISTORY_SIZE = 20;
+const histories = new WeakMap();
+/** Remembers an element as the newest entry of a document's history. */
+export function recordFocus(element, doc = element.ownerDocument) {
+    const history = histories.get(doc);
+    if (!history || element === doc.body || element === doc.documentElement)
+        return;
+    const { entries } = history;
+    const newest = entries.at(-1)?.deref();
+    if (newest === element)
+        return;
+    // Drop an earlier entry for the same element and every entry that has been collected.
+    const kept = entries.filter((entry) => {
+        const value = entry.deref();
+        return value !== undefined && value !== element;
+    });
+    kept.push(new WeakRef(element));
+    history.entries = kept.slice(-FOCUS_HISTORY_SIZE);
+}
+/**
+ * Starts remembering focus in `doc`. Calls nest: the listener stays until every caller has run
+ * the function this returns. Safe to call on the server, where it does nothing.
+ */
+export function installFocusHistory(doc = typeof document === 'undefined' ? undefined : document) {
+    if (!doc)
+        return () => { };
+    let history = histories.get(doc);
+    if (!history) {
+        const onFocusIn = (event) => {
+            // Retargeted at the document when the focus is inside a shadow root: use the real target.
+            const target = event.composedPath()[0] ?? event.target;
+            if (target instanceof HTMLElement)
+                recordFocus(target, doc);
+        };
+        doc.addEventListener('focusin', onFocusIn, true);
+        history = {
+            entries: [],
+            installs: 0,
+            stop: () => doc.removeEventListener('focusin', onFocusIn, true)
+        };
+        histories.set(doc, history);
+        // Whatever has focus now is the first thing worth remembering.
+        const active = doc.activeElement;
+        if (active instanceof HTMLElement)
+            recordFocus(active, doc);
+    }
+    history.installs += 1;
+    const owned = history;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        owned.installs -= 1;
+        if (owned.installs > 0)
+            return;
+        owned.stop();
+        histories.delete(doc);
+    };
+}
+/** The remembered elements of `doc` that are still connected, newest first. */
+export function getFocusHistory(doc = document) {
+    const entries = histories.get(doc)?.entries ?? [];
+    const live = [];
+    for (const entry of entries) {
+        const element = entry.deref();
+        if (element?.isConnected)
+            live.push(element);
+    }
+    return live.reverse();
+}
+/**
+ * The most recently focused element that can take focus again: connected, enabled, rendered and
+ * not inside `exclude` (the overlay that is closing) or an `inert` subtree. `null` when none is.
+ */
+export function findFocusFallback(doc, { exclude, accept } = {}) {
+    for (const element of getFocusHistory(doc)) {
+        if (exclude && composedContains(exclude, element))
+            continue;
+        if (element.closest('[inert]') || !isFocusable(element))
+            continue;
+        if (accept && !accept(element))
+            continue;
+        return element;
+    }
+    return null;
+}
+/** Forgets everything remembered for `doc`. For tests. */
+export function clearFocusHistory(doc = document) {
+    const history = histories.get(doc);
+    if (history)
+        history.entries = [];
+}

package/dist/utils/handlers.d.ts

@@ -0,0 +1,7 @@
+type Handler<E extends Event> = (event: E) => unknown;
+/**
+ * Runs `consumer` first, then `builtIn` unless the consumer called `event.preventDefault()`.
+ * Either side may be missing; the returned handler is always callable.
+ */
+export declare function composeHandlers<E extends Event>(consumer: Handler<E> | null | undefined, builtIn: Handler<E> | null | undefined): (event: E) => void;
+export {};

package/dist/utils/handlers.js

@@ -0,0 +1,14 @@
+// Handler composition for components that wrap a consumer's handler around built-in behaviour.
+// The rule (AGENTS.md proposed law 3): the consumer's handler runs first, on the same native
+// event, and calling `event.preventDefault()` there cancels the built-in behaviour.
+/**
+ * Runs `consumer` first, then `builtIn` unless the consumer called `event.preventDefault()`.
+ * Either side may be missing; the returned handler is always callable.
+ */
+export function composeHandlers(consumer, builtIn) {
+    return (event) => {
+        consumer?.(event);
+        if (!event.defaultPrevented)
+            builtIn?.(event);
+    };
+}