@lnpg/pkgn-sol 1.0.0-beta.0

package/src/scss/mixins/_spacing.scss

@@ -0,0 +1,176 @@
+/**
+ * pkgn-sol Design Foundation: Spacing Mixins
+ *
+ * CSS emitters built on top of the canonical spacing scale.
+ *
+ * This layer exists to bridge:
+ *   maps -> functions -> mixins -> selectors / declarations
+ *
+ * Responsibilities:
+ * - Emit spacing values into CSS declarations
+ * - Provide ergonomic helpers for common spacing patterns
+ * - Delegate all validation and scale logic to functions.spacing
+ *
+ * Design notes:
+ * - This file DOES generate CSS.
+ * - We never re-implement spacing logic here.
+ * - Invalid keys fail fast via strict functions.
+ * - Mixins are intentionally dumb: they wire values, not rules.
+ *
+ * @module
+ * @group  mixins.spacing
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:list';
+@use 'sass:meta';
+@use '../functions/spacing' as fn;
+
+/* ----------------------------------------------------------------------------
+ - Internal helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Normalises a value into a list.
+ *
+ * - null   => null
+ * - number => (number,)
+ * - list   => list (unchanged)
+ *
+ * @access private
+ */
+@function _as-list($value) {
+  @if $value == null {
+    @return null;
+  }
+
+  @if meta.type-of($value) == 'number' {
+    @return list.append((), $value, comma);
+  }
+
+  @return $value;
+}
+
+/* ----------------------------------------------------------------------------
+ - Primitive emitters
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits a spacing value for a CSS property.
+ *
+ * Example:
+ *   @include spacing-prop(margin-top, 4);
+ *
+ * @param {string} $property
+ * @param {number} $key
+ */
+@mixin spacing-prop($property, $key) {
+  @if meta.type-of($property) != 'string' {
+    @error "Expected $property to be a string, got '#{meta.type-of($property)}'";
+  }
+
+  #{$property}: fn.spacing($key);
+}
+
+/**
+ * Emits a negative spacing value for a CSS property.
+ *
+ * Example:
+ *   @include spacing-prop-neg(margin-top, 2);
+ *
+ * @param {string} $property
+ * @param {number} $key
+ */
+@mixin spacing-prop-neg($property, $key) {
+  @if meta.type-of($property) != 'string' {
+    @error "Expected $property to be a string, got '#{meta.type-of($property)}'";
+  }
+
+  #{$property}: fn.spacing-neg($key);
+}
+
+/* ----------------------------------------------------------------------------
+ - Axis helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits vertical spacing (top + bottom).
+ *
+ * Example:
+ *   @include spacing-y(padding, 3);
+ *
+ * @param {string} $property
+ * @param {number} $key
+ */
+@mixin spacing-y($property, $key) {
+  @include spacing-prop('#{$property}-top', $key);
+  @include spacing-prop('#{$property}-bottom', $key);
+}
+
+/**
+ * Emits horizontal spacing (left + right).
+ *
+ * Example:
+ *   @include spacing-x(margin, 2);
+ *
+ * @param {string} $property
+ * @param {number} $key
+ */
+@mixin spacing-x($property, $key) {
+  @include spacing-prop('#{$property}-left', $key);
+  @include spacing-prop('#{$property}-right', $key);
+}
+
+/* ----------------------------------------------------------------------------
+ - Shorthand helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits spacing for all four sides.
+ *
+ * Example:
+ *   @include spacing-all(margin, 4);
+ *
+ * @param {string} $property
+ * @param {number} $key
+ */
+@mixin spacing-all($property, $key) {
+  @if meta.type-of($property) != 'string' {
+    @error "Expected $property to be a string, got '#{meta.type-of($property)}'";
+  }
+
+  #{$property}: fn.spacing($key);
+}
+
+/**
+ * Emits spacing for multiple keys in registry order.
+ *
+ * Useful for generators.
+ *
+ * Example:
+ *   @include spacing-list(padding, (1, 2, 3));
+ *
+ * @param {string} $property
+ * @param {list}   $keys
+ */
+@mixin spacing-list($property, $keys) {
+  @if meta.type-of($property) != 'string' {
+    @error "Expected $property to be a string, got '#{meta.type-of($property)}'";
+  }
+
+  $use-keys: _as-list($keys);
+
+  @if meta.type-of($use-keys) != 'list' {
+    @error "Expected $keys to be a list or number, got '#{meta.type-of($keys)}'";
+  }
+
+  $values: ();
+
+  @each $k in $use-keys {
+    $values: list.append($values, fn.spacing($k), space);
+  }
+
+  #{$property}: $values;
+}

