@geoit/ui

GEO design system for Angular 18 + ng-zorro 18. Standalone components, design tokens, and AI-ready usage docs (shipped in the package under ai/).

Install

npm install @geoit/ui

Publish

Từ root repository:

npm run publish:npm:dry   # kiểm tra tarball, không publish
npm run release:npm:patch # tăng patch version rồi build + publish

Ở máy consumer, nếu npm đang dùng cache version cũ:

npm cache clean --force
npm install @geoit/ui@latest --prefer-online --force

Peer dependencies (install in your app if missing):

npm install @angular/animations@^18 @angular/common@^18 @angular/core@^18 \
  @angular/forms@^18 @angular/cdk@^18 @ant-design/icons-angular@^18 ng-zorro-antd@^18 \
  ol@^10 proj4@^2

ol + proj4 are required when you use map components (geo-map, geo-map-shell, …).

Setup styles (once per app)

In your global styles (e.g. styles.scss):

@import "node_modules/ng-zorro-antd/ng-zorro-antd.min.css";
@import "node_modules/@geoit/ui/src/lib/styles/design-tokens.scss";
@import "node_modules/@geoit/ui/src/lib/styles/theme.scss";

Providers (animations + Vietnamese i18n for date pickers):

import { provideAnimations } from "@angular/platform-browser/animations";
import { provideNzI18n, vi_VN } from "ng-zorro-antd/i18n";
import { registerLocaleData } from "@angular/common";
import vi from "@angular/common/locales/vi";

registerLocaleData(vi);

// in appConfig.providers:
provideAnimations(),
provideNzI18n(vi_VN),

Use tokens in your CSS — do not hardcode brand colors or radius:

• var(--geo-color-primary-default)
• var(--geo-radius) (default 8px; md/lg/xl for chips & popovers)

Quick start

import { Component } from "@angular/core";
import { FormsModule } from "@angular/forms";
import { GeoButtonComponent, GeoInputComponent, GeoFormModalComponent, GeoToastService } from "@geoit/ui";

@Component({
  standalone: true,
  imports: [FormsModule, GeoButtonComponent, GeoInputComponent, GeoFormModalComponent],
  template: `
    <geo-button appearance="primary" color="brand" icon="plus" (clicked)="open = true"> Thêm mới </geo-button>

    <geo-form-modal [open]="open" title="Thêm mới" cancelText="Hủy bỏ" okText="Lưu" (openChange)="open = $event" (ok)="save()">
      <geo-input label="Tên" [required]="true" [block]="true" [(ngModel)]="name"></geo-input>
    </geo-form-modal>
  `,
})
export class DemoComponent {
  open = false;
  name = "";

  constructor(private toast: GeoToastService) {}

  save(): void {
    this.toast.success("Thành công!", "Đã lưu.");
    this.open = false;
  }
}

Common components

| Need | Component | Example | | --------------- | -------------------------------- | ----------------------------------------------------------------- | | Button / CTA | geo-button | <geo-button appearance="primary" color="brand">Lưu</geo-button> | | Text field | geo-input | <geo-input label="Họ tên" [(ngModel)]="name" [block]="true"> | | Select | geo-select | <geo-select [options]="opts" [(ngModel)]="v" [block]="true"> | | Checkbox | geo-checkbox | <geo-checkbox label="Đồng ý" [(checked)]="ok"> | | Radio | geo-radio | <geo-radio [options]="opts" [(ngModel)]="v"> | | Date / range | geo-date-picker / geo-date-range-picker | [(ngModel)] + format="dd/MM/yyyy" | | Form dialog | geo-form-modal | See Quick start | | Confirm delete | geo-confirm-modal | [visible] + (confirm) | | Steps in dialog | geo-form-modal + geo-stepper | See recipes | | App shell | geo-layout | menu + header + content | | Page title | geo-page-title | <geo-page-title title="Chi tiết hồ sơ"> | | Breadcrumb | geo-breadcrumb | [items]="[{ label, link? }]" | | Toast | GeoToastService | this.toast.success(title, message) | | Alert | geo-alert | type="success" \| "error" \| … | | Status pill | geo-status-tag | status="success" label="Đã duyệt" | | Table | geo-table | [columns] + [data] + paging | | Upload | geo-upload | Drag-drop multi-file | | Map portal | geo-map-shell | Search + layers + legend + parcel (recommended) | | Bare map | geo-map | OpenLayers host + GeoMapController | | Typography | geo-typography | variant="h3" \| "body" \| … |

