@geoit/ui 0.0.2 → 0.0.4

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,150 @@ 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';
 ```
 
-## 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 **6px**)
+
+## 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>
+```
+
+### 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-slider`
+
+`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, docs live in `node_modules/@geoit/ui/ai/`:
+After install:
 
 | 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/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 docs |
-| `node_modules/@geoit/ui/ai/recipes.md` | Copy-paste recipes |
+| `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
+```
 
-### Consumer Cursor rule (recommended)
+### Cursor rule (recommended)
 
-Create `.cursor/rules/geo-ui.mdc` in your app:
+`.cursor/rules/geo-ui.mdc` in your app:
 
 ```md
 ---
@@ -43,4 +165,18 @@ UI must use `@geoit/ui`. Before writing UI, read:
 - 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` (6px) |
+| Font | `--geo-font-family` |
+
+TypeScript mirror: `geoColorTokens` from `@geoit/ui` (via styles/tokens export).
+
+## License
+
+Internal / project license — see repository.

package/ai/AGENTS.md

@@ -9,8 +9,8 @@ Instructions for AI coding agents (Cursor, Copilot, etc.) when building UI with
 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.
+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.
 
 ## Import pattern
 
@@ -80,7 +80,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,7 +10,7 @@ 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-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-date-picker` | forms | Single date (optional time) picker. | [geo-date-picker.md](./components/geo-date-picker.md) |
@@ -39,6 +39,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-07-27T01:57:41.109Z
 
 Regenerate: `npm run ai:docs`