31 |
32 | ## Features
33 | - **No transpilation** – It's all plain vanilla JavaScript
34 | - **Small size** – Weighing in at `3kb`, you'll barely notice it
35 | - **Minimal API** – Only a handfull functions to learn
36 | - **No magic** – Prototypal state and events
37 | - **It's fast** – Both on server and client
38 |
39 | ## Example
40 | ```js
41 | import { html, mount, use, Component } from 'https://cdn.skypack.dev/yeet@next'
42 |
43 | mount('body', Component(App))
44 |
45 | function App (state, emit) {
46 | use(store)
47 |
48 | return function () {
49 | return html`
50 |
51 |
Clicked ${state.count} times
52 |
53 |
54 | `
55 | }
56 | }
57 |
58 | function store (state, emitter) {
59 | state.count = 0
60 | emitter.on('increment', function () {
61 | state.count++
62 | emitter.emit('render')
63 | })
64 | }
65 | ```
66 |
67 | ## Why yeet?
68 | Building interactive and performant websites shouldn't require a whole lot of
69 | dependencies, a bundler, or even Node.js for that matter. The JavaScript
70 | language has all the capabilities required built right in, without sacrificing
71 | either developer or user experience.
72 |
73 | Frameworks are tools and tools should be interchangeable and easy to replace.
74 | That's why yeet rely on the lowest common denominator – the DOM. There are no
75 | unneccessary abstractions such as virtual DOM, synthetic events or template
76 | syntax to learn. Only functions and prototypes.
77 |
78 | If you know JavaScript you already know most there is to know about yeet. And
79 | anything new you learn from using yeet is directly benefitial to anything else
80 | you might want to use JavaScript for.
81 |
82 | ## Prototypal state
83 | The state object in yeet is shared between components using prototypes. You can
84 | think of the state object as a shared context which components can use to read
85 | from and write to.
86 |
87 | However, a component can only ever mutate its own state, it can only read from
88 | the parent state, yet they are the same object – what?! This is achieved using
89 | prototypes. The prototype of a component's state object is the parent
90 | component's state object.
91 |
92 |
93 | About prototypal inheritance
94 |
95 | JavaScript prototypes are the mechanism for inheriting properties and behavior
96 | from one object to another. What is facinating about prototypes is that they
97 | are live – meaning that any change made to an object is immediately made
98 | available to all other objects whose prototype chain includes said object.
99 |
100 | ```js
101 | const parent = {}
102 | const child = Object.create(parent)
103 |
104 | parent.name = 'world'
105 | console.log(`Hello ${parent.name}`) // Hello world
106 | console.log(`Hello ${child.name}`) // Hello world
107 |
108 | child.name = 'planet'
109 | console.log(`Hello ${parent.name}`) // Hello world
110 | console.log(`Hello ${child.name}`) // Hello planet
111 | ```
112 |
113 | Read more about [Object prototypes][Object prototypes].
114 |
115 |
116 |
117 | To modify a parent state object, one can use events to communicate up the
118 | component tree (or prototype chain, if you will).
119 |
120 | ## Events
121 | Events are the core mechanism for communication up the component tree. Yeet
122 | adhers to the dogma "data down, events up", which is to say that data should be
123 | passed down the component tree, either with state or as arguments. When
124 | something happens, e.g. the user clicks a button, an event should be emitted
125 | which bubbles up the component tree, notifying components which may then mutate
126 | their state and issue a re-render.
127 |
128 | ## Components
129 | Components can be usefull in situations when you need a locally contained state,
130 | want to use some third party library or want to know when components mount or
131 | unmout in the DOM.
132 |
133 | Components in yeet use [generator functions][generator functions] to control the
134 | component lifecycle. By using generators yeet can step through your component
135 | and pause execution until the appropiate time, e.g. when the component has
136 | updated or is removed from the DOM. This allows you to retain local variables
137 | which persist throughout the component lifespan without meddling with `this` or
138 | learning new state management techinques, they're just regular ol' variables.
139 |
140 | ```js
141 | import { html, ref, mount, Component } from 'https://cdn.skypack.dev/yeet@next'
142 | import mapboxgl from 'https://cdn.skypack.dev/mapbox-gl'
143 |
144 | const state = { center: [18.0704503, 59.3244897] }
145 |
146 | mount('#app', Component(Map), state)
147 |
148 | function * Map (state, emit) {
149 | const container = ref()
150 | let map
151 |
152 | yield function * () {
153 | yield html``
154 |
155 | map = map || new mapboxgl.Map({
156 | container: container.current,
157 | center: state.center
158 | })
159 | }
160 |
161 | map.destroy()
162 | }
163 | ```
164 |
165 | ### Generators
166 | Using generators allows you to keep local variables accessible throughout the
167 | component lifecycle. If you are already familiar with generators there's not
168 | really that much to learn.
169 |
170 | If you are new to generators, learning yeet will only further build your
171 | JavaScript toolset, there is nothing here which you cannot use in other
172 | contexts.
173 |
174 | A generator function is a special kind of function which can pause execution
175 | midway and allows us to inspect intermediate values before procceding with
176 | execution. A generator function has two caracteristics which set it appart from
177 | regular functions, and asterics (`*`) after the `function` keyword and the
178 | `yield` keyword.
179 |
180 |
181 | The anatomy of a generator function
182 |
183 | ```js
184 | // ↓ This thing makes it a generator function
185 | function * createGenerator (list) {
186 | for (const num of list) {
187 | yield num // ← Pause here
188 | }
189 | return 'finished!'
190 | }
191 |
192 | // ↓ Call it like any other function
193 | const generator = createGenerator([1, 2, 3])
194 |
195 | // We can now step through the generator
196 | generator.next() // { value: 1, done: false }
197 | generator.next() // { value: 2, done: false }
198 | generator.next() // { value: 3, done: false }
199 | generator.next() // { value: 'finished!', done: true }
200 | ```
201 |
202 |
203 |
204 | By yielding in a yeet component you are telling yeet to halt execution and save
205 | the rest of the function for later, e.g. when the component has updated or when
206 | it is removed from the DOM. A yeet component's lifecycle is thereby clearly laid
207 | out in chronological order, from top to bottom.
208 |
209 | #### Lifecycle
210 | Generators are used to declare the lifecycle of yeet components. Only functions,
211 | html partials (returned by the `html` and `svg` tags) and promises carry any
212 | special meaning when using `yield`. When a yeet component yields a function,
213 | that is the function which will be used for any consecutive re-renders. Anything
214 | that comes after `yield` will be executed once the components is removed from
215 | the DOM (e.g. replaced by another element).
216 |
217 | ```js
218 | function * MyComponent () {
219 | // Happens only once, during setup
220 | yield function () {
221 | // Happens every time the component updates
222 | }
223 | // Happens only once, when the component is removed/replaced
224 | }
225 | ```
226 |
227 | They yielded function may also be a generator function. This can be used to
228 | perform side effects such as setting up subscriptions, manually manipulating the
229 | DOM or initializing some third party library. This is handled asynchrounously,
230 | meaning the DOM will have updated and the changes may have been made visible to
231 | the user before the generator finishes.
232 |
233 | ```js
234 | function MyComponent () {
235 | return function * () {
236 | // Happens before every update
237 | yield html`
Hello planet!
`
238 | // Happens after every update
239 | }
240 | }
241 | ```
242 |
243 | If you require immediate access to the rendered element, e.g. to _synchronously_
244 | mutate or inspect the rendered element _before_ the page updates, you may yield
245 | yet another function.
246 |
247 | _Note: Use with causion, this may have a negative impact on performance._
248 |
249 | ```js
250 | function MyComponent () {
251 | return function () {
252 | return function * () {
253 | // Happens before every update
254 | yield html`
Hello planet!
`
255 | // Happens SYNCHRONOUSLY after every update
256 | }
257 | }
258 | }
259 | ```
260 |
261 | #### Arguments (a.k.a. `props`)
262 | Even though all components have access to the shared state, you'll probably need
263 | to supply your components with some arguments to configure behavior or forward
264 | particular properties. You can either provide extra arguments to the `Component`
265 | function or you can call the function returned by `Component` with any number of
266 | arguments.
267 |
268 | ```js
269 | function Reaction (state, emit) {
270 | // ↓ Arguments are provided to the inner function
271 | return function ({ emoji }) {
272 | return html``
273 | }
274 | }
275 |
276 | // ↓ Declare component on beforehand
277 | const ReactionComponent = Component(Reaction)
278 |
279 | // ↓ Declare component and arguments on beforehand
280 | const SadReaction = Component(Reaction, { emoji: '😢' })
281 |
282 | html`
283 |
288 | `
289 | ```
290 |
291 | ### Async components
292 | Components can yield any value but if you yield a Promise yeet will await the
293 | promise before it continues to render. On the server, rendering is asynchronous by
294 | design, this means that all promises are resolved as the component renders.
295 | Rendering in the browser behaves a little differently. While awaiting a promise
296 | nothing will be rendered in place of the component. Once all yielded promises
297 | have resolved (or rejected) the component will finish rendering and the element
298 | will appear on the page.
299 |
300 | Yeet does not make any difference between promises which resolve or reject, you
301 | will have to catch and handle rejections accordingly, yeet will just forward the
302 | resolved or rejected value.
303 |
304 | ```js
305 | import fetch from 'cross-fetch'
306 | import { html, use } from 'yeet'
307 |
308 | function User (state, emit) {
309 | const get = use(api) // ← Register api store with component
310 | return function () {
311 | // ↓ Expose the promise to yeet
312 | const user = yield get(`/users/${state.user.id}`)
313 | return html`
314 |
315 |
${user.name}
316 |
317 | `
318 | }
319 | }
320 |
321 | function api (state, emit) {
322 | if (!state.cache) state.cache = {} // ← Use existing cache if available
323 |
324 | // ↓ Return a function for lazily reading from the cache
325 | return function (url) {
326 | if (url in state.cache) return state.cache[url] // ← Read from cache
327 | return fetch(url).then(async function (res) {
328 | const data = await data.json()
329 | state.cache[url] = data // ← Store response in cache
330 | return data // ← Return repsonse
331 | })
332 | }
333 | }
334 | ```
335 |
336 | #### Lists and Keys
337 | In most situations yeet does an excellent job at keeping track of which
338 | component goes where. This is in part handled by identifying which template tags
339 | (the `html` and `svg` tag functions) are used. In JavaScript, template
340 | literals are unique and yeet leverages this to keep track of which template tag
341 | goes where.
342 |
343 | When it comes to components, yeet uses your component function as a unique key to
344 | keep track of which component is tied to which element in the DOM.
345 |
346 | When it comes to lists of identical components, this becomes difficult and yeet
347 | needs a helping hand in keeping track. In these situations, you can provide a
348 | unique `key` to each component which will be used to make sure that everything
349 | keeps running smoothly.
350 |
351 | ```js
352 | function Exponential (state, emit) {
353 | let exponent = 1
354 |
355 | function increment () {
356 | exponent++
357 | emit('render')
358 | }
359 |
360 | return function ({ num }) {
361 | return html`
362 |
363 |
364 |
365 | `
366 | }
367 | }
368 |
369 | const numbers = [1, 2, 3, 4, 5]
370 | return html`
371 |
372 | ${numbers.map((num) => Component(Exponential, { num, key: num }))}
373 |
374 | `
375 | ```
376 |
377 | ### Stores
378 | Stores are the mechanism for sharing behavior between components, or even apps.
379 | A store can subscribe to events, mutate the local state and issue re-renders.
380 |
381 | ```js
382 | import { html, use, Component } from 'https://cdn.skypack.dev/yeet@next'
383 |
384 | function Parent (state, emit) {
385 | use(counter) // ← Use the counter store with this component
386 |
387 | return function () {
388 | return html`
389 | ${Component(Increment)}
390 |
391 | ${Component(Decrement)}
392 | `
393 | }
394 | }
395 |
396 | function Increment (state, emit) {
397 | return html``
398 | }
399 |
400 | function Decrement (state, emit) {
401 | return html``
402 | }
403 |
404 | function counter (state, emitter) {
405 | state.count = 0 // ← Define some initial state
406 |
407 | emitter.on('increment', function () {
408 | state.count++
409 | emitter.emit('render')
410 | })
411 |
412 | emitter.on('decrement', function () {
413 | state.count--
414 | emitter.emit('render')
415 | })
416 | }
417 | ```
418 |
419 | #### Events
420 | How you choose to name your events is entirely up to you. There's only one
421 | exception: the `render` event has special meaning and will re-render the closest
422 | component in the component tree. The `render` event does not bubble.
423 |
424 | ## Server rendering (SSR)
425 | Yeet has first-class support for server rendering. There are plans to support
426 | server-rendered templates, meaning any backend could render the actual HTML and
427 | yeet would wire up functionality using the pre-existing markup.
428 |
429 | Rendering on the server supports fully asynchronous components. If a component
430 | yields promises, yeet will wait for these promises to resolve while rendering.
431 |
432 | ### Server rendered templates (non-Node.js)
433 | _Coming soon…_
434 |
435 | ## API
436 | The API is intentionally small.
437 |
438 | ### html
439 | Create html partials which can be rendered to DOM nodes (or strings in Node.js).
440 |
441 | ```js
442 | import { html } from 'https://cdn.skypack.dev/yeet@next'
443 |
444 | const name = 'planet'
445 | html`
Hello ${name}!
`
446 | ```
447 |
448 | #### Attributes
449 | Both literal attributes as well as dynamically "spread" attributes work. Arrays
450 | will be joined with an empty space (` `) to make it easier to work with many
451 | space separated attributes, e.g. `class`.
452 |
453 | ```js
454 | import { html } from 'https://cdn.skypack.dev/yeet@next'
455 |
456 | const attrs = { disabled: true, hidden: false, placeholder: null }
457 | html``
458 | // →
459 | ```
460 |
461 | ##### Events
462 | Events can be attached to elements using the standard `on`-prefix.
463 |
464 | ```js
465 | import { html } from 'https://cdn.skypack.dev/yeet@next'
466 |
467 | html``
468 | ```
469 |
470 | #### Arrays
471 | If you have lists of things you want to render as elements, interpolating arrays
472 | works just like you'd expect.
473 |
474 | ```js
475 | import { html } from 'https://cdn.skypack.dev/yeet@next'
476 |
477 | const list = [1, 2, 3]
478 | html`${list.map((num) => html`
${num}
`)}`
479 | ```
480 |
481 | #### Fragments
482 | It's not always that you can or need to have an outer containing element.
483 | Rendering fragments works just like single container elements.
484 |
485 | ```js
486 | import { html } from 'https://cdn.skypack.dev/yeet@next'
487 |
488 | html`
489 |
Hello world!
490 |
Lorem ipsum dolor sit amet…
491 | `
492 | ```
493 |
494 | ### svg
495 | The `svg` tag is required for rendering all kinds of SVG elements, such as
496 | ``
759 | template = document.createElement('template')
760 | template.innerHTML = html
761 | template = template.content
762 | if (template.childNodes.length === 1 && !isPlaceholder(template.firstChild)) {
763 | template = template.firstChild
764 | if (isSVG && !hasSVGTag) template = template.firstChild
765 | }
766 | templates.set(strings, template)
767 | return template
768 | }
769 |
770 | /**
771 | * Child node container
772 | * @class Child
773 | * @param {Node} node Current node
774 | * @param {number} index Node position
775 | * @param {Array} order List of sibling nodes
776 | * @param {Node} parent Parent node
777 | */
778 | function Child (node, index, order, parent) {
779 | this.node = node
780 | this.index = index
781 | this.order = order
782 | this.parent = parent
783 | }
784 |
785 | /**
786 | * Create a HTML partial object
787 | * @export
788 | * @class Partial
789 | * @param {Array} strings Template strings
790 | * @param {Array} values Template partials
791 | * @param {Boolean} isSVG Whether the partial is an SVG node
792 | */
793 | export function Partial (strings, values, isSVG = false) {
794 | this.key = strings
795 | this.strings = strings
796 | this.values = values
797 | this.isSVG = isSVG
798 | }
799 |
800 | /**
801 | * Create a context object
802 | * @export
803 | * @class Context
804 | * @param {any} key Unique context identifier
805 | * @param {object} [state={}] Context state object
806 | */
807 | function Context (key, state = {}) {
808 | this.key = key
809 | this.hooks = []
810 | this.editors = []
811 | this.state = state
812 | this.stack = [this]
813 | this.emitter = new Emitter()
814 | this.emit = this.emitter.emit.bind(this.emitter)
815 | this.emitter.on(HOOK, (fn) => this.hooks.push(fn))
816 | }
817 |
818 | /**
819 | * Reference a mounted node via ref#current
820 | * @class Ref
821 | * @export
822 | */
823 | class Ref {
824 | get current () {
825 | return refs.get(this)
826 | }
827 | }
828 |
829 | /**
830 | * Generic event emitter
831 | * @class Emitter
832 | * @extends {Map}
833 | */
834 | class Emitter extends Map {
835 | /**
836 | * Attach listener for event
837 | * @param {string} event Event name
838 | * @param {function(...any): void} fn Event listener function
839 | * @memberof Emitter
840 | */
841 | on (event, fn) {
842 | const listeners = this.get(event)
843 | if (listeners) listeners.add(fn)
844 | else this.set(event, new Set([fn]))
845 | }
846 |
847 | /**
848 | * Remove given listener for event
849 | * @param {string} event Event name
850 | * @param {function(...any): void} fn Registered listener
851 | * @memberof Emitter
852 | */
853 | removeListener (event, fn) {
854 | const listeners = this.get(event)
855 | if (listeners) listeners.delete(fn)
856 | }
857 |
858 | /**
859 | * Emit event to all listeners
860 | * @param {string} event Event name
861 | * @param {...any} args Event parameters to be forwarded to listeners
862 | * @memberof Emitter
863 | */
864 | emit (event, ...args) {
865 | if (event !== WILDCARD) this.emit(WILDCARD, event, ...args)
866 | if (!this.has(event)) return
867 | for (const fn of this.get(event)) fn(...args)
868 | }
869 | }
870 |
871 | /**
872 | * Implementation of EventListener
873 | * @link https://developer.mozilla.org/en-US/docs/web/api/eventlistener
874 | * @class EventHandler
875 | * @extends {Map}
876 | */
877 | class EventHandler extends Map {
878 | /**
879 | * Create a new EventHandler
880 | * @param {Node} node The node onto which to attach events
881 | * @memberof EventHandler
882 | */
883 | constructor (node) {
884 | super()
885 | this.node = node
886 | events.set(node, this)
887 | }
888 |
889 | /**
890 | * Get an existing EvetnHandler for node or create a new one
891 | * @param {Node} node The node to bind listeners to
892 | * @returns {EventHandler}
893 | */
894 | static get (node) {
895 | return events.get(node) || new EventHandler(node)
896 | }
897 |
898 | /**
899 | * Delegate to assigned event listener
900 | * @param {Event} event
901 | * @returns {any}
902 | * @memberof EventHandler
903 | */
904 | handleEvent (event) {
905 | const handle = this.get(event.type)
906 | return handle.call(event.currentTarget, event)
907 | }
908 |
909 | /**
910 | * Add event listener
911 | * @param {string} key Event name
912 | * @param {function(Event): any} value Event listener
913 | * @memberof EventHandler
914 | */
915 | set (key, value) {
916 | const { node } = this
917 | const event = key.replace(ON, '')
918 | if (value) node.addEventListener(event, this)
919 | else node.removeEventListener(event, this)
920 | super.set(event, value)
921 | }
922 | }
923 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "yeet",
3 | "description": "A teeny-weeny frontend framework for creating websites",
4 | "version": "1.0.0-1",
5 | "main": "dist/server.cjs.js",
6 | "browser": "dist/browser.cjs.js",
7 | "types": "dist/index.d.ts",
8 | "type": "module",
9 | "exports": {
10 | "import": "./index.js",
11 | "node": "./server.js",
12 | "default": "./index.js"
13 | },
14 | "scripts": {
15 | "test": "uvu test/server && umu test/browser && standard",
16 | "build": "npm run build:server && npm run build:browser && echo '{\"type\":\"commonjs\"}' > dist/package.json",
17 | "build:server": "rollup --no-esModule --format=cjs --file=dist/server.cjs.js server.js",
18 | "build:browser": "rollup --no-esModule --format=cjs --file=dist/browser.cjs.js index.js",
19 | "compile": "npx -p typescript tsc *.js --declaration --allowJs --emitDeclarationOnly --outFile dist/index.d.ts",
20 | "prepublishOnly": "npm run build && npm run compile"
21 | },
22 | "files": [
23 | "index.js",
24 | "server.js",
25 | "dist"
26 | ],
27 | "author": "Carl Törnqvist ",
28 | "license": "MIT",
29 | "devDependencies": {
30 | "rollup": "^2.40.0",
31 | "standard": "^16.0.3",
32 | "umu": "^0.0.2",
33 | "uvu": "^0.5.1"
34 | }
35 | }
36 |
--------------------------------------------------------------------------------
/server.js:
--------------------------------------------------------------------------------
1 | const RENDER = 'render'
2 | const REF_ATTR = /\s*ref=("|')?$/i
3 | const ATTRIBUTE = /<[a-z-]+[^>]*?\s+(([^\t\n\f "'>/=]+)=("|')?)?$/i
4 | const BOOL_PROPS = [
5 | 'async', 'autofocus', 'autoplay', 'checked', 'controls', 'default',
6 | 'defaultchecked', 'defer', 'disabled', 'formnovalidate', 'hidden',
7 | 'ismap', 'loop', 'multiple', 'muted', 'novalidate', 'open', 'playsinline',
8 | 'readonly', 'required', 'reversed', 'selected'
9 | ]
10 |
11 | /**
12 | * @callback Store
13 | * @param {object} state
14 | * @param {Emitter} emitter
15 | * @returns {any}
16 | */
17 |
18 | /**
19 | * @callback Initialize
20 | * @param {object} state
21 | * @param {Emit} emit
22 | * @returns {any}
23 | */
24 |
25 | /** @type {Context|null} */
26 | let current
27 |
28 | /** @type {WeakMap} */
29 | const cache = new WeakMap()
30 |
31 | /**
32 | * @callback Store
33 | * @param {object} state
34 | * @param {Emitter} emitter
35 | * @returns {any}
36 | */
37 |
38 | /**
39 | * Register a store function to be used for current component context
40 | * @export
41 | * @param {Store} fn Store function
42 | * @returns {any}
43 | */
44 | export function use (fn) {
45 | return fn(current.state, current.emitter)
46 | }
47 |
48 | /**
49 | * Create HTML partial
50 | * @export
51 | * @param {Array} strings Template literal strings
52 | * @param {...any} values Template literal values
53 | * @returns {Partial}
54 | */
55 | export function html (strings, ...values) {
56 | return new Partial({ strings, values })
57 | }
58 |
59 | /**
60 | * Create SVG partial
61 | * @export
62 | * @param {Array} strings Template literal strings
63 | * @param {...any} values Template literal values
64 | * @returns {Partial}
65 | */
66 | export const svg = html
67 |
68 | /**
69 | * Treat raw HTML string as partial, bypassing HTML escape behavior
70 | * @export
71 | * @param {any} value
72 | * @returns {Partial}
73 | */
74 | export function raw (value) {
75 | return new Raw(value)
76 | }
77 |
78 | /**
79 | * Declare where partial is to be mounted in DOM, useful for SSR
80 | * @export
81 | * @param {Node|string} node Any compatible node or node selector
82 | * @param {Partial} partial The partial to mount
83 | * @param {object} [state={}] Root state
84 | * @returns {Partial}
85 | */
86 | export function mount (selector, partial, state = {}) {
87 | partial.selector = selector
88 | partial.state = state
89 | return partial
90 | }
91 |
92 | /**
93 | * Render partial to promise
94 | * @export
95 | * @param {Partial} partial The partial to be rendered
96 | * @param {object} [state={}] Root state
97 | * @returns {Promise}
98 | */
99 | export async function render (partial, state = {}) {
100 | if (partial instanceof Component) partial = await unwrap(partial, state)
101 | if (!(partial instanceof Partial)) return Promise.resolve(partial)
102 |
103 | let string = ''
104 | for await (const chunk of parse(partial, state)) string += chunk
105 | return string
106 | }
107 |
108 | /**
109 | * Create element reference
110 | * @export
111 | * @returns {Ref}
112 | */
113 | export function ref () {
114 | return new Ref()
115 | }
116 |
117 | /**
118 | * Create a context object
119 | * @class Context
120 | * @param {object} [state={}] Initial state
121 | */
122 | function Context (state = {}) {
123 | const ctx = cache.get(state)
124 | if (ctx) state = Object.create(state)
125 | this.emitter = new Emitter(ctx?.emitter)
126 | this.state = state
127 | cache.set(state, this)
128 | }
129 |
130 | /**
131 | * Holder of raw HTML value
132 | * @class Raw
133 | */
134 | class Raw extends String {}
135 |
136 | /**
137 | * Create a HTML partial object
138 | * @export
139 | * @class Partial
140 | */
141 | export class Partial {
142 | constructor ({ strings, values }) {
143 | this.strings = strings
144 | this.values = values
145 | }
146 |
147 | async * [Symbol.asyncIterator] (state = {}) {
148 | yield * parse(this, state)
149 | }
150 | }
151 |
152 | /**
153 | * Creates a stateful component
154 | * @export
155 | * @param {Initialize} fn Component initialize function
156 | * @param {...args} args Arguments forwarded to component render function
157 | * @returns {function(...any): Component} Component render function
158 | */
159 | export function Component (fn, ...args) {
160 | const props = { fn, args, key: args[0]?.key || fn }
161 | if (this instanceof Component) return Object.assign(this, props)
162 | return Object.setPrototypeOf(Object.assign(function Render (..._args) {
163 | if (!_args.length) _args = args
164 | return new Component(fn, ..._args)
165 | }, props), Component.prototype)
166 | }
167 | Component.prototype = Object.create(Partial.prototype)
168 | Component.prototype.constructor = Component
169 | Component.prototype[Symbol.asyncIterator] = async function * (state = {}) {
170 | yield * await unwrap(this, state)
171 | }
172 |
173 | /**
174 | * Create iterable for partial
175 | * @param {Partial} partial The partial to parse
176 | * @param {object} [state={}] Root state passed down to components
177 | * @memberof Partial
178 | * @returns {AsyncGenerator}
179 | */
180 | async function * parse (partial, state = {}) {
181 | const { strings, values } = partial
182 |
183 | // Claim top level state to prevent mutations
184 | if (!cache.has(state)) cache.set(state, partial)
185 |
186 | let html = ''
187 | for (let i = 0, len = strings.length; i < len; i++) {
188 | const string = strings[i]
189 | let value = await values[i]
190 |
191 | // Aggregate HTML as we pass through
192 | html += string
193 |
194 | const isAttr = ATTRIBUTE.test(html)
195 |
196 | // Flatten arrays
197 | if (Array.isArray(value)) {
198 | value = await Promise.all(value.flat())
199 | }
200 |
201 | if (isAttr) {
202 | if (value instanceof Ref) {
203 | const match = REF_ATTR.exec(string)
204 | console.assert(match, !match && `yeet: Got a ref as value for \`${string.match(ATTRIBUTE)?.[2]}\`, use instead \`ref=\${myRef}\`.`)
205 | yield string.replace(match[0], '')
206 | continue
207 | } else if (typeof value === 'boolean' || value == null) {
208 | const [, attr, name, quote] = html.match(ATTRIBUTE)
209 | if (attr && BOOL_PROPS.includes(name)) {
210 | console.assert(!quote, quote && `yeet: Boolean attribute \`${name}\` should not be quoted, use instead \`${name}=\${${JSON.stringify(value)}}\`.`)
211 | // Drop falsy boolean attributes altogether
212 | if (!value) yield string.slice(0, (attr.length + 1) * -1)
213 | // Leave only the attribute name in place for truthy attributes
214 | else yield string.slice(0, (attr.length - name.length) * -1)
215 | continue
216 | }
217 | } else if (Array.isArray(value)) {
218 | value = await Promise.all(value.map(function (val) {
219 | return isObject(val) ? objToAttrs(val) : val
220 | }))
221 | value = value.join(' ')
222 | } else if (isObject(value)) {
223 | value = await objToAttrs(value)
224 | }
225 |
226 | html += value
227 | yield string + value
228 | continue
229 | }
230 |
231 | // No use of aggregate outside attributes
232 | html = ''
233 | yield string
234 |
235 | if (value != null) {
236 | yield * resolve(value, state)
237 | }
238 | }
239 | }
240 |
241 | /**
242 | * Resolve a value to string
243 | * @param {any} value The value to resolve
244 | * @param {object} state Current state
245 | * @returns {AsyncGenerator}
246 | */
247 | async function * resolve (value, state) {
248 | if (Array.isArray(value)) {
249 | for (const val of value) yield * resolve(val, state)
250 | return
251 | }
252 |
253 | if (value instanceof Component) value = await unwrap(value, state)
254 | if (value instanceof Partial) {
255 | yield * parse(value, state)
256 | } else {
257 | yield value instanceof Raw ? value : escape(value)
258 | }
259 | }
260 |
261 | /**
262 | * Escape HTML characters
263 | * @param {string} value
264 | * @returns {string}
265 | */
266 | function escape (value) {
267 | return String(value)
268 | .replace(/&/g, '&')
269 | .replace(//g, '>')
271 | .replace(/"/g, '"')
272 | .replace(/'/g, ''')
273 | }
274 |
275 | /**
276 | * Unwrap Component value
277 | * @param {Component} component
278 | * @param {object} state
279 | * @returns {any}
280 | */
281 | function unwrap (component, state) {
282 | const { fn, args } = component
283 | const ctx = current = new Context(state)
284 | const emit = ctx.emitter.emit.bind(ctx.emitter)
285 | return unwind(fn(ctx.state, emit), ctx, args)
286 | }
287 |
288 | /**
289 | * Serialize an object to HTML attributes
290 | * @param {object} obj An object
291 | * @returns {Promise}
292 | */
293 | async function objToAttrs (obj) {
294 | const arr = []
295 | for (let [key, value] of Object.entries(obj)) {
296 | value = await value
297 | arr.push(`${key}="${value}"`)
298 | }
299 | return arr.join(' ')
300 | }
301 |
302 | /**
303 | * Unwind nested generators, awaiting yielded promises
304 | * @param {any} value The value to unwind
305 | * @param {Context} ctx Current context
306 | * @param {Array} args Arguments to forward to setup functions
307 | * @returns {Promise<*>}
308 | */
309 | async function unwind (value, ctx, args) {
310 | while (typeof value === 'function') {
311 | current = ctx
312 | value = value(...args)
313 | args = []
314 | }
315 | if (value instanceof Component) {
316 | value = await unwrap(value, ctx.state)
317 | }
318 | if (isGenerator(value)) {
319 | let res = value.next()
320 | while (!res.done && (!res.value || res.value instanceof Promise)) {
321 | if (res.value instanceof Promise) {
322 | res.value = await res.value
323 | current = ctx
324 | }
325 | res = value.next(res.value)
326 | }
327 | return unwind(res.value, ctx, args)
328 | }
329 | return value
330 | }
331 |
332 | /**
333 | * Determine whether value is a plain object
334 | * @param {any} value
335 | * @returns {boolean}
336 | */
337 | function isObject (value) {
338 | return Object.prototype.toString.call(value) === '[object Object]'
339 | }
340 |
341 | /**
342 | * Determine whether value is a generator object
343 | * @param {any} obj
344 | * @returns {boolean}
345 | */
346 | function isGenerator (obj) {
347 | return obj &&
348 | typeof obj.next === 'function' &&
349 | typeof obj.throw === 'function'
350 | }
351 |
352 | /**
353 | * Create a reference to a element node (available in Browser only)
354 | * @class Ref
355 | */
356 | class Ref {}
357 |
358 | /**
359 | * Generic event emitter
360 | * @class Emitter
361 | * @extends {Map}
362 | */
363 | class Emitter extends Map {
364 | constructor (emitter) {
365 | super()
366 | if (emitter) {
367 | // Forward all event to provided emitter
368 | this.on('*', emitter.emit.bind(emitter))
369 | }
370 | }
371 |
372 | /**
373 | * Attach listener for event
374 | * @param {string} event Event name
375 | * @param {function(...any): void} fn Event listener function
376 | * @memberof Emitter
377 | */
378 | on (event, fn) {
379 | const listeners = this.get(event)
380 | if (listeners) listeners.add(fn)
381 | else this.set(event, new Set([fn]))
382 | }
383 |
384 | /**
385 | * Remove given listener for event
386 | * @param {string} event Event name
387 | * @param {function(...any): void} fn Registered listener
388 | * @memberof Emitter
389 | */
390 | removeListener (event, fn) {
391 | const listeners = this.get(event)
392 | if (listeners) listeners.delete(fn)
393 | }
394 |
395 | /**
396 | * Emit event to all listeners
397 | * @param {string} event Event name
398 | * @param {...any} args Event parameters to be forwarded to listeners
399 | * @memberof Emitter
400 | */
401 | emit (event, ...args) {
402 | if (event === RENDER) return
403 | if (event !== '*') this.emit('*', event, ...args)
404 | if (!this.has(event)) return
405 | for (const fn of this.get(event)) fn(...args)
406 | }
407 | }
408 |
--------------------------------------------------------------------------------
/test/browser/component/api.js:
--------------------------------------------------------------------------------
1 | import { suite } from 'uvu'
2 | import * as assert from 'uvu/assert'
3 | import { Partial, Component, html, use, render, mount } from '../../../index.js'
4 |
5 | const component = suite('component')
6 | const args = suite('arguments')
7 | const state = suite('state')
8 | const stores = suite('stores')
9 | const lifecycle = suite('lifecycle')
10 |
11 | component('inherits partial', function () {
12 | assert.type(Component, 'function')
13 | assert.ok(Object.isPrototypeOf.call(Partial.prototype, Component.prototype))
14 | })
15 |
16 | component('returns component object', function () {
17 | const fn = Component(Function.prototype)
18 | assert.type(fn, 'function')
19 | const res = fn()
20 | assert.instance(res, Partial)
21 | assert.instance(res, Component)
22 | })
23 |
24 | args('should be function', function () {
25 | const Main = Component(null)
26 | assert.throws(() => render(Main))
27 | })
28 |
29 | args('inital arguments', function () {
30 | const MyComponent = Component(function (state, emit) {
31 | assert.type(state, 'object')
32 | assert.type(emit, 'function')
33 | })
34 | render(MyComponent('test'))
35 | })
36 |
37 | args('are forwarded', function () {
38 | const MyComponent = Component(function () {
39 | return function (str) {
40 | assert.is(str, 'test')
41 | }
42 | })
43 | render(MyComponent('test'))
44 | })
45 |
46 | args('can be provided on declaration', function () {
47 | const MyComponent = Component(Main, 'world')
48 | render(MyComponent)
49 | function Main () {
50 | return (name) => assert.is(name, 'world')
51 | }
52 | })
53 |
54 | args('can be supplied when calling', function () {
55 | const MyComponent = Component(Main)
56 | render(MyComponent('world'))
57 | function Main () {
58 | return (name) => assert.is(name, 'world')
59 | }
60 | })
61 |
62 | args('provided when called override declaration arguments', function () {
63 | const MyComponent = Component(Main, 'world')
64 | render(MyComponent('planet'))
65 | function Main () {
66 | return (name) => assert.is(name, 'planet')
67 | }
68 | })
69 |
70 | state('is inherited', function () {
71 | render(html`
72 |
3 | 
8 |
9 |
10 |
11 | 
13 |
14 |
15 |
16 | 
18 |
19 |
20 |
21 | 
23 |
24 |
25 |
26 | 
28 |
29 |