@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/esm/elements/media/audio/audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.js","names":[],"sources":["../../../../../src/elements/media/audio/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Audio element helpers.\n *\n * @remarks\n * The audio element (`<audio>`) embeds sound content in documents.\n * It can load audio via `src` or nested `<source>` elements, and it can\n * also be a destination for streamed media via MediaStream.\n *\n * Best-practice guidance (MDN + platform norms):\n * - Avoid autoplaying audio unless the user explicitly opts in.\n * - Prefer showing controls (`controls`) when audio playback is user-facing.\n * - Use `preload=\"metadata\"` as a sensible hint if you want duration, etc.\n * - Use CORS (`crossOrigin`) when audio might be reused by `<canvas>` without tainting.\n * - Prefer multiple `<source>` elements for format fallbacks where needed.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create audio elements in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Allowed `preload` values for media elements.\n *\n * @remarks\n * Per MDN, browsers treat this as a hint and may ignore it; `metadata` is a\n * common best-practice default in specs/guidance.\n *\n * @category Attributes\n */\nexport type AudioPreload = 'none' | 'metadata' | 'auto';\n\n/**\n * Allowed values for the `crossorigin` attribute for media fetches.\n *\n * @category Attributes\n */\nexport type AudioCrossOrigin = 'anonymous' | 'use-credentials';\n\n/**\n * Allowed tokens for the `controlslist` attribute (when `controls` is enabled).\n *\n * @remarks\n * MDN lists allowed values including `nodownload`, `nofullscreen`, `noremoteplayback`.\n * (`nofullscreen` is effectively video-oriented but is still a valid token in the attribute.)\n *\n * @category Attributes\n */\nexport type AudioControlsList = 'nodownload' | 'nofullscreen' | 'noremoteplayback';\n\n/**\n * The semantic tag name for audio elements.\n *\n * @category Constants\n */\nexport const AUDIO_TAG = 'audio' as const;\n\n/**\n * A CSS selector targeting audio elements.\n *\n * @category Constants\n */\nexport const AUDIO_SELECTOR = 'audio';\n\n/**\n * Attribute bag for audio creation/enhancement.\n *\n * @remarks\n * Audio elements accept HTML global attributes plus a media-specific subset.\n * pkgn-sol also supports structured ARIA input for common ARIA fields.\n *\n * @category Attributes\n */\nexport type AudioAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * The URL of the audio resource to embed.\n   *\n   * @remarks\n   * Optional if you instead provide nested `<source>` elements.\n   */\n  src?: string;\n\n  /**\n   * Whether browser playback controls should be shown.\n   */\n  controls?: boolean;\n\n  /**\n   * Whether playback should begin automatically.\n   *\n   * @remarks\n   * Autoplaying audio is often blocked unless user-initiated. If `autoplay`\n   * is enabled and `muted` is not specified, pkgn-sol defaults `muted` to `true`\n   * as a pragmatic alignment with autoplay policies.\n   */\n  autoplay?: boolean;\n\n  /**\n   * Whether the audio should loop back to the start after ending.\n   */\n  loop?: boolean;\n\n  /**\n   * Whether the audio should start out muted.\n   */\n  muted?: boolean;\n\n  /**\n   * Hint about how much to preload.\n   */\n  preload?: AudioPreload;\n\n  /**\n   * CORS mode for fetching the audio resource.\n   */\n  crossOrigin?: AudioCrossOrigin;\n\n  /**\n   * Restrict which built-in controls the user agent exposes (when `controls` is set).\n   *\n   * @example\n   * controlsList: ['nodownload', 'noremoteplayback']\n   */\n  controlsList?: AudioControlsList[];\n\n  /**\n   * Disable remote playback (Chromecast/AirPlay/etc).\n   */\n  disableRemotePlayback?: boolean;\n};\n\n/**\n * Normalize {@link AudioAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The audio attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: AudioAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, ...rest } = attrs;\n\n  if (!aria) return rest;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (typeof aria.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n  const hasMapped = Object.keys(mappedAria).length > 0;\n\n  return hasMapped ? { ...rest, aria: mappedAria } : rest;\n}\n\n/**\n * Create an audio element with optional attributes.\n *\n * @remarks\n * Global attributes are applied via pkgn-sol's shared DOM helper, including security\n * guards that block inline event handler attributes (e.g. `onclick`) and raw\n * `style` attribute strings through escape hatches.\n *\n * Media-specific attributes are applied directly to the element.\n *\n * @param attrs - Optional attributes to apply.\n * @returns The created `<audio>` element.\n *\n * @example\n * ```ts\n * import { createAudio } from \"@lnpg/pkgn-sol/elements/media/audio\";\n *\n * document.body.appendChild(\n *   createAudio({ controls: true, src: \"/audio/intro.mp3\", preload: \"metadata\" })\n * );\n * ```\n *\n * @category DOM\n */\nexport function createAudio(attrs?: AudioAttrs): ElementOf<typeof AUDIO_TAG> {\n  const el = createElement(AUDIO_TAG, toGlobalAttrs(attrs));\n\n  if (!attrs) return el;\n\n  if (typeof attrs.src === 'string') el.src = attrs.src;\n\n  if (typeof attrs.controls === 'boolean') el.controls = attrs.controls;\n\n  if (typeof attrs.autoplay === 'boolean') el.autoplay = attrs.autoplay;\n  if (typeof attrs.loop === 'boolean') el.loop = attrs.loop;\n\n  // Pragmatic autoplay alignment: if autoplay is enabled and muted is not provided,\n  // default to muted to reduce the chance of autoplay being blocked.\n  if (typeof attrs.muted === 'boolean') {\n    el.muted = attrs.muted;\n  } else if (attrs.autoplay === true) {\n    el.muted = true;\n  }\n\n  if (typeof attrs.preload === 'string') el.preload = attrs.preload;\n\n  if (typeof attrs.crossOrigin === 'string') el.crossOrigin = attrs.crossOrigin;\n\n  if (Array.isArray(attrs.controlsList) && attrs.controlsList.length > 0) {\n    // `controlslist` is a token list attribute; set as a space-separated list.\n    el.setAttribute('controlslist', attrs.controlsList.join(' '));\n  }\n\n  if (typeof attrs.disableRemotePlayback === 'boolean') {\n    if (attrs.disableRemotePlayback) el.setAttribute('disableremoteplayback', '');\n    else el.removeAttribute('disableremoteplayback');\n  }\n\n  return el;\n}\n\n/**\n * Enhance audio elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceAudios(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for audio.\n  void root;\n}\n"],"mappings":";;;;;;;IA2Fa,IAAY,SAOZ,IAAiB;AAkF9B,SAAS,EAAc,GAA6C;CAClE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,GAAG,MAAS;CAE1B,IAAI,CAAC,GAAM,OAAO;CAElB,IAAM,IAA+C,EAAE;CAQvD,OANI,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,SAE7C,OAAO,KAAK,EAAW,CAAC,SAAS,IAEhC;EAAE,GAAG;EAAM,MAAM;EAAY,GAAG;;AA2BrD,SAAgB,EAAY,GAAiD;CAC3E,IAAM,IAAK,EAAc,GAAW,EAAc,EAAM,CAAC;CAiCzD,OA/BK,KAED,OAAO,EAAM,OAAQ,aAAU,EAAG,MAAM,EAAM,MAE9C,OAAO,EAAM,YAAa,cAAW,EAAG,WAAW,EAAM,WAEzD,OAAO,EAAM,YAAa,cAAW,EAAG,WAAW,EAAM,WACzD,OAAO,EAAM,QAAS,cAAW,EAAG,OAAO,EAAM,OAIjD,OAAO,EAAM,SAAU,YACzB,EAAG,QAAQ,EAAM,QACR,EAAM,aAAa,OAC5B,EAAG,QAAQ,KAGT,OAAO,EAAM,WAAY,aAAU,EAAG,UAAU,EAAM,UAEtD,OAAO,EAAM,eAAgB,aAAU,EAAG,cAAc,EAAM,cAE9D,MAAM,QAAQ,EAAM,aAAa,IAAI,EAAM,aAAa,SAAS,KAEnE,EAAG,aAAa,gBAAgB,EAAM,aAAa,KAAK,IAAI,CAAC,EAG3D,OAAO,EAAM,yBAA0B,cACrC,EAAM,wBAAuB,EAAG,aAAa,yBAAyB,GAAG,GACxE,EAAG,gBAAgB,wBAAwB,GAG3C,KA/BY;;AAoDrB,SAAgB,EAAc,IAAmB,UAAgB"}

package/dist/esm/elements/media/canvas/canvas.js

@@ -0,0 +1,21 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/media/canvas/index.ts
+var n = /* @__PURE__ */ e({
+	CANVAS_SELECTOR: () => i,
+	CANVAS_TAG: () => r,
+	createCanvas: () => o,
+	enhanceCanvases: () => s
+}), r = "canvas", i = "canvas";
+function a(e) {
+	if (!e) return;
+	let { aria: t, width: n, height: r, ...i } = e, a = { ...i }, o = {};
+	return typeof t?.label == "string" && (o.label = t.label), typeof t?.labelledby == "string" && (o.labelledby = t.labelledby), typeof t?.hidden == "boolean" && (o.hidden = t.hidden), Object.keys(o).length > 0 && (a.aria = o), (typeof n == "number" || typeof r == "number") && (a.attrs = { ...a.attrs ?? {} }, typeof n == "number" && (a.attrs.width = n), typeof r == "number" && (a.attrs.height = r)), a;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as CANVAS_SELECTOR, r as CANVAS_TAG, o as createCanvas, s as enhanceCanvases, n as t };
+
+//# sourceMappingURL=canvas.js.map

package/dist/esm/elements/media/canvas/canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.js","names":[],"sources":["../../../../../src/elements/media/canvas/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Canvas element helpers.\n *\n * @remarks\n * The canvas element (`<canvas>`) provides a scriptable drawing surface.\n *\n * Best-practice guidance:\n * - Prefer setting `width` and `height` attributes (not only CSS sizing) to avoid\n *   rendering distortion from bitmap scaling.\n * - Provide meaningful fallback content where appropriate (e.g. a short text\n *   alternative) as the canvas element can represent its fallback content in\n *   non-visual/unsupported contexts.\n * - If the canvas conveys information, ensure it is labeled accessibly (e.g.\n *   via `aria-label` / `aria-labelledby`) and that equivalent information is\n *   available outside the canvas where needed.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create canvas elements in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs (e.g. `lable`).\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for canvas.\n *\n * @category Constants\n */\nexport const CANVAS_TAG = 'canvas' as const;\n\n/**\n * A CSS selector targeting canvas elements.\n *\n * @category Constants\n */\nexport const CANVAS_SELECTOR = 'canvas';\n\n/**\n * Attribute bag for canvas creation/enhancement.\n *\n * @remarks\n * Canvas supports:\n * - standard HTML global attributes\n * - `width` and `height` attributes for bitmap sizing\n * - structured ARIA input mapped into `aria-*`\n *\n * @category Attributes\n */\nexport type CanvasAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Bitmap width (in CSS pixels) for the canvas drawing surface.\n   *\n   * @remarks\n   * Prefer this over CSS-only sizing to avoid scaling distortion.\n   */\n  width?: number;\n\n  /**\n   * Bitmap height (in CSS pixels) for the canvas drawing surface.\n   *\n   * @remarks\n   * Prefer this over CSS-only sizing to avoid scaling distortion.\n   */\n  height?: number;\n};\n\n/**\n * Normalize {@link CanvasAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The canvas attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: CanvasAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, width, height, ...rest } = attrs;\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (typeof aria?.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria?.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n  if (typeof aria?.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n  if (Object.keys(mappedAria).length > 0) mapped.aria = mappedAria;\n\n  // Canvas-specific attributes are routed via the safe attrs escape hatch.\n  if (typeof width === 'number' || typeof height === 'number') {\n    mapped.attrs = { ...(mapped.attrs ?? {}) };\n\n    if (typeof width === 'number') mapped.attrs.width = width;\n    if (typeof height === 'number') mapped.attrs.height = height;\n  }\n\n  return mapped;\n}\n\n/**\n * Create a canvas element with optional fallback text content and attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - `width` and `height` (if provided) are applied as attributes via the safe\n *   attribute path in `dom.ts`.\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional fallback text content for the canvas.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<canvas>` element.\n *\n * @example\n * Create a 300x150 canvas with a label:\n * ```ts\n * import { createCanvas } from \"@lnpg/pkgn-sol/elements/media/canvas\";\n *\n * const el = createCanvas(undefined, {\n *   width: 300,\n *   height: 150,\n *   aria: { label: \"Sparkline chart\" },\n * });\n * ```\n *\n * @category DOM\n */\nexport function createCanvas(text?: string, attrs?: CanvasAttrs): ElementOf<typeof CANVAS_TAG> {\n  return createElement(CANVAS_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance canvas elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceCanvases(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for canvas.\n  void root;\n}\n"],"mappings":";;;;;;;IA+Da,IAAa,UAOb,IAAkB;AA4C/B,SAAS,EAAc,GAA8C;CACnE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,UAAO,WAAQ,GAAG,MAAS,GAEnC,IAAsB,EAAE,GAAG,GAAM,EAEjC,IAA+C,EAAE;CAevD,OAdI,OAAO,GAAM,SAAU,aAAU,EAAW,QAAQ,EAAK,QACzD,OAAO,GAAM,cAAe,aAAU,EAAW,aAAa,EAAK,aACnE,OAAO,GAAM,UAAW,cAAW,EAAW,SAAS,EAAK,SAE5D,OAAO,KAAK,EAAW,CAAC,SAAS,MAAG,EAAO,OAAO,KAGlD,OAAO,KAAU,YAAY,OAAO,KAAW,cACjD,EAAO,QAAQ,EAAE,GAAI,EAAO,SAAS,EAAE,EAAG,EAEtC,OAAO,KAAU,aAAU,EAAO,MAAM,QAAQ,IAChD,OAAO,KAAW,aAAU,EAAO,MAAM,SAAS,KAGjD;;AAgCT,SAAgB,EAAa,GAAe,GAAmD;CAC7F,OAAO,EAAc,GAAY,EAAc,EAAM,EAAE,EAAK;;AAqB9D,SAAgB,EAAgB,IAAmB,UAAgB"}

package/dist/esm/elements/media/embed/embed.js

@@ -0,0 +1,44 @@
+import { i as e, r as t } from "../../../chunks/dom.js";
+//#region src/elements/media/embed/index.ts
+var n = /* @__PURE__ */ e({
+	EMBED_SELECTOR: () => i,
+	EMBED_TAG: () => r,
+	createEmbed: () => s,
+	enhanceEmbeds: () => c
+}), r = "embed", i = "embed";
+function a(e, t) {
+	if (e == null) return;
+	if (typeof e == "number") {
+		if (!Number.isFinite(e) || e < 0) throw Error(`Invalid ${t}: must be a finite, non-negative number.`);
+		return String(Math.floor(e));
+	}
+	let n = String(e).trim();
+	if (n.length !== 0) {
+		if (n.includes("%")) throw Error(`Invalid ${t}: percentages are not allowed for <embed> ${t}.`);
+		if (!/^\d+$/.test(n)) throw Error(`Invalid ${t}: must be a non-negative integer (CSS pixels).`);
+		return n;
+	}
+}
+function o(e) {
+	if (!e) return;
+	let { aria: t, src: n, type: r, width: i, height: o, attrs: s, ...c } = e, l = t ? (() => {
+		let e = {};
+		return typeof t.label == "string" && (e.label = t.label), typeof t.labelledby == "string" && (e.labelledby = t.labelledby), typeof t.hidden == "boolean" && (e.hidden = t.hidden), Object.keys(e).length > 0 ? e : void 0;
+	})() : void 0, u = a(i, "width"), d = a(o, "height"), f = (() => {
+		let e = { ...s ?? {} };
+		return typeof n == "string" && n.length > 0 && (e.src = n), typeof r == "string" && r.length > 0 && (e.type = r), typeof u == "string" && (e.width = u), typeof d == "string" && (e.height = d), Object.keys(e).length > 0 ? e : void 0;
+	})();
+	return {
+		...c,
+		...l ? { aria: l } : null,
+		...f ? { attrs: f } : null
+	};
+}
+function s(e) {
+	return t(r, o(e));
+}
+function c(e = document) {}
+//#endregion
+export { i as EMBED_SELECTOR, r as EMBED_TAG, s as createEmbed, c as enhanceEmbeds, n as t };
+
+//# sourceMappingURL=embed.js.map

package/dist/esm/elements/media/embed/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","names":[],"sources":["../../../../../src/elements/media/embed/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Embed element helpers.\n *\n * @remarks\n * The embed element (`<embed>`) embeds external content at a point in the\n * document. Historically this was often browser plug-ins; modern browsers have\n * largely removed plug-in support, so relying on `<embed>` is frequently a poor\n * choice for general-purpose sites. Prefer purpose-built elements when possible\n * (e.g. `<img>`, `<video>`, `<audio>`, `<iframe>`, or `<object>` depending on the use case).\n *\n * Best-practice guidance:\n * - Prefer native elements over `<embed>` when there is a semantic alternative.\n * - Use the `title` attribute to label embedded content for assistive technology.\n * - `width`/`height` should be absolute pixel values (no percentages).\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create embed nodes in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport {\n  createVoidElement,\n  type AttrValue,\n  type ElementOf,\n  type GlobalAttrs,\n} from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for embed.\n *\n * @category Constants\n */\nexport const EMBED_TAG = 'embed' as const;\n\n/**\n * A CSS selector targeting embed elements.\n *\n * @category Constants\n */\nexport const EMBED_SELECTOR = 'embed';\n\n/**\n * Attribute bag for embed creation/enhancement.\n *\n * @remarks\n * `<embed>` supports global attributes plus:\n * - `src` (URL)\n * - `type` (MIME type)\n * - `width` / `height` (absolute pixel values; percentages are invalid)\n *\n * Accessibility:\n * - Provide a `title` (global attribute) to label the embedded content.\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, mapped into\n * `aria-*` attributes.\n *\n * @category Attributes\n */\nexport type EmbedAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * URL of the resource being embedded.\n   */\n  src?: string;\n\n  /**\n   * MIME type used to select the appropriate handler.\n   */\n  type?: string;\n\n  /**\n   * Displayed width in CSS pixels (absolute; percentages are not allowed).\n   */\n  width?: number | string;\n\n  /**\n   * Displayed height in CSS pixels (absolute; percentages are not allowed).\n   */\n  height?: number | string;\n\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Normalize an HTML dimension attribute value.\n *\n * @remarks\n * MDN notes `width`/`height` must be absolute values (percentages are invalid).\n * HTML attribute values for these are effectively numeric pixel counts.\n *\n * @param v - The provided dimension.\n * @param name - Attribute name for error messages.\n * @returns A stringified non-negative integer, or `undefined` if not provided.\n *\n * @category Internal\n */\nfunction normalizeDim(v: EmbedAttrs['width'], name: 'width' | 'height'): string | undefined {\n  if (v === undefined || v === null) return undefined;\n\n  if (typeof v === 'number') {\n    if (!Number.isFinite(v) || v < 0) {\n      throw new Error(`Invalid ${name}: must be a finite, non-negative number.`);\n    }\n    // HTML width/height attributes are integer-like; normalize safely.\n    return String(Math.floor(v));\n  }\n\n  const s = String(v).trim();\n\n  if (s.length === 0) return undefined;\n\n  if (s.includes('%')) {\n    throw new Error(`Invalid ${name}: percentages are not allowed for <embed> ${name}.`);\n  }\n\n  if (!/^\\d+$/.test(s)) {\n    throw new Error(`Invalid ${name}: must be a non-negative integer (CSS pixels).`);\n  }\n\n  return s;\n}\n\n/**\n * Normalize {@link EmbedAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The embed attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: EmbedAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, src, type, width, height, attrs: extraAttrs, ...rest } = attrs;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> | undefined = aria\n    ? (() => {\n        const a: NonNullable<GlobalAttrs['aria']> = {};\n        if (typeof aria.label === 'string') a.label = aria.label;\n        if (typeof aria.labelledby === 'string') a.labelledby = aria.labelledby;\n        if (typeof aria.hidden === 'boolean') a.hidden = aria.hidden;\n        return Object.keys(a).length > 0 ? a : undefined;\n      })()\n    : undefined;\n\n  const w = normalizeDim(width, 'width');\n  const h = normalizeDim(height, 'height');\n\n  const mergedAttrs: Record<string, AttrValue> | undefined = (() => {\n    const a: Record<string, AttrValue> = { ...(extraAttrs ?? {}) };\n\n    if (typeof src === 'string' && src.length > 0) a.src = src;\n    if (typeof type === 'string' && type.length > 0) a.type = type;\n\n    if (typeof w === 'string') a.width = w;\n    if (typeof h === 'string') a.height = h;\n\n    return Object.keys(a).length > 0 ? a : undefined;\n  })();\n\n  const mapped: GlobalAttrs = {\n    ...rest,\n    ...(mappedAria ? { aria: mappedAria } : null),\n    ...(mergedAttrs ? { attrs: mergedAttrs } : null),\n  };\n\n  return mapped;\n}\n\n/**\n * Create an embed element and apply attributes.\n *\n * @remarks\n * Global attributes are applied via pkgn-sol's shared DOM helper, including security\n * guards that block inline event handler attributes (e.g. `onclick`) and raw\n * `style` attribute strings.\n *\n * @param attrs - Optional attributes to apply.\n * @returns The created `<embed>` element.\n *\n * @example\n * ```ts\n * import { createEmbed } from \"@lnpg/pkgn-sol/elements/media/embed\";\n *\n * document.body.appendChild(\n *   createEmbed({ src: \"/files/manual.pdf\", type: \"application/pdf\", title: \"User manual\" })\n * );\n * ```\n *\n * @category DOM\n */\nexport function createEmbed(attrs?: EmbedAttrs): ElementOf<typeof EMBED_TAG> {\n  return createVoidElement(EMBED_TAG, toGlobalAttrs(attrs));\n}\n\n/**\n * Enhance embed elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceEmbeds(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for embed.\n  void root;\n}\n"],"mappings":";;;;;;;IAmEa,IAAY,SAOZ,IAAiB;AA2D9B,SAAS,EAAa,GAAwB,GAA8C;CAC1F,IAAI,KAAyB,MAAM;CAEnC,IAAI,OAAO,KAAM,UAAU;EACzB,IAAI,CAAC,OAAO,SAAS,EAAE,IAAI,IAAI,GAC7B,MAAU,MAAM,WAAW,EAAK,0CAA0C;EAG5E,OAAO,OAAO,KAAK,MAAM,EAAE,CAAC;;CAG9B,IAAM,IAAI,OAAO,EAAE,CAAC,MAAM;CAEtB,MAAE,WAAW,GAEjB;MAAI,EAAE,SAAS,IAAI,EACjB,MAAU,MAAM,WAAW,EAAK,4CAA4C,EAAK,GAAG;EAGtF,IAAI,CAAC,QAAQ,KAAK,EAAE,EAClB,MAAU,MAAM,WAAW,EAAK,gDAAgD;EAGlF,OAAO;;;AAWT,SAAS,EAAc,GAA6C;CAClE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,QAAK,SAAM,UAAO,WAAQ,OAAO,GAAY,GAAG,MAAS,GAEjE,IAA2D,WACtD;EACL,IAAM,IAAsC,EAAE;EAI9C,OAHI,OAAO,EAAK,SAAU,aAAU,EAAE,QAAQ,EAAK,QAC/C,OAAO,EAAK,cAAe,aAAU,EAAE,aAAa,EAAK,aACzD,OAAO,EAAK,UAAW,cAAW,EAAE,SAAS,EAAK,SAC/C,OAAO,KAAK,EAAE,CAAC,SAAS,IAAI,IAAI,KAAA;KACrC,GACJ,KAAA,GAEE,IAAI,EAAa,GAAO,QAAQ,EAChC,IAAI,EAAa,GAAQ,SAAS,EAElC,WAA4D;EAChE,IAAM,IAA+B,EAAE,GAAI,KAAc,EAAE,EAAG;EAQ9D,OANI,OAAO,KAAQ,YAAY,EAAI,SAAS,MAAG,EAAE,MAAM,IACnD,OAAO,KAAS,YAAY,EAAK,SAAS,MAAG,EAAE,OAAO,IAEtD,OAAO,KAAM,aAAU,EAAE,QAAQ,IACjC,OAAO,KAAM,aAAU,EAAE,SAAS,IAE/B,OAAO,KAAK,EAAE,CAAC,SAAS,IAAI,IAAI,KAAA;KACrC;CAQJ,OAAO;EALL,GAAG;EACH,GAAI,IAAa,EAAE,MAAM,GAAY,GAAG;EACxC,GAAI,IAAc,EAAE,OAAO,GAAa,GAAG;EAGtC;;AAyBT,SAAgB,EAAY,GAAiD;CAC3E,OAAO,EAAkB,GAAW,EAAc,EAAM,CAAC;;AAa3D,SAAgB,EAAc,IAAmB,UAAgB"}

package/dist/esm/elements/media/iframe/iframe.js

@@ -0,0 +1,27 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/media/iframe/index.ts
+var n = /* @__PURE__ */ e({
+	IFRAME_SELECTOR: () => i,
+	IFRAME_TAG: () => r,
+	createIFrame: () => o,
+	enhanceIFrames: () => s
+}), r = "iframe", i = "iframe";
+function a(e) {
+	if (!e) return;
+	let { aria: t, src: n, srcdoc: r, name: i, sandbox: a, allow: o, allowFullScreen: s, loading: c, referrerPolicy: l, width: u, height: d, fetchPriority: f, csp: p, credentialless: m, ...h } = e, g = { ...h.attrs ?? {} }, _ = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(g, e) || (g[e] = t));
+	};
+	_("src", n), _("srcdoc", r), _("name", i), _("sandbox", a), _("allow", o), _("loading", c), _("referrerpolicy", l), _("width", u), _("height", d), _("fetchpriority", f), _("csp", p), s === !0 && _("allowfullscreen", ""), m === !0 && _("credentialless", "");
+	let v = {};
+	t && (typeof t.label == "string" && (v.label = t.label), typeof t.labelledby == "string" && (v.labelledby = t.labelledby), typeof t.hidden == "boolean" && (v.hidden = t.hidden));
+	let y = Object.keys(v).length > 0, b = Object.keys(g).length > 0, x = { ...h };
+	return b && (x.attrs = g), y && (x.aria = v), x;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as IFRAME_SELECTOR, r as IFRAME_TAG, o as createIFrame, s as enhanceIFrames, n as t };
+
+//# sourceMappingURL=iframe.js.map

package/dist/esm/elements/media/iframe/iframe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iframe.js","names":[],"sources":["../../../../../src/elements/media/iframe/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: IFrame element helpers.\n *\n * @remarks\n * The iframe element (`<iframe>`) embeds another HTML page into the current page.\n *\n * Best-practice guidance:\n * - Prefer `<iframe>` only when you truly need third-party or isolated documents.\n * - Consider `loading=\"lazy\"` for non-critical iframes to reduce initial load cost.\n * - Use `sandbox` with the least permissions possible when embedding untrusted content.\n * - Prefer restrictive `referrerpolicy` when embedding third-party content.\n * - Provide a meaningful `title` for accessibility (screen readers use it to identify the frame).\n * - Avoid obsolete attributes like `frameborder`; use CSS instead.\n *\n * Security notes:\n * - `srcdoc` embeds HTML directly. pkgn-sol does not sanitize or validate it.\n *   If you build `srcdoc` from untrusted input, that is on you (and your incident report).\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create iframes in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs, type AttrValue } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for iframe embeds.\n *\n * @category Constants\n */\nexport const IFRAME_TAG = 'iframe' as const;\n\n/**\n * A CSS selector targeting iframe elements.\n *\n * @category Constants\n */\nexport const IFRAME_SELECTOR = 'iframe';\n\n/**\n * Allowed values for the iframe `loading` attribute.\n *\n * @category Types\n */\nexport type IFrameLoading = 'eager' | 'lazy';\n\n/**\n * Allowed values for the iframe `referrerpolicy` attribute.\n *\n * @category Types\n */\nexport type IFrameReferrerPolicy =\n  | 'no-referrer'\n  | 'no-referrer-when-downgrade'\n  | 'origin'\n  | 'origin-when-cross-origin'\n  | 'same-origin'\n  | 'strict-origin'\n  | 'strict-origin-when-cross-origin'\n  | 'unsafe-url';\n\n/**\n * Allowed values for the `fetchpriority` attribute.\n *\n * @category Types\n */\nexport type FetchPriority = 'high' | 'low' | 'auto';\n\n/**\n * Attribute bag for iframe creation/enhancement.\n *\n * @remarks\n * Iframes accept standard HTML global attributes plus iframe-specific attributes.\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type IFrameAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Address of the document to embed.\n   */\n  src?: string;\n\n  /**\n   * Inline HTML to render within the iframe.\n   *\n   * @remarks\n   * pkgn-sol does not sanitize `srcdoc`.\n   */\n  srcdoc?: string;\n\n  /**\n   * A name for the browsing context.\n   */\n  name?: string;\n\n  /**\n   * A space-separated list of sandbox tokens.\n   *\n   * @remarks\n   * Use the least permissive sandbox you can.\n   */\n  sandbox?: string;\n\n  /**\n   * Permissions policy for the iframe (previously \"feature policy\").\n   *\n   * @remarks\n   * Example: `allow=\"fullscreen; geolocation 'none'\"`.\n   */\n  allow?: string;\n\n  /**\n   * Whether fullscreen is allowed.\n   *\n   * @remarks\n   * Mirrors the `allowfullscreen` boolean attribute.\n   */\n  allowFullScreen?: boolean;\n\n  /**\n   * Whether the iframe should be loaded lazily or eagerly.\n   */\n  loading?: IFrameLoading;\n\n  /**\n   * Referrer policy for requests made by the iframe.\n   */\n  referrerPolicy?: IFrameReferrerPolicy;\n\n  /**\n   * Display width, in CSS pixels.\n   */\n  width?: number | string;\n\n  /**\n   * Display height, in CSS pixels.\n   */\n  height?: number | string;\n\n  /**\n   * Fetch priority hint.\n   */\n  fetchPriority?: FetchPriority;\n\n  /**\n   * Content Security Policy to apply to the embedded document.\n   *\n   * @remarks\n   * Support varies by browser and context.\n   */\n  csp?: string;\n\n  /**\n   * Whether to use a credentialless iframe (privacy-oriented isolation).\n   *\n   * @remarks\n   * Mirrors the `credentialless` boolean attribute where supported.\n   */\n  credentialless?: boolean;\n};\n\n/**\n * Normalize {@link IFrameAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The iframe attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: IFrameAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const {\n    aria,\n    src,\n    srcdoc,\n    name,\n    sandbox,\n    allow,\n    allowFullScreen,\n    loading,\n    referrerPolicy,\n    width,\n    height,\n    fetchPriority,\n    csp,\n    credentialless,\n    ...rest\n  } = attrs;\n\n  // Start with any caller-provided attrs escape hatch (it is still validated by dom.ts).\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  // Helper: only set if caller didn't already set the raw attribute explicitly.\n  const setIfUnset = (key: string, value: AttrValue | undefined): void => {\n    if (value === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = value;\n  };\n\n  setIfUnset('src', src);\n  setIfUnset('srcdoc', srcdoc);\n  setIfUnset('name', name);\n  setIfUnset('sandbox', sandbox);\n  setIfUnset('allow', allow);\n  setIfUnset('loading', loading);\n  setIfUnset('referrerpolicy', referrerPolicy);\n  setIfUnset('width', width);\n  setIfUnset('height', height);\n  setIfUnset('fetchpriority', fetchPriority);\n  setIfUnset('csp', csp);\n\n  // Boolean attributes are represented by presence. We set empty-string when true.\n  if (allowFullScreen === true) setIfUnset('allowfullscreen', '');\n  if (credentialless === true) setIfUnset('credentialless', '');\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;\n\n  const next: GlobalAttrs = { ...rest };\n  if (hasMergedAttrs) next.attrs = mergedAttrs;\n  if (hasMappedAria) next.aria = mappedAria;\n\n  return next;\n}\n\n/**\n * Create an iframe element with optional fallback text and attributes.\n *\n * @remarks\n * - Fallback text is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional fallback text content for the iframe (rarely used, but valid).\n * @param attrs - Optional attributes to apply.\n * @returns The created `<iframe>` element.\n *\n * @example\n * ```ts\n * import { createIFrame } from \"@lnpg/pkgn-sol/elements/media/iframe\";\n *\n * document.body.appendChild(\n *   createIFrame(undefined, {\n *     title: \"Embedded map\",\n *     src: \"https://example.com/map\",\n *     loading: \"lazy\",\n *     sandbox: \"allow-scripts allow-same-origin\"\n *   })\n * );\n * ```\n *\n * @category DOM\n */\nexport function createIFrame(text?: string, attrs?: IFrameAttrs): ElementOf<typeof IFRAME_TAG> {\n  return createElement(IFRAME_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance iframe elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceIFrames(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for iframe.\n  void root;\n}\n"],"mappings":";;;;;;;IAiEa,IAAa,UAOb,IAAkB;AA4I/B,SAAS,EAAc,GAA8C;CACnE,IAAI,CAAC,GAAO;CAEZ,IAAM,EACJ,SACA,QACA,WACA,SACA,YACA,UACA,oBACA,YACA,mBACA,UACA,WACA,kBACA,QACA,mBACA,GAAG,MACD,GAGE,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAGlE,KAAc,GAAa,MAAuC;EAClE,MAAU,KAAA,MACV,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;;CAiBrB,AAdA,EAAW,OAAO,EAAI,EACtB,EAAW,UAAU,EAAO,EAC5B,EAAW,QAAQ,EAAK,EACxB,EAAW,WAAW,EAAQ,EAC9B,EAAW,SAAS,EAAM,EAC1B,EAAW,WAAW,EAAQ,EAC9B,EAAW,kBAAkB,EAAe,EAC5C,EAAW,SAAS,EAAM,EAC1B,EAAW,UAAU,EAAO,EAC5B,EAAW,iBAAiB,EAAc,EAC1C,EAAW,OAAO,EAAI,EAGlB,MAAoB,MAAM,EAAW,mBAAmB,GAAG,EAC3D,MAAmB,MAAM,EAAW,kBAAkB,GAAG;CAE7D,IAAM,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAgB,OAAO,KAAK,EAAW,CAAC,SAAS,GACjD,IAAiB,OAAO,KAAK,EAAY,CAAC,SAAS,GAEnD,IAAoB,EAAE,GAAG,GAAM;CAIrC,OAHI,MAAgB,EAAK,QAAQ,IAC7B,MAAe,EAAK,OAAO,IAExB;;AAgCT,SAAgB,EAAa,GAAe,GAAmD;CAC7F,OAAO,EAAc,GAAY,EAAc,EAAM,EAAE,EAAK;;AAqB9D,SAAgB,EAAe,IAAmB,UAAgB"}

package/dist/esm/elements/media/img/img.js

@@ -0,0 +1,25 @@
+import { i as e, r as t } from "../../../chunks/dom.js";
+//#region src/elements/media/img/index.ts
+var n = /* @__PURE__ */ e({
+	IMG_SELECTOR: () => "img",
+	IMG_TAG: () => "img",
+	createImg: () => o,
+	enhanceImgs: () => s
+}), r = "img", i = "img";
+function a(e) {
+	let { aria: t, alt: n, src: r, srcset: i, sizes: a, width: o, height: s, loading: c, decoding: l, referrerPolicy: u, ...d } = e ?? {}, f = { ...d }, p = {};
+	t && (typeof t.label == "string" && (p.label = t.label), typeof t.labelledby == "string" && (p.labelledby = t.labelledby), typeof t.hidden == "boolean" && (p.hidden = t.hidden)), Object.keys(p).length > 0 && (f.aria = p), f.attrs = {
+		...f.attrs ?? {},
+		alt: typeof n == "string" ? n : ""
+	};
+	let m = typeof r == "string" && r.length > 0, h = typeof i == "string" && i.length > 0;
+	return m && (f.attrs.src = r), h && (f.attrs.srcset = i), a && (f.attrs.sizes = a), typeof o == "number" && (f.attrs.width = o), typeof s == "number" && (f.attrs.height = s), c && (f.attrs.loading = c), l && (f.attrs.decoding = l), u && (f.attrs.referrerpolicy = u), !m && !h && (f.attrs.src = "data:,"), f;
+}
+function o(e) {
+	return t("img", a(e));
+}
+function s(e = document) {}
+//#endregion
+export { i as IMG_SELECTOR, r as IMG_TAG, o as createImg, s as enhanceImgs, n as t };
+
+//# sourceMappingURL=img.js.map

package/dist/esm/elements/media/img/img.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"img.js","names":[],"sources":["../../../../../src/elements/media/img/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Img element helpers.\n *\n * @remarks\n * The img element (`<img>`) embeds an image into the document.\n *\n * Best-practice guidance:\n * - The `alt` attribute must always be present.\n * - Use `alt=\"\"` for purely decorative images.\n * - Provide meaningful alternative text for informative images.\n * - Do not rely on images alone to convey critical information.\n *\n * This module enforces:\n * - `alt` always exists (defaults to empty string if not provided)\n * - If neither `src` nor `srcset` is provided, a safe fallback\n *   `src=\"data:,\"` is applied to avoid broken network requests\n * - All global attributes are applied via pkgn-sol's hardened DOM helpers\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createVoidElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  label?: string;\n  labelledby?: string;\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for images.\n *\n * @category Constants\n */\nexport const IMG_TAG = 'img' as const;\n\n/**\n * A CSS selector targeting img elements.\n *\n * @category Constants\n */\nexport const IMG_SELECTOR = 'img';\n\n/**\n * Img-specific attributes.\n *\n * @remarks\n * `alt` is mandatory per HTML specification.\n *\n * @category Attributes\n */\nexport type ImgAttrs = Omit<GlobalAttrs, 'aria'> & {\n  alt?: string;\n  src?: string;\n  srcset?: string;\n  sizes?: string;\n  width?: number;\n  height?: number;\n  loading?: 'lazy' | 'eager';\n  decoding?: 'sync' | 'async' | 'auto';\n  referrerPolicy?: string;\n  aria?: StructuredAria;\n};\n\nfunction toGlobalAttrs(attrs?: ImgAttrs): GlobalAttrs {\n  const {\n    aria,\n    alt,\n    src,\n    srcset,\n    sizes,\n    width,\n    height,\n    loading,\n    decoding,\n    referrerPolicy,\n    ...rest\n  } = attrs ?? {};\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  if (Object.keys(mappedAria).length > 0) {\n    mapped.aria = mappedAria;\n  }\n\n  mapped.attrs = {\n    ...(mapped.attrs ?? {}),\n    alt: typeof alt === 'string' ? alt : '',\n  };\n\n  const hasSrc = typeof src === 'string' && src.length > 0;\n  const hasSrcset = typeof srcset === 'string' && srcset.length > 0;\n\n  if (hasSrc) mapped.attrs.src = src;\n  if (hasSrcset) mapped.attrs.srcset = srcset;\n  if (sizes) mapped.attrs.sizes = sizes;\n  if (typeof width === 'number') mapped.attrs.width = width;\n  if (typeof height === 'number') mapped.attrs.height = height;\n  if (loading) mapped.attrs.loading = loading;\n  if (decoding) mapped.attrs.decoding = decoding;\n  if (referrerPolicy) mapped.attrs.referrerpolicy = referrerPolicy;\n\n  if (!hasSrc && !hasSrcset) {\n    mapped.attrs.src = 'data:,';\n  }\n\n  return mapped;\n}\n\n/**\n * Create an img element with enforced accessibility safeguards.\n *\n * @category DOM\n */\nexport function createImg(attrs?: ImgAttrs): ElementOf<typeof IMG_TAG> {\n  return createVoidElement(IMG_TAG, toGlobalAttrs(attrs));\n}\n\n/**\n * Enhance img elements within a given root.\n *\n * @remarks\n * No runtime behaviour in v0.1.0.\n *\n * @category Enhancement\n */\nexport function enhanceImgs(root: ParentNode = document): void {\n  void root;\n}\n"],"mappings":";;;;;;;IA2Ca,IAAU,OAOV,IAAe;AAuB5B,SAAS,EAAc,GAA+B;CACpD,IAAM,EACJ,SACA,QACA,QACA,WACA,UACA,UACA,WACA,YACA,aACA,mBACA,GAAG,MACD,KAAS,EAAE,EAET,IAAsB,EAAE,GAAG,GAAM,EAEjC,IAA+C,EAAE;CAYvD,AAVI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,UAG7D,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAO,OAAO,IAGhB,EAAO,QAAQ;EACb,GAAI,EAAO,SAAS,EAAE;EACtB,KAAK,OAAO,KAAQ,WAAW,IAAM;EACtC;CAED,IAAM,IAAS,OAAO,KAAQ,YAAY,EAAI,SAAS,GACjD,IAAY,OAAO,KAAW,YAAY,EAAO,SAAS;CAehE,OAbI,MAAQ,EAAO,MAAM,MAAM,IAC3B,MAAW,EAAO,MAAM,SAAS,IACjC,MAAO,EAAO,MAAM,QAAQ,IAC5B,OAAO,KAAU,aAAU,EAAO,MAAM,QAAQ,IAChD,OAAO,KAAW,aAAU,EAAO,MAAM,SAAS,IAClD,MAAS,EAAO,MAAM,UAAU,IAChC,MAAU,EAAO,MAAM,WAAW,IAClC,MAAgB,EAAO,MAAM,iBAAiB,IAE9C,CAAC,KAAU,CAAC,MACd,EAAO,MAAM,MAAM,WAGd;;AAQT,SAAgB,EAAU,GAA6C;CACrE,OAAO,EAAA,OAA2B,EAAc,EAAM,CAAC;;AAWzD,SAAgB,EAAY,IAAmB,UAAgB"}

package/dist/esm/elements/media/math/math.js

@@ -0,0 +1,23 @@
+import { i as e, t } from "../../../chunks/dom.js";
+//#region src/elements/media/math/index.ts
+var n = /* @__PURE__ */ e({
+	MATH_SELECTOR: () => i,
+	MATH_TAG: () => r,
+	createMath: () => o,
+	enhanceMath: () => s
+}), r = "math", i = "math";
+function a(e) {
+	let { aria: t, display: n, attrs: r, tabIndex: i, ...a } = e ?? {}, o = { ...a }, s = {};
+	typeof t?.label == "string" && (s.label = t.label), typeof t?.labelledby == "string" && (s.labelledby = t.labelledby), typeof t?.hidden == "boolean" ? s.hidden = t.hidden : s.hidden = !0, Object.keys(s).length > 0 && (o.aria = s), typeof i == "number" ? o.tabIndex = i : o.tabIndex = -1;
+	let c = { ...r ?? {} };
+	return n && (c.display = n), Object.keys(c).length > 0 && (o.attrs = c), o;
+}
+function o(e, n) {
+	let i = document.createElement(r);
+	return t(i, a(n)), typeof e == "string" && (i.textContent = e), i;
+}
+function s(e = document) {}
+//#endregion
+export { i as MATH_SELECTOR, r as MATH_TAG, o as createMath, s as enhanceMath, n as t };
+
+//# sourceMappingURL=math.js.map

package/dist/esm/elements/media/math/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","names":[],"sources":["../../../../../src/elements/media/math/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Math element helpers.\n *\n * @remarks\n * The MathML math element (`<math>`) represents mathematical notation.\n *\n * Best-practice guidance:\n * - Prefer real MathML over images for math content when possible.\n * - Use `display=\"block\"` for standalone equations; inline math remains the default.\n * - Do not rely on raw attribute injection for behavior; keep markup semantic.\n *\n * Accessibility defaults for pkgn-sol v0.1.0:\n * - `<math>` is treated as decorative by default:\n *   - `aria-hidden=\"true\"`\n *   - `tabIndex = -1`\n * - If consumers provide explicit overrides (e.g. `aria.hidden`, `tabIndex`), pkgn-sol\n *   respects them.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create MathML roots in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { applyGlobalAttrs, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs (e.g. `lable`).\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for MathML roots.\n *\n * @category Constants\n */\nexport const MATH_TAG = 'math' as const;\n\n/**\n * A CSS selector targeting math elements.\n *\n * @category Constants\n */\nexport const MATH_SELECTOR = 'math';\n\n/**\n * Attribute bag for math creation/enhancement.\n *\n * @remarks\n * MathML `<math>` supports the `display` attribute:\n * - `inline` (default)\n * - `block`\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type MathAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * MathML display mode.\n   *\n   * @remarks\n   * `block` renders as a block-level equation, `inline` renders inline.\n   */\n  display?: 'block' | 'inline';\n};\n\n/**\n * Normalize {@link MathAttrs} into {@link GlobalAttrs} for `dom.ts`,\n * applying pkgn-sol's MathML accessibility defaults.\n *\n * @param attrs - The math attributes.\n * @returns A {@link GlobalAttrs} object (always returned to support defaults).\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: MathAttrs): GlobalAttrs {\n  const { aria, display, attrs: rawAttrs, tabIndex, ...rest } = attrs ?? {};\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  // Decorative by default, unless explicitly overridden.\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (typeof aria?.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria?.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n\n  const explicitAriaHidden = typeof aria?.hidden === 'boolean';\n  if (explicitAriaHidden) {\n    mappedAria.hidden = aria.hidden!;\n  } else {\n    mappedAria.hidden = true;\n  }\n\n  if (Object.keys(mappedAria).length > 0) {\n    mapped.aria = mappedAria;\n  }\n\n  if (typeof tabIndex === 'number') {\n    mapped.tabIndex = tabIndex;\n  } else {\n    mapped.tabIndex = -1;\n  }\n\n  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(rawAttrs ?? {}) };\n\n  if (display) mergedAttrs.display = display;\n\n  if (Object.keys(mergedAttrs).length > 0) {\n    mapped.attrs = mergedAttrs;\n  }\n\n  return mapped;\n}\n\n/**\n * Create a MathML `<math>` element with optional text content and attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * Note: `<math>` is not part of {@link HTMLElementTagNameMap}, so pkgn-sol creates it\n * via `document.createElement(\"math\")` and narrows the type to {@link MathMLElement}.\n *\n * @param text - Optional text content for the math element.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<math>` element.\n *\n * @category DOM\n */\nexport function createMath(text?: string, attrs?: MathAttrs): MathMLElement {\n  const el = document.createElement(MATH_TAG) as unknown as MathMLElement;\n\n  applyGlobalAttrs(el as unknown as HTMLElement, toGlobalAttrs(attrs));\n\n  if (typeof text === 'string') (el as unknown as Node).textContent = text;\n\n  return el;\n}\n\n/**\n * Enhance math elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceMath(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for math.\n  void root;\n}\n"],"mappings":";;;;;;;IAiEa,IAAW,QAOX,IAAgB;AAuC7B,SAAS,EAAc,GAAgC;CACrD,IAAM,EAAE,SAAM,YAAS,OAAO,GAAU,aAAU,GAAG,MAAS,KAAS,EAAE,EAEnE,IAAsB,EAAE,GAAG,GAAM,EAGjC,IAA+C,EAAE;CAgBvD,AAdI,OAAO,GAAM,SAAU,aAAU,EAAW,QAAQ,EAAK,QACzD,OAAO,GAAM,cAAe,aAAU,EAAW,aAAa,EAAK,aAE5C,OAAO,GAAM,UAAW,YAEjD,EAAW,SAAS,EAAK,SAEzB,EAAW,SAAS,IAGlB,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAO,OAAO,IAGZ,OAAO,KAAa,WACtB,EAAO,WAAW,IAElB,EAAO,WAAW;CAGpB,IAAM,IAAiD,EAAE,GAAI,KAAY,EAAE,EAAG;CAQ9E,OANI,MAAS,EAAY,UAAU,IAE/B,OAAO,KAAK,EAAY,CAAC,SAAS,MACpC,EAAO,QAAQ,IAGV;;AAqBT,SAAgB,EAAW,GAAe,GAAkC;CAC1E,IAAM,IAAK,SAAS,cAAc,EAAS;CAM3C,OAJA,EAAiB,GAA8B,EAAc,EAAM,CAAC,EAEhE,OAAO,KAAS,aAAU,EAAwB,cAAc,IAE7D;;AAqBT,SAAgB,EAAY,IAAmB,UAAgB"}

package/dist/esm/elements/media/media.js

@@ -0,0 +1,26 @@
+import { i as e } from "../../chunks/dom.js";
+import { t } from "./img/img.js";
+import { t as n } from "./svg/svg.js";
+import { t as r } from "./math/math.js";
+import { t as i } from "./canvas/canvas.js";
+import { t as a } from "./iframe/iframe.js";
+import { t as o } from "./embed/embed.js";
+import { t as s } from "./object/object.js";
+import { t as c } from "./video/video.js";
+import { t as l } from "./audio/audio.js";
+//#region src/elements/media/index.ts
+var u = /* @__PURE__ */ e({
+	audio: () => l,
+	canvas: () => i,
+	embed: () => o,
+	iframe: () => a,
+	img: () => t,
+	math: () => r,
+	object: () => s,
+	svg: () => n,
+	video: () => c
+});
+//#endregion
+export { l as audio, i as canvas, o as embed, a as iframe, t as img, r as math, s as object, n as svg, u as t, c as video };
+
+//# sourceMappingURL=media.js.map

package/dist/esm/elements/media/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","names":[],"sources":["../../../../src/elements/media/index.ts"],"sourcesContent":["/**\n * Media element factories.\n *\n * Provides framework-agnostic factory functions for embedded, graphical,\n * and time-based media elements.\n *\n * These factories:\n * - Create semantic HTML media elements using pkgn-sol's hardened DOM helpers.\n * - Forward curated global attributes.\n * - Enforce structured, typed attribute bags.\n * - Apply sensible fallbacks where required by the HTML specification.\n * - Prevent unsafe attribute injection.\n *\n * @module elements/media\n * @since 0.1.0\n */\n\n/**\n * `<img>` element factory namespace.\n *\n * Embeds raster images into the document.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img\n */\nexport * as img from './img';\n\n/**\n * `<svg>` element factory namespace.\n *\n * Embeds scalable vector graphics content.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/svg\n */\nexport * as svg from './svg';\n\n/**\n * `<math>` element factory namespace.\n *\n * Embeds MathML content for mathematical notation.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/math\n */\nexport * as math from './math';\n\n/**\n * `<canvas>` element factory namespace.\n *\n * Provides a bitmap rendering surface for scripted drawing.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas\n */\nexport * as canvas from './canvas';\n\n/**\n * `<iframe>` element factory namespace.\n *\n * Embeds another HTML page within the current document.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe\n */\nexport * as iframe from './iframe';\n\n/**\n * `<embed>` element factory namespace.\n *\n * Embeds external content such as plugins or media resources.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed\n */\nexport * as embed from './embed';\n\n/**\n * `<object>` element factory namespace.\n *\n * Embeds external resources such as images, PDFs, or interactive content.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object\n */\nexport * as object from './object';\n\n/**\n * `<video>` element factory namespace.\n *\n * Embeds time-based video media.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video\n */\nexport * as video from './video';\n\n/**\n * `<audio>` element factory namespace.\n *\n * Embeds time-based audio media.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio\n */\nexport * as audio from './audio';\n"],"mappings":""}

package/dist/esm/elements/media/object/object.js

@@ -0,0 +1,37 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/media/object/index.ts
+var n = /* @__PURE__ */ e({
+	OBJECT_SELECTOR: () => i,
+	OBJECT_TAG: () => r,
+	createObject: () => s,
+	enhanceObjects: () => c
+}), r = "object", i = "object";
+function a(e, t) {
+	if (typeof t == "number") {
+		if (!Number.isFinite(t) || t < 0 || !Number.isInteger(t)) throw Error(`Invalid ${e}: expected a non-negative integer.`);
+		return String(t);
+	}
+	if (!/^\d+$/.test(t)) throw Error(`Invalid ${e}: expected a numeric string.`);
+	return t;
+}
+function o(e) {
+	if (!e) return { attrs: { data: "about:blank" } };
+	let { aria: t, data: n, type: r, name: i, form: o, width: s, height: c, attrs: l, ...u } = e, d = {};
+	t && (typeof t.label == "string" && (d.label = t.label), typeof t.labelledby == "string" && (d.labelledby = t.labelledby), typeof t.describedby == "string" && (d.describedby = t.describedby), typeof t.hidden == "boolean" && (d.hidden = t.hidden));
+	let f = { ...l ?? {} };
+	typeof n == "string" && n.length > 0 && (f.data = n), typeof r == "string" && r.length > 0 && (f.type = r), f.data === void 0 && f.type === void 0 && (f.data = "about:blank"), typeof i == "string" && i.length > 0 && (f.name = i), typeof o == "string" && o.length > 0 && (f.form = o), s !== void 0 && (f.width = a("width", s)), c !== void 0 && (f.height = a("height", c));
+	let p = Object.keys(d).length > 0, m = Object.keys(f).length > 0;
+	return {
+		...u,
+		...p ? { aria: d } : null,
+		...m ? { attrs: f } : null
+	};
+}
+function s(e, n) {
+	return t(r, o(n), e);
+}
+function c(e = document) {}
+//#endregion
+export { i as OBJECT_SELECTOR, r as OBJECT_TAG, s as createObject, c as enhanceObjects, n as t };
+
+//# sourceMappingURL=object.js.map

package/dist/esm/elements/media/object/object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.js","names":[],"sources":["../../../../../src/elements/media/object/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Object element helpers.\n *\n * @remarks\n * The object element (`<object>`) embeds external resources (HTML, images, PDFs,\n * SVG, etc.) into the document.\n *\n * Best-practice guidance:\n * - Prefer purpose-built elements when available:\n *   - `<img>` for images\n *   - `<video>` / `<audio>` for media\n *   - `<iframe>` for embedded documents/interactive content (with sandboxing)\n * - Always provide a meaningful fallback inside `<object>` for unsupported content.\n * - Avoid obsolete attributes (e.g. `codebase`, `classid`, `declare`, etc.).\n * - For layout, prefer CSS. If using `width`/`height` attributes, keep them numeric.\n *\n * Attribute guidance:\n * - At least one of `data` or `type` should be provided.\n * - If neither is provided, pkgn-sol falls back to `data=\"about:blank\"` to avoid an\n *   \"empty\" embed configuration while staying inert.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create object elements in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * ID reference to the describing element(s), mapped to `aria-describedby`.\n   */\n  describedby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for object embeds.\n *\n * @category Constants\n */\nexport const OBJECT_TAG = 'object' as const;\n\n/**\n * A CSS selector targeting object elements.\n *\n * @category Constants\n */\nexport const OBJECT_SELECTOR = 'object';\n\n/**\n * Dimension values allowed for width/height attributes.\n *\n * @remarks\n * Per best practice, keep these numeric (pixels). Prefer CSS for layout.\n *\n * @category Types\n */\nexport type ObjectDimension = number | `${number}`;\n\n/**\n * Attribute bag for object creation/enhancement.\n *\n * @remarks\n * - `data` and `type` are the primary configuration attributes.\n * - Provide fallback content via `text` or by appending children after creation.\n * - Global attributes are supported, including a structured ARIA input.\n *\n * @category Attributes\n */\nexport type ObjectAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Address of the resource to embed (maps to `data`).\n   */\n  data?: string;\n\n  /**\n   * MIME type of the embedded resource (maps to `type`).\n   *\n   * @example\n   * \"text/html\", \"image/svg+xml\", \"application/pdf\"\n   */\n  type?: string;\n\n  /**\n   * Name of the object (maps to `name`).\n   */\n  name?: string;\n\n  /**\n   * Associate the object with a form (maps to `form`).\n   */\n  form?: string;\n\n  /**\n   * Width in CSS pixels (maps to `width`).\n   *\n   * @remarks\n   * Prefer CSS for layout.\n   */\n  width?: ObjectDimension;\n\n  /**\n   * Height in CSS pixels (maps to `height`).\n   *\n   * @remarks\n   * Prefer CSS for layout.\n   */\n  height?: ObjectDimension;\n\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Validate and normalize a width/height value.\n *\n * @param name - Attribute name for error messages.\n * @param v - The provided dimension.\n * @returns A normalized string suitable for attributes.\n *\n * @category Internal\n */\nfunction normalizeDimension(name: 'width' | 'height', v: ObjectDimension): string {\n  if (typeof v === 'number') {\n    if (!Number.isFinite(v) || v < 0 || !Number.isInteger(v)) {\n      throw new Error(`Invalid ${name}: expected a non-negative integer.`);\n    }\n    return String(v);\n  }\n\n  // String numeric (template literal), but validate anyway.\n  if (!/^\\d+$/.test(v)) {\n    throw new Error(`Invalid ${name}: expected a numeric string.`);\n  }\n\n  return v;\n}\n\n/**\n * Normalize {@link ObjectAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The object attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: ObjectAttrs): GlobalAttrs | undefined {\n  if (!attrs) {\n    // Best-practice: an object should have at least data or type.\n    // We still allow `createObject()` with no args, but keep it inert.\n    return { attrs: { data: 'about:blank' } };\n  }\n\n  const { aria, data, type, name, form, width, height, attrs: extraAttrs, ...rest } = attrs;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.describedby === 'string') mappedAria.describedby = aria.describedby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const mappedAttrs: Record<string, AttrValue> = { ...(extraAttrs ?? {}) };\n\n  // Primary embed configuration.\n  if (typeof data === 'string' && data.length > 0) mappedAttrs.data = data;\n  if (typeof type === 'string' && type.length > 0) mappedAttrs.type = type;\n\n  // Per guidance/spec: at least one of data/type should exist.\n  // If neither is provided, keep it inert rather than \"empty\".\n  if (mappedAttrs.data === undefined && mappedAttrs.type === undefined) {\n    mappedAttrs.data = 'about:blank';\n  }\n\n  if (typeof name === 'string' && name.length > 0) mappedAttrs.name = name;\n  if (typeof form === 'string' && form.length > 0) mappedAttrs.form = form;\n\n  if (width !== undefined) mappedAttrs.width = normalizeDimension('width', width);\n  if (height !== undefined) mappedAttrs.height = normalizeDimension('height', height);\n\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n  const hasMappedAttrs = Object.keys(mappedAttrs).length > 0;\n\n  return {\n    ...rest,\n    ...(hasMappedAria ? { aria: mappedAria } : null),\n    ...(hasMappedAttrs ? { attrs: mappedAttrs } : null),\n  };\n}\n\n/**\n * Create an object element with optional fallback text and attributes.\n *\n * @remarks\n * - Fallback text is assigned via `textContent` (never `innerHTML`).\n * - For richer fallback, append children after creation.\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional fallback text content for the object.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<object>` element.\n *\n * @example\n * ```ts\n * import { createObject } from \"@lnpg/pkgn-sol/elements/media/object\";\n *\n * const obj = createObject(\"Your browser can't display this content.\", {\n *   data: \"/docs/guide.pdf\",\n *   type: \"application/pdf\",\n *   width: 640,\n *   height: 480,\n * });\n *\n * document.body.appendChild(obj);\n * ```\n *\n * @category DOM\n */\nexport function createObject(text?: string, attrs?: ObjectAttrs): ElementOf<typeof OBJECT_TAG> {\n  return createElement(OBJECT_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance object elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceObjects(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for object.\n  void root;\n}\n"],"mappings":";;;;;;;IAyEa,IAAa,UAOb,IAAkB;AA6E/B,SAAS,EAAmB,GAA0B,GAA4B;CAChF,IAAI,OAAO,KAAM,UAAU;EACzB,IAAI,CAAC,OAAO,SAAS,EAAE,IAAI,IAAI,KAAK,CAAC,OAAO,UAAU,EAAE,EACtD,MAAU,MAAM,WAAW,EAAK,oCAAoC;EAEtE,OAAO,OAAO,EAAE;;CAIlB,IAAI,CAAC,QAAQ,KAAK,EAAE,EAClB,MAAU,MAAM,WAAW,EAAK,8BAA8B;CAGhE,OAAO;;AAWT,SAAS,EAAc,GAA8C;CACnE,IAAI,CAAC,GAGH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,EAAE;CAG3C,IAAM,EAAE,SAAM,SAAM,SAAM,SAAM,SAAM,UAAO,WAAQ,OAAO,GAAY,GAAG,MAAS,GAE9E,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,eAAgB,aAAU,EAAW,cAAc,EAAK,cACpE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAyC,EAAE,GAAI,KAAc,EAAE,EAAG;CAgBxE,AAbI,OAAO,KAAS,YAAY,EAAK,SAAS,MAAG,EAAY,OAAO,IAChE,OAAO,KAAS,YAAY,EAAK,SAAS,MAAG,EAAY,OAAO,IAIhE,EAAY,SAAS,KAAA,KAAa,EAAY,SAAS,KAAA,MACzD,EAAY,OAAO,gBAGjB,OAAO,KAAS,YAAY,EAAK,SAAS,MAAG,EAAY,OAAO,IAChE,OAAO,KAAS,YAAY,EAAK,SAAS,MAAG,EAAY,OAAO,IAEhE,MAAU,KAAA,MAAW,EAAY,QAAQ,EAAmB,SAAS,EAAM,GAC3E,MAAW,KAAA,MAAW,EAAY,SAAS,EAAmB,UAAU,EAAO;CAEnF,IAAM,IAAgB,OAAO,KAAK,EAAW,CAAC,SAAS,GACjD,IAAiB,OAAO,KAAK,EAAY,CAAC,SAAS;CAEzD,OAAO;EACL,GAAG;EACH,GAAI,IAAgB,EAAE,MAAM,GAAY,GAAG;EAC3C,GAAI,IAAiB,EAAE,OAAO,GAAa,GAAG;EAC/C;;AAiCH,SAAgB,EAAa,GAAe,GAAmD;CAC7F,OAAO,EAAc,GAAY,EAAc,EAAM,EAAE,EAAK;;AAqB9D,SAAgB,EAAe,IAAmB,UAAgB"}

