@akanjs/cli 0.0.142 → 0.0.144

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

@@ -0,0 +1,347 @@
+# 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 model 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  // model definition
+        └── <scalarName>.dictionary.ts // translations
+```
+
+### Basic Structure
+
+```typescript
+import { ModelDictionary } from "@akanjs/dictionary";
+import type { YourModel } from "./your-model.constant";
+
+const modelDictionary = {
+  // Required model metadata
+  modelName: ["Model Name", "모델 이름"],
+  modelDesc: ["Model description", "모델 설명"],
+
+  // Field translations with descriptions
+  fieldName: ["Field Label", "필드 라벨"],
+  "desc-fieldName": ["Field description", "필드 설명"],
+
+  // Enum translations with descriptions
+  "enum-status-active": ["Active", "활성"],
+  "enumdesc-status-active": ["Active status", "활성 상태"],
+} satisfies ModelDictionary<YourModel>;
+
+export const yourModelDictionary = modelDictionary;
+```
+
+## Required Imports
+
+```typescript
+import { ModelDictionary } from "@akanjs/dictionary";
+import type { YourModel } from "./your-model.constant";
+```
+
+## Translation Patterns
+
+### 1. Model Metadata (Required)
+
+Every scalar dictionary must include these two translations at the beginning:
+
+```typescript
+modelName: ["User", "사용자"],         // Short display name
+modelDesc: ["User account", "사용자 계정"], // Longer description
+```
+
+### 2. Field Translations
+
+Each field from the constant file must have both a label and description:
+
+```typescript
+// Field label
+username: ["Username", "사용자명"],
+
+// Field description (must follow immediately after the field)
+"desc-username": ["User's login name", "로그인에 사용하는 이름"],
+```
+
+### 3. Enum Value Translations
+
+Each enum value must have both a label and description:
+
+```typescript
+// Enum value label
+"enum-status-active": ["Active", "활성"],
+
+// Enum value description (must follow immediately)
+"enumdesc-status-active": ["Account is active", "계정이 활성화됨"],
+```
+
+### 4. Custom Translations (Optional)
+
+Additional translations specific to this model but not tied to fields:
+
+```typescript
+userProfileTitle: ["User Profile", "사용자 프로필"],
+```
+
+## Section Organization
+
+Use comment separators to organize your translations:
+
+```typescript
+// * ==================== Model ==================== * //
+username: ["Username", "사용자명"],
+"desc-username": ["User's login name", "로그인에 사용하는 이름"],
+// * ==================== Model ==================== * //
+
+// * ==================== Enums ==================== * //
+"enum-status-active": ["Active", "활성"],
+"enumdesc-status-active": ["Account is active", "계정이 활성화됨"],
+// * ==================== Enums ==================== * //
+
+// * ==================== Custom ==================== * //
+userProfileTitle: ["User Profile", "사용자 프로필"],
+// * ==================== Custom ==================== * //
+```
+
+## Type Safety
+
+Always use the `satisfies` operator with `ModelDictionary<YourModel>` to ensure:
+
+1. All required fields from the model are translated
+2. Field names match exactly
+3. Typescript will catch typos and missing fields
+
+```typescript
+} satisfies ModelDictionary<YourModel>; // Type safety check
+```
+
+## Validation Rules and Checklist
+
+### Required Elements
+
+- [ ] Import `ModelDictionary` from `@akanjs/dictionary`
+- [ ] Import the model type from the constant file
+- [ ] Include `modelName` and `modelDesc` translations
+- [ ] Translate all fields from the model
+- [ ] Add descriptions for all fields with `desc-` prefix
+- [ ] Translate all enum values with `enum-field-value` pattern
+- [ ] Add descriptions for all enum values with `enumdesc-` prefix
+- [ ] Use `satisfies ModelDictionary<YourModel>` for type checking
+- [ ] Export with the correct naming convention
+
+### Translation Arrays
+
+- [ ] Each translation is a tuple with exactly two elements
+- [ ] First element is English translation
+- [ ] Second element is Korean translation
+- [ ] No trailing punctuation in translations
+- [ ] First letter capitalized in English
+
+### Organization
+
+- [ ] Group fields with their descriptions
+- [ ] Group enum values with their descriptions
+- [ ] Use standard comment separators
+- [ ] Place model metadata first, then fields, then enums
+
+## Common Mistakes and Fixes
+
+### 1. Missing Field Description
+
+```typescript
+// ❌ Wrong (missing description)
+username: ["Username", "사용자명"],
+
+// ✅ Correct
+username: ["Username", "사용자명"],
+"desc-username": ["User's login name", "로그인에 사용하는 이름"],
+```
+
+### 2. Incorrect Enum Naming Pattern
+
+```typescript
+// ❌ Wrong (incorrect format)
+"enum_status_active": ["Active", "활성"],
+// or
+"enumStatus-active": ["Active", "활성"],
+
+// ✅ Correct
+"enum-status-active": ["Active", "활성"],
+"enumdesc-status-active": ["Account is active", "계정이 활성화됨"],
+```
+
+### 3. Missing Model Metadata
+
+```typescript
+// ❌ Wrong (missing required metadata)
+const modelDictionary = {
+  username: ["Username", "사용자명"],
+  // ...
+
+// ✅ Correct
+const modelDictionary = {
+  modelName: ["User", "사용자"],
+  modelDesc: ["User account", "사용자 계정"],
+  username: ["Username", "사용자명"],
+  // ...
+```
+
+### 4. Incorrect Translation Array Format
+
+```typescript
+// ❌ Wrong (single string, not a tuple)
+username: "Username",
+// or
+username: ["Username"],
+
+// ✅ Correct
+username: ["Username", "사용자명"],
+```
+
+### 5. Missing Type Safety
+
+```typescript
+// ❌ Wrong (no type checking)
+export const userDictionary = modelDictionary;
+
+// ✅ Correct
+const modelDictionary = {
+  // ...
+} satisfies ModelDictionary<User>;
+
+export const userDictionary = modelDictionary;
+```
+
+## Best Practices
+
+### 1. Order Translations Logically
+
+```typescript
+// First: model metadata
+modelName: ["User", "사용자"],
+modelDesc: ["User account", "사용자 계정"],
+
+// Second: fields with descriptions
+username: ["Username", "사용자명"],
+"desc-username": ["User's login name", "로그인에 사용하는 이름"],
+
+// Third: enum values with descriptions
+"enum-status-active": ["Active", "활성"],
+"enumdesc-status-active": ["Account is active", "계정이 활성화됨"],
+
+// Last: custom translations
+profileHeading: ["Profile Details", "프로필 상세정보"],
+```
+
+### 2. Use Clear Comment Separators
+
+```typescript
+// * ==================== Model ==================== * //
+// Fields go here
+// * ==================== Model ==================== * //
+
+// * ==================== Enums ==================== * //
+// Enum translations go here
+// * ==================== Enums ==================== * //
+
+// * ==================== Custom ==================== * //
+// Custom translations go here
+// * ==================== Custom ==================== * //
+```
+
+### 3. Match Constant File Structure
+
+Follow the same field order as in the constant file for easier maintenance.
+
+### 4. Naming Conventions
+
+- Export name should match model name: `userDictionary` for `User` model
+- Field names must exactly match the constant file
+- Use kebab-case for prefix separators: `desc-`, `enum-`, `enumdesc-`
+
+### 5. Consistent Translation Style
+
+- First letter capitalized for English
+- No trailing punctuation
+- Keep translations concise but clear
+- Be consistent in terminology
+
+## Full Example
+
+```typescript
+// File: apps/example/lib/__scalar/user/user.dictionary.ts
+import { ModelDictionary } from "@akanjs/dictionary";
+import type { User } from "./user.constant";
+
+const modelDictionary = {
+  modelName: ["User", "사용자"],
+  modelDesc: ["System user account", "시스템 사용자 계정"],
+
+  // * ==================== Model ==================== * //
+  username: ["Username", "사용자명"],
+  "desc-username": ["Unique login identifier", "고유 로그인 식별자"],
+
+  email: ["Email", "이메일"],
+  "desc-email": ["Contact email address", "연락용 이메일 주소"],
+
+  displayName: ["Display Name", "표시 이름"],
+  "desc-displayName": ["Public name shown to others", "다른 사용자에게 표시되는 이름"],
+
+  status: ["Status", "상태"],
+  "desc-status": ["Account status", "계정 상태"],
+
+  lastLoginAt: ["Last Login", "마지막 로그인"],
+  "desc-lastLoginAt": ["Most recent login time", "가장 최근 로그인 시간"],
+  // * ==================== Model ==================== * //
+
+  // * ==================== Enums ==================== * //
+  "enum-status-active": ["Active", "활성"],
+  "enumdesc-status-active": ["Account is enabled and usable", "계정이 활성화되어 사용 가능함"],
+
+  "enum-status-inactive": ["Inactive", "비활성"],
+  "enumdesc-status-inactive": ["Account is temporarily disabled", "계정이 일시적으로 비활성화됨"],
+
+  "enum-status-banned": ["Banned", "차단됨"],
+  "enumdesc-status-banned": ["Account is permanently disabled", "계정이 영구적으로 비활성화됨"],
+
+  "enum-status-pending": ["Pending", "대기 중"],
+  "enumdesc-status-pending": ["Account awaiting verification", "계정 인증 대기 중"],
+  // * ==================== Enums ==================== * //
+
+  // * ==================== Custom ==================== * //
+  profileHeading: ["User Profile", "사용자 프로필"],
+  accountSettings: ["Account Settings", "계정 설정"],
+  loginHistory: ["Login History", "로그인 기록"],
+  // * ==================== Custom ==================== * //
+} satisfies ModelDictionary<User>;
+
+export const userDictionary = modelDictionary;
+```
+
+## Summary Checklist
+
+1. **Imports**: Import `ModelDictionary` and model type
+2. **Metadata**: Include `modelName` and `modelDesc`
+3. **Fields**: Translate all model fields with descriptions
+4. **Enums**: Translate all enum values with descriptions
+5. **Format**: Use proper prefix patterns (`desc-`, `enum-`, `enumdesc-`)
+6. **Arrays**: Use two-element arrays for all translations
+7. **Organization**: Group related translations with comment separators
+8. **Type Safety**: Use `satisfies ModelDictionary<YourModel>`
+9. **Export**: Name the export to match the model name
+10. **Completeness**: Ensure all fields and enums from the constant file are translated
+
+Following these guidelines will ensure your scalar dictionary files are complete, consistent, and maintainable across the Akan.js framework.

package/src/guidelines/sharedUiUsage/sharedUiUsage.instruction.md

@@ -0,0 +1,318 @@
+# 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
+
+All UI components are available as named exports from the `@shared/ui` package:
+
+```tsx
+import { Field, Data, Load, Model, System, Only, Editor, Property } from "@shared/ui";
+```
+
+Each namespace contains specialized components for specific use cases:
+
+- **Field**: Form inputs and data entry components
+- **Data**: Data visualization and management interfaces
+- **Load**: Data loading patterns with SSR/CSR support
+- **Model**: CRUD operations with modal and inline editing
+- **System**: Application-level providers and utilities
+- **Only**: Conditional rendering based on user state and device
+- **Editor**: Rich text editing capabilities
+- **Property**: Metadata-driven property editing
+
+### 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.field("myModel", "title")}
+        desc={l.desc("myModel", "title")}
+        value={formState.title}
+        onChange={(value) => st.do.setTitleOnMyModel(value)}
+        nullable={false}
+        maxlength={100}
+      />
+
+      <Field.Number
+        label={l.field("myModel", "amount")}
+        desc={l.desc("myModel", "amount")}
+        value={formState.amount}
+        onChange={(value) => st.do.setAmountOnMyModel(value)}
+        min={0}
+        max={1000}
+        unit="KRW"
+      />
+
+      <Field.ToggleSelect
+        label={l.field("myModel", "status")}
+        desc={l.desc("myModel", "status")}
+        value={formState.status}
+        items={cnst.Status}
+        onChange={(status) => st.do.setStatusOnMyModel(status)}
+        model="myModel"
+        field="status"
+      />
+    </>
+  );
+};
+```
+
+### 2. Data Management Components
+
+Data components are used to display and manage collections of data:
+
+```tsx
+import { Data, Model } from "@shared/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 "@shared/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 "@shared/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.field("user", "name")} desc={l.desc("user", "name")} 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.