@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/break/br/br.scss

@@ -0,0 +1,26 @@
+/**
+ * pkgn-sol Design Foundation: BR Element
+ *
+ * Line break (`br`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Ensures consistent structural behavior for `<br>` across modern browsers
+ * - Applies no visual styling (line breaks are structural, not presentational)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.breaks.br
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(br) {
+  /* --------------------------------------------------------------------------
+   - Structural baseline
+   -------------------------------------------------------------------------- */
+
+  display: inline; // default behaviour
+  content: ''; // explicit structural content
+}

package/src/elements/break/br/index.ts

@@ -0,0 +1,150 @@
+/**
+ * pkgn-sol Design Foundation: Br element helpers.
+ *
+ * @remarks
+ * The br element (`<br>`) represents a line break within phrasing content.
+ *
+ * Best-practice guidance:
+ * - Use `<br>` only for line breaks within text (e.g. poems, addresses).
+ * - Do not use `<br>` for layout or spacing. Use CSS instead.
+ * - `<br>` is a void element and must not contain text content.
+ *
+ * This module provides a small, framework-agnostic helper so consumers can:
+ * - create line breaks safely in vanilla JS/TS
+ * - apply consistent global attributes via pkgn-sol's hardened DOM helpers
+ * - rely on a stable enhancement hook for future evolution
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createVoidElement, 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 labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for line break elements.
+ *
+ * @category Constants
+ */
+export const BR_TAG = 'br' as const;
+
+/**
+ * A CSS selector targeting br elements.
+ *
+ * @category Constants
+ */
+export const BR_SELECTOR = 'br';
+
+/**
+ * Attribute bag for br creation/enhancement.
+ *
+ * @remarks
+ * `<br>` accepts only global HTML attributes.
+ * It does not accept text content and has no element-specific attributes.
+ *
+ * @category Attributes
+ */
+export type BrAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link BrAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The br attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: BrAttrs): 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 a br element with optional global attributes.
+ *
+ * @remarks
+ * - `<br>` is a void element and does not accept text content.
+ * - 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 `<br>` element.
+ *
+ * @example
+ * ```ts
+ * import { createBr } from "@lnpg/pkgn-sol/elements/break/br";
+ *
+ * paragraph.appendChild(createBr());
+ * ```
+ *
+ * @category DOM
+ */
+export function createBr(attrs?: BrAttrs): ElementOf<typeof BR_TAG> {
+  return createVoidElement(BR_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance br elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * It exists to establish a stable enhancement pattern across all elements.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceBrs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for br.
+  void root;
+}

package/src/elements/break/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Line and word break element factories.
+ *
+ * Provides framework-agnostic factory functions for elements that control
+ * line breaking and word breaking behaviour within text flow.
+ *
+ * These factories:
+ * - Create semantic HTML break elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured ARIA input where applicable.
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/break
+ * @since 0.1.0
+ */
+
+/**
+ * `<br>` element factory namespace.
+ *
+ * Represents a line break opportunity within text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/br
+ */
+export * as br from './br';
+
+/**
+ * `<wbr>` element factory namespace.
+ *
+ * Represents a word break opportunity within text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr
+ */
+export * as wbr from './wbr';

package/src/elements/break/wbr/index.ts

@@ -0,0 +1,151 @@
+/**
+ * pkgn-sol Design Foundation: Wbr element helpers.
+ *
+ * @remarks
+ * The wbr element (`<wbr>`) represents a word break opportunity.
+ *
+ * Best-practice guidance:
+ * - Use `<wbr>` to suggest optional break points within long words or URLs.
+ * - It does not force a line break; the browser decides if a break is needed.
+ * - Do not use `<wbr>` for layout or spacing. Use CSS instead.
+ * - `<wbr>` is a void element and must not contain text content.
+ *
+ * This module provides a small, framework-agnostic helper so consumers can:
+ * - create word break opportunities safely in vanilla JS/TS
+ * - apply consistent global attributes via pkgn-sol's hardened DOM helpers
+ * - rely on a stable enhancement hook for future evolution
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createVoidElement, 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 labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for word break opportunity elements.
+ *
+ * @category Constants
+ */
+export const WBR_TAG = 'wbr' as const;
+
+/**
+ * A CSS selector targeting wbr elements.
+ *
+ * @category Constants
+ */
+export const WBR_SELECTOR = 'wbr';
+
+/**
+ * Attribute bag for wbr creation/enhancement.
+ *
+ * @remarks
+ * `<wbr>` accepts only global HTML attributes.
+ * It does not accept text content and has no element-specific attributes.
+ *
+ * @category Attributes
+ */
+export type WbrAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link WbrAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The wbr attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: WbrAttrs): 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 a wbr element with optional global attributes.
+ *
+ * @remarks
+ * - `<wbr>` is a void element and does not accept text content.
+ * - 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 `<wbr>` element.
+ *
+ * @example
+ * ```ts
+ * import { createWbr } from "@lnpg/pkgn-sol/elements/break/wbr";
+ *
+ * paragraph.appendChild(createWbr());
+ * ```
+ *
+ * @category DOM
+ */
+export function createWbr(attrs?: WbrAttrs): ElementOf<typeof WBR_TAG> {
+  return createVoidElement(WBR_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance wbr elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * It exists to establish a stable enhancement pattern across all elements.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceWbrs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for wbr.
+  void root;
+}

package/src/elements/break/wbr/wbr.scss

@@ -0,0 +1,27 @@
+/**
+ * pkgn-sol Design Foundation: WBR Element
+ *
+ * Word Break Opportunity (`wbr`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Preserves structural inline behavior
+ * - Applies no visual styling
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.breaks.wbr
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(wbr) {
+  /* --------------------------------------------------------------------------
+   - Structural baseline
+   -------------------------------------------------------------------------- */
+
+  // `<wbr>` is inline by default and introduces an optional line break.
+  // No visual styling should be applied.
+  display: inline;
+}

