@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/layout/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Layout element factories.
+ *
+ * Provides framework-agnostic factory functions for HTML elements used to
+ * structure the major sections of a document or application.
+ *
+ * These factories:
+ * - Create semantic layout structures using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct document outline and accessibility semantics.
+ * - Prevent unsafe attribute injection.
+ *
+ * The elements in this module define the high-level structure of pages,
+ * articles, navigation regions, and supporting content.
+ *
+ * @module elements/layout
+ * @since 0.1.0
+ */
+
+/**
+ * `<article>` element factory namespace.
+ *
+ * Represents a self-contained composition that can be independently
+ * distributed or reused, such as a blog post, news article, or forum entry.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article
+ */
+export * as article from './article';
+
+/**
+ * `<aside>` element factory namespace.
+ *
+ * Represents content indirectly related to the surrounding content, often
+ * presented as a sidebar, pull quote, or complementary section.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside
+ */
+export * as aside from './aside';
+
+/**
+ * `<footer>` element factory namespace.
+ *
+ * Represents a footer for its nearest sectioning content or sectioning root,
+ * typically containing metadata, copyright information, or related links.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer
+ */
+export * as footer from './footer';
+
+/**
+ * `<header>` element factory namespace.
+ *
+ * Represents introductory content or navigational aids for a page or section,
+ * often containing headings, logos, or navigation elements.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header
+ */
+export * as header from './header';
+
+/**
+ * `<main>` element factory namespace.
+ *
+ * Represents the dominant content of the document body. There should only be
+ * one `<main>` element per document.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main
+ */
+export * as main from './main';
+
+/**
+ * `<nav>` element factory namespace.
+ *
+ * Represents a section of the page containing navigation links to other
+ * pages or parts of the current page.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav
+ */
+export * as nav from './nav';
+
+/**
+ * `<section>` element factory namespace.
+ *
+ * Represents a thematic grouping of content, typically with a heading.
+ * Sections contribute to the document outline.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
+ */
+export * as section from './section';

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

