surf-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berkan Çetinkaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# SURF [![Build Status](https://ci.berkan.cc/api/badges/2/status.svg)](https://ci.berkan.cc/repos/2)
+
+HTML-first, server-driven UI framework with local client-side state.
+
+> **Mental Model**: "Surface changes, Cell lives."
+
+## Philosophy
+
+- **Server is the source of truth** — All data and validation lives on the server
+- **Client handles local motion** — Only temporary, interactive state on the client
+- **HTML is the data format** — UI changes through HTML patches, not JSON APIs
+- **No build step required** — Works directly in the browser, no transpilation needed
+- **Progressive enhancement** — Works without JS, enhanced with JS
+
+## Non-Goals
+
+- ❌ Global client-side store
+- ❌ Virtual DOM
+- ❌ Mandatory JSON APIs
+- ❌ Hidden magic or implicit behavior
+
+## Installation
+
+```html
+<script src="https://unpkg.com/surf@latest/dist/surf.min.js"></script>
+```
+
+Or install via npm:
+
+```bash
+npm install surf
+```
+
+## Core Concepts
+
+### Surface
+
+A Surface is a DOM region that can be replaced by server responses.
+
+```html
+<main id="main" d-surface>
+  <!-- Content that can be replaced -->
+</main>
+```
+
+### Cell
+
+A Cell is a local, client-side state container. Cells survive Surface updates.
+
+```html
+<div d-cell="{ count: 0 }">
+  <span d-text="count"></span>
+  <button d-signal="click: count = count + 1">+</button>
+</div>
+```
+
+### Signal
+
+Signals define reactive behavior inside a Cell.
+
+| `d-signal` | Event handler | `d-signal="click: open = true"` |
+| `d-text` | Text binding | `d-text="count"` |
+| `d-show` | Conditional display | `d-show="open"` |
+| `d-attr` | Attribute binding | `d-attr="disabled: loading"` |
+| `d-attr` | Class toggling | `d-attr="class.active: isActive"` |
+
+### Signal Features
+
+**Form Resetting:**
+Use the `reset` keyword to clear forms declaratively. Surf automatically ensures this happens *after* submission data is captured.
+
+```html
+<form d-pulse="commit" d-signal="submit: reset">
+  <input name="msg">
+</form>
+```
+
+**Native Methods (`this.method()`):**
+Call native DOM methods on the element triggering the signal.
+
+```html
+<input type="text" d-signal="focus: this.select()">
+<video d-signal="mouseenter: this.play()"></video>
+```
+
+### Plugins
+
+Surf supports a lightweight plugin system.
+
+```javascript
+import Surf from './surf.js';
+import DragAndDrop from './plugins/drag-and-drop.js';
+
+Surf.use(DragAndDrop);
+```
+
+**Drag & Drop Plugin:**
+Enable drag-and-drop reordering with simple attributes.
+
+```html
+<div d-drag-zone="group-name" d-drag-url="/api/move">
+  <div d-drag-handle>...</div>
+</div>
+```
+
+### Pulse
+
+A Pulse triggers server interaction.
+
+```html
+<!-- Navigation (GET) -->
+<a href="/page" d-pulse="navigate" d-target="#main">Go to Page</a>
+
+<!-- Action (POST) -->
+<!-- Sends Cell state + data attributes -->
+<button d-pulse="action" d-action="/api/like" data-id="123">Like</button>
+
+<!-- Form submission (POST) -->
+<form d-pulse="commit" d-target="#form">
+  <input name="email" required>
+  <button type="submit">Submit</button>
+</form>
+
+<!-- Refresh content -->
+<button d-pulse="refresh" d-target="#main">Refresh</button>
+```
+
+### Auto-Refresh
+
+Surfaces can automatically poll the server for updates.
+
+```html
+<div d-surface d-auto-refresh="5000" d-auto-refresh-url="/api/news">
+  <!-- Content updates every 5 seconds -->
+</div>
+```
+
+### Patch
+
+Server returns HTML patches to update Surfaces.
+
+```html
+<d-patch>
+  <surface target="#main">
+    <h1>Updated Content</h1>
+  </surface>
+  <surface target="#toast">
+    <div class="toast">Saved!</div>
+  </surface>
+</d-patch>
+```
+
+## JavaScript API
+
+```javascript
+// Navigate to URL
+Surf.go('/page', { target: '#main' });
+
+// Refresh a surface
+Surf.refresh('#main');
+
+// Listen to events
+Surf.on('before:pulse', (e) => console.log('Loading...'));
+Surf.on('after:patch', (e) => console.log('Done!'));
+Surf.on('error:network', (e) => console.error(e.error));
+
+// Manual state access
+Surf.getState('#my-cell');
+Surf.setState('#my-cell', { count: 5 });
+```
+
+## Echo Rule
+
+> "Surface changes, Cell lives."
+
+When a Surface is patched, Cell states are preserved. If a Cell with the same `id` or `d-cell-id` exists in the new content, its state is restored automatically.
+
+```html
+<!-- Before patch: count = 5 -->
+<div id="counter" d-cell="{ count: 0 }">
+  <span d-text="count">5</span>
+</div>
+
+<!-- After patch: count still = 5 (preserved by Echo) -->
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Serve examples
+npm run serve
+```
+
+## License
+
+MIT

