@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/layout/aside/aside.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Aside Element
+ *
+ * Tangential content (`aside`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing
+ * - Keeps `<aside>` structural (no layout or float assumptions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.aside
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(aside) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  box-sizing: border-box;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline typography (standalone-safe)
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: var(--lg-typography-font-sizes-base-font-size, inherit);
+  font-weight: var(--lg-typography-formatting-base-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  background-color: transparent;
+}

package/src/elements/layout/aside/index.ts

@@ -0,0 +1,161 @@
+/**
+ * pkgn-sol Design Foundation: Aside element helpers.
+ *
+ * @remarks
+ * The aside element (`<aside>`) represents content that is tangentially related
+ * to the content around it, such as sidebars, callout boxes, pull quotes, or
+ * related links.
+ *
+ * Best-practice guidance:
+ * - Use `<aside>` for content related to the surrounding section, but not part of
+ *   the main narrative flow.
+ * - Avoid using `<aside>` purely for visual layout. Use CSS for layout and choose
+ *   semantic elements for meaning.
+ * - Prefer native semantics. Only add ARIA roles when needed.
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<aside>` element
+ *
+ * @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 the labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for aside.
+ *
+ * @category Constants
+ */
+export const ASIDE_TAG = 'aside' as const;
+
+/**
+ * A CSS selector targeting aside elements.
+ *
+ * @category Constants
+ */
+export const ASIDE_SELECTOR = 'aside';
+
+/**
+ * Attribute bag for aside creation/enhancement.
+ *
+ * @remarks
+ * Aside 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 AsideAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link AsideAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The aside attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: AsideAttrs): 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 aside 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 aside.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<aside>` element.
+ *
+ * @example
+ * ```ts
+ * import { createAside } from "@lnpg/pkgn-sol/elements/layout/aside";
+ *
+ * const a = createAside("Related links", { className: "sidebar" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createAside(text?: string, attrs?: AsideAttrs): ElementOf<typeof ASIDE_TAG> {
+  return createElement(ASIDE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance aside 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
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceAsides(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for aside.
+  void root;
+}

package/src/elements/layout/footer/footer.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Footer Element
+ *
+ * Footer (`footer`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing
+ * - Keeps `<footer>` structural (no layout opinions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.footer
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(footer) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  box-sizing: border-box;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline typography (standalone-safe)
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: var(--lg-typography-font-sizes-base-font-size, inherit);
+  font-weight: var(--lg-typography-formatting-base-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  background-color: transparent;
+}

package/src/elements/layout/footer/index.ts

@@ -0,0 +1,161 @@
+/**
+ * pkgn-sol Design Foundation: Footer element helpers.
+ *
+ * @remarks
+ * The footer element (`<footer>`) represents a footer for its nearest ancestor
+ * sectioning content or sectioning root. It can be used as a page footer or as
+ * a footer within an `<article>`, `<section>`, etc.
+ *
+ * Best-practice guidance:
+ * - Use `<footer>` for information about the section it belongs to (author info,
+ *   related links, legal text, etc.).
+ * - Do not use `<footer>` purely for visual positioning. Layout is CSS; meaning
+ *   is HTML.
+ * - Prefer native semantics. Only add ARIA roles when needed.
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<footer>` element
+ *
+ * @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 the labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for footer.
+ *
+ * @category Constants
+ */
+export const FOOTER_TAG = 'footer' as const;
+
+/**
+ * A CSS selector targeting footer elements.
+ *
+ * @category Constants
+ */
+export const FOOTER_SELECTOR = 'footer';
+
+/**
+ * Attribute bag for footer creation/enhancement.
+ *
+ * @remarks
+ * Footer 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 FooterAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link FooterAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The footer attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: FooterAttrs): 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 a footer 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 footer.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<footer>` element.
+ *
+ * @example
+ * ```ts
+ * import { createFooter } from "@lnpg/pkgn-sol/elements/layout/footer";
+ *
+ * const f = createFooter("© 2026", { className: "site-footer" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createFooter(text?: string, attrs?: FooterAttrs): ElementOf<typeof FOOTER_TAG> {
+  return createElement(FOOTER_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance footer 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
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceFooters(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for footer.
+  void root;
+}

package/src/elements/layout/header/header.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Header Element
+ *
+ * Introductory content (`header`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing (avoid reliance on browser defaults)
+ * - Keeps `<header>` structural (no layout opinions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.header
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(header) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  box-sizing: border-box;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline typography (standalone-safe)
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: var(--lg-typography-font-sizes-base-font-size, inherit);
+  font-weight: var(--lg-typography-formatting-base-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  background-color: transparent;
+}

package/src/elements/layout/header/index.ts

@@ -0,0 +1,171 @@
+/**
+ * pkgn-sol Design Foundation: Header (`header`) element helpers.
+ *
+ * @remarks
+ * The header element (`<header>`) represents introductory content for its nearest
+ * ancestor sectioning root or sectioning content element. It commonly contains a
+ * heading (`<h1>`-`<h6>`), branding, navigation aids, or other introductory UI.
+ *
+ * Best-practice guidance:
+ * - Use `<header>` to group introductory content for a page or section.
+ * - Prefer meaningful structure (headings, landmarks) over generic containers.
+ * - Avoid using `<header>` purely for styling. Use CSS classes for styling and
+ *   keep semantics intentional.
+ * - A top-level `<header>` (scoped to `<body>` and not inside sectioning content)
+ *   may be exposed as a landmark; nested headers typically are not.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create header 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/header
+ * @see https://html.spec.whatwg.org/multipage/sections.html#the-header-element
+ *
+ * @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 header elements.
+ *
+ * @category Constants
+ */
+export const HEADER_TAG = 'header' as const;
+
+/**
+ * A CSS selector targeting header elements.
+ *
+ * @category Constants
+ */
+export const HEADER_SELECTOR = 'header';
+
+/**
+ * Attribute bag for header creation/enhancement.
+ *
+ * @remarks
+ * `<header>` 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 HeaderAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link HeaderAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The header attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: HeaderAttrs): 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 a header 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 header.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<header>` element.
+ *
+ * @example
+ * Create and append a header:
+ * ```ts
+ * import { createHeader } from "@lnpg/pkgn-sol/elements/layout/header";
+ *
+ * document.body.prepend(
+ *   createHeader(undefined, { className: "site-header" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createHeader(text?: string, attrs?: HeaderAttrs): ElementOf<typeof HEADER_TAG> {
+  return createElement(HEADER_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance header 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 enhanceHeaders(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for header.
+  void root;
+}