@omnisass/library 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # История изменений OmniSass
-Обратите внимание, что данный текст представляет собой краткое изложение истории разработки проекта по версиям. Для более детального ознакомления с изменениями рекомендуется обратиться к соответствующему [разделу](https://sourcecraft.dev/therteenten/omnisass/commits/?rev=master) в SourceCraft.
+Обратите внимание, что данный текст представляет собой краткое изложение истории разработки проекта по версиям. Для более детального ознакомления с изменениями рекомендуется обратиться к соответствующему [разделу](https://sourcecraft.dev/omnisass/library/commits/?rev=master) в SourceCraft.
 
-## 0.0.1 - Alpha Public Preview
-...
+## v0.4.0 - Public Alpha Release
+{% note info %}
+
+Данная версия библиотеки включает завершённую реализацию функций, построенных на основе встроенного модуля `sass:string`. В фокусе следующего релиза — разработка функциональности с использованием модуля `sass:map`.
+
+{% endnote %}
+
+### Добавленные новые Sass-функции
+#### Вспомогательные функции
+- **string-count** - Подсчитывает количество вхождений подстроки в строку.
+- **string-reverse** - Переворачивает строку (меняет порядок символов на обратный).
+- **string-lorips** - Генерирует текст-заполнитель на основе указанного списка слов.
+- **string-repeat** - Повторяет строку указанное количество раз.
+
+#### Функции для получения значений
+- **get-string-hash** - Вычисляет числовой хеш-код для строки по алгоритму DJB2.
+- **get-uid** - Генерирует уникальный строковый идентификатор с префиксом.
+
+
+## v0.3.0 - Public Alpha Release
+{% note warning "Примечание" %}
+
+В списке изменений к версии 0.3.0 будут указаны все изменения, внесённые в предыдущих версиях, поскольку ранее они не фиксировались в документации.
+
+{% endnote %}
+
+### Добавленные новые Sass-функции
+#### Конверторы значений
+- **convert-camel2kebab** - Конвертирует строку из `camelCase` (верблюжья нотация) в `kebab-case` (кебаб-нотация или дефисная нотация).
+- **convert-em2px** - Конвертирует значения из относительных единиц (`em`) в пиксели (`px`).
+- **convert-hex2rgba** - Преобразует цвет в строку формата RGBA с поддержкой прозрачности.
+- **convert-hex2rgb** - Преобразует цвет из HEX формата в строку формата RGB.
+- **convert-kebab2camel** - Конвертирует строку из `kebab-case` (кебаб-нотация) в `camelCase` (верблюжья нотация).
+- **convert-kebab2snake** - Преобразует строку из `kebab-case` (кебаб-нотация) в `snake_case` (змеиная нотация).
+- **convert-px2em** - Конвертирует значения из пикселей (`px`) в относительные единицы (`em`).
+- **convert-px2rem** - Конвертирует значения из пикселей (`px`) в относительные единицы (`rem`).
+- **convert-rem2px** - Конвертирует значения из относительных единиц (`rem`) в пиксели (`px`).
+- **convert-snake2kebab** - Преобразует строку из `snake_case` (змеиная нотация) в `kebab-case` (кебаб-нотация).
+
+#### Функции для получения значений
+- **get-color-brightness** - Рассчитывает яркость (светлоту) цвета.
+- **get-color-darkest** - Находит самый темный цвет в списке по значению lightness в HSL-пространстве.
+- **get-list-item-end** - Возвращает последний элемент списка.
+- **get-list-item-start** - Возвращает первый элемент списка.
+- **get-list-item** - Возвращает первый или последний элемент списка.
+- **get-number-from-percent** - Вычисляет абсолютное значение по проценту от целого.
+- **get-number-height-by-ratio** - Вычисляет высоту на основе ширины и соотношения сторон.
+- **get-number-max** - Находит максимальное числовое значение в списке.
+- **get-number-min** - Находит минимальное числовое значение в списке.
+- **get-number-percentage-of** - Вычисляет процентное отношение части к целому.
+- **get-number-unit** - Возвращает единицы измерения числа в виде строки.
+- **get-number-width-by-ratio** - Вычисляет ширину на основе высоты и соотношения сторон.
+
+#### Вспомогательные функции
+- **color-blend** - Линейная интерполяция (смешивание) между двумя цветами.
+- **color-blend-steps** - Создает последовательность равномерно распределенных цветов между двумя точками.
+- **color-hue-shift** - Поворачивает цветовой тон (hue) цвета на заданное количество градусов.
+- **color-scale** - Генерирует монохромную шкалу оттенков путем затемнения базового цвета.
+- **color-shade** - Создает затемненную версию цвета, добавляя к нему черный цвет.
+- **color-tint** - Осветляет исходный цвет, смешивая его с белым.
+- **color-triad** - Генерирует триадную цветовую схему из трех равноудаленных цветов.
+- **list-dedupe** - Удаляет дублирующиеся значения из списка.
+- **list-insert-at** - Вставляет значение в список по указанному индексу.
+- **list-merge** - Объединяет несколько списков в один плоский список.
+- **list-remove-at** - Удаляет элемент из списка по указанному индексу.
+- **list-sum-numbers-safe** - Безопасно суммирует числовые значения в списке с проверкой единиц измерения.
+- **list-sum-numbers** - Суммирует все числовые значения в списке.
+- **url-encode** - Кодирует строку для безопасного использования в URL.
+- **number-ceil-to** - Округляет число вверх до ближайшего кратного значения.
+- **number-clamp-max** - Ограничивает число сверху, обеспечивая максимальное значение.
+- **number-clamp-min** - Ограничивает число снизу, обеспечивая минимальное значение.
+- **number-clamp** - Ограничивает число заданным диапазоном значений.
+- **number-denormalize** - Денормализует число из единичного интервала [0, 1] в исходный диапазон.
+- **number-fibonacci** - Генерирует последовательность чисел Фибоначчи.
+- **number-floor-to** - Округляет число вниз до ближайшего кратного значения.
+- **number-format-with-separator** - Форматирует число, добавляя разделители тысяч для улучшения читаемости больших чисел.
+- **number-normalize** - Нормализует число к единичному интервалу [0, 1].
+- **number-random-between-int** - Генерирует случайное целое число в заданном диапазоне.
+- **number-random-between** - Генерирует случайное число в заданном диапазоне.
+- **number-range** - Генерирует последовательность чисел в заданном диапазоне с определенным шагом.
+- **number-round-to-nearest** - Округляет число до ближайшего кратного значения с использованием стандартного математического округления (половинки в сторону от нуля).
+- **number-round-to** - Округляет число до указанного количества знаков после запятой.
+- **number-strip-unit** - Удаляет единицы измерения из числа, возвращая безразмерное значение.
+- **string-capitalize** - Преобразует первый символ строки в верхний регистр, остальные оставляет без изменений.
+- **string-replace** - Заменяет все вхождения подстроки в строке на другую подстроку.
+- **string-trim-end** - Удаляет пробелы с конца строки (справа).
+- **string-trim-start** - Удаляет пробелы с начала строки (слева).
+- **string-trim** - Удаляет пробелы с начала и конца строки.
+
+#### Функции для логгирования
+- **log-invalid-type** - Логирует ошибку или предупреждение о несоответствии типа параметра ожидаемым типам.
+- **log-invalid-value** - Логирует ошибку или предупреждение о недопустимом значении параметра, когда передано значение, не входящее в список разрешенных.
+
+#### Функции для валидации значений
+- **is-color-light** - Определяет, является ли цвет светлым (по пороговому значению светлоты).
+- **is-color-list** - Проверяет, что все элементы в списке являются цветами.
+- **is-list-contained** - Проверяет, содержится ли значение в указанном списке.
+- **is-time** - Проверяет, является ли значение корректным временным значением.
+- **is-int-even** - Проверяет, является ли целое число четным.
+- **is-int-odd** - Проверяет, является ли целое число нечетным.
+- **is-int** - Проверяет, является ли число целым (integer).
+- **is-number-has-unit** - Проверяет, имеет ли число единицы измерения.
+- **is-number-negative** - Проверяет, является ли значение отрицательным числом.
+- **is-number-positive** - Проверяет, является ли значение положительным числом.
+- **is-number-unitless** - Проверяет, является ли число безразмерным.
+- **is-number-zero** - Проверяет, является ли значение нулем (числовым нулем).
+- **is-string-contained** - Проверяет, содержится ли подстрока в указанной строке.
+- **is-string-empty** - Проверяет, является ли строка пустой.
+- **is-string-ending-with** - Проверяет, заканчивается ли строка указанной подстрокой.
+- **is-string-starting-with** - Проверяет, начинается ли строка с указанной подстроки.
+- **is-boolean** - Проверяет, является ли переданное значение логическим типом (boolean).
+- **is-color** - Проверяет, является ли значение допустимым цветом.
+- **is-list** - Проверяет, является ли значение списком (list) или списком аргументов (arglist).
+- **is-map** - Проверяет, является ли значение ассоциативным массивом (map).
+- **is-number** - Проверяет, является ли значение числом
+- **is-string** - Проверяет, является ли значение строкой (string)
+- **is-type** - Возвращает тип данных переданного значения.
+
+> Чтобы получить подробные сведения об API новых функций, посетите веб-сайт по адресу [https://omnisass.sourcecraft.site/sassdocs/](https://omnisass.sourcecraft.site/sassdocs/).

package/README.md

@@ -1,2 +1,96 @@
+<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>
+
 # OmniSass
+> ВАЖНО: Библиотека сейчас проходит стадию тестирования. Вполне возможно, что до финальной версии 1.0.0 будут внесены изменения в API или удалены некоторые функции. Рекомендуется использовать её исключительно для ознакомительных целей.
+
 Библиотека функций и миксинов, написанная на языке CSS-препроцессора Sass. Она предназначена для того, чтобы упростить, ускорить и улучшить процесс создания стилей для веб-сайтов.
+
+![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 представляет собой обширный, стандартизированный и тщательно задокументированный пакет, включающий решения, годами собранные сообществом.
+
+Большинство функций и миксинов — результат работы множества людей, которые в разное время занимались разработкой на языке Sass. Разработчик OmniSass ([@therteenten](https://t.me/therteenten)) сосредоточился на качественной стандартизации, документировании и создании единого инструмента на базе разрозненных элементов.
+
+## Установка библиотеки
+1. Для работы OmniSass необходимо, чтобы была установлена библиотека [`sass`](https://www.npmjs.com/package/sass):
+
+    ```shell
+    npm install sass
+    ```
+
+2. После завершения установки вы можете добавить библиотеку [`@omnisass/library`](https://www.npmjs.com/package/@omnisass/library):
+
+    ```shell
+    npm install @omnisass/library
+    ```
+
+3. Готово! OmniSass готов к использованию.
+
+## Использование
+Вы можете внедрить модуль в ваш файл стилей после установки необходимых библиотек:
+
+```scss
+@use '@omnisass/library' as omnisass;
+```
+
+1. Мы испортируем модуль `@omnisass/library`
+2. Вся "начинка" модуля доступна в пространстве `omnisass`
+
+Затем мы применяем одну из функций из библиотеки. Например, `is-boolean`:
+
+```scss
+@debug omnisass.is-boolean(true);
+```
+
+В консоли мы получаем:
+
+```shell
+src/styles/main.scss:3 Debug: true
+```
+
+Готово. Мы успешно установили, импортировали и использовали библиотеку в проект.
+
+> При компиляции Sass без ключа `--load-path=node_modules` для импорта модуля нужно указать полный путь к папке библиотеки. В нашем случае, если файл styles.scss находится в директории ./src/styles/, следует использовать следующую конструкцию: `@use '../../node_modules/@omnisass/library' as omnisass;`.
+
+## Полезные ссылки
+- [Документация API (SassDoc)](https://omnisass.sourcecraft.site/sassdocs/)
+- [Организация на SourceCraft](https://sourcecraft.dev/omnisass/overview)
+- [Канал в Telegram](https://t.me/omnisass)
+- [Список изменений](https://sourcecraft.dev/omnisass/library/browse/CHANGELOG.md?rev=develop)
+
+## Благодарности
+- [github@takamoso](https://github.com/takamoso) - за функции `is-boolean`, `is-list` и др.
+- [github@KittyGiraudel](https://github.com/KittyGiraudel) - за функции `color-shade`, `color-tint` и др.
+- [github@sindresorhus](https://github.com/sindresorhus) - за функции `get-list-item-end`, `get-list-item-start` и др.
+- [github@selfishprimate](https://github.com/selfishprimate) - за функцию [`is-time`](https://github.com/selfishprimate/gerillass/blob/master/scss/utilities/_is-time.scss) и др.
+- [github@pentzzsolt](https://github.com/pentzzsolt) - за функцию `is-int` и др.
+
+> Если я забыл вас упомянуть в этом списке, то прошу написать мне на [Telegram](https://t.me/therteenten).
+
+## Лицензия
+Этот проект лицензирован под лицензией MIT - подробности см. в файле [LICENSE](LICENSE).
+```
+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/index.scss

@@ -21,6 +21,7 @@
 @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/misc/get-uid';
 @forward 'modules/utilities/getters/number/get-number-from-percent';
 @forward 'modules/utilities/getters/number/get-number-height-by-ratio';
 @forward 'modules/utilities/getters/number/get-number-max';
@@ -28,6 +29,7 @@
 @forward 'modules/utilities/getters/number/get-number-percentage-of';
 @forward 'modules/utilities/getters/number/get-number-unit';
 @forward 'modules/utilities/getters/number/get-number-width-by-ratio';
+@forward 'modules/utilities/getters/string/get-string-hash';
 
 // Helpers
 @forward 'modules/utilities/helpers/color/color-blend';
@@ -60,7 +62,11 @@
 @forward 'modules/utilities/helpers/number/number-round-to-nearest';
 @forward 'modules/utilities/helpers/number/number-strip-unit';
 @forward 'modules/utilities/helpers/string/string-capitalize';
+@forward 'modules/utilities/helpers/string/string-count';
+@forward 'modules/utilities/helpers/string/string-lorips';
+@forward 'modules/utilities/helpers/string/string-repeat';
 @forward 'modules/utilities/helpers/string/string-replace';
+@forward 'modules/utilities/helpers/string/string-reverse';
 @forward 'modules/utilities/helpers/string/string-trim';
 @forward 'modules/utilities/helpers/string/string-trim-end';
 @forward 'modules/utilities/helpers/string/string-trim-start';

package/modules/utilities/converters/_convert-camel2kebab.scss

@@ -101,14 +101,15 @@
 /// 	заглавными буквами (кроме первой) добавлены дефисы.
 /// 	Результат готов к использованию как CSS-класс или
 /// 	часть селектора.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нестроковых значений. Аргумент должен быть строкой
-/// 	для корректной работы строковых функций Sass.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `string`
 @function convert-camel2kebab($value) {
 
 	// Переменная для накопления результата преобразования.
 	// Инициализируется пустой строкой.
-	$-result: '';
+	$-result: null;
 
 	// Проверка типа входного параметра: ожидается строковое значение.
 	// Функция is-string() проверяет, является ли $value строкой

package/modules/utilities/converters/_convert-em2px.scss

@@ -187,9 +187,11 @@
 /// @return {Number} - Значение в единицах `px`, рассчитанное
 /// 	по формуле: `($em * $base) * 1px`. Возвращает дробное
 /// 	или целое число с единицами измерения `px`.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нечисловых значений. Для корректной работы оба
-/// 	аргумента должны быть числами.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$em` → `number`
+/// - `$base` → `number`
 @function convert-em2px($em, $base: 16px) {
 
 	// Проверка типа первого параметра: ожидается числовое

package/modules/utilities/converters/_convert-hex2rgb.scss

@@ -52,6 +52,10 @@
 /// 	где `r`, `g`, `b` - числовые значения от 0 до 255.
 /// 	Если передан некорректный цвет, может вызвать ошибку
 /// 	Sass.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
 @function convert-hex2rgb($color) {
 
 	// Проверка типа входного параметра: ожидается

package/modules/utilities/converters/_convert-hex2rgba.scss

@@ -67,6 +67,11 @@
 /// @return {String} - Строка в формате `"rgba(r, g, b, a)"`,
 /// 	где `r`, `g`, `b` - числовые значения от 0 до 255,
 /// 	`a` - значение прозрачности.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
+/// - `$alpha` → `number`
 @function convert-hex2rgba($color, $alpha: 1) {
 
 	// Проверка типа первого параметра: ожидается

package/modules/utilities/converters/_convert-kebab2camel.scss

@@ -146,13 +146,14 @@
 /// 	дефисы удалены, а символы, которые следовали за
 /// 	дефисами, преобразованы в верхний регистр. Первый
 /// 	символ остается в исходном регистре.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нестроковых значений. Аргумент должен быть строкой
-/// 	для корректной работы строковых функций Sass.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `string`
 @function convert-kebab2camel($value) {
 
 	// Переменная для накопления результата преобразования.
-	$-result: "";
+	$-result: null;
 
 	// Проверка типа входного параметра: ожидается строковое значение.
 	// Функция is-string() проверяет, является ли $value строкой

package/modules/utilities/converters/_convert-kebab2snake.scss

@@ -78,10 +78,10 @@
 /// 	дефисы заменены на символы нижнего подчеркивания.
 /// 	Результат подходит для использования в backend-языках
 /// 	программирования, конфигурационных файлах и API-запросах.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нестроковых значений или если функция `string-replace`
-/// 	не определена. Требуется наличие функции `string-replace`
-/// 	в модуле `helpers` для корректной работы.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `string`
 /// @requires {function} string-replace - Вспомогательная
 /// 	функция замены подстрок в строке.
 /// 	Должна быть определена и доступна для корректной работы

package/modules/utilities/converters/_convert-px2em.scss

@@ -170,10 +170,11 @@
 /// @return {Number} - Значение в единицах `em`, рассчитанное
 /// 	по формуле: `($px / $base) * 1em`. Возвращает дробное
 /// 	или целое число с единицами измерения `em`.
-/// @throws {Error} - Может выбросить ошибку деления на ноль,
-/// 	если `$base` равен 0 после удаления единиц измерения.
-/// 	Также может выбросить ошибку при передаче нечисловых
-/// 	значений.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$px` → `number`
+/// - `$base` → `number`
 @function convert-px2em($px, $base: 16px) {
 
 	// Проверка типа первого параметра: ожидается числовое

package/modules/utilities/converters/_convert-px2rem.scss

@@ -114,10 +114,11 @@
 /// @return {Number} - Значение в единицах `rem`, рассчитанное
 /// 	по формуле: `($px / $base) * 1rem`. Возвращает дробное
 /// 	или целое число с единицами измерения `rem`.
-/// @throws {Error} - Может выбросить ошибку деления на ноль,
-/// 	если `$base` равен 0 после удаления единиц измерения.
-/// 	Также может выбросить ошибку при передаче нечисловых
-/// 	значений.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$px` → `number`
+/// - `$base` → `number`
 @function convert-px2rem($px, $base: 16px) {
 
 	// Проверка типа первого параметра: ожидается числовое

package/modules/utilities/converters/_convert-rem2px.scss

@@ -142,9 +142,11 @@
 /// @return {Number} - Значение в единицах `px`, рассчитанное
 /// 	по формуле: `($rem * $base) * 1px`. Возвращает дробное
 /// 	или целое число с единицами измерения `px`.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нечисловых значений. Для корректной работы оба аргумента
-/// 	должны быть числами.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$rem` → `number`
+/// - `$base` → `number`
 @function convert-rem2px($rem, $base: 16px) {
 
 	// Проверка типа первого параметра: ожидается числовое

package/modules/utilities/converters/_convert-snake2kebab.scss

@@ -124,10 +124,10 @@
 /// 	символы нижнего подчеркивания заменены на дефисы.
 /// 	Результат готов к использованию как CSS-класс, часть
 /// 	селектора или имя CSS-переменной.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нестроковых значений или если функция `string-replace`
-/// 	не определена. Требуется наличие функции `string-replace`
-/// 	в доступном scope.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `string`
 /// @require {function} string-replace - Вспомогательная
 /// 	функция замены подстрок в строке из модуля `helpers`.
 /// 	Должна быть определена и доступна для корректной работы

package/modules/utilities/getters/color/_get-color-brightness.scss

@@ -89,6 +89,10 @@
 /// 	Черный цвет вернет значение около 0%, белый - 100%,
 /// 	серые тона - промежуточные значения в зависимости от
 /// 	их светлоты.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
 @function get-color-brightness($color) {
 
 	// Проверка типа входного параметра: ожидается

package/modules/utilities/getters/color/_get-color-darkest.scss

@@ -104,13 +104,17 @@
 /// @throws {Error} - Может выбросить ошибку, если в списке
 /// 	встречаются элементы, не являющиеся цветами, при
 /// 	попытке вызова `color.channel()`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color-list` → `list`
 @function get-color-darkest($color-list) {
 
 	// Инициализация переменных для хранения результата поиска.
 	// - $-result: будет содержать самый темный цвет из списка
 	// - $-min-lightness: будет содержать минимальное значение
 	// 	  яркости (наименьшая яркость = самый темный)
-	$-result: '';
+	$-result: null;
 	$-min-lightness: null;
 
 	// Проверка типа входного параметра: ожидается список

package/modules/utilities/getters/list/_get-list-item-end.scss

@@ -82,8 +82,10 @@
 /// 	извлечь последний элемент
 /// @return {*} - Последний элемент списка. Возвращает
 /// 	`null`, если список пустой.
-/// @throws Не выбрасывает ошибок, возвращает
-/// 	`null` для пустых списков
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function get-list-item-end($list) {
 
 	@if not is-list($list) {

package/modules/utilities/getters/list/_get-list-item-start.scss

@@ -77,8 +77,10 @@
 /// 	первый элемент.
 /// @return {*} - Первый элемент списка. Возвращает `null`,
 /// 	если список пустой.
-/// @throws Не выбрасывает ошибки, но возвращает
-/// 	`null` для пустых списков.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function get-list-item-start($list) {
 
 	@if not is-list($list) {

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

@@ -90,15 +90,17 @@
 /// 	`null` для пустых списков, некорректных значений
 /// 	`$direction` или если список не содержит элементов
 /// 	в указанной позиции.
-/// @throws Не выбрасывает ошибок, безопасно обрабатывает
-/// 	некорректные входные данные. Для пустых списков и
-/// 	некорректных значений `$direction` возвращает `null`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
+/// - `$direction` → `string`
 @function get-list-item($list, $direction: 'start') {
 
 	// Переменная для хранения результата функции
 	// Инициализируем пустой строкой, но тип может
 	// измениться в зависимости от функций get-list-item-start/end
-	$-result: '';
+	$-result: null;
 
 	// ВАЛИДАЦИЯ ПАРАМЕТРА $direction