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

package/dist/esm/shared/models/record_core.js

@@ -0,0 +1,215 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WatchableRecordKeysCore = exports.RecordCore = void 0;
+var _private_utils = require("../private_utils");
+var _error_utils = require("../error_utils");
+var _field_core = require("../types/field_core");
+var _abstract_model = _interopRequireDefault(require("./abstract_model"));
+var _field_core2 = require("./field_core");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const WatchableRecordKeysCore = exports.WatchableRecordKeysCore = Object.freeze({
+  name: 'name',
+  // TODO(kasra): these keys don't have matching getters (not that they should
+  // it's just inconsistent...)
+  cellValues: 'cellValues'
+});
+
+/** @hidden */
+
+/** @hidden */
+class RecordCore extends _abstract_model.default {
+  /** @internal */
+  static _className = 'RecordCore';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableRecordKeysCore, key);
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * @internal
+   */
+  constructor(sdk, parentRecordStore, parentTable, recordId) {
+    super(sdk, recordId);
+    this._parentRecordStore = parentRecordStore;
+    this._parentTable = parentTable;
+  }
+
+  /**
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    const tableData = this._baseData.tablesById[this.parentTable.id];
+    if (!tableData) {
+      return null;
+    }
+    const recordsById = tableData.recordsById;
+    (0, _error_utils.invariant)(recordsById, 'Record data is not loaded');
+    return recordsById[this._id] ?? null;
+  }
+
+  /**
+   * The table that this record belongs to. Should never change because records aren't moved between tables.
+   *
+   * @internal (since we may not be able to return parent model instances in the immutable models world)
+   * @example
+   * ```js
+   * import {useRecords} from '@airtable/blocks/base/ui';
+   * const records = useRecords(myTable);
+   * console.log(records[0].parentTable.id === myTable.id);
+   * // => true
+   * ```
+   */
+  get parentTable() {
+    return this._parentTable;
+  }
+  /**
+   * @internal
+   */
+  _getFieldMatching(fieldOrFieldIdOrFieldName) {
+    if (fieldOrFieldIdOrFieldName instanceof _field_core2.FieldCore) {
+      return this._parentTable.__getFieldMatching(fieldOrFieldIdOrFieldName.id);
+    }
+    return this.parentTable.__getFieldMatching(fieldOrFieldIdOrFieldName);
+  }
+
+  /**
+   * @internal
+   *
+   * For use when we need the raw public API cell value. Specifically makes a difference
+   * for lookup fields, where we translate the format to a blocks-specific format in getCellValue.
+   * That format is incompatible with fieldTypeProvider methods, which expect the public API
+   * format - use _getRawCellValue instead.
+   */
+  _getRawCellValue(field) {
+    const {
+      cellValuesByFieldId
+    } = this._data;
+    if (!cellValuesByFieldId) {
+      return null;
+    }
+    const cellValue = cellValuesByFieldId[field.id] !== undefined ? cellValuesByFieldId[field.id] : null;
+    if (typeof cellValue === 'object' && cellValue !== null) {
+      // Copy non-primitives.
+      // TODO(kasra): maybe freezeDeep instead?
+      return (0, _private_utils.cloneDeep)(cellValue);
+    } else {
+      return cellValue;
+    }
+  }
+  /**
+   * Gets the cell value of the given field for this record.
+   *
+   * @param fieldOrFieldIdOrFieldName The field (or field ID or field name) whose cell value you'd like to get.
+   * @example
+   * ```js
+   * const cellValue = myRecord.getCellValue(mySingleLineTextField);
+   * console.log(cellValue);
+   * // => 'cell value'
+   * ```
+   */
+  getCellValue(fieldOrFieldIdOrFieldName) {
+    const field = this._getFieldMatching(fieldOrFieldIdOrFieldName);
+    const cellValue = this._getRawCellValue(field);
+
+    // HACK: migrate to new public lookup cell value format if needed
+    if (typeof cellValue === 'object' && cellValue !== null && field.type === _field_core.FieldType.MULTIPLE_LOOKUP_VALUES && !this._sdk.__airtableInterface.sdkInitData.isUsingNewLookupCellValueFormat) {
+      const cellValueForMigration = [];
+      (0, _error_utils.invariant)(Array.isArray(cellValue.linkedRecordIds), 'linkedRecordIds');
+      for (const linkedRecordId of cellValue.linkedRecordIds) {
+        (0, _error_utils.invariant)(typeof linkedRecordId === 'string', 'linkedRecordId');
+        const {
+          valuesByLinkedRecordId
+        } = cellValue;
+        (0, _error_utils.invariant)(valuesByLinkedRecordId && typeof valuesByLinkedRecordId === 'object', 'valuesByLinkedRecordId');
+        const value = valuesByLinkedRecordId[linkedRecordId];
+        if (Array.isArray(value)) {
+          for (const v of value) {
+            cellValueForMigration.push({
+              linkedRecordId,
+              value: v
+            });
+          }
+        } else {
+          cellValueForMigration.push({
+            linkedRecordId,
+            value
+          });
+        }
+      }
+      return cellValueForMigration;
+    }
+    return cellValue;
+  }
+  /**
+   * Gets the cell value of the given field for this record, formatted as a `string`.
+   *
+   * @param fieldOrFieldIdOrFieldName The field (or field ID or field name) whose cell value you'd like to get.
+   * @example
+   * ```js
+   * const stringValue = myRecord.getCellValueAsString(myNumberField);
+   * console.log(stringValue);
+   * // => '42'
+   * ```
+   */
+  getCellValueAsString(fieldOrFieldIdOrFieldName) {
+    const field = this._getFieldMatching(fieldOrFieldIdOrFieldName);
+    const cellValue = this._getRawCellValue(field);
+    if (cellValue === null || cellValue === undefined) {
+      return '';
+    } else {
+      const airtableInterface = this._sdk.__airtableInterface;
+      const appInterface = this._sdk.__appInterface;
+      return airtableInterface.fieldTypeProvider.convertCellValueToString(appInterface, cellValue, field._data);
+    }
+  }
+  /**
+   * The primary cell value in this record, formatted as a `string`.
+   *
+   * @example
+   * ```js
+   * console.log(myRecord.name);
+   * // => '42'
+   * ```
+   */
+  get name() {
+    return this.getCellValueAsString(this.parentTable.primaryField);
+  }
+  /**
+   * The created time of this record.
+   *
+   * @example
+   * ```js
+   * console.log(`
+   *     This record was created at ${myRecord.createdTime.toISOString()}
+   * `);
+   * ```
+   */
+  get createdTime() {
+    return new Date(this._data.createdTime);
+  }
+  /**
+   * @internal
+   */
+  __triggerOnChangeForDirtyPaths(dirtyPaths) {
+    const {
+      cellValuesByFieldId
+    } = dirtyPaths;
+    if (cellValuesByFieldId && !(0, _private_utils.isObjectEmpty)(cellValuesByFieldId)) {
+      // TODO: don't trigger changes for fields that aren't supposed to be loaded
+      // (in some cases, e.g. record created, liveapp will send cell values
+      // that we're not subscribed to).
+
+      this._onChange(WatchableRecordKeysCore.cellValues, Object.keys(cellValuesByFieldId));
+      if (cellValuesByFieldId[this.parentTable.primaryField.id]) {
+        this._onChange(WatchableRecordKeysCore.name);
+      }
+    }
+  }
+}
+exports.RecordCore = RecordCore;

