shelving 1.30.4 → 1.31.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.30.4",
+	"version": "1.31.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/schema/NumberSchema.js

@@ -1,4 +1,4 @@
-import { toNumber, roundNumber } from "../util/index.js";
+import { toNumber, roundStep } from "../util/index.js";
 import { InvalidFeedback } from "../feedback/index.js";
 import { Schema } from "./Schema.js";
 import { OPTIONAL } from "./OptionalSchema.js";
@@ -15,7 +15,7 @@ export class NumberSchema extends Schema {
         const unsafeNumber = toNumber(unsafeValue);
         if (typeof unsafeNumber !== "number")
             throw new InvalidFeedback("Must be number", { value: unsafeValue });
-        const safeNumber = typeof this.step === "number" ? roundNumber(unsafeNumber, this.step) : unsafeNumber;
+        const safeNumber = typeof this.step === "number" ? roundStep(unsafeNumber, this.step) : unsafeNumber;
         if (typeof this.max === "number" && safeNumber > this.max)
             throw new InvalidFeedback(`Maximum ${this.max}`, { value: safeNumber });
         if (typeof this.min === "number" && safeNumber < this.min)

package/util/assert.d.ts

@@ -29,6 +29,10 @@ export declare function assertArray<T extends ImmutableArray>(value: T | unknown
 export declare function assertLength<T extends {
     length: number;
 }>(value: T | unknown, min: number, max?: number): asserts value is T;
+/** Assert that a value is a number greater than. */
+export declare function assertGreater(value: number | unknown, target: number): asserts value is number;
+/** Assert that a value is a number less than. */
+export declare function assertLess(value: number | unknown, target: number): asserts value is number;
 /** Assert that a value is an instance of something. */
 export declare function assertInstance<T>(value: T | unknown, type: Class<T>): asserts value is T;
 /** Assert that a value is a function. */

package/util/assert.js

@@ -58,6 +58,16 @@ export function assertLength(value, min, max = min) {
     if (!isObject(value) || typeof value.length !== "number" || value.length < min || value.length > max)
         throw new AssertionError(`Must have length ${min}–${max}`, value);
 }
+/** Assert that a value is a number greater than. */
+export function assertGreater(value, target) {
+    if (typeof value !== "number" || value <= target)
+        throw new AssertionError(`Must be greater than ${target}`, value);
+}
+/** Assert that a value is a number less than. */
+export function assertLess(value, target) {
+    if (typeof value !== "number" || value >= target)
+        throw new AssertionError(`Must be less than ${target}`, value);
+}
 /** Assert that a value is an instance of something. */
 export function assertInstance(value, type) {
     if (!(value instanceof type))

package/util/color.d.ts

@@ -0,0 +1,29 @@
+/** Things that can be converted to a `Color` instance. */
+export declare type PossibleColor = Color | string;
+/** Represent a color. */
+export declare class Color {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+    constructor(r?: number | string, g?: number | string, b?: number | string, a?: number | string);
+    /** Convert this color to a six or eight digit hex color. */
+    get hex(): string;
+    /** Convert this color to an `rgb()` string. */
+    get rgb(): string;
+    /** Convert this color to an `rgba()` string. */
+    get rgba(): string;
+    /** Get the sRGB luminance of this color. */
+    get luminance(): number;
+    toString(): string;
+}
+/** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
+export declare function getColorChannel(channel: number | string): number;
+/** Convert a possible color to a `Color` instance or `null` */
+export declare function toColor(color: PossibleColor): Color | null;
+/** Convert a possible color to a `Color` instance */
+export declare function getColor(input: PossibleColor): Color;
+/** Is a color light? */
+export declare const isLight: (input: PossibleColor) => boolean;
+/** Is a color dark? */
+export declare const isDark: (input: PossibleColor) => boolean;

package/util/color.js

@@ -0,0 +1,70 @@
+import { AssertionError } from "../error/index.js";
+import { getBetween, roundNumber } from "./number.js";
+// Constants.
+const DARK = 140; // Anything with a luminance > 140 is considered light.
+const MIN = 0; // Maximum value of a channel.
+const MAX = 255; // Maximum value of a channel.
+// Regular expressions.
+const HEX3 = /^#?([0-F])([0-F])([0-F])$/i;
+const HEX6 = /^#?([0-F]{2})([0-F]{2})([0-F]{2})([0-F]{2})?$/i;
+/** Represent a color. */
+export class Color {
+    constructor(r = 255, g = 255, b = 255, a = 255) {
+        this.r = getColorChannel(r);
+        this.g = getColorChannel(g);
+        this.b = getColorChannel(b);
+        this.a = getColorChannel(a);
+    }
+    /** Convert this color to a six or eight digit hex color. */
+    get hex() {
+        return `#${_hex(this.r)}${_hex(this.g)}${_hex(this.b)}${this.a < MAX ? _hex(this.a) : ""}`;
+    }
+    /** Convert this color to an `rgb()` string. */
+    get rgb() {
+        return `rgb(${this.r}, ${this.g}, ${this.b})`;
+    }
+    /** Convert this color to an `rgba()` string. */
+    get rgba() {
+        return `rgba(${this.r}, ${this.g}, ${this.b}, ${roundNumber(this.a / 256, 4)})`;
+    }
+    /** Get the sRGB luminance of this color. */
+    get luminance() {
+        // Green is the largest component of the luminence, etc.
+        return Math.round(0.2126 * this.r + 0.7152 * this.g + 0.0722 * this.b);
+    }
+    toString() {
+        return this.rgba;
+    }
+}
+/** Convert number channel to a hex string (results will be unpredictable if number is outside 0-MAX). */
+const _hex = (channel) => channel.toString(16).padStart(2, "00");
+/** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
+export function getColorChannel(channel) {
+    const num = typeof channel === "string" ? parseInt(channel.padStart(2, "00"), 16) : Math.round(channel);
+    if (Number.isFinite(num))
+        return getBetween(num, MIN, MAX);
+    throw new AssertionError("Invalid color channel", channel);
+}
+/** Convert a possible color to a `Color` instance or `null` */
+export function toColor(color) {
+    if (color instanceof Color)
+        return color;
+    const hex3 = color.match(HEX3);
+    if (hex3)
+        return new Color(hex3[1], hex3[2], hex3[3]);
+    const hex6 = color.match(HEX6);
+    if (hex6)
+        return new Color(hex6[1], hex6[2], hex6[3], hex6[4]);
+    return null;
+}
+/** Convert a possible color to a `Color` instance */
+export function getColor(input) {
+    const color = toColor(input);
+    if (color)
+        return color;
+    throw new AssertionError("Invalid color", color);
+}
+/** Is a color light? */
+export const isLight = (input) => getColor(input).luminance > DARK;
+/** Is a color dark? */
+export const isDark = (input) => getColor(input).luminance <= DARK;

package/util/index.d.ts

@@ -4,6 +4,7 @@ export * from "./async.js";
 export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
+export * from "./color.js";
 export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";

package/util/index.js

@@ -4,6 +4,7 @@ export * from "./async.js";
 export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
+export * from "./color.js";
 export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";

package/util/number.d.ts

@@ -11,13 +11,6 @@ export declare const IS_NUMBER: (v: unknown) => v is number;
  * - Everything else returns `null`
  */
 export declare function toNumber(value: unknown): number | null;
-/**
- * Convert a stringy number into a number.
- *
- * @param str The string to convert.
- * @return The number, null (valid, meaning no number).
- */
-export declare const stringToNumber: (str: string) => number | null;
 /**
  * Round numbers to a given step.
  *
@@ -25,7 +18,16 @@ export declare const stringToNumber: (str: string) => number | null;
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
  * @returns The number rounded to the step.
  */
-export declare const roundNumber: (num: number, step?: number) => number;
+export declare function roundStep(num: number, step?: number): number;
+/**
+ * Round a number to a specified set of decimal places.
+ * - Doesn't include excess `0` zeroes like `num.toFixed()` and `num.toPrecision()` do.
+ *
+ * @param num The number to format.
+ * @param precision Maximum of digits shown after the decimal point (defaults to 10), with zeroes trimmed.
+ * @returns The number formatted as a string in the browser's current locale.
+ */
+export declare const roundNumber: (num: number, precision?: number) => string;
 /**
  * Format a number (based on the user's browser settings).
  * @param num The number to format.
@@ -41,3 +43,11 @@ export declare const formatNumber: (num: number, precision?: number) => string;
  * @param end The end of the range, e.g. `20`
  */
 export declare const isBetween: (num: number, start: number, end: number) => boolean;
+/**
+ *  Apply a min/max to a number to return a number that's definitely in the specified range.
+ *
+ * @param num The number to apply the min/max to, e.g. `17`
+ * @param start The start of the range, e.g. `10`
+ * @param end The end of the range, e.g. `20`
+ */
+export declare const getBetween: (num: number, start: number, end: number) => number;

package/util/number.js

@@ -12,33 +12,15 @@ export const IS_NUMBER = (v) => typeof v === "number";
  * - Everything else returns `null`
  */
 export function toNumber(value) {
-    if (typeof value === "number" && Number.isFinite(value))
-        return value;
-    if (typeof value === "string")
-        return stringToNumber(value);
-    if (value instanceof Date)
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    else if (typeof value === "string")
+        return toNumber(parseFloat(value.replace(NUMERIC, "")));
+    else if (value instanceof Date)
         return value.getTime();
     return null;
 }
-const R_NON_NUMERIC = /[^0-9]+/g; // Any non-numeric characters.
-const R_PREFIX = /^[^0-9.]*/; // Characters that come before any digits or decimal points
-/**
- * Convert a stringy number into a number.
- *
- * @param str The string to convert.
- * @return The number, null (valid, meaning no number).
- */
-export const stringToNumber = (str) => {
-    var _a;
-    if (!str)
-        return null;
-    const [a, ...b] = str.split(".");
-    const num = Number.parseFloat(`${a.replace(R_NON_NUMERIC, "")}.${b.join("").replace(R_NON_NUMERIC, "")}`);
-    if (Number.isNaN(num))
-        return null;
-    const isNeg = !((((_a = str.match(R_PREFIX)) === null || _a === void 0 ? void 0 : _a[0]) || "").split("-").length % 2);
-    return Number.isNaN(num) ? null : isNeg ? 0 - num : num;
-};
+const NUMERIC = /[^0-9-.]/g;
 /**
  * Round numbers to a given step.
  *
@@ -46,11 +28,20 @@ export const stringToNumber = (str) => {
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
  * @returns The number rounded to the step.
  */
-export const roundNumber = (num, step = 1) => {
+export function roundStep(num, step = 1) {
     if (step < 0.00001)
-        throw new AssertionError("roundNumber() does not work accurately with steps smaller than 0.00001", step);
+        throw new AssertionError("roundToStep() does not work accurately with steps smaller than 0.00001", step);
     return Math.round(num / step) * step;
-};
+}
+/**
+ * Round a number to a specified set of decimal places.
+ * - Doesn't include excess `0` zeroes like `num.toFixed()` and `num.toPrecision()` do.
+ *
+ * @param num The number to format.
+ * @param precision Maximum of digits shown after the decimal point (defaults to 10), with zeroes trimmed.
+ * @returns The number formatted as a string in the browser's current locale.
+ */
+export const roundNumber = (num, precision = 10) => new Intl.NumberFormat("en-US", { maximumFractionDigits: precision }).format(num);
 /**
  * Format a number (based on the user's browser settings).
  * @param num The number to format.
@@ -66,3 +57,11 @@ export const formatNumber = (num, precision = 10) => new Intl.NumberFormat(undef
  * @param end The end of the range, e.g. `20`
  */
 export const isBetween = (num, start, end) => num >= start && num <= end;
+/**
+ *  Apply a min/max to a number to return a number that's definitely in the specified range.
+ *
+ * @param num The number to apply the min/max to, e.g. `17`
+ * @param start The start of the range, e.g. `10`
+ * @param end The end of the range, e.g. `20`
+ */
+export const getBetween = (num, start, end) => Math.max(start, Math.min(end, num));