@geoit/ui 0.0.2 → 0.0.5

package/ai/components/geo-toast.md

@@ -1,16 +1,24 @@
 # geo-toast
 
-> AI quick reference for **GeoToastComponent**
+> Complete usage reference for **GeoToastComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Toast UI; prefer GeoToastService for app-wide notifications.
 
 ## Import
+
 ```ts
-import { GeoToastComponent } from '@geoit/ui';
+import { GeoToastComponent, GeoToastService } from '@geoit/ui';
+// Inject GeoToastService via constructor — providedIn: 'root'
 ```
 
-Standalone component — add to `imports: [GeoToastComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoToastComponent]
+```
 
 ## Selector
 `geo-toast`
@@ -24,38 +32,141 @@ Transient success/error after actions.
 ## Do not use when
 Persistent inline messages — use geo-alert.
 
+## How to use
+
+Thông báo tạm thời. Ưu tiên inject GeoToastService (success/error/warning/info). Component geo-toast chỉ khi cần render tĩ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 |
-|-------|-------|
-| `type` | See component TS / Storybook Controls |
-| `title` | See component TS / Storybook Controls |
-| `message` | See component TS / Storybook Controls |
-| `closable` | See component TS / Storybook Controls |
-| `showIcon` | See component TS / Storybook Controls |
-| `visible` | See component TS / Storybook Controls |
-| `icon` | 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` | — |
+| `showIcon` | `boolean` | `true` | — |
+| `visible` | `boolean` | `true` | Two-way `model()` (supports banana binding). |
+| `icon` | `string \| undefined` | `undefined` | Override Ant Design icon type. |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `closed` | EventEmitter |
 
-## Example
-```html
-// Preferred
-this.toast.success('Thành công!', 'Đã lưu hồ sơ.');
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `closed` | `OutputEmitterRef<void>` | — |
+
+## Related types
+
+From `figma/geo-toast/geo-toast.types.ts`:
+
+```ts
+export interface GeoToastOptions {
+  /** Auto close duration (ms). `0` = không tự đóng. Default `4500`. */
+  duration?: number;
+  /** Vị trí toast. Default `topRight`. */
+  placement?: GeoToastPlacement;
+  /** Pause countdown khi hover. Default `true`. */
+  pauseOnHover?: boolean;
+  /** Animate enter/leave. Default `true`. */
+  animate?: boolean;
+  /** Unique key — toast cùng key sẽ được thay thế. */
+  key?: string;
+  /** Hiện icon trạng thái. Default `true`. */
+  showIcon?: boolean;
+  /** Hiện nút đóng. Default `true`. */
+  closable?: boolean;
+  /** Custom icon type (Ant Design). */
+  icon?: string;
+  /** Inline style trên notice. */
+  style?: NgStyleInterface;
+  /** Extra CSS class. */
+  className?: NgClassInterface | string;
+  /** Arbitrary data gắn vào notice. */
+  data?: unknown;
+}
+
+export interface GeoToastConfig extends GeoToastOptions {
+  type: GeoToastType;
+  title?: string;
+  message?: string;
+}
+
+export interface GeoToastGlobalConfig {
+  duration?: number;
+  placement?: GeoToastPlacement;
+  pauseOnHover?: boolean;
+  animate?: boolean;
+  maxStack?: number;
+  top?: number;
+  bottom?: number;
+}
+
+export type GeoToastType = 'success' | 'error' | 'warning' | 'info';
 
-// Or static
-<geo-toast type="success" title="Thành công!" message="Đã lưu."></geo-toast>
+export type GeoToastPlacement = NzNotificationPlacement;
 ```
 
