refactor: improve types (use csstypes) and type-coverage

Author: chrisrzhou

lib/create-theme-renderer.js

@@ -1,7 +1,7 @@
 import {isUnitlessProperty} from 'css-in-js-utils';
 import {createRenderer} from 'fela';
 import {render as renderToDom} from 'fela-dom';
-import enforceLonghands from 'fela-enforce-longhands';
+import enforceLonghands from 'fela-enforce-longhands'; // type-coverage:ignore-line
 import monolithic from 'fela-monolithic';
 import {createWebPreset} from 'fela-preset-web';
 import {isPlainObject, merge} from 'uinix-fp';
@@ -14,7 +14,6 @@ import {validateNamespacePrefix} from './utils/validate-namespace-prefix.js';
 
 /**
  * @typedef {import('./types.js').StyleObject} StyleObject
- * @typedef {import('./types.js').StyleProps} StyleProps
  * @typedef {import('./types.js').StyleRule} StyleRule
  * @typedef {import('./types.js').Theme} Theme
  * @typedef {import('./types.js').ThemeSpec} ThemeSpec
@@ -94,7 +93,6 @@ export const createThemeRenderer = (options = {}) => {
       ? merge({':root': cssVariables})(initialGlobalStyles)
       : initialGlobalStyles;
     for (const [selector, style] of Object.entries(globalStyles)) {
-      /** @type {StyleObject} */
       const processedStyle = plugins.reduce(
         (_acc, plugin) => plugin(style, 'STATIC', renderer, {theme}),
         style,
@@ -106,14 +104,14 @@ export const createThemeRenderer = (options = {}) => {
   /**
    * Renders style (themed or responsive).
    *
+   * @template P
    * @param {StyleObject} style
-   * @param {StyleProps} styleProps
+   * @param {P} [styleProps]
    * @returns {string} Rendered CSS classname
    */
   const renderStyle = (style, styleProps) => {
-    const styleRule = /** @type {StyleRule} */ (
-      isPlainObject(style) ? () => style : style
-    );
+    const styleRule = isPlainObject(style) ? () => style : style;
+    // @ts-ignore mask vendor internals
     return renderer.renderRule(styleRule, {...styleProps, theme});
   };
 

lib/types.js

@@ -1,52 +1,65 @@
-// Imports
 /**
- * @typedef {import('fela').IStyle} IStyle
- * @typedef {import('fela').TRule} TRule
+ * @typedef {import('csstype').Properties} CssTypeProperties
  */
 
-// Aliases
 /**
- * @typedef {string} CssProperty
- *    A valid CSS property e.g. "backgroundColor", "paddingLeft"
- *
+ * This module exports nothing.  It contains JSDoc typedefs.
+ */
+export {};
+
+// CSS
+/**
  * @typedef {string | number} CssValue
- *    A valid CSS value e.g. "4px", 4, "red".
+ *    A valid base CSS value e.g. "4px", 4, "red".
  *
- * @typedef {string} ThemeProperty
- *    A string key in the Theme object.
+ * @typedef {keyof CssTypeProperties} CssProperty
+ *    A valid CSS property e.g. "backgroundColor", "paddingLeft".
+ *
+ * @typedef {Record<string, CssValue>} CssVariables
+ *    Map of CSS variables to CSS values.
  */
 
 // Theme
 /**
- * @typedef {Record<ThemeProperty, CssProperty[]>} ThemeSpec
+ * @typedef {string} ThemeProperty
+ *    A theme property.
+ *
+ * @typedef {Record<ThemeProperty, Array<CssProperty>>} ThemeSpec
  *    A theme spec relates theme properties with CSS properties.
  *
  * @typedef {{
- *   [key: string]: ThemePropertyDefinition | CssValue
- * }} ThemePropertyDefinition
- *    A theme property definition is an arbitrarily nested interface that
- *    organizes resolved CSS values.
+ *   [key: string]: ThemeRecursive | CssValue
+ * }} ThemeRecursive
+ *    Recursive helper type.
  *
- * @typedef {Record<ThemeProperty, ThemePropertyDefinition>} Theme
- *    A theme relates theme properties with theme property definitions.
+ * @typedef {Record<ThemeProperty, ThemeRecursive>} Theme
+ *    A theme relates theme properties with CSS values (recursive).
  */
 
 // Style
 /**
- * @typedef {Record<string, any>} StyleObject
- *    A style object
+ * @typedef {CssValue | Array<CssValue>} StyleValue
+ *    Style values can be specified as either singleton or array of CSS values.
  *
- * @typedef {TRule} StyleRule
- *    A style rule (function)
+ * @typedef {CssTypeProperties & Record<string, StyleValue>} StyleCssProperties
+ *    Mapping of CSS properties to style values.
  *
- * @typedef {StyleObject | StyleRule} Style
- *    Either a style object or rule
+ * @typedef {{
+ *    [key: string]: StyleRecursiveAny | StyleRecursivePseudo | StyleCssProperties | StyleValue;
+ * }} StyleRecursiveAny;
+ *    Recursive helper type.
  *
- * @typedef {Object} StyleProps
- *    Generic object for style props
- */
-
-/**
- * This module exports nothing.  It contains JSDoc typedefs.
+ * @typedef {{
+ *    [key: string]: StyleRecursivePseudo | StyleRecursiveAny | StyleCssProperties | StyleValue;
+ * }} StyleRecursivePseudo;
+ *    Recursive helper type.
+ *
+ * @typedef {StyleCssProperties | StyleRecursivePseudo | StyleRecursiveAny} StyleObject
+ *    A style object.
+ *
+ * @typedef {<P>(props?: P) => StyleObject | null} StyleRule
+ *    A style rule is a function returning a style object or null.
+ *
+ * @typedef {StyleObject | StyleRule} Style
+ *    A style can be either a style object or a style rule.
  */
-export {};

lib/utils/coerce-esm.js

@@ -5,5 +5,5 @@
  * @param {X} x
  * @returns {X}
  */
-// @ts-ignore
+// @ts-ignore TODO: tighten
 export const coerceEsm = (x) => (x && x.default ? x.default : x);

lib/utils/plugin-responsive-value.js

@@ -1,4 +1,4 @@
-import felaResponsiveValue from 'fela-plugin-responsive-value';
+import felaResponsiveValue from 'fela-plugin-responsive-value'; // type-coverage:ignore-line
 
 import {coerceEsm} from './coerce-esm.js';
 

lib/utils/plugin-theme-value.js

@@ -1,17 +1,21 @@
 import {isPlainObject, props} from 'uinix-fp';
+
 import {createCssVariable} from './create-css-variable.js';
 
 /**
  * @typedef {import('fela').TPlugin} FelaPlugin
+ * @typedef {import('../types.js').CssValue} CssValue
+ * @typedef {import('../types.js').CssVariables} CssVariables
  * @typedef {import('../types.js').StyleObject} StyleObject
  * @typedef {import('../types.js').Theme} Theme
+ * @typedef {import('../types.js').ThemeProperty} ThemeProperty
  * @typedef {import('../types.js').ThemeSpec} ThemeSpec
  */
 
 /**
  * Customized Fela theme value plugin.
  * @param {Object} params
- * @param {Object} [params.cssVariables]
+ * @param {CssVariables} [params.cssVariables]
  * @param {string} [params.namespace]
  * @param {ThemeSpec} params.themeSpec
  * @returns {FelaPlugin}
@@ -22,16 +26,17 @@ export const themeValue =
     resolveThemeValues({
       cssVariables,
       namespace,
-      style,
-      // @ts-ignore
+      // @ts-ignore mask vendor internals
+      /** @type {StyleObject} */ style,
+      // @ts-ignore TODO: tighten
       theme: props.theme,
       themeSpec,
     });
 
 /**
  * Recursively resolve theme value
  * @param {Object} params
- * @param {Object} [params.cssVariables]
+ * @param {CssVariables} [params.cssVariables]
  * @param {string} [params.namespace='']
  * @param {StyleObject} params.style
  * @param {Theme} params.theme
@@ -57,6 +62,7 @@ const resolveThemeValues = ({
       if (cssVariable in cssVariables) {
         style[cssProperty] = `var(${cssVariable})`;
       } else {
+        // @ts-ignore TODO: tighten
         const isNegative = NEGATIVE_REGEXP.test(styleValue);
         if (isNegative) {
           styleValue = String(styleValue).split(NEGATIVE_REGEXP)[1].trim();
@@ -75,6 +81,7 @@ const resolveThemeValues = ({
       style[cssProperty] = resolveThemeValues({
         cssVariables,
         namespace,
+        // @ts-ignore TODO: tighten
         style: style[cssProperty],
         theme,
         themeSpec,
@@ -86,14 +93,23 @@ const resolveThemeValues = ({
 };
 
 /**
- * Creates a theme themeMapping from a theme spec
+ * Creates a theme mapping of theme property resolvers from a theme spec.
+ *
+ * @typedef ThemePropertyResolver
+ *    A map storing the themeProperty and resolve method.
+ * @property {(theme: Theme) => CssValue} resolve
+ *    Resolves CSS value given a theme.
+ * @property {ThemeProperty} themeProperty
+ *    A theme property.
+ *
+ * @typedef {Partial<Record<string, ThemePropertyResolver>>} ThemeMapping;
  *
  * @param {ThemeSpec} themeSpec
- * @returns {Object.<string, any>}
+ * @returns {ThemeMapping}
  */
 const createThemeMapping = (themeSpec) => {
-  /** @type {Object.<string, any>} */
-  const initialAcc = {};
+  /** @type {ThemeMapping} */
+  const themeMapping = {};
   return Object.entries(themeSpec).reduce(
     (acc, [themeProperty, cssProperties]) => {
       for (const cssProperty of cssProperties) {
@@ -105,6 +121,6 @@ const createThemeMapping = (themeSpec) => {
 
       return acc;
     },
-    initialAcc,
+    themeMapping,
   );
 };