@ankhorage/rules-design 0.5.0 → 0.6.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,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 34695ae: Add factual website design-property recognition with retained provenance and unresolved evidence.
8
+
3
9
  ## 0.5.0
4
10
 
5
11
  ### Minor 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.5.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)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v0.6.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
 
@@ -37,4 +37,5 @@ import { createRuleRegistry, evaluateRules } from '@ankhorage/rules';
37
37
  - [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
38
38
  - [Module relationships](././paradox/diagrams/module-relationships.mmd)
39
39
  - [Export graph](././paradox/diagrams/export-graph.mmd)
40
+ - [recognizeWebsiteDesignProperties sequence](././paradox/diagrams/sequences/recognize-website-design-properties.mmd)
40
41
  - [selectDesignRuleProfile sequence](././paradox/diagrams/sequences/select-design-rule-profile.mmd)
@@ -0,0 +1,4 @@
1
+ import type { WebsiteObservationDocument } from '@ankhorage/contracts/website';
2
+ import type { WebsiteDesignRecognition } from '../../types/websiteDesignRecognition';
3
+ /*** Recognizes exact design properties from validated website observations without evaluating them. */
4
+ export declare function recognizeWebsiteDesignProperties(document: WebsiteObservationDocument): WebsiteDesignRecognition;
@@ -0,0 +1,191 @@
1
+ import { isRecord } from '@ankhorage/utility/object';
2
+ import { tokenCandidates } from './tokenCandidates';
3
+ /*** Recognizes exact design properties from validated website observations without evaluating them. */
4
+ export function recognizeWebsiteDesignProperties(document) {
5
+ const nodes = document.pages.flatMap((page) => page.nodes.map((node) => recognizeNode(page.id, node)));
6
+ return { nodes, tokenCandidates: tokenCandidates(nodes) };
7
+ }
8
+ const colorProperties = ['color', 'backgroundColor', 'borderColor', 'opacity'];
9
+ const typographyProperties = [
10
+ 'fontFamily',
11
+ 'fontSize',
12
+ 'fontStyle',
13
+ 'fontWeight',
14
+ 'letterSpacing',
15
+ 'lineHeight',
16
+ 'textAlign',
17
+ 'textDecoration',
18
+ ];
19
+ const layoutProperties = [
20
+ 'display',
21
+ 'position',
22
+ 'visibility',
23
+ 'borderRadius',
24
+ 'borderWidth',
25
+ 'boxShadow',
26
+ 'margin',
27
+ 'padding',
28
+ 'alignContent',
29
+ 'alignItems',
30
+ 'alignSelf',
31
+ 'gap',
32
+ 'flexDirection',
33
+ 'flexBasis',
34
+ 'flexGrow',
35
+ 'flexShrink',
36
+ 'flexWrap',
37
+ 'justifyContent',
38
+ 'justifyItems',
39
+ 'justifySelf',
40
+ 'order',
41
+ 'placeContent',
42
+ 'placeItems',
43
+ 'placeSelf',
44
+ 'gridAutoColumns',
45
+ 'gridAutoFlow',
46
+ 'gridAutoRows',
47
+ 'gridColumn',
48
+ 'gridColumnEnd',
49
+ 'gridColumnStart',
50
+ 'gridRow',
51
+ 'gridRowEnd',
52
+ 'gridRowStart',
53
+ 'gridTemplateColumns',
54
+ 'gridTemplateRows',
55
+ 'overflow',
56
+ 'overflowX',
57
+ 'overflowY',
58
+ 'backgroundImage',
59
+ 'backgroundPosition',
60
+ 'backgroundRepeat',
61
+ 'backgroundSize',
62
+ ];
63
+ /*** Retains every available node style and safe semantic observation at its source identity. */
64
+ function recognizeNode(pageId, node) {
65
+ return {
66
+ sourceRef: node.sourceRef,
67
+ pageId,
68
+ colors: cssObservations(pageId, node, colorProperties),
69
+ typography: cssObservations(pageId, node, typographyProperties),
70
+ layout: cssObservations(pageId, node, layoutProperties),
71
+ responsive: responsiveObservations(pageId, node),
72
+ accessibility: accessibilityObservations(pageId, node),
73
+ media: node.media,
74
+ unresolved: unresolvedObservations(pageId, node),
75
+ };
76
+ }
77
+ /*** Projects exact available computed CSS values while retaining viewport, state, and provenance. */
78
+ function cssObservations(pageId, node, properties) {
79
+ return node.observations.flatMap((observation) => {
80
+ const { css } = observation;
81
+ return observation.availability.status === 'available' && css !== null
82
+ ? properties.map((name) => cssObservation(pageId, node.sourceRef, observation, css, name))
83
+ : [];
84
+ });
85
+ }
86
+ /*** Creates one source-linked computed CSS observation without normalizing its original literal. */
87
+ function cssObservation(pageId, sourceRef, observation, css, name) {
88
+ return {
89
+ name,
90
+ value: cssValue(cssPropertyValue(css, name)),
91
+ viewportId: observation.viewportId,
92
+ stateId: observation.stateId,
93
+ sourceRef,
94
+ pageId,
95
+ provenance: observation.provenance,
96
+ };
97
+ }
98
+ /*** Reads a named computed CSS field without indexing an untrusted external object. */
99
+ function cssPropertyValue(css, name) {
100
+ const value = Object.entries(isRecord(css) ? css : {}).find(([property]) => property === name)?.[1];
101
+ if (value === undefined)
102
+ throw new TypeError(`Unknown computed CSS property: ${name}`);
103
+ return value;
104
+ }
105
+ /*** Converts the one structured CSS box value into a portable serializable value. */
106
+ function cssValue(value) {
107
+ if (typeof value === 'string')
108
+ return value;
109
+ if (isRecord(value) &&
110
+ typeof value.bottom === 'string' &&
111
+ typeof value.left === 'string' &&
112
+ typeof value.right === 'string' &&
113
+ typeof value.top === 'string')
114
+ return { bottom: value.bottom, left: value.left, right: value.right, top: value.top };
115
+ throw new TypeError('Computed CSS values must be strings or complete box edges.');
116
+ }
117
+ /*** Retains responsive geometry and CSS state samples without inventing source-authored breakpoints. */
118
+ function responsiveObservations(pageId, node) {
119
+ return node.observations.map((observation) => ({
120
+ name: 'observation',
121
+ value: {
122
+ availability: observation.availability.status,
123
+ rect: observation.rect === null
124
+ ? null
125
+ : {
126
+ height: observation.rect.height,
127
+ width: observation.rect.width,
128
+ x: observation.rect.x,
129
+ y: observation.rect.y,
130
+ },
131
+ },
132
+ viewportId: observation.viewportId,
133
+ stateId: observation.stateId,
134
+ sourceRef: node.sourceRef,
135
+ pageId,
136
+ provenance: observation.provenance,
137
+ }));
138
+ }
139
+ /*** Retains semantic and accessible-name evidence without producing accessibility conclusions. */
140
+ function accessibilityObservations(pageId, node) {
141
+ const { sourceRef } = node;
142
+ const semantic = {
143
+ attributes: node.dom.attributes,
144
+ links: node.links.map((link) => ({
145
+ label: link.label,
146
+ sourceRef: link.sourceRef,
147
+ url: link.url,
148
+ })),
149
+ tagName: node.dom.tagName,
150
+ textRuns: node.textRuns.map((textRun) => ({
151
+ end: textRun.end,
152
+ sourceRef: textRun.sourceRef,
153
+ start: textRun.start,
154
+ text: textRun.text,
155
+ })),
156
+ };
157
+ return node.observations.map((observation) => ({
158
+ name: 'semantics',
159
+ value: semantic,
160
+ viewportId: observation.viewportId,
161
+ stateId: observation.stateId,
162
+ sourceRef,
163
+ pageId,
164
+ provenance: observation.provenance,
165
+ }));
166
+ }
167
+ /*** Records unavailable CSS or geometry samples with their producer-supplied missing reason. */
168
+ function unresolvedObservations(pageId, node) {
169
+ return node.observations.flatMap((observation) => {
170
+ const { availability } = observation;
171
+ if (availability.status !== 'missing' || availability.missing === null)
172
+ return [];
173
+ const { missing } = availability;
174
+ return unresolvedObservationKinds(observation).map((kind) => ({
175
+ kind,
176
+ missing,
177
+ provenance: observation.provenance,
178
+ sourceRef: node.sourceRef,
179
+ pageId,
180
+ stateId: observation.stateId,
181
+ viewportId: observation.viewportId,
182
+ }));
183
+ });
184
+ }
185
+ /*** Distinguishes each unavailable evidence channel without pretending it was observed. */
186
+ function unresolvedObservationKinds(observation) {
187
+ return [
188
+ ...(observation.css === null ? ['computed-css'] : []),
189
+ ...(observation.rect === null ? ['geometry'] : []),
190
+ ];
191
+ }
@@ -0,0 +1,3 @@
1
+ import type { WebsiteDesignNodeRecognition, WebsiteDesignTokenCandidate } from '../../types/websiteDesignRecognition';
2
+ /*** Finds repeated exact design literals and records them as role-free reusable token candidates. */
3
+ export declare function tokenCandidates(nodes: readonly WebsiteDesignNodeRecognition[]): readonly WebsiteDesignTokenCandidate[];
@@ -0,0 +1,77 @@
1
+ import { isRecord } from '@ankhorage/utility/object';
2
+ const tokenKinds = ['color', 'radius', 'shadow', 'spacing', 'typography'];
3
+ /*** Finds repeated exact design literals and records them as role-free reusable token candidates. */
4
+ export function tokenCandidates(nodes) {
5
+ return tokenKinds.flatMap((kind) => candidatesForKind(nodes, kind));
6
+ }
7
+ /*** Extracts deterministic repeated candidates for one design-token family. */
8
+ function candidatesForKind(nodes, kind) {
9
+ const observations = nodes.flatMap((node) => tokenObservationsForKind(node, kind));
10
+ return [
11
+ ...Map.groupBy(observations, (observation) => `${observation.property}\u0000${observation.value}`).entries(),
12
+ ]
13
+ .filter(([, values]) => sourceReferences(values).length > 1)
14
+ .map(([, values]) => ({
15
+ kind,
16
+ property: values[0].property,
17
+ value: values[0].value,
18
+ originalValues: [...new Set(values.map((item) => item.value))],
19
+ sourceRefs: sourceReferences(values),
20
+ confidence: sourceReferences(values).length / sourceReferences(observations).length,
21
+ inferredRole: null,
22
+ }))
23
+ .toSorted((left, right) => left.property.localeCompare(right.property) || left.value.localeCompare(right.value));
24
+ }
25
+ /*** Extracts deterministic page-qualified source identities so viewport samples do not fabricate repetition. */
26
+ function sourceReferences(observations) {
27
+ return [
28
+ ...new Map(observations.map((observation) => [
29
+ sourceReferenceKey(observation),
30
+ { pageId: observation.pageId, sourceRef: observation.sourceRef },
31
+ ])).values(),
32
+ ].toSorted((left, right) => sourceReferenceKey(left).localeCompare(sourceReferenceKey(right)));
33
+ }
34
+ /*** Serializes the two-part observed-node identity only for deterministic deduplication and ordering. */
35
+ function sourceReferenceKey(reference) {
36
+ return `${reference.pageId}\u0000${reference.sourceRef}`;
37
+ }
38
+ /*** Selects only the observations that belong to one factual token family. */
39
+ function tokenObservationsForKind(node, kind) {
40
+ return observationsForKind(node, kind).flatMap((observation) => tokenObservations(observation, kind));
41
+ }
42
+ /*** Retains each exact scalar or spacing-edge literal with its CSS-property ownership. */
43
+ function tokenObservations(observation, kind) {
44
+ if (typeof observation.value === 'string') {
45
+ return [
46
+ { ...sourceReference(observation), property: observation.name, value: observation.value },
47
+ ];
48
+ }
49
+ return kind === 'spacing' ? spacingEdgeTokenObservations(observation) : [];
50
+ }
51
+ /*** Expands a structured margin or padding value into its exact physical-edge token evidence. */
52
+ function spacingEdgeTokenObservations(observation) {
53
+ return isRecord(observation.value)
54
+ ? Object.entries(observation.value).flatMap(([edge, value]) => typeof value === 'string' && ['top', 'right', 'bottom', 'left'].includes(edge)
55
+ ? [{ ...sourceReference(observation), property: `${observation.name}.${edge}`, value }]
56
+ : [])
57
+ : [];
58
+ }
59
+ /*** Extracts the reusable page-qualified source identity from one design property observation. */
60
+ function sourceReference(observation) {
61
+ return { pageId: observation.pageId, sourceRef: observation.sourceRef };
62
+ }
63
+ /*** Selects only the property observations that belong to one factual token family. */
64
+ function observationsForKind(node, kind) {
65
+ switch (kind) {
66
+ case 'color':
67
+ return node.colors.filter((observation) => observation.name !== 'opacity');
68
+ case 'radius':
69
+ return node.layout.filter((observation) => observation.name === 'borderRadius');
70
+ case 'shadow':
71
+ return node.layout.filter((observation) => observation.name === 'boxShadow');
72
+ case 'spacing':
73
+ return node.layout.filter((observation) => ['gap', 'margin', 'padding'].includes(observation.name));
74
+ case 'typography':
75
+ return node.typography;
76
+ }
77
+ }
package/dist/index.d.ts CHANGED
@@ -4,7 +4,9 @@ export { designRuleProviderManifest } from './features/catalog/designRuleProvide
4
4
  export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
5
5
  export { createDesignRuleProvider } from './features/provider/designRuleProvider';
6
6
  export { selectDesignRuleProfile } from './features/provider/selectDesignRuleProfile';
7
+ export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
7
8
  export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
8
9
  export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
9
10
  export type { DesignContext, DesignRuleProfileSelection, DesignRuleProvider, DesignRuleProviderOptions, } from './types/designRuleProvider';
10
11
  export type { WebsiteAssessmentRuleOptions } from './types/websiteAssessment';
12
+ export type { WebsiteDesignNodeRecognition, WebsiteDesignPropertyObservation, WebsiteDesignRecognition, WebsiteDesignSourceReference, WebsiteDesignTokenCandidate, WebsiteDesignUnresolvedObservation, } from './types/websiteDesignRecognition';
package/dist/index.js CHANGED
@@ -4,4 +4,5 @@ export { designRuleProviderManifest } from './features/catalog/designRuleProvide
4
4
  export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
5
5
  export { createDesignRuleProvider } from './features/provider/designRuleProvider';
6
6
  export { selectDesignRuleProfile } from './features/provider/selectDesignRuleProfile';
7
+ export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
7
8
  export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
@@ -0,0 +1,54 @@
1
+ import type { SerializableValue } from '@ankhorage/contracts';
2
+ import type { WebsiteMediaReference, WebsiteMissingValue, WebsiteObservationProvenance } from '@ankhorage/contracts/website';
3
+ /*** Identifies one observed DOM node within the page that owns its local source reference. */
4
+ export interface WebsiteDesignSourceReference {
5
+ readonly pageId: string;
6
+ readonly sourceRef: string;
7
+ }
8
+ /*** Describes one exact observed design value without assigning a quality verdict. */
9
+ export interface WebsiteDesignPropertyObservation {
10
+ readonly name: string;
11
+ readonly value: SerializableValue;
12
+ readonly viewportId: string;
13
+ readonly stateId: string;
14
+ readonly sourceRef: string;
15
+ readonly pageId: string;
16
+ readonly provenance: WebsiteObservationProvenance;
17
+ }
18
+ /*** Retains an unavailable observation instead of substituting or silently omitting design evidence. */
19
+ export interface WebsiteDesignUnresolvedObservation {
20
+ readonly kind: 'computed-css' | 'geometry';
21
+ readonly viewportId: string;
22
+ readonly stateId: string;
23
+ readonly sourceRef: string;
24
+ readonly pageId: string;
25
+ readonly provenance: WebsiteObservationProvenance;
26
+ readonly missing: WebsiteMissingValue;
27
+ }
28
+ /*** Groups all factual design observations for one stable observed DOM node. */
29
+ export interface WebsiteDesignNodeRecognition {
30
+ readonly sourceRef: string;
31
+ readonly pageId: string;
32
+ readonly colors: readonly WebsiteDesignPropertyObservation[];
33
+ readonly typography: readonly WebsiteDesignPropertyObservation[];
34
+ readonly layout: readonly WebsiteDesignPropertyObservation[];
35
+ readonly responsive: readonly WebsiteDesignPropertyObservation[];
36
+ readonly accessibility: readonly WebsiteDesignPropertyObservation[];
37
+ readonly media: readonly WebsiteMediaReference[];
38
+ readonly unresolved: readonly WebsiteDesignUnresolvedObservation[];
39
+ }
40
+ /*** Records a repeated observed value as a reusable token candidate without inventing a role. */
41
+ export interface WebsiteDesignTokenCandidate {
42
+ readonly kind: 'color' | 'radius' | 'shadow' | 'spacing' | 'typography';
43
+ readonly property: string;
44
+ readonly value: string;
45
+ readonly originalValues: readonly string[];
46
+ readonly sourceRefs: readonly WebsiteDesignSourceReference[];
47
+ readonly confidence: number;
48
+ readonly inferredRole: null;
49
+ }
50
+ /*** Provides the factual design-property contribution for later website recognition assembly. */
51
+ export interface WebsiteDesignRecognition {
52
+ readonly nodes: readonly WebsiteDesignNodeRecognition[];
53
+ readonly tokenCandidates: readonly WebsiteDesignTokenCandidate[];
54
+ }
File without changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/rules-design",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",
@@ -58,7 +58,7 @@
58
58
  "@ankhorage/paradox": "^0.3.6"
59
59
  },
60
60
  "dependencies": {
61
- "@ankhorage/contracts": "^26.4.0",
61
+ "@ankhorage/contracts": "^26.6.0",
62
62
  "@ankhorage/rules": "^0.4.0",
63
63
  "@ankhorage/utility": "^1.10.0"
64
64
  }