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

package/dist/cjs/shared/types/mutation_constants.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MAX_TABLE_NAME_LENGTH = exports.MAX_NUM_FIELDS_PER_TABLE = exports.MAX_FIELD_NAME_LENGTH = exports.MAX_FIELD_DESCRIPTION_LENGTH = void 0;
+// Mirrored from clientServerSharedConfigSettings
+var MAX_FIELD_NAME_LENGTH = exports.MAX_FIELD_NAME_LENGTH = 255;
+var MAX_FIELD_DESCRIPTION_LENGTH = exports.MAX_FIELD_DESCRIPTION_LENGTH = 20000;
+var MAX_TABLE_NAME_LENGTH = exports.MAX_TABLE_NAME_LENGTH = 255;
+var MAX_NUM_FIELDS_PER_TABLE = exports.MAX_NUM_FIELDS_PER_TABLE = 500;

package/dist/cjs/shared/types/mutations_core.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MutationTypesCore = void 0;
+/** @module @airtable/blocks: mutations */ /** */
+
+/** @hidden */
+var MutationTypesCore = exports.MutationTypesCore = Object.freeze({
+  SET_MULTIPLE_GLOBAL_CONFIG_PATHS: 'setMultipleGlobalConfigPaths'
+});
+
+// /** @hidden */
+// export type MutationType = ObjectValues<typeof MutationTypesCore>;
+
+/**
+ * The Mutation emitted when the App modifies one or more values in the
+ * {@link GlobalConfig}.
+ *
+ * @docsPath testing/mutations/SetMultipleGlobalConfigPathsMutation
+ */
+
+/** @hidden */
+
+/** @hidden */
+
+/** @hidden */
+
+/** */
+
+/** */
+
+/** Indicates whether the user has permission to perform a particular action, and if not, why. */

package/dist/cjs/shared/types/permission_levels.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PermissionLevels = void 0;
+/** @hidden */
+var PermissionLevels = exports.PermissionLevels = Object.freeze({
+  NONE: 'none',
+  READ: 'read',
+  COMMENT: 'comment',
+  EDIT: 'edit',
+  CREATE: 'create',
+  OWNER: 'owner'
+});
+
+/** @hidden */

package/dist/cjs/shared/types/record.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cjs/shared/types/stat.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cjs/shared/types/table_core.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cjs/shared/ui/global_config_synced_component_helpers.js

@@ -0,0 +1,27 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _airtable_interface = require("../../base/types/airtable_interface");
+var _use_watchable = _interopRequireDefault(require("./use_watchable"));
+var _sdk_context = require("./sdk_context");
+/** @hidden */
+var globalConfigSyncedComponentHelpers = {
+  globalConfigKeyPropType: _propTypes.default.oneOfType([_propTypes.default.string.isRequired, _propTypes.default.arrayOf(_propTypes.default.string.isRequired).isRequired]).isRequired,
+  useDefaultWatchesForSyncedComponent(globalConfigKey) {
+    var sdk = (0, _sdk_context.useSdk)();
+    var globalConfig = sdk.globalConfig,
+      session = sdk.session;
+    var runContext = sdk.getBlockRunContext();
+    (0, _use_watchable.default)(globalConfig, [globalConfig.__getTopLevelKey(globalConfigKey)]);
+    (0, _use_watchable.default)(session, ['permissionLevel']);
+    var viewIfInViewContext = runContext.type === _airtable_interface.BlockRunContextType.VIEW ? sdk.base.getTableById(runContext.tableId).getViewById(runContext.viewId) : null;
+    // We can't conditionally watch, but if it's not a viewContext the model will be null.
+    (0, _use_watchable.default)(viewIfInViewContext, ['isLockedView']);
+  }
+};
+var _default = exports.default = globalConfigSyncedComponentHelpers;

package/dist/cjs/shared/ui/loader.js

