@geoit/ui 0.0.2 → 0.0.4

package/ai/components/geo-file-picker.md

@@ -1,16 +1,24 @@
 # geo-file-picker
 
-> AI quick reference for **GeoFilePickerComponent**
+> Complete usage reference for **GeoFilePickerComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Compact file input for forms (button + filename).
 
 ## Import
+
 ```ts
 import { GeoFilePickerComponent } from '@geoit/ui';
+import { FormsModule } from '@angular/forms'; // when using [(ngModel)]
 ```
 
-Standalone component — add to `imports: [GeoFilePickerComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoFilePickerComponent, FormsModule]
+```
 
 ## Selector
 `geo-file-picker`
@@ -24,39 +32,102 @@ Single/small file field inside a form row.
 ## Do not use when
 Drag-drop multi upload with progress — use geo-upload.
 
+## How to use
+
+Ô chọn file gọn trong form (nút + tên file). CVA; (fileChange) nhận File | FileList; accept để giới hạn loại.
+
+## Binding
+
+Supports **ControlValueAccessor**.
+
+```html
+<geo-file-picker [(ngModel)]="value"></geo-file-picker>
+<!-- or -->
+<geo-file-picker formControlName="field"></geo-file-picker>
+```
+
+Also import `FormsModule` (template-driven) or `ReactiveFormsModule`.
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `label` | See component TS / Storybook Controls |
-| `placeholder` | See component TS / Storybook Controls |
-| `buttonText` | See component TS / Storybook Controls |
-| `required` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `accept` | See component TS / Storybook Controls |
-| `multiple` | See component TS / Storybook Controls |
-| `error` | See component TS / Storybook Controls |
-| `errorMessage` | See component TS / Storybook Controls |
-| `block` | See component TS / Storybook Controls |
-| `width` | See component TS / Storybook Controls |
-| `selectedName` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `label` | `string` | `'Tải file'` | — |
+| `placeholder` | `string` | `'Chọn giá trị'` | — |
+| `buttonText` | `string` | `'Chọn file'` | — |
+| `required` | `boolean` | `false` | — |
+| `disabled` | `boolean` | `false` | — |
+| `accept` | `string` | `''` | — |
+| `multiple` | `boolean` | `false` | — |
+| `error` | `boolean` | `false` | — |
+| `errorMessage` | `string` | `''` | — |
+| `block` | `boolean` | `false` | — |
+| `width` | `number \| string` | — | — |
+| `selectedName` | `string` | `''` | Tên file đã upload (server) — hiện khi chưa có File local trong CVA. Dùng cho flow: chọn file → upload → giữ tên từ API. |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `fileChange` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `fileChange` | `EventEmitter<File \| File[] \| null>` | — |
+
+## Related types
+
+From `figma/geo-file-picker/geo-file-picker.types.ts`:
+
+```ts
+export interface GeoFilePickerValue {
+  file: File;
+  name: string;
+}
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-file-picker label="Đính kèm" accept=".pdf,.png" (fileChange)="onFile($event)" [block]="true"></geo-file-picker>
 ```
 
