@geoit/ui 0.0.2 → 0.0.5

package/ai/components/geo-alert.md

@@ -1,16 +1,23 @@
 # geo-alert
 
-> AI quick reference for **GeoAlertComponent**
+> Complete usage reference for **GeoAlertComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Inline alert banner (success/error/warning/info).
 
 ## Import
+
 ```ts
 import { GeoAlertComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoAlertComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoAlertComponent]
+```
 
 ## Selector
 `geo-alert`
@@ -24,33 +31,80 @@ Form-level or page-level status messages that stay in layout.
 ## Do not use when
 Transient notifications — use geo-toast / GeoToastService.
 
+## How to use
+
+Hiển thị banner trạng thái cố định trong layout (form/page). Dùng type success|error|warning|info; đóng qua closable + (closed).
+
+## Binding
+
+Standalone component — drive via Inputs (`input()` / `model()`) and Outputs (`output()`). Banana bindings work for any `model()` fields (e.g. `[(open)]`, `[(pageIndex)]`).
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `type` | See component TS / Storybook Controls |
-| `title` | See component TS / Storybook Controls |
-| `message` | See component TS / Storybook Controls |
-| `closable` | See component TS / Storybook Controls |
-| `visible` | See component TS / Storybook Controls |
-| `showIcon` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | `'info'` | — |
+| `title` | `string` | `''` | — |
+| `message` | `string` | `''` | — |
+| `closable` | `boolean` | `true` | — |
+| `visible` | `boolean` | `true` | Two-way `model()` (supports banana binding). |
+| `showIcon` | `boolean` | `true` | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `closed` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `closed` | `OutputEmitterRef<void>` | — |
+
+## Related types
+
+From `figma/geo-alert/geo-alert.types.ts`:
+
+```ts
+export type GeoAlertType = 'success' | 'error' | 'warning' | 'info';
+```
+
+## Examples
+
+### Basic
+
 ```html
-<geo-alert type="success" title="Thành công" message="Đã lưu."></geo-alert>
+<geo-alert type="success" title="Thành công" message="Đã lưu hồ sơ."></geo-alert>
 ```
 
