@lnpg/pkgn-sol 1.0.0-beta.0

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

@@ -0,0 +1,161 @@
+/**
+ * pkgn-sol Design Foundation: B element helpers.
+ *
+ * @remarks
+ * The b element (`<b>`) represents a span of text to which attention is being
+ * drawn for utilitarian purposes, without conveying extra importance.
+ *
+ * Best-practice guidance:
+ * - Use `<b>` to draw attention without implying importance.
+ * - Use `<strong>` for strong importance and `<em>` for stress emphasis.
+ * - Do not use `<b>` purely for styling. Prefer CSS (e.g. `font-weight`) when the
+ *   goal is visual bolding rather than semantics.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create inline attention 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/b
+ *
+ * @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 "bring attention to" spans.
+ *
+ * @category Constants
+ */
+export const B_TAG = 'b' as const;
+
+/**
+ * A CSS selector targeting b elements.
+ *
+ * @category Constants
+ */
+export const B_SELECTOR = 'b';
+
+/**
+ * Attribute bag for b creation/enhancement.
+ *
+ * @remarks
+ * B 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 BAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link BAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The b attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: BAttrs): 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 b 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 b element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<b>` element.
+ *
+ * @example
+ * ```ts
+ * import { createB } from "@lnpg/pkgn-sol/elements/inline/b";
+ *
+ * document.body.appendChild(createB("Keyword", { className: "keyword" }));
+ * ```
+ *
+ * @category DOM
+ */
+export function createB(text?: string, attrs?: BAttrs): ElementOf<typeof B_TAG> {
+  return createElement(B_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance b 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 enhanceBs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for b.
+  void root;
+}

package/src/elements/inline/cite/cite.scss

@@ -0,0 +1,36 @@
+/**
+ * pkgn-sol Design Foundation: Cite Element
+ *
+ * Citation (`cite`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Preserves citation semantics
+ * - Normalizes to a consistent italic style (common UA behavior)
+ * - Avoids deeper typography decisions; inheritance remains primary
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.cite
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(cite) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+
+  // UA commonly renders citations as italic; define explicitly for consistency.
+  font-style: italic;
+
+  // Preserve inherited typography context otherwise.
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}

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

@@ -0,0 +1,165 @@
+/**
+ * pkgn-sol Design Foundation: Cite element helpers.
+ *
+ * @remarks
+ * The cite element (`<cite>`) represents the title of a creative work (e.g. a book,
+ * paper, essay, poem, song, film, TV show, game, sculpture, painting, etc.). :contentReference[oaicite:2]{index=2}
+ *
+ * Best-practice guidance:
+ * - Use `<cite>` for the title of the work being referenced, not the author's name
+ *   and not purely for styling. :contentReference[oaicite:3]{index=3}
+ * - If you want a visible link to a source, use an `<a>` element (and/or surrounding
+ *   citation patterns) rather than relying on hidden metadata. (pkgn-sol intentionally
+ *   does not invent citation-specific behaviors here.)
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create cite inline nodes 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 cite.
+ *
+ * @category Constants
+ */
+export const CITE_TAG = 'cite' as const;
+
+/**
+ * A CSS selector targeting cite elements.
+ *
+ * @category Constants
+ */
+export const CITE_SELECTOR = 'cite';
+
+/**
+ * Attribute bag for cite creation/enhancement.
+ *
+ * @remarks
+ * The `<cite>` element uses standard HTML global attributes. :contentReference[oaicite:4]{index=4}
+ *
+ * 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 CiteAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link CiteAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The cite attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: CiteAttrs): 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 cite 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 cite element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<cite>` element.
+ *
+ * @example
+ * Cite a work title:
+ * ```ts
+ * import { createCite } from "@lnpg/pkgn-sol/elements/inline/cite";
+ *
+ * const c = createCite("The Scream", { className: "work-title" });
+ * document.body.appendChild(c);
+ * ```
+ *
+ * @category DOM
+ */
+export function createCite(text?: string, attrs?: CiteAttrs): ElementOf<typeof CITE_TAG> {
+  return createElement(CITE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance cite 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 enhanceCites(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for cite.
+  void root;
+}

package/src/elements/inline/code/code.scss

@@ -0,0 +1,45 @@
+/**
+ * pkgn-sol Design Foundation: Code Element
+ *
+ * Inline code (`code`)
+ *
+ * Baseline reset + light branding.
+ *
+ * Notes:
+ * - `<code>` is intended to render in a monospace face by default.
+ * - Normalize to token-driven code typography so the element can ship standalone.
+ *
+ * References (2025+):
+ * - MDN: `<code>` element default monospace intent (Oct 2025)
+ *
+ * @module
+ * @group  elements.inline.code
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(code) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Preserve surrounding flow and line metrics.
+  line-height: inherit;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned code typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-code-font-family);
+  font-size: inherit;
+  font-weight: inherit;
+  color: var(--lg-theme-base-colours-code-font-color);
+
+  // Keep neutral by default; no background/pill styling in baseline.
+  background-color: transparent;
+}

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

@@ -0,0 +1,176 @@
+/**
+ * pkgn-sol Design Foundation: Code element helpers.
+ *
+ * @remarks
+ * The code element (`<code>`) represents a fragment of computer code.
+ *
+ * Best-practice guidance:
+ * - Use `<code>` for inline code fragments inside text.
+ * - For code blocks, pair `<code>` with `<pre>` (e.g. `<pre><code>...</code></pre>`).
+ * - Do not use `<code>` purely for visual styling. If the intent is presentational
+ *   (monospace text), use CSS instead.
+ *
+ * Attributes:
+ * - `<code>` has no element-specific attributes in HTML. It accepts global
+ *   attributes only.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<code>` 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/code
+ * @see https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-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.
+ *
+ * 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 code element.
+ *
+ * @category Constants
+ */
+export const CODE_TAG = 'code' as const;
+
+/**
+ * A CSS selector targeting code elements.
+ *
+ * @category Constants
+ */
+export const CODE_SELECTOR = 'code';
+
+/**
+ * Attribute bag for code creation/enhancement.
+ *
+ * @remarks
+ * `<code>` 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 CodeAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link CodeAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The code attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: CodeAttrs): 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 code 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: `<code>` 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 code element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<code>` element.
+ *
+ * @example
+ * ```ts
+ * import { createCode } from "@lnpg/pkgn-sol/elements/inline/code";
+ *
+ * const snippet = createCode("npm run build", { className: "cmd" });
+ * document.body.appendChild(snippet);
+ * ```
+ *
+ * @category DOM
+ */
+export function createCode(text?: string, attrs?: CodeAttrs): ElementOf<typeof CODE_TAG> {
+  return createElement(CODE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance code 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 enhanceCodes(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for code.
+  void root;
+}

package/src/elements/inline/data/data.scss

@@ -0,0 +1,36 @@
+/**
+ * pkgn-sol Design Foundation: Data Element
+ *
+ * Machine-readable data (`data`)
+ *
+ * Baseline reset only.
+ *
+ * This module:
+ * - Preserves semantics (content + machine-readable value)
+ * - Avoids presentation (should behave like a neutral inline element)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.inline.data
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(data) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Preserve inherited typography and color.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+}