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

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

@@ -0,0 +1,326 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _private_utils = require("../../shared/private_utils");
+var _mutations = require("../types/mutations");
+var _abstract_model = _interopRequireDefault(require("../../shared/models/abstract_model"));
+var _object_pool = _interopRequireDefault(require("./object_pool"));
+var _record_query_result = _interopRequireWildcard(require("./record_query_result"));
+var _view_metadata_query_result = _interopRequireDefault(require("./view_metadata_query_result"));
+var RecordColoring = _interopRequireWildcard(require("./record_coloring"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: View */ /** */
+
+// This doesn't follow our enum naming conventions because we want the keys
+// to mirror the method/getter names on the model class.
+const WatchableViewKeys = Object.freeze({
+  name: 'name',
+  isLockedView: 'isLockedView'
+});
+
+/**
+ * A key in {@link View} that can be watched.
+ * - `name`
+ */
+
+/**
+ * A class that represents an Airtable view. Every {@link Table} has one or more views.
+ *
+ * @docsPath models/View
+ */
+class View extends _abstract_model.default {
+  /** @internal */
+  static _className = 'View';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableViewKeys, key);
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * @internal
+   */
+  constructor(sdk, parentTable, viewDataStore, viewId) {
+    super(sdk, viewId);
+    this._parentTable = parentTable;
+    this._viewDataStore = viewDataStore;
+    this.__viewMetadataQueryResultPool = new _object_pool.default(_view_metadata_query_result.default);
+  }
+
+  /**
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    const tableData = this._baseData.tablesById[this.parentTable.id];
+    return tableData?.viewsById[this._id] ?? null;
+  }
+  /**
+   * The table that this view belongs to. Should never change because views aren't moved between tables.
+   *
+   * @internal (since we may not be able to return parent model instances in the immutable models world)
+   * @example
+   * ```js
+   * const view = myTable.getViewByName('Grid View');
+   * console.log(view.parentTable.id === myTable.id);
+   * // => true
+   * ```
+   */
+  get parentTable() {
+    return this._parentTable;
+  }
+  /**
+   * The name of the view. Can be watched.
+   *
+   * @example
+   * ```js
+   * console.log(myView.name);
+   * // => 'Grid view'
+   * ```
+   */
+  get name() {
+    return this._data.name;
+  }
+  /**
+   * The type of the view, such as Grid, Calendar, or Kanban. Should never change because view types cannot be modified.
+   *
+   * @example
+   * ```js
+   * console.log(myView.type);
+   * // => 'kanban'
+   * ```
+   */
+  get type() {
+    return this._data.type;
+  }
+  /**
+   * If the view is locked. Can be watched.
+   *
+   * @example
+   * ```js
+   * console.log(myView.isLockedView);
+   * // => false
+   * ```
+   */
+  get isLockedView() {
+    return this._data.isLockedView;
+  }
+  /**
+   * The URL for the view. You can visit this URL in the browser to be taken to the view in the Airtable UI.
+   *
+   * @example
+   * ```js
+   * console.log(myView.url);
+   * // => 'https://airtable.com/appxxxxxxxxxxxxxx/tblxxxxxxxxxxxxxx/viwxxxxxxxxxxxxxx'
+   * ```
+   */
+  get url() {
+    return this._sdk.__airtableInterface.urlConstructor.getViewUrl(this.id, this.parentTable.id);
+  }
+  /**
+   * Select records from the view. Returns a {@link RecordQueryResult}.
+   *
+   * Consider using {@link useRecords} or {@link useRecordIds} instead, unless you need the
+   * features of a QueryResult (e.g. `queryResult.getRecordById`). Record hooks handle
+   * loading/unloading and updating your UI automatically, but manually `select`ing records is
+   * useful for one-off data processing.
+   *
+   * @param opts Options for the query, such as sorts, fields, and record coloring. By
+   * default, records will be coloured according to the view.
+   * @example
+   * ```js
+   * import {useBase, useRecords} from '@airtable/blocks/base/ui';
+   * import React from 'react';
+   *
+   * function TodoList() {
+   *     const base = useBase();
+   *     const table = base.getTableByName('Tasks');
+   *     const view = table.getViewByName('Grid view');
+   *
+   *     const queryResult = view.selectRecords();
+   *     const records = useRecords(queryResult);
+   *
+   *     return (
+   *         <ul>
+   *             {records.map(record => (
+   *                 <li key={record.id}>
+   *                     {record.name || 'Unnamed record'}
+   *                 </li>
+   *             ))}
+   *         </ul>
+   *     );
+   * }
+   * ```
+   */
+  selectRecords() {
+    let opts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    const normalizedOpts = _record_query_result.default._normalizeOpts(this.parentTable, this._viewDataStore.parentRecordStore, {
+      ...opts,
+      recordColorMode: opts.recordColorMode === undefined ? RecordColoring.modes.byView(this) : opts.recordColorMode
+    });
+    return this.parentTable.__tableOrViewQueryResultPool.getObjectForReuse(this._sdk, this, normalizedOpts);
+  }
+  /**
+   * Select and load records from the view. Returns a {@link RecordQueryResult} promise where
+   * record data has been loaded.
+   *
+   * Consider using {@link useRecords} or {@link useRecordIds} instead, unless you need the
+   * features of a QueryResult (e.g. `queryResult.getRecordById`). Record hooks handle
+   * loading/unloading and updating your UI automatically, but manually `select`ing records is
+   * useful for one-off data processing.
+   *
+   * Once you've finished with your query, remember to call `queryResult.unloadData()`.
+   *
+   * @param opts Options for the query, such as sorts, fields, and record coloring. By
+   * default, records will be coloured according to the view.
+   * @example
+   * ```js
+   * async function getRecordCountAsync(view) {
+   *     const query = await view.selectRecordsAsync();
+   *     const recordCount = query.recordIds.length;
+   *     query.unloadData();
+   *     return recordCount;
+   * }
+   * ```
+   */
+  async selectRecordsAsync() {
+    let opts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    const queryResult = this.selectRecords(opts);
+    await queryResult.loadDataAsync();
+    return queryResult;
+  }
+  /**
+   * Select the field order and visible fields from the view. Returns a
+   * {@link ViewMetadataQueryResult}.
+   *
+   * Consider using {@link useViewMetadata} instead if you're creating a React UI. The
+   * {@link useViewMetadata} hook handles loading/unloading and updating your UI automatically,
+   * but manually `select`ing data is useful for one-off data processing.
+   *
+   * @example
+   * ```js
+   * async function loadMetadataForViewAsync(view) {
+   *     const viewMetadata = view.selectMetadata();
+   *     await viewMetadata.loadDataAsync();
+   *
+   *     console.log('Visible fields:');
+   *     console.log(viewMetadata.visibleFields.map(field => field.name));
+   *     // => ['Field 1', 'Field 2', 'Field 3']
+   *
+   *     console.log('All fields:');
+   *     console.log(viewMetadata.allFields.map(field => field.name));
+   *     // => ['Field 1', 'Field 2', 'Field 3', 'Hidden field 4']
+   *
+   *     viewMetadata.unloadData();
+   * }
+   * ```
+   */
+  selectMetadata() {
+    return this.__viewMetadataQueryResultPool.getObjectForReuse(this._sdk, this, this._viewDataStore);
+  }
+  /**
+   * Select and load the field order and visible fields from the view. Returns a
+   * {@link ViewMetadataQueryResult} promise where the metadata has already been loaded.
+   *
+   * Consider using {@link useViewMetadata} instead if you're creating a React UI. The
+   * {@link useViewMetadata} hook handles loading/unloading and updating your UI automatically,
+   * but manually `select`ing data is useful for one-off data processing.
+   *
+   * @example
+   * ```js
+   * async function loadMetadataForViewAsync(view) {
+   *     const viewMetadata = await view.selectMetadata();
+   *
+   *     console.log('Visible fields:');
+   *     console.log(viewMetadata.visibleFields.map(field => field.name));
+   *     // => ['Field 1', 'Field 2', 'Field 3']
+   *
+   *     console.log('All fields:');
+   *     console.log(viewMetadata.allFields.map(field => field.name));
+   *     // => ['Field 1', 'Field 2', 'Field 3', 'Hidden field 4']
+   *
+   *     viewMetadata.unloadData();
+   * }
+   * ```
+   */
+  async selectMetadataAsync() {
+    const queryResult = this.selectMetadata();
+    await queryResult.loadDataAsync();
+    return queryResult;
+  }
+
+  /**
+   * Checks whether the current user has permission to update view metadata.
+   *
+   * @param viewMetadata
+   * @hidden
+   */
+  checkPermissionsForUpdateMetadata(viewMetadata) {
+    const metadata = {
+      groupLevels: (0, _record_query_result.normalizeSortsOrGroups)(this.parentTable, viewMetadata.groupLevels)
+    };
+    return this._sdk.__mutations.checkPermissionsForMutation({
+      type: _mutations.MutationTypes.UPDATE_VIEW_METADATA,
+      tableId: this.parentTable.id,
+      viewId: this.id,
+      metadata
+    });
+  }
+
+  /**
+   * An alias for `checkPermissionsForUpdateMetadata(viewMetadata).hasPermission`.
+   *
+   * Checks whether the current user has permission to update view metadata.
+   *
+   * @param viewMetadata
+   * @hidden
+   */
+  hasPermissionToUpdateMetadata(viewMetadata) {
+    return this.checkPermissionsForUpdateMetadata(viewMetadata).hasPermission;
+  }
+
+  /**
+   * Updates view metadata, this is currently only supported from block views
+   * altering their own view's grouping config.
+   *
+   * @param ViewMetadataForUpdate
+   * @hidden
+   */
+  async updateMetadataAsync(viewMetadata) {
+    const metadata = {
+      groupLevels: (0, _record_query_result.normalizeSortsOrGroups)(this.parentTable, viewMetadata.groupLevels)
+    };
+    await this._sdk.__mutations.applyMutationAsync({
+      type: _mutations.MutationTypes.UPDATE_VIEW_METADATA,
+      tableId: this.parentTable.id,
+      viewId: this.id,
+      metadata
+    });
+  }
+
+  /**
+   * @internal
+   */
+  __triggerOnChangeForDirtyPaths(dirtyPaths) {
+    let didViewSchemaChange = false;
+    this._viewDataStore.triggerOnChangeForDirtyPaths(dirtyPaths);
+    if (dirtyPaths.name) {
+      this._onChange(WatchableViewKeys.name);
+      didViewSchemaChange = true;
+    }
+    if (dirtyPaths.isLocked) {
+      this._onChange(WatchableViewKeys.isLockedView);
+      didViewSchemaChange = true;
+    }
+    return didViewSchemaChange;
+  }
+}
+var _default = exports.default = View;

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

@@ -0,0 +1,265 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.WatchableViewDataStoreKeys = 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"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const WatchableViewDataStoreKeys = exports.WatchableViewDataStoreKeys = Object.freeze({
+  visibleRecords: 'visibleRecords',
+  visibleRecordIds: 'visibleRecordIds',
+  groups: 'groups',
+  groupLevels: 'groupLevels',
+  recordColors: 'recordColors',
+  allFieldIds: 'allFieldIds',
+  visibleFieldIds: 'visibleFieldIds'
+});
+
+/** @internal */
+
+// ViewDataStore contains loadable data for a specific view. That means the set of visible records,
+// and field order/visibility information. View itself only contains core schema information. The
+// data here doesn't belong in View as it's record data or conditionally loaded.
+/** @internal */
+class ViewDataStore extends _abstract_model_with_async_data.default {
+  static _className = 'ViewDataStore';
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableViewDataStoreKeys, key);
+  }
+  static _shouldLoadDataForKey(key) {
+    return true;
+  }
+  constructor(sdk, parentRecordStore, viewId) {
+    super(sdk, `${viewId}-ViewDataStore`);
+    this.parentRecordStore = parentRecordStore;
+    this._airtableInterface = sdk.__airtableInterface;
+    this._mostRecentTableLoadPromise = null;
+    this.viewId = viewId;
+  }
+  get _dataOrNullIfDeleted() {
+    const tableData = this._baseData.tablesById[this.parentRecordStore.tableId];
+    return tableData?.viewsById[this.viewId] ?? null;
+  }
+  _onChangeIsDataLoaded() {
+    // noop
+  }
+  get isDataLoaded() {
+    return this._isDataLoaded && this.parentRecordStore.isRecordMetadataLoaded;
+  }
+  __onDataDeletion() {
+    this._forceUnload();
+  }
+  async loadDataAsync() {
+    // Override this method to also load table data.
+    // NOTE: it's important that we call loadDataAsync on the table here and not in
+    // _loadDataAsync since we want the retain counts for the view and table to increase/decrease
+    // in lock-step. If we load table data in _loadDataAsync, the table's retain
+    // count only increments some of the time, which leads to unexpected behavior.
+    const tableLoadPromise = this.parentRecordStore.loadRecordMetadataAsync();
+    this._mostRecentTableLoadPromise = tableLoadPromise;
+    await super.loadDataAsync();
+  }
+  async _loadDataAsync() {
+    // We need to be sure that the table data is loaded *before* we return
+    // from this method.
+    (0, _error_utils.invariant)(this._mostRecentTableLoadPromise, 'No table load promise');
+    const tableLoadPromise = this._mostRecentTableLoadPromise;
+    const [viewData] = await Promise.all([this._airtableInterface.fetchAndSubscribeToViewDataAsync(this.parentRecordStore.tableId, this.viewId), tableLoadPromise]);
+    this._data.visibleRecordIds = viewData.visibleRecordIds;
+    this._data.fieldOrder = viewData.fieldOrder;
+    this._data.groups = viewData.groups;
+    this._data.groupLevels = viewData.groupLevels;
+    this._data.colorsByRecordId = viewData.colorsByRecordId;
+    if (this._data.colorsByRecordId) {
+      for (const record of this.visibleRecords) {
+        if ((0, _private_utils.has)(this._data.colorsByRecordId, record.id)) {
+          record.__triggerOnChangeForRecordColorInViewId(this.viewId);
+        }
+      }
+    }
+    return [WatchableViewDataStoreKeys.visibleRecords, WatchableViewDataStoreKeys.visibleRecordIds, WatchableViewDataStoreKeys.allFieldIds, WatchableViewDataStoreKeys.groups, WatchableViewDataStoreKeys.groupLevels, WatchableViewDataStoreKeys.visibleFieldIds, WatchableViewDataStoreKeys.recordColors];
+  }
+  unloadData() {
+    // Override this method to also unload the table's data.
+    // NOTE: it's important that we do this here, since we want the view and table's
+    // retain counts to increment/decrement in lock-step. If we unload the table's
+    // data in _unloadData, it leads to unexpected behavior.
+    super.unloadData();
+    this.parentRecordStore.unloadRecordMetadata();
+  }
+  _unloadData() {
+    this._mostRecentTableLoadPromise = null;
+    this._airtableInterface.unsubscribeFromViewData(this.parentRecordStore.tableId, this.viewId);
+    if (!this.isDeleted) {
+      this._data.visibleRecordIds = undefined;
+      this._data.groups = undefined;
+      this._data.colorsByRecordId = undefined;
+    }
+  }
+  __generateChangesForParentTableAddMultipleRecords(recordIds) {
+    const newVisibleRecordIds = [...this.visibleRecordIds, ...recordIds];
+    return [{
+      path: ['tablesById', this.parentRecordStore.tableId, 'viewsById', this.viewId, 'visibleRecordIds'],
+      value: newVisibleRecordIds
+    }];
+  }
+  __generateChangesForParentTableDeleteMultipleRecords(recordIds) {
+    const recordIdsToDeleteSet = {};
+    for (const recordId of recordIds) {
+      recordIdsToDeleteSet[recordId] = true;
+    }
+    const newVisibleRecordIds = this.visibleRecordIds.filter(recordId => !recordIdsToDeleteSet[recordId]);
+    const changePayload = [{
+      path: ['tablesById', this.parentRecordStore.tableId, 'viewsById', this.viewId, 'visibleRecordIds'],
+      value: newVisibleRecordIds
+    }];
+    if (this._data.groups) {
+      const newGroups = this.__recursivelyRemoveRecordsFromGroupsInPlace((0, _private_utils.cloneDeep)(this._data.groups), recordIdsToDeleteSet);
+      changePayload.push({
+        path: ['tablesById', this.parentRecordStore.tableId, 'viewsById', this.viewId, 'groups'],
+        value: newGroups
+      });
+    }
+    return changePayload;
+  }
+  __recursivelyRemoveRecordsFromGroupsInPlace(groups, recordIdsToDeleteSet) {
+    if (!groups || groups.length === 0) {
+      return groups;
+    }
+    return groups.map(group => {
+      if (group.visibleRecordIds) {
+        group.visibleRecordIds = group.visibleRecordIds.filter(id => !recordIdsToDeleteSet[id]);
+      }
+      this.__recursivelyRemoveRecordsFromGroupsInPlace(group.groups, recordIdsToDeleteSet);
+      return group;
+    });
+  }
+
+  /**
+   * The record IDs that are not filtered out of this view.
+   * Can be watched to know when records are created, deleted, reordered, or
+   * filtered in and out of this view.
+   */
+  get visibleRecordIds() {
+    const visibleRecordIds = this._data.visibleRecordIds;
+    (0, _error_utils.invariant)(visibleRecordIds, 'View data is not loaded');
+
+    // Freeze visibleRecordIds so users can't mutate it.
+    // If it changes from liveapp, we get an entire new array which will
+    // replace this one, so it's okay to freeze it.
+    if (!Object.isFrozen(visibleRecordIds)) {
+      Object.freeze(visibleRecordIds);
+    }
+    return visibleRecordIds;
+  }
+
+  /**
+   * The records that are not filtered out of this view.
+   * Can be watched to know when records are created, deleted, reordered, or
+   * filtered in and out of this view.
+   */
+  get visibleRecords() {
+    (0, _error_utils.invariant)(this.parentRecordStore.isRecordMetadataLoaded, 'Table data is not loaded');
+    const visibleRecordIds = this._data.visibleRecordIds;
+    (0, _error_utils.invariant)(visibleRecordIds, 'View data is not loaded');
+    return visibleRecordIds.map(recordId => {
+      const record = this.parentRecordStore.getRecordByIdIfExists(recordId);
+      (0, _error_utils.invariant)(record, 'Record in view does not exist');
+      return record;
+    });
+  }
+
+  /**
+   * Gets the groups in a view, can be watched to be notified if a record changes groups,
+   * if a record is changed/deleted/created, if sort order of groups changes, grouping
+   * heirarchy changes, or grouping field changes.
+   *
+   * @hidden
+   */
+  get groups() {
+    (0, _error_utils.invariant)(this.parentRecordStore.isRecordMetadataLoaded, 'Table data is not loaded');
+    const groups = this._data.groups;
+    return groups ?? null;
+  }
+
+  /**
+   * Gets the group config for this view, can be watched to know when groupLevels
+   * changes (reorder, groups deleted, groups changed, grouped field changes)
+   */
+  get groupLevels() {
+    (0, _error_utils.invariant)(this.parentRecordStore.isRecordMetadataLoaded, 'Table data is not loaded');
+    const groupLevels = this._data.groupLevels;
+    return groupLevels ?? null;
+  }
+
+  /**
+   * Get the color name for the specified record in this view, or null if no
+   * color is available. Watch with 'recordColors'
+   *
+   * @param recordOrRecordId the record/record id to get the color for
+   */
+  getRecordColor(record) {
+    (0, _error_utils.invariant)(this.isDataLoaded, 'View data is not loaded');
+    return this._data.colorsByRecordId?.[record.id] ?? null;
+  }
+  get allFieldIds() {
+    const fieldOrder = this._data.fieldOrder;
+    (0, _error_utils.invariant)(fieldOrder, 'View data is not loaded');
+    return fieldOrder.fieldIds;
+  }
+  get visibleFieldIds() {
+    const fieldOrder = this._data.fieldOrder;
+    (0, _error_utils.invariant)(fieldOrder, 'View data is not loaded');
+    const {
+      fieldIds
+    } = fieldOrder;
+    return fieldIds.slice(0, fieldOrder.visibleFieldCount);
+  }
+  triggerOnChangeForDirtyPaths(dirtyPaths) {
+    if (dirtyPaths.visibleRecordIds) {
+      this._onChange(WatchableViewDataStoreKeys.visibleRecords);
+      this._onChange(WatchableViewDataStoreKeys.visibleRecordIds);
+    }
+    if (dirtyPaths.fieldOrder) {
+      this._onChange(WatchableViewDataStoreKeys.allFieldIds);
+      // TODO(kasra): only trigger visibleFields if the *visible* field ids changed.
+      this._onChange(WatchableViewDataStoreKeys.visibleFieldIds);
+    }
+    // Technically it's possible for groupLevels changing to cause a groups
+    // change since we derive group information from the groupLevels (fieldId)
+    if (dirtyPaths.groups || dirtyPaths.groupLevels) {
+      this._onChange(WatchableViewDataStoreKeys.groups);
+    }
+    if (dirtyPaths.groupLevels) {
+      this._onChange(WatchableViewDataStoreKeys.groupLevels);
+    }
+    if (dirtyPaths.colorsByRecordId) {
+      const changedRecordIds = dirtyPaths.colorsByRecordId._isDirty ? null : Object.keys(dirtyPaths.colorsByRecordId);
+      if (changedRecordIds) {
+        // Checking isRecordMetadataLoaded fixes a timing issue:
+        // When a new table loads in liveapp, we'll receive the record
+        // colors before getting the response to our loadData call.
+        // This is a temporary fix: we need a more general solution to
+        // avoid processing events associated with subscriptions whose
+        // data we haven't received yet.
+        if (this.parentRecordStore.isRecordMetadataLoaded) {
+          for (const recordId of changedRecordIds) {
+            const record = this.parentRecordStore.getRecordByIdIfExists(recordId);
+            // Similar to above, we could be receiving the change notification
+            // for a record color before receiving the new record itself.
+            if (record) {
+              record.__triggerOnChangeForRecordColorInViewId(this.viewId);
+            }
+          }
+        }
+      }
+      this._onChange(WatchableViewDataStoreKeys.recordColors, changedRecordIds);
+    }
+  }
+}
+
+/** @internal */
+var _default = exports.default = ViewDataStore;