@nimblebrain/synapse 0.8.0 → 0.10.0

package/README.md

@@ -43,10 +43,43 @@ npm install @nimblebrain/synapse
 |-------------|-------------|
 | `@nimblebrain/synapse` | Vanilla JS core — `connect()`, `createSynapse()`, `createStore()` |
 | `@nimblebrain/synapse/react` | React hooks and providers (`AppProvider`, `SynapseProvider`) |
+| `@nimblebrain/synapse/ui` | Component library — tokens, primitives, components, layouts |
+| `@nimblebrain/synapse/ui/fonts` | Side-effect import that loads the brand fonts into the iframe |
 | `@nimblebrain/synapse/vite` | Vite plugin for dev mode |
 | `@nimblebrain/synapse/codegen` | CLI + programmatic code generation |
 | `@nimblebrain/synapse/iife` | Pre-built IIFE bundle for `<script>` tags (`window.Synapse`) |
 
+## UI Components (`@nimblebrain/synapse/ui`)
+
+A React component library for embedded Synapse apps: a token contract, layout
+primitives (`Stack`, `Inline`, …), components (`Card`, `Badge`, `Drawer`,
+`Table`, `ListRow`, …), and responsive layout scaffolds (`AppFrame`,
+`SidebarLayout`, `ListDetailLayout`). The `gallery/` app is a living reference —
+every token and component in light/dark across several themes.
+
+### Design principles
+
+These are the durable decisions behind the library; they rarely change.
+
+- **The library holds no brand.** Tokens are `var(--token, neutral-fallback)`
+  references, not hex values. The host injects the real palette/fonts at runtime
+  (the MCP ext-apps `hostContext.styles.variables`), so the same app adopts
+  whatever host it runs in. Standalone, it renders in neutral fallbacks.
+- **Theme via CSS, not React.** Components style with token-driven inline-style
+  objects whose values are those `var()` refs, so theming — including light/dark —
+  resolves in CSS with no re-render. `ensureStyle` injects keyframes and
+  pseudo-state rules once; brand values never get baked in.
+- **Scaffold only genuinely-complex layouts.** `AppFrame`, `SidebarLayout`, and
+  `ListDetailLayout` exist because they encapsulate real responsive/stateful
+  complexity. Boards, grids, and simple lists are primitives + recipes, not
+  components — the library codifies the shapes apps actually take, not a general
+  layout engine.
+- **Responsive to the pane, not the device.** Layouts observe their own width
+  (`ResizeObserver` via `useBreakpoint`), because an app's iframe may be
+  fullscreen, split, or a narrow rail regardless of screen size.
+- **Lean on the platform.** `Drawer` is built on the native `<dialog>` element
+  (focus-trap, Escape, scroll behavior for free) rather than re-implementing them.
+
 ## Quick Start
 
 ### Vanilla JS

package/dist/codegen/index.cjs

@@ -1,10 +1,14 @@
 'use strict';
 
-var chunk42N5BB5O_cjs = require('../chunk-42N5BB5O.cjs');
 var chunkHLT5UBJF_cjs = require('../chunk-HLT5UBJF.cjs');
+var chunk42N5BB5O_cjs = require('../chunk-42N5BB5O.cjs');
 
 
 
+Object.defineProperty(exports, "generateTypes", {
+  enumerable: true,
+  get: function () { return chunkHLT5UBJF_cjs.generateTypes; }
+});
 Object.defineProperty(exports, "readFromManifest", {
   enumerable: true,
   get: function () { return chunk42N5BB5O_cjs.readFromManifest; }
@@ -17,9 +21,5 @@ Object.defineProperty(exports, "readFromServer", {
   enumerable: true,
   get: function () { return chunk42N5BB5O_cjs.readFromServer; }
 });
-Object.defineProperty(exports, "generateTypes", {
-  enumerable: true,
-  get: function () { return chunkHLT5UBJF_cjs.generateTypes; }
-});
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/codegen/index.js

@@ -1,4 +1,4 @@
-export { readFromManifest, readFromSchemaDir, readFromServer } from '../chunk-YWX3D24J.js';
 export { generateTypes } from '../chunk-JKHGWDZI.js';
+export { readFromManifest, readFromSchemaDir, readFromServer } from '../chunk-YWX3D24J.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/ui/fonts.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+// src/ui/fonts.ts
+var FONTSHARE_HREF = "https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&f[]=erode@400,500&display=swap";
+var LINK_ID = "nb-synapse-fonts";
+function injectFonts() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(LINK_ID)) return;
+  const link = document.createElement("link");
+  link.id = LINK_ID;
+  link.rel = "stylesheet";
+  link.href = FONTSHARE_HREF;
+  document.head.appendChild(link);
+}
+injectFonts();
+
+exports.injectFonts = injectFonts;
+//# sourceMappingURL=fonts.cjs.map
+//# sourceMappingURL=fonts.cjs.map

