@ankhorage/rules-design 0.3.1 → 0.3.3
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 +13 -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/features/media/createMediaRuleSet.d.ts +12 -0
- package/dist/features/media/createMediaRuleSet.js +98 -0
- package/dist/features/media/evaluateMediaApplicability.d.ts +3 -0
- package/dist/features/media/evaluateMediaApplicability.js +64 -0
- package/dist/features/media/evaluateMediaAssessment.d.ts +14 -0
- package/dist/features/media/evaluateMediaAssessment.js +177 -0
- package/dist/features/media/mediaRuleDefinitions.d.ts +7 -0
- package/dist/features/media/mediaRuleDefinitions.js +17 -0
- package/dist/features/responsive/createResponsiveRules.d.ts +4 -0
- package/dist/features/responsive/createResponsiveRules.js +197 -0
- package/dist/features/responsive/evaluateResponsiveOrder.d.ts +3 -0
- package/dist/features/responsive/evaluateResponsiveOrder.js +33 -0
- package/dist/features/responsive/isContainedInResponsiveBounds.d.ts +3 -0
- package/dist/features/responsive/isContainedInResponsiveBounds.js +7 -0
- package/dist/features/responsive/parseResponsiveMatrix.d.ts +3 -0
- package/dist/features/responsive/parseResponsiveMatrix.js +146 -0
- package/dist/features/responsive/responsiveElementsOfKind.d.ts +3 -0
- package/dist/features/responsive/responsiveElementsOfKind.js +8 -0
- package/dist/features/responsive/selectResponsiveFact.d.ts +10 -0
- package/dist/features/responsive/selectResponsiveFact.js +12 -0
- package/dist/types/color.d.ts +25 -0
- package/dist/types/color.js +0 -0
- package/dist/types/responsive.d.ts +45 -0
- package/dist/types/responsive.js +0 -0
- package/package.json +1 -1
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { evaluateMediaAssessment, } from './evaluateMediaAssessment';
|
|
2
|
+
import { mediaRuleDefinitions } from './mediaRuleDefinitions';
|
|
3
|
+
/*** Creates the independently composable Images and Media rule contribution from portable facts. */
|
|
4
|
+
export function createMediaRuleSet(options = {}) {
|
|
5
|
+
const aspectRatioTolerance = resolveAspectRatioTolerance(options);
|
|
6
|
+
return {
|
|
7
|
+
id: 'ankhorage.rules-design.media',
|
|
8
|
+
rules: mediaRuleDefinitions.map((definition) => createMediaRule(definition, aspectRatioTolerance)),
|
|
9
|
+
};
|
|
10
|
+
}
|
|
11
|
+
/*** Builds one pure generic Rule from a fixed catalog media identifier. */
|
|
12
|
+
function createMediaRule(definition, aspectRatioTolerance) {
|
|
13
|
+
return {
|
|
14
|
+
defaultSeverity: definition.id === 'design.media.focal-point' ? 'warning' : 'error',
|
|
15
|
+
dependencies: [],
|
|
16
|
+
evaluate: ({ context, scope }) => evaluateMediaRule(definition, aspectRatioTolerance, context, scope),
|
|
17
|
+
identity: { id: definition.id, version: '1.0.0' },
|
|
18
|
+
requiredCapabilities: ['media.metadata'],
|
|
19
|
+
summary: definition.summary,
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
/*** Evaluates all complete, scope-matching assessments without fabricating unavailable measurements. */
|
|
23
|
+
function evaluateMediaRule(definition, aspectRatioTolerance, context, scope) {
|
|
24
|
+
const scopedFacts = context.facts.filter((fact) => matchesMediaScope(fact, scope));
|
|
25
|
+
if (scopedFacts.length === 0) {
|
|
26
|
+
return incomplete(definition.id, 'No media assessment fact exists for this scope.');
|
|
27
|
+
}
|
|
28
|
+
if (scopedFacts.some((fact) => fact.status === 'missing')) {
|
|
29
|
+
return incomplete(definition.id, 'A media assessment fact is explicitly unavailable.');
|
|
30
|
+
}
|
|
31
|
+
const assessments = scopedFacts.flatMap(toMediaAssessment);
|
|
32
|
+
if (assessments.length !== scopedFacts.length) {
|
|
33
|
+
return incomplete(definition.id, 'A media assessment fact has an invalid serializable value.');
|
|
34
|
+
}
|
|
35
|
+
const checks = assessments.map((assessment) => evaluateMediaAssessment(definition, aspectRatioTolerance, assessment));
|
|
36
|
+
if (checks.some((check) => check === null)) {
|
|
37
|
+
return incomplete(definition.id, 'A media assessment lacks the measurements required by this rule.');
|
|
38
|
+
}
|
|
39
|
+
return failedOutcome(definition, checks.filter((check) => check !== null));
|
|
40
|
+
}
|
|
41
|
+
/*** Resolves the trusted aspect-ratio tolerance at the factory boundary. */
|
|
42
|
+
function resolveAspectRatioTolerance(options) {
|
|
43
|
+
const tolerance = options.aspectRatioTolerance ?? 0;
|
|
44
|
+
if (!Number.isFinite(tolerance) || tolerance < 0) {
|
|
45
|
+
throw new TypeError('Aspect-ratio tolerance must be a finite non-negative number.');
|
|
46
|
+
}
|
|
47
|
+
return tolerance;
|
|
48
|
+
}
|
|
49
|
+
/*** Matches only media facts observed for the exact evaluation scope. */
|
|
50
|
+
function matchesMediaScope(fact, scope) {
|
|
51
|
+
return (fact.kind === 'design.media.assessment' &&
|
|
52
|
+
fact.scope.id === scope.id &&
|
|
53
|
+
fact.scope.kind === scope.kind);
|
|
54
|
+
}
|
|
55
|
+
/*** Parses one available frozen fact into its minimal rule-owned media shape. */
|
|
56
|
+
function toMediaAssessment(fact) {
|
|
57
|
+
if (fact.status !== 'available' || !isSerializableRecord(fact.value))
|
|
58
|
+
return [];
|
|
59
|
+
const { mediaId } = fact.value;
|
|
60
|
+
return typeof mediaId === 'string' && mediaId.length > 0
|
|
61
|
+
? [{ id: mediaId, value: fact.value }]
|
|
62
|
+
: [];
|
|
63
|
+
}
|
|
64
|
+
/*** Converts failed media checks to rule findings from every scoped assessment. */
|
|
65
|
+
function failedOutcome(definition, checks) {
|
|
66
|
+
const failures = checks.filter((check) => check.status === 'FAIL');
|
|
67
|
+
return failures.length === 0
|
|
68
|
+
? { findings: [], status: 'PASS' }
|
|
69
|
+
: {
|
|
70
|
+
findings: failures.map((failure) => ({
|
|
71
|
+
evidence: failure.evidence,
|
|
72
|
+
message: failure.message,
|
|
73
|
+
ruleId: definition.id,
|
|
74
|
+
severity: definition.id === 'design.media.focal-point' ? 'warning' : 'error',
|
|
75
|
+
subjects: [{ id: failure.mediaId, kind: 'media' }],
|
|
76
|
+
})),
|
|
77
|
+
status: 'FAIL',
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
/*** Creates a deterministic incomplete outcome for absent or invalid factual evidence. */
|
|
81
|
+
function incomplete(ruleId, message) {
|
|
82
|
+
return {
|
|
83
|
+
findings: [
|
|
84
|
+
{
|
|
85
|
+
evidence: { reason: message },
|
|
86
|
+
message,
|
|
87
|
+
ruleId,
|
|
88
|
+
severity: 'info',
|
|
89
|
+
subjects: [{ id: 'media-facts', kind: 'media-facts' }],
|
|
90
|
+
},
|
|
91
|
+
],
|
|
92
|
+
status: 'INCOMPLETE',
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
/*** Identifies a serializable keyed record without accepting serializable arrays. */
|
|
96
|
+
function isSerializableRecord(value) {
|
|
97
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
98
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { MediaAssessment, MediaCheck } from './evaluateMediaAssessment';
|
|
2
|
+
/*** Evaluates policy-owned evidence that can prove a media rule does not apply. */
|
|
3
|
+
export declare function evaluateMediaApplicability(ruleId: string, assessment: MediaAssessment): MediaCheck | null | undefined;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/*** Evaluates policy-owned evidence that can prove a media rule does not apply. */
|
|
2
|
+
export function evaluateMediaApplicability(ruleId, assessment) {
|
|
3
|
+
switch (ruleId) {
|
|
4
|
+
case 'design.media.focal-point':
|
|
5
|
+
return focalPointApplicability(assessment);
|
|
6
|
+
case 'design.media.responsive-sources':
|
|
7
|
+
return responsiveSourcesApplicability(assessment);
|
|
8
|
+
case 'design.media.overlay-legibility':
|
|
9
|
+
return textOverlayApplicability(assessment);
|
|
10
|
+
case 'design.media.icon-sizing':
|
|
11
|
+
return iconApplicability(assessment);
|
|
12
|
+
default:
|
|
13
|
+
return undefined;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
/*** Resolves a declared focal-point characteristic without trusting generic adapter flags. */
|
|
17
|
+
function focalPointApplicability(assessment) {
|
|
18
|
+
const { hasFocalPoint } = assessment.value;
|
|
19
|
+
return booleanCharacteristic(assessment, Object.hasOwn(assessment.value, 'hasFocalPoint'), hasFocalPoint, 'no declared focal point', ['focalPointX', 'focalPointY', 'visibleBottom', 'visibleLeft', 'visibleRight', 'visibleTop']);
|
|
20
|
+
}
|
|
21
|
+
/*** Resolves a declared responsive-source characteristic without inferring it from absent widths. */
|
|
22
|
+
function responsiveSourcesApplicability(assessment) {
|
|
23
|
+
const { hasResponsiveSources } = assessment.value;
|
|
24
|
+
return booleanCharacteristic(assessment, Object.hasOwn(assessment.value, 'hasResponsiveSources'), hasResponsiveSources, 'no responsive source set', ['devicePixelRatio', 'renderedWidth', 'selectedSourceWidth', 'sourceWidths']);
|
|
25
|
+
}
|
|
26
|
+
/*** Resolves a declared text-overlay characteristic without trusting generic adapter flags. */
|
|
27
|
+
function textOverlayApplicability(assessment) {
|
|
28
|
+
const { hasTextOverlay } = assessment.value;
|
|
29
|
+
return booleanCharacteristic(assessment, Object.hasOwn(assessment.value, 'hasTextOverlay'), hasTextOverlay, 'no text overlay', ['overlayContrastRatio']);
|
|
30
|
+
}
|
|
31
|
+
/*** Accepts a boolean characteristic only when the assessed media explicitly declared it. */
|
|
32
|
+
function booleanCharacteristic(assessment, isDeclared, value, reason, measurementFields) {
|
|
33
|
+
if (!isDeclared || value === true)
|
|
34
|
+
return undefined;
|
|
35
|
+
if (value !== false)
|
|
36
|
+
return null;
|
|
37
|
+
return hasMeasuredEvidence(assessment, measurementFields)
|
|
38
|
+
? undefined
|
|
39
|
+
: skippedCheck(assessment, reason);
|
|
40
|
+
}
|
|
41
|
+
/*** Applies icon sizing only to media whose validated kind establishes it is not an icon. */
|
|
42
|
+
function iconApplicability(assessment) {
|
|
43
|
+
const { mediaKind } = assessment.value;
|
|
44
|
+
if (!Object.hasOwn(assessment.value, 'mediaKind') || mediaKind === 'icon')
|
|
45
|
+
return undefined;
|
|
46
|
+
if (mediaKind !== 'image')
|
|
47
|
+
return null;
|
|
48
|
+
return hasMeasuredEvidence(assessment, ['actualIconSize', 'expectedIconSize'])
|
|
49
|
+
? undefined
|
|
50
|
+
: skippedCheck(assessment, 'media is not an icon');
|
|
51
|
+
}
|
|
52
|
+
/*** Detects rule-specific measurement evidence that contradicts a non-applicability characteristic. */
|
|
53
|
+
function hasMeasuredEvidence(assessment, fields) {
|
|
54
|
+
return fields.some((field) => Object.hasOwn(assessment.value, field));
|
|
55
|
+
}
|
|
56
|
+
/*** Records a rule-specific, validated reason why one media assessment has no policy obligation. */
|
|
57
|
+
function skippedCheck(assessment, reason) {
|
|
58
|
+
return {
|
|
59
|
+
evidence: { factId: assessment.id, reason },
|
|
60
|
+
mediaId: assessment.id,
|
|
61
|
+
message: `${assessment.id} is not applicable because ${reason}.`,
|
|
62
|
+
status: 'SKIPPED',
|
|
63
|
+
};
|
|
64
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { JsonValue } from '@ankhorage/rules';
|
|
2
|
+
import type { MediaRuleDefinition } from './mediaRuleDefinitions';
|
|
3
|
+
/*** Evaluates one rule-specific predicate from one normalized media assessment. */
|
|
4
|
+
export declare function evaluateMediaAssessment(definition: MediaRuleDefinition, aspectRatioTolerance: number, assessment: MediaAssessment): MediaCheck | null;
|
|
5
|
+
export interface MediaAssessment {
|
|
6
|
+
readonly id: string;
|
|
7
|
+
readonly value: Readonly<Record<string, JsonValue>>;
|
|
8
|
+
}
|
|
9
|
+
export interface MediaCheck {
|
|
10
|
+
readonly evidence: JsonValue;
|
|
11
|
+
readonly mediaId: string;
|
|
12
|
+
readonly message: string;
|
|
13
|
+
readonly status: 'FAIL' | 'PASS' | 'SKIPPED';
|
|
14
|
+
}
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
import { evaluateMediaApplicability } from './evaluateMediaApplicability';
|
|
2
|
+
/*** Evaluates one rule-specific predicate from one normalized media assessment. */
|
|
3
|
+
export function evaluateMediaAssessment(definition, aspectRatioTolerance, assessment) {
|
|
4
|
+
const applicability = evaluateMediaApplicability(definition.id, assessment);
|
|
5
|
+
if (applicability !== undefined)
|
|
6
|
+
return applicability;
|
|
7
|
+
switch (definition.id) {
|
|
8
|
+
case 'design.media.aspect-ratio':
|
|
9
|
+
return aspectRatio(assessment, aspectRatioTolerance);
|
|
10
|
+
case 'design.media.intrinsic-size':
|
|
11
|
+
return positiveDimensions(assessment);
|
|
12
|
+
case 'design.media.resolution-fit':
|
|
13
|
+
return resolutionFit(assessment);
|
|
14
|
+
case 'design.media.object-fit':
|
|
15
|
+
return compareStrings(assessment, (value) => value.actualObjectFit, (value) => value.expectedObjectFit, 'object fit');
|
|
16
|
+
case 'design.media.focal-point':
|
|
17
|
+
return focalPointPreservation(assessment);
|
|
18
|
+
case 'design.media.responsive-sources':
|
|
19
|
+
return responsiveSourceSelection(assessment);
|
|
20
|
+
case 'design.media.overlay-legibility':
|
|
21
|
+
return contrast(assessment, definition.minimumContrastRatio);
|
|
22
|
+
case 'design.media.icon-sizing':
|
|
23
|
+
return equalNumbers(assessment, (value) => value.actualIconSize, (value) => value.expectedIconSize, 'icon size');
|
|
24
|
+
case 'design.media.decorative-vs-content':
|
|
25
|
+
return decorativeClassification(assessment);
|
|
26
|
+
default:
|
|
27
|
+
return null;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/*** Compares measured and expected aspect ratios with a rule-factory-owned tolerance. */
|
|
31
|
+
function aspectRatio(assessment, tolerance) {
|
|
32
|
+
const actual = asFiniteNumber(assessment.value.actualAspectRatio);
|
|
33
|
+
const expected = asPositiveNumber(assessment.value.expectedAspectRatio);
|
|
34
|
+
return actual === null || expected === null
|
|
35
|
+
? null
|
|
36
|
+
: check(assessment, Math.abs(actual - expected) <= tolerance + Number.EPSILON, 'aspect ratio', actual, {
|
|
37
|
+
expected,
|
|
38
|
+
tolerance,
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
/*** Requires two positive intrinsic dimensions without inferring absent metadata. */
|
|
42
|
+
function positiveDimensions(assessment) {
|
|
43
|
+
const width = asFiniteNumber(assessment.value.intrinsicWidth);
|
|
44
|
+
const height = asFiniteNumber(assessment.value.intrinsicHeight);
|
|
45
|
+
return width === null || height === null
|
|
46
|
+
? null
|
|
47
|
+
: check(assessment, width > 0 && height > 0, 'intrinsic dimensions', { height, width }, 'positive dimensions');
|
|
48
|
+
}
|
|
49
|
+
/*** Verifies that intrinsic dimensions cover the observed rendered dimensions. */
|
|
50
|
+
function resolutionFit(assessment) {
|
|
51
|
+
const intrinsicWidth = asPositiveNumber(assessment.value.intrinsicWidth);
|
|
52
|
+
const intrinsicHeight = asPositiveNumber(assessment.value.intrinsicHeight);
|
|
53
|
+
const renderedWidth = asPositiveNumber(assessment.value.renderedWidth);
|
|
54
|
+
const renderedHeight = asPositiveNumber(assessment.value.renderedHeight);
|
|
55
|
+
return intrinsicWidth === null ||
|
|
56
|
+
intrinsicHeight === null ||
|
|
57
|
+
renderedWidth === null ||
|
|
58
|
+
renderedHeight === null
|
|
59
|
+
? null
|
|
60
|
+
: check(assessment, intrinsicWidth >= renderedWidth && intrinsicHeight >= renderedHeight, 'resolution fit', { intrinsicHeight, intrinsicWidth }, { renderedHeight, renderedWidth });
|
|
61
|
+
}
|
|
62
|
+
/*** Compares resolved and configured media string values. */
|
|
63
|
+
function compareStrings(assessment, actualSelector, expectedSelector, label) {
|
|
64
|
+
const actual = asString(actualSelector(assessment.value));
|
|
65
|
+
const expected = asString(expectedSelector(assessment.value));
|
|
66
|
+
return actual === null || expected === null
|
|
67
|
+
? null
|
|
68
|
+
: check(assessment, actual === expected, label, actual, expected);
|
|
69
|
+
}
|
|
70
|
+
/*** Verifies that a normalized focal point lies within the measured visible crop bounds. */
|
|
71
|
+
function focalPointPreservation(assessment) {
|
|
72
|
+
const focalPointX = asUnitInterval(assessment.value.focalPointX);
|
|
73
|
+
const focalPointY = asUnitInterval(assessment.value.focalPointY);
|
|
74
|
+
const visibleLeft = asUnitInterval(assessment.value.visibleLeft);
|
|
75
|
+
const visibleRight = asUnitInterval(assessment.value.visibleRight);
|
|
76
|
+
const visibleTop = asUnitInterval(assessment.value.visibleTop);
|
|
77
|
+
const visibleBottom = asUnitInterval(assessment.value.visibleBottom);
|
|
78
|
+
if (focalPointX === null ||
|
|
79
|
+
focalPointY === null ||
|
|
80
|
+
visibleLeft === null ||
|
|
81
|
+
visibleRight === null ||
|
|
82
|
+
visibleTop === null ||
|
|
83
|
+
visibleBottom === null ||
|
|
84
|
+
visibleLeft > visibleRight ||
|
|
85
|
+
visibleTop > visibleBottom)
|
|
86
|
+
return null;
|
|
87
|
+
return check(assessment, focalPointX >= visibleLeft &&
|
|
88
|
+
focalPointX <= visibleRight &&
|
|
89
|
+
focalPointY >= visibleTop &&
|
|
90
|
+
focalPointY <= visibleBottom, 'focal point visibility', { focalPointX, focalPointY }, { visibleBottom, visibleLeft, visibleRight, visibleTop });
|
|
91
|
+
}
|
|
92
|
+
/*** Verifies a measured responsive source selection covers the rendered pixel demand. */
|
|
93
|
+
function responsiveSourceSelection(assessment) {
|
|
94
|
+
const renderedWidth = asPositiveNumber(assessment.value.renderedWidth);
|
|
95
|
+
const devicePixelRatio = asPositiveNumber(assessment.value.devicePixelRatio);
|
|
96
|
+
const selectedSourceWidth = asPositiveNumber(assessment.value.selectedSourceWidth);
|
|
97
|
+
const sourceWidths = asDistinctPositiveNumbers(assessment.value.sourceWidths);
|
|
98
|
+
if (renderedWidth === null ||
|
|
99
|
+
devicePixelRatio === null ||
|
|
100
|
+
selectedSourceWidth === null ||
|
|
101
|
+
sourceWidths === null ||
|
|
102
|
+
sourceWidths.length < 2 ||
|
|
103
|
+
!sourceWidths.includes(selectedSourceWidth))
|
|
104
|
+
return null;
|
|
105
|
+
const requiredWidth = renderedWidth * devicePixelRatio;
|
|
106
|
+
const closestSufficientSource = sourceWidths
|
|
107
|
+
.filter((width) => width >= requiredWidth)
|
|
108
|
+
.reduce((closest, width) => (closest === null || width < closest ? width : closest), null);
|
|
109
|
+
return closestSufficientSource === null
|
|
110
|
+
? check(assessment, false, 'responsive source selection', { selectedSourceWidth, sourceWidths }, { requiredWidth })
|
|
111
|
+
: check(assessment, selectedSourceWidth === closestSufficientSource, 'responsive source selection', { selectedSourceWidth, sourceWidths }, { requiredWidth, selectedSourceWidth: closestSufficientSource });
|
|
112
|
+
}
|
|
113
|
+
/*** Uses the media-rule-owned contrast threshold instead of an adapter-supplied requirement. */
|
|
114
|
+
function contrast(assessment, minimumContrastRatio) {
|
|
115
|
+
const actual = asFiniteNumber(assessment.value.overlayContrastRatio);
|
|
116
|
+
return actual === null || minimumContrastRatio === undefined
|
|
117
|
+
? null
|
|
118
|
+
: check(assessment, actual >= minimumContrastRatio, 'overlay contrast', actual, minimumContrastRatio);
|
|
119
|
+
}
|
|
120
|
+
/*** Compares two finite numeric media measurements that must be exactly configured. */
|
|
121
|
+
function equalNumbers(assessment, actualSelector, expectedSelector, label) {
|
|
122
|
+
const actual = asFiniteNumber(actualSelector(assessment.value));
|
|
123
|
+
const expected = asPositiveNumber(expectedSelector(assessment.value));
|
|
124
|
+
return actual === null || expected === null
|
|
125
|
+
? null
|
|
126
|
+
: check(assessment, actual === expected, label, actual, expected);
|
|
127
|
+
}
|
|
128
|
+
/*** Requires decorative media to be unnamed and content media to expose a usable name. */
|
|
129
|
+
function decorativeClassification(assessment) {
|
|
130
|
+
const { accessibleName, classification: classificationValue } = assessment.value;
|
|
131
|
+
const classification = asString(classificationValue);
|
|
132
|
+
if (classification !== 'content' && classification !== 'decorative')
|
|
133
|
+
return null;
|
|
134
|
+
if (accessibleName !== null && typeof accessibleName !== 'string')
|
|
135
|
+
return null;
|
|
136
|
+
const passed = (classification === 'decorative' && accessibleName === null) ||
|
|
137
|
+
(classification === 'content' &&
|
|
138
|
+
typeof accessibleName === 'string' &&
|
|
139
|
+
accessibleName.length > 0);
|
|
140
|
+
return check(assessment, passed, 'media classification', { accessibleName, classification }, classification);
|
|
141
|
+
}
|
|
142
|
+
/*** Creates consistent serializable failure evidence for a measured media predicate. */
|
|
143
|
+
function check(assessment, passed, label, actual, expected) {
|
|
144
|
+
return {
|
|
145
|
+
evidence: { actual, expected, factId: assessment.id },
|
|
146
|
+
mediaId: assessment.id,
|
|
147
|
+
message: `${assessment.id} has ${label} ${JSON.stringify(actual)} but requires ${JSON.stringify(expected)}.`,
|
|
148
|
+
status: passed ? 'PASS' : 'FAIL',
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
/*** Narrows a serializable value to a finite numeric observation. */
|
|
152
|
+
function asFiniteNumber(value) {
|
|
153
|
+
return typeof value === 'number' && Number.isFinite(value) ? value : null;
|
|
154
|
+
}
|
|
155
|
+
/*** Narrows a positive finite numeric observation. */
|
|
156
|
+
function asPositiveNumber(value) {
|
|
157
|
+
const number = asFiniteNumber(value);
|
|
158
|
+
return number !== null && number > 0 ? number : null;
|
|
159
|
+
}
|
|
160
|
+
/*** Narrows a finite normalized coordinate between zero and one. */
|
|
161
|
+
function asUnitInterval(value) {
|
|
162
|
+
const number = asFiniteNumber(value);
|
|
163
|
+
return number !== null && number >= 0 && number <= 1 ? number : null;
|
|
164
|
+
}
|
|
165
|
+
/*** Narrows a JSON numeric array to distinct positive source widths. */
|
|
166
|
+
function asDistinctPositiveNumbers(value) {
|
|
167
|
+
if (!Array.isArray(value))
|
|
168
|
+
return null;
|
|
169
|
+
const numbers = value.map(asPositiveNumber);
|
|
170
|
+
return numbers.some((number) => number === null) || new Set(numbers).size !== numbers.length
|
|
171
|
+
? null
|
|
172
|
+
: numbers;
|
|
173
|
+
}
|
|
174
|
+
/*** Narrows a serializable value to a non-empty string observation. */
|
|
175
|
+
function asString(value) {
|
|
176
|
+
return typeof value === 'string' && value.length > 0 ? value : null;
|
|
177
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/*** Declares the fixed Images and Media catalog entries owned by this rule group. */
|
|
2
|
+
export declare const mediaRuleDefinitions: readonly MediaRuleDefinition[];
|
|
3
|
+
export interface MediaRuleDefinition {
|
|
4
|
+
readonly id: string;
|
|
5
|
+
readonly minimumContrastRatio?: number;
|
|
6
|
+
readonly summary: string;
|
|
7
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/*** Declares the fixed Images and Media catalog entries owned by this rule group. */
|
|
2
|
+
const definitions = [
|
|
3
|
+
['design.media.aspect-ratio', 'Require configured media aspect ratios.'],
|
|
4
|
+
['design.media.intrinsic-size', 'Require known positive intrinsic media dimensions.'],
|
|
5
|
+
['design.media.resolution-fit', 'Require media resolution suitable for rendered bounds.'],
|
|
6
|
+
['design.media.object-fit', 'Require configured object fitting.'],
|
|
7
|
+
['design.media.focal-point', 'Preserve declared focal points after cropping.'],
|
|
8
|
+
['design.media.responsive-sources', 'Require responsive media sources when assessed.'],
|
|
9
|
+
['design.media.overlay-legibility', 'Require sufficient measured overlay contrast.', 4.5],
|
|
10
|
+
['design.media.icon-sizing', 'Require configured icon sizing.'],
|
|
11
|
+
[
|
|
12
|
+
'design.media.decorative-vs-content',
|
|
13
|
+
'Require media classification to agree with its accessible name.',
|
|
14
|
+
],
|
|
15
|
+
];
|
|
16
|
+
/*** Declares the fixed Images and Media catalog entries owned by this rule group. */
|
|
17
|
+
export const mediaRuleDefinitions = definitions.map(([id, summary, minimumContrastRatio]) => ({ id, minimumContrastRatio, summary }));
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { Rule } from '@ankhorage/rules';
|
|
2
|
+
import type { ResponsiveDesignContext } from '../../types/responsive';
|
|
3
|
+
/*** Creates the independently owned Responsive rule family from normalized viewport facts. */
|
|
4
|
+
export declare function createResponsiveRules(): readonly Rule<ResponsiveDesignContext>[];
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import { evaluateResponsiveOrder } from './evaluateResponsiveOrder';
|
|
2
|
+
import { isContainedInResponsiveBounds } from './isContainedInResponsiveBounds';
|
|
3
|
+
import { parseResponsiveMatrix } from './parseResponsiveMatrix';
|
|
4
|
+
import { responsiveElementsOfKind } from './responsiveElementsOfKind';
|
|
5
|
+
import { selectResponsiveFact } from './selectResponsiveFact';
|
|
6
|
+
/*** Creates the independently owned Responsive rule family from normalized viewport facts. */
|
|
7
|
+
export function createResponsiveRules() {
|
|
8
|
+
return responsiveRuleDefinitions.map(createResponsiveRule);
|
|
9
|
+
}
|
|
10
|
+
const responsiveRuleDefinitions = [
|
|
11
|
+
{
|
|
12
|
+
evaluate: () => pass(),
|
|
13
|
+
id: 'design.responsive.breakpoint-coverage',
|
|
14
|
+
severity: 'warning',
|
|
15
|
+
summary: 'Require every declared breakpoint range to have a viewport measurement.',
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
evaluate: (matrix) => evaluateViewportBoolean(matrix, (viewport) => viewport.layout.renderedWidth > viewport.size.width, 'Layouts did not reflow.'),
|
|
19
|
+
id: 'design.responsive.reflow',
|
|
20
|
+
severity: 'warning',
|
|
21
|
+
summary: 'Require measured layouts to reflow at every declared viewport.',
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
evaluate: (matrix) => evaluateViewportBoolean(matrix, (viewport) => viewport.layout.scrollWidth > viewport.size.width, 'Layouts overflow horizontally.'),
|
|
25
|
+
id: 'design.responsive.horizontal-overflow',
|
|
26
|
+
severity: 'warning',
|
|
27
|
+
summary: 'Require viewport measurements without horizontal overflow.',
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
evaluate: (matrix) => evaluateElementBoolean(matrix, 'text', (element) => element.textLineCount === null || element.textUnwrappedWidth === null
|
|
31
|
+
? null
|
|
32
|
+
: element.textUnwrappedWidth <= element.bounds.width || element.textLineCount > 1, 'Text does not wrap meaningfully.'),
|
|
33
|
+
id: 'design.responsive.text-wrap',
|
|
34
|
+
severity: 'warning',
|
|
35
|
+
summary: 'Require measured text to wrap meaningfully at each viewport.',
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
evaluate: (matrix) => {
|
|
39
|
+
const controls = responsiveElementsOfKind(matrix, 'control');
|
|
40
|
+
if (controls.length === 0)
|
|
41
|
+
return incomplete('No control measurements were supplied.');
|
|
42
|
+
const tooSmall = controls.filter((element) => element.bounds.width < 24 || element.bounds.height < 24);
|
|
43
|
+
return tooSmall.length === 0
|
|
44
|
+
? pass()
|
|
45
|
+
: fail('Controls do not meet the 24 CSS pixel touch-target policy.', tooSmall.map((item) => item.id));
|
|
46
|
+
},
|
|
47
|
+
id: 'design.responsive.touch-target',
|
|
48
|
+
severity: 'warning',
|
|
49
|
+
summary: 'Require measured controls to meet the responsive touch target.',
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
evaluate: evaluateResponsiveOrder,
|
|
53
|
+
id: 'design.responsive.order',
|
|
54
|
+
severity: 'warning',
|
|
55
|
+
summary: 'Require important text to retain its reading order when reflowed.',
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
evaluate: (matrix) => evaluateElementBoolean(matrix, 'image', (element) => element.focalPointBounds === null
|
|
59
|
+
? null
|
|
60
|
+
: isContainedInResponsiveBounds(element.bounds, element.focalPointBounds), 'Image crops hide declared focal content.'),
|
|
61
|
+
id: 'design.responsive.image-crop',
|
|
62
|
+
severity: 'warning',
|
|
63
|
+
summary: 'Advises when measured responsive image crops hide focal content.',
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
evaluate: (matrix) => {
|
|
67
|
+
const problematic = matrix.viewports.flatMap((viewport) => viewport.elements.filter((element) => element.fixedSize !== null &&
|
|
68
|
+
(element.fixedSize.width > viewport.size.width ||
|
|
69
|
+
element.fixedSize.height > viewport.size.height)));
|
|
70
|
+
return problematic.length === 0
|
|
71
|
+
? pass()
|
|
72
|
+
: fail('Problematic fixed dimensions were measured.', problematic.map((item) => item.id));
|
|
73
|
+
},
|
|
74
|
+
id: 'design.responsive.fixed-dimensions',
|
|
75
|
+
severity: 'warning',
|
|
76
|
+
summary: 'Require measurements without problematic fixed dimensions.',
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
evaluate: (matrix) => {
|
|
80
|
+
const zoomed = matrix.viewports.filter((viewport) => viewport.zoom > 1);
|
|
81
|
+
if (zoomed.length === 0)
|
|
82
|
+
return incomplete('No zoomed viewport measurement was supplied.');
|
|
83
|
+
const failures = zoomed.filter((viewport) => viewport.layout.renderedWidth > viewport.size.width);
|
|
84
|
+
return failures.length === 0
|
|
85
|
+
? pass()
|
|
86
|
+
: fail('Layouts do not reflow under zoom.', failures.map((item) => item.id));
|
|
87
|
+
},
|
|
88
|
+
id: 'design.responsive.zoom-reflow',
|
|
89
|
+
severity: 'warning',
|
|
90
|
+
summary: 'Require a zoomed viewport measurement whose layout reflows.',
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
evaluate: (matrix) => {
|
|
94
|
+
const observed = new Set(matrix.viewports.map((viewport) => viewport.orientation));
|
|
95
|
+
const missing = matrix.requiredOrientations.filter((orientation) => !observed.has(orientation));
|
|
96
|
+
if (missing.length > 0)
|
|
97
|
+
return incomplete('Required orientation measurements were not supplied.', missing);
|
|
98
|
+
const failures = matrix.viewports.filter((viewport) => viewport.layout.renderedWidth > viewport.size.width ||
|
|
99
|
+
viewport.layout.scrollWidth > viewport.size.width);
|
|
100
|
+
return failures.length === 0
|
|
101
|
+
? pass()
|
|
102
|
+
: fail('Layouts are not robust across orientation.', failures.map((item) => item.id));
|
|
103
|
+
},
|
|
104
|
+
id: 'design.responsive.orientation',
|
|
105
|
+
severity: 'warning',
|
|
106
|
+
summary: 'Require declared portrait and landscape measurements to remain robust.',
|
|
107
|
+
},
|
|
108
|
+
];
|
|
109
|
+
/*** Creates one generic Rules contract from a responsive policy definition. */
|
|
110
|
+
function createResponsiveRule(definition) {
|
|
111
|
+
return {
|
|
112
|
+
defaultSeverity: definition.severity,
|
|
113
|
+
dependencies: [],
|
|
114
|
+
evaluate: ({ context, scope }) => evaluateResponsiveRule(context.facts, definition, scope),
|
|
115
|
+
identity: { id: definition.id, version: '1.0.0' },
|
|
116
|
+
requiredCapabilities: ['viewport.layout', 'viewport.matrix'],
|
|
117
|
+
summary: definition.summary,
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
/*** Evaluates one rule only from available, normalized responsive matrix facts. */
|
|
121
|
+
function evaluateResponsiveRule(facts, definition, scope) {
|
|
122
|
+
const fact = selectResponsiveFact(facts, scope);
|
|
123
|
+
if (fact === null) {
|
|
124
|
+
return outcome(definition.id, 'INCOMPLETE', 'Responsive viewport measurements are unavailable.', []);
|
|
125
|
+
}
|
|
126
|
+
const matrix = parseResponsiveMatrix(fact.value);
|
|
127
|
+
if (matrix === null) {
|
|
128
|
+
return outcome(definition.id, 'INCOMPLETE', 'Responsive viewport measurements are malformed.', [
|
|
129
|
+
fact.id,
|
|
130
|
+
]);
|
|
131
|
+
}
|
|
132
|
+
if (matrix.viewports.length === 0) {
|
|
133
|
+
return outcome(definition.id, 'INCOMPLETE', 'No responsive viewport measurements were supplied.', [], [fact.id]);
|
|
134
|
+
}
|
|
135
|
+
const missingBreakpointIds = requiredBreakpointIds(matrix);
|
|
136
|
+
if (missingBreakpointIds.length > 0) {
|
|
137
|
+
return outcome(definition.id, 'INCOMPLETE', 'Required breakpoint viewport measurements were not supplied.', missingBreakpointIds, [fact.id]);
|
|
138
|
+
}
|
|
139
|
+
const evaluation = definition.evaluate(matrix);
|
|
140
|
+
return outcome(definition.id, evaluation.status, evaluation.message, evaluation.failingIds, [
|
|
141
|
+
fact.id,
|
|
142
|
+
]);
|
|
143
|
+
}
|
|
144
|
+
/*** Lists declared breakpoint IDs that lack their required viewport evidence. */
|
|
145
|
+
function requiredBreakpointIds(matrix) {
|
|
146
|
+
const observedIds = new Set(matrix.viewports.map((viewport) => viewport.id));
|
|
147
|
+
return matrix.requiredBreakpointIds.filter((id) => !observedIds.has(id));
|
|
148
|
+
}
|
|
149
|
+
/*** Builds an engine finding without allowing a missing measurement to look successful. */
|
|
150
|
+
function outcome(ruleId, status, message, subjectIds, factIds = []) {
|
|
151
|
+
return status === 'PASS'
|
|
152
|
+
? { findings: [], status }
|
|
153
|
+
: {
|
|
154
|
+
findings: [
|
|
155
|
+
{
|
|
156
|
+
evidence: { factIds, subjectIds },
|
|
157
|
+
message,
|
|
158
|
+
ruleId,
|
|
159
|
+
severity: 'info',
|
|
160
|
+
subjects: subjectIds.map((id) => ({ id, kind: 'responsive-measurement' })),
|
|
161
|
+
},
|
|
162
|
+
],
|
|
163
|
+
status,
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
/*** Returns a passing responsive policy evaluation. */
|
|
167
|
+
function pass() {
|
|
168
|
+
return { failingIds: [], message: '', status: 'PASS' };
|
|
169
|
+
}
|
|
170
|
+
/*** Returns a failed responsive policy evaluation with its measured subjects. */
|
|
171
|
+
function fail(message, failingIds) {
|
|
172
|
+
return { failingIds, message, status: 'FAIL' };
|
|
173
|
+
}
|
|
174
|
+
/*** Returns an incomplete responsive policy evaluation when measurements are absent. */
|
|
175
|
+
function incomplete(message, failingIds = []) {
|
|
176
|
+
return { failingIds, message, status: 'INCOMPLETE' };
|
|
177
|
+
}
|
|
178
|
+
/*** Evaluates a required boolean viewport measurement. */
|
|
179
|
+
function evaluateViewportBoolean(matrix, isFailure, message) {
|
|
180
|
+
const failures = matrix.viewports.filter(isFailure);
|
|
181
|
+
return failures.length === 0
|
|
182
|
+
? pass()
|
|
183
|
+
: fail(message, failures.map((item) => item.id));
|
|
184
|
+
}
|
|
185
|
+
/*** Evaluates a required boolean element measurement for one semantic element kind. */
|
|
186
|
+
function evaluateElementBoolean(matrix, kind, observed, message) {
|
|
187
|
+
const elements = responsiveElementsOfKind(matrix, kind);
|
|
188
|
+
if (elements.length === 0)
|
|
189
|
+
return incomplete(`No ${kind} measurements were supplied.`);
|
|
190
|
+
const unknown = elements.filter((element) => observed(element) === null);
|
|
191
|
+
if (unknown.length > 0)
|
|
192
|
+
return incomplete(`${kind} measurements are incomplete.`, unknown.map((item) => item.id));
|
|
193
|
+
const failures = elements.filter((element) => observed(element) === false);
|
|
194
|
+
return failures.length === 0
|
|
195
|
+
? pass()
|
|
196
|
+
: fail(message, failures.map((item) => item.id));
|
|
197
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { ResponsiveEvaluation, ResponsiveMatrix } from '../../types/responsive';
|
|
2
|
+
/*** Assesses reading and visual order only when all measured text order values are available. */
|
|
3
|
+
export declare function evaluateResponsiveOrder(matrix: ResponsiveMatrix): ResponsiveEvaluation;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { responsiveElementsOfKind } from './responsiveElementsOfKind';
|
|
2
|
+
/*** Assesses reading and visual order only when all measured text order values are available. */
|
|
3
|
+
export function evaluateResponsiveOrder(matrix) {
|
|
4
|
+
const text = responsiveElementsOfKind(matrix, 'text');
|
|
5
|
+
if (text.length === 0)
|
|
6
|
+
return incomplete('No reading and visual order measurements were supplied.');
|
|
7
|
+
const incompleteOrder = text.filter((element) => element.readingOrder === null || element.visualOrder === null);
|
|
8
|
+
if (incompleteOrder.length > 0) {
|
|
9
|
+
return incomplete('Reading and visual order measurements are incomplete.', incompleteOrder.map((item) => item.id));
|
|
10
|
+
}
|
|
11
|
+
const reordered = text
|
|
12
|
+
.filter(hasOrder)
|
|
13
|
+
.filter((element) => element.readingOrder !== element.visualOrder);
|
|
14
|
+
return reordered.length === 0
|
|
15
|
+
? pass()
|
|
16
|
+
: fail('Visual order differs from reading order.', reordered.map((item) => item.id));
|
|
17
|
+
}
|
|
18
|
+
/*** Narrows a text observation to complete reading and visual order measurements. */
|
|
19
|
+
function hasOrder(element) {
|
|
20
|
+
return element.readingOrder !== null && element.visualOrder !== null;
|
|
21
|
+
}
|
|
22
|
+
/*** Returns a passing order assessment. */
|
|
23
|
+
function pass() {
|
|
24
|
+
return { failingIds: [], message: '', status: 'PASS' };
|
|
25
|
+
}
|
|
26
|
+
/*** Returns a failed or incomplete order assessment with affected text identities. */
|
|
27
|
+
function fail(message, failingIds) {
|
|
28
|
+
return { failingIds, message, status: 'FAIL' };
|
|
29
|
+
}
|
|
30
|
+
/*** Returns an incomplete order assessment when measurements are absent. */
|
|
31
|
+
function incomplete(message, failingIds = []) {
|
|
32
|
+
return { failingIds, message, status: 'INCOMPLETE' };
|
|
33
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { ResponsiveElement } from '../../types/responsive';
|
|
2
|
+
/*** Checks whether measured focal geometry remains within the image's visible bounds. */
|
|
3
|
+
export declare function isContainedInResponsiveBounds(container: ResponsiveElement['bounds'], candidate: ResponsiveElement['bounds']): boolean;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/*** Checks whether measured focal geometry remains within the image's visible bounds. */
|
|
2
|
+
export function isContainedInResponsiveBounds(container, candidate) {
|
|
3
|
+
return (candidate.x >= container.x &&
|
|
4
|
+
candidate.y >= container.y &&
|
|
5
|
+
candidate.x + candidate.width <= container.x + container.width &&
|
|
6
|
+
candidate.y + candidate.height <= container.y + container.height);
|
|
7
|
+
}
|