Enable user data pre-population in NAME and TEXT fields via user() function

[Copilot]

NAME fields couldn't resolve user template variables, causing errors when attempting to pre-populate informant names with logged-in user data. TEXT fields also lacked access to user fields like fullHonorificName and device.

Changes

Type system updates

• User type: Added device field to support device information pre-population
• SystemVariables: Changed $user from ad-hoc structure to proper User type

New user() function

Created type-safe accessor for user fields, replacing deprecated $user.* string templates:

// New syntax (type-safe)
{
  id: 'informant.name',
  type: FieldType.NAME,
  defaultValue: user('name')  // Converts User.name to NameFieldValue
}

{
  id: 'registrar.title',
  type: FieldType.TEXT,
  defaultValue: user('fullHonorificName')
}

Supports: name, fullHonorificName, device, province, district

Template resolution

• replacePlaceholders: Added conversion from User.name format ({use, given: [], family}) to NameFieldValue ({firstname, surname, middlename}) for NAME fields
• Deprecation warning: Emits console warning when legacy $user.* syntax is detected

Hook updates

• useUserDetails: Returns complete User structure matching SystemVariables['$user'] type instead of partial fields

Example

Previously failed with "Could not resolve NAME":

defaultValue: { firstname: '$user.name', surname: '$user.name' }  // ❌

Now works:

defaultValue: user('name')  // ✅ Resolves to { firstname: 'John', surname: 'Doe', middlename: 'Michael' }

Original prompt

---

This section details on the original issue you should resolve

<issue_title>It isnt possible to pre-populate user's name into informant name field</issue_title>
<issue_description>In Uganda, it is a requirement to pre-populate the logged in user's name into the informant's name field.

You can do this in a FieldType.TEXT component:

{ 
id: 'review.registrarName',
 type: FieldType.TEXT,
 required: false,
 defaultValue: '$user.name',
}

But you cannot do this in a FieldType.NAME component:

id: 'informant.name',
type: FieldType.NAME,
defaultValue: {
   firstname: '$user.name',
   surname: '$user.name',
   middlename: '$user.name'
},

Tech design

It needs to be possible to use user serialiser as part of a name field default value

type: FieldType.NAME,
defaultValue:  user('name'),

This should internally translate to a {firstname: <user's firstname>, surname: '<user's surname>'} so a name field compatible value. The correct place to do this is inside handleDefaultValue.
Also make it so SystemVariables.$user is not a new arbitrary user type but instead is of type User from packages/commons/src/users/User.ts.

User's name is represented as:

name: z.array(
  z.object({
    use: z.string(),
    given: z.array(z.string()),
    family: z.string()
  })
),

This value should only be converted to the name input value inside handleDefaultValue and should always be kept as the original structure for as long as possible.

[!NOTE]
Old string template variables are to be deprecated in favour of user('name') style references. No new design should use the $user.name syntax

Tech tasks

• Ensure assigning user('name') to NAME field value prefils the input properly
• Ensure user('fullHonorificName') and user('device') can both be used as a default value for TEXT type field
• Add a deprecation warning for string typed template variables here
  </issue_description>

Comments on the Issue (you are @copilot in this section)

@prinzab @euanmillar Note that this behaviour isn't always required. It is only needed when it's HFA / Field Agent type. @SyedaAfrida @rikukissa @Alta-Nel @jpye-finch needs to come up with proper design before we assign any milestone @rikukissa @SyedaAfrida tech design is now done for this item @euanmillar @rikukissa Uganda also use cases to pre-pop with more user information. Ideally Uganda would configure the information they need for the user in this form but it isnt configurable so I am trying to make do with what we have. Maybe they could re-purpose the "Full Honorific Name" and potentially also the "Device" field available in the user form. Is there any way the tech design can include all the fields in the create user form? We could then play with labels to hack a solution that satisfies them to some degree. @rikukissa @euanmillar Sure, it seems both `fullHonorificName` and `device` are just plain text fields that are easy to be made available. Some fields like `name` are a bit more complex and need conversion a supported input field type like `NameFieldValue` to function properly.

{
  "id": "6509920c42f19d1950648ea8",
  "name": [
    {
      "use": "en",
      "given": [
        "Kennedy"
      ],
      "family": "Mweene"
    }
  ],
  "role": "LOCAL_REGISTRAR",
  "avatar": "/ocrvs/754f89eb-69eb-4845-b17f-f5d6fb294e8e.jpg",
  "signature": "/ocrvs/0840890e-1ed8-4465-ba1a-2d8031960bc0.png",
  "primaryOfficeId": "5ae4e8fe-e15d-4345-bbea-dbd81fddbb9b",
  "fullHonorificName": "Doctor Kennedy Mweene the 2nd",
  "type": "user"
}

I'm also noticing here that device field needs to be exposed. Repurposing it for some other use case should be perfectly fine, same with fullHonorificName if it's not used in the certificate. I'll update the design.

For 2.x we should consider adding a customisable section of additional fields to the user form as it seems to be a common request.</comment_new>
<comment_new>@euanmillar
Thanks Riku. That would be wonderful. Some of those fields may exist in the main declaration form so if the same ids can be used it is clearer what can pre-pop. For example, if the user was based in a health institution, the place of birth location could be pre-populated. That is anoth...

• Fixes It isnt possible to pre-populate user's name into informant name field #11266

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[rikukissa]

This function already exists with name userSerializer
packages/commons/src/events/serializers/user/serializer.ts

Use it instead. "$user.name" style references are also deprecated.

@copilot

[rikukissa]

Ensure return value is of type User from

packages/commons/src/users/User.ts:45

@copilot

[github-actions]

This PR has been marked with label stale Since it has been inactive for 20 days. It will automatically be closed in 10 days if no further activity occurs.