@@ -0,0 +1,175 @@
+/**
+ * pkgn-sol Design Foundation: Main element helpers.
+ *
+ * @remarks
+ * The main element (`<main>`) represents the dominant content of the document.
+ * It is a landmark element that helps assistive technologies and other tooling
+ * identify the primary content area.
+ *
+ * Best-practice guidance:
+ * - Use **only one** `<main>` per document.
+ * - The content of `<main>` should be unique to the document (avoid repeated UI
+ *   like nav, site chrome, copyright, etc.).
+ * - Do not place `<main>` as a descendant of `<article>`, `<aside>`, `<footer>`,
+ *   `<header>`, or `<nav>`.
+ *
+ * Attributes:
+ * - `<main>` supports **global attributes only**.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create main landmarks 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: Main element (`<main>`)
+ *
+ * @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 main landmarks.
+ *
+ * @category Constants
+ */
+export const MAIN_TAG = 'main' as const;
+
+/**
+ * A CSS selector targeting main elements.
+ *
+ * @category Constants
+ */
+export const MAIN_SELECTOR = 'main';
+
+/**
+ * Attribute bag for main creation/enhancement.
+ *
+ * @remarks
+ * Main 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 MainAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link MainAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The main attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: MainAttrs): 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 main 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.
+ *
+ * This helper does not enforce document-level semantics (e.g. "only one `<main>`")
+ * at runtime. That is a document-authoring responsibility.
+ *
+ * @param text - Optional text content for the main element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<main>` element.
+ *
+ * @example
+ * ```ts
+ * import { createMain } from "@lnpg/pkgn-sol/elements/layout/main";
+ *
+ * document.body.appendChild(
+ *   createMain(undefined, { id: "content", className: "page-main" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createMain(text?: string, attrs?: MainAttrs): ElementOf<typeof MAIN_TAG> {
+  return createElement(MAIN_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance main 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 enhanceMains(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for main.
+  void root;
+}

package/src/elements/layout/main/main.scss

@@ -0,0 +1,43 @@
+/**
+ * pkgn-sol Design Foundation: Main Element
+ *
+ * Main content landmark (`main`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing (avoid relying on browser defaults)
+ * - Keeps `<main>` as a structural container (no layout opinions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.main
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(main) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // `<main>` behaves like a block-level sectioning container.
+  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/nav/index.ts

@@ -0,0 +1,176 @@
+/**
+ * pkgn-sol Design Foundation: Nav element helpers.
+ *
+ * @remarks
+ * The nav element (`<nav>`) represents a section of a page whose purpose is to
+ * provide navigation links.
+ *
+ * Best-practice guidance:
+ * - Use `<nav>` for major navigation blocks (site navigation, table of contents).
+ * - If a page has multiple navigation regions, provide an accessible name via
+ *   `aria-label` or `aria-labelledby` so assistive tech can distinguish them.
+ * - Avoid nesting `<nav>` elements.
+ * - Prefer semantic grouping of links (e.g. lists) inside the nav.
+ *
+ * pkgn-sol provides small, framework-agnostic helpers so consumers can:
+ * - create navigation regions 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/nav
+ * @see https://html.spec.whatwg.org/multipage/sections.html#the-nav-element
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * `<nav>` is a landmark with an implicit `navigation` role.
+ *
+ * pkgn-sol intentionally encourages naming navigation regions when multiple navs
+ * exist on the same page (e.g. primary vs footer vs breadcrumb navigation).
+ *
+ * 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 nav.
+ *
+ * @category Constants
+ */
+export const NAV_TAG = 'nav' as const;
+
+/**
+ * A CSS selector targeting nav elements.
+ *
+ * @category Constants
+ */
+export const NAV_SELECTOR = 'nav';
+
+/**
+ * Attribute bag for nav creation/enhancement.
+ *
+ * @remarks
+ * Nav elements accept standard HTML global attributes.
+ *
+ * Accessibility note:
+ * - `<nav>` has an implicit landmark role.
+ * - The ARIA-in-HTML mapping indicates no explicit `role` is permitted for
+ *   `<nav>` in normal usage. pkgn-sol therefore omits `role` from {@link NavAttrs}.
+ *   Name navs via `aria-label` / `aria-labelledby` instead.
+ *
+ * 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 NavAttrs = Omit<GlobalAttrs, 'aria' | 'role'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link NavAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The nav attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: NavAttrs): 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 nav 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 nav.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<nav>` element.
+ *
+ * @example
+ * Create a labelled primary navigation region:
+ * ```ts
+ * import { createNav } from "@lnpg/pkgn-sol/elements/layout/nav";
+ *
+ * const nav = createNav(undefined, { aria: { label: "Primary" }, className: "site-nav" });
+ * document.body.appendChild(nav);
+ * ```
+ *
+ * @category DOM
+ */
+export function createNav(text?: string, attrs?: NavAttrs): ElementOf<typeof NAV_TAG> {
+  return createElement(NAV_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance nav 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 enhanceNavs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for nav.
+  void root;
+}

package/src/elements/layout/nav/nav.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Nav Element
+ *
+ * Navigation landmark (`nav`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing (avoid reliance on browser defaults)
+ * - Keeps `<nav>` structural (no layout opinions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.nav
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(nav) {
+  /* --------------------------------------------------------------------------
+   - 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/section/index.ts

@@ -0,0 +1,168 @@
+/**
+ * pkgn-sol Design Foundation: Section element helpers.
+ *
+ * @remarks
+ * The section element (`<section>`) represents a standalone thematic grouping of
+ * content, typically with a heading.
+ *
+ * Best-practice guidance:
+ * - Do not treat `<section>` as a "semantic `<div>`". Use it when the content is a
+ *   distinct theme that belongs in the document outline.
+ * - Prefer including a heading (`<h1>`-`<h6>`) that describes the section's purpose.
+ * - If you just need a generic container with no semantic meaning, use `<div>`.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create sections 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: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
+ * - HTML Standard: https://html.spec.whatwg.org/multipage/sections.html#the-section-element
+ * - WHATWG blog (context): https://blog.whatwg.org/is-not-just-a-semantic
+ *
+ * @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 section elements.
+ *
+ * @category Constants
+ */
+export const SECTION_TAG = 'section' as const;
+
+/**
+ * A CSS selector targeting section elements.
+ *
+ * @category Constants
+ */
+export const SECTION_SELECTOR = 'section';
+
+/**
+ * Attribute bag for section creation/enhancement.
+ *
+ * @remarks
+ * Section 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 SectionAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link SectionAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The section attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: SectionAttrs): 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 section 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 section.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<section>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSection } from "@lnpg/pkgn-sol/elements/layout/section";
+ *
+ * const s = createSection(undefined, { id: "features" });
+ * document.body.appendChild(s);
+ * ```
+ *
+ * @category DOM
+ */
+export function createSection(text?: string, attrs?: SectionAttrs): ElementOf<typeof SECTION_TAG> {
+  return createElement(SECTION_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance section 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 enhanceSections(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for section.
+  void root;
+}