@syntrologie/adapt-overlays 0.0.0-semantically-released

package/dist/runtime.js

@@ -0,0 +1,267 @@
+/**
+ * Adaptive Overlays - Runtime Module
+ *
+ * Visual overlay actions: highlight, pulse, badge, tooltip.
+ */
+import { showHighlight } from './highlight';
+import { showTooltip } from './tooltip';
+import { sanitizeHtml } from './sanitizer';
+import { executeModal } from './modal';
+// Re-export executeModal for use by other packages
+export { executeModal };
+// ============================================================================
+// Executors
+// ============================================================================
+/**
+ * Execute a highlight action
+ */
+export const executeHighlight = async (action, context) => {
+    const anchorEl = context.resolveAnchor(action.anchorId);
+    if (!anchorEl) {
+        throw new Error(`Anchor not found: ${action.anchorId}`);
+    }
+    const handle = showHighlight(anchorEl, context.overlayRoot, {
+        paddingPx: action.style?.paddingPx ?? 12,
+        radiusPx: action.style?.radiusPx ?? 12,
+        scrimOpacity: action.style?.scrimOpacity ?? 0.55,
+        ringColor: action.style?.color,
+        blocking: false,
+        onClickOutside: false,
+        onEsc: false,
+    });
+    context.publishEvent('action.applied', {
+        id: context.generateId(),
+        kind: 'overlays:highlight',
+        anchorId: action.anchorId,
+    });
+    return {
+        cleanup: () => {
+            handle.destroy();
+        },
+    };
+};
+/**
+ * Execute a pulse action
+ */
+export const executePulse = async (action, context) => {
+    const anchorEl = context.resolveAnchor(action.anchorId);
+    if (!anchorEl) {
+        throw new Error(`Anchor not found: ${action.anchorId}`);
+    }
+    const duration = action.duration ?? 2000;
+    const className = 'syntro-pulse-effect';
+    // Inject pulse animation styles if not already present
+    if (!document.querySelector('[data-syntro-pulse-styles]')) {
+        const style = document.createElement('style');
+        style.setAttribute('data-syntro-pulse-styles', '');
+        style.textContent = `
+      @keyframes syntro-pulse {
+        0%, 100% {
+          box-shadow: 0 0 0 0 rgba(79, 70, 229, 0.4);
+        }
+        50% {
+          box-shadow: 0 0 0 8px rgba(79, 70, 229, 0);
+        }
+      }
+      .${className} {
+        animation: syntro-pulse 1s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+      }
+    `;
+        document.head.appendChild(style);
+    }
+    // Add pulse class
+    anchorEl.classList.add(className);
+    // Set up auto-remove timeout
+    const timeoutId = setTimeout(() => {
+        anchorEl.classList.remove(className);
+    }, duration);
+    context.publishEvent('action.applied', {
+        id: context.generateId(),
+        kind: 'overlays:pulse',
+        anchorId: action.anchorId,
+        duration,
+    });
+    return {
+        cleanup: () => {
+            clearTimeout(timeoutId);
+            anchorEl.classList.remove(className);
+        },
+    };
+};
+/**
+ * Execute a badge action
+ */
+export const executeBadge = async (action, context) => {
+    const anchorEl = context.resolveAnchor(action.anchorId);
+    if (!anchorEl) {
+        throw new Error(`Anchor not found: ${action.anchorId}`);
+    }
+    // Create badge element
+    const badge = document.createElement('div');
+    badge.className = 'syntro-badge';
+    badge.textContent = action.content;
+    badge.setAttribute('data-syntro-badge', action.anchorId);
+    // Inject badge styles if not present
+    if (!document.querySelector('[data-syntro-badge-styles]')) {
+        const style = document.createElement('style');
+        style.setAttribute('data-syntro-badge-styles', '');
+        style.textContent = `
+      .syntro-badge {
+        position: absolute;
+        padding: 2px 6px;
+        font-size: 12px;
+        font-weight: 600;
+        line-height: 1;
+        color: white;
+        background: var(--syntro-accent, #4f46e5);
+        border-radius: 9999px;
+        pointer-events: none;
+        z-index: 2147483646;
+        white-space: nowrap;
+      }
+    `;
+        document.head.appendChild(style);
+    }
+    // Position badge relative to anchor
+    const position = action.position ?? 'top-right';
+    // Ensure anchor has relative positioning for badge
+    const originalPosition = anchorEl.style.position;
+    if (getComputedStyle(anchorEl).position === 'static') {
+        anchorEl.style.position = 'relative';
+    }
+    // Append to anchor for relative positioning
+    anchorEl.appendChild(badge);
+    // Position based on config
+    switch (position) {
+        case 'top-left':
+            Object.assign(badge.style, { top: '-8px', left: '-8px' });
+            break;
+        case 'top-right':
+            Object.assign(badge.style, { top: '-8px', right: '-8px' });
+            break;
+        case 'bottom-left':
+            Object.assign(badge.style, { bottom: '-8px', left: '-8px' });
+            break;
+        case 'bottom-right':
+            Object.assign(badge.style, { bottom: '-8px', right: '-8px' });
+            break;
+    }
+    context.publishEvent('action.applied', {
+        id: context.generateId(),
+        kind: 'overlays:badge',
+        anchorId: action.anchorId,
+        content: action.content,
+        position,
+    });
+    return {
+        cleanup: () => {
+            badge.remove();
+            if (originalPosition !== undefined) {
+                anchorEl.style.position = originalPosition;
+            }
+        },
+        updateFn: (changes) => {
+            if ('content' in changes && typeof changes.content === 'string') {
+                badge.textContent = changes.content;
+            }
+        },
+    };
+};
+/**
+ * Execute a tooltip action
+ */
+export const executeTooltip = async (action, context) => {
+    const anchorEl = context.resolveAnchor(action.anchorId);
+    if (!anchorEl) {
+        throw new Error(`Anchor not found: ${action.anchorId}`);
+    }
+    // Build tooltip HTML
+    const content = action.content;
+    let html = '';
+    if (content.title) {
+        html += `<div class="syntro-tt-title">${sanitizeHtml(content.title)}</div>`;
+    }
+    html += `<div class="syntro-tt-body">${sanitizeHtml(content.body)}</div>`;
+    // Add CTA buttons if provided (new multi-button support)
+    if (content.ctaButtons && content.ctaButtons.length > 0) {
+        html += `<div class="syntro-tt-actions">`;
+        for (const btn of content.ctaButtons) {
+            const isPrimary = btn.primary ?? false;
+            html += `
+        <button
+          class="syntro-tt-btn ${isPrimary ? 'syntro-tt-btn-primary' : ''}"
+          data-syntro-action="${sanitizeHtml(btn.actionId)}"
+        >
+          ${sanitizeHtml(btn.label)}
+        </button>
+      `;
+        }
+        html += `</div>`;
+    }
+    else if (content.cta) {
+        // Legacy single CTA support
+        html += `<div class="syntro-tt-actions">
+      <button class="syntro-tt-btn syntro-tt-btn-primary" data-syntro-action="cta">
+        ${sanitizeHtml(content.cta.label)}
+      </button>
+    </div>`;
+    }
+    const handle = showTooltip(anchorEl, context.overlayRoot, {
+        html,
+        placement: action.placement ?? 'top',
+        trigger: action.trigger ?? 'immediate',
+        onAction: (actionId) => {
+            if (actionId === 'cta' && content.cta) {
+                context.publishEvent('action.cta_clicked', {
+                    anchorId: action.anchorId,
+                    ctaLabel: content.cta.label,
+                });
+            }
+            else if (content.ctaButtons) {
+                const clickedBtn = content.ctaButtons.find((b) => b.actionId === actionId);
+                if (clickedBtn) {
+                    context.publishEvent('action.tooltip_cta_clicked', {
+                        anchorId: action.anchorId,
+                        actionId,
+                        label: clickedBtn.label,
+                    });
+                }
+            }
+        },
+    });
+    context.publishEvent('action.applied', {
+        id: context.generateId(),
+        kind: 'overlays:tooltip',
+        anchorId: action.anchorId,
+        trigger: action.trigger ?? 'immediate',
+    });
+    return {
+        cleanup: () => {
+            handle.destroy();
+        },
+    };
+};
+// ============================================================================
+// Executor Definitions for Registration
+// ============================================================================
+/**
+ * All executors provided by this app.
+ * These are registered with the runtime's ExecutorRegistry.
+ */
+export const executors = [
+    { kind: 'overlays:highlight', executor: executeHighlight },
+    { kind: 'overlays:pulse', executor: executePulse },
+    { kind: 'overlays:badge', executor: executeBadge },
+    { kind: 'overlays:tooltip', executor: executeTooltip },
+    { kind: 'overlays:modal', executor: executeModal },
+];
+/**
+ * App runtime manifest.
+ */
+export const runtime = {
+    id: 'adaptive-overlays',
+    version: '1.0.0',
+    name: 'Overlays',
+    description: 'Tooltips, highlights, badges, modals, and visual overlays',
+    executors,
+};

