@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,32 @@
+/**
+ * Line and word break element factories.
+ *
+ * Provides framework-agnostic factory functions for elements that control
+ * line breaking and word breaking behaviour within text flow.
+ *
+ * These factories:
+ * - Create semantic HTML break elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured ARIA input where applicable.
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/break
+ * @since 0.1.0
+ */
+/**
+ * `<br>` element factory namespace.
+ *
+ * Represents a line break opportunity within text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/br
+ */
+export * as br from './br';
+/**
+ * `<wbr>` element factory namespace.
+ *
+ * Represents a word break opportunity within text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr
+ */
+export * as wbr from './wbr';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/elements/break/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,MAAM,CAAC;AAE3B;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC"}

package/dist/types/elements/break/wbr/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * pkgn-sol Design Foundation: Wbr element helpers.
+ *
+ * @remarks
+ * The wbr element (`<wbr>`) represents a word break opportunity.
+ *
+ * Best-practice guidance:
+ * - Use `<wbr>` to suggest optional break points within long words or URLs.
+ * - It does not force a line break; the browser decides if a break is needed.
+ * - Do not use `<wbr>` for layout or spacing. Use CSS instead.
+ * - `<wbr>` is a void element and must not contain text content.
+ *
+ * This module provides a small, framework-agnostic helper so consumers can:
+ * - create word break opportunities safely in vanilla JS/TS
+ * - apply consistent global attributes via pkgn-sol's hardened DOM helpers
+ * - rely on a stable enhancement hook for future evolution
+ *
+ * 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 labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for word break opportunity elements.
+ *
+ * @category Constants
+ */
+export declare const WBR_TAG: "wbr";
+/**
+ * A CSS selector targeting wbr elements.
+ *
+ * @category Constants
+ */
+export declare const WBR_SELECTOR = "wbr";
+/**
+ * Attribute bag for wbr creation/enhancement.
+ *
+ * @remarks
+ * `<wbr>` accepts only global HTML attributes.
+ * It does not accept text content and has no element-specific attributes.
+ *
+ * @category Attributes
+ */
+export type WbrAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a wbr element with optional global attributes.
+ *
+ * @remarks
+ * - `<wbr>` is a void element and does not accept text content.
+ * - 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 `<wbr>` element.
+ *
+ * @example
+ * ```ts
+ * import { createWbr } from "@lnpg/pkgn-sol/elements/break/wbr";
+ *
+ * paragraph.appendChild(createWbr());
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createWbr(attrs?: WbrAttrs): ElementOf<typeof WBR_TAG>;
+/**
+ * Enhance wbr elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * It exists to establish a stable enhancement pattern across all elements.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceWbrs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/break/wbr/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/break/wbr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,OAAO,EAAG,KAAc,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACjD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,OAAO,OAAO,CAAC,CAErE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG7D"}

package/dist/types/elements/container/div/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * pkgn-sol Design Foundation: Div element helpers.
+ *
+ * @remarks
+ * The div element (`<div>`) is a non-semantic, generic container.
+ *
+ * Best-practice guidance:
+ * - Prefer semantic elements when available (e.g. `<section>`, `<nav>`, `<article>`).
+ * - Use `<div>` as a last resort when no semantic element fits.
+ * - Avoid obsolete attributes like `align`; use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create div containers 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 (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 div containers.
+ *
+ * @category Constants
+ */
+export declare const DIV_TAG: "div";
+/**
+ * A CSS selector targeting div elements.
+ *
+ * @category Constants
+ */
+export declare const DIV_SELECTOR = "div";
+/**
+ * Attribute bag for div creation/enhancement.
+ *
+ * @remarks
+ * Div elements accept standard HTML global attributes.
+ *
+ * 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 DivAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a div element with optional text content and global 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.
+ *
+ * @param text - Optional text content for the div.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<div>` element.
+ *
+ * @example
+ * Create and append a div:
+ * ```ts
+ * import { createDiv } from "@lnpg/pkgn-sol/elements/container/div";
+ *
+ * document.body.appendChild(
+ *   createDiv("Hello.", { className: "box", id: "root" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDiv(text?: string, attrs?: DivAttrs): ElementOf<typeof DIV_TAG>;
+/**
+ * Enhance div 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 enhanceDivs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/container/div/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/container/div/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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,OAAO,EAAG,KAAc,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACjD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,OAAO,OAAO,CAAC,CAEpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG7D"}

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

@@ -0,0 +1,32 @@
+/**
+ * Container element factories.
+ *
+ * Provides framework-agnostic factory functions for generic container
+ * elements used to group flow or inline content.
+ *
+ * These factories:
+ * - Create semantic HTML elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured ARIA input.
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/container
+ * @since 0.1.0
+ */
+/**
+ * `<div>` element factory namespace.
+ *
+ * Represents a generic block-level container with no semantic meaning.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div
+ */
+export * as div from './div';
+/**
+ * `<span>` element factory namespace.
+ *
+ * Represents a generic inline container with no semantic meaning.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+ */
+export * as span from './span';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/elements/container/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC"}

package/dist/types/elements/container/span/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * pkgn-sol Design Foundation: Span element helpers.
+ *
+ * @remarks
+ * The `<span>` element is a generic inline container for phrasing content.
+ * It has no inherent semantics and should be used only when no more suitable
+ * semantic element exists.
+ *
+ * This module:
+ * - Creates `<span>` elements via pkgn-sol's DOM helpers (no direct DOM calls).
+ * - Applies a curated subset of global attributes safely.
+ * - Exposes an enhancement hook (currently a no-op) for consistency and
+ *   potential future progressive enhancements.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is a small, typed subset intended to prevent typo-driven ARIA bugs and
+ * keep the API practical. Values are mapped into {@link GlobalAttrs.aria}.
+ *
+ * @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 span.
+ *
+ * @category Constants
+ */
+export declare const SPAN_TAG: "span";
+/**
+ * A CSS selector targeting span elements.
+ *
+ * @category Constants
+ */
+export declare const SPAN_SELECTOR = "span";
+/**
+ * Attribute bag for span creation/enhancement.
+ *
+ * @remarks
+ * `<span>` supports HTML global attributes only.
+ *
+ * pkgn-sol additionally supports a typed, structured ARIA input that is mapped into
+ * {@link GlobalAttrs.aria} without modifying the shared DOM helpers.
+ *
+ * @category Attributes
+ */
+export type SpanAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a span element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which enforces:
+ *   - No inline event handler attributes (e.g. `onclick`)
+ *   - No raw `style` attribute injection (use the `style` object field)
+ *   - No empty attribute names
+ *
+ * @param text - Optional text content for the span.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<span>` element.
+ *
+ * @category DOM
+ */
+export declare function createSpan(text?: string, attrs?: SpanAttrs): ElementOf<typeof SPAN_TAG>;
+/**
+ * Enhance span elements within a given root.
+ *
+ * @remarks
+ * Intentionally a no-op in `0.1.0`. This exists to provide a stable, consistent
+ * integration hook across element modules.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceSpans(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/container/span/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/container/span/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;GAQG;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;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAClD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA0BF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,QAAQ,CAAC,CAEvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG9D"}

package/dist/types/elements/figure/figcaption/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * pkgn-sol Design Foundation: Figcaption element helpers.
+ *
+ * @remarks
+ * The figcaption element (`<figcaption>`) represents a caption or legend for
+ * the rest of the contents of its parent `<figure>` element.
+ *
+ * Best-practice guidance (summary):
+ * - Use `<figcaption>` as the caption for a `<figure>`.
+ * - Place it as the first or last child of the `<figure>` where possible.
+ * - Keep the visible caption text human-friendly and meaningful.
+ * - Do not use `<figcaption>` purely for styling. Use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<figcaption>` 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;
+};
+/**
+ * The semantic tag name for figcaption.
+ *
+ * @category Constants
+ */
+export declare const FIGCAPTION_TAG: "figcaption";
+/**
+ * A CSS selector targeting figcaption elements.
+ *
+ * @category Constants
+ */
+export declare const FIGCAPTION_SELECTOR = "figcaption";
+/**
+ * Attribute bag for figcaption creation/enhancement.
+ *
+ * @remarks
+ * `<figcaption>` supports standard HTML global attributes.
+ *
+ * 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 FigcaptionAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a figcaption 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.
+ *
+ * @param text - Optional text content for the figcaption element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<figcaption>` element.
+ *
+ * @example
+ * ```ts
+ * import { createFigcaption } from "@lnpg/pkgn-sol/elements/figure/figcaption";
+ *
+ * const c = createFigcaption("Kitchen layout, 2026", { className: "caption" });
+ * document.body.appendChild(c);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createFigcaption(text?: string, attrs?: FigcaptionAttrs): ElementOf<typeof FIGCAPTION_TAG>;
+/**
+ * Enhance figcaption 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 enhanceFigcaptions(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/figure/figcaption/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/figure/figcaption/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,cAAc,EAAG,YAAqB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACxD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,eAAe,GACtB,SAAS,CAAC,OAAO,cAAc,CAAC,CAElC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGpE"}

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

@@ -0,0 +1,124 @@
+/**
+ * pkgn-sol Design Foundation: Figure element helpers.
+ *
+ * @remarks
+ * The figure element (`<figure>`) represents self-contained content, optionally
+ * with a caption provided by a nested `<figcaption>`.
+ *
+ * Best-practice guidance:
+ * - Use `<figure>` for content referenced from the main flow but which could be
+ *   moved elsewhere without affecting the document's meaning.
+ * - If a caption is present, use `<figcaption>` as the first or last child.
+ * - Avoid using `<figure>` purely as a styling hook.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<figure>` 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.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure
+ *
+ * @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 figure.
+ *
+ * @category Constants
+ */
+export declare const FIGURE_TAG: "figure";
+/**
+ * A CSS selector targeting figure elements.
+ *
+ * @category Constants
+ */
+export declare const FIGURE_SELECTOR = "figure";
+/**
+ * Attribute bag for figure creation/enhancement.
+ *
+ * @remarks
+ * `<figure>` supports standard HTML global attributes only.
+ *
+ * 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 FigureAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a figure element with optional text content and global 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.
+ *
+ * Note: `<figure>` typically contains richer flow content (images, code blocks,
+ * quotes, etc.). This helper supports optional text for parity with other pkgn-sol
+ * element factories; consumers can append child nodes as needed.
+ *
+ * @param text - Optional text content for the figure.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<figure>` element.
+ *
+ * @example
+ * Create a figure and append custom content:
+ * ```ts
+ * import { createFigure } from "@lnpg/pkgn-sol/elements/figure/figure";
+ * import { createFigcaption } from "@lnpg/pkgn-sol/elements/figure/figcaption";
+ *
+ * const fig = createFigure(undefined, { className: "media" });
+ * fig.appendChild(document.createElement("img"));
+ * fig.appendChild(createFigcaption("Caption"));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createFigure(text?: string, attrs?: FigureAttrs): ElementOf<typeof FIGURE_TAG>;
+/**
+ * Enhance figure 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 enhanceFigures(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/figure/figure/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;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE7F;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}