@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/responsive/area/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * pkgn-sol Design Foundation: Area element helpers.
+ *
+ * @remarks
+ * The area element (`<area>`) defines a hyperlink or dead region within an image map.
+ * It is used inside a `<map>` element to define clickable (or non-clickable) areas.
+ *
+ * Best-practice guidance:
+ * - Use `<area>` only within `<map>` and pair with an `<img usemap="...">`.
+ * - Prefer meaningful alternative text for clickable regions (screen readers rely on it).
+ * - Keep shapes and coordinates accurate; imprecise maps are a usability disaster.
+ *
+ * Spec-aware pkgn-sol behavior:
+ * - If `href` is provided: `alt` is required, and pkgn-sol will ensure an `alt` attribute
+ *   exists (defaults to empty string if not provided).
+ * - If `href` is not provided: `alt` must be omitted, and pkgn-sol will omit it.
+ *
+ * Global attributes are applied via pkgn-sol's hardened DOM helpers (`dom.ts`), which block:
+ * - inline event handler attributes (e.g. `onclick`)
+ * - the raw `style` attribute string (use `style` object instead)
+ *
+ * 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.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for area elements.
+ *
+ * @category Constants
+ */
+export declare const AREA_TAG: "area";
+/**
+ * A CSS selector targeting area elements.
+ *
+ * @category Constants
+ */
+export declare const AREA_SELECTOR = "area";
+/**
+ * Enumerated shape values for `<area>`.
+ *
+ * @remarks
+ * The default (when omitted) is effectively `rect` in HTML's image map processing model,
+ * but pkgn-sol does not force a default; it passes through what you provide.
+ *
+ * @category Types
+ */
+export type AreaShape = 'rect' | 'circle' | 'poly' | 'default';
+/**
+ * Area-specific attributes.
+ *
+ * @remarks
+ * `<area>` largely mirrors hyperlink-related attributes when `href` is present.
+ * pkgn-sol enforces the spec rule around `alt`:
+ * - `href` present => `alt` must be present (pkgn-sol ensures it exists)
+ * - `href` absent  => `alt` must be omitted (pkgn-sol omits it)
+ *
+ * @category Attributes
+ */
+export type AreaAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Alternative text for the area.
+     *
+     * @remarks
+     * Only applied when `href` is present. If `href` is present and `alt` is not
+     * provided, pkgn-sol defaults it to `""`. If `href` is absent, pkgn-sol omits `alt`
+     * entirely.
+     */
+    alt?: string;
+    /**
+     * Link target URL. When present, the area represents a hyperlink.
+     */
+    href?: string;
+    /**
+     * The shape of the area. Common values: `rect`, `circle`, `poly`, `default`.
+     */
+    shape?: AreaShape;
+    /**
+     * Coordinates defining the area geometry. Interpretation depends on `shape`.
+     */
+    coords?: string;
+    /**
+     * Where to display the linked URL (e.g. `_blank`).
+     */
+    target?: string;
+    /**
+     * Whether to download the linked resource instead of navigating.
+     *
+     * @remarks
+     * May be a boolean (attribute presence) or a suggested filename.
+     */
+    download?: boolean | string;
+    /**
+     * A space-separated list of URLs to ping when the link is followed.
+     */
+    ping?: string;
+    /**
+     * Relationship of the target object to the linking object.
+     */
+    rel?: string;
+    /**
+     * Referrer policy for the link.
+     */
+    referrerPolicy?: string;
+    /**
+     * Language of the linked resource (BCP 47 tag).
+     */
+    hreflang?: string;
+    /**
+     * MIME type of the linked resource (advisory).
+     */
+    type?: string;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an area element with spec-aware `alt` handling.
+ *
+ * @remarks
+ * - `<area>` is a void element (no text content).
+ * - If `href` is present, pkgn-sol ensures `alt` is present (defaults to `""`).
+ * - If `href` is absent, pkgn-sol omits `alt`.
+ *
+ * @category DOM
+ */
+export declare function createArea(attrs?: AreaAttrs): ElementOf<typeof AREA_TAG>;
+/**
+ * Enhance area elements within a given root.
+ *
+ * @remarks
+ * No runtime behaviour in v0.1.0.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceAreas(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/responsive/area/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/responsive/area/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;;;GAIG;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,QAAQ,EAAG,MAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAClD;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAE5B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAgEF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,QAAQ,CAAC,CAExE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAE9D"}

package/dist/types/elements/responsive/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Responsive media element factories.
+ *
+ * Provides framework-agnostic factory functions for HTML elements commonly used
+ * to deliver responsive, adaptive, and accessible media experiences.
+ *
+ * These factories:
+ * - Create semantic responsive/media structures using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct relationships between media resources and their metadata
+ *   (e.g. `<picture>` + `<source>`, media maps via `<map>` + `<area>`, and timed
+ *   text via `<track>`).
+ * - Prevent unsafe attribute injection.
+ *
+ * The elements in this module support native browser features for responsive
+ * images, image maps, and timed text tracks without framework assumptions.
+ *
+ * @module elements/responsive
+ * @since 0.1.0
+ */
+/**
+ * `<area>` element factory namespace.
+ *
+ * Represents a clickable hotspot region within an image map, associated with a
+ * `<map>` element. Typically paired with an `<img usemap="...">`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area
+ */
+export * as area from './area';
+/**
+ * `<map>` element factory namespace.
+ *
+ * Represents an image map container holding `<area>` definitions that describe
+ * interactive regions on an associated image.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/map
+ */
+export * as map from './map';
+/**
+ * `<picture>` element factory namespace.
+ *
+ * Represents a container for responsive images, allowing multiple `<source>`
+ * candidates and a fallback `<img>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture
+ */
+export * as picture from './picture';
+/**
+ * `<source>` element factory namespace.
+ *
+ * Represents a media resource candidate for `<picture>`, `<audio>`, or
+ * `<video>`, selected by the browser based on type/media conditions.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source
+ */
+export * as source from './source';
+/**
+ * `<track>` element factory namespace.
+ *
+ * Represents an external timed text track (subtitles, captions, descriptions,
+ * chapters, or metadata) for `<audio>` or `<video>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track
+ */
+export * as track from './track';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/responsive/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/elements/responsive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;GAOG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;;GAOG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AAErC;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC"}

