@geoit/ui 0.0.2 → 0.0.5

package/ai/components/geo-checkbox.md

@@ -1,16 +1,23 @@
 # geo-checkbox
 
-> AI quick reference for **GeoCheckboxComponent**
+> Complete usage reference for **GeoCheckboxComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-Checkbox with label; supports CVA / ngModel.
+Checkbox with label; bind with [(checked)] (not CVA/ngModel).
 
 ## Import
+
 ```ts
 import { GeoCheckboxComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoCheckboxComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoCheckboxComponent]
+```
 
 ## Selector
 `geo-checkbox`
@@ -24,31 +31,71 @@ Boolean / multi-select options in forms.
 ## Do not use when
 Single exclusive choice — use geo-radio.
 
+## How to use
+
+Checkbox có label. Two-way bằng [(checked)] / (checkedChange) — không phải CVA ngModel.
+
+## Binding
+
+**`model()` two-way** on `checked` (Angular 18):
+
+```html
+<geo-checkbox [(checked)]="agreed"></geo-checkbox>
+```
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `label` | See component TS / Storybook Controls |
-| `checked` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `indeterminate` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `label` | `string` | `''` | — |
+| `checked` | `boolean` | `false` | Two-way: `[(checked)]`. — Two-way `model()` (supports banana binding). |
+| `disabled` | `boolean` | `false` | — |
+| `indeterminate` | `boolean` | `false` | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `checkedChange` | EventEmitter |
 
-## Example
+_None_
+
+
+## Examples
+
+### Basic
+
+```html
+<geo-checkbox label="Tôi đồng ý điều khoản" [(checked)]="agreed"></geo-checkbox>
+```
+
+### Full options
+
 ```html
-<geo-checkbox label="Tôi đồng ý" [(ngModel)]="agreed"></geo-checkbox>
+<geo-checkbox
+  label="Chọn tất cả"
+  [(checked)]="allChecked"
+  [indeterminate]="indeterminate"
+  [disabled]="loading"
+  (checkedChange)="onToggleAll($event)"
+></geo-checkbox>
 ```
 
+## Tips
+
+- Độc quyền 1 lựa chọn → geo-radio.
+- indeterminate cho trạng thái chọn một phần (select-all).
+- Luôn dùng [(checked)], không [(ngModel)].
+## Related components
+
+- [`geo-radio`](./geo-radio.md)
+- [`geo-button`](./geo-button.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-checkbox.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-checkbox/geo-checkbox.component.ts`
 
-## Storybook
-GEO / related story for `geo-checkbox`
-
-## 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-column-picker.md

@@ -1,16 +1,23 @@
 # geo-column-picker
 
-> AI quick reference for **GeoColumnPickerComponent**
+> Complete usage reference for **GeoColumnPickerComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Column visibility picker for tables (optional persistence).
 
 ## Import
+
 ```ts
 import { GeoColumnPickerComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoColumnPickerComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoColumnPickerComponent]
+```
 
 ## Selector
 `geo-column-picker`
@@ -24,31 +31,97 @@ Let users show/hide table columns.
 ## Do not use when
 Static tables with fixed columns.
 
+## How to use
+
+Popup ẩn/hiện cột bảng. [items] GeoColumnPickerItem[]; (apply) nhận payload cột đã chọn; tùy chọn storageKey để persist.
+
+## 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 |
-|-------|-------|
-| `triggerLabel` | See component TS / Storybook Controls |
-| `hint` | See component TS / Storybook Controls |
-| `items` | See component TS / Storybook Controls |
-| `storageKey` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `triggerLabel` | `string` | `'Ẩn hiện cột'` | — |
+| `hint` | `string` | `'Chọn cột hiển thị trên bảng.'` | — |
+| `items` | `GeoColumnPickerItem[]` | `[]` | — |
+| `storageKey` | `string \| undefined` | `undefined` | Lưu trạng thái ẩn/hiện cột theo session khi người dùng áp dụng |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `apply` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `apply` | `OutputEmitterRef<GeoColumnPickerApplyPayload>` | — |
+
+## Related types
+
+From `figma/geo-table/geo-column-picker/geo-column-picker.types.ts`:
+
+```ts
+export interface GeoColumnPickerItem {
+  key: string;
+  title: string;
+  visible: boolean;
+  locked?: boolean;
+  /** @deprecated Không còn UI ghim/di chuyển cột. */
+  pinnable?: boolean;
+  /** @deprecated Không còn UI ghim/di chuyển cột. */
+  pinned?: GeoColumnPinSide | null;
+}
+
+export interface GeoColumnPickerApplyPayload {
+  visibility: Record<string, boolean>;
+  /** @deprecated Luôn `{}` từ picker mới — giữ field để tương thích. */
+  pinned: Record<string, GeoColumnPinSide | null>;
+}
+
+export type GeoColumnPinSide = 'left' | 'right';
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-column-picker [items]="cols" (apply)="onCols($event)"></geo-column-picker>
 ```
 
+### Full options
+
+```html
+<geo-column-picker
+  triggerLabel="Ẩn hiện cột"
+  hint="Chọn cột hiển thị trên bảng."
+  [items]="[
+    { key: 'code', label: 'Mã', visible: true },
+    { key: 'name', label: 'Tên', visible: true },
+    { key: 'status', label: 'Trạng thái', visible: false }
+  ]"
+  storageKey="ho-so-columns"
+  (apply)="onColumnApply($event)"
+></geo-column-picker>
+```
+
+## Tips
+
+- Thường gắn qua geo-table-toolbar [columnItems].
+- storageKey ổn định theo màn hình (vd. 'hs-columns').
+- triggerLabel/hint tiếng Việt mặc định đã có.
+## Related components
+
+- [`geo-table`](./geo-table.md)
+- [`geo-table-toolbar`](./geo-table-toolbar.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-column-picker.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-table/geo-column-picker/geo-column-picker.component.ts`
 
