@airtable/blocks 0.0.0-experimental-f52bc4e5e-20250709 → 0.0.0-experimental-3649c7162-20250904

package/dist/esm/base/models/cursor.js

@@ -0,0 +1,305 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _private_utils = require("../../shared/private_utils");
+var _error_utils = require("../../shared/error_utils");
+var _abstract_model_with_async_data = _interopRequireDefault(require("./abstract_model_with_async_data"));
+var _table = _interopRequireDefault(require("./table"));
+var _view = _interopRequireDefault(require("./view"));
+var _record = _interopRequireDefault(require("./record"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: Cursor */ /** */
+
+const WatchableCursorKeys = Object.freeze({
+  selectedRecordIds: 'selectedRecordIds',
+  selectedFieldIds: 'selectedFieldIds',
+  activeTableId: 'activeTableId',
+  activeViewId: 'activeViewId',
+  isDataLoaded: 'isDataLoaded'
+});
+
+/**
+ * Watchable keys in {@link Cursor}.
+ * - `selectedRecordIds`
+ * - `selectedFieldIds`
+ * - `activeTableId`
+ * - `activeViewId`
+ * - `isDataLoaded`
+ */
+
+/** @hidden */
+
+// NOTE: cursor is an AbstractModel because it includes loadable data.
+/**
+ * Model class containing information about the state of the user's current interactions in
+ * Airtable - specifically, their active table, active view, selected records and selected fields.
+ * Also allows you to set the active table and active view.
+ *
+ * Selected records and fields are not loaded by default and the cursor must be loaded with
+ * {@link useLoadable} to access them.
+ *
+ * ```js
+ * import {useCursor, useWatchable} from '@airtable/blocks/base/ui';
+ *
+ *  function ActiveTableAndView() {
+ *      const cursor = useCursor();
+ *
+ *      return (
+ *          <div>
+ *              Active table: {cursor.activeTableId}
+ *              <br />
+ *              Active view: {cursor.activeViewId}
+ *          </div>
+ *      );
+ *  }
+ * ```
+ *
+ * ```js
+ * import {useCursor, useLoadable, useWatchable} from '@airtable/blocks/base/ui';
+ *
+ *  function SelectedRecordAndFieldIds() {
+ *      const cursor = useCursor();
+ *      // load selected records and fields
+ *      useLoadable(cursor);
+ *
+ *      // re-render whenever the list of selected records or fields changes
+ *      useWatchable(cursor, ['selectedRecordIds', 'selectedFieldIds']);
+ *
+ *      return (
+ *          <div>
+ *              Selected records: {cursor.selectedRecordIds.join(', ')}
+ *              <br />
+ *              Selected fields: {cursor.selectedFieldIds.join(', ')}
+ *          </div>
+ *      );
+ *  }
+ * ```
+ *
+ * @docsPath models/Cursor
+ */
+class Cursor extends _abstract_model_with_async_data.default {
+  /** @internal */
+  static _className = 'Cursor';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableCursorKeys, key);
+  }
+  /** @internal */
+  static _shouldLoadDataForKey(key) {
+    return true;
+  }
+  /** @internal */
+
+  /** @internal */
+  constructor(sdk) {
+    super(sdk, 'cursor');
+    const baseData = sdk.__airtableInterface.sdkInitData.baseData;
+    const selectedRecordIdSet = baseData.cursorData?.selectedRecordIdSet ?? null;
+    const selectedFieldIdSet = baseData.cursorData?.selectedFieldIdSet ?? null;
+    const activeTableId = baseData.activeTableId;
+    const activeTable = activeTableId ? baseData.tablesById[activeTableId] : null;
+    const activeViewId = activeTable?.activeViewId ?? null;
+    this._cursorData = {
+      selectedRecordIdSet,
+      selectedFieldIdSet,
+      activeTableId,
+      activeViewId
+    };
+    Object.seal(this);
+  }
+
+  /**
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    return this._cursorData;
+  }
+  /**
+   * @internal
+   */
+  _onChangeIsDataLoaded() {
+    this._onChange(WatchableCursorKeys.isDataLoaded);
+  }
+  /**
+   * @internal
+   */
+  async _loadDataAsync() {
+    const cursorData = await this._sdk.__airtableInterface.fetchAndSubscribeToCursorDataAsync();
+    this._cursorData.selectedRecordIdSet = cursorData.selectedRecordIdSet;
+    this._cursorData.selectedFieldIdSet = cursorData.selectedFieldIdSet;
+    return [WatchableCursorKeys.selectedRecordIds, WatchableCursorKeys.selectedFieldIds];
+  }
+  /**
+   * @internal
+   */
+  _unloadData() {
+    this._sdk.__airtableInterface.unsubscribeFromCursorData();
+    this._cursorData.selectedRecordIdSet = null;
+    this._cursorData.selectedFieldIdSet = null;
+  }
+  /**
+   * The record IDs of all currently selected records, or an empty array if no records are selected.
+   *
+   * Not loaded by default. You must load cursor data with `useLoadable(cursor)` (recommended) or
+   * `cursor.loadDataAsync()` before use.
+   *
+   * Can be watched.
+   */
+  get selectedRecordIds() {
+    const {
+      selectedRecordIdSet
+    } = this._data;
+    (0, _error_utils.invariant)(selectedRecordIdSet, 'Cursor data is not loaded');
+    const selectedRecordIds = Object.keys(selectedRecordIdSet);
+    return selectedRecordIds;
+  }
+  /**
+   * The field IDs of all currently selected fields, or an empty array if no fields are selected.
+   *
+   * Not loaded by default: you must load cursor data with `useLoadable(cursor)` (recommended) or
+   * `cursor.loadDataAsync()` before use.
+   *
+   * Can be watched.
+   */
+  get selectedFieldIds() {
+    const {
+      selectedFieldIdSet
+    } = this._data;
+    (0, _error_utils.invariant)(selectedFieldIdSet, 'Cursor data is not loaded');
+    const selectedRecordIds = Object.keys(selectedFieldIdSet);
+    return selectedRecordIds;
+  }
+  /**
+   * Checks whether a given record is selected.
+   *
+   * Selected records are not loaded by default. You must load cursor data with
+   * `useLoadable(cursor)` (recommended) or `cursor.loadDataAsync()` before use.
+   *
+   * @param recordOrRecordId The record or record ID to check for.
+   */
+  isRecordSelected(recordOrRecordId) {
+    const {
+      selectedRecordIdSet
+    } = this._data;
+    (0, _error_utils.invariant)(selectedRecordIdSet, 'Cursor data is not loaded');
+    let recordId;
+    if (recordOrRecordId instanceof _record.default) {
+      recordId = recordOrRecordId.id;
+    } else {
+      recordId = recordOrRecordId;
+    }
+    return !!selectedRecordIdSet[recordId];
+  }
+  /**
+   * The currently active table ID. Can be null when the active table has changed and is not yet
+   * loaded, and can also refer to a table that is not yet loaded.
+   *
+   * When fetching the {@link Table}, use `base.getTableByIdIfExists(cursor.activeTableId)` and
+   * check the return value is not `null` to be resilient to those cases.
+   *
+   * Can be watched.
+   */
+  get activeTableId() {
+    return this._data.activeTableId;
+  }
+  /**
+   * The currently active view ID. This will always be a view belonging to `activeTableId`. Can be
+   * null when the active view has changed and is not yet loaded, and can also refer to a view
+   * that is not yet loaded.
+   *
+   * When fetching the {@link View}, use `table.getViewByIdIfExists(cursor.activeViewId)` and
+   * check the return value is not `null` to be resilient to those cases.
+   *
+   * Can be watched.
+   */
+  get activeViewId() {
+    return this._data.activeViewId;
+  }
+  /**
+   * Sets the specified table to active in the Airtable UI. If the extension installation or extensions pane
+   * is fullscreen, fullscreen mode will be exited.
+   *
+   * @param tableOrTableId The target table or table ID to set as active in the Airtable main page.
+   */
+  setActiveTable(tableOrTableId) {
+    const tableId = tableOrTableId instanceof _table.default ? tableOrTableId.id : tableOrTableId;
+    this._sdk.__airtableInterface.setActiveViewOrTable(tableId);
+  }
+  /**
+   * Sets the specified view (and corresponding table) to active in the Airtable UI. If the extension
+   * installation or extensions pane is fullscreen, fullscreen mode will be exited.
+   *
+   * @param tableOrTableId The table or table ID that the target view belongs to.
+   * @param viewOrViewId The target view or view ID to set as active in the Airtable main page.
+   */
+  setActiveView(tableOrTableId, viewOrViewId) {
+    const tableId = tableOrTableId instanceof _table.default ? tableOrTableId.id : tableOrTableId;
+    const viewId = viewOrViewId instanceof _view.default ? viewOrViewId.id : viewOrViewId;
+    this._sdk.__airtableInterface.setActiveViewOrTable(tableId, viewId);
+  }
+
+  /**
+   * @internal
+   */
+  __applyChangesWithoutTriggeringEvents(changes) {
+    const changedKeys = {
+      [WatchableCursorKeys.selectedRecordIds]: false,
+      [WatchableCursorKeys.activeTableId]: false,
+      [WatchableCursorKeys.activeViewId]: false
+    };
+    for (const {
+      path,
+      value
+    } of changes) {
+      if (path[0] === 'cursorData') {
+        switch (path[1]) {
+          case 'selectedRecordIdSet':
+            {
+              (0, _error_utils.invariant)(path.length === 2, 'cannot set within selectedRecordIdSet');
+              this._cursorData.selectedRecordIdSet = value;
+              changedKeys[WatchableCursorKeys.selectedRecordIds] = true;
+              break;
+            }
+          case 'selectedFieldIdSet':
+            {
+              (0, _error_utils.invariant)(path.length === 2, 'cannot set within selectedFieldIdSet');
+              this._cursorData.selectedFieldIdSet = value;
+              changedKeys[WatchableCursorKeys.selectedFieldIds] = true;
+              break;
+            }
+          default:
+          // No-op for future unknown paths.
+        }
+      }
+      if (path[0] === 'activeTableId') {
+        (0, _error_utils.invariant)(value === null || typeof value === 'string', 'activeTableId must be string or null');
+        this._cursorData.activeTableId = value;
+        changedKeys[WatchableCursorKeys.activeTableId] = true;
+        if (value === null) {
+          this._cursorData.activeViewId = null;
+          changedKeys[WatchableCursorKeys.activeViewId] = true;
+        }
+      }
+      if (path[0] === 'tablesById' && path[1] === this.activeTableId && path[2] === 'activeViewId') {
+        (0, _error_utils.invariant)(value === null || typeof value === 'string', 'activeTableId must be string or null');
+        this._cursorData.activeViewId = value;
+        changedKeys[WatchableCursorKeys.activeViewId] = true;
+      }
+    }
+    return changedKeys;
+  }
+  /**
+   * @internal
+   */
+  __triggerOnChangeForChangedKeys(changedKeys) {
+    for (const [key, didChange] of (0, _private_utils.entries)(changedKeys)) {
+      if (didChange) {
+        this._onChange(key);
+      }
+    }
+  }
+}
+var _default = exports.default = Cursor;