+## Examples
+
+### Service (preferred)
+
+```ts
+import { GeoToastService } from '@geoit/ui';
+
+constructor(private toast: GeoToastService) {}
+
+save(): void {
+  this.toast.success('Thành công!', 'Đã lưu hồ sơ.');
+}
+
+fail(): void {
+  this.toast.error('Lỗi!', 'Không thể lưu.', { duration: 0 });
+}
+
+warn(): void {
+  this.toast.warning('Cảnh báo!', 'Dữ liệu chưa đầy đủ.');
+}
+
+info(): void {
+  this.toast.info('Thông báo', 'Hệ thống sẽ bảo trì lúc 22:00.');
+}
+```
+
+### Static template
+
+```html
+<geo-toast
+  type="success"
+  title="Thành công!"
+  message="Đã lưu."
+  [closable]="true"
+  [showIcon]="true"
+  [visible]="true"
+></geo-toast>
+```
+
+## Tips
+
+- Inline persistent → geo-alert.
+- duration: 0 để toast không tự đóng.
+- Import GeoToastService từ @geoit/ui (providedIn root).
+## Related components
+
+- [`geo-alert`](./geo-alert.md)
+- [`geo-confirm-modal`](./geo-confirm-modal.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-toast.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-toast/geo-toast.component.ts`
 
-## Storybook
-GEO / related story for `geo-toast`
-
-## 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-tree.md

@@ -1,16 +1,23 @@
 # geo-tree
 
-> AI quick reference for **GeoTreeComponent**
+> Complete usage reference for **GeoTreeComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Tree view with checkable / expandable nodes.
 
 ## Import
+
 ```ts
 import { GeoTreeComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoTreeComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoTreeComponent]
+```
 
 ## Selector
 `geo-tree`
@@ -24,35 +31,100 @@ Hierarchy selection (org, folder, category).
 ## Do not use when
 Flat lists — use geo-table or select.
 
+## How to use
+
+Cây phân cấp. [nodes] GeoTreeNode[]; bật checkable + [(checkedKeys)]; [(expandedKeys)]; (nodeClick).
+
+## 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 |
-|-------|-------|
-| `nodes` | See component TS / Storybook Controls |
-| `checkable` | See component TS / Storybook Controls |
-| `checkedKeys` | See component TS / Storybook Controls |
-| `expandedKeys` | See component TS / Storybook Controls |
-| `showLine` | See component TS / Storybook Controls |
-| `blockNode` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `nodes` | `GeoTreeNode[]` | `[]` | — |
+| `checkable` | `boolean` | `false` | — |
+| `checkedKeys` | `Array<string \| number>` | `[]` | Two-way `model()` (supports banana binding). |
+| `expandedKeys` | `Array<string \| number>` | `[]` | Two-way `model()` (supports banana binding). |
+| `showLine` | `boolean` | `false` | — |
+| `blockNode` | `boolean` | `false` | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `checkedKeysChange` | EventEmitter |
-| `expandedKeysChange` | EventEmitter |
-| `nodeClick` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `nodeClick` | `OutputEmitterRef<NzFormatEmitEvent>` | — |
+
+## Related types
+
+From `figma/geo-tree/geo-tree.types.ts`:
+
+```ts
+export interface GeoTreeNode {
+  key: string;
+  title: string;
+  expanded?: boolean;
+  children?: GeoTreeNode[];
+  isLeaf?: boolean;
+  disabled?: boolean;
+  disableCheckbox?: boolean;
+  /** Payload tùy chọn (domain gắn data nghiệp vụ). */
+  data?: unknown;
+  [prop: string]: unknown;
+}
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-tree [nodes]="nodes" [checkable]="true" [(checkedKeys)]="checked"></geo-tree>
 ```
 
+### Full options
+
+```html
+<geo-tree
+  [nodes]="[
+    {
+      title: 'Đơn vị gốc',
+      key: 'root',
+      children: [
+        { title: 'Phòng A', key: 'a' },
+        { title: 'Phòng B', key: 'b' }
+      ]
+    }
+  ]"
+  [checkable]="true"
+  [(checkedKeys)]="checkedKeys"
+  [(expandedKeys)]="expandedKeys"
+  [showLine]="true"
+  [blockNode]="true"
+  (nodeClick)="onNode($event)"
+></geo-tree>
+```
+
+## Tips
+
+- nodes: { title, key, children? }[].
+- showLine / blockNode theo design cần thiết.
+- Không dùng thay select đơn giản.
+## Related components
+
+- [`geo-checkbox`](./geo-checkbox.md)
+- [`geo-select`](./geo-select.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-tree.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-tree/geo-tree.component.ts`
 
-## Storybook
-GEO / related story for `geo-tree`
-
-## 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-typography.md

@@ -1,16 +1,23 @@
 # geo-typography
 
-> AI quick reference for **GeoTypographyComponent**
+> Complete usage reference for **GeoTypographyComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Text with GEO type scale (h1–tiny) and semantic colors.
 
 ## Import
+
 ```ts
 import { GeoTypographyComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoTypographyComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoTypographyComponent]
+```
 
 ## Selector
 `geo-typography`
@@ -24,34 +31,78 @@ All readable text; prefer over raw h1/p with custom CSS.
 ## Do not use when
 Do not hardcode font-size/color — use variant/color props.
 
