@rip-lang/ui 0.3.0 → 0.3.2

package/README.md

@@ -16,7 +16,7 @@ import { get, use, start, notFound } from '@rip-lang/api'
 import { ripUI } from '@rip-lang/ui/serve'
 
 dir = import.meta.dir
-use ripUI dir: dir, watch: true, title: 'My App'
+use ripUI dir: dir, components: 'pages', includes: ['ui'], watch: true, title: 'My App'
 get '/css/*', -> @send "#{dir}/css/#{@req.path.slice(5)}"
 notFound -> @send "#{dir}/index.html", 'text/html; charset=UTF-8'
 start port: 3000
@@ -25,47 +25,101 @@ start port: 3000
 **`index.html`** — the page:
 
 ```html
-<script type="module" src="/rip/browser.js"></script>
+<script type="module" src="/rip/rip-ui.min.js"></script>
 <script type="text/rip">
-  { launch } = importRip! '/rip/ui.rip'
+  { launch } = importRip! 'ui.rip'
   launch()
 </script>
 ```
 
-**`components/index.rip`** — a component:
+**`pages/index.rip`** — a page component:
 
 ```coffee
 export Home = component
   @count := 0
   render
-    div
+    .
       h1 "Hello from Rip UI"
       button @click: (-> @count += 1), "Clicked #{@count} times"
 ```
 
 Run `bun index.rip`, open `http://localhost:3000`.
 
-## How It Works
+## Component Composition
 
-The browser loads two things from the `/rip/` namespace:
+Page components in `pages/` map to routes via file-based routing. Shared
+components in `ui/` (or any `includes` directory) are available by PascalCase
+name. No imports needed:
 
-- `/rip/browser.js` — the Rip compiler (~45KB gzip, cached forever)
-- `/rip/ui.rip` — the UI framework (compiled in the browser in ~10-20ms)
+```coffee
+# ui/card.rip
+export Card = component
+  title =! ""
+  render
+    .card
+      if title
+        h3 "#{title}"
+      @children
+
+# pages/about.rip
+export About = component
+  render
+    .
+      h1 "About"
+      Card title: "The Idea"
+        p "Components compose naturally."
+      Card title: "Architecture"
+        p "PascalCase resolution, signal passthrough, children blocks."
+```
+
+Reactive props via `:=` signal passthrough. Readonly props via `=!`.
+Children blocks passed as DOM nodes via `@children`.
+
+## How It Works
+
+The browser loads one file — `rip-ui.min.js` (~52KB Brotli) — which bundles the
+Rip compiler and the pre-compiled UI framework. No runtime compilation of the
+framework, no extra network requests.
 
 Then `launch()` fetches the app bundle, hydrates the stash, and renders.
 
+### Browser Execution Contexts
+
+Rip provides full async/await support across every browser context — no other
+compile-to-JS language has this:
+
+| Context | How async works | Returns value? |
+|---------|-----------------|----------------|
+| `<script type="text/rip">` | Async IIFE wrapper | No (fire-and-forget) |
+| Playground "Run" button | Async IIFE wrapper | No (use console.log) |
+| `rip()` console REPL | Rip `do ->` block | Yes (sync direct, async via Promise) |
+| `.rip` files via `importRip()` | ES module import | Yes (module exports) |
+
+The `!` postfix compiles to `await`. Inline scripts are wrapped in an async IIFE
+automatically. The `rip()` console function wraps user code in a `do ->` block
+so the Rip compiler handles implicit return and auto-async natively.
+
+### globalThis Exports
+
+When `rip-ui.min.js` loads, it registers these on `globalThis`:
+
+| Function | Purpose |
+|----------|---------|
+| `rip(code)` | Console REPL — compile and execute Rip code |
+| `importRip(url)` | Fetch, compile, and import a `.rip` file as an ES module |
+| `compileToJS(code)` | Compile Rip source to JavaScript |
+| `__rip` | Reactive runtime — `__state`, `__computed`, `__effect`, `__batch` |
+| `__ripComponent` | Component runtime — `__Component`, `__clsx`, `__fragment` |
+| `__ripExports` | All compiler exports — `compile`, `formatSExpr`, `VERSION`, etc. |
+
 ## The Stash
 
