add a description property to column mapping for custom widgets (#255)

app/client/models/ColumnToMap.ts

@@ -9,6 +9,8 @@ export class ColumnToMapImpl implements Required<ColumnToMap> {
   public name: string;
   // Label to show instead of the name.
   public title: string;
+  // Human description of the column.
+  public description: string;
   // If column is optional (used only on the UI).
   public optional: boolean;
   // Type of the column that widget expects.
@@ -20,6 +22,7 @@ export class ColumnToMapImpl implements Required<ColumnToMap> {
   constructor(def: string|ColumnToMap) {
     this.name = typeof def === 'string' ? def : def.name;
     this.title = typeof def === 'string' ? def : (def.title ?? def.name);
+    this.description = typeof def === 'string' ? '' : (def.description ?? '');
     this.optional = typeof def === 'string' ? false : (def.optional ?? false);
     this.type = typeof def === 'string' ? 'Any' : (def.type ?? 'Any');
     this.typeDesc = String(UserType.typeDefs[this.type]?.label ?? "any").toLowerCase();

app/client/ui/CustomSectionConfig.ts

@@ -4,7 +4,7 @@ import * as kf from 'app/client/lib/koForm';
 import {ColumnToMapImpl} from 'app/client/models/ColumnToMap';
 import {ColumnRec, ViewSectionRec} from 'app/client/models/DocModel';
 import {reportError} from 'app/client/models/errors';
-import {cssLabel, cssRow, cssSeparator} from 'app/client/ui/RightPanelStyles';
+import {cssHelp, cssLabel, cssRow, cssSeparator} from 'app/client/ui/RightPanelStyles';
 import {cssDragRow, cssFieldEntry, cssFieldLabel} from 'app/client/ui/VisibleFieldsConfig';
 import {basicButton, primaryButton, textButton} from 'app/client/ui2018/buttons';
 import {colors, vars} from 'app/client/ui2018/cssVars';
@@ -61,6 +61,10 @@ class ColumnPicker extends Disposable {
         this._column.optional ? cssSubLabel(" (optional)") : null,
         testId('label-for-' + this._column.name),
       ),
+      this._column.description ? cssHelp(
+        this._column.description,
+        testId('help-for-' + this._column.name),
+      ) : null,
       cssRow(
         select(
           properValue,

app/client/ui/RightPanelStyles.ts

@@ -13,6 +13,12 @@ export const cssLabel = styled('div', `
   font-size: ${vars.xsmallFontSize};
 `);
 
+export const cssHelp = styled('div', `
+  margin: -8px 16px 12px 16px;
+  font-style: italic;
+  font-size: ${vars.xsmallFontSize};
+`);
+
 export const cssRow = styled('div', `
   display: flex;
   margin: 8px 16px;

app/plugin/CustomSectionAPI.ts

@@ -11,6 +11,10 @@ export interface ColumnToMap {
    * Title or short description of a column (used as a label in section mapping).
    */
   title?: string|null,
+  /**
+   * Optional long description of a column (used as a help text in section mapping).
+   */
+  description?: string|null,
   /**
    * Column type, by default ANY.
    */