├── .gitignore
├── .prettierignore
├── CHANGELOG.md
├── LICENSE.md
├── README.md
├── package-lock.json
├── package.json
├── prettier.config.cjs
├── rollup.config.js
├── src
├── shoemaker.ts
└── utilities
│ ├── attributes.ts
│ ├── directives.ts
│ └── properties.ts
└── tsconfig.json
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | dist
3 | examples
4 | node_modules
--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
1 | *.md
2 | .github
3 | lib
4 | node_modules
5 | package-lock.json
6 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | # 1.0.0-beta.6
4 |
5 | - Use `_` prefix for private properties to improve end user experience
6 |
7 | # 1.0.0-beta.5
8 |
9 | - 🚨 BREAKING: renamed lifecyle methods so they're more intuitive
10 | - `onBeforeMount` => `onConnect`
11 | - `onMount` => `onReady`
12 | - `onDestroy` => `onDisconnect`
13 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | Copyright (c) 2020 A Beautiful Site, LLC
2 |
3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4 |
5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6 |
7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Shoemaker
2 |
3 | An elegant way to create web components.
4 |
5 | Created by [Cory LaViska](https://twitter.com/claviska).
6 |
7 | ⚠️ This project was a fun experiment, but it is no longer being developed or maintained.
8 |
9 | ## Overview
10 |
11 | Shoemaker provides an abstract class that you can extend to make your own [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) with an elegant API and reactive data binding. It gives you a closer-to-the-metal experience than many other custom element authoring tools.
12 |
13 | - Declarative templates
14 | - Reactive data binding via props
15 | - Fast, efficient rendering
16 | - Lifecycle hooks
17 | - Watchers
18 |
19 | Shoemaker is written in TypeScript. For an optimal developer experience you should use TypeScript as well, but it is by no means a requirement.
20 |
21 | ## Installation
22 |
23 | To get started, install Shoemaker:
24 |
25 | ```bash
26 | npm install @shoelace-style/shoemaker
27 | ```
28 |
29 | ## Your First Component
30 |
31 | Let's create a simple counter component using TypeScript.
32 |
33 | ```ts
34 | import { Shoemaker, html } from '@shoelace-style/shoemaker';
35 |
36 | export class MyCounter extends Shoemaker {
37 | static tag = 'my-counter';
38 | static props = ['count'];
39 |
40 | count = 0;
41 |
42 | render() {
43 | return html`
44 |
45 | Count: ${this.count}
46 |
47 | `;
48 | }
49 | }
50 |
51 | MyCounter.register(); // now you can use
55 | JavaScript version
56 |
57 | The same component in browser-friendly JavaScript looks like this.
58 |
59 | ```js
60 | import { Shoemaker, html } from '@shoelace-style/shoemaker';
61 |
62 | export class MyCounter extends Shoemaker {
63 | constructor() {
64 | super();
65 | this.count = 0;
66 | }
67 |
68 | render() {
69 | return html`
70 |
71 | Count: ${this.count}
72 |
73 | `;
74 | }
75 | }
76 |
77 | MyCounter.tag = 'my-counter';
78 | MyCounter.props = ['count'];
79 | MyCounter.register();
80 | ```
81 |
82 |
83 | ## API
84 |
85 | ### Metadata
86 |
87 | Metadata is defined using the following static properties.
88 |
89 | - `tag` - The custom element's tag. Per the spec, this must start with a letter and contain at least one dash.
90 | - `props` - An array of prop names to be made reactive. That is, changing any of these props will trigger a rerender. Always use camelCase notation for props.
91 | - `reflect` - An array of prop names that will reflect their values to the corresponding DOM attribute (e.g. `myProp` ==> `my-prop`).
92 | - `styles` - A string containing the component's stylesheet. If you're using a bundler, it's convenient to import your CSS or SCSS as a string from separate files.
93 |
94 | In TypeScript, metadata is defined like this:
95 |
96 | ```ts
97 | class MyComponent extends Shoemaker {
98 | static tag = 'my-component';
99 | static props = ['value', 'disabled'];
100 | static reflect = ['disabled'];
101 | static styles = `...`;
102 |
103 | // ...
104 | }
105 | ```
106 |
107 |
108 | JavaScript version
109 | If you're not using TypeScript or Babel to transpile bleeding-edge JavaScript into something browsers can understand, you should define metadata like this instead:
110 |
111 | ```js
112 | class MyComponent extends Shoemaker {
113 | // ...
114 | }
115 |
116 | MyComponent.tag = 'my-component';
117 | MyComponent.props = ['value', 'disabled'];
118 | MyComponent.reflect = ['disabled'];
119 | MyComponent.styles = `...`;
120 | ```
121 |
122 |
123 | ### Props
124 |
125 | In Shoemaker, the term "prop" refers to a form of state that the user controls by setting HTML attributes or JavaScript properties on the element. The concept of attributes and properties can be confusing, so Shoemaker abstracts them into "props." Internally, Shoemaker only looks at properties, but it will automatically sync attribute changes to their corresponding properties for better DX. This means that the color attribute in `` will translate to `this.color = 'blue'` on the element instance and, if the attribute changes, `this.color` will update to match.
126 |
127 | By default, property changes will not reflect back to attributes. Thus, setting `this.color = 'tomato'` will update the property but not the attribute nor the DOM. You can modify this behavior by adding props to the `reflect` array. This can be useful if you intend to style your element with attribute selectors.
128 |
129 | Attributes are always lower-kebab-case and properties are always camelCase. For example, an attribute named primary-color will have a corresponding property of primaryColor. Shoemaker handles this conversion for you automatically.
130 |
131 | In TypeScript, props can be defined like this:
132 |
133 | ```ts
134 | class MyComponent extends Shoemaker {
135 | static tag = 'my-component';
136 | static props = ['value', 'disabled']; // make them reactive
137 |
138 | value: number = 0;
139 | disabled: boolean = false;
140 |
141 | // ...
142 | }
143 | ```
144 |
145 |
146 | JavaScript version
147 | The same props can be defined in JavaScript like this:
148 |
149 | ```js
150 | class MyComponent extends Shoemaker {
151 | constructor() {
152 | super();
153 | this.value = 0;
154 | this.disabled = false;
155 | }
156 |
157 | // ...
158 | }
159 |
160 | MyComponent.tag = 'my-component';
161 | MyComponent.props = ['value', 'disabled']; // make them reactive
162 |
163 | ```
164 |
165 |
166 | ### Templates & rendering
167 |
168 | Each component is rendered by its `render()` method, which must return a template. Templates are powered by [uhtml](https://github.com/WebReflection/uhtml), a performant, lightweight rendering library. No virtual DOM is used.
169 |
170 | To create a template, import the `html` function from the Shoemaker package and use it like so:
171 |
172 | ```ts
173 | class MyComponent extends Shoemaker {
174 | static tag = 'my-component';
175 |
176 | render() {
177 | return html`
178 |
179 |
181 | `
182 | }
183 | }
184 | ```
185 |
186 | If this syntax looks new to you, take a moment to read about [tagged templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to better understand how they work.
187 |
188 | Note: If your editor doesn't highlight the HTML in your templates, try using an extension such as [this one for VS Code](https://marketplace.visualstudio.com/items?itemName=bierner.lit-html).
189 |
190 | Note: By design, Shoemaker components _always_ contain a [shadow root](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) for encapsulation purposes, so to allow children you should include a [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) element. If you're not familiar with how custom element slots work, now is a good time to [study up on them](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots).
191 |
192 | #### Interpolation
193 |
194 | You can use interpolation to make templates dynamic. Let's take another look at our counter example. Notice how the count is displayed using `${this.count}`? That simply outputs the currently value of the `count` prop, and since `count` is also listed as one our our static props, every time it changes the component will automatically rerender.
195 |
196 | Also note how we're using `onclick` to watch for clicks. Although it looks the same, this isn't the standard `onclick` attribute. uthml interprets any `on` attribute as a listener and executes the associated expression when the event is emitted. Thus, clicking the button will increment `this.count` by one.
197 |
198 | ```ts
199 | class MyCounter extends Shoemaker {
200 | static tag = 'my-counter';
201 | static props = ['count'];
202 |
203 | count = 0;
204 |
205 | render() {
206 | return html`
207 |
208 | Count: ${this.count}
209 |
210 | `;
211 | }
212 | }
213 | ```
214 |
215 | Another way to write this is to split the expression into a separate function. This time, we remove the arrow function and append `.bind(this)` so it's called with the correct context. We're also adding the `event` argument so we can log the event as an example.
216 |
217 | ```ts
218 | class MyCounter extends Shoemaker {
219 | static tag = 'my-counter';
220 | static props = ['count'];
221 |
222 | count = 0;
223 |
224 | handleClick(event: MouseEvent) {
225 | this.count++;
226 | console.log(event);
227 | }
228 |
229 | render() {
230 | return html`
231 |
232 | Count: ${this.count}
233 |
234 | `;
235 | }
236 | }
237 | ```
238 |
239 | #### Passing properties
240 |
241 | Attributes can only store string values, so to pass arrays, objects, and non-scalar values you should pass them as a property using the `.` prefix. Imagine we have a `` element that accepts an array of colors for its `swatches` prop. Using the dot prefix will ensure it receives the array correctly.
242 |
243 | ```ts
244 | class MyComponent extends Shoemaker {
245 |
246 | // ...
247 |
248 | render() {
249 | const swatches = ['red', 'orange', 'yellow', 'green', 'blue', 'purple'];
250 |
251 | return html`
252 |
253 | `;
254 | }
255 | }
256 | ```
257 |
258 | #### Boolean attributes
259 |
260 | There's no such thing as boolean attributes in HTML, although we use them as such. Still, sometimes they're useful. Think of a `disabled` attribute with no value:
261 |
262 | ```html
263 |
305 | ...
306 |
307 | `;
308 | }
309 | }
310 | ```
311 |
312 | Any truthy value will add the class or style and any falsey value will remove it. This will render as:
313 |
314 | ```html
315 |
316 | ...
317 |
318 | ```
319 |
320 | #### More about templates
321 |
322 | There are some things you can't do in templates, such as using sparse attributes like `style="top:${x}; left${y}"` (instead, use ``style=${`top:${x}; left${y}`}``).
323 |
324 | I'll expand this section of the docs more later, but for now, refer to [uhtml's API docs](https://github.com/WebReflection/uhtml#api-documentation) for details.
325 |
326 | ### Lifecyle methods
327 |
328 | Shoemaker exposes intuitive lifecycle methods.
329 |
330 | - `onConnect()` - Called when the component is connected to the DOM and all properties are set, but before the first render. This is a good place to fetch data and do other pre-render init. At this point, the component's internals are not yet available in the DOM.
331 | - `onReady()` - Called after the first render.
332 | - `onDisconnect()` - Called when the component is disconnected from the DOM. This is a good place to cleanup listeners, observers, etc.
333 |
334 | ### Emitting events
335 |
336 | Use the `emit()` method to emit custom events. By convention, and for maximum compatibility with frameworks, custom event names should be lower-kebab-case. For example, use `my-click` instead of `myClick`.
337 |
338 | ```ts
339 | class MyEmit extends Shoemaker {
340 | static tag = 'my-emit';
341 |
342 | render() {
343 | return html`
344 |
345 | Click to emit an event
346 |
347 | `;
348 | }
349 | }
350 | ```
351 |
352 | The `emit()` method accepts an optional second argument of `CustomEventInit` options (default values shown):
353 |
354 | ```ts
355 | this.emit('my-click', {
356 | bubbles: true,
357 | cancelable: true,
358 | composed: true,
359 | detail: {
360 | /* this is where you can pass custom data to your event */
361 | }
362 | });
363 | ```
364 |
365 | ### Methods
366 |
367 | Define methods as you normally would on a class:
368 |
369 | ```ts
370 | class MyMethod extends Shoemaker {
371 | static tag = 'my-method';
372 |
373 | public announce() {
374 | alert('Hey!');
375 | }
376 |
377 | // ...
378 | }
379 | ```
380 |
381 | To access a method on the element:
382 |
383 | ```html
384 |