package/dist/esm/elements/media/svg/svg.js

@@ -0,0 +1,27 @@
+import { i as e, t } from "../../../chunks/dom.js";
+//#region src/elements/media/svg/index.ts
+var n = /* @__PURE__ */ e({
+	SVG_SELECTOR: () => "svg",
+	SVG_TAG: () => "svg",
+	createSvg: () => o,
+	enhanceSvgs: () => s
+}), r = "svg", i = "svg";
+function a(e) {
+	let { aria: t, viewBox: n, width: r, height: i, role: a, tabIndex: o, attrs: s, ...c } = e ?? {}, l = { ...c };
+	a && (l.role = a);
+	let u = {}, d = typeof t?.label == "string", f = typeof t?.labelledby == "string", p = typeof t?.hidden == "boolean";
+	d && (u.label = t.label), f && (u.labelledby = t.labelledby), p && (u.hidden = t.hidden);
+	let m = !d && !f;
+	m && !p && (u.hidden = !0), Object.keys(u).length > 0 && (l.aria = u), !m && !a && (l.role = "img"), typeof o == "number" ? l.tabIndex = o : m && (l.tabIndex = -1);
+	let h = { ...s ?? {} };
+	return m && (h.focusable = "false"), n && (h.viewBox = n), r !== void 0 && (h.width = r), i !== void 0 && (h.height = i), Object.keys(h).length > 0 && (l.attrs = h), l;
+}
+function o(e, n) {
+	let r = document.createElement("svg");
+	return t(r, a(n)), typeof e == "string" && (r.textContent = e), r;
+}
+function s(e = document) {}
+//#endregion
+export { i as SVG_SELECTOR, r as SVG_TAG, o as createSvg, s as enhanceSvgs, n as t };
+
+//# sourceMappingURL=svg.js.map

