cellery 0.0.4 → 1.0.0

package/README.md

@@ -1,16 +1,78 @@
 # Cellery
 
-> **WIP** - A deliberately simple cross-platform UI framework
+> **WIP** - A stream-driven cross-platform UI framework
 
-Cellery is a minimalist framework for cross-platform user interfaces. It keeps component internals simple while allowing renderers flexibility in how they display content. The framework provides essential building blocks called "Cells" - stateless, minimal components that renderers implement to allow complex applications to be built through composition.
+Cellery is a minimal UI framework built around streams. Components called **Cells** subscribe to events and emit render instructions — no virtual DOM, no framework lock-in. Any Adapter can consume the output: HTML, TUI, native, mobile, whatever fits your use case.
 
-Core philosophy: cells are stateless and minimal, renderers handle display, applications control behavior.
+## How it works
 
-## Why?
+Cellery sits at the end of a pipeline. Writers (state machines, database change feeds, RPC streams) push events in, and Cells react by emitting render instructions out.
 
-GUI, TUI, mobile, browser - all have unique needs. Rather than trying to solve all of these, `Cellery` lets you build functional components, similar to Flutter. Renderers can then choose to implement as much or as little as needed for their use case.
+This publishes events to `Cellery` which you can subscribe to.
 
-Want to render to eInk? Native components rather than React Native? TUI? Implement the `Cells` as you need for your use case while targetting a consistent UX across devices.
+```js
+const { Cellery } = require('cellery')
+
+pipeline(
+  myWriter,
+  new Transform({
+    transform(status, cb) {
+      this.push({ event: 'something-happened', status })
+      cb()
+    }
+  }),
+  cellery
+)
+```
+
+Cells subscribe to events and re-render reactively:
+
+```js
+const welcome = new Message({ id: 'welcome', value: 'Welcome', cellery })
+
+welcome.sub({ event: 'login' }, (cell, { user }) => {
+  cell.value = `Welcome back ${user.displayName}`
+  cell.render({ id: 'messages', insert: 'beforeend' })
+})
+```
+
+Or you render Cells at will, passing details how they should render:
+
+```js
+const msg = new Message({ value: 'Use /join <invite> to join a room', cellery })
+msg.render({ id: 'messages', insert: 'beforeend' })
+```
+
+Rendering is handled by `Adapters`. Currently these are simply called by `Cellery` to render components when components manually choose to be re-rendered. By default they pass along meta so your `adapter` can figure out what to do with them. But there's no rules, no lifecycles. Just streams of content and events for your to react to as you need.
+
+## Cells
+
+We're trying to keep Cells simple. A super basic set of low level components to see how much can be achieved with little.
+
+| Cell        | Description                              |
+|-------------|------------------------------------------|
+| `Cell`      | Base class for all components            |
+| `MultiCell` | Composes multiple cells into one render  |
+| `Container` | Layout wrapper with scroll and flex opts |
+| `App`       | Root cell, id is always `'app'`          |
+| `Text`      | Inline text content                      |
+| `Paragraph` | Block text content                       |
+| `Input`     | Text input, single or multiline          |
+
+## Decorations
+
+Style primitives passed to cells — `Adapters` decide how to apply them. Just more meta for you to render with.
+
+- `Color` — RGBA color, construct from hex or object
+- `Spacing` — padding/margin with `all`, `symmetric`, or `only`
+- `Border` — border width and color
+- `BoxDecoration` — wraps border (and future decoration props)
+- `Alignment` — horizontal or vertical layout direction with justify/items
+- `Size` — named size tokens: `xs`, `s`, `m`, `l`, `xl`
+
+## Renderers
+
+`Adapters` must implement a single `render(cell)` method and return content in whatever format they need. The framework makes no assumptions about output format.
 
 ## Status
 

package/index.js

@@ -0,0 +1,9 @@
+const Cellery = require('./lib/cellery')
+const cells = require('./lib/cells')
+const decoration = require('./lib/decorations')
+
+module.exports = {
+  Cellery,
+  ...cells,
+  ...decoration
+}

package/lib/cellery.js

@@ -0,0 +1,24 @@
+const Iambus = require('iambus')
+
+class Cellery extends Iambus {
+  constructor(app, adapter) {
+    super()
+    this.app = app
+    this.adapter = adapter
+
+    this.app.register(this)
+  }
+
+  // TODO: pipe compat...
+  write(data) {
+    this.pub(data)
+  }
+  on(type, cb) {}
+  emit(type, stream) {}
+
+  render() {
+    this.app.render()
+  }
+}
+
+module.exports = Cellery