package/dist/ui/fonts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/fonts.ts"],"names":[],"mappings":";;;AAuBA,IAAM,cAAA,GACJ,yFAAA;AACF,IAAM,OAAA,GAAU,kBAAA;AAOT,SAAS,WAAA,GAAoB;AAClC,EAAA,IAAI,OAAO,aAAa,WAAA,EAAa;AACrC,EAAA,IAAI,QAAA,CAAS,cAAA,CAAe,OAAO,CAAA,EAAG;AACtC,EAAA,MAAM,IAAA,GAAO,QAAA,CAAS,aAAA,CAAc,MAAM,CAAA;AAC1C,EAAA,IAAA,CAAK,EAAA,GAAK,OAAA;AACV,EAAA,IAAA,CAAK,GAAA,GAAM,YAAA;AACX,EAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,EAAA,QAAA,CAAS,IAAA,CAAK,YAAY,IAAI,CAAA;AAChC;AAEA,WAAA,EAAY","file":"fonts.cjs","sourcesContent":["/**\n * Loads the NimbleBrain brand fonts into the current document. Import for the\n * side effect:\n *\n * ```ts\n * import \"@nimblebrain/synapse/ui/fonts\";\n * ```\n *\n * The token contract names these fonts (`--font-sans: Satoshi`,\n * `--nb-font-heading: Erode`), but a font *name* only renders if the font\n * *files* are loaded in the iframe document — each app iframe is its own\n * document and does not inherit the host's `@font-face`s. This module injects\n * the Fontshare stylesheet so the named fonts resolve instead of silently\n * falling back.\n *\n * JetBrains Mono (`--font-mono`) is not injected here — apps that render code\n * should add `@fontsource-variable/jetbrains-mono` to their own bundle.\n *\n * CSP note: the host iframe must allow `https://api.fontshare.com` in its\n * `style-src`/`font-src` for this to take effect. If blocked, fonts fall back\n * to the neutral system stack in the token contract.\n */\n\nconst FONTSHARE_HREF =\n  \"https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&f[]=erode@400,500&display=swap\";\nconst LINK_ID = \"nb-synapse-fonts\";\n\n/**\n * Inject the Fontshare brand-font stylesheet once. Idempotent and SSR-safe\n * (no-ops when `document` is unavailable). Called automatically on import;\n * exported for explicit invocation.\n */\nexport function injectFonts(): void {\n  if (typeof document === \"undefined\") return;\n  if (document.getElementById(LINK_ID)) return;\n  const link = document.createElement(\"link\");\n  link.id = LINK_ID;\n  link.rel = \"stylesheet\";\n  link.href = FONTSHARE_HREF;\n  document.head.appendChild(link);\n}\n\ninjectFonts();\n"]}

package/dist/ui/fonts.d.cts

@@ -0,0 +1,30 @@
+/**
+ * Loads the NimbleBrain brand fonts into the current document. Import for the
+ * side effect:
+ *
+ * ```ts
+ * import "@nimblebrain/synapse/ui/fonts";
+ * ```
+ *
+ * The token contract names these fonts (`--font-sans: Satoshi`,
+ * `--nb-font-heading: Erode`), but a font *name* only renders if the font
+ * *files* are loaded in the iframe document — each app iframe is its own
+ * document and does not inherit the host's `@font-face`s. This module injects
+ * the Fontshare stylesheet so the named fonts resolve instead of silently
+ * falling back.
+ *
+ * JetBrains Mono (`--font-mono`) is not injected here — apps that render code
+ * should add `@fontsource-variable/jetbrains-mono` to their own bundle.
+ *
+ * CSP note: the host iframe must allow `https://api.fontshare.com` in its
+ * `style-src`/`font-src` for this to take effect. If blocked, fonts fall back
+ * to the neutral system stack in the token contract.
+ */
+/**
+ * Inject the Fontshare brand-font stylesheet once. Idempotent and SSR-safe
+ * (no-ops when `document` is unavailable). Called automatically on import;
+ * exported for explicit invocation.
+ */
+declare function injectFonts(): void;
+
+export { injectFonts };

