What it is, and why it exists

/**
 * Counter - `observable`, `computed`, `effect`, and what "fine-grained" means.
 *
 * Three bindings read `count`. Pressing +1 re-runs those three and nothing
 * else on the page, because each binding owns its own effect and each effect
 * knows exactly what it read.
 */
function counter() {
    const count = observable(0);
    const runs = observable(0);

    // A computed works out its own inputs at runtime. Neither of these is told
    // that it depends on `count`; both discover it by reading it.
    const doubled = computed(() => count.value * 2);
    const parity = computed(() => (count.value % 2 === 0 ? 'even' : 'odd'));

    // An effect is the same machinery pointed at a side effect. `peek()` reads
    // without subscribing - reading `runs.value` here would make this effect
    // depend on its own write and spin forever.
    effect(() => {
        count.value;
        runs.value = runs.peek() + 1;
    });

    return {
        count, doubled, parity, runs,
        step(by) { count.value += by; },
        reset() { count.value = 0; }
    };
}

/**
 * Two-way binding, with no change handler anywhere.
 *
 * Text, number, radio group, checkbox and a `<select>` populated by
 * `data-options` all write straight back into the view model; `data-focus`
 * reports where the caret is. The JSON panel is a `computed` reading the same
 * observables the inputs write to, so it cannot disagree with them.
 */
function bindings() {
    const person = {
        name: observable('Ada Lovelace'),
        age: observable(36),
        town: observable('Harrogate'),
        contact: observable('email'),
        newsletter: observable(false)
    };

    const focused = observable(false);

    return {
        person,
        focused,
        towns: ['Harrogate', 'Knaresborough', 'Ripon', 'Wetherby', 'Otley', 'Ilkley'],

        asJson: computed(() => JSON.stringify({
            name: person.name.value,
            age: person.age.value,
            town: person.town.value || null,
            contact: person.contact.value,
            newsletter: person.newsletter.value
        }, null, 2))
    };
}

<div class="demo-stage demo-split">
    <div class="demo-form">
        <label class="form-label">Name
            <input class="form-input" data-model="person.name.value" data-focus="focused.value">
        </label>

        <label class="form-label">Age
            <input class="form-input" type="number" min="0" max="120" data-model="person.age.value">
        </label>

        <label class="form-label">Home town
            <select class="form-select" data-model="person.town.value" data-options="towns" data-options-caption="'Anywhere'"></select>
        </label>

        <fieldset class="demo-fieldset">
            <legend>Contact by</legend>
            <label><input type="radio" name="contact" value="email" data-model="person.contact.value"> Email</label>
            <label><input type="radio" name="contact" value="phone" data-model="person.contact.value"> Phone</label>
            <label><input type="radio" name="contact" value="post" data-model="person.contact.value"> Post</label>
        </fieldset>

        <label class="demo-switch">
            <input type="checkbox" data-model="person.newsletter.value"> Send me the newsletter
        </label>
    </div>

    <div class="demo-mirror">
        <p class="demo-mirror-title">The view model, live</p>
        <pre class="demo-json" data-bind-text="asJson.value">{}</pre>
        <p class="demo-note">Caret in the name field: <b data-bind-text="focused.value">false</b></p>
        <p class="demo-note" data-if="person.newsletter.value">Thank you. Nothing is actually sent.</p>
    </div>
</div>

/**
 * The smallest list app anyone actually writes: add, tick off, delete, with a
 * derived summary and an empty state.
 *
 * `done: observable(false)` is the line worth staring at. `observableArray`
 * tracks the array - pushes, removes, reorders - not the fields inside its
 * items. A plain `done: false` would tick in the DOM and change nothing else.
 */
function todo() {
    const todos = observableArray([
        {id: 1, title: 'Read the twelve bindings', done: observable(true)},
        {id: 2, title: 'Bind a form with no change handler', done: observable(false)},
        {id: 3, title: 'Delete a row and watch the others keep their DOM', done: observable(false)}
    ]);

    const draft = observable('');
    const composing = observable(false);
    let nextId = 4;

    return {
        todos,
        draft,
        composing,

        ready: computed(() => draft.value.trim() !== ''),

        summary: computed(() => {
            const all = todos.value;
            const left = all.filter(t => !t.done.value).length;
            return `${left} of ${all.length} left`;
        }),

        add() {
            if (draft.value.trim() === '') return;
            todos.push({id: nextId++, title: draft.value.trim(), done: observable(false)});
            draft.value = '';
            composing.value = true;      // put the caret back in the field
        },

        // Inside a list `$data` is the item, so a row reaches the list that
        // owns it through `$parent` - `data-on-click="$parent.remove($data)"`.
        remove(item) { todos.remove(item); }
    };
}

/**
 * Two components over one host element, and a slot the page fills.
 *
 * `data-component` takes an expression: point it at an observable and the
 * rendered component follows the value. The old instance is disposed - view
 * model first, then its effects, then its nodes - and the new one is built
 * with the params re-evaluated. The projected slot content is not rebuilt; it
 * is the same DOM, moved.
 */
registerComponent('team-card', {
    template: `
        <article class="demo-card">
            <h4 data-bind-text="$data.heading"></h4>
            <p class="demo-card-name">{{person.name.value}}</p>
            <p class="demo-card-role">{{person.title.value}}, since {{person.since.value}}</p>
            <button class="btn btn-sm" data-on-click="celebrate" data-bind-text="cheer.value"></button>
            <footer>{{#slot footer}}<small>No footer was supplied.</small>{{/slot}}</footer>
        </article>`,

    create(params) {
        // `cheer` belongs to this instance. Swap the component away and back and
        // it starts again from scratch, because the instance is a new one.
        const cheer = observable('Say something nice');
        return {
            heading: params.heading,
            person: params.person,
            cheer,
            celebrate() { cheer.value = `Well done, ${params.person.name.value}`; }
        };
    }
});

registerComponent('stat-card', {
    template: `
        <article class="demo-card demo-card--stat">
            <h4 data-bind-text="$data.heading"></h4>
            <dl class="demo-facts">
                <div><dt>Role</dt><dd>{{person.title.value}}</dd></div>
                <div><dt>Since</dt><dd>{{person.since.value}}</dd></div>
                <div><dt>Years</dt><dd>{{years.value}}</dd></div>
            </dl>
            <footer>{{#slot footer}}<small>No footer was supplied.</small>{{/slot}}</footer>
        </article>`,

    create(params) {
        return {
            heading: params.heading,
            person: params.person,
            years: computed(() => 2026 - Number(params.person.since.value))
        };
    }
});

function componentDemo() {
    // Params pass by reference when the expression names the observable, so
    // both components see this promotion - the page and the component are
    // reading the same cell, not two copies of a value.
    const person = {
        name: observable('Ada Lovelace'),
        title: observable('Analyst'),
        since: observable(2019)
    };

    const view = observable('team-card');
    const ranks = ['Analyst', 'Senior Analyst', 'Principal', 'Head of Numbers'];

    return {
        person,
        view,
        show(name) { view.value = name; },
        promote() {
            const next = ranks.indexOf(person.title.value) + 1;
            person.title.value = ranks[Math.min(next, ranks.length - 1)];
        }
    };
}