@adobe/spectrum-wc-core 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/mixins/sized-mixin.js.map

@@ -1 +1 @@
-{"version":3,"file":"sized-mixin.js","names":[],"sources":["../../mixins/sized-mixin.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\nimport { PropertyValues, ReactiveElement } from 'lit';\nimport { property } from 'lit/decorators.js';\n\ntype Constructor<T = Record<string, unknown>> = {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  new (...args: any[]): T;\n  prototype: T;\n};\n\nexport const ELEMENT_SIZES = ['xxs', 'xs', 's', 'm', 'l', 'xl', 'xxl'] as const;\nexport type ElementSize = (typeof ELEMENT_SIZES)[number];\n\nexport const DEFAULT_ELEMENT_SIZES = [\n  's',\n  'm',\n  'l',\n  'xl',\n] as const satisfies readonly ElementSize[];\nexport type DefaultElementSize = (typeof DEFAULT_ELEMENT_SIZES)[number];\n\nexport interface SizedElementInterface {\n  size: ElementSize;\n}\n\nexport interface SizedElementConstructor {\n  readonly VALID_SIZES: readonly ElementSize[];\n}\n\nexport function SizedMixin<T extends Constructor<ReactiveElement>>(\n  constructor: T,\n  {\n    validSizes = [...DEFAULT_ELEMENT_SIZES],\n    noDefaultSize,\n    defaultSize = 'm',\n  }: {\n    validSizes?: readonly ElementSize[];\n    noDefaultSize?: boolean;\n    defaultSize?: ElementSize;\n  } = {}\n): T & Constructor<SizedElementInterface> & SizedElementConstructor {\n  class SizedElement extends constructor {\n    /**\n     * @internal\n     */\n    static readonly VALID_SIZES: readonly ElementSize[] = validSizes;\n\n    @property({ type: String })\n    public get size(): ElementSize {\n      return this._size || defaultSize;\n    }\n\n    public set size(value: ElementSize) {\n      const fallbackSize = noDefaultSize ? null : defaultSize;\n      const size = (value ? value.toLocaleLowerCase() : value) as ElementSize;\n      const classValidSizes = (\n        this.constructor as unknown as SizedElementConstructor\n      ).VALID_SIZES;\n      const validSize = (\n        classValidSizes.includes(size) ? size : fallbackSize\n      ) as ElementSize;\n      if (validSize) {\n        this.setAttribute('size', validSize);\n      }\n      if (this._size === validSize) {\n        return;\n      }\n      const oldSize = this._size;\n      this._size = validSize;\n      this.requestUpdate('size', oldSize);\n    }\n\n    /** @internal */\n    private _size: ElementSize | null = defaultSize;\n\n    protected override update(changes: PropertyValues): void {\n      if (!this.hasAttribute('size') && !noDefaultSize) {\n        this.setAttribute('size', this.size);\n      }\n      super.update(changes);\n    }\n  }\n  return SizedElement;\n}\n"],"mappings":";;;AAoBA,IAAa,IAAgB;CAAC;CAAO;CAAM;CAAK;CAAK;CAAK;CAAM;CAAM,EAGzD,IAAwB;CACnC;CACA;CACA;CACA;CACD;AAWD,SAAgB,EACd,GACA,EACE,gBAAa,CAAC,GAAG,EAAsB,EACvC,kBACA,iBAAc,QAKZ,EAAE,EAC4D;;CAClE,MAAM,UAAqB,EAAY;;6BAgCD;;EA1BpC,IACW,OAAoB;AAC7B,UAAO,KAAK,SAAS;;EAGvB,IAAW,KAAK,GAAoB;GAClC,IAAM,IAAe,IAAgB,OAAO,GACtC,IAAQ,KAAQ,EAAM,mBAAmB,EAIzC,IAFJ,KAAK,YACL,YAEgB,SAAS,EAAK,GAAG,IAAO;AAK1C,OAHI,KACF,KAAK,aAAa,QAAQ,EAAU,EAElC,KAAK,UAAU,EACjB;GAEF,IAAM,IAAU,KAAK;AAErB,GADA,KAAK,QAAQ,GACb,KAAK,cAAc,QAAQ,EAAQ;;EAMrC,OAA0B,GAA+B;AAIvD,GAHI,CAAC,KAAK,aAAa,OAAO,IAAI,CAAC,KACjC,KAAK,aAAa,QAAQ,KAAK,KAAK,EAEtC,MAAM,OAAO,EAAQ;;;AAGzB,+BArCwD,MAErD,EAAS,EAAE,MAAM,QAAQ,CAAC,CAAA,EAAA,EAAA,WAAA,QAAA,KAAA,EAmCtB"}
+{"version":3,"file":"sized-mixin.js","names":[],"sources":["../../mixins/sized-mixin.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\nimport { PropertyValues, ReactiveElement } from 'lit';\nimport { property } from 'lit/decorators.js';\n\ntype Constructor<T = Record<string, unknown>> = {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  new (...args: any[]): T;\n  prototype: T;\n};\n\nexport const ELEMENT_SIZES = ['xxs', 'xs', 's', 'm', 'l', 'xl', 'xxl'] as const;\nexport type ElementSize = (typeof ELEMENT_SIZES)[number];\n\nexport const DEFAULT_ELEMENT_SIZES = [\n  's',\n  'm',\n  'l',\n  'xl',\n] as const satisfies readonly ElementSize[];\nexport type DefaultElementSize = (typeof DEFAULT_ELEMENT_SIZES)[number];\n\nexport interface SizedElementInterface {\n  size: ElementSize;\n}\n\nexport interface SizedElementConstructor {\n  readonly VALID_SIZES: readonly ElementSize[];\n  readonly NO_DEFAULT_SIZE: boolean;\n}\n\n/**\n * Mixes size-awareness into a Lit `ReactiveElement` subclass.\n *\n * ## Why NO_DEFAULT_SIZE is a static rather than a closure variable\n *\n * The original implementation captured `noDefaultSize` in a closure at call\n * time. That works when a component applies SizedMixin directly to a plain\n * base (e.g. `SizedMixin(SpectrumElement, { noDefaultSize: true })`), but\n * breaks silently when a component extends a base that is already SizedMixin'd.\n *\n * Consider InfieldButton extending ButtonBase:\n *   - ButtonBase = SizedMixin(SpectrumElement, {}) — closure captures noDefaultSize=false\n *   - InfieldButtonBase extends ButtonBase\n *\n * Even if a second SizedMixin wrapper is applied with noDefaultSize=true, calling\n * super.update() reaches the inner ButtonBase SizedMixin, whose update() still\n * reads noDefaultSize=false from its closure and writes size=\"m\" to the DOM.\n * Likewise, when a parent calls removeAttribute('size'), the inherited setter\n * reads the inner closure's fallbackSize='m' and immediately re-sets the attribute.\n *\n * Making NO_DEFAULT_SIZE a static property solves both problems: the setter and\n * update() read this.constructor.NO_DEFAULT_SIZE, which follows the prototype\n * chain to the leaf class. A subclass like InfieldButtonBase only needs to\n * declare `static override readonly NO_DEFAULT_SIZE = true` — no mixin\n * re-wrapping, no lifecycle interception, and the correct value is read by every\n * SizedMixin layer in the chain.\n */\nexport function SizedMixin<T extends Constructor<ReactiveElement>>(\n  constructor: T,\n  {\n    validSizes = [...DEFAULT_ELEMENT_SIZES],\n    noDefaultSize,\n    defaultSize = 'm',\n  }: {\n    validSizes?: readonly ElementSize[];\n    noDefaultSize?: boolean;\n    defaultSize?: ElementSize;\n  } = {}\n): T & Constructor<SizedElementInterface> & SizedElementConstructor {\n  class SizedElement extends constructor {\n    /**\n     * @internal\n     */\n    static readonly VALID_SIZES: readonly ElementSize[] = validSizes;\n\n    /**\n     * When true, the component does not auto-reflect a default size attribute.\n     * The parent is expected to supply the size. Subclasses of an already-sized\n     * base (e.g. InfieldButtonBase extends ButtonBase) can override this static\n     * to opt out of the inherited base's auto-set behavior without re-wrapping\n     * the mixin.\n     *\n     * @internal\n     */\n    static readonly NO_DEFAULT_SIZE: boolean = noDefaultSize ?? false;\n\n    @property({ type: String })\n    public get size(): ElementSize {\n      return this._size || defaultSize;\n    }\n\n    public set size(value: ElementSize) {\n      const sizedConstructor = this\n        .constructor as unknown as SizedElementConstructor;\n      const fallbackSize = sizedConstructor.NO_DEFAULT_SIZE\n        ? null\n        : defaultSize;\n      const size = (value ? value.toLocaleLowerCase() : value) as ElementSize;\n      const classValidSizes = sizedConstructor.VALID_SIZES;\n      const validSize = (\n        classValidSizes.includes(size) ? size : fallbackSize\n      ) as ElementSize;\n      if (validSize) {\n        this.setAttribute('size', validSize);\n      }\n      if (this._size === validSize) {\n        return;\n      }\n      const oldSize = this._size;\n      this._size = validSize;\n      this.requestUpdate('size', oldSize);\n    }\n\n    /** @internal */\n    private _size: ElementSize | null = defaultSize;\n\n    protected override update(changes: PropertyValues): void {\n      if (\n        !this.hasAttribute('size') &&\n        !(this.constructor as unknown as SizedElementConstructor)\n          .NO_DEFAULT_SIZE\n      ) {\n        this.setAttribute('size', this.size);\n      }\n      super.update(changes);\n    }\n  }\n  return SizedElement;\n}\n"],"mappings":";;;AAoBA,IAAa,IAAgB;CAAC;CAAO;CAAM;CAAK;CAAK;CAAK;CAAM;CAAM,EAGzD,IAAwB;CACnC;CACA;CACA;CACA;CACD;AAuCD,SAAgB,EACd,GACA,EACE,gBAAa,CAAC,GAAG,EAAsB,EACvC,kBACA,iBAAc,QAKZ,EAAE,EAC4D;;CAClE,MAAM,UAAqB,EAAY;;6BA6CD;;EA5BpC,IACW,OAAoB;AAC7B,UAAO,KAAK,SAAS;;EAGvB,IAAW,KAAK,GAAoB;GAClC,IAAM,IAAmB,KACtB,aACG,IAAe,EAAiB,kBAClC,OACA,GACE,IAAQ,KAAQ,EAAM,mBAAmB,EAEzC,IADkB,EAAiB,YAEvB,SAAS,EAAK,GAAG,IAAO;AAK1C,OAHI,KACF,KAAK,aAAa,QAAQ,EAAU,EAElC,KAAK,UAAU,EACjB;GAEF,IAAM,IAAU,KAAK;AAErB,GADA,KAAK,QAAQ,GACb,KAAK,cAAc,QAAQ,EAAQ;;EAMrC,OAA0B,GAA+B;AAQvD,GANE,CAAC,KAAK,aAAa,OAAO,IAC1B,CAAE,KAAK,YACJ,mBAEH,KAAK,aAAa,QAAQ,KAAK,KAAK,EAEtC,MAAM,OAAO,EAAQ;;;AAGzB,+BAtDwD,uBAWX,KAAA,OAAiB,KAAjB,MAE1C,EAAS,EAAE,MAAM,QAAQ,CAAC,CAAA,EAAA,EAAA,WAAA,QAAA,KAAA,EAyCtB"}