package/dist/esm/elements/media/svg/svg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.js","names":[],"sources":["../../../../../src/elements/media/svg/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Svg element helpers.\n *\n * @remarks\n * The svg element (`<svg>`) defines scalable vector graphics.\n *\n * pkgn-sol enforces:\n * - Default decorative behaviour:\n *   - aria-hidden=\"true\"\n *   - tabIndex = -1\n *   - focusable=\"false\"\n * - If aria.label or aria.labelledby is provided:\n *   - role=\"img\" is added (unless explicitly set)\n * - Explicit overrides for role, aria-hidden and tabIndex are respected.\n *\n * @module\n * @category Elements\n */\n\nimport { applyGlobalAttrs, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input.\n */\nexport type StructuredAria = {\n  label?: string;\n  labelledby?: string;\n  hidden?: boolean;\n};\n\nexport const SVG_TAG = 'svg';\nexport const SVG_SELECTOR = 'svg';\n\nexport type SvgAttrs = Omit<GlobalAttrs, 'aria'> & {\n  viewBox?: string;\n  width?: number | string;\n  height?: number | string;\n  aria?: StructuredAria;\n};\n\nfunction toGlobalAttrs(attrs?: SvgAttrs): GlobalAttrs {\n  const { aria, viewBox, width, height, role, tabIndex, attrs: rawAttrs, ...rest } = attrs ?? {};\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  // Preserve explicit role\n  if (role) {\n    mapped.role = role;\n  }\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  const hasLabel = typeof aria?.label === 'string';\n  const hasLabelledby = typeof aria?.labelledby === 'string';\n  const explicitAriaHidden = typeof aria?.hidden === 'boolean';\n\n  if (hasLabel) mappedAria.label = aria.label!;\n  if (hasLabelledby) mappedAria.labelledby = aria.labelledby!;\n  if (explicitAriaHidden) mappedAria.hidden = aria.hidden!;\n\n  const isDecorative = !hasLabel && !hasLabelledby;\n\n  if (isDecorative && !explicitAriaHidden) {\n    mappedAria.hidden = true;\n  }\n\n  if (Object.keys(mappedAria).length > 0) {\n    mapped.aria = mappedAria;\n  }\n\n  // Only auto-assign role if user did not provide one\n  if (!isDecorative && !role) {\n    mapped.role = 'img';\n  }\n\n  if (typeof tabIndex === 'number') {\n    mapped.tabIndex = tabIndex;\n  } else if (isDecorative) {\n    mapped.tabIndex = -1;\n  }\n\n  // Merge user attrs with internal attrs\n  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = {\n    ...(rawAttrs ?? {}),\n  };\n\n  if (isDecorative) {\n    mergedAttrs.focusable = 'false';\n  }\n\n  if (viewBox) mergedAttrs.viewBox = viewBox;\n  if (width !== undefined) mergedAttrs.width = width;\n  if (height !== undefined) mergedAttrs.height = height;\n\n  if (Object.keys(mergedAttrs).length > 0) {\n    mapped.attrs = mergedAttrs;\n  }\n\n  return mapped;\n}\n\n/**\n * Create an SVG element with accessibility defaults.\n */\nexport function createSvg(text?: string, attrs?: SvgAttrs): SVGSVGElement {\n  const el = document.createElement('svg') as unknown as SVGSVGElement;\n\n  applyGlobalAttrs(el as unknown as HTMLElement, toGlobalAttrs(attrs));\n\n  if (typeof text === 'string') {\n    el.textContent = text;\n  }\n\n  return el;\n}\n\n/**\n * No-op enhancement hook.\n */\nexport function enhanceSvgs(root: ParentNode = document): void {\n  void root;\n}\n"],"mappings":";;;;;;;IA8Ba,IAAU,OACV,IAAe;AAS5B,SAAS,EAAc,GAA+B;CACpD,IAAM,EAAE,SAAM,YAAS,UAAO,WAAQ,SAAM,aAAU,OAAO,GAAU,GAAG,MAAS,KAAS,EAAE,EAExF,IAAsB,EAAE,GAAG,GAAM;CAGvC,AAAI,MACF,EAAO,OAAO;CAGhB,IAAM,IAA+C,EAAE,EAEjD,IAAW,OAAO,GAAM,SAAU,UAClC,IAAgB,OAAO,GAAM,cAAe,UAC5C,IAAqB,OAAO,GAAM,UAAW;CAInD,AAFI,MAAU,EAAW,QAAQ,EAAK,QAClC,MAAe,EAAW,aAAa,EAAK,aAC5C,MAAoB,EAAW,SAAS,EAAK;CAEjD,IAAM,IAAe,CAAC,KAAY,CAAC;CAenC,AAbI,KAAgB,CAAC,MACnB,EAAW,SAAS,KAGlB,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAO,OAAO,IAIZ,CAAC,KAAgB,CAAC,MACpB,EAAO,OAAO,QAGZ,OAAO,KAAa,WACtB,EAAO,WAAW,IACT,MACT,EAAO,WAAW;CAIpB,IAAM,IAAiD,EACrD,GAAI,KAAY,EAAE,EACnB;CAcD,OAZI,MACF,EAAY,YAAY,UAGtB,MAAS,EAAY,UAAU,IAC/B,MAAU,KAAA,MAAW,EAAY,QAAQ,IACzC,MAAW,KAAA,MAAW,EAAY,SAAS,IAE3C,OAAO,KAAK,EAAY,CAAC,SAAS,MACpC,EAAO,QAAQ,IAGV;;AAMT,SAAgB,EAAU,GAAe,GAAiC;CACxE,IAAM,IAAK,SAAS,cAAc,MAAM;CAQxC,OANA,EAAiB,GAA8B,EAAc,EAAM,CAAC,EAEhE,OAAO,KAAS,aAClB,EAAG,cAAc,IAGZ;;AAMT,SAAgB,EAAY,IAAmB,UAAgB"}

