@uxf/styles 11.114.0 → 11.122.4

package/README.md

@@ -1,5 +1,38 @@
 # @uxf/styles
 
+Low-level, framework-agnostic styling helpers: color mixing, CSS unit conversion, responsive media-query strings, CSS-in-JS property builders, an `sr-only` style object, and shared CSS unit types.
+
+## When to use
+
+Reach for `@uxf/styles` when you need small, pure helpers that produce **CSS values or media-query strings** in TypeScript/CSS-in-JS code (used internally by `@uxf/ui` and by app styling). Every helper is a plain function or object that returns a string/number/object.
+
+It is **not** a component library and ships **no** stylesheet, global CSS, or Tailwind preset — only compiled JS and type declarations. It peer-depends on `@uxf/core` for a few utilities.
+
+## Installation
+
+```
+yarn add @uxf/styles
+```
+
+`@uxf/core` is a required **peer dependency**; `color2k` is bundled as a regular dependency. There is no CSS to import and no provider to set up.
+
+## Quick start
+
+Import from the exact subpath (there is no package-root entry — see Gotchas):
+
+```tsx
+import { rem } from "@uxf/styles/units/rem";
+import { mqMin } from "@uxf/styles/responsive/mq-min";
+
+const styles = {
+    padding: rem(16), // "1rem"
+    [`@media ${mqMin(768)}`]: {
+        // "(min-width: 48em)"
+        padding: rem(24), // "1.5rem"
+    },
+};
+```
+
 ## Color
 
 ### `shade` and `tint`
@@ -8,12 +41,13 @@
 - returns HEX string with mix of provided color and specified amount of black (`shade`) or white (`tint`)
 
 ```ts
-import { shade } from "@uxf/styles/colors/shade";
+import { shade } from "@uxf/styles/color/shade";
 
 const darker = shade("#f00", 0.1);
 ```
+
 ```ts
-import { tint } from "@uxf/styles/colors/tint";
+import { tint } from "@uxf/styles/color/tint";
 
 const lighter = tint("#f00", 0.1);
 ```
@@ -22,7 +56,8 @@ const lighter = tint("#f00", 0.1);
 
 ### `srOnly`
 
-- returns js object with CSS to hide an element to all devices except screen readers
+- a JS object (React `CSSProperties`) with CSS to hide an element from all devices except screen readers
+- apply it as an inline style / spread it — it is not a CSS class
 
 ```tsx
 import { srOnly } from "@uxf/styles/mixins/sr-only";
@@ -34,7 +69,7 @@ const example = <div style={srOnly} />;
 
 ### `columnsToPercent`
 
-- returns css `calc()` value with relative width of provided number of columns in provided total columns (defaults is `12`) compensated by optionally provided gutter in pixels
+- returns css `calc()` value with relative width of provided number of columns in provided total columns (default is `12`) compensated by an optionally provided gutter (default `0`, in pixels)
 
 ```tsx
 import { columnsToPercent } from "@uxf/styles/properties/columns-to-percent";
