akanjs 0.0.1 → 2.0.0-beta.1

package/cli/guidelines/scalarDictionary/scalarDictionary.instruction.md

@@ -0,0 +1,273 @@
+# Scalar Dictionary Implementation Guide for Akan.js
+
+## Purpose of Scalar Dictionary Files
+
+Scalar dictionary files in Akan.js provide internationalization (i18n) support by:
+
+- Defining translations for scalar names, fields, and enum values
+- Supporting multiple languages (primarily English and Korean)
+- Enabling consistent terminology across the application
+- Providing field descriptions for documentation and tooltips
+- Maintaining type safety with the constant model definition
+- Creating a centralized translation source for UI components
+
+## File Structure and Location
+
+### Location Convention
+
+```
+{app,lib}/
+└── */lib/__scalar/
+    └── <scalarName>/                  # camelCase directory
+        ├── <scalarName>.constant.ts   # scalar definition
+        └── <scalarName>.dictionary.ts # translations
+```
+
+### Key Benefits
+
+- End-to-end type safety
+- Fluent builder pattern
+- Automatic validation via generics
+- Multi-language support
+
+## Required Imports
+
+```typescript
+import { scalarDictionary } from "akanjs/dictionary";
+
+// Import types using "import type" for cleaner code
+import type { YourScalar, YourEnum } from "./yourScalar.constant";
+```
+
+## Scalar Dictionary Builder
+
+The `scalarDictionary()` function creates a type-safe dictionary using a fluent builder pattern.
+
+### Builder Methods
+
+| Method                       | Description                      | Example                                                                    |
+| ---------------------------- | -------------------------------- | -------------------------------------------------------------------------- |
+| `.of((t) => ...)`            | Define scalar name & description | `.of((t) => t(["Scalar Name", "스칼라 이름"]).desc(["Desc", "설명"]))`     |
+| `.model<T>((t) => ...)`      | Define field translations        | `.model<YourScalar>((t) => ({ fieldName: t(["Label", "레이블"]) }))`       |
+| `.enum<T>(name, (t) => ...)` | Define enum value translations   | `.enum<YourEnum>("enumName", (t) => ({ value1: t(["Label", "레이블"]) }))` |
+
+## Translation Format
+
+Each translation uses the `t()` function with an array of values. The array order matches the language order defined in `scalarDictionary()`.
+
+```typescript
+// Language order: ["en", "ko"]
+// Index 0 = English, Index 1 = Korean
+
+t(["English Label", "한국어 레이블"]).desc(["English description", "한국어 설명"]);
+```
+
+### Translation Methods
+
+| Method         | Purpose                | Example                                  |
+| -------------- | ---------------------- | ---------------------------------------- |
+| `t([...])`     | Define the label/name  | `t(["Status", "상태"])`                  |
+| `.desc([...])` | Define the description | `.desc(["Current status", "현재 상태"])` |
+
+> **Note**: Both label and description are required for complete internationalization support.
+
+## Basic Structure
+
+```typescript
+import { scalarDictionary } from "akanjs/dictionary";
+import type { YourScalar, YourEnum } from "./yourScalar.constant";
+
+export const dictionary = scalarDictionary(["en", "ko"])
+  .of((t) => t(["Scalar Name", "스칼라 이름"]).desc(["Scalar description", "스칼라 설명"]))
+  .model<YourScalar>((t) => ({
+    fieldName: t(["Field Label", "필드 레이블"]).desc(["Field description", "필드 설명"]),
+  }))
+  .enum<YourEnum>("enumName", (t) => ({
+    value1: t(["Value Label", "값 레이블"]).desc(["Value description", "값 설명"]),
+  }));
+```
+
+## Complete Example
+
+```typescript
+// File: libs/payment/lib/__scalar/price/price.dictionary.ts
+import { scalarDictionary } from "akanjs/dictionary";
+import type { Currency, Price } from "./price.constant";
+
+export const dictionary = scalarDictionary(["en", "ko"])
+  .of((t) => t(["Price", "가격"]).desc(["Price information", "가격 정보"]))
+  .model<Price>((t) => ({
+    amount: t(["Amount", "금액"]).desc(["Price amount", "가격 금액"]),
+    currency: t(["Currency", "통화"]).desc(["Currency type", "통화 유형"]),
+  }))
+  .enum<Currency>("currency", (t) => ({
+    usd: t(["USD", "달러"]).desc(["US Dollar", "미국 달러"]),
+    krw: t(["KRW", "원"]).desc(["Korean Won", "한국 원"]),
+    eur: t(["EUR", "유로"]).desc(["Euro", "유로"]),
+  }));
+```
+
+## Enum Name Matching
+
+The first argument to `.enum()` must match the name used in `enumOf()` from the constant file. This ensures proper type checking and runtime resolution.
+
+### Example
+
+**constant.ts**:
+
+```typescript
+export class Currency extends enumOf("currency", ["usd", "krw", "eur"]) {}
+```
+
+**dictionary.ts**:
+
+```typescript
+// Must match: "currency"
+.enum<Currency>("currency", (t) => ({
+  usd: t(["USD", "달러"]).desc(["US Dollar", "미국 달러"]),
+  krw: t(["KRW", "원"]).desc(["Korean Won", "한국 원"]),
+  eur: t(["EUR", "유로"]).desc(["Euro", "유로"]),
+}))
+```
+
+> **Important**: The enum name string must exactly match the first argument of `enumOf()`. For example, `enumOf("journey", [...])` requires `.enum<Journey>("journey", ...)`.
+
+## Type Imports
+
+Always import types from the constant file to ensure type safety. The generic parameters enforce that all fields and enum values have translations.
+
+```typescript
+import { scalarDictionary } from "akanjs/dictionary";
+
+// Import types using "import type" for cleaner code
+import type { EncourageInfo, Inquiry, Journey } from "./encourageInfo.constant";
+
+export const dictionary = scalarDictionary(["en", "ko"])
+  .of((t) => t(["Encourage Info", "격려 정보"]).desc(["Encouragement information", "격려 정보"]))
+  .model<EncourageInfo>((t) => ({
+    // TypeScript ensures all fields of EncourageInfo are defined
+  }))
+  .enum<Journey>("journey", (t) => ({
+    // TypeScript ensures all values of Journey enum are defined
+  }))
+  .enum<Inquiry>("inquiry", (t) => ({
+    // TypeScript ensures all values of Inquiry enum are defined
+  }));
+```
+
+### Type Safety Benefits
+
+- **`import type`**: Use `import type` for type-only imports. This ensures no runtime code is included.
+- **`.model<Type>`**: Provides autocomplete for field names and validates that all fields are translated.
+- **`.enum<Type>`**: Provides autocomplete for enum values and validates that all values are translated.
+
+## Common Mistakes and Fixes
+
+| Issue             | Wrong ❌                         | Correct ✅                                      |
+| ----------------- | -------------------------------- | ----------------------------------------------- |
+| Missing .desc()   | `t(["Label", "레이블"])`         | `t(["Label", "레이블"]).desc(["Desc", "설명"])` |
+| Wrong enum name   | `.enum<Journey>("Journey", ...)` | `.enum<Journey>("journey", ...)`                |
+| Missing export    | `const dictionary = ...`         | `export const dictionary = ...`                 |
+| Wrong array order | `t(["한국어", "English"])`       | `t(["English", "한국어"])`                      |
+| Missing field     | (TypeScript error)               | All fields defined                              |
+
+## Best Practices
+
+### 1. Always Use Type Generics
+
+Use `.model<Type>` and `.enum<Type>` to ensure TypeScript validates all fields and values are translated.
+
+### 2. Consistent Language Order
+
+Always use the same language order (e.g., `["en", "ko"]`) across all dictionaries in your project.
+
+### 3. Meaningful Descriptions
+
+Provide helpful descriptions that explain the field's purpose, not just repeat the label.
+
+```typescript
+// ❌ Bad - description just repeats the label
+amount: t(["Amount", "금액"]).desc(["Amount", "금액"]),
+
+// ✅ Good - description explains the purpose
+amount: t(["Amount", "금액"]).desc(["Price amount in selected currency", "선택된 통화의 가격 금액"]),
+```
+
+### 4. Export as 'dictionary'
+
+Use the standard export name `dictionary` for consistency with the framework's auto-import system.
+
+```typescript
+// ✅ Correct
+export const dictionary = scalarDictionary(["en", "ko"])...
+```
+
+## Implementation Checklist
+
+### Required Elements
+
+- [ ] File location: `__scalar/<name>/<name>.dictionary.ts`
+- [ ] Import `scalarDictionary` from `akanjs/dictionary`
+- [ ] Import types from constant file using `import type`
+- [ ] Initialize with correct language order: `["en", "ko"]`
+- [ ] Define scalar name/description with `.of()`
+- [ ] Define all field translations with `.model<Type>()`
+- [ ] Define all enum translations with `.enum<Type>(name)`
+- [ ] Ensure enum name matches `enumOf()` name
+- [ ] Include both label and description for all entries
+- [ ] Export as `dictionary`
+
+### Translation Format
+
+- [ ] Each translation uses `t([...]).desc([...])`
+- [ ] First element is English translation
+- [ ] Second element is Korean translation
+- [ ] No trailing punctuation in translations
+- [ ] First letter capitalized in English
+
+## Full Example with Multiple Enums
+
+```typescript
+// File: apps/example/lib/__scalar/encourageInfo/encourageInfo.dictionary.ts
+import { scalarDictionary } from "akanjs/dictionary";
+import type { EncourageInfo, Inquiry, Journey } from "./encourageInfo.constant";
+
+export const dictionary = scalarDictionary(["en", "ko"])
+  .of((t) => t(["Encourage Info", "격려 정보"]).desc(["User encouragement settings", "사용자 격려 설정"]))
+  .model<EncourageInfo>((t) => ({
+    journey: t(["Journey", "여정"]).desc(["User journey stage", "사용자 여정 단계"]),
+    inquiry: t(["Inquiry", "문의"]).desc(["Inquiry type", "문의 유형"]),
+    message: t(["Message", "메시지"]).desc(["Encouragement message", "격려 메시지"]),
+    showAt: t(["Show At", "표시 시간"]).desc(["When to show encouragement", "격려 표시 시점"]),
+  }))
+  .enum<Journey>("journey", (t) => ({
+    firstJoin: t(["First Join", "첫 가입"]).desc(["User just joined", "사용자가 방금 가입함"]),
+    waitPay: t(["Waiting Payment", "결제 대기"]).desc(["Awaiting payment", "결제 대기 중"]),
+    onProgress: t(["In Progress", "진행 중"]).desc(["Currently active", "현재 진행 중"]),
+    completed: t(["Completed", "완료됨"]).desc(["Journey completed", "여정 완료"]),
+  }))
+  .enum<Inquiry>("inquiry", (t) => ({
+    general: t(["General", "일반"]).desc(["General inquiry", "일반 문의"]),
+    support: t(["Support", "지원"]).desc(["Technical support", "기술 지원"]),
+    billing: t(["Billing", "청구"]).desc(["Billing inquiry", "청구 문의"]),
+  }));
+```
+
+## Pro Tips
+
+- **TypeScript Errors**: TypeScript will show errors if you miss any fields or enum values - use this to your advantage!
+- **Usage**: The dictionary is used for UI labels, form validation messages, and API documentation
+- **Descriptions**: Keep descriptions concise but informative - they appear in tooltips and help text
+- **Consistency**: Match the field order in dictionary with the constant file for easier maintenance
+
+## Summary
+
+1. **Import**: `scalarDictionary` from `akanjs/dictionary`, types from constant file
+2. **Initialize**: `scalarDictionary(["en", "ko"])`
+3. **Scalar Info**: `.of((t) => t([...]).desc([...]))`
+4. **Fields**: `.model<Type>((t) => ({ field: t([...]).desc([...]) }))`
+5. **Enums**: `.enum<Type>("enumName", (t) => ({ value: t([...]).desc([...]) }))`
+6. **Export**: `export const dictionary = ...`
+7. **Format**: `t(["English", "Korean"]).desc(["English desc", "Korean desc"])`
+
+Following these guidelines ensures your scalar dictionary files are complete, type-safe, and maintainable across the Akan.js framework.

