Skip to content

Commit

Permalink
Merge pull request #23 from efflore/v0.8.5-docs
Browse files Browse the repository at this point in the history 
docs: update example on installation & setup page
  • Loading branch information
@estherbrunner
estherbrunner authored Oct 5, 2024
2 parents 0085a51 + 2adfef4 commit 78c87d0
Show file tree
Hide file tree
Showing 12 changed files with 718 additions and 561 deletions.
6 changes: 6 additions & 0 deletions docs/assets/css/components.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,17 @@ my-counter {
p {
display: inline-block;
margin: 0;
flex: 1;
}

span {
margin-right: 0.5rem;
}

button {
padding: 0.25rem 0.5rem;
flex: 0;
}
}

code-block {
Expand Down
2 changes: 1 addition & 1 deletion docs/assets/js/main.min.js
View file

Large diffs are not rendered by default.

32 changes: 14 additions & 18 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,9 +108,7 @@ <h1>📘 Introduction</h1>

<section>
<h2>What is UIElement?</h2>
<p>
<strong>UIElement</strong> is a lightweight JavaScript library that extends the native <code>HTMLElement</code> class to bring efficient state management and reactivity to your Web Components without client-side rendering or the overhead of a larger framework.
</p>
<p><strong>UIElement</strong> is a lightweight JavaScript library that extends the native <code>HTMLElement</code> class to bring efficient state management and reactivity to your Web Components without client-side rendering or the overhead of a larger framework.</p>
<ul>
<li><strong>Minimalist & Lightweight</strong>: Only what you need to manage state and reactivity.</li>
<li><strong>Signals-Based Reactivity</strong>: Fine-grained updates based on state changes.</li>
Expand Down Expand Up @@ -147,15 +145,11 @@ <h2>When Should You Use UIElement?</h2>

<section>
<h2>How UIElement Works</h2>
<p>
UIElement relies on signals—small pieces of reactive state that notify your components when changes occur. This allows for efficient updates to HTML content, handling reactivity only when necessary.
</p>
<p>
<strong>Signals & Auto-Effects:</strong> Signals automatically trigger updates to the DOM when they change.
</p>
<p>UIElement relies on signals—small pieces of reactive state that notify your components when changes occur. This allows for efficient updates to HTML content, handling reactivity only when necessary.</p>
<p><strong>Signals & Auto-Effects:</strong> Signals automatically trigger updates to the DOM when they change.</p>
<code-block language="js">
<pre><code class="language-js">this.set('count', 0); // Define a signal for 'count'
this.first('.count').map(setText('count')); // Automatically update content when 'count' changes</code></pre>
this.first('.count').forEach(setText('count')); // Automatically update content when 'count' changes</code></pre>
</code-block>
</section>

Expand All @@ -178,7 +172,7 @@ <h2>Quick Start Guide</h2>
Count: <span class="count"></span>
Parity: <span class="parity"></span>
</p>
<button class="decrement">-</button>
<button class="decrement">−</button>
<button class="increment">+</button>
</my-counter>
</div>
Expand Down Expand Up @@ -209,7 +203,7 @@ <h2>Quick Start Guide</h2>
Parity: &lt;span class="parity"&gt;&lt;/span&gt;
&lt;/p&gt;
&lt;button id="increment"&gt;+&lt;/button&gt;
&lt;button id="decrement"&gt;-&lt;/button&gt;
&lt;button id="decrement"&gt;−&lt;/button&gt;
&lt;/my-counter&gt;</code></pre>
<input-button class="copy">
<button type="button" class="secondary small">Copy</button>
Expand All @@ -235,11 +229,17 @@ <h2>Quick Start Guide</h2>
p {
display: inline-block;
margin: 0;
flex: 1;
}

span {
margin-right: 0.5rem;
}

button {
padding: 0.25rem 0.5rem;
flex: 0;
}
}</code></pre>
<input-button class="copy">
<button type="button" class="secondary small">Copy</button>
Expand Down Expand Up @@ -284,16 +284,12 @@ <h2>Quick Start Guide</h2>
</details>
</accordion-panel>
</component-demo>
<p>
For a full setup, see the <a href="installation-setup.html">Installation & Setup</a> page, or jump into the <a href="detailed-walkthrough.html">Detailed Walkthrough</a> to learn how to build your first component.
</p>
<p>For a full setup, see the <a href="installation-setup.html">Installation & Setup</a> page, or jump into the <a href="detailed-walkthrough.html">Detailed Walkthrough</a> to learn how to build your first component.</p>
</section>

