@lnpg/pkgn-sol 1.0.0-beta.0

package/src/scss/tokens/_typography.scss

@@ -0,0 +1,218 @@
+/**
+ * pkgn-sol Design Foundation: Typography Tokens
+ *
+ * Canonical typography primitives for the pkgn-sol design foundation.
+ *
+ * These tokens define:
+ * - Font families
+ * - Font weights
+ * - Font sizes (derived from a single base size)
+ * - Line heights
+ * - Spacing defaults used by typography components
+ *
+ * This file is intentionally data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  tokens.typography
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use './spacing' as spacing;
+@use './theme' as theme;
+
+/* --------------------------------------------------------------------------
+ - Font families
+ ------------------------------------------------------------------------- */
+
+/**
+ * Default body font family.
+ *
+ * Merriweather with sensible serif fallbacks.
+ *
+ * @type string
+ */
+$base-font-family: theme.$base-font, Georgia, 'Times New Roman', Times, serif;
+
+/**
+ * Default heading font family.
+ *
+ * Montserrat with modern sans-serif fallbacks.
+ *
+ * @type string
+ */
+$heading-font-family:
+  theme.$heading-font,
+  -apple-system,
+  BlinkMacSystemFont,
+  'Segoe UI',
+  Roboto,
+  'Helvetica Neue',
+  Arial,
+  sans-serif;
+
+/**
+ * Default monospace/code font family.
+ *
+ * @type string
+ */
+$code-font-family:
+  theme.$code-font, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New',
+  monospace;
+
+/* --------------------------------------------------------------------------
+ - Font weights
+ ------------------------------------------------------------------------- */
+
+/**
+ * Font weight: thin.
+ *
+ * @type number
+ */
+$thin-font-weight: 100;
+
+/**
+ * Font weight: lighter.
+ *
+ * @type number
+ */
+$lighter-font-weight: 200;
+
+/**
+ * Font weight: light.
+ *
+ * @type number
+ */
+$light-font-weight: 300;
+
+/**
+ * Font weight: normal.
+ *
+ * @type number
+ */
+$normal-font-weight: 400;
+
+/**
+ * Font weight: medium.
+ *
+ * @type number
+ */
+$medium-font-weight: 500;
+
+/**
+ * Font weight: semibold.
+ *
+ * @type number
+ */
+$semibold-font-weight: 600;
+
+/**
+ * Font weight: bold.
+ *
+ * @type number
+ */
+$bold-font-weight: 700;
+
+/**
+ * Font weight: bolder.
+ *
+ * @type number
+ */
+$bolder-font-weight: 800;
+
+/**
+ * Font weight: black.
+ *
+ * @type number
+ */
+$black-font-weight: 900;
+
+/* --------------------------------------------------------------------------
+ - Font sizes
+ ------------------------------------------------------------------------- */
+
+/**
+ * Base font size for the system.
+ *
+ * All heading sizes are derived from this token to ensure consistent scaling.
+ *
+ * @type number
+ */
+$base-font-size: 1rem;
+
+/**
+ * Heading font sizes (relative to $base-font-size).
+ *
+ * @type number
+ */
+$font-size-h1: $base-font-size * 2.5;
+
+/** @type number */
+$font-size-h2: $base-font-size * 2;
+
+/** @type number */
+$font-size-h3: $base-font-size * 1.75;
+
+/** @type number */
+$font-size-h4: $base-font-size * 1.5;
+
+/** @type number */
+$font-size-h5: $base-font-size * 1.25;
+
+/** @type number */
+$font-size-h6: $base-font-size;
+
+/* --------------------------------------------------------------------------
+ - Typography Formating
+ ------------------------------------------------------------------------- */
+
+/**
+ * Default body font weight.
+ *
+ * @type number
+ */
+$base-font-weight: $normal-font-weight;
+
+/**
+ * Default heading font weight.
+ *
+ * @type number
+ */
+$heading-font-weight: $bold-font-weight;
+
+/**
+ * Default body line height.
+ *
+ * @type number
+ */
+$base-line-height: 1.5;
+
+/**
+ * Default heading line height.
+ *
+ * @type number
+ */
+$heading-line-height: 1.2;
+
+/* --------------------------------------------------------------------------
+ - Spacing defaults
+ ------------------------------------------------------------------------- */
+
+/**
+ * Default bottom margin used for typographic blocks (e.g. paragraphs).
+ *
+ * @type number
+ */
+$base-margin-bottom: 1rem;
+
+/**
+ * Default bottom margin used for headings.
+ *
+ * @type number
+ */
+$heading-margin-bottom: spacing.$base-spacing * 0.5;

