css-calipers 0.15.0 → 1.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (207) hide show
  1. package/LICENSE.txt +1 -1
  2. package/README.md +70 -434
  3. package/dist/cjs/color/formats/display-p3/display-p3.js +25 -0
  4. package/dist/cjs/color/formats/escalate.js +41 -0
  5. package/dist/cjs/color/formats/hex/hex.js +28 -0
  6. package/dist/cjs/color/formats/hexAlpha/hexAlpha.js +25 -0
  7. package/dist/cjs/color/formats/hsl/hsl.js +23 -0
  8. package/dist/cjs/color/formats/hwb/hwb.js +24 -0
  9. package/dist/cjs/color/formats/index.js +36 -0
  10. package/dist/cjs/color/formats/internals.js +93 -0
  11. package/dist/cjs/color/formats/lab/lab.js +24 -0
  12. package/dist/cjs/color/formats/lch/lch.js +23 -0
  13. package/dist/cjs/color/formats/oklab/oklab.js +24 -0
  14. package/dist/cjs/color/formats/oklch/oklch.js +28 -0
  15. package/dist/cjs/color/formats/resolve.js +16 -0
  16. package/dist/cjs/color/formats/rgb/rgb.js +29 -0
  17. package/dist/cjs/color/formats/rgba/rgba.js +27 -0
  18. package/dist/cjs/color/formats/types.js +11 -0
  19. package/dist/cjs/color/index.js +619 -0
  20. package/dist/cjs/color/types.js +2 -0
  21. package/dist/cjs/core.js +11 -8
  22. package/dist/cjs/corpus.js +53 -0
  23. package/dist/cjs/css-values/cssValues.js +78 -0
  24. package/dist/cjs/css-values/index.js +36 -0
  25. package/dist/cjs/css-values/multi.js +290 -0
  26. package/dist/cjs/css-values/propertyMap.js +2 -0
  27. package/dist/cjs/css-values/spec.js +197 -0
  28. package/dist/cjs/default.js +17 -0
  29. package/dist/cjs/factory.js +1 -1
  30. package/dist/cjs/float.js +110 -0
  31. package/dist/cjs/index.js +29 -9
  32. package/dist/cjs/integer.js +114 -0
  33. package/dist/cjs/internal/createCoreApi.js +103 -38
  34. package/dist/cjs/internal/errors.js +13 -14
  35. package/dist/cjs/internal/toPlainDecimal.js +31 -0
  36. package/dist/cjs/measurements.js +41 -0
  37. package/dist/cjs/ratio.js +57 -22
  38. package/dist/cjs/scalar.js +9 -0
  39. package/dist/cjs/units/absolute.js +8 -8
  40. package/dist/cjs/units/angle.js +5 -5
  41. package/dist/cjs/units/container.js +7 -7
  42. package/dist/cjs/units/font-relative.js +13 -13
  43. package/dist/cjs/units/frequency.js +3 -3
  44. package/dist/cjs/units/grid.js +2 -2
  45. package/dist/cjs/units/index.js +9 -9
  46. package/dist/cjs/units/percent.js +4 -4
  47. package/dist/cjs/units/resolution.js +4 -4
  48. package/dist/cjs/units/time.js +3 -3
  49. package/dist/cjs/units/viewport-dynamic.js +7 -7
  50. package/dist/cjs/units/viewport-large.js +7 -7
  51. package/dist/cjs/units/viewport-small.js +7 -7
  52. package/dist/cjs/units/viewport.js +7 -7
  53. package/dist/esm/color/formats/display-p3/display-p3.d.ts +10 -0
  54. package/dist/esm/color/formats/display-p3/display-p3.d.ts.map +1 -0
  55. package/dist/esm/color/formats/display-p3/display-p3.js +22 -0
  56. package/dist/esm/color/formats/escalate.d.ts +10 -0
  57. package/dist/esm/color/formats/escalate.d.ts.map +1 -0
  58. package/dist/esm/color/formats/escalate.js +37 -0
  59. package/dist/esm/color/formats/hex/hex.d.ts +9 -0
  60. package/dist/esm/color/formats/hex/hex.d.ts.map +1 -0
  61. package/dist/esm/color/formats/hex/hex.js +25 -0
  62. package/dist/esm/color/formats/hexAlpha/hexAlpha.d.ts +9 -0
  63. package/dist/esm/color/formats/hexAlpha/hexAlpha.d.ts.map +1 -0
  64. package/dist/esm/color/formats/hexAlpha/hexAlpha.js +22 -0
  65. package/dist/esm/color/formats/hsl/hsl.d.ts +8 -0
  66. package/dist/esm/color/formats/hsl/hsl.d.ts.map +1 -0
  67. package/dist/esm/color/formats/hsl/hsl.js +20 -0
  68. package/dist/esm/color/formats/hwb/hwb.d.ts +9 -0
  69. package/dist/esm/color/formats/hwb/hwb.d.ts.map +1 -0
  70. package/dist/esm/color/formats/hwb/hwb.js +21 -0
  71. package/dist/esm/color/formats/index.d.ts +24 -0
  72. package/dist/esm/color/formats/index.d.ts.map +1 -0
  73. package/dist/esm/color/formats/index.js +32 -0
  74. package/dist/esm/color/formats/internals.d.ts +35 -0
  75. package/dist/esm/color/formats/internals.d.ts.map +1 -0
  76. package/dist/esm/color/formats/internals.js +78 -0
  77. package/dist/esm/color/formats/lab/lab.d.ts +9 -0
  78. package/dist/esm/color/formats/lab/lab.d.ts.map +1 -0
  79. package/dist/esm/color/formats/lab/lab.js +21 -0
  80. package/dist/esm/color/formats/lch/lch.d.ts +8 -0
  81. package/dist/esm/color/formats/lch/lch.d.ts.map +1 -0
  82. package/dist/esm/color/formats/lch/lch.js +20 -0
  83. package/dist/esm/color/formats/oklab/oklab.d.ts +9 -0
  84. package/dist/esm/color/formats/oklab/oklab.d.ts.map +1 -0
  85. package/dist/esm/color/formats/oklab/oklab.js +21 -0
  86. package/dist/esm/color/formats/oklch/oklch.d.ts +13 -0
  87. package/dist/esm/color/formats/oklch/oklch.d.ts.map +1 -0
  88. package/dist/esm/color/formats/oklch/oklch.js +25 -0
  89. package/dist/esm/color/formats/resolve.d.ts +15 -0
  90. package/dist/esm/color/formats/resolve.d.ts.map +1 -0
  91. package/dist/esm/color/formats/resolve.js +12 -0
  92. package/dist/esm/color/formats/rgb/rgb.d.ts +11 -0
  93. package/dist/esm/color/formats/rgb/rgb.d.ts.map +1 -0
  94. package/dist/esm/color/formats/rgb/rgb.js +26 -0
  95. package/dist/esm/color/formats/rgba/rgba.d.ts +9 -0
  96. package/dist/esm/color/formats/rgba/rgba.d.ts.map +1 -0
  97. package/dist/esm/color/formats/rgba/rgba.js +24 -0
  98. package/dist/esm/color/formats/types.d.ts +48 -0
  99. package/dist/esm/color/formats/types.d.ts.map +1 -0
  100. package/dist/esm/color/formats/types.js +7 -0
  101. package/dist/esm/color/index.d.ts +81 -0
  102. package/dist/esm/color/index.d.ts.map +1 -0
  103. package/dist/esm/color/index.js +609 -0
  104. package/dist/esm/color/types.d.ts +294 -0
  105. package/dist/esm/color/types.d.ts.map +1 -0
  106. package/dist/esm/color/types.js +1 -0
  107. package/dist/esm/core.d.ts +76 -270
  108. package/dist/esm/core.d.ts.map +1 -1
  109. package/dist/esm/core.js +5 -7
  110. package/dist/esm/corpus.d.ts +26 -0
  111. package/dist/esm/corpus.d.ts.map +1 -0
  112. package/dist/esm/corpus.js +37 -0
  113. package/dist/esm/css-values/cssValues.d.ts +60 -0
  114. package/dist/esm/css-values/cssValues.d.ts.map +1 -0
  115. package/dist/esm/css-values/cssValues.js +74 -0
  116. package/dist/esm/css-values/index.d.ts +6 -0
  117. package/dist/esm/css-values/index.d.ts.map +1 -0
  118. package/dist/esm/css-values/index.js +12 -0
  119. package/dist/esm/css-values/multi.d.ts +188 -0
  120. package/dist/esm/css-values/multi.d.ts.map +1 -0
  121. package/dist/esm/css-values/multi.js +281 -0
  122. package/dist/esm/css-values/propertyMap.d.ts +39 -0
  123. package/dist/esm/css-values/propertyMap.d.ts.map +1 -0
  124. package/dist/esm/css-values/propertyMap.js +1 -0
  125. package/dist/esm/css-values/spec.d.ts +36 -0
  126. package/dist/esm/css-values/spec.d.ts.map +1 -0
  127. package/dist/esm/css-values/spec.js +194 -0
  128. package/dist/esm/default.d.ts +267 -0
  129. package/dist/esm/default.d.ts.map +1 -0
  130. package/dist/esm/default.js +14 -0
  131. package/dist/esm/factory.d.ts +1 -1
  132. package/dist/esm/factory.d.ts.map +1 -1
  133. package/dist/esm/factory.js +3 -3
  134. package/dist/esm/float.d.ts +35 -0
  135. package/dist/esm/float.d.ts.map +1 -0
  136. package/dist/esm/float.js +104 -0
  137. package/dist/esm/index.d.ts +11 -9
  138. package/dist/esm/index.d.ts.map +1 -1
  139. package/dist/esm/index.js +19 -9
  140. package/dist/esm/integer.d.ts +36 -0
  141. package/dist/esm/integer.d.ts.map +1 -0
  142. package/dist/esm/integer.js +108 -0
  143. package/dist/esm/internal/buildMeasurementCreationError.tests.d.ts +1 -1
  144. package/dist/esm/internal/buildMeasurementCreationError.tests.d.ts.map +1 -1
  145. package/dist/esm/internal/createCoreApi.d.ts +9 -1
  146. package/dist/esm/internal/createCoreApi.d.ts.map +1 -1
  147. package/dist/esm/internal/createCoreApi.js +103 -38
  148. package/dist/esm/internal/createUnitsApi.d.ts +1 -1
  149. package/dist/esm/internal/createUnitsApi.d.ts.map +1 -1
  150. package/dist/esm/internal/errors.d.ts +3 -3
  151. package/dist/esm/internal/errors.d.ts.map +1 -1
  152. package/dist/esm/internal/errors.js +13 -14
  153. package/dist/esm/internal/toPlainDecimal.d.ts +2 -0
  154. package/dist/esm/internal/toPlainDecimal.d.ts.map +1 -0
  155. package/dist/esm/internal/toPlainDecimal.js +27 -0
  156. package/dist/esm/measurements.d.ts +16 -0
  157. package/dist/esm/measurements.d.ts.map +1 -0
  158. package/dist/esm/measurements.js +25 -0
  159. package/dist/esm/ratio.d.ts +14 -5
  160. package/dist/esm/ratio.d.ts.map +1 -1
  161. package/dist/esm/ratio.js +57 -22
  162. package/dist/esm/scalar.d.ts +14 -0
  163. package/dist/esm/scalar.d.ts.map +1 -0
  164. package/dist/esm/scalar.js +5 -0
  165. package/dist/esm/units/absolute.d.ts +1 -1
  166. package/dist/esm/units/absolute.d.ts.map +1 -1
  167. package/dist/esm/units/absolute.js +1 -1
  168. package/dist/esm/units/angle.d.ts +1 -1
  169. package/dist/esm/units/angle.d.ts.map +1 -1
  170. package/dist/esm/units/angle.js +1 -1
  171. package/dist/esm/units/container.d.ts +1 -1
  172. package/dist/esm/units/container.d.ts.map +1 -1
  173. package/dist/esm/units/container.js +1 -1
  174. package/dist/esm/units/font-relative.d.ts +1 -1
  175. package/dist/esm/units/font-relative.d.ts.map +1 -1
  176. package/dist/esm/units/font-relative.js +1 -1
  177. package/dist/esm/units/frequency.d.ts +1 -1
  178. package/dist/esm/units/frequency.d.ts.map +1 -1
  179. package/dist/esm/units/frequency.js +1 -1
  180. package/dist/esm/units/grid.d.ts +1 -1
  181. package/dist/esm/units/grid.d.ts.map +1 -1
  182. package/dist/esm/units/grid.js +1 -1
  183. package/dist/esm/units/index.d.ts +9 -9
  184. package/dist/esm/units/index.d.ts.map +1 -1
  185. package/dist/esm/units/index.js +9 -9
  186. package/dist/esm/units/percent.d.ts +1 -1
  187. package/dist/esm/units/percent.d.ts.map +1 -1
  188. package/dist/esm/units/percent.js +1 -1
  189. package/dist/esm/units/resolution.d.ts +1 -1
  190. package/dist/esm/units/resolution.d.ts.map +1 -1
  191. package/dist/esm/units/resolution.js +1 -1
  192. package/dist/esm/units/time.d.ts +1 -1
  193. package/dist/esm/units/time.d.ts.map +1 -1
  194. package/dist/esm/units/time.js +1 -1
  195. package/dist/esm/units/viewport-dynamic.d.ts +1 -1
  196. package/dist/esm/units/viewport-dynamic.d.ts.map +1 -1
  197. package/dist/esm/units/viewport-dynamic.js +1 -1
  198. package/dist/esm/units/viewport-large.d.ts +1 -1
  199. package/dist/esm/units/viewport-large.d.ts.map +1 -1
  200. package/dist/esm/units/viewport-large.js +1 -1
  201. package/dist/esm/units/viewport-small.d.ts +1 -1
  202. package/dist/esm/units/viewport-small.d.ts.map +1 -1
  203. package/dist/esm/units/viewport-small.js +1 -1
  204. package/dist/esm/units/viewport.d.ts +1 -1
  205. package/dist/esm/units/viewport.d.ts.map +1 -1
  206. package/dist/esm/units/viewport.js +1 -1
  207. package/package.json +55 -13
