feat: add <StxModal>, stxAlert(), and stxConfirm() builtins

Three new built-in UI primitives:

1. <StxModal id="name"> — declarative modal with slot content.
   Opened/closed via modal.open(id), modal.close(id), modal.toggle(id).
   Supports size (sm/md/lg/xl/full), closeOnBackdrop, closeOnEscape.
   Animated open/close with backdrop blur and scale transition.
   Locks body scroll while open, restores on close.

2. stxAlert(message, options?) — styled window.alert() replacement.
   Returns Promise<void>. Supports title, type (info/warning/error/
   success), custom button text. Renders as a centered dialog with
   icon, backdrop, and animated entry/exit.

3. stxConfirm(message, options?) — styled window.confirm() replacement.
   Returns Promise<boolean>. Cancel + OK buttons, Escape = cancel.
   Type 'question' shows a ? icon by default. Supports custom
   confirmText/cancelText.

All three:
- Dark mode via prefers-color-scheme
- Keyboard accessible (Escape to close/cancel, autofocus primary button)
- ARIA attributes (role="dialog", aria-modal)
- Zero dependencies, just DOM manipulation
- Available as runtime globals in <script client> blocks

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: glennmichael123

packages/stx/src/builtins/index.ts

@@ -11,13 +11,15 @@ export { StxLinkBuiltin } from './stx-link'
 export { StxImageBuiltin } from './stx-image'
 export { StxLoadingIndicatorBuiltin } from './stx-loading-indicator'
 export { StxToastBuiltin } from './toast'
+export { StxModalBuiltin } from './modal'
 export { IconBuiltin, preloadIconCollection } from './icon'
 
 import { registry } from '../component-registry'
 import { StxLinkBuiltin } from './stx-link'
 import { StxImageBuiltin } from './stx-image'
 import { StxLoadingIndicatorBuiltin } from './stx-loading-indicator'
 import { StxToastBuiltin } from './toast'