-Everything lives in one reactive tree:
+App state lives in one reactive tree:
 
 ```
 app
-├── components/          ← component source files
-│   ├── index.rip
-│   ├── counter.rip
-│   └── _layout.rip
-├── routes          ← navigation state (path, params, query, hash)
-└── data            ← reactive app state (title, theme, user, etc.)
+├── routes    ← navigation state (path, params, query, hash)
+└── data      ← reactive app state (title, theme, user, etc.)
 ```
 
 Writing to `app.data.theme` updates any component reading it. The stash
@@ -74,13 +128,14 @@ uses Rip's built-in reactive primitives — the same signals that power
 
 ## The App Bundle
 
-The bundle is JSON served at `/{app}/bundle`. It populates the stash:
+The bundle is JSON served at `/{app}/bundle`:
 
 ```json
 {
   "components": {
     "components/index.rip": "export Home = component...",
-    "components/counter.rip": "export Counter = component..."
+    "components/counter.rip": "export Counter = component...",
+    "components/_lib/card.rip": "export Card = component..."
   },
   "data": {
     "title": "My App",
@@ -89,20 +144,26 @@ The bundle is JSON served at `/{app}/bundle`. It populates the stash:
 }
 ```
 
+On disk you organize your app into `pages/` and `ui/`. The middleware
+maps them into a flat `components/` namespace in the bundle — pages go
+under `components/`, shared components under `components/_lib/`. The `_`
+prefix tells the router to skip `_lib/` entries when generating routes.
+
 ## Server Middleware
 
 The `ripUI` middleware registers routes for the framework files, the app
 bundle, and optional SSE hot-reload:
 
 ```coffee
-use ripUI app: '/demo', dir: dir, title: 'My App'
+use ripUI dir: dir, components: 'pages', includes: ['ui'], watch: true, title: 'My App'
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `app` | `''` | URL mount point |
 | `dir` | `'.'` | App directory on disk |
-| `components` | `'components'` | Components subdirectory within `dir` |
+| `components` | `'components'` | Directory for page components (file-based routing) |
+| `includes` | `[]` | Directories for shared components (no routes) |
 | `watch` | `false` | Enable SSE hot-reload |
 | `debounce` | `250` | Milliseconds to batch file change events |
 | `state` | `null` | Initial app state |
@@ -111,11 +172,10 @@ use ripUI app: '/demo', dir: dir, title: 'My App'
 Routes registered:
 
 ```
-/rip/browser.js      — Rip compiler
-/rip/ui.rip          — UI framework
+/rip/rip-ui.min.js   — Rip compiler + pre-compiled UI framework
 /{app}/bundle        — app bundle (components + data as JSON)
 /{app}/watch         — SSE hot-reload stream (when watch: true)
