fix: make scoped CSS support optional via opt-in

Add scoped_css_support trait to VueTemplate that controls whether
<style scoped> in templates is processed. This is a backwards-compatible
change that defaults to False to avoid breaking existing code.

Configuration options:
- Environment variable: IPYVUE_SCOPED_CSS_SUPPORT=1
- Global setting: ipyvue.scoped_css_support = True
- Per-widget: VueTemplate(..., scoped_css_support=True)

The explicit scoped=True/False trait (used with the css trait) still
works independently of this setting.

Author: Maarten Breddels AI

README.md

@@ -26,6 +26,51 @@ For a development installation (requires npm),
     $ jupyter nbextension enable --py --sys-prefix ipyvue
     $ jupyter labextension develop . --overwrite
 
+Scoped CSS Support
+------------------
+
+`<style scoped>` in `VueTemplate` templates is supported but disabled by default for backwards
+compatibility. When enabled, CSS rules only apply to the component's own elements.
+
+Enable globally via environment variable:
+
+    $ IPYVUE_SCOPED_CSS_SUPPORT=1 jupyter lab
+
+Or in Python:
+
+```python
+import ipyvue
+ipyvue.scoped_css_support = True
+```
+
+Or per widget:
+
+```python
+from ipyvue import VueTemplate
+
+class MyComponent(VueTemplate):
+    template = """
+    <template>
+        <span class="styled">Hello</span>
+    </template>
+    <style scoped>
+        .styled { color: red; }
+    </style>
+    """
+
+widget = MyComponent(scoped_css_support=True)
+```
+
+Note: The `css` trait with `scoped=True` always works, regardless of this setting:
+
+```python
+widget = VueTemplate(
+    template="<template><span class='x'>Hi</span></template>",
+    css=".x { color: blue; }",
+    scoped=True
+)
+```
+
 Sponsors
 --------
 

ipyvue/VueTemplateWidget.py

@@ -1,5 +1,5 @@
 import os
-from traitlets import Any, Bool, Unicode, List, Dict, Union, Instance
+from traitlets import Any, Bool, Unicode, List, Dict, Union, Instance, default
 from ipywidgets import DOMWidget
 from ipywidgets.widgets.widget import widget_serialization
 
@@ -8,6 +8,7 @@
 from .ForceLoad import force_load_instance
 import inspect
 from importlib import import_module
+import ipyvue
 
 OBJECT_REF = "objectRef"
 FUNCTION_REF = "functionRef"
@@ -120,6 +121,12 @@ class VueTemplate(DOMWidget, Events):
 
     scoped = Bool(None, allow_none=True).tag(sync=True)
 
+    scoped_css_support = Bool(allow_none=False).tag(sync=True)
+
+    @default("scoped_css_support")
+    def _default_scoped_css_support(self):
+        return ipyvue.scoped_css_support
+
     methods = Unicode(None, allow_none=True).tag(sync=True)
 
     data = Unicode(None, allow_none=True).tag(sync=True)

ipyvue/__init__.py

@@ -1,3 +1,5 @@
+import os
+
 from ._version import __version__
 from .Html import Html
 from .Template import Template, watch
@@ -10,6 +12,22 @@
 )
 
 
+def _parse_bool_env(key: str, default: bool = False) -> bool:
+    """Parse boolean from environment variable."""
+    val = os.environ.get(key, "").lower()
+    if val in ("1", "true", "yes", "on"):
+        return True
+    if val in ("0", "false", "no", "off"):
+        return False
+    return default
+
+
+# Global default for scoped CSS support in VueTemplate.
+# Can be set via environment variable IPYVUE_SCOPED_CSS_SUPPORT=1
+# or changed at runtime: ipyvue.scoped_css_support = True
+scoped_css_support = _parse_bool_env("IPYVUE_SCOPED_CSS_SUPPORT", False)
+
+
 def _jupyter_labextension_paths():
     return [
         {

js/src/VueTemplateRenderer.js

@@ -101,7 +101,12 @@ function createComponentObject(model, parentView) {
     const cssId = (vuefile.STYLE && vuefile.STYLE.id);
     const scopedFromTemplate = (vuefile.STYLE && vuefile.STYLE.scoped);
     const scoped = model.get('scoped');
-    const useScoped = scoped !== null && scoped !== undefined ? scoped : scopedFromTemplate;
+    const scopedCssSupport = model.get('scoped_css_support');
+    // If scoped trait is explicitly set, use it (for css trait with scoped=True/False)
+    // If scoped is not set (None), only honor <style scoped> from template if scoped_css_support is enabled
+    const useScoped = scoped !== null && scoped !== undefined
+        ? scoped
+        : (scopedCssSupport && scopedFromTemplate);
     const scopeId = useScoped && css ? getScopeId(model, cssId) : null;
 
     if (css) {
@@ -217,7 +222,7 @@ function createComponentObject(model, parentView) {
 function createDataMapping(model) {
     return model.keys()
         .filter(prop => !prop.startsWith('_')
-            && !['events', 'template', 'components', 'layout', 'css', 'scoped', 'data', 'methods'].includes(prop))
+            && !['events', 'template', 'components', 'layout', 'css', 'scoped', 'scoped_css_support', 'data', 'methods'].includes(prop))
         .reduce((result, prop) => {
             result[prop] = _.cloneDeep(model.get(prop)); // eslint-disable-line no-param-reassign
             return result;
@@ -227,7 +232,7 @@ function createDataMapping(model) {
 function addModelListeners(model, vueModel) {
     model.keys()
         .filter(prop => !prop.startsWith('_')
-            && !['v_model', 'components', 'layout', 'css', 'scoped', 'data', 'methods'].includes(prop))
+            && !['v_model', 'components', 'layout', 'css', 'scoped', 'scoped_css_support', 'data', 'methods'].includes(prop))
         // eslint-disable-next-line no-param-reassign
         .forEach(prop => model.on(`change:${prop}`, () => {
             if (_.isEqual(model.get(prop), vueModel[prop])) {
@@ -253,7 +258,7 @@ function addModelListeners(model, vueModel) {
 
 function createWatches(model, parentView, templateWatchers) {
     const modelWatchers = model.keys().filter(prop => !prop.startsWith('_')
-    && !['events', 'template', 'components', 'layout', 'css', 'scoped', 'data', 'methods'].includes(prop))
+    && !['events', 'template', 'components', 'layout', 'css', 'scoped', 'scoped_css_support', 'data', 'methods'].includes(prop))
     .reduce((result, prop) => ({
         ...result,
         [prop]: {

tests/ui/test_template.py

@@ -167,7 +167,7 @@ def kernel_code():
         import ipywidgets as widgets
         from IPython.display import display
 
-        scoped = ScopedStyleTemplate()
+        scoped = ScopedStyleTemplate(scoped_css_support=True)
         unscoped = vue.Html(
             tag="span",
             children=["Unscoped text"],