@shadow-js/core 0.1.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/LICENSE +21 -0
- package/README.md +386 -0
- package/dist/chunk-6Y3CCWOY.js +887 -0
- package/dist/chunk-6Y3CCWOY.js.map +1 -0
- package/dist/chunk-B5FTYDUG.js +3 -0
- package/dist/chunk-B5FTYDUG.js.map +1 -0
- package/dist/index.cjs +2000 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +609 -0
- package/dist/index.d.ts +609 -0
- package/dist/index.js +1094 -0
- package/dist/index.js.map +1 -0
- package/dist/jsx-Bugil6CJ.d.cts +151 -0
- package/dist/jsx-Bugil6CJ.d.ts +151 -0
- package/dist/jsx-dev-runtime.cjs +742 -0
- package/dist/jsx-dev-runtime.cjs.map +1 -0
- package/dist/jsx-dev-runtime.d.cts +2 -0
- package/dist/jsx-dev-runtime.d.ts +2 -0
- package/dist/jsx-dev-runtime.js +4 -0
- package/dist/jsx-dev-runtime.js.map +1 -0
- package/dist/jsx-runtime.cjs +742 -0
- package/dist/jsx-runtime.cjs.map +1 -0
- package/dist/jsx-runtime.d.cts +36 -0
- package/dist/jsx-runtime.d.ts +36 -0
- package/dist/jsx-runtime.js +4 -0
- package/dist/jsx-runtime.js.map +1 -0
- package/package.json +66 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Jehaad AL-Johani
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
# ShadowJS Core Framework
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@shadow-js/core)
|
|
4
|
+
[](https://www.typescriptlang.org/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
|
|
7
|
+
The core ShadowJS framework providing fine-grained reactivity, JSX runtime, and essential UI components.
|
|
8
|
+
|
|
9
|
+
## ✨ Features
|
|
10
|
+
|
|
11
|
+
- **🎯 Fine-grained Reactivity**: Only re-render what actually changes
|
|
12
|
+
- **⚡ Fast Runtime**: Minimal overhead with optimized DOM updates
|
|
13
|
+
- **🎨 JSX-First**: Familiar React-like syntax with powerful extensions
|
|
14
|
+
- **📦 Tree-Shakable**: Only bundle what you use
|
|
15
|
+
- **🔧 TypeScript Ready**: Full type safety and IntelliSense support
|
|
16
|
+
- **🎭 Component System**: Built-in components for common UI patterns
|
|
17
|
+
|
|
18
|
+
## 📦 Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @shadow-js/core
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
For development with hot reload and JSX compilation:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm install @shadow-js/core @shadow-js/vite
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 🚀 Quick Start
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
import { useStore, Show, For } from "@shadow-js/core";
|
|
34
|
+
|
|
35
|
+
function Counter() {
|
|
36
|
+
const [count, setCount] = useStore(0);
|
|
37
|
+
const [items, setItems] = useStore(["Shadow", "JS", "Reactivity"]);
|
|
38
|
+
|
|
39
|
+
return (
|
|
40
|
+
<div>
|
|
41
|
+
<h2>Counter: {() => count()}</h2>
|
|
42
|
+
<button onClick={() => setCount(count() + 1)}>Increment</button>
|
|
43
|
+
|
|
44
|
+
<Show when={() => count() > 5} fallback={<p>Keep clicking!</p>}>
|
|
45
|
+
<p>🎉 You reached {() => count()}!</p>
|
|
46
|
+
</Show>
|
|
47
|
+
|
|
48
|
+
<ul>
|
|
49
|
+
<For each={() => items()}>{(item) => <li>{() => item}</li>}</For>
|
|
50
|
+
</ul>
|
|
51
|
+
</div>
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## 🎯 Core Concepts
|
|
57
|
+
|
|
58
|
+
### Reactive Stores
|
|
59
|
+
|
|
60
|
+
Create reactive state that automatically updates dependent computations:
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
import { useStore } from "@shadow-js/core";
|
|
64
|
+
|
|
65
|
+
function App() {
|
|
66
|
+
const [count, setCount] = useStore(0);
|
|
67
|
+
const doubled = () => count() * 2; // Reactive computation
|
|
68
|
+
|
|
69
|
+
return (
|
|
70
|
+
<div>
|
|
71
|
+
<p>Count: {() => count()}</p>
|
|
72
|
+
<p>Doubled: {() => doubled()}</p> {/* Updates automatically */}
|
|
73
|
+
<button onClick={() => setCount(count() + 1)}>+</button>
|
|
74
|
+
</div>
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Effects and Lifecycle
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
import { useEffect, onMount, onCleanup } from "@shadow-js/core";
|
|
83
|
+
|
|
84
|
+
function Timer() {
|
|
85
|
+
const [time, setTime] = useStore(new Date());
|
|
86
|
+
|
|
87
|
+
onMount(() => {
|
|
88
|
+
console.log("Component mounted");
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
useEffect(() => {
|
|
92
|
+
const interval = setInterval(() => {
|
|
93
|
+
setTime(new Date());
|
|
94
|
+
}, 1000);
|
|
95
|
+
|
|
96
|
+
// Cleanup on unmount or dependency change
|
|
97
|
+
return () => clearInterval(interval);
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
onCleanup(() => {
|
|
101
|
+
console.log("Component unmounting");
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
return <div>Current time: {() => time().toLocaleTimeString()}</div>;
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Conditional Rendering
|
|
109
|
+
|
|
110
|
+
```tsx
|
|
111
|
+
import { Show } from "@shadow-js/core";
|
|
112
|
+
|
|
113
|
+
function UserStatus({ user }) {
|
|
114
|
+
return (
|
|
115
|
+
<Show when={() => user()} fallback={<div>Please log in</div>}>
|
|
116
|
+
<div>Welcome back, {() => user().name}!</div>
|
|
117
|
+
</Show>
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Lists with For
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
import { For } from "@shadow-js/core";
|
|
126
|
+
|
|
127
|
+
function TodoList({ todos }) {
|
|
128
|
+
return (
|
|
129
|
+
<ul>
|
|
130
|
+
<For each={() => todos()}>
|
|
131
|
+
{(todo, index) => (
|
|
132
|
+
<li>
|
|
133
|
+
{() => index() + 1}. {() => todo.title}
|
|
134
|
+
</li>
|
|
135
|
+
)}
|
|
136
|
+
</For>
|
|
137
|
+
</ul>
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Switch/Case Pattern
|
|
143
|
+
|
|
144
|
+
```tsx
|
|
145
|
+
import { Switch, Match } from "@shadow-js/core";
|
|
146
|
+
|
|
147
|
+
function StatusDisplay({ status }) {
|
|
148
|
+
return (
|
|
149
|
+
<Switch fallback={<div>Unknown status</div>}>
|
|
150
|
+
<Match when={() => status() === "loading"}>
|
|
151
|
+
<div>Loading...</div>
|
|
152
|
+
</Match>
|
|
153
|
+
<Match when={() => status() === "success"}>
|
|
154
|
+
<div>Success!</div>
|
|
155
|
+
</Match>
|
|
156
|
+
<Match when={() => status() === "error"}>
|
|
157
|
+
<div>Error occurred</div>
|
|
158
|
+
</Match>
|
|
159
|
+
</Switch>
|
|
160
|
+
);
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Async Operations with Suspense
|
|
165
|
+
|
|
166
|
+
```tsx
|
|
167
|
+
import { Suspense, lazy } from "@shadow-js/core";
|
|
168
|
+
|
|
169
|
+
// Lazy load components
|
|
170
|
+
const LazyComponent = lazy(() => import("./HeavyComponent"));
|
|
171
|
+
|
|
172
|
+
function App() {
|
|
173
|
+
return (
|
|
174
|
+
<Suspense fallback={<div>Loading component...</div>}>
|
|
175
|
+
<LazyComponent />
|
|
176
|
+
</Suspense>
|
|
177
|
+
);
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## 📚 API Reference
|
|
182
|
+
|
|
183
|
+
### Reactivity Hooks
|
|
184
|
+
|
|
185
|
+
| Hook | Description |
|
|
186
|
+
| --------------------------- | ----------------------------------------- |
|
|
187
|
+
| `useStore<T>(initialValue)` | Create a reactive store |
|
|
188
|
+
| `useEffect(fn, deps?)` | Run side effects when dependencies change |
|
|
189
|
+
| `useMemo<T>(fn, deps?)` | Memoize expensive computations |
|
|
190
|
+
| `useId()` | Generate unique IDs |
|
|
191
|
+
| `onMount(fn)` | Run code when component mounts |
|
|
192
|
+
| `onCleanup(fn)` | Run cleanup code when component unmounts |
|
|
193
|
+
|
|
194
|
+
### Control Flow Components
|
|
195
|
+
|
|
196
|
+
| Component | Description |
|
|
197
|
+
| ----------------- | ------------------------------------------ |
|
|
198
|
+
| `<Show>` | Conditional rendering with fallback |
|
|
199
|
+
| `<For>` | Render lists with automatic key management |
|
|
200
|
+
| `<Switch>` | Multiple conditional rendering |
|
|
201
|
+
| `<Match>` | Case condition for Switch |
|
|
202
|
+
| `<Suspense>` | Handle async operations |
|
|
203
|
+
| `<ErrorBoundary>` | Catch and handle errors |
|
|
204
|
+
|
|
205
|
+
### Utilities
|
|
206
|
+
|
|
207
|
+
| Utility | Description |
|
|
208
|
+
| ------------------------------ | ----------------------------------------- |
|
|
209
|
+
| `createContext<T>()` | Create a context for dependency injection |
|
|
210
|
+
| `useContext<T>(context)` | Consume context values |
|
|
211
|
+
| `lazy<T>(importFn)` | Lazy load components |
|
|
212
|
+
| `render(component, container)` | Render component to DOM |
|
|
213
|
+
| `Fragment` | Group elements without wrapper |
|
|
214
|
+
|
|
215
|
+
## 🔧 Advanced Usage
|
|
216
|
+
|
|
217
|
+
### Custom Hooks
|
|
218
|
+
|
|
219
|
+
```tsx
|
|
220
|
+
import { useStore, useEffect } from "@shadow-js/core";
|
|
221
|
+
|
|
222
|
+
function useLocalStorage<T>(key: string, initialValue: T) {
|
|
223
|
+
const [storedValue, setStoredValue] = useStore<T>(() => {
|
|
224
|
+
try {
|
|
225
|
+
const item = localStorage.getItem(key);
|
|
226
|
+
return item ? JSON.parse(item) : initialValue;
|
|
227
|
+
} catch (error) {
|
|
228
|
+
return initialValue;
|
|
229
|
+
}
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
useEffect(() => {
|
|
233
|
+
try {
|
|
234
|
+
localStorage.setItem(key, JSON.stringify(storedValue()));
|
|
235
|
+
} catch (error) {
|
|
236
|
+
console.warn(`Error saving to localStorage:`, error);
|
|
237
|
+
}
|
|
238
|
+
});
|
|
239
|
+
|
|
240
|
+
return [storedValue, setStoredValue] as const;
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Context and Global State
|
|
245
|
+
|
|
246
|
+
```tsx
|
|
247
|
+
import { createContext, useContext } from "@shadow-js/core";
|
|
248
|
+
|
|
249
|
+
const ThemeContext = createContext();
|
|
250
|
+
|
|
251
|
+
function ThemeProvider({ children }) {
|
|
252
|
+
const [theme, setTheme] = useStore<"light" | "dark">("light");
|
|
253
|
+
|
|
254
|
+
const toggleTheme = () => {
|
|
255
|
+
setTheme(theme() === "light" ? "dark" : "light");
|
|
256
|
+
};
|
|
257
|
+
|
|
258
|
+
return (
|
|
259
|
+
<ThemeContext.Provider value={{ theme, toggleTheme }}>
|
|
260
|
+
{children}
|
|
261
|
+
</ThemeContext.Provider>
|
|
262
|
+
);
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
function useTheme() {
|
|
266
|
+
const context = useContext(ThemeContext);
|
|
267
|
+
if (!context) {
|
|
268
|
+
throw new Error("useTheme must be used within ThemeProvider");
|
|
269
|
+
}
|
|
270
|
+
return context;
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Error Boundaries
|
|
275
|
+
|
|
276
|
+
```tsx
|
|
277
|
+
import { ErrorBoundary } from "@shadow-js/core";
|
|
278
|
+
|
|
279
|
+
function App() {
|
|
280
|
+
return (
|
|
281
|
+
<ErrorBoundary fallback={(error) => <div>Error: {error.message}</div>}>
|
|
282
|
+
<ComponentThatMightError />
|
|
283
|
+
</ErrorBoundary>
|
|
284
|
+
);
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
## 🔌 Integration
|
|
289
|
+
|
|
290
|
+
### Vite Plugin
|
|
291
|
+
|
|
292
|
+
For the best development experience, use the ShadowJS Vite plugin:
|
|
293
|
+
|
|
294
|
+
**vite.config.ts**
|
|
295
|
+
|
|
296
|
+
```typescript
|
|
297
|
+
import { defineConfig } from "vite";
|
|
298
|
+
import shadow from "@shadow-js/vite";
|
|
299
|
+
|
|
300
|
+
export default defineConfig({
|
|
301
|
+
plugins: [shadow()],
|
|
302
|
+
});
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
### Manual JSX Setup
|
|
306
|
+
|
|
307
|
+
If you prefer manual setup, configure your bundler to use ShadowJS JSX runtime:
|
|
308
|
+
|
|
309
|
+
```json
|
|
310
|
+
{
|
|
311
|
+
"compilerOptions": {
|
|
312
|
+
"jsx": "react-jsx",
|
|
313
|
+
"jsxImportSource": "@shadow-js/core"
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
## 🎨 Styling
|
|
319
|
+
|
|
320
|
+
ShadowJS works with any CSS solution:
|
|
321
|
+
|
|
322
|
+
```tsx
|
|
323
|
+
// Inline styles (reactive)
|
|
324
|
+
<div style={() => ({ color: theme() === "dark" ? "white" : "black" })}>
|
|
325
|
+
Dynamic styling
|
|
326
|
+
</div>
|
|
327
|
+
|
|
328
|
+
// CSS Classes
|
|
329
|
+
<div className="my-component">
|
|
330
|
+
Static styling
|
|
331
|
+
</div>
|
|
332
|
+
|
|
333
|
+
// CSS Modules
|
|
334
|
+
import styles from "./Component.module.css";
|
|
335
|
+
<div className={styles.container}>CSS Modules</div>
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## 🏗️ Architecture
|
|
339
|
+
|
|
340
|
+
ShadowJS is built with performance and developer experience in mind:
|
|
341
|
+
|
|
342
|
+
### Fine-grained Reactivity System
|
|
343
|
+
|
|
344
|
+
- **Automatic dependency tracking**: No manual dependency arrays
|
|
345
|
+
- **Efficient updates**: Only affected components re-render
|
|
346
|
+
- **Memory management**: Automatic cleanup of unused subscriptions
|
|
347
|
+
|
|
348
|
+
### Optimized Runtime
|
|
349
|
+
|
|
350
|
+
- **Minimal bundle size**: Core runtime is < 9KB gzipped
|
|
351
|
+
- **Fast reconciliation**: Optimized DOM diffing algorithm
|
|
352
|
+
- **Memory efficient**: Smart memory management and cleanup
|
|
353
|
+
|
|
354
|
+
### Developer Experience
|
|
355
|
+
|
|
356
|
+
- **TypeScript first**: Full type safety and IntelliSense
|
|
357
|
+
- **Great error messages**: Clear error reporting and debugging
|
|
358
|
+
- **Hot reload friendly**: Optimized for development workflows
|
|
359
|
+
|
|
360
|
+
## 📚 Examples
|
|
361
|
+
|
|
362
|
+
Check out the [examples documentation](../../documentation/examples.md) for comprehensive code examples covering:
|
|
363
|
+
|
|
364
|
+
- Basic patterns and best practices
|
|
365
|
+
- Advanced reactive patterns
|
|
366
|
+
- Real-world application examples
|
|
367
|
+
- Integration patterns
|
|
368
|
+
|
|
369
|
+
## 🤝 Contributing
|
|
370
|
+
|
|
371
|
+
We welcome contributions! See the [Contributing Guide](../../CONTRIBUTING.md) for details.
|
|
372
|
+
|
|
373
|
+
## 📄 License
|
|
374
|
+
|
|
375
|
+
MIT License - see [LICENSE](../../LICENSE) for details.
|
|
376
|
+
|
|
377
|
+
## 📞 Support
|
|
378
|
+
|
|
379
|
+
- **Documentation**: [ShadowJS Docs](../../README.md)
|
|
380
|
+
- **Examples**: [Code Examples](../../documentation/examples.md)
|
|
381
|
+
- **Issues**: [GitHub Issues](https://github.com/shadowjs-dev/shadow/issues)
|
|
382
|
+
- **Discussions**: [GitHub Discussions](https://github.com/shadowjs-dev/shadow/discussions)
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
Built by Jehaad AL-Johani for fine-grained reactivity.
|