package/dist/esm/elements/media/video/video.js

@@ -0,0 +1,27 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/media/video/index.ts
+var n = /* @__PURE__ */ e({
+	VIDEO_SELECTOR: () => i,
+	VIDEO_TAG: () => r,
+	createVideo: () => o,
+	enhanceVideos: () => s
+}), r = "video", i = "video";
+function a(e) {
+	if (!e) return;
+	let { aria: t, src: n, controls: r, autoplay: i, loop: a, muted: o, playsInline: s, preload: c, poster: l, width: u, height: d, crossOrigin: f, controlsList: p, disablePictureInPicture: m, disableRemotePlayback: h, referrerPolicy: g, fetchPriority: _, ...v } = e, y = { ...v };
+	if (t) {
+		let e = {};
+		typeof t.label == "string" && (e.label = t.label), typeof t.labelledby == "string" && (e.labelledby = t.labelledby), typeof t.hidden == "boolean" && (e.hidden = t.hidden), Object.keys(e).length > 0 && (y.aria = e);
+	}
+	let b = {};
+	return typeof p == "string" && (b.controlslist = p), Array.isArray(p) && (b.controlslist = p.join(" ")), typeof g == "string" && (b.referrerpolicy = g), typeof _ == "string" && (b.fetchpriority = _), typeof m == "boolean" && (b.disablepictureinpicture = m), typeof h == "boolean" && (b.disableremoteplayback = h), Object.keys(b).length > 0 && (y.attrs = b), y;
+}
+function o(e, n) {
+	let i = t(r, a(n), e);
+	return n ? (typeof n.src == "string" && (i.src = n.src), typeof n.controls == "boolean" && (i.controls = n.controls), typeof n.autoplay == "boolean" && (i.autoplay = n.autoplay), typeof n.loop == "boolean" && (i.loop = n.loop), n.autoplay === !0 && typeof n.muted != "boolean" ? i.muted = !0 : typeof n.muted == "boolean" && (i.muted = n.muted), typeof n.playsInline == "boolean" && (i.playsInline = n.playsInline), typeof n.preload == "string" && (i.preload = n.preload), typeof n.poster == "string" && (i.poster = n.poster), typeof n.width == "number" && (i.width = n.width), typeof n.height == "number" && (i.height = n.height), typeof n.crossOrigin == "string" && (i.crossOrigin = n.crossOrigin), i) : i;
+}
+function s(e = document) {}
+//#endregion
+export { i as VIDEO_SELECTOR, r as VIDEO_TAG, o as createVideo, s as enhanceVideos, n as t };
+
+//# sourceMappingURL=video.js.map

