@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,182 @@
+/**
+ * pkgn-sol Design Foundation: i element helpers.
+ *
+ * @remarks
+ * The i element (`<i>`) represents a range of text set off from the normal prose
+ * for some reason, such as:
+ * - idiomatic text / alternate voice or mood
+ * - technical terms
+ * - taxonomical designations
+ * - transliterations
+ *
+ * Best-practice guidance:
+ * - Do not use `<i>` purely for visual italics. Use CSS when the intent is
+ *   presentational rather than semantic.
+ * - If you mean emphasis (stress), use `<em>`.
+ * - If you mean importance, use `<strong>`.
+ * - If you mean the title of a work, use `<cite>`.
+ *
+ * Attributes:
+ * - `<i>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<i>` 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/i
+ * @see https://html.spec.whatwg.org/multipage/text-level-semantics.html
+ *
+ * @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 the i element.
+ *
+ * @category Constants
+ */
+export const I_TAG = 'i' as const;
+
+/**
+ * A CSS selector targeting i elements.
+ *
+ * @category Constants
+ */
+export const I_SELECTOR = 'i';
+
+/**
+ * Attribute bag for i creation/enhancement.
+ *
+ * @remarks
+ * `<i>` 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 IAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link IAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The i attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: IAttrs): 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 i 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: `<i>` 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 i element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<i>` element.
+ *
+ * @example
+ * ```ts
+ * import { createI } from "@lnpg/pkgn-sol/elements/inline/i";
+ *
+ * const term = createI("Homo sapiens", { className: "taxonomy" });
+ * document.body.appendChild(term);
+ * ```
+ *
+ * @category DOM
+ */
+export function createI(text?: string, attrs?: IAttrs): ElementOf<typeof I_TAG> {
+  return createElement(I_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance i 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 enhanceIs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for i.
+  void root;
+}

package/src/elements/inline/index.ts

@@ -0,0 +1,254 @@
+/**
+ * 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';

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

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

package/src/elements/inline/kbd/kbd.scss

@@ -0,0 +1,44 @@
+/**
+ * pkgn-sol Design Foundation: KBD Element
+ *
+ * Keyboard input (`kbd`)
+ *
+ * Baseline reset + light branding.
+ *
+ * Notes:
+ * - `<kbd>` represents user keyboard input.
+ * - UA styling varies (monospace + sometimes bordered/pill styles).
+ * - Normalize to token-driven code typography.
+ * - Do NOT impose decorative key styling at baseline.
+ *
+ * References (2025+):
+ * - MDN: `<kbd>` element reference (Oct 2025)
+ *
+ * @module
+ * @group  elements.inline.kbd
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(kbd) {
+  /* --------------------------------------------------------------------------
+   - 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-weight: inherit;
+  font-style: inherit;
+  color: var(--lg-theme-base-colours-code-font-color);
+  background-color: transparent;
+}