@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/layout/section/section.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Section Element
+ *
+ * Generic section (`section`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing (structural consistency)
+ * - Keeps `<section>` as a semantic container (no layout opinions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.section
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(section) {
+  /* --------------------------------------------------------------------------
+   - 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/list/dd/dd.scss

@@ -0,0 +1,49 @@
+/**
+ * pkgn-sol Design Foundation: DD Element
+ *
+ * Description details (`dd`)
+ *
+ * Structural baseline only (light normalization).
+ *
+ * This module:
+ * - Normalizes UA indentation (commonly a left margin) to avoid inconsistent layouts
+ * - Keeps typography inherited (the content is prose/structure, not a styled component)
+ * - Avoids imposing spacing patterns; `dl`/layout layer owns presentation
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<dd>` semantics in description lists :contentReference[oaicite:3]{index=3}
+ * - MDN (Learn): default `<dd>` margin-left/indentation note (Oct 2025) :contentReference[oaicite:4]{index=4}
+ * - Reset guidance (Oct 2025): normalize margins/padding across browsers :contentReference[oaicite:5]{index=5}
+ *
+ * @module
+ * @group  elements.list.dd
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(dd) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA indentation (often ~2.5em / 40px margin-left) to a clean baseline.
+  margin: 0;
+  margin-inline-start: 0;
+  padding: 0;
+  border: 0;
+
+  // Robust text behavior.
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  // Preserve inherited typography.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

package/src/elements/list/dd/index.ts

@@ -0,0 +1,159 @@
+/**
+ * pkgn-sol Design Foundation: Description Details (`<dd>`) element helpers.
+ *
+ * @remarks
+ * The `<dd>` element provides the description, definition, or value for the
+ * preceding term (`<dt>`) within a description list (`<dl>`).
+ *
+ * Best-practice guidance:
+ * - Use `<dd>` only within a `<dl>`.
+ * - Pair `<dd>` with an appropriate `<dt>` term.
+ * - Use semantic lists for terms/values, not for layout.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<dd>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - pass a structured, typed attribute bag
+ *
+ * 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/dd
+ * @see https://html.spec.whatwg.org/multipage/grouping-content.html#the-dd-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 dd.
+ *
+ * @category Constants
+ */
+export const DD_TAG = 'dd' as const;
+
+/**
+ * A CSS selector targeting dd elements.
+ *
+ * @category Constants
+ */
+export const DD_SELECTOR = 'dd';
+
+/**
+ * Attribute bag for dd creation/enhancement.
+ *
+ * @remarks
+ * `<dd>` only supports 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 DdAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DdAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The dd attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DdAttrs): 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 dd 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 dd element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dd>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDd } from "@lnpg/pkgn-sol/elements/list/dd";
+ *
+ * const dd = createDd("A sea serpent.", { className: "desc" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createDd(text?: string, attrs?: DdAttrs): ElementOf<typeof DD_TAG> {
+  return createElement(DD_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance dd 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 enhanceDds(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for dd.
+  void root;
+}

package/src/elements/list/dl/dl.scss

@@ -0,0 +1,39 @@
+/**
+ * pkgn-sol Design Foundation: DL Element
+ *
+ * Description list (`dl`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Normalizes UA spacing for consistent cross-browser rendering
+ * - Preserves semantics (no forced layout patterns)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<dl>` semantics and usage ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dl?utm_source=chatgpt.com))
+ * - MDN Learn: default list styling notes (Oct 2025) ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Text_styling/Styling_lists?utm_source=chatgpt.com))
+ * - Reset guidance (Oct 2025): normalize margins/padding ([useaxentix.com](https://useaxentix.com/blog/css/css-reset-complete-guide/?utm_source=chatgpt.com))
+ *
+ * @module
+ * @group  elements.list.dl
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(dl) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA spacing to a predictable baseline.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Ensure predictable sizing.
+  box-sizing: border-box;
+  max-width: 100%;
+}

package/src/elements/list/dl/index.ts

@@ -0,0 +1,171 @@
+/**
+ * pkgn-sol Design Foundation: Dl element helpers.
+ *
+ * @remarks
+ * The dl element (`<dl>`) represents a description list (a set of name-value groups).
+ * It is commonly used with `<dt>` (term/name) and `<dd>` (description/value).
+ *
+ * Best-practice guidance:
+ * - Prefer `<dl>` when you're expressing name-value pairs (not just "a list").
+ * - Use `<dt>` / `<dd>` in sensible groupings to keep meaning clear.
+ * - Avoid misusing `<dl>` for layout or arbitrary indentation; use CSS instead.
+ *
+ * Attributes:
+ * - `<dl>` has no element-specific attributes in modern HTML.
+ * - It accepts standard global attributes (id, class, lang, data-*, aria-*, etc.).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<dl>` 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 description lists.
+ *
+ * @category Constants
+ */
+export const DL_TAG = 'dl' as const;
+
+/**
+ * A CSS selector targeting dl elements.
+ *
+ * @category Constants
+ */
+export const DL_SELECTOR = 'dl';
+
+/**
+ * Attribute bag for dl creation/enhancement.
+ *
+ * @remarks
+ * Dl 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 DlAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DlAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The dl attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DlAttrs): 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 dl element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - In real usage, `<dl>` typically contains `<dt>` / `<dd>` children; pkgn-sol keeps
+ *   factories small and safe, so this helper supports optional text as a simple
+ *   convenience, not as a replacement for proper `<dt>` / `<dd>` structure.
+ * - 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 dl.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dl>` element.
+ *
+ * @example
+ * Create and append a dl:
+ * ```ts
+ * import { createDl } from "@lnpg/pkgn-sol/elements/list/dl";
+ *
+ * document.body.appendChild(
+ *   createDl(undefined, { className: "meta", id: "product-specs" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createDl(text?: string, attrs?: DlAttrs): ElementOf<typeof DL_TAG> {
+  return createElement(DL_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance dl 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 enhanceDls(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for dl.
+  void root;
+}

package/src/elements/list/dt/dt.scss

@@ -0,0 +1,51 @@
+/**
+ * pkgn-sol Design Foundation: DT Element
+ *
+ * Description term (`dt`)
+ *
+ * Structural baseline + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing so `<dl>` layouts are consistent across browsers
+ * - Preserves semantic emphasis via explicit, token-driven weight (no UA "bold" assumptions)
+ * - Avoids layout patterns (columns/grids) at baseline
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<dt>` semantics in description lists :contentReference[oaicite:0]{index=0}
+ * - MDN (Learn): default list styling notes for `<dl>/<dt>/<dd>` (Oct 2025) :contentReference[oaicite:1]{index=1}
+ * - Reset guidance (Oct 2025): normalize margins/padding across browsers :contentReference[oaicite:2]{index=2}
+ *
+ * @module
+ * @group  elements.list.dt
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(dt) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // UA defaults commonly rely on margins/weights; normalize spacing explicitly.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Robust text behavior.
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned semantic emphasis
+   -------------------------------------------------------------------------- */
+
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: var(--lg-typography-font-weights-semibold-font-weight);
+  line-height: inherit;
+  color: inherit;
+}

package/src/elements/list/dt/index.ts

@@ -0,0 +1,166 @@
+/**
+ * pkgn-sol Design Foundation: Dt element helpers.
+ *
+ * @remarks
+ * The dt element (`<dt>`) represents a definition term in a description list (`<dl>`).
+ * It is typically paired with one or more `<dd>` elements (the descriptions/details).
+ *
+ * Best-practice guidance:
+ * - Use `<dl>` + `<dt>` + `<dd>` for name/value groups (terms and descriptions),
+ *   not for arbitrary layout or "two-column" grids.
+ * - Keep terms concise; put the detail/content in `<dd>`.
+ * - Use CSS for presentation (avoid presentational patterns that change semantics).
+ *
+ * Attributes:
+ * - `<dt>` supports only global attributes (no element-specific attributes).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create dt elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * @see MDN `<dt>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt
+ * @see WHATWG HTML `<dt>`: https://html.spec.whatwg.org/multipage/grouping-content.html#the-dt-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 dt elements.
+ *
+ * @category Constants
+ */
+export const DT_TAG = 'dt' as const;
+
+/**
+ * A CSS selector targeting dt elements.
+ *
+ * @category Constants
+ */
+export const DT_SELECTOR = 'dt';
+
+/**
+ * Attribute bag for dt creation/enhancement.
+ *
+ * @remarks
+ * Dt 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 DtAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DtAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The dt attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DtAttrs): 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 dt 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 dt.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dt>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDt } from "@lnpg/pkgn-sol/elements/list/dt";
+ *
+ * const dl = document.createElement("dl");
+ * dl.appendChild(createDt("Size"));
+ * ```
+ *
+ * @category DOM
+ */
+export function createDt(text?: string, attrs?: DtAttrs): ElementOf<typeof DT_TAG> {
+  return createElement(DT_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance dt 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 enhanceDts(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for dt.
+  void root;
+}