@wrnrlr/prelude 0.0.1 → 0.1.3

package/.github/workflows/publish.yml

@@ -5,12 +5,53 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   publish:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write # The OIDC ID token is used for authentication with JSR.
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
-      - run: npx jsr publish
+      - name: Check out the repository to the runner
+        uses: actions/checkout@v4
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Deno install
+        run: deno install
+
+      # - name: Lint
+      #   run: deno lint
+
+      - name: Run tests
+        run: deno task test
+
+      - name: Build
+        run: deno task build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './www/dist'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      # - name: Setup NPM
+      #   run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /home/runner/.npmrc
+      #   env:
+      #     NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      # - name: Run release script
+      #   run: /home/runner/.deno/bin/deno task release

package/deno.json

@@ -1,23 +1,32 @@
 {
   "name": "@wrnrlr/prelude",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "exports": "./src/mod.ts",
   "compilerOptions": {
-    "strict": true,
+    "strict": false,
     "checkJs": false,
     "noImplicitThis": false,
-    "lib": ["dom","dom.iterable","dom.asynciterable","deno.ns"]
+    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
   },
   "imports": {
     "@std/assert": "jsr:@std/assert@^1.0.0",
+    "@std/fs": "jsr:@std/fs@^1.0.5",
+    "@std/path": "jsr:@std/path@^1.0.6",
     "@std/testing": "jsr:@std/testing@^0.225.3",
-    "typedoc": "npm:typedoc",
-    "vite": "npm:vite@^5.4.2",
-    "typedoc-plugin-markdown": "npm:typedoc-plugin-markdown"
+    "jsdom": "npm:jsdom",
+    "typedoc": "npm:typedoc@^0.26.6",
+    "vite": "npm:vite@^5.4.9",
+    "esbuild": "npm:esbuild@^0.24.0"
   },
   "tasks": {
-    "dev": "deno run -A npm:vite@^5.4.2",
-    "test": "deno test -A --unstable-sloppy-imports ./test/*.[jt]s",
-    "docs": "deno run -A npm:typedoc "
+    "dev": "deno run -A npm:vite --config www/vite.config.js",
+    "test": "deno test -A ./test/*.[jt]s",
+    "docs": "deno run -A npm:typedoc --options www/typedoc.json",
+    "build": "deno run -A npm:vite build --mode production --config www/vite.config.js",
+    "release": "deno publish --allow-slow-types --allow-dirty && npm publish --access public",
+    "clean": "rm -rf dist/ www/dist www/docs"
+  },
+  "lint": {
+    "include": ["src"]
   }
 }

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "@wrnrlr/prelude",
-  "version": "0.0.1",
+  "type": "module",
+  "version": "0.1.3",
   "author": "Werner Laurensse",
   "description": "A signal based frontend library with fine-grained reactivity",
   "main": "./src/mod.ts",
-  "directories": {
-    "example": "example",
-    "test": "test"
-  },
-  "scripts": {}
+  "scripts": {},
+  "dependencies": { "@codemirror/lang-html": "^6.4.9", "codemirror": "^6.0.1" }
 }

package/readme.md