+### Full options
+
+```html
+<geo-alert
+  type="warning"
+  title="Cảnh báo"
+  message="Vui lòng kiểm tra lại thông tin trước khi gửi."
+  [closable]="true"
+  [visible]="showAlert"
+  [showIcon]="true"
+  (closed)="showAlert = false"
+></geo-alert>
+```
+
+## Tips
+
+- Toast tạm thời → GeoToastService / geo-toast; alert là inline persistent.
+- Gắn [visible] nếu cần ẩn/hiện từ component cha.
+- title + message dùng tiếng Việt ngắn gọn.
+## Related components
+
+- [`geo-toast`](./geo-toast.md)
+- [`geo-icon`](./geo-icon.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-alert.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-alert/geo-alert.component.ts`
 
-## Storybook
-GEO / related story for `geo-alert`
-
-## Rules for AI
-- Prefer this component over raw ng-zorro / HTML equivalents for the same UI role.
+## Rules for AI / consumers
+- Prefer this component over raw ng-zorro / HTML for the same UI role.
 - Use design tokens (`var(--geo-*)`) — never hardcode brand colors or radius.
-- Match props to Storybook Controls / this doc; do not invent unsupported inputs.
+- Match props exactly to the Inputs table; do not invent unsupported inputs.
+- Copy examples and adapt labels/bindings only.

package/ai/components/geo-back-button.md

@@ -1,16 +1,23 @@
 # geo-back-button
 
-> AI quick reference for **GeoBackButtonComponent**
+> Complete usage reference for **GeoBackButtonComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Back navigation control (history or custom click).
 
 ## Import
+
 ```ts
 import { GeoBackButtonComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoBackButtonComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoBackButtonComponent]
+```
 
 ## Selector
 `geo-back-button`
@@ -24,31 +31,70 @@ Detail/edit pages that return to a list.
 ## Do not use when
 Primary CTA — use geo-button.
 
+## How to use
+
+Nút quay lại trên trang chi tiết/sửa. Mặc định historyBack=true; hoặc lắng nghe (clicked) để điều hướng tùy chỉnh.
+
+## Binding
+
+Standalone component — drive via Inputs (`input()` / `model()`) and Outputs (`output()`). Banana bindings work for any `model()` fields (e.g. `[(open)]`, `[(pageIndex)]`).
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `ariaLabel` | See component TS / Storybook Controls |
-| `title` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `historyBack` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `ariaLabel` | `string` | `'Quay lại'` | — |
+| `title` | `string` | `'Quay lại'` | — |
+| `disabled` | `boolean` | `false` | — |
+| `historyBack` | `boolean` | `true` | `true` (mặc định): `Location.back()` — về trang trước trong history. |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `clicked` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `clicked` | `OutputEmitterRef<MouseEvent>` | — |
+
+
+## Examples
+
+### Basic
+
 ```html
 <geo-back-button (clicked)="goBack()"></geo-back-button>
 ```
 
+### Full options
+
+```html
+<geo-back-button
+  title="Quay lại danh sách"
+  ariaLabel="Quay lại danh sách"
+  [historyBack]="false"
+  [disabled]="saving"
+  (clicked)="router.navigate(['/danh-sach'])"
+></geo-back-button>
+```
+
+## Tips
+
+- CTA chính → geo-button, không dùng back-button.
+- Đặt title/ariaLabel tiếng Việt (mặc định 'Quay lại').
+- Tắt historyBack và xử lý (clicked) khi dùng router.navigate.
+## Related components
+
+- [`geo-button`](./geo-button.md)
+- [`geo-page-title`](./geo-page-title.md)
+- [`geo-breadcrumb`](./geo-breadcrumb.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-back-button.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-back-button/geo-back-button.component.ts`
 
-## Storybook
-GEO / related story for `geo-back-button`
-
-## Rules for AI
-- Prefer this component over raw ng-zorro / HTML equivalents for the same UI role.
+## Rules for AI / consumers
+- Prefer this component over raw ng-zorro / HTML for the same UI role.
 - Use design tokens (`var(--geo-*)`) — never hardcode brand colors or radius.
-- Match props to Storybook Controls / this doc; do not invent unsupported inputs.
+- Match props exactly to the Inputs table; do not invent unsupported inputs.
+- Copy examples and adapt labels/bindings only.

package/ai/components/geo-breadcrumb.md

@@ -1,16 +1,23 @@
 # geo-breadcrumb
 
-> AI quick reference for **GeoBreadcrumbComponent**
+> Complete usage reference for **GeoBreadcrumbComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Breadcrumb trail; last item active (primary).
 
 ## Import
+
 ```ts
 import { GeoBreadcrumbComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoBreadcrumbComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoBreadcrumbComponent]
+```
 
 ## Selector
 `geo-breadcrumb`
@@ -24,15 +31,47 @@ Page hierarchy under page title.
 ## Do not use when
 Primary navigation / sidebar menus.
 
+## How to use
+
+Đường dẫn phân cấp trang. Truyền [items] dạng { label, link? }; mục cuối là active (không cần link).
+
+## Binding
+
+Standalone component — drive via Inputs (`input()` / `model()`) and Outputs (`output()`). Banana bindings work for any `model()` fields (e.g. `[(open)]`, `[(pageIndex)]`).
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `items` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `items` | `GeoBreadcrumbItem[]` | `[]` | — |
 
 ## Outputs
+
 _None_
 
-## Example
+## Related types
+
+From `figma/geo-breadcrumb/geo-breadcrumb.types.ts`:
+
+```ts
+export interface GeoBreadcrumbItem {
+  /** Hiển thị trên breadcrumb. */
+  label: string;
+  /** Router link (optional) — bỏ trống = không phải link. */
+  link?: string | string[];
+  /** Query params khi dùng routerLink. */
+  queryParams?: Record<string, string | number | boolean>;
+  /** Đánh dấu item hiện tại (thường là item cuối). */
+  active?: boolean;
+}
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-breadcrumb [items]="[
   { label: 'Trang chủ', link: '/' },
@@ -40,13 +79,33 @@ _None_
 ]"></geo-breadcrumb>
 ```
 
+### Full options
+
+```html
+<geo-breadcrumb [items]="[
+  { label: 'Trang chủ', link: '/' },
+  { label: 'Tra cứu hồ sơ', link: '/tra-cuu' },
+  { label: 'Xem chi tiết hồ sơ' }
+]"></geo-breadcrumb>
+```
+
+## Tips
+
+- Thường đặt trên geo-page-title.
+- Không dùng cho menu sidebar.
+- label tiếng Việt; link là route path.
+## Related components
+
+- [`geo-page-title`](./geo-page-title.md)
+- [`geo-back-button`](./geo-back-button.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-breadcrumb.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-breadcrumb/geo-breadcrumb.component.ts`
 
-## Storybook
-GEO / related story for `geo-breadcrumb`
-
-## Rules for AI
-- Prefer this component over raw ng-zorro / HTML equivalents for the same UI role.
+## Rules for AI / consumers
+- Prefer this component over raw ng-zorro / HTML for the same UI role.
 - Use design tokens (`var(--geo-*)`) — never hardcode brand colors or radius.
-- Match props to Storybook Controls / this doc; do not invent unsupported inputs.
+- Match props exactly to the Inputs table; do not invent unsupported inputs.
+- Copy examples and adapt labels/bindings only.

package/ai/components/geo-button.md

@@ -1,16 +1,23 @@
 # geo-button
 
-> AI quick reference for **GeoButtonComponent**
+> Complete usage reference for **GeoButtonComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Primary action button with brand/semantic colors and icons.
 
 ## Import
+
 ```ts
 import { GeoButtonComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoButtonComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoButtonComponent]
+```
 
 ## Selector
 `geo-button`
@@ -24,40 +31,96 @@ All CTAs, form submit/cancel, toolbar actions.
 ## Do not use when
 Do not use raw ant-btn or native button for branded UI.
 
+## How to use
+
+CTA chính của GEO UI. appearance primary|secondary|tertiary; color brand|danger|warning|success; icon Ant Design qua [icon].
+
+## Binding
+
+Standalone component — drive via Inputs (`input()` / `model()`) and Outputs (`output()`). Banana bindings work for any `model()` fields (e.g. `[(open)]`, `[(pageIndex)]`).
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `appearance` | See component TS / Storybook Controls |
-| `color` | See component TS / Storybook Controls |
-| `icon` | See component TS / Storybook Controls |
-| `iconTheme` | See component TS / Storybook Controls |
-| `iconPlacement` | See component TS / Storybook Controls |
-| `iconOnly` | See component TS / Storybook Controls |
-| `type` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `tooltip` | See component TS / Storybook Controls |
-| `tooltipPlacement` | See component TS / Storybook Controls |
-| `active` | See component TS / Storybook Controls |
-| `title` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `appearance` | `'primary' \| 'secondary' \| 'tertiary'` | `'primary'` | — |
+| `color` | `'brand' \| 'danger' \| 'warning' \| 'success'` | `'brand'` | — |
+| `icon` | `string \| undefined` | `undefined` | — |
+| `iconTheme` | `'outline' \| 'fill' \| 'twotone'` | `'outline'` | — |
+| `iconPlacement` | `'start' \| 'end'` | `'start'` | Vị trí icon: `start` (trái) hoặc `end` (phải). |
+| `iconOnly` | `boolean` | `false` | — |
+| `type` | `'button' \| 'submit'` | `'button'` | — |
+| `disabled` | `boolean` | `false` | — |
+| `tooltip` | `string` | `''` | Tooltip Ant Design (`nz-tooltip`). Ưu tiên hơn `title` native. |
+| `tooltipPlacement` | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'le…` | `'top'` | — |
+| `active` | `boolean` | `false` | Trạng thái active (vd. toolbar toggle đang bật). |
+| `title` | `string` | `''` | Native `title` — fallback khi không set `tooltip`. |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `clicked` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `clicked` | `OutputEmitterRef<MouseEvent>` | — |
+
+## Related types
+
+From `figma/geo-button/geo-button.types.ts`:
+
+```ts
+export type GeoButtonAppearance = 'primary' | 'secondary' | 'tertiary';
+
+export type GeoButtonColor = 'brand' | 'danger' | 'warning' | 'success';
+
+export type GeoButtonTooltipPlacement = 'top' | 'left' | 'right' | 'bottom' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'leftTop' | 'leftBottom' | 'rightTop' | 'rightBottom';
+```
+
+## Examples
+
+### Basic
+
 ```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>
 ```
 
+### Full options
+
+```html
+<geo-button
+  appearance="primary"
+  color="brand"
+  icon="right"
+  iconTheme="outline"
+  iconPlacement="end"
+  type="submit"
+  tooltip="Lưu và tiếp tục"
+  tooltipPlacement="top"
+  [disabled]="saving"
+  (clicked)="onSave()"
+>Tiếp theo</geo-button>
+
+<geo-button appearance="secondary" color="danger" icon="delete" [iconOnly]="true" tooltip="Xóa"></geo-button>
+```
+
+## Tips
+
+- Không dùng ant-btn / <button> raw cho UI brand.
+- iconPlacement start|end; iconOnly cho toolbar icon.
+- Dùng tooltip thay title native khi cần hover text.
+## Related components
+
+- [`geo-icon`](./geo-icon.md)
+- [`geo-form-modal`](./geo-form-modal.md)
+- [`geo-confirm-modal`](./geo-confirm-modal.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-button.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-button/geo-button.component.ts`
 
-## Storybook
-GEO / related story for `geo-button`
-
-## Rules for AI
-- Prefer this component over raw ng-zorro / HTML equivalents for the same UI role.
+## Rules for AI / consumers
+- Prefer this component over raw ng-zorro / HTML for the same UI role.
 - Use design tokens (`var(--geo-*)`) — never hardcode brand colors or radius.
-- Match props to Storybook Controls / this doc; do not invent unsupported inputs.
+- Match props exactly to the Inputs table; do not invent unsupported inputs.
+- Copy examples and adapt labels/bindings only.

package/ai/components/geo-chart.md

@@ -0,0 +1,103 @@
+# geo-chart
+
+> Complete usage reference for **GeoChartComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
+
+## Summary
+GeoChartComponent
+
+## Import
+
+```ts
+import { GeoChartComponent } from '@geoit/ui';
+```
+
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoChartComponent]
+```
+
+## Selector
+`geo-chart`
+
+## Category
+`other`
+
+## When to use
+—
+
+## Do not use when
+—
+
+
+## Binding
+
+Standalone component — drive via Inputs (`input()` / `model()`) and Outputs (`output()`). Banana bindings work for any `model()` fields (e.g. `[(open)]`, `[(pageIndex)]`).
+
+## Inputs
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | `'bar' \| 'donut'` | `'bar'` | — |
+| `title` | `string` | `''` | — |
+| `data` | `GeoChartDatum[]` | `[]` | — |
+| `height` | `number` | `260` | — |
+| `showLegend` | `boolean` | `true` | — |
+| `showSort` | `boolean` | `false` | — |
+| `sort` | `'none' \| 'asc' \| 'desc'` | `'desc'` | Two-way `model()` (supports banana binding). |
+| `emptyText` | `string` | `'Chưa có dữ liệu thống kê.'` | — |
+| `unit` | `string` | `''` | — |
+
+## Outputs
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `segmentClick` | `OutputEmitterRef<GeoChartSegmentClick>` | — |
+| `sortChange` | `OutputEmitterRef<'none' \| 'asc' \| 'desc'>` | — |
+
+## Related types
+
+From `figma/geo-chart/geo-chart.types.ts`:
+
+```ts
+export interface GeoChartDatum {
+  id?: string;
+  label: string;
+  value: number;
+  /** Optional CSS color; prefer design tokens when possible. */
+  color?: string;
+}
+
+export interface GeoChartSegmentClick {
+  datum: GeoChartDatum;
+  index: number;
+}
+
+export type GeoChartType = 'bar' | 'donut';
+
+export type GeoChartSort = 'none' | 'asc' | 'desc';
+```
+
+## Examples
+
+### Example
+
+```html
+<geo-chart></geo-chart>
+```
+
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-chart.md`
+
+## Source
+`projects/geo-ui/src/lib/figma/geo-chart/geo-chart.component.ts`
+
+## Rules for AI / consumers
+- Prefer this component over raw ng-zorro / HTML for the same UI role.
+- Use design tokens (`var(--geo-*)`) — never hardcode brand colors or radius.
+- Match props exactly to the Inputs table; do not invent unsupported inputs.
+- Copy examples and adapt labels/bindings only.