package/lib/cells.js

@@ -0,0 +1,116 @@
+class Cell {
+  constructor(opts = {}) {
+    this.id = opts.id
+    this.children = opts.children || []
+    this.cellery = opts.cellery
+    this.padding = opts.padding
+    this.margin = opts.margin
+    this.color = opts.color
+    this.alignment = opts.alignment
+    this.decoration = opts.decoration
+    this.size = opts.size
+  }
+
+  sub(pattern, cb) {
+    this.cellery.sub(pattern).on('data', (d) => cb(this, d))
+  }
+
+  render(opts = {}) {
+    this.cellery.pub({
+      event: 'render',
+      id: this.id,
+      content: this.cellery.adapter.render(this),
+      ...opts
+    })
+  }
+
+  destroy() {
+    this.cellery.pub({
+      event: 'render',
+      id: this.id,
+      destroy: true
+    })
+  }
+
+  register(cellery) {
+    this.cellery = cellery
+    for (const c of this.children) {
+      c.register(cellery)
+    }
+  }
+}
+
+class MultiCell {
+  constructor(opts = {}) {
+    this.id = opts.id
+    this.cellery = opts.cellery
+  }
+
+  sub(pattern, cb) {
+    this.cellery.sub(pattern).on('data', (d) => cb(this, d))
+  }
+
+  _render() {
+    // impl
+  }
+
+  render(opts = {}) {
+    const cell = this._render()
+    cell.register(this.cellery)
+    cell.render(opts)
+  }
+}
+
+class Container extends Cell {
+  // TODO: replace with classes
+  static ScrollAll = 'all'
+  static ScrollVertical = 'vertical'
+  static ScrollHorizontal = 'horizontal'
+  static ScrollNone = 'none'
+  static FlexAuto = 'auto'
+  static FlexNone = 'none'
+
+  constructor(opts = {}) {
+    super(opts)
+    this.scroll = opts.scroll || Container.ScrollNone
+    this.flex = opts.flex || Container.FlexNone
+  }
+}
+
+class App extends Cell {
+  constructor(opts = {}) {
+    super({ ...opts, id: 'app' })
+  }
+}
+
+class Text extends Cell {
+  constructor(opts = {}) {
+    super(opts)
+    this.value = opts.value || ''
+  }
+}
+
+class Paragraph extends Cell {
+  constructor(opts = {}) {
+    super(opts)
+  }
+}
+
+class Input extends Cell {
+  constructor(opts = {}) {
+    super(opts)
+    this.multiline = !!opts.multiline
+    this.placeholder = opts.placeholder
+    this.type = opts.type || 'text'
+  }
+}
+
+module.exports = {
+  Cell,
+  MultiCell,
+  Container,
+  App,
+  Text,
+  Paragraph,
+  Input
+}

package/lib/{base.js → decorations.js}

