asljs-part-srv 0.1.1 → 0.1.2

package/README.md

@@ -9,8 +9,8 @@
 editor in the browser, as a tree of folders, each opened as a tab of its
 details - path, size, modification time - and the artefact definitions that
 match it. Each `part.json` of the working directory, else of its folders, is a
-project, chosen in a list box. It reads a project on every request and never
-serves the content of a file.
+project, chosen in a selector that finds it by its title. It reads a project on
+every request and never serves the content of a file.
 
 ## Installation
 

package/dist/app.d.ts

@@ -1,7 +1,7 @@
 import { type EditorApp, type EditorAppContext } from 'asljs-appbase';
 /**
  * The part application as an editor plugin: its projects, by `part.json`.
- * Each `part.json` `findProjects` finds from the working directory is a
+ * Each `part.json` `findAppProjects` finds from the working directory is a
  * project. A project's root, definitions and state folder come from its own
  * `part.json` only, else the default, when it is first requested; no option
  * or environment variable sets them, since one value cannot suit every

package/dist/app.js

@@ -1,15 +1,34 @@
-import { configPath, configStrings, createEditorApp, findBrowserModules, findProjects, stateFolder } from 'asljs-appbase';
+import { configPath, configStrings, createEditorApp, findAppProjects, findBrowserModules, stateFolder } from 'asljs-appbase';
 import { CONFIG_FILE, resolveDefinitionSource } from 'asljs-part';
 import { ICONS } from 'asljs-ui-editor';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createProjectHandler } from './view.js';
 /**
- * The style of an artefact's details: a scrolling view of the tab, its
- * table of the location, path, size and modification time, and its list of
- * definitions.
+ * The style of an artefact's details: the tab, the details with the preview
+ * of a file on their right and an action bar along its bottom, as the graph
+ * of `rq-srv` has them; a scrolling view of the details, their table of the
+ * location, path, size and modification time, and their list of
+ * definitions; and the file's content in the preview.
  */
