@kolkrabbi/kol-framework 0.49.0 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Site shell and page layout",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,7 @@
   "module": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./vite": "./src/vite.js",
     "./src/*": "./src/*",
     "./kol-framework.css": "./kol-framework.css",
     "./kol-brand-color.css": "./kol-brand-color.css"
@@ -21,8 +22,8 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.239.0",
-    "@kolkrabbi/kol-icons": "^0.33.0"
+    "@kolkrabbi/kol-component": "^0.266.0",
+    "@kolkrabbi/kol-icons": "^0.39.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -17,6 +17,8 @@ export { useDragResize } from '@kolkrabbi/kol-component'
 export { default as ShellHeader, HEADER_ICON } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
 export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY, THEME_BOOT_SCRIPT } from './theme.js'
+/* the app loader's runtime half — the build half is `loaderApp()` in `@kolkrabbi/kol-framework/vite` */
+export { hideLoaderApp } from './loaderApp.js'
 export { default as Layout } from './Layout.jsx'
 export { default as PageSection } from './PageSection.jsx'
 export { default as PortalFooter } from './PortalFooter.jsx'

package/src/loaderApp.js

@@ -0,0 +1,14 @@
+/**
+ * hideLoaderApp — the app loader's other half (`loaderApp()` in `@kolkrabbi/kol-framework/vite` writes it into
+ * index.html). Call it once React has committed: two frames later the loader fades (240 ms, none under reduced
+ * motion — the CSS drops the transition) and leaves the DOM. Safe to call when there is no loader.
+ */
+export function hideLoaderApp() {
+  if (typeof document === 'undefined') return
+  const el = document.getElementById('kol-loader-app')
+  if (!el) return
+  requestAnimationFrame(() => requestAnimationFrame(() => {
+    el.classList.add('is-done')
+    setTimeout(() => { el.remove(); document.getElementById('kol-loader-app-css')?.remove() }, 300)
+  }))
+}

package/src/vite.js

@@ -0,0 +1,71 @@
+/**
+ * Vite plugins for KOL apps — Node-side, no React (import from `@kolkrabbi/kol-framework/vite` in vite.config).
+ *
+ * devFavicon — THE DEV TAB IS TELLABLE AT A GLANCE (2026-10-17 — user: "I need to be able to tell which tabs
+ * are localhost dev and which are production"). On the dev server the favicon becomes a solid tile with the
+ * app's letters; a build never sees it (`apply: 'serve'`). It REPLACES the page's icon link: fxr appended a
+ * second one and browsers pick their own (Firefox kept prod's), mirror swapped it at runtime after load.
+ * Each app picks its letters and ground once — the table lives in 16-app-anatomy.md § Dev favicon.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.label='DEV']   1–3 letters, fitted to the tile
+ * @param {string} [opts.ground='#7C5CFF']  the tile's colour — unique per app
+ * @param {string} [opts.ink='#FFFFFF']
+ */
+export function devFavicon({ label = 'DEV', ground = '#7C5CFF', ink = '#FFFFFF' } = {}) {
+  const text = String(label).slice(0, 3).toUpperCase()
+  const size = text.length === 1 ? 28 : text.length === 2 ? 20 : 15
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="${ground}"/>`
+    + `<text x="16" y="${(16 + size * 0.36).toFixed(1)}" text-anchor="middle" font-family="Arial Black, Arial, sans-serif" font-weight="900" font-size="${size}"`
+    + `${text.length > 1 ? ' textLength="28" lengthAdjust="spacingAndGlyphs"' : ''} fill="${ink}">${text}</text></svg>`
+  const link = `<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,${encodeURIComponent(svg)}">`
+  return {
+    name: 'kol-dev-favicon',
+    apply: 'serve',
+    transformIndexHtml(html) {
+      return /<link rel="icon"[^>]*>/.test(html) ? html.replace(/<link rel="icon"[^>]*>/, link) : html.replace('</head>', `${link}</head>`)
+    },
+  }
+}
+
+/**
+ * loaderApp — THE APP LOADER, OWNED ONCE (AppLoader, kol-monitor 2026-10-17 — user: *"shouldnt that loader just be
+ * owned in DS and consumed by the fxr monitor and mirror? with custom graphic input as prop?"*). The app's mark
+ * centred on the theme's ground, pulsing while the bundle downloads. It has to be static HTML in `index.html` —
+ * a React component would only appear after the wait it covers — so this plugin writes it there: fxr's loader,
+ * once, with the graphic as an option. Call `hideLoaderApp()` (kol-framework) after the first commit.
+ *
+ * Ground and ink follow the stored `data-theme`, else the system (run `THEME_BOOT_SCRIPT` before it, as every
+ * KOL app does). Reduced motion: no pulse, no fade.
+ *
+ * @param {Object} opts
+ * @param {string} opts.graphic   an SVG — the markup itself, or a path (relative to the app root) to an .svg file;
+ *                                draw it in `currentColor` so it takes the ground's ink
+ * @param {number} [opts.size=64] the mark's edge in px
+ */
+export function loaderApp({ graphic, size = 64 } = {}) {
+  let root = process.cwd()
+  const css = `#kol-loader-app{position:fixed;inset:0;z-index:2147483647;display:grid;place-items:center;background:#FAFAFA;color:#0E0E11;transition:opacity 240ms ease}`
+    + `@media (prefers-color-scheme: dark){:root:not([data-theme="light"]) #kol-loader-app{background:#121215;color:#FFFFFF}}`
+    + `:root[data-theme="dark"] #kol-loader-app{background:#121215;color:#FFFFFF}`
+    + `#kol-loader-app svg{width:${size}px;height:${size}px;animation:kol-loader-app-pulse 1.6s ease-in-out infinite}`
+    + `#kol-loader-app.is-done{opacity:0;pointer-events:none}`
+    + `@keyframes kol-loader-app-pulse{50%{opacity:.35}}`
+    + `@media (prefers-reduced-motion: reduce){#kol-loader-app svg{animation:none}#kol-loader-app{transition:none}}`
+  return {
+    name: 'kol-loader-app',
+    configResolved(config) { root = config.root },
+    async transformIndexHtml(html) {
+      let svg = String(graphic ?? '').trim()
+      if (svg && !svg.startsWith('<')) {
+        const { readFile } = await import('node:fs/promises')
+        const { resolve } = await import('node:path')
+        svg = (await readFile(resolve(root, svg), 'utf8')).trim()
+      }
+      svg = svg.replace(/<\?xml[^>]*>/, '').replace(/<!--[\s\S]*?-->/g, '')
+      return html
+        .replace('</head>', `<style id="kol-loader-app-css">${css}</style></head>`)
+        .replace(/<body([^>]*)>/, `<body$1><div id="kol-loader-app" aria-hidden="true">${svg}</div>`)
+    },
+  }
+}