create-appraisejs 0.3.0 → 0.3.1-alpha.1

package/templates/blank/src/app/(base)/locators/locator-helpers.ts

@@ -13,21 +13,11 @@ export type LocatorGroupSummary = {
 export type ConflictResolutionSummary = Pick<ConflictResolution, 'id'>
 
 function isLocatorGroupRow(value: unknown): value is LocatorGroupSummary {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'name' in value &&
-    typeof value.name === 'string'
-  )
+  return typeof value === 'object' && value !== null && 'name' in value && typeof value.name === 'string'
 }
 
 function isConflictRow(value: unknown): value is ConflictResolutionSummary {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'id' in value &&
-    typeof value.id === 'string'
-  )
+  return typeof value === 'object' && value !== null && 'id' in value && typeof value.id === 'string'
 }
 
 function isLocatorTableRow(value: unknown): value is LocatorTableRow {

package/templates/blank/src/app/(base)/locators/locator-sync-toast.ts

@@ -0,0 +1,34 @@
+import { toast } from '@/hooks/use-toast'
+
+export type LocatorSyncPayload = {
+  locatorsCreated: number
+  locatorsMergedToFile: number
+  conflicts: number
+  errors: string[]
+}
+
+export function showLocatorSyncToast(payload: LocatorSyncPayload, refresh: () => void) {
+  if (payload.errors.length > 0) {
+    toast({
+      variant: 'destructive',
+      title: 'Sync completed with errors',
+      description: `Created ${payload.locatorsCreated} locators, merged ${payload.locatorsMergedToFile} into files, ${payload.conflicts} conflicts detected. ${payload.errors.length} error(s) occurred.`,
+    })
+    refresh()
+    return
+  }
+
+  toast({
+    title: 'Sync completed successfully',
+    description: `Created ${payload.locatorsCreated} locators, merged ${payload.locatorsMergedToFile} into files, ${payload.conflicts} conflicts detected.`,
+  })
+  refresh()
+}
+
+export function showLocatorSyncFailureToast(description: string) {
+  toast({
+    variant: 'destructive',
+    title: 'Sync failed',
+    description,
+  })
+}

package/templates/blank/src/app/(base)/locators/locator-table-columns.tsx

@@ -9,66 +9,65 @@ import { deleteLocatorAction } from '@/actions/locator/locator-actions'
 import { formatDateTime } from '@/lib/utils'
 import type { LocatorTableRow } from './locator-helpers'
 
-export const locatorTableCols: ColumnDef<LocatorTableRow>[] =
-  [
-    {
-      id: 'select',
-      header: ({ table }) => (
-        <Checkbox
-          checked={table.getIsAllPageRowsSelected() || (table.getIsSomePageRowsSelected() && 'indeterminate')}
-          onCheckedChange={value => table.toggleAllPageRowsSelected(!!value)}
-          aria-label="Select all"
-          className="mr-2"
-        />
-      ),
-      cell: ({ row }) => (
-        <Checkbox
-          checked={row.getIsSelected()}
-          onCheckedChange={value => row.toggleSelected(!!value)}
-          aria-label="Select row"
-          className="mr-2"
-        />
-      ),
-      enableSorting: false,
-      enableHiding: false,
-    },
-    {
-      accessorKey: 'name',
-      header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
-    },
-    {
-      accessorKey: 'value',
-      header: ({ column }) => <DataTableColumnHeader column={column} title="Value" />,
+export const locatorTableCols: ColumnDef<LocatorTableRow>[] = [
+  {
+    id: 'select',
+    header: ({ table }) => (
+      <Checkbox
+        checked={table.getIsAllPageRowsSelected() || (table.getIsSomePageRowsSelected() && 'indeterminate')}
+        onCheckedChange={value => table.toggleAllPageRowsSelected(!!value)}
+        aria-label="Select all"
+        className="mr-2"
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        checked={row.getIsSelected()}
+        onCheckedChange={value => row.toggleSelected(!!value)}
+        aria-label="Select row"
+        className="mr-2"
+      />
+    ),
+    enableSorting: false,
+    enableHiding: false,
+  },
+  {
+    accessorKey: 'name',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
+  },
+  {
+    accessorKey: 'value',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Value" />,
+  },
+  {
+    accessorKey: 'locatorGroup.name',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Locator Group" />,
+    cell: ({ row }) => row.original.locatorGroup?.name ?? '-',
+  },
+  {
+    accessorKey: 'createdAt',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Created At" />,
+    cell: ({ row }) => {
+      return formatDateTime(row.original.createdAt)
     },
-    {
-      accessorKey: 'locatorGroup.name',
-      header: ({ column }) => <DataTableColumnHeader column={column} title="Locator Group" />,
-      cell: ({ row }) => row.original.locatorGroup?.name ?? '-',
+  },
+  {
+    accessorKey: 'updatedAt',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Updated At" />,
+    cell: ({ row }) => {
+      return formatDateTime(row.original.updatedAt)
     },
-    {
-      accessorKey: 'createdAt',
-      header: ({ column }) => <DataTableColumnHeader column={column} title="Created At" />,
-      cell: ({ row }) => {
-        return formatDateTime(row.original.createdAt)
-      },
-    },
-    {
-      accessorKey: 'updatedAt',
-      header: ({ column }) => <DataTableColumnHeader column={column} title="Updated At" />,
-      cell: ({ row }) => {
-        return formatDateTime(row.original.updatedAt)
-      },
-    },
-    {
-      id: 'actions',
-      cell: ({ row }) => {
-        const locator = row.original
-        return (
-          <TableActions
-            modifyLink={`/locators/modify/${locator.id}`}
-            deleteHandler={() => deleteLocatorAction([locator.id])}
-          />
-        )
-      },
+  },
+  {
+    id: 'actions',
+    cell: ({ row }) => {
+      const locator = row.original
+      return (
+        <TableActions
+          modifyLink={`/locators/modify/${locator.id}`}
+          deleteHandler={() => deleteLocatorAction([locator.id])}
+        />
+      )
     },
-  ]
+  },
+]

package/templates/blank/src/app/(base)/locators/modify/[id]/page.tsx

@@ -55,7 +55,7 @@ const ModifyLocator = async ({ params }: { params: Promise<{ id: string }> }) =>
       <div className="mb-8">
         <PageHeader>
           <span className="flex items-center">
-            <Crosshair className="mr-2 h-8 w-8" />
+            <Crosshair className="mr-2 size-8" />
             Modify Locator
           </span>
         </PageHeader>

package/templates/blank/src/app/(base)/locators/page.tsx

@@ -27,7 +27,7 @@ const Locators = async () => {
     return (
       <div className="flex min-h-[calc(100vh-20rem)] items-center justify-center">
         <EmptyState
-          icon={<Code className="h-8 w-8" />}
+          icon={<Code className="size-8" />}
           title="No locators found"
           description="Get started by creating a locator to identify elements on your pages"
           createRoute="/locators/create"
@@ -43,13 +43,11 @@ const Locators = async () => {
         <div>
           <PageHeader>
             <span className="flex items-center">
-              <Code className="mr-2 h-8 w-8" />
+              <Code className="mr-2 size-8" />
               Locators
             </span>
           </PageHeader>
-          <HeaderSubtitle>
-            Locators are the elements that are used to identify the elements on the page
-          </HeaderSubtitle>
+          <HeaderSubtitle>Locators are the elements that are used to identify the elements on the page</HeaderSubtitle>
         </div>
       </div>
       <Suspense fallback={<DataTableSkeleton />}>

package/templates/blank/src/app/(base)/locators/picker/page.tsx

@@ -1,5 +1,11 @@
+import type { Metadata } from 'next'
 import { redirect } from 'next/navigation'
 
+export const metadata: Metadata = {
+  title: 'Appraise | Locator Picker',
+  description: 'Opens the locator workspace to pick or create locators.',
+}
+
 const LocatorPickerPage = () => {
   redirect('/locators/create')
 }

package/templates/blank/src/app/(base)/locators/sync-locators-button.tsx

@@ -2,66 +2,25 @@
 
 import { Button } from '@/components/ui/button'
 import { RefreshCw } from 'lucide-react'
-import { useState } from 'react'
-import { syncLocatorsFromFilesAction } from '@/actions/locator/locator-actions'
-import { toast } from '@/hooks/use-toast'
+import { useTransition } from 'react'
 import { useRouter } from 'next/navigation'
 
-export function SyncLocatorsButton() {
-  const [isLoading, setIsLoading] = useState(false)
-  const router = useRouter()
-
-  const handleSync = async () => {
-    setIsLoading(true)
-    try {
-      const result = await syncLocatorsFromFilesAction()
-
-      if (result.status === 200 && result.data) {
-        const { locatorsCreated, locatorsMergedToFile, conflicts, errors } = result.data as {
-          locatorsCreated: number
-          locatorsMergedToFile: number
-          conflicts: number
-          errors: string[]
-        }
+import { runLocatorFileSync } from './locator-file-sync'
 
-        if (errors.length > 0) {
-          toast({
-            variant: 'destructive',
-            title: 'Sync completed with errors',
-            description: `Created ${locatorsCreated} locators, merged ${locatorsMergedToFile} into files, ${conflicts} conflicts detected. ${errors.length} error(s) occurred.`,
-          })
-        } else {
-          toast({
-            title: 'Sync completed successfully',
-            description: `Created ${locatorsCreated} locators, merged ${locatorsMergedToFile} into files, ${conflicts} conflicts detected.`,
-          })
-        }
+export function SyncLocatorsButton() {
+  const [isPending, startTransition] = useTransition()
+  const { refresh } = useRouter()
 
-        // Refresh the page to show updated data
-        router.refresh()
-      } else {
-        toast({
-          variant: 'destructive',
-          title: 'Sync failed',
-          description: result.error || 'An error occurred during sync',
-        })
-      }
-    } catch (error) {
-      toast({
-        variant: 'destructive',
-        title: 'Sync failed',
-        description: `An error occurred: ${error}`,
-      })
-    } finally {
-      setIsLoading(false)
-    }
+  const handleSync = () => {
+    startTransition(() => {
+      void runLocatorFileSync(refresh)
+    })
   }
 
   return (
-    <Button onClick={handleSync} disabled={isLoading} variant="outline">
-      <RefreshCw className={`h-4 w-4 ${isLoading ? 'animate-spin' : ''}`} />
-      {isLoading ? 'Syncing...' : 'Sync Locators'}
+    <Button onClick={handleSync} disabled={isPending} variant="outline">
+      <RefreshCw className={`size-4 ${isPending ? 'animate-spin' : ''}`} />
+      {isPending ? 'Syncing...' : 'Sync Locators'}
     </Button>
   )
 }
-

package/templates/blank/src/app/(base)/modules/modify/[id]/page.tsx

@@ -10,12 +10,13 @@ export const metadata: Metadata = {
 
 const ModifyModule = async ({ params }: { params: Promise<{ id: string }> }) => {
   const { id } = await params
-  const { data: moduleToBeEditedData, error: moduleToBeEditedError } = await getModuleByIdAction(id)
-
-  const { data: modulesData, error: modulesError } = await getAllModulesAction()
+  if (!id?.trim()) {
+    return <div>Error: Invalid module id.</div>
+  }
 
-  if (moduleToBeEditedError || modulesError) {
-    return <div>Error: {moduleToBeEditedError || modulesError}</div>
+  const { data: moduleToBeEditedData, error: moduleToBeEditedError } = await getModuleByIdAction(id)
+  if (moduleToBeEditedError) {
+    return <div>Error: {moduleToBeEditedError}</div>
   }
 
   const [moduleData] = getModuleTableRows([moduleToBeEditedData])
@@ -23,6 +24,11 @@ const ModifyModule = async ({ params }: { params: Promise<{ id: string }> }) =>
     return <div>Error: Module data is unavailable.</div>
   }
 
+  const { data: modulesData, error: modulesError } = await getAllModulesAction()
+  if (modulesError) {
+    return <div>Error: {modulesError}</div>
+  }
+
   const parentOptions = getModuleParentOptions(getModuleTableRows(modulesData), moduleData.id)
 
   return (

package/templates/blank/src/app/(base)/modules/module-form-helpers.ts

@@ -0,0 +1,12 @@
+import { moduleSchema, type Module as ModuleFormValues } from '@/constants/form-opts/module-form-opts'
+import type { ActionResponse } from '@/types/form/actionHandler'
+
+export type ModuleFormSubmitAction = (_prev: unknown, value: ModuleFormValues, id?: string) => Promise<ActionResponse>
+
+export const moduleFieldValidators = {
+  name: moduleSchema.shape.name,
+}
+
+export function getActionErrorMessage(response: ActionResponse) {
+  return response.error || response.message || 'Unable to save module.'
+}

package/templates/blank/src/app/(base)/modules/module-form.tsx

@@ -5,9 +5,11 @@ import ErrorMessage from '@/components/form/error-message'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
-import { formOpts, type Module, ROOT_MODULE_UUID } from '@/constants/form-opts/module-form-opts'
+import { moduleFormOpts, type Module, ROOT_MODULE_UUID } from '@/constants/form-opts/module-form-opts'
 import { toast } from '@/hooks/use-toast'
 import { useForm } from '@tanstack/react-form'
+import { Save } from 'lucide-react'
+import { TanStackForm } from '@/lib/form/tanstack-form'
 import { useRouter } from 'next/navigation'
 import {
   getActionErrorMessage,
@@ -30,6 +32,8 @@ type ModuleFieldErrorsProps = {
   isTouched: boolean
 }
 
+const EMPTY_PARENT_OPTIONS: ModuleParentOption[] = []
+
 function getErrorMessage(error: unknown) {
   if (typeof error === 'string') {
     return error
@@ -49,8 +53,8 @@ function ModuleFieldErrors({ errors, isTouched }: ModuleFieldErrorsProps) {
 
   return (
     <div className="flex flex-col gap-1" aria-live="polite">
-      {errors.map((error, index) => (
-        <ErrorMessage key={`${String(error)}-${index}`} message={getErrorMessage(error)} visible={true} />
+      {errors.map(error => (
+        <ErrorMessage key={getErrorMessage(error)} message={getErrorMessage(error)} visible={true} />
       ))}
     </div>
   )
@@ -60,14 +64,14 @@ const ModuleForm = ({
   defaultValues,
   successTitle,
   successMessage,
-  parentOptions = [],
+  parentOptions = EMPTY_PARENT_OPTIONS,
   id,
   onSubmitAction,
 }: ModuleFormProps) => {
-  const router = useRouter()
+  const { push } = useRouter()
   const form = useForm({
-    defaultValues: defaultValues ?? formOpts.defaultValues,
-    validators: formOpts.validators,
+    defaultValues: defaultValues ?? moduleFormOpts.defaultValues,
+    validators: moduleFormOpts.validators,
     onSubmit: async ({ value }) => {
       const res = await onSubmitAction(undefined, value, id)
       if (res.status === 200) {
@@ -75,7 +79,7 @@ const ModuleForm = ({
           title: successTitle,
           description: successMessage,
         })
-        router.push('/modules')
+        push('/modules')
       }
       if (res.status === 400) {
         toast({
@@ -94,13 +98,7 @@ const ModuleForm = ({
     },
   })
   return (
-    <form
-      onSubmit={e => {
-        e.preventDefault()
-        e.stopPropagation()
-        form.handleSubmit()
-      }}
-    >
+    <TanStackForm onSubmit={() => form.handleSubmit()}>
       <form.Field
         name="name"
         validators={{
@@ -125,9 +123,7 @@ const ModuleForm = ({
               <Select value={field.state.value || ROOT_MODULE_UUID} onValueChange={value => field.handleChange(value)}>
                 <SelectTrigger id={field.name}>
                   <SelectValue
-                    placeholder={
-                      parentOptions.length === 0 ? 'No parent modules available' : 'Select a parent or Root'
-                    }
+                    placeholder={parentOptions.length === 0 ? 'No parent modules available' : 'Select a parent or Root'}
                   />
                 </SelectTrigger>
                 <SelectContent>
@@ -148,11 +144,12 @@ const ModuleForm = ({
       <form.Subscribe selector={formState => [formState.canSubmit, formState.isSubmitting]}>
         {([canSubmit, isSubmitting]) => (
           <Button type="submit" disabled={!canSubmit}>
-            {isSubmitting ? '...' : 'Save'}
+            <Save className="size-4" aria-hidden />
+            <span className="font-bold">{isSubmitting ? '...' : 'Save'}</span>
           </Button>
         )}
       </form.Subscribe>
-    </form>
+    </TanStackForm>
   )
 }
 

package/templates/blank/src/app/(base)/modules/module-helpers.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  getActionErrorMessage,
+  getModuleFormParentId,
+  getModuleParentOptions,
+  getModuleTableRows,
+} from './module-helpers'
+
+const moduleRow = {
+  id: 'module-1',
+  name: 'Payments',
+  parentId: null,
+  parent: null,
+  createdAt: new Date('2026-01-01T00:00:00.000Z'),
+  updatedAt: new Date('2026-01-02T00:00:00.000Z'),
+}
+
+describe('module helpers', () => {
+  it('filters action data to valid module table rows', () => {
+    expect(getModuleTableRows([moduleRow, { id: 'bad-row', name: 'Missing dates' }])).toEqual([moduleRow])
+    expect(getModuleTableRows(undefined)).toEqual([])
+  })
+
+  it('builds selectable parent options and excludes the edited module', () => {
+    expect(
+      getModuleParentOptions(
+        [
+          moduleRow,
+          {
+            ...moduleRow,
+            id: 'module-2',
+            name: 'Checkout',
+          },
+        ],
+        'module-1',
+      ),
+    ).toEqual([{ id: 'module-2', name: 'Checkout' }])
+  })
+
+  it('falls back to the root module parent id and formats action errors', () => {
+    expect(getModuleFormParentId(null)).toBe('00000000-0000-0000-0000-000000000000')
+    expect(getModuleFormParentId('module-1')).toBe('module-1')
+    expect(getActionErrorMessage({ error: 'Nope' })).toBe('Nope')
+    expect(getActionErrorMessage({ message: 'Try again' })).toBe('Try again')
+    expect(getActionErrorMessage({})).toBe('Unable to save module.')
+  })
+})

package/templates/blank/src/app/(base)/modules/module-helpers.ts

@@ -1,64 +1,4 @@
-import { ROOT_MODULE_UUID, moduleSchema, type Module as ModuleFormValues } from '@/constants/form-opts/module-form-opts'
-import type { ModuleWithParent } from '@/services/module/module-service'
-import type { ActionResponse, ActionResponseData } from '@/types/form/actionHandler'
-
-export type ModuleTableRow = ModuleWithParent
-
-export type ModuleParentOption = {
-  id: string
-  name: string
-}
-
-export type ModuleFormSubmitAction = (
-  _prev: unknown,
-  value: ModuleFormValues,
-  id?: string,
-) => Promise<ActionResponse>
-
-export const moduleFieldValidators = {
-  name: moduleSchema.shape.name,
-}
-
-export function getActionErrorMessage(response: ActionResponse) {
-  return response.error || response.message || 'Unable to save module.'
-}
-
-export function getModuleParentOptions(modules: ModuleTableRow[], excludedId?: string): ModuleParentOption[] {
-  return modules
-    .filter(module => module.id !== excludedId)
-    .map(module => ({
-      id: module.id,
-      name: module.name,
-    }))
-}
-
-export function getModuleFormParentId(parentId: string | null | undefined) {
-  return parentId ?? ROOT_MODULE_UUID
-}
-
-function isModuleParent(value: unknown): value is ModuleTableRow['parent'] {
-  return value === null || (typeof value === 'object' && value !== null && 'name' in value && typeof value.name === 'string')
-}
-
-function isModuleTableRow(value: unknown): value is ModuleTableRow {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'name' in value &&
-    typeof value.name === 'string' &&
-    'parentId' in value &&
-    (typeof value.parentId === 'string' || value.parentId === null) &&
-    'createdAt' in value &&
-    value.createdAt instanceof Date &&
-    'updatedAt' in value &&
-    value.updatedAt instanceof Date &&
-    'parent' in value &&
-    isModuleParent(value.parent)
-  )
-}
-
-export function getModuleTableRows(data: ActionResponseData | undefined): ModuleTableRow[] {
-  return Array.isArray(data) ? data.filter(isModuleTableRow) : []
-}
+export { getActionErrorMessage, moduleFieldValidators, type ModuleFormSubmitAction } from './module-form-helpers'
+export { getModuleFormParentId, getModuleParentOptions } from './module-parent-helpers'
+export { getModuleTableRows } from './module-row-helpers'
+export type { ModuleParentOption, ModuleTableRow } from './module-types'

package/templates/blank/src/app/(base)/modules/module-parent-helpers.ts

@@ -0,0 +1,16 @@
+import { ROOT_MODULE_UUID } from '@/constants/form-opts/module-form-opts'
+
+import type { ModuleParentOption, ModuleTableRow } from './module-types'
+
+export function getModuleParentOptions(modules: ModuleTableRow[], excludedId?: string): ModuleParentOption[] {
+  return modules
+    .filter(module => module.id !== excludedId)
+    .map(module => ({
+      id: module.id,
+      name: module.name,
+    }))
+}
+
+export function getModuleFormParentId(parentId: string | null | undefined) {
+  return parentId ?? ROOT_MODULE_UUID
+}

package/templates/blank/src/app/(base)/modules/module-row-helpers.ts

@@ -0,0 +1,32 @@
+import type { ActionResponseData } from '@/types/form/actionHandler'
+
+import type { ModuleTableRow } from './module-types'
+
+function isModuleParent(value: unknown): value is ModuleTableRow['parent'] {
+  return (
+    value === null || (typeof value === 'object' && value !== null && 'name' in value && typeof value.name === 'string')
+  )
+}
+
+function isModuleTableRow(value: unknown): value is ModuleTableRow {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'name' in value &&
+    typeof value.name === 'string' &&
+    'parentId' in value &&
+    (typeof value.parentId === 'string' || value.parentId === null) &&
+    'createdAt' in value &&
+    value.createdAt instanceof Date &&
+    'updatedAt' in value &&
+    value.updatedAt instanceof Date &&
+    'parent' in value &&
+    isModuleParent(value.parent)
+  )
+}
+
+export function getModuleTableRows(data: ActionResponseData | undefined): ModuleTableRow[] {
+  return Array.isArray(data) ? data.filter(isModuleTableRow) : []
+}

package/templates/blank/src/app/(base)/modules/module-types.ts

@@ -0,0 +1,8 @@
+import type { ModuleWithParent } from '@/services/module/module-service'
+
+export type ModuleTableRow = ModuleWithParent
+
+export type ModuleParentOption = {
+  id: string
+  name: string
+}

package/templates/blank/src/app/(base)/modules/page.tsx

@@ -28,7 +28,7 @@ const Modules = async () => {
     return (
       <div className="flex min-h-[calc(100vh-20rem)] items-center justify-center">
         <EmptyState
-          icon={<Code className="h-8 w-8" />}
+          icon={<Code className="size-8" />}
           title="No modules found"
           description="Get started by creating a module to organize your application components"
           createRoute="/modules/create"
@@ -43,7 +43,7 @@ const Modules = async () => {
       <div className="mb-8">
         <PageHeader>
           <span className="flex items-center">
-            <Code className="mr-2 h-8 w-8" />
+            <Code className="mr-2 size-8" />
             Modules
           </span>
         </PageHeader>