@@ -0,0 +1,68 @@
+"use strict";
+
+require("core-js/modules/es.symbol.js");
+require("core-js/modules/es.array.filter.js");
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.object.get-own-property-descriptors.js");
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.weak-map.js");
+require("core-js/modules/web.dom-collections.for-each.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 _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+require("core-js/modules/es.array.concat.js");
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var React = _interopRequireWildcard(require("react"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(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 ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+var ORIGINAL_SIZE = 54;
+
+/**
+ * @internal
+ */
+
+// Override the default props and then just proxy through to our loader.
+/**
+ * @internal
+ */
+var Loader = props => {
+  var fillColor = props.fillColor,
+    scale = props.scale,
+    className = props.className,
+    style = props.style;
+  return /*#__PURE__*/React.createElement("svg", {
+    width: ORIGINAL_SIZE * scale,
+    height: ORIGINAL_SIZE * scale,
+    viewBox: "0 0 ".concat(ORIGINAL_SIZE, " ").concat(ORIGINAL_SIZE),
+    className: className,
+    style: _objectSpread({
+      shapeRendering: 'geometricPrecision'
+    }, style)
+  }, /*#__PURE__*/React.createElement("g", null, /*#__PURE__*/React.createElement("path", {
+    d: "M10.9,48.6c-1.6-1.3-2-3.6-0.7-5.3c1.3-1.6,3.6-2.1,5.3-0.8c0.8,0.5,1.5,1.1,2.4,1.5c7.5,4.1,16.8,2.7,22.8-3.4c1.5-1.5,3.8-1.5,5.3,0c1.4,1.5,1.4,3.9,0,5.3c-8.4,8.5-21.4,10.6-31.8,4.8C13,50.1,11.9,49.3,10.9,48.6z",
+    fill: fillColor
+  }), /*#__PURE__*/React.createElement("path", {
+    d: "M53.6,31.4c-0.3,2.1-2.3,3.5-4.4,3.2c-2.1-0.3-3.4-2.3-3.1-4.4c0.2-1.1,0.2-2.2,0.2-3.3c0-8.7-5.7-16.2-13.7-18.5c-2-0.5-3.2-2.7-2.6-4.7s2.6-3.2,4.7-2.6C46,4.4,53.9,14.9,53.9,27C53.9,28.5,53.8,30,53.6,31.4z",
+    fill: fillColor
+  }), /*#__PURE__*/React.createElement("path", {
+    d: "M16.7,1.9c1.9-0.8,4.1,0.2,4.8,2.2s-0.2,4.2-2.1,5c-7.2,2.9-12,10-12,18.1c0,1.6,0.2,3.2,0.6,4.7c0.5,2-0.7,4.1-2.7,4.6c-2,0.5-4-0.7-4.5-2.8C0.3,31.5,0,29.3,0,27.1C0,15.8,6.7,5.9,16.7,1.9z",
+    fill: fillColor
+  })));
+};
+Loader.propTypes = {
+  fillColor: _propTypes.default.string.isRequired,
+  scale: _propTypes.default.number.isRequired,
+  className: _propTypes.default.string,
+  style: _propTypes.default.object
+};
+Loader.defaultProps = {
+  fillColor: '#888',
+  scale: 0.3
+};
+var _default = exports.default = Loader;

package/dist/cjs/shared/ui/remote_utils.js

@@ -0,0 +1,92 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.loadCSSFromString = loadCSSFromString;
+exports.loadCSSFromURLAsync = loadCSSFromURLAsync;
+exports.loadScriptFromURLAsync = loadScriptFromURLAsync;
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.promise.js");
+var _error_utils = require("../error_utils");
+/** @module @airtable/blocks/ui: Loading external resources */ /** */
+
+/**
+ * Injects CSS from a string into the page. Returns the HTML style element inserted into the page.
+ *
+ * @param css The CSS string.
+ * @example
+ * ```js
+ * import {loadCSSFromString} from '@airtable/blocks/ui';
+ * loadCSSFromString('body { background: red; }');
+ * ```
+ * @docsPath UI/utils/loadCSSFromString
+ */
+function loadCSSFromString(css) {
+  var styleTag = document.createElement('style');
+  styleTag.innerHTML = css;
+  (0, _error_utils.invariant)(document.head, 'no document head');
+  document.head.appendChild(styleTag);
+  return styleTag;
+}
+
+/**
+ * Injects CSS from a remote URL.
+ *
+ * Returns a promise that resolves to the HTML style element inserted into the page.
+ *
+ * @param url The URL of the stylesheet.
+ * @example
+ * ```js
+ * import {loadCSSFromURLAsync} from '@airtable/blocks/ui';
+ * loadCSSFromURLAsync('https://example.com/style.css');
+ * ```
+ * @docsPath UI/utils/loadCSSFromURLAsync
+ */
+function loadCSSFromURLAsync(url) {
+  // Pre-create the error for a nicer stack trace.
+  var loadError = new Error('Failed to load remote CSS: ' + url);
+  return new Promise((resolve, reject) => {
+    var linkTag = document.createElement('link');
+    linkTag.setAttribute('rel', 'stylesheet');
+    linkTag.setAttribute('href', url);
+    linkTag.addEventListener('load', () => {
+      resolve(linkTag);
+    });
+    linkTag.addEventListener('error', () => {
+      reject(loadError);
+    });
+    (0, _error_utils.invariant)(document.head, 'no document head');
+    document.head.appendChild(linkTag);
+  });
+}
+
+/**
+ * Injects Javascript from a remote URL.
+ *
+ * Returns a promise that resolves to the HTML script element inserted into the page.
+ *
+ * @param url The URL of the script.
+ * @example
+ * ```js
+ * import {loadScriptFromURLAsync} from '@airtable/blocks/ui';
+ * loadScriptFromURLAsync('https://example.com/script.js');
+ * ```
+ * @docsPath UI/utils/loadScriptFromURLAsync
+ */
+function loadScriptFromURLAsync(url) {
+  // Pre-create the error for a nicer stack trace.
+  var loadError = new Error('Failed to load remote script: ' + url);
+  return new Promise((resolve, reject) => {
+    var scriptTag = document.createElement('script');
+    scriptTag.addEventListener('load', () => {
+      resolve(scriptTag);
+    });
+    scriptTag.addEventListener('error', () => {
+      reject(loadError);
+    });
+    scriptTag.setAttribute('src', url);
+    (0, _error_utils.invariant)(document.head, 'no document head');
+    document.head.appendChild(scriptTag);
+  });
+}

package/dist/cjs/shared/ui/sdk_context.js

@@ -0,0 +1,21 @@
+"use strict";
+
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.weak-map.js");
+require("core-js/modules/web.dom-collections.iterator.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useSdk = exports.SdkContext = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _error_utils = require("../error_utils");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(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; }
+var SdkContext = exports.SdkContext = /*#__PURE__*/React.createContext(null);
+var useSdk = () => {
+  var sdk = React.useContext(SdkContext);
+  (0, _error_utils.invariant)(sdk, 'This component can only be used in a block. Make sure to use `initializeBlock` at the root of this component tree.');
+  return sdk;
+};
+exports.useSdk = useSdk;

package/dist/cjs/shared/ui/use_array_identity.js

@@ -0,0 +1,32 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useArrayIdentity;
+var _react = require("react");
+/**
+ * As long as the array passed to this hook shallow-equals its previous value, this hook will
+ * return the same array instance. This is useful when writing hooks that accept arrays - it might
+ * be convenient for the consumer of the hook to write their array inline, but that won't have
+ * have referential equality which might make using the array with `useEffect` or similar tricky.
+ * `useArrayIdentity` can wrap that array, making it easier to use with hooks like `useEffect`.
+ *
+ * @internal
+ */
+function useArrayIdentity(array) {
+  var arrayRef = (0, _react.useRef)(array);
+  if (arrayRef.current !== array) {
+    if (arrayRef.current.length !== array.length) {
+      arrayRef.current = array;
+    } else {
+      for (var i = 0; i < array.length; i++) {
+        if (arrayRef.current[i] !== array[i]) {
+          arrayRef.current = array;
+          break;
+        }
+      }
+    }
+  }
+  return arrayRef.current;
+}

package/dist/cjs/shared/ui/use_base.js

@@ -0,0 +1,21 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _use_watchable = _interopRequireDefault(require("./use_watchable"));
+var _sdk_context = require("./sdk_context");
+/**
+ * @hidden
+ */
+var useBase = () => {
+  var _useSdk = (0, _sdk_context.useSdk)(),
+    base = _useSdk.base,
+    session = _useSdk.session;
+  (0, _use_watchable.default)(base, ['schema']);
+  (0, _use_watchable.default)(session, ['permissionLevel']);
+  return base;
+};
+var _default = exports.default = useBase;

package/dist/cjs/shared/ui/use_global_config.js

@@ -0,0 +1,47 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useGlobalConfig;
+var _use_watchable = _interopRequireDefault(require("./use_watchable"));
+var _sdk_context = require("./sdk_context");
+/** @module @airtable/blocks/ui: useGlobalConfig */ /** */
+
+/**
+ * Returns the extension's {@link GlobalConfig} and updates whenever any key in {@link GlobalConfig}
+ * changes.
+ *
+ * @example
+ * ```js
+ * import {Button, useGlobalConfig} from '@airtable/blocks/ui';
+ *
+ * function SyncedCounter() {
+ *     const globalConfig = useGlobalConfig();
+ *     const count = globalConfig.get('count');
+ *
+ *     const increment = () => globalConfig.setAsync('count', count + 1);
+ *     const decrement = () => globalConfig.setAsync('count', count - 1);
+ *     const isEnabled = globalConfig.hasPermissionToSet('count');
+ *
+ *     return (
+ *         <React.Fragment>
+ *             <Button icon="minus" onClick={decrement} disabled={!isEnabled} ariaLabel="decrease"/>
+ *             {count}
+ *             <Button icon="plus" onClick={increment} disabled={!isEnabled} ariaLabel="increase"/>
+ *         </React.Fragment>
+ *     );
+ * }
+ * ```
+ * @docsPath UI/hooks/useGlobalConfig
+ * @hook
+ */
+function useGlobalConfig() {
+  var _useSdk = (0, _sdk_context.useSdk)(),
+    globalConfig = _useSdk.globalConfig,
+    session = _useSdk.session;
+  (0, _use_watchable.default)(session, ['permissionLevel']);
+  (0, _use_watchable.default)(globalConfig, ['*']);
+  return globalConfig;
+}

package/dist/cjs/shared/ui/use_loadable.js

@@ -0,0 +1,240 @@
+"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.slice.js");
+require("core-js/modules/es.regexp.exec.js");
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useLoadable;
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.array.map.js");
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.promise.js");
+require("core-js/modules/es.regexp.to-string.js");
+require("core-js/modules/web.dom-collections.iterator.js");
+var _react = require("react");
+var _useSubscription = require("use-subscription");
+var _private_utils = require("../private_utils");
+var _error_utils = require("../error_utils");
+var _use_array_identity = _interopRequireDefault(require("./use_array_identity"));
+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; } /** @module @airtable/blocks/ui: useLoadable */ /** */
+// rather than asking for an AbstractModelWithAsyncData, we define a much more specific interface
+// that enforces 'isDataLoaded' as a watchable key.
+/**
+ * A model that can be loaded.
+ * Usually a {@link Cursor}, {@link RecordQueryResult}, or a {@link ViewMetadataQueryResult}.
+ */
+
+var SUSPENSE_CLEAN_UP_MS = 60000;
+
+/**
+ * Options object for the {@link useLoadable} hook.
+ */
+
+/**
+ * When you're writing an extension, not all of the data in your base is available to work with straight
+ * away. We need to load it from Airtable first. This hook is a low-level tool for managing that.
+ * You might not need to use it directly though - if you're working with a {@link RecordQueryResult}, try
+ * {@link useRecords}, {@link useRecordIds}, or {@link useRecordById} first.
+ *
+ * When you need to use a loadable model, `useLoadable(theModel)` will make sure that the model is
+ * loaded when your component mounts, and unloaded when your component unmounts. By default, you
+ * don't need to worry about waiting for the data to load - the hook uses React Suspense to make
+ * sure the rest of your component doesn't run until the data is loaded. Whilst the data is
+ * loading, the entire extension will show a loading indicator. If you want to change where that
+ * indicator shows or how it looks, use [`<React.Suspense />`](https://reactjs.org/docs/react-api.html#reactsuspense|)
+ * around the component that uses the hook.
+ *
+ * You can pass several models to `useLoadable` in an array - it will load all of them simultaneously.
+ * We'll memoize this array using shallow equality, so there's no need to use `useMemo`.
+ *
+ * If you need more control, you can pass `{shouldSuspend: false}` as a second argument to
+ * the hook. In that case though, `useLoadable` will cause your component to re-render whenever the
+ * load-state of any model you passed in changes, and you should check each model's `.isDataLoaded`
+ *  property before trying to use the data you loaded.
+ *
+ * @param models The models to load.
+ * @param opts Optional options to control how the hook works.
+ *
+ * @example
+ * ```js
+ * import {useCursor, useLoadable, useWatchable} from '@airtable/blocks/ui';
+ *
+ *  function SelectedRecordIds() {
+ *      const cursor = useCursor();
+ *      // load selected records
+ *      useLoadable(cursor);
+ *
+ *      // re-render whenever the list of selected records changes
+ *      useWatchable(cursor, ['selectedRecordIds']);
+ *
+ *      // render the list of selected record ids
+ *      return <div>Selected records: {cursor.selectedRecordIds.join(', ')}</div>;
+ *  }
+ * ```
+ *
+ * @example
+ * ```js
+ *  import {useLoadable} from '@airtable/blocks/ui';
+ *
+ *  function LoadTwoQueryResults({queryResultA, queryResultB}) {
+ *      // load the queryResults:
+ *      useLoadable([queryResultA, queryResultB]);
+ *
+ *      // now, we can use the data
+ *      return <SomeFancyComponent />;
+ *  }
+ * ```
+ *
+ * @example
+ * ```js
+ *  import {useLoadable, useBase} from '@airtable/blocks/ui';
+ *
+ *  function LoadAllRecords() {
+ *      const base = useBase();
+ *
+ *      // get a query result for every table in the base:
+ *      const queryResults = base.tables.map(table => table.selectRecords());
+ *
+ *      // load them all:
+ *      useLoadable(queryResults);
+ *
+ *      // use the data:
+ *      return <SomeFancyComponent queryResults={queryResults} />;
+ *  }
+ * ```
+ * @docsPath UI/hooks/useLoadable
+ * @hook
+ */
+function useLoadable(models) {
+  var opts = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {
+    shouldSuspend: true
+  };
+  var shouldSuspend = opts && (0, _private_utils.has)(opts, 'shouldSuspend') ? opts.shouldSuspend : true;
+  var constModels = (0, _use_array_identity.default)(Array.isArray(models) ? models : [models]);
+  var compactModels = (0, _react.useMemo)(() => {
+    var compacted = (0, _private_utils.compact)(constModels);
+    var _iterator = _createForOfIteratorHelper(compacted),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var model = _step.value;
+        if (typeof model.loadDataAsync !== 'function') {
+          throw (0, _error_utils.spawnError)('useLoadable called with %s, which is not a loadable', typeof model === 'object' ? model.toString() : typeof model);
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    return compacted;
+  }, [constModels]);
+
+  // .every returns `true` in the case of an empty array
+  var areAllModelsLoaded = compactModels.every(model => model.isDataLoaded);
+  if (shouldSuspend && !areAllModelsLoaded) {
+    var suspensePromise = Promise.all(compactModels.map(model => model.loadDataAsync())).then(() => {
+      // if data isn't loaded and we're in suspense mode, we need to start the data loading and
+      // throw the load promise. when we throw though, the render tree gets thrown away and none
+      // of out hooks will be retained - so we can't attach this QueryResult to a component
+      // lifecycle and use that to unload it. Instead, we load it and keep it loaded for a long
+      // enough time that it can resolve and then be rendered successfully. After the timeout has
+      // passed, we unload it, allowing the data to be released as long as it's not used anywhere
+      // else in the extension.
+      setTimeout(() => {
+        var _iterator2 = _createForOfIteratorHelper(compactModels),
+          _step2;
+        try {
+          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+            var model = _step2.value;
+            model.unloadData();
+          }
+        } catch (err) {
+          _iterator2.e(err);
+        } finally {
+          _iterator2.f();
+        }
+      }, SUSPENSE_CLEAN_UP_MS);
+    }).catch(error => {
+      // eslint-disable-next-line no-console
+      console.error(error);
+      throw error;
+    });
+    throw suspensePromise;
+  }
+
+  // re-render when loaded state changes. technically, we could use `useWatchable` here, but as
+  // our LoadableModel isn't a Watchable, we can't. There's no way to preserve flow errors when
+  // watching something that doesn't have a 'isDataLoaded' watch key and use `Watchable`.
+  var modelIsLoadedSubscription = (0, _react.useMemo)(() => ({
+    getCurrentValue: () => compactModels.map(model => model.isDataLoaded).join(','),
+    subscribe: onChange => {
+      var _iterator3 = _createForOfIteratorHelper(compactModels),
+        _step3;
+      try {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var model = _step3.value;
+          model.watch('isDataLoaded', onChange);
+        }
+      } catch (err) {
+        _iterator3.e(err);
+      } finally {
+        _iterator3.f();
+      }
+      return () => {
+        var _iterator4 = _createForOfIteratorHelper(compactModels),
+          _step4;
+        try {
+          for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+            var model = _step4.value;
+            model.unwatch('isDataLoaded', onChange);
+          }
+        } catch (err) {
+          _iterator4.e(err);
+        } finally {
+          _iterator4.f();
+        }
+      };
+    }
+  }), [compactModels]);
+  (0, _useSubscription.useSubscription)(modelIsLoadedSubscription);
+
+  // the main part of this hook comes down to managing the query result data loading in sync with
+  // the component lifecycle. That means loading the data when the component mounts, and
+  // unloading it when the component unmounts.
+  (0, _react.useEffect)(() => {
+    var _iterator5 = _createForOfIteratorHelper(compactModels),
+      _step5;
+    try {
+      for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+        var model = _step5.value;
+        model.loadDataAsync();
+      }
+    } catch (err) {
+      _iterator5.e(err);
+    } finally {
+      _iterator5.f();
+    }
+    return () => {
+      var _iterator6 = _createForOfIteratorHelper(compactModels),
+        _step6;
+      try {
+        for (_iterator6.s(); !(_step6 = _iterator6.n()).done;) {
+          var model = _step6.value;
+          model.unloadData();
+        }
+      } catch (err) {
+        _iterator6.e(err);
+      } finally {
+        _iterator6.f();
+      }
+    };
+  }, [compactModels]);
+}

package/dist/cjs/shared/ui/use_session.js

@@ -0,0 +1,20 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _use_watchable = _interopRequireDefault(require("./use_watchable"));
+var _sdk_context = require("./sdk_context");
+/** @internal */
+var useSession = () => {
+  var _useSdk = (0, _sdk_context.useSdk)(),
+    session = _useSdk.session,
+    base = _useSdk.base;
+  (0, _use_watchable.default)(session, ['permissionLevel', 'currentUser']);
+  // permission checks depend on the base schema, so we need to track that too:
+  (0, _use_watchable.default)(base, ['schema']);
+  return session;
+};
+var _default = exports.default = useSession;