+import { StxModalBuiltin } from './modal'
 import { IconBuiltin } from './icon'
 
 /**
@@ -29,5 +31,6 @@ export function registerBuiltins(): void {
   registry.registerBuiltin(StxImageBuiltin)
   registry.registerBuiltin(StxLoadingIndicatorBuiltin)
   registry.registerBuiltin(StxToastBuiltin)
+  registry.registerBuiltin(StxModalBuiltin)
   registry.registerBuiltin(IconBuiltin)
 }

packages/stx/src/builtins/modal.ts

@@ -0,0 +1,70 @@
+/**
+ * StxModal Builtin Component
+ *
+ * Renders a hidden modal dialog with slot content. Opened/closed via
+ * the runtime `modal.open(id)` / `modal.close(id)` globals.
+ *
+ * Usage:
+ *   <StxModal id="settings">
+ *     <h2>Settings</h2>
+ *     <p>Modal content here</p>
+ *   </StxModal>
+ *
+ *   <StxModal id="delete-confirm" size="sm" closeOnBackdrop="false">
+ *     <h3>Are you sure?</h3>
+ *   </StxModal>
+ *
+ * Props:
+ *   - id (required) — unique modal identifier
+ *   - size — 'sm' | 'md' | 'lg' | 'xl' | 'full' (default: 'md')
+ *   - closeOnBackdrop — whether clicking backdrop closes modal (default: true)
+ *   - closeOnEscape — whether Escape key closes modal (default: true)
+ *
+ * @module builtins/modal
+ */
+
+import type { BuiltinComponentDef, ResolvedProps, RenderContext } from '../component-registry'
+
+function resolveProp(props: ResolvedProps, key: string): string | undefined {
+  if (props.serverDynamic[key] !== undefined) return String(props.serverDynamic[key])
+  const val = props.static[key]
+  if (typeof val === 'string') return val
+  return undefined
+}
+
+const SIZE_WIDTHS: Record<string, string> = {
+  sm: 'max-width:24rem',
+  md: 'max-width:32rem',
+  lg: 'max-width:42rem',
+  xl: 'max-width:56rem',
+  full: 'max-width:calc(100vw - 2rem);max-height:calc(100vh - 2rem)',
+}
+
+export const StxModalBuiltin: BuiltinComponentDef = {
+  name: 'StxModal',
+  aliases: ['stx-modal'],
+
+  render(props: ResolvedProps, slotContent: string, _ctx: RenderContext): string {
+    const id = resolveProp(props, 'id')
+    if (!id) {
+      console.warn('[stx] <StxModal> requires an "id" prop')
+      return '<!-- StxModal: missing id prop -->'
+    }
+
+    const size = resolveProp(props, 'size') || 'md'
+    const closeOnBackdrop = resolveProp(props, 'closeOnBackdrop') !== 'false'
+    const closeOnEscape = resolveProp(props, 'closeOnEscape') !== 'false'
+    const maxWidth = SIZE_WIDTHS[size] || SIZE_WIDTHS.md
+
+    return `<div id="stx-modal-${id}" class="stx-modal-backdrop" data-stx-modal="${id}" data-close-backdrop="${closeOnBackdrop}" data-close-escape="${closeOnEscape}" style="display:none;position:fixed;inset:0;z-index:99999;align-items:center;justify-content:center;background:rgba(0,0,0,0.5);backdrop-filter:blur(2px);opacity:0;transition:opacity 0.2s ease" aria-modal="true" role="dialog">
+  <div class="stx-modal-panel" style="${maxWidth};width:100%;margin:1rem;border-radius:0.75rem;box-shadow:0 20px 60px rgba(0,0,0,0.3);overflow:hidden;transform:scale(0.95) translateY(8px);transition:transform 0.2s ease,opacity 0.2s ease;opacity:0;background:var(--stx-modal-bg,#fff);color:var(--stx-modal-text,#1f2937)">
+    <div style="padding:1.5rem">${slotContent}</div>
+  </div>
+</div>
+<style>
+@media(prefers-color-scheme:dark){[data-stx-modal]{--stx-modal-bg:#1f2937;--stx-modal-text:#f3f4f6}}
+.stx-modal-backdrop[data-stx-modal-open]{display:flex!important;opacity:1}
+.stx-modal-backdrop[data-stx-modal-open] .stx-modal-panel{transform:scale(1) translateY(0);opacity:1}
+</style>`
+  },
+}

packages/stx/src/signals.ts

@@ -3005,6 +3005,158 @@ catch (e) {}
     }
   };
 
