dazscript-framework 1.0.8 → 1.0.10

package/README.md

@@ -299,6 +299,17 @@ Custom action icons are selected from `action(...)` metadata and sibling image f
 
 `scriptname.action.png` is the installed custom action icon. Daz Studio uses the same action icon for menu and toolbar placements. `scriptname.png` is the preferred script/content icon fallback. `scriptname.dsa.png` is a legacy fallback kept for older projects and will be removed in a future breaking release.
 
+Setup dialog header assets are optional and are discovered beside `src/Setup.dsa.ts`:
+
+1. `src/Setup.header.png`
+2. `src/Setup.tip.png`
+3. `src/Setup.png`
+4. `src/Setup.dsa.png` legacy fallback
+
+Header text can be placed in `src/Setup.header.html`, `src/Setup.header.md`, or `src/Setup.header.txt`, with `src/Setup.html`, `src/Setup.md`, and `src/Setup.txt` as script-named fallbacks. The installer generator embeds that text into `Setup.dsa.ts`, so Daz Studio does not need to read the text file at setup time. The setup dialog renders the header body with `DzTextBrowser` rich text support; no Markdown conversion is performed. The image remains a deployed PNG asset and is resolved relative to the generated setup script at runtime.
+
+The same layout is available to custom dialogs through `add.header({ imagePath, html, text, height, imageWidth }).build()`. Use `html` for rich text, or `text` for escaped plain text.
+
 This replaces the older `Install.dsa.ts` / `Uninstall.dsa.ts` pattern. The installer generator removes those legacy files if they exist.
 
 ### Setup Keyboard Shortcuts

package/dist/scripts/install-generator.js

@@ -276,6 +276,49 @@ function toPosix(filePath) {
   return filePath.replace(/\\/g, '/');
 }
 
