@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,137 @@
+/**
+ * pkgn-sol Design Foundation: Code element helpers.
+ *
+ * @remarks
+ * The code element (`<code>`) represents a fragment of computer code.
+ *
+ * Best-practice guidance:
+ * - Use `<code>` for inline code fragments inside text.
+ * - For code blocks, pair `<code>` with `<pre>` (e.g. `<pre><code>...</code></pre>`).
+ * - Do not use `<code>` purely for visual styling. If the intent is presentational
+ *   (monospace text), use CSS instead.
+ *
+ * Attributes:
+ * - `<code>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<code>` 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/Reference/Elements/code
+ * @see https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element
+ *
+ * @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 code element.
+ *
+ * @category Constants
+ */
+export declare const CODE_TAG: "code";
+/**
+ * A CSS selector targeting code elements.
+ *
+ * @category Constants
+ */
+export declare const CODE_SELECTOR = "code";
+/**
+ * Attribute bag for code creation/enhancement.
+ *
+ * @remarks
+ * `<code>` 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 CodeAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a code 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: `<code>` 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 code element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<code>` element.
+ *
+ * @example
+ * ```ts
+ * import { createCode } from "@lnpg/pkgn-sol/elements/inline/code";
+ *
+ * const snippet = createCode("npm run build", { className: "cmd" });
+ * document.body.appendChild(snippet);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createCode(text?: string, attrs?: CodeAttrs): ElementOf<typeof CODE_TAG>;
+/**
+ * Enhance code 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 enhanceCodes(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/code/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;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;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAClD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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/data/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * pkgn-sol Design Foundation: Data (`data`) element helpers.
+ *
+ * @remarks
+ * The data element (`<data>`) links human-readable content to a machine-readable
+ * value via the `value` attribute.
+ *
+ * Best-practice guidance:
+ * - Use `value` for canonical/machine-readable values (IDs, codes, normalized forms).
+ * - Keep visible text human-friendly.
+ * - Prefer explicit `value` when the machine value differs from the displayed text.
+ *
+ * pkgn-sol applies a sensible fallback:
+ * - If `attrs.value` is omitted and `text` is provided, pkgn-sol sets `value` to `text`.
+ *
+ * Security notes:
+ * - pkgn-sol blocks unsafe attribute *names* (e.g. `onclick`, raw `style`).
+ * - pkgn-sol does not sanitize attribute *values*. Treat untrusted inputs accordingly.
+ *
+ * References:
+ * - MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/data
+ * - WHATWG: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-data-element
+ *
+ * @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;
+};
+/**
+ * Allowed value types for the `value` attribute on `<data>`.
+ *
+ * @remarks
+ * HTML treats attributes as strings. pkgn-sol allows string/number and coerces to string.
+ *
+ * @category Attributes
+ */
+export type DataValue = string | number;
+/**
+ * The semantic tag name for data elements.
+ *
+ * @category Constants
+ */
+export declare const DATA_TAG: "data";
+/**
+ * A CSS selector targeting data elements.
+ *
+ * @category Constants
+ */
+export declare const DATA_SELECTOR = "data";
+/**
+ * Attribute bag for data element creation/enhancement.
+ *
+ * @remarks
+ * Data elements accept standard HTML global attributes, plus:
+ * - `value`: machine-readable translation of the element's content.
+ *
+ * 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 DataAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Machine-readable value for the data.
+     *
+     * @remarks
+     * If omitted and `text` is provided, pkgn-sol falls back to using `text` as `value`.
+     */
+    value?: DataValue;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a data 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.
+ * - If `attrs.value` is omitted and `text` is provided, pkgn-sol sets `value` to `text`.
+ *
+ * @param text - Optional human-readable content for the data element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<data>` element.
+ *
+ * @example
+ * ```ts
+ * import { createData } from "@lnpg/pkgn-sol/elements/inline/data";
+ *
+ * document.body.appendChild(
+ *   createData("Mini Ketchup", { value: 398 })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createData(text?: string, attrs?: DataAttrs): ElementOf<typeof DATA_TAG>;
+/**
+ * Enhance data 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 enhanceDatas(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/data/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;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAG,MAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAClD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAmDF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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/dfn/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * pkgn-sol Design Foundation: Dfn element helpers.
+ *
+ * @remarks
+ * The dfn element (`<dfn>`) indicates the defining instance of a term.
+ * The nearest containing phrasing context (often a paragraph, list item, or
+ * section) should include the term's definition.
+ *
+ * Best-practice guidance:
+ * - Use `<dfn>` for the defining instance of a term, not for general emphasis.
+ * - Avoid nesting `<dfn>` inside another `<dfn>`.
+ * - If you use the `title` attribute on `<dfn>`, it should contain only the term
+ *   being defined (useful when the displayed text differs from the term).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create definition-term markers 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/dfn
+ *
+ * @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 defining instances of terms.
+ *
+ * @category Constants
+ */
+export declare const DFN_TAG: "dfn";
+/**
+ * A CSS selector targeting dfn elements.
+ *
+ * @category Constants
+ */
+export declare const DFN_SELECTOR = "dfn";
+/**
+ * Attribute bag for dfn creation/enhancement.
+ *
+ * @remarks
+ * Dfn 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 DfnAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a dfn 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 dfn element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dfn>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDfn } from "@lnpg/pkgn-sol/elements/inline/dfn";
+ *
+ * document.body.appendChild(
+ *   createDfn("validator", { id: "term-validator" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDfn(text?: string, attrs?: DfnAttrs): ElementOf<typeof DFN_TAG>;
+/**
+ * Enhance dfn 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 enhanceDfns(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

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

@@ -0,0 +1,124 @@
+/**
+ * pkgn-sol Design Foundation: Em element helpers.
+ *
+ * @remarks
+ * The em element (`<em>`) marks text that has stress emphasis. Stress emphasis is
+ * semantic: it can change the meaning of a sentence, and nested `<em>` elements
+ * indicate a greater degree of emphasis. :contentReference[oaicite:2]{index=2}
+ *
+ * Best-practice guidance:
+ * - Use `<em>` when you would change vocal stress if speaking the sentence.
+ * - Avoid using `<em>` purely for visual styling (e.g. italics); use CSS instead.
+ * - Nested `<em>` increases emphasis; do not nest for decoration. :contentReference[oaicite:3]{index=3}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create emphasis 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 stress emphasis.
+ *
+ * @category Constants
+ */
+export declare const EM_TAG: "em";
+/**
+ * A CSS selector targeting em elements.
+ *
+ * @category Constants
+ */
+export declare const EM_SELECTOR = "em";
+/**
+ * Attribute bag for em creation/enhancement.
+ *
+ * @remarks
+ * The `<em>` element uses standard HTML global attributes. :contentReference[oaicite:4]{index=4}
+ *
+ * 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 EmAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an em 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 em element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<em>` element.
+ *
+ * @example
+ * Stress emphasis:
+ * ```ts
+ * import { createEm } from "@lnpg/pkgn-sol/elements/inline/em";
+ *
+ * const e = createEm("really", { className: "stress" });
+ * document.body.appendChild(e);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createEm(text?: string, attrs?: EmAttrs): ElementOf<typeof EM_TAG>;
+/**
+ * Enhance em 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 enhanceEms(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,143 @@
+/**
+ * pkgn-sol Design Foundation: i element helpers.
+ *
+ * @remarks
+ * The i element (`<i>`) represents a range of text set off from the normal prose
+ * for some reason, such as:
+ * - idiomatic text / alternate voice or mood
+ * - technical terms
+ * - taxonomical designations
+ * - transliterations
+ *
+ * Best-practice guidance:
+ * - Do not use `<i>` purely for visual italics. Use CSS when the intent is
+ *   presentational rather than semantic.
+ * - If you mean emphasis (stress), use `<em>`.
+ * - If you mean importance, use `<strong>`.
+ * - If you mean the title of a work, use `<cite>`.
+ *
+ * Attributes:
+ * - `<i>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<i>` 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/Reference/Elements/i
+ * @see https://html.spec.whatwg.org/multipage/text-level-semantics.html
+ *
+ * @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 i element.
+ *
+ * @category Constants
+ */
+export declare const I_TAG: "i";
+/**
+ * A CSS selector targeting i elements.
+ *
+ * @category Constants
+ */
+export declare const I_SELECTOR = "i";
+/**
+ * Attribute bag for i creation/enhancement.
+ *
+ * @remarks
+ * `<i>` 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 IAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an i 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: `<i>` 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 i element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<i>` element.
+ *
+ * @example
+ * ```ts
+ * import { createI } from "@lnpg/pkgn-sol/elements/inline/i";
+ *
+ * const term = createI("Homo sapiens", { className: "taxonomy" });
+ * document.body.appendChild(term);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createI(text?: string, attrs?: IAttrs): ElementOf<typeof I_TAG>;
+/**
+ * Enhance i 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 enhanceIs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/i/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAC/C;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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"}