add custom order

Author: thien-remote

next/src/custom/order.ts

@@ -0,0 +1,53 @@
+import type { Field } from '../field/type'
+import type { JsfSchema } from '../types'
+
+function sort(params: {
+  fields: Field[]
+  order: string[]
+}): Field[] {
+  const { fields: prevFields, order } = params
+
+  // Map from field name to expected index
+  const indexMap: Record<string, number | undefined> = {}
+  order.forEach((key, index) => {
+    indexMap[key] = index
+  })
+
+  const nextFields = prevFields.sort((a, b) => {
+    // Compare by index
+    const indexA = indexMap[a.name] ?? Infinity
+    const indexB = indexMap[b.name] ?? Infinity
+
+    // The else actually only happens when both are Infinity,
+    // i.e., not specified in the order array
+    if (indexA !== indexB)
+      return indexA - indexB
+
+    // If not specified, maintain original relative order
+    return prevFields.indexOf(a) - prevFields.indexOf(b)
+  })
+
+  return nextFields
+}
+
+/**
+ * Sort fields by schema's `x-jsf-order`
+ */
+export function setCustomOrder(params: {
+  schema: JsfSchema
+  fields: Field[]
+}): Field[] {
+  const { schema, fields } = params
+
+  // TypeScript does not yield if we remove this check,
+  // but it's only because our typing is likely not right.
+  // See internal discussion:
+  // - https://remote-com.slack.com/archives/C02HTN0LY02/p1738745237733389?thread_ts=1738741631.346809&cid=C02HTN0LY02
+  if (typeof schema === 'boolean')
+    throw new Error('Schema must be an object')
+
+  if (schema['x-jsf-order'] !== undefined)
+    return sort({ fields, order: schema['x-jsf-order'] })
+
+  return fields
+}

next/test/custom/order.test.ts

@@ -0,0 +1,74 @@
+import type { JsfSchema } from '../../src/types'
+import { describe, expect, it } from '@jest/globals'
+import { createHeadlessForm } from '../../src'
+
+describe('custom order', () => {
+  it('should sort fields by x-jsf-order', () => {
+    const schema: JsfSchema = {
+      'type': 'object',
+      'properties': {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+      'x-jsf-order': ['age', 'name'],
+    }
+    const form = createHeadlessForm(schema)
+
+    const keys = form.fields.map(field => field.name)
+    expect(keys).toEqual(['age', 'name'])
+  })
+
+  it('should sort nested objects', () => {
+    const addressSchema: JsfSchema = {
+      'type': 'object',
+      'properties': {
+        state: { type: 'string' },
+        city: { type: 'string' },
+        street: { type: 'string' },
+      },
+      'x-jsf-order': ['street', 'city', 'state'],
+    }
+
+    const mainSchema: JsfSchema = {
+      'type': 'object',
+      'properties': {
+        address: addressSchema,
+        name: { type: 'string' },
+      },
+      'x-jsf-order': ['name', 'address'],
+    }
+
+    const form = createHeadlessForm(mainSchema)
+
+    const mainKeys = form.fields.map(field => field.name)
+    expect(mainKeys).toEqual(['name', 'address'])
+
+    const addressField = form.fields.find(field => field.name === 'address')
+    if (addressField === undefined)
+      throw new Error('Address field not found')
+
+    // This already throws if "fields" is undefined
+    const addressKeys = addressField.fields?.map(field => field.name)
+    expect(addressKeys).toEqual(['street', 'city', 'state'])
+  })
+
+  it('should respect initial, unspecified order', () => {
+    const schema: JsfSchema = {
+      'type': 'object',
+      'properties': {
+        one: { type: 'string' },
+        two: { type: 'string' },
+        three: { type: 'string' },
+      },
+      'x-jsf-order': ['three'],
+    }
+
+    const form = createHeadlessForm(schema)
+    const keys = form.fields.map(field => field.name)
+
+    // "one" and "two" are not specified,
+    // so they are added to the end,
+    // respecting their relative initial order
+    expect(keys).toEqual(['three', 'one', 'two'])
+  })
+})