@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/list/ul/index.ts

@@ -0,0 +1,195 @@
+/**
+ * pkgn-sol Design Foundation: Unordered list (ul) element helpers.
+ *
+ * @remarks
+ * The unordered list element (`<ul>`) represents a list of items where the
+ * order does not change the meaning.
+ *
+ * Best-practice guidance:
+ * - Use `<ul>` for lists where sequence is not meaningful (use `<ol>` when it is).
+ * - Ensure list children are `<li>` elements.
+ * - Do not use `<ul>` purely for indentation or spacing; use CSS for layout.
+ * - The legacy `type` attribute is obsolete; prefer `list-style-type` in CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<ul>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - optionally set legacy presentation attributes in a controlled way
+ *
+ * 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 unordered lists.
+ *
+ * @category Constants
+ */
+export const UL_TAG = 'ul' as const;
+
+/**
+ * A CSS selector targeting unordered list elements.
+ *
+ * @category Constants
+ */
+export const UL_SELECTOR = 'ul';
+
+/**
+ * Legacy marker style values for `<ul type="...">`.
+ *
+ * @remarks
+ * The `type` attribute is obsolete in HTML5. Prefer CSS `list-style-type`.
+ * This is included as a pragmatic escape hatch for legacy markup needs.
+ *
+ * @category Attributes
+ */
+export type UlLegacyType = 'disc' | 'circle' | 'square';
+
+/**
+ * Attribute bag for ul creation/enhancement.
+ *
+ * @remarks
+ * `<ul>` primarily accepts standard HTML global attributes.
+ *
+ * pkgn-sol also supports:
+ * - structured ARIA input mapped into `aria-*`
+ * - optional legacy `type` mapping to the `type` attribute (obsolete)
+ * - an `attrs` escape hatch, still guarded by pkgn-sol's attribute safety rules
+ *
+ * @category Attributes
+ */
+export type UlAttrs = Omit<GlobalAttrs, 'aria' | 'attrs'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Legacy bullet style hint mapped to the `type` attribute (obsolete).
+   *
+   * @remarks
+   * Prefer CSS `list-style-type` instead.
+   */
+  type?: UlLegacyType;
+
+  /**
+   * 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 UlAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The ul attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: UlAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, type, 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;
+  }
+
+  // Merge escape-hatch attrs and add legacy `type` if provided.
+  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(extraAttrs ?? {}) };
+  if (typeof type === 'string' && type.length > 0) mergedAttrs.type = type;
+
+  if (Object.keys(mergedAttrs).length > 0) mapped.attrs = mergedAttrs;
+
+  return mapped;
+}
+
+/**
+ * Create an unordered list (`<ul>`) with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - In real documents, `<ul>` should contain `<li>` children, not raw text.
+ *   The optional `text` parameter exists for consistency with pkgn-sol factories and
+ *   testing convenience.
+ * - 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 ul.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<ul>` element.
+ *
+ * @example
+ * ```ts
+ * import { createUl } from "@lnpg/pkgn-sol/elements/list/ul";
+ *
+ * const ul = createUl(undefined, { id: "features" });
+ * document.body.appendChild(ul);
+ * ```
+ *
+ * @category DOM
+ */
+export function createUl(text?: string, attrs?: UlAttrs): ElementOf<typeof UL_TAG> {
+  return createElement(UL_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance unordered list 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 enhanceUls(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for ul.
+  void root;
+}

package/src/elements/list/ul/ul.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: UL Element
+ *
+ * Unordered list (`ul`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - Preserve list markers (accessibility + semantics).
+ * - Normalize UA margin/padding variance.
+ * - Avoid decorative styling at baseline.
+ *
+ * References (2025+):
+ * - MDN: `<ul>` element reference (Sep 2025)
+ * - Modern CSS reset guidance (Oct 2025)
+ *
+ * @module
+ * @group  elements.list.ul
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(ul) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA vertical spacing.
+  margin: 0;
+
+  // Normalize indentation consistently across engines.
+  padding-inline-start: 1.5em;
+
+  // Preserve default marker style.
+  list-style-position: outside;
+  list-style-type: disc;
+
+  // Ensure predictable sizing.
+  box-sizing: border-box;
+}

package/src/elements/media/audio/audio.scss

@@ -0,0 +1,43 @@
+/**
+ * pkgn-sol Design Foundation: Audio Element
+ *
+ * Media player (`audio`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Normalizes `<audio>` layout behavior across browsers
+ * - Removes legacy presentation artifacts
+ * - Preserves intrinsic control rendering
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.media.audio
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(audio) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Replaced element baseline.
+  display: inline-block;
+  vertical-align: middle;
+
+  // Remove incidental UA presentation.
+  border: 0;
+  margin: 0;
+  padding: 0;
+
+  /* --------------------------------------------------------------------------
+   - Layout predictability
+   -------------------------------------------------------------------------- */
+
+  // Allow responsive containment without overriding explicit author sizing.
+  max-width: 100%;
+
+  // Predictable sizing model.
+  box-sizing: border-box;
+}

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

@@ -0,0 +1,281 @@
+/**
+ * pkgn-sol Design Foundation: Audio element helpers.
+ *
+ * @remarks
+ * The audio element (`<audio>`) embeds sound content in documents.
+ * It can load audio via `src` or nested `<source>` elements, and it can
+ * also be a destination for streamed media via MediaStream.
+ *
+ * Best-practice guidance (MDN + platform norms):
+ * - Avoid autoplaying audio unless the user explicitly opts in.
+ * - Prefer showing controls (`controls`) when audio playback is user-facing.
+ * - Use `preload="metadata"` as a sensible hint if you want duration, etc.
+ * - Use CORS (`crossOrigin`) when audio might be reused by `<canvas>` without tainting.
+ * - Prefer multiple `<source>` elements for format fallbacks where needed.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create audio 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.
+ *
+ * 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 `preload` values for media elements.
+ *
+ * @remarks
+ * Per MDN, browsers treat this as a hint and may ignore it; `metadata` is a
+ * common best-practice default in specs/guidance.
+ *
+ * @category Attributes
+ */
+export type AudioPreload = 'none' | 'metadata' | 'auto';
+
+/**
+ * Allowed values for the `crossorigin` attribute for media fetches.
+ *
+ * @category Attributes
+ */
+export type AudioCrossOrigin = 'anonymous' | 'use-credentials';
+
+/**
+ * Allowed tokens for the `controlslist` attribute (when `controls` is enabled).
+ *
+ * @remarks
+ * MDN lists allowed values including `nodownload`, `nofullscreen`, `noremoteplayback`.
+ * (`nofullscreen` is effectively video-oriented but is still a valid token in the attribute.)
+ *
+ * @category Attributes
+ */
+export type AudioControlsList = 'nodownload' | 'nofullscreen' | 'noremoteplayback';
+
+/**
+ * The semantic tag name for audio elements.
+ *
+ * @category Constants
+ */
+export const AUDIO_TAG = 'audio' as const;
+
+/**
+ * A CSS selector targeting audio elements.
+ *
+ * @category Constants
+ */
+export const AUDIO_SELECTOR = 'audio';
+
+/**
+ * Attribute bag for audio creation/enhancement.
+ *
+ * @remarks
+ * Audio elements accept HTML global attributes plus a media-specific subset.
+ * pkgn-sol also supports structured ARIA input for common ARIA fields.
+ *
+ * @category Attributes
+ */
+export type AudioAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * The URL of the audio resource to embed.
+   *
+   * @remarks
+   * Optional if you instead provide nested `<source>` elements.
+   */
+  src?: string;
+
+  /**
+   * Whether browser playback controls should be shown.
+   */
+  controls?: boolean;
+
+  /**
+   * Whether playback should begin automatically.
+   *
+   * @remarks
+   * Autoplaying audio is often blocked unless user-initiated. If `autoplay`
+   * is enabled and `muted` is not specified, pkgn-sol defaults `muted` to `true`
+   * as a pragmatic alignment with autoplay policies.
+   */
+  autoplay?: boolean;
+
+  /**
+   * Whether the audio should loop back to the start after ending.
+   */
+  loop?: boolean;
+
+  /**
+   * Whether the audio should start out muted.
+   */
+  muted?: boolean;
+
+  /**
+   * Hint about how much to preload.
+   */
+  preload?: AudioPreload;
+
+  /**
+   * CORS mode for fetching the audio resource.
+   */
+  crossOrigin?: AudioCrossOrigin;
+
+  /**
+   * Restrict which built-in controls the user agent exposes (when `controls` is set).
+   *
+   * @example
+   * controlsList: ['nodownload', 'noremoteplayback']
+   */
+  controlsList?: AudioControlsList[];
+
+  /**
+   * Disable remote playback (Chromecast/AirPlay/etc).
+   */
+  disableRemotePlayback?: boolean;
+};
+
+/**
+ * Normalize {@link AudioAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The audio attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: AudioAttrs): 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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * Create an audio element with optional attributes.
+ *
+ * @remarks
+ * 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 through escape hatches.
+ *
+ * Media-specific attributes are applied directly to the element.
+ *
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<audio>` element.
+ *
+ * @example
+ * ```ts
+ * import { createAudio } from "@lnpg/pkgn-sol/elements/media/audio";
+ *
+ * document.body.appendChild(
+ *   createAudio({ controls: true, src: "/audio/intro.mp3", preload: "metadata" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createAudio(attrs?: AudioAttrs): ElementOf<typeof AUDIO_TAG> {
+  const el = createElement(AUDIO_TAG, toGlobalAttrs(attrs));
+
+  if (!attrs) return el;
+
+  if (typeof attrs.src === 'string') el.src = attrs.src;
+
+  if (typeof attrs.controls === 'boolean') el.controls = attrs.controls;
+
+  if (typeof attrs.autoplay === 'boolean') el.autoplay = attrs.autoplay;
+  if (typeof attrs.loop === 'boolean') el.loop = attrs.loop;
+
+  // Pragmatic autoplay alignment: if autoplay is enabled and muted is not provided,
+  // default to muted to reduce the chance of autoplay being blocked.
+  if (typeof attrs.muted === 'boolean') {
+    el.muted = attrs.muted;
+  } else if (attrs.autoplay === true) {
+    el.muted = true;
+  }
+
+  if (typeof attrs.preload === 'string') el.preload = attrs.preload;
+
+  if (typeof attrs.crossOrigin === 'string') el.crossOrigin = attrs.crossOrigin;
+
+  if (Array.isArray(attrs.controlsList) && attrs.controlsList.length > 0) {
+    // `controlslist` is a token list attribute; set as a space-separated list.
+    el.setAttribute('controlslist', attrs.controlsList.join(' '));
+  }
+
+  if (typeof attrs.disableRemotePlayback === 'boolean') {
+    if (attrs.disableRemotePlayback) el.setAttribute('disableremoteplayback', '');
+    else el.removeAttribute('disableremoteplayback');
+  }
+
+  return el;
+}
+
+/**
+ * Enhance audio 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 enhanceAudios(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for audio.
+  void root;
+}

package/src/elements/media/canvas/canvas.scss

@@ -0,0 +1,46 @@
+/**
+ * pkgn-sol Design Foundation: Canvas Element
+ *
+ * Graphic canvas (`canvas`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Normalizes display and rendering baseline
+ * - Preserves inline-block behavior
+ * - Ensures predictable sizing and overflow handling
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<canvas>` element (intrinsic sizing + script-driven content)
+ * - Modern reset guidance: avoid overriding replaced element intrinsic semantics
+ * - CSS WG logical property expectations
+ *
+ * @module
+ * @group  elements.media.canvas
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(canvas) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Display and structural behavior
+  display: inline-block; // UA default, best for replaced elements
+
+  // Remove any unexpected margins/padding
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  /* --------------------------------------------------------------------------
+   - Layout predictability
+   -------------------------------------------------------------------------- */
+
+  // Ensure canvas does not overflow out of flow unexpectedly
+  max-width: 100%;
+  height: auto; // preserve aspect ratio
+  box-sizing: border-box; // predictable sizing
+}