@lishangpei/nav-sidebar/src/nav-sidebar-wc.d.ts

企业级站点导航组件 - 基于 Web Components，真正的跨框架复用

/**
 * Type definitions for NavSidebar Web Component
 */

export interface Site {
  id?: string | number;
  name: string;
  url: string;
  env?: string;
  count?: number;
  lastVisit?: string;
  tag?: string;
  description?: string;
}

export interface SiteClickEventDetail {
  site: Site;
  originalEvent: MouseEvent;
}

export interface EnvChangeEventDetail {
  newEnv: string;
  oldEnv: string;
}

/**
 * Custom events for NavSidebarElement
 */
export interface NavSidebarElementEventMap {
  'ready': CustomEvent<void>;
  'show': CustomEvent<void>;
  'hide': CustomEvent<void>;
  'site-click': CustomEvent<SiteClickEventDetail>;
  'env-change': CustomEvent<EnvChangeEventDetail>;
}

/**
 * NavSidebar Web Component Element
 */
export class NavSidebarElement extends HTMLElement {
  // Observed attributes
  static get observedAttributes(): string[];

  // Properties
  sites: Site[];
  filteredSites: Site[];
  currentEnv: string;
  isOpen: boolean;
  isTopbarVisible: boolean;
  currentTagType: string | null;

  // Configuration
  config: {
    apiUrl: string | null;
    sites: Site[];
    title: string;
    environments: string[];
    defaultEnv: string;
    floatIcon: string;
    enableFrequentVisits: boolean;
    frequentVisitsLimit: number;
    autoInit: boolean;
  };

  // Lifecycle methods
  connectedCallback(): void;
  disconnectedCallback(): void;
  attributeChangedCallback(name: string, oldValue: string, newValue: string): void;

  // Initialization
  init(): Promise<void>;

  // Public API
  show(): void;
  hide(): void;
  toggle(): void;
  switchEnvironment(env: string): Promise<void>;
  getCurrentEnvironment(): string;
  refresh(): Promise<void>;
  setSites(sites: Site[]): void;
  getSites(): Site[];
  clearVisitStats(): void;
  getFrequentVisits(limit?: number): Site[];

  // Event listeners
  addEventListener<K extends keyof NavSidebarElementEventMap>(
    type: K,
    listener: (this: NavSidebarElement, ev: NavSidebarElementEventMap[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions
  ): void;

  removeEventListener<K extends keyof NavSidebarElementEventMap>(
    type: K,
    listener: (this: NavSidebarElement, ev: NavSidebarElementEventMap[K]) => any,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | EventListenerOptions
  ): void;
}

/**
 * JSX intrinsic elements for TypeScript + React
 */
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'nav-sidebar': React.DetailedHTMLProps<
        React.HTMLAttributes<NavSidebarElement> & {
          'api-url'?: string;
          'title'?: string;
          'default-env'?: string;
          'environments'?: string;
          'float-icon'?: string;
          'enable-frequent-visits'?: string | boolean;
          'frequent-visits-limit'?: string | number;
          'auto-init'?: string | boolean;
          ref?: React.Ref<NavSidebarElement>;
        },
        NavSidebarElement
      >;
    }
  }
}

export default NavSidebarElement;