@udixio/theme 1.0.0-beta.8 → 1.0.0

package/src/material-color-utilities/htc.ts

@@ -0,0 +1,198 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * A color system built using CAM16 hue and chroma, and L* from
+ * L*a*b*.
+ *
+ * Using L* creates a link between the color system, contrast, and thus
+ * accessibility. Contrast ratio depends on relative luminance, or Y in the XYZ
+ * color space. L*, or perceptual luminance can be calculated from Y.
+ *
+ * Unlike Y, L* is linear to human perception, allowing trivial creation of
+ * accurate color tones.
+ *
+ * Unlike contrast ratio, measuring contrast in L* is linear, and simple to
+ * calculate. A difference of 40 in HCT tone guarantees a contrast ratio >= 3.0,
+ * and a difference of 50 guarantees a contrast ratio >= 4.5.
+ */
+
+import { Cam16, lstarFromArgb, lstarFromY, ViewingConditions } from '@material/material-color-utilities';
+import { HctSolver } from './hct_solver';
+
+/**
+ * HCT, hue, chroma, and tone. A color system that provides a perceptually
+ * accurate color measurement system that can also accurately render what colors
+ * will appear as in different lighting environments.
+ */
+export class Hct {
+  /**
+   * @param hue 0 <= hue < 360; invalid values are corrected.
+   * @param chroma 0 <= chroma < ?; Informally, colorfulness. The color
+   *     returned may be lower than the requested chroma. Chroma has a different
+   *     maximum for any given hue and tone.
+   * @param tone 0 <= tone <= 100; invalid values are corrected.
+   * @return HCT representation of a color in default viewing conditions.
+   */
+
+  internalHue: number;
+  internalChroma: number;
+  internalTone: number;
+
+  private constructor(private argb: number) {
+    const cam = Cam16.fromInt(argb);
+    this.internalHue = cam.hue;
+    this.internalChroma = cam.chroma;
+    this.internalTone = lstarFromArgb(argb);
+    this.argb = argb;
+  }
+
+  /**
+   * A number, in degrees, representing ex. red, orange, yellow, etc.
+   * Ranges from 0 <= hue < 360.
+   */
+  get hue(): number {
+    return this.internalHue;
+  }
+
+  /**
+   * @param newHue 0 <= newHue < 360; invalid values are corrected.
+   * Chroma may decrease because chroma has a different maximum for any given
+   * hue and tone.
+   */
+  set hue(newHue: number) {
+    this.setInternalState(
+      HctSolver.solveToInt(newHue, this.internalChroma, this.internalTone),
+    );
+  }
+
+  get chroma(): number {
+    return this.internalChroma;
+  }
+
+  /**
+   * @param newChroma 0 <= newChroma < ?
+   * Chroma may decrease because chroma has a different maximum for any given
+   * hue and tone.
+   */
+  set chroma(newChroma: number) {
+    this.setInternalState(
+      HctSolver.solveToInt(this.internalHue, newChroma, this.internalTone),
+    );
+  }
+
+  /** Lightness. Ranges from 0 to 100. */
+  get tone(): number {
+    return this.internalTone;
+  }
+
+  /**
+   * @param newTone 0 <= newTone <= 100; invalid valids are corrected.
+   * Chroma may decrease because chroma has a different maximum for any given
+   * hue and tone.
+   */
+  set tone(newTone: number) {
+    this.setInternalState(
+      HctSolver.solveToInt(this.internalHue, this.internalChroma, newTone),
+    );
+  }
+
+  static from(hue: number, chroma: number, tone: number) {
+    return new Hct(HctSolver.solveToInt(hue, chroma, tone));
+  }
+
+  /**
+   * @param argb ARGB representation of a color.
+   * @return HCT representation of a color in default viewing conditions
+   */
+  static fromInt(argb: number) {
+    return new Hct(argb);
+  }
+
+  static isBlue(hue: number): boolean {
+    return hue >= 250 && hue < 270;
+  }
+
+  static isYellow(hue: number): boolean {
+    return hue >= 105 && hue < 125;
+  }
+
+  static isCyan(hue: number): boolean {
+    return hue >= 170 && hue < 207;
+  }
+
+  toInt(): number {
+    return this.argb;
+  }
+
+  /** Sets a property of the Hct object. */
+  setValue(propertyName: string, value: number) {
+    (this as any)[propertyName] = value;
+  }
+
+  toString(): string {
+    return `HCT(${this.hue.toFixed(0)}, ${this.chroma.toFixed(0)}, ${this.tone.toFixed(
+      0,
+    )})`;
+  }
+
+  /**
+   * Translates a color into different [ViewingConditions].
+   *
+   * Colors change appearance. They look different with lights on versus off,
+   * the same color, as in hex code, on white looks different when on black.
+   * This is called color relativity, most famously explicated by Josef Albers
+   * in Interaction of Color.
+   *
+   * In color science, color appearance models can account for this and
+   * calculate the appearance of a color in different settings. HCT is based on
+   * CAM16, a color appearance model, and uses it to make these calculations.
+   *
+   * See [ViewingConditions.make] for parameters affecting color appearance.
+   */
+  inViewingConditions(vc: ViewingConditions): Hct {
+    // 1. Use CAM16 to find XYZ coordinates of color in specified VC.
+    const cam = Cam16.fromInt(this.toInt());
+    const viewedInVc = cam.xyzInViewingConditions(vc);
+
+    // 2. Create CAM16 of those XYZ coordinates in default VC.
+    const recastInVc = Cam16.fromXyzInViewingConditions(
+      viewedInVc[0],
+      viewedInVc[1],
+      viewedInVc[2],
+      ViewingConditions.make(),
+    );
+
+    // 3. Create HCT from:
+    // - CAM16 using default VC with XYZ coordinates in specified VC.
+    // - L* converted from Y in XYZ coordinates in specified VC.
+    const recastHct = Hct.from(
+      recastInVc.hue,
+      recastInVc.chroma,
+      lstarFromY(viewedInVc[1]),
+    );
+    return recastHct;
+  }
+
+  private setInternalState(argb: number) {
+    const cam = Cam16.fromInt(argb);
+    this.internalHue = cam.hue;
+    this.internalChroma = cam.chroma;
+    this.internalTone = lstarFromArgb(argb);
+    this.argb = argb;
+  }
+}

