@mlut/core 1.0.0

package/README.md

@@ -0,0 +1,24 @@
+# mlut core #
+
+<img alt="Logo" src="https://github.com/mr150/mlut/raw/master/docs/img/logo-full.png" width="350"/>
+
+The [mlut](https://github.com/mr150/mlut) core contains:
+- Sass tools
+- CSS library
+- JIT engine
+
+### Installation ###
+
+```
+npm i -D @mlut/core sass-embedded
+```
+
+When using this package, you will need to install Sass separately. We recommend [sass-embedded](https://www.npmjs.com/package/sass-embedded), but regular [sass](https://www.npmjs.com/package/sass) is also suitable.
+
+This allows you to control the versions of all your dependencies, and to choose which Sass implementation to use.
+
+## Documentation ##
+Full documentation available [here](https://mr150.github.io/mlut/)
+
+## License ##
+MIT

package/_index.scss

@@ -0,0 +1 @@
+@forward 'dist/sass';

package/_tools.scss

@@ -0,0 +1 @@
+@forward 'dist/sass/tools';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './jit/index.js';
+export * from './utils/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './jit/index.js';
+export * from './utils/index.js';

package/dist/jit/JitEngine.d.ts

@@ -0,0 +1,19 @@
+export declare class JitEngine {
+    private utils;
+    private inputFilePath;
+    private inputFileDir;
+    private sassModuleName;
+    private inputFileCache;
+    private generationDebounce;
+    private readonly defaultSassConfig;
+    private readonly utilsByFile;
+    private readonly utilsRegexps;
+    private readonly configRegexps;
+    init([inputPath, inputContent]?: [string | undefined, string | undefined]): Promise<void>;
+    putAndGenerateCss(id: string, content: string): Promise<string | undefined>;
+    private extractUtils;
+    private normalizeClassNameStr;
+    private extractUserSassConfig;
+    private loadUtils;
+}
+export declare const jitEngine: JitEngine;

package/dist/jit/JitEngine.js

@@ -0,0 +1,124 @@
+import path from 'node:path';
+import { logger } from '../utils/index.js';
+const sass = await import('sass-embedded')
+    .catch(() => import('sass'))
+    .catch(() => {
+    throw new Error('The Sass package is not installed. You can do this with `npm i -D sass-embedded`');
+});
+const __dirname = new URL('.', import.meta.url).pathname;
+export class JitEngine {
+    utils = new Set();
+    inputFilePath = '';
+    inputFileDir = __dirname;
+    sassModuleName = 'tools';
+    inputFileCache = '@use "../sass/tools";';
+    generationDebounce;
+    defaultSassConfig = '@use "sass:map";\n @use "../sass/tools/settings" as ml;';
+    utilsByFile = new Map();
+    utilsRegexps = {
+        quotedContent: /"\n?[^"]*?[A-Z][^"\n]*\n?"/g,
+        singleQuotedContent: /'\n?[^']*?[A-Z][^'\n]*\n?'/g,
+        tooMoreSpaces: /\s{2,}|\n/g,
+        utilName: /^-?[A-Z]{1}[a-zA-Z]*/,
+    };
+    configRegexps = {
+        userSettings: /@use ['"][^'"]*(tools|mlut|core)['"](\s*as\s+[\w]+)?\s+with\s*\(([^;]+)\);/s,
+        sassModuleName: /@use ['"][^'"]*(tools|mlut|core)['"]\s*;/s,
+    };
+    async init([inputPath, inputContent] = ['', '']) {
+        let sassConfig = this.defaultSassConfig;
+        if (inputPath && inputContent) {
+            this.inputFilePath = path.join(process.cwd(), inputPath);
+            this.inputFileDir = path.dirname(this.inputFilePath);
+            this.inputFileCache = inputContent;
+            sassConfig = this.extractUserSassConfig(inputContent);
+        }
+        await this.loadUtils(sassConfig);
+    }
+    async putAndGenerateCss(id, content) {
+        if (this.utils.size === 0) {
+            logger.warn('Config with utilities is not loaded!');
+            return '';
+        }
+        if (id === this.inputFilePath) {
+            this.inputFileCache = content;
+            const sassConfig = this.extractUserSassConfig(content);
+            if (sassConfig) {
+                await this.loadUtils(sassConfig);
+            }
+        }
+        else if (content) {
+            this.utilsByFile.set(id, this.extractUtils(content));
+        }
+        else {
+            this.utilsByFile.delete(id);
+        }
+        return new Promise((resolve) => {
+            //eslint-disable-next-line
+            let timeout;
+            clearTimeout(this.generationDebounce);
+            this.generationDebounce = setTimeout(async () => {
+                clearTimeout(timeout);
+                const allUniqueUtils = [...new Set([...this.utilsByFile.values()].flat())];
+                const applyStr = `\n@include ${this.sassModuleName}.apply(${JSON.stringify(allUniqueUtils)},(),true);`;
+                // `compileStringAsync` is almost always faster than `compile` in sass-embedded
+                const css = await sass.compileStringAsync(this.inputFileCache + applyStr, { loadPaths: [this.inputFileDir, 'node_modules'] }).then(({ css }) => css, (e) => (logger.error('Sass compilation error.', e), undefined));
+                resolve(css);
+            }, 100);
+            timeout = setTimeout(() => resolve(undefined), 300);
+        });
+    }
+    extractUtils(content) {
+        const allClassNames = [];
+        const quotedClassNames = content
+            .match(this.utilsRegexps.quotedContent)
+            //eslint-disable-next-line
+            ?.map(this.normalizeClassNameStr, this);
+        const singleQuotedClassNames = content
+            .replace(this.utilsRegexps.quotedContent, '')
+            .match(this.utilsRegexps.singleQuotedContent)
+            //eslint-disable-next-line
+            ?.map(this.normalizeClassNameStr, this);
+        for (const item of [quotedClassNames, singleQuotedClassNames]) {
+            if (item instanceof Array) {
+                allClassNames.push(...item);
+            }
+        }
+        return [...allClassNames.join(' ').split(' ').reduce((acc, cssClass) => {
+                const utility = cssClass.split('_').find((str) => (this.utilsRegexps.utilName.test(str)));
+                if (utility) {
+                    const utilName = utility.match(this.utilsRegexps.utilName)?.[0];
+                    if (this.utils.has(utilName) || utilName[0] === '-') {
+                        acc.add(cssClass);
+                    }
+                }
+                return acc;
+            }, new Set())];
+    }
+    normalizeClassNameStr(str) {
+        return str.replace(this.utilsRegexps.tooMoreSpaces, ' ').slice(1, -1);
+    }
+    extractUserSassConfig(content) {
+        let matchResult = content.match(this.configRegexps.userSettings);
+        if (matchResult != null) {
+            const userSettings = matchResult.at(-1);
+            this.sassModuleName = matchResult[2] ?
+                matchResult[2].replace(/\s*as\s*/, '') :
+                matchResult[1];
+            return this.defaultSassConfig.slice(0, -1) + ` with (${userSettings});`;
+        }
+        matchResult = content.match(this.configRegexps.sassModuleName);
+        if (matchResult != null) {
+            this.sassModuleName = matchResult[1];
+        }
+    }
+    async loadUtils(userConfig = this.defaultSassConfig) {
+        const { css } = (await sass.compileStringAsync(userConfig + '\n a{ all: map.keys(map.get(ml.$utils-db, "utils", "registry")); }', {
+            style: 'compressed',
+            loadPaths: [__dirname, 'node_modules'],
+        }));
+        const strEnd = css.lastIndexOf('"') - css.length + 1;
+        this.utils = new Set(JSON.parse('[' + css.split('all:')[1].slice(0, strEnd) + ']'));
+    }
+}
+export const jitEngine = new JitEngine();

package/dist/jit/index.d.ts

@@ -0,0 +1 @@
+export * from './JitEngine.js';

package/dist/jit/index.js

@@ -0,0 +1 @@
+export * from './JitEngine.js';

package/dist/sass/addons/demo-theme.scss

@@ -0,0 +1,112 @@
+@use 'sass:map';
+@use '../tools' as ml;
+
+// Demo theme
+//
+// A full-fledged design theme to create an interface. Contains a set of utilities and a colors palette.
+//
+// By default (in JIT mode), only the palette will be loaded. If you want to load and generate utilities (AOT), pass `$is-aot: true` to the module configuration.
+//
+// Styleguide: addons.catalog.demo_theme
+
+// Colors
+//
+// Colors are automatically loaded into the mlut settings, so you can use them when adding utilities or styles. Utilities with colors are generated with [range syntax](section-how_to.html#kssref-how_to-mk_utils-range-color).
+// - step of color shade: **25**
+// - step in the value of utilities: **50**
+// - shades for each color: **8**. This means that for each color there are shades from 0 to 350. For example: `C-red0`, `Bgc-blue150`
+//
+// Name | Base color
+// :---  | :---
+// gray | <span style="background-color: #c5ccd3">#c5ccd3</span>
+// red | <span style="background-color: #ff5c5c"><span style="color: white">#ff5c5c</span></span>
+// orange | <span style="background-color: #ffad5c">#ffad5c</span>
+// yellow | <span style="background-color: #faeb61">#faeb61</span>
+// green | <span style="background-color: #70fa61">#70fa61</span>
+// aqua | <span style="background-color: #5cffbb">#5cffbb</span>
+// blue | <span style="background-color: #62a8f8">#62a8f8</span>
+// purple | <span style="background-color: #d35cff">#d35cff</span>
+//
+// Styleguide: addons.catalog.demo_theme.colors
+
+$demo-colors: (
+	'gray0': #c5ccd3,
+	'red0': #ff5c5c,
+	'orange0': #ffad5c,
+	'yellow0': #faeb61,
+	'green0': #70fa61,
+	'aqua0': #5cffbb,
+	'blue0': #62a8f8,
+	'purple0': #d35cff,
+);
+
+ml.$utils-db: map.merge(
+	ml.$utils-db, 'common', 'keywords', 'colors',
+	map.merge(
+		$demo-colors,
+		map.get(ml.$utils-db, 'common', 'keywords', 'colors')
+	)
+);
+
+$is-aot: false !default;
+$shade-step: -25 !default;
+$-color-names: map.keys($demo-colors);
+
+@if $is-aot {
+	$generate: true !default;
+	$colors-at-rules: ml.$kBpAll !default;
+	$colors-pre-states: '^:h' !default;
+	$colors-post-states: 'h f fw ph' !default;
+
+	$colors-at-rules: $colors-at-rules and $colors-at-rules + '_';
+	$colors-pre-states: $colors-pre-states and $colors-pre-states + ' _';
+	$colors-post-states: $colors-post-states and '_ ' + $colors-post-states;
+
+	$-colors-key: $colors-at-rules + $colors-pre-states + 'Colors' + $colors-post-states;
+
+	//stylelint-disable
+	$demo-utils: (
+		ml.$cBpAllCp + 'W': (5u, 10u, 20u, 25u, 40u, 70u),
+		ml.$cBpAllCp + 'H': (5u, 10u, 20u, 25u),
+		$-colors-key: ([
+		$-color-names, 8, ('rgb': $shade-step)
+	], 'white'),
+		ml.$cBpAllCp + 'Fns': ([1u, 8], 3gg, 14u, 4gg, 5gg),
+		ml.$cBpAllCp + 'Lnh': (
+			'md': 1.4,
+			'lg': 1.6,
+			'xl': 1.8,
+			'xxl': 2,
+		),
+		ml.$cBpAllCp + 'Offsets': ([1u, 8],),
+		ml.$cBpAllCp + 'Translates': ([1u, 8], [-8u, -1]),
+		ml.$cBpAllCp + 'BdWidth': (1u, 2u),
+		ml.$cBpAllCp + 'BdRadius': (2, [1u, 4]),
+		ml.$kBpAll + ' #{ml.$kArSt}_^:h _O_ h f fw': ([10p, 90, 10],),
+		ml.$kBpAll + ' #{ml.$kArSt}_^:h _Bxsd_ h f fw': (
+			'sm': rgba(0, 0, 0, 0.16) 0px 1px 4px,
+			'md': rgba(0, 0, 0, 0.24) 0px 3px 8px,
+			'lg': rgba(0, 0, 0, 0.35) 0px 5px 15px,
+		),
+		ml.$cArStBp + '-S_ h f': (0.8, 0.9, 1.1, 1.2, 1.5),
+	);
+
+	@if $generate {
+		ml.$utils-map: map.set(
+			ml.$utils-map,
+			'demo-theme',
+			$demo-utils
+		);
+	}
+} @else {
+	ml.$utils-db: map.merge(
+		ml.$utils-db, 'common', 'keywords', 'colors',
+		map.merge(
+			map.get(
+				ml.generate-uv-color-range([$-color-names, 8, ('rgb': $shade-step)], 'C'),
+				'values',
+			),
+			map.get(ml.$utils-db, 'common', 'keywords', 'colors')
+		)
+	);
+}

package/dist/sass/css/_base-setup.scss

@@ -0,0 +1,3 @@
+@forward 'styles';
+@forward 'helpers';
+@forward 'utils/load';

package/dist/sass/css/_index.scss

@@ -0,0 +1,2 @@
+@forward 'styles';
+@forward 'helpers';

package/dist/sass/css/helpers/_index.scss

@@ -0,0 +1,3 @@
+@forward 'btn';
+@forward 'wrapper';
+@forward 'ratio-box';

package/dist/sass/css/helpers/btn.scss

@@ -0,0 +1,28 @@
+@use '../../tools' as ml;
+
+/*
+Btn
+
+Helper for creating buttons. Prepares any element to styling as a button.
+
+Markup: ../../../docs/examples/css_lib-helpers/btn/btn.html
+
+Styleguide: css_lib.helpers.btn
+*/
+
+.btn {
+	display: inline-block;
+	margin: 0;
+	padding: 0;
+	line-height: inherit;
+	text-align: center;
+	text-decoration: none;
+	vertical-align: middle;
+	background: none;
+	border: 0;
+	cursor: pointer;
+
+	@if not ml.$base-border-box {
+		box-sizing: border-box;
+	}
+}

package/dist/sass/css/helpers/gs-debug.scss

@@ -0,0 +1,28 @@
+@use '../../tools' as ml;
+
+/*
+Grid-system debug
+
+Helper for debugging layouts that built with grid system. It displays a grid system columns and gutters in the background of the container. The grid system are generated depending on the [settings](section-settings.html#kssref-settings-gs).
+
+There may be minor inaccuracies in the drawing of the grid, because the grid is generated with CSS `linear-gradient()`. For gutters calculation are used [CSS custom properties](section-css_lib.html#kssref-css_lib-styles-css_vars).
+
+It **not included** in the default mlut distributive.
+
+Markup: ../../../docs/examples/css_lib-helpers/grid-debug/grid-debug.html
+
+Styleguide: css_lib.helpers.gs-debug
+*/
+
+.gs-debug {
+	/* autoprefixer: off */
+	padding: calc(var(ml.$var-gg) * 3) 0px;
+	background-image: linear-gradient(
+		90deg,
+		ml.$gs-debug-gtr-color var(ml.$var-gg),
+		ml.$gs-debug-col-color var(ml.$var-gg),
+		ml.$gs-debug-col-color calc(100% - var(ml.$var-gg)),
+		ml.$gs-debug-gtr-color 0
+	);
+	background-size: calc(1 / var(ml.$var-gscc) * 100%);
+}

package/dist/sass/css/helpers/ratio-box.scss

@@ -0,0 +1,47 @@
+@use '../../tools' as ml;
+
+/*
+Ratio-box
+
+Helper for creating containers, with proportional width and height. Implemented using a pseudo-element with a `padding-bottom` in %.
+
+The default aspect ratio is 16:9.
+
+.Pt75p_b - 4:3 aspect ratio.
+.Pt100p_b - 1:1 aspect ratio.
+
+Markup: ../../../docs/examples/css_lib-helpers/ratio-block/ratio-block.hbs
+
+Styleguide: css_lib.helpers.ratio-box
+*/
+
+.ratio-box {
+	position: relative;
+
+	&::before {
+		display: block;
+		width: 100%;
+		padding-top: 56.25%;
+		content: '';
+	}
+
+	> :first-child {
+		position: absolute;
+		top: 0px;
+		left: 0px;
+		width: 100%;
+		height: 100%;
+	}
+}
+
+@if ml.$ratio-box-flex {
+	.ratio-box-flex {
+		&::before {
+			float: left;
+			padding-top: 56.25%;
+			content: '';
+		}
+
+		@include ml.apply('-Cl');
+	}
+}

package/dist/sass/css/helpers/row.scss

@@ -0,0 +1,98 @@
+@use '../../tools' as ml;
+
+/*
+Row
+
+Helper for creating layouts. Suitable for columns, cards and horizontal lists. By default, flexbox technology is used for layouts.
+
+Parts of the layout within a `row` are created using the elements:
+* [row__col](#kssref-css_lib-helpers-row-row__col)
+* [row__item](#kssref-css_lib-helpers-row-row__item)
+
+`Rows` can be put into each other an unlimited number of times.
+
+`Row` contains CSS counter named `ml-row-item`.
+
+It **not included** in the default mlut distributive because partially based on the legacy grid system. It is recommended to use the [CSS grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout) utilities instead.
+
+Markup: ../../../docs/examples/css_lib-helpers/row/row.html
+
+Styleguide: css_lib.helpers.row
+*/
+
+/*
+row__col
+
+The main element for creating columns in layout. By default, it stretches the entire width of the container. The columns have gutters on the sides and bottom.
+
+The gutters are implemented using the `margin` and [CSS custom properties](section-css_lib.html#kssref-css_lib-styles-css_vars).
+
+Column width is set using [W utility](section-utils-reference.html#kssref-utils-reference-w). See example [above](#kssref-css_lib-helpers-row). The formulas for calculating the width and offset for the column are stored in the custom properties. In `--ml-gscf` for W and `--ml-gsof` for [Ml utility](section-utils-reference.html#kssref-utils-reference-ml). These formulas:
+```scss
+--ml-gscf: calc(var(--ml-gsc) / var(--ml-gscc) * 100% - var(--ml-gsfd, var(--ml-gg)) * 2);
+--ml-gsof: calc(var(--ml-gso) / var(--ml-gscc) * 100% + var(--ml-gsfd, var(--ml-gg)));
+```
+`--ml-gsc` or `--ml-gso` is the value of the width or offset in the grid columns. This is a custom property of the utility.<br>
+`--ml-gscc` - the number of columns in the grid system. This is a [global](section-css_lib.html#kssref-css_lib-styles-css_vars) custom property that can be changed on any DOM node.<br>
+`--ml-gsfd` - variable is equal to the gutter if the gutter at the columns is created using margin. In `row__col` is equal `1gg`.<br>
+Some of these variables can be changed using [custom utilities](section-utils-reference.html#kssref-utils-reference--gscc).
+
+You can create nested layouts with a mix of `row` and `row__col` on the same DOM node. If you don't need double fields in the nested row, use the mix with the `row__item`. See example below.
+
+Markup: ../../../docs/examples/css_lib-helpers/row/row__col.html
+
+Styleguide: css_lib.helpers.row.row__col
+*/
+
+/*
+row__item
+
+Element for creating parts of the layout. By default, it stretches across the width of the content.
+
+The sizes and offsets are set with help of utilities.
+
+Like a `row__col`, an element contains formulas for calculating width and offset. But `--ml-gsfd` here is equal 0px.
+
+Markup: ../../../docs/examples/css_lib-helpers/row/row__item.html
+
+Styleguide: css_lib.helpers.row.row__item
+*/
+
+.row {
+	position: relative;
+	display: flex;
+	flex-wrap: wrap;
+	padding: 0px;
+	list-style: none;
+	counter-reset: ml-row-item;
+
+	@include ml.apply('M0;-1gg');
+}
+
+.row__col,
+.row__item {
+	#{ml.$var-gsfd}: 0px;
+	max-width: 100%;
+
+	@if not ml.$base-border-box {
+		box-sizing: border-box;
+	}
+
+	@include ml.apply('-Gsf');
+
+	& > :first-child:not([class]) {
+		margin-top: 0px;
+	}
+
+	& > :last-child:not([class]) {
+		margin-bottom: 0px;
+	}
+}
+
+.row__col {
+	@include ml.apply('-Gsfd1gg W12gc M0;1gg;2gg');
+
+	&.row {
+		margin-bottom: 0px;
+	}
+}

package/dist/sass/css/helpers/wrapper.scss

@@ -0,0 +1,21 @@
+@use '../../tools' as ml;
+
+/*
+Wrapper
+
+The helper-container for the main content of the page. The maximum width is set in the [settings](section-settings.html#kssref-settings-general). The default is `1200px`.
+
+The container has sides `padding` that equal to gutters so that the content does not stick to sides on small screens. On wide screens the container is centered.
+
+Markup: ../../../docs/examples/css_lib-helpers/wrapper/wrapper.html
+
+Styleguide: css_lib.helpers.wrapper
+*/
+
+.wrapper {
+	display: block;
+	max-width: ml.$wrapper-max-width;
+	margin: 0 auto;
+
+	@include ml.apply('-Px1gg');
+}

package/dist/sass/css/styles/_index.scss

@@ -0,0 +1,2 @@
+@forward 'variables';
+@forward 'generic';