@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/heading/h2/index.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 { createElement, 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 const H2_TAG = 'h2' as const;
+
+/**
+ * A CSS selector targeting h2 elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link H2Attrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The h2 attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: H2Attrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * 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 function createH2(text?: string, attrs?: H2Attrs): ElementOf<typeof H2_TAG> {
+  return createElement(H2_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * 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 function enhanceH2s(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for h2.
+  void root;
+}

package/src/elements/heading/h3/h3.scss

@@ -0,0 +1,54 @@
+/**
+ * pkgn-sol Design Foundation: H3 Element
+ *
+ * Section heading (`h3`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA default heading margins for consistent layout
+ * - Avoids reliance on UA heading sizing (browser defaults are not a stable contract)
+ * - Applies pkgn-sol heading typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.heading.h3
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(h3) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA spacing (headings ship with UA margins that differ by browser).
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Robust heading text behavior.
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned heading typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-heading-font-family);
+  font-size: var(--lg-typography-font-sizes-font-size-h3);
+  font-weight: var(--lg-typography-formatting-heading-font-weight);
+  line-height: var(--lg-typography-formatting-heading-line-height);
+  color: var(--lg-theme-base-colours-heading-font-color);
+
+  // Progressive enhancement for nicer headline wrapping.
+  text-wrap: balance;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-end: var(--lg-typography-spacing-heading-margin-bottom);
+}

package/src/elements/heading/h3/index.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 { createElement, 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 const H3_TAG = 'h3' as const;
+
+/**
+ * A CSS selector targeting h3 elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link H3Attrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The h3 attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: H3Attrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * 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 function createH3(text?: string, attrs?: H3Attrs): ElementOf<typeof H3_TAG> {
+  return createElement(H3_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * 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 function enhanceH3s(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for h3.
+  void root;
+}

package/src/elements/heading/h4/h4.scss

@@ -0,0 +1,48 @@
+/**
+ * pkgn-sol Design Foundation: H4 Element
+ *
+ * Section heading (`h4`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA default heading margins for consistent layout
+ * - Avoids reliance on UA heading sizing (browser defaults are not a stable contract)
+ * - Applies pkgn-sol heading typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.heading.h4
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(h4) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned heading typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-heading-font-family);
+  font-size: var(--lg-typography-font-sizes-font-size-h4);
+  font-weight: var(--lg-typography-formatting-heading-font-weight);
+  line-height: var(--lg-typography-formatting-heading-line-height);
+  color: var(--lg-theme-base-colours-heading-font-color);
+  text-wrap: balance;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-end: var(--lg-typography-spacing-heading-margin-bottom);
+}

package/src/elements/heading/h4/index.ts

@@ -0,0 +1,150 @@
+/**
+ * pkgn-sol Design Foundation: H4 element helpers.
+ *
+ * @remarks
+ * The `<h4>` element represents a level 4 section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to communicate structure, not visual styling.
+ * - Avoid skipping heading levels in a way that breaks hierarchy (e.g. `h2` → `h4`).
+ * - Keep headings descriptive and concise for accessibility.
+ * - Prefer CSS for appearance; headings are about semantics.
+ *
+ * This module:
+ * - Creates `<h4>` elements via pkgn-sol's hardened DOM helpers (no direct DOM calls).
+ * - Applies a curated subset of global attributes safely.
+ * - Supports a small, typed structured ARIA input mapped into `aria-*`.
+ * - Exposes a stable enhancement hook (currently a no-op) for API consistency.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is a small, typed subset intended to prevent typo-driven ARIA bugs and
+ * keep the API practical. Values are mapped into {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+  /**
+   * Accessible label, mapped to `aria-label`.
+   */
+  label?: string;
+
+  /**
+   * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for `<h4>`.
+ *
+ * @category Constants
+ */
+export const H4_TAG = 'h4' as const;
+
+/**
+ * A CSS selector targeting `<h4>` elements.
+ *
+ * @category Constants
+ */
+export const H4_SELECTOR = 'h4';
+
+/**
+ * Attribute bag for `<h4>` creation/enhancement.
+ *
+ * @remarks
+ * `<h4>` supports HTML global attributes only.
+ *
+ * pkgn-sol additionally supports a typed, structured ARIA input that is mapped into
+ * {@link GlobalAttrs.aria} without modifying the shared DOM helpers.
+ *
+ * @category Attributes
+ */
+export type H4Attrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link H4Attrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The `<h4>` attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: H4Attrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  return Object.keys(mappedAria).length > 0 ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * Create an `<h4>` element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which enforces:
+ *   - No inline event handler attributes (e.g. `onclick`)
+ *   - No raw `style` attribute injection (use the `style` object field)
+ *   - No empty attribute names
+ *
+ * @param text - Optional text content for the heading.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<h4>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH4 } from "@lnpg/pkgn-sol/elements/heading/h4";
+ *
+ * const h = createH4("Details", { id: "details-heading" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createH4(text?: string, attrs?: H4Attrs): ElementOf<typeof H4_TAG> {
+  return createElement(H4_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance `<h4>` elements within a given root.
+ *
+ * @remarks
+ * Intentionally a no-op in `0.1.0`. This exists to provide a stable, consistent
+ * integration hook across element modules.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceH4s(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for h4.
+  void root;
+}

package/src/elements/heading/h5/h5.scss

@@ -0,0 +1,50 @@
+/**
+ * pkgn-sol Design Foundation: H5 Element
+ *
+ * Section heading (`h5`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA default heading margins for consistent layout
+ * - Avoids reliance on UA heading sizing (browser defaults are not a stable contract)
+ * - Applies pkgn-sol heading typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.heading.h5
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(h5) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned heading typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-heading-font-family);
+  font-size: var(--lg-typography-font-sizes-font-size-h5);
+  font-weight: var(--lg-typography-formatting-heading-font-weight);
+  line-height: var(--lg-typography-formatting-heading-line-height);
+  color: var(--lg-theme-base-colours-heading-font-color);
+
+  // Progressive enhancement for nicer headline wrapping.
+  text-wrap: balance;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-end: var(--lg-typography-spacing-heading-margin-bottom);
+}