@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 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
- ![license: MIT](././paradox/badges/license.svg) ![npm: v0.9.2](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: canonical](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v0.9.4](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: canonical](././paradox/badges/docs.svg)
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.map((recognition) => recognition.uiNode),
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 tagName = node.dom.tagName.toLowerCase();
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 (isGroupedCard(node, parent, childNodesByParent))
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 a card only when a measured sibling group shares explicit surface traits. */
121
- function isGroupedCard(node, parent, childNodesByParent) {
122
- if (parent === null || !isLayoutGroup(parent))
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
- const siblings = meaningfulChildren(parent.sourceRef, childNodesByParent);
125
- return siblings.length >= 2 && siblings.every(isCardSurface) && isCardSurface(node);
126
- }
127
- /*** Flattens transparent DOM wrappers before measuring the source siblings in a layout group. */
128
- function meaningfulChildren(parentSourceRef, childNodesByParent) {
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
- /*** 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'));
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 === 'rgba(0, 0, 0, 0)';
186
+ return value === 'transparent' || parseCssColor(value)?.alpha === 0;
88
187
  }
@@ -1,2 +1,3 @@
1
- /*** Maps explicit HTML semantics without relying on framework or page-builder selectors. */
2
- export declare function recognizeWebsiteStructureSemanticComponentType(tagName: string): string | null;
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 or page-builder selectors. */
2
- export function recognizeWebsiteStructureSemanticComponentType(tagName) {
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', 'Container'],
42
+ ['main', 'Main'],
31
43
  ['menu', 'List'],
32
- ['nav', 'Container'],
44
+ ['nav', 'Nav'],
33
45
  ['ol', 'List'],
34
46
  ['p', 'RichText'],
35
47
  ['section', 'Section'],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/rules-design",
3
- "version": "0.9.2",
3
+ "version": "0.9.4",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",