zinkee 0.1.42 → 0.1.44

package/README.md

@@ -144,7 +144,7 @@ zinkee --json schemas get projects
 Simple field types use `--type`, `--slug`, `--label`:
 
 ```bash
-zinkee schemas fields create projects --type text --slug name --label "Name"
+zinkee schemas fields create projects --type text --slug name --label "Name" --description "Primary project name"
 zinkee schemas fields create projects --type number --slug budget --label "Budget" --required true --default 0
 zinkee schemas fields create projects --type date --slug start-date --label "Start Date"
 zinkee schemas fields create projects --type file --slug attachment --label "Attachment"
@@ -206,6 +206,8 @@ Use `--default <value>` for the common default-value case:
 
 ```bash
 zinkee schemas fields update projects budget --default 0
+zinkee schemas fields update projects budget --description "Approved project budget"
+zinkee schemas fields update projects budget --description "" # Clear the description
 ```
 
 PATCH bodies are flat (no `set` / `unset` wrapper). Config properties must be wrapped inside a `config` key:
@@ -454,8 +456,8 @@ zinkee displays folders delete "Executive Dashboards"
 ### Creation flow
 
 1. Create the display
-2. Create context variables
-3. Create widgets with `variableMap` bindings
+2. Create context variables — optional; a display without variables shows every widget unfiltered
+3. Create widgets, binding them to the variables through `variableMap` if the display has any
 4. Set freeform layout positions
 
 ### Templates
@@ -469,7 +471,11 @@ zinkee displays folders delete "Executive Dashboards"
 ### Create a freeform display
 
 ```bash
-zinkee --json displays create --name "Project Dashboard" --template freeform
+zinkee --json displays create --name "Project Dashboard" \
+  --description "Project delivery overview" \
+  --template freeform
+zinkee --json displays update <display-uuid> --description "Updated overview"
+zinkee --json displays update <display-uuid> --description "" # Clear the description
 ```
 
 ### Add a context variable
@@ -486,11 +492,12 @@ Variables accept slugs for `--source-schema` and `--source-field`.
 
 ### Add widgets
 
-Every widget MUST include a `variableMap` that maps each display variable to a field in the widget's schema:
+A widget's `variableMap` maps display variables to fields in the widget's schema. It is optional: a
+widget that binds no variable shows its whole table, bounded only by its own filters.
 
 - **Same schema as variable**: bind to the same display field (e.g., `project-name`)
 - **Different schema**: bind to the ReferenceField pointing to the variable's schema (e.g., `task-project`)
-- **No filtering**: set to `null`
+- **No filtering**: set to `null`, or leave the variable out of the map
 
 ```bash
 # Table widget (--field accepts slugs)

package/dist/index.js

