@zero-studio/library 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+/*!
+ * ZERO Technology Library (ZTL) v1.0.0
+ * TypeScript Definitions
+ * MIT License — https://zero-tech.dev
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ZTLTheme    = 'dark' | 'light';
+export type ZTLLang     = 'en' | 'ar';
+export type ZTLToastPos = 'br' | 'bl' | 'tr' | 'tl' | 'tc';
+export type ZTLToastType = 'success' | 'danger' | 'warning' | 'info';
+export type ZTLModalSize = 'sm' | 'lg' | 'xl' | 'full' | '';
+export type ZTLBtnSize   = 'xs' | 'sm' | 'lg' | 'xl';
+export type ZTLAvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type ZTLStatus     = 'online' | 'offline' | 'busy' | 'away';
+export type ZTLAlertType  = 'success' | 'danger' | 'warning' | 'info';
+export type ZTLProgressColor = 'success' | 'purple' | 'warning' | 'info' | 'danger';
+export type ZTLDirection = 'ltr' | 'rtl';
+
+export interface ZTLConfig {
+  /** UI theme. Default: 'dark' */
+  theme?: ZTLTheme;
+  /** Brand accent color (CSS color). Default: '#00f5a0' */
+  accent?: string;
+  /** Enable RTL layout. Auto-set if lang='ar'. Default: false */
+  rtl?: boolean;
+  /** Primary language. Default: 'en' */
+  lang?: ZTLLang;
+  /** Toast position. Default: 'br' */
+  toastPosition?: ZTLToastPos;
+  /** Toast auto-dismiss duration in ms. Default: 4000 */
+  toastDuration?: number;
+  /** Auto-initialize [data-ztl-*] elements. Default: true */
+  autoInit?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// i18n
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ZTLTranslations {
+  close:         string;
+  confirm:       string;
+  cancel:        string;
+  ok:            string;
+  copy:          string;
+  copied:        string;
+  loading:       string;
+  noData:        string;
+  error:         string;
+  success:       string;
+  warning:       string;
+  info:          string;
+  required:      string;
+  minLength:     (n: number) => string;
+  maxLength:     (n: number) => string;
+  invalid:       string;
+  search:        string;
+  prev:          string;
+  next:          string;
+  showing:       (from: number, to: number, total: number) => string;
+  deleteConfirm: string;
+  uploadDrop:    string;
+  uploadLimit:   (mb: number) => string;
+}
+
+export declare const i18n: Record<ZTLLang, ZTLTranslations>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TOAST
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ToastOptions {
+  /** Auto-dismiss duration in ms. Default: 4000 */
+  duration?: number;
+  /** Custom icon (emoji / HTML) */
+  icon?: string;
+  /** Show close button. Default: true */
+  closable?: boolean;
+}
+
+export declare class ToastManager {
+  constructor(position?: ZTLToastPos, lang?: ZTLLang);
+  show(message: string, type?: ZTLToastType, options?: ToastOptions): HTMLElement;
+  success(message: string, options?: ToastOptions): HTMLElement;
+  danger(message: string, options?: ToastOptions): HTMLElement;
+  warning(message: string, options?: ToastOptions): HTMLElement;
+  info(message: string, options?: ToastOptions): HTMLElement;
+  clear(): void;
+  destroy(): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MODAL
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ModalOptions {
+  title?:        string;
+  body?:         string;
+  size?:         ZTLModalSize;
+  closable?:     boolean;
+  onConfirm?:    () => void;
+  onCancel?:     () => void;
+  confirmLabel?: string;
+  cancelLabel?:  string;
+  lang?:         ZTLLang;
+}
+
+export declare class Modal {
+  constructor(options?: ModalOptions);
+  open(): this;
+  close(): this;
+  destroy(): void;
+  setBody(html: string): this;
+  setTitle(text: string): this;
+  static confirm(message: string, options?: Omit<ModalOptions, 'body'>): Promise<boolean>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TABS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TabsOptions {
+  onChange?: (index: number, prev: number) => void;
+}
+
+export declare class Tabs {
+  constructor(container: HTMLElement | string, options?: TabsOptions);
+  activate(index: number): void;
+  getActive(): number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DROPDOWN
+// ─────────────────────────────────────────────────────────────────────────────
+
+export declare class Dropdown {
+  constructor(trigger: HTMLElement | string, menu: HTMLElement | string);
+  open(): void;
+  close(): void;
+  toggle(): void;
+  isOpen(): boolean;
+  destroy(): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PROGRESS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ProgressBarOptions {
+  value?: number;
+  min?:   number;
+  max?:   number;
+  animate?: boolean;
+}
+
+export declare class ProgressBar {
+  constructor(element: HTMLElement | string, options?: ProgressBarOptions);
+  set(value: number): this;
+  increment(by?: number): this;
+  decrement(by?: number): this;
+  complete(): this;
+  reset(): this;
+  animateTo(target: number, duration?: number): this;
+  readonly value: number;
+}
+
+export interface CircularProgressOptions {
+  value?:       number;
+  size?:        number;
+  strokeWidth?: number;
+  color?:       string;
+}
+
+export declare class CircularProgress {
+  constructor(container: HTMLElement | string, options?: CircularProgressOptions);
+  set(value: number): this;
+  animateTo(target: number, duration?: number): this;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TOOLTIP
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+
+export declare class Tooltip {
+  constructor(element: HTMLElement | string, text: string, position?: TooltipPosition);
+  update(text: string): this;
+  destroy(): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FORM VALIDATOR
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ValidationRule =
+  | 'required'
+  | { type: 'minLength'; value: number }
+  | { type: 'maxLength'; value: number }
+  | { type: 'email' }
+  | { type: 'pattern'; value: RegExp; message?: string }
+  | { type: 'custom'; validate: (value: string) => true | string };
+
+export interface FormValidatorOptions {
+  lang?:     ZTLLang;
+  onSubmit?: (values: Record<string, string>, event: Event) => void;
+}
+
+export declare class FormValidator {
+  constructor(
+    form: HTMLFormElement | string,
+    rules: Record<string, ValidationRule[]>,
+    options?: FormValidatorOptions
+  );
+  validate(): boolean;
+  getValues(): Record<string, string>;
+  clearErrors(): void;
+  setErrors(errors: Record<string, string>): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TAG INPUT
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TagInputOptions {
+  initial?:  string[];
+  max?:      number;
+  onChange?: (tags: string[]) => void;
+  onAdd?:    (tag: string, tags: string[]) => void;
+  onRemove?: (tag: string, tags: string[]) => void;
+}
+
+export declare class TagInput {
+  constructor(container: HTMLElement | string, options?: TagInputOptions);
+  add(text: string): this;
+  remove(text: string): this;
+  getTags(): string[];
+  clear(): this;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DATA TABLE
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TableColumn<T = Record<string, unknown>> {
+  key:       keyof T & string;
+  label:     string;
+  sortable?: boolean;
+  render?:   (value: unknown, row: T) => string;
+}
+
+export interface DataTableOptions<T = Record<string, unknown>> {
+  columns:     TableColumn<T>[];
+  data:        T[];
+  pageSize?:   number;
+  searchable?: boolean;
+  lang?:       ZTLLang;
+}
+
+export declare class DataTable<T = Record<string, unknown>> {
+  constructor(container: HTMLElement | string, options: DataTableOptions<T>);
+  update(data: T[]): this;
+  setPage(page: number): this;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// THEME MANAGER
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ThemeManagerOptions {
+  storageKey?: string;
+  default?:    ZTLTheme;
+}
+
+export declare class ThemeManager {
+  constructor(options?: ThemeManagerOptions);
+  apply(theme: ZTLTheme): void;
+  toggle(): void;
+  setAccent(color: string): void;
+  readonly current: ZTLTheme;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CounterOptions {
+  duration?: number;
+  prefix?:   string;
+  suffix?:   string;
+  decimals?: number;
+}
+
+export interface ClipboardResult {
+  success: boolean;
+  message: string;
+}
+
+export interface SkeletonInstance {
+  clear:   () => void;
+  replace: (html: string) => void;
+}
+
+export declare function copyToClipboard(text: string, lang?: ZTLLang): Promise<ClipboardResult>;
+export declare function animateCounter(el: HTMLElement, target: number, options?: CounterOptions): void;
+export declare function skeleton(container: HTMLElement | string, count?: number): SkeletonInstance;
+export declare function initScrollReveal(selector?: string): void;
+export declare function initCounters(selector?: string): void;
+export declare function initCopyButtons(lang?: ZTLLang): void;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAIN ZTL INTERFACE
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ZTLInstance {
+  readonly version: string;
+  lang:   ZTLLang;
+  theme:  ThemeManager;
+  toast:  ToastManager;
+
+  init(config?: ZTLConfig): ZTLInstance;
+
+  // Components
+  Modal:           typeof Modal;
+  Tabs:            typeof Tabs;
+  Dropdown:        typeof Dropdown;
+  ProgressBar:     typeof ProgressBar;
+  CircularProgress: typeof CircularProgress;
+  Tooltip:         typeof Tooltip;
+  FormValidator:   typeof FormValidator;
+  TagInput:        typeof TagInput;
+  DataTable:       typeof DataTable;
+  ThemeManager:    typeof ThemeManager;
+  ToastManager:    typeof ToastManager;
+
+  // Utils
+  copyToClipboard: typeof copyToClipboard;
+  animateCounter:  typeof animateCounter;
+  skeleton:        typeof skeleton;
+  initScrollReveal: typeof initScrollReveal;
+  initCounters:    typeof initCounters;
+  initCopyButtons: typeof initCopyButtons;
+
+  // i18n
+  i18n: typeof i18n;
+  t(key: keyof ZTLTranslations, ...args: unknown[]): string;
+
+  // DOM
+  $:  (selector: string, context?: Document | HTMLElement) => HTMLElement | null;
+  $$: (selector: string, context?: Document | HTMLElement) => HTMLElement[];
+}
+
+declare const ZTL: ZTLInstance;
+export default ZTL;
+export { ZTL };