@ankhorage/rules-design 0.9.0 → 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 +12 -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/dist/features/website-recognition/recognizeWebsiteStructure.js +17 -81
- package/dist/features/website-recognition/websiteStructureEvidence.d.ts +10 -0
- package/dist/features/website-recognition/websiteStructureEvidence.js +88 -0
- package/dist/features/website-recognition/websiteStructureSemantics.js +14 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- b614a47: Recognize source-grounded site header and footer evidence without asserting cross-page identity.
|
|
8
|
+
|
|
9
|
+
## 0.9.1
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- 3346adc: Recognize semantic HTML landmarks and content alongside evidence-backed layout, card, and transparent-wrapper structures without losing child provenance.
|
|
14
|
+
|
|
3
15
|
## 0.9.0
|
|
4
16
|
|
|
5
17
|
### Minor 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
|
|
|
@@ -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
|
+
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { recognizeWebsiteStructureProps } from './recognizeWebsiteStructureProps';
|
|
2
|
+
import { websiteStructureEvidence } from './websiteStructureEvidence';
|
|
2
3
|
import { recognizeWebsiteStructureSemanticComponentType } from './websiteStructureSemantics';
|
|
3
4
|
import { createWebsiteStructureTreeNode } from './websiteStructureTreeNodes';
|
|
4
5
|
/*** Recognizes source-linked canonical component trees from validated website observations. */
|
|
@@ -52,7 +53,8 @@ function recognizeTreeNode(node, nodesBySourceRef, childNodesByParent, effective
|
|
|
52
53
|
return [];
|
|
53
54
|
}
|
|
54
55
|
const children = childNodesByParent.get(node.sourceRef) ?? [];
|
|
55
|
-
if (!isCyclicSourceRef(node, nodesBySourceRef) &&
|
|
56
|
+
if (!isCyclicSourceRef(node, nodesBySourceRef) &&
|
|
57
|
+
websiteStructureEvidence(node, children).isTransparentWrapper) {
|
|
56
58
|
return children.flatMap((child) => recognizeTreeNode(child, nodesBySourceRef, childNodesByParent, effectiveParentSourceRef, [...inheritedSourceRefs, node.sourceRef], [...ancestorSourceRefs, node.sourceRef]));
|
|
57
59
|
}
|
|
58
60
|
const childRecognitions = children.flatMap((child) => recognizeTreeNode(child, nodesBySourceRef, childNodesByParent, node.sourceRef, [], [...ancestorSourceRefs, node.sourceRef]));
|
|
@@ -69,7 +71,7 @@ function createRecognizedTreeNode(node, parent, childNodesByParent, nodesBySourc
|
|
|
69
71
|
const props = recognizeWebsiteStructureProps(node);
|
|
70
72
|
return createWebsiteStructureTreeNode(node, componentType, [...inheritedSourceRefs, node.sourceRef], props, children, cyclic
|
|
71
73
|
? 'Source hierarchy contains a cycle.'
|
|
72
|
-
:
|
|
74
|
+
: websiteStructureEvidence(node).availableObservation === null
|
|
73
75
|
? 'No available rendered observation exists for this source node.'
|
|
74
76
|
: 'Visible source node has no canonical component mapping.');
|
|
75
77
|
}
|
|
@@ -89,44 +91,31 @@ function isCyclicSourceRef(node, nodesBySourceRef) {
|
|
|
89
91
|
function containsSourceRef(recognitions, sourceRef) {
|
|
90
92
|
return recognitions.some((recognition) => recognition.nodes.some((node) => node.sourceRefs.includes(sourceRef)));
|
|
91
93
|
}
|
|
92
|
-
/*** Identifies wrappers with no independently meaningful semantic, textual, media, or visual role. */
|
|
93
|
-
function isTransparentWrapper(node, children) {
|
|
94
|
-
const observation = availableObservation(node);
|
|
95
|
-
const tagName = node.dom.tagName.toLowerCase();
|
|
96
|
-
return (children.length > 0 &&
|
|
97
|
-
node.links.length === 0 &&
|
|
98
|
-
node.media.length === 0 &&
|
|
99
|
-
node.textRuns.length === 0 &&
|
|
100
|
-
(tagName === 'div' || tagName === 'span') &&
|
|
101
|
-
observation !== null &&
|
|
102
|
-
!hasLayoutRole(observation) &&
|
|
103
|
-
!hasSurfaceRole(observation));
|
|
104
|
-
}
|
|
105
94
|
/*** Maps observed DOM semantics and measured layout traits to already representable UI components. */
|
|
106
95
|
function recognizeComponentType(node, parent, childNodesByParent) {
|
|
107
|
-
const observation =
|
|
96
|
+
const observation = websiteStructureEvidence(node).availableObservation;
|
|
108
97
|
if (observation === null)
|
|
109
98
|
return 'Unknown';
|
|
110
99
|
const tagName = node.dom.tagName.toLowerCase();
|
|
111
100
|
const semanticType = recognizeWebsiteStructureSemanticComponentType(tagName);
|
|
112
101
|
if (semanticType !== null)
|
|
113
102
|
return semanticType;
|
|
114
|
-
if (node.media.length > 0)
|
|
115
|
-
return node.media.every((media) => media.kind === 'image') ? 'Image' : 'Media';
|
|
116
|
-
if (node.links.length > 0)
|
|
117
|
-
return 'Link';
|
|
118
|
-
if (node.textRuns.length > 0)
|
|
119
|
-
return 'RichText';
|
|
120
|
-
if (isGroupedCard(node, parent, childNodesByParent))
|
|
121
|
-
return 'Card';
|
|
122
103
|
const { css } = observation;
|
|
123
104
|
if (css === null)
|
|
124
105
|
return 'Unknown';
|
|
106
|
+
if (isGroupedCard(node, parent, childNodesByParent))
|
|
107
|
+
return 'Card';
|
|
125
108
|
if (css.display.includes('grid'))
|
|
126
109
|
return 'Grid';
|
|
127
110
|
if (css.display.includes('flex'))
|
|
128
111
|
return 'Flex';
|
|
129
|
-
|
|
112
|
+
if (node.media.length > 0)
|
|
113
|
+
return node.media.every((media) => media.kind === 'image') ? 'Image' : 'Media';
|
|
114
|
+
if (node.links.length > 0)
|
|
115
|
+
return 'Link';
|
|
116
|
+
if (node.textRuns.length > 0)
|
|
117
|
+
return 'RichText';
|
|
118
|
+
return websiteStructureEvidence(node).hasVisualRole ? 'Container' : 'Unknown';
|
|
130
119
|
}
|
|
131
120
|
/*** Recognizes a card only when a measured sibling group shares explicit surface traits. */
|
|
132
121
|
function isGroupedCard(node, parent, childNodesByParent) {
|
|
@@ -140,70 +129,17 @@ function meaningfulChildren(parentSourceRef, childNodesByParent) {
|
|
|
140
129
|
const children = childNodesByParent.get(parentSourceRef) ?? [];
|
|
141
130
|
return children.flatMap((child) => {
|
|
142
131
|
const nestedChildren = childNodesByParent.get(child.sourceRef) ?? [];
|
|
143
|
-
return
|
|
132
|
+
return websiteStructureEvidence(child, nestedChildren).isTransparentWrapper
|
|
144
133
|
? meaningfulChildren(child.sourceRef, childNodesByParent)
|
|
145
134
|
: [child];
|
|
146
135
|
});
|
|
147
136
|
}
|
|
148
137
|
/*** Tests whether a parent has measured Grid or Flex grouping semantics. */
|
|
149
138
|
function isLayoutGroup(node) {
|
|
150
|
-
const css =
|
|
139
|
+
const css = websiteStructureEvidence(node).availableObservation?.css;
|
|
151
140
|
return css === null || css === undefined ? false : /grid|flex/.test(css.display);
|
|
152
141
|
}
|
|
153
142
|
/*** Requires padding plus radius, border, or shadow so colored columns are not invented as cards. */
|
|
154
143
|
function isCardSurface(node) {
|
|
155
|
-
|
|
156
|
-
const css = observation?.css;
|
|
157
|
-
return (css !== null &&
|
|
158
|
-
css !== undefined &&
|
|
159
|
-
hasNonZeroEdge(css.padding) &&
|
|
160
|
-
(hasNonZeroCssValue(css.borderRadius) ||
|
|
161
|
-
hasNonZeroCssValue(css.borderWidth) ||
|
|
162
|
-
css.boxShadow !== 'none'));
|
|
163
|
-
}
|
|
164
|
-
/*** Selects a visible available observation deterministically without inventing a missing style. */
|
|
165
|
-
function availableObservation(node) {
|
|
166
|
-
return ([...node.observations]
|
|
167
|
-
.sort((left, right) => left.viewportId.localeCompare(right.viewportId) ||
|
|
168
|
-
left.stateId.localeCompare(right.stateId))
|
|
169
|
-
.find((observation) => observation.availability.status === 'available' &&
|
|
170
|
-
observation.css !== null &&
|
|
171
|
-
observation.rect !== null &&
|
|
172
|
-
observation.rect.width > 0 &&
|
|
173
|
-
observation.rect.height > 0 &&
|
|
174
|
-
observation.css.display !== 'none' &&
|
|
175
|
-
observation.css.visibility !== 'hidden' &&
|
|
176
|
-
observation.css.visibility !== 'collapse' &&
|
|
177
|
-
observation.css.opacity !== '0') ?? null);
|
|
178
|
-
}
|
|
179
|
-
/*** Identifies layout evidence that gives an otherwise generic container a real component role. */
|
|
180
|
-
function hasLayoutRole(observation) {
|
|
181
|
-
const { css } = observation;
|
|
182
|
-
return (css !== null &&
|
|
183
|
-
(css.display.includes('grid') ||
|
|
184
|
-
css.display.includes('flex') ||
|
|
185
|
-
hasNonZeroEdge(css.padding) ||
|
|
186
|
-
hasNonZeroEdge(css.margin) ||
|
|
187
|
-
hasNonZeroCssValue(css.gap)));
|
|
188
|
-
}
|
|
189
|
-
/*** Identifies measured border, radius, background, or shadow evidence for a visual container. */
|
|
190
|
-
function hasSurfaceRole(observation) {
|
|
191
|
-
const { css } = observation;
|
|
192
|
-
return (css !== null &&
|
|
193
|
-
(hasNonZeroCssValue(css.borderRadius) ||
|
|
194
|
-
hasNonZeroCssValue(css.borderWidth) ||
|
|
195
|
-
css.boxShadow !== 'none' ||
|
|
196
|
-
!isTransparentColor(css.backgroundColor)));
|
|
197
|
-
}
|
|
198
|
-
/*** Tests CSS box edges without parsing or normalizing their original literals. */
|
|
199
|
-
function hasNonZeroEdge(edges) {
|
|
200
|
-
return [edges.top, edges.right, edges.bottom, edges.left].some(hasNonZeroCssValue);
|
|
201
|
-
}
|
|
202
|
-
/*** Detects non-zero CSS literals while preserving their exact source value elsewhere. */
|
|
203
|
-
function hasNonZeroCssValue(value) {
|
|
204
|
-
return value !== '0' && value !== '0px' && value !== 'normal' && value !== 'auto';
|
|
205
|
-
}
|
|
206
|
-
/*** Recognizes the transparent computed color forms without assigning a color token. */
|
|
207
|
-
function isTransparentColor(value) {
|
|
208
|
-
return value === 'transparent' || value === 'rgba(0, 0, 0, 0)';
|
|
144
|
+
return websiteStructureEvidence(node).hasCardSurface;
|
|
209
145
|
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { WebsiteNodeObservation, WebsiteObservedNode } from '@ankhorage/contracts/website';
|
|
2
|
+
/*** Collects complete evidence needed to classify an observed website structure node. */
|
|
3
|
+
export declare function websiteStructureEvidence(node: WebsiteObservedNode, children?: readonly WebsiteObservedNode[]): WebsiteStructureEvidence;
|
|
4
|
+
interface WebsiteStructureEvidence {
|
|
5
|
+
readonly availableObservation: WebsiteNodeObservation | null;
|
|
6
|
+
readonly hasCardSurface: boolean;
|
|
7
|
+
readonly hasVisualRole: boolean;
|
|
8
|
+
readonly isTransparentWrapper: boolean;
|
|
9
|
+
}
|
|
10
|
+
export {};
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/*** Collects complete evidence needed to classify an observed website structure node. */
|
|
2
|
+
export function websiteStructureEvidence(node, children = []) {
|
|
3
|
+
return {
|
|
4
|
+
availableObservation: availableObservation(node),
|
|
5
|
+
hasCardSurface: hasCardSurface(node),
|
|
6
|
+
hasVisualRole: hasVisualRole(node),
|
|
7
|
+
isTransparentWrapper: isTransparentWrapper(node, children),
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
/*** Selects a visible available observation deterministically without inventing a missing style. */
|
|
11
|
+
function availableObservation(node) {
|
|
12
|
+
return ([...node.observations]
|
|
13
|
+
.sort((left, right) => left.viewportId.localeCompare(right.viewportId) ||
|
|
14
|
+
left.stateId.localeCompare(right.stateId))
|
|
15
|
+
.find((observation) => observation.availability.status === 'available' &&
|
|
16
|
+
observation.css !== null &&
|
|
17
|
+
observation.rect !== null &&
|
|
18
|
+
observation.rect.width > 0 &&
|
|
19
|
+
observation.rect.height > 0 &&
|
|
20
|
+
observation.css.display !== 'none' &&
|
|
21
|
+
observation.css.visibility !== 'hidden' &&
|
|
22
|
+
observation.css.visibility !== 'collapse' &&
|
|
23
|
+
observation.css.opacity !== '0') ?? null);
|
|
24
|
+
}
|
|
25
|
+
/*** Requires padding plus radius, border, or shadow so colored columns are not invented as cards. */
|
|
26
|
+
function hasCardSurface(node) {
|
|
27
|
+
const css = availableObservation(node)?.css;
|
|
28
|
+
return (css !== null &&
|
|
29
|
+
css !== undefined &&
|
|
30
|
+
hasNonZeroEdge(css.padding) &&
|
|
31
|
+
(hasNonZeroCssValue(css.borderRadius) ||
|
|
32
|
+
hasNonZeroCssValue(css.borderWidth) ||
|
|
33
|
+
css.boxShadow !== 'none'));
|
|
34
|
+
}
|
|
35
|
+
/*** Tests whether a visible observation gives a generic node a layout or surface role. */
|
|
36
|
+
function hasVisualRole(node) {
|
|
37
|
+
const observation = availableObservation(node);
|
|
38
|
+
return observation !== null && (hasLayoutRole(observation) || hasSurfaceRole(observation));
|
|
39
|
+
}
|
|
40
|
+
/*** Identifies wrappers only when complete observations prove no independent role. */
|
|
41
|
+
function isTransparentWrapper(node, children) {
|
|
42
|
+
const tagName = node.dom.tagName.toLowerCase();
|
|
43
|
+
return (children.length > 0 &&
|
|
44
|
+
node.links.length === 0 &&
|
|
45
|
+
node.media.length === 0 &&
|
|
46
|
+
node.textRuns.length === 0 &&
|
|
47
|
+
(tagName === 'div' || tagName === 'span') &&
|
|
48
|
+
node.observations.length > 0 &&
|
|
49
|
+
node.observations.every(isTransparentObservation));
|
|
50
|
+
}
|
|
51
|
+
/*** Requires usable CSS evidence and excludes every measured layout or surface role. */
|
|
52
|
+
function isTransparentObservation(observation) {
|
|
53
|
+
return (observation.availability.status === 'available' &&
|
|
54
|
+
observation.css !== null &&
|
|
55
|
+
!hasLayoutRole(observation) &&
|
|
56
|
+
!hasSurfaceRole(observation));
|
|
57
|
+
}
|
|
58
|
+
/*** Identifies layout evidence that gives an otherwise generic container a real component role. */
|
|
59
|
+
function hasLayoutRole(observation) {
|
|
60
|
+
const { css } = observation;
|
|
61
|
+
return (css !== null &&
|
|
62
|
+
(css.display.includes('grid') ||
|
|
63
|
+
css.display.includes('flex') ||
|
|
64
|
+
hasNonZeroEdge(css.padding) ||
|
|
65
|
+
hasNonZeroEdge(css.margin) ||
|
|
66
|
+
hasNonZeroCssValue(css.gap)));
|
|
67
|
+
}
|
|
68
|
+
/*** Identifies measured border, radius, background, or shadow evidence for a visual container. */
|
|
69
|
+
function hasSurfaceRole(observation) {
|
|
70
|
+
const { css } = observation;
|
|
71
|
+
return (css !== null &&
|
|
72
|
+
(hasNonZeroCssValue(css.borderRadius) ||
|
|
73
|
+
hasNonZeroCssValue(css.borderWidth) ||
|
|
74
|
+
css.boxShadow !== 'none' ||
|
|
75
|
+
!isTransparentColor(css.backgroundColor)));
|
|
76
|
+
}
|
|
77
|
+
/*** Tests CSS box edges without parsing or normalizing their original literals. */
|
|
78
|
+
function hasNonZeroEdge(edges) {
|
|
79
|
+
return [edges.top, edges.right, edges.bottom, edges.left].some(hasNonZeroCssValue);
|
|
80
|
+
}
|
|
81
|
+
/*** Detects non-zero CSS literals while preserving their exact source value elsewhere. */
|
|
82
|
+
function hasNonZeroCssValue(value) {
|
|
83
|
+
return value !== '0' && value !== '0px' && value !== 'normal' && value !== 'auto';
|
|
84
|
+
}
|
|
85
|
+
/*** Recognizes transparent computed-color forms without assigning a color token. */
|
|
86
|
+
function isTransparentColor(value) {
|
|
87
|
+
return value === 'transparent' || value === 'rgba(0, 0, 0, 0)';
|
|
88
|
+
}
|
|
@@ -6,22 +6,36 @@ export function recognizeWebsiteStructureSemanticComponentType(tagName) {
|
|
|
6
6
|
}
|
|
7
7
|
const semanticComponentTypes = [
|
|
8
8
|
['a', 'Link'],
|
|
9
|
+
['address', 'RichText'],
|
|
10
|
+
['aside', 'Container'],
|
|
9
11
|
['article', 'Container'],
|
|
10
12
|
['audio', 'Media'],
|
|
11
13
|
['body', 'Container'],
|
|
12
14
|
['blockquote', 'RichText'],
|
|
13
15
|
['button', 'Button'],
|
|
16
|
+
['dd', 'ListItem'],
|
|
17
|
+
['details', 'Container'],
|
|
18
|
+
['dl', 'List'],
|
|
19
|
+
['dt', 'ListItem'],
|
|
20
|
+
['em', 'RichText'],
|
|
14
21
|
['footer', 'Footer'],
|
|
15
22
|
['form', 'Form'],
|
|
23
|
+
['figure', 'Container'],
|
|
24
|
+
['figcaption', 'RichText'],
|
|
16
25
|
['header', 'Header'],
|
|
17
26
|
['iframe', 'Media'],
|
|
18
27
|
['img', 'Image'],
|
|
19
28
|
['label', 'RichText'],
|
|
20
29
|
['li', 'ListItem'],
|
|
21
30
|
['main', 'Container'],
|
|
31
|
+
['menu', 'List'],
|
|
32
|
+
['nav', 'Container'],
|
|
22
33
|
['ol', 'List'],
|
|
23
34
|
['p', 'RichText'],
|
|
24
35
|
['section', 'Section'],
|
|
36
|
+
['small', 'RichText'],
|
|
37
|
+
['strong', 'RichText'],
|
|
38
|
+
['summary', 'RichText'],
|
|
25
39
|
['ul', 'List'],
|
|
26
40
|
['video', 'Media'],
|
|
27
41
|
];
|
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
|
}
|