package/dist/esm/elements/media/video/video.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.js","names":[],"sources":["../../../../../src/elements/media/video/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Video element helpers.\n *\n * @remarks\n * The video element (`<video>`) embeds media playback.\n *\n * Best-practice guidance:\n * - Provide user controls (`controls`) unless you have a very strong reason not to.\n * - Autoplay is often blocked when audio is present; if `autoplay` is enabled,\n *   videos commonly need to be `muted` to actually autoplay in modern browsers.\n * - Prefer captions/subtitles via `<track>` for accessibility when relevant.\n * - Avoid obsolete attributes; use modern properties/attributes and CSS instead.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create video elements in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Token values for the `preload` attribute.\n *\n * @category Attributes\n */\nexport type VideoPreload = 'none' | 'metadata' | 'auto';\n\n/**\n * Token values for the `crossorigin` attribute.\n *\n * @category Attributes\n */\nexport type VideoCrossOrigin = 'anonymous' | 'use-credentials';\n\n/**\n * Token values for the `referrerpolicy` attribute.\n *\n * @category Attributes\n */\nexport type VideoReferrerPolicy =\n  | 'no-referrer'\n  | 'no-referrer-when-downgrade'\n  | 'origin'\n  | 'origin-when-cross-origin'\n  | 'same-origin'\n  | 'strict-origin'\n  | 'strict-origin-when-cross-origin'\n  | 'unsafe-url';\n\n/**\n * Token values for the `fetchpriority` attribute (where supported).\n *\n * @category Attributes\n */\nexport type VideoFetchPriority = 'high' | 'low' | 'auto';\n\n/**\n * The semantic tag name for video.\n *\n * @category Constants\n */\nexport const VIDEO_TAG = 'video' as const;\n\n/**\n * A CSS selector targeting video elements.\n *\n * @category Constants\n */\nexport const VIDEO_SELECTOR = 'video';\n\n/**\n * Attribute bag for video creation/enhancement.\n *\n * @remarks\n * Video elements accept standard HTML global attributes, plus media-specific\n * attributes and properties.\n *\n * pkgn-sol supports a structured ARIA input for common ARIA fields, mapped into\n * {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type VideoAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Source URL for the video.\n   */\n  src?: string;\n\n  /**\n   * Whether the browser should offer playback controls to the user.\n   */\n  controls?: boolean;\n\n  /**\n   * Whether the video should start playing automatically.\n   *\n   * @remarks\n   * Autoplay is frequently blocked unless the video is muted.\n   */\n  autoplay?: boolean;\n\n  /**\n   * Whether the video should loop after ending.\n   */\n  loop?: boolean;\n\n  /**\n   * Whether the audio should be muted.\n   */\n  muted?: boolean;\n\n  /**\n   * Hint that playback should happen inline on mobile browsers (not fullscreen).\n   */\n  playsInline?: boolean;\n\n  /**\n   * Preload behavior hint.\n   */\n  preload?: VideoPreload;\n\n  /**\n   * Poster image URL shown before playback starts.\n   */\n  poster?: string;\n\n  /**\n   * Display width in CSS pixels (attribute-reflected).\n   */\n  width?: number;\n\n  /**\n   * Display height in CSS pixels (attribute-reflected).\n   */\n  height?: number;\n\n  /**\n   * CORS setting for fetching the media.\n   */\n  crossOrigin?: VideoCrossOrigin;\n\n  /**\n   * Feature-control tokens for the video UI.\n   *\n   * @remarks\n   * Maps to the `controlslist` attribute (space-separated tokens).\n   */\n  controlsList?: string[] | string;\n\n  /**\n   * Disable Picture-in-Picture where supported.\n   */\n  disablePictureInPicture?: boolean;\n\n  /**\n   * Disable remote playback where supported.\n   */\n  disableRemotePlayback?: boolean;\n\n  /**\n   * Referrer policy for fetching the media.\n   */\n  referrerPolicy?: VideoReferrerPolicy;\n\n  /**\n   * Fetch priority hint (where supported).\n   */\n  fetchPriority?: VideoFetchPriority;\n};\n\n/**\n * Normalize {@link VideoAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The video attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: VideoAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const {\n    aria,\n    src,\n    controls,\n    autoplay,\n    loop,\n    muted,\n    playsInline,\n    preload,\n    poster,\n    width,\n    height,\n    crossOrigin,\n    controlsList,\n    disablePictureInPicture,\n    disableRemotePlayback,\n    referrerPolicy,\n    fetchPriority,\n    ...rest\n  } = attrs;\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  if (aria) {\n    const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n    if (Object.keys(mappedAria).length > 0) mapped.aria = mappedAria;\n  }\n\n  // Only attach attrs if we actually have any element-specific attributes to set\n  // via dom.ts (keeps output stable and avoids needless objects).\n  const elementAttrs: NonNullable<GlobalAttrs['attrs']> = {};\n\n  if (typeof controlsList === 'string') elementAttrs.controlslist = controlsList;\n  if (Array.isArray(controlsList)) elementAttrs.controlslist = controlsList.join(' ');\n\n  if (typeof referrerPolicy === 'string') elementAttrs.referrerpolicy = referrerPolicy;\n  if (typeof fetchPriority === 'string') elementAttrs.fetchpriority = fetchPriority;\n\n  // Boolean-ish feature flags that don't have reliable reflected properties everywhere.\n  if (typeof disablePictureInPicture === 'boolean') {\n    elementAttrs.disablepictureinpicture = disablePictureInPicture;\n  }\n  if (typeof disableRemotePlayback === 'boolean') {\n    elementAttrs.disableremoteplayback = disableRemotePlayback;\n  }\n\n  if (Object.keys(elementAttrs).length > 0) mapped.attrs = elementAttrs;\n\n  // The rest are applied as properties after createElement to preserve proper boolean semantics.\n  void src;\n  void controls;\n  void autoplay;\n  void loop;\n  void muted;\n  void playsInline;\n  void preload;\n  void poster;\n  void width;\n  void height;\n  void crossOrigin;\n\n  return mapped;\n}\n\n/**\n * Create a video element with optional fallback text and attributes.\n *\n * @remarks\n * - Fallback text is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n * - If `autoplay` is enabled and `muted` is not explicitly provided, pkgn-sol will\n *   default `muted` to `true` to align with common browser autoplay policies.\n *\n * @param text - Optional fallback text shown if video is unsupported.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<video>` element.\n *\n * @example\n * ```ts\n * import { createVideo } from \"@lnpg/pkgn-sol/elements/media/video\";\n *\n * document.body.appendChild(\n *   createVideo(\"Your browser does not support video.\", {\n *     src: \"/media/intro.mp4\",\n *     controls: true,\n *     preload: \"metadata\",\n *   })\n * );\n * ```\n *\n * @category DOM\n */\nexport function createVideo(text?: string, attrs?: VideoAttrs): HTMLVideoElement {\n  const el = createElement(VIDEO_TAG, toGlobalAttrs(attrs), text) as unknown as HTMLVideoElement;\n\n  if (!attrs) return el;\n\n  if (typeof attrs.src === 'string') el.src = attrs.src;\n\n  if (typeof attrs.controls === 'boolean') el.controls = attrs.controls;\n\n  if (typeof attrs.autoplay === 'boolean') el.autoplay = attrs.autoplay;\n  if (typeof attrs.loop === 'boolean') el.loop = attrs.loop;\n\n  // Practical default: autoplay usually requires muted.\n  if (attrs.autoplay === true && typeof attrs.muted !== 'boolean') {\n    el.muted = true;\n  } else if (typeof attrs.muted === 'boolean') {\n    el.muted = attrs.muted;\n  }\n\n  if (typeof attrs.playsInline === 'boolean')\n    (el as unknown as { playsInline?: boolean }).playsInline = attrs.playsInline;\n\n  if (typeof attrs.preload === 'string') el.preload = attrs.preload;\n\n  if (typeof attrs.poster === 'string') el.poster = attrs.poster;\n\n  if (typeof attrs.width === 'number') el.width = attrs.width;\n  if (typeof attrs.height === 'number') el.height = attrs.height;\n\n  if (typeof attrs.crossOrigin === 'string') el.crossOrigin = attrs.crossOrigin;\n\n  return el;\n}\n\n/**\n * Enhance video elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceVideos(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for video.\n  void root;\n}\n"],"mappings":";;;;;;;IAgGa,IAAY,SAOZ,IAAiB;AAmH9B,SAAS,EAAc,GAA6C;CAClE,IAAI,CAAC,GAAO;CAEZ,IAAM,EACJ,SACA,QACA,aACA,aACA,SACA,UACA,gBACA,YACA,WACA,UACA,WACA,gBACA,iBACA,4BACA,0BACA,mBACA,kBACA,GAAG,MACD,GAEE,IAAsB,EAAE,GAAG,GAAM;CAEvC,IAAI,GAAM;EACR,IAAM,IAA+C,EAAE;EAMvD,AAJI,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,SAE3D,OAAO,KAAK,EAAW,CAAC,SAAS,MAAG,EAAO,OAAO;;CAKxD,IAAM,IAAkD,EAAE;CA+B1D,OA7BI,OAAO,KAAiB,aAAU,EAAa,eAAe,IAC9D,MAAM,QAAQ,EAAa,KAAE,EAAa,eAAe,EAAa,KAAK,IAAI,GAE/E,OAAO,KAAmB,aAAU,EAAa,iBAAiB,IAClE,OAAO,KAAkB,aAAU,EAAa,gBAAgB,IAGhE,OAAO,KAA4B,cACrC,EAAa,0BAA0B,IAErC,OAAO,KAA0B,cACnC,EAAa,wBAAwB,IAGnC,OAAO,KAAK,EAAa,CAAC,SAAS,MAAG,EAAO,QAAQ,IAelD;;AAiCT,SAAgB,EAAY,GAAe,GAAsC;CAC/E,IAAM,IAAK,EAAc,GAAW,EAAc,EAAM,EAAE,EAAK;CA8B/D,OA5BK,KAED,OAAO,EAAM,OAAQ,aAAU,EAAG,MAAM,EAAM,MAE9C,OAAO,EAAM,YAAa,cAAW,EAAG,WAAW,EAAM,WAEzD,OAAO,EAAM,YAAa,cAAW,EAAG,WAAW,EAAM,WACzD,OAAO,EAAM,QAAS,cAAW,EAAG,OAAO,EAAM,OAGjD,EAAM,aAAa,MAAQ,OAAO,EAAM,SAAU,YACpD,EAAG,QAAQ,KACF,OAAO,EAAM,SAAU,cAChC,EAAG,QAAQ,EAAM,QAGf,OAAO,EAAM,eAAgB,cAC/B,EAA6C,cAAc,EAAM,cAE/D,OAAO,EAAM,WAAY,aAAU,EAAG,UAAU,EAAM,UAEtD,OAAO,EAAM,UAAW,aAAU,EAAG,SAAS,EAAM,SAEpD,OAAO,EAAM,SAAU,aAAU,EAAG,QAAQ,EAAM,QAClD,OAAO,EAAM,UAAW,aAAU,EAAG,SAAS,EAAM,SAEpD,OAAO,EAAM,eAAgB,aAAU,EAAG,cAAc,EAAM,cAE3D,KA5BY;;AAiDrB,SAAgB,EAAc,IAAmB,UAAgB"}

package/dist/esm/elements/responsive/area/area.js

@@ -0,0 +1,20 @@
+import { i as e, r as t } from "../../../chunks/dom.js";
+//#region src/elements/responsive/area/index.ts
+var n = /* @__PURE__ */ e({
+	AREA_SELECTOR: () => i,
+	AREA_TAG: () => r,
+	createArea: () => o,
+	enhanceAreas: () => s
+}), r = "area", i = "area";
+function a(e) {
+	let { aria: t, alt: n, href: r, shape: i, coords: a, target: o, download: s, ping: c, rel: l, referrerPolicy: u, hreflang: d, type: f, ...p } = e ?? {}, m = { ...p }, h = {};
+	return t && (typeof t.label == "string" && (h.label = t.label), typeof t.labelledby == "string" && (h.labelledby = t.labelledby), typeof t.hidden == "boolean" && (h.hidden = t.hidden)), Object.keys(h).length > 0 && (m.aria = h), m.attrs = { ...m.attrs ?? {} }, typeof r == "string" && r.length > 0 && (m.attrs.href = r, m.attrs.alt = typeof n == "string" ? n : ""), i && (m.attrs.shape = i), a && (m.attrs.coords = a), o && (m.attrs.target = o), typeof s == "boolean" && (m.attrs.download = s), typeof s == "string" && (m.attrs.download = s), c && (m.attrs.ping = c), l && (m.attrs.rel = l), u && (m.attrs.referrerpolicy = u), d && (m.attrs.hreflang = d), f && (m.attrs.type = f), m;
+}
+function o(e) {
+	return t(r, a(e));
+}
+function s(e = document) {}
+//#endregion
+export { i as AREA_SELECTOR, r as AREA_TAG, o as createArea, s as enhanceAreas, n as t };
+
+//# sourceMappingURL=area.js.map

package/dist/esm/elements/responsive/area/area.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"area.js","names":[],"sources":["../../../../../src/elements/responsive/area/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Area element helpers.\n *\n * @remarks\n * The area element (`<area>`) defines a hyperlink or dead region within an image map.\n * It is used inside a `<map>` element to define clickable (or non-clickable) areas.\n *\n * Best-practice guidance:\n * - Use `<area>` only within `<map>` and pair with an `<img usemap=\"...\">`.\n * - Prefer meaningful alternative text for clickable regions (screen readers rely on it).\n * - Keep shapes and coordinates accurate; imprecise maps are a usability disaster.\n *\n * Spec-aware pkgn-sol behavior:\n * - If `href` is provided: `alt` is required, and pkgn-sol will ensure an `alt` attribute\n *   exists (defaults to empty string if not provided).\n * - If `href` is not provided: `alt` must be omitted, and pkgn-sol will omit it.\n *\n * Global attributes are applied via pkgn-sol's hardened DOM helpers (`dom.ts`), which block:\n * - inline event handler attributes (e.g. `onclick`)\n * - the raw `style` attribute string (use `style` object instead)\n *\n * This module has no side effects and does not mutate the DOM unless you call its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createVoidElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for area elements.\n *\n * @category Constants\n */\nexport const AREA_TAG = 'area' as const;\n\n/**\n * A CSS selector targeting area elements.\n *\n * @category Constants\n */\nexport const AREA_SELECTOR = 'area';\n\n/**\n * Enumerated shape values for `<area>`.\n *\n * @remarks\n * The default (when omitted) is effectively `rect` in HTML's image map processing model,\n * but pkgn-sol does not force a default; it passes through what you provide.\n *\n * @category Types\n */\nexport type AreaShape = 'rect' | 'circle' | 'poly' | 'default';\n\n/**\n * Area-specific attributes.\n *\n * @remarks\n * `<area>` largely mirrors hyperlink-related attributes when `href` is present.\n * pkgn-sol enforces the spec rule around `alt`:\n * - `href` present => `alt` must be present (pkgn-sol ensures it exists)\n * - `href` absent  => `alt` must be omitted (pkgn-sol omits it)\n *\n * @category Attributes\n */\nexport type AreaAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Alternative text for the area.\n   *\n   * @remarks\n   * Only applied when `href` is present. If `href` is present and `alt` is not\n   * provided, pkgn-sol defaults it to `\"\"`. If `href` is absent, pkgn-sol omits `alt`\n   * entirely.\n   */\n  alt?: string;\n\n  /**\n   * Link target URL. When present, the area represents a hyperlink.\n   */\n  href?: string;\n\n  /**\n   * The shape of the area. Common values: `rect`, `circle`, `poly`, `default`.\n   */\n  shape?: AreaShape;\n\n  /**\n   * Coordinates defining the area geometry. Interpretation depends on `shape`.\n   */\n  coords?: string;\n\n  /**\n   * Where to display the linked URL (e.g. `_blank`).\n   */\n  target?: string;\n\n  /**\n   * Whether to download the linked resource instead of navigating.\n   *\n   * @remarks\n   * May be a boolean (attribute presence) or a suggested filename.\n   */\n  download?: boolean | string;\n\n  /**\n   * A space-separated list of URLs to ping when the link is followed.\n   */\n  ping?: string;\n\n  /**\n   * Relationship of the target object to the linking object.\n   */\n  rel?: string;\n\n  /**\n   * Referrer policy for the link.\n   */\n  referrerPolicy?: string;\n\n  /**\n   * Language of the linked resource (BCP 47 tag).\n   */\n  hreflang?: string;\n\n  /**\n   * MIME type of the linked resource (advisory).\n   */\n  type?: string;\n\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\nfunction toGlobalAttrs(attrs?: AreaAttrs): GlobalAttrs {\n  const {\n    aria,\n    alt,\n    href,\n    shape,\n    coords,\n    target,\n    download,\n    ping,\n    rel,\n    referrerPolicy,\n    hreflang,\n    type,\n    ...rest\n  } = attrs ?? {};\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  if (Object.keys(mappedAria).length > 0) {\n    mapped.aria = mappedAria;\n  }\n\n  // Apply element-specific attributes via the safe attrs escape hatch.\n  mapped.attrs = { ...(mapped.attrs ?? {}) };\n\n  const hasHref = typeof href === 'string' && href.length > 0;\n\n  if (hasHref) {\n    mapped.attrs.href = href;\n\n    // Spec: if href is present, alt must be present.\n    mapped.attrs.alt = typeof alt === 'string' ? alt : '';\n  } else {\n    // Spec: if href is absent, alt must be omitted.\n    // We intentionally do not set `alt` here even if provided.\n  }\n\n  if (shape) mapped.attrs.shape = shape;\n  if (coords) mapped.attrs.coords = coords;\n  if (target) mapped.attrs.target = target;\n\n  if (typeof download === 'boolean') mapped.attrs.download = download;\n  if (typeof download === 'string') mapped.attrs.download = download;\n\n  if (ping) mapped.attrs.ping = ping;\n  if (rel) mapped.attrs.rel = rel;\n  if (referrerPolicy) mapped.attrs.referrerpolicy = referrerPolicy;\n  if (hreflang) mapped.attrs.hreflang = hreflang;\n  if (type) mapped.attrs.type = type;\n\n  return mapped;\n}\n\n/**\n * Create an area element with spec-aware `alt` handling.\n *\n * @remarks\n * - `<area>` is a void element (no text content).\n * - If `href` is present, pkgn-sol ensures `alt` is present (defaults to `\"\"`).\n * - If `href` is absent, pkgn-sol omits `alt`.\n *\n * @category DOM\n */\nexport function createArea(attrs?: AreaAttrs): ElementOf<typeof AREA_TAG> {\n  return createVoidElement(AREA_TAG, toGlobalAttrs(attrs));\n}\n\n/**\n * Enhance area elements within a given root.\n *\n * @remarks\n * No runtime behaviour in v0.1.0.\n *\n * @category Enhancement\n */\nexport function enhanceAreas(root: ParentNode = document): void {\n  void root;\n}\n"],"mappings":";;;;;;;IAwDa,IAAW,QAOX,IAAgB;AA8F7B,SAAS,EAAc,GAAgC;CACrD,IAAM,EACJ,SACA,QACA,SACA,UACA,WACA,WACA,aACA,SACA,QACA,mBACA,aACA,SACA,GAAG,MACD,KAAS,EAAE,EAET,IAAsB,EAAE,GAAG,GAAM,EAEjC,IAA+C,EAAE;CAwCvD,OAtCI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,UAG7D,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAO,OAAO,IAIhB,EAAO,QAAQ,EAAE,GAAI,EAAO,SAAS,EAAE,EAAG,EAE1B,OAAO,KAAS,YAAY,EAAK,SAAS,MAGxD,EAAO,MAAM,OAAO,GAGpB,EAAO,MAAM,MAAM,OAAO,KAAQ,WAAW,IAAM,KAMjD,MAAO,EAAO,MAAM,QAAQ,IAC5B,MAAQ,EAAO,MAAM,SAAS,IAC9B,MAAQ,EAAO,MAAM,SAAS,IAE9B,OAAO,KAAa,cAAW,EAAO,MAAM,WAAW,IACvD,OAAO,KAAa,aAAU,EAAO,MAAM,WAAW,IAEtD,MAAM,EAAO,MAAM,OAAO,IAC1B,MAAK,EAAO,MAAM,MAAM,IACxB,MAAgB,EAAO,MAAM,iBAAiB,IAC9C,MAAU,EAAO,MAAM,WAAW,IAClC,MAAM,EAAO,MAAM,OAAO,IAEvB;;AAaT,SAAgB,EAAW,GAA+C;CACxE,OAAO,EAAkB,GAAU,EAAc,EAAM,CAAC;;AAW1D,SAAgB,EAAa,IAAmB,UAAgB"}

