v4

[titouanmathis]

Vision

v3: a micro-framework for writing JS components.
v4: a toolkit of HTML-first meta-components for adding interactivity.

HTML becomes the primary interface. Custom JS is only needed for complex cases (Slider, Drag, etc.). Meta-components (Action, Fetch, DataBind, Transition) cover 80% of use cases directly from markup.

Principles:

• 0 runtime dependencies
• HTML-first, progressive enhancement, Light DOM
• What the browser does natively, we do not reimplement
• The registry is the catalog of components available to HTML

---

Architectural changes

$emit — bubbling events (#630)

$emit dispatches a standard CustomEvent with bubbles: true and an __source property referencing the emitting instance:

$emit(event, ...args) {
  const e = new CustomEvent(event, { bubbles: true, detail: args });
  e.__source = this;
  this.$el.dispatchEvent(e);
}

• Events bubble up the DOM natively — enables event delegation
• __source identifies the emitting instance for on{Child}{Event} resolution
• Action keeps working as-is — data-on:fetch-before listens to fetch-before which bubbles normally
• $on / $off keep working as-is — direct listener on $el

on{Child}{Event} — event delegation

The parent listens on this.$el instead of binding on each child. The handler walks up from event.target to this.$el, looking for mounted instances.

handler(event) {
  let el = event.target;
  while (el && el !== this.$el) {
    if (el.__base__) {
      for (const [name, instance] of el.__base__) {
        if (instance === "terminated") continue;
        const method = `on${name}${pascalCase(event.type)}`;
        if (typeof this[method] === "function") {
          this[method]({ event, target: instance });
          return;
        }
      }
    }
    el = el.parentElement;
  }
}

• el.__base__ is a Map<string, Base> keyed by config.name (already implemented on develop)
• Dynamically added children work automatically (no binding/unbinding needed)
• The parent still needs config.components to know which events to listen to (resolving method name ambiguity: onSliderDragStart → SliderDrag + Start)
• mouseenter/mouseleave do not bubble — these keep direct binding on the child element (accepted limitation)

$parent → $closest(name)

$parent is removed. Replaced by an explicit query:

// v3
this.$parent.goNext();

// v4
this.$closest("Slider").goNext();

$children → $query(name)

// v3
for (const item of this.$children.SliderItem) { ... }

// v4
for (const item of this.$query("SliderItem")) { ... }

Sugar for queryComponentAll(name, { from: this.$el }) (already implemented as helper, #629).

createApp removed

The registry + MutationObserver handle everything. Features are configured separately (#691):

// v4
import { defineFeatures, registerComponent } from "@studiometa/js-toolkit";
defineFeatures({ breakpoints: { ... } });
registerComponent(MyComponent);

No root "App" component required. Each component is independent.

SafeAction — CSP-safe declarative commands

New component alongside Action. No new Function(), just declarative method calls:

<!-- Action (CSP-unsafe, kept for backwards compat) -->
<button data-component="Action" data-on:click="Modal->target.open()">

<!-- SafeAction (CSP-safe, recommended) -->
<button data-component="SafeAction" data-on:click="Modal.open">
<button data-component="SafeAction" data-on:click="Modal(#my-modal).open">
<button data-component="SafeAction" data-on:click="Modal(.sidebar).close">

Format: Component[(selector)].method — parsed with a simple regex, resolved via the registry.

---

Breaking changes

• Make custom events bubble up by default with __source annotation ([Feature] Enable bubbling and cancelation for custom events #630)
• Refactor EventsManager — event delegation on this.$el instead of binding on each child
• Remove createApp (replaced by registerComponent + defineFeatures)
• Remove $parent property (replaced by $closest(name))
• Remove $root property
• Remove $children property (replaced by $query(name))
• Remove LoadService
• Remove KeyService
• Remove ability to configure the blocking feature
• Maybe remove prefix and attributes feature configuration (to reduce size)
• Update default breakpoints to match @studiometa/tailwind-config
• Make ResponsiveOptionsManager the default
• Config merge strategy for refs ([Base] Maybe improve config merge strategy? #627) — merge by default instead of override

New features

• $query(name) — scoped descendant instance query on Base
• $closest(name) — ancestor instance lookup on Base
• defineFeatures() helper ([Features] Features should be configurable outside of the createApp helper #691)
• SafeAction component — CSP-safe declarative commands
• Multiple option types ([Base] Add support for multiple option type #651)
• Sibling configuration config.use ([Feature] Add support for sibling configuration #697)
• Component tree inspector / DX improvements (Improve DX #653)

Meta-components integrated into core

Some components from @studiometa/ui are promoted to the core framework:

• Action — event → JS expression on a target (CSP-unsafe)
• SafeAction — event → declarative command on a target (CSP-safe)
• Fetch — HTTP request → DOM swap
• Transition — enter/leave animations
• DataBind, DataModel, DataEffect, DataComputed — reactive data binding

UI components removed (replaced by web platform)

These components no longer need to exist in @studiometa/ui:

Component	Native replacement
Modal	<dialog> + showModal() + Invoker Commands (commandfor)
Accordion / AccordionItem	<details> + <summary>
AnchorScrollTo	scroll-behavior: smooth + <a href="#id">
Sticky	position: sticky
Figure	loading="lazy"
Hoverable	CSS :hover + :has()
Prefetch	<link rel="prefetch"> + Speculation Rules API
Sentinel	IntersectionObserver (trivial)

Services

Service	v4 status
RafService	✅ Keep — read/write scheduling has no native equivalent
DragService	✅ Keep — custom drag + inertia has no native equivalent
ScrollService	✅ Keep — aggregation + throttle still useful
ResizeService	⚠️ Simplify — recommend ResizeObserver
PointerService	⚠️ Simplify
LoadService	🗑 Remove
KeyService	🗑 Remove
MutationService	⚠️ Internal use only (registry)

---

Already done on develop (v3.4.x)

• ✅ registerComponent() helper ([Feature] Add support for a registry #683, [Feature] Add support for custom name or selector to register a component #676)
• ✅ Global registry with MutationObserver auto-mount
• ✅ __base__ is a Map<string, Base> keyed by config.name
• ✅ $parent resolved dynamically via getInstances() + findClosestInstance() ([Bugfix] Refactor $parent to work with the new registry  #700, [Bug] The $parent property might not be defined with the new registry #699)
• ✅ addToRegistry() recursively registers config.components children ([Base] Children component should be registered with registerComponent #690, [Bugfix] Add child components to the registry #692)
• ✅ createApp simplified (no internal MutationObserver — registry handles it)
• ✅ queryComponent / queryComponentAll helpers ([Feature] Add a queryComponent helper function #629)
• ✅ Auto-update when DOM changes via MutationObserver ([Base] Add support for auto-updating a component when its DOM changes #562)

Migration path

Phase 1 — v3.x (non-breaking)

• Add $query() and $closest() as methods on Base
• Add defineFeatures() helper ([Features] Features should be configurable outside of the createApp helper #691)
• Deprecation warnings on $parent, $children, $root

Phase 2 — v4 (breaking)

• $emit with bubbles: true + __source ([Feature] Enable bubbling and cancelation for custom events #630)
• Event delegation in EventsManager
• Remove $parent, $root, $children
• Remove createApp
• Remove LoadService, KeyService
• Integrate Action, SafeAction, Fetch, Transition, Data* into core
• Config merge strategy for refs ([Base] Maybe improve config merge strategy? #627)
• Multiple option types ([Base] Add support for multiple option type #651)
• Sibling configuration config.use ([Feature] Add support for sibling configuration #697)

[titouanmathis]

v4 Framework Setup Spec Draft

Goal

v4 should reduce framework complexity, move closer to the web platform, and make Studio Meta components easy to use in existing projects without heavy build tooling.

Primary target use case:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Lazy,Figure,Slider"></script>

<ui-slider>
  ...
</ui-slider>

<ui-figure>
  ...
</ui-figure>

v4 should feel like adding platform-native behavior to HTML, not adopting a full JavaScript framework.

---

1. Guiding principles

• Zero runtime dependencies.
• HTML-first.
• Progressive enhancement.
• Light DOM only, no Shadow DOM by default.
• Keep Base as the component authoring model.
• Use Web Components as the mounting/lifecycle primitive.
• Use directives for small attachable behaviors.
• No required app root.
• No required bundler.
• No required createApp.
• Compatible with server-rendered HTML.
• Easy to add to inherited projects: WordPress, Shopify, PrestaShop, Twig, Blade, static HTML, etc.

---

2. Components

2.1 Components are custom elements

v3:

<div data-component="FigureShopify">
  ...
</div>

v4:

<ui-figure-shopify>
  ...
</ui-figure-shopify>

The custom element tag is generated from the component config.name.

class FigureShopify extends Base {
  static config = {
    name: 'FigureShopify',
  };
}

Default generated tag:

ui-figure-shopify

2.2 Prefix configuration

The custom element prefix is configurable at framework level:

defineFeatures({
  prefix: 'ui',
});

Examples:

defineFeatures({ prefix: 'ui' });
// <ui-slider>

defineFeatures({ prefix: 'meta' });
// <meta-slider>

2.3 Components still extend Base

Authors should continue writing:

class Slider extends Base {
  static config = {
    name: 'Slider',
  };

  next() {}
  previous() {}
}

Not:

class Slider extends HTMLElement {}

Internally, the toolkit creates a custom element wrapper.

Conceptual implementation:

class ToolkitCustomElement extends HTMLElement {
  connectedCallback() {
    this.__base = new Component(this);
    this.__base.$mount();
  }

  disconnectedCallback() {
    this.__base?.$terminate();
  }
}

2.4 No Shadow DOM

Components use Light DOM.

<ui-slider>
  <div>Slide 1</div>
  <div>Slide 2</div>
</ui-slider>

CSS from the host project should keep working normally.

---

3. Component registration

3.1 Basic registration

import { registerComponent } from '@studiometa/js-toolkit';
import Slider from './Slider.js';

registerComponent(Slider);

This defines:

<ui-slider>

and mounts instances automatically through the custom element lifecycle.

3.2 No app root

v4 should not require:

createApp(App)();

Instead:

registerComponent(Slider);
registerComponent(Figure);
registerComponent(Accordion);

or:

import '@studiometa/ui/slider';

3.3 Compatibility with data-component

During migration, v3-style mounting may remain available:

<div data-component="Slider"></div>
<ui-slider></ui-slider>

But in v4, custom elements are the primary API.

---

4. Directives

4.1 Utility components become directives

Small utility/meta components should no longer be full components.

Examples:

• Action
• SafeAction
• Fetch
• DataBind
• DataModel
• DataEffect
• DataComputed
• possibly Transition

v3:

<button
  data-component="Action"
  data-option-target="Modal"
  data-option-effect="target.open()">
  Open
</button>

v4:

<button data-action:click="Modal.open">
  Open
</button>

4.2 Components are nouns, directives are behaviors

Components:

<ui-slider>
  ...
</ui-slider>

<ui-figure>
  ...
</ui-figure>

Directives:

<button data-action:click="Slider.next">
  Next
</button>

<form data-fetch="/cart/add" data-fetch-target="#cart">
  ...
</form>

<span data-bind:text="cart.total"></span>

4.3 Directive registration

Possible API:

registerDirective('action', ActionDirective);
registerDirective('fetch', FetchDirective);
registerDirective('bind', DataBindDirective);

Directive class shape:

class FetchDirective {
  constructor(element, options) {}

  connected() {}
  updated() {}
  disconnected() {}
}

4.4 Directive storage

Components currently use:

el.__base__ = Map<componentName, Base>

Directives could use:

el.__directives__ = Map<directiveKey, DirectiveInstance>

Examples of directive keys:

action:click
fetch
bind:text

---

5. Directive syntax

Keep syntax simple and HTML-readable.

5.1 Action

<button data-action:click="Modal.open">
  Open
</button>

With selector:

<button data-action:click="Modal(#cart-modal).open">
  Open cart
</button>

With event modifiers:

<button data-action:click.prevent.stop="Modal.open">
  Open
</button>

Possible modifiers:

prevent
stop
once
capture
passive
debounce
debounce300

5.2 Fetch

<button data-fetch="/cart" data-fetch-target="#cart">
  Refresh cart
</button>

<form
  data-fetch="/cart/add"
  data-fetch-method="post"
  data-fetch-target="#cart">
  ...
</form>

5.3 Bind

<input data-bind:value="cart.quantity">

<span data-bind:text="cart.total"></span>

5.4 Transition

If exposed as directive:

<div data-transition>
  ...
</div>

or:

<div data-transition:enter="fade-in" data-transition:leave="fade-out">
  ...
</div>

---

6. Referencing component instances from directives

Directives should reference component instances by their config.name.

class Modal extends Base {
  static config = {
    name: 'Modal',
  };
}

<ui-modal id="cart-modal"></ui-modal>

<button data-action:click="Modal(#cart-modal).open">
  Open
</button>

6.1 Reference grammar

Base grammar:

Name
Name(selector)
Name(selector):state

Examples:

Modal
Modal(#cart-modal)
Modal(.sidebar)
SliderItem([data-index="2"])
Cart:mounted

6.2 Method call grammar

For CSP-safe actions:

Component.method
Component(selector).method

Examples:

<button data-action:click="Modal.open">
  Open all modals
</button>

<button data-action:click="Modal(#cart-modal).open">
  Open cart modal
</button>

<button data-action:click="Slider(#gallery).next">
  Next
</button>

6.3 Resolution behavior

For:

<button data-action:click="Slider(#gallery).next">

The directive should:

1. resolve all matching Slider instances,
2. filter by #gallery,
3. call next() on each matching instance.

For:

<button data-action:click="Slider.next">

The directive may call next() on all mounted Slider instances.

6.4 Current element resolution

If a component is mounted on the same element, it should be resolvable by name.

<ui-transition data-action:click="Transition.enter">
  ...
</ui-transition>

Resolution order:

1. instance on current element,
2. matching component instances from registry/query.

Optional future helpers:

<button data-action:click="$closest(Modal).open">
<button data-action:click="$self(Transition).enter">
<button data-action:click="$query(SliderItem).disable">

But these are not required for the first version.

---

7. Events

7.1 $emit bubbles by default

v4 should make emitted events native bubbling CustomEvents.

Conceptual implementation:

$emit(event, ...args) {
  const e = new CustomEvent(event, {
    bubbles: true,
    detail: args,
  });

  e.__source = this;

  this.$el.dispatchEvent(e);
}

Benefits:

• native event bubbling,
• easier event delegation,
• directives can listen naturally,
• dynamically added children work better,
• less manual parent/child binding.

7.2 Directives use native events

<form
  data-fetch="/cart/add"
  data-action:fetch-after="Cart.refresh">
  ...
</form>

FetchDirective emits:

fetch-before
fetch-after
fetch-error

data-action:fetch-after listens directly.

---

8. CDN delivery

8.1 Curated CDN bundle

Main usage:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Lazy,Figure,Slider"></script>

This loads and registers only the requested components.

Equivalent generated module:

import { registerComponent } from '@studiometa/js-toolkit';
import { Lazy, Figure, Slider } from '@studiometa/ui';

registerComponent(Lazy);
registerComponent(Figure);
registerComponent(Slider);

8.2 Recommended script type

Use ESM:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Slider"></script>

8.3 CDN parameters

Short form:

?c=Lazy,Figure,Slider

Explicit form, optional:

?components=Lazy,Figure,Slider

Prefix:

?c=Slider&prefix=ui

Example:

<script
  type="module"
  src="https://cdn.studiometa.dev/ui?c=Slider,Figure&prefix=ui">
</script>

8.4 Cache normalization

The CDN should normalize component lists.

These should resolve to the same cached resource:

?c=Lazy,Figure,Slider
?c=Slider,Figure,Lazy
?c=Figure,Slider,Lazy

Canonical order:

?c=Figure,Lazy,Slider

---

9. Lazy component loading

9.1 Lazy component

Lazy is a component that loads other components from markup.

<script type="module" src="https://cdn.studiometa.dev/ui?c=Lazy,Slider"></script>

<ui-slider>
  ...
</ui-slider>

<ui-lazy component="Accordion" when="inView">
  <ui-accordion>
    ...
  </ui-accordion>
</ui-lazy>

Accordion is not loaded initially. It is loaded when <ui-lazy> decides it is needed.

9.2 Lazy API

Single component:

<ui-lazy component="Accordion" when="inView">
  <ui-accordion>...</ui-accordion>
</ui-lazy>

Multiple components:

<ui-lazy component="Accordion,Tabs" when="inView">
  <ui-accordion>...</ui-accordion>
  <ui-tabs>...</ui-tabs>
</ui-lazy>

9.3 when values

Initial supported values could be:

inView
idle
interaction
click

Possible future value:

<ui-lazy component="DesktopMenu" when="media:(min-width: 768px)">
  <ui-desktop-menu>...</ui-desktop-menu>
</ui-lazy>

9.4 Lazy loading behavior

Conceptual implementation:

class Lazy extends Base {
  async mounted() {
    await this.waitForCondition(this.$options.when);
    await loadComponents(this.$options.component);
  }
}

It loads from:

https://cdn.studiometa.dev/ui?c=Accordion

or a more cacheable component endpoint:

https://cdn.studiometa.dev/ui/Accordion.js

---

10. Example: adding Slider to an existing project

Minimal:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Slider"></script>

<ui-slider id="gallery">
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</ui-slider>

With controls:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Action,Slider"></script>

<ui-slider id="gallery">
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</ui-slider>

<button data-action:click="Slider(#gallery).previous">
  Previous
</button>

<button data-action:click="Slider(#gallery).next">
  Next
</button>

With lazy loaded accordion:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Lazy,Slider,Action"></script>

<ui-slider id="gallery">
  ...
</ui-slider>

<button data-action:click="Slider(#gallery).next">
  Next
</button>

<ui-lazy component="Accordion" when="inView">
  <ui-accordion>
    ...
  </ui-accordion>
</ui-lazy>

---

11. Migration path

Phase 1: v3 compatibility

Add support for custom-element mounting while preserving data-component.

<div data-component="Slider"></div>
<ui-slider></ui-slider>

Add early directive registry.

<button data-action:click="Slider.next"></button>

Deprecate utility components used via data-component.

Phase 2: v4 breaking changes

• Custom elements become the primary component API.
• data-component is deprecated or moved to compatibility mode.
• createApp is removed.
• $parent, $root, $children are removed.
• $query() and $closest() are the preferred APIs.
• $emit() bubbles by default.
• Utility/meta components become directives.
• CDN delivery becomes an official supported usage path.

---

12. Success criteria

v4 succeeds if this works:

<script type="module" src="https://cdn.studiometa.dev/ui?c=Slider,Action"></script>

<ui-slider id="gallery">
  ...
</ui-slider>

<button data-action:click="Slider(#gallery).next">
  Next
</button>

With:

• no npm install,
• no bundler,
• no app bootstrap,
• no Shadow DOM,
• no framework setup,
• no rewriting the existing project architecture.

Final positioning:

v4 is a zero-dependency toolkit for authoring and shipping drop-in Light DOM web components and HTML directives.