package/dist/utils/dev-validation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+/**
+ * Whether dev-mode validation is active: `false` in production builds and in
+ * non-browser (SSR) environments, otherwise mirrors `window.__swc.DEBUG`.
+ *
+ * Use this to guard the *call site* of a warning whose condition or message is
+ * expensive to compute (for example a DOM traversal), so that work is skipped
+ * entirely when validation is off:
+ *
+ * ```ts
+ * if (isDebug()) {
+ *   this.warnAboutExpensiveThing(); // only traverses the DOM when validation runs
+ * }
+ * ```
+ *
+ * For cheap conditions, call `warnIf`/`validateEnum` directly; they already
+ * gate internally. This helper exists only to avoid paying call-site argument
+ * cost in the expensive cases. It checks `process.env.NODE_ENV` first so a
+ * bundler can dead-code-eliminate the guarded block in production, matching the
+ * other helpers in this file, and short-circuits when `window` is undefined so
+ * it is safe to call during server-side rendering.
+ */
+export declare function isDebug(): boolean;
+/**
+ * Warns when `value` is not one of `valid`. Covers union-type/enum property
+ * validation (e.g. `variant`, `size`).
+ *
+ * @param element - The component instance the warning is attributed to.
+ * @param check - The enum check to perform.
+ * @param check.prop - The property name, for the warning message.
+ * @param check.value - The value received.
+ * @param check.valid - The allowed values.
+ * @param check.url - Documentation URL for the component.
+ * @param check.options - Passed through to `window.__swc.warn`.
+ */
+export declare function validateEnum<T extends string>(element: HTMLElement, { prop, value, valid, url, options, }: {
+    prop: string;
+    value: string;
+    valid: readonly T[];
+    url: string;
+    options?: SWCWarningOptions;
+}): void;
+/**
+ * Warns when `condition` is true. The general-purpose validation primitive:
+ * covers required properties, conditionally required properties, mutually
+ * exclusive/no-effect property combinations, and any component-specific
+ * quirk that doesn't fit the other helpers here.
+ *
+ * @param element - The component instance the warning is attributed to.
+ * @param condition - Warn when this is true.
+ * @param message - The warning message.
+ * @param url - Documentation URL for the component.
+ * @param options - Passed through to `window.__swc.warn`.
+ */
+export declare function warnIf(element: HTMLElement, condition: boolean, message: string, url: string, options?: SWCWarningOptions): void;
+/**
+ * Warns when a slot has no assigned nodes. Covers required-slot validation.
+ *
+ * @param element - The component instance the warning is attributed to.
+ * @param slot - The slot element to check (`null`/`undefined` counts as empty).
+ * @param slotName - The slot's `name` attribute (or `"default"`), for the message.
+ * @param url - Documentation URL for the component.
+ * @param options - Passed through to `window.__swc.warn`.
+ */
+export declare function validateRequiredSlot(element: HTMLElement, slot: HTMLSlotElement | null | undefined, slotName: string, url: string, options?: SWCWarningOptions): void;
+/**
+ * Warns for each assigned element in `slot` whose tag name is not in
+ * `allowedTagNames`. Covers allowed-children slot validation (e.g. a heading
+ * slot that only accepts `<h2>`-`<h6>`).
+ *
+ * @param element - The component instance the warning is attributed to.
+ * @param slot - The slot element to check.
+ * @param allowedTagNames - Allowed tag names (case-insensitive, e.g. `['h2', 'h3']`).
+ * @param slotName - The slot's `name` attribute (or `"default"`), for the message.
+ * @param url - Documentation URL for the component.
+ * @param options - Passed through to `window.__swc.warn`.
+ */
+export declare function validateAllowedChildren(element: HTMLElement, slot: HTMLSlotElement | null | undefined, allowedTagNames: readonly string[], slotName: string, url: string, options?: SWCWarningOptions): void;