package/dist/plugins/debounce.js

@@ -0,0 +1,2 @@
+var SurfDebounce=(()=>{var i=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var f=(n,t)=>{for(var o in t)i(n,o,{get:t[o],enumerable:!0})},A=(n,t,o,e)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of b(t))!h.call(n,r)&&r!==o&&i(n,r,{get:()=>t[r],enumerable:!(e=p(t,r))||e.enumerable});return n};var $=n=>A(i({},"__esModule",{value:!0}),n);var I={};f(I,{default:()=>v});var v={install(n){let t=new WeakMap;document.addEventListener("input",o=>{let e=o.target;if(!e.hasAttribute("d-input"))return;let r=e.getAttribute("d-input"),u=parseInt(e.getAttribute("d-debounce")||"300",10),a=e.getAttribute("d-target"),c=parseInt(e.getAttribute("d-min-length")||"3",10),s=e.value.trim();t.has(e)&&clearTimeout(t.get(e));let l=setTimeout(()=>{if(s.length>0&&s.length<c)return;let g=r.includes("?")?"&":"?",d=e.name||"q",m=`${r}${g}${d}=${encodeURIComponent(s)}`;n.go(m,{target:a})},u);t.set(e,l)}),console.log("[Surf] Debounce Plugin installed")}};return $(I);})();
+window.SurfDebounce=SurfDebounce.default

package/dist/plugins/drag-and-drop.js

@@ -0,0 +1,2 @@
+var SurfDragAndDrop=(()=>{var u=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var D=Object.prototype.hasOwnProperty;var h=(a,o)=>{for(var n in o)u(a,n,{get:o[n],enumerable:!0})},L=(a,o,n,c)=>{if(o&&typeof o=="object"||typeof o=="function")for(let s of m(o))!D.call(a,s)&&s!==n&&u(a,s,{get:()=>o[s],enumerable:!(c=b(o,s))||c.enumerable});return a};var y=a=>L(u({},"__esModule",{value:!0}),a);var E={};h(E,{default:()=>A});var w={name:"drag-and-drop",install(a,o={}){let n=null,c=(t=document)=>{t.querySelectorAll('[d-draggable="true"]').forEach(e=>{e.setAttribute("draggable","true")})};c(),new MutationObserver(t=>{t.forEach(e=>{e.addedNodes.forEach(r=>{r.nodeType===1&&(r.hasAttribute("d-draggable")&&r.setAttribute("draggable","true"),c(r))})})}).observe(document.body,{childList:!0,subtree:!0}),document.addEventListener("dragstart",t=>{if(t.target.closest("[d-no-drag]")){t.preventDefault();return}if(!t.target.closest('[d-draggable="true"]'))return;let e=t.target.closest('[d-draggable="true"]');n=e;let r=e.getAttribute("d-drag-data");r&&t.dataTransfer.setData("text/plain",r),t.dataTransfer.effectAllowed="move",e.classList.add("dragging")}),document.addEventListener("dragend",t=>{n&&(n.classList.remove("dragging"),n=null),document.querySelectorAll(".drag-over").forEach(e=>{e.classList.remove("drag-over")})}),document.addEventListener("dragover",t=>{let e=t.target.closest("[d-drop-zone]");e&&(t.preventDefault(),t.dataTransfer.dropEffect="move",e.classList.add("drag-over"))}),document.addEventListener("dragleave",t=>{let e=t.target.closest("[d-drop-zone]");if(!e)return;let r=e.getBoundingClientRect(),d=t.clientX,l=t.clientY;(d<r.left||d>=r.right||l<r.top||l>=r.bottom)&&e.classList.remove("drag-over")}),document.addEventListener("drop",async t=>{let e=t.target.closest("[d-drop-zone]");if(!e)return;t.preventDefault(),e.classList.remove("drag-over");let r=e.getAttribute("d-drop-url");if(r)try{let d=t.dataTransfer.getData("text/plain");if(!d)return;let l=JSON.parse(d),f=e.getAttribute("d-drop-data");if(f){let i=JSON.parse(f);Object.assign(l,i)}let p=new URLSearchParams;for(let[i,v]of Object.entries(l))p.append(i,v);let g=await fetch(r,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:p});if(g.ok){let i=await g.text();a&&a.applyPatch&&a.applyPatch(i)}else console.error("[Surf DnD] Drop request failed",g.status)}catch(d){console.error("[Surf DnD] Drop error",d)}}),console.log("[Surf] Drag & Drop plugin installed")}},A=w;return y(E);})();
+window.SurfDragAndDrop=SurfDragAndDrop.default