@gemx-dev/clarity-visualize 0.8.47 → 0.8.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemx-dev/clarity-visualize",
-  "version": "0.8.47",
+  "version": "0.8.48",
   "description": "Clarity visualize",
   "author": "Microsoft Corp.",
   "license": "MIT",
@@ -9,7 +9,7 @@
   "unpkg": "build/clarity.visualize.min.js",
   "types": "types/index.d.ts",
   "dependencies": {
-    "@gemx-dev/clarity-decode": "^0.8.47"
+    "@gemx-dev/clarity-decode": "^0.8.48"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^24.0.0",

package/src/custom/README.md

@@ -0,0 +1,60 @@
+# Custom Clarity Visualize Modules
+
+This directory contains custom rendering modules that extend the base Clarity visualization for GemX.
+
+## Structure
+
+All custom modules follow the functional module pattern:
+- Pure functions for testability
+- No side effects in utility functions
+- Clear separation of concerns
+- Type-safe interfaces
+
+## Modules
+
+### Dialog Module (`dialog.ts`)
+
+Renders HTML `<dialog>` elements with proper top-layer and backdrop support.
+
+**Functions:**
+
+- `getDialogRenderOptions(attributes, dialogElement)` - Extracts rendering options from attributes
+- `showDialog(dialogElement, isModal, onError)` - Shows dialog with proper modal/non-modal handling
+- `closeDialog(dialogElement)` - Safely closes a dialog
+- `renderDialog(dialogElement, options, onError)` - Main entry point for dialog rendering
+- `cleanDialogAttributes(attributes)` - Removes internal tracking attributes
+
+**Usage:**
+
+```typescript
+import * as dialogCustom from "./custom/dialog";
+
+const renderOptions = dialogCustom.getDialogRenderOptions(node.attributes, dialogElement);
+node.attributes = dialogCustom.cleanDialogAttributes(node.attributes);
+
+dialogCustom.renderDialog(
+    dialogElement,
+    renderOptions,
+    this.state.options.logerror
+);
+```
+
+**Features:**
+
+- Automatic detection of modal vs non-modal dialogs
+- Proper top-layer rendering via `showModal()`
+- Backdrop support for modal dialogs
+- Handles dialogs already open from HTML attributes
+- Error handling and logging
+
+## Adding New Custom Modules
+
+1. Create a new file in this directory (e.g., `my-feature.ts`)
+2. Follow the functional module pattern
+3. Export functions with clear type signatures
+4. Add exports to `index.ts`
+5. Document the module in this README
+
+## Testing
+
+Custom modules should be unit tested separately from the main Clarity codebase.

package/src/custom/dialog.ts

@@ -0,0 +1,129 @@
+/**
+ * Custom module for rendering HTML Dialog elements
+ * Handles proper visualization of modal dialogs in the top-layer
+ */
+
+export interface DialogRenderOptions {
+    isModal: boolean;
+    shouldBeOpen: boolean;
+    isExistingDialog: boolean;
+}
+
+/**
+ * Extracts dialog rendering options from node attributes
+ *
+ * @param attributes - Node attributes containing dialog state
+ * @param dialogElement - The dialog element being rendered
+ * @returns Dialog render options
+ */
+export function getDialogRenderOptions(
+    attributes: { [key: string]: string },
+    dialogElement: HTMLDialogElement | null
+): DialogRenderOptions {
+    return {
+        isModal: attributes["data-clarity-modal"] === "true",
+        shouldBeOpen: attributes["open"] !== undefined,
+        isExistingDialog: !!dialogElement
+    };
+}
+
+/**
+ * Shows a dialog element with proper modal/non-modal handling
+ * Modal dialogs are shown via showModal() to render in top-layer with backdrop
+ * Non-modal dialogs are shown via show() method
+ *
+ * @param dialogElement - The dialog element to show
+ * @param isModal - Whether this is a modal dialog
+ * @param onError - Optional error callback
+ */
+export function showDialog(
+    dialogElement: HTMLDialogElement,
+    isModal: boolean,
+    onError?: (error: Error) => void
+): void {
+    try {
+        if (!dialogElement.isConnected) {
+            console.warn('⚠️ Dialog not connected to DOM, skipping show');
+            return;
+        }
+
+        // IMPORTANT: If dialog is already open (from HTML attribute),
+        // we need to close and reopen to ensure showModal() is called
+        // and dialog enters top-layer properly
+        if (dialogElement.open) {
+            dialogElement.close();
+        }
+
+        if (isModal) {
+            dialogElement.showModal();
+        } else {
+            dialogElement.show();
+        }
+    } catch (e) {
+        console.error('❌ Error showing dialog:', e);
+        if (onError) {
+            onError(e as Error);
+        }
+    }
+}
+
+/**
+ * Closes a dialog element safely
+ *
+ * @param dialogElement - The dialog element to close
+ */
+export function closeDialog(dialogElement: HTMLDialogElement): void {
+    try {
+        if (dialogElement.open) {
+            dialogElement.close();
+        }
+    } catch (e) {
+        console.warn('⚠️ Error closing dialog:', e);
+    }
+}
+
+/**
+ * Handles dialog rendering based on its state
+ * This is the main entry point for dialog rendering logic
+ *
+ * @param dialogElement - The dialog element to render
+ * @param options - Dialog render options
+ * @param onError - Optional error callback
+ */
+export function renderDialog(
+    dialogElement: HTMLDialogElement,
+    options: DialogRenderOptions,
+    onError?: (error: Error) => void
+): void {
+    const { isModal, shouldBeOpen, isExistingDialog } = options;
+
+    if (shouldBeOpen) {
+        const doShow = () => showDialog(dialogElement, isModal, onError);
+
+        if (isExistingDialog) {
+            // Dialog already exists, call immediately
+            doShow();
+        } else {
+            // New dialog, wait for DOM insertion
+            setTimeout(doShow, 0);
+        }
+    } else if (dialogElement.open) {
+        // Dialog should be closed
+        closeDialog(dialogElement);
+    }
+}
+
+/**
+ * Removes custom tracking attributes before rendering
+ * These attributes are only for internal use
+ *
+ * @param attributes - Attributes object to clean
+ * @returns Cleaned attributes
+ */
+export function cleanDialogAttributes(
+    attributes: { [key: string]: string }
+): { [key: string]: string } {
+    const cleaned = { ...attributes };
+    delete cleaned["data-clarity-modal"];
+    return cleaned;
+}

package/src/custom/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Custom modules for GemX Clarity Visualize extensions
+ * Contains custom rendering logic that extends the base Clarity visualization
+ */
+
+export * from "./dialog";

package/src/layout.ts

@@ -5,6 +5,7 @@ import { StyleSheetOperation } from "@gemx-dev/clarity-js/types/layout";
 import { AnimationOperation } from "@gemx-dev/clarity-js/types/layout";
 import { Constant as LayoutConstants } from "@gemx-dev/clarity-js/types/layout";
 import sharedStyle from "./styles/shared.css";
+import * as dialogCustom from "./custom/dialog";
 
 /* BEGIN blobUnavailableSvgs */
 import blobUnavailableSvgEnglish from "./styles/blobUnavailable/english.svg";
@@ -459,6 +460,31 @@ export class LayoutHelper {
                         this.insertDefaultElement(node, parent, pivot, doc, insert);
                         break;
                     }
+                case "DIALOG":
+                    {
+                        // Use custom module for dialog rendering
+                        let dialogElement = this.element(node.id) as HTMLDialogElement;
+                        dialogElement = dialogElement ? dialogElement : this.createElement(doc, node.tag) as HTMLDialogElement;
+                        if (!node.attributes) { node.attributes = {}; }
+
+                        // Extract render options before cleaning attributes
+                        const renderOptions = dialogCustom.getDialogRenderOptions(node.attributes, dialogElement);
+
+                        // Clean custom tracking attributes
+                        node.attributes = dialogCustom.cleanDialogAttributes(node.attributes);
+
+                        // Set attributes and insert into DOM
+                        this.setAttributes(dialogElement, node);
+                        insert(node, parent, dialogElement, pivot);
+
+                        // Render dialog with proper modal/non-modal handling
+                        dialogCustom.renderDialog(
+                            dialogElement,
+                            renderOptions,
+                            this.state.options.logerror
+                        );
+                        break;
+                    }
                 default:
                     this.insertDefaultElement(node, parent, pivot, doc, insert);
                     break;

package/src/styles/shared.css

@@ -3,4 +3,22 @@ iframe[data-clarity-unavailable-small], iframe[data-clarity-unavailable], img[da
     border-style: dashed;
     border-width: 6px;
     border-color: #827DFF;
+}
+
+/* Dialog top-layer styles */
+/* Ensure modal dialogs appear in the top-layer with proper z-index */
+dialog[open] {
+    /* Modal dialogs shown via showModal() are automatically placed in top-layer by the browser */
+    /* This ensures proper stacking even during replay */
+    z-index: auto;
+}
+
+/* Style the backdrop for modal dialogs */
+dialog::backdrop {
+    background: rgba(0, 0, 0, 0.5);
+}
+
+/* Ensure non-modal dialogs (shown via show()) are positioned correctly */
+dialog:not([open]) {
+    display: none;
 }