dashtaste 0.0.0-stage → 0.0.2

package/dist/rules/dt018-glow.js

@@ -0,0 +1,27 @@
+import { walk, rule, charts } from './helpers.js';
+import { rgb } from '../color.js';
+/** Coloured CSS shadows with blur at least 12px, or chart shadowBlur at least 10, create glow. */
+export const dt018 = rule(18, 'glow', 'warn', 'Coloured CSS shadows with blur at least 12px, or chart shadowBlur at least 10, create glow.', 'remove glow and use hairline borders', function check(facts, context, emit) {
+    for (const entry of facts.shadows ?? []) {
+        const value = entry.boxShadow + ' ' + entry.textShadow;
+        const chunks = value.split(/,(?![^()]*\))/);
+        if (chunks.some((item) => {
+            const nums = [
+                ...item.replace(/rgba?\([^)]*\)|#[\da-f]+/gi, '').matchAll(/(-?[\d.]+)px/g),
+            ].map((m) => +m[1]);
+            const lineColor = item.match(/rgba?\([^)]*\)|#[\da-f]+/i)?.[0];
+            const channels = lineColor ? rgb(lineColor) : undefined;
+            return nums[2] >= 12 && channels && Math.max(...channels) - Math.min(...channels) > 0.05;
+        }))
+            emit(entry.selector);
+    }
+    charts(facts, (option, path) => {
+        let found = false;
+        walk(option, (key, value) => {
+            if (key === 'shadowBlur' && typeof value === 'number' && value >= 10)
+                found = true;
+        });
+        if (found)
+            emit(path);
+    });
+});

package/dist/rules/dt019-kpi-overload.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../types.js';
+/** More than 6 global or 8 cn KPI tiles weakens priority. */
+export declare const dt019: Rule;

package/dist/rules/dt019-kpi-overload.js

@@ -0,0 +1,7 @@
+import { packs } from '../packs/index.js';
+import { rule } from './helpers.js';
+/** More than 6 global or 8 cn KPI tiles weakens priority. */
+export const dt019 = rule(19, 'kpi-overload', 'warn', 'More than 6 global or 8 cn KPI tiles weakens priority.', 'keep only primary KPIs in the first view', function check(facts, context, emit) {
+    if ((facts.kpis?.length ?? 0) > packs[context.pack].limits.maxKpis)
+        emit('page');
+});

package/dist/rules/dt020-kpi-rainbow.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../types.js';
+/** Three or more distinct accent colours on KPI values or tiles distract. Neutral greys and pack text/background tokens are excluded. */
+export declare const dt020: Rule;

package/dist/rules/dt020-kpi-rainbow.js

@@ -0,0 +1,27 @@
+import { rule, sameColor } from './helpers.js';
+import { rgb } from '../color.js';
+import { getTokens } from '../packs/index.js';
+/** Three or more distinct accent colours on KPI values or tiles distract. Neutral greys and pack text/background tokens are excluded. */
+export const dt020 = rule(20, 'kpi-rainbow', 'warn', 'Three or more distinct accent colours on KPI values or tiles distract. Neutral greys and pack text/background tokens are excluded.', 'use ink for values and reserve colour for deltas', function check(facts, context, emit) {
+    const tokens = getTokens(context.pack, context.mode);
+    const neutral = [
+        tokens.ink,
+        tokens.muted,
+        tokens.paper,
+        tokens.card,
+        tokens.page,
+        tokens.bg,
+        tokens.panel,
+    ].filter((entry) => typeof entry === 'string');
+    const accent = (entry) => {
+        const channels = rgb(entry);
+        return (channels &&
+            Math.max(...channels) - Math.min(...channels) > 0.08 &&
+            !neutral.some((n) => sameColor(n, entry)));
+    };
+    const colors = (facts.kpis ?? [])
+        .flatMap((kpi) => [kpi.color, kpi.background ?? ''])
+        .filter(accent);
+    if (new Set(colors.map((entry) => rgb(entry)?.join(','))).size >= 3)
+        emit('page');
+});