package/dist/esm/elements/responsive/map/map.js

@@ -0,0 +1,35 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/responsive/map/index.ts
+var n = /* @__PURE__ */ e({
+	MAP_SELECTOR: () => "map",
+	MAP_TAG: () => "map",
+	createMap: () => s,
+	enhanceMaps: () => c
+}), r = "map", i = "map";
+function a(e) {
+	let t = String(e).trim();
+	if (t.length === 0) throw Error("Map \"name\" must be a non-empty string.");
+	if (/\s/.test(t)) throw Error("Map \"name\" must not contain whitespace.");
+}
+function o(e) {
+	let { aria: t, name: n, ...r } = e ?? {}, i = { ...r.attrs ?? {} }, o = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(i, e) || (i[e] = t));
+	}, s = typeof n == "string" ? n : typeof r.id == "string" ? r.id : "map";
+	if (a(s), typeof n == "string" && typeof r.id == "string" && n !== r.id) throw Error("Map \"id\" must match \"name\" when both are provided.");
+	o("name", s);
+	let c = {};
+	t && (typeof t.label == "string" && (c.label = t.label), typeof t.labelledby == "string" && (c.labelledby = t.labelledby), typeof t.hidden == "boolean" && (c.hidden = t.hidden));
+	let l = {
+		...r,
+		attrs: i
+	};
+	return Object.keys(c).length > 0 && (l.aria = c), l;
+}
+function s(e, n) {
+	return t("map", o(n), e);
+}
+function c(e = document) {}
+//#endregion
+export { i as MAP_SELECTOR, r as MAP_TAG, s as createMap, c as enhanceMaps, n as t };
+
+//# sourceMappingURL=map.js.map

