@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,229 @@
+/**
+ * Inline text element factories.
+ *
+ * Provides framework-agnostic factory functions for semantic and typographic
+ * inline elements used inside paragraphs, headings, labels, and other text
+ * content.
+ *
+ * These factories:
+ * - Create semantic inline elements using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Encourage accessible, standards-aligned markup.
+ * - Prevent unsafe attribute injection.
+ *
+ * Inline elements refine meaning (emphasis, citations, abbreviations), express
+ * user input or code, and support annotations such as Ruby text.
+ *
+ * @module elements/inline
+ * @since 0.1.0
+ */
+/**
+ * `<a>` element factory namespace.
+ *
+ * Represents a hyperlink to another location.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
+ */
+export * as anchor from './a';
+/**
+ * `<abbr>` element factory namespace.
+ *
+ * Represents an abbreviation or acronym, typically with a `title` expansion.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr
+ */
+export * as abbr from './abbr';
+/**
+ * `<b>` element factory namespace.
+ *
+ * Represents stylistically offset text without conveying extra importance.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/b
+ */
+export * as b from './b';
+/**
+ * `<small>` element factory namespace.
+ *
+ * Represents side comments or small print.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small
+ */
+export * as small from './small';
+/**
+ * `<strong>` element factory namespace.
+ *
+ * Represents strong importance, seriousness, or urgency.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong
+ */
+export * as strong from './strong';
+/**
+ * `<cite>` element factory namespace.
+ *
+ * Represents the title of a cited creative work.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite
+ */
+export * as cite from './cite';
+/**
+ * `<code>` element factory namespace.
+ *
+ * Represents a fragment of computer code.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code
+ */
+export * as code from './code';
+/**
+ * `<data>` element factory namespace.
+ *
+ * Associates a machine-readable value with human-readable content.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/data
+ */
+export * as data from './data';
+/**
+ * `<dfn>` element factory namespace.
+ *
+ * Represents the defining instance of a term.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn
+ */
+export * as dfn from './dfn';
+/**
+ * `<em>` element factory namespace.
+ *
+ * Represents stress emphasis.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em
+ */
+export * as em from './em';
+/**
+ * `<i>` element factory namespace.
+ *
+ * Represents text in an alternate voice or mood, or otherwise offset from normal prose.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i
+ */
+export * as italic from './i';
+/**
+ * `<kbd>` element factory namespace.
+ *
+ * Represents user input, typically keyboard input.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd
+ */
+export * as kbd from './kbd';
+/**
+ * `<mark>` element factory namespace.
+ *
+ * Represents text marked or highlighted for reference.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+ */
+export * as mark from './mark';
+/**
+ * `<q>` element factory namespace.
+ *
+ * Represents a short inline quotation.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q
+ */
+export * as q from './q';
+/**
+ * `<rb>` element factory namespace.
+ *
+ * Represents the base text component of a ruby annotation.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/rb
+ */
+export * as rb from './rb';
+/**
+ * `<rp>` element factory namespace.
+ *
+ * Represents fallback parentheses for ruby annotations.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/rp
+ */
+export * as rp from './rp';
+/**
+ * `<rt>` element factory namespace.
+ *
+ * Represents ruby text, the pronunciation/annotation for base text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/rt
+ */
+export * as rt from './rt';
+/**
+ * `<rtc>` element factory namespace.
+ *
+ * Represents a ruby text container for semantic annotation groups.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/rtc
+ */
+export * as rtc from './rtc';
+/**
+ * `<ruby>` element factory namespace.
+ *
+ * Represents ruby annotations for East Asian typography.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ruby
+ */
+export * as ruby from './ruby';
+/**
+ * `<s>` element factory namespace.
+ *
+ * Represents content that is no longer accurate or relevant.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s
+ */
+export * as s from './s';
+/**
+ * `<samp>` element factory namespace.
+ *
+ * Represents sample output from a program or computing system.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp
+ */
+export * as samp from './samp';
+/**
+ * `<sub>` element factory namespace.
+ *
+ * Represents subscript text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+ */
+export * as sub from './sub';
+/**
+ * `<sup>` element factory namespace.
+ *
+ * Represents superscript text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
+ */
+export * as sup from './sup';
+/**
+ * `<time>` element factory namespace.
+ *
+ * Represents a specific time period, optionally with a machine-readable `datetime`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time
+ */
+export * as time from './time';
+/**
+ * `<u>` element factory namespace.
+ *
+ * Represents unarticulated annotation, such as misspelled text or proper names in some contexts.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u
+ */
+export * as u from './u';
+/**
+ * `<var>` element factory namespace.
+ *
+ * Represents a variable in a mathematical expression or programming context.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/var
+ */
+export * as var from './var';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/elements/inline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;GAMG;AACH,OAAO,KAAK,MAAM,MAAM,KAAK,CAAC;AAE9B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;GAMG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC;;;;;;GAMG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,MAAM,CAAC;AAE3B;;;;;;GAMG;AACH,OAAO,KAAK,MAAM,MAAM,KAAK,CAAC;AAE9B;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,MAAM,CAAC;AAE3B;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,MAAM,CAAC;AAE3B;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,MAAM,CAAC;AAE3B;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;;;;;GAMG;AACH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;GAMG;AACH,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC"}

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

