@ankhorage/rules-design 0.9.3 → 0.10.0
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/createWebsiteRecognitionRuleSet.d.ts +4 -0
- package/dist/features/website-recognition/createWebsiteRecognitionRuleSet.js +58 -0
- package/dist/features/website-recognition/recognizeWebsiteStructure.js +40 -23
- package/dist/features/website-recognition/websiteStructureEvidence.d.ts +1 -0
- package/dist/features/website-recognition/websiteStructureEvidence.js +31 -14
- package/dist/features/website-recognition/websiteStructureSemantics.d.ts +3 -2
- package/dist/features/website-recognition/websiteStructureSemantics.js +16 -4
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/types/websiteRecognitionRules.d.ts +7 -0
- package/dist/types/websiteRecognitionRules.js +0 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.10.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- d6ba244: Define versioned website Card recognition through the canonical Rules evaluator with reusable, inspectable owned-background and shadow signals. Decorative borders and radius no longer imply Cards.
|
|
8
|
+
|
|
9
|
+
## 0.9.4
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- c0b4205: Recognize HTML and ARIA navigation and main landmarks as canonical website regions while retaining source-linked responsive evidence.
|
|
14
|
+
|
|
3
15
|
## 0.9.3
|
|
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
|
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { RuleSet } from '@ankhorage/rules';
|
|
2
|
+
import type { WebsiteRecognitionRuleContext } from '../../types/websiteRecognitionRules';
|
|
3
|
+
/*** Declares the versioned, provider-neutral Card predicate in the canonical Rules format. */
|
|
4
|
+
export declare function createWebsiteRecognitionRuleSet(): RuleSet<WebsiteRecognitionRuleContext>;
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { websiteStructureEvidence } from './websiteStructureEvidence';
|
|
2
|
+
/*** Declares the versioned, provider-neutral Card predicate in the canonical Rules format. */
|
|
3
|
+
export function createWebsiteRecognitionRuleSet() {
|
|
4
|
+
return {
|
|
5
|
+
id: 'ankhorage.rules-design.website-recognition',
|
|
6
|
+
rules: [cardRecognitionRule],
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
const cardRecognitionRule = {
|
|
10
|
+
defaultSeverity: 'info',
|
|
11
|
+
dependencies: [],
|
|
12
|
+
identity: { id: 'design.website-recognition.card', version: '1.0.0' },
|
|
13
|
+
summary: 'A layout child owns a visible background or shadow independent of its layout cell.',
|
|
14
|
+
evaluate: ({ context }) => evaluateCardRecognition(context),
|
|
15
|
+
};
|
|
16
|
+
/*** PASS means Card match; FAIL means no match, not a quality or policy violation. */
|
|
17
|
+
function evaluateCardRecognition(context) {
|
|
18
|
+
const { node, parent, childNodesByParent } = context;
|
|
19
|
+
const evidence = websiteStructureEvidence(node, [], parent);
|
|
20
|
+
if (evidence.availableObservation === null)
|
|
21
|
+
return { findings: [], status: 'INCOMPLETE' };
|
|
22
|
+
if (!isLayoutGroup(parent) ||
|
|
23
|
+
ownsNestedSurfaceLayout(node, childNodesByParent) ||
|
|
24
|
+
!evidence.hasCardSurface)
|
|
25
|
+
return { findings: [], status: 'FAIL' };
|
|
26
|
+
return {
|
|
27
|
+
findings: [
|
|
28
|
+
{
|
|
29
|
+
evidence: {
|
|
30
|
+
signals: evidence.cardSurfaceReasons,
|
|
31
|
+
sourceRef: node.sourceRef,
|
|
32
|
+
},
|
|
33
|
+
message: 'This layout child owns a visible Card surface.',
|
|
34
|
+
ruleId: cardRecognitionRule.identity.id,
|
|
35
|
+
severity: 'info',
|
|
36
|
+
subjects: [{ id: node.sourceRef, kind: 'website-node' }],
|
|
37
|
+
},
|
|
38
|
+
],
|
|
39
|
+
status: 'PASS',
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/*** Prevents a layout owning separately bounded children from being their Card wrapper. */
|
|
43
|
+
function ownsNestedSurfaceLayout(node, childNodesByParent) {
|
|
44
|
+
if (!isLayoutGroup(node))
|
|
45
|
+
return false;
|
|
46
|
+
return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
|
|
47
|
+
}
|
|
48
|
+
/*** Checks measured Flex/Grid layout semantics without creating synthetic layout nodes. */
|
|
49
|
+
function isLayoutGroup(node) {
|
|
50
|
+
if (node === null)
|
|
51
|
+
return false;
|
|
52
|
+
const css = websiteStructureEvidence(node).availableObservation?.css;
|
|
53
|
+
return css !== null && css !== undefined && /grid|flex/u.test(css.display);
|
|
54
|
+
}
|
|
55
|
+
/*** Generic wrappers may own nested surfaces; semantic descendants retain their own type. */
|
|
56
|
+
function isGenericSurfaceNode(node) {
|
|
57
|
+
return ['div', 'span'].includes(node.dom.tagName.toLowerCase());
|
|
58
|
+
}
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { evaluateRules } from '@ankhorage/rules';
|
|
2
|
+
import { createWebsiteRecognitionRuleSet } from './createWebsiteRecognitionRuleSet';
|
|
1
3
|
import { recognizeWebsiteStructureProps } from './recognizeWebsiteStructureProps';
|
|
2
4
|
import { websiteStructureEvidence } from './websiteStructureEvidence';
|
|
3
5
|
import { recognizeWebsiteStructureSemanticComponentType } from './websiteStructureSemantics';
|
|
@@ -23,13 +25,46 @@ function recognizePage(page) {
|
|
|
23
25
|
nodes: allRecognitions.flatMap((recognition) => recognition.nodes),
|
|
24
26
|
path: page.path,
|
|
25
27
|
root: {
|
|
26
|
-
children: allRecognitions
|
|
28
|
+
children: pageRootChildren(allRecognitions),
|
|
27
29
|
id: `${page.id}:root`,
|
|
28
30
|
type: 'Container',
|
|
29
31
|
},
|
|
30
32
|
url: page.url,
|
|
31
33
|
};
|
|
32
34
|
}
|
|
35
|
+
/*** Adds one analysis-only Main grouping when no observed main landmark owns page content. */
|
|
36
|
+
function pageRootChildren(recognitions) {
|
|
37
|
+
if (recognitions.some((recognition) => containsComponentType(recognition.uiNode, 'Main')))
|
|
38
|
+
return recognitions.map((recognition) => recognition.uiNode);
|
|
39
|
+
return groupPageContentAsMain(recognitions.map((recognition) => recognition.uiNode));
|
|
40
|
+
}
|
|
41
|
+
/*** Preserves DOM order while grouping non-chrome root content without introducing layout semantics. */
|
|
42
|
+
function groupPageContentAsMain(nodes) {
|
|
43
|
+
return nodes.flatMap((node, index) => {
|
|
44
|
+
if (isPageChrome(node))
|
|
45
|
+
return [node];
|
|
46
|
+
if (index > 0 && !isPageChrome(nodes[index - 1]))
|
|
47
|
+
return [];
|
|
48
|
+
const nextChromeOffset = nodes.slice(index).findIndex(isPageChrome);
|
|
49
|
+
const content = nodes.slice(index, nextChromeOffset === -1 ? undefined : index + nextChromeOffset);
|
|
50
|
+
return [
|
|
51
|
+
{
|
|
52
|
+
children: content,
|
|
53
|
+
id: 'page:main',
|
|
54
|
+
type: 'Main',
|
|
55
|
+
},
|
|
56
|
+
];
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
/*** Limits synthetic page grouping to site-chrome siblings so local regions stay in their parents. */
|
|
60
|
+
function isPageChrome(node) {
|
|
61
|
+
return node.type === 'Footer' || node.type === 'Header';
|
|
62
|
+
}
|
|
63
|
+
/*** Detects an observed main landmark anywhere in the preserved recursive source tree. */
|
|
64
|
+
function containsComponentType(node, componentType) {
|
|
65
|
+
return (node.type === componentType ||
|
|
66
|
+
(node.children ?? []).some((child) => containsComponentType(child, componentType)));
|
|
67
|
+
}
|
|
33
68
|
/*** Indexes observed children in DOM order for deterministic parent traversal. */
|
|
34
69
|
function createChildNodesByParent(nodes) {
|
|
35
70
|
const entries = nodes.reduce((childrenByParent, node) => {
|
|
@@ -96,8 +131,7 @@ function recognizeComponentType(node, parent, childNodesByParent) {
|
|
|
96
131
|
const observation = websiteStructureEvidence(node).availableObservation;
|
|
97
132
|
if (observation === null)
|
|
98
133
|
return 'Unknown';
|
|
99
|
-
const
|
|
100
|
-
const semanticType = recognizeWebsiteStructureSemanticComponentType(tagName);
|
|
134
|
+
const semanticType = recognizeWebsiteStructureSemanticComponentType(node);
|
|
101
135
|
if (semanticType !== null)
|
|
102
136
|
return semanticType;
|
|
103
137
|
const { css } = observation;
|
|
@@ -119,25 +153,8 @@ function recognizeComponentType(node, parent, childNodesByParent) {
|
|
|
119
153
|
return 'RichText';
|
|
120
154
|
return websiteStructureEvidence(node).hasVisualRole ? 'Container' : 'Unknown';
|
|
121
155
|
}
|
|
122
|
-
/***
|
|
156
|
+
/*** Evaluates the versioned canonical Card rule before committing a primary module type. */
|
|
123
157
|
function isCard(node, parent, childNodesByParent) {
|
|
124
|
-
|
|
125
|
-
|
|
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))
|
|
132
|
-
return false;
|
|
133
|
-
return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
|
|
134
|
-
}
|
|
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());
|
|
138
|
-
}
|
|
139
|
-
/*** Tests whether a parent has measured Grid or Flex grouping semantics. */
|
|
140
|
-
function isLayoutGroup(node) {
|
|
141
|
-
const css = websiteStructureEvidence(node).availableObservation?.css;
|
|
142
|
-
return css === null || css === undefined ? false : /grid|flex/.test(css.display);
|
|
158
|
+
const evaluation = evaluateRules({ childNodesByParent, node, parent }, createWebsiteRecognitionRuleSet().rules, { scope: { id: node.sourceRef, kind: 'website-node' } });
|
|
159
|
+
return evaluation.results.some((result) => result.status === 'PASS');
|
|
143
160
|
}
|
|
@@ -3,6 +3,7 @@ import type { WebsiteNodeObservation, WebsiteObservedNode } from '@ankhorage/con
|
|
|
3
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
|
+
readonly cardSurfaceReasons: readonly string[];
|
|
6
7
|
readonly hasCardSurface: boolean;
|
|
7
8
|
readonly hasDividerEvidence: boolean;
|
|
8
9
|
readonly hasVisualRole: boolean;
|
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
/*** Collects complete evidence needed to classify an observed website structure node. */
|
|
2
2
|
export function websiteStructureEvidence(node, children = [], parent = null) {
|
|
3
|
+
const cardSurfaceReasons = cardSurfaceReasonsForNode(node, parent);
|
|
3
4
|
return {
|
|
4
5
|
availableObservation: availableObservation(node),
|
|
5
|
-
|
|
6
|
+
cardSurfaceReasons,
|
|
7
|
+
hasCardSurface: cardSurfaceReasons.length > 0,
|
|
6
8
|
hasDividerEvidence: hasDividerEvidence(node),
|
|
7
9
|
hasVisualRole: hasVisualRole(node),
|
|
8
10
|
isTransparentWrapper: isTransparentWrapper(node, children),
|
|
@@ -35,12 +37,13 @@ function isVisibleObservation(observation) {
|
|
|
35
37
|
observation.css.visibility !== 'collapse' &&
|
|
36
38
|
observation.css.opacity !== '0');
|
|
37
39
|
}
|
|
38
|
-
/*** Finds
|
|
39
|
-
function
|
|
40
|
-
return
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
40
|
+
/*** Finds all independently owned Card-surface signals across visible viewport observations. */
|
|
41
|
+
function cardSurfaceReasonsForNode(node, parent) {
|
|
42
|
+
return [
|
|
43
|
+
...new Set(node.observations.flatMap((observation) => isVisibleObservation(observation)
|
|
44
|
+
? cardSurfaceReasonsForObservation(observation, parent === null ? null : observationFor(parent, observation))
|
|
45
|
+
: [])),
|
|
46
|
+
];
|
|
44
47
|
}
|
|
45
48
|
/*** Identifies a visible horizontal or vertical line with independent divider semantics or geometry. */
|
|
46
49
|
function hasDividerEvidence(node) {
|
|
@@ -64,15 +67,29 @@ function hasDividerGeometry(width, height) {
|
|
|
64
67
|
const longerSide = Math.max(width, height);
|
|
65
68
|
return shorterSide <= 4 && longerSide >= 16 && longerSide / Math.max(shorterSide, 1) >= 8;
|
|
66
69
|
}
|
|
67
|
-
/***
|
|
68
|
-
function
|
|
70
|
+
/*** Lists reusable visual-surface predicates; borders, radius and padding cannot match. */
|
|
71
|
+
function cardSurfaceReasonsForObservation(observation, parentObservation) {
|
|
69
72
|
const { css } = observation;
|
|
70
73
|
if (css === null)
|
|
71
|
-
return
|
|
72
|
-
return
|
|
73
|
-
css.
|
|
74
|
-
|
|
75
|
-
|
|
74
|
+
return [];
|
|
75
|
+
return [
|
|
76
|
+
...(hasVisibleBackground(css.backgroundColor, parentObservation?.css?.backgroundColor ?? null)
|
|
77
|
+
? ['background-color']
|
|
78
|
+
: []),
|
|
79
|
+
...(css.backgroundImage !== 'none' ? ['background-image'] : []),
|
|
80
|
+
...(hasVisibleBoxShadow(css.boxShadow) ? ['box-shadow'] : []),
|
|
81
|
+
];
|
|
82
|
+
}
|
|
83
|
+
/*** Shares the same owned-surface predicates with independent divider evidence. */
|
|
84
|
+
function hasOwnedCardSurface(observation, parentObservation) {
|
|
85
|
+
return cardSurfaceReasonsForObservation(observation, parentObservation).length > 0;
|
|
86
|
+
}
|
|
87
|
+
/*** Retains visible border evidence for actual dividers, not card classification. */
|
|
88
|
+
function hasVisibleSurfaceBoundary(observation, parentObservation) {
|
|
89
|
+
const { css } = observation;
|
|
90
|
+
return (css !== null &&
|
|
91
|
+
(hasOwnedCardSurface(observation, parentObservation) ||
|
|
92
|
+
(hasNonZeroCssValue(css.borderWidth) && !isTransparentColor(css.borderColor))));
|
|
76
93
|
}
|
|
77
94
|
/*** Compares composited CSS colors so transparent backgrounds remain surface evidence when visible. */
|
|
78
95
|
function hasVisibleBackground(backgroundColor, parentBackgroundColor) {
|
|
@@ -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'],
|
package/dist/index.d.ts
CHANGED
|
@@ -7,8 +7,10 @@ export { selectDesignRuleProfile } from './features/provider/selectDesignRulePro
|
|
|
7
7
|
export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
|
|
8
8
|
export { recognizeWebsiteDocument } from './features/recognition/recognizeWebsiteDocument';
|
|
9
9
|
export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
|
|
10
|
+
export { createWebsiteRecognitionRuleSet } from './features/website-recognition/createWebsiteRecognitionRuleSet';
|
|
10
11
|
export { recognizeWebsiteStructure } from './features/website-recognition/recognizeWebsiteStructure';
|
|
11
12
|
export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
|
|
12
13
|
export type { DesignContext, DesignRuleProfileSelection, DesignRuleProvider, DesignRuleProviderOptions, } from './types/designRuleProvider';
|
|
13
14
|
export type { WebsiteAssessmentRuleOptions } from './types/websiteAssessment';
|
|
14
15
|
export type { WebsiteDesignNodeRecognition, WebsiteDesignPropertyObservation, WebsiteDesignRecognition, WebsiteDesignSourceReference, WebsiteDesignTokenCandidate, WebsiteDesignUnresolvedObservation, } from './types/websiteDesignRecognition';
|
|
16
|
+
export type { WebsiteRecognitionRuleContext } from './types/websiteRecognitionRules';
|
package/dist/index.js
CHANGED
|
@@ -7,4 +7,5 @@ export { selectDesignRuleProfile } from './features/provider/selectDesignRulePro
|
|
|
7
7
|
export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
|
|
8
8
|
export { recognizeWebsiteDocument } from './features/recognition/recognizeWebsiteDocument';
|
|
9
9
|
export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
|
|
10
|
+
export { createWebsiteRecognitionRuleSet } from './features/website-recognition/createWebsiteRecognitionRuleSet';
|
|
10
11
|
export { recognizeWebsiteStructure } from './features/website-recognition/recognizeWebsiteStructure';
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { WebsiteObservedNode } from '@ankhorage/contracts/website';
|
|
2
|
+
/*** Source-linked facts used by the canonical Rules evaluation for website modules. */
|
|
3
|
+
export interface WebsiteRecognitionRuleContext {
|
|
4
|
+
readonly childNodesByParent: ReadonlyMap<string, readonly WebsiteObservedNode[]>;
|
|
5
|
+
readonly node: WebsiteObservedNode;
|
|
6
|
+
readonly parent: WebsiteObservedNode | null;
|
|
7
|
+
}
|
|
File without changes
|