package/src/ts/adapters/tailwind/v4/index.ts

@@ -0,0 +1,2 @@
+export { solTailwindPreset } from './preset';
+export { solTailwindPlugin } from './plugin';

package/src/ts/adapters/tailwind/v4/plugin.ts

@@ -0,0 +1,47 @@
+export type PluginApi = {
+  addUtilities: (utilities: Record<string, Record<string, string>>) => void;
+  theme: (path: string) => unknown;
+};
+
+type TailwindPluginFactory = (handler: (api: PluginApi) => void) => unknown;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+async function loadTailwindPluginFactory(): Promise<TailwindPluginFactory> {
+  let mod: unknown;
+
+  try {
+    // Dynamic import keeps Tailwind as an optional peer dependency.
+    mod = (await import('tailwindcss/plugin')) as unknown;
+  } catch {
+    throw new Error('Tailwind is not installed. Install "tailwindcss" to use solTailwindPlugin.');
+  }
+
+  // Handle both CJS and ESM default export shapes.
+  const candidate: unknown = isRecord(mod) && 'default' in mod ? mod.default : mod;
+
+  if (typeof candidate !== 'function') {
+    throw new Error('"tailwindcss/plugin" did not export a plugin factory function as expected.');
+  }
+
+  return candidate as TailwindPluginFactory;
+}
+
+/**
+ * Returns the pkgn-sol Tailwind plugin.
+ *
+ * Note: this is async so Tailwind can remain an optional peer dependency.
+ */
+export async function solTailwindPlugin(): Promise<unknown> {
+  const plugin = await loadTailwindPluginFactory();
+
+  return plugin(({ addUtilities }: PluginApi) => {
+    addUtilities({
+      '.sol-example': {
+        fontSize: '1rem',
+      },
+    });
+  });
+}

package/src/ts/adapters/tailwind/v4/preset.ts

@@ -0,0 +1,75 @@
+/**
+ * pkgn-sol Tailwind preset.
+ *
+ * This intentionally:
+ * - does NOT import Tailwind at runtime (so it can be used as a plain object)
+ * - maps pkgn-sol CSS variables to Tailwind theme tokens
+ */
+
+export type SolTailwindPreset = {
+  theme?: Record<string, unknown>;
+};
+
+type TailwindColours = Record<string, Record<string, string>>;
+
+function rgbaVar(varName: string): string {
+  // Tailwind supports the <alpha-value> placeholder for arbitrary alpha.
+  return `rgb(var(${varName}) / <alpha-value>)`;
+}
+
+function solColourVarRgb(token: string): string {
+  return `--sol-colour-${token}-rgb`;
+}
+
+function makeSolColourScale(colourName: string): Record<string, string> {
+  // pkgn-sol defines: tint-90/80/70/60 + base + shade-10/20/30/40.
+  // Map to Tailwind's 50..900 scale.
+  return {
+    '50': rgbaVar(solColourVarRgb(`${colourName}-tint-90`)),
+    '100': rgbaVar(solColourVarRgb(`${colourName}-tint-80`)),
+    '200': rgbaVar(solColourVarRgb(`${colourName}-tint-70`)),
+    '300': rgbaVar(solColourVarRgb(`${colourName}-tint-60`)),
+    '500': rgbaVar(solColourVarRgb(`${colourName}-base`)),
+    '600': rgbaVar(solColourVarRgb(`${colourName}-shade-10`)),
+    '700': rgbaVar(solColourVarRgb(`${colourName}-shade-20`)),
+    '800': rgbaVar(solColourVarRgb(`${colourName}-shade-30`)),
+    '900': rgbaVar(solColourVarRgb(`${colourName}-shade-40`)),
+  };
+}
+
+function makeSolColours(): TailwindColours {
+  const names = [
+    'grey',
+    'blue',
+    'indigo',
+    'purple',
+    'pink',
+    'red',
+    'orange',
+    'yellow',
+    'green',
+    'teal',
+  ];
+
+  const colours: TailwindColours = {
+    // Convenience accessors.
+    sol: {
+      '0': rgbaVar('--sol-colour-black-rgb'),
+      '1000': rgbaVar('--sol-colour-white-rgb'),
+    },
+  };
+
+  for (const name of names) {
+    colours[name] = makeSolColourScale(name);
+  }
+
+  return colours;
+}
+
+export const solTailwindPreset: SolTailwindPreset = {
+  theme: {
+    extend: {
+      colors: makeSolColours(),
+    },
+  },
+};

