@zeyos/zx 4.2.0 → 4.3.4

package/src/components/card-view/card-view.css

@@ -1,6 +1,10 @@
 .zx-card-view {
-  --zx-card-view-min-card-width: 18rem;
+  --zx-card-view-min-card-width: 15rem;
   --zx-card-view-column-basis: 0%;
+  --zx-card-view-card-padding: var(--zx-space-3);
+  --zx-card-view-card-gap: var(--zx-space-2);
+  --zx-card-view-grid-gap: var(--zx-space-3);
+  --zx-card-view-preview-size: 1.75rem;
   inline-size: 100%;
   min-inline-size: 0;
   container-type: inline-size;
@@ -44,22 +48,23 @@
 }
 
 .zx-card-view__group + .zx-card-view__group {
-  margin-block-start: var(--zx-space-6);
+  margin-block-start: var(--zx-space-4);
 }
 
 .zx-card-view__group-heading {
-  margin: 0 0 var(--zx-space-3);
+  margin: 0 0 var(--zx-space-2);
   color: var(--zx-color-text);
-  font-size: var(--zx-text-lg);
-  line-height: 1.35;
+  font-size: var(--zx-text-sm);
+  font-weight: 600;
+  line-height: 1.3;
 }
 
 .zx-card-view__list {
   display: grid;
-  grid-template-columns: repeat(auto-fit,
+  grid-template-columns: repeat(auto-fill,
     minmax(min(100%, max(var(--zx-card-view-min-card-width),
-      calc(var(--zx-card-view-column-basis) - var(--zx-space-4)))), 1fr));
-  gap: var(--zx-space-4);
+      calc(var(--zx-card-view-column-basis) - var(--zx-card-view-grid-gap)))), 1fr));
+  gap: var(--zx-card-view-grid-gap);
   min-inline-size: 0;
   margin: 0;
   padding: 0;
@@ -102,7 +107,7 @@
   box-shadow: var(--zx-focus-ring);
 }
 
-.zx-record-card[aria-selected="true"] {
+.zx-record-card[data-selected="true"] {
   border-color: var(--zx-color-accent);
   box-shadow: inset 0 0 0 1px var(--zx-color-accent);
 }
@@ -181,6 +186,40 @@
   min-inline-size: 0;
 }
 
+.zx-record-card__eyebrow {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+}
+
+.zx-record-card__eyebrow-group,
+.zx-record-card__title-prefix {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--zx-space-1);
+  min-inline-size: 0;
+  margin: 0;
+}
+
+.zx-record-card__eyebrow-group[data-card-slot="eyebrow-end"] {
+  justify-content: flex-end;
+  margin-inline-start: auto;
+}
+
+.zx-record-card__title-row {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+}
+
+.zx-record-card__title-row > .zx-record-card__heading {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+}
+
 .zx-record-card__heading {
   margin: 0;
   overflow-wrap: anywhere;
@@ -387,3 +426,166 @@
       box-shadow var(--zx-dur-fast) var(--zx-ease);
   }
 }
