feat(translator/dictionary): add new module.

translator/dictionary/_dictionary.get.function.scss

@@ -0,0 +1,68 @@
+// Sass.
+@use 'sass:list';
+@use 'sass:meta';
+
+// Variables.
+@forward 'dictionary.variables';
+@use 'dictionary.variables' as variables;
+
+// Functions.
+@use '../../meta/meta.of-type.function' as *;
+
+// Modules.
+@use '../../map';
+
+// Status: REVIEW: Check
+// The `dictionary.get()` function returns the .
+// @param `$key` Dictionary key.
+// @param `$dictionary` Dictionary of list or map type to get.
+// @param `$default` The default returned value if the dictionary is null.
+// @param `$global` Whether use the global dictionary.
+// @return The return value is the dictionary
+@function get($key: null, $dictionary: (), $default: null, $global: null) {
+  $dictionary: if(meta.type-of($dictionary) == list and list.length($dictionary) > 0, map.retrieve(get, $dictionary...), $dictionary);
+  @if if(meta.type-of($global) == bool, $global, variables.$dictionary-global) {
+    @if $key {
+      $dictionary: if(
+        of-type(map, map.get(variables.$dictionary, $key, ()), map.get($dictionary, $key, $default)),
+        map.deep-merge(map.get(variables.$dictionary, $key), map.get($dictionary, $key, $default)),
+        map.get($dictionary, $key, $default) or map.get(variables.$dictionary, $key, $default)
+      );
+    } @else {
+      $dictionary: map.deep-merge(variables.$dictionary, $dictionary);
+    }
+  } @else if $key {
+    $dictionary: map.get($dictionary, $key, $default);
+  }
+  @return $dictionary;
+}
+
+// Examples.
+// Get the global dictionary.
+// @debug get(); //
+
+// Deactivate picking from the global dictionary.
+// @debug get($global: false); // ()
+
+// Get the dictionary from the `$dictionary-example` variable.
+// @debug get(null, variables.$dictionary-example); //
+// @debug get(null, variables.$dictionary-example, $global: false); //
+
+// Get the dictionary from the `$dictionary-example` variable by using string key.
+// @debug get(general, variables.$dictionary-example); //
+// @debug get(class, variables.$dictionary-example); //
+
+// Get the dictionary from the `$dictionary-example` variable by using deep key.
+// @debug get((class, calendars), variables.$dictionary-example); //
+
+// Get dictionary from the `$dictionary-example` variable.
+// @debug get(general, variables.$dictionary-example, $global: false); //
+
+// Get the default value on `null`.
+// @debug get(no-field, variables.$dictionary-example, (prefix: spectre)); //
+
+// Get dictionary from the `$dictionary-example` variable with a deep key.
+// @debug get(null, variables.$dictionary-example (class, calendars), $global: false); //
+
+// Get single translation.
+// @debug get((class, separator)); //

translator/dictionary/_dictionary.is-global.function.scss

@@ -0,0 +1,17 @@
+// Sass.
+@use 'sass:meta';
+
+// Variables.
+@use 'dictionary.variables' as variables;
+
+// Status: REVIEW: Check
+// The `dictionary.is-global()` function.
+// @param `$global` Whether use the global dictionary.
+@function is-global($global: null) {
+  @if if(meta.type-of($global) == bool, $global, variables.$dictionary-global) {
+    @return true;
+  }
+  @return $global;
+}
+
+// Examples.

translator/dictionary/_dictionary.merge.function.scss

