@geoit/ui 0.0.2 → 0.0.5

package/AGENTS.md

@@ -2,7 +2,18 @@
 
 Package name: **`@geoit/ui`**
 
-Canonical AI docs live under **`ai/`**:
+Canonical AI docs live under **`ai/`**.
+
+## Library code (`src/lib/figma`)
+
+Use **Angular 18** conventions:
+
+- `input()` / `output()` / `model()` — not `@Input` / `@Output`
+- `ChangeDetectionStrategy.OnPush`
+- `@if` / `@for`; `inject()` for DI
+- See `.cursor/rules/angular-18-figma.mdc`
+
+## AI docs
 
 | File | Purpose |
 |------|---------|
@@ -12,14 +23,7 @@ Canonical AI docs live under **`ai/`**:
 | [`ai/recipes.md`](./ai/recipes.md) | Copy-paste UI recipes |
 | [`ai/README.md`](./ai/README.md) | Index |
 
-Regenerate component docs + catalog:
-
 ```bash
 npm run ai:docs
-```
-
-Install in other projects:
-
-```bash
 npm install @geoit/ui
 ```

package/README.md

@@ -1,6 +1,6 @@
-# geo-ui (@geoit/ui)
+# @geoit/ui
 
-Angular 18 + ng-zorro GEO design system.
+GEO design system for **Angular 18** + **ng-zorro 18**. Standalone components, design tokens, and AI-ready usage docs.
 
 ## Install
 
@@ -8,28 +8,136 @@ Angular 18 + ng-zorro GEO design system.
 npm install @geoit/ui
 ```
 
-## Styles (app once)
+**Peer dependencies** (install in your app if missing):
+
+```bash
+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
+```
+
+## Setup styles (once per app)
+
+In your global styles (e.g. `styles.scss`):
 
 ```scss