package/dist/sanitizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTML Sanitizer
+ *
+ * Sanitizes HTML to prevent XSS attacks.
+ * Uses native Sanitizer API when available, falls back to whitelist approach.
+ */
+export declare function sanitizeHtml(html: string): string;
+//# sourceMappingURL=sanitizer.d.ts.map

package/dist/sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.d.ts","sourceRoot":"","sources":["../src/sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqDjD"}

package/dist/sanitizer.js

@@ -0,0 +1,75 @@
+/**
+ * HTML Sanitizer
+ *
+ * Sanitizes HTML to prevent XSS attacks.
+ * Uses native Sanitizer API when available, falls back to whitelist approach.
+ */
+const ALLOWED_TAGS = new Set([
+    'b',
+    'strong',
+    'i',
+    'em',
+    'u',
+    'span',
+    'div',
+    'p',
+    'br',
+    'ul',
+    'ol',
+    'li',
+    'code',
+    'pre',
+    'small',
+    'sup',
+    'sub',
+    'a',
+    'button',
+]);
+export function sanitizeHtml(html) {
+    // Try native Sanitizer API first
+    const hasNative = typeof window.Sanitizer === 'function';
+    if (hasNative) {
+        try {
+            const s = new window.Sanitizer({});
+            const frag = s.sanitizeToFragment(html);
+            const div = document.createElement('div');
+            div.append(frag);
+            return div.innerHTML;
+        }
+        catch {
+            // Fall through to manual sanitizer
+        }
+    }
+    // Conservative fallback sanitizer
+    const tpl = document.createElement('template');
+    tpl.innerHTML = html;
+    const root = tpl.content;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, null);
+    const toRemove = [];
+    while (walker.nextNode()) {
+        const el = walker.currentNode;
+        const tag = el.tagName.toLowerCase();
+        if (!ALLOWED_TAGS.has(tag)) {
+            toRemove.push(el);
+            continue;
+        }
+        // Remove dangerous attributes
+        for (const attr of Array.from(el.attributes)) {
+            const name = attr.name.toLowerCase();
+            const value = attr.value.trim().toLowerCase();
+            const isEvent = name.startsWith('on');
+            const isJsUrl = (name === 'href' || name === 'src') && value.startsWith('javascript:');
+            if (isEvent || isJsUrl) {
+                el.removeAttribute(attr.name);
+            }
+        }
+    }
+    // Remove disallowed elements but keep their children
+    for (const el of toRemove) {
+        while (el.firstChild) {
+            el.parentNode?.insertBefore(el.firstChild, el);
+        }
+        el.remove();
+    }
+    return tpl.innerHTML;
+}

