@tailor-platform/erp-kit 0.2.0 → 0.2.1

package/skills/erp-kit-app-5-implementation/references/frontend.md

@@ -0,0 +1,242 @@
+# Frontend Implementation Patterns
+
+## Table of Contents
+
+- [Frontend Scaffold](#frontend-scaffold)
+- [Frontend Pages](#frontend-pages)
+
+---
+
+## Frontend Scaffold
+
+```
+frontend/
+├── src/
+│   ├── main.tsx, App.tsx, index.css
+│   ├── graphql/
+│   │   ├── index.ts                      # gql.tada setup
+│   │   └── generated/                    # Placeholder until backend deploy
+│   ├── lib/
+│   │   ├── auth-client.ts
+│   │   └── utils.ts                      # cn() utility
+│   ├── providers/
+│   │   └── graphql-provider.tsx          # urql client with DPoP auth
+│   ├── components/
+│   │   ├── ui/                           # shadcn/Radix primitives
+│   │   └── composed/                     # empty-state, error-fallback, loading
+│   └── pages/
+│       └── <domain>/
+│           ├── page.tsx                  # Module redirect (REQUIRED)
+│           └── <entity>/
+│               ├── page.tsx              # ListView
+│               ├── components/<entities>-table.tsx
+│               ├── create/page.tsx + components/create-<entity>-form.tsx
+│               └── [id]/
+│                   ├── page.tsx          # DetailView
+│                   ├── components/<entity>-detail.tsx, <entity>-actions.tsx
+│                   └── edit/page.tsx + components/edit-<entity>-form.tsx
+├── scripts/generate-graphql.mjs
+├── package.json, vite.config.ts, tsconfig.json, eslint.config.js
+└── components.json
+```
+
+`package.json` key dependencies and scripts:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "generate": "node --env-file=.env ./scripts/generate-graphql.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tailor-platform/app-shell": "...",
+    "gql.tada": "...",
+    "urql": "...",
+    "react-hook-form": "...",
+    "@hookform/resolvers": "...",
+    "zod": "...",
+    "tailwindcss": "...",
+    "lucide-react": "..."
+  },
+  "devDependencies": {
+    "@tailor-platform/app-shell-vite-plugin": "...",
+    "@tailor-platform/sdk": "...",
+    "@tailwindcss/vite": "...",
+    "vite": "...",
+    "typescript": "..."
+  }
+}
+```
+
+`scripts/generate-graphql.mjs` — fetches the GraphQL schema from the deployed backend:
+
+```js
+import { execSync } from "node:child_process";
+const url = process.env.VITE_TAILOR_APP_URL;
+execSync(`pnpm gql-tada generate schema "${url}/query"`);
+execSync("pnpm gql-tada generate output");
+```
+
+Before deployment, create empty placeholders for `src/graphql/generated/schema.graphql` and `graphql-env.d.ts` so the project compiles. After backend deployment, configure `.env` with `VITE_TAILOR_APP_URL` and `VITE_TAILOR_CLIENT_ID`, then run `pnpm generate` to regenerate them.
+
+---
+
+## Frontend Pages
+
+### GraphQL Setup
+
+All operations use gql.tada for type safety:
+
+```ts
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+```
+
+Built-in queries (`gqlOperations: "query"`) generate:
+
+- `<Entity>(id: ID!)` — get by ID
+- `<entities>` — list with connection pattern (`edges { node { ... } }`)
+
+Mutations are defined by custom resolvers.
+
+### ListView
+
+Key points:
+
+- Query uses connection pattern: `edges { node { ...Fragment } }`
+- Two-level fragments: row fragment for items, table fragment for the connection
+- `EmptyState` when `edges.length === 0`
+- Columns map to screen spec's "Required Columns"
+- `Layout` with title and create action button
+
+### DetailView
+
+Key points:
+
+- Two-column `Layout`: detail on left, actions on right
+- `useParams()` to get entity ID from route
+- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields:
+
+```tsx
+<DescriptionCard
+  data={resource}
+  title="Overview"
+  columns={3}
+  fields={[
+    { key: "name", label: "Name", meta: { copyable: true } },
+    {
+      key: "status",
+      label: "Status",
+      type: "badge",
+      meta: { badgeVariantMap: { ACTIVE: "success" } },
+    },
+    { key: "createdAt", label: "Created At", type: "date", meta: { dateFormat: "medium" } },
+  ]}
+/>
+```
+
+Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+
+### Form Pattern
+
+Create and edit forms share the same structure:
+
+- **React Hook Form + Zod** for validation with `zodResolver`
+- **urql `useMutation`** for GraphQL mutations
+- **Navigate `".."`** to go back to list after success
+- Edit form pre-fills `defaultValues` from existing entity via fragment
+
+#### Field Type Mapping
+
+| Field Type | Component                 | Zod Schema                      |
+| ---------- | ------------------------- | ------------------------------- |
+| Text       | `<Input />`               | `z.string()`                    |
+| Textarea   | `<textarea />`            | `z.string()`                    |
+| Dropdown   | `<Select />`              | `z.string()` or `z.enum([...])` |
+| Date       | `<Input type="date" />`   | `z.string()` (ISO format)       |
+| Number     | `<Input type="number" />` | `z.coerce.number()`             |
+| Checkbox   | `<Checkbox />`            | `z.boolean()`                   |
+
+#### Validation
+
+- **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
+- **Required: No** → `.optional()`
+
+### Shared Component Patterns
+
+#### Fragment Collocation
+
+Each component defines and exports its own GraphQL fragment. The parent page imports it and includes it in the query:
+
+```tsx
+// components/user-card.tsx
+export const UserCardFragment = graphql(`
+  fragment UserCard on User {
+    id
+    name
+    email
+  }
+`);
+
+export const UserCard = ({ user }: { user: FragmentOf<typeof UserCardFragment> }) => {
+  const data = readFragment(UserCardFragment, user);
+  return <div>{data.name}</div>;
+};
+
+// page.tsx
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserCard
+      }
+    }
+  `,
+  [UserCardFragment],
+);
+```
+
+#### App.tsx
+
+- `AuthGuard` is not exported from app-shell — implement it yourself, pass via `guardComponent` prop
+- `GraphQLProvider` needs `authClient` prop to attach DPoP auth headers
+- Required env vars: `VITE_TAILOR_APP_URL`, `VITE_TAILOR_CLIENT_ID`
+- Auth client: create once in `src/lib/auth-client.ts` using `createAuthClient({ appUri, clientId })`
+- Sidebar: use `SidebarGroup` + `SidebarItem` for custom ordering
+
+#### Module-level page.tsx (required)
+
+Every module directory must have a `page.tsx` that redirects to the first child. Use **absolute paths** to avoid double-path bugs:
+
+```tsx
+useEffect(() => {
+  void navigate("/item-management/item", { replace: true });
+}, [navigate]);
+```
+
+#### Page conventions
+
+Every page component must:
+
+1. Be the **default export** of `page.tsx`
+2. Set `appShellPageProps` with at least `meta.title`
+
+#### Common imports
+
+```tsx
+import {
+  Layout,
+  Link,
+  useParams,
+  useNavigate,
+  type AppShellPageProps,
+} from "@tailor-platform/app-shell";
+import { useQuery, useMutation } from "urql";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+```

