@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,143 @@
+/**
+ * pkgn-sol Design Foundation: rb element helpers.
+ *
+ * @remarks
+ * The rb element (`<rb>`) represents the ruby base text: the text being
+ * annotated within a `<ruby>` element.
+ *
+ * Best-practice guidance:
+ * - Use `<rb>` to wrap each atomic segment of base text when authoring complex
+ *   ruby annotations (e.g. multiple base units with paired `<rt>` annotations).
+ * - For simple ruby, the base text can be implicit (`<ruby>base<rt>anno</rt></ruby>`),
+ *   but using `<rb>` can improve clarity and pairing in complex markup.
+ * - `<rb>` is intended to be used within `<ruby>` (or within `<rtc>` in extended
+ *   ruby models), alongside `<rt>` / `<rp>` / `<rtc>` where applicable.
+ *
+ * Attributes:
+ * - `<rb>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * Implementation note:
+ * - In HTML source, `</rb>` may be omitted in certain sequences, but pkgn-sol creates
+ *   DOM nodes, so it always creates a concrete `<rb>` element.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<rb>` 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/Reference/Elements/rb
+ * @see https://www.w3.org/TR/html-ruby-extensions/
+ *
+ * @module
+ * @category Elements
+ */
+import { 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 ruby base units.
+ *
+ * @category Constants
+ */
+export declare const RB_TAG: "rb";
+/**
+ * A CSS selector targeting rb elements.
+ *
+ * @category Constants
+ */
+export declare const RB_SELECTOR = "rb";
+/**
+ * Attribute bag for rb creation/enhancement.
+ *
+ * @remarks
+ * `<rb>` 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.
+ *
+ * Security note:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style}.
+ *
+ * @category Attributes
+ */
+export type RbAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an rb 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.
+ *
+ * Note: `<rb>` is phrasing content. This helper supports a simple `text`
+ * convenience for cases where plain text is sufficient; consumers can still
+ * append richer child nodes afterwards.
+ *
+ * @param text - Optional text content for the rb element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<rb>` element.
+ *
+ * @example
+ * ```ts
+ * import { createRb } from "@lnpg/pkgn-sol/elements/inline/rb";
+ *
+ * const rb = createRb("漢", { className: "ruby-base" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createRb(text?: string, attrs?: RbAttrs): HTMLElement;
+/**
+ * Enhance rb 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 enhanceRbs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/rb/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAChD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAMpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

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

@@ -0,0 +1,123 @@
+/**
+ * pkgn-sol Design Foundation: Rp element helpers.
+ *
+ * @remarks
+ * The rp element (`<rp>`) provides fallback parentheses (or other markers) for
+ * ruby annotations when ruby rendering is not supported.
+ *
+ * Best-practice guidance:
+ * - Use `<rp>` only inside `<ruby>` as a fallback wrapper around `<rt>` content.
+ * - Keep `<rp>` content short (commonly "(" and ")").
+ * - Do not use `<rp>` for general punctuation or layout. Use normal text instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create rp elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol ever needs runtime behavior
+ *
+ * References:
+ * - MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/rp
+ *
+ * @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 rp elements.
+ *
+ * @category Constants
+ */
+export declare const RP_TAG: "rp";
+/**
+ * A CSS selector targeting rp elements.
+ *
+ * @category Constants
+ */
+export declare const RP_SELECTOR = "rp";
+/**
+ * Attribute bag for rp creation/enhancement.
+ *
+ * @remarks
+ * Rp 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 RpAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an rp 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 rp element (commonly "(" or ")").
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<rp>` element.
+ *
+ * @example
+ * Create a ruby fallback wrapper:
+ * ```ts
+ * import { createRp } from "@lnpg/pkgn-sol/elements/inline/rp";
+ *
+ * const open = createRp("(");
+ * const close = createRp(")");
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createRp(text?: string, attrs?: RpAttrs): ElementOf<typeof RP_TAG>;
+/**
+ * Enhance rp 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 enhanceRps(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/rp/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,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAChD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CAEjF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

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

@@ -0,0 +1,124 @@
+/**
+ * pkgn-sol Design Foundation: Rt element helpers.
+ *
+ * @remarks
+ * The rt element (`<rt>`) provides the ruby text component of a ruby annotation.
+ * Ruby annotations are commonly used to supply pronunciation, translation, or
+ * transliteration information (often in East Asian typography).
+ *
+ * Best-practice guidance:
+ * - `<rt>` must be used within a `<ruby>` element.
+ * - Use ruby for semantic annotation (pronunciation/reading aids), not for
+ *   purely presentational styling.
+ * - Prefer plain text via `textContent` for annotation content (pkgn-sol enforces
+ *   this by using `textContent`, never `innerHTML`).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<rt>` nodes 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/rt
+ *
+ * @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 ruby text annotations.
+ *
+ * @category Constants
+ */
+export declare const RT_TAG: "rt";
+/**
+ * A CSS selector targeting rt elements.
+ *
+ * @category Constants
+ */
+export declare const RT_SELECTOR = "rt";
+/**
+ * Attribute bag for rt creation/enhancement.
+ *
+ * @remarks
+ * Rt elements include only 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 RtAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an rt 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 rt element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<rt>` element.
+ *
+ * @example
+ * ```ts
+ * import { createRt } from "@lnpg/pkgn-sol/elements/inline/rt";
+ *
+ * // Intended usage: inside <ruby>
+ * const rt = createRt("kan");
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createRt(text?: string, attrs?: RtAttrs): ElementOf<typeof RT_TAG>;
+/**
+ * Enhance rt 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 enhanceRts(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/rt/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,MAAM,EAAG,IAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAChD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,MAAM,CAAC,CAEjF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG5D"}

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

@@ -0,0 +1,122 @@
+/**
+ * pkgn-sol Design Foundation: Rtc element helpers.
+ *
+ * @remarks
+ * The rtc element (`<rtc>`) is a ruby text container used within `<ruby>` to
+ * group ruby annotation text components, typically for semantic annotations.
+ *
+ * Best-practice guidance:
+ * - Use `<rtc>` only as part of `<ruby>` markup.
+ * - `<rtc>` has no element-specific attributes; it accepts global attributes.
+ *
+ * Note on DOM typing:
+ * - `<rtc>` is not part of {@link HTMLElementTagNameMap} in TypeScript's DOM
+ *   typings, so pkgn-sol creates it via `document.createElement("rtc")` and returns
+ *   an {@link HTMLElement}.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create rtc 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.
+ *
+ * @module
+ * @category Elements
+ */
+import { 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 ruby text containers.
+ *
+ * @category Constants
+ */
+export declare const RTC_TAG: "rtc";
+/**
+ * A CSS selector targeting rtc elements.
+ *
+ * @category Constants
+ */
+export declare const RTC_SELECTOR = "rtc";
+/**
+ * Attribute bag for rtc creation/enhancement.
+ *
+ * @remarks
+ * The `<rtc>` element uses standard HTML global attributes and has no
+ * element-specific 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 RtcAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an rtc 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.
+ *
+ * Note: `<rtc>` is not part of {@link HTMLElementTagNameMap}, so pkgn-sol creates it
+ * via `document.createElement("rtc")` and returns {@link HTMLElement}.
+ *
+ * @param text - Optional text content for the rtc element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<rtc>` element.
+ *
+ * @category DOM
+ */
+export declare function createRtc(text?: string, attrs?: RtcAttrs): HTMLElement;
+/**
+ * Enhance rtc 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 enhanceRtcs(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/rtc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;;;;;;;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;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACjD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,WAAW,CAQtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG7D"}

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

@@ -0,0 +1,147 @@
+/**
+ * pkgn-sol Design Foundation: ruby element helpers.
+ *
+ * @remarks
+ * The ruby element (`<ruby>`) represents ruby annotations: small annotation text
+ * rendered above, below, or next to base text (commonly used for pronunciation,
+ * transliteration, or translation in East Asian typography).
+ *
+ * Best-practice guidance:
+ * - Prefer correct ruby structure: base text followed by `<rt>` for annotation text.
+ * - Use `<rp>` to provide fallback parentheses for user agents that do not support
+ *   ruby rendering. Modern browsers generally ignore `<rp>` when ruby is supported,
+ *   but it improves graceful degradation.
+ * - For complex ruby (multiple base segments / multiple annotations), consider
+ *   using `<rb>` to delimit base segments and `<rtc>` for semantic annotation groupings.
+ * - Avoid using `innerHTML` for untrusted content. pkgn-sol assigns text via `textContent`.
+ *
+ * Attributes:
+ * - `<ruby>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<ruby>` 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/Reference/Elements/ruby
+ * @see https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-ruby-element
+ * @see https://www.w3.org/TR/ruby-use-cases/
+ *
+ * @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 ruby annotation containers.
+ *
+ * @category Constants
+ */
+export declare const RUBY_TAG: "ruby";
+/**
+ * A CSS selector targeting ruby elements.
+ *
+ * @category Constants
+ */
+export declare const RUBY_SELECTOR = "ruby";
+/**
+ * Attribute bag for ruby creation/enhancement.
+ *
+ * @remarks
+ * `<ruby>` 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.
+ *
+ * Security note:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style}.
+ *
+ * @category Attributes
+ */
+export type RubyAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a ruby 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.
+ *
+ * Note:
+ * - `<ruby>` typically contains mixed children (`<rt>`, `<rp>`, `<rb>`, etc.).
+ *   The `text` argument is a convenience for simple cases; consumers can append
+ *   richer child nodes afterwards.
+ *
+ * @param text - Optional text content for the ruby element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<ruby>` element.
+ *
+ * @example
+ * ```ts
+ * import { createRuby } from "@lnpg/pkgn-sol/elements/inline/ruby";
+ *
+ * const ruby = createRuby();
+ * ruby.append(
+ *   document.createTextNode("漢"),
+ *   document.createElement("rt")
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createRuby(text?: string, attrs?: RubyAttrs): ElementOf<typeof RUBY_TAG>;
+/**
+ * Enhance ruby 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 enhanceRubies(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/inline/ruby/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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;AA4BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,QAAQ,CAAC,CAEvF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}