@vastare/fundatio 0.1.0

package/dist/types/elements/layout/nav/index.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Fundatio Design Foundation: Nav element helpers.
+ *
+ * @remarks
+ * The nav element (`<nav>`) represents a section of a page whose purpose is to
+ * provide navigation links.
+ *
+ * Best-practice guidance:
+ * - Use `<nav>` for major navigation blocks (site navigation, table of contents).
+ * - If a page has multiple navigation regions, provide an accessible name via
+ *   `aria-label` or `aria-labelledby` so assistive tech can distinguish them.
+ * - Avoid nesting `<nav>` elements.
+ * - Prefer semantic grouping of links (e.g. lists) inside the nav.
+ *
+ * Fundatio provides small, framework-agnostic helpers so consumers can:
+ * - create navigation regions 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/nav
+ * @see https://html.spec.whatwg.org/multipage/sections.html#the-nav-element
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @remarks
+ * `<nav>` is a landmark with an implicit `navigation` role.
+ *
+ * Fundatio intentionally encourages naming navigation regions when multiple navs
+ * exist on the same page (e.g. primary vs footer vs breadcrumb navigation).
+ *
+ * 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 nav.
+ *
+ * @category Constants
+ */
+export declare const NAV_TAG: "nav";
+/**
+ * A CSS selector targeting nav elements.
+ *
+ * @category Constants
+ */
+export declare const NAV_SELECTOR = "nav";
+/**
+ * Attribute bag for nav creation/enhancement.
+ *
+ * @remarks
+ * Nav elements accept standard HTML global attributes.
+ *
+ * Accessibility note:
+ * - `<nav>` has an implicit landmark role.
+ * - The ARIA-in-HTML mapping indicates no explicit `role` is permitted for
+ *   `<nav>` in normal usage. Fundatio therefore omits `role` from {@link NavAttrs}.
+ *   Name navs via `aria-label` / `aria-labelledby` instead.
+ *
+ * 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 NavAttrs = Omit<GlobalAttrs, 'aria' | 'role'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a nav 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 nav.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<nav>` element.
+ *
+ * @example
+ * Create a labelled primary navigation region:
+ * ```ts
+ * import { createNav } from "@Vastare/Fundatio/elements/layout/nav";
+ *
+ * const nav = createNav(undefined, { aria: { label: "Primary" }, className: "site-nav" });
+ * document.body.appendChild(nav);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createNav(text?: string, attrs?: NavAttrs): ElementOf<typeof NAV_TAG>;
+/**
+ * Enhance nav 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 enhanceNavs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/layout/nav/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/layout/nav/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;;;GAYG;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,OAAO,EAAG,KAAc,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG;IAC1D;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,OAAO,OAAO,CAAC,CAEpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG7D"}

package/dist/types/elements/layout/section/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Fundatio Design Foundation: Section element helpers.
+ *
+ * @remarks
+ * The section element (`<section>`) represents a standalone thematic grouping of
+ * content, typically with a heading.
+ *
+ * Best-practice guidance:
+ * - Do not treat `<section>` as a "semantic `<div>`". Use it when the content is a
+ *   distinct theme that belongs in the document outline.
+ * - Prefer including a heading (`<h1>`-`<h6>`) that describes the section's purpose.
+ * - If you just need a generic container with no semantic meaning, use `<div>`.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create sections 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: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
+ * - HTML Standard: https://html.spec.whatwg.org/multipage/sections.html#the-section-element
+ * - WHATWG blog (context): https://blog.whatwg.org/is-not-just-a-semantic
+ *
+ * @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 section elements.
+ *
+ * @category Constants
+ */
+export declare const SECTION_TAG: "section";
+/**
+ * A CSS selector targeting section elements.
+ *
+ * @category Constants
+ */
+export declare const SECTION_SELECTOR = "section";
+/**
+ * Attribute bag for section creation/enhancement.
+ *
+ * @remarks
+ * Section 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 SectionAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a section 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 section.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<section>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSection } from "@Vastare/Fundatio/elements/layout/section";
+ *
+ * const s = createSection(undefined, { id: "features" });
+ * document.body.appendChild(s);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSection(text?: string, attrs?: SectionAttrs): ElementOf<typeof SECTION_TAG>;
+/**
+ * Enhance section 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 enhanceSections(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/layout/section/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/layout/section/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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,WAAW,EAAG,SAAkB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACrD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEhG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGjE"}

package/dist/types/elements/list/dd/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Fundatio Design Foundation: Description Details (`<dd>`) element helpers.
+ *
+ * @remarks
+ * The `<dd>` element provides the description, definition, or value for the
+ * preceding term (`<dt>`) within a description list (`<dl>`).
+ *
+ * Best-practice guidance:
+ * - Use `<dd>` only within a `<dl>`.
+ * - Pair `<dd>` with an appropriate `<dt>` term.
+ * - Use semantic lists for terms/values, not for layout.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<dd>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - pass a structured, typed attribute bag
+ *
+ * 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/Reference/Elements/dd
+ * @see https://html.spec.whatwg.org/multipage/grouping-content.html#the-dd-element
+ *
+ * @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 dd.
+ *
+ * @category Constants
+ */
+export declare const DD_TAG: "dd";
+/**
+ * A CSS selector targeting dd elements.
+ *
+ * @category Constants
+ */
+export declare const DD_SELECTOR = "dd";
+/**
+ * Attribute bag for dd creation/enhancement.
+ *
+ * @remarks
+ * `<dd>` only supports 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 DdAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a dd 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 dd element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dd>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDd } from "@Vastare/Fundatio/elements/list/dd";
+ *
+ * const dd = createDd("A sea serpent.", { className: "desc" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDd(text?: string, attrs?: DdAttrs): ElementOf<typeof DD_TAG>;
+/**
+ * Enhance dd 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
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceDds(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/list/dd/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/list/dd/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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;AA4BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CAEjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

package/dist/types/elements/list/dl/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Fundatio Design Foundation: Dl element helpers.
+ *
+ * @remarks
+ * The dl element (`<dl>`) represents a description list (a set of name-value groups).
+ * It is commonly used with `<dt>` (term/name) and `<dd>` (description/value).
+ *
+ * Best-practice guidance:
+ * - Prefer `<dl>` when you're expressing name-value pairs (not just "a list").
+ * - Use `<dt>` / `<dd>` in sensible groupings to keep meaning clear.
+ * - Avoid misusing `<dl>` for layout or arbitrary indentation; use CSS instead.
+ *
+ * Attributes:
+ * - `<dl>` has no element-specific attributes in modern HTML.
+ * - It accepts standard global attributes (id, class, lang, data-*, aria-*, etc.).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<dl>` 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.
+ *
+ * @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 description lists.
+ *
+ * @category Constants
+ */
+export declare const DL_TAG: "dl";
+/**
+ * A CSS selector targeting dl elements.
+ *
+ * @category Constants
+ */
+export declare const DL_SELECTOR = "dl";
+/**
+ * Attribute bag for dl creation/enhancement.
+ *
+ * @remarks
+ * Dl 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 DlAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a dl element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - In real usage, `<dl>` typically contains `<dt>` / `<dd>` children; Fundatio keeps
+ *   factories small and safe, so this helper supports optional text as a simple
+ *   convenience, not as a replacement for proper `<dt>` / `<dd>` structure.
+ * - 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 dl.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dl>` element.
+ *
+ * @example
+ * Create and append a dl:
+ * ```ts
+ * import { createDl } from "@Vastare/Fundatio/elements/list/dl";
+ *
+ * document.body.appendChild(
+ *   createDl(undefined, { className: "meta", id: "product-specs" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDl(text?: string, attrs?: DlAttrs): ElementOf<typeof DL_TAG>;
+/**
+ * Enhance dl 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 enhanceDls(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/list/dl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/list/dl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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"}

package/dist/types/elements/list/dt/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Fundatio Design Foundation: Dt element helpers.
+ *
+ * @remarks
+ * The dt element (`<dt>`) represents a definition term in a description list (`<dl>`).
+ * It is typically paired with one or more `<dd>` elements (the descriptions/details).
+ *
+ * Best-practice guidance:
+ * - Use `<dl>` + `<dt>` + `<dd>` for name/value groups (terms and descriptions),
+ *   not for arbitrary layout or "two-column" grids.
+ * - Keep terms concise; put the detail/content in `<dd>`.
+ * - Use CSS for presentation (avoid presentational patterns that change semantics).
+ *
+ * Attributes:
+ * - `<dt>` supports only global attributes (no element-specific attributes).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create dt elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if Fundatio ever needs runtime behavior
+ *
+ * @see MDN `<dt>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt
+ * @see WHATWG HTML `<dt>`: https://html.spec.whatwg.org/multipage/grouping-content.html#the-dt-element
+ *
+ * @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 dt elements.
+ *
+ * @category Constants
+ */
+export declare const DT_TAG: "dt";
+/**
+ * A CSS selector targeting dt elements.
+ *
+ * @category Constants
+ */
+export declare const DT_SELECTOR = "dt";
+/**
+ * Attribute bag for dt creation/enhancement.
+ *
+ * @remarks
+ * Dt 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 DtAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a dt 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 dt.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dt>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDt } from "@Vastare/Fundatio/elements/list/dt";
+ *
+ * const dl = document.createElement("dl");
+ * dl.appendChild(createDt("Size"));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDt(text?: string, attrs?: DtAttrs): ElementOf<typeof DT_TAG>;
+/**
+ * Enhance dt 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 enhanceDts(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/list/dt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/list/dt/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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"}