@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/esm/elements/form/datalist/datalist.js

@@ -0,0 +1,26 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/datalist/index.ts
+var n = /* @__PURE__ */ e({
+	DATALIST_SELECTOR: () => i,
+	DATALIST_TAG: () => r,
+	createDatalist: () => o,
+	enhanceDatalists: () => s
+}), r = "datalist", i = "datalist";
+function a(e) {
+	if (!e) return;
+	let { aria: t, ...n } = e;
+	if (!t) return n;
+	let r = {};
+	return typeof t.label == "string" && (r.label = t.label), typeof t.labelledby == "string" && (r.labelledby = t.labelledby), typeof t.hidden == "boolean" && (r.hidden = t.hidden), Object.keys(r).length > 0 ? {
+		...n,
+		aria: r
+	} : n;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as DATALIST_SELECTOR, r as DATALIST_TAG, o as createDatalist, s as enhanceDatalists, n as t };
+
+//# sourceMappingURL=datalist.js.map

package/dist/esm/elements/form/datalist/datalist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datalist.js","names":[],"sources":["../../../../../src/elements/form/datalist/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Datalist element helpers.\n *\n * @remarks\n * The datalist element (`<datalist>`) contains a set of `<option>` elements that\n * represent permissible or recommended values for an associated form control\n * (most commonly an `<input>`), connected via the input's `list` attribute.\n *\n * Best-practice guidance:\n * - Pair a `<datalist>` with an `<input>` using a stable, unique `id` on the\n *   datalist and a matching `list` attribute on the input.\n * - Use `<datalist>` for suggestions, not strict validation. If users must pick\n *   from a fixed set, prefer `<select>`.\n * - Populate suggestions using descendant `<option>` elements, typically with\n *   `value` attributes.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create `<datalist>` elements in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * Attributes:\n * - `<datalist>` supports global attributes only (no element-specific content\n *   attributes).\n *\n * Security:\n * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which\n *   block inline event handler attributes (e.g. `onclick`) and raw `style`\n *   attribute injection (use the `style` object field instead).\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/datalist\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs (e.g. `lable`).\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for datalist.\n *\n * @category Constants\n */\nexport const DATALIST_TAG = 'datalist' as const;\n\n/**\n * A CSS selector targeting datalist elements.\n *\n * @category Constants\n */\nexport const DATALIST_SELECTOR = 'datalist';\n\n/**\n * Attribute bag for datalist creation/enhancement.\n *\n * @remarks\n * Datalist elements accept standard HTML global attributes.\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type DatalistAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Normalize {@link DatalistAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The datalist attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: DatalistAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, ...rest } = attrs;\n\n  if (!aria) return rest;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (typeof aria.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n  // Only attach `aria` if something was actually defined.\n  const hasMapped = Object.keys(mappedAria).length > 0;\n\n  return hasMapped ? { ...rest, aria: mappedAria } : rest;\n}\n\n/**\n * Create a datalist element with optional text content and global attributes.\n *\n * @remarks\n * While `<datalist>` is typically populated with `<option>` children, this helper\n * follows pkgn-sol's consistent \"optional text\" factory signature for non-void elements.\n *\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the datalist (rare, but supported).\n * @param attrs - Optional attributes to apply.\n * @returns The created `<datalist>` element.\n *\n * @example\n * ```ts\n * import { createDatalist } from \"@lnpg/pkgn-sol/elements/form/datalist\";\n *\n * const dl = createDatalist(undefined, { id: \"city-list\" });\n * document.body.appendChild(dl);\n * ```\n *\n * @category DOM\n */\nexport function createDatalist(\n  text?: string,\n  attrs?: DatalistAttrs,\n): ElementOf<typeof DATALIST_TAG> {\n  return createElement(DATALIST_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance datalist elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceDatalists(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for datalist.\n  void root;\n}\n"],"mappings":";;;;;;;IA0Ea,IAAe,YAOf,IAAoB;AA4BjC,SAAS,EAAc,GAAgD;CACrE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,GAAG,MAAS;CAE1B,IAAI,CAAC,GAAM,OAAO;CAElB,IAAM,IAA+C,EAAE;CASvD,OAPI,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,SAG7C,OAAO,KAAK,EAAW,CAAC,SAAS,IAEhC;EAAE,GAAG;EAAM,MAAM;EAAY,GAAG;;AA6BrD,SAAgB,EACd,GACA,GACgC;CAChC,OAAO,EAAc,GAAc,EAAc,EAAM,EAAE,EAAK;;AAqBhE,SAAgB,EAAiB,IAAmB,UAAgB"}

package/dist/esm/elements/form/fieldset/fieldset.js

@@ -0,0 +1,27 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/fieldset/index.ts
+var n = /* @__PURE__ */ e({
+	FIELDSET_SELECTOR: () => i,
+	FIELDSET_TAG: () => r,
+	createFieldset: () => o,
+	enhanceFieldsets: () => s
+}), r = "fieldset", i = "fieldset";
+function a(e) {
+	if (!e) return;
+	let { aria: t, disabled: n, form: r, name: i, ...a } = e, o = { ...a.attrs ?? {} }, s = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(o, e) || (o[e] = t));
+	};
+	s("form", r), s("name", i), n === !0 && s("disabled", "");
+	let c = {};
+	t && (typeof t.label == "string" && (c.label = t.label), typeof t.labelledby == "string" && (c.labelledby = t.labelledby), typeof t.hidden == "boolean" && (c.hidden = t.hidden));
+	let l = Object.keys(c).length > 0, u = Object.keys(o).length > 0, d = { ...a };
+	return u && (d.attrs = o), l && (d.aria = c), d;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as FIELDSET_SELECTOR, r as FIELDSET_TAG, o as createFieldset, s as enhanceFieldsets, n as t };
+
+//# sourceMappingURL=fieldset.js.map

package/dist/esm/elements/form/fieldset/fieldset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldset.js","names":[],"sources":["../../../../../src/elements/form/fieldset/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Fieldset element helpers.\n *\n * @remarks\n * The fieldset element (`<fieldset>`) groups related form controls, typically\n * with a `<legend>` that provides an accessible label for the group.\n *\n * Best-practice guidance:\n * - Use `<fieldset>` to group related controls (e.g. radio button sets).\n * - Prefer a meaningful `<legend>` as the first child to label the group.\n * - Do not use `<fieldset>` purely for layout; use CSS for visual grouping.\n *\n * Attribute behavior notes:\n * - When `disabled` is set on a `<fieldset>`, user agents disable descendant\n *   form controls, except those that are descendants of the fieldset's first\n *   `<legend>` child (if any). This is native platform behavior.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create fieldsets in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset\n * @see https://www.w3.org/WAI/tutorials/forms/grouping/\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for fieldset groups.\n *\n * @category Constants\n */\nexport const FIELDSET_TAG = 'fieldset' as const;\n\n/**\n * A CSS selector targeting fieldset elements.\n *\n * @category Constants\n */\nexport const FIELDSET_SELECTOR = 'fieldset';\n\n/**\n * Attribute bag for fieldset creation/enhancement.\n *\n * @remarks\n * Fieldset accepts standard HTML global attributes plus fieldset-specific\n * attributes (`disabled`, `form`, `name`).\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type FieldsetAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Disables descendant form controls (native platform behavior).\n   *\n   * @remarks\n   * When set, controls inside the first `<legend>` (if present) are typically\n   * excluded from disabling per spec/user agent behavior.\n   */\n  disabled?: boolean;\n\n  /**\n   * Associates the fieldset with a form element by ID, even if not a descendant.\n   */\n  form?: string;\n\n  /**\n   * Name of the fieldset (submitted/associated in form processing contexts).\n   */\n  name?: string;\n};\n\n/**\n * Normalize {@link FieldsetAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The fieldset attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: FieldsetAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, disabled, form, name, ...rest } = attrs;\n\n  // Start with any caller-provided attrs escape hatch (still validated by dom.ts).\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  const setIfUnset = (key: string, value: AttrValue | undefined): void => {\n    if (value === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = value;\n  };\n\n  setIfUnset('form', form);\n  setIfUnset('name', name);\n\n  // Boolean attributes are represented by presence. We set empty-string when true.\n  if (disabled === true) setIfUnset('disabled', '');\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;\n\n  const next: GlobalAttrs = { ...rest };\n  if (hasMergedAttrs) next.attrs = mergedAttrs;\n  if (hasMappedAria) next.aria = mappedAria;\n\n  return next;\n}\n\n/**\n * Create a fieldset element with optional text content and attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the fieldset (rare; most fieldsets contain child nodes).\n * @param attrs - Optional attributes to apply.\n * @returns The created `<fieldset>` element.\n *\n * @example\n * ```ts\n * import { createFieldset } from \"@lnpg/pkgn-sol/elements/form/fieldset\";\n *\n * const fs = createFieldset(undefined, { disabled: false });\n * // fs.appendChild(createLegend(\"Shipping address\"));\n * ```\n *\n * @category DOM\n */\nexport function createFieldset(\n  text?: string,\n  attrs?: FieldsetAttrs,\n): ElementOf<typeof FIELDSET_TAG> {\n  return createElement(FIELDSET_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance fieldset elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceFieldsets(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for fieldset.\n  void root;\n}\n"],"mappings":";;;;;;;IAmEa,IAAe,YAOf,IAAoB;AAgDjC,SAAS,EAAc,GAAgD;CACrE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,aAAU,SAAM,SAAM,GAAG,MAAS,GAG1C,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAElE,KAAc,GAAa,MAAuC;EAClE,MAAU,KAAA,MACV,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;;CAOrB,AAJA,EAAW,QAAQ,EAAK,EACxB,EAAW,QAAQ,EAAK,EAGpB,MAAa,MAAM,EAAW,YAAY,GAAG;CAEjD,IAAM,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAgB,OAAO,KAAK,EAAW,CAAC,SAAS,GACjD,IAAiB,OAAO,KAAK,EAAY,CAAC,SAAS,GAEnD,IAAoB,EAAE,GAAG,GAAM;CAIrC,OAHI,MAAgB,EAAK,QAAQ,IAC7B,MAAe,EAAK,OAAO,IAExB;;AA0BT,SAAgB,EACd,GACA,GACgC;CAChC,OAAO,EAAc,GAAc,EAAc,EAAM,EAAE,EAAK;;AAqBhE,SAAgB,EAAiB,IAAmB,UAAgB"}

