Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proofreading the docs... #37

Draft
wants to merge 12 commits into
base: v2
Choose a base branch
from
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ It's stable and predictable.

If you have ever played with Web-Component-like frameworks (not to name Vue, React, Svelte…), you may know how debugging gets tricky and requires extra tooling.

Because LEGO is native, your browser developper toobar is all you need.
Because LEGO is native, your browser developer toolbar is all you need.
- `debugger` works as expected,
- _step-by-step_ debugging,
- element inspector,
Expand Down Expand Up @@ -85,12 +85,12 @@ There's no [Vite](https://vitejs.dev/) nor other 3rd parties, it's [just an inte
## What is LEGO Behind?

- 👙 Minimalist: ~74~ 61 lines of readable code in its core (non-optimised, uncompressed, no cheating)
- 🌱 Zero dependency: it uses [Petit-Dom](https://github.com/yelouafi/petit-dom) which is stable and embedded, so no bad suprise in the future
- 🌱 Zero dependency: it uses [Petit-Dom](https://github.com/yelouafi/petit-dom) which is stable and embedded, so no bad surprise in the future
- ♻️ Reactive: updating the state recalculate the Virtual Dom when needed
- 🚀 fast: using virtual dom through a thin layer makes it close to bare-metal
- 💧 Simple: that's [Vanilla](http://vanilla-js.com/), there isn't much to know, it's a raw class to extend; no magic ✨
- 🪶 3 directives to enhance HTML: `:if` for conditions, `:for` for loops, `@myfuncname` to call an action
- 🏡 Native: LEGO components are actual native web-components, you benefit from all the today's and tomorrow's possibilites ([slot](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots), [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM), …).
- 🏡 Native: LEGO components are actual native web-components, you benefit from all the today's and tomorrow's possibilities ([slot](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots), [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM), …).

Lego is not (and will never be):
- 🏯 A full bloated frontend framework with routing. [Others do it well](https://github.com/visionmedia/page.js).
Expand Down
92 changes: 9 additions & 83 deletions docs/20.07-attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,103 +10,29 @@ parent: Usage
#### Component Attributes

Attributes declared on the components will be all be accessible through the `state`.
If the property is initialized in the `this.state`, the attribute will be reactive:

```html
<x-user status="thinking 🤔"><x-user>
```

`status` will therefore be reactive and the _thinking 🤔_ attribute value will overwrite the _Happy 😄_ default status.

⚠️ A property that is not declared in the `state` won't be reactive.

These properties can be accessed through `this.getAttribute()` from within the component.
After all, these components are just native! 🏡


#### Slots
vinyll marked this conversation as resolved.
Show resolved Hide resolved

[Slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) are part of the
native web-component.
Because Lego builds native web-components, you can use the standard _slots_ as documented.
If the property is initialized in the `this.state`, the attribute will be reactive.

Example:

__index.html__
```html
<user-profile>
<span>This user is in Paris</span>
<user-profile>
```

__bricks/user-profile.html__
```html
<template>
<h1>User profile</h1>
<p>important information: <slot></slot></p>
</template>
<x-user status="Thinking 🤔"></x-user>
```

Will write `…<p>important information: <span>This user is in Paris</span></p>`

[See more advanced examples](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots#Adding_flexibility_with_slots).


### Reactive CSS Within `<style>`
vinyll marked this conversation as resolved.
Show resolved Hide resolved

CSS is much more fun when it's scoped.
Here it come with the web-components.

Here again, no trick, just the full power of web-components and scoping styles.
Well, you should know that the css is reactive too! 😲

Writing CSS is as easy as

__bricks/x-user.html__
```html
<script>
const state = { fontScale: 1 }
const state = { status: "Happy 😄" }
</script>

<template>
<h1>Bonjour!</h1>
<p>User status: {{ state.status }}</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope, that should be ${ state.status }

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed 👍

</template>

<style>
:host {
font-size: ${state.fontScale}rem;
}
h1 {
padding: 1rem;
text-align: center;
}
</style>
```

#### Host

[`:host` is a native selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:host())
for web-components.
It allows to select the current component itself.

#### Variables

You can use variables in your CSS just like in your templates.

Example:
```html
<script>
const state = { color: '#357' }
</script>

<template>
<h1>Bonjour<h1>
</template>
`status` will therefore be reactive and the _Thinking 🤔_ attribute value will overwrite the _Happy 😄_ default status.

<style>
h1 {
color: ${ state.color };
}
</style>
```
⚠️ A property that is not declared in the `state` won't be reactive.

will apply the `#357` color onto `h1`.
These properties can be accessed through `this.getAttribute()` from within the component.
After all, these components are just native! 🏡
2 changes: 1 addition & 1 deletion docs/20.10-script.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ parent: Usage

## `<script extend>` tag

The "script extend" tag is has a special behavior.
The "script extend" tag is a special behavior.
You will create a class extending the component, that's how you extend your
full component with advanced script.

Expand Down
49 changes: 30 additions & 19 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,24 @@ layout: home

LEGO (_Lightweight Embedded Gluten-free Objects_) is a library for writing fast ♻️ reactive, 📦 scoped and predictable 🏡 **native web-components** in HTML/CSS/JS, that are easy to digest 🌱 for your browser.

## Native Web-Components?

Yes, you write native HTML, CSS and JS and create a native web-components [W3C](https://en.wikipedia.org/wiki/World_Wide_Web_Consortium) compliant.

It's stable and predictable.

If you have ever played with Web-Component-like frameworks (not to name Vue, React, Svelte…), you may know how debugging gets tricky and requires extra tooling.

Because LEGO is native, your browser developer toolbar is all you need.
- `debugger` works as expected,
- _step-by-step_ debugging,
- element inspector,
- the console with the live JS in the context…

It's all just normal!

## What does LEGO actually look like?

Example (`my-example.html`):
```html
<template>
Expand All @@ -19,34 +37,27 @@ Example (`my-example.html`):
</style>
```

These are **native HTML elements** with Shadow DOM, slots and all native features from the official specs.

Lego is:
## What is LEGO Behind?

- 👙 Minimalist: ~74~ 61 lines of readable code in its core (non-optimised, uncompressed, no cheating).
- 🌱 Low dependency: its single third-party is the minimalist [Petit-Dom](https://github.com/yelouafi/petit-dom) which itself has no dependency
- 👙 Minimalist: ~74~ 61 lines of readable code in its core (non-optimised, uncompressed, no cheating)
- 🌱 Zero dependency: it uses [Petit-Dom](https://github.com/yelouafi/petit-dom) which is stable and embedded, so no bad surprise in the future
- ♻️ Reactive: updating the state recalculate the Virtual Dom when needed
- 🚀 fast: using virtual dom through a thin layer makes it close to bare-metal
- 💧 Simple: that's [Vanilla](http://vanilla-js.com/), there isn't much to know, it's a raw class to extend; no magic ✨
- 🏡 Native: webcomponents are actual native webcomponents, you benefit from all the today's and tomorrow's possibilites (slot, encapsulation, …)
- 🦺 Safe: because it has no third-party dependency and is
fully based on browser features, it's secured and upgraded
via your browser.
- 🪶 3 directives to enhance HTML: `:if` for conditions, `:for` for loops, `@myfuncname` to call an action
- 🏡 Native: LEGO components are actual native web-components, you benefit from all the today's and tomorrow's possibilities ([slot](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots), [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM), …).

Lego is not (and will never be):
- 🏯 A full bloated frontend framework with built-in routing. [Others do it well](https://github.com/visionmedia/page.js).
- 🏗 A website builder with buit-in SSR or similar complexities.
- 🏯 A full bloated frontend framework with routing. [Others do it well](https://github.com/visionmedia/page.js).
- 🏗 A website builder with SSR or similar complexities.
- 🔐 An HTML replacement that locks you into a specific technology.
- 🧓 An old browsers or IE compatible library (you may try [webcomponent polyfills](https://github.com/webcomponents/polyfills) if you feel wild).

View the [demo](https://polight.github.io/lego-demo/) and [their source](https://github.com/Polight/lego-demo) 🧪.
## Next Steps and Demo
mlbiche marked this conversation as resolved.
Show resolved Hide resolved

Lego is inspired from the [native Web-Component spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components) and [Riot](https://riot.js.org/).
🧪 View the [demo](https://polight.github.io/lego-demo/) and [their source](https://github.com/Polight/lego-demo) 🧪.

It's just **much lighter** with simplicity, a source code that is readable for a regular human which makes it accessible to hack, tweak and maintain in the loooong term.
The [core lib](https://github.com/Polight/lego/blob/master/src/lib/Component.js) is only 61 <abbr title="Lines Of Code">LOC</abbr>!
Lego is as light as **3Kb** for the full bundle!
💭 Lego is inspired from the [native Web-Component spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components) and [Riot](https://riot.js.org/).

No Babel transpiler, no Parcel, no Webpack… it just works out of the box.
🔧 Customizing and contributing is just **much lighter** with simplicity, source that are easy to read, to hack and to maintain.

Demo: [view in action](https://polight.github.io/lego-demo/)
🎈 You can [read the core code](https://github.com/Polight/lego/blob/master/src/lib/Component.js) that is only 61 <abbr title="Lines Of Code">LOC</abbr> resulting that Lego is **as light as 3Kb** for the full bundle!
10 changes: 6 additions & 4 deletions src/compiler/vdom-parser.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ function cleanChildren(children = []) {
})
}

function extractDirectives(node) {
let isSetupMode = false
function extractDirectives(node, isSetup = isSetupMode) {
const directives = []
node.attrs = node.attrs.reduce((attrs, attr) => {
let name = attr.name
Expand Down Expand Up @@ -70,9 +71,10 @@ function convert(node, indentSize = 0) {
return wrapDirectives(directives, vnode(node.nodeName, attributes, childrenIndent), indent)
}

function parse(html, indent) {
const document = parseFragment(html)
return convert(document, indent)
function parse(html, isSetup) {
isSetupMode = isSetup
const document = parser.parseFragment(html)
return convert(document)
}

export default parse