@omnisass/library 0.2.0 → 0.3.0

package/test.md

@@ -1,168 +0,0 @@
-Напиши мне комментарии SassDoc для этой функции:
-
-```scss
-@function convert-camel2kebab($value) {
-
-	$-result: '';
-	$-length: string.length($value);
-
-	@for $i from 1 through $-length {
-
-		$-char: string.slice($value, $i, $i);
-
-		@if $-char == string.to-upper-case($-char) and $i > 1 {
-			$-result: $-result + '-' + string.to-lower-case($-char);
-		} @else {
-			$-result: $-result + string.to-lower-case($-char);
-		}
-
-	}
-
-	@return $-result;
-
-}
-```
-но, так, как это сделано на примере этой функции:
-
-```scss
-/// Конвертирует значения из относительных единиц (`em`) в
-/// пиксели (`px`).
-///
-/// Функция выполняет преобразование значений в единицах `em`
-/// в пиксели относительно заданного базового размера. Это
-/// особенно полезно для обратных расчетов, когда необходимо
-/// получить точное пиксельное значение из относительного,
-/// учитывая контекст родительского элемента.
-///
-/// Важные особенности функции:
-/// - Преобразует `em` в `px` с указанием единиц `px`
-/// - Поддерживает кастомный базовый размер (по умолчанию 16px)
-/// - Удаляет единицы измерения для корректного математического
-/// 	расчета
-/// - Возвращает результат с единицами `px` для семантической
-/// 	ясности
-/// - Обрабатывает целые и дробные значения
-/// - Полезен для расчета точных размеров из относительных
-/// 	величин
-/// - Обеспечивает обратное преобразование к `convert-px2em`
-/// - Учитывает относительную природу `em` единиц
-/// ---
-/// @name convert-em2px
-/// @group utilities-converters
-/// @since 2025.12.27
-/// @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/numbers См. также: Официальная документация Sass - Тип данных "Числа"
-/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Единицы измерения в числах
-/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units См. также: MDN Web Docs - Значения и единицы измерения CSS
-/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Sizing_items_in_CSS См. также: MDN Web Docs - Размеры элементов в CSS
-/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/length См. также: MDN Web Docs - CSS-тип <length>
-/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
-/// @link https://css-tricks.com/snippets/css/guide-to-em-and-rem-units-in-css/ См. также: CSS-Tricks - Руководство по em и rem единицам в CSS
-/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
-/// @link https://www.w3schools.com/css/css_units.asp См. также: W3Schools - CSS единицы измерения
-/// @example scss - Стандартное преобразование (базовый размер 16px)
-/// 	@debug convert-em2px(1em);            // 16px
-/// 	@debug convert-em2px(0.5em);          // 8px
-/// 	@debug convert-em2px(1.5em);          // 24px
-/// 	@debug convert-em2px(2em);            // 32px
-/// 	@debug convert-em2px(3em);            // 48px
-/// 	@debug convert-em2px(0.25em);         // 4px
-/// 	@debug convert-em2px(0.0625em);       // 1px
-/// @example scss - Дробные значения em
-/// 	@debug convert-em2px(0.78125em);      // 12.5px
-/// 	@debug convert-em2px(1.171875em);     // 18.75px
-/// 	@debug convert-em2px(0.03125em);      // 0.5px
-/// 	@debug convert-em2px(0.9em);          // 14.4px
-/// 	@debug convert-em2px(1.125em);        // 18px
-/// 	@debug convert-em2px(1.333em);        // 21.328px
-/// @example scss - Кастомный базовый размер
-/// 	@debug convert-em2px(1em, 10px);      // 10px (база 10px)
-/// 	@debug convert-em2px(2em, 10px);      // 20px (база 10px)
-/// 	@debug convert-em2px(0.8em, 10px);    // 8px (база 10px)
-/// 	@debug convert-em2px(0.8em, 20px);    // 16px (база 20px)
-/// 	@debug convert-em2px(1.2em, 20px);    // 24px (база 20px)
-/// 	@debug convert-em2px(0.5em, 20px);    // 10px (база 20px)
-/// @example scss - Граничные случаи
-/// 	@debug convert-em2px(0em);            // 0px
-/// 	@debug convert-em2px(0em, 16px);      // 0px
-/// 	@debug convert-em2px(10em);           // 160px
-/// 	@debug convert-em2px(62.5em);         // 1000px
-/// 	@debug convert-em2px(0.01em, 100px);  // 1px
-/// 	@debug convert-em2px(100em);          // 1600px
-/// @example scss - Отрицательные значения
-/// 	@debug convert-em2px(-1em);           // -16px
-/// 	@debug convert-em2px(-0.5em);         // -8px
-/// 	@debug convert-em2px(-1.5em);         // -24px
-/// 	@debug convert-em2px(-2em, 8px);      // -16px
-/// @example scss - Безразмерные числа как аргументы
-/// 	@debug convert-em2px(1, 16);          // 16px (без единиц, но работает)
-/// 	@debug convert-em2px(0.5, 16);        // 8px
-/// 	@debug convert-em2px(1.5, 16);        // 24px
-/// @example scss - Контекст вложенности em
-/// 	// em зависят оass-lang.com/documentation/values/numbers#unitsт контекста родительского элемента
-/// 	.parent { font-size: 20px; }
-/// 	.child {
-/// 	  // 1em внутри .parent равно 20px
-/// 	  $px-value: convert-em2px(1em, 20px); // 20px
-/// 	  // 0.5em внутри .parent равно 10px
-/// 	  $px-value: convert-em2px(0.5em, 20px); // 10px
-/// 	}
-///
-/// 	// Вложенные em множатся
-/// 	.grandparent { font-size: 16px; }
-/// 	.parent { font-size: 1.5em; } // 24px
-/// 	.child {
-/// 	  // 1em внутри .parent равно 24px, а не 16px!
-/// 	  $px-value: convert-em2px(1em, 24px); // 24px
-/// 	}
-/// @example css - Результат
-/// 	.parent {
-/// 		font-size: 20px;
-/// 	}
-///
-/// 	.grandparent {
-/// 		font-size: 16px;
-/// 	}
-///
-/// 	.parent {
-/// 		font-size: 1.5em;
-/// 	}
-/// @param {Number} $em - Значение в единицах `em` для
-/// 	конвертации. Может быть целым или дробным числом,
-/// 	положительным или отрицательным. Единицы измерения (`em`)
-/// 	удаляются для расчета, но ожидается, что значение
-/// 	изначально выражено в `em`.
-/// @param {Number} $base [16px] - Базовый размер в пикселях
-/// 	для расчета. По умолчанию используется `16px`, что
-/// 	соответствует стандартному размеру шрифта в большинстве
-/// 	браузеров. Может быть любым положительным числом (обычно
-/// 	в пикселях). Важно, что параметр представляет размер
-/// 	шрифта родительского элемента, относительно которого
-/// 	рассчитываются `em`.
-/// @return {Number} - Значение в единицах `px`, рассчитанное
-/// 	по формуле: `($em * $base) * 1px`. Возвращает дробное
-/// 	или целое число с единицами измерения `px`.
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нечисловых значений. Для корректной работы оба
-/// 	аргумента должны быть числами.
-@function convert-em2px($em, $base: 16px) {
-	@return helpers.number-strip-unit($em) * helpers.number-strip-unit($base) * 1px;
-}
-```
-
-но, учти несколько моментов:
-
-1. Старайся описания укладывать такую же ширину строки
-2. В строке `/// @since` нужно указать текущую дату в формате `YYYY.MM.DD`
-3. Строку `/// @author Murad Rustamov (therteenten)` менять не нужно, как и строку `/// @group`
-4. Первые две ссылки также необходимо не трогать:
-```scss
-/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
-/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
-```
-5. Ссылки должны быть по теме, к которой относится смысл функции и ссылки должны быть в виде `/// @link https://some.com См. также: Название сайта - Название старницы` (данное правило не относится к первым двум ссылкам из пункта 4)
-6. Количество ссылок не меньше 8
-7. Примеры `/// @example` должны быть достоверны и без ошибок