package/dist/types/elements/responsive/map/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * pkgn-sol Design Foundation: Map element helpers.
+ *
+ * @remarks
+ * The map element (`<map>`) defines an image map: a set of clickable regions
+ * (typically via descendant `<area>` elements) that can be referenced from an
+ * `<img>` (or other image-like element) using the `usemap` attribute.
+ *
+ * Best-practice guidance:
+ * - Always provide a meaningful, unique `name` for the map.
+ * - Use `<area>` children to define interactive regions.
+ * - Keep `name` free of whitespace and ensure it is unique within the document/tree.
+ * - If you also set `id`, it should match `name` (spec requirement).
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<map>` element
+ * - WHATWG HTML: map element and `name` requirements
+ *
+ * @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 map.
+ *
+ * @category Constants
+ */
+export declare const MAP_TAG: "map";
+/**
+ * A CSS selector targeting map elements.
+ *
+ * @category Constants
+ */
+export declare const MAP_SELECTOR = "map";
+/**
+ * Attribute bag for map creation/enhancement.
+ *
+ * @remarks
+ * Element-specific attributes:
+ * - `name` (required by spec for referencing via `usemap`)
+ *
+ * Spec notes:
+ * - `name` must be present, non-empty, and contain no ASCII whitespace.
+ * - If `id` is also specified, it must match `name`.
+ *
+ * pkgn-sol behavior:
+ * - If `name` is omitted, pkgn-sol provides a deterministic fallback:
+ *   - uses `id` if provided
+ *   - otherwise defaults to `"map"`
+ *   Callers should set a unique name in real documents.
+ *
+ * @category Attributes
+ */
+export type MapAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Name of the image map.
+     *
+     * @remarks
+     * Used by `<img usemap="#NAME">` to reference this `<map>`.
+     */
+    name?: string;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a map element with optional text content and attributes.
+ *
+ * @remarks
+ * While `<map>` typically contains `<area>` elements (not text), pkgn-sol still
+ * supports optional `text` for:
+ * - fallback content
+ * - simple labelling in environments that inspect textContent
+ *
+ * - Text 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.
+ *
+ * @param text - Optional text content.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<map>` element.
+ *
+ * @example
+ * ```ts
+ * import { createMap } from "@lnpg/pkgn-sol/elements/responsive/map";
+ *
+ * const m = createMap(undefined, { name: "product-map" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createMap(text?: string, attrs?: MapAttrs): ElementOf<typeof MAP_TAG>;
+/**
+ * Enhance map 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 enhanceMaps(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/responsive/map/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/responsive/map/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElG;;;;;;;;;;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,OAAO,EAAG,KAAc,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACjD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAiFF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,OAAO,OAAO,CAAC,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG7D"}

package/dist/types/elements/responsive/picture/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * pkgn-sol Design Foundation: Picture element helpers.
+ *
+ * @remarks
+ * The picture element (`<picture>`) is a container used for responsive images.
+ * It allows authors to provide multiple image sources (typically via child
+ * `<source>` elements) and a required fallback `<img>` element.
+ *
+ * Best-practice guidance:
+ * - Always include an `<img>` inside `<picture>` as the fallback and for
+ *   accessibility. The alternative text (`alt`) belongs on the `<img>`, not on
+ *   `<picture>`.
+ * - Use `<source>` elements with `media` and/or `type` to provide format and
+ *   breakpoint-specific sources.
+ * - Prefer modern formats (e.g. AVIF/WebP) with a sensible fallback.
+ *
+ * pkgn-sol-specific conventions:
+ * - `<picture>` has no element-specific attributes; this module applies global
+ *   attributes via pkgn-sol's hardened DOM helpers (`dom.ts`), which block inline
+ *   event handler attributes (e.g. `onclick`) and the raw `style` attribute
+ *   string.
+ * - Supports a small structured ARIA input to reduce typo-based ARIA bugs.
+ *
+ * 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 mapped into {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for picture containers.
+ *
+ * @category Constants
+ */
+export declare const PICTURE_TAG: "picture";
+/**
+ * A CSS selector targeting picture elements.
+ *
+ * @category Constants
+ */
+export declare const PICTURE_SELECTOR = "picture";
+/**
+ * Attribute bag for picture creation/enhancement.
+ *
+ * @remarks
+ * `<picture>` does not define unique attributes; it is a container that affects
+ * image source selection in conjunction with child `<source>` and `<img>`.
+ *
+ *
+ * pkgn-sol supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type PictureAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a picture element with optional global attributes.
+ *
+ * @remarks
+ * `<picture>` is a container; authors must append a fallback `<img>` and any
+ * `<source>` children. The alternative text (`alt`) is provided on the `<img>`.
+ *
+ *
+ * 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 `<picture>` element.
+ *
+ * @example
+ * ```ts
+ * import { createPicture } from "@lnpg/pkgn-sol/elements/responsive/picture";
+ *
+ * const p = createPicture({ className: "hero-media" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createPicture(attrs?: PictureAttrs): ElementOf<typeof PICTURE_TAG>;
+/**
+ * Enhance picture 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 enhancePictures(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/responsive/picture/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/responsive/picture/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;GAOG;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,WAAW,EAAG,SAAkB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACrD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGjE"}

package/dist/types/elements/responsive/source/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * pkgn-sol Design Foundation: Source element helpers.
+ *
+ * @remarks
+ * The source element (`<source>`) provides one or more media resources for:
+ * - `<picture>` (responsive images via `srcset`/`sizes`)
+ * - `<audio>` / `<video>` (alternate encodings via `src`)
+ *
+ * Best-practice guidance:
+ * - Use `<picture><source srcset ...></picture>` for responsive images and art direction.
+ * - Use multiple `<source>` children under `<audio>/<video>` to provide fallback formats.
+ * - Prefer providing a `type` when possible to help user agents skip unsupported formats.
+ * - Use `media` to gate sources behind media conditions.
+ * - Only use `sizes` when `srcset` is present (it is meaningless otherwise).
+ *
+ * Attributes (element-specific):
+ * - `src` (string): media resource URL (primarily for `<audio>/<video>` contexts).
+ * - `srcSet` (string): source set candidates (primarily for `<picture>` contexts).
+ * - `sizes` (string): sizes list for `srcset` selection.
+ * - `type` (string): MIME type hint.
+ * - `media` (string): media query condition.
+ *
+ * Notes:
+ * - `<source>` is a void element (no text content).
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which
+ *   block inline event handler attributes (e.g. `onclick`) and raw `style`
+ *   attribute injection (use the `style` object field instead).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source
+ *
+ * @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 (e.g. `lable`).
+ *
+ * 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 source.
+ *
+ * @category Constants
+ */
+export declare const SOURCE_TAG: "source";
+/**
+ * A CSS selector targeting source elements.
+ *
+ * @category Constants
+ */
+export declare const SOURCE_SELECTOR = "source";
+/**
+ * Attribute bag for source creation/enhancement.
+ *
+ * @remarks
+ * Source elements accept standard HTML global attributes plus source-specific
+ * content attributes used by `<picture>`, `<audio>`, and `<video>`.
+ *
+ * pkgn-sol supports structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * Validation rules enforced by this module:
+ * - `sizes` may only be specified when `srcSet` is provided.
+ * - At least one of `src` or `srcSet` must be provided (a `<source>` without a
+ *   resource is not useful).
+ *
+ * @category Attributes
+ */
+export type SourceAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Media resource URL.
+     *
+     * @remarks
+     * Primarily used by `<audio>` and `<video>`. It is ignored when the `<source>`
+     * is nested inside `<picture>`.
+     */
+    src?: string;
+    /**
+     * Image candidate source set.
+     *
+     * @remarks
+     * Primarily used by `<picture>` responsive images.
+     * Maps to the `srcset` content attribute.
+     */
+    srcSet?: string;
+    /**
+     * Sizes list describing the intended display size for `srcset` selection.
+     *
+     * @remarks
+     * Only meaningful when `srcset` is present.
+     */
+    sizes?: string;
+    /**
+     * Media query condition for selecting this source.
+     */
+    media?: string;
+    /**
+     * MIME type hint for the resource(s).
+     */
+    type?: string;
+};
+/**
+ * Create a source element with attributes.
+ *
+ * @remarks
+ * `<source>` is a void element: it never carries text content.
+ *
+ * Global attributes and escape-hatch 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 `<source>` element.
+ *
+ * @example
+ * Responsive image source (picture):
+ * ```ts
+ * import { createSource } from "@lnpg/pkgn-sol/elements/responsive/source";
+ *
+ * const s = createSource({
+ *   srcSet: "/img/hero-800.jpg 800w, /img/hero-1600.jpg 1600w",
+ *   sizes: "(max-width: 800px) 100vw, 800px",
+ *   type: "image/jpeg"
+ * });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSource(attrs?: SourceAttrs): ElementOf<typeof SOURCE_TAG>;
+/**
+ * Enhance source 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 enhanceSources(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/responsive/source/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/responsive/source/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;;;;;;;;;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,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAwDF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}