@formant/ava 3.4.1-formant

package/lib/advisor/types.d.ts

@@ -0,0 +1,218 @@
+import { IntervalMark, RectMark, LineMark, PointMark, TextMark, CellMark, AreaMark } from '@antv/g2';
+import type { ColorSchemeType } from '@antv/color-schema';
+import type { SimulationType } from '@antv/smart-color';
+/** AVA 包内跨模块引用 */
+import type { Purpose, CkbConfig } from '../ckb';
+import type { Specification, Data } from '../common/types';
+/** Advisor 模块内引用 */
+import type { RuleConfig, BasicDataPropertyForAdvice, Preferences, RuleType } from './ruler/types';
+/**
+ * Advisor config type
+ */
+export type AdvisorConfig = {
+    ckbCfg?: CkbConfig;
+    ruleCfg?: RuleConfig;
+};
+/**
+ * Single chart-recommendation from advisor.
+ *
+ * @public
+ */
+export type Advice = {
+    /**
+     * Chart Type: should be standard CKB ChartID or any string id for customized chart.
+     */
+    type: string;
+    /**
+     * for the recommended chart, the specification information needs to be declared,
+     * which may be antv-spec or custom spec (for indicator cards and cross tabs)
+     */
+    spec: Specification | null;
+    /**
+     * A score summarized by rule scoring, which measures how well an individual chart
+     * is recommended in a recommendation scenario.
+     * The higher the score, the more recommended it is
+     */
+    score: number;
+    /**
+     * lint array: problems that remain after the recommendation, with possible solutions accordingly.
+     */
+    lint?: Lint[];
+};
+/**
+ * Describe a chart recommendation problem.
+ */
+export type Lint = {
+    /** rule type: 'HARD' | 'SOFT' | 'DESIGN'  */
+    type: RuleType;
+    /** rule id: standard ruleId or any string for custom rule */
+    id: string;
+    /** rule score */
+    score: number;
+    /** fix solution */
+    fix?: any;
+    /** docs: explanation */
+    docs?: any;
+};
+export type AdviseParams = ChartAdviseParams;
+export type ChartAdviseParams = {
+    /** input data to advise */
+    data: Data;
+    /** customized data props to advise */
+    dataProps?: Partial<BasicDataPropertyForAdvice>[];
+    /** data fields to focus, apply in `data` and `dataProps` */
+    fields?: string[];
+    /** SmartColor mode on/off */
+    smartColor?: boolean;
+    /** advising options such as purpose, layout preferences */
+    options?: AdvisorOptions;
+    /** smart color options */
+    colorOptions?: SmartColorOptions;
+};
+/**
+ * @public
+ */
+export type AdvisorOptions = {
+    /**
+     * analysis purpose, correspond to purpose of CKB, including
+     * Comparison
+     * Trend
+     * Distribution
+     * Rank
+     * Proportion
+     * Composition
+     */
+    purpose?: Purpose;
+    /**
+     * preference settings for landscape or portrait
+     */
+    preferences?: Preferences;
+    /**
+     * whether to apply design rules
+     */
+    refine?: boolean;
+    /**
+     * specify fields in the dataset
+     */
+    fields?: string[];
+    /**
+     * whether to show scoring process in console
+     * @deprecated since 3.0.0, use `exportLog` instead
+     */
+    showLog?: boolean;
+    /**
+     * custom theme
+     */
+    theme?: Theme;
+    /**
+     * only consider chart types with spec
+     */
+    requireSpec?: boolean;
+};
+export type Theme = {
+    /** hex string */
+    primaryColor?: string;
+};
+/**
+ * return type of color options for smart color
+ * @public
+ */
+export type SmartColorOptions = {
+    /**
+     *  hex string
+     */
+    themeColor?: string;
+    /**
+     * mode employed for color generation
+     */
+    colorSchemeType?: ColorSchemeType;
+    /**
+     * mode employed for color simulation
+     */
+    simulationType?: SimulationType;
+};
+export type AdviseResult = {
+    advices: Advice[];
+    log: ScoringResultForChartType[];
+};
+export type LintResult = {
+    lints: Lint[];
+    log: ScoringResultForRule[];
+};
+/**
+ * Log for scoring a single rule.
+ */
+export interface ScoringResultForRule {
+    phase: 'ADVISE' | 'LINT';
+    /**
+     * standard ChartRuleId or any string id for custom rule
+     */
+    ruleId: string;
+    /**
+     * scoring result for this rule, score = base * weight
+     */
+    score: number;
+    /**
+     * scoring from validator
+     */
+    base: number;
+    /**
+     * weight of this rule
+     */
+    weight: number;
+    /**
+     * type of this rule
+     */
+    ruleType: RuleType;
+}
+/**
+ * Summary log of checking all rules for a single chart type.
+ */
+export interface ScoringResultForChartType {
+    /**
+     * scoring for this chart type: standard ChartId or any string for custom chart
+     */
+    chartType: string;
+    /**
+     * final score
+     */
+    score: number;
+    /**
+     * whole records of scoring
+     */
+    log?: ScoringResultForRule[];
+}
+export * from './ruler/types';
+export interface LinterOptions {
+    purpose?: Purpose;
+    preferences?: Preferences;
+}
+export interface LintParams {
+    spec: Specification;
+    dataProps?: BasicDataPropertyForAdvice[];
+    options?: LinterOptions;
+}
+/** g2-spec 相关types */
+export type Mark = IntervalMark | RectMark | LineMark | PointMark | TextMark | CellMark | AreaMark;
+export type Primitive = number | string | boolean | Date;
+export type TabularData = Record<string, Primitive>[];
+export type Callback = (datum: Record<string, Primitive>, index: number, data: TabularData) => Primitive;
+export type DataType = 'quantitative' | 'categorical' | 'temporal';
+/** Encode 的值 */
+export type Encode = Primitive | Callback;
+/** Encode 的对象 */
+export type MarkEncode = Record<string, Encode>;
+/** 带有字段类型的 Encode 对象 */
+export type MarkEncodeWithType = Record<string, {
+    field: Encode;
+    type: DataType;
+}>;
+/** 原 G2 spec 去掉复杂 Encode 类型并添加简易版 Encode 类型 */
+export type G2ChartSpec = Omit<Mark, 'encode'> & {
+    encode: MarkEncode;
+};
+/** 原 G2 spec 去掉复杂 Encode 类型并添加简易版（带字段类型的） Encode 类型 */
+export type ChartSpecWithEncodeType = Omit<Mark, 'encode'> & {
+    encode: MarkEncodeWithType;
+};
+export type { Specification };