@@ -55,7 +90,8 @@ const example = encodedSvgUrl(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="
 
 ### `repeatGridColumns`
 
-- returns css `repeat()` value of provided number of columns and size
+- returns css `repeat()` value of provided number of columns and size (default `"1fr"`)
+- returns `null` when `count` is falsy
 
 ```tsx
 import { repeatGridColumns } from "@uxf/styles/properties/repeat-grid-columns";
@@ -66,133 +102,162 @@ const example = repeatGridColumns(6, "1fr"); /* returns "repeat(6, 1fr)" */
 ### `transition`
 
 - returns css `transition` property for specified property or an array of properties
+- accepts a `keyof CSSProperties` value (or array); defaults: `duration = 400` (ms), `easing = "ease-in-out"`
 
 ```tsx
 import { transition } from "@uxf/styles/properties/transition";
 
 const example = transition(["color", "transform"], 400, "ease-in-out");
-/* returns "color 400ms ease-in-out, transform 400 ease-in-out" */
+/* returns "color 400ms ease-in-out, transform 400ms ease-in-out" */
 ```
 
 ## Responsive
 
-### string media queries `mqBetween`, `mqHiDpi`, `mqMax`, `mqMin`
+### string media queries: `mqBetween`, `mqHiDpi`, `mqMax`, `mqMin`
 
 ```tsx
 import { mqBetween } from "@uxf/styles/responsive/mq-between";
 
-const example = mqBetween(320, 480)
-/* returns "(min-width: 20em and (max-width: 29.9375em)" */
+const example = mqBetween(320, 480);
+/* returns "(min-width: 20em) and (max-width: 29.9375em)" */
 ```
+
 ```tsx
 import { mqHiDpi } from "@uxf/styles/responsive/mq-hidpi";
 
-const example = mqHiDpi(3)
-/* returns hidpi media query string for DPR 3.0 */
+const example = mqHiDpi(3);
+/* returns hidpi media query string for DPR 3.0 (default ratio is 2) */
 ```
 
-### `window.matchMedia().matches` media queries `matchBetween`, `matchHiDpi`, `matchMax`, `matchMin`
+### `window.matchMedia().matches` media queries: `matchBetween`, `matchHidpi`, `matchMax`, `matchMin`
+
+- each returns a boolean; on the server (no `window`) they return `false`
 
 ```tsx
 import { matchBetween } from "@uxf/styles/responsive/match-between";
 
-const example = matchBetween(320, 480) /* returns boolean */
+const example = matchBetween(320, 480); /* returns boolean */
 ```
+
 ```tsx
-import { matchHiDpi } from "@uxf/styles/responsive/match-hidpi";
+import { matchHidpi } from "@uxf/styles/responsive/match-hidpi";
 
-const example = matchHiDpi(3) /* returns boolean */
+const example = matchHidpi(3); /* returns boolean */
 ```
 
 ## Units
 
 ### `em` and `rem`
 
-- returns string values divided by specified amount (defaults `16`)
+- returns string value divided by specified base (default `16`); `0` returns the string `"0"`
 
 ```tsx
 import { em } from "@uxf/styles/units/em";
 
-const example1 = em(320) /* returns "20em" */
-const example2 = em(320, 10) /* returns "32em" */
+const example1 = em(320); /* returns "20em" */
+const example2 = em(320, 10); /* returns "32em" */
 ```
+
 ```tsx
 import { rem } from "@uxf/styles/units/rem";
 
-const example1 = rem(320) /* returns "20rem" */
-const example2 = rem(320, 10) /* returns "32rem" */
+const example1 = rem(320); /* returns "20rem" */
+const example2 = rem(320, 10); /* returns "32rem" */
 ```
 
 ### `emToPx` and `remToPx`
 
-- parse em or rem units to pixels (always returns `number`) by specified base (defaults `16`)
+- parse em or rem units to pixels (always returns `number`) by specified base (default `16`)
 - the string `"0"` is also accepted and returns `0`
-- throws an error for any other invalid input (previously returned the input as-is)
+- throws an error for any other invalid input
 
 ```tsx
 import { emToPx } from "@uxf/styles/units/em-to-px";
 
-const example1 = emToPx("20em")    /* 320 */
-const example2 = emToPx("20em", 10) /* 200 */
-const example3 = emToPx("0")       /* 0 */
+const example1 = emToPx("20em"); /* 320 */
+const example2 = emToPx("20em", 10); /* 200 */
+const example3 = emToPx("0"); /* 0 */
 // emToPx("20rem") — throws error: Invalid value
 ```
+
 ```tsx
 import { remToPx } from "@uxf/styles/units/rem-to-px";
 
-const example1 = remToPx("20rem")    /* 320 */
-const example2 = remToPx("20rem", 10) /* 200 */
-const example3 = remToPx("0")        /* 0 */
+const example1 = remToPx("20rem"); /* 320 */
+const example2 = remToPx("20rem", 10); /* 200 */
+const example3 = remToPx("0"); /* 0 */
 // remToPx("20%") — throws error: Invalid value
 ```
 
 ### `formatCssValue`
 
-- returns normalized css value: pass string as string or input to rem or zero as string or optionally forced input as string
+- returns a normalized css value: numbers become `rem` (or a plain string when `0` or `forceString`), non-empty strings pass through, anything else returns `null`
 
 ```tsx
 import { formatCssValue } from "@uxf/styles/units/format-css-value";
 
-const example1 = formatCssValue(0) /* returns "0" */
-const example2 = formatCssValue(24) /* returns "1.5rem" */
-const example3 = formatCssValue("100%") /* returns "100%" */
-const example4 = formatCssValue(1, true) /* returns "1" */
+const example1 = formatCssValue(0); /* returns "0" */
+const example2 = formatCssValue(24); /* returns "1.5rem" */
+const example3 = formatCssValue("100%"); /* returns "100%" */
+const example4 = formatCssValue(1, true); /* returns "1" */
 ```
 
 ### `percent`
 
-- returns float of percentage of provided number in provided max value (defaults `100`) with provided precision (defaults `2`)
+- returns float of percentage of provided number in provided max value (default `100`) with provided precision (default `2`)
 
 ```tsx
 import { percent } from "@uxf/styles/units/percent";
 
-const example = percent(54.874, 80, 2) /* returns 68.59 */
+const example = percent(54.874, 80, 2); /* returns 68.59 */
 ```
 
 ### `spacing`
 
-> **Deprecated** — This function will be deleted in future versions.
+> **Deprecated** — this function will be deleted in future versions.
 
-- returns input multiplied by given factor (defaults `8`)
+- returns input multiplied by given factor (default `8`)
 
 ```tsx
 import { spacing } from "@uxf/styles/units/spacing";
 
-const example = spacing(4) /* returns 32 */
-
+const example = spacing(4); /* returns 32 */
 ```
+
 ### `withUnit`
 
-- returns literal of input with CSS unit
+- returns literal of input with the given CSS unit
 
 ```tsx
 import { withUnit } from "@uxf/styles/units/with-unit";
 
-const example = withUnit(80, "vh") /* returns "80vh" */
+const example = withUnit(80, "vh"); /* returns "80vh" */
 ```
 
 ## Types
 
-- typed css units
-- shared types for utils
+Shared, typed CSS units and helper types, all exported from `@uxf/styles/types`:
+
+```ts
+import type { CssUnits, TransitionProperties } from "@uxf/styles/types";
+```
 
+| Type                       | Description                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `CssTimeUnits`             | `"ms" \| "s"`                                                       |
+| `CssAbsoluteLengthsUnits`  | absolute length/angle units (`cm`, `mm`, `in`, `px`, `pt`, `pc`, `deg`, `rad`) |
+| `CssRelativeLengthsUnits`  | relative units (`em`, `ex`, `ch`, `rem`, `vw`, `vh`, `vmin`, `vmax`, `%`) |
+| `CssUnits`                 | union of all of the above (accepted by `withUnit`)                  |
+| `TransitionProperty`       | `keyof CSSProperties`                                               |
+| `TransitionProperties`     | `TransitionProperty \| TransitionProperty[]` (accepted by `transition`) |
+
+## Gotchas
+
+- **Deep imports only.** There is no package-root entry (no `index`), so a bare `import … from "@uxf/styles"` does not resolve. Always import from the exact subpath, e.g. `@uxf/styles/units/rem`.
+- **No `exports` map.** Subpaths resolve by filesystem, so a path must match the on-disk file exactly — note it is `color` (singular) and `match-hidpi`.
+- **Casing mismatch to watch.** The media-query string builder is `mqHiDpi` (capital `D`), but the boolean matcher is `matchHidpi` (lowercase `d`).
+- **Ships no CSS.** Only compiled JS/JSX and `.d.ts` files are published (see `.npmignore`); there is no stylesheet, global CSS, or Tailwind preset to import.
+- **`srOnly` is a JS object**, not a class — apply it via `style={srOnly}` or by spreading, not `className`.
+- **`match*` helpers are client-only in effect.** They read `window.matchMedia` and return `false` on the server (guarded by `@uxf/core`'s `isBrowser`), so they are SSR-safe but never `true` during server render.
+- **`emToPx` / `remToPx` throw** on any input that is not a matching `em` / `rem` string or the string `"0"`.
+- **`@uxf/core` is a required peer dependency.**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/styles",
-    "version": "11.114.0",
+    "version": "11.122.4",
     "description": "",
     "main": "index.js",
     "scripts": {