@yuneta/gobj-ui 1.0.1 → 2.2.0

package/README.md

@@ -1,382 +1,59 @@
 # gobj-ui — Yuneta UI Library
 
-> **This is the `v1` (frozen) branch.** Active development is on `main` (v2).
-> See the branch table in the `main` README.
+Reusable GUI components for Yuneta GClass front-ends: a declarative shell
+(`C_YUI_SHELL`/`NAV`/`PAGER`/`WIZARD`), the legacy GClass GUI stack
+(`C_YUI_MAIN`/`WINDOW`/`TABS`/`ROUTING`), TreeDB editors, charts and maps.
 
-Reusable GUI components for building Yuneta-based web applications. Every
-component is a GClass (from [`@yuneta/gobj-js`](https://www.npmjs.com/package/@yuneta/gobj-js))
-that plugs into the GObject tree and communicates via events.
+Published as `@yuneta/gobj-ui`. Built on top of [`@yuneta/gobj-js`](https://github.com/artgins/gobj-js.js).
 
-## What this package ships
+## Two maintained lines
 
-`gobj-ui` is the **Yuneta UI library**. This `v1` line is the **frozen legacy
-GClass GUI stack only** — `C_YUI_MAIN`, `C_YUI_WINDOW`, `C_YUI_TABS`,
-`C_YUI_FORM`, `C_YUI_ROUTING`, TreeDB editors, charts and maps. It is consumed
-by **estadodelaire** and **hidraulia**, which resolve `@yuneta/gobj-ui` to this
-checkout through an npm `file:` dependency.
+This repository carries **two parallel lines** with different layouts and
+consumers. They are independent snapshots (no shared git ancestry):
 
-The **declarative shell** (`C_YUI_SHELL`, `C_YUI_NAV`, `C_YUI_PAGER`,
-`C_YUI_WIZARD`) is **not** on this line — it lives on the **v2 / `main`** line,
-consumed by **wattyzer**.
+| Line | Branch | Tag | Layout | Consumed by | How | Status |
+|------|--------|-----|--------|-------------|-----|--------|
+| **v2** | `main` | `2.0.0`+ | `src/` subdir | **wattyzer** | local `file:` dep on the yunetas submodule | active development |
+| **v1** | `v1` | `1.0.0` | `src/` subdir | **estadodelaire**, **hidraulia** | published npm `@yuneta/gobj-ui@^1.0.0` | frozen, maintenance-only |
 
-> **Where development happens.** This repo (`github.com/artgins/gobj-ui.js`) is
-> the single source of truth, embedded as a git submodule in both yunetas
-> (`kernel/js/gobj-ui`, tracking `v1`) and wattyzer (`gui/src/gobj-ui`, tracking
-> `main`/v2). All new feature work lands on `main`/v2; `v1` is maintenance-only.
+- **v2 / `main`** is the active development line: the declarative shell on top
+  of the legacy stack. It is embedded as a git submodule in **yunetas** at
+  `kernel/js/gobj-ui`, and **wattyzer** consumes that checkout as a `file:`
+  dependency (`@yuneta/gobj-ui` → `../../../yunetas/kernel/js/gobj-ui`),
+  importing by package specifier (`@yuneta/gobj-ui/src/*.js`, exports map
+  `"./src/*"`; the `index.js` barrel and the vite plugin stay at the package root).
+- **v1 / `v1`** is the frozen legacy-only stack (the declarative shell is not on
+  this line). It is **published to npm**; estadodelaire and hidraulia depend on
+  `@yuneta/gobj-ui@^1.0.0` from the registry. Land only maintenance fixes here,
+  then `npm publish` a new `1.x`.
 
-## Components
+All new feature work lands on `main`/v2.
 
-- **App shell** (`C_YUI_MAIN`) — layered layout with toolbar,
-  modals, and notifications.
-- **Window manager** (`C_YUI_WINDOW`) — draggable/resizable floating windows.
-- **Tabs** (`C_YUI_TABS`) — tab container for sub-components.
-- **Form builder** (`C_YUI_FORM`) — dynamic forms backed by Tabulator and TomSelect.
-- **Routing** (`C_YUI_ROUTING`) — hash-based menu/content
-  routing. Used by `C_YUI_MAIN`-based apps.
-- **Map** (`C_YUI_MAP`) — MapLibre GL map wrapper.
-- **Charts** (`C_YUI_UPLOT`) — uPlot chart wrapper.
-- **JSON viewer** (`C_YUI_JSON_GRAPH`) — JSON visualization with AntV/G6.
-- **TreeDB UI** — topic list, table+form editor, graph manager, and G6-based node graph editor for interacting with Yuneta TreeDB backends.
-
-Extracted from `gui_treedb` to be shared across projects (EstadoDelAire, TreeDB GUI, etc.).
-
-## Install
-
-This project uses [`vite`](https://vite.dev/) as build tool.
-
-Install the latest `node`:
-
-    nvm install --lts
-
-When writing this readme the LTS version was:
-
-    node --version
-        v22.17.0
-
-    npm install -g vite
-
-Install dependencies:
-
-    npm install
-
-To build:
-
-    vite build
-
-To publish a new version of @yuneta/gobj-ui to [npmjs.com](https://www.npmjs.com/package/@yuneta/gobj-ui):
-
-    # 1. Configure your npm token (only once)
-    echo "//registry.npmjs.org/:_authToken=<your-token>" > ~/.npmrc
-
-    # 2. Update the version in package.json
-    npm version patch   # or minor / major
-
-    # 3. Publish (build runs automatically via prepublishOnly)
-    npm publish --access public
-
-To create an npm token, go to [npmjs.com](https://www.npmjs.com) → Account → Access Tokens.
-
-## Update
-
-ONLY one time: to update all js packages, install the module:
-
-    npm install -g npm-check-updates
-
-To download new releases:
-
-    ncu -u
-
-And to install the new versions:
-
-    npm install
-
----
-
-## Quick Start
-
-### 1. Add dependency
-
-In your project's `package.json`:
-
-```json
-{
-    "dependencies": {
-        "@yuneta/gobj-ui": "file:../../../yunetas/kernel/js/gobj-ui",
-        "@yuneta/gobj-js": "file:../../../yunetas/kernel/js/gobj-js"
-    }
-}
-```
-
-Adjust the relative path to match your directory layout.
-
-### 2. Register GClasses in `main.js`
-
-```js
-import {
-    register_c_yui_main,
-    register_c_yui_window,
-    register_c_yui_tabs,
-    register_c_yui_form,
-    register_c_yui_routing,
-    register_c_yui_map,
-    register_c_yui_uplot,
-    register_c_yui_treedb_topics,
-    register_c_yui_treedb_graph,
-    inject_svg_icons,
-} from "@yuneta/gobj-ui";
-
-// Register in main():
-register_c_yui_main();
-register_c_yui_window();
-register_c_yui_tabs();
-// ... etc.
-```
-
-### 3. Import CSS
-
-```js
-import "@yuneta/gobj-ui/src/c_yui_main.css";
-import "@yuneta/gobj-ui/src/c_yui_map.css";
-import "@yuneta/gobj-ui/src/c_yui_routing.css";
-import "@yuneta/gobj-ui/src/ytable.css";
-import "@yuneta/gobj-ui/src/yui_toolbar.css";
-import "@yuneta/gobj-ui/src/lib_graph.css";
-import "@yuneta/gobj-ui/src/yui_icons.css";
-```
-
-### 4. Configure `C_YUI_MAIN` with your app branding
-
-`c_yui_main.js` does **not** import logos or flags directly. Your app provides
-them as GClass attributes:
-
-```js
-// In your c_yuneta_gui.js:
-import {logo_wide_svg} from "./logos_svg.js";      // your app logo
-import {flags_of_world} from "./locales/flags.js";  // your app flags
-
-__yuno__.__yui_main__ = gobj_create_service(
-    "__yui_main__",
-    "C_YUI_MAIN",
-    {
-        logo_wide_svg: logo_wide_svg,
-        flags_of_world: flags_of_world,
-    },
-    gobj
-);
-```
-
-### 5. Vite configuration
-
-```js
-import { defineConfig } from "vite";
-import { yunetaHtmlPlugin } from "@yuneta/gobj-ui/vite-plugin-yuneta-html.js";
-
-export default defineConfig({
-    resolve: {
-        preserveSymlinks: true,
-    },
-    plugins: [
-        yunetaHtmlPlugin({ defaultTitle: "My App" })
-    ]
-});
-```
-
-> **Note**: `preserveSymlinks: true` is required so that Vite resolves
-> `import "@yuneta/gobj-js"` from within gobj-ui's source files using the host
-> app's `node_modules/`.
-
-## Project Structure
-
-```
-gobj-ui/
-├── index.js                           # Barrel re-exports
-├── package.json                       # Peer dependencies
-├── vite-plugin-yuneta-html.js         # Shared Vite plugin
-├── skeleton/                          # Template files for new projects
-│   ├── index.html                     #   HTML template with placeholders
-│   └── config.json                    #   Documented config schema
-└── src/
-    ├── Components ─────────────────────────────────────────────
-    │   c_yui_main.js        Main app shell (layers, toolbar, modals)
-    │   c_yui_window.js      Draggable/resizable floating windows
-    │   c_yui_tabs.js        Tab container for sub-components
-    │   c_yui_form.js        Form builder (Tabulator + TomSelect)
-    │   c_yui_routing.js     Hash-based menu/content routing
-    │   c_yui_map.js         MapLibre GL map wrapper
-    │   c_yui_uplot.js       uPlot chart wrapper
-    │   c_yui_json_graph.js  JSON visualization with AntV/G6
-    │
-    ├── TreeDB Components ──────────────────────────────────────
-    │   c_yui_treedb_topics.js           Topic list management
-    │   c_yui_treedb_topic_with_form.js  Table + form editor
-    │   c_yui_treedb_graph.js            Graph manager / backend bridge
-    │   c_g6_nodes_tree.js               G6-based node graph editor
-    │
-    ├── Utilities ──────────────────────────────────────────────
-    │   lib_graph.js         DOM utilities (classes, enable/disable)
-    │   lib_icons.js         SVG icon injection
-    │   lib_maplibre.js      Custom MapLibre controls
-    │   themes.js            Light/dark theme management
-    │   ytable.js            Simple HTML table with selection
-    │   yui_toolbar.js       Horizontal scrollable toolbar
-    │   yui_dev.js           Developer tools (JSON editor, traffic)
-    │
-    └── CSS ────────────────────────────────────────────────────
-        c_yui_main.css       Main layout and layers
-        c_yui_map.css        Map styles
-        c_yui_routing.css    Router layout
-        lib_graph.css        Graph utility styles
-        ytable.css           Table styles
-        yui_toolbar.css      Toolbar styles
-        yui_icons.css        Icon font styles
-```
-
-## Exports
-
-### Components
-
-| Export | Source | Description |
-|--------|--------|-------------|
-| `register_c_yui_main` | `c_yui_main.js` | Main app shell with layers and toolbar |
-| `display_volatil_modal` | `c_yui_main.js` | Show a temporary modal |
-| `display_info_message` | `c_yui_main.js` | Show info notification |
-| `display_warning_message` | `c_yui_main.js` | Show warning notification |
-| `display_error_message` | `c_yui_main.js` | Show error notification |
-| `get_yesnocancel` | `c_yui_main.js` | Yes/No/Cancel dialog |
-| `get_yesno` | `c_yui_main.js` | Yes/No dialog |
-| `get_ok` | `c_yui_main.js` | OK dialog |
-| `register_c_yui_window` | `c_yui_window.js` | Floating window container |
-| `register_c_yui_tabs` | `c_yui_tabs.js` | Tab container |
-| `register_c_yui_form` | `c_yui_form.js` | Form builder |
-| `register_c_yui_routing` | `c_yui_routing.js` | Hash-based routing |
-| `register_c_yui_map` | `c_yui_map.js` | Map component |
-| `register_c_yui_uplot` | `c_yui_uplot.js` | Chart component |
-| `register_c_yui_json_graph` | `c_yui_json_graph.js` | JSON graph viewer |
-
-### TreeDB Components
-
-| Export | Source | Description |
-|--------|--------|-------------|
-| `register_c_yui_treedb_topics` | `c_yui_treedb_topics.js` | Topic list UI |
-| `register_c_yui_treedb_topic_with_form` | `c_yui_treedb_topic_with_form.js` | Table + form editor |
-| `register_c_yui_treedb_graph` | `c_yui_treedb_graph.js` | Graph backend bridge |
-| `register_c_g6_nodes_tree` | `c_g6_nodes_tree.js` | G6 node graph editor |
-
-### Utilities
-
-| Export | Source | Description |
-|--------|--------|-------------|
-| `addClasses`, `removeClasses`, `toggleClasses` | `lib_graph.js` | CSS class manipulation |
-| `removeChildElements` | `lib_graph.js` | Remove all children from element |
-| `disableElements`, `enableElements` | `lib_graph.js` | Enable/disable DOM elements |
-| `set_submit_state`, `set_cancel_state`, `set_active_state` | `lib_graph.js` | Visual state helpers |
-| `getStrokeColor` | `lib_graph.js` | Generate stroke from fill color |
-| `inject_svg_icons` | `lib_icons.js` | Inject SVG icon symbols into DOM |
-| `EditControl`, `MarkerControl` | `lib_maplibre.js` | Custom MapLibre GL controls |
-| `themes` | `themes.js` | Theme initialization and switching |
-| `YTable`, `createYTable` | `ytable.js` | HTML table with selection |
-| `yui_toolbar` | `yui_toolbar.js` | Scrollable toolbar builder |
-| `info_traffic`, `setup_dev` | `yui_dev.js` | Developer panel and traffic monitor |
-
-## Icon set (`yui_icons.css`)
-
-The shipped icon set is **~40 CSS-mask glyphs** with class names
-`yi-<name>`. Anything outside that list renders as a **solid black
-square** (the default CSS mask with no image). Before using a new
-icon name, grep the file:
+## Usage
 
 ```bash
-grep '^\.yi-.*::before' kernel/js/gobj-ui/src/yui_icons.css
-```
-
-If you need an icon that isn't there, add it to `yui_icons.css` first
-(SVG → CSS mask), then reference `yi-<name>` from your component. See
-memory `yui_icons_set`.
-
-## Skeleton — Starting a New Project
-
-Copy the template files from `skeleton/` to bootstrap a new GUI:
-
-```bash
-cp gobj-ui/skeleton/index.html  my-gui/index.html
-cp gobj-ui/skeleton/config.json my-gui/config.json
-```
-
-### `index.html`
-
-A clean, invariant HTML file with three placeholders replaced at build time:
-
-| Placeholder | Replaced with | Source |
-|-------------|---------------|--------|
-| `<!-- CSP_PLACEHOLDER -->` | Full `<meta http-equiv="Content-Security-Policy">` tag | `config.json → csp_connect_src` |
-| `<title></title>` | `<title>My App</title>` | `config.json → title` |
-| `<!-- METADATA_PLACEHOLDER -->` | `<meta name="..." content="...">` tags | `config.json → metadata` |
+# v2 (active): clone yunetas with submodules; wattyzer picks it up via file:
+git clone --recurse-submodules <yunetas>
+git submodule update --init kernel/js/gobj-ui      # yunetas tracks main/v2
 
-**You should not edit `index.html` directly.** All variable parts go in `config.json`.
-
-### `config.json`
-
-```json
-{
-    "title": "My Yuneta GUI",
-
-    "metadata": {
-        "application-name": "My Yuneta GUI",
-        "description": "Yuneta-based GUI application",
-        "keywords": "yuneta gui"
-    },
-
-    "csp_connect_src": [
-        "wss://localhost:1800",
-        "https://localhost:1801",
-        "https://auth.artgins.com"
-    ]
-}
+# v1 (frozen): consumers just install the published package
+npm install @yuneta/gobj-ui@^1.0.0
 ```
 
-**`csp_connect_src`** must list every origin from `backend_config.js`:
-- Each `backend_urls` value (`wss://...`)
-- Each BFF endpoint (`https://...:port`)
-- Each Keycloak `auth-server-url` (`https://...`)
-
-Entries starting with `_comment` are ignored (used for inline documentation).
+Edit v2 from the yunetas `kernel/js/gobj-ui` checkout, commit on `main` in this
+repo, then bump that submodule pointer in yunetas. For v1, work from a `v1`
+checkout and publish.
 
-## Vite Plugin — `yunetaHtmlPlugin`
+## Build & test
 
-Shared plugin that replaces the placeholders in `index.html` at build time.
-
-```js
-import { yunetaHtmlPlugin } from "@yuneta/gobj-ui/vite-plugin-yuneta-html.js";
-
-// Options:
-yunetaHtmlPlugin({
-    defaultTitle: "My App",     // Fallback if config.json is missing
-    configPath: "./config.json" // Custom path (default: ./config.json)
-})
+```bash
+npm install
+npm run build      # vite -> dist/ (ES/CJS/UMD/IIFE, min + non-min)
+npm test           # vitest (v2/main only; v1 has no test target)
 ```
 
-The plugin generates a strict Content-Security-Policy with:
-- `default-src 'self'`
-- `script-src 'self'`
-- `style-src 'self' 'unsafe-inline'` (required by Bulma)
-- `connect-src 'self' <origins from csp_connect_src>`
-- `worker-src 'self' blob:`
-- `child-src 'self' blob:`
-- `img-src 'self' data: blob:`
-- `font-src 'self' data:`
-
-## Peer Dependencies
-
-gobj-ui does **not** bundle these — your project must include them:
+`dist/` is gitignored. v1 consumers get `dist/` from the **published** npm
+tarball; v2 (wattyzer) imports source files by specifier. Rebuild `dist/` to
+validate and before publishing a v1 release.
 
-| Package | Used by |
-|---------|---------|
-| `@yuneta/gobj-js` | All components (GClass framework) |
-| `@antv/g6` | `c_g6_nodes_tree`, `c_yui_json_graph` |
-| `bulma` | All components (CSS framework) |
-| `i18next` | `c_yui_main`, `c_yui_form` (i18n) |
-| `maplibre-gl` | `c_yui_map` |
-| `tabulator-tables` | `c_yui_form`, `c_yui_treedb_topic_with_form` |
-| `tom-select` | `c_yui_form`, `c_yui_treedb_topic_with_form` |
-| `uplot` | `c_yui_uplot` |
-| `vanilla-jsoneditor` | `c_yui_treedb_topic_with_form`, `yui_dev` |
+Copyright (c) 2024-2026, ArtGins. All Rights Reserved.