swoop-common 2.2.83 → 2.2.85

package/README.md

@@ -1,225 +1,225 @@
-.# Swoop Library
-
-This library is used for rendering **Swoop itinerary templates**.
-It provides tools for defining **custom field types**, registering **custom components**,
-rendering templates from a **MasterSchema**, and includes SDKs for all related services.
-It supports both input mode (for creating templates) and presentation mode (for rendering them for end users).
-The schema system is stage-aware, enabling precise control over what data is editable or displayed at which stage.
-
-> Note: This package is intended for internal use only.
-
----
-
-# Swoop Library
-
-## Initialization
-
-Before using the Swoop Library, you must initialize it with service URLs:
-
-```ts
-import { init } from "swoop-common";
-
-init({
-  coreServiceUrl: "https://your.core.service",
-  swoopServiceForwardUrl: "https://your.forward.service",
-});
-```
-
-## Service Interfaces
-
-The library provides three primary service interfaces to interact with backend systems:
-
-- **SwoopService** — Interfaces with the Swoop API.
-- **CoreService** — For core service.
-
-These interfaces offer convenient methods to work seamlessly with the underlying services required by the itinerary system.
-
-## StyledFormView
-
-The `StyledFormView` component is the entry point for rendering a full itinerary template. It handles schema parsing and renderer injection based on mode and form stage.
-
-```tsx
-import { StyledFormView } from "your-form-library";
-
-<StyledFormView
-  initialData={/* object */}
-  schema={/* MasterSchema */}
-  onChange={(val) => console.log(val)}
-  pool="FORM"
-  readonly={false}
-  stage="Inst"
-/>;
-```
-
-### Props
-
-| Name        | Type                 | Description                                                        |
-| ----------- | -------------------- | ------------------------------------------------------------------ |
-| initialData | `any`                | Initial values for the template. Should not be updated frequently. |
-| schema      | `MasterSchema`       | Template definition object.                                        |
-| onChange    | `(val: any) => void` | Callback with updated data.                                        |
-| pool        | `ComponentPool`      | `"FORM"` or `"PRESENTATION"` depending on context.                 |
-| readonly    | `boolean`            | Disables inputs if true (only relevant in FORM pool).              |
-| stage       | `Stage`              | Controls which data segment is being rendered.                     |
-
-### Stages
-
-The template system is divided into stages:
-
-- **Stage.Comp** – Data stored on the root component, often static (e.g. metadata, titles). Does not include any dynamic or time-based fields.
-- **Stage.Inst** – Instance-specific data (e.g. timings, localized notes). This is the most common stage for editable fields.
-- **Stage.User** – Data unique to individual users (e.g. room number).
-
-Each stage builds on the one before it. For example, `Stage.User` includes everything from `Stage.Comp` and `Stage.Inst`. Fields are editable based on the current stage. If a value is defined in two stages, the lower stage will take priority.
-
----
-
-## Custom Components
-
-Custom components define how individual fields render. These can behave like typical form inputs or be used for display-only formatting in the `PRESENTATION` pool.
-
-### Example
-
-```tsx
-const FormExample: React.FC<Props> = ({
-  text,
-  onChange,
-  getError,
-  label,
-  enabled,
-}) => {
-  const [val, setVal] = useState(text);
-  const error = getError ? getError("example")?.message : undefined;
-  const onChangeDebounced = useMemo(() => debounce(onChange, 300), [onChange]);
-
-  const update = (value: string) => {
-    setVal(value);
-    onChangeDebounced(value);
-  };
-
-  return (
-    <Paper
-      sx={{
-        display: "flex",
-        flexDirection: "column",
-        gap: 1,
-        p: 2,
-        background: "#CBC3E3",
-        mb: 1,
-      }}
-    >
-      {!enabled && "THIS IS DISABLED"}
-      <Typography variant="h6">{label}</Typography>
-      <TextField
-        label="Example label"
-        value={val}
-        onChange={(e) => update(e.target.value)}
-        error={!!error}
-        helperText={error}
-        disabled={!enabled}
-      />
-    </Paper>
-  );
-};
-
-const FormRendererExample: React.FC<ControlProps> = ({
-  data,
-  handleChange,
-  path,
-  label,
-  enabled,
-}) => {
-  const getError = useLocalErrors(path);
-  return (
-    <FormExample
-      text={data as string}
-      onChange={(val) => handleChange(path, val)}
-      getError={getError}
-      label={label}
-      enabled={enabled}
-    />
-  );
-};
-
-registerComponent("example", FormRendererExample, ComponentPool.FORM);
-registerComponent("example", FormRendererExample, ComponentPool.PRESENTATION);
-```
-
-> Important: You **cannot register two components with the same name within the same pool**. You _can_ register the same component name across different pools (e.g., `"example"` in both `"FORM"` and `"PRESENTATION"`).
-
-### Presentation Pool
-
-The `PRESENTATION` pool is more than just read-only. It is designed for **customer-facing output**, rendering fields in a clean, non-form-like layout for readability and professionalism.
-
----
-
-## Custom Types
-
-Custom field types define what kinds of fields can be used when **building a template**. These appear in the template builder UI as selectable field types and control how data is validated and configured.
-
-### Syntax
-
-```ts
-registerType(
-  "typeId", // Unique type string
-  "Display Name", // Name shown in template builder
-  schema, // JSON Schema defining the data structure
-  optionsSchema, // JSON Schema defining configuration data structure
-  requiredOptions // boolean: must the options be filled?
-);
-```
-
-### Example
-
-```ts
-registerType(
-  "enum",
-  "Dropdown",
-  { type: "array" },
-  {
-    type: "object",
-    title: "Dropdown Options",
-    properties: {
-      enumValues: {
-        title: "Dropdown Values",
-        type: "array",
-        items: { type: "string" },
-      },
-    },
-  },
-  true
-);
-```
-
-This type defines a dropdown field where the values are defined via the `enumValues` property in the template configuration.
-
-### Custom Option Editors
-
-If you want to render a **custom options block** (i.e., how the field type's options are displayed in the template editor), you must do the following:
-
-1. In the top-level `optionsSchema` of the type, define `"x-type": "yourTypeName"`
-2. Create and register a custom component with the name `"yourTypeName"` in the `"FORM"` pool.
-
-This component will then be used to render the configuration UI for that field type.
-
----
-
-## File Locations
-
-- **Custom components** must be placed in `src/renderers`. They may be nested within subfolders. All files inside `renderers/` will be automatically imported in the correct order.
-- **Custom types** must be added to `src/default_registration/fields_base.tsx`.
-
-No manual import wiring is required beyond placing the file in the correct folder.
-
----
-
-## Publishing to NPM
-
-To publish a new version of the package:
-
-```bash
-npm run build             # Compile the package
-npm version patch         # Bump the patch version (or use minor/major as needed)
-npm adduser               # Log in to NPM (if not already)
-npm publish               # Publish the package
-```
+.# Swoop Library
+
+This library is used for rendering **Swoop itinerary templates**.
+It provides tools for defining **custom field types**, registering **custom components**,
+rendering templates from a **MasterSchema**, and includes SDKs for all related services.
+It supports both input mode (for creating templates) and presentation mode (for rendering them for end users).
+The schema system is stage-aware, enabling precise control over what data is editable or displayed at which stage.
+
+> Note: This package is intended for internal use only.
+
+---
+
+# Swoop Library
+
+## Initialization
+
+Before using the Swoop Library, you must initialize it with service URLs:
+
+```ts
+import { init } from "swoop-common";
+
+init({
+  coreServiceUrl: "https://your.core.service",
+  swoopServiceForwardUrl: "https://your.forward.service",
+});
+```
+
+## Service Interfaces
+
+The library provides three primary service interfaces to interact with backend systems:
+
+- **SwoopService** — Interfaces with the Swoop API.
+- **CoreService** — For core service.
+
+These interfaces offer convenient methods to work seamlessly with the underlying services required by the itinerary system.
+
+## StyledFormView
+
+The `StyledFormView` component is the entry point for rendering a full itinerary template. It handles schema parsing and renderer injection based on mode and form stage.
+
+```tsx
+import { StyledFormView } from "your-form-library";
+
+<StyledFormView
+  initialData={/* object */}
+  schema={/* MasterSchema */}
+  onChange={(val) => console.log(val)}
+  pool="FORM"
+  readonly={false}
+  stage="Inst"
+/>;
+```
+
+### Props
+
+| Name        | Type                 | Description                                                        |
+| ----------- | -------------------- | ------------------------------------------------------------------ |
+| initialData | `any`                | Initial values for the template. Should not be updated frequently. |
+| schema      | `MasterSchema`       | Template definition object.                                        |
+| onChange    | `(val: any) => void` | Callback with updated data.                                        |
+| pool        | `ComponentPool`      | `"FORM"` or `"PRESENTATION"` depending on context.                 |
+| readonly    | `boolean`            | Disables inputs if true (only relevant in FORM pool).              |
+| stage       | `Stage`              | Controls which data segment is being rendered.                     |
+
+### Stages
+
+The template system is divided into stages:
+
+- **Stage.Comp** – Data stored on the root component, often static (e.g. metadata, titles). Does not include any dynamic or time-based fields.
+- **Stage.Inst** – Instance-specific data (e.g. timings, localized notes). This is the most common stage for editable fields.
+- **Stage.User** – Data unique to individual users (e.g. room number).
+
+Each stage builds on the one before it. For example, `Stage.User` includes everything from `Stage.Comp` and `Stage.Inst`. Fields are editable based on the current stage. If a value is defined in two stages, the lower stage will take priority.
+
+---
+
+## Custom Components
+
+Custom components define how individual fields render. These can behave like typical form inputs or be used for display-only formatting in the `PRESENTATION` pool.
+
+### Example
+
+```tsx
+const FormExample: React.FC<Props> = ({
+  text,
+  onChange,
+  getError,
+  label,
+  enabled,
+}) => {
+  const [val, setVal] = useState(text);
+  const error = getError ? getError("example")?.message : undefined;
+  const onChangeDebounced = useMemo(() => debounce(onChange, 300), [onChange]);
+
+  const update = (value: string) => {
+    setVal(value);
+    onChangeDebounced(value);
+  };
+
+  return (
+    <Paper
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 1,
+        p: 2,
+        background: "#CBC3E3",
+        mb: 1,
+      }}
+    >
+      {!enabled && "THIS IS DISABLED"}
+      <Typography variant="h6">{label}</Typography>
+      <TextField
+        label="Example label"
+        value={val}
+        onChange={(e) => update(e.target.value)}
+        error={!!error}
+        helperText={error}
+        disabled={!enabled}
+      />
+    </Paper>
+  );
+};
+
+const FormRendererExample: React.FC<ControlProps> = ({
+  data,
+  handleChange,
+  path,
+  label,
+  enabled,
+}) => {
+  const getError = useLocalErrors(path);
+  return (
+    <FormExample
+      text={data as string}
+      onChange={(val) => handleChange(path, val)}
+      getError={getError}
+      label={label}
+      enabled={enabled}
+    />
+  );
+};
+
+registerComponent("example", FormRendererExample, ComponentPool.FORM);
+registerComponent("example", FormRendererExample, ComponentPool.PRESENTATION);
+```
+
+> Important: You **cannot register two components with the same name within the same pool**. You _can_ register the same component name across different pools (e.g., `"example"` in both `"FORM"` and `"PRESENTATION"`).
+
+### Presentation Pool
+
+The `PRESENTATION` pool is more than just read-only. It is designed for **customer-facing output**, rendering fields in a clean, non-form-like layout for readability and professionalism.
+
+---
+
+## Custom Types
+
+Custom field types define what kinds of fields can be used when **building a template**. These appear in the template builder UI as selectable field types and control how data is validated and configured.
+
+### Syntax
+
+```ts
+registerType(
+  "typeId", // Unique type string
+  "Display Name", // Name shown in template builder
+  schema, // JSON Schema defining the data structure
+  optionsSchema, // JSON Schema defining configuration data structure
+  requiredOptions // boolean: must the options be filled?
+);
+```
+
+### Example
+
+```ts
+registerType(
+  "enum",
+  "Dropdown",
+  { type: "array" },
+  {
+    type: "object",
+    title: "Dropdown Options",
+    properties: {
+      enumValues: {
+        title: "Dropdown Values",
+        type: "array",
+        items: { type: "string" },
+      },
+    },
+  },
+  true
+);
+```
+
+This type defines a dropdown field where the values are defined via the `enumValues` property in the template configuration.
+
+### Custom Option Editors
+
+If you want to render a **custom options block** (i.e., how the field type's options are displayed in the template editor), you must do the following:
+
+1. In the top-level `optionsSchema` of the type, define `"x-type": "yourTypeName"`
+2. Create and register a custom component with the name `"yourTypeName"` in the `"FORM"` pool.
+
+This component will then be used to render the configuration UI for that field type.
+
+---
+
+## File Locations
+
+- **Custom components** must be placed in `src/renderers`. They may be nested within subfolders. All files inside `renderers/` will be automatically imported in the correct order.
+- **Custom types** must be added to `src/default_registration/fields_base.tsx`.
+
+No manual import wiring is required beyond placing the file in the correct folder.
+
+---
+
+## Publishing to NPM
+
+To publish a new version of the package:
+
+```bash
+npm run build             # Compile the package
+npm version patch         # Bump the patch version (or use minor/major as needed)
+npm adduser               # Log in to NPM (if not already)
+npm publish               # Publish the package
+```

package/dist/rendering/prebuild/generated/import_generated.d.ts

@@ -8,6 +8,7 @@ import "../../renderers/Image/ImagePresentation";
 import "../../renderers/StagedText";
 import "../../renderers/Subset";
 import "../../renderers/TemplatePicker";
+import "../../renderers/testComponent/TestCompForm";
 import "../../renderers/textfield/MultilineForm";
 import "../../renderers/textfield/MultilinePresentation";
 import "../../schema/formBuilders/formBuilderJsonSchema";

package/dist/rendering/prebuild/generated/import_generated.js

@@ -10,6 +10,7 @@ import "../../renderers/Image/ImagePresentation";
 import "../../renderers/StagedText";
 import "../../renderers/Subset";
 import "../../renderers/TemplatePicker";
+import "../../renderers/testComponent/TestCompForm";
 import "../../renderers/textfield/MultilineForm";
 import "../../renderers/textfield/MultilinePresentation";
 // Build template from schema last

package/dist/rendering/renderers/testComponent/TestCompForm.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rendering/renderers/testComponent/TestCompForm.js

@@ -0,0 +1,35 @@
+import React, { useMemo, useState } from "react";
+import { Box, debounce, MenuItem, Select, TextField } from "@mui/material";
+import { useLocalErrors } from "../../hooks/errors";
+import { ComponentPool } from "../../registry/types";
+import { registerComponent } from "../../registry/components";
+const TestCompForm = ({ textValues, onChange, getError, label, enabled, }) => {
+    var _a, _b;
+    const [values, setValues] = useState(textValues);
+    const [key, setKey] = useState(null);
+    const error = getError ? (_a = getError("testComp")) === null || _a === void 0 ? void 0 : _a.message : undefined;
+    const onChangeDebounced = useMemo(() => debounce(onChange, 300), [onChange]);
+    // Update text field value when key selection changes
+    const val = key ? ((_b = values[key]) !== null && _b !== void 0 ? _b : "") : "";
+    const handleSelectChange = (selectedKey) => {
+        setKey(selectedKey);
+    };
+    const update = (value) => {
+        setValues((prev) => {
+            const updated = Object.assign(Object.assign({}, prev), { [key]: value });
+            onChangeDebounced(updated);
+            return updated;
+        });
+    };
+    return (React.createElement(Box, null,
+        React.createElement(Select, { fullWidth: true, value: key, onChange: (e) => handleSelectChange(e.target.value), disabled: !enabled },
+            React.createElement(MenuItem, { value: "option1" }, "Option 1"),
+            React.createElement(MenuItem, { value: "option2" }, "Option 2"),
+            React.createElement(MenuItem, { value: "option3" }, "Option 3")),
+        React.createElement(TextField, { label: label, value: val, onChange: (e) => update(e.target.value), error: !!error, helperText: error, multiline: true, fullWidth: true, sx: { mb: 1 }, disabled: !enabled || !key })));
+};
+const FormRendererExample = ({ data, handleChange, path, label, enabled, }) => {
+    const getError = useLocalErrors(path);
+    return (React.createElement(TestCompForm, { textValues: data, onChange: (addr) => handleChange(path, addr), getError: getError, label: label, enabled: enabled }));
+};
+registerComponent("testComp", FormRendererExample, ComponentPool.FORM);

package/dist/rendering/type_registration/register.js

@@ -37,8 +37,8 @@ registerType("enum", "Dropdown", { type: "string" }, {
             title: "Dropdown Values",
             type: "array",
             items: { type: "string" },
-        }
-    }
+        },
+    },
 }, true);
 registerType("array", "List", { type: "array" }, {
     type: "object",
@@ -62,7 +62,7 @@ registerType("stagedEnum", "Staged Dropdown", {
             title: "Dropdown Values",
             type: "array",
             items: { type: "string" },
-        }
+        },
     },
 }, true);
 registerType("object", "Group", { type: "object" }, {
@@ -106,31 +106,32 @@ registerType("address", "Address", {
     properties: {
         line1: {
             type: "string",
-            title: "Address Line 1"
+            title: "Address Line 1",
         },
         line2: {
             type: "string",
-            title: "Address Line 2"
+            title: "Address Line 2",
         },
         city: {
             type: "string",
-            title: "City"
+            title: "City",
         },
         county: {
             type: "string",
-            title: "County"
+            title: "County",
         },
         postcode: {
             type: "string",
             title: "Postcode",
-            pattern: "^[A-Z]{1,2}[0-9][0-9A-Z]? ?[0-9][A-Z]{2}$"
+            pattern: "^[A-Z]{1,2}[0-9][0-9A-Z]? ?[0-9][A-Z]{2}$",
         },
         number: {
             type: "number",
-            title: "Number"
-        }
+            title: "Number",
+        },
     },
-    required: ["line1", "city", "postcode"]
+    required: ["line1", "city", "postcode"],
 }, {}, false);
 registerType("image", "Image", { type: "string" }, {}, false);
 registerType("multiline", "Multiline", { type: "string" }, {}, false);
+registerType("testComp", "Test Component", { type: "object" }, {}, false);

package/package.json

@@ -1,66 +1,66 @@
-{
-  "name": "swoop-common",
-  "version": "2.2.83",
-  "main": "dist/api/index.js",
-  "types": "dist/api/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/api/index.js",
-      "require": "./dist/api/index.js",
-      "types": "./dist/api/index.d.ts"
-    },
-    "./rendering": {
-      "import": "./dist/rendering/index.js",
-      "require": "./dist/rendering/index.js",
-      "types": "./dist/rendering/index.d.ts"
-    }
-  },
-  "./rendering": {
-    "import": "./dist/rendering/index.js",
-    "require": "./dist/rendering/index.js",
-    "types": "./dist/rendering/index.d.ts"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "rimraf ./dist && tsc",
-    "build-imports": "tsx ./src/rendering/prebuild/import.ts",
-    "generate-swoop-specs": "tsx ./src/api/specsgen.ts",
-    "build-core-sdk": "npx openapi-typescript-codegen --input ./openapi/core_service.yaml --output ./src/api/generated/core --client fetch",
-    "build-swoop-sdk": "npm run generate-swoop-specs && npx openapi-typescript-codegen --input ./openapi/swoop_service.yaml --output ./src/api/generated/swoop --client fetch --postfixModels Swoop --request ./src/api/templates/request.ts",
-    "prebuild": "npm run build-imports && npm run build-sdk",
-    "build-sdk-exports": "tsx ./src/api/gen.ts",
-    "build-sdk": "npm run build-core-sdk && npm run build-swoop-sdk && npm run build-sdk-exports"
-  },
-  "author": "",
-  "license": "ISC",
-  "description": "",
-  "dependencies": {
-    "@apidevtools/swagger-parser": "^12.0.0",
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
-    "@jsonforms/core": "^3.5.1",
-    "@jsonforms/material-renderers": "^3.5.1",
-    "@jsonforms/react": "^3.5.1",
-    "ajv": "^8.17.1",
-    "js-yaml": "^4.1.1",
-    "lodash.merge": "^4.6.2",
-    "openapi-ts": "^0.3.4",
-    "react": "^19.0.0",
-    "rimraf": "^6.0.1",
-    "swoop-common": "^2.1.55"
-  },
-  "devDependencies": {
-    "@apidevtools/swagger-cli": "^4.0.4",
-    "@hey-api/openapi-ts": "^0.80.2",
-    "@types/js-yaml": "^4.0.9",
-    "@types/lodash.merge": "^4.6.9",
-    "@types/node": "^24.0.14",
-    "@types/react": "^19",
-    "openapi-typescript-codegen": "^0.29.0",
-    "tsx": "^4.20.3",
-    "typescript": "^5.8.3"
-  }
-}
+{
+  "name": "swoop-common",
+  "version": "2.2.85",
+  "main": "dist/api/index.js",
+  "types": "dist/api/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/api/index.js",
+      "require": "./dist/api/index.js",
+      "types": "./dist/api/index.d.ts"
+    },
+    "./rendering": {
+      "import": "./dist/rendering/index.js",
+      "require": "./dist/rendering/index.js",
+      "types": "./dist/rendering/index.d.ts"
+    }
+  },
+  "./rendering": {
+    "import": "./dist/rendering/index.js",
+    "require": "./dist/rendering/index.js",
+    "types": "./dist/rendering/index.d.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "rimraf ./dist && tsc",
+    "build-imports": "tsx ./src/rendering/prebuild/import.ts",
+    "generate-swoop-specs": "tsx ./src/api/specsgen.ts",
+    "build-core-sdk": "npx openapi-typescript-codegen --input ./openapi/core_service.yaml --output ./src/api/generated/core --client fetch",
+    "build-swoop-sdk": "npm run generate-swoop-specs && npx openapi-typescript-codegen --input ./openapi/swoop_service.yaml --output ./src/api/generated/swoop --client fetch --postfixModels Swoop --request ./src/api/templates/request.ts",
+    "prebuild": "npm run build-imports && npm run build-sdk",
+    "build-sdk-exports": "tsx ./src/api/gen.ts",
+    "build-sdk": "npm run build-core-sdk && npm run build-swoop-sdk && npm run build-sdk-exports"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.0.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@jsonforms/core": "^3.5.1",
+    "@jsonforms/material-renderers": "^3.5.1",
+    "@jsonforms/react": "^3.5.1",
+    "ajv": "^8.17.1",
+    "js-yaml": "^4.1.1",
+    "lodash.merge": "^4.6.2",
+    "openapi-ts": "^0.3.4",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "swoop-common": "^2.1.55"
+  },
+  "devDependencies": {
+    "@apidevtools/swagger-cli": "^4.0.4",
+    "@hey-api/openapi-ts": "^0.80.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/lodash.merge": "^4.6.9",
+    "@types/node": "^24.0.14",
+    "@types/react": "^19",
+    "openapi-typescript-codegen": "^0.29.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}