package/src/elements/container/div/div.scss

@@ -0,0 +1,27 @@
+/**
+ * pkgn-sol Design Foundation: Div Element
+ *
+ * Generic container (`div`)
+ *
+ * Baseline hygiene only.
+ *
+ * Notes:
+ * - `<div>` has no meaningful UA styling beyond its default `display` behavior.
+ * - Modern reset guidance (2025+) favors *not* force-resetting elements that
+ *   already render consistently across engines, to avoid accidental layout bugs.
+ *
+ * @module
+ * @group  elements.container.div
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(div) {
+  /* --------------------------------------------------------------------------
+   - Baseline
+   -------------------------------------------------------------------------- */
+
+  // `<div>` is block-level by default in UA rendering. We declare it explicitly
+  // for clarity and predictability when this element stylesheet is consumed alone.
+  display: block;
+}

package/src/elements/container/div/index.ts

@@ -0,0 +1,163 @@
+/**
+ * pkgn-sol Design Foundation: Div element helpers.
+ *
+ * @remarks
+ * The div element (`<div>`) is a non-semantic, generic container.
+ *
+ * Best-practice guidance:
+ * - Prefer semantic elements when available (e.g. `<section>`, `<nav>`, `<article>`).
+ * - Use `<div>` as a last resort when no semantic element fits.
+ * - Avoid obsolete attributes like `align`; use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create div containers 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 div containers.
+ *
+ * @category Constants
+ */
+export const DIV_TAG = 'div' as const;
+
+/**
+ * A CSS selector targeting div elements.
+ *
+ * @category Constants
+ */
+export const DIV_SELECTOR = 'div';
+
+/**
+ * Attribute bag for div creation/enhancement.
+ *
+ * @remarks
+ * Div 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 DivAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DivAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The div attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DivAttrs): 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 div 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 div.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<div>` element.
+ *
+ * @example
+ * Create and append a div:
+ * ```ts
+ * import { createDiv } from "@lnpg/pkgn-sol/elements/container/div";
+ *
+ * document.body.appendChild(
+ *   createDiv("Hello.", { className: "box", id: "root" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createDiv(text?: string, attrs?: DivAttrs): ElementOf<typeof DIV_TAG> {
+  return createElement(DIV_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance div 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 enhanceDivs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for div.
+  void root;
+}

package/src/elements/container/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Container element factories.
+ *
+ * Provides framework-agnostic factory functions for generic container
+ * elements used to group flow or inline content.
+ *
+ * These factories:
+ * - Create semantic HTML elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured ARIA input.
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/container
+ * @since 0.1.0
+ */
+
+/**
+ * `<div>` element factory namespace.
+ *
+ * Represents a generic block-level container with no semantic meaning.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div
+ */
+export * as div from './div';
+
+/**
+ * `<span>` element factory namespace.
+ *
+ * Represents a generic inline container with no semantic meaning.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+ */
+export * as span from './span';