@happyvertical/smrt-ui 0.57.12 → 0.57.14

package/dist/components/forms/control-dom.d.ts

@@ -1,6 +1,14 @@
-/** DOM adapter helpers shared by addressable control Implementations. */
 export declare function focusControl(node: HTMLElement): void;
 export declare function revealControl(node: HTMLElement): void;
+/** Existing control descriptors keep their void return contract. */
 export declare function highlightControl(node: HTMLElement, durationMs?: number): void;
+export declare function highlightControl(node: HTMLElement, durationMs: number, options: {
+    presentation: 'outline';
+}): void;
+export declare function highlightControl(node: HTMLElement, durationMs: number, options: {
+    presentation: 'spotlight';
+    dismissLabel: string;
+    onDismiss?: () => void;
+}): () => void;
 export declare function emitControlChange(node: HTMLElement): void;
 //# sourceMappingURL=control-dom.d.ts.map

package/dist/components/forms/control-dom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-dom.d.ts","sourceRoot":"","sources":["../../../src/components/forms/control-dom.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAYzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAKpD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAMrD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,SAAO,GAAG,IAAI,CAK3E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAMzD"}
+{"version":3,"file":"control-dom.d.ts","sourceRoot":"","sources":["../../../src/components/forms/control-dom.ts"],"names":[],"mappings":"AAcA,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAKpD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAMrD;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;AAC/E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IAAE,YAAY,EAAE,SAAS,CAAA;CAAE,GACnC,IAAI,CAAC;AACR,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,YAAY,EAAE,WAAW,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB,GACA,MAAM,IAAI,CAAC;AAgCd,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAMzD"}

package/dist/components/forms/control-dom.js

@@ -1,3 +1,4 @@
+import { paintControlSpotlight } from './control-spotlight.js';
 /** DOM adapter helpers shared by addressable control Implementations. */
 const focusableControlSelector = [
     'input:not([type="hidden"]):not(:disabled)',
@@ -21,12 +22,25 @@ export function revealControl(node) {
         behavior: 'smooth',
     });
 }
