@mohasinac/appkit 2.1.3 → 2.3.0

package/src/contracts/repository.ts

@@ -1,87 +0,0 @@
-// ─── Repository Interfaces ────────────────────────────────────────────────────
-// Segregated per ISP: features that only read never depend on IWriteRepository.
-
-/** Field comparison operators supported by Sieve-style query strings. */
-export type WhereOp =
-  | "=="
-  | "!="
-  | "<"
-  | "<="
-  | ">"
-  | ">="
-  | "array-contains"
-  | "in"
-  | "not-in"
-  | "array-contains-any";
-
-/**
- * Provider-agnostic query descriptor.
- * `filters` uses Sieve syntax: "field==value,field2>value2"
- * DB adapters translate this into native query predicates.
- */
-export interface SieveQuery {
-  /** Sieve filter string, e.g. "status==published,price>100" */
-  filters?: string;
-  /** Field name to sort by */
-  sort?: string;
-  /** Sort direction (default: "asc") */
-  order?: "asc" | "desc";
-  /** 1-based page number (default: 1) */
-  page?: number;
-  /** Items per page (default: 20) */
-  perPage?: number;
-}
-
-/** Paginated result envelope returned by IReadRepository.findAll() */
-export interface PagedResult<T> {
-  data: T[];
-  total: number;
-  page: number;
-  perPage: number;
-  totalPages: number;
-}
-
-// ─── Read contract ─────────────────────────────────────────────────────────
-export interface IReadRepository<T> {
-  findById(id: string): Promise<T | null>;
-  findAll(query?: SieveQuery): Promise<PagedResult<T>>;
-  findWhere(field: keyof T, op: WhereOp, value: unknown): Promise<T[]>;
-}
-
-// ─── Write contract ────────────────────────────────────────────────────────
-export interface IWriteRepository<T> {
-  create(data: Omit<T, "id" | "createdAt" | "updatedAt">): Promise<T>;
-  update(id: string, data: Partial<T>): Promise<T>;
-  delete(id: string): Promise<void>;
-  batchCreate(
-    items: Array<Omit<T, "id" | "createdAt" | "updatedAt">>,
-  ): Promise<T[]>;
-  batchDelete(ids: string[]): Promise<void>;
-}
-
-/** Full CRUD repository — combines read + write. */
-export interface IRepository<T>
-  extends IReadRepository<T>, IWriteRepository<T> {}
-
-/**
- * Repository with real-time subscription support (e.g. Firestore RTDB).
- * Returns an unsubscribe function from both subscribe methods.
- */
-export interface IRealtimeRepository<T> extends IRepository<T> {
-  subscribe(id: string, cb: (data: T | null) => void): () => void;
-  subscribeWhere(
-    field: keyof T,
-    value: unknown,
-    cb: (items: T[]) => void,
-  ): () => void;
-}
-
-/**
- * Database provider — creates IRepository<T> instances on demand.
- * Registered once in providers.config.ts; feature packages call
- * `getProviders().db.getRepository<T>(collection)` so they never
- * import a concrete adapter (FirebaseRepository, PrismaRepository, …).
- */
-export interface IDbProvider {
-  getRepository<T>(collection: string): IRepository<T>;
-}

package/src/contracts/search.ts