Button API (quick)

| Input | Values | Default | | ---------------------------------- | --------------------------------------------- | --------- | | appearance | primary | secondary | tertiary | primary | | color | brand | danger | warning | success | brand | | icon / iconPlacement | Ant icon name; start | end | start | | disabled / iconOnly / active | boolean | false |

<geo-button appearance="primary" color="brand" icon="plus">Thêm mới</geo-button>
<geo-button appearance="primary" icon="right" iconPlacement="end">Tiếp theo</geo-button>
<geo-button appearance="secondary" (clicked)="cancel()">Hủy</geo-button>

Form controls & ngModel

These implement ControlValueAccessor — use [(ngModel)] or reactive forms:

geo-input, geo-textarea, geo-select, geo-radio, geo-date-picker, geo-date-range-picker, geo-file-picker

• geo-checkbox → [(checked)] (not CVA)
• geo-slider → [(value)] (model())

Map portal (quick)

<geo-map-shell
  height="640px"
  [demoSearch]="false"
  parcelAudience="citizen"
  [layers]="layers"
  (mapReady)="ctrl = $event"
  (search)="onSearch($event)"
></geo-map-shell>

See ai/recipes.md §13 and ai/components/geo-map-shell.md.

Toast (preferred)

import { GeoToastService } from '@geoit/ui';

constructor(private toast: GeoToastService) {}

this.toast.success('Thành công!', 'Đã lưu hồ sơ.');
this.toast.error('Lỗi!', 'Không thể lưu.');

Full docs (shipped in the package)

After install:

| Path | Purpose | | ------------------------------------------- | ----------------------------------------------- | | node_modules/@geoit/ui/ai/AGENTS.md | Rules for humans & AI agents | | node_modules/@geoit/ui/ai/README.md | Component index | | node_modules/@geoit/ui/ai/catalog.json | Machine-readable catalog | | node_modules/@geoit/ui/ai/components/*.md | Per-component API (inputs/outputs/examples) | | node_modules/@geoit/ui/ai/recipes.md | Copy-paste screen patterns |

Open a component doc before using it, e.g.:

node_modules/@geoit/ui/ai/components/geo-button.md
node_modules/@geoit/ui/ai/components/geo-form-modal.md
node_modules/@geoit/ui/ai/components/geo-map-shell.md
node_modules/@geoit/ui/ai/components/geo-table.md

Cursor rule (recommended)

.cursor/rules/geo-ui.mdc in your app:

---
description: Use @geoit/ui components
alwaysApply: true
---

UI must use `@geoit/ui`. Before writing UI, read:

- node_modules/@geoit/ui/ai/AGENTS.md
- node_modules/@geoit/ui/ai/catalog.json
- node_modules/@geoit/ui/ai/components/<selector>.md when needed
- node_modules/@geoit/ui/ai/recipes.md for screen patterns

Design tokens

| Group | Examples | | -------- | ------------------------------------------------------------------------- | | Primary | --geo-color-primary-default (#9A4828), hover, light, dark, background | | Neutral | --geo-color-neutral-900 … 100, white | | Semantic | success / error / warning / info | | Radius | --geo-radius (8px) + --geo-radius-{xs,sm,md,lg,xl,2xl,full} | | Font | --geo-font-family |

TypeScript mirror: geoColorTokens from @geoit/ui (via styles/tokens export).

License

Internal / project license — see repository.