package/dist/utils/dev-validation.js

@@ -0,0 +1,33 @@
+//#region utils/dev-validation.ts
+function e(e, t, n, r) {
+	var i;
+	(i = window.__swc) != null && i.DEBUG && window.__swc.warn(e, t, n, r);
+}
+function t() {
+	var e;
+	return process.env.NODE_ENV === "production" || typeof window > "u" ? !1 : !!((e = window.__swc) != null && e.DEBUG);
+}
+function n(t, { prop: n, value: r, valid: i, url: a, options: o }) {
+	process.env.NODE_ENV !== "production" && (i.includes(r) || e(t, `<${t.localName}> expects "${n}" to be one of: ${i.join(", ")}. Received "${r}".`, a, {
+		issues: [`${n}="${r}"`],
+		...o
+	}));
+}
+function r(t, n, r, i, a) {
+	process.env.NODE_ENV !== "production" && n && e(t, r, i, a);
+}
+function i(t, n, r, i, a) {
+	process.env.NODE_ENV !== "production" && (!n || n.assignedNodes({ flatten: !0 }).length === 0) && e(t, `<${t.localName}> requires content in the "${r}" slot.`, i, a);
+}
+function a(t, n, r, i, a, o) {
+	if (process.env.NODE_ENV === "production" || !n) return;
+	let s = r.map((e) => e.toUpperCase()), c = r.map((e) => `<${e}>`).join(", ");
+	for (let r of n.assignedElements()) s.includes(r.tagName) || e(t, `<${t.localName}> "${i}" slot received a <${r.tagName.toLowerCase()}> element. Only ${c} elements are allowed.`, a, {
+		issues: [`${i} slot: <${r.tagName.toLowerCase()}>`],
+		...o
+	});
+}
+//#endregion
+export { t as isDebug, a as validateAllowedChildren, n as validateEnum, i as validateRequiredSlot, r as warnIf };
+
+//# sourceMappingURL=dev-validation.js.map

