@formant/ava 3.4.1-formant

package/lib/advisor/ruler/rules/landscape-or-portrait.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.landscapeOrPortrait = void 0;
+var constants_1 = require("./constants");
+var applyChartTypes = [
+    'bar_chart',
+    'grouped_bar_chart',
+    'stacked_bar_chart',
+    'percent_stacked_bar_chart',
+    'column_chart',
+    'grouped_column_chart',
+    'stacked_column_chart',
+    'percent_stacked_column_chart',
+];
+function hasCanvasLayout(_a) {
+    var chartType = _a.chartType, dataProps = _a.dataProps, preferences = _a.preferences;
+    return !!(dataProps && chartType && preferences && preferences.canvasLayout);
+}
+exports.landscapeOrPortrait = {
+    id: 'landscape-or-portrait',
+    type: 'SOFT',
+    docs: {
+        lintText: 'Recommend column charts for landscape layout and bar charts for portrait layout.',
+    },
+    trigger: function (info) {
+        return applyChartTypes.includes(info.chartType) && hasCanvasLayout(info);
+    },
+    validator: function (args) {
+        var result = 1;
+        var chartType = args.chartType, preferences = args.preferences;
+        if (hasCanvasLayout(args)) {
+            if (preferences.canvasLayout === 'portrait' &&
+                ['bar_chart', 'grouped_bar_chart', 'stacked_bar_chart', 'percent_stacked_bar_chart'].includes(chartType)) {
+                result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5;
+            }
+            else if (preferences.canvasLayout === 'landscape' &&
+                ['column_chart', 'grouped_column_chart', 'stacked_column_chart', 'percent_stacked_column_chart'].includes(chartType)) {
+                result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5;
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/limit-series.d.ts

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

package/lib/advisor/ruler/rules/limit-series.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.limitSeries = void 0;
+var utils_1 = require("../../utils");
+var utils_2 = require("../utils");
+var constants_1 = require("./constants");
+function hasSeriesField(dataProps) {
+    var nominalOrOrdinalFields = dataProps.filter(function (field) {
+        return (0, utils_1.intersects)(field.levelOfMeasurements, ['Nominal', 'Ordinal']);
+    });
+    return nominalOrOrdinalFields.length >= 2;
+}
+/*
+只有 heatmap 能映射两个 维值非常多的 字段，因为对于 其他图表，如柱状图来说，第二个维度字段 就要映射成 颜色了。而颜色不适合映射特别多的维度。
+所以，在有 两个 维度字段的时候，在两个维度的维值都很多的情况下，要给 heatmap 加分，给其他图表减分。
+ */
+exports.limitSeries = {
+    id: 'limit-series',
+    type: 'SOFT',
+    docs: {
+        lintText: 'Avoid too many values in one series.',
+    },
+    trigger: function (_a) {
+        var dataProps = _a.dataProps;
+        return hasSeriesField(dataProps);
+    },
+    validator: function (args) {
+        var result = 1;
+        var dataProps = args.dataProps, chartType = args.chartType;
+        if (dataProps) {
+            var nominalOrOrdinalFields = dataProps.filter(function (field) {
+                return (0, utils_1.intersects)(field.levelOfMeasurements, ['Nominal', 'Ordinal']);
+            });
+            if (nominalOrOrdinalFields.length >= 2) {
+                var sortedFields = nominalOrOrdinalFields.sort(utils_2.compare);
+                var f = sortedFields[1];
+                if (f.distinct) {
+                    result = f.distinct > constants_1.MAX_SOFT_RULE_COEFFICIENT ? 1 / constants_1.MAX_SOFT_RULE_COEFFICIENT : 1 / f.distinct;
+                    if (f.distinct > 6 && chartType === 'heatmap') {
+                        result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5;
+                    }
+                    else if (chartType === 'heatmap') {
+                        result = 1;
+                    }
+                }
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/line-field-time-ordinal.d.ts

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

package/lib/advisor/ruler/rules/line-field-time-ordinal.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineFieldTimeOrdinal = void 0;
+var utils_1 = require("../../utils");
+var constants_1 = require("./constants");
+var applyChartTypes = ['line_chart', 'area_chart', 'stacked_area_chart', 'percent_stacked_area_chart'];
+exports.lineFieldTimeOrdinal = {
+    id: 'line-field-time-ordinal',
+    type: 'SOFT',
+    docs: {
+        lintText: 'Data containing time or ordinal fields are suitable for line or area charts.',
+    },
+    trigger: function (_a) {
+        var chartType = _a.chartType;
+        return applyChartTypes.includes(chartType);
+    },
+    validator: function (args) {
+        var result = 1;
+        var dataProps = args.dataProps;
+        if (dataProps) {
+            var field4TimeOrOrdinal = dataProps.find(function (field) { return (0, utils_1.intersects)(field.levelOfMeasurements, ['Ordinal', 'Time']); });
+            if (field4TimeOrOrdinal) {
+                result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5;
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/no-redundant-field.d.ts

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

package/lib/advisor/ruler/rules/no-redundant-field.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noRedundantField = void 0;
+exports.noRedundantField = {
+    id: 'no-redundant-field',
+    type: 'HARD',
+    docs: {
+        lintText: 'No redundant field.',
+    },
+    trigger: function () {
+        return true;
+    },
+    validator: function (args) {
+        var result = 0;
+        var dataProps = args.dataProps, chartType = args.chartType, chartWIKI = args.chartWIKI;
+        if (dataProps && chartType && chartWIKI[chartType]) {
+            var dataPres = chartWIKI[chartType].dataPres || [];
+            var maxFieldQty = dataPres
+                .map(function (e) {
+                if (e.maxQty === '*') {
+                    return 99;
+                }
+                return e.maxQty;
+            })
+                .reduce(function (acc, cv) { return acc + cv; });
+            if (dataProps.length) {
+                var fieldQty = dataProps.length;
+                if (fieldQty <= maxFieldQty) {
+                    result = 1;
+                }
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/nominal-enum-combinatorial.d.ts

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

package/lib/advisor/ruler/rules/nominal-enum-combinatorial.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nominalEnumCombinatorial = void 0;
+var utils_1 = require("../../utils");
+var utils_2 = require("../utils");
+var constants_1 = require("./constants");
+var applyChartTypes = [
+    'bar_chart',
+    'column_chart',
+    'grouped_bar_chart',
+    'grouped_column_chart',
+    'stacked_bar_chart',
+    'stacked_column_chart',
+];
+function getNominalFields(dataProps) {
+    return dataProps.filter(function (field) { return (0, utils_1.hasSubset)(field.levelOfMeasurements, ['Nominal']); });
+}
+exports.nominalEnumCombinatorial = {
+    id: 'nominal-enum-combinatorial',
+    type: 'SOFT',
+    docs: {
+        lintText: 'Single (Basic) and Multi (Stacked, Grouped,...) charts should be optimized recommended by nominal enums combinatorial numbers.',
+    },
+    trigger: function (_a) {
+        var chartType = _a.chartType, dataProps = _a.dataProps;
+        return (applyChartTypes.includes(chartType) && getNominalFields(dataProps).length >= 2);
+    },
+    validator: function (args) {
+        var result = 1;
+        var dataProps = args.dataProps, chartType = args.chartType;
+        if (dataProps) {
+            var nominalFields = getNominalFields(dataProps);
+            if (nominalFields.length >= 2) {
+                var sortedNominals = nominalFields.sort(utils_2.compare);
+                var f1 = sortedNominals[0];
+                var f2 = sortedNominals[1];
+                if (f1.distinct === f1.count) {
+                    if (['bar_chart', 'column_chart'].includes(chartType)) {
+                        result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5;
+                    }
+                }
+                if (f1.count && f1.distinct && f2.distinct && f1.count > f1.distinct) {
+                    var typeOptions = [
+                        'grouped_bar_chart',
+                        'grouped_column_chart',
+                        'stacked_bar_chart',
+                        'stacked_column_chart',
+                    ];
+                    if (typeOptions.includes(chartType)) {
+                        result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5;
+                    }
+                }
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/purpose-check.d.ts

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

package/lib/advisor/ruler/rules/purpose-check.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.purposeCheck = void 0;
+exports.purposeCheck = {
+    id: 'purpose-check',
+    type: 'HARD',
+    docs: {
+        lintText: 'Choose chart types that satisfy the purpose, if purpose is defined.',
+    },
+    trigger: function () {
+        return true;
+    },
+    validator: function (args) {
+        var result = 0;
+        var chartType = args.chartType, purpose = args.purpose, chartWIKI = args.chartWIKI;
+        // if purpose is not defined
+        if (!purpose) {
+            result = 1;
+            return result;
+        }
+        if (chartType && chartWIKI[chartType] && purpose) {
+            var purp = chartWIKI[chartType].purpose || '';
+            if (purp.includes(purpose)) {
+                result = 1;
+                return result;
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/series-qty-limit.d.ts

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

package/lib/advisor/ruler/rules/series-qty-limit.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seriesQtyLimit = void 0;
+var utils_1 = require("../../utils");
+var constants_1 = require("./constants");
+var applyChartTypes = ['pie_chart', 'donut_chart', 'radar_chart', 'rose_chart'];
+exports.seriesQtyLimit = {
+    id: 'series-qty-limit',
+    type: 'SOFT',
+    docs: {
+        lintText: 'Some charts should has at most N values for the series.',
+    },
+    trigger: function (_a) {
+        var chartType = _a.chartType;
+        return applyChartTypes.includes(chartType);
+    },
+    validator: function (args) {
+        var result = 1;
+        var dataProps = args.dataProps, chartType = args.chartType;
+        var limit = args.limit;
+        if (!Number.isInteger(limit) || limit <= 0) {
+            limit = 6;
+            if (chartType === 'pie_chart' || chartType === 'donut_chart' || chartType === 'rose_chart')
+                limit = 6;
+            if (chartType === 'radar_chart')
+                limit = 8;
+        }
+        if (dataProps) {
+            var field4Series = dataProps.find(function (field) { return (0, utils_1.hasSubset)(field.levelOfMeasurements, ['Nominal']); });
+            var seriesQty = field4Series && field4Series.count ? field4Series.count : 0;
+            if (seriesQty >= 2 && seriesQty <= limit) {
+                result = constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5 + 2 / seriesQty;
+            }
+        }
+        return result;
+    },
+};

package/lib/advisor/ruler/rules/x-axis-line-fading.d.ts

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

package/lib/advisor/ruler/rules/x-axis-line-fading.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.xAxisLineFading = void 0;
+var inferDataType_1 = require("../../utils/inferDataType");
+var constants_1 = require("./constants");
+var applyChartTypes = ['line_chart'];
+exports.xAxisLineFading = {
+    id: 'x-axis-line-fading',
+    type: 'DESIGN',
+    docs: {
+        // FIXME formal description
+        lintText: 'Adjust axis to make it prettier',
+    },
+    trigger: function (_a) {
+        var chartType = _a.chartType;
+        return applyChartTypes.includes(chartType);
+    },
+    optimizer: function (dataProps, chartSpec) {
+        var _a;
+        var specWithEncodeType = (0, inferDataType_1.getSpecWithEncodeType)(chartSpec);
+        var encode = specWithEncodeType.encode;
+        if (encode && ((_a = encode.y) === null || _a === void 0 ? void 0 : _a.type) === 'quantitative') {
+            var fieldInfo = dataProps.find(function (item) { var _a; return item.name === ((_a = encode.y) === null || _a === void 0 ? void 0 : _a.field); });
+            if (fieldInfo) {
+                var range = fieldInfo.maximum - fieldInfo.minimum;
+                if (fieldInfo.minimum && fieldInfo.maximum && range < (fieldInfo.maximum * 2) / 3) {
+                    var yScaleMin = Math.floor(fieldInfo.minimum - range / (constants_1.MAX_SOFT_RULE_COEFFICIENT * 0.5));
+                    return {
+                        axis: {
+                            x: { tick: false },
+                        },
+                        scale: {
+                            y: {
+                                domainMin: yScaleMin > 0 ? yScaleMin : 0,
+                            },
+                        },
+                        clip: true,
+                    };
+                }
+            }
+        }
+        return {};
+    },
+};

package/lib/advisor/ruler/types.d.ts

@@ -0,0 +1,125 @@
+import type { FieldInfo } from '../../data';
+import type { LevelOfMeasurement, ChartKnowledgeBase } from '../../ckb';
+import type { Specification } from '../../common/types';
+/**
+ * Type of different rules.
+ *
+ * @public
+ */
+export type RuleType = 'HARD' | 'SOFT' | 'DESIGN';
+/**
+ * this minimum subset of pipeline/DataProperty, make pipeline can start with step2(dataPropsToAdvice)
+ * @public
+ */
+export interface BasicDataPropertyForAdvice {
+    /** field name */
+    readonly name?: string;
+    /** LevelOfMeasurement */
+    readonly levelOfMeasurements?: LevelOfMeasurement[];
+    /** used for split column xy series */
+    readonly rawData: any[];
+    /** required types in  FieldInfo */
+    readonly recommendation: FieldInfo['recommendation'];
+    readonly type: FieldInfo['type'];
+    readonly distinct?: number;
+    readonly count?: number;
+    readonly sum?: number;
+    readonly maximum?: any;
+    readonly minimum?: any;
+    readonly missing?: number;
+    [key: string]: any;
+}
+/**
+ * 偏好选项：横向布局 - landscape | 纵向布局 - portrait
+ * @public
+ */
+export interface Preferences {
+    canvasLayout: 'landscape' | 'portrait';
+}
+/**
+ * @public
+ */
+export interface Info {
+    chartType?: string;
+    chartWIKI?: ChartKnowledgeBase;
+    dataProps: BasicDataPropertyForAdvice[] | BasicDataPropertyForAdvice;
+    purpose?: string;
+    preferences?: Preferences;
+    customWeight?: number;
+    [key: string]: any;
+}
+/**
+ * @public
+ */
+export type Validator = (args: Info) => number | boolean;
+export type Trigger = (args: Info) => boolean;
+export type Optimizer = (dataProps: BasicDataPropertyForAdvice[] | BasicDataPropertyForAdvice, chartSpec: Specification) => object;
+/**
+ * @public
+ */
+export interface ChartRuleConfig {
+    /**
+     * customized weight for the rule
+     */
+    weight?: number;
+    /**
+     * whether to ignore the rule
+     */
+    off?: boolean;
+    /**
+     * user customized parameters of Validator
+     */
+    extra?: Record<string, any>;
+}
+/**
+ * @public
+ */
+export type ChartRuleConfigMap = Record<string, ChartRuleConfig>;
+/**
+ * @public
+ */
+export type Docs = {
+    lintText?: string;
+    detailedText?: string;
+    moreLink?: string;
+    [key: string]: any;
+};
+type DefaultRuleModule = {
+    id: string;
+    docs: Docs;
+    trigger: Trigger;
+    option?: ChartRuleConfig;
+};
+export type ChartRuleModule = DefaultRuleModule & {
+    type: 'HARD' | 'SOFT';
+    validator: Validator;
+};
+export type DesignRuleModule = DefaultRuleModule & {
+    type: 'DESIGN';
+    optimizer: Optimizer;
+};
+export type RuleModule = ChartRuleModule | DesignRuleModule;
+/**
+ * rule config
+ *
+ * @public
+ */
+export type RuleConfig = {
+    /**
+     * include: should contain standard ChartRuleID, or any string id for custom rule.
+     */
+    include?: string[];
+    /**
+     * exclude: should contain standard ChartRuleID, or any string id for custom rule.
+     */
+    exclude?: string[];
+    /**
+     * customized rule instance
+     */
+    custom?: Record<string, RuleModule>;
+    /**
+     * config for rules
+     */
+    options?: ChartRuleConfigMap;
+};
+export {};

package/lib/advisor/ruler/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,10 @@
+import { CHART_IDS } from '../../ckb';
+import type { ScoringResultForRule } from '../types';
+import type { ChartKnowledge, ChartKnowledgeBase } from '../../ckb';
+import type { BasicDataPropertyForAdvice, Info, RuleModule } from './types';
+export declare function compare(f1: any, f2: any): 0 | 1 | -1;
+export declare function verifyDataProps(dataPre: ChartKnowledge['dataPres'][number], dataProps: BasicDataPropertyForAdvice[]): boolean;
+export declare function isUndefined(value: any): boolean;
+declare type ChartID = (typeof CHART_IDS)[number];
+export declare const computeScore: (chartType: ChartID | string, chartWIKI: ChartKnowledgeBase, ruleBase: Record<string, RuleModule>, ruleType: 'HARD' | 'SOFT', info: Info, log: ScoringResultForRule[]) => number;
+export {};

package/lib/advisor/ruler/utils.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeScore = exports.isUndefined = exports.verifyDataProps = exports.compare = void 0;
+var tslib_1 = require("tslib");
+var utils_1 = require("../utils");
+var constants_1 = require("../constants");
+function compare(f1, f2) {
+    if (f1.distinct < f2.distinct) {
+        return 1;
+    }
+    if (f1.distinct > f2.distinct) {
+        return -1;
+    }
+    return 0;
+}
+exports.compare = compare;
+function verifyDataProps(dataPre, dataProps) {
+    var fieldsLOMs = dataProps.map(function (info) {
+        return info.levelOfMeasurements;
+    });
+    if (fieldsLOMs) {
+        var lomCount_1 = 0;
+        fieldsLOMs.forEach(function (fieldLOM) {
+            if (fieldLOM && (0, utils_1.intersects)(fieldLOM, dataPre.fieldConditions)) {
+                lomCount_1 += 1;
+            }
+        });
+        if (lomCount_1 >= dataPre.minQty && (lomCount_1 <= dataPre.maxQty || dataPre.maxQty === '*')) {
+            return true;
+        }
+    }
+    return false;
+}
+exports.verifyDataProps = verifyDataProps;
+function isUndefined(value) {
+    return value === undefined;
+}
+exports.isUndefined = isUndefined;
+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.computeScore = computeScore;