@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,208 @@
+/**
+ * pkgn-sol Design Foundation: Data (`data`) element helpers.
+ *
+ * @remarks
+ * The data element (`<data>`) links human-readable content to a machine-readable
+ * value via the `value` attribute.
+ *
+ * Best-practice guidance:
+ * - Use `value` for canonical/machine-readable values (IDs, codes, normalized forms).
+ * - Keep visible text human-friendly.
+ * - Prefer explicit `value` when the machine value differs from the displayed text.
+ *
+ * pkgn-sol applies a sensible fallback:
+ * - If `attrs.value` is omitted and `text` is provided, pkgn-sol sets `value` to `text`.
+ *
+ * Security notes:
+ * - pkgn-sol blocks unsafe attribute *names* (e.g. `onclick`, raw `style`).
+ * - pkgn-sol does not sanitize attribute *values*. Treat untrusted inputs accordingly.
+ *
+ * References:
+ * - MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/data
+ * - WHATWG: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-data-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`.
+   */
+  label?: string;
+
+  /**
+   * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * Allowed value types for the `value` attribute on `<data>`.
+ *
+ * @remarks
+ * HTML treats attributes as strings. pkgn-sol allows string/number and coerces to string.
+ *
+ * @category Attributes
+ */
+export type DataValue = string | number;
+
+/**
+ * The semantic tag name for data elements.
+ *
+ * @category Constants
+ */
+export const DATA_TAG = 'data' as const;
+
+/**
+ * A CSS selector targeting data elements.
+ *
+ * @category Constants
+ */
+export const DATA_SELECTOR = 'data';
+
+/**
+ * Attribute bag for data element creation/enhancement.
+ *
+ * @remarks
+ * Data elements accept standard HTML global attributes, plus:
+ * - `value`: machine-readable translation of the element's content.
+ *
+ * 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 DataAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Machine-readable value for the data.
+   *
+   * @remarks
+   * If omitted and `text` is provided, pkgn-sol falls back to using `text` as `value`.
+   */
+  value?: DataValue;
+
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DataAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The data element attributes.
+ * @param text - Optional text content used for the `value` fallback.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DataAttrs, text?: string): GlobalAttrs | undefined {
+  if (!attrs) {
+    // Even when attrs are omitted, we may still want to apply the value fallback.
+    // However, without an attrs bag there's nowhere to attach `attrs.value`.
+    return undefined;
+  }
+
+  const { aria, value, ...rest } = attrs;
+
+  const out: GlobalAttrs = rest;
+
+  const rawAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(out.attrs ?? {}) };
+
+  // Prefer explicit `value`. Otherwise, fall back to `text` (if provided).
+  const effectiveValue =
+    typeof value === 'string' || typeof value === 'number'
+      ? value
+      : typeof text === 'string'
+        ? text
+        : undefined;
+
+  if (typeof effectiveValue === 'string' || typeof effectiveValue === 'number') {
+    rawAttrs.value = effectiveValue;
+  }
+
+  if (Object.keys(rawAttrs).length > 0) out.attrs = rawAttrs;
+
+  if (!aria) return out;
+
+  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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...out, aria: mappedAria } : out;
+}
+
+/**
+ * Create a data 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.
+ * - If `attrs.value` is omitted and `text` is provided, pkgn-sol sets `value` to `text`.
+ *
+ * @param text - Optional human-readable content for the data element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<data>` element.
+ *
+ * @example
+ * ```ts
+ * import { createData } from "@lnpg/pkgn-sol/elements/inline/data";
+ *
+ * document.body.appendChild(
+ *   createData("Mini Ketchup", { value: 398 })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createData(text?: string, attrs?: DataAttrs): ElementOf<typeof DATA_TAG> {
+  return createElement(DATA_TAG, toGlobalAttrs(attrs, text), text);
+}
+
+/**
+ * Enhance data 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 enhanceDatas(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for data.
+  void root;
+}

package/src/elements/inline/dfn/dfn.scss

@@ -0,0 +1,36 @@
+/**
+ * pkgn-sol Design Foundation: DFN Element
+ *
+ * Defining instance (`dfn`)
+ *
+ * Baseline reset + light normalization.
+ *
+ * This module:
+ * - Preserves semantic "definition" emphasis
+ * - Normalizes italic styling explicitly
+ * - Avoids introducing additional presentation
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.dfn
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(dfn) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Normalize to explicit italic for consistent emphasis.
+  font-style: italic;
+
+  // Preserve inherited typography context.
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,164 @@
+/**
+ * pkgn-sol Design Foundation: Dfn element helpers.
+ *
+ * @remarks
+ * The dfn element (`<dfn>`) indicates the defining instance of a term.
+ * The nearest containing phrasing context (often a paragraph, list item, or
+ * section) should include the term's definition.
+ *
+ * Best-practice guidance:
+ * - Use `<dfn>` for the defining instance of a term, not for general emphasis.
+ * - Avoid nesting `<dfn>` inside another `<dfn>`.
+ * - If you use the `title` attribute on `<dfn>`, it should contain only the term
+ *   being defined (useful when the displayed text differs from the term).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create definition-term markers 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/dfn
+ *
+ * @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 defining instances of terms.
+ *
+ * @category Constants
+ */
+export const DFN_TAG = 'dfn' as const;
+
+/**
+ * A CSS selector targeting dfn elements.
+ *
+ * @category Constants
+ */
+export const DFN_SELECTOR = 'dfn';
+
+/**
+ * Attribute bag for dfn creation/enhancement.
+ *
+ * @remarks
+ * Dfn 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 DfnAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DfnAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The dfn attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DfnAttrs): 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 dfn 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 dfn element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dfn>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDfn } from "@lnpg/pkgn-sol/elements/inline/dfn";
+ *
+ * document.body.appendChild(
+ *   createDfn("validator", { id: "term-validator" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createDfn(text?: string, attrs?: DfnAttrs): ElementOf<typeof DFN_TAG> {
+  return createElement(DFN_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance dfn 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 enhanceDfns(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for dfn.
+  void root;
+}

package/src/elements/inline/em/em.scss

@@ -0,0 +1,35 @@
+/**
+ * pkgn-sol Design Foundation: Emphasis Element
+ *
+ * Stress emphasis (`em`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Preserves semantic emphasis with consistent italic rendering
+ * - Avoids introducing typography decisions beyond the element's purpose
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.em
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(em) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Preserve semantic emphasis explicitly (UA styles typically use italic).
+  font-style: italic;
+
+  // Keep typography otherwise inherited.
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,164 @@
+/**
+ * pkgn-sol Design Foundation: Em element helpers.
+ *
+ * @remarks
+ * The em element (`<em>`) marks text that has stress emphasis. Stress emphasis is
+ * semantic: it can change the meaning of a sentence, and nested `<em>` elements
+ * indicate a greater degree of emphasis. :contentReference[oaicite:2]{index=2}
+ *
+ * Best-practice guidance:
+ * - Use `<em>` when you would change vocal stress if speaking the sentence.
+ * - Avoid using `<em>` purely for visual styling (e.g. italics); use CSS instead.
+ * - Nested `<em>` increases emphasis; do not nest for decoration. :contentReference[oaicite:3]{index=3}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create emphasis 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.
+ *
+ * @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 stress emphasis.
+ *
+ * @category Constants
+ */
+export const EM_TAG = 'em' as const;
+
+/**
+ * A CSS selector targeting em elements.
+ *
+ * @category Constants
+ */
+export const EM_SELECTOR = 'em';
+
+/**
+ * Attribute bag for em creation/enhancement.
+ *
+ * @remarks
+ * The `<em>` element uses standard HTML global attributes. :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.
+ *
+ * @category Attributes
+ */
+export type EmAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link EmAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The em attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: EmAttrs): 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 em 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 em element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<em>` element.
+ *
+ * @example
+ * Stress emphasis:
+ * ```ts
+ * import { createEm } from "@lnpg/pkgn-sol/elements/inline/em";
+ *
+ * const e = createEm("really", { className: "stress" });
+ * document.body.appendChild(e);
+ * ```
+ *
+ * @category DOM
+ */
+export function createEm(text?: string, attrs?: EmAttrs): ElementOf<typeof EM_TAG> {
+  return createElement(EM_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance em 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 enhanceEms(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for em.
+  void root;
+}

package/src/elements/inline/i/i.scss

@@ -0,0 +1,38 @@
+/**
+ * pkgn-sol Design Foundation: I Element
+ *
+ * Idiomatic text (`i`)
+ *
+ * Baseline reset + normalized italic rendering.
+ *
+ * Notes:
+ * - `<i>` represents text in an alternate voice or mood (idiomatic).
+ * - UA styles commonly render `<i>` as italic, but not uniformly.
+ * - Normalize explicitly while preserving inherited typography otherwise.
+ *
+ * References (2025+):
+ * - MDN: `<i>` element reference (Aug 2025)
+ *
+ * @module
+ * @group  elements.inline.i
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(i) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Normalize idiomatic emphasis to italic (common UA behavior).
+  font-style: italic;
+
+  // Preserve inherited typography context otherwise.
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}