@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/inline/sup/index.ts

@@ -0,0 +1,165 @@
+/**
+ * pkgn-sol Design Foundation: Sup element helpers.
+ *
+ * @remarks
+ * The sup element (`<sup>`) represents superscript text.
+ *
+ * Best-practice guidance:
+ * - Use `<sup>` for semantic superscripts such as footnote markers, ordinal indicators,
+ *   and mathematical exponents.
+ * - Avoid using `<sup>` purely for visual styling; prefer CSS when semantics are not intended.
+ * - For footnotes, consider pairing markers with accessible labelling (e.g. via `aria-label`)
+ *   and appropriate linking patterns.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create superscript nodes 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.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
+ *
+ * @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 superscript elements.
+ *
+ * @category Constants
+ */
+export const SUP_TAG = 'sup' as const;
+
+/**
+ * A CSS selector targeting sup elements.
+ *
+ * @category Constants
+ */
+export const SUP_SELECTOR = 'sup';
+
+/**
+ * Attribute bag for sup creation/enhancement.
+ *
+ * @remarks
+ * Sup 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 SupAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link SupAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The sup attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: SupAttrs): 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 sup 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 sup.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<sup>` element.
+ *
+ * @example
+ * Create a footnote marker:
+ * ```ts
+ * import { createSup } from "@lnpg/pkgn-sol/elements/inline/sup";
+ *
+ * const marker = createSup("1", { aria: { label: "Footnote 1" } });
+ * ```
+ *
+ * @category DOM
+ */
+export function createSup(text?: string, attrs?: SupAttrs): ElementOf<typeof SUP_TAG> {
+  return createElement(SUP_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance sup 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 enhanceSups(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for sup.
+  void root;
+}

package/src/elements/inline/sup/sup.scss

@@ -0,0 +1,43 @@
+/**
+ * pkgn-sol Design Foundation: Sup Element
+ *
+ * Superscript (`sup`)
+ *
+ * Baseline reset + normalized superscript behavior.
+ *
+ * Notes:
+ * - `<sup>` raises text relative to baseline.
+ * - UA styles typically reduce font-size and adjust vertical alignment.
+ * - Normalize explicitly for consistent rendering across engines.
+ *
+ * References (2025+):
+ * - MDN: `<sup>` element reference (Sep 2025)
+ *
+ * @module
+ * @group  elements.inline.sup
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(sup) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Explicit scaling rather than UA relative sizing.
+  font-size: 0.75em;
+
+  // Prevent superscripts from inflating line boxes unpredictably.
+  line-height: 0;
+
+  // Normalize vertical shift.
+  vertical-align: super;
+
+  // Preserve inherited typography context.
+  font-family: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  color: inherit;
+}

package/src/elements/inline/time/index.ts

@@ -0,0 +1,206 @@
+/**
+ * pkgn-sol Design Foundation: Time element helpers.
+ *
+ * @remarks
+ * The time element (`<time>`) represents a specific period in time.
+ *
+ * Best-practice guidance (summary):
+ * - Provide a machine-readable `datetime` value when possible.
+ * - Keep visible text human-friendly (e.g. "Tomorrow", "12 Feb 2026").
+ * - Avoid using `<time>` purely for styling.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<time>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - supply a typed `datetime`/`dateTime` field mapped to the `datetime` attribute
+ *
+ * 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.
+ *
+ * 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 time.
+ *
+ * @category Constants
+ */
+export const TIME_TAG = 'time' as const;
+
+/**
+ * A CSS selector targeting time elements.
+ *
+ * @category Constants
+ */
+export const TIME_SELECTOR = 'time';
+
+/**
+ * Attribute bag for time creation/enhancement.
+ *
+ * @remarks
+ * In addition to global attributes, `<time>` commonly uses the `datetime`
+ * attribute to provide a machine-readable value.
+ *
+ * pkgn-sol supports:
+ * - `datetime` (preferred, aligns with the HTML attribute name)
+ * - `dateTime` (alias for ergonomic camelCase usage)
+ *
+ * @category Attributes
+ */
+export type TimeAttrs = Omit<GlobalAttrs, 'aria' | 'attrs'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Machine-readable time value, mapped to the `datetime` attribute.
+   *
+   * @remarks
+   * Examples:
+   * - `2026-02-25`
+   * - `2026-02-25T16:30:00Z`
+   * - `PT2H`
+   *
+   * If a {@link Date} is provided, it is converted via `toISOString()`.
+   */
+  datetime?: string | Date;
+
+  /**
+   * Alias of {@link TimeAttrs.datetime}.
+   *
+   * @remarks
+   * Supported for ergonomic camelCase input. If both are provided, `datetime`
+   * takes precedence.
+   */
+  dateTime?: string | Date;
+
+  /**
+   * Additional attributes not modeled above.
+   *
+   * @remarks
+   * This exists as an escape hatch while still allowing pkgn-sol to apply its
+   * attribute safety rules via `dom.ts`.
+   */
+  attrs?: GlobalAttrs['attrs'];
+};
+
+/**
+ * Normalize {@link TimeAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The time attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TimeAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, datetime, dateTime, attrs: extraAttrs, ...rest } = attrs;
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  // Map structured aria.
+  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) mapped.aria = mappedAria;
+  }
+
+  // Map datetime/dateTime -> datetime attribute, while preserving any provided attrs.
+  const v = datetime ?? dateTime;
+
+  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(extraAttrs ?? {}) };
+
+  if (typeof v === 'string') {
+    if (v.length > 0) mergedAttrs.datetime = v;
+  } else if (v instanceof Date) {
+    mergedAttrs.datetime = v.toISOString();
+  }
+
+  if (Object.keys(mergedAttrs).length > 0) mapped.attrs = mergedAttrs;
+
+  return mapped;
+}
+
+/**
+ * Create a time 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 time element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<time>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTime } from "@lnpg/pkgn-sol/elements/inline/time";
+ *
+ * const t = createTime("25 Feb 2026", { datetime: "2026-02-25" });
+ * document.body.appendChild(t);
+ * ```
+ *
+ * @example
+ * Using the `dateTime` alias:
+ * ```ts
+ * const t = createTime("25 Feb 2026", { dateTime: "2026-02-25" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createTime(text?: string, attrs?: TimeAttrs): ElementOf<typeof TIME_TAG> {
+  return createElement(TIME_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance time 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 enhanceTimes(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for time.
+  void root;
+}

package/src/elements/inline/time/time.scss

@@ -0,0 +1,38 @@
+/**
+ * pkgn-sol Design Foundation: Time Element
+ *
+ * Date / time (`time`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - `<time>` is a semantic wrapper (human-readable content + machine-readable `datetime`).
+ * - It carries no meaningful UA presentation; keep it neutral and inherited.
+ *
+ * References (2025+):
+ * - MDN: `<time>` element reference (Aug 2025)
+ *
+ * @module
+ * @group  elements.inline.time
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(time) {
+  /* --------------------------------------------------------------------------
+   - Baseline
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Preserve inherited typography.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

package/src/elements/inline/u/index.ts

@@ -0,0 +1,162 @@
+/**
+ * pkgn-sol Design Foundation: U element helpers.
+ *
+ * @remarks
+ * The u element (`<u>`) represents a span of text with an unarticulated,
+ * explicitly rendered non-textual annotation.
+ *
+ * Best-practice guidance:
+ * - Do not use `<u>` purely for underlining text. Use CSS (`text-decoration`) for
+ *   presentation.
+ * - Use `<u>` only when the semantics are appropriate (e.g. marking misspellings
+ *   or other non-textual annotations).
+ * - Avoid usage where it could be confused with a hyperlink.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create u elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u
+ *
+ * @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 unarticulated annotation spans.
+ *
+ * @category Constants
+ */
+export const U_TAG = 'u' as const;
+
+/**
+ * A CSS selector targeting u elements.
+ *
+ * @category Constants
+ */
+export const U_SELECTOR = 'u';
+
+/**
+ * Attribute bag for u creation/enhancement.
+ *
+ * @remarks
+ * U 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 UAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link UAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The u attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: UAttrs): 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 u 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 u element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<u>` element.
+ *
+ * @example
+ * ```ts
+ * import { createU } from "@lnpg/pkgn-sol/elements/inline/u";
+ *
+ * const misspelt = createU("teh", { aria: { label: "Misspelt word" } });
+ * ```
+ *
+ * @category DOM
+ */
+export function createU(text?: string, attrs?: UAttrs): ElementOf<typeof U_TAG> {
+  return createElement(U_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance u 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 enhanceUs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for u.
+  void root;
+}

package/src/elements/inline/u/u.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: U Element
+ *
+ * Unarticulated annotation (`u`)
+ *
+ * Baseline reset + normalized underline.
+ *
+ * Notes:
+ * - `<u>` is an annotation, not "make it underlined".
+ * - UA underlining varies in thickness/ink skipping.
+ * - Normalize underline via `text-decoration` while preserving inherited typography.
+ *
+ * References (2025+):
+ * - MDN: `<u>` element reference (Aug 2025)
+ * - MDN: `text-decoration` properties (2025)
+ *
+ * @module
+ * @group  elements.inline.u
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(u) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Normalize underline rendering.
+  text-decoration-line: underline;
+  text-decoration-color: currentcolor;
+  text-decoration-skip-ink: auto;
+
+  // Preserve inherited typography context.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}