@craft-ng/core 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-ng/core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Reactive State Management for Angular - Type-safe, signal-based utilities for composable and reusable state management",
   "author": "Romain Geffrault",
   "license": "MIT",
@@ -38,4 +38,4 @@
   "dependencies": {
     "tslib": "^2.3.0"
   }
-}
+}

package/types/craft-ng-core.d.ts

@@ -6074,6 +6074,74 @@ type ReadonlySource$<T> = {
     subscribe: (callback: (value: T) => void) => ReturnType<EventEmitter<T>['subscribe']>;
     value: Signal<T | undefined>;
 };
+/**
+ * Creates an event emitter with automatic cleanup and signal-based value tracking.
+ *
+ * `source$` provides a lightweight event streaming solution that combines event emission,
+ * automatic subscription cleanup via `DestroyRef`, and signal-based reactive value tracking.
+ *
+ * @template T - The type of values emitted by the source
+ *
+ * @returns {Source$<T>} An object with the following methods and properties:
+ * - `emit(value: T)` - Emits a value to all subscribers and updates the internal signal
+ * - `subscribe(callback: (value: T) => void)` - Subscribes to emissions with automatic cleanup
+ * - `value: Signal<T | undefined>` - A read-only signal containing the last emitted value
+ * - `asReadonly()` - Returns a read-only version (only `subscribe` and `value`)
+ * - `preserveLastValue()` - Returns a variant that immediately emits the last value to new subscribers
+ *
+ * @example
+ * Basic usage with state coordination
+ * ```typescript
+ * import { source$, state, on$ } from '@craft-ng/core';
+ *
+ * @Component({
+ *   selector: 'app-counter',
+ *   template: `
+ *     <p>Count: {{ counter() }}</p>
+ *     <button (click)="counter.increment()">+1</button>
+ *     <button (click)="reset$.emit()">Reset</button>
+ *   `,
+ * })
+ * export class CounterComponent {
+ *   reset$ = source$<void>();
+ *
+ *   counter = state(0, ({ set, update }) => ({
+ *     increment: () => update((v) => v + 1),
+ *     reset: on$(this.reset$, () => set(0)),
+ *   }));
+ * }
+ * ```
+ *
+ *
+ * @example
+ * Late subscriber with preserved last value
+ * ```typescript
+ * const notifications$ = source$<string>().preserveLastValue();
+ *
+ * notifications$.emit('Server started');
+ * notifications$.emit('Database connected');
+ *
+ * // Late subscriber receives the last value immediately
+ * notifications$.subscribe((msg) => {
+ *   console.log(msg); // 'Database connected'
+ * });
+ * ```
+ *
+ * @example
+ * Read-only access pattern
+ * ```typescript
+ * class DataService {
+ *   private dataUpdated$ = source$<Data>();
+ *   readonly dataUpdated = this.dataUpdated$.asReadonly();
+ *
+ *   updateData(data: Data) {
+ *     this.dataUpdated$.emit(data);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://ng-craft.dev/utils/source$ | source$ documentation}
+ */
 declare function source$<T>(): Source$<T>;
 
 type InferSourceType<S> = S extends SignalSource<infer T> ? T : S extends Source$<infer U> ? U : S extends _Subscribable<infer V> ? V : never;
@@ -8164,5 +8232,215 @@ declare function reactiveWritableSignal<State>(initialValue: State, reactionBuil
     current: NoInfer<State>;
 }) => NoInfer<State>, options?: SyncOptions) => ReactionEntry<State, Params>) => Record<string, ReactionEntry<State, any>>): WritableSignal<State>;
 
