@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/form/textarea/index.ts

@@ -0,0 +1,351 @@
+/**
+ * pkgn-sol Design Foundation: Textarea element helpers.
+ *
+ * @remarks
+ * The textarea element (`<textarea>`) is a multi-line plain-text form control.
+ *
+ * Best-practice guidance:
+ * - Always provide an accessible name (typically via a `<label>`).
+ * - Prefer `placeholder` as a hint, not as a substitute for a label.
+ * - Use `rows`/`cols` to set a sensible baseline size, then use CSS for layout.
+ * - Use `minLength`/`maxLength` for client-side constraints, but validate on the server.
+ * - Use `wrap="hard"` only when you intentionally want line breaks inserted for
+ *   form submission, and ensure `cols` is set.
+ * - Use `dirname` only when you actually want directionality included in submission.
+ *
+ * Attributes (element-specific):
+ * - `name`, `form`, `disabled`, `required`, `readOnly`
+ * - `cols`, `rows`
+ * - `minLength`, `maxLength`
+ * - `placeholder`
+ * - `autoComplete`, `autoFocus`, `autoCapitalize`
+ * - `dirName`
+ * - `wrap`
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which
+ *   block inline event handler attributes (e.g. `onclick`) and raw `style`
+ *   attribute injection (use the `style` object field instead).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/textarea
+ *
+ * @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 textarea.
+ *
+ * @category Constants
+ */
+export const TEXTAREA_TAG = 'textarea' as const;
+
+/**
+ * A CSS selector targeting textarea elements.
+ *
+ * @category Constants
+ */
+export const TEXTAREA_SELECTOR = 'textarea';
+
+/**
+ * Textarea wrap modes.
+ *
+ * @remarks
+ * - `soft` (default): the submitted value is not forcibly wrapped.
+ * - `hard`: line breaks are inserted for submission based on `cols`.
+ *
+ * @category Types
+ */
+export type TextareaWrap = 'soft' | 'hard';
+
+/**
+ * Autocapitalize values accepted by browsers for form controls.
+ *
+ * @remarks
+ * This is a content attribute commonly supported on form controls.
+ *
+ * @category Types
+ */
+export type AutoCapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+
+/**
+ * Attribute bag for textarea creation/enhancement.
+ *
+ * @remarks
+ * Textareas accept standard HTML global attributes plus textarea-specific content
+ * 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 TextareaAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Name used during form submission.
+   */
+  name?: string;
+
+  /**
+   * Associate the control with a form by ID.
+   */
+  form?: string;
+
+  /**
+   * Whether the textarea is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether the textarea is required.
+   */
+  required?: boolean;
+
+  /**
+   * Whether the textarea is read-only.
+   *
+   * @remarks
+   * Maps to the `readonly` content attribute.
+   */
+  readOnly?: boolean;
+
+  /**
+   * The number of visible text columns.
+   */
+  cols?: number;
+
+  /**
+   * The number of visible text rows.
+   */
+  rows?: number;
+
+  /**
+   * Minimum input length.
+   *
+   * @remarks
+   * Maps to the `minlength` content attribute.
+   */
+  minLength?: number;
+
+  /**
+   * Maximum input length.
+   *
+   * @remarks
+   * Maps to the `maxlength` content attribute.
+   */
+  maxLength?: number;
+
+  /**
+   * Placeholder hint text.
+   */
+  placeholder?: string;
+
+  /**
+   * Autofill hint.
+   */
+  autoComplete?: string;
+
+  /**
+   * Whether the control should be focused on page load.
+   */
+  autoFocus?: boolean;
+
+  /**
+   * Autocapitalization behavior.
+   */
+  autoCapitalize?: AutoCapitalize;
+
+  /**
+   * Submission directionality field name.
+   *
+   * @remarks
+   * When set, the value must not be empty.
+   * Maps to the `dirname` content attribute.
+   */
+  dirName?: string;
+
+  /**
+   * Wrapping mode for form submission.
+   */
+  wrap?: TextareaWrap;
+};
+
+/**
+ * Normalize {@link TextareaAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The textarea attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @throws Error if `dirName` is provided but empty/whitespace.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: TextareaAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const {
+    aria,
+    name,
+    form,
+    disabled,
+    required,
+    readOnly,
+    cols,
+    rows,
+    minLength,
+    maxLength,
+    placeholder,
+    autoComplete,
+    autoFocus,
+    autoCapitalize,
+    dirName,
+    wrap,
+    ...rest
+  } = attrs;
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  const extra: NonNullable<GlobalAttrs['attrs']> = { ...(mapped.attrs ?? {}) };
+
+  if (typeof name === 'string') extra.name = name;
+  if (typeof form === 'string') extra.form = form;
+
+  if (disabled === true) extra.disabled = true;
+  if (required === true) extra.required = true;
+  if (readOnly === true) extra.readonly = true;
+
+  if (typeof cols === 'number' && Number.isFinite(cols)) extra.cols = cols;
+  if (typeof rows === 'number' && Number.isFinite(rows)) extra.rows = rows;
+
+  if (typeof minLength === 'number' && Number.isFinite(minLength)) extra.minlength = minLength;
+  if (typeof maxLength === 'number' && Number.isFinite(maxLength)) extra.maxlength = maxLength;
+
+  if (typeof placeholder === 'string') extra.placeholder = placeholder;
+
+  if (typeof autoComplete === 'string') extra.autocomplete = autoComplete;
+  if (autoFocus === true) extra.autofocus = true;
+  if (typeof autoCapitalize === 'string') extra.autocapitalize = autoCapitalize;
+
+  if (typeof dirName === 'string') {
+    const dn = dirName.trim();
+    if (dn.length === 0) {
+      throw new Error('textarea dirName must not be an empty string.');
+    }
+    extra.dirname = dn;
+  }
+
+  if (wrap === 'soft' || wrap === 'hard') {
+    extra.wrap = wrap;
+
+    // "hard" wrap only has an effect when cols is set, so we enforce a safe default.
+    if (wrap === 'hard' && typeof extra.cols === 'undefined') {
+      extra.cols = 20;
+    }
+  }
+
+  if (Object.keys(extra).length > 0) {
+    mapped.attrs = extra;
+  }
+
+  if (!aria) return mapped;
+
+  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 hasMappedAria = Object.keys(mappedAria).length > 0;
+
+  return hasMappedAria ? { ...mapped, aria: mappedAria } : mapped;
+}
+
+/**
+ * Create a textarea element with optional initial value and attributes.
+ *
+ * @remarks
+ * For `<textarea>`, the initial value is represented by its text content in HTML.
+ * pkgn-sol assigns the provided `text` via `textContent` (never `innerHTML`).
+ *
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes and escape-hatch 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 initial value (assigned as `textContent`).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<textarea>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTextarea } from "@lnpg/pkgn-sol/elements/form/textarea";
+ *
+ * const t = createTextarea("Hello", { rows: 4, cols: 40, name: "message" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createTextarea(
+  text?: string,
+  attrs?: TextareaAttrs,
+): ElementOf<typeof TEXTAREA_TAG> {
+  return createElement(TEXTAREA_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance textarea 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 enhanceTextareas(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for textarea.
+  void root;
+}

package/src/elements/form/textarea/textarea.scss

@@ -0,0 +1,39 @@
+/**
+ * pkgn-sol Design Foundation: Textarea Element
+ *
+ * Multi-line text input (`textarea`)
+ *
+ * Token-driven, light baseline.
+ *
+ * This module:
+ * - Normalizes typography inheritance (most noticeable in textarea)
+ * - Normalizes sizing model and spacing
+ * - Avoids destructive resets that interfere with native editing behavior
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.textarea
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(textarea) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Ensure textarea matches surrounding typography.
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: var(--lg-typography-font-sizes-base-font-size, inherit);
+  font-weight: var(--lg-typography-formatting-base-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  box-sizing: border-box;
+  margin: 0;
+
+  // Maintain predictable alignment in inline/flow contexts.
+  vertical-align: top;
+
+  // Avoid forcing resize behavior at baseline.
+  background-color: transparent;
+}

package/src/elements/heading/h1/h1.scss

@@ -0,0 +1,59 @@
+/**
+ * pkgn-sol Design Foundation: H1 Element
+ *
+ * Section heading (`h1`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA default heading margins (which vary and are actively changing)
+ * - Explicitly defines size/spacing to avoid reliance on browser defaults
+ * - Applies pkgn-sol heading typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: UA `<h1>` defaults are changing; define your own size/margins (Apr 2025)
+ * - MDN: `<h1>-<h6>` are block-level by default
+ * - MDN: `text-wrap` for balanced heading wrapping (Dec 2025)
+ *
+ * @module
+ * @group  elements.heading.h1
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(h1) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Do not rely on UA defaults (they are changing across browsers).
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Robust heading text behavior.
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned heading typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-heading-font-family);
+  font-size: var(--lg-typography-font-sizes-font-size-h1);
+  font-weight: var(--lg-typography-formatting-heading-font-weight);
+  line-height: var(--lg-typography-formatting-heading-line-height);
+  color: var(--lg-theme-base-colours-heading-font-color);
+
+  // Progressive enhancement for nicer headline wrapping.
+  text-wrap: balance;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-end: var(--lg-typography-spacing-heading-margin-bottom);
+}

package/src/elements/heading/h1/index.ts

@@ -0,0 +1,170 @@
+/**
+ * pkgn-sol Design Foundation: H1 element helpers.
+ *
+ * @remarks
+ * The h1 element (`<h1>`) represents the highest-rank section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to convey document structure, not for visual styling.
+ * - Keep heading levels ordered (don't jump from `<h1>` to `<h3>` because you
+ *   like the font size). Use CSS for presentation.
+ * - Prefer clear, succinct headings that describe the section that follows.
+ * - Many accessibility guides recommend a single `<h1>` as the page/document's
+ *   primary heading. HTML allows multiple headings, but consistency matters.
+ * - Don't rely on default browser heading styles; user-agent styles can change.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<h1>` 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.
+ *
+ * References:
+ * - MDN: Heading elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
+ * - MDN: Headings and paragraphs: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs
+ * - W3C WAI: Headings: https://www.w3.org/WAI/tutorials/page-structure/headings/
+ * - WHATWG HTML: Sections / heading content: https://html.spec.whatwg.org/multipage/sections.html
+ *
+ * @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 the primary heading element.
+ *
+ * @category Constants
+ */
+export const H1_TAG = 'h1' as const;
+
+/**
+ * A CSS selector targeting h1 elements.
+ *
+ * @category Constants
+ */
+export const H1_SELECTOR = 'h1';
+
+/**
+ * Attribute bag for h1 creation/enhancement.
+ *
+ * @remarks
+ * H1 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 H1Attrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link H1Attrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The h1 attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: H1Attrs): 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 h1 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 heading.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<h1>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH1 } from "@lnpg/pkgn-sol/elements/heading/h1";
+ *
+ * document.body.prepend(createH1("Page title", { id: "title" }));
+ * ```
+ *
+ * @category DOM
+ */
+export function createH1(text?: string, attrs?: H1Attrs): ElementOf<typeof H1_TAG> {
+  return createElement(H1_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance h1 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 enhanceH1s(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for h1.
+  void root;
+}

package/src/elements/heading/h2/h2.scss

@@ -0,0 +1,53 @@
+/**
+ * pkgn-sol Design Foundation: H2 Element
+ *
+ * Section heading (`h2`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA default heading margins for consistent layout
+ * - Explicitly defines size/spacing to avoid UA variability
+ * - Applies pkgn-sol heading typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<h1>-<h6>` semantics and default block layout
+ * - Modern reset guidance: normalize heading margins and sizes (Oct 2025)
+ * - MDN: `text-wrap` balanced heading wrapping (Dec 2025)
+ *
+ * @module
+ * @group  elements.heading.h2
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(h2) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned heading typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-heading-font-family);
+  font-size: var(--lg-typography-font-sizes-font-size-h2);
+  font-weight: var(--lg-typography-formatting-heading-font-weight);
+  line-height: var(--lg-typography-formatting-heading-line-height);
+  color: var(--lg-theme-base-colours-heading-font-color);
+  text-wrap: balance;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-end: var(--lg-typography-spacing-heading-margin-bottom);
+}