package/dist/rules/dt021-emoji-icons.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../types.js';
+/** Emoji in headings, KPI labels, and rankings add inconsistent iconography. */
+export declare const dt021: Rule;

package/dist/rules/dt021-emoji-icons.js

@@ -0,0 +1,10 @@
+import { rule, charts } from './helpers.js';
+/** Emoji in headings, KPI labels, and rankings add inconsistent iconography. */
+export const dt021 = rule(21, 'emoji-icons', 'warn', 'Emoji in headings, KPI labels, and rankings add inconsistent iconography.', 'use plain text and plain numerals for rankings', function check(facts, context, emit) {
+    for (const entry of facts.emojis ?? [])
+        emit(entry.selector);
+    charts(facts, (option, path) => {
+        if (/\p{Extended_Pictographic}/u.test(JSON.stringify(option.title ?? '')))
+            emit(`${path}.title`);
+    });
+});

package/dist/rules/dt022-cjk-min-size.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../types.js';
+/** CJK text must be at least 12px. */
+export declare const dt022: Rule;

package/dist/rules/dt022-cjk-min-size.js

@@ -0,0 +1,9 @@
+import { packs } from '../packs/index.js';
+import { rule } from './helpers.js';
+/** CJK text must be at least 12px. */
+export const dt022 = rule(22, 'cjk-min-size', 'warn', 'CJK text must be at least 12px.', 'set CJK text to at least 12px', function check(facts, context, emit) {
+    for (const text of facts.texts ?? [])
+        if (/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u.test(text.text) &&
+            text.fontSize < packs[context.pack].limits.cjkMinFontSize)
+            emit(text.selector);
+}, true);

package/dist/rules/dt023-legend-single-series.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../types.js';
+/** An explicitly visible legend on one series repeats context. */
+export declare const dt023: Rule;

package/dist/rules/dt023-legend-single-series.js

@@ -0,0 +1,8 @@
+import { asArray, series, rule, charts } from './helpers.js';
+/** An explicitly visible legend on one series repeats context. */
+export const dt023 = rule(23, 'legend-single-series', 'info', 'An explicitly visible legend on one series repeats context.', 'hide the legend or label the series directly', function check(facts, context, emit) {
+    charts(facts, (option, path) => {
+        if (series(option).length === 1 && asArray(option.legend).some((l) => l.show !== false))
+            emit(`${path}.legend`);
+    });
+});

package/dist/rules/dt024-bar-width.d.ts

@@ -0,0 +1 @@
+export declare const dt024: import("../types.js").Rule;

package/dist/rules/dt024-bar-width.js

@@ -0,0 +1,14 @@
+import { rule, charts, series } from './helpers.js';
+export const dt024 = rule(24, 'bar-width', 'warn', 'Bars need an explicit width cap of 24px, or 32px on screens.', 'set barMaxWidth to 24 or less; use 32 or less on screens', (facts, context, emit) => {
+    charts(facts, (option, path) => series(option).forEach((s, i) => {
+        if (s.type !== 'bar')
+            return;
+        const cap = context.pack === 'cn' && context.mode === 'dark' ? 32 : 24;
+        const width = s.barMaxWidth ?? s.barWidth;
+        if (typeof width !== 'number' ||
+            width > cap ||
+            width <= 0 ||
+            (typeof s.barWidth === 'number' && s.barWidth > cap))
+            emit(`${path}.series[${i}]`);
+    }));
+});

package/dist/rules/dt025-legend-not-direct-label.d.ts

@@ -0,0 +1 @@
+export declare const dt025: import("../types.js").Rule;

package/dist/rules/dt025-legend-not-direct-label.js

@@ -0,0 +1,11 @@
+import { rule, charts, series, asArray } from './helpers.js';
+export const dt025 = rule(25, 'legend-not-direct-label', 'warn', 'Two to four line series need direct labels instead of a legend.', 'hide the legend and label series at their last point', (facts, context, emit) => {
+    charts(facts, (option, path) => {
+        const lines = series(option).filter((s) => s.type === 'line');
+        if (lines.length < 2 || lines.length > 4)
+            return;
+        if (asArray(option.legend).some((l) => l.show !== false) &&
+            !lines.every((s) => s.endLabel?.show || s.label?.show))
+            emit(path);
+    });
+});