-export { EXTERNALLY_PROVIDED, EmptyContext, GlobalPersisterHandlerService, STORE_CONFIG_TOKEN, SourceBrand, SourceBranded, addMany, addOne, afterRecomputation, asyncProcess, capitalize, computedIds, computedSource, computedTotal, contract, craft, craftAsyncProcesses, craftComputedStates, craftFactoryEntries, craftInject, craftInputs, craftMutations, craftQuery, craftQueryParam, craftQueryParams, craftSetAllQueriesParamsStandalone, craftSources, craftState, createMethodHandlers, insertLocalStoragePersister, insertPaginationPlaceholderData, insertReactOnMutation, isSource, linkedSource, localStoragePersister, map, mapOne, mutation, partialContext, query, queryParam, reactiveWritableSignal, removeAll, removeMany, removeOne, resourceById, serializeQueryParams, serializedQueryParamsObjectToString, setAll, setMany, setOne, signalSource, source$, sourceFromEvent, stackedSource, state, toSource, toggleMany, toggleOne, updateMany, updateOne, upsertMany, upsertOne };
-export type { AsyncProcessOutput, AsyncProcessRef, CloudProxy, CloudProxySource, ContextConstraints, ContextInput, CraftFactory, CraftFactoryEntries, CraftFactoryUtility, DeferredExtract, EntitiesUtilBrand, EqualParams, ExcludeCommonKeys, ExtractSignalPropsAndMethods, FilterMethodsBoundToSources, FilterPrivateFields, FilterSource, FlatRecord, HasChild$1 as HasChild, HasKeys, IdSelector, Identifier, InferInjectedType, IsAny, IsEmptyObject, IsNever, IsUnknown, MakeOptionalPropertiesRequired$1 as MakeOptionalPropertiesRequired, MergeObject$1 as MergeObject, MergeObjects$1 as MergeObjects, MergeTwoContexts, MutationOutput, MutationRef, Not, OmitStrict, PartialContext, Prettify, QueryOutput, QueryParamConfig, QueryParamNavigationOptions$1 as QueryParamNavigationOptions, QueryParamOutput, QueryParamsToState, QueryRef, ReadonlySource, ReadonlySource$, RemoveIndexSignature, ReplaceStoreConfigToken, ResourceByIdHandler, ResourceByIdLikeMutationRef, ResourceByIdLikeQueryRef, ResourceByIdRef, ResourceLikeMutationRef, ResourceLikeQueryRef, SignalSource, Source$, SourceFromEvent, SourceSetterMethods, SourceSubscribe, SpecificCraftQueryParamOutputs, SpecificCraftQueryParamsOutputs, StackSource, StateOutput, StoreConfigConstraints, StoreConfigToken, ToConnectableMethodFromInject, ToConnectableSourceFromInject, UnionToIntersection$1 as UnionToIntersection, UnionToTuple$1 as UnionToTuple, Update };
+type FromEventToSource$<T> = ReadonlySource$<T> & {
+    dispose: () => void;
+};
+/**
+ * Converts DOM events to a ReadonlySource$ stream with automatic cleanup on component destruction.
+ *
+ * This function bridges DOM events with ng-craft's source$ reactive system by:
+ * - Converting native DOM events to source emissions
+ * - Automatically removing event listeners on component destruction
+ * - Supporting optional event payload transformation
+ * - Providing manual disposal capability
+ * - Returning a readonly source with `subscribe` and `value` properties
+ *
+ * @remarks
+ * **Automatic Cleanup:**
+ * - Event listeners are automatically removed when the injection context is destroyed
+ * - Uses Angular's `DestroyRef` for lifecycle management
+ * - Manual cleanup available via `dispose()` method
+ * - Prevents memory leaks from dangling event listeners
+ *
+ * **Use Cases:**
+ * - **User interactions**: Click, input, scroll, keyboard events
+ * - **Window events**: Resize, scroll, focus, online/offline
+ * - **Document events**: Visibility changes, custom events
+ * - **Media events**: Video/audio play, pause, ended
+ * - **Form events**: Submit, change, input
+ * - **Custom events**: Application-specific DOM events
+ *
+ * **Event Transformation:**
+ * - Without `computedValue`: Emits the raw event object
+ * - With `computedValue`: Transforms event before emission
+ * - Useful for extracting specific event properties
+ * - Reduces payload size and improves type safety
+ *
+ * **Integration with Stores:**
+ * - Use the readonly source in queries/mutations via `on$()`
+ * - Trigger async operations on DOM events
+ * - Coordinate multiple components via event sources
+ *
+ * **Injection Context:**
+ * - Must be called within Angular injection context
+ * - Typically called in component constructor or class fields
+ * - Uses `assertInInjectionContext()` for safety
+ *
+ * @template T - The type of the event object
+ * @template ComputedValue - The type after optional transformation
+ *
+ * @param target - The DOM element or event target to listen to.
+ *   Can be any EventTarget (HTMLElement, Window, Document, etc.)
+ *
+ * @param eventName - The name of the event to listen for.
+ *   Standard DOM event names: 'click', 'input', 'scroll', etc.
+ *
+ * @param options - Optional configuration:
+ *   - `event`: Event listener options (capture, passive, once, etc.)
+ *   - `computedValue`: Function to transform event before emission
+ *
+ * @returns A readonly source that emits on DOM events with:
+ *   - `subscribe()`: Subscribe to event emissions
+ *   - `value`: Signal containing the last emitted value
+ *   - `dispose()`: Method to manually remove event listener
+ *   - Automatic cleanup on component destruction
+ *
+ * @example
+ * Basic click event source
+ * ```ts
+ * @Component({
+ *   selector: 'app-clicker',
+ *   template: '<button #btn>Click me</button>',
+ * })
+ * export class ClickerComponent {
+ *   @ViewChild('btn', { read: ElementRef }) button!: ElementRef<HTMLButtonElement>;
+ *
+ *   click$ = fromEventToSource$<MouseEvent>(
+ *     this.button.nativeElement,
+ *     'click'
+ *   );
+ *
+ *   counter = state(0, ({ update }) => ({
+ *     increment: on$(this.click$, () => update((v) => v + 1)),
+ *   }));
+ * }
+ * ```
+ *
+ * @example
+ * Window scroll event with transformation
+ * ```ts
+ * @Component({
+ *   selector: 'app-infinite-scroll',
+ *   template: '...',
+ * })
+ * export class InfiniteScrollComponent {
+ *   scroll$ = fromEventToSource$(window, 'scroll', {
+ *     computedValue: () => ({
+ *       scrollY: window.scrollY,
+ *       scrollHeight: document.documentElement.scrollHeight,
+ *       clientHeight: window.innerHeight,
+ *     }),
+ *     event: { passive: true },
+ *   });
+ *
+ *   // Access scroll position via signal
+ *   scrollPosition = this.scroll$.value;
+ *
+ *   // Subscribe to scroll events
+ *   ngOnInit() {
+ *     this.scroll$.subscribe((data) => {
+ *       const nearBottom = data.scrollY + data.clientHeight >= data.scrollHeight - 100;
+ *       if (nearBottom) {
+ *         // Load more data
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Form input event for real-time search
+ * ```ts
+ * @Component({
+ *   selector: 'app-search',
+ *   template: '<input #searchInput type="text" placeholder="Search..." />',
+ * })
+ * export class SearchComponent {
+ *   @ViewChild('searchInput', { read: ElementRef }) input!: ElementRef<HTMLInputElement>;
+ *
+ *   input$ = fromEventToSource$(this.input.nativeElement, 'input', {
+ *     computedValue: (event: Event) => {
+ *       const target = event.target as HTMLInputElement;
+ *       return target.value;
+ *     },
+ *   });
+ *
+ *   // Current input value as signal
+ *   searchTerm = this.input$.value;
+ *
+ *   // React to input changes
+ *   searchResults = state([], ({ set }) => ({
+ *     search: on$(this.input$, async (term) => {
+ *       if (term.length < 3) {
+ *         set([]);
+ *         return;
+ *       }
+ *       const results = await fetchResults(term);
+ *       set(results);
+ *     }),
+ *   }));
+ * }
+ * ```
+ *
+ * @example
+ * Window resize event
+ * ```ts
+ * @Component({
+ *   selector: 'app-responsive',
+ *   template: '...',
+ * })
+ * export class ResponsiveComponent {
+ *   resize$ = fromEventToSource$(window, 'resize', {
+ *     computedValue: () => ({
+ *       width: window.innerWidth,
+ *       height: window.innerHeight,
+ *     }),
+ *   });
+ *
+ *   dimensions = this.resize$.value;
+ * }
+ * ```
+ *
+ * @example
+ * Manual disposal for dynamic elements
+ * ```ts
+ * @Component({
+ *   selector: 'app-dynamic',
+ *   template: '...',
+ * })
+ * export class DynamicComponent {
+ *   private click$?: FromEventToSource$<MouseEvent>;
+ *
+ *   attachListener(element: HTMLElement) {
+ *     // Remove previous listener if exists
+ *     this.click$?.dispose();
+ *
+ *     // Attach to new element
+ *     this.click$ = fromEventToSource$<MouseEvent>(element, 'click');
+ *   }
+ *
+ *   detachListener() {
+ *     // Manually remove listener before component destruction
+ *     this.click$?.dispose();
+ *     this.click$ = undefined;
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://ng-craft.dev/utils/from-event-to-source$ | fromEventToSource$ documentation}
+ */
+declare function fromEventToSource$<T>(target: EventTarget, eventName: string, options?: {
+    event?: boolean | AddEventListenerOptions;
+    computedValue?: never;
+}): FromEventToSource$<T>;
+declare function fromEventToSource$<T, ComputedValue>(target: EventTarget, eventName: string, options?: {
+    event?: boolean | AddEventListenerOptions;
+    computedValue: (event: T) => ComputedValue;
+}): FromEventToSource$<ComputedValue>;
+
+declare function on$<State, SourceType>(_source: {
+    subscribe: EventEmitter<SourceType>['subscribe'];
+}, callback: (source: SourceType) => State): SourceBranded;
+
+export { EXTERNALLY_PROVIDED, EmptyContext, GlobalPersisterHandlerService, STORE_CONFIG_TOKEN, SourceBrand, SourceBranded, addMany, addOne, afterRecomputation, asyncProcess, capitalize, computedIds, computedSource, computedTotal, contract, craft, craftAsyncProcesses, craftComputedStates, craftFactoryEntries, craftInject, craftInputs, craftMutations, craftQuery, craftQueryParam, craftQueryParams, craftSetAllQueriesParamsStandalone, craftSources, craftState, createMethodHandlers, fromEventToSource$, insertLocalStoragePersister, insertPaginationPlaceholderData, insertReactOnMutation, isSource, linkedSource, localStoragePersister, map, mapOne, mutation, on$, partialContext, query, queryParam, reactiveWritableSignal, removeAll, removeMany, removeOne, resourceById, serializeQueryParams, serializedQueryParamsObjectToString, setAll, setMany, setOne, signalSource, source$, sourceFromEvent, stackedSource, state, toSource, toggleMany, toggleOne, updateMany, updateOne, upsertMany, upsertOne };
+export type { AsyncProcessOutput, AsyncProcessRef, CloudProxy, CloudProxySource, ContextConstraints, ContextInput, CraftFactory, CraftFactoryEntries, CraftFactoryUtility, DeferredExtract, EntitiesUtilBrand, EqualParams, ExcludeCommonKeys, ExtractSignalPropsAndMethods, FilterMethodsBoundToSources, FilterPrivateFields, FilterSource, FlatRecord, FromEventToSource$, HasChild$1 as HasChild, HasKeys, IdSelector, Identifier, InferInjectedType, IsAny, IsEmptyObject, IsNever, IsUnknown, MakeOptionalPropertiesRequired$1 as MakeOptionalPropertiesRequired, MergeObject$1 as MergeObject, MergeObjects$1 as MergeObjects, MergeTwoContexts, MutationOutput, MutationRef, Not, OmitStrict, PartialContext, Prettify, QueryOutput, QueryParamConfig, QueryParamNavigationOptions$1 as QueryParamNavigationOptions, QueryParamOutput, QueryParamsToState, QueryRef, ReadonlySource, ReadonlySource$, RemoveIndexSignature, ReplaceStoreConfigToken, ResourceByIdHandler, ResourceByIdLikeMutationRef, ResourceByIdLikeQueryRef, ResourceByIdRef, ResourceLikeMutationRef, ResourceLikeQueryRef, SignalSource, Source$, SourceFromEvent, SourceSetterMethods, SourceSubscribe, SpecificCraftQueryParamOutputs, SpecificCraftQueryParamsOutputs, StackSource, StateOutput, StoreConfigConstraints, StoreConfigToken, ToConnectableMethodFromInject, ToConnectableSourceFromInject, UnionToIntersection$1 as UnionToIntersection, UnionToTuple$1 as UnionToTuple, Update };