@@ -1,49 +0,0 @@
-// ─── Search Shared Types ──────────────────────────────────────────────────────
-
-export interface SearchOptions {
-  page?: number;
-  perPage?: number;
-  filters?: string;
-  facets?: string[];
-  sortBy?: string;
-  /** Attributes to include in the result (default: all) */
-  attributesToRetrieve?: string[];
-  /** Attributes to highlight in results */
-  attributesToHighlight?: string[];
-}
-
-export interface SearchHit<T> {
-  id: string;
-  data: T;
-  score?: number;
-  highlights?: Record<string, string>;
-}
-
-export interface SearchResult<T> {
-  hits: SearchHit<T>[];
-  total: number;
-  page: number;
-  perPage: number;
-  totalPages: number;
-  processingTimeMs?: number;
-  facets?: Record<string, Record<string, number>>;
-}
-
-export interface SuggestOptions {
-  limit?: number;
-  filters?: string;
-}
-
-// ─── Search Interface ─────────────────────────────────────────────────────────
-
-/**
- * Full-text search adapter contract.
- * Implemented by concrete provider packages (for example, Typesense or Meilisearch).
- */
-export interface ISearchProvider<T = Record<string, unknown>> {
-  index(id: string, data: T): Promise<void>;
-  indexBatch(items: Array<{ id: string; data: T }>): Promise<void>;
-  remove(id: string): Promise<void>;
-  search(query: string, options?: SearchOptions): Promise<SearchResult<T>>;
-  suggest(query: string, options?: SuggestOptions): Promise<string[]>;
-}

package/src/contracts/shipping.ts

@@ -1,77 +0,0 @@
-// ─── Shipping Shared Types ────────────────────────────────────────────────────
-
-export interface ShippingAddress {
-  name: string;
-  phone: string;
-  addressLine1: string;
-  addressLine2?: string;
-  city: string;
-  state: string;
-  pincode: string;
-  country: string;
-}
-
-export interface CreateShipmentInput {
-  orderId: string;
-  dimensions: {
-    weight: number; // kg
-    length: number; // cm
-    width: number; // cm
-    height: number; // cm
-  };
-  pickup: ShippingAddress;
-  delivery: ShippingAddress;
-  codAmount?: number;
-  isCod?: boolean;
-}
-
-export interface Shipment {
-  id: string;
-  trackingId: string;
-  orderId: string;
-  status: string;
-  courier?: string;
-  estimatedDelivery?: string; // ISO-8601
-  createdAt: string; // ISO-8601
-}
-
-export interface TrackingEvent {
-  status: string;
-  location: string;
-  timestamp: string; // ISO-8601
-  description?: string;
-}
-
-export interface TrackingInfo {
-  trackingId: string;
-  currentStatus: string;
-  estimatedDelivery?: string; // ISO-8601
-  events: TrackingEvent[];
-}
-
-export interface ServiceabilityResult {
-  isServiceable: boolean;
-  couriers: Array<{
-    name: string;
-    estimatedDays: number;
-    rate: number;
-  }>;
-}
-
-// ─── Shipping Interface ───────────────────────────────────────────────────────
-
-/**
- * Shipping carrier adapter contract.
- * Implemented by @mohasinac/shipping-shiprocket, @mohasinac/shipping-shippo,
- * @mohasinac/shipping-easypost.
- */
-export interface IShippingProvider {
-  createShipment(data: CreateShipmentInput): Promise<Shipment>;
-  trackShipment(trackingId: string): Promise<TrackingInfo>;
-  cancelShipment(shipmentId: string): Promise<void>;
-  checkServiceability(
-    pincode: string,
-    weight: number,
-  ): Promise<ServiceabilityResult>;
-  generateLabel(shipmentId: string): Promise<ArrayBuffer>;
-}

package/src/contracts/storage.ts

@@ -1,37 +0,0 @@
-// ─── Storage Shared Types ─────────────────────────────────────────────────────
-
-export interface UploadOptions {
-  contentType?: string;
-  cacheControl?: string;
-  /** Make the file publicly accessible (default: true) */
-  isPublic?: boolean;
-  metadata?: Record<string, string>;
-}
-
-export interface StorageFile {
-  path: string;
-  url: string;
-  contentType: string;
-  size: number;
-  updatedAt: string; // ISO-8601
-}
-
-// ─── Storage Interface ────────────────────────────────────────────────────────
-
-/**
- * File storage adapter contract.
- * Implemented by @mohasinac/storage-firebase, @mohasinac/storage-s3,
- * @mohasinac/storage-cloudinary, @mohasinac/storage-uploadthing.
- */
-export interface IStorageProvider {
-  upload(
-    file: Buffer,
-    path: string,
-    options?: UploadOptions,
-  ): Promise<StorageFile>;
-  delete(path: string): Promise<void>;
-  getPublicUrl(path: string): string;
-  getSignedUrl(path: string, expiresInSeconds?: number): Promise<string>;
-  copy(from: string, to: string): Promise<StorageFile>;
-  list(prefix: string): Promise<StorageFile[]>;
-}

