smol.js 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# smol.js
+
+> Minimal Web Component library with zero dependencies
+
+## Features
+
+- ✅ **Zero dependencies** - Only ~3KB gzipped
+- ✅ **Standards-based** - Uses native Web Components
+- ✅ **TypeScript-first** - Full type safety
+- ✅ **Reactivity** - Fine-grained signals and state
+- ✅ **SSR ready** - Server-side rendering support
+- ✅ **Framework-agnostic** - Works with anything
+
+## Installation
+
+```bash
+npm install smol.js
+```
+
+## Quick Start
+
+### Basic Component
+
+```typescript
+import { smolComponent, html, smolSignal } from 'smol.js';
+
+smolComponent({
+  tag: 'my-counter',
+  
+  // Scoped CSS
+  styles: css`
+    button { padding: 0.5rem; }
+  `,
+  
+  // Component Logic
+  connected() {
+    this.count = smolSignal(0);
+  },
+  
+  // Template with automated reactivity
+  template(ctx) {
+    const count = this.count.value;
+    
+    return html`
+      <button @click=${() => this.count.value++}>
+        Count: ${count}
+      </button>
+    `;
+  }
+});
+```
+
+## Core Concepts
+
+### Components (`smolComponent`)
+
+Creates a standard native Web Component.
+
+```typescript
+smolComponent({
+  tag: 'user-card',
+  
+  // Define attributes to watch for changes
+  observedAttributes: ['username'],
+  
+  // Lifecycle methods
+  connected() { console.log('Mounted'); },
+  disconnected() { console.log('Unmounted'); },
+  
+  // React to attribute changes
+  attributeChanged(name, oldVal, newVal) {
+    // ...
+  },
+  
+  // Render template
+  template(ctx) {
+    return html`<div>Hello ${ctx.element.getAttribute('username')}</div>`;
+  }
+});
+```
+
+### Reactivity (`smolSignal`, `computed`, `effect`)
+
+Fine-grained reactivity system.
+
+```typescript
+// Create a signal
+const count = smolSignal(0);
+
+// Create a computed value (updates automatically)
+const double = computed(() => count.value * 2);
+
+// Run a side effect when signals change
+effect(() => {
+  console.log(`Count is ${count.value}, double is ${double.value}`);
+});
+
+count.value++; // Logs: "Count is 1, double is 2"
+```
+
+### Services (`smolService`)
+
+Singleton services for global state and logic.
+
+```typescript
+// Define service
+export const authService = smolService({
+  name: 'auth',
+  factory: () => {
+    const user = smolSignal(null);
+    return {
+      user,
+      login: (name) => user.value = name
+    };
+  }
+});
+
+// Use in component
+import { authService } from './auth.service';
+
+smolComponent({
+  // ...
+  template(ctx) {
+    const user = authService.user.value;
+    return html`
+      <div>User: ${user}</div>
+      <button @click=${() => authService.login('Alice')}>Login</button>
+    `;
+  }
+});
+```
+
+## Templates
+
+### External Templates (`.html?smol`)
+
+You can separate your HTML and CSS into files using the Vite plugin.
+
+**vite.config.ts**:
+```typescript
+import { smolTemplatePlugin } from 'smol.js/vite';
+export default {
+  plugins: [smolTemplatePlugin()]
+};
+```
+
+**my-cmp.ts**:
+```typescript
+import template from './my-cmp.html?smol';
+import styles from './my-cmp.css?inline';
+
+smolComponent({
+  tag: 'my-cmp',
+  styles,
+  template(ctx) {
+    // Variables used in HTML must be available in context or locals
+    return template(html, this); 
+  }
+});
+```
+
+**my-cmp.html**:
+```html
+<div>
+  <!-- 'count' refers to this.count from the component instance -->
+  Count: ${count.value}
+</div>
+```
+
+## Hydration
+
+For Client-Side Hydration of SSR content:
+
+**main.ts**:
+```typescript
+// Initializes hydration for all components
+import 'smol.js/src/hydrate-client'; 
+```
+
+Or manually:
+```typescript
+import { hydrateAll } from 'smol.js';
+
+document.addEventListener('DOMContentLoaded', () => {
+  hydrateAll();
+});
+```
+
+## API Reference
+
+### `html`
+Tagged template literal for defining HTML structure.
+
+### `css`
+Tagged template literal for defining styles.
+
+### `smolState(obj)`
+Creates a deeply reactive object proxy.
+
+### `inject(service)`
+Retrieves a service instance (mostly used internally or for testing).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Clear all services (useful for testing)
+ */
+export declare function clearServices(): void;
+
+/**
+ * Create a computed signal that derives its value from other signals
+ *
+ * @example
+ * ```ts
+ * const count = smolSignal(0);
+ * const doubled = computed(() => count.value * 2);
+ * ```
+ */
+export declare function computed<T>(fn: () => T): Signal<T>;
+
+/**
+ * Tagged template literal for CSS styles
+ *
+ * @example
+ * ```ts
+ * const styles = css`
+ *   :host {
+ *     display: block;
+ *   }
+ * `;
+ * ```
+ */
+export declare function css(strings: TemplateStringsArray, ...values: any[]): string;
+
+/**
+ * Create an effect that runs when signals change
+ *
+ * @example
+ * ```ts
+ * const count = smolSignal(0);
+ *
+ * effect(() => {
+ *   console.log('Count is:', count.value);
+ * });
+ * ```
+ */
+export declare function effect(fn: () => void): () => void;
+
+/**
+ * Tagged template literal for HTML templates
+ *
+ * @example
+ * ```ts
+ * const template = html`<div>${value}</div>`;
+ * ```
+ */
+export declare function html(strings: TemplateStringsArray, ...values: any[]): TemplateResult;
+
+/**
+ * Hydrate all smol components on the page
+ *
+ * Call this after the page loads to hydrate all server-rendered components.
+ */
+export declare function hydrateAll(): void;
+
+/**
+ * Hydrate a server-rendered component
+ *
+ * This attaches event listeners and sets up reactivity
+ * without re-rendering the component.
+ */
+export declare function hydrateComponent(element: SmolElement): void;
+
+/**
+ * Inject a service by name
+ *
+ * @example
+ * ```ts
+ * const api = inject<ApiService>('ApiService');
+ * ```
+ */
+export declare function inject<T = any>(name: string): T;
+
+/**
+ * Check if a value is a TemplateResult
+ */
+export declare function isTemplateResult(value: any): value is TemplateResult;
+
+/**
+ * Render a template to a DOM node
+ * This handles event listeners, attributes, and text content
+ * IMPORTANT: Preserves existing <style> elements in shadow DOM
+ */
+export declare function render(template: TemplateResult, container: HTMLElement | ShadowRoot): void;
+
+/**
+ * Render a component to an HTML string with Declarative Shadow DOM
+ * This is used for server-side rendering (SSR)
+ *
+ * @example
+ * ```ts
+ * const html = renderComponentToString(MyCounter, { initialCount: 0 });
+ * // Returns: <my-counter><template shadowrootmode="open">...</template></my-counter>
+ * ```
+ */
+export declare function renderComponentToString(ComponentClass: typeof HTMLElement, attributes?: Record<string, string>): string;
+
+/**
+ * Render a template result to an HTML string
+ * Used for SSR or initial rendering
+ */
+export declare function renderToString(template: TemplateResult): string;
+
+export declare interface Signal<T> {
+    /** Get the current value */
+    get value(): T;
+    /** Set a new value */
+    set value(newValue: T);
+    /** Subscribe to value changes */
+    subscribe(fn: (value: T) => void): () => void;
+    /** Internal subscribers */
+    _subscribers: Set<(value: T) => void>;
+}
+
+/**
+ * Create a custom Web Component
+ *
+ * This function creates a custom element class and automatically registers it.
+ * It handles Shadow DOM, lifecycle callbacks, and template rendering.
+ *
+ * @example
+ * ```ts
+ * // my-button.html
+ * // <button><slot>Button</slot></button>
+ *
+ * // my-button.css
+ * // button { padding: 0.5rem 1rem; }
+ *
+ * import { smolComponent, html } from 'smol.js';
+ * import styles from './my-button.css?inline';
+ * import template from './my-button.html?smol';
+ *
+ * smolComponent({
+ *   tag: 'my-button',
+ *   observedAttributes: ['variant'],
+ *
+ *   styles,
+ *
+ *   template(ctx) {
+ *     return template(html);
+ *   }
+ * });
+ * ```
+ */
+export declare function smolComponent(config: SmolComponentConfig): typeof HTMLElement;
+
+export declare interface SmolComponentConfig {
+    /** The custom element tag name (must contain a hyphen) */
+    tag: string;
+    /** Shadow DOM mode */
+    mode?: 'open' | 'closed';
+    /** List of attributes to observe for changes */
+    observedAttributes?: string[];
+    /** Component styles (use css`` tagged template) */
+    styles?: string;
+    /** Template function that returns HTML */
+    template?: (this: SmolElement, ctx: SmolContext) => string | TemplateResult;
+    /** Lifecycle: element connected to DOM */
+    connected?: (this: SmolElement) => void;
+    /** Lifecycle: element disconnected from DOM */
+    disconnected?: (this: SmolElement) => void;
+    /** Lifecycle: observed attribute changed */
+    attributeChanged?: (this: SmolElement, name: string, oldValue: string | null, newValue: string | null) => void;
+}
+
+export declare interface SmolContext {
+    /** Emit a custom event */
+    emit: (name: string, detail?: any) => void;
+    /** Trigger a re-render */
+    render: () => void;
+    /** Access to element properties */
+    [key: string]: any;
+}
+
+export declare interface SmolElement extends HTMLElement {
+    /** Trigger a re-render of the component */
+    render(): void;
+    /** Emit a custom event from the component */
+    emit(name: string, detail?: any): void;
+    /** Access to the shadow root */
+    readonly shadowRoot: ShadowRoot;
+}
+
+/**
+ * Create a service (singleton by default)
+ *
+ * Services provide shared functionality across components.
+ *
+ * @example
+ * ```ts
+ * const ApiService = smolService({
+ *   name: 'ApiService',
+ *   factory: () => ({
+ *     async fetchData(url: string) {
+ *       const res = await fetch(url);
+ *       return res.json();
+ *     }
+ *   })
+ * });
+ *
+ * // Use in component:
+ * const api = inject('ApiService');
+ * ```
+ */
+export declare function smolService<T>(config: SmolServiceConfig<T>): T;
+
+export declare interface SmolServiceConfig<T> {
+    /** Unique service name */
+    name: string;
+    /** Factory function to create the service */
+    factory: () => T;
+    /** Whether this is a singleton (default: true) */
+    singleton?: boolean;
+}
+
+/**
+ * Create a reactive signal
+ *
+ * Signals are lightweight reactive primitives that notify subscribers when their value changes.
+ *
+ * @example
+ * ```ts
+ * const count = smolSignal(0);
+ *
+ * // Subscribe to changes
+ * count.subscribe((value) => console.log('Count:', value));
+ *
+ * // Update value
+ * count.value = 1; // logs "Count: 1"
+ * ```
+ */
+export declare function smolSignal<T>(initialValue: T): Signal<T>;
+
+/**
+ * Create a reactive state object using Proxy
+ *
+ * Unlike signals, state objects are reactive objects that track changes to any property.
+ *
+ * @example
+ * ```ts
+ * const state = smolState({
+ *   count: 0,
+ *   name: 'John'
+ * });
+ *
+ * state.subscribe(() => {
+ *   console.log('State changed:', state.data);
+ * });
+ *
+ * state.data.count++; // triggers subscribers
+ * ```
+ */
+export declare function smolState<T extends object>(initialValue: T): State<T>;
+
+/**
+ * Server-side render utility
+ * Renders multiple components to HTML
+ */
+export declare function ssr(components: Array<{
+    component: typeof HTMLElement;
+    attributes?: Record<string, string>;
+}>): string;
+
+export declare interface State<T extends object> {
+    /** The proxied state object */
+    data: T;
+    /** Subscribe to any state change */
+    subscribe(fn: () => void): () => void;
+    /** Internal subscribers */
+    _subscribers: Set<() => void>;
+}
+
+export declare interface TemplateResult {
+    strings: TemplateStringsArray;
+    values: any[];
+    _isTemplateResult: true;
+}
+
+export { }