package/dist/schema.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Adaptive Overlays - Config Schema
+ *
+ * Zod schema for validating overlays app configuration.
+ */
+import { z } from 'zod';
+/**
+ * Overlays app config schema.
+ * Defines the structure for overlay configurations in a canvas config.
+ */
+export declare const configSchema: z.ZodObject<{
+    /** Highlight configurations */
+    highlights: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        anchorId: z.ZodString;
+        style: z.ZodOptional<z.ZodObject<{
+            color: z.ZodOptional<z.ZodString>;
+            paddingPx: z.ZodOptional<z.ZodNumber>;
+            radiusPx: z.ZodOptional<z.ZodNumber>;
+            scrimOpacity: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            color?: string | undefined;
+            paddingPx?: number | undefined;
+            radiusPx?: number | undefined;
+            scrimOpacity?: number | undefined;
+        }, {
+            color?: string | undefined;
+            paddingPx?: number | undefined;
+            radiusPx?: number | undefined;
+            scrimOpacity?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        anchorId: string;
+        style?: {
+            color?: string | undefined;
+            paddingPx?: number | undefined;
+            radiusPx?: number | undefined;
+            scrimOpacity?: number | undefined;
+        } | undefined;
+    }, {
+        anchorId: string;
+        style?: {
+            color?: string | undefined;
+            paddingPx?: number | undefined;
+            radiusPx?: number | undefined;
+            scrimOpacity?: number | undefined;
+        } | undefined;
+    }>, "many">>;
+    /** Tooltip configurations */
+    tooltips: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        anchorId: z.ZodString;
+        content: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            body: z.ZodString;
+            cta: z.ZodOptional<z.ZodObject<{
+                label: z.ZodString;
+                action: z.ZodUnknown;
+            }, "strip", z.ZodTypeAny, {
+                label: string;
+                action?: unknown;
+            }, {
+                label: string;
+                action?: unknown;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            body: string;
+            title?: string | undefined;
+            cta?: {
+                label: string;
+                action?: unknown;
+            } | undefined;
+        }, {
+            body: string;
+            title?: string | undefined;
+            cta?: {
+                label: string;
+                action?: unknown;
+            } | undefined;
+        }>;
+        trigger: z.ZodOptional<z.ZodEnum<["immediate", "hover", "click"]>>;
+        placement: z.ZodOptional<z.ZodEnum<["top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end", "right", "right-start", "right-end"]>>;
+    }, "strip", z.ZodTypeAny, {
+        anchorId: string;
+        content: {
+            body: string;
+            title?: string | undefined;
+            cta?: {
+                label: string;
+                action?: unknown;
+            } | undefined;
+        };
+        trigger?: "immediate" | "hover" | "click" | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | undefined;
+    }, {
+        anchorId: string;
+        content: {
+            body: string;
+            title?: string | undefined;
+            cta?: {
+                label: string;
+                action?: unknown;
+            } | undefined;
+        };
+        trigger?: "immediate" | "hover" | "click" | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | undefined;
+    }>, "many">>;
+    /** Badge configurations */
+    badges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        anchorId: z.ZodString;
+        content: z.ZodString;
+        position: z.ZodOptional<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right"]>>;
+    }, "strip", z.ZodTypeAny, {
+        anchorId: string;
+        content: string;
+        position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
+    }, {
+        anchorId: string;
+        content: string;
+        position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
+    }>, "many">>;
+    /** Pulse configurations */
+    pulses: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        anchorId: z.ZodString;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        anchorId: string;
+        duration?: number | undefined;
+    }, {
+        anchorId: string;
+        duration?: number | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    highlights?: {
+        anchorId: string;
+        style?: {
+            color?: string | undefined;
+            paddingPx?: number | undefined;
+            radiusPx?: number | undefined;
+            scrimOpacity?: number | undefined;
+        } | undefined;
+    }[] | undefined;
+    tooltips?: {
+        anchorId: string;
+        content: {
+            body: string;
+            title?: string | undefined;
+            cta?: {
+                label: string;
+                action?: unknown;
+            } | undefined;
+        };
+        trigger?: "immediate" | "hover" | "click" | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | undefined;
+    }[] | undefined;
+    badges?: {
+        anchorId: string;
+        content: string;
+        position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
+    }[] | undefined;
+    pulses?: {
+        anchorId: string;
+        duration?: number | undefined;
+    }[] | undefined;
+}, {
+    highlights?: {
+        anchorId: string;
+        style?: {
+            color?: string | undefined;
+            paddingPx?: number | undefined;
+            radiusPx?: number | undefined;
+            scrimOpacity?: number | undefined;
+        } | undefined;
+    }[] | undefined;
+    tooltips?: {
+        anchorId: string;
+        content: {
+            body: string;
+            title?: string | undefined;
+            cta?: {
+                label: string;
+                action?: unknown;
+            } | undefined;
+        };
+        trigger?: "immediate" | "hover" | "click" | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | undefined;
+    }[] | undefined;
+    badges?: {
+        anchorId: string;
+        content: string;
+        position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
+    }[] | undefined;
+    pulses?: {
+        anchorId: string;
+        duration?: number | undefined;
+    }[] | undefined;
+}>;
+export type OverlaysConfig = z.infer<typeof configSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiB/B,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAoC7B,2BAA2B;;;;;;;;;;;;;;IAW3B,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS3B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/schema.js

