arcane-os 0.2.2 → 0.3.0

package/runtime/arcane/components/directory-picker.html

@@ -33,6 +33,9 @@
     const host=this;
     const root=host.shadowRoot;
     const {default:DirectoryPicker}=await import('../modules/DirectoryPicker.js');
+    const {createArcaneEventSource,projectArcaneDOMEvent}=await import('arcane-os/event-manager');
+    const events=createArcaneEventSource(host,{source:'arcane.component.directory-picker',eventTypes:['directory-picker-cancel','directory-picker-change','directory-picker-error','directory-picker-ready']});
+    const lifecycleController=new AbortController();
     const field=root.querySelector('#field');
     const label=root.querySelector('#label');
     const pathDisplay=root.querySelector('#path');
@@ -45,18 +48,37 @@
     let disabled=false;
     let pending=false;
     let picker=new DirectoryPicker();
+    let operationGeneration=0;
+    let selectionRevision=0;
+    let operationSequence=0;
+    let destroyed=false;
 
     host.configure=configure;
+    host.destroy=destroy;
     host.focus=focus;
     host.select=select;
 
     Object.defineProperties(host,{
-        disabled:{get:()=>disabled,set:setDisabled},
-        options:{get:getOptions,set:configure},
-        value:{get:()=>currentValue,set:setValue}
+        disabled:{configurable:true,get:()=>disabled,set:setDisabled},
+        options:{configurable:true,get:getOptions,set:configure},
+        value:{configurable:true,get:()=>currentValue,set:setValue}
     });
 