package/dist/esm/elements/form/form/form.js

@@ -0,0 +1,27 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/form/index.ts
+var n = /* @__PURE__ */ e({
+	FORM_SELECTOR: () => i,
+	FORM_TAG: () => r,
+	createForm: () => o,
+	enhanceForms: () => s
+}), r = "form", i = "form";
+function a(e) {
+	if (!e) return;
+	let { aria: t, action: n, method: r, enctype: i, acceptCharset: a, autocomplete: o, name: s, noValidate: c, target: l, rel: u, ...d } = e, f = { ...d.attrs ?? {} }, p = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(f, e) || (f[e] = t));
+	};
+	p("action", n), p("method", r), p("enctype", i), p("accept-charset", a), p("autocomplete", o), p("name", s), p("target", l), p("rel", u), c === !0 && p("novalidate", "");
+	let m = {};
+	t && (typeof t.label == "string" && (m.label = t.label), typeof t.labelledby == "string" && (m.labelledby = t.labelledby), typeof t.hidden == "boolean" && (m.hidden = t.hidden));
+	let h = Object.keys(m).length > 0, g = Object.keys(f).length > 0, _ = { ...d };
+	return g && (_.attrs = f), h && (_.aria = m), _;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as FORM_SELECTOR, r as FORM_TAG, o as createForm, s as enhanceForms, n as t };
+
+//# sourceMappingURL=form.js.map

package/dist/esm/elements/form/form/form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.js","names":[],"sources":["../../../../../src/elements/form/form/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Form element helpers.\n *\n * @remarks\n * The form element (`<form>`) groups interactive controls for submitting data.\n *\n * Best-practice guidance:\n * - Prefer HTTPS endpoints for `action` to protect user data in transit.\n * - Use `method=\"post\"` for submissions that change server state or include sensitive data.\n * - Use `enctype=\"multipart/form-data\"` when uploading files.\n * - Provide explicit labels for controls and ensure accessible naming.\n * - Consider `rel=\"noopener\"` when using `target=\"_blank\"` to avoid `window.opener` exposure.\n *\n * pkgn-sol notes:\n * - This module is framework-agnostic and has no side effects.\n * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:\n *   - inline event handler attributes (e.g. `onclick`)\n *   - raw `style` attribute injection (use the `style` object instead)\n * - Text passed to factories is assigned via `textContent` (never `innerHTML`).\n *\n * References:\n * - MDN: `<form>` element :contentReference[oaicite:3]{index=3}\n * - WHATWG HTML: Forms & submission attributes :contentReference[oaicite:4]{index=4}\n * - MDN: `rel` on `<form>` / `noopener` :contentReference[oaicite:5]{index=5}\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for forms.\n *\n * @category Constants\n */\nexport const FORM_TAG = 'form' as const;\n\n/**\n * A CSS selector targeting form elements.\n *\n * @category Constants\n */\nexport const FORM_SELECTOR = 'form';\n\n/**\n * Allowed values for the form `method` attribute.\n *\n * @remarks\n * HTML supports `get`, `post`, and `dialog` (for dialog-associated forms).\n *\n * @category Types\n */\nexport type FormMethod = 'get' | 'post' | 'dialog';\n\n/**\n * Allowed values for the form `enctype` attribute.\n *\n * @category Types\n */\nexport type FormEnctype =\n  | 'application/x-www-form-urlencoded'\n  | 'multipart/form-data'\n  | 'text/plain';\n\n/**\n * Allowed values for the form `autocomplete` attribute.\n *\n * @category Types\n */\nexport type FormAutocomplete = 'on' | 'off';\n\n/**\n * Attribute bag for form creation/enhancement.\n *\n * @remarks\n * `<form>` supports standard HTML global attributes plus submission-related\n * attributes (action, method, enctype, target, etc.).\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type FormAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * URL that processes the form submission.\n   *\n   * @remarks\n   * If omitted, the user agent submits to the current document URL.\n   */\n  action?: string;\n\n  /**\n   * HTTP method used to submit the form.\n   *\n   * @remarks\n   * Valid values are `get`, `post`, and `dialog`.\n   */\n  method?: FormMethod;\n\n  /**\n   * Encoding type for the form submission.\n   *\n   * @remarks\n   * Use `multipart/form-data` when uploading files.\n   */\n  enctype?: FormEnctype;\n\n  /**\n   * Character encodings that are acceptable for server processing.\n   *\n   * @remarks\n   * Maps to the `accept-charset` attribute.\n   */\n  acceptCharset?: string;\n\n  /**\n   * Whether the browser may autofill this form.\n   */\n  autocomplete?: FormAutocomplete;\n\n  /**\n   * Name of the form, used for referencing the form in scripts and documents.\n   */\n  name?: string;\n\n  /**\n   * Disable constraint validation when submitting the form.\n   *\n   * @remarks\n   * Maps to the boolean `novalidate` attribute (represented by attribute presence).\n   */\n  noValidate?: boolean;\n\n  /**\n   * Where to display the response after submitting the form.\n   *\n   * @remarks\n   * Common values: `_self`, `_blank`, `_parent`, `_top`, or a named browsing context.\n   */\n  target?: '_self' | '_blank' | '_parent' | '_top' | (string & {});\n\n  /**\n   * Relationship (link types) for the form submission when `target` creates a new context.\n   *\n   * @remarks\n   * This is a space-separated list of tokens (e.g. `noopener noreferrer`).\n   */\n  rel?: string;\n\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Normalize {@link FormAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @remarks\n * - Preserves caller-provided `attrs` escape hatch (still validated by `dom.ts`).\n * - Element-specific attributes are merged into `attrs` without overwriting keys\n *   explicitly provided by the caller.\n * - Boolean attributes are represented by presence; we set empty-string when true.\n *\n * @param attrs - The form attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: FormAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const {\n    aria,\n    action,\n    method,\n    enctype,\n    acceptCharset,\n    autocomplete,\n    name,\n    noValidate,\n    target,\n    rel,\n    ...rest\n  } = attrs;\n\n  // Start with any caller-provided attrs escape hatch (it is still validated by dom.ts).\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  // Helper: only set if caller didn't already set the raw attribute explicitly.\n  const setIfUnset = (key: string, value: AttrValue | undefined): void => {\n    if (value === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = value;\n  };\n\n  setIfUnset('action', action);\n  setIfUnset('method', method);\n  setIfUnset('enctype', enctype);\n  setIfUnset('accept-charset', acceptCharset);\n  setIfUnset('autocomplete', autocomplete);\n  setIfUnset('name', name);\n  setIfUnset('target', target);\n  setIfUnset('rel', rel);\n\n  // Boolean attributes are represented by presence. We set empty-string when true.\n  if (noValidate === true) setIfUnset('novalidate', '');\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;\n\n  const next: GlobalAttrs = { ...rest };\n  if (hasMergedAttrs) next.attrs = mergedAttrs;\n  if (hasMappedAria) next.aria = mappedAria;\n\n  return next;\n}\n\n/**\n * Create a form element with optional fallback text and attributes.\n *\n * @remarks\n * - Fallback text is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the form (rare, but supported for parity).\n * @param attrs - Optional attributes to apply.\n * @returns The created `<form>` element.\n *\n * @example\n * ```ts\n * import { createForm } from \"@lnpg/pkgn-sol/elements/form/form\";\n *\n * const form = createForm(undefined, {\n *   action: \"/submit\",\n *   method: \"post\",\n *   enctype: \"application/x-www-form-urlencoded\",\n * });\n * document.body.appendChild(form);\n * ```\n *\n * @category DOM\n */\nexport function createForm(text?: string, attrs?: FormAttrs): ElementOf<typeof FORM_TAG> {\n  return createElement(FORM_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance form elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceForms(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for form.\n  void root;\n}\n"],"mappings":";;;;;;;IAgEa,IAAW,QAOX,IAAgB;AAgI7B,SAAS,EAAc,GAA4C;CACjE,IAAI,CAAC,GAAO;CAEZ,IAAM,EACJ,SACA,WACA,WACA,YACA,kBACA,iBACA,SACA,eACA,WACA,QACA,GAAG,MACD,GAGE,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAGlE,KAAc,GAAa,MAAuC;EAClE,MAAU,KAAA,MACV,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;;CAarB,AAVA,EAAW,UAAU,EAAO,EAC5B,EAAW,UAAU,EAAO,EAC5B,EAAW,WAAW,EAAQ,EAC9B,EAAW,kBAAkB,EAAc,EAC3C,EAAW,gBAAgB,EAAa,EACxC,EAAW,QAAQ,EAAK,EACxB,EAAW,UAAU,EAAO,EAC5B,EAAW,OAAO,EAAI,EAGlB,MAAe,MAAM,EAAW,cAAc,GAAG;CAErD,IAAM,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAgB,OAAO,KAAK,EAAW,CAAC,SAAS,GACjD,IAAiB,OAAO,KAAK,EAAY,CAAC,SAAS,GAEnD,IAAoB,EAAE,GAAG,GAAM;CAIrC,OAHI,MAAgB,EAAK,QAAQ,IAC7B,MAAe,EAAK,OAAO,IAExB;;AA8BT,SAAgB,EAAW,GAAe,GAA+C;CACvF,OAAO,EAAc,GAAU,EAAc,EAAM,EAAE,EAAK;;AAqB5D,SAAgB,EAAa,IAAmB,UAAgB"}

package/dist/esm/elements/form/form.js

@@ -0,0 +1,36 @@
+import { i as e } from "../../chunks/dom.js";
+import { t } from "./button/button.js";
+import { t as n } from "./datalist/datalist.js";
+import { t as r } from "./fieldset/fieldset.js";
+import { t as i } from "./form/form.js";
+import { t as a } from "./input/input.js";
+import { t as o } from "./label/label.js";
+import { t as s } from "./legend/legend.js";
+import { t as c } from "./meter/meter.js";
+import { t as l } from "./optgroup/optgroup.js";
+import { t as u } from "./option/option.js";
+import { t as d } from "./output/output.js";
+import { t as f } from "./progress/progress.js";
+import { t as p } from "./select/select.js";
+import { t as m } from "./textarea/textarea.js";
+//#region src/elements/form/index.ts
+var h = /* @__PURE__ */ e({
+	button: () => t,
+	datalist: () => n,
+	fieldset: () => r,
+	form: () => i,
+	input: () => a,
+	label: () => o,
+	legend: () => s,
+	meter: () => c,
+	optgroup: () => l,
+	option: () => u,
+	output: () => d,
+	progress: () => f,
+	select: () => p,
+	textarea: () => m
+});
+//#endregion
+export { t as button, n as datalist, r as fieldset, i as form, a as input, o as label, s as legend, c as meter, l as optgroup, u as option, d as output, f as progress, p as select, h as t, m as textarea };
+
+//# sourceMappingURL=form.js.map

package/dist/esm/elements/form/form.js.map

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

package/dist/esm/elements/form/input/input.js

@@ -0,0 +1,31 @@
+import { i as e, r as t } from "../../../chunks/dom.js";
+//#region src/elements/form/input/index.ts
+var n = /* @__PURE__ */ e({
+	INPUT_SELECTOR: () => i,
+	INPUT_TAG: () => r,
+	createInput: () => o,
+	enhanceInputs: () => s
+}), r = "input", i = "input";
+function a(e) {
+	let { aria: t, type: n, name: r, value: i, placeholder: a, disabled: o, readOnly: s, required: c, multiple: l, checked: u, min: d, max: f, step: p, minLength: m, maxLength: h, pattern: g, size: _, autoComplete: v, autofocus: y, list: b, form: x, formAction: S, formEnctype: C, formMethod: w, formNoValidate: T, formTarget: E, src: D, alt: O, width: k, height: A, accept: j, capture: M, inputMode: N, enterKeyHint: P, popoverTarget: F, popoverTargetAction: I, ...L } = e ?? {}, R = { ...L.attrs ?? {} }, z = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(R, e) || (R[e] = t));
+	};
+	z("type", n ?? "text"), z("name", r), z("value", i), z("placeholder", a), z("min", d), z("max", f), z("step", p), z("minlength", typeof m == "number" ? m : void 0), z("maxlength", typeof h == "number" ? h : void 0), z("pattern", g), z("size", typeof _ == "number" ? _ : void 0), z("autocomplete", v), z("list", b), z("form", x), z("formaction", S), z("formenctype", C), z("formmethod", w), z("formtarget", E), z("src", D), z("alt", O), z("width", typeof k == "number" ? k : void 0), z("height", typeof A == "number" ? A : void 0), z("accept", j), z("inputmode", N), z("enterkeyhint", P), z("popovertarget", F), z("popovertargetaction", I), o === !0 && z("disabled", ""), s === !0 && z("readonly", ""), c === !0 && z("required", ""), l === !0 && z("multiple", ""), u === !0 && z("checked", ""), y === !0 && z("autofocus", ""), T === !0 && z("formnovalidate", ""), M === !0 && z("capture", ""), M === "user" && z("capture", "user"), M === "environment" && z("capture", "environment");
+	let B = {
+		...L,
+		attrs: R
+	}, V = {};
+	if (t && (typeof t.label == "string" && (V.label = t.label), typeof t.labelledby == "string" && (V.labelledby = t.labelledby), typeof t.hidden == "boolean" && (V.hidden = t.hidden)), Object.keys(V).length > 0 && (B.aria = V), Object.keys(R).length === 0) {
+		let { attrs: e, ...t } = B;
+		return t;
+	}
+	return B;
+}
+function o(e) {
+	return t(r, a(e));
+}
+function s(e = document) {}
+//#endregion
+export { i as INPUT_SELECTOR, r as INPUT_TAG, o as createInput, s as enhanceInputs, n as t };
+
+//# sourceMappingURL=input.js.map