package/dist/ui/fonts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Loads the NimbleBrain brand fonts into the current document. Import for the
+ * side effect:
+ *
+ * ```ts
+ * import "@nimblebrain/synapse/ui/fonts";
+ * ```
+ *
+ * The token contract names these fonts (`--font-sans: Satoshi`,
+ * `--nb-font-heading: Erode`), but a font *name* only renders if the font
+ * *files* are loaded in the iframe document — each app iframe is its own
+ * document and does not inherit the host's `@font-face`s. This module injects
+ * the Fontshare stylesheet so the named fonts resolve instead of silently
+ * falling back.
+ *
+ * JetBrains Mono (`--font-mono`) is not injected here — apps that render code
+ * should add `@fontsource-variable/jetbrains-mono` to their own bundle.
+ *
+ * CSP note: the host iframe must allow `https://api.fontshare.com` in its
+ * `style-src`/`font-src` for this to take effect. If blocked, fonts fall back
+ * to the neutral system stack in the token contract.
+ */
+/**
+ * Inject the Fontshare brand-font stylesheet once. Idempotent and SSR-safe
+ * (no-ops when `document` is unavailable). Called automatically on import;
+ * exported for explicit invocation.
+ */
+declare function injectFonts(): void;
+
+export { injectFonts };

package/dist/ui/fonts.js

@@ -0,0 +1,17 @@
+// src/ui/fonts.ts
+var FONTSHARE_HREF = "https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&f[]=erode@400,500&display=swap";
+var LINK_ID = "nb-synapse-fonts";
+function injectFonts() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(LINK_ID)) return;
+  const link = document.createElement("link");
+  link.id = LINK_ID;
+  link.rel = "stylesheet";
+  link.href = FONTSHARE_HREF;
+  document.head.appendChild(link);
+}
+injectFonts();
+
+export { injectFonts };
+//# sourceMappingURL=fonts.js.map
+//# sourceMappingURL=fonts.js.map

package/dist/ui/fonts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/fonts.ts"],"names":[],"mappings":";AAuBA,IAAM,cAAA,GACJ,yFAAA;AACF,IAAM,OAAA,GAAU,kBAAA;AAOT,SAAS,WAAA,GAAoB;AAClC,EAAA,IAAI,OAAO,aAAa,WAAA,EAAa;AACrC,EAAA,IAAI,QAAA,CAAS,cAAA,CAAe,OAAO,CAAA,EAAG;AACtC,EAAA,MAAM,IAAA,GAAO,QAAA,CAAS,aAAA,CAAc,MAAM,CAAA;AAC1C,EAAA,IAAA,CAAK,EAAA,GAAK,OAAA;AACV,EAAA,IAAA,CAAK,GAAA,GAAM,YAAA;AACX,EAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,EAAA,QAAA,CAAS,IAAA,CAAK,YAAY,IAAI,CAAA;AAChC;AAEA,WAAA,EAAY","file":"fonts.js","sourcesContent":["/**\n * Loads the NimbleBrain brand fonts into the current document. Import for the\n * side effect:\n *\n * ```ts\n * import \"@nimblebrain/synapse/ui/fonts\";\n * ```\n *\n * The token contract names these fonts (`--font-sans: Satoshi`,\n * `--nb-font-heading: Erode`), but a font *name* only renders if the font\n * *files* are loaded in the iframe document — each app iframe is its own\n * document and does not inherit the host's `@font-face`s. This module injects\n * the Fontshare stylesheet so the named fonts resolve instead of silently\n * falling back.\n *\n * JetBrains Mono (`--font-mono`) is not injected here — apps that render code\n * should add `@fontsource-variable/jetbrains-mono` to their own bundle.\n *\n * CSP note: the host iframe must allow `https://api.fontshare.com` in its\n * `style-src`/`font-src` for this to take effect. If blocked, fonts fall back\n * to the neutral system stack in the token contract.\n */\n\nconst FONTSHARE_HREF =\n  \"https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&f[]=erode@400,500&display=swap\";\nconst LINK_ID = \"nb-synapse-fonts\";\n\n/**\n * Inject the Fontshare brand-font stylesheet once. Idempotent and SSR-safe\n * (no-ops when `document` is unavailable). Called automatically on import;\n * exported for explicit invocation.\n */\nexport function injectFonts(): void {\n  if (typeof document === \"undefined\") return;\n  if (document.getElementById(LINK_ID)) return;\n  const link = document.createElement(\"link\");\n  link.id = LINK_ID;\n  link.rel = \"stylesheet\";\n  link.href = FONTSHARE_HREF;\n  document.head.appendChild(link);\n}\n\ninjectFonts();\n"]}