package/test.scss

@@ -1,405 +0,0 @@
-
-
-
-
-
-
-
-
-
-// ============================================================================
-// 7. ФУНКЦИИ ЭКРАНИРОВАНИЯ И КОДИРОВАНИЯ
-// ============================================================================
-
-// Простое URL-кодирование
-
-
-// Экранирование кавычек
-@function escape-quotes($string) {
-	$string: string-replace($string, '"', '\"');
-	$string: string-replace($string, "'", "\'");
-	@return $string;
-}
-
-// Экранирование для использования в CSS-контенте
-@function escape-css-content($string) {
-	$string: string-replace($string, "\\", "\\\\");
-	$string: string-replace($string, '"', '\"');
-	$string: string-replace($string, "'", "\'");
-	$string: string-replace($string, "\n", "\\A ");
-	@return $string;
-}
-
-// ============================================================================
-// 8. ФУНКЦИИ ДЛЯ РАБОТЫ С ПУТЯМИ И ФАЙЛАМИ
-// ============================================================================
-
-// Получение имени файла из пути
-@function get-filename($path) {
-	$last-slash: string-index($path, "/");
-	@if $last-slash {
-		@return string.slice($path, $last-slash + 1);
-	}
-
-	$last-backslash: string-index($path, "\\");
-	@if $last-backslash {
-		@return string.slice($path, $last-backslash + 1);
-	}
-
-	@return $path;
-}
-
-// Получение расширения файла
-@function get-extension($filename) {
-	$last-dot: string-index($filename, ".");
-	@if $last-dot {
-		@return string.slice($filename, $last-dot + 1);
-	}
-	@return "";
-}
-
-// Получение имени файла без расширения
-@function get-filename-without-extension($filename) {
-	$extension: get-extension($filename);
-	@if string-length($extension) > 0 {
-		$extension-length: string-length($extension) + 1; // +1 для точки
-		@return string.slice($filename, 1, -$extension-length - 1);
-	}
-	@return $filename;
-}
-
-// Получение директории из пути
-@function get-directory($path) {
-	$last-slash: string-index($path, "/");
-	@if $last-slash {
-		@return string.slice($path, 1, $last-slash);
-	}
-
-	$last-backslash: string-index($path, "\\");
-	@if $last-backslash {
-		@return string.slice($path, 1, $last-backslash);
-	}
-
-	@return "./";
-}
-
-// ============================================================================
-// 9. ФУНКЦИИ ГЕНЕРАЦИИ И УНИКАЛЬНЫХ ИДЕНТИФИКАТОРОВ
-// ============================================================================
-
-// Генерация уникального идентификатора с префиксом
-@function unique-string-id($prefix: "id-") {
-	$random: random(1000000);
-	$timestamp: unique-id(); // Встроенная функция Sass
-	@return $prefix + $random + "-" + $timestamp;
-}
-
-// Генерация хеша из строки (упрощенный вариант)
-@function string-hash($string) {
-	$hash: 0;
-	$length: string-length($string);
-
-	@for $i from 1 through $length {
-		$char: string.slice($string, $i, $i);
-		$hash: (($hash * 31) + string-index("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", $char)) % 1000000;
-	}
-
-	@return $hash;
-}
-
-// ============================================================================
-// 10. ФУНКЦИИ ДЛЯ РАБОТЫ С КЛАССАМИ И СЕЛЕКТОРАМИ
-// ============================================================================
-
-// Генерация модификаторов для БЭМ
-@function generate-bem-modifiers($block, $modifiers...) {
-	$result: ();
-	@each $modifier in $modifiers {
-		$result: append($result, $block + "--" + $modifier, comma);
-	}
-	@return $result;
-}
-
-// Генерация элементов для БЭМ
-@function generate-bem-elements($block, $elements...) {
-	$result: ();
-	@each $element in $elements {
-		$result: append($result, $block + "__" + $element, comma);
-	}
-	@return $result;
-}
-
-// Создание селектора с состоянием
-@function with-state($selector, $state) {
-	@return $selector + ":" + $state;
-}
-
-// Создание селектора с псевдоэлементом
-@function with-pseudo($selector, $pseudo) {
-	@return $selector + "::" + $pseudo;
-}
-
-// ============================================================================
-// 11. ФУНКЦИИ ПАДИНГА И ВЫРАВНИВАНИЯ
-// ============================================================================
-
-// Дополнение строки слева
-@function string-pad-left($string, $length, $pad-char: " ") {
-	@while string-length($string) < $length {
-		$string: $pad-char + $string;
-	}
-	@return $string;
-}
-
-// Дополнение строки справа
-@function string-pad-right($string, $length, $pad-char: " ") {
-	@while string-length($string) < $length {
-		$string: $string + $pad-char;
-	}
-	@return $string;
-}
-
-// Дополнение строки с обеих сторон
-@function string-pad-both($string, $length, $pad-char: " ") {
-	@while string-length($string) < $length {
-		$string: $pad-char + $string + $pad-char;
-	}
-
-	// Если длина нечетная, удалить один символ справа
-	@if string-length($string) > $length {
-		$string: string.slice($string, 1, -2);
-	}
-
-	@return $string;
-}
-
-// Центрирование текста в указанной ширине
-@function string-center($string, $width, $pad-char: " ") {
-	$string-length: string-length($string);
-	@if $string-length >= $width {
-		@return $string;
-	}
-
-	$padding: $width - $string-length;
-	$left-padding: floor($padding / 2);
-	$right-padding: $padding - $left-padding;
-
-	$result: $string;
-	@for $i from 1 through $left-padding {
-		$result: $pad-char + $result;
-	}
-	@for $i from 1 through $right-padding {
-		$result: $result + $pad-char;
-	}
-
-	@return $result;
-}
-
-// ============================================================================
-// 12. ФУНКЦИИ ПОВТОРЕНИЯ И ГЕНЕРАЦИИ
-// ============================================================================
-
-// Повторение строки указанное количество раз
-@function string-repeat($string, $times) {
-	$result: "";
-	@for $i from 1 through $times {
-		$result: $result + $string;
-	}
-	@return $result;
-}
-
-// Генерация последовательности символов
-@function generate-sequence($start, $end) {
-	$result: "";
-	@for $i from $start through $end {
-		$result: $result + string.slice("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", $i, $i);
-	}
-	@return $result;
-}
-
-// Генерация Lorem Ipsum текста
-@function lorem-ipsum($words: 10) {
-	$lorem-words: "lorem" "ipsum" "dolor" "sit" "amet" "consectetur" "adipiscing" "elit" "sed" "do"
-								"eiusmod" "tempor" "incididunt" "ut" "labore" "et" "dolore" "magna" "aliqua" "ut"
-								"enim" "ad" "minim" "veniam" "quis" "nostrud" "exercitation" "ullamco" "laboris"
-								"nisi" "ut" "aliquip" "ex" "ea" "commodo" "consequat";
-
-	$result: "";
-	@for $i from 1 through $words {
-		$word-index: ($i - 1) % length($lorem-words) + 1;
-		$word: nth($lorem-words, $word-index);
-		$result: $result + $word;
-		@if $i != $words {
-			$result: $result + " ";
-		}
-	}
-
-	@return capitalize($result) + ".";
-}
-
-// ============================================================================
-// 13. ВСПОМОГАТЕЛЬНЫЕ И КОМБИНИРОВАННЫЕ ФУНКЦИИ
-// ============================================================================
-
-// Обращение строки
-@function string-reverse($string) {
-	$result: "";
-	$length: string-length($string);
-
-	@for $i from $length through 1 {
-		$result: $result + string.slice($string, $i, $i);
-	}
-
-	@return $result;
-}
-
-// Подсчет вхождений подстроки
-@function string-count($string, $substring) {
-	$count: 0;
-	$index: string-index($string, $substring);
-
-	@while $index != null {
-		$count: $count + 1;
-		$string: string.slice($string, $index + string-length($substring));
-		$index: string-index($string, $substring);
-	}
-
-	@return $count;
-}
-
-// Удаление всех пробелов
-@function remove-spaces($string) {
-	@return string-replace($string, " ", "");
-}
-
-// Удаление всех указанных символов
-@function remove-chars($string, $chars) {
-	@each $char in $chars {
-		$string: string-replace($string, $char, "");
-	}
-	@return $string;
-}
-
-// Получение уникальных символов из строки
-@function unique-chars($string) {
-	$result: "";
-	$length: string-length($string);
-
-	@for $i from 1 through $length {
-		$char: string.slice($string, $i, $i);
-		@if not contains($result, $char) {
-			$result: $result + $char;
-		}
-	}
-
-	@return $result;
-}
-
-// ============================================================================
-// 14. ФУНКЦИИ ДЛЯ РАБОТЫ С ЦВЕТАМИ (Строковые представления)
-// ============================================================================
-
-// Извлечение hex значения из строки цвета
-@function extract-hex($color-string) {
-	$color-string: to-lower-case($color-string);
-	$hash-index: string-index($color-string, "#");
-
-	@if $hash-index {
-		$hex-start: $hash-index + 1;
-		$hex: string.slice($color-string, $hex-start);
-
-		// Убираем все не-hex символы
-		$hex: remove-chars($hex, (" ", ";", ")", "(", ","));
-
-		@return "#" + $hex;
-	}
-
-	@return null;
-}
-
-// Проверка, является ли строка hex-цветом
-@function is-hex-color($string) {
-	$string: to-lower-case(string-trim($string));
-	@if not string-starts-with($string, "#") {
-		@return false;
-	}
-
-	$hex: string.slice($string, 2);
-	$hex-length: string-length($hex);
-
-	@if $hex-length != 3 and $hex-length != 6 and $hex-length != 8 {
-		@return false;
-	}
-
-	$valid-chars: "0123456789abcdef";
-
-	@for $i from 1 through $hex-length {
-		$char: string.slice($hex, $i, $i);
-		@if not contains($valid-chars, $char) {
-			@return false;
-		}
-	}
-
-	@return true;
-}
-
-// ============================================================================
-// 15. ФУНКЦИИ ДЛЯ РАБОТЫ С МЕДИА-ЗАПРОСАМИ
-// ============================================================================
-
-// Создание медиа-запроса с минимальной шириной
-@function min-width-query($width) {
-	@return "(min-width: " + $width + ")";
-}
-
-// Создание медиа-запроса с максимальной шириной
-@function max-width-query($width) {
-	@return "(max-width: " + $width + ")";
-}
-
-// Создание медиа-запроса для диапазона ширины
-@function width-range-query($min, $max) {
-	@return "(min-width: " + $min + ") and (max-width: " + $max + ")";
-}
-
-// ============================================================================
-// ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ
-// ============================================================================
-
-/*
-// Примеры использования функций:
-
-// 1. Базовые операции
-$test: "Hello World";
-$length: string-length($test); // 11
-$upper: to-upper-case($test); // "HELLO WORLD"
-$substr: string.slice($test, 7, 11); // "World"
-
-// 2. Проверки
-$has-world: contains($test, "World"); // true
-$starts-hello: string-starts-with($test, "Hello"); // true
-$ends-world: string-ends-with($test, "World"); // true
-
-// 3. Обрезка
-$trimmed: string-trim("	Hello	"); // "Hello"
-
-// 4. Замена
-$replaced: string-replace($test, "World", "Sass"); // "Hello Sass"
-
-// 5. Преобразование регистра
-$kebab: camel-to-kebab("helloWorld"); // "hello-world"
-$camel: kebab-to-camel("hello-world"); // "helloWorld"
-
-// 6. Работа с CSS значениями
-$unit: get-unit("10px"); // "px"
-$number: get-number("10px"); // 10
-$no-unit: strip-unit("10px"); // 10
-
-// 7. Генерация классов
-$modifiers: generate-bem-modifiers("button", "primary", "large");
-// ".button--primary, .button--large"
-*/
-
-// ============================================================================
-// КОНЕЦ БИБЛИОТЕКИ ФУНКЦИЙ ДЛЯ РАБОТЫ СО СТРОКАМИ
-// ============================================================================