@optique/core 1.1.0-dev.2057 → 1.1.0-dev.2065

package/dist/valueparser.d.cts

@@ -747,6 +747,83 @@ declare function fileSize(options?: FileSizeOptionsNumber): ValueParser<"sync",
  * @since 1.1.0
  */
 declare function fileSize(options: FileSizeOptionsBigInt): ValueParser<"sync", bigint>;
+/**
+ * A structured CSS color value with normalized RGBA components.
+ * @since 1.1.0
+ */
+interface Color {
+  /** Red channel, 0–255. */
+  readonly r: number;
+  /** Green channel, 0–255. */
+  readonly g: number;
+  /** Blue channel, 0–255. */
+  readonly b: number;
+  /** Alpha channel, 0–1 (1 = fully opaque). */
+  readonly a: number;
+}
+/**
+ * The CSS color notation a {@link color} parser accepts.
+ * @since 1.1.0
+ */
+type ColorFormat = "hex" | "rgb" | "hsl" | "named";
+/**
+ * Options for creating a {@link color} value parser.
+ * @since 1.1.0
+ */
+interface ColorOptions {
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"COLOR"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Restricts which CSS color notations are accepted.  Defaults to all
+   * four notations: `"hex"`, `"rgb"`, `"hsl"`, and `"named"`.
+   * @default all formats
+   */
+  readonly formats?: readonly ColorFormat[];
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `{ r: 0, g: 0, b: 0, a: 1 }`
+   * @since 1.1.0
+   */
+  readonly placeholder?: Color;
+  /**
+   * Custom error messages for color parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid CSS color string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser that accepts CSS color strings and returns a
+ * structured {@link Color} object with normalized RGBA components.
+ *
+ * Supported input notations by default:
+ * - Hex: `#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa`
+ * - RGB: `rgb(r, g, b)`, `rgba(r, g, b, a)`
+ * - HSL: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
+ * - Named: all 148 CSS Level 4 named colors (e.g., `red`, `rebeccapurple`)
+ *
+ * The `format()` method always outputs canonical lowercase hex
+ * (`#rrggbb` when fully opaque, `#rrggbbaa` otherwise).
+ *
+ * @param options Configuration options for the parser.
+ * @returns A sync value parser producing {@link Color} objects.
+ * @throws {TypeError} If {@link ColorOptions.metavar} is an empty string, or
+ *   if {@link ColorOptions.formats} contains an invalid format name.
+ * @throws {RangeError} If {@link ValueParser.format} is called with a
+ *   {@link Color} whose `r`, `g`, or `b` channel is not an integer in
+ *   0–255, or whose `a` channel is not a finite number in 0–1.
+ * @since 1.1.0
+ */
+declare function color(options?: ColorOptions): ValueParser<"sync", Color>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -2329,4 +2406,4 @@ interface CidrOptions {
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -747,6 +747,83 @@ declare function fileSize(options?: FileSizeOptionsNumber): ValueParser<"sync",
  * @since 1.1.0
  */
 declare function fileSize(options: FileSizeOptionsBigInt): ValueParser<"sync", bigint>;
+/**
+ * A structured CSS color value with normalized RGBA components.
+ * @since 1.1.0
+ */
+interface Color {
+  /** Red channel, 0–255. */
+  readonly r: number;
+  /** Green channel, 0–255. */
+  readonly g: number;
+  /** Blue channel, 0–255. */
+  readonly b: number;
+  /** Alpha channel, 0–1 (1 = fully opaque). */
+  readonly a: number;
+}
+/**
+ * The CSS color notation a {@link color} parser accepts.
+ * @since 1.1.0
+ */
+type ColorFormat = "hex" | "rgb" | "hsl" | "named";
+/**
+ * Options for creating a {@link color} value parser.
+ * @since 1.1.0
+ */
+interface ColorOptions {
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"COLOR"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Restricts which CSS color notations are accepted.  Defaults to all
+   * four notations: `"hex"`, `"rgb"`, `"hsl"`, and `"named"`.
+   * @default all formats
+   */
+  readonly formats?: readonly ColorFormat[];
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `{ r: 0, g: 0, b: 0, a: 1 }`
+   * @since 1.1.0
+   */
+  readonly placeholder?: Color;
+  /**
+   * Custom error messages for color parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid CSS color string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser that accepts CSS color strings and returns a
+ * structured {@link Color} object with normalized RGBA components.
+ *
+ * Supported input notations by default:
+ * - Hex: `#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa`
+ * - RGB: `rgb(r, g, b)`, `rgba(r, g, b, a)`
+ * - HSL: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
+ * - Named: all 148 CSS Level 4 named colors (e.g., `red`, `rebeccapurple`)
+ *
+ * The `format()` method always outputs canonical lowercase hex
+ * (`#rrggbb` when fully opaque, `#rrggbbaa` otherwise).
+ *
+ * @param options Configuration options for the parser.
+ * @returns A sync value parser producing {@link Color} objects.
+ * @throws {TypeError} If {@link ColorOptions.metavar} is an empty string, or
+ *   if {@link ColorOptions.formats} contains an invalid format name.
+ * @throws {RangeError} If {@link ValueParser.format} is called with a
+ *   {@link Color} whose `r`, `g`, or `b` channel is not an integer in
+ *   0–255, or whose `a` channel is not a finite number in 0–1.
+ * @since 1.1.0
+ */
+declare function color(options?: ColorOptions): ValueParser<"sync", Color>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -2329,4 +2406,4 @@ interface CidrOptions {
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };