@lnpg/pkgn-sol 1.0.0-beta.0

package/src/scss/mixins/_fonts.scss

@@ -0,0 +1,227 @@
+/**
+ * pkgn-sol Design Foundation: Font Face Mixins
+ *
+ * CSS emitters for @font-face rules driven by the canonical font registries.
+ *
+ * This layer exists to bridge:
+ *   tokens -> maps -> functions -> mixins -> selectors / at-rules
+ *
+ * Responsibilities:
+ * - Emit `@font-face` rules from the canonical registry (group/variant maps)
+ * - Provide targeted emitters (single variant / group / all groups)
+ * - Offer developer ergonomics (string-or-list group/variant inputs)
+ * - Keep output deterministic and predictable (no magic path rewriting)
+ *
+ * Design notes:
+ * - This file DOES generate CSS (via @font-face at-rules).
+ * - Emits one selected source per rule; no multi-format fallback chains.
+ * - We validate inputs and fail fast with actionable errors.
+ * - We validate the selected source and fail fast with actionable errors.
+ *
+ * @module
+ * @group  mixins.fonts
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../functions/fonts' as fn;
+@use '../tokens/theme' as theme;
+
+/* ----------------------------------------------------------------------------
+ - Internal helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Normalises a value into a list.
+ *
+ * - null   => null
+ * - string => (string,)
+ * - list   => list (unchanged)
+ */
+@function _as-list($value) {
+  @if $value == null {
+    @return null;
+  }
+
+  @if meta.type-of($value) == 'string' {
+    @return ($value,); // 👈 THE COMMA MATTERS
+  }
+
+  @return $value;
+}
+
+/**
+ * Joins a base path and a relative path safely.
+ */
+@function _join-path($base, $path) {
+  @if meta.type-of($path) != 'string' {
+    @error "Expected $path to be type 'string', got '#{meta.type-of($path)}'";
+  }
+
+  @if string.index($path, '://') {
+    @return $path;
+  }
+
+  @if string.slice($path, 1, 1) == '/' {
+    @return $path;
+  }
+
+  @if not $base {
+    @return $path;
+  }
+
+  @if meta.type-of($base) != 'string' {
+    @error "Expected $base to be type 'string' (or null), got '#{meta.type-of($base)}'";
+  }
+
+  @if string.length($base) == 0 {
+    @return $path;
+  }
+
+  $base-ends-slash: string.slice($base, string.length($base), string.length($base)) == '/';
+  $path-starts-slash: string.slice($path, 1, 1) == '/';
+
+  @if $base-ends-slash and $path-starts-slash {
+    @return '#{$base}#{string.slice($path, 2)}';
+  }
+
+  @if not $base-ends-slash and not $path-starts-slash {
+    @return '#{$base}/#{$path}';
+  }
+
+  @return '#{$base}#{$path}';
+}
+
+/**
+ * Builds a single `url(...) format(...)` src entry.
+ */
+@function _src-entry($path, $format, $base-path) {
+  @if meta.type-of($format) != 'string' {
+    @error "Expected $format to be type 'string', got '#{meta.type-of($format)}'";
+  }
+
+  $p: _join-path($base-path, $path);
+
+  @return string.unquote("url('#{$p}') format('#{$format}')");
+}
+
+/* ----------------------------------------------------------------------------
+ - Public emitters
+ --------------------------------------------------------------------------- */
+
+@mixin font-face($group, $variant, $base-path: theme.$base-font-path) {
+  $v: fn.font-variant($group, $variant);
+  $family: fn.font-descriptor($group, $variant, 'family');
+  $style: fn.font-descriptor($group, $variant, 'style');
+  $weight: fn.font-descriptor($group, $variant, 'weight');
+  $display: fn.font-descriptor($group, $variant, 'display');
+  $sources: fn.font-sources($group, $variant);
+
+  @if meta.type-of($family) != 'string' {
+    @error "Expected font family for '#{$group}/#{$variant}' to be a string, got '#{meta.type-of($family)}'";
+  }
+
+  @if meta.type-of($style) != 'string' {
+    @error "Expected font style for '#{$group}/#{$variant}' to be a string, got '#{meta.type-of($style)}'";
+  }
+
+  $type: meta.type-of($weight);
+
+  @if $type != 'number' and $type != 'string' and $type != 'list' {
+    @error "Expected font weight for '#{$group}/#{$variant}' to be a number, string, or list, got '#{$type}'";
+  }
+
+  @if meta.type-of($display) != 'string' {
+    @error "Expected font display for '#{$group}/#{$variant}' to be a string, got '#{meta.type-of($display)}'";
+  }
+
+  @if meta.type-of($sources) != 'map' {
+    @error "Expected font sources for '#{$group}/#{$variant}' to be a map, got '#{meta.type-of($sources)}'";
+  }
+
+  @if list.length(map.keys($sources)) != 1 {
+    @error "Expected exactly one font source for '#{$group}/#{$variant}', got '#{list.length(map.keys($sources))}'";
+  }
+
+  $format: list.nth(map.keys($sources), 1);
+  $path: map.get($sources, $format);
+
+  @if meta.type-of($format) != 'string' {
+    @error "Expected source format key to be a string, got '#{meta.type-of($format)}'";
+  }
+
+  @if meta.type-of($path) != 'string' {
+    @error "Expected source path for '#{$group}/#{$variant}' format '#{$format}' to be a string, got '#{meta.type-of($path)}'";
+  }
+
+  @font-face {
+    font-family: $family;
+    font-style: $style;
+    font-weight: $weight;
+    font-display: $display;
+    src: _src-entry($path, $format, $base-path);
+  }
+}
+
+/**
+ * Emits @font-face rules for all variants in a group.
+ */
+@mixin font-group-faces($group, $variants: null, $base-path: theme.$base-font-path) {
+  $use-variants: null;
+
+  @if not $variants {
+    $use-variants: fn.font-variants($group);
+  } @else {
+    $use-variants: _as-list($variants);
+  }
+
+  @if meta.type-of($use-variants) != 'list' {
+    @error "Expected $variants to be a list, string, or null, got '#{meta.type-of($variants)}'";
+  }
+
+  @each $variant in $use-variants {
+    @include font-face($group, $variant, $base-path: $base-path);
+  }
+}
+
+/**
+ * Emits @font-face rules for all registered font groups.
+ */
+@mixin font-faces($groups: null, $base-path: theme.$base-font-path) {
+  $use-groups: null;
+
+  @if not $groups {
+    $use-groups: fn.font-groups();
+  } @else {
+    $use-groups: _as-list($groups);
+  }
+
+  @if meta.type-of($use-groups) != 'list' {
+    @error "Expected $groups to be a list, string, or null, got '#{meta.type-of($groups)}'";
+  }
+
+  @each $group in $use-groups {
+    @include font-group-faces($group, $variants: null, $base-path: $base-path);
+  }
+}
+
+/* ----------------------------------------------------------------------------
+ - Convenience wrappers
+ --------------------------------------------------------------------------- */
+
+@mixin base-font-faces($base-path: theme.$base-font-path) {
+  @include font-group-faces('base', $base-path: $base-path);
+}
+
+@mixin heading-font-faces($base-path: theme.$base-font-path) {
+  @include font-group-faces('headings', $base-path: $base-path);
+}
+
+@mixin code-font-faces($base-path: theme.$base-font-path) {
+  @include font-group-faces('code', $base-path: $base-path);
+}

