@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,125 @@
+/**
+ * pkgn-sol Design Foundation: S (strikethrough) element helpers.
+ *
+ * @remarks
+ * The s element (`<s>`) represents content that is no longer accurate or no
+ * longer relevant. It is a presentational indicator of "this isn't current"
+ * rather than an edit-tracking semantic.
+ *
+ * Best-practice guidance:
+ * - Use `<s>` for "no longer relevant/accurate" text (e.g. outdated pricing).
+ * - Use `<del>` when you mean "this was removed" (edit history / document diff semantics).
+ * - Do not use `<s>` as a substitute for emphasis; use appropriate semantics and CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<s>` 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/s
+ *
+ * @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 s elements.
+ *
+ * @category Constants
+ */
+export declare const S_TAG: "s";
+/**
+ * A CSS selector targeting s elements.
+ *
+ * @category Constants
+ */
+export declare const S_SELECTOR = "s";
+/**
+ * Attribute bag for s creation/enhancement.
+ *
+ * @remarks
+ * The `<s>` 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 SAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an s 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 element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<s>` element.
+ *
+ * @example
+ * ```ts
+ * import { createS } from "@lnpg/pkgn-sol/elements/inline/s";
+ *
+ * const el = createS("£199", { className: "old-price" });
+ * document.body.appendChild(el);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createS(text?: string, attrs?: SAttrs): ElementOf<typeof S_TAG>;
+/**
+ * Enhance s 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 enhanceSs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

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

@@ -0,0 +1,122 @@
+/**
+ * pkgn-sol Design Foundation: Samp element helpers.
+ *
+ * @remarks
+ * The samp element (`<samp>`) represents sample (or quoted) output from another
+ * program or computing system.
+ *
+ * Best-practice guidance:
+ * - Use `<samp>` for *output* (what the computer/system printed).
+ * - Use `<kbd>` for user input (what the user typed/pressed).
+ * - Use `<code>` for code fragments (source code).
+ * - Use CSS for presentation; semantics should match meaning.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create samp nodes 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/samp
+ *
+ * @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 sample output.
+ *
+ * @category Constants
+ */
+export declare const SAMP_TAG: "samp";
+/**
+ * A CSS selector targeting samp elements.
+ *
+ * @category Constants
+ */
+export declare const SAMP_SELECTOR = "samp";
+/**
+ * Attribute bag for samp creation/enhancement.
+ *
+ * @remarks
+ * Samp 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 SampAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a samp 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 samp element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<samp>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSamp } from "@lnpg/pkgn-sol/elements/inline/samp";
+ *
+ * // Sample output:
+ * const out = createSamp("Everything up-to-date");
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSamp(text?: string, attrs?: SampAttrs): ElementOf<typeof SAMP_TAG>;
+/**
+ * Enhance samp 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 enhanceSamps(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/samp/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,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;AA6BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,QAAQ,CAAC,CAEvF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG9D"}

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

@@ -0,0 +1,138 @@
+/**
+ * pkgn-sol Design Foundation: Small element helpers.
+ *
+ * @remarks
+ * The small element (`<small>`) represents side comments and small print.
+ *
+ * Best-practice guidance:
+ * - Use `<small>` for side notes, disclaimers, legal restrictions, copyright,
+ *   attribution, or licensing text.
+ * - Do not use `<small>` purely to make text visually smaller. Use CSS when the
+ *   intent is presentational rather than semantic.
+ * - Keep accessible meaning intact: if the content is important, it should be
+ *   readable and not "hidden" behind styling choices.
+ *
+ * Attributes:
+ * - `<small>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<small>` 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/small
+ *
+ * @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 the small element.
+ *
+ * @category Constants
+ */
+export declare const SMALL_TAG: "small";
+/**
+ * A CSS selector targeting small elements.
+ *
+ * @category Constants
+ */
+export declare const SMALL_SELECTOR = "small";
+/**
+ * Attribute bag for small creation/enhancement.
+ *
+ * @remarks
+ * `<small>` 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.
+ *
+ * Security note:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style}.
+ *
+ * @category Attributes
+ */
+export type SmallAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a small 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.
+ *
+ * Note: `<small>` is phrasing content. This helper supports a simple `text`
+ * convenience for cases where plain text is sufficient; consumers can still
+ * append richer child nodes afterwards.
+ *
+ * @param text - Optional text content for the small element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<small>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSmall } from "@lnpg/pkgn-sol/elements/inline/small";
+ *
+ * const legal = createSmall("Terms apply.", { className: "legal" });
+ * document.body.appendChild(legal);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSmall(text?: string, attrs?: SmallAttrs): ElementOf<typeof SMALL_TAG>;
+/**
+ * Enhance small 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 enhanceSmalls(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/small/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAE1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}

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

@@ -0,0 +1,126 @@
+/**
+ * pkgn-sol Design Foundation: Strong element helpers.
+ *
+ * @remarks
+ * The strong element (`<strong>`) indicates that its contents have strong
+ * importance, seriousness, or urgency. Browsers typically render it as bold,
+ * but the semantic meaning is what matters. :contentReference[oaicite:3]{index=3}
+ *
+ * Best-practice guidance:
+ * - Use `<strong>` for genuinely important text (e.g. warnings, urgent notes).
+ * - Do not use `<strong>` purely for visual styling; use CSS for presentation.
+ * - Do not confuse `<strong>` with `<b>`:
+ *   - `<strong>` conveys importance/seriousness/urgency.
+ *   - `<b>` draws attention without adding semantic importance. :contentReference[oaicite:4]{index=4}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create strong text 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.
+ *
+ * @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 strong importance.
+ *
+ * @category Constants
+ */
+export declare const STRONG_TAG: "strong";
+/**
+ * A CSS selector targeting strong elements.
+ *
+ * @category Constants
+ */
+export declare const STRONG_SELECTOR = "strong";
+/**
+ * Attribute bag for strong creation/enhancement.
+ *
+ * @remarks
+ * The `<strong>` element uses 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 StrongAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a strong 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 strong element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<strong>` element.
+ *
+ * @example
+ * Emphasize a warning:
+ * ```ts
+ * import { createStrong } from "@lnpg/pkgn-sol/elements/inline/strong";
+ *
+ * const warning = createStrong("Warning:", { className: "warning-label" });
+ * document.body.appendChild(warning);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createStrong(text?: string, attrs?: StrongAttrs): ElementOf<typeof STRONG_TAG>;
+/**
+ * Enhance strong 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 enhanceStrongs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/strong/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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE7F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}

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

@@ -0,0 +1,130 @@
+/**
+ * pkgn-sol Design Foundation: Sub element helpers.
+ *
+ * @remarks
+ * The sub element (`<sub>`) represents subscript text.
+ *
+ * Best-practice guidance:
+ * - Use `<sub>` for typographical conventions (e.g. chemical formulas like H₂O,
+ *   mathematical indices in plain text, footnote markers) where subscript is
+ *   semantically appropriate.
+ * - Do not use `<sub>` purely for presentation. Use CSS for visual styling.
+ *
+ * The `<sub>` element has no element-specific attributes. It supports standard
+ * HTML global attributes.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create sub 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.
+ *
+ * MDN:
+ * - https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/sub
+ *
+ * @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 subscript text.
+ *
+ * @category Constants
+ */
+export declare const SUB_TAG: "sub";
+/**
+ * A CSS selector targeting sub elements.
+ *
+ * @category Constants
+ */
+export declare const SUB_SELECTOR = "sub";
+/**
+ * Attribute bag for sub creation/enhancement.
+ *
+ * @remarks
+ * The `<sub>` 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 SubAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a sub 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 sub element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<sub>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSub } from "@lnpg/pkgn-sol/elements/inline/sub";
+ *
+ * const formula = document.createElement("span");
+ * formula.append("H");
+ * formula.appendChild(createSub("2"));
+ * formula.append("O");
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSub(text?: string, attrs?: SubAttrs): ElementOf<typeof SUB_TAG>;
+/**
+ * Enhance sub 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 enhanceSubs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

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