@@ -0,0 +1,65 @@
+// Sass.
+@use 'sass:list';
+
+// Variables.
+@forward 'dictionary.variables';
+@use 'dictionary.variables' as variables;
+
+// Functions.
+@use 'dictionary.get.function' as *;
+@use 'dictionary.is-global.function' as *;
+
+// Modules.
+@use '../../map';
+
+// Status: DONE
+// The `dictionary.merge()` function.
+// @param `$key`
+// @param `$dictionary`
+// @param `$global`
+@function merge($key: null, $dictionary, $global: null) {
+  @if type-of($dictionary) == list {
+    $fetched-dictionary: ();
+    @each $dictionary in if(list.separator($dictionary) == comma, $dictionary, ($dictionary,)) {
+      $fetched-dictionary: map.deep-merge($fetched-dictionary, map.retrieve(pick, $dictionary, ()));
+    }
+
+    $dictionary: $fetched-dictionary;
+  }
+
+  $dictionary: if(
+    $key,
+    map.merge(get($global: $global), list.append($key, $dictionary)...),
+    map.deep-merge(get($global: $global), $dictionary)
+  );
+  @if is-global($global) {
+    variables.$dictionary: $dictionary;
+  }
+  @return $dictionary;
+}
+
+// Examples.
+// merge an empty map
+// @debug merge(null, (), true); // (size: size, small: sm, class: (prefix: null, separator: "-", suffix: null), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null), null: (size: size, small: sm, class: (prefix: null, separator: "-", suffix: null), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null)))
+
+// get `class` key and merge with an empty map
+// @debug merge(class, ()); // (size: size, small: sm, class: (prefix: null, separator: "-", suffix: null), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null))
+
+// get `class` key and merge with a map
+// @debug merge(class, (test: 1)); // (size: size, small: sm, class: (prefix: null, separator: "-", suffix: null, test: 1), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null))
+// @debug merge(class, (class: (prefix: spectre1, suffix: big))); // (size: size, small: sm, class: (prefix: null, separator: "-", suffix: null, class: (prefix: spectre1, suffix: big)), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null))
+// @debug merge(class, ((prefix: second, suffix: big), (prefix: first, suffix: big)));
+// @debug merge(class, (prefix: spectre)); // (size: size, small: sm, class: (prefix: spectre, separator: "-", suffix: null), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null))
+// @debug merge(class, (prefix: spectre, suffix: big)); // (size: size, small: sm, class: (prefix: spectre, separator: "-", suffix: big), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null))
+
+// get `var` key and merge with a map
+// @debug merge(var, (test: 1)); // (size: size, small: sm, class: (prefix: null, separator: "-", suffix: null), var: (prefix: s, hue: h, saturation: s, lightness: l, alpha: a, separator: "-", suffix: null, test: 1))
+
+// multiple
+// @debug merge(class, ((test: 1), (test-5: 5, test-4: 4, test-3: 3), (test-3: test, test-4: test))); // (delimiter: "-", (extra large, "extra large", extra-large): xl, (extra small, "extra small", extra-small): xs, large: lg, medium: md, small: sm, size: size, class: (delimiter: "-", prefix: spectre, separator: "-", suffix: end, test: 1, test-5: 5, test-4: test, test-3: test), var: (delimiter: "-", prefix: s, separator: "-", suffix: null, alpha: a, hue: h, lightness: l, saturation: s))
+// @debug merge(class, ((test-1: (test-2: (test-3: (1: 1, 2: 2))))));
+
+// pick multiple dictionaries with the keys
+// @debug merge(null, variables.$dictionary-example general);
+// @debug merge(null, variables.$dictionary-example ((general, (wrapper, wrap)), (class, calendars),));
+// @debug merge(class, (variables.$dictionary-example (general, (class, calendars))));

translator/dictionary/_dictionary.pick.function.scss