-const STYLE = `.part-view { height: 100%; box-sizing: border-box; overflow: auto; padding: 0.75rem 1rem; line-height: 1.5; }
+const STYLE = `.part-document { height: 100%; display: flex; flex-direction: column; background: #fff; }
+.part-stage { flex: 1; min-height: 0; display: flex; }
+.part-view { flex: 1; min-width: 0; box-sizing: border-box; overflow: auto; padding: 0.75rem 1rem; line-height: 1.5; }
+asljs-diagram-preview { width: min(40rem, 45vw); border-left: 1px solid #ddd; background: #fff; }
+.asljs-diagram-preview-splitter { background: transparent; transition: background 0.15s; }
+.asljs-diagram-preview-splitter:hover, .asljs-diagram-preview-splitter:focus-visible { background: #1a73e8; outline: none; }
+.asljs-diagram-preview-placeholder, .asljs-diagram-preview-body > .asljs-plugin-note { margin: 1rem; color: #757575; }
+.part-actionbar { display: flex; align-items: center; justify-content: flex-end; padding: 2px 8px; background: #f3f4f6; border-top: 1px solid #ddd; }
+.asljs-diagram-preview-tabs { gap: 2px; }
+.asljs-diagram-preview-tab { border: 0; border-radius: 4px; background: none; padding: 3px 10px; font: inherit; color: #555; cursor: pointer; }
+.asljs-diagram-preview-tab:hover:not(:disabled) { background: #e5e7eb; }
+.asljs-diagram-preview-tab[aria-selected="true"] { background: #dbe7fd; color: #1a73e8; }
+.asljs-diagram-preview-toggle { width: 28px; height: 28px; display: grid; place-items: center; border: 0; border-radius: 4px; background: none; color: #555; cursor: pointer; }
+.asljs-diagram-preview-toggle:hover:not(:disabled) { background: #e5e7eb; }
+.asljs-diagram-preview-toggle[aria-expanded="true"] { color: #1a73e8; }
+.part-content { flex: 1; min-height: 0; overflow: auto; margin: 0; padding: 0.75rem 1rem; box-sizing: border-box; }
+.part-text { font-family: ui-monospace, monospace; font-size: 0.85rem; line-height: 1.45; white-space: pre; }
+.part-image { max-width: 100%; }
 .part-details { border-collapse: collapse; margin: 0 0 1rem; }
 .part-details th { text-align: left; color: #555; font-weight: normal; padding: 2px 1rem 2px 0; vertical-align: top; }
 .part-details td { padding: 2px 0; word-break: break-all; }
@@ -18,15 +37,16 @@ const STYLE = `.part-view { height: 100%; box-sizing: border-box; overflow: auto
 .part-note { color: #757575; }`;
 /**
  * The part application as an editor plugin: its projects, by `part.json`.
- * Each `part.json` `findProjects` finds from the working directory is a
+ * Each `part.json` `findAppProjects` finds from the working directory is a
  * project. A project's root, definitions and state folder come from its own
  * `part.json` only, else the default, when it is first requested; no option
  * or environment variable sets them, since one value cannot suit every
  * project.
  */
 export async function createApp(context) {
-    const projects = await findProjects(context.cwd, CONFIG_FILE, context.files);
-    return createEditorApp({ id: 'part',
+    const projects = await findAppProjects(context, CONFIG_FILE, { required: true });
+    return createEditorApp({
+        id: 'part',
         title: 'Part',
         icon: ICONS.document,
         base: context.base,
@@ -35,8 +55,11 @@ export async function createApp(context) {
         plugin: fileURLToPath(new URL('./browser/plugin.js', import.meta.url)),
         // The page loads the plugin's packages, and what they import, from
         // the server.
-        modules: findBrowserModules(['asljs-ui-editor'], path.dirname(fileURLToPath(import.meta.url))),
-        style: STYLE });
+        modules: findBrowserModules(['asljs-ui-diagram',
+            'asljs-ui-editor',
+            'asljs-ui-markdown'], path.dirname(fileURLToPath(import.meta.url))),
+        style: STYLE
+    });
 }
 /**
  * The project part reads in an application project: `project`,

package/dist/browser/plugin.d.ts

@@ -5,7 +5,9 @@ import { type EditorPluginFactory } from 'asljs-ui-editor';
  * `_/data.json` once, when it is made. Its Artefacts operation is a
  * `pathTree` of their locations, grouped by `locationSegments`, its groups
  * folded. Choosing an entry opens its details as a document whose id is
- * `part:<location>`, rendered here from `_/artefact.json`. Its search finds
+ * `part:<location>`, rendered here from `_/artefact.json`, with the preview
+ * of a file on their right, `previewOf`, in an `asljs-diagram-preview`
+ * whose state, shared by the tabs, this browser keeps. Its search finds
  * artefacts by location (`searchMatcher`), at most `MAX_RESULTS` of them: a
  * file by its path, with or without `file:`, and another artefact by its
  * location. Every URL is relative to the project's `base`.

package/dist/browser/plugin.js

@@ -1,16 +1,29 @@
-import { element, fetchJson, ICONS, note, pathTree, searchMatcher, tree } from 'asljs-ui-editor';
+import { observable } from 'asljs-observable';
+import { createPreviewModel } from 'asljs-ui-diagram';
+import { element, fetchJson, ICONS, note, pathHref, pathTree, projectPath, searchMatcher, tree } from 'asljs-ui-editor';
+import { markdownDocument } from 'asljs-ui-markdown';
 import { locationSegments } from './locations.js';
 /**
  * How many matches a search shows.
  */
 const MAX_RESULTS = 200;
+/**
+ * Where the browser keeps the state of the details' preview.
+ */
+const LAYOUT_KEY = 'part-view-layout';
+/**
+ * The largest file the preview shows, in bytes.
+ */
+const PREVIEW_LIMIT = 1024 * 1024;
 /**
  * The plugin of a project, the browser module of `asljs-ui-editor` the
  * server serves. It loads the project's files and other artefacts from
  * `_/data.json` once, when it is made. Its Artefacts operation is a
  * `pathTree` of their locations, grouped by `locationSegments`, its groups
  * folded. Choosing an entry opens its details as a document whose id is
- * `part:<location>`, rendered here from `_/artefact.json`. Its search finds
+ * `part:<location>`, rendered here from `_/artefact.json`, with the preview
+ * of a file on their right, `previewOf`, in an `asljs-diagram-preview`
+ * whose state, shared by the tabs, this browser keeps. Its search finds
  * artefacts by location (`searchMatcher`), at most `MAX_RESULTS` of them: a
  * file by its path, with or without `file:`, and another artefact by its
  * location. Every URL is relative to the project's `base`.
@@ -30,11 +43,82 @@ const createPlugin = async ({ id, base, model }) => {
             document: location => documentOf(location, locationSegments(location).at(-1)),
             open: false }));
     };
+    // The preview of the details: whether it is shown, its mode and its
+    // width, kept in this browser.
+    let stored = {};
+    try {
+        stored =
+            JSON.parse(localStorage.getItem(LAYOUT_KEY) ?? '{}');
+    }
+    catch {
+        // Without storage, the preview starts open.
+    }
+    const preview = createPreviewModel(stored.preview
+        ?? { open: true,
+            mode: 'view' });
+    preview.on('change', () => {
+        try {
+            localStorage.setItem(LAYOUT_KEY, JSON.stringify({ preview: { open: preview.open,
+                    mode: preview.mode,
+                    width: preview.width } }));
+        }
+        catch {
+            // Without storage, the preview lasts until the page is reloaded.
+        }
+    });
+    // A link of a previewed markdown file to another file of the project
+    // opens that file's details.
+    const openLink = (url) => {
+        const relative = projectPath(base, url);
+        const file = relative === null
+            ? undefined
+            : files.find(candidate => candidate.replaceAll('\\', '/')
+                === relative);
+        if (file === undefined) {
+            return false;
+        }
+        model.open(documentOf(`file:${file}`, locationSegments(`file:${file}`).at(-1)));
+        return true;
+    };
     const renderDocument = (opened) => {
         const { location } = opened.data;
-        const view = element('div', 'part-view');
+        const view = element('div', 'part-document');
+        const details = element('div', 'part-view');
+        // The panel shows the file of the details, once they are read: its
+        // selection is the file's path, and none for another artefact.
+        const shown = observable({ selection: [] });
+        let file = null;
+        const modes = [{ id: 'view',
+                title: 'View',
+                isEnabled: selection => selection.length === 1
+                    && file !== null,
+                render: async () => await previewOf(base, file, openLink) }];
+        const panel = document.createElement('asljs-diagram-preview');
+        panel.placeholder = '';
+        panel.modes = modes;
+        panel.model = shown;
+        panel.preview = preview;
+        const stage = element('div', 'part-stage');
+        stage.append(details, panel);
+        const tabs = document.createElement('asljs-diagram-preview-tabs');
+        tabs.modes = modes;
+        tabs.preview = preview;
+        const bar = element('div', 'part-actionbar');
+        bar.append(tabs);
+        view.append(stage, bar);
         void fetchJson(base, `_/artefact.json?location=${encodeURIComponent(location)}`)
-            .then(details => view.append(...detailsView(details)), (error) => view.append(note(error instanceof Error
+            .then((read) => {
+            details.append(...detailsView(read));
+            if (read.path === null) {
+                panel.placeholder =
+                    'Only a file has a preview.';
+            }
+            else {
+                file = read;
+            }
+            shown.selection =
+                [location];
+        }, (error) => details.append(note(error instanceof Error
             ? error.message
             : String(error))));
         return view;
@@ -47,6 +131,9 @@ const createPlugin = async ({ id, base, model }) => {
                 icon: ICONS.document,
                 render: artefactsPanel }],
         renderDocument,
+        documentOf: location => documentOf(location, location
+            .split(/[\\/]/)
+            .at(-1)),
         search: async (query) => {
             const matches = searchMatcher(query);
             return [...files
@@ -86,6 +173,61 @@ function detailsView(details) {
         element('h2', undefined, 'Definitions'),
         definitionsView(details.definitions)];
 }
+/**
+ * The preview of a file, read from the server as it is: an image as an image,
+ * a markdown file rendered, `openLink` opening its links to other files, and
+ * other text as it is; a note for a binary file, one over `PREVIEW_LIMIT`,
+ * and one the server does not serve.
+ */
+async function previewOf(base, file, openLink) {
+    if ((file.size
+        ?? 0)
+        > PREVIEW_LIMIT) {
+        return note(`The file is too large to preview, ${file.size} bytes.`);
+    }
+    const url = new URL(pathHref(base, file.path), location.href);
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            return note(`The file has no preview: ${response.status} ${response.statusText}`
+                .trim());
+        }
+        if ((response.headers.get('content-type') ?? '')
+            .startsWith('image/')) {
+            const image = element('img', 'part-image');
+            image.src = url.href;
+            image.alt = file.name;
+            const frame = element('div', 'part-content');
+            frame.append(image);
+            return frame;
+        }
+        let text;
+        try {
+            text =
+                new TextDecoder('utf-8', { fatal: true })
+                    .decode(await response.arrayBuffer());
+        }
+        catch {
+            text = '\0';
+        }
+        if (text.includes('\0')) {
+            return note('A binary file has no preview.');
+        }
+        if (/\.md$/i.test(file.path)) {
+            return markdownDocument({ url,
+                load: async () => ({ body: text }),
+                openLink });
+        }
+        const code = element('pre', 'part-content part-text');
+        code.append(element('code', undefined, text));
+        return code;
+    }
+    catch (error) {
+        return note(error instanceof Error
+            ? error.message
+            : String(error));
+    }
+}
 function row(label, value) {
     const made = element('tr');
     const cell = element('td');

package/dist/project.js

@@ -1,5 +1,5 @@
-import { isInside } from 'asljs-locator';
 import { toDisplayPath } from 'asljs-appbase';
+import { isInside } from 'asljs-locator';
 import { FILE_SCHEME, providersFactory } from 'asljs-part';
 import { stat } from 'node:fs/promises';
 import path from 'node:path';

package/dist/view.d.ts

@@ -13,8 +13,14 @@ export declare const DATA_PATH = "/_/data.json";
 /**
  * The handler of a project, relative to where it is mounted. It answers
  * data, which the plugin renders: `DATA_PATH` the files and the other
- * artefacts of the project, and `ARTEFACT_PATH` the details of an artefact,
- * or 404 with `{ error }` saying why there is none. No file of the project
- * is served; the project is read on every request.
+ * artefacts of the project, `ARTEFACT_PATH` the details of an artefact, or
+ * 404 with `{ error }` saying why there is none, and a file of the project
+ * root by its path, as it is, for the preview, unless `isServed` refuses it.
+ * The project is read on every request.
  */
 export declare function createProjectHandler(project: Project): RequestHandler;
+/**
+ * Whether a file of the project is served, by its path relative to the
+ * root: not one in a dot folder, a dot file or one under `node_modules`.
+ */
+export declare function isServed(relative: string): boolean;

package/dist/view.js

@@ -13,9 +13,10 @@ export const DATA_PATH = '/_/data.json';
 /**
  * The handler of a project, relative to where it is mounted. It answers
  * data, which the plugin renders: `DATA_PATH` the files and the other
- * artefacts of the project, and `ARTEFACT_PATH` the details of an artefact,
- * or 404 with `{ error }` saying why there is none. No file of the project
- * is served; the project is read on every request.
+ * artefacts of the project, `ARTEFACT_PATH` the details of an artefact, or
+ * 404 with `{ error }` saying why there is none, and a file of the project
+ * root by its path, as it is, for the preview, unless `isServed` refuses it.
+ * The project is read on every request.
  */
 export function createProjectHandler(project) {
     return createHandler({ folder: project.root,
@@ -28,5 +29,15 @@ export function createProjectHandler(project) {
                     return jsonReply(404, { error: `${messageOf(error)}.` });
                 }
             } },
-        allow: () => false });
+        allow: isServed });
+}
+/**
+ * Whether a file of the project is served, by its path relative to the
+ * root: not one in a dot folder, a dot file or one under `node_modules`.
+ */
+export function isServed(relative) {
+    return !relative
+        .split('/')
+        .some(segment => segment.startsWith('.')
+        || segment === 'node_modules');
 }

package/docs/part-srv.md

@@ -26,7 +26,10 @@ folder, `--working-dir` or else the working directory:
   path from the working folder, leaving out what `.gitignore` ignores, `.git`
   and `node_modules`.
 - With none, the working folder is the one project, with the nearest `part.json`
-  of a parent, or none.
+  of a parent.
+- With no `part.json` there either, `part-srv` stops with an error, since a
+  project's `part.json` says which artefacts it supports; `factory-srv` serves
+  its other applications.
 
 The root, the definitions and the state folder of each project come from its own
 `part.json` only, `project`, `definitions` and `stateDir`, its paths resolved
@@ -49,8 +52,9 @@ server that shows several applications serves it at `/part/`.
   icon opens its panel next to the column; the button at the bottom of the
   column hides and shows the panel. Dragging the panel's inner edge resizes it,
   and the browser remembers the width, and the project shown, for the next
-  visit. With more than one project, a list box heads the panel; choosing
-  another project closes the details of the one before.
+  visit. With more than one project, a selector heads the panel, its filter box
+  finding a project by its title; choosing another project shows its artefacts,
+  and the details of the one before stay open.
   - **Artefacts** - the artefacts of the project as one tree of their locations,
     folded at first: grouped by scheme, such as `file:`, `npm:` or `git:`, then
     by each segment of the path, anything between `/` or `\`, as `npm:` >
@@ -75,6 +79,16 @@ server that shows several applications serves it at `/part/`.
   first paragraph of its description; a file no definition matches says so. A
   file that does not exist, a path outside the project and an unknown location
   give a note that says so.
+
+  The details have a preview of their file on their right, as the graph of
+  `rq-srv` has of its node: an `asljs-diagram-preview` of `asljs-ui-diagram`,
+  read from the server as the file is. An image is shown, a markdown file is
+  rendered - a link to another file of the project opens that file's details -
+  and other text is shown as it is. A binary file, one over 1 MiB, one the
+  server does not serve, and an artefact that is not a file have a note instead.
+  The View tab at the right of the action bar under the details shows it, and
+  the button after it shows and hides it; dragging its left edge resizes it, and
+  the browser remembers its width and whether it is shown, for every tab.
 - `/_/app.json` - the application and its projects, each with the path it is
   served at; `/_/plugin/plugin.js` - the plugin the editor loads, a browser
   module, with the modules beside it under `/_/plugin/`.
@@ -90,12 +104,15 @@ server that shows several applications serves it at `/part/`.
     a `file:` location, a path relative to the project root, or the location of
     another artefact. When there is none, the answer is 404 with `{ error }`,
     the message the details tab shows.
-
-The content of a file is never read or served: the server answers the details
-only, and serves nothing of a project but its data. The project is read on every
-request, so a reload shows the files as they are. The page loads
-`asljs-ui-editor` and what it imports from the server, under `/modules/`, so it
-needs no network.
+  - `/p/<project>/<path>` - a file of the project root, by its path, as it is,
+    for the preview: a `.md` file as `text/markdown`. A file in a dot folder, a
+    dot file and a file under `node_modules` are not found.
+
+The server renders nothing: it answers the details and the files as they are,
+and the preview is made in the browser. The project is read on every request, so
+a reload shows the files as they are. The page loads `asljs-ui-editor`,
+`asljs-ui-diagram`, `asljs-ui-markdown` and what they import from the server,
+under `/modules/`, so it needs no network.
 
 ## Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asljs-part-srv",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The part-srv web server: a project's files in an editor, each with its details and the artefact definitions that match it.",
   "type": "module",
   "asljs": {
@@ -22,22 +22,37 @@
     "dist/**",
     "docs/**",
     "README.md",
-    "LICENSE.md"
+    "LICENSE.md",
+    "!dist/*.tsbuildinfo"
   ],
   "scripts": {
     "flint": "toolkit flint",
-    "clean": "toolkit clean",
-    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
-    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "clean:build": "node ../../../scripts/cleanBuildOutDir.js",
+    "clean:dist": "node ../../../scripts/cleanDistOutDir.js",
+    "compile:build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "compile:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "build:dist": "node ../../../scripts/buildDistDeps.js && npm run compile:dist",
     "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
     "guard:clean-git": "toolkit ensure-clean-working-directory",
-    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "prepack": "npm run clean:build && npm run clean:dist && npm run build:dist && npm run compile:build && npm run test && npm run guard:clean-git",
     "postpublish": "toolkit tag-release-revision",
     "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
     "test:watch": "node --watch --test \"build/**/*.test.js\"",
     "release:patch": "toolkit release-patch",
-    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+    "build": "npm run clean:build && npm run flint && npm run typecheck && npm run compile:build && npm run test"
   },
+  "distDependencies": [
+    "asljs-appbase",
+    "asljs-locator",
+    "asljs-logging",
+    "asljs-observable",
+    "asljs-part",
+    "asljs-testing",
+    "asljs-tmpdir",
+    "asljs-ui-diagram",
+    "asljs-ui-editor",
+    "asljs-ui-markdown"
+  ],
   "keywords": [
     "artefacts",
     "project",
@@ -57,8 +72,11 @@
     "asljs-locator": "^0.1.1",
     "asljs-logging": "^0.1.1",
     "asljs-appbase": "^0.1.3",
+    "asljs-observable": "^0.5.6",
     "asljs-part": "^0.3.2",
+    "asljs-ui-diagram": "^0.1.2",
     "asljs-ui-editor": "^0.1.1",
+    "asljs-ui-markdown": "^0.1.1",
     "commander": "^15.0.0"
   },
   "devDependencies": {