@texuli/core 0.7.0 → 0.9.0

package/dist/i18n/i18n.js

@@ -0,0 +1,185 @@
+/**
+ * The message runtime (ADR-016). An `I18n` holds the catalogs of the
+ * locales it has loaded, loads a locale lazily the first time it becomes
+ * active (`registerLocale(locale, () => import('./pt-BR.ts'))`), and
+ * resolves an id against the active locale, then its base language
+ * (`pt-BR` → `pt`), then the English default the component passes. It is
+ * framework-free: components read it from context (`I18N_CONTEXT`) and
+ * re-read their labels when `subscribe` reports a change.
+ */
+import { LOCALE_TAG, parseCatalog } from "./catalog.js";
+import { fillPlaceholders, formatMessage, interpolate, } from "./format.js";
+import { pseudoLocalize } from "./pseudo.js";
+/** The context key components read an `I18n` from (`setContext(I18N_CONTEXT, i18n)`); one per realm. */
+export const I18N_CONTEXT = Symbol.for('texuli.i18n');
+/** The pseudo-locale (`en-XA`): every resolved string is accented and bracketed, so unlocalized text stands out. */
+export const PSEUDO_LOCALE = 'en-XA';
+/** The base language of a tag: `pt-BR` → `pt`; `undefined` for a bare language. */
+function baseLanguage(locale) {
+    const dash = locale.indexOf('-');
+    return dash > 0 ? locale.slice(0, dash) : undefined;
+}
+function normalizeLocale(locale) {
+    return LOCALE_TAG.test(locale) ? locale : 'en';
+}
+/** Create a message runtime. Never throws on bad catalogs; bad messages are dropped with issues. */
+export function createI18n(options = {}) {
+    const catalogs = new Map();
+    const loaders = new Map(Object.entries(options.loaders ?? {}));
+    const loading = new Map();
+    const listeners = new Set();
+    let locale = normalizeLocale(options.locale ?? 'en');
+    let version = 0;
+    let request = 0;
+    const notify = () => {
+        version += 1;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const add = (input, silent) => {
+        const parsed = parseCatalog(input);
+        if (!parsed.catalog)
+            return parsed.issues;
+        const target = catalogs.get(parsed.catalog.locale) ?? Object.create(null);
+        Object.assign(target, parsed.catalog.messages);
+        catalogs.set(parsed.catalog.locale, target);
+        if (!silent)
+            notify();
+        return parsed.issues;
+    };
+    for (const catalog of options.catalogs ?? []) {
+        const issues = add(catalog, true);
+        if (issues.length > 0)
+            options.onIssues?.(catalog.locale ?? '', issues);
+    }
+    const lookup = (id) => {
+        const own = catalogs.get(locale);
+        if (own && Object.hasOwn(own, id))
+            return own[id];
+        const base = baseLanguage(locale);
+        const parent = base ? catalogs.get(base) : undefined;
+        return parent && Object.hasOwn(parent, id) ? parent[id] : undefined;
+    };
+    const load = (tag) => {
+        if (catalogs.has(tag) || tag === PSEUDO_LOCALE)
+            return Promise.resolve(true);
+        const pending = loading.get(tag);
+        if (pending)
+            return pending;
+        const loader = loaders.get(tag);
+        if (!loader)
+            return Promise.resolve(false);
+        const promise = Promise.resolve()
+            .then(loader)
+            .then((module) => {
+            const catalog = module && typeof module === 'object' && 'default' in module ? module.default : module;
+            const issues = add(catalog && typeof catalog === 'object' ? { ...catalog, locale: tag } : catalog, true);
+            if (issues.length > 0)
+                options.onIssues?.(tag, issues);
+            return catalogs.has(tag);
+        })
+            .catch((error) => {
+            options.onIssues?.(tag, [
+                { id: '', message: error instanceof Error ? error.message : 'the locale failed to load' },
+            ]);
+            return false;
+        })
+            .finally(() => loading.delete(tag));
+        loading.set(tag, promise);
+        return promise;
+    };
+    const i18n = {
+        get locale() {
+            return locale;
+        },
+        get version() {
+            return version;
+        },
+        t(id, english, values) {
+            const found = lookup(id);
+            const text = formatMessage(found ?? english, values, locale);
+            return locale === PSEUDO_LOCALE ? pseudoLocalize(text) : text;
+        },
+        has(id) {
+            return lookup(id) !== undefined;
+        },
+        async setLocale(next) {
+            if (!LOCALE_TAG.test(next))
+                return false;
+            const ticket = ++request;
+            const base = baseLanguage(next);
+            const [own, parent] = await Promise.all([load(next), base ? load(base) : false]);
+            // A later call wins. A locale with neither its own nor a base catalog
+            // activates only when it is English (the defaults are English).
+            if (ticket !== request)
+                return false;
+            if (!own && !parent && next !== 'en' && base !== 'en')
+                return false;
+            if (locale !== next) {
+                locale = next;
+                notify();
+            }
+            return true;
+        },
+        registerLocale(tag, loader) {
+            if (!LOCALE_TAG.test(tag) || typeof loader !== 'function')
+                return;
+            loaders.set(tag, loader);
+        },
+        addCatalog(catalog) {
+            return add(catalog, false);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    // A loader registered for the starting locale loads right away.
+    if (!catalogs.has(locale) && loaders.has(locale)) {
+        void load(locale).then((ok) => {
+            if (ok)
+                notify();
+        });
+    }
+    return i18n;
+}
+/**
+ * The resolution order for one label (ADR-016): the instance prop when the
+ * caller set one, then the catalog from context, then the English default.
+ */
+export function resolveLabel(instance, i18n, id, english, values) {
+    if (typeof instance === 'string')
+        return values ? interpolate(instance, values) : instance;
+    if (i18n)
+        return i18n.t(id, english, values);
+    return formatMessage(english, values);
+}
+/** The English-only `Translate`: what components use with no `I18n` in context. */
+export const englishMessages = (_id, english, values) => fillPlaceholders(typeof english === 'string' ? english : english.other, values);
+/** `pageLabel` → `page-label`: the id segment of a label key. */
+function kebab(key) {
+    return key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+}
+/**
+ * Resolve a component's English label object through the catalog: every
+ * string label becomes `messages(`${prefix}.${kebab(key)}`, english)`. A
+ * function label (`remove: (tag) => …`) stays as is unless the catalog has
+ * its id, whose message then receives the arguments as `{0}`, `{1}`…
+ * Callers spread their instance overrides on top (the instance prop wins).
+ */
+export function localizeLabels(messages, prefix, defaults) {
+    const out = {};
+    for (const [key, value] of Object.entries(defaults)) {
+        const id = `${prefix}.${kebab(key)}`;
+        if (typeof value === 'string')
+            out[key] = messages(id, value);
+        else if (typeof value === 'function' && messages.has?.(id)) {
+            out[key] = (...args) => messages(id, '', Object.fromEntries(args.map((arg, index) => [String(index), arg])));
+        }
+        else
+            out[key] = value;
+    }
+    return out;
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @texuli/core/i18n: message catalogs, lazy locales and label resolution
+ * (ADR-016). Framework-free; components read an `I18n` from context.
+ */
+export { CATALOG_LIMITS, type CatalogIssue, type CatalogParse, checkMessage, LOCALE_TAG, MESSAGE_ID, type MessageCatalog, type MessageCheck, parseCatalog, } from './catalog.js';
+export { fillPlaceholders, formatMessage, interpolate, type Message, type MessageValues, type PluralMessage, type SelectMessage, } from './format.js';
+export { createI18n, englishMessages, I18N_CONTEXT, type I18n, type I18nOptions, type LocaleLoader, localizeLabels, type MessageLookup, PSEUDO_LOCALE, resolveLabel, type Translate, } from './i18n.js';
+export { isPseudoLocalized, pseudoLocalize } from './pseudo.js';

package/dist/i18n/index.js

@@ -0,0 +1,8 @@
+/**
+ * @texuli/core/i18n: message catalogs, lazy locales and label resolution
+ * (ADR-016). Framework-free; components read an `I18n` from context.
+ */
+export { CATALOG_LIMITS, checkMessage, LOCALE_TAG, MESSAGE_ID, parseCatalog, } from "./catalog.js";
+export { fillPlaceholders, formatMessage, interpolate, } from "./format.js";
+export { createI18n, englishMessages, I18N_CONTEXT, localizeLabels, PSEUDO_LOCALE, resolveLabel, } from "./i18n.js";
+export { isPseudoLocalized, pseudoLocalize } from "./pseudo.js";

package/dist/i18n/pseudo.d.ts

@@ -0,0 +1,4 @@
+/** The pseudo form of `text`: `⟦Çlóśé⟧`-style, linear in the length of the text. */
+export declare function pseudoLocalize(text: string): string;
+/** Whether `text` is pseudo-localized (starts with `⟦` and ends with `⟧`). */
+export declare function isPseudoLocalized(text: string): boolean;

package/dist/i18n/pseudo.js

@@ -0,0 +1,41 @@
+/**
+ * Pseudo-localization for coverage (ADR-016): accented, bracketed and
+ * slightly longer text, so a label that skipped the catalog (still plain
+ * English) or a layout that clips longer translations stands out. `{name}`
+ * placeholders are kept as is.
+ */
+const ACCENTS = {
+    a: 'á',
+    c: 'ç',
+    e: 'é',
+    i: 'í',
+    n: 'ñ',
+    o: 'ó',
+    u: 'ú',
+    y: 'ý',
+    A: 'Á',
+    C: 'Ç',
+    E: 'É',
+    I: 'Í',
+    N: 'Ñ',
+    O: 'Ó',
+    U: 'Ú',
+    Y: 'Ý',
+};
+/** The pseudo form of `text`: `⟦Çlóśé⟧`-style, linear in the length of the text. */
+export function pseudoLocalize(text) {
+    let out = '';
+    let inPlaceholder = false;
+    for (const char of text) {
+        if (char === '{')
+            inPlaceholder = true;
+        else if (char === '}')
+            inPlaceholder = false;
+        out += inPlaceholder ? char : (ACCENTS[char] ?? char);
+    }
+    return `⟦${out}⟧`;
+}
+/** Whether `text` is pseudo-localized (starts with `⟦` and ends with `⟧`). */
+export function isPseudoLocalized(text) {
+    return text.startsWith('⟦') && text.endsWith('⟧');
+}

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { computeInertTargets, createInertRegistry, getInertRegistry, INERT_REGIS
 export { ariaKeyShortcuts, createShortcutMap, detectPlatform, flipArrowForDirection, formatShortcut, getNavigationIntent, hasCommandModifier, isActivationKey, isComposing, isTextEntryTarget, type KeyboardEventLike, type MatchOptions, matchesShortcut, type NavigationIntent, type NavigationOptions, normalizeKey, type ParsedShortcut, type PlatformSource, parseShortcut, type ResolvedShortcut, resolveShortcut, type ShortcutBinding, type ShortcutMap, type ShortcutPlatform, type ShortcutStyle, } from './keyboard/index.js';
 export { type BindLayerStackDocumentOptions, bindLayerStackDocument, createLayerStack, decideEscape, getLayerStack, isPointerOutsideTopLayer, LAYER_STACK_GLOBAL_KEY, type LayerEntry, type LayerId, type LayerRegistration, type LayerStack, type LayerStackDocumentBinding, type LayerStackGlobal, layerReceivesEscape, layerReceivesOutsideInteraction, type RegisterLayerInput, resetLayerStack, } from './layer-stack/index.js';
 export { createOverlay, OVERLAY_MODE_ATTR, OVERLAY_Z_BASE, type OverlayController, type OverlayDismissEvent, type OverlayDismissReason, type OverlayMode, type OverlayOptions, type OverlayPhase, } from './overlay/index.js';
-export { createPortal, type PortalController, type PortalOptions, type PortalTarget, } from './portal/index.js';
+export { createPortal, createScopedPortal, createScopedPortalRoot, findPortalScope, PORTAL_ROOT_ATTRIBUTE, type PortalController, type PortalOptions, type PortalScope, type PortalTarget, SCOPE_ATTRIBUTE, SCOPE_SELECTOR, type ScopedPortalOptions, type ScopedPortalRoot, } from './portal/index.js';
 export { type ApplyPositionOptions, type AutoUpdateOptions, applyPosition, autoUpdate, canUseCssAnchor, clearPosition, computeDomPosition, cssAnchorDeclarations, type DomPositionOptions, type FloatingPosition, getContainerRect, getScrollAncestors, getViewportRect, intersectRects, layoutBox, measureRect, observeMove, observeResize, type PositionFloatingOptions, type PositionReference, type PositionStrategy, positionFloating, readDirection, snapToDevicePixel, supportsCssAnchorPositioning, type VirtualElement, } from './position-dom/index.js';
 export { type AnyPlacement, type ArrowPosition, arrowPosition, availableSpace, type ComputePositionOptions, type ComputePositionResult, computePosition, flipFallbacks, insetRect, isLogicalPlacement, isPlacement, type LogicalPlacement, listPlacements, mirrorPlacementForRtl, overflowOf, type Placement, type PositionOffset, place, type Rect, rect, rectBottom, rectRight, resolveLogicalPlacement, resolvePlacementForDirection, type SideOverflow, shiftIntoBoundary, sizeToAvailable, totalOverflow, } from './position-math/index.js';
 export { type CreatePresenceOptions, createPresence, hasPendingMotion, PRESENCE_STATE_ATTR, type PresenceController, type PresenceHooks, type PresenceSnapshot, type PresenceState, parseCssTimeList, prefersReducedMotion, REDUCED_MOTION_QUERY, } from './presence/presence.js';

package/dist/index.js

@@ -10,7 +10,7 @@ export { computeInertTargets, createInertRegistry, getInertRegistry, INERT_REGIS
 export { ariaKeyShortcuts, createShortcutMap, detectPlatform, flipArrowForDirection, formatShortcut, getNavigationIntent, hasCommandModifier, isActivationKey, isComposing, isTextEntryTarget, matchesShortcut, normalizeKey, parseShortcut, resolveShortcut, } from "./keyboard/index.js";
 export { bindLayerStackDocument, createLayerStack, decideEscape, getLayerStack, isPointerOutsideTopLayer, LAYER_STACK_GLOBAL_KEY, layerReceivesEscape, layerReceivesOutsideInteraction, resetLayerStack, } from "./layer-stack/index.js";
 export { createOverlay, OVERLAY_MODE_ATTR, OVERLAY_Z_BASE, } from "./overlay/index.js";
-export { createPortal, } from "./portal/index.js";
+export { createPortal, createScopedPortal, createScopedPortalRoot, findPortalScope, PORTAL_ROOT_ATTRIBUTE, SCOPE_ATTRIBUTE, SCOPE_SELECTOR, } from "./portal/index.js";
 export { applyPosition, autoUpdate, canUseCssAnchor, clearPosition, computeDomPosition, cssAnchorDeclarations, getContainerRect, getScrollAncestors, getViewportRect, intersectRects, layoutBox, measureRect, observeMove, observeResize, positionFloating, readDirection, snapToDevicePixel, supportsCssAnchorPositioning, } from "./position-dom/index.js";
 export { arrowPosition, availableSpace, computePosition, flipFallbacks, insetRect, isLogicalPlacement, isPlacement, listPlacements, mirrorPlacementForRtl, overflowOf, place, rect, rectBottom, rectRight, resolveLogicalPlacement, resolvePlacementForDirection, shiftIntoBoundary, sizeToAvailable, totalOverflow, } from "./position-math/index.js";
 export { createPresence, hasPendingMotion, PRESENCE_STATE_ATTR, parseCssTimeList, prefersReducedMotion, REDUCED_MOTION_QUERY, } from "./presence/presence.js";

package/dist/portal/index.d.ts

@@ -1,8 +1,17 @@
-/** A DOM element that can receive a portal, or `null` to use the document body. */
+export { createScopedPortal, createScopedPortalRoot, findPortalScope, PORTAL_ROOT_ATTRIBUTE, type PortalScope, SCOPE_ATTRIBUTE, SCOPE_SELECTOR, type ScopedPortalOptions, type ScopedPortalRoot, } from './scope.js';
+/** A DOM element that can receive a portal, or `null` for the default (the document body). */
 export type PortalTarget = Element | null | undefined;
 /** Initial target for a portal. Omitting it sends the source to `body`. */
 export type PortalOptions = {
     target?: PortalTarget;
+    /**
+     * Where an omitted or `null` target goes instead of `body`, asked on every
+     * placement with the source's original parent (`null` falls back to body).
+     * `createScopedPortal` uses it to follow a token scope.
+     */
+    fallback?: (origin: Element | null) => Element | null;
+    /** Called after every placement and at destroy, with the source's parent. */
+    settled?: (parent: Node | null) => void;
 };
 /** Controls the target of one portaled element and restores its original place. */
 export type PortalController = {

package/dist/portal/index.js

@@ -1,3 +1,4 @@
+export { createScopedPortal, createScopedPortalRoot, findPortalScope, PORTAL_ROOT_ATTRIBUTE, SCOPE_ATTRIBUTE, SCOPE_SELECTOR, } from "./scope.js";
 /**
  * Move an existing element to `target` or its owner document's body. The same
  * element is moved, rather than cloned, so its listeners, framework state and
@@ -35,44 +36,16 @@ export function createPortal(source, options = {}) {
         setTarget(target) {
             if (disposed || !source || !ownerDocument)
                 return false;
-            const destination = target ?? ownerDocument.body;
-            if (!destination) {
-                restoreToOrigin();
-                return true;
-            }
-            if (destination.ownerDocument !== ownerDocument ||
-                destination === source ||
-                source.contains(destination)) {
-                return false;
-            }
-            if (originMarker?.parentNode === destination && originalParent === destination) {
-                restoreToOrigin();
-                return true;
-            }
-            if (source.parentNode === destination)
-                return true;
-            const createdMarker = originMarker === null && originalParent !== null;
-            if (createdMarker && originalParent) {
-                originMarker = ownerDocument.createComment('texuli-portal-origin');
-                originalParent.insertBefore(originMarker, source);
-            }
-            try {
-                destination.append(source);
-            }
-            catch {
-                if (createdMarker && originMarker?.parentNode) {
-                    originMarker.parentNode.removeChild(originMarker);
-                    originMarker = null;
-                }
-                return false;
-            }
-            return true;
+            const moved = place(target);
+            options.settled?.(source.parentNode);
+            return moved;
         },
         destroy() {
             if (disposed)
                 return;
             disposed = true;
             restoreToOrigin();
+            options.settled?.(source?.parentNode ?? null);
         },
         get currentTarget() {
             return getCurrentTarget();
@@ -81,6 +54,45 @@ export function createPortal(source, options = {}) {
             return source !== null && source !== undefined && source.parentNode !== originalParent;
         },
     };
+    function place(target) {
+        if (!source || !ownerDocument)
+            return false;
+        const origin = originMarker?.parentNode ?? originalParent;
+        const destination = target ??
+            options.fallback?.(origin?.nodeType === 1 ? origin : null) ??
+            ownerDocument.body;
+        if (!destination) {
+            restoreToOrigin();
+            return true;
+        }
+        if (destination.ownerDocument !== ownerDocument ||
+            destination === source ||
+            source.contains(destination)) {
+            return false;
+        }
+        if (originMarker?.parentNode === destination && originalParent === destination) {
+            restoreToOrigin();
+            return true;
+        }
+        if (source.parentNode === destination)
+            return true;
+        const createdMarker = originMarker === null && originalParent !== null;
+        if (createdMarker && originalParent) {
+            originMarker = ownerDocument.createComment('texuli-portal-origin');
+            originalParent.insertBefore(originMarker, source);
+        }
+        try {
+            destination.append(source);
+        }
+        catch {
+            if (createdMarker && originMarker?.parentNode) {
+                originMarker.parentNode.removeChild(originMarker);
+                originMarker = null;
+            }
+            return false;
+        }
+        return true;
+    }
     if (source)
         controller.setTarget(options.target);
     return controller;

package/dist/portal/scope.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Token scopes for portals (ADR-023). A theme or design system applied to an
+ * element (`applyTheme(el)`) marks it `[data-tx-scope]` and writes its
+ * `--tx-*` custom properties inline. Content portaled to `body` would leave
+ * that subtree and lose the scope, so a scoped portal mounts it in a scoped
+ * portal root instead: a box-less (`display: contents`) body child that
+ * mirrors the scope's `data-tx-*` attributes and inline custom properties,
+ * kept in sync while it lives.
+ */
+import { type PortalController, type PortalOptions } from './index.js';
+/** The attribute that marks an element as a token scope. */
+export declare const SCOPE_ATTRIBUTE = "data-tx-scope";
+/** The attribute on a scoped portal root. */
+export declare const PORTAL_ROOT_ATTRIBUTE = "data-tx-portal-root";
+/** What counts as a scope: the marker, or a theme attribute (scopes written before the marker). */
+export declare const SCOPE_SELECTOR = "[data-tx-scope], [data-tx-theme]";
+/**
+ * The nearest token scope of `from` (itself included): the closest
+ * `[data-tx-scope]` or `[data-tx-theme]` element. `null` without one, and
+ * when that scope already holds `body` (a page-wide theme on `<html>` reaches
+ * body portals as it is). Inside a scoped portal root, the scope it mirrors.
+ */
+export declare function findPortalScope(from: Element | null | undefined): Element | null;
+/** A body child that carries one scope's tokens to the content portaled into it. */
+export type ScopedPortalRoot = {
+    /** The root element; portal content into it. */
+    readonly element: HTMLElement;
+    /** The scope it mirrors. */
+    readonly scope: Element;
+    /** Copy the scope again (the observer does this on every change). */
+    sync(): void;
+    /** Stop observing and remove the root; idempotent. */
+    destroy(): void;
+};
+/**
+ * Create a scoped portal root for `scope` at the end of its document's body.
+ * Returns `null` when the document has no body (SSR, a detached document).
+ * Without `MutationObserver` it mirrors once; call `sync()` after changes.
+ */
+export declare function createScopedPortalRoot(scope: Element): ScopedPortalRoot | null;
+/**
+ * The token scope a scoped portal follows, resolved on every placement:
+ * `'auto'` (default) finds the nearest scope around the source's original
+ * position; an element names one; a function returns one; `null` opts out
+ * (always `body`).
+ */
+export type PortalScope = Element | null | 'auto' | (() => Element | null);
+export type ScopedPortalOptions = Omit<PortalOptions, 'fallback' | 'settled'> & {
+    scope?: PortalScope;
+};
+/**
+ * `createPortal` that follows a token scope: an omitted or `null` target is
+ * the scoped portal root of the scope (created on demand, removed once the
+ * source leaves it), or `body` without a scope. An explicit target wins. The
+ * scope is resolved on every placement, so a theme applied after creation is
+ * followed by the next `setTarget`.
+ */
+export declare function createScopedPortal(source: Element | null | undefined, options?: ScopedPortalOptions): PortalController;

package/dist/portal/scope.js

@@ -0,0 +1,118 @@
+/**
+ * Token scopes for portals (ADR-023). A theme or design system applied to an
+ * element (`applyTheme(el)`) marks it `[data-tx-scope]` and writes its
+ * `--tx-*` custom properties inline. Content portaled to `body` would leave
+ * that subtree and lose the scope, so a scoped portal mounts it in a scoped
+ * portal root instead: a box-less (`display: contents`) body child that
+ * mirrors the scope's `data-tx-*` attributes and inline custom properties,
+ * kept in sync while it lives.
+ */
+import { createPortal } from "./index.js";
+/** The attribute that marks an element as a token scope. */
+export const SCOPE_ATTRIBUTE = 'data-tx-scope';
+/** The attribute on a scoped portal root. */
+export const PORTAL_ROOT_ATTRIBUTE = 'data-tx-portal-root';
+/** What counts as a scope: the marker, or a theme attribute (scopes written before the marker). */
+export const SCOPE_SELECTOR = '[data-tx-scope], [data-tx-theme]';
+/** Each live root, back to the scope it mirrors (a nested overlay mirrors the scope, not the root). */
+const rootScopes = /* @__PURE__ */ new WeakMap();
+/** `data-tx-*` attributes, except the portal and overlay markers. */
+const mirrored = (name) => name.startsWith('data-tx-') && !/^data-tx-(portal|overlay)/.test(name);
+/**
+ * The nearest token scope of `from` (itself included): the closest
+ * `[data-tx-scope]` or `[data-tx-theme]` element. `null` without one, and
+ * when that scope already holds `body` (a page-wide theme on `<html>` reaches
+ * body portals as it is). Inside a scoped portal root, the scope it mirrors.
+ */
+export function findPortalScope(from) {
+    const scope = from?.closest(SCOPE_SELECTOR) ?? null;
+    if (!scope)
+        return null;
+    const body = scope.ownerDocument.body;
+    return rootScopes.get(scope) ?? (body && scope.contains(body) ? null : scope);
+}
+/**
+ * Create a scoped portal root for `scope` at the end of its document's body.
+ * Returns `null` when the document has no body (SSR, a detached document).
+ * Without `MutationObserver` it mirrors once; call `sync()` after changes.
+ */
+export function createScopedPortalRoot(scope) {
+    const doc = scope.ownerDocument;
+    if (!doc.body)
+        return null;
+    const element = doc.createElement('div');
+    const style = element.style;
+    element.setAttribute(PORTAL_ROOT_ATTRIBUTE, '');
+    style.setProperty('display', 'contents', 'important');
+    let properties = [];
+    const sync = () => {
+        for (const { name } of Array.from(element.attributes)) {
+            if (mirrored(name) && !scope.hasAttribute(name))
+                element.removeAttribute(name);
+        }
+        for (const { name, value } of Array.from(scope.attributes)) {
+            if (mirrored(name))
+                element.setAttribute(name, value);
+        }
+        const inline = scope.style;
+        const next = Array.from(inline ?? []).filter((name) => name.startsWith('--'));
+        for (const name of properties)
+            if (!next.includes(name))
+                style.removeProperty(name);
+        for (const name of next) {
+            style.setProperty(name, inline.getPropertyValue(name), inline.getPropertyPriority(name));
+        }
+        properties = next;
+    };
+    sync();
+    doc.body.append(element);
+    rootScopes.set(element, scope);
+    const Observer = doc.defaultView?.MutationObserver;
+    const observer = Observer ? new Observer(sync) : null;
+    observer?.observe(scope, { attributes: true });
+    return {
+        element,
+        scope,
+        sync,
+        destroy() {
+            observer?.disconnect();
+            rootScopes.delete(element);
+            element.remove();
+        },
+    };
+}
+/**
+ * `createPortal` that follows a token scope: an omitted or `null` target is
+ * the scoped portal root of the scope (created on demand, removed once the
+ * source leaves it), or `body` without a scope. An explicit target wins. The
+ * scope is resolved on every placement, so a theme applied after creation is
+ * followed by the next `setTarget`.
+ */
+export function createScopedPortal(source, options = {}) {
+    const { scope = 'auto' } = options;
+    const roots = [];
+    return createPortal(source, {
+        target: options.target,
+        fallback(origin) {
+            const found = scope === 'auto' ? findPortalScope(origin) : typeof scope === 'function' ? scope() : scope;
+            if (!found)
+                return null;
+            let root = roots.find((entry) => entry.scope === found);
+            if (!root) {
+                root = createScopedPortalRoot(found) ?? undefined;
+                if (root)
+                    roots.push(root);
+            }
+            return root?.element ?? null;
+        },
+        settled(parent) {
+            for (let index = roots.length - 1; index >= 0; index -= 1) {
+                const root = roots[index];
+                if (root.element === parent)
+                    continue;
+                root.destroy();
+                roots.splice(index, 1);
+            }
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texuli/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Texels: framework-free behavior and policy that every Texuli component is built from.",
   "keywords": [
     "svelte",
@@ -26,6 +26,7 @@
     ".": "./dist/index.js",
     "./announcer": "./dist/announcer/index.js",
     "./controllable": "./dist/controllable/controllable-state.js",
+    "./data-source": "./dist/data-source/index.js",
     "./dir-locale": "./dist/dir-locale/dir-locale.js",
     "./dismiss": "./dist/dismiss/index.js",
     "./editor-history": "./dist/editor/history.js",
@@ -34,8 +35,10 @@
     "./editor-model": "./dist/editor/model.js",
     "./editor-transforms": "./dist/editor/edit.js",
     "./env": "./dist/env/index.js",
+    "./expression": "./dist/expression/index.js",
     "./focus-scope": "./dist/focus-scope/index.js",
     "./form-bridge": "./dist/form-bridge/form-bridge.js",
+    "./i18n": "./dist/i18n/index.js",
     "./ids": "./dist/ids/ids.js",
     "./inert": "./dist/inert/index.js",
     "./keyboard": "./dist/keyboard/index.js",