<section>
<h2>Next Steps</h2>
<p>
Continue to the <a href="installation-setup.html">Installation & Setup</a> to get started, or dive into <a href="core-concepts.html">Core Concepts</a> to learn more about signals and reactivity.
</p>
<p>Continue to the <a href="installation-setup.html">Installation & Setup</a> to get started, or dive into <a href="core-concepts.html">Core Concepts</a> to learn more about signals and reactivity.</p>
</section>
</main>
</body>
Expand Down
123 changes: 67 additions & 56 deletions docs/installation-setup.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,25 +103,19 @@ <h1 class="content">UIElement Docs <small>Version 0.8.5</small></h1>
<main>
<section class="hero">
<h1>⚙️ Installation & Setup</h1>
<p class="lead">
Get started with <strong>UIElement</strong> by including it directly in your HTML or installing it via npm. Follow the steps below to set up your environment and start building reactive Web Components.
</p>
<p class="lead">Get started with <strong>UIElement</strong> by including it directly in your HTML or installing it via npm. Follow the steps below to set up your environment and start building reactive Web Components.</p>
</section>

<section>
<h2>Using a CDN</h2>
<p>
For the easiest setup, include <strong>UIElement</strong> directly in your HTML via a CDN. This is ideal for quick projects or testing.
</p>
<p>For the easiest setup, include <strong>UIElement</strong> directly in your HTML via a CDN. This is ideal for quick projects or testing.</p>
<code-block>
<pre><code>&lt;script src="https://cdn.jsdelivr.net/npm/@efflore/ui-element@latest/index.min.js"&gt;&lt;/script&gt;</code></pre>
</code-block>
<p>
Or use <code>&lt;script type="module"&gt;</code> to import UIElement in your HTML:
</p>
<code-block>
<pre><code>&lt;script type="module"&gt;
import { UIElement } from 'https://cdn.jsdelivr.net/npm/@efflore/ui-element@latest/index.min.js';
<p>Or use <code>&lt;script type="module"&gt;</code> to import UIElement in your HTML:</p>
<code-block language="js">
<pre><code class="language-js">&lt;script type="module"&gt;
import { UIElement } from 'https://cdn.jsdelivr.net/npm/@efflore/ui-element@latest/index.min.js'

// Your code here
&lt;/script&gt;</code></pre>
Expand All @@ -130,61 +124,80 @@ <h2>Using a CDN</h2>

<section>
<h2>Using a Self-Hosted Copy</h2>
<p>
You can include the built UIElement script from a local or hosted path if you prefer to self-host the script. The latest version is available in the Github Repo under <a href="https://github.com/efflore/ui-element/blob/main/index.min.js" target="_blank">https://github.com/efflore/ui-element/blob/main/index.min.js</a>
</p>
<p>
Remember to keep the hosted file updated to use the latest features and bug fixes.
</p>
<p>You can include the built UIElement script from a local or hosted path if you prefer to self-host the script. The latest version is available in the Github Repo under <a href="https://github.com/efflore/ui-element/blob/main/index.min.js" target="_blank">https://github.com/efflore/ui-element/blob/main/index.min.js</a></p>
<p>Remember to keep the hosted file updated to use the latest features and bug fixes.</p>
</section>

<section>
<h2>Installing with NPM</h2>
<p>
If you are using a bundler like Vite, Rollup, Webpack, or another module system, npm is the best way to install and manage <strong>UIElement</strong>.
</p>
<pre><code>npm install @efflore/ui-element</code></pre>
<p>
Then import <code>UIElement</code> in your JavaScript:
</p>
<p>If you are using a bundler like Vite, Rollup, Webpack, or another module system, npm is the best way to install and manage <strong>UIElement</strong>.</p>
<code-block>
<pre><code>import { UIElement } from '@efflore/ui-element';</code></pre>
<pre><code>npm install @efflore/ui-element</code></pre>
</code-block>
<p>Then import <code>UIElement</code> in your JavaScript:</p>
<code-block language="js">
<pre><code class="language-js">import { UIElement } from '@efflore/ui-element';</code></pre>
</code-block>
<p>
Use build tools to bundle the library into your project as necessary.
</p>
<p>Use build tools to bundle the library into your project as necessary.</p>
</section>

<section>
<h2>Creating Your First Component</h2>
<p>
Let's verify your setup by creating an interactive <code>HelloWorld</code> component that updates based on user input.
</p>
<pre><code>class HelloWorld extends UIElement {
connectedCallback() {
// Update content dynamically based on the 'name' signal
this.first('.greeting').map(setText('name'));

// Handle user input to change the 'name'
this.first('input').map(on('input', event =&gt; this.set('name', event.target.value)));
}
}
HelloWorld.define('hello-world');</code></pre>
<p>
Include it in your HTML (server-rendered):
</p>
<pre><code>&lt;hello-world&gt;
&lt;label for="name-input"&gt;Your name&lt;/label&gt;
&lt;input type="text" id="name-input" /&gt;
&lt;p&gt;Hello, &lt;span class="greeting"&gt;World&lt;/span&gt;!&lt;/p&gt;
&lt;/hello-world&gt;</code></pre>
<p>Let's verify your setup by creating an interactive <code>HelloWorld</code> component that updates based on user input.</p>
<code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!">
<p class="meta">
<span class="language">js</span>
</p>
<pre><code class="language-js">&lt;script type="module"&gt;
import { UIElement, setText, on } from 'https://cdn.jsdelivr.net/npm/@efflore/ui-element@latest/index.min.js'

