@airtable/blocks 0.0.0-experimental-20e3506bd-20250428

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

@@ -0,0 +1,393 @@
+"use strict";
+
+require("core-js/modules/es.symbol.js");
+require("core-js/modules/es.symbol.description.js");
+require("core-js/modules/es.array.from.js");
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.array.slice.js");
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.regexp.exec.js");
+require("core-js/modules/es.regexp.to-string.js");
+require("core-js/modules/web.dom-collections.iterator.js");
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+var _possibleConstructorReturn2 = _interopRequireDefault(require("@babel/runtime/helpers/possibleConstructorReturn"));
+var _getPrototypeOf2 = _interopRequireDefault(require("@babel/runtime/helpers/getPrototypeOf"));
+var _inherits2 = _interopRequireDefault(require("@babel/runtime/helpers/inherits"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+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 _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+function _callSuper(t, o, e) { return o = (0, _getPrototypeOf2.default)(o), (0, _possibleConstructorReturn2.default)(t, _isNativeReflectConstruct() ? Reflect.construct(o, e || [], (0, _getPrototypeOf2.default)(t).constructor) : o.apply(t, e)); }
+function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); } catch (t) {} return (_isNativeReflectConstruct = function _isNativeReflectConstruct() { return !!t; })(); } /** @module @airtable/blocks/models: Cursor */ /** */
+var 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/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/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
+ */
+var Cursor = /*#__PURE__*/function (_AbstractModelWithAsy) {
+  /** @internal */
+  function Cursor(sdk) {
+    var _baseData$cursorData$, _baseData$cursorData, _baseData$cursorData$2, _baseData$cursorData2, _activeTable$activeVi;
+    var _this;
+    (0, _classCallCheck2.default)(this, Cursor);
+    _this = _callSuper(this, Cursor, [sdk, 'cursor']);
+    /** @internal */
+    (0, _defineProperty2.default)(_this, "_cursorData", void 0);
+    var baseData = sdk.__airtableInterface.sdkInitData.baseData;
+    var selectedRecordIdSet = (_baseData$cursorData$ = (_baseData$cursorData = baseData.cursorData) === null || _baseData$cursorData === void 0 ? void 0 : _baseData$cursorData.selectedRecordIdSet) !== null && _baseData$cursorData$ !== void 0 ? _baseData$cursorData$ : null;
+    var selectedFieldIdSet = (_baseData$cursorData$2 = (_baseData$cursorData2 = baseData.cursorData) === null || _baseData$cursorData2 === void 0 ? void 0 : _baseData$cursorData2.selectedFieldIdSet) !== null && _baseData$cursorData$2 !== void 0 ? _baseData$cursorData$2 : null;
+    var activeTableId = baseData.activeTableId;
+    var activeTable = activeTableId ? baseData.tablesById[activeTableId] : null;
+    var activeViewId = (_activeTable$activeVi = activeTable === null || activeTable === void 0 ? void 0 : activeTable.activeViewId) !== null && _activeTable$activeVi !== void 0 ? _activeTable$activeVi : null;
+    _this._cursorData = {
+      selectedRecordIdSet,
+      selectedFieldIdSet,
+      activeTableId,
+      activeViewId
+    };
+    Object.seal(_this);
+    return _this;
+  }
+
+  /**
+   * @internal
+   */
+  (0, _inherits2.default)(Cursor, _AbstractModelWithAsy);
+  return (0, _createClass2.default)(Cursor, [{
+    key: "_dataOrNullIfDeleted",
+    get: function get() {
+      return this._cursorData;
+    }
+    /**
+     * @internal
+     */
+  }, {
+    key: "_onChangeIsDataLoaded",
+    value: function _onChangeIsDataLoaded() {
+      this._onChange(WatchableCursorKeys.isDataLoaded);
+    }
+    /**
+     * @internal
+     */
+  }, {
+    key: "_loadDataAsync",
+    value: (function () {
+      var _loadDataAsync2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
+        var cursorData;
+        return _regenerator.default.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              _context.next = 2;
+              return this._sdk.__airtableInterface.fetchAndSubscribeToCursorDataAsync();
+            case 2:
+              cursorData = _context.sent;
+              this._cursorData.selectedRecordIdSet = cursorData.selectedRecordIdSet;
+              this._cursorData.selectedFieldIdSet = cursorData.selectedFieldIdSet;
+              return _context.abrupt("return", [WatchableCursorKeys.selectedRecordIds, WatchableCursorKeys.selectedFieldIds]);
+            case 6:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee, this);
+      }));
+      function _loadDataAsync() {
+        return _loadDataAsync2.apply(this, arguments);
+      }
+      return _loadDataAsync;
+    }()
+    /**
+     * @internal
+     */
+    )
+  }, {
+    key: "_unloadData",
+    value: function _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.
+     */
+  }, {
+    key: "selectedRecordIds",
+    get: function get() {
+      var selectedRecordIdSet = this._data.selectedRecordIdSet;
+      (0, _error_utils.invariant)(selectedRecordIdSet, 'Cursor data is not loaded');
+      var 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.
+     */
+  }, {
+    key: "selectedFieldIds",
+    get: function get() {
+      var selectedFieldIdSet = this._data.selectedFieldIdSet;
+      (0, _error_utils.invariant)(selectedFieldIdSet, 'Cursor data is not loaded');
+      var 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.
+     */
+  }, {
+    key: "isRecordSelected",
+    value: function isRecordSelected(recordOrRecordId) {
+      var selectedRecordIdSet = this._data.selectedRecordIdSet;
+      (0, _error_utils.invariant)(selectedRecordIdSet, 'Cursor data is not loaded');
+      var 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.
+     */
+  }, {
+    key: "activeTableId",
+    get: function get() {
+      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.
+     */
+  }, {
+    key: "activeViewId",
+    get: function get() {
+      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.
+     */
+  }, {
+    key: "setActiveTable",
+    value: function setActiveTable(tableOrTableId) {
+      var 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.
+     */
+  }, {
+    key: "setActiveView",
+    value: function setActiveView(tableOrTableId, viewOrViewId) {
+      var tableId = tableOrTableId instanceof _table.default ? tableOrTableId.id : tableOrTableId;
+      var viewId = viewOrViewId instanceof _view.default ? viewOrViewId.id : viewOrViewId;
+      this._sdk.__airtableInterface.setActiveViewOrTable(tableId, viewId);
+    }
+
+    /**
+     * @internal
+     */
+  }, {
+    key: "__applyChangesWithoutTriggeringEvents",
+    value: function __applyChangesWithoutTriggeringEvents(changes) {
+      var changedKeys = {
+        [WatchableCursorKeys.selectedRecordIds]: false,
+        [WatchableCursorKeys.activeTableId]: false,
+        [WatchableCursorKeys.activeViewId]: false
+      };
+      var _iterator = _createForOfIteratorHelper(changes),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var _step$value = _step.value,
+            path = _step$value.path,
+            value = _step$value.value;
+          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;
+          }
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return changedKeys;
+    }
+    /**
+     * @internal
+     */
+  }, {
+    key: "__triggerOnChangeForChangedKeys",
+    value: function __triggerOnChangeForChangedKeys(changedKeys) {
+      var _iterator2 = _createForOfIteratorHelper((0, _private_utils.entries)(changedKeys)),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _step2$value = (0, _slicedToArray2.default)(_step2.value, 2),
+            key = _step2$value[0],
+            didChange = _step2$value[1];
+          if (didChange) {
+            this._onChange(key);
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  }], [{
+    key: "_isWatchableKey",
+    value: /** @internal */
+    function _isWatchableKey(key) {
+      return (0, _private_utils.isEnumValue)(WatchableCursorKeys, key);
+    }
+    /** @internal */
+  }, {
+    key: "_shouldLoadDataForKey",
+    value: function _shouldLoadDataForKey(key) {
+      return true;
+    }
+  }]);
+}(_abstract_model_with_async_data.default);
+/** @internal */
+(0, _defineProperty2.default)(Cursor, "_className", 'Cursor');
+var _default = exports.default = Cursor;