@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/table/td/td.scss

@@ -0,0 +1,48 @@
+/**
+ * pkgn-sol Design Foundation: TD Element
+ *
+ * Table data cell (`td`)
+ *
+ * Structural baseline + light branding.
+ *
+ * This module:
+ * - Normalizes UA defaults (notably alignment variance and incidental padding)
+ * - Preserves the table formatting context (no forced display)
+ * - Applies pkgn-sol typography tokens so the element can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.td
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(td) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // `td` participates in the table formatting context; do not override display.
+  margin: 0;
+  border: 0;
+
+  // Neutralize UA padding variance; spacing is owned by the table styling layer.
+  padding: 0;
+
+  // Direction-aware default alignment.
+  text-align: start;
+
+  // Normalize vertical alignment for multi-line cells.
+  vertical-align: top;
+  background-color: transparent;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline 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);
+}

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

@@ -0,0 +1,171 @@
+/**
+ * pkgn-sol Design Foundation: Tfoot element helpers.
+ *
+ * @remarks
+ * The tfoot element (`<tfoot>`) encapsulates a set of table rows (`<tr>`) that
+ * comprise the footer of a table, typically containing column summaries such as
+ * totals or other aggregate values. :contentReference[oaicite:1]{index=1}
+ *
+ * Best-practice guidance:
+ * - Use `<tfoot>` for footer rows (summaries/totals), and keep the table's
+ *   structure logical with `<thead>` for headers and `<tbody>` for body rows.
+ * - Many guides recommend placing `<tfoot>` after `<tbody>` for readability. :contentReference[oaicite:2]{index=2}
+ * - Avoid deprecated presentational attributes 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 `<tfoot>` 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 tfoot elements.
+ *
+ * @category Constants
+ */
+export const TFOOT_TAG = 'tfoot' as const;
+
+/**
+ * A CSS selector targeting tfoot elements.
+ *
+ * @category Constants
+ */
+export const TFOOT_SELECTOR = 'tfoot';
+
+/**
+ * Attribute bag for tfoot creation/enhancement.
+ *
+ * @remarks
+ * Tfoot 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 TfootAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link TfootAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The tfoot attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TfootAttrs): 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 tfoot element with global attributes.
+ *
+ * @remarks
+ * - `<tfoot>` is a structural table element. pkgn-sol does not accept a text argument
+ *   for this factory. Populate it with `<tr>` (and cells) 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 `<tfoot>` element.
+ *
+ * @example
+ * Create and append a tfoot:
+ * ```ts
+ * import { createTfoot } from "@lnpg/pkgn-sol/elements/table/tfoot";
+ *
+ * const tfoot = createTfoot({ className: "table-foot" });
+ * table.appendChild(tfoot);
+ * ```
+ *
+ * @category DOM
+ */
+export function createTfoot(attrs?: TfootAttrs): ElementOf<typeof TFOOT_TAG> {
+  return createElement(TFOOT_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance tfoot 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 enhanceTfoots(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for tfoot.
+  void root;
+}

package/src/elements/table/tfoot/tfoot.scss

@@ -0,0 +1,30 @@
+/**
+ * pkgn-sol Design Foundation: Tfoot Element
+ *
+ * Table footer (`tfoot`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Preserves native table formatting context
+ * - Avoids overriding internal table display roles
+ * - Removes incidental presentation artifacts
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.tfoot
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(tfoot) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Do NOT force display; preserve table formatting context.
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background-color: transparent;
+}

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

@@ -0,0 +1,277 @@
+/**
+ * pkgn-sol Design Foundation: Th element helpers.
+ *
+ * @remarks
+ * The th element (`<th>`) represents a header cell in a table row (`<tr>`).
+ * It is used to label a group of related cells, typically via:
+ * - `scope` for simple row/column headers
+ * - `headers` for complex tables with multi-level or irregular headings
+ *
+ * Best-practice guidance:
+ * - Prefer native table semantics (use `<th>` for headers, not `role="columnheader"`).
+ * - Use `scope` for simple tables (`row`, `col`, `rowgroup`, `colgroup`).
+ * - For complex tables, use `id` on `<th>` cells and reference them with
+ *   `headers` from the related data cells (and sometimes header cells).
+ * - Avoid deprecated presentational attributes and use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<th>` cells 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 th elements.
+ *
+ * @category Constants
+ */
+export const TH_TAG = 'th' as const;
+
+/**
+ * A CSS selector targeting th elements.
+ *
+ * @category Constants
+ */
+export const TH_SELECTOR = 'th';
+
+/**
+ * Allowed `scope` values for `<th>`.
+ *
+ * @remarks
+ * The HTML spec defines explicit keywords plus an automatic/default state.
+ * pkgn-sol exposes the common keyword values and allows an explicit `"auto"` value
+ * to match the spec's conceptual default state. Consumers control structure;
+ * pkgn-sol does not attempt to enforce table-model anchoring constraints.
+ *
+ * @category Attributes
+ */
+export type ThScope = 'row' | 'col' | 'rowgroup' | 'colgroup' | 'auto';
+
+/**
+ * Attribute bag for th creation/enhancement.
+ *
+ * @remarks
+ * Th elements accept standard HTML global attributes, plus:
+ * - `abbr`: an alternative label for the header cell (often abbreviated)
+ * - `colspan`: number of columns the cell spans
+ * - `rowspan`: number of rows the cell spans
+ * - `headers`: space-separated IDs of `<th>` elements that apply to this cell
+ * - `scope`: indicates the set of cells this header applies to (`row`, `col`, etc.)
+ *
+ * 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 ThAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Alternative label for the header cell.
+   *
+   * @remarks
+   * Useful when the visible header text is long but needs a shorter label in
+   * other contexts (e.g. when referenced as a header).
+   */
+  abbr?: string;
+
+  /**
+   * Number of columns the cell spans.
+   *
+   * @remarks
+   * Must be a positive integer to be meaningful. pkgn-sol sets the attribute only
+   * when you provide a finite value greater than 0.
+   */
+  colspan?: number;
+
+  /**
+   * Number of rows the cell spans.
+   *
+   * @remarks
+   * Must be a positive integer to be meaningful. pkgn-sol sets the attribute only
+   * when you provide a finite value greater than 0.
+   */
+  rowspan?: number;
+
+  /**
+   * Space-separated IDs of `<th>` elements that apply to this cell.
+   *
+   * @remarks
+   * This is primarily used for complex tables where `scope` is insufficient.
+   * pkgn-sol does not validate ID existence; consumers control their DOM trees.
+   */
+  headers?: string;
+
+  /**
+   * Indicates which cells the header cell applies to.
+   *
+   * @remarks
+   * Use for simple row/column headers. For complex tables, prefer `headers`.
+   */
+  scope?: ThScope;
+};
+
+/**
+ * Set an attribute only if it is not already present on the attribute bag.
+ *
+ * @remarks
+ * This supports the pkgn-sol convention where explicit raw attributes provided via
+ * {@link GlobalAttrs.attrs} are treated as the caller's final intent.
+ *
+ * @param attrs - The destination attributes object.
+ * @param name - Attribute name.
+ * @param value - Attribute value.
+ *
+ * @category Internal
+ */
+function setIfUnset(
+  attrs: NonNullable<GlobalAttrs['attrs']>,
+  name: string,
+  value: string | number | boolean,
+): void {
+  if (Object.prototype.hasOwnProperty.call(attrs, name)) return;
+  attrs[name] = value;
+}
+
+/**
+ * Normalize {@link ThAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The th attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: ThAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, abbr, colspan, rowspan, headers, scope, ...rest } = attrs;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> | undefined = aria
+    ? (() => {
+        const out: NonNullable<GlobalAttrs['aria']> = {};
+        if (typeof aria.label === 'string') out.label = aria.label;
+        if (typeof aria.labelledby === 'string') out.labelledby = aria.labelledby;
+        if (typeof aria.hidden === 'boolean') out.hidden = aria.hidden;
+
+        return Object.keys(out).length > 0 ? out : undefined;
+      })()
+    : undefined;
+
+  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(rest.attrs ?? {}) };
+
+  if (typeof abbr === 'string' && abbr.length > 0) setIfUnset(mergedAttrs, 'abbr', abbr);
+  if (typeof headers === 'string' && headers.length > 0)
+    setIfUnset(mergedAttrs, 'headers', headers);
+
+  if (typeof scope === 'string' && scope.length > 0) setIfUnset(mergedAttrs, 'scope', scope);
+
+  if (typeof colspan === 'number' && Number.isFinite(colspan) && colspan > 0) {
+    setIfUnset(mergedAttrs, 'colspan', Math.trunc(colspan));
+  }
+
+  if (typeof rowspan === 'number' && Number.isFinite(rowspan) && rowspan > 0) {
+    setIfUnset(mergedAttrs, 'rowspan', Math.trunc(rowspan));
+  }
+
+  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;
+
+  return {
+    ...rest,
+    ...(mappedAria ? { aria: mappedAria } : null),
+    ...(hasMergedAttrs ? { attrs: mergedAttrs } : null),
+  };
+}
+
+/**
+ * Create a th 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 header cell.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<th>` element.
+ *
+ * @example
+ * Create a column header cell:
+ * ```ts
+ * import { createTh } from "@lnpg/pkgn-sol/elements/table/th";
+ *
+ * const th = createTh("Price", { scope: "col" });
+ * row.appendChild(th);
+ * ```
+ *
+ * @category DOM
+ */
+export function createTh(text?: string, attrs?: ThAttrs): ElementOf<typeof TH_TAG> {
+  return createElement(TH_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance th 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 enhanceThs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for th.
+  void root;
+}

package/src/elements/table/th/th.scss

@@ -0,0 +1,48 @@
+/**
+ * pkgn-sol Design Foundation: TH Element
+ *
+ * Table header cell (`th`)
+ *
+ * Structural baseline + light branding.
+ *
+ * This module:
+ * - Normalizes UA defaults (notably alignment + weight variance)
+ * - Keeps table semantics intact (no borders/padding assumptions beyond baseline)
+ * - Applies pkgn-sol typography tokens so the element can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.th
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(th) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // `th` participates in the table formatting context; do not override display.
+  margin: 0;
+  border: 0;
+
+  // Neutralize UA padding variance; spacing is owned by the table styling layer.
+  padding: 0;
+
+  // Normalize header alignment differences between engines.
+  text-align: start;
+
+  // Normalize vertical alignment for multi-line headers.
+  vertical-align: top;
+  background-color: transparent;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline 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-heading-font-weight);
+  line-height: var(--lg-typography-formatting-base-line-height);
+  color: var(--lg-theme-base-colours-base-font-color);
+}