@lnpg/pkgn-sol 1.0.0-beta.0

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

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

package/src/elements/inline/ruby/ruby.scss

@@ -0,0 +1,39 @@
+/**
+ * pkgn-sol Design Foundation: Ruby Element
+ *
+ * Ruby annotation container (`ruby`)
+ *
+ * Baseline reset only.
+ *
+ * Notes:
+ * - `<ruby>` establishes a ruby formatting context.
+ * - Do NOT override display; preserve intrinsic ruby behavior.
+ * - Avoid interfering with annotation layout.
+ *
+ * References (2025+):
+ * - MDN: `<ruby>` element reference (Sep 2025)
+ *
+ * @module
+ * @group  elements.inline.ruby
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(ruby) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Preserve intrinsic ruby layout behavior.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Maintain inherited typography context.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,165 @@
+/**
+ * pkgn-sol Design Foundation: S (strikethrough) element helpers.
+ *
+ * @remarks
+ * The s element (`<s>`) represents content that is no longer accurate or no
+ * longer relevant. It is a presentational indicator of "this isn't current"
+ * rather than an edit-tracking semantic.
+ *
+ * Best-practice guidance:
+ * - Use `<s>` for "no longer relevant/accurate" text (e.g. outdated pricing).
+ * - Use `<del>` when you mean "this was removed" (edit history / document diff semantics).
+ * - Do not use `<s>` as a substitute for emphasis; use appropriate semantics and CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<s>` 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/Element/s
+ *
+ * @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.
+ *
+ * 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 s elements.
+ *
+ * @category Constants
+ */
+export const S_TAG = 's' as const;
+
+/**
+ * A CSS selector targeting s elements.
+ *
+ * @category Constants
+ */
+export const S_SELECTOR = 's';
+
+/**
+ * Attribute bag for s creation/enhancement.
+ *
+ * @remarks
+ * The `<s>` element 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.
+ *
+ * @category Attributes
+ */
+export type SAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link SAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The s attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: SAttrs): 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 s 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 element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<s>` element.
+ *
+ * @example
+ * ```ts
+ * import { createS } from "@lnpg/pkgn-sol/elements/inline/s";
+ *
+ * const el = createS("£199", { className: "old-price" });
+ * document.body.appendChild(el);
+ * ```
+ *
+ * @category DOM
+ */
+export function createS(text?: string, attrs?: SAttrs): ElementOf<typeof S_TAG> {
+  return createElement(S_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance s 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 enhanceSs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for s.
+  void root;
+}

package/src/elements/inline/s/s.scss

@@ -0,0 +1,37 @@
+/**
+ * pkgn-sol Design Foundation: S Element
+ *
+ * Strikethrough / no longer accurate (`s`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Preserves semantic strikethrough intent explicitly
+ * - Normalizes decoration rendering via currentColor
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.s
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(s) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // Preserve semantic strikethrough.
+  text-decoration-line: line-through;
+  text-decoration-color: currentcolor;
+
+  // Preserve inherited typography context.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,162 @@
+/**
+ * pkgn-sol Design Foundation: Samp element helpers.
+ *
+ * @remarks
+ * The samp element (`<samp>`) represents sample (or quoted) output from another
+ * program or computing system.
+ *
+ * Best-practice guidance:
+ * - Use `<samp>` for *output* (what the computer/system printed).
+ * - Use `<kbd>` for user input (what the user typed/pressed).
+ * - Use `<code>` for code fragments (source code).
+ * - Use CSS for presentation; semantics should match meaning.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create samp 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/samp
+ *
+ * @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 sample output.
+ *
+ * @category Constants
+ */
+export const SAMP_TAG = 'samp' as const;
+
+/**
+ * A CSS selector targeting samp elements.
+ *
+ * @category Constants
+ */
+export const SAMP_SELECTOR = 'samp';
+
+/**
+ * Attribute bag for samp creation/enhancement.
+ *
+ * @remarks
+ * Samp 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 SampAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link SampAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The samp attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: SampAttrs): 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 samp 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 samp element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<samp>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSamp } from "@lnpg/pkgn-sol/elements/inline/samp";
+ *
+ * // Sample output:
+ * const out = createSamp("Everything up-to-date");
+ * ```
+ *
+ * @category DOM
+ */
+export function createSamp(text?: string, attrs?: SampAttrs): ElementOf<typeof SAMP_TAG> {
+  return createElement(SAMP_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance samp 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 enhanceSamps(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for samp.
+  void root;
+}

package/src/elements/inline/samp/samp.scss

@@ -0,0 +1,43 @@
+/**
+ * pkgn-sol Design Foundation: Samp Element
+ *
+ * Sample output (`samp`)
+ *
+ * Baseline reset + light branding.
+ *
+ * Notes:
+ * - `<samp>` represents sample output from a program or system.
+ * - UA presentation is typically monospace.
+ * - Normalize to token-driven code typography so it ships standalone.
+ *
+ * References (2025+):
+ * - MDN: `<samp>` element reference (Oct 2025)
+ *
+ * @module
+ * @group  elements.inline.samp
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(samp) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  line-height: inherit;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned code typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-code-font-family);
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  color: var(--lg-theme-base-colours-code-font-color);
+  background-color: transparent;
+}