@unseenco/theatre-core 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -1231,6 +1231,7 @@ type ISheetObjectOptions = {
     static?: readonly StaticPropPath[];
     __actions__THIS_API_IS_UNSTABLE_AND_WILL_CHANGE_IN_THE_NEXT_VERSION?: SheetObjectActionsConfig;
 };
+type ISheetPropsOptions = Omit<ISheetObjectOptions, 'visible' | 'showPropsOf'>;
 interface ISheet {
     /**
      * All sheets have `sheet.type === 'Theatre_Sheet_PublicAPI'`
@@ -1308,6 +1309,14 @@ interface ISheet {
      * ```
      */
     object<Props extends UnknownShorthandCompoundProps>(key: string, props: Props, options?: ISheetObjectOptions): ISheetObject<Props>;
+    /**
+     * Declares props scoped to the sheet (not a scene object). The returned handle
+     * behaves like a sheet object for `props`, `value`, `onValuesChange`, and
+     * Studio editing, but is hidden from {@link ISheet.getObjects} and the outline.
+     *
+     * Sheet props are shared across all sequence variants (static and sequenced).
+     */
+    props<Props extends UnknownShorthandCompoundProps>(config: Props, options?: ISheetPropsOptions): ISheetObject<Props>;
     /**
      * Detaches a previously created child object from the sheet.
      *

package/dist/index.js

@@ -4193,6 +4193,14 @@ function setDeepImmutable(obj, path, replace) {
 
 // core/src/sequences/sequenceVariants.ts
 var import_theatre_dataverse5 = require("@unseenco/theatre-dataverse");
+
+// shared/src/utils/sheetProps.ts
+var SHEET_PROPS_OBJECT_KEY = "__theatre_sheet_props__";
+function isSheetPropsObjectKey(objectKey) {
+  return objectKey === SHEET_PROPS_OBJECT_KEY;
+}
+
+// core/src/sequences/sequenceVariants.ts
 var DEFAULT_SEQUENCE_VARIANT = "default";
 function mergeSequenceTrackMaps(defaultTracks, overrideTracks, activeVariant) {
   const merged = {};
@@ -4222,6 +4230,9 @@ function getDefaultStaticOverridesByObject(sheetState) {
   return sheetState?.staticOverrides?.byObject;
 }
 function getEffectiveStaticOverrideForObject(sheetState, variantId, objectKey) {
+  if (isSheetPropsObjectKey(objectKey)) {
+    return getDefaultStaticOverridesByObject(sheetState)?.[objectKey];
+  }
   const defaultOverrides = getDefaultStaticOverridesByObject(sheetState)?.[objectKey];
   if (variantId === DEFAULT_SEQUENCE_VARIANT) {
     return defaultOverrides;
@@ -4409,7 +4420,8 @@ var SheetObject = class {
           withAhistoricStaticsCache
         );
         const activeVariant = (0, import_theatre_dataverse6.val)(this.sheet.effectiveActiveSequenceVariantD);
-        const statics = (0, import_theatre_dataverse6.val)(this.template.getStaticValues(activeVariant));
+        const staticVariant = isSheetPropsObjectKey(this.address.objectKey) ? DEFAULT_SEQUENCE_VARIANT : activeVariant;
+        const statics = (0, import_theatre_dataverse6.val)(this.template.getStaticValues(staticVariant));
         const withStaticsCache = import_theatre_dataverse6.prism.memo(
           "withStatics",
           () => /* @__PURE__ */ new WeakMap(),
@@ -4484,10 +4496,11 @@ var SheetObject = class {
   getSequencedValues() {
     return (0, import_theatre_dataverse6.prism)(() => {
       const activeVariant = (0, import_theatre_dataverse6.val)(this.sheet.effectiveActiveSequenceVariantD);
+      const sequenceVariant = isSheetPropsObjectKey(this.address.objectKey) ? DEFAULT_SEQUENCE_VARIANT : activeVariant;
       const tracksToProcessD = import_theatre_dataverse6.prism.memo(
         "tracksToProcess",
-        () => this.template.getArrayOfValidSequenceTracks(activeVariant),
-        [activeVariant]
+        () => this.template.getArrayOfValidSequenceTracks(sequenceVariant),
+        [sequenceVariant]
       );
       const tracksToProcess = (0, import_theatre_dataverse6.val)(tracksToProcessD);
       const valsAtom = new import_theatre_dataverse6.Atom({});
@@ -5424,6 +5437,9 @@ var SheetObjectTemplate = class {
       "getArrayOfValidSequenceTracks:".concat(sequenceVariant),
       () => (0, import_theatre_dataverse7.prism)(
         () => {
+          const effectiveSequenceVariant = isSheetPropsObjectKey(
+            this.address.objectKey
+          ) ? DEFAULT_SEQUENCE_VARIANT : sequenceVariant;
           const pointerToSheetState = this.project.pointers.historic.sheetsById[this.address.sheetId];
           (0, import_theatre_dataverse7.val)(pointerToSheetState.variantObjectOverrides);
           const defaultTrackIdByPropPath = valTrackIdByPropPathForObject(
@@ -5431,19 +5447,19 @@ var SheetObjectTemplate = class {
             DEFAULT_SEQUENCE_VARIANT,
             this.address.objectKey
           );
-          const variantTrackIdByPropPath = sequenceVariant === DEFAULT_SEQUENCE_VARIANT ? void 0 : valTrackIdByPropPathForObject(
+          const variantTrackIdByPropPath = effectiveSequenceVariant === DEFAULT_SEQUENCE_VARIANT ? void 0 : valTrackIdByPropPathForObject(
             pointerToSheetState,
-            sequenceVariant,
+            effectiveSequenceVariant,
             this.address.objectKey
           );
           const mergedTrackMap = mergeSequenceTrackMaps(
             defaultTrackIdByPropPath,
             variantTrackIdByPropPath,
-            sequenceVariant
+            effectiveSequenceVariant
           );
-          const unsequencedPropPaths = sequenceVariant === DEFAULT_SEQUENCE_VARIANT ? void 0 : valUnsequencedPropPathsForObject(
+          const unsequencedPropPaths = effectiveSequenceVariant === DEFAULT_SEQUENCE_VARIANT ? void 0 : valUnsequencedPropPathsForObject(
             pointerToSheetState,
-            sequenceVariant,
+            effectiveSequenceVariant,
             this.address.objectKey
           );
           const unsequencedPropPathSet = unsequencedPropPaths ? new Set(unsequencedPropPaths) : void 0;
@@ -6703,6 +6719,11 @@ var TheatreSheet = class {
       key,
       "sheet.object"
     );
+    if (isSheetPropsObjectKey(sanitizedPath)) {
+      throw new InvalidArgumentError(
+        'The key "'.concat(sanitizedPath, '" is reserved for sheet-level props. Use sheet.props() instead of sheet.object().')
+      );
+    }
     const existingObject = internal2.getObject(sanitizedPath);
     const nativeObject = null;
     const actions = opts?.__actions__THIS_API_IS_UNSTABLE_AND_WILL_CHANGE_IN_THE_NEXT_VERSION;
@@ -6799,6 +6820,74 @@ var TheatreSheet = class {
       return object.publicApi;
     }
   }
+  props(config, opts) {
+    const internal2 = privateAPI(this);
+    const objectKey = SHEET_PROPS_OBJECT_KEY;
+    const existingObject = internal2.getSheetPropsObject();
+    const nativeObject = null;
+    const actions = opts?.__actions__THIS_API_IS_UNSTABLE_AND_WILL_CHANGE_IN_THE_NEXT_VERSION;
+    if (existingObject) {
+      if (process.env.NODE_ENV !== "production") {
+        const prevConfig = getUnsanitizedObjectProps(existingObject);
+        if (prevConfig) {
+          if (!(0, import_fast_deep_equal2.default)(config, prevConfig)) {
+            if (opts?.reconfigure === true) {
+              const sanitizedConfig2 = compound(config);
+              existingObject.template.reconfigure(sanitizedConfig2);
+              if (opts.transient !== void 0) {
+                existingObject.template.setTransientPropPaths(
+                  opts.transient,
+                  sanitizedConfig2
+                );
+              }
+              if (opts.static !== void 0) {
+                existingObject.template.setStaticPropPaths(
+                  opts.static,
+                  sanitizedConfig2
+                );
+              }
+              setUnsanitizedObjectProps(existingObject, config);
+              return existingObject.publicApi;
+            } else {
+              throw new Error(
+                "You seem to have called sheet.props(config) twice, with different values for `config`. Use the same config on repeat calls, or pass `{reconfigure: true}` to change the schema."
+              );
+            }
+          }
+        }
+      }
+      if (actions) {
+        existingObject.template._temp_setActions(actions);
+      }
+      if (opts?.transient !== void 0) {
+        existingObject.template.setTransientPropPaths(
+          opts.transient,
+          existingObject.template.staticConfig
+        );
+      }
+      if (opts?.static !== void 0) {
+        existingObject.template.setStaticPropPaths(
+          opts.static,
+          existingObject.template.staticConfig
+        );
+      }
+      return existingObject.publicApi;
+    }
+    const sanitizedConfig = compound(config);
+    const object = internal2.createObject(
+      objectKey,
+      nativeObject,
+      sanitizedConfig,
+      actions,
+      false,
+      opts?.transient,
+      opts?.static
+    );
+    if (process.env.NODE_ENV !== "production") {
+      setUnsanitizedObjectProps(object, config);
+    }
+    return object.publicApi;
+  }
   get sequence() {
     return privateAPI(this).getSequence().publicApi;
   }
@@ -6823,6 +6912,11 @@ var TheatreSheet = class {
       key,
       'sheet.deleteObject("'.concat(key, '")')
     );
+    if (isSheetPropsObjectKey(sanitizedPath)) {
+      throw new InvalidArgumentError(
+        "Sheet props cannot be detached. They are removed when the sheet instance is unloaded."
+      );
+    }
     const obj = internal2.getObject(sanitizedPath);
     if (!obj) {
       notify.warning(
@@ -6929,9 +7023,12 @@ var Sheet = class {
   }
   getObjects() {
     return Object.values(this._objects.get()).filter(
-      (obj) => !!obj
+      (obj) => !!obj && !isSheetPropsObjectKey(obj.address.objectKey)
     );
   }
+  getSheetPropsObject() {
+    return this.getObject(SHEET_PROPS_OBJECT_KEY);
+  }
   deleteObject(objectKey) {
     const obj = this._objects.get()[objectKey];
     this._objects.reduce((state) => {
@@ -8552,7 +8649,7 @@ var CoreBundle = class {
     return "Theatre_CoreBundle";
   }
   get version() {
-    return "0.2.1";
+    return "0.2.3";
   }
   getBitsForStudio(studio, callback) {
     if (this._studio) {