@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/text/pre/index.ts

@@ -0,0 +1,175 @@
+/**
+ * pkgn-sol Design Foundation: Pre element helpers.
+ *
+ * @remarks
+ * The pre element (`<pre>`) represents preformatted text which is intended to be
+ * presented "as written", preserving whitespace and line breaks.
+ *
+ * Best-practice guidance:
+ * - Use `<pre>` for text where whitespace is meaningful (e.g. code blocks, ASCII art,
+ *   logs, configuration snippets). :contentReference[oaicite:3]{index=3}
+ * - For code examples, prefer `<pre><code>...</code></pre>` to provide clearer
+ *   semantics for assistive tech and tooling.
+ * - Avoid obsolete/non-standard attributes historically associated with `<pre>`
+ *   such as `width`, `cols`, or `wrap`; control layout with CSS instead
+ *   (e.g. `white-space: pre-wrap` or overflow rules). :contentReference[oaicite:4]{index=4}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create preformatted blocks 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 preformatted text blocks.
+ *
+ * @category Constants
+ */
+export const PRE_TAG = 'pre' as const;
+
+/**
+ * A CSS selector targeting pre elements.
+ *
+ * @category Constants
+ */
+export const PRE_SELECTOR = 'pre';
+
+/**
+ * Attribute bag for pre creation/enhancement.
+ *
+ * @remarks
+ * The `<pre>` element uses 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 PreAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link PreAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The pre attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: PreAttrs): 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 pre 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:
+ * - `<pre>` preserves whitespace by default in browser rendering, but wrapping
+ *   behavior is typically controlled with CSS (e.g. `white-space: pre-wrap`). :contentReference[oaicite:5]{index=5}
+ *
+ * @param text - Optional text content for the pre element.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<pre>` element.
+ *
+ * @example
+ * Create a code block:
+ * ```ts
+ * import { createPre } from "@lnpg/pkgn-sol/elements/text/pre";
+ *
+ * const pre = createPre("npm run build\nnpm run test", {
+ *   className: "code-block",
+ *   aria: { label: "Command output" }
+ * });
+ *
+ * document.body.appendChild(pre);
+ * ```
+ *
+ * @category DOM
+ */
+export function createPre(text?: string, attrs?: PreAttrs): ElementOf<typeof PRE_TAG> {
+  return createElement(PRE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance pre 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 enhancePres(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for pre.
+  void root;
+}

package/src/elements/text/pre/pre.scss

@@ -0,0 +1,59 @@
+/**
+ * pkgn-sol Design Foundation: Preformatted Text (`pre`)
+ *
+ * Baseline reset + reliable, brand-aligned formatting defaults.
+ *
+ * Resets considerations:
+ * - Preserve whitespace semantics (the core purpose of `<pre>`).
+ * - Remove unexpected padding/margins that vary by browser.
+ * - Normalize default monospace font stacks while still using brand variables.
+ * - Manage overflow consistently across engines.
+ * - Keep line wrapping predictable.
+ *
+ * Branding considerations:
+ * - Use code font family tokens.
+ * - Respect default user intent for monospace display.
+ *
+ * References (2025+):
+ * - MDN: `<pre>` element semantics inclusion (line breaks & whitespace) (MDN)
+ * - Modern reset guidance recommending preservation of display with normalization
+ *   rather than destruction of semantics (Josh W. Comeau CSS reset articles)
+ * - Logical properties for spacing (MDN / CSS WG specs)
+ */
+
+:where(pre) {
+  /* --------------------------------------------------------------------------
+   - Display & semantics
+   -------------------------------------------------------------------------- */
+
+  display: block; // consistent block rendering
+  white-space: pre; // preserve whitespace, tabs, line breaks
+
+  /* --------------------------------------------------------------------------
+   - Normalization
+   -------------------------------------------------------------------------- */
+
+  margin: 0; // unset UA margin variance
+  padding: 0; // reset padding differences
+  border: 0; // remove default borders if present
+  overflow: auto; // consistent handling of large content
+  box-sizing: border-box; // predictable sizing model
+
+  /* --------------------------------------------------------------------------
+   - Typography (brand-aligned tokens)
+   -------------------------------------------------------------------------- */
+
+  font-family: var(--lg-typography-font-families-code-font-family);
+  font-size: var(--lg-typography-font-sizes-base-font-size);
+  font-weight: var(--lg-typography-font-weights-normal-font-weight);
+  line-height: var(--lg-typography-formatting-base-line-height);
+  color: var(--lg-theme-base-colours-base-font-color);
+
+  /* --------------------------------------------------------------------------
+   - Accessibility & usability
+   -------------------------------------------------------------------------- */
+
+  max-width: 100%; // prevent overflow beyond container      // horizontal scroll for long lines
+  tab-size: 4; // modern default for readability
+  hyphens: none; // no line breaks inside code tokens
+}

package/src/scss/_elements.scss

@@ -0,0 +1,178 @@
+/**
+ * pkgn-sol Design Foundation: Elements Loader
+ *
+ * Primary element composition layer for the pkgn-sol design foundation.
+ *
+ * This file composes all baseline element modules that collectively
+ * form the element-layer output of the system.
+ *
+ * IMPORTANT:
+ * - This file is intentionally composition-only.
+ * - It must not define selectors, variables, mixins, or functions.
+ * - Import order matters and is part of the public contract of the build.
+ * - This file MUST use `@use` (not `@forward`).
+ *
+ * Current state:
+ * - Element modules emit baseline resets using low-specificity `:where()`.
+ * - Token references are resolved inside each element module.
+ * - No logic or configuration is performed here.
+ *
+ * @module
+ * @group  elements
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+/* ----------------------------------------------------------------------------
+ - Composition
+ --------------------------------------------------------------------------- */
+
+/**
+ * Text content elements.
+ */
+@use '../elements/text/paragraph/paragraph';
+@use '../elements/text/hr/hr';
+@use '../elements/text/pre/pre';
+@use '../elements/text/blockquote/blockquote';
+@use '../elements/text/address/address';
+
+/**
+ * Container elements.
+ */
+@use '../elements/container/div/div';
+@use '../elements/container/span/span';
+
+/**
+ * Line break elements.
+ */
+@use '../elements/break/br/br';
+@use '../elements/break/wbr/wbr';
+
+/**
+ * Media elements.
+ */
+@use '../elements/media/canvas/canvas';
+@use '../elements/media/embed/embed';
+@use '../elements/media/iframe/iframe';
+@use '../elements/media/img/img';
+@use '../elements/media/math/math';
+@use '../elements/media/object/object';
+@use '../elements/media/svg/svg';
+@use '../elements/media/video/video';
+@use '../elements/media/audio/audio';
+
+/**
+ * Table elements.
+ */
+@use '../elements/table/table/table';
+@use '../elements/table/colgroup/colgroup';
+@use '../elements/table/col/col';
+@use '../elements/table/thead/thead';
+@use '../elements/table/tbody/tbody';
+@use '../elements/table/tfoot/tfoot';
+@use '../elements/table/tr/tr';
+@use '../elements/table/th/th';
+@use '../elements/table/td/td';
+@use '../elements/table/caption/caption';
+
+/**
+ * Heading elements.
+ */
+@use '../elements/heading/h1/h1';
+@use '../elements/heading/h2/h2';
+@use '../elements/heading/h3/h3';
+@use '../elements/heading/h4/h4';
+@use '../elements/heading/h5/h5';
+@use '../elements/heading/h6/h6';
+
+/**
+ * Inline semantic elements.
+ */
+@use '../elements/inline/a/a';
+@use '../elements/inline/em/em';
+@use '../elements/inline/strong/strong';
+@use '../elements/inline/small/small';
+@use '../elements/inline/s/s';
+@use '../elements/inline/cite/cite';
+@use '../elements/inline/q/q';
+@use '../elements/inline/dfn/dfn';
+@use '../elements/inline/abbr/abbr';
+@use '../elements/inline/data/data';
+@use '../elements/inline/time/time';
+@use '../elements/inline/code/code';
+@use '../elements/inline/var/var';
+@use '../elements/inline/samp/samp';
+@use '../elements/inline/kbd/kbd';
+@use '../elements/inline/sub/sub';
+@use '../elements/inline/sup/sup';
+@use '../elements/inline/i/i';
+@use '../elements/inline/b/b';
+@use '../elements/inline/u/u';
+@use '../elements/inline/mark/mark';
+@use '../elements/inline/ruby/ruby';
+@use '../elements/inline/rb/rb';
+@use '../elements/inline/rt/rt';
+@use '../elements/inline/rtc/rtc';
+@use '../elements/inline/rp/rp';
+
+/**
+ * List elements.
+ */
+@use '../elements/list/ol/ol';
+@use '../elements/list/ul/ul';
+@use '../elements/list/li/li';
+@use '../elements/list/dl/dl';
+@use '../elements/list/dt/dt';
+@use '../elements/list/dd/dd';
+
+/**
+ * Figure elements.
+ */
+@use '../elements/figure/figure/figure';
+@use '../elements/figure/figcaption/figcaption';
+
+/**
+ * Form elements.
+ */
+@use '../elements/form/form/form';
+@use '../elements/form/label/label';
+@use '../elements/form/input/input';
+@use '../elements/form/textarea/textarea';
+@use '../elements/form/select/select';
+@use '../elements/form/button/button';
+@use '../elements/form/fieldset/fieldset';
+@use '../elements/form/legend/legend';
+@use '../elements/form/datalist/datalist';
+@use '../elements/form/optgroup/optgroup';
+@use '../elements/form/option/option';
+@use '../elements/form/output/output';
+@use '../elements/form/progress/progress';
+@use '../elements/form/meter/meter';
+
+/**
+ * Interactive elements.
+ */
+@use '../elements/interactive/details/details';
+@use '../elements/interactive/summary/summary';
+@use '../elements/interactive/dialog/dialog';
+
+/**
+ * Responsive media semantics.
+ */
+@use '../elements/responsive/picture/picture';
+@use '../elements/responsive/source/source';
+@use '../elements/responsive/track/track';
+@use '../elements/responsive/map/map';
+@use '../elements/responsive/area/area';
+
+/**
+ * Layout and sectioning elements.
+ */
+@use '../elements/layout/main/main';
+@use '../elements/layout/section/section';
+@use '../elements/layout/article/article';
+@use '../elements/layout/aside/aside';
+@use '../elements/layout/nav/nav';
+@use '../elements/layout/header/header';
+@use '../elements/layout/footer/footer';

package/src/scss/_font-face.scss

@@ -0,0 +1,35 @@
+/**
+ * pkgn-sol Design Foundation: Font-face Declarations
+ *
+ * Emits @font-face rules for the registered font groups.
+ *
+ * This file intentionally:
+ * - Is composition-only (no variables, functions, or selectors beyond @font-face)
+ * - Delegates all registry access to maps/functions/mixins
+ * - Emits all defined groups explicitly (base, headings, code), even if they
+ *   currently share the same placeholder family (e.g. Montserrat)
+ *
+ * @module
+ * @group  core.font-face
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+/* ----------------------------------------------------------------------------
+ - Composition
+ --------------------------------------------------------------------------- */
+
+@use './mixins/fonts' as font-mx;
+
+/**
+ * Emit font-face rules for each public group.
+ *
+ * We intentionally *do not* dedupe by family name here because:
+ * - base/headings/code are separate contracts
+ * - placeholder families may be identical pre-0.1.0
+ * - consumers may override groups independently later
+ */
+@include font-mx.font-group-faces('base');
+@include font-mx.font-group-faces('headings');
+@include font-mx.font-group-faces('code');

package/src/scss/_reboot.scss

@@ -0,0 +1,120 @@
+/**
+ * pkgn-sol Design Foundation: Reboot (Global Baseline)
+ *
+ * Minimal, opinionated reset establishing a predictable baseline
+ * for all downstream styles.
+ *
+ * This file intentionally:
+ * - Normalises box model behaviour
+ * - Establishes global document and body defaults
+ * - Avoids component- or utility-specific rules
+ * - Uses explicit values (tokens will be wired later)
+ *
+ * This is not a full Normalize.css replacement.
+ * It is a controlled baseline aligned to modern browser behaviour.
+ *
+ * @module
+ * @group  core.reboot
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+/* ----------------------------------------------------------------------------
+ - Global box model
+ --------------------------------------------------------------------------- */
+
+/**
+ * Apply `border-box` sizing universally.
+ *
+ * This ensures element dimensions are predictable and prevents
+ * padding and borders from affecting declared widths and heights.
+ *
+ * Applied to pseudo-elements to maintain consistency for generated
+ * content (icons, overlays, overlays, pseudo-layouts, etc.). */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+/* ----------------------------------------------------------------------------
+ - Document root
+ --------------------------------------------------------------------------- */
+
+/**
+ * Root document element.
+ *
+ * Responsibilities:
+ * - Establish full-height document context
+ * - Disable browser text-size inflation (notably on iOS)
+ * - Normalise baseline line-height inheritance
+ *
+ * Notes:
+ * - `text-size-adjust` is included for forward compatibility
+ * - `-webkit-text-size-adjust` remains the most reliable implementation */
+html {
+  /* Remove default UA spacing */
+  margin: 0;
+  padding: 0;
+
+  /* Establish full-height document context */
+  height: 100%;
+
+  /* Baseline line-height for typographic inheritance */
+  line-height: var(--lg-typography-formatting-base-line-height, 1.5);
+
+  /* Prevent automatic font scaling */
+  text-size-adjust: 100%;
+}
+
+/* ----------------------------------------------------------------------------
+ - Body baseline
+ --------------------------------------------------------------------------- */
+
+/**
+ * Global body defaults.
+ *
+ * Responsibilities:
+ * - Remove default browser spacing
+ * - Establish minimum viewport height
+ * - Define baseline typography and colours
+ * - Normalise interaction affordances
+ *
+ * Values are intentionally hard-coded for now.
+ * These will later be sourced from tokens / CSS variables. */
+body {
+  /* Remove default UA spacing */
+  margin: 0;
+  padding: 0;
+
+  /* Ensure body spans at least the viewport height */
+  min-height: 100vh;
+
+  /* Base font stack (temporary, tokenised later) */
+  font-family: var(
+    --lg-typography-font-families-base-font-family,
+    'Montserrat',
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    Roboto,
+    'Helvetica Neue',
+    Arial,
+    sans-serif
+  );
+
+  /* Explicit baseline typography */
+  font-weight: var(--lg-typography-formatting-base-font-weight, normal);
+  font-size: var(--lg-typography-font-sizes-base-font-size, 1rem);
+
+  /* Base text and background colours */
+  color: var(--lg-theme-base-colours-base-font-color, #212529);
+  background-color: var(--lg-theme-base-colours-body-bg-color, #f8f9fa);
+
+  /* Logical text alignment (RTL-safe) */
+  text-align: start;
+
+  /* Remove iOS tap highlight flash */
+  -webkit-tap-highlight-color: rgb(0 0 0 / 0%);
+}

package/src/scss/_root.scss

@@ -0,0 +1,112 @@
+/**
+ * pkgn-sol Design Foundation: Root Scope
+ *
+ * Root-scope CSS custom property emission for pkgn-sol.
+ *
+ * This file is the selector-layer entrypoint for global variables:
+ * - It creates the `:root {}` selector.
+ * - It wires canonical registries through mixin emitters.
+ * - It remains theme-agnostic (no dark/light scopes yet).
+ *
+ * Responsibilities:
+ * - Emit stable CSS variables for:
+ *   - Theme registry (heterogeneous values)
+ *   - Colour registry (scales + rgb companions)
+ *   - Typography registry (all groups)
+ *   - Spacing vars (only if a spacing vars emitter exists)
+ *
+ * Design notes:
+ * - Keys become variable names as-is.
+ * - Prefix is sourced from the theme registry to respect consumer overrides.
+ *
+ * @module
+ * @group  root
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:meta';
+@use 'sass:string';
+@use './functions/theme' as theme-fn;
+@use './mixins/theme' as theme-mx;
+@use './mixins/colours' as colour-mx;
+@use './mixins/typography' as type-mx;
+@use './mixins/spacing' as space-mx;
+
+/* ----------------------------------------------------------------------------
+ - Internal helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Returns a valid CSS custom property prefix including the leading `--`.
+ *
+ * Source of truth:
+ * - theme.try-theme-value("namespace", "theme-prefix", "sol-")
+ *
+ * Accepted override shapes:
+ * - "sol-"   → "--sol-"
+ * - "--sol-" → "--sol-"
+ * - ""/null  → "--sol-" (fallback)
+ *
+ * @access private
+ *
+ * @return {string}
+ */
+@function _var-prefix() {
+  $raw: theme-fn.try-theme-value('namespace', 'theme-prefix', 'sol-');
+
+  @if meta.type-of($raw) != 'string' or string.length($raw) == 0 {
+    @return '--sol-';
+  }
+
+  @if string.slice($raw, 1, 2) == '--' {
+    @return $raw;
+  }
+
+  @return '--#{$raw}';
+}
+
+/* ----------------------------------------------------------------------------
+ - Root emission
+ --------------------------------------------------------------------------- */
+
+:root {
+  $var-prefix: _var-prefix();
+
+  // Theme registry variables (heterogeneous values supported).
+  @include theme-mx.theme-root-vars($groups: null, $var-prefix: $var-prefix, $namespace: 'theme');
+
+  // Colour registry variables (scales + rgb companions by default).
+  @include colour-mx.colour-root-vars(
+    $scales: null,
+    $base-map: null,
+    $var-prefix: $var-prefix,
+    $group: 'colour',
+    $with-rgb: true,
+    $rgb-suffix: '-rgb'
+  );
+
+  // Typography registry variables (all groups).
+  @include type-mx.typography-root-vars(
+    $groups: null,
+    $var-prefix: $var-prefix,
+    $namespace: 'typography'
+  );
+
+  /** 
+   * Spacing vars:
+   * Your current spacing mixins file provides property helpers (spacing-x/y/etc),
+   * but does not (yet) provide a vars emitter like spacing-root-vars().
+   *
+   * Make this future-proof: if you add spacing-root-vars later, it will
+   * automatically start emitting spacing vars at :root without changing this file.
+   */
+  @if meta.mixin-exists('spacing-root-vars', $module: space-mx) {
+    @include space-mx.spacing-root-vars(
+      $scales: null,
+      $var-prefix: $var-prefix,
+      $namespace: 'spacing'
+    );
+  }
+}