@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/table/thead/index.ts

@@ -0,0 +1,170 @@
+/**
+ * pkgn-sol Design Foundation: Thead element helpers.
+ *
+ * @remarks
+ * The thead element (`<thead>`) represents the block of rows that form the
+ * column headers (and related header-area rows) for a table.
+ *
+ * Best-practice guidance:
+ * - Use `<thead>` to group header rows, typically using `<th>` cells for headers.
+ * - Keep the table structure logical: `<caption>` (optional), then `<colgroup>`
+ *   (optional), then `<thead>`, then `<tbody>`/`<tfoot>` as needed.
+ * - Avoid deprecated presentational attributes (e.g. `align`) and use CSS instead.
+ * - Prefer native table semantics; only use ARIA when you cannot express the
+ *   intended structure using proper table markup.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<thead>` 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 thead elements.
+ *
+ * @category Constants
+ */
+export const THEAD_TAG = 'thead' as const;
+
+/**
+ * A CSS selector targeting thead elements.
+ *
+ * @category Constants
+ */
+export const THEAD_SELECTOR = 'thead';
+
+/**
+ * Attribute bag for thead creation/enhancement.
+ *
+ * @remarks
+ * Thead 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 TheadAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link TheadAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The thead attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TheadAttrs): 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 thead element with global attributes.
+ *
+ * @remarks
+ * - `<thead>` is a structural table element. pkgn-sol does not accept a text argument
+ *   for this factory. Populate it with `<tr>` and header cells (`<th>`) as needed.
+ * - 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 attrs - Optional attributes to apply.
+ * @returns The created `<thead>` element.
+ *
+ * @example
+ * Create and append a thead:
+ * ```ts
+ * import { createThead } from "@lnpg/pkgn-sol/elements/table/thead";
+ *
+ * const thead = createThead({ className: "table-head" });
+ * table.appendChild(thead);
+ * ```
+ *
+ * @category DOM
+ */
+export function createThead(attrs?: TheadAttrs): ElementOf<typeof THEAD_TAG> {
+  return createElement(THEAD_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance thead 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 enhanceTheads(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for thead.
+  void root;
+}

package/src/elements/table/thead/thead.scss

@@ -0,0 +1,32 @@
+/**
+ * pkgn-sol Design Foundation: Thead Element
+ *
+ * Table head (`thead`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Normalizes `<thead>` to its internal table display role
+ * - Avoids presentational styling (headers are styled at `th` / cell layer)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.thead
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(thead) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Internal table element role per the CSS table model.
+  display: table-header-group;
+
+  // Defensive baseline: avoid incidental spacing/presentation.
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background-color: transparent;
+}

package/src/elements/table/tr/index.ts

@@ -0,0 +1,174 @@
+/**
+ * pkgn-sol Design Foundation: Tr element helpers.
+ *
+ * @remarks
+ * The tr element (`<tr>`) represents a row of cells within a table section.
+ * A row typically contains `<td>` and/or `<th>` elements.
+ *
+ * Best-practice guidance:
+ * - Use tables for data, not layout.
+ * - Group rows with `<thead>`, `<tbody>`, and `<tfoot>` for clearer structure.
+ * - Use `<th>` for header cells (and `scope`/`headers` where appropriate) for
+ *   accessible tables.
+ * - Avoid obsolete presentational attributes on table elements (e.g. `align`,
+ *   `bgcolor`, `valign`). Use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<tr>` 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: `<tr>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tr
+ * - WHATWG HTML: Tables: https://html.spec.whatwg.org/multipage/tables.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 table rows.
+ *
+ * @category Constants
+ */
+export const TR_TAG = 'tr' as const;
+
+/**
+ * A CSS selector targeting tr elements.
+ *
+ * @category Constants
+ */
+export const TR_SELECTOR = 'tr';
+
+/**
+ * Attribute bag for tr creation/enhancement.
+ *
+ * @remarks
+ * `<tr>` 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.
+ *
+ * Note: legacy presentational attributes historically existed for table rows,
+ * but are obsolete. Consumers can still use {@link GlobalAttrs.attrs} as an
+ * escape hatch where necessary, subject to pkgn-sol's security rules in `dom.ts`
+ * (blocks inline event handlers and raw `style` attribute strings).
+ *
+ * @category Attributes
+ */
+export type TrAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link TrAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The tr attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TrAttrs): 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 tr element with optional text content and global attributes.
+ *
+ * @remarks
+ * - In real usage, `<tr>` should contain `<td>` and/or `<th>` cells (not text).
+ * - Optional 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 row (generally discouraged).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<tr>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTr } from "@lnpg/pkgn-sol/elements/table/tr";
+ *
+ * const row = createTr(undefined, { className: "row" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createTr(text?: string, attrs?: TrAttrs): ElementOf<typeof TR_TAG> {
+  return createElement(TR_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance tr 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 enhanceTrs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for tr.
+  void root;
+}

package/src/elements/table/tr/tr.scss

@@ -0,0 +1,30 @@
+/**
+ * pkgn-sol Design Foundation: Table Row Element
+ *
+ * Table row (`tr`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Preserves native table row behavior
+ * - Avoids forcing display values
+ * - Removes incidental presentation artifacts
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.tr
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(tr) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Do NOT override display: table-row.
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background-color: transparent;
+}

package/src/elements/text/address/address.scss

@@ -0,0 +1,61 @@
+/**
+ * pkgn-sol Design Foundation: Address Element
+ *
+ * Contact information (`address`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA defaults (notably the common italic default)
+ * - Keeps semantics intact while avoiding opinionated presentation
+ * - Applies pkgn-sol typography tokens so the element can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<address>` element (updated Jul 2025)
+ * - WHATWG HTML rendering guidance (UA expectations)
+ * - Modern reset guidance: normalize inconsistencies, avoid destructive resets (2025)
+ *
+ * @module
+ * @group  elements.text.address
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(address) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // UA styles commonly apply `font-style: italic` to `<address>`.
+  // Normalize to a clean baseline so presentation is controlled by the system.
+  font-style: normal;
+
+  // Remove default UA spacing so layout is predictable across engines.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Robust content handling.
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-base-font-family);
+  font-size: var(--lg-typography-font-sizes-base-font-size);
+  font-weight: var(--lg-typography-formatting-base-font-weight);
+  line-height: var(--lg-typography-formatting-base-line-height);
+  color: var(--lg-theme-base-colours-base-font-color);
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block: var(--lg-typography-spacing-base-margin-bottom);
+  margin-inline: 0;
+}

package/src/elements/text/address/index.ts

@@ -0,0 +1,173 @@
+/**
+ * pkgn-sol Design Foundation: Address (`address`) element helpers.
+ *
+ * @remarks
+ * The address element (`<address>`) represents contact information for a person,
+ * people, or an organization.
+ *
+ * Best-practice guidance:
+ * - Use `<address>` for contact information associated with the nearest
+ *   `<article>` or `<body>` ancestor.
+ * - Do not use `<address>` for arbitrary postal addresses. It is about contact
+ *   information for the author/owner/organization associated with the content.
+ * - Avoid using `<address>` purely for styling (e.g. italics/indentation).
+ *   Presentation is the job of CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create address blocks 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/address
+ * - WHATWG: https://html.spec.whatwg.org/multipage/sections.html#the-address-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`.
+   *
+   * @remarks
+   * Prefer `labelledby` when a visible labeling element exists.
+   */
+  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 address blocks.
+ *
+ * @category Constants
+ */
+export const ADDRESS_TAG = 'address' as const;
+
+/**
+ * A CSS selector targeting address elements.
+ *
+ * @category Constants
+ */
+export const ADDRESS_SELECTOR = 'address';
+
+/**
+ * Attribute bag for address creation/enhancement.
+ *
+ * @remarks
+ * Address 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 AddressAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link AddressAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The address attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: AddressAttrs): 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 address element with optional text content and 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 address.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<address>` element.
+ *
+ * @example
+ * ```ts
+ * import { createAddress } from "@lnpg/pkgn-sol/elements/text/address";
+ *
+ * document.body.appendChild(
+ *   createAddress("Contact: hello@example.com", { className: "contact" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createAddress(text?: string, attrs?: AddressAttrs): ElementOf<typeof ADDRESS_TAG> {
+  return createElement(ADDRESS_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance address 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 enhanceAddresses(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for address.
+  void root;
+}

package/src/elements/text/blockquote/blockquote.scss

@@ -0,0 +1,50 @@
+/**
+ * pkgn-sol Design Foundation: Blockquote Element
+ *
+ * Block quotation (`blockquote`)
+ *
+ * Baseline reset + light, brand-aligned spacing defaults.
+ *
+ * This module:
+ * - Normalizes UA indentation/margins for consistent layout across browsers
+ * - Preserves blockquote semantics (no decorative quote injection)
+ * - Uses low-specificity selectors (`:where()`)
+ * - Applies pkgn-sol spacing tokens so the element can be shipped standalone
+ *
+ * @module
+ * @group  elements.text.blockquote
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(blockquote) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // UA styles commonly apply indentation via margins. Normalize to a clean baseline.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Keep typography predictable and inheritable.
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+
+  // Robust text behavior for long strings/URLs in quoted content.
+  overflow-wrap: break-word;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned defaults
+   -------------------------------------------------------------------------- */
+
+  // Provide consistent separation from surrounding content.
+  margin-block: var(--lg-typography-spacing-base-margin-bottom);
+  margin-inline: 0;
+}