@unseenco/theatre-core 0.2.3 → 0.3.0

package/README.md

@@ -7,30 +7,14 @@ Theatre.js can be used both programmatically _and_ visually.
 You can use Theatre.js to:
 
 * Animate 3D objects made with THREE.js or other 3D libraries
-  
-  ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-3d-short.gif)
-
-  <sub>Art by [drei.lu](https://sketchfab.com/models/91964c1ce1a34c3985b6257441efa500)</sub>
-
 * Animate HTML/SVG via React or other libraries
-
-  ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-dom.gif)
-
 * Design micro-interactions
-
-  ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-micro-interaction.gif)
-
 * Choreograph generative interactive art
-
-  ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-generative.gif)
-
 * Or animate any other JS variable
 
-  ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-console.gif)
-
-## Documentation and Tutorials
+## Documentation
 
-You can find the documentation and video tutorials [here](https://theatrejs.com/docs/latest).
+Guides and API reference live in the monorepo `docs/` workspace. Run `yarn docs:dev` from the repo root, or see the deployed site from [craftedbygc/theatre](https://github.com/craftedbygc/theatre).
 
 ## Community
 

package/dist/index.d.ts

@@ -312,6 +312,14 @@ type ShorthandCompoundPropsToLonghandCompoundProps<P extends UnknownShorthandCom
  *
  */
 declare function compoundFromSanitizedProps<Props extends UnknownValidCompoundProps>(sanitizedProps: Props, opts?: CommonOpts): PropTypeConfig_Compound<Props>;
+/**
+ * Shorthand compound prop type: plain object literals are sanitized into longhand prop configs.
+ *
+ * @example
+ * ```ts
+ * sheet.object('obj', types.compound({x: 0, y: 0}))
+ * ```
+ */
 declare const compound: <Props extends UnknownShorthandCompoundProps>(props: Props, opts?: CommonOpts) => PropTypeConfig_Compound<ShorthandCompoundPropsToLonghandCompoundProps<Props>>;
 /**
  * A file prop type
@@ -412,6 +420,12 @@ declare const number: (defaultValue: number, opts?: {
     precision?: number;
     label?: string;
 }) => PropTypeConfig_Number;
+/**
+ * RGBA color prop type factory.
+ *
+ * @param defaultValue - Initial color; defaults to opaque black
+ * @param opts - Optional `{ label }` for the Studio
+ */
 declare const rgba: (defaultValue?: Rgba, opts?: CommonOpts) => PropTypeConfig_Rgba;
 /**
  * A boolean prop type
@@ -521,6 +535,7 @@ opts?: {
  * ```
  */
 type Interpolator<T> = (left: T, right: T, progression: number) => T;
+/** Base shape shared by all Theatre prop type configurations. */
 interface IBasePropType<LiteralIdentifier extends string, ValueType, DeserializeType = ValueType> {
     /**
      * Each prop config has a string literal identifying it. For example,
@@ -531,6 +546,7 @@ interface IBasePropType<LiteralIdentifier extends string, ValueType, Deserialize
      * the `valueType` is only used by typescript. It won't be present in runtime.
      */
     valueType: ValueType;
+    /** Internal marker distinguishing Theatre prop configs from plain values. */
     [propTypeSymbol]: 'TheatrePropType';
     /**
      * Each prop type may be given a custom label instead of the name of the sub-prop
@@ -545,6 +561,7 @@ interface IBasePropType<LiteralIdentifier extends string, ValueType, Deserialize
      * ```
      */
     label: string | undefined;
+    /** Default value used when the prop has no override or keyframes. */
     default: ValueType;
     /**
      * Each prop config has a `deserializeAndSanitize()` function that deserializes and sanitizes
@@ -574,8 +591,11 @@ interface IBasePropType<LiteralIdentifier extends string, ValueType, Deserialize
 interface ISimplePropType<LiteralIdentifier extends string, ValueType> extends IBasePropType<LiteralIdentifier, ValueType, ValueType> {
     interpolate: Interpolator<ValueType>;
 }
+/** Number prop type configuration. */
 interface PropTypeConfig_Number extends ISimplePropType<'number', number> {
+    /** Optional min/max shown in the Studio number editor (not a runtime clamp). */
     range?: [min: number, max: number];
+    /** Custom nudging behavior when dragging the number in the Studio. */
     nudgeFn: NumberNudgeFn;
     /**
      * See {@link defaultNumberNudgeFn} to see how `nudgeMultiplier` is treated.
@@ -587,12 +607,14 @@ interface PropTypeConfig_Number extends ISimplePropType<'number', number> {
      */
     precision?: number;
 }
+/** Function that computes a new number when the user nudges a number prop in the Studio. */
 type NumberNudgeFn = (p: {
     deltaX: number;
     deltaFraction: number;
     magnitude: number;
     config: PropTypeConfig_Number;
 }) => number;
+/** Boolean prop type configuration. */
 interface PropTypeConfig_Boolean extends ISimplePropType<'boolean', boolean> {
 }
 type CommonOpts = {
@@ -610,14 +632,20 @@ type CommonOpts = {
      */
     label?: string;
 };
+/** String prop type configuration. */
 interface PropTypeConfig_String extends ISimplePropType<'string', string> {
 }
+/** String-literal prop type configuration (menu or switch UI in the Studio). */
 interface PropTypeConfig_StringLiteral<T extends string> extends ISimplePropType<'stringLiteral', T> {
+    /** Map of allowed values to human-readable labels in the Studio. */
     valuesAndLabels: Record<T, string>;
+    /** Whether the Studio renders a dropdown menu or a switch control. */
     as: 'menu' | 'switch';
 }
+/** RGBA color prop type configuration. */
 interface PropTypeConfig_Rgba extends ISimplePropType<'rgba', Rgba> {
 }
+/** Image (texture) prop type configuration. */
 interface PropTypeConfig_Image extends ISimplePropType<'image', Asset> {
     /**
      * When `false`, Studio edits are session-only and not written to persisted
@@ -625,22 +653,30 @@ interface PropTypeConfig_Image extends ISimplePropType<'image', Asset> {
      */
     persist: boolean;
 }
+/** File asset prop type configuration. */
 interface PropTypeConfig_File extends ISimplePropType<'file', File> {
 }
 type DeepPartialCompound<Props extends UnknownValidCompoundProps> = {
     [K in keyof Props]?: DeepPartial<Props[K]>;
 };
 type DeepPartial<Conf extends PropTypeConfig> = Conf extends PropTypeConfig_AllSimples ? Conf['valueType'] : Conf extends PropTypeConfig_Compound<infer T> ? DeepPartialCompound<T> : never;
+/** Compound (nested object) prop type configuration. */
 interface PropTypeConfig_Compound<Props extends UnknownValidCompoundProps> extends IBasePropType<'compound', {
     [K in keyof Props]: Props[K]['valueType'];
 }, DeepPartialCompound<Props>> {
+    /** Child prop configurations keyed by sub-prop name. */
     props: Record<keyof Props, PropTypeConfig>;
 }
+/** Enum (discriminated) prop type configuration with named cases. */
 interface PropTypeConfig_Enum extends IBasePropType<'enum', {}> {
+    /** Prop configs for each enum case name. */
     cases: Record<string, PropTypeConfig>;
+    /** Case name used when no value is set. */
     defaultCase: string;
 }
+/** Union of all simple (non-compound, non-enum) prop type configurations. */
 type PropTypeConfig_AllSimples = PropTypeConfig_Number | PropTypeConfig_Boolean | PropTypeConfig_String | PropTypeConfig_StringLiteral<$IntentionalAny> | PropTypeConfig_Rgba | PropTypeConfig_Image | PropTypeConfig_File;
+/** Any Theatre prop type configuration (simple, compound, or enum). */
 type PropTypeConfig = PropTypeConfig_AllSimples | PropTypeConfig_Compound<$IntentionalAny> | PropTypeConfig_Enum;
 
 type index_d_UnknownShorthandCompoundProps = UnknownShorthandCompoundProps;
@@ -700,6 +736,7 @@ type TransientPropPath = string | readonly (string | number)[];
 /** Same path format as {@link TransientPropPath}. */
 type StaticPropPath = TransientPropPath;
 
+/** Public API for a custom requestAnimationFrame driver that advances Theatre's core ticker. */
 interface IRafDriver {
     /**
      * All raf derivers have have `driver.type === 'Theatre_RafDriver_PublicAPI'`
@@ -822,6 +859,7 @@ type SheetObjectValuesChangeMeta = {
      */
     variant: SequenceVariantId;
 };
+/** Public API for a Theatre.js sheet object (animated props and Studio integration). */
 interface ISheetObject<Props extends UnknownShorthandCompoundProps = UnknownShorthandCompoundProps> {
     /**
      * All Objects will have `object.type === 'Theatre_SheetObject_PublicAPI'`
@@ -988,7 +1026,9 @@ interface IAttachAudioArgs {
      */
     destinationNode?: AudioNode;
 }
+/** Public API for a sheet's animation sequence (playback, playhead, and audio). */
 interface ISequence {
+    /** Discriminator for Theatre.js public sequence instances. */
     readonly type: 'Theatre_Sequence_PublicAPI';
     /**
      * Starts playback of a sequence.
@@ -1195,6 +1235,7 @@ interface ISequence {
 
 type SheetObjectAction = (object: ISheetObject) => void;
 type SheetObjectActionsConfig = Record<string, SheetObjectAction>;
+/** Options for {@link ISheet.object} beyond prop definitions (visibility, showPropsOf, etc.). */
 type ISheetObjectOptions = {
     reconfigure?: boolean;
     /**
@@ -1232,6 +1273,7 @@ type ISheetObjectOptions = {
     __actions__THIS_API_IS_UNSTABLE_AND_WILL_CHANGE_IN_THE_NEXT_VERSION?: SheetObjectActionsConfig;
 };
 type ISheetPropsOptions = Omit<ISheetObjectOptions, 'visible' | 'showPropsOf'>;
+/** Public API for a Theatre.js sheet (objects, sequence, and runtime lifecycle). */
 interface ISheet {
     /**
      * All sheets have `sheet.type === 'Theatre_Sheet_PublicAPI'`
@@ -1430,6 +1472,7 @@ type ISheetOptions = {
      */
     visible?: boolean;
 };
+/** Options passed to {@link getProject} when creating or attaching to a project. */
 type IProjectConfig = {
     /**
      * The state of the project, as [exported](https://www.theatrejs.com/docs/latest/manual/projects#state) by the studio.
@@ -1450,6 +1493,7 @@ type IProjectConfig = {
  * A Theatre.js project
  */
 interface IProject {
+    /** Discriminator for Theatre.js public project instances. */
     readonly type: 'Theatre_Project_PublicAPI';
     /**
      * If `@unseenco/theatre-studio` is used, this promise would resolve when studio has loaded
@@ -1478,6 +1522,14 @@ interface IProject {
      * **Docs: https://www.theatrejs.com/docs/latest/manual/sheets**
      */
     sheet(sheetId: string, instanceIdOrOpts?: string | ISheetOptions): ISheet;
+    /**
+     * Creates a Sheet under the project (overload with explicit `instanceId`).
+     *
+     * @param sheetId - Sheets are identified by their `sheetId`, which must be a string longer than 3 characters
+     * @param instanceId - Instance id when creating multiple instances of the same sheet
+     * @param opts - Optionally provide `{ visible: false }` to hide the sheet from the Studio outline panel
+     * @returns The newly created Sheet
+     */
     sheet(sheetId: string, instanceId: string, opts?: ISheetOptions): ISheet;
     /**
      * Returns all currently loaded sheet instances under this project.
@@ -1553,6 +1605,7 @@ type Notifiers = {
      */
     error: Notify;
 };
+/** User-facing notification helpers (success, warning, info, error) used by Theatre.js runtimes. */
 declare const notify: Notifiers;
 
 /**
@@ -1676,7 +1729,7 @@ declare function val<T>(pointer: PointerType<T>): T;
  * This type represents the object returned by `studio.createContnentOfSaveFile()`. It's
  * meant for advanced users who want to interact with the state of projects. In the vast
  * majority of cases, you __should not__ use this type. Either an API for your use-case
- * already exists, or you should open an issue on GitHub: https://github.com/theatre-js/theatre/issues
+ * already exists, or you should open an issue on GitHub: https://github.com/craftedbygc/theatre/issues
  *
  */
 type __UNSTABLE_Project_OnDiskState = OnDiskState;