# Dev: UI Guide

UI development is a key part of SD.Next, and we welcome contributions to improve the user interface.

UI components are written in **TypeScript** and located in 3 separate locations within SD.Next:

- **Core**:  
  Contains core UI components and StandardUI  
  Folder: `ui/`  
  Repo: <https://github.com/vladmandic/sdnext>  
- **ModernUI**:  
  Contains ModernUI UI components and related code  
  Folder: `extensions-builtin/sdnext-modernui/`  
  Repo: <https://github.com/binaryQuantumSoul/sdnext-modernui>  
- **Kanvas**:  
  Contains Kanvas UI components and related code  
  Folder: `extensions-builtin/sdnext-kanvas/`  
  Repo: <https://github.com/vladmandic/sdnext-kanvas>

> [!NOTE]
> Depending on the scope of your changes, your contribution may involve one or more of these repositories.

> [!IMPORTANT] Any changes to the code requires rebuild to be visible in the application.

> [!WARNING] Do not edit built files, always edit source files and run the build command to generate the built files.

## Requirements

All UI work requires that NodeJS is installed  
Install requirements:  

> [!TIP]
> `pnpm` is recommended for faster installs and better dependency management

```bash
npm install -g pnpm
pnpm install
```

## Building

All build commands are defined in `package.json` and can be run with `pnpm run <command>`.

To create production builds:
- `build:core` - builds core UI components and StandardUI
- `build:modernui` - builds ModernUI components
- `build:kanvas` - builds Kanvas components
- `build` - builds all UI components

To run development builds with watch mode that automatically rebuilds on file changes:
- `dev:ui` - builds ModernUI components with watch mode
- `dev:modernui` - builds ModernUI components with watch mode
- `dev:kanvas` - builds Kanvas components with watch mode

## Lint

[SD.Next](https://github.com/vladmandic/sdnext) uses both `ESLint, Precommit and Typescript` checks to maintain code quality and enforce coding standards.

> [!IMPORTANT]
> Linting is required for all contributions and can be run with

- `tsc:core` - runs TypeScript checks for core UI components
- `tsc:modernui` - runs TypeScript checks for ModernUI components
- `tsc:kanvas` - runs TypeScript checks for Kanvas components
- `tsc` - runs TypeScript checks for all UI components
- `eslint:core` - runs ESLint for core UI components
- `eslint:modernui` - runs ESLint for ModernUI components
- `eslint:kanvas` - runs ESLint for Kanvas components
- `eslint` - runs ESLint for all UI components
- `precommit` - runs Precommit checks for all UI components

> [!TIP]
> `pnpm run ui` runs all UI checks and a full build.  
> It is recommended before submitting a PR.  

## Paths

- **Core**: source `ui/` -> target `ui/dist/`
- **ModernUI**: source `extensions-builtin/sdnext-modernui/src/` -> target `extensions-builtin/sdnext-modernui/javascript/`
- **Kanvas**: source `extensions-builtin/sdnext-kanvas/src/` -> target `extensions-builtin/sdnext-kanvas/javascript/` & target `extensions-builtin/sdnext-kanvas/dist/`

## Notes

*Python-vs-TypeScript* UI method calls:

When calling UI methods from **Python** using **Gradio** `_js=...` interface,  
the method must be:
1. Exposed in the `window` object
2. Registered in `ui/globals.d.ts`

When calling UI methods from **TypeScript** code,  
do NOT use the `window` object as goal is to avoid global namespace pollution,  
but import the method directly from the source file.