@masterteam/components 0.0.83 → 0.0.85

package/types/masterteam-components.d.ts

@@ -424,7 +424,68 @@ interface QueryResult<T> {
     error: Signal<string | null>;
 }
 /**
- * Base facade with smart query selector factory
+ * @deprecated Use direct `select()` + `computed()` pattern instead for better performance.
+ *
+ * **Problem with BaseFacade:**
+ * - All computed signals depend on the full state, causing unnecessary recomputations
+ * - Bypasses NGXS selector memoization
+ * - Uses `as any` casting, losing type safety
+ *
+ * **New Pattern - Use slice-based selectors:**
+ *
+ * ```typescript
+ * // In your State class - add slice selectors:
+ * @Selector()
+ * static getLoadingActive(state: MyStateModel): string[] {
+ *   return state.loadingActive;
+ * }
+ *
+ * @Selector()
+ * static getErrors(state: MyStateModel): Record<string, string | null> {
+ *   return state.errors;
+ * }
+ *
+ * // In your Facade - don't extend BaseFacade:
+ * @Injectable({ providedIn: 'root' })
+ * export class MyFacade {
+ *   private readonly store = inject(Store);
+ *
+ *   // Data selectors - memoized by NGXS
+ *   readonly items = select(MyState.getItems);
+ *
+ *   // Loading/Error slices - memoized by NGXS
+ *   private readonly loadingActive = select(MyState.getLoadingActive);
+ *   private readonly errors = select(MyState.getErrors);
+ *
+ *   // Loading signals - computed from slice (minimal reactivity)
+ *   readonly isLoadingItems = computed(() =>
+ *     this.loadingActive().includes(MyActionKey.GetItems)
+ *   );
+ *
+ *   // Error signals - computed from slice (minimal reactivity)
+ *   readonly itemsError = computed(() =>
+ *     this.errors()[MyActionKey.GetItems] ?? null
+ *   );
+ *
+ *   // Dispatchers
+ *   loadItems() {
+ *     return this.store.dispatch(new GetItems());
+ *   }
+ * }
+ * ```
+ *
+ * **Template Usage:**
+ * ```html
+ * @if (facade.isLoadingItems()) {
+ *   <loading-spinner />
+ * } @else if (facade.itemsError(); as error) {
+ *   <error-alert>{{ error }}</error-alert>
+ * } @else {
+ *   @for (item of facade.items(); track item.id) {
+ *     <item-card [item]="item" />
+ *   }
+ * }
+ * ```
  */
 declare abstract class BaseFacade<TState, TLoadingName extends string> {
     /**
@@ -482,7 +543,15 @@ interface CrudLoadConfig<T, TState, TData = T[]> {
     key: string;
     request$: Observable<Response<TData>>;
     stateProperty?: (state: TState) => T[];
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for complex state updates.
+     * CRUD methods should only be used for simple array operations with `stateProperty`.
+     */
     updateState?: (state: TState, data: TData) => Partial<TState>;
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for data transformation.
+     * CRUD methods should only be used for simple array operations.
+     */
     transform?: (data: TData) => TData;
     onError?: (error: any, state: TState) => Partial<TState> | void;
     errorMessage?: string;
@@ -491,7 +560,15 @@ interface CrudCreateConfig<T, TState> {
     key: string;
     request$: Observable<Response<T>>;
     stateProperty: (state: TState) => T[];
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for complex state updates.
+     * CRUD methods should only be used for simple array operations with `stateProperty`.
+     */
     updateState?: (state: TState, items: T[]) => Partial<TState>;
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for data transformation.
+     * CRUD methods should only be used for simple array operations.
+     */
     transform?: (data: T) => T;
     onError?: (error: any, state: TState) => Partial<TState> | void;
     errorMessage?: string;
@@ -502,7 +579,15 @@ interface CrudUpdateConfig<T, TState> {
     uniqueKey: keyof T;
     id: string | number;
     stateProperty: (state: TState) => T[];
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for complex state updates.
+     * CRUD methods should only be used for simple array operations with `stateProperty`.
+     */
     updateState?: (state: TState, items: T[]) => Partial<TState>;
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for data transformation.
+     * CRUD methods should only be used for simple array operations.
+     */
     transform?: (data: T) => T;
     onError?: (error: any, state: TState) => Partial<TState> | void;
     errorMessage?: string;
@@ -513,6 +598,10 @@ interface CrudDeleteConfig<T, TState> {
     uniqueKey: keyof T;
     id: string | number;
     stateProperty: (state: TState) => T[];
+    /**
+     * @deprecated Use `handleApiRequest` with `onSuccess` for complex state updates.
+     * CRUD methods should only be used for simple array operations with `stateProperty`.
+     */
     updateState?: (state: TState, items: T[]) => Partial<TState>;
     onError?: (error: any, state: TState) => Partial<TState> | void;
     errorMessage?: string;
@@ -529,7 +618,19 @@ declare abstract class CrudStateBase<T, TState extends LoadingStateShape<TLoad>,
      */
     private getDefaultUpdateState;
     /**
-     * Load data (single item or array) with config object
+     * @deprecated Use `handleApiRequest` directly with `onSuccess` callback.
+     * The `load()` method provides no significant benefit over `handleApiRequest`.
+     *
+     * @example
+     * // Instead of this.load(), use:
+     * return handleApiRequest({
+     *   ctx,
+     *   key: ActionKey.GetItems,
+     *   request$: req$,
+     *   onSuccess: (response) => ({
+     *     items: response.data ?? [],
+     *   }),
+     * });
      */
     protected load<TData = T[]>(ctx: StateContext<TState>, config: CrudLoadConfig<T, TState, TData>): Observable<Response<TData>>;
     /**
@@ -618,5 +719,15 @@ interface RequestContextConfig {
  */
 declare const REQUEST_CONTEXT: HttpContextToken<RequestContextConfig>;
 
-export { BaseFacade, BaseFieldConfig, CheckboxFieldConfig, ColorPickerFieldConfig, CrudStateBase, DateFieldConfig, EditorFieldConfig, IconFieldConfig, MultiSelectFieldConfig, NumberFieldConfig, PickListFieldConfig, REQUEST_CONTEXT, RadioButtonFieldConfig, RadioCardsFieldConfig, SelectFieldConfig, SliderFieldConfig, SpacerFieldConfig, TextFieldConfig, TextareaFieldConfig, ToggleFieldConfig, UploadFileFieldConfig, UserSearchFieldConfig, ValidatorConfig, changeBackgroundColor, changePrimaryColor, changeTextColor, createCustomValidator, createEntityAdapter, endLoading, generateTailwindPalette, handleApiRequest, isInvalid, provideMTComponents, provideMTConfirmation, provideMTMessages, setLoadingError, startLoading, wrapValidatorWithMessage };
+/**
+ * Color utility functions for brand display.
+ */
+/**
+ * Converts a hex color to a light shade (equivalent to primary-100 in Tailwind).
+ * This creates a color with ~10% opacity or a very light tint by mixing with white.
+ */
+declare function getLightColor(hexColor: string): string;
+declare function getContrastColor(bgColor: string): string;
+
+export { BaseFacade, BaseFieldConfig, CheckboxFieldConfig, ColorPickerFieldConfig, CrudStateBase, DateFieldConfig, EditorFieldConfig, IconFieldConfig, MultiSelectFieldConfig, NumberFieldConfig, PickListFieldConfig, REQUEST_CONTEXT, RadioButtonFieldConfig, RadioCardsFieldConfig, SelectFieldConfig, SliderFieldConfig, SpacerFieldConfig, TextFieldConfig, TextareaFieldConfig, ToggleFieldConfig, UploadFileFieldConfig, UserSearchFieldConfig, ValidatorConfig, changeBackgroundColor, changePrimaryColor, changeTextColor, createCustomValidator, createEntityAdapter, endLoading, generateTailwindPalette, getContrastColor, getLightColor, handleApiRequest, isInvalid, provideMTComponents, provideMTConfirmation, provideMTMessages, setLoadingError, startLoading, wrapValidatorWithMessage };
 export type { ApiRequestConfig, BaseFieldConstructorConfig, CrudCreateConfig, CrudDeleteConfig, CrudLoadConfig, CrudUpdateConfig, DynamicFieldConfig, DynamicFormConfig, EntityAdapter, FieldRelationAction, FieldRelationConfig, FieldState, FieldType, LayoutConfig, LoadingStateShape, MTThemeOptions, PaletteShade, QueryResult, RequestContextConfig, Response, ResponsiveColSpan, SectionConfig, ValidatorType };