-## Storybook
-GEO / related story for `geo-column-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-confirm-modal.md

@@ -1,16 +1,23 @@
 # geo-confirm-modal
 
-> AI quick reference for **GeoConfirmModalComponent**
+> Complete usage reference for **GeoConfirmModalComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Confirm / danger dialog (destroy actions).
 
 ## Import
+
 ```ts
 import { GeoConfirmModalComponent } from '@geoit/ui';
 ```
 
-Standalone component — add to `imports: [GeoConfirmModalComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoConfirmModalComponent]
+```
 
 ## Selector
 `geo-confirm-modal`
@@ -24,29 +31,55 @@ Delete, irreversible actions.
 ## Do not use when
 Multi-field forms — use geo-form-modal.
 
+## How to use
+
+Dialog xác nhận hành động phá hủy (xóa). Điều khiển bằng [visible] + (visibleChange); (confirm)/(cancel).
+
+## 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 |
-|-------|-------|
-| `visible` | See component TS / Storybook Controls |
-| `title` | See component TS / Storybook Controls |
-| `message` | See component TS / Storybook Controls |
-| `highlight` | See component TS / Storybook Controls |
-| `description` | See component TS / Storybook Controls |
-| `cancelText` | See component TS / Storybook Controls |
-| `confirmText` | See component TS / Storybook Controls |
-| `confirmLoading` | See component TS / Storybook Controls |
-| `width` | See component TS / Storybook Controls |
-| `maskClosable` | See component TS / Storybook Controls |
-| `closable` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `visible` | `boolean` | `false` | Two-way `model()` (supports banana binding). |
+| `title` | `string` | `'Xác nhận xoá'` | — |
+| `message` | `string` | `''` | — |
+| `highlight` | `string` | `''` | — |
+| `description` | `string` | `'Hành động không thể hoàn tác, bạn chắc chắn muốn thực hiện?'` | — |
+| `cancelText` | `string` | `'Hủy'` | — |
+| `confirmText` | `string` | `'Xác nhận'` | — |
+| `confirmLoading` | `boolean` | `false` | — |
+| `width` | `number \| string` | `445` | — |
+| `maskClosable` | `boolean` | `false` | — |
+| `closable` | `boolean` | `true` | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `visibleChange` | EventEmitter |
-| `confirm` | EventEmitter |
-| `cancel` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `confirm` | `OutputEmitterRef<void>` | — |
+| `cancel` | `OutputEmitterRef<void>` | — |
+
+## Related types
+
+From `figma/geo-confirm-modal/geo-confirm-modal.types.ts`:
+
+```ts
+export interface GeoConfirmModalContent {
+  message?: string;
+  highlight?: string;
+  description?: string;
+}
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-confirm-modal
   [visible]="open"
