Reference

Bascik Scoping Compatibility

Legend

• ✓ Supported and tested
• △ Partially supported (see notes)
• ✕ Intentionally unsupported (see notes)
• – Not yet supported

CSS Scoping

CSS scoping applies to .css files paired with a component's HTML file. Place the .css file in the same directory as the component and give it the same base name.

Selectors

Other CSS Features

JavaScript Scoping

Bascik rewrites DOM selector references inside component <script> tags to match scoped attribute values. All rewrites happen at build time with no runtime is added.

IIFE Isolation

DOM Selector Rewriting

Notes on Gaps

The unsupported JS patterns above all involve dynamic attribute manipulation where static analysis cannot safely identify which component's attribute is being referenced from a string literal.

The recommended pattern is to query scoped elements by a single id or single-class selector first, store the reference, then use the reference for all further DOM operations:

<!-- source - works correctly -->
<div id="panel" class="card"></div>
<script>
  const panel = document.getElementById("panel"); // ← rewritten by Bascik
  panel.style.display = "none"; // ← operate on the reference
  panel.dataset.state = "closed"; // ← data attributes for state
</script>

Class queries are document-wide (not per-instance)

Class names are scoped to the component type, not to individual instances. This means querySelectorAll(".my-class") inside a component script, which Bascik rewrites to querySelectorAll(".bascik__comp__my-class"): will find matching elements across all instances of that component on the page, not just the current instance.

To operate only on the current instance's elements, query by id (which includes a per-instance hash) and traverse from the returned element:

// In component - gets only THIS instance's panel:
const panel = document.getElementById("panel"); // rewritten with instance hash

FormData with scoped name attributes

When a component uses <input name="username">, Bascik scopes the name attribute to a per-instance value like bascik__comp__a1b2c3__username. As a result, new FormData(form) entries use the scoped name as the key. If your server-side code expects the unscoped field name, you will need to adapt it, or extract values using formData.get with the scoped name, or via form.elements iteration.

Design Decisions & Known Non-Starters

Things that looked implementable but were deliberately left out, and why. Record these so we don't revisit the same dead ends.

CSS #id {} selector: first attempt rejected, now implemented

First attempt (failed): Used a simple lookahead /#([a-zA-Z][a-zA-Z0-9-_]*)(?=[\s{:,])/g. This incorrectly matched hex colour values in property position:

background: linear-gradient(#abc, #def)   /* ← comma triggered the match */
background: #abc url('./img.png')         /* ← space triggered the match */
color: #abc\n                             /* ← newline triggered the match */

Second attempt (current implementation, ✓): Changed to a context-aware lookahead:

/#([a-zA-Z][a-zA-Z0-9-_]*)(?=[^{};]*\{)/g

The key insight: in selector position the next { always appears before any ; or }. In value position (property declarations, gradient functions, etc.) a ; or } always appears before the next {. This reliably distinguishes the two contexts:

#btn { }                          → matches  (selector: { before ;/})
.parent #btn { }                  → matches  (compound selector)
@media (...) { #btn { } }         → matches  (nested selector)
color: #abc;                      → skipped  (value: ; before {)
linear-gradient(#abc, #def)        → skipped  (value: } closes rule before next {)
color: #abc\n}                    → skipped  (} terminates before {)

Remaining known edge case: A bare property declaration at the CSS file's top level (which is itself invalid CSS) could theoretically yield a false positive. This cannot occur in valid component CSS.

Implementation:convertCssIdSelectorsToClasses in styles.ts. The hash #id {} is converted to .bascik__comp__id__id {} and the generated class is injected onto the HTML element. Specificity drops from (0,1,0,0) to (0,0,1,0), which is acceptable and consistent with how element selectors are handled.

CSS comma-separated element selectors: now implemented

Same context-aware lookahead technique used for #id conversion. Adding ) to the lookahead stop set ([^{};)]*\{) prevents false positives inside :is(), :where(), :has() pseudo-functions, because the closing ) terminates the lookahead before { is reached:

div:is(p, h2) { }    →  h2 is after , but ) stops lookahead before { → skipped ✓
h1, h2 { }           →  h2 is after , ; then { before ;/}/} → MATCHES ✓
transition: color 0.2s, opacity 0.3s;  →  ; before { → skipped ✓

Pass 2 regex:/(?<=,[ \t]*)[a-z1-6]+(?=[^{};)]*\{)/g

Compound / descendant element selectors: partially implemented

Previously:.card p {} was ✕, p after a class was not converted, so the rule applied globally.

Now: A new Pass 4 in convertCssElementSelectorsToClasses handles element selectors that follow a scoped class name (with optional combinator):

/* Source: */
.card p { color: blue; }
.list > li { padding: 0; }
.article > h2 { font-size: 1.2rem; }

/* After bascik: */
.bascik__card .bascik__card__el__p { color: blue; }
.bascik__list > .bascik__list__el__li { padding: 0; }
.bascik__article > .bascik__article__el__h2 { font-size: 1.2rem; }

This works because the class-scoping pass runs first, writing the bascik__ prefix, which Pass 4 uses as a safe anchor. The bascik__ prefix never appears in CSS property value position.

Still not handled: bare element–element combinators (div p {}, p + p {}) with no class anchor on the left side. These still need a class to anchor against.

CSS nesting element selectors: partially implemented

Approach: The & character is exclusively a CSS nesting selector and never appears in property value position. This makes & (ampersand + whitespace) a safe anchor:

/(?<=&\s+(?:[>+~]\s+)?)[a-z1-6]+(?=[^{};)]*\{)/g

Handles: & p {}, & > h2 {}, & + li {}, & ~ span {}.

Not handled:& .parent p {} (element after class in nesting), &p {} (element directly appended to &). These require the combinator/whitespace anchor to precede the element.

CSS element.id property setter: not implemented

What was considered: Rewriting el.id = "my-id" to use the scoped ID name.

Why it was not implemented: The pattern \.id\s*=\s*["'] matches any property chain ending in .id, including el.dataset.id = "foo" (which sets a data-id attribute, not the DOM id). There is no reliable way to distinguish these cases with a regex.

The correct workaround: Use getElementById("my-id") to retrieve the element reference first, then work with the reference. Bascik rewrites getElementById correctly. Avoid assigning el.id from a scoped ID value in component scripts.

What "Scoped" Means

Class attributes are scoped to the component type (name only). All instances of the same component on a page share the same scoped class names, which allows CSS to be deduplicated to a single <style> block.

ID and name attributes are scoped per component instance (name + unique instance ID) so that multiple instances on the same page have distinct DOM identifiers.

class  →  bascik__<componentName>__<originalName>
id     →  bascik__<componentName>__<instanceId>__<originalName>
name   →  bascik__<componentName>__<instanceId>__<originalName>

With obfuscateAttributeNames: true (the default in production builds), these verbose names are hashed to short hex strings (e.g. ba1b2c3d). The HTML, CSS, and JavaScript are all updated with the same scoped names so they stay in sync.

This is a build-time transformation: no JavaScript is loaded at runtime to manage scoping. The output is plain HTML.