@valbuild/core 0.100.0 → 0.101.0

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

@@ -41,6 +41,7 @@ import { getValidationBasis, getValidationHash } from "./remote/validationBasis.
 import { getFileHash, hashToRemoteFileHash } from "./remote/fileHash.js";
 import { splitRemoteRef } from "./remote/splitRemoteRef.js";
 import { convertRemoteSource } from "./schema/remote.js";
+import { colorToHex, convertColor, detectColorFormat, formatColor, parseColor } from "./schema/colorFormat.js";
 export { type SerializedArraySchema, ArraySchema } from "./schema/array.js";
 export { type SerializedObjectSchema, ObjectSchema } from "./schema/object.js";
 export { type SerializedRecordSchema, RecordSchema } from "./schema/record.js";
@@ -50,6 +51,8 @@ export { type SerializedBooleanSchema, BooleanSchema } from "./schema/boolean.js
 export { type SerializedImageSchema, ImageSchema } from "./schema/image.js";
 export { type SerializedFileSchema, FileSchema } from "./schema/file.js";
 export { type SerializedDateSchema, DateSchema } from "./schema/date.js";
+export { type SerializedColorSchema, type ColorOptions, ColorSchema, } from "./schema/color.js";
+export { type ColorFormat, type ParsedColor, COLOR_FORMATS, DEFAULT_COLOR_FORMAT, } from "./schema/colorFormat.js";
 export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetime.js";
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
 export { type SerializedRouteSchema, RouteSchema } from "./schema/route.js";