package/dist/esm/elements/form/input/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","names":[],"sources":["../../../../../src/elements/form/input/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Input element helpers.\n *\n * @remarks\n * The input element (`<input>`) represents a typed data field whose behavior is\n * primarily controlled by its `type` attribute. :contentReference[oaicite:5]{index=5}\n *\n * Best-practice guidance:\n * - Prefer the most specific `type` possible (e.g. `email`, `tel`, `number`)\n *   to improve UX and validation behavior.\n * - Always provide an accessible name (visible label, `aria-label`, or\n *   `aria-labelledby`).\n * - Treat `autocomplete`, `inputmode`, and `enterkeyhint` as UX hints, not\n *   security controls. :contentReference[oaicite:6]{index=6}\n * - For `<input type=\"image\">`, include meaningful `alt` text; while it may be\n *   technically optional, it should be provided for usability/accessibility. :contentReference[oaicite:7]{index=7}\n *\n * pkgn-sol-specific conventions:\n * - Defaults `type` to `\"text\"` unless explicitly overridden (typed field or raw\n *   attrs escape hatch), matching HTML's default behavior. :contentReference[oaicite:8]{index=8}\n * - Applies global attributes via pkgn-sol's hardened DOM helpers (`dom.ts`),\n *   which block inline event handler attributes (e.g. `onclick`) and the raw\n *   `style` attribute string.\n * - Supports a small structured ARIA input to reduce typo-based ARIA bugs.\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport {\n  createVoidElement,\n  type AttrValue,\n  type ElementOf,\n  type GlobalAttrs,\n} from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset mapped into {@link GlobalAttrs.aria}.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Common input `type` values.\n *\n * @remarks\n * The `type` attribute controls which control is rendered and how values are\n * processed. :contentReference[oaicite:9]{index=9}\n *\n * pkgn-sol models the widely used types while still allowing the raw `attrs` escape\n * hatch for unusual/experimental values.\n *\n * @category Attributes\n */\nexport type InputType =\n  | 'text'\n  | 'password'\n  | 'email'\n  | 'number'\n  | 'search'\n  | 'tel'\n  | 'url'\n  | 'date'\n  | 'datetime-local'\n  | 'month'\n  | 'week'\n  | 'time'\n  | 'color'\n  | 'checkbox'\n  | 'radio'\n  | 'file'\n  | 'hidden'\n  | 'image'\n  | 'range'\n  | 'reset'\n  | 'submit'\n  | 'button';\n\n/**\n * Values for the `inputmode` hint.\n *\n * @remarks\n * `inputmode` is a hint to user agents about what kind of virtual keyboard to\n * show. :contentReference[oaicite:10]{index=10}\n *\n * @category Attributes\n */\nexport type InputMode =\n  | 'none'\n  | 'text'\n  | 'tel'\n  | 'url'\n  | 'email'\n  | 'numeric'\n  | 'decimal'\n  | 'search';\n\n/**\n * Values for the `enterkeyhint` hint.\n *\n * @remarks\n * Defines what action label/icon to present for the enter key on virtual\n * keyboards. :contentReference[oaicite:11]{index=11}\n *\n * @category Attributes\n */\nexport type EnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';\n\n/**\n * Values for the `popovertargetaction` attribute when the input is used as a\n * popover invoker button.\n *\n * @category Attributes\n */\nexport type PopoverTargetAction = 'toggle' | 'show' | 'hide';\n\n/**\n * The semantic tag name for inputs.\n *\n * @category Constants\n */\nexport const INPUT_TAG = 'input' as const;\n\n/**\n * A CSS selector targeting input elements.\n *\n * @category Constants\n */\nexport const INPUT_SELECTOR = 'input';\n\n/**\n * Attribute bag for input creation/enhancement.\n *\n * @remarks\n * `<input>` supports a large surface area of attributes, many of which are\n * type-dependent. pkgn-sol models common attributes explicitly and provides\n * {@link GlobalAttrs.attrs} as an escape hatch (validated by `dom.ts`).\n *\n * Notes:\n * - pkgn-sol defaults `type` to `\"text\"` unless explicitly overridden. :contentReference[oaicite:12]{index=12}\n * - Boolean attributes are applied by presence (empty string) when `true`.\n * - For `type=\"image\"`, `alt` should be provided for accessibility. :contentReference[oaicite:13]{index=13}\n *\n * @category Attributes\n */\nexport type InputAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * The input type. Defaults to `\"text\"` in pkgn-sol.\n   */\n  type?: InputType;\n\n  /**\n   * Form field name (used during submission).\n   */\n  name?: string;\n\n  /**\n   * Initial/current value (type-dependent semantics).\n   */\n  value?: string;\n\n  /**\n   * Placeholder hint (text-like types).\n   */\n  placeholder?: string;\n\n  /**\n   * Disables the control when true.\n   */\n  disabled?: boolean;\n\n  /**\n   * Marks the control read-only when true (where applicable).\n   */\n  readOnly?: boolean;\n\n  /**\n   * Marks the control required for form submission.\n   */\n  required?: boolean;\n\n  /**\n   * Enables multiple values (e.g. file inputs).\n   */\n  multiple?: boolean;\n\n  /**\n   * Marks a checkbox or radio as checked.\n   */\n  checked?: boolean;\n\n  /**\n   * Minimum value (number/date/time/range-like types).\n   */\n  min?: string | number;\n\n  /**\n   * Maximum value (number/date/time/range-like types).\n   */\n  max?: string | number;\n\n  /**\n   * Step interval (number/date/time/range-like types).\n   */\n  step?: string | number;\n\n  /**\n   * Minimum length (text-like types).\n   */\n  minLength?: number;\n\n  /**\n   * Maximum length (text-like types).\n   */\n  maxLength?: number;\n\n  /**\n   * Validation pattern (text-like types).\n   */\n  pattern?: string;\n\n  /**\n   * Size hint (visible character width, where applicable).\n   */\n  size?: number;\n\n  /**\n   * Autocomplete hint.\n   */\n  autoComplete?: string;\n\n  /**\n   * Autofocus hint.\n   */\n  autofocus?: boolean;\n\n  /**\n   * Associates the control with a datalist element by ID.\n   */\n  list?: string;\n\n  /**\n   * Associates the control with a form element by ID.\n   */\n  form?: string;\n\n  /**\n   * Overrides form submission target for submit/image inputs.\n   */\n  formAction?: string;\n\n  /**\n   * Overrides form submission encoding for submit/image inputs.\n   */\n  formEnctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';\n\n  /**\n   * Overrides form submission method for submit/image inputs.\n   */\n  formMethod?: 'get' | 'post' | 'dialog';\n\n  /**\n   * Prevents constraint validation on submission.\n   */\n  formNoValidate?: boolean;\n\n  /**\n   * Overrides form submission browsing context target.\n   */\n  formTarget?: string;\n\n  /**\n   * Source URL for `type=\"image\"`.\n   */\n  src?: string;\n\n  /**\n   * Alternate text for `type=\"image\"`.\n   *\n   * @remarks\n   * This is only meaningful for image inputs and should be provided. :contentReference[oaicite:14]{index=14}\n   */\n  alt?: string;\n\n  /**\n   * Width for `type=\"image\"`.\n   */\n  width?: number;\n\n  /**\n   * Height for `type=\"image\"`.\n   */\n  height?: number;\n\n  /**\n   * Accepted file types (for `type=\"file\"`).\n   */\n  accept?: string;\n\n  /**\n   * Media capture hint (primarily file inputs on mobile).\n   *\n   * @remarks\n   * If set to `true`, the boolean attribute is applied by presence.\n   */\n  capture?: 'user' | 'environment' | true;\n\n  /**\n   * Hint for the virtual keyboard shown on touch devices.\n   */\n  inputMode?: InputMode;\n\n  /**\n   * Hint for the virtual keyboard enter key label/icon.\n   */\n  enterKeyHint?: EnterKeyHint;\n\n  /**\n   * ID of the popover element this input controls (typically `type=\"button\"`).\n   */\n  popoverTarget?: string;\n\n  /**\n   * Action to perform on the targeted popover.\n   */\n  popoverTargetAction?: PopoverTargetAction;\n};\n\n/**\n * Normalize {@link InputAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @remarks\n * Pattern:\n * - Start with any caller-provided raw attrs escape hatch.\n * - Apply typed attributes without overriding explicit raw attributes.\n * - Map structured ARIA into {@link GlobalAttrs.aria}.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: InputAttrs): GlobalAttrs {\n  const {\n    aria,\n    type,\n    name,\n    value,\n    placeholder,\n    disabled,\n    readOnly,\n    required,\n    multiple,\n    checked,\n    min,\n    max,\n    step,\n    minLength,\n    maxLength,\n    pattern,\n    size,\n    autoComplete,\n    autofocus,\n    list,\n    form,\n    formAction,\n    formEnctype,\n    formMethod,\n    formNoValidate,\n    formTarget,\n    src,\n    alt,\n    width,\n    height,\n    accept,\n    capture,\n    inputMode,\n    enterKeyHint,\n    popoverTarget,\n    popoverTargetAction,\n    ...rest\n  } = attrs ?? {};\n\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  const setIfUnset = (key: string, v: AttrValue | undefined): void => {\n    if (v === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = v;\n  };\n\n  // Default type to \"text\" unless explicitly overridden.\n  setIfUnset('type', type ?? 'text');\n\n  setIfUnset('name', name);\n  setIfUnset('value', value);\n  setIfUnset('placeholder', placeholder);\n  setIfUnset('min', min);\n  setIfUnset('max', max);\n  setIfUnset('step', step);\n  setIfUnset('minlength', typeof minLength === 'number' ? minLength : undefined);\n  setIfUnset('maxlength', typeof maxLength === 'number' ? maxLength : undefined);\n  setIfUnset('pattern', pattern);\n  setIfUnset('size', typeof size === 'number' ? size : undefined);\n  setIfUnset('autocomplete', autoComplete);\n  setIfUnset('list', list);\n  setIfUnset('form', form);\n\n  setIfUnset('formaction', formAction);\n  setIfUnset('formenctype', formEnctype);\n  setIfUnset('formmethod', formMethod);\n  setIfUnset('formtarget', formTarget);\n\n  setIfUnset('src', src);\n  setIfUnset('alt', alt);\n  setIfUnset('width', typeof width === 'number' ? width : undefined);\n  setIfUnset('height', typeof height === 'number' ? height : undefined);\n\n  setIfUnset('accept', accept);\n  setIfUnset('inputmode', inputMode);\n  setIfUnset('enterkeyhint', enterKeyHint);\n\n  setIfUnset('popovertarget', popoverTarget);\n  setIfUnset('popovertargetaction', popoverTargetAction);\n\n  // Boolean attributes: presence (empty string) when true.\n  if (disabled === true) setIfUnset('disabled', '');\n  if (readOnly === true) setIfUnset('readonly', '');\n  if (required === true) setIfUnset('required', '');\n  if (multiple === true) setIfUnset('multiple', '');\n  if (checked === true) setIfUnset('checked', '');\n  if (autofocus === true) setIfUnset('autofocus', '');\n  if (formNoValidate === true) setIfUnset('formnovalidate', '');\n\n  if (capture === true) setIfUnset('capture', '');\n  if (capture === 'user') setIfUnset('capture', 'user');\n  if (capture === 'environment') setIfUnset('capture', 'environment');\n\n  const mapped: GlobalAttrs = { ...rest, attrs: mergedAttrs };\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  if (Object.keys(mappedAria).length > 0) {\n    mapped.aria = mappedAria;\n  }\n\n  if (Object.keys(mergedAttrs).length === 0) {\n    const { attrs: _unused, ...withoutAttrs } = mapped;\n    return withoutAttrs;\n  }\n\n  return mapped;\n}\n\n/**\n * Create an input element with attributes.\n *\n * @remarks\n * - `<input>` is a void element; it never receives text content. :contentReference[oaicite:15]{index=15}\n * - pkgn-sol defaults `type` to `\"text\"` unless overridden. :contentReference[oaicite:16]{index=16}\n * - Global attributes are applied via pkgn-sol's shared DOM helper, including security\n *   guards that block inline event handler attributes (e.g. `onclick`) and raw\n *   `style` attribute strings.\n *\n * @param attrs - Optional attributes to apply.\n * @returns The created `<input>` element.\n *\n * @example\n * ```ts\n * import { createInput } from \"@lnpg/pkgn-sol/elements/form/input\";\n *\n * const email = createInput({\n *   type: \"email\",\n *   name: \"email\",\n *   autoComplete: \"email\",\n *   inputMode: \"email\",\n * });\n * ```\n *\n * @category DOM\n */\nexport function createInput(attrs?: InputAttrs): ElementOf<typeof INPUT_TAG> {\n  return createVoidElement(INPUT_TAG, toGlobalAttrs(attrs));\n}\n\n/**\n * Enhance input elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceInputs(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for input.\n  void root;\n}\n"],"mappings":";;;;;;;IA+Ia,IAAY,SAOZ,IAAiB;AAwN9B,SAAS,EAAc,GAAiC;CACtD,IAAM,EACJ,SACA,SACA,SACA,UACA,gBACA,aACA,aACA,aACA,aACA,YACA,QACA,QACA,SACA,cACA,cACA,YACA,SACA,iBACA,cACA,SACA,SACA,eACA,gBACA,eACA,mBACA,eACA,QACA,QACA,UACA,WACA,WACA,YACA,cACA,iBACA,kBACA,wBACA,GAAG,MACD,KAAS,EAAE,EAET,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAElE,KAAc,GAAa,MAAmC;EAC9D,MAAM,KAAA,MACN,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;;CAgDrB,AA5CA,EAAW,QAAQ,KAAQ,OAAO,EAElC,EAAW,QAAQ,EAAK,EACxB,EAAW,SAAS,EAAM,EAC1B,EAAW,eAAe,EAAY,EACtC,EAAW,OAAO,EAAI,EACtB,EAAW,OAAO,EAAI,EACtB,EAAW,QAAQ,EAAK,EACxB,EAAW,aAAa,OAAO,KAAc,WAAW,IAAY,KAAA,EAAU,EAC9E,EAAW,aAAa,OAAO,KAAc,WAAW,IAAY,KAAA,EAAU,EAC9E,EAAW,WAAW,EAAQ,EAC9B,EAAW,QAAQ,OAAO,KAAS,WAAW,IAAO,KAAA,EAAU,EAC/D,EAAW,gBAAgB,EAAa,EACxC,EAAW,QAAQ,EAAK,EACxB,EAAW,QAAQ,EAAK,EAExB,EAAW,cAAc,EAAW,EACpC,EAAW,eAAe,EAAY,EACtC,EAAW,cAAc,EAAW,EACpC,EAAW,cAAc,EAAW,EAEpC,EAAW,OAAO,EAAI,EACtB,EAAW,OAAO,EAAI,EACtB,EAAW,SAAS,OAAO,KAAU,WAAW,IAAQ,KAAA,EAAU,EAClE,EAAW,UAAU,OAAO,KAAW,WAAW,IAAS,KAAA,EAAU,EAErE,EAAW,UAAU,EAAO,EAC5B,EAAW,aAAa,EAAU,EAClC,EAAW,gBAAgB,EAAa,EAExC,EAAW,iBAAiB,EAAc,EAC1C,EAAW,uBAAuB,EAAoB,EAGlD,MAAa,MAAM,EAAW,YAAY,GAAG,EAC7C,MAAa,MAAM,EAAW,YAAY,GAAG,EAC7C,MAAa,MAAM,EAAW,YAAY,GAAG,EAC7C,MAAa,MAAM,EAAW,YAAY,GAAG,EAC7C,MAAY,MAAM,EAAW,WAAW,GAAG,EAC3C,MAAc,MAAM,EAAW,aAAa,GAAG,EAC/C,MAAmB,MAAM,EAAW,kBAAkB,GAAG,EAEzD,MAAY,MAAM,EAAW,WAAW,GAAG,EAC3C,MAAY,UAAQ,EAAW,WAAW,OAAO,EACjD,MAAY,iBAAe,EAAW,WAAW,cAAc;CAEnE,IAAM,IAAsB;EAAE,GAAG;EAAM,OAAO;EAAa,EAErD,IAA+C,EAAE;CAWvD,IAVI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,UAG7D,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAO,OAAO,IAGZ,OAAO,KAAK,EAAY,CAAC,WAAW,GAAG;EACzC,IAAM,EAAE,OAAO,GAAS,GAAG,MAAiB;EAC5C,OAAO;;CAGT,OAAO;;AA8BT,SAAgB,EAAY,GAAiD;CAC3E,OAAO,EAAkB,GAAW,EAAc,EAAM,CAAC;;AAa3D,SAAgB,EAAc,IAAmB,UAAgB"}

package/dist/esm/elements/form/label/label.js

@@ -0,0 +1,29 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/label/index.ts
+var n = /* @__PURE__ */ e({
+	LABEL_SELECTOR: () => i,
+	LABEL_TAG: () => r,
+	createLabel: () => o,
+	enhanceLabels: () => s
+}), r = "label", i = "label";
+function a(e) {
+	if (!e) return;
+	let { aria: t, htmlFor: n, ...r } = e, i = { ...r };
+	if (typeof n == "string" && n.length > 0 && (i.attrs = {
+		...i.attrs ?? {},
+		for: n
+	}), !t) return i;
+	let a = {};
+	return typeof t.label == "string" && (a.label = t.label), typeof t.labelledby == "string" && (a.labelledby = t.labelledby), typeof t.hidden == "boolean" && (a.hidden = t.hidden), Object.keys(a).length > 0 ? {
+		...i,
+		aria: a
+	} : i;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as LABEL_SELECTOR, r as LABEL_TAG, o as createLabel, s as enhanceLabels, n as t };
+
+//# sourceMappingURL=label.js.map

