@shanyucoder/flowgrid 0.1.0

package/adapters/nextjs/codegen/runners/validate-registry.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { access } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import {
+  REGISTRY_REL,
+  loadDesignRegistry,
+  lookupAlias
+} from './lib/design-registry.mjs'
+import { findMoleculeComponent } from './lib/component-resolve.mjs'
+
+const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+
+async function pathExists(relativePath) {
+  try {
+    await access(path.join(root, relativePath))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const registry = await loadDesignRegistry(root)
+  const errors = []
+  const warnings = []
+
+  console.log(`portal-design.registry v${registry.version} (${registry.canonicalSystem})`)
+  console.log(`  path: ${REGISTRY_REL}`)
+  console.log(`  shadcn components discovered: ${Object.keys(registry.components ?? {}).length}`)
+  console.log(`  shells: ${Object.keys(registry.shells ?? {}).join(', ')}`)
+
+  for (const [name, shell] of Object.entries(registry.shells ?? {})) {
+    const portalPath = shell.portal?.path
+    if (portalPath && shell.portal?.status === 'implemented') {
+      const exists = await pathExists(portalPath)
+      if (!exists) {
+        errors.push(`shell ${name}: missing ${portalPath}`)
+      }
+    }
+    if (portalPath?.endsWith('.vue') === false && shell.portal?.status === 'planned') {
+      warnings.push(`shell ${name}: status planned (${portalPath})`)
+    }
+  }
+
+  for (const [name, widget] of Object.entries(registry.fieldWidgets ?? {})) {
+    const portal = widget.portal ?? {}
+    const rel = portal.molecule
+      ? `components/molecules/**/${portal.molecule.replace(/^Mo/, '')}.vue`
+      : portal.ui
+        ? `components/ui/${String(portal.ui).replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')}`
+        : null
+    if (portal.status === 'implemented' && portal.molecule) {
+      const found = await findMoleculeComponent(root, portal.molecule)
+      if (!found) {
+        errors.push(`fieldWidget ${name}: molecule ${portal.molecule} not found`)
+      }
+    }
+    if (portal.status === 'planned') {
+      warnings.push(`fieldWidget ${name}: planned (${portal.molecule ?? portal.ui ?? rel})`)
+    }
+  }
+
+  for (const [alias, canonical] of Object.entries(registry.aliasIndex ?? {})) {
+    const resolved =
+      registry.shells?.[canonical] ||
+      registry.components?.[canonical] ||
+      registry.fieldWidgets?.[canonical] ||
+      registry.detailRenders?.[canonical] ||
+      lookupAlias(canonical, registry)
+    if (!resolved && canonical !== 'MoFabButton' && canonical !== 'DataPageHeader') {
+      warnings.push(`aliasIndex "${alias}" → "${canonical}" — target not verified in registry`)
+    }
+  }
+
+  for (const warning of warnings) {
+    console.warn(`  warn: ${warning}`)
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`  error: ${error}`)
+    }
+    process.exit(1)
+  }
+
+  console.log('  validate: OK')
+}
+
+async function findMolecule(root, baseName) {
+  const moName = baseName.startsWith('Mo') ? baseName : `Mo${baseName}`
+  return findMoleculeComponent(root, moName)
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/adapters/nextjs/codegen/templates/common/confirm-dialog.hbs

@@ -0,0 +1,81 @@
+{{!-- Common Confirm Dialog Pattern --}}
+import { useState } from 'react'
+import { Button } from '@/components/ui/button'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog'
+import { CheckCircle2 } from 'lucide-react'
+
+interface ConfirmDialogProps {
+  title?: string
+  description?: string
+  confirmText?: string
+  cancelText?: string
+  onConfirm: () => void | Promise<void>
+  trigger?: React.ReactNode
+}
+
+export function ConfirmDialog({
+  title = 'Are you sure?',
+  description = 'This action will proceed with the requested operation.',
+  confirmText = 'Confirm',
+  cancelText = 'Cancel',
+  onConfirm,
+  trigger
+}: ConfirmDialogProps) {
+  const [open, setOpen] = useState(false)
+  const [isPending, setIsPending] = useState(false)
+
+  const handleConfirm = async () => {
+    try {
+      setIsPending(true)
+      await onConfirm()
+      setOpen(false)
+    } catch (error) {
+      console.error('Confirmation action failed', error)
+    } finally {
+      setIsPending(false)
+    }
+  }
+
+  return (
+    <AlertDialog open={open} onOpenChange={setOpen}>
+      <AlertDialogTrigger asChild>
+        {trigger || (
+          <Button variant="outline" className="gap-2">
+            <CheckCircle2 className="h-4 w-4" />
+            {confirmText}
+          </Button>
+        )}
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>
+            {description}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel disabled={isPending}>{cancelText}</AlertDialogCancel>
+          <AlertDialogAction 
+            onClick={(e) => {
+              e.preventDefault()
+              handleConfirm()
+            }}
+            disabled={isPending}
+          >
+            {isPending ? 'Processing...' : confirmText}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}

package/adapters/nextjs/codegen/templates/common/delete-flow.hbs

@@ -0,0 +1,106 @@
+{{!-- Common Delete Flow Pattern --}}
+import { useState } from 'react'
+import { Button } from '@/components/ui/button'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog'
+import { Trash2 } from 'lucide-react'
+import { useToast } from '@/hooks/use-toast'
+
+{{#if apiPath}}
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { client } from '@/lib/api-client'
+{{/if}}
+
+interface DeleteFlowProps {
+  id: string | number
+  name?: string
+  onSuccess?: () => void
+}
+
+export function DeleteFlow({ id, name, onSuccess }: DeleteFlowProps) {
+  const [open, setOpen] = useState(false)
+  const { toast } = useToast()
+  {{#if apiPath}}
+  const queryClient = useQueryClient()
+  
+  const deleteMutation = useMutation({
+    mutationFn: async () => {
+      return client.delete(`{{{apiPath}}}/${id}`)
+    },
+    onSuccess: () => {
+      toast({
+        title: t('Deleted successfully'),
+        description: `The item ${name ? `"${name}" ` : ''}has been deleted.`,
+      })
+      setOpen(false)
+      queryClient.invalidateQueries({ queryKey: ['{{{apiKey}}}'] })
+      onSuccess?.()
+    },
+    onError: (error) => {
+      toast({
+        title: t('Delete failed'),
+        description: error.message || 'An unexpected error occurred.',
+        variant: 'destructive',
+      })
+    }
+  })
+  {{/if}}
+
+  const handleDelete = () => {
+    {{#if apiPath}}
+    deleteMutation.mutate()
+    {{else}}
+    console.warn('No API path provided for DeleteFlow. Implement custom delete logic here.')
+    toast({
+      title: t('Action required'),
+      description: 'API integration is missing for this delete flow.',
+    })
+    setOpen(false)
+    {{/if}}
+  }
+
+  return (
+    <AlertDialog open={open} onOpenChange={setOpen}>
+      <AlertDialogTrigger asChild>
+        <Button variant="ghost" size="icon" className="text-destructive hover:bg-destructive/10">
+          <Trash2 className="h-4 w-4" />
+        </Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This action cannot be undone. This will permanently delete the item
+            {name ? ` "${name}"` : ''} and remove its data from our servers.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction 
+            onClick={(e) => {
+              e.preventDefault()
+              handleDelete()
+            }}
+            className="bg-destructive hover:bg-destructive/90"
+            {{#if apiPath}}disabled={deleteMutation.isPending}{{/if}}
+          >
+            {{#if apiPath}}
+              {deleteMutation.isPending ? 'Deleting...' : 'Delete'}
+            {{else}}
+              Delete
+            {{/if}}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}

package/adapters/nextjs/codegen/templates/create/form.tsx.hbs

@@ -0,0 +1,45 @@
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { Button, Input, Label } from '@/components/ui';
+import { use{{entityPascal}}Form } from '@/hooks/{{entity}}/use{{entityPascal}}Form';
+
+export function {{entityPascal}}Form() {
+  const router = useRouter();
+  const { values, setField, pending, errorMsg, submit } = use{{entityPascal}}Form();
+
+  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const ok = await submit();
+    if (ok) router.push('{{listRoutePath}}');
+  }
+
+  return (
+    <form
+      onSubmit={onSubmit}
+      className="max-w-lg space-y-4"
+      data-testid="{{testIdModule}}-form"
+    >
+{{#each formFields}}
+{{#if hidden}}
+      <input type="hidden" name="{{key}}" value={String(values.{{key}} ?? '')} data-testid="{{../testIdModule}}-{{key}}-hidden" />
+{{else}}
+      <div>
+        <Label htmlFor="{{key}}">{t('{{label}}')}</Label>
+        <Input
+          id="{{key}}"
+          data-testid="{{../testIdModule}}-{{key}}-input"
+          value={String(values.{{key}} ?? '')}
+          onChange={(event) => setField('{{key}}', event.target.value)}
+          {{#if visual.maxWidth}}data-max-width="{{visual.maxWidth}}"{{/if}}
+        />
+      </div>
+{{/if}}
+{{/each}}
+      {errorMsg ? <p className="text-sm text-destructive">{errorMsg}</p> : null}
+      <Button type="submit" disabled={pending} data-testid="{{testIdModule}}-submit-btn">
+        {pending ? 'Saving…' : 'Save'}
+      </Button>
+    </form>
+  );
+}

package/adapters/nextjs/codegen/templates/create/mock.ts.hbs

@@ -0,0 +1,15 @@
+import type { {{entityPascal}}, {{entityPascal}}CreateRequest } from '@portal/models/{{entity}}';
+
+/**
+ * Prototype mock create — replace with service.create on /wire.
+ */
+export async function {{entityCamel}}MockCreate(
+  payload: {{entityPascal}}CreateRequest,
+): Promise<{{entityPascal}}> {
+  await new Promise((resolve) => setTimeout(resolve, 80));
+
+  return {
+    id: Date.now(),
+    ...payload,
+  } as {{entityPascal}};
+}

package/adapters/nextjs/codegen/templates/create/page.tsx.hbs

@@ -0,0 +1,12 @@
+'use client';
+
+import { {{entityPascal}}Form } from '@/components/{{entity}}/{{entityPascal}}Form';
+
+export default function {{entityPascal}}CreatePage() {
+  return (
+    <div data-testid="{{testIdModule}}-page" className="p-6">
+      <h1 className="text-2xl font-semibold mb-6">{t('{{title}}')}</h1>
+      <{{entityPascal}}Form />
+    </div>
+  );
+}

package/adapters/nextjs/codegen/templates/create/service.ts.hbs

@@ -0,0 +1,25 @@
+import {
+  {{entityPascal}}CreateRequestSchema,
+  {{entityPascal}}ReadSchema,
+} from '@portal/models/{{entity}}';
+import type { {{entityPascal}}CreateRequest, {{entityPascal}} } from '@portal/models/{{entity}}';
+import type { ApiResponse } from '@portal/models/common/api.types';
+import { apiFetch } from '@/lib/api-client';
+import { assertApiSuccess, parseApiData } from '@/services/shared/api-response';
+
+type ApiFetch = typeof apiFetch;
+
+export function create{{entityPascal}}FormService(fetch: ApiFetch = apiFetch) {
+  return {
+    async create(payload: {{entityPascal}}CreateRequest): Promise<{{entityPascal}}> {
+      const res = await fetch<ApiResponse<unknown>>('{{createEndpoint.path}}', {
+        method: '{{createEndpoint.method}}',
+        body: payload,
+      });
+      assertApiSuccess(res);
+      return parseApiData({{entityPascal}}ReadSchema, res.data);
+    },
+  };
+}
+
+export type {{entityPascal}}FormService = ReturnType<typeof create{{entityPascal}}FormService>;

package/adapters/nextjs/codegen/templates/create/useForm.ts.hbs

@@ -0,0 +1,59 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+import type { {{entityPascal}}CreateRequest } from '@portal/models/{{entity}}';
+import { {{entityCamel}}CreateFormSchema } from '@/validations/{{entity}}/schemas';
+import { create{{entityPascal}}FormService } from '@/services/{{entity}}Form.service';
+import { {{entityCamel}}MockCreate } from '@/mocks/{{entity}}.mock';
+
+const initialValues: Record<string, unknown> = {
+{{#each formFields}}
+  {{key}}: {{#if (eq type 'number')}}0{{else}}''{{/if}},
+{{/each}}
+};
+
+/**
+ * {{title}} — create form hook (portal-gen).
+ * Mock boundary: replace {{entityCamel}}MockCreate with service.create on /wire.
+ */
+export function use{{entityPascal}}Form() {
+  const service = useMemo(() => create{{entityPascal}}FormService(), []);
+  const [pending, setPending] = useState(false);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const [values, setValues] = useState<Record<string, unknown>>(initialValues);
+
+  const setField = useCallback((key: string, value: unknown) => {
+    setValues((current) => ({ ...current, [key]: value }));
+  }, []);
+
+  const submit = useCallback(async (): Promise<boolean> => {
+    setPending(true);
+    setErrorMsg(null);
+
+    const parsed = {{entityCamel}}CreateFormSchema.safeParse(values);
+    if (!parsed.success) {
+      setErrorMsg(parsed.error.issues[0]?.message ?? 'Invalid form');
+      setPending(false);
+      return false;
+    }
+
+    try {
+      await {{entityCamel}}MockCreate(parsed.data as {{entityPascal}}CreateRequest);
+      return true;
+    } catch (error: unknown) {
+      setErrorMsg((error as Error)?.message ?? 'Cannot create {{title}}');
+      return false;
+    } finally {
+      setPending(false);
+    }
+  }, [values]);
+
+  return {
+    values,
+    setField,
+    pending,
+    errorMsg,
+    submit,
+    service,
+  };
+}

package/adapters/nextjs/codegen/templates/create/validation.ts.hbs

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+import { {{entityPascal}}CreateRequestSchema } from '@portal/models/{{entity}}';
+import { fields } from '@portal/models/common/fields';
+
+export const {{entityCamel}}CreateObjectSchema = z.object({
+{{#each formFieldSchemas}}
+  {{key}}: {{{zodField}}},
+{{/each}}
+});
+
+/** Strict form validation (portal validations layer). */
+export const {{entityCamel}}CreateFormSchema = {{entityCamel}}CreateObjectSchema;
+
+/** API contract — re-export from models. */
+export { {{entityPascal}}CreateRequestSchema };

package/adapters/nextjs/codegen/templates/list/mock.ts.hbs

@@ -0,0 +1,25 @@
+import type { {{entityPascal}}ListResponse } from '@portal/models/{{entity}}';
+
+const PAGE1 = {{{json mockRowsPage1}}} as Record<string, unknown>[];
+const PAGE2 = {{{json mockRowsPage2}}} as Record<string, unknown>[];
+
+/**
+ * Prototype mock search — replace with service.search on /wire.
+ */
+export async function {{entityCamel}}MockSearch(
+  query: Record<string, unknown> = {},
+): Promise<{{entityPascal}}ListResponse> {
+  await new Promise((resolve) => setTimeout(resolve, 80));
+
+  const page = Number(query.page ?? 1);
+  const perPage = Number(query.per_page ?? {{defaultPageSize}});
+  const source = page <= 1 ? PAGE1 : PAGE2;
+  const items = source.slice(0, perPage);
+
+  return {
+    items,
+    total: PAGE1.length + PAGE2.length,
+    page,
+    per_page: perPage,
+  };
+}

package/adapters/nextjs/codegen/templates/list/page.custom.tsx.hbs

@@ -0,0 +1,65 @@
+'use client';
+
+import { useEffect } from 'react';
+import { DataListPage } from '@/components/common';
+import { use{{entityPascal}}List } from '@/hooks/{{entity}}/use{{entityPascal}}List';
+
+/**
+ * Custom list shell — extend slots / toolbar in /prototype, then re-run portal:gen.
+ */
+export default function {{entityPascal}}ListPage() {
+  const {
+    columns,
+    items,
+    pending,
+    total,
+    searchKeys,
+    load,
+  } = use{{entityPascal}}List();
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  return (
+    <DataListPage
+      title={t('{{title}}')}
+      testId="{{testIdModule}}-page"
+      tableTestId="{{testIdModule}}-table"
+      toolbarTestId="{{testIdModule}}-toolbar"
+      paginationTestId="{{testIdModule}}-pagination"
+      rowTestId="{{testIdModule}}-row"
+      columns={columns}
+      items={items}
+      pending={pending}
+      total={total ?? undefined}
+      pageSize={{{defaultPageSize}}}
+      searchKeys={searchKeys}
+      renderCell={(key, _row, value) => {
+{{#each slotBindings}}
+        if (key === '{{slot}}') {
+{{#if wired}}
+          return (
+            <{{component}}
+              {{#if (eq valueProp 'label')}}
+              label={t(String(value ?? ''))}
+              {{else}}
+              {{valueProp}}={value}
+              {{/if}}
+              testId="{{../testIdModule}}-{{slot}}"
+            />
+          );
+{{else}}
+          return (
+            <span data-testid="{{../testIdModule}}-{{slot}}-placeholder">
+              {String(value ?? '')}
+            </span>
+          );
+{{/if}}
+        }
+{{/each}}
+        return undefined;
+      }}
+    />
+  );
+}

package/adapters/nextjs/codegen/templates/list/page.tsx.hbs

@@ -0,0 +1,37 @@
+'use client';
+
+import { useEffect } from 'react';
+import { DataListPage } from '@/components/common';
+import { use{{entityPascal}}List } from '@/hooks/{{entity}}/use{{entityPascal}}List';
+
+export default function {{entityPascal}}ListPage() {
+  const {
+    columns,
+    items,
+    pending,
+    total,
+    searchKeys,
+    load,
+  } = use{{entityPascal}}List();
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  return (
+    <DataListPage
+      title={t('{{title}}')}
+      testId="{{testIdModule}}-page"
+      tableTestId="{{testIdModule}}-table"
+      toolbarTestId="{{testIdModule}}-toolbar"
+      paginationTestId="{{testIdModule}}-pagination"
+      rowTestId="{{testIdModule}}-row"
+      columns={columns}
+      items={items}
+      pending={pending}
+      total={total ?? undefined}
+      pageSize={{{defaultPageSize}}}
+      searchKeys={searchKeys}
+    />
+  );
+}

package/adapters/nextjs/codegen/templates/list/service.ts.hbs

@@ -0,0 +1,37 @@
+import {
+  {{entityPascal}}ListResponseSchema,
+  type {{entityPascal}}ListResponse,
+} from '@portal/models/{{entity}}';
+import type { ApiResponse } from '@portal/models/common/api.types';
+import { apiFetch } from '@/lib/api-client';
+import { assertApiSuccess, parseApiData } from '@/services/shared/api-response';
+
+type ApiFetch = typeof apiFetch;
+
+export type {{entityPascal}}SearchParams = Record<string, unknown> & {
+  page?: number;
+  per_page?: number;
+};
+
+export function create{{entityPascal}}Service(fetch: ApiFetch = apiFetch) {
+  return {
+    async search(params?: {{entityPascal}}SearchParams): Promise<{{entityPascal}}ListResponse> {
+      const res = await fetch<ApiResponse<unknown>>('{{listEndpoint.path}}', {
+        method: '{{listEndpoint.method}}'{{#if (eq listEndpoint.method 'POST')}},
+        body: params{{/if}}{{#if (eq listEndpoint.method 'GET')}},
+        query: params{{/if}}
+      });
+      assertApiSuccess(res);
+      return parseApiData({{entityPascal}}ListResponseSchema, res.data);
+    }{{#if exportEndpoint}},
+    async exportReport(body: Record<string, unknown>): Promise<Blob> {
+      return fetch<Blob>('{{exportEndpoint.path}}', {
+        method: '{{exportEndpoint.method}}',
+        body,
+        responseType: 'blob',
+      });
+    }{{/if}}
+  };
+}
+
+export type {{entityPascal}}Service = ReturnType<typeof create{{entityPascal}}Service>;