@@ -0,0 +1,73 @@
+// Sass.
+@use 'sass:list';
+@use 'sass:meta';
+
+// Variables.
+@use 'dictionary.variables' as variables;
+
+// Modules.
+@use '../../map';
+
+// Status: REVIEW: Check.
+// The `dictionary.pick()` function returns the dictionary .
+@function pick($key, $dictionary: (), $global: null) {
+  // Retrieve dictionary from the list
+  $dictionary: if(meta.type-of($dictionary) == list and list.length($dictionary) > 0, map.retrieve(pick, $dictionary...), $dictionary);
+
+  // If global dictionary is activated then merge it with the `$dictionary`.
+  @if if(meta.type-of($global) == bool, $global, variables.$dictionary-global) {
+    $dictionary: if(
+      $key,
+      map.deep-merge(map.pick(variables.$dictionary, $key...), map.pick($dictionary, $key...) or $default),
+      map.deep-merge(variables.$dictionary, $dictionary)
+    );
+  } @else if $key {
+    $dictionary: map.pick($dictionary, $key...) or $default;
+  }
+  @return $dictionary;
+}
+
+// Examples.
+// $-dictionary: (
+//   general: (word: słowo, (wrapper, wrap): owijka, technology: (action: akcja)),
+//   class: (prefix: spectre-prefix, suffix: spectre-suffix, calendars: (calendar: cal), labels: (label: lab)),
+//   prefix: spectre,
+//   suffix: end,
+//   separator: '--',
+//   var: (prefix: spectre, suffix: end)
+// );
+
+// Examples.
+// Pick the global dictionary.
+// @debug pick(null); // ()
+
+// Deactivate picking from the global dictionary.
+// @debug pick(null, $global: false); // ()
+
+// Pick dictionary from the `$-dictionary` variable.
+// @debug pick(null, $-dictionary); //
+
+// Pick dictionary from the `$-dictionary` variable by using string key.
+// @debug pick(general, $-dictionary); //
+
+// Pick dictionary from the `$-dictionary` variable by using deep key.
+// @debug pick(((class, calendars),), $-dictionary class); //
+// @debug pick([(class, calendars)], $-dictionary); //
+
+// Pick dictionary from the `$-dictionary` with not existing key.
+// @debug pick(no-field, $-dictionary); //
+
+// Pick dictionary from the `$-dictionary` variable and `$global` false.
+// @debug pick(null, $-dictionary, $global: false); //
+// @debug pick(general, $-dictionary, $global: false); //
+// @debug pick(no-field, $-dictionary, $global: false); //
+
+// Pick dictionary by using multiple keys and deep key.
+// @debug pick((general, var, (class, calendars)), $-dictionary); //
+
+// Custom dictionary.
+// @debug pick(class, $-dictionary); //
+// @debug pick((prefix,), $-dictionary); //
+
+// Custom dictionary + pick key
+// @debug pick(null, $-dictionary ((class, calendars),), $global: false); //

translator/dictionary/_dictionary.set.function.scss

@@ -0,0 +1,26 @@
+// Functions.
+@use '../../map/map.set.function';
+@use 'dictionary.is-global.function' as *;
+@use 'dictionary.merge.function' as *;
+
+// Variables.
+@forward 'dictionary.variables';
+@use 'dictionary.variables' as variables;
+
+// Status: DONE
+// The `dictionary.set()` function returns the.
+// @param `$key`
+// @param `$value`
+// @param `$dictionary`
+// @param `$global`
+// @return The return value is
+@function set($key, $value, $dictionary: (), $global: null) {
+  $dictionary: map.set(merge(null, $dictionary, $global), $key, $value);
+  @if is-global($global) {
+    variables.$dictionary: $dictionary;
+  }
+  @return $dictionary;
+}
+
+// Examples.
+@debug set('dictionary name', (word: translation));

translator/dictionary/_dictionary.spec.scss

