@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,122 @@
+/**
+ * pkgn-sol Design Foundation: Footer element helpers.
+ *
+ * @remarks
+ * The footer element (`<footer>`) represents a footer for its nearest ancestor
+ * sectioning content or sectioning root. It can be used as a page footer or as
+ * a footer within an `<article>`, `<section>`, etc.
+ *
+ * Best-practice guidance:
+ * - Use `<footer>` for information about the section it belongs to (author info,
+ *   related links, legal text, etc.).
+ * - Do not use `<footer>` purely for visual positioning. Layout is CSS; meaning
+ *   is HTML.
+ * - Prefer native semantics. Only add ARIA roles when needed.
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<footer>` element
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for footer.
+ *
+ * @category Constants
+ */
+export declare const FOOTER_TAG: "footer";
+/**
+ * A CSS selector targeting footer elements.
+ *
+ * @category Constants
+ */
+export declare const FOOTER_SELECTOR = "footer";
+/**
+ * Attribute bag for footer creation/enhancement.
+ *
+ * @remarks
+ * Footer elements accept standard HTML global attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type FooterAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a footer element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the footer.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<footer>` element.
+ *
+ * @example
+ * ```ts
+ * import { createFooter } from "@lnpg/pkgn-sol/elements/layout/footer";
+ *
+ * const f = createFooter("© 2026", { className: "site-footer" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createFooter(text?: string, attrs?: FooterAttrs): ElementOf<typeof FOOTER_TAG>;
+/**
+ * Enhance footer elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceFooters(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/layout/footer/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,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGhE"}

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

@@ -0,0 +1,131 @@
+/**
+ * pkgn-sol Design Foundation: Header (`header`) element helpers.
+ *
+ * @remarks
+ * The header element (`<header>`) represents introductory content for its nearest
+ * ancestor sectioning root or sectioning content element. It commonly contains a
+ * heading (`<h1>`-`<h6>`), branding, navigation aids, or other introductory UI.
+ *
+ * Best-practice guidance:
+ * - Use `<header>` to group introductory content for a page or section.
+ * - Prefer meaningful structure (headings, landmarks) over generic containers.
+ * - Avoid using `<header>` purely for styling. Use CSS classes for styling and
+ *   keep semantics intentional.
+ * - A top-level `<header>` (scoped to `<body>` and not inside sectioning content)
+ *   may be exposed as a landmark; nested headers typically are not.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create header elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header
+ * @see https://html.spec.whatwg.org/multipage/sections.html#the-header-element
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs (e.g. `lable`).
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for header elements.
+ *
+ * @category Constants
+ */
+export declare const HEADER_TAG: "header";
+/**
+ * A CSS selector targeting header elements.
+ *
+ * @category Constants
+ */
+export declare const HEADER_SELECTOR = "header";
+/**
+ * Attribute bag for header creation/enhancement.
+ *
+ * @remarks
+ * `<header>` accepts standard HTML global attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type HeaderAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a header element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the header.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<header>` element.
+ *
+ * @example
+ * Create and append a header:
+ * ```ts
+ * import { createHeader } from "@lnpg/pkgn-sol/elements/layout/header";
+ *
+ * document.body.prepend(
+ *   createHeader(undefined, { className: "site-header" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createHeader(text?: string, attrs?: HeaderAttrs): ElementOf<typeof HEADER_TAG>;
+/**
+ * Enhance header elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceHeaders(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/layout/header/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;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;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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/layout/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Layout element factories.
+ *
+ * Provides framework-agnostic factory functions for HTML elements used to
+ * structure the major sections of a document or application.
+ *
+ * These factories:
+ * - Create semantic layout structures using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct document outline and accessibility semantics.
+ * - Prevent unsafe attribute injection.
+ *
+ * The elements in this module define the high-level structure of pages,
+ * articles, navigation regions, and supporting content.
+ *
+ * @module elements/layout
+ * @since 0.1.0
+ */
+/**
+ * `<article>` element factory namespace.
+ *
+ * Represents a self-contained composition that can be independently
+ * distributed or reused, such as a blog post, news article, or forum entry.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article
+ */
+export * as article from './article';
+/**
+ * `<aside>` element factory namespace.
+ *
+ * Represents content indirectly related to the surrounding content, often
+ * presented as a sidebar, pull quote, or complementary section.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside
+ */
+export * as aside from './aside';
+/**
+ * `<footer>` element factory namespace.
+ *
+ * Represents a footer for its nearest sectioning content or sectioning root,
+ * typically containing metadata, copyright information, or related links.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer
+ */
+export * as footer from './footer';
+/**
+ * `<header>` element factory namespace.
+ *
+ * Represents introductory content or navigational aids for a page or section,
+ * often containing headings, logos, or navigation elements.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header
+ */
+export * as header from './header';
+/**
+ * `<main>` element factory namespace.
+ *
+ * Represents the dominant content of the document body. There should only be
+ * one `<main>` element per document.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main
+ */
+export * as main from './main';
+/**
+ * `<nav>` element factory namespace.
+ *
+ * Represents a section of the page containing navigation links to other
+ * pages or parts of the current page.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav
+ */
+export * as nav from './nav';
+/**
+ * `<section>` element factory namespace.
+ *
+ * Represents a thematic grouping of content, typically with a heading.
+ * Sections contribute to the document outline.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
+ */
+export * as section from './section';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/elements/layout/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AAErC;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;;GAOG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC"}

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

