create-appraisejs 0.3.0 → 0.3.1-alpha.0

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace-helpers.ts

@@ -1,333 +1,34 @@
-import type { GroupResolutionMode as PickerGroupResolutionMode, LocatorPickerSession } from '@/types/locator-picker'
-import type { ActionResponseData } from '@/types/form/actionHandler'
-import type { Environment, Locator, LocatorGroup, Module } from '@prisma/client'
-
-import { inferGroupSuggestion, normalizeRoute, suggestLocatorName } from '@/lib/locator-picker/suggestions'
-
-export type LocatorSourceType = 'environment' | 'url'
-export type LocatorWorkspaceMode = 'create' | 'modify'
-export type GroupResolutionMode = PickerGroupResolutionMode
-
-export const locatorSourceTypes = ['environment', 'url'] as const
-export const locatorWorkspaceResolutionModes = ['existing', 'create'] as const
-
-export type LocatorWorkspaceInitialValues = {
-  locatorName?: string
-  selector?: string
-  resolutionMode?: GroupResolutionMode
-  existingLocatorGroupId?: string
-  newLocatorGroupName?: string
-  route?: string
-  moduleId?: string
-}
-
-export type CreateLocatorWorkspaceProps = {
-  environments: Environment[]
-  locatorGroups: LocatorGroup[]
-  modules: Module[]
-  mode?: LocatorWorkspaceMode
-  locatorId?: string
-  initialValues?: LocatorWorkspaceInitialValues
-}
-
-export type LocatorWorkspaceState = {
-  sourceType: LocatorSourceType
-  environmentId: string
-  url: string
-  locatorName: string
-  selector: string
-  resolutionMode: GroupResolutionMode
-  existingLocatorGroupId: string
-  newLocatorGroupName: string
-  route: string
-  moduleId: string
-  lastAutoLocatorName: string
-  lastAutoSelector: string
-  lastAutoExistingGroupId: string
-  lastAutoGroupName: string
-  lastAutoRoute: string
-  lastAutoModuleId: string
-}
-
-export function statusTone(status: LocatorPickerSession['status']) {
-  switch (status) {
-    case 'picked':
-      return 'default'
-    case 'saving':
-      return 'secondary'
-    case 'closed':
-      return 'outline'
-    case 'error':
-      return 'destructive'
-    case 'ready':
-      return 'secondary'
-    case 'starting':
-    default:
-      return 'secondary'
-  }
-}
-
-export function formatStatus(status: LocatorPickerSession['status']) {
-  return status === 'picked' ? 'Picked' : `${status.charAt(0).toUpperCase()}${status.slice(1)}`
-}
-
-export function createInitialWorkspaceState(
-  environments: Environment[],
-  initialValues?: LocatorWorkspaceInitialValues,
-): LocatorWorkspaceState {
-  const initialRoute = normalizeRoute(initialValues?.route ?? '/')
-
-  return {
-    sourceType: environments.length > 0 ? 'environment' : 'url',
-    environmentId: environments[0]?.id ?? '',
-    url: '',
-    locatorName: initialValues?.locatorName ?? '',
-    selector: initialValues?.selector ?? '',
-    resolutionMode: initialValues?.resolutionMode ?? 'existing',
-    existingLocatorGroupId: initialValues?.existingLocatorGroupId ?? '',
-    newLocatorGroupName: initialValues?.newLocatorGroupName ?? '',
-    route: initialRoute,
-    moduleId: initialValues?.moduleId ?? '',
-    lastAutoLocatorName: initialValues?.locatorName ?? '',
-    lastAutoSelector: initialValues?.selector ?? '',
-    lastAutoExistingGroupId: initialValues?.existingLocatorGroupId ?? '',
-    lastAutoGroupName: initialValues?.newLocatorGroupName ?? '',
-    lastAutoRoute: initialRoute,
-    lastAutoModuleId: initialValues?.moduleId ?? '',
-  }
-}
-
-export function getPickerPayloadSignature(session: LocatorPickerSession | null) {
-  const pickedLocator = session?.pickedLocator
-  if (!session || !pickedLocator) {
-    return ''
-  }
-
-  return `${session.updatedAt}:${pickedLocator.currentUrl}:${pickedLocator.selector}`
-}
-
-export function applyPickedLocatorToWorkspaceState(
-  currentState: LocatorWorkspaceState,
-  session: LocatorPickerSession,
-  locatorGroups: LocatorGroup[],
-  modules: Module[],
-): LocatorWorkspaceState {
-  const pickedLocator = session.pickedLocator
-  if (!pickedLocator) {
-    return currentState
-  }
-
-  const nextState = { ...currentState }
-
-  if (currentState.selector === '' || currentState.selector === currentState.lastAutoSelector) {
-    nextState.selector = pickedLocator.selector
-    nextState.lastAutoSelector = pickedLocator.selector
-  }
-
-  const suggestedName = suggestLocatorName(pickedLocator)
-  if (suggestedName && (currentState.locatorName === '' || currentState.locatorName === currentState.lastAutoLocatorName)) {
-    nextState.locatorName = suggestedName
-    nextState.lastAutoLocatorName = suggestedName
-  }
-
-  const suggestion = inferGroupSuggestion(pickedLocator.pathname, pickedLocator.pageTitle, locatorGroups, modules)
-
-  if (currentState.route === '/' || currentState.route === '' || currentState.route === currentState.lastAutoRoute) {
-    nextState.route = suggestion.route
-    nextState.lastAutoRoute = suggestion.route
-  }
-
-  if (suggestion.mode === 'existing') {
-    nextState.resolutionMode = currentState.resolutionMode === 'create' ? 'existing' : currentState.resolutionMode
-
-    const nextExistingGroupId = suggestion.existingLocatorGroupId ?? ''
-    if (
-      currentState.existingLocatorGroupId === '' ||
-      currentState.existingLocatorGroupId === currentState.lastAutoExistingGroupId
-    ) {
-      nextState.existingLocatorGroupId = nextExistingGroupId
-      nextState.lastAutoExistingGroupId = nextExistingGroupId
-    }
-  } else {
-    if (
-      currentState.resolutionMode === 'create' ||
-      currentState.existingLocatorGroupId === '' ||
-      currentState.existingLocatorGroupId === currentState.lastAutoExistingGroupId
-    ) {
-      nextState.resolutionMode = 'create'
-    }
-
-    if (currentState.newLocatorGroupName === '' || currentState.newLocatorGroupName === currentState.lastAutoGroupName) {
-      nextState.newLocatorGroupName = suggestion.suggestedGroupName
-      nextState.lastAutoGroupName = suggestion.suggestedGroupName
-    }
-
-    if (currentState.moduleId === '' || currentState.moduleId === currentState.lastAutoModuleId) {
-      const nextModuleId = suggestion.suggestedModuleId ?? ''
-      nextState.moduleId = nextModuleId
-      nextState.lastAutoModuleId = nextModuleId
-    }
-  }
-
-  return nextState
-}
-
-export function createWorkspaceAutoFillSnapshot(state: LocatorWorkspaceState) {
-  return {
-    lastAutoLocatorName: state.locatorName,
-    lastAutoSelector: state.selector,
-    lastAutoExistingGroupId: state.existingLocatorGroupId,
-    lastAutoGroupName: state.newLocatorGroupName,
-    lastAutoRoute: state.route,
-    lastAutoModuleId: state.moduleId,
-  }
-}
-
-export function canSaveLocator(state: LocatorWorkspaceState) {
-  return (
-    state.locatorName.trim() !== '' &&
-    state.selector.trim() !== '' &&
-    ((state.resolutionMode === 'existing' && state.existingLocatorGroupId !== '') ||
-      (state.resolutionMode === 'create' && state.newLocatorGroupName.trim() !== '' && state.moduleId !== ''))
-  )
-}
-
-export function canLaunchPicker(state: LocatorWorkspaceState) {
-  return state.sourceType === 'environment' ? state.environmentId !== '' : state.url.trim() !== ''
-}
-
-export function getLocatorSourceType(value: string): LocatorSourceType {
-  return locatorSourceTypes.find(sourceType => sourceType === value) ?? 'environment'
-}
-
-export function getLocatorWorkspaceResolutionMode(value: string): GroupResolutionMode {
-  return locatorWorkspaceResolutionModes.find(resolutionMode => resolutionMode === value) ?? 'existing'
-}
-
-function isEnvironmentRow(value: unknown): value is Environment {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'name' in value &&
-    typeof value.name === 'string' &&
-    'baseUrl' in value &&
-    typeof value.baseUrl === 'string' &&
-    'apiBaseUrl' in value &&
-    (typeof value.apiBaseUrl === 'string' || value.apiBaseUrl === null) &&
-    'username' in value &&
-    (typeof value.username === 'string' || value.username === null) &&
-    'password' in value &&
-    (typeof value.password === 'string' || value.password === null) &&
-    'createdAt' in value &&
-    value.createdAt instanceof Date &&
-    'updatedAt' in value &&
-    value.updatedAt instanceof Date
-  )
-}
-
-function isLocatorGroupRow(value: unknown): value is LocatorGroup {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'name' in value &&
-    typeof value.name === 'string' &&
-    'route' in value &&
-    typeof value.route === 'string' &&
-    'moduleId' in value &&
-    typeof value.moduleId === 'string' &&
-    'createdAt' in value &&
-    value.createdAt instanceof Date &&
-    'updatedAt' in value &&
-    value.updatedAt instanceof Date
-  )
-}
-
-function isModuleRow(value: unknown): value is Module {
-  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
-  )
-}
-
-function isLocatorRow(value: unknown): value is Locator & { locatorGroup?: LocatorGroup | null } {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'name' in value &&
-    typeof value.name === 'string' &&
-    'value' in value &&
-    typeof value.value === 'string' &&
-    'locatorGroupId' in value &&
-    (typeof value.locatorGroupId === 'string' || value.locatorGroupId === null) &&
-    'createdAt' in value &&
-    value.createdAt instanceof Date &&
-    'updatedAt' in value &&
-    value.updatedAt instanceof Date
-  )
-}
-
-function isLocatorPickerSession(value: unknown): value is LocatorPickerSession {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'sessionId' in value &&
-    typeof value.sessionId === 'string' &&
-    'launchSource' in value &&
-    typeof value.launchSource === 'object' &&
-    value.launchSource !== null &&
-    'url' in value.launchSource &&
-    typeof value.launchSource.url === 'string' &&
-    'browserName' in value &&
-    value.browserName === 'chromium' &&
-    'status' in value &&
-    typeof value.status === 'string' &&
-    'currentUrl' in value &&
-    typeof value.currentUrl === 'string' &&
-    'currentPathname' in value &&
-    typeof value.currentPathname === 'string' &&
-    'pageTitle' in value &&
-    typeof value.pageTitle === 'string' &&
-    'companionPid' in value &&
-    (typeof value.companionPid === 'number' || value.companionPid === null) &&
-    'startedAt' in value &&
-    typeof value.startedAt === 'string' &&
-    'updatedAt' in value &&
-    typeof value.updatedAt === 'string'
-  )
-}
-
-export function getEnvironmentRows(data: ActionResponseData | undefined): Environment[] {
-  return Array.isArray(data) ? data.filter(isEnvironmentRow) : []
-}
-
-export function getLocatorGroupRows(data: ActionResponseData | undefined): LocatorGroup[] {
-  return Array.isArray(data) ? data.filter(isLocatorGroupRow) : []
-}
-
-export function getModuleRows(data: ActionResponseData | undefined): Module[] {
-  return Array.isArray(data) ? data.filter(isModuleRow) : []
-}
-
-export function getLocatorRow(data: ActionResponseData | undefined) {
-  return isLocatorRow(data) ? data : null
-}
-
-export function getLocatorPickerSession(data: ActionResponseData | undefined) {
-  return isLocatorPickerSession(data) ? data : null
-}
+export type {
+  CreateLocatorWorkspaceProps,
+  GroupResolutionMode,
+  InlineLocatorSaveResult,
+  LocatorSourceType,
+  LocatorWorkspaceDisplayMode,
+  LocatorWorkspaceEnvironment,
+  LocatorWorkspaceInitialValues,
+  LocatorWorkspaceLocatorGroup,
+  LocatorWorkspaceMode,
+  LocatorWorkspaceModule,
+  LocatorWorkspaceState,
+} from './create-locator-workspace-types'
+export { locatorSourceTypes, locatorWorkspaceResolutionModes } from './create-locator-workspace-types'
+export {
+  applyPickedLocatorToWorkspaceState,
+  canLaunchPicker,
+  canSaveLocator,
+  createInitialWorkspaceState,
+  createWorkspaceAutoFillSnapshot,
+  formatStatus,
+  getLocatorSourceType,
+  getLocatorWorkspaceResolutionMode,
+  getPickerPayloadSignature,
+  statusTone,
+} from './create-locator-workspace-state'
+export {
+  getEnvironmentRows,
+  getInlineLocatorSaveResult,
+  getLocatorGroupRows,
+  getLocatorPickerSession,
+  getLocatorRow,
+  getModuleRows,
+} from './create-locator-workspace-response'

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace-response.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  getEnvironmentRows,
+  getInlineLocatorSaveResult,
+  getLocatorGroupRows,
+  getLocatorPickerSession,
+  getLocatorRow,
+  getModuleRows,
+} from './create-locator-workspace-response'
+
+describe('create-locator-workspace response helpers', () => {
+  const now = new Date('2026-05-12T00:00:00.000Z')
+
+  it('filters action response row payloads by expected shape', () => {
+    const environment = {
+      id: 'env-1',
+      name: 'Local',
+      baseUrl: 'https://example.com',
+      apiBaseUrl: null,
+      username: null,
+      password: null,
+      createdAt: now,
+      updatedAt: now,
+    }
+    const locatorGroup = {
+      id: 'group-1',
+      name: 'Login',
+      route: '/login',
+      moduleId: 'module-1',
+      createdAt: now,
+      updatedAt: now,
+    }
+    const moduleRow = {
+      id: 'module-1',
+      name: 'Auth',
+      parentId: null,
+      createdAt: now,
+      updatedAt: now,
+    }
+
+    expect(getEnvironmentRows([environment, { ...environment, baseUrl: null }])).toEqual([environment])
+    expect(getLocatorGroupRows([locatorGroup, { ...locatorGroup, moduleId: null }])).toEqual([locatorGroup])
+    expect(getModuleRows([moduleRow, { ...moduleRow, createdAt: 'today' }])).toEqual([moduleRow])
+  })
+
+  it('returns locator picker session, locator row, and inline save results from valid action payloads', () => {
+    const locator = {
+      id: 'locator-1',
+      name: 'Login button',
+      value: 'button[data-testid="login"]',
+      locatorGroupId: 'group-1',
+      createdAt: now,
+      updatedAt: now,
+    }
+    const session = {
+      sessionId: 'session-1',
+      launchSource: { url: 'https://example.com' },
+      browserName: 'chromium',
+      status: 'ready',
+      currentUrl: 'https://example.com/login',
+      currentPathname: '/login',
+      pageTitle: 'Login',
+      companionPid: null,
+      startedAt: '2026-05-12T00:00:00.000Z',
+      updatedAt: '2026-05-12T00:00:01.000Z',
+    }
+    const inlineResult = {
+      locatorId: 'locator-1',
+      locatorName: 'Login button',
+      locatorGroupId: 'group-1',
+      locatorGroupName: 'Login',
+      selector: 'button[data-testid="login"]',
+      route: '/login',
+      moduleId: 'module-1',
+    }
+
+    expect(getLocatorRow(locator)).toEqual(locator)
+    expect(getLocatorPickerSession(session)).toEqual(session)
+    expect(getInlineLocatorSaveResult(inlineResult)).toEqual(inlineResult)
+    expect(getLocatorRow({ ...locator, value: null })).toBeNull()
+    expect(getLocatorPickerSession({ ...session, browserName: 'firefox' })).toBeNull()
+    expect(getInlineLocatorSaveResult({ ...inlineResult, selector: null })).toBeNull()
+  })
+})

