@akanjs/cli 0.0.149 → 0.0.151

package/esm/src/guidelines/modelTemplate/modelTemplate.generate.json

@@ -0,0 +1,104 @@
+{
+  "title": "Model Template",
+  "description": "How to create and implement Model.Template.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "example",
+      "description": "Model Template examples",
+      "path": "{apps,libs}/*/lib/*/*.Template.ts{,x}",
+      "sample": 5
+    },
+    {
+      "type": "usage",
+      "description": "Model Template usage in pages",
+      "path": "apps/*/app/**/page.tsx",
+      "filterText": ".Template.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Template usage in Utils",
+      "path": "{apps,libs}/*/lib/*/*.Util.tsx",
+      "filterText": ".Template.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Template usage in Zones",
+      "path": "{apps,libs}/*/lib/*/*.Zone.tsx",
+      "filterText": ".Template.",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Form Field components",
+      "path": "libs/shared/ui/Field.tsx",
+      "sample": 5
+    },
+    {
+      "type": "reference",
+      "description": "Form validation examples",
+      "path": "{apps,libs}/*/lib/**/*.Template.tsx",
+      "filterText": "validate",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Store integration examples",
+      "path": "{apps,libs}/*/lib/**/*.store.ts",
+      "filterText": "Form",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Internationalization with usePage",
+      "path": "{apps,libs}/*/lib/**/usePage.{ts,tsx}",
+      "sample": 1
+    },
+    {
+      "type": "reference",
+      "description": "Integration with Model.constant.ts",
+      "path": "{apps,libs}/*/lib/**/*.constant.ts",
+      "filterText": "@Model.Input",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./modelTemplate.instruction.md",
+    "contents": [
+      "Purpose and role of Model.Template.tsx files",
+      "File location and naming conventions",
+      "Basic structure and component patterns",
+      "Integration with store state management",
+      "Field types and form components",
+      "Form validation approaches",
+      "Internationalization with usePage",
+      "Form layout patterns and best practices",
+      "Using templates in pages, utilities, and zones",
+      "State management and lifecycle methods",
+      "Performance optimization techniques",
+      "Accessibility considerations",
+      "Common patterns and reusable components",
+      "Form state integration with database models",
+      "Troubleshooting common issues",
+      "Integration with API calls and form submission"
+    ],
+    "rules": [
+      "Model.Template.tsx is a client component, so it should include 'use client' directive",
+      "Model.Template.tsx components should accept an optional id parameter to support both creation and editing",
+      "Use Form components from the Field namespace for consistent UI and validation",
+      "Always connect form state to Zustand store via st.use.[model]Form()",
+      "Update form state using st.do.set[Field]On[Model]() actions",
+      "Use usePage() hook for internationalization of labels and messages",
+      "Implement form validation at field level when possible",
+      "Reset form state on component unmount to prevent stale data",
+      "Split complex forms into smaller, focused components",
+      "Follow accessibility best practices for all form fields",
+      "Use consistent layout patterns across the application",
+      "Provide clear validation feedback and error messages",
+      "Initialize form data from API when editing existing models",
+      "Implement proper error handling for form submissions"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/template/page.tsx"
+}

package/esm/src/guidelines/modelUnit/modelUnit.generate.json

@@ -0,0 +1,92 @@
+{
+  "title": "Model Unit",
+  "description": "How to create and implement Model.Unit.tsx files in Akan.js",
+  "scans": [
+    {
+      "type": "example",
+      "description": "Model Unit examples",
+      "path": "{apps,libs}/*/lib/*/*.Unit.tsx",
+      "sample": 5
+    },
+    {
+      "type": "implementation",
+      "description": "Model Unit typical implementations",
+      "path": "{apps,libs}/*/lib/**/*.Unit.tsx",
+      "filterText": "export const Abstract",
+      "sample": 3
+    },
+    {
+      "type": "implementation",
+      "description": "Model Unit Card implementations",
+      "path": "{apps,libs}/*/lib/**/*.Unit.tsx",
+      "filterText": "export const Card",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Model Unit usage in pages",
+      "path": "apps/*/app/**/page.tsx",
+      "filterText": ".Unit.",
+      "sample": 1
+    },
+    {
+      "type": "usage",
+      "description": "Model Unit usage in Utils",
+      "path": "{apps,libs}/*/lib/*/*.Util.tsx",
+      "filterText": ".Unit.",
+      "sample": 1
+    },
+    {
+      "type": "usage",
+      "description": "Model Unit usage in Templates",
+      "path": "{apps,libs}/*/lib/*/*.Template.tsx",
+      "filterText": ".Unit.",
+      "sample": 1
+    },
+    {
+      "type": "usage",
+      "description": "Model Unit usage in Zones",
+      "path": "{apps,libs}/*/lib/*/*.Zone.tsx",
+      "filterText": ".Unit.",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Integration with database models",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "sample": 1
+    },
+    {
+      "type": "reference",
+      "description": "Integration with model constants",
+      "path": "{apps,libs}/*/lib/*/*.constant.ts",
+      "sample": 1
+    }
+  ],
+  "update": {
+    "filePath": "./modelUnit.instruction.md",
+    "contents": [
+      "Purpose and role of Model.Unit.tsx files",
+      "How to create Model.Unit.tsx files",
+      "Common export patterns (Abstract, Card, Full, etc.)",
+      "Integration with LightModel types from constants",
+      "How to use Model.Unit.tsx files in pages",
+      "How to use Model.Unit.tsx files in Utils",
+      "How to use Model.Unit.tsx files in Zones",
+      "How to use Model.Unit.tsx files in Templates",
+      "Best practices for performance optimization",
+      "Common component patterns and variations"
+    ],
+    "rules": [
+      "Model.Unit.tsx is a server component, so it should not use client-side hooks like useEffect, useState, etc.",
+      "Model.Unit.tsx is a presentation component of cnst.LightModel to reuse in pages, Utils, Zones, and Templates, etc.",
+      "Always accept className prop for styling customization",
+      "Create multiple export variations (Abstract, Card, Full) for different use cases",
+      "Use semantic HTML and ensure accessibility",
+      "Focus on presentation only - do not include business logic",
+      "Include href prop for navigation when appropriate",
+      "Ensure proper image handling with the Image component from @util/ui"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/unit/page.tsx"
+}

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

@@ -39,7 +39,7 @@ A typical Model.Unit.tsx file exports multiple component variations:
 ```tsx
 import { clsx } from "clsx";
 import { cnst } from "@your-lib/client";
-import { Image, Link } from "@util/ui";
+import { Image, Link } from "@akanjs/ui";
 
 // Compact representation (minimal details)
 export const Abstract = ({
@@ -253,7 +253,7 @@ export const Card = ({ user, className }: { user: cnst.LightUser; className?: st
 Always use the optimized `Image` component from `@util/ui` with proper attributes:
 
 ```tsx
-import { Image } from "@util/ui";
+import { Image } from "@akanjs/ui";
 
 export const Card = ({ product }: { product: cnst.LightProduct }) => (
   <div className="card">

package/esm/src/guidelines/modelUtil/modelUtil.generate.json

@@ -0,0 +1,93 @@
+{
+  "title": "Model Util",
+  "description": "How to create and implement Model.Util.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "example",
+      "description": "Model Util examples",
+      "path": "{apps,libs}/*/lib/*/*.Util.ts{,x}",
+      "sample": 5
+    },
+    {
+      "type": "source",
+      "description": "Example of high-quality Model.Util implementation",
+      "path": "libs/shared/lib/admin/Admin.Util.tsx"
+    },
+    {
+      "type": "source",
+      "description": "Example of complex Model.Util implementation",
+      "path": "libs/shared/lib/user/User.Util.tsx"
+    },
+    {
+      "type": "usage",
+      "description": "Model Util usage in pages",
+      "path": "apps/*/app/**/page.tsx",
+      "filterText": ".Util.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Util usage in Units",
+      "path": "{apps,libs}/*/lib/*/*.Unit.tsx",
+      "filterText": ".Util.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Util usage in Templates",
+      "path": "{apps,libs}/*/lib/*/*.Template.tsx",
+      "filterText": ".Util.",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Model Util usage in Views",
+      "path": "{apps,libs}/*/lib/*/*.View.tsx",
+      "filterText": ".Util.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Util usage in Zones",
+      "path": "{apps,libs}/*/lib/*/*.Zone.tsx",
+      "filterText": ".Util.",
+      "sample": 3
+    },
+    {
+      "type": "related",
+      "description": "Relationship with model.store.ts",
+      "path": "{apps,libs}/*/lib/*/*.{store,signal}.ts",
+      "sample": 2
+    }
+  ],
+  "update": {
+    "filePath": "./modelUtil.instruction.md",
+    "contents": [
+      "Purpose and role of Model.Util.ts files",
+      "How to create Model.Util.ts files",
+      "Common patterns and implementations",
+      "Using with store actions and state",
+      "Using with signal API calls",
+      "Performance optimization techniques",
+      "How to use Model.Util.ts files in pages",
+      "How to use Model.Util.ts files in Units",
+      "How to use Model.Util.ts files in Templates",
+      "How to use Model.Util.ts files in Views",
+      "How to use Model.Util.ts files in Zones",
+      "Best practices and error handling"
+    ],
+    "rules": [
+      "Model.Util.tsx is a client component, so it can use client-side hooks like useEffect, useState, etc.",
+      "Model.Util.tsx is a utility component to reuse in pages, Units, Templates, Views, and Zones, etc.",
+      "Util components should be focused on a single responsibility",
+      "Util can be a wrapper component for using in server components",
+      "Util can be a wrapper component for store actions or signal api calls",
+      "Util components should handle their own loading and error states",
+      "Always use TypeScript for type safety in props and returned values",
+      "Consider memoization for performance-critical components",
+      "Follow consistent naming conventions (e.g., ActionButton, FilterPanel)",
+      "Document props with JSDoc comments for better IDE support"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/util/page.tsx"
+}

package/esm/src/guidelines/modelView/modelView.generate.json

@@ -0,0 +1,80 @@
+{
+  "title": "Model View",
+  "description": "How to create and implement Model.View.tsx files in Akan.js",
+  "scans": [
+    {
+      "type": "example",
+      "description": "Model View examples",
+      "path": "{apps,libs}/*/lib/*/*.View.tsx",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Model View interfaces",
+      "path": "{apps,libs}/*/lib/*/*.View.tsx",
+      "filterText": "ViewProps",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model View usage in pages",
+      "path": "apps/*/app/**/page.tsx",
+      "filterText": ".View.",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Model View usage in Utils",
+      "path": "{apps,libs}/*/lib/*/*.Util.tsx",
+      "filterText": ".View.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model View usage in Zones",
+      "path": "{apps,libs}/*/lib/*/*.Zone.tsx",
+      "filterText": ".View.",
+      "sample": 3
+    },
+    {
+      "type": "compare",
+      "description": "Compare with Unit components",
+      "path": "{apps,libs}/*/lib/*/*.Unit.tsx",
+      "sample": 2
+    },
+    {
+      "type": "compare",
+      "description": "Compare with Template components",
+      "path": "{apps,libs}/*/lib/*/*.Template.tsx",
+      "sample": 2
+    }
+  ],
+  "update": {
+    "filePath": "./modelView.instruction.md",
+    "contents": [
+      "Purpose and role of Model.View.tsx files in the Akan.js architecture",
+      "Core principles of Model.View.tsx components",
+      "File structure and component organization",
+      "Props design and interfaces",
+      "Component variations and specialized views",
+      "Integration with other Akan.js components",
+      "Server component considerations",
+      "Best practices for effective View components",
+      "How to use Model.View.tsx in pages, Utils and Zones",
+      "Common patterns and advanced techniques",
+      "Performance optimization strategies",
+      "Troubleshooting and common issues"
+    ],
+    "rules": [
+      "Model.View.tsx is a server component, so it should not use client-side hooks like useEffect, useState, etc.",
+      "Model.View.tsx focuses on presentation of model data, not interaction or state management",
+      "Model.View.tsx files export named functional components, not default exports",
+      "Components should be designed for reuse across pages, Utils, and Zones",
+      "Props interfaces should follow consistent naming patterns",
+      "View components should be responsive and accessible",
+      "Complex views should be broken into logical, reusable sections",
+      "Components should handle edge cases like missing data gracefully"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/view/page.tsx"
+}

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

@@ -748,7 +748,7 @@ export const Product = ({ product }: ProductViewProps) => (
 ### 1. Optimize Images and Media
 
 ```tsx
-import { Image } from "@util/ui"; // Optimized image component
+import { Image } from "@akanjs/ui"; // Optimized image component
 
 export const General = ({ product }: ProductViewProps) => (
   <div className="product-view">

package/esm/src/guidelines/modelZone/modelZone.generate.json

@@ -0,0 +1,126 @@
+{
+  "title": "Model Zone",
+  "description": "How to create and implement Model.Zone.tsx files in Akan.js",
+  "scans": [
+    {
+      "type": "example",
+      "description": "Model Zone examples",
+      "path": "{apps,libs}/*/lib/*/*.Zone.{ts,tsx}",
+      "sample": 5
+    },
+    {
+      "type": "usage",
+      "description": "Model Zone usage in pages",
+      "path": "apps/*/app/**/page.tsx",
+      "filterText": ".Zone.",
+      "sample": 5
+    },
+    {
+      "type": "pattern",
+      "description": "Admin Zone patterns",
+      "path": "{apps,libs}/*/lib/*/*.Zone.{ts,tsx}",
+      "filterText": "export const Admin",
+      "sample": 3
+    },
+    {
+      "type": "pattern",
+      "description": "Card Zone patterns",
+      "path": "{apps,libs}/*/lib/*/*.Zone.{ts,tsx}",
+      "filterText": "export const Card",
+      "sample": 3
+    },
+    {
+      "type": "pattern",
+      "description": "View Zone patterns",
+      "path": "{apps,libs}/*/lib/*/*.Zone.{ts,tsx}",
+      "filterText": "export const View",
+      "sample": 3
+    },
+    {
+      "type": "pattern",
+      "description": "Specialized Zone patterns",
+      "path": "{apps,libs}/*/lib/*/*.Zone.{ts,tsx}",
+      "filterText": "Load.Units|Load.View|Data.ListContainer",
+      "sample": 3
+    },
+    {
+      "type": "integration",
+      "description": "Zone integration with Load components",
+      "path": "{apps,libs}/*/lib/*/*.Zone.{ts,tsx}",
+      "filterText": "Load.Page|Load.Units|Load.View",
+      "sample": 3
+    }
+  ],
+  "interfaces": [
+    {
+      "name": "Common Zone Props",
+      "description": "Typical props used by Zone components",
+      "properties": [
+        {
+          "name": "className",
+          "type": "string",
+          "optional": true,
+          "description": "CSS class name for styling flexibility"
+        },
+        {
+          "name": "init",
+          "type": "ClientInit<model, LightModel>",
+          "optional": false,
+          "description": "Initialization data for model list"
+        },
+        {
+          "name": "view",
+          "type": "ClientView<model, Model>",
+          "optional": false,
+          "description": "View data for a single model instance"
+        },
+        {
+          "name": "query",
+          "type": "QueryProps",
+          "optional": true,
+          "description": "Query parameters for filtering data"
+        },
+        {
+          "name": "sliceName",
+          "type": "string",
+          "optional": true,
+          "description": "Name of the state slice for data management"
+        }
+      ]
+    },
+    {
+      "name": "Architectural Position",
+      "description": "How Zone components fit in the component hierarchy",
+      "notes": [
+        "Page Components → Zone Components → View/Unit/Template Components",
+        "Client Components (use client) → Can use hooks and client-side state",
+        "Typically used within Load.Page in page.tsx files",
+        "Act as connectors between data fetching and UI presentation"
+      ]
+    }
+  ],
+  "update": {
+    "filePath": "./modelZone.instruction.md",
+    "contents": [
+      "Purpose and role of Model.Zone.tsx files",
+      "Component structure and naming patterns",
+      "Common Zone component types (Admin, View, Card, specialized)",
+      "Props patterns and data handling",
+      "Client component patterns and hooks usage",
+      "Integration with page components and data fetching",
+      "Composition with other Model components (Unit, View, Template, Util)",
+      "Best practices and implementation guidelines"
+    ],
+    "rules": [
+      "Model.Zone.tsx is a client component, so it can use client-side hooks like useEffect, useState, etc.",
+      "Model.Zone.tsx is a container component that connects data with UI presentation",
+      "Zone components typically import and use other model components (Unit, View, Template, Util)",
+      "Zone components should handle presentation logic, not business logic or data fetching",
+      "Common Zone types include Admin, View, Card, and specialized components",
+      "Zone components should accept flexible props like className for styling customization",
+      "Zone components often use Load.Units, Load.View, or Data.ListContainer for data handling",
+      "Zone components serve as the bridge between page components and UI presentation"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/zone/page.tsx"
+}

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

@@ -33,7 +33,7 @@ Example: `apps/angelo/lib/bizAccount/bizAccount.Zone.tsx`
 ```tsx
 "use client";
 
-import { Load, Data } from "@shared/ui";
+import { Load, Data } from "@akanjs/ui";
 import { ModelsProps } from "@akanjs/client";
 import { ClientInit, ClientView } from "@akanjs/signal";
 import { Model } from "./index";
@@ -275,7 +275,7 @@ Zone components are typically used within page.tsx files using the Load.Page pat
 
 ```tsx
 // app/[lang]/(app)/model/page.tsx
-import { Load } from "@shared/ui";
+import { Load } from "@akanjs/ui";
 import { fetch } from "@akanjs/signal";
 import { Model } from "@app/lib";
 
@@ -465,7 +465,7 @@ export const Dashboard = ({ className }: { className?: string }) => {
 "use client";
 
 import { useEffect } from "react";
-import { Load } from "@shared/ui";
+import { Load } from "@akanjs/ui";
 import { fetch, subscriptions } from "@akanjs/signal";
 
 export const LiveFeed = ({ className, init }: { className?: string; init: ClientInit<"model", cnst.LightModel> }) => {

package/esm/src/guidelines/scalarConstant/scalarConstant.generate.json

@@ -0,0 +1,102 @@
+{
+  "title": "Scalar Constant",
+  "description": "how to generate a scalar.constant.ts file",
+  "scans": [
+    {
+      "type": "source",
+      "description": "core constant library source code for scalar definitions",
+      "path": "pkgs/@akanjs/constant/src/classMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "field metadata implementation",
+      "path": "pkgs/@akanjs/constant/src/fieldMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "scalar metadata implementation",
+      "path": "pkgs/@akanjs/constant/src/scalar.ts"
+    },
+    {
+      "type": "source",
+      "description": "base scalar types and enumOf implementation",
+      "path": "pkgs/@akanjs/base/src/base.ts"
+    },
+    {
+      "type": "source",
+      "description": "GqlScalar type definition",
+      "path": "pkgs/@akanjs/base/src/scalar.ts"
+    },
+    {
+      "type": "source",
+      "description": "constant metadata usage in graphql schema generation",
+      "path": "pkgs/@akanjs/server/src/gql.ts"
+    },
+    {
+      "type": "source",
+      "description": "constant metadata usage in mongoDB schema generation",
+      "path": "pkgs/@akanjs/server/src/schema.ts"
+    },
+    {
+      "type": "example",
+      "description": "simple scalar.constant.ts file examples",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "lines < 30",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "complex scalar.constant.ts file examples with enum definitions",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "lines > 30 && /enumOf/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "scalar.constant.ts file examples with static methods",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "/static\\s+\\w+/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "scalar.constant.ts file examples with nested scalar references",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "/import.*\\.constant/",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./scalarConstant.instruction.md",
+    "contents": [
+      "Purpose of scalar constants in Akan.js",
+      "File structure and location conventions",
+      "Naming standards for directories, files, classes and enums",
+      "Required imports and framework types",
+      "Model definition with @Model.Scalar decorator",
+      "Field definitions with @Field.Prop and other decorators",
+      "Field options reference table",
+      "Array fields implementation",
+      "Map fields implementation",
+      "Enum implementation with enumOf",
+      "Static methods in scalar classes",
+      "Validation rules and checklists",
+      "Common mistakes and fixes",
+      "Full examples of scalar.constant.ts files"
+    ],
+    "rules": [
+      "One scalar.constant.ts should contain only one @Model.Scalar class. If you need more than one scalar model, make another scalar.constant.ts file.",
+      "The directory and filename convention is camelCase, such as `geoLocation/geoLocation.constant.ts`",
+      "The class name should be PascalCase, matching the camelCase directory name (e.g., GeoLocation for geoLocation)",
+      "The @Model.Scalar parameter MUST match the class name exactly",
+      "The values of enum strings must be camelCase (not uppercase)",
+      "Do not forget to import required imports like enumOf, Float, type Dayjs, etc.",
+      "Do not add options that don't exist in Field.Prop decorator. Carefully check that each option exists.",
+      "Always use Dayjs type for Date fields, not JavaScript's native Date",
+      "For nullable fields, add both the { nullable: true } option and the TypeScript union type (Type | null)",
+      "Use bracket notation for arrays ([Type]) rather than generics (Array<Type>)",
+      "Always export both const and type for enums created with enumOf"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/scalar/constant/page.tsx"
+}