package/cli/guidelines/scalarModule/scalarModule.generate.json

@@ -0,0 +1,35 @@
+{
+  "title": "Scalar Module",
+  "description": "Overview and summary of scalar modules in Akan.js - reusable data structures for embedded documents, DTOs, and shared schemas",
+  "scans": [
+    {
+      "type": "source",
+      "description": "constant instruction file",
+      "path": "pkgs/akanjs/cli/guidelines/scalarConstant/scalarConstant.instruction.md"
+    },
+    {
+      "type": "source",
+      "description": "dictionary instruction file",
+      "path": "pkgs/akanjs/cli/guidelines/scalarDictionary/scalarDictionary.instruction.md"
+    },
+    {
+      "type": "source",
+      "description": "core scalar module factory functions",
+      "path": "pkgs/akanjs/server/module.ts"
+    }
+  ],
+  "update": {
+    "filePath": "./scalarModule.instruction.md",
+    "contents": [
+      "Purpose and architecture of scalar modules in Akan.js",
+      "Complete file structure and directory organization",
+      "Naming conventions for directories, files, classes, enums and dictionary keys"
+    ],
+    "rules": [
+      "Follow camelCase naming for directories and files",
+      "Use PascalCase for class names and enum types",
+      "Design scalars for reusability across multiple modules"
+    ]
+  },
+  "page": "/akanjs/(docs)/docs/scalar/overview/_index.tsx"
+}