-export function highlightControl(node, durationMs = 1600) {
-    node.dataset.smrtHighlighted = 'true';
-    globalThis.setTimeout(() => {
-        if (node.isConnected)
-            delete node.dataset.smrtHighlighted;
-    }, durationMs);
+export function highlightControl(node, durationMs = 1600, options) {
+    let disposed = false;
+    const remove = options?.presentation === 'spotlight'
+        ? paintControlSpotlight(node, options)
+        : (() => {
+            node.dataset.smrtHighlighted = 'true';
+            return () => {
+                delete node.dataset.smrtHighlighted;
+            };
+        })();
+    const timer = globalThis.setTimeout(() => cleanup(), durationMs);
+    const cleanup = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        globalThis.clearTimeout(timer);
+        remove();
+    };
+    return cleanup;
 }
 export function emitControlChange(node) {
     queueMicrotask(() => {

package/dist/components/forms/control-spotlight.d.ts

@@ -0,0 +1,6 @@
+/** Passive viewport veil around an actual control; no guide/navigation state. */
+export declare function paintControlSpotlight(node: HTMLElement, options: {
+    dismissLabel: string;
+    onDismiss?: () => void;
+}): () => void;
+//# sourceMappingURL=control-spotlight.d.ts.map

package/dist/components/forms/control-spotlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-spotlight.d.ts","sourceRoot":"","sources":["../../../src/components/forms/control-spotlight.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GACxD,MAAM,IAAI,CA+FZ"}

package/dist/components/forms/control-spotlight.js

@@ -0,0 +1,96 @@
+/** Passive viewport veil around an actual control; no guide/navigation state. */
+export function paintControlSpotlight(node, options) {
+    const doc = node.ownerDocument;
+    const view = doc.defaultView;
+    if (!view || !node.isConnected)
+        return () => { };
+    const root = doc.createElement('div');
+    root.dataset.smrtComponent = 'ControlSpotlight';
+    const tokens = view.getComputedStyle(node);
+    Object.assign(root.style, {
+        position: 'fixed',
+        inset: '0',
+        pointerEvents: 'none',
+        zIndex: tokens.getPropertyValue('--smrt-z-index-overlay').trim() || '1200',
+    });
+    const veil = doc.createElement('div');
+    veil.dataset.smrtSpotlightVeil = '';
+    veil.setAttribute('aria-hidden', 'true');
+    Object.assign(veil.style, {
+        position: 'absolute',
+        inset: '0',
+        pointerEvents: 'none',
+        // Spotlight is a guidance veil, matching the contact spotlight rather
+        // than the theme's lighter modal scrim. Other overlays keep their tokens.
+        background: 'rgba(3, 5, 9, 0.72)',
+    });
+    const button = doc.createElement('button');
+    button.type = 'button';
+    button.textContent = options.dismissLabel;
+    button.setAttribute('aria-label', options.dismissLabel);
+    Object.assign(button.style, {
+        position: 'absolute',
+        insetInlineEnd: '1rem',
+        pointerEvents: 'auto',
+        cursor: 'pointer',
+        padding: '0.5rem 1rem',
+        borderRadius: tokens.getPropertyValue('--smrt-radius-medium').trim() || '0.5rem',
+        background: tokens.getPropertyValue('--smrt-color-surface').trim() || '#fff',
+        color: tokens.getPropertyValue('--smrt-color-on-surface').trim() || '#111',
+        border: tokens.getPropertyValue('--smrt-hairline').trim() ||
+            '1px solid currentColor',
+        font: 'inherit',
+    });
+    root.append(veil, button);
+    let disposed = false;
+    let frame = 0;
+    const cleanup = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        view.cancelAnimationFrame(frame);
+        root.remove();
+        button.removeEventListener('click', dismiss);
+    };
+    const dismiss = () => {
+        cleanup();
+        options.onDismiss?.();
+    };
+    const update = () => {
+        if (disposed)
+            return;
+        // The shell exposes its occupied phone footer track on descendants.
+        // Read it live: a guide can remain active while the viewport crosses to phone.
+        const footerTrack = view
+            .getComputedStyle(node)
+            .getPropertyValue('--smrt-admin-shell-phone-bar-track')
+            .trim();
+        button.style.insetBlockEnd = `calc(1rem + ${footerTrack || 'env(safe-area-inset-bottom, 0px)'})`;
+        const r = node.getBoundingClientRect();
+        if (!node.isConnected ||
+            node.closest('[hidden],[inert],[aria-hidden="true"]') ||
+            (typeof node.checkVisibility === 'function' && !node.checkVisibility()) ||
+            r.width <= 0 ||
+            r.height <= 0 ||
+            r.right <= 0 ||
+            r.bottom <= 0 ||
+            r.left >= view.innerWidth ||
+            r.top >= view.innerHeight) {
+            dismiss();
+            return;
+        }
+        const x1 = Math.max(0, Math.round(r.left - 8));
+        const y1 = Math.max(0, Math.round(r.top - 8));
+        const x2 = Math.min(view.innerWidth, Math.round(r.right + 8));
+        const y2 = Math.min(view.innerHeight, Math.round(r.bottom + 8));
+        veil.style.clipPath = `polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, ${x1}px ${y1}px, ${x1}px ${y2}px, ${x2}px ${y2}px, ${x2}px ${y1}px, ${x1}px ${y1}px)`;
+        // Track movement caused by scrolling, resizing or surrounding layout. No
+        // animation/interpolation is applied, including under reduced motion.
+        frame = view.requestAnimationFrame(update);
+    };
+    button.addEventListener('click', dismiss);
+    update();
+    if (!disposed)
+        doc.body.append(root);
+    return cleanup;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-ui",
-  "version": "0.57.12",
+  "version": "0.57.14",
   "smrtJsdoc": "strict",
   "description": "Domain-agnostic Svelte 5 UI runtime for SMRT: primitives, i18n client, theme system, and module UI registry",
   "type": "module",
@@ -164,7 +164,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@happyvertical/smrt-types": "0.57.12",
+    "@happyvertical/smrt-types": "0.57.14",
     "esm-env": "^1.2.2"
   },
   "peerDependencies": {