JavaScript

50 files, no framework, no build step, and a component system nobody has written down. This is the most original and least documented convention in the estate, and reconstructing it by counting is most of what the survey behind this page did.

1. The complete example

/**
 * sg-compute-left-nav — vertical icon-rail navigation for the admin dashboard.
 *
 * Items: Compute / Storage / Settings / Diagnostics.
 * Click fires sp-cli:nav.selected { view } on document.
 *
 * @module sg-compute-left-nav
 * @version 0.1.0
 */

import { SgComponent } from 'https://dev.tools.sgraph.ai/components/base/v1/v1.0/v1.0.0/sg-component.js'

class SgComputeLeftNav extends SgComponent {

    static jsUrl = import.meta.url
    get resourceName()   { return 'sg-compute-left-nav' }
    get sharedCssPaths() { return ['https://dev.tools.sgraph.ai/components/tokens/v1/v1.0/v1.0.0/sg-tokens.css'] }

    onReady() {
        this._current = 'compute'
        this.shadowRoot.querySelectorAll('.nav-item').forEach(btn => {
            btn.addEventListener('click', () => this._select(btn.dataset.view))
        })
        this._update()
    }

    _select(view) {
        if (view === this._current) return
        this._current = view
        this._update()
        document.dispatchEvent(new CustomEvent('sp-cli:nav.selected', {
            detail:  { view },
            bubbles: true, composed: true,
        }))
    }

    _update() {
        this.shadowRoot.querySelectorAll('.nav-item').forEach(btn => {
            btn.classList.toggle('selected', btn.dataset.view === this._current)
            btn.setAttribute('aria-current', btn.dataset.view === this._current ? 'page' : 'false')
        })
    }
}

customElements.define('sg-compute-left-nav', SgComputeLeftNav)

2. The component system

Native web components. 41 customElements.define calls across 50 files. No React, no Vue, no bundler, no build step. The browser is the runtime.

The three-file triplet

Every component is exactly three files, same basename, same directory:

sg-compute-left-nav.js      behaviour
sg-compute-left-nav.html    markup
sg-compute-left-nav.css     styles

static jsUrl = import.meta.url is what makes this work: the component knows its own URL, so the base class can fetch the sibling .html and .css without anything being told where they live.

Self-locating components are the mechanism that removes the build step.

The versioned CDN path

https://dev.tools.sgraph.ai/components/<name>/v1/v1.0/v1.0.0/<file>.js
                                              ^^^ ^^^^ ^^^^^^
                                            major minor patch — as directories

Three nested directories, one per semver level. A consumer pins at whatever depth it wants stability: /v1/ follows the major, /v1.0/ follows the minor, /v1.0.0/ is frozen. Immutable URLs, no lockfile, no node_modules, cacheable forever. The same scheme is used locally under components/.

What the CDN serves today: SgComponent (the base class), sg-tokens.css (design tokens), sg-vault-client.js and sg-vault-write.js.

The base-class contract

SgComponent supplies the lifecycle; a component overrides four things:

onReady() rather than connectedCallback is the tell. The base class handles the async fetch of the sibling files and calls onReady() once the shadow root is populated, so a component never has to think about whether its markup has arrived. It is a small API decision that removes a whole class of race condition, and it is exactly the kind of thing a lint rule should enforce. The rule that would →

6 files call attachShadow directly; the rest inherit it from the base class, and every component addresses its own markup through this.shadowRoot.

3. Formatting, measured

4. Events, state and data

Events are namespaced and go through document:

document.dispatchEvent(new CustomEvent('sp-cli:nav.selected', {
    detail:  { view },
    bubbles: true, composed: true,
}))

bubbles: true, composed: true is what lets an event escape the shadow root. The namespace is sp-cli: — the old CLI name — and it appears in 23 files. That is a rename surface nobody had counted, and renaming an event namespace is a breaking change for any listener outside the repository.

State is instance fields, _-prefixed, set in onReady(). No store, no observable, no framework state layer. Cross-component state goes through the event bus and through purpose-built shared modules — settings-bus.js, vault-bus.js, poll.js.

Constants are frozen and centralised

// ── launch-defaults.js — canonical launch constants ────────────────────────── //
// Single source of truth. Both sg-compute-compute-view and sg-compute-launch-form
// import from here. Update here only — do not duplicate locally.

export const REGIONS = Object.freeze([
    'eu-west-2', 'us-east-1', 'ap-southeast-1', 'eu-west-1', 'us-west-2',
])

Object.freeze on every exported constant, and a comment that names the consumers and forbids local duplication. That is the same single source of truth instinct that drives manifest.py and the repo-root version file, expressed with a mechanism rather than a request. The pattern →

5. Why “no build step” is the interesting claim

It is worth arguing rather than just reporting, because it is a real trade with a real breaking point.

Where it stops working is the honest part: at the point you need a dependency graph deeper than one level, or a package that only ships as CommonJS. Neither has happened yet in 50 files, which is not the same as neither happening. Q7 →

6. What to fix before this becomes a standard

Four inconsistencies, in the order they should be settled. All four are cheap, and none of them can be settled by a site — they need a decision.

1. Semicolons. components/ is semicolon-free; shared/ is not. Pick one — the newer tree suggests dropping them — and write the config.
2. Two banner styles. JSDoc on components, // ── on shared modules. Pick one per file type and say which.
3. The sp-cli: event namespace is legacy naming in 23 files. Rename it with the rest, and note that it is a breaking change for external listeners.
4. _private in JavaScript versus Python rule 9. State that rule 9 is Python-only, or change one of the two. Right now it is neither enforced nor retired. Q2 →