@vastare/fundatio 0.1.0

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

@@ -0,0 +1,152 @@
+/**
+ * Fundatio 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.
+ *
+ * Fundatio notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via Fundatio'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 Fundatio 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
+ *
+ * Fundatio 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 Fundatio'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 `1.0.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 @@
+/**
+ * Fundatio 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. Fundatio 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.
+ *
+ * Fundatio-specific conventions:
+ * - Requires `label` at creation time to avoid invalid/anonymous optgroups.
+ * - Applies global attributes via Fundatio'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 Fundatio 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. Fundatio requires the label
+ * as a separate argument in {@link createOptgroup}. :contentReference[oaicite:6]{index=6}
+ *
+ * Fundatio 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 Fundatio'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 "@Vastare/Fundatio/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 `1.0.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"}

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

@@ -0,0 +1,160 @@
+/**
+ * Fundatio 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 Fundatio'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 Fundatio 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.
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing Fundatio'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 Fundatio'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 "@Vastare/Fundatio/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 `1.0.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 @@
+/**
+ * Fundatio 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 Fundatio 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 Fundatio 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`).
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing Fundatio'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 Fundatio'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 "@Vastare/Fundatio/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 `1.0.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"}