package/dist/esm/elements/responsive/map/map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.js","names":[],"sources":["../../../../../src/elements/responsive/map/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Map element helpers.\n *\n * @remarks\n * The map element (`<map>`) defines an image map: a set of clickable regions\n * (typically via descendant `<area>` elements) that can be referenced from an\n * `<img>` (or other image-like element) using the `usemap` attribute.\n *\n * Best-practice guidance:\n * - Always provide a meaningful, unique `name` for the map.\n * - Use `<area>` children to define interactive regions.\n * - Keep `name` free of whitespace and ensure it is unique within the document/tree.\n * - If you also set `id`, it should match `name` (spec requirement).\n *\n * pkgn-sol notes:\n * - This module is framework-agnostic and has no side effects.\n * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:\n *   - inline event handler attributes (e.g. `onclick`)\n *   - raw `style` attribute injection (use the `style` object instead)\n * - Text passed to factories is assigned via `textContent` (never `innerHTML`).\n *\n * References:\n * - MDN: `<map>` element\n * - WHATWG HTML: map element and `name` requirements\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for map.\n *\n * @category Constants\n */\nexport const MAP_TAG = 'map' as const;\n\n/**\n * A CSS selector targeting map elements.\n *\n * @category Constants\n */\nexport const MAP_SELECTOR = 'map';\n\n/**\n * Attribute bag for map creation/enhancement.\n *\n * @remarks\n * Element-specific attributes:\n * - `name` (required by spec for referencing via `usemap`)\n *\n * Spec notes:\n * - `name` must be present, non-empty, and contain no ASCII whitespace.\n * - If `id` is also specified, it must match `name`.\n *\n * pkgn-sol behavior:\n * - If `name` is omitted, pkgn-sol provides a deterministic fallback:\n *   - uses `id` if provided\n *   - otherwise defaults to `\"map\"`\n *   Callers should set a unique name in real documents.\n *\n * @category Attributes\n */\nexport type MapAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Name of the image map.\n   *\n   * @remarks\n   * Used by `<img usemap=\"#NAME\">` to reference this `<map>`.\n   */\n  name?: string;\n\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Validate a map `name` value according to spec constraints.\n *\n * @param name - The name to validate.\n * @throws Error if the name is empty or contains whitespace.\n *\n * @category Internal\n */\nfunction assertValidMapName(name: string): void {\n  const raw = String(name);\n  const trimmed = raw.trim();\n\n  if (trimmed.length === 0) {\n    throw new Error('Map \"name\" must be a non-empty string.');\n  }\n\n  // Spec: no ASCII whitespace. We conservatively reject any whitespace.\n  if (/\\s/.test(trimmed)) {\n    throw new Error('Map \"name\" must not contain whitespace.');\n  }\n}\n\n/**\n * Normalize {@link MapAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @remarks\n * - Preserves caller-provided `attrs` escape hatch (still validated by `dom.ts`).\n * - Applies/validates the required `name` attribute deterministically.\n * - Enforces the spec rule that `id` and `name` must match if both are provided.\n *\n * @param attrs - The map attributes.\n * @returns A {@link GlobalAttrs} object.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: MapAttrs): GlobalAttrs {\n  const a: MapAttrs = attrs ?? {};\n\n  const { aria, name, ...rest } = a;\n\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  const setIfUnset = (key: string, v: AttrValue | undefined): void => {\n    if (v === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = v;\n  };\n\n  // Determine name:\n  // - explicit `name`\n  // - else use `id` if present (and ensure spec match if both were provided)\n  // - else deterministic fallback \"map\"\n  const resolvedName =\n    typeof name === 'string' ? name : typeof rest.id === 'string' ? rest.id : 'map';\n\n  assertValidMapName(resolvedName);\n\n  if (typeof name === 'string' && typeof rest.id === 'string' && name !== rest.id) {\n    throw new Error('Map \"id\" must match \"name\" when both are provided.');\n  }\n\n  setIfUnset('name', resolvedName);\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const next: GlobalAttrs = { ...rest, attrs: mergedAttrs };\n\n  if (Object.keys(mappedAria).length > 0) {\n    next.aria = mappedAria;\n  }\n\n  return next;\n}\n\n/**\n * Create a map element with optional text content and attributes.\n *\n * @remarks\n * While `<map>` typically contains `<area>` elements (not text), pkgn-sol still\n * supports optional `text` for:\n * - fallback content\n * - simple labelling in environments that inspect textContent\n *\n * - Text is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<map>` element.\n *\n * @example\n * ```ts\n * import { createMap } from \"@lnpg/pkgn-sol/elements/responsive/map\";\n *\n * const m = createMap(undefined, { name: \"product-map\" });\n * ```\n *\n * @category DOM\n */\nexport function createMap(text?: string, attrs?: MapAttrs): ElementOf<typeof MAP_TAG> {\n  return createElement(MAP_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance map elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceMaps(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for map.\n  void root;\n}\n"],"mappings":";;;;;;;IAgEa,IAAU,OAOV,IAAe;AA4C5B,SAAS,EAAmB,GAAoB;CAE9C,IAAM,IADM,OAAO,EACH,CAAI,MAAM;CAE1B,IAAI,EAAQ,WAAW,GACrB,MAAU,MAAM,2CAAyC;CAI3D,IAAI,KAAK,KAAK,EAAQ,EACpB,MAAU,MAAM,4CAA0C;;AAiB9D,SAAS,EAAc,GAA+B;CAGpD,IAAM,EAAE,SAAM,SAAM,GAAG,MAFH,KAAS,EAAE,EAIzB,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAElE,KAAc,GAAa,MAAmC;EAC9D,MAAM,KAAA,MACN,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;IAOf,IACJ,OAAO,KAAS,WAAW,IAAO,OAAO,EAAK,MAAO,WAAW,EAAK,KAAK;CAI5E,IAFA,EAAmB,EAAa,EAE5B,OAAO,KAAS,YAAY,OAAO,EAAK,MAAO,YAAY,MAAS,EAAK,IAC3E,MAAU,MAAM,yDAAqD;CAGvE,EAAW,QAAQ,EAAa;CAEhC,IAAM,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAoB;EAAE,GAAG;EAAM,OAAO;EAAa;CAMzD,OAJI,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAK,OAAO,IAGP;;AA8BT,SAAgB,EAAU,GAAe,GAA6C;CACpF,OAAO,EAAA,OAAuB,EAAc,EAAM,EAAE,EAAK;;AAa3D,SAAgB,EAAY,IAAmB,UAAgB"}