package/cli/guidelines/scalarModule/scalarModule.instruction.md

@@ -0,0 +1,81 @@
+# Scalar Modules Overview
+
+## Purpose
+
+Scalar modules provide reusable value objects for:
+
+- Embedded documents in domain models
+- Shared DTOs and configuration objects
+- Type-safe schemas across your application
+- Internationalized data structures
+
+## Core Principles
+
+- **Reusability**: Designed for cross-module consumption
+- **Stateless**: Pure data containers without business logic
+- **Type-Safe**: Full TypeScript integration with runtime validation
+- **Composable**: Embeddable within larger domain models
+- **I18n Ready**: Built-in translation support
+
+## File Structure
+
+```
+{domain}/lib/
+└── __scalar/                  // Special scalar directory
+    └── [scalarName]/          // camelCase scalar name
+        ├── [name].constant.ts   // Schema definition
+        ├── [name].dictionary.ts // I18n translations
+        └── [name].document.ts   // Method extensions (optional)
+```
+
+## File Responsibilities
+
+| File Type         | Purpose                                                          |
+| ----------------- | ---------------------------------------------------------------- |
+| `*.constant.ts`   | Defines schema with `@Model.Scalar` and `@Field.Prop` decorators |
+| `*.dictionary.ts` | Provides internationalization with `ModelDictionary<Type>`       |
+| `*.document.ts`   | Extends functionality with custom methods using `by()` decorator |
+
+## Naming Conventions
+
+| Element          | Convention             | Example                     |
+| ---------------- | ---------------------- | --------------------------- |
+| Scalar Directory | `camelCase`            | `geoLocation`               |
+| Constant File    | `[name].constant.ts`   | `geoLocation.constant.ts`   |
+| Dictionary File  | `[name].dictionary.ts` | `geoLocation.dictionary.ts` |
+| Document File    | `[name].document.ts`   | `geoLocation.document.ts`   |
+| Scalar Class     | `PascalCase`           | `GeoLocation`               |
+| Enum Values      | `camelCase`            | `highAccuracy`              |
+| Dictionary Keys  | `kebab-case` prefixes  | `desc-fieldName`            |
+
+## Core Components
+
+1. **Constant File**: Schema definition with typed fields and validation
+2. **Dictionary File**: I18n translations for model metadata, fields and enums
+3. **Document File**: Optional method extensions for data transformations
+
+## Key Rules
+
+1. One scalar class per file with matching `@Model.Scalar` parameter
+2. All fields require decorators (`@Field.Prop`, `@Field.Hidden`, etc.)
+3. Dictionary must include all fields/enums with `modelName`/`modelDesc`
+4. Use `satisfies ModelDictionary<Type>` for dictionary type safety
+
+## Best Practices
+
+- Design for maximum reusability across modules
+- Keep scalars focused and lightweight
+- Use immutable fields for invariant data
+- Provide complete I18n coverage in dictionaries
+- Add document methods only for data transformations
+- Validate fields with options (min/max, minlength/maxlength)
+
+## Integration Points
+
+- **Domain Models**: Embedded as value objects
+- **GraphQL**: Auto-generated types and enums
+- **Validation**: Runtime type checking through decorators
+- **Internationalization**: Consistent terminology via dictionaries
+- **API Contracts**: Shared request/response payloads
+
+Scalar modules provide foundational data structures that enable consistent, type-safe modeling across Akan.js applications while promoting code reuse and maintainability.