package/src/module.ts

@@ -85,3 +85,41 @@ export { type RevokePermissionFromRoleInput } from "./modules/user-management/co
 export { type AssignRoleToUserInput } from "./modules/user-management/command/assignRoleToUser";
 export { type RevokeRoleFromUserInput } from "./modules/user-management/command/revokeRoleFromUser";
 export { type LogAuditEventInput } from "./modules/user-management/command/logAuditEvent";
+// item-management
+export { defineModule as defineItemManagementModule } from "./modules/item-management/module";
+export {
+  permissions as itemManagementPermissions,
+  own as itemManagementOwn,
+  all as itemManagementAll,
+} from "./modules/item-management/lib/permissions.generated";
+export { ItemStatus } from "./modules/item-management/generated/enums";
+export {
+  ItemNotFoundError,
+  DuplicateSkuError,
+  DuplicateBarcodeError,
+  UnitNotFoundError as ItemUnitNotFoundError,
+  SkuImmutableError,
+  UomLockedError,
+  NoFieldsToUpdateError,
+  InvalidStateTransitionError,
+  DeleteNonDraftError,
+  NodeNotFoundError,
+  DuplicateNodeCodeError,
+  ParentNodeNotFoundError,
+  MaxDepthExceededError,
+  CodeImmutableError,
+  MissingRequiredFieldsError,
+  CircularReferenceError,
+  NodeHasChildrenError,
+  NodeHasAssignmentsError,
+  DuplicateAssignmentError,
+  AssignmentNotFoundError as ItemAssignmentNotFoundError,
+} from "./modules/item-management/lib/errors.generated";
+export { type GetItemInput } from "./modules/item-management/query/getItem";
+export { type GetTaxonomyNodeInput } from "./modules/item-management/query/getTaxonomyNode";
+export { type CreateItemInput } from "./modules/item-management/command/createItem";
+export { type UpdateItemInput } from "./modules/item-management/command/updateItem";
+export { type ActivateItemInput } from "./modules/item-management/command/activateItem";
+export { type DeactivateItemInput } from "./modules/item-management/command/deactivateItem";
+export { type CreateTaxonomyNodeInput } from "./modules/item-management/command/createTaxonomyNode";
+export { type AssignItemToTaxonomyInput } from "./modules/item-management/command/assignItemToTaxonomy";

