shelving 1.244.0 → 1.244.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.244.0",
+	"version": "1.244.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/schema/ColorSchema.d.ts

@@ -4,7 +4,7 @@ import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
  *
  * @see https://dhoulb.github.io/shelving/schema/ColorSchema/ColorSchemaOptions
  */
-export interface ColorSchemaOptions extends Omit<StringSchemaOptions, "type" | "min" | "max" | "match" | "rows"> {
+export interface ColorSchemaOptions extends Omit<StringSchemaOptions, "min" | "match" | "rows"> {
 }
 /**
  * Schema that defines a valid color hex string, e.g. `#00CCFF`
@@ -19,12 +19,14 @@ export declare class ColorSchema extends StringSchema {
     /**
      * Create a new `ColorSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for hex colors).
+     * @param options Options for the schema (inherits `StringSchema` options except `min`, `match`, and `rows`, which are fixed for hex colors).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"color"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Color"`).
      * @param options.value Default hex value used when the input is `undefined` (defaults to `"#000000"`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"color"`).
+     * @param options.max Maximum allowed character length (defaults to `7`).
      */
-    constructor({ one, title, value, ...options }: ColorSchemaOptions);
+    constructor({ one, title, value, input, max, ...options }: ColorSchemaOptions);
     /**
      * Sanitize the string into a `#RRGGBB` hex color.
      *

package/schema/ColorSchema.js

@@ -15,20 +15,22 @@ export class ColorSchema extends StringSchema {
     /**
      * Create a new `ColorSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for hex colors).
+     * @param options Options for the schema (inherits `StringSchema` options except `min`, `match`, and `rows`, which are fixed for hex colors).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"color"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Color"`).
      * @param options.value Default hex value used when the input is `undefined` (defaults to `"#000000"`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"color"`).
+     * @param options.max Maximum allowed character length (defaults to `7`).
      */
-    constructor({ one = "color", title = "Color", value = "#000000", ...options }) {
+    constructor({ one = "color", title = "Color", value = "#000000", input = "color", max = 7, ...options }) {
         super({
             one,
             title,
             value,
             ...options,
-            input: "color",
+            input,
+            max,
             min: 1,
-            max: 7,
             rows: 1,
             match: COLOR_REGEXP,
         });

package/schema/CurrencyCodeSchema.d.ts

@@ -9,7 +9,7 @@ import { StringSchema } from "./StringSchema.js";
  *
  * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchemaOptions
  */
-export interface CurrencyCodeSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "rows"> {
+export interface CurrencyCodeSchemaOptions extends Omit<StringSchemaOptions, "min" | "match" | "rows"> {
     currencies?: ImmutableArray<CurrencyCode>;
 }
 /**
@@ -32,11 +32,11 @@ export declare class CurrencyCodeSchema extends StringSchema {
     /**
      * Create a new `CurrencyCodeSchema`.
      *
-     * @param options Options for the schema (`currencies`, plus base `StringSchemaOptions` except `input`/`min`/`max`/`match`/`rows`).
+     * @param options Options for the schema (`currencies`, plus base `StringSchemaOptions` except `min`/`match`/`rows`).
      * @example new CurrencyCodeSchema({ currencies: ["GBP", "USD"] })
      * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema
      */
-    constructor({ one, title, currencies, ...options }: CurrencyCodeSchemaOptions);
+    constructor({ one, title, currencies, max, ...options }: CurrencyCodeSchemaOptions);
     /**
      * Sanitize an input string down to uppercase `A-Z` letters.
      *

package/schema/CurrencyCodeSchema.js

@@ -21,17 +21,17 @@ export class CurrencyCodeSchema extends StringSchema {
     /**
      * Create a new `CurrencyCodeSchema`.
      *
-     * @param options Options for the schema (`currencies`, plus base `StringSchemaOptions` except `input`/`min`/`max`/`match`/`rows`).
+     * @param options Options for the schema (`currencies`, plus base `StringSchemaOptions` except `min`/`match`/`rows`).
      * @example new CurrencyCodeSchema({ currencies: ["GBP", "USD"] })
      * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema
      */
-    constructor({ one = "currency", title = "Currency", currencies = CURRENCY_CODES, ...options }) {
+    constructor({ one = "currency", title = "Currency", currencies = CURRENCY_CODES, max = 3, ...options }) {
         super({
             one,
             title,
             ...options,
+            max, // Valid currency code is 3 uppercase letters.
             min: 3,
-            max: 3, // Valid currency code is 3 uppercase letters.
             rows: 1,
             case: "upper",
             match: /^[A-Z]{3}$/, // Valid currency code is 3 uppercase letters.

package/schema/EmailSchema.d.ts

@@ -1,5 +1,12 @@
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
+/**
+ * Options for an `EmailSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/EmailSchema/EmailSchemaOptions
+ */
+export interface EmailSchemaOptions extends Omit<StringSchemaOptions, "min" | "match" | "rows"> {
+}
 /**
  * Schema that defines a valid email address.
  *
@@ -24,11 +31,13 @@ export declare class EmailSchema extends StringSchema {
     /**
      * Create a new `EmailSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for emails).
+     * @param options Options for the schema (inherits `StringSchema` options except `min`, `match`, and `rows`, which are fixed for emails).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"email address"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Email"`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"email"`).
+     * @param options.max Maximum allowed character length (defaults to `254`).
      */
-    constructor({ one, title, ...options }: Omit<StringSchemaOptions, "type" | "min" | "max" | "match" | "rows">);
+    constructor({ one, title, input, max, ...options }: EmailSchemaOptions);
     /**
      * Sanitize the string into a valid email address.
      *

package/schema/EmailSchema.js

@@ -26,18 +26,20 @@ export class EmailSchema extends StringSchema {
     /**
      * Create a new `EmailSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for emails).
+     * @param options Options for the schema (inherits `StringSchema` options except `min`, `match`, and `rows`, which are fixed for emails).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"email address"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Email"`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"email"`).
+     * @param options.max Maximum allowed character length (defaults to `254`).
      */
-    constructor({ one = "email address", title = "Email", ...options }) {
+    constructor({ one = "email address", title = "Email", input = "email", max = 254, ...options }) {
         super({
             one,
             title,
             ...options,
-            input: "email",
+            input,
+            max,
             min: 1,
-            max: 254,
             rows: 1,
             match: R_MATCH,
         });

package/schema/PasswordSchema.d.ts

@@ -1,15 +1,8 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
-/**
- * Options for a `PasswordSchema`.
- *
- * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PasswordSchemaOptions
- */
-export interface PasswordSchemaOptions extends Omit<StringSchemaOptions, "input"> {
-}
 /**
  * Schema that defines a valid password string.
  *
- * - Forces the `<input />` hint to `"password"` for downstream UIs.
+ * - Defaults the `<input />` hint to `"password"`, but a caller can override it (e.g. `"text"` for a show-password toggle).
  * - Never formats the value for display (`format()` always returns `""`).
  *
  * @example new PasswordSchema({}).validate("hunter2"); // Returns "hunter2"
@@ -19,12 +12,13 @@ export declare class PasswordSchema extends StringSchema {
     /**
      * Create a new `PasswordSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `input`, which is fixed to `"password"`).
+     * @param options Options for the schema (inherits all `StringSchema` options).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"password"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Password"`).
      * @param options.min Minimum allowed character length (defaults to `6`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"password"`).
      */
-    constructor({ one, title, min, ...options }?: PasswordSchemaOptions);
+    constructor({ one, title, min, input, ...options }?: StringSchemaOptions);
     /**
      * Format a password value for display (always returns `""`).
      *
@@ -37,9 +31,9 @@ export declare class PasswordSchema extends StringSchema {
     format(): string;
 }
 /**
- * Sugar instance of [`StringSchema`](/schema/StringSchema) for a password string. Equivalent to `new StringSchema({})`.
+ * Sugar instance of [`PasswordSchema`](/schema/PasswordSchema) for a password string. Equivalent to `new PasswordSchema({})`.
  *
  * @example PASSWORD.validate("hunter2"); // Returns "hunter2"
  * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PASSWORD
  */
-export declare const PASSWORD: StringSchema;
+export declare const PASSWORD: PasswordSchema;

package/schema/PasswordSchema.js

@@ -2,7 +2,7 @@ import { StringSchema } from "./StringSchema.js";
 /**
  * Schema that defines a valid password string.
  *
- * - Forces the `<input />` hint to `"password"` for downstream UIs.
+ * - Defaults the `<input />` hint to `"password"`, but a caller can override it (e.g. `"text"` for a show-password toggle).
  * - Never formats the value for display (`format()` always returns `""`).
  *
  * @example new PasswordSchema({}).validate("hunter2"); // Returns "hunter2"
@@ -12,13 +12,14 @@ export class PasswordSchema extends StringSchema {
     /**
      * Create a new `PasswordSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `input`, which is fixed to `"password"`).
+     * @param options Options for the schema (inherits all `StringSchema` options).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"password"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Password"`).
      * @param options.min Minimum allowed character length (defaults to `6`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"password"`).
      */
-    constructor({ one = "password", title = "Password", min = 6, ...options } = {}) {
-        super({ one, title, min, ...options, input: "password" });
+    constructor({ one = "password", title = "Password", min = 6, input = "password", ...options } = {}) {
+        super({ one, title, min, input, ...options });
     }
     /**
      * Format a password value for display (always returns `""`).
@@ -34,9 +35,9 @@ export class PasswordSchema extends StringSchema {
     }
 }
 /**
- * Sugar instance of [`StringSchema`](/schema/StringSchema) for a password string. Equivalent to `new StringSchema({})`.
+ * Sugar instance of [`PasswordSchema`](/schema/PasswordSchema) for a password string. Equivalent to `new PasswordSchema({})`.
  *
  * @example PASSWORD.validate("hunter2"); // Returns "hunter2"
  * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PASSWORD
  */
-export const PASSWORD = new StringSchema({});
+export const PASSWORD = new PasswordSchema({});

package/schema/PhoneSchema.d.ts

@@ -5,7 +5,7 @@ import { StringSchema } from "./StringSchema.js";
  *
  * @see https://dhoulb.github.io/shelving/schema/PhoneSchema/PhoneSchemaOptions
  */
-export interface PhoneSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "rows"> {
+export interface PhoneSchemaOptions extends Omit<StringSchemaOptions, "min" | "match" | "rows"> {
 }
 /**
  * Schema that defines a valid phone number.
@@ -20,11 +20,13 @@ export declare class PhoneSchema extends StringSchema {
     /**
      * Create a new `PhoneSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `input`, `min`, `max`, `match`, and `rows`, which are fixed for phone numbers).
+     * @param options Options for the schema (inherits `StringSchema` options except `min`, `match`, and `rows`, which are fixed for phone numbers).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"phone number"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Phone"`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"tel"`).
+     * @param options.max Maximum allowed character length (defaults to `16`).
      */
-    constructor({ one, title, ...options }: PhoneSchemaOptions);
+    constructor({ one, title, input, max, ...options }: PhoneSchemaOptions);
     /**
      * Sanitize the string into a valid E.164 phone number.
      *

package/schema/PhoneSchema.js

@@ -13,19 +13,21 @@ export class PhoneSchema extends StringSchema {
     /**
      * Create a new `PhoneSchema`.
      *
-     * @param options Options for the schema (inherits `StringSchema` options except `input`, `min`, `max`, `match`, and `rows`, which are fixed for phone numbers).
+     * @param options Options for the schema (inherits `StringSchema` options except `min`, `match`, and `rows`, which are fixed for phone numbers).
      * @param options.one Singular noun describing one value, used in error messages (defaults to `"phone number"`).
      * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Phone"`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"tel"`).
+     * @param options.max Maximum allowed character length (defaults to `16`).
      */
-    constructor({ one = "phone number", title = "Phone", ...options }) {
+    constructor({ one = "phone number", title = "Phone", input = "tel", max = 16, ...options }) {
         super({
             one,
             title,
             ...options,
-            input: "tel",
-            min: 1,
+            input,
             // Valid phone number is 16 digits or fewer (15 numerals with a leading `+` plus).
-            max: 16,
+            max,
+            min: 1,
             rows: 1,
             // Valid phone number is max 16 digits made up of:
             // - Country code (`+` plus character and 1-3 digits, e.g. `+44` or `+1`).

package/schema/SlugSchema.d.ts

@@ -1,4 +1,11 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
+/**
+ * Options for a `SlugSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/SlugSchema/SlugSchemaOptions
+ */
+export interface SlugSchemaOptions extends Omit<StringSchemaOptions, "min" | "rows"> {
+}
 /**
  * Schema that defines a valid slug, e.g. `this-is-a-slug`.
  *
@@ -17,7 +24,7 @@ export declare class SlugSchema extends StringSchema {
      *
      * @param options Options for the schema (inherited string options like `one`, `title`, `value`).
      */
-    constructor(options: Omit<StringSchemaOptions, "min" | "max" | "rows">);
+    constructor({ max, ...options }: SlugSchemaOptions);
     /**
      * Sanitize a string before validation by converting it into a slug.
      *

package/schema/SlugSchema.js

@@ -19,11 +19,11 @@ export class SlugSchema extends StringSchema {
      *
      * @param options Options for the schema (inherited string options like `one`, `title`, `value`).
      */
-    constructor(options) {
+    constructor({ max = 32, ...options }) {
         super({
             ...options,
+            max,
             min: 1,
-            max: 32,
             rows: 1,
         });
     }

package/schema/URISchema.d.ts

@@ -8,7 +8,7 @@ import { StringSchema } from "./StringSchema.js";
  *
  * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchemaOptions
  */
-export interface URISchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "rows"> {
+export interface URISchemaOptions extends Omit<StringSchemaOptions, "min" | "rows"> {
     readonly schemes?: URISchemes | undefined;
 }
 /**
@@ -28,9 +28,11 @@ export declare class URISchema extends StringSchema {
     /**
      * Create a new `URISchema`.
      *
-     * @param options Options for the schema (`schemes`, plus inherited string options like `one`, `title`, `value`).
+     * @param options Options for the schema (`schemes`, plus inherited string options like `one`, `title`, `value`, `input`, `max`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"url"`).
+     * @param options.max Maximum allowed character length (defaults to `512`).
      */
-    constructor({ one, title, schemes, ...options }: URISchemaOptions);
+    constructor({ one, title, schemes, input, max, ...options }: URISchemaOptions);
     /**
      * Validate an unknown input value and return a normalised absolute URI string.
      *

package/schema/URISchema.js

@@ -20,16 +20,18 @@ export class URISchema extends StringSchema {
     /**
      * Create a new `URISchema`.
      *
-     * @param options Options for the schema (`schemes`, plus inherited string options like `one`, `title`, `value`).
+     * @param options Options for the schema (`schemes`, plus inherited string options like `one`, `title`, `value`, `input`, `max`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"url"`).
+     * @param options.max Maximum allowed character length (defaults to `512`).
      */
-    constructor({ one = "URI", title = "URI", schemes = HTTP_SCHEMES, ...options }) {
+    constructor({ one = "URI", title = "URI", schemes = HTTP_SCHEMES, input = "url", max = 512, ...options }) {
         super({
             one,
             title,
             ...options,
-            input: "url",
+            input,
+            max,
             min: 1,
-            max: 512,
             rows: 1,
         });
         this.schemes = schemes;

package/schema/URLSchema.d.ts

@@ -10,7 +10,7 @@ import { StringSchema } from "./StringSchema.js";
  *
  * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchemaOptions
  */
-export interface URLSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "rows"> {
+export interface URLSchemaOptions extends Omit<StringSchemaOptions, "min" | "rows"> {
     readonly base?: URL | URLString | undefined;
     readonly schemes?: URISchemes | undefined;
 }
@@ -33,9 +33,11 @@ export declare class URLSchema extends StringSchema {
     /**
      * Create a new `URLSchema`.
      *
-     * @param options Options for the schema (`base`, `schemes`, plus inherited string options like `one`, `title`, `value`).
+     * @param options Options for the schema (`base`, `schemes`, plus inherited string options like `one`, `title`, `value`, `input`, `max`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"url"`).
+     * @param options.max Maximum allowed character length (defaults to `512`).
      */
-    constructor({ one, title, base, schemes, ...options }: URLSchemaOptions);
+    constructor({ one, title, base, schemes, input, max, ...options }: URLSchemaOptions);
     /**
      * Validate an unknown input value and return a normalised absolute URL string.
      *

package/schema/URLSchema.js

@@ -23,16 +23,18 @@ export class URLSchema extends StringSchema {
     /**
      * Create a new `URLSchema`.
      *
-     * @param options Options for the schema (`base`, `schemes`, plus inherited string options like `one`, `title`, `value`).
+     * @param options Options for the schema (`base`, `schemes`, plus inherited string options like `one`, `title`, `value`, `input`, `max`).
+     * @param options.input HTML `<input />` `type=""` hint (defaults to `"url"`).
+     * @param options.max Maximum allowed character length (defaults to `512`).
      */
-    constructor({ one = "URL", title = "URL", base, schemes = HTTP_SCHEMES, ...options }) {
+    constructor({ one = "URL", title = "URL", base, schemes = HTTP_SCHEMES, input = "url", max = 512, ...options }) {
         super({
             one,
             title,
             ...options,
-            input: "url",
+            input,
+            max,
             min: 1,
-            max: 512,
             rows: 1,
         });
         this.base = getURL(base)?.href;

package/schema/UUIDSchema.d.ts

@@ -1,4 +1,11 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
+/**
+ * Options for a `UUIDSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUIDSchemaOptions
+ */
+export interface UUIDSchemaOptions extends Omit<StringSchemaOptions, "min" | "match" | "rows"> {
+}
 /**
  * Schema that defines a valid UUID string (versions 1-5). Defaults to any-version validation.
  *
@@ -14,9 +21,10 @@ export declare class UUIDSchema extends StringSchema {
     /**
      * Create a new `UUIDSchema`.
      *
-     * @param options Options for the schema (inherited string options like `one`, `title`, `value`).
+     * @param options Options for the schema (inherited string options like `one`, `title`, `value`, `input`, `max`).
+     * @param options.max Maximum allowed character length (defaults to `36`).
      */
-    constructor({ one, title, ...rest }?: Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "rows">);
+    constructor({ one, title, max, ...rest }?: UUIDSchemaOptions);
     /**
      * Sanitize a string before validation by normalising it into a canonical UUID.
      *

package/schema/UUIDSchema.js

@@ -16,15 +16,16 @@ export class UUIDSchema extends StringSchema {
     /**
      * Create a new `UUIDSchema`.
      *
-     * @param options Options for the schema (inherited string options like `one`, `title`, `value`).
+     * @param options Options for the schema (inherited string options like `one`, `title`, `value`, `input`, `max`).
+     * @param options.max Maximum allowed character length (defaults to `36`).
      */
-    constructor({ one = "UUID", title = "UUID", ...rest } = {}) {
+    constructor({ one = "UUID", title = "UUID", max = 36, ...rest } = {}) {
         super({
             one,
             title,
             ...rest,
+            max, // 36 chars including hyphens (which get stripped by sanitize for appearances).
             min: 32,
-            max: 36, // 36 chars including hyphens (which get stripped by sanitize for appearances).
             rows: 1,
         });
     }