package/dist/esm/elements/form/label/label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label.js","names":[],"sources":["../../../../../src/elements/form/label/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Label element helpers.\n *\n * @remarks\n * The label element (`<label>`) represents a caption in a user interface and is\n * primarily used to provide an accessible name for a form control.\n *\n * Best-practice guidance:\n * - Always associate labels with their control:\n *   - Prefer an explicit association using `for` (pkgn-sol: {@link LabelAttrs.htmlFor})\n *     that matches the control's `id`.\n *   - Alternatively, wrap the control inside the `<label>` element.\n * - Do not rely on placeholder text as a replacement for a visible label.\n * - Keep label text concise and descriptive.\n *\n * Attributes:\n * - `<label>` supports global attributes.\n * - The only relevant label-specific content attribute is `for`, reflected in\n *   JavaScript as `htmlFor`. (The `label` element does not have a `form` content\n *   attribute; it has a `form` *IDL attribute* derived from the associated control.)\n *\n * Security:\n * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which\n *   block inline event handler attributes (e.g. `onclick`) and raw `style`\n *   attribute injection (use the `style` object field instead).\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs (e.g. `lable`).\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for label.\n *\n * @category Constants\n */\nexport const LABEL_TAG = 'label' as const;\n\n/**\n * A CSS selector targeting label elements.\n *\n * @category Constants\n */\nexport const LABEL_SELECTOR = 'label';\n\n/**\n * Attribute bag for label creation/enhancement.\n *\n * @remarks\n * Labels accept standard HTML global attributes.\n *\n * Label-specific:\n * - {@link LabelAttrs.htmlFor} maps to the `for` attribute, associating the label\n *   with the control whose `id` matches.\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type LabelAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Associate the label with a labelable form control by ID.\n   *\n   * @remarks\n   * This maps to the `for` content attribute.\n   *\n   * The value should match the `id` of a labelable element in the same document\n   * tree (e.g. `<input id=\"email\">` pairs with `<label for=\"email\">`).\n   */\n  htmlFor?: string;\n};\n\n/**\n * Normalize {@link LabelAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The label attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: LabelAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, htmlFor, ...rest } = attrs;\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  if (typeof htmlFor === 'string' && htmlFor.length > 0) {\n    mapped.attrs = {\n      ...(mapped.attrs ?? {}),\n      for: htmlFor,\n    };\n  }\n\n  if (!aria) return mapped;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (typeof aria.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n  // Only attach `aria` if something was actually defined.\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n\n  return hasMappedAria ? { ...mapped, aria: mappedAria } : mapped;\n}\n\n/**\n * Create a label element with optional text content and attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the label.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<label>` element.\n *\n * @example\n * ```ts\n * import { createLabel } from \"@lnpg/pkgn-sol/elements/form/label\";\n *\n * const label = createLabel(\"Email address\", { htmlFor: \"email\" });\n * ```\n *\n * @category DOM\n */\nexport function createLabel(text?: string, attrs?: LabelAttrs): ElementOf<typeof LABEL_TAG> {\n  return createElement(LABEL_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance label elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceLabels(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for label.\n  void root;\n}\n"],"mappings":";;;;;;;IAoEa,IAAY,SAOZ,IAAiB;AA2C9B,SAAS,EAAc,GAA6C;CAClE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,YAAS,GAAG,MAAS,GAE7B,IAAsB,EAAE,GAAG,GAAM;CASvC,IAPI,OAAO,KAAY,YAAY,EAAQ,SAAS,MAClD,EAAO,QAAQ;EACb,GAAI,EAAO,SAAS,EAAE;EACtB,KAAK;EACN,GAGC,CAAC,GAAM,OAAO;CAElB,IAAM,IAA+C,EAAE;CASvD,OAPI,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,SAGzC,OAAO,KAAK,EAAW,CAAC,SAAS,IAEhC;EAAE,GAAG;EAAQ,MAAM;EAAY,GAAG;;AAyB3D,SAAgB,EAAY,GAAe,GAAiD;CAC1F,OAAO,EAAc,GAAW,EAAc,EAAM,EAAE,EAAK;;AAqB7D,SAAgB,EAAc,IAAmB,UAAgB"}

