custom-rendrer 0.0.0-stage → 1.0.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/README.md CHANGED
@@ -1,3 +1,121 @@
1
- # Temporary Holding Version
1
+ # custom-rendrer
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A presentation-layer abstraction and masking engine with build-time plugins for Vite, Webpack, and Rollup.
4
+
5
+ It visually transforms on-screen text using CSS pseudo-elements while leaving the underlying DOM text nodes and application state intact. This guarantees that React/Vue component reconciliations, DOM queries, and form submissions remain unmodified.
6
+
7
+ ---
8
+
9
+ ## Features
10
+
11
+ - **DOM Preservation:** Modifies visual presentation via attribute-driven CSS pseudo-elements without altering internal `textContent`.
12
+ - **Bidirectional Mapping:** Supports automated case matching (lower, capitalized, UPPER) and context-aware overrides.
13
+ - **Build Plugin Integration:** First-class plugins for Vite, Webpack, and Rollup to inject rules at build time.
14
+ - **Safe I/O Defaults:** Form controls (`<input>`, `<textarea>`) and sensitive elements (`<code>`, `<pre>`) are excluded by default.
15
+ - **Dynamic Updates:** Built-in `MutationObserver` automatically applies rules to asynchronously loaded or re-rendered components.
16
+
17
+ ---
18
+
19
+ ## Installation
20
+
21
+ ```bash
22
+ npm install custom-rendrer
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Usage
28
+
29
+ ### 1. Vite Setup
30
+
31
+ Add the plugin to your `vite.config.js`:
32
+
33
+ ```javascript
34
+ import { defineConfig } from 'vite';
35
+ import { frontendAbstractionVitePlugin } from 'custom-rendrer/vite';
36
+
37
+ export default defineConfig({
38
+ plugins: [
39
+ frontendAbstractionVitePlugin({
40
+ rules: [
41
+ { original: 'Merchant', display: 'Retailer' },
42
+ { original: 'Invoice', display: 'Statement' }
43
+ ],
44
+ config: {
45
+ excludeInputs: true,
46
+ },
47
+ }),
48
+ ],
49
+ });
50
+ ```
51
+
52
+ ### 2. Webpack Setup
53
+
54
+ Add the plugin to your `webpack.config.js`:
55
+
56
+ ```javascript
57
+ import { FrontendAbstractionWebpackPlugin } from 'custom-rendrer/webpack';
58
+
59
+ export default {
60
+ // ... Webpack config
61
+ plugins: [
62
+ new FrontendAbstractionWebpackPlugin({
63
+ rules: [
64
+ { original: 'Merchant', display: 'Retailer' },
65
+ ],
66
+ }),
67
+ ],
68
+ };
69
+ ```
70
+
71
+ ### 3. Client-side Runtime Usage
72
+
73
+ You can also import and configure the runtime manually in your application:
74
+
75
+ ```javascript
76
+ import { runtime, initAbstractionRuntime } from 'custom-rendrer/runtime';
77
+
78
+ // Initialize with custom options
79
+ const appRuntime = initAbstractionRuntime({
80
+ excludeInputs: true,
81
+ });
82
+
83
+ // Add dynamic user mappings on the fly
84
+ appRuntime.addMapping('Customer', 'Client');
85
+ ```
86
+
87
+ ---
88
+
89
+ ## Rule Configuration
90
+
91
+ Each transformation rule accepts the following properties:
92
+
93
+ | Property | Type | Description |
94
+ | :--- | :--- | :--- |
95
+ | `original` | `string \| RegExp` | The term to match in source elements |
96
+ | `display` | `string` | The substituted visual display text |
97
+ | `priority` | `number` | Rule priority (higher numbers take precedence) |
98
+ | `context` | `object \| function` | Optional criteria (e.g. `{ elementType: 'th' }`) |
99
+ | `caseSensitive`| `boolean` | When false, matches and preserves original casing |
100
+
101
+ ---
102
+
103
+ ## Publishing
104
+
105
+ To verify package contents before publishing:
106
+
107
+ ```bash
108
+ npm pack --dry-run
109
+ ```
110
+
111
+ To run test validations:
112
+
113
+ ```bash
114
+ npm test
115
+ ```
116
+
117
+ To publish to npm:
118
+
119
+ ```bash
120
+ npm publish
121
+ ```
@@ -0,0 +1,65 @@
1
+ /**
2
+ * TransformationContext
3
+ * Encapsulates contextual information for transformations (e.g. element type,
4
+ * component hierarchy, attribute context, or custom metadata).
5
+ */
6
+ export class TransformationContext {
7
+ constructor(options = {}) {
8
+ this.elementType = options.elementType || null;
9
+ this.componentName = options.componentName || null;
10
+ this.parentPath = options.parentPath || null;
11
+ this.attributes = options.attributes || {};
12
+ this.metadata = options.metadata || {};
13
+ this.isInput = options.isInput || false;
14
+ }
15
+
16
+ /**
17
+ * Matches this context against rule criteria.
18
+ * Criteria can include elementType, componentName, attributes, or custom predicate.
19
+ */
20
+ matches(criteria) {
21
+ if (!criteria) return true;
22
+
23
+ if (typeof criteria === 'function') {
24
+ return Boolean(criteria(this));
25
+ }
26
+
27
+ if (criteria.elementType) {
28
+ const target = String(criteria.elementType).toLowerCase();
29
+ const current = String(this.elementType || '').toLowerCase();
30
+ if (target !== current && target !== '*') return false;
31
+ }
32
+
33
+ if (criteria.componentName) {
34
+ if (criteria.componentName instanceof RegExp) {
35
+ if (!criteria.componentName.test(this.componentName || '')) return false;
36
+ } else if (criteria.componentName !== this.componentName) {
37
+ return false;
38
+ }
39
+ }
40
+
41
+ if (criteria.attributes && typeof criteria.attributes === 'object') {
42
+ for (const [key, value] of Object.entries(criteria.attributes)) {
43
+ if (this.attributes[key] !== value) return false;
44
+ }
45
+ }
46
+
47
+ return true;
48
+ }
49
+
50
+ clone(overrides = {}) {
51
+ return new TransformationContext({
52
+ elementType: overrides.elementType ?? this.elementType,
53
+ componentName: overrides.componentName ?? this.componentName,
54
+ parentPath: overrides.parentPath ?? this.parentPath,
55
+ attributes: { ...this.attributes, ...(overrides.attributes || {}) },
56
+ metadata: { ...this.metadata, ...(overrides.metadata || {}) },
57
+ isInput: overrides.isInput ?? this.isInput,
58
+ });
59
+ }
60
+
61
+ static create(options) {
62
+ if (options instanceof TransformationContext) return options;
63
+ return new TransformationContext(options || {});
64
+ }
65
+ }
package/core/engine.js ADDED
@@ -0,0 +1,130 @@
1
+ import { TransformationRegistry } from './registry.js';
2
+ import { ValueTransformer } from './transformer.js';
3
+ import { TransformationContext } from './context.js';
4
+ import { ConfigurationManager } from '../rules/config.js';
5
+ import { isExcludedElement } from '../rules/exclusions.js';
6
+
7
+ /**
8
+ * AbstractionEngine
9
+ * Independent core engine for frontend abstraction.
10
+ * Completely decoupled from React and build tools.
11
+ */
12
+ export class AbstractionEngine {
13
+ constructor(options = {}) {
14
+ this.config = new ConfigurationManager(options);
15
+ this.registry = new TransformationRegistry();
16
+ this.transformer = new ValueTransformer(this.registry);
17
+
18
+ // Initialize with default or configured mappings
19
+ const initialMappings = this.config.get('mappings') || [];
20
+ for (const mapping of initialMappings) {
21
+ this.registry.register(mapping);
22
+ }
23
+ }
24
+
25
+ /**
26
+ * Transforms an original value to its display value.
27
+ * @param {any} original
28
+ * @param {TransformationContext|Object} [context]
29
+ * @returns {any} display value
30
+ */
31
+ toDisplay(original, context = null) {
32
+ if (!this.config.isEnabled()) {
33
+ return original;
34
+ }
35
+ return this.transformer.toDisplay(original, context);
36
+ }
37
+
38
+ /**
39
+ * Transforms a display value back to its original value.
40
+ * @param {any} display
41
+ * @param {TransformationContext|Object} [context]
42
+ * @returns {any} original value
43
+ */
44
+ toOriginal(display, context = null) {
45
+ if (!this.config.isEnabled()) {
46
+ return display;
47
+ }
48
+ return this.transformer.toOriginal(display, context);
49
+ }
50
+
51
+ /**
52
+ * Transforms text content containing potential matches.
53
+ */
54
+ transformText(text, context = null) {
55
+ if (!this.config.isEnabled()) {
56
+ return text;
57
+ }
58
+ return this.transformer.transformTextContent(text, context);
59
+ }
60
+
61
+ /**
62
+ * Registers a new transformation rule.
63
+ */
64
+ registerRule(rule) {
65
+ return this.registry.register(rule);
66
+ }
67
+
68
+ /**
69
+ * Unregisters a rule by ID.
70
+ */
71
+ unregisterRule(id) {
72
+ return this.registry.unregister(id);
73
+ }
74
+
75
+ /**
76
+ * Enables a rule by ID.
77
+ */
78
+ enableRule(id) {
79
+ return this.registry.enable(id);
80
+ }
81
+
82
+ /**
83
+ * Disables a rule by ID.
84
+ */
85
+ disableRule(id) {
86
+ return this.registry.disable(id);
87
+ }
88
+
89
+ /**
90
+ * Gets the rule registry instance.
91
+ */
92
+ getRegistry() {
93
+ return this.registry;
94
+ }
95
+
96
+ /**
97
+ * Updates engine configuration.
98
+ */
99
+ configure(options) {
100
+ return this.config.update(options);
101
+ }
102
+
103
+ /**
104
+ * Gets current configuration.
105
+ */
106
+ getConfig() {
107
+ return this.config.getAll();
108
+ }
109
+
110
+ /**
111
+ * Checks if an element is excluded from transformation.
112
+ */
113
+ isExcluded(element, context = null) {
114
+ return isExcludedElement(element, {
115
+ ...this.config.getAll(),
116
+ context,
117
+ });
118
+ }
119
+
120
+ /**
121
+ * Creates a transformation context.
122
+ */
123
+ createContext(options) {
124
+ return TransformationContext.create(options);
125
+ }
126
+ }
127
+
128
+ // Global default singleton instance
129
+ export const engine = new AbstractionEngine();
130
+ export default engine;
@@ -0,0 +1,174 @@
1
+ import { TransformationContext } from './context.js';
2
+
3
+ /**
4
+ * TransformationRegistry
5
+ * Manages transformation rules, priorities, context criteria, and duplicate resolution.
6
+ */
7
+ export class TransformationRegistry {
8
+ constructor() {
9
+ this._rules = new Map();
10
+ this._sequence = 0;
11
+ }
12
+
13
+ /**
14
+ * Registers a new transformation rule.
15
+ * @param {Object} rule
16
+ * @returns {string} ruleId
17
+ */
18
+ register(rule) {
19
+ if (!rule) throw new Error('Rule definition is required');
20
+ if (rule.original === undefined && !rule.matcher) {
21
+ throw new Error('Rule must define "original" or "matcher"');
22
+ }
23
+
24
+ const id = rule.id || `rule_${++this._sequence}_${Date.now()}`;
25
+ const ruleRecord = {
26
+ id,
27
+ original: rule.original,
28
+ display: rule.display,
29
+ priority: Number(rule.priority || 0),
30
+ context: rule.context || null,
31
+ enabled: rule.enabled !== false,
32
+ matcher: rule.matcher || null,
33
+ toDisplayFn: typeof rule.toDisplay === 'function' ? rule.toDisplay : null,
34
+ toOriginalFn: typeof rule.toOriginal === 'function' ? rule.toOriginal : null,
35
+ metadata: rule.metadata || {},
36
+ sequence: ++this._sequence,
37
+ };
38
+
39
+ this._rules.set(id, ruleRecord);
40
+ return id;
41
+ }
42
+
43
+ /**
44
+ * Unregisters a rule by ID.
45
+ */
46
+ unregister(id) {
47
+ return this._rules.delete(id);
48
+ }
49
+
50
+ /**
51
+ * Enables a rule by ID.
52
+ */
53
+ enable(id) {
54
+ const rule = this._rules.get(id);
55
+ if (rule) {
56
+ rule.enabled = true;
57
+ return true;
58
+ }
59
+ return false;
60
+ }
61
+
62
+ /**
63
+ * Disables a rule by ID.
64
+ */
65
+ disable(id) {
66
+ const rule = this._rules.get(id);
67
+ if (rule) {
68
+ rule.enabled = false;
69
+ return true;
70
+ }
71
+ return false;
72
+ }
73
+
74
+ /**
75
+ * Clears all registered rules.
76
+ */
77
+ clear() {
78
+ this._rules.clear();
79
+ }
80
+
81
+ /**
82
+ * Returns all registered rules as an array.
83
+ */
84
+ getAllRules() {
85
+ return Array.from(this._rules.values());
86
+ }
87
+
88
+ /**
89
+ * Gets a specific rule by ID.
90
+ */
91
+ getRule(id) {
92
+ return this._rules.get(id) || null;
93
+ }
94
+
95
+ /**
96
+ * Finds matching active rules for an original value and context,
97
+ * sorted by priority descending and insertion sequence descending.
98
+ */
99
+ findRulesForOriginal(originalValue, rawContext = null) {
100
+ const context = TransformationContext.create(rawContext);
101
+ const matches = [];
102
+
103
+ for (const rule of this._rules.values()) {
104
+ if (!rule.enabled) continue;
105
+ if (rule.context && !context.matches(rule.context)) continue;
106
+
107
+ let isMatch = false;
108
+ if (rule.matcher) {
109
+ if (rule.matcher instanceof RegExp) {
110
+ isMatch = rule.matcher.test(String(originalValue));
111
+ } else if (typeof rule.matcher === 'function') {
112
+ isMatch = Boolean(rule.matcher(originalValue, context));
113
+ }
114
+ } else if (rule.original !== undefined) {
115
+ if (rule.caseSensitive === true) {
116
+ isMatch = String(rule.original) === String(originalValue);
117
+ } else {
118
+ isMatch = String(rule.original).toLowerCase() === String(originalValue).toLowerCase();
119
+ }
120
+ }
121
+
122
+ if (isMatch) {
123
+ matches.push(rule);
124
+ }
125
+ }
126
+
127
+ // Sort by priority desc, then sequence desc
128
+ return matches.sort((a, b) => {
129
+ if (b.priority !== a.priority) return b.priority - a.priority;
130
+ return b.sequence - a.sequence;
131
+ });
132
+ }
133
+
134
+ /**
135
+ * Finds matching active rules for a display value and context,
136
+ * sorted by priority descending. Disambiguates duplicate display values
137
+ * using context criteria first, then priority.
138
+ */
139
+ findRulesForDisplay(displayValue, rawContext = null) {
140
+ const context = TransformationContext.create(rawContext);
141
+ const matches = [];
142
+
143
+ for (const rule of this._rules.values()) {
144
+ if (!rule.enabled) continue;
145
+ if (rule.context && !context.matches(rule.context)) continue;
146
+
147
+ let isMatch = false;
148
+ if (rule.display !== undefined) {
149
+ if (rule.caseSensitive === true) {
150
+ isMatch = String(rule.display) === String(displayValue);
151
+ } else {
152
+ isMatch = String(rule.display).toLowerCase() === String(displayValue).toLowerCase();
153
+ }
154
+ } else if (rule.toOriginalFn) {
155
+ // Can test if toOriginal returns a defined original value
156
+ try {
157
+ const testOrig = rule.toOriginalFn(displayValue, context);
158
+ isMatch = testOrig !== undefined && testOrig !== null;
159
+ } catch {
160
+ isMatch = false;
161
+ }
162
+ }
163
+
164
+ if (isMatch) {
165
+ matches.push(rule);
166
+ }
167
+ }
168
+
169
+ return matches.sort((a, b) => {
170
+ if (b.priority !== a.priority) return b.priority - a.priority;
171
+ return b.sequence - a.sequence;
172
+ });
173
+ }
174
+ }
@@ -0,0 +1,140 @@
1
+ import { TransformationContext } from './context.js';
2
+
3
+ function matchCase(sourceWord, targetWord) {
4
+ if (!sourceWord || !targetWord) return targetWord;
5
+ const strSource = String(sourceWord);
6
+ const strTarget = String(targetWord);
7
+ // All uppercase: e.g. "MERCHANT" -> "RETAILER"
8
+ if (strSource === strSource.toUpperCase() && strSource.length > 1) {
9
+ return strTarget.toUpperCase();
10
+ }
11
+ // Title / Capitalized: e.g. "Merchant" -> "Retailer"
12
+ if (strSource[0] === strSource[0].toUpperCase()) {
13
+ return strTarget.charAt(0).toUpperCase() + strTarget.slice(1);
14
+ }
15
+ // Lowercase: e.g. "merchant" -> "retailer"
16
+ return strTarget.toLowerCase();
17
+ }
18
+
19
+ /**
20
+ * ValueTransformer
21
+ * Executes transformation logic against registered rules while respecting boundaries and context.
22
+ */
23
+ export class ValueTransformer {
24
+ constructor(registry) {
25
+ this.registry = registry;
26
+ }
27
+
28
+ /**
29
+ * Transforms an original value to its display value.
30
+ * @param {any} originalValue
31
+ * @param {TransformationContext|Object} rawContext
32
+ * @returns {any} displayValue
33
+ */
34
+ toDisplay(originalValue, rawContext = null) {
35
+ if (originalValue === null || originalValue === undefined) {
36
+ return originalValue;
37
+ }
38
+
39
+ const context = TransformationContext.create(rawContext);
40
+ const rules = this.registry.findRulesForOriginal(originalValue, context);
41
+
42
+ if (rules.length === 0) {
43
+ return originalValue;
44
+ }
45
+
46
+ // Top priority rule wins
47
+ const rule = rules[0];
48
+
49
+ if (rule.toDisplayFn) {
50
+ return rule.toDisplayFn(originalValue, context);
51
+ }
52
+
53
+ if (rule.display !== undefined) {
54
+ return rule.caseSensitive === true
55
+ ? rule.display
56
+ : matchCase(originalValue, rule.display);
57
+ }
58
+
59
+ return originalValue;
60
+ }
61
+
62
+ /**
63
+ * Transforms a display value back to its original value.
64
+ * @param {any} displayValue
65
+ * @param {TransformationContext|Object} rawContext
66
+ * @returns {any} originalValue
67
+ */
68
+ toOriginal(displayValue, rawContext = null) {
69
+ if (displayValue === null || displayValue === undefined) {
70
+ return displayValue;
71
+ }
72
+
73
+ const context = TransformationContext.create(rawContext);
74
+ const rules = this.registry.findRulesForDisplay(displayValue, context);
75
+
76
+ if (rules.length === 0) {
77
+ return displayValue;
78
+ }
79
+
80
+ // Disambiguation: Highest priority rule matching context wins
81
+ const rule = rules[0];
82
+
83
+ if (rule.toOriginalFn) {
84
+ return rule.toOriginalFn(displayValue, context);
85
+ }
86
+
87
+ if (rule.original !== undefined) {
88
+ return rule.caseSensitive === true
89
+ ? rule.original
90
+ : matchCase(displayValue, rule.original);
91
+ }
92
+
93
+ return displayValue;
94
+ }
95
+
96
+ /**
97
+ * Transforms substrings or tokens in a composite text block if configured.
98
+ */
99
+ transformTextContent(text, rawContext = null) {
100
+ if (typeof text !== 'string') return text;
101
+ const context = TransformationContext.create(rawContext);
102
+
103
+ // If exact full-match hits
104
+ const exactDisplay = this.toDisplay(text, context);
105
+ if (exactDisplay !== text) {
106
+ return exactDisplay;
107
+ }
108
+
109
+ const rules = this.registry.getAllRules().filter(r => r.enabled && (!r.context || context.matches(r.context)));
110
+ let result = text;
111
+
112
+ for (const rule of rules) {
113
+ if (rule.original && typeof rule.original === 'string') {
114
+ const targetDisplay = rule.display !== undefined ? String(rule.display) : String(rule.original);
115
+ const isCaseSensitive = rule.caseSensitive === true;
116
+ const flags = isCaseSensitive ? 'g' : 'gi';
117
+ const escapedOrig = escapeRegExp(rule.original);
118
+
119
+ // Pattern handles optional plural 's' or 'es'
120
+ const pattern = new RegExp(`\\b(${escapedOrig})(s|es)?\\b`, flags);
121
+
122
+ result = result.replace(pattern, (match, base, pluralSuffix) => {
123
+ let replaced = isCaseSensitive ? targetDisplay : matchCase(base, targetDisplay);
124
+ if (pluralSuffix) {
125
+ if (!replaced.toLowerCase().endsWith('s')) {
126
+ replaced += pluralSuffix;
127
+ }
128
+ }
129
+ return replaced;
130
+ });
131
+ }
132
+ }
133
+
134
+ return result;
135
+ }
136
+ }
137
+
138
+ function escapeRegExp(string) {
139
+ return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
140
+ }