+  // ── Modal system ──────────────────────────────────────────────────
+  var modal = {
+    open: function(id) {
+      var el = document.querySelector('[data-stx-modal="' + id + '"]');
+      if (!el) { console.warn('[stx:modal] Modal "' + id + '" not found'); return; }
+      el.style.display = 'flex';
+      // Force reflow then animate
+      void el.offsetHeight;
+      el.setAttribute('data-stx-modal-open', '');
+      document.body.style.overflow = 'hidden';
+      // Escape key handler
+      if (el.getAttribute('data-close-escape') !== 'false') {
+        var escHandler = function(e) {
+          if (e.key === 'Escape') { modal.close(id); document.removeEventListener('keydown', escHandler); }
+        };
+        document.addEventListener('keydown', escHandler);
+        el._stxEscHandler = escHandler;
+      }
+      // Backdrop click
+      if (el.getAttribute('data-close-backdrop') !== 'false') {
+        el.onclick = function(e) { if (e.target === el) modal.close(id); };
+      }
+    },
+    close: function(id) {
+      var el = document.querySelector('[data-stx-modal="' + id + '"]');
+      if (!el) return;
+      el.removeAttribute('data-stx-modal-open');
+      if (el._stxEscHandler) { document.removeEventListener('keydown', el._stxEscHandler); el._stxEscHandler = null; }
+      el.onclick = null;
+      setTimeout(function() {
+        el.style.display = 'none';
+        // Restore scroll if no other modals are open
+        if (!document.querySelector('[data-stx-modal-open]')) document.body.style.overflow = '';
+      }, 200);
+    },
+    toggle: function(id) {
+      var el = document.querySelector('[data-stx-modal="' + id + '"]');
+      if (el && el.hasAttribute('data-stx-modal-open')) modal.close(id);
+      else modal.open(id);
+    }
+  };
+
+  // ── Alert & Confirm dialogs ─────────────────────────────────────
+  // Styled replacements for window.alert() and window.confirm().
+  // Both return Promises and render into a temporary modal overlay.
+
+  var _dialogId = 0;
+  var _dialogIcons = {
+    info: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#2563eb" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>',
+    warning: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#d97706" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
+    error: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#dc2626" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>',
+    success: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#16a34a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M9 12l2 2 4-4"/></svg>',
+    question: '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#6366f1" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 015.83 1c0 2-3 3-3 3"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>'
+  };
+
+  function _createDialog(message, options, isConfirm) {
+    var opts = options || {};
+    var type = opts.type || (isConfirm ? 'question' : 'info');
+    var title = opts.title || '';
+    var confirmText = opts.confirmText || 'OK';
+    var cancelText = opts.cancelText || 'Cancel';
+    var id = 'stx-dialog-' + (++_dialogId);
+    var isDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+    var bg = isDark ? '#1f2937' : '#ffffff';
+    var textColor = isDark ? '#f3f4f6' : '#1f2937';
+    var subColor = isDark ? '#9ca3af' : '#6b7280';
+    var icon = _dialogIcons[type] || _dialogIcons.info;
+
+    return new Promise(function(resolve) {
+      var backdrop = document.createElement('div');
+      backdrop.id = id;
+      backdrop.style.cssText = 'position:fixed;inset:0;z-index:999999;display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,0.5);backdrop-filter:blur(2px);opacity:0;transition:opacity 0.2s ease;font-family:system-ui,-apple-system,sans-serif';
+      backdrop.setAttribute('role', 'alertdialog');
+      backdrop.setAttribute('aria-modal', 'true');
+
+      var panel = document.createElement('div');
+      panel.style.cssText = 'max-width:24rem;width:calc(100% - 2rem);border-radius:0.75rem;padding:1.5rem;background:' + bg + ';color:' + textColor + ';box-shadow:0 20px 60px rgba(0,0,0,0.3);transform:scale(0.95);transition:transform 0.2s ease;text-align:center';
+
+      var iconDiv = document.createElement('div');
+      iconDiv.style.cssText = 'display:flex;justify-content:center;margin-bottom:1rem';
+      iconDiv.innerHTML = icon;
+      panel.appendChild(iconDiv);
+
+      if (title) {
+        var titleEl = document.createElement('h3');
+        titleEl.style.cssText = 'margin:0 0 0.5rem;font-size:1.125rem;font-weight:600';
+        titleEl.textContent = title;
+        panel.appendChild(titleEl);
+      }
+
+      var msgEl = document.createElement('p');
+      msgEl.style.cssText = 'margin:0 0 1.25rem;font-size:0.875rem;line-height:1.5;color:' + subColor;
+      msgEl.textContent = message;
+      panel.appendChild(msgEl);
+
+      var btnRow = document.createElement('div');
+      btnRow.style.cssText = 'display:flex;gap:0.75rem;justify-content:center';
+
+      function cleanup(result) {
+        backdrop.style.opacity = '0';
+        panel.style.transform = 'scale(0.95)';
+        setTimeout(function() { backdrop.remove(); }, 200);
+        resolve(result);
+      }
+
+      if (isConfirm) {
+        var cancelBtn = document.createElement('button');
+        cancelBtn.textContent = cancelText;
+        cancelBtn.style.cssText = 'padding:0.5rem 1.25rem;border-radius:0.5rem;font-size:0.875rem;font-weight:500;cursor:pointer;border:1px solid ' + (isDark ? '#374151' : '#d1d5db') + ';background:transparent;color:' + textColor + ';transition:background 0.15s';
+        cancelBtn.onmouseover = function() { this.style.background = isDark ? '#374151' : '#f3f4f6'; };
+        cancelBtn.onmouseout = function() { this.style.background = 'transparent'; };
+        cancelBtn.onclick = function() { cleanup(false); };
+        btnRow.appendChild(cancelBtn);
+      }
+
+      var okBtn = document.createElement('button');
+      okBtn.textContent = confirmText;
+      var btnColor = type === 'error' ? '#dc2626' : type === 'warning' ? '#d97706' : '#5672cd';
+      okBtn.style.cssText = 'padding:0.5rem 1.25rem;border-radius:0.5rem;font-size:0.875rem;font-weight:500;cursor:pointer;border:none;background:' + btnColor + ';color:#fff;transition:opacity 0.15s';
+      okBtn.onmouseover = function() { this.style.opacity = '0.9'; };
+      okBtn.onmouseout = function() { this.style.opacity = '1'; };
+      okBtn.onclick = function() { cleanup(isConfirm ? true : undefined); };
+      btnRow.appendChild(okBtn);
+
+      panel.appendChild(btnRow);
+      backdrop.appendChild(panel);
+      document.body.appendChild(backdrop);
+
+      // Animate in
+      void backdrop.offsetHeight;
+      backdrop.style.opacity = '1';
+      panel.style.transform = 'scale(1)';
+
+      // Escape key
+      var escHandler = function(e) {
+        if (e.key === 'Escape') { cleanup(isConfirm ? false : undefined); document.removeEventListener('keydown', escHandler); }
+      };
+      document.addEventListener('keydown', escHandler);
+
+      // Focus the primary button
+      okBtn.focus();
+    });
+  }
+
+  function stxAlert(message, options) {
+    return _createDialog(message, options, false);
+  }
+
+  function stxConfirm(message, options) {
+    return _createDialog(message, options, true);
+  }
+
   // Component mount system
   var mountQueue = [];
 
