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

package/dist/esm/base/viewport.js

@@ -0,0 +1,353 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _watchable = _interopRequireDefault(require("../shared/watchable"));
+var _private_utils = require("../shared/private_utils");
+var _error_utils = require("../shared/error_utils");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks: viewport */ /** */
+
+const WatchableViewportKeys = Object.freeze({
+  isFullscreen: 'isFullscreen',
+  size: 'size',
+  minSize: 'minSize',
+  maxFullscreenSize: 'maxFullscreenSize'
+});
+
+/**
+ * Watchable keys in {@link Viewport}.
+ * - `isFullscreen`
+ * - `size`
+ * - `minSize`
+ * - `maxFullscreenSize`
+ */
+
+/** */
+
+const compareWithNulls = (a, b, compare) => {
+  if (a !== null && b !== null) {
+    return compare(a, b);
+  }
+  if (a === null) {
+    return b;
+  }
+  if (b === null) {
+    return a;
+  }
+  return null;
+};
+/**
+ * Information about the current viewport
+ *
+ * The {@link useViewport} hook is the recommend way to watch for viewport changes
+ * button, but you can also use it directly.
+ *
+ * @example
+ * ```js
+ * import {viewport} from '@airtable/blocks/base';
+ * ```
+ * @docsPath models/Viewport
+ */
+class Viewport extends _watchable.default {
+  /** @internal */
+  static _className = 'Viewport';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableViewportKeys, key);
+  }
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+  _minSizes = new Set();
+  /** @internal */
+  _maxFullscreenSizes = new Set();
+  /** @internal */
+  _cachedMaxFullscreenSize = null;
+  /** @internal */
+  _cachedMinSize = null;
+
+  /** @internal */
+  constructor(isFullscreen, airtableInterface) {
+    super();
+    this._isFullscreen = isFullscreen;
+    this._airtableInterface = airtableInterface;
+
+    // When size is watched, we'll increment this counter, and we'll decrement
+    // it when it is unwatched and the counter is at 0. This way we can lazily
+    // add an event listener for window resize and remove it when nobody is
+    // listening anymore.
+    this._sizeWatchCount = 0;
+    this._onSizeChangeDebounced = (0, _private_utils.debounce)(this._onSizeChange.bind(this), 200);
+
+    // whenever maxFullscreenSize changes, we want to sync it back to the
+    // containing frame
+    this.watch(WatchableViewportKeys.maxFullscreenSize, () => {
+      this._airtableInterface.setFullscreenMaxSize(this.maxFullscreenSize);
+    });
+  }
+  /**
+   * Request to enter fullscreen mode.
+   *
+   * May fail if another extension is fullscreen or this extension doesn't have
+   * permission to fullscreen itself. Watch `isFullscreen` to know if the
+   * request succeeded.
+   */
+  enterFullscreenIfPossible() {
+    this._airtableInterface.enterFullscreen();
+  }
+  /** Request to exit fullscreen mode */
+  exitFullscreen() {
+    this._airtableInterface.exitFullscreen();
+  }
+
+  /**
+   * The maximum dimensions of the extension when it is in
+   * fullscreen mode. Returns the smallest set of dimensions added with
+   * {@link addMaxFullscreenSize}.
+   *
+   * If `width` or `height` is null, it means there is
+   * no max size constraint on that dimension. If `maxFullscreenSize` would be
+   * smaller than {@link minSize}, it is constrained to be at least `minSize`.
+   */
+  get maxFullscreenSize() {
+    if (!this._cachedMaxFullscreenSize) {
+      const maxFullscreenSize = Array.from(this._maxFullscreenSizes).reduce((memo, size) => ({
+        width: compareWithNulls(memo.width, size.width, Math.min),
+        height: compareWithNulls(memo.height, size.height, Math.min)
+      }), {
+        width: null,
+        height: null
+      });
+      const minSize = this.minSize;
+      this._cachedMaxFullscreenSize = {
+        width: maxFullscreenSize.width !== null && minSize.width !== null ? Math.max(maxFullscreenSize.width, minSize.width) : maxFullscreenSize.width,
+        height: maxFullscreenSize.height !== null && minSize.height !== null ? Math.max(maxFullscreenSize.height, minSize.height) : maxFullscreenSize.height
+      };
+    }
+    return this._cachedMaxFullscreenSize;
+  }
+
+  /**
+   * Add a maximum fullscreen size constraint. Use `.maxFullscreenSize` to get
+   * the aggregate of all added constraints.
+   *
+   * Returns a function that can be called to remove the fullscreen size constraint that was added.
+   *
+   * @param sizeConstraint The width and height constraints to add. Both
+   * `width` and `height` are optional - if either is set to null, that means
+   * there is no max size in that dimension.
+   */
+  addMaxFullscreenSize(sizeConstraint) {
+    const {
+      width,
+      height
+    } = sizeConstraint;
+    const size = Object.freeze({
+      width: typeof width === 'number' ? width : null,
+      height: typeof height === 'number' ? height : null
+    });
+    this._cachedMaxFullscreenSize = null;
+    this._maxFullscreenSizes.add(size);
+    this._onChange(WatchableViewportKeys.maxFullscreenSize);
+    return () => {
+      (0, _error_utils.invariant)(this._maxFullscreenSizes.has(size), 'UnsetFn can only be called once');
+      this._cachedMaxFullscreenSize = null;
+      this._maxFullscreenSizes.delete(size);
+      this._onChange(WatchableViewportKeys.maxFullscreenSize);
+    };
+  }
+
+  /**
+   * The minimum dimensions of the extension - if the viewport gets smaller than this
+   * size, an overlay will be shown asking the user to resize the extension to be bigger.
+   *
+   * The largest set of dimensions added with addMinSize. If `width` or `height` is null, it means
+   * there is no minSize constraint on that dimension.
+   */
+  get minSize() {
+    if (!this._cachedMinSize) {
+      this._cachedMinSize = Array.from(this._minSizes).reduce((memo, size) => ({
+        width: compareWithNulls(memo.width, size.width, Math.max),
+        height: compareWithNulls(memo.height, size.height, Math.max)
+      }), {
+        width: null,
+        height: null
+      });
+    }
+    return this._cachedMinSize;
+  }
+
+  /**
+   * Add a minimum frame size constraint. Use `.minSize`` to get the aggregate
+   * of all added constraints.
+   *
+   * Upon adding a constraint, if the extension is focused and the frame is smaller than the
+   * minimum size, the extension will enter fullscreen mode.
+   *
+   * Returns a function that can be called to remove the  size constraint that was added.
+   *
+   * @param sizeConstraint The width and height constraints to add. Both `width`
+   * and `height` are optional - if either is set to null, that means there is
+   * no min size in that dimension.
+   */
+  addMinSize(sizeConstraint) {
+    const {
+      width,
+      height
+    } = sizeConstraint;
+    const size = Object.freeze({
+      width: typeof width === 'number' ? width : null,
+      height: typeof height === 'number' ? height : null
+    });
+    this._cachedMinSize = null;
+    // min size is also a constraint on maxFullscreenSize:
+    this._cachedMaxFullscreenSize = null;
+    this._minSizes.add(size);
+    this._onChange(WatchableViewportKeys.minSize);
+    this._onChange(WatchableViewportKeys.maxFullscreenSize);
+    if (this.isSmallerThanMinSize) {
+      this.enterFullscreenIfPossible();
+    }
+    return () => {
+      (0, _error_utils.invariant)(this._minSizes.has(size), 'UnsetFn can only be called once');
+      this._cachedMinSize = null;
+      this._cachedMaxFullscreenSize = null;
+      this._minSizes.delete(size);
+      this._onChange(WatchableViewportKeys.minSize);
+      // min size is also a constraint on maxFullscreenSize:
+      this._onChange(WatchableViewportKeys.maxFullscreenSize);
+    };
+  }
+
+  /**
+   * `true` if the extension frame is smaller than `minSize`, `false` otherwise.
+   */
+  get isSmallerThanMinSize() {
+    const {
+      width,
+      height
+    } = this.size;
+    const isWidthTooSmall = this.minSize.width !== null && this.minSize.width > width;
+    const isHeightTooSmall = this.minSize.height !== null && this.minSize.height > height;
+    return isWidthTooSmall || isHeightTooSmall;
+  }
+  /**
+   * `true` if the extension is fullscreen, `false` otherwise.
+   */
+  get isFullscreen() {
+    return this._isFullscreen;
+  }
+  /**
+   * The current size of the extension frame.
+   *
+   * Can be watched.
+   */
+  get size() {
+    return {
+      width: window.innerWidth,
+      height: window.innerHeight
+    };
+  }
+  /**
+   * Get notified of changes to the viewport.
+   *
+   * Watchable keys are:
+   * - `'isFullscreen'`
+   * - `'size'`
+   * - `'minSize'`
+   * - `'maxFullscreenSize'`
+   *
+   * Every call to `.watch` should have a matching call to `.unwatch`.
+   *
+   * Returns the array of keys that were watched.
+   *
+   * @param keys the keys to watch
+   * @param callback a function to call when those keys change
+   * @param context an optional context for `this` in `callback`.
+   */
+  watch(keys, callback, context) {
+    const validKeys = super.watch(keys, callback, context);
+    if (validKeys.includes(WatchableViewportKeys.size)) {
+      if (this._sizeWatchCount === 0) {
+        window.addEventListener('resize', this._onSizeChangeDebounced, false);
+      }
+      this._sizeWatchCount++;
+    }
+    return validKeys;
+  }
+  /**
+   * Unwatch keys watched with `.watch`.
+   *
+   * Should be called with the same arguments given to `.watch`.
+   *
+   * Returns the array of keys that were unwatched
+   *
+   * @param keys the keys to unwatch
+   * @param callback the function passed to `.watch` for these keys
+   * @param context the context that was passed to `.watch` for this `callback`
+   */
+  unwatch(keys, callback, context) {
+    const validKeys = super.unwatch(keys, callback, context);
+    if (validKeys.includes(WatchableViewportKeys.size)) {
+      this._sizeWatchCount--;
+      if (this._sizeWatchCount === 0) {
+        window.removeEventListener('resize', this._onSizeChangeDebounced, false);
+      }
+    }
+    return validKeys;
+  }
+  /**
+   * @internal
+   */
+  __onEnterFullscreen() {
+    this._isFullscreen = true;
+    this._onChange(WatchableViewportKeys.isFullscreen);
+    this._onChange(WatchableViewportKeys.size);
+  }
+  /**
+   * @internal
+   */
+  __onExitFullscreen() {
+    this._isFullscreen = false;
+    this._onChange(WatchableViewportKeys.isFullscreen);
+    this._onChange(WatchableViewportKeys.size);
+  }
+  /**
+   * @internal
+   */
+  __focus() {
+    const {
+      body,
+      activeElement
+    } = document;
+    // See comment in BlockFrame.focusIframe for why we do this.
+    if (activeElement && activeElement !== body) {
+      // If there's already an activeElement, re-focus it.
+      activeElement.focus();
+    } else if (body) {
+      // If there isn't an activeElement, create a dummy input
+      // to capture focus.
+      const input = document.createElement('input');
+      body.appendChild(input);
+      input.focus();
+      input.remove();
+    }
+  }
+  /**
+   * @internal
+   */
+  _onSizeChange() {
+    this._onChange(WatchableViewportKeys.size);
+  }
+}
+var _default = exports.default = Viewport;