+function resolveSetupHeaderImage(workdir) {
+  const candidates = [
+    path.join(workdir, 'src', 'Setup.header.png'),
+    path.join(workdir, 'src', 'Setup.tip.png'),
+    path.join(workdir, 'src', 'Setup.png'),
+    path.join(workdir, 'src', 'Setup.dsa.png'),
+  ];
+  const match = candidates.find((candidate) => fs.existsSync(candidate));
+  return match ? `./${path.basename(match)}` : undefined;
+}
+
+function resolveSetupHeaderTextFile(workdir) {
+  const candidates = [
+    path.join(workdir, 'src', 'Setup.header.html'),
+    path.join(workdir, 'src', 'Setup.header.md'),
+    path.join(workdir, 'src', 'Setup.header.txt'),
+    path.join(workdir, 'src', 'Setup.html'),
+    path.join(workdir, 'src', 'Setup.md'),
+    path.join(workdir, 'src', 'Setup.txt'),
+  ];
+
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+function loadSetupHeader(workdir) {
+  const header = {};
+  const imagePath = resolveSetupHeaderImage(workdir);
+  const textFile = resolveSetupHeaderTextFile(workdir);
+
+  if (imagePath) {
+    header.headerImagePath = imagePath;
+  }
+
+  if (textFile) {
+    const text = fs.readFileSync(textFile, 'utf8').trim();
+    if (text) {
+      header.headerText = text;
+    }
+  }
+
+  return header;
+}
+
 function resolveShortcutFile(workdir, config) {
   const configuredPath =
     config.keyboardShortcutsPath ||
@@ -340,6 +383,7 @@ function generateInstallerFiles(workdir, options) {
     settingsPath,
     bundleName,
     shortcutBackupPath: `${appDataPath}/Installer/keyboard-shortcuts-backup.json`,
+    ...loadSetupHeader(workdir),
   };
   if (shortcutData.shortcuts && shortcutData.shortcuts.length > 0) {
     setupOptions.shortcuts = shortcutData.shortcuts;

package/package.json

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

package/src/dialog/builders/dialog-header-builder.ts

@@ -0,0 +1,86 @@
+import LayoutBuilder from './layout-builder'
+import { createWidget } from './widget-builder'
+import { WidgetBuilderContext } from './widgets-builder'
+import { getScriptPath } from '@dsf/helpers/script-helper'
+
+export type DialogHeaderOptions = {
+    image?: Pixmap
+    imagePath?: string
+    imageWidth?: number
+    height?: number
+    html?: string
+    text?: string
+}
+
+const escapeHtml = (value: string): string =>
+    value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;')
+        .replace(/\r?\n/g, '<br>')
+
+const resolveImagePath = (filePath: string): string => {
+    const value = String(filePath ?? '').replace(/\\/g, '/')
+    if (!value) return ''
+    if (value.indexOf(':') >= 0 || value.charAt(0) === '/') return value
+
+    return `${getScriptPath()}/${value.replace(/^\.\//, '')}`
+}
+
+export class DialogHeaderBuilder {
+    constructor(
+        private readonly context: WidgetBuilderContext,
+        private readonly options: DialogHeaderOptions
+    ) { }
+
+    build(): DzWidget {
+        const height = this.options.height ?? 96
+        const imageWidth = this.options.imageWidth ?? height
+        const html = this.options.html ?? (
+            typeof this.options.text === 'string'
+                ? escapeHtml(this.options.text)
+                : ''
+        )
+
+        return createWidget(this.context).build(DzWidget, (container) => {
+            container.setFixedHeight(height)
+
+            LayoutBuilder
+                .create(this.context)
+                .parent(container)
+                .direction('horizontal')
+                .build(() => {
+                    this.buildImage(height, imageWidth)
+                    this.buildText(html, height)
+                })
+        })
+    }
+
+    private buildImage(height: number, imageWidth: number): void {
+        const pixmap = this.options.image ?? (
+            this.options.imagePath ? new Pixmap(resolveImagePath(this.options.imagePath)) : null
+        )
+        if (!pixmap) return
+
+        createWidget(this.context).build(DzLabel, (label) => {
+            label.pixmap = pixmap
+            label.scaledContents = true
+            label.setFixedWidth(imageWidth)
+            label.setFixedHeight(height)
+        })
+    }
+
+    private buildText(html: string, height: number): void {
+        if (!html) return
+
+        createWidget(this.context).build(DzTextBrowser, (textBrowser) => {
+            textBrowser.html = html
+            textBrowser.readOnly = true
+            textBrowser.lineWrapMode = DzTextEdit.WidgetWidth
+            textBrowser.wordWrapMode = DzTextEdit.WordWrap
+            textBrowser.setFixedHeight(height)
+        })
+    }
+}

package/src/dialog/builders/widgets-builder.ts

@@ -4,6 +4,7 @@ import CheckBoxBuilder from './checkbox-builder'
 import ColorPickerBuilder from './color-picker-builder'
 import { ComboBoxBuilder } from './combo-box-builder'
 import { ComboEditBuilder } from './combo-edit-builder'
+import { DialogHeaderBuilder, DialogHeaderOptions } from './dialog-header-builder'
 import GroupBoxBuilder from './groupbox-builder'
 import LabelBuilder from './label-builder'
 import LayoutBuilder, { LayoutOrientation } from './layout-builder'
@@ -63,6 +64,10 @@ export class WidgetsBuilder {
         return new LabelBuilder(this.context).text(text)
     }
 
+    header(options: DialogHeaderOptions): DialogHeaderBuilder {
+        return new DialogHeaderBuilder(this.context, options)
+    }
+
     button(text?: string): ButtonBuilder {
         return new ButtonBuilder(this.context).text(text)
     }

package/src/helpers/custom-action-installer-helper.ts

@@ -13,6 +13,7 @@ import { promptKeyboardShortcut } from '@dsf/shared/set-keyboard-shortcut'
 import { readFromFile, saveToFile } from './file-helper'
 import { getCanonicalInstallerEntry, toActionKey } from './custom-action-installer-entries'
 import { canResetSetupShortcut, getDisplayedSetupShortcut, resetSetupShortcut, setSetupShortcut, updateShortcutOverrideState } from './custom-action-installer-shortcuts'
+import { getScriptPath } from './script-helper'
 
 type InstallerEntry = {
     action: CustomAction
@@ -31,6 +32,10 @@ type InstallerEntry = {
 type SetupDialogOptions = {
     settingsPath: string
     bundleName?: string
+    headerImagePath?: string
+    headerImageWidth?: number
+    headerHeight?: number
+    headerText?: string
     shortcuts?: ActionAccelerator[]
     shortcutsSourcePath?: string
     shortcutBackupPath?: string
@@ -96,6 +101,17 @@ const getSetupDialogOptions = (options: string | SetupDialogOptions): SetupDialo
 const getShortcutBackupPath = (options: SetupDialogOptions): string =>
     `${App.getAppDataPath()}/${options.shortcutBackupPath ?? `${options.settingsPath}/keyboard-shortcuts-backup.json`}`
 
+const hasSetupHeader = (options: SetupDialogOptions): boolean =>
+    Boolean(options.headerImagePath || options.headerText)
+
+const resolveSetupAssetPath = (filePath: string | null | undefined): string => {
+    const value = String(filePath ?? '').replace(/\\/g, '/')
+    if (!value) return ''
+    if (value.indexOf(':') >= 0 || value.charAt(0) === '/') return value
+
+    return `${getScriptPath()}/${value.replace(/^\.\//, '')}`
+}
+
 const buildEntries = (actions: CustomAction[]): InstallerEntry[] => {
     return actions
         .filter((action) => Boolean(action.menuPath) || Boolean(action.toolbar))
@@ -180,9 +196,9 @@ class InstallerSelectionDialog extends BasicDialog {
     constructor(
         private readonly entries: InstallerEntry[],
         private readonly shortcutEntries: ShortcutEntry[],
-        bundleName?: string
+        private readonly options: SetupDialogOptions
     ) {
-        super(bundleName ? `${bundleName} Setup` : 'Setup Scripts', 'dsfSetupScripts')
+        super(options.bundleName ? `${options.bundleName} Setup` : 'Setup Scripts', 'dsfSetupScripts')
         this.items$ = new Observable(entries.map(toTreeNode))
         this.shortcutItems$ = new Observable(shortcutEntries.map(toShortcutTreeNode))
     }
@@ -214,9 +230,13 @@ class InstallerSelectionDialog extends BasicDialog {
     private buildScriptsTab(): void {
         const add = this.add
 
-        add.label('Choose which scripts to install, then use the columns to review their shortcut, menu, and toolbar targets.')
-            .wordWrap()
-            .build()
+        if (hasSetupHeader(this.options)) {
+            this.buildHeader()
+        } else {
+            add.label('Choose which scripts to install, then use the columns to review their shortcut, menu, and toolbar targets.')
+                .wordWrap()
+                .build()
+        }
         add.group('Search').horizontal().build(() => {
             add.edit()
                 .value(this.keywords$)
@@ -285,6 +305,20 @@ class InstallerSelectionDialog extends BasicDialog {
         })
     }
 
+    private buildHeader(): void {
+        const add = this.add
+        const height = this.options.headerHeight ?? 96
+        const imageWidth = this.options.headerImageWidth ?? height
+        const headerText = String(this.options.headerText ?? 'Choose which scripts to install, then use the columns to review their shortcut, menu, and toolbar targets.')
+
+        add.header({
+            imagePath: resolveSetupAssetPath(this.options.headerImagePath),
+            imageWidth,
+            height,
+            html: headerText
+        }).build()
+    }
+
     private buildShortcutsTab(): void {
         const add = this.add
 
@@ -559,7 +593,7 @@ class InstallerSelectionDialog extends BasicDialog {
 const runDialog = (actions: CustomAction[], options: SetupDialogOptions): SetupSelection | null => {
     const entries = buildEntries(actions)
     const shortcutEntries = buildShortcutEntries(options.shortcuts)
-    const dialog = new InstallerSelectionDialog(entries, shortcutEntries, options.bundleName)
+    const dialog = new InstallerSelectionDialog(entries, shortcutEntries, options)
     return dialog.ok() ? dialog.getSelections() : null
 }
 

package/src/scripts/install-generator.test.ts

@@ -29,6 +29,10 @@ const writePng = (projectDir: string, fileName: string): void => {
     fs.writeFileSync(path.join(projectDir, 'src', fileName), 'png')
 }
 
+const writeText = (projectDir: string, fileName: string, content: string): void => {
+    fs.writeFileSync(path.join(projectDir, 'src', fileName), content)
+}
+
 const generateSetup = (projectDir: string): string => {
     const previousCwd = process.cwd()
     process.chdir(projectDir)
@@ -103,3 +107,83 @@ describe('install generator action icons', () => {
         expect(setup).not.toContain('"icon": "custom-icon.dsa.png"')
     })
 })
+
+describe('install generator setup header', () => {
+    it('uses the explicit setup header image before the generic setup image', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.header.png')
+        writePng(projectDir, 'Setup.tip.png')
+        writePng(projectDir, 'Setup.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.header.png"')
+        expect(setup).not.toContain('"headerImagePath":"./Setup.tip.png"')
+        expect(setup).not.toContain('"headerImagePath":"./Setup.png"')
+    })
+
+    it('uses the setup tip image before the generic setup image', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.tip.png')
+        writePng(projectDir, 'Setup.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.tip.png"')
+        expect(setup).not.toContain('"headerImagePath":"./Setup.png"')
+    })
+
+    it('falls back to the generic setup image when no explicit header image exists', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.png"')
+    })
+
+    it('falls back to the setup script image when no header image exists', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.dsa.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.dsa.png"')
+    })
+
+    it('embeds setup header markdown text into generated setup options', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writeText(projectDir, 'Setup.header.md', 'Header line\n\nSecond line\n')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerText":"Header line\\n\\nSecond line"')
+    })
+
+    it('prefers setup header html over markdown text', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writeText(projectDir, 'Setup.header.html', '<h2>HTML Header</h2>')
+        writeText(projectDir, 'Setup.header.md', '# Markdown Header')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerText":"<h2>HTML Header</h2>"')
+        expect(setup).not.toContain('# Markdown Header')
+    })
+
+    it('falls back to setup script markdown when no header text file exists', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writeText(projectDir, 'Setup.md', 'Setup markdown fallback')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerText":"Setup markdown fallback"')
+    })
+})