@mlut/core 1.0.0

package/dist/sass/tools/settings/base/_utils.scss

@@ -0,0 +1,578 @@
+@use 'sass:map';
+@use 'sass:list';
+
+// Utilities
+//
+// In the settings of utilities, there are both data and configs.
+//
+// Styleguide: settings.utils
+
+// Other
+//
+// Other settings that are not contained in main large maps
+//
+// Styleguide: settings.utils.other
+
+// $utils-up-specificity
+//
+// `boolean | string`<br>Increase the specificity of all utilities at once. When `true` - to each utility property will be added `!important`. A string with a CSS selector is also acceptable. It will be added before the utility selector. <br>Defaults to: `false`
+//
+// ```scss
+//	@use 'mlut/tools' as ml with (
+//		$utils-up-specificity: true,
+//	);
+//
+//	@include ml.apply('Mt2r');
+//
+//	// CSS
+//	.Mt2r {
+//		margin-top: 2rem !important;
+//	}
+// ```
+//
+// Styleguide: settings.utils.other.up_specificity
+
+// Utils groups
+//
+// Groups are stored in a separate database `$utils-groups-db`. To modify or add groups, use `$utils-groups`. When specifying utilities in the group, you can use Generation Syntax. In this case, utilities with components will be generated for each value.
+//
+// ```scss
+//	@use 'mlut' as ml with (
+//		$utils-groups: (
+//			'MPSpaces': (
+//				'M_ frc', Mt, Mr, Mb, Ml, -Mx, -My,
+//				P, Pt, Pr, Pb, Pl, -Px, -Py,
+//			),
+//		),
+//		$utils: (
+//			'MPSpaces': (
+//				100, '$myOffset'
+//			),
+//		),
+//	);
+//
+//	// CSS
+//	// some utils from standard library before
+//
+//	.M100 {
+//	  margin: 100px;
+//	}
+//
+//	.M100_frc:first-child {
+//	  margin: 100px;
+//	}
+//
+//	.M-\$myOffset {
+//	  margin: var(--ml-myOffset);
+//	}
+//
+//	.M-\$myOffset_frc:first-child {
+//	  margin: var(--ml-myOffset);
+//	}
+//
+//	.Mt100 {
+//	  margin-top: 100px;
+//	}
+//
+//	// etc
+// ```
+//
+// Styleguide: settings.utils.other.groups
+
+// Config
+//
+// Most of the settings are stored here, on the basis of which utilities work. Below are some sections that may be useful during customization.
+//
+// Styleguide: settings.utils.config
+
+// States
+//
+// States are stored in the `states` section and grouped by type:
+// - `pseudo-cls` - pseudo classes
+// - `pseudo-elm` - pseudo elements
+// - `custom` - all the rest
+//
+// Below is a quick reference of states. Later it will be supplemented by comments and examples.
+//
+// If you want to add a state, it is recommended to do this in the `custom` section. *Please note* that in the code, all custom states begin with a hyphen. This prevents names collision with native states from CSS.
+// ```scss
+//	@use 'mlut/tools' as ml with (
+//		$utils-config: (
+//			'states': (
+//				'custom': (
+//					'rtl': '[dir=“rtl”]',
+//				),
+//			),
+//		),
+//	);
+//
+//	@include ml.apply(('-rtl _Mr2r'), (), true);
+//
+//	// CSS
+//	[dir=“rtl”] .-rtl_Mr2r {
+//		margin-right: 2rem;
+//	}
+// ```
+//
+// Styleguide: settings.utils.config.states
+
+// Conversion type
+//
+// Available on the key `conversion-types`. This is a map, the keys in which are names of types that are used in utility options. The values in a map are a list of converters through which the value of utilities passes.
+// ```scss
+//	$utils-cfg: (
+//		'conversion-types': (
+//			'angle': ('angle', 'global-kw', 'cust-prop'),
+//			'grid-span': ('grid-span', 'num-length', 'global-kw', 'cust-prop'),
+//		),
+//	);
+// ```
+// Each converter is a function that returns, either an converted or initial value. By default, if the value was converted, then the process stops, else the value passes to the next converter from the list. If not a single  converter has no worked, then at the result we get the initial value. But this behavior can be changed when adding a keyword `Pl`(pipeline) to the list. The converters specified after it will be applied regardless of whether the value was converted in one of them. The list of all converters can be viewed in the code, but later they will be added here
+//
+// Below you can find all available types of conversion. In the description of each type there will be a schema: a list of converters and keywords on which the conversion depends. For DRY reason, in the schema used Sass variables containing frequently used converters. They will be presented in the documentation as meta-types. You can use these variables when adding new types of conversion. In addition, the description of the type will have examples of its work.
+//
+// Styleguide: settings.utils.config.conversion
+
+// $uv-type-base
+//
+// The basic meta type on which all other types are based. Schema:
+// ```scss
+//	$uv-type-base: ('global-kw', 'cust-prop');
+// ```
+// Usage:
+// ```scss
+//	// global keywords
+//	@debug ml.uv('C-ih'); // inherit
+//	@debug ml.uv('W-gSm'); // 520px - sm breakpoints
+//
+//	// custom properties
+//	@debug ml.uv('W-$myCard?200'); // var(--ml-myCard, 200px)
+// ```
+//
+// Styleguide: settings.utils.config.conversion.meta_base
+
+// $uv-type-default
+//
+// Meta type that corresponds to the default conversion type. If the type of conversion is not specified for the utility, then this will be used. Schema:
+// ```scss
+//	$uv-type-default: list.join(('keyword', 'number'), $uv-type-base);
+//
+//	// and below in the conversion types
+//	'conversion-types': (
+//		'default': $uv-type-default,
+// ```
+// Usage:
+// ```scss
+//	// keyword
+//	@debug ml.uv('Ai-c'); // center
+//	@debug ml.uv('Bd'); // 1px solid
+//
+//	// number
+//	@debug ml.uv('W200'); // 200px
+//	@debug ml.uv('Ml-0.7'); // -0.7rem
+//	@debug ml.uv('P1r;2e;5p'); // 1rem 2em 5%
+//	@debug ml.uv('Ml-2.5gg'); // calc(var(--ml-gg) * -2.5)
+//	@debug ml.uv('W1/3'); // 33.3333333333%
+//	@debug ml.uv('W2/$div'); // calc(2 / var(--ml-div) * 100%)
+// ```
+//
+// Styleguide: settings.utils.config.conversion.meta_default
+
+// num-length
+//
+// This type converts numbers almost as a default type, except that it does not convert numbers without units of measurement in a pixels. Schema:
+// ```scss
+//	('num-length': list.join('num-length', $uv-type-base))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('Zi5'); // 5
+//	@debug ml.uv('Tas2e'); // 2em
+// ```
+//
+// Styleguide: settings.utils.config.conversion.num-length
+
+// kw-num-length
+//
+// Type works almost as a default type, with the exception of that it does not convert numbers without units of measurement in a pixels. Schema:
+// ```scss
+//	('kw-num-length': list.set-nth($uv-type-default, 2, 'num-length'))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('Fnw300'); // 300
+//	@debug ml.uv('Fnw-bd'); // bolder
+//	@debug ml.uv('Lnh4.5u'); // 1.125rem
+// ```
+//
+// Styleguide: settings.utils.config.conversion.kw-num-length
+
+// num-percent
+//
+// Converts percent to decimal fractions. Schema:
+// ```scss
+//	('num-percent': list.join('num-percent', $uv-type-base))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('O70p'); // 0.7
+//	@debug ml.uv('-S-50p'); // -0.5
+// ```
+//
+// Styleguide: settings.utils.config.conversion.num-percent
+
+// angle
+//
+// Converts angles. Schema:
+// ```scss
+//	('angle': list.join('angle', $uv-type-base))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('-Rt45d'); // 45deg
+//	@debug ml.uv('-Rt-50g'); // -50grad
+//	@debug ml.uv('-Sk3.14r;2r'); // 3.14rad 2rad
+//	@debug ml.uv('-Hur-1.5t'); // -1.5turn
+// ```
+//
+// Styleguide: settings.utils.config.conversion.angle
+
+// color
+//
+// Converts colors. Schema:
+// ```scss
+//	('color': list.join('color', $uv-type-base))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('C-tp'); // transparent
+//	@debug ml.uv('Bgc#c06*$bgAlpha'); // rgba(204, 0, 102, var(--ml-bgAlpha, 1))
+//
+//	// you can use custom color keyword that you added in the database
+//	@debug ml.uv('Bgc-purple50*20p'); // rgba(102, 0, 204, 0.2)
+// ```
+//
+// Styleguide: settings.utils.config.conversion.color
+
+// abbr-kw
+//
+// Expand abbreaviations of utilities. Schema:
+// ```scss
+//	('abbr-kw': list.join('abbr', $uv-type-default))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('Wlc-tf'); // transform
+//	@debug ml.uv('Ts-bdc;2s,c;1s'); // border-color 2s, color 1s
+// ```
+//
+// Styleguide: settings.utils.config.conversion.abbr-kw
+
+// grid-tpl
+//
+// Adds converting of special keywords for grid templates to the default type. Schema:
+// ```scss
+//	('grid-tpl': list.join('grid-tracks', $uv-type-default))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('Gtc-t4'); // repeat(4, minmax(0, 1fr))
+//	@debug ml.uv('G-t3/af;d;15r'); // repeat(3, minmax(0, 1fr)) / auto-flow dense 15rem
+// ```
+//
+// Styleguide: settings.utils.config.conversion.grid-tpl
+
+// grid-span
+//
+// Converts special keywords, to specify the sizes of the grid items in spans. Schema:
+// ```scss
+//	('grid-span': list.join(('grid-span', 'num-length'), $uv-type-base))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('Gc-s3'); // span 3 / span 3
+// ```
+//
+// Styleguide: settings.utils.config.conversion.grid-span
+
+// outline
+//
+// Adds colors conversion to a default converters chain. Schema:
+// ```scss
+//	('outline': list.join(
+//		('keyword', 'color', 'number'), $uv-type-base
+//	))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('Bd3;tp;d'); // 3px transparent dotted
+// ```
+//
+// Styleguide: settings.utils.config.conversion.outline
+
+// gradient
+//
+// Converts values in the gradient functions. Schema:
+// ```scss
+//	('gradient': (
+//		'keyword', 'color', 'cust-prop', 'Pl', 'number', 'angle', 'global-kw'
+//	))
+// ```
+// Usage:
+// ```scss
+//	@debug ml.uv('-Gdrl-b;r,black,#ff0'); // repeating-linear-gradient(to bottom right, black, #ff0)
+//	@debug ml.uv('-Gdl-50d,blue;3r,cc;80p'); // linear-gradient(50deg, blue 3rem, currentColor 80%)
+// ```
+//
+// Styleguide: settings.utils.config.conversion.gradient
+
+$cCtx: '-Ctx' !default;
+$kSsVCP: 'Pl' !default; // pipeline
+$kSsUMCS: 'core' !default;
+$uv-type-base: ('global-kw', 'cust-prop',) !default;
+$uv-type-default: list.join(('keyword', 'number'), $uv-type-base);
+$uv-kw-alias-behavior: 0 !default;
+$utils-up-specificity: false !default;
+$utils-config: () !default;
+$utils-config-ext: () !default;
+$jit: () !default;
+
+//stylelint-disable
+$utils-cfg: (
+	'gg-fallback-list': (
+		T, R, B, L, -X, -Y, -I,
+		P, Pt, Pr, Pb, Pl, -Px, -Py,
+		M, Mt, Mr, Mb, Ml, -Mx, -My,
+		Bdw, Bdtw, Bdrw, Bdbw, Bdlw, -Bdxw, -Bdyw,
+		Bd, Bdt, Bdr, Bdb, Bdl, -Bdx, -Bdy,
+		Mxw, Mnw, Mxh, Mnh,
+		Fns, -Fns, Txi, Lnh, Lts, Txs, Va, Txd, Fn,
+		Bxsd, Bdrd, Bgs, Bgp, Ol, Olw, Olo,
+		Stw, Fl, Flb, Tfo, -Gdl, -Gdrl,
+	),
+
+	'conversion-types': (
+		'default': $uv-type-default,
+		'num-length': list.join('num-length', $uv-type-base),
+		'kw-num-length': list.set-nth($uv-type-default, 2, 'num-length'),
+		'num-percent': list.join('num-percent', $uv-type-base),
+		'angle': list.join('angle', $uv-type-base),
+		'color': list.join('color', $uv-type-base),
+		'abbr-kw': list.join('abbr', $uv-type-default),
+		'grid-tpl': list.join('grid-tracks', $uv-type-default),
+		'grid-span': list.join(('grid-span', 'num-length'), $uv-type-base),
+		'resolution': list.set-nth($uv-type-default, 2, 'resolution'),
+		'outline': list.join(
+			('keyword', 'color', 'number'), $uv-type-base
+		),
+		'gradient': (
+			'keyword', 'color', 'cust-prop', $kSsVCP, 'number', 'angle', 'global-kw'
+		)
+	),
+
+	'abbr-separators': (),
+
+	'converters': (),
+
+	'transformers': (),
+
+	'range-generators': (),
+
+	'units': (
+		'default': (
+			'': 1px,
+			'e': 1em,
+			'p': 1%,
+			'r': 1rem,
+		),
+		'num-length': (
+			'e': 1em,
+			'p': 1%,
+			'r': 1rem,
+		),
+		'resolution': (
+			'i': 1dpi,
+			'c': 1dpcm,
+			'x': 1dppx,
+		),
+		'num-percent': (
+			'p': 0.01,
+		),
+		'angle': (
+			'd': 1deg,
+			'g': 1grad,
+			'r': 1rad,
+			'ra': 1rad,
+			't': 1turn,
+		),
+	),
+
+	'tokens': (
+		'util': (
+			'str-value': '-',
+			'raw-value': '=',
+			'num-value': '',
+			'hash-value': '',
+			'fallback-value': '?',
+			'color-alpha': '*',
+			'space': ';',
+			'custom-property': '$',
+			'global-keyword': 'g',
+			'keyword-chain': '.',
+			'important': '!',
+			'no-list-separator': '  ',
+			'list-separator1': ',',
+			'list-separator2': '/',
+			'component': '_',
+		),
+		'states': (
+			'or': ',',
+			'and': ':',
+			'not': '!',
+			'custom': '-',
+			'this-util': '&',
+			'context': '^',
+			'raw': '=',
+		),
+		'generation': (
+			'states-pseudo-classes': 'StPC',
+			'states-pseudo-elements': 'StPE',
+			'states-only': 'StOl',
+			'states-combine': 'StCb',
+			'uv-keywords-alias': 'KW',
+		),
+	),
+
+	'states': (
+		'pseudo-cls': (
+			'a': ':active',
+			'c': ':checked',
+			'd': ':disabled',
+			'df': ':default',
+			'de': ':defined',
+			'e': ':empty',
+			'en': ':enabled',
+			'f': ':focus',
+			'fw': ':focus-within',
+			'fv': ':focus-visible',
+			'frc': ':first-child',
+			'frot': ':first-of-type',
+			'h': ':hover',
+			'i': ':invalid',
+			'id': ':indeterminate',
+			'inr': ':in-range',
+			'lc': ':last-child',
+			'lot': ':last-of-type',
+			'ln': ':link',
+			'oc': ':only-child',
+			'oot': ':only-of-type',
+			'ot': ':optional',
+			'ouor': ':out-of-range',
+			'phs': ':placeholder-shown',
+			'r': ':required',
+			'rt': ':root',
+			'rdo': ':read-only',
+			'rdw': ':read-write',
+			't': ':target',
+			'v': ':visited',
+			'vl': ':valid',
+		),
+		'pseudo-elm': (
+			'af': '::after',
+			'b': '::before',
+			'frl': '::first-line',
+			'frlt': '::first-letter',
+			'flsb': '::file-selector-button',
+			'm': '::marker',
+			'ph': '::placeholder',
+			's': '::selection',
+		),
+		'custom': (
+			'btc': '>*+*', // between children
+			'evc': ':nth-child(2n)', // even child
+			'evot': ':nth-of-type(2n)', // even of type
+			'odc': ':nth-child(odd)', // odd child
+			'odot': ':nth-of-type(odd)',
+			'op': '[open]',
+			'tif': '[tabindex="0"]', // tabindex focus
+			'nojs': '.no-js',
+		),
+	),
+) !default;
+
+$utils-cfg: map.deep-merge($utils-cfg, $utils-config);
+$utils-cfg: map.deep-merge($utils-cfg, $utils-config-ext);
+
+$tUSv: map.get($utils-cfg, 'tokens', 'util', 'str-value');
+$tUNv: map.get($utils-cfg, 'tokens', 'util', 'num-value');
+$tURv: map.get($utils-cfg, 'tokens', 'util', 'raw-value');
+$tUHv: map.get($utils-cfg, 'tokens', 'util', 'hash-value');
+$tUFv: map.get($utils-cfg, 'tokens', 'util', 'fallback-value');
+$tUCla: map.get($utils-cfg, 'tokens', 'util', 'color-alpha');
+$tUGkw: map.get($utils-cfg, 'tokens', 'util', 'global-keyword');
+$tUCp: map.get($utils-cfg, 'tokens', 'util', 'custom-property');
+$tUIm: map.get($utils-cfg, 'tokens', 'util', 'important');
+$tUCm: map.get($utils-cfg, 'tokens', 'util', 'component');
+$tUSp: map.get($utils-cfg, 'tokens', 'util', 'space');
+$tUKwc: map.get($utils-cfg, 'tokens', 'util', 'keyword-chain');
+$tUNls: map.get($utils-cfg, 'tokens', 'util', 'no-list-separator');
+$tULs1: map.get($utils-cfg, 'tokens', 'util', 'list-separator1');
+$tULs2: map.get($utils-cfg, 'tokens', 'util', 'list-separator2');
+
+$tSOr: map.get($utils-cfg, 'tokens', 'states', 'or');
+$tSAnd: map.get($utils-cfg, 'tokens', 'states', 'and');
+$tSNot: map.get($utils-cfg, 'tokens', 'states', 'not');
+$tSCs: map.get($utils-cfg, 'tokens', 'states', 'custom');
+$tSTu: map.get($utils-cfg, 'tokens', 'states', 'this-util');
+$tSCn: map.get($utils-cfg, 'tokens', 'states', 'context');
+$tSRaw: map.get($utils-cfg, 'tokens', 'states', 'raw');
+$tSTudv: $tSTu + $tUSv;
+
+$kUvKA: map.get($utils-cfg, 'tokens', 'generation', 'uv-keywords-alias');
+$kStPC: map.get($utils-cfg, 'tokens', 'generation', 'states-pseudo-classes');
+$kStPE: map.get($utils-cfg, 'tokens', 'generation', 'states-pseudo-elements');
+$kStCb: map.get($utils-cfg, 'tokens', 'generation', 'states-combine');
+$kStOl: map.get($utils-cfg, 'tokens', 'generation', 'states-only');
+$kCfOv: '/override' !default;
+$kCfBan: '/ban' !default;
+$kCfAl: '/allow' !default;
+
+$utils-cfg: map.set(
+	$utils-cfg,
+	'states',
+	'keywords',
+	map.merge(
+		(
+			$kStPC: 'pseudo-cls',
+			$kStPE: 'pseudo-elm',
+			$kStCb: null,
+			$kStOl: null,
+		),
+		map.get($utils-cfg, 'states', 'keywords') or ()
+	)
+);
+
+$utils-cfg: map.merge(
+	$utils-cfg,
+	(
+		'tokens-values': (
+			$tUNls: space,
+			$tULs1: comma,
+			$tULs2: slash,
+		),
+		'abbr-separators': list.join(
+			(
+				$tUSv,
+				$tUNv,
+				$tURv,
+				$tUHv,
+			),
+			map.get($utils-cfg, 'abbr-separators') or ()
+		)
+	)
+);
+
+$utils-states: map.merge(
+	map.get($utils-cfg, 'states', 'pseudo-cls'),
+	map.get($utils-cfg, 'states', 'pseudo-elm'),
+);