package/src/scss/mixins/_index.scss

@@ -0,0 +1,93 @@
+/**
+ * pkgn-sol Design Foundation: Mixins Index
+ *
+ * Public API surface for all mixin modules.
+ *
+ * This file intentionally:
+ * - Re-exports mixin modules using `@forward`
+ * - Defines the *only* supported import path for mixins
+ * - Avoids loading modules eagerly or creating side effects
+ *
+ * IMPORTANT:
+ * - This file MUST NOT use `@use`
+ * - This file MUST NOT reference tokens, maps, or functions directly
+ * - This file MUST NOT perform logic, validation, or transformation
+ *
+ * Consumers should import mixins via:
+ *
+ *   @use "mixins" as mx;
+ *
+ * Never import individual mixin files directly unless you are inside
+ * the design system itself.
+ *
+ * @module
+ * @group  mixins
+ * @access public
+ * @since  0.1.0
+ */
+
+/* ----------------------------------------------------------------------------
+ - Core variable emitters
+ --------------------------------------------------------------------------- */
+
+/**
+ * Theme variable emitters.
+ *
+ * Emits CSS custom properties for the canonical theme registry.
+ */
+@forward 'theme';
+
+/**
+ * Colour variable emitters.
+ *
+ * Emits CSS custom properties for colour scales and base colours,
+ * including optional RGB companions.
+ */
+@forward 'colours';
+
+/**
+ * Typography variable emitters.
+ *
+ * Emits CSS custom properties for typography groups such as
+ * font families, sizes, weights, formatting, and spacing.
+ */
+@forward 'typography';
+
+/* ----------------------------------------------------------------------------
+ - Layout & spacing utilities
+ --------------------------------------------------------------------------- */
+
+/**
+ * Spacing utility mixins.
+ *
+ * Provides spacing helpers (x/y/all/list/negative variants)
+ * for applying margin and padding consistently.
+ *
+ * NOTE:
+ * This module currently provides *property helpers* only.
+ * A spacing vars emitter may be added in the future.
+ */
+@forward 'spacing';
+
+/* ----------------------------------------------------------------------------
+ - Fonts & assets
+ --------------------------------------------------------------------------- */
+
+/**
+ * Font-face generators.
+ *
+ * Emits @font-face rules from the canonical font registry.
+ */
+@forward 'fonts';
+
+/* ----------------------------------------------------------------------------
+ - System & configuration helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Global options helpers.
+ *
+ * Provides mixins for consuming option-level configuration
+ * (e.g. feature flags, namespace helpers).
+ */
+@forward 'options';