package/lib/advisor/types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./ruler/types"), exports);

package/lib/advisor/utils/clone.d.ts

@@ -0,0 +1,2 @@
+declare const cloneDeep: (obj: any) => any;
+export default cloneDeep;

package/lib/advisor/utils/clone.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var cloneDeep = function (obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    var result;
+    if (Array.isArray(obj)) {
+        result = [];
+        for (var i = 0, l = obj.length; i < l; i += 1) {
+            if (typeof obj[i] === 'object' && obj[i] != null) {
+                result[i] = cloneDeep(obj[i]);
+            }
+            else {
+                result[i] = obj[i];
+            }
+        }
+    }
+    else {
+        result = {};
+        var objKeys = Object.keys(obj);
+        for (var i = 0; i < objKeys.length; i += 1) {
+            var key = objKeys[i];
+            if (typeof obj[key] === 'object' && obj[key] != null) {
+                result[key] = cloneDeep(obj[key]);
+            }
+            else {
+                result[key] = obj[key];
+            }
+        }
+    }
+    return result;
+};
+exports.default = cloneDeep;

package/lib/advisor/utils/compare.d.ts

@@ -0,0 +1,3 @@
+import type { BasicDataPropertyForAdvice } from '../ruler/types';
+declare const compare: (f1: BasicDataPropertyForAdvice, f2: BasicDataPropertyForAdvice) => number;
+export default compare;

