@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,183 @@
+/**
+ * pkgn-sol Design Foundation: Table element helpers.
+ *
+ * @remarks
+ * The table element (`<table>`) represents tabular data with more than one
+ * dimension (rows and columns).
+ *
+ * Best-practice guidance:
+ * - Use tables for data, not for layout.
+ * - Provide a clear `<caption>` describing the table's purpose.
+ * - Use `<thead>`, `<tbody>`, and `<tfoot>` to group table content meaningfully.
+ * - Mark header cells with `<th>` (not `<td>`), and use `scope`/`headers` where
+ *   appropriate for accessibility, especially in more complex tables.
+ * - Avoid obsolete presentational attributes (e.g. `border`, `cellpadding`,
+ *   `cellspacing`, `align`, `bgcolor`). Use CSS instead.
+ * - If additional long-form description is needed, consider `aria-describedby`
+ *   pointing to explanatory text outside the table.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create table 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: `<table>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table
+ * - WHATWG: Table model: 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 HTML tables.
+ *
+ * @category Constants
+ */
+export const TABLE_TAG = 'table' as const;
+
+/**
+ * A CSS selector targeting table elements.
+ *
+ * @category Constants
+ */
+export const TABLE_SELECTOR = 'table';
+
+/**
+ * Attribute bag for table creation/enhancement.
+ *
+ * @remarks
+ * Table 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.
+ *
+ * Note: table-specific presentational attributes historically existed but are
+ * obsolete in modern HTML. 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 TableAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link TableAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The table attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TableAttrs): 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 table element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Table content is typically structured with child elements (`<caption>`,
+ *   `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`). This helper does not build
+ *   table structure, it only creates the `<table>` element.
+ * - Optional text content is assigned via `textContent` (never `innerHTML`).
+ *   In real usage, prefer building actual table child elements rather than
+ *   relying on text content.
+ * - 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 table (generally discouraged).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<table>` element.
+ *
+ * @example
+ * Create a table and append it:
+ * ```ts
+ * import { createTable } from "@lnpg/pkgn-sol/elements/table/table";
+ *
+ * const table = createTable(undefined, { className: "data-table" });
+ * document.body.appendChild(table);
+ * ```
+ *
+ * @category DOM
+ */
+export function createTable(text?: string, attrs?: TableAttrs): ElementOf<typeof TABLE_TAG> {
+  return createElement(TABLE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance table 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 enhanceTables(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for table.
+  void root;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * pkgn-sol Design Foundation: Table Element
+ *
+ * Table (`table`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Normalizes default UA table model differences (spacing + collapsing)
+ * - Keeps layout predictable without imposing a "designed" table style
+ * - Applies pkgn-sol base typography tokens so the element can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.table
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(table) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: table;
+
+  // UA defaults commonly use `border-collapse: separate` and non-zero spacing.
+  // Normalize to a consistent baseline, and avoid "mystery gaps" between cells.
+  border-collapse: collapse;
+  border-spacing: 0;
+
+  // Normalize legacy/UA text indentation behavior for tables.
+  text-indent: 0;
+
+  // Remove incidental presentation.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Predictable sizing model.
+  box-sizing: border-box;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - 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);
+
+  // Keep the table neutral unless styled at the cell layer.
+  background-color: transparent;
+}

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

@@ -0,0 +1,174 @@
+/**
+ * pkgn-sol Design Foundation: Tbody element helpers.
+ *
+ * @remarks
+ * The tbody element (`<tbody>`) represents a block of rows that make up the main
+ * body of a table's data.
+ *
+ * Best-practice guidance:
+ * - Use tables for data, not layout.
+ * - Group rows meaningfully with `<thead>`, `<tbody>`, and `<tfoot>`.
+ * - Prefer semantic headers via `<th>` (with appropriate `scope`/`headers`)
+ *   and provide a `<caption>` for accessible tables.
+ * - Avoid obsolete presentational attributes (e.g. `align`, `valign`, `char`,
+ *   `charoff`). Use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<tbody>` 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: `<tbody>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tbody
+ * - 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 body sections.
+ *
+ * @category Constants
+ */
+export const TBODY_TAG = 'tbody' as const;
+
+/**
+ * A CSS selector targeting tbody elements.
+ *
+ * @category Constants
+ */
+export const TBODY_SELECTOR = 'tbody';
+
+/**
+ * Attribute bag for tbody creation/enhancement.
+ *
+ * @remarks
+ * `<tbody>` 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: some legacy presentational attributes existed historically for table
+ * sections, 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 TbodyAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link TbodyAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The tbody attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TbodyAttrs): 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 tbody element with optional text content and global attributes.
+ *
+ * @remarks
+ * - In real usage, `<tbody>` should contain `<tr>` rows (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 tbody (generally discouraged).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<tbody>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTbody } from "@lnpg/pkgn-sol/elements/table/tbody";
+ *
+ * const tbody = createTbody(undefined, { className: "data-body" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createTbody(text?: string, attrs?: TbodyAttrs): ElementOf<typeof TBODY_TAG> {
+  return createElement(TBODY_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance tbody 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 enhanceTbodies(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for tbody.
+  void root;
+}

package/src/elements/table/tbody/tbody.scss

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

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

@@ -0,0 +1,220 @@
+/**
+ * pkgn-sol Design Foundation: Td element helpers.
+ *
+ * @remarks
+ * The td element (`<td>`) represents a data cell in a table row (`<tr>`).
+ *
+ * Best-practice guidance:
+ * - Use `<td>` for data cells and `<th>` for header cells.
+ * - Provide a `<caption>` and properly marked header cells for accessible tables.
+ * - Prefer simple tables. For complex tables with multi-level headers, use
+ *   the `headers` attribute to associate a `<td>` with one or more `<th>` IDs.
+ * - Avoid obsolete presentational attributes (e.g. `align`, `bgcolor`, `valign`).
+ *   Use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<td>` 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: `<td>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/td
+ * - WHATWG HTML: Tables: https://html.spec.whatwg.org/multipage/tables.html
+ * - W3C WAI: Tables (headers/id technique): https://www.w3.org/WAI/tutorials/tables/multi-level/
+ *
+ * @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 data cells.
+ *
+ * @category Constants
+ */
+export const TD_TAG = 'td' as const;
+
+/**
+ * A CSS selector targeting td elements.
+ *
+ * @category Constants
+ */
+export const TD_SELECTOR = 'td';
+
+/**
+ * Attribute bag for td creation/enhancement.
+ *
+ * @remarks
+ * In addition to global attributes, `<td>` participates in the table model via:
+ * - `colspan`: number of columns spanned (positive integer)
+ * - `rowspan`: number of rows spanned (positive integer)
+ * - `headers`: space-separated list of `<th id="...">` references for complex tables
+ *
+ * pkgn-sol supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type TdAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Number of columns this cell spans.
+   *
+   * @remarks
+   * Must be a positive integer greater than zero.
+   */
+  colspan?: number;
+
+  /**
+   * Number of rows this cell spans.
+   *
+   * @remarks
+   * Must be a positive integer greater than zero.
+   */
+  rowspan?: number;
+
+  /**
+   * Space-separated list of header cell IDs (`<th id="...">`) that apply to this cell.
+   *
+   * @remarks
+   * This is typically only necessary for complex tables.
+   */
+  headers?: string;
+};
+
+/**
+ * Normalize {@link TdAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The td attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TdAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, colspan, rowspan, headers, attrs: rawAttrs, ...rest } = attrs;
+
+  const out: GlobalAttrs = { ...rest };
+
+  // Map structured ARIA, only if something is actually defined.
+  if (aria) {
+    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;
+
+    if (Object.keys(mappedAria).length > 0) out.aria = mappedAria;
+  }
+
+  // Preserve caller escape hatch, but allow pkgn-sol-typed fields to fill gaps.
+  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(rawAttrs ?? {}) };
+
+  const hasOwn = (k: string) => Object.prototype.hasOwnProperty.call(mergedAttrs, k);
+
+  if (typeof colspan === 'number' && !hasOwn('colspan')) {
+    if (!Number.isInteger(colspan) || colspan <= 0) {
+      throw new Error('Invalid "colspan" for <td>: expected a positive integer greater than zero.');
+    }
+    mergedAttrs.colspan = colspan;
+  }
+
+  if (typeof rowspan === 'number' && !hasOwn('rowspan')) {
+    if (!Number.isInteger(rowspan) || rowspan <= 0) {
+      throw new Error('Invalid "rowspan" for <td>: expected a positive integer greater than zero.');
+    }
+    mergedAttrs.rowspan = rowspan;
+  }
+
+  if (typeof headers === 'string' && !hasOwn('headers')) {
+    const trimmed = headers.trim();
+    if (trimmed.length === 0) {
+      throw new Error('Invalid "headers" for <td>: expected a non-empty string.');
+    }
+    mergedAttrs.headers = trimmed;
+  }
+
+  if (Object.keys(mergedAttrs).length > 0) out.attrs = mergedAttrs;
+
+  return out;
+}
+
+/**
+ * Create a td element with optional text content and global attributes.
+ *
+ * @remarks
+ * - In real usage, `<td>` contains text and/or phrasing content, but should never
+ *   be built via `innerHTML` from untrusted data.
+ * - 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 td.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<td>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTd } from "@lnpg/pkgn-sol/elements/table/td";
+ *
+ * const cell = createTd("42", { colspan: 2 });
+ * ```
+ *
+ * @category DOM
+ */
+export function createTd(text?: string, attrs?: TdAttrs): ElementOf<typeof TD_TAG> {
+  return createElement(TD_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance td elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceTds(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for td.
+  void root;
+}