@akanjs/cli 0.0.146 → 0.0.147

package/cjs/src/guidelines/modelTemplate/modelTemplate.instruction.md

@@ -10,568 +10,595 @@ Model.Template.tsx files are client-side React components that define the form s
 4. **UI Consistency**: Ensure uniform form design across the application
 5. **Type Safety**: Enforce data types based on Model.Constant definitions
 6. **Internationalization**: Support multi-language form fields with dictionary integration
+7. **Component Reusability**: Enable form sections to be used in multiple contexts (pages, modals, utilities)
 
 ## File Location and Naming Convention
 
+### Standard Path
+
 ```
-libs/[domain]/lib/[model]/[Model].Template.tsx
+{apps,libs}/*/lib/[model]/[Model].Template.tsx
 ```
 
-For example:
+### Examples:
 
-- `libs/shared/lib/admin/Admin.Template.tsx`
-- `apps/akamir/lib/rewardRequest/RewardRequest.Template.tsx`
+- `libs/game/lib/map/Map.Template.tsx`
+- `apps/lu/lib/feeling/Feeling.Template.tsx`
+- `libs/shared/lib/user/User.Template.tsx`
 
-The file should export one or more named components, typically including:
+### Naming Rules:
 
-- `General`: Main form template used in most scenarios
-- `Advanced`: Optional complex fields for advanced forms
-- `Compact`: Simplified version for inline editing or mobile views
+- PascalCase for model names (e.g., `Map.Template.tsx`)
+- Place in the same directory as other model files (`[Model].store.ts`, `[Model].constant.ts`)
+- Export named components (typically `General`, `Advanced`, `Compact`)
 
-## Creating Model.Template.tsx Files
+## Basic Structure and Component Patterns
 
-### Basic Structure
+### Minimum Structure
 
 ```tsx
-// File: libs/[domain]/lib/[model]/[Model].Template.tsx
 "use client";
-import { Field } from "@akanjs/client";
-import { cnst } from "@[project]/constant";
+import { Field } from "@shared/ui";
 import { st } from "@[project]/client";
 import { usePage } from "@[project]/lib/usePage";
 
 export const General = ({ id }: { id?: string }) => {
-  const form = st.use.[model]Form(); // e.g., st.use.adminForm()
+  const form = st.use.[model]Form();
   const { l } = usePage();
 
   return (
-    <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+    <div className="grid grid-cols-1 gap-4">
       <Field.Text
-        label={l.field.name}
-        value={form.name}
-        onChange={(v) => st.do.setNameOn[Model](v)}
-        required
-        maxLength={30}
-      />
-
-      <Field.Select
-        label={l.field.status}
-        value={form.status}
-        options={cnst.[Model]Status.options}
-        onChange={(v) => st.do.setStatusOn[Model](v)}
+        label={l.field("model", "fieldName")}
+        value={form.fieldName}
+        onChange={(v) => st.do.setFieldNameOn[Model](v)}
       />
-
-      {/* Add other fields */}
     </div>
   );
 };
 ```
 
-### Integration with Store State
-
-Model.Template components connect to Zustand store slices that follow a consistent pattern:
+### Component Organization Patterns
 
 ```tsx
-// Form state (defined in model.store.ts)
-interface [Model]State {
-  [model]Form: cnst.[Model]Input;
-  // other state properties...
-}
+// Single-file pattern
+export const General = () => { /* main form */ }
+export const Advanced = () => { /* advanced fields */ }
+
+// Multi-file pattern (recommended)
+[Model].Template/
+├─ General.tsx
+├─ Sections/
+│  ├─ BasicInfo.tsx
+│  ├─ ContactDetails.tsx
+```
 
-// Form actions (defined in model.store.ts)
-interface [Model]Action {
-  setNameOn[Model]: (name: string) => void;
-  setStatusOn[Model]: (status: cnst.[Model]Status) => void;
-  // other actions...
-}
+## Integration with Store State Management
 
