@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/container/span/index.ts

@@ -0,0 +1,137 @@
+/**
+ * pkgn-sol Design Foundation: Span element helpers.
+ *
+ * @remarks
+ * The `<span>` element is a generic inline container for phrasing content.
+ * It has no inherent semantics and should be used only when no more suitable
+ * semantic element exists.
+ *
+ * This module:
+ * - Creates `<span>` elements via pkgn-sol's DOM helpers (no direct DOM calls).
+ * - Applies a curated subset of global attributes safely.
+ * - Exposes an enhancement hook (currently a no-op) for consistency and
+ *   potential future progressive enhancements.
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by pkgn-sol element factories.
+ *
+ * @remarks
+ * This is a small, typed subset intended to prevent typo-driven ARIA bugs and
+ * keep the API practical. Values are mapped into {@link GlobalAttrs.aria}.
+ *
+ * @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 span.
+ *
+ * @category Constants
+ */
+export const SPAN_TAG = 'span' as const;
+
+/**
+ * A CSS selector targeting span elements.
+ *
+ * @category Constants
+ */
+export const SPAN_SELECTOR = 'span';
+
+/**
+ * Attribute bag for span creation/enhancement.
+ *
+ * @remarks
+ * `<span>` supports HTML global attributes only.
+ *
+ * pkgn-sol additionally supports a typed, structured ARIA input that is mapped into
+ * {@link GlobalAttrs.aria} without modifying the shared DOM helpers.
+ *
+ * @category Attributes
+ */
+export type SpanAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link SpanAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The span attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: SpanAttrs): 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;
+
+  return Object.keys(mappedAria).length > 0 ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * Create a span element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which enforces:
+ *   - No inline event handler attributes (e.g. `onclick`)
+ *   - No raw `style` attribute injection (use the `style` object field)
+ *   - No empty attribute names
+ *
+ * @param text - Optional text content for the span.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<span>` element.
+ *
+ * @category DOM
+ */
+export function createSpan(text?: string, attrs?: SpanAttrs): ElementOf<typeof SPAN_TAG> {
+  return createElement(SPAN_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance span elements within a given root.
+ *
+ * @remarks
+ * Intentionally a no-op in `0.1.0`. This exists to provide a stable, consistent
+ * integration hook across element modules.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceSpans(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for span.
+  void root;
+}

package/src/elements/container/span/span.scss

@@ -0,0 +1,28 @@
+/**
+ * pkgn-sol Design Foundation: Span Element
+ *
+ * Generic inline container (`span`)
+ *
+ * Baseline hygiene only.
+ *
+ * Notes:
+ * - `<span>` is an inline, non-semantic container.
+ * - It carries no meaningful UA styling beyond `display: inline`.
+ * - Modern reset guidance (2025+) recommends avoiding unnecessary resets
+ *   on elements that already render consistently across engines.
+ * - Keep inheritance intact; do not interfere with typography or layout.
+ *
+ * @module
+ * @group  elements.container.span
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(span) {
+  /* --------------------------------------------------------------------------
+   - Baseline
+   -------------------------------------------------------------------------- */
+
+  // Explicitly declare default inline behavior for clarity when shipped standalone.
+  display: inline;
+}

package/src/elements/figure/figcaption/figcaption.scss

@@ -0,0 +1,53 @@
+/**
+ * pkgn-sol Design Foundation: Figcaption Element
+ *
+ * Figure caption (`figcaption`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing and typography variance
+ * - Provides a subtle, token-driven caption treatment without heavy styling
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<figcaption>` element reference ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/figcaption?utm_source=chatgpt.com))
+ * - Reset guidance (Oct 2025): normalize margins/padding ([useaxentix.com](https://useaxentix.com/blog/css/css-reset-complete-guide/?utm_source=chatgpt.com))
+ *
+ * @module
+ * @group  elements.figure.figcaption
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(figcaption) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  max-width: 100%;
+  overflow-wrap: break-word;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned typography
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-base-font-family);
+  font-size: 0.875em;
+  font-weight: var(--lg-typography-formatting-base-font-weight);
+  line-height: var(--lg-typography-formatting-base-line-height);
+  color: var(--lg-theme-base-colours-base-font-color);
+
+  // Keep caption visually subordinate without imposing italics.
+  opacity: 0.85;
+
+  /* --------------------------------------------------------------------------
+   - Spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-start: var(--lg-typography-spacing-heading-margin-bottom);
+}

package/src/elements/figure/figcaption/index.ts

@@ -0,0 +1,157 @@
+/**
+ * pkgn-sol Design Foundation: Figcaption element helpers.
+ *
+ * @remarks
+ * The figcaption element (`<figcaption>`) represents a caption or legend for
+ * the rest of the contents of its parent `<figure>` element.
+ *
+ * Best-practice guidance (summary):
+ * - Use `<figcaption>` as the caption for a `<figure>`.
+ * - Place it as the first or last child of the `<figure>` where possible.
+ * - Keep the visible caption text human-friendly and meaningful.
+ * - Do not use `<figcaption>` purely for styling. Use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<figcaption>` 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 { 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 figcaption.
+ *
+ * @category Constants
+ */
+export const FIGCAPTION_TAG = 'figcaption' as const;
+
+/**
+ * A CSS selector targeting figcaption elements.
+ *
+ * @category Constants
+ */
+export const FIGCAPTION_SELECTOR = 'figcaption';
+
+/**
+ * Attribute bag for figcaption creation/enhancement.
+ *
+ * @remarks
+ * `<figcaption>` supports 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 FigcaptionAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link FigcaptionAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The figcaption attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: FigcaptionAttrs): 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 figcaption 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.
+ *
+ * @param text - Optional text content for the figcaption element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<figcaption>` element.
+ *
+ * @example
+ * ```ts
+ * import { createFigcaption } from "@lnpg/pkgn-sol/elements/figure/figcaption";
+ *
+ * const c = createFigcaption("Kitchen layout, 2026", { className: "caption" });
+ * document.body.appendChild(c);
+ * ```
+ *
+ * @category DOM
+ */
+export function createFigcaption(
+  text?: string,
+  attrs?: FigcaptionAttrs,
+): ElementOf<typeof FIGCAPTION_TAG> {
+  return createElement(FIGCAPTION_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance figcaption 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 enhanceFigcaptions(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for figcaption.
+  void root;
+}

package/src/elements/figure/figure/figure.scss

@@ -0,0 +1,53 @@
+/**
+ * pkgn-sol Design Foundation: Figure Element
+ *
+ * Self-contained content (`figure`)
+ *
+ * Baseline reset + light branding (spacing + typography inheritance).
+ *
+ * This module:
+ * - Normalizes UA margins for consistent cross-browser layout
+ * - Preserves semantics (no forced alignment/centering)
+ * - Applies pkgn-sol spacing token so the element can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * References (2025+):
+ * - MDN: `<figure>` element reference ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/figure?utm_source=chatgpt.com))
+ * - Reset guidance (Oct 2025): normalize margins across browsers ([useaxentix.com](https://useaxentix.com/blog/css/css-reset-complete-guide/?utm_source=chatgpt.com))
+ *
+ * @module
+ * @group  elements.figure.figure
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(figure) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA margins (browsers often apply block margins to figure).
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Predictable sizing.
+  box-sizing: border-box;
+  max-width: 100%;
+
+  // Preserve inherited typography context.
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned spacing
+   -------------------------------------------------------------------------- */
+
+  margin-block-end: var(--lg-typography-spacing-base-margin-bottom);
+}

package/src/elements/figure/figure/index.ts

@@ -0,0 +1,164 @@
+/**
+ * pkgn-sol Design Foundation: Figure element helpers.
+ *
+ * @remarks
+ * The figure element (`<figure>`) represents self-contained content, optionally
+ * with a caption provided by a nested `<figcaption>`.
+ *
+ * Best-practice guidance:
+ * - Use `<figure>` for content referenced from the main flow but which could be
+ *   moved elsewhere without affecting the document's meaning.
+ * - If a caption is present, use `<figcaption>` as the first or last child.
+ * - Avoid using `<figure>` purely as a styling hook.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<figure>` 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/figure
+ *
+ * @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 figure.
+ *
+ * @category Constants
+ */
+export const FIGURE_TAG = 'figure' as const;
+
+/**
+ * A CSS selector targeting figure elements.
+ *
+ * @category Constants
+ */
+export const FIGURE_SELECTOR = 'figure';
+
+/**
+ * Attribute bag for figure creation/enhancement.
+ *
+ * @remarks
+ * `<figure>` supports standard HTML global attributes only.
+ *
+ * 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 FigureAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link FigureAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The figure attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: FigureAttrs): 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 figure 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: `<figure>` typically contains richer flow content (images, code blocks,
+ * quotes, etc.). This helper supports optional text for parity with other pkgn-sol
+ * element factories; consumers can append child nodes as needed.
+ *
+ * @param text - Optional text content for the figure.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<figure>` element.
+ *
+ * @example
+ * Create a figure and append custom content:
+ * ```ts
+ * import { createFigure } from "@lnpg/pkgn-sol/elements/figure/figure";
+ * import { createFigcaption } from "@lnpg/pkgn-sol/elements/figure/figcaption";
+ *
+ * const fig = createFigure(undefined, { className: "media" });
+ * fig.appendChild(document.createElement("img"));
+ * fig.appendChild(createFigcaption("Caption"));
+ * ```
+ *
+ * @category DOM
+ */
+export function createFigure(text?: string, attrs?: FigureAttrs): ElementOf<typeof FIGURE_TAG> {
+  return createElement(FIGURE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance figure 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 enhanceFigures(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for figure.
+  void root;
+}

package/src/elements/figure/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Figure and figcaption element factories.
+ *
+ * Provides framework-agnostic factory functions for the semantic HTML
+ * `<figure>` and `<figcaption>` elements.
+ *
+ * These factories:
+ * - Create semantic figure structures using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct semantic relationships between media and captions.
+ * - Prevent unsafe attribute injection.
+ *
+ * The `<figure>` element represents self-contained content such as images,
+ * diagrams, code listings, or illustrations, optionally paired with a
+ * `<figcaption>` that provides a caption or legend.
+ *
+ * @module elements/figure
+ * @since 0.1.0
+ */
+
+/**
+ * `<figcaption>` element factory namespace.
+ *
+ * Represents a caption or legend describing the contents of a `<figure>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption
+ */
+export * as figcaption from './figcaption';
+
+/**
+ * `<figure>` element factory namespace.
+ *
+ * Represents self-contained content that may include media, illustrations,
+ * code examples, or diagrams, optionally associated with a `<figcaption>`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure
+ */
+export * as figure from './figure';

package/src/elements/form/button/button.scss

@@ -0,0 +1,39 @@
+/**
+ * pkgn-sol Design Foundation: Button Element
+ *
+ * Button control (`button`)
+ *
+ * Token-driven, light baseline.
+ *
+ * This module:
+ * - Normalizes typography inheritance (avoid OS/UA font mismatch)
+ * - Normalizes sizing model and incidental spacing
+ * - Preserves native button appearance (no destructive resets)
+ * - Adds a safe usability default cursor
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.button
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(button) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Buttons are styled per-platform by default; keep that, but normalize typography.
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: var(--lg-typography-font-sizes-base-font-size, inherit);
+  font-weight: var(--lg-typography-formatting-base-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  box-sizing: border-box;
+  margin: 0;
+
+  // Usability: communicates interactivity without touching visuals.
+  cursor: pointer;
+
+  // Do not force appearance/background/borders at baseline.
+}