-    choose.addEventListener('click',()=>select().catch(()=>{}));
+    choose.addEventListener(
+        'click',
+        ()=>select().catch(
+            error=>console.error('Unable to select a directory:',error)
+        ),
+        {signal:lifecycleController.signal}
+    );
+
+    function emit(type,detail={},publicDetail={},operationId=null){
+        if(destroyed){
+            return false;
+        }
+        const publication=events.dispatch(type,detail,{publicDetail,operationId});
+        return projectArcaneDOMEvent(host,publication.occurrence,{bubbles:true,composed:true});
+    }
 
     function datasetOptions(){
         return {
@@ -71,32 +93,47 @@
     }
 
     function configure(input={}){
+        if(destroyed){
+            return false;
+        }
         if(!input||typeof input!=='object'||Array.isArray(input)){
             throw new TypeError('Directory picker configuration must be an object.');
         }
+        const replacesSelection=Object.prototype.hasOwnProperty.call(input,'picker')
+            ||Object.prototype.hasOwnProperty.call(input,'value');
         const next={...datasetOptions(),...options,...input};
         const nextDisabled=Object.prototype.hasOwnProperty.call(input,'disabled')||!host.ready
             ?Boolean(next.disabled)
             :disabled;
+        const nextPicker=input.picker===undefined?picker:input.picker;
         if(input.picker!==undefined){
-            if(!input.picker||typeof input.picker.select!=='function'){
+            if(!nextPicker||typeof nextPicker.select!=='function'){
                 throw new TypeError('picker must expose a select(options) function.');
             }
-            picker=input.picker;
         }
-        options={
+        const nextOptions={
             buttonLabel:text(next.buttonLabel,'Choose folder'),
             help:text(next.help,'Choose one folder from this device.'),
             label:text(next.label,'Folder'),
             placeholder:text(next.placeholder,'No folder selected'),
             title:text(next.title,next.label||'Choose folder')
         };
+        const replacesValue=Object.prototype.hasOwnProperty.call(input,'value')
+            ||!host.ready;
+        const nextValue=replacesValue
+            ?normalizeValue(next.value??'')
+            :currentValue;
+        if(replacesSelection){
+            reviseSelection();
+        }
+        picker=nextPicker;
+        options=nextOptions;
         label.innerText=options.label;
         help.innerText=options.help;
         choose.innerText=options.buttonLabel;
         pathDisplay.placeholder=options.placeholder;
-        if(Object.prototype.hasOwnProperty.call(input,'value')||!host.ready){
-            setValue(next.value??'');
+        if(replacesValue){
+            applyValue(nextValue);
         }
         setDisabled(nextDisabled);
         return getOptions();
@@ -112,17 +149,33 @@
     }
 
     function setValue(value=''){
-        const next=`${value??''}`.trim();
-        if(next.length>4096||/[\u0000-\u001f\u007f]/.test(next)){
-            throw new TypeError('The directory path must be bounded plain text.');
+        if(destroyed){
+            return currentValue;
         }
-        currentValue=next;
+        const next=normalizeValue(value);
+        reviseSelection();
+        return applyValue(next);
+    }
+
+    function applyValue(value=''){
+        currentValue=normalizeValue(value);
         pathDisplay.value=currentValue;
         host.dataset.hasValue=`${Boolean(currentValue)}`;
         return currentValue;
     }
 
+    function normalizeValue(value=''){
+        const next=`${value??''}`.trim();
+        if(next.length>4096||/[\u0000-\u001f\u007f]/.test(next)){
+            throw new TypeError('The directory path must be bounded plain text.');
+        }
+        return next;
+    }
+
     function setDisabled(value=false){
+        if(destroyed){
+            return disabled;
+        }
         disabled=Boolean(value);
         pathDisplay.disabled=disabled;
         choose.disabled=disabled||pending;
@@ -132,12 +185,18 @@
     }
 
     function focus(options){
+        if(destroyed){
+            return false;
+        }
         choose.focus(options);
         return document.activeElement===host||root.activeElement===choose;
     }
 
     async function select(){
-        if(disabled||pending) return null;
+        if(destroyed||disabled||pending) return null;
+        const generation=++operationGeneration;
+        const revision=selectionRevision;
+        const operationId=`${events.descriptor.instanceId}:select:${++operationSequence}`;
         const previousPath=currentValue;
         setPending(true);
         setStatus('Opening the folder selector.');
@@ -146,34 +205,39 @@
                 ...(currentValue?{initialPath:currentValue}:{}),
                 title:options.title||options.label||'Choose folder'
             });
+            if(destroyed
+                ||generation!==operationGeneration
+                ||revision!==selectionRevision){
+                return null;
+            }
             if(result.cancelled){
                 setStatus('Folder selection canceled.');
-                host.dispatchEvent(new CustomEvent('directory-picker-cancel',{
-                    bubbles:true,
-                    composed:true,
-                    detail:{path:currentValue}
-                }));
+                emit('directory-picker-cancel',{path:currentValue,reason:'directory-selection-cancelled'},{hasPath:Boolean(currentValue),reason:'directory-selection-cancelled'},operationId);
                 return result;
             }
-            setValue(result.path);
+            applyValue(result.path);
             setStatus('Folder selected.');
-            host.dispatchEvent(new CustomEvent('directory-picker-change',{
-                bubbles:true,
-                composed:true,
-                detail:{path:currentValue,previousPath,source:'picker'}
-            }));
+            emit('directory-picker-change',{path:currentValue,previousPath,source:'picker'},{hasPath:Boolean(currentValue),changed:currentValue!==previousPath},operationId);
             return result;
         }catch(error){
+            if(destroyed
+                ||generation!==operationGeneration
+                ||revision!==selectionRevision){
+                return null;
+            }
             const message=error?.message||'The folder selector could not open.';
             setStatus(message,'error');
-            host.dispatchEvent(new CustomEvent('directory-picker-error',{
-                bubbles:true,
-                composed:true,
-                detail:{error,message}
-            }));
+            const code=String(error?.code||'ARCANE_DIRECTORY_PICKER_SELECTION_FAILED');
+            const reason='directory-selection-failed';
+            emit('directory-picker-error',{error,message,code,reason},{code,reason},operationId);
             throw error;
         }finally{
-            setPending(false);
+            if(!destroyed&&generation===operationGeneration){
+                setPending(false);
+                if(revision!==selectionRevision){
+                    setStatus('Folder selection superseded.');
+                }
+            }
         }
     }
 
@@ -185,13 +249,35 @@
         return pending;
     }
 
+    function reviseSelection(){
+        selectionRevision+=1;
+        if(pending){
+            setStatus('Folder selection superseded; waiting for the selector to close.');
+        }
+    }
+
     function setStatus(message='',tone=''){
         status.innerText=`${message||''}`;
         status.dataset.tone=tone;
         return status.innerText;
     }
 
+    function destroy(){
+        if(destroyed){
+            return false;
+        }
+        destroyed=true;
+        operationGeneration+=1;
+        selectionRevision+=1;
+        lifecycleController.abort('directory-picker-destroyed');
+        pending=false;
+        picker?.destroy?.();
+        events.dispose();
+        host.ready=false;
+        return true;
+    }
+
     configure(datasetOptions());
     host.ready=true;
-    host.dispatchEvent(new CustomEvent('directory-picker-ready',{bubbles:true,composed:true}));
+    emit('directory-picker-ready',{}, {ready:true});
 </script>

package/runtime/arcane/components/document-inspector.html

@@ -70,17 +70,24 @@
     const notesLabel=shadow.querySelector('[data-notes-label]');
     const saveState=shadow.querySelector('.save-state');
     const {default:MD}=await import('../modules/MD.js');
+    const {createArcaneEventSource,projectArcaneDOMEvent}=await import('arcane-os/event-manager');
+    const events=createArcaneEventSource(host,{source:'arcane.component.document-inspector',eventTypes:['document-review-change','document-inspector-ready']});
+    const lifecycleController=new AbortController();
     let rawMarkdown='';
     let renderedMarkdown='';
     let markdownMessage=null;
     let activeRecordId='';
     let loadSequence=0;
+    let loadController=null;
+    let operationSequence=0;
+    let destroyed=false;
 
     host.loadDocument=loadDocument;
     host.selectView=selectView;
+    host.destroy=destroy;
     host.ready=true;
 
-    tabs.forEach(tab=>tab.addEventListener('click',()=>selectView(tab.dataset.view)));
+    tabs.forEach(tab=>tab.addEventListener('click',()=>selectView(tab.dataset.view),{signal:lifecycleController.signal}));
     tabs.forEach(tab=>tab.addEventListener('keydown',event=>{
         if(!['ArrowLeft','ArrowRight','Home','End'].includes(event.key)) return;
         event.preventDefault();
@@ -88,16 +95,18 @@
         const index=available.indexOf(tab);
         const next=event.key==='Home'?0:event.key==='End'?available.length-1:(index+(event.key==='ArrowRight'?1:-1)+available.length)%available.length;
         selectView(available[next].dataset.view); available[next].focus();
-    }));
-    searchInput.addEventListener('input',()=>highlightSearch(searchInput.value));
+    },{signal:lifecycleController.signal}));
+    searchInput.addEventListener('input',()=>highlightSearch(searchInput.value),{signal:lifecycleController.signal});
     reviewForm.addEventListener('submit',event=>{
         event.preventDefault();
         const attributes={};
         reviewFields.querySelectorAll('[data-review-field]').forEach(field=>{attributes[field.dataset.reviewField]=field.value;});
         const detail={recordId:activeRecordId,status:reviewStatus.value,classification:reviewClassification.value||'unassigned',attributes,notes:reviewNotes.value};
         saveState.textContent='Saving…';
-        host.dispatchEvent(new CustomEvent('document-review-change',{detail,bubbles:true,composed:true}));
-    });
+        const operationId=`${events.descriptor.instanceId}:review-change:${++operationSequence}`;
+        const publication=events.dispatch('document-review-change',detail,{operationId,publicDetail:{hasRecord:Boolean(activeRecordId),attributeCount:Object.keys(attributes).length,hasNotes:Boolean(reviewNotes.value)}});
+        projectArcaneDOMEvent(host,publication.occurrence,{bubbles:true,composed:true});
+    },{signal:lifecycleController.signal});
 
     function sameOriginUrl(value){
         if(!String(value||'').trim()) throw new TypeError('A document source is required.');
@@ -117,6 +126,9 @@
     }
 
     function selectView(view='pdf'){
+        if(destroyed){
+            return false;
+        }
         const available=tabs.filter(tab=>!tab.hidden);
         const selected=available.some(tab=>tab.dataset.view===view)?view:available[0]?.dataset.view;
         tabs.forEach(tab=>{const active=tab.dataset.view===selected;tab.setAttribute('aria-selected',String(active));tab.tabIndex=active?0:-1;});
@@ -172,6 +184,12 @@
     }
 
     async function loadDocument(config={}){
+        if(destroyed){
+            return false;
+        }
+        loadController?.abort('document-replaced');
+        const controller=new AbortController();
+        loadController=controller;
         const sequence=++loadSequence;
         activeRecordId=String(config.recordId||'');
         saveState.textContent=''; searchInput.value=''; matchStatus.textContent='';
@@ -231,22 +249,41 @@
         if(hasText){
             showSurfaceMessage(markdownSurface,'Loading document text…');
             try{
-                const response=await fetch(sameOriginUrl(config.markdownUrl),{cache:'no-store',credentials:'same-origin'});
+                const response=await fetch(sameOriginUrl(config.markdownUrl),{cache:'no-store',credentials:'same-origin',signal:controller.signal});
                 if(!response.ok) throw new Error(`Document text unavailable (${response.status}).`);
                 const markdown=await response.text();
-                if(sequence!==loadSequence) return false;
+                if(destroyed||sequence!==loadSequence) return false;
                 rawMarkdown=markdown; renderedMarkdown=safeMarkdown(rawMarkdown); showMarkdown();
             }catch(error){
-                if(sequence!==loadSequence) return false;
+                if(destroyed||sequence!==loadSequence||controller.signal.aborted) return false;
                 markdownMessage={message:error.message,className:'error'}; showMarkdown();
             }
         }else{
             markdownMessage={message:'No document text is available.',className:'loading'};
             showMarkdown();
         }
+        if(loadController===controller){
+            loadController=null;
+        }
+        return !destroyed&&sequence===loadSequence;
+    }
+
+    function destroy(){
+        if(destroyed){
+            return false;
+        }
+        destroyed=true;
+        loadSequence+=1;
+        loadController?.abort('document-inspector-destroyed');
+        loadController=null;
+        lifecycleController.abort('document-inspector-destroyed');
+        pdfPanel.replaceChildren();
+        events.dispose();
+        host.ready=false;
         return true;
     }
 
