@ankhorage/rules-design 0.9.2 → 0.9.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 +6 -0
- package/README.md +1 -1
- package/dist/features/website-recognition/recognizeWebsiteStructure.js +17 -19
- package/dist/features/website-recognition/websiteStructureEvidence.d.ts +2 -1
- package/dist/features/website-recognition/websiteStructureEvidence.js +111 -12
- 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
|
|
|
@@ -103,7 +103,9 @@ function recognizeComponentType(node, parent, childNodesByParent) {
|
|
|
103
103
|
const { css } = observation;
|
|
104
104
|
if (css === null)
|
|
105
105
|
return 'Unknown';
|
|
106
|
-
if (
|
|
106
|
+
if (websiteStructureEvidence(node).hasDividerEvidence)
|
|
107
|
+
return 'Divider';
|
|
108
|
+
if (isCard(node, parent, childNodesByParent))
|
|
107
109
|
return 'Card';
|
|
108
110
|
if (css.display.includes('grid'))
|
|
109
111
|
return 'Grid';
|
|
@@ -117,29 +119,25 @@ function recognizeComponentType(node, parent, childNodesByParent) {
|
|
|
117
119
|
return 'RichText';
|
|
118
120
|
return websiteStructureEvidence(node).hasVisualRole ? 'Container' : 'Unknown';
|
|
119
121
|
}
|
|
120
|
-
/*** Recognizes
|
|
121
|
-
function
|
|
122
|
-
|
|
122
|
+
/*** Recognizes one rendered layout child with an independently visible surface boundary as a card. */
|
|
123
|
+
function isCard(node, parent, childNodesByParent) {
|
|
124
|
+
return (parent !== null &&
|
|
125
|
+
isLayoutGroup(parent) &&
|
|
126
|
+
websiteStructureEvidence(node, [], parent).hasCardSurface &&
|
|
127
|
+
!ownsNestedSurfaceLayout(node, childNodesByParent));
|
|
128
|
+
}
|
|
129
|
+
/*** Keeps a layout container distinct when it owns independently bounded layout children. */
|
|
130
|
+
function ownsNestedSurfaceLayout(node, childNodesByParent) {
|
|
131
|
+
if (!isLayoutGroup(node))
|
|
123
132
|
return false;
|
|
124
|
-
|
|
125
|
-
return siblings.length >= 2 && siblings.every(isCardSurface) && isCardSurface(node);
|
|
133
|
+
return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
|
|
126
134
|
}
|
|
127
|
-
/***
|
|
128
|
-
function
|
|
129
|
-
|
|
130
|
-
return children.flatMap((child) => {
|
|
131
|
-
const nestedChildren = childNodesByParent.get(child.sourceRef) ?? [];
|
|
132
|
-
return websiteStructureEvidence(child, nestedChildren).isTransparentWrapper
|
|
133
|
-
? meaningfulChildren(child.sourceRef, childNodesByParent)
|
|
134
|
-
: [child];
|
|
135
|
-
});
|
|
135
|
+
/*** Limits nested layout ownership to generic wrappers so semantic content never hides its card root. */
|
|
136
|
+
function isGenericSurfaceNode(node) {
|
|
137
|
+
return ['div', 'span'].includes(node.dom.tagName.toLowerCase());
|
|
136
138
|
}
|
|
137
139
|
/*** Tests whether a parent has measured Grid or Flex grouping semantics. */
|
|
138
140
|
function isLayoutGroup(node) {
|
|
139
141
|
const css = websiteStructureEvidence(node).availableObservation?.css;
|
|
140
142
|
return css === null || css === undefined ? false : /grid|flex/.test(css.display);
|
|
141
143
|
}
|
|
142
|
-
/*** Requires padding plus radius, border, or shadow so colored columns are not invented as cards. */
|
|
143
|
-
function isCardSurface(node) {
|
|
144
|
-
return websiteStructureEvidence(node).hasCardSurface;
|
|
145
|
-
}
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import type { WebsiteNodeObservation, WebsiteObservedNode } from '@ankhorage/contracts/website';
|
|
2
2
|
/*** Collects complete evidence needed to classify an observed website structure node. */
|
|
3
|
-
export declare function websiteStructureEvidence(node: WebsiteObservedNode, children?: readonly WebsiteObservedNode[]): WebsiteStructureEvidence;
|
|
3
|
+
export declare function websiteStructureEvidence(node: WebsiteObservedNode, children?: readonly WebsiteObservedNode[], parent?: WebsiteObservedNode | null): WebsiteStructureEvidence;
|
|
4
4
|
interface WebsiteStructureEvidence {
|
|
5
5
|
readonly availableObservation: WebsiteNodeObservation | null;
|
|
6
6
|
readonly hasCardSurface: boolean;
|
|
7
|
+
readonly hasDividerEvidence: boolean;
|
|
7
8
|
readonly hasVisualRole: boolean;
|
|
8
9
|
readonly isTransparentWrapper: boolean;
|
|
9
10
|
}
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
/*** Collects complete evidence needed to classify an observed website structure node. */
|
|
2
|
-
export function websiteStructureEvidence(node, children = []) {
|
|
2
|
+
export function websiteStructureEvidence(node, children = [], parent = null) {
|
|
3
3
|
return {
|
|
4
4
|
availableObservation: availableObservation(node),
|
|
5
|
-
hasCardSurface: hasCardSurface(node),
|
|
5
|
+
hasCardSurface: hasCardSurface(node, parent),
|
|
6
|
+
hasDividerEvidence: hasDividerEvidence(node),
|
|
6
7
|
hasVisualRole: hasVisualRole(node),
|
|
7
8
|
isTransparentWrapper: isTransparentWrapper(node, children),
|
|
8
9
|
};
|
|
@@ -22,15 +23,113 @@ function availableObservation(node) {
|
|
|
22
23
|
observation.css.visibility !== 'collapse' &&
|
|
23
24
|
observation.css.opacity !== '0') ?? null);
|
|
24
25
|
}
|
|
25
|
-
/***
|
|
26
|
-
function
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
26
|
+
/*** Tests whether one observation proves a rendered, visible CSS box. */
|
|
27
|
+
function isVisibleObservation(observation) {
|
|
28
|
+
return (observation.availability.status === 'available' &&
|
|
29
|
+
observation.css !== null &&
|
|
30
|
+
observation.rect !== null &&
|
|
31
|
+
observation.rect.width > 0 &&
|
|
32
|
+
observation.rect.height > 0 &&
|
|
33
|
+
observation.css.display !== 'none' &&
|
|
34
|
+
observation.css.visibility !== 'hidden' &&
|
|
35
|
+
observation.css.visibility !== 'collapse' &&
|
|
36
|
+
observation.css.opacity !== '0');
|
|
37
|
+
}
|
|
38
|
+
/*** Finds a visible node-owned surface boundary without inferring one from padding or radius. */
|
|
39
|
+
function hasCardSurface(node, parent) {
|
|
40
|
+
return node.observations.some((observation) => {
|
|
41
|
+
const parentObservation = parent === null ? null : observationFor(parent, observation);
|
|
42
|
+
return (isVisibleObservation(observation) && hasVisibleSurfaceBoundary(observation, parentObservation));
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
/*** Identifies a visible horizontal or vertical line with independent divider semantics or geometry. */
|
|
46
|
+
function hasDividerEvidence(node) {
|
|
47
|
+
const tagName = node.dom.tagName.toLowerCase();
|
|
48
|
+
return node.observations.some((observation) => isVisibleObservation(observation) &&
|
|
49
|
+
observation.css !== null &&
|
|
50
|
+
observation.rect !== null &&
|
|
51
|
+
hasVisibleSurfaceBoundary(observation, null) &&
|
|
52
|
+
(tagName === 'hr' ||
|
|
53
|
+
observation.semanticAttributes?.role === 'separator' ||
|
|
54
|
+
hasDividerGeometry(observation.rect.width, observation.rect.height)));
|
|
55
|
+
}
|
|
56
|
+
/*** Finds the observation for the same viewport and rendered state without mixing responsive evidence. */
|
|
57
|
+
function observationFor(node, observation) {
|
|
58
|
+
return (node.observations.find((candidate) => candidate.viewportId === observation.viewportId &&
|
|
59
|
+
candidate.stateId === observation.stateId) ?? null);
|
|
60
|
+
}
|
|
61
|
+
/*** Tests whether a measured rectangle has the proportions of a rendered separator line. */
|
|
62
|
+
function hasDividerGeometry(width, height) {
|
|
63
|
+
const shorterSide = Math.min(width, height);
|
|
64
|
+
const longerSide = Math.max(width, height);
|
|
65
|
+
return shorterSide <= 4 && longerSide >= 16 && longerSide / Math.max(shorterSide, 1) >= 8;
|
|
66
|
+
}
|
|
67
|
+
/*** Requires one directly visible boundary feature owned by the node. */
|
|
68
|
+
function hasVisibleSurfaceBoundary(observation, parentObservation) {
|
|
69
|
+
const { css } = observation;
|
|
70
|
+
if (css === null)
|
|
71
|
+
return false;
|
|
72
|
+
return (hasVisibleBackground(css.backgroundColor, parentObservation?.css?.backgroundColor ?? null) ||
|
|
73
|
+
css.backgroundImage !== 'none' ||
|
|
74
|
+
(hasNonZeroCssValue(css.borderWidth) && !isTransparentColor(css.borderColor)) ||
|
|
75
|
+
hasVisibleBoxShadow(css.boxShadow));
|
|
76
|
+
}
|
|
77
|
+
/*** Compares composited CSS colors so transparent backgrounds remain surface evidence when visible. */
|
|
78
|
+
function hasVisibleBackground(backgroundColor, parentBackgroundColor) {
|
|
79
|
+
const color = parseCssColor(backgroundColor);
|
|
80
|
+
if (color === null)
|
|
81
|
+
return !isTransparentColor(backgroundColor) && backgroundColor !== parentBackgroundColor;
|
|
82
|
+
if (color.alpha === 0)
|
|
83
|
+
return false;
|
|
84
|
+
if (parentBackgroundColor === null)
|
|
85
|
+
return true;
|
|
86
|
+
const parentColor = parseCssColor(parentBackgroundColor);
|
|
87
|
+
if (parentColor === null)
|
|
88
|
+
return backgroundColor !== parentBackgroundColor;
|
|
89
|
+
return !sameColor(compositeColor(color, parentColor), parentColor);
|
|
90
|
+
}
|
|
91
|
+
/*** Parses browser-computed rgb and rgba color values without fabricating color tokens. */
|
|
92
|
+
function parseCssColor(value) {
|
|
93
|
+
if (value === 'transparent')
|
|
94
|
+
return { alpha: 0, blue: 0, green: 0, red: 0 };
|
|
95
|
+
const match = /^rgba?\(\s*([\d.]+)[,\s]+\s*([\d.]+)[,\s]+\s*([\d.]+)(?:\s*[,/]\s*([\d.]+))?\s*\)$/.exec(value);
|
|
96
|
+
if (match === null)
|
|
97
|
+
return null;
|
|
98
|
+
const alpha = match.at(-1);
|
|
99
|
+
return {
|
|
100
|
+
alpha: alpha === undefined ? 1 : Number(alpha),
|
|
101
|
+
blue: Number(match[3]),
|
|
102
|
+
green: Number(match[2]),
|
|
103
|
+
red: Number(match[1]),
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
/*** Composites a foreground color over its observed parent background. */
|
|
107
|
+
function compositeColor(foreground, background) {
|
|
108
|
+
const alpha = foreground.alpha + background.alpha * (1 - foreground.alpha);
|
|
109
|
+
if (alpha === 0)
|
|
110
|
+
return { alpha: 0, blue: 0, green: 0, red: 0 };
|
|
111
|
+
const compositeChannel = (foregroundChannel, backgroundChannel) => (foregroundChannel * foreground.alpha +
|
|
112
|
+
backgroundChannel * background.alpha * (1 - foreground.alpha)) /
|
|
113
|
+
alpha;
|
|
114
|
+
return {
|
|
115
|
+
alpha,
|
|
116
|
+
blue: compositeChannel(foreground.blue, background.blue),
|
|
117
|
+
green: compositeChannel(foreground.green, background.green),
|
|
118
|
+
red: compositeChannel(foreground.red, background.red),
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
/*** Compares parsed colors with a small tolerance for browser-computed floating point values. */
|
|
122
|
+
function sameColor(left, right) {
|
|
123
|
+
return [
|
|
124
|
+
left.red - right.red,
|
|
125
|
+
left.green - right.green,
|
|
126
|
+
left.blue - right.blue,
|
|
127
|
+
left.alpha - right.alpha,
|
|
128
|
+
].every((difference) => Math.abs(difference) < 0.001);
|
|
129
|
+
}
|
|
130
|
+
/*** Excludes shadows whose entire computed color is transparent. */
|
|
131
|
+
function hasVisibleBoxShadow(value) {
|
|
132
|
+
return value !== 'none' && !/rgba\([^)]*,\s*0\s*\)/.test(value);
|
|
34
133
|
}
|
|
35
134
|
/*** Tests whether a visible observation gives a generic node a layout or surface role. */
|
|
36
135
|
function hasVisualRole(node) {
|
|
@@ -84,5 +183,5 @@ function hasNonZeroCssValue(value) {
|
|
|
84
183
|
}
|
|
85
184
|
/*** Recognizes transparent computed-color forms without assigning a color token. */
|
|
86
185
|
function isTransparentColor(value) {
|
|
87
|
-
return value === 'transparent' || value ===
|
|
186
|
+
return value === 'transparent' || parseCssColor(value)?.alpha === 0;
|
|
88
187
|
}
|