package/dist/esm/injected/airtable_interface.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = getAirtableInterface;
+var _error_utils = require("../shared/error_utils");
+const AIRTABLE_INTERFACE_VERSION = 0;
+let airtableInterface = null;
+const missingAirtableInterfaceErrorMessage = ['Error: Extension environment misconfigured', '\n\n', 'Airtable Extensions can only run in the presence of an Airtable Base. If you ', 'are trying to run your Extension with a Base hosted on airtable.com, then be ', 'sure you are using the Airtable CLI to serve your code and accessing it ', 'through a Custom Extension installed inside a Base on airtable.com.', '\n\n', 'If you are trying to run automated tests for your Extension, then make sure ', 'you have loaded the `@airtable/testing-library` module *before* the ', '`@airtable/blocks` module.'].join('');
+
+/** @hidden */
+function getAirtableInterface() {
+  const getAirtableInterfaceAtVersion = window.__getAirtableInterfaceAtVersion;
+  if (!airtableInterface) {
+    if (!getAirtableInterfaceAtVersion) {
+      throw (0, _error_utils.spawnError)(missingAirtableInterfaceErrorMessage);
+    }
+    airtableInterface = getAirtableInterfaceAtVersion(AIRTABLE_INTERFACE_VERSION);
+  }
+  return airtableInterface;
+}

