@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/list/index.ts

@@ -0,0 +1,74 @@
+/**
+ * List element factories.
+ *
+ * Provides framework-agnostic factory functions for HTML list and list-related
+ * elements used to express collections of items and term/description pairs.
+ *
+ * These factories:
+ * - Create list elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Encourage accessible, standards-aligned markup.
+ * - Prevent unsafe attribute injection.
+ *
+ * List elements are the backbone of navigations, feature lists, checklists, and
+ * definition/description content, while preserving semantic meaning for assistive
+ * technologies.
+ *
+ * @module elements/list
+ * @since 0.1.0
+ */
+
+/**
+ * `<dd>` element factory namespace.
+ *
+ * Represents the description/details/value for a term in a description list (`<dl>`).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd
+ */
+export * as dd from './dd';
+
+/**
+ * `<dl>` element factory namespace.
+ *
+ * Represents a description list (name-value groups), containing `<dt>` and `<dd>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
+ */
+export * as dl from './dl';
+
+/**
+ * `<dt>` element factory namespace.
+ *
+ * Represents a term/name in a description list (`<dl>`).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt
+ */
+export * as dt from './dt';
+
+/**
+ * `<li>` element factory namespace.
+ *
+ * Represents a list item inside `<ul>`, `<ol>`, or `<menu>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+ */
+export * as li from './li';
+
+/**
+ * `<ol>` element factory namespace.
+ *
+ * Represents an ordered list where item order is meaningful.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol
+ */
+export * as ol from './ol';
+
+/**
+ * `<ul>` element factory namespace.
+ *
+ * Represents an unordered list where item order is not meaningful.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul
+ */
+export * as ul from './ul';

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