-// In Template component
+### Connecting to Zustand Store
+
+```tsx
+// Access form state
 const form = st.use.[model]Form();
-const { setNameOn[Model] } = st.do;
+
+// Update fields
+<Field.Text
+  value={form.name}
+  onChange={st.do.setNameOn[Model]}
+/>
+```
+
+### Store Action Patterns
+
+```tsx
+// Simple field update
+st.do.setNameOn[Model](value);
+
+// Nested field update
+st.do.writeOn[Model](["address", "city"], value);
+
+// List operations
+st.do.addItemOn[Model](newItem);
+st.do.removeItemOn[Model](index);
 ```
 
-### Field Types and Components
+### Initialization and Cleanup
 
-Akan.js provides a comprehensive set of form field components in the `Field` namespace:
+```tsx
+useEffect(() => {
+  if (id) {
+    // Load existing data
+    void st.do.load[Model](id);
+  }
+
+  return () => {
+    // Reset form on unmount
+    st.do.reset[Model]Form();
+  };
+}, [id]);
+```
+
+## Field Types and Form Components
+
+### Core Field Components
+
+| Component            | Usage                 | Example                                     |
+| -------------------- | --------------------- | ------------------------------------------- |
+| `Field.Text`         | Text input            | `<Field.Text value={form.name} />`          |
+| `Field.TextArea`     | Multi-line text       | `<Field.TextArea value={form.desc} />`      |
+| `Field.Number`       | Numeric input         | `<Field.Number value={form.age} />`         |
+| `Field.Select`       | Dropdown selection    | `<Field.Select options={statusOptions} />`  |
+| `Field.ToggleSelect` | Toggleable options    | `<Field.ToggleSelect items={types} />`      |
+| `Field.Tags`         | Tag input             | `<Field.Tags value={form.tags} />`          |
+| `Field.Img`          | Image upload          | `<Field.Img sliceName="model" />`           |
+| `Field.Date`         | Date picker           | `<Field.Date value={form.dueDate} />`       |
+| `Field.Parent`       | Relationship selector | `<Field.Parent sliceName="relatedModel" />` |
+| `Field.Slate`        | Rich text editor      | `<Field.Slate valuePath="content" />`       |
+
+### Complex Field Example
 
 ```tsx
-<Field.Text />      // Text input
-<Field.Textarea />  // Multi-line text
-<Field.Number />    // Numeric input
-<Field.Select />    // Dropdown selection
-<Field.Checkbox />  // Toggle input
-<Field.Date />      // Date picker
-<Field.File />      // File upload
-<Field.Image />     // Image upload with preview
-<Field.Radio />     // Radio button group
-<Field.Switch />    // Toggle switch
-<Field.Tags />      // Tag input
-<Field.Time />      // Time picker
-<Field.Color />     // Color picker
-<Field.Autocomplete /> // Text input with suggestions
-<Field.MultiSelect /> // Multi-value selection
-<Field.RichText />  // Rich text editor
-<Field.CodeEditor /> // Code editor
-<Field.Location />  // Map location picker
-<Field.Slider />    // Numeric range slider
-<Field.Password />  // Password input with visibility toggle
+<Field.List
+  label={l.field("map", "spawnPositions")}
+  value={form.spawnPositions}
+  onAdd={() => st.do.addSpawnPosition(defaultPosition)}
+  renderItem={(position, idx) => (
+    <div className="flex gap-4">
+      <Field.Text value={position.key} onChange={(v) => st.do.writeOnMap(["spawnPositions", idx, "key"], v)} />
+      <Field.DoubleNumber
+        value={position.position}
+        onChange={(v) => st.do.writeOnMap(["spawnPositions", idx, "position"], v)}
+      />
+    </div>
+  )}
+/>
 ```
 
-### Form Validation
+## Form Validation Approaches
 
-Field components support validation through props:
+### Field-Level Validation
 
 ```tsx
-<Field.Text
-  label="Email"
+<Field.Email
   value={form.email}
-  onChange={(v) => st.do.setEmailOnUser(v)}
   validate={(v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)}
   errorMessage="Invalid email format"
   required
-  maxLength={50}
 />
 ```
 
-Common validation options:
+### Custom Validation Functions
+
+```tsx
+// Phone validation
+<Field.Phone
+  value={form.phone}
+  validate={(v) => isPhoneNumber(v)}
+/>
+
+// Custom business rule
+<Field.Number
+  value={form.quantity}
+  validate={(v) => v > 0 ? true : "Must be positive"}
+/>
+```
+
+### Validation Props
 