@@ -1,12 +1,24 @@
-const { EventEmitter } = require('events')
+class Alignment {
+  direction = ''
+  justify = ''
+  items = ''
 
-const Alignment = {
-  Left: 'left',
-  Center: 'center',
-  Right: 'right'
+  constructor(direction, justify, items) {
+    this.direction = direction
+    this.justify = justify
+    this.items = items
+  }
+
+  static Horizontal({ justify, items }) {
+    return new Alignment('horizontal', justify, items)
+  }
+
+  static Vertical({ justify, items }) {
+    return new Alignment('vertical', justify, items)
+  }
 }
 
-class EdgeInsets {
+class Spacing {
   left = 0
   top = 0
   right = 0
@@ -20,49 +32,19 @@ class EdgeInsets {
   }
 
   static all(value) {
-    return new EdgeInsets(value, value, value, value)
+    return new Spacing(value, value, value, value)
   }
 
   static symmetric({ vertical, horizontal }) {
-    return new EdgeInsets(horizontal, vertical, horizontal, vertical)
+    return new Spacing(horizontal, vertical, horizontal, vertical)
   }
 
   static only({ left, right, top, bottom }) {
-    return new EdgeInsets(left, top, right, bottom)
-  }
-
-  toString() {
-    return `EdgeInsets(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
-  }
-}
-
-class Border {
-  width = 0
-  color = null
-
-  constructor(opts = {}) {
-    this.width = opts.width || 1
-    this.color = opts.color
-  }
-
-  static all(opts) {
-    return new Border(opts)
-  }
-
-  toString() {
-    return `Border(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
-  }
-}
-
-class BoxDecoration {
-  border = null
-
-  constructor(opts = {}) {
-    this.border = opts.border
+    return new Spacing(left, top, right, bottom)
   }
 
   toString() {
-    return `BoxDecoration(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
+    return `Spacing(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
   }
 }
 
@@ -125,71 +107,51 @@ class Color {
   }
 }
 
-class HotKey {
-  constructor(opts = {}) {
-    this.key = opts.key
-    this.ctrl = opts.ctrl ?? false
-    this.shift = opts.shift ?? false
-  }
-}
+class Border {
+  width = 0
+  color = null
 
-class Cell extends EventEmitter {
-  constructor() {
-    super()
+  constructor(opts = {}) {
+    this.width = opts.width || 1
+    this.color = opts.color
   }
 
-  setAttribute(key, value) {
-    const oldValue = this[key]
-    this[key] = value
-
-    if (this.constructor.observedAttributes && this.constructor.observedAttributes.includes(key)) {
-      this.attributeChangedCallback(key, oldValue, value)
-    }
+  static all(opts) {
+    return new Border(opts)
   }
 
-  connectedCallback() {}
-  disconnectedCallback() {}
-  adoptedCallback() {}
-  attributeChangedCallback(name, oldValue, newValue) {}
+  // todo: support trlb
 
   toString() {
-    return `${this.constructor.name}(${Object.entries(this)
-      .filter(([_, v]) => (Array.isArray(v) ? v.length : v))
-      .map(([k, v]) => `${k}: ${Array.isArray(v) ? `[${v.map((vc) => vc.toString())}]` : v}`)
-      .join(', ')})`
+    return `Border(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
   }
 }
 
-class Cellery {
-  #renderer = null
-  #child = null
+class BoxDecoration {
+  border = null
 
   constructor(opts = {}) {
-    this.#renderer = opts.renderer
-    this.#child = opts.child
+    this.border = opts.border
   }
 
-  update(child) {
-    this.#child = child
-    return this.#renderer.render(child)
+  toString() {
+    return `BoxDecoration(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
   }
+}
 
-  render() {
-    if (!this.#renderer) {
-      return this.#child.toString()
-    }
-
-    return this.#renderer.render(this.#child)
-  }
+const Size = {
+  XS: 'xs',
+  S: 's',
+  M: 'm',
+  L: 'l',
+  XL: 'xl'
 }
 
 module.exports = {
   Alignment,
-  Border,
   BoxDecoration,
+  Border,
   Color,
-  EdgeInsets,
-  Cell,
-  Cellery,
-  HotKey
+  Spacing,
+  Size
 }

package/package.json

@@ -1,40 +1,22 @@
 {
   "name": "cellery",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "description": "cellery",
   "exports": {
     "./package": "./package.json",
-    "./renderers": "./lib/renderers/index.js",
-    "./components": "./lib/components/index.js",
     ".": {
       "types": "./index.d.ts",
-      "default": "./lib/index.js"
-    }
-  },
-  "imports": {
-    "process": {
-      "bare": "bare-process",
-      "default": "process"
-    },
-    "fs": {
-      "bare": "bare-fs",
-      "default": "fs"
-    },
-    "events": {
-      "bare": "bare-events",
-      "default": "events"
+      "default": "./index.js"
     }
   },
+  "type": "commonjs",
   "files": [
     "package.json",
     "index.js",
     "index.d.ts",
-    "lib",
-    "demo",
-    "example.js"
+    "lib"
   ],
   "devDependencies": {
-    "bare-fs": "^4.5.2",
     "brittle": "^3.19.0",
     "lunte": "^1.2.0",
     "prettier": "^3.6.2",
@@ -56,9 +38,6 @@
   },
   "homepage": "https://github.com/holepunchto/cellery",
   "dependencies": {
-    "bare-ansi-escapes": "^2.2.3",
-    "bare-events": "^2.8.2",
-    "bare-process": "^4.2.2",
-    "graceful-goodbye": "^1.3.3"
+    "iambus": "^2.0.6"
   }
 }