package/dist/esm/elements/form/legend/legend.js

@@ -0,0 +1,26 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/legend/index.ts
+var n = /* @__PURE__ */ e({
+	LEGEND_SELECTOR: () => i,
+	LEGEND_TAG: () => r,
+	createLegend: () => o,
+	enhanceLegends: () => s
+}), r = "legend", i = "legend";
+function a(e) {
+	if (!e) return;
+	let { aria: t, ...n } = e;
+	if (!t) return n;
+	let r = {};
+	return typeof t.label == "string" && (r.label = t.label), typeof t.labelledby == "string" && (r.labelledby = t.labelledby), typeof t.hidden == "boolean" && (r.hidden = t.hidden), Object.keys(r).length > 0 ? {
+		...n,
+		aria: r
+	} : n;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as LEGEND_SELECTOR, r as LEGEND_TAG, o as createLegend, s as enhanceLegends, n as t };
+
+//# sourceMappingURL=legend.js.map

package/dist/esm/elements/form/legend/legend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.js","names":[],"sources":["../../../../../src/elements/form/legend/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Legend element helpers.\n *\n * @remarks\n * The legend element (`<legend>`) represents a caption for the content of its\n * parent `<fieldset>`. It is commonly used to label groups of related form\n * controls (e.g. radio-button groups), improving clarity and accessibility.\n *\n * Best-practice guidance:\n * - Use `<legend>` as the first child of a `<fieldset>` to label the group.\n * - Keep legend text concise and meaningful (it is typically announced with\n *   grouped controls by assistive technologies).\n * - Avoid using `<legend>` purely for layout; use CSS for styling/spacing.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create `<legend>` elements in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend\n * @see https://www.w3.org/WAI/tutorials/forms/grouping/\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for legend.\n *\n * @category Constants\n */\nexport const LEGEND_TAG = 'legend' as const;\n\n/**\n * A CSS selector targeting legend elements.\n *\n * @category Constants\n */\nexport const LEGEND_SELECTOR = 'legend';\n\n/**\n * Attribute bag for legend creation/enhancement.\n *\n * @remarks\n * Legend elements accept standard HTML global attributes.\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type LegendAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Normalize {@link LegendAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The legend attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: LegendAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, ...rest } = attrs;\n\n  if (!aria) return rest;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (typeof aria.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n  // Only attach `aria` if something was actually defined.\n  const hasMapped = Object.keys(mappedAria).length > 0;\n\n  return hasMapped ? { ...rest, aria: mappedAria } : rest;\n}\n\n/**\n * Create a legend element with optional text content and global attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the legend.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<legend>` element.\n *\n * @example\n * ```ts\n * import { createLegend } from \"@lnpg/pkgn-sol/elements/form/legend\";\n *\n * const legend = createLegend(\"Delivery address\");\n * ```\n *\n * @category DOM\n */\nexport function createLegend(text?: string, attrs?: LegendAttrs): ElementOf<typeof LEGEND_TAG> {\n  return createElement(LEGEND_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance legend elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceLegends(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for legend.\n  void root;\n}\n"],"mappings":";;;;;;;IAgEa,IAAa,UAOb,IAAkB;AA4B/B,SAAS,EAAc,GAA8C;CACnE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,GAAG,MAAS;CAE1B,IAAI,CAAC,GAAM,OAAO;CAElB,IAAM,IAA+C,EAAE;CASvD,OAPI,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,SAG7C,OAAO,KAAK,EAAW,CAAC,SAAS,IAEhC;EAAE,GAAG;EAAM,MAAM;EAAY,GAAG;;AAyBrD,SAAgB,EAAa,GAAe,GAAmD;CAC7F,OAAO,EAAc,GAAY,EAAc,EAAM,EAAE,EAAK;;AAqB9D,SAAgB,EAAe,IAAmB,UAAgB"}

package/dist/esm/elements/form/meter/meter.js

@@ -0,0 +1,29 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/meter/index.ts
+var n = /* @__PURE__ */ e({
+	METER_SELECTOR: () => i,
+	METER_TAG: () => r,
+	createMeter: () => o,
+	enhanceMeters: () => s
+}), r = "meter", i = "meter";
+function a(e) {
+	let { aria: t, value: n, min: r, max: i, low: a, high: o, optimum: s, form: c, ...l } = e ?? {}, u = { ...l.attrs ?? {} }, d = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(u, e) || (u[e] = t));
+	};
+	d("min", typeof r == "number" ? r : 0), d("max", typeof i == "number" ? i : 1), d("value", typeof n == "number" ? n : 0), d("low", typeof a == "number" ? a : void 0), d("high", typeof o == "number" ? o : void 0), d("optimum", typeof s == "number" ? s : void 0), d("form", typeof c == "string" ? c : void 0);
+	let f = {};
+	t && (typeof t.label == "string" && (f.label = t.label), typeof t.labelledby == "string" && (f.labelledby = t.labelledby), typeof t.hidden == "boolean" && (f.hidden = t.hidden));
+	let p = {
+		...l,
+		attrs: u
+	};
+	return Object.keys(f).length > 0 && (p.aria = f), p;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as METER_SELECTOR, r as METER_TAG, o as createMeter, s as enhanceMeters, n as t };
+
+//# sourceMappingURL=meter.js.map