package/skills/erp-kit-app-1-requirements/references/structure.md

@@ -1,27 +0,0 @@
-# Application Directory Structure
-
-```
-{app_name}/
-├── backend/
-│   ├── src/
-│   │   ├── modules.ts              # Declaring module usage
-│   │   ├── modules/
-│   │   │   └── {module-name}/      # Module-specific directory
-│   │   │       ├── resolvers/      # API Definition to expose graphql apis
-│   │   │       └── executors/      # PubSub Automation (one file per declaration)
-│   │   └── generated/              # Auto-generated code (do not edit)
-│   └── tailor.config.ts            # tailor application config
-│
-└── frontend/
-    └── src/
-        ├── pages/                  # File-based routing (auto-discovered by Vite plugin)
-        │   └── {page-path}/
-        │       ├── page.tsx
-        │       └── {page-path}/
-        │           ├── components/
-        │           └── page.tsx
-        ├── components/
-        │   └── ui/                 # Generic UI components
-        ├── graphql/                # gql.tada settings
-        └── providers/              # react providers
-```

package/skills/erp-kit-app-2-breakdown/references/screen-detailview.md

@@ -1,106 +0,0 @@
-# DetailView Screen Implementation
-
-Implementation pattern for screens with `Screen Type: DetailView`.
-Assumes `page.md` and `component.md` rules.
-
-## File Structure
-
-```
-{screen-path}/[id]/
-├── components/
-│   ├── {screen-name}-detail.tsx     # Main content (left column)
-│   └── {screen-name}-actions.tsx    # Action sidebar (right column)
-├── edit/
-│   ├── components/
-│   │   └── edit-{screen-name}-form.tsx
-│   └── page.tsx
-└── page.tsx
-```
-
-## Layout
-
-- Two-column layout: main content on the left, actions on the right.
-
-```tsx
-const ResourcePage = () => {
-  const { id } = useParams();
-  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
-    query: ResourceQuery,
-    variables: { id: id! },
-  });
-
-  if (fetching) return <Loading />;
-  if (error || !data?.resource) return <ErrorFallback ... />;
-
-  return (
-    <Layout columns={2} title="Resource Detail">
-      <Layout.Column>
-        <ResourceDetail resource={data.resource} />
-      </Layout.Column>
-      <Layout.Column>
-        <ResourceActions resource={data.resource} />
-      </Layout.Column>
-    </Layout>
-  );
-};
-```
-
-## Left Column: Detail Component
-
-Stack `DescriptionCard` and related tables vertically with `space-y-6`.
-
-- `DescriptionCard` (`@tailor-platform/app-shell`): renders key-value fields declaratively.
-- Complex content (tables, timelines): wrap in `<div className="rounded-lg border bg-card p-6">`.
-
-### DescriptionCard
-
-```tsx
-<DescriptionCard
-  data={resource}
-  title="Overview"
-  columns={3}
-  fields={[
-    { key: "name", label: "Name", meta: { copyable: true } },
-    {
-      key: "status",
-      label: "Status",
-      type: "badge",
-      meta: { badgeVariantMap: { ACTIVE: "success", PENDING: "warning" } },
-    },
-    { type: "divider" },
-    {
-      key: "createdAt",
-      label: "Created At",
-      type: "date",
-      meta: { dateFormat: "medium" },
-    },
-  ]}
-/>
-```
-
-Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
-
-## Right Column: Actions Component
-
-Wrap in a `Card` component. Use `Button variant="ghost"` for each action item.
-
-```tsx
-<Card>
-  <CardHeader>
-    <CardTitle>Actions</CardTitle>
-  </CardHeader>
-  <CardContent className="space-y-2">
-    <Button variant="ghost" className="w-full justify-start gap-2" asChild>
-      <Link to="edit">✎ Edit</Link>
-    </Button>
-    <Button variant="ghost" className="w-full justify-start gap-2" onClick={handler}>
-      ✓ Approve
-    </Button>
-  </CardContent>
-</Card>
-```
-
-- Navigation: `<Button variant="ghost" asChild><Link to="...">`
-- Mutation: `<Button variant="ghost" onClick={handler}>` with custom resolvers (see `backend/resolvers.md`)
-- Conditional: show/hide based on status
-- Multiple cards: stack with `<div className="space-y-6">`

