Merge pull request #19 from entur/feat/corrected-xmlshape

Replace serializeValue with schema-aware toXmlShape

Author: dynnamitt

packages/my_vehicletype-editor/WIRE_IN_TYPE_HELPERS.md

@@ -0,0 +1,87 @@
+# Wire in `type_helpers.ts` for XML serialization
+
+## Context
+
+`serialize.ts` currently uses a convention-only `serializeValue()` that walks objects
+recursively, renames `$`-prefixed keys to `@_` attributes, and stringifies booleans.
+It has **no schema awareness** — it misses:
+
+- simpleContent `value` → `#text` (e.g. `TextType { value, $lang }` stays as `{ value, @_lang }` instead of `{ '#text', @_lang }`)
+- Ref-structure attrs (e.g. `DeckPlanRef { value, $ref, $version }` — nested `$ref` doesn't get `@_` rename because `serializeValue` doesn't recurse into string-valued refs)
+
+`generated/type_helpers.ts` has a schema-aware `toXmlShape()` that handles all of
+this correctly. It was generated from the NeTEx JSON Schema by
+`netex-typescript-model/typescript/scripts/generate-hathor-helpers.ts` using
+`makeInlinedToXmlShape()`.
+
+## What to do
+
+### 1. Replace `serializeValue` with `toXmlShape` in `serialize.ts`
+
+```ts
+import { XMLBuilder } from 'fast-xml-parser';
+import { toXmlShape } from './generated/type_helpers.js';
+import type { VehicleType } from './generated/types.js';
+
+const builder = new XMLBuilder({
+  format: true,
+  indentBy: '  ',
+  ignoreAttributes: false,
+});
+
+export function serialize(obj: Partial<VehicleType>): string {
+  const xmlObj = toXmlShape(obj as Record<string, any>);
+  return builder.build({ VehicleType: xmlObj }) as string;
+}
+```
+
+Delete `serializeValue()` — it is fully replaced.
+
+### 2. Update serialize tests
+
+The existing tests in `__tests__/serialize.test.ts` pass partial VehicleType
+objects directly. Most will keep working since `toXmlShape` uses a base loop
+that copies unknown properties as-is. But check:
+
+- **Ref tests** (`DeckPlanRef`, `IncludedIn`, `ClassifiedAsRef`, `BrandingRef`) —
+  if these are currently passed as bare strings (`{ DeckPlanRef: 'test' }`),
+  `toXmlShape` will copy them through unchanged (same behavior). But if the
+  editor starts passing ref _objects_ (`{ value: 'x', $ref: 'x' }`), the
+  dispatch `default` branch won't transform nested attrs. See TODOs in
+  `type_helpers.ts` for adding ref-type functions.
+
+- **Name / ShortName / Description** — tests pass `{ Value: 'a' }` (capital V).
+  The stem shape from `normalize` uses `value` (lowercase). Verify which casing
+  the editor actually produces and align the tests.
+
+- **Roundtrip test** — the `normalize → serialize → parse → normalize` roundtrip
+  should still pass since `toXmlShape` handles the same primitives. Run it to
+  confirm.
+
+### 3. Re-export (optional)
+
+If consumers outside the editor package need `toXmlShape` directly, add to
+`index.ts`:
+
+```ts
+export { toXmlShape } from './generated/type_helpers.js';
+```
+
+## Known gaps (see TODOs in `type_helpers.ts`)
+
+| Gap | Impact | Fix |
+|-----|--------|-----|
+| Ref types (`BrandingRef`, `DeckPlanRef`, `ValidBetween`, `VehicleTypeRefStructure`, `VehicleModelRefStructure`) hit dispatch `default` pass-through | Nested `$ref`/`$version` attrs won't get `@_` rename | Add these to `TYPES[]` in the generator and add dispatch cases |
+| `VehicleManoeuvringRequirements` is hand-written | Works, but won't track schema changes | Replace when/if type lands in NeTEx XSD |
+| Only VehicleType tree is covered | Vehicle / DeckPlan exports won't use schema-aware transform | Add their types when Hathor needs them |
+
+## How to regenerate
+
+From `netex-typescript-model/`:
+
+```bash
+cd typescript
+npx tsx scripts/generate-hathor-helpers.ts
+```
+
+Requires `generated-src/base/base.schema.json` (run `make all` first if missing).