package/dist/esm/shared/models/record_store_core.js

@@ -0,0 +1,160 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.WatchableRecordStoreKeysCore = exports.WatchableCellValuesInFieldKeyPrefix = void 0;
+var _private_utils = require("../../shared/private_utils");
+var _error_utils = require("../../shared/error_utils");
+var _abstract_model = _interopRequireDefault(require("../../shared/models/abstract_model"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const WatchableRecordStoreKeysCore = exports.WatchableRecordStoreKeysCore = Object.freeze({
+  records: 'records',
+  recordIds: 'recordIds',
+  cellValues: 'cellValues'
+});
+const WatchableCellValuesInFieldKeyPrefix = exports.WatchableCellValuesInFieldKeyPrefix = 'cellValuesInField:';
+
+/**
+ * The string case is to accommodate prefix keys
+ *
+ * @internal
+ */
+
+/**
+ * One RecordStore exists per table, and contains all the record data associated with that table.
+ * Table itself is for schema information only, so isn't the appropriate place for this data.
+ *
+ * @internal
+ */
+class RecordStoreCore extends _abstract_model.default {
+  static _className = 'RecordStoreCore';
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableRecordStoreKeysCore, key) || key.startsWith(WatchableCellValuesInFieldKeyPrefix);
+  }
+  _recordModelsById = {};
+  constructor(sdk, tableId) {
+    super(sdk, `${tableId}-RecordStore`);
+    this.tableId = tableId;
+  }
+  get _dataOrNullIfDeleted() {
+    return this._baseData.tablesById[this.tableId] ?? null;
+  }
+  watch(keys, callback, context) {
+    const validKeys = super.watch(keys, callback, context);
+    return validKeys;
+  }
+  unwatch(keys, callback, context) {
+    const validKeys = super.unwatch(keys, callback, context);
+    return validKeys;
+  }
+
+  /**
+   * The records in this table.
+   */
+  get records() {
+    const recordsById = this._data.recordsById;
+    (0, _error_utils.invariant)(recordsById, 'Record metadata is not loaded');
+    const records = this.recordIds.map(recordId => {
+      const record = this.getRecordByIdIfExists(recordId);
+      (0, _error_utils.invariant)(record, 'record');
+      return record;
+    });
+    return records;
+  }
+
+  /**
+   * The record IDs in this table.
+   */
+
+  getRecordByIdIfExists(recordId) {
+    const recordsById = this._data.recordsById;
+    (0, _error_utils.invariant)(recordsById, 'Record metadata is not loaded');
+    (0, _error_utils.invariant)(typeof recordId === 'string', 'getRecordById expects a string');
+    if (!recordsById[recordId]) {
+      return null;
+    } else {
+      if (this._recordModelsById[recordId]) {
+        return this._recordModelsById[recordId];
+      }
+      const newRecord = this._constructRecord(recordId, this._sdk.base.getTableById(this.tableId));
+      this._recordModelsById[recordId] = newRecord;
+      return newRecord;
+    }
+  }
+  triggerOnChangeForDirtyPaths(dirtyPaths) {
+    if (dirtyPaths.recordsById) {
+      // Since tables don't have a record order, need to detect if a record
+      // was created or deleted and trigger onChange for records.
+      const dirtyFieldIdsSet = {};
+      const addedRecordIds = [];
+      const removedRecordIds = [];
+      for (const [recordId, dirtyRecordPaths] of (0, _private_utils.entries)(dirtyPaths.recordsById)) {
+        if (dirtyRecordPaths && dirtyRecordPaths._isDirty) {
+          // If the entire record is dirty, it was either created or deleted.
+          (0, _error_utils.invariant)(this._data.recordsById, 'No recordsById');
+          if ((0, _private_utils.has)(this._data.recordsById, recordId)) {
+            addedRecordIds.push(recordId);
+          } else {
+            removedRecordIds.push(recordId);
+            const recordModel = this._recordModelsById[recordId];
+            if (recordModel) {
+              // Remove the Record model if it was deleted.
+              delete this._recordModelsById[recordId];
+            }
+          }
+        } else {
+          const recordModel = this._recordModelsById[recordId];
+          if (recordModel) {
+            recordModel.__triggerOnChangeForDirtyPaths(dirtyRecordPaths);
+          }
+        }
+        const {
+          cellValuesByFieldId
+        } = dirtyRecordPaths;
+        if (cellValuesByFieldId) {
+          for (const fieldId of Object.keys(cellValuesByFieldId)) {
+            dirtyFieldIdsSet[fieldId] = true;
+          }
+        }
+      }
+
+      // Now that we've composed our created/deleted record ids arrays, let's fire
+      // the records onChange event if any records were created or deleted.
+      if (addedRecordIds.length > 0 || removedRecordIds.length > 0) {
+        this._onChange(WatchableRecordStoreKeysCore.records, {
+          addedRecordIds,
+          removedRecordIds
+        });
+        this._onChange(WatchableRecordStoreKeysCore.recordIds, {
+          addedRecordIds,
+          removedRecordIds
+        });
+      }
+
+      // NOTE: this is an experimental (and somewhat messy) way to watch
+      // for changes to cells in a table, as an alternative to implementing
+      // full event bubbling. For now, it unblocks the things we want to
+      // build, but we may replace it.
+      // If we keep it, could be more efficient by not calling _onChange
+      // if there are no subscribers.
+      // TODO: don't trigger changes for fields that aren't supposed to be loaded
+      // (in some cases, e.g. record created, liveapp will send cell values
+      // that we're not subscribed to).
+      const fieldIds = Object.freeze(Object.keys(dirtyFieldIdsSet));
+      const recordIds = Object.freeze(Object.keys(dirtyPaths.recordsById));
+      if (fieldIds.length > 0 && recordIds.length > 0) {
+        this._onChange(WatchableRecordStoreKeysCore.cellValues, {
+          recordIds,
+          fieldIds
+        });
+      }
+      for (const fieldId of fieldIds) {
+        this._onChange(WatchableCellValuesInFieldKeyPrefix + fieldId, recordIds, fieldId);
+      }
+    }
+  }
+}
+
+/** @internal */
+var _default = exports.default = RecordStoreCore;