package/templates/starter/src/app/(base)/locators/create/create-locator-workspace-response.ts

@@ -0,0 +1,125 @@
+import type {
+  ActionResponseData,
+  Environment,
+  InlineLocatorSaveResult,
+  Locator,
+  LocatorGroup,
+  LocatorPickerSession,
+  Module,
+} from './create-locator-workspace-types'
+
+type UnknownRecord = Record<string, unknown>
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null
+}
+
+function hasStringProp(value: UnknownRecord, property: string) {
+  return typeof value[property] === 'string'
+}
+
+function hasNullableStringProp(value: UnknownRecord, property: string) {
+  return typeof value[property] === 'string' || value[property] === null
+}
+
+function hasDateProp(value: UnknownRecord, property: string) {
+  return value[property] instanceof Date
+}
+
+function hasStringProps<T extends string>(
+  value: UnknownRecord,
+  properties: readonly T[],
+): value is UnknownRecord & Record<T, string> {
+  return properties.every(property => hasStringProp(value, property))
+}
+
+function hasNullableStringProps(value: UnknownRecord, properties: string[]) {
+  return properties.every(property => hasNullableStringProp(value, property))
+}
+
+function hasDateProps(value: UnknownRecord) {
+  return hasDateProp(value, 'createdAt') && hasDateProp(value, 'updatedAt')
+}
+
+function isEnvironmentRow(value: unknown): value is Environment {
+  return (
+    isRecord(value) &&
+    hasStringProps(value, ['id', 'name', 'baseUrl']) &&
+    hasNullableStringProps(value, ['apiBaseUrl', 'username', 'password']) &&
+    hasDateProps(value)
+  )
+}
+
+function isLocatorGroupRow(value: unknown): value is LocatorGroup {
+  return (
+    isRecord(value) && hasStringProps(value, ['id', 'name', 'route', 'moduleId']) && hasDateProps(value)
+  )
+}
+
+function isModuleRow(value: unknown): value is Module {
+  return (
+    isRecord(value) &&
+    hasStringProps(value, ['id', 'name']) &&
+    hasNullableStringProp(value, 'parentId') &&
+    hasDateProps(value)
+  )
+}
+
+function isLocatorRow(value: unknown): value is Locator & { locatorGroup?: LocatorGroup | null } {
+  return (
+    isRecord(value) &&
+    hasStringProps(value, ['id', 'name', 'value']) &&
+    hasNullableStringProp(value, 'locatorGroupId') &&
+    hasDateProps(value)
+  )
+}
+
+function isLocatorPickerSession(value: unknown): value is LocatorPickerSession {
+  if (!isRecord(value) || !isRecord(value.launchSource)) {
+    return false
+  }
+
+  return (
+    value.browserName === 'chromium' &&
+    hasStringProp(value.launchSource, 'url') &&
+    hasStringProps(value, ['sessionId', 'status', 'currentUrl', 'currentPathname', 'pageTitle', 'startedAt', 'updatedAt']) &&
+    (typeof value.companionPid === 'number' || value.companionPid === null) &&
+    'companionPid' in value
+  )
+}
+
+export function getEnvironmentRows(data: ActionResponseData | undefined): Environment[] {
+  return Array.isArray(data) ? data.filter(isEnvironmentRow) : []
+}
+
+export function getLocatorGroupRows(data: ActionResponseData | undefined): LocatorGroup[] {
+  return Array.isArray(data) ? data.filter(isLocatorGroupRow) : []
+}
+
+export function getModuleRows(data: ActionResponseData | undefined): Module[] {
+  return Array.isArray(data) ? data.filter(isModuleRow) : []
+}
+
+export function getLocatorRow(data: ActionResponseData | undefined) {
+  return isLocatorRow(data) ? data : null
+}
+
+export function getLocatorPickerSession(data: ActionResponseData | undefined) {
+  return isLocatorPickerSession(data) ? data : null
+}
+
+export function getInlineLocatorSaveResult(data: ActionResponseData | undefined): InlineLocatorSaveResult | null {
+  if (isRecord(data) && hasStringProps(data, ['locatorId', 'locatorName', 'locatorGroupId', 'locatorGroupName', 'selector', 'route', 'moduleId'])) {
+    return {
+      locatorId: data.locatorId,
+      locatorName: data.locatorName,
+      locatorGroupId: data.locatorGroupId,
+      locatorGroupName: data.locatorGroupName,
+      selector: data.selector,
+      route: data.route,
+      moduleId: data.moduleId,
+    }
+  }
+
+  return null
+}