-- `required`: Makes the field required
-- `maxLength`: Maximum character length
-- `minLength`: Minimum character length
-- `min`/`max`: Number range limits
-- `pattern`: Regex pattern for validation
-- `validate`: Custom validation function
-- `errorMessage`: Custom error message
+| Prop                    | Description          | Example                         |
+| ----------------------- | -------------------- | ------------------------------- |
+| `required`              | Mandatory field      | `required`                      |
+| `min`/`max`             | Number range         | `min={0} max={100}`             |
+| `minLength`/`maxLength` | Text length          | `minLength={2}`                 |
+| `validate`              | Custom validation fn | `validate={(v) => isValid(v)}`  |
+| `errorMessage`          | Custom error text    | `errorMessage="Invalid format"` |
 
-### Internationalization
+## Internationalization with usePage
 
-Templates should use the `usePage()` hook to access localized strings:
+### Dictionary Integration
 
 ```tsx
 const { l } = usePage();
 
+// Basic field
+<Field.Text label={l.field("model", "name")} />
+
+// With description
 <Field.Text
-  label={l.field.email}
-  placeholder={l.desc.enterEmail}
-  // ...
-/>;
+  label={l.field("model", "email")}
+  desc={l.desc("model", "email")}
+/>
+
+// Dynamic content
+<div>{l(`profileVerify.enum-type-${type}`)}</div>
 ```
 
-## Form Layout Patterns
+### Dictionary Structure
 
-### Basic Grid Layout
+```tsx
+// Example dictionary
+export const dictionary = {
+  field: {
+    model: {
+      name: { en: "Name", ko: "이름" },
+      email: { en: "Email", ko: "이메일" },
+    },
+  },
+  desc: {
+    model: {
+      email: { en: "Your contact email", ko: "연락처 이메일" },
+    },
+  },
+};
+```
+
+## Form Layout Patterns and Best Practices
+
+### Responsive Grid Layout
 
 ```tsx
 <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-  <Field.Text label="First Name" /* ... */ />
-  <Field.Text label="Last Name" /* ... */ />
-  <Field.Email label="Email" className="md:col-span-2" /* ... */ />
+  <Field.Text label="First Name" />
+  <Field.Text label="Last Name" />
+  <Field.Email label="Email" className="md:col-span-2" />
 </div>
 ```
 
-### Grouped Fields
+### Section Grouping
 
 ```tsx
-<div className="space-y-6">
-  <fieldset className="rounded-md border p-4">
-    <legend className="text-lg font-medium">{l.section.personalInfo}</legend>
-    <div className="grid grid-cols-1 gap-4 md:grid-cols-2">{/* Personal info fields */}</div>
-  </fieldset>
-
-  <fieldset className="rounded-md border p-4">
-    <legend className="text-lg font-medium">{l.section.contactInfo}</legend>
-    <div className="grid grid-cols-1 gap-4 md:grid-cols-2">{/* Contact info fields */}</div>
-  </fieldset>
-</div>
+<section className="mb-6">
+  <h3 className="mb-3 text-xl font-semibold">Personal Information</h3>
+  <div className="space-y-4">
+    <Field.Text label="Full Name" />
+    <Field.Date label="Birth Date" />
+  </div>
+</section>
 ```
 
-### Conditional Fields
+### Conditional Sections
 
 ```tsx
 {
   form.type === "business" && (
-    <>
-      <Field.Text label="Company Name" /* ... */ />
-      <Field.Text label="Tax ID" /* ... */ />
-    </>
+    <section>
+      <h3>Business Details</h3>
+      <Field.Text label="Company Name" />
+      <Field.Text label="Tax ID" />
+    </section>
   );
 }
 ```
 
-### Nested Components
+### Best Practices
 
