Model.Util Implementation Guide

Specialized client components that encapsulate model-specific functionality and business logic

Purpose and Role

Model.Util components serve as reusable utility components that encapsulate model-specific functionality. They handle actions, UI interactions, and complex client-side logic while integrating with stores and API signals.

componentType	Description	Example
Action Buttons	CRUD operations with built-in state management	`1DeleteButton, CreateButton, RefreshButton`
Form Wrappers	Specialized form components with validation	`1QuickEditForm, StatusToggle`
Data Visualizers	Components for displaying model statistics	`1StatsPanel, AnalyticsChart`
Composite Utilities	Combined functionality components	`1FilterPanel, CategorySelector`

Action Buttons

CRUD operations with built-in state management

1DeleteButton, CreateButton, RefreshButton

Form Wrappers

Specialized form components with validation

1QuickEditForm, StatusToggle

Data Visualizers

Components for displaying model statistics

1StatsPanel, AnalyticsChart

Composite Utilities

Combined functionality components

1FilterPanel, CategorySelector

Basic Implementation

1// File: lib/project/Project.Util.tsx
2"use client";
3
4import { useState } from "react";
5import { Button } from "@util/ui";
6import { projectStore } from "./project.store";
7import { projectSignal } from "./project.signal";
8
9export const CreateButton = ({ className }: { className?: string }) => {
10  const { showCreateModal } = projectStore();
11
12  return (
13    <Button 
14      className={className}
15      variant="primary"
16      onClick={showCreateModal}
17    >
18      Create New Project
19    </Button>
20  );
21};
22
23export const DeleteButton = ({ id, name }: { id: string; name: string }) => {
24  const [confirming, setConfirming] = useState(false);
25  const { deleteProject } = projectStore();
26
27  const handleDelete = async () => {
28    await projectSignal.deleteProject(id);
29    setConfirming(false);
30    deleteProject(id);
31  };
32
33  return (
34    <>
35      <Button variant="error" onClick={() => setConfirming(true)}>
36        Delete
37      </Button>
38      
39      {confirming && (
40        <div className="modal modal-open">
41          <div className="modal-box">
42            <h3>Confirm Delete</h3>
43            <p>Delete project {name}?</p>
44            <div className="modal-action">
45              <Button variant="outline" onClick={() => setConfirming(false)}>
46                Cancel
47              </Button>
48              <Button variant="error" onClick={handleDelete}>
49                Confirm
50              </Button>
51            </div>
52          </div>
53        </div>
54      )}
55    </>
56  );
57};
58

Store Integration

Util components connect to Zustand stores for state management and actions:

Option	Type	Default	Description	Example
useStore	Hook	-	Access store state and actions	`1st.use.model()`
Selective State	Pattern	-	Extract only needed state properties	`1state => ({ item: state.items[id] })`
Loading States	Handling	-	Track and display loading indicators	`1isUpdating, isRefreshing`

useStore:Hook:-

Access store state and actions

1st.use.model()

Selective State:Pattern:-

Extract only needed state properties

1state => ({ item: state.items[id] })

Loading States:Handling:-

Track and display loading indicators

1isUpdating, isRefreshing

1export const StatusToggle = ({ id }: { id: string }) => {
2  const { status, updateStatus } = projectStore(
3    (state) => ({
4      status: state.projects[id]?.status,
5      updateStatus: state.updateStatus
6    })
7  );
8
9  const toggle = () => {
10    const newStatus = status === 'active' ? 'inactive' : 'active';
11    updateStatus(id, newStatus);
12  };
13
14  return (
15    <Toggle
16      checked={status === 'active'}
17      onChange={toggle}
18      label={status === 'active' ? 'Active' : 'Inactive'}
19    />
20  );
21};
22

Performance Optimization

Optimize util components with memoization and lazy loading:

1import { memo } from "react";
2
3export const StatCard = memo(({ value, label }: { value: number; label: string }) => (
4  <div className="stats bg-base-200">
5    <div className="stat">
6      <div className="stat-title">{label}</div>
7      <div className="stat-value">{value}</div>
8    </div>
9  </div>
10));
11
12// Lazy load heavy components
13const LazyChart = dynamic(() => import('./ChartComponent'), {
14  loading: () => <div className="loading loading-spinner"></div>
15});
16
17export const AnalyticsPanel = ({ id }: { id: string }) => (
18  <div className="h-96">
19    <LazyChart projectId={id} />
20  </div>
21);
22

Usage in Application Layers

Util components integrate across all application layers:

1// In Views
2import { ProjectUtil } from "../project.Util";
3
4export const ProjectDetailView = ({ id }) => (
5  <div className="p-4">
6    <div className="flex justify-end gap-2 mb-4">
7      <ProjectUtil.EditButton id={id} />
8      <ProjectUtil.ShareButton id={id} />
9      <ProjectUtil.DeleteButton id={id} />
10    </div>
11    {/* ... */}
12  </div>
13);
14
15// In Units
16export const ProjectCard = ({ project }) => (
17  <div className="card bg-base-100 shadow">
18    <div className="card-body">
19      <h3 className="card-title">{project.name}</h3>
20      <ProjectUtil.StatusBadge status={project.status} />
21      <div className="card-actions justify-end">
22        <ProjectUtil.ViewButton id={project.id} />
23      </div>
24    </div>
25  </div>
26);
27
28// In Templates
29export const ProjectForm = () => (
30  <form>
31    {/* Form fields */}
32    <ProjectUtil.CategorySelector />
33    <ProjectUtil.TagsInput />
34    <div className="form-actions">
35      <ProjectUtil.CancelButton />
36      <ProjectUtil.SubmitButton />
37    </div>
38  </form>
39);
40

Best Practices

Follow these guidelines for maintainable util components:

Always include className prop for styling flexibility
Handle loading, error, and success states consistently
Use TypeScript interfaces for props and state
Implement JSDoc comments for documentation
Memoize expensive computations and components

1/**
2 * Renders a status badge with color coding
3 * 
4 * @param status - Current project status
5 * @param size - Badge size (sm/md/lg)
6 */
7export const StatusBadge = ({ 
8  status, 
9  size = 'md' 
10}: { 
11  status: ProjectStatus; 
12  size?: 'sm' | 'md' | 'lg';
13}) => {
14  const colorMap = {
15    active: 'success',
16    pending: 'warning',
17    archived: 'neutral'
18  };
19
20  return (
21    <span className={`badge badge-${colorMap[status]} badge-${size}`}>
22      {status}
23    </span>
24  );
25};
26

Summary

Model.Util components are essential building blocks that encapsulate model-specific functionality, promote code reuse, and maintain separation between business logic and presentation. By following these patterns, you create maintainable and consistent utilities throughout your application.

Quick Start

Released under the MIT License

Official Akan.js Consulting onAkansoft

System managed bybassman

Docs

Model.Util Implementation Guide