package/src/contracts/style.ts

@@ -1,25 +0,0 @@
-// ─── Style Adapter Interface ──────────────────────────────────────────────────
-
-/**
- * CSS framework adapter contract.
- * UI components call cn()/token() through this adapter, making them
- * CSS-framework-agnostic.
- *
- * Implemented by:
- *   @mohasinac/css-tailwind  — twMerge + clsx
- *   @mohasinac/css-vanilla   — plain string join
- *   @mohasinac/css-emotion   — Emotion cx()
- *   @mohasinac/css-modules   — CSS Modules
- */
-export interface IStyleAdapter {
-  /**
-   * Merges and deduplicates class names.
-   * Equivalent to twMerge(clsx(...)) in Tailwind projects.
-   */
-  cn(...classes: Array<string | undefined | null | false>): string;
-  /**
-   * Resolves a design token name to a CSS custom property reference.
-   * e.g. token("color-primary") → "var(--appkit-color-primary)"
-   */
-  token(name: string): string;
-}

package/src/contracts/table.ts

@@ -1,148 +0,0 @@
-/**
- * Table, pagination and sticky-header configuration types.
- *
- * Every table/list view in every feat-* package accepts these config objects.
- * Apps can spread-merge over the exported defaults to override only what they need:
- *
- * @example
- * // App-level base config (one file, reused everywhere)
- * import { DEFAULT_TABLE_CONFIG, DEFAULT_PAGINATION_CONFIG } from "./";
- *
- * export const myTableConfig: TableConfig = {
- *   ...DEFAULT_TABLE_CONFIG,
- *   pageSize: 10,
- *   showViewToggle: true,
- * };
- *
- * export const myPaginationConfig: PaginationConfig = {
- *   ...DEFAULT_PAGINATION_CONFIG,
- *   perPage: 10,
- *   showPageSizeSelector: true,
- *   pageSizeOptions: [10, 25, 50],
- * };
- *
- * // In a component
- * <DataTable tableConfig={myTableConfig} paginationConfig={myPaginationConfig} ... />
- *
- * // In a hook
- * const { products } = useProducts(params, { paginationConfig: myPaginationConfig });
- */
-
-// ─── Pagination ────────────────────────────────────────────────────────────────
-
-/**
- * Composable pagination configuration.
- * All fields are optional so apps can spread-merge over the defaults.
- */
-export interface PaginationConfig {
-  /** Items per page sent to the API. Default: 20 */
-  perPage?: number;
-  /** Hard cap on perPage (for page-size selector). Default: 100 */
-  maxPerPage?: number;
-  /** Show a page-size selector UI element. Default: false */
-  showPageSizeSelector?: boolean;
-  /** Options for the page-size selector. Default: [10, 20, 50, 100] */
-  pageSizeOptions?: number[];
-  /** Show first / last page buttons. Default: true */
-  showFirstLast?: boolean;
-  /** Show previous / next buttons. Default: true */
-  showPrevNext?: boolean;
-  /** Max visible page number buttons before ellipsis. Default: 7 */
-  maxVisible?: number;
-  /** Size variant for pagination button sizing. Default: "md" */
-  size?: "sm" | "md" | "lg";
-}
-
-export const DEFAULT_PAGINATION_CONFIG: Required<PaginationConfig> = {
-  perPage: 20,
-  maxPerPage: 100,
-  showPageSizeSelector: false,
-  pageSizeOptions: [10, 20, 50, 100],
-  showFirstLast: true,
-  showPrevNext: true,
-  maxVisible: 7,
-  size: "md",
-};
-
-// ─── Sticky header ─────────────────────────────────────────────────────────────
-
-/**
- * Sticky header configuration for data tables.
- * When `enabled` is true the thead is pinned while the tbody scrolls.
- */
-export interface StickyConfig {
-  /** Pin the header while the body scrolls. Default: false */
-  enabled?: boolean;
-  /** Tailwind `top-*` class applied to the sticky thead. Default: "top-0" */
-  topOffset?: string;
-  /** Max height of the scrollable container. Default: "600px" */
-  maxHeight?: string;
-  /** z-index of the sticky header. Default: 10 */
-  zIndex?: number;
-}
-
-export const DEFAULT_STICKY_CONFIG: Required<StickyConfig> = {
-  enabled: false,
-  topOffset: "top-0",
-  maxHeight: "600px",
-  zIndex: 10,
-};
-
-// ─── Table ─────────────────────────────────────────────────────────────────────
-
-/** View mode options for DataTable. */
-export type TableViewMode = "table" | "grid" | "list";
-
-/**
- * Composable table configuration.
- * Pass a Partial<TableConfig> to any DataTable / admin-list hook; values are
- * deep-merged with DEFAULT_TABLE_CONFIG at the use site.
- */
-export interface TableConfig {
-  /** Items shown per page (internal pagination). Default: 20 */
-  pageSize?: number;
-  /** Sticky header behaviour. Default: disabled */
-  sticky?: StickyConfig;
-  /** Alternate row background colour. Default: false */
-  striped?: boolean;
-  /** Enable row checkbox selection. Default: false */
-  selectable?: boolean;
-  /** Show view-mode toggle (table / grid / list). Default: false */
-  showViewToggle?: boolean;
-  /** Default view mode. Default: "table" */
-  defaultViewMode?: TableViewMode;
-  /** Pagination widget configuration. */
-  pagination?: PaginationConfig;
-}
-
-export const DEFAULT_TABLE_CONFIG: {
-  pageSize: number;
-  sticky: Required<StickyConfig>;
-  striped: boolean;
-  selectable: boolean;
-  showViewToggle: boolean;
-  defaultViewMode: TableViewMode;
-  pagination: Required<PaginationConfig>;
-} = {
-  pageSize: DEFAULT_PAGINATION_CONFIG.perPage,
-  sticky: DEFAULT_STICKY_CONFIG,
-  striped: false,
-  selectable: false,
-  showViewToggle: false,
-  defaultViewMode: "table",
-  pagination: DEFAULT_PAGINATION_CONFIG,
-};
-
-/**
- * Utility: merge a Partial<TableConfig> over the defaults.
- * Performs a shallow merge at the top level and deep merge for nested objects.
- */
-export function mergeTableConfig(override?: Partial<TableConfig>): typeof DEFAULT_TABLE_CONFIG {
-  if (!override) return DEFAULT_TABLE_CONFIG;
-  return {
-    ...DEFAULT_TABLE_CONFIG,
-    ...override,
-    sticky: { ...DEFAULT_STICKY_CONFIG, ...override.sticky },
-    pagination: { ...DEFAULT_PAGINATION_CONFIG, ...override.pagination },
-  };
-}