+
+/*
+ * CardView intentionally presents the shared record-card anatomy more densely than Kanban. Keep
+ * these selectors scoped: Kanban owns its own board-card rhythm while both views retain the same
+ * safe, semantic markup and delegated interaction hooks.
+ */
+.zx-card-view .zx-record-card {
+  border-radius: var(--zx-radius-md);
+}
+
+.zx-card-view .zx-record-card:has(> .zx-record-card__preview) {
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: start;
+}
+
+.zx-card-view .zx-record-card__preview {
+  inline-size: var(--zx-card-view-preview-size);
+  block-size: var(--zx-card-view-preview-size);
+  margin-block-start: var(--zx-card-view-card-padding);
+  margin-inline-start: var(--zx-card-view-card-padding);
+  border: 0;
+  border-radius: var(--zx-radius-sm);
+  aspect-ratio: 1;
+}
+
+.zx-card-view .zx-record-card__preview .zx-icon {
+  inline-size: .875rem;
+  block-size: .875rem;
+}
+
+.zx-card-view .zx-record-card__body {
+  gap: var(--zx-card-view-card-gap);
+  padding: var(--zx-card-view-card-padding);
+}
+
+.zx-card-view .zx-record-card:has(> .zx-record-card__preview) .zx-record-card__body {
+  padding-inline-start: var(--zx-card-view-card-gap);
+}
+
+.zx-card-view .zx-record-card__header {
+  gap: var(--zx-space-2);
+}
+
+.zx-card-view .zx-record-card__selection {
+  min-block-size: 1.25rem;
+}
+
+.zx-card-view .zx-record-card__heading {
+  font-size: var(--zx-text-md);
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.zx-card-view .zx-record-card__primary,
+.zx-card-view .zx-record-card__title {
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.zx-card-view .zx-record-card__subtitle {
+  margin-block-start: calc(var(--zx-space-1) / 2);
+  overflow: hidden;
+  font-size: var(--zx-text-xs);
+  line-height: 1.3;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.zx-card-view .zx-record-card__actions {
+  flex-wrap: nowrap;
+  gap: calc(var(--zx-space-1) / 2);
+}
+
+.zx-card-view .zx-record-card__action {
+  min-block-size: 1.75rem;
+  border-color: transparent;
+  background: transparent;
+  padding-inline: var(--zx-space-2);
+  font-size: var(--zx-text-xs);
+}
+
+.zx-card-view .zx-record-card__metadata {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--zx-space-1);
+}
+
+.zx-card-view .zx-record-card__field {
+  display: inline-flex;
+  flex: 0 1 auto;
+  align-items: center;
+  gap: var(--zx-space-1);
+  max-inline-size: 100%;
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-bg-muted);
+  padding: calc(var(--zx-space-1) / 2) var(--zx-space-2);
+}
+
+.zx-card-view .zx-record-card__label {
+  flex: none;
+  font-size: var(--zx-text-xs);
+  font-weight: 500;
+  line-height: 1.2;
+}
+
+.zx-card-view .zx-record-card__value {
+  overflow: hidden;
+  font-size: var(--zx-text-xs);
+  line-height: 1.2;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.zx-card-view .zx-card-view__group-empty {
+  padding: var(--zx-space-3);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-card-view .zx-card-view__empty {
+  min-block-size: 6rem;
+  border-radius: var(--zx-radius-md);
+  padding: var(--zx-space-4);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-card-view .zx-card-view__skeleton {
+  grid-template-columns: var(--zx-card-view-preview-size) minmax(0, 1fr);
+  gap: var(--zx-card-view-card-gap);
+  padding: var(--zx-card-view-card-padding);
+}
+
+.zx-card-view .zx-card-view__skeleton-preview {
+  grid-row: 1 / span 2;
+  inline-size: var(--zx-card-view-preview-size);
+  margin: 0;
+  aspect-ratio: 1;
+  border-radius: var(--zx-radius-sm);
+}
+
+.zx-card-view .zx-card-view__skeleton-line {
+  min-inline-size: 0;
+  block-size: .625rem;
+}
+
+.zx-card-view .zx-card-view__skeleton-line:nth-child(3) {
+  inline-size: 62%;
+}
+
+.zx-card-view .zx-card-view__skeleton-line:nth-child(4) {
+  grid-column: 1 / -1;
+  inline-size: 42%;
+}
+
+@media (pointer: coarse) {
+  .zx-card-view .zx-record-card__selection,
+  .zx-card-view .zx-record-card__action {
+    min-inline-size: 44px;
+    min-block-size: 44px;
+  }
+}

package/src/components/card-view/card-view.js

@@ -39,7 +39,7 @@ import {
  * @property {string|((record:ViewRecord,index:number)=>unknown)|null} [groupBy=null]
  * Field id or local group resolver.
  * @property {unknown[]} [groupOrder=[]] Preferred group ids; missing ids render as empty groups.
- * @property {number|string} [minCardWidth='18rem'] Responsive minimum card width.
+ * @property {number|string} [minCardWidth='15rem'] Responsive minimum card width.
  * @property {number|null} [maxColumns=null] Maximum cards per row; null is unconstrained.
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Card surface treatment.
  * @property {number} [loadingCount=6] Skeleton cards shown while loading.
@@ -87,7 +87,7 @@ export class CardView extends RecordView {
     actions: [],
     groupBy: null,
     groupOrder: [],
-    minCardWidth: '18rem',
+    minCardWidth: '15rem',
     maxColumns: null,
     variant: 'outlined',
     loadingCount: 6,
@@ -329,7 +329,7 @@ export class CardView extends RecordView {
     for (const [id, card] of this._cardNodesById) {
       const selected = this._isViewSelected(id);
       card.dataset.selected = String(selected);
-      if (this.options.selectable) card.setAttribute('aria-selected', String(selected));
+      if (this.options.selectable) card.setAttribute('aria-description', selected ? 'Selected' : 'Not selected');
       const checkbox = /** @type {HTMLInputElement|null} */ (card.querySelector('[data-record-selection]'));
       if (checkbox) checkbox.checked = selected;
     }
@@ -469,11 +469,11 @@ function normalizeGroupId(value) {
 
 /** @param {unknown} value @returns {string} */
 export function normalizeCardWidth(value) {
-  if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? `${value}px` : '18rem';
+  if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? `${value}px` : '15rem';
   const text = String(value ?? '').trim();
-  if (!text || text.length > 128 || /[;{}\u0000-\u001f\u007f]/.test(text)) return '18rem';
-  if (/(?:url|image|image-set|cross-fade|element|expression)\s*\(/i.test(text)) return '18rem';
-  if (typeof globalThis.CSS?.supports === 'function' && !globalThis.CSS.supports('width', text)) return '18rem';
+  if (!text || text.length > 128 || /[;{}\u0000-\u001f\u007f]/.test(text)) return '15rem';
+  if (/(?:url|image|image-set|cross-fade|element|expression)\s*\(/i.test(text)) return '15rem';
+  if (typeof globalThis.CSS?.supports === 'function' && !globalThis.CSS.supports('width', text)) return '15rem';
   return text;
 }
 

package/src/components/card-view/record-card.js

@@ -7,6 +7,15 @@ import { readViewField, renderViewField } from '../view/record-view.js';
 /** @typedef {Record<string, any>} ViewRecord */
 /** @typedef {import('../view/record-view.js').ViewField} ViewField */
 /** @typedef {string|((record:ViewRecord,index:number)=>unknown)|null} RecordCardValueSource */
+/** @typedef {'eyebrow-start'|'eyebrow-end'|'title-prefix'} RecordCardFieldSlot */
+
+/**
+ * @typedef {Object} RecordCardFieldGroups
+ * @property {ViewField[]} eyebrowStart Fields shown at the logical start of the eyebrow row.
+ * @property {ViewField[]} eyebrowEnd Fields shown at the logical end of the eyebrow row.
+ * @property {ViewField[]} titlePrefix Fields shown immediately before, but outside, the heading.
+ * @property {ViewField[]} metadata Remaining labelled metadata fields.
+ */
 
 /**
  * @typedef {Object} RecordCardPreviewDescriptor
@@ -73,11 +82,12 @@ import { readViewField, renderViewField } from '../view/record-view.js';
  * becomes text, URLs are normalized before reaching native attributes, and actions expose stable
  * data attributes for a component-owned delegated listener.
  *
- * The returned `<li>` belongs in a semantic `<ul>`/`<ol>`. When selectable it carries
- * `aria-selected`; multi-selection adds a native checkbox. It deliberately retains list-item
- * semantics rather than becoming an ARIA option because cards may contain native links and
- * buttons, which the listbox pattern does not permit inside an option. Preview images are paired
- * with a stable fallback. The owning component listens for image `error` and marks the fallback.
+ * The returned `<li>` belongs in a semantic `<ul>`/`<ol>`. When selectable its global
+ * `aria-description` announces selection without applying the unsupported `aria-selected` state
+ * to a listitem; multi-selection also adds a native checkbox. It deliberately remains a listitem
+ * rather than becoming an ARIA option because cards may contain native links and buttons, which
+ * the listbox pattern does not permit inside an option. Preview images are paired with a stable
+ * fallback. The owning component listens for image `error` and marks the fallback.
  *
  * @param {ViewRecord} record Record to render.
  * @param {number} index Current display index.
@@ -112,6 +122,13 @@ export function createRecordCard(record, index, options = {}) {
     class: 'zx-record-card__heading',
     id: headingId
   }, headingContent);
+  const fieldGroups = partitionRecordCardFields(visibleFields, titleSource, subtitleSource);
+  const eyebrow = createEyebrow(record, index, fieldGroups.eyebrowStart, fieldGroups.eyebrowEnd);
+  const titlePrefix = createFieldList(record, index, fieldGroups.titlePrefix,
+    'zx-record-card__title-prefix', 'title-prefix');
+  const titleRow = titlePrefix
+    ? h('div', { class: 'zx-record-card__title-row' }, titlePrefix, heading)
+    : heading;
   const selection = selectable === 'multi' ? h('label', {
     class: 'zx-record-card__selection'
   }, h('input', {
@@ -127,15 +144,15 @@ export function createRecordCard(record, index, options = {}) {
     ariaLabel: `Actions for ${textAlternative(title) || 'record'}`
   }, controls, actionNodes) : null;
   const header = h('header', { class: 'zx-record-card__header' }, selection,
-    h('div', { class: 'zx-record-card__titles' }, heading,
+    h('div', { class: 'zx-record-card__titles' }, titleRow,
       isEmptyContent(subtitle) ? null : h('p', { class: 'zx-record-card__subtitle' }, contentNode(subtitle))),
     actionArea);
-  const metadata = createMetadata(record, index, visibleFields, titleSource, subtitleSource);
-  const body = h('div', { class: 'zx-record-card__body' }, header, metadata);
+  const metadata = createFieldList(record, index, fieldGroups.metadata, 'zx-record-card__metadata');
+  const body = h('div', { class: 'zx-record-card__body' }, eyebrow, header, metadata);
   const card = /** @type {HTMLLIElement} */ (h('li', {
     class: 'zx-record-card',
     tabindex: 0,
-    ariaSelected: selectable ? String(selected) : undefined,
+    ariaDescription: selectable ? selected ? 'Selected' : 'Not selected' : undefined,
     ariaLabelledby: headingId,
     dataset: {
       recordIndex: String(index),
@@ -146,6 +163,36 @@ export function createRecordCard(record, index, options = {}) {
   return card;
 }
 
+/**
+ * Partitions ordered visible fields into the shared record-card slots. A recognized
+ * `field.view.card.slot` moves the field to that semantic region; absent or unknown values remain
+ * ordinary metadata. Title and subtitle fields retain the existing no-duplication rule.
+ *
+ * The input array and descriptors are never mutated. Each field appears in at most one result
+ * array, and the order within every result follows the supplied visible-field order.
+ *
+ * @param {ViewField[]} fields Ordered visible fields.
+ * @param {RecordCardValueSource} [titleSource=null] Active title field or resolver.
+ * @param {RecordCardValueSource} [subtitleSource=null] Active subtitle field or resolver.
+ * @returns {RecordCardFieldGroups} Partitioned fields.
+ */
+export function partitionRecordCardFields(fields, titleSource = null, subtitleSource = null) {
+  /** @type {RecordCardFieldGroups} */
+  const groups = { eyebrowStart: [], eyebrowEnd: [], titlePrefix: [], metadata: [] };
+  const titleId = typeof titleSource === 'string' ? titleSource : null;
+  const subtitleId = typeof subtitleSource === 'string' ? subtitleSource : null;
+
+  for (const field of Array.isArray(fields) ? fields : []) {
+    if (!field.duplicate && (field.id === titleId || field.id === subtitleId)) continue;
+    const slot = resolveRecordCardFieldSlot(field);
+    if (slot === 'eyebrow-start') groups.eyebrowStart.push(field);
+    else if (slot === 'eyebrow-end') groups.eyebrowEnd.push(field);
+    else if (slot === 'title-prefix') groups.titlePrefix.push(field);
+    else groups.metadata.push(field);
+  }
+  return groups;
+}
+
 /**
  * Resolves a preview without touching the DOM. Unsafe, malformed, and non-image URL schemes are
  * rejected into the same descriptor shape so callers can still render the stable fallback.
@@ -245,26 +292,52 @@ function createPreview(preview) {
   }, fallback, image);
 }
 
+/**
+ * @param {ViewRecord} record
+ * @param {number} index
+ * @param {ViewField[]} eyebrowStart
+ * @param {ViewField[]} eyebrowEnd
+ * @returns {HTMLElement|null}
+ */
+function createEyebrow(record, index, eyebrowStart, eyebrowEnd) {
+  const start = createFieldList(record, index, eyebrowStart,
+    'zx-record-card__eyebrow-group', 'eyebrow-start');
+  const end = createFieldList(record, index, eyebrowEnd,
+    'zx-record-card__eyebrow-group', 'eyebrow-end');
+  return start || end ? h('div', { class: 'zx-record-card__eyebrow' }, start, end) : null;
+}
+
 /**
  * @param {ViewRecord} record
  * @param {number} index
  * @param {ViewField[]} fields
- * @param {RecordCardValueSource} titleSource
- * @param {RecordCardValueSource} subtitleSource
+ * @param {string} className
+ * @param {RecordCardFieldSlot|null} [slot=null]
  * @returns {HTMLElement|null}
  */
-function createMetadata(record, index, fields, titleSource, subtitleSource) {
-  const titleId = typeof titleSource === 'string' ? titleSource : null;
-  const subtitleId = typeof subtitleSource === 'string' ? subtitleSource : null;
-  const visible = fields.filter((field) => field.duplicate || field.id !== titleId && field.id !== subtitleId);
-  if (visible.length === 0) return null;
-  return h('dl', { class: 'zx-record-card__metadata' }, visible.map((field) => h('div', {
+function createFieldList(record, index, fields, className, slot = null) {
+  if (fields.length === 0) return null;
+  return h('dl', {
+    class: className,
+    dataset: slot ? { cardSlot: slot } : undefined
+  }, fields.map((field) => h('div', {
     class: 'zx-record-card__field',
-    dataset: { fieldId: field.id }
+    dataset: { fieldId: field.id, ...(slot ? { cardSlot: slot } : {}) }
   }, h('dt', { class: 'zx-record-card__label' }, field.label),
   h('dd', { class: 'zx-record-card__value' }, contentNode(renderViewField(field, record, index))))));
 }
 
+/** @param {ViewField} field @returns {RecordCardFieldSlot|null} */
+function resolveRecordCardFieldSlot(field) {
+  const view = field?.view;
+  if (!view || typeof view !== 'object' || Array.isArray(view)) return null;
+  const card = view.card;
+  if (!card || typeof card !== 'object' || Array.isArray(card)) return null;
+  const slot = /** @type {{slot?:unknown}} */ (card).slot;
+  return slot === 'eyebrow-start' || slot === 'eyebrow-end' || slot === 'title-prefix'
+    ? slot : null;
+}
+
 /** @param {RecordCardAction} action @returns {HTMLElement} */
 function createAction(action) {
   const label = String(action.label ?? '');
@@ -356,7 +429,7 @@ function safePreviewUrl(value) {
   try {
     const base = globalThis.location?.href ?? 'https://zx.invalid/';
     const protocol = new URL(href, base).protocol.toLowerCase();
-    return ['http:', 'https:', 'blob:', 'file:'].includes(protocol) ? href : null;
+    return ['http:', 'https:', 'blob:'].includes(protocol) ? href : null;
   } catch {
     return null;
   }

package/src/components/context-menu/context-menu.css

@@ -29,7 +29,7 @@
 
 .zx-context-menu__item:hover,
 .zx-context-menu__item:focus-visible {
-  background: var(--zx-color-bg-hover);
+  background: var(--zx-color-overlay-hover);
 }
 
 .zx-context-menu__item[data-danger="true"] {
@@ -50,5 +50,5 @@
 .zx-context-menu__separator {
   block-size: 1px;
   margin: var(--zx-space-1) var(--zx-space-2);
-  background: var(--zx-color-border);
+  background: var(--zx-color-overlay-divider);
 }

package/src/components/context-menu/context-menu.js

@@ -82,7 +82,11 @@ export class ContextMenu extends Component {
     this.#target = resolved;
     document.body.append(this.el);
 
-    this.#dropdown = new Dropdown(this.el, { openOn: 'manual', placement: 'bottom-start' });
+    this.#dropdown = new Dropdown(this.el, {
+      openOn: 'manual',
+      placement: 'bottom-start',
+      scope: resolved
+    });
     this.#panel = this.#dropdown.getPanel();
     this.#panel.classList.add('zx-context-menu');
     this.#panel.setAttribute('role', 'menu');

package/src/components/date-picker/date-picker.css

@@ -31,14 +31,14 @@
   place-items: center;
   min-inline-size: var(--zx-control-height);
   padding: 0;
-  border-color: var(--zx-color-bg-surface);
-  background: inherit;
+  border-color: transparent;
+  background: transparent;
 }
 
 .zx-date-picker__heading {
   overflow: hidden;
-  border-color: var(--zx-color-bg-surface);
-  background: inherit;
+  border-color: transparent;
+  background: transparent;
   font-weight: 650;
   text-overflow: ellipsis;
   text-wrap: nowrap;
@@ -76,9 +76,9 @@
   min-inline-size: 0;
   min-block-size: var(--zx-control-height);
   padding: 0;
-  border-color: var(--zx-color-bg-surface);
+  border-color: transparent;
   border-radius: var(--zx-radius-md);
-  background: inherit;
+  background: transparent;
   font-variant-numeric: tabular-nums;
 }
 
@@ -125,10 +125,12 @@
   inset: var(--zx-space-3);
   border: 1px solid var(--zx-color-overlay-border);
   border-radius: var(--zx-radius-md);
-  background: var(--zx-color-overlay-surface);
+  background-color: var(--zx-color-overlay-surface);
+  background-image: var(--zx-overlay-surface-image);
+  background-clip: padding-box;
   -webkit-backdrop-filter: var(--zx-glass-filter-overlay);
   backdrop-filter: var(--zx-glass-filter-overlay);
-  box-shadow: var(--zx-glass-raised-shadow);
+  box-shadow: var(--zx-glass-overlay-shadow);
   padding: var(--zx-space-3);
 }
 
@@ -157,11 +159,16 @@
 .zx-month-picker__month {
   min-inline-size: 0;
   padding-inline: var(--zx-space-1);
-  border-color: var(--zx-color-bg-surface);
-  background: inherit;
+  border-color: transparent;
+  background: transparent;
+}
+
+.zx-date-picker__quick-month[aria-selected="true"] {
+  background: var(--zx-color-overlay-selected);
+  color: var(--zx-color-accent);
+  font-weight: 700;
 }
 
-.zx-date-picker__quick-month[aria-selected="true"],
 .zx-month-picker__month[aria-selected="true"] {
   background: var(--zx-color-bg-selected);
   color: var(--zx-color-accent);

package/src/components/datebox/date-range-box.css

@@ -124,10 +124,12 @@
 .zx-date-range-box__popover .zx-date-range-picker__surface {
   max-inline-size: none;
   border-color: var(--zx-color-overlay-border);
-  background: var(--zx-color-overlay-surface);
+  background-color: var(--zx-color-overlay-surface);
+  background-image: var(--zx-overlay-surface-image);
+  background-clip: padding-box;
   -webkit-backdrop-filter: var(--zx-glass-filter-overlay);
   backdrop-filter: var(--zx-glass-filter-overlay);
-  box-shadow: var(--zx-glass-raised-shadow);
+  box-shadow: var(--zx-glass-overlay-shadow);
 }
 
 @media (prefers-reduced-transparency: reduce) {

package/src/components/datebox/datebox.css

@@ -104,10 +104,12 @@
 
 .zx-datebox__popover .zx-date-picker__surface {
   border-color: var(--zx-color-overlay-border);
-  background: var(--zx-color-overlay-surface);
+  background-color: var(--zx-color-overlay-surface);
+  background-image: var(--zx-overlay-surface-image);
+  background-clip: padding-box;
   -webkit-backdrop-filter: var(--zx-glass-filter-overlay);
   backdrop-filter: var(--zx-glass-filter-overlay);
-  box-shadow: var(--zx-glass-raised-shadow);
+  box-shadow: var(--zx-glass-overlay-shadow);
 }
 
 @media (prefers-reduced-transparency: reduce) {

package/src/components/dialog/dialog.css

@@ -3,7 +3,8 @@
   padding: 0;
 }
 
-.zx-dialog[open] {
+.zx-dialog[open],
+.zx-dialog:popover-open {
   display: grid;
 }
 
@@ -17,7 +18,7 @@
 
 .zx-dialog__header {
   justify-content: space-between;
-  border-block-end: 1px solid var(--zx-color-border);
+  border-block-end: 1px solid var(--zx-color-overlay-divider);
 }
 
 .zx-dialog__title {
@@ -40,7 +41,7 @@
 
 .zx-dialog__footer {
   justify-content: flex-end;
-  border-block-start: 1px solid var(--zx-color-border);
+  border-block-start: 1px solid var(--zx-color-overlay-divider);
 }
 
 .zx-dialog__footer[hidden] {

package/src/components/dialog/dialog.js

@@ -22,6 +22,7 @@ const FOCUSABLE_SELECTOR = [
  * @property {DialogButton[]} [buttons=[]] Footer buttons.
  * @property {boolean} [closable=true] Whether Escape and the header button may close the dialog.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -89,7 +90,7 @@ export class Dialog extends Modal {
   #opener = null;
 
   /**
-   * Creates a structured dialog appended to `document.body`.
+   * Creates a structured dialog in the configured theme scope, or at document level when unscoped.
    * @param {Element|string|null} [_target=null] Ignored; Dialog always owns its root.
    * @param {DialogOptions} [options={}] Dialog options.
    */

package/src/components/dropdown/dropdown.css

@@ -4,10 +4,12 @@
   overflow: auto;
   border: 1px solid var(--zx-color-overlay-border);
   border-radius: var(--zx-radius-md);
-  background: var(--zx-color-overlay-surface);
+  background-color: var(--zx-color-overlay-surface);
+  background-image: var(--zx-overlay-surface-image);
+  background-clip: padding-box;
   -webkit-backdrop-filter: var(--zx-glass-filter-overlay);
   backdrop-filter: var(--zx-glass-filter-overlay);
-  box-shadow: var(--zx-glass-raised-shadow);
+  box-shadow: var(--zx-glass-overlay-shadow);
   color: var(--zx-color-text);
   padding: var(--zx-space-3);
 }