@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/form/label/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * pkgn-sol Design Foundation: Label element helpers.
+ *
+ * @remarks
+ * The label element (`<label>`) represents a caption in a user interface and is
+ * primarily used to provide an accessible name for a form control.
+ *
+ * Best-practice guidance:
+ * - Always associate labels with their control:
+ *   - Prefer an explicit association using `for` (pkgn-sol: {@link LabelAttrs.htmlFor})
+ *     that matches the control's `id`.
+ *   - Alternatively, wrap the control inside the `<label>` element.
+ * - Do not rely on placeholder text as a replacement for a visible label.
+ * - Keep label text concise and descriptive.
+ *
+ * Attributes:
+ * - `<label>` supports global attributes.
+ * - The only relevant label-specific content attribute is `for`, reflected in
+ *   JavaScript as `htmlFor`. (The `label` element does not have a `form` content
+ *   attribute; it has a `form` *IDL attribute* derived from the associated control.)
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which
+ *   block inline event handler attributes (e.g. `onclick`) and raw `style`
+ *   attribute injection (use the `style` object field instead).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs (e.g. `lable`).
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for label.
+ *
+ * @category Constants
+ */
+export declare const LABEL_TAG: "label";
+/**
+ * A CSS selector targeting label elements.
+ *
+ * @category Constants
+ */
+export declare const LABEL_SELECTOR = "label";
+/**
+ * Attribute bag for label creation/enhancement.
+ *
+ * @remarks
+ * Labels accept standard HTML global attributes.
+ *
+ * Label-specific:
+ * - {@link LabelAttrs.htmlFor} maps to the `for` attribute, associating the label
+ *   with the control whose `id` matches.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type LabelAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Associate the label with a labelable form control by ID.
+     *
+     * @remarks
+     * This maps to the `for` content attribute.
+     *
+     * The value should match the `id` of a labelable element in the same document
+     * tree (e.g. `<input id="email">` pairs with `<label for="email">`).
+     */
+    htmlFor?: string;
+};
+/**
+ * Create a label element with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the label.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<label>` element.
+ *
+ * @example
+ * ```ts
+ * import { createLabel } from "@lnpg/pkgn-sol/elements/form/label";
+ *
+ * const label = createLabel("Email address", { htmlFor: "email" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createLabel(text?: string, attrs?: LabelAttrs): ElementOf<typeof LABEL_TAG>;
+/**
+ * Enhance label elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceLabels(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/form/label/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/label/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAsCF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAE1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}

package/dist/types/elements/form/legend/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * pkgn-sol Design Foundation: Legend element helpers.
+ *
+ * @remarks
+ * The legend element (`<legend>`) represents a caption for the content of its
+ * parent `<fieldset>`. It is commonly used to label groups of related form
+ * controls (e.g. radio-button groups), improving clarity and accessibility.
+ *
+ * Best-practice guidance:
+ * - Use `<legend>` as the first child of a `<fieldset>` to label the group.
+ * - Keep legend text concise and meaningful (it is typically announced with
+ *   grouped controls by assistive technologies).
+ * - Avoid using `<legend>` purely for layout; use CSS for styling/spacing.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<legend>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend
+ * @see https://www.w3.org/WAI/tutorials/forms/grouping/
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for legend.
+ *
+ * @category Constants
+ */
+export declare const LEGEND_TAG: "legend";
+/**
+ * A CSS selector targeting legend elements.
+ *
+ * @category Constants
+ */
+export declare const LEGEND_SELECTOR = "legend";
+/**
+ * Attribute bag for legend creation/enhancement.
+ *
+ * @remarks
+ * Legend elements accept standard HTML global attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type LegendAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a legend element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the legend.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<legend>` element.
+ *
+ * @example
+ * ```ts
+ * import { createLegend } from "@lnpg/pkgn-sol/elements/form/legend";
+ *
+ * const legend = createLegend("Delivery address");
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createLegend(text?: string, attrs?: LegendAttrs): ElementOf<typeof LEGEND_TAG>;
+/**
+ * Enhance legend elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceLegends(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/form/legend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/legend/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE7F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}

package/dist/types/elements/form/meter/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * pkgn-sol Design Foundation: Meter element helpers.
+ *
+ * @remarks
+ * The meter element (`<meter>`) represents a scalar measurement within a known range,
+ * or a fractional value.
+ *
+ * Best-practice guidance:
+ * - Use `<meter>` for a known-range measurement (e.g. disk usage, score, relevance).
+ * - Do NOT use `<meter>` for task progress. Use `<progress>` for progress indication.
+ * - Provide fallback text content for user agents that don't render `<meter>`.
+ * - Define `min`/`max` if your `value` is not in the default 0..1 range.
+ * - Use `low`/`high`/`optimum` only when you actually want "good/bad" semantics.
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<meter>` element
+ * - WHATWG HTML: meter attributes and behavior
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for meter.
+ *
+ * @category Constants
+ */
+export declare const METER_TAG: "meter";
+/**
+ * A CSS selector targeting meter elements.
+ *
+ * @category Constants
+ */
+export declare const METER_SELECTOR = "meter";
+/**
+ * Attribute bag for meter creation/enhancement.
+ *
+ * @remarks
+ * Supported element-specific attributes:
+ * - `value`, `min`, `max`, `low`, `high`, `optimum`
+ * - `form` (associates the meter with a form owner by ID)
+ *
+ * Defaults (documented platform behavior):
+ * - `min` defaults to `0` when omitted
+ * - `max` defaults to `1` when omitted
+ * - `value` defaults to `0` when omitted or malformed
+ *
+ * pkgn-sol applies these defaults as explicit attributes to keep output predictable
+ * and testable even in node-based DOM shims.
+ *
+ * @category Attributes
+ */
+export type MeterAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Current numeric value.
+     *
+     * @remarks
+     * Should be within `[min, max]` when those are defined.
+     */
+    value?: number;
+    /**
+     * Lower numeric bound of the range. Defaults to `0`.
+     */
+    min?: number;
+    /**
+     * Upper numeric bound of the range. Defaults to `1`.
+     */
+    max?: number;
+    /**
+     * Upper numeric bound of the low end of the range.
+     */
+    low?: number;
+    /**
+     * Lower numeric bound of the high end of the range.
+     */
+    high?: number;
+    /**
+     * The optimal value within the range.
+     */
+    optimum?: number;
+    /**
+     * Associates the meter with a form element by ID.
+     *
+     * @remarks
+     * Mirrors the HTML `form` attribute used by form-associated elements.
+     */
+    form?: string;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a meter element with optional fallback text and attributes.
+ *
+ * @remarks
+ * - Fallback text is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional fallback text for user agents that don't render `<meter>`.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<meter>` element.
+ *
+ * @category DOM
+ */
+export declare function createMeter(text?: string, attrs?: MeterAttrs): ElementOf<typeof METER_TAG>;
+/**
+ * Enhance meter elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceMeters(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/form/meter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/meter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6DF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAE1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}

package/dist/types/elements/form/optgroup/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * pkgn-sol Design Foundation: Optgroup element helpers.
+ *
+ * @remarks
+ * The optgroup element (`<optgroup>`) groups related `<option>` elements within
+ * a `<select>`, allowing user agents to present grouped choices with a label.
+ * :contentReference[oaicite:3]{index=3}
+ *
+ * Best-practice guidance:
+ * - Always provide a meaningful `label`. MDN notes this attribute is mandatory
+ *   when the element is used. pkgn-sol enforces this by requiring `label` when
+ *   creating an optgroup. :contentReference[oaicite:4]{index=4}
+ * - Use `disabled` to disable all options within the group when appropriate.
+ * :contentReference[oaicite:5]{index=5}
+ * - Prefer native semantics; avoid ARIA where native semantics already apply.
+ *
+ * pkgn-sol-specific conventions:
+ * - Requires `label` at creation time to avoid invalid/anonymous optgroups.
+ * - Applies global attributes via pkgn-sol's hardened DOM helpers (`dom.ts`), which
+ *   block inline event handler attributes (e.g. `onclick`) and the raw `style`
+ *   attribute string.
+ * - Supports a small structured ARIA input to reduce typo-based ARIA bugs.
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset mapped into {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for option groups.
+ *
+ * @category Constants
+ */
+export declare const OPTGROUP_TAG: "optgroup";
+/**
+ * A CSS selector targeting optgroup elements.
+ *
+ * @category Constants
+ */
+export declare const OPTGROUP_SELECTOR = "optgroup";
+/**
+ * Attribute bag for optgroup creation/enhancement.
+ *
+ * @remarks
+ * `<optgroup>` accepts global attributes plus:
+ * - `disabled` (boolean attribute)
+ *
+ * The `label` attribute is mandatory for meaningful use. pkgn-sol requires the label
+ * as a separate argument in {@link createOptgroup}. :contentReference[oaicite:6]{index=6}
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type OptgroupAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Disables the option group when true.
+     *
+     * @remarks
+     * When disabled, none of the options in the group are selectable. :contentReference[oaicite:7]{index=7}
+     */
+    disabled?: boolean;
+};
+/**
+ * Create an optgroup element with a required label and optional attributes.
+ *
+ * @remarks
+ * - The label is mapped to the `label` attribute (required for meaningful use). :contentReference[oaicite:8]{index=8}
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, including security
+ *   guards that block inline event handler attributes (e.g. `onclick`) and raw
+ *   `style` attribute strings.
+ *
+ * @param label - The optgroup label shown by the user agent.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<optgroup>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOptgroup } from "@lnpg/pkgn-sol/elements/form/optgroup";
+ *
+ * const g = createOptgroup("Fruits", { disabled: false });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createOptgroup(label: string, attrs?: OptgroupAttrs): ElementOf<typeof OPTGROUP_TAG>;
+/**
+ * Enhance optgroup elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceOptgroups(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/form/optgroup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/optgroup/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAG,UAAmB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACtD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA6CF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,aAAa,GACpB,SAAS,CAAC,OAAO,YAAY,CAAC,CAEhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGlE"}