@akanjs/cli 1.0.19 → 2.1.0-rc.0

package/src/guidelines/scalarDictionary/scalarDictionary.instruction.md

@@ -1,273 +0,0 @@
-# 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/src/guidelines/scalarModule/scalarModule.instruction.md

@@ -1,81 +0,0 @@
-# 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/src/guidelines/sharedUiUsage/sharedUiUsage.instruction.md

@@ -1,310 +0,0 @@
-# Using Shared UI Components in Akan.js
-
-## Overview
-
-The `@shared/ui` library in the Akan.js framework provides a comprehensive set of React components designed for building data-driven applications. This library follows consistent patterns and deeply integrates with the application's store system, making it efficient to develop complex UIs with minimal code.
-
-## Key Features
-
-- **Store-Centric Architecture**: Seamless integration with standardized store slices using naming conventions
-- **Type-Safe Components**: Extensive TypeScript generic usage for compile-time safety
-- **Internationalization**: Built-in multi-language support throughout all components
-- **Responsive Design**: Mobile-first approach with adaptive breakpoints
-- **Performance Optimized**: Components use memoization, lazy loading, and efficient rendering strategies
-- **Accessibility Compliant**: Proper ARIA attributes and keyboard navigation
-- **Extensible Architecture**: Plugin systems and customizable renderers
-- **Unidirectional Data Flow**: Predictable state management patterns
-
-## Getting Started
-
-### Importing Components
-
-UI components are available as named exports from the `@shared/ui` package:
-
-```tsx
-import { Field, Only, Editor } from "@shared/ui";
-```
-
-Each namespace contains specialized components for specific use cases:
-
-- **Field**: Form inputs and data entry components
-- **Only**: Conditional rendering based on user state and device
-- **Editor**: Rich text editing capabilities
-
-### Component Organization in Your Module
-
-When building a module in Akan.js, you should organize your components following the pattern:
-
-```
-/lib/myFeature/
-  MyFeature.constant.ts     # Types, GraphQL schema, enums
-  MyFeature.service.ts      # Business logic and database operations
-  MyFeature.signal.ts       # Client state management and API calls
-  MyFeature.store.ts        # Zustand store definitions
-  MyFeature.Template.tsx    # Form templates for create/edit
-  MyFeature.Unit.tsx        # Card/list item components
-  MyFeature.View.tsx        # Full page views
-  MyFeature.Zone.tsx        # Layout containers
-  MyFeature.Util.tsx        # Utility components
-```
-
-## Usage Examples
-
-### 1. Basic Form Fields
-
-Form fields are used for data entry and are integrated with the validation system:
-
-```tsx
-import { Field } from "@shared/ui";
-import { usePage } from "@shared/client";
-
-const MyComponent = () => {
-  const { l } = usePage(); // For internationalization
-
-  return (
-    <>
-      <Field.Text
-        label={l("myModel.title")}
-        desc={l("myModel.title.desc")}
-        value={formState.title}
-        onChange={(value) => st.do.setTitleOnMyModel(value)}
-        nullable={false}
-        maxlength={100}
-      />
-
-      <Field.Number
-        label={l("myModel.amount")}
-        desc={l("myModel.amount.desc")}
-        value={formState.amount}
-        onChange={(value) => st.do.setAmountOnMyModel(value)}
-        min={0}
-        max={1000}
-        unit="KRW"
-      />
-
-      <Field.ToggleSelect
-        label={l("myModel.status")}
-        desc={l("myModel.status.desc")}
-        value={formState.status}
-        items={cnst.Status}
-        onChange={(status) => st.do.setStatusOnMyModel(status)}
-      />
-    </>
-  );
-};
-```
-
-### 2. Data Management Components
-
-Data components are used to display and manage collections of data:
-
-```tsx
-import { Data, Model } from "@akanjs/ui";
-
-export const MyFeatureAdmin = ({ sliceName = "myFeature" }) => {
-  return (
-    <Data.ListContainer
-      sliceName={sliceName}
-      renderItem={MyFeature.Unit.Card}
-      renderDashboard={MyFeature.Util.Stat}
-      renderTemplate={MyFeature.Template.General}
-      renderView={(myFeature) => <MyFeature.View.General myFeature={myFeature} />}
-      columns={["id", "title", "status", "createdAt"]}
-      actions={(myFeature) => ["remove", "edit", "view"]}
-    />
-  );
-};
-```
-
-### 3. Loading and Data Fetching
-
-Load components handle data fetching and state management:
-
-```tsx
-import { Load } from "@akanjs/ui";
-
-export const MyFeatureView = ({ id }) => {
-  return (
-    <Load.View
-      loader={() => fetch.myFeature(id)}
-      render={(myFeature) => (
-        <div className="space-y-4 p-4">
-          <h1>{myFeature.title}</h1>
-          <p>{myFeature.description}</p>
-        </div>
-      )}
-    />
-  );
-};
-
-export const MyFeatureList = () => {
-  return (
-    <Load.Units
-      init={st.do.initMyFeature}
-      renderItem={(myFeature) => <MyFeature.Unit.Card key={myFeature.id} myFeature={myFeature} />}
-      filter={(myFeature) => myFeature.isActive}
-      sort={(a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()}
-    />
-  );
-};
-```
-
-### 4. CRUD Operations
-
-Model components handle create, read, update and delete operations:
-
-```tsx
-import { Model } from "@akanjs/ui";
-
-export const CreateMyFeature = () => {
-  return (
-    <Model.NewWrapper sliceName="myFeature">
-      <button className="btn btn-primary">Create New</button>
-    </Model.NewWrapper>
-  );
-};
-
-export const EditMyFeature = ({ id }) => {
-  return (
-    <Model.EditModal
-      sliceName="myFeature"
-      id={id}
-      renderTitle={(myFeature) => `Edit ${myFeature.title}`}
-      onSubmit="closeModal"
-    />
-  );
-};
-
-export const ViewMyFeature = ({ id }) => {
-  return (
-    <Model.ViewModal
-      id={id}
-      renderView={(myFeature) => <MyFeature.View.General myFeature={myFeature} />}
-      renderAction={(myFeature) => (
-        <Model.EditWrapper sliceName="myFeature" id={myFeature.id}>
-          <button className="btn btn-secondary">Edit</button>
-        </Model.EditWrapper>
-      )}
-    />
-  );
-};
-```
-
-### 5. Conditional Rendering
-
-Only components handle conditional rendering based on user roles or device:
-
-```tsx
-import { Only } from "@shared/ui";
-
-export const AdminFeature = () => {
-  return (
-    <Only.Admin roles={["superadmin", "manager"]}>
-      <div className="bg-red-100 p-4">Admin Only Content</div>
-    </Only.Admin>
-  );
-};
-
-export const MobileFeature = () => {
-  return (
-    <>
-      <Only.Mobile>
-        <div className="compact-view">Mobile View</div>
-      </Only.Mobile>
-
-      <Only.Web>
-        <div className="expanded-view">Desktop View</div>
-      </Only.Web>
-    </>
-  );
-};
-```
-
-## Integration with Store System
-
-The components integrate deeply with the Akan.js store system using standardized naming conventions:
-
-```tsx
-// Field.ParentId example
-<Field.ParentId
-  label="Organization"
-  sliceName="orgInUser" // References st.slice.orgInUser
-  value={userForm.org}
-  onChange={st.do.setOrgOnUser}
-  renderOption={(org) => org.name}
-/>
-```
-
-The components automatically use naming conventions to interact with your store:
-
-- `${modelName}List` for accessing list data
-- `init${ModelName}` for initialization functions
-- `${modelName}Form` for form state
-- `add${ModelName}Files` for file uploads
-
-## Common Patterns
-
-### Render Props
-
-Many components use render props for customization:
-
-```tsx
-<Data.ListContainer
-  renderItem={(item) => <MyItem item={item} />}
-  renderDashboard={(props) => <MyDashboard {...props} />}
-  renderTemplate={(form) => <MyTemplate form={form} />}
-  renderView={(model) => <MyView model={model} />}
-/>
-```
-
-### Internationalization
-
-Components automatically integrate with the internationalization system:
-
-```tsx
-const { l } = usePage();
-
-<Field.Text label={l("user.name")} desc={l("user.name.desc")} placeholder={l("user.namePlaceholder")} />;
-```
-
-### State Management Integration
-
-Components seamlessly integrate with the state management:
-
-```tsx
-<Field.ToggleSelect value={userForm.role} onChange={(role) => st.do.setRoleOnUser(role)} items={cnst.UserRole} />
-```
-
-## Best Practices
-
-1. **Use the appropriate component type** for each part of your feature:
-   - Use **Field** components for data entry
-   - Use **Data** components for data visualization and management
-   - Use **Load** components for data fetching
-   - Use **Model** components for CRUD operations
-
-2. **Leverage the internationalization system** by using the `l` function for all user-facing text
-
-3. **Follow the naming conventions** for store slices and actions to ensure proper integration
-
-4. **Use render props** for customization rather than creating custom components
-
-5. **Utilize conditional rendering** with Only components rather than conditional logic in your components
-
-6. **Structure your modules** following the Akan.js pattern with separate files for each concern
-
-## Troubleshooting
-
-Common issues and solutions:
-
-1. **Component not updating when store changes**: Ensure you're using the correct store slice name and following naming conventions
-
-2. **Field validation errors**: Check the validation rules and ensure you're providing the correct props (minlength, maxlength, etc.)
-
-3. **Data not loading**: Verify that the loader function is correctly implemented and returning data in the expected format
-
-4. **Missing translations**: Ensure that all keys are defined in your dictionary files and that you're using the correct model and field names
-
-## Conclusion
-
-The shared UI library provides a comprehensive set of components for building data-driven applications with Akan.js. By following the patterns and conventions outlined in this guide, you can efficiently build complex UIs with minimal code.