@@ -58,13 +91,45 @@ Multi-field forms — use geo-form-modal.
 ></geo-confirm-modal>
 ```
 
+### Full options
+
+```html
+<geo-confirm-modal
+  [visible]="confirmOpen"
+  title="Xác nhận xoá"
+  message="Bạn sắp xóa hồ sơ"
+  highlight="HS-2024-001"
+  description="Hành động không thể hoàn tác, bạn chắc chắn muốn thực hiện?"
+  cancelText="Hủy"
+  confirmText="Xóa"
+  [confirmLoading]="deleting"
+  [width]="445"
+  [maskClosable]="false"
+  [closable]="true"
+  (confirm)="onDelete()"
+  (cancel)="confirmOpen = false"
+  (visibleChange)="confirmOpen = $event"
+></geo-confirm-modal>
+```
+
+## Tips
+
+- Form nhiều field → geo-form-modal.
+- highlight để nhấn mạnh tên đối tượng bị xóa.
+- confirmLoading khi đang gọi API.
+## Related components
+
+- [`geo-form-modal`](./geo-form-modal.md)
+- [`geo-button`](./geo-button.md)
+- [`geo-toast`](./geo-toast.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-confirm-modal.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-confirm-modal/geo-confirm-modal.component.ts`
 
-## Storybook
-GEO / related story for `geo-confirm-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-dashboard.md

@@ -0,0 +1,91 @@
+# geo-dashboard
+
+> Complete usage reference for **GeoDashboardComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
+
+## Summary
+GeoDashboardComponent
+
+## Import
+
+```ts
+import { GeoDashboardComponent } from '@geoit/ui';
+```
+
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoDashboardComponent]
+```
+
+## Selector
+`geo-dashboard`
+
+## 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 |
+|-------|------|---------|-------------|
+| `title` | `string` | `'Dashboard thống kê'` | — |
+| `breadcrumb` | `GeoBreadcrumbItem[]` | `[ { label: 'Trang chủ', link: '/' }, { label: 'Dashboard' }, ]` | — |
+| `stats` | `GeoStatCardItem[]` | `[]` | — |
+| `wardChartTitle` | `string` | `'Diện tích quy hoạch theo phường/xã'` | — |
+| `wardData` | `GeoChartDatum[]` | `[]` | — |
+| `mismatchChartTitle` | `string` | `'Tỷ lệ thửa quy hoạch khác mục đích hiện trạng'` | — |
+| `mismatchData` | `GeoChartDatum[]` | `[]` | — |
+| `wardUnit` | `string` | `'ha'` | — |
+| `period` | `GeoDateRangeValue` | `null` | Two-way `model()` (supports banana binding). |
+
+## Outputs
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `periodChange` | `OutputEmitterRef<GeoDateRangeValue>` | — |
+| `mismatchSegmentClick` | `OutputEmitterRef<GeoChartSegmentClick>` | — |
+| `wardSegmentClick` | `OutputEmitterRef<GeoChartSegmentClick>` | — |
+
+## Related types
+
+From `figma/geo-dashboard/geo-dashboard.types.ts`:
+
+```ts
+export interface GeoDashboardPeriodChange {
+  range: GeoDateRangeValue | null;
+}
+```
+
+## Examples
+
+### Example
+
+```html
+<geo-dashboard></geo-dashboard>
+```
+
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-dashboard.md`
+
+## Source
+`projects/geo-ui/src/lib/figma/geo-dashboard/geo-dashboard.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.

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

@@ -1,16 +1,24 @@
 # geo-date-picker
 
-> AI quick reference for **GeoDatePickerComponent**
+> Complete usage reference for **GeoDatePickerComponent** (`@geoit/ui`)
+>
+> Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
 Single date (optional time) picker.
 
 ## Import
+
 ```ts
 import { GeoDatePickerComponent } from '@geoit/ui';
+import { FormsModule } from '@angular/forms'; // when using [(ngModel)]
 ```
 
-Standalone component — add to `imports: [GeoDatePickerComponent]` of the consuming standalone component/module.
+Add to the consuming standalone component:
+
+```ts
+imports: [GeoDatePickerComponent, FormsModule]
+```
 
 ## Selector
 `geo-date-picker`
@@ -24,42 +32,110 @@ One date field in forms.
 ## Do not use when
 Date range — use geo-date-range-picker.
 
