@texuli/core 0.8.0 → 0.9.0

package/README.md

@@ -12,9 +12,9 @@ when you need Texuli's URL policy to sanitize links and media from agents
 or users. It has no runtime dependencies and imports no UI framework.
 
 > **Status: 0.x release.** Texuli is in development. The packages are
-> published to npm as `0.8.0`, a pre-1.0 release (1.0.0 will be the first
-> stable release). Under 0.x, a new minor (`0.9.0`) may contain breaking
-> changes, so pin the exact version or use `^0.8.0`, which accepts only 0.8.x.
+> published to npm as `0.9.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.10.0`) may contain breaking
+> changes, so pin the exact version or use `^0.9.0`, which accepts only 0.9.x.
 
 ## Install
 

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.8.0",
+  "version": "0.9.0",
   "description": "Texels: framework-free behavior and policy that every Texuli component is built from.",
   "keywords": [
     "svelte",