@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/inline/sup/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * pkgn-sol Design Foundation: Sup element helpers.
+ *
+ * @remarks
+ * The sup element (`<sup>`) represents superscript text.
+ *
+ * Best-practice guidance:
+ * - Use `<sup>` for semantic superscripts such as footnote markers, ordinal indicators,
+ *   and mathematical exponents.
+ * - Avoid using `<sup>` purely for visual styling; prefer CSS when semantics are not intended.
+ * - For footnotes, consider pairing markers with accessible labelling (e.g. via `aria-label`)
+ *   and appropriate linking patterns.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create superscript nodes 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/sup
+ *
+ * @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 superscript elements.
+ *
+ * @category Constants
+ */
+export declare const SUP_TAG: "sup";
+/**
+ * A CSS selector targeting sup elements.
+ *
+ * @category Constants
+ */
+export declare const SUP_SELECTOR = "sup";
+/**
+ * Attribute bag for sup creation/enhancement.
+ *
+ * @remarks
+ * Sup 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 SupAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a sup 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 sup.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<sup>` element.
+ *
+ * @example
+ * Create a footnote marker:
+ * ```ts
+ * import { createSup } from "@lnpg/pkgn-sol/elements/inline/sup";
+ *
+ * const marker = createSup("1", { aria: { label: "Footnote 1" } });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSup(text?: string, attrs?: SupAttrs): ElementOf<typeof SUP_TAG>;
+/**
+ * Enhance sup 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 enhanceSups(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/sup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/sup/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,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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/inline/time/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * pkgn-sol Design Foundation: Time element helpers.
+ *
+ * @remarks
+ * The time element (`<time>`) represents a specific period in time.
+ *
+ * Best-practice guidance (summary):
+ * - Provide a machine-readable `datetime` value when possible.
+ * - Keep visible text human-friendly (e.g. "Tomorrow", "12 Feb 2026").
+ * - Avoid using `<time>` purely for styling.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<time>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - supply a typed `datetime`/`dateTime` field mapped to the `datetime` attribute
+ *
+ * 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 time.
+ *
+ * @category Constants
+ */
+export declare const TIME_TAG: "time";
+/**
+ * A CSS selector targeting time elements.
+ *
+ * @category Constants
+ */
+export declare const TIME_SELECTOR = "time";
+/**
+ * Attribute bag for time creation/enhancement.
+ *
+ * @remarks
+ * In addition to global attributes, `<time>` commonly uses the `datetime`
+ * attribute to provide a machine-readable value.
+ *
+ * pkgn-sol supports:
+ * - `datetime` (preferred, aligns with the HTML attribute name)
+ * - `dateTime` (alias for ergonomic camelCase usage)
+ *
+ * @category Attributes
+ */
+export type TimeAttrs = Omit<GlobalAttrs, 'aria' | 'attrs'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Machine-readable time value, mapped to the `datetime` attribute.
+     *
+     * @remarks
+     * Examples:
+     * - `2026-02-25`
+     * - `2026-02-25T16:30:00Z`
+     * - `PT2H`
+     *
+     * If a {@link Date} is provided, it is converted via `toISOString()`.
+     */
+    datetime?: string | Date;
+    /**
+     * Alias of {@link TimeAttrs.datetime}.
+     *
+     * @remarks
+     * Supported for ergonomic camelCase input. If both are provided, `datetime`
+     * takes precedence.
+     */
+    dateTime?: string | Date;
+    /**
+     * 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 time 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 time element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<time>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTime } from "@lnpg/pkgn-sol/elements/inline/time";
+ *
+ * const t = createTime("25 Feb 2026", { datetime: "2026-02-25" });
+ * document.body.appendChild(t);
+ * ```
+ *
+ * @example
+ * Using the `dateTime` alias:
+ * ```ts
+ * const t = createTime("25 Feb 2026", { dateTime: "2026-02-25" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createTime(text?: string, attrs?: TimeAttrs): ElementOf<typeof TIME_TAG>;
+/**
+ * Enhance time 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 enhanceTimes(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/time/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/time/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,QAAQ,EAAG,MAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG;IAC5D;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC9B,CAAC;AA2CF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,QAAQ,CAAC,CAEvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG9D"}

package/dist/types/elements/inline/u/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * pkgn-sol Design Foundation: U element helpers.
+ *
+ * @remarks
+ * The u element (`<u>`) represents a span of text with an unarticulated,
+ * explicitly rendered non-textual annotation.
+ *
+ * Best-practice guidance:
+ * - Do not use `<u>` purely for underlining text. Use CSS (`text-decoration`) for
+ *   presentation.
+ * - Use `<u>` only when the semantics are appropriate (e.g. marking misspellings
+ *   or other non-textual annotations).
+ * - Avoid usage where it could be confused with a hyperlink.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create u elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u
+ *
+ * @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 unarticulated annotation spans.
+ *
+ * @category Constants
+ */
+export declare const U_TAG: "u";
+/**
+ * A CSS selector targeting u elements.
+ *
+ * @category Constants
+ */
+export declare const U_SELECTOR = "u";
+/**
+ * Attribute bag for u creation/enhancement.
+ *
+ * @remarks
+ * U 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 UAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a u 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 u element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<u>` element.
+ *
+ * @example
+ * ```ts
+ * import { createU } from "@lnpg/pkgn-sol/elements/inline/u";
+ *
+ * const misspelt = createU("teh", { aria: { label: "Misspelt word" } });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createU(text?: string, attrs?: UAttrs): ElementOf<typeof U_TAG>;
+/**
+ * Enhance u 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 enhanceUs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/u/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/u/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,KAAK,EAAG,GAAY,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAC/C;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,KAAK,CAAC,CAE9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG3D"}

package/dist/types/elements/inline/var/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * pkgn-sol Design Foundation: Var element helpers.
+ *
+ * @remarks
+ * The var element (`<var>`) represents a variable name in a mathematical
+ * expression or programming context. Browsers typically render it in italics
+ * by default, but presentation should be handled via CSS.
+ *
+ * Best-practice guidance:
+ * - Use `<var>` specifically for variables (e.g. `x`, `y`, `n`, `userId`).
+ * - Use `<code>` for code fragments, `<kbd>` for user input, and `<samp>` for
+ *   sample output, rather than overloading `<var>`.
+ * - Keep semantics clean: `<var>` is inline and should not be used as a generic
+ *   styling hook.
+ *
+ * pkgn-sol provides small, framework-agnostic helpers so consumers can:
+ * - create `<var>` 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/var
+ *
+ * @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 var elements.
+ *
+ * @category Constants
+ */
+export declare const VAR_TAG: "var";
+/**
+ * A CSS selector targeting var elements.
+ *
+ * @category Constants
+ */
+export declare const VAR_SELECTOR = "var";
+/**
+ * Attribute bag for var creation/enhancement.
+ *
+ * @remarks
+ * The `<var>` element accepts 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 VarAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a var 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 var element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<var>` element.
+ *
+ * @example
+ * ```ts
+ * import { createVar } from "@lnpg/pkgn-sol/elements/inline/var";
+ *
+ * const v = createVar("n", { className: "symbol" });
+ * document.body.appendChild(v);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createVar(text?: string, attrs?: VarAttrs): ElementOf<typeof VAR_TAG>;
+/**
+ * Enhance var 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 enhanceVars(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/var/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/var/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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/interactive/details/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * pkgn-sol Design Foundation: Details element helpers.
+ *
+ * @remarks
+ * The details element (`<details>`) creates a disclosure widget where content is
+ * shown/hidden by toggling the element open/closed. (MDN) :contentReference[oaicite:3]{index=3}
+ *
+ * Best-practice guidance:
+ * - Provide a visible label using a child `<summary>` element; it acts as the
+ *   interactive control for toggling the parent `<details>`. (MDN) :contentReference[oaicite:4]{index=4}
+ * - Use the `open` attribute to render expanded by default. (MDN) :contentReference[oaicite:5]{index=5}
+ * - If using the `name` attribute to create a mutually-exclusive group, authors
+ *   must avoid markup where more than one element in the same name group has
+ *   `open` present. User agents may enforce exclusivity by changing `open`.
+ *   (WHATWG) :contentReference[oaicite:6]{index=6}
+ *
+ * pkgn-sol-specific conventions:
+ * - 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 details disclosure widgets.
+ *
+ * @category Constants
+ */
+export declare const DETAILS_TAG: "details";
+/**
+ * A CSS selector targeting details elements.
+ *
+ * @category Constants
+ */
+export declare const DETAILS_SELECTOR = "details";
+/**
+ * Attribute bag for details creation/enhancement.
+ *
+ * @remarks
+ * `<details>` accepts global attributes plus:
+ * - `open` (boolean attribute)
+ * - `name` (creates a mutually-exclusive details name group, per spec)
+ *
+ * `name` grouping behavior is specified by HTML; pkgn-sol does not enforce group
+ * constraints at runtime. (WHATWG) :contentReference[oaicite:7]{index=7}
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type DetailsAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Whether the details is open (expanded) by default.
+     *
+     * @remarks
+     * This maps to the boolean `open` attribute. (MDN) :contentReference[oaicite:8]{index=8}
+     */
+    open?: boolean;
+    /**
+     * Name of a mutually-exclusive details group.
+     *
+     * @remarks
+     * Details with the same `name` may form an exclusive group where at most one
+     * is open at a time. (WHATWG) :contentReference[oaicite:9]{index=9}
+     */
+    name?: string;
+};
+/**
+ * Create a details element with optional attributes.
+ *
+ * @remarks
+ * - Provide a child `<summary>` for the visible label/toggle control. (MDN) :contentReference[oaicite:10]{index=10}
+ * - 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 `<details>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDetails } from "@lnpg/pkgn-sol/elements/interactive/details";
+ *
+ * const d = createDetails({ open: true });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDetails(attrs?: DetailsAttrs): ElementOf<typeof DETAILS_TAG>;
+/**
+ * Enhance details 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 enhanceDetails(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/interactive/details/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/interactive/details/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElG;;;;;;;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;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACrD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAmDF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}