package/lib/advisor/utils/compare.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+var isNil_1 = tslib_1.__importDefault(require("./isNil"));
+var compare = function (f1, f2) {
+    if ((0, isNil_1.default)(f1.distinct) || (0, isNil_1.default)(f2.distinct)) {
+        if (f1.distinct < f2.distinct) {
+            return 1;
+        }
+        if (f1.distinct > f2.distinct) {
+            return -1;
+        }
+        return 0;
+    }
+    return 0;
+};
+exports.default = compare;

package/lib/advisor/utils/computeScore.d.ts

@@ -0,0 +1,7 @@
+import { Info, RuleModule } from '../ruler';
+import { CHART_IDS } from '../../ckb';
+import type { ScoringResultForRule } from '../types';
+import type { ChartKnowledgeBase } from '../../ckb';
+declare type ChartID = (typeof CHART_IDS)[number];
+declare const computeScore: (chartType: ChartID | string, chartWIKI: ChartKnowledgeBase, ruleBase: Record<string, RuleModule>, ruleType: 'HARD' | 'SOFT', info: Info, log: ScoringResultForRule[]) => number;
+export default computeScore;

package/lib/advisor/utils/computeScore.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+var constants_1 = require("../constants");
+var defaultWeights = constants_1.DEFAULT_RULE_WEIGHTS;
+var computeScore = function (chartType, chartWIKI, ruleBase, ruleType, info, log) {
+    // initial score is 1 for HARD rules and 0 for SOFT rules
+    var computedScore = 1;
+    Object.values(ruleBase)
+        .filter(function (r) {
+        var _a, _b, _c;
+        var weight = ((_a = r.option) === null || _a === void 0 ? void 0 : _a.weight) || defaultWeights[r.id] || 1;
+        var extra = (_b = r.option) === null || _b === void 0 ? void 0 : _b.extra;
+        return r.type === ruleType && r.trigger(tslib_1.__assign(tslib_1.__assign(tslib_1.__assign(tslib_1.__assign({}, info), { weight: weight }), extra), { chartType: chartType, chartWIKI: chartWIKI })) && !((_c = r.option) === null || _c === void 0 ? void 0 : _c.off);
+    })
+        .forEach(function (r) {
+        var _a, _b;
+        var weight = ((_a = r.option) === null || _a === void 0 ? void 0 : _a.weight) || defaultWeights[r.id] || 1;
+        var extra = (_b = r.option) === null || _b === void 0 ? void 0 : _b.extra;
+        var base = r.validator(tslib_1.__assign(tslib_1.__assign(tslib_1.__assign(tslib_1.__assign({}, info), { weight: weight }), extra), { chartType: chartType, chartWIKI: chartWIKI }));
+        var score = weight * base;
+        computedScore *= score;
+        log.push({ phase: 'ADVISE', ruleId: r.id, score: score, base: base, weight: weight, ruleType: ruleType });
+    });
+    return computedScore;
+};
+exports.default = computeScore;

package/lib/advisor/utils/deep-mix.d.ts

@@ -0,0 +1,2 @@
+declare const deepMix: (rst: any, ...args: any[]) => any;
+export default deepMix;

package/lib/advisor/utils/deep-mix.js

