@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/inline/rp/index.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 { createElement, 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 const RP_TAG = 'rp' as const;
+
+/**
+ * A CSS selector targeting rp elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link RpAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The rp attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: RpAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * 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 function createRp(text?: string, attrs?: RpAttrs): ElementOf<typeof RP_TAG> {
+  return createElement(RP_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * 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 function enhanceRps(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for rp.
+  void root;
+}

package/src/elements/inline/rp/rp.scss

@@ -0,0 +1,41 @@
+/**
+ * pkgn-sol Design Foundation: RP Element
+ *
+ * Ruby fallback parentheses (`rp`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - `<rp>` provides fallback parentheses for user agents that don't support ruby rendering.
+ * - In supporting browsers, `<rp>` is typically not rendered; in fallback contexts,
+ *   it should behave like neutral inline text.
+ * - Do not override display; preserve intrinsic ruby/fallback behavior.
+ *
+ * References (2025+):
+ * - MDN: `<rp>` element reference (updated Feb 2026)
+ * - MDN: CSS ruby layout guide (updated Nov 2025)
+ *
+ * @module
+ * @group  elements.inline.rp
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(rp) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve intrinsic ruby formatting model behavior.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Inherit typography from surrounding context.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

package/src/elements/inline/rt/index.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 { createElement, 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 const RT_TAG = 'rt' as const;
+
+/**
+ * A CSS selector targeting rt elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link RtAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The rt attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: RtAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * 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 function createRt(text?: string, attrs?: RtAttrs): ElementOf<typeof RT_TAG> {
+  return createElement(RT_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * 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 function enhanceRts(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for rt.
+  void root;
+}

package/src/elements/inline/rt/rt.scss

@@ -0,0 +1,36 @@
+/**
+ * pkgn-sol Design Foundation: RT Element
+ *
+ * Ruby text (`rt`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - `<rt>` provides the annotation text (pronunciation/translation/etc.) for `<ruby>`.
+ * - Ruby layout is handled by the ruby formatting model; do not override display.
+ *
+ * @module
+ * @group  elements.inline.rt
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(rt) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve intrinsic ruby formatting model behavior.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Inherit typography from surrounding context.
+  // (Do not force font-size here; sizing is often controlled at ruby level.)
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

package/src/elements/inline/rtc/index.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 { applyGlobalAttrs, 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 const RTC_TAG = 'rtc' as const;
+
+/**
+ * A CSS selector targeting rtc elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link RtcAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The rtc attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: RtcAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * 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 function createRtc(text?: string, attrs?: RtcAttrs): HTMLElement {
+  const el = document.createElement(RTC_TAG);
+
+  applyGlobalAttrs(el, toGlobalAttrs(attrs));
+
+  if (typeof text === 'string') el.textContent = text;
+
+  return el;
+}
+
+/**
+ * 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 function enhanceRtcs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for rtc.
+  void root;
+}

package/src/elements/inline/rtc/rtc.scss

@@ -0,0 +1,40 @@
+/**
+ * pkgn-sol Design Foundation: RTC Element
+ *
+ * Ruby text container (`rtc`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - `<rtc>` groups semantic annotations for `<rb>` base text within `<ruby>`.
+ * - Ruby layout is governed by the ruby formatting model; do not override display.
+ * - Avoid presentational styling here. Any styling belongs at the ruby system level.
+ *
+ * References (2025+):
+ * - MDN: `<rtc>` element reference (updated Feb 2026)
+ * - MDN: CSS ruby layout guide (updated Nov 2025)
+ *
+ * @module
+ * @group  elements.inline.rtc
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(rtc) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve intrinsic ruby formatting model behavior.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Inherit typography from surrounding context.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}