package/src/core/CacheManager.ts

@@ -1,85 +0,0 @@
-/**
- * CacheManager Class — @mohasinac/core
- *
- * Simple TTL-based in-memory cache with FIFO eviction.
- * Pure utility — no framework or app-specific imports.
- */
-
-export interface CacheOptions {
-  ttl?: number;
-}
-
-export interface CacheEntry<T> {
-  value: T;
-  timestamp: number;
-  ttl?: number;
-}
-
-export class CacheManager {
-  private static instance: CacheManager;
-  private readonly cache: Map<string, CacheEntry<unknown>> = new Map();
-  private readonly maxSize: number;
-
-  private constructor(maxSize: number = 100) {
-    this.maxSize = maxSize;
-  }
-
-  public static getInstance(maxSize?: number): CacheManager {
-    if (!CacheManager.instance) {
-      CacheManager.instance = new CacheManager(maxSize);
-    }
-    return CacheManager.instance;
-  }
-
-  public set<T>(key: string, value: T, options?: CacheOptions): void {
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      const firstKey = this.cache.keys().next().value as string | undefined;
-      if (firstKey !== undefined) this.cache.delete(firstKey);
-    }
-    this.cache.set(key, { value, timestamp: Date.now(), ttl: options?.ttl });
-  }
-
-  public get<T>(key: string): T | null {
-    const entry = this.cache.get(key);
-    if (!entry) return null;
-    if (entry.ttl && Date.now() - entry.timestamp > entry.ttl) {
-      this.cache.delete(key);
-      return null;
-    }
-    return entry.value as T;
-  }
-
-  public has(key: string): boolean {
-    return this.get(key) !== null;
-  }
-
-  public delete(key: string): boolean {
-    return this.cache.delete(key);
-  }
-
-  public clear(): void {
-    this.cache.clear();
-  }
-
-  public size(): number {
-    return this.cache.size;
-  }
-
-  public keys(): string[] {
-    return Array.from(this.cache.keys());
-  }
-
-  public cleanExpired(): number {
-    let cleaned = 0;
-    for (const [key, entry] of this.cache.entries()) {
-      if (entry.ttl && Date.now() - entry.timestamp > entry.ttl) {
-        this.cache.delete(key);
-        cleaned++;
-      }
-    }
-    return cleaned;
-  }
-}
-
-/** Default shared CacheManager singleton */
-export const cacheManager = CacheManager.getInstance();

