@context-action/core 1.2.5 → 1.3.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.
Files changed (38) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +18 -1
  3. package/dist/element-BJpk34By.d.cts +35 -0
  4. package/dist/element-BJpk34By.d.cts.map +1 -0
  5. package/dist/element-BJpk34By.d.ts +35 -0
  6. package/dist/element-BJpk34By.d.ts.map +1 -0
  7. package/dist/element-BcfeiQgA.cjs +190 -0
  8. package/dist/element-DSSLaFmw.js +180 -0
  9. package/dist/element-DSSLaFmw.js.map +1 -0
  10. package/dist/element-react.cjs +81 -0
  11. package/dist/element-react.d.cts +11 -0
  12. package/dist/element-react.d.cts.map +1 -0
  13. package/dist/element-react.d.ts +11 -0
  14. package/dist/element-react.d.ts.map +1 -0
  15. package/dist/element-react.js +79 -0
  16. package/dist/element-react.js.map +1 -0
  17. package/dist/element.cjs +5 -0
  18. package/dist/element.d.cts +3 -0
  19. package/dist/element.d.ts +3 -0
  20. package/dist/element.js +3 -0
  21. package/dist/index.cjs +154 -47
  22. package/dist/index.d.cts +2 -1
  23. package/dist/index.d.cts.map +1 -1
  24. package/dist/index.d.ts +2 -1
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +154 -47
  27. package/dist/index.js.map +1 -1
  28. package/dist/public-action-methods-C_ppItRr.d.cts +5 -0
  29. package/dist/public-action-methods-C_ppItRr.d.cts.map +1 -0
  30. package/dist/public-action-methods-C_ppItRr.d.ts +5 -0
  31. package/dist/public-action-methods-C_ppItRr.d.ts.map +1 -0
  32. package/docs/action-contracts.md +78 -0
  33. package/docs/element-host-patterns.en.md +129 -0
  34. package/docs/element-host-patterns.ko.md +116 -0
  35. package/docs/element-interop.md +126 -0
  36. package/docs/interop-review.en.md +55 -0
  37. package/docs/interop-review.ko.md +51 -0
  38. package/package.json +35 -4
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Change Log
2
2
 
3
+ Pending changes that are not part of a published version are recorded in the repository's [UNRELEASED.md](https://github.com/mineclover/context-action/blob/main/packages/core/UNRELEASED.md).
4
+
5
+ ## [1.3.0] (2026-10-29)
6
+
7
+ ### Element interop
8
+
9
+ - Add the framework-neutral `./element` and React host `./element/react` entry
10
+ points for element lifecycle and property/event binding contracts.
11
+ - Preserve the phase-specific action pipeline and asynchronous shutdown contracts
12
+ used by the current Core release cohort.
13
+
14
+ ## [1.2.6] (2026-10-02)
15
+
16
+ - Reissue the coordinated state-management cohort with fresh provenance for the time-travel and hydration stability release.
17
+
3
18
  ## [1.2.5] (2026-10-02)
4
19
 
5
20
  - Reissue the coordinated state-management cohort with fresh provenance for the product-stability release.
package/README.md CHANGED
@@ -4,6 +4,10 @@ Type-safe action pipeline management library for **vanilla JavaScript/TypeScript
4
4
 
5
5
  > **✨ Framework-Agnostic**: Works with vanilla JavaScript, React, Vue, Svelte, or any JavaScript environment. No framework dependencies required!
6
6
 
7
+ > Local candidate: optional `/element` DOM bindings and `/element/react` host bridge.
8
+ > The default Action entry stays DOM/React-free. See [ownership, lifecycle and release limits](docs/element-interop.md).
9
+ > These exports are not in the current registry release.
10
+
7
11
  ## Installation
8
12
 
9
13
  ```bash
@@ -177,7 +181,7 @@ const actions = new ActionRegister<MyActions>({
177
181
  // should be treated as a programming error.
178
182
  ```
179
183
 
180
- ## v1.2 Pipeline Contract
184
+ ## v1.3 Pipeline Contract
181
185
 
182
186
  ### Phase-specific registration
183
187
 
@@ -465,6 +469,19 @@ await actions.dispatch('processFiles', files, {
465
469
  });
466
470
  ```
467
471
 
472
+ ### One-time handler lifecycle
473
+
474
+ `once: true` means at most one invocation per registration, including concurrent
475
+ dispatches and retries. A skipped condition does not consume the registration.
476
+ In parallel/race mode, all handler conditions are evaluated before execution;
477
+ if a condition throws, no result handler starts and uninvoked once handlers
478
+ remain available. Sequential mode evaluates conditions as it reaches each handler,
479
+ so previously executed handlers are not rolled back.
480
+
481
+ Once observers also run at most once, even when concurrent dispatches wait for
482
+ an earlier observer. Cleanup runs once after started work settles. This is an
483
+ in-memory registration guarantee, not persistent or cross-process deduplication.
484
+
468
485
  ### Error Handling & Recovery
469
486
 
470
487
  ```typescript
