@vastare/fundatio 0.1.0

package/dist/types/elements/interactive/details/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Fundatio Design Foundation: Details element helpers.
+ *
+ * @remarks
+ * The details element (`<details>`) creates a disclosure widget where content is
+ * shown/hidden by toggling the element open/closed. (MDN) :contentReference[oaicite:3]{index=3}
+ *
+ * Best-practice guidance:
+ * - Provide a visible label using a child `<summary>` element; it acts as the
+ *   interactive control for toggling the parent `<details>`. (MDN) :contentReference[oaicite:4]{index=4}
+ * - Use the `open` attribute to render expanded by default. (MDN) :contentReference[oaicite:5]{index=5}
+ * - If using the `name` attribute to create a mutually-exclusive group, authors
+ *   must avoid markup where more than one element in the same name group has
+ *   `open` present. User agents may enforce exclusivity by changing `open`.
+ *   (WHATWG) :contentReference[oaicite:6]{index=6}
+ *
+ * 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 details disclosure widgets.
+ *
+ * @category Constants
+ */
+export declare const DETAILS_TAG: "details";
+/**
+ * A CSS selector targeting details elements.
+ *
+ * @category Constants
+ */
+export declare const DETAILS_SELECTOR = "details";
+/**
+ * Attribute bag for details creation/enhancement.
+ *
+ * @remarks
+ * `<details>` accepts global attributes plus:
+ * - `open` (boolean attribute)
+ * - `name` (creates a mutually-exclusive details name group, per spec)
+ *
+ * `name` grouping behavior is specified by HTML; Fundatio does not enforce group
+ * constraints at runtime. (WHATWG) :contentReference[oaicite:7]{index=7}
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type DetailsAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Whether the details is open (expanded) by default.
+     *
+     * @remarks
+     * This maps to the boolean `open` attribute. (MDN) :contentReference[oaicite:8]{index=8}
+     */
+    open?: boolean;
+    /**
+     * Name of a mutually-exclusive details group.
+     *
+     * @remarks
+     * Details with the same `name` may form an exclusive group where at most one
+     * is open at a time. (WHATWG) :contentReference[oaicite:9]{index=9}
+     */
+    name?: string;
+};
+/**
+ * Create a details element with optional attributes.
+ *
+ * @remarks
+ * - Provide a child `<summary>` for the visible label/toggle control. (MDN) :contentReference[oaicite:10]{index=10}
+ * - 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 `<details>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDetails } from "@Vastare/Fundatio/elements/interactive/details";
+ *
+ * const d = createDetails({ open: true });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDetails(attrs?: DetailsAttrs): ElementOf<typeof DETAILS_TAG>;
+/**
+ * Enhance details 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 enhanceDetails(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/interactive/details/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/interactive/details/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,WAAW,EAAG,SAAkB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACrD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAmDF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}

package/dist/types/elements/interactive/dialog/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Fundatio Design Foundation: Dialog element helpers.
+ *
+ * @remarks
+ * The dialog element (`<dialog>`) represents a modal or non-modal dialog box
+ * (e.g. a confirm prompt, inspector, or subwindow).
+ *
+ * Best-practice guidance:
+ * - Prefer using the platform APIs:
+ *   - `dialog.showModal()` for modal dialogs
+ *   - `dialog.show()` for non-modal dialogs
+ *   - `dialog.close()` to close, optionally supplying a return value
+ * - Provide an accessible name for the dialog content (e.g. heading + `aria-labelledby`
+ *   or `aria-label` when appropriate).
+ * - Ensure the dialog contains an obvious close mechanism.
+ * - Avoid relying solely on adding/removing `open`; prefer the element's methods
+ *   for correct focus and modal behavior.
+ *
+ * Attributes (element-specific):
+ * - `open` (boolean): when present, the dialog is active and available for interaction.
+ * - `closedBy` (enumerated): maps to the `closedby` content attribute (spec-defined).
+ *
+ * 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/dialog
+ *
+ * @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 dialog.
+ *
+ * @category Constants
+ */
+export declare const DIALOG_TAG: "dialog";
+/**
+ * A CSS selector targeting dialog elements.
+ *
+ * @category Constants
+ */
+export declare const DIALOG_SELECTOR = "dialog";
+/**
+ * Values supported by the `closedby` content attribute.
+ *
+ * @remarks
+ * This is a newer platform feature that specifies which user actions can close
+ * the dialog automatically.
+ *
+ * - `any`: close requests or clicks outside close the dialog.
+ * - `closerequest`: close requests close the dialog.
+ * - `none`: no user actions automatically close the dialog.
+ *
+ * @category Types
+ */
+export type DialogClosedBy = 'any' | 'closerequest' | 'none';
+/**
+ * Attribute bag for dialog creation/enhancement.
+ *
+ * @remarks
+ * Dialog elements accept standard HTML global attributes plus a small set of
+ * dialog-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 DialogAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Whether the dialog is open (active).
+     *
+     * @remarks
+     * Maps to the `open` boolean attribute.
+     *
+     * Prefer controlling visibility via the native methods (`showModal`, `show`,
+     * `close`) when possible.
+     */
+    open?: boolean;
+    /**
+     * Control user actions that can close the dialog.
+     *
+     * @remarks
+     * Maps to the `closedby` content attribute.
+     */
+    closedBy?: DialogClosedBy;
+};
+/**
+ * Create a dialog 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 dialog.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dialog>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDialog } from "@Vastare/Fundatio/elements/interactive/dialog";
+ *
+ * const d = createDialog("Hello", { open: true });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createDialog(text?: string, attrs?: DialogAttrs): ElementOf<typeof DIALOG_TAG>;
+/**
+ * Enhance dialog 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 enhanceDialogs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/interactive/dialog/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/interactive/dialog/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,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,cAAc,GAAG,MAAM,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,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/interactive/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Interactive element factories.
+ *
+ * Provides framework-agnostic factory functions for interactive HTML elements
+ * that expose built-in browser behaviors such as disclosure widgets and modal
+ * dialogs.
+ *
+ * These factories:
+ * - Create semantic interactive structures using Fundatio's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct accessibility semantics and relationships.
+ * - Prevent unsafe attribute injection.
+ *
+ * The elements in this module provide native interactivity that browsers
+ * understand without requiring JavaScript frameworks.
+ *
+ * @module elements/interactive
+ * @since 1.0.0
+ */
+/**
+ * `<details>` element factory namespace.
+ *
+ * Represents a disclosure widget that users can open and close to reveal
+ * additional information.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
+ */
+export * as details from './details';
+/**
+ * `<dialog>` element factory namespace.
+ *
+ * Represents a dialog box or interactive component such as a modal window,
+ * alert, or confirmation interface.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+ */
+export * as dialog from './dialog';
+/**
+ * `<summary>` element factory namespace.
+ *
+ * Represents the summary or visible heading for a `<details>` disclosure
+ * widget. Clicking the summary toggles the details content.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary
+ */
+export * as summary from './summary';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/interactive/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/elements/interactive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AAErC;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC"}