package/dist/esm/interface/assert_run_context.js

@@ -0,0 +1,12 @@
+"use strict";
+
+var _airtable_interface = _interopRequireDefault(require("../injected/airtable_interface"));
+var _error_utils = require("../shared/error_utils");
+var _airtable_interface2 = require("./types/airtable_interface");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+if (window.__getAirtableInterfaceAtVersion) {
+  const runContextType = (0, _airtable_interface.default)().sdkInitData.runContext.type;
+  if (runContextType !== _airtable_interface2.BlockRunContextType.PAGE_ELEMENT_IN_QUERY_CONTAINER) {
+    throw (0, _error_utils.spawnError)('Unexpected import when running block in interface');
+  }
+}

package/dist/esm/interface/index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.__reset = __reset;
+var _warning = require("../shared/warning");
+var _airtable_interface = _interopRequireDefault(require("../injected/airtable_interface"));
+var _sdk = require("./sdk");
+var _initialize_block = require("./ui/initialize_block");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @internal */
+function __reset() {
+  const __sdk = new _sdk.InterfaceBlockSdk((0, _airtable_interface.default)());
+
+  // The following injections are necessary to allow the referenced modules
+  // to be imported directly by consumer code while also avoiding cycles in
+  // the module dependency graph.
+  (0, _initialize_block.__injectSdkIntoInitializeBlock)(__sdk);
+  (0, _warning.__injectSdkIntoWarning)(__sdk);
+}
+__reset();

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

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Base = void 0;
+var _base_core = require("../../shared/models/base_core");
+var _table = require("./table");
+var _record_store = require("./record_store");
+/**
+ * Model class representing a base.
+ *
+ * If you want the base model to automatically recalculate whenever the base schema changes, try the
+ * {@link useBase} hook.
+ *
+ * @docsPath models/Base
+ */
+class Base extends _base_core.BaseCore {
+  /** @internal */
+  _constructTable(tableId) {
+    const recordStore = this.__getRecordStore(tableId);
+    return new _table.Table(this, recordStore, tableId, this._sdk);
+  }
+
+  /** @internal */
+  _constructRecordStore(sdk, tableId) {
+    return new _record_store.RecordStore(sdk, tableId);
+  }
+
+  /** @internal */
+  _iterateTableIds() {
+    return Object.keys(this._data.tablesById);
+  }
+}
+exports.Base = Base;

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

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Field = void 0;
+var _field_core = require("../../shared/models/field_core");
+/**
+ * Model class representing a field in a table.
+ *
+ * @example
+ * ```js
+ * import {useBase} from '@airtable/blocks/interface/ui';
+ *
+ * function App() {
+ *     const base = useBase();
+ *     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';
+}
+exports.Field = Field;

package/dist/{cjs → esm}/interface/models/models.js

@@ -5,46 +5,47 @@ Object.defineProperty(exports, "__esModule", {
 });
 Object.defineProperty(exports, "Base", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _base.Base;
   }
 });
 Object.defineProperty(exports, "Field", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _field.Field;
   }
 });
 Object.defineProperty(exports, "FieldConfig", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _field_core.FieldConfig;
   }
 });
 Object.defineProperty(exports, "FieldType", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _field_core.FieldType;
   }
 });
 Object.defineProperty(exports, "Record", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _record.Record;
   }
 });
 Object.defineProperty(exports, "Session", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _session.Session;
   }
 });
 Object.defineProperty(exports, "Table", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _table.Table;
   }
 });
+require("../assert_run_context");
 var _field_core = require("../../shared/types/field_core");
 var _base = require("./base");
 var _table = require("./table");

package/dist/esm/interface/models/mutations.js

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Mutations = void 0;
+var _mutations_core = require("../../shared/models/mutations_core");
+var _mutations = require("../types/mutations");
+/** @hidden */
+class Mutations extends _mutations_core.MutationsCore {
+  /** @internal */
+  _isRecordStoreReadyForMutations() {
+    return true;
+  }
+
+  /** @internal */
+  _isFieldAvailableForMutation() {
+    return true;
+  }
+
+  /** @internal */
+  _getDefaultRecordProperties() {
+    return {
+      createdTime: new Date().toJSON()
+    };
+  }
+
+  /** @internal */
+  _getOptimisticModelChangesForMutation(mutation) {
+    switch (mutation.type) {
+      case _mutations.MutationTypes.CREATE_MULTIPLE_RECORDS:
+        {
+          // Ideally, we'd add the recordIds to the `recordOrder` of the Table (see
+          // how we optimistically remove from this in the DELETE_MULTIPLE_RECORDS
+          // case below). But we can't really do that because we don't know how to
+          // sort the records. As a result, we'll just optimistically add the records
+          // to the store, so if the developer calls `getRecordById` for a recordId
+          // that was just created, it will exist. But if they are iterating over
+          // all records, they will only get the new records once the mutation is
+          // applied and liveapp sends an update to the recordOrder.
+          return super._getOptimisticModelChangesForMutation(mutation);
+        }
+      case _mutations.MutationTypes.DELETE_MULTIPLE_RECORDS:
+        {
+          const {
+            tableId,
+            recordIds: deletedRecordIds
+          } = mutation;
+          const recordStore = this._base.__getRecordStore(tableId);
+          const deletedRecordIdsSet = new Set(deletedRecordIds);
+          return [{
+            path: ['tablesById', tableId, 'recordOrder'],
+            value: recordStore.recordIds.filter(recordId => !deletedRecordIdsSet.has(recordId))
+          }, ...super._getOptimisticModelChangesForMutation(mutation)];
+        }
+      default:
+        {
+          return super._getOptimisticModelChangesForMutation(mutation);
+        }
+    }
+  }
+}
+exports.Mutations = Mutations;