package/skills/erp-kit-app-2-breakdown/references/screen-form.md

@@ -1,139 +0,0 @@
-# Form Screen Implementation
-
-Implementation pattern for screens with `Screen Type: Form`.
-Assumes `page.md` and `component.md` rules.
-
-## File Structure
-
-```
-{screen-path}/
-├── components/
-│   └── {screen-name}-form.tsx    # Form component with validation
-└── page.tsx
-```
-
-## Page Component (page.tsx)
-
-Form pages delegate mutation logic to the form component.
-
-```tsx
-const ScreenNamePage = () => (
-  <Layout columns={1} title="Screen Title">
-    <Layout.Column>
-      <ScreenNameForm />
-    </Layout.Column>
-  </Layout>
-);
-```
-
-For edit forms that need existing data, co-locate data fetching in the page component:
-
-```tsx
-const EditPage = () => {
-  const { id } = useParams();
-  const [{ data, error, fetching }] = useQuery({
-    query: ResourceQuery,
-    variables: { id: id! },
-  });
-
-  if (fetching) return <Loading />;
-  if (error || !data?.resource) return <ErrorFallback ... />;
-
-  return (
-    <Layout columns={1} title="Edit Resource">
-      <Layout.Column>
-        <EditResourceForm resource={data.resource} />
-      </Layout.Column>
-    </Layout>
-  );
-};
-```
-
-## Form Component (components/{screen-name}-form.tsx)
-
-### Technology Stack
-
-- `react-hook-form` — form state management
-- `zod` + `@hookform/resolvers/zod` — validation
-- `useMutation` (urql) — GraphQL mutation
-- `useNavigate` (@tailor-platform/app-shell) — post-submit navigation
-
-### Pattern
-
-```tsx
-const formSchema = z.object({
-  title: z.string().min(1, "Title is required"),
-  description: z.string().optional(),
-});
-
-type FormValues = z.infer<typeof formSchema>;
-
-export const ScreenNameForm = () => {
-  const navigate = useNavigate();
-  const [, createResource] = useMutation(CreateMutation);
-
-  const form = useForm<FormValues>({
-    resolver: zodResolver(formSchema),
-    defaultValues: { title: "", description: "" },
-  });
-
-  const onSubmit = (values: FormValues) => {
-    void createResource({ input: values }).then((result) => {
-      if (!result.error) {
-        void navigate("..");
-      }
-    });
-  };
-
-  return (
-    <Form {...form}>
-      <form onSubmit={(e) => void form.handleSubmit(onSubmit)(e)} className="max-w-md space-y-4">
-        <FormField
-          control={form.control}
-          name="title"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Title</FormLabel>
-              <FormControl>
-                <Input placeholder="Enter title" {...field} />
-              </FormControl>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-        <div className="flex gap-2">
-          <Button type="submit">Create</Button>
-          <Button type="button" variant="outline" onClick={() => void navigate("..")}>
-            Cancel
-          </Button>
-        </div>
-      </form>
-    </Form>
-  );
-};
-```
-
-## Field Type Mapping
-
-| Field Type | Component                      | Zod Schema                      |
-| ---------- | ------------------------------ | ------------------------------- |
-| Text       | `<Input />`                    | `z.string()`                    |
-| Textarea   | `<textarea className="..." />` | `z.string()`                    |
-| Dropdown   | `<Select />`                   | `z.string()` or `z.enum([...])` |
-| Date       | `<Input type="date" />`        | `z.string()` (ISO format)       |
-| Number     | `<Input type="number" />`      | `z.coerce.number()`             |
-| Email      | `<Input type="email" />`       | `z.string().email()`            |
-| Checkbox   | `<Checkbox />`                 | `z.boolean()`                   |
-| Radio      | `<RadioGroup />`               | `z.enum([...])`                 |
-
-## Validation Mapping
-
-- **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
-- **Required: No** → `.optional()`
-
-## Key Points
-
-- Set `defaultValues` for all fields (empty string, false, etc.)
-- Navigate to `".."` after successful mutation
-- Cancel button must use `type="button"` to prevent form submit
-- For edit forms, accept fragment data as props and pre-fill `defaultValues`