package/src/scss/mixins/_options.scss

@@ -0,0 +1,297 @@
+/**
+ * pkgn-sol Design Foundation: Options Mixins
+ *
+ * CSS emitters for option registry values (typically as CSS custom properties).
+ *
+ * This layer exists to bridge:
+ *   tokens -> maps -> functions -> mixins -> selectors / properties
+ *
+ * Responsibilities:
+ * - Emit CSS custom properties from the canonical options registry
+ * - Provide targeted emitters (single option / subset / all options)
+ * - Offer developer ergonomics (string-or-list inputs, sane defaults)
+ * - Keep output deterministic and predictable (no magic key rewriting)
+ *
+ * Design notes:
+ * - This file DOES generate CSS (via custom properties).
+ * - We do not mutate registries (options stay canonical).
+ * - We validate inputs and fail fast with actionable errors.
+ *
+ * @module
+ * @group  mixins.options
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../functions/options' as fn;
+
+/* ----------------------------------------------------------------------------
+ - Internal helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Normalises a value into a list.
+ *
+ * Developer ergonomics:
+ * - null => null
+ * - string => (string,)
+ * - list => list (unchanged)
+ *
+ * @access private
+ *
+ * @param  {*} $value
+ *
+ * @return {*}
+ */
+@function _as-list($value) {
+  @if $value == null {
+    @return null;
+  }
+
+  @if meta.type-of($value) == 'string' {
+    @return list.append((), $value, comma);
+  }
+
+  @return $value;
+}
+
+/**
+ * Casts a Sass value into a string representation (without caring what it was).
+ *
+ * Used for safe comparisons when user passes unquoted identifiers etc.
+ *
+ * @access private
+ *
+ * @param  {*} $value
+ *
+ * @return {string}
+ */
+@function _stringify($value) {
+  @if meta.type-of($value) == 'string' {
+    @return $value;
+  }
+
+  @return '#{$value}';
+}
+
+/**
+ * Normalises a key filter into a list of strings (or null).
+ *
+ * @access private
+ *
+ * @param  {list|string|null} $keys
+ *
+ * @return {list|null}
+ */
+@function _normalise-keys($keys) {
+  $use: _as-list($keys);
+
+  @if $use == null {
+    @return null;
+  }
+
+  @if meta.type-of($use) != 'list' {
+    @error "Expected $keys to be a list, string, or null, got '#{meta.type-of($keys)}'";
+  }
+
+  $out: ();
+
+  @each $k in $use {
+    $out: list.append($out, _stringify($k), comma);
+  }
+
+  @return $out;
+}
+
+/**
+ * Converts bool to a CSS-friendly numeric value.
+ *
+ * @access private
+ *
+ * @param  {bool} $value
+ *
+ * @return {number}
+ */
+@function _bool-to-int($value) {
+  @if meta.type-of($value) != 'bool' {
+    @error "Expected $value to be type 'bool', got '#{meta.type-of($value)}'";
+  }
+
+  @if $value {
+    @return 1;
+  }
+
+  @return 0;
+}
+
+/**
+ * Normalises option values for CSS emission.
+ *
+ * - string: emitted unquoted
+ * - bool: emitted as 0/1
+ * - everything else: emitted as-is (numbers, colors, lists, etc.)
+ *
+ * @access private
+ *
+ * @param  {*} $value
+ *
+ * @return {*}
+ */
+@function _css-value($value) {
+  @if $value == null {
+    @error "Expected option value to be non-null";
+  }
+
+  $t: meta.type-of($value);
+
+  @if $t == 'string' {
+    @return string.unquote($value);
+  }
+
+  @if $t == 'bool' {
+    @return _bool-to-int($value);
+  }
+
+  @return $value;
+}
+
+/**
+ * Builds a CSS custom property name.
+ *
+ * If $prefix is provided:
+ *   --<prefix>-<key>
+ * else:
+ *   --<key>
+ *
+ * @access private
+ *
+ * @param  {string|null} $prefix
+ * @param  {string}      $key
+ *
+ * @return {string}
+ */
+@function _var-name($prefix, $key) {
+  @if meta.type-of($key) != 'string' {
+    @error "Expected $key to be type 'string', got '#{meta.type-of($key)}'";
+  }
+
+  @if $prefix == null {
+    @return '--#{$key}';
+  }
+
+  @if meta.type-of($prefix) != 'string' {
+    @error "Expected $prefix to be type 'string' (or null), got '#{meta.type-of($prefix)}'";
+  }
+
+  @if string.length($prefix) == 0 {
+    @return '--#{$key}';
+  }
+
+  @return '--#{$prefix}-#{$key}';
+}
+
+/* ----------------------------------------------------------------------------
+ - Public emitters
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits a single CSS custom property from the options registry.
+ *
+ * Example:
+ *   :root { @include option-var("prefix"); }
+ *
+ * @param  {string}      $key
+ * @param  {string|null} $prefix  Optional override prefix for emitted var names
+ *
+ * @return {void}
+ */
+@mixin option-var($key, $prefix: null) {
+  @if meta.type-of($key) != 'string' {
+    @error "Expected $key to be type 'string', got '#{meta.type-of($key)}'";
+  }
+
+  $value: fn.option($key);
+
+  #{_var-name($prefix, $key)}: _css-value($value);
+}
+
+/**
+ * Emits CSS custom properties for the options registry (optionally filtered).
+ *
+ * Default behavior:
+ * - If $prefix is null, attempts to use registry option("prefix") as var prefix.
+ *   If that option does not exist, falls back to no prefix.
+ *
+ * Filtering:
+ * - $keys can be null (all), a string, or a list of strings.
+ *
+ * Example:
+ *   :root { @include options-vars(); }
+ *   :root { @include options-vars($keys: ("prefix","dark-mode")); }
+ *
+ * @param  {list|string|null} $keys
+ * @param  {string|null}      $prefix
+ *
+ * @return {void}
+ */
+@mixin options-vars($keys: null, $prefix: null) {
+  $opts: fn.options();
+
+  @if meta.type-of($opts) != 'map' {
+    @error "Expected options registry to be a map, got '#{meta.type-of($opts)}'";
+  }
+
+  $use-keys: _normalise-keys($keys);
+
+  // Prefix resolution:
+  // - explicit $prefix wins
+  // - else try registry "prefix"
+  // - else null (no prefix)
+  $use-prefix: $prefix;
+
+  @if $use-prefix == null and fn.has-option('prefix') == true {
+    $p: fn.option('prefix');
+
+    @if $p != null and meta.type-of($p) == 'string' and string.length($p) > 0 {
+      $use-prefix: $p;
+    }
+  }
+
+  @each $k, $v in $opts {
+    @if $v == null {
+      @continue;
+    }
+
+    @if meta.type-of($k) != 'string' {
+      @error "Expected option key to be a string, got '#{meta.type-of($k)}'";
+    }
+
+    @if $use-keys != null and list.index($use-keys, $k) == null {
+      @continue;
+    }
+
+    #{_var-name($use-prefix, $k)}: _css-value($v);
+  }
+}
+
+/**
+ * Convenience emitter for a `:root` block.
+ *
+ * Example:
+ *   @include options-root();
+ *
+ * @param  {list|string|null} $keys
+ * @param  {string|null}      $prefix
+ *
+ * @return {void}
+ */
+@mixin options-root($keys: null, $prefix: null) {
+  :root {
+    @include options-vars($keys: $keys, $prefix: $prefix);
+  }
+}