@kubohiroya/turbowarp-title-menu 0.1.0

package/README.md

@@ -0,0 +1,276 @@
+# TurboWarp Title Menu
+
+[日本語](README.ja.md)
+
+Reusable title, application menu, and DSL source storage controls for TurboWarp extensions and packaged projects.
+
+**User guide:** [English](https://kubohiroya.github.io/turbowarp-title-menu/)
+
+## What it does
+
+- Shows a reusable title dialog with title, author, license, official website, language, and close controls.
+- Shows a stage-mounted application menu built on the shared `@kubohiroya/turbowarp-app-shell` primitive, so a host project can define its own actions instead of a fixed set.
+- Shows a DSL file manager that adds, opens, renames, and deletes stored files, and sorts them by name, update time, or size.
+- Stores many DSL files in IndexedDB without tying the mechanism to TM Kamishibai.
+- Exposes a small Composition API for projects that want to wire the controls into their own runtime.
+
+## Documentation and block icon
+
+This extension publishes its English user documentation with GitHub Pages.
+
+- `docsURI` points to the English GitHub Pages documentation: `https://kubohiroya.github.io/turbowarp-title-menu/`.
+- `blockIconURI` is a self-contained SVG encoded as `data:image/svg+xml;base64,...`.
+- The block icon represents a small title/menu panel.
+
+## Requirements and safety
+
+- TurboWarp Desktop, TurboWarp Web, or a packaged TurboWarp project that allows custom extensions.
+- Browser DOM access for the title and menu overlays.
+- Browser IndexedDB for DSL source persistence.
+- Unsandboxed extension mode.
+
+> [!IMPORTANT]
+> This extension must run without the sandbox because it creates DOM controls above the stage and uses browser storage. Load unsandboxed extension code only from a source you trust.
+
+## Installation
+
+### Ready-to-use JavaScript
+
+1. Download [`dist/turbowarp-title-menu.js`](dist/turbowarp-title-menu.js?raw=1).
+2. Open **Extensions** in TurboWarp.
+3. Choose **Custom Extension** and load the file.
+4. Enable **Run extension without sandbox**.
+
+The reviewed JavaScript build is committed to this repository, so users do not need Node.js to install the extension.
+
+### npm package
+
+Install an exact version that you have reviewed:
+
+```bash
+pnpm add --save-exact @kubohiroya/turbowarp-title-menu@0.1.0
+```
+
+Load the standalone bundle from:
+
+```text
+node_modules/@kubohiroya/turbowarp-title-menu/dist/turbowarp-title-menu.js
+```
+
+A version-pinned CDN URL is:
+
+```text
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-title-menu@0.1.0/dist/turbowarp-title-menu.js
+```
+
+## Quick start
+
+1. Load `dist/turbowarp-title-menu.js` as an unsandboxed custom extension.
+2. Run `show title dialog` immediately after startup.
+3. Use `show application menu`, or `show DSL file manager` directly, when the project should expose DSL file actions.
+
+```text
+when green flag clicked
+show title dialog
+```
+
+## Block reference
+
+The block reference is generated from [`src/block-definitions.json`](src/block-definitions.json). Do not edit the generated section manually.
+
+<!-- BEGIN GENERATED BLOCKS -->
+
+### `show title dialog`
+
+Shows the configured title dialog above the TurboWarp stage.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `showTitle` |
+
+### `show application menu`
+
+Shows the application menu above the TurboWarp stage.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `showMenu` |
+
+### `show DSL file manager`
+
+Shows the dialog that adds, opens, renames, deletes, and sorts stored DSL files.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `showDslFiles` |
+
+### `when a DSL source is opened`
+
+Runs after the operator opens a stored DSL file, or after the opened source is announced again.
+
+| Property | Value |
+|---|---|
+| Type | Hat |
+| Opcode | `whenDslSourceOpened` |
+
+### `reload the opened DSL source`
+
+Announces the currently opened DSL source again without showing a dialog.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `reloadOpenedDsl` |
+
+### `opened DSL file name`
+
+Returns the name of the DSL file that is currently open, or an empty string.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `openedDslName` |
+
+### `opened DSL source`
+
+Returns the text of the DSL file that is currently open, or an empty string.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `openedDslSource` |
+
+### `has a saved DSL file?`
+
+Reports whether at least one DSL file is stored in IndexedDB.
+
+| Property | Value |
+|---|---|
+| Type | Boolean |
+| Opcode | `hasSavedDsl` |
+
+### `saved DSL file count`
+
+Returns how many DSL files are stored in IndexedDB.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `savedDslCount` |
+
+### `last DSL storage error`
+
+Returns the most recent DSL storage failure in the interface language, or an empty string.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `lastDslError` |
+
+<!-- END GENERATED BLOCKS -->
+
+## Important behavior
+
+| Situation | Behavior |
+|---|---|
+| Startup title | `show title dialog` mounts a dialog over the stage and keeps Scratch sprites untouched. |
+| Official website | The title dialog opens the configured website URL in a new browser tab. |
+| Adding a DSL file | `Add file` opens a browser file picker and stores the chosen source. It does not open the file; the operator presses `Open` when the project should use it. |
+| Renaming | Names are unique. Renaming a file to a name another file already uses fails and leaves both files unchanged. |
+| Deleting | Deleting asks for a second confirming click, and deleting the open file clears the opened source. |
+| Storage limits | A file over 1 MiB, or a 65th file, is refused with a message. The store never evicts a file on its own. |
+| Storage failures | Every failure is shown in the dialog and reported by `last DSL storage error`; a script is never interrupted by a thrown storage error. |
+| Project stop | The controls remain explicit UI overlays; consumers can dispose Composition API instances when their runtime ends. |
+
+## Composition API
+
+Importing the Composition API gives host projects direct control over DOM mounting, callbacks,
+locales, the storage database, and DSL source events. The application menu is re-exported from
+`@kubohiroya/turbowarp-app-shell`, so a host owns its own action vocabulary.
+
+```ts
+import {
+  createApplicationMenu,
+  createDslFilesDialog,
+  createDslStore,
+  createTitleDialog,
+  dslReloadEventName
+} from '@kubohiroya/turbowarp-title-menu';
+
+const store = createDslStore({databaseName: 'my-runtime'});
+
+const title = createTitleDialog({
+  mount: stageContainer,
+  locales: {
+    en: {
+      title: 'My Story',
+      author: 'Author: Example',
+      license: 'License: MPL-2.0',
+      website: 'Official Website',
+      close: 'Close'
+    }
+  },
+  websiteUrl: 'https://example.com'
+});
+
+const files = createDslFilesDialog({
+  mount: stageContainer,
+  locales: {en: myFileManagerLabels},
+  list: (sort) => store.list(sort),
+  onAdd: () => addFileThroughMyOwnPicker(),
+  onOpen: async (id) => {
+    const record = await store.get(id);
+    if (record === null) return;
+    await store.markOpened(id);
+    window.dispatchEvent(new CustomEvent(dslReloadEventName, {detail: {record}}));
+  },
+  onRename: (id, name) => store.rename(id, name),
+  onRemove: (id) => store.remove(id)
+});
+
+const menu = createApplicationMenu({
+  document,
+  mount: stageContainer,
+  actions: [
+    {id: 'files', labels: {en: 'DSL files'}, onSelect: () => files.show('en')},
+    {id: 'about', labels: {en: 'About'}, onSelect: () => title.show('en')}
+  ]
+});
+
+menu.show('en');
+```
+
+## Compatibility
+
+| Identifier | Value | Stability |
+|---|---|---|
+| Product name | `TurboWarp Title Menu` | Human-facing |
+| Repository | `kubohiroya/turbowarp-title-menu` | Current source location |
+| npm package | `@kubohiroya/turbowarp-title-menu` | Public package contract |
+| Extension ID | `kubohiroyaturbowarptitlemenu` | Stored in SB3; migration required to change |
+
+## Development
+
+Use Node.js 22 or later and the pnpm version declared by `packageManager`.
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+## Release
+
+1. Update the version in `package.json`.
+2. Run `pnpm run check`.
+3. Merge the release PR.
+4. Create tag `v<version>` on the verified commit.
+5. Publish the same version to npm when applicable.
+6. Verify GitHub Release, npm tarball, GitHub Pages, `docsURI`, block icon, and CDN artifacts.
+
+## License
+
+[Mozilla Public License 2.0](LICENSE) (SPDX: `MPL-2.0`).

package/dist/extension-manifest.json

@@ -0,0 +1,57 @@
+{
+  "formatVersion": 1,
+  "id": "kubohiroyaturbowarptitlemenu",
+  "blocks": [
+    {
+      "opcode": "hasSavedDsl",
+      "blockType": "BOOLEAN",
+      "arguments": []
+    },
+    {
+      "opcode": "lastDslError",
+      "blockType": "REPORTER",
+      "arguments": []
+    },
+    {
+      "opcode": "openedDslName",
+      "blockType": "REPORTER",
+      "arguments": []
+    },
+    {
+      "opcode": "openedDslSource",
+      "blockType": "REPORTER",
+      "arguments": []
+    },
+    {
+      "opcode": "reloadOpenedDsl",
+      "blockType": "COMMAND",
+      "arguments": []
+    },
+    {
+      "opcode": "savedDslCount",
+      "blockType": "REPORTER",
+      "arguments": []
+    },
+    {
+      "opcode": "showDslFiles",
+      "blockType": "COMMAND",
+      "arguments": []
+    },
+    {
+      "opcode": "showMenu",
+      "blockType": "COMMAND",
+      "arguments": []
+    },
+    {
+      "opcode": "showTitle",
+      "blockType": "COMMAND",
+      "arguments": []
+    },
+    {
+      "opcode": "whenDslSourceOpened",
+      "blockType": "HAT",
+      "arguments": []
+    }
+  ],
+  "menus": []
+}

package/dist/lib/composition.js

@@ -0,0 +1,5 @@
+export { createAppShellApplicationMenu as createApplicationMenu } from '@kubohiroya/turbowarp-app-shell';
+export { createDslFilesDialog } from './dsl-files-dialog.js';
+export { createDslStore, defaultDslSort, DslStoreError, readDslFile } from './dsl-store.js';
+export { dslOpenEventName, dslReloadEventName } from './events.js';
+export { createTitleDialog } from './title-dialog.js';

package/dist/lib/dom.js

@@ -0,0 +1,33 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function requireDocument(value) {
+    if (!isRecord(value) || typeof value.createElement !== 'function') {
+        throw new TypeError('document must provide createElement');
+    }
+    return value;
+}
+export function requireElement(value, name) {
+    if (!isRecord(value) || typeof value.appendChild !== 'function') {
+        throw new TypeError(`${name} must be a DOM element`);
+    }
+    return value;
+}
+export function ensureRelativeMount(mount) {
+    const previous = mount.style.position;
+    if (previous === '' || previous === 'static') {
+        mount.style.position = 'relative';
+        return () => {
+            mount.style.position = previous;
+        };
+    }
+    return () => { };
+}
+export function invokeSafely(operation, onError) {
+    try {
+        Promise.resolve(operation()).catch((error) => onError?.(error));
+    }
+    catch (error) {
+        onError?.(error);
+    }
+}

package/dist/lib/dsl-files-dialog.js

@@ -0,0 +1,323 @@
+import { isRecord, requireDocument, requireElement } from './dom';
+import { defaultDslSort } from './dsl-store';
+const defaultSortDirections = Object.freeze({
+    name: 'asc',
+    updatedAt: 'desc',
+    byteLength: 'desc'
+});
+function requireLocales(value) {
+    if (!isRecord(value) || Object.keys(value).length === 0) {
+        throw new TypeError('locales must contain at least one locale');
+    }
+    return value;
+}
+function textFor(locales, locale) {
+    const text = locales[locale] ?? locales['en'] ?? Object.values(locales)[0];
+    if (text === undefined)
+        throw new TypeError('locales must contain at least one locale');
+    return text;
+}
+function defaultFormatSize(byteLength) {
+    if (byteLength < 1024)
+        return `${byteLength} B`;
+    if (byteLength < 1024 * 1024)
+        return `${(byteLength / 1024).toFixed(1)} KB`;
+    return `${(byteLength / (1024 * 1024)).toFixed(1)} MB`;
+}
+function defaultFormatDate(isoDate) {
+    const parsed = new Date(isoDate);
+    if (Number.isNaN(parsed.getTime()))
+        return isoDate;
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${parsed.getFullYear()}-${pad(parsed.getMonth() + 1)}-${pad(parsed.getDate())} ${pad(parsed.getHours())}:${pad(parsed.getMinutes())}`;
+}
+function defaultDescribeError(error) {
+    if (error instanceof Error && error.message.length > 0)
+        return error.message;
+    return String(error);
+}
+export function createDslFilesDialog(options) {
+    if (!isRecord(options))
+        throw new TypeError('DSL files dialog options must be an object');
+    const document = requireDocument(options.document ?? globalThis.document);
+    const mount = requireElement(options.mount ?? document.body, 'mount');
+    const locales = requireLocales(options.locales);
+    const describeError = options.describeError ?? defaultDescribeError;
+    const formatSize = options.formatSize ?? defaultFormatSize;
+    const formatDate = options.formatDate ?? defaultFormatDate;
+    let locale = options.initialLocale ?? 'en';
+    let sort = options.initialSort ?? defaultDslSort;
+    let summaries = [];
+    let renamingId = null;
+    let confirmingRemovalId = null;
+    let status = '';
+    let disposed = false;
+    const root = document.createElement('section');
+    const panel = document.createElement('div');
+    const heading = document.createElement('h1');
+    const closeButton = document.createElement('button');
+    const toolbar = document.createElement('div');
+    const addButton = document.createElement('button');
+    const sortBar = document.createElement('div');
+    const listElement = document.createElement('div');
+    const statusElement = document.createElement('p');
+    root.setAttribute('data-turbowarp-title-menu-dsl-files', 'true');
+    root.style.cssText =
+        'position:absolute;inset:0;z-index:2147483646;align-items:center;justify-content:center;padding:16px;box-sizing:border-box;background:rgba(0,0,0,.6);font-family:sans-serif;';
+    // Visibility is the one property the dialog toggles, so it is set apart from the style sheet.
+    root.style.display = 'none';
+    panel.style.cssText =
+        'width:min(720px,96%);max-height:90%;display:flex;flex-direction:column;gap:10px;padding:18px;box-sizing:border-box;background:#ffffff;color:#1b1f27;border-radius:10px;box-shadow:0 10px 36px rgba(0,0,0,.45);overflow:hidden;';
+    heading.style.cssText = 'margin:0;font-size:20px;line-height:1.3;';
+    toolbar.style.cssText = 'display:flex;gap:8px;align-items:center;flex-wrap:wrap;';
+    sortBar.style.cssText = 'display:flex;gap:6px;align-items:center;flex-wrap:wrap;';
+    listElement.style.cssText = 'flex:1;min-height:0;overflow:auto;display:flex;flex-direction:column;gap:6px;';
+    statusElement.style.cssText = 'margin:0;min-height:18px;font-size:13px;color:#8a1c1c;';
+    const headerRow = document.createElement('div');
+    headerRow.style.cssText = 'display:flex;align-items:center;justify-content:space-between;gap:8px;';
+    headerRow.appendChild(heading);
+    headerRow.appendChild(closeButton);
+    panel.appendChild(headerRow);
+    toolbar.appendChild(addButton);
+    toolbar.appendChild(sortBar);
+    panel.appendChild(toolbar);
+    panel.appendChild(listElement);
+    panel.appendChild(statusElement);
+    root.appendChild(panel);
+    const previousMountPosition = mount.style.position;
+    if (previousMountPosition === '' || previousMountPosition === 'static') {
+        mount.style.position = 'relative';
+    }
+    mount.appendChild(root);
+    function styleButton(button, tone) {
+        const palette = {
+            primary: 'background:#1f6feb;color:#ffffff;border:1px solid #1f6feb;',
+            plain: 'background:#f2f4f8;color:#1b1f27;border:1px solid #ccd2de;',
+            danger: 'background:#b42318;color:#ffffff;border:1px solid #b42318;',
+            active: 'background:#d7e6ff;color:#0b3a82;border:1px solid #1f6feb;'
+        }[tone];
+        button.style.cssText = `${palette}padding:5px 10px;border-radius:6px;font-size:13px;cursor:pointer;`;
+    }
+    function run(operation) {
+        try {
+            Promise.resolve(operation()).catch(handleFailure);
+        }
+        catch (error) {
+            handleFailure(error);
+        }
+    }
+    function handleFailure(error) {
+        status = describeError(error);
+        options.onError?.(error);
+        render();
+    }
+    /** Every mutation goes through here so the list and the status line stay in step. */
+    function mutate(operation) {
+        run(async () => {
+            status = '';
+            try {
+                await operation();
+            }
+            catch (error) {
+                status = describeError(error);
+                options.onError?.(error);
+                render();
+                return;
+            }
+            await reload();
+        });
+    }
+    async function reload() {
+        if (disposed)
+            return;
+        summaries = await options.list(sort);
+        render();
+    }
+    function selectSort(field) {
+        if (sort.field === field) {
+            sort = { field, direction: sort.direction === 'asc' ? 'desc' : 'asc' };
+        }
+        else {
+            sort = { field, direction: defaultSortDirections[field] };
+        }
+        renamingId = null;
+        confirmingRemovalId = null;
+        mutate(() => undefined);
+    }
+    function createButton(label, tone, onClick) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.textContent = label;
+        styleButton(button, tone);
+        button.addEventListener('click', onClick);
+        return button;
+    }
+    function renderSortBar(text) {
+        const arrow = sort.direction === 'asc' ? ' ▲' : ' ▼';
+        const fields = [
+            ['name', text.sortByName],
+            ['updatedAt', text.sortByDate],
+            ['byteLength', text.sortBySize]
+        ];
+        for (const [field, label] of fields) {
+            const active = sort.field === field;
+            const button = createButton(active ? `${label}${arrow}` : label, active ? 'active' : 'plain', () => selectSort(field));
+            button.setAttribute('data-sort-field', field);
+            if (active)
+                button.setAttribute('aria-pressed', 'true');
+            sortBar.appendChild(button);
+        }
+    }
+    function renderRow(summary, text) {
+        const row = document.createElement('div');
+        row.setAttribute('data-dsl-file-id', summary.id);
+        row.style.cssText =
+            'display:flex;align-items:center;gap:8px;padding:8px;border:1px solid #e2e6ee;border-radius:8px;';
+        if (renamingId === summary.id) {
+            const input = document.createElement('input');
+            input.type = 'text';
+            input.value = summary.name;
+            input.setAttribute('data-rename-input', summary.id);
+            input.style.cssText = 'flex:1;min-width:0;padding:5px 8px;border:1px solid #1f6feb;border-radius:6px;font-size:14px;';
+            const commit = () => {
+                const nextName = input.value;
+                renamingId = null;
+                mutate(() => options.onRename(summary.id, nextName));
+            };
+            input.addEventListener('keydown', (event) => {
+                const key = event.key;
+                if (key === 'Enter')
+                    commit();
+                if (key === 'Escape') {
+                    renamingId = null;
+                    render();
+                }
+            });
+            row.appendChild(input);
+            row.appendChild(createButton(text.confirm, 'primary', commit));
+            row.appendChild(createButton(text.cancel, 'plain', () => {
+                renamingId = null;
+                render();
+            }));
+            return row;
+        }
+        const name = document.createElement('span');
+        name.textContent = summary.name;
+        name.style.cssText = 'flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:14px;';
+        const date = document.createElement('span');
+        date.textContent = formatDate(summary.updatedAt);
+        date.style.cssText = 'font-size:12px;color:#5a6172;white-space:nowrap;';
+        const size = document.createElement('span');
+        size.textContent = formatSize(summary.byteLength);
+        size.style.cssText = 'font-size:12px;color:#5a6172;white-space:nowrap;min-width:64px;text-align:right;';
+        row.appendChild(name);
+        row.appendChild(date);
+        row.appendChild(size);
+        if (confirmingRemovalId === summary.id) {
+            row.appendChild(createButton(text.confirmRemove, 'danger', () => {
+                confirmingRemovalId = null;
+                mutate(() => options.onRemove(summary.id));
+            }));
+            row.appendChild(createButton(text.cancel, 'plain', () => {
+                confirmingRemovalId = null;
+                render();
+            }));
+            return row;
+        }
+        row.appendChild(createButton(text.open, 'primary', () => {
+            mutate(() => options.onOpen(summary.id));
+        }));
+        row.appendChild(createButton(text.rename, 'plain', () => {
+            renamingId = summary.id;
+            confirmingRemovalId = null;
+            render();
+        }));
+        row.appendChild(createButton(text.remove, 'plain', () => {
+            confirmingRemovalId = summary.id;
+            renamingId = null;
+            render();
+        }));
+        return row;
+    }
+    function render() {
+        if (disposed)
+            return;
+        const text = textFor(locales, locale);
+        heading.textContent = text.title;
+        closeButton.textContent = text.close;
+        closeButton.setAttribute('aria-label', text.close);
+        addButton.textContent = text.add;
+        statusElement.textContent = status;
+        sortBar.replaceChildren();
+        renderSortBar(text);
+        listElement.replaceChildren();
+        if (summaries.length === 0) {
+            const empty = document.createElement('p');
+            empty.textContent = text.empty;
+            empty.style.cssText = 'margin:8px 0;font-size:14px;color:#5a6172;';
+            listElement.appendChild(empty);
+        }
+        else {
+            for (const summary of summaries)
+                listElement.appendChild(renderRow(summary, text));
+        }
+    }
+    styleButton(closeButton, 'plain');
+    styleButton(addButton, 'primary');
+    closeButton.type = 'button';
+    addButton.type = 'button';
+    closeButton.addEventListener('click', () => hide());
+    addButton.addEventListener('click', () => {
+        mutate(() => options.onAdd());
+    });
+    function hide() {
+        if (disposed)
+            return;
+        renamingId = null;
+        confirmingRemovalId = null;
+        root.style.display = 'none';
+    }
+    function ensureActive() {
+        if (disposed)
+            throw new TypeError('DSL files dialog is disposed');
+    }
+    render();
+    return Object.freeze({
+        element: root,
+        get locale() {
+            return locale;
+        },
+        get sort() {
+            return sort;
+        },
+        async show(nextLocale) {
+            ensureActive();
+            if (nextLocale !== undefined)
+                locale = nextLocale;
+            status = '';
+            root.style.display = 'flex';
+            await reload();
+            return locale;
+        },
+        hide,
+        async refresh() {
+            ensureActive();
+            await reload();
+        },
+        setLocale(nextLocale) {
+            ensureActive();
+            locale = nextLocale;
+            render();
+            return locale;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            root.remove();
+            if (previousMountPosition === '' || previousMountPosition === 'static') {
+                mount.style.position = previousMountPosition;
+            }
+        }
+    });
+}