@@ -0,0 +1,294 @@
1
+ import type { Property } from 'csstype';
2
+ import type { Color } from 'culori';
3
+ import type { DegMeasurement } from '../units/angle';
4
+ import type { ColorSpaceDescriptor } from './formats/types';
5
+ /**
6
+ * The color book's TYPE contract: the live, library-agnostic surface for the
7
+ * input + storage layers. Runtime lives in `./color.ts`, which re-exports these.
8
+ *
9
+ * The backing library (culori) is referenced only by the internal `Store.color`
10
+ * shape; the author-facing types (`ColorInput`, `ColorObject`, `Symbolic*`) never
11
+ * name it.
12
+ */
13
+ export type ColorObject = {
14
+ space: 'rgb';
15
+ r: number;
16
+ g: number;
17
+ b: number;
18
+ alpha?: number;
19
+ } | {
20
+ space: 'hsl';
21
+ h: number;
22
+ s: number;
23
+ l: number;
24
+ alpha?: number;
25
+ } | {
26
+ space: 'hwb';
27
+ h: number;
28
+ w: number;
29
+ b: number;
30
+ alpha?: number;
31
+ } | {
32
+ space: 'lab';
33
+ l: number;
34
+ a: number;
35
+ b: number;
36
+ alpha?: number;
37
+ } | {
38
+ space: 'lch';
39
+ l: number;
40
+ c: number;
41
+ h: number;
42
+ alpha?: number;
43
+ } | {
44
+ space: 'oklab';
45
+ l: number;
46
+ a: number;
47
+ b: number;
48
+ alpha?: number;
49
+ } | {
50
+ space: 'oklch';
51
+ l: number;
52
+ c: number;
53
+ h: number;
54
+ alpha?: number;
55
+ };
56
+ /** The color-space discriminants (`'rgb' | 'hsl' | ...`). */
57
+ export type ColorSpace = ColorObject['space'];
58
+ export type CurrentColor = 'currentColor';
59
+ /** CSS Color 4 system colors (current). */
60
+ export type SystemColor = 'Canvas' | 'CanvasText' | 'LinkText' | 'VisitedText' | 'ActiveText' | 'ButtonFace' | 'ButtonText' | 'ButtonBorder' | 'Field' | 'FieldText' | 'Highlight' | 'HighlightText' | 'SelectedItem' | 'SelectedItemText' | 'Mark' | 'MarkText' | 'GrayText' | 'AccentColor' | 'AccentColorText';
61
+ /** Deprecated system colors (Appendix A): valid values, accepted as passthrough. */
62
+ export type DeprecatedSystemColor = 'ActiveBorder' | 'ActiveCaption' | 'AppWorkspace' | 'Background' | 'ButtonHighlight' | 'ButtonShadow' | 'CaptionText' | 'InactiveBorder' | 'InactiveCaption' | 'InactiveCaptionText' | 'InfoBackground' | 'InfoText' | 'Menu' | 'MenuText' | 'Scrollbar' | 'ThreeDDarkShadow' | 'ThreeDFace' | 'ThreeDHighlight' | 'ThreeDLightShadow' | 'ThreeDShadow' | 'Window' | 'WindowFrame' | 'WindowText';
63
+ /** CSS-wide cascade keywords: valid color values, accepted as passthrough. */
64
+ export type CascadeKeyword = 'inherit' | 'initial' | 'unset' | 'revert' | 'revert-layer';
65
+ /** Any keyword with no fixed value (emit-only; modifying/converting it throws). */
66
+ export type SymbolicColor = CurrentColor | SystemColor | DeprecatedSystemColor | CascadeKeyword;
67
+ /**
68
+ * The canonical store, shared by the input and storage steps.
69
+ *
70
+ * - `color` is a culori color object. It can be any mode after INPUT (parse), and
71
+ * is normalized to OKLCH after STORAGE. That OKLCH-only state is a runtime
72
+ * invariant (asserted by the storage tests), not encoded in the type: the engine
73
+ * ties input and storage to one `Store`, so `color` stays broad here.
74
+ * - symbolic keywords carry no value and pass through untouched.
75
+ */
76
+ export type Store = {
77
+ kind: 'color';
78
+ color: Color;
79
+ } | {
80
+ kind: 'symbolic';
81
+ keyword: SymbolicColor;
82
+ };
83
+ /**
84
+ * What a color may be created from: a CSS string, a structured `ColorObject`, or an
85
+ * existing `ResolvedColor` (re-wrap). All library-agnostic - culori is never named.
86
+ */
87
+ export type ColorInput = string | ColorObject | ResolvedColor;
88
+ /** A CSS color value string. The `.css()` terminal returns this (csstype-typed). */
89
+ export type CssColor = Property.Color;
90
+ /**
91
+ * A CSS color string hardened to the format that produced it. A specific format
92
+ * selector (`color(x).hex()`) yields a value typed `ColorString<'hex'>`, so "this is
93
+ * a hex color" survives in the type, not just at runtime. Stays assignable to a plain
94
+ * `CssColor`.
95
+ */
96
+ export type ColorString<F extends string = string> = CssColor & {
97
+ readonly __colorFormat: F;
98
+ };
99
+ /**
100
+ * The output formats. Every alpha-capable format always renders its alpha slot;
101
+ * `rgb` / `hex` (hex6) carry no alpha and warn if they would drop a non-opaque one.
102
+ */
103
+ export type CssFormat = {
104
+ format: 'rgba';
105
+ } | {
106
+ format: 'rgb';
107
+ } | {
108
+ format: 'hex';
109
+ } | {
110
+ format: 'hexAlpha';
111
+ } | {
112
+ format: 'hsl';
113
+ } | {
114
+ format: 'hwb';
115
+ } | {
116
+ format: 'lab';
117
+ } | {
118
+ format: 'lch';
119
+ } | {
120
+ format: 'oklab';
121
+ } | {
122
+ format: 'oklch';
123
+ } | {
124
+ format: 'displayP3';
125
+ };
126
+ /** The format discriminants (`'rgba' | 'hex' | ...`). */
127
+ export type FormatName = CssFormat['format'];
128
+ /**
129
+ * An entry in `ColorConfig.output`: either a built-in format selector (`CssFormat`,
130
+ * e.g. `colorFormats.hex`) or a full custom descriptor authored via
131
+ * `defineColorSpace`. A custom descriptor carries an arbitrary `format` string, so the
132
+ * engine must resolve it from the passed object, not by a registry name lookup.
133
+ */
134
+ export type OutputFormat = CssFormat | ColorSpaceDescriptor<string>;
135
+ /**
136
+ * A custom colour-format PLUGIN: a full output descriptor (render + fidelity +
137
+ * browser bits) that ALSO bridges the INPUT edge. Registered through `createColor`,
138
+ * a plugin extends the pipeline at both edges while storage stays canonical OKLCH.
139
+ *
140
+ * `parse` recognizes and converts this format's INPUT into a culori `Color`; the
141
+ * existing `storeColor` then normalizes it to OKLCH. Returning `undefined` declines
142
+ * the input, so the next plugin (then the built-in parser) gets a chance. A plugin
143
+ * therefore only claims inputs the built-ins reject (e.g. `'flamingo'`).
144
+ */
145
+ export interface ColorFormatPlugin<F extends string = string> extends ColorSpaceDescriptor<F> {
146
+ parse?: (input: string) => Color | undefined;
147
+ /**
148
+ * A browser-compatibility hook (output-edge). When this format's `render` emits a
149
+ * token a downstream post-processor (Lightning CSS, via gilding) cannot understand,
150
+ * the format declares HERE how to rewrite its own output into safe CSS. The gilding
151
+ * finisher reads this off the `createColor` registry and runs it as a pre-step in
152
+ * front of its core (the onion), instead of hard-coding a keyword map.
153
+ *
154
+ * Optional, so existing plugins are unaffected. Deliberately a plain string->string
155
+ * transform: calipers takes on NO gilding dependency, and this is purely additive.
156
+ * Calipers' own logic (parse / render / escalation) MUST NOT read this field.
157
+ */
158
+ fallback?: (css: string) => string;
159
+ }
160
+ /**
161
+ * How a "can't faithfully represent this" violation is surfaced: dropping a real
162
+ * alpha, out-of-gamut, or modifying a symbolic color. `auto` = throw in dev / warn
163
+ * in prod.
164
+ */
165
+ export type Strictness = 'auto' | 'throw' | 'warn' | 'silent';
166
+ /**
167
+ * How a fully-transparent color (alpha 0) is rendered: the `transparent` keyword,
168
+ * white at 0, black at 0, or `preserve` (the colour's own RGB at alpha 0, e.g.
169
+ * `rgba(51, 102, 204, 0)`). `preserve` is the truest fade: it keeps the hue, so a
170
+ * gradient toward it stays in-colour instead of drifting through black.
171
+ */
172
+ export type TransparentRendering = 'keyword' | 'white' | 'black' | 'preserve';
173
+ /**
174
+ * The separable CSS blend modes: the per-channel formula modes from the W3C
175
+ * compositing spec. They are defined on sRGB channels, so `blend()` applies them in
176
+ * sRGB. The non-separable modes (`hue`, `saturation`, `color`, `luminosity`) are
177
+ * intentionally excluded, they are not channel formulas.
178
+ */
179
+ export type BlendMode = 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion';
180
+ /** The color book's config (factory-settable via `publishBookColor`). */
181
+ export interface ColorConfig {
182
+ /**
183
+ * What `.css()` renders with no argument: a single format, or a priority list that
184
+ * escalates to the first format faithfully holding the color (simplest first). An
185
+ * entry may be a built-in selector (`colorFormats.hex`) or a full custom descriptor
186
+ * authored via `defineColorSpace`.
187
+ */
188
+ output: OutputFormat | ReadonlyArray<OutputFormat>;
189
+ /** how violations are surfaced (strict by default; relaxed only in production). */
190
+ strictness: Strictness;
191
+ /**
192
+ * How a fully-transparent color (alpha 0) renders: the `transparent` keyword,
193
+ * white at 0, black at 0, or the colour's own RGB at 0 (`preserve`). This is the
194
+ * default for any render; override it per result with `.transparentAs(mode)`.
195
+ */
196
+ transparent: TransparentRendering;
197
+ /**
198
+ * Drop the alpha slot when the color is fully opaque (alpha 1) for formats whose
199
+ * alpha is optional (e.g. `rgba(...,1)` -> `rgb(...)`). Lossless. Off by default.
200
+ */
201
+ omitOpaqueAlpha: boolean;
202
+ }
203
+ /**
204
+ * The resolved color: render via `.css()`, or pick a format. The selectors set the
205
+ * format and return a new result; you still finish with `.css()`. Rendering only
206
+ * ever happens through `.css()`.
207
+ */
208
+ export interface ResolvedColor<F extends string = FormatName> {
209
+ /** the single render terminal: a `ColorString<F>` in this result's configured
210
+ * format. Argument-free: override the output beforehand via a named selector
211
+ * (`.hex()`, `.oklch()`, ...) or `.formatAs(...)`, then finish with `.css()`. */
212
+ css(): ColorString<F>;
213
+ rgba(): ResolvedColor<'rgba'>;
214
+ rgb(): ResolvedColor<'rgb'>;
215
+ hex(): ResolvedColor<'hex'>;
216
+ hexAlpha(): ResolvedColor<'hexAlpha'>;
217
+ hsl(): ResolvedColor<'hsl'>;
218
+ hwb(): ResolvedColor<'hwb'>;
219
+ lab(): ResolvedColor<'lab'>;
220
+ lch(): ResolvedColor<'lch'>;
221
+ oklab(): ResolvedColor<'oklab'>;
222
+ oklch(): ResolvedColor<'oklch'>;
223
+ displayP3(): ResolvedColor<'displayP3'>;
224
+ /**
225
+ * Override the configured output format for THIS result, then finish with
226
+ * `.css()`. Accepts a single `OutputFormat` (built-in selector or custom
227
+ * descriptor) or a priority list that escalates to the first faithful format.
228
+ * The ergonomic path for a built-in is its named selector (`.hex()`, `.oklch()`,
229
+ * ...); `formatAs` is for a custom descriptor or a dynamic / list output.
230
+ */
231
+ formatAs(format: OutputFormat): ResolvedColor;
232
+ formatAs(formats: ReadonlyArray<OutputFormat>): ResolvedColor;
233
+ /**
234
+ * Override how a fully-transparent colour (alpha 0) renders for THIS result,
235
+ * winning over the configured `transparent` default (most-specific wins). A no-op
236
+ * when the colour is not fully transparent. The output format threads through
237
+ * unchanged, so it composes with the format selectors in any order.
238
+ */
239
+ transparentAs(mode: TransparentRendering): ResolvedColor<F>;
240
+ alpha: {
241
+ (): number;
242
+ (value: number): ResolvedColor<F>;
243
+ };
244
+ darken(amount?: number): ResolvedColor<F>;
245
+ lighten(amount?: number): ResolvedColor<F>;
246
+ brighten(amount?: number): ResolvedColor<F>;
247
+ saturate(amount?: number): ResolvedColor<F>;
248
+ desaturate(amount?: number): ResolvedColor<F>;
249
+ hueShift(value: DegMeasurement): ResolvedColor<F>;
250
+ /** Set the OKLCH lightness coordinate absolutely (0..1). */
251
+ setLightness(value: number): ResolvedColor<F>;
252
+ /** Set the OKLCH chroma coordinate absolutely (>= 0). */
253
+ setChroma(value: number): ResolvedColor<F>;
254
+ /** Set the OKLCH hue coordinate absolutely (degrees, wrapped to [0, 360)). */
255
+ setHue(value: DegMeasurement): ResolvedColor<F>;
256
+ /** Rotate the OKLCH hue by 180 degrees (the colour wheel opposite). */
257
+ complement(): ResolvedColor<F>;
258
+ /**
259
+ * Invert the OKLCH lightness (`L -> 1 - L`), keeping chroma and hue. `amount`
260
+ * (0..1) interpolates original <-> inverted; default `1` (full invert), and `0.5`
261
+ * lands on mid lightness for any colour.
262
+ */
263
+ invert(amount?: number): ResolvedColor<F>;
264
+ /**
265
+ * Drop OKLCH chroma toward grey (`C -> C * (1 - amount)`), keeping lightness and
266
+ * hue. `amount` (0..1); default `1` (fully desaturated grey).
267
+ */
268
+ grayscale(amount?: number): ResolvedColor<F>;
269
+ /**
270
+ * Blend `other` onto this colour with a separable blend mode. Blend modes are
271
+ * sRGB-defined channel formulas, so the blend is computed in sRGB (a wide-gamut
272
+ * operand is gamut-mapped to sRGB first); storage stays canonical OKLCH.
273
+ */
274
+ blend(other: ColorInput, mode: BlendMode): ResolvedColor<F>;
275
+ /**
276
+ * Adjust THIS colour's OKLCH lightness toward black or white until its WCAG 2.x
277
+ * contrast against `other` reaches `ratio` (default `4.5`, WCAG AA; pass `7` for
278
+ * AAA), moving the least amount needed. If the ratio is unreachable even at pure
279
+ * black/white, returns the best-achievable (max-contrast) colour.
280
+ */
281
+ ensureContrast(other: ColorInput, ratio?: number): ResolvedColor<F>;
282
+ /**
283
+ * The WCAG 2.x relative-luminance contrast ratio between this colour and
284
+ * `other` (1..21). A terminal (returns a number, like `alpha()`); on a symbolic
285
+ * colour it is a violation and returns `NaN`.
286
+ */
287
+ contrast(other: ColorInput): number;
288
+ mix(target: ColorInput, ratio?: number, mode?: ColorSpace): ResolvedColor<F>;
289
+ mixSolid(target: ColorInput, ratio?: number, mode?: ColorSpace): ResolvedColor<F>;
290
+ mixWithAlpha(target: ColorInput, ratio?: number, alpha?: number, mode?: ColorSpace): ResolvedColor<F>;
291
+ solid(): ResolvedColor<F>;
292
+ clone(): ResolvedColor<F>;
293
+ }
294
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/color/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1 @@
1
+ export {};