@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/media/math/index.ts

@@ -0,0 +1,200 @@
+/**
+ * pkgn-sol Design Foundation: Math element helpers.
+ *
+ * @remarks
+ * The MathML math element (`<math>`) represents mathematical notation.
+ *
+ * Best-practice guidance:
+ * - Prefer real MathML over images for math content when possible.
+ * - Use `display="block"` for standalone equations; inline math remains the default.
+ * - Do not rely on raw attribute injection for behavior; keep markup semantic.
+ *
+ * Accessibility defaults for pkgn-sol v0.1.0:
+ * - `<math>` is treated as decorative by default:
+ *   - `aria-hidden="true"`
+ *   - `tabIndex = -1`
+ * - If consumers provide explicit overrides (e.g. `aria.hidden`, `tabIndex`), pkgn-sol
+ *   respects them.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create MathML roots 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 { applyGlobalAttrs, 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 MathML roots.
+ *
+ * @category Constants
+ */
+export const MATH_TAG = 'math' as const;
+
+/**
+ * A CSS selector targeting math elements.
+ *
+ * @category Constants
+ */
+export const MATH_SELECTOR = 'math';
+
+/**
+ * Attribute bag for math creation/enhancement.
+ *
+ * @remarks
+ * MathML `<math>` supports the `display` attribute:
+ * - `inline` (default)
+ * - `block`
+ *
+ * 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 MathAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * MathML display mode.
+   *
+   * @remarks
+   * `block` renders as a block-level equation, `inline` renders inline.
+   */
+  display?: 'block' | 'inline';
+};
+
+/**
+ * Normalize {@link MathAttrs} into {@link GlobalAttrs} for `dom.ts`,
+ * applying pkgn-sol's MathML accessibility defaults.
+ *
+ * @param attrs - The math attributes.
+ * @returns A {@link GlobalAttrs} object (always returned to support defaults).
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: MathAttrs): GlobalAttrs {
+  const { aria, display, attrs: rawAttrs, tabIndex, ...rest } = attrs ?? {};
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  // Decorative by default, unless explicitly overridden.
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria?.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria?.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+
+  const explicitAriaHidden = typeof aria?.hidden === 'boolean';
+  if (explicitAriaHidden) {
+    mappedAria.hidden = aria.hidden!;
+  } else {
+    mappedAria.hidden = true;
+  }
+
+  if (Object.keys(mappedAria).length > 0) {
+    mapped.aria = mappedAria;
+  }
+
+  if (typeof tabIndex === 'number') {
+    mapped.tabIndex = tabIndex;
+  } else {
+    mapped.tabIndex = -1;
+  }
+
+  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(rawAttrs ?? {}) };
+
+  if (display) mergedAttrs.display = display;
+
+  if (Object.keys(mergedAttrs).length > 0) {
+    mapped.attrs = mergedAttrs;
+  }
+
+  return mapped;
+}
+
+/**
+ * Create a MathML `<math>` 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.
+ *
+ * Note: `<math>` is not part of {@link HTMLElementTagNameMap}, so pkgn-sol creates it
+ * via `document.createElement("math")` and narrows the type to {@link MathMLElement}.
+ *
+ * @param text - Optional text content for the math element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<math>` element.
+ *
+ * @category DOM
+ */
+export function createMath(text?: string, attrs?: MathAttrs): MathMLElement {
+  const el = document.createElement(MATH_TAG) as unknown as MathMLElement;
+
+  applyGlobalAttrs(el as unknown as HTMLElement, toGlobalAttrs(attrs));
+
+  if (typeof text === 'string') (el as unknown as Node).textContent = text;
+
+  return el;
+}
+
+/**
+ * Enhance math 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 enhanceMath(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for math.
+  void root;
+}

package/src/elements/media/math/math.scss

@@ -0,0 +1,46 @@
+/**
+ * pkgn-sol Design Foundation: Math Element
+ *
+ * Mathematical formula (`math`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Normalizes layout behavior for MathML
+ * - Preserves intrinsic rendering semantics
+ * - Avoids interfering with MathML display logic
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.media.math
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(math) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // MathML is inline by default.
+  display: inline;
+
+  // Prevent unexpected spacing artifacts.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  /* --------------------------------------------------------------------------
+   - Layout predictability
+   -------------------------------------------------------------------------- */
+
+  // Ensure inline math does not overflow container.
+  max-width: 100%;
+  overflow-wrap: normal;
+
+  // Maintain consistent alignment within text flow.
+  vertical-align: middle;
+
+  // Predictable sizing model.
+  box-sizing: border-box;
+}

