zinkee 0.1.25 → 0.1.26

package/.claude/settings.local.json

@@ -47,7 +47,10 @@
       "Bash(echo \"=== exit $? \\(grep\\) ===\")",
       "Bash(grep -rn \"resourceType\" src/)",
       "Bash(grep -rn \"automation-folders/\\\\${\\\\|/automations:move\\\\|{folderId}/automations\" src/)",
-      "Bash(grep -rn \"navigation resources move.*--type\\\\|resourceType\" docs/ README.md)"
+      "Bash(grep -rn \"navigation resources move.*--type\\\\|resourceType\" docs/ README.md)",
+      "Bash(zinkee --version)",
+      "Bash(zinkee --json profiles list)",
+      "Bash(zinkee displays *)"
     ]
   }
 }

package/README.md

@@ -486,9 +486,51 @@ zinkee --json displays widgets create <display-uuid> \
     "chart":{"yAxisSeries":[{"typeCalc":"SUM","fieldCalc":"hours-field-slug","axisType":"PRIMARY"}]}
   }'
 
-# KANBAN, TIMELINE, DETAIL also supported
+# KANBAN widget (field mapping lives in view.viewAdditionalProperties.viewState)
+zinkee --json displays widgets create <display-uuid> \
+  --type KANBAN \
+  --name "Status board" \
+  --origin-resource <schema-uuid> \
+  --field <name-field-uuid> --field <status-field-uuid> --field <amount-field-uuid> \
+  --column-field <status-field-uuid> \
+  --swimlane-field <owner-field-uuid> \
+  --card-title-field <name-field-uuid> \
+  --card-category1-field <status-field-uuid> \
+  --aggregation-method sum --aggregation-field <amount-field-uuid> \
+  --view-state '{"showNoValueColumn":true,"showNoValueSwimlane":true}'
+
+# TIMELINE widget (cardConfig uses category1/category2/category4, no category3)
+zinkee --json displays widgets create <display-uuid> \
+  --type TIMELINE \
+  --name "Customer schedule" \
+  --origin-resource <schema-uuid> \
+  --field <name-field-uuid> --field <start-field-uuid> --field <end-field-uuid> \
+  --start-date-field <start-field-uuid> \
+  --end-date-field <end-field-uuid> \
+  --label-field <name-field-uuid> \
+  --card-title-field <name-field-uuid> \
+  --view-state '{"granularity":"month","sidebarWidth":300}'
+
+# HIERARCHY widget (columns + root level + repeatable child levels)
+zinkee --json displays widgets create <display-uuid> \
+  --type HIERARCHY \
+  --name "Org tree" \
+  --origin-resource <schema-uuid> \
+  --field <name-field-uuid> --field <status-field-uuid> --field <amount-field-uuid> \
+  --hierarchy-label "Name" \
+  --hierarchy-info "col_1779975207355_zfndknslw:Status" \
+  --hierarchy-number "col_1779975261490_h8kd3nv9ws:Total amount:SUM" \
+  --hierarchy-root-name "Customers" \
+  --hierarchy-root-label-field <name-field-uuid> \
+  --hierarchy-root-info "col_1779975207355_zfndknslw:<status-field-uuid>" \
+  --hierarchy-root-number "col_1779975261490_h8kd3nv9ws:<amount-field-uuid>" \
+  --hierarchy-child '{"name":"Projects","schemaId":"<projects-schema-uuid>","childFieldId":"<project-customer-field-uuid>","labelFieldId":"<project-name-field-uuid>","infoMappings":[],"numberMappings":[{"columnId":"col_1779975261490_h8kd3nv9ws","fieldId":"<project-amount-field-uuid>"}]}'
 ```
 
+For KANBAN/TIMELINE, `cardConfig` differs by type: KANBAN exposes `category1Field`/`category2Field`/`category3Field` (`--card-category1-field`…`--card-category3-field`), TIMELINE exposes `category1Field`/`category2Field`/`category4Field` (`--card-category4-field`). UI-state scalars (`columnOrder`, `hiddenColumns`, `collapsedColumns`, `hideEmptyColumns`, `showNoValueColumn`, `showNoValueSwimlane`, `granularity`, `sidebarWidth`, `visibleFields`, `collapsedGroups`, `collapsedSubgroups`, `showUngroupedEvents`, `showUnsubgroupedEvents`) go through `--view-state '<json>'` / `--view-state-file <path>`.
+
+For HIERARCHY, `label` is required at every level but info/number mappings are optional; each child level relates to its parent through `childFieldId` (level 2 → root, level 3 → level 2, …). Numeric columns aggregate upward: a parent shows the aggregation of its children's values, falling back to the level's own mapped value when children have none. Column ids (the `id` in `--hierarchy-info`/`--hierarchy-number`, reused as `columnId` in every mapping) must be unique opaque identifiers you choose — not the column name; the frontend generates them as `col_<timestamp>_<random>` (e.g. `col_1779975207355_zfndknslw`). Pass the whole `hierarchyConfig` at once with `--hierarchy-config '<json>'` / `--hierarchy-config-file <path>` if you prefer.
+
 Widget types: `TABLE_OR_SUBTABLE`, `DETAIL`, `KPI`, `CHART`, `TIMELINE`, `KANBAN`, `HIERARCHY`.
 
 ### Set freeform layout
@@ -525,6 +567,8 @@ For comparators the parser does not cover yet (e.g. `NOT_CONTAINS`, `RANGE`) kee
 
 Slugs are resolved to UUIDs in: `--field`, `--source-schema`, `--source-field`, `--x-axis-field`, `--filter` field reference, `kpi.fieldCalc`, `chart.xAxisFieldId`, `chart.yAxisSeries[].fieldCalc`, `bindings.variableMap` values.
 
+**Exception:** field references inside the KANBAN/TIMELINE `viewState` (`--column-field`, `--start-date-field`, `--card-*-field`, `--aggregation-field`, …) and inside the HIERARCHY `hierarchyConfig` (`--hierarchy-root-label-field`, `--hierarchy-root-info`/`--hierarchy-root-number` field ids, child level `*FieldId`/`schemaId`) are **not** slug-resolved — the backend only resolves slugs in `view.fields`, so these must be canonical UUIDs.
+
 Display UUIDs are required for `displays widgets create/update` and `displays variables create`.
 
 ---

package/dist/index.js

@@ -3381,7 +3381,7 @@ var specificExamples = {
   "displays widgets create": buildCommandExamples([
     {
       description: "Create a TABLE widget (CLI normalises --type table to TABLE_OR_SUBTABLE).",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Customers --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field id --field contact-name --field status --sort '{"fieldId":"id","direction":"DESC"}'`,
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Customers --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field contact-name --field status --field amount --sort '{"fieldId":"contact-name","direction":"ASC"}'`,
       raw: `{
   "type": "TABLE_OR_SUBTABLE",
   "source": {
@@ -3396,11 +3396,11 @@ var specificExamples = {
   },
   "query": {
     "sorts": [
-      { "fieldId": "id", "direction": "DESC" }
+      { "fieldId": "contact-name", "direction": "ASC" }
     ]
   },
   "view": {
-    "fields": ["id", "contact-name", "status"]
+    "fields": ["contact-name", "status", "amount"]
   }
 }`,
       response: `{
@@ -3480,7 +3480,7 @@ var specificExamples = {
     },
     {
       description: "Create a bars CHART widget with a monthly time-serie x-axis and two y-axis series.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"contact-name","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
       raw: `{
   "type": "CHART",
   "source": {
@@ -3505,7 +3505,7 @@ var specificExamples = {
       },
       {
         "typeCalc": "COUNT",
-        "fieldCalc": "id",
+        "fieldCalc": "contact-name",
         "color": "#E57373",
         "axisType": "SECONDARY"
       }
@@ -3575,8 +3575,8 @@ var specificExamples = {
 }`
     },
     {
-      description: "Create a TIMELINE widget.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type TIMELINE --name "Customer schedule" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":6}' --field contact-name --field due-date`,
+      description: "Create a TIMELINE widget via flags. The typed view state lives in view.viewAdditionalProperties.viewState; field references there must be UUIDs (slugs are only resolved in --field). cardConfig uses category1/category2/category4 (no category3). Use --view-state for UI scalars (granularity, sidebarWidth, show* ...).",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type TIMELINE --name "Customer schedule" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":6}' --field c60b8526-5835-4c9f-aecd-9a16c7704a34 --field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --start-date-field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --end-date-field e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012 --label-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --group-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --subgroup-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --progress-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --card-title-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --card-category1-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --card-category2-field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --card-category4-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --card-description-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --view-state '{"granularity":"month","sidebarWidth":300,"showUngroupedEvents":true,"showUnsubgroupedEvents":true}'`,
       raw: `{
   "type": "TIMELINE",
   "source": {
@@ -3588,13 +3588,41 @@ var specificExamples = {
   },
   "presentation": { "name": "Customer schedule" },
   "view": {
-    "fields": ["contact-name", "due-date"]
+    "fields": [
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+      "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+      "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
+    ],
+    "viewAdditionalProperties": {
+      "viewState": {
+        "granularity": "month",
+        "sidebarWidth": 300,
+        "showUngroupedEvents": true,
+        "showUnsubgroupedEvents": true,
+        "fieldMapping": {
+          "startDateField": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+          "endDateField": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012",
+          "labelField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "groupField": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+          "subgroupField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "progressField": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+          "cardConfig": {
+            "titleField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+            "category1Field": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+            "category2Field": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            "category4Field": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+            "descriptionField": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+          }
+        }
+      }
+    }
   }
 }`
     },
     {
-      description: "Create a KANBAN widget with a status filter and groupsExpanded config (rich query/view requires --raw).",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --raw '{"type":"KANBAN","source":{"originResourceId":"2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e","isOriginSubSchema":false},"placement":{"layout":{"x":0,"y":0,"w":12,"h":8}},"presentation":{"name":"Status board"},"query":{"filters":[{"origin":{"schemaId":"contacts","fieldId":"status"},"comparisonOperator":"ANY_OF","values":["1","2","3"]}]},"view":{"fields":["contact-name","status","amount"],"groupsExpanded":{"1":true,"2":true,"3":false}}}'`,
+      description: "Create a KANBAN widget via flags. The typed view state lives in view.viewAdditionalProperties.viewState; field references there must be UUIDs (slugs are only resolved in --field). cardConfig uses category1/category2/category3 (no category4). --aggregation-method/--aggregation-field set the card aggregation; use --view-state for UI scalars.",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type KANBAN --name "Status board" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field c60b8526-5835-4c9f-aecd-9a16c7704a34 --field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --column-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --swimlane-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --card-title-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --card-category1-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --card-category2-field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --card-category3-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --card-description-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --aggregation-method sum --aggregation-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --view-state '{"hideEmptyColumns":false,"showNoValueColumn":true,"showNoValueSwimlane":true}'`,
       raw: `{
   "type": "KANBAN",
   "source": {
@@ -3605,27 +3633,41 @@ var specificExamples = {
     "layout": { "x": 0, "y": 0, "w": 12, "h": 8 }
   },
   "presentation": { "name": "Status board" },
-  "query": {
-    "filters": [
-      {
-        "origin": {
-          "schemaId": "contacts",
-          "fieldId": "status"
-        },
-        "comparisonOperator": "ANY_OF",
-        "values": ["1", "2", "3"]
-      }
-    ]
-  },
   "view": {
-    "fields": ["contact-name", "status", "amount"],
-    "groupsExpanded": { "1": true, "2": true, "3": false }
+    "fields": [
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+      "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+      "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
+    ],
+    "viewAdditionalProperties": {
+      "viewState": {
+        "hideEmptyColumns": false,
+        "showNoValueColumn": true,
+        "showNoValueSwimlane": true,
+        "fieldMapping": {
+          "columnField": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+          "swimlaneField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "cardConfig": {
+            "titleField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+            "category1Field": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+            "category2Field": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            "category3Field": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+            "descriptionField": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+          },
+          "aggregationConfig": {
+            "method": "sum",
+            "fieldId": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043"
+          }
+        }
+      }
+    }
   }
 }`
     },
     {
-      description: "Create a HIERARCHY widget rooted on a parent field.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --raw '{"type":"HIERARCHY","source":{"originResourceId":"2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e","isOriginSubSchema":false},"placement":{"layout":{"x":0,"y":0,"w":12,"h":6}},"presentation":{"name":"Org tree"},"view":{"fields":["contact-name","status"],"hierarchyConfig":{"parentFieldId":"contact-name"}}}'`,
+      description: "Create a HIERARCHY widget via flags. Declare columns once (--hierarchy-label, repeatable --hierarchy-info <id:name>, --hierarchy-number <id:name:aggregation>), map the root level (the view's own table) with --hierarchy-root-* and add each child level as a JSON object with --hierarchy-child. label is required per level; info/number mappings are optional. Column ids (e.g. col_1779975207355_zfndknslw) are unique opaque identifiers you choose \u2014 not the column name \u2014 and are reused as columnId in every mapping. All field references must be UUIDs.",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type HIERARCHY --name "Org tree" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":6}' --field c60b8526-5835-4c9f-aecd-9a16c7704a34 --field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --hierarchy-label "Name" --hierarchy-info "col_1779975207355_zfndknslw:Status" --hierarchy-info "col_1779975243018_qm4t7xb2pa:Description" --hierarchy-number "col_1779975261490_h8kd3nv9ws:Total amount:SUM" --hierarchy-root-name "Customers" --hierarchy-root-label-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --hierarchy-root-info "col_1779975207355_zfndknslw:a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890" --hierarchy-root-number "col_1779975261490_h8kd3nv9ws:c52efe3f-2825-4c60-a7e3-34dd4c1ce043" --hierarchy-child '{"name":"Projects","schemaId":"3ec9cdef-7e0a-4cdd-8019-8fb9281f5d6f","childFieldId":"80deefae-af3d-4000-b322-bfe1594f8073","labelFieldId":"50dbef0b-7e0a-4fdd-8019-8fb9281f5d70","infoMappings":[{"columnId":"col_1779975243018_qm4t7xb2pa","fieldId":"60dcef0c-8f1b-4eee-9120-9fc0392f6e71"}],"numberMappings":[{"columnId":"col_1779975261490_h8kd3nv9ws","fieldId":"70ddef0d-9f2c-4fff-a221-afd0493f7f72"}]}'`,
       raw: `{
   "type": "HIERARCHY",
   "source": {
@@ -3637,9 +3679,46 @@ var specificExamples = {
   },
   "presentation": { "name": "Org tree" },
   "view": {
-    "fields": ["contact-name", "status"],
+    "fields": [
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+      "c52efe3f-2825-4c60-a7e3-34dd4c1ce043"
+    ],
     "hierarchyConfig": {
-      "parentFieldId": "contact-name"
+      "columns": {
+        "label": "Name",
+        "infos": [
+          { "id": "col_1779975207355_zfndknslw", "name": "Status" },
+          { "id": "col_1779975243018_qm4t7xb2pa", "name": "Description" }
+        ],
+        "numbers": [
+          { "id": "col_1779975261490_h8kd3nv9ws", "name": "Total amount", "aggregation": "SUM" }
+        ]
+      },
+      "rootLevel": {
+        "name": "Customers",
+        "labelFieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+        "infoMappings": [
+          { "columnId": "col_1779975207355_zfndknslw", "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890" }
+        ],
+        "numberMappings": [
+          { "columnId": "col_1779975261490_h8kd3nv9ws", "fieldId": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043" }
+        ]
+      },
+      "childLevels": [
+        {
+          "name": "Projects",
+          "schemaId": "3ec9cdef-7e0a-4cdd-8019-8fb9281f5d6f",
+          "childFieldId": "80deefae-af3d-4000-b322-bfe1594f8073",
+          "labelFieldId": "50dbef0b-7e0a-4fdd-8019-8fb9281f5d70",
+          "infoMappings": [
+            { "columnId": "col_1779975243018_qm4t7xb2pa", "fieldId": "60dcef0c-8f1b-4eee-9120-9fc0392f6e71" }
+          ],
+          "numberMappings": [
+            { "columnId": "col_1779975261490_h8kd3nv9ws", "fieldId": "70ddef0d-9f2c-4fff-a221-afd0493f7f72" }
+          ]
+        }
+      ]
     }
   }
 }`
@@ -3648,13 +3727,13 @@ var specificExamples = {
   "displays widgets update": buildCommandExamples([
     {
       description: "Move placement, update view columns, rename the widget and lock it.",
-      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --layout '{"x":1,"y":2,"w":8,"h":4}' --field id --field contact-name --field status --name "Revenue Updated" --widget-read-only`,
+      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --layout '{"x":1,"y":2,"w":8,"h":4}' --field contact-name --field status --field amount --name "Revenue Updated" --widget-read-only`,
       raw: `{
   "placement": {
     "layout": { "x": 1, "y": 2, "w": 8, "h": 4 }
   },
   "view": {
-    "fields": ["id", "contact-name", "status"]
+    "fields": ["contact-name", "status", "amount"]
   },
   "presentation": { "name": "Revenue Updated" },
   "behavior": { "readOnly": true }
@@ -4711,7 +4790,7 @@ var specificExamples = {
         "hideDeleteButton": false
       },
       "view": {
-        "fields": ["id", "contact-name", "status", "amount"],
+        "fields": ["contact-name", "status", "amount"],
         "columnSize": { "contact-name": 240 }
       }
     }
@@ -4928,7 +5007,7 @@ var specificExamples = {
     "hideDeleteButton": false
   },
   "view": {
-    "fields": ["id", "contact-name", "status", "amount"],
+    "fields": ["contact-name", "status", "amount"],
     "columnSize": { "contact-name": 240 }
   }
 }`
@@ -8619,6 +8698,150 @@ function readNamedJsonOption(raw, rawFile, inlineFlag = "--option", fileFlag = "
 function isEmptyObject3(value) {
   return Object.keys(value).length === 0;
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(target, source) {
+  const out = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const existing = out[key];
+    out[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+  }
+  return out;
+}
+function assignDefined(target, key, value) {
+  if (value !== void 0) target[key] = value;
+}
+function readNamedJsonObject(raw, rawFile, inlineFlag, fileFlag) {
+  const parsed = readNamedJsonOption(raw, rawFile, inlineFlag, fileFlag);
+  if (parsed === void 0) return void 0;
+  if (!isPlainObject(parsed)) {
+    throw new CliError("invalid_cli_usage", `${inlineFlag} payload must be a JSON object.`);
+  }
+  return parsed;
+}
+var HIERARCHY_AGGREGATIONS = /* @__PURE__ */ new Set([
+  "SUM",
+  "AVERAGE",
+  "MINIMUM",
+  "MAXIMUM",
+  "COUNT",
+  "COUNT_DISTINCT"
+]);
+function parseHierarchyInfo(value) {
+  const idx = value.indexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new CliError("invalid_cli_usage", `--hierarchy-info "${value}" must use the format <id:name>.`);
+  }
+  return { id: value.slice(0, idx).trim(), name: value.slice(idx + 1).trim() };
+}
+function parseHierarchyNumber(value) {
+  const parts = value.split(":");
+  if (parts.length < 3) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number "${value}" must use the format <id:name:aggregation>.`
+    );
+  }
+  const id = parts[0]?.trim() ?? "";
+  const aggregation = (parts[parts.length - 1]?.trim() ?? "").toUpperCase();
+  const name = parts.slice(1, -1).join(":").trim();
+  if (!id || !name) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number "${value}" must use the format <id:name:aggregation>.`
+    );
+  }
+  if (!HIERARCHY_AGGREGATIONS.has(aggregation)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number aggregation "${aggregation}" must be one of SUM, AVERAGE, MINIMUM, MAXIMUM, COUNT, COUNT_DISTINCT.`
+    );
+  }
+  return { id, name, aggregation };
+}
+function parseHierarchyMapping(value, flag) {
+  const idx = value.indexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new CliError("invalid_cli_usage", `${flag} "${value}" must use the format <columnId:fieldId>.`);
+  }
+  return { columnId: value.slice(0, idx).trim(), fieldId: value.slice(idx + 1).trim() };
+}
+function buildWidgetFieldMapping(options) {
+  const mapping = {};
+  assignDefined(mapping, "columnField", options.columnField);
+  assignDefined(mapping, "swimlaneField", options.swimlaneField);
+  assignDefined(mapping, "startDateField", options.startDateField);
+  assignDefined(mapping, "endDateField", options.endDateField);
+  assignDefined(mapping, "labelField", options.labelField);
+  assignDefined(mapping, "groupField", options.groupField);
+  assignDefined(mapping, "subgroupField", options.subgroupField);
+  assignDefined(mapping, "progressField", options.progressField);
+  const cardConfig = {};
+  assignDefined(cardConfig, "titleField", options.cardTitleField);
+  assignDefined(cardConfig, "category1Field", options.cardCategory1Field);
+  assignDefined(cardConfig, "category2Field", options.cardCategory2Field);
+  assignDefined(cardConfig, "category3Field", options.cardCategory3Field);
+  assignDefined(cardConfig, "category4Field", options.cardCategory4Field);
+  assignDefined(cardConfig, "descriptionField", options.cardDescriptionField);
+  if (Object.keys(cardConfig).length > 0) mapping.cardConfig = cardConfig;
+  const aggregationConfig = {};
+  assignDefined(aggregationConfig, "method", options.aggregationMethod);
+  assignDefined(aggregationConfig, "fieldId", options.aggregationField);
+  if (Object.keys(aggregationConfig).length > 0) mapping.aggregationConfig = aggregationConfig;
+  return Object.keys(mapping).length > 0 ? mapping : void 0;
+}
+function buildHierarchyConfig(options) {
+  const base = readNamedJsonObject(
+    options.hierarchyConfig,
+    options.hierarchyConfigFile,
+    "--hierarchy-config",
+    "--hierarchy-config-file"
+  );
+  const patch = {};
+  const columns = {};
+  assignDefined(columns, "label", options.hierarchyLabel);
+  if (options.hierarchyInfo && options.hierarchyInfo.length > 0) {
+    columns.infos = options.hierarchyInfo.map(parseHierarchyInfo);
+  }
+  if (options.hierarchyNumber && options.hierarchyNumber.length > 0) {
+    columns.numbers = options.hierarchyNumber.map(parseHierarchyNumber);
+  }
+  if (Object.keys(columns).length > 0) patch.columns = columns;
+  const rootLevel = {};
+  assignDefined(rootLevel, "name", options.hierarchyRootName);
+  assignDefined(rootLevel, "labelFieldId", options.hierarchyRootLabelField);
+  if (options.hierarchyRootInfo && options.hierarchyRootInfo.length > 0) {
+    rootLevel.infoMappings = options.hierarchyRootInfo.map(
+      (entry) => parseHierarchyMapping(entry, "--hierarchy-root-info")
+    );
+  }
+  if (options.hierarchyRootNumber && options.hierarchyRootNumber.length > 0) {
+    rootLevel.numberMappings = options.hierarchyRootNumber.map(
+      (entry) => parseHierarchyMapping(entry, "--hierarchy-root-number")
+    );
+  }
+  if (Object.keys(rootLevel).length > 0) patch.rootLevel = rootLevel;
+  if (options.hierarchyChild && options.hierarchyChild.length > 0) {
+    patch.childLevels = options.hierarchyChild.map((entry, index) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(entry);
+      } catch {
+        throw new CliError("invalid_cli_usage", `--hierarchy-child payload #${index + 1} is invalid JSON.`);
+      }
+      if (!isPlainObject(parsed)) {
+        throw new CliError(
+          "invalid_cli_usage",
+          `--hierarchy-child payload #${index + 1} must be a JSON object.`
+        );
+      }
+      return parsed;
+    });
+  }
+  if (base === void 0 && Object.keys(patch).length === 0) return void 0;
+  return deepMerge(base ?? {}, patch);
+}
 function displayRows(displays) {
   return displays.map((display) => ({
     id: display.id,
@@ -8725,11 +8948,31 @@ function buildWidgetBody(options) {
       layout
     };
   }
+  const viewPatch = {};
   if (options.field && options.field.length > 0) {
-    body.view = {
-      ...typeof body.view === "object" && body.view ? body.view : {},
-      fields: options.field
-    };
+    viewPatch.fields = options.field;
+  }
+  const fieldMapping = buildWidgetFieldMapping(options);
+  const viewStateBase = readNamedJsonObject(
+    options.viewState,
+    options.viewStateFile,
+    "--view-state",
+    "--view-state-file"
+  );
+  let viewState = viewStateBase ? { ...viewStateBase } : void 0;
+  if (fieldMapping) {
+    viewState = deepMerge(viewState ?? {}, { fieldMapping });
+  }
+  if (viewState !== void 0) {
+    viewPatch.viewAdditionalProperties = { viewState };
+  }
+  const hierarchyConfig = buildHierarchyConfig(options);
+  if (hierarchyConfig !== void 0) {
+    viewPatch.hierarchyConfig = hierarchyConfig;
+  }
+  if (Object.keys(viewPatch).length > 0) {
+    const existingView = typeof body.view === "object" && body.view ? body.view : {};
+    body.view = deepMerge(existingView, viewPatch);
   }
   const queryMerge = {};
   if (options.sort && options.sort.length > 0) queryMerge.sorts = options.sort;
@@ -9068,7 +9311,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("--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("--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));
@@ -9078,7 +9321,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("--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("--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));