# sapit-ui base framework guide and business usage
> Applies to: sapit-ui-framework (the base / sources), sapit-ui-plus (published artifact), sapit-base-template (business sample).
>
> This document is also the data source of the built-in `/docs`, `/components` and `/tools` pages.
>
> Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering.
---
## Contents
- [1. Overview](#docs-1Overview)
- [2. What the base provides](#docs-2Whatthebaseprovides)
- [3. Build and configuration](#docs-3Buildandconfiguration)
- [4. Business project integration](#docs-4Businessprojectintegration)
- [5. Caveats](#docs-5Caveats)
- [6. Online documentation entry](#docs-6Onlinedocumentationentry)
---
## 1. Overview
### 1.1 The five pieces
| Project | Role | Description |
| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `sapit-ui-framework` | Base (sources) | Library project holding the built-in components and common dependencies, packed in Vite lib mode |
| `sapit-ui-plus` | Published artifact | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) |
| `sapit-base-template` | Business consumer | Builds business pages and configuration on top of the `sapit-ui-plus` git dependency |
```text
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template
```
### 1.2 What the package contains
The `sapit-ui-plus` a business project installs carries only what runs at runtime (not the base source tree):
```text
node_modules/sapit-ui-plus/
├─ lib/ # build output: js / css / images — what the business actually imports
├─ docs/ # this document, rendered by the built-in /docs page
├─ vite-plugins/ # plugins referenced by the business vite.config.js (e.g. sso-plugin)
├─ static/ # static assets (login page images, ...)
└─ package.json
```
A business project only references three things: the entry `sapit-ui-plus`, the styles `sapit-ui-plus/lib/css/style.css`, and `vite-plugins/*` on demand.
---
## 2. What the base provides
### 2.1 Global components
`packages/index.js` uses `import.meta.glob('./components/**/*.vue')` to register every `components/**/*.vue` **by file name**, so templates can use the file name as the tag (e.g. ``, ``).
| Category | Components |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Layout | `SSkeletonLayout` (skeleton layout: title + button group + content), `SListLayout`, `SListCardLayout` (card list), `SListTableTreeLayout`, `SSuperListLayout` (advanced list: column settings + advanced filter), `SFormLayout`, `SPanelLayout`, `SCollapses`/`SCollapsesItem`, `SDrawer` |
| Overlay | `SModal`, `SModalTemplate`, `ModalHeader`, `SIconModal`, `SImportModal` (bulk import) |
| Form / filter | `SForm`, `SFormItem` (multi-column + `full` for a whole row), `SExtendFieldsForm`/`SExtendFieldsFormItem` (dynamic extra fields), `SFilterWrap`, `SFilterItem` (`full` for a whole row), `SFilterToolbar` (filter area shell: main row + more-filters collapse + reset), `STableToolbar` (table area shell: body height auto-fits the content area; used as a pair with `SFilterToolbar`), `SCascader`, `STree`, `STreeSelect`, `SDataRangeTreeSelect` (data-permission scope tree), `SUserSelect`, `SUserSelectButton`, `SChooseUser` (user picker with data permission), `SBelowChoosePosition` (position picker), `SOfficeSelect`, `SIconSelect` (icon dropdown, searchable/multiple), `SIconSelectPopover` (icon grid panel), `SIconModal` (icon browser) |
| Upload | `SFileUpload`, `SDraggerUpload`, `SCopperUpload`, `CropperModal` |
| Display / others | `STab`/`STabItem` (tab bar: arrows + drag when the tabs overflow), `SEditor`, `SEmpty`, `SIcon`, `SSvg`, `SAnchor`, `SColorPicker`, `SToggleLanguage`, `SettingFilter`, `SettingColumns`, `SSideMenu`/`STopMenu` |
> **Props / events / methods / slots, live previews and example code for every component live in the built-in component page `/components`** (tools and config live on their own page `/tools`, listing every web-config option and every `$utils` method).
>
> A few usage notes:
>
> - Component names are **PascalCase** (`SForm` / `STable`); both `` and `` resolve in templates — just stay consistent.
> - All `@ant-design/icons-vue` icons are registered globally, and the icon map is exposed as `$icons`.
> - A few helper components are internal (e.g. `ModalHeader`, `CropperModal`, `SettingColumns` / `SettingFilter`) — do not reference them from business code.
### 2.2 Global properties / methods
Available after `$registerGlobalConfig` runs (`this.$xxx` / `$xxx` in templates / `window.$xxx`):
| Name | Description |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$registerGlobalConfig(config, pages)` | Initialization entry (see 4.2) |
| `$utils` | Utility collection: `$utils.env` / `$utils.ls` / `$utils.http` plus general helpers |
| `env` | Merged environment configuration (= `$utils.env`) |
| `$i18n` / `$l(name)` | Internationalization (see 2.7). Lives on `globalProperties`: usable **directly in templates** as `$l('xx')`; inside `