@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 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
- ![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.10.0](././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
 
@@ -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.map((recognition) => recognition.uiNode),
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 tagName = node.dom.tagName.toLowerCase();
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
- /*** Recognizes one rendered layout child with an independently visible surface boundary as a card. */
156
+ /*** Evaluates the versioned canonical Card rule before committing a primary module type. */
123
157
  function isCard(node, parent, childNodesByParent) {
124
- return (parent !== null &&
125
- isLayoutGroup(parent) &&
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
- hasCardSurface: hasCardSurface(node, parent),
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 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
- });
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
- /*** Requires one directly visible boundary feature owned by the node. */
68
- function hasVisibleSurfaceBoundary(observation, parentObservation) {
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 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));
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
- /*** 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/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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/rules-design",
3
- "version": "0.9.3",
3
+ "version": "0.10.0",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",