-@import 'node_modules/@geoit/ui/src/lib/styles/design-tokens.scss';
-@import 'node_modules/@geoit/ui/src/lib/styles/theme.scss';
+@import "node_modules/@geoit/ui/src/lib/styles/design-tokens.scss";
+@import "node_modules/@geoit/ui/src/lib/styles/theme.scss";
 ```
 
-## AI / agent docs (shipped with this package)
+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
+
+```ts
+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">`                    |
+| 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                                                       |
+| 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                                              |
+| 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`   |
+
+```html
+<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>
+```
 
-After install, docs live in `node_modules/@geoit/ui/ai/`:
+### Form controls & `ngModel`
 
-| Path | Purpose |
-|------|---------|
-| `node_modules/@geoit/ui/AGENTS.md` | Pointer + rules |
-| `node_modules/@geoit/ui/ai/AGENTS.md` | Full agent rules |
-| `node_modules/@geoit/ui/ai/catalog.json` | Machine-readable catalog |
-| `node_modules/@geoit/ui/ai/components/*.md` | Per-component docs |
-| `node_modules/@geoit/ui/ai/recipes.md` | Copy-paste recipes |
+These implement **ControlValueAccessor** — use `[(ngModel)]` or reactive forms:
 
-### Consumer Cursor rule (recommended)
+`geo-input`, `geo-textarea`, `geo-select`, `geo-radio`, `geo-date-picker`, `geo-date-range-picker`, `geo-slider`
 
-Create `.cursor/rules/geo-ui.mdc` in your app:
+`geo-checkbox` uses **`[(checked)]`** (not CVA).
+
+### Toast (preferred)
+
+```ts
+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.:
+
+```text
+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-table.md
+```
+
+### Cursor rule (recommended)
+
+`.cursor/rules/geo-ui.mdc` in your app:
 
 ```md
 ---
@@ -38,9 +146,24 @@ 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
 ```
 
-Or `@`-mention `node_modules/@geoit/ui/ai/catalog.json` in chat.
+## 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.

package/ai/AGENTS.md

@@ -8,19 +8,22 @@ Instructions for AI coding agents (Cursor, Copilot, etc.) when building UI with
 2. **Do not** invent parallel wrappers or raw `nz-button` / `nz-input` / `nz-modal` when a `geo-*` equivalent exists.
 3. **Do not hardcode** brand colors or border-radius. Use tokens:
    - Colors: `var(--geo-color-*)` or `geoColorTokens` from `@geoit/ui`
-   - Radius: `var(--geo-radius)` (default **6px**)
-4. Before implementing a component, **read** `ai/components/<selector>.md` and/or `ai/catalog.json`.
-5. Prefer **copying examples** from those docs / Storybook over inventing new APIs.
+   - Radius: `var(--geo-radius)` (default **8px**; scale: sm 6 / md 10 / lg 12 / xl 14)
+4. Before implementing a component, **read the full doc** `ai/components/<selector>.md` (Inputs/Outputs/Examples/Tips) and/or `ai/catalog.json`.
+5. Prefer **copying examples** from those docs — adapt labels/bindings only; do not invent props.
+
+## Library implementation (maintainers)
+
+When changing `projects/geo-ui/src/lib/figma`:
+
+- Angular **18**: `input()` / `output()` / `model()`, `OnPush`, `@if`/`@for`, `inject()`
+- Do **not** add new `@Input` / `@Output` / `EventEmitter`
+- After API changes: `npm run ai:docs`
 
 ## Import pattern
 
 ```ts
-import {
-  GeoButtonComponent,
-  GeoInputComponent,
-  GeoFormModalComponent,
-  GeoStepperComponent,
-} from '@geoit/ui';
+import { GeoButtonComponent, GeoInputComponent, GeoFormModalComponent, GeoStepperComponent } from "@geoit/ui";
 ```
 
 Standalone consumers:
@@ -35,8 +38,8 @@ Standalone consumers:
 ## Styles (app once)
 
 ```scss
-@import 'node_modules/@geoit/ui/src/lib/styles/design-tokens.scss';
-@import 'node_modules/@geoit/ui/src/lib/styles/theme.scss';
+@import "node_modules/@geoit/ui/src/lib/styles/design-tokens.scss";
+@import "node_modules/@geoit/ui/src/lib/styles/theme.scss";
 ```
 
 ## Composition recipes
@@ -50,25 +53,32 @@ See [`recipes.md`](./recipes.md) for:
 
 ## Decision cheat-sheet
 
-| Need | Use |
-|------|-----|
-| CTA / actions | `geo-button` |
-| Text field | `geo-input` / `geo-textarea` |
-| Select | `geo-select` |
-| Exclusive options | `geo-radio` |
-| Checkbox | `geo-checkbox` |
-| Dialog form | `geo-form-modal` |
-| Confirm delete | `geo-confirm-modal` |
-| Multi-step in dialog | `geo-form-modal` + `geo-stepper` |
-| Multi-step full page | `geo-step-form-layout` |
-| Page heading | `geo-page-title` (+ `geo-breadcrumb`) |
-| Status pill | `geo-status-tag` |
-| Transient notice | `GeoToastService` / `geo-toast` |
-| Inline notice | `geo-alert` |
-| Upload drag-drop | `geo-upload` |
-| Compact file field | `geo-file-picker` |
-| Data grid | `geo-table` (+ toolbar/filter) |
-| Typography | `geo-typography` |
+| Need                 | Use                                   |
+| -------------------- | ------------------------------------- |
+| CTA / actions        | `geo-button`                          |
+| Text field           | `geo-input` / `geo-textarea`          |
+| Select               | `geo-select`                          |
+| Exclusive options    | `geo-radio`                           |
+| Checkbox             | `geo-checkbox`                        |
+| Dialog form          | `geo-form-modal`                      |
+| Confirm delete       | `geo-confirm-modal`                   |
+| Multi-step in dialog | `geo-form-modal` + `geo-stepper`      |
+| Multi-step full page | `geo-step-form-layout`                |
+| App shell (sider+header) | `geo-layout`                     |
+| Layout sidebar / header / footer | `geo-layout-sidebar` / `geo-layout-header` / `geo-layout-footer` |
+| Page heading         | `geo-page-title` (+ `geo-breadcrumb`) or `geo-page-header` |
+| Dashboard KPI / chart | `geo-stat-card` / `geo-chart` / `geo-dashboard` |
+| Login / forgot password | `geo-login` / `geo-forgot-password` |
+| Feedback form        | `geo-feedback-form`                   |
+| Overlap analysis     | `geo-overlap-result`                  |
+| Empty region         | `geo-empty-state`                     |
+| Status pill          | `geo-status-tag`                      |
+| Transient notice     | `GeoToastService` / `geo-toast`       |
+| Inline notice        | `geo-alert`                           |
+| Upload drag-drop     | `geo-upload`                          |
+| Compact file field   | `geo-file-picker`                     |
+| Data grid            | `geo-table` (+ toolbar/filter)        |
+| Typography           | `geo-typography`                      |
 
 ## Anti-patterns
 
@@ -80,7 +90,8 @@ See [`recipes.md`](./recipes.md) for:
 ## Catalog
 
 - Index: [`README.md`](./README.md)
-- Machine catalog: [`catalog.json`](./catalog.json)
-- Per component: [`components/`](./components/)
+- Machine catalog: [`catalog.json`](./catalog.json) (includes input types/defaults)
+- Per component: [`components/`](./components/) — full Inputs/Outputs tables
+- Recipes: [`recipes.md`](./recipes.md)
 
 Regenerate docs: `npm run ai:docs`

package/ai/README.md

@@ -10,21 +10,55 @@ Agent rules: [`AGENTS.md`](./AGENTS.md) · Recipes: [`recipes.md`](./recipes.md)
 | `geo-back-button` | navigation | Back navigation control (history or custom click). | [geo-back-button.md](./components/geo-back-button.md) |
 | `geo-breadcrumb` | navigation | Breadcrumb trail; last item active (primary). | [geo-breadcrumb.md](./components/geo-breadcrumb.md) |
 | `geo-button` | actions | Primary action button with brand/semantic colors and icons. | [geo-button.md](./components/geo-button.md) |
-| `geo-checkbox` | forms | Checkbox with label; supports CVA / ngModel. | [geo-checkbox.md](./components/geo-checkbox.md) |
+| `geo-chart` | other | GeoChartComponent | [geo-chart.md](./components/geo-chart.md) |
+| `geo-checkbox` | forms | Checkbox with label; bind with [(checked)] (not CVA/ngModel). | [geo-checkbox.md](./components/geo-checkbox.md) |
 | `geo-column-picker` | data | Column visibility picker for tables (optional persistence). | [geo-column-picker.md](./components/geo-column-picker.md) |
 | `geo-confirm-modal` | overlay | Confirm / danger dialog (destroy actions). | [geo-confirm-modal.md](./components/geo-confirm-modal.md) |
+| `geo-dashboard` | other | GeoDashboardComponent | [geo-dashboard.md](./components/geo-dashboard.md) |
 | `geo-date-picker` | forms | Single date (optional time) picker. | [geo-date-picker.md](./components/geo-date-picker.md) |
 | `geo-date-range-picker` | forms | Start–end date range picker. | [geo-date-range-picker.md](./components/geo-date-range-picker.md) |
+| `geo-empty-state` | other | GeoEmptyStateComponent | [geo-empty-state.md](./components/geo-empty-state.md) |
+| `geo-feedback-form` | other | GeoFeedbackFormComponent | [geo-feedback-form.md](./components/geo-feedback-form.md) |
 | `geo-file-picker` | forms | Compact file input for forms (button + filename). | [geo-file-picker.md](./components/geo-file-picker.md) |
+| `geo-forgot-password` | other | GeoForgotPasswordComponent | [geo-forgot-password.md](./components/geo-forgot-password.md) |
 | `geo-form-modal` | overlay | Form modal: fixed header/footer, scrollable body via ng-content. | [geo-form-modal.md](./components/geo-form-modal.md) |
 | `geo-icon` | display | Ant Design icon wrapper with GEO size/color tokens. | [geo-icon.md](./components/geo-icon.md) |
 | `geo-input` | forms | Text input with label, validation, icons; CVA/ngModel. | [geo-input.md](./components/geo-input.md) |
+| `geo-layout` | layout | App shell composing sidebar + header + content + footer. | [geo-layout.md](./components/geo-layout.md) |
+| `geo-layout-footer` | layout | Minimal layout footer with copyright text + content slot. | [geo-layout-footer.md](./components/geo-layout-footer.md) |
+| `geo-layout-header` | layout | Soft top bar: toggle + breadcrumb + user/notification actions. | [geo-layout-header.md](./components/geo-layout-header.md) |
+| `geo-layout-header-actions` | layout | Header actions: notification/subsystem icons + user chip with popovers. | [geo-layout-header-actions.md](./components/geo-layout-header-actions.md) |
+| `geo-layout-sidebar` | layout | White sidebar: brand + recursive menu (collapse / mobile drawer). | [geo-layout-sidebar.md](./components/geo-layout-sidebar.md) |
+| `geo-list-page` | other | GeoListPageComponent | [geo-list-page.md](./components/geo-list-page.md) |
+| `geo-login` | other | GeoLoginComponent | [geo-login.md](./components/geo-login.md) |
+| `geo-map` | map | OpenLayers map host with basemap, typed layers, and GeoMapController. | [geo-map.md](./components/geo-map.md) |
+| `geo-map-admin-filter` | other | GeoMapAdminFilterComponent | [geo-map-admin-filter.md](./components/geo-map-admin-filter.md) |
+| `geo-map-basemap-switcher` | other | GeoMapBasemapSwitcherComponent | [geo-map-basemap-switcher.md](./components/geo-map-basemap-switcher.md) |
+| `geo-map-help` | other | GeoMapHelpComponent | [geo-map-help.md](./components/geo-map-help.md) |
+| `geo-map-layer-card` | other | GeoMapLayerCardComponent | [geo-map-layer-card.md](./components/geo-map-layer-card.md) |
+| `geo-map-layer-panel` | other | GeoMapLayerPanelComponent | [geo-map-layer-panel.md](./components/geo-map-layer-panel.md) |
+| `geo-map-layers-drawer` | other | GeoMapLayersDrawerComponent | [geo-map-layers-drawer.md](./components/geo-map-layers-drawer.md) |
+| `geo-map-legend` | other | GeoMapLegendComponent | [geo-map-legend.md](./components/geo-map-legend.md) |
+| `geo-map-locate` | other | GeoMapLocateComponent | [geo-map-locate.md](./components/geo-map-locate.md) |
+| `geo-map-location-chip` | other | GeoMapLocationChipComponent | [geo-map-location-chip.md](./components/geo-map-location-chip.md) |
+| `geo-map-measure` | other | GeoMapMeasureComponent | [geo-map-measure.md](./components/geo-map-measure.md) |
+| `geo-map-opacity` | other | GeoMapOpacityComponent | [geo-map-opacity.md](./components/geo-map-opacity.md) |
+| `geo-map-parcel-popup` | other | GeoMapParcelPopupComponent | [geo-map-parcel-popup.md](./components/geo-map-parcel-popup.md) |
+| `geo-map-search` | other | GeoMapSearchComponent | [geo-map-search.md](./components/geo-map-search.md) |
+| `geo-map-shell` | other | GeoMapShellComponent | [geo-map-shell.md](./components/geo-map-shell.md) |
+| `geo-map-snapshot` | other | GeoMapSnapshotComponent | [geo-map-snapshot.md](./components/geo-map-snapshot.md) |
+| `geo-map-swipe` | other | GeoMapSwipeComponent | [geo-map-swipe.md](./components/geo-map-swipe.md) |
+| `geo-map-toolbar` | other | GeoMapToolbarComponent | [geo-map-toolbar.md](./components/geo-map-toolbar.md) |
+| `geo-map-zoom` | other | GeoMapZoomComponent | [geo-map-zoom.md](./components/geo-map-zoom.md) |
+| `geo-overlap-result` | other | GeoOverlapResultComponent | [geo-overlap-result.md](./components/geo-overlap-result.md) |
+| `geo-page-header` | other | GeoPageHeaderComponent | [geo-page-header.md](./components/geo-page-header.md) |
 | `geo-page-title` | display | Page title (uppercase) with short primary accent underline; uses geo-typography. | [geo-page-title.md](./components/geo-page-title.md) |
 | `geo-pagination` | navigation | Standalone pagination control. | [geo-pagination.md](./components/geo-pagination.md) |
 | `geo-radio` | forms | Radio group (horizontal/vertical or button style). | [geo-radio.md](./components/geo-radio.md) |
 | `geo-row-actions` | data | Row action icons/menu (edit, more, custom). | [geo-row-actions.md](./components/geo-row-actions.md) |
 | `geo-select` | forms | Select / multi-select dropdown. | [geo-select.md](./components/geo-select.md) |
 | `geo-slider` | forms | Numeric range slider. | [geo-slider.md](./components/geo-slider.md) |
+| `geo-stat-card` | other | GeoStatCardComponent | [geo-stat-card.md](./components/geo-stat-card.md) |
 | `geo-status-tag` | display | Pill status tag with optional dot (success/error/warning/info/teal/…). | [geo-status-tag.md](./components/geo-status-tag.md) |
 | `geo-step-form-layout` | layout | Full-page multi-step form: vertical stepper + content card + footer actions. | [geo-step-form-layout.md](./components/geo-step-form-layout.md) |
 | `geo-stepper` | navigation | Steps indicator (horizontal default). Active=primary, completed=success+check. | [geo-stepper.md](./components/geo-stepper.md) |
@@ -39,6 +73,6 @@ Agent rules: [`AGENTS.md`](./AGENTS.md) · Recipes: [`recipes.md`](./recipes.md)
 | `geo-typography` | display | Text with GEO type scale (h1–tiny) and semantic colors. | [geo-typography.md](./components/geo-typography.md) |
 | `geo-upload` | forms | Drag-drop upload zone with progress list. | [geo-upload.md](./components/geo-upload.md) |
 
-Generated: 2026-07-27T01:27:04.549Z
+Generated: 2026-08-24T03:07:52.099Z
 
 Regenerate: `npm run ai:docs`