@@ -0,0 +1,78 @@
+"use strict";
+/*
+ * implementation of deepMix in antv/utils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var MAX_MIX_LEVEL = 5;
+var isObjectLike = function (value) {
+    /*
+     * isObjectLike({}) => true
+     * isObjectLike([1, 2, 3]) => true
+     * isObjectLike(Function) => false
+     * isObjectLike(null) => false
+     */
+    return typeof value === 'object' && value !== null;
+};
+var toString = {}.toString;
+var isType = function (value, type) { return toString.call(value) === "[object ".concat(type, "]"); };
+var isPlainObject = function (value) {
+    /*
+     * isObjectLike(new Foo) => false
+     * isObjectLike([1, 2, 3]) => false
+     * isObjectLike({ x: 0, y: 0 }) => true
+     * isObjectLike(Object.create(null)) => true
+     */
+    if (!isObjectLike(value) || !isType(value, 'Object')) {
+        return false;
+    }
+    if (Object.getPrototypeOf(value) === null) {
+        return true;
+    }
+    var proto = value;
+    while (Object.getPrototypeOf(proto) !== null) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    return Object.getPrototypeOf(value) === proto;
+};
+var isArray = function (value) {
+    return Array.isArray ? Array.isArray(value) : isType(value, 'Array');
+};
+function pDeepMix(inputDist, src, inputLevel, inputMaxLevel) {
+    var level = inputLevel || 0;
+    var maxLevel = inputMaxLevel || MAX_MIX_LEVEL;
+    var dist = inputDist;
+    Object.keys(src).forEach(function (key) {
+        if (Object.prototype.hasOwnProperty.call(src, key)) {
+            var value = src[key];
+            if (value !== null && isPlainObject(value)) {
+                if (!isPlainObject(dist[key])) {
+                    dist[key] = {};
+                }
+                if (level < maxLevel) {
+                    pDeepMix(dist[key], value, level + 1, maxLevel);
+                }
+                else {
+                    dist[key] = src[key];
+                }
+            }
+            else if (isArray(value)) {
+                dist[key] = [];
+                dist[key] = dist[key].concat(value);
+            }
+            else if (value !== undefined) {
+                dist[key] = value;
+            }
+        }
+    });
+}
+var deepMix = function (rst) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    for (var i = 0; i < args.length; i += 1) {
+        pDeepMix(rst, args[i]);
+    }
+    return rst;
+};
+exports.default = deepMix;

package/lib/advisor/utils/hasSubset.d.ts

@@ -0,0 +1 @@
+export declare function hasSubset(array1: any[], array2: any[]): boolean;

package/lib/advisor/utils/hasSubset.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSubset = void 0;
+function hasSubset(array1, array2) {
+    return array2.every(function (e) { return array1.includes(e); });
+}
+exports.hasSubset = hasSubset;

package/lib/advisor/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { default as deepMix } from './deep-mix';
+export { default as compare } from './compare';
+export { default as cloneDeep } from './clone';
+export { hasSubset } from './hasSubset';
+export { intersects } from './intersects';

package/lib/advisor/utils/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/*
+ * TODO @GuangMingYouBei: migrate utils into one unified folder of in ava.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.intersects = exports.hasSubset = exports.cloneDeep = exports.compare = exports.deepMix = void 0;
+var deep_mix_1 = require("./deep-mix");
+Object.defineProperty(exports, "deepMix", { enumerable: true, get: function () { return __importDefault(deep_mix_1).default; } });
+var compare_1 = require("./compare");
+Object.defineProperty(exports, "compare", { enumerable: true, get: function () { return __importDefault(compare_1).default; } });
+var clone_1 = require("./clone");
+Object.defineProperty(exports, "cloneDeep", { enumerable: true, get: function () { return __importDefault(clone_1).default; } });
+var hasSubset_1 = require("./hasSubset");
+Object.defineProperty(exports, "hasSubset", { enumerable: true, get: function () { return hasSubset_1.hasSubset; } });
+var intersects_1 = require("./intersects");
+Object.defineProperty(exports, "intersects", { enumerable: true, get: function () { return intersects_1.intersects; } });

package/lib/advisor/utils/inferDataType.d.ts

@@ -0,0 +1,6 @@
+import { ScaleTypes } from '@antv/g2';
+import { ChartSpecWithEncodeType, DataType, Encode, G2ChartSpec, TabularData } from '../types';
+/** 推断数据类型 */
+export declare function inferDataType(data: TabularData, encode: Encode, scale: ScaleTypes | undefined): DataType;
+/** 获取带有字段类型的 chartSpec */
+export declare function getSpecWithEncodeType(chartSpec: G2ChartSpec): ChartSpecWithEncodeType;