package/dist/utils/dev-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-validation.js","names":[],"sources":["../../utils/dev-validation.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * The single place \"warn in development\" lives: the `DEBUG` gate plus the\n * `window.__swc.warn` call. Every public helper below computes its own\n * predicate and message, then defers the actual emit to this primitive, so\n * there is one source of truth for how a warning is gated and dispatched.\n *\n * Note: this deliberately does **not** include the\n * `process.env.NODE_ENV === 'production'` guard. That guard must stay in each\n * public helper so a bundler can dead-code-eliminate the message construction\n * inside that function for production builds; centralizing it here would leave\n * each caller's message-building in the production bundle.\n *\n * @param element - The component instance the warning is attributed to.\n * @param message - The warning message.\n * @param url - Documentation URL for the component.\n * @param options - Passed through to `window.__swc.warn`.\n */\nfunction emitWarning(\n  element: HTMLElement,\n  message: string,\n  url: string,\n  options?: SWCWarningOptions\n): void {\n  if (!window.__swc?.DEBUG) {\n    return;\n  }\n  window.__swc.warn(element, message, url, options);\n}\n\n/**\n * Whether dev-mode validation is active: `false` in production builds and in\n * non-browser (SSR) environments, otherwise mirrors `window.__swc.DEBUG`.\n *\n * Use this to guard the *call site* of a warning whose condition or message is\n * expensive to compute (for example a DOM traversal), so that work is skipped\n * entirely when validation is off:\n *\n * ```ts\n * if (isDebug()) {\n *   this.warnAboutExpensiveThing(); // only traverses the DOM when validation runs\n * }\n * ```\n *\n * For cheap conditions, call `warnIf`/`validateEnum` directly; they already\n * gate internally. This helper exists only to avoid paying call-site argument\n * cost in the expensive cases. It checks `process.env.NODE_ENV` first so a\n * bundler can dead-code-eliminate the guarded block in production, matching the\n * other helpers in this file, and short-circuits when `window` is undefined so\n * it is safe to call during server-side rendering.\n */\nexport function isDebug(): boolean {\n  if (process.env.NODE_ENV === 'production') {\n    return false;\n  }\n  if (typeof window === 'undefined') {\n    return false;\n  }\n  return Boolean(window.__swc?.DEBUG);\n}\n\n/**\n * Warns when `value` is not one of `valid`. Covers union-type/enum property\n * validation (e.g. `variant`, `size`).\n *\n * @param element - The component instance the warning is attributed to.\n * @param check - The enum check to perform.\n * @param check.prop - The property name, for the warning message.\n * @param check.value - The value received.\n * @param check.valid - The allowed values.\n * @param check.url - Documentation URL for the component.\n * @param check.options - Passed through to `window.__swc.warn`.\n */\nexport function validateEnum<T extends string>(\n  element: HTMLElement,\n  {\n    prop,\n    value,\n    valid,\n    url,\n    options,\n  }: {\n    prop: string;\n    value: string;\n    valid: readonly T[];\n    url: string;\n    options?: SWCWarningOptions;\n  }\n): void {\n  if (process.env.NODE_ENV === 'production') {\n    return;\n  }\n  if ((valid as readonly string[]).includes(value)) {\n    return;\n  }\n  emitWarning(\n    element,\n    `<${element.localName}> expects \"${prop}\" to be one of: ${valid.join(', ')}. Received \"${value}\".`,\n    url,\n    { issues: [`${prop}=\"${value}\"`], ...options }\n  );\n}\n\n/**\n * Warns when `condition` is true. The general-purpose validation primitive:\n * covers required properties, conditionally required properties, mutually\n * exclusive/no-effect property combinations, and any component-specific\n * quirk that doesn't fit the other helpers here.\n *\n * @param element - The component instance the warning is attributed to.\n * @param condition - Warn when this is true.\n * @param message - The warning message.\n * @param url - Documentation URL for the component.\n * @param options - Passed through to `window.__swc.warn`.\n */\nexport function warnIf(\n  element: HTMLElement,\n  condition: boolean,\n  message: string,\n  url: string,\n  options?: SWCWarningOptions\n): void {\n  if (process.env.NODE_ENV === 'production') {\n    return;\n  }\n  if (!condition) {\n    return;\n  }\n  emitWarning(element, message, url, options);\n}\n\n/**\n * Warns when a slot has no assigned nodes. Covers required-slot validation.\n *\n * @param element - The component instance the warning is attributed to.\n * @param slot - The slot element to check (`null`/`undefined` counts as empty).\n * @param slotName - The slot's `name` attribute (or `\"default\"`), for the message.\n * @param url - Documentation URL for the component.\n * @param options - Passed through to `window.__swc.warn`.\n */\nexport function validateRequiredSlot(\n  element: HTMLElement,\n  slot: HTMLSlotElement | null | undefined,\n  slotName: string,\n  url: string,\n  options?: SWCWarningOptions\n): void {\n  if (process.env.NODE_ENV === 'production') {\n    return;\n  }\n  const isEmpty = !slot || slot.assignedNodes({ flatten: true }).length === 0;\n  if (!isEmpty) {\n    return;\n  }\n  emitWarning(\n    element,\n    `<${element.localName}> requires content in the \"${slotName}\" slot.`,\n    url,\n    options\n  );\n}\n\n/**\n * Warns for each assigned element in `slot` whose tag name is not in\n * `allowedTagNames`. Covers allowed-children slot validation (e.g. a heading\n * slot that only accepts `<h2>`-`<h6>`).\n *\n * @param element - The component instance the warning is attributed to.\n * @param slot - The slot element to check.\n * @param allowedTagNames - Allowed tag names (case-insensitive, e.g. `['h2', 'h3']`).\n * @param slotName - The slot's `name` attribute (or `\"default\"`), for the message.\n * @param url - Documentation URL for the component.\n * @param options - Passed through to `window.__swc.warn`.\n */\nexport function validateAllowedChildren(\n  element: HTMLElement,\n  slot: HTMLSlotElement | null | undefined,\n  allowedTagNames: readonly string[],\n  slotName: string,\n  url: string,\n  options?: SWCWarningOptions\n): void {\n  if (process.env.NODE_ENV === 'production') {\n    return;\n  }\n  if (!slot) {\n    return;\n  }\n  const allowed = allowedTagNames.map((tag) => tag.toUpperCase());\n  const allowedList = allowedTagNames.map((tag) => `<${tag}>`).join(', ');\n  for (const el of slot.assignedElements()) {\n    if (!allowed.includes(el.tagName)) {\n      emitWarning(\n        element,\n        `<${element.localName}> \"${slotName}\" slot received a <${el.tagName.toLowerCase()}> element. Only ${allowedList} elements are allowed.`,\n        url,\n        {\n          issues: [`${slotName} slot: <${el.tagName.toLowerCase()}>`],\n          ...options,\n        }\n      );\n    }\n  }\n}\n"],"mappings":";AA6BA,SAAS,EACP,GACA,GACA,GACA,GACM;;AACF,EAAA,IAAC,OAAO,UAAA,QAAA,EAAO,SAGnB,OAAO,MAAM,KAAK,GAAS,GAAS,GAAK,EAAQ;;AAwBnD,SAAgB,IAAmB;;AAOjC,QANA,QAAA,IAAA,aAA6B,gBAGzB,OAAO,SAAW,MACb,KAEF,IAAA,IAAQ,OAAO,UAAA,QAAA,EAAO;;AAe/B,SAAgB,EACd,GACA,EACE,SACA,UACA,UACA,QACA,cAQI;AACN,SAAA,IAAA,aAA6B,iBAGxB,EAA4B,SAAS,EAAM,IAGhD,EACE,GACA,IAAI,EAAQ,UAAU,aAAa,EAAK,kBAAkB,EAAM,KAAK,KAAK,CAAC,cAAc,EAAM,KAC/F,GACA;EAAE,QAAQ,CAAC,GAAG,EAAK,IAAI,EAAM,GAAG;EAAE,GAAG;EAAS,CAC/C;;AAeH,SAAgB,EACd,GACA,GACA,GACA,GACA,GACM;AACN,SAAA,IAAA,aAA6B,gBAGxB,KAGL,EAAY,GAAS,GAAS,GAAK,EAAQ;;AAY7C,SAAgB,EACd,GACA,GACA,GACA,GACA,GACM;AACN,SAAA,IAAA,aAA6B,iBAGb,CAAC,KAAQ,EAAK,cAAc,EAAE,SAAS,IAAM,CAAC,CAAC,WAAW,MAI1E,EACE,GACA,IAAI,EAAQ,UAAU,6BAA6B,EAAS,UAC5D,GACA,EACD;;AAeH,SAAgB,EACd,GACA,GACA,GACA,GACA,GACA,GACM;AAIN,KAHA,QAAA,IAAA,aAA6B,gBAGzB,CAAC,EACH;CAEF,IAAM,IAAU,EAAgB,KAAK,MAAQ,EAAI,aAAa,CAAC,EACzD,IAAc,EAAgB,KAAK,MAAQ,IAAI,EAAI,GAAG,CAAC,KAAK,KAAK;AACvE,MAAK,IAAM,KAAM,EAAK,kBAAkB,CACtC,CAAK,EAAQ,SAAS,EAAG,QAAQ,IAC/B,EACE,GACA,IAAI,EAAQ,UAAU,KAAK,EAAS,qBAAqB,EAAG,QAAQ,aAAa,CAAC,kBAAkB,EAAY,yBAChH,GACA;EACE,QAAQ,CAAC,GAAG,EAAS,UAAU,EAAG,QAAQ,aAAa,CAAC,GAAG;EAC3D,GAAG;EACJ,CACF"}

