shama / base-element

:beginner: An element authoring library for creating standalone and performant elements.

shama

Things for helping me build other things.

Have an opinion on my things? Great! Fork and publish your own thing.

quick start

npm init
npm i shama --save-dev
./node_modules/.bin/shama
npm run watch

require('shama')

Create something like this or use ./node_modules/.bin/shama:

./
├── app
│   ├── css
│   │   └── index.styl
│   └── index.js
├── bin
│   └── build.js
└── package.json

bin/build.js

var path = require('path')
require('shama')(path.resolve(__dirname, '..'))

package.json

{
  "name": "thing",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "build": "node bin/build.js",
    "watch": "node bin/build.js watch"
  }
}

require('shama/build')

// Compile a index.html, index.js and index.css file
// using browserify and stylus
var build = require('shama/build')()
build.css().js().html()

// or more simply
build.all()

// or more complexly
build.all({
  js: { src: 'app/index.js', dest: 'dist/index.js' },
  css: { src: 'app/index.styl', dest: 'dist/index.css' },
  html: { dest: 'dist/index.html', title: 'My website' },
}, function(err) {
  console.log('done!')
})

require('shama/server')

// Starts a server using jaws on port 8080
var server = require('shama/server')({
  // Default is index.html
  '/': 'index.html',
  // Serve up static files from cwd
  '/*': './',
  // Write your own req/res handlers
  '/api/:endpoint': function(req, res) {
    var params = req.extras.params
    res.json({ params.endpoint: true })
  }
})
server.start(8080)

require('shama/watch')

require('shama/watch')({
  'app/**/*': build.all.bind(build),
})

license

Copyright (c) 2015 Kyle Robinson Young
Licensed under the MIT license.

base-element's Issues

server side rendering

extract style > css / css examples

CSS can be attached to elements with: this.attachCSS('css src') which will localize the CSS to the element.

• How does this fair with nested elements? Im thinking top level elements should rule the CSS of all nested elements
• Extract into separate module and add a ton more tests
• A dynamic className wont work well if written out to a file.css
• Experiment more with overriding element CSS

Combine the server / client test script

They should be combined as all aspects should run on both.

Then update the test script to: standard && node test/index.js && zuul --local 9966 -- test/index.js

browser-test-helpers needs an update most likely.

combine node.render() + this.afterRender() ?

From this.afterRender():

This method needs to be called when returning a constructed virtual tree.

If the method is mandatory, wouldn't it make sense to always run it internally? What are the use cases for not running this method?

const baseElement = require('base-element')
const html = require('virtual-dom')

const el = baseElement()

// I would prefer this:
el.render(data => html(`<div></div>`))

// over always typing this:
el.render(data => this.afterRender(html(`<div></div>`)))

I'm not sure how the internals are laid out, but passed in function is being bound it might simplify the code and possibly make the interface more resilient. Thanks!

replaceChild vs appendChild

I'm working on better mounting elements that were initially server rendered and looking for feedback

/cc @yoshuawuyts @bendrucker @chinedufn @sethvincent

Currently if a server renders <div class="app">Loading</div> and an element is loaded with createElement(document.querySelector('.app')) the resulting HTML is:

<div class="app">Loading<div class="app">Client Side Loaded</div></div> because the attach point always appends. We want to replaceChild instead to get the following HTML:

<div class="app">Client Side Loaded</div>

Which solution is preferred?

A) Leave attaching up to the user
This is what I currently do but it's a bit verbose

var el = createElement()
document.querySelector('.app').appendChild(el.element)
// or to mount
document.body.replaceChild(el.element, document.querySelector('.app'))

B) Detect if the attaching node is the same as rendered
The most simplest for the end user but a bit magical
We could check if the node has the same id or class and assume the user wants to replaceChild instead of appendChild:

<div class="app loading">Loading</div>

var el = createElement(document.querySelector('.app'))
// "el" is a div with the class "app" so we replace instead of append

C) Add methods to explicitly call
Adds more APIs to all elements which isn't desired

var el = createElement()
el.appendTo(document.body)
// or to mount
el.mountTo(document.querySelector('.app'))

Thanks!

Default __appendTo__ to false instead of document.body

Wanted to propose this for a future breaking version. I'm finding myself wanting to output a vtree from render without any DOM side effects far more often than I'm attaching components to the body. Super trivial to change the default in userland in the mean time.

.toString()?

When rendering on the server it can be neat to implement a .toString() function (or equivalent) to render components to html. I'm not sure what the tradeoffs are; but I think it's feasible to implement for every component. Thanks!

See Also

• vdom-to-html

Rename `.on()`?

Originally I named it .on() for readability, such as el.on('click') or el.on('selected'). But I understand that is a commonly used name so maybe another would be better suited. Initiated by this: https://twitter.com/yoshuawuyts/status/597563041119608832

@yoshuawuyts Could you elaborate more on why .attachListener() would be a better name? Thanks!

Security

Document setTimeout delay rationale

virtual-dom definitely requires you to wait until the next tick in hooks to be sure that DOM element has actually been inserted. base-element uses a timeout of 10 for load/unload events:

base-element/index.js

Lines 72 to 74 in 95f5ec2

	setTimeout(function BaseElement_unhook_setTimeout () {
	self.cb('unload', node)
	}, 10)

Why 10ms via setTimeout instead of just nextTick?

Add function removeEventListener

Does it make sense to add a removeEventListener function as well for symmetry?

This should also make it possible to do more sugary things like .once()