dazscript-framework 1.0.15 → 1.0.16

package/README.md

@@ -501,7 +501,7 @@ The framework ships helpers for common Daz Studio tasks, all importable from `@d
 |---|---|
 | `scene-helper` | `getRoot()`, `getSelectedNode()`, `getNodes()` |
 | `node-helper` | Type checks (`isFigure`, `isBone`), transforms, visibility |
-| `property-helper` | Find, read, and adjust node properties |
+| `property-helper` | Set paths, unlock, cast numeric types, and inspect property inputs/outputs |
 | `array-helper` | `distinct()`, `flatten()`, `groupBy()` |
 | `string-helper` | Case, trimming, splitting |
 | `directory-helper` | File and path operations |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",

package/src/helpers/message-box-helper.test.ts

@@ -0,0 +1,43 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { confirm, prompt } from './message-box-helper'
+
+vi.mock('@dsf/common/log', () => ({ debug: vi.fn() }))
+
+describe('message-box-helper', () => {
+    const question = vi.fn()
+
+    beforeEach(() => {
+        question.mockReset()
+        vi.stubGlobal('MessageBox', { question })
+    })
+
+    it('treats the first confirm button as ok', () => {
+        question.mockReturnValue(0)
+
+        expect(confirm('Continue?')).toEqual({ ok: true, cancel: false })
+    })
+
+    it('treats the second confirm button as cancel', () => {
+        question.mockReturnValue(1)
+
+        expect(confirm('Continue?')).toEqual({ ok: false, cancel: true })
+    })
+
+    it('treats the first prompt button as cancel so Esc is also cancel', () => {
+        question.mockReturnValue(0)
+
+        expect(prompt('Reset?', 'Reset', 'Zero', 'Default')).toEqual({ cancel: true, selection: -1 })
+    })
+
+    it('maps the second prompt button to the first selection', () => {
+        question.mockReturnValue(1)
+
+        expect(prompt('Reset?', 'Reset', 'Zero', 'Default')).toEqual({ cancel: false, selection: 0 })
+    })
+
+    it('maps the third prompt button to the second selection', () => {
+        question.mockReturnValue(2)
+
+        expect(prompt('Reset?', 'Reset', 'Zero', 'Default')).toEqual({ cancel: false, selection: 1 })
+    })
+})

package/src/helpers/message-box-helper.ts

@@ -20,7 +20,7 @@ export const confirm = (message?: string): { ok: boolean, cancel: boolean } => {
 }
 
 export const prompt = (text: string, title: string, button0: string, button1?: string): { cancel: boolean, selection: number } => {
-    const response = MessageBox.question(text, title, button0, button1 ?? "", "Cancel")
+    const response = MessageBox.question(text, title, "Cancel", button0, button1 ?? "")
 
-    return { cancel: response === 0, selection: response };
-}
+    return { cancel: response === 0, selection: response - 1 };
+}

package/src/helpers/property-helper.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest'
+import { getPropertyInputs, getPropertyOutputs } from './property-helper'
+
+vi.mock('@dsf/core/global', () => ({
+    sceneHelper: {
+        getInternalName: vi.fn(),
+        getNode: vi.fn(),
+        getUniqueMorphName: vi.fn(),
+        setInternalName: vi.fn(),
+        setPropertyPath: vi.fn()
+    }
+}))
+
+describe('property-helper relationships', () => {
+    const property = (name: string, inheritsTypes: string[] = []) => ({
+        name,
+        inherits: (type: string) => inheritsTypes.indexOf(type) >= 0,
+        getNumControllers: () => 0,
+        getController: () => null,
+        getNumSlaveControllers: () => 0,
+        getSlaveController: () => null,
+        getLinkProperty: () => null,
+        getFollowProperty: () => null
+    }) as any
+
+    it('gets input properties from normal and redirected controller properties', () => {
+        const driver = property('driver')
+        const redirectedDriver = property('redirectedDriver')
+        const controller = {
+            getProperty: () => driver,
+            getCurrentProperty: () => redirectedDriver
+        }
+        const driven = {
+            ...property('driven'),
+            getNumControllers: () => 1,
+            getController: () => controller
+        }
+
+        expect(getPropertyInputs(driven as any)).toEqual([
+            { property: driver, controller, source: 'controller' },
+            { property: redirectedDriver, controller, source: 'currentController' }
+        ])
+    })
+
+    it('gets input properties from direct numeric link and follow properties', () => {
+        const link = property('link')
+        const follow = property('follow')
+        const driven = {
+            ...property('driven', ['DzNumericProperty', 'DzFloatProperty']),
+            getLinkProperty: () => link,
+            getFollowProperty: () => follow
+        }
+
+        expect(getPropertyInputs(driven as any)).toEqual([
+            { property: link, controller: null, source: 'link' },
+            { property: follow, controller: null, source: 'follow' }
+        ])
+    })
+
+    it('gets output properties from slave controller owners', () => {
+        const output = property('output')
+        const controller = {
+            getOwner: () => output
+        }
+        const driver = {
+            ...property('driver'),
+            getNumSlaveControllers: () => 1,
+            getSlaveController: () => controller
+        }
+
+        expect(getPropertyOutputs(driver as any)).toEqual([
+            { property: output, controller, source: 'slaveController' }
+        ])
+    })
+
+    it('does not duplicate the same relation', () => {
+        const driver = property('driver')
+        const controller = {
+            getProperty: () => driver,
+            getCurrentProperty: () => driver
+        }
+        const driven = {
+            ...property('driven'),
+            getNumControllers: () => 2,
+            getController: () => controller
+        }
+
+        expect(getPropertyInputs(driven as any)).toEqual([
+            { property: driver, controller, source: 'controller' },
+            { property: driver, controller, source: 'currentController' }
+        ])
+    })
+
+})

package/src/helpers/property-helper.ts

@@ -1,5 +1,19 @@
 import { sceneHelper } from '@dsf/core/global'
 
+export type PropertyRelationSource = 'controller' | 'currentController' | 'link' | 'follow' | 'slaveController'
+
+/**
+ * A property relationship discovered from Daz controller, link, follow, or slave-controller APIs.
+ */
+export type PropertyRelation = {
+    /** The related input or output property. */
+    property: DzProperty
+    /** The controller that exposed the relation, or null for direct numeric property links. */
+    controller: DzController | null
+    /** The Daz API surface that exposed the relation. */
+    source: PropertyRelationSource
+}
+
 /**
  * Sets the DzPropertyGroup path (and appropriate geometryregion_dz) for the given property.
  * @param property  The property to change the path of.
@@ -18,6 +32,11 @@ export const getName = (property: DzProperty): string => {
     return sceneHelper.getInternalName(property).valueOf()
 }
 
+/**
+ * Ensures the property's internal name is unique on its owning node.
+ * @param property The property whose internal name should be checked.
+ * @returns The unique internal name assigned to the property.
+ */
 export const ensureNameIsUnique = (property: DzProperty): string => {
     const name = getName(property)
     const uniqueName = sceneHelper.getUniqueMorphName(sceneHelper.getNode(property), name)
@@ -39,24 +58,122 @@ export const unlock = (property: DzProperty, then: (property: DzProperty) => voi
     if (locked) property.lock(false)
 }
 
+/**
+ * Adds a property relation unless the same property, controller, and source were already collected.
+ * @param relations The relation collection to update.
+ * @param property The related property to add, or null to skip.
+ * @param controller The controller that exposed the relation, or null for direct property links.
+ * @param source The Daz API surface that exposed the relation.
+ */
+const addRelation = (relations: PropertyRelation[], property: DzProperty | null, controller: DzController | null, source: PropertyRelationSource): void => {
+    if (!property) return
+
+    for (let relation of relations) {
+        if (relation.property === property && relation.controller === controller && relation.source === source) return
+    }
+
+    relations.push({ property, controller, source })
+}
+
+/**
+ * Gets the source property referenced by a controller.
+ * @param controller The controller to inspect.
+ * @param current If true, uses getCurrentProperty; otherwise, uses getProperty.
+ * @returns The controller's property, or null when the controller does not expose that method.
+ */
+const getControllerProperty = (controller: DzController, current: boolean): DzProperty | null => {
+    const methodName = current ? 'getCurrentProperty' : 'getProperty'
+    const method = (controller as any)[methodName]
+    if (typeof method !== 'function') return null
+
+    return method.call(controller) as DzProperty | null
+}
+
+/**
+ * Gets properties that drive this property through controllers or direct numeric links.
+ * @param property The property whose input/driving properties should be collected.
+ * @returns Related input properties with the controller/source that exposed each relation.
+ */
+export const getPropertyInputs = (property: DzProperty): PropertyRelation[] => {
+    const relations: PropertyRelation[] = []
+    const controllerCount = property.getNumControllers()
+
+    for (let index = 0; index < controllerCount; index++) {
+        const controller = property.getController(index)
+        addRelation(relations, getControllerProperty(controller, false), controller, 'controller')
+        addRelation(relations, getControllerProperty(controller, true), controller, 'currentController')
+    }
+
+    const numericProperty = cast<DzNumericProperty>(property, 'DzNumericProperty')
+    if (numericProperty) {
+        addRelation(relations, numericProperty.getLinkProperty(), null, 'link')
+        addRelation(relations, numericProperty.getFollowProperty(), null, 'follow')
+    }
+
+    return relations
+}
+
+/**
+ * Gets properties driven by this property through slave controllers.
+ * @param property The property whose output/driven properties should be collected.
+ * @returns Related output properties with the controller/source that exposed each relation.
+ */
+export const getPropertyOutputs = (property: DzProperty): PropertyRelation[] => {
+    const relations: PropertyRelation[] = []
+    const controllerCount = property.getNumSlaveControllers()
+
+    for (let index = 0; index < controllerCount; index++) {
+        const controller = property.getSlaveController(index)
+        addRelation(relations, controller.getOwner(), controller, 'slaveController')
+    }
+
+    return relations
+}
+
+/**
+ * Checks whether a property is a Daz numeric property.
+ * @param property The property to check.
+ * @returns True if the property inherits DzNumericProperty.
+ */
 export const isNumeric = (property: DzProperty): boolean => {
     return property.inherits('DzNumericProperty')
 }
 
+/**
+ * Casts a property to a specific Daz property type when it inherits that type.
+ * @param property The property to cast.
+ * @param type The Daz property class name to test.
+ * @returns The property typed as T, or null when it does not inherit the requested type.
+ */
 export const cast = <T extends DzProperty>(property: DzProperty, type: 'DzNumericProperty' | 'DzFloatProperty' | 'DzIntProperty'): T | null => {
     return property.inherits(type)
         ? property as T
         : null
 }
 
+/**
+ * Casts a property to a numeric float or int property.
+ * @param property The property to cast.
+ * @returns The property as DzFloatProperty or DzIntProperty, or null if it is neither.
+ */
 export const toNumeric = (property: DzProperty): DzFloatProperty | DzIntProperty | null => {
     return toFloat(property) ?? toInt(property)
 }
 
+/**
+ * Casts a property to a float property.
+ * @param property The property to cast.
+ * @returns The property as DzFloatProperty, or null if it is not one.
+ */
 export const toFloat = (property: DzProperty): DzFloatProperty | null => {
     return cast<DzFloatProperty>(property, 'DzFloatProperty')
 }
 
+/**
+ * Casts a property to an int property.
+ * @param property The property to cast.
+ * @returns The property as DzIntProperty, or null if it is not one.
+ */
 export const toInt = (property: DzProperty): DzIntProperty | null => {
     return cast<DzIntProperty>(property, 'DzIntProperty')
-}
+}