@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/inline/a/index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * pkgn-sol Design Foundation: Anchor (`a`) element helpers.
+ *
+ * @remarks
+ * The anchor element (`<a>`) creates a hyperlink when the `href` attribute is
+ * present. It can link to web pages, files, email addresses, locations within
+ * the same page, or any URL-addressable resource.
+ *
+ * Best-practice guidance:
+ * - Prefer clear, descriptive link text. Avoid "click here".
+ * - If using `target="_blank"`, strongly consider `rel="noopener noreferrer"`
+ *   to prevent opener-based attacks (reverse tabnabbing).
+ * - Do not use `<a>` as a button. Use `<button>` for actions and controls.
+ * - Validate/sanitize untrusted URLs before assigning them to `href`.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create anchors 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: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
+ * - WHATWG: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element
+ * - MDN rel=noopener: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/noopener
+ * - MDN rel=noreferrer: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/noreferrer
+ *
+ * @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`.
+     *
+     * @remarks
+     * Prefer `labelledby` when a visible labeling element exists.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * Common targets for anchor navigation.
+ *
+ * @remarks
+ * Browsers also accept custom named targets (e.g. `myWindow`).
+ *
+ * @category Attributes
+ */
+export type AnchorTarget = '_self' | '_blank' | '_parent' | '_top' | (string & {});
+/**
+ * Allowed values for the `referrerpolicy` attribute.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/referrerpolicy
+ *
+ * @category Attributes
+ */
+export type ReferrerPolicy = 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+/**
+ * The semantic tag name for anchors.
+ *
+ * @category Constants
+ */
+export declare const A_TAG: "a";
+/**
+ * A CSS selector targeting anchor elements.
+ *
+ * @category Constants
+ */
+export declare const A_SELECTOR = "a";
+/**
+ * Attribute bag for anchor creation/enhancement.
+ *
+ * @remarks
+ * Anchor elements accept standard HTML global attributes, plus link-related
+ * attributes such as `href`, `target`, and `rel`.
+ *
+ * Security notes:
+ * - pkgn-sol blocks unsafe attribute *names* (e.g. `onclick`, raw `style`).
+ * - pkgn-sol does not sanitize attribute *values*. Callers must validate untrusted
+ *   URLs before passing them as `href`.
+ * - When `target="_blank"` is used and `rel` is not provided, pkgn-sol applies a
+ *   conservative default: `rel="noopener noreferrer"`.
+ *
+ * @category Attributes
+ */
+export type AnchorAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Destination URL for the hyperlink.
+     *
+     * @remarks
+     * If omitted, the anchor is not a hyperlink.
+     */
+    href?: string;
+    /**
+     * Where to display the linked URL.
+     */
+    target?: AnchorTarget;
+    /**
+     * Relationship between the current document and the linked resource.
+     *
+     * @remarks
+     * If `target="_blank"` is used and `rel` is not provided, pkgn-sol applies
+     * `noopener noreferrer` by default.
+     */
+    rel?: string;
+    /**
+     * Indicates the linked resource should be downloaded.
+     *
+     * @remarks
+     * - `true` sets a bare `download` attribute.
+     * - A string sets the suggested filename.
+     */
+    download?: boolean | string;
+    /**
+     * Language of the linked resource.
+     */
+    hreflang?: string;
+    /**
+     * Space-separated list of URLs to notify (POST "ping") when the link is followed.
+     *
+     * @remarks
+     * Limited browser support; use with care.
+     */
+    ping?: string | string[];
+    /**
+     * Referrer policy for the request initiated by following the hyperlink.
+     */
+    referrerPolicy?: ReferrerPolicy;
+    /**
+     * MIME type hint for the linked resource.
+     */
+    type?: string;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an anchor element with optional text content and 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 anchor.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<a>` element.
+ *
+ * @example
+ * ```ts
+ * import { createA } from "@lnpg/pkgn-sol/elements/inline/a";
+ *
+ * document.body.appendChild(
+ *   createA("Read more", { href: "/docs", className: "link" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createA(text?: string, attrs?: AnchorAttrs): ElementOf<typeof A_TAG>;
+/**
+ * Enhance anchor 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 enhanceAs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/a/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/a/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;;;;;OAKG;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;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,4BAA4B,GAC5B,QAAQ,GACR,0BAA0B,GAC1B,aAAa,GACb,eAAe,GACf,iCAAiC,GACjC,YAAY,CAAC;AAEjB;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAG,GAAY,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA2DF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,KAAK,CAAC,CAEnF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG3D"}

package/dist/types/elements/inline/abbr/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * pkgn-sol Design Foundation: Abbreviation (`abbr`) element helpers.
+ *
+ * @remarks
+ * The abbreviation element (`<abbr>`) represents an abbreviation or acronym.
+ *
+ * Best-practice guidance:
+ * - Provide the expanded form in plain text on first use where possible.
+ * - Optionally provide an expansion via the `title` attribute.
+ *   Spec guidance: if `title` is used on `<abbr>`, it should contain the expansion
+ *   of the abbreviation and nothing else.
+ * - Do not rely solely on `title` tooltips for accessibility; tooltip exposure
+ *   varies across browsers and assistive technologies.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create abbr 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.
+ *
+ * References:
+ * - MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr
+ * - WHATWG: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-abbr-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 abbreviations.
+ *
+ * @category Constants
+ */
+export declare const ABBR_TAG: "abbr";
+/**
+ * A CSS selector targeting abbr elements.
+ *
+ * @category Constants
+ */
+export declare const ABBR_SELECTOR = "abbr";
+/**
+ * Attribute bag for abbr creation/enhancement.
+ *
+ * @remarks
+ * Abbr elements accept standard HTML global attributes.
+ *
+ * For expansions, prefer:
+ * - expanding the term in plain text on first use, and/or
+ * - using {@link GlobalAttrs.title} to provide an expansion (advisory text).
+ *
+ * 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 AbbrAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an abbr element with optional text content and 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 abbreviation (e.g. "NASA").
+ * @param attrs - Optional attributes to apply (e.g. `title` for expansion).
+ * @returns The created `<abbr>` element.
+ *
+ * @example
+ * ```ts
+ * import { createAbbr } from "@lnpg/pkgn-sol/elements/inline/abbr";
+ *
+ * const el = createAbbr("NASA", { title: "National Aeronautics and Space Administration" });
+ * document.body.appendChild(el);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createAbbr(text?: string, attrs?: AbbrAttrs): ElementOf<typeof ABBR_TAG>;
+/**
+ * Enhance abbr 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 enhanceAbbrs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/abbr/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/abbr/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,QAAQ,EAAG,MAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAClD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;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/inline/b/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * pkgn-sol Design Foundation: B element helpers.
+ *
+ * @remarks
+ * The b element (`<b>`) represents a span of text to which attention is being
+ * drawn for utilitarian purposes, without conveying extra importance.
+ *
+ * Best-practice guidance:
+ * - Use `<b>` to draw attention without implying importance.
+ * - Use `<strong>` for strong importance and `<em>` for stress emphasis.
+ * - Do not use `<b>` purely for styling. Prefer CSS (e.g. `font-weight`) when the
+ *   goal is visual bolding rather than semantics.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create inline attention spans in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/b
+ *
+ * @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 "bring attention to" spans.
+ *
+ * @category Constants
+ */
+export declare const B_TAG: "b";
+/**
+ * A CSS selector targeting b elements.
+ *
+ * @category Constants
+ */
+export declare const B_SELECTOR = "b";
+/**
+ * Attribute bag for b creation/enhancement.
+ *
+ * @remarks
+ * B 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 BAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a b 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 b element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<b>` element.
+ *
+ * @example
+ * ```ts
+ * import { createB } from "@lnpg/pkgn-sol/elements/inline/b";
+ *
+ * document.body.appendChild(createB("Keyword", { className: "keyword" }));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createB(text?: string, attrs?: BAttrs): ElementOf<typeof B_TAG>;
+/**
+ * Enhance b 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 enhanceBs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/b/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/b/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,KAAK,EAAG,GAAY,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAC/C;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,KAAK,CAAC,CAE9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG3D"}

package/dist/types/elements/inline/cite/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * pkgn-sol Design Foundation: Cite element helpers.
+ *
+ * @remarks
+ * The cite element (`<cite>`) represents the title of a creative work (e.g. a book,
+ * paper, essay, poem, song, film, TV show, game, sculpture, painting, etc.). :contentReference[oaicite:2]{index=2}
+ *
+ * Best-practice guidance:
+ * - Use `<cite>` for the title of the work being referenced, not the author's name
+ *   and not purely for styling. :contentReference[oaicite:3]{index=3}
+ * - If you want a visible link to a source, use an `<a>` element (and/or surrounding
+ *   citation patterns) rather than relying on hidden metadata. (pkgn-sol intentionally
+ *   does not invent citation-specific behaviors here.)
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create cite inline nodes 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.
+ *
+ * @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 cite.
+ *
+ * @category Constants
+ */
+export declare const CITE_TAG: "cite";
+/**
+ * A CSS selector targeting cite elements.
+ *
+ * @category Constants
+ */
+export declare const CITE_SELECTOR = "cite";
+/**
+ * Attribute bag for cite creation/enhancement.
+ *
+ * @remarks
+ * The `<cite>` element uses standard HTML global attributes. :contentReference[oaicite:4]{index=4}
+ *
+ * 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 CiteAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a cite 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 cite element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<cite>` element.
+ *
+ * @example
+ * Cite a work title:
+ * ```ts
+ * import { createCite } from "@lnpg/pkgn-sol/elements/inline/cite";
+ *
+ * const c = createCite("The Scream", { className: "work-title" });
+ * document.body.appendChild(c);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createCite(text?: string, attrs?: CiteAttrs): ElementOf<typeof CITE_TAG>;
+/**
+ * Enhance cite 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 enhanceCites(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/inline/cite/index.d.ts.map

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