-Break complex forms into nested components for better organization:
-
-```tsx
-export const General = ({ id }: { id?: string }) => {
-  // Main form logic
-  return (
-    <div className="space-y-6">
-      <BasicInfo />
-      <ContactDetails />
-      <Preferences />
-    </div>
-  );
-};
-
-const BasicInfo = () => {
-  const form = st.use.userForm();
-  // Component implementation
-};
-```
+1. Use consistent spacing (`gap-4`, `mb-4`)
+2. Group related fields visually
+3. Place important fields above the fold
+4. Use appropriate field types for data
+5. Provide clear validation feedback
+6. Optimize for mobile-first experiences
 
-## Using Model.Template in Pages
+## Using Templates in Pages, Utilities, and Zones
 
-### Creation Page
+### In Page Components
 
 ```tsx
-// apps/app-name/app/[lang]/[model]/new/page.tsx
-import { Model } from "@shared/ui";
-import { [Model] } from "@[project]/client";
-
-export default function NewModelPage() {
-  return (
-    <Model.Edit
-      sliceName="[model]"
-      type="form"
-      onSubmit="/[model]"
-    >
-      <[Model].Template.General />
-    </Model.Edit>
-  );
-}
+// Creation page
+<Model.Edit sliceName="model" type="form">
+  <Model.Template.General />
+</Model.Edit>
+
+// Edit page
+<Model.Edit modelId={params.id} sliceName="model">
+  <Model.Template.General id={params.id} />
+</Model.Edit>
 ```
 
-### Editing Page
+### In Utility Components
 
 ```tsx
-// apps/app-name/app/[lang]/[model]/[id]/edit/page.tsx
-import { Model } from "@shared/ui";
-import { [Model] } from "@[project]/client";
-
-export default function EditModelPage({ params }) {
-  return (
-    <Model.Edit
-      modelId={params.id}
-      sliceName="[model]"
-      renderTitle={l => l.title.edit[model]}
-    >
-      <[Model].Template.General id={params.id} />
-    </Model.Edit>
-  );
-}
+// Modal-based editing
+<Modal.Open opens={`edit-${id}`}>
+  <button>Edit</button>
+</Modal.Open>
+
+<Modal.Window name={`edit-${id}`}>
+  <Model.Edit modelId={id} sliceName="model">
+    <Model.Template.Compact />
+  </Model.Edit>
+</Modal.Window>
 ```
 
-## Using Model.Template in Utility Components
-
-### In Modal Dialogs
+### In Zone Components
 
 ```tsx
-// libs/[domain]/lib/[model]/[Model].Util.tsx
-import { Modal, Model } from "@util/ui";
-import { [Model] } from "@[project]/client";
+// List view with create form
+<Data.ListContainer
+  renderTemplate={() => <Model.Template.General />}
+/>
 
-export const EditButton = ({ id }: { id: string }) => (
-  <>
-    <Modal.Open opens={`edit-${id}`}>
-      <button>Edit</button>
-    </Modal.Open>
-
-    <Modal.Window name={`edit-${id}`}>
-      <Model.Edit
-        modelId={id}
-        sliceName="[model]"
-      >
-        <[Model].Template.General id={id} />
-      </Model.Edit>
-    </Modal.Window>
-  </>
-);
+// Inline editor
+<Zone.InlineEdit>
+  <Model.Template.Compact />
+</Zone.InlineEdit>
 ```
 
-### In Custom Forms
+## State Management and Lifecycle Methods
+
+### Lifecycle Hooks
 
 ```tsx
-// libs/[domain]/lib/[model]/[Model].Util.tsx
-import { st } from "@[project]/client";
-import { [Model] } from "@[project]/client";
+useEffect(() => {
+  // Initialize form data
+  if (id) void st.do.loadModel(id);
 
-export const CustomFormSection = () => {
-  const form = st.use.[model]Form();
+  // Initialize related data
+  void st.do.initRelatedData();
 
-  return (
-    <div>
-      <h3>Advanced Settings</h3>
-      <[Model].Template.Advanced />
-      <button onClick={st.do.submit[model]}>Save</button>
-    </div>
-  );
-};
+  return () => {
+    // Cleanup on unmount
+    st.do.resetModelForm();
+  };
+}, [id]);
 ```
 
-## Using Model.Template in Zone Components
+### Form State Flow
 
