@ankhorage/rules-design 0.9.2 → 0.9.3

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.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 94478d7: Recognize independently visible website cards and provider-neutral CSS dividers.
8
+
3
9
  ## 0.9.2
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.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.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)
7
7
 
8
8
  Declarative catalog for reusable design rules.
9
9
 
@@ -103,7 +103,9 @@ function recognizeComponentType(node, parent, childNodesByParent) {
103
103
  const { css } = observation;
104
104
  if (css === null)
105
105
  return 'Unknown';
106
- if (isGroupedCard(node, parent, childNodesByParent))
106
+ if (websiteStructureEvidence(node).hasDividerEvidence)
107
+ return 'Divider';
108
+ if (isCard(node, parent, childNodesByParent))
107
109
  return 'Card';
108
110
  if (css.display.includes('grid'))
109
111
  return 'Grid';
@@ -117,29 +119,25 @@ function recognizeComponentType(node, parent, childNodesByParent) {
117
119
  return 'RichText';
118
120
  return websiteStructureEvidence(node).hasVisualRole ? 'Container' : 'Unknown';
119
121
  }
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))
122
+ /*** Recognizes one rendered layout child with an independently visible surface boundary as a card. */
123
+ 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))
123
132
  return false;
124
- const siblings = meaningfulChildren(parent.sourceRef, childNodesByParent);
125
- return siblings.length >= 2 && siblings.every(isCardSurface) && isCardSurface(node);
133
+ return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
126
134
  }
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
- });
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());
136
138
  }
137
139
  /*** Tests whether a parent has measured Grid or Flex grouping semantics. */
138
140
  function isLayoutGroup(node) {
139
141
  const css = websiteStructureEvidence(node).availableObservation?.css;
140
142
  return css === null || css === undefined ? false : /grid|flex/.test(css.display);
141
143
  }
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
  }
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.3",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",