@zotezica/simple-front 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @zotezica/simple-front
+
+A minimal JS library for server-rendered apps with interactive islands.
+
+## Philosophy
+
+Modern full-stack frameworks (Next.js, SvelteKit, Remix) own everything — routing, data fetching, rendering — and couple your backend to their conventions. This is too much when you have a real backend (Hono, Express, Rails) that renders HTML and you just need a little client-side interactivity.
+
+The insight: **the only things you actually need from a framework are:**
+1. Smooth navigation between server-rendered pages (no full-page blink)
+2. A way to mount interactive components onto server-rendered DOM nodes
+
+That's it. Everything else stays on the server.
+
+**Core principles:**
+- Server renders all read-only data — no spinners, no client-side fetches for page content
+- Islands own only interactivity: forms, toggles, drawers
+- CSP `script-src 'self'` compliant — no inline event handlers, no eval
+- No opinions about your backend or build tool
+
+## Install
+
+```bash
+npm install @zotezica/simple-front
+```
+
+Svelte and React are optional peer dependencies — install whichever you use.
+
+## Usage
+
+```ts
+// Svelte
+import { island, start, slideDownFadeIn } from "@zotezica/simple-front/svelte";
+
+// React
+import { island, start, slideDownFadeIn } from "@zotezica/simple-front/react";
+```
+
+Register islands and call `start()`:
+
+```ts
+const animate = slideDownFadeIn();
+
+island("search-island", () => import("./islands/Search.svelte"), { animate });
+
+island("product-island", () => import("./islands/Product.svelte"), {
+  props: (el) => ({ productId: el.dataset.productId }),
+  animate,
+});
+
+start();
+```
+
+The server renders mount points as empty divs with `data-*` props:
+
+```html
+<div id="product-island" data-product-id="abc123"></div>
+```
+
+`simple-front` finds them by ID, reads props from `data-*` attributes, and mounts the component.
+
+## API
+
+### `island(id, importer, options?)`
+
+Registers an island.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `props` | `(el: HTMLElement) => Record<string, unknown>` | Reads props from the element before mounting |
+| `animate` | `IslandAnimation` | Animation to run when the island mounts |
+
+### `start()`
+
+Attaches the click interceptor, `popstate`, and `app:navigate` listeners, then mounts all registered islands found in the current DOM.
+
+### `navigate(url, options?)`
+
+Programmatically navigate to a URL. Options: `{ replace?: boolean }`.
+
+### `app:navigate` event
+
+Islands trigger navigation by dispatching a custom event — no need to import `navigate`:
+
+```ts
+window.dispatchEvent(new CustomEvent("app:navigate", {
+  detail: { url: "/products/abc123" }
+}));
+```
+
+## Animations
+
+Built-in animations, all accepting `{ duration?, easing? }`:
+
+```ts
+import { slideDown, fadeIn, slideDownFadeIn } from "@zotezica/simple-front/svelte";
+
+island("my-island", () => import("./My.svelte"), {
+  animate: slideDownFadeIn({ duration: 300 }),
+});
+```
+
+| Animation | Description |
+|-----------|-------------|
+| `slideDown()` | Animates height from 0 to natural height |
+| `fadeIn()` | Animates opacity from 0 to 1 |
+| `slideDownFadeIn()` | Slide, then fade |
+
+You can also pass any custom animation:
+
+```ts
+island("my-island", () => import("./My.svelte"), {
+  animate: {
+    prepare: (el) => { el.style.opacity = "0"; },
+    run: (el) => el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 300 }).finished,
+  },
+});
+```
+
+## Navigation
+
+`simple-front` intercepts same-origin link clicks, fetches the new page, diffs the DOM with morphdom, and updates the URL — no full-page reload. View Transitions API is used when available.
+
+The `X-Navigation: 1` header is sent on every fetch, letting the server skip the layout if it wants to return a partial response.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@zotezica/simple-front",
+  "version": "0.1.0",
+  "description": "Minimal JS library for server-rendered apps with interactive islands",
+  "type": "module",
+  "author": "Zica",
+  "license": "MIT",
+  "packageManager": "pnpm@10.29.3",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/core.ts",
+      "default": "./src/core.ts"
+    },
+    "./svelte": {
+      "types": "./src/svelte.ts",
+      "default": "./src/svelte.ts"
+    },
+    "./react": {
+      "types": "./src/react.ts",
+      "default": "./src/react.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "svelte": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "morphdom": "^2.7.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "svelte": "^5.55.8",
+    "typescript": "^5.8.3"
+  }
+}

package/src/animations.ts

@@ -0,0 +1,57 @@
+import type { IslandAnimation } from "./types.js";
+
+type AnimationOptions = {
+  duration?: number;
+  easing?: string;
+};
+
+export function slideDown({ duration = 300, easing = "ease" }: AnimationOptions = {}): IslandAnimation {
+  return {
+    run: (el) => {
+      el.style.height = "0px";
+      el.style.overflow = "hidden";
+
+      return new Promise((resolve) => {
+        requestAnimationFrame(() => {
+          const targetHeight = el.scrollHeight;
+          const anim = el.animate(
+            [{ height: "0px" }, { height: `${targetHeight}px` }],
+            { duration, easing },
+          );
+          anim.onfinish = () => {
+            el.style.height = "";
+            el.style.overflow = "";
+            resolve();
+          };
+        });
+      });
+    },
+  };
+}
+
+export function fadeIn({ duration = 300, easing = "ease-out" }: AnimationOptions = {}): IslandAnimation {
+  return {
+    prepare: (el) => { el.style.opacity = "0"; },
+    run: (el) => {
+      return new Promise((resolve) => {
+        requestAnimationFrame(() => {
+          const anim = el.animate([{ opacity: "0" }, { opacity: "1" }], { duration, easing });
+          anim.onfinish = () => {
+            el.style.opacity = "";
+            resolve();
+          };
+        });
+      });
+    },
+  };
+}
+
+export function slideDownFadeIn({ duration = 300, easing = "ease" }: AnimationOptions = {}): IslandAnimation {
+  return {
+    prepare: (el) => { el.style.opacity = "0"; },
+    run: async (el) => {
+      await slideDown({ duration, easing }).run(el);
+      await fadeIn({ duration: Math.round(duration * 0.6), easing: "ease-out" }).run(el);
+    },
+  };
+}