package/dist/esm/interface/models/record.js

@@ -0,0 +1,51 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Record = void 0;
+var _error_utils = require("../../shared/error_utils");
+var _record_core = require("../../shared/models/record_core");
+var _field_core = require("../../shared/types/field_core");
+const WatchableRecordKeys = Object.freeze({
+  ..._record_core.WatchableRecordKeysCore
+});
+/**
+ * Any key within record that can be watched:
+ * - `'name'`
+ * - `'cellValues'`
+ */
+
+/**
+ * Model class representing a record in a table.
+ *
+ * Do not instantiate. You can get instances of this class by calling {@link useRecords}.
+ *
+ * @docsPath models/Record
+ */
+class Record extends _record_core.RecordCore {
+  /** @internal */
+  static _className = 'Record';
+
+  /**
+   * Fetch foreign records for a field. Subsequent calls to this method will
+   * override previous calls that are still pending. The previous call(s)
+   * will immediately resolve with an empty `records` array.
+   *
+   * @param fieldId - The ID of the field to fetch foreign records for.
+   * @param filterString - The filter string to use to filter the records.
+   * @returns A promise that resolves to the foreign records.
+   */
+  fetchForeignRecordsAsync(field, filterString) {
+    const parentTable = this.parentTable;
+    if (field.parentTable !== parentTable) {
+      throw (0, _error_utils.spawnError)('Field %s is not in the same table as the record', field.name);
+    }
+    if (field.type !== _field_core.FieldType.MULTIPLE_RECORD_LINKS) {
+      throw (0, _error_utils.spawnError)('Field %s is not a multiple record links field', field.name);
+    }
+    const airtableInterface = this.parentTable.parentBase.__sdk.__airtableInterface;
+    return airtableInterface.fetchForeignRecordsAsync(parentTable.id, this.id, field.id, filterString);
+  }
+}
+exports.Record = Record;