package/dist/utils/index.d.ts

@@ -12,9 +12,11 @@
 export { physicalSide } from './actual-placement.js';
 export { capitalize } from './capitalize.js';
 export { deepContains } from './deep-contains.js';
+export { isDebug, validateAllowedChildren, validateEnum, validateRequiredSlot, warnIf, } from './dev-validation.js';
 export { isTopDismissible, registerDismissible, unregisterDismissible, } from './dismissible-stack.js';
 export { getActiveElement } from './get-active-element.js';
 export { focusableSelector, tabbableSelector } from './focusable-selectors.js';
 export { getLabelFromSlot } from './get-label-from-slot.js';
+export { isFocusVisibleInTree } from './is-focus-visible-in-tree.js';
 export { resolveTrigger, type ResolvedTrigger, type ResolveTriggerOptions, } from './resolve-trigger.js';
 export { hasActiveTransition, maxTransitionDurationMs, runAfterTransition, } from './transition.js';

package/dist/utils/index.js

@@ -1,10 +1,12 @@
-import { getActiveElement as e } from "./get-active-element.js";
-import { physicalSide as t } from "./actual-placement.js";
-import { capitalize as n } from "./capitalize.js";
-import { deepContains as r } from "./deep-contains.js";
-import { isTopDismissible as i, registerDismissible as a, unregisterDismissible as o } from "./dismissible-stack.js";
-import { focusableSelector as s, tabbableSelector as c } from "./focusable-selectors.js";
-import { getLabelFromSlot as l } from "./get-label-from-slot.js";
-import { resolveTrigger as u } from "./resolve-trigger.js";
-import { hasActiveTransition as d, maxTransitionDurationMs as f, runAfterTransition as p } from "./transition.js";
-export { n as capitalize, r as deepContains, s as focusableSelector, e as getActiveElement, l as getLabelFromSlot, d as hasActiveTransition, i as isTopDismissible, f as maxTransitionDurationMs, t as physicalSide, a as registerDismissible, u as resolveTrigger, p as runAfterTransition, c as tabbableSelector, o as unregisterDismissible };
+import { physicalSide as e } from "./actual-placement.js";
+import { capitalize as t } from "./capitalize.js";
+import { deepContains as n } from "./deep-contains.js";
+import { isDebug as r, validateAllowedChildren as i, validateEnum as a, validateRequiredSlot as o, warnIf as s } from "./dev-validation.js";
+import { isTopDismissible as c, registerDismissible as l, unregisterDismissible as u } from "./dismissible-stack.js";
+import { getActiveElement as d } from "./get-active-element.js";
+import { focusableSelector as f, tabbableSelector as p } from "./focusable-selectors.js";
+import { getLabelFromSlot as m } from "./get-label-from-slot.js";
+import { isFocusVisibleInTree as h } from "./is-focus-visible-in-tree.js";
+import { resolveTrigger as g } from "./resolve-trigger.js";
+import { hasActiveTransition as _, maxTransitionDurationMs as v, runAfterTransition as y } from "./transition.js";
+export { t as capitalize, n as deepContains, f as focusableSelector, d as getActiveElement, m as getLabelFromSlot, _ as hasActiveTransition, r as isDebug, h as isFocusVisibleInTree, c as isTopDismissible, v as maxTransitionDurationMs, e as physicalSide, l as registerDismissible, g as resolveTrigger, y as runAfterTransition, p as tabbableSelector, u as unregisterDismissible, i as validateAllowedChildren, a as validateEnum, o as validateRequiredSlot, s as warnIf };