package/src/core.ts

@@ -0,0 +1,98 @@
+import morphdom from "morphdom";
+import type { AppConfig, IslandOptions, MountFn } from "./types.js";
+export { slideDown, fadeIn, slideDownFadeIn } from "./animations.js";
+export type { AnimateFn, PropsFactory, IslandAnimation, IslandOptions, MountFn, AppConfig, NavigateDetail } from "./types.js";
+
+type IslandEntry = {
+  importer: () => Promise<{ default: unknown }>;
+  options: IslandOptions;
+};
+
+const parser = new DOMParser();
+
+export function createApp(config: AppConfig) {
+  const registry = new Map<string, IslandEntry>();
+  const mounted = new WeakSet<Element>();
+
+  async function navigate(url: string, { replace = false }: { replace?: boolean } = {}): Promise<void> {
+    const res = await fetch(url, { headers: { "X-Navigation": "1" } });
+
+    if (!res.ok || res.redirected) {
+      location.assign(res.url || url);
+      return;
+    }
+
+    const html = await res.text();
+    const doc = parser.parseFromString(html, "text/html");
+
+    const transition = () => {
+      morphdom(document.body, doc.body, { childrenOnly: true });
+      document.title = doc.title;
+      if (replace) {
+        history.replaceState({}, "", url);
+      } else {
+        history.pushState({}, "", url);
+      }
+      mountIslands();
+    };
+
+    if (document.startViewTransition) {
+      document.startViewTransition(transition);
+    } else {
+      transition();
+    }
+  }
+
+  function mountIslands(): void {
+    for (const [id, entry] of registry) {
+      const el = document.getElementById(id);
+      if (!el) continue;
+      if (mounted.has(el)) continue;
+      mounted.add(el);
+      mountIsland(el, entry, config.mount);
+    }
+  }
+
+  function island(
+    id: string,
+    importer: () => Promise<{ default: unknown }>,
+    options: IslandOptions = {},
+  ): void {
+    registry.set(id, { importer, options });
+  }
+
+  function start(): void {
+    document.addEventListener("click", (e) => {
+      const a = (e.target as Element).closest("a[href]") as HTMLAnchorElement | null;
+      if (!a) return;
+      if (a.origin !== location.origin) return;
+      if (a.hasAttribute("download") || a.target === "_blank") return;
+      e.preventDefault();
+      if (a.href === location.href) return;
+      navigate(a.href);
+    });
+
+    window.addEventListener("popstate", () => navigate(location.href, { replace: true }));
+
+    window.addEventListener("app:navigate", (e) => {
+      const { url, replace } = (e as CustomEvent<{ url: string; replace?: boolean }>).detail;
+      navigate(url, { replace });
+    });
+
+    mountIslands();
+  }
+
+  return { island, start, navigate };
+}
+
+function mountIsland(el: HTMLElement, entry: IslandEntry, mountFn: MountFn): void {
+  const props = entry.options.props ? entry.options.props(el) : {};
+  const animate = entry.options.animate;
+
+  if (animate?.prepare) animate.prepare(el);
+
+  entry.importer().then(({ default: Component }) => {
+    mountFn(Component, el, props);
+    if (animate) animate.run(el);
+  });
+}

package/src/react.ts

@@ -0,0 +1,12 @@
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { createApp } from "./core.js";
+export { slideDown, fadeIn, slideDownFadeIn } from "./animations.js";
+export type { AnimateFn, PropsFactory, IslandAnimation, IslandOptions } from "./types.js";
+
+const { island, start, navigate } = createApp({
+  mount: (Component, target, props) =>
+    createRoot(target).render(createElement(Component as Parameters<typeof createElement>[0], props)),
+});
+
+export { island, start, navigate };

package/src/svelte.ts

@@ -0,0 +1,11 @@
+import { mount } from "svelte";
+import { createApp } from "./core.js";
+export { slideDown, fadeIn, slideDownFadeIn } from "./animations.js";
+export type { AnimateFn, PropsFactory, IslandAnimation, IslandOptions } from "./types.js";
+
+const { island, start, navigate } = createApp({
+  mount: (Component, target, props) =>
+    mount(Component as Parameters<typeof mount>[0], { target, props }),
+});
+
+export { island, start, navigate };

package/src/types.ts

@@ -0,0 +1,30 @@
+export type AnimateFn = (el: HTMLElement) => void | Promise<void>;
+
+export type PropsFactory<T extends Record<string, unknown> = Record<string, unknown>> = (
+  el: HTMLElement,
+) => T;
+
+export type IslandAnimation = {
+  prepare?: (el: HTMLElement) => void;
+  run: AnimateFn;
+};
+
+export type IslandOptions<T extends Record<string, unknown> = Record<string, unknown>> = {
+  props?: PropsFactory<T>;
+  animate?: IslandAnimation;
+};
+
+export type MountFn = (
+  Component: unknown,
+  target: HTMLElement,
+  props: Record<string, unknown>,
+) => void;
+
+export type AppConfig = {
+  mount: MountFn;
+};
+
+export type NavigateDetail = {
+  url: string;
+  replace?: boolean;
+};