@omnisass/library 0.4.0 → 0.5.0

package/README.en.md

@@ -0,0 +1,99 @@
+[🇷🇺 Русский](./README.md )
+
+<p align="left">
+  <img src="https://sourcecraft.dev/file?owner=omnisass&repo=library&rev=anvil&path=.omnisass%2Fimages%2Fomnisass_logo_rounded.png" width="150" height="150" alt="Project logo">
+</p>
+
+# OmniSass
+> IMPORTANT: The library is currently undergoing testing. It is possible that API changes will be made or some functions will be removed before the final version 1.0.0. It is recommended to use it exclusively for informational purposes.
+
+A library of functions and mixins written in the CSS preprocessor language Sass. It is designed to simplify, speed up and improve the process of creating styles for websites.
+
+![NPM Version](https://img.shields.io/npm/v/%40omnisass%2Flibrary?logo=npm&label=%40omnisass%2Flibrary&labelColor=%23CB3837&color=white) ![NPM Downloads](https://img.shields.io/npm/dw/%40omnisass%2Flibrary?logo=npm&logoColor=white&labelColor=%23CB3837&color=white) ![NPM Last Update](https://img.shields.io/npm/last-update/%40omnisass%2Flibrary?logo=npm&logoColor=white&labelColor=%23CB3837&color=white) ![NPM Collaborators](https://img.shields.io/npm/collaborators/%40omnisass%2Flibrary?logo=npm&logoColor=white&labelColor=%23CB3837&color=white) ![NPM License](https://img.shields.io/npm/l/%40omnisass%2Flibrary?logo=ReadMe&logoColor=white&labelColor=%23018EF5&color=white) ![NPM (prod) Dependency Version](https://img.shields.io/npm/dependency-version/%40omnisass%2Flibrary/sass?logo=Sass&logoColor=white&labelColor=%23CC6699&color=white)
+
+OmniSass is an extensive, standardized, and carefully documented package that includes solutions built over the years by the community.
+
+Most of the features and mixins are the result of the work of many people who have been developing in the Sass language at various times. OmniSass Developer ([@therteenten](https://t.me/therteenten )) He focused on qualitative standardization, documentation, and the creation of a single tool based on disparate elements.
+
+## Installing the library
+1. For OmniSass to work, the [`sass`](https://www.npmjs.com/package/sass ) library must be installed:
+
+    ```shell
+    npm install sass
+    ```
+
+2. After the installation is complete, you can add the library [`@omnisass/library`](https://www.npmjs.com/package/@omnisass/library ):
+
+    ```shell
+    npm install @omnisass/library
+    ```
+
+3. It's done! OmniSass is ready to use.
+
+## Usage
+You can embed the module in your style file after installing the necessary libraries.:
+
+```scss
+@use '@omnisass/library' as omnisass;
+```
+
+1. We're messing up the `@omnisass/library` module
+2. The entire "stuffing" of the module is available in the omnisass space
+
+Then we apply one of the functions from the library. For example, `is-boolean`:
+
+```scss
+@debug omnisass.is-boolean(true);
+```
+
+In the console, we get:
+
+```shell
+src/styles/main.scss:3 Debug: true
+```
+
+Done. We have successfully installed, imported, and used the library in the project.
+
+> When compiling Sass without the `--load-path=node_modules` key, you must specify the full path to the library folder to import the module. In our case, if the styles.scss file is located in the ./src/styles/ directory, the following construction should be used: `@use'../../node_modules/@omnisass/library'as omnisass;`.
+
+## Useful links
+- [API Documentation (SassDoc)](https://omnisass.sourcecraft.site/sassdocs/)
+- [Organization on SourceCraft](https://sourcecraft.dev/omnisass/overview )
+- [Telegram Channel](https://t.me/omnisass )
+- [List of changes](https://sourcecraft.dev/omnisass/library/browse/CHANGELOG.md?rev=develop )
+
+## Thanks
+- [github@takamoso](https://github.com/takamoso ) - for the functions `is-boolean`, `is-list`, etc.
+- [github@KittyGiraudel](https://github.com/KittyGiraudel ) - for the functions `color-shade`, `color-tint`, etc.
+- [github@sindresorhus](https://github.com/sindresorhus ) - for the functions `get-list-item-end`, `get-list-item-start`, etc.
+- [github@selfishprimate](https://github.com/selfishprimate ) - for the [`is-time`] function(https://github.com/selfishprimate/gerillass/blob/master/scss/utilities/_is-time.scss ) and others.
+- [github@pentzzsolt](https://github.com/pentzzsolt ) - for the `is-int` function, etc.
+
+> If I forgot to mention you in this list, please write to me on [Telegram](https://t.me/therteenten ).
+
+## License
+This project is licensed under the MIT license - for details, see the [LICENSE](LICENSE) file.
+
+```
+MIT License
+
+Copyright (c) 2025, Murad Rustamov (therteenten) <therteenten@ya.ru>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/README.md

@@ -1,3 +1,5 @@
+[🇬🇧 English](./README.en.md)
+
 <p align="left">
   <img src="https://sourcecraft.dev/file?owner=omnisass&repo=library&rev=anvil&path=.omnisass%2Fimages%2Fomnisass_logo_rounded.png" width="150" height="150" alt="Логотип проекта">
 </p>

package/_configs.scss

@@ -25,7 +25,7 @@
 /// @name set-strict-mode
 /// @access public
 /// @example scss Отключение режима
-/// 	@use 'omnisass' as libomnisass with (
+/// 	@use 'omnisass' as omnisass with (
 /// 		$set-strict-mode: false
 /// 	);
 /// @type Boolean

package/index.scss

@@ -3,7 +3,7 @@
 @forward 'configs';
 @forward 'package';
 
-/// Converters
+// Utilities: Converters
 @forward 'modules/utilities/converters/convert-camel2kebab';
 @forward 'modules/utilities/converters/convert-em2px';
 @forward 'modules/utilities/converters/convert-hex2rgb';
@@ -15,12 +15,13 @@
 @forward 'modules/utilities/converters/convert-rem2px';
 @forward 'modules/utilities/converters/convert-snake2kebab';
 
-// Getters
+// Utilities: Getters
 @forward 'modules/utilities/getters/color/get-color-brightness';
 @forward 'modules/utilities/getters/color/get-color-darkest';
 @forward 'modules/utilities/getters/list/get-list-item';
 @forward 'modules/utilities/getters/list/get-list-item-end';
 @forward 'modules/utilities/getters/list/get-list-item-start';
+@forward 'modules/utilities/getters/map/get-map-item';
 @forward 'modules/utilities/getters/misc/get-uid';
 @forward 'modules/utilities/getters/number/get-number-from-percent';
 @forward 'modules/utilities/getters/number/get-number-height-by-ratio';
@@ -31,7 +32,7 @@
 @forward 'modules/utilities/getters/number/get-number-width-by-ratio';
 @forward 'modules/utilities/getters/string/get-string-hash';
 
-// Helpers
+// Utilities: Helpers
 @forward 'modules/utilities/helpers/color/color-blend';
 @forward 'modules/utilities/helpers/color/color-blend-steps';
 @forward 'modules/utilities/helpers/color/color-hue-shift';
@@ -45,6 +46,7 @@
 @forward 'modules/utilities/helpers/list/list-remove-at';
 @forward 'modules/utilities/helpers/list/list-sum-numbers';
 @forward 'modules/utilities/helpers/list/list-sum-numbers-safe';
+@forward 'modules/utilities/helpers/map/map-remove-keys';
 @forward 'modules/utilities/helpers/misc/url-encode';
 @forward 'modules/utilities/helpers/number/number-ceil-to';
 @forward 'modules/utilities/helpers/number/number-clamp';
@@ -71,11 +73,15 @@
 @forward 'modules/utilities/helpers/string/string-trim-end';
 @forward 'modules/utilities/helpers/string/string-trim-start';
 
-// Loggers
+// Utilities: Loggers
 @forward 'modules/utilities/loggers/log-invalid-type';
 @forward 'modules/utilities/loggers/log-invalid-value';
+@forward 'modules/utilities/loggers/log';
 
-// Validators
+// Utilities: Setters
+@forward 'modules/utilities/setters/map/set-map-item';
+
+// Utilities: Validators
 @forward 'modules/utilities/validators/color/is-color-light';
 @forward 'modules/utilities/validators/color/is-color-list';
 @forward 'modules/utilities/validators/list/is-list-contained';

package/modules/utilities/getters/map/_get-map-item.scss

@@ -0,0 +1,159 @@
+@use 'sass:map';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-map' as *;
+
+/// Безопасно извлекает значение из карты по цепочке ключей.
+///
+/// Функция последовательно проходит по переданным ключам,
+/// углубляясь во вложенные карты, и возвращает значение,
+/// соответствующее последнему ключу. Если на любом уровне
+/// ключ отсутствует, функция возвращает `null`. Это позволяет
+/// избежать ошибок при работе со сложными структурами данных
+/// и избавляет от необходимости писать громоздкие проверки.
+///
+/// Для проверки типа входного параметра используется служебная
+/// функция `log-invalid-type`, которая при несоответствии типа
+/// генерирует предупреждение (или ошибку) и возвращает `null`.
+/// ---
+/// @name get-map-item
+/// @group utilities-getters
+/// @since 2026.03.18
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/values/maps См. также: Официальная документация Sass - Тип данных "Карты" (`maps`)
+/// @link https://sass-lang.com/documentation/modules/map См. также: Официальная документация Sass - Модуль `sass:map`
+/// @link https://sass-lang.com/documentation/modules/map#get См. также: Официальная документация Sass - Функция `map.get()`
+/// @link https://sass-lang.com/documentation/modules/map#has-key См. также: Официальная документация Sass - Функция `map.has-key()`
+/// @link https://sass-lang.com/documentation/at-rules/function См. также: Официальная документация Sass - Правило `@function`
+/// @link https://sass-guidelin.es/ru/#maps См. также: Sass Guidelines (рус.) - Работа с картами
+/// @link https://www.sitepoint.com/using-sass-maps/ См. также: SitePoint - Using Sass Maps
+/// @link https://css-tricks.com/snippets/sass/deep-getset-maps/ См. также: CSS-Tricks - Deep Get/Set for Sass Maps
+/// @link https://www.smashingmagazine.com/2015/07/real-work-sass-maps/ См. также: Smashing Magazine - Real Work with Sass Maps
+/// @link https://dev.to/sarah_chima/working-with-sass-maps-5cm5 См. также: Dev.to - Working with Sass Maps
+/// @link https://code.tutsplus.com/tutorials/an-introduction-to-sass-maps--cms-22138 См. также: Envato Tuts+ - An Introduction to Sass Maps
+/// @link https://habr.com/ru/post/309656/ См. также: Habr - Карты данных (maps) в Sass
+/// @link https://htmlacademy.ru/blog/boost/tools/sass-maps См. также: HTML Academy - Sass-карты: когда и как применять
+/// @link https://ru.hexlet.io/courses/sass-basics/lessons/maps/theory_unit См. также: Hexlet - Карты (maps) в Sass
+/// @link https://www.youtube.com/watch?v=6kUo6lBF0Cc См. также: YouTube - Уроки Sass #5: Карты данных (Maps)
+/// @link https://www.youtube.com/watch?v=dN_rpAoy8I0 См. также: YouTube - Sass Maps Tutorial (LevelUp Tuts)
+/// @link https://stackoverflow.com/questions/28548587/sass-check-if-key-exists-in-multi-level-map См. также: Stack Overflow - Проверка существования ключа во вложенной карте
+/// @link https://stackoverflow.com/questions/37705095/sass-get-value-from-nested-map См. также: Stack Overflow - Получение значения из вложенной карты
+/// @link https://www.npmjs.com/package/sass См. также: npm - Документация пакета Dart Sass
+/// @link https://github.com/sass/sass/tree/main/spec См. также: GitHub - Спецификация языка Sass
+/// @example scss - Извлечение значения из плоской карты
+///   $breakpoints: (
+///     mobile: 480px,
+///     tablet: 768px,
+///     desktop: 1024px
+///   );
+/// 
+///   @debug get-map-item($breakpoints, desktop); // 1024px
+///
+/// @example scss - Доступ к вложенным данным конфигурации
+///   $theme: (
+///     colors: (
+///       primary: #3498db,
+///       secondary: #2ecc71
+///     ),
+///     fonts: (
+///       base: 16px,
+///       headings: (
+///         h1: 2rem,
+///         h2: 1.5rem
+///       )
+///     )
+///   );
+///
+///   @debug get-map-item($theme, colors, primary);        // #3498db
+///   @debug get-map-item($theme, fonts, headings, h2);    // 1.5rem
+///
+/// @example scss - Возврат `null` при отсутствии ключа
+///   @debug get-map-item($theme, colors, accent);         // null
+///   @debug get-map-item($theme, missing, key);           // null
+///
+/// @example scss - Использование с переменным числом ключей
+///   $keys: ('fonts', 'headings', 'h1');
+///   @debug get-map-item($theme, $keys...);               // 2rem
+///
+/// @example scss - Применение для получения параметров темы
+///   @mixin button($color-key) {
+///     $bg: get-map-item($theme, colors, $color-key);
+///     background: $bg;
+///   }
+///
+///   .button-primary { @include button(primary); }
+///
+/// @example css - Результат выполнения
+/// 	.button-primary {
+/// 		background: #3498db;
+/// 	}
+/// @example scss - Защита от ошибок при отсутствии карты
+///   $not-a-map: 'string';
+///   @debug get-map-item($not-a-map, any);  // вызывает log-invalid-type и возвращает null
+///
+/// @param {Map} $map - Карта, из которой извлекается значение.
+///   Должна быть типа `map`. В случае передачи другого типа
+///   вызывается `log-invalid-type` и возвращается его результат.
+/// @param {String...} $keys - Один или несколько ключей,
+///   образующих путь к искомому значению. Ключи могут быть
+///   любого типа, поддерживаемого картами Sass (обычно строки).
+/// @return {*} - Значение, находящееся по указанному пути,
+///   или `null`, если хотя бы один из ключей отсутствует,
+///   либо если входная карта имеет неверный тип.
+/// @throws {Error} - Выбрасывает ошибку (или предупреждение)
+///   через функцию `log-invalid-type`, если параметр `$map`
+///   не является картой. Текст ошибки зависит от реализации
+///   `log-invalid-type`, но в стандартном случае возвращается
+///   `null`.
+@function get-map-item($map, $keys...) {
+
+	// Проверяем, что первый аргумент действительно
+	// является картой.
+	@if not is-map($map) {
+
+		// Если это не так, вызываем функцию логирования ошибки
+		// и возвращаем её результат.
+		// Функция log-invalid-type должна обработать некорректный
+		// тип и вернуть null (или выбросить ошибку в зависимости
+		// от настроек).
+		@return log-invalid-type(
+			'get-map-item',
+			$map,
+			'$map',
+			'map'
+		);
+
+	} @else {
+
+		// Проходим по всем переданным ключам последовательно.
+		// На каждом шаге проверяем, существует ли текущий ключ
+		// в текущей карте.
+		@each $-key in $keys {
+
+			@if map.has-key($map, $-key) {
+
+				// Если ключ существует — переходим на уровень глубже,
+				// заменяя $map на полученное значение (которое может
+				// быть как картой, так и любым другим типом).
+				$map: map.get($map, $-key);
+
+			} @else {
+
+				// Если на любом уровне ключ не найден — прерываем
+				// выполнение и возвращаем null.
+				@return null;
+
+			}
+
+		}
+
+		// После успешного прохождения всех ключей возвращаем
+		// итоговое значение. Оно может быть чем угодно: картой,
+		// строкой, числом, списком и т.д.
+		@return $map;
+
+	}
+
+}

package/modules/utilities/helpers/list/_list-sum-numbers-safe.scss

@@ -84,9 +84,10 @@
 /// 	измерения первого найденного числа.
 /// @throws {Warning} - Выводит предупреждение при обнаружении
 /// 	чисел с несовместимыми единицами измерения.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `list`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function list-sum-numbers-safe($list) {
 
 	// Проверка типа входного параметра: ожидается список или arglist.

package/modules/utilities/helpers/list/_list-sum-numbers.scss

@@ -66,9 +66,10 @@
 /// @throws {Error} - Может выбросить ошибку при попытке
 /// 	сложить числа с несовместимыми единицами измерения
 /// 	(например, px + em).
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `list`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function list-sum-numbers($list) {
 
 	// Проверка типа входного параметра: ожидается список или arglist.

package/modules/utilities/helpers/map/_map-remove-keys.scss

@@ -0,0 +1,153 @@
+@use 'sass:map';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-map' as *;
+
+/// Удаляет указанные ключи из карты.
+///
+/// Функция позволяет удалить один или несколько ключей
+/// из карты за один вызов. В отличие от стандартной
+/// функции `map.remove()`, которая принимает только один
+/// ключ для удаления, эта функция принимает список ключей
+/// и последовательно удаляет их все. Это значительно
+/// упрощает код при необходимости удалить несколько
+/// ключей из одной карты, избавляя от необходимости
+/// писать цепочку вызовов `map.remove()`.
+///
+/// Функция работает путём итеративного обхода списка
+/// удаляемых ключей и применения встроенной функции
+/// `map.remove()` к каждому из них. Исходная карта
+/// остаётся неизменной — функция возвращает новую карту,
+/// из которой удалены указанные ключи. Если переданный
+/// ключ отсутствует в карте, он просто игнорируется,
+/// что делает функцию безопасной в использовании.
+///
+/// Важные особенности функции:
+/// - Удаляет несколько ключей за один вызов
+/// - Возвращает новую карту, не мутируя исходную
+/// - Безопасно игнорирует отсутствующие ключи
+/// - Поддерживает удаление любого количества ключей
+/// - Интегрируется с системой валидации типов
+/// - Позволяет создавать чистые конфигурации
+/// - Упрощает фильтрацию данных
+/// ---
+/// @name map-remove-keys
+/// @group utilities-helpers
+/// @since 2026.03.28
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/values/maps См. также: Официальная документация Sass - Тип данных "Карты" (`maps`)
+/// @link https://sass-lang.com/documentation/modules/map См. также: Официальная документация Sass - Модуль `sass:map`
+/// @link https://sass-lang.com/documentation/modules/map#remove См. также: Официальная документация Sass - Функция `map.remove()`
+/// @link https://sass-lang.com/documentation/modules/map#merge См. также: Официальная документация Sass - Функция `map.merge()`
+/// @link https://sass-lang.com/documentation/at-rules/function См. также: Официальная документация Sass - Правило `@function`
+/// @link https://sass-guidelin.es/ru/#maps-1 См. также: Sass Guidelines - Работа с картами
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://www.sitepoint.com/using-sass-maps/ См. также: SitePoint - Использование карт Sass
+/// @link https://www.smashingmagazine.com/2015/07/real-work-sass-maps/ См. также: Smashing Magazine - Реальная работа с картами Sass
+/// @link https://dev.to/sarah_chima/working-with-sass-maps-5cm5 См. также: Dev.to - Работа с картами Sass
+/// @link https://code.tutsplus.com/tutorials/an-introduction-to-sass-maps--cms-22138 См. также: Envato Tuts+ - Введение в карты Sass
+/// @link https://habr.com/ru/post/309656/ См. также: Habr - Карты данных (maps) в Sass
+/// @link https://htmlacademy.ru/blog/boost/tools/sass-maps См. также: HTML Academy - Sass-карты: практическое руководство
+/// @link https://ru.hexlet.io/courses/sass-basics/lessons/maps/theory_unit См. также: Hexlet - Карты в Sass
+/// @link https://www.youtube.com/watch?v=6kUo6lBF0Cc См. также: YouTube - Уроки Sass #5: Карты данных (Maps)
+/// @link https://stackoverflow.com/questions/42841580/remove-multiple-keys-from-sass-map См. также: Stack Overflow - Удаление нескольких ключей из карты Sass
+/// @link https://stackoverflow.com/questions/36586774/sass-remove-map-value См. также: Stack Overflow - Удаление значения из карты Sass
+/// @link https://github.com/sass/sass/tree/main/spec См. также: GitHub - Спецификация языка Sass
+/// @link https://www.npmjs.com/package/sass См. также: npm - Документация пакета Dart Sass
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/delete См. также: MDN Web Docs - JavaScript метод Map.delete()
+/// @link https://en.wikipedia.org/wiki/Associative_array См. также: Wikipedia - Ассоциативный массив
+/// @link https://ru.wikipedia.org/wiki/Ассоциативный_массив См. также: Wikipedia - Ассоциативный массив (рус.)
+/// @link https://www.php.net/manual/en/function.unset.php См. также: PHP Manual - Функция unset()
+/// @example scss - Удаление одного ключа из карты
+/// 	$config: (
+/// 		debug: true,
+/// 		theme: 'dark',
+/// 		language: 'ru'
+/// 	);
+///
+/// 	$clean-config: map-remove-keys($config, debug); // Результат: (theme: 'dark', language: 'ru')
+///
+/// @example scss - Безопасное удаление (игнорирование отсутствующих ключей)
+/// 	$colors: (
+/// 		primary: #3498db,
+/// 		secondary: #2ecc71
+/// 	);
+///
+/// 	// Ключ 'tertiary' отсутствует, но ошибки не будет
+/// 	$filtered: map-remove-keys($colors, (secondary, tertiary)); // Результат: (primary: #3498db)
+///
+/// @example scss - Динамическое удаление на основе списка
+/// 	$theme: (
+/// 		colors: (
+/// 			primary: #3498db,
+/// 			secondary: #2ecc71
+/// 		),
+/// 		spacing: (sm: 8px, md: 16px),
+/// 		typography: (base: 16px, h1: 2rem)
+/// 	);
+///
+/// 	$keys-to-remove: (spacing, typography);
+/// 	$simplified-theme: map-remove-keys($theme, $keys-to-remove); // Результат: (colors: (primary: #3498db, secondary: #2ecc71))
+///
+/// @example scss - Использование в цикле для удаления из нескольких карт
+/// 	@function prepare-for-output($data) {
+/// 		$sensitive-keys: (password, token, credit_card);
+/// 		@return map-remove-keys($data, $sensitive-keys);
+/// 	}
+///
+/// 	$user-data: (
+/// 		name: 'Alice',
+/// 		email: 'alice@example.com',
+/// 		password: 'secret123',
+/// 		token: 'jwt_token_xyz'
+/// 	);
+///
+/// 	$public-data: prepare-for-output($user-data); // Результат: (name: 'Alice', email: 'alice@example.com')
+/// 
+/// @param {Map} $map - Исходная карта, из которой
+///   удаляются ключи. Остаётся неизменной, функция
+///   возвращает новую карту. Должна быть типа `map`.
+/// @param {List} $remove-keys - Список ключей, которые
+///   нужно удалить из карты. Может быть как одиночным
+///   значением, так и списком. Отсутствующие в карте
+///   ключи безопасно игнорируются.
+/// @return {Map} - Новая карта, из которой удалены
+///   указанные ключи. Если удалены все ключи, возвращает
+///   пустую карту `()`.
+/// @throws {Error} - Выбрасывает ошибку через функцию
+///   `log-invalid-type`, если параметр `$map` не является
+///   картой. Сообщение об ошибке локализовано и содержит
+///   информацию об ожидаемом типе данных.
+@function map-remove-keys($map, $remove-keys) {
+
+	// Проверяем, что первый аргумент действительно является картой.
+	// Если это не так, вызываем функцию логирования ошибки
+	// и возвращаем её результат.
+	@if not is-map($map) {
+
+		@return log-invalid-type(
+			'map-remove-keys',
+			$map,
+			'$map',
+			'map'
+		);
+
+	} @else {
+
+		// Проходим по всем ключам из списка удаляемых ключей.
+		// Для каждого ключа применяем встроенную функцию map.remove().
+		// Если ключ отсутствует в карте, map.remove() просто
+		// возвращает карту без изменений — это безопасное поведение.
+		@each $key in $remove-keys {
+			$map: map.remove($map, $key);
+		}
+
+		// Возвращаем новую карту без удалённых ключей.
+		// Исходная карта остаётся неизменной.
+		@return $map;
+
+	}
+
+}

package/modules/utilities/helpers/misc/_url-encode.scss

@@ -67,10 +67,11 @@
 /// @return {String} - Закодированная строка, где все символы
 /// 	из карты замены преобразованы в их процентное
 /// 	представление.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `string` (`$value`) или
-/// 	`map` (`$chars-map`). Компиляция Sass будет остановлена
-/// 	с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `string`
+/// - `$chars-map` → `map`
 /// @require {function} string-replace - Вспомогательная
 /// 	функция замены подстрок в строке. Должна быть определена
 /// 	и доступна для корректной работы данной функции.

package/modules/utilities/helpers/number/_number-ceil-to.scss

@@ -105,9 +105,11 @@
 /// @return {Number} - Число, округленное вверх до ближайшего
 /// 	значения, кратного `$nearest`. Сохраняет единицы
 /// 	измерения исходного числа `$value`.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$nearest` → `number`
 @function number-ceil-to($value, $nearest) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-clamp-max.scss

@@ -86,9 +86,11 @@
 /// 	или `$value-max`. Если `$value` меньше или равно `$value-max`,
 /// 	возвращается `$value`. В противном случае возвращается
 /// 	`$value-max`.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$value-max` → `number`
 @function number-clamp-max($value, $value-max) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-clamp-min.scss

@@ -94,9 +94,11 @@
 /// 	или `$value-min`. Если `$value` больше или равно `$value-min`,
 /// 	возвращается `$value`. В противном случае возвращается
 /// 	`$value-min`.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$value-min` → `number`
 @function number-clamp-min($value, $value-min) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-clamp.scss

@@ -105,9 +105,12 @@
 /// 	диапазона.
 /// @throws {Warning} - когда `$value-min > $value-max` поведение
 /// 	функции может быть неинтуитивным.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$value-min` → `number`
+/// - `$value-max` → `number`
 @function number-clamp($value, $value-min, $value-max) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-denormalize.scss

@@ -170,9 +170,12 @@
 /// @throws Не выбрасывает ошибок, безопасно обрабатывает все
 /// 	числовые значения. Формула математически корректна для
 /// 	любых числовых аргументов.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$value-min` → `number`
+/// - `$value-max` → `number`
 @function number-denormalize($value, $value-min, $value-max) {
 
 	// Проверка типа первого параметра: ожидается нормализованное числовое значение.