Guide

Core Concepts

This document introduces the core concepts of TSone to help you understand its design and how it works.

1. Application Instance

An application instance is the entry point for a TSone application. Create one with createApp.

import { createApp } from '@geektech/tsone';

const app = createApp({
  state: {
    appName: 'My App',
  },
});

app.mount();

2. Components

All components extend Component<Props, State> and use protected render(): VNode to describe the UI.

Component Lifecycle

• beforeMount(): called before the component mounts
• onMounted(): called after the component mounts
• beforeUpdate(): called before the component updates
• onUpdated(): called after the component updates
• beforeUnmount(): called before the component unmounts
• onUnmounted(): called after the component unmounts

Component Rendering

A component returns virtual nodes from render(); the renderer selects a text, element, component, or slot strategy based on the VNode type.

3. Reactivity System

TSone reactivity is implemented with Proxy. Common APIs include reactive, effect, computed, readonly, ref, and stop.

Core APIs

• reactive(target): creates a reactive object
• effect(fn): creates an effect function
• computed(fn): creates a computed value
• readonly(target): creates a readonly reactive object
• ref(value): creates a reactive reference that wraps one value

4. Virtual DOM

The virtual DOM is a lightweight abstraction of the real DOM.

Virtual DOM Structure

const vnode = {
  tag: 'div',
  props: { className: 'container' },
  listeners: {
    click: () => console.log('clicked'),
  },
  children: [
    'Hello World',
    { tag: 'button', children: ['Click Me'] },
  ],
};

const componentVnode = {
  component: MyComponent,
  props: { title: 'My Component' },
};

5. Routing

Create a router instance with createRouter, then use RouterView and RouterLink for rendering and navigation.

Route Configuration

import { createRouter } from '@geektech/tsone/router';

const router = createRouter({
  routes: [
    { path: '/', component: HomeComponent, meta: { title: 'Home' } },
    { path: '/about', component: AboutComponent, meta: { title: 'About Us' } },
  ],
  mode: 'history',
  base: '/',
});

6. Style Management

TSone provides a built-in StyleManager. Each component instance can manage styles through this.styleManager.

Style Definition

protected initStyles() {
  this.styleManager.addStyle('.container', {
    selector: '.container',
    properties: {
      width: '100%',
      maxWidth: '1200px',
      margin: '0 auto',
    },
  });
}

7. Plugin System

Install plugins with app.use() to extend application context and components.

Plugin Example

const myPlugin = {
  install(app: { myMethod?: () => void }) {
    app.myMethod = () => {
      console.log('My plugin method');
    };
  },
};

app.use(myPlugin);

8. Event System

Components can notify through emit/on, and on returns an unsubscribe function.

Event Example

this.emit('custom-event', 'event data');

const unsubscribe = component.on('custom-event', (data) => {
  console.log('Event received:', data);
});
unsubscribe();

9. Conditions, Lists, Dependencies, and Forms

VNode directions.if controls mounting for elements, components, and slots; each provides stable keys for lists.

const rows = each(
  this.state.rows,
  (row) => ({ tag: 'li', children: [row.name] }),
  (row) => row.id
);

const sidebar = {
  component: Sidebar,
  directions: { if: this.state.open },
};

Applications or components can provide dependencies with provide. Child components use inject to retrieve the closest value.

const LOCALE: InjectionKey<string> = Symbol('locale');
app.provide(LOCALE, 'zh-CN');
const locale = this.inject(LOCALE, 'en-US');

Native form nodes bind state through directions.model. Validation is handled by a separate createForm controller.

const name = Input({ directions: { model: 'profile.name' } });
const form = createForm(this.state, {
  'profile.name': [required('Please enter a name'), minLength(2)],
});
const result = form.validate();

Summary

Start with the Architecture Overview to see how the layers fit together. Together, these concepts form TSone’s application model. Continue with Component System, Reactive System and Routing for more concrete code patterns.