# Schematics

- Page: https://koobiq.io/en/main/schematics/overview

As part of the **Koobiq** design system, a set of **schematics** is provided — CLI tools designed to automate library installation, perform migrations, and update components in Angular projects.

---

## Available Schematics

### ng-add

Installs the [`@koobiq/components`](https://github.com/koobiq/angular-components) library and adds all necessary dependencies.

**When to use:** When adding the library to a project for the first time.

```bash
ng add @koobiq/components
```

### new-icons-pack

Updates icon prefixes and names required to migrate from version `7.2.x` and below to version `8.0.2` and above.

**When to use:** After upgrading the [`@koobiq/icons`](https://github.com/koobiq/icons) library to version `8.0.2` or later.

```bash
ng generate @koobiq/components:new-icons-pack
```

### css-selectors

Updates deprecated CSS selectors (typography and color naming) according to the new design system conventions.

**When to use:** After upgrading the [`@koobiq/components`](https://github.com/koobiq/angular-components) library to version `18.6.0` or later.

```bash
ng generate @koobiq/components:css-selectors
```

### deprecated-icons

Moves icons off the deprecated `pt-icons` font to `kbq` and renames the deprecated icons.

**When to use:** while the project still has `pt-icons` classes (`class="pt-icons pt-icons-<name>"`).

```bash
ng generate @koobiq/components:deprecated-icons
```

### empty-state-size-attr

Updates size attribute names and values for the [`Empty state`](https://koobiq.io/en/components/empty-state.md) component in both HTML and TypeScript templates.

**When to use:** After upgrading the [`@koobiq/components`](https://github.com/koobiq/angular-components) library to version `18.22.0` or later.

```bash
ng generate @koobiq/components:empty-state-size-attr
```

### loader-overlay-size-attr

Updates size attribute names and values for the [`Overlay`](https://koobiq.io/en/components/loader-overlay.md) component in both HTML and TypeScript templates.

**When to use:** After upgrading the [`@koobiq/components`](https://github.com/koobiq/angular-components) library to version `18.22.0` or later.

```bash
ng generate @koobiq/components:loader-overlay-size-attr
```

### icons-replacement

Replaces icon names with new ones.

**When to use:** after updating the [`@koobiq/icons`](https://github.com/koobiq/icons) library version to `11.0.0` and higher.

```bash
ng generate @koobiq/components:icons-replacement
```

### Icon migrations: which ones and in what order

The three icon schematics are not run by `ng update`; run the ones that match the project yourself, in this order: `icons-replacement` renames the names the other two produce, so it goes last.

| Order | Schematic           | Run it when the project has                                                          |
| ----- | ------------------- | ------------------------------------------------------------------------------------ |
| 1     | `new-icons-pack`    | `@koobiq/icons` below `8.0.2`: the `mc` prefix (`mc-<name>`, `kbq-icon="mc-<name>"`) |
| 2     | `deprecated-icons`  | `pt-icons` classes (`class="pt-icons pt-icons-<name>"`)                              |
| 3     | `icons-replacement` | `@koobiq/icons` below `11.0.0`                                                       |

Each of them only reports what it finds until it is run with `--fix=true`, and each logs which icon mapping it uses. Common options:

- `--project` — a project name or a folder such as `./libs`; without it the whole workspace is migrated. `node_modules` and `dist` are always skipped.
- `--custom-data-path` (`new-icons-pack`, `icons-replacement`) — a JSON file with your own icon mapping, resolved from the workspace root: `[{ "replace": "kbq-add-to-list_16", "replaceWith": "kbq-file-plus-o_16" }]`. Without it the built-in mapping is used.

```bash
ng generate @koobiq/components:new-icons-pack --project ./libs
ng generate @koobiq/components:new-icons-pack --project ./libs --fix=true
```

## How to run a schematic

- Make sure Angular CLI is installed:

```bash
ng version
```

- Run the desired schematic using the `ng generate` command:

```bash
ng generate "@koobiq/components:<schematic-name>"
```

- Some schematics support additional options. See the `schema.json` file inside the corresponding schematic folder.