package/dist/esm/base/models/field.js

@@ -0,0 +1,338 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _field_core = require("../../shared/models/field_core");
+var _mutations = require("../types/mutations");
+var _private_utils = require("../../shared/private_utils");
+/** @module @airtable/blocks/models: Field */ /** */
+
+/**
+ * Model class representing a field in a table.
+ *
+ * @example
+ * ```js
+ * import {base} from '@airtable/blocks/base';
+ *
+ * const table = base.getTableByName('Table 1');
+ * const field = table.getFieldByName('Name');
+ * console.log('The type of this field is', field.type);
+ * ```
+ * @docsPath models/Field
+ */
+class Field extends _field_core.FieldCore {
+  /** @internal */
+  static _className = 'Field';
+
+  // The following method is untested because its implementation resists
+  // testing and because it is expected to be redesigned.
+  // istanbul ignore next
+  /**
+   * A list of available aggregators given this field's configuration.
+   *
+   * @example
+   * ```js
+   * const fieldAggregators = myField.availableAggregators;
+   * ```
+   */
+  get availableAggregators() {
+    const airtableInterface = this._sdk.__airtableInterface;
+    const availableAggregatorKeysSet = new Set(airtableInterface.aggregators.getAvailableAggregatorKeysForField(this._data));
+    const base = this.parentTable.parentBase;
+    return (0, _private_utils.values)(base.aggregators).filter(aggregator => {
+      return availableAggregatorKeysSet.has(aggregator.key);
+    });
+  }
+  // The following method is untested because its implementation resists
+  // testing and because it is expected to be redesigned.
+  // istanbul ignore next
+  /**
+   * Checks if the given aggregator is available for this field.
+   *
+   * @param aggregator The aggregator object or aggregator key.
+   * @example
+   * ```js
+   * import {base} from '@airtable/blocks/base';
+   *
+   * const aggregator = base.aggregators.totalAttachmentSize;
+   *
+   * // Using an aggregator object
+   * console.log(myAttachmentField.isAggregatorAvailable(aggregator));
+   * // => true
+   *
+   * // Using an aggregator key
+   * console.log(myTextField.isAggregatorAvailable('totalAttachmentSize'));
+   * // => false
+   * ```
+   */
+  isAggregatorAvailable(aggregator) {
+    const aggregatorKey = typeof aggregator === 'string' ? aggregator : aggregator.key;
+    const airtableInterface = this._sdk.__airtableInterface;
+    const availableAggregatorKeys = airtableInterface.aggregators.getAvailableAggregatorKeysForField(this._data);
+    return availableAggregatorKeys.some(key => key === aggregatorKey);
+  }
+
+  /**
+   * Checks whether the current user has permission to perform the given name update.
+   *
+   * Accepts partial input, in the same format as {@link updateNameAsync}.
+   *
+   * 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 name new name for the field
+   *
+   * @example
+   * ```js
+   * const updateFieldCheckResult = field.checkPermissionsForUpdateName();
+   *
+   * if (!updateFieldCheckResult.hasPermission) {
+   *     alert(updateFieldCheckResult.reasonDisplayString);
+   * }
+   * ```
+   */
+  checkPermissionsForUpdateName(name) {
+    return this._sdk.__mutations.checkPermissionsForMutation({
+      type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_NAME,
+      tableId: this.parentTable.id,
+      id: this.id,
+      name
+    });
+  }
+
+  /**
+   * An alias for `checkPermissionsForUpdateName(options).hasPermission`.
+   *
+   * Checks whether the current user has permission to perform the name update.
+   *
+   * Accepts partial input, in the same format as {@link updateNameAsync}.
+   *
+   * @param name new name for the field
+   *
+   * @example
+   * ```js
+   * const canUpdateField = field.hasPermissionToUpdateName();
+   *
+   * if (!canUpdateField) {
+   *     alert('not allowed!');
+   * }
+   * ```
+   */
+  hasPermissionToUpdateName(name) {
+    return this.checkPermissionsForUpdateName(name).hasPermission;
+  }
+
+  /**
+   * Updates the name for this field.
+   *
+   * Throws an error if the user does not have permission to update the field, or if an invalid
+   * name is provided.
+   *
+   * This action is asynchronous. Unlike updates to cell values, updates to field name are
+   * **not** applied optimistically locally. You must `await` the returned promise before
+   * relying on the change in your extension.
+   *
+   * @param name new name for the field
+   *
+   * @example
+   * ```js
+   * await myTextField.updateNameAsync('My New Name');
+   * ```
+   */
+  async updateNameAsync(name) {
+    await this._sdk.__mutations.applyMutationAsync({
+      type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_NAME,
+      tableId: this.parentTable.id,
+      id: this.id,
+      name
+    });
+  }
+
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  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!');
+   * }
+   * ```
+   */
+  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 extension.
+   *
+   * @param description new description for the field
+   *
+   * @example
+   * ```js
+   * await myTextField.updateDescriptionAsync('This is a text field');
+   * ```
+   */
+  async updateDescriptionAsync(description) {
+    await this._sdk.__mutations.applyMutationAsync({
+      type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_DESCRIPTION,
+      tableId: this.parentTable.id,
+      id: this.id,
+      description
+    });
+  }
+
+  /**
+   * 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 field,
+   * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+   * used to display an error message to the user.
+   *
+   * @param options new options for the field
+   *
+   * @example
+   * ```js
+   * const updateFieldCheckResult = field.checkPermissionsForUpdateOptions();
+   *
+   * if (!updateFieldCheckResult.hasPermission) {
+   *     alert(updateFieldCheckResult.reasonDisplayString);
+   * }
+   * ```
+   */
+  checkPermissionsForUpdateOptions(options) {
+    return this._sdk.__mutations.checkPermissionsForMutation({
+      type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_CONFIG,
+      tableId: this.parentTable.id,
+      id: this.id,
+      config: {
+        type: this.type,
+        options: options
+      }
+    });
+  }
+
+  /**
+   * An alias for `checkPermissionsForUpdateOptions(options).hasPermission`.
+   *
+   * Checks whether the current user has permission to perform the options update.
+   *
+   * Accepts partial input, in the same format as {@link updateOptionsAsync}.
+   *
+   * @param options new options for the field
+   *
+   * @example
+   * ```js
+   * const canUpdateField = field.hasPermissionToUpdateOptions();
+   *
+   * if (!canUpdateField) {
+   *     alert('not allowed!');
+   * }
+   * ```
+   */
+  hasPermissionToUpdateOptions(options) {
+    return this.checkPermissionsForUpdateOptions(options).hasPermission;
+  }
+
+  /**
+   * Updates the options for this field.
+   *
+   * Throws an error if the user does not have permission to update the field, if invalid
+   * options are provided, if this field has no writable options, or if updates to this field
+   * type is not supported.
+   *
+   * Refer to {@link FieldType} for supported field types, the write format for options, and
+   * other specifics for certain field types.
+   *
+   * This action is asynchronous. Unlike updates to cell values, updates to field options are
+   * **not** applied optimistically locally. You must `await` the returned promise before
+   * relying on the change in your extension.
+   *
+   * 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
+   * async function addChoiceToSelectField(selectField, nameForNewOption) {
+   *     const updatedOptions = {
+   *         choices: [
+   *             ...selectField.options.choices,
+   *             {name: nameForNewOption},
+   *         ]
+   *     };
+   *
+   *     if (selectField.hasPermissionToUpdateOptions(updatedOptions)) {
+   *         await selectField.updateOptionsAsync(updatedOptions);
+   *     }
+   * }
+   * ```
+   */
+  async updateOptionsAsync(options) {
+    let opts = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    await this._sdk.__mutations.applyMutationAsync({
+      type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_CONFIG,
+      tableId: this.parentTable.id,
+      id: this.id,
+      config: {
+        type: this.type,
+        options: options
+      },
+      opts
+    });
+  }
+}
+var _default = exports.default = Field;