+## How to use
+
+Text theo type scale GEO. variant h1–h4|subtitle|body|body-small|caption|…; color semantic; strong/underline/mark/code.
+
+## 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 |
-|-------|-------|
-| `variant` | See component TS / Storybook Controls |
-| `color` | See component TS / Storybook Controls |
-| `strong` | See component TS / Storybook Controls |
-| `underline` | See component TS / Storybook Controls |
-| `delete` | See component TS / Storybook Controls |
-| `mark` | See component TS / Storybook Controls |
-| `code` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `variant` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'subtitle' \| 'body' \| 'body-small' \| 'caption' \| 'overline' \| 'tiny'` | `'body'` | Type scale variant from the design system. |
+| `color` | `'default' \| 'secondary' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'disabled'` | `'default'` | Semantic text color. |
+| `strong` | `boolean` | `false` | Force bold weight (overrides variant weight when true). |
+| `underline` | `boolean` | `false` | Underline text decoration. |
+| `delete` | `boolean` | `false` | Strikethrough text decoration. |
+| `mark` | `boolean` | `false` | Mark / highlight background. |
+| `code` | `boolean` | `false` | Monospace code appearance. |
+| `disabled` | `boolean` | `false` | Disabled appearance |
 
 ## Outputs
+
 _None_
 
-## Example
+## Related types
+
+From `figma/geo-typography/geo-typography.types.ts`:
+
+```ts
+export type GeoTypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'subtitle' | 'body' | 'body-small' | 'caption' | 'overline' | 'tiny';
+
+export type GeoTypographyColor = 'default' | 'secondary' | 'primary' | 'success' | 'warning' | 'danger' | 'disabled';
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-typography variant="h3">Tiêu đề</geo-typography>
 <geo-typography variant="body" color="secondary">Mô tả phụ</geo-typography>
 ```
 
+### Full options
+
+```html
+<geo-typography variant="h4" [strong]="true">1. Thông tin cá nhân</geo-typography>
+<geo-typography variant="body" color="primary" [underline]="true">Xem chi tiết</geo-typography>
+<geo-typography variant="caption" color="danger">Trường bắt buộc</geo-typography>
+<geo-typography variant="body-small" [code]="true">HS-2024-001</geo-typography>
+```
+
+## Tips
+
+- Tiêu đề trang có gạch nhấn → geo-page-title.
+- color: default|secondary|primary|success|warning|danger|disabled.
+- Không hardcode font-size — dùng variant.
+## Related components
+
+- [`geo-page-title`](./geo-page-title.md)
+- [`geo-status-tag`](./geo-status-tag.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-typography.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-typography/geo-typography.component.ts`
 
-## Storybook
-GEO / related story for `geo-typography`
-
-## 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-upload.md

@@ -1,16 +1,23 @@
 # geo-upload
 
-> AI quick reference for **GeoUploadComponent**
+> Complete usage reference for **GeoUploadComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Drag-drop upload zone with progress list.
 
 ## Import
+
 ```ts
 import { GeoUploadComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoUploadComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoUploadComponent]
+```
 
 ## Selector
 `geo-upload`
@@ -24,40 +31,69 @@ Multi-file upload with progress UI.
 ## Do not use when
 Simple one-file form field — use geo-file-picker.
 