-### List View Creation
+1. **Initialization**: Load data when component mounts
+2. **User Interaction**: Update state via store actions
+3. **Validation**: Validate on change/blur/submit
+4. **Submission**: Process form data
+5. **Cleanup**: Reset state on unmount
 
-```tsx
-// libs/[domain]/lib/[model]/[Model].Zone.tsx
-import { Data } from "@shared/ui";
-import { [Model] } from "@[project]/client";
-
-export const AdminZone = () => (
-  <Data.ListContainer
-    renderTemplate={() => <[Model].Template.General />}
-    // ...other props
-  />
-);
-```
+## Performance Optimization Techniques
 
-### Inline Editing
+### Memoization
 
 ```tsx
-// libs/[domain]/lib/[model]/[Model].Zone.tsx
-import { Model } from "@shared/ui";
-import { [Model] } from "@[project]/client";
-
-export const InlineEditor = ({ id }: { id: string }) => (
-  <Model.EditInline
-    modelId={id}
-    sliceName="[model]"
-  >
-    <[Model].Template.Compact id={id} />
-  </Model.EditInline>
-);
+const FormSection = React.memo(({ fields }) => {
+  // Component implementation
+});
 ```
 
-## Best Practices
-
-### 1. Component Organization
-
-Split complex templates into logical sections:
+### Debounced Inputs
 
 ```tsx
-// Recommended structure
-[Model].Template.tsx
-├─ General.tsx   // Main form
-├─ Advanced.tsx  // Advanced fields
-├─ Compact.tsx   // Simplified form
-└─ Sections/     // Form sections
-   ├─ Basic.tsx
-   └─ Metadata.tsx
-```
+import { useDebounce } from "@akanjs/hooks";
 
-### 2. State Management
+const [input, setInput] = useState("");
+const debouncedInput = useDebounce(input, 300);
 
-- Use `st.use.[model]Form()` for accessing form state
-- Use `st.do.set[Field]On[Model]()` for updating form fields
-- Perform form initialization in useEffect:
-
-```tsx
 useEffect(() => {
-  if (id) {
-    void sig.[model].get[Model](id).then(data => {
-      st.do.set[Model]Form(data.[model]);
-    });
-  }
-
-  // Reset form on unmount
-  return () => st.do.reset[Model]Form();
-}, [id]);
+  st.do.search(debouncedInput);
+}, [debouncedInput]);
 ```
 
-### 3. Validation Approaches
-
-- **Field-level validation**: Use the `validate` prop on field components
-- **Form-level validation**: Use custom validation logic before submission
-- **Server-side validation**: Always validate in the service layer as well
+### Lazy Loading
 
 ```tsx
-// Form-level validation example
-const handleSubmit = () => {
-  const errors = validateForm(form);
-  if (Object.keys(errors).length > 0) {
-    st.do.setFormErrors(errors);
-    return;
-  }
+const HeavyEditor = React.lazy(() => import("./HeavyEditor"));
 
-  st.do.submit[Model]();
-};
+<Suspense fallback={<Loader />}>
+  <HeavyEditor />
+</Suspense>;
 ```
 
-### 4. Performance Optimization
+## Accessibility Considerations
 
-- Memoize components with `React.memo` for complex forms
-- Use controlled components consistently
-- Debounce input changes for expensive operations:
+### Accessible Form Patterns
 
 ```tsx
-import { useDebounce } from "@[project]/lib/hooks";
-
-const debouncedValue = useDebounce(inputValue, 300);
+// Proper labeling
+<label htmlFor="email-field">Email</label>
+<input id="email-field" type="email" />
+
+// ARIA attributes
+<div
+  role="alert"
+  aria-live="polite"
+>
+  {error && <p>{error}</p>}
+</div>
 
-useEffect(() => {
-  // Perform expensive operation with debouncedValue
-}, [debouncedValue]);
+// Keyboard navigation
+<button onKeyDown={handleKeyNavigation}>Submit</button>
 ```
 
-### 5. Accessibility
+### Accessibility Requirements
 