package/dist/rules/dt026-line-weight.d.ts

@@ -0,0 +1 @@
+export declare const dt026: import("../types.js").Rule;

package/dist/rules/dt026-line-weight.js

@@ -0,0 +1,8 @@
+import { rule, charts, series } from './helpers.js';
+export const dt026 = rule(26, 'line-weight', 'warn', 'Line widths outside 1–3px obscure the data.', 'use 2px main lines and 1.5px comparison lines', (facts, context, emit) => {
+    charts(facts, (option, path) => series(option).forEach((s, i) => {
+        const width = s.lineStyle?.width;
+        if (s.type === 'line' && typeof width === 'number' && (width < 1 || width > 3))
+            emit(`${path}.series[${i}]`);
+    }));
+});

package/dist/rules/dt027-tabular-numerals.d.ts

@@ -0,0 +1 @@
+export declare const dt027: import("../types.js").Rule;

package/dist/rules/dt027-tabular-numerals.js

@@ -0,0 +1,16 @@
+import { rule } from './helpers.js';
+export const dt027 = rule(27, 'tabular-numerals', 'warn', 'KPI numbers need tabular numerals.', 'set font-variant-numeric to tabular-nums', (facts, context, emit) => {
+    const numbers = [
+        ...(facts.kpis ?? []),
+        ...(facts.texts ?? []).filter((t) => /^[\s+−\-\d,.%KMB万亿¥$€]+$/.test(t.text) && /\d/.test(t.text)),
+    ];
+    const seen = new Set();
+    for (const n of numbers) {
+        const tabular = /tabular-nums/.test(n.fontVariantNumeric ?? '') ||
+            /["']tnum["'](?:\s+(?:1|on))?(?=\s*(?:,|$))/.test(n.fontFeatureSettings ?? '');
+        if (!tabular && !seen.has(n.selector)) {
+            emit(n.selector);
+            seen.add(n.selector);
+        }
+    }
+});

package/dist/rules/dt028-hero-metric.d.ts

@@ -0,0 +1 @@
+export declare const dt028: import("../types.js").Rule;

package/dist/rules/dt028-hero-metric.js

@@ -0,0 +1,14 @@
+import { rule } from './helpers.js';
+export const dt028 = rule(28, 'hero-metric', 'info', 'Pages with at least three KPIs need a clear hero metric.', 'make the largest KPI at least 1.6 times the median of the others', (facts, context, emit) => {
+    const sizes = (facts.kpis ?? [])
+        .map((k) => k.fontSize ?? 0)
+        .filter((n) => n > 0)
+        .sort((a, b) => a - b);
+    if (sizes.length < 3)
+        return;
+    const largest = sizes.pop();
+    const mid = Math.floor(sizes.length / 2);
+    const median = sizes.length % 2 ? sizes[mid] : (sizes[mid - 1] + sizes[mid]) / 2;
+    if (largest < median * 1.6)
+        emit('page.kpis');
+});

package/dist/rules/helpers.d.ts

@@ -0,0 +1,32 @@
+import type { Rule, Option, PageFacts, CheckOptions, Severity } from '../types.js';
+export declare function asArray<T>(value: T | T[] | null | undefined): T[];
+export declare function series(option: Option): Option[];
+interface ValueAxis extends Option {
+    _dimension: 'x' | 'y';
+    _index: number;
+    _path: string;
+}
+/** An axis without a declared type or category data defaults to a value axis. */
+export declare function valueAxes(option: Option): ValueAxis[];
+/** Data may contain numbers, coordinate tuples, or objects with a value field. */
+export declare function seriesValues(item: Option): number[];
+export declare function seriesColor(item: Option, index: number, option: Option): unknown;
+export declare function allColors(option: Option): string[];
+export declare function walk(value: unknown, visit: (key: string, value: unknown) => void): void;
+export declare function isPie(item: Option): boolean;
+export declare function pieRadii(item: Option): number[];
+export declare function hasUnit(axis: Option): boolean;
+export declare const defaultColors: Set<string>;
+export type Context = Required<Pick<CheckOptions, 'pack' | 'mode'>> & CheckOptions;
+export type Emit = (path: string, message?: string, severity?: Severity) => void;
+/** Keep finding metadata and default messages consistent across all rule checks. */
+export declare function rule(number: number, name: string, severity: Severity, description: string, fix: string, run: (facts: PageFacts, context: Context, emit: Emit) => void, cnOnly?: boolean): Rule;
+export declare function charts(facts: PageFacts, visit: (option: Option, path: string) => void): void;
+export declare function background(facts: PageFacts, context: Context, option?: Option): string;
+/** Allow small rounding differences between hex and computed CSS colours. */
+export declare function sameColor(first: string, second: string): boolean;
+export declare function deltaDirection(text: string): 'up' | 'down' | 'flat';
+export declare function conventionColor(color: string, expected: string): boolean;
+/** Narrow JSON objects before inspecting extension fields. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export {};

package/dist/rules/helpers.js

@@ -0,0 +1,161 @@
+import { rgb } from '../color.js';
+import { getTokens } from '../packs/index.js';
+export function asArray(value) {
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+export function series(option) {
+    return asArray(option.series);
+}
+/** An axis without a declared type or category data defaults to a value axis. */
+export function valueAxes(option) {
+    const axes = [];
+    for (const dimension of ['x', 'y']) {
+        const options = dimension === 'x' ? option.xAxis : option.yAxis;
+        asArray(options).forEach((axis, index) => {
+            if (axis.type === 'value' || (!axis.type && !axis.data)) {
+                axes.push({
+                    ...axis,
+                    _dimension: dimension,
+                    _index: index,
+                    _path: `${dimension}Axis[${index}]`,
+                });
+            }
+        });
+    }
+    return axes;
+}
+/** Data may contain numbers, coordinate tuples, or objects with a value field. */
+export function seriesValues(item) {
+    return asArray(item.data).flatMap((datum) => {
+        const value = isRecord(datum) ? datum.value : datum;
+        return asArray(value).filter((entry) => typeof entry === 'number' && Number.isFinite(entry));
+    });
+}
+export function seriesColor(item, index, option) {
+    const palette = asArray(option.color);
+    return (item.lineStyle?.color ?? item.itemStyle?.color ?? palette[index % Math.max(1, palette.length)]);
+}
+export function allColors(option) {
+    const colors = [...asArray(option.color)];
+    series(option).forEach((item, index) => {
+        colors.push(seriesColor(item, index, option));
+        for (const datum of asArray(item.data)) {
+            if (isRecord(datum) && isRecord(datum.itemStyle))
+                colors.push(datum.itemStyle.color);
+        }
+    });
+    return colors.filter((color) => typeof color === 'string');
+}
+export function walk(value, visit) {
+    if (!value || typeof value !== 'object')
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        visit(key, child);
+        walk(child, visit);
+    }
+}
+export function isPie(item) {
+    return item.type === 'pie';
+}
+export function pieRadii(item) {
+    return asArray(item.radius).map((radius) => parseFloat(String(radius)));
+}
+export function hasUnit(axis) {
+    return !!(axis.name ||
+        axis.unit ||
+        axis.unitMetadata ||
+        axis.meta?.unit ||
+        axis.axisLabel?.formatter ||
+        (Array.isArray(axis.renderedTickLabels) &&
+            axis.renderedTickLabels.some((text) => /[$¥€£%万亿]|\d\s*[KMB]\b|\d\s*(?:元|人|件|次|ms|s|kg|days|months)\b/i.test(String(text)))));
+}
+export const defaultColors = new Set([
+    // ECharts 6 default theme, alongside the ECharts 5 palette below.
+    '#5070dd',
+    '#b6d634',
+    '#505372',
+    '#ff994d',
+    '#0ca8df',
+    '#ffd10a',
+    '#fb628b',
+    '#785db0',
+    '#3fbe95',
+    '#5470c6',
+    '#91cc75',
+    '#fac858',
+    '#ee6666',
+    '#73c0de',
+    '#3ba272',
+    '#fc8452',
+    '#9a60b4',
+    '#ea7ccc',
+]);
+/** Keep finding metadata and default messages consistent across all rule checks. */
+export function rule(number, name, severity, description, fix, run, cnOnly = false) {
+    const id = `DT${String(number).padStart(3, '0')}`;
+    return {
+        id,
+        name,
+        severity,
+        packs: cnOnly ? ['cn'] : ['global', 'cn'],
+        description,
+        fix,
+        check(facts, context) {
+            const findings = [];
+            const emit = (path, message = name.replaceAll('-', ' '), level = severity) => {
+                findings.push({ ruleId: id, severity: level, message, path, fix });
+            };
+            run(facts, context, emit);
+            return findings;
+        },
+    };
+}
+export function charts(facts, visit) {
+    facts.charts.forEach((chart, index) => visit(chart.option, `charts[${index}]`));
+}
+export function background(facts, context, option) {
+    const tokens = getTokens(context.pack, context.mode);
+    return (context.background ??
+        option?.backgroundColor ??
+        facts.page?.background ??
+        String(tokens.paper ?? tokens.card ?? tokens.panel));
+}
+/** Allow small rounding differences between hex and computed CSS colours. */
+export function sameColor(first, second) {
+    const firstChannels = rgb(first);
+    const secondChannels = rgb(second);
+    return (!!firstChannels &&
+        !!secondChannels &&
+        firstChannels.every((channel, index) => Math.abs(channel - secondChannels[index]) < 0.015));
+}
+export function deltaDirection(text) {
+    if (/[▼↓]|-\s*\d/.test(text))
+        return 'down';
+    if (/[▲↑]|\+\s*\d/.test(text))
+        return 'up';
+    return 'flat';
+}
+function dominantChannel(channels) {
+    const [red, green, blue] = channels;
+    if (red > green * 1.15 && red > blue * 1.15)
+        return 'red';
+    if (green > red * 1.15 && green > blue * 1.05)
+        return 'green';
+    return 'other';
+}
+export function conventionColor(color, expected) {
+    if (sameColor(color, expected))
+        return true;
+    const actualChannels = rgb(color);
+    const expectedChannels = rgb(expected);
+    if (!actualChannels || !expectedChannels)
+        return false;
+    const actualChannel = dominantChannel(actualChannels);
+    return actualChannel !== 'other' && actualChannel === dominantChannel(expectedChannels);
+}
+/** Narrow JSON objects before inspecting extension fields. */
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../types.js';
+export declare const rules: Rule[];

