@ankhorage/rules-design 0.9.1 → 0.9.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/recognition/recognizeWebsiteDocument.js +2 -0
- package/dist/features/website-recognition/recognizeWebsiteSiteChrome.d.ts +3 -0
- package/dist/features/website-recognition/recognizeWebsiteSiteChrome.js +189 -0
- package/package.json +2 -2
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
|
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { recognizeWebsiteSiteChrome } from '../website-recognition/recognizeWebsiteSiteChrome';
|
|
1
2
|
import { recognizeWebsiteStructure } from '../website-recognition/recognizeWebsiteStructure';
|
|
2
3
|
import { createWebsiteAssetIndex } from './createWebsiteAssetIndex';
|
|
3
4
|
import { qualifyWebsiteRecognitionProps } from './qualifyWebsiteRecognitionProps';
|
|
@@ -21,6 +22,7 @@ export function recognizeWebsiteDocument(document) {
|
|
|
21
22
|
recognizedAt: document.collectedAt,
|
|
22
23
|
schemaVersion: 1,
|
|
23
24
|
site: document.site,
|
|
25
|
+
siteChrome: recognizeWebsiteSiteChrome(document, pages),
|
|
24
26
|
source: document.source,
|
|
25
27
|
};
|
|
26
28
|
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { WebsiteObservationDocument, WebsitePageRecognition, WebsiteRecognitionDocument } from '@ankhorage/contracts/website';
|
|
2
|
+
/*** Recognizes page-grounded header and footer candidates without asserting cross-page identity. */
|
|
3
|
+
export declare function recognizeWebsiteSiteChrome(document: WebsiteObservationDocument, pages: readonly WebsitePageRecognition[]): WebsiteRecognitionDocument['siteChrome'];
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
/*** Recognizes page-grounded header and footer candidates without asserting cross-page identity. */
|
|
2
|
+
export function recognizeWebsiteSiteChrome(document, pages) {
|
|
3
|
+
return {
|
|
4
|
+
candidates: document.pages.flatMap((page) => {
|
|
5
|
+
const recognition = pages.find((candidate) => candidate.id === page.id);
|
|
6
|
+
if (recognition === undefined)
|
|
7
|
+
throw new TypeError(`Missing recognition for page ${page.id}.`);
|
|
8
|
+
const nodesBySourceRef = new Map(page.nodes.map((node) => [node.sourceRef, node]));
|
|
9
|
+
return page.nodes.flatMap((node) => {
|
|
10
|
+
const role = siteChromeRole(node);
|
|
11
|
+
return role === null || hasSameRoleLandmarkAncestor(node, role, nodesBySourceRef)
|
|
12
|
+
? []
|
|
13
|
+
: [createCandidate(page.id, node, role, nodesBySourceRef, recognition)];
|
|
14
|
+
});
|
|
15
|
+
}),
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
/*** Creates one source-specific candidate so later consumers, not this recognizer, compare pages. */
|
|
19
|
+
function createCandidate(pageId, node, role, nodesBySourceRef, page) {
|
|
20
|
+
const source = sourceEvidence(pageId, node, nodesBySourceRef);
|
|
21
|
+
const subtree = subtreeFor(page, pageId, node.sourceRef);
|
|
22
|
+
const local = hasLocalContentAncestor(node, nodesBySourceRef, page, pageId, hasExplicitLandmarkRole(node));
|
|
23
|
+
const uncertainty = node.observations.flatMap((observation) => observation.availability.status === 'missing' && observation.availability.missing !== null
|
|
24
|
+
? [observation.availability.missing]
|
|
25
|
+
: []);
|
|
26
|
+
return {
|
|
27
|
+
classification: local ? 'page-local' : 'site-candidate',
|
|
28
|
+
confidence: local ? 0.5 : 0.9,
|
|
29
|
+
id: JSON.stringify([role, pageId, node.sourceRef]),
|
|
30
|
+
memberships: [
|
|
31
|
+
{
|
|
32
|
+
pageId,
|
|
33
|
+
source,
|
|
34
|
+
state: hasConditionalObservation(node) ? 'variant' : 'present',
|
|
35
|
+
subtree,
|
|
36
|
+
},
|
|
37
|
+
],
|
|
38
|
+
role,
|
|
39
|
+
uncertainty,
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/*** Identifies HTML landmarks unless an explicit ARIA role overrides their ownership. */
|
|
43
|
+
function siteChromeRole(node) {
|
|
44
|
+
if (Object.hasOwn(node.dom.attributes, 'role'))
|
|
45
|
+
return landmarkRoleFor(node.dom.attributes.role);
|
|
46
|
+
const observedRole = node.observations
|
|
47
|
+
.map((observation) => observation.semanticAttributes?.role)
|
|
48
|
+
.find((role) => typeof role === 'string');
|
|
49
|
+
if (observedRole !== undefined)
|
|
50
|
+
return landmarkRoleFor(observedRole);
|
|
51
|
+
const tagName = node.dom.tagName.toLowerCase();
|
|
52
|
+
if (tagName === 'header' || tagName === 'footer')
|
|
53
|
+
return tagName;
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
/*** Maps only ARIA landmark roles that own site chrome. */
|
|
57
|
+
function landmarkRoleFor(role) {
|
|
58
|
+
if (role === 'banner')
|
|
59
|
+
return 'header';
|
|
60
|
+
if (role === 'contentinfo')
|
|
61
|
+
return 'footer';
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
/*** Distinguishes explicit ARIA landmark evidence from implicit HTML landmark semantics. */
|
|
65
|
+
function hasExplicitLandmarkRole(node) {
|
|
66
|
+
return (landmarkRoleFor(node.dom.attributes.role) !== null ||
|
|
67
|
+
node.observations.some((observation) => landmarkRoleFor(observation.semanticAttributes?.role) !== null));
|
|
68
|
+
}
|
|
69
|
+
/*** Suppresses nested duplicates while retaining their UI descendants in the owning landmark subtree. */
|
|
70
|
+
function hasSameRoleLandmarkAncestor(node, role, nodesBySourceRef) {
|
|
71
|
+
return ancestorNodes(node, nodesBySourceRef).some((ancestor) => siteChromeRole(ancestor) === role);
|
|
72
|
+
}
|
|
73
|
+
/*** Preserves raw DOM, landmark, and viewport evidence with page-qualified source identity. */
|
|
74
|
+
function sourceEvidence(pageId, node, nodesBySourceRef) {
|
|
75
|
+
return {
|
|
76
|
+
ancestorSourceRefs: ancestorSourceRefs(pageId, node, nodesBySourceRef),
|
|
77
|
+
dom: node.dom,
|
|
78
|
+
observations: node.observations.map((observation) => ({
|
|
79
|
+
availability: observation.availability,
|
|
80
|
+
...(observation.semanticAttributes === undefined
|
|
81
|
+
? {}
|
|
82
|
+
: { semanticAttributes: observation.semanticAttributes }),
|
|
83
|
+
rect: observation.rect,
|
|
84
|
+
stateId: observation.stateId,
|
|
85
|
+
viewportId: observation.viewportId,
|
|
86
|
+
visibility: visibilityOf(observation),
|
|
87
|
+
})),
|
|
88
|
+
parentSourceRef: node.parentSourceRef === null ? null : sourceIdentity(pageId, node.parentSourceRef),
|
|
89
|
+
semantics: {
|
|
90
|
+
ariaLabel: ariaLabel(node),
|
|
91
|
+
role: semanticRole(node),
|
|
92
|
+
},
|
|
93
|
+
sourceRef: sourceIdentity(pageId, node.sourceRef),
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
/*** Retains the first explicit DOM or viewport ARIA role without normalizing its literal. */
|
|
97
|
+
function semanticRole(node) {
|
|
98
|
+
const roles = [
|
|
99
|
+
Object.hasOwn(node.dom.attributes, 'role') ? node.dom.attributes.role : null,
|
|
100
|
+
...node.observations.map((observation) => observation.semanticAttributes?.role),
|
|
101
|
+
];
|
|
102
|
+
return roles.find((role) => typeof role === 'string') ?? null;
|
|
103
|
+
}
|
|
104
|
+
/*** Reads an accessible label from DOM or viewport-specific semantic evidence without fabrication. */
|
|
105
|
+
function ariaLabel(node) {
|
|
106
|
+
const labels = [
|
|
107
|
+
node.dom.attributes['aria-label'],
|
|
108
|
+
...node.observations.map((observation) => observation.semanticAttributes?.['aria-label']),
|
|
109
|
+
];
|
|
110
|
+
return labels.find((label) => typeof label === 'string') ?? null;
|
|
111
|
+
}
|
|
112
|
+
/*** Converts measured CSS visibility to the bounded portable visibility vocabulary. */
|
|
113
|
+
function visibilityOf(observation) {
|
|
114
|
+
if (observation.availability.status !== 'available' || observation.css === null)
|
|
115
|
+
return 'unknown';
|
|
116
|
+
return observation.css.display === 'none' ||
|
|
117
|
+
observation.css.visibility === 'hidden' ||
|
|
118
|
+
observation.css.visibility === 'collapse' ||
|
|
119
|
+
observation.css.opacity === '0'
|
|
120
|
+
? 'hidden'
|
|
121
|
+
: 'visible';
|
|
122
|
+
}
|
|
123
|
+
/*** Classifies differing measured visibility or availability as a real responsive/state variant. */
|
|
124
|
+
function hasConditionalObservation(node) {
|
|
125
|
+
const states = node.observations.map((observation) => `${observation.availability.status}:${visibilityOf(observation)}`);
|
|
126
|
+
return new Set(states).size > 1;
|
|
127
|
+
}
|
|
128
|
+
/*** Finds content-owned ancestors from DOM lineage and canonical recognized card mappings. */
|
|
129
|
+
function hasLocalContentAncestor(node, nodesBySourceRef, page, pageId, hasExplicitLandmark) {
|
|
130
|
+
return ancestorNodes(node, nodesBySourceRef).some((ancestor) => {
|
|
131
|
+
const tagName = ancestor.dom.tagName.toLowerCase();
|
|
132
|
+
const recognized = page.nodes.find((candidate) => candidate.id === sourceIdentity(pageId, ancestor.sourceRef));
|
|
133
|
+
return (['article', 'aside', 'main'].includes(tagName) ||
|
|
134
|
+
(!hasExplicitLandmark && tagName === 'section') ||
|
|
135
|
+
recognized?.componentType === 'Card');
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
/*** Traverses actual parent references with cycle protection instead of trusting optional ancestry hints. */
|
|
139
|
+
function ancestorNodes(node, nodesBySourceRef) {
|
|
140
|
+
const ancestors = [];
|
|
141
|
+
const seen = new Set([node.sourceRef]);
|
|
142
|
+
let { parentSourceRef } = node;
|
|
143
|
+
while (parentSourceRef !== null && !seen.has(parentSourceRef)) {
|
|
144
|
+
const parent = nodesBySourceRef.get(parentSourceRef);
|
|
145
|
+
if (parent === undefined)
|
|
146
|
+
break;
|
|
147
|
+
ancestors.push(parent);
|
|
148
|
+
seen.add(parent.sourceRef);
|
|
149
|
+
const { parentSourceRef: nextParentSourceRef } = parent;
|
|
150
|
+
parentSourceRef = nextParentSourceRef;
|
|
151
|
+
}
|
|
152
|
+
return ancestors;
|
|
153
|
+
}
|
|
154
|
+
/*** Qualifies ancestor references consistently with the public recognition document. */
|
|
155
|
+
function ancestorSourceRefs(pageId, node, nodesBySourceRef) {
|
|
156
|
+
return ancestorNodes(node, nodesBySourceRef).map((ancestor) => sourceIdentity(pageId, ancestor.sourceRef));
|
|
157
|
+
}
|
|
158
|
+
/*** Retains the complete recursive UI subtree and its ordered recognized-node traversal. */
|
|
159
|
+
function subtreeFor(page, pageId, sourceRef) {
|
|
160
|
+
const root = findUiNode(page.root, sourceIdentity(pageId, sourceRef));
|
|
161
|
+
if (root === null)
|
|
162
|
+
return null;
|
|
163
|
+
const nodeIds = uiNodeIds(root);
|
|
164
|
+
const nodesById = new Map(page.nodes.map((node) => [node.id, node]));
|
|
165
|
+
const nodes = nodeIds.flatMap((id) => {
|
|
166
|
+
const node = nodesById.get(id);
|
|
167
|
+
return node === undefined ? [] : [node];
|
|
168
|
+
});
|
|
169
|
+
return { nodes, root };
|
|
170
|
+
}
|
|
171
|
+
/*** Locates a source-qualified UI node without flattening or recreating its child tree. */
|
|
172
|
+
function findUiNode(node, id) {
|
|
173
|
+
if (node.id === id)
|
|
174
|
+
return node;
|
|
175
|
+
for (const child of node.children ?? []) {
|
|
176
|
+
const match = findUiNode(child, id);
|
|
177
|
+
if (match !== null)
|
|
178
|
+
return match;
|
|
179
|
+
}
|
|
180
|
+
return null;
|
|
181
|
+
}
|
|
182
|
+
/*** Enumerates a UI subtree in deterministic pre-order so node evidence matches tree order. */
|
|
183
|
+
function uiNodeIds(node) {
|
|
184
|
+
return [node.id, ...(node.children ?? []).flatMap(uiNodeIds)];
|
|
185
|
+
}
|
|
186
|
+
/*** Uses the established page-qualified source identity format for public provenance. */
|
|
187
|
+
function sourceIdentity(pageId, sourceRef) {
|
|
188
|
+
return JSON.stringify([pageId, sourceRef]);
|
|
189
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ankhorage/rules-design",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.2",
|
|
4
4
|
"description": "Declarative catalog for reusable design rules.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/ankhorage/rules-design#readme",
|
|
@@ -106,7 +106,7 @@
|
|
|
106
106
|
"dependencies": {
|
|
107
107
|
"@ankhorage/ankh": "^0.13.4",
|
|
108
108
|
"@ankhorage/capability": "^0.2.2",
|
|
109
|
-
"@ankhorage/contracts": "
|
|
109
|
+
"@ankhorage/contracts": "26.12.0",
|
|
110
110
|
"@ankhorage/rules": "^0.4.0",
|
|
111
111
|
"@ankhorage/utility": "^1.10.0"
|
|
112
112
|
}
|