@aaqu/fromcubes-react 0.1.0 → 0.2.0

package/README.md

@@ -6,20 +6,19 @@
 [![Node-RED](https://img.shields.io/badge/Node--RED-%E2%89%A5%204.0-8f0000.svg)](https://nodered.org)
 [![license](https://img.shields.io/npm/l/%40aaqu%2Ffromcubes-react.svg)](./LICENSE)
 [![Discord](https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/KYzsfKkYxX)
+[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Aaqu)
 
 **📖 Documentation — step-by-step guide with screenshots:** [aaqu.github.io/fromcubes-modules](https://aaqu.github.io/fromcubes-modules/) — install → import → edit JSX → live dashboard, on one example.
 
 [![Documentation walkthrough](https://aaqu.github.io/fromcubes-modules/img/docs-scroll.gif)](https://aaqu.github.io/fromcubes-modules/)
 
-> **⚠️ Alpha Module** — This project is in early development. Expect breaking changes. Test on a clean Node-RED instance.
-
 A Node-RED node that turns any `/fromcubes/<sub-path>` URL into a React page. Write JSX in the editor, deploy, open the URL — your component talks to the flow over WebSocket. No build step, no browser compiler. All portal pages are served under the hardcoded `/fromcubes/` prefix so every node cleanly coexists under one URL tree.
 
 For internals, plugin authoring, and the deploy pipeline see [README-DEV.md](./README-DEV.md).
 
 **💬 Questions, feedback, showcase?** Join the [fromcubes Discord](https://discord.gg/KYzsfKkYxX).
 
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L01UOFRG)
+**❤️ Support the project:** [![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Aaqu)
 
 ## Prerequisites
 
@@ -41,12 +40,17 @@ npm install @aaqu/fromcubes-react
 # restart Node-RED
 ```
 
-That's it. No build step. Any npm packages you list in the node config (e.g. `d3, three`) are installed automatically on deploy.
+That's it — this is the whole core: the nodes, deploy-time bundling, the WebSocket bridge and the React Editor. No build step. Any npm packages you list in the node config (e.g. `d3, three`) are installed automatically on deploy.
 
 ### Add-ons
 
-Three parts ship as their own packages, and for now installing the core
-installs them too:
+Everything else is an add-on you install only if you need it:
+
+```bash
+cd ~/.node-red
+npm install @aaqu/fromcubes-tailwind        # and/or -assets, -auth-headers
+# restart Node-RED
+```
 
 | Package | What it adds |
 |---|---|
@@ -54,10 +58,29 @@ installs them too:
 | [`@aaqu/fromcubes-auth-headers`](https://www.npmjs.com/package/@aaqu/fromcubes-auth-headers) | Users from `x-portal-user-*` headers set by a reverse proxy (Portal Auth) |
 | [`@aaqu/fromcubes-assets`](https://www.npmjs.com/package/@aaqu/fromcubes-assets) | Static files for portals, managed from a sidebar tab |
 
-Each is a Node-RED plugin built on the same API anyone can use — see
-[Plugins](#plugins-identity-providers-and-css-engines). Coming from
-`@aaqu/fromcubes-portal-react`? Uninstall it first, then install this
-package: both register the same nodes. Your flows keep working unchanged.
+Without an add-on its feature is simply off, and the editor says so once in
+the log: no Tailwind means portals get no generated stylesheet (style them
+with a `<link>`/`<style>` in **Head HTML**, or inline), no auth-headers means
+Portal Auth sees every session as anonymous, no assets means no sidebar and no
+`/fromcubes/public/`. Install an add-on later and it switches on by itself —
+**Menu → Settings → Fromcubes** shows what is in use.
+
+The shipped examples are styled with Tailwind; install
+`@aaqu/fromcubes-tailwind` to see them as intended.
+
+Each add-on is a Node-RED plugin built on the same API anyone can use — see
+[Plugins](#plugins-identity-providers-and-css-engines).
+
+**Coming from `@aaqu/fromcubes-portal-react`?** It contained all of the above.
+Uninstall it first (both register the same nodes), then install the core
+**and the add-ons you used** — for the same features as before:
+
+```bash
+npm uninstall @aaqu/fromcubes-portal-react
+npm install @aaqu/fromcubes-react @aaqu/fromcubes-tailwind @aaqu/fromcubes-assets @aaqu/fromcubes-auth-headers
+```
+
+Your flows keep working unchanged.
 
 ## Your first portal
 
@@ -401,6 +424,13 @@ behind a reverse proxy. Highlights:
   inbound identity headers before injecting verified ones, and Node-RED must
   not be reachable except through that proxy.
 
+## Support
+
+fromcubes is built and maintained by one person. If it saves you time,
+consider sponsoring its development:
+
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor_on-GitHub-ea4aaa?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Aaqu)
+
 ## License
 
 Apache-2.0

package/examples/PixiJS Sprites.json

@@ -29,8 +29,8 @@
         "id": "fc-pixi-comp-statusbar",
         "type": "fc-portal-component",
         "z": "fc-pixi-flow",
-        "compName": "StatusBar",
-        "compCode": "function StatusBar({ spriteCount, totalClicks, lastClicked }) {\n  return (\n    <div className=\"px-6 py-4 bg-zinc-900/50 border-t border-zinc-800/50 flex items-center gap-6 flex-wrap\">\n      <Stat label=\"Sprites\">\n        <span className=\"text-sm font-mono text-cyan-400\">{spriteCount}</span>\n      </Stat>\n      <Stat label=\"Total clicks\">\n        <span className=\"text-sm font-mono text-emerald-400\">{totalClicks}</span>\n      </Stat>\n      <Stat label=\"Last clicked\">\n        <span className=\"text-sm font-mono text-zinc-300\">{lastClicked || '\\u2014'}</span>\n      </Stat>\n    </div>\n  );\n}",
+        "compName": "PixiStatusBar",
+        "compCode": "function PixiStatusBar({ spriteCount, totalClicks, lastClicked }) {\n  return (\n    <div className=\"px-6 py-4 bg-zinc-900/50 border-t border-zinc-800/50 flex items-center gap-6 flex-wrap\">\n      <Stat label=\"Sprites\">\n        <span className=\"text-sm font-mono text-cyan-400\">{spriteCount}</span>\n      </Stat>\n      <Stat label=\"Total clicks\">\n        <span className=\"text-sm font-mono text-emerald-400\">{totalClicks}</span>\n      </Stat>\n      <Stat label=\"Last clicked\">\n        <span className=\"text-sm font-mono text-zinc-300\">{lastClicked || '\\u2014'}</span>\n      </Stat>\n    </div>\n  );\n}",
         "x": 360,
         "y": 300,
         "wires": []
@@ -91,7 +91,7 @@
                 "var": "PixiReact"
             }
         ],
-        "componentCode": "import { Sprite } from 'pixi.js';\nimport { Application, extend } from '@pixi/react';\nextend({ Sprite });\n\nfunction App() {\n  const { data, send } = useNodeRed();\n  const [sprites, setSprites] = useState([]);\n  const [totalClicks, setTotalClicks] = useState(0);\n  const [lastClicked, setLastClicked] = useState(null);\n  const idRef = useRef(0);\n\n  useEffect(() => {\n    if (!data) return;\n    setSprites(prev => {\n      const next = [...prev, {\n        id: idRef.current++,\n        x: 40 + Math.random() * 520,\n        y: 40 + Math.random() * 320,\n        tint: data.tint || 0x22d3ee\n      }];\n      return next.length > 12 ? next.slice(-12) : next;\n    });\n  }, [data]);\n\n  const handleClick = useCallback((info) => {\n    setTotalClicks(c => c + 1);\n    setLastClicked('#' + info.id);\n    send({\n      action: 'clicked',\n      spriteId: info.id,\n      x: Math.round(info.x),\n      y: Math.round(info.y),\n      spriteClicks: info.clicks,\n      timestamp: Date.now()\n    }, 'pixi/click');\n  }, [send]);\n\n  return (\n    <Page>\n      <Header title=\"fromcubes Pixi\" subtitle=\"click the bunnies\" />\n      <div className=\"flex-1 flex items-center justify-center p-6\">\n        <div className=\"rounded-xl overflow-hidden border border-zinc-800\">\n          <Application width={600} height={400} background={0x18181b} antialias>\n            {sprites.map(s => (\n              <ClickableSprite key={s.id} {...s} onClick={handleClick} />\n            ))}\n          </Application>\n        </div>\n      </div>\n      <StatusBar spriteCount={sprites.length} totalClicks={totalClicks} lastClicked={lastClicked} />\n    </Page>\n  );\n}",
+        "componentCode": "import { Sprite } from 'pixi.js';\nimport { Application, extend } from '@pixi/react';\nextend({ Sprite });\n\nfunction App() {\n  const { data, send } = useNodeRed();\n  const [sprites, setSprites] = useState([]);\n  const [totalClicks, setTotalClicks] = useState(0);\n  const [lastClicked, setLastClicked] = useState(null);\n  const idRef = useRef(0);\n\n  useEffect(() => {\n    if (!data) return;\n    setSprites(prev => {\n      const next = [...prev, {\n        id: idRef.current++,\n        x: 40 + Math.random() * 520,\n        y: 40 + Math.random() * 320,\n        tint: data.tint || 0x22d3ee\n      }];\n      return next.length > 12 ? next.slice(-12) : next;\n    });\n  }, [data]);\n\n  const handleClick = useCallback((info) => {\n    setTotalClicks(c => c + 1);\n    setLastClicked('#' + info.id);\n    send({\n      action: 'clicked',\n      spriteId: info.id,\n      x: Math.round(info.x),\n      y: Math.round(info.y),\n      spriteClicks: info.clicks,\n      timestamp: Date.now()\n    }, 'pixi/click');\n  }, [send]);\n\n  return (\n    <Page>\n      <Header title=\"fromcubes Pixi\" subtitle=\"click the bunnies\" />\n      <div className=\"flex-1 flex items-center justify-center p-6\">\n        <div className=\"rounded-xl overflow-hidden border border-zinc-800\">\n          <Application width={600} height={400} background={0x18181b} antialias>\n            {sprites.map(s => (\n              <ClickableSprite key={s.id} {...s} onClick={handleClick} />\n            ))}\n          </Application>\n        </div>\n      </div>\n      <PixiStatusBar spriteCount={sprites.length} totalClicks={totalClicks} lastClicked={lastClicked} />\n    </Page>\n  );\n}",
         "x": 560,
         "y": 160,
         "wires": [

package/examples/Three.js Scene.json

@@ -29,8 +29,8 @@
         "id": "fc-three-comp-statusbar",
         "type": "fc-portal-component",
         "z": "fc-three-flow",
-        "compName": "StatusBar",
-        "compCode": "function StatusBar({ leftColor, rightColor, clickCount }) {\n  return (\n    <div className=\"px-6 py-4 bg-zinc-900/50 border-t border-zinc-800/50 flex items-center gap-6 flex-wrap\">\n      <Stat label=\"Left box\">\n        <span className=\"w-4 h-4 rounded-full border border-zinc-700\" style={{ backgroundColor: leftColor }} />\n      </Stat>\n      <Stat label=\"Right box\">\n        <span className=\"w-4 h-4 rounded-full border border-zinc-700\" style={{ backgroundColor: rightColor }} />\n      </Stat>\n      <Stat label=\"Clicks\">\n        <span className=\"text-sm font-mono text-cyan-400\">{clickCount}</span>\n      </Stat>\n    </div>\n  );\n}",
+        "compName": "ThreeStatusBar",
+        "compCode": "function ThreeStatusBar({ leftColor, rightColor, clickCount }) {\n  return (\n    <div className=\"px-6 py-4 bg-zinc-900/50 border-t border-zinc-800/50 flex items-center gap-6 flex-wrap\">\n      <Stat label=\"Left box\">\n        <span className=\"w-4 h-4 rounded-full border border-zinc-700\" style={{ backgroundColor: leftColor }} />\n      </Stat>\n      <Stat label=\"Right box\">\n        <span className=\"w-4 h-4 rounded-full border border-zinc-700\" style={{ backgroundColor: rightColor }} />\n      </Stat>\n      <Stat label=\"Clicks\">\n        <span className=\"text-sm font-mono text-cyan-400\">{clickCount}</span>\n      </Stat>\n    </div>\n  );\n}",
         "x": 360,
         "y": 300,
         "wires": []
@@ -95,7 +95,7 @@
                 "var": "Drei"
             }
         ],
-        "componentCode": "import { Canvas } from '@react-three/fiber';\nimport { OrbitControls } from '@react-three/drei';\n\nfunction App() {\n  const { data, send } = useNodeRed();\n  const colors = data || { leftColor: 'orange', rightColor: 'cyan' };\n  const [clickCount, setClickCount] = useState(0);\n\n  const handleToggle = useCallback((clicked) => {\n    setClickCount(prev => prev + 1);\n    send({ action: clicked ? 'clicked' : 'unclicked', clicks: clickCount + 1 }, '3d/interact');\n  }, [send, clickCount]);\n\n  return (\n    <div className=\"h-screen bg-zinc-950 text-zinc-100 flex flex-col\">\n      <Header title=\"fromcubes 3D\" subtitle=\"React Three Fiber + live Node-RED data\" />\n      <div className=\"flex-1 overflow-hidden\">\n        <Canvas style={{ width: '100%', height: '100%' }}>\n          <ambientLight intensity={Math.PI / 2} />\n          <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} decay={0} intensity={Math.PI} />\n          <pointLight position={[-10, -10, -10]} decay={0} intensity={Math.PI} />\n          <Box position={[-1.2, 0, 0]} color={colors.leftColor} onToggle={handleToggle} />\n          <Box position={[1.2, 0, 0]} color={colors.rightColor} onToggle={handleToggle} />\n          <OrbitControls />\n        </Canvas>\n      </div>\n      <StatusBar leftColor={colors.leftColor} rightColor={colors.rightColor} clickCount={clickCount} />\n    </div>\n  );\n}",
+        "componentCode": "import { Canvas } from '@react-three/fiber';\nimport { OrbitControls } from '@react-three/drei';\n\nfunction App() {\n  const { data, send } = useNodeRed();\n  const colors = data || { leftColor: 'orange', rightColor: 'cyan' };\n  const [clickCount, setClickCount] = useState(0);\n\n  const handleToggle = useCallback((clicked) => {\n    setClickCount(prev => prev + 1);\n    send({ action: clicked ? 'clicked' : 'unclicked', clicks: clickCount + 1 }, '3d/interact');\n  }, [send, clickCount]);\n\n  return (\n    <div className=\"h-screen bg-zinc-950 text-zinc-100 flex flex-col\">\n      <Header title=\"fromcubes 3D\" subtitle=\"React Three Fiber + live Node-RED data\" />\n      <div className=\"flex-1 overflow-hidden\">\n        <Canvas style={{ width: '100%', height: '100%' }}>\n          <ambientLight intensity={Math.PI / 2} />\n          <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} decay={0} intensity={Math.PI} />\n          <pointLight position={[-10, -10, -10]} decay={0} intensity={Math.PI} />\n          <Box position={[-1.2, 0, 0]} color={colors.leftColor} onToggle={handleToggle} />\n          <Box position={[1.2, 0, 0]} color={colors.rightColor} onToggle={handleToggle} />\n          <OrbitControls />\n        </Canvas>\n      </div>\n      <ThreeStatusBar leftColor={colors.leftColor} rightColor={colors.rightColor} clickCount={clickCount} />\n    </div>\n  );\n}",
         "x": 560,
         "y": 160,
         "wires": [

package/nodes/editor/workspace.css

@@ -630,6 +630,13 @@ body.fc-ws-open #red-ui-notifications {
 /* ── Settings → Fromcubes (provider-settings.js) ─────────────────
    Lives in Node-RED's own Settings tray, not in the overlay, so it uses
    Node-RED's theme variables instead of the vs-dark palette above. */
+/* Same box as Node-RED's own View pane (#red-ui-settings-tab-view): fills
+   the content area, scrolls on its own, 20px side padding. */
+.fc-ps {
+  position: absolute; top: 0; right: 0; bottom: 0; left: 0;
+  padding: 8px 20px 20px;
+  overflow-y: auto;
+}
 .fc-ps .fc-ps-section { margin-bottom: 24px; }
 .fc-ps .fc-ps-hint { color: var(--red-ui-secondary-text-color); margin: 0 0 8px; }
 .fc-ps .fc-ps-note,

package/nodes/lib/providers.js

@@ -30,9 +30,13 @@
  *      — the administrator's word; the editor shows it locked.
  *   2. The choice made in the editor (Settings → Fromcubes), persisted in
  *      `<userDir>/fromcubes/providers.json`.
- *   3. The defaults, `headers` and `tailwind` — names, not code: when their
- *      add-on is not installed the default is simply missing (identity:
- *      anonymous; css: unstyled), exactly like any other missing provider.
+ *   3. The default: the official add-on when it is installed — `headers`
+ *      from @aaqu/fromcubes-auth-headers, `tailwind` from
+ *      @aaqu/fromcubes-tailwind — and `none` when it is not. The core works
+ *      on its own; installing the add-on is what turns the feature on. Only
+ *      the official package counts here: another package registering a
+ *      plugin called `headers` never becomes the default identity provider
+ *      (it can still be chosen explicitly, in 1 or 2).
  * Installing a plugin never switches anything on its own — for identity that
  * would let a package change who counts as logged in.
  *
@@ -50,6 +54,7 @@ const API_VERSION = 1;
 
 const DEFAULT_IDENTITY = "headers";
 const DEFAULT_CSS = "tailwind";
+const NONE = "none";
 
 // Bounds on what a provider may hand us. Generous enough that anything the
 // built-in header parser produces passes untouched (its groups header is
@@ -68,8 +73,18 @@ const MAX_EDITOR_CLASS_LEN = 200;
 const USER_STRING_FIELDS = ["login", "displayName", "email", "role"];
 
 const KINDS = {
-  identity: { type: IDENTITY_TYPE, setting: "identityProvider", fallback: DEFAULT_IDENTITY },
-  css: { type: CSS_TYPE, setting: "cssEngine", fallback: DEFAULT_CSS },
+  identity: {
+    type: IDENTITY_TYPE,
+    setting: "identityProvider",
+    fallback: DEFAULT_IDENTITY,
+    fallbackModule: "@aaqu/fromcubes-auth-headers",
+  },
+  css: {
+    type: CSS_TYPE,
+    setting: "cssEngine",
+    fallback: DEFAULT_CSS,
+    fallbackModule: "@aaqu/fromcubes-tailwind",
+  },
 };
 
 // Provider ids travel through the settings file, the admin API and the
@@ -261,7 +276,24 @@ function createProviders(RED, opts = {}) {
       return { id: fromSettings, source: "settings" };
     }
     if (chosen[kind]) return { id: chosen[kind], source: "editor" };
-    return { id: k.fallback, source: "default" };
+    const official = pluginsOf(k.type).some(
+      (p) => p.id === k.fallback && p.module === k.fallbackModule,
+    );
+    return { id: official ? k.fallback : NONE, source: "default", addonMissing: !official };
+  }
+
+  /**
+   * Log once, at info level, why a kind runs on `none` by default — so a
+   * core installed on its own explains itself instead of failing quietly.
+   * @param {string} kind
+   * @param {string} msg
+   * @returns {void}
+   */
+  function explainNone(kind, msg) {
+    const key = "none:" + kind;
+    if (logged.has(key)) return;
+    logged.add(key);
+    if (RED.log.info) RED.log.info("[portal-react] " + msg);
   }
 
   /**
@@ -428,7 +460,15 @@ function createProviders(RED, opts = {}) {
    * @returns {Promise<Object|null>}
    */
   async function resolveUser(req) {
-    const id = identityId();
+    const cur = current("identity");
+    const id = cur.id;
+    // Called only for portals with Portal Auth on — so this is someone who
+    // expects users and gets none.
+    if (cur.addonMissing) {
+      explainNone("identity", "Portal Auth is on but no identity provider is installed, so every " +
+        "session is anonymous. For users from x-portal-user-* headers install " +
+        "@aaqu/fromcubes-auth-headers, or choose a provider in Settings → Fromcubes.");
+    }
     const { provider, error } = lookup(IDENTITY_TYPE, builtins.identity, id);
     if (!provider) {
       logOnce(error + " — every session is anonymous");
@@ -466,7 +506,12 @@ function createProviders(RED, opts = {}) {
    * @returns {Promise<{css: string}>}
    */
   async function generateCss(source) {
-    const id = cssEngineId();
+    const cur = current("css");
+    const id = cur.id;
+    if (cur.addonMissing) {
+      explainNone("css", "No CSS engine is installed, so portals are served without a stylesheet. " +
+        "For Tailwind CSS install @aaqu/fromcubes-tailwind.");
+    }
     const { provider, error } = lookup(CSS_TYPE, builtins.css, id);
     if (!provider) throw new Error(error);
     if (typeof provider.generate !== "function") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaqu/fromcubes-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fromcubes React - React portals for Node-RED, built at deploy, with live WebSocket data binding",
   "type": "commonjs",
   "keywords": [
@@ -41,10 +41,7 @@
     "monaco-editor": "^0.56.0",
     "prettier": "^3.9.8",
     "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "@aaqu/fromcubes-assets": "^0.1.0",
-    "@aaqu/fromcubes-auth-headers": "^0.1.0",
-    "@aaqu/fromcubes-tailwind": "^0.1.0"
+    "react-dom": "^19.3.0"
   },
   "peerDependencies": {
     "ws": "^8.21.0"
@@ -64,8 +61,8 @@
   },
   "homepage": "https://aaqu.github.io/fromcubes-modules/",
   "funding": {
-    "type": "ko-fi",
-    "url": "https://ko-fi.com/L4L01UOFRG"
+    "type": "github",
+    "url": "https://github.com/sponsors/Aaqu"
   },
   "license": "Apache-2.0",
   "author": {