@vastare/fundatio 0.1.0

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

@@ -0,0 +1,140 @@
+/**
+ * Fundatio 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`.
+ *
+ * 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: `<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 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 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)
+ *
+ * Fundatio behavior:
+ * - If `value` is omitted, Fundatio does NOT set it, preserving indeterminate semantics.
+ * - If `value` is provided and `max` is omitted, Fundatio 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 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 `<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 `1.0.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 @@
+/**
+ * Fundatio 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)
+ *
+ * Fundatio-specific conventions:
+ * - 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 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))
+ *
+ * Fundatio 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 Fundatio'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 "@Vastare/Fundatio/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 `1.0.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"}

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

@@ -0,0 +1,228 @@
+/**
+ * Fundatio Design Foundation: Textarea element helpers.
+ *
+ * @remarks
+ * The textarea element (`<textarea>`) is a multi-line plain-text form control.
+ *
+ * Best-practice guidance:
+ * - Always provide an accessible name (typically via a `<label>`).
+ * - Prefer `placeholder` as a hint, not as a substitute for a label.
+ * - Use `rows`/`cols` to set a sensible baseline size, then use CSS for layout.
+ * - Use `minLength`/`maxLength` for client-side constraints, but validate on the server.
+ * - Use `wrap="hard"` only when you intentionally want line breaks inserted for
+ *   form submission, and ensure `cols` is set.
+ * - Use `dirname` only when you actually want directionality included in submission.
+ *
+ * Attributes (element-specific):
+ * - `name`, `form`, `disabled`, `required`, `readOnly`
+ * - `cols`, `rows`
+ * - `minLength`, `maxLength`
+ * - `placeholder`
+ * - `autoComplete`, `autoFocus`, `autoCapitalize`
+ * - `dirName`
+ * - `wrap`
+ *
+ * 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/textarea
+ *
+ * @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 textarea.
+ *
+ * @category Constants
+ */
+export declare const TEXTAREA_TAG: "textarea";
+/**
+ * A CSS selector targeting textarea elements.
+ *
+ * @category Constants
+ */
+export declare const TEXTAREA_SELECTOR = "textarea";
+/**
+ * Textarea wrap modes.
+ *
+ * @remarks
+ * - `soft` (default): the submitted value is not forcibly wrapped.
+ * - `hard`: line breaks are inserted for submission based on `cols`.
+ *
+ * @category Types
+ */
+export type TextareaWrap = 'soft' | 'hard';
+/**
+ * Autocapitalize values accepted by browsers for form controls.
+ *
+ * @remarks
+ * This is a content attribute commonly supported on form controls.
+ *
+ * @category Types
+ */
+export type AutoCapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+/**
+ * Attribute bag for textarea creation/enhancement.
+ *
+ * @remarks
+ * Textareas accept standard HTML global attributes plus textarea-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 TextareaAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Name used during form submission.
+     */
+    name?: string;
+    /**
+     * Associate the control with a form by ID.
+     */
+    form?: string;
+    /**
+     * Whether the textarea is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the textarea is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the textarea is read-only.
+     *
+     * @remarks
+     * Maps to the `readonly` content attribute.
+     */
+    readOnly?: boolean;
+    /**
+     * The number of visible text columns.
+     */
+    cols?: number;
+    /**
+     * The number of visible text rows.
+     */
+    rows?: number;
+    /**
+     * Minimum input length.
+     *
+     * @remarks
+     * Maps to the `minlength` content attribute.
+     */
+    minLength?: number;
+    /**
+     * Maximum input length.
+     *
+     * @remarks
+     * Maps to the `maxlength` content attribute.
+     */
+    maxLength?: number;
+    /**
+     * Placeholder hint text.
+     */
+    placeholder?: string;
+    /**
+     * Autofill hint.
+     */
+    autoComplete?: string;
+    /**
+     * Whether the control should be focused on page load.
+     */
+    autoFocus?: boolean;
+    /**
+     * Autocapitalization behavior.
+     */
+    autoCapitalize?: AutoCapitalize;
+    /**
+     * Submission directionality field name.
+     *
+     * @remarks
+     * When set, the value must not be empty.
+     * Maps to the `dirname` content attribute.
+     */
+    dirName?: string;
+    /**
+     * Wrapping mode for form submission.
+     */
+    wrap?: TextareaWrap;
+};
+/**
+ * Create a textarea element with optional initial value and attributes.
+ *
+ * @remarks
+ * For `<textarea>`, the initial value is represented by its text content in HTML.
+ * Fundatio assigns the provided `text` via `textContent` (never `innerHTML`).
+ *
+ * - 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 initial value (assigned as `textContent`).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<textarea>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTextarea } from "@Vastare/Fundatio/elements/form/textarea";
+ *
+ * const t = createTextarea("Hello", { rows: 4, cols: 40, name: "message" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createTextarea(text?: string, attrs?: TextareaAttrs): ElementOf<typeof TEXTAREA_TAG>;
+/**
+ * Enhance textarea 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 enhanceTextareas(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/form/textarea/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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,YAAY,EAAG,UAAmB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,OAAO,GAAG,YAAY,CAAC;AAE1F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACtD;;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;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,CAAC;AA4FF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAC5B,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,aAAa,GACpB,SAAS,CAAC,OAAO,YAAY,CAAC,CAEhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGlE"}

package/dist/types/elements/heading/h1/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Fundatio Design Foundation: H1 element helpers.
+ *
+ * @remarks
+ * The h1 element (`<h1>`) represents the highest-rank section heading.
+ *
+ * Best-practice guidance:
+ * - Use headings to convey document structure, not for visual styling.
+ * - Keep heading levels ordered (don't jump from `<h1>` to `<h3>` because you
+ *   like the font size). Use CSS for presentation.
+ * - Prefer clear, succinct headings that describe the section that follows.
+ * - Many accessibility guides recommend a single `<h1>` as the page/document's
+ *   primary heading. HTML allows multiple headings, but consistency matters.
+ * - Don't rely on default browser heading styles; user-agent styles can change.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<h1>` elements 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.
+ *
+ * References:
+ * - MDN: Heading elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
+ * - MDN: Headings and paragraphs: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs
+ * - W3C WAI: Headings: https://www.w3.org/WAI/tutorials/page-structure/headings/
+ * - WHATWG HTML: Sections / heading content: https://html.spec.whatwg.org/multipage/sections.html
+ *
+ * @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 the primary heading element.
+ *
+ * @category Constants
+ */
+export declare const H1_TAG: "h1";
+/**
+ * A CSS selector targeting h1 elements.
+ *
+ * @category Constants
+ */
+export declare const H1_SELECTOR = "h1";
+/**
+ * Attribute bag for h1 creation/enhancement.
+ *
+ * @remarks
+ * H1 elements accept standard HTML global 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 H1Attrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an h1 element with optional text content and global 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 heading.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<h1>` element.
+ *
+ * @example
+ * ```ts
+ * import { createH1 } from "@Vastare/Fundatio/elements/heading/h1";
+ *
+ * document.body.prepend(createH1("Page title", { id: "title" }));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createH1(text?: string, attrs?: H1Attrs): ElementOf<typeof H1_TAG>;
+/**
+ * Enhance h1 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 enhanceH1s(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/heading/h1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/heading/h1/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,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAChD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CAEjF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}