@@ -0,0 +1,35 @@
1
+ //#region src/facade/types.d.ts
2
+ type PublicHandleFactory<Target extends object, Handle> = (getTarget: () => Target | null) => Handle;
3
+ //#endregion
4
+ //#region src/element/contracts.d.ts
5
+ type ImperativeHandleFactory<Element extends HTMLElement, Handle> = PublicHandleFactory<Element, Handle>;
6
+ interface ElementBindingConfig<Props extends object> {
7
+ properties?: readonly (keyof Props)[];
8
+ events?: Record<string, string>;
9
+ }
10
+ interface ElementBridgeConfig<Props extends object, Element extends HTMLElement = HTMLElement, Handle = Element> extends ElementBindingConfig<Props> {
11
+ createHandle?: ImperativeHandleFactory<Element, Handle>;
12
+ }
13
+ interface ElementBridgeContract<Props extends object, Element extends HTMLElement = HTMLElement, Handle = Element> extends ElementBridgeConfig<Props, Element, Handle> {
14
+ tagName: string;
15
+ }
16
+ interface ElementBindingOptions {
17
+ assignmentErrors?: 'ignore' | 'throw';
18
+ }
19
+ interface ElementBinding<Props extends object> {
20
+ readonly disposed: boolean;
21
+ update(input: Props): void;
22
+ updateProperties(input: Props): void;
23
+ updateEvents(input: Props): void;
24
+ disconnectEvents(): void;
25
+ dispose(): void;
26
+ }
27
+ //#endregion
28
+ //#region src/element/create-element-facade.d.ts
29
+ declare function createElementFacade<Element extends HTMLElement, const Keys extends readonly (keyof Element)[]>(keys: Keys): ImperativeHandleFactory<Element, Pick<Element, Keys[number]>>;
30
+ //#endregion
31
+ //#region src/element/create-element-binding.d.ts
32
+ declare function createElementBinding<Props extends object>(element: HTMLElement, config: ElementBindingConfig<Props>, options?: ElementBindingOptions): ElementBinding<Props>;
33
+ //#endregion
34
+ export { ElementBindingOptions as a, ImperativeHandleFactory as c, ElementBindingConfig as i, createElementFacade as n, ElementBridgeConfig as o, ElementBinding as r, ElementBridgeContract as s, createElementBinding as t };
35
+ //# sourceMappingURL=element-BJpk34By.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"element-BJpk34By.d.cts","names":[],"sources":["../src/facade/types.ts","../src/element/contracts.ts","../src/element/create-element-facade.ts","../src/element/create-element-binding.ts"],"mappings":";KACY,oBAAoB,uBAAuB,WACpD,iBAAiB,kBAAkB;;;KCA1B,wBAAwB,gBAAgB,aAAa,UAAU,oBAAoB,SAAS;UAGvF,qBAAqB;EACpC,6BAA6B;EAC7B,SAAS;;UAGM,oBAAoB,sBAAsB,gBAAgB,cAAc,aAAa,SAAS,iBACrG,qBAAqB;EAC7B,eAAe,wBAAwB,SAAS;;UAGjC,sBAAsB,sBAAsB,gBAAgB,cAAc,aAAa,SAAS,iBACvG,oBAAoB,OAAO,SAAS;EAC5C;;UAGe;EACf;;UAIe,eAAe;WACrB;EAET,OAAO,OAAO;EACd,iBAAiB,OAAO;EACxB,aAAa,OAAO;EAEpB;EAEA;;;;iBC9Bc,oBAAoB,gBAAgB,mBAAmB,6BAA6B,YAClG,MAAM,OACL,wBAAwB,SAAS,KAAK,SAAS;;;iBCDlC,qBAAqB,sBACnC,SAAS,aACT,QAAQ,qBAAqB,QAC7B,UAAS,wBACR,eAAe"}
@@ -0,0 +1,35 @@
1
+ //#region src/facade/types.d.ts
2
+ type PublicHandleFactory<Target extends object, Handle> = (getTarget: () => Target | null) => Handle;
3
+ //#endregion
4
+ //#region src/element/contracts.d.ts
5
+ type ImperativeHandleFactory<Element extends HTMLElement, Handle> = PublicHandleFactory<Element, Handle>;
6
+ interface ElementBindingConfig<Props extends object> {
7
+ properties?: readonly (keyof Props)[];
8
+ events?: Record<string, string>;
9
+ }
10
+ interface ElementBridgeConfig<Props extends object, Element extends HTMLElement = HTMLElement, Handle = Element> extends ElementBindingConfig<Props> {
11
+ createHandle?: ImperativeHandleFactory<Element, Handle>;
12
+ }
13
+ interface ElementBridgeContract<Props extends object, Element extends HTMLElement = HTMLElement, Handle = Element> extends ElementBridgeConfig<Props, Element, Handle> {
14
+ tagName: string;
15
+ }
16
+ interface ElementBindingOptions {
17
+ assignmentErrors?: 'ignore' | 'throw';
18
+ }
19
+ interface ElementBinding<Props extends object> {
20
+ readonly disposed: boolean;
21
+ update(input: Props): void;
22
+ updateProperties(input: Props): void;
23
+ updateEvents(input: Props): void;
24
+ disconnectEvents(): void;
25
+ dispose(): void;
26
+ }
27
+ //#endregion
28
+ //#region src/element/create-element-facade.d.ts
29
+ declare function createElementFacade<Element extends HTMLElement, const Keys extends readonly (keyof Element)[]>(keys: Keys): ImperativeHandleFactory<Element, Pick<Element, Keys[number]>>;
30
+ //#endregion
31
+ //#region src/element/create-element-binding.d.ts
32
+ declare function createElementBinding<Props extends object>(element: HTMLElement, config: ElementBindingConfig<Props>, options?: ElementBindingOptions): ElementBinding<Props>;
33
+ //#endregion
34
+ export { ElementBindingOptions as a, ImperativeHandleFactory as c, ElementBindingConfig as i, createElementFacade as n, ElementBridgeConfig as o, ElementBinding as r, ElementBridgeContract as s, createElementBinding as t };
35
+ //# sourceMappingURL=element-BJpk34By.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"element-BJpk34By.d.ts","names":[],"sources":["../src/facade/types.ts","../src/element/contracts.ts","../src/element/create-element-facade.ts","../src/element/create-element-binding.ts"],"mappings":";KACY,oBAAoB,uBAAuB,WACpD,iBAAiB,kBAAkB;;;KCA1B,wBAAwB,gBAAgB,aAAa,UAAU,oBAAoB,SAAS;UAGvF,qBAAqB;EACpC,6BAA6B;EAC7B,SAAS;;UAGM,oBAAoB,sBAAsB,gBAAgB,cAAc,aAAa,SAAS,iBACrG,qBAAqB;EAC7B,eAAe,wBAAwB,SAAS;;UAGjC,sBAAsB,sBAAsB,gBAAgB,cAAc,aAAa,SAAS,iBACvG,oBAAoB,OAAO,SAAS;EAC5C;;UAGe;EACf;;UAIe,eAAe;WACrB;EAET,OAAO,OAAO;EACd,iBAAiB,OAAO;EACxB,aAAa,OAAO;EAEpB;EAEA;;;;iBC9Bc,oBAAoB,gBAAgB,mBAAmB,6BAA6B,YAClG,MAAM,OACL,wBAAwB,SAAS,KAAK,SAAS;;;iBCDlC,qBAAqB,sBACnC,SAAS,aACT,QAAQ,qBAAqB,QAC7B,UAAS,wBACR,eAAe"}
@@ -0,0 +1,190 @@
1
+ //#region src/facade/create-public-facade.ts
2
+ function findDescriptor(target, key) {
3
+ let current = target;
4
+ while (current) {
5
+ const descriptor = Object.getOwnPropertyDescriptor(current, key);
6
+ if (descriptor) return descriptor;
7
+ current = Object.getPrototypeOf(current);
8
+ }
9
+ }
10
+ /** Allow-list projection, not a sandbox or revocable command capability. */
11
+ function createPublicFacade(keys, detachedMessage = "Public handle target is not available") {
12
+ const uniqueKeys = Array.from(new Set(keys));
13
+ return (getElement) => {
14
+ const requireElement = () => {
15
+ const element = getElement();
16
+ if (!element) throw new Error(detachedMessage);
17
+ return element;
18
+ };
19
+ const methods = /* @__PURE__ */ new WeakMap();
20
+ const facade = {};
21
+ for (const key of uniqueKeys) Object.defineProperty(facade, key, {
22
+ configurable: false,
23
+ enumerable: true,
24
+ get() {
25
+ const element = requireElement();
26
+ const value = Reflect.get(element, key, element);
27
+ if (typeof value !== "function") return value;
28
+ let cache = methods.get(element);
29
+ if (!cache) {
30
+ cache = /* @__PURE__ */ new Map();
31
+ methods.set(element, cache);
32
+ }
33
+ const cached = cache.get(key);
34
+ if (cached?.source === value) return cached.bound;
35
+ const bound = value.bind(element);
36
+ cache.set(key, {
37
+ source: value,
38
+ bound
39
+ });
40
+ return bound;
41
+ },
42
+ set(value) {
43
+ const element = requireElement();
44
+ const descriptor = findDescriptor(element, key);
45
+ if (descriptor && !descriptor.set && !descriptor.writable || !Reflect.set(element, key, value, element)) throw new TypeError(`Cannot assign to read-only property '${String(key)}'`);
46
+ }
47
+ });
48
+ return Object.freeze(facade);
49
+ };
50
+ }
51
+
52
+ //#endregion
53
+ //#region src/element/create-element-facade.ts
54
+ /** DOM specialization of the internal object projection; not a revocable capability. */
55
+ function createElementFacade(keys) {
56
+ return createPublicFacade(keys, "Custom element handle is not mounted");
57
+ }
58
+
59
+ //#endregion
60
+ //#region src/element/event-bindings.ts
61
+ function isHandler(value) {
62
+ return typeof value === "function" || typeof value === "object" && value !== null && typeof value.handleEvent === "function";
63
+ }
64
+ function createEventBindings(element, events, active) {
65
+ const bindings = /* @__PURE__ */ new Map();
66
+ function remove(key, binding) {
67
+ binding.active = false;
68
+ bindings.delete(key);
69
+ element.removeEventListener(binding.eventName, binding.listener);
70
+ }
71
+ return {
72
+ update(input) {
73
+ const handlers = input;
74
+ for (const [key, eventName] of events) {
75
+ if (!active()) return;
76
+ const handler = handlers[key];
77
+ const old = bindings.get(key);
78
+ if (old?.handler === handler) continue;
79
+ if (old) remove(key, old);
80
+ if (!active()) return;
81
+ if (!isHandler(handler)) continue;
82
+ const binding = {
83
+ handler,
84
+ eventName,
85
+ active: true,
86
+ listener(event) {
87
+ if (!active() || !binding.active) return;
88
+ if (typeof handler === "function") handler(event);
89
+ else handler.handleEvent(event);
90
+ }
91
+ };
92
+ bindings.set(key, binding);
93
+ try {
94
+ element.addEventListener(eventName, binding.listener);
95
+ } catch (error) {
96
+ remove(key, binding);
97
+ throw error;
98
+ }
99
+ if (!active()) remove(key, binding);
100
+ }
101
+ },
102
+ disconnect() {
103
+ for (const [key, binding] of bindings) remove(key, binding);
104
+ }
105
+ };
106
+ }
107
+
108
+ //#endregion
109
+ //#region src/element/property-bindings.ts
110
+ /** Only attempted bridge writes are owned. Omission releases ownership even if reset is rejected. */
111
+ function createPropertyBindings(element, properties, active, assignmentErrors) {
112
+ const applied = /* @__PURE__ */ new Set();
113
+ const host = element;
114
+ return (input) => {
115
+ for (const key of properties) {
116
+ if (!active()) return;
117
+ if (key in input) {
118
+ const value = input[key];
119
+ if (!active()) return;
120
+ applied.add(key);
121
+ try {
122
+ host[key] = value;
123
+ } catch (error) {
124
+ if (assignmentErrors === "throw") throw error;
125
+ }
126
+ } else if (applied.delete(key)) try {
127
+ host[key] = void 0;
128
+ } catch {}
129
+ }
130
+ };
131
+ }
132
+
133
+ //#endregion
134
+ //#region src/element/create-element-binding.ts
135
+ /** Framework-neutral DOM transport. Lifecycle adapters supply complete snapshots, not patches. */
136
+ function createElementBinding(element, config, options = {}) {
137
+ let disposed = false;
138
+ let updating = false;
139
+ const active = () => !disposed;
140
+ const properties = createPropertyBindings(element, Array.from(new Set(config.properties ?? [])), active, options.assignmentErrors ?? "ignore");
141
+ const events = createEventBindings(element, Object.entries(config.events ?? {}), active);
142
+ function run(update) {
143
+ if (disposed) throw new Error("Element binding is disposed");
144
+ if (updating) throw new Error("Element binding update is already in progress");
145
+ updating = true;
146
+ try {
147
+ update();
148
+ } finally {
149
+ updating = false;
150
+ }
151
+ }
152
+ return {
153
+ get disposed() {
154
+ return disposed;
155
+ },
156
+ update(input) {
157
+ run(() => {
158
+ events.update(input);
159
+ if (active()) properties(input);
160
+ });
161
+ },
162
+ updateProperties(input) {
163
+ run(() => properties(input));
164
+ },
165
+ updateEvents(input) {
166
+ run(() => events.update(input));
167
+ },
168
+ disconnectEvents() {
169
+ events.disconnect();
170
+ },
171
+ dispose() {
172
+ disposed = true;
173
+ events.disconnect();
174
+ }
175
+ };
176
+ }
177
+
178
+ //#endregion
179
+ Object.defineProperty(exports, 'createElementBinding', {
180
+ enumerable: true,
181
+ get: function () {
182
+ return createElementBinding;
183
+ }
184
+ });
185
+ Object.defineProperty(exports, 'createElementFacade', {
186
+ enumerable: true,
187
+ get: function () {
188
+ return createElementFacade;
189
+ }
190
+ });
@@ -0,0 +1,180 @@
1
+ //#region src/facade/create-public-facade.ts
2
+ function findDescriptor(target, key) {
3
+ let current = target;
4
+ while (current) {
5
+ const descriptor = Object.getOwnPropertyDescriptor(current, key);
6
+ if (descriptor) return descriptor;
7
+ current = Object.getPrototypeOf(current);
8
+ }
9
+ }
10
+ /** Allow-list projection, not a sandbox or revocable command capability. */
11
+ function createPublicFacade(keys, detachedMessage = "Public handle target is not available") {
12
+ const uniqueKeys = Array.from(new Set(keys));
13
+ return (getElement) => {
14
+ const requireElement = () => {
15
+ const element = getElement();
16
+ if (!element) throw new Error(detachedMessage);
17
+ return element;
18
+ };
19
+ const methods = /* @__PURE__ */ new WeakMap();
20
+ const facade = {};
21
+ for (const key of uniqueKeys) Object.defineProperty(facade, key, {
22
+ configurable: false,
23
+ enumerable: true,
24
+ get() {
25
+ const element = requireElement();
26
+ const value = Reflect.get(element, key, element);
27
+ if (typeof value !== "function") return value;
28
+ let cache = methods.get(element);
29
+ if (!cache) {
30
+ cache = /* @__PURE__ */ new Map();
31
+ methods.set(element, cache);
32
+ }
33
+ const cached = cache.get(key);
34
+ if (cached?.source === value) return cached.bound;
35
+ const bound = value.bind(element);
36
+ cache.set(key, {
37
+ source: value,
38
+ bound
39
+ });
40
+ return bound;
41
+ },
42
+ set(value) {
43
+ const element = requireElement();
44
+ const descriptor = findDescriptor(element, key);
45
+ if (descriptor && !descriptor.set && !descriptor.writable || !Reflect.set(element, key, value, element)) throw new TypeError(`Cannot assign to read-only property '${String(key)}'`);
46
+ }
47
+ });
48
+ return Object.freeze(facade);
49
+ };
50
+ }
51
+
52
+ //#endregion
53
+ //#region src/element/create-element-facade.ts
54
+ /** DOM specialization of the internal object projection; not a revocable capability. */
55
+ function createElementFacade(keys) {
56
+ return createPublicFacade(keys, "Custom element handle is not mounted");
57
+ }
58
+
59
+ //#endregion
60
+ //#region src/element/event-bindings.ts
61
+ function isHandler(value) {
62
+ return typeof value === "function" || typeof value === "object" && value !== null && typeof value.handleEvent === "function";
63
+ }
64
+ function createEventBindings(element, events, active) {
65
+ const bindings = /* @__PURE__ */ new Map();
66
+ function remove(key, binding) {
67
+ binding.active = false;
68
+ bindings.delete(key);
69
+ element.removeEventListener(binding.eventName, binding.listener);
70
+ }
71
+ return {
72
+ update(input) {
73
+ const handlers = input;
74
+ for (const [key, eventName] of events) {
75
+ if (!active()) return;
76
+ const handler = handlers[key];
77
+ const old = bindings.get(key);
78
+ if (old?.handler === handler) continue;
79
+ if (old) remove(key, old);
80
+ if (!active()) return;
81
+ if (!isHandler(handler)) continue;
82
+ const binding = {
83
+ handler,
84
+ eventName,
85
+ active: true,
86
+ listener(event) {
87
+ if (!active() || !binding.active) return;
88
+ if (typeof handler === "function") handler(event);
89
+ else handler.handleEvent(event);
90
+ }
91
+ };
92
+ bindings.set(key, binding);
93
+ try {
94
+ element.addEventListener(eventName, binding.listener);
95
+ } catch (error) {
96
+ remove(key, binding);
97
+ throw error;
98
+ }
99
+ if (!active()) remove(key, binding);
100
+ }
101
+ },
102
+ disconnect() {
103
+ for (const [key, binding] of bindings) remove(key, binding);
104
+ }
105
+ };
106
+ }
107
+
108
+ //#endregion
109
+ //#region src/element/property-bindings.ts
110
+ /** Only attempted bridge writes are owned. Omission releases ownership even if reset is rejected. */
111
+ function createPropertyBindings(element, properties, active, assignmentErrors) {
112
+ const applied = /* @__PURE__ */ new Set();
113
+ const host = element;
114
+ return (input) => {
115
+ for (const key of properties) {
116
+ if (!active()) return;
117
+ if (key in input) {
118
+ const value = input[key];
119
+ if (!active()) return;
120
+ applied.add(key);
121
+ try {
122
+ host[key] = value;
123
+ } catch (error) {
124
+ if (assignmentErrors === "throw") throw error;
125
+ }
126
+ } else if (applied.delete(key)) try {
127
+ host[key] = void 0;
128
+ } catch {}
129
+ }
130
+ };
131
+ }
132
+
133
+ //#endregion
134
+ //#region src/element/create-element-binding.ts
135
+ /** Framework-neutral DOM transport. Lifecycle adapters supply complete snapshots, not patches. */
136
+ function createElementBinding(element, config, options = {}) {
137
+ let disposed = false;
138
+ let updating = false;
139
+ const active = () => !disposed;
140
+ const properties = createPropertyBindings(element, Array.from(new Set(config.properties ?? [])), active, options.assignmentErrors ?? "ignore");
141
+ const events = createEventBindings(element, Object.entries(config.events ?? {}), active);
142
+ function run(update) {
143
+ if (disposed) throw new Error("Element binding is disposed");
144
+ if (updating) throw new Error("Element binding update is already in progress");
145
+ updating = true;
146
+ try {
147
+ update();
148
+ } finally {
149
+ updating = false;
150
+ }
151
+ }
152
+ return {
153
+ get disposed() {
154
+ return disposed;
155
+ },
156
+ update(input) {
157
+ run(() => {
158
+ events.update(input);
159
+ if (active()) properties(input);
160
+ });
161
+ },
162
+ updateProperties(input) {
163
+ run(() => properties(input));
164
+ },
165
+ updateEvents(input) {
166
+ run(() => events.update(input));
167
+ },
168
+ disconnectEvents() {
169
+ events.disconnect();
170
+ },
171
+ dispose() {
172
+ disposed = true;
173
+ events.disconnect();
174
+ }
175
+ };
176
+ }
177
+
178
+ //#endregion
179
+ export { createElementFacade as n, createElementBinding as t };
180
+ //# sourceMappingURL=element-DSSLaFmw.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"element-DSSLaFmw.js","names":[],"sources":["../src/facade/create-public-facade.ts","../src/element/create-element-facade.ts","../src/element/event-bindings.ts","../src/element/property-bindings.ts","../src/element/create-element-binding.ts"],"sourcesContent":["import type { PublicHandleFactory } from './types.js';\n\nfunction findDescriptor(target: object, key: PropertyKey): PropertyDescriptor | undefined {\n let current: object | null = target;\n while (current) {\n const descriptor = Object.getOwnPropertyDescriptor(current, key);\n if (descriptor) return descriptor;\n current = Object.getPrototypeOf(current);\n }\n return undefined;\n}\n\n/** Allow-list projection, not a sandbox or revocable command capability. */\nexport function createPublicFacade<Element extends object, const Keys extends readonly (keyof Element)[]>(\n keys: Keys,\n detachedMessage = 'Public handle target is not available',\n): PublicHandleFactory<Element, Pick<Element, Keys[number]>> {\n const uniqueKeys = Array.from(new Set(keys));\n return getElement => {\n const requireElement = (): Element => {\n const element = getElement();\n if (!element) throw new Error(detachedMessage);\n return element;\n };\n const methods = new WeakMap<Element, Map<PropertyKey, { source: unknown; bound: unknown }>>();\n const facade = {} as Pick<Element, Keys[number]>;\n for (const key of uniqueKeys) {\n Object.defineProperty(facade, key, {\n configurable: false,\n enumerable: true,\n get() {\n const element = requireElement();\n const value: unknown = Reflect.get(element, key, element);\n if (typeof value !== 'function') return value;\n let cache = methods.get(element);\n if (!cache) { cache = new Map(); methods.set(element, cache); }\n const cached = cache.get(key);\n if (cached?.source === value) return cached.bound;\n const bound = value.bind(element);\n cache.set(key, { source: value, bound });\n return bound;\n },\n set(value: unknown) {\n const element = requireElement();\n const descriptor = findDescriptor(element, key);\n if ((descriptor && !descriptor.set && !descriptor.writable) || !Reflect.set(element, key, value, element)) {\n throw new TypeError(`Cannot assign to read-only property '${String(key)}'`);\n }\n },\n });\n }\n return Object.freeze(facade);\n };\n}\n","import { createPublicFacade } from '../facade/create-public-facade.js';\nimport type { ImperativeHandleFactory } from './contracts.js';\n\n/** DOM specialization of the internal object projection; not a revocable capability. */\nexport function createElementFacade<Element extends HTMLElement, const Keys extends readonly (keyof Element)[]>(\n keys: Keys,\n): ImperativeHandleFactory<Element, Pick<Element, Keys[number]>> {\n return createPublicFacade<Element, Keys>(keys, 'Custom element handle is not mounted');\n}\n","type Handler = ((event: Event) => void) | { handleEvent(event: Event): void };\ninterface Binding {\n handler: Handler;\n eventName: string;\n listener: EventListener;\n active: boolean;\n}\n\nfunction isHandler(value: unknown): value is Handler {\n return typeof value === 'function' || (typeof value === 'object' && value !== null\n && typeof (value as { handleEvent?: unknown }).handleEvent === 'function');\n}\n\nexport function createEventBindings(element: HTMLElement, events: readonly (readonly [string, string])[], active: () => boolean) {\n const bindings = new Map<string, Binding>();\n function remove(key: string, binding: Binding): void {\n binding.active = false;\n bindings.delete(key);\n element.removeEventListener(binding.eventName, binding.listener);\n }\n return {\n update(input: object): void {\n const handlers = input as Record<string, unknown>;\n for (const [key, eventName] of events) {\n if (!active()) return;\n const handler = handlers[key];\n const old = bindings.get(key);\n if (old?.handler === handler) continue;\n if (old) remove(key, old);\n if (!active()) return;\n if (!isHandler(handler)) continue;\n const binding: Binding = {\n handler, eventName, active: true,\n listener(event) {\n if (!active() || !binding.active) return;\n if (typeof handler === 'function') handler(event);\n else handler.handleEvent(event);\n },\n };\n bindings.set(key, binding);\n try { element.addEventListener(eventName, binding.listener); }\n catch (error) { remove(key, binding); throw error; }\n // Defensive against a host overriding addEventListener and disposing reentrantly.\n if (!active()) remove(key, binding);\n }\n },\n disconnect(): void {\n for (const [key, binding] of bindings) remove(key, binding);\n },\n };\n}\n","/** Only attempted bridge writes are owned. Omission releases ownership even if reset is rejected. */\nexport function createPropertyBindings<Props extends object>(\n element: HTMLElement,\n properties: readonly (keyof Props)[],\n active: () => boolean,\n assignmentErrors: 'ignore' | 'throw',\n) {\n const applied = new Set<keyof Props>();\n const host = element as unknown as Record<keyof Props, unknown>;\n return (input: Props): void => {\n for (const key of properties) {\n if (!active()) return;\n if (key in input) {\n const value = input[key];\n if (!active()) return;\n applied.add(key);\n try { host[key] = value; }\n catch (error) { if (assignmentErrors === 'throw') throw error; }\n } else if (applied.delete(key)) {\n try { host[key] = undefined; } catch { /* Omission cleanup is always best-effort. */ }\n }\n }\n };\n}\n","import type { ElementBinding, ElementBindingConfig, ElementBindingOptions } from './contracts.js';\nimport { createEventBindings } from './event-bindings.js';\nimport { createPropertyBindings } from './property-bindings.js';\n\n/** Framework-neutral DOM transport. Lifecycle adapters supply complete snapshots, not patches. */\nexport function createElementBinding<Props extends object>(\n element: HTMLElement,\n config: ElementBindingConfig<Props>,\n options: ElementBindingOptions = {},\n): ElementBinding<Props> {\n let disposed = false;\n let updating = false;\n const active = () => !disposed;\n const properties = createPropertyBindings(element, Array.from(new Set(config.properties ?? [])), active, options.assignmentErrors ?? 'ignore');\n const events = createEventBindings(element, Object.entries(config.events ?? {}), active);\n function run(update: () => void): void {\n if (disposed) throw new Error('Element binding is disposed');\n if (updating) throw new Error('Element binding update is already in progress');\n updating = true;\n try { update(); } finally { updating = false; }\n }\n return {\n get disposed() { return disposed; },\n update(input) { run(() => { events.update(input); if (active()) properties(input); }); },\n updateProperties(input) { run(() => properties(input)); },\n updateEvents(input) { run(() => events.update(input)); },\n disconnectEvents() { events.disconnect(); },\n dispose() { disposed = true; events.disconnect(); },\n };\n}\n"],"mappings":"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"}
@@ -0,0 +1,81 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
2
+ const require_element = require('./element-BcfeiQgA.cjs');
3
+
4
+ //#region src/bridges/react-element/create-react-element-bridge.ts
5
+ function assignRef(ref, value) {
6
+ if (typeof ref === "function") ref(value);
7
+ else if (ref) ref.current = value;
8
+ }
9
+ /** Opt-in host adapter; inject the consuming runtime rather than importing another hook dispatcher. */
10
+ function createReactElementBridge(React, options, assignmentErrors = "ignore") {
11
+ const useLayout = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
12
+ const { tagName, createHandle } = options;
13
+ const properties = Array.from(new Set(options.properties ?? []));
14
+ const propertySet = new Set(properties);
15
+ const events = { ...options.events };
16
+ const eventProps = new Set(Object.keys(events));
17
+ const config = {
18
+ properties,
19
+ events
20
+ };
21
+ const Bridge = React.forwardRef(function ElementBridge(props, forwardedRef) {
22
+ const elementRef = React.useRef(null);
23
+ const [element, setElement] = React.useState(null);
24
+ const bindingRef = React.useRef(null);
25
+ const rawForwardedRef = React.useRef(forwardedRef);
26
+ const ref = React.useCallback((node) => {
27
+ if (bindingRef.current && bindingRef.current.element !== node) {
28
+ bindingRef.current.binding.dispose();
29
+ bindingRef.current = null;
30
+ }
31
+ elementRef.current = node;
32
+ if (!createHandle) assignRef(rawForwardedRef.current, node);
33
+ setElement(node);
34
+ }, []);
35
+ React.useImperativeHandle(createHandle ? forwardedRef : null, () => createHandle ? createHandle(() => elementRef.current) : null, [createHandle]);
36
+ useLayout(() => {
37
+ if (createHandle || rawForwardedRef.current === forwardedRef) return;
38
+ const previousRef = rawForwardedRef.current;
39
+ rawForwardedRef.current = forwardedRef;
40
+ assignRef(previousRef, null);
41
+ assignRef(forwardedRef, elementRef.current);
42
+ }, [
43
+ createHandle,
44
+ element,
45
+ forwardedRef
46
+ ]);
47
+ useLayout(() => {
48
+ const currentElement = elementRef.current;
49
+ if (!element || !currentElement || element !== currentElement) return;
50
+ if (bindingRef.current?.element !== currentElement) {
51
+ bindingRef.current?.binding.dispose();
52
+ bindingRef.current = {
53
+ element: currentElement,
54
+ binding: require_element.createElementBinding(currentElement, config, { assignmentErrors })
55
+ };
56
+ }
57
+ bindingRef.current.binding.update(props);
58
+ }, [element, props]);
59
+ React.useEffect(() => {
60
+ const current = bindingRef.current;
61
+ const currentElement = elementRef.current;
62
+ if (currentElement && current?.element === currentElement) current.binding.updateEvents(props);
63
+ });
64
+ React.useEffect(() => () => {
65
+ bindingRef.current?.binding.disconnectEvents();
66
+ }, []);
67
+ const domProps = { ref };
68
+ for (const [key, value] of Object.entries(props)) {
69
+ if (propertySet.has(key) || eventProps.has(key)) continue;
70
+ domProps[key === "className" ? "class" : key === "htmlFor" ? "for" : key] = value;
71
+ }
72
+ return React.createElement(tagName, domProps);
73
+ });
74
+ Bridge.displayName = `ElementBridge(${tagName})`;
75
+ return Bridge;
76
+ }
77
+
78
+ //#endregion
79
+ exports.createElementBinding = require_element.createElementBinding;
80
+ exports.createElementFacade = require_element.createElementFacade;
81
+ exports.createReactElementBridge = createReactElementBridge;
@@ -0,0 +1,11 @@
1
+ import { a as ElementBindingOptions, c as ImperativeHandleFactory, i as ElementBindingConfig, n as createElementFacade, o as ElementBridgeConfig, r as ElementBinding, s as ElementBridgeContract, t as createElementBinding } from "./element-BJpk34By.cjs";
2
+ import { t as PublicActionMethods } from "./public-action-methods-C_ppItRr.cjs";
3
+ import * as React from "react";
4
+ //#region src/bridges/react-element/types.d.ts
5
+ type ReactElementComponent<Props, Element extends HTMLElement, Handle = Element> = React.ForwardRefExoticComponent<React.PropsWithoutRef<Props & Omit<React.HTMLAttributes<Element>, keyof Props>> & React.RefAttributes<Handle>>;
6
+ //#endregion
7
+ //#region src/bridges/react-element/create-react-element-bridge.d.ts
8
+ export declare function createReactElementBridge<Props extends object = Record<string, unknown>, Element extends HTMLElement = HTMLElement, Handle = Element>(React: typeof import('react'), options: ElementBridgeContract<Props, Element, Handle>, assignmentErrors?: 'ignore' | 'throw'): ReactElementComponent<Props, Element, Handle>;
9
+ //#endregion
10
+ export { type ElementBinding, type ElementBindingConfig, type ElementBindingOptions, type ElementBridgeConfig, type ElementBridgeContract, type ImperativeHandleFactory, type PublicActionMethods, type ReactElementComponent, createElementBinding, createElementFacade };
11
+ //# sourceMappingURL=element-react.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"element-react.d.cts","names":[],"sources":["../src/bridges/react-element/types.ts","../src/bridges/react-element/create-react-element-bridge.ts"],"mappings":";;;;KAEY,sBAAsB,OAAO,gBAAgB,aAAa,SAAS,WAAW,MAAM,0BAC9F,MAAM,gBAAgB,QAAQ,KAAK,MAAM,eAAe,gBAAgB,UAAU,MAAM,cAAc;;;wBCQxF,yBAAyB,uBAAuB,yBAAyB,gBAAgB,cAAc,aAAa,SAAS,SAC3I,+BACA,SAAS,sBAAsB,OAAO,SAAS,SAC/C,wCACC,sBAAsB,OAAO,SAAS"}
@@ -0,0 +1,11 @@
1
+ import { a as ElementBindingOptions, c as ImperativeHandleFactory, i as ElementBindingConfig, n as createElementFacade, o as ElementBridgeConfig, r as ElementBinding, s as ElementBridgeContract, t as createElementBinding } from "./element-BJpk34By.js";
2
+ import { t as PublicActionMethods } from "./public-action-methods-C_ppItRr.js";
3
+ import * as React from "react";
4
+ //#region src/bridges/react-element/types.d.ts
5
+ type ReactElementComponent<Props, Element extends HTMLElement, Handle = Element> = React.ForwardRefExoticComponent<React.PropsWithoutRef<Props & Omit<React.HTMLAttributes<Element>, keyof Props>> & React.RefAttributes<Handle>>;
6
+ //#endregion
7
+ //#region src/bridges/react-element/create-react-element-bridge.d.ts
8
+ export declare function createReactElementBridge<Props extends object = Record<string, unknown>, Element extends HTMLElement = HTMLElement, Handle = Element>(React: typeof import('react'), options: ElementBridgeContract<Props, Element, Handle>, assignmentErrors?: 'ignore' | 'throw'): ReactElementComponent<Props, Element, Handle>;
9
+ //#endregion
10
+ export { type ElementBinding, type ElementBindingConfig, type ElementBindingOptions, type ElementBridgeConfig, type ElementBridgeContract, type ImperativeHandleFactory, type PublicActionMethods, type ReactElementComponent, createElementBinding, createElementFacade };
11
+ //# sourceMappingURL=element-react.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"element-react.d.ts","names":[],"sources":["../src/bridges/react-element/types.ts","../src/bridges/react-element/create-react-element-bridge.ts"],"mappings":";;;;KAEY,sBAAsB,OAAO,gBAAgB,aAAa,SAAS,WAAW,MAAM,0BAC9F,MAAM,gBAAgB,QAAQ,KAAK,MAAM,eAAe,gBAAgB,UAAU,MAAM,cAAc;;;wBCQxF,yBAAyB,uBAAuB,yBAAyB,gBAAgB,cAAc,aAAa,SAAS,SAC3I,+BACA,SAAS,sBAAsB,OAAO,SAAS,SAC/C,wCACC,sBAAsB,OAAO,SAAS"}