+## How to use
+
+Chọn một ngày (CVA). [(ngModel)] hoặc formControlName; format mặc định dd/MM/yyyy; bật showTime khi cần giờ.
+
+## Binding
+
+Supports **ControlValueAccessor**.
+
+```html
+<geo-date-picker [(ngModel)]="value"></geo-date-picker>
+<!-- or -->
+<geo-date-picker formControlName="field"></geo-date-picker>
+```
+
+Also import `FormsModule` (template-driven) or `ReactiveFormsModule`.
+
+Library API uses Angular 18 `input()` / `output()` signals under the hood.
+
 ## Inputs
-| Input | Notes |
-|-------|-------|
-| `label` | See component TS / Storybook Controls |
-| `placeholder` | See component TS / Storybook Controls |
-| `format` | See component TS / Storybook Controls |
-| `mode` | See component TS / Storybook Controls |
-| `size` | See component TS / Storybook Controls |
-| `disabled` | See component TS / Storybook Controls |
-| `required` | See component TS / Storybook Controls |
-| `error` | See component TS / Storybook Controls |
-| `errorMessage` | See component TS / Storybook Controls |
-| `allowClear` | See component TS / Storybook Controls |
-| `showToday` | See component TS / Storybook Controls |
-| `showTime` | See component TS / Storybook Controls |
-| `block` | See component TS / Storybook Controls |
-| `width` | See component TS / Storybook Controls |
-| `disabledDate` | See component TS / Storybook Controls |
+
+Every supported Input (do not invent others):
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `label` | `string` | `''` | — |
+| `placeholder` | `string` | `'Chọn ngày'` | — |
+| `format` | `string` | `'dd/MM/yyyy'` | — |
+| `mode` | `'date' \| 'week' \| 'month' \| 'year'` | `'date'` | — |
+| `size` | `'default' \| 'small'` | `'default'` | — |
+| `disabled` | `boolean` | `false` | — |
+| `required` | `boolean` | `false` | — |
+| `error` | `boolean` | `false` | — |
+| `errorMessage` | `string` | `''` | — |
+| `allowClear` | `boolean` | `true` | — |
+| `showToday` | `boolean` | `true` | — |
+| `showTime` | `boolean` | `false` | — |
+| `block` | `boolean` | `false` | — |
+| `width` | `number \| string \| undefined` | `undefined` | — |
+| `disabledDate` | `((current: Date) => boolean) \| undefined` | `undefined` | — |
 
 ## Outputs
-| Output | Notes |
-|--------|-------|
-| `valueChange` | EventEmitter |
 
-## Example
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `valueChange` | `OutputEmitterRef<Date \| null>` | — |
+
+## Related types
+
+From `figma/geo-date-picker/geo-date-picker.types.ts`:
+
+```ts
+export type GeoDatePickerMode = 'date' | 'week' | 'month' | 'year';
+
+export type GeoDatePickerSize = 'default' | 'small';
+```
+
+## Examples
+
+### Basic
+
 ```html
 <geo-date-picker label="Ngày tạo" [required]="true" [(ngModel)]="date" [block]="true"></geo-date-picker>
 ```
 
+### Full options
+
+```html
+<geo-date-picker
+  label="Ngày hiệu lực"
+  placeholder="Chọn ngày"
+  format="dd/MM/yyyy"
+  mode="date"
+  size="default"
+  [required]="true"
+  [allowClear]="true"
+  [showToday]="true"
+  [showTime]="false"
+  [block]="true"
+  [error]="hasError"
+  errorMessage="Vui lòng chọn ngày"
+  [disabledDate]="disablePast"
+  [(ngModel)]="effectiveDate"
+  (valueChange)="onDate($event)"
+></geo-date-picker>
+```
+
+## Tips
+
+- Khoảng ngày → geo-date-range-picker.
+- [block]="true" trong form modal/grid.
+- disabledDate để chặn ngày không hợp lệ.
+## Related components
+
+- [`geo-date-range-picker`](./geo-date-range-picker.md)
+- [`geo-input`](./geo-input.md)
+- [`geo-form-modal`](./geo-form-modal.md)
+## Package path
+`node_modules/@geoit/ui/ai/components/geo-date-picker.md`
+
 ## Source
 `projects/geo-ui/src/lib/figma/geo-date-picker/geo-date-picker.component.ts`
 
-## Storybook
-GEO / related story for `geo-date-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.