Application & Components

/**
 * Main application container extending TemplateSet
 * @template T - Component constructor type
 * @template P - Props type
 * @template E - Environment type
 */
class App<T, P, E> extends TemplateSet {
  /** Application name */
  name: string;
  /** Root component constructor */
  Root: ComponentConstructor<P, E>;
  /** Application props */
  props: P;
  /** Application environment */
  env: E;
  /** Internal scheduler */
  scheduler: Scheduler;
  /** Set of sub-roots */
  subRoots: Set<ComponentNode>;
  /** Root component node */
  root: ComponentNode<P, E> | null;

  /** Static target validation utility */
  static validateTarget(target: any): void;
  /** Static set of all app instances */
  static apps: Set<App>;
  /** Static OWL version string */
  static version: string;

  /**
   * Creates a new OWL application
   * @param Root - Root component constructor
   * @param config - Application configuration
   */
  constructor(Root: ComponentConstructor<P, E>, config?: AppConfig<P, E>);

  /**
   * Mounts the application to a DOM target
   * @param target - DOM element or shadow root to mount to
   * @param options - Mount options
   * @returns Promise resolving to the mounted component instance
   */
  mount(target: HTMLElement | ShadowRoot, options?: MountOptions): Promise<Component<P, E>>;

  /**
   * Creates a sub-root component that can be independently mounted
   * @template Props - Component props type
   * @template SubEnv - Sub-environment type
   * @param Root - Component constructor
   * @param config - Root configuration
   * @returns Root object with mount and destroy methods
   */
  createRoot<Props, SubEnv>(
    Root: ComponentConstructor<Props, SubEnv>,
    config?: RootConfig<Props, SubEnv>
  ): Root<Props, SubEnv>;

  /**
   * Creates a component node
   * @param Component - Component constructor
   * @param props - Component props
   * @returns New ComponentNode instance
   */
  makeNode(Component: ComponentConstructor, props: any): ComponentNode;
}

import { App, Component, xml } from "@odoo/owl";

class MyApp extends Component {
  static template = xml`<div>Hello OWL!</div>`;
}

// Basic app creation and mounting
const app = new App(MyApp, {
  name: "MyApplication",
  dev: true
});

await app.mount(document.body);

// App with props and environment
const appWithConfig = new App(MyApp, {
  props: { title: "My App" },
  env: { apiUrl: "https://api.example.com" },
  dev: process.env.NODE_ENV === "development"
});

await appWithConfig.mount(document.getElementById("app"));

// Creating sub-roots for micro-frontend patterns
const subRoot = app.createRoot(AnotherComponent, {
  props: { mode: "embedded" },
  env: { theme: "dark" }
});

await subRoot.mount(document.getElementById("widget"));

/**
 * Convenience function to mount a component directly
 * @template T - Component constructor type
 * @template P - Props type
 * @template E - Environment type
 * @param C - Component constructor to mount
 * @param target - DOM element or shadow root to mount to
 * @param config - Optional application configuration
 * @returns Promise resolving to the mounted component instance
 */
function mount<T, P, E>(
  C: ComponentConstructor<P, E>,
  target: HTMLElement | ShadowRoot,
  config?: AppConfig<P, E>
): Promise<Component<P, E>>;

import { mount, Component, xml } from "@odoo/owl";

class QuickComponent extends Component {
  static template = xml`<div>Quick mount!</div>`;
}

// Simple mounting
await mount(QuickComponent, document.body);

// Mount with configuration
await mount(QuickComponent, document.getElementById("app"), {
  props: { message: "Hello" },
  env: { user: currentUser },
  dev: true
});

/**
 * Base component class for all OWL components
 * @template Props - Component props type
 * @template Env - Environment type
 */
class Component<Props = any, Env = any> {
  /** Static template string (must be defined by subclasses) */
  static template: string;
  /** Static props validation schema */
  static props?: Schema;
  /** Static default props values */
  static defaultProps?: any;
  /** Static sub-components registry */
  static components?: { [componentName: string]: ComponentConstructor };

  /** Component props */
  props: Props;
  /** Component environment */
  env: Env;
  /** Internal OWL component node (do not use directly) */
  __owl__: ComponentNode;

  /**
   * Component constructor (called by OWL framework)
   * @param props - Component properties
   * @param env - Component environment
   * @param node - Internal component node
   */
  constructor(props: Props, env: Env, node: ComponentNode);

  /**
   * Setup hook called during component initialization
   * Use this for state initialization, hook setup, and other initialization logic
   */
  setup(): void;

  /**
   * Triggers a re-render of this component
   * @param deep - Whether to force deep re-render of all children
   */
  render(deep?: boolean): void;
}

import { Component, xml, useState, useEnv } from "@odoo/owl";

// Basic component with template
class SimpleGreeting extends Component {
  static template = xml`
    <div class="greeting">
      <h1>Hello, <t t-esc="props.name"/>!</h1>
    </div>
  `;
}

// Component with state and lifecycle
class TodoList extends Component {
  static template = xml`
    <div class="todo-list">
      <input t-model="state.newTodo" t-on-keyup.enter="addTodo"/>
      <ul>
        <li t-foreach="state.todos" t-as="todo" t-key="todo.id">
          <t t-esc="todo.text"/>
        </li>
      </ul>
    </div>
  `;

  setup() {
    this.state = useState({
      todos: [],
      newTodo: ""
    });
  }

  addTodo() {
    if (this.state.newTodo.trim()) {
      this.state.todos.push({
        id: Date.now(),
        text: this.state.newTodo.trim()
      });
      this.state.newTodo = "";
    }
  }
}

// Component with props validation and environment usage
class UserProfile extends Component {
  static template = xml`
    <div class="user-profile">
      <h2><t t-esc="props.user.name"/></h2>
      <p><t t-esc="props.user.email"/></p>
      <button t-if="env.isAdmin" t-on-click="editUser">Edit</button>
    </div>
  `;

  static props = {
    user: {
      type: Object,
      shape: {
        name: String,
        email: String,
        id: Number
      }
    }
  };

  setup() {
    this.env = useEnv();
  }

  editUser() {
    console.log("Editing user:", this.props.user.id);
  }
}

interface AppConfig<P, E> extends TemplateSetConfig, RootConfig<P, E> {
  /** Application name for debugging */
  name?: string;
  /** Enable test mode */
  test?: boolean;
  /** Warn if components don't have static props */
  warnIfNoStaticProps?: boolean;
}

interface RootConfig<P, E> {
  /** Props to pass to root component */
  props?: P;
  /** Environment to provide to components */
  env?: E;
}

interface MountOptions {
  /** Where to position the component in the target */
  position?: "first-child" | "last-child";
}

interface Root<P, E> {
  /** Component node reference */
  node: ComponentNode<P, E>;
  /** Mount the root to a DOM target */
  mount(target: HTMLElement | ShadowRoot, options?: MountOptions): Promise<Component<P, E>>;
  /** Destroy the root and clean up */
  destroy(): void;
}