package/src/scss/mixins/_theme.scss

@@ -0,0 +1,273 @@
+/**
+ * pkgn-sol Design Foundation: Theme Mixins
+ *
+ * CSS custom property (variable) emitters for the canonical theme registry.
+ *
+ * This layer exists to bridge:
+ *   tokens -> maps -> functions -> mixins -> selectors (e.g. :root)
+ *
+ * Responsibilities:
+ * - Emit stable CSS variables for theme groups and keys
+ * - Respect consumer overrides via `@use "tokens/theme" with (...)`
+ * - Provide targeted emitters (single group / subset) for generators & apps
+ *
+ * Design notes:
+ * - Theme values are intentionally heterogeneous (bools, strings, numbers, maps).
+ * - We do NOT enforce value types here; correctness is delegated to functions.
+ * - Keys become variable names as-is (no semantic rewriting).
+ * - This file does not create selectors. You control scope.
+ *
+ * @module
+ * @group  mixins.theme
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../functions/theme' as fn;
+
+/* ----------------------------------------------------------------------------
+ - 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 list.append((), $value, comma);
+  }
+
+  @return $value;
+}
+
+/**
+ * Builds a CSS custom property name for a theme token.
+ *
+ * Example output (default):
+ *   --sol-theme-namespace-theme-prefix
+ *
+ * @access private
+ *
+ * @param  {string} $group-key
+ * @param  {string} $token-key
+ * @param  {string} $var-prefix   Must include the leading `--`
+ * @param  {string} $namespace
+ *
+ * @return {string}
+ */
+@function _css-var-name($group-key, $token-key, $var-prefix, $namespace) {
+  @if meta.type-of($group-key) != 'string' {
+    @error "Expected $group-key to be type 'string', got '#{meta.type-of($group-key)}'";
+  }
+
+  @if meta.type-of($token-key) != 'string' {
+    @error "Expected $token-key to be type 'string', got '#{meta.type-of($token-key)}'";
+  }
+
+  @if meta.type-of($var-prefix) != 'string' {
+    @error "Expected $var-prefix to be type 'string', got '#{meta.type-of($var-prefix)}'";
+  }
+
+  @if meta.type-of($namespace) != 'string' {
+    @error "Expected $namespace to be type 'string', got '#{meta.type-of($namespace)}'";
+  }
+
+  @return '#{$var-prefix}#{$namespace}-#{$group-key}-#{$token-key}';
+}
+
+/**
+ * Serializes a string->string map of selected font source paths.
+ *
+ * Each value is emitted using the single selected font format from the
+ * theme registry. This does not create multi-format fallback chains.
+ *
+ * @access private
+ *
+ * @param  {map} $sources
+ *
+ * @return {list}
+ */
+@function _serialize-font-sources($sources) {
+  $base-font-path: fn.theme-value('asset-paths', 'base-font-path');
+  $source-format: fn.theme-value('font-source-format', 'format');
+  $out: ();
+
+  @each $k, $path in $sources {
+    @if meta.type-of($path) != 'string' {
+      @error "Expected font source '#{$k}' to be a string, got '#{meta.type-of($path)}'";
+    }
+
+    @if $path != '' {
+      $out: list.append(
+        $out,
+        string.unquote("url('#{$base-font-path}/#{$path}') format('#{$source-format}')"),
+        comma
+      );
+    }
+  }
+
+  @return $out;
+}
+
+/**
+ * Emits a single CSS custom property declaration.
+ *
+ * @access private
+ *
+ * @param  {string} $name
+ * @param  {*}      $value
+ *
+ * @return {void}
+ */
+@mixin _emit-var($name, $value) {
+  @if meta.type-of($name) != 'string' {
+    @error "Expected $name to be type 'string', got '#{meta.type-of($name)}'";
+  }
+
+  #{$name}: #{$value};
+}
+
+/* ----------------------------------------------------------------------------
+ - Public emitters
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits CSS variables for a single theme group.
+ *
+ * Typical usage:
+ *   :root { @include theme-group-vars("namespace"); }
+ *   [data-theme="dark"] { @include theme-group-vars("feature-flags"); }
+ *
+ * Output naming (default):
+ *   --sol-theme-<group>-<key>: <value>;
+ *
+ * @param  {string}     $group
+ * @param  {list|null} $keys        Optional subset
+ * @param  {string}    $var-prefix  Leading custom prop prefix (default: --sol-)
+ * @param  {string}    $namespace   Namespace segment (default: theme)
+ *
+ * @return {void}
+ */
+@mixin theme-group-vars($group, $keys: null, $var-prefix: '--sol-', $namespace: 'theme') {
+  // Strict access with actionable errors.
+  $m: fn.theme-group($group);
+
+  @if meta.type-of($m) != 'map' {
+    @error "Expected theme group '#{$group}' to be a map, got '#{meta.type-of($m)}'";
+  }
+
+  $use-keys: _as-list($keys);
+
+  @if $use-keys != null and meta.type-of($use-keys) != 'list' {
+    @error "Expected $keys to be a list, string, or null, got '#{meta.type-of($use-keys)}'";
+  }
+
+  @each $key, $val in $m {
+    @if meta.type-of($key) != 'string' {
+      @error "Expected theme key in group '#{$group}' to be a string, got '#{meta.type-of($key)}'";
+    }
+
+    @if $use-keys != null and list.index($use-keys, $key) == null {
+      @continue;
+    }
+
+    // Special-case: string->string maps are not valid CSS values.
+    // We currently only support serializing such maps for font sources.
+    @if meta.type-of($val) == 'map' {
+      $all-string-pairs: true;
+
+      @each $k, $v in $val {
+        @if meta.type-of($k) != 'string' or meta.type-of($v) != 'string' {
+          $all-string-pairs: false;
+        }
+      }
+
+      @if $all-string-pairs == true {
+        $val: _serialize-font-sources($val);
+      }
+    }
+
+    $name: _css-var-name($group, $key, $var-prefix, $namespace);
+
+    @include _emit-var($name, $val);
+  }
+
+  // Fail fast when a subset was requested but nothing matched.
+  @if $use-keys != null and list.length($use-keys) > 0 {
+    $emitted: false;
+
+    @each $k in $use-keys {
+      @if map.has-key($m, $k) {
+        $emitted: true;
+      }
+    }
+
+    @if $emitted == false {
+      @error "No matching keys emitted for theme group '#{$group}'. Check $keys against fn.theme-keys('#{$group}').";
+    }
+  }
+}
+
+/**
+ * Emits CSS variables for *all* registered theme groups.
+ *
+ * @param  {list|null} $groups
+ * @param  {string}    $var-prefix
+ * @param  {string}    $namespace
+ *
+ * @return {void}
+ */
+@mixin theme-vars($groups: null, $var-prefix: '--sol-', $namespace: 'theme') {
+  $use-groups: null;
+
+  @if $groups == null {
+    $use-groups: fn.theme-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($use-groups)}'";
+  }
+
+  @each $group in $use-groups {
+    @include theme-group-vars(
+      $group,
+      $keys: null,
+      $var-prefix: $var-prefix,
+      $namespace: $namespace
+    );
+  }
+}
+
+/**
+ * Top-level convenience mixin to emit everything theme-related.
+ *
+ * This intentionally does NOT create selectors.
+ * You decide the scope, e.g.:
+ *
+ *   :root { @include theme-root-vars(); }
+ *   [data-theme="dark"] { @include theme-root-vars(); }
+ *
+ * @param  {list|null} $groups
+ * @param  {string}    $var-prefix
+ * @param  {string}    $namespace
+ *
+ * @return {void}
+ */
+@mixin theme-root-vars($groups: null, $var-prefix: '--sol-', $namespace: 'theme') {
+  @include theme-vars($groups: $groups, $var-prefix: $var-prefix, $namespace: $namespace);
+}