-- Associate labels with inputs using `htmlFor`/`id`
-- Provide ARIA attributes for custom components
-- Ensure keyboard navigation works properly
-- Use semantic HTML elements
+1. Associate all inputs with labels
+2. Provide ARIA attributes for custom components
+3. Ensure proper focus management
+4. Support keyboard navigation
+5. Provide error messages as live regions
+6. Use sufficient color contrast
 
-```tsx
-<label htmlFor="name-field" className="block text-sm font-medium">
-  Name
-</label>
-<input
-  id="name-field"
-  type="text"
-  aria-describedby="name-description"
-  // ...
-/>
-<p id="name-description" className="text-xs text-gray-500">
-  Enter your full name as it appears on your ID
-</p>
-```
+## Common Patterns and Reusable Components
 
-## Common Patterns
-
-### Conditional Fields
+### Reusable Form Sections
 
 ```tsx
-{
-  form.type === "advanced" && (
-    <Field.Text
-      label="Advanced Option"
-      value={form.advancedOption}
-      onChange={(v) => st.do.setAdvancedOptionOn[Model](v)}
-    />
-  );
-}
+// AddressSection.tsx
+export const AddressSection = () => (
+  <>
+    <Field.Text label="Street" />
+    <Field.Text label="City" />
+    <Field.Text label="Zip Code" />
+  </>
+);
+
+// Usage
+<AddressSection />;
 ```
 
-### Field Groups
+### Dynamic Field Arrays
 
 ```tsx
-const ContactSection = () => {
-  const form = st.use.[model]Form();
-  const { l } = usePage();
-
-  return (
-    <fieldset className="border p-4">
-      <legend>{l.section.contactInfo}</legend>
-      <Field.Text label={l.field.email} /* ... */ />
-      <Field.Text label={l.field.phone} /* ... */ />
-    </fieldset>
-  );
-};
+<Field.List
+  value={form.items}
+  onAdd={() => st.do.addItem(defaultItem)}
+  renderItem={(item, index) => (
+    <div key={index}>
+      <Field.Text value={item.name} />
+      <Field.Number value={item.quantity} />
+    </div>
+  )}
+/>
 ```
 
-### Custom Field Components
+### Compound Components
 
 ```tsx
-const CustomField = ({ label, value, onChange }) => {
-  const handleChange = (e) => {
-    onChange(e.target.value);
-  };
-
-  return (
-    <div className="custom-field">
-      <label>{label}</label>
-      <input value={value} onChange={handleChange} className="special-input" />
-    </div>
-  );
-};
+// DockerRegistryField.tsx
+const DockerRegistry = ({ value, onChange }) => (
+  <>
+    <Field.Text label="URI" value={value.uri} />
+    <Field.Text label="Username" value={value.username} />
+    <Field.Text label="Password" value={value.password} />
+  </>
+);
 ```
 
 ## Form State Integration with Database Models
 
-Templates connect to state that directly corresponds to the model structure defined in `[model].constant.ts`:
+### Type Alignment
 
 ```tsx
-// In [model].constant.ts
-@Model.Input("[Model]Input")
-export class [Model]Input {
+// Model.constant.ts
+@Model.Input("ProjectInput")
+export class ProjectInput {
   @Field.Prop(() => String)
   name: string;
-
-  @Field.Prop(() => String)
-  description: string;
 }
 
-// In [Model].Template.tsx
-const form = st.use.[model]Form(); // Type: [Model]Input
+// Project.Template.tsx
+const form = st.use.projectForm(); // Type: ProjectInput
 
-<Field.Text
-  value={form.name}
-  onChange={(v) => st.do.setNameOn[Model](v)}
-/>
+<Field.Text value={form.name} onChange={st.do.setNameOnProject} />;
 ```
 
-## Troubleshooting
-
-### Form Not Updating
+### Data Transformation
 
-- Verify Zustand store actions are properly connected
-- Check for conflicting state updates in parent components
-- Ensure `onChange` handlers are updating the correct store slice
-- Verify that the form state is being properly initialized
+```tsx
+// Before submission
+const handleSubmit = () => {
+  const dataToSend = transformFormData(form);
+  st.do.createProject(dataToSend);
+};
 
-### Validation Issues
+// After load
+useEffect(() => {
+  if (data) {
+    const formData = transformAPIData(data);
+    st.do.setProjectForm(formData);
+  }
+}, [data]);
+```
 
