arcane-os 0.16.3 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.17.0
+
+- Add neutral `modal.configure({dismissible})` configuration, defaulting to
+  `true`. Setting it to `false` hides the close button and prevents Escape,
+  backdrop and close-button dismissal while preserving the owner's existing
+  programmatic close/destroy lifecycle and running-task behavior.
+- Retain the configuration through population, open/close cycles and task
+  completion. Keep focus within useful content when hiding a focused close
+  control, and preserve default modal behavior for existing consumers.
+
 ## 0.16.3
 
 - Remember browser-reported PWA installation in app-scoped DBOPFS and suppress

package/docs/reference/runtime-components.md

@@ -79,7 +79,7 @@ appropriate.
 | [`markdown-document.html`](#markdown-documenthtml) | Renders and navigates a complete Markdown document with focusable fragments. | `configure()`<br>`load()`<br>`render()`<br>`clear()`<br>`fail()`<br>`focus()`<br>`focusFragment()`<br>`destroy()` | `markdown-document-ready`<br>`markdown-document-state`<br>`markdown-document-loading`<br>`markdown-document-rendered`<br>`markdown-document-empty`<br>`markdown-document-error`<br>`markdown-document-navigate` | Complete Markdown/state normalized; malformed input and Marked/DOM failures remain visible |
 | [`markdown-editor.html`](#markdown-editorhtml) | Configurable Markdown authoring, toolbar, preview, title, and save surface. | `configure()`<br>`focus()`<br>`clear()`<br>`saveEntry()`<br>`destroy()` | `markdown-editor-ready`<br>`markdown-editor-change`<br>`markdown-editor-saved` | Editor values normalized; injected save result mixed |
 | [`media-embed.html`](#media-embedhtml) | Loads a parsed YouTube video or playlist embed with ordinary hosting by default, optional privacy enhancement, and an external-platform action. | `configure()`<br>`load()`<br>`destroy()` | `media-embed-ready`<br>`media-load`<br>`media-error`<br>`media-open-platform` | URL/error normalized; iframe/platform behavior native |
-| [`modal.html`](#modalhtml) | Generic modal with population, open/close, actions, and sequential task execution. | `populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
+| [`modal.html`](#modalhtml) | Generic modal with population, configurable user dismissal, actions, and concurrent task execution. | `configure()`<br>`populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()`<br>`running`<br>`opened` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
 | [`output-panel.html`](#output-panelhtml) | Presents status, output, body, coverage, actions, pending, error, and cleared states. | `configure()`<br>`setOutput()`<br>`setBody()`<br>`setCoverage()`<br>`setActions()`<br>`setPending()`<br>`setStatus()`<br>`setError()`<br>`clear()`<br>`destroy()` | `output-panel-ready`<br>`output-panel-state`<br>`output-panel-change`<br>`output-panel-action`<br>`output-panel-error`<br>`output-panel-cleared` | DOM-normalized |
 | [`preferences-form.html`](#preferences-formhtml) | Builds a schema-driven preferences form with submit, reset, busy, and status behavior. | `configure()`<br>`getValues()`<br>`setValues()`<br>`setBusy()`<br>`setStatus()`<br>`destroy()` | `preferences-form-ready`<br>`preferences-change`<br>`preferences-submit`<br>`preferences-reset` | Normalized form values |
 | [`pwa-install.html`](#pwa-installhtml) | Presents a dismissible browser installation action with floating or inline placement. | `configure()`<br>`install()`<br>`dismiss()`<br>`destroy()`<br>`state`<br>`ready` | `pwa-install-ready`<br>`pwa-install-change`<br>`pwa-install-dismissed` | Browser install availability and outcome supplied by the shared PWA owner |
@@ -944,11 +944,28 @@ Shared dependencies: [`YouTubeMedia.js`](runtime-modules.md#youtubemediajs).
 
 ### Overview
 
-Generic modal with population, open/close, actions, and sequential task execution.
+Generic modal with population, configurable user dismissal, actions, and concurrent task execution.
 
 ### Public surface
 
-Methods/properties: `populate()`, `open()`, `close()`, `runTasks()`, `destroy()`.
+Methods/properties: `configure()`, `populate()`, `open()`, `close()`, `runTasks()`,
+`destroy()`, `running`, `opened`.
+
+`configure({dismissible})` synchronously returns the current `{dismissible}`
+configuration, or `false` after destruction. `dismissible` starts as `true`;
+omitting it preserves the current choice. A supplied value must be a boolean.
+Setting it to `false` hides the close button and prevents user dismissal through
+Escape, backdrop clicks and the close button. Setting it back to `true` restores
+normal user dismissal. The choice persists across population, open/close cycles
+and task completion. If the close button held focus when disabled, focus moves
+to a content control or the focusable modal body.
+
+This option does not prevent the owning application from calling `close()` or
+`destroy()`. The existing running-task behavior remains: `close()` leaves a
+running modal open unless called with its existing second `force` argument set
+to `true`; `destroy()` releases the component. Product-specific conditions for
+closing a modal belong to the application. Content, actions and task results
+are preserved, and `runTasks()` continues to execute independent jobs concurrently.
 
 Events: `modal-ready`, `modal-opened`, `modal-closed`, `modal-action`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -68,7 +68,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/components/modal.html

@@ -150,7 +150,7 @@
         <button id="close" class="modal-button" part="close" type="button" aria-label="Close" title="Close">&#10005;</button>
         <header id="modal-header" class="modal-header" part="header" hidden><slot id="header-slot" name="header"></slot></header>
         <input type="search" id="modal-search" class="modal-search hidden" part="search" placeholder="Search..." aria-label="Search modal content">
-        <div id="modal-content" class="modal-content" part="body"><slot name="body"></slot></div>
+        <div id="modal-content" class="modal-content" part="body" tabindex="-1"><slot name="body"></slot></div>
         <footer id="modal-footer" class="modal-footer" part="footer" hidden><slot id="footer-slot" name="footer"></slot></footer>
     </div>
 </dialog>
@@ -174,11 +174,13 @@
     const modalStack=window.modalStack=window.modalStack||[];
 
     let running=false;
+    let dismissible = true;
     let disposed=false;
     let activeRun=Promise.resolve([]);
     let returnFocus=null;
 
     host.ready=false;
+    host.configure = configure;
     host.populate=populate;
     host.open=open;
     host.close=close;
@@ -195,13 +197,18 @@
         opened:{get:function getOpenedState(){return dialog.open;}}
     });
 
-    dialog.addEventListener('cancel',function preventRunningDialogCancellation(event){
-        event.preventDefault();
-        close(event);
-    });
+    dialog.addEventListener(
+        'cancel',
+        function handleDialogCancellation(event) {
+            event.preventDefault();
+            if (dismissible) {
+                close(event);
+            }
+        }
+    );
 
     dialog.addEventListener('click',function closeFromDialogBackdrop(event){
-        if(event.target!==dialog||running){
+        if (event.target !== dialog || running || !dismissible) {
             return;
         }
         const bounds=dialog.getBoundingClientRect();
@@ -214,9 +221,45 @@
         }
     });
 
-    closeButton.addEventListener('click',function closeFromButton(event){
-        close(event);
-    });
+    closeButton.addEventListener(
+        'click',
+        function closeFromButton(event) {
+            if (dismissible) {
+                close(event);
+            }
+        }
+    );
+
+    function configure(input = {}) {
+        if (disposed) return false;
+        if (input === null || !is.object(input) || is.array(input)) {
+            throw new TypeError('Modal configuration must be an object.');
+        }
+        if (input.dismissible !== undefined) {
+            if (!is.boolean(input.dismissible)) {
+                throw new TypeError('Modal dismissible must be a boolean.');
+            }
+            dismissible = input.dismissible;
+        }
+        const closeButtonFocused = shadowRoot.activeElement === closeButton;
+        updateCloseButton();
+        if (dialog.open && !dismissible && closeButtonFocused) {
+            focusOpenedModal();
+        }
+        return {dismissible};
+    }
+
+    function updateCloseButton() {
+        closeButton.classList.toggle('hidden', running || !dismissible);
+    }
+
+    function focusOpenedModal() {
+        const focusTarget = modalContent.querySelector('[autofocus],input:not([disabled]),select:not([disabled]),textarea:not([disabled]),button:not([disabled]),a[href]')
+            || (running || !dismissible ? modalContent : closeButton);
+        focusTarget.focus(
+            {preventScroll: true}
+        );
+    }
 
     for(const slot of [headerSlot,footerSlot]){
         const region=slot.parentElement;
@@ -253,10 +296,7 @@
                 ?document.activeElement
                 :null;
             dialog.showModal();
-            queueMicrotask(function focusOpenedModal(){
-                const focusTarget=modalContent.querySelector('[autofocus],input:not([disabled]),select:not([disabled]),textarea:not([disabled]),button:not([disabled]),a[href]')||closeButton;
-                focusTarget?.focus({preventScroll:true});
-            });
+            queueMicrotask(focusOpenedModal);
             emit('modal-opened',{}, {opened:true});
         }
         return true;
@@ -274,7 +314,7 @@
         if(wasOpen){
             dialog.close();
         }
-        closeButton.classList.remove('hidden');
+        updateCloseButton();
 
         const stackIndex=modalStack.indexOf(host);
         if(stackIndex>-1){
@@ -317,7 +357,7 @@
     }
 
     async function populate(content='<p>Content goes here</p>',search=false){
-        closeButton.classList.remove('hidden');
+        updateCloseButton();
         modalSearch.classList.toggle('hidden',!search);
         if(content instanceof Node){
             modalContent.replaceChildren(content);
@@ -349,7 +389,7 @@
         }
 
         running=true;
-        closeButton.classList.add('hidden');
+        updateCloseButton();
         modalSearch.classList.add('hidden');
         modalContent.replaceChildren();
 
@@ -399,16 +439,20 @@
             return result.status==='rejected';
         });
         running=false;
-        closeButton.classList.remove('hidden');
+        updateCloseButton();
 
         if(failed){
             heading.innerText='Some Tasks Could Not Be Completed';
-            message.innerText='You may close this message and try again.';
+            message.innerText = dismissible
+                ? 'You may close this message and try again.'
+                : 'Review the failed tasks and try again.';
             return results;
         }
 
         heading.innerText='All Tasks Complete';
-        message.innerText='Every task completed. You may close this message.';
+        message.innerText = dismissible
+            ? 'Every task completed. You may close this message.'
+            : 'Every task completed.';
         return results;
     }