@@ -2611,6 +2611,20 @@ var specificExamples = {
     }
   ]),
   "schemas fields update": buildCommandExamples([
+    {
+      description: "Set the field description without changing its label or configuration.",
+      command: 'zinkee --json schemas fields update contacts contact-name --description "Primary name shown for the customer"',
+      raw: `{
+  "description": "Primary name shown for the customer"
+}`
+    },
+    {
+      description: "Clear the field description.",
+      command: 'zinkee --json schemas fields update contacts contact-name --description ""',
+      raw: `{
+  "description": ""
+}`
+    },
     {
       description: "Rename slug and label.",
       command: `zinkee --json schemas fields update contacts contact-name --label "Customer Full Name" --raw '{"slug":"customer-full-name"}'`,
@@ -3380,10 +3394,11 @@ var specificExamples = {
   ]),
   "displays create": buildCommandExamples([
     {
-      description: "Create a freeform display with an initial widget layout. Freeform layouts travel through --freeform-layouts.",
-      command: `zinkee --json displays create --name "Control Proyecto Freeform" --template freeform --freeform-layouts '{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}'`,
+      description: "Create a described freeform display with an initial widget layout. Freeform layouts travel through --freeform-layouts.",
+      command: `zinkee --json displays create --name "Control Proyecto Freeform" --description "Project delivery overview" --template freeform --freeform-layouts '{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}'`,
       raw: `{
   "name": "Control Proyecto Freeform",
+  "description": "Project delivery overview",
   "layout": {
     "template": "freeform",
     "freeformLayouts": {
@@ -5220,6 +5235,20 @@ var specificExamples = {
     }
   ]),
   "displays update": buildCommandExamples([
+    {
+      description: "Update only the display description.",
+      command: 'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --description "Sales pipeline overview"',
+      raw: `{
+  "description": "Sales pipeline overview"
+}`
+    },
+    {
+      description: "Clear the display description.",
+      command: 'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --description ""',
+      raw: `{
+  "description": ""
+}`
+    },
     {
       description: "Rename a display (patch of top-level metadata only).",
       command: 'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --name "Pipeline overview (renamed)"',
@@ -6516,8 +6545,21 @@ function buildSchemaFieldCreateExamples(type) {
   const flat = filteredDefinitions.flatMap(
     (definition) => definition.examplePayloads.map((example) => ({ definition, example }))
   );
-  return buildCommandExamples(
-    flat.map(({ example }, index) => {
+  const flagExamples = selectedDefinition === void 0 || selectedDefinition.key === "text" ? [
+    {
+      description: "Text field with a description.",
+      command: 'zinkee --json schemas fields create contacts --type text --slug customer-name --label "Customer Name" --description "Primary name shown for the customer"',
+      raw: `{
+  "type": "TextField",
+  "slug": "customer-name",
+  "label": "Customer Name",
+  "description": "Primary name shown for the customer"
+}`
+    }
+  ] : [];
+  return buildCommandExamples([
+    ...flagExamples,
+    ...flat.map(({ example }, index) => {
       const slug = typeof example.payload.slug === "string" ? example.payload.slug : "field";
       const command = `zinkee --json schemas fields create contacts --raw '${JSON.stringify(example.payload)}'`;
       if (index === 0) {
@@ -6536,7 +6578,7 @@ function buildSchemaFieldCreateExamples(type) {
         command
       };
     })
-  );
+  ]);
 }
 function getCommandExamples(commandName, filters = {}) {
   const examples = commandName === "schemas fields create" ? buildSchemaFieldCreateExamples(filters.type) : specificExamples[commandName] ?? fallbackExamples(commandName);
@@ -9647,7 +9689,7 @@ function registerDisplaysCommands(program, options = {}) {
     }
     printTable([{ id: data.id, name: data.name ?? "", layoutTemplate: data.layout?.template ?? "" }], ["id", "name", "layoutTemplate"], stdout);
   });
-  displays.command("create").description("Create a display").requiredOption("--name <name>", "display name").requiredOption("--template <template>", "layout template").option("--freeform-layouts <json>", "freeform layouts JSON").option("--freeform-layouts-file <path>", "freeform layouts JSON file").action(async function action(commandOptions) {
+  displays.command("create").description("Create a display").requiredOption("--name <name>", "display name").option("--description <text>", "display description").requiredOption("--template <template>", "layout template").option("--freeform-layouts <json>", "freeform layouts JSON").option("--freeform-layouts-file <path>", "freeform layouts JSON file").action(async function action(commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays create", readOnly, "write");
     const layout2 = { template: commandOptions.template };
@@ -9658,18 +9700,30 @@ function registerDisplaysCommands(program, options = {}) {
       "--freeform-layouts-file"
     );
     if (freeformLayouts !== void 0) layout2.freeformLayouts = freeformLayouts;
-    const data = await api.createDisplay({ name: commandOptions.name, layout: layout2 });
+    const data = await api.createDisplay({
+      name: commandOptions.name,
+      description: commandOptions.description,
+      layout: layout2
+    });
     if (json) {
       emitJson4(stdout, "displays create", data);
       return;
     }
     writeLine4(stdout, `Created display "${commandOptions.name}".`);
   });
-  displays.command("update").description("Update a display").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).option("--name <name>", "display name").action(async function action(display, commandOptions) {
+  displays.command("update").description("Update a display").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).option("--name <name>", "display name").option("--description <text>", 'display description (use "" to clear)').action(async function action(display, commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays update", readOnly, "write");
-    if (!commandOptions.name) throw new CliError("invalid_cli_usage", "Nothing to update.");
-    const data = await api.updateDisplay(display, { name: commandOptions.name });
+    if (commandOptions.name === void 0 && commandOptions.description === void 0) {
+      throw new CliError("invalid_cli_usage", "Nothing to update.");
+    }
+    if (commandOptions.name !== void 0 && commandOptions.name.trim().length === 0) {
+      throw new CliError("invalid_cli_usage", "Display name cannot be empty.");
+    }
+    const data = await api.updateDisplay(display, {
+      name: commandOptions.name,
+      description: commandOptions.description
+    });
     if (json) {
       emitJson4(stdout, "displays update", data);
       return;
@@ -12285,6 +12339,9 @@ function buildFieldCreateInput(options) {
   if (options.required !== void 0) {
     input.required = options.required;
   }
+  if (options.description !== void 0) {
+    input.description = options.description;
+  }
   applyFieldDefaultValue(input, options.default);
   if ("config" in input && isJsonObject7(input.config) && isEmptyObject6(input.config)) {
     delete input.config;
@@ -12328,6 +12385,9 @@ function buildFieldUpdateInput(currentType, options) {
   if (options.required !== void 0) {
     input.required = options.required;
   }
+  if (options.description !== void 0) {
+    input.description = options.description;
+  }
   applyFieldDefaultValue(input, options.default);
   return input;
 }
@@ -12511,7 +12571,7 @@ function registerSchemasCommands(program, options = {}) {
     }
     emitFieldsTable(stdout, [data]);
   });
-  fields.command("create").description(`Create a field in a schema.${buildSchemaFieldCreateHelpText()}`).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector10).option("--type <type>", `field type (${formatSchemaFieldTypes()})`).option("--slug <slug>", "field slug").option("--label <label>", "field label").option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload (see type-specific shapes in --help)").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, commandOptions) {
+  fields.command("create").description(`Create a field in a schema.${buildSchemaFieldCreateHelpText()}`).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector10).option("--type <type>", `field type (${formatSchemaFieldTypes()})`).option("--slug <slug>", "field slug").option("--label <label>", "field label").option("--description <text>", "field description").option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload (see type-specific shapes in --help)").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, commandOptions) {
     const { api, json, readOnly } = createSchemasApi(this, filePath);
     ensureWritable9("schemas fields create", readOnly, "write");
     const input = buildFieldCreateInput(commandOptions);
@@ -12528,7 +12588,7 @@ function registerSchemasCommands(program, options = {}) {
     }
     writeLine12(stdout, `Created field "${data.slug ?? commandOptions.slug}".`);
   });
-  fields.command("update").description("Update a field in a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector10).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector10).option("--label <label>", "field label").option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, field, commandOptions) {
+  fields.command("update").description("Update a field in a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector10).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector10).option("--label <label>", "field label").option("--description <text>", 'field description (use "" to clear)').option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, field, commandOptions) {
     const { api, json, readOnly } = createSchemasApi(this, filePath);
     ensureWritable9("schemas fields update", readOnly, "write");
     const resolvedSchema = await resolveSchemaSelector2(api, schema);
@@ -12542,7 +12602,7 @@ function registerSchemasCommands(program, options = {}) {
     if (isEmptyObject6(input)) {
       throw new CliError(
         "invalid_cli_usage",
-        'Provide at least one field update via "--label", "--required", "--raw", or "--raw-file".'
+        'Provide at least one field update via "--label", "--description", "--required", "--default", "--raw", or "--raw-file".'
       );
     }
     const data = await api.updateField(resolvedSchema, resolvedField, input);