@ankhorage/rules-design 0.9.2 → 0.9.4
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 +12 -0
- package/README.md +1 -1
- package/dist/features/website-recognition/recognizeWebsiteStructure.js +53 -23
- package/dist/features/website-recognition/websiteStructureEvidence.d.ts +2 -1
- package/dist/features/website-recognition/websiteStructureEvidence.js +111 -12
- package/dist/features/website-recognition/websiteStructureSemantics.d.ts +3 -2
- package/dist/features/website-recognition/websiteStructureSemantics.js +16 -4
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.4
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- c0b4205: Recognize HTML and ARIA navigation and main landmarks as canonical website regions while retaining source-linked responsive evidence.
|
|
8
|
+
|
|
9
|
+
## 0.9.3
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- 94478d7: Recognize independently visible website cards and provider-neutral CSS dividers.
|
|
14
|
+
|
|
3
15
|
## 0.9.2
|
|
4
16
|
|
|
5
17
|
### Patch Changes
|
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
|
|
|
@@ -23,13 +23,46 @@ function recognizePage(page) {
|
|
|
23
23
|
nodes: allRecognitions.flatMap((recognition) => recognition.nodes),
|
|
24
24
|
path: page.path,
|
|
25
25
|
root: {
|
|
26
|
-
children: allRecognitions
|
|
26
|
+
children: pageRootChildren(allRecognitions),
|
|
27
27
|
id: `${page.id}:root`,
|
|
28
28
|
type: 'Container',
|
|
29
29
|
},
|
|
30
30
|
url: page.url,
|
|
31
31
|
};
|
|
32
32
|
}
|
|
33
|
+
/*** Adds one analysis-only Main grouping when no observed main landmark owns page content. */
|
|
34
|
+
function pageRootChildren(recognitions) {
|
|
35
|
+
if (recognitions.some((recognition) => containsComponentType(recognition.uiNode, 'Main')))
|
|
36
|
+
return recognitions.map((recognition) => recognition.uiNode);
|
|
37
|
+
return groupPageContentAsMain(recognitions.map((recognition) => recognition.uiNode));
|
|
38
|
+
}
|
|
39
|
+
/*** Preserves DOM order while grouping non-chrome root content without introducing layout semantics. */
|
|
40
|
+
function groupPageContentAsMain(nodes) {
|
|
41
|
+
return nodes.flatMap((node, index) => {
|
|
42
|
+
if (isPageChrome(node))
|
|
43
|
+
return [node];
|
|
44
|
+
if (index > 0 && !isPageChrome(nodes[index - 1]))
|
|
45
|
+
return [];
|
|
46
|
+
const nextChromeOffset = nodes.slice(index).findIndex(isPageChrome);
|
|
47
|
+
const content = nodes.slice(index, nextChromeOffset === -1 ? undefined : index + nextChromeOffset);
|
|
48
|
+
return [
|
|
49
|
+
{
|
|
50
|
+
children: content,
|
|
51
|
+
id: 'page:main',
|
|
52
|
+
type: 'Main',
|
|
53
|
+
},
|
|
54
|
+
];
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
/*** Limits synthetic page grouping to site-chrome siblings so local regions stay in their parents. */
|
|
58
|
+
function isPageChrome(node) {
|
|
59
|
+
return node.type === 'Footer' || node.type === 'Header';
|
|
60
|
+
}
|
|
61
|
+
/*** Detects an observed main landmark anywhere in the preserved recursive source tree. */
|
|
62
|
+
function containsComponentType(node, componentType) {
|
|
63
|
+
return (node.type === componentType ||
|
|
64
|
+
(node.children ?? []).some((child) => containsComponentType(child, componentType)));
|
|
65
|
+
}
|
|
33
66
|
/*** Indexes observed children in DOM order for deterministic parent traversal. */
|
|
34
67
|
function createChildNodesByParent(nodes) {
|
|
35
68
|
const entries = nodes.reduce((childrenByParent, node) => {
|
|
@@ -96,14 +129,15 @@ function recognizeComponentType(node, parent, childNodesByParent) {
|
|
|
96
129
|
const observation = websiteStructureEvidence(node).availableObservation;
|
|
97
130
|
if (observation === null)
|
|
98
131
|
return 'Unknown';
|
|
99
|
-
const
|
|
100
|
-
const semanticType = recognizeWebsiteStructureSemanticComponentType(tagName);
|
|
132
|
+
const semanticType = recognizeWebsiteStructureSemanticComponentType(node);
|
|
101
133
|
if (semanticType !== null)
|
|
102
134
|
return semanticType;
|
|
103
135
|
const { css } = observation;
|
|
104
136
|
if (css === null)
|
|
105
137
|
return 'Unknown';
|
|
106
|
-
if (
|
|
138
|
+
if (websiteStructureEvidence(node).hasDividerEvidence)
|
|
139
|
+
return 'Divider';
|
|
140
|
+
if (isCard(node, parent, childNodesByParent))
|
|
107
141
|
return 'Card';
|
|
108
142
|
if (css.display.includes('grid'))
|
|
109
143
|
return 'Grid';
|
|
@@ -117,29 +151,25 @@ function recognizeComponentType(node, parent, childNodesByParent) {
|
|
|
117
151
|
return 'RichText';
|
|
118
152
|
return websiteStructureEvidence(node).hasVisualRole ? 'Container' : 'Unknown';
|
|
119
153
|
}
|
|
120
|
-
/*** Recognizes
|
|
121
|
-
function
|
|
122
|
-
|
|
154
|
+
/*** Recognizes one rendered layout child with an independently visible surface boundary as a card. */
|
|
155
|
+
function isCard(node, parent, childNodesByParent) {
|
|
156
|
+
return (parent !== null &&
|
|
157
|
+
isLayoutGroup(parent) &&
|
|
158
|
+
websiteStructureEvidence(node, [], parent).hasCardSurface &&
|
|
159
|
+
!ownsNestedSurfaceLayout(node, childNodesByParent));
|
|
160
|
+
}
|
|
161
|
+
/*** Keeps a layout container distinct when it owns independently bounded layout children. */
|
|
162
|
+
function ownsNestedSurfaceLayout(node, childNodesByParent) {
|
|
163
|
+
if (!isLayoutGroup(node))
|
|
123
164
|
return false;
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
const children = childNodesByParent.get(parentSourceRef) ?? [];
|
|
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
|
-
});
|
|
165
|
+
return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
|
|
166
|
+
}
|
|
167
|
+
/*** Limits nested layout ownership to generic wrappers so semantic content never hides its card root. */
|
|
168
|
+
function isGenericSurfaceNode(node) {
|
|
169
|
+
return ['div', 'span'].includes(node.dom.tagName.toLowerCase());
|
|
136
170
|
}
|
|
137
171
|
/*** Tests whether a parent has measured Grid or Flex grouping semantics. */
|
|
138
172
|
function isLayoutGroup(node) {
|
|
139
173
|
const css = websiteStructureEvidence(node).availableObservation?.css;
|
|
140
174
|
return css === null || css === undefined ? false : /grid|flex/.test(css.display);
|
|
141
175
|
}
|
|
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
|
}
|
|
@@ -1,2 +1,3 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
import type { WebsiteObservedNode } from '@ankhorage/contracts/website';
|
|
2
|
+
/*** Maps explicit HTML and observed ARIA semantics without relying on framework selectors. */
|
|
3
|
+
export declare function recognizeWebsiteStructureSemanticComponentType(node: WebsiteObservedNode): string | null;
|
|
@@ -1,9 +1,21 @@
|
|
|
1
|
-
/*** Maps explicit HTML semantics without relying on framework
|
|
2
|
-
export function recognizeWebsiteStructureSemanticComponentType(
|
|
1
|
+
/*** Maps explicit HTML and observed ARIA semantics without relying on framework selectors. */
|
|
2
|
+
export function recognizeWebsiteStructureSemanticComponentType(node) {
|
|
3
|
+
const role = semanticRole(node);
|
|
4
|
+
if (role === 'navigation')
|
|
5
|
+
return 'Nav';
|
|
6
|
+
const tagName = node.dom.tagName.toLowerCase();
|
|
3
7
|
if (/^h[1-6]$/.test(tagName))
|
|
4
8
|
return 'Heading';
|
|
5
9
|
return semanticComponentTypes.find(([name]) => name === tagName)?.[1] ?? null;
|
|
6
10
|
}
|
|
11
|
+
/*** Retains the first explicit DOM or rendered ARIA role without inventing semantics. */
|
|
12
|
+
function semanticRole(node) {
|
|
13
|
+
const roles = [
|
|
14
|
+
Object.hasOwn(node.dom.attributes, 'role') ? node.dom.attributes.role : null,
|
|
15
|
+
...node.observations.map((observation) => observation.semanticAttributes?.role),
|
|
16
|
+
];
|
|
17
|
+
return roles.find((role) => typeof role === 'string') ?? null;
|
|
18
|
+
}
|
|
7
19
|
const semanticComponentTypes = [
|
|
8
20
|
['a', 'Link'],
|
|
9
21
|
['address', 'RichText'],
|
|
@@ -27,9 +39,9 @@ const semanticComponentTypes = [
|
|
|
27
39
|
['img', 'Image'],
|
|
28
40
|
['label', 'RichText'],
|
|
29
41
|
['li', 'ListItem'],
|
|
30
|
-
['main', '
|
|
42
|
+
['main', 'Main'],
|
|
31
43
|
['menu', 'List'],
|
|
32
|
-
['nav', '
|
|
44
|
+
['nav', 'Nav'],
|
|
33
45
|
['ol', 'List'],
|
|
34
46
|
['p', 'RichText'],
|
|
35
47
|
['section', 'Section'],
|