+### Full options
+
+```html
+<geo-file-picker
+  label="Tải file"
+  placeholder="Chọn giá trị"
+  buttonText="Chọn file"
+  accept=".pdf,.doc,.docx"
+  [multiple]="false"
+  [required]="true"
+  [block]="true"
+  [error]="fileError"
+  errorMessage="Vui lòng chọn file"
+  [(ngModel)]="file"
+  (fileChange)="onFile($event)"
+></geo-file-picker>
+```
+
+## Tips
+
+- Upload kéo-thả nhiều file + progress → geo-upload.
+- selectedName hiển thị tên đã chọn khi không bind CVA file object.
+- [block]="true" trong modal form.
+## Related components
+
+- [`geo-upload`](./geo-upload.md)
+- [`geo-form-modal`](./geo-form-modal.md)
+- [`geo-input`](./geo-input.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-file-picker.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-file-picker/geo-file-picker.component.ts`
 
-## Storybook
-GEO / related story for `geo-file-picker`
-
-## 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-form-modal.md

@@ -1,16 +1,24 @@
 # geo-form-modal
 
-> AI quick reference for **GeoFormModalComponent**
+> Complete usage reference for **GeoFormModalComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Form modal: fixed header/footer, scrollable body via ng-content.
 
 ## Import
+
 ```ts
 import { GeoFormModalComponent } from '@geoit/ui';
+import { FormsModule } from '@angular/forms'; // when using [(ngModel)]
 ```
 
-Standalone component — add to `imports: [GeoFormModalComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoFormModalComponent, FormsModule]
+```
 
 ## Selector
 `geo-form-modal`
@@ -24,45 +32,61 @@ Create/edit dialogs; compose geo-stepper inside body for multi-step.
 ## Do not use when
 Full-page wizards — use geo-step-form-layout.
 
+## How to use
+
+Modal form: header/footer cố định, body scroll qua ng-content. [open] + (openChange); (ok)/(cancel). Ghép geo-stepper trong body cho multi-step dialog.
+
+## Binding
+
+Standalone presentational / container component — drive via Inputs and Outputs (no `ngModel` unless documented).
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `open` | See component TS / Storybook Controls |
-| `title` | See component TS / Storybook Controls |
-| `titleUppercase` | See component TS / Storybook Controls |
-| `okText` | See component TS / Storybook Controls |
-| `cancelText` | See component TS / Storybook Controls |
-| `cancelIcon` | See component TS / Storybook Controls |
-| `cancelIconPlacement` | See component TS / Storybook Controls |
-| `okIcon` | See component TS / Storybook Controls |
-| `okIconPlacement` | See component TS / Storybook Controls |
-| `secondaryOkText` | See component TS / Storybook Controls |
-| `confirmLoading` | See component TS / Storybook Controls |
-| `okDisabled` | See component TS / Storybook Controls |
-| `readonly` | See component TS / Storybook Controls |
-| `width` | See component TS / Storybook Controls |
-| `closable` | See component TS / Storybook Controls |
-| `mask` | See component TS / Storybook Controls |
-| `maskClosable` | See component TS / Storybook Controls |
-| `keyboard` | See component TS / Storybook Controls |
-| `centered` | See component TS / Storybook Controls |
-| `zIndex` | See component TS / Storybook Controls |
-| `className` | See component TS / Storybook Controls |
-| `wrapClassName` | See component TS / Storybook Controls |
-| `bodyScroll` | See component TS / Storybook Controls |
-| `bodyMaxHeight` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `open` | `boolean` | `false` | Tương đương `open` (antd) / `nzVisible` (ng-zorro). |
+| `title` | `string` | `''` | — |
+| `titleUppercase` | `boolean` | `true` | Title chữ in hoa. Default `true` theo design. |
+| `okText` | `string` | `'Lưu'` | — |
+| `cancelText` | `string` | `'Hủy'` | — |
+| `cancelIcon` | `string` | — | Icon nút cancel (vd. `left` cho Quay lại). |
+| `cancelIconPlacement` | `'start' \| 'end'` | `'start'` | — |
+| `okIcon` | `string` | — | Icon nút OK (vd. `right` cho Tiếp theo). |
+| `okIconPlacement` | `'start' \| 'end'` | `'end'` | — |
+| `secondaryOkText` | `string` | `''` | Nút phụ (vd. Lưu và khởi tạo lại). Chỉ hiện khi có text và không readonly. |
+| `confirmLoading` | `boolean` | `false` | Loading trên nút OK — giống antd `confirmLoading` / nz `nzOkLoading`. |
+| `okDisabled` | `boolean` | `false` | Disable nút OK — giống antd `okButtonProps.disabled` / nz `nzOkDisabled`. |
+| `readonly` | `boolean` | `false` | Ẩn nút OK (xem chi tiết). |
+| `width` | `number \| string` | `720` | — |
+| `closable` | `boolean` | `true` | — |
+| `mask` | `boolean` | `true` | — |
+| `maskClosable` | `boolean` | `false` | — |
+| `keyboard` | `boolean` | `true` | — |
+| `centered` | `boolean` | `true` | — |
+| `zIndex` | `number` | `1000` | — |
+| `className` | `string` | `''` | — |
+| `wrapClassName` | `string` | `''` | — |
+| `bodyScroll` | `boolean` | `true` | Body cuộn, header/footer cố định. |
+| `bodyMaxHeight` | `string \| number` | `'60vh'` | Max-height của vùng body khi `bodyScroll` (vd `'60vh'`, `400`). |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `openChange` | EventEmitter |
-| `ok` | EventEmitter |
-| `secondaryOk` | EventEmitter |
-| `cancel` | EventEmitter |
-| `afterOpen` | EventEmitter |
-| `afterClose` | EventEmitter |
-
-## Example
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `openChange` | `EventEmitter<boolean>` | — |
+| `ok` | `EventEmitter<void>` | — |
+| `secondaryOk` | `EventEmitter<void>` | — |
+| `cancel` | `EventEmitter<void>` | — |
+| `afterOpen` | `EventEmitter<void>` | — |
+| `afterClose` | `EventEmitter<void>` | — |
+
+
+## Examples
+
+### Basic
+
 ```html
 <geo-form-modal
   [open]="open"
@@ -76,13 +100,57 @@ Full-page wizards — use geo-step-form-layout.
 </geo-form-modal>
 ```
 
+### Full options
+
+```html
+<geo-form-modal
+  [open]="open"
+  title="Lập phiếu đăng ký"
+  [titleUppercase]="true"
+  cancelText="Hủy bỏ"
+  okText="Lưu"
+  okIcon="right"
+  okIconPlacement="end"
+  [confirmLoading]="saving"
+  [okDisabled]="!valid"
+  [width]="720"
+  [closable]="true"
+  [mask]="true"
+  [maskClosable]="false"
+  [centered]="true"
+  [bodyScroll]="true"
+  bodyMaxHeight="60vh"
+  (openChange)="open = $event"
+  (ok)="onSave()"
+  (cancel)="open = false"
+>
+  <div style="display:grid;grid-template-columns:1fr 1fr;gap:16px;">
+    <geo-input label="Mã" [required]="true" [block]="true" [(ngModel)]="code"></geo-input>
+    <geo-input label="Tên" [required]="true" [block]="true" [(ngModel)]="name"></geo-input>
+  </div>
+</geo-form-modal>
+```
+
+## Tips
+
+- Wizard full-page → geo-step-form-layout.
+- okIcon/cancelIcon + placement cho nút Tiếp theo / Quay lại.
+- bodyMaxHeight mặc định 60vh; readonly ẩn nút OK.
+## Related components
+
+- [`geo-stepper`](./geo-stepper.md)
+- [`geo-input`](./geo-input.md)
+- [`geo-select`](./geo-select.md)
+- [`geo-confirm-modal`](./geo-confirm-modal.md)
+- [`geo-step-form-layout`](./geo-step-form-layout.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-form-modal.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-form-modal/geo-form-modal.component.ts`
 
-## Storybook
-GEO / related story for `geo-form-modal`
-
-## 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-icon.md

@@ -1,16 +1,23 @@
 # geo-icon
 
-> AI quick reference for **GeoIconComponent**
+> Complete usage reference for **GeoIconComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Ant Design icon wrapper with GEO size/color tokens.
 
 ## Import
+
 ```ts
 import { GeoIconComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoIconComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoIconComponent]
+```
 
 ## Selector
 `geo-icon`
@@ -24,30 +31,77 @@ Standalone icons; buttons usually use geo-button [icon].
 ## Do not use when
 Do not hardcode icon hex colors — use color token names.
 
+## How to use
+
+Wrapper icon Ant Design. Bắt buộc [type]; size xs|sm|md|lg|xl hoặc px; color dùng token (vd. primary / var(--geo-color-*)).
+
+## Binding
+
+Standalone presentational / container component — drive via Inputs and Outputs (no `ngModel` unless documented).
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `type` | See component TS / Storybook Controls |
-| `theme` | See component TS / Storybook Controls |
-| `spin` | See component TS / Storybook Controls |
-| `size` | See component TS / Storybook Controls |
-| `color` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | — | — | Tên icon Ant Design (vd. `close`, `search`, `appstore`). |
+| `theme` | `'outline' \| 'fill' \| 'twotone'` | `'outline'` | — |
+| `spin` | `boolean` | `false` | — |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number \| string` | `'md'` | xs \| sm \| md \| lg \| xl \| number(px) \| CSS size string |
+| `color` | `string` | — | CSS color — ưu tiên design token, vd. `var(--geo-color-primary-default)` |
 
 ## Outputs
+
 _None_
 
-## Example
+## Related types
+
+From `figma/geo-icon/geo-icon.types.ts`:
+
+```ts
+export type GeoIconTheme = 'outline' | 'fill' | 'twotone';
+
+export type GeoIconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | string;
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-icon type="search" size="md" color="primary"></geo-icon>
 ```
 
+### Full options
+
+```html
+<geo-icon
+  type="loading"
+  theme="outline"
+  size="lg"
+  color="var(--geo-color-primary-default)"
+  [spin]="true"
+></geo-icon>
+```
+
+## Tips
+
+- Trong nút ưu tiên geo-button [icon].
+- Không hardcode hex — dùng color token.
+- theme outline|fill|twotone; spin cho loading.
+## Related components
+
+- [`geo-button`](./geo-button.md)
+- [`geo-status-tag`](./geo-status-tag.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-icon.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-icon/geo-icon.component.ts`
 
-## Storybook
-GEO / related story for `geo-icon`
-
-## 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-input.md

@@ -1,16 +1,24 @@
 # geo-input
 
-> AI quick reference for **GeoInputComponent**
+> Complete usage reference for **GeoInputComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Text input with label, validation, icons; CVA/ngModel.
 
 ## Import
+
 ```ts
 import { GeoInputComponent } from '@geoit/ui';
+import { FormsModule } from '@angular/forms'; // when using [(ngModel)]
 ```
 
-Standalone component — add to `imports: [GeoInputComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoInputComponent, FormsModule]
+```
 
 ## Selector
 `geo-input`
@@ -24,42 +32,97 @@ Default text fields in forms.
 ## Do not use when
 Long text — use geo-textarea; select options — use geo-select.
 
+## How to use
+
+Ô text chuẩn form (CVA). label + [(ngModel)]; type text|number|password|email; prefixIcon/suffixIcon; [block] full width.
+
+## Binding
+
+Supports **ControlValueAccessor**.
+
+```html
+<geo-input [(ngModel)]="value"></geo-input>
+<!-- or -->
+<geo-input formControlName="field"></geo-input>
+```
+
+Also import `FormsModule` (template-driven) or `ReactiveFormsModule`.
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `label` | See component TS / Storybook Controls |
-| `placeholder` | See component TS / Storybook Controls |
-| `type` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `readonly` | See component TS / Storybook Controls |
-| `required` | See component TS / Storybook Controls |
-| `error` | See component TS / Storybook Controls |
-| `errorMessage` | See component TS / Storybook Controls |
-| `maxlength` | See component TS / Storybook Controls |
-| `prefixIcon` | See component TS / Storybook Controls |
-| `suffixIcon` | See component TS / Storybook Controls |
-| `allowClear` | See component TS / Storybook Controls |
-| `block` | See component TS / Storybook Controls |
-| `width` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `label` | `string` | `''` | — |
+| `placeholder` | `string` | `''` | — |
+| `type` | `'text' \| 'number' \| 'password' \| 'email'` | `'text'` | — |
+| `disabled` | `boolean` | `false` | — |
+| `readonly` | `boolean` | `false` | — |
+| `required` | `boolean` | `false` | — |
+| `error` | `boolean` | `false` | — |
+| `errorMessage` | `string` | `''` | — |
+| `maxlength` | `number` | — | — |
+| `prefixIcon` | `string` | — | — |
+| `suffixIcon` | `string` | — | — |
+| `allowClear` | `boolean` | `false` | — |
+| `block` | `boolean` | `false` | — |
+| `width` | `number \| string` | — | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `valueChange` | EventEmitter |
-| `enterPressed` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `valueChange` | `EventEmitter<string>` | — |
+| `enterPressed` | `EventEmitter<void>` | — |
+
+
+## Examples
+
+### Basic
+
 ```html
 <geo-input label="Họ tên" [required]="true" [block]="true" [(ngModel)]="name"></geo-input>
 ```
 
+### Full options
+
+```html
+<geo-input
+  label="Mã hồ sơ"
+  placeholder="Nhập mã hồ sơ"
+  type="text"
+  prefixIcon="search"
+  [allowClear]="true"
+  [required]="true"
+  [block]="true"
+  [maxlength]="50"
+  [error]="codeError"
+  errorMessage="Mã không được để trống"
+  [(ngModel)]="code"
+  (enterPressed)="onSearch()"
+  (valueChange)="onCode($event)"
+></geo-input>
+```
+
+## Tips
+
+- Văn bản dài → geo-textarea; chọn danh sách → geo-select.
+- error + errorMessage khi validate fail.
+- (enterPressed) cho tìm kiếm nhanh.
+## Related components
+
+- [`geo-textarea`](./geo-textarea.md)
+- [`geo-select`](./geo-select.md)
+- [`geo-form-modal`](./geo-form-modal.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-input.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-input/geo-input.component.ts`
 
-## Storybook
-GEO / related story for `geo-input`
-
-## 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.