@ankhorage/rules-design 0.9.3 → 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,11 @@
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
+
3
9
  ## 0.9.3
4
10
 
5
11
  ### 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.3](././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,8 +129,7 @@ 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;
@@ -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.3",
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",