@airtable/blocks 1.7.1 → 1.9.0-experimental-5565d56-20211029

package/CHANGELOG.md

@@ -9,9 +9,33 @@ Not every commit needs to result in a change to this file (e.g. docs and chore c
 commit that affects the code in a way that consumers might care about should include edits to the
 'Unreleased' section though. Breaking changes should be prefixed with `**BREAKING:**`.
 
-## [Unreleased](https://github.com/airtable/blocks/compare/@airtable/blocks@1.7.1...HEAD)
+## [Unreleased](https://github.com/airtable/blocks/compare/@airtable/blocks@1.9.0...HEAD)
 
-No changes.
+<<<<<<< seankeenan-at-fixTypoAndFormattingFromOpenPR
+
+-   # Fix typo in cursor.ts documentation - thanks @m2creates!
+-   Add new `calendarDay` icon (and micro variant)
+    > > > > > > > main
+
+## [1.9.0](https://github.com/airtable/blocks/compare/@airtable/blocks@1.8.0...@airtable/blocks@1.9.0) - 2021-09-15
+
+-   Update documentation for `FieldType.CHECKBOX` cell read & write types to be more accurate.
+-   Fetching field types & configs is now cached, making it more performant.
+-   Field descriptions can now be edited and specified when creating a new field:
+    -   Added `field.updateDescriptionAsync`.
+    -   Added optional `description` argument to `table.createFieldAsync`.
+    -   Added optional `description` property to `field` objects accepted by
+        `base.createTableAsync`.
+
+## [1.8.0](https://github.com/airtable/blocks/compare/@airtable/blocks@1.7.2...@airtable/blocks@1.8.0) - 2021-07-12
+
+-   Add `opts` argument to `Field.updateOptionsAsync` with `enableSelectFieldChoiceDeletion` opt.
+-   Add `prefersSingleRecordLink` to `field.options` for `MULTIPLE_RECORD_LINKS` type fields.
+-   Add new timeline icon (and micro variant).
+
+## [1.7.2](https://github.com/airtable/blocks/compare/@airtable/blocks@1.7.1...@airtable/blocks@1.7.2) - 2021-05-26
+
+-   Add `FieldType.EXTERNAL_SYNC_SOURCE`.
 
 ## [1.7.1](https://github.com/airtable/blocks/compare/@airtable/blocks@1.7.0...@airtable/blocks@1.7.1) - 2021-05-21
 

package/dist/cjs/error_utils.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.spawnError = spawnError;
 exports.invariant = invariant;
 exports.spawnUnknownSwitchCaseError = spawnUnknownSwitchCaseError;
+exports.spawnExhaustiveSwitchError = spawnExhaustiveSwitchError;
 exports.spawnAbstractMethodError = spawnAbstractMethodError;
 
 // If errorOriginFn is specified, all frames above and including the call to errorOriginFn
@@ -79,6 +80,22 @@ function spawnUnknownSwitchCaseError(valueDescription, providedValue, key) {
   var providedValueKeyString = providedValueKey !== null && providedValueKey !== undefined ? providedValueKey : 'null';
   return spawnErrorWithOriginOmittedFromStackTrace('Unknown value %s for %s', [providedValueKeyString, valueDescription], spawnUnknownSwitchCaseError);
 }
+/**
+ * Forces TypeScript to prove that calling this function is impossible at a
+ * type level by accepting `never`. In the unlikely case this function is
+ * called we infer a useful error message.
+ *
+ * @internal
+ */
+
+
+function spawnExhaustiveSwitchError(impossibleValue) {
+  if (impossibleValue === null) {
+    return spawnErrorWithOriginOmittedFromStackTrace('Unexpected null in exhaustive switch', undefined, spawnExhaustiveSwitchError);
+  } else {
+    return spawnErrorWithOriginOmittedFromStackTrace("Unexpected %s in exhaustive switch", [typeof impossibleValue], spawnExhaustiveSwitchError);
+  }
+}
 /**
  * @internal
  */

package/dist/cjs/models/base.js

@@ -435,8 +435,6 @@ function (_AbstractModel) {
       return table;
     }
     /**
-     * _Beta feature with unstable API. May have breaking changes before release._
-     *
      * Checks whether the current user has permission to create a table.
      *
      * Accepts partial input, in the same format as {@link createTableAsync}.
@@ -473,14 +471,13 @@ function (_AbstractModel) {
               type: field.type
             }, field.options ? {
               options: field.options
-            } : null) : undefined
+            } : null) : undefined,
+            description: field.description
           };
         })
       });
     }
     /**
-     * _Beta feature with unstable API. May have breaking changes before release._
-     *
      * An alias for `checkPermissionsForCreateTable(name, fields).hasPermission`.
      *
      * Checks whether the current user has permission to create a table.
@@ -506,12 +503,11 @@ function (_AbstractModel) {
       return this.checkPermissionsForCreateTable(name, fields).hasPermission;
     }
     /**
-     * _Beta feature with unstable API. May have breaking changes before release._
-     *
      * Creates a new table.
      *
      * Throws an error if the user does not have permission to create a table, if an invalid
-     * table name is provided, or if invalid fields are provided (invalid name, type or options).
+     * table name is provided, or if invalid fields are provided (invalid name, type, options or
+     * description).
      *
      * Refer to {@link FieldType} for supported field types, the write format for field options, and
      * other specifics for certain field types.
@@ -528,7 +524,10 @@ function (_AbstractModel) {
      * table in your app.
      *
      * @param name name for the table. must be case-insensitive unique
-     * @param fields array of fields to create in the table: see below for details.
+     * @param fields array of fields to create in the table: see below for an example. `name` and
+     * `type` must be specified for all fields, while `options` is only required for fields that
+     * have field options. `description` is optional and will be `''` if not specified or if
+     * specified as `null`.
      *
      * @example
      * ```js
@@ -536,7 +535,7 @@ function (_AbstractModel) {
      *     const name = 'My new table';
      *     const fields = [
      *         // Name will be the primary field of the table.
-     *         {name: 'Name', type: FieldType.SINGLE_LINE_TEXT},
+     *         {name: 'Name', type: FieldType.SINGLE_LINE_TEXT, description: 'This is the primary field'},
      *         {name: 'Notes', type: FieldType.RICH_TEXT},
      *         {name: 'Attachments', type: FieldType.MULTIPLE_ATTACHMENTS},
      *         {name: 'Number', type: FieldType.NUMBER, options: {
@@ -572,13 +571,19 @@ function (_AbstractModel) {
                 type: _mutations.MutationTypes.CREATE_SINGLE_TABLE,
                 name,
                 fields: fields.map(field => {
+                  var _field$description;
+
                   return {
                     name: field.name,
                     config: _objectSpread({
                       type: field.type
                     }, field.options ? {
                       options: field.options
-                    } : null)
+                    } : null),
+                    // Coerce undefined to null so that only old SDKs pass "undefined" for description
+                    // '' is permitted, as we already set empty descriptions to '' when editing descriptions
+                    // from the UI
+                    description: (_field$description = field.description) !== null && _field$description !== void 0 ? _field$description : null
                   };
                 })
               }));

package/dist/cjs/models/cursor.js

@@ -89,6 +89,7 @@ var WatchableCursorKeys = Object.freeze({
  *      return (
  *          <div>
  *              Active table: {cursor.activeTableId}
+ *              <br />
  *              Active view: {cursor.activeViewId}
  *          </div>
  *      );
@@ -109,6 +110,7 @@ var WatchableCursorKeys = Object.freeze({
  *      return (
  *          <div>
  *              Selected records: {cursor.selectedRecordIds.join(', ')}
+ *              <br />
  *              Selected fields: {cursor.selectedFieldIds.join(', ')}
  *          </div>
  *      );

package/dist/cjs/models/field.js

@@ -109,7 +109,9 @@ function (_AbstractModel) {
     (0, _classCallCheck2.default)(this, Field);
     _this = (0, _possibleConstructorReturn2.default)(this, (0, _getPrototypeOf2.default)(Field).call(this, sdk, fieldId));
     (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "_parentTable", void 0);
+    (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "_cachedFieldTypeConfigOrNull", void 0);
     _this._parentTable = parentTable;
+    _this._cachedFieldTypeConfigOrNull = null;
     return _this;
   }
   /**
@@ -118,16 +120,50 @@ function (_AbstractModel) {
 
 
   (0, _createClass2.default)(Field, [{
-    key: "checkPermissionsForUpdateOptions",
+    key: "_getCachedConfigFromFieldTypeProvider",
+    // We use a cached response from FieldTypeProvider because getting the config can
+    // be an expensive operation. In particular when fieldConfigs are extremely large
+    // (eg: Select fields with lots of select options)
+    value: function _getCachedConfigFromFieldTypeProvider() {
+      if (this._cachedFieldTypeConfigOrNull !== null) {
+        return this._cachedFieldTypeConfigOrNull;
+      }
 
+      var airtableInterface = this._sdk.__airtableInterface;
+      var appInterface = this._sdk.__appInterface;
+      this._cachedFieldTypeConfigOrNull = airtableInterface.fieldTypeProvider.getConfig(appInterface, this._data, this.parentTable.__getFieldNamesById());
+      return this._cachedFieldTypeConfigOrNull;
+    }
+  }, {
+    key: "_clearCachedConfig",
+    value: function _clearCachedConfig() {
+      this._cachedFieldTypeConfigOrNull = null;
+    }
     /**
-     * _Beta feature with unstable API. May have breaking changes before release._
+     * The type and options of the field to make type narrowing `FieldOptions` easier.
      *
+     * @see {@link FieldConfig}
+     * @example
+     * const fieldConfig = field.config;
+     * if (fieldConfig.type === FieldType.SINGLE_SELECT) {
+     *     return fieldConfig.options.choices;
+     * } else if (fieldConfig.type === FieldType.MULTIPLE_LOOKUP_VALUES && fieldConfig.options.isValid) {
+     *     if (fieldConfig.options.result.type === FieldType.SINGLE_SELECT) {
+     *         return fieldConfig.options.result.options.choices;
+     *     }
+     * }
+     * return DEFAULT_CHOICES;
+     */
+
+  }, {
+    key: "checkPermissionsForUpdateOptions",
+
+    /**
      * Checks whether the current user has permission to perform the given options update.
      *
      * Accepts partial input, in the same format as {@link updateOptionsAsync}.
      *
-     * Returns `{hasPermission: true}` if the current user can update the specified record,
+     * Returns `{hasPermission: true}` if the current user can update the specified field,
      * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
      * used to display an error message to the user.
      *
@@ -154,8 +190,6 @@ function (_AbstractModel) {
       });
     }
     /**
-     * _Beta feature with unstable API. May have breaking changes before release._
-     *
      * An alias for `checkPermissionsForUpdateOptions(options).hasPermission`.
      *
      * Checks whether the current user has permission to perform the options update.
@@ -180,8 +214,6 @@ function (_AbstractModel) {
       return this.checkPermissionsForUpdateOptions(options).hasPermission;
     }
     /**
-     * _Beta feature with unstable API. May have breaking changes before release._
-     *
      * Updates the options for this field.
      *
      * Throws an error if the user does not have permission to update the field, if invalid
@@ -195,7 +227,11 @@ function (_AbstractModel) {
      * **not** applied optimistically locally. You must `await` the returned promise before
      * relying on the change in your app.
      *
+     * Optionally, you can pass an `opts` object as the second argument. See {@link UpdateFieldOptionsOpts}
+     * for available options.
+     *
      * @param options new options for the field
+     * @param opts optional options to affect the behavior of the update
      *
      * @example
      * ```js
@@ -217,11 +253,14 @@ function (_AbstractModel) {
   }, {
     key: "updateOptionsAsync",
     value: function updateOptionsAsync(options) {
+      var opts,
+          _args = arguments;
       return _regenerator.default.async(function updateOptionsAsync$(_context) {
         while (1) {
           switch (_context.prev = _context.next) {
             case 0:
-              _context.next = 2;
+              opts = _args.length > 1 && _args[1] !== undefined ? _args[1] : {};
+              _context.next = 3;
               return _regenerator.default.awrap(this._sdk.__mutations.applyMutationAsync({
                 type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_CONFIG,
                 tableId: this.parentTable.id,
@@ -229,16 +268,115 @@ function (_AbstractModel) {
                 config: {
                   type: this.type,
                   options: options
-                }
+                },
+                opts
               }));
 
-            case 2:
+            case 3:
             case "end":
               return _context.stop();
           }
         }
       }, null, this);
     }
+    /**
+     * Checks whether the current user has permission to perform the given description update.
+     *
+     * Accepts partial input, in the same format as {@link updateDescriptionAsync}.
+     *
+     * Returns `{hasPermission: true}` if the current user can update the specified field,
+     * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+     * used to display an error message to the user.
+     *
+     * @param description new description for the field
+     *
+     * @example
+     * ```js
+     * const updateFieldCheckResult = field.checkPermissionsForUpdateDescription();
+     *
+     * if (!updateFieldCheckResult.hasPermission) {
+     *     alert(updateFieldCheckResult.reasonDisplayString);
+     * }
+     * ```
+     */
+
+  }, {
+    key: "checkPermissionsForUpdateDescription",
+    value: function checkPermissionsForUpdateDescription(description) {
+      return this._sdk.__mutations.checkPermissionsForMutation({
+        type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_DESCRIPTION,
+        tableId: this.parentTable.id,
+        id: this.id,
+        description
+      });
+    }
+    /**
+     * An alias for `checkPermissionsForUpdateDescription(options).hasPermission`.
+     *
+     * Checks whether the current user has permission to perform the description update.
+     *
+     * Accepts partial input, in the same format as {@link updateDescriptionAsync}.
+     *
+     * @param description new description for the field
+     *
+     * @example
+     * ```js
+     * const canUpdateField = field.hasPermissionToUpdateDescription();
+     *
+     * if (!canUpdateField) {
+     *     alert('not allowed!');
+     * }
+     * ```
+     */
+
+  }, {
+    key: "hasPermissionToUpdateDescription",
+    value: function hasPermissionToUpdateDescription(description) {
+      return this.checkPermissionsForUpdateDescription(description).hasPermission;
+    }
+    /**
+     * Updates the description for this field.
+     *
+     * To remove an existing description, pass `''` as the new description.
+     * `null` is also accepted and will be coerced to `''` for consistency with field creation.
+     *
+     * Throws an error if the user does not have permission to update the field, or if an invalid
+     * description is provided.
+     *
+     * This action is asynchronous. Unlike updates to cell values, updates to field descriptions are
+     * **not** applied optimistically locally. You must `await` the returned promise before
+     * relying on the change in your app.
+     *
+     * @param description new description for the field
+     *
+     * @example
+     * ```js
+     * await myTextField.updateDescriptionAsync('This is a text field');
+     * ```
+     */
+
+  }, {
+    key: "updateDescriptionAsync",
+    value: function updateDescriptionAsync(description) {
+      return _regenerator.default.async(function updateDescriptionAsync$(_context2) {
+        while (1) {
+          switch (_context2.prev = _context2.next) {
+            case 0:
+              _context2.next = 2;
+              return _regenerator.default.awrap(this._sdk.__mutations.applyMutationAsync({
+                type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_DESCRIPTION,
+                tableId: this.parentTable.id,
+                id: this.id,
+                description
+              }));
+
+            case 2:
+            case "end":
+              return _context2.stop();
+          }
+        }
+      }, null, this);
+    }
     /**
      * `true` if this field is computed, `false` otherwise. A field is
      * "computed" if it's value is not set by user input (e.g. autoNumber, formula,
@@ -327,6 +465,9 @@ function (_AbstractModel) {
   }, {
     key: "__triggerOnChangeForDirtyPaths",
     value: function __triggerOnChangeForDirtyPaths(dirtyPaths) {
+      // Always clear the cached config when anything on the field data model changes
+      this._clearCachedConfig();
+
       if (dirtyPaths.name) {
         this._onChange(WatchableFieldKeys.name);
       }
@@ -400,11 +541,8 @@ function (_AbstractModel) {
   }, {
     key: "type",
     get: function get() {
-      var airtableInterface = this._sdk.__airtableInterface;
-      var appInterface = this._sdk.__appInterface;
-
-      var _airtableInterface$fi = airtableInterface.fieldTypeProvider.getConfig(appInterface, this._data, this.parentTable.__getFieldNamesById()),
-          type = _airtableInterface$fi.type; // We intend to switch from "lookup" to "multipleLookupValues", but need to support both
+      var _this$_getCachedConfi = this._getCachedConfigFromFieldTypeProvider(),
+          type = _this$_getCachedConfi.type; // We intend to switch from "lookup" to "multipleLookupValues", but need to support both
       // until the transition is complete. See <https://airtable.quip.com/VxaMAmAfUscs> for more.
       // @ts-ignore
 
@@ -435,31 +573,14 @@ function (_AbstractModel) {
   }, {
     key: "options",
     get: function get() {
-      var airtableInterface = this._sdk.__airtableInterface;
-      var appInterface = this._sdk.__appInterface;
-
-      var _airtableInterface$fi2 = airtableInterface.fieldTypeProvider.getConfig(appInterface, this._data, this.parentTable.__getFieldNamesById()),
-          options = _airtableInterface$fi2.options; // TODO(emma): can we remove this cloneDeep?
+      var _this$_getCachedConfi2 = this._getCachedConfigFromFieldTypeProvider(),
+          options = _this$_getCachedConfi2.options; // TODO: In the next breaking release freeze (inside of the cache) and replace
+      // FieldOptions with readonly<FieldOptions>.
+      // Today this is required because we re-use the fieldTypeProvider.getConfig response.
 
 
       return options ? (0, _private_utils.cloneDeep)(options) : null;
     }
-    /**
-     * The type and options of the field to make type narrowing `FieldOptions` easier.
-     *
-     * @see {@link FieldConfig}
-     * @example
-     * const fieldConfig = field.config;
-     * if (fieldConfig.type === FieldType.SINGLE_SELECT) {
-     *     return fieldConfig.options.choices;
-     * } else if (fieldConfig.type === FieldType.MULTIPLE_LOOKUP_VALUES && fieldConfig.options.isValid) {
-     *     if (fieldConfig.options.result.type === FieldType.SINGLE_SELECT) {
-     *         return fieldConfig.options.result.options.choices;
-     *     }
-     * }
-     * return DEFAULT_CHOICES;
-     */
-
   }, {
     key: "config",
     get: function get() {

package/dist/cjs/models/grouped_record_query_result.js

@@ -245,19 +245,13 @@ function (_RecordQueryResult) {
         while (1) {
           switch (_context2.prev = _context2.next) {
             case 0:
-              this._parentQueryResult.__groupedRecordQueryResultPool.registerObjectForReuseStrong(this); // Ensure we invalidate our memoized computed recordIds whenever a relevant hook changes
-              // TODO: (SeanKeenan) At the moment this should never be relevant, because groups are recreated
-              // anytime the groups change - but this is how it should work once groups persist AND
-              // watching recordIds only changes if records in this group change.
-              // In the meantime this does ensure that a deleted GroupedRecordQuery with stale recordIds
-              // doesn't return the cached array.
+              // TODO: This entire class assumes it is torn down and re-created by the parent whenever
+              // a change to the group is made.
+              this._parentQueryResult.__groupedRecordQueryResultPool.registerObjectForReuseStrong(this);
 
-
-              this.watch(['recordIds', 'groups', 'groupLevels'], this._invalidateComputedRecordIds, this);
-              this.watch(['recordIds'], this._invalidateRecordIdsSet, this);
               return _context2.abrupt("return", this._getChangedKeysOnLoad());
 
-            case 4:
+            case 2:
             case "end":
               return _context2.stop();
           }
@@ -269,10 +263,7 @@ function (_RecordQueryResult) {
   }, {
     key: "_unloadData",
     value: function _unloadData() {
-      // Ensure we invalidate our memoized computed recordIds whenever a relevant hook changes
-      this.unwatch(['recordIds', 'groups', 'groupLevels'], this._invalidateComputedRecordIds, this);
-      this.unwatch(['recordIds'], this._invalidateRecordIdsSet, this); // Invalidate both of the caches, as this object can no longer be accessed
-
+      // Invalidate both of the caches, as this object can no longer be accessed
       this._invalidateComputedRecordIds();
 
       this._invalidateRecordIdsSet();