@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 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
+ [![npm version](https://img.shields.io/npm/v/core.svg)](https://www.npmjs.com/package/@shadow-js/core)
4
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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.