package/dist/esm/elements/form/meter/meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.js","names":[],"sources":["../../../../../src/elements/form/meter/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Meter element helpers.\n *\n * @remarks\n * The meter element (`<meter>`) represents a scalar measurement within a known range,\n * or a fractional value.\n *\n * Best-practice guidance:\n * - Use `<meter>` for a known-range measurement (e.g. disk usage, score, relevance).\n * - Do NOT use `<meter>` for task progress. Use `<progress>` for progress indication.\n * - Provide fallback text content for user agents that don't render `<meter>`.\n * - Define `min`/`max` if your `value` is not in the default 0..1 range.\n * - Use `low`/`high`/`optimum` only when you actually want \"good/bad\" semantics.\n *\n * pkgn-sol notes:\n * - This module is framework-agnostic and has no side effects.\n * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:\n *   - inline event handler attributes (e.g. `onclick`)\n *   - raw `style` attribute injection (use the `style` object instead)\n * - Text passed to factories is assigned via `textContent` (never `innerHTML`).\n *\n * References:\n * - MDN: `<meter>` element\n * - WHATWG HTML: meter attributes and behavior\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for meter.\n *\n * @category Constants\n */\nexport const METER_TAG = 'meter' as const;\n\n/**\n * A CSS selector targeting meter elements.\n *\n * @category Constants\n */\nexport const METER_SELECTOR = 'meter';\n\n/**\n * Attribute bag for meter creation/enhancement.\n *\n * @remarks\n * Supported element-specific attributes:\n * - `value`, `min`, `max`, `low`, `high`, `optimum`\n * - `form` (associates the meter with a form owner by ID)\n *\n * Defaults (documented platform behavior):\n * - `min` defaults to `0` when omitted\n * - `max` defaults to `1` when omitted\n * - `value` defaults to `0` when omitted or malformed\n *\n * pkgn-sol applies these defaults as explicit attributes to keep output predictable\n * and testable even in node-based DOM shims.\n *\n * @category Attributes\n */\nexport type MeterAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Current numeric value.\n   *\n   * @remarks\n   * Should be within `[min, max]` when those are defined.\n   */\n  value?: number;\n\n  /**\n   * Lower numeric bound of the range. Defaults to `0`.\n   */\n  min?: number;\n\n  /**\n   * Upper numeric bound of the range. Defaults to `1`.\n   */\n  max?: number;\n\n  /**\n   * Upper numeric bound of the low end of the range.\n   */\n  low?: number;\n\n  /**\n   * Lower numeric bound of the high end of the range.\n   */\n  high?: number;\n\n  /**\n   * The optimal value within the range.\n   */\n  optimum?: number;\n\n  /**\n   * Associates the meter with a form element by ID.\n   *\n   * @remarks\n   * Mirrors the HTML `form` attribute used by form-associated elements.\n   */\n  form?: string;\n\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n};\n\n/**\n * Normalize {@link MeterAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @remarks\n * - Preserves caller-provided `attrs` escape hatch (still validated by `dom.ts`).\n * - Element-specific attributes are merged into `attrs` without overwriting keys\n *   explicitly provided by the caller.\n * - Applies predictable defaults for `min`, `max`, and `value` even if callers\n *   omit the `attrs` bag entirely.\n *\n * @param attrs - The meter attributes.\n * @returns A {@link GlobalAttrs} object.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: MeterAttrs): GlobalAttrs {\n  const a: MeterAttrs = attrs ?? {};\n\n  const { aria, value, min, max, low, high, optimum, form, ...rest } = a;\n\n  // Start with any caller-provided attrs escape hatch (it is still validated by dom.ts).\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  // Helper: only set if caller didn't already set the raw attribute explicitly.\n  const setIfUnset = (key: string, v: AttrValue | undefined): void => {\n    if (v === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = v;\n  };\n\n  // Defaults: make output deterministic even when attrs is omitted.\n  setIfUnset('min', typeof min === 'number' ? min : 0);\n  setIfUnset('max', typeof max === 'number' ? max : 1);\n  setIfUnset('value', typeof value === 'number' ? value : 0);\n\n  // Optional meter semantics.\n  setIfUnset('low', typeof low === 'number' ? low : undefined);\n  setIfUnset('high', typeof high === 'number' ? high : undefined);\n  setIfUnset('optimum', typeof optimum === 'number' ? optimum : undefined);\n\n  // Form association.\n  setIfUnset('form', typeof form === 'string' ? form : undefined);\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const next: GlobalAttrs = { ...rest, attrs: mergedAttrs };\n\n  if (Object.keys(mappedAria).length > 0) {\n    next.aria = mappedAria;\n  }\n\n  return next;\n}\n\n/**\n * Create a meter element with optional fallback text and attributes.\n *\n * @remarks\n * - Fallback text is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional fallback text for user agents that don't render `<meter>`.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<meter>` element.\n *\n * @category DOM\n */\nexport function createMeter(text?: string, attrs?: MeterAttrs): ElementOf<typeof METER_TAG> {\n  return createElement(METER_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance meter elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceMeters(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for meter.\n  void root;\n}\n"],"mappings":";;;;;;;IAgEa,IAAY,SAOZ,IAAiB;AAmF9B,SAAS,EAAc,GAAiC;CAGtD,IAAM,EAAE,SAAM,UAAO,QAAK,QAAK,QAAK,SAAM,YAAS,SAAM,GAAG,MAFtC,KAAS,EAAE,EAK3B,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAGlE,KAAc,GAAa,MAAmC;EAC9D,MAAM,KAAA,MACN,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;;CAcrB,AAVA,EAAW,OAAO,OAAO,KAAQ,WAAW,IAAM,EAAE,EACpD,EAAW,OAAO,OAAO,KAAQ,WAAW,IAAM,EAAE,EACpD,EAAW,SAAS,OAAO,KAAU,WAAW,IAAQ,EAAE,EAG1D,EAAW,OAAO,OAAO,KAAQ,WAAW,IAAM,KAAA,EAAU,EAC5D,EAAW,QAAQ,OAAO,KAAS,WAAW,IAAO,KAAA,EAAU,EAC/D,EAAW,WAAW,OAAO,KAAY,WAAW,IAAU,KAAA,EAAU,EAGxE,EAAW,QAAQ,OAAO,KAAS,WAAW,IAAO,KAAA,EAAU;CAE/D,IAAM,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAoB;EAAE,GAAG;EAAM,OAAO;EAAa;CAMzD,OAJI,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAK,OAAO,IAGP;;AAkBT,SAAgB,EAAY,GAAe,GAAiD;CAC1F,OAAO,EAAc,GAAW,EAAc,EAAM,EAAE,EAAK;;AAa7D,SAAgB,EAAc,IAAmB,UAAgB"}

package/dist/esm/elements/form/optgroup/optgroup.js

@@ -0,0 +1,24 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/optgroup/index.ts
+var n = /* @__PURE__ */ e({
+	OPTGROUP_SELECTOR: () => i,
+	OPTGROUP_TAG: () => r,
+	createOptgroup: () => o,
+	enhanceOptgroups: () => s
+}), r = "optgroup", i = "optgroup";
+function a(e, t) {
+	let { aria: n, disabled: r, ...i } = t ?? {}, a = {};
+	n && (typeof n.label == "string" && (a.label = n.label), typeof n.labelledby == "string" && (a.labelledby = n.labelledby), typeof n.hidden == "boolean" && (a.hidden = n.hidden));
+	let o = { ...i.attrs ?? {} };
+	Object.prototype.hasOwnProperty.call(o, "label") || (o.label = e), r === !0 && !Object.prototype.hasOwnProperty.call(o, "disabled") && (o.disabled = "");
+	let s = { ...i };
+	return Object.keys(o).length > 0 && (s.attrs = o), Object.keys(a).length > 0 && (s.aria = a), s;
+}
+function o(e, n) {
+	return t(r, a(e, n));
+}
+function s(e = document) {}
+//#endregion
+export { i as OPTGROUP_SELECTOR, r as OPTGROUP_TAG, o as createOptgroup, s as enhanceOptgroups, n as t };
+
+//# sourceMappingURL=optgroup.js.map

package/dist/esm/elements/form/optgroup/optgroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optgroup.js","names":[],"sources":["../../../../../src/elements/form/optgroup/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Optgroup element helpers.\n *\n * @remarks\n * The optgroup element (`<optgroup>`) groups related `<option>` elements within\n * a `<select>`, allowing user agents to present grouped choices with a label.\n * :contentReference[oaicite:3]{index=3}\n *\n * Best-practice guidance:\n * - Always provide a meaningful `label`. MDN notes this attribute is mandatory\n *   when the element is used. pkgn-sol enforces this by requiring `label` when\n *   creating an optgroup. :contentReference[oaicite:4]{index=4}\n * - Use `disabled` to disable all options within the group when appropriate.\n * :contentReference[oaicite:5]{index=5}\n * - Prefer native semantics; avoid ARIA where native semantics already apply.\n *\n * pkgn-sol-specific conventions:\n * - Requires `label` at creation time to avoid invalid/anonymous optgroups.\n * - Applies global attributes via pkgn-sol's hardened DOM helpers (`dom.ts`), which\n *   block inline event handler attributes (e.g. `onclick`) and the raw `style`\n *   attribute string.\n * - Supports a small structured ARIA input to reduce typo-based ARIA bugs.\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset mapped into {@link GlobalAttrs.aria}.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for option groups.\n *\n * @category Constants\n */\nexport const OPTGROUP_TAG = 'optgroup' as const;\n\n/**\n * A CSS selector targeting optgroup elements.\n *\n * @category Constants\n */\nexport const OPTGROUP_SELECTOR = 'optgroup';\n\n/**\n * Attribute bag for optgroup creation/enhancement.\n *\n * @remarks\n * `<optgroup>` accepts global attributes plus:\n * - `disabled` (boolean attribute)\n *\n * The `label` attribute is mandatory for meaningful use. pkgn-sol requires the label\n * as a separate argument in {@link createOptgroup}. :contentReference[oaicite:6]{index=6}\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, mapped into\n * {@link GlobalAttrs.aria}.\n *\n * @category Attributes\n */\nexport type OptgroupAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Disables the option group when true.\n   *\n   * @remarks\n   * When disabled, none of the options in the group are selectable. :contentReference[oaicite:7]{index=7}\n   */\n  disabled?: boolean;\n};\n\n/**\n * Normalize {@link OptgroupAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param label - The required optgroup label, mapped to the `label` attribute.\n * @param attrs - The optgroup attributes.\n * @returns A {@link GlobalAttrs} object containing mapped attributes.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(label: string, attrs?: OptgroupAttrs): GlobalAttrs {\n  const { aria, disabled, ...rest } = attrs ?? {};\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const mergedAttrs: NonNullable<GlobalAttrs['attrs']> = { ...(rest.attrs ?? {}) };\n\n  // Always set the mandatory label attribute unless explicitly overridden via raw attrs.\n  if (!Object.prototype.hasOwnProperty.call(mergedAttrs, 'label')) {\n    mergedAttrs.label = label;\n  }\n\n  // Boolean attribute by presence when true.\n  if (disabled === true && !Object.prototype.hasOwnProperty.call(mergedAttrs, 'disabled')) {\n    mergedAttrs.disabled = '';\n  }\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  if (Object.keys(mergedAttrs).length > 0) mapped.attrs = mergedAttrs;\n\n  if (Object.keys(mappedAria).length > 0) {\n    mapped.aria = mappedAria;\n  }\n\n  return mapped;\n}\n\n/**\n * Create an optgroup element with a required label and optional attributes.\n *\n * @remarks\n * - The label is mapped to the `label` attribute (required for meaningful use). :contentReference[oaicite:8]{index=8}\n * - Global attributes are applied via pkgn-sol's shared DOM helper, including security\n *   guards that block inline event handler attributes (e.g. `onclick`) and raw\n *   `style` attribute strings.\n *\n * @param label - The optgroup label shown by the user agent.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<optgroup>` element.\n *\n * @example\n * ```ts\n * import { createOptgroup } from \"@lnpg/pkgn-sol/elements/form/optgroup\";\n *\n * const g = createOptgroup(\"Fruits\", { disabled: false });\n * ```\n *\n * @category DOM\n */\nexport function createOptgroup(\n  label: string,\n  attrs?: OptgroupAttrs,\n): ElementOf<typeof OPTGROUP_TAG> {\n  return createElement(OPTGROUP_TAG, toGlobalAttrs(label, attrs));\n}\n\n/**\n * Enhance optgroup elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceOptgroups(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for optgroup.\n  void root;\n}\n"],"mappings":";;;;;;;IA8Da,IAAe,YAOf,IAAoB;AAyCjC,SAAS,EAAc,GAAe,GAAoC;CACxE,IAAM,EAAE,SAAM,aAAU,GAAG,MAAS,KAAS,EAAE,EAEzC,IAA+C,EAAE;CAEvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAiD,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG;CAQhF,AALK,OAAO,UAAU,eAAe,KAAK,GAAa,QAAQ,KAC7D,EAAY,QAAQ,IAIlB,MAAa,MAAQ,CAAC,OAAO,UAAU,eAAe,KAAK,GAAa,WAAW,KACrF,EAAY,WAAW;CAGzB,IAAM,IAAsB,EAAE,GAAG,GAAM;CAQvC,OANI,OAAO,KAAK,EAAY,CAAC,SAAS,MAAG,EAAO,QAAQ,IAEpD,OAAO,KAAK,EAAW,CAAC,SAAS,MACnC,EAAO,OAAO,IAGT;;AAyBT,SAAgB,EACd,GACA,GACgC;CAChC,OAAO,EAAc,GAAc,EAAc,GAAO,EAAM,CAAC;;AAajE,SAAgB,EAAiB,IAAmB,UAAgB"}