package/cli/guidelines/sharedUiUsage/sharedUiUsage.generate.json

@@ -0,0 +1,108 @@
+{
+  "title": "Shared UI Components Usage Guide",
+  "description": "Comprehensive guide on using shared library UI components in Akan.js applications",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Core shared UI component library structure",
+      "path": "libs/shared/ui/index.ts"
+    },
+    {
+      "type": "source",
+      "description": "Field component implementations (form inputs)",
+      "path": "libs/shared/ui/Field.tsx"
+    },
+    {
+      "type": "source",
+      "description": "Data component implementations (tables, lists, visualization)",
+      "path": "libs/shared/ui/Data/index_.tsx"
+    },
+    {
+      "type": "source",
+      "description": "Load component implementations (data fetching)",
+      "path": "libs/shared/ui/Load/index_.tsx"
+    },
+    {
+      "type": "source",
+      "description": "Model component implementations (CRUD operations)",
+      "path": "libs/shared/ui/Model/index_.tsx"
+    },
+    {
+      "type": "source",
+      "description": "System component implementations (providers, app utilities)",
+      "path": "libs/shared/ui/System/index.tsx"
+    },
+    {
+      "type": "source",
+      "description": "Only component implementations (conditional rendering)",
+      "path": "libs/shared/ui/Only/index.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Field components usage examples",
+      "path": "{apps,libs}/*/lib/*/*.{Template,Unit,View,Zone}.tsx",
+      "filterText": "Field} from \"@shared/ui\"",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Data components usage examples",
+      "path": "{apps,libs}/*/lib/*/*.{Zone,View}.tsx",
+      "filterText": "Data} from \"@shared/ui\"",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Load components usage examples",
+      "path": "{apps,libs}/*/lib/*/*.{Zone,View}.tsx",
+      "filterText": "Load} from \"@shared/ui\"",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Model components usage examples",
+      "path": "{apps,libs}/*/lib/*/*.{Template,Unit,Util,Zone}.tsx",
+      "filterText": "Model} from \"@shared/ui\"",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Only component usage examples",
+      "path": "{apps,libs}/*/lib/*/*.{Unit,View,Util}.tsx",
+      "filterText": "Only} from \"@shared/ui\"",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Complex form examples with validation",
+      "path": "{apps,libs}/*/lib/*/*.Template.tsx",
+      "filterText": "validate",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Store integration examples",
+      "path": "{apps,libs}/*/lib/*/*.{Template,Unit,View,Zone}.tsx",
+      "filterText": "sliceName",
+      "sample": 5
+    }
+  ],
+  "update": {
+    "filePath": "./sharedUiUsage.instruction.md",
+    "contents": [
+      "Overview of Shared UI Components",
+      "Component Namespaces (Field, Data, Load, Model, System, Only, Editor, Property)",
+      "Basic Component Usage",
+      "Form Fields and Validation",
+      "Data Management Components",
+      "Loading and Data Fetching",
+      "CRUD Operations",
+      "Conditional Rendering",
+      "Store Integration",
+      "Common Patterns and Best Practices",
+      "Troubleshooting"
+    ],
+    "rules": []
+  },
+  "page": "/model/[model]"
+}