cellery 0.0.2 → 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/decorations.js

@@ -0,0 +1,157 @@
+class Alignment {
+  direction = ''
+  justify = ''
+  items = ''
+
+  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 Spacing {
+  left = 0
+  top = 0
+  right = 0
+  bottom = 0
+
+  constructor(left, top, right, bottom) {
+    this.left = left
+    this.top = top
+    this.right = right
+    this.bottom = bottom
+  }
+
+  static all(value) {
+    return new Spacing(value, value, value, value)
+  }
+
+  static symmetric({ vertical, horizontal }) {
+    return new Spacing(horizontal, vertical, horizontal, vertical)
+  }
+
+  static only({ left, right, top, bottom }) {
+    return new Spacing(left, top, right, bottom)
+  }
+
+  toString() {
+    return `Spacing(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
+  }
+}
+
+class Color {
+  red = 0
+  green = 0
+  blue = 0
+  alpha = 0
+
+  constructor(red, green, blue, alpha) {
+    this.red = red || 0
+    this.green = green || 0
+    this.blue = blue || 0
+    this.alpha = alpha || 1
+  }
+
+  toString() {
+    return `Color(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
+  }
+
+  toRGBA() {
+    return `rgba(${this.red}, ${this.green}, ${this.blue}, ${this.alpha})`
+  }
+
+  toRGB() {
+    return `rgba(${this.red}, ${this.green}, ${this.blue})`
+  }
+
+  static from(value, alpha) {
+    if (typeof value === 'string' && value.startsWith('#')) {
+      return this.#fromHex(value, alpha)
+    }
+    if (typeof value === 'object') {
+      const { red, green, blue, alpha } = value
+      return new Color(red, green, blue, alpha)
+    }
+  }
+
+  static #fromHex(hex, alpha = 1) {
+    if (typeof hex !== 'string') return null
+
+    hex = hex.trim().replace(/^#/, '').toLowerCase()
+
+    if (hex.length === 3) {
+      const r = hex[0] + hex[0]
+      const g = hex[1] + hex[1]
+      const b = hex[2] + hex[2]
+      hex = r + g + b
+    }
+
+    if (hex.length !== 6 || !/^[0-9a-f]{6}$/.test(hex)) {
+      return null
+    }
+
+    const r = parseInt(hex.slice(0, 2), 16)
+    const g = parseInt(hex.slice(2, 4), 16)
+    const b = parseInt(hex.slice(4, 6), 16)
+
+    return new Color(r, g, b, alpha)
+  }
+}
+
+class Border {
+  width = 0
+  color = null
+
+  constructor(opts = {}) {
+    this.width = opts.width || 1
+    this.color = opts.color
+  }
+
+  static all(opts) {
+    return new Border(opts)
+  }
+
+  // todo: support trlb
+
+  toString() {
+    return `Border(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
+  }
+}
+
+class BoxDecoration {
+  border = null
+
+  constructor(opts = {}) {
+    this.border = opts.border
+  }
+
+  toString() {
+    return `BoxDecoration(${Object.entries(this).map(([k, v]) => `${k}: ${v}`)})`
+  }
+}
+
+const Size = {
+  XS: 'xs',
+  S: 's',
+  M: 'm',
+  L: 'l',
+  XL: 'xl'
+}
+
+module.exports = {
+  Alignment,
+  BoxDecoration,
+  Border,
+  Color,
+  Spacing,
+  Size
+}

package/package.json

@@ -1,37 +1,22 @@
 {
   "name": "cellery",
-  "version": "0.0.2",
+  "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"
+    "index.d.ts",
+    "lib"
   ],
   "devDependencies": {
-    "bare-fs": "^4.5.2",
     "brittle": "^3.19.0",
     "lunte": "^1.2.0",
     "prettier": "^3.6.2",
@@ -53,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"
   }
 }