package/dist/types/elements/interactive/summary/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Fundatio Design Foundation: Summary element helpers.
+ *
+ * @remarks
+ * The summary element (`<summary>`) provides the visible label for a parent
+ * `<details>` disclosure widget. Activating (clicking / pressing Enter) on the
+ * `<summary>` toggles the open state of the parent `<details>` element.
+ *
+ * Best-practice guidance:
+ * - Use `<summary>` only as the first child of a `<details>` element.
+ * - Use clear, concise text so the disclosure purpose is obvious.
+ * - Prefer semantic content inside `<summary>`; avoid overly complex interactive
+ *   children inside the summary label.
+ *
+ * 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: `<summary>` element
+ * - WHATWG HTML: `<details>` content model and summary semantics
+ *
+ * @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 summary.
+ *
+ * @category Constants
+ */
+export declare const SUMMARY_TAG: "summary";
+/**
+ * A CSS selector targeting summary elements.
+ *
+ * @category Constants
+ */
+export declare const SUMMARY_SELECTOR = "summary";
+/**
+ * Attribute bag for summary creation/enhancement.
+ *
+ * @remarks
+ * `<summary>` supports 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 SummaryAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a summary 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 summary.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<summary>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSummary } from "@Vastare/Fundatio/elements/interactive/summary";
+ *
+ * const s = createSummary("More details");
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createSummary(text?: string, attrs?: SummaryAttrs): ElementOf<typeof SUMMARY_TAG>;
+/**
+ * Enhance summary 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 enhanceSummaries(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/interactive/summary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/interactive/summary/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,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;AA4BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEhG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGlE"}

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

@@ -0,0 +1,129 @@
+/**
+ * Fundatio Design Foundation: Article element helpers.
+ *
+ * @remarks
+ * The article element (`<article>`) represents a self-contained composition in a
+ * document, page, application, or site that is intended to be independently
+ * distributable or reusable (e.g. syndication).
+ *
+ * Best-practice guidance:
+ * - Use `<article>` for content that makes sense on its own (blog post, news item,
+ *   forum post, comment, product card, etc.).
+ * - Prefer `<section>` for thematic grouping that is not independently distributable.
+ * - Articles commonly include a heading (h1-h6) in their content, but this module
+ *   does not enforce structure at runtime.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create article 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.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article
+ * @see https://html.spec.whatwg.org/multipage/sections.html#the-article-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 article.
+ *
+ * @category Constants
+ */
+export declare const ARTICLE_TAG: "article";
+/**
+ * A CSS selector targeting article elements.
+ *
+ * @category Constants
+ */
+export declare const ARTICLE_SELECTOR = "article";
+/**
+ * Attribute bag for article creation/enhancement.
+ *
+ * @remarks
+ * Article 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 ArticleAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an article 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 article.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<article>` element.
+ *
+ * @example
+ * ```ts
+ * import { createArticle } from "@Vastare/Fundatio/elements/layout/article";
+ *
+ * document.body.appendChild(
+ *   createArticle(undefined, { className: "post", aria: { label: "Blog post" } })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createArticle(text?: string, attrs?: ArticleAttrs): ElementOf<typeof ARTICLE_TAG>;
+/**
+ * Enhance article 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 enhanceArticles(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/layout/article/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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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"}