@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,165 @@
+/**
+ * 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 { 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 marked/highlighted text.
+ *
+ * @category Constants
+ */
+export const MARK_TAG = 'mark' as const;
+
+/**
+ * A CSS selector targeting mark elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link MarkAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The mark attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: MarkAttrs): 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 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 function createMark(text?: string, attrs?: MarkAttrs): ElementOf<typeof MARK_TAG> {
+  return createElement(MARK_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * 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 function enhanceMarks(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for mark.
+  void root;
+}

package/src/elements/inline/mark/mark.scss

@@ -0,0 +1,45 @@
+/**
+ * pkgn-sol Design Foundation: Mark Element
+ *
+ * Highlighted text (`mark`)
+ *
+ * Baseline reset + token-driven highlight.
+ *
+ * Notes:
+ * - `<mark>` represents relevant or highlighted text.
+ * - Replace UA yellow with brand token-based highlight.
+ * - Preserve contrast and readability.
+ *
+ * References (2025+):
+ * - MDN: `<mark>` element reference (Oct 2025)
+ *
+ * @module
+ * @group  elements.inline.mark
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(mark) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned highlight
+   -------------------------------------------------------------------------- */
+
+  background-color: var(--lg-colour-yellow-tint-50);
+  color: var(--lg-theme-base-colours-base-font-color);
+
+  // Preserve inherited typography metrics.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+}

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

@@ -0,0 +1,206 @@
+/**
+ * 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 { 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 inline quotations.
+ *
+ * @category Constants
+ */
+export const Q_TAG = 'q' as const;
+
+/**
+ * A CSS selector targeting q elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Set an attribute value only if that key is currently unset.
+ *
+ * @remarks
+ * This supports pkgn-sol's "escape hatch" convention where `attrs.attrs` can override
+ * any element-specific mappings.
+ *
+ * @category Internal
+ */
+function setIfUnset(
+  bag: Record<string, import('../../../ts/dom').AttrValue>,
+  key: string,
+  value: import('../../../ts/dom').AttrValue,
+): void {
+  if (typeof bag[key] === 'undefined') bag[key] = value;
+}
+
+/**
+ * Normalize {@link QAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The q attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: QAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, cite, ...rest } = attrs;
+
+  // Start with global attrs.
+  const out: GlobalAttrs = { ...rest };
+
+  // Map element-specific attributes into the escape hatch bag.
+  if (typeof cite === 'string' && cite.length > 0) {
+    const bag: NonNullable<GlobalAttrs['attrs']> = { ...(out.attrs ?? {}) };
+    setIfUnset(bag, 'cite', cite);
+    out.attrs = bag;
+  }
+
+  // Map structured ARIA.
+  if (!aria) return out;
+
+  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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...out, aria: mappedAria } : out;
+}
+
+/**
+ * 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 function createQ(text?: string, attrs?: QAttrs): ElementOf<typeof Q_TAG> {
+  return createElement(Q_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * 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 function enhanceQs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for q.
+  void root;
+}

package/src/elements/inline/q/q.scss

@@ -0,0 +1,44 @@
+/**
+ * pkgn-sol Design Foundation: Q Element
+ *
+ * Inline quotation (`q`)
+ *
+ * Baseline reset only.
+ *
+ * This module:
+ * - Preserves UA-generated quotation marks
+ * - Avoids destructive resets (no quote removal)
+ * - Normalizes inline behavior
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.q
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(q) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Preserve browser-managed quotes (do NOT set quotes: none)
+  // This maintains locale-aware punctuation behavior.
+
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Ensure robust inline wrapping.
+  overflow-wrap: break-word;
+
+  // Preserve inherited typography.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,186 @@
+/**
+ * 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 { createElement, 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 const RB_TAG = 'rb' as const;
+
+/**
+ * A CSS selector targeting rb elements.
+ *
+ * @category Constants
+ */
+export 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;
+};
+
+/**
+ * Normalize {@link RbAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The rb attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: RbAttrs): 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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * 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 function createRb(text?: string, attrs?: RbAttrs): HTMLElement {
+  return createElement(
+    RB_TAG as unknown as keyof HTMLElementTagNameMap,
+    toGlobalAttrs(attrs),
+    text,
+  ) as unknown as 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 function enhanceRbs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for rb.
+  void root;
+}

package/src/elements/inline/rb/rb.scss

@@ -0,0 +1,35 @@
+/**
+ * pkgn-sol Design Foundation: RB Element
+ *
+ * Ruby base (`rb`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - `<rb>` delimits the base text being annotated inside `<ruby>`.
+ * - Ruby layout is handled by the ruby formatting model; do not override display.
+ *
+ * @module
+ * @group  elements.inline.rb
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(rb) {
+  /* --------------------------------------------------------------------------
+   - 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;
+}