@ankhorage/rules-design 0.3.1 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +1 -1
- package/dist/features/color/colorObservationValues.d.ts +7 -0
- package/dist/features/color/colorObservationValues.js +9 -0
- package/dist/features/color/createColorPolicyRules.d.ts +6 -0
- package/dist/features/color/createColorPolicyRules.js +138 -0
- package/dist/features/color/createColorRuleSet.d.ts +6 -0
- package/dist/features/color/createColorRuleSet.js +175 -0
- package/dist/features/color/evaluateColorPolicyObservation.d.ts +6 -0
- package/dist/features/color/evaluateColorPolicyObservation.js +148 -0
- package/dist/features/color/isColorRulePolicy.d.ts +3 -0
- package/dist/features/color/isColorRulePolicy.js +84 -0
- package/dist/types/color.d.ts +25 -0
- package/dist/types/color.js +0 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# @ankhorage/rules-design
|
|
5
5
|
|
|
6
|
-
         
|
|
7
7
|
|
|
8
8
|
Declarative catalog for reusable design rules.
|
|
9
9
|
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { JsonValue } from '@ankhorage/rules';
|
|
2
|
+
/*** Provides shared primitive checks for normalized Color observation fields. */
|
|
3
|
+
export declare const colorObservationValues: {
|
|
4
|
+
sequence: (left: readonly string[], right: readonly string[]) => boolean;
|
|
5
|
+
strings: (value: JsonValue | undefined) => readonly string[] | undefined;
|
|
6
|
+
text: (value: unknown) => value is string;
|
|
7
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { isDeepStrictEqual } from 'node:util';
|
|
2
|
+
/*** Provides shared primitive checks for normalized Color observation fields. */
|
|
3
|
+
export const colorObservationValues = {
|
|
4
|
+
sequence: (left, right) => isDeepStrictEqual(left, right),
|
|
5
|
+
strings: (value) => Array.isArray(value) && value.length > 0 && value.every(colorObservationValues.text)
|
|
6
|
+
? value
|
|
7
|
+
: undefined,
|
|
8
|
+
text: (value) => typeof value === 'string' && value.trim() !== '',
|
|
9
|
+
};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Rule } from '@ankhorage/rules';
|
|
2
|
+
import type { ColorRulePolicy } from '../../types/color';
|
|
3
|
+
import type { DesignContext } from '../../types/designRuleProvider';
|
|
4
|
+
export type { ColorRulePolicy } from '../../types/color';
|
|
5
|
+
/*** Creates the twelve frozen Color and Tokens policy rules from normalized raw observations. */
|
|
6
|
+
export declare function createColorPolicyRules(policy: ColorRulePolicy): readonly Rule<DesignContext>[];
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { colorObservationValues } from './colorObservationValues';
|
|
3
|
+
import { evaluateColorPolicyObservation } from './evaluateColorPolicyObservation';
|
|
4
|
+
import { isColorRulePolicy } from './isColorRulePolicy';
|
|
5
|
+
const policyRuleIds = [
|
|
6
|
+
'design.color.syntax-valid',
|
|
7
|
+
'design.color.token-exists',
|
|
8
|
+
'design.color.token-allowed',
|
|
9
|
+
'design.color.semantic-role',
|
|
10
|
+
'design.color.literal-drift',
|
|
11
|
+
'design.color.ramp-consistency',
|
|
12
|
+
'design.color.alpha-composition',
|
|
13
|
+
'design.color.surface-role',
|
|
14
|
+
'design.color.hover-state',
|
|
15
|
+
'design.color.active-state',
|
|
16
|
+
'design.color.disabled-state',
|
|
17
|
+
'design.color.theme-coverage',
|
|
18
|
+
];
|
|
19
|
+
const { text } = colorObservationValues;
|
|
20
|
+
/*** Creates the twelve frozen Color and Tokens policy rules from normalized raw observations. */
|
|
21
|
+
export function createColorPolicyRules(policy) {
|
|
22
|
+
validateColorRulePolicy(policy);
|
|
23
|
+
return policyRuleIds.map((ruleId) => createColorPolicyRule(ruleId, policy));
|
|
24
|
+
}
|
|
25
|
+
/*** Rejects malformed trusted policy before Color rules can produce ambiguous verdicts. */
|
|
26
|
+
function validateColorRulePolicy(policy) {
|
|
27
|
+
if (!isColorRulePolicy(policy))
|
|
28
|
+
throw new Error('Color rule policy must define complete acceptance and coverage configuration.');
|
|
29
|
+
}
|
|
30
|
+
/*** Constructs one fact-driven atomic rule without trusting adapter verdict fields. */
|
|
31
|
+
function createColorPolicyRule(ruleId, policy) {
|
|
32
|
+
return {
|
|
33
|
+
defaultSeverity: 'warning',
|
|
34
|
+
dependencies: [],
|
|
35
|
+
evaluate: (input) => evaluateColorPolicyRule(ruleId, policy, input),
|
|
36
|
+
identity: { id: ruleId, version: '1.0.0' },
|
|
37
|
+
requiredCapabilities: ['design.color-policy-facts'],
|
|
38
|
+
summary: colorPolicySummary(ruleId),
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/*** Assesses each normalized raw observation with the rule-specific trusted policy. */
|
|
42
|
+
function evaluateColorPolicyRule(ruleId, policy, input) {
|
|
43
|
+
const facts = (input.context.facts ?? []).filter((fact) => fact.kind === ruleId && sameScope(fact, input));
|
|
44
|
+
const observations = facts.map((fact) => ({ fact, observation: parseObservation(fact) }));
|
|
45
|
+
if (facts.length === 0 || observations.some(({ observation }) => observation === undefined))
|
|
46
|
+
return incomplete(ruleId, input);
|
|
47
|
+
const assessments = observations.flatMap(({ fact, observation }) => observation === undefined
|
|
48
|
+
? []
|
|
49
|
+
: [
|
|
50
|
+
{
|
|
51
|
+
fact,
|
|
52
|
+
observation,
|
|
53
|
+
verdict: evaluateColorPolicyObservation(ruleId, observation.value, policy),
|
|
54
|
+
},
|
|
55
|
+
]);
|
|
56
|
+
if (assessments.some(({ verdict }) => verdict === 'INCOMPLETE'))
|
|
57
|
+
return incomplete(ruleId, input);
|
|
58
|
+
const findings = assessments.flatMap(({ fact, observation, verdict }) => verdict === 'FAIL' ? [finding(ruleId, fact, observation)] : []);
|
|
59
|
+
return { findings, status: findings.length === 0 ? 'PASS' : 'FAIL' };
|
|
60
|
+
}
|
|
61
|
+
/*** Accepts facts only from the complete active Rules scope. */
|
|
62
|
+
function sameScope(fact, input) {
|
|
63
|
+
return fact.scope.id === input.scope.id && fact.scope.kind === input.scope.kind;
|
|
64
|
+
}
|
|
65
|
+
/*** Parses available raw evidence while ignoring adapter-supplied verdict fields. */
|
|
66
|
+
function parseObservation(fact) {
|
|
67
|
+
if (fact.status !== 'available' || !isRecord(fact.value) || !isSubject(fact.value.subject))
|
|
68
|
+
return undefined;
|
|
69
|
+
const { subject, ...value } = fact.value;
|
|
70
|
+
return Object.values(value).every(isJsonValue) ? { subject, value } : undefined;
|
|
71
|
+
}
|
|
72
|
+
/*** Narrows a serializable raw observation field to the Rules JSON vocabulary. */
|
|
73
|
+
function isJsonValue(value) {
|
|
74
|
+
return (value === null ||
|
|
75
|
+
typeof value === 'boolean' ||
|
|
76
|
+
typeof value === 'number' ||
|
|
77
|
+
typeof value === 'string' ||
|
|
78
|
+
(Array.isArray(value) && value.every(isJsonValue)) ||
|
|
79
|
+
(isRecord(value) && Object.values(value).every(isJsonValue)));
|
|
80
|
+
}
|
|
81
|
+
/*** Narrows the observation provenance required for an evidence-backed finding. */
|
|
82
|
+
function isSubject(value) {
|
|
83
|
+
return isRecord(value) && text(value.id) && text(value.kind);
|
|
84
|
+
}
|
|
85
|
+
/*** Reports unavailable or malformed evidence without creating a false pass. */
|
|
86
|
+
function incomplete(ruleId, input) {
|
|
87
|
+
return {
|
|
88
|
+
findings: [
|
|
89
|
+
{
|
|
90
|
+
evidence: { scopeId: input.scope.id },
|
|
91
|
+
message: `${colorPolicySummary(ruleId)} No available normalized raw observation was supplied for this exact scope.`,
|
|
92
|
+
ruleId,
|
|
93
|
+
severity: 'info',
|
|
94
|
+
subjects: [{ id: input.scope.id, kind: input.scope.kind }],
|
|
95
|
+
},
|
|
96
|
+
],
|
|
97
|
+
status: 'INCOMPLETE',
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
/*** Creates an evidence-backed finding from a trusted policy contradiction. */
|
|
101
|
+
function finding(ruleId, fact, observation) {
|
|
102
|
+
return {
|
|
103
|
+
evidence: { factId: fact.id, observation: observation.value },
|
|
104
|
+
message: `${colorPolicySummary(ruleId)} Observed raw values contradict the configured policy.`,
|
|
105
|
+
ruleId,
|
|
106
|
+
severity: 'warning',
|
|
107
|
+
subjects: [observation.subject],
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
/*** Supplies the frozen catalog summary for one Color and Tokens rule. */
|
|
111
|
+
function colorPolicySummary(ruleId) {
|
|
112
|
+
switch (ruleId) {
|
|
113
|
+
case 'design.color.active-state':
|
|
114
|
+
return 'Active color variation follows policy.';
|
|
115
|
+
case 'design.color.alpha-composition':
|
|
116
|
+
return 'Transparency is evaluated against the actual backdrop.';
|
|
117
|
+
case 'design.color.disabled-state':
|
|
118
|
+
return 'Disabled colors communicate disabled state.';
|
|
119
|
+
case 'design.color.hover-state':
|
|
120
|
+
return 'Hover color variation follows policy.';
|
|
121
|
+
case 'design.color.literal-drift':
|
|
122
|
+
return 'Unnecessary literal values do not drift from tokens.';
|
|
123
|
+
case 'design.color.ramp-consistency':
|
|
124
|
+
return 'Defined color ramps remain consistent.';
|
|
125
|
+
case 'design.color.semantic-role':
|
|
126
|
+
return 'Foreground, background, and border roles are semantically correct.';
|
|
127
|
+
case 'design.color.surface-role':
|
|
128
|
+
return 'Surface colors consistently express their role.';
|
|
129
|
+
case 'design.color.syntax-valid':
|
|
130
|
+
return 'Colors are syntactically valid.';
|
|
131
|
+
case 'design.color.theme-coverage':
|
|
132
|
+
return 'Light and dark theme tokens are available.';
|
|
133
|
+
case 'design.color.token-allowed':
|
|
134
|
+
return 'Only permitted palette tokens are used.';
|
|
135
|
+
case 'design.color.token-exists':
|
|
136
|
+
return 'Referenced color tokens exist.';
|
|
137
|
+
}
|
|
138
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { RuleSet } from '@ankhorage/rules';
|
|
2
|
+
import type { DesignContext } from '../../types/designRuleProvider';
|
|
3
|
+
import { type ColorRulePolicy } from './createColorPolicyRules';
|
|
4
|
+
export type { ColorRulePolicy } from './createColorPolicyRules';
|
|
5
|
+
/*** Creates the isolated Color and Tokens contribution without central registration. */
|
|
6
|
+
export declare function createColorRuleSet(policy: ColorRulePolicy): RuleSet<DesignContext>;
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { createColorPolicyRules } from './createColorPolicyRules';
|
|
3
|
+
/*** Creates the isolated Color and Tokens contribution without central registration. */
|
|
4
|
+
export function createColorRuleSet(policy) {
|
|
5
|
+
return {
|
|
6
|
+
id: 'ankhorage.rules-design.color',
|
|
7
|
+
rules: [...createColorPolicyRules(policy), createUsageRule(policy)],
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
/*** Evaluates rendered color areas against provider-owned targets and tolerances. */
|
|
11
|
+
function createUsageRule(policy) {
|
|
12
|
+
return {
|
|
13
|
+
defaultSeverity: 'warning',
|
|
14
|
+
dependencies: [],
|
|
15
|
+
evaluate: (input) => evaluateUsage(input, policy),
|
|
16
|
+
identity: { id: 'design.color.usage-distribution', version: '1.0.0' },
|
|
17
|
+
requiredCapabilities: ['rendered.area-analysis'],
|
|
18
|
+
summary: 'Compare separately measured rendered color-role areas with the configured distribution.',
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
/*** Keeps exact rule scope, breakpoint, theme, and coverage measurements isolated. */
|
|
22
|
+
function evaluateUsage(input, policy) {
|
|
23
|
+
const facts = (input.context.facts ?? []).filter((fact) => fact.kind === 'design.color.usage-distribution' && exactScope(fact, input));
|
|
24
|
+
const observations = facts.map(parseObservation);
|
|
25
|
+
if (facts.length === 0 || observations.some((value) => value === undefined))
|
|
26
|
+
return incomplete(input, 'No complete normalized rendered-area fact was supplied.');
|
|
27
|
+
const complete = observations.filter(isObservation);
|
|
28
|
+
const missing = missingCoverage(complete, policy);
|
|
29
|
+
if (missing.length > 0)
|
|
30
|
+
return incomplete(input, `Required rendered-area scope measurements are missing: ${missing.join(', ')}.`);
|
|
31
|
+
const page = complete.filter((observation) => observation.scope === 'page');
|
|
32
|
+
const failures = page.flatMap((observation) => deviations(observation, policy).map((value) => finding(value, 'warning')));
|
|
33
|
+
const diagnostics = complete
|
|
34
|
+
.filter((observation) => observation.scope !== 'page')
|
|
35
|
+
.flatMap((observation) => deviations(observation, policy).map((value) => finding(value, 'info')));
|
|
36
|
+
return {
|
|
37
|
+
findings: [...failures, ...diagnostics],
|
|
38
|
+
status: failures.length === 0 ? 'PASS' : 'FAIL',
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/*** Requires configured coverage for every breakpoint and theme without merging local samples. */
|
|
42
|
+
function missingCoverage(observations, policy) {
|
|
43
|
+
return policy.requiredBreakpointIds.flatMap((breakpointId) => policy.requiredThemeIds.flatMap((themeId) => policy.requiredScopes.flatMap((scope) => hasRequiredCoverage(observations, breakpointId, themeId, scope)
|
|
44
|
+
? []
|
|
45
|
+
: [`${breakpointId}:${themeId}:${scope}`])));
|
|
46
|
+
}
|
|
47
|
+
/*** Requires one page assessment and at least one advisory local sample for configured coverage. */
|
|
48
|
+
function hasRequiredCoverage(observations, breakpointId, themeId, scope) {
|
|
49
|
+
const matching = observations.filter((observation) => observation.breakpointId === breakpointId &&
|
|
50
|
+
observation.themeId === themeId &&
|
|
51
|
+
observation.scope === scope);
|
|
52
|
+
return scope === 'page' ? matching.length === 1 : matching.length > 0;
|
|
53
|
+
}
|
|
54
|
+
/*** Narrows a parsed observation after incomplete evidence has been rejected. */
|
|
55
|
+
function isObservation(observation) {
|
|
56
|
+
return observation !== undefined;
|
|
57
|
+
}
|
|
58
|
+
/*** Validates one available pixel observation including exact total and unknown coverage. */
|
|
59
|
+
function parseObservation(fact) {
|
|
60
|
+
if (fact.status !== 'available' || !isRecord(fact.value))
|
|
61
|
+
return undefined;
|
|
62
|
+
const { value } = fact;
|
|
63
|
+
const roles = value.rolePixels;
|
|
64
|
+
if (!isRecord(roles))
|
|
65
|
+
return undefined;
|
|
66
|
+
const identity = parseIdentity(value);
|
|
67
|
+
const pixels = parsePixels(value, roles);
|
|
68
|
+
if (!identity || !pixels)
|
|
69
|
+
return undefined;
|
|
70
|
+
const total = pixels.base + pixels.secondary + pixels.accent + pixels.unknown;
|
|
71
|
+
return total === pixels.measuredPixels &&
|
|
72
|
+
pixels.measuredPixels > 0 &&
|
|
73
|
+
pixels.unknown === pixels.unknownPixels &&
|
|
74
|
+
pixels.unknownPixels === 0
|
|
75
|
+
? {
|
|
76
|
+
...identity,
|
|
77
|
+
rolePixels: pixels,
|
|
78
|
+
measuredPixels: pixels.measuredPixels,
|
|
79
|
+
unknownPixels: pixels.unknownPixels,
|
|
80
|
+
}
|
|
81
|
+
: undefined;
|
|
82
|
+
}
|
|
83
|
+
/*** Parses the immutable breakpoint, theme, and coverage identity. */
|
|
84
|
+
function parseIdentity(value) {
|
|
85
|
+
return text(value.breakpointId) &&
|
|
86
|
+
text(value.themeId) &&
|
|
87
|
+
text(value.scopeId) &&
|
|
88
|
+
isCoverageScope(value.scope)
|
|
89
|
+
? {
|
|
90
|
+
breakpointId: value.breakpointId,
|
|
91
|
+
scope: value.scope,
|
|
92
|
+
scopeId: value.scopeId,
|
|
93
|
+
themeId: value.themeId,
|
|
94
|
+
}
|
|
95
|
+
: undefined;
|
|
96
|
+
}
|
|
97
|
+
/*** Parses exclusive integer pixel counters without accepting partial coverage. */
|
|
98
|
+
function parsePixels(value, roles) {
|
|
99
|
+
const { measuredPixels, unknownPixels } = value;
|
|
100
|
+
const { accent, base, secondary, unknown } = roles;
|
|
101
|
+
return pixel(measuredPixels) &&
|
|
102
|
+
pixel(unknownPixels) &&
|
|
103
|
+
pixel(accent) &&
|
|
104
|
+
pixel(base) &&
|
|
105
|
+
pixel(secondary) &&
|
|
106
|
+
pixel(unknown)
|
|
107
|
+
? { accent, base, measuredPixels, secondary, unknown, unknownPixels }
|
|
108
|
+
: undefined;
|
|
109
|
+
}
|
|
110
|
+
/*** Produces deviations only when the provider-owned tolerance is exceeded. */
|
|
111
|
+
function deviations(observation, policy) {
|
|
112
|
+
return [
|
|
113
|
+
deviation('base', observation.rolePixels.base, observation, policy.roleTargets.base, policy.roleTolerances.base),
|
|
114
|
+
deviation('secondary', observation.rolePixels.secondary, observation, policy.roleTargets.secondary, policy.roleTolerances.secondary),
|
|
115
|
+
deviation('accent', observation.rolePixels.accent, observation, policy.roleTargets.accent, policy.roleTolerances.accent),
|
|
116
|
+
].flatMap((value) => (value === undefined ? [] : [value]));
|
|
117
|
+
}
|
|
118
|
+
/*** Produces one deviation when a measured role exceeds its configured tolerance. */
|
|
119
|
+
function deviation(role, pixels, observation, target, tolerance) {
|
|
120
|
+
const observed = pixels / observation.measuredPixels;
|
|
121
|
+
return Math.abs(observed - target) > tolerance
|
|
122
|
+
? { observation, observed, role, target, tolerance }
|
|
123
|
+
: undefined;
|
|
124
|
+
}
|
|
125
|
+
/*** Creates a full-evidence finding while retaining advisory viewport and scroll results. */
|
|
126
|
+
function finding(value, severity) {
|
|
127
|
+
return {
|
|
128
|
+
evidence: {
|
|
129
|
+
breakpointId: value.observation.breakpointId,
|
|
130
|
+
observed: value.observed,
|
|
131
|
+
role: value.role,
|
|
132
|
+
scope: value.observation.scope,
|
|
133
|
+
scopeId: value.observation.scopeId,
|
|
134
|
+
target: value.target,
|
|
135
|
+
themeId: value.observation.themeId,
|
|
136
|
+
tolerance: value.tolerance,
|
|
137
|
+
unknownPixels: value.observation.unknownPixels,
|
|
138
|
+
},
|
|
139
|
+
message: `${value.role} occupies ${value.observed} of ${value.observation.scope}, outside its configured tolerance.`,
|
|
140
|
+
ruleId: 'design.color.usage-distribution',
|
|
141
|
+
severity,
|
|
142
|
+
subjects: [{ id: value.observation.scopeId, kind: 'rendered-color-scope' }],
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
/*** Reports missing evidence without allowing a partial page to pass. */
|
|
146
|
+
function incomplete(input, message) {
|
|
147
|
+
return {
|
|
148
|
+
findings: [
|
|
149
|
+
{
|
|
150
|
+
evidence: { scopeId: input.scope.id },
|
|
151
|
+
message,
|
|
152
|
+
ruleId: 'design.color.usage-distribution',
|
|
153
|
+
severity: 'info',
|
|
154
|
+
subjects: [{ id: input.scope.id, kind: input.scope.kind }],
|
|
155
|
+
},
|
|
156
|
+
],
|
|
157
|
+
status: 'INCOMPLETE',
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
/*** Compares the complete active Rules scope rather than only its identifier. */
|
|
161
|
+
function exactScope(fact, input) {
|
|
162
|
+
return fact.scope.id === input.scope.id && fact.scope.kind === input.scope.kind;
|
|
163
|
+
}
|
|
164
|
+
/*** Narrows a non-empty identifier. */
|
|
165
|
+
function text(value) {
|
|
166
|
+
return typeof value === 'string' && value.trim() !== '';
|
|
167
|
+
}
|
|
168
|
+
/*** Narrows a non-negative integer pixel count. */
|
|
169
|
+
function pixel(value) {
|
|
170
|
+
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
|
|
171
|
+
}
|
|
172
|
+
/*** Narrows coverage scope vocabulary. */
|
|
173
|
+
function isCoverageScope(value) {
|
|
174
|
+
return value === 'page' || value === 'scroll-sample' || value === 'viewport';
|
|
175
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { JsonValue } from '@ankhorage/rules';
|
|
2
|
+
import type { ColorPolicyRuleId, ColorRulePolicy } from '../../types/color';
|
|
3
|
+
type Verdict = 'FAIL' | 'INCOMPLETE' | 'PASS';
|
|
4
|
+
/*** Evaluates one normalized raw observation using its frozen Color rule policy. */
|
|
5
|
+
export declare function evaluateColorPolicyObservation(ruleId: ColorPolicyRuleId, value: Readonly<Record<string, JsonValue>>, policy: ColorRulePolicy): Verdict;
|
|
6
|
+
export {};
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import { colorObservationValues } from './colorObservationValues';
|
|
2
|
+
/*** Evaluates one normalized raw observation using its frozen Color rule policy. */
|
|
3
|
+
export function evaluateColorPolicyObservation(ruleId, value, policy) {
|
|
4
|
+
switch (ruleId) {
|
|
5
|
+
case 'design.color.syntax-valid':
|
|
6
|
+
return syntaxValid(value, policy);
|
|
7
|
+
case 'design.color.token-exists':
|
|
8
|
+
return tokenExists(value, policy);
|
|
9
|
+
case 'design.color.token-allowed':
|
|
10
|
+
return tokenAllowed(value, policy);
|
|
11
|
+
case 'design.color.semantic-role':
|
|
12
|
+
return semanticRole(value, policy);
|
|
13
|
+
case 'design.color.literal-drift':
|
|
14
|
+
return literalDrift(value, policy);
|
|
15
|
+
case 'design.color.ramp-consistency':
|
|
16
|
+
return rampConsistency(value, policy);
|
|
17
|
+
case 'design.color.alpha-composition':
|
|
18
|
+
return alphaComposition(value, policy);
|
|
19
|
+
case 'design.color.surface-role':
|
|
20
|
+
return surfaceRole(value, policy);
|
|
21
|
+
case 'design.color.hover-state':
|
|
22
|
+
return state(value, policy, 'hover');
|
|
23
|
+
case 'design.color.active-state':
|
|
24
|
+
return state(value, policy, 'active');
|
|
25
|
+
case 'design.color.disabled-state':
|
|
26
|
+
return state(value, policy, 'disabled');
|
|
27
|
+
case 'design.color.theme-coverage':
|
|
28
|
+
return themeCoverage(value, policy);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/*** Confirms syntax policy and the corresponding literal form. */
|
|
32
|
+
function syntaxValid(value, policy) {
|
|
33
|
+
const { color, syntax } = value;
|
|
34
|
+
if (!colorObservationValues.text(color) || !colorObservationValues.text(syntax))
|
|
35
|
+
return 'INCOMPLETE';
|
|
36
|
+
return policy.allowedColorSyntaxes.includes(syntax) && validColorSyntax(color, syntax)
|
|
37
|
+
? 'PASS'
|
|
38
|
+
: 'FAIL';
|
|
39
|
+
}
|
|
40
|
+
/*** Validates the supported syntax representation without deriving a policy verdict. */
|
|
41
|
+
function validColorSyntax(color, syntax) {
|
|
42
|
+
if (syntax === 'hex')
|
|
43
|
+
return /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/iu.test(color);
|
|
44
|
+
if (syntax === 'token')
|
|
45
|
+
return /^[-\w./]+$/u.test(color);
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
/*** Requires a referenced token to be present in the trusted inventory. */
|
|
49
|
+
function tokenExists(value, policy) {
|
|
50
|
+
return colorObservationValues.text(value.token)
|
|
51
|
+
? policy.knownTokens.includes(value.token)
|
|
52
|
+
? 'PASS'
|
|
53
|
+
: 'FAIL'
|
|
54
|
+
: 'INCOMPLETE';
|
|
55
|
+
}
|
|
56
|
+
/*** Requires a referenced token to be permitted for use. */
|
|
57
|
+
function tokenAllowed(value, policy) {
|
|
58
|
+
return colorObservationValues.text(value.token)
|
|
59
|
+
? policy.allowedTokens.includes(value.token)
|
|
60
|
+
? 'PASS'
|
|
61
|
+
: 'FAIL'
|
|
62
|
+
: 'INCOMPLETE';
|
|
63
|
+
}
|
|
64
|
+
/*** Checks that a semantic role uses one of its trusted tokens. */
|
|
65
|
+
function semanticRole(value, policy) {
|
|
66
|
+
const { role, token } = value;
|
|
67
|
+
if (!colorObservationValues.text(role) || !colorObservationValues.text(token))
|
|
68
|
+
return 'INCOMPLETE';
|
|
69
|
+
return configuredTokens(policy.semanticRoleTokens, role)?.includes(token) ? 'PASS' : 'FAIL';
|
|
70
|
+
}
|
|
71
|
+
/*** Rejects a canonical literal when it identifies a different token. */
|
|
72
|
+
function literalDrift(value, policy) {
|
|
73
|
+
const { literal, token } = value;
|
|
74
|
+
if (!colorObservationValues.text(literal) || !colorObservationValues.text(token))
|
|
75
|
+
return 'INCOMPLETE';
|
|
76
|
+
const canonicalToken = configuredValue(policy.canonicalLiterals, literal);
|
|
77
|
+
return canonicalToken === undefined || canonicalToken === token ? 'PASS' : 'FAIL';
|
|
78
|
+
}
|
|
79
|
+
/*** Verifies the complete ordered token sequence for a named color ramp. */
|
|
80
|
+
function rampConsistency(value, policy) {
|
|
81
|
+
const { ramp } = value;
|
|
82
|
+
const tokens = colorObservationValues.strings(value.tokens);
|
|
83
|
+
if (!colorObservationValues.text(ramp) || tokens === undefined)
|
|
84
|
+
return 'INCOMPLETE';
|
|
85
|
+
const expectedTokens = configuredTokens(policy.rampTokens, ramp);
|
|
86
|
+
return expectedTokens !== undefined && colorObservationValues.sequence(tokens, expectedTokens)
|
|
87
|
+
? 'PASS'
|
|
88
|
+
: 'FAIL';
|
|
89
|
+
}
|
|
90
|
+
/*** Verifies a foreground and backdrop against their trusted composited result. */
|
|
91
|
+
function alphaComposition(value, policy) {
|
|
92
|
+
const { backdrop, composite, foreground } = value;
|
|
93
|
+
if (!colorObservationValues.text(foreground) ||
|
|
94
|
+
!colorObservationValues.text(backdrop) ||
|
|
95
|
+
!colorObservationValues.text(composite))
|
|
96
|
+
return 'INCOMPLETE';
|
|
97
|
+
const composites = configuredTokens(policy.alphaCompositions, foreground);
|
|
98
|
+
return configuredValue(composites, backdrop) === composite ? 'PASS' : 'FAIL';
|
|
99
|
+
}
|
|
100
|
+
/*** Checks the configured token inventory for a rendered surface role. */
|
|
101
|
+
function surfaceRole(value, policy) {
|
|
102
|
+
const { surface, token } = value;
|
|
103
|
+
if (!colorObservationValues.text(surface) || !colorObservationValues.text(token))
|
|
104
|
+
return 'INCOMPLETE';
|
|
105
|
+
return configuredTokens(policy.surfaceRoleTokens, surface)?.includes(token) ? 'PASS' : 'FAIL';
|
|
106
|
+
}
|
|
107
|
+
/*** Checks the configured transition token for one interactive state. */
|
|
108
|
+
function state(value, policy, stateName) {
|
|
109
|
+
const { baseToken, stateToken } = value;
|
|
110
|
+
if (!colorObservationValues.text(baseToken) || !colorObservationValues.text(stateToken))
|
|
111
|
+
return 'INCOMPLETE';
|
|
112
|
+
return configuredValue(statePolicy(policy, stateName), baseToken) === stateToken
|
|
113
|
+
? 'PASS'
|
|
114
|
+
: 'FAIL';
|
|
115
|
+
}
|
|
116
|
+
/*** Selects a fixed interactive state map without dynamic policy object access. */
|
|
117
|
+
function statePolicy(policy, stateName) {
|
|
118
|
+
switch (stateName) {
|
|
119
|
+
case 'active':
|
|
120
|
+
return policy.stateTokens.active;
|
|
121
|
+
case 'disabled':
|
|
122
|
+
return policy.stateTokens.disabled;
|
|
123
|
+
case 'hover':
|
|
124
|
+
return policy.stateTokens.hover;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/*** Requires a token to supply every required theme in its policy inventory. */
|
|
128
|
+
function themeCoverage(value, policy) {
|
|
129
|
+
const { token } = value;
|
|
130
|
+
const themes = colorObservationValues.strings(value.themes);
|
|
131
|
+
if (!colorObservationValues.text(token) || themes === undefined)
|
|
132
|
+
return 'INCOMPLETE';
|
|
133
|
+
const configuredThemes = configuredTokens(policy.themeTokens, token);
|
|
134
|
+
return configuredThemes !== undefined &&
|
|
135
|
+
policy.requiredThemeIds.every((theme) => themes.includes(theme) && configuredThemes.includes(theme))
|
|
136
|
+
? 'PASS'
|
|
137
|
+
: 'FAIL';
|
|
138
|
+
}
|
|
139
|
+
/*** Retrieves a configured string value without dynamic object indexing. */
|
|
140
|
+
function configuredValue(values, key) {
|
|
141
|
+
return values === undefined
|
|
142
|
+
? undefined
|
|
143
|
+
: Object.entries(values).find(([entry]) => entry === key)?.[1];
|
|
144
|
+
}
|
|
145
|
+
/*** Retrieves a configured string list without dynamic object indexing. */
|
|
146
|
+
function configuredTokens(values, key) {
|
|
147
|
+
return Object.entries(values).find(([entry]) => entry === key)?.[1];
|
|
148
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
/*** Verifies trusted Color factory policy before assessment closures are created. */
|
|
3
|
+
export function isColorRulePolicy(value) {
|
|
4
|
+
return (isRecord(value) &&
|
|
5
|
+
value.version === 1 &&
|
|
6
|
+
corePolicy(value) &&
|
|
7
|
+
colorSyntaxes(value.allowedColorSyntaxes) &&
|
|
8
|
+
identifiers(value.knownTokens) &&
|
|
9
|
+
identifiers(value.allowedTokens) &&
|
|
10
|
+
identifiers(value.requiredBreakpointIds) &&
|
|
11
|
+
identifiers(value.requiredThemeIds) &&
|
|
12
|
+
coverageScopes(value.requiredScopes) &&
|
|
13
|
+
roleMap(value.roleTargets, true) &&
|
|
14
|
+
roleMap(value.roleTolerances, false));
|
|
15
|
+
}
|
|
16
|
+
/*** Validates the semantic policy maps independently from the coverage policy. */
|
|
17
|
+
function corePolicy(value) {
|
|
18
|
+
return (stringMap(value.canonicalLiterals) &&
|
|
19
|
+
tokenLists(value.rampTokens) &&
|
|
20
|
+
nestedTokenMap(value.alphaCompositions) &&
|
|
21
|
+
tokenLists(value.semanticRoleTokens) &&
|
|
22
|
+
tokenLists(value.surfaceRoleTokens) &&
|
|
23
|
+
stateTokenMaps(value.stateTokens) &&
|
|
24
|
+
tokenLists(value.themeTokens));
|
|
25
|
+
}
|
|
26
|
+
/*** Requires non-empty unique policy identifiers. */
|
|
27
|
+
function identifiers(value) {
|
|
28
|
+
return (Array.isArray(value) &&
|
|
29
|
+
value.length > 0 &&
|
|
30
|
+
new Set(value).size === value.length &&
|
|
31
|
+
value.every(text));
|
|
32
|
+
}
|
|
33
|
+
/*** Requires configured Color syntax formats to use the supported closed vocabulary. */
|
|
34
|
+
function colorSyntaxes(value) {
|
|
35
|
+
return identifiers(value) && value.every((syntax) => syntax === 'hex' || syntax === 'token');
|
|
36
|
+
}
|
|
37
|
+
/*** Narrows a complete map of raw literal values to canonical token names. */
|
|
38
|
+
function stringMap(value) {
|
|
39
|
+
return isRecord(value) && Object.keys(value).every(text) && Object.values(value).every(text);
|
|
40
|
+
}
|
|
41
|
+
/*** Narrows a semantic role map whose entries are non-empty trusted token inventories. */
|
|
42
|
+
function tokenLists(value) {
|
|
43
|
+
return (isRecord(value) && Object.keys(value).every(text) && Object.values(value).every(identifiers));
|
|
44
|
+
}
|
|
45
|
+
/*** Narrows a foreground and backdrop matrix to its trusted composited token. */
|
|
46
|
+
function nestedTokenMap(value) {
|
|
47
|
+
return isRecord(value) && Object.keys(value).every(text) && Object.values(value).every(stringMap);
|
|
48
|
+
}
|
|
49
|
+
/*** Narrows the three explicit interactive state policies. */
|
|
50
|
+
function stateTokenMaps(value) {
|
|
51
|
+
return (isRecord(value) &&
|
|
52
|
+
stringMap(value.active) &&
|
|
53
|
+
stringMap(value.disabled) &&
|
|
54
|
+
stringMap(value.hover));
|
|
55
|
+
}
|
|
56
|
+
/*** Requires page evidence while allowing any enabled local diagnostic scopes. */
|
|
57
|
+
function coverageScopes(value) {
|
|
58
|
+
return (Array.isArray(value) &&
|
|
59
|
+
value.includes('page') &&
|
|
60
|
+
new Set(value).size === value.length &&
|
|
61
|
+
value.every((scope) => scope === 'page' || scope === 'scroll-sample' || scope === 'viewport'));
|
|
62
|
+
}
|
|
63
|
+
/*** Checks normalized target or tolerance role maps. */
|
|
64
|
+
function roleMap(value, target) {
|
|
65
|
+
if (!isRecord(value))
|
|
66
|
+
return false;
|
|
67
|
+
const { accent, base, secondary } = value;
|
|
68
|
+
return (proportion(accent) &&
|
|
69
|
+
proportion(base) &&
|
|
70
|
+
proportion(secondary) &&
|
|
71
|
+
(!target ||
|
|
72
|
+
(typeof base === 'number' &&
|
|
73
|
+
typeof secondary === 'number' &&
|
|
74
|
+
typeof accent === 'number' &&
|
|
75
|
+
Math.abs(base + secondary + accent - 1) < Number.EPSILON)));
|
|
76
|
+
}
|
|
77
|
+
/*** Narrows a finite role proportion within the supported inclusive range. */
|
|
78
|
+
function proportion(value) {
|
|
79
|
+
return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
|
|
80
|
+
}
|
|
81
|
+
/*** Narrows a non-empty identifier. */
|
|
82
|
+
function text(value) {
|
|
83
|
+
return typeof value === 'string' && value.trim() !== '';
|
|
84
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/*** Identifies one frozen atomic Color policy rule. */
|
|
2
|
+
export type ColorPolicyRuleId = 'design.color.syntax-valid' | 'design.color.token-exists' | 'design.color.token-allowed' | 'design.color.semantic-role' | 'design.color.literal-drift' | 'design.color.ramp-consistency' | 'design.color.alpha-composition' | 'design.color.surface-role' | 'design.color.hover-state' | 'design.color.active-state' | 'design.color.disabled-state' | 'design.color.theme-coverage';
|
|
3
|
+
type ColorState = 'active' | 'disabled' | 'hover';
|
|
4
|
+
type ColorRole = 'accent' | 'base' | 'secondary';
|
|
5
|
+
type RoleValues = Readonly<Record<ColorRole, number>>;
|
|
6
|
+
/*** Configures trusted semantic acceptance and coverage policy for frozen Color rules. */
|
|
7
|
+
export interface ColorRulePolicy {
|
|
8
|
+
readonly alphaCompositions: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
9
|
+
readonly allowedColorSyntaxes: readonly string[];
|
|
10
|
+
readonly allowedTokens: readonly string[];
|
|
11
|
+
readonly canonicalLiterals: Readonly<Record<string, string>>;
|
|
12
|
+
readonly knownTokens: readonly string[];
|
|
13
|
+
readonly rampTokens: Readonly<Record<string, readonly string[]>>;
|
|
14
|
+
readonly requiredBreakpointIds: readonly string[];
|
|
15
|
+
readonly requiredScopes: readonly ('page' | 'scroll-sample' | 'viewport')[];
|
|
16
|
+
readonly requiredThemeIds: readonly string[];
|
|
17
|
+
readonly roleTargets: RoleValues;
|
|
18
|
+
readonly roleTolerances: RoleValues;
|
|
19
|
+
readonly semanticRoleTokens: Readonly<Record<string, readonly string[]>>;
|
|
20
|
+
readonly stateTokens: Readonly<Record<ColorState, Readonly<Record<string, string>>>>;
|
|
21
|
+
readonly surfaceRoleTokens: Readonly<Record<string, readonly string[]>>;
|
|
22
|
+
readonly themeTokens: Readonly<Record<string, readonly string[]>>;
|
|
23
|
+
readonly version: number;
|
|
24
|
+
}
|
|
25
|
+
export {};
|
|
File without changes
|