@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,166 @@
+/**
+ * pkgn-sol Design Foundation: H5 element helpers.
+ *
+ * @remarks
+ * The h5 element (`<h5>`) represents a fifth-rank section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to communicate document structure, not visual styling.
+ * - Keep heading levels ordered (don't jump from `<h2>` to `<h5>` because you
+ *   like the font size). Use CSS for presentation.
+ * - Ensure headings accurately describe the section content that follows.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<h5>` 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 fifth-level headings.
+ *
+ * @category Constants
+ */
+export const H5_TAG = 'h5' as const;
+
+/**
+ * A CSS selector targeting h5 elements.
+ *
+ * @category Constants
+ */
+export const H5_SELECTOR = 'h5';
+
+/**
+ * Attribute bag for h5 creation/enhancement.
+ *
+ * @remarks
+ * H5 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 H5Attrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link H5Attrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The h5 attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: H5Attrs): 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 h5 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 `<h5>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH5 } from "@lnpg/pkgn-sol/elements/heading/h5";
+ *
+ * const h = createH5("Subsection heading");
+ * ```
+ *
+ * @category DOM
+ */
+export function createH5(text?: string, attrs?: H5Attrs): ElementOf<typeof H5_TAG> {
+  return createElement(H5_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance h5 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 enhanceH5s(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for h5.
+  void root;
+}

package/src/elements/heading/h6/h6.scss

@@ -0,0 +1,48 @@
+/**
+ * pkgn-sol Design Foundation: H6 Element
+ *
+ * Section heading (`h6`)
+ *
+ * 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.h6
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(h6) {
+  /* --------------------------------------------------------------------------
+   - 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-h6);
+  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/h6/index.ts

@@ -0,0 +1,158 @@
+/**
+ * pkgn-sol Design Foundation: H6 element helpers.
+ *
+ * @remarks
+ * The h6 element (`<h6>`) represents the lowest-ranked section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to convey document structure, not visual styling.
+ * - Do not choose heading levels based on appearance; use CSS for styling.
+ * - Avoid skipping heading levels (e.g. jumping from `<h2>` to `<h6>`), unless the
+ *   document structure genuinely calls for it.
+ * - Keep headings short and descriptive to support accessibility navigation.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create heading 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/Heading_Elements
+ * @see 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.
+ *
+ * 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 labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for h6 headings.
+ *
+ * @category Constants
+ */
+export const H6_TAG = 'h6' as const;
+
+/**
+ * A CSS selector targeting h6 elements.
+ *
+ * @category Constants
+ */
+export const H6_SELECTOR = 'h6';
+
+/**
+ * Attribute bag for h6 creation/enhancement.
+ *
+ * @remarks
+ * `<h6>` 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 H6Attrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link H6Attrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The h6 attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: H6Attrs): 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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * Create an h6 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 `<h6>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH6 } from "@lnpg/pkgn-sol/elements/heading/h6";
+ *
+ * const heading = createH6("Minor heading", { id: "minor" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createH6(text?: string, attrs?: H6Attrs): ElementOf<typeof H6_TAG> {
+  return createElement(H6_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance h6 elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * It exists to establish a stable enhancement pattern across all elements.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceH6s(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for h6.
+  void root;
+}

package/src/elements/heading/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Heading element factories.
+ *
+ * Provides framework-agnostic factory functions for semantic HTML heading
+ * elements (`<h1>` through `<h6>`).
+ *
+ * These factories:
+ * - Create semantic heading elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct document outline semantics.
+ * - Prevent unsafe attribute injection.
+ *
+ * Headings define the hierarchical structure of a document and should be used
+ * in order where possible to maintain accessibility and navigability.
+ *
+ * @module elements/heading
+ * @since 0.1.0
+ */
+
+/**
+ * `<h1>` element factory namespace.
+ *
+ * Represents the top-level heading of a page or section.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ */
+export * as h1 from './h1';
+
+/**
+ * `<h2>` element factory namespace.
+ *
+ * Represents a second-level section heading.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ */
+export * as h2 from './h2';
+
+/**
+ * `<h3>` element factory namespace.
+ *
+ * Represents a third-level section heading.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ */
+export * as h3 from './h3';
+
+/**
+ * `<h4>` element factory namespace.
+ *
+ * Represents a fourth-level section heading.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ */
+export * as h4 from './h4';
+
+/**
+ * `<h5>` element factory namespace.
+ *
+ * Represents a fifth-level section heading.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ */
+export * as h5 from './h5';
+
+/**
+ * `<h6>` element factory namespace.
+ *
+ * Represents a sixth-level section heading.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
+ */
+export * as h6 from './h6';

package/src/elements/index.ts

@@ -0,0 +1,118 @@
+/**
+ * pkgn-sol element factory namespaces.
+ *
+ * Provides grouped access to all HTML element factory modules included in pkgn-sol.
+ *
+ * These namespaces:
+ * - Expose framework-agnostic DOM factory helpers.
+ * - Maintain strong TypeScript typing for attributes.
+ * - Forward pkgn-sol's curated global attributes safely.
+ * - Prevent unsafe attribute injection.
+ * - Keep the public API stable and predictable.
+ *
+ * Each namespace corresponds to a semantic category of HTML elements,
+ * allowing consumers to import only what they need while preserving
+ * a logical structure across the library.
+ *
+ * @module elements
+ * @since 0.1.0
+ */
+
+/**
+ * Container element factories.
+ *
+ * Generic structural elements such as `<div>` and `<span>` used for grouping
+ * and layout where no stronger semantic element is appropriate.
+ */
+export * as container from './container';
+
+/**
+ * Break element factories.
+ *
+ * Line and word break elements that influence text flow.
+ */
+export * as break from './break';
+
+/**
+ * Media element factories.
+ *
+ * Elements for embedding media such as images, video, audio, and embedded
+ * external resources.
+ */
+export * as media from './media';
+
+/**
+ * Table element factories.
+ *
+ * Elements used to construct semantic tabular data structures.
+ */
+export * as table from './table';
+
+/**
+ * Heading element factories.
+ *
+ * Document heading elements (`h1`-`h6`) used to create the page outline
+ * and hierarchical structure.
+ */
+export * as heading from './heading';
+
+/**
+ * Text content element factories.
+ *
+ * Elements used for paragraphs, quotations, horizontal rules, and other
+ * primary textual structures.
+ */
+export * as text from './text';
+
+/**
+ * Inline text element factories.
+ *
+ * Elements that apply semantic meaning, emphasis, or annotations within
+ * flowing text.
+ */
+export * as inline from './inline';
+
+/**
+ * List element factories.
+ *
+ * Elements for ordered, unordered, and description lists.
+ */
+export * as list from './list';
+
+/**
+ * Figure element factories.
+ *
+ * Elements for self-contained media, illustrations, diagrams, or code
+ * samples with optional captions.
+ */
+export * as figure from './figure';
+
+/**
+ * Form element factories.
+ *
+ * Elements used to collect, validate, and submit user input.
+ */
+export * as form from './form';
+
+/**
+ * Interactive element factories.
+ *
+ * Elements that provide native interactive behaviors such as dialogs
+ * and disclosure widgets.
+ */
+export * as interactive from './interactive';
+
+/**
+ * Responsive media element factories.
+ *
+ * Elements supporting responsive images, media sources, and timed text
+ * tracks.
+ */
+export * as responsive from './responsive';
+
+/**
+ * Layout element factories.
+ *
+ * High-level structural elements that define the major sections of a page.
+ */
+export * as layout from './layout';

package/src/elements/inline/a/a.scss

@@ -0,0 +1,55 @@
+/**
+ * pkgn-sol Design Foundation: Anchor Element
+ *
+ * Hyperlink (`a`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Keeps links recognizable as links (underline by default)
+ * - Normalizes link styling to be token-driven (color via brand vars)
+ * - Avoids removing focus indicators (accessibility)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.a
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(a) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Anchors are inline by default; keep in-flow link behavior.
+  display: inline;
+
+  // Remove incidental spacing artifacts.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Ensure decoration uses the current text color consistently.
+  text-decoration-color: currentcolor;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned defaults
+   -------------------------------------------------------------------------- */
+
+  // Provide a branded default without breaking inheritance-based composition.
+  color: var(--lg-theme-brand-colours-primary-colour, inherit);
+
+  // Keep links identifiable without relying on UA color choices.
+  text-decoration-line: underline;
+}
+
+:where(a:visited) {
+  // Visited link styling is privacy-restricted; color is allowed.
+  color: var(--lg-theme-brand-colours-secondary-colour, inherit);
+}
+
+:where(a:hover) {
+  // Subtle affordance without changing semantics or accessibility.
+  color: var(--lg-theme-brand-colours-tertiary-colour, inherit);
+}