@@ -0,0 +1,74 @@
+/**
+ * Adaptive Overlays - Config Schema
+ *
+ * Zod schema for validating overlays app configuration.
+ */
+import { z } from 'zod';
+/**
+ * Overlays app config schema.
+ * Defines the structure for overlay configurations in a canvas config.
+ */
+export const configSchema = z.object({
+    /** Highlight configurations */
+    highlights: z
+        .array(z.object({
+        anchorId: z.string(),
+        style: z
+            .object({
+            color: z.string().optional(),
+            paddingPx: z.number().optional(),
+            radiusPx: z.number().optional(),
+            scrimOpacity: z.number().optional(),
+        })
+            .optional(),
+    }))
+        .optional(),
+    /** Tooltip configurations */
+    tooltips: z
+        .array(z.object({
+        anchorId: z.string(),
+        content: z.object({
+            title: z.string().optional(),
+            body: z.string(),
+            cta: z
+                .object({
+                label: z.string(),
+                action: z.unknown(), // ActionStep - validated separately
+            })
+                .optional(),
+        }),
+        trigger: z.enum(['immediate', 'hover', 'click']).optional(),
+        placement: z
+            .enum([
+            'top',
+            'top-start',
+            'top-end',
+            'bottom',
+            'bottom-start',
+            'bottom-end',
+            'left',
+            'left-start',
+            'left-end',
+            'right',
+            'right-start',
+            'right-end',
+        ])
+            .optional(),
+    }))
+        .optional(),
+    /** Badge configurations */
+    badges: z
+        .array(z.object({
+        anchorId: z.string(),
+        content: z.string(),
+        position: z.enum(['top-left', 'top-right', 'bottom-left', 'bottom-right']).optional(),
+    }))
+        .optional(),
+    /** Pulse configurations */
+    pulses: z
+        .array(z.object({
+        anchorId: z.string(),
+        duration: z.number().optional(),
+    }))
+        .optional(),
+});

package/dist/tooltip.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tooltip Overlay
+ *
+ * Creates a positioned tooltip near an element using Floating UI.
+ */
+import { type Placement } from '@floating-ui/dom';
+export type TooltipHandle = {
+    destroy(): void;
+    el: HTMLElement;
+};
+export interface TooltipOptions {
+    html: string;
+    placement?: Placement | 'auto';
+    offsetPx?: number;
+    blocking?: boolean;
+    trigger?: 'immediate' | 'hover' | 'click';
+    onAction?: (actionId: string) => void;
+}
+export declare function showTooltip(anchorEl: HTMLElement, overlayRoot: HTMLElement, opts: TooltipOptions): TooltipHandle;
+//# sourceMappingURL=tooltip.d.ts.map

package/dist/tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../src/tooltip.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EASL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,aAAa,GAAG;IAAE,OAAO,IAAI,IAAI,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAyCD,wBAAgB,WAAW,CACzB,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,cAAc,GACnB,aAAa,CAkNf"}