@@ -1,86 +1,208 @@
-# PreludeJS
+# Prelude
+[Home](https://wrnrlr.github.io/prelude/) [NPM](https://www.npmjs.com/package/@wrnrlr/prelude) [JSR](https://jsr.io/@wrnrlr/prelude)
+
+Prelude lets you develop web applications in a familiar component-based functional style.
+It is build with the desire to have a lightweight frontend framework that works
+using just JavaScript but that nontheless can handle complex web applications without
+sacrificing on developer expierence.
 
 ## Get Started
 
-Run directly in the browser using ESM
-   ```js
+Prelude works with most popular JavaScript runtimes: Node, Deno, Bun or the borwser.
+It is available on NPM and JSR under the package named `@wrnrlr/prelude`.
+
+The quickest way to get started with Prelude is uing the [Playground](https://wrnrlr.github.io/prelude/playground) app on the homepage.
+It offers a IDE complete with a code editor, live preview and a number of examples.
+Aternativaly you can develop on your local machine using `vite`.
+
+Some Prelude APIs can also be used in the REPL to expore their behaviour interactively.
+
+## Basic Example
+
+This is a example of a button that increments a counter when it is clicked.
+
+```html
+<!DOCTYPE html>
+<title>Counter</title>
+
+<script type="module">
   import {h, signal, render} from 'https://esm.sh/@wrnrlr/prelude'
-  ```
 
-Install from NPM to run with Node or Bun
-   ```js
-  import {h, signal, render} from 'wrnrlr/prelude'
-  ```
+  function Counter() {
+    const n = signal(1)
+    return h('button', {onClick: e => n(n=>n+1)}, n)
+  }
+
+  render(Counter, document.body)
+</script>
+```
+
+## Hyperscript
 
-Use Deno's JSR
-   ```js
-  import {h, signal, render} from 'jsr:wrnrlr/prelude'
-  ```
+Prelude does not use JSX or a templating language to descript html instead we use a DSL called HyperScript.
 
-A simple js frontend library
+The `h` function is used in either of two ways based on the type of the first argument,
+when it is a string it will create a html element like ,
+and when it is a function it will create a reactive component.
 
 ```js
-import {h,signal,render} from 'https://jsr.org/wrnrlr/prelude.ts'
+h('div',{},[
+  h('label','Name'),h('input',{})
+])
+```
 
-function Counter() {
-  const n = signal(1)
-  return [n,h('button',{onclick(e){n(n=>n+1)}},'+')]
-}
+### Event Handler
+
+Prelude tries to integrate with the existing web APIs as much as possible, handeling user events is no different,
+use a function to the event callback.
 
-render(Counter, document.body)
+In the following example we listen for `onclick` events for a button, and increment the value of the `n` signal.
+
+```js
+h('button', {onClick:e => n(i => i + 1)}, n)
 ```
 
-## Signals
+Be adviced, the event handler MUST always have one argument even if this is not being used, lest HyperScript confuses it for a signal
+and ignores the events.
 
 ```js
-const a = signal(1)
-const b = signal(2)
+// Ok
+h('button', {onClick: e => console.log('Ok')})
+h('button', {onClick: _ => console.log('Ok')})
+// This event handler will be ignored
+h('button', {onClick: () => console.log('Wrong')})
+```
+
+## Reactivity
+
+### Signals
+
+A signal is an object that holds a value with a setter to update this value and a getter that returns this value whenever it is updated.
+
+Create signal.
+```js
+// Create a signal with value one
+const n = signal(1)
+
+// Get value from signal
+n()
+
+// Set value for signal
+n(2)
+
+// Set value with an update function
+n(i=>i+1)
+
+// Derived signal
+const n2 = () => n() * 2
+```
+
+### Effects
+
+The `effect` function lets you subscribe to signals and perform side-effects whenever the signal chages.
+
+```js
+const a = signal(1), b = signal(2)
 effect(() => console.log('a+b', a()+b()))
 const c = () => a()+b()
 effect(() => console.log('c', c()))
 a(i => i+1)
 ```
 
-## Hyperscript
+### Memo
 
-The `h` function allows one to write html in javascript with a DSL specifically designed
+The `memo` function caches the result of the function passed to it.
 
 ```js
-h('div',{},[
-  h('label','Name'),h('input',{})
-])
+const n2 = memo(() => n() * 2)
 ```
 
-## Event Handler
+### Untrack
 
-An event handler MUST have an argument even if this is not being used,
-otherwise hyperscript will confuse it for a signal.
+## Conditional Rendering
 
 ```js
-// Ok
-h('button', {onClick: e => console.log('Ok')}, 'Hi')
-h('button', {onClick: _ => console.log('Ok')}, 'Hi')
-// This event handler will be ignored
-h('button', {onClick: () => console.log('Wrong')}, '')
+h(Show, {when:() => n()%2 === 0, fallback:'odd'}, 'even')
 ```
 
-## Conditional Rendering
+It is also possible to conditionally render a component by prefixing it with a JavaScript *and-expression*, like in the example below,
+but using `Show` is going to be faster.
 
 ```js
-h(Show, {when:show}, 'Hi')
+h('',show&&'Hi')
 ```
 
 ## Rendering Lists
 
 ```js
-h(List, {each:show}, 'Hi')
+h(List, {each:['a','b','c']}, (v,i)=>`${i()}:${v()}`)
+```
+
+## Fetching Resources
+
+The `resource()` function lets you define a asynchronous signal.
+
+
+```js
+resource(async ()=>getPosts())
 ```
 
-## Inversion of Control
+## Dependency Injection
 Prelude supports dependency injection with the `contect` and `useContext` APIs.
 
-## Advanced DataTable
+```js
+const CounterCtx = context()
+const useCounter = () => useContext(CounterCtx)
+
+function CounterProvider(props) {
+  const count = signal(0)
+  const increment = () => count(i=>i+1)
+  return h(CounterCtx.Provider, {value:[count,increment]}, props.children)
+}
+
+function Counter() {
+  const [n, increment] = useCounter()
+  return h('button', {onClick:e=>increment()}, n)
+}
+
+function
+
+function App() {
+  h(CounterProvider, h(Counter))
+}
+```
+
+## Router
 
 ```js
-h(Table)
+h(Router,[
+  {path:'/', component:Posts},
+  {path:'/user', component:Users}
+])
 ```
+
+## Learn More
+
+* [API Reference]()
+* [SolidJS Docs]():
+  The documentation of SolidJS also a good place for background information because Prelude is lacking extensive documentation at this time.
+  Prelude started as a SolidJS clone, but with better HyperScript support. A lot of the concepts are the same but naming conventions can vary.
+
+## TODO
+
+* [ ] tailwind styling
+* SSR
+* Hydration
+* Components
+  * [ ] Select
+  * [ ] Multiselect
+  * [ ] DataTable
+  * [ ] Dropdown
+  * [ ] Dialog
+  * [ ] Dynamic
+
+## Links
+
+* [Homepage](https://wrnrlr.github.io/prelude)
+* [NPM](https://www.npmjs.com/package/@wrnrlr/prelude)
+* [JSR](https://jsr.io/@wrnrlr/prelude)

package/src/constants.ts

@@ -1,3 +1,4 @@
+// @ts-nocheck:
 /**
 * Non-breakable space in Unicode
 * @group Utils
@@ -13,7 +14,7 @@ declare type DocumentFragment = any
 export declare type Node = any
 
 export type Mountable = Elem | Document | ShadowRoot | DocumentFragment | Node;
-type ExpandableNode = Node & { [key: string]: any };
+type ExpandableNode = Node & { [key: string]: unknown };
 
 // type Expect<T extends true> = T;
 // type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;

package/src/{controlflow.js → controlflow.ts}

@@ -1,81 +1,94 @@
-import {signal,sample,batch,memo,root,Signal} from './reactive.ts'
+// @ts-nocheck:
+import type { Child } from './hyperscript.ts'
+import {signal,untrack,batch,memo,root,type Signal} from './reactive.ts'
+
+export type ShowProps<T> = {
+  when: T,
+  children: Child | ((a:()=>T)=>void),
+  fallback: unknown
+}
 
 /**
 Show children if `when` prop is true, otherwise show `fallback`.
 @group Components
 */
-export function Show(props) {
+export function Show<T>(props:ShowProps<T>) {
   const condition = memo(()=>props.when)
   return memo(()=>{
     const c = condition()
     if (c) {
       const child = props.children
       const fn = typeof child === "function" && child.length > 0
-      return fn ? sample(() => child(() => props.when)) : child
+      return fn ? untrack(() => child(() => props.when)) : child
     } else return props.fallback
   })
 }
 
-export function wrap(s,k) {
-  const t = typeof k
-  if (t === 'number') return (...a) => {
-    const b = s()
-    return (a.length) ? s(b.toSpliced(k, 1, a[0])).at(k) : b.at(k)
-  }; else if (t === 'string') return (...a) => {
-    const b = s()
-    return a.length ? s(({ ...b, [k]: a[0] }))[k] : b[k]
-  }; else if (t === 'function') return (...a) => {
-    const i = k(), c = typeof i
-    if (c==='number') return a.length ? s(old => old.toSpliced(i, 1, a[0]))[i] : s()[i]
-    else if (c === 'string') return a => a.length ? s(b => ({...b, [i]:a[0]}))[i] : s()[i]
-    throw new Error('Cannot wrap signal')
-  }
-  throw new Error('Cannot wrap signal')
+type ItemHolder = {
+  index:number,
+  indexSetter?:any,
+  value:unknown,
+  valueSetter:any,
+  disposer: any
+}
+
+export type ListProps<T> = {
+  when: T,
+  each: any,
+  children: Child | ((a:()=>T)=>void),
+  fallback: unknown
 }
 
 /**
 List
 @group Components
 */
-export function List(props) {
+export function List<T>(props:ListProps<T>) {
   const fallback = "fallback" in props && { fallback: () => props.fallback }
   const list = props.each
-  const cb = props.children.call ? props.children : (v)=>v
-  let items = [], item, unusedItems, i, j, newValue, mapped, oldIndex, oldValue,
-    indexes = cb.length > 1 ? [] : null;
-  function newValueGetter(_) { return newValue }
+  const cb:any = (props.children as any)?.call ? props.children : (v:any)=>v
+  let items:ItemHolder[] = [],
+    item: undefined|ItemHolder,
+    // unusedItems,
+    i: undefined|number,
+    newValue: undefined|number,
+    mapped: number[],
+    oldIndex: number,
+    oldValue: unknown
+  const indexes = cb.length > 1 ? [] : null;
+  function newValueGetter(_:unknown) { return newValue }
   function changeBoth() {
-    item.index = i
-    item.indexSetter?.(i)
-    item.value = newValue
-    item.valueSetter?.(newValueGetter)
+    item!.index = i!
+    item!.indexSetter?.(i)
+    item!.value = newValue!
+    item!.valueSetter?.(newValueGetter)
   }
-  function mapperWithIndexes(disposer) {
+  function mapperWithIndexes(disposer:any) {
     const V = newValue, I = i, Is = signal(I), Vs = signal(V)
-    items.push({value: newValue, index: I, disposer, indexSetter: Is, valueSetter: Vs})
+    items.push({value: newValue, index: I!, disposer, indexSetter: Is, valueSetter: Vs})
     return cb(
-      (...a) => a.length ?
-        sample(()=>list(list=>list.toSpliced(I,1,a[0])))
+      (...a:any[]) => a.length ?
+        untrack(()=>list((list:any)=>list.toSpliced(I,1,a[0])))
         : Vs(),
       ()=>Is())
   }
-  function mapperWithoutIndexes(disposer) {
+  function mapperWithoutIndexes(disposer:any) {
     const V = newValue, I = i, Vs = signal(V)
-    items.push({value: V, index: i, disposer, valueSetter: Vs})
-    return cb((...a) => a.length ?
-      sample(()=>list(list=>list.toSpliced(I,1,a[0])))
+    items.push({value: V, index: i!, disposer, valueSetter: Vs})
+    return cb((...a:unknown[]) => a.length ?
+      untrack(()=>list((list:any)=>list.toSpliced(I,1,a[0])))
       : Vs())
   }
   const mapper = indexes ? mapperWithIndexes : mapperWithoutIndexes
   return memo(() => {
-    const newItems = list() || []
+    const newItems = list.call ? list() : list
     // (newItems)[$TRACK]; // top level tracking
-    return sample(() => {
+    return untrack(() => {
       const temp = new Array(newItems.length) // new mapped array
-      unusedItems = items.length
+      let unusedItems = items.length
 
       // 1) no change when values & indexes match
-      for (j = unusedItems - 1; j >= 0; --j) {
+      for (let j = unusedItems - 1; j >= 0; --j) {
         item = items[j]
         oldIndex = item.index
         if (oldIndex < newItems.length && newItems[oldIndex] === item.value) {
@@ -90,7 +103,7 @@ export function List(props) {
       // #2 prepare values matcher
       const matcher = new Map()
       const matchedItems = new Uint8Array(unusedItems)
-      for (j = unusedItems - 1; j >= 0; --j) {
+      for (let j = unusedItems - 1; j >= 0; --j) {
         oldValue = items[j].value
         matcher.get(oldValue)?.push(j) ?? matcher.set(oldValue, [j])
       }
@@ -99,19 +112,19 @@ export function List(props) {
       for (i = 0; i < newItems.length; ++i) {
         if (i in temp) continue
         newValue = newItems[i]
-        j = matcher.get(newValue)?.pop() ?? -1
+        const j = matcher.get(newValue)?.pop() ?? -1
         if (j >= 0) {
-          item = items[j]
-          oldIndex = item.index
+          item = items[j as number]
+          oldIndex = item!.index
           temp[i] = mapped[oldIndex]
-          item.index = i
-          item.indexSetter?.(i)
-          matchedItems[j] = 1
+          item!.index = i
+          item!.indexSetter?.(i)
+          matchedItems[j as number] = 1
         }
       }
 
       // 3) reduce unusedItems for matched items
-      for (j = matchedItems.length - 1; j >= 0; --j) {
+      for (let j = matchedItems.length - 1; j >= 0; --j) {
         if (matchedItems[j] && --unusedItems !== j) {
           item = items[j]
           items[j] = items[unusedItems]
@@ -120,9 +133,9 @@ export function List(props) {
       }
 
       // 4) change values when indexes match
-      for (j = unusedItems - 1; j >= 0; --j) {
+      for (let j = unusedItems - 1; j >= 0; --j) {
         item = items[j];
-        oldIndex = item.index;
+        oldIndex = item!.index;
         if (!(oldIndex in temp) && oldIndex < newItems.length) {
           temp[oldIndex] = mapped[oldIndex]
           newValue = newItems[oldIndex]
@@ -156,7 +169,7 @@ export function List(props) {
   })
 }
 
-function disposeList(list) {
+function disposeList(list:any[]) {
   for (let i = 0; i < list.length; i++) {
     list[i]?.disposer()
   }

package/src/hyperscript.ts

@@ -1,5 +1,6 @@
-import {sample} from './reactive.ts'
-import {Properties,BooleanAttributes,DelegatedEvents,DOMElements, type Mountable} from './constants.ts'
+// @ts-nocheck:
+import {untrack} from './reactive.ts'
+import type {Properties,BooleanAttributes,DelegatedEvents,DOMElements, Mountable} from './constants.ts'
 import type {Runtime,$RUNTIME} from './runtime.ts'
 
 const ELEMENT: unique symbol = Symbol(), {isArray} = Array
@@ -89,7 +90,7 @@ export function hyperscript(r:Runtime, patch?:any):HyperScript {
     let children: Child
 
     if (typeof second === 'object' && !isArray(second)) {
-      children = third || [];
+      children = (third as Child) || [];
       props = ((second ?? {}) as T&{children:K})
     } else {
       children = (second as Child) || []
@@ -115,7 +116,7 @@ export function hyperscript(r:Runtime, patch?:any):HyperScript {
           dynamicProperty(props as any, k)
         }
       }
-      e = sample(()=>(element as Component<T&{children:K}>)(props as T&{children:K}))
+      e = untrack(()=>(element as Component<T&{children:K}>)(props as T&{children:K}))
       ret = () => e
     } else {
       const tag = parseTag(element as Tag)
@@ -160,12 +161,12 @@ function detectMultiExpression(list:any):boolean {
 // ^([a-zA-Z]\w*)?(#[a-zA-Z][-\w]*)?(.[a-zA-Z][-\w]*)*
 function parseTag(s:string):{name:string,id?:string,classes:string[]} {
   const classes:string[] = [];
-  let name:string, id = undefined, i:number
+  let id:string|undefined = undefined, i:number
 
   i = s.indexOf('#')
   if (i===-1) i = s.indexOf('.')
   if (i===-1) i = s.length
-  name = s.slice(0, i) || 'div'
+  const name = s.slice(0, i) || 'div'
   s = s.slice(i)
 
   if (s[0]==='#') {

package/src/mod.ts

@@ -1,15 +1,18 @@
+// @ts-nocheck:
 export type {Getter,Setter,Fn,EqualsFn,ErrorFn,RootFn,UpdateFn} from './reactive.ts'
-export {signal,effect,sample,batch,memo,root,onMount} from './reactive.ts'
+export {signal,effect,untrack,batch,memo,root,wrap,onMount} from './reactive.ts'
 export {nbsp} from './constants.ts'
-export {wrap,Show,List} from './controlflow.js'
+export {Show,List} from './controlflow.ts'
 export {runtime, type Runtime} from './runtime.ts'
 import {runtime, type Runtime} from './runtime.ts'
 export {hyperscript,type HyperScript,type Child,type Props,type Tag,type View,type Component} from './hyperscript.ts'
 import {type HyperScript, hyperscript} from './hyperscript.ts'
-export {Input,Table} from './components.js'
-export * from './canvas.js'
+export {Router} from './router.js'
+export {resource,makeAbortable,abortable} from './resource.js'
+// export {Input,Table} from './components.js'
+// export * from './canvas.js'
 
-const r:Runtime = runtime(window as any)
+const r:Runtime|undefined = /*#__PURE__*/ (typeof window === 'object') ? runtime(window as any) : undefined
 
 /** h
 @example Element with a single child
@@ -26,20 +29,19 @@ h(Input,{onInput:e => {}})
 ```
 @group Hyperscript
 */
-const h:HyperScript = hyperscript(r)
+const h:HyperScript|undefined = /*#__PURE__*/ r ? hyperscript(r) : undefined
 
-const render = r.render
+const render = /*#__PURE__*/ r?.render
 
-import {signal} from './reactive.ts'
-import {wrap} from './controlflow.js'
+// import {signal,wrap} from './reactive.ts'
 
-/**
-@group Utils
-*/
-export function $(a:any,b:any):any {
-  const t = typeof a
-  if (t==='function') return wrap(a,b)
-  else return signal(a,b)
-}
+// /**
+// @group Utils
+// */
+// export function $(a:any,b:any):any {
+//   const t = typeof a
+//   if (t==='function') return wrap(a,b)
+//   else return signal(a,b)
+// }
 
 export {h,render}