@akanjs/cli 0.0.142 → 0.0.144

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

@@ -0,0 +1,577 @@
+# Model.Template.tsx Implementation Guide
+
+## Purpose and Role of Model.Template.tsx Files
+
+Model.Template.tsx files are client-side React components that define the form structure for creating/editing models in Akan.js applications. They serve as:
+
+1. **Form Blueprints**: Provide reusable form structures for model CRUD operations
+2. **State Management**: Connect form inputs to Zustand store slices
+3. **Validation**: Implement field-level validation rules
+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
+
+## File Location and Naming Convention
+
+```
+libs/[domain]/lib/[model]/[Model].Template.tsx
+```
+
+For example:
+
+- `libs/shared/lib/admin/Admin.Template.tsx`
+- `apps/akamir/lib/rewardRequest/RewardRequest.Template.tsx`
+
+The file should export one or more named components, typically including:
+
+- `General`: Main form template used in most scenarios
+- `Advanced`: Optional complex fields for advanced forms
+- `Compact`: Simplified version for inline editing or mobile views
+
+## Creating Model.Template.tsx Files
+
+### Basic Structure
+
+```tsx
+// File: libs/[domain]/lib/[model]/[Model].Template.tsx
+"use client";
+import { Field } from "@akanjs/client";
+import { cnst } from "@[project]/constant";
+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 { l } = usePage();
+
+  return (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+      <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)}
+      />
+
+      {/* Add other fields */}
+    </div>
+  );
+};
+```
+
+### Integration with Store State
+
+Model.Template components connect to Zustand store slices that follow a consistent pattern:
+
+```tsx
+// Form state (defined in model.store.ts)
+interface [Model]State {
+  [model]Form: cnst.[Model]Input;
+  // other state properties...
+}
+
+// Form actions (defined in model.store.ts)
+interface [Model]Action {
+  setNameOn[Model]: (name: string) => void;
+  setStatusOn[Model]: (status: cnst.[Model]Status) => void;
+  // other actions...
+}
+
+// In Template component
+const form = st.use.[model]Form();
+const { setNameOn[Model] } = st.do;
+```
+
+### Field Types and Components
+
+Akan.js provides a comprehensive set of form field components in the `Field` namespace:
+
+```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
+```
+
+### Form Validation
+
+Field components support validation through props:
+
+```tsx
+<Field.Text
+  label="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:
+
+- `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
+
+### Internationalization
+
+Templates should use the `usePage()` hook to access localized strings:
+
+```tsx
+const { l } = usePage();
+
+<Field.Text
+  label={l.field.email}
+  placeholder={l.desc.enterEmail}
+  // ...
+/>;
+```
+
+## Form Layout Patterns
+
+### Basic 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" /* ... */ />
+</div>
+```
+
+### Grouped Fields
+
+```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>
+```
+
+### Conditional Fields
+
+```tsx
+{
+  form.type === "business" && (
+    <>
+      <Field.Text label="Company Name" /* ... */ />
+      <Field.Text label="Tax ID" /* ... */ />
+    </>
+  );
+}
+```
+
+### Nested Components
+
+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
+};
+```
+
+## Using Model.Template in Pages
+
+### Creation Page
+
+```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>
+  );
+}
+```
+
+### Editing Page
+
+```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>
+  );
+}
+```
+
+## Using Model.Template in Utility Components
+
+### In Modal Dialogs
+
+```tsx
+// libs/[domain]/lib/[model]/[Model].Util.tsx
+import { Modal, Model } from "@util/ui";
+import { [Model] } from "@[project]/client";
+
+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>
+  </>
+);
+```
+
+### In Custom Forms
+
+```tsx
+// libs/[domain]/lib/[model]/[Model].Util.tsx
+import { st } from "@[project]/client";
+import { [Model] } from "@[project]/client";
+
+export const CustomFormSection = () => {
+  const form = st.use.[model]Form();
+
+  return (
+    <div>
+      <h3>Advanced Settings</h3>
+      <[Model].Template.Advanced />
+      <button onClick={st.do.submit[model]}>Save</button>
+    </div>
+  );
+};
+```
+
+## Using Model.Template in Zone Components
+
+### List View Creation
+
+```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
+  />
+);
+```
+
+### Inline Editing
+
+```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>
+);
+```
+
+## Best Practices
+
+### 1. Component Organization
+
+Split complex templates into logical sections:
+
+```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
+```
+
+### 2. State Management
+
+- 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]);
+```
+
+### 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
+
+```tsx
+// Form-level validation example
+const handleSubmit = () => {
+  const errors = validateForm(form);
+  if (Object.keys(errors).length > 0) {
+    st.do.setFormErrors(errors);
+    return;
+  }
+
+  st.do.submit[Model]();
+};
+```
+
+### 4. Performance Optimization
+
+- Memoize components with `React.memo` for complex forms
+- Use controlled components consistently
+- Debounce input changes for expensive operations:
+
+```tsx
+import { useDebounce } from "@[project]/lib/hooks";
+
+const debouncedValue = useDebounce(inputValue, 300);
+
+useEffect(() => {
+  // Perform expensive operation with debouncedValue
+}, [debouncedValue]);
+```
+
+### 5. Accessibility
+
+- Associate labels with inputs using `htmlFor`/`id`
+- Provide ARIA attributes for custom components
+- Ensure keyboard navigation works properly
+- Use semantic HTML elements
+
+```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
+
+### Conditional Fields
+
+```tsx
+{
+  form.type === "advanced" && (
+    <Field.Text
+      label="Advanced Option"
+      value={form.advancedOption}
+      onChange={(v) => st.do.setAdvancedOptionOn[Model](v)}
+    />
+  );
+}
+```
+
+### Field Groups
+
+```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>
+  );
+};
+```
+
+### Custom Field 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>
+  );
+};
+```
+
+## Form State Integration with Database Models
+
+Templates connect to state that directly corresponds to the model structure defined in `[model].constant.ts`:
+
+```tsx
+// In [model].constant.ts
+@Model.Input("[Model]Input")
+export class [Model]Input {
+  @Field.Prop(() => String)
+  name: string;
+
+  @Field.Prop(() => String)
+  description: string;
+}
+
+// In [Model].Template.tsx
+const form = st.use.[model]Form(); // Type: [Model]Input
+
+<Field.Text
+  value={form.name}
+  onChange={(v) => st.do.setNameOn[Model](v)}
+/>
+```
+
+## Troubleshooting
+
+### Form Not Updating
+
+- 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
+
+### Validation Issues
+
+- 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
+
+### Performance Problems
+
+- Profile re-renders with React DevTools
+- Implement memoization on complex components
+- Consider virtualizing large forms
+- Check for unnecessary re-renders
+
+### Type Errors
+
+- 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
+
+## Integration with API Calls
+
+Templates should work with signals and stores to handle form submissions:
+
+```tsx
+// In [model].store.ts
+createUser: async () => {
+  const { userForm } = get();
+  try {
+    const user = await sig.user.createUser({ data: userForm });
+    set((state) => {
+      state.users = [...state.users, user];
+      state.userForm = {
+        /* reset form */
+      };
+    });
+    return user;
+  } catch (error) {
+    set((state) => {
+      state.formErrors = error.errors || { general: error.message };
+    });
+    throw error;
+  }
+};
+
+// In component
+const handleSubmit = async () => {
+  try {
+    await st.do.createUser();
+    // Handle success (navigation, toast, etc.)
+  } catch (error) {
+    // Error already handled in store
+  }
+};
+```