@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/form/textarea/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * pkgn-sol Design Foundation: Textarea element helpers.
+ *
+ * @remarks
+ * The textarea element (`<textarea>`) is a multi-line plain-text form control.
+ *
+ * Best-practice guidance:
+ * - Always provide an accessible name (typically via a `<label>`).
+ * - Prefer `placeholder` as a hint, not as a substitute for a label.
+ * - Use `rows`/`cols` to set a sensible baseline size, then use CSS for layout.
+ * - Use `minLength`/`maxLength` for client-side constraints, but validate on the server.
+ * - Use `wrap="hard"` only when you intentionally want line breaks inserted for
+ *   form submission, and ensure `cols` is set.
+ * - Use `dirname` only when you actually want directionality included in submission.
+ *
+ * Attributes (element-specific):
+ * - `name`, `form`, `disabled`, `required`, `readOnly`
+ * - `cols`, `rows`
+ * - `minLength`, `maxLength`
+ * - `placeholder`
+ * - `autoComplete`, `autoFocus`, `autoCapitalize`
+ * - `dirName`
+ * - `wrap`
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which
+ *   block inline event handler attributes (e.g. `onclick`) and raw `style`
+ *   attribute injection (use the `style` object field instead).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/textarea
+ *
+ * @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 textarea.
+ *
+ * @category Constants
+ */
+export declare const TEXTAREA_TAG: "textarea";
+/**
+ * A CSS selector targeting textarea elements.
+ *
+ * @category Constants
+ */
+export declare const TEXTAREA_SELECTOR = "textarea";
+/**
+ * Textarea wrap modes.
+ *
+ * @remarks
+ * - `soft` (default): the submitted value is not forcibly wrapped.
+ * - `hard`: line breaks are inserted for submission based on `cols`.
+ *
+ * @category Types
+ */
+export type TextareaWrap = 'soft' | 'hard';
+/**
+ * Autocapitalize values accepted by browsers for form controls.
+ *
+ * @remarks
+ * This is a content attribute commonly supported on form controls.
+ *
+ * @category Types
+ */
+export type AutoCapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+/**
+ * Attribute bag for textarea creation/enhancement.
+ *
+ * @remarks
+ * Textareas accept standard HTML global attributes plus textarea-specific content
+ * 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 TextareaAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Name used during form submission.
+     */
+    name?: string;
+    /**
+     * Associate the control with a form by ID.
+     */
+    form?: string;
+    /**
+     * Whether the textarea is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the textarea is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the textarea is read-only.
+     *
+     * @remarks
+     * Maps to the `readonly` content attribute.
+     */
+    readOnly?: boolean;
+    /**
+     * The number of visible text columns.
+     */
+    cols?: number;
+    /**
+     * The number of visible text rows.
+     */
+    rows?: number;
+    /**
+     * Minimum input length.
+     *
+     * @remarks
+     * Maps to the `minlength` content attribute.
+     */
+    minLength?: number;
+    /**
+     * Maximum input length.
+     *
+     * @remarks
+     * Maps to the `maxlength` content attribute.
+     */
+    maxLength?: number;
+    /**
+     * Placeholder hint text.
+     */
+    placeholder?: string;
+    /**
+     * Autofill hint.
+     */
+    autoComplete?: string;
+    /**
+     * Whether the control should be focused on page load.
+     */
+    autoFocus?: boolean;
+    /**
+     * Autocapitalization behavior.
+     */
+    autoCapitalize?: AutoCapitalize;
+    /**
+     * Submission directionality field name.
+     *
+     * @remarks
+     * When set, the value must not be empty.
+     * Maps to the `dirname` content attribute.
+     */
+    dirName?: string;
+    /**
+     * Wrapping mode for form submission.
+     */
+    wrap?: TextareaWrap;
+};
+/**
+ * Create a textarea element with optional initial value and attributes.
+ *
+ * @remarks
+ * For `<textarea>`, the initial value is represented by its text content in HTML.
+ * pkgn-sol assigns the provided `text` via `textContent` (never `innerHTML`).
+ *
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes and escape-hatch attributes are applied via pkgn-sol's shared
+ *   DOM helper, including security guards that block inline event handler
+ *   attributes (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional initial value (assigned as `textContent`).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<textarea>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTextarea } from "@lnpg/pkgn-sol/elements/form/textarea";
+ *
+ * const t = createTextarea("Hello", { rows: 4, cols: 40, name: "message" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createTextarea(text?: string, attrs?: TextareaAttrs): ElementOf<typeof TEXTAREA_TAG>;
+/**
+ * Enhance textarea 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 enhanceTextareas(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/form/textarea/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/textarea/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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,YAAY,EAAG,UAAmB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,OAAO,GAAG,YAAY,CAAC;AAE1F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACtD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,CAAC;AA4FF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAC5B,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,aAAa,GACpB,SAAS,CAAC,OAAO,YAAY,CAAC,CAEhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGlE"}

package/dist/types/elements/heading/h1/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * pkgn-sol Design Foundation: H1 element helpers.
+ *
+ * @remarks
+ * The h1 element (`<h1>`) represents the highest-rank section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to convey document structure, not for visual styling.
+ * - Keep heading levels ordered (don't jump from `<h1>` to `<h3>` because you
+ *   like the font size). Use CSS for presentation.
+ * - Prefer clear, succinct headings that describe the section that follows.
+ * - Many accessibility guides recommend a single `<h1>` as the page/document's
+ *   primary heading. HTML allows multiple headings, but consistency matters.
+ * - Don't rely on default browser heading styles; user-agent styles can change.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<h1>` 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.
+ *
+ * References:
+ * - MDN: Heading elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
+ * - MDN: Headings and paragraphs: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs
+ * - W3C WAI: Headings: https://www.w3.org/WAI/tutorials/page-structure/headings/
+ * - WHATWG HTML: Sections / heading content: https://html.spec.whatwg.org/multipage/sections.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 (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 the primary heading element.
+ *
+ * @category Constants
+ */
+export declare const H1_TAG: "h1";
+/**
+ * A CSS selector targeting h1 elements.
+ *
+ * @category Constants
+ */
+export declare const H1_SELECTOR = "h1";
+/**
+ * Attribute bag for h1 creation/enhancement.
+ *
+ * @remarks
+ * H1 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 H1Attrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an h1 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 heading.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<h1>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH1 } from "@lnpg/pkgn-sol/elements/heading/h1";
+ *
+ * document.body.prepend(createH1("Page title", { id: "title" }));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createH1(text?: string, attrs?: H1Attrs): ElementOf<typeof H1_TAG>;
+/**
+ * Enhance h1 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 enhanceH1s(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/heading/h1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/heading/h1/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;;;;;;;;;;;;;;;;;;;;;GAqBG;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/heading/h2/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * pkgn-sol Design Foundation: H2 element helpers.
+ *
+ * @remarks
+ * The h2 element (`<h2>`) represents a second-level heading. Headings define the
+ * hierarchical structure of a document and provide navigational landmarks for
+ * assistive technologies. :contentReference[oaicite:1]{index=1}
+ *
+ * Best-practice guidance:
+ * - Use headings to represent structure, not visual styling.
+ * - Prefer a logical hierarchy (e.g. `<h1>` then `<h2>`, then `<h3>`), and avoid
+ *   skipping levels purely for appearance. :contentReference[oaicite:2]{index=2}
+ * - Keep headings concise and descriptive to support scanning and accessibility. :contentReference[oaicite:3]{index=3}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<h2>` 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 (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 h2 headings.
+ *
+ * @category Constants
+ */
+export declare const H2_TAG: "h2";
+/**
+ * A CSS selector targeting h2 elements.
+ *
+ * @category Constants
+ */
+export declare const H2_SELECTOR = "h2";
+/**
+ * Attribute bag for h2 creation/enhancement.
+ *
+ * @remarks
+ * H2 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.
+ *
+ * Security notes:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style} instead.
+ *
+ * @category Attributes
+ */
+export type H2Attrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an h2 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 h2.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<h2>` element.
+ *
+ * @example
+ * Create and append a heading:
+ * ```ts
+ * import { createH2 } from "@lnpg/pkgn-sol/elements/heading/h2";
+ *
+ * document.body.appendChild(createH2("Section title", { className: "section-title" }));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createH2(text?: string, attrs?: H2Attrs): ElementOf<typeof H2_TAG>;
+/**
+ * Enhance h2 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 enhanceH2s(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/heading/h2/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/heading/h2/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAChD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;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/heading/h3/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * pkgn-sol Design Foundation: H3 element helpers.
+ *
+ * @remarks
+ * The h3 element (`<h3>`) represents a third-rank section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to convey document structure, not for visual styling.
+ * - Keep heading levels ordered (don't jump from `<h2>` to `<h4>` because you
+ *   like the font size). Use CSS for presentation.
+ * - Ensure headings describe the section content that follows.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<h3>` 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.
+ *
+ * References:
+ * - MDN: Heading elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
+ * - W3C WAI: Headings: https://www.w3.org/WAI/tutorials/page-structure/headings/
+ * - WHATWG HTML: Sections / heading content: https://html.spec.whatwg.org/multipage/sections.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 (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 third-level headings.
+ *
+ * @category Constants
+ */
+export declare const H3_TAG: "h3";
+/**
+ * A CSS selector targeting h3 elements.
+ *
+ * @category Constants
+ */
+export declare const H3_SELECTOR = "h3";
+/**
+ * Attribute bag for h3 creation/enhancement.
+ *
+ * @remarks
+ * H3 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 H3Attrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an h3 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 heading.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<h3>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH3 } from "@lnpg/pkgn-sol/elements/heading/h3";
+ *
+ * const h = createH3("Section heading", { id: "section" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createH3(text?: string, attrs?: H3Attrs): ElementOf<typeof H3_TAG>;
+/**
+ * Enhance h3 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 enhanceH3s(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/heading/h3/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/heading/h3/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,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;;;;;;;;;;;;;;;;;;;;;GAqBG;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"}