@cesdk/cesdk-js 1.63.0-rc.2 → 1.63.0-rc.4

package/index.d.ts

@@ -3373,6 +3373,182 @@ export declare type ExportSceneAction = (options: {
  * The FeatureAPI allows you to enable or disable specific functionality
  * within the editor based on custom conditions or user permissions.
  *
+ * ## Understanding the Feature System
+ *
+ * The feature system uses a **predicate chain** to determine if a feature is enabled.
+ * There are two types of predicates:
+ *
+ * 1. **Boolean predicates** (e.g., `true` or `false`) - These are **always terminal** and immediately return their value.
+ * 2. **Function predicates** - The implementation decides whether to call `isPreviousEnable()` (continue chain) or return directly (end chain).
+ *
+ * ### Evaluation Order
+ *
+ * Predicates are evaluated in this order:
+ * 1. **`set()` predicates** (most recent first) - Evaluated **FIRST**
+ * 2. **`enable()`/`disable()` state** - Evaluated **LAST**
+ *
+ * This means **`set()` can override `enable()` and `disable()`**.
+ *
+ * ## Common Use Cases and Expected Outcomes
+ *
+ * ### Use Case 1: Simple Enable/Disable
+ *
+ * **Use `enable()` and `disable()` for simple on/off control:**
+ *
+ * ```typescript
+ * // Enable a feature with its default behavior
+ * cesdk.feature.enable('ly.img.delete');
+ * // isEnabled: true
+ *
+ * // Disable it
+ * cesdk.feature.disable('ly.img.delete');
+ * // isEnabled: false
+ *
+ * // Re-enable it
+ * cesdk.feature.enable('ly.img.delete');
+ * // isEnabled: true
+ * ```
+ *
+ * **Expected outcome:** `enable()` and `disable()` work together to toggle features on/off.
+ *
+ * ### Use Case 2: Custom Conditions with `set()`
+ *
+ * **Use `set()` when you need custom logic:**
+ *
+ * ```typescript
+ * // Enable delete only when something is selected
+ * cesdk.feature.set('ly.img.delete', ({ engine }) => {
+ *   return engine.block.findAllSelected().length > 0;
+ * });
+ * // isEnabled: depends on selection
+ *
+ * // Now calling disable() won't work because set() is evaluated first!
+ * cesdk.feature.disable('ly.img.delete');
+ * // isEnabled: still depends on selection (disable is ignored)
+ * ```
+ *
+ * **Expected outcome:** `set()` function predicates are evaluated before `disable()`,
+ * so `disable()` has no effect when a `set()` predicate exists.
+ *
+ * ### Use Case 3: Terminal Boolean Predicates
+ *
+ * **Boolean predicates are terminal - they stop the chain:**
+ *
+ * ```typescript
+ * cesdk.feature.enable('ly.img.delete'); // Default predicate: true
+ * cesdk.feature.set('ly.img.delete', false); // Adds false to front
+ * // Chain: [set(false), enable(true)]
+ * // Evaluation: false (stops here, never reaches enable)
+ * // isEnabled: false
+ *
+ * cesdk.feature.set('ly.img.delete', true); // Adds true to front
+ * // Chain: [set(true), set(false), enable(true)]
+ * // Evaluation: true (stops here, never reaches the rest)
+ * // isEnabled: true
+ * ```
+ *
+ * **Expected outcome:** The most recent `set()` call with a boolean wins because
+ * boolean predicates are terminal.
+ *
+ * ### Use Case 4: Layering Conditions with Functions
+ *
+ * **Function predicates can check previous conditions:**
+ *
+ * ```typescript
+ * // Base: Feature enabled by default
+ * cesdk.feature.enable('ly.img.delete');
+ *
+ * // Layer 1: Add selection requirement
+ * cesdk.feature.set('ly.img.delete', ({ isPreviousEnable, engine }) => {
+ *   const baseEnabled = isPreviousEnable(); // Checks enable(true)
+ *   const hasSelection = engine.block.findAllSelected().length > 0;
+ *   return baseEnabled && hasSelection;
+ * });
+ * // isEnabled: true only if enabled AND has selection
+ *
+ * // Layer 2: Add mode requirement
+ * cesdk.feature.set('ly.img.delete', ({ isPreviousEnable, engine }) => {
+ *   const previousEnabled = isPreviousEnable(); // Checks Layer 1
+ *   const isDesignMode = engine.scene.getMode() === 'Design';
+ *   return previousEnabled && isDesignMode;
+ * });
+ * // isEnabled: true only if all conditions met (mode + selection + enabled)
+ * ```
+ *
+ * **Expected outcome:** Each `set()` call with a function can build on previous
+ * conditions by calling `isPreviousEnable()`.
+ *
+ * ### Use Case 5: Overriding with `set()`
+ *
+ * **`set()` can completely override enable/disable:**
+ *
+ * ```typescript
+ * cesdk.feature.enable('ly.img.delete');
+ * cesdk.feature.disable('ly.img.delete');
+ * // isEnabled: false (disable overrides enable)
+ *
+ * // But set() overrides both:
+ * cesdk.feature.set('ly.img.delete', true);
+ * // Chain: [set(true), disable(false)]
+ * // isEnabled: true (set is terminal, disable never evaluated)
+ * ```
+ *
+ * **Expected outcome:** `set()` with a boolean always wins because it's evaluated
+ * first and is terminal.
+ *
+ * ### Use Case 6: Glob Patterns for Bulk Operations
+ *
+ * **Use wildcards to affect multiple features:**
+ *
+ * ```typescript
+ * // Enable all video features at once
+ * cesdk.feature.enable('ly.img.video.*');
+ *
+ * // Disable all crop features
+ * cesdk.feature.disable('ly.img.crop.*');
+ *
+ * // Set custom predicate for all navigation features
+ * cesdk.feature.set('ly.img.navigation.*', ({ engine }) => {
+ *   return engine.scene.getMode() === 'Design';
+ * });
+ *
+ * // Check if all video features are enabled
+ * const allVideoEnabled = cesdk.feature.isEnabled('ly.img.video.*');
+ * // Returns true only if ALL matching features are enabled
+ * ```
+ *
+ * **Expected outcome:** Glob patterns match multiple features. `isEnabled()` with
+ * a glob returns `true` only if **all** matching features are enabled.
+ *
+ * ### Use Case 7: Role-Based Access Control
+ *
+ * **Implement permissions using predicates:**
+ *
+ * ```typescript
+ * const userRole = 'editor'; // Could be 'viewer', 'editor', 'admin'
+ *
+ * cesdk.feature.set('ly.img.delete', () => {
+ *   return userRole === 'editor' || userRole === 'admin';
+ * });
+ *
+ * cesdk.feature.set('ly.img.settings', () => {
+ *   return userRole === 'admin';
+ * });
+ * ```
+ *
+ * **Expected outcome:** Features are enabled based on user roles, with predicates
+ * evaluated on every check.
+ *
+ * ## Key Principles
+ *
+ * 1. **Use `enable()` for simple on/off** - Works with default predicates
+ * 2. **Use `disable()` to turn off enabled features** - Only works if no `set()` predicates exist
+ * 3. **Use `set()` for custom logic** - Overrides `enable()`/`disable()`
+ * 4. **Boolean predicates are terminal** - Stop evaluation immediately
+ * 5. **Function predicates can chain** - Call `isPreviousEnable()` to continue
+ * 6. **Most recent `set()` wins** - Evaluated in LIFO order (most recent first)
+ * 7. **Glob patterns affect multiple features** - Use `*` as wildcard
+ *
  * @categoryDescription Feature Control
  * Methods for enabling and checking the status of editor features based on custom predicates.
  *