Region Management

/**
 * Container for managing view lifecycle within a DOM element
 * @param options - Configuration options for the region
 */
const Region: {
  new (options?: RegionOptions): Region;
  extend(properties: object, classProperties?: object): typeof Region;
};

interface Region {
  /** Initialize the region (noop method for overriding) */
  initialize(): void;
  
  /** Show a view in the region */
  show(view: View, options?: ShowOptions): this;
  
  /** Get the region's DOM element */
  getEl(el?: string | Element): Element;
  
  /** Attach view HTML to the region */
  attachHtml(view: View): void;
  
  /** Empty the region by destroying/removing the current view */
  empty(options?: EmptyOptions): this;
  
  /** Destroy the current view */
  destroyView(view: View): void;
  
  /** Remove the current view without destroying */
  removeView(view: View): void;
  
  /** Detach the current view */
  detachView(): View | undefined;
  
  /** Detach HTML from the region */
  detachHtml(): void;
  
  /** Check if the region has a current view */
  hasView(): boolean;
  
  /** Reset the region to initial state */
  reset(options?: ResetOptions): this;
  
  /** Check if the region is destroyed */
  isDestroyed(): boolean;
  
  /** Destroy the region and clean up resources */
  destroy(options?: DestroyOptions): this;
  
  /** Check if the region element has been replaced */
  isReplaced(): boolean;
  
  /** Check if the region is currently swapping views */
  isSwappingView(): boolean;
  
  /** Get the region's DOM element, optionally by selector */
  getEl(el?: string | Element): Element;
}

interface RegionOptions {
  /** DOM element or selector for the region */
  el?: string | Element;
  
  /** Parent element to search within for el */
  parentEl?: string | Element;
  
  /** Whether to replace the region element with view element */
  replaceElement?: boolean;
  
  /** Whether to allow missing DOM elements */
  allowMissingEl?: boolean;
}

import { Region, View } from "backbone.marionette";

// Create a region
const region = new Region({ el: '#main-content' });

// Create and show a view
class ContentView extends View {
  template() {
    return '<h1>Main Content</h1><p>This is the main content area.</p>';
  }
}

const contentView = new ContentView();
region.show(contentView);

// Show a different view (automatically cleans up previous)
class OtherView extends View {
  template() {
    return '<h1>Other Content</h1>';
  }
}

const otherView = new OtherView();
region.show(otherView); // contentView is automatically destroyed

// Empty the region
region.empty(); // otherView is destroyed and removed

// Check region state
console.log(region.hasView()); // false
console.log(region.isDestroyed()); // false

/**
 * Show a view in the region, replacing any existing view
 * @param view - View instance to show
 * @param options - Options for showing the view
 * @returns The region instance for chaining
 */
show(view: View, options?: ShowOptions): this;

/**
 * Check if the region currently has a view
 * @returns True if region has a current view
 */
hasView(): boolean;

/**
 * Get the region's DOM element
 * @param el - Optional element to set/get
 * @returns The region's DOM element
 */
getEl(el?: string | Element): Element;

/**
 * Attach view HTML to the region's element
 * @param view - View whose HTML should be attached
 */
attachHtml(view: View): void;

interface ShowOptions {
  /** Force showing even if same view */
  forceShow?: boolean;
  
  /** Prevent destroying the previous view */
  preventDestroy?: boolean;
}

// Basic view showing
const region = new Region({ el: '#sidebar' });
const sidebarView = new SidebarView();
region.show(sidebarView);

// Show with options
const newView = new NewSidebarView();
region.show(newView, { 
  forceShow: true // Show even if it's the same view instance
});

// Prevent destroying previous view
const temporaryView = new TemporaryView();
region.show(temporaryView, { 
  preventDestroy: true // Previous view won't be destroyed
});

/**
 * Empty the region by removing/destroying the current view
 * @param options - Options for emptying
 * @returns The region instance for chaining
 */
empty(options?: EmptyOptions): this;

/**
 * Destroy the current view in the region
 * @param view - View to destroy (should be current view)
 */
destroyView(view: View): void;

/**
 * Remove the current view without destroying it
 * @param view - View to remove (should be current view)
 */
removeView(view: View): void;

/**
 * Detach the current view from the region
 * @returns The detached view or undefined
 */
detachView(): View | undefined;