package/dist/esm/elements/form/option/option.js

@@ -0,0 +1,26 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/option/index.ts
+var n = /* @__PURE__ */ e({
+	OPTION_SELECTOR: () => i,
+	OPTION_TAG: () => r,
+	createOption: () => o,
+	enhanceOptions: () => s
+}), r = "option", i = "option";
+function a(e) {
+	if (!e) return;
+	let { aria: t, value: n, label: r, disabled: i, selected: a, ...o } = e, s = { ...o }, c = { ...s.attrs ?? {} };
+	if (typeof n == "string" && (c.value = n), typeof r == "string" && (c.label = r), i === !0 && (c.disabled = !0), a === !0 && (c.selected = !0), Object.keys(c).length > 0 && (s.attrs = c), !t) return s;
+	let l = {};
+	return typeof t.label == "string" && (l.label = t.label), typeof t.labelledby == "string" && (l.labelledby = t.labelledby), typeof t.hidden == "boolean" && (l.hidden = t.hidden), Object.keys(l).length > 0 ? {
+		...s,
+		aria: l
+	} : s;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as OPTION_SELECTOR, r as OPTION_TAG, o as createOption, s as enhanceOptions, n as t };
+
+//# sourceMappingURL=option.js.map

package/dist/esm/elements/form/option/option.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"option.js","names":[],"sources":["../../../../../src/elements/form/option/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Option element helpers.\n *\n * @remarks\n * The option element (`<option>`) defines an item within a `<select>`, `<optgroup>`,\n * or `<datalist>` element.\n *\n * Best-practice guidance:\n * - Prefer providing a `value` for form submission semantics. If `value` is omitted,\n *   the option's value typically falls back to its text content.\n * - Use `label` when you need a shorter label for UI display or accessibility hints,\n *   but keep the option text clear and readable.\n * - Use `disabled` to prevent selection of an option (or to mark placeholders as\n *   unavailable).\n * - Use `selected` to mark the default selection in a `<select>` (usually one\n *   option should be selected by default).\n *\n * Attributes:\n * - `value` (string): the value submitted/used when selected.\n * - `label` (string): a label for the option.\n * - `disabled` (boolean): whether the option is unavailable.\n * - `selected` (boolean): whether the option is selected by default.\n *\n * Security:\n * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which\n *   block inline event handler attributes (e.g. `onclick`) and raw `style`\n *   attribute injection (use the `style` object field instead).\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/option\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs (e.g. `lable`).\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for option.\n *\n * @category Constants\n */\nexport const OPTION_TAG = 'option' as const;\n\n/**\n * A CSS selector targeting option elements.\n *\n * @category Constants\n */\nexport const OPTION_SELECTOR = 'option';\n\n/**\n * Attribute bag for option creation/enhancement.\n *\n * @remarks\n * Options accept standard HTML global attributes plus a small set of option-specific\n * content attributes.\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type OptionAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * The option value.\n   *\n   * @remarks\n   * If omitted, user agents commonly derive a value from the option's text.\n   */\n  value?: string;\n\n  /**\n   * A label for the option.\n   *\n   * @remarks\n   * When present, this may be used by user agents as the option's label instead\n   * of the text content in certain contexts.\n   */\n  label?: string;\n\n  /**\n   * Whether the option is disabled.\n   */\n  disabled?: boolean;\n\n  /**\n   * Whether the option is selected by default.\n   *\n   * @remarks\n   * For `<select>`, `selected` commonly indicates the default selected option on\n   * initial load. If multiple options are marked selected, browser behavior varies;\n   * prefer a single default selection unless using a multi-select.\n   */\n  selected?: boolean;\n};\n\n/**\n * Normalize {@link OptionAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The option attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: OptionAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, value, label, disabled, selected, ...rest } = attrs;\n\n  const mapped: GlobalAttrs = { ...rest };\n\n  const extra: NonNullable<GlobalAttrs['attrs']> = { ...(mapped.attrs ?? {}) };\n\n  if (typeof value === 'string') extra.value = value;\n  if (typeof label === 'string') extra.label = label;\n\n  if (disabled === true) extra.disabled = true;\n  if (selected === true) extra.selected = true;\n\n  // Only attach `attrs` if something was actually defined/added.\n  if (Object.keys(extra).length > 0) {\n    mapped.attrs = extra;\n  }\n\n  if (!aria) return mapped;\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n\n  if (typeof aria.label === 'string') mappedAria.label = aria.label;\n  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n\n  return hasMappedAria ? { ...mapped, aria: mappedAria } : mapped;\n}\n\n/**\n * Create an option element with optional text content and attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes and escape-hatch attributes are applied via pkgn-sol's shared\n *   DOM helper, including security guards that block inline event handler\n *   attributes (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the option.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<option>` element.\n *\n * @example\n * ```ts\n * import { createOption } from \"@lnpg/pkgn-sol/elements/form/option\";\n *\n * const opt = createOption(\"United Kingdom\", { value: \"UK\" });\n * ```\n *\n * @category DOM\n */\nexport function createOption(text?: string, attrs?: OptionAttrs): ElementOf<typeof OPTION_TAG> {\n  return createElement(OPTION_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance option elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceOptions(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for option.\n  void root;\n}\n"],"mappings":";;;;;;;IAqEa,IAAa,UAOb,IAAkB;AA6D/B,SAAS,EAAc,GAA8C;CACnE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,UAAO,UAAO,aAAU,aAAU,GAAG,MAAS,GAEtD,IAAsB,EAAE,GAAG,GAAM,EAEjC,IAA2C,EAAE,GAAI,EAAO,SAAS,EAAE,EAAG;CAa5E,IAXI,OAAO,KAAU,aAAU,EAAM,QAAQ,IACzC,OAAO,KAAU,aAAU,EAAM,QAAQ,IAEzC,MAAa,OAAM,EAAM,WAAW,KACpC,MAAa,OAAM,EAAM,WAAW,KAGpC,OAAO,KAAK,EAAM,CAAC,SAAS,MAC9B,EAAO,QAAQ,IAGb,CAAC,GAAM,OAAO;CAElB,IAAM,IAA+C,EAAE;CAQvD,OANI,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK,SAEzC,OAAO,KAAK,EAAW,CAAC,SAAS,IAEhC;EAAE,GAAG;EAAQ,MAAM;EAAY,GAAG;;AAyB3D,SAAgB,EAAa,GAAe,GAAmD;CAC7F,OAAO,EAAc,GAAY,EAAc,EAAM,EAAE,EAAK;;AAqB9D,SAAgB,EAAe,IAAmB,UAAgB"}

package/dist/esm/elements/form/output/output.js

