@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,187 @@
+/**
+ * pkgn-sol Design Foundation: Optgroup element helpers.
+ *
+ * @remarks
+ * The optgroup element (`<optgroup>`) groups related `<option>` elements within
+ * a `<select>`, allowing user agents to present grouped choices with a label.
+ * :contentReference[oaicite:3]{index=3}
+ *
+ * Best-practice guidance:
+ * - Always provide a meaningful `label`. MDN notes this attribute is mandatory
+ *   when the element is used. pkgn-sol enforces this by requiring `label` when
+ *   creating an optgroup. :contentReference[oaicite:4]{index=4}
+ * - Use `disabled` to disable all options within the group when appropriate.
+ * :contentReference[oaicite:5]{index=5}
+ * - Prefer native semantics; avoid ARIA where native semantics already apply.
+ *
+ * pkgn-sol-specific conventions:
+ * - Requires `label` at creation time to avoid invalid/anonymous optgroups.
+ * - Applies global attributes via pkgn-sol's hardened DOM helpers (`dom.ts`), which
+ *   block inline event handler attributes (e.g. `onclick`) and the raw `style`
+ *   attribute string.
+ * - Supports a small structured ARIA input to reduce typo-based ARIA bugs.
+ *
+ * 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 mapped into {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+  /**
+   * Accessible label, mapped to `aria-label`.
+   */
+  label?: string;
+
+  /**
+   * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for option groups.
+ *
+ * @category Constants
+ */
+export const OPTGROUP_TAG = 'optgroup' as const;
+
+/**
+ * A CSS selector targeting optgroup elements.
+ *
+ * @category Constants
+ */
+export const OPTGROUP_SELECTOR = 'optgroup';
+
+/**
+ * Attribute bag for optgroup creation/enhancement.
+ *
+ * @remarks
+ * `<optgroup>` accepts global attributes plus:
+ * - `disabled` (boolean attribute)
+ *
+ * The `label` attribute is mandatory for meaningful use. pkgn-sol requires the label
+ * as a separate argument in {@link createOptgroup}. :contentReference[oaicite:6]{index=6}
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type OptgroupAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Disables the option group when true.
+   *
+   * @remarks
+   * When disabled, none of the options in the group are selectable. :contentReference[oaicite:7]{index=7}
+   */
+  disabled?: boolean;
+};
+
+/**
+ * Normalize {@link OptgroupAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param label - The required optgroup label, mapped to the `label` attribute.
+ * @param attrs - The optgroup attributes.
+ * @returns A {@link GlobalAttrs} object containing mapped attributes.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(label: string, attrs?: OptgroupAttrs): GlobalAttrs {
+  const { aria, disabled, ...rest } = attrs ?? {};
+
+  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 mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(rest.attrs ?? {}) };
+
+  // Always set the mandatory label attribute unless explicitly overridden via raw attrs.
+  if (!Object.prototype.hasOwnProperty.call(mergedAttrs, 'label')) {
+    mergedAttrs.label = label;
+  }
+
+  // Boolean attribute by presence when true.
+  if (disabled === true && !Object.prototype.hasOwnProperty.call(mergedAttrs, 'disabled')) {
+    mergedAttrs.disabled = '';
+  }
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  if (Object.keys(mergedAttrs).length > 0) mapped.attrs = mergedAttrs;
+
+  if (Object.keys(mappedAria).length > 0) {
+    mapped.aria = mappedAria;
+  }
+
+  return mapped;
+}
+
+/**
+ * Create an optgroup element with a required label and optional attributes.
+ *
+ * @remarks
+ * - The label is mapped to the `label` attribute (required for meaningful use). :contentReference[oaicite:8]{index=8}
+ * - 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 label - The optgroup label shown by the user agent.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<optgroup>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOptgroup } from "@lnpg/pkgn-sol/elements/form/optgroup";
+ *
+ * const g = createOptgroup("Fruits", { disabled: false });
+ * ```
+ *
+ * @category DOM
+ */
+export function createOptgroup(
+  label: string,
+  attrs?: OptgroupAttrs,
+): ElementOf<typeof OPTGROUP_TAG> {
+  return createElement(OPTGROUP_TAG, toGlobalAttrs(label, attrs));
+}
+
+/**
+ * Enhance optgroup 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 enhanceOptgroups(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for optgroup.
+  void root;
+}

package/src/elements/form/optgroup/optgroup.scss

@@ -0,0 +1,37 @@
+/**
+ * pkgn-sol Design Foundation: Optgroup Element
+ *
+ * Option group (`optgroup`)
+ *
+ * Token-driven, light baseline.
+ *
+ * Notes:
+ * - `<optgroup>` groups `<option>`s inside `<select>`.
+ * - Rendering is heavily UA-controlled; avoid destructive resets.
+ * - Normalize typography to match system tokens (where the UA allows it).
+ *
+ * References (2025+):
+ * - MDN: `<optgroup>` element reference (2025)
+ *
+ * @module
+ * @group  elements.form.optgroup
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(optgroup) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve UA control rendering; normalize typography where possible.
+  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-font-weights-semibold-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background-color: transparent;
+}

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

@@ -0,0 +1,218 @@
+/**
+ * pkgn-sol Design Foundation: Option element helpers.
+ *
+ * @remarks
+ * The option element (`<option>`) defines an item within a `<select>`, `<optgroup>`,
+ * or `<datalist>` element.
+ *
+ * Best-practice guidance:
+ * - Prefer providing a `value` for form submission semantics. If `value` is omitted,
+ *   the option's value typically falls back to its text content.
+ * - Use `label` when you need a shorter label for UI display or accessibility hints,
+ *   but keep the option text clear and readable.
+ * - Use `disabled` to prevent selection of an option (or to mark placeholders as
+ *   unavailable).
+ * - Use `selected` to mark the default selection in a `<select>` (usually one
+ *   option should be selected by default).
+ *
+ * Attributes:
+ * - `value` (string): the value submitted/used when selected.
+ * - `label` (string): a label for the option.
+ * - `disabled` (boolean): whether the option is unavailable.
+ * - `selected` (boolean): whether the option is selected by default.
+ *
+ * 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/option
+ *
+ * @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 option.
+ *
+ * @category Constants
+ */
+export const OPTION_TAG = 'option' as const;
+
+/**
+ * A CSS selector targeting option elements.
+ *
+ * @category Constants
+ */
+export const OPTION_SELECTOR = 'option';
+
+/**
+ * Attribute bag for option creation/enhancement.
+ *
+ * @remarks
+ * Options accept standard HTML global attributes plus a small set of option-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 OptionAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * The option value.
+   *
+   * @remarks
+   * If omitted, user agents commonly derive a value from the option's text.
+   */
+  value?: string;
+
+  /**
+   * A label for the option.
+   *
+   * @remarks
+   * When present, this may be used by user agents as the option's label instead
+   * of the text content in certain contexts.
+   */
+  label?: string;
+
+  /**
+   * Whether the option is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether the option is selected by default.
+   *
+   * @remarks
+   * For `<select>`, `selected` commonly indicates the default selected option on
+   * initial load. If multiple options are marked selected, browser behavior varies;
+   * prefer a single default selection unless using a multi-select.
+   */
+  selected?: boolean;
+};
+
+/**
+ * Normalize {@link OptionAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The option attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: OptionAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, value, label, disabled, selected, ...rest } = attrs;
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  const extra: NonNullable<GlobalAttrs['attrs']> = { ...(mapped.attrs ?? {}) };
+
+  if (typeof value === 'string') extra.value = value;
+  if (typeof label === 'string') extra.label = label;
+
+  if (disabled === true) extra.disabled = true;
+  if (selected === true) extra.selected = true;
+
+  // Only attach `attrs` if something was actually defined/added.
+  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 an option element with optional text content and attributes.
+ *
+ * @remarks
+ * - 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 text content for the option.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<option>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOption } from "@lnpg/pkgn-sol/elements/form/option";
+ *
+ * const opt = createOption("United Kingdom", { value: "UK" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createOption(text?: string, attrs?: OptionAttrs): ElementOf<typeof OPTION_TAG> {
+  return createElement(OPTION_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance option 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 enhanceOptions(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for option.
+  void root;
+}

package/src/elements/form/option/option.scss

@@ -0,0 +1,38 @@
+/**
+ * pkgn-sol Design Foundation: Option Element
+ *
+ * Select option (`option`)
+ *
+ * Token-driven, light baseline.
+ *
+ * Notes:
+ * - `<option>` is rendered inside UA form controls; styling support varies widely.
+ * - Avoid destructive resets; normalize typography to system tokens where allowed.
+ *
+ * References (2025+):
+ * - MDN: `<option>` element reference (2025)
+ *
+ * @module
+ * @group  elements.form.option
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(option) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve UA control rendering; normalize typography where possible.
+  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);
+
+  // Defensive normalization (often ignored by UA, but harmless).
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background-color: transparent;
+}

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

@@ -0,0 +1,205 @@
+/**
+ * pkgn-sol Design Foundation: Output element helpers.
+ *
+ * @remarks
+ * The output element (`<output>`) represents the result of a calculation or a
+ * user action, commonly used in forms to display derived values without
+ * requiring focus changes.
+ *
+ * Best-practice guidance:
+ * - Use `<output>` for computed results derived from form controls.
+ * - Use the `for` attribute to associate the output with the control(s) whose
+ *   values it reflects (space-separated list of element IDs).
+ * - Prefer semantic HTML and native behavior over ARIA. Many browsers treat
+ *   `<output>` as an ARIA live region, so updating its text may be announced by
+ *   assistive technologies without moving focus.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create outputs 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/output
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/form
+ *
+ * @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 output.
+ *
+ * @category Constants
+ */
+export const OUTPUT_TAG = 'output' as const;
+
+/**
+ * A CSS selector targeting output elements.
+ *
+ * @category Constants
+ */
+export const OUTPUT_SELECTOR = 'output';
+
+/**
+ * Attribute bag for output creation/enhancement.
+ *
+ * @remarks
+ * Output accepts standard HTML global attributes plus output-specific
+ * attributes (`for`, `form`, `name`).
+ *
+ * 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 OutputAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Space-separated list of element IDs whose values contributed to the output.
+   *
+   * @remarks
+   * This maps to the `for` attribute (yes, the HTML attribute is literally
+   * called `for`).
+   */
+  for?: string;
+
+  /**
+   * Associates the output with a form element by ID, even if not a descendant.
+   */
+  form?: string;
+
+  /**
+   * Name of the output (useful in form-associated contexts).
+   */
+  name?: string;
+};
+
+/**
+ * Normalize {@link OutputAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The output attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: OutputAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, for: htmlFor, form, name, ...rest } = attrs;
+
+  // Start with any caller-provided attrs escape hatch (still validated by dom.ts).
+  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };
+
+  const setIfUnset = (key: string, value: AttrValue | undefined): void => {
+    if (value === undefined) return;
+    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;
+    mergedAttrs[key] = value;
+  };
+
+  setIfUnset('for', htmlFor);
+  setIfUnset('form', form);
+  setIfUnset('name', name);
+
+  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 hasMergedAttrs = Object.keys(mergedAttrs).length > 0;
+  const hasMappedAria = Object.keys(mappedAria).length > 0;
+
+  const next: GlobalAttrs = { ...rest };
+  if (hasMergedAttrs) next.attrs = mergedAttrs;
+  if (hasMappedAria) next.aria = mappedAria;
+
+  return next;
+}
+
+/**
+ * Create an output 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 output.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<output>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOutput } from "@lnpg/pkgn-sol/elements/form/output";
+ *
+ * const out = createOutput("0", { name: "result", for: "a b" });
+ * ```
+ *
+ * @category DOM
+ */
+export function createOutput(text?: string, attrs?: OutputAttrs): ElementOf<typeof OUTPUT_TAG> {
+  return createElement(OUTPUT_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance output 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 enhanceOutputs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for output.
+  void root;
+}