@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/list/li/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * pkgn-sol Design Foundation: Li element helpers.
+ *
+ * @remarks
+ * The list item element (`<li>`) represents an item in a list.
+ *
+ * Best-practice guidance:
+ * - Use `<li>` only as a direct child of a list container (`<ul>`, `<ol>`, `<menu>`).
+ * - Prefer semantic list structure over styling hacks.
+ * - For ordered lists, use the `value` attribute/property to control numbering when needed
+ *   (e.g. continuing a sequence after inserted items).
+ * - Avoid the legacy `type` attribute where possible; prefer list-level semantics and CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<li>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - supply typed element-specific fields like `value`
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * Legacy marker type options for list items.
+ *
+ * @remarks
+ * The `type` attribute on `<li>` is legacy and should be avoided when possible.
+ * It is retained here for compatibility scenarios.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+ *
+ * @category Attributes
+ */
+export type LiMarkerType = '1' | 'a' | 'A' | 'i' | 'I';
+/**
+ * The semantic tag name for list items.
+ *
+ * @category Constants
+ */
+export declare const LI_TAG: "li";
+/**
+ * A CSS selector targeting list item elements.
+ *
+ * @category Constants
+ */
+export declare const LI_SELECTOR = "li";
+/**
+ * Attribute bag for li creation/enhancement.
+ *
+ * @remarks
+ * In addition to global attributes, `<li>` supports:
+ * - `value` (primarily for `<ol>` numbering control)
+ * - legacy `type` marker hint (deprecated)
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+ *
+ * @category Attributes
+ */
+export type LiAttrs = Omit<GlobalAttrs, 'aria' | 'attrs'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Ordinal value for ordered lists.
+     *
+     * @remarks
+     * When used within an `<ol>`, this sets the list item's numbering value.
+     * This is modeled as a number and applied via the `HTMLLIElement.value` property.
+     */
+    value?: number;
+    /**
+     * Legacy marker type hint (deprecated).
+     *
+     * @remarks
+     * Prefer list semantics and CSS. Retained for compatibility.
+     */
+    type?: LiMarkerType;
+    /**
+     * Additional attributes not modeled above.
+     *
+     * @remarks
+     * This exists as an escape hatch while still allowing pkgn-sol to apply its
+     * attribute safety rules via `dom.ts`.
+     */
+    attrs?: GlobalAttrs['attrs'];
+};
+/**
+ * Create a list item element with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ * - The `value` field is applied via the `HTMLLIElement.value` property for correct behavior.
+ *
+ * @param text - Optional text content for the list item.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<li>` element.
+ *
+ * @example
+ * ```ts
+ * import { createLi } from "@lnpg/pkgn-sol/elements/list/li";
+ *
+ * const li = createLi("Item 3", { value: 3 });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createLi(text?: string, attrs?: LiAttrs): ElementOf<typeof LI_TAG>;
+/**
+ * Enhance list item elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceLis(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/list/li/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/list/li/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG;IAC1D;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC9B,CAAC;AAoCF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CASjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

package/dist/types/elements/list/ol/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * pkgn-sol Design Foundation: Ordered list element helpers.
+ *
+ * @remarks
+ * The ordered list element (`<ol>`) represents an ordered list of items.
+ *
+ * Best-practice guidance:
+ * - Prefer `<ol>` when the order of items matters (steps, rankings, sequences).
+ * - List items should be `<li>` elements (direct children).
+ * - Avoid presentational attributes when possible; prefer CSS for styling.
+ * - Use `start`/`reversed` only when semantics require non-default numbering.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create ordered lists in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for ordered lists.
+ *
+ * @category Constants
+ */
+export declare const OL_TAG: "ol";
+/**
+ * A CSS selector targeting ordered list elements.
+ *
+ * @category Constants
+ */
+export declare const OL_SELECTOR = "ol";
+/**
+ * Allowed values for the `<ol>` `type` attribute.
+ *
+ * @remarks
+ * While `type` is still supported by browsers, it is presentational and CSS is
+ * often preferable.
+ *
+ * - `1`  Decimal numbers (default)
+ * - `a`  Lowercase letters
+ * - `A`  Uppercase letters
+ * - `i`  Lowercase Roman numerals
+ * - `I`  Uppercase Roman numerals
+ *
+ * @category Attributes
+ */
+export type OlType = '1' | 'a' | 'A' | 'i' | 'I';
+/**
+ * Attribute bag for ordered list creation/enhancement.
+ *
+ * @remarks
+ * Ordered lists accept HTML global attributes and a small set of specific
+ * attributes:
+ * - `reversed` for descending numbering
+ * - `start` to set the initial counter value
+ * - `type` to choose the marker style (often better via CSS)
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type OlAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Whether numbering should be descending.
+     */
+    reversed?: boolean;
+    /**
+     * Starting value for the list counter.
+     */
+    start?: number;
+    /**
+     * Marker type for list items.
+     */
+    type?: OlType;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an ordered list element with global and list-specific attributes.
+ *
+ * @remarks
+ * This helper intentionally does not accept raw HTML. Consumers should append
+ * `<li>` children using DOM APIs.
+ *
+ * Global attributes are applied via pkgn-sol's shared DOM helper, including security
+ * guards that block inline event handler attributes (e.g. `onclick`) and raw
+ * `style` attribute strings.
+ *
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<ol>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOl } from "@lnpg/pkgn-sol/elements/list/ol";
+ *
+ * const ol = createOl({ start: 3, reversed: true, className: "steps" });
+ * document.body.appendChild(ol);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createOl(attrs?: OlAttrs): ElementOf<typeof OL_TAG>;
+/**
+ * Enhance ordered list elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceOls(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/list/ol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/list/ol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAChD;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA0BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CAWlE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

package/dist/types/elements/list/ul/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * pkgn-sol Design Foundation: Unordered list (ul) element helpers.
+ *
+ * @remarks
+ * The unordered list element (`<ul>`) represents a list of items where the
+ * order does not change the meaning.
+ *
+ * Best-practice guidance:
+ * - Use `<ul>` for lists where sequence is not meaningful (use `<ol>` when it is).
+ * - Ensure list children are `<li>` elements.
+ * - Do not use `<ul>` purely for indentation or spacing; use CSS for layout.
+ * - The legacy `type` attribute is obsolete; prefer `list-style-type` in CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<ul>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - optionally set legacy presentation attributes in a controlled way
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for unordered lists.
+ *
+ * @category Constants
+ */
+export declare const UL_TAG: "ul";
+/**
+ * A CSS selector targeting unordered list elements.
+ *
+ * @category Constants
+ */
+export declare const UL_SELECTOR = "ul";
+/**
+ * Legacy marker style values for `<ul type="...">`.
+ *
+ * @remarks
+ * The `type` attribute is obsolete in HTML5. Prefer CSS `list-style-type`.
+ * This is included as a pragmatic escape hatch for legacy markup needs.
+ *
+ * @category Attributes
+ */
+export type UlLegacyType = 'disc' | 'circle' | 'square';
+/**
+ * Attribute bag for ul creation/enhancement.
+ *
+ * @remarks
+ * `<ul>` primarily accepts standard HTML global attributes.
+ *
+ * pkgn-sol also supports:
+ * - structured ARIA input mapped into `aria-*`
+ * - optional legacy `type` mapping to the `type` attribute (obsolete)
+ * - an `attrs` escape hatch, still guarded by pkgn-sol's attribute safety rules
+ *
+ * @category Attributes
+ */
+export type UlAttrs = Omit<GlobalAttrs, 'aria' | 'attrs'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Legacy bullet style hint mapped to the `type` attribute (obsolete).
+     *
+     * @remarks
+     * Prefer CSS `list-style-type` instead.
+     */
+    type?: UlLegacyType;
+    /**
+     * Additional attributes not modeled above.
+     *
+     * @remarks
+     * This exists as an escape hatch while still allowing pkgn-sol to apply its
+     * attribute safety rules via `dom.ts`.
+     */
+    attrs?: GlobalAttrs['attrs'];
+};
+/**
+ * Create an unordered list (`<ul>`) with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - In real documents, `<ul>` should contain `<li>` children, not raw text.
+ *   The optional `text` parameter exists for consistency with pkgn-sol factories and
+ *   testing convenience.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the ul.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<ul>` element.
+ *
+ * @example
+ * ```ts
+ * import { createUl } from "@lnpg/pkgn-sol/elements/list/ul";
+ *
+ * const ul = createUl(undefined, { id: "features" });
+ * document.body.appendChild(ul);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createUl(text?: string, attrs?: UlAttrs): ElementOf<typeof UL_TAG>;
+/**
+ * Enhance unordered list elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceUls(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/list/ul/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/list/ul/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG;IAC1D;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC9B,CAAC;AAoCF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

package/dist/types/elements/media/audio/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * pkgn-sol Design Foundation: Audio element helpers.
+ *
+ * @remarks
+ * The audio element (`<audio>`) embeds sound content in documents.
+ * It can load audio via `src` or nested `<source>` elements, and it can
+ * also be a destination for streamed media via MediaStream.
+ *
+ * Best-practice guidance (MDN + platform norms):
+ * - Avoid autoplaying audio unless the user explicitly opts in.
+ * - Prefer showing controls (`controls`) when audio playback is user-facing.
+ * - Use `preload="metadata"` as a sensible hint if you want duration, etc.
+ * - Use CORS (`crossOrigin`) when audio might be reused by `<canvas>` without tainting.
+ * - Prefer multiple `<source>` elements for format fallbacks where needed.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create audio elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * Allowed `preload` values for media elements.
+ *
+ * @remarks
+ * Per MDN, browsers treat this as a hint and may ignore it; `metadata` is a
+ * common best-practice default in specs/guidance.
+ *
+ * @category Attributes
+ */
+export type AudioPreload = 'none' | 'metadata' | 'auto';
+/**
+ * Allowed values for the `crossorigin` attribute for media fetches.
+ *
+ * @category Attributes
+ */
+export type AudioCrossOrigin = 'anonymous' | 'use-credentials';
+/**
+ * Allowed tokens for the `controlslist` attribute (when `controls` is enabled).
+ *
+ * @remarks
+ * MDN lists allowed values including `nodownload`, `nofullscreen`, `noremoteplayback`.
+ * (`nofullscreen` is effectively video-oriented but is still a valid token in the attribute.)
+ *
+ * @category Attributes
+ */
+export type AudioControlsList = 'nodownload' | 'nofullscreen' | 'noremoteplayback';
+/**
+ * The semantic tag name for audio elements.
+ *
+ * @category Constants
+ */
+export declare const AUDIO_TAG: "audio";
+/**
+ * A CSS selector targeting audio elements.
+ *
+ * @category Constants
+ */
+export declare const AUDIO_SELECTOR = "audio";
+/**
+ * Attribute bag for audio creation/enhancement.
+ *
+ * @remarks
+ * Audio elements accept HTML global attributes plus a media-specific subset.
+ * pkgn-sol also supports structured ARIA input for common ARIA fields.
+ *
+ * @category Attributes
+ */
+export type AudioAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * The URL of the audio resource to embed.
+     *
+     * @remarks
+     * Optional if you instead provide nested `<source>` elements.
+     */
+    src?: string;
+    /**
+     * Whether browser playback controls should be shown.
+     */
+    controls?: boolean;
+    /**
+     * Whether playback should begin automatically.
+     *
+     * @remarks
+     * Autoplaying audio is often blocked unless user-initiated. If `autoplay`
+     * is enabled and `muted` is not specified, pkgn-sol defaults `muted` to `true`
+     * as a pragmatic alignment with autoplay policies.
+     */
+    autoplay?: boolean;
+    /**
+     * Whether the audio should loop back to the start after ending.
+     */
+    loop?: boolean;
+    /**
+     * Whether the audio should start out muted.
+     */
+    muted?: boolean;
+    /**
+     * Hint about how much to preload.
+     */
+    preload?: AudioPreload;
+    /**
+     * CORS mode for fetching the audio resource.
+     */
+    crossOrigin?: AudioCrossOrigin;
+    /**
+     * Restrict which built-in controls the user agent exposes (when `controls` is set).
+     *
+     * @example
+     * controlsList: ['nodownload', 'noremoteplayback']
+     */
+    controlsList?: AudioControlsList[];
+    /**
+     * Disable remote playback (Chromecast/AirPlay/etc).
+     */
+    disableRemotePlayback?: boolean;
+};
+/**
+ * Create an audio element with optional attributes.
+ *
+ * @remarks
+ * Global attributes are applied via pkgn-sol's shared DOM helper, including security
+ * guards that block inline event handler attributes (e.g. `onclick`) and raw
+ * `style` attribute strings through escape hatches.
+ *
+ * Media-specific attributes are applied directly to the element.
+ *
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<audio>` element.
+ *
+ * @example
+ * ```ts
+ * import { createAudio } from "@lnpg/pkgn-sol/elements/media/audio";
+ *
+ * document.body.appendChild(
+ *   createAudio({ controls: true, src: "/audio/intro.mp3", preload: "metadata" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createAudio(attrs?: AudioAttrs): ElementOf<typeof AUDIO_TAG>;
+/**
+ * Enhance audio elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceAudios(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/media/audio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/media/audio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAE/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEnC;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAmC3E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}