-    host.markSaved=message=>{saveState.textContent=String(message||'Saved');};
-    host.dispatchEvent(new CustomEvent('document-inspector-ready',{bubbles:true,composed:true}));
+    host.markSaved=message=>{if(destroyed)return false;saveState.textContent=String(message||'Saved');return true;};
+    const readyPublication=events.dispatch('document-inspector-ready',{}, {publicDetail:{ready:true}});
+    projectArcaneDOMEvent(host,readyPublication.occurrence,{bubbles:true,composed:true});
 </script>

package/runtime/arcane/components/file-drop.html

@@ -46,6 +46,9 @@
 <script type="module">
     const host=this;
     const root=host.shadowRoot;
+    const {createArcaneEventSource,projectArcaneDOMEvent}=await import('arcane-os/event-manager');
+    const events=createArcaneEventSource(host,{source:'arcane.component.file-drop',eventTypes:['file-drop-selected','file-drop-state','file-drop-progress','file-drop-error','file-drop-ready']});
+    const lifecycleController=new AbortController();
     const dropZone=root.querySelector('#dropZone');
     const title=root.querySelector('#fileDropTitle');
     const hint=root.querySelector('#fileDropHint');
@@ -62,27 +65,38 @@
     let currentFiles=[];
     let progress=null;
     let options={};