/**
 * Detach HTML content from the region element
 */
detachHtml(): void;

interface EmptyOptions {
  /** Whether to check if region should be empty after operation */
  checkForEmpty?: boolean;
}

// Empty region (destroys current view)
region.empty();

// Empty with options
region.empty({ checkForEmpty: true });

// Detach view without destroying
const detachedView = region.detachView();
// detachedView can be reused elsewhere

// Remove specific view
if (region.hasView()) {
  region.removeView(region.currentView);
}

/**
 * Reset the region to its initial state
 * @param options - Reset options
 * @returns The region instance for chaining
 */
reset(options?: ResetOptions): this;

/**
 * Check if the region has been destroyed
 * @returns True if region is destroyed
 */
isDestroyed(): boolean;

/**
 * Destroy the region and clean up all resources
 * @param options - Destroy options
 * @returns The region instance for chaining
 */
destroy(options?: DestroyOptions): this;

/**
 * Check if the region element has been replaced
 * @returns True if element was replaced
 */
isReplaced(): boolean;

/**
 * Check if the region is currently in the process of swapping views
 * @returns True if currently swapping views
 */
isSwappingView(): boolean;

interface ResetOptions {
  /** Whether to destroy current view during reset */
  destroyView?: boolean;
}

// Region that replaces its element
const region = new Region({ 
  el: '#replaceable-container',
  replaceElement: true 
});

// When showing a view, the region's element is replaced with view's element
const view = new View({
  tagName: 'section',
  className: 'main-section'
});

region.show(view); // #replaceable-container is replaced with <section class="main-section">

/**
 * Set custom DOM API for all regions
 * @param mixin - DOM API mixin object
 */
static setDomApi(mixin: DomApiMixin): void;

/** DOM API instance used by the region */
Dom: DomApi;

/** Unique identifier prefix for regions */
cidPrefix: 'mnr';

/** Whether to replace the region element with view element */
replaceElement: boolean; // default: false

/** The currently displayed view */
currentView: View | undefined;

// View showing events
region.on('before:show', (view, region, options) => { /* ... */ });
region.on('show', (view, region, options) => { /* ... */ });

// View emptying events
region.on('before:empty', (view, region) => { /* ... */ });
region.on('empty', (view, region) => { /* ... */ });

// View swapping events
region.on('before:swap', (newView, oldView, region) => { /* ... */ });
region.on('swap', (newView, oldView, region) => { /* ... */ });

// Region destruction events
region.on('before:destroy', (region, options) => { /* ... */ });
region.on('destroy', (region, options) => { /* ... */ });

// Listen to region events
region.on('show', (view, region) => {
  console.log('View shown in region:', view);
});

region.on('empty', (view, region) => {
  console.log('Region emptied, view was:', view);
});

// Global region event handling
import { Region } from "backbone.marionette";

// Listen to all region events
Region.prototype.on('show', (view, region) => {
  // Track all views shown in any region
  analytics.trackViewShown(view.constructor.name);
});

// Custom region with additional behavior
class ModalRegion extends Region {
  show(view, options = {}) {
    // Add modal-specific behavior
    this.el.classList.add('modal-active');
    return super.show(view, options);
  }
  
  empty(options = {}) {
    // Remove modal styling
    this.el.classList.remove('modal-active');
    return super.empty(options);
  }
  
  onShow(view) {
    // Custom show behavior
    view.$el.fadeIn();
  }
  
  onEmpty() {
    // Custom empty behavior
    this.el.style.display = 'none';
  }
}

// Use custom region
const modalRegion = new ModalRegion({ el: '#modal-container' });

// Create regions dynamically
class DynamicLayoutView extends View {
  template() {
    return '<div id="dynamic-content"></div>';
  }
  
  onRender() {
    // Create region after render
    this.addRegion('dynamicRegion', '#dynamic-content');
  }
  
  showDynamicContent(contentType) {
    let view;
    switch (contentType) {
      case 'chart':
        view = new ChartView();
        break;
      case 'table':
        view = new TableView();
        break;
      default:
        view = new DefaultView();
    }
    
    this.showChildView('dynamicRegion', view);
  }
}

interface ResetOptions {
  destroyView?: boolean;
}

interface DestroyOptions {
  checkForEmpty?: boolean;
}