package/src/scss/mixins/_typography.scss

@@ -0,0 +1,272 @@
+/**
+ * pkgn-sol Design Foundation: Typography Mixins
+ *
+ * CSS custom property (variable) emitters for the canonical typography registry.
+ *
+ * This layer exists to bridge:
+ *   tokens -> maps -> functions -> mixins -> selectors (e.g. :root)
+ *
+ * Responsibilities:
+ * - Emit stable `:root` (or theme-scope) CSS variables for typography groups
+ * - Provide targeted emitters (single group / subset) for consumers & generators
+ * - Keep naming deterministic: registry keys become variable names, as-is
+ *
+ * Design notes:
+ * - Typography is grouped (families, weights, sizes, formatting, spacing).
+ * - This file does not assume where it is included (core vs. consumer build).
+ * - This file does not create selectors. You decide the scope.
+ *
+ * @module
+ * @group  mixins.typography
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../functions/typography' as fn;
+
+/* ----------------------------------------------------------------------------
+ - 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 list.append((), $value, comma);
+  }
+
+  @return $value;
+}
+
+/**
+ * Builds a CSS custom property name for a typography token.
+ *
+ * Example output (default):
+ *   --sol-typography-font-sizes-font-size-h1
+ *
+ * @access private
+ *
+ * @param  {string} $group-key     Typography group key (e.g. "font-sizes")
+ * @param  {string} $token-key     Token key within the group (e.g. "font-size-h1")
+ * @param  {string} $var-prefix    Must include the leading `--` (default: --sol-)
+ * @param  {string} $namespace     Namespace segment after prefix (default: typography)
+ *
+ * @return {string}
+ */
+@function _css-var-name($group-key, $token-key, $var-prefix, $namespace) {
+  @if meta.type-of($group-key) != 'string' {
+    @error "Expected $group-key to be type 'string', got '#{meta.type-of($group-key)}'";
+  }
+
+  @if meta.type-of($token-key) != 'string' {
+    @error "Expected $token-key to be type 'string', got '#{meta.type-of($token-key)}'";
+  }
+
+  @if meta.type-of($var-prefix) != 'string' {
+    @error "Expected $var-prefix to be type 'string', got '#{meta.type-of($var-prefix)}'";
+  }
+
+  @if meta.type-of($namespace) != 'string' {
+    @error "Expected $namespace to be type 'string', got '#{meta.type-of($namespace)}'";
+  }
+
+  @return '#{$var-prefix}#{$namespace}-#{$group-key}-#{$token-key}';
+}
+
+/**
+ * Emits a single CSS custom property declaration.
+ *
+ * @access private
+ *
+ * @param  {string} $name   Full var name including `--`
+ * @param  {*}      $value
+ *
+ * @return {void}
+ */
+@mixin _emit-var($name, $value) {
+  @if meta.type-of($name) != 'string' {
+    @error "Expected $name to be type 'string', got '#{meta.type-of($name)}'";
+  }
+
+  #{$name}: #{$value};
+}
+
+/* ----------------------------------------------------------------------------
+ - Public emitters
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits CSS variables for a single typography group.
+ *
+ * Typical usage:
+ *   :root { @include typography-group-vars("font-sizes"); }
+ *   [data-theme="compact"] { @include typography-group-vars("spacing"); }
+ *
+ * Output naming (default):
+ *   --sol-typography-<group>-<key>: <value>;
+ *
+ * @param  {string} $group
+ * @param  {list|null} $keys        Optional subset (e.g. ("base-font-size","font-size-h1"))
+ * @param  {string} $var-prefix     Leading custom prop prefix (default: --sol-)
+ * @param  {string} $namespace      Namespace segment (default: typography)
+ *
+ * @return {void}
+ */
+@mixin typography-group-vars($group, $keys: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  // Strict group access with actionable errors.
+  $m: fn.typography-group($group);
+
+  @if meta.type-of($m) != 'map' {
+    @error "Expected typography group '#{$group}' to be a map, got '#{meta.type-of($m)}'";
+  }
+
+  $use-keys: _as-list($keys);
+
+  @if $use-keys != null and meta.type-of($use-keys) != 'list' {
+    @error "Expected $keys to be a list, string, or null, got '#{meta.type-of($keys)}'";
+  }
+
+  @each $key, $val in $m {
+    @if meta.type-of($key) != 'string' {
+      @error "Expected typography key in group '#{$group}' to be a string, got '#{meta.type-of($key)}'";
+    }
+
+    @if $use-keys != null and list.index($use-keys, $key) == null {
+      @continue;
+    }
+
+    $name: _css-var-name($group, $key, $var-prefix, $namespace);
+
+    @include _emit-var($name, $val);
+  }
+
+  // If a subset was requested, fail fast when none matched.
+  @if $use-keys != null and list.length($use-keys) > 0 {
+    $emitted: false;
+
+    @each $k in $use-keys {
+      @if map.has-key($m, $k) {
+        $emitted: true;
+      }
+    }
+
+    @if $emitted == false {
+      @error "No matching keys emitted for typography group '#{$group}'. Check $keys against fn.typography-keys('#{$group}').";
+    }
+  }
+}
+
+/**
+ * Emits CSS variables for *all* registered typography groups.
+ *
+ * @param  {list|null} $groups      Optional subset (e.g. ("font-sizes","formatting"))
+ * @param  {string}    $var-prefix  Leading custom prop prefix (default: --sol-)
+ * @param  {string}    $namespace   Namespace segment (default: typography)
+ *
+ * @return {void}
+ */
+@mixin typography-vars($groups: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  $use-groups: null;
+
+  @if $groups == null {
+    $use-groups: fn.typography-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($use-groups)}'";
+  }
+
+  @each $group in $use-groups {
+    @include typography-group-vars(
+      $group,
+      $keys: null,
+      $var-prefix: $var-prefix,
+      $namespace: $namespace
+    );
+  }
+}
+
+/**
+ * Top-level convenience mixin to emit everything typography-related for `:root`
+ * (or any selector you wrap it in).
+ *
+ * This intentionally does NOT create selectors.
+ * You decide the scope, e.g.:
+ *
+ *   :root { @include typography-root-vars(); }
+ *   [data-theme="dense"] { @include typography-root-vars($groups: ("spacing")); }
+ *
+ * @param  {list|null} $groups
+ * @param  {string}    $var-prefix
+ * @param  {string}    $namespace
+ *
+ * @return {void}
+ */
+@mixin typography-root-vars($groups: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  @include typography-vars($groups: $groups, $var-prefix: $var-prefix, $namespace: $namespace);
+}
+
+/* ----------------------------------------------------------------------------
+ - Convenience wrappers
+ --------------------------------------------------------------------------- */
+
+@mixin font-family-vars($keys: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  @include typography-group-vars(
+    'font-families',
+    $keys: $keys,
+    $var-prefix: $var-prefix,
+    $namespace: $namespace
+  );
+}
+
+@mixin font-weight-vars($keys: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  @include typography-group-vars(
+    'font-weights',
+    $keys: $keys,
+    $var-prefix: $var-prefix,
+    $namespace: $namespace
+  );
+}
+
+@mixin font-size-vars($keys: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  @include typography-group-vars(
+    'font-sizes',
+    $keys: $keys,
+    $var-prefix: $var-prefix,
+    $namespace: $namespace
+  );
+}
+
+@mixin typography-format-vars($keys: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  @include typography-group-vars(
+    'formatting',
+    $keys: $keys,
+    $var-prefix: $var-prefix,
+    $namespace: $namespace
+  );
+}
+
+@mixin typography-spacing-vars($keys: null, $var-prefix: '--sol-', $namespace: 'typography') {
+  @include typography-group-vars(
+    'spacing',
+    $keys: $keys,
+    $var-prefix: $var-prefix,
+    $namespace: $namespace
+  );
+}