+    let operationSequence=0;
+    let destroyed=false;
 
     host.clear=clear;
     host.configure=configure;
+    host.destroy=destroy;
     host.openPicker=openPicker;
     host.setBusy=setBusy;
     host.setError=setError;
     host.setProgress=setProgress;
 
     Object.defineProperties(host,{
-        busy:{get:()=>busy,set:setBusy},
-        files:{get:()=>currentFiles.slice()},
-        options:{get:getOptions,set:configure},
-        progress:{get:()=>progress,set:setProgress}
+        busy:{configurable:true,get:()=>busy,set:setBusy},
+        files:{configurable:true,get:()=>currentFiles.slice()},
+        options:{configurable:true,get:getOptions,set:configure},
+        progress:{configurable:true,get:()=>progress,set:setProgress}
     });
 
-    choose.addEventListener('click',openPicker);
-    picker.addEventListener('change',()=>acceptFiles(picker.files,'picker'));
-    dropZone.addEventListener('dragenter',dragEnter);
-    dropZone.addEventListener('dragover',dragOver);
-    dropZone.addEventListener('dragleave',dragLeave);
-    dropZone.addEventListener('drop',dropFiles);
+    choose.addEventListener('click',openPicker,{signal:lifecycleController.signal});
+    picker.addEventListener('change',()=>acceptFiles(picker.files,'picker'),{signal:lifecycleController.signal});
+    dropZone.addEventListener('dragenter',dragEnter,{signal:lifecycleController.signal});
+    dropZone.addEventListener('dragover',dragOver,{signal:lifecycleController.signal});
+    dropZone.addEventListener('dragleave',dragLeave,{signal:lifecycleController.signal});
+    dropZone.addEventListener('drop',dropFiles,{signal:lifecycleController.signal});
+
+    function emit(type,detail={},publicDetail={},operationId=null){
+        if(destroyed){
+            return false;
+        }
+        const publication=events.dispatch(type,detail,{publicDetail,operationId});
+        return projectArcaneDOMEvent(host,publication.occurrence,{bubbles:true,composed:true});
+    }
 
     function datasetOptions(){
         return {
@@ -96,6 +110,9 @@
     }
 
     function configure(input={}){
+        if(destroyed){
+            return false;
+        }
         const previous={...datasetOptions(),...options};
         options={
             ...previous,
@@ -121,7 +138,7 @@
     }
 
     function openPicker(){
-        if(busy){
+        if(destroyed||busy){
             return false;
         }
         picker.click();
@@ -163,12 +180,23 @@
     }
 
     function acceptFiles(fileList=[],source='api'){
+        if(destroyed){
+            return false;
+        }
+        const operationId=`${events.descriptor.instanceId}:select:${++operationSequence}`;
         const files=Array.from(fileList||[]).filter(Boolean);
         if(!files.length){
             return false;
         }
         if(options.maxFiles>0&&files.length>options.maxFiles){
-            setError(`Select no more than ${options.maxFiles} file${options.maxFiles===1?'':'s'}.`);
+            setError(
+                `Select no more than ${options.maxFiles} file${options.maxFiles===1?'':'s'}.`,
+                {
+                    code:'ARCANE_FILE_DROP_FILE_COUNT_LIMIT_EXCEEDED',
+                    reason:'file-count-limit-exceeded'
+                },
+                operationId
+            );
             return false;
         }
         currentFiles=options.multiple?files:files.slice(0,1);
@@ -176,16 +204,14 @@
         feedback.hidden=false;
         statusElement.className='status';
         statusElement.innerText=`${currentFiles.length} file${currentFiles.length===1?'':'s'} selected.`;
-        host.dispatchEvent(new CustomEvent('file-drop-selected',{
-            bubbles:true,
-            cancelable:false,
-            composed:true,
-            detail:{files:currentFiles.slice(),source}
-        }));
+        emit('file-drop-selected',{files:currentFiles.slice(),source},{fileCount:currentFiles.length,source:String(source)},operationId);
         return currentFiles.slice();
     }
 
     function setBusy(value=true,message=''){
+        if(destroyed){
+            return busy;
+        }
         busy=Boolean(value);
         choose.disabled=busy;
         picker.disabled=busy;
@@ -196,15 +222,14 @@
             statusElement.className='status';
             statusElement.innerText=`${message}`;
         }
-        host.dispatchEvent(new CustomEvent('file-drop-state',{
-            bubbles:true,
-            composed:true,
-            detail:{busy,progress}
-        }));
+        emit('file-drop-state',{busy,progress},{busy,hasProgress:progress!==null});
         return busy;
     }
 
     function setProgress(value=null,label=''){
+        if(destroyed){
+            return progress;
+        }
         const numeric=Number(value);
         progress=value===null||value===undefined||!Number.isFinite(numeric)
             ?null
@@ -218,30 +243,35 @@
             progressElement.removeAttribute('value');
             progressLabel.innerText='';
         }
-        host.dispatchEvent(new CustomEvent('file-drop-progress',{
-            bubbles:true,
-            composed:true,
-            detail:{progress,label:progressLabel.innerText}
-        }));
+        emit('file-drop-progress',{progress,label:progressLabel.innerText},{progress});
         return progress;
     }
 
-    function setError(message=''){
+    function setError(message='',errorDetail={},operationId=null){
+        if(destroyed){
+            return '';
+        }
         const text=`${message||''}`;
         feedback.hidden=!text&&progress===null;
         statusElement.innerText=text;
         statusElement.className=text?'status arcane-error':'status';
         if(text){
-            host.dispatchEvent(new CustomEvent('file-drop-error',{
-                bubbles:true,
-                composed:true,
-                detail:{message:text}
-            }));
+            const code=String(errorDetail?.code||'ARCANE_FILE_DROP_INPUT_REJECTED');
+            const reason=String(errorDetail?.reason||'file-input-rejected');
+            emit(
+                'file-drop-error',
+                {message:text,code,reason},
+                {code,reason},
+                operationId||`${events.descriptor.instanceId}:error:${++operationSequence}`
+            );
         }
         return text;
     }
 
     function clear(){
+        if(destroyed){
+            return false;
+        }
         currentFiles=[];
         picker.value='';
         setBusy(false);
@@ -256,9 +286,25 @@
         return Number.isFinite(numeric)&&numeric>=0?numeric:fallback;
     }
 
+    function destroy(){
+        if(destroyed){
+            return false;
+        }
+        destroyed=true;
+        lifecycleController.abort('file-drop-destroyed');
+        dragDepth=0;
+        busy=false;
+        currentFiles=[];
+        progress=null;
+        picker.value='';
+        events.dispose();
+        host.ready=false;
+        return true;
+    }
+
     configure(datasetOptions());
     dropZone.dataset.dragActive='false';
     setBusy(false);
     host.ready=true;
-    host.dispatchEvent(new CustomEvent('file-drop-ready',{bubbles:true,composed:true}));
+    emit('file-drop-ready',{}, {ready:true});
 </script>