@@ -0,0 +1,76 @@
+// Sass.
+@use 'sass:map';
+
+// Modules.
+@use '../dictionary';
+
+dictionary.$dictionary: (a: 2);
+
+// Variables.
+$dictionary-example: (
+  general: (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, color: c),
+  class: (prefix: class-prefix, separator: class-separator, suffix: class-suffix, calendars: (calendar: cal), labels: (label: lab)),
+  prefix: spectre,
+  border: b,
+  color: c,
+  separator: '-',
+  suffix: end,
+  outline: o,
+  var: (prefix: var-prefix, suffix: var-suffix)
+);
+
+
+// @debug dictionary.merge('example', $dictionary-example);
+@debug dictionary.set('example', $dictionary-example);
+
+@debug dictionary.$dictionary;
+
+
+// get.
+// @debug dictionary.get(get, $dictionary-example, general); // (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, color: c)
+// @debug dictionary.retrieve(get, $dictionary-example, (class, calendars)); // (calendar: cal)
+
+// pick
+// @debug dictionary.retrieve(pick, $dictionary-example, general); // (general: (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, color: c))
+// @debug dictionary.retrieve(pick, $dictionary-example, (general, var)); // (general: (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, color: c), var: (prefix: var-prefix, suffix: var-suffix))
+
+// --- List
+// @debug dictionary.translate-list((wrapper, technology), $dictionary: $dictionary-example general); // owijka, tech
+// @debug dictionary.translate-list((wrapper, technology) color, $dictionary: $dictionary-example general); // (owijka, tech) c
+// @debug dictionary.translate-list((wrapper,), general, $dictionary-example); // (owijka,)
+
+// Different dictionary.
+// @debug dictionary.translate-list((calendar, label), $dictionary: ($dictionary-example, (class, calendars))); // cal, label
+
+// --- Map
+// String.
+// @debug dictionary.translate-map((word: wrapper), $dictionary: $dictionary-example general); // (word: owijka)
+// @debug dictionary.translate-map((limit: first), $dictionary: ((first, start): 1, (last, length, end): 50)); // (limit: 1)
+
+// List.
+// @debug dictionary.translate-map((word: (wrapper, wrap)), $dictionary: $dictionary-example general); // (word: (owijka, owijka))
+
+// Different dictionary.
+// @debug dictionary.translate-map((calendar: calendar), $dictionary: ($dictionary-example, (class, calendars))); // (calendar: cal)
+
+
+// --- String
+// @debug dictionary.translate-string(word, $dictionary: map.get($dictionary-example, general)); // słowo
+// @debug dictionary.translate-string(wrapper, general, $dictionary-example); // owijka
+// @debug dictionary.translate-string(calendar, $dictionary: map.get($dictionary-example, class, calendars)); // cal
+
+
+// --- Any
+// List.
+// @debug dictionary.translate((wrapper, technology), $dictionary: ($dictionary-example, 'general')); // owijka, tech
+// @debug dictionary.translate((wrapper, technology) color, $dictionary: $dictionary-example general); // (owijka, tech) c
+
+// Map.
+// @debug dictionary.translate((word: wrapper), $dictionary: $dictionary-example general); // (word: owijka)
+// @debug dictionary.translate((limit: first), $dictionary: ((first, start): 1, (last, length, end): 50)); // (limit: 1)
+
+// String.
+// @debug dictionary.translate(wrapper, $dictionary: $dictionary-example general); // owijka
+
+// Different dictionary.
+// @debug dictionary.translate(calendar, $dictionary: $dictionary-example (class, calendars)); // cal

translator/dictionary/_dictionary.translation.function.scss

@@ -0,0 +1,24 @@
+// Sass.
+@use 'sass:list';
+
+// Status: TODO: Check return null or $string for an errors.
+// The `dictionary.translation()` function.
+@function translation($search, $dictionaries...) {
+  @each $dictionary in $dictionaries {
+    @each $phrase, $translation in $dictionary {
+      @if list.index($phrase, $search) and $translation {
+        @return $translation;
+      }
+    }
+  }
+  @return null;
+}
+
+// Examples.
+// @debug translation(prefix, $dictionary); // null
+// @debug translation(extra large, $dictionary); // xl
+// @debug translation(prefix, $dictionary-example, $dictionary); // spectre
+// @debug translation(outline, $dictionary, $dictionary-example); // o
+// @debug translation(delimiter, $dictionary, $dictionary-example); // -
+// @debug translation('extra small', $dictionary, $dictionary-example); // xs
+// @debug translation(extra-large, $dictionary, $dictionary-example); // xl

translator/dictionary/_dictionary.variables.scss

@@ -0,0 +1,5 @@
+// Dictionary map.
+$dictionary: () !default;
+
+// Each module uses a dictionary from the `dictionary.var` file.
+$dictionary-global: true;

translator/dictionary/_index.scss

@@ -0,0 +1,6 @@
+@forward 'dictionary.get.function';
+@forward 'dictionary.merge.function';
+@forward 'dictionary.pick.function';
+@forward 'dictionary.set.function';
+@forward 'dictionary.translation.function';
+@forward 'dictionary.variables';