@@ -79,6 +82,13 @@ declare const Internal: {
     joinModuleFilePathAndModulePath: typeof joinModuleFilePathAndModulePath;
     nextAppRouter: import("./router.js").ValRouter;
     externalPageRouter: import("./router.js").ValRouter;
+    color: {
+        parseColor: typeof parseColor;
+        formatColor: typeof formatColor;
+        convertColor: typeof convertColor;
+        detectColorFormat: typeof detectColorFormat;
+        colorToHex: typeof colorToHex;
+    };
     remote: {
         createRemoteRef: typeof createRemoteRef;
         getValidationBasis: typeof getValidationBasis;

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

@@ -13,6 +13,7 @@ import { file } from "./schema/file.js";
 import { files } from "./schema/files.js";
 import { date } from "./schema/date.js";
 import { datetime } from "./schema/datetime.js";
+import { color } from "./schema/color.js";
 import { route } from "./schema/route.js";
 import { router } from "./schema/router.js";
 import { images } from "./schema/images.js";
@@ -173,6 +174,25 @@ export type InitSchema = {
      *
      */
     readonly datetime: typeof datetime;
+    /**
+     * Define a color.
+     *
+     * Stored as a CSS color string, so it can be used directly in `style`
+     * attributes or set as a CSS custom property.
+     *
+     * The notation is decided by the `format` option, which defaults to `"hsl"`.
+     * Set `alpha: true` to allow transparency.
+     *
+     * @example
+     * const schema = s.color();
+     * export default c.define("/example.val.ts", schema, "hsl(217.22 91.22% 59.8%)");
+     *
+     * @example
+     * const schema = s.color({ format: "hex" });
+     * export default c.define("/example.val.ts", schema, "#3b82f6");
+     *
+     */
+    readonly color: typeof color;
     /**
      * Define a string that references a route path in your application.
      *
@@ -283,6 +303,7 @@ export declare function initSchema(): {
     }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/files.js").FilesEntryMetadata>>;
     date: (options?: Record<string, never>) => import("./schema/date.js").DateSchema<import("./schema/string.js").RawString>;
     datetime: (options?: Record<string, never>) => import("./schema/datetime.js").DateTimeSchema<import("./schema/string.js").RawString>;
+    color: (options?: import("./schema/color.js").ColorOptions) => import("./schema/color.js").ColorSchema<import("./schema/string.js").RawString>;
     route: <T extends string>(options?: Record<string, never>) => import("./schema/route.js").RouteSchema<T>;
     router: typeof router;
     images: <Accept extends `image/${string}`>(options?: import("./schema/images.js").ImagesOptions<Accept>) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{

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

@@ -0,0 +1,57 @@
+import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
+import { ReifiedRender } from "../render.js";
+import { SourcePath } from "../val/index.js";
+import { ColorFormat } from "./colorFormat.js";
+import { RawString } from "./string.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+export type { ColorFormat } from "./colorFormat.js";
+export type ColorOptions = {
+    /**
+     * The CSS notation the color is stored in.
+     *
+     * Defaults to `"hsl"`.
+     *
+     * @example
+     * "hex"   // #3b82f6
+     * "rgb"   // rgb(59 130 246)
+     * "hsl"   // hsl(217.22 91.22% 59.8%)
+     * "oklch" // oklch(0.6231 0.188 259.81)
+     */
+    format?: ColorFormat;
+    /**
+     * Allow an alpha channel (transparency).
+     *
+     * Defaults to `false`: a color with an alpha channel is a validation error
+     * unless this is enabled.
+     */
+    alpha?: boolean;
+};
+export type SerializedColorSchema = {
+    type: "color";
+    options?: ColorOptions;
+    opt: boolean;
+    customValidate?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+export declare class ColorSchema<Src extends string | null> extends Schema<Src> {
+    private readonly options?;
+    private readonly opt;
+    private readonly customValidateFunctions;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    constructor(options?: ColorOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    describe(description: string | null): ColorSchema<Src>;
+    validate(validationFunction: (src: Src) => false | string): ColorSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): ColorSchema<Src | null>;
+    readonly(): ColorSchema<Src>;
+    hidden(): ColorSchema<Src>;
+    protected executeSerialize(): SerializedSchema;
+    protected executeRender(): ReifiedRender;
+}
+export declare const color: (options?: ColorOptions) => ColorSchema<RawString>;

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

@@ -0,0 +1,83 @@
+/**
+ * Parsing / formatting of the CSS color strings stored by `s.color()`.
+ *
+ * Colors are stored as plain CSS strings so that they can be used directly in
+ * `style` attributes and CSS custom properties. The schema decides which family
+ * (`hex`, `rgb`, `hsl` or `oklch`) the string is written in, this module does
+ * the conversion between them.
+ *
+ * All colors are sRGB: `oklch` is only used as an output notation, so any
+ * `oklch` value that falls outside the sRGB gamut is clipped when converted
+ * back to the other formats.
+ */
+export declare const COLOR_FORMATS: readonly ["hex", "rgb", "hsl", "oklch"];
+export type ColorFormat = (typeof COLOR_FORMATS)[number];
+export declare const DEFAULT_COLOR_FORMAT: ColorFormat;
+/**
+ * A color, normalized to sRGB.
+ *
+ * `r`, `g` and `b` are 0-255 (not rounded), `a` is 0-1.
+ */
+export type ParsedColor = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/**
+ * Which color notation a string uses, or `null` if it is not a notation we
+ * recognize. This looks at the syntax only: `detectColorFormat` says nothing
+ * about whether the value actually parses (`hsl(nope)` is still `"hsl"`).
+ */
+export declare function detectColorFormat(value: string): ColorFormat | null;
+/**
+ * Parses a CSS color string into sRGB channels.
+ *
+ * Accepts hex (3, 4, 6 and 8 digits), `rgb()` / `rgba()`, `hsl()` / `hsla()`
+ * and `oklch()`, in both the legacy comma and the modern space syntax. Returns
+ * `null` if the value is not a color we can parse - notably: named colors
+ * (`red`), `color()`, `lab()` and `color-mix()` are not supported.
+ */
+export declare function parseColor(value: string): ParsedColor | null;
+export declare function rgbToHsl(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare function hslToRgb(h: number, s: number, l: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * sRGB to Oklch, using Björn Ottosson's Oklab matrices.
+ */
+export declare function rgbToOklch(r: number, g: number, b: number): {
+    l: number;
+    c: number;
+    h: number;
+};
+/**
+ * Oklch to sRGB. Out of gamut colors are clipped per channel.
+ */
+export declare function oklchToRgb(l: number, c: number, h: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Serializes a color to the canonical string of the given format.
+ *
+ * The modern, space separated CSS syntax is used for the color functions
+ * (`rgb(255 0 0 / 0.5)`). Alpha is only included when it is not fully opaque.
+ */
+export declare function formatColor(color: ParsedColor, format: ColorFormat): string;
+/**
+ * Converts a color string to the canonical string of the given format, or
+ * `null` if the input cannot be parsed.
+ */
+export declare function convertColor(value: string, format: ColorFormat): string | null;
+/**
+ * `#rrggbb`, which is what `<input type="color">` uses as its value.
+ */
+export declare function colorToHex(color: ParsedColor): string;

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

@@ -12,6 +12,7 @@ import { SerializedRecordSchema } from "./record.js";
 import { SerializedRichTextSchema } from "./richtext.js";
 import { RawString, SerializedStringSchema } from "./string.js";
 import { SerializedUnionSchema } from "./union.js";
+import { SerializedColorSchema } from "./color.js";
 import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.js";
 import { SerializedRouteSchema } from "./route.js";
@@ -19,7 +20,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { FileSource } from "../source/file.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
 import { ReifiedRender } from "../render.js";
-export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedRouteSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedRouteSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;