@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,211 @@
+/**
+ * pkgn-sol Design Foundation: Fieldset element helpers.
+ *
+ * @remarks
+ * The fieldset element (`<fieldset>`) groups related form controls, typically
+ * with a `<legend>` that provides an accessible label for the group.
+ *
+ * Best-practice guidance:
+ * - Use `<fieldset>` to group related controls (e.g. radio button sets).
+ * - Prefer a meaningful `<legend>` as the first child to label the group.
+ * - Do not use `<fieldset>` purely for layout; use CSS for visual grouping.
+ *
+ * Attribute behavior notes:
+ * - When `disabled` is set on a `<fieldset>`, user agents disable descendant
+ *   form controls, except those that are descendants of the fieldset's first
+ *   `<legend>` child (if any). This is native platform behavior.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create fieldsets 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/fieldset
+ * @see https://www.w3.org/WAI/tutorials/forms/grouping/
+ *
+ * @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 fieldset groups.
+ *
+ * @category Constants
+ */
+export const FIELDSET_TAG = 'fieldset' as const;
+
+/**
+ * A CSS selector targeting fieldset elements.
+ *
+ * @category Constants
+ */
+export const FIELDSET_SELECTOR = 'fieldset';
+
+/**
+ * Attribute bag for fieldset creation/enhancement.
+ *
+ * @remarks
+ * Fieldset accepts standard HTML global attributes plus fieldset-specific
+ * attributes (`disabled`, `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 FieldsetAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Disables descendant form controls (native platform behavior).
+   *
+   * @remarks
+   * When set, controls inside the first `<legend>` (if present) are typically
+   * excluded from disabling per spec/user agent behavior.
+   */
+  disabled?: boolean;
+
+  /**
+   * Associates the fieldset with a form element by ID, even if not a descendant.
+   */
+  form?: string;
+
+  /**
+   * Name of the fieldset (submitted/associated in form processing contexts).
+   */
+  name?: string;
+};
+
+/**
+ * Normalize {@link FieldsetAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The fieldset attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: FieldsetAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, disabled, 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('form', form);
+  setIfUnset('name', name);
+
+  // Boolean attributes are represented by presence. We set empty-string when true.
+  if (disabled === true) setIfUnset('disabled', '');
+
+  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 hasMappedAria = Object.keys(mappedAria).length > 0;
+  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;
+
+  const next: GlobalAttrs = { ...rest };
+  if (hasMergedAttrs) next.attrs = mergedAttrs;
+  if (hasMappedAria) next.aria = mappedAria;
+
+  return next;
+}
+
+/**
+ * Create a fieldset 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 fieldset (rare; most fieldsets contain child nodes).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<fieldset>` element.
+ *
+ * @example
+ * ```ts
+ * import { createFieldset } from "@lnpg/pkgn-sol/elements/form/fieldset";
+ *
+ * const fs = createFieldset(undefined, { disabled: false });
+ * // fs.appendChild(createLegend("Shipping address"));
+ * ```
+ *
+ * @category DOM
+ */
+export function createFieldset(
+  text?: string,
+  attrs?: FieldsetAttrs,
+): ElementOf<typeof FIELDSET_TAG> {
+  return createElement(FIELDSET_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance fieldset 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 enhanceFieldsets(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for fieldset.
+  void root;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Form Element
+ *
+ * Form (`form`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing to a consistent baseline
+ * - Keeps form as a structural container (no layout patterns imposed)
+ * - Applies base typography tokens so the element can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.form
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(form) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  box-sizing: border-box;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline typography (standalone-safe)
+   -------------------------------------------------------------------------- */
+
+  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);
+  background-color: transparent;
+}

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

@@ -0,0 +1,308 @@
+/**
+ * pkgn-sol Design Foundation: Form element helpers.
+ *
+ * @remarks
+ * The form element (`<form>`) groups interactive controls for submitting data.
+ *
+ * Best-practice guidance:
+ * - Prefer HTTPS endpoints for `action` to protect user data in transit.
+ * - Use `method="post"` for submissions that change server state or include sensitive data.
+ * - Use `enctype="multipart/form-data"` when uploading files.
+ * - Provide explicit labels for controls and ensure accessible naming.
+ * - Consider `rel="noopener"` when using `target="_blank"` to avoid `window.opener` exposure.
+ *
+ * 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: `<form>` element :contentReference[oaicite:3]{index=3}
+ * - WHATWG HTML: Forms & submission attributes :contentReference[oaicite:4]{index=4}
+ * - MDN: `rel` on `<form>` / `noopener` :contentReference[oaicite:5]{index=5}
+ *
+ * @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 forms.
+ *
+ * @category Constants
+ */
+export const FORM_TAG = 'form' as const;
+
+/**
+ * A CSS selector targeting form elements.
+ *
+ * @category Constants
+ */
+export const FORM_SELECTOR = 'form';
+
+/**
+ * Allowed values for the form `method` attribute.
+ *
+ * @remarks
+ * HTML supports `get`, `post`, and `dialog` (for dialog-associated forms).
+ *
+ * @category Types
+ */
+export type FormMethod = 'get' | 'post' | 'dialog';
+
+/**
+ * Allowed values for the form `enctype` attribute.
+ *
+ * @category Types
+ */
+export type FormEnctype =
+  | 'application/x-www-form-urlencoded'
+  | 'multipart/form-data'
+  | 'text/plain';
+
+/**
+ * Allowed values for the form `autocomplete` attribute.
+ *
+ * @category Types
+ */
+export type FormAutocomplete = 'on' | 'off';
+
+/**
+ * Attribute bag for form creation/enhancement.
+ *
+ * @remarks
+ * `<form>` supports standard HTML global attributes plus submission-related
+ * attributes (action, method, enctype, target, etc.).
+ *
+ * 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 FormAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * URL that processes the form submission.
+   *
+   * @remarks
+   * If omitted, the user agent submits to the current document URL.
+   */
+  action?: string;
+
+  /**
+   * HTTP method used to submit the form.
+   *
+   * @remarks
+   * Valid values are `get`, `post`, and `dialog`.
+   */
+  method?: FormMethod;
+
+  /**
+   * Encoding type for the form submission.
+   *
+   * @remarks
+   * Use `multipart/form-data` when uploading files.
+   */
+  enctype?: FormEnctype;
+
+  /**
+   * Character encodings that are acceptable for server processing.
+   *
+   * @remarks
+   * Maps to the `accept-charset` attribute.
+   */
+  acceptCharset?: string;
+
+  /**
+   * Whether the browser may autofill this form.
+   */
+  autocomplete?: FormAutocomplete;
+
+  /**
+   * Name of the form, used for referencing the form in scripts and documents.
+   */
+  name?: string;
+
+  /**
+   * Disable constraint validation when submitting the form.
+   *
+   * @remarks
+   * Maps to the boolean `novalidate` attribute (represented by attribute presence).
+   */
+  noValidate?: boolean;
+
+  /**
+   * Where to display the response after submitting the form.
+   *
+   * @remarks
+   * Common values: `_self`, `_blank`, `_parent`, `_top`, or a named browsing context.
+   */
+  target?: '_self' | '_blank' | '_parent' | '_top' | (string & {});
+
+  /**
+   * Relationship (link types) for the form submission when `target` creates a new context.
+   *
+   * @remarks
+   * This is a space-separated list of tokens (e.g. `noopener noreferrer`).
+   */
+  rel?: string;
+
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link FormAttrs} 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.
+ * - Boolean attributes are represented by presence; we set empty-string when true.
+ *
+ * @param attrs - The form attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: FormAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const {
+    aria,
+    action,
+    method,
+    enctype,
+    acceptCharset,
+    autocomplete,
+    name,
+    noValidate,
+    target,
+    rel,
+    ...rest
+  } = attrs;
+
+  // 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, value: AttrValue | undefined): void => {
+    if (value === undefined) return;
+    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;
+    mergedAttrs[key] = value;
+  };
+
+  setIfUnset('action', action);
+  setIfUnset('method', method);
+  setIfUnset('enctype', enctype);
+  setIfUnset('accept-charset', acceptCharset);
+  setIfUnset('autocomplete', autocomplete);
+  setIfUnset('name', name);
+  setIfUnset('target', target);
+  setIfUnset('rel', rel);
+
+  // Boolean attributes are represented by presence. We set empty-string when true.
+  if (noValidate === true) setIfUnset('novalidate', '');
+
+  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 hasMappedAria = Object.keys(mappedAria).length > 0;
+  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;
+
+  const next: GlobalAttrs = { ...rest };
+  if (hasMergedAttrs) next.attrs = mergedAttrs;
+  if (hasMappedAria) next.aria = mappedAria;
+
+  return next;
+}
+
+/**
+ * Create a form 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 text content for the form (rare, but supported for parity).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<form>` element.
+ *
+ * @example
+ * ```ts
+ * import { createForm } from "@lnpg/pkgn-sol/elements/form/form";
+ *
+ * const form = createForm(undefined, {
+ *   action: "/submit",
+ *   method: "post",
+ *   enctype: "application/x-www-form-urlencoded",
+ * });
+ * document.body.appendChild(form);
+ * ```
+ *
+ * @category DOM
+ */
+export function createForm(text?: string, attrs?: FormAttrs): ElementOf<typeof FORM_TAG> {
+  return createElement(FORM_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance form 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 enhanceForms(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for form.
+  void root;
+}

package/src/elements/form/index.ts

@@ -0,0 +1,153 @@
+/**
+ * Form element factories.
+ *
+ * Provides framework-agnostic factory functions for common HTML form elements.
+ *
+ * These factories:
+ * - Create semantic form structures using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct form semantics and associations (e.g. labels, fieldsets).
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/form
+ * @since 0.1.0
+ */
+
+/**
+ * `<button>` element factory namespace.
+ *
+ * Represents a clickable button used to submit forms, reset forms, or trigger
+ * custom actions.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button
+ */
+export * as button from './button';
+
+/**
+ * `<datalist>` element factory namespace.
+ *
+ * Represents a set of `<option>` suggestions for an associated `<input>`,
+ * enabling autocomplete-like behavior.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
+ */
+export * as datalist from './datalist';
+
+/**
+ * `<fieldset>` element factory namespace.
+ *
+ * Represents a grouping container for related form controls, typically paired
+ * with a `<legend>` that labels the group.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset
+ */
+export * as fieldset from './fieldset';
+
+/**
+ * `<form>` element factory namespace.
+ *
+ * Represents a document section containing interactive controls for submitting
+ * information to a web server or handling via client-side logic.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
+ */
+export * as form from './form';
+
+/**
+ * `<input>` element factory namespace.
+ *
+ * Represents an interactive control for entering data. The `type` attribute
+ * determines the control's behavior and UI.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
+ */
+export * as input from './input';
+
+/**
+ * `<label>` element factory namespace.
+ *
+ * Represents a caption for a form control, improving usability and
+ * accessibility. Typically associated via the `for` attribute or by nesting.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label
+ */
+export * as label from './label';
+
+/**
+ * `<legend>` element factory namespace.
+ *
+ * Represents a caption for the content of its parent `<fieldset>`, providing an
+ * accessible label for grouped controls.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend
+ */
+export * as legend from './legend';
+
+/**
+ * `<meter>` element factory namespace.
+ *
+ * Represents a scalar measurement within a known range, or a fractional value.
+ * Use `<progress>` instead for progress over time.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meter
+ */
+export * as meter from './meter';
+
+/**
+ * `<optgroup>` element factory namespace.
+ *
+ * Represents a grouping of `<option>` elements within a `<select>` or
+ * `<datalist>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup
+ */
+export * as optgroup from './optgroup';
+
+/**
+ * `<option>` element factory namespace.
+ *
+ * Represents an item within a `<select>`, `<datalist>`, or `<optgroup>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option
+ */
+export * as option from './option';
+
+/**
+ * `<output>` element factory namespace.
+ *
+ * Represents the result of a calculation or user action, commonly used in
+ * forms to display derived values.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/output
+ */
+export * as output from './output';
+
+/**
+ * `<progress>` element factory namespace.
+ *
+ * Represents the completion progress of a task, typically over time.
+ * Use `<meter>` instead for a measurement within a known range.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress
+ */
+export * as progress from './progress';
+
+/**
+ * `<select>` element factory namespace.
+ *
+ * Represents a control that provides a menu of options for the user to choose
+ * from.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select
+ */
+export * as select from './select';
+
+/**
+ * `<textarea>` element factory namespace.
+ *
+ * Represents a multi-line plain-text editing control.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+ */
+export * as textarea from './textarea';