@valbuild/core 0.144.0 → 0.145.0

package/dist/{index-aa16dd90.esm.js → index-307b907e.esm.js}

@@ -10185,6 +10185,87 @@ function patchPathToModulePath(patchPath) {
   }).join(".");
 }
 
+/**
+ * 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.
+ */
+
+/**
+ * Division of decimals is not exact (`0.3 / 0.1` is `2.9999999999999996`), so a
+ * value counts as on the grid when it is within this many steps of it.
+ */
+var GRID_EPSILON = 1e-9;
+
+/** Where the step grid starts: the schema's `min`, or 0 when it has none. */
+function stepOrigin(rules) {
+  var _rules$min;
+  return (_rules$min = rules.min) !== null && _rules$min !== void 0 ? _rules$min : 0;
+}
+
+/** Is `value` one of `origin + n * step`? */
+function isOnStep(value, origin, step) {
+  var steps = (value - origin) / step;
+  return Math.abs(steps - Math.round(steps)) < GRID_EPSILON;
+}
+
+/**
+ * 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.
+ */
+function nearestAllowedNumber(value, rules) {
+  var _rules$step;
+  var step = (_rules$step = rules.step) !== null && _rules$step !== void 0 ? _rules$step : rules.integer ? 1 : undefined;
+  var lo = rules.min;
+  var hi = rules.max;
+  if (lo !== undefined && hi !== undefined && lo > hi) {
+    return null;
+  }
+  var clamp = function clamp(n) {
+    return Math.min(hi !== null && hi !== void 0 ? hi : Infinity, Math.max(lo !== null && lo !== void 0 ? lo : -Infinity, n));
+  };
+  if (step === undefined) {
+    return clamp(value);
+  }
+  var origin = rules.integer && rules.step === undefined ? 0 : stepOrigin(rules);
+  var toGrid = function toGrid(n) {
+    return roundToDecimals(origin + n * step);
+  };
+  var n = Math.round((clamp(value) - origin) / step);
+  // Rounding can step outside the range by one; walk back in.
+  if (lo !== undefined && toGrid(n) < lo) n += 1;
+  if (hi !== undefined && toGrid(n) > hi) n -= 1;
+  var snapped = toGrid(n);
+  if (lo !== undefined && snapped < lo || hi !== undefined && snapped > hi) {
+    return null;
+  }
+  if (rules.integer && !Number.isInteger(snapped)) {
+    return null;
+  }
+  return snapped;
+}
+
+/**
+ * `0.1 + 0.2` is `0.30000000000000004`. A value offered to an editor should
+ * read `0.3`, so grid values are rounded to 12 significant decimals — far below
+ * any step anyone writes, far above floating point noise.
+ */
+function roundToDecimals(n) {
+  return Number.parseFloat(n.toFixed(12));
+}
+
+/**
+ * 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).
+ */
+
 var NumberSchema = /*#__PURE__*/function (_Schema) {
   function NumberSchema(options) {
     var _this;
@@ -10194,6 +10275,7 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     var isHidden = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
     var description = arguments.length > 5 ? arguments[5] : undefined;
     var previewInput = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : null;
+    var renderInput = arguments.length > 7 && arguments[7] !== undefined ? arguments[7] : null;
     _classCallCheck(this, NumberSchema);
     _this = _callSuper(this, NumberSchema);
     _this.options = options;
@@ -10203,6 +10285,8 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     _this.isHidden = isHidden;
     _this.description = description;
     _this.previewInput = previewInput;
+    _this.renderInput = renderInput;
+    assertNumberSchemaIsConsistent(_this.options, _this.renderInput);
     return _this;
   }
 
@@ -10227,7 +10311,7 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   return _createClass(NumberSchema, [{
     key: "describe",
     value: function describe(description) {
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.previewInput);
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.previewInput, this.renderInput);
     }
 
     /**
@@ -10253,12 +10337,12 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "validate",
     value: function validate(validationFunction) {
-      return new NumberSchema(this.options, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.isReadonly, this.isHidden, this.description, this.previewInput);
+      return new NumberSchema(this.options, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
     }
   }, {
     key: "executeValidate",
     value: function executeValidate(path, src) {
-      var _this$options, _this$options2;
+      var _this$options;
       var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
         path: path
       });
@@ -10271,20 +10355,35 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
           value: src
         }]));
       }
-      if ((_this$options = this.options) !== null && _this$options !== void 0 && _this$options.max && src > this.options.max) {
-        return _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "Expected 'number' less than ".concat(this.options.max),
+      var errors = _toConsumableArray(customValidationErrors);
+      var options = (_this$options = this.options) !== null && _this$options !== void 0 ? _this$options : {};
+      // `!== undefined`, not truthiness: a bound of 0 is a bound. `.max(0)` and
+      // `.min(0)` used to be ignored, which a slider from 0 makes common.
+      if (options.max !== undefined && src > options.max) {
+        errors.push({
+          message: "Must be at most ".concat(options.max),
           value: src
-        }]));
+        });
       }
-      if ((_this$options2 = this.options) !== null && _this$options2 !== void 0 && _this$options2.min && src < this.options.min) {
-        return _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "Expected 'number' greater than ".concat(this.options.min),
+      if (options.min !== undefined && src < options.min) {
+        errors.push({
+          message: "Must be at least ".concat(options.min),
           value: src
-        }]));
+        });
       }
-      if (customValidationErrors.length > 0) {
-        return _defineProperty({}, path, customValidationErrors);
+      if (options.integer && !Number.isInteger(src)) {
+        errors.push({
+          message: "Must be a whole number",
+          value: src
+        });
+      } else if (options.step !== undefined && !isOnStep(src, stepOrigin(options), options.step)) {
+        errors.push({
+          message: "Must be a multiple of ".concat(options.step, ", counted from ").concat(stepOrigin(options)),
+          value: src
+        });
+      }
+      if (errors.length > 0) {
+        return _defineProperty({}, path, errors);
       }
       return false;
     }
@@ -10323,19 +10422,19 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new NumberSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput);
+      return new NumberSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
     }
   }, {
     key: "readonly",
     value: function readonly() {
       var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.previewInput);
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
     }
   }, {
     key: "hidden",
     value: function hidden() {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.previewInput);
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.previewInput, this.renderInput);
     }
 
     /**
@@ -10350,7 +10449,7 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     value: function max(_max) {
       return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
         max: _max
-      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput);
+      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
     }
 
     /**
@@ -10365,7 +10464,50 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     value: function min(_min) {
       return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
         min: _min
-      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput);
+      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
+    }
+
+    /**
+     * 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);
+     */
+  }, {
+    key: "step",
+    value: function step(_step) {
+      return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
+        step: _step
+      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
+    }
+
+    /**
+     * 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);
+     */
+  }, {
+    key: "render",
+    value: function render(input) {
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput, input);
     }
   }, {
     key: "executeCustomValidateAt",
@@ -10389,7 +10531,7 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "preview",
     value: function preview(select) {
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, select);
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, select, this.renderInput);
     }
   }, {
     key: "executePreviewItem",
@@ -10409,11 +10551,12 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "executeSerialize",
     value: function executeSerialize() {
-      var _this$customValidateF;
+      var _this$renderInput, _this$customValidateF;
       return {
         type: "number",
         preview: this.previewInput ? true : undefined,
         options: this.options,
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
         opt: this.opt,
         customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         readonly: this.isReadonly,
@@ -10426,6 +10569,63 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
 var number = function number(options) {
   return new NumberSchema(options);
 };
+var _int = function _int() {
+  return new NumberSchema({
+    integer: true
+  });
+};
+function assertNumberSchemaIsConsistent(options, render) {
+  var opts = options !== null && options !== void 0 ? options : {};
+  var kind = opts.integer ? "s.int()" : "s.number()";
+  if (opts.step !== undefined) {
+    if (!(opts.step > 0) || !Number.isFinite(opts.step)) {
+      throw new Error("".concat(kind, ".step(").concat(opts.step, "): the step must be above 0"));
+    }
+    if (opts.integer && !Number.isInteger(opts.step)) {
+      throw new Error("".concat(kind, ".step(").concat(opts.step, "): the step of an int must be a whole number"));
+    }
+  }
+  if (render === null) {
+    return;
+  }
+  var where = "".concat(kind, ".render({ as: \"slider\", min: ").concat(render.min, ", max: ").concat(render.max, " })");
+  if (!Number.isFinite(render.min) || !Number.isFinite(render.max)) {
+    throw new Error("".concat(where, ": the slider needs a min and a max"));
+  }
+  if (!(render.min < render.max)) {
+    throw new Error("".concat(where, ": the slider's min must be below its max"));
+  }
+  if (opts.min !== undefined && render.min < opts.min) {
+    throw new Error("".concat(where, ": the slider's min ").concat(render.min, " is below the schema's min ").concat(opts.min));
+  }
+  if (opts.max !== undefined && render.max > opts.max) {
+    throw new Error("".concat(where, ": the slider's max ").concat(render.max, " is above the schema's max ").concat(opts.max));
+  }
+  if (render.step !== undefined && !(render.step > 0)) {
+    throw new Error("".concat(where, ": the slider's step must be above 0"));
+  }
+  if (opts.integer) {
+    var sliderNumbers = [["min", render.min], ["max", render.max], ["step", render.step]];
+    for (var _i = 0, _sliderNumbers = sliderNumbers; _i < _sliderNumbers.length; _i++) {
+      var _sliderNumbers$_i = _slicedToArray(_sliderNumbers[_i], 2),
+        name = _sliderNumbers$_i[0],
+        value = _sliderNumbers$_i[1];
+      if (value !== undefined && !Number.isInteger(value)) {
+        throw new Error("".concat(where, ": the slider's ").concat(name, " ").concat(value, " must be a whole number on an int"));
+      }
+    }
+  }
+  if (opts.step !== undefined) {
+    var _render$step;
+    var sliderStep = (_render$step = render.step) !== null && _render$step !== void 0 ? _render$step : opts.step;
+    if (!isOnStep(sliderStep, 0, opts.step)) {
+      throw new Error("".concat(where, ": the slider's step ").concat(sliderStep, " must be a multiple of the schema's step ").concat(opts.step));
+    }
+    if (!isOnStep(render.min, stepOrigin(opts), opts.step)) {
+      throw new Error("".concat(where, ": the slider's min ").concat(render.min, " is not one of the schema's steps (").concat(opts.step, ", counted from ").concat(stepOrigin(opts), ")"));
+    }
+  }
+}
 
 /**
  * @deprecated Use {@link SerializedDiscriminatedUnionSchema} or
@@ -13204,6 +13404,7 @@ function initSchema(options) {
     array: array,
     object: object,
     number: number,
+    "int": _int,
     discriminatedUnion: discriminatedUnion,
     "enum": enumSchema,
     union: union,
@@ -15114,7 +15315,7 @@ function deserializeSchema(serialized) {
   return schema;
 }
 function deserializeSchemaImpl(serialized) {
-  var _serialized$options, _serialized$options2, _serialized$multiline, _serialized$render, _serialized$accept, _serialized$dir, _serialized$remote, _serialized$jsonValue, _serialized$render2, _serialized$external, _serialized$render3, _serialized$render4, _serialized$remote2, _serialized$readonly, _serialized$hidden;
+  var _serialized$options, _serialized$options2, _serialized$multiline, _serialized$render, _serialized$render2, _serialized$accept, _serialized$dir, _serialized$remote, _serialized$jsonValue, _serialized$render3, _serialized$external, _serialized$render4, _serialized$render5, _serialized$remote2, _serialized$readonly, _serialized$hidden;
   switch (serialized.type) {
     case "string":
       return new StringSchema(_objectSpread2(_objectSpread2({}, serialized.options), {}, {
@@ -15126,7 +15327,7 @@ function deserializeSchemaImpl(serialized) {
     case "boolean":
       return new BooleanSchema(serialized.opt, [], false, false, serialized.description);
     case "number":
-      return new NumberSchema(serialized.options, serialized.opt, [], false, false, serialized.description);
+      return new NumberSchema(serialized.options, serialized.opt, [], false, false, serialized.description, null, (_serialized$render = serialized.render) !== null && _serialized$render !== void 0 ? _serialized$render : null);
     case "object":
       return new ObjectSchema(Object.fromEntries(Object.entries(serialized.items).map(function (_ref) {
         var _ref2 = _slicedToArray(_ref, 2),
@@ -15149,7 +15350,7 @@ function deserializeSchemaImpl(serialized) {
     case "array":
       return new ArraySchema(deserializeSchema(serialized.item), serialized.opt, [], false, false, serialized.description,
       // The preview closure cannot survive serialization; the render can.
-      null, (_serialized$render = serialized.render) !== null && _serialized$render !== void 0 ? _serialized$render : null);
+      null, (_serialized$render2 = serialized.render) !== null && _serialized$render2 !== void 0 ? _serialized$render2 : null);
     case "discriminated-union":
       return new DiscriminatedUnionSchema(serialized.key,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -15178,12 +15379,12 @@ function deserializeSchemaImpl(serialized) {
         altSchema: serialized.alt ? deserializeSchema(serialized.alt) : undefined
       } : undefined, false, false, serialized.description, (_serialized$jsonValue = serialized.jsonValues) !== null && _serialized$jsonValue !== void 0 ? _serialized$jsonValue : false,
       // The preview closure cannot survive serialization; the render can.
-      null, (_serialized$render2 = serialized.render) !== null && _serialized$render2 !== void 0 ? _serialized$render2 : null, // The external label is static data, so it survives serialization and
+      null, (_serialized$render3 = serialized.render) !== null && _serialized$render3 !== void 0 ? _serialized$render3 : null, // The external label is static data, so it survives serialization and
       // must be carried back: a deserialized schema that forgot it would walk
       // an external record as if its entries were local.
       (_serialized$external = serialized.external) !== null && _serialized$external !== void 0 ? _serialized$external : null);
     case "keyOf":
-      return new KeyOfSchema(serialized.schema, serialized.path, serialized.opt, [], false, false, serialized.description, (_serialized$render3 = serialized.render) !== null && _serialized$render3 !== void 0 ? _serialized$render3 : null);
+      return new KeyOfSchema(serialized.schema, serialized.path, serialized.opt, [], false, false, serialized.description, (_serialized$render4 = serialized.render) !== null && _serialized$render4 !== void 0 ? _serialized$render4 : null);
     case "locale":
       {
         return new LocaleSchema(serialized.opt, [], false, false, serialized.description);
@@ -15201,7 +15402,7 @@ function deserializeSchemaImpl(serialized) {
     case "image":
       return new ImageSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description);
     case "video":
-      return new VideoSchema(serialized.options, serialized.opt, serialized.remote, [], false, false, serialized.description, (_serialized$render4 = serialized.render) !== null && _serialized$render4 !== void 0 ? _serialized$render4 : null, null, serialized.referencedModule ? {
+      return new VideoSchema(serialized.options, serialized.opt, serialized.remote, [], false, false, serialized.description, (_serialized$render5 = serialized.render) !== null && _serialized$render5 !== void 0 ? _serialized$render5 : null, null, serialized.referencedModule ? {
         modulePath: serialized.referencedModule,
         entries: null,
         remote: (_serialized$remote2 = serialized.remote) !== null && _serialized$remote2 !== void 0 ? _serialized$remote2 : false
@@ -15260,11 +15461,12 @@ function deserializeSchemaImpl(serialized) {
  */
 /**
  * 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
@@ -15320,6 +15522,33 @@ function deserializeSchemaImpl(serialized) {
  * What `.render(...)` takes, and what the serialized schema carries verbatim.
  */
 
+/**
+ * `{ 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.
+ */
+
+/**
+ * What `s.number().render(...)` and `s.int().render(...)` take.
+ */
+
 /**
  * Does this CONTAINER edit its items inside their list rows, rather than behind
  * clickable preview rows that navigate to them?
@@ -15901,7 +16130,7 @@ function isPageRouter(routerId) {
 
 var corePackageJson = {
 	name: "@valbuild/core",
-	version: "0.144.0",
+	version: "0.145.0",
 	"private": false,
 	description: "Val - supercharged hard-coded content",
 	repository: {
@@ -16028,6 +16257,11 @@ var Internal = {
   rejectScheme: rejectScheme,
   schemeOf: schemeOf,
   UNSAFE_URL_SCHEMES: UNSAFE_URL_SCHEMES,
+  number: {
+    nearestAllowedNumber: nearestAllowedNumber,
+    isOnStep: isOnStep,
+    stepOrigin: stepOrigin
+  },
   color: {
     parseColor: parseColor,
     formatColor: formatColor,