package/dist/utils/is-focus-visible-in-tree.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+/**
+ * Returns whether the deepest focused element in a tree is matched by
+ * `:focus-visible` (i.e. the platform would show a focus ring).
+ *
+ * Traverses shadow DOM boundaries via {@link getActiveElement} before testing
+ * the pseudo-class, so it reports the truly focused element rather than stopping
+ * at a shadow host.
+ *
+ * @param root - The document or shadow root to start traversal from. Pass a
+ *               component's root node (`el.getRootNode()`) to scope the check to
+ *               that tree. Defaults to `document`.
+ * @returns `true` if the active element matches `:focus-visible`, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * // Inside a component, mirror focus-visible state to a reactive property.
+ * this.focused = isFocusVisibleInTree(
+ *   this.getRootNode() as Document | ShadowRoot
+ * );
+ * ```
+ */
+export declare function isFocusVisibleInTree(root?: Document | ShadowRoot): boolean;

package/dist/utils/is-focus-visible-in-tree.js

@@ -0,0 +1,11 @@
+import { getActiveElement as e } from "./get-active-element.js";
+//#region utils/is-focus-visible-in-tree.ts
+function t(t = document) {
+	var n;
+	let r = e(t);
+	return (n = r == null ? void 0 : r.matches(":focus-visible")) == null ? !1 : n;
+}
+//#endregion
+export { t as isFocusVisibleInTree };
+
+//# sourceMappingURL=is-focus-visible-in-tree.js.map