packages/my_vehicletype-editor/src/SimpleEditor.tsx

@@ -32,14 +32,28 @@ export interface SimpleEditorProps {
 
 const EURO_CLASSES = ['', 'Euro5', 'Euro6'] as const;
 
-// TextType[] flattening helpers
+// Inline helpers that convert between display strings and the VehicleType
+// structure on every keystroke. There is no separate "simple" data shape —
+// the state is always Partial<VehicleType>. These just bridge the gap
+// between a single text field and the underlying NeTEx type:
+//   textVal / textSet  — TextType[]  ↔ single string (first item, lang=nb)
+//   numVal / parseNum  — number      ↔ input string
 const textVal = (arr?: TextType[]) => arr?.[0]?.Value ?? '';
 const textSet = (text: string): TextType[] | undefined =>
   text ? [{ Value: text, $lang: 'nb' }] : undefined;
 
 const numVal = (n: number | undefined) => (n != null ? String(n) : '');
 const parseNum = (s: string) => (s === '' ? undefined : Number(s));
 
+/**
+ * Friendly form editor over {@link VehicleType}.
+ *
+ * Reads from and writes directly to `Partial<VehicleType>` — there is no
+ * intermediate "simplified" shape. Each onChange handler converts its input
+ * value into the full NeTEx structure inline (e.g. a Name text field calls
+ * `textSet` which rebuilds `TextType[]`). The complex type flows out on
+ * every keystroke, so no `simplifiedToStem` transform is needed downstream.
+ */
 export function SimpleEditor({ value, onChange }: SimpleEditorProps): React.JSX.Element {
   const { containerRef, topFraction, isResizing, onMouseDown } = useResizablePane(0.65);
   const [bottomTab, setBottomTab] = useState(0);

packages/my_vehicletype-editor/src/generated/type_helpers.ts

@@ -0,0 +1,175 @@
+/**
+ * Stem-object → XMLBuilder-shape converters for VehicleType and its children.
+ *
+ * **Generated by** `netex-typescript-model/typescript/scripts/generate-hathor-helpers.ts`
+ * from `makeInlinedToXmlShape()` in `to-xml-shape.ts`, driven by the base JSON Schema
+ * (`generated-src/base/base.schema.json`). Re-run the generator to pick up schema changes.
+ *
+ * **Architecture:** `base()` / `baseSimple()` handle the generic transform (attr rename
+ * `$`→`@_`, bool stringify, simpleContent `value`→`#text`). Per-entity functions add
+ * override lines only for complex children that need recursive `toXmlShape` delegation.
+ * `toXmlShapeDispatch` routes child names to the correct function.
+ *
+ * **Entry point:** `toXmlShape(obj)` — takes a VehicleType stem object, returns the
+ * shape expected by fast-xml-parser `XMLBuilder`.
+ */
+// Auto-generated by generate-hathor-helpers.ts — do not edit
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+type XmlShape = Record<string, any>;
+type ToXmlShapeFn = (name: string, obj: any) => any;
+
+function base(obj: Record<string, any>): XmlShape {
+  const out: XmlShape = {};
+  for (const k of Object.keys(obj)) {
+    const v = obj[k];
+    if (v === undefined) continue;
+    if (k[0] === '$') out['@_' + k.slice(1)] = typeof v === 'boolean' ? String(v) : v;
+    else out[k] = typeof v === 'boolean' ? String(v) : v;
+  }
+  return out;
+}
+
+function baseSimple(obj: Record<string, any>): XmlShape {
+  const out: XmlShape = {};
+  for (const k of Object.keys(obj)) {
+    const v = obj[k];
+    if (v === undefined) continue;
+    if (k[0] === '$') out['@_' + k.slice(1)] = typeof v === 'boolean' ? String(v) : v;
+    else if (k === 'value') out['#text'] = v;
+    else out[k] = typeof v === 'boolean' ? String(v) : v;
+  }
+  return out;
+}
+
+export function textTypeToXmlShape(obj: Record<string, any>): XmlShape {
+  const out = baseSimple(obj);
+  return out;
+}
+
+export function privateCodeStructureToXmlShape(obj: Record<string, any>): XmlShape {
+  const out = baseSimple(obj);
+  return out;
+}
+
+export function keyValueStructureToXmlShape(obj: Record<string, any>): XmlShape {
+  const out = baseSimple(obj);
+  return out;
+}
+
+export function passengerCapacityStructureToXmlShape(
+  obj: Record<string, any>,
+  toXmlShape: ToXmlShapeFn
+): XmlShape {
+  const out = base(obj);
+  if (obj['ValidBetween'] !== undefined)
+    out['ValidBetween'] = obj['ValidBetween'].map(function (item: any) {
+      return toXmlShape('ValidBetween', item);
+    });
+  if (obj['keyList'] !== undefined) out['keyList'] = toXmlShape('keyList', obj['keyList']);
+  if (obj['privateCodes'] !== undefined)
+    out['privateCodes'] = toXmlShape('privateCodes', obj['privateCodes']);
+  if (obj['BrandingRef'] !== undefined)
+    out['BrandingRef'] = toXmlShape('BrandingRef', obj['BrandingRef']);
+  return out;
+}
+
+export function keyListToXmlShape(obj: Record<string, any>, toXmlShape: ToXmlShapeFn): XmlShape {
+  const out = base(obj);
+  if (obj['KeyValue'] !== undefined)
+    out['KeyValue'] = obj['KeyValue'].map(function (item: any) {
+      return toXmlShape('KeyValueStructure', item);
+    });
+  return out;
+}
+
+export function privateCodesToXmlShape(
+  obj: Record<string, any>,
+  toXmlShape: ToXmlShapeFn
+): XmlShape {
+  const out = base(obj);
+  if (obj['PrivateCode'] !== undefined)
+    out['PrivateCode'] = obj['PrivateCode'].map(function (item: any) {
+      return toXmlShape('PrivateCode', item);
+    });
+  return out;
+}
+
+export function vehicleTypeToXmlShape(
+  obj: Record<string, any>,
+  toXmlShape: ToXmlShapeFn
+): XmlShape {
+  const out = base(obj);
+  if (obj['ValidBetween'] !== undefined)
+    out['ValidBetween'] = obj['ValidBetween'].map(function (item: any) {
+      return toXmlShape('ValidBetween', item);
+    });
+  if (obj['keyList'] !== undefined) out['keyList'] = toXmlShape('keyList', obj['keyList']);
+  if (obj['privateCodes'] !== undefined)
+    out['privateCodes'] = toXmlShape('privateCodes', obj['privateCodes']);
+  if (obj['BrandingRef'] !== undefined)
+    out['BrandingRef'] = toXmlShape('BrandingRef', obj['BrandingRef']);
+  if (obj['Name'] !== undefined)
+    out['Name'] = obj['Name'].map(function (item: any) {
+      return toXmlShape('TextType', item);
+    });
+  if (obj['ShortName'] !== undefined)
+    out['ShortName'] = obj['ShortName'].map(function (item: any) {
+      return toXmlShape('TextType', item);
+    });
+  if (obj['Description'] !== undefined)
+    out['Description'] = obj['Description'].map(function (item: any) {
+      return toXmlShape('TextType', item);
+    });
+  if (obj['PrivateCode'] !== undefined)
+    out['PrivateCode'] = toXmlShape('PrivateCode', obj['PrivateCode']);
+  if (obj['PassengerCapacity'] !== undefined)
+    out['PassengerCapacity'] = toXmlShape('PassengerCapacityStructure', obj['PassengerCapacity']);
+  if (obj['DeckPlanRef'] !== undefined)
+    out['DeckPlanRef'] = toXmlShape('DeckPlanRef', obj['DeckPlanRef']);
+  if (obj['IncludedIn'] !== undefined)
+    out['IncludedIn'] = toXmlShape('VehicleTypeRefStructure', obj['IncludedIn']);
+  if (obj['ClassifiedAsRef'] !== undefined)
+    out['ClassifiedAsRef'] = toXmlShape('VehicleModelRefStructure', obj['ClassifiedAsRef']);
+  return out;
+}
+
+// --- hand-written (not in schema) ---
+// TODO: VehicleManoeuvringRequirements is not in the NeTEx XSD. If it gets added
+//       upstream, replace this stub with a generated function in TYPES[].
+export function vehicleManoeuvringRequirementsToXmlShape(obj: Record<string, any>): XmlShape {
+  return base(obj);
+}
+
+// TODO: Dispatch only covers types reachable from VehicleType. To support
+//       Vehicle / DeckPlan XML export, add their leaf types to TYPES[] in the
+//       generator and add cases here.
+// TODO: BrandingRef, DeckPlanRef, ValidBetween, VehicleTypeRefStructure, and
+//       VehicleModelRefStructure hit the `default` pass-through — their nested
+//       attrs ($ref, $version) won't get the @_ rename. Generate functions for
+//       these ref types once Hathor needs valid XML for them.
+function toXmlShapeDispatch(name: string, obj: any): any {
+  if (obj === undefined || obj === null) return obj;
+  if (typeof obj !== 'object') return obj;
+  const rec = obj as Record<string, any>;
+  switch (name) {
+    case 'TextType':
+      return textTypeToXmlShape(rec);
+    case 'PrivateCode':
+      return privateCodeStructureToXmlShape(rec);
+    case 'KeyValueStructure':
+      return keyValueStructureToXmlShape(rec);
+    case 'PassengerCapacityStructure':
+      return passengerCapacityStructureToXmlShape(rec, toXmlShapeDispatch);
+    case 'keyList':
+      return keyListToXmlShape(rec, toXmlShapeDispatch);
+    case 'privateCodes':
+      return privateCodesToXmlShape(rec, toXmlShapeDispatch);
+    default:
+      return rec;
+  }
+}
+
+export function toXmlShape(obj: Record<string, any>): XmlShape {
+  return vehicleTypeToXmlShape(obj, toXmlShapeDispatch);
+}

packages/my_vehicletype-editor/src/index.ts

@@ -32,3 +32,4 @@ export { validate } from './generated/validate.js';
 export type { ValidationResult } from './generated/validate.js';
 export { normalize } from './normalize.js';
 export { serialize } from './serialize.js';
+export { toXmlShape } from './generated/type_helpers.js';

packages/my_vehicletype-editor/src/serialize.ts

@@ -1,4 +1,5 @@
 import { XMLBuilder } from 'fast-xml-parser';
+import { toXmlShape } from './generated/type_helpers.js';
 import type { VehicleType } from './generated/types.js';
 
 const builder = new XMLBuilder({
@@ -7,30 +8,8 @@ const builder = new XMLBuilder({
   ignoreAttributes: false,
 });
 
-function serializeValue(obj: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [key, val] of Object.entries(obj)) {
-    if (val === undefined) continue;
-    if (key.startsWith('$')) {
-      out[`@_${key.slice(1)}`] = typeof val === 'boolean' ? String(val) : val;
-    } else if (Array.isArray(val)) {
-      out[key] = val.map(item =>
-        typeof item === 'object' && item !== null
-          ? serializeValue(item as Record<string, unknown>)
-          : item
-      );
-    } else if (typeof val === 'object' && val !== null) {
-      out[key] = serializeValue(val as Record<string, unknown>);
-    } else if (typeof val === 'boolean') {
-      out[key] = String(val);
-    } else {
-      out[key] = val;
-    }
-  }
-  return out;
-}
-
 export function serialize(obj: Partial<VehicleType>): string {
-  const xmlObj = serializeValue(obj as Record<string, unknown>);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const xmlObj = toXmlShape(obj as Record<string, any>);
   return builder.build({ VehicleType: xmlObj }) as string;
 }