@@ -3054,6 +3206,9 @@ catch (e) {}
     useHead,
     useSeoMeta,
     toast,
+    modal,
+    alert: stxAlert,
+    confirm: stxConfirm,
     helpers: globalHelpers,
 
     // Component composition API (Phase 4)
@@ -3510,6 +3665,9 @@ else {
   window.useHead = useHead;
   window.useSeoMeta = useSeoMeta;
   window.toast = toast;
+  window.modal = modal;
+  window.stxAlert = stxAlert;
+  window.stxConfirm = stxConfirm;
   window.defineStore = window.stx.defineStore;
   window.useStore = window.stx.useStore;
   window.ref = state;

packages/stx/stx.d.ts

@@ -325,6 +325,42 @@ interface StxToast {
 
 declare const toast: StxToast
 
+// ============================================================================
+// Modal system
+// ============================================================================
+
+interface StxModal {
+  /** Open a modal by its id */
+  open: (id: string) => void
+  /** Close a modal by its id */
+  close: (id: string) => void
+  /** Toggle a modal by its id */
+  toggle: (id: string) => void
+}
+
+declare const modal: StxModal
+
+// ============================================================================
+// Alert & Confirm dialogs
+// ============================================================================
+
+interface StxDialogOptions {
+  /** Dialog title displayed above the message */
+  title?: string
+  /** Icon type: 'info' | 'warning' | 'error' | 'success' | 'question' */
+  type?: 'info' | 'warning' | 'error' | 'success' | 'question'
+  /** Text for the confirm/OK button (default: 'OK') */
+  confirmText?: string
+  /** Text for the cancel button — confirm only (default: 'Cancel') */
+  cancelText?: string
+}
+
+/** Styled replacement for window.alert(). Returns a Promise that resolves when dismissed. */
+declare function stxAlert(message: string, options?: StxDialogOptions): Promise<void>
+
+/** Styled replacement for window.confirm(). Returns a Promise<boolean>. */
+declare function stxConfirm(message: string, options?: StxDialogOptions): Promise<boolean>
+
 // ============================================================================
 // Stores (Pinia-inspired, signals-based)
 // ============================================================================
@@ -439,6 +475,13 @@ interface StxRuntimeRegistry {
   // Toast
   toast: StxToast
 
+  // Modal
+  modal: StxModal
+
+  // Dialogs
+  alert: typeof stxAlert
+  confirm: typeof stxConfirm
+
   // Mount API
   mount: (setupFn: () => any) => void
   mountEl: (selector: string, setupFn: () => any) => void