package/lib/advisor/utils/inferDataType.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSpecWithEncodeType = exports.inferDataType = void 0;
+var tslib_1 = require("tslib");
+var lodash_1 = require("lodash");
+function isQuantitative(d) {
+    return typeof d === 'number';
+}
+function isCategorical(d) {
+    return typeof d === 'string' || typeof d === 'boolean';
+}
+function isTemporal(d) {
+    return d instanceof Date;
+}
+function isField(data, encode) {
+    return typeof encode === 'string' && data.some(function (d) { return d[encode] !== undefined; });
+}
+function isTransform(encode) {
+    return typeof encode === 'function';
+}
+// @ts-ignore: constant - 常数比例尺 / identity - 恒等比例尺 对用户不透出，所以此处ts-ignore
+function scaleType2dataType(scaleType) {
+    switch (scaleType) {
+        case 'linear':
+        case 'log':
+        case 'pow':
+        case 'sqrt':
+        case 'qunatile':
+        case 'threshold':
+        case 'quantize':
+        case 'sequential':
+            return 'quantitative';
+        case 'time':
+            return 'temporal';
+        case 'ordinal':
+        case 'point':
+        case 'band':
+            return 'categorical';
+        default:
+            throw new Error("Unkonwn scale type: ".concat(scaleType, "."));
+    }
+}
+function values2dataType(values) {
+    if (values.some(isQuantitative))
+        return 'quantitative';
+    if (values.some(isCategorical))
+        return 'categorical';
+    if (values.some(isTemporal))
+        return 'temporal';
+    throw new Error("Unknown type: ".concat(typeof values[0]));
+}
+function columnOf(data, encode) {
+    if (isTransform(encode))
+        return data.map(encode);
+    if (isField(data, encode))
+        return data.map(function (d) { return d[encode]; });
+    return data.map(function () { return encode; });
+}
+/** 推断数据类型 */
+function inferDataType(data, encode, scale) {
+    if (scale !== undefined)
+        return scaleType2dataType(scale);
+    var values = columnOf(data, encode);
+    return values2dataType(values);
+}
+exports.inferDataType = inferDataType;
+/** 获取带有字段类型的 chartSpec */
+function getSpecWithEncodeType(chartSpec) {
+    var encode = chartSpec.encode, data = chartSpec.data, scale = chartSpec.scale;
+    var newEncode = (0, lodash_1.mapValues)(encode, function (value, key) {
+        return { field: value, type: inferDataType(data, value, scale === null || scale === void 0 ? void 0 : scale[key].type) };
+    });
+    return tslib_1.__assign(tslib_1.__assign({}, chartSpec), { encode: newEncode });
+}
+exports.getSpecWithEncodeType = getSpecWithEncodeType;

package/lib/advisor/utils/intersects.d.ts

@@ -0,0 +1 @@
+export declare function intersects(array1: any[], array2: any[]): boolean;

package/lib/advisor/utils/intersects.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.intersects = void 0;
+function intersects(array1, array2) {
+    return array2.some(function (e) { return array1.includes(e); });
+}
+exports.intersects = intersects;

package/lib/advisor/utils/isNil.d.ts

@@ -0,0 +1,2 @@
+declare const isNil: (input: any) => boolean;
+export default isNil;

package/lib/advisor/utils/isNil.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var isNil = function (input) {
+    return input === null;
+};
+exports.default = isNil;

package/lib/ckb/base.d.ts

@@ -0,0 +1,2 @@
+import type { PureChartKnowledgeBase } from './types';
+export declare const base: PureChartKnowledgeBase;