package/src/material-color-utilities/toneDeltaPair.ts

@@ -19,8 +19,21 @@ import { DynamicColor } from './dynamic_color';
 
 /**
  * Describes the different in tone between colors.
+ *
+ * nearer and farther are deprecated. Use DeltaConstraint instead.
+ */
+export type TonePolarity =
+  | 'darker'
+  | 'lighter'
+  | 'nearer'
+  | 'farther'
+  | 'relative_darker'
+  | 'relative_lighter';
+
+/**
+ * Describes how to fulfill a tone delta pair constraint.
  */
-export type TonePolarity = 'darker' | 'lighter' | 'nearer' | 'farther';
+export type DeltaConstraint = 'exact' | 'nearer' | 'farther';
 
 /**
  * Documents a constraint between two DynamicColors, in which their tones must
@@ -36,13 +49,14 @@ export class ToneDeltaPair {
    *
    * The polarity is an adjective that describes "A", compared to "B".
    *
-   * For instance, ToneDeltaPair(A, B, 15, 'darker', stayTogether) states that
-   * A's tone should be at least 15 darker than B's.
+   * For instance, ToneDeltaPair(A, B, 15, 'darker', 'exact') states that
+   * A's tone should be exactly 15 darker than B's.
    *
-   * 'nearer' and 'farther' describes closeness to the surface roles. For
-   * instance, ToneDeltaPair(A, B, 10, 'nearer', stayTogether) states that A
-   * should be 10 lighter than B in light mode, and 10 darker than B in dark
-   * mode.
+   * 'relative_darker' and 'relative_lighter' describes the tone adjustment
+   * relative to the surface color trend (white in light mode; black in dark
+   * mode). For instance, ToneDeltaPair(A, B, 10, 'relative_lighter',
+   * 'farther') states that A should be at least 10 lighter than B in light
+   * mode, and at least 10 darker than B in dark mode.
    *
    * @param roleA The first role in a pair.
    * @param roleB The second role in a pair.
@@ -50,8 +64,9 @@ export class ToneDeltaPair {
    * values have undefined behavior.
    * @param polarity The relative relation between tones of roleA and roleB,
    * as described above.
-   * @param stayTogether Whether these two roles should stay on the same side of
-   * the "awkward zone" (T50-59). This is necessary for certain cases where
+   * @param constraint How to fulfill the tone delta pair constraint.
+   * @param stayTogether Whether these two roles should stay on the same side
+   * of the "awkward zone" (T50-59). This is necessary for certain cases where
    * one role has two backgrounds.
    */
   constructor(
@@ -59,6 +74,9 @@ export class ToneDeltaPair {
     readonly roleB: DynamicColor,
     readonly delta: number,
     readonly polarity: TonePolarity,
-    readonly stayTogether: boolean
-  ) {}
+    readonly stayTogether: boolean,
+    readonly constraint?: DeltaConstraint,
+  ) {
+    this.constraint = constraint ?? 'exact';
+  }
 }