@@ -0,0 +1,27 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/output/index.ts
+var n = /* @__PURE__ */ e({
+	OUTPUT_SELECTOR: () => i,
+	OUTPUT_TAG: () => r,
+	createOutput: () => o,
+	enhanceOutputs: () => s
+}), r = "output", i = "output";
+function a(e) {
+	if (!e) return;
+	let { aria: t, for: n, form: r, name: i, ...a } = e, o = { ...a.attrs ?? {} }, s = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(o, e) || (o[e] = t));
+	};
+	s("for", n), s("form", r), s("name", i);
+	let c = {};
+	t && (typeof t.label == "string" && (c.label = t.label), typeof t.labelledby == "string" && (c.labelledby = t.labelledby), typeof t.hidden == "boolean" && (c.hidden = t.hidden));
+	let l = Object.keys(o).length > 0, u = Object.keys(c).length > 0, d = { ...a };
+	return l && (d.attrs = o), u && (d.aria = c), d;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as OUTPUT_SELECTOR, r as OUTPUT_TAG, o as createOutput, s as enhanceOutputs, n as t };
+
+//# sourceMappingURL=output.js.map

package/dist/esm/elements/form/output/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","names":[],"sources":["../../../../../src/elements/form/output/index.ts"],"sourcesContent":["/**\n * pkgn-sol Design Foundation: Output element helpers.\n *\n * @remarks\n * The output element (`<output>`) represents the result of a calculation or a\n * user action, commonly used in forms to display derived values without\n * requiring focus changes.\n *\n * Best-practice guidance:\n * - Use `<output>` for computed results derived from form controls.\n * - Use the `for` attribute to associate the output with the control(s) whose\n *   values it reflects (space-separated list of element IDs).\n * - Prefer semantic HTML and native behavior over ARIA. Many browsers treat\n *   `<output>` as an ARIA live region, so updating its text may be announced by\n *   assistive technologies without moving focus.\n *\n * This module provides small, framework-agnostic helpers so consumers can:\n * - create outputs in vanilla JS/TS without templates\n * - apply consistent global attributes safely\n * - use a stable \"enhancement\" hook if pkgn-sol ever needs runtime behavior\n *\n * This module has no side effects and does not mutate the DOM unless you call\n * its functions.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/output\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for\n * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/form\n *\n * @module\n * @category Elements\n */\n\nimport { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';\n\n/**\n * Structured ARIA input supported by pkgn-sol element factories.\n *\n * @remarks\n * This is intentionally a small, typed subset that covers common cases and\n * prevents typo-based ARIA bugs.\n *\n * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.\n *\n * @category Attributes\n */\nexport type StructuredAria = {\n  /**\n   * Accessible label, mapped to `aria-label`.\n   */\n  label?: string;\n\n  /**\n   * ID reference to the labelling element(s), mapped to `aria-labelledby`.\n   */\n  labelledby?: string;\n\n  /**\n   * Decorative/hidden hint, mapped to `aria-hidden`.\n   */\n  hidden?: boolean;\n};\n\n/**\n * The semantic tag name for output.\n *\n * @category Constants\n */\nexport const OUTPUT_TAG = 'output' as const;\n\n/**\n * A CSS selector targeting output elements.\n *\n * @category Constants\n */\nexport const OUTPUT_SELECTOR = 'output';\n\n/**\n * Attribute bag for output creation/enhancement.\n *\n * @remarks\n * Output accepts standard HTML global attributes plus output-specific\n * attributes (`for`, `form`, `name`).\n *\n * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is\n * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.\n *\n * @category Attributes\n */\nexport type OutputAttrs = Omit<GlobalAttrs, 'aria'> & {\n  /**\n   * Structured ARIA fields mapped into `aria-*` attributes.\n   */\n  aria?: StructuredAria;\n\n  /**\n   * Space-separated list of element IDs whose values contributed to the output.\n   *\n   * @remarks\n   * This maps to the `for` attribute (yes, the HTML attribute is literally\n   * called `for`).\n   */\n  for?: string;\n\n  /**\n   * Associates the output with a form element by ID, even if not a descendant.\n   */\n  form?: string;\n\n  /**\n   * Name of the output (useful in form-associated contexts).\n   */\n  name?: string;\n};\n\n/**\n * Normalize {@link OutputAttrs} into {@link GlobalAttrs} for `dom.ts`.\n *\n * @param attrs - The output attributes.\n * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.\n *\n * @category Internal\n */\nfunction toGlobalAttrs(attrs?: OutputAttrs): GlobalAttrs | undefined {\n  if (!attrs) return undefined;\n\n  const { aria, for: htmlFor, form, name, ...rest } = attrs;\n\n  // Start with any caller-provided attrs escape hatch (still validated by dom.ts).\n  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };\n\n  const setIfUnset = (key: string, value: AttrValue | undefined): void => {\n    if (value === undefined) return;\n    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;\n    mergedAttrs[key] = value;\n  };\n\n  setIfUnset('for', htmlFor);\n  setIfUnset('form', form);\n  setIfUnset('name', name);\n\n  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};\n  if (aria) {\n    if (typeof aria.label === 'string') mappedAria.label = aria.label;\n    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;\n    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;\n  }\n\n  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;\n  const hasMappedAria = Object.keys(mappedAria).length > 0;\n\n  const next: GlobalAttrs = { ...rest };\n  if (hasMergedAttrs) next.attrs = mergedAttrs;\n  if (hasMappedAria) next.aria = mappedAria;\n\n  return next;\n}\n\n/**\n * Create an output element with optional text content and attributes.\n *\n * @remarks\n * - Text content is assigned via `textContent` (never `innerHTML`).\n * - Global attributes are applied via pkgn-sol's shared DOM helper,\n *   including security guards that block inline event handler attributes\n *   (e.g. `onclick`) and raw `style` attribute strings.\n *\n * @param text - Optional text content for the output.\n * @param attrs - Optional attributes to apply.\n * @returns The created `<output>` element.\n *\n * @example\n * ```ts\n * import { createOutput } from \"@lnpg/pkgn-sol/elements/form/output\";\n *\n * const out = createOutput(\"0\", { name: \"result\", for: \"a b\" });\n * ```\n *\n * @category DOM\n */\nexport function createOutput(text?: string, attrs?: OutputAttrs): ElementOf<typeof OUTPUT_TAG> {\n  return createElement(OUTPUT_TAG, toGlobalAttrs(attrs), text);\n}\n\n/**\n * Enhance output elements within a given root.\n *\n * @remarks\n * This is intentionally a no-op in `0.1.0`.\n *\n * Why does it exist?\n * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)\n * - It allows future progressive enhancements without changing consumer code\n *\n * What it will never do:\n * - It will not inject styles (CSS remains the source of truth)\n * - It will not introduce framework-specific behavior\n *\n * @param root - The node to search within. Defaults to `document`.\n *\n * @category Enhancement\n */\nexport function enhanceOutputs(root: ParentNode = document): void {\n  // v0.1.0: no runtime behavior for output.\n  void root;\n}\n"],"mappings":";;;;;;;IAmEa,IAAa,UAOb,IAAkB;AAgD/B,SAAS,EAAc,GAA8C;CACnE,IAAI,CAAC,GAAO;CAEZ,IAAM,EAAE,SAAM,KAAK,GAAS,SAAM,SAAM,GAAG,MAAS,GAG9C,IAAyC,EAAE,GAAI,EAAK,SAAS,EAAE,EAAG,EAElE,KAAc,GAAa,MAAuC;EAClE,MAAU,KAAA,MACV,OAAO,UAAU,eAAe,KAAK,GAAa,EAAI,KAC1D,EAAY,KAAO;;CAKrB,AAFA,EAAW,OAAO,EAAQ,EAC1B,EAAW,QAAQ,EAAK,EACxB,EAAW,QAAQ,EAAK;CAExB,IAAM,IAA+C,EAAE;CACvD,AAAI,MACE,OAAO,EAAK,SAAU,aAAU,EAAW,QAAQ,EAAK,QACxD,OAAO,EAAK,cAAe,aAAU,EAAW,aAAa,EAAK,aAClE,OAAO,EAAK,UAAW,cAAW,EAAW,SAAS,EAAK;CAGjE,IAAM,IAAiB,OAAO,KAAK,EAAY,CAAC,SAAS,GACnD,IAAgB,OAAO,KAAK,EAAW,CAAC,SAAS,GAEjD,IAAoB,EAAE,GAAG,GAAM;CAIrC,OAHI,MAAgB,EAAK,QAAQ,IAC7B,MAAe,EAAK,OAAO,IAExB;;AAyBT,SAAgB,EAAa,GAAe,GAAmD;CAC7F,OAAO,EAAc,GAAY,EAAc,EAAM,EAAE,EAAK;;AAqB9D,SAAgB,EAAe,IAAmB,UAAgB"}

package/dist/esm/elements/form/progress/progress.js

@@ -0,0 +1,27 @@
+import { i as e, n as t } from "../../../chunks/dom.js";
+//#region src/elements/form/progress/index.ts
+var n = /* @__PURE__ */ e({
+	PROGRESS_SELECTOR: () => i,
+	PROGRESS_TAG: () => r,
+	createProgress: () => o,
+	enhanceProgresses: () => s
+}), r = "progress", i = "progress";
+function a(e) {
+	if (!e) return;
+	let { aria: t, value: n, max: r, ...i } = e, a = { ...i.attrs ?? {} }, o = (e, t) => {
+		t !== void 0 && (Object.prototype.hasOwnProperty.call(a, e) || (a[e] = t));
+	}, s = typeof n == "number";
+	s && o("value", n), s ? o("max", typeof r == "number" ? r : 1) : o("max", typeof r == "number" ? r : void 0);
+	let c = {};
+	t && (typeof t.label == "string" && (c.label = t.label), typeof t.labelledby == "string" && (c.labelledby = t.labelledby), typeof t.hidden == "boolean" && (c.hidden = t.hidden));
+	let l = Object.keys(a).length > 0, u = Object.keys(c).length > 0, d = { ...i };
+	return l && (d.attrs = a), u && (d.aria = c), d;
+}
+function o(e, n) {
+	return t(r, a(n), e);
+}
+function s(e = document) {}
+//#endregion
+export { i as PROGRESS_SELECTOR, r as PROGRESS_TAG, o as createProgress, s as enhanceProgresses, n as t };
+
+//# sourceMappingURL=progress.js.map