@@ -0,0 +1,123 @@
+/**
+ * pkgn-sol Design Foundation: Kbd (`kbd`) element helpers.
+ *
+ * @remarks
+ * The kbd element (`<kbd>`) represents user input, typically keyboard input,
+ * but it may also represent input via other mechanisms (e.g. voice commands).
+ *
+ * Best-practice guidance:
+ * - Use `<kbd>` for inline, human-readable input instructions (keys, shortcuts, commands).
+ * - For key combinations, it is common to wrap the whole sequence in an outer `<kbd>`
+ *   and each individual key as inner `<kbd>` elements (e.g. `<kbd><kbd>Ctrl</kbd>+<kbd>S</kbd></kbd>`).
+ * - Do not rely on default styling; apply CSS for consistent presentation.
+ *
+ * Security notes:
+ * - pkgn-sol blocks unsafe attribute *names* (e.g. `onclick`, raw `style`) via `dom.ts`.
+ * - pkgn-sol does not sanitize attribute *values*. Treat untrusted inputs accordingly.
+ *
+ * References:
+ * - MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd
+ * - WHATWG: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-kbd-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 kbd elements.
+ *
+ * @category Constants
+ */
+export declare const KBD_TAG: "kbd";
+/**
+ * A CSS selector targeting kbd elements.
+ *
+ * @category Constants
+ */
+export declare const KBD_SELECTOR = "kbd";
+/**
+ * Attribute bag for kbd creation/enhancement.
+ *
+ * @remarks
+ * Kbd 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 KbdAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a kbd 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 kbd element (e.g. "Ctrl", "⌘", "F3").
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<kbd>` element.
+ *
+ * @example
+ * ```ts
+ * import { createKbd } from "@lnpg/pkgn-sol/elements/inline/kbd";
+ *
+ * const shortcut = createKbd(undefined, { className: "keys" });
+ * shortcut.append(createKbd("Ctrl"), document.createTextNode("+"), createKbd("S"));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createKbd(text?: string, attrs?: KbdAttrs): ElementOf<typeof KBD_TAG>;
+/**
+ * Enhance kbd 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 enhanceKbds(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/kbd/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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,OAAO,EAAG,KAAc,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACjD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;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/inline/mark/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * pkgn-sol Design Foundation: Mark element helpers.
+ *
+ * @remarks
+ * The mark element (`<mark>`) represents text that is marked or highlighted for
+ * reference or notation because it is relevant in the current context.
+ *
+ * Common, semantic uses:
+ * - Highlighting search matches within results or a document.
+ * - Marking passages being referenced elsewhere (e.g. annotated excerpts).
+ *
+ * Best-practice guidance:
+ * - Use `<mark>` when the highlight communicates contextual relevance, not merely
+ *   a visual style.
+ * - Prefer CSS for purely presentational highlighting.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create marked text 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/mark
+ *
+ * @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 marked/highlighted text.
+ *
+ * @category Constants
+ */
+export declare const MARK_TAG: "mark";
+/**
+ * A CSS selector targeting mark elements.
+ *
+ * @category Constants
+ */
+export declare const MARK_SELECTOR = "mark";
+/**
+ * Attribute bag for mark creation/enhancement.
+ *
+ * @remarks
+ * Mark 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 MarkAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a mark 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 mark element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<mark>` element.
+ *
+ * @example
+ * ```ts
+ * import { createMark } from "@lnpg/pkgn-sol/elements/inline/mark";
+ *
+ * // Highlight a search match:
+ * document.body.appendChild(createMark("kitchen", { className: "match" }));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createMark(text?: string, attrs?: MarkAttrs): ElementOf<typeof MARK_TAG>;
+/**
+ * Enhance mark 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 enhanceMarks(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

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

@@ -0,0 +1,138 @@
+/**
+ * pkgn-sol Design Foundation: Q element helpers.
+ *
+ * @remarks
+ * The q element (`<q>`) indicates that the enclosed text is a short inline
+ * quotation. Most modern browsers render it with quotation punctuation. This
+ * element is intended for quotations that do not require paragraph breaks; for
+ * longer quotations, use `<blockquote>`. :contentReference[oaicite:3]{index=3}
+ *
+ * Best-practice guidance:
+ * - Use `<q>` for short inline quotations; use `<blockquote>` for longer quotes.
+ * - Do not manually insert quotation punctuation immediately around `<q>`; user
+ *   agents may insert punctuation as part of rendering. :contentReference[oaicite:4]{index=4}
+ * - If you want a visible, user-facing citation link, use an `<a>` element.
+ *   The optional `cite` attribute on `<q>` is a URL for the quotation source and
+ *   is often treated as metadata. :contentReference[oaicite:5]{index=5}
+ *
+ * Security note:
+ * - pkgn-sol does not attempt to validate or sanitize URLs. If `cite` is derived from
+ *   untrusted input, validate it at the application boundary.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create inline quotations 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 inline quotations.
+ *
+ * @category Constants
+ */
+export declare const Q_TAG: "q";
+/**
+ * A CSS selector targeting q elements.
+ *
+ * @category Constants
+ */
+export declare const Q_SELECTOR = "q";
+/**
+ * Attribute bag for q creation/enhancement.
+ *
+ * @remarks
+ * The `<q>` element uses standard HTML global attributes and supports an
+ * optional `cite` attribute, which provides a URL for the quotation source. :contentReference[oaicite:6]{index=6}
+ *
+ * pkgn-sol supports structured ARIA for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type QAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * A URL for the source of the quotation.
+     *
+     * @remarks
+     * This reflects the `cite` attribute used by `<q>` (and `<blockquote>`).
+     * User agents may expose it, but it is often treated as metadata. :contentReference[oaicite:7]{index=7}
+     */
+    cite?: string;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a q 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.
+ * - The optional `cite` attribute is applied via the `attrs` escape hatch. :contentReference[oaicite:8]{index=8}
+ *
+ * @param text - Optional text content for the q element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<q>` element.
+ *
+ * @example
+ * Inline quotation with source metadata:
+ * ```ts
+ * import { createQ } from "@lnpg/pkgn-sol/elements/inline/q";
+ *
+ * const q = createQ("We choose to go to the Moon.", {
+ *   cite: "https://example.com/speech",
+ *   aria: { label: "Inline quotation" }
+ * });
+ *
+ * document.body.appendChild(q);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createQ(text?: string, attrs?: QAttrs): ElementOf<typeof Q_TAG>;
+/**
+ * Enhance q elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceQs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/q/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,KAAK,EAAG,GAAY,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAC/C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAwDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,KAAK,CAAC,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG3D"}