@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,189 @@
+/**
+ * pkgn-sol Design Foundation: Col element helpers.
+ *
+ * @remarks
+ * The col element (`<col>`) represents one or more columns in a table, and is
+ * used to apply presentation (typically CSS) to columns as a group.
+ *
+ * Best-practice guidance:
+ * - Use `<col>` only inside a `<colgroup>`.
+ * - Use `<col>` for column-level styling (widths, background, etc.), not layout hacks.
+ * - Don't rely on `<col>` for semantics or accessibility. Use proper table
+ *   structure (`<caption>`, `<th>`, `scope`/`headers`) for accessible data tables.
+ * - Avoid obsolete presentational attributes; prefer CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<col>` 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: `<col>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/col
+ * - WHATWG HTML: Tables: https://html.spec.whatwg.org/multipage/tables.html
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createVoidElement, 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 column definitions.
+ *
+ * @category Constants
+ */
+export const COL_TAG = 'col' as const;
+
+/**
+ * A CSS selector targeting col elements.
+ *
+ * @category Constants
+ */
+export const COL_SELECTOR = 'col';
+
+/**
+ * Attribute bag for col creation/enhancement.
+ *
+ * @remarks
+ * `<col>` supports standard HTML global attributes and one primary element
+ * attribute: `span`.
+ *
+ * `span` specifies how many consecutive columns this `<col>` applies to.
+ * If omitted, browsers treat it as `1`.
+ *
+ * pkgn-sol supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type ColAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Number of consecutive columns this `<col>` element applies to.
+   *
+   * @remarks
+   * Must be a positive integer greater than zero. If omitted, the browser default
+   * is `1`.
+   */
+  span?: number;
+};
+
+/**
+ * Normalize {@link ColAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The col attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: ColAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, span, 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 ?? {}) };
+
+  // Only set `span` if provided AND caller didn't already set it via raw attrs.
+  if (typeof span === 'number' && !Object.prototype.hasOwnProperty.call(mergedAttrs, 'span')) {
+    // Spec constraint: positive integer > 0.
+    if (!Number.isInteger(span) || span <= 0) {
+      throw new Error('Invalid "span" for <col>: expected a positive integer greater than zero.');
+    }
+    mergedAttrs.span = span;
+  }
+
+  if (Object.keys(mergedAttrs).length > 0) out.attrs = mergedAttrs;
+
+  return out;
+}
+
+/**
+ * Create a col element (`<col>`) and apply global attributes.
+ *
+ * @remarks
+ * `<col>` is a void element. It does not accept text content or children.
+ *
+ * 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 `<col>` element.
+ *
+ * @example
+ * Create a `<col>` that spans 2 columns:
+ * ```ts
+ * import { createCol } from "@lnpg/pkgn-sol/elements/table/col";
+ *
+ * const col = createCol({ span: 2, className: "numeric" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createCol(attrs?: ColAttrs): ElementOf<typeof COL_TAG> {
+  return createVoidElement(COL_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance col 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 enhanceCols(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for col.
+  void root;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * pkgn-sol Design Foundation: Colgroup Element
+ *
+ * Table column group (`colgroup`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Normalizes `<colgroup>` to its internal table display role
+ * - Avoids adding presentational styling (column groups are structural)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.table.colgroup
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(colgroup) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Internal table element role per the CSS table model.
+  display: table-column-group;
+
+  // Defensive baseline: avoid incidental spacing/presentation.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Keep neutral; styling is typically applied via width/background on columns.
+  background-color: transparent;
+}

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

@@ -0,0 +1,224 @@
+/**
+ * pkgn-sol Design Foundation: Colgroup element helpers.
+ *
+ * @remarks
+ * The colgroup element (`<colgroup>`) represents a group of one or more columns
+ * in a table and is primarily used to apply presentation (not structure) to
+ * entire columns (typically via CSS). :contentReference[oaicite:1]{index=1}
+ *
+ * Best-practice guidance:
+ * - Use `<colgroup>` (and optionally `<col>`) to apply column-level styling
+ *   without repeating styles across cells.
+ * - Place `<colgroup>` inside a `<table>`, after any `<caption>` and before
+ *   `<thead>`, `<tbody>`, `<tfoot>`, or `<tr>`. :contentReference[oaicite:2]{index=2}
+ * - Use the `span` attribute only when the `<colgroup>` contains no `<col>`
+ *   children; otherwise, define spans via `<col>` elements. :contentReference[oaicite:3]{index=3}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<colgroup>` 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 colgroup elements.
+ *
+ * @category Constants
+ */
+export const COLGROUP_TAG = 'colgroup' as const;
+
+/**
+ * A CSS selector targeting colgroup elements.
+ *
+ * @category Constants
+ */
+export const COLGROUP_SELECTOR = 'colgroup';
+
+/**
+ * Attribute bag for colgroup creation/enhancement.
+ *
+ * @remarks
+ * Colgroup elements accept standard HTML global attributes, plus:
+ * - `span`: the number of consecutive columns in the group (when no `<col>`
+ *   children are present). :contentReference[oaicite:4]{index=4}
+ *
+ * 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 ColgroupAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Number of consecutive columns spanned by this column group.
+   *
+   * @remarks
+   * This should be a positive integer. The HTML spec clamps values above 1000
+   * and treats invalid/zero values as `1` in the table model. pkgn-sol does not
+   * attempt to emulate the full table model at runtime; it sets the attribute
+   * when you provide a valid positive integer. :contentReference[oaicite:5]{index=5}
+   *
+   * Note: Not permitted when the `<colgroup>` contains one or more `<col>`
+   * elements. pkgn-sol does not enforce child-structure rules; consumers control
+   * their DOM trees. :contentReference[oaicite:6]{index=6}
+   */
+  span?: number;
+};
+
+/**
+ * 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 ColgroupAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The colgroup attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: ColgroupAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, span, ...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 ?? {}) };
+
+  // Apply `span` only when it is a valid positive integer.
+  if (typeof span === 'number' && Number.isFinite(span) && span > 0) {
+    // HTML defines span as an unsigned long; we keep it integer-ish.
+    setIfUnset(mergedAttrs, 'span', Math.trunc(span));
+  }
+
+  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;
+
+  return {
+    ...rest,
+    ...(mappedAria ? { aria: mappedAria } : null),
+    ...(hasMergedAttrs ? { attrs: mergedAttrs } : null),
+  };
+}
+
+/**
+ * Create a colgroup element with global attributes.
+ *
+ * @remarks
+ * - `<colgroup>` should not contain text content; pkgn-sol does not accept a `text`
+ *   argument for this factory.
+ * - 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 `<colgroup>` element.
+ *
+ * @example
+ * Create a colgroup that spans two columns:
+ * ```ts
+ * import { createColgroup } from "@lnpg/pkgn-sol/elements/table/colgroup";
+ *
+ * const colgroup = createColgroup({ span: 2, className: "cols" });
+ * table.appendChild(colgroup);
+ * ```
+ *
+ * @category DOM
+ */
+export function createColgroup(attrs?: ColgroupAttrs): ElementOf<typeof COLGROUP_TAG> {
+  return createElement(COLGROUP_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance colgroup 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 enhanceColgroups(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for colgroup.
+  void root;
+}

package/src/elements/table/index.ts

@@ -0,0 +1,111 @@
+/**
+ * Table element factories.
+ *
+ * Provides framework-agnostic factory functions for semantic HTML table
+ * structures and related elements.
+ *
+ * These factories:
+ * - Create semantic table elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve native table semantics and accessibility.
+ * - Prevent unsafe attribute injection.
+ *
+ * Tables in pkgn-sol are intentionally low-level primitives. They do not attempt
+ * to manage layout, styling, or data structures. Consumers remain responsible
+ * for building meaningful table structures.
+ *
+ * @module elements/table
+ * @since 0.1.0
+ */
+
+/**
+ * `<table>` element factory namespace.
+ *
+ * Represents tabular data arranged in rows and columns.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table
+ */
+export * as table from './table';
+
+/**
+ * `<colgroup>` element factory namespace.
+ *
+ * Groups one or more `<col>` elements for shared column styling and
+ * structural definition.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/colgroup
+ */
+export * as colgroup from './colgroup';
+
+/**
+ * `<col>` element factory namespace.
+ *
+ * Defines column-level properties within a table.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/col
+ */
+export * as col from './col';
+
+/**
+ * `<thead>` element factory namespace.
+ *
+ * Groups header rows that label table columns.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/thead
+ */
+export * as thead from './thead';
+
+/**
+ * `<tbody>` element factory namespace.
+ *
+ * Groups the primary body rows of a table.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tbody
+ */
+export * as tbody from './tbody';
+
+/**
+ * `<tfoot>` element factory namespace.
+ *
+ * Groups footer rows containing summaries or totals.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tfoot
+ */
+export * as tfoot from './tfoot';
+
+/**
+ * `<tr>` element factory namespace.
+ *
+ * Represents a table row.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tr
+ */
+export * as tr from './tr';
+
+/**
+ * `<th>` element factory namespace.
+ *
+ * Represents a header cell that labels a row or column.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th
+ */
+export * as th from './th';
+
+/**
+ * `<td>` element factory namespace.
+ *
+ * Represents a standard table data cell.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td
+ */
+export * as td from './td';
+
+/**
+ * `<caption>` element factory namespace.
+ *
+ * Provides a title or description for a table.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption
+ */
+export * as caption from './caption';