package/src/plugin/index.ts

@@ -0,0 +1,3 @@
+export * from './plugin.abstract';
+export * from './plugin.module';
+export * from './plugin.api';

package/src/plugin/plugin.abstract.ts

@@ -1,7 +1,48 @@
-import { AppService } from '../app.service';
+import { API } from '../API';
 
-export abstract class PluginAbstract {
-  static dependencies: (new () => PluginAbstract)[];
+export type PluginConstructor<Plugin extends PluginImplAbstract<any>> = new (
+  ...args: any
+) => Plugin;
 
-  protected constructor(protected appService: AppService) {}
+export abstract class PluginAbstract<
+  Plugin extends PluginImplAbstract<Options>,
+  Options extends object,
+> {
+  public abstract readonly dependencies: (new (
+    ...args: any
+  ) => PluginAbstract<any, any>)[];
+  public abstract readonly name: string;
+  public options: Options;
+  public abstract readonly pluginClass: PluginConstructor<Plugin>;
+  protected pluginInstance: Plugin | undefined;
+
+  constructor(options: Options) {
+    this.options = options;
+  }
+
+  public init(api: API) {
+    this.pluginInstance = new this.pluginClass(api, this.options);
+    this.pluginInstance.onInit?.();
+    return this;
+  }
+
+  public getInstance(): Plugin {
+    if (!this.pluginInstance) {
+      throw new Error(`Plugin ${this.name} is not initialized`);
+    }
+    return this.pluginInstance;
+  }
+}
+
+export abstract class PluginImplAbstract<Options extends object> {
+  constructor(
+    protected api: API,
+    protected options: Options,
+  ) {
+    this.onInit?.();
+  }
+
+  abstract onInit?(): void;
+
+  abstract onLoad?(): void;
 }

package/src/plugin/plugin.api.ts

@@ -0,0 +1,51 @@
+import { PluginAbstract } from './plugin.abstract';
+import { API } from '../API';
+
+export class PluginApi {
+  private plugins = new Map<string, PluginAbstract<any, any>>();
+
+  public addPlugin(plugin: PluginAbstract<any, any>) {
+    this.plugins.set(plugin.name, plugin);
+  }
+
+  public initPlugins(api: API) {
+    const plugins = new Map(this.plugins);
+
+    let size = 0;
+
+    this.plugins = new Map();
+
+    do {
+      size = plugins.size;
+      plugins.forEach((plugin, key) => {
+        const deps = plugin.dependencies.filter(
+          (dep) => !this.plugins.has(new dep().name),
+        );
+        if (deps.length === 0) {
+          this.plugins.set(plugin.name, plugin.init(api));
+          plugins.delete(key);
+        }
+      });
+    } while (plugins.size != 0 && plugins.size < size);
+
+    if (plugins.size > 0)
+      throw new Error(
+        "Some plugins couldn't be loaded due to missing dependencies: " +
+          Array.from(plugins.keys()),
+      );
+  }
+
+  public loadPlugins() {
+    this.plugins.forEach((plugin) => {
+      plugin.getInstance().onLoad?.();
+    });
+  }
+
+  public getPlugin<T extends PluginAbstract<any, any>>(
+    plugin: new (...args: any) => T,
+  ): T {
+    const pluginInstance = this.plugins.get(new plugin().name);
+    if (!pluginInstance) throw new Error(`Plugin ${plugin.name} not found`);
+    return pluginInstance as T;
+  }
+}

package/src/plugin/plugin.module.ts

@@ -1,7 +1,7 @@
 import { asClass } from 'awilix';
 import { Module } from '../app.container';
-import { PluginService } from './plugin.service';
+import { PluginApi } from './plugin.api';
 
 export const PluginModule: Module = {
-  pluginService: asClass(PluginService).singleton(),
+  pluginApi: asClass(PluginApi).singleton(),
 };

package/src/plugins/font/font.plugin.ts

@@ -0,0 +1,203 @@
+import { PluginAbstract, PluginImplAbstract } from '../../plugin';
+
+export enum FontFamily {
+  Expressive = 'expressive',
+  Neutral = 'neutral',
+}
+export type FontStyle = {
+  fontSize: number;
+  lineHeight: number;
+  fontWeight: number;
+  letterSpacing?: number;
+  fontFamily: FontFamily;
+};
+export type FontRole = 'display' | 'headline' | 'title' | 'label' | 'body';
+export type FontSize = 'large' | 'medium' | 'small';
+interface FontPluginOptions {
+  fontFamily?: {
+    expressive?: string[];
+    neutral?: string[];
+  };
+  fontStyles?: Partial<Record<FontRole, Record<FontSize, Partial<FontStyle>>>>;
+}
+
+export class FontPlugin extends PluginAbstract<
+  FontPluginImpl,
+  FontPluginOptions
+> {
+  dependencies = [];
+  name = 'font';
+  pluginClass = FontPluginImpl;
+}
+
+class FontPluginImpl extends PluginImplAbstract<FontPluginOptions> {
+  private _fontFamily: { expressive: string[]; neutral: string[] } | undefined;
+
+  get fontFamily(): { expressive: string[]; neutral: string[] } {
+    if (!this._fontFamily) throw new Error('Font family not initialized');
+    return this._fontFamily;
+  }
+
+  set fontFamily(
+    value: { expressive: string[]; neutral: string[] } | undefined
+  ) {
+    this._fontFamily = value;
+  }
+
+  private _fontStyles:
+    | Record<FontRole, Record<FontSize, FontStyle>>
+    | undefined;
+
+  get fontStyles(): Record<FontRole, Record<FontSize, FontStyle>> {
+    if (!this._fontStyles) throw new Error('Font styles not initialized');
+    return this._fontStyles;
+  }
+
+  set fontStyles(
+    value: Record<FontRole, Record<FontSize, FontStyle>> | undefined
+  ) {
+    this._fontStyles = value;
+  }
+
+  getFonts() {
+    return {
+      fontStyles: this.fontStyles,
+      fontFamily: this.fontFamily,
+    };
+  }
+
+  onInit(): void {
+    this.fontFamily = {
+      expressive: this.options?.fontFamily?.expressive ?? [
+        'Roboto',
+        'sans-serif',
+      ],
+      neutral: this.options?.fontFamily?.neutral ?? ['Roboto', 'sans-serif'],
+    };
+    this.fontStyles = {
+      display: {
+        large: {
+          fontWeight: 400,
+          fontSize: 3.5625,
+          lineHeight: 4,
+          letterSpacing: -0.015625,
+          fontFamily: FontFamily.Expressive,
+        },
+        medium: {
+          fontWeight: 400,
+          fontSize: 2.8125,
+          lineHeight: 3.25,
+          fontFamily: FontFamily.Expressive,
+        },
+        small: {
+          fontWeight: 400,
+          fontSize: 2.25,
+          lineHeight: 2.75,
+          fontFamily: FontFamily.Expressive,
+        },
+      },
+      headline: {
+        large: {
+          fontWeight: 400,
+          fontSize: 2,
+          lineHeight: 2.5,
+          fontFamily: FontFamily.Expressive,
+        },
+        medium: {
+          fontWeight: 400,
+          fontSize: 1.75,
+          lineHeight: 2.25,
+          fontFamily: FontFamily.Expressive,
+        },
+        small: {
+          fontWeight: 400,
+          fontSize: 1.5,
+          lineHeight: 2,
+          fontFamily: FontFamily.Expressive,
+        },
+      },
+      title: {
+        large: {
+          fontWeight: 400,
+          fontSize: 1.375,
+          lineHeight: 1.75,
+          fontFamily: FontFamily.Neutral,
+        },
+        medium: {
+          fontWeight: 500,
+          fontSize: 1,
+          lineHeight: 1.5,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.009375,
+        },
+        small: {
+          fontWeight: 500,
+          fontSize: 0.875,
+          lineHeight: 1.25,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.00625,
+        },
+      },
+      label: {
+        large: {
+          fontWeight: 500,
+          fontSize: 0.875,
+          lineHeight: 1.25,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.00625,
+        },
+        medium: {
+          fontWeight: 500,
+          fontSize: 0.75,
+          lineHeight: 1,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.03125,
+        },
+        small: {
+          fontWeight: 500,
+          fontSize: 0.6875,
+          lineHeight: 1,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.03125,
+        },
+      },
+      body: {
+        large: {
+          fontWeight: 400,
+          fontSize: 1,
+          lineHeight: 1.5625,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.03125,
+        },
+        medium: {
+          fontWeight: 400,
+          fontSize: 0.875,
+          lineHeight: 1.25,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.015625,
+        },
+        small: {
+          fontWeight: 400,
+          fontSize: 0.75,
+          lineHeight: 1,
+          fontFamily: FontFamily.Neutral,
+          letterSpacing: 0.025,
+        },
+      },
+    };
+
+    if (this.options && this.options.fontStyles)
+      Object.entries(this.options.fontStyles).forEach(([key, fontParam]) => {
+        const fontRole: FontRole = key as FontRole;
+        Object.entries(fontParam).forEach(([size, fontStyle]) => {
+          const fontSize: FontSize = size as FontSize;
+          if (fontStyle) {
+            this.fontStyles[fontRole][fontSize] = {
+              ...this.fontStyles[fontRole][fontSize],
+              ...fontStyle,
+            };
+          }
+        });
+      });
+  }
+}

package/src/plugins/font/index.ts

@@ -0,0 +1 @@
+export * from './font.plugin';

package/src/plugins/index.ts

@@ -0,0 +1 @@
+export * from './font';

package/src/theme/index.ts

@@ -1,4 +1,7 @@
-export * from './entities';
-export * from './models';
-export * from './services';
 export * from './theme.module';
+export * from './variants';
+export * from './scheme.manager';
+export * from './scheme';
+export * from './theme.api';
+export * from './variant';
+export * from './variant.manager';

package/src/theme/{services/scheme.service.ts → scheme.manager.ts}

@@ -1,9 +1,6 @@
-import { SchemeEntity, SchemeOptions } from '../entities/scheme.entity';
-import {
-  argbFromHex,
-  Hct,
-  TonalPalette,
-} from '@material/material-color-utilities';
+import { Scheme, SchemeOptions } from './scheme';
+import { argbFromHex, TonalPalette } from '@material/material-color-utilities';
+import { Hct } from '../material-color-utilities/htc';
 
 export type SchemeServiceOptions = Omit<
   SchemeOptions,
@@ -12,15 +9,31 @@ export type SchemeServiceOptions = Omit<
   sourcesColorHex: Record<string, string> & { primary?: string };
   palettes: Record<
     string,
-    {
-      sourceColorkey?: string;
-      tonalPalette: (sourceColorHct: Hct) => TonalPalette;
-    }
+    | {
+        sourceColorkey: string;
+        tonalPalette: CustomPaletteFunction;
+      }
+    | {
+        sourceColorkey?: never;
+        tonalPalette: PaletteFunction;
+      }
   >;
 };
 
