@ox-content/islands 0.3.0-alpha.11
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/dist/index-Bc2Aw38x.d.ts +177 -0
- package/dist/index-Bc2Aw38x.d.ts.map +1 -0
- package/dist/index.js +261 -0
- package/dist/index.js.map +1 -0
- package/package.json +49 -0
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
//#region src/types.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Island Architecture Types
|
|
4
|
+
*
|
|
5
|
+
* Framework-agnostic type definitions for the Island system.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Loading strategy for islands.
|
|
9
|
+
*
|
|
10
|
+
* - `eager`: Hydrate immediately on page load
|
|
11
|
+
* - `idle`: Hydrate when the browser is idle (requestIdleCallback)
|
|
12
|
+
* - `visible`: Hydrate when the element becomes visible (IntersectionObserver)
|
|
13
|
+
* - `media`: Hydrate when a media query matches
|
|
14
|
+
*/
|
|
15
|
+
type LoadStrategy = "eager" | "idle" | "visible" | "media";
|
|
16
|
+
/**
|
|
17
|
+
* Island configuration extracted from data attributes.
|
|
18
|
+
*/
|
|
19
|
+
interface IslandConfig {
|
|
20
|
+
/** Unique island identifier */
|
|
21
|
+
id: string;
|
|
22
|
+
/** Component name to hydrate */
|
|
23
|
+
component: string;
|
|
24
|
+
/** Loading strategy */
|
|
25
|
+
load: LoadStrategy;
|
|
26
|
+
/** Media query for 'media' load strategy */
|
|
27
|
+
mediaQuery?: string;
|
|
28
|
+
/** Component props (JSON serialized in data-ox-props) */
|
|
29
|
+
props: Record<string, unknown>;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Hydration function signature.
|
|
33
|
+
*
|
|
34
|
+
* Called when an island should be hydrated.
|
|
35
|
+
* Returns an optional cleanup function.
|
|
36
|
+
*/
|
|
37
|
+
type HydrateFunction = (element: HTMLElement, props: Record<string, unknown>) => void | (() => void);
|
|
38
|
+
/**
|
|
39
|
+
* Component registry mapping component names to hydrate functions.
|
|
40
|
+
*/
|
|
41
|
+
type ComponentRegistry = Map<string, HydrateFunction>;
|
|
42
|
+
/**
|
|
43
|
+
* Options for initializing islands.
|
|
44
|
+
*/
|
|
45
|
+
interface InitIslandsOptions {
|
|
46
|
+
/** Root margin for IntersectionObserver (visible strategy). Default: "200px" */
|
|
47
|
+
rootMargin?: string;
|
|
48
|
+
/** Threshold for IntersectionObserver. Default: 0 */
|
|
49
|
+
threshold?: number;
|
|
50
|
+
/** Timeout for idle callback fallback in ms. Default: 200 */
|
|
51
|
+
idleTimeout?: number;
|
|
52
|
+
/** Custom selector for finding islands. Default: "[data-ox-island]" */
|
|
53
|
+
selector?: string;
|
|
54
|
+
/** Called when an island starts hydrating */
|
|
55
|
+
onHydrateStart?: (element: HTMLElement, config: IslandConfig) => void;
|
|
56
|
+
/** Called when an island finishes hydrating */
|
|
57
|
+
onHydrateEnd?: (element: HTMLElement, config: IslandConfig) => void;
|
|
58
|
+
/** Called when hydration fails */
|
|
59
|
+
onHydrateError?: (element: HTMLElement, config: IslandConfig, error: Error) => void;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Island instance tracking.
|
|
63
|
+
*/
|
|
64
|
+
interface IslandInstance {
|
|
65
|
+
element: HTMLElement;
|
|
66
|
+
config: IslandConfig;
|
|
67
|
+
cleanup?: () => void;
|
|
68
|
+
hydrated: boolean;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Island controller returned by initIslands.
|
|
72
|
+
*/
|
|
73
|
+
interface IslandController {
|
|
74
|
+
/** All tracked island instances */
|
|
75
|
+
instances: IslandInstance[];
|
|
76
|
+
/** Manually hydrate a specific island */
|
|
77
|
+
hydrate: (element: HTMLElement) => void;
|
|
78
|
+
/** Destroy all islands and cleanup */
|
|
79
|
+
destroy: () => void;
|
|
80
|
+
}
|
|
81
|
+
//# sourceMappingURL=types.d.ts.map
|
|
82
|
+
//#endregion
|
|
83
|
+
//#region src/runtime.d.ts
|
|
84
|
+
/**
|
|
85
|
+
* Initialize islands with a hydration function.
|
|
86
|
+
*
|
|
87
|
+
* This is the main entry point for the island system.
|
|
88
|
+
* Pass a hydrate function that knows how to mount your components.
|
|
89
|
+
*
|
|
90
|
+
* @example Vue
|
|
91
|
+
* ```ts
|
|
92
|
+
* import { initIslands } from '@ox-content/islands';
|
|
93
|
+
* import { createApp, h } from 'vue';
|
|
94
|
+
* import Counter from './Counter.vue';
|
|
95
|
+
*
|
|
96
|
+
* const components = { Counter };
|
|
97
|
+
*
|
|
98
|
+
* initIslands((el, props) => {
|
|
99
|
+
* const name = el.dataset.oxIsland!;
|
|
100
|
+
* const Component = components[name];
|
|
101
|
+
* if (!Component) return;
|
|
102
|
+
*
|
|
103
|
+
* const app = createApp({ render: () => h(Component, props) });
|
|
104
|
+
* app.mount(el);
|
|
105
|
+
*
|
|
106
|
+
* return () => app.unmount();
|
|
107
|
+
* });
|
|
108
|
+
* ```
|
|
109
|
+
*
|
|
110
|
+
* @example React
|
|
111
|
+
* ```ts
|
|
112
|
+
* import { initIslands } from '@ox-content/islands';
|
|
113
|
+
* import { createRoot } from 'react-dom/client';
|
|
114
|
+
* import Counter from './Counter';
|
|
115
|
+
*
|
|
116
|
+
* const components = { Counter };
|
|
117
|
+
*
|
|
118
|
+
* initIslands((el, props) => {
|
|
119
|
+
* const name = el.dataset.oxIsland!;
|
|
120
|
+
* const Component = components[name];
|
|
121
|
+
* if (!Component) return;
|
|
122
|
+
*
|
|
123
|
+
* const root = createRoot(el);
|
|
124
|
+
* root.render(<Component {...props} />);
|
|
125
|
+
*
|
|
126
|
+
* return () => root.unmount();
|
|
127
|
+
* });
|
|
128
|
+
* ```
|
|
129
|
+
*
|
|
130
|
+
* @example Vanilla JS
|
|
131
|
+
* ```ts
|
|
132
|
+
* import { initIslands } from '@ox-content/islands';
|
|
133
|
+
*
|
|
134
|
+
* initIslands((el, props) => {
|
|
135
|
+
* const name = el.dataset.oxIsland!;
|
|
136
|
+
*
|
|
137
|
+
* if (name === 'Counter') {
|
|
138
|
+
* let count = props.initial || 0;
|
|
139
|
+
* const button = el.querySelector('button')!;
|
|
140
|
+
* const handler = () => {
|
|
141
|
+
* count++;
|
|
142
|
+
* button.textContent = String(count);
|
|
143
|
+
* };
|
|
144
|
+
* button.addEventListener('click', handler);
|
|
145
|
+
* return () => button.removeEventListener('click', handler);
|
|
146
|
+
* }
|
|
147
|
+
* });
|
|
148
|
+
* ```
|
|
149
|
+
*/
|
|
150
|
+
declare function initIslands(hydrate: HydrateFunction, options?: InitIslandsOptions): IslandController;
|
|
151
|
+
/**
|
|
152
|
+
* Create a deferred hydration wrapper.
|
|
153
|
+
*
|
|
154
|
+
* Returns a function that can be called to hydrate islands later.
|
|
155
|
+
* Useful for frameworks that need to register components first.
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```ts
|
|
159
|
+
* const deferredInit = createDeferredInit();
|
|
160
|
+
*
|
|
161
|
+
* // Later, after components are ready
|
|
162
|
+
* const components = await loadComponents();
|
|
163
|
+
* deferredInit((el, props) => {
|
|
164
|
+
* const Component = components[el.dataset.oxIsland!];
|
|
165
|
+
* // ...
|
|
166
|
+
* });
|
|
167
|
+
* ```
|
|
168
|
+
*/
|
|
169
|
+
declare function createDeferredInit(options?: InitIslandsOptions): (hydrate: HydrateFunction) => IslandController;
|
|
170
|
+
/**
|
|
171
|
+
* Check if islands are supported in the current environment.
|
|
172
|
+
*/
|
|
173
|
+
declare function isIslandsSupported(): boolean;
|
|
174
|
+
//# sourceMappingURL=runtime.d.ts.map
|
|
175
|
+
//#endregion
|
|
176
|
+
export { type ComponentRegistry, type HydrateFunction, type InitIslandsOptions, type IslandConfig, type IslandController, type IslandInstance, type LoadStrategy, createDeferredInit, initIslands, isIslandsSupported };
|
|
177
|
+
//# sourceMappingURL=index-Bc2Aw38x.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index-Bc2Aw38x.d.ts","names":[],"sources":["../src/types.ts","../src/runtime.ts"],"sourcesContent":[],"mappings":";;AAcA;AAKA;;;;;AAmBA;;;;;AAQA;AAA6B,KAhCjB,YAAA,GAgCiB,OAAA,GAAA,MAAA,GAAA,SAAA,GAAA,OAAA;;;;AAKZ,UAhCA,YAAA,CAgCkB;EAAA;MAUN,MAAA;;WAEF,EAAA,MAAA;;MAEE,EAxCrB,YAwCqB;;YAA0C,CAAA,EAAA,MAAA;EAAK;EAM3D,KAAA,EA1CR,MA0CQ,CAAA,MAAc,EAAA,OAAA,CAAA;;;;;AAU/B;;;AAIqB,KA/CT,eAAA,GA+CS,CAAA,OAAA,EA9CV,WA8CU,EAAA,KAAA,EA7CZ,MA6CY,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,GAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;;;;KAvCT,iBAAA,GAAoB,YAAY;ACqI5C;;;AAEY,UDlIK,kBAAA,CCkIL;;EACO,UAAA,CAAA,EAAA,MAAA;EA2JH;EAAkB,SAAA,CAAA,EAAA,MAAA;;aAErB,CAAA,EAAA,MAAA;;EAAoC,QAAA,CAAA,EAAA,MAAA;EAOjC;6BD7Ra,qBAAqB;;2BAEvB,qBAAqB;;6BAEnB,qBAAqB,qBAAqB;;;;;UAMtD,cAAA;WACN;UACD;;;;;;;UAQO,gBAAA;;aAEJ;;qBAEQ;;;;;;;AA/CrB;;;;;AAQA;;;;;AAKA;;;;;;;;;;AAoBA;;;;;AAUA;;;;;;;;ACkGA;;;;;;AA8JA;;;;;;AASA;;;;;;;;;;;;;;;;;;;;;iBAvKgB,WAAA,UACL,2BACC,qBACT;;;;;;;;;;;;;;;;;;;iBA2Ja,kBAAA,WACJ,+BACC,oBAAoB;;;;iBAOjB,kBAAA,CAAA"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
//#region src/runtime.ts
|
|
2
|
+
const defaultOptions = {
|
|
3
|
+
rootMargin: "200px",
|
|
4
|
+
threshold: 0,
|
|
5
|
+
idleTimeout: 200,
|
|
6
|
+
selector: "[data-ox-island]"
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* Parse island configuration from element attributes.
|
|
10
|
+
*/
|
|
11
|
+
function parseIslandConfig(element) {
|
|
12
|
+
const component = element.dataset.oxIsland || "";
|
|
13
|
+
const load = element.dataset.oxLoad || "eager";
|
|
14
|
+
const mediaQuery = element.dataset.oxMedia;
|
|
15
|
+
let props = {};
|
|
16
|
+
try {
|
|
17
|
+
const propsJson = element.dataset.oxProps;
|
|
18
|
+
if (propsJson) props = JSON.parse(propsJson);
|
|
19
|
+
} catch (e) {
|
|
20
|
+
console.warn("[ox-islands] Failed to parse props for", element, e);
|
|
21
|
+
}
|
|
22
|
+
return {
|
|
23
|
+
id: element.id || `island-${Math.random().toString(36).slice(2, 9)}`,
|
|
24
|
+
component,
|
|
25
|
+
load,
|
|
26
|
+
mediaQuery,
|
|
27
|
+
props
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Observe element visibility using IntersectionObserver.
|
|
32
|
+
*/
|
|
33
|
+
function observeVisibility(element, callback, options) {
|
|
34
|
+
const observer = new IntersectionObserver((entries) => {
|
|
35
|
+
if (entries[0].isIntersecting) {
|
|
36
|
+
observer.disconnect();
|
|
37
|
+
callback();
|
|
38
|
+
}
|
|
39
|
+
}, {
|
|
40
|
+
rootMargin: options.rootMargin,
|
|
41
|
+
threshold: options.threshold
|
|
42
|
+
});
|
|
43
|
+
observer.observe(element);
|
|
44
|
+
return () => observer.disconnect();
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Observe media query changes.
|
|
48
|
+
*/
|
|
49
|
+
function observeMedia(query, callback) {
|
|
50
|
+
const mql = matchMedia(query);
|
|
51
|
+
if (mql.matches) {
|
|
52
|
+
callback();
|
|
53
|
+
return () => {};
|
|
54
|
+
}
|
|
55
|
+
const handler = () => {
|
|
56
|
+
if (mql.matches) {
|
|
57
|
+
mql.removeEventListener("change", handler);
|
|
58
|
+
callback();
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
mql.addEventListener("change", handler);
|
|
62
|
+
return () => mql.removeEventListener("change", handler);
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Schedule callback for browser idle time.
|
|
66
|
+
*/
|
|
67
|
+
function scheduleIdle(callback, timeout) {
|
|
68
|
+
if ("requestIdleCallback" in window) {
|
|
69
|
+
const id = requestIdleCallback(callback, { timeout });
|
|
70
|
+
return () => cancelIdleCallback(id);
|
|
71
|
+
}
|
|
72
|
+
const id = setTimeout(callback, timeout);
|
|
73
|
+
return () => clearTimeout(id);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Initialize islands with a hydration function.
|
|
77
|
+
*
|
|
78
|
+
* This is the main entry point for the island system.
|
|
79
|
+
* Pass a hydrate function that knows how to mount your components.
|
|
80
|
+
*
|
|
81
|
+
* @example Vue
|
|
82
|
+
* ```ts
|
|
83
|
+
* import { initIslands } from '@ox-content/islands';
|
|
84
|
+
* import { createApp, h } from 'vue';
|
|
85
|
+
* import Counter from './Counter.vue';
|
|
86
|
+
*
|
|
87
|
+
* const components = { Counter };
|
|
88
|
+
*
|
|
89
|
+
* initIslands((el, props) => {
|
|
90
|
+
* const name = el.dataset.oxIsland!;
|
|
91
|
+
* const Component = components[name];
|
|
92
|
+
* if (!Component) return;
|
|
93
|
+
*
|
|
94
|
+
* const app = createApp({ render: () => h(Component, props) });
|
|
95
|
+
* app.mount(el);
|
|
96
|
+
*
|
|
97
|
+
* return () => app.unmount();
|
|
98
|
+
* });
|
|
99
|
+
* ```
|
|
100
|
+
*
|
|
101
|
+
* @example React
|
|
102
|
+
* ```ts
|
|
103
|
+
* import { initIslands } from '@ox-content/islands';
|
|
104
|
+
* import { createRoot } from 'react-dom/client';
|
|
105
|
+
* import Counter from './Counter';
|
|
106
|
+
*
|
|
107
|
+
* const components = { Counter };
|
|
108
|
+
*
|
|
109
|
+
* initIslands((el, props) => {
|
|
110
|
+
* const name = el.dataset.oxIsland!;
|
|
111
|
+
* const Component = components[name];
|
|
112
|
+
* if (!Component) return;
|
|
113
|
+
*
|
|
114
|
+
* const root = createRoot(el);
|
|
115
|
+
* root.render(<Component {...props} />);
|
|
116
|
+
*
|
|
117
|
+
* return () => root.unmount();
|
|
118
|
+
* });
|
|
119
|
+
* ```
|
|
120
|
+
*
|
|
121
|
+
* @example Vanilla JS
|
|
122
|
+
* ```ts
|
|
123
|
+
* import { initIslands } from '@ox-content/islands';
|
|
124
|
+
*
|
|
125
|
+
* initIslands((el, props) => {
|
|
126
|
+
* const name = el.dataset.oxIsland!;
|
|
127
|
+
*
|
|
128
|
+
* if (name === 'Counter') {
|
|
129
|
+
* let count = props.initial || 0;
|
|
130
|
+
* const button = el.querySelector('button')!;
|
|
131
|
+
* const handler = () => {
|
|
132
|
+
* count++;
|
|
133
|
+
* button.textContent = String(count);
|
|
134
|
+
* };
|
|
135
|
+
* button.addEventListener('click', handler);
|
|
136
|
+
* return () => button.removeEventListener('click', handler);
|
|
137
|
+
* }
|
|
138
|
+
* });
|
|
139
|
+
* ```
|
|
140
|
+
*/
|
|
141
|
+
function initIslands(hydrate, options) {
|
|
142
|
+
const opts = {
|
|
143
|
+
...defaultOptions,
|
|
144
|
+
...options
|
|
145
|
+
};
|
|
146
|
+
const instances = [];
|
|
147
|
+
const cleanups = [];
|
|
148
|
+
/**
|
|
149
|
+
* Hydrate a single island element.
|
|
150
|
+
*/
|
|
151
|
+
function hydrateIsland(element, config) {
|
|
152
|
+
const instance = instances.find((i) => i.element === element);
|
|
153
|
+
if (instance?.hydrated) return;
|
|
154
|
+
try {
|
|
155
|
+
opts.onHydrateStart?.(element, config);
|
|
156
|
+
element.classList.add("ox-island-loading");
|
|
157
|
+
const cleanup = hydrate(element, config.props);
|
|
158
|
+
element.dataset.oxHydrated = "true";
|
|
159
|
+
element.classList.remove("ox-island-loading");
|
|
160
|
+
if (instance) {
|
|
161
|
+
instance.cleanup = cleanup || void 0;
|
|
162
|
+
instance.hydrated = true;
|
|
163
|
+
} else instances.push({
|
|
164
|
+
element,
|
|
165
|
+
config,
|
|
166
|
+
cleanup: cleanup || void 0,
|
|
167
|
+
hydrated: true
|
|
168
|
+
});
|
|
169
|
+
opts.onHydrateEnd?.(element, config);
|
|
170
|
+
} catch (error) {
|
|
171
|
+
element.classList.remove("ox-island-loading");
|
|
172
|
+
element.classList.add("ox-island-error");
|
|
173
|
+
element.dataset.oxError = error instanceof Error ? error.message : String(error);
|
|
174
|
+
opts.onHydrateError?.(element, config, error instanceof Error ? error : new Error(String(error)));
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Schedule hydration based on load strategy.
|
|
179
|
+
*/
|
|
180
|
+
function scheduleHydration(element, config) {
|
|
181
|
+
switch (config.load) {
|
|
182
|
+
case "eager":
|
|
183
|
+
hydrateIsland(element, config);
|
|
184
|
+
break;
|
|
185
|
+
case "idle": {
|
|
186
|
+
const cancel = scheduleIdle(() => hydrateIsland(element, config), opts.idleTimeout);
|
|
187
|
+
cleanups.push(cancel);
|
|
188
|
+
break;
|
|
189
|
+
}
|
|
190
|
+
case "visible": {
|
|
191
|
+
const cancel = observeVisibility(element, () => hydrateIsland(element, config), {
|
|
192
|
+
rootMargin: opts.rootMargin,
|
|
193
|
+
threshold: opts.threshold
|
|
194
|
+
});
|
|
195
|
+
cleanups.push(cancel);
|
|
196
|
+
break;
|
|
197
|
+
}
|
|
198
|
+
case "media":
|
|
199
|
+
if (config.mediaQuery) {
|
|
200
|
+
const cancel = observeMedia(config.mediaQuery, () => hydrateIsland(element, config));
|
|
201
|
+
cleanups.push(cancel);
|
|
202
|
+
} else hydrateIsland(element, config);
|
|
203
|
+
break;
|
|
204
|
+
default: hydrateIsland(element, config);
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
document.querySelectorAll(opts.selector).forEach((element) => {
|
|
208
|
+
const config = parseIslandConfig(element);
|
|
209
|
+
instances.push({
|
|
210
|
+
element,
|
|
211
|
+
config,
|
|
212
|
+
hydrated: false
|
|
213
|
+
});
|
|
214
|
+
scheduleHydration(element, config);
|
|
215
|
+
});
|
|
216
|
+
return {
|
|
217
|
+
instances,
|
|
218
|
+
hydrate(element) {
|
|
219
|
+
hydrateIsland(element, parseIslandConfig(element));
|
|
220
|
+
},
|
|
221
|
+
destroy() {
|
|
222
|
+
cleanups.forEach((cleanup) => cleanup());
|
|
223
|
+
cleanups.length = 0;
|
|
224
|
+
instances.forEach((instance) => {
|
|
225
|
+
if (instance.cleanup) instance.cleanup();
|
|
226
|
+
});
|
|
227
|
+
instances.length = 0;
|
|
228
|
+
}
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
/**
|
|
232
|
+
* Create a deferred hydration wrapper.
|
|
233
|
+
*
|
|
234
|
+
* Returns a function that can be called to hydrate islands later.
|
|
235
|
+
* Useful for frameworks that need to register components first.
|
|
236
|
+
*
|
|
237
|
+
* @example
|
|
238
|
+
* ```ts
|
|
239
|
+
* const deferredInit = createDeferredInit();
|
|
240
|
+
*
|
|
241
|
+
* // Later, after components are ready
|
|
242
|
+
* const components = await loadComponents();
|
|
243
|
+
* deferredInit((el, props) => {
|
|
244
|
+
* const Component = components[el.dataset.oxIsland!];
|
|
245
|
+
* // ...
|
|
246
|
+
* });
|
|
247
|
+
* ```
|
|
248
|
+
*/
|
|
249
|
+
function createDeferredInit(options) {
|
|
250
|
+
return (hydrate) => initIslands(hydrate, options);
|
|
251
|
+
}
|
|
252
|
+
/**
|
|
253
|
+
* Check if islands are supported in the current environment.
|
|
254
|
+
*/
|
|
255
|
+
function isIslandsSupported() {
|
|
256
|
+
return typeof window !== "undefined" && typeof document !== "undefined" && typeof IntersectionObserver !== "undefined" && typeof MutationObserver !== "undefined";
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
//#endregion
|
|
260
|
+
export { createDeferredInit, initIslands, isIslandsSupported };
|
|
261
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../src/runtime.ts"],"sourcesContent":["/**\n * Island Architecture Runtime\n *\n * Framework-agnostic Island controller using pure Vanilla JavaScript.\n * No framework dependencies - works with Vue, React, Svelte, or plain JS.\n */\n\nimport type {\n HydrateFunction,\n InitIslandsOptions,\n IslandConfig,\n IslandInstance,\n IslandController,\n LoadStrategy,\n} from \"./types\";\n\nconst defaultOptions: Required<Omit<InitIslandsOptions, \"onHydrateStart\" | \"onHydrateEnd\" | \"onHydrateError\">> & InitIslandsOptions = {\n rootMargin: \"200px\",\n threshold: 0,\n idleTimeout: 200,\n selector: \"[data-ox-island]\",\n};\n\n/**\n * Parse island configuration from element attributes.\n */\nfunction parseIslandConfig(element: HTMLElement): IslandConfig {\n const component = element.dataset.oxIsland || \"\";\n const load = (element.dataset.oxLoad as LoadStrategy) || \"eager\";\n const mediaQuery = element.dataset.oxMedia;\n\n let props: Record<string, unknown> = {};\n try {\n const propsJson = element.dataset.oxProps;\n if (propsJson) {\n props = JSON.parse(propsJson);\n }\n } catch (e) {\n console.warn(\"[ox-islands] Failed to parse props for\", element, e);\n }\n\n return {\n id: element.id || `island-${Math.random().toString(36).slice(2, 9)}`,\n component,\n load,\n mediaQuery,\n props,\n };\n}\n\n/**\n * Observe element visibility using IntersectionObserver.\n */\nfunction observeVisibility(\n element: HTMLElement,\n callback: () => void,\n options: { rootMargin: string; threshold: number },\n): () => void {\n const observer = new IntersectionObserver(\n (entries) => {\n if (entries[0].isIntersecting) {\n observer.disconnect();\n callback();\n }\n },\n {\n rootMargin: options.rootMargin,\n threshold: options.threshold,\n },\n );\n\n observer.observe(element);\n\n return () => observer.disconnect();\n}\n\n/**\n * Observe media query changes.\n */\nfunction observeMedia(query: string, callback: () => void): () => void {\n const mql = matchMedia(query);\n\n if (mql.matches) {\n callback();\n return () => {};\n }\n\n const handler = () => {\n if (mql.matches) {\n mql.removeEventListener(\"change\", handler);\n callback();\n }\n };\n\n mql.addEventListener(\"change\", handler);\n\n return () => mql.removeEventListener(\"change\", handler);\n}\n\n/**\n * Schedule callback for browser idle time.\n */\nfunction scheduleIdle(callback: () => void, timeout: number): () => void {\n if (\"requestIdleCallback\" in window) {\n const id = requestIdleCallback(callback, { timeout });\n return () => cancelIdleCallback(id);\n }\n\n // Fallback for Safari and older browsers\n const id = setTimeout(callback, timeout);\n return () => clearTimeout(id);\n}\n\n/**\n * Initialize islands with a hydration function.\n *\n * This is the main entry point for the island system.\n * Pass a hydrate function that knows how to mount your components.\n *\n * @example Vue\n * ```ts\n * import { initIslands } from '@ox-content/islands';\n * import { createApp, h } from 'vue';\n * import Counter from './Counter.vue';\n *\n * const components = { Counter };\n *\n * initIslands((el, props) => {\n * const name = el.dataset.oxIsland!;\n * const Component = components[name];\n * if (!Component) return;\n *\n * const app = createApp({ render: () => h(Component, props) });\n * app.mount(el);\n *\n * return () => app.unmount();\n * });\n * ```\n *\n * @example React\n * ```ts\n * import { initIslands } from '@ox-content/islands';\n * import { createRoot } from 'react-dom/client';\n * import Counter from './Counter';\n *\n * const components = { Counter };\n *\n * initIslands((el, props) => {\n * const name = el.dataset.oxIsland!;\n * const Component = components[name];\n * if (!Component) return;\n *\n * const root = createRoot(el);\n * root.render(<Component {...props} />);\n *\n * return () => root.unmount();\n * });\n * ```\n *\n * @example Vanilla JS\n * ```ts\n * import { initIslands } from '@ox-content/islands';\n *\n * initIslands((el, props) => {\n * const name = el.dataset.oxIsland!;\n *\n * if (name === 'Counter') {\n * let count = props.initial || 0;\n * const button = el.querySelector('button')!;\n * const handler = () => {\n * count++;\n * button.textContent = String(count);\n * };\n * button.addEventListener('click', handler);\n * return () => button.removeEventListener('click', handler);\n * }\n * });\n * ```\n */\nexport function initIslands(\n hydrate: HydrateFunction,\n options?: InitIslandsOptions,\n): IslandController {\n const opts = { ...defaultOptions, ...options };\n const instances: IslandInstance[] = [];\n const cleanups: (() => void)[] = [];\n\n /**\n * Hydrate a single island element.\n */\n function hydrateIsland(element: HTMLElement, config: IslandConfig): void {\n // Find existing instance\n const instance = instances.find((i) => i.element === element);\n if (instance?.hydrated) return;\n\n try {\n opts.onHydrateStart?.(element, config);\n\n // Mark as loading\n element.classList.add(\"ox-island-loading\");\n\n // Call the hydrate function\n const cleanup = hydrate(element, config.props);\n\n // Mark as hydrated\n element.dataset.oxHydrated = \"true\";\n element.classList.remove(\"ox-island-loading\");\n\n // Update instance\n if (instance) {\n instance.cleanup = cleanup || undefined;\n instance.hydrated = true;\n } else {\n instances.push({\n element,\n config,\n cleanup: cleanup || undefined,\n hydrated: true,\n });\n }\n\n opts.onHydrateEnd?.(element, config);\n } catch (error) {\n element.classList.remove(\"ox-island-loading\");\n element.classList.add(\"ox-island-error\");\n element.dataset.oxError = error instanceof Error ? error.message : String(error);\n\n opts.onHydrateError?.(element, config, error instanceof Error ? error : new Error(String(error)));\n }\n }\n\n /**\n * Schedule hydration based on load strategy.\n */\n function scheduleHydration(element: HTMLElement, config: IslandConfig): void {\n switch (config.load) {\n case \"eager\":\n hydrateIsland(element, config);\n break;\n\n case \"idle\": {\n const cancel = scheduleIdle(\n () => hydrateIsland(element, config),\n opts.idleTimeout,\n );\n cleanups.push(cancel);\n break;\n }\n\n case \"visible\": {\n const cancel = observeVisibility(\n element,\n () => hydrateIsland(element, config),\n { rootMargin: opts.rootMargin, threshold: opts.threshold },\n );\n cleanups.push(cancel);\n break;\n }\n\n case \"media\": {\n if (config.mediaQuery) {\n const cancel = observeMedia(config.mediaQuery, () =>\n hydrateIsland(element, config),\n );\n cleanups.push(cancel);\n } else {\n // No media query specified, fall back to eager\n hydrateIsland(element, config);\n }\n break;\n }\n\n default:\n hydrateIsland(element, config);\n }\n }\n\n // Find and process all island elements\n const elements = document.querySelectorAll<HTMLElement>(opts.selector);\n\n elements.forEach((element) => {\n const config = parseIslandConfig(element);\n\n // Track instance\n instances.push({\n element,\n config,\n hydrated: false,\n });\n\n // Schedule hydration\n scheduleHydration(element, config);\n });\n\n // Return controller\n return {\n instances,\n\n hydrate(element: HTMLElement): void {\n const config = parseIslandConfig(element);\n hydrateIsland(element, config);\n },\n\n destroy(): void {\n // Cancel pending hydrations\n cleanups.forEach((cleanup) => cleanup());\n cleanups.length = 0;\n\n // Cleanup hydrated instances\n instances.forEach((instance) => {\n if (instance.cleanup) {\n instance.cleanup();\n }\n });\n instances.length = 0;\n },\n };\n}\n\n/**\n * Create a deferred hydration wrapper.\n *\n * Returns a function that can be called to hydrate islands later.\n * Useful for frameworks that need to register components first.\n *\n * @example\n * ```ts\n * const deferredInit = createDeferredInit();\n *\n * // Later, after components are ready\n * const components = await loadComponents();\n * deferredInit((el, props) => {\n * const Component = components[el.dataset.oxIsland!];\n * // ...\n * });\n * ```\n */\nexport function createDeferredInit(\n options?: InitIslandsOptions,\n): (hydrate: HydrateFunction) => IslandController {\n return (hydrate: HydrateFunction) => initIslands(hydrate, options);\n}\n\n/**\n * Check if islands are supported in the current environment.\n */\nexport function isIslandsSupported(): boolean {\n return (\n typeof window !== \"undefined\" &&\n typeof document !== \"undefined\" &&\n typeof IntersectionObserver !== \"undefined\" &&\n typeof MutationObserver !== \"undefined\"\n );\n}\n"],"mappings":"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"}
|
package/package.json
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@ox-content/islands",
|
|
3
|
+
"version": "0.3.0-alpha.11",
|
|
4
|
+
"description": "Framework-agnostic Island Architecture for ox-content",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"import": "./dist/index.js",
|
|
11
|
+
"types": "./dist/index.d.ts"
|
|
12
|
+
},
|
|
13
|
+
"./runtime": {
|
|
14
|
+
"import": "./dist/runtime.js",
|
|
15
|
+
"types": "./dist/runtime.d.ts"
|
|
16
|
+
}
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"dist"
|
|
20
|
+
],
|
|
21
|
+
"devDependencies": {
|
|
22
|
+
"@types/node": "^22.0.0",
|
|
23
|
+
"@typescript/native-preview": "^7.0.0-dev.20250601",
|
|
24
|
+
"tsdown": "^0.12.0",
|
|
25
|
+
"typescript": "^5.7.0"
|
|
26
|
+
},
|
|
27
|
+
"keywords": [
|
|
28
|
+
"islands",
|
|
29
|
+
"island-architecture",
|
|
30
|
+
"partial-hydration",
|
|
31
|
+
"ox-content",
|
|
32
|
+
"framework-agnostic"
|
|
33
|
+
],
|
|
34
|
+
"license": "MIT",
|
|
35
|
+
"author": "ubugeeei",
|
|
36
|
+
"repository": {
|
|
37
|
+
"type": "git",
|
|
38
|
+
"url": "https://github.com/ubugeeei/ox-content.git",
|
|
39
|
+
"directory": "npm/ox-content-islands"
|
|
40
|
+
},
|
|
41
|
+
"publishConfig": {
|
|
42
|
+
"access": "public"
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "tsdown",
|
|
46
|
+
"dev": "tsdown --watch",
|
|
47
|
+
"typecheck": "tsgo --noEmit"
|
|
48
|
+
}
|
|
49
|
+
}
|