@oardi/css-utils 0.134.0 → 1.0.0

package/css-utils-manifest.json

@@ -1,14 +1,15 @@
 {
 	"package": "@oardi/css-utils",
-	"version": "0.134.0",
+	"version": "1.0.0",
 	"breakpoints": { "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" },
 	"lifecycle": {
-		"deprecated": [
+		"deprecated": [],
+		"removed": [
 			{
 				"pattern": "lh-{value}",
 				"values": ["xs", "sm", "md", "lg", "xl", "xxl", "xxxl"],
 				"deprecatedIn": "0.123.0",
-				"plannedRemoval": "next major release",
+				"removedIn": "1.0.0",
 				"replacements": {
 					"lh-xs": "line-height-none",
 					"lh-sm": "line-height-tight",
@@ -23,12 +24,10 @@
 				"pattern": "letter-space-{value}",
 				"values": ["0", "1", "2", "3", "4", "5"],
 				"deprecatedIn": "0.130.0",
-				"plannedRemoval": "next major release",
+				"removedIn": "1.0.0",
 				"replacement": "letter-spacing-{effect}",
 				"note": "Choose an effect intentionally; the relative scale is not a visual alias for the pixel scale."
-			}
-		],
-		"removed": [
+			},
 			{
 				"pattern": "active",
 				"deprecatedIn": "0.53.0",
@@ -70,15 +69,10 @@
 		},
 		"Text / colors": {
 			"families": [
-				{ "patterns": ["letter-space-{value}"], "values": ["0", "1", "2", "3", "4", "5"] },
 				{
 					"patterns": ["letter-spacing-{value}"],
 					"values": ["normal", "tight", "wide", "wider", "widest"]
 				},
-				{
-					"patterns": ["lh-{value}", "text-{breakpoint}-{value}"],
-					"values": ["lg", "md", "sm", "xl", "xs", "xxl", "xxxl"]
-				},
 				{
 					"patterns": ["line-height-{value}"],
 					"values": ["loose", "none", "normal", "relaxed", "snug", "tight"]
@@ -111,6 +105,10 @@
 					"patterns": ["text-underline-{value}"],
 					"values": ["accent", "error", "primary", "secondary", "success", "warning"]
 				},
+				{
+					"patterns": ["text-{breakpoint}-{value}"],
+					"values": ["lg", "md", "sm", "xl", "xs", "xxl", "xxxl"]
+				},
 				{
 					"patterns": ["text-{value}"],
 					"values": [
@@ -726,6 +724,10 @@
 				"btn",
 				"card",
 				"chip",
+				"combobox",
+				"combobox-empty",
+				"combobox-option",
+				"combobox-panel",
 				"disabled",
 				"drawer",
 				"drawer-body",

package/css-utils-reference.md

@@ -3,7 +3,7 @@
 > Generated automatically. Do not edit manually.
 
 - Package: `@oardi/css-utils`
-- Version: `0.134.0`
+- Version: `1.0.0`
 - Source: public SCSS entry point and utility configuration
 
 ## Usage guidance
@@ -20,10 +20,12 @@ Deprecated classes are still emitted and remain listed in the current API groups
 
 ### Deprecated
 
+### Removed
+
 - `lh-{value}`
     - Values: `xs` | `sm` | `md` | `lg` | `xl` | `xxl` | `xxxl`
     - Deprecated in: `0.123.0`
-    - Planned removal: next major release
+    - Removed in: `1.0.0`
     - Replacements:
         - `lh-xs` -> `line-height-none`
         - `lh-sm` -> `line-height-tight`
@@ -32,15 +34,15 @@ Deprecated classes are still emitted and remain listed in the current API groups
         - `lh-xl` -> `line-height-relaxed`
         - `lh-xxl` -> `line-height-loose`
         - `lh-xxxl` -> `line-height-extra-loose`
+    - Availability: not emitted by the current package
 
 - `letter-space-{value}`
     - Values: `0` | `1` | `2` | `3` | `4` | `5`
     - Deprecated in: `0.130.0`
-    - Planned removal: next major release
+    - Removed in: `1.0.0`
     - Replacement: `letter-spacing-{effect}`
     - Note: Choose an effect intentionally; the relative scale is not a visual alias for the pixel scale.
-
-### Removed
+    - Availability: not emitted by the current package
 
 - `active`
     - Deprecated in: `0.53.0`
@@ -93,19 +95,10 @@ Classes:
 
 ## Text / colors
 
-Values: `0` | `1` | `2` | `3` | `4` | `5`
-
-- `letter-space-{value}`
-
 Values: `normal` | `tight` | `wide` | `wider` | `widest`
 
 - `letter-spacing-{value}`
 
-Values: `lg` | `md` | `sm` | `xl` | `xs` | `xxl` | `xxxl`
-
-- `lh-{value}`
-- `text-{breakpoint}-{value}`
-
 Values: `loose` | `none` | `normal` | `relaxed` | `snug` | `tight`
 
 - `line-height-{value}`
@@ -118,6 +111,10 @@ Values: `accent` | `error` | `primary` | `secondary` | `success` | `warning`
 
 - `text-underline-{value}`
 
+Values: `lg` | `md` | `sm` | `xl` | `xs` | `xxl` | `xxxl`
+
+- `text-{breakpoint}-{value}`
+
 Values: `accent` | `black` | `body` | `capitalize` | `center` | `end` | `error` | `inherit` | `inverse` | `lg` | `md` | `muted` | `primary` | `secondary` | `sm` | `start` | `subtle` | `success` | `uppercase` | `warning` | `white` | `xl` | `xs` | `xxl` | `xxxl`
 
 - `text-{value}`
@@ -500,6 +497,10 @@ Classes:
 - `btn`
 - `card`
 - `chip`
+- `combobox`
+- `combobox-empty`
+- `combobox-option`
+- `combobox-panel`
 - `disabled`
 - `drawer`
 - `drawer-body`

package/migration-v1.md

@@ -0,0 +1,91 @@
+# Migrating to CSS Utils 1.0.0
+
+Version 1.0.0 removes the deprecated typography compatibility API. Update your markup, CSS-variable overrides and Sass configuration before upgrading from 0.x. The effect-based default values, base font sizes, responsive font-size utilities and semantic heading styles are unchanged.
+
+## Line height
+
+Replace the removed classes and size-based CSS tokens with their effect-based counterparts:
+
+| Removed class | Replacement                | Removed token        | Replacement token           | Default |
+| ------------- | -------------------------- | -------------------- | --------------------------- | ------- |
+| `.lh-xs`      | `.line-height-none`        | `--line-height-xs`   | `--line-height-none`        | `1`     |
+| `.lh-sm`      | `.line-height-tight`       | `--line-height-sm`   | `--line-height-tight`       | `1.125` |
+| `.lh-md`      | `.line-height-snug`        | `--line-height-md`   | `--line-height-snug`        | `1.25`  |
+| `.lh-lg`      | `.line-height-normal`      | `--line-height-lg`   | `--line-height-normal`      | `1.5`   |
+| `.lh-xl`      | `.line-height-relaxed`     | `--line-height-xl`   | `--line-height-relaxed`     | `1.75`  |
+| `.lh-xxl`     | `.line-height-loose`       | `--line-height-xxl`  | `--line-height-loose`       | `2`     |
+| `.lh-xxxl`    | `.line-height-extra-loose` | `--line-height-xxxl` | `--line-height-extra-loose` | `2.5`   |
+
+The global `--line-height` token remains unchanged. Range Slider marks, Stepper labels/status and Skeleton text placeholders now use `--line-height-tight`; migrate any old `--line-height-sm` overrides intended to customize those components.
+
+### Sass configuration
+
+The `lineHeights` theme map keeps its name and now uses effect names directly. Rename its keys using the same mapping above, including any `map.get()` calls in your own Sass. The intermediate public `$line-height-effect-names` map has been removed.
+
+Before:
+
+```scss
+@use '@oardi/css-utils/theme' with (
+	$theme: (
+		lineHeights: (
+			sm: 1.2,
+		),
+	)
+);
+@use '@oardi/css-utils';
+```
+
+After:
+
+```scss
+@use '@oardi/css-utils/theme' with (
+	$theme: (
+		lineHeights: (
+			tight: 1.2,
+		),
+	)
+);
+@use '@oardi/css-utils';
+```
+
+Import and configure the theme before any CSS Utils entry point that uses it. The theme import itself emits no CSS. The Dart Sass CLI uses the same imports with a `pkg:` prefix and `--pkg-importer=node`.
+
+Custom keys are supported: `lineHeights: (compact: 1.1)` adds `--line-height-compact` and `.line-height-compact`. Existing defaults are retained through the theme's deep merge. Old size keys are no longer aliases for effect names; leaving `sm` in your configuration does not customize `tight`.
+
+## Letter spacing
+
+The `.letter-space-0` through `.letter-space-5` classes and the public `$letterSpacings` list from the `text` Sass module have been removed. Use the existing `letterSpacings` **theme map** and `.letter-spacing-{effect}` utilities instead.
+
+| Class                    | Default    |
+| ------------------------ | ---------- |
+| `.letter-spacing-tight`  | `-0.025em` |
+| `.letter-spacing-normal` | `0`        |
+| `.letter-spacing-wide`   | `0.025em`  |
+| `.letter-spacing-wider`  | `0.05em`   |
+| `.letter-spacing-widest` | `0.1em`    |
+
+`.letter-space-0` can become `.letter-spacing-normal` with the default theme. For the old positive pixel values, choose an effect deliberately: the relative scale changes with font size and is not a visual alias for `1px` through `5px`.
+
+To preserve a specific pixel value, define a custom theme key instead:
+
+```scss
+@use '@oardi/css-utils/theme' with (
+	$theme: (
+		letterSpacings: (
+			label: 2px,
+		),
+	)
+);
+@use '@oardi/css-utils';
+```
+
+This generates `.letter-spacing-label` and `--letter-spacing-label: 2px`. Alternatively, override an existing token where needed, for example `--letter-spacing-wide: 2px` on a specific element. Review tracking at small and large font sizes when adopting the relative defaults.
+
+## Upgrade checks
+
+- Search application markup and generated class names for `lh-` and `letter-space-` utilities.
+- Search styles and inline overrides for the removed size-based `--line-height-*` tokens.
+- Rename old `lineHeights` Sass keys and replace direct uses of `$line-height-effect-names` and the `text` module's `$letterSpacings` list.
+- Compile your application's SCSS and check typography, Range Slider, Stepper and Skeleton views with your theme overrides.
+
+The package's `css-utils-manifest.json` and `css-utils-reference.md` record the removed utility families with `removedIn: 1.0.0` and their replacements. All other public entry points keep their existing paths; the package continues to ship SCSS without a JavaScript runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oardi/css-utils",
-	"version": "0.134.0",
+	"version": "1.0.0",
 	"author": "Ardian Shala",
 	"homepage": "https://css-utils.oardi.com",
 	"description": "Powerful set of semantic css classes with support for breakpoints, directions and spacings",
@@ -38,6 +38,7 @@
 		"scss",
 		"css-utils-reference.md",
 		"css-utils-manifest.json",
+		"migration-v1.md",
 		"LICENSE.md"
 	],
 	"license": "MIT",

package/readme.md

@@ -162,6 +162,7 @@ Component tokens can be changed locally without affecting the rest of the interf
 
 ## Learn more
 
+- [Migration from 0.x to 1.0.0](migration-v1.md)
 - [Full documentation and showcase](https://css-utils.oardi.com/)
 - [Get-started guide](https://css-utils.oardi.com/get-started)
 - [Utilities, components and design tokens](https://css-utils.oardi.com/utilities/core-concepts)

package/scss/components/combobox.scss

@@ -0,0 +1,84 @@
+@use '../layers.scss';
+
+@layer components {
+	.combobox {
+		--combobox-max-height: 16rem;
+		--combobox-available-height: calc(100vh - 1rem);
+		--combobox-padding: var(--spacer-1);
+		--combobox-bg-color: var(--bg-surface);
+		--combobox-color: var(--text-color);
+		--combobox-border-color: var(--border-color);
+		--combobox-border-radius: var(--border-radius);
+		--combobox-box-shadow: var(--shadow-lg);
+		--combobox-active-bg-color: var(--bg-surface-hover);
+		--combobox-selected-color: var(--action-color);
+		--combobox-z-index: var(--z-index-tooltip);
+	}
+
+	.combobox-panel {
+		position: fixed;
+		z-index: var(--combobox-z-index);
+		inset: auto;
+		box-sizing: border-box;
+		max-block-size: min(var(--combobox-max-height), var(--combobox-available-height));
+		margin: 0;
+		padding: var(--combobox-padding);
+		border: var(--border-width) solid var(--combobox-border-color);
+		border-radius: var(--combobox-border-radius);
+		background: var(--combobox-bg-color);
+		color: var(--combobox-color);
+		box-shadow: var(--combobox-box-shadow);
+		overflow: auto;
+		overscroll-behavior: contain;
+
+		&[hidden] {
+			display: none;
+		}
+	}
+
+	.combobox-option,
+	.combobox-empty {
+		padding: var(--spacer-2) var(--spacer-3);
+		overflow-wrap: anywhere;
+	}
+
+	.combobox-option {
+		border-radius: var(--border-radius-sm);
+		cursor: pointer;
+
+		&[data-combobox-active],
+		&:hover {
+			background: var(--combobox-active-bg-color);
+		}
+
+		&[aria-selected='true'] {
+			color: var(--combobox-selected-color);
+			font-weight: 600;
+		}
+		&[aria-disabled='true'] {
+			color: var(--disabled-text-color);
+			background: transparent;
+			cursor: not-allowed;
+		}
+	}
+
+	.combobox-empty {
+		color: var(--text-muted);
+	}
+
+	@media (forced-colors: active) {
+		.combobox-panel {
+			border-color: CanvasText;
+		}
+		.combobox-option[data-combobox-active] {
+			outline: 2px solid Highlight;
+			outline-offset: -2px;
+		}
+		.combobox-option[aria-selected='true'] {
+			color: LinkText;
+		}
+		.combobox-option[aria-disabled='true'] {
+			color: GrayText;
+		}
+	}
+}

package/scss/components/range-slider.scss

@@ -179,7 +179,7 @@
 		color: var(--range-slider-marker-color);
 		font-size: var(--font-size-sm);
 		font-variant-numeric: tabular-nums;
-		line-height: var(--line-height-sm);
+		line-height: var(--line-height-tight);
 	}
 
 	@media (forced-colors: active) {

package/scss/components/skeleton.scss

@@ -6,7 +6,7 @@
 		--skeleton-height: 1rem;
 		--skeleton-size: 2.5rem;
 		--skeleton-font-size: var(--font-size);
-		--skeleton-line-height: var(--line-height-sm);
+		--skeleton-line-height: var(--line-height-tight);
 		--skeleton-control-height: 2.5rem;
 		--skeleton-aspect-ratio: auto;
 		--skeleton-border-radius: var(--border-radius-sm);

package/scss/components/stepper.scss

@@ -100,7 +100,7 @@
 		display: block;
 		color: var(--stepper-color);
 		font-weight: 700;
-		line-height: var(--line-height-sm);
+		line-height: var(--line-height-tight);
 		text-decoration-thickness: 0.08em;
 		text-underline-offset: 0.18em;
 	}
@@ -110,7 +110,7 @@
 		margin-block-start: var(--spacer-1);
 		color: var(--stepper-muted-color);
 		font-size: var(--font-size-sm);
-		line-height: var(--line-height-sm);
+		line-height: var(--line-height-tight);
 	}
 
 	.stepper-item.is-completed {

package/scss/index.scss

@@ -46,6 +46,7 @@
 @forward './components/overlay.scss';
 @forward './components/pagination.scss';
 @forward './components/popover.scss';
+@forward './components/combobox.scss';
 @forward './components/progress.scss';
 @forward './components/range-slider.scss';
 @forward './components/segmented-control.scss';

package/scss/text.scss

@@ -2,9 +2,6 @@
 @use './layers.scss';
 @use './theme.scss' as theme;
 
-// Deprecated: retained for the existing pixel-based utilities.
-$letterSpacings: 0, 1, 2, 3, 4, 5;
-
 @layer utilities {
 	.text-center {
 		text-align: center;
@@ -97,29 +94,15 @@ $letterSpacings: 0, 1, 2, 3, 4, 5;
 		}
 	}
 
-	// Deprecated: use .line-height-* utilities instead.
 	@each $name, $value in map.get(theme.$theme, lineHeights) {
-		.lh-#{$name} {
+		.line-height-#{$name} {
 			line-height: var(--line-height-#{$name});
 		}
 	}
 
-	@each $effect, $legacy-name in theme.$line-height-effect-names {
-		.line-height-#{$effect} {
-			line-height: var(--line-height-#{$effect});
-		}
-	}
-
 	@each $name, $value in map.get(theme.$theme, letterSpacings) {
 		.letter-spacing-#{$name} {
 			letter-spacing: var(--letter-spacing-#{$name});
 		}
 	}
-
-	// Deprecated: use .letter-spacing-* utilities instead.
-	@each $letterSpacing in $letterSpacings {
-		.letter-space-#{$letterSpacing} {
-			letter-spacing: #{$letterSpacing}px;
-		}
-	}
 }

package/scss/theme.scss

@@ -169,24 +169,13 @@ $-breakpoints: (
 );
 
 $-line-heights: (
-	xs: 1,
-	sm: 1.125,
-	md: 1.25,
-	lg: 1.5,
-	xl: 1.75,
-	xxl: 2,
-	xxxl: 2.5,
-);
-
-// Map the public effect names to the existing Sass scale during the compatibility period.
-$line-height-effect-names: (
-	none: xs,
-	tight: sm,
-	snug: md,
-	normal: lg,
-	relaxed: xl,
-	loose: xxl,
-	extra-loose: xxxl,
+	none: 1,
+	tight: 1.125,
+	snug: 1.25,
+	normal: 1.5,
+	relaxed: 1.75,
+	loose: 2,
+	extra-loose: 2.5,
 );
 
 $-letter-spacings: (

package/scss/variables.scss

@@ -32,11 +32,6 @@
 		}
 
 		--line-height: 1.8;
-		@each $effect, $legacy-name in theme.$line-height-effect-names {
-			--line-height-#{$effect}: #{map.get(map.get(theme.$theme, lineHeights), $legacy-name)};
-		}
-
-		// Deprecated: retained for existing .lh-* utilities and component tokens.
 		@each $name, $value in map.get(theme.$theme, lineHeights) {
 			--line-height-#{$name}: #{$value};
 		}