package/dist/utils/is-focus-visible-in-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-focus-visible-in-tree.js","names":[],"sources":["../../utils/is-focus-visible-in-tree.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { getActiveElement } from './get-active-element.js';\n\n/**\n * Returns whether the deepest focused element in a tree is matched by\n * `:focus-visible` (i.e. the platform would show a focus ring).\n *\n * Traverses shadow DOM boundaries via {@link getActiveElement} before testing\n * the pseudo-class, so it reports the truly focused element rather than stopping\n * at a shadow host.\n *\n * @param root - The document or shadow root to start traversal from. Pass a\n *               component's root node (`el.getRootNode()`) to scope the check to\n *               that tree. Defaults to `document`.\n * @returns `true` if the active element matches `:focus-visible`, otherwise `false`.\n *\n * @example\n * ```typescript\n * // Inside a component, mirror focus-visible state to a reactive property.\n * this.focused = isFocusVisibleInTree(\n *   this.getRootNode() as Document | ShadowRoot\n * );\n * ```\n */\nexport function isFocusVisibleInTree(\n  root: Document | ShadowRoot = document\n): boolean {\n  const active = getActiveElement(root);\n  return active?.matches(':focus-visible') ?? false;\n}\n"],"mappings":";;AAmCA,SAAgB,EACd,IAA8B,UACrB;;CACT,IAAM,IAAS,EAAiB,EAAK;AACrC,SAAA,IAAA,KAAA,OAAA,KAAA,IAAO,EAAQ,QAAQ,iBAAiB,KAAA,OAAI,KAAJ"}

