zinkee 0.1.7 → 0.1.8

package/src/utils/schema-fields.ts

@@ -10,7 +10,13 @@ export type SchemaFieldTypeKey =
   | "reference"
   | "formula"
   | "member"
-  | "autoincremental";
+  | "autoincremental"
+  | "schedule";
+
+export interface SchemaFieldExamplePayload {
+  name: string;
+  payload: JsonObject;
+}
 
 export interface SchemaFieldTypeDefinition {
   key: SchemaFieldTypeKey;
@@ -18,7 +24,7 @@ export interface SchemaFieldTypeDefinition {
   aliases: readonly string[];
   description: string;
   rawShape: string;
-  examplePayload: JsonObject;
+  examplePayloads: readonly SchemaFieldExamplePayload[];
 }
 
 function isJsonObject(value: unknown): value is JsonObject {
@@ -55,12 +61,37 @@ const fieldTypeDefinitions = [
     aliases: ["text", "TextField"],
     description: "Plain text field.",
     rawShape:
-      '{"type":"text","slug":"name","label":"Name"}',
-    examplePayload: {
-      type: "text",
-      slug: "name",
-      label: "Name",
-    },
+      '{"type":"TextField","slug":"name","label":"Name","config":{"textType":"NORMAL"}}',
+    examplePayloads: [
+      {
+        name: "Text field (normal)",
+        payload: {
+          type: "TextField",
+          slug: "customer-name",
+          label: "Customer Name",
+          required: true,
+          config: {
+            textType: "NORMAL",
+            defaultValue: null,
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Text field (long)",
+        payload: {
+          type: "TextField",
+          slug: "customer-notes",
+          label: "Customer Notes",
+          required: false,
+          config: {
+            textType: "LONG",
+            defaultValue: "Add internal notes here...",
+            conditionalFormatting: [],
+          },
+        },
+      },
+    ],
   },
   {
     key: "number",
@@ -68,23 +99,125 @@ const fieldTypeDefinitions = [
     aliases: ["number", "NumberField"],
     description: "Numeric field.",
     rawShape:
-      '{"type":"number","slug":"price-eur","label":"Price EUR","config":{"defaultValue":"0","formatOptions":{"format":"number","decimals":2,"thousandsSeparator":true,"symbolEnabled":true,"symbolValue":" €","symbolPosition":"right"}}}',
-    examplePayload: {
-      type: "number",
-      slug: "price-eur",
-      label: "Price EUR",
-      config: {
-        defaultValue: "0",
-        formatOptions: {
-          format: "number",
-          decimals: 2,
-          thousandsSeparator: true,
-          symbolEnabled: true,
-          symbolValue: " €",
-          symbolPosition: "right",
+      '{"type":"NumberField","slug":"quantity","label":"Quantity","config":{"defaultValue":"0","formatOptions":{"format":"number","decimals":0,"thousandsSeparator":false}}}',
+    examplePayloads: [
+      {
+        name: "Number field (plain integer)",
+        payload: {
+          type: "NumberField",
+          slug: "quantity",
+          label: "Quantity",
+          required: false,
+          config: {
+            defaultValue: "0",
+            formatOptions: {
+              format: "number",
+              decimals: 0,
+              thousandsSeparator: false,
+            },
+            conditionalFormatting: [],
+          },
         },
       },
-    },
+      {
+        name: "Number field (decimal with thousands)",
+        payload: {
+          type: "NumberField",
+          slug: "weight",
+          label: "Weight (kg)",
+          required: false,
+          config: {
+            defaultValue: "0",
+            formatOptions: {
+              format: "number",
+              decimals: 2,
+              thousandsSeparator: true,
+              negativesInRed: false,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Number field (currency € prefix)",
+        payload: {
+          type: "NumberField",
+          slug: "amount-eur",
+          label: "Amount (EUR)",
+          required: false,
+          config: {
+            defaultValue: "0",
+            formatOptions: {
+              format: "currency",
+              decimals: 2,
+              negativesInRed: true,
+              thousandsSeparator: true,
+              symbolEnabled: true,
+              symbolPosition: "before",
+              symbolValue: "€",
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Number field (currency $ suffix)",
+        payload: {
+          type: "NumberField",
+          slug: "amount-usd",
+          label: "Amount (USD)",
+          required: false,
+          config: {
+            defaultValue: "0",
+            formatOptions: {
+              format: "currency",
+              decimals: 2,
+              negativesInRed: false,
+              thousandsSeparator: true,
+              symbolEnabled: true,
+              symbolPosition: "right",
+              symbolValue: " $",
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Number field (percentage)",
+        payload: {
+          type: "NumberField",
+          slug: "discount-rate",
+          label: "Discount Rate",
+          required: false,
+          config: {
+            defaultValue: "0",
+            formatOptions: {
+              format: "percentage",
+              decimals: 1,
+              negativesInRed: true,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Number field (duration HH:MM)",
+        payload: {
+          type: "NumberField",
+          slug: "tracked-time",
+          label: "Tracked Time",
+          required: false,
+          config: {
+            defaultValue: "0",
+            formatOptions: {
+              format: "duration",
+              durationFormat: "HH:MM",
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+    ],
   },
   {
     key: "date",
@@ -92,12 +225,63 @@ const fieldTypeDefinitions = [
     aliases: ["date", "DateField"],
     description: "Date or datetime field.",
     rawShape:
-      '{"type":"date","slug":"due-date","label":"Due date"}',
-    examplePayload: {
-      type: "date",
-      slug: "due-date",
-      label: "Due date",
-    },
+      '{"type":"DateField","slug":"due-date","label":"Due Date","config":{"formatOptions":{"format":"date","dateFormat":"YYYY-MM-DD","showTime":false}}}',
+    examplePayloads: [
+      {
+        name: "Date field (date only)",
+        payload: {
+          type: "DateField",
+          slug: "birth-date",
+          label: "Birth Date",
+          required: false,
+          config: {
+            defaultValue: null,
+            formatOptions: {
+              format: "date",
+              dateFormat: "YYYY-MM-DD",
+              showTime: false,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Date field (datetime EU)",
+        payload: {
+          type: "DateField",
+          slug: "due-date",
+          label: "Due Date",
+          required: false,
+          config: {
+            defaultValue: null,
+            formatOptions: {
+              format: "datetime",
+              dateFormat: "DD/MM/YYYY",
+              showTime: true,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Date field (datetime US)",
+        payload: {
+          type: "DateField",
+          slug: "appointment-at",
+          label: "Appointment",
+          required: false,
+          config: {
+            defaultValue: null,
+            formatOptions: {
+              format: "datetime",
+              dateFormat: "MM/DD/YYYY",
+              showTime: true,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+    ],
   },
   {
     key: "option",
@@ -105,26 +289,85 @@ const fieldTypeDefinitions = [
     aliases: ["option", "OptionField"],
     description: "Dropdown/select field with options.",
     rawShape:
-      '{"type":"option","slug":"status","label":"Status","config":{"options":[{"id":1,"name":"Open","color":"default"},{"id":2,"name":"Closed","color":"success"}]}}',
-    examplePayload: {
-      type: "option",
-      slug: "status",
-      label: "Status",
-      config: {
-        options: [
-          {
-            id: 1,
-            name: "Open",
-            color: "default",
+      '{"type":"OptionField","slug":"status","label":"Status","config":{"options":[{"id":1,"name":"Open","color":"default"},{"id":2,"name":"Closed","color":"success"}]}}',
+    examplePayloads: [
+      {
+        name: "Option field (select dropdown)",
+        payload: {
+          type: "OptionField",
+          slug: "priority",
+          label: "Priority",
+          required: false,
+          config: {
+            options: [
+              { id: 1, name: "Low", color: "default" },
+              { id: 2, name: "Medium", color: "warning" },
+              { id: 3, name: "High", color: "danger" },
+            ],
+            defaultValue: 1,
+            conditionalFormatting: [],
+            buttonConfig: null,
           },
-          {
-            id: 2,
-            name: "Closed",
-            color: "success",
+        },
+      },
+      {
+        name: "Option field (button cycle)",
+        payload: {
+          type: "OptionField",
+          slug: "stage",
+          label: "Stage",
+          required: false,
+          config: {
+            options: [
+              { id: 1, name: "To Do", color: "default" },
+              { id: 2, name: "Doing", color: "warning" },
+              { id: 3, name: "Done", color: "success" },
+            ],
+            defaultValue: 1,
+            conditionalFormatting: [],
+            buttonConfig: {
+              displayMode: "button",
+              buttonBehavior: {
+                mode: "cycle",
+                cycleOrder: [1, 2, 3],
+                requireConfirmation: false,
+                lockAfterSelection: false,
+                allowReselect: true,
+              },
+            },
           },
-        ],
+        },
       },
-    },
+      {
+        name: "Option field (button dropdown w/ confirm)",
+        payload: {
+          type: "OptionField",
+          slug: "status",
+          label: "Status",
+          required: false,
+          config: {
+            options: [
+              { id: 1, name: "Open", color: "default" },
+              { id: 2, name: "In Progress", color: "warning" },
+              { id: 3, name: "Done", color: "success" },
+            ],
+            defaultValue: 1,
+            conditionalFormatting: [],
+            buttonConfig: {
+              displayMode: "button",
+              buttonBehavior: {
+                mode: "dropdown",
+                requireConfirmation: true,
+                confirmationMessage: "Confirm status change",
+                useFixedLabel: true,
+                buttonLabel: "Set status",
+                allowReselect: true,
+              },
+            },
+          },
+        },
+      },
+    ],
   },
   {
     key: "file",
@@ -132,12 +375,19 @@ const fieldTypeDefinitions = [
     aliases: ["file", "FileField"],
     description: "File attachment field.",
     rawShape:
-      '{"type":"file","slug":"attachment","label":"Attachment"}',
-    examplePayload: {
-      type: "file",
-      slug: "attachment",
-      label: "Attachment",
-    },
+      '{"type":"FileField","slug":"attachment","label":"Attachment","config":{}}',
+    examplePayloads: [
+      {
+        name: "File field",
+        payload: {
+          type: "FileField",
+          slug: "attachment",
+          label: "Attachment",
+          required: false,
+          config: {},
+        },
+      },
+    ],
   },
   {
     key: "reference",
@@ -145,17 +395,54 @@ const fieldTypeDefinitions = [
     aliases: ["reference", "ReferenceField"],
     description: "Reference to another schema.",
     rawShape:
-      '{"type":"reference","slug":"project","label":"Project","config":{"targetSchema":"<schema-uuid>","targetDisplayField":"<field-uuid>","deleteBehavior":"SET_NULL"}}',
-    examplePayload: {
-      type: "reference",
-      slug: "project",
-      label: "Project",
-      config: {
-        targetSchema: "<schema-uuid>",
-        targetDisplayField: "<field-uuid>",
-        deleteBehavior: "SET_NULL",
+      '{"type":"ReferenceField","slug":"company-ref","label":"Company","config":{"targetSchema":"<schema-uuid>","targetDisplayField":"<field-uuid>"}}',
+    examplePayloads: [
+      {
+        name: "Reference field (minimal)",
+        payload: {
+          type: "ReferenceField",
+          slug: "company-ref",
+          label: "Company",
+          required: false,
+          config: {
+            targetSchema: "5223cbc8-8c6c-4694-93bc-dd176364df9b",
+            targetDisplayField: "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          },
+        },
       },
-    },
+      {
+        name: "Reference field (restrict + filter + description)",
+        payload: {
+          type: "ReferenceField",
+          slug: "customer-ref",
+          label: "Customer",
+          required: false,
+          config: {
+            targetSchema: "5223cbc8-8c6c-4694-93bc-dd176364df9b",
+            targetDisplayField: "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+            deleteBehavior: "RESTRICT",
+            defaultValue: "8ad602a1-f6e3-43f6-9ab2-f1c5afc99621::Ref A",
+            filterFields: [
+              {
+                fatherField: "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+                currentField: "45c5da96-0dc2-4cc1-ba61-7660a9c6da32",
+                comparison: "EQUAL",
+                value: null,
+              },
+            ],
+            descriptionFields: [
+              {
+                id: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+                fieldType: "NumberField",
+                options: null,
+                format: "number",
+              },
+            ],
+            conditionalFormatting: [],
+          },
+        },
+      },
+    ],
   },
   {
     key: "formula",
@@ -163,15 +450,79 @@ const fieldTypeDefinitions = [
     aliases: ["formula", "FormulaField"],
     description: "Calculated field from a formula.",
     rawShape:
-      '{"type":"formula","slug":"total","label":"Total","config":{"formulaText":"{price} * {quantity}"}}',
-    examplePayload: {
-      type: "formula",
-      slug: "total",
-      label: "Total",
-      config: {
-        formulaText: "{price} * {quantity}",
+      '{"type":"FormulaField","slug":"formula-summary","label":"Formula Summary","config":{"formulaText":"concat(firstName, \' \', lastName)","uiFormatKind":"none"}}',
+    examplePayloads: [
+      {
+        name: "Formula field (none)",
+        payload: {
+          type: "FormulaField",
+          slug: "formula-summary",
+          label: "Formula Summary",
+          required: false,
+          config: {
+            formulaText: "concat(firstName, ' ', lastName)",
+            uiFormatKind: "none",
+            status: "ACTIVE",
+            conditionalFormatting: [],
+          },
+        },
       },
-    },
+      {
+        name: "Formula field (number)",
+        payload: {
+          type: "FormulaField",
+          slug: "formula-total",
+          label: "Formula Total",
+          required: false,
+          config: {
+            formulaText: "amount * 1.21",
+            uiFormatKind: "number",
+            status: "ACTIVE",
+            numberFormatOptions: {
+              format: "number",
+              decimals: 2,
+              thousandsSeparator: true,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Formula field (date)",
+        payload: {
+          type: "FormulaField",
+          slug: "formula-deadline",
+          label: "Computed Deadline",
+          required: false,
+          config: {
+            formulaText: "addDays(startDate, 7)",
+            uiFormatKind: "date",
+            status: "ACTIVE",
+            dateFormatOptions: {
+              format: "date",
+              dateFormat: "DD/MM/YYYY",
+              showTime: false,
+            },
+            conditionalFormatting: [],
+          },
+        },
+      },
+      {
+        name: "Formula field (member)",
+        payload: {
+          type: "FormulaField",
+          slug: "formula-assignee",
+          label: "Computed Assignee",
+          required: false,
+          config: {
+            formulaText: "manager",
+            uiFormatKind: "member",
+            status: "ACTIVE",
+            conditionalFormatting: [],
+          },
+        },
+      },
+    ],
   },
   {
     key: "member",
@@ -179,15 +530,22 @@ const fieldTypeDefinitions = [
     aliases: ["member", "MemberField"],
     description: "Workspace member field.",
     rawShape:
-      '{"type":"member","slug":"owner","label":"Owner","config":{"defaultValue":"<member-id>"}}',
-    examplePayload: {
-      type: "member",
-      slug: "owner",
-      label: "Owner",
-      config: {
-        defaultValue: "<member-id>",
+      '{"type":"MemberField","slug":"owner","label":"Owner","config":{"defaultValue":null}}',
+    examplePayloads: [
+      {
+        name: "Member field",
+        payload: {
+          type: "MemberField",
+          slug: "owner",
+          label: "Owner",
+          required: false,
+          config: {
+            defaultValue: null,
+            conditionalFormatting: [],
+          },
+        },
       },
-    },
+    ],
   },
   {
     key: "autoincremental",
@@ -200,15 +558,76 @@ const fieldTypeDefinitions = [
     ],
     description: "Auto-generated incremental counter.",
     rawShape:
-      '{"type":"autoincremental","slug":"counter","label":"Counter","config":{"segmentedByFieldId":null}}',
-    examplePayload: {
-      type: "autoincremental",
-      slug: "counter",
-      label: "Counter",
-      config: {
-        segmentedByFieldId: null,
+      '{"type":"AutoIncrementalField","slug":"order-number","label":"Order Number","config":{"segmentedByFieldId":null}}',
+    examplePayloads: [
+      {
+        name: "Autoincremental (global counter)",
+        payload: {
+          type: "AutoIncrementalField",
+          slug: "order-number",
+          label: "Order Number",
+          required: false,
+          config: {
+            segmentedByFieldId: null,
+            conditionalFormatting: [],
+          },
+        },
       },
-    },
+      {
+        name: "Autoincremental (segmented)",
+        payload: {
+          type: "AutoIncrementalField",
+          slug: "sequence-code",
+          label: "Sequence Code",
+          required: false,
+          config: {
+            segmentedByFieldId: "45c5da96-0dc2-4cc1-ba61-7660a9c6da32",
+            conditionalFormatting: [],
+          },
+        },
+      },
+    ],
+  },
+  {
+    key: "schedule",
+    className: "ScheduleField",
+    aliases: ["schedule", "ScheduleField"],
+    description:
+      "Recurrence/schedule field bound to a number reference and a date period (frequency: monthly or daily).",
+    rawShape:
+      '{"type":"ScheduleField","slug":"recurrence","label":"Recurrence","config":{"referenceField":"<number-field-uuid>","beginningPeriodField":"<date-field-uuid>","endingPeriodField":"<date-field-uuid>","frequency":"monthly"}}',
+    examplePayloads: [
+      {
+        name: "Schedule field (monthly)",
+        payload: {
+          type: "ScheduleField",
+          slug: "monthly-recurrence",
+          label: "Monthly Recurrence",
+          required: false,
+          config: {
+            referenceField: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+            beginningPeriodField: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            endingPeriodField: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            frequency: "monthly",
+          },
+        },
+      },
+      {
+        name: "Schedule field (daily)",
+        payload: {
+          type: "ScheduleField",
+          slug: "daily-recurrence",
+          label: "Daily Recurrence",
+          required: false,
+          config: {
+            referenceField: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+            beginningPeriodField: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            endingPeriodField: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            frequency: "daily",
+          },
+        },
+      },
+    ],
   },
 ] as const satisfies readonly SchemaFieldTypeDefinition[];
 
@@ -397,6 +816,70 @@ function normalizeReferencePayload(input: JsonObject): JsonObject {
   return normalized;
 }
 
+const scheduleAllowedFrequencies = new Set(["monthly", "daily"]);
+
+function normalizeSchedulePayload(input: JsonObject): JsonObject {
+  const additionalProperties = toJsonObject(input.additionalProperties) ?? {};
+  const config = toJsonObject(input.config) ?? {};
+  const referenceField =
+    config.referenceField ?? input.referenceField ?? additionalProperties.referenceField;
+  const beginningPeriodField =
+    config.beginningPeriodField ??
+    input.beginningPeriodField ??
+    additionalProperties.beginningPeriodField;
+  const endingPeriodField =
+    config.endingPeriodField ??
+    input.endingPeriodField ??
+    additionalProperties.endingPeriodField;
+  const frequency =
+    config.frequency ?? input.frequency ?? additionalProperties.frequency;
+
+  const {
+    referenceField: _referenceField,
+    beginningPeriodField: _beginningPeriodField,
+    endingPeriodField: _endingPeriodField,
+    frequency: _frequency,
+    additionalProperties: _additionalProperties,
+    ...rest
+  } = input;
+
+  const normalized: JsonObject = {
+    ...rest,
+    config: {
+      ...config,
+      ...(referenceField !== undefined ? { referenceField } : {}),
+      ...(beginningPeriodField !== undefined ? { beginningPeriodField } : {}),
+      ...(endingPeriodField !== undefined ? { endingPeriodField } : {}),
+      ...(frequency !== undefined ? { frequency } : {}),
+    },
+  };
+
+  const normalizedConfig = toJsonObject(normalized.config) ?? {};
+  const definition = resolveSchemaFieldType("schedule")!;
+
+  if (
+    !toStringValue(normalizedConfig.referenceField) ||
+    !toStringValue(normalizedConfig.beginningPeriodField) ||
+    !toStringValue(normalizedConfig.endingPeriodField) ||
+    !toStringValue(normalizedConfig.frequency)
+  ) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Schedule fields require "referenceField", "beginningPeriodField", "endingPeriodField" and "frequency". Expected raw shape: ${definition.rawShape}`,
+    );
+  }
+
+  const frequencyValue = toStringValue(normalizedConfig.frequency)!;
+  if (!scheduleAllowedFrequencies.has(frequencyValue)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Schedule "frequency" must be "monthly" or "daily" (received "${frequencyValue}").`,
+    );
+  }
+
+  return normalized;
+}
+
 function normalizeFormulaPayload(input: JsonObject): JsonObject {
   const { status: _status, ...rest } = input;
   const rawAdditionalProperties = toJsonObject(input.additionalProperties);
@@ -465,6 +948,8 @@ export function normalizeSchemaFieldCreatePayload(input: JsonObject): JsonObject
       return normalizeReferencePayload(normalizedWithType);
     case "formula":
       return normalizeFormulaPayload(normalizedWithType);
+    case "schedule":
+      return normalizeSchedulePayload(normalizedWithType);
     case "autoincremental": {
       const config = toJsonObject(normalizedWithType.config) ?? {};
       const segmentedByFieldId =