@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/components/xsurfacemanager-controller.js

@@ -48,7 +48,11 @@
     'dialog',
     'drawer',
     'popover',
-    'tooltip'
+    'tooltip',
+    'region',
+    'toast',
+    'lightbox',
+    'menu'
   ]);
 
   const DEFAULT_CAPABILITIES = Object.freeze({
@@ -58,7 +62,11 @@
     dialog: Object.freeze(['open', 'focus', 'close', 'snapshot']),
     drawer: Object.freeze(['open', 'focus', 'close', 'resize', 'restore', 'snapshot']),
     popover: Object.freeze(['open', 'focus', 'close', 'snapshot']),
-    tooltip: Object.freeze(['open', 'close', 'snapshot'])
+    tooltip: Object.freeze(['open', 'close', 'snapshot']),
+    region: Object.freeze(['open', 'focus', 'close', 'update', 'restore', 'snapshot']),
+    toast: Object.freeze(['open', 'close', 'dismiss', 'snapshot']),
+    lightbox: Object.freeze(['open', 'focus', 'close', 'snapshot']),
+    menu: Object.freeze(['open', 'focus', 'close', 'update', 'snapshot'])
   });
 
   const DEFAULT_BOUNDS = Object.freeze({
@@ -68,7 +76,11 @@
     dialog: Object.freeze({ x: 0, y: 0, width: 480, height: 320, minWidth: 280, minHeight: 160 }),
     drawer: Object.freeze({ x: 0, y: 0, width: 360, height: 720, minWidth: 240, minHeight: 180 }),
     popover: Object.freeze({ x: 0, y: 0, width: 280, height: 160, minWidth: 160, minHeight: 96 }),
-    tooltip: Object.freeze({ x: 0, y: 0, width: 220, height: 80, minWidth: 120, minHeight: 48 })
+    tooltip: Object.freeze({ x: 0, y: 0, width: 220, height: 80, minWidth: 120, minHeight: 48 }),
+    region: Object.freeze({ x: 0, y: 0, width: 640, height: 360, minWidth: 160, minHeight: 96 }),
+    toast: Object.freeze({ x: 0, y: 0, width: 360, height: 96, minWidth: 220, minHeight: 48 }),
+    lightbox: Object.freeze({ x: 0, y: 0, width: 720, height: 520, minWidth: 320, minHeight: 220 }),
+    menu: Object.freeze({ x: 0, y: 0, width: 280, height: 240, minWidth: 160, minHeight: 96 })
   });
 
   const DIAGNOSTIC_CODES = Object.freeze([
@@ -200,6 +212,7 @@
       id,
       manager: managerId,
       type,
+      kind: clampString(source.kind || record.kind, type),
       label,
       stateKey,
       status: defaultOpen ? 'open' : 'closed',
@@ -233,6 +246,7 @@
       id: record.id,
       manager: record.manager,
       type: record.type,
+      kind: record.kind || record.type,
       label: record.label,
       status: record.status,
       active: record.active,
@@ -496,9 +510,19 @@
 
       const previous = registry.get(record.id);
       if (previous) {
+        record.bounds = normalizeSurfaceBounds(previous.bounds, record.type);
+        record.previousBounds = previous.previousBounds
+          ? normalizeSurfaceBounds(previous.previousBounds, record.type)
+          : null;
         record.zIndex = previous.zIndex;
         record.active = previous.active;
         record.status = previous.status;
+        record.minimized = previous.minimized;
+        record.maximized = previous.maximized;
+        record.pinned = previous.pinned;
+        record.collapsed = previous.collapsed;
+        record.placement = previous.placement;
+        record.mode = previous.mode;
       }
       registry.set(record.id, record);
       if (record.status === 'open') {

package/components/xsurfacemanager.d.ts

@@ -55,6 +55,8 @@ export type XSurfaceManagerEventName =
   | 'surface-stack-policy-focus-restored'
   | 'surface-stack-policy-error'
   | 'surface-layout-engine-applied'
+  | 'surface-region-command'
+  | 'surface-portal-policy'
   | 'remote-surface-mounted'
   | 'remote-surface-degraded'
   | 'remote-surface-refused'

package/components/xsurfacemanager.js

@@ -10,7 +10,7 @@ import {
   toOverlaySurfaceRecord
 } from './xsurfaceoverlay-bridge.js';
 
-const SURFACE_MANAGED_ELEMENT_SELECTOR = `x-surface-window, x-side-panel, ${SURFACE_OVERLAY_SELECTOR}`;
+const SURFACE_MANAGED_ELEMENT_SELECTOR = `x-surface-window, x-side-panel, x-surface-region, ${SURFACE_OVERLAY_SELECTOR}`;
 const SURFACE_MANAGER_PERSISTENCE_SCHEMA = 'xtend.surface.manager-persistence.v1';
 const SURFACE_PERSISTED_SNAPSHOT_SCHEMA = 'xtend.surface.persisted-snapshot.v1';
 const SURFACE_PERSISTENCE_DIAGNOSTIC_SCHEMA = 'xtend.surface.persistence-diagnostic.v1';
@@ -31,7 +31,7 @@ const SURFACE_LAYOUT_ENGINE_SCHEMA = 'xtend.surface.layout-engine.v1';
 const SURFACE_LAYOUT_ENGINE_REPORT_SCHEMA = 'xtend.surface.layout-engine-report.v1';
 const SURFACE_LAYOUT_ENGINE_DIAGNOSTIC_SCHEMA = 'xtend.surface.layout-engine-diagnostic.v1';
 const SURFACE_LAYOUT_ENGINES = Object.freeze(['freeform', 'docked', 'split', 'tile', 'stacked']);
-const SURFACE_LAYOUT_SURFACE_TYPES = Object.freeze(['window', 'side-panel']);
+const SURFACE_LAYOUT_SURFACE_TYPES = Object.freeze(['window', 'side-panel', 'region']);
 const SURFACE_LAYOUT_PLACEMENTS = Object.freeze(['left', 'right', 'top', 'bottom', 'inline', 'center']);
 const SURFACE_REMOTE_POLICY_SCHEMA = 'xtend.surface.remote-policy-bridge.v1';
 const SURFACE_REMOTE_POLICY_REPORT_SCHEMA = 'xtend.surface.remote-policy-report.v1';
@@ -105,7 +105,7 @@ function surfaceElementSelector(surfaceId) {
     .split(',')
     .map((selector) => `${selector.trim()}[id="${id}"]`)
     .join(', ');
-  return `x-surface-window[surface-id="${id}"], x-side-panel[surface-id="${id}"], ${overlayBySurfaceId}, ${overlayById}`;
+  return `x-surface-window[surface-id="${id}"], x-side-panel[surface-id="${id}"], x-surface-region[surface-id="${id}"], x-surface-region[id="${id}"], [data-rmt-surface="${id}"], ${overlayBySurfaceId}, ${overlayById}`;
 }
 
 function safeJsonParse(value) {
@@ -486,6 +486,7 @@ function clonePersistedSurfaceRecord(record) {
     id: record.id,
     manager: record.manager,
     type: record.type,
+    kind: record.kind || record.type,
     label: record.label,
     status: record.status,
     active: Boolean(record.active),
@@ -679,7 +680,7 @@ class XSurfaceManager extends HTMLElement {
       lane: 'visible',
       hydrationPolicy: 'visible',
       criticalMeasurements: ['mount', 'register-surface', 'snapshot', 'surface-content-hydrate', 'surface-route-lifecycle', 'surface-stack-policy', 'surface-layout-engine', 'surface-remote-policy'],
-      cleanup: ['slotchange', 'surface-window-command', 'surface-panel-command', 'surface-overlay-command', 'route-lifecycle-listeners', 'stack-policy-listeners']
+      cleanup: ['slotchange', 'surface-window-command', 'surface-panel-command', 'surface-region-command', 'surface-overlay-command', 'route-lifecycle-listeners', 'stack-policy-listeners']
     };
   }
 
@@ -749,6 +750,7 @@ class XSurfaceManager extends HTMLElement {
     this._handleSlotChange = this._registerAssignedSurfaces.bind(this);
     this._handleSurfaceCommand = this._onSurfaceCommand.bind(this);
     this._handlePanelCommand = this._onSurfaceCommand.bind(this);
+    this._handleRegionCommand = this._onSurfaceCommand.bind(this);
     this._handleOverlayCommand = this._onSurfaceCommand.bind(this);
     this._handleOverlayLifecycle = this._onOverlayLifecycle.bind(this);
     this._handleSurfaceRouteSignal = this._onSurfaceRouteSignal.bind(this);
@@ -817,6 +819,7 @@ class XSurfaceManager extends HTMLElement {
     this._slots.forEach((slot) => slot.addEventListener('slotchange', this._handleSlotChange));
     this.addEventListener('surface-window-command', this._handleSurfaceCommand);
     this.addEventListener('surface-panel-command', this._handlePanelCommand);
+    this.addEventListener('surface-region-command', this._handleRegionCommand);
     this.addEventListener('surface-overlay-command', this._handleOverlayCommand);
     this._addSurfaceRouteListeners();
     this._addSurfaceStackPolicyListeners();
@@ -843,6 +846,7 @@ class XSurfaceManager extends HTMLElement {
     this._slots.forEach((slot) => slot.removeEventListener('slotchange', this._handleSlotChange));
     this.removeEventListener('surface-window-command', this._handleSurfaceCommand);
     this.removeEventListener('surface-panel-command', this._handlePanelCommand);
+    this.removeEventListener('surface-region-command', this._handleRegionCommand);
     this.removeEventListener('surface-overlay-command', this._handleOverlayCommand);
     this._removeSurfaceRouteListeners();
     this._removeSurfaceStackPolicyListeners();
@@ -3642,13 +3646,21 @@ class XSurfaceManager extends HTMLElement {
 
   _onSurfaceCommand(event) {
     const detail = event.detail || {};
-    const { command, payload } = detail;
+    const { payload } = detail;
+    const rawCommand = detail.command;
     const surfaceId = detail.surfaceId || detail.id;
-    if (!surfaceId || !command) return;
+    if (!surfaceId || !rawCommand) return;
     event.stopPropagation();
+    const command = {
+      show: 'open',
+      hide: 'close',
+      dismiss: 'close'
+    }[rawCommand] || rawCommand;
+    const current = this.snapshot().surfaces.find((record) => record.id === surfaceId);
     const commands = {
       open: () => this.openSurface(surfaceId, payload),
       close: () => this.closeSurface(surfaceId, payload && payload.reason),
+      toggle: () => current && current.status !== 'closed' ? this.closeSurface(surfaceId, payload && payload.reason || 'toggle') : this.openSurface(surfaceId, payload),
       focus: () => this.focusSurface(surfaceId),
       move: () => this.moveSurface(surfaceId, payload),
       resize: () => this.resizeSurface(surfaceId, payload),
@@ -3677,7 +3689,7 @@ class XSurfaceManager extends HTMLElement {
     }
 
     const detail = event.detail || {};
-    if (event.type.endsWith('-opened')) {
+    if (event.type.endsWith('-opened') || event.type === 'toast-shown') {
       this.openSurface(surfaceId, {
         source: detail.source || event.type,
         legacyEvent: event.type
@@ -3685,7 +3697,7 @@ class XSurfaceManager extends HTMLElement {
       return;
     }
 
-    if (event.type.endsWith('-closed')) {
+    if (event.type.endsWith('-closed') || event.type === 'toast-dismissed') {
       this.closeSurface(surfaceId, detail.source || event.type);
       return;
     }

package/components/xsurfaceoverlay-bridge.d.ts

@@ -1,7 +1,7 @@
 import type { XtendSurfaceRecord, XtendSurfaceType } from './xsurfacemanager-controller';
 
 export declare const SURFACE_OVERLAY_BRIDGE_SCHEMA: 'xtend.surface.overlay-stack-bridge.v1';
-export declare const SURFACE_OVERLAY_SELECTOR: 'x-modal, x-dialog, x-drawer';
+export declare const SURFACE_OVERLAY_SELECTOR: 'x-modal, x-dialog, x-drawer, x-popover, x-tooltip, x-toast, x-lightbox, x-menu';
 export declare const OVERLAY_LIFECYCLE_EVENTS: readonly [
   'modal-opened',
   'modal-closed',
@@ -9,13 +9,28 @@ export declare const OVERLAY_LIFECYCLE_EVENTS: readonly [
   'dialog-closed',
   'drawer-opened',
   'drawer-closed',
-  'drawer-route-selected'
+  'drawer-route-selected',
+  'popover-opened',
+  'popover-closed',
+  'tooltip-opened',
+  'tooltip-closed',
+  'toast-shown',
+  'toast-dismissed',
+  'lightbox-opened',
+  'lightbox-closed',
+  'menu-opened',
+  'menu-closed',
+  'menu-navigate'
 ];
 
+export type XtendSurfaceOverlayComponentRef = 'x-modal' | 'x-dialog' | 'x-drawer' | 'x-popover' | 'x-tooltip' | 'x-toast' | 'x-lightbox' | 'x-menu';
+export type XtendSurfaceOverlayType = Extract<XtendSurfaceType, 'modal' | 'dialog' | 'drawer' | 'popover' | 'tooltip' | 'toast' | 'lightbox' | 'menu'>;
+
 export interface XtendSurfaceOverlayCompatibilityProfile {
   schema: typeof SURFACE_OVERLAY_BRIDGE_SCHEMA;
-  componentRef: 'x-modal' | 'x-dialog' | 'x-drawer';
-  surfaceType: Extract<XtendSurfaceType, 'modal' | 'dialog' | 'drawer'>;
+  componentRef: XtendSurfaceOverlayComponentRef;
+  surfaceType: XtendSurfaceOverlayType;
+  surfaceKind: XtendSurfaceOverlayType;
   managerSlot: 'overlays';
   managerEvent: 'surface-overlay-command';
   legacyLifecycleEvents: readonly string[];
@@ -37,7 +52,7 @@ export interface XtendSurfaceOverlayCompatibilityProfile {
 export declare function isSurfaceOverlayElement(element: Element | null | undefined): element is HTMLElement;
 export declare function findSurfaceOverlayElement(event: Event): HTMLElement | null;
 export declare function overlaySurfaceId(element: HTMLElement): string;
-export declare function overlaySurfaceType(element: HTMLElement): Extract<XtendSurfaceType, 'modal' | 'dialog' | 'drawer'>;
+export declare function overlaySurfaceType(element: HTMLElement): XtendSurfaceOverlayType;
 export declare function createOverlayCompatibilityProfile(element: HTMLElement): XtendSurfaceOverlayCompatibilityProfile | null;
 export declare function toOverlaySurfaceRecord(element: HTMLElement, managerId?: string): Partial<XtendSurfaceRecord> & Record<string, unknown>;
 export declare function applyOverlaySurfaceSnapshot(element: HTMLElement, record?: Partial<XtendSurfaceRecord>): void;

package/components/xsurfaceoverlay-bridge.js

@@ -1,4 +1,4 @@
-const SURFACE_OVERLAY_SELECTOR = 'x-modal, x-dialog, x-drawer';
+const SURFACE_OVERLAY_SELECTOR = 'x-modal, x-dialog, x-drawer, x-popover, x-tooltip, x-toast, x-lightbox, x-menu';
 const SURFACE_OVERLAY_BRIDGE_SCHEMA = 'xtend.surface.overlay-stack-bridge.v1';
 const SURFACE_RECORD_SCHEMA = 'xtend.surface.record.v1';
 const OVERLAY_Z_INDEX_BASE = 2147483000;
@@ -33,6 +33,56 @@ const OVERLAY_PROFILES = Object.freeze({
     lifecycleEvents: Object.freeze(['drawer-opened', 'drawer-closed', 'drawer-route-selected']),
     modal: false,
     capabilities: Object.freeze(['open', 'focus', 'close', 'resize', 'restore', 'snapshot'])
+  }),
+  'x-popover': Object.freeze({
+    componentRef: 'x-popover',
+    surfaceType: 'popover',
+    family: 'popover',
+    stateKey: 'xpopover-open-<id>',
+    labelAttributes: Object.freeze(['label', 'aria-label', 'title']),
+    lifecycleEvents: Object.freeze(['popover-opened', 'popover-closed']),
+    modal: false,
+    capabilities: Object.freeze(['open', 'focus', 'close', 'snapshot'])
+  }),
+  'x-tooltip': Object.freeze({
+    componentRef: 'x-tooltip',
+    surfaceType: 'tooltip',
+    family: 'tooltip',
+    stateKey: 'xtooltip-open-<id>',
+    labelAttributes: Object.freeze(['label', 'aria-label', 'title']),
+    lifecycleEvents: Object.freeze(['tooltip-opened', 'tooltip-closed']),
+    modal: false,
+    capabilities: Object.freeze(['open', 'close', 'snapshot'])
+  }),
+  'x-toast': Object.freeze({
+    componentRef: 'x-toast',
+    surfaceType: 'toast',
+    family: 'toast',
+    stateKey: 'xtoast-state-<id>',
+    labelAttributes: Object.freeze(['label', 'aria-label', 'title', 'type']),
+    lifecycleEvents: Object.freeze(['toast-shown', 'toast-dismissed']),
+    modal: false,
+    capabilities: Object.freeze(['open', 'close', 'dismiss', 'snapshot'])
+  }),
+  'x-lightbox': Object.freeze({
+    componentRef: 'x-lightbox',
+    surfaceType: 'lightbox',
+    family: 'media-lightbox',
+    stateKey: 'xlightbox-open-<id>',
+    labelAttributes: Object.freeze(['label', 'aria-label', 'title', 'alt']),
+    lifecycleEvents: Object.freeze(['lightbox-opened', 'lightbox-closed']),
+    modal: true,
+    capabilities: Object.freeze(['open', 'focus', 'close', 'snapshot'])
+  }),
+  'x-menu': Object.freeze({
+    componentRef: 'x-menu',
+    surfaceType: 'menu',
+    family: 'menu',
+    stateKey: 'xmenu-state-<id>',
+    labelAttributes: Object.freeze(['label', 'aria-label', 'title']),
+    lifecycleEvents: Object.freeze(['menu-opened', 'menu-closed', 'menu-navigate']),
+    modal: false,
+    capabilities: Object.freeze(['open', 'focus', 'close', 'update', 'snapshot'])
   })
 });
 
@@ -43,7 +93,18 @@ const OVERLAY_LIFECYCLE_EVENTS = Object.freeze([
   'dialog-closed',
   'drawer-opened',
   'drawer-closed',
-  'drawer-route-selected'
+  'drawer-route-selected',
+  'popover-opened',
+  'popover-closed',
+  'tooltip-opened',
+  'tooltip-closed',
+  'toast-shown',
+  'toast-dismissed',
+  'lightbox-opened',
+  'lightbox-closed',
+  'menu-opened',
+  'menu-closed',
+  'menu-navigate'
 ]);
 
 function overlayTagName(element) {
@@ -108,13 +169,26 @@ function overlaySurfaceType(element) {
   return profile ? profile.surfaceType : 'dialog';
 }
 
+function overlayElementIsOpen(element, profile = overlayProfileFor(element)) {
+  if (!element) return false;
+  if (element.hasAttribute && element.hasAttribute('open')) return true;
+  const tag = overlayTagName(element);
+  if (tag === 'x-toast') return element.isConnected !== false && element._dismissed !== true;
+  if (tag === 'x-menu') return element.isConnected !== false;
+  if (profile && profile.surfaceType === 'menu') return element.isConnected !== false;
+  return false;
+}
+
 function overlayLabel(element, profile, id) {
   return readAttribute(element, profile.labelAttributes, id || profile.surfaceType);
 }
 
 function overlayPlacement(element, type) {
-  if (type !== 'drawer') return null;
-  return readAttribute(element, ['placement'], 'right');
+  if (type === 'drawer') return readAttribute(element, ['placement'], 'right');
+  if (type === 'popover') return readAttribute(element, ['placement'], 'bottom');
+  if (type === 'tooltip') return readAttribute(element, ['placement'], 'top');
+  if (type === 'menu') return readAttribute(element, ['placement'], 'bottom-start');
+  return null;
 }
 
 function overlayIsModal(element, profile, type) {
@@ -134,6 +208,7 @@ function createOverlayCompatibilityProfile(element) {
     schema: SURFACE_OVERLAY_BRIDGE_SCHEMA,
     componentRef: profile.componentRef,
     surfaceType: profile.surfaceType,
+    surfaceKind: profile.surfaceType,
     managerSlot: 'overlays',
     managerEvent: 'surface-overlay-command',
     legacyLifecycleEvents: profile.lifecycleEvents.slice(),
@@ -168,10 +243,11 @@ function toOverlaySurfaceRecord(element, managerId = 'xtend.surface.manager') {
     id,
     manager: managerId,
     type,
+    kind: type,
     label: overlayLabel(element, profile, id),
     stateKey: overlayStateKey(profile, id),
-    status: element.hasAttribute('open') ? 'open' : 'closed',
-    defaultOpen: element.hasAttribute('open'),
+    status: overlayElementIsOpen(element, profile) ? 'open' : 'closed',
+    defaultOpen: overlayElementIsOpen(element, profile),
     modal: overlayIsModal(element, profile, type),
     placement,
     mode: 'overlay',
@@ -183,25 +259,45 @@ function toOverlaySurfaceRecord(element, managerId = 'xtend.surface.manager') {
 }
 
 function callOverlayOpen(element) {
-  if (overlayTagName(element) === 'x-drawer' && typeof element.openDrawer === 'function') {
-    element.openDrawer({ source: 'surface-manager' });
-    return;
+  const tag = overlayTagName(element);
+  const methodNames = tag === 'x-drawer'
+    ? ['openDrawer', 'show', 'open']
+    : ['openModal', 'openDialog', 'openLightbox', 'show', 'open'];
+  for (const methodName of methodNames) {
+    if (typeof element[methodName] === 'function') {
+      element[methodName]({ source: 'surface-manager' });
+      return;
+    }
   }
-  if (typeof element.open === 'function') {
-    element.open({ source: 'surface-manager' });
-    return;
+  if ('open' in element) {
+    try {
+      element.open = true;
+      return;
+    } catch (_error) {
+      // Fall through to attribute bridge.
+    }
   }
   element.setAttribute('open', '');
 }
 
 function callOverlayClose(element) {
-  if (overlayTagName(element) === 'x-drawer' && typeof element.closeDrawer === 'function') {
-    element.closeDrawer({ source: 'surface-manager' });
-    return;
+  const tag = overlayTagName(element);
+  const methodNames = tag === 'x-drawer'
+    ? ['closeDrawer', 'hide', 'close']
+    : ['closeModal', 'closeDialog', 'closeLightbox', 'dismiss', 'hide', 'close'];
+  for (const methodName of methodNames) {
+    if (typeof element[methodName] === 'function') {
+      element[methodName]({ source: 'surface-manager' });
+      return;
+    }
   }
-  if (typeof element.close === 'function') {
-    element.close({ source: 'surface-manager' });
-    return;
+  if ('open' in element) {
+    try {
+      element.open = false;
+      return;
+    } catch (_error) {
+      // Fall through to attribute bridge.
+    }
   }
   element.removeAttribute('open');
 }

package/components/xsurfaceportal.d.ts

@@ -0,0 +1,29 @@
+export type XSurfacePortalPolicy = 'stacked' | 'modal' | 'nonmodal' | 'toast-region' | 'clipping-escape' | string;
+export type XSurfacePortalAttributeName = 'portal-id' | 'policy' | 'layer' | 'for' | 'z-index-start' | 'z-step';
+
+export interface XSurfacePortalPolicyRecord {
+  schema: 'xtend.surface.portal-policy.v1';
+  id: string;
+  policy: XSurfacePortalPolicy;
+  layer: string;
+  target: string;
+  zIndexStart: number;
+  zStep: number;
+  component: 'x-surface-portal';
+  kernelBoundary: 'no-rmt-kernel-import-of-xtend-types';
+}
+
+export interface XSurfacePortalElement extends HTMLElement {
+  readonly portalId: string;
+  readonly policy: XSurfacePortalPolicy;
+  toPortalPolicy(): XSurfacePortalPolicyRecord;
+  addEventListener(type: 'surface-portal-policy', listener: (event: CustomEvent<XSurfacePortalPolicyRecord>) => void, options?: boolean | AddEventListenerOptions): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'x-surface-portal': XSurfacePortalElement;
+  }
+}
+
+export {};

package/components/xsurfaceportal.js

@@ -0,0 +1,122 @@
+class XSurfacePortal extends HTMLElement {
+  static get observedAttributes() {
+    return ['portal-id', 'policy', 'layer', 'for', 'z-index-start', 'z-step'];
+  }
+
+  static get xtendComponentContract() {
+    return {
+      schema: 'xtend.component.contract.v2',
+      tag: 'x-surface-portal',
+      maturity: 'experimental',
+      source: {
+        strategy: 'xtend.legacy-esm.component-source',
+        state: 'js-runtime',
+        sourcePath: 'components/xsurfaceportal.js'
+      },
+      runtime: {
+        format: 'esm',
+        artifact: 'components/xsurfaceportal.js',
+        declaration: 'components/xsurfaceportal.d.ts',
+        localOnly: true,
+        cdnAllowed: false
+      },
+      rmt: {
+        adapter: 'xtend.component',
+        surfaceContract: 'xtend.surface.type-capability-matrix.v1',
+        kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'
+      }
+    };
+  }
+
+  static get xtendRmtMetadata() {
+    return {
+      schema: 'xtend.rmt.component-contract.v1',
+      adapter: 'xtend.component',
+      tag: 'x-surface-portal',
+      componentRecordKind: 'custom_element',
+      templateMode: 'dom_descriptor',
+      portalPolicies: ['stacked', 'modal', 'nonmodal', 'toast-region', 'clipping-escape'],
+      kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'
+    };
+  }
+
+  static get xtendScaffoldA11yProfile() {
+    return {
+      schema: 'xtend.a11y.component-profile.v1',
+      role: 'none',
+      policy: 'portal-policy-announced-by-managed-surface',
+      keyboardModel: 'delegated-to-surface-manager',
+      aria: ['aria-hidden']
+    };
+  }
+
+  static get xtendScaffoldPerformanceProfile() {
+    return {
+      schema: 'xtend.performance.component-profile.v1',
+      budgetClass: 'surface-orchestration',
+      lane: 'surface.portal.policy',
+      hydrationPolicy: 'policy-only',
+      measurements: ['policy-dispatch', 'stack-reflow']
+    };
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: contents;
+        }
+      </style>
+      <slot></slot>
+    `;
+  }
+
+  connectedCallback() {
+    if (!this.hasAttribute('portal-id') && this.id) this.setAttribute('portal-id', this.id);
+    if (!this.hasAttribute('policy')) this.setAttribute('policy', 'stacked');
+    if (!this.hasAttribute('aria-hidden')) this.setAttribute('aria-hidden', 'true');
+    this._emitPolicy();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this._emitPolicy();
+  }
+
+  get portalId() {
+    return this.getAttribute('portal-id') || this.id || 'portal.app';
+  }
+
+  get policy() {
+    return this.getAttribute('policy') || 'stacked';
+  }
+
+  toPortalPolicy() {
+    return {
+      schema: 'xtend.surface.portal-policy.v1',
+      id: this.portalId,
+      policy: this.policy,
+      layer: this.getAttribute('layer') || this.portalId,
+      target: this.getAttribute('for') || '',
+      zIndexStart: Number(this.getAttribute('z-index-start') || 1000),
+      zStep: Number(this.getAttribute('z-step') || 10),
+      component: 'x-surface-portal',
+      kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'
+    };
+  }
+
+  _emitPolicy() {
+    this.dispatchEvent(new CustomEvent('surface-portal-policy', {
+      bubbles: true,
+      composed: true,
+      detail: this.toPortalPolicy()
+    }));
+  }
+}
+
+if (!customElements.get('x-surface-portal')) {
+  customElements.define('x-surface-portal', XSurfacePortal);
+}
+
+export { XSurfacePortal };

package/components/xsurfaceregion.d.ts

@@ -0,0 +1,50 @@
+import type {
+  XtendSurfaceRecord
+} from './xsurfacemanager-controller';
+
+export type XSurfaceRegionKind = 'root' | 'workspace' | 'page' | 'card' | 'list' | 'region' | 'overlay-host' | string;
+export type XSurfaceRegionAttributeName =
+  | 'surface-id'
+  | 'label'
+  | 'kind'
+  | 'open'
+  | 'active'
+  | 'hidden'
+  | 'mode'
+  | 'placement'
+  | 'initial-x'
+  | 'initial-y'
+  | 'initial-width'
+  | 'initial-height'
+  | 'role';
+
+export type XSurfaceRegionCommand = 'open' | 'close' | 'focus' | 'restore' | 'update';
+
+export interface XSurfaceRegionCommandDetail {
+  surfaceId: string;
+  command: XSurfaceRegionCommand;
+  payload: Record<string, unknown>;
+}
+
+export interface XSurfaceRegionElement extends HTMLElement {
+  surfaceManager: HTMLElement | null;
+  readonly surfaceId: string;
+  readonly kind: XSurfaceRegionKind;
+  open: boolean;
+  toSurfaceRecord(managerId: string): Partial<XtendSurfaceRecord> & Record<string, unknown>;
+  applySurfaceSnapshot(record: XtendSurfaceRecord): void;
+  openRegion(): XSurfaceRegionCommandDetail;
+  closeRegion(reason?: string): XSurfaceRegionCommandDetail;
+  focusRegion(): XSurfaceRegionCommandDetail;
+  restoreRegion(): XSurfaceRegionCommandDetail;
+  updateRegion(payload?: Record<string, unknown>): XSurfaceRegionCommandDetail;
+  addEventListener(type: 'surface-region-command', listener: (event: CustomEvent<XSurfaceRegionCommandDetail>) => void, options?: boolean | AddEventListenerOptions): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'x-surface-region': XSurfaceRegionElement;
+  }
+}
+
+export {};