package/dist/esm/shared/models/session_core.js

@@ -0,0 +1,160 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SessionCore = void 0;
+var _error_utils = require("../error_utils");
+var _private_utils = require("../private_utils");
+var _abstract_model = _interopRequireDefault(require("./abstract_model"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: Session */ /** */
+
+/** @hidden */
+
+const WatchableSessionKeys = Object.freeze({
+  permissionLevel: 'permissionLevel',
+  // NOTE: the current user's identity will never change, but their name/email/profile pic/etc. can.
+  currentUser: 'currentUser'
+});
+
+/**
+ * Watchable keys in {@link Session}.
+ * - `currentUser`
+ * - `permissionLevel`
+ */
+
+/** @hidden */
+class SessionCore extends _abstract_model.default {
+  /** @internal */
+  static _className = 'SessionCore';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableSessionKeys, key);
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * @internal
+   */
+  constructor(sdk) {
+    super(sdk, 'session');
+    this._airtableInterface = sdk.__airtableInterface;
+    const {
+      permissionLevel,
+      currentUserId,
+      enabledFeatureNames
+    } = this._airtableInterface.sdkInitData.baseData;
+    this._sessionData = {
+      permissionLevel,
+      currentUserId,
+      enabledFeatureNames
+    };
+    Object.seal(this);
+  }
+
+  /**
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    return this._sessionData;
+  }
+
+  /**
+   * The current user, or `null` if the extension is running in a publicly shared base.
+   *
+   * @example
+   * ```js
+   * import {useSession} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function CurrentUser() {
+   *     const session = useSession();
+   *
+   *     if (!session.currentUser) {
+   *         return <div>This extension is being used in a public share.</div>;
+   *     }
+   *
+   *     return <ul>
+   *         <li>ID: {session.currentUser.id}</li>
+   *         <li>E-mail: {session.currentUser.email}</li>
+   *         <li>Name: {session.currentUser.name}</li>
+   *     </ul>;
+   * }
+   * ```
+   */
+  get currentUser() {
+    const userId = this._sessionData.currentUserId;
+    if (!userId) {
+      return null;
+    } else {
+      const {
+        base
+      } = this._sdk;
+      return base.getCollaboratorByIdIfExists(userId);
+    }
+  }
+  /**
+   * Returns true if `featureName` is enabled and automatically tracks an exposure.
+   *
+   * @internal
+   */
+  __isFeatureEnabled(featureName) {
+    this._airtableInterface.trackExposure(featureName);
+    return this.__peekIfFeatureIsEnabled(featureName);
+  }
+
+  /**
+   * Returns true if `featureName` is enabled; does not track an exposure.
+   *
+   * @internal
+   */
+  __peekIfFeatureIsEnabled(featureName) {
+    return this._sessionData.enabledFeatureNames.includes(featureName);
+  }
+
+  /**
+   * @internal
+   */
+  __applyChangesWithoutTriggeringEvents(changes) {
+    const changedKeys = {
+      [WatchableSessionKeys.permissionLevel]: false,
+      [WatchableSessionKeys.currentUser]: false
+    };
+    for (const {
+      path,
+      value
+    } of changes) {
+      if (path[0] === 'permissionLevel') {
+        (0, _error_utils.invariant)(path.length === 1, 'cannot set within permissionLevel');
+
+        // NOTE: just verify that the permission level is a string (rather than
+        // checking isEnumValue against PermissionLevels) in case new permission
+        // levels are added on the liveapp side. Permissions behavior gets routed
+        // through the checkPermissionsForMutation AirtableInterface helper, so we
+        // should still be able to handle unknown permission levels.
+        (0, _error_utils.invariant)(typeof value === 'string', 'permissionLevel must be a string');
+        this._sessionData.permissionLevel = value;
+        changedKeys[WatchableSessionKeys.permissionLevel] = true;
+      }
+
+      // TODO(emma): fire change only when the current user's info changes
+      if (path[0] === 'collaboratorsById') {
+        changedKeys[WatchableSessionKeys.currentUser] = true;
+      }
+    }
+    return changedKeys;
+  }
+  /**
+   * @internal
+   */
+  __triggerOnChangeForChangedKeys(changedKeys) {
+    for (const [key, didChange] of (0, _private_utils.entries)(changedKeys)) {
+      if (didChange) {
+        this._onChange(key);
+      }
+    }
+  }
+}
+exports.SessionCore = SessionCore;