@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,160 @@
+/**
+ * pkgn-sol Design Foundation: Option element helpers.
+ *
+ * @remarks
+ * The option element (`<option>`) defines an item within a `<select>`, `<optgroup>`,
+ * or `<datalist>` element.
+ *
+ * Best-practice guidance:
+ * - Prefer providing a `value` for form submission semantics. If `value` is omitted,
+ *   the option's value typically falls back to its text content.
+ * - Use `label` when you need a shorter label for UI display or accessibility hints,
+ *   but keep the option text clear and readable.
+ * - Use `disabled` to prevent selection of an option (or to mark placeholders as
+ *   unavailable).
+ * - Use `selected` to mark the default selection in a `<select>` (usually one
+ *   option should be selected by default).
+ *
+ * Attributes:
+ * - `value` (string): the value submitted/used when selected.
+ * - `label` (string): a label for the option.
+ * - `disabled` (boolean): whether the option is unavailable.
+ * - `selected` (boolean): whether the option is selected by default.
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by pkgn-sol's `dom.ts` helpers which
+ *   block inline event handler attributes (e.g. `onclick`) and raw `style`
+ *   attribute injection (use the `style` object field instead).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/option
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs (e.g. `lable`).
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for option.
+ *
+ * @category Constants
+ */
+export declare const OPTION_TAG: "option";
+/**
+ * A CSS selector targeting option elements.
+ *
+ * @category Constants
+ */
+export declare const OPTION_SELECTOR = "option";
+/**
+ * Attribute bag for option creation/enhancement.
+ *
+ * @remarks
+ * Options accept standard HTML global attributes plus a small set of option-specific
+ * content attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type OptionAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * The option value.
+     *
+     * @remarks
+     * If omitted, user agents commonly derive a value from the option's text.
+     */
+    value?: string;
+    /**
+     * A label for the option.
+     *
+     * @remarks
+     * When present, this may be used by user agents as the option's label instead
+     * of the text content in certain contexts.
+     */
+    label?: string;
+    /**
+     * Whether the option is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the option is selected by default.
+     *
+     * @remarks
+     * For `<select>`, `selected` commonly indicates the default selected option on
+     * initial load. If multiple options are marked selected, browser behavior varies;
+     * prefer a single default selection unless using a multi-select.
+     */
+    selected?: boolean;
+};
+/**
+ * Create an option element with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes and escape-hatch attributes are applied via pkgn-sol's shared
+ *   DOM helper, including security guards that block inline event handler
+ *   attributes (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the option.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<option>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOption } from "@lnpg/pkgn-sol/elements/form/option";
+ *
+ * const opt = createOption("United Kingdom", { value: "UK" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createOption(text?: string, attrs?: OptionAttrs): ElementOf<typeof OPTION_TAG>;
+/**
+ * Enhance option elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceOptions(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/option/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA2CF;;;;;;;;;;;;;;;;;;;;;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/output/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * pkgn-sol Design Foundation: Output element helpers.
+ *
+ * @remarks
+ * The output element (`<output>`) represents the result of a calculation or a
+ * user action, commonly used in forms to display derived values without
+ * requiring focus changes.
+ *
+ * Best-practice guidance:
+ * - Use `<output>` for computed results derived from form controls.
+ * - Use the `for` attribute to associate the output with the control(s) whose
+ *   values it reflects (space-separated list of element IDs).
+ * - Prefer semantic HTML and native behavior over ARIA. Many browsers treat
+ *   `<output>` as an ARIA live region, so updating its text may be announced by
+ *   assistive technologies without moving focus.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create outputs in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/output
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/for
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/form
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for output.
+ *
+ * @category Constants
+ */
+export declare const OUTPUT_TAG: "output";
+/**
+ * A CSS selector targeting output elements.
+ *
+ * @category Constants
+ */
+export declare const OUTPUT_SELECTOR = "output";
+/**
+ * Attribute bag for output creation/enhancement.
+ *
+ * @remarks
+ * Output accepts standard HTML global attributes plus output-specific
+ * attributes (`for`, `form`, `name`).
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type OutputAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Space-separated list of element IDs whose values contributed to the output.
+     *
+     * @remarks
+     * This maps to the `for` attribute (yes, the HTML attribute is literally
+     * called `for`).
+     */
+    for?: string;
+    /**
+     * Associates the output with a form element by ID, even if not a descendant.
+     */
+    form?: string;
+    /**
+     * Name of the output (useful in form-associated contexts).
+     */
+    name?: string;
+};
+/**
+ * Create an output element with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the output.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<output>` element.
+ *
+ * @example
+ * ```ts
+ * import { createOutput } from "@lnpg/pkgn-sol/elements/form/output";
+ *
+ * const out = createOutput("0", { name: "result", for: "a b" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createOutput(text?: string, attrs?: OutputAttrs): ElementOf<typeof OUTPUT_TAG>;
+/**
+ * Enhance output elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceOutputs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/output/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AA6CF;;;;;;;;;;;;;;;;;;;;;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/progress/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * pkgn-sol Design Foundation: Progress element helpers.
+ *
+ * @remarks
+ * The progress element (`<progress>`) represents the completion progress of a task.
+ *
+ * Best-practice guidance:
+ * - Use `<progress>` to represent task completion (downloads, uploads, multi-step flows).
+ * - If the amount of work is unknown, omit `value` to produce an indeterminate progress bar.
+ * - Provide fallback text content for user agents that don't render `<progress>`.
+ * - When using a determinate progress bar, set `value` and (usually) `max`.
+ *
+ * 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: `<progress>` element
+ * - WHATWG HTML: `progress` element IDL and defaults (`max` defaults to 1.0)
+ * - MDN: `:indeterminate` and indeterminate `<progress>` when `value` is absent
+ *
+ * @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 progress.
+ *
+ * @category Constants
+ */
+export declare const PROGRESS_TAG: "progress";
+/**
+ * A CSS selector targeting progress elements.
+ *
+ * @category Constants
+ */
+export declare const PROGRESS_SELECTOR = "progress";
+/**
+ * Attribute bag for progress creation/enhancement.
+ *
+ * @remarks
+ * Supported element-specific attributes:
+ * - `value` (optional): when omitted, the progress bar is indeterminate
+ * - `max` (optional): defaults to 1.0 when omitted (platform default)
+ *
+ * pkgn-sol behavior:
+ * - If `value` is omitted, pkgn-sol does NOT set it, preserving indeterminate semantics.
+ * - If `value` is provided and `max` is omitted, pkgn-sol applies `max=1` explicitly
+ *   for predictable, testable output in node-based environments.
+ *
+ * @category Attributes
+ */
+export type ProgressAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Current progress value.
+     *
+     * @remarks
+     * If omitted, the progress bar is indeterminate.
+     */
+    value?: number;
+    /**
+     * Maximum value. Must be greater than 0.
+     *
+     * @remarks
+     * Defaults to 1.0 when omitted (platform default).
+     */
+    max?: number;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a progress 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 `<progress>`.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<progress>` element.
+ *
+ * @example
+ * Indeterminate progress:
+ * ```ts
+ * createProgress("Loading...");
+ * ```
+ *
+ * @example
+ * Determinate progress:
+ * ```ts
+ * createProgress(undefined, { value: 30, max: 100 });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createProgress(text?: string, attrs?: ProgressAttrs): ElementOf<typeof PROGRESS_TAG>;
+/**
+ * Enhance progress 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 enhanceProgresses(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/progress/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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,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;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA2DF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAC5B,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,aAAa,GACpB,SAAS,CAAC,OAAO,YAAY,CAAC,CAEhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGnE"}

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

@@ -0,0 +1,158 @@
+/**
+ * pkgn-sol Design Foundation: Select element helpers.
+ *
+ * @remarks
+ * The select element (`<select>`) is a form control for choosing one or more
+ * options from a list, typically expressed via child `<option>` and `<optgroup>`
+ * elements. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select?utm_source=chatgpt.com))
+ *
+ * Best-practice guidance:
+ * - Provide an accessible name via a `<label>` or ARIA labelling.
+ * - Prefer native semantics over custom "fake selects" unless you have a very
+ *   good reason (and a lot of time for accessibility testing).
+ * - Use `multiple` and/or `size` intentionally; they change presentation and
+ *   interaction patterns. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select?utm_source=chatgpt.com))
+ * - Use `autocomplete` as a hint to user agents, not a security control. (HTML Standard)
+ *
+ * pkgn-sol-specific conventions:
+ * - 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 select controls.
+ *
+ * @category Constants
+ */
+export declare const SELECT_TAG: "select";
+/**
+ * A CSS selector targeting select elements.
+ *
+ * @category Constants
+ */
+export declare const SELECT_SELECTOR = "select";
+/**
+ * Attribute bag for select creation/enhancement.
+ *
+ * @remarks
+ * `<select>` accepts global attributes plus a small set of form-control and
+ * select-specific attributes such as `multiple` and `size`. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select?utm_source=chatgpt.com))
+ *
+ * pkgn-sol models the most common attributes explicitly and leaves an escape hatch via
+ * {@link GlobalAttrs.attrs} for less common cases (validated by `dom.ts`).
+ *
+ * @category Attributes
+ */
+export type SelectAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * The form control name (used during submission).
+     */
+    name?: string;
+    /**
+     * Explicitly associate the control with a form by ID.
+     */
+    form?: string;
+    /**
+     * Disables the control when true.
+     */
+    disabled?: boolean;
+    /**
+     * Marks the control required for form submission.
+     */
+    required?: boolean;
+    /**
+     * Enables selection of multiple options.
+     */
+    multiple?: boolean;
+    /**
+     * Number of options visible at once. Commonly used with `multiple`.
+     */
+    size?: number;
+    /**
+     * Autofocus hint.
+     */
+    autofocus?: boolean;
+    /**
+     * Autofill hint for user agents.
+     *
+     * @remarks
+     * Defined by HTML for form controls.
+     */
+    autoComplete?: string;
+    /**
+     * Directionality submission control (submits `name.dir`).
+     *
+     * @remarks
+     * Defined by the HTML form-control infrastructure (`dirname`).
+     */
+    dirName?: string;
+};
+/**
+ * Create a select element with optional attributes.
+ *
+ * @remarks
+ * - `<select>` content is provided via child `<option>`/`<optgroup>` elements,
+ *   not text content. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select?utm_source=chatgpt.com))
+ * - 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 attrs - Optional attributes to apply.
+ * @returns The created `<select>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSelect } from "@lnpg/pkgn-sol/elements/form/select";
+ *
+ * const s = createSelect({ name: "country", required: true });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSelect(attrs?: SelectAttrs): ElementOf<typeof SELECT_TAG>;
+/**
+ * Enhance select 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 enhanceSelects(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/select/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElG;;;;;;;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,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAwEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}