flexdesk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nor-os
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# FlexDesk
+
+A tiling window manager and widget set for desktop-class web applications.
+
+Tiles that split and tab, a command palette, dockable panels, virtual desktops, a
+DataTable with sticky headers and CSV export, managed windows, modals, toasts,
+trees and context menus.
+
+**Zero runtime dependencies.** No React, no framework, nothing. If you install
+FlexDesk, you install FlexDesk.
+
+FlexDesk was extracted from [EcoAgent](https://github.com/nor-os/EcoAgent), a
+macroeconomic simulation platform, and it knows nothing about economics: no
+application vocabulary, no import of anything application-specific, in any
+shipped file.
+
+```bash
+npm install flexdesk
+```
+
+Or vendor `dist/` and load it through an import map — no bundler, no build step.
+That is exactly what EcoAgent does:
+
+```html
+<script type="importmap">
+{ "imports": {
+    "@flexdesk/core":    "./vendor/flexdesk/core.js",
+    "@flexdesk/host":    "./vendor/flexdesk/host.js",
+    "@flexdesk/wm":      "./vendor/flexdesk/wm.js",
+    "@flexdesk/widgets": "./vendor/flexdesk/widgets.js"
+} }
+</script>
+<link href="./vendor/flexdesk/flexdesk.css" rel="stylesheet" />
+```
+
+## Seven entry points
+
+Because someone who wants a DataTable should not have to download a window
+manager, and neither of them should drag in a plotting engine or a code editor.
+
+| Entry | Size | What is in it |
+|---|---|---|
+| `@flexdesk/core` | 30 kB | Event bus, settings store, logging, state machine, state guard |
+| `@flexdesk/host` | 5 kB | The host port (below) |
+| `@flexdesk/wm` | 166 kB | Tiling window manager: tabs, splits, desktops, command palette, taxonomy, `createShell()` |
+| `@flexdesk/widgets` | 192 kB | DataTable, modals, managed windows, toasts, trees, panels, context menus |
+| `@flexdesk/charts` | 26 kB | Plotly wrapper, chart types, subplot layouts, downsampling, plot windows |
+| `@flexdesk/tiles` | 67 kB | Draggable/resizable widget grid, tile base class, widget registry, layout persistence |
+| `@flexdesk/editor` | 62 kB | Monaco loader + factory, multi-file tab bar, search, split panes, undo manager |
+
+They share code through chunks, so importing two of them does **not** give you two
+event buses — and therefore not two copies of every module-level singleton. A test
+asserts each kernel symbol is defined exactly once across the whole `dist/`.
+
+Two different things here are called "tiles", which is unfortunate but honest to
+the code: `@flexdesk/wm` tiles the *window*; `@flexdesk/tiles` is a dashboard
+*widget grid*.
+
+## Hello, shell
+
+```js
+import { createShell, createTaxonomy, createEntityCatalog } from '@flexdesk/wm';
+import { createHost } from '@flexdesk/host';
+import { DataTable } from '@flexdesk/widgets';
+
+const store = new Map();
+
+const shell = await createShell({
+    root: document.getElementById('app'),
+
+    // YOUR ontology. FlexDesk has none.
+    taxonomy: createTaxonomy({
+        root: 'cosmos',
+        kinds: {
+            cosmos: { label: 'Cosmos', isTopNav: true, sources: ['planet'] },
+            planet: { label: 'Planet', icon: 'circle' },
+            moon: {
+                label: 'Moon',
+                // "jupiter/europa" — your naming convention, not the library's.
+                ancestors: ({ id }) => {
+                    const i = String(id).indexOf('/');
+                    return i > 0 ? [{ kind: 'planet', id: String(id).slice(0, i) }] : [];
+                },
+            },
+        },
+    }),
+
+    entities: createEntityCatalog({ sources: [/* what the palette searches */] }),
+    content:  { planet: (hostEl, props) => { /* render a tile */ } },
+
+    // Where persistence goes. An in-memory Map is a perfectly good host.
+    host: createHost({
+        state: {
+            read:  async (k) => store.get(k) ?? null,
+            write: async (k, v) => (store.set(k, v), true),
+        },
+    }),
+
+    // Chrome is ELEMENTS, not selectors. The library never guesses at your markup.
+    chrome: { topNav: document.getElementById('nav') },
+});
+```
+
+A working version of exactly this — planets and moons, a mock host, no backend —
+lives in `demo/`.
+
+## The host port
+
+FlexDesk never touches `pywebview`, `fetch`, `localStorage` or the filesystem. It
+asks a **Host**, and you supply one. `createHost({...})` validates the capabilities
+you pass and freezes the result; anything you leave out is simply absent, and the
+library degrades rather than throwing.
+
+```js
+createHost({
+    state:   { read, write },              // layout persistence
+    dialogs: { saveFile },                 // optional — CSV export falls back to a Blob
+    window:  { minimize, maximize, ... },  // optional — no native chrome buttons without it
+})
+```
+
+`NULL_HOST` is a valid host with nothing behind it.
+
+## Peer dependencies
+
+`@flexdesk/charts` needs Plotly (4.4 MB). `@flexdesk/editor` needs Monaco (14 MB).
+Neither is bundled, and **neither is guessed at**:
+
+```js
+import { setPlotlySource } from '@flexdesk/charts';
+import { setMonacoBasePath, setDefaultLanguage } from '@flexdesk/editor';
+
+setPlotlySource('/vendor/plotly/plotly.min.js');
+setMonacoBasePath('/vendor/monaco');
+setDefaultLanguage('my-dsl');              // default: 'plaintext'
+```
+
+There is deliberately **no default path**. A hardcoded `'vendor/monaco'` is one
+application's directory layout, and for everyone else it is a 404 that surfaces as
+an editor which silently never appears. `initMonaco()` throws instead.
+
+If you already load Plotly yourself (a `<script>` tag that sets `window.Plotly`),
+the chart loader short-circuits and you can skip `setPlotlySource`.
+
+## Layouts are keyed by whatever you key them by
+
+`@flexdesk/tiles` stores layouts under keys **you** choose and resolves a starting
+layout through a callback **you** supply:
+
+```js
+import { configureLayoutPersistence } from '@flexdesk/tiles';
+
+configureLayoutPersistence({
+    layoutsKey: 'myapp.layouts',                          // default: 'twm.tiles.layouts'
+    resolveTemplate: (ctx) => pickTemplate(ctx) ?? null,  // null => empty grid
+});
+```
+
+**Configure it before anything reads it.** The store is a singleton; built before
+you supply your key, it is built with the default, and every layout your users have
+saved becomes silently invisible. That is a data-loss bug that raises no error, so
+the configuration step is explicit rather than lazy.
+
+A layout is keyed by *something* — a document, a user, a run — and the library has
+no opinion about which. It calls that a `contextId`.
+
+## Styling
+
+Three stylesheets, and that is the whole CSS contract:
+
+| | |
+|---|---|
+| `dist/tokens.css` | Every rule reads `var(--…)` from here. Swap this one file and the shell restyles. |
+| `dist/reset.css` | The reset. |
+| `dist/flexdesk.css` | The library. Every class is `twm-` prefixed (the original working name; the prefix is stable and not worth a breaking rename). |
+
+Icons are rendered by applying the `material-symbols-outlined` class. FlexDesk does
+not ship the font — supply it from Google Fonts or self-host. Without it, icons fall
+back to their text names and nothing breaks.
+
+## Build
+
+```bash
+npm install
+npm run build      # -> dist/
+```
+
+`dist/` is committed. The packaging decision is *prebuilt dist*: this repo owns the
+build so that a consumer with no bundler can load the library through a plain import
+map. See `.gitignore` — it says so there too, because it is the kind of thing someone
+"tidies up" later.
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE) and [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,53 @@
+# Third-party licences
+
+FlexDesk itself is MIT (see `LICENSE`).
+
+## Runtime dependencies: none
+
+FlexDesk has **zero runtime dependencies**. Nothing is bundled into `dist/` except
+FlexDesk's own source. The build declares `external: []`, so if a dependency were
+ever introduced, the build would fail on an unresolved bare specifier rather than
+quietly growing one.
+
+If you install `flexdesk`, you install nothing else.
+
+| | |
+|---|---|
+| Bare-specifier imports in `src/` | **0** |
+| `dependencies` in `package.json` | **none** |
+| External assets referenced by `dist/flexdesk.css` | **none** (its one image is an inline `data:` URI) |
+
+## Optional peer dependencies
+
+These are **not installed, not bundled, and not required**. Each is needed only if
+you import the entry point that uses it, and FlexDesk never guesses where you keep
+it — you tell it (`setPlotlySource()`, `setMonacoBasePath()`).
+
+| Package | Needed by | Licence | Copyright |
+|---|---|---|---|
+| [plotly.js](https://github.com/plotly/plotly.js) | `@flexdesk/charts` | MIT | Plotly, Inc. |
+| [monaco-editor](https://github.com/microsoft/monaco-editor) | `@flexdesk/editor` | MIT | Microsoft Corporation |
+
+## Optional asset
+
+FlexDesk's widgets render icons by applying the `material-symbols-outlined` class.
+The font itself is **not shipped** — you supply it, from Google Fonts or self-hosted.
+Without it, icons fall back to their text names; nothing breaks.
+
+| Asset | Licence | Copyright |
+|---|---|---|
+| [Material Symbols](https://github.com/google/material-design-icons) | Apache-2.0 | Google LLC |
+
+## Build-time only
+
+Not shipped, not a dependency of consumers.
+
+| Package | Licence | Copyright |
+|---|---|---|
+| [esbuild](https://github.com/evanw/esbuild) | MIT | Evan Wallace |
+
+---
+
+Every licence above was read from the package's own `LICENSE` file or from the
+licence header in the distributed artifact — not from memory. Material Symbols was
+confirmed against `google/material-design-icons/LICENSE`.