-- Confirm validation regex patterns match server-side rules
-- Check field requirements in `[model].constant.ts`
-- Verify error messages are properly displayed
-- Test edge cases like empty strings and special characters
+## Troubleshooting Common Issues
 
-### Performance Problems
+### Common Problems and Solutions
 
-- Profile re-renders with React DevTools
-- Implement memoization on complex components
-- Consider virtualizing large forms
-- Check for unnecessary re-renders
+| Issue                   | Solution                                       |
+| ----------------------- | ---------------------------------------------- |
+| Form not updating       | Verify Zustand actions are connected correctly |
+| Validation not working  | Check validate prop and error handling         |
+| Performance issues      | Memoize components, debounce inputs            |
+| Type mismatches         | Ensure constant types match form state         |
+| Missing translations    | Verify dictionary keys and scopes              |
+| Form reset issues       | Check cleanup useEffect dependencies           |
+| API submission failures | Validate server-side requirements              |
 
-### Type Errors
+### Debugging Tips
 
-- Ensure `[model].constant.ts` types are up to date
-- Verify FormState interface matches `[Model]Input`
-- Check for correct import paths
-- Validate that prop types match the expected form field types
+1. Check Zustand store state with Redux DevTools
+2. Verify prop drilling in complex forms
+3. Test validation rules independently
+4. Check network requests for API errors
+5. Verify dictionary key paths with `l()` function
+6. Ensure all required fields have `required` prop
 
-## Integration with API Calls
+## Integration with API Calls and Form Submission
 
-Templates should work with signals and stores to handle form submissions:
+### Submission Workflow
 
 ```tsx
-// In [model].store.ts
-createUser: async () => {
-  const { userForm } = get();
+const handleSubmit = async () => {
   try {
-    const user = await sig.user.createUser({ data: userForm });
-    set((state) => {
-      state.users = [...state.users, user];
-      state.userForm = {
-        /* reset form */
-      };
-    });
-    return user;
+    // Validate form
+    const errors = validateForm(form);
+    if (Object.keys(errors).length) throw errors;
+
+    // Submit data
+    if (id) {
+      await st.do.updateModel(id, form);
+    } else {
+      await st.do.createModel(form);
+    }
+
+    // Redirect on success
+    router.push("/success");
   } catch (error) {
-    set((state) => {
-      state.formErrors = error.errors || { general: error.message };
-    });
-    throw error;
+    // Handle API errors
+    st.do.setFormErrors(error);
   }
 };
 
 // In component
-const handleSubmit = async () => {
+<Button onClick={handleSubmit}>Save</Button>;
+```
+
+### API Error Handling
+
+```tsx
+// In store
+createModel: async (form) => {
   try {
-    await st.do.createUser();
-    // Handle success (navigation, toast, etc.)
+    return await fetch.createModel(form);
   } catch (error) {
-    // Error already handled in store
+    // Transform API errors to form errors
+    const formErrors = transformErrors(error);
+    set({ formErrors });
+    throw formErrors;
   }
 };
 ```
+
+### Success/Failure Feedback
+
+```tsx
+// Using toast notifications
+toast.success(l("model.createdSuccess"));
+
+// Inline messages
+{
+  submitError && <div className="text-error">{submitError}</div>;
+}
+```
+
+## Additional Best Practices
+
+### Component Design Principles
+
+1. **Single Responsibility**: Each template should focus on one model
+2. **Reusability**: Design components to work in different contexts
+3. **Composition**: Build complex forms from simple components
+4. **Consistency**: Follow established patterns across all templates
+5. **Accessibility**: Meet WCAG 2.1 standards for all form elements
+
+### Performance Guidelines
+
+1. Avoid unnecessary state updates
+2. Use React.memo for expensive components
+3. Virtualize long lists of fields
+4. Debounce rapid state updates
+5. Lazy load heavy form sections
+
+### Testing Recommendations
+
+1. Unit test validation functions
+2. Test form submission flows
+3. Verify internationalization coverage
+4. Test accessibility with screen readers
+5. Perform cross-browser testing