zinkee 0.1.37 → 0.1.39

package/dist/index.js

@@ -461,7 +461,7 @@ var commandRegistry = {
     command: "displays cross-widget-filter set",
     accessLevel: "write",
     supportsExample: true,
-    supportsRaw: false,
+    supportsRaw: true,
     output: writeOutput
   },
   "displays cross-widget-filter delete": {
@@ -3554,6 +3554,48 @@ var specificExamples = {
       response: `{
   "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
   "widgetId": "11111111-1111-4111-a111-111111111111"
+}`
+    },
+    {
+      description: "Create a TABLE widget with locked fields: contact-name locked permanently (no conditions) and status locked while invoice-number is empty, with before/after lock messages.",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Invoices --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field contact-name --field invoice-number --field status --field amount --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-message-before "status:Status locks until the invoice number is set." --lock-message-after "status:Status is locked because the invoice number is missing."`,
+      raw: `{
+  "type": "TABLE_OR_SUBTABLE",
+  "source": {
+    "originResourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+    "isOriginSubSchema": false
+  },
+  "placement": {
+    "layout": { "x": 0, "y": 0, "w": 12, "h": 8 }
+  },
+  "presentation": { "name": "Invoices" },
+  "view": {
+    "fields": ["contact-name", "invoice-number", "status", "amount"]
+  },
+  "behavior": {
+    "lockedFields": [
+      {
+        "field": { "fieldId": "contact-name" },
+        "conditions": []
+      },
+      {
+        "field": { "fieldId": "status" },
+        "conditions": [
+          {
+            "origin": { "fieldId": "invoice-number" },
+            "comparisonOperator": "IS_EMPTY",
+            "values": []
+          }
+        ],
+        "messageBeforeLock": "Status locks until the invoice number is set.",
+        "messageAfterLock": "Status is locked because the invoice number is missing."
+      }
+    ]
+  }
+}`,
+      response: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "widgetId": "11111111-1111-4111-a111-111111111111"
 }`
     },
     {
@@ -3935,6 +3977,43 @@ var specificExamples = {
     "hideDeleteButton": true,
     "hideFilterButton": true
   }
+}`
+    },
+    {
+      description: "Configure locked fields (replaces the stored configuration): contact-name locked permanently, status locked while invoice-number is empty. Empty conditions = always locked; conditions combine with AND. Enforcement happens in display widgets only, never in the database view.",
+      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-message-before "status:Status locks until the invoice number is set." --lock-message-after "status:Status is locked because the invoice number is missing."`,
+      raw: `{
+  "behavior": {
+    "lockedFields": [
+      {
+        "field": { "fieldId": "contact-name" },
+        "conditions": []
+      },
+      {
+        "field": { "fieldId": "status" },
+        "conditions": [
+          {
+            "origin": { "fieldId": "invoice-number" },
+            "comparisonOperator": "IS_EMPTY",
+            "values": []
+          }
+        ],
+        "messageBeforeLock": "Status locks until the invoice number is set.",
+        "messageAfterLock": "Status is locked because the invoice number is missing."
+      }
+    ]
+  }
+}`,
+      response: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "widgetId": "11111111-1111-4111-a111-111111111111"
+}`
+    },
+    {
+      description: "Clear the locked-fields configuration.",
+      command: "zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --clear-locked-fields",
+      raw: `{
+  "behavior": { "lockedFields": [] }
 }`
     },
     {
@@ -4036,40 +4115,86 @@ var specificExamples = {
   ]),
   "displays cross-widget-filter set": buildCommandExamples([
     {
-      description: "Link one source widget/field to several target widgets through the same field.",
+      description: "Single configuration with flags: link one source widget/field to several targets. The whole array is replaced.",
       command: "zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --source-widget 11111111-1111-4111-a111-111111111111 --source-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --target 22222222-2222-4222-a222-222222222222:c60b8526-5835-4c9f-aecd-9a16c7704a34 --target 33333333-3333-4333-a333-333333333333:c60b8526-5835-4c9f-aecd-9a16c7704a34",
-      raw: `{
-  "source": {
-    "widgetId": "11111111-1111-4111-a111-111111111111",
-    "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-  },
-  "targets": [
-    {
-      "widgetId": "22222222-2222-4222-a222-222222222222",
+      raw: `[
+  {
+    "source": {
+      "widgetId": "11111111-1111-4111-a111-111111111111",
       "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
     },
+    "targets": [
+      {
+        "widgetId": "22222222-2222-4222-a222-222222222222",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      },
+      {
+        "widgetId": "33333333-3333-4333-a333-333333333333",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      }
+    ]
+  }
+]`
+    },
     {
-      "widgetId": "33333333-3333-4333-a333-333333333333",
+      description: "Several independent configurations with --raw (each source filters its own targets). A widget cannot be a target of two configurations.",
+      command: `zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --raw '[{"source":{"widgetId":"11111111-1111-4111-a111-111111111111","fieldId":"c60b8526-5835-4c9f-aecd-9a16c7704a34"},"targets":[{"widgetId":"22222222-2222-4222-a222-222222222222","fieldId":"c60b8526-5835-4c9f-aecd-9a16c7704a34"}]},{"source":{"widgetId":"44444444-4444-4444-a444-444444444444","fieldId":"a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"},"targets":[{"widgetId":"55555555-5555-4555-a555-555555555555","fieldId":"a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"}]}]'`,
+      raw: `[
+  {
+    "source": {
+      "widgetId": "11111111-1111-4111-a111-111111111111",
       "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-    }
-  ]
-}`
     },
-    {
-      description: "Filter one target widget by the status field of the source.",
-      command: "zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --source-widget 11111111-1111-4111-a111-111111111111 --source-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --target 66666666-6666-4666-a666-666666666666:a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
-      raw: `{
-  "source": {
-    "widgetId": "11111111-1111-4111-a111-111111111111",
-    "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+    "targets": [
+      {
+        "widgetId": "22222222-2222-4222-a222-222222222222",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      }
+    ]
   },
-  "targets": [
+  {
+    "source": {
+      "widgetId": "44444444-4444-4444-a444-444444444444",
+      "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+    },
+    "targets": [
+      {
+        "widgetId": "55555555-5555-4555-a555-555555555555",
+        "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+      }
+    ]
+  }
+]`
+    },
     {
-      "widgetId": "66666666-6666-4666-a666-666666666666",
+      description: "Hierarchy chain with --raw-file: a target of one configuration is the source of the next (click Parent \u2192 filters Child, click Child \u2192 filters Grandchild).",
+      command: "zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --raw-file cross-widget-filter.json",
+      raw: `[
+  {
+    "source": {
+      "widgetId": "11111111-1111-4111-a111-111111111111",
+      "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+    },
+    "targets": [
+      {
+        "widgetId": "22222222-2222-4222-a222-222222222222",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      }
+    ]
+  },
+  {
+    "source": {
+      "widgetId": "22222222-2222-4222-a222-222222222222",
       "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
-    }
-  ]
-}`
+    },
+    "targets": [
+      {
+        "widgetId": "33333333-3333-4333-a333-333333333333",
+        "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+      }
+    ]
+  }
+]`
     }
   ]),
   "schemas list": buildCommandExamples([
@@ -4962,18 +5087,20 @@ var specificExamples = {
       }
     }
   ],
-  "crossWidgetFilter": {
-    "source": {
-      "widgetId": "11111111-1111-4111-a111-111111111111",
-      "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-    },
-    "targets": [
-      {
-        "widgetId": "22222222-2222-4222-a222-222222222222",
+  "crossWidgetFilter": [
+    {
+      "sourceWidget": {
+        "widgetId": "11111111-1111-4111-a111-111111111111",
         "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-      }
-    ]
-  },
+      },
+      "targetWidgets": [
+        {
+          "widgetId": "22222222-2222-4222-a222-222222222222",
+          "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+        }
+      ]
+    }
+  ],
   "navigationTargets": [
     {
       "id": "nav-target-customer",
@@ -8859,6 +8986,83 @@ function parseFilterExpression(input) {
 function collectFilters(value, previous = []) {
   return [...previous, parseFilterExpression(value)];
 }
+function parseLockConditionOption(input) {
+  const trimmed = input.trim();
+  let lockedField;
+  let expressionText;
+  if (trimmed.includes(":") && !trimmed.includes(" ")) {
+    const separatorIndex = trimmed.indexOf(":");
+    lockedField = trimmed.slice(0, separatorIndex).trim();
+    expressionText = trimmed.slice(separatorIndex + 1).trim();
+  } else {
+    const parts = trimmed.split(/\s+/);
+    lockedField = parts[0]?.trim() ?? "";
+    expressionText = parts.slice(1).join(" ").trim();
+  }
+  if (!lockedField || !expressionText) {
+    throw new InvalidArgumentError3(
+      'Expected "<lockedField>:<field>:<comparator>[:<value>]" (or space-separated), e.g. "status:invoice-number:is_empty".'
+    );
+  }
+  return { lockedField, expression: parseFilterExpression(expressionText) };
+}
+function collectLockConditions(value, previous = []) {
+  return [...previous, parseLockConditionOption(value)];
+}
+function parseLockMessageOption(input) {
+  const separatorIndex = input.indexOf(":");
+  const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
+  const message = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim() : "";
+  if (!lockedField || !message) {
+    throw new InvalidArgumentError3('Expected "<lockedField>:<message>", e.g. "status:Locked once approved.".');
+  }
+  return { lockedField, message };
+}
+function collectLockMessages(value, previous = []) {
+  return [...previous, parseLockMessageOption(value)];
+}
+function buildLockedFields(options) {
+  const hasLockFlags = (options.lockField?.length ?? 0) > 0 || (options.lockCondition?.length ?? 0) > 0 || (options.lockMessageBefore?.length ?? 0) > 0 || (options.lockMessageAfter?.length ?? 0) > 0;
+  if (options.clearLockedFields) {
+    if (hasLockFlags) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Use either "--clear-locked-fields" or the "--lock-*" flags, not both.'
+      );
+    }
+    return [];
+  }
+  if (!hasLockFlags) {
+    return void 0;
+  }
+  const rules = /* @__PURE__ */ new Map();
+  const ensureRule = (lockedField) => {
+    let rule = rules.get(lockedField);
+    if (!rule) {
+      rule = { conditions: [] };
+      rules.set(lockedField, rule);
+    }
+    return rule;
+  };
+  for (const lockedField of options.lockField ?? []) {
+    ensureRule(lockedField);
+  }
+  for (const { lockedField, expression } of options.lockCondition ?? []) {
+    ensureRule(lockedField).conditions.push(toDisplayFilter(expression));
+  }
+  for (const { lockedField, message } of options.lockMessageBefore ?? []) {
+    ensureRule(lockedField).messageBeforeLock = message;
+  }
+  for (const { lockedField, message } of options.lockMessageAfter ?? []) {
+    ensureRule(lockedField).messageAfterLock = message;
+  }
+  return [...rules.entries()].map(([lockedField, rule]) => ({
+    field: { fieldId: lockedField },
+    conditions: rule.conditions,
+    ...rule.messageBeforeLock !== void 0 ? { messageBeforeLock: rule.messageBeforeLock } : {},
+    ...rule.messageAfterLock !== void 0 ? { messageAfterLock: rule.messageAfterLock } : {}
+  }));
+}
 function readRawObject2(raw, rawFile) {
   if (raw && rawFile) {
     throw new CliError("invalid_cli_usage", 'Use either "--raw" or "--raw-file", not both.');
@@ -9189,6 +9393,13 @@ function buildWidgetBody(options) {
       hideSeeButton: options.hideSeeButton
     };
   }
+  const lockedFields = buildLockedFields(options);
+  if (lockedFields !== void 0) {
+    body.behavior = {
+      ...typeof body.behavior === "object" && body.behavior ? body.behavior : {},
+      lockedFields
+    };
+  }
   if (options.calc || options.calcField || options.kpiConfig) {
     body.kpi = {
       ...typeof body.kpi === "object" && body.kpi ? body.kpi : {},
@@ -9226,20 +9437,54 @@ function buildNavigationTargetBody(options) {
   }
   return body;
 }
+function readRawArray(raw, rawFile) {
+  if (raw && rawFile) {
+    throw new CliError("invalid_cli_usage", 'Use either "--raw" or "--raw-file", not both.');
+  }
+  const source = rawFile ? readFileSync4(rawFile, "utf8") : raw;
+  if (!source) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(source);
+    if (!Array.isArray(parsed)) {
+      throw new CliError("invalid_cli_usage", "Raw cross widget filter payload must be a JSON array of configurations.");
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError("invalid_cli_usage", "Raw JSON payload is invalid.");
+  }
+}
 function buildCrossWidgetFilterBody(options) {
-  return {
-    source: {
-      widgetId: options.sourceWidget,
-      fieldId: options.sourceField
-    },
-    targets: options.target.map((entry) => {
-      const [widgetId, fieldId] = entry.split(":");
-      if (!widgetId || !fieldId) {
-        throw new CliError("invalid_cli_usage", `Invalid --target entry "${entry}". Use <widgetId:fieldId>.`);
-      }
-      return { widgetId, fieldId };
-    })
+  if (options.raw !== void 0 || options.rawFile !== void 0) {
+    return readRawArray(options.raw, options.rawFile);
+  }
+  if (!options.sourceWidget || !options.sourceField) {
+    throw new CliError(
+      "invalid_cli_usage",
+      "Provide --source-widget and --source-field, or --raw/--raw-file with the full configuration array."
+    );
+  }
+  const source = {
+    widgetId: options.sourceWidget,
+    fieldId: options.sourceField
   };
+  if (options.sourceSchema) {
+    source.schemaId = options.sourceSchema;
+  }
+  return [
+    {
+      source,
+      targets: (options.target ?? []).map((entry) => {
+        const [widgetId, fieldId] = entry.split(":");
+        if (!widgetId || !fieldId) {
+          throw new CliError("invalid_cli_usage", `Invalid --target entry "${entry}". Use <widgetId:fieldId>.`);
+        }
+        return { widgetId, fieldId };
+      })
+    }
+  ];
 }
 function registerDisplaysCommands(program, options = {}) {
   const filePath = options.configPath ?? defaultConfigPath;
@@ -9506,7 +9751,7 @@ function registerDisplaysCommands(program, options = {}) {
     }
     printTable([data], void 0, stdout);
   });
-  widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).requiredOption("--type <type>", "widget type").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, commandOptions) {
+  widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).requiredOption("--type <type>", "widget type").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, []).option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, []).option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, []).option("--clear-locked-fields", "clear the widget locked-fields configuration").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays widgets create", readOnly, "write");
     const data = await api.createWidget(display, buildWidgetBody(commandOptions));
@@ -9516,7 +9761,7 @@ function registerDisplaysCommands(program, options = {}) {
     }
     writeLine4(stdout, `Created widget on display "${display.value}".`);
   });
-  widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).argument("<widget>", "widget id").option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, widgetId, commandOptions) {
+  widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).argument("<widget>", "widget id").option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, []).option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, []).option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, []).option("--clear-locked-fields", "clear the widget locked-fields configuration").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, widgetId, commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays widgets update", readOnly, "write");
     const data = await api.updateWidget(display, widgetId, buildWidgetBody(commandOptions));
@@ -9586,9 +9831,9 @@ function registerDisplaysCommands(program, options = {}) {
       emitJson4(stdout, "displays cross-widget-filter get", item);
       return;
     }
-    printTable(item ? [item] : [], void 0, stdout);
+    printTable(item ?? [], void 0, stdout);
   });
-  cross.command("set").description("Set cross widget filter").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).requiredOption("--source-widget <id>").requiredOption("--source-field <id>").requiredOption("--target <widget:field>", "repeatable target", (v, p = []) => [...p, v], []).action(async function action(display, commandOptions) {
+  cross.command("set").description("Set cross widget filter (replaces the whole array of configurations)").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).option("--source-widget <id>", "source widget id (single-configuration mode)").option("--source-field <id>", "source field id (single-configuration mode)").option("--source-schema <id>", "source schema id, only for HIERARCHY source widgets").option("--target <widget:field>", "repeatable target (single-configuration mode)", (v, p = []) => [...p, v], []).option("--raw <json>", "full array of configurations as JSON (for several configurations)").option("--raw-file <path>", "path to a JSON file with the full array of configurations").action(async function action(display, commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays cross-widget-filter set", readOnly, "write");
     const data = await api.setCrossWidgetFilter(display, buildCrossWidgetFilterBody(commandOptions));