package/src/elements/media/object/index.ts

@@ -0,0 +1,282 @@
+/**
+ * pkgn-sol Design Foundation: Object element helpers.
+ *
+ * @remarks
+ * The object element (`<object>`) embeds external resources (HTML, images, PDFs,
+ * SVG, etc.) into the document.
+ *
+ * Best-practice guidance:
+ * - Prefer purpose-built elements when available:
+ *   - `<img>` for images
+ *   - `<video>` / `<audio>` for media
+ *   - `<iframe>` for embedded documents/interactive content (with sandboxing)
+ * - Always provide a meaningful fallback inside `<object>` for unsupported content.
+ * - Avoid obsolete attributes (e.g. `codebase`, `classid`, `declare`, etc.).
+ * - For layout, prefer CSS. If using `width`/`height` attributes, keep them numeric.
+ *
+ * Attribute guidance:
+ * - At least one of `data` or `type` should be provided.
+ * - If neither is provided, pkgn-sol falls back to `data="about:blank"` to avoid an
+ *   "empty" embed configuration while staying inert.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create object 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 AttrValue, 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;
+
+  /**
+   * ID reference to the describing element(s), mapped to `aria-describedby`.
+   */
+  describedby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for object embeds.
+ *
+ * @category Constants
+ */
+export const OBJECT_TAG = 'object' as const;
+
+/**
+ * A CSS selector targeting object elements.
+ *
+ * @category Constants
+ */
+export const OBJECT_SELECTOR = 'object';
+
+/**
+ * Dimension values allowed for width/height attributes.
+ *
+ * @remarks
+ * Per best practice, keep these numeric (pixels). Prefer CSS for layout.
+ *
+ * @category Types
+ */
+export type ObjectDimension = number | `${number}`;
+
+/**
+ * Attribute bag for object creation/enhancement.
+ *
+ * @remarks
+ * - `data` and `type` are the primary configuration attributes.
+ * - Provide fallback content via `text` or by appending children after creation.
+ * - Global attributes are supported, including a structured ARIA input.
+ *
+ * @category Attributes
+ */
+export type ObjectAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Address of the resource to embed (maps to `data`).
+   */
+  data?: string;
+
+  /**
+   * MIME type of the embedded resource (maps to `type`).
+   *
+   * @example
+   * "text/html", "image/svg+xml", "application/pdf"
+   */
+  type?: string;
+
+  /**
+   * Name of the object (maps to `name`).
+   */
+  name?: string;
+
+  /**
+   * Associate the object with a form (maps to `form`).
+   */
+  form?: string;
+
+  /**
+   * Width in CSS pixels (maps to `width`).
+   *
+   * @remarks
+   * Prefer CSS for layout.
+   */
+  width?: ObjectDimension;
+
+  /**
+   * Height in CSS pixels (maps to `height`).
+   *
+   * @remarks
+   * Prefer CSS for layout.
+   */
+  height?: ObjectDimension;
+
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Validate and normalize a width/height value.
+ *
+ * @param name - Attribute name for error messages.
+ * @param v - The provided dimension.
+ * @returns A normalized string suitable for attributes.
+ *
+ * @category Internal
+ */
+function normalizeDimension(name: 'width' | 'height', v: ObjectDimension): string {
+  if (typeof v === 'number') {
+    if (!Number.isFinite(v) || v < 0 || !Number.isInteger(v)) {
+      throw new Error(`Invalid ${name}: expected a non-negative integer.`);
+    }
+    return String(v);
+  }
+
+  // String numeric (template literal), but validate anyway.
+  if (!/^\d+$/.test(v)) {
+    throw new Error(`Invalid ${name}: expected a numeric string.`);
+  }
+
+  return v;
+}
+
+/**
+ * Normalize {@link ObjectAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The object attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: ObjectAttrs): GlobalAttrs | undefined {
+  if (!attrs) {
+    // Best-practice: an object should have at least data or type.
+    // We still allow `createObject()` with no args, but keep it inert.
+    return { attrs: { data: 'about:blank' } };
+  }
+
+  const { aria, data, type, name, form, width, height, attrs: extraAttrs, ...rest } = attrs;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+  if (aria) {
+    if (typeof aria.label === 'string') mappedAria.label = aria.label;
+    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+    if (typeof aria.describedby === 'string') mappedAria.describedby = aria.describedby;
+    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+  }
+
+  const mappedAttrs: Record<string, AttrValue> = { ...(extraAttrs ?? {}) };
+
+  // Primary embed configuration.
+  if (typeof data === 'string' && data.length > 0) mappedAttrs.data = data;
+  if (typeof type === 'string' && type.length > 0) mappedAttrs.type = type;
+
+  // Per guidance/spec: at least one of data/type should exist.
+  // If neither is provided, keep it inert rather than "empty".
+  if (mappedAttrs.data === undefined && mappedAttrs.type === undefined) {
+    mappedAttrs.data = 'about:blank';
+  }
+
+  if (typeof name === 'string' && name.length > 0) mappedAttrs.name = name;
+  if (typeof form === 'string' && form.length > 0) mappedAttrs.form = form;
+
+  if (width !== undefined) mappedAttrs.width = normalizeDimension('width', width);
+  if (height !== undefined) mappedAttrs.height = normalizeDimension('height', height);
+
+  const hasMappedAria = Object.keys(mappedAria).length > 0;
+  const hasMappedAttrs = Object.keys(mappedAttrs).length > 0;
+
+  return {
+    ...rest,
+    ...(hasMappedAria ? { aria: mappedAria } : null),
+    ...(hasMappedAttrs ? { attrs: mappedAttrs } : null),
+  };
+}
+
+/**
+ * Create an object element with optional fallback text and attributes.
+ *
+ * @remarks
+ * - Fallback text is assigned via `textContent` (never `innerHTML`).
+ * - For richer fallback, append children after creation.
+ * - 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 fallback text content for the object.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<object>` element.
+ *
+ * @example
+ * ```ts
+ * import { createObject } from "@lnpg/pkgn-sol/elements/media/object";
+ *
+ * const obj = createObject("Your browser can't display this content.", {
+ *   data: "/docs/guide.pdf",
+ *   type: "application/pdf",
+ *   width: 640,
+ *   height: 480,
+ * });
+ *
+ * document.body.appendChild(obj);
+ * ```
+ *
+ * @category DOM
+ */
+export function createObject(text?: string, attrs?: ObjectAttrs): ElementOf<typeof OBJECT_TAG> {
+  return createElement(OBJECT_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance object 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 enhanceObjects(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for object.
+  void root;
+}

package/src/elements/media/object/object.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Object Element
+ *
+ * External resource (`object`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Normalizes `<object>` as a replaced element for predictable layout
+ * - Removes legacy border presentation (historically affected by deprecated `border`-style attributes)
+ * - Avoids opinionated sizing/aspect-ratio behavior (author-controlled)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.media.object
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(object) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Replaced element baseline.
+  display: inline-block;
+  vertical-align: middle;
+
+  // Remove legacy/UA presentation quirks.
+  border: 0;
+  margin: 0;
+  padding: 0;
+
+  /* --------------------------------------------------------------------------
+   - Layout predictability
+   -------------------------------------------------------------------------- */
+
+  // Predictable sizing model when constrained by layout, without overriding
+  // explicit author sizing.
+  box-sizing: border-box;
+  max-width: 100%;
+}

package/src/elements/media/svg/index.ts

@@ -0,0 +1,122 @@
+/**
+ * pkgn-sol Design Foundation: Svg element helpers.
+ *
+ * @remarks
+ * The svg element (`<svg>`) defines scalable vector graphics.
+ *
+ * pkgn-sol enforces:
+ * - Default decorative behaviour:
+ *   - aria-hidden="true"
+ *   - tabIndex = -1
+ *   - focusable="false"
+ * - If aria.label or aria.labelledby is provided:
+ *   - role="img" is added (unless explicitly set)
+ * - Explicit overrides for role, aria-hidden and tabIndex are respected.
+ *
+ * @module
+ * @category Elements
+ */
+
+import { applyGlobalAttrs, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input.
+ */
+export type StructuredAria = {
+  label?: string;
+  labelledby?: string;
+  hidden?: boolean;
+};
+
+export const SVG_TAG = 'svg';
+export const SVG_SELECTOR = 'svg';
+
+export type SvgAttrs = Omit<GlobalAttrs, 'aria'> & {
+  viewBox?: string;
+  width?: number | string;
+  height?: number | string;
+  aria?: StructuredAria;
+};
+
+function toGlobalAttrs(attrs?: SvgAttrs): GlobalAttrs {
+  const { aria, viewBox, width, height, role, tabIndex, attrs: rawAttrs, ...rest } = attrs ?? {};
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  // Preserve explicit role
+  if (role) {
+    mapped.role = role;
+  }
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  const hasLabel = typeof aria?.label === 'string';
+  const hasLabelledby = typeof aria?.labelledby === 'string';
+  const explicitAriaHidden = typeof aria?.hidden === 'boolean';
+
+  if (hasLabel) mappedAria.label = aria.label!;
+  if (hasLabelledby) mappedAria.labelledby = aria.labelledby!;
+  if (explicitAriaHidden) mappedAria.hidden = aria.hidden!;
+
+  const isDecorative = !hasLabel && !hasLabelledby;
+
+  if (isDecorative && !explicitAriaHidden) {
+    mappedAria.hidden = true;
+  }
+
+  if (Object.keys(mappedAria).length > 0) {
+    mapped.aria = mappedAria;
+  }
+
+  // Only auto-assign role if user did not provide one
+  if (!isDecorative && !role) {
+    mapped.role = 'img';
+  }
+
+  if (typeof tabIndex === 'number') {
+    mapped.tabIndex = tabIndex;
+  } else if (isDecorative) {
+    mapped.tabIndex = -1;
+  }
+
+  // Merge user attrs with internal attrs
+  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = {
+    ...(rawAttrs ?? {}),
+  };
+
+  if (isDecorative) {
+    mergedAttrs.focusable = 'false';
+  }
+
+  if (viewBox) mergedAttrs.viewBox = viewBox;
+  if (width !== undefined) mergedAttrs.width = width;
+  if (height !== undefined) mergedAttrs.height = height;
+
+  if (Object.keys(mergedAttrs).length > 0) {
+    mapped.attrs = mergedAttrs;
+  }
+
+  return mapped;
+}
+
+/**
+ * Create an SVG element with accessibility defaults.
+ */
+export function createSvg(text?: string, attrs?: SvgAttrs): SVGSVGElement {
+  const el = document.createElement('svg') as unknown as SVGSVGElement;
+
+  applyGlobalAttrs(el as unknown as HTMLElement, toGlobalAttrs(attrs));
+
+  if (typeof text === 'string') {
+    el.textContent = text;
+  }
+
+  return el;
+}
+
+/**
+ * No-op enhancement hook.
+ */
+export function enhanceSvgs(root: ParentNode = document): void {
+  void root;
+}