+## How to use
+
+Vùng kéo-thả upload + danh sách tiến độ. accept/maxSize; [(fileList)]; (change)/(remove)/(reject). Form gọn một file → geo-file-picker.
+
+## 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 |
-|-------|-------|
-| `action` | See component TS / Storybook Controls |
-| `accept` | See component TS / Storybook Controls |
-| `maxSize` | See component TS / Storybook Controls |
-| `multiple` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `error` | See component TS / Storybook Controls |
-| `errorMessage` | See component TS / Storybook Controls |
-| `hint` | See component TS / Storybook Controls |
-| `titlePrefix` | See component TS / Storybook Controls |
-| `selectText` | See component TS / Storybook Controls |
-| `titleSuffix` | See component TS / Storybook Controls |
-| `listTitle` | See component TS / Storybook Controls |
-| `showListTitle` | See component TS / Storybook Controls |
-| `fileList` | See component TS / Storybook Controls |
-| `headers` | See component TS / Storybook Controls |
-| `data` | See component TS / Storybook Controls |
-| `name` | See component TS / Storybook Controls |
-| `withCredentials` | See component TS / Storybook Controls |
-| `directory` | See component TS / Storybook Controls |
-| `customRequest` | See component TS / Storybook Controls |
-| `beforeUpload` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `action` | `string \| ((file: NzUploadFile) => string \| Observable<string>)` | `''` | Upload endpoint — bỏ trống nếu dùng `customRequest` / chỉ chọn file local. |
+| `accept` | `string` | `'.png,.jpg,.jpeg,.svg'` | — |
+| `maxSize` | — | `1024 * 1024` | Max size (bytes). Default 1MB. `0` = không giới hạn. |
+| `multiple` | `boolean` | `true` | — |
+| `disabled` | `boolean` | `false` | — |
+| `error` | `boolean` | `false` | — |
+| `errorMessage` | `string` | `''` | — |
+| `hint` | `string` | `'Chỉ cho phép file dạng .png, .jpg, .jpeg, .svg và dung lượng không quá 1Mb'` | — |
+| `titlePrefix` | `string` | `'Kéo thả ảnh hoặc'` | — |
+| `selectText` | `string` | `'Chọn file'` | — |
+| `titleSuffix` | `string` | `'để tải lên'` | — |
+| `listTitle` | `string` | `'Tập tin đính kèm'` | — |
+| `showListTitle` | `boolean` | `true` | — |
+| `fileList` | `GeoUploadFile[]` | `[]` | Controlled file list. — Two-way `model()` (supports banana binding). |
+| `headers` | `{} \| ((file: NzUploadFile) => {} \| Observable<{}>) \| undefined` | `undefined` | — |
+| `data` | `{} \| ((file: NzUploadFile) => {} \| Observable<{}>) \| undefined` | `undefined` | — |
+| `name` | `string` | `'file'` | — |
+| `withCredentials` | `boolean` | `false` | — |
+| `directory` | `boolean` | `false` | — |
+| `customRequest` | `GeoUploadCustomRequest \| undefined` | `undefined` | Custom XHR — mặc định simulate progress khi không có `action`. |
+| `beforeUpload` | `((file: NzUploadFile, fileList: NzUploadFile[]) => boolean \| Observable<boolean>) \| undefined` | `undefined` | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `fileListChange` | EventEmitter |
-| `change` | EventEmitter |
-| `remove` | EventEmitter |
-| `reject` | EventEmitter |
-
-## Example
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `change` | `OutputEmitterRef<NzUploadChangeParam>` | — |
+| `remove` | `OutputEmitterRef<GeoUploadFile>` | — |
+| `reject` | `OutputEmitterRef<{ file: File; reason: 'type' \| 'size' }>` | — |
+
+## Related types
+
+From `figma/geo-upload/geo-upload.types.ts`:
+
+```ts
+export interface GeoUploadFile extends NzUploadFile {
+  /** Bytes uploaded so far (for "100Kb / 200Kb"). */
+  loaded?: number;
+  /** Upload speed in bytes/sec (for "870kb/sec"). */
+  speed?: number;
+}
+
+export type GeoUploadCustomRequest = (item: NzUploadXHRArgs) => Subscription;
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-upload
   accept=".png,.jpg"
@@ -66,13 +102,47 @@ Simple one-file form field — use geo-file-picker.
 ></geo-upload>
 ```
 
+### Full options
+
+```html
+<geo-upload
+  action="/api/upload"
+  accept=".png,.jpg,.jpeg,.svg,.pdf"
+  [maxSize]="2097152"
+  [multiple]="true"
+  [disabled]="false"
+  hint="Chỉ cho phép .png, .jpg, .pdf và dung lượng không quá 2Mb"
+  titlePrefix="Kéo thả ảnh hoặc"
+  selectText="Chọn file"
+  titleSuffix="để tải lên"
+  listTitle="Tập tin đính kèm"
+  [showListTitle]="true"
+  [(fileList)]="files"
+  (fileListChange)="onFiles($event)"
+  (change)="onUploadChange($event)"
+  (remove)="onRemove($event)"
+  (reject)="onReject($event)"
+></geo-upload>
+```
+
+## Tips
+
+- maxSize tính bằng byte (mặc định 1MB).
+- hint/titlePrefix/selectText/titleSuffix tiếng Việt tùy chỉnh.
+- customRequest / beforeUpload khi cần upload tùy biến.
+## Related components
+
+- [`geo-file-picker`](./geo-file-picker.md)
+- [`geo-form-modal`](./geo-form-modal.md)
+- [`geo-button`](./geo-button.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-upload.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-upload/geo-upload.component.ts`
 
-## Storybook
-GEO / related story for `geo-upload`
-
-## 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.