@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,194 @@
+/**
+ * pkgn-sol Design Foundation: Label element helpers.
+ *
+ * @remarks
+ * The label element (`<label>`) represents a caption in a user interface and is
+ * primarily used to provide an accessible name for a form control.
+ *
+ * Best-practice guidance:
+ * - Always associate labels with their control:
+ *   - Prefer an explicit association using `for` (pkgn-sol: {@link LabelAttrs.htmlFor})
+ *     that matches the control's `id`.
+ *   - Alternatively, wrap the control inside the `<label>` element.
+ * - Do not rely on placeholder text as a replacement for a visible label.
+ * - Keep label text concise and descriptive.
+ *
+ * Attributes:
+ * - `<label>` supports global attributes.
+ * - The only relevant label-specific content attribute is `for`, reflected in
+ *   JavaScript as `htmlFor`. (The `label` element does not have a `form` content
+ *   attribute; it has a `form` *IDL attribute* derived from the associated control.)
+ *
+ * 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/label
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for
+ *
+ * @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 label.
+ *
+ * @category Constants
+ */
+export const LABEL_TAG = 'label' as const;
+
+/**
+ * A CSS selector targeting label elements.
+ *
+ * @category Constants
+ */
+export const LABEL_SELECTOR = 'label';
+
+/**
+ * Attribute bag for label creation/enhancement.
+ *
+ * @remarks
+ * Labels accept standard HTML global attributes.
+ *
+ * Label-specific:
+ * - {@link LabelAttrs.htmlFor} maps to the `for` attribute, associating the label
+ *   with the control whose `id` matches.
+ *
+ * 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 LabelAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Associate the label with a labelable form control by ID.
+   *
+   * @remarks
+   * This maps to the `for` content attribute.
+   *
+   * The value should match the `id` of a labelable element in the same document
+   * tree (e.g. `<input id="email">` pairs with `<label for="email">`).
+   */
+  htmlFor?: string;
+};
+
+/**
+ * Normalize {@link LabelAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The label attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: LabelAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, htmlFor, ...rest } = attrs;
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  if (typeof htmlFor === 'string' && htmlFor.length > 0) {
+    mapped.attrs = {
+      ...(mapped.attrs ?? {}),
+      for: htmlFor,
+    };
+  }
+
+  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;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMappedAria = Object.keys(mappedAria).length > 0;
+
+  return hasMappedAria ? { ...mapped, aria: mappedAria } : mapped;
+}
+
+/**
+ * Create a label 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.
+ *
+ * @param text - Optional text content for the label.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<label>` element.
+ *
+ * @example
+ * ```ts
+ * import { createLabel } from "@lnpg/pkgn-sol/elements/form/label";
+ *
+ * const label = createLabel("Email address", { htmlFor: "email" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createLabel(text?: string, attrs?: LabelAttrs): ElementOf<typeof LABEL_TAG> {
+  return createElement(LABEL_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance label 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 enhanceLabels(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for label.
+  void root;
+}

package/src/elements/form/label/label.scss

@@ -0,0 +1,41 @@
+/**
+ * pkgn-sol Design Foundation: Label Element
+ *
+ * Label (`label`)
+ *
+ * Baseline reset + light usability normalization.
+ *
+ * This module:
+ * - Keeps label inline by default (matches typical UA behavior)
+ * - Normalizes spacing
+ * - Uses pointer cursor to reflect interactive association with form controls
+ * - Preserves inherited typography (labels should match surrounding content)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.label
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(label) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Labels are interactive when associated with a control.
+  cursor: pointer;
+
+  // Preserve inherited typography.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,166 @@
+/**
+ * pkgn-sol Design Foundation: Legend element helpers.
+ *
+ * @remarks
+ * The legend element (`<legend>`) represents a caption for the content of its
+ * parent `<fieldset>`. It is commonly used to label groups of related form
+ * controls (e.g. radio-button groups), improving clarity and accessibility.
+ *
+ * Best-practice guidance:
+ * - Use `<legend>` as the first child of a `<fieldset>` to label the group.
+ * - Keep legend text concise and meaningful (it is typically announced with
+ *   grouped controls by assistive technologies).
+ * - Avoid using `<legend>` purely for layout; use CSS for styling/spacing.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<legend>` 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.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend
+ * @see https://www.w3.org/WAI/tutorials/forms/grouping/
+ *
+ * @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 legend.
+ *
+ * @category Constants
+ */
+export const LEGEND_TAG = 'legend' as const;
+
+/**
+ * A CSS selector targeting legend elements.
+ *
+ * @category Constants
+ */
+export const LEGEND_SELECTOR = 'legend';
+
+/**
+ * Attribute bag for legend creation/enhancement.
+ *
+ * @remarks
+ * Legend 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 LegendAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link LegendAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The legend attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: LegendAttrs): 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 legend 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 legend.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<legend>` element.
+ *
+ * @example
+ * ```ts
+ * import { createLegend } from "@lnpg/pkgn-sol/elements/form/legend";
+ *
+ * const legend = createLegend("Delivery address");
+ * ```
+ *
+ * @category DOM
+ */
+export function createLegend(text?: string, attrs?: LegendAttrs): ElementOf<typeof LEGEND_TAG> {
+  return createElement(LEGEND_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance legend 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 enhanceLegends(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for legend.
+  void root;
+}

package/src/elements/form/legend/legend.scss

@@ -0,0 +1,40 @@
+/**
+ * pkgn-sol Design Foundation: Legend Element
+ *
+ * Fieldset caption (`legend`)
+ *
+ * Token-driven, light baseline.
+ *
+ * This module:
+ * - Normalizes UA spacing quirks without breaking legend/fieldset behavior
+ * - Preserves semantics (caption for the group)
+ * - Applies a subtle heading-like weight via tokens (but no decorative styling)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.legend
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(legend) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve intrinsic legend behavior (do not force display).
+  margin: 0;
+  padding: 0;
+  border: 0;
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  // Typography: keep consistent with system and slightly emphasized.
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: var(--lg-typography-font-weights-semibold-font-weight, inherit);
+  line-height: inherit;
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  background-color: transparent;
+}

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

@@ -0,0 +1,231 @@
+/**
+ * pkgn-sol Design Foundation: Meter element helpers.
+ *
+ * @remarks
+ * The meter element (`<meter>`) represents a scalar measurement within a known range,
+ * or a fractional value.
+ *
+ * Best-practice guidance:
+ * - Use `<meter>` for a known-range measurement (e.g. disk usage, score, relevance).
+ * - Do NOT use `<meter>` for task progress. Use `<progress>` for progress indication.
+ * - Provide fallback text content for user agents that don't render `<meter>`.
+ * - Define `min`/`max` if your `value` is not in the default 0..1 range.
+ * - Use `low`/`high`/`optimum` only when you actually want "good/bad" semantics.
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<meter>` element
+ * - WHATWG HTML: meter attributes and behavior
+ *
+ * @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;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for meter.
+ *
+ * @category Constants
+ */
+export const METER_TAG = 'meter' as const;
+
+/**
+ * A CSS selector targeting meter elements.
+ *
+ * @category Constants
+ */
+export const METER_SELECTOR = 'meter';
+
+/**
+ * Attribute bag for meter creation/enhancement.
+ *
+ * @remarks
+ * Supported element-specific attributes:
+ * - `value`, `min`, `max`, `low`, `high`, `optimum`
+ * - `form` (associates the meter with a form owner by ID)
+ *
+ * Defaults (documented platform behavior):
+ * - `min` defaults to `0` when omitted
+ * - `max` defaults to `1` when omitted
+ * - `value` defaults to `0` when omitted or malformed
+ *
+ * pkgn-sol applies these defaults as explicit attributes to keep output predictable
+ * and testable even in node-based DOM shims.
+ *
+ * @category Attributes
+ */
+export type MeterAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Current numeric value.
+   *
+   * @remarks
+   * Should be within `[min, max]` when those are defined.
+   */
+  value?: number;
+
+  /**
+   * Lower numeric bound of the range. Defaults to `0`.
+   */
+  min?: number;
+
+  /**
+   * Upper numeric bound of the range. Defaults to `1`.
+   */
+  max?: number;
+
+  /**
+   * Upper numeric bound of the low end of the range.
+   */
+  low?: number;
+
+  /**
+   * Lower numeric bound of the high end of the range.
+   */
+  high?: number;
+
+  /**
+   * The optimal value within the range.
+   */
+  optimum?: number;
+
+  /**
+   * Associates the meter with a form element by ID.
+   *
+   * @remarks
+   * Mirrors the HTML `form` attribute used by form-associated elements.
+   */
+  form?: string;
+
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link MeterAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @remarks
+ * - Preserves caller-provided `attrs` escape hatch (still validated by `dom.ts`).
+ * - Element-specific attributes are merged into `attrs` without overwriting keys
+ *   explicitly provided by the caller.
+ * - Applies predictable defaults for `min`, `max`, and `value` even if callers
+ *   omit the `attrs` bag entirely.
+ *
+ * @param attrs - The meter attributes.
+ * @returns A {@link GlobalAttrs} object.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: MeterAttrs): GlobalAttrs {
+  const a: MeterAttrs = attrs ?? {};
+
+  const { aria, value, min, max, low, high, optimum, form, ...rest } = a;
+
+  // Start with any caller-provided attrs escape hatch (it is still validated by dom.ts).
+  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };
+
+  // Helper: only set if caller didn't already set the raw attribute explicitly.
+  const setIfUnset = (key: string, v: AttrValue | undefined): void => {
+    if (v === undefined) return;
+    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;
+    mergedAttrs[key] = v;
+  };
+
+  // Defaults: make output deterministic even when attrs is omitted.
+  setIfUnset('min', typeof min === 'number' ? min : 0);
+  setIfUnset('max', typeof max === 'number' ? max : 1);
+  setIfUnset('value', typeof value === 'number' ? value : 0);
+
+  // Optional meter semantics.
+  setIfUnset('low', typeof low === 'number' ? low : undefined);
+  setIfUnset('high', typeof high === 'number' ? high : undefined);
+  setIfUnset('optimum', typeof optimum === 'number' ? optimum : undefined);
+
+  // Form association.
+  setIfUnset('form', typeof form === 'string' ? form : undefined);
+
+  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.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+  }
+
+  const next: GlobalAttrs = { ...rest, attrs: mergedAttrs };
+
+  if (Object.keys(mappedAria).length > 0) {
+    next.aria = mappedAria;
+  }
+
+  return next;
+}
+
+/**
+ * Create a meter element with optional fallback text and attributes.
+ *
+ * @remarks
+ * - Fallback text 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 fallback text for user agents that don't render `<meter>`.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<meter>` element.
+ *
+ * @category DOM
+ */
+export function createMeter(text?: string, attrs?: MeterAttrs): ElementOf<typeof METER_TAG> {
+  return createElement(METER_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance meter 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 enhanceMeters(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for meter.
+  void root;
+}

package/src/elements/form/meter/meter.scss

@@ -0,0 +1,36 @@
+/**
+ * pkgn-sol Design Foundation: Meter Element
+ *
+ * Scalar gauge (`meter`)
+ *
+ * Token-driven, light baseline.
+ *
+ * This module:
+ * - Normalizes typography inheritance (avoid OS/UA font mismatch)
+ * - Normalizes sizing model and incidental spacing
+ * - Avoids destructive resets that break native meter rendering
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.meter
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(meter) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve native rendering (UA-controlled), but normalize 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;
+  max-width: 100%;
+  vertical-align: baseline;
+  background-color: transparent;
+}