@wistia/kaleidoscope 0.0.1 → 0.0.2-beta.28ee13df.cba4a37

package/README.md

@@ -1,6 +1,6 @@
 # @wistia/kaleidoscope
 
-TODO: describe what this package does.
+Shared color logic for Wistia's audience-facing design system, Kaleidoscope.
 
 ## Installation
 
@@ -8,6 +8,96 @@ TODO: describe what this package does.
 yarn add @wistia/kaleidoscope
 ```
 
+## Usage
+
+```ts
+import { Color, ColorScale } from '@wistia/kaleidoscope';
+
+const brand = new Color('#2949e5');
+
+brand.lighten(0.5); // Lighten by 50%, preserving hue
+brand.blend('#ffcc00', 0.5); // Blend yellow into base color, using oklch color space
+brand.contrast('#ffffff'); // fetch the contrast ratio of the given color against white
+
+// Yields a set of 5 colors between black, brand blue, and white, where the lightness is
+// adjusted for optical balance throughout the scale.
+new ColorScale(['#000000', brand, '#ffffff']).correctLightness().colors(5);
+```
+
+`Color` reads hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, with or without the `#`),
+`rgb()`/`rgba()` in both legacy and modern CSS syntax, `[r, g, b, a]` tuples, and any
+`{ r, g, b, a }` object. Named CSS colors, e.g., "darkcyan", are not supported.
+
+Every method returns a new instance, so a color or scale can be shared without anything
+mutating it out from under its other holders.
+
+| `Color` | |
+| --- | --- |
+| **Conversion** | `toHex`, `toHexWithAlpha`, `toRgb`, `toRgba`, `toRgbaTuple`, `toHsl`, `toLab`, `toString` |
+| **Adjust lightness** | `lighten`, `darken`, `withLightness` |
+| **Adjust mix** | `tint`, `shade`, `blend` |
+| **Adjust alpha** | `withAlpha` |
+| **Measure** | `luminance`, `contrast` |
+| **Construct** | `Color.parse`, `Color.fromHsl`, `Color.fromLab` |
+
+| `ColorScale` | |
+| --- | --- |
+| **Generate** | `at`, `colors` |
+| **Configure** | `mode`, `domain`, `gamma`, `padding`, `classes`, `correctLightness` |
+
+
+## Contrast
+
+Two helpers pick or repair a color so it clears the WCAG ratio its content needs. Both
+take named options and return a `Color`; `shape` names the kind of content and defaults to
+`paragraphText` (4.5:1).
+
+```ts
+import { adjustColorForProperContrast, getBestColorForText } from '@wistia/kaleidoscope';
+
+// Choose from a palette. Of the candidates that clear the ratio, you get the one closest
+// in tone to the background — legible without jumping to stark black or white.
+getBestColorForText({
+  backgroundColor: '#ffffff',
+  palette: ['#2949e5', '#c7d3ff'],
+  shape: 'smallText',
+}); // '#2949e5' — the tint is too pale to clear 5.5:1
+
+// Repair a single color. Hue is pinned, so the result still reads as the color you gave it.
+adjustColorForProperContrast({
+  foregroundColor: '#2949e5',
+  backgroundColor: '#2949e5',
+  shape: 'nonText',
+});
+```
+
+`getBestColorForText` always keeps black and white in play, so an empty `palette` still
+yields whichever of the two reads against the background, and `exclude` can never strand it
+without a legible option. It also keeps text on the side it belongs on — light on a dark
+background, dark on a light one — since the WCAG ratio is symmetric and would otherwise
+allow murky dark-on-dark results at the looser ratios. `adjustColorForProperContrast`
+returns its input untouched when that already contrasts.
+
+Some backgrounds cannot reach the stricter ratios from any color at all — a mid-gray tops
+out near 5.3:1, short of `smallText`. Rather than throwing, both helpers then return the
+most contrasting color available, which is always black or white and is picked by measuring
+both. Check the result with `contrast` when the ratio is load-bearing.
+
+
+## Storybook
+
+Color is easier to judge by eye than by assertion, so every feature has a story, including
+playgrounds for `Color` and `ColorScale` wired to live controls.
+
+**[Browse the Storybook →](https://wistia.github.io/vhs/storybook-kaleidoscope/)**
+
+Or run it locally, from the repo root:
+
+```sh
+yarn storybook:kaleidoscope   # serves on http://127.0.0.1:6008
+```
+
+
 ## Development
 
 This package lives in the [vhs monorepo](https://github.com/wistia/vhs). From the repo root:

package/dist/index.d.ts

@@ -1,11 +1,280 @@
 
 //#region src/colorContrastRatiosByShape.d.ts
 declare const colorContrastRatiosByShape: {
-  nonText: number;
-  largeText: number;
-  paragraphText: number;
-  smallText: number;
+  readonly nonText: 3.0;
+  readonly largeText: 3.0;
+  readonly paragraphText: 4.5;
+  readonly smallText: 5.5;
 };
+/** The kind of content a color has to be legible as, which sets the ratio it has to clear. */
+type ColorShape = keyof typeof colorContrastRatiosByShape;
 //#endregion
-export { colorContrastRatiosByShape };
+//#region src/Color.d.ts
+/**
+ * An immutable sRGB color with transformation methods like lighten, darken, tint, shade.
+ * Also includes methods to calculate contrast ratio against another color, relative luminance, etc.
+ *
+ * @example
+ * ```ts
+ * new Color('#2949e5').lighten(0.5).toHex();    // '#89aaff'
+ * new Color('#2949e5').withAlpha(0.5).toRgba(); // 'rgba(41, 73, 229, 0.5)'
+ * new Color('#2949e5').contrast('#ffffff');     // 6.6
+ * ```
+ */
+declare class Color {
+  #private;
+  /**
+   * Read `input` into a color, returning `null` when it cannot be parsed.
+   */
+  static parse(input: ColorInput): Color | null;
+  static fromHsl(hsl: Hsl, alpha?: number): Color;
+  static fromLab(lab: Lab, alpha?: number): Color;
+  /** Red channel, 0–255. Kept unrounded so that chained operations don't accumulate error. */
+  readonly r: number;
+  /** Green channel, 0–255. Kept unrounded so that chained operations don't accumulate error. */
+  readonly g: number;
+  /** Blue channel, 0–255. Kept unrounded so that chained operations don't accumulate error. */
+  readonly b: number;
+  /** Alpha channel, 0–1. */
+  readonly a: number;
+  /**
+   * @param input - any supported color representation. Input that cannot be read as a
+   *   color resolves to brand blue rather than failing, so a malformed value degrades to
+   *   a usable color instead of interrupting a render.
+   */
+  constructor(input: ColorInput);
+  /** `#rrggbb`. Alpha is dropped — use {@link Color.toHexWithAlpha} to keep it. */
+  toHex(): string;
+  /** `#rrggbbaa`. */
+  toHexWithAlpha(): string;
+  /** `rgb(41, 73, 229)`. */
+  toRgb(): string;
+  /** `rgba(41, 73, 229, 0.5)`. */
+  toRgba(): string;
+  /** Rounded channels, ready to hand to another color library. */
+  toRgbaTuple(): RgbaTuple;
+  toHsl(): Hsl;
+  toLab(): Lab;
+  /** Hex when fully opaque, `rgba()` otherwise, so the alpha is never silently lost. */
+  toString(): string;
+  /**
+   * WCAG relative luminance, from 0 (black) to 1 (white). Alpha is ignored — luminance
+   * is only meaningful once a color has been composited onto a background.
+   */
+  luminance(): number;
+  /**
+   * WCAG contrast ratio against `other`, from 1 (identical) to 21 (black on white),
+   * reported to one decimal place.
+   *
+   * @see {@link colorContrastRatiosByShape} for the ratio each kind of content needs
+   */
+  contrast(other: ColorInput): number;
+  /**
+   * Raise perceptual lightness `ratio` (0–1) of the way to white, holding the hue steady.
+   *
+   * The hue is held in OKLCh, so a lightened color stays recognizably itself: a blue
+   * lightens to a paler blue instead of drifting purple, and a red that runs out of sRGB
+   * gives up colorfulness rather than sliding towards orange. That is the difference from
+   * {@link Color.tint}, which stirs white into the channels and lets the hue land where it
+   * may.
+   */
+  lighten(ratio: number): Color;
+  /** Lower perceptual lightness `ratio` (0–1) of the way to black, holding the hue steady. */
+  darken(ratio: number): Color;
+  /** Mix `ratio` (0–1) of white in. */
+  tint(ratio: number, mode?: InterpolationMode): Color;
+  /** Mix `ratio` (0–1) of black in. */
+  shade(ratio: number, mode?: InterpolationMode): Color;
+  /**
+   * Mix towards `other`, where `ratio` 0 keeps this color and 1 returns `other`. Alpha is
+   * always interpolated linearly, whichever `mode` the channels travel through.
+   */
+  blend(other: ColorInput, ratio?: number, mode?: InterpolationMode): Color;
+  /** Replace the alpha channel with `alpha` (0–1). */
+  withAlpha(alpha: number): Color;
+  /**
+   * Replace HSL lightness with `lightness` (0–100), leaving hue and saturation alone.
+   * Use this to hit an absolute lightness; use {@link Color.lighten} to step relative to
+   * where the color already is.
+   */
+  withLightness(lightness: number): Color;
+}
+//#endregion
+//#region src/types.d.ts
+/** Red, green and blue channels, each in the 0–255 range. */
+type RgbTuple = [red: number, green: number, blue: number];
+/** Red, green and blue channels (0–255) plus an alpha channel (0–1). */
+type RgbaTuple = [red: number, green: number, blue: number, alpha: number];
+/** RGB channels (0–255) with an optional alpha channel (0–1). */
+type ColorTuple = [red: number, green: number, blue: number, alpha?: number];
+/** Any object carrying RGB channels (0–255) and an optional alpha channel (0–1). */
+type RgbaObject = {
+  readonly a?: number;
+  readonly b: number;
+  readonly g: number;
+  readonly r: number;
+};
+/**
+ * Anything that can be read as a color:
+ *
+ * - a hex string — `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` (the `#` is optional)
+ * - an `rgb()`/`rgba()` string in either legacy comma syntax (`rgb(41, 73, 229)`) or
+ *   modern space syntax (`rgb(41 73 229 / 50%)`), with numbers or percentages
+ * - an `[r, g, b]` or `[r, g, b, a]` tuple
+ * - an object with `r`, `g`, `b` and optionally `a` — including another `Color`
+ *
+ * CSS named colors (`red`, `transparent`, …) are not supported.
+ */
+type ColorInput = Color | ColorTuple | RgbaObject | string;
+/** Hue (0–360), saturation (0–100) and lightness (0–100). */
+type Hsl = {
+  readonly hue: number;
+  readonly lightness: number;
+  readonly saturation: number;
+};
+/**
+ * CIELAB: perceptual lightness (0–100), plus the green–red (`a`) and blue–yellow (`b`)
+ * axes, which are unbounded but in practice fall within ±128.
+ */
+type Lab = {
+  readonly a: number;
+  readonly b: number;
+  readonly lightness: number;
+};
+/**
+ * The color space a blend interpolates through.
+ *
+ * - `oklch` — perceptually uniform, and the only mode that carries hue as a hue, so a
+ *   blend takes the short way round the wheel instead of through the grays in between
+ * - `lab` — perceptually uniform, interpolated on the rectangular axes
+ * - `lrgb` — linear RGB; avoids the muddy midpoints of naive RGB blending
+ * - `rgb` — naive channel-wise RGB; fastest, and what CSS `color-mix()` does in sRGB
+ */
+type InterpolationMode = "lab" | "lrgb" | "oklch" | "rgb";
+//#endregion
+//#region src/adjustColorForProperContrast.d.ts
+type AdjustColorForProperContrastOptions = {
+  /** What the foreground sits on. Never adjusted. */
+  readonly backgroundColor: ColorInput;
+  /** The color to nudge until it is legible. Returned untouched if it already is. */
+  readonly foregroundColor: ColorInput;
+  /** What the foreground is. Defaults to `paragraphText` (4.5:1). */
+  readonly shape?: ColorShape;
+};
+/**
+ * Walk `foregroundColor` towards white or black until it clears the contrast ratio
+ * `shape` requires against `backgroundColor`.
+ *
+ * Hue is pinned for the whole walk, so the result still reads as the color you passed in
+ * — a washed-out brand blue stays blue rather than drifting towards its neighbors. The
+ * direction is whichever gains contrast faster, reversing if it hits an extreme with the
+ * ratio still unmet. Text-grade ratios that can't be met either way settle on plain white
+ * or black, since at that point nothing else beats them.
+ *
+ * @example
+ * ```ts
+ * // Already legible, so nothing moves.
+ * adjustColorForProperContrast({
+ *   foregroundColor: '#2949e5',
+ *   backgroundColor: '#ffffff',
+ * }).toHex(); // '#2949e5'
+ *
+ * // A brand blue on itself, darkened until it separates.
+ * adjustColorForProperContrast({
+ *   foregroundColor: '#2949e5',
+ *   backgroundColor: '#2949e5',
+ *   shape: 'nonText',
+ * }).toHex();
+ * ```
+ */
+declare const adjustColorForProperContrast: ({ backgroundColor, foregroundColor, shape }: AdjustColorForProperContrastOptions) => Color;
+//#endregion
+//#region src/ColorScale.d.ts
+type ColorScaleOptions = {
+  /**
+   * Quantize the scale into bands instead of leaving it continuous: a count of equally sized
+   * classes across the domain, or explicit class breaks.
+   */
+  readonly classes?: number | number[];
+  /**
+   * Redistribute stops so that perceived lightness moves evenly from end to end. Worth
+   * turning on for any scale a reader is meant to rank by eye.
+   */
+  readonly correctLightness?: boolean;
+  /**
+   * The input range, `[0, 1]` by default. Two values set the ends; supply one value per
+   * color to pin each color to a position, or more than two to warp the scale.
+   */
+  readonly domain?: number[];
+  /** Bias the scale towards one end. Above 1 favors the start, below 1 the end. */
+  readonly gamma?: number;
+  /** The color space blends travel through. */
+  readonly mode?: InterpolationMode;
+  /** Trim `[start, end]` fractions off the scale, dropping its most extreme colors. */
+  readonly padding?: [number, number] | number;
+};
+/**
+ * A continuous scale between two or more colors — the chroma.js `scale` model, as an
+ * immutable class. Every configuration method returns a new scale, so a configured scale
+ * is safe to hold onto and share.
+ *
+ * @example
+ * ```ts
+ * const scale = new ColorScale(['#2949e5', '#ffffff']);
+ * scale.at(0.5).toHex();                             // the midpoint color
+ * scale.colors(5).map((color) => color.toHex());     // five evenly spaced colors
+ * scale.correctLightness().domain([0, 100]).at(72);  // perceptually even, read in %
+ * ```
+ */
+declare class ColorScale {
+  #private;
+  /**
+   * @param colors - the colors the scale runs through; a single color makes a flat scale
+   * @throws {TypeError} when `colors` is empty or `domain` has fewer than two values
+   */
+  constructor(colors: readonly ColorInput[], options?: ColorScaleOptions);
+  /** The color at `value`, read through the scale's domain, classes, gamma and padding. */
+  at(value: number): Color;
+  /** `count` colors spread evenly across the domain. */
+  colors(count: number): Color[];
+  mode(mode: InterpolationMode): ColorScale;
+  domain(domain: number[]): ColorScale;
+  gamma(gamma: number): ColorScale;
+  padding(padding: [number, number] | number): ColorScale;
+  correctLightness(correctLightness?: boolean): ColorScale;
+  classes(classes: number | number[]): ColorScale;
+}
+//#endregion
+//#region src/getBestColorForText.d.ts
+type BestColorForTextOptions = {
+  /** Always excluded from the result.*/
+  readonly backgroundColor: ColorInput;
+  /**
+   * Colors that are part of the palette but should not be considered as candidates.
+   * Useful in scenarios like the webinar pages color derivation logic, where we might include derived colors
+   * in the palette used by some fields, like `lowEmphasisTextColor`, but we want to exclude the derived colors
+   * from other fields, like `mainTextColor`.
+   */
+  readonly exclude?: readonly ColorInput[];
+  /**
+   * The colors to choose from. Black and white are included automatically, so an empty/absent palette
+   * still yields whichever of the two has best contrast against `backgroundColor`.
+   */
+  readonly palette?: readonly ColorInput[];
+  /** The type of text/shape that will use the resulting color. Defaults to `paragraphText` (4.5:1). */
+  readonly shape?: ColorShape;
+};
+/**
+ * Picks a color most suitable for a given text (or non-text) shape against the given background color.
+ * Accepts an optional color palette, but white and black are always included as options in addition to the palette.
+ * Also accepts a set of colors from the palette that should be excluded from consideration.
+ *
+ * @example
+ * ```ts
+ * getBestColorForText({ backgroundColor: '#2949e5' }).toHex(); // '#ffffff'
+ * ```
+ */
+declare const getBestColorForText: ({ backgroundColor, exclude, palette, shape }: BestColorForTextOptions) => Color;
+//#endregion
+export { type AdjustColorForProperContrastOptions, type BestColorForTextOptions, Color, type ColorInput, ColorScale, type ColorScaleOptions, type ColorShape, type ColorTuple, type Hsl, type InterpolationMode, type Lab, type RgbTuple, type RgbaObject, type RgbaTuple, adjustColorForProperContrast, colorContrastRatiosByShape, getBestColorForText };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/colorContrastRatiosByShape.ts"],"mappings":";;cAAa;EACX;EACA;EACA;EACA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/colorContrastRatiosByShape.ts","../src/Color.ts","../src/types.ts","../src/adjustColorForProperContrast.ts","../src/ColorScale.ts","../src/getBestColorForText.ts"],"mappings":";;cAAa;WACX;WACA;WACA;WACA;;;KAIU,0BAA0B;;;;;;;;;;;;;;cCyEzB;;;;;SAIJ,MAAM,OAAO,aAAa;SAK1B,QAAQ,KAAK,KAAK,iBAAY;SAK9B,QAAQ,KAAK,KAAK,iBAAY;;WAM5B;;WAGA;;WAGA;;WAGA;;;;;;EAOT,YAAY,OAAO;;EASnB;;EAKA;;EAKA;;EAKA;;EAKA,eAAe;EAIf,SAAS;EAIT,SAAS;;EAKT;;;;;EAQA;;;;;;;EAUA,SAAS,OAAO;;;;;;;;;;EAiBhB,QAAQ,gBAAgB;;EAKxB,OAAO,gBAAgB;;EAKvB,KAAK,eAAe,OAAM,oBAAiD;;EAK3E,MAAM,eAAe,OAAM,oBAAiD;;;;;EAQ5E,MACE,OAAO,YACP,gBACA,OAAM,oBACL;;EAwCH,UAAU,gBAAgB;;;;;;EAS1B,cAAc,oBAAoB;;;;;KC1QxB,YAAY,aAAa,eAAe;;KAGxC,aAAa,aAAa,eAAe,cAAc;;KAGvD,cAAc,aAAa,eAAe,cAAc;;KAGxD;WACD;WACA;WACA;WACA;;;;;;;;;;;;;KAcC,aAAa,QAAQ,aAAa;;KAGlC;WACD;WACA;WACA;;;;;;KAOC;WACD;WACA;WACA;;;;;;;;;;;KAYC;;;KC1BA;;WAED,iBAAiB;;WAGjB,iBAAiB;;WAGjB,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6BN,iCACX,iBACA,iBACA,SACC,wCAAsC;;;KCzD7B;;;;;WAKD;;;;;WAMA;;;;;WAMA;;WAGA;;WAGA,OAAO;;WAGP;;;;;;;;;;;;;;;cAgDE;;;;;;EAmBX,YAAY,iBAAiB,cAAc,UAAS;;EAkEpD,GAAG,gBAAgB;;EAQnB,OAAO,gBAAgB;EAmBvB,KAAK,MAAM,oBAAoB;EAI/B,OAAO,mBAAmB;EAI1B,MAAM,gBAAgB;EAItB,QAAQ,qCAAqC;EAI7C,iBAAiB,6BAA0B;EAI3C,QAAQ,6BAA6B;;;;KCtN3B;;WAED,iBAAiB;;;;;;;WAQjB,mBAAmB;;;;;WAMnB,mBAAmB;;WAGnB,QAAQ;;;;;;;;;;;;cAaN,wBACX,iBACA,SACA,SACA,SACC,4BAA0B"}