package/dist/rules/index.js

@@ -0,0 +1,58 @@
+import { dt028 } from './dt028-hero-metric.js';
+import { dt027 } from './dt027-tabular-numerals.js';
+import { dt026 } from './dt026-line-weight.js';
+import { dt025 } from './dt025-legend-not-direct-label.js';
+import { dt024 } from './dt024-bar-width.js';
+import { dt001 } from './dt001-default-palette.js';
+import { dt002 } from './dt002-rainbow-palette.js';
+import { dt003 } from './dt003-smooth-line.js';
+import { dt004 } from './dt004-symbols-everywhere.js';
+import { dt005 } from './dt005-pie-slices.js';
+import { dt006 } from './dt006-pie-overuse.js';
+import { dt007 } from './dt007-three-d.js';
+import { dt008 } from './dt008-dual-axis.js';
+import { dt009 } from './dt009-missing-unit.js';
+import { dt010 } from './dt010-bar-baseline.js';
+import { dt011 } from './dt011-raw-large-numbers.js';
+import { dt012 } from './dt012-unit-system.js';
+import { dt013 } from './dt013-delta-convention.js';
+import { dt014 } from './dt014-delta-colour-only.js';
+import { dt015 } from './dt015-low-contrast-text.js';
+import { dt016 } from './dt016-thin-line-contrast.js';
+import { dt017 } from './dt017-gradient-decoration.js';
+import { dt018 } from './dt018-glow.js';
+import { dt019 } from './dt019-kpi-overload.js';
+import { dt020 } from './dt020-kpi-rainbow.js';
+import { dt021 } from './dt021-emoji-icons.js';
+import { dt022 } from './dt022-cjk-min-size.js';
+import { dt023 } from './dt023-legend-single-series.js';
+export const rules = [
+    dt001,
+    dt002,
+    dt003,
+    dt004,
+    dt005,
+    dt006,
+    dt007,
+    dt008,
+    dt009,
+    dt010,
+    dt011,
+    dt012,
+    dt013,
+    dt014,
+    dt015,
+    dt016,
+    dt017,
+    dt018,
+    dt019,
+    dt020,
+    dt021,
+    dt022,
+    dt023,
+    dt024,
+    dt025,
+    dt026,
+    dt027,
+    dt028,
+];

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+import type { PackName, Mode, DeltaColors, Polarity } from './packs/index.js';
+/** JSON-compatible ECharts options; unknown extension fields are retained. */
+export interface ChartStyle {
+    type?: string;
+    color?: string | Option;
+    formatter?: string | ((...args: unknown[]) => unknown);
+    width?: number;
+    fontSize?: number;
+    fontWeight?: number | 'bold' | 'normal';
+    show?: boolean;
+}
+/** Fields inspected by the rules; other ECharts fields remain available as unknown. */
+export interface Option {
+    [key: string]: unknown;
+    series?: Option | Option[];
+    xAxis?: Option | Option[];
+    yAxis?: Option | Option[];
+    legend?: Option | Option[];
+    color?: string | string[];
+    backgroundColor?: string;
+    type?: string;
+    data?: unknown[];
+    lineStyle?: ChartStyle;
+    itemStyle?: ChartStyle;
+    textStyle?: ChartStyle;
+    axisLabel?: ChartStyle;
+    label?: ChartStyle;
+    tooltip?: {
+        show?: boolean;
+        formatter?: unknown;
+        valueFormatter?: unknown;
+    };
+    name?: string;
+    unit?: unknown;
+    unitMetadata?: unknown;
+    meta?: {
+        unit?: unknown;
+    };
+    radius?: string | number | (string | number)[];
+    smooth?: boolean | number;
+    showSymbol?: boolean;
+    symbol?: string;
+    roseType?: string | boolean;
+    min?: number | string;
+    scale?: boolean;
+}
+export interface ChartFacts {
+    id?: string;
+    option: Option;
+}
+export interface TextFact {
+    selector: string;
+    text: string;
+    color: string;
+    background: string;
+    fontSize: number;
+    fontWeight: number;
+    fontVariantNumeric?: string;
+    fontFeatureSettings?: string;
+}
+export interface DeltaFact {
+    selector: string;
+    text: string;
+    color: string;
+    direction?: 'up' | 'down' | 'flat';
+    polarity?: Polarity;
+}
+export interface PageFacts {
+    charts: ChartFacts[];
+    texts?: TextFact[];
+    gradients?: {
+        selector: string;
+        background: string;
+    }[];
+    shadows?: {
+        selector: string;
+        boxShadow: string;
+        textShadow: string;
+    }[];
+    kpis?: {
+        selector: string;
+        text: string;
+        color: string;
+        background?: string;
+        fontSize?: number;
+        fontVariantNumeric?: string;
+        fontFeatureSettings?: string;
+    }[];
+    deltas?: DeltaFact[];
+    emojis?: {
+        selector: string;
+        text: string;
+    }[];
+    page?: {
+        background?: string;
+        deltaColors?: DeltaColors;
+    };
+}
+export interface CheckOptions {
+    pack?: PackName;
+    mode?: Mode;
+    background?: string;
+    disable?: string[];
+    only?: string[];
+}
+export type Severity = 'error' | 'warn' | 'info';
+export interface Finding {
+    ruleId: string;
+    severity: Severity;
+    message: string;
+    path: string;
+    fix: string;
+}
+export interface Rule {
+    id: string;
+    name: string;
+    severity: Severity;
+    packs: PackName[];
+    description: string;
+    fix: string;
+    check: (facts: PageFacts, options: Required<Pick<CheckOptions, 'pack' | 'mode'>> & CheckOptions) => Finding[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};