package/src/core/EventBus.ts

@@ -1,89 +0,0 @@
-/**
- * EventBus Class — @mohasinac/core
- *
- * Singleton pub/sub event bus for decoupled communication.
- * Pure utility — no framework or app-specific imports.
- */
-
-import { Logger } from "./Logger";
-
-const logger = Logger.getInstance();
-
-type EventCallback = (...args: unknown[]) => void;
-
-export interface EventSubscription {
-  unsubscribe: () => void;
-}
-
-export class EventBus {
-  private static instance: EventBus;
-  private readonly events: Map<string, EventCallback[]> = new Map();
-
-  private constructor() {}
-
-  public static getInstance(): EventBus {
-    if (!EventBus.instance) {
-      EventBus.instance = new EventBus();
-    }
-    return EventBus.instance;
-  }
-
-  public on(event: string, callback: EventCallback): EventSubscription {
-    if (!this.events.has(event)) {
-      this.events.set(event, []);
-    }
-    this.events.get(event)!.push(callback);
-    return { unsubscribe: () => this.off(event, callback) };
-  }
-
-  public once(event: string, callback: EventCallback): EventSubscription {
-    const wrapped = (...args: unknown[]) => {
-      callback(...args);
-      this.off(event, wrapped);
-    };
-    return this.on(event, wrapped);
-  }
-
-  public off(event: string, callback: EventCallback): void {
-    const callbacks = this.events.get(event);
-    if (!callbacks) return;
-    const idx = callbacks.indexOf(callback);
-    if (idx > -1) callbacks.splice(idx, 1);
-    if (callbacks.length === 0) this.events.delete(event);
-  }
-
-  public emit(event: string, ...args: unknown[]): void {
-    const callbacks = this.events.get(event);
-    if (!callbacks) return;
-    callbacks.forEach((cb) => {
-      try {
-        cb(...args);
-      } catch (error) {
-        logger.error(`EventBus: error in handler for "${event}"`, { error });
-      }
-    });
-  }
-
-  public removeAllListeners(event?: string): void {
-    if (event) {
-      this.events.delete(event);
-    } else {
-      this.events.clear();
-    }
-  }
-
-  public listenerCount(event: string): number {
-    return this.events.get(event)?.length ?? 0;
-  }
-
-  public eventNames(): string[] {
-    return Array.from(this.events.keys());
-  }
-
-  public hasListeners(event: string): boolean {
-    return this.listenerCount(event) > 0;
-  }
-}
-
-/** Shared singleton instance */
-export const eventBus = EventBus.getInstance();