package/dist/utils/resolve-trigger.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-trigger.js","names":[],"sources":["../../utils/resolve-trigger.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Options for {@link resolveTrigger}.\n */\nexport interface ResolveTriggerOptions {\n  /** ID of the trigger element in the host's tree root. */\n  for?: string;\n  /** Direct trigger reference; overrides `for` when set. */\n  triggerElement?: HTMLElement | null;\n}\n\n/**\n * The resolved trigger and the element that should receive ARIA wiring.\n *\n * `trigger` is the element used for positioning. `interactiveElement` is the\n * AT-facing focusable element: the inner `<button>` of an open-shadow SWC\n * component when present, otherwise the trigger itself.\n */\nexport interface ResolvedTrigger {\n  trigger: HTMLElement | null;\n  interactiveElement: HTMLElement | null;\n}\n\n/**\n * Resolve the trigger for a popover-like host and discover the AT-facing inner\n * button across shadow boundaries.\n *\n * Resolution order: a direct `triggerElement` reference wins; otherwise `for`\n * is resolved by ID within the host's tree root (`getRootNode().getElementById`,\n * strictly same-root). When the resolved trigger exposes an open shadow root,\n * its inner `<button>` becomes the `interactiveElement` that receives ARIA;\n * otherwise ARIA is wired on the trigger itself.\n */\nexport function resolveTrigger(\n  host: HTMLElement,\n  options: ResolveTriggerOptions\n): ResolvedTrigger {\n  let trigger: HTMLElement | null = options.triggerElement ?? null;\n\n  if (!trigger && options.for) {\n    // `getRootNode()` returns the Document or the host's ShadowRoot; both expose\n    // `getElementById`, keeping resolution strictly within the same tree root.\n    const root = host.getRootNode() as Document | ShadowRoot;\n    trigger = root.getElementById?.(options.for) ?? null;\n  }\n\n  if (!trigger) {\n    return { trigger: null, interactiveElement: null };\n  }\n\n  // Inner-button discovery: for a 2nd-gen component trigger with an open shadow\n  // root, wire ARIA on the AT-facing inner <button>. Closed-shadow or native\n  // triggers fall back to the trigger host itself.\n  const innerButton = trigger.shadowRoot?.querySelector('button') ?? null;\n\n  return { trigger, interactiveElement: innerButton ?? trigger };\n}\n"],"mappings":";AA4CA,SAAgB,EACd,GACA,GACiB;;CACjB,IAAI,KAAA,IAA8B,EAAQ,mBAAA,OAAkB,OAAlB;AAE1C,KAAI,CAAC,KAAW,EAAQ,KAAK;;EAG3B,IAAM,IAAO,EAAK,aAAa;AAC/B,OAAA,KAAA,IAAU,EAAK,mBAAA,OAAA,KAAA,IAAA,EAAA,KAAA,GAAiB,EAAQ,IAAI,KAAA,OAAI,OAAJ;;AAG9C,KAAI,CAAC,EACH,QAAO;EAAE,SAAS;EAAM,oBAAoB;EAAM;CAMpD,IAAM,KAAA,KAAA,IAAc,EAAQ,eAAA,OAAA,KAAA,IAAA,EAAY,cAAc,SAAS,KAAA,OAAI,OAAJ;AAE/D,QAAO;EAAE;EAAS,oBAAoB,KAAA,OAAe,IAAf;EAAwB"}
+{"version":3,"file":"resolve-trigger.js","names":[],"sources":["../../utils/resolve-trigger.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Options for {@link resolveTrigger}.\n */\nexport interface ResolveTriggerOptions {\n  /** ID of the trigger element in the host's tree root. */\n  for?: string;\n  /** Direct trigger reference; overrides `for` when set. */\n  triggerElement?: HTMLElement | null;\n}\n\n/**\n * The resolved trigger and the element that should receive ARIA wiring.\n *\n * `trigger` is the element used for positioning. `interactiveElement` is the\n * AT-facing focusable element: the inner `<button>` of an open-shadow SWC\n * component when present, otherwise the trigger itself.\n */\nexport interface ResolvedTrigger {\n  trigger: HTMLElement | null;\n  interactiveElement: HTMLElement | null;\n}\n\n/**\n * Resolve the trigger for a popover-like host and discover the AT-facing inner\n * button across shadow boundaries.\n *\n * Resolution order: a direct `triggerElement` reference wins; otherwise `for`\n * is resolved by ID within the host's tree root (`getRootNode().getElementById`,\n * strictly same-root). When the resolved trigger exposes an open shadow root,\n * its inner `<button>` becomes the `interactiveElement` that receives ARIA;\n * otherwise ARIA is wired on the trigger itself.\n */\nexport function resolveTrigger(\n  host: HTMLElement,\n  options: ResolveTriggerOptions\n): ResolvedTrigger {\n  let trigger: HTMLElement | null = options.triggerElement ?? null;\n\n  if (!trigger && options.for) {\n    // `getRootNode()` returns the Document or the host's ShadowRoot; both expose\n    // `getElementById`, keeping resolution strictly within the same tree root.\n    const root = host.getRootNode() as Document | ShadowRoot;\n    trigger = root.getElementById?.(options.for) ?? null;\n  }\n\n  if (!trigger) {\n    return { trigger: null, interactiveElement: null };\n  }\n\n  // Inner-button discovery: for a gen2 component trigger with an open shadow\n  // root, wire ARIA on the AT-facing inner <button>. Closed-shadow or native\n  // triggers fall back to the trigger host itself.\n  const innerButton = trigger.shadowRoot?.querySelector('button') ?? null;\n\n  return { trigger, interactiveElement: innerButton ?? trigger };\n}\n"],"mappings":";AA4CA,SAAgB,EACd,GACA,GACiB;;CACjB,IAAI,KAAA,IAA8B,EAAQ,mBAAA,OAAkB,OAAlB;AAE1C,KAAI,CAAC,KAAW,EAAQ,KAAK;;EAG3B,IAAM,IAAO,EAAK,aAAa;AAC/B,OAAA,KAAA,IAAU,EAAK,mBAAA,OAAA,KAAA,IAAA,EAAA,KAAA,GAAiB,EAAQ,IAAI,KAAA,OAAI,OAAJ;;AAG9C,KAAI,CAAC,EACH,QAAO;EAAE,SAAS;EAAM,oBAAoB;EAAM;CAMpD,IAAM,KAAA,KAAA,IAAc,EAAQ,eAAA,OAAA,KAAA,IAAA,EAAY,cAAc,SAAS,KAAA,OAAI,OAAJ;AAE/D,QAAO;EAAE;EAAS,oBAAoB,KAAA,OAAe,IAAf;EAAwB"}