-/{app}/components/*       — individual component files (for hot-reload refetch)
+/{app}/components/*  — individual component files (for hot-reload refetch)
 ```
 
 ## State Preservation (Keep-Alive)
@@ -184,7 +244,6 @@ get '/', -> Response.redirect('/demo/', 302)
 start port: 3002
 ```
 
-Each app is a directory with `components/`, `css/`, `index.html`, and `index.rip`.
 The `/rip/` namespace is shared — all apps use the same compiler and framework.
 
 ## File Structure
@@ -193,16 +252,65 @@ The `/rip/` namespace is shared — all apps use the same compiler and framework
 my-app/
 ├── index.rip            # Server
 ├── index.html           # HTML page
-├── components/
+├── pages/               # Page components (file-based routing)
 │   ├── _layout.rip      # Root layout
 │   ├── index.rip        # Home          → /
 │   ├── about.rip        # About         → /about
 │   └── users/
 │       └── [id].rip     # User profile  → /users/:id
+├── ui/                  # Shared components (no routes)
+│   └── card.rip         # Card          → available as Card
 └── css/
     └── styles.css       # Styles
 ```
 
+Files starting with `_` don't generate routes (`_layout.rip` is a layout,
+not a page). Directories starting with `_` are also excluded, which is how
+shared components from `includes` stay out of the router.
+
+## Hash Routing
+
+For static hosting (GitHub Pages, S3, etc.) where the server can't handle
+SPA fallback routing, use hash-based URLs:
+
+```coffee
+launch '/app', hash: true
+```
+
+This switches from `/about` to `page.html#/about`. Back/forward navigation,
+direct URL loading, and `href="#/path"` links all work correctly.
+
+## Static Deployment — `launch bundle:`
+
+Inline all components in a single HTML file for zero-server deployment.
+Use `rip-ui.min.js` (~52KB Brotli) — a combined bundle with the compiler
+and pre-compiled UI framework. No extra network requests, no runtime
+compilation of the framework:
+
+```html
+<script type="module" src="dist/rip-ui.min.js"></script>
+<script type="text/rip">
+  { launch } = importRip! 'ui.rip'
+
+  launch bundle:
+    '/':        '''
+                  export Home = component
+                    render
+                      h1 "Hello"
+                '''
+    '/about':   '''
+                  export About = component
+                    render
+                      h1 "About"
+                '''
+  , hash: true
+</script>
+```
+
+See `docs/demo.html` for a complete example — the full Rip UI Demo app
+(6 components, router, reactive state, persistence) in 337 lines of
+static HTML.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/ui",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Zero-build reactive web framework — rip.js + ui.rip + launch(url)",
   "type": "module",
   "main": "ui.rip",
@@ -32,7 +32,7 @@
   "author": "Steve Shreeve <steve.shreeve@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "rip-lang": "^3.6.0"
+    "rip-lang": "^3.9.1"
   },
   "files": [
     "ui.rip",
@@ -40,7 +40,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@rip-lang/api": ">=1.1.4"
+    "@rip-lang/api": ">=1.1.6"
   },
   "peerDependenciesMeta": {
     "@rip-lang/api": {

package/serve.rip

@@ -7,12 +7,13 @@
 #
 # Usage:
 #   import { ripUI } from '@rip-lang/ui/serve'
-#   use ripUI app: '/demo', dir: dir, title: 'My App'
+#   use ripUI dir: dir, components: 'pages', includes: ['ui'], watch: true, title: 'My App'
 #
 # Options:
 #   app:        string  — URL mount point (default: '')
 #   dir:        string  — app directory on disk (default: '.')
-#   components: string  — components subdirectory name (default: 'components')
+#   components: string  — directory for page components, relative to dir (default: 'components')
+#   includes:   array   — directories for shared components, relative to dir (default: [])
 #   watch:      boolean — enable SSE hot-reload endpoint (default: false)
 #   debounce:   number  — ms to batch filesystem events (default: 250)
 #   state:      object  — initial app state passed via bundle
@@ -26,27 +27,27 @@ import { watch as fsWatch } from 'node:fs'
 export ripUI = (opts = {}) ->
   prefix        = opts.app or ''
   appDir        = opts.dir or '.'
-  componentsDir = opts.components or "#{appDir}/components"
+  componentsDir = "#{appDir}/#{opts.components or 'components'}"
+  includeDirs   = (opts.includes or []).map (d) -> "#{appDir}/#{d}"
   enableWatch   = opts.watch or false
   debounceMs    = opts.debounce or 250
   appState      = opts.state or null
   appTitle      = opts.title or null
   uiDir         = import.meta.dir
 
-  # Resolve compiler (rip.browser.js)
-  compilerPath = null
+  # Resolve rip-ui.min.js (compiler + UI framework bundled)
+  bundlePath = null
   try
-    compilerPath = Bun.fileURLToPath(import.meta.resolve('rip-lang/docs/dist/rip.browser.js'))
+    bundlePath = Bun.fileURLToPath(import.meta.resolve('rip-lang/docs/dist/rip-ui.min.js'))
   catch
-    compilerPath = "#{uiDir}/../../docs/dist/rip.browser.js"
+    bundlePath = "#{uiDir}/../../docs/dist/rip-ui.min.js"
 
   # ----------------------------------------------------------------------------
-  # Route: /rip/* — framework files (compiler + ui.rip), registered once
+  # Route: /rip/* — framework files, registered once
   # ----------------------------------------------------------------------------
 
   unless ripUI._registered
-    get "/rip/browser.js", (c) -> c.send compilerPath, 'application/javascript'
-    get "/rip/ui.rip", (c) -> c.send "#{uiDir}/ui.rip", 'text/plain; charset=UTF-8'
+    get "/rip/rip-ui.min.js", (c) -> c.send bundlePath, 'application/javascript'
     ripUI._registered = true
 
   # ----------------------------------------------------------------------------
@@ -66,6 +67,9 @@ export ripUI = (opts = {}) ->
   if enableWatch
     fsWatch componentsDir, { recursive: true }, (event, filename) ->
       bundleDirty = true if filename?.endsWith('.rip')
+    for incDir in includeDirs
+      fsWatch incDir, { recursive: true }, (event, filename) ->
+        bundleDirty = true if filename?.endsWith('.rip')
 
   get "#{prefix}/bundle", (c) ->
     if bundleDirty or not bundleCache
@@ -75,6 +79,13 @@ export ripUI = (opts = {}) ->
       for path in paths
         components["components/#{path}"] = Bun.file("#{componentsDir}/#{path}").text!
 
+      # Merge external include directories into components/_lib/
+      for dir in includeDirs
+        incPaths = Array.from(glob.scanSync(dir))
+        for path in incPaths
+          key = "components/_lib/#{path}"
+          components[key] = Bun.file("#{dir}/#{path}").text! unless components[key]
+
       data = {}
       data.title = appTitle if appTitle
       data.watch = enableWatch
@@ -94,11 +105,14 @@ export ripUI = (opts = {}) ->
       watcher  = null
       heartbeat = null
 
+      watchers = []
+
       cleanup = ->
-        watcher?.close()
+        w.close() for w in watchers
         clearTimeout(timer) if timer
         clearInterval(heartbeat) if heartbeat
-        watcher = heartbeat = timer = null
+        watchers = []
+        heartbeat = timer = null
 
       new Response new ReadableStream(
         start: (controller) ->
@@ -123,11 +137,16 @@ export ripUI = (opts = {}) ->
             timer = null
             send('changed', { paths }) if paths.length > 0
 
-          watcher = fsWatch componentsDir, { recursive: true }, (event, filename) ->
-            return unless filename?.endsWith('.rip')
-            pending.add "components/#{filename}"
-            clearTimeout(timer) if timer
-            timer = setTimeout(flush, debounceMs)
+          addWatcher = (dir, keyPrefix) ->
+            watchers.push fsWatch dir, { recursive: true }, (event, filename) ->
+              return unless filename?.endsWith('.rip')
+              pending.add "#{keyPrefix}#{filename}"
+              clearTimeout(timer) if timer
+              timer = setTimeout(flush, debounceMs)
+
+          addWatcher componentsDir, 'components/'
+          for incDir in includeDirs
+            addWatcher incDir, 'components/_lib/'
 
         cancel: -> cleanup()
       ),

package/ui.rip

@@ -360,6 +360,10 @@ buildRoutes = (components, root = 'components') ->
 
     continue if name.startsWith('_')
 
+    # Skip files in _-prefixed directories (shared components, not pages)
+    segs = rel.split('/')
+    continue if segs.length > 1 and segs.some((s, i) -> i < segs.length - 1 and s.startsWith('_'))
+
     urlPattern = fileToPattern(rel)
     regex = patternToRegex(urlPattern)
     routes.push { pattern: urlPattern, regex, file: filePath, rel }
@@ -392,6 +396,7 @@ getLayoutChain = (routeFile, root, layouts) ->
 export createRouter = (components, opts = {}) ->
   root = opts.root or 'components'
   base = opts.base or ''
+  hashMode = opts.hash or false
   onError = opts.onError or null
 
   stripBase = (url) ->
@@ -400,7 +405,21 @@ export createRouter = (components, opts = {}) ->
   addBase = (path) ->
     if base then base + path else path
 
-  _path       = __state(stripBase(location.pathname))
+  readUrl = ->
+    if hashMode
+      h = location.hash.slice(1)
+      return '/' unless h
+      if h[0] is '/' then h else '/' + h
+    else
+      location.pathname + location.search + location.hash
+
+  writeUrl = (path) ->
+    if hashMode
+      if path is '/' then location.pathname else '#' + path.slice(1)
+    else
+      addBase(path)
+
+  _path       = __state(stripBase(if hashMode then readUrl() else location.pathname))
   _params     = __state({})
   _route      = __state(null)
   _layouts    = __state([])
@@ -418,6 +437,7 @@ export createRouter = (components, opts = {}) ->
   resolve = (url) ->
     rawPath = url.split('?')[0].split('#')[0]
     path = stripBase(rawPath)
+    path = if path[0] is '/' then path else '/' + path
     queryStr = url.split('?')[1]?.split('#')[0] or ''
     hash = if url.includes('#') then url.split('#')[1] else ''
 
@@ -436,7 +456,7 @@ export createRouter = (components, opts = {}) ->
     onError({ status: 404, path }) if onError
     false
 
-  onPopState = -> resolve(location.pathname + location.search + location.hash)
+  onPopState = -> resolve(readUrl())
   window.addEventListener 'popstate', onPopState if typeof window isnt 'undefined'
 
   onClick = (e) ->
@@ -448,18 +468,19 @@ export createRouter = (components, opts = {}) ->
     return if url.origin isnt location.origin
     return if target.target is '_blank' or target.hasAttribute('data-external')
     e.preventDefault()
-    router.push url.pathname + url.search + url.hash
+    dest = if hashMode and url.hash then (url.hash.slice(1) or '/') else (url.pathname + url.search + url.hash)
+    router.push dest
 
   document.addEventListener 'click', onClick if typeof document isnt 'undefined'
 
   router =
     push: (url) ->
       if resolve(url)
-        history.pushState null, '', addBase(_path.read())
+        history.pushState null, '', writeUrl(_path.read())
 
     replace: (url) ->
       if resolve(url)
-        history.replaceState null, '', addBase(_path.read())
+        history.replaceState null, '', writeUrl(_path.read())
 
     back: -> history.back()
     forward: -> history.forward()
@@ -482,7 +503,7 @@ export createRouter = (components, opts = {}) ->
     routes: undefined  # overridden by getter
 
     init: ->
-      resolve location.pathname + location.search + location.hash
+      resolve readUrl()
       router
 
     destroy: ->
@@ -794,11 +815,14 @@ export createRenderer = (opts = {}) ->
 # ==============================================================================
 
 export launch = (appBase = '', opts = {}) ->
+  if typeof appBase is 'object'
+    opts = appBase
+    appBase = ''
   appBase = appBase.replace(/\/+$/, '')  # strip trailing slashes
   target = opts.target or '#app'
   compile = opts.compile or null
   persist = opts.persist or false
-  bundleUrl = "#{appBase}/bundle"
+  hash = opts.hash or false
 
   # Auto-detect compile function from the global rip.js module
   unless compile
@@ -810,10 +834,14 @@ export launch = (appBase = '', opts = {}) ->
     el.id = target.replace(/^#/, '')
     document.body.prepend el
 
-  # Fetch the app bundle
-  res = await fetch(bundleUrl)
-  throw new Error "launch: #{bundleUrl} (#{res.status})" unless res.ok
-  bundle = res.json!
+  # Get the app bundle — inline, from DOM, or fetch from server
+  if opts.bundle
+    bundle = opts.bundle
+  else
+    bundleUrl = "#{appBase}/bundle"
+    res = await fetch(bundleUrl)
+    throw new Error "launch: #{bundleUrl} (#{res.status})" unless res.ok
+    bundle = res.json!
 
   # Create the unified stash
   app = stash { components: {}, routes: {}, data: {} }
@@ -860,6 +888,7 @@ export launch = (appBase = '', opts = {}) ->
   router = createRouter appComponents,
     root: 'components'
     base: appBase
+    hash: hash
     onError: (err) -> console.error "[Rip] Error #{err.status}: #{err.message or err.path}"
 
   # Create renderer