@@ -0,0 +1,213 @@
+/**
+ * pkgn-sol Design Foundation: Li element helpers.
+ *
+ * @remarks
+ * The list item element (`<li>`) represents an item in a list.
+ *
+ * Best-practice guidance:
+ * - Use `<li>` only as a direct child of a list container (`<ul>`, `<ol>`, `<menu>`).
+ * - Prefer semantic list structure over styling hacks.
+ * - For ordered lists, use the `value` attribute/property to control numbering when needed
+ *   (e.g. continuing a sequence after inserted items).
+ * - Avoid the legacy `type` attribute where possible; prefer list-level semantics and CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<li>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - supply typed element-specific fields like `value`
+ *
+ * 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;
+};
+
+/**
+ * Legacy marker type options for list items.
+ *
+ * @remarks
+ * The `type` attribute on `<li>` is legacy and should be avoided when possible.
+ * It is retained here for compatibility scenarios.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+ *
+ * @category Attributes
+ */
+export type LiMarkerType = '1' | 'a' | 'A' | 'i' | 'I';
+
+/**
+ * The semantic tag name for list items.
+ *
+ * @category Constants
+ */
+export const LI_TAG = 'li' as const;
+
+/**
+ * A CSS selector targeting list item elements.
+ *
+ * @category Constants
+ */
+export const LI_SELECTOR = 'li';
+
+/**
+ * Attribute bag for li creation/enhancement.
+ *
+ * @remarks
+ * In addition to global attributes, `<li>` supports:
+ * - `value` (primarily for `<ol>` numbering control)
+ * - legacy `type` marker hint (deprecated)
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
+ *
+ * @category Attributes
+ */
+export type LiAttrs = Omit<GlobalAttrs, 'aria' | 'attrs'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Ordinal value for ordered lists.
+   *
+   * @remarks
+   * When used within an `<ol>`, this sets the list item's numbering value.
+   * This is modeled as a number and applied via the `HTMLLIElement.value` property.
+   */
+  value?: number;
+
+  /**
+   * Legacy marker type hint (deprecated).
+   *
+   * @remarks
+   * Prefer list semantics and CSS. Retained for compatibility.
+   */
+  type?: LiMarkerType;
+
+  /**
+   * 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 LiAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The li attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: LiAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, type, attrs: extraAttrs, value: _value, ...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 extra attrs and map legacy `type` through the hardened attrs path.
+  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 a list item 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.
+ * - The `value` field is applied via the `HTMLLIElement.value` property for correct behavior.
+ *
+ * @param text - Optional text content for the list item.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<li>` element.
+ *
+ * @example
+ * ```ts
+ * import { createLi } from "@lnpg/pkgn-sol/elements/list/li";
+ *
+ * const li = createLi("Item 3", { value: 3 });
+ * ```
+ *
+ * @category DOM
+ */
+export function createLi(text?: string, attrs?: LiAttrs): ElementOf<typeof LI_TAG> {
+  const el = createElement(LI_TAG, toGlobalAttrs(attrs), text);
+
+  // Apply ordered-list numbering via the DOM property.
+  if (attrs && typeof attrs.value === 'number' && Number.isFinite(attrs.value)) {
+    (el as unknown as HTMLLIElement).value = attrs.value;
+  }
+
+  return el;
+}
+
+/**
+ * Enhance list item 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
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceLis(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for li.
+  void root;
+}

package/src/elements/list/li/li.scss

@@ -0,0 +1,39 @@
+/**
+ * pkgn-sol Design Foundation: LI Element
+ *
+ * List item (`li`)
+ *
+ * Structural baseline only.
+ *
+ * This module:
+ * - Normalizes UA spacing without removing markers
+ * - Preserves list semantics (markers are owned by `ol`/`ul`)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<li>` semantics and allowed parents ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/li?utm_source=chatgpt.com))
+ * - MDN Learn: list styling notes (Oct 2025) ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Text_styling/Styling_lists?utm_source=chatgpt.com))
+ * - Reset guidance (Oct 2025): normalize margins/padding ([useaxentix.com](https://useaxentix.com/blog/css/css-reset-complete-guide/?utm_source=chatgpt.com))
+ *
+ * @module
+ * @group  elements.list.li
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(li) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: list-item;
+
+  // Normalize UA spacing differences.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Robust inline content handling.
+  overflow-wrap: break-word;
+  max-width: 100%;
+}

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

@@ -0,0 +1,205 @@
+/**
+ * pkgn-sol Design Foundation: Ordered list element helpers.
+ *
+ * @remarks
+ * The ordered list element (`<ol>`) represents an ordered list of items.
+ *
+ * Best-practice guidance:
+ * - Prefer `<ol>` when the order of items matters (steps, rankings, sequences).
+ * - List items should be `<li>` elements (direct children).
+ * - Avoid presentational attributes when possible; prefer CSS for styling.
+ * - Use `start`/`reversed` only when semantics require non-default numbering.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create ordered lists 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;
+};
+
+/**
+ * The semantic tag name for ordered lists.
+ *
+ * @category Constants
+ */
+export const OL_TAG = 'ol' as const;
+
+/**
+ * A CSS selector targeting ordered list elements.
+ *
+ * @category Constants
+ */
+export const OL_SELECTOR = 'ol';
+
+/**
+ * Allowed values for the `<ol>` `type` attribute.
+ *
+ * @remarks
+ * While `type` is still supported by browsers, it is presentational and CSS is
+ * often preferable.
+ *
+ * - `1`  Decimal numbers (default)
+ * - `a`  Lowercase letters
+ * - `A`  Uppercase letters
+ * - `i`  Lowercase Roman numerals
+ * - `I`  Uppercase Roman numerals
+ *
+ * @category Attributes
+ */
+export type OlType = '1' | 'a' | 'A' | 'i' | 'I';
+
+/**
+ * Attribute bag for ordered list creation/enhancement.
+ *
+ * @remarks
+ * Ordered lists accept HTML global attributes and a small set of specific
+ * attributes:
+ * - `reversed` for descending numbering
+ * - `start` to set the initial counter value
+ * - `type` to choose the marker style (often better via CSS)
+ *
+ * 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 OlAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Whether numbering should be descending.
+   */
+  reversed?: boolean;
+
+  /**
+   * Starting value for the list counter.
+   */
+  start?: number;
+
+  /**
+   * Marker type for list items.
+   */
+  type?: OlType;
+
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link OlAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The ordered list attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: OlAttrs): 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 ordered list element with global and list-specific attributes.
+ *
+ * @remarks
+ * This helper intentionally does not accept raw HTML. Consumers should append
+ * `<li>` children using DOM APIs.
+ *
+ * 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 `<ol>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOl } from "@lnpg/pkgn-sol/elements/list/ol";
+ *
+ * const ol = createOl({ start: 3, reversed: true, className: "steps" });
+ * document.body.appendChild(ol);
+ * ```
+ *
+ * @category DOM
+ */
+export function createOl(attrs?: OlAttrs): ElementOf<typeof OL_TAG> {
+  const el = createElement(OL_TAG, toGlobalAttrs(attrs));
+  const ol = el as unknown as HTMLOListElement;
+
+  if (attrs) {
+    if (typeof attrs.reversed === 'boolean') ol.reversed = attrs.reversed;
+    if (typeof attrs.start === 'number' && Number.isFinite(attrs.start)) ol.start = attrs.start;
+    if (typeof attrs.type === 'string') ol.type = attrs.type;
+  }
+
+  return el;
+}
+
+/**
+ * Enhance ordered list 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 enhanceOls(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for ol.
+  void root;
+}

package/src/elements/list/ol/ol.scss

@@ -0,0 +1,39 @@
+/**
+ * pkgn-sol Design Foundation: OL Element
+ *
+ * Ordered list (`ol`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - Preserve numbering semantics.
+ * - Normalize UA margin/padding variance.
+ * - Avoid decorative styling at baseline.
+ *
+ * References (2025+):
+ * - MDN: `<ol>` element reference (Sep 2025)
+ *
+ * @module
+ * @group  elements.list.ol
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(ol) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA vertical spacing.
+  margin: 0;
+
+  // Normalize indentation consistently.
+  padding-inline-start: 1.5em;
+
+  // Preserve numbering behavior.
+  list-style-position: outside;
+  list-style-type: decimal;
+  box-sizing: border-box;
+}