class HelloWorld extends UIElement {
connectedCallback() {

// Update content dynamically based on the 'name' signal
this.first('span').forEach(setText('name'))

// Handle user input to change the 'name'
this.first('input').forEach(on('input', e =&gt; this.set('name', e.target.value)))
}
}
HelloWorld.define('hello-world')
&lt;/script&gt;</code></pre>
<input-button class="copy">
<button type="button" class="secondary small">Copy</button>
</input-button>
</code-block>
<p>Include the above in your HTML (server-rendered), together with this snippet:</p>
<code-block language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!">
<p class="meta">
<span class="language">html</span>
</p>
<pre><code>&lt;hello-world&gt;
&lt;label&gt;Your name
&lt;input type="text"&gt;
&lt;/label&gt;
&lt;p&gt;Hello, &lt;span&gt;World&lt;/span&gt;!&lt;/p&gt;
&lt;/hello-world&gt;</code></pre>
<input-button class="copy">
<button type="button" class="secondary small">Copy</button>
</input-button>
</code-block>
</section>

<section>
<h2>Verifying Installation</h2>
<p>
To verify your setup:
</p>
<p>The result should look similar to this:</p>
<component-demo>
<div class="preview">
<hello-world>
<label>Your name
<input type="text">
</label>
<p>Hello, <span>World</span>!</p>
</hello-world>
</div>
</component-demo>
<p>To verify your setup:</p>
<ul>
<li><strong>CDN & Self-Hosted Users</strong>: Check the browser console for any script loading errors and ensure typing in the input field updates the greeting.</li>
<li><strong>NPM Users</strong>: Ensure <code>node_modules</code> contains <code>@efflore/ui-element</code> and your bundler correctly bundles the library.</li>
Expand All @@ -193,9 +206,7 @@ <h2>Verifying Installation</h2>

<section>
<h2>Next Steps</h2>
<p>
Now that you've set up <strong>UIElement</strong>, you're ready to dive deeper into building reactive Web Components. Check out the <a href="core-concepts.html">Core Concepts</a> page to learn more about signals and reactivity, or proceed to the <a href="detailed-walkthrough.html">Detailed Walkthrough</a> for building more advanced components.
</p>
<p>Now that you've set up <strong>UIElement</strong>, you're ready to dive deeper into building reactive Web Components. Check out the <a href="core-concepts.html">Core Concepts</a> page to learn more about signals and reactivity, or proceed to the <a href="detailed-walkthrough.html">Detailed Walkthrough</a> for building more advanced components.</p>
</section>
</main>

Expand Down
17 changes: 13 additions & 4 deletions docs/main.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,22 @@ class MyCounter extends UIElement {

connectedCallback() {
this.set('parity', () => this.get('count') % 2 ? 'odd' : 'even')
this.first('.increment').map(on('click', () => this.set('count', v => ++v)))
this.first('.decrement').map(on('click', () => this.set('count', v => --v)))
this.first('.count').map(setText('count'))
this.first('.parity').map(setText('parity'))
this.first('.increment').forEach(on('click', () => this.set('count', v => ++v)))
this.first('.decrement').foEach(on('click', () => this.set('count', v => --v)))
this.first('.count').forEach(setText('count'))
this.first('.parity').forEach(setText('parity'))
}
}
MyCounter.define('my-counter')

class HelloWorld extends UIElement {
connectedCallback() {
this.first('span').forEach(setText('name'))
this.first('input').forEach(on('input', e => this.set('name', e.target.value)))
}
}
HelloWorld.define('hello-world')

class CodeBlock extends UIElement {
static observedAttributes = ['collapsed']
static attributeMap = {
Expand Down Expand Up @@ -434,6 +442,7 @@ const MEDIA_MOTION = 'media-motion'
const MEDIA_THEME = 'media-theme'
const MEDIA_VIEWPORT = 'media-viewport'
const MEDIA_ORIENTATION = 'media-orientation'

class MediaContext extends UIElement {
static providedContexts = [MEDIA_MOTION, MEDIA_THEME, MEDIA_VIEWPORT, MEDIA_ORIENTATION]

Expand Down
Loading

0 comments on commit 78c87d0

Please sign in to comment.