@@ -0,0 +1,135 @@
+/**
+ * pkgn-sol Design Foundation: Main element helpers.
+ *
+ * @remarks
+ * The main element (`<main>`) represents the dominant content of the document.
+ * It is a landmark element that helps assistive technologies and other tooling
+ * identify the primary content area.
+ *
+ * Best-practice guidance:
+ * - Use **only one** `<main>` per document.
+ * - The content of `<main>` should be unique to the document (avoid repeated UI
+ *   like nav, site chrome, copyright, etc.).
+ * - Do not place `<main>` as a descendant of `<article>`, `<aside>`, `<footer>`,
+ *   `<header>`, or `<nav>`.
+ *
+ * Attributes:
+ * - `<main>` supports **global attributes only**.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create main landmarks in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * References:
+ * - MDN: Main element (`<main>`)
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for main landmarks.
+ *
+ * @category Constants
+ */
+export declare const MAIN_TAG: "main";
+/**
+ * A CSS selector targeting main elements.
+ *
+ * @category Constants
+ */
+export declare const MAIN_SELECTOR = "main";
+/**
+ * Attribute bag for main creation/enhancement.
+ *
+ * @remarks
+ * Main elements accept standard HTML global attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type MainAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a main element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * This helper does not enforce document-level semantics (e.g. "only one `<main>`")
+ * at runtime. That is a document-authoring responsibility.
+ *
+ * @param text - Optional text content for the main element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<main>` element.
+ *
+ * @example
+ * ```ts
+ * import { createMain } from "@lnpg/pkgn-sol/elements/layout/main";
+ *
+ * document.body.appendChild(
+ *   createMain(undefined, { id: "content", className: "page-main" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createMain(text?: string, attrs?: MainAttrs): ElementOf<typeof MAIN_TAG>;
+/**
+ * Enhance main elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceMains(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/layout/main/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,QAAQ,EAAG,MAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAClD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,QAAQ,CAAC,CAEvF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG9D"}

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

@@ -0,0 +1,136 @@
+/**
+ * pkgn-sol 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.
+ *
+ * pkgn-sol provides small, framework-agnostic helpers so consumers can:
+ * - create navigation regions without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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 pkgn-sol element factories.
+ *
+ * @remarks
+ * `<nav>` is a landmark with an implicit `navigation` role.
+ *
+ * pkgn-sol 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. pkgn-sol therefore omits `role` from {@link NavAttrs}.
+ *   Name navs via `aria-label` / `aria-labelledby` instead.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type 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 pkgn-sol's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the nav.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<nav>` element.
+ *
+ * @example
+ * Create a labelled primary navigation region:
+ * ```ts
+ * import { createNav } from "@lnpg/pkgn-sol/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 `0.1.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function 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"}