-export class SchemeService {
-  private schemeEntity?: SchemeEntity;
+type PaletteFunctionArgs = {
+  isDark: boolean;
+  sourceColorHct: Hct;
+};
+
+export type PaletteFunction = (args: PaletteFunctionArgs) => TonalPalette;
+export type CustomPaletteFunction = (
+  args: PaletteFunctionArgs & {
+    colorHct: Hct;
+  },
+) => TonalPalette;
+
+export class SchemeManager {
+  private schemeEntity?: Scheme;
   private options?: SchemeServiceOptions;
 
   createOrUpdate(options: Partial<SchemeServiceOptions>) {
@@ -53,25 +66,32 @@ export class SchemeService {
       { sourceColorkey, tonalPalette: paletteFunction },
     ] of Object.entries(this.options.palettes)) {
       let palette: TonalPalette;
-      if (!sourceColorkey) {
-        palette = paletteFunction(sourceColorHct);
+      if (typeof sourceColorkey != 'string') {
+        palette = paletteFunction({
+          sourceColorHct: sourceColorHct,
+          isDark: options.isDark ?? false,
+        });
       } else {
         const sourceColorArgb = argbFromHex(
-          this.options.sourcesColorHex[sourceColorkey]
+          this.options.sourcesColorHex[sourceColorkey],
         );
-        const sourceColorHct: Hct = Hct.fromInt(sourceColorArgb);
-        palette = paletteFunction(sourceColorHct);
+        const colorHct: Hct = Hct.fromInt(sourceColorArgb);
+        palette = paletteFunction({
+          sourceColorHct: sourceColorHct,
+          colorHct: colorHct,
+          isDark: options.isDark ?? false,
+        });
       }
       palettes.set(key, palette);
     }
-    this.schemeEntity = new SchemeEntity({
+    this.schemeEntity = new Scheme({
       ...this.options,
       palettes: palettes,
       sourceColorArgb: sourceColorArgb,
     });
   }
 
-  get(): SchemeEntity {
+  get(): Scheme {
     if (!this.schemeEntity) {
       throw new Error('Scheme is not created');
     }