@valbuild/core 0.144.0 → 0.145.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @valbuild/core
 
+## 0.145.0
+
+### Minor Changes
+
+- [#851](https://github.com/valbuild/val/pull/851) [`b6cb939`](https://github.com/valbuild/val/commit/b6cb9395d8bdcd5182e9c6ba84f5284930de2fa5) Thanks [@freekh](https://github.com/freekh)! - New `s.int()` for whole numbers, `.step()` on `s.int()` and `s.number()`, and a slider for both:
+
+  ```ts
+  s.object({
+    columns: s.int().min(1).max(6),
+    opacity: s
+      .int()
+      .min(0)
+      .max(100)
+      .step(5)
+      .render({ as: "slider", min: 0, max: 100 }),
+    lineHeight: s.number().render({ as: "slider", min: 1, max: 2, step: 0.1 }),
+  });
+  ```
+
+  - `.min()`, `.max()` and `.step()` are rules the validator checks. A step is counted from `min`, or from 0 when there is none.
+  - `.render({ as: "slider", min, max, step? })` is how the field is edited: a slider, with a box beside it for typing an exact value. `min` and `max` are required. The slider's step defaults to the schema's `.step()`, then to 1.
+  - The slider can only produce values the schema accepts. A slider outside `.min()`/`.max()`, with a step that is not a multiple of `.step()`, or with decimals on an `s.int()` throws where the schema is defined.
+  - A value outside the slider's range is still valid content. The field says it is out of the slider's reach and offers "Set to" the nearest stop. A value that breaks a rule offers "Round to" the nearest allowed value.
+  - Fixed: `.min(0)` and `.max(0)` on `s.number()` were ignored.
+  - A new item of a number schema starts at the nearest allowed value instead of `0`, so `s.int().min(1)` starts at 1.
+
 ## 0.144.0
 
 ### Minor Changes

package/dist/declarations/src/index.d.ts

@@ -58,6 +58,8 @@ export { type SerializedObjectSchema, ObjectSchema } from "./schema/object.js";
 export { type SerializedRecordSchema, type MediaCollectionType, RecordSchema, } from "./schema/record.js";
 export { type SerializedStringSchema, StringSchema } from "./schema/string.js";
 export { type SerializedNumberSchema, NumberSchema } from "./schema/number.js";
+import { nearestAllowedNumber, isOnStep, stepOrigin } from "./schema/numberRules.js";
+export type { NumberRules } from "./schema/numberRules.js";
 export { type SerializedBooleanSchema, BooleanSchema } from "./schema/boolean.js";
 export { type SerializedImageSchema, ImageSchema } from "./schema/image.js";
 export { type SerializedFileSchema, FileSchema } from "./schema/file.js";
@@ -89,7 +91,7 @@ export { type SerializedUnionSchema, type UnionSchema, type SerializedStringUnio
 export { type SerializedLiteralSchema, LiteralSchema } from "./schema/literal.js";
 export { deserializeSchema } from "./schema/deserialize.js";
 export { type PreviewItem, type ItemPreviewInput, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";
-export { type InlineRender, type FieldRender, isInlineRender } from "./render.js";
+export { type InlineRender, type FieldRender, type SliderRender, type NumberRender, isInlineRender, } from "./render.js";
 export type { ValRouter, ExternalPageRouter, RouteValidationError, } from "./router.js";
 export { parseNextJsRoutePattern, parseTanStackRoutePattern, tanStackSegmentsOfRoutePath, validateUrlAgainstPattern, } from "./router.js";
 export { getSourcePathFromRoute, isPageRouter } from "./getSourcePathFromRoute.js";
@@ -173,6 +175,11 @@ declare const Internal: {
     rejectScheme: typeof rejectScheme;
     schemeOf: typeof schemeOf;
     UNSAFE_URL_SCHEMES: readonly ["javascript", "data", "vbscript", "file", "blob"];
+    number: {
+        nearestAllowedNumber: typeof nearestAllowedNumber;
+        isOnStep: typeof isOnStep;
+        stepOrigin: typeof stepOrigin;
+    };
     color: {
         parseColor: typeof parseColor;
         formatColor: typeof formatColor;

package/dist/declarations/src/initSchema.d.ts

@@ -1,5 +1,5 @@
 import { array } from "./schema/array.js";
-import { number } from "./schema/number.js";
+import { int, number } from "./schema/number.js";
 import { object } from "./schema/object.js";
 import { string } from "./schema/string.js";
 import { boolean } from "./schema/boolean.js";
@@ -74,6 +74,28 @@ export type InitSchema = {
      *
      */
     readonly number: typeof number;
+    /**
+     * Define a whole number. The source is an ordinary `number`; `s.int()` adds
+     * the rule that it has no decimals.
+     *
+     * Takes `.min()`, `.max()` and `.step()` for what the value may be, and
+     * `.render({ as: "slider", min, max })` to edit it with a slider.
+     *
+     * @example
+     * const schema = s.object({
+     *   columns: s.int().min(1).max(6),
+     *   opacity: s.int().min(0).max(100).step(5).render({
+     *     as: "slider",
+     *     min: 0,
+     *     max: 100,
+     *   }),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   columns: 3,
+     *   opacity: 40,
+     * });
+     */
+    readonly int: typeof int;
     /**
      * Define one of several object shapes, told apart by a tag field.
      *

package/dist/declarations/src/render.d.ts

@@ -27,11 +27,12 @@ import type { SerializedSchema } from "./schema/index.js";
  */
 /**
  * A RENDER is how a field is laid out in the editor, and it applies only when
- * you are looking at the field. It is declared by a CONTAINER about its
- * children, never by a child about itself: `s.array(item).render({ as: "inline" })`
- * and `s.record(item).render({ as: "inline" })`. The one other schema that takes
- * a render is `s.keyOf(...)`, where it means something of its own (see
- * `KeyOfSchema.render`).
+ * you are looking at the field. On a list it is declared by the CONTAINER about
+ * its children, never by a child about itself: `s.array(item).render({ as: "inline" })`
+ * and `s.record(item).render({ as: "inline" })`. Two other schemas take a
+ * render, each meaning something of its own: `s.keyOf(...)` (see
+ * `KeyOfSchema.render`) and `s.number()` / `s.int()`, whose `{ as: "slider" }`
+ * is a different input for the same value (see {@link SliderRender}).
  *
  * Why the container: inline is a property of the LIST — "my items are edited in
  * their rows" — and the item schema is the wrong place to say it. An item can be
@@ -89,6 +90,38 @@ export type InlineRender = {
  * What `.render(...)` takes, and what the serialized schema carries verbatim.
  */
 export type FieldRender = InlineRender;
+/**
+ * `{ as: "slider", min, max }` on `s.int()` or `s.number()`: the value is
+ * edited with a slider from `min` to `max`, next to a box that takes a typed
+ * value.
+ *
+ * `min` and `max` are REQUIRED, because a slider without ends is not a slider.
+ * They are the slider's own and are not validation: a value outside them is
+ * still valid content (if the schema allows it), and the field says it is out
+ * of the slider's reach and offers to bring it back. What the schema accepts is
+ * `.min()`, `.max()` and `.step()` on the schema itself.
+ *
+ * The one rule tying the two together: **the slider may only produce values
+ * the schema accepts.** So its range has to lie inside the schema's, its step
+ * has to be a multiple of the schema's step and its `min` on the schema's grid,
+ * and on `s.int()` all of them have to be whole numbers. A schema that breaks
+ * that throws where it is defined — see `NumberSchema`.
+ *
+ * `step` defaults to the schema's `.step()`, and to 1 when there is none.
+ *
+ * Unlike `inline` this is about the field itself — no list reads it, and
+ * {@link isInlineRender} answers `false` for it.
+ */
+export type SliderRender = {
+    as: "slider";
+    min: number;
+    max: number;
+    step?: number;
+};
+/**
+ * What `s.number().render(...)` and `s.int().render(...)` take.
+ */
+export type NumberRender = SliderRender;
 /**
  * Does this CONTAINER edit its items inside their list rows, rather than behind
  * clickable preview rows that navigate to them?

package/dist/declarations/src/schema/number.d.ts

@@ -1,16 +1,23 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ItemPreviewInput, PreviewItem } from "../preview.js";
+import { NumberRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-type NumberOptions = {
-    max?: number;
-    min?: number;
-};
+import { NumberRules } from "./numberRules.js";
+/**
+ * What the value has to be. `integer` is what makes a number schema an
+ * `s.int()`: the source is a number either way, so an int is a number schema
+ * with one more rule rather than a schema type of its own (which every walk
+ * over a schema would have had to learn).
+ */
+type NumberOptions = NumberRules;
 export type SerializedNumberSchema = {
     type: "number";
     /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
     preview?: true;
     options?: NumberOptions;
+    /** How the field is edited. Static config — see `render.ts`. */
+    render?: NumberRender;
     opt: boolean;
     customValidate?: boolean;
     readonly?: boolean;
@@ -25,7 +32,8 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     private readonly isHidden;
     private readonly description?;
     private readonly previewInput;
-    constructor(options?: NumberOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null);
+    private readonly renderInput;
+    constructor(options?: NumberOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, renderInput?: NumberRender | null);
     /**
      * Describe this field.
      *
@@ -86,6 +94,37 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
      * export default c.define("/example.val.ts", schema, 3);
      */
     min(min: number): NumberSchema<Src>;
+    /**
+     * Validate that the number is on a grid of `step`: one of `min`, `min + step`,
+     * `min + 2 * step` and so on, counted from 0 when there is no `.min()`.
+     *
+     * A slider rendered on this field moves in the same steps unless its render
+     * says otherwise (and then its step has to be a multiple of this one).
+     *
+     * @example
+     * const schema = s.int().min(0).max(100).step(5);
+     * export default c.define("/example.val.ts", schema, 40);
+     */
+    step(step: number): NumberSchema<Src>;
+    /**
+     * Choose how this field is edited. `{ as: "slider", min, max }` edits it with
+     * a slider from `min` to `max`, next to a box for typing an exact value.
+     *
+     * `min` and `max` are required — a slider without ends is not a slider — and
+     * they are the slider's, not validation: use `.min()` / `.max()` for what the
+     * value may be. The slider can only produce values this schema accepts, so
+     * its range must lie inside `.min()`/`.max()`, its `step` (which defaults to
+     * `.step()`, then 1) must be a multiple of `.step()`, and on `s.int()` all of
+     * them must be whole numbers. A schema that breaks this throws here.
+     *
+     * Static configuration, not a callback — see `render.ts`. A second
+     * `.render(...)` replaces the first.
+     *
+     * @example
+     * const schema = s.int().render({ as: "slider", min: 0, max: 100, step: 5 });
+     * export default c.define("/example.val.ts", schema, 40);
+     */
+    render(input: NumberRender): NumberSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
@@ -104,4 +143,5 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     protected executeSerialize(): SerializedSchema;
 }
 export declare const number: (options?: NumberOptions) => NumberSchema<number>;
+export declare const int: () => NumberSchema<number>;
 export {};

package/dist/declarations/src/schema/numberRules.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a number schema accepts, in one place, so the validator and the
+ * Studio's "Round to …" / "Set to …" buttons cannot disagree about it.
+ *
+ * A button that offers a value the validator then rejects is worse than no
+ * button, which is exactly what two copies of this arithmetic would drift into.
+ */
+export type NumberRules = {
+    min?: number;
+    max?: number;
+    /** Whole numbers only — `s.int()`. */
+    integer?: boolean;
+    /** Allowed values are `origin + n * step`, where the origin is `min` or 0. */
+    step?: number;
+};
+/** Where the step grid starts: the schema's `min`, or 0 when it has none. */
+export declare function stepOrigin(rules: NumberRules): number;
+/** Is `value` one of `origin + n * step`? */
+export declare function isOnStep(value: number, origin: number, step: number): boolean;
+/**
+ * The allowed value closest to `value`: inside `min`/`max`, on the step grid,
+ * and whole when the schema is an int.
+ *
+ * Returns `null` when the rules leave nothing to snap to — a `min` above
+ * `max`, or a range too narrow to hold a single step or a single whole number.
+ */
+export declare function nearestAllowedNumber(value: number, rules: NumberRules): number | null;