package/src/ts/dom.ts

@@ -0,0 +1,378 @@
+/**
+ * DOM helpers for pkgn-sol element modules.
+ *
+ * @remarks
+ * pkgn-sol is a design foundation, not a component framework. These helpers exist to
+ * keep element entrypoints small, consistent, and safe across:
+ * - Vanilla JS
+ * - TypeScript direct consumption
+ * - React and Vue lifecycle usage
+ *
+ * The helpers apply a curated set of common global attributes and provide an
+ * escape hatch for additional attributes, while preventing common XSS footguns.
+ *
+ * @module
+ * @category Internal
+ */
+
+/**
+ * Canonical element return type for a given HTML tag key.
+ *
+ * @remarks
+ * This avoids "invented" DOM types (e.g. `HTMLAddressElement`) and always matches
+ * what TypeScript's `lib.dom.d.ts` actually provides.
+ *
+ * @example
+ * type HrEl = ElementOf<'hr'>; // HTMLHRElement
+ * type AddressEl = ElementOf<'address'>; // HTMLElement (no special DOM interface)
+ *
+ * @category Types
+ */
+export type ElementOf<K extends keyof HTMLElementTagNameMap> = HTMLElementTagNameMap[K];
+
+/**
+ * Values that are safely coerced to strings for attributes.
+ *
+ * @category Types
+ */
+export type AttrValue = string | number | boolean;
+
+/**
+ * A curated, safe subset of HTML global attributes commonly applied to elements.
+ *
+ * @remarks
+ * This type intentionally focuses on widely used global attributes and provides
+ * a generic escape hatch via {@link GlobalAttrs.attrs} for less common cases.
+ *
+ * Security rules enforced by {@link applyGlobalAttrs}:
+ * - Blocks inline event handler attributes like `onclick`
+ * - Blocks the raw `style` attribute. Use {@link GlobalAttrs.style} instead
+ *
+ * @category Attributes
+ */
+export type GlobalAttrs = {
+  /**
+   * The element ID.
+   *
+   * @remarks
+   * Must be unique within the document.
+   */
+  id?: string;
+
+  /**
+   * The element class string.
+   *
+   * @remarks
+   * This maps to `class` in HTML. Use this instead of passing `class` through
+   * {@link GlobalAttrs.attrs}.
+   */
+  className?: string;
+
+  /**
+   * Advisory information, typically shown as a tooltip in browsers.
+   */
+  title?: string;
+
+  /**
+   * Language of the element's content.
+   *
+   * @remarks
+   * Useful when rendering mixed-language documents, or when an element's content
+   * differs from the page language.
+   */
+  lang?: string;
+
+  /**
+   * Text direction of the element's content.
+   */
+  dir?: 'ltr' | 'rtl' | 'auto';
+
+  /**
+   * Optional ARIA role.
+   *
+   * @remarks
+   * Prefer native semantics when possible. Only set `role` when needed.
+   */
+  role?: string;
+
+  /**
+   * Whether the element is hidden.
+   *
+   * @remarks
+   * Mirrors the `hidden` boolean attribute.
+   */
+  hidden?: boolean;
+
+  /**
+   * Tabbing order.
+   *
+   * @remarks
+   * Use with care. Setting a tab index on non-interactive elements can reduce
+   * usability and accessibility.
+   */
+  tabIndex?: number;
+
+  /**
+   * Whether the element is draggable.
+   */
+  draggable?: boolean;
+
+  /**
+   * Whether spellchecking is enabled for editable content.
+   *
+   * @remarks
+   * Mirrors `spellcheck`. This has effect primarily when `contentEditable` is used.
+   */
+  spellCheck?: boolean;
+
+  /**
+   * Translation hint for user agents.
+   *
+   * @remarks
+   * Maps to the `translate` attribute.
+   */
+  translate?: 'yes' | 'no';
+
+  /**
+   * Whether the element is editable.
+   *
+   * @remarks
+   * Use sparingly. Many apps are better served by explicit form controls.
+   */
+  contentEditable?: 'true' | 'false' | 'plaintext-only';
+
+  /**
+   * Inline style properties to assign to the element.
+   *
+   * @remarks
+   * This is safer than accepting a raw style string because it avoids the
+   * `style="..."` attribute injection surface.
+   *
+   * This does not make untrusted input "safe". If callers build styles from
+   * untrusted sources, they must validate inputs appropriately.
+   */
+  style?: Partial<CSSStyleDeclaration>;
+
+  /**
+   * Dataset values applied as `data-*` attributes.
+   *
+   * @remarks
+   * Keys map to `HTMLElement.dataset` keys (camelCase), and values are coerced
+   * to strings.
+   *
+   * Example: `{ trackingId: "123" }` becomes `data-tracking-id="123"`.
+   */
+  dataset?: Record<string, AttrValue>;
+
+  /**
+   * ARIA attribute values applied as `aria-*` attributes.
+   *
+   * @remarks
+   * Keys are appended to `aria-`. Example: `{ label: "Close" }` becomes
+   * `aria-label="Close"`.
+   */
+  aria?: Record<string, AttrValue>;
+
+  /**
+   * Escape hatch for additional attributes not modeled above.
+   *
+   * @remarks
+   * This exists to keep the API practical without turning pkgn-sol into a full DOM
+   * abstraction layer.
+   *
+   * Security rules:
+   * - Attributes starting with `on` are rejected (blocks inline event handlers)
+   * - The `style` attribute is rejected (use {@link GlobalAttrs.style})
+   */
+  attrs?: Record<string, AttrValue>;
+};
+
+/**
+ * Enforce attribute-name safety rules for attribute escape hatches.
+ *
+ * @remarks
+ * This function blocks common XSS surfaces when callers attempt to set raw
+ * attributes. It is intentionally conservative.
+ *
+ * @param name - The attribute name as provided by the caller.
+ * @throws Error if the attribute name is not permitted.
+ *
+ * @category Security
+ */
+function assertSafeAttrName(name: string): void {
+  const raw = String(name);
+  const n = raw.trim().toLowerCase();
+
+  if (n.length === 0) {
+    throw new Error('Unsafe attribute "" is not allowed (empty attribute name).');
+  }
+
+  // Block inline event handlers: onclick, onload, onerror, etc.
+  if (n.startsWith('on')) {
+    throw new Error(
+      `Unsafe attribute "${raw}" is not allowed (event handler attributes are blocked).`,
+    );
+  }
+
+  // Block raw style attribute injection. Use the `style` object field instead.
+  if (n === 'style') {
+    throw new Error(
+      'Unsafe attribute "style" is not allowed. Use the "style" object field instead.',
+    );
+  }
+}
+
+/**
+ * Set an attribute on an element after applying security rules.
+ *
+ * @param el - The element to modify.
+ * @param name - The attribute name.
+ * @param value - The attribute value.
+ * @throws Error if the attribute name is not permitted.
+ *
+ * @category Internal
+ */
+function setAttr(el: Element, name: string, value: AttrValue): void {
+  assertSafeAttrName(name);
+  el.setAttribute(name, String(value));
+}
+
+/**
+ * Apply {@link GlobalAttrs} to an existing element.
+ *
+ * @remarks
+ * - This function does not attempt to "sanitize" content. It avoids the biggest
+ *   footguns by refusing inline event handler attributes and raw `style`.
+ * - Text content should be assigned via `textContent` rather than `innerHTML`.
+ *
+ * @param el - The element to apply attributes to.
+ * @param a - The attribute bag. If omitted, the function is a no-op.
+ *
+ * @example
+ * Apply common attributes:
+ * ```ts
+ * const p = document.createElement("p");
+ * applyGlobalAttrs(p, { id: "intro", className: "lead", lang: "en" });
+ * ```
+ *
+ * @example
+ * Apply dataset and ARIA:
+ * ```ts
+ * applyGlobalAttrs(p, {
+ *   dataset: { trackingId: "123" },
+ *   aria: { label: "Intro paragraph" }
+ * });
+ * ```
+ *
+ * @throws Error if {@link GlobalAttrs.attrs} or {@link GlobalAttrs.aria} contain
+ * an unsafe attribute name.
+ *
+ * @category Attributes
+ */
+export function applyGlobalAttrs(el: HTMLElement, a?: GlobalAttrs): void {
+  if (!a) return;
+
+  if (a.id) el.id = a.id;
+  if (a.className) el.className = a.className;
+  if (a.title) el.title = a.title;
+
+  if (a.lang) el.lang = a.lang;
+  if (a.dir) el.dir = a.dir;
+
+  if (a.role) setAttr(el, 'role', a.role);
+
+  if (typeof a.hidden === 'boolean') el.hidden = a.hidden;
+  if (typeof a.tabIndex === 'number') el.tabIndex = a.tabIndex;
+
+  if (typeof a.draggable === 'boolean') el.draggable = a.draggable;
+  if (typeof a.spellCheck === 'boolean') el.spellcheck = a.spellCheck;
+
+  if (a.translate) setAttr(el, 'translate', a.translate);
+
+  if (a.contentEditable) el.contentEditable = a.contentEditable;
+
+  if (a.style) {
+    Object.assign(el.style, a.style);
+  }
+
+  if (a.dataset) {
+    for (const [k, v] of Object.entries(a.dataset)) {
+      // Dataset keys must be valid identifiers; consumers control this.
+      el.dataset[k] = String(v);
+    }
+  }
+
+  if (a.aria) {
+    for (const [k, v] of Object.entries(a.aria)) {
+      setAttr(el, `aria-${k}`, v);
+    }
+  }
+
+  if (a.attrs) {
+    for (const [k, v] of Object.entries(a.attrs)) {
+      setAttr(el, k, v);
+    }
+  }
+}
+
+/**
+ * Create a DOM element, apply {@link GlobalAttrs}, and optionally set text content.
+ *
+ * @remarks
+ * This helper is intentionally conservative:
+ * - Uses `textContent`, not `innerHTML`, which prevents HTML interpretation.
+ * - Does not accept a raw style string.
+ *
+ * @typeParam K - A key of {@link HTMLElementTagNameMap}, inferred from `tag`.
+ * @param tag - The tag name to create.
+ * @param attrs - Global attributes to apply.
+ * @param text - Optional text content. Assigned via `textContent`.
+ * @returns The created element with the correct DOM type for the tag.
+ *
+ * @example
+ * ```ts
+ * const p = createElement("p", { className: "lead" }, "Hello.");
+ * document.body.appendChild(p);
+ * ```
+ *
+ * @throws Error if unsafe attributes are provided via {@link GlobalAttrs.attrs}
+ * or {@link GlobalAttrs.aria}.
+ *
+ * @category DOM
+ */
+export function createElement<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  attrs?: GlobalAttrs,
+  text?: string,
+): ElementOf<K> {
+  const el = document.createElement(tag) as ElementOf<K>;
+  applyGlobalAttrs(el as unknown as HTMLElement, attrs);
+
+  // Security: textContent does not interpret HTML.
+  if (typeof text === 'string') (el as unknown as Node).textContent = text;
+
+  return el;
+}
+
+/**
+ * Create a void element (e.g. `<hr>`, `<br>`) and apply {@link GlobalAttrs}.
+ *
+ * @remarks
+ * Use this when the element must never carry text content.
+ *
+ * @typeParam K - A key of {@link HTMLElementTagNameMap}, inferred from `tag`.
+ * @param tag - The tag name to create.
+ * @param attrs - Global attributes to apply.
+ * @returns The created element with the correct DOM type for the tag.
+ *
+ * @throws Error if unsafe attributes are provided via {@link GlobalAttrs.attrs}
+ * or {@link GlobalAttrs.aria}.
+ *
+ * @category DOM
+ */
+export function createVoidElement<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  attrs?: GlobalAttrs,
+): ElementOf<K> {
+  return createElement(tag, attrs);
+}