structui 0.1.0__py3-none-any.whl

structui/__init__.py

@@ -0,0 +1,7 @@
+"""StructUI - A format-agnostic, schema-driven, hierarchical configuration UI."""
+
+__version__ = "0.1.0"
+
+from .app import run_app
+
+__all__ = ["run_app"]

structui/app.py

@@ -0,0 +1,15 @@
+from nicegui import ui
+from structui.ui import StructUI
+from structui.state import AppState
+from structui.schema import SchemaManager
+
+def run_app(data_dir: str = ".", schema_filepath: str = ".structui_schema.yaml", port: int = 8080):
+    schema_manager = SchemaManager(schema_filepath)
+    app_state = AppState(data_dir, schema_manager)
+    
+    ui_instance = StructUI(app_state, schema_manager)
+    
+    @ui.page('/')
+    def main_page():
+        ui_instance.render()
+    ui.run(port=port, title="StructUI Editor", show=False, reload=False)

structui/cli.py

@@ -0,0 +1,20 @@
+import argparse
+import sys
+from structui.app import run_app
+
+def main():
+    parser = argparse.ArgumentParser(description="StructUI Configuration Editor")
+    parser.add_argument("--dir", type=str, default=".", help="Directory containing config files")
+    parser.add_argument("--schema", type=str, default=".structui_schema.yaml", help="Path to schema file")
+    parser.add_argument("--port", type=int, default=8080, help="Port to run the UI on (default: 8080)")
+    
+    args = parser.parse_args()
+    
+    try:
+        run_app(data_dir=args.dir, schema_filepath=args.schema, port=args.port)
+    except Exception as e:
+        print(f"Error starting StructUI: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ in {"__main__", "__mp_main__"}:
+    main()

structui/file_picker.py

@@ -0,0 +1,95 @@
+import platform
+from pathlib import Path
+from typing import Optional
+
+from nicegui import events, ui
+
+
+class LocalFilePicker(ui.dialog):
+
+    def __init__(self, directory: str, *,
+                 upper_limit: Optional[str] = ..., multiple: bool = False, show_hidden_files: bool = False,
+                 dirs_only: bool = False) -> None:
+        """Local File Picker
+
+        This is a simple file picker that allows you to select a file from the local filesystem where NiceGUI is running.
+
+        :param directory: The directory to start in.
+        :param upper_limit: The directory to stop navigating up (e.g. the root directory).
+        :param multiple: Whether to allow multiple files to be selected.
+        :param show_hidden_files: Whether to show hidden files.
+        :param dirs_only: Whether to only show directories.
+        """
+        super().__init__()
+
+        self.path = Path(directory).expanduser().resolve()
+        if upper_limit is None:
+            self.upper_limit = None
+        else:
+            self.upper_limit = Path(directory if upper_limit == ... else upper_limit).expanduser().resolve()
+        self.show_hidden_files = show_hidden_files
+        self.dirs_only = dirs_only
+
+        with self, ui.card():
+            self.add_drives_toggle()
+            self.grid = ui.aggrid({
+                'columnDefs': [{'field': 'name', 'headerName': 'File'}],
+                'rowSelection': 'multiple' if multiple else 'single',
+            }, html_columns=[0]).classes('w-96').on('cellDoubleClicked', self.handle_double_click)
+            with ui.row().classes('w-full justify-end'):
+                ui.button('Cancel', on_click=self.close).props('outline')
+                ui.button('Ok', on_click=self._handle_ok)
+        self.update_grid()
+
+    def add_drives_toggle(self):
+        if platform.system() == 'Windows':
+            import win32api
+            drives = win32api.GetLogicalDriveStrings().split('\000')[:-1]
+            self.drives_toggle = ui.toggle(drives, value=drives[0], on_change=self.update_drive)
+
+    def update_drive(self):
+        self.path = Path(self.drives_toggle.value).expanduser()
+        self.update_grid()
+
+    def update_grid(self) -> None:
+        paths = list(self.path.iterdir())
+        if not self.show_hidden_files:
+            paths = [p for p in paths if not p.name.startswith('.')]
+        if self.dirs_only:
+            paths = [p for p in paths if p.is_dir()]
+        paths.sort(key=lambda p: p.name.lower())
+        paths.sort(key=lambda p: not p.is_dir())
+
+        self.grid.options['rowData'] = [
+            {
+                'name': f'📁 <strong>{p.name}</strong>' if p.is_dir() else p.name,
+                'path': str(p),
+            }
+            for p in paths
+        ]
+        if self.upper_limit is None or self.path != self.upper_limit:
+            self.grid.options['rowData'].insert(0, {
+                'name': '📁 <strong>..</strong>',
+                'path': str(self.path.parent),
+            })
+        self.grid.update()
+
+    def handle_double_click(self, e: events.GenericEventArguments) -> None:
+        self.path = Path(e.args['data']['path'])
+        if self.path.is_dir():
+            self.update_grid()
+        else:
+            self.submit([str(self.path)])
+
+    async def _handle_ok(self):
+        try:
+            rows = await self.grid.get_selected_rows()
+        except TimeoutError:
+            rows = []
+            
+        if rows:
+            self.submit([r['path'] for r in rows])
+        elif self.dirs_only:
+            self.submit([str(self.path)])
+        else:
+            ui.notify('No file selected.')

structui/parser.py

@@ -0,0 +1,51 @@
+import os
+import yaml
+import json
+from abc import ABC, abstractmethod
+from typing import Dict, Any
+
+class DataParser(ABC):
+    """Abstract base class for format-agnostic configuration parsing."""
+    
+    @abstractmethod
+    def load(self, filepath: str) -> Any:
+        pass
+        
+    @abstractmethod
+    def save(self, filepath: str, data: Any):
+        pass
+
+class YamlParser(DataParser):
+    def load(self, filepath: str) -> Any:
+        try:
+            with open(filepath, 'r') as f:
+                return yaml.safe_load(f)
+        except Exception as e:
+            print(f"YAML Load Error ({filepath}): {e}")
+            return None
+            
+    def save(self, filepath: str, data: Any):
+        with open(filepath, 'w') as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+class JsonParser(DataParser):
+    def load(self, filepath: str) -> Any:
+        try:
+            with open(filepath, 'r') as f:
+                return json.load(f)
+        except Exception as e:
+            print(f"JSON Load Error ({filepath}): {e}")
+            return None
+            
+    def save(self, filepath: str, data: Any):
+        with open(filepath, 'w') as f:
+            json.dump(data, f, indent=4)
+
+def get_parser(filepath: str) -> DataParser:
+    """Factory method to resolve the correct parser by file extension."""
+    if filepath.endswith(('.yaml', '.yml')):
+        return YamlParser()
+    elif filepath.endswith('.json'):
+        return JsonParser()
+    # Easily extensible to XML, CSV, etc.
+    return YamlParser()

structui/schema.py

@@ -0,0 +1,117 @@
+import os
+from typing import Dict, Any
+from .parser import get_parser
+
+class SchemaManager:
+    """Handles schema metadata parsing, defaults resolution, and validation logic."""
+    
+    def __init__(self, schema_filepath: str):
+        self.schema_filepath = schema_filepath
+        self.schema_meta: Dict[str, Any] = {}
+        self._load_schema()
+        
+    def _load_schema(self):
+        if os.path.exists(self.schema_filepath):
+            parser = get_parser(self.schema_filepath)
+            loaded_schema = parser.load(self.schema_filepath)
+            self.schema_meta = loaded_schema if loaded_schema is not None else {}
+        else:
+            print(f"Schema file {self.schema_filepath} not found. Using empty schema.")
+
+    def get_meta(self, key: str) -> Dict[str, Any]:
+        """Safely fetch metadata for a property key."""
+        return self.schema_meta.get(key, {})
+
+    def get_default_val_for_type(self, type_str: str) -> Any:
+        """Returns a sensible default value based on the given schema type."""
+        if type_str == 'boolean': return False
+        if type_str in ['integer', 'number', 'float']: return 0
+        if type_str in ['dict', 'container']: return {}
+        if type_str == 'list': return []
+        return ""
+
+    def prefill_required(self, schema_key: str) -> Dict[str, Any]:
+        """Scans the schema and creates a dictionary containing all REQUIRED child properties pre-filled."""
+        new_val = {}
+        allowed = self.get_meta(schema_key).get('allowed_children', [])
+        for child_key in allowed:
+            child_meta = self.get_meta(child_key)
+            if child_meta.get('required', False):
+                child_type = child_meta.get('type', 'string')
+                if child_type in ['container', 'dict']:
+                    new_val[child_key] = self.prefill_required(child_key)
+                else:
+                    new_val[child_key] = self.get_default_val_for_type(child_type)
+        return new_val
+
+    def get_schema_key_for_path(self, path: str, root_data: Any) -> str:
+        """Resolves the active schema definition key for a data path location."""
+        if path == "root":
+            return "root"
+        parts = path.split('/')[1:]
+        current_schema_key = None
+        curr_data = root_data
+        
+        for p in parts:
+            if curr_data is not None:
+                if isinstance(curr_data, list) and p.isdigit():
+                    try: curr_data = curr_data[int(p)]
+                    except IndexError: curr_data = None
+                elif isinstance(curr_data, dict):
+                    curr_data = curr_data.get(p)
+                else:
+                    curr_data = None
+
+            if p.endswith(('.yaml', '.yml', '.json')):
+                current_schema_key = os.path.splitext(p)[0]
+            elif p.isdigit():
+                if current_schema_key and current_schema_key in self.schema_meta:
+                    meta = self.get_meta(current_schema_key)
+                    if 'list_item_types' in meta:
+                        best_match = None
+                        max_overlap = -1
+                        if isinstance(curr_data, dict):
+                            for t in meta['list_item_types']:
+                                allowed = set(self.get_meta(t).get('allowed_children', []))
+                                overlap = len(allowed.intersection(curr_data.keys()))
+                                if overlap > max_overlap:
+                                    max_overlap = overlap
+                                    best_match = t
+                        current_schema_key = best_match if best_match else meta['list_item_types'][0]
+                    else:
+                        current_schema_key = meta.get('list_item_type', current_schema_key)
+            else:
+                current_schema_key = p
+        return current_schema_key
+
+    def get_label_key_for_schema(self, schema_key: str) -> str:
+        """Finds which sub-property should be dynamically used as the naming label for UI containers."""
+        if schema_key and schema_key in self.schema_meta:
+            meta = self.get_meta(schema_key)
+            if 'label_key' in meta:
+                return meta['label_key']
+            for child in meta.get('allowed_children', []):
+                if child in self.schema_meta and self.schema_meta[child].get('is_label', False):
+                    return child
+        return None
+
+    def get_item_label(self, item_data: Any, item_path: str, root_data: Any, default_label: str) -> str:
+        """Agnostically determines the display label for an object via schema rules."""
+        if not isinstance(item_data, dict):
+            return default_label
+            
+        schema_key = self.get_schema_key_for_path(item_path, root_data)
+        label_key = self.get_label_key_for_schema(schema_key)
+        
+        if label_key and label_key in item_data:
+            return str(item_data[label_key])
+            
+        for k, v in item_data.items():
+            if 'name' in str(k).lower() and isinstance(v, (str, int)):
+                return str(v)
+                
+        for k, v in item_data.items():
+            if isinstance(v, str):
+                return v
+                
+        return default_label

structui/state.py

@@ -0,0 +1,138 @@
+import os
+import glob
+import copy
+from typing import Dict, Any, List
+from .schema import SchemaManager
+from .parser import get_parser
+
+class AppState:
+    """Manages raw config data, memory states, transactions, and undo/redo stacks."""
+    
+    def __init__(self, data_dir: str, schema_manager: SchemaManager):
+        self.data_dir = data_dir
+        self.schema_manager = schema_manager
+        
+        self.config_data: Dict[str, Any] = {}
+        self.history: List[Dict[str, Any]] = []
+        self.history_index: int = -1
+        self.last_saved_index: int = -1
+        self.is_dirty: bool = False
+        
+        self.load_files()
+        
+    def load_files(self):
+        """Loads all supported formatting files in the source directory."""
+        self.config_data = {}
+        files = glob.glob(os.path.join(self.data_dir, "*.yaml")) + \
+                glob.glob(os.path.join(self.data_dir, "*.yml")) + \
+                glob.glob(os.path.join(self.data_dir, "*.json"))
+                
+        for filepath in files:
+            filename = os.path.basename(filepath)
+            if filename == os.path.basename(self.schema_manager.schema_filepath):
+                continue
+                
+            parser = get_parser(filepath)
+            data = parser.load(filepath)
+            
+            if data is None:
+                # Fill structure based on declared schema
+                schema_key = os.path.splitext(filename)[0]
+                file_type = self.schema_manager.get_meta(schema_key).get('type', 'dict')
+                data = [] if file_type == 'list' else {}
+                
+            self.config_data[filename] = data
+            
+        self.history = [copy.deepcopy(self.config_data)]
+        self.history_index = 0
+        self.last_saved_index = 0
+        self.is_dirty = False
+
+    def commit(self):
+        """Saves a memory snapshot into the history stack."""
+        self.history = self.history[:self.history_index + 1]
+        self.history.append(copy.deepcopy(self.config_data))
+        
+        if len(self.history) > 100:
+            self.history.pop(0)
+            if self.last_saved_index > 0:
+                self.last_saved_index -= 1
+            elif self.last_saved_index == 0:
+                self.last_saved_index = -1
+        else:
+            self.history_index += 1
+        self.is_dirty = (self.history_index != self.last_saved_index)
+
+    def undo(self) -> bool:
+        """Reverts local modification to a previous epoch."""
+        if self.history_index > 0:
+            self.history_index -= 1
+            self.config_data = copy.deepcopy(self.history[self.history_index])
+            self.is_dirty = (self.history_index != self.last_saved_index)
+            return True
+        return False
+
+    def redo(self) -> bool:
+        """Restores a previous undo."""
+        if self.history_index < len(self.history) - 1:
+            self.history_index += 1
+            self.config_data = copy.deepcopy(self.history[self.history_index])
+            self.is_dirty = (self.history_index != self.last_saved_index)
+            return True
+        return False
+
+    def get_data_by_path(self, path: str) -> Any:
+        """Returns the local data node associated with the UI tree path string."""
+        if path == "root":
+            return self.config_data
+            
+        keys = path.split('/')[1:]
+        curr = self.config_data
+        
+        try:
+            for key in keys:
+                if curr is None: return None
+                if isinstance(curr, list): 
+                    curr = curr[int(key)]
+                elif isinstance(curr, dict): 
+                    curr = curr.get(key)
+                else: 
+                    return None
+            return curr
+        except (IndexError, ValueError, KeyError, AttributeError):
+            return None
+
+    def set_data_by_path(self, path: str, property_key: str, new_value: Any):
+        """Mutates a targeted property value on the underlying tree."""
+        curr = self.get_data_by_path(path)
+        if isinstance(curr, dict):
+            curr[property_key] = new_value
+        elif isinstance(curr, list):
+            curr[int(property_key)] = new_value
+        self.is_dirty = (self.history_index != self.last_saved_index)
+
+    def save_all_to_disk(self):
+        """Dispatches save operations to agnostic parsers and handles raw deletion tracking."""
+        schema_base = os.path.basename(self.schema_manager.schema_filepath)
+        existing_logical_files = [
+            f for f in os.listdir(self.data_dir) 
+            if f.endswith(('.yaml', '.yml', '.json')) and f != schema_base
+        ]
+        
+        for filename, data in self.config_data.items():
+            filepath = os.path.join(self.data_dir, filename)
+            try:
+                parser = get_parser(filepath)
+                parser.save(filepath, data)
+            except Exception as e:
+                print(f"Error saving {filename}: {e}")
+                
+        for f in existing_logical_files:
+            if f not in self.config_data:
+                try:
+                    os.remove(os.path.join(self.data_dir, f))
+                except Exception as e:
+                    print(f"Error removing {f}: {e}")
+                    
+        self.last_saved_index = self.history_index
+        self.is_dirty = False

structui/ui.py

@@ -0,0 +1,458 @@
+import os
+import sys
+from nicegui import app, ui
+from typing import Dict, Any, List
+from .state import AppState
+from .schema import SchemaManager
+from .file_picker import LocalFilePicker
+
+class StructUI:
+    """The central view abstraction for managing the hierarchical NiceGUI visualization."""
+
+    def __init__(self, state: AppState, schema_manager: SchemaManager):
+        self.state = state
+        self.schema_manager = schema_manager
+        
+        self.selected_path = {"value": "root"}
+        self.tree = None
+        self.editor_scroll_area = None
+        self.footer_pane = None
+        self.dark_mode = None
+        self.save_btn = None
+
+    def get_allowed_options(self, path: str, data_node: Any) -> List[Dict[str, str]]:
+        schema_key = self.schema_manager.get_schema_key_for_path(path, self.state.config_data)
+        meta = self.schema_manager.get_meta(schema_key) if schema_key else {}
+        allowed_from_schema = meta.get('allowed_children', [])
+        allowed_options = []
+        
+        if isinstance(data_node, dict):
+            for child in allowed_from_schema:
+                if child not in data_node:
+                    allowed_options.append({'label': f"Add {child.replace('_', ' ').title()}", 'type': 'dict_key', 'key': child})
+                else:
+                    child_meta = self.schema_manager.get_meta(child)
+                    if isinstance(data_node[child], list) and child_meta.get('type') in ['container', 'list']:
+                        if 'list_item_types' in child_meta:
+                            for item_type in child_meta['list_item_types']:
+                                allowed_options.append({'label': f"Add New {item_type.replace('_', ' ').title()} to {child}", 'type': 'list_item_append', 'key': child, 'item_type': item_type})
+                        else:
+                            item_type = child_meta.get('list_item_type', child)
+                            allowed_options.append({'label': f"Add New {item_type.replace('_', ' ').title()} to {child}", 'type': 'list_item_append', 'key': child, 'item_type': item_type})
+                            
+            if not meta.get('restrict_custom_keys', False):
+                allowed_options.append({'label': "Add Custom File" if path == "root" else "Add Custom Key", 'type': 'custom_dict'})
+            
+        elif isinstance(data_node, list):
+            meta = self.schema_manager.get_meta(schema_key) if schema_key else {}
+            if 'list_item_types' in meta:
+                for item_type in meta['list_item_types']:
+                    allowed_options.append({'label': f"Add New {item_type.replace('_', ' ').title()}", 'type': 'list_item_typed', 'key': item_type})
+            elif 'list_item_type' in meta:
+                item_type = meta['list_item_type']
+                allowed_options.append({'label': f"Add New {item_type.replace('_', ' ').upper()}", 'type': 'list_item_typed', 'key': item_type})
+            else:
+                allowed_options.append({'label': "Add New Item", 'type': 'list_item'})
+                
+        return allowed_options
+
+    def build_tree_nodes(self, data: Any, path: str = "root", name: str = "Configurations") -> Dict[str, Any]:
+        node = {'id': path, 'label': name}
+        children = []
+        node['allowed'] = self.get_allowed_options(path, data)
+        has_prims = False
+        
+        if isinstance(data, dict):
+            for k, v in data.items():
+                if not isinstance(v, (dict, list)):
+                    has_prims = True
+                elif isinstance(v, list) and all(not isinstance(x, (dict, list)) for x in v):
+                    if self.schema_manager.get_meta(str(k)).get('type') not in ['container', 'list']:
+                        has_prims = True
+                        
+                if isinstance(v, (dict, list)):
+                    if isinstance(v, list) and all(not isinstance(x, (dict, list)) for x in v):
+                        if self.schema_manager.get_meta(str(k)).get('type') not in ['container', 'list']:
+                            continue
+                    children.append(self.build_tree_nodes(v, f"{path}/{k}", str(k)))
+        elif isinstance(data, list):
+            for i, v in enumerate(data):
+                if isinstance(v, (dict, list)):
+                    label = self.schema_manager.get_item_label(v, f"{path}/{i}", self.state.config_data, f"[{i}]")
+                    children.append(self.build_tree_nodes(v, f"{path}/{i}", label))
+                    
+        if has_prims:
+            node['icon'], node['color'] = 'settings', 'blue-8'
+        else:
+            node['icon'], node['color'] = 'folder', 'primary'
+            
+        if not children and not has_prims:
+            node['icon'], node['color'] = 'folder_open', 'grey-5'
+                    
+        if children:
+            node['children'] = children
+            
+        return node
+
+    def refresh_tree_and_editor(self):
+        if self.tree is not None:
+            new_nodes = [self.build_tree_nodes(self.state.config_data)]
+            curr_expanded = set(self.tree._props.get('expanded', []))
+            
+            if self.selected_path["value"]:
+                parts = self.selected_path["value"].split('/')
+                for i in range(1, len(parts) + 1):
+                    curr_expanded.add("/".join(parts[:i]))
+            
+            self.tree._props['nodes'] = new_nodes
+            self.tree._props['expanded'] = list(curr_expanded)
+            
+            if self.selected_path["value"]:
+                self.tree._props['selected'] = self.selected_path["value"]
+                
+            self.tree.update()
+            
+        if not self.selected_path["value"]:
+            self.selected_path["value"] = "root"
+            
+        self.update_save_btn_state()
+
+        self.draw_editor(self.selected_path["value"])
+
+    def update_save_btn_state(self):
+        if getattr(self, 'save_btn', None):
+            if getattr(self.state, 'is_dirty', False):
+                self.save_btn._props['color'] = 'warning'
+                self.save_btn.tooltip('Unsaved Changes Available!')
+            else:
+                self.save_btn._props['color'] = 'primary'
+                self.save_btn.tooltip('Save Configurations')
+            self.save_btn.update()
+
+        self.draw_editor(self.selected_path["value"])
+
+    def update_footer(self, prop_key=None):
+        self.footer_pane.clear()
+        with self.footer_pane:
+            if not prop_key:
+                ui.label("Help & Metadata").classes('text-lg font-bold text-gray-700 dark:text-gray-300')
+                ui.label("Select a property in the editor to see its description and type.").classes('text-gray-500 dark:text-gray-400 italic')
+                return
+                
+            meta = self.schema_manager.get_meta(prop_key)
+            if not meta:
+                meta = {"type": "unknown", "desc": "No description available for this property."}
+                
+            with ui.row().classes('items-center gap-2 mb-2'):
+                ui.icon('info', size='sm', color='primary')
+                ui.label(prop_key).classes('text-lg font-bold text-blue-800 dark:text-blue-300 font-mono')
+                ui.badge(meta.get('type', 'unknown'), color='blue-200').classes('text-blue-900 ml-2')
+                
+                is_req = meta.get('required', False)
+                req_color = "red-100 text-red-800" if is_req else "green-100 text-green-800"
+                ui.badge("Required" if is_req else "Optional").classes(f'ml-2 {req_color} font-bold border border-current')
+            ui.markdown(meta.get('desc', 'No description provided.')).classes('text-gray-700 dark:text-gray-300 text-md ml-8')
+
+    def handle_add_node(self, path: str, option: Dict[str, str]):
+        data_node = self.state.get_data_by_path(path)
+        opt_type = option['type']
+        
+        if opt_type == 'dict_key':
+            if isinstance(data_node, dict):
+                k = option.get('key')
+                meta_type = self.schema_manager.get_meta(k).get('type')
+                if meta_type == 'list':
+                    data_node[k] = []
+                elif meta_type in ['container', 'dict']:
+                    data_node[k] = {}
+                elif meta_type == 'bool':
+                    data_node[k] = False
+                elif meta_type in ['int', 'number', 'float']:
+                    data_node[k] = 0
+                else:
+                    data_node[k] = ""
+        elif opt_type == 'custom_dict':
+            if isinstance(data_node, dict):
+                with ui.dialog() as dialog, ui.card().classes('min-w-[300px]'):
+                    def perform_add(dyn_key, dyn_type):
+                        if dyn_key:
+                            if dyn_type == 'dict': data_node[dyn_key] = {}
+                            elif dyn_type == 'list': data_node[dyn_key] = []
+                            elif dyn_type == 'string': data_node[dyn_key] = ""
+                            elif dyn_type == 'integer': data_node[dyn_key] = 0
+                            elif dyn_type == 'boolean': data_node[dyn_key] = False
+                        dialog.close()
+                        self.state.commit()
+                        self.refresh_tree_and_editor()
+                    ui.label('Enter new key name:').classes('font-bold')
+                    inp = ui.input().classes('w-full')
+                    ui.label('Select Type:').classes('font-bold mt-2')
+                    type_sel = ui.select(['string', 'integer', 'boolean', 'list', 'dict'], value='string').classes('w-full')
+                    ui.button('Add', on_click=lambda: perform_add(inp.value, type_sel.value)).classes('mt-4 w-full')
+                dialog.open()
+                return
+        elif opt_type in ['list_item', 'list_item_typed']:
+            if isinstance(data_node, list):
+                data_node.append({})
+        elif opt_type == 'list_item_append':
+            if isinstance(data_node, dict):
+                list_key = option.get('key')
+                if list_key in data_node and isinstance(data_node[list_key], list):
+                    data_node[list_key].append({})
+                    
+        self.state.commit()
+        self.refresh_tree_and_editor()
+
+    def draw_editor(self, path: str):
+        if not path:
+            path = "root"
+        self.selected_path["value"] = path
+        self.editor_scroll_area.clear()
+        self.update_footer(None)
+
+        data_node = self.state.get_data_by_path(path)
+        if data_node is None:
+            with self.editor_scroll_area:
+                ui.label("This node no longer exists or was deleted.").classes('text-red-500 mt-10 text-lg font-bold')
+            return 
+
+        with self.editor_scroll_area:
+            # INTERACTIVE BREADCRUMBS
+            parts = path.split('/')
+            with ui.row().classes('items-center gap-2 mb-6 w-full flex-wrap'):
+                current_path = []
+                for i, p in enumerate(parts):
+                    current_path.append(p)
+                    full_path = "/".join(current_path)
+                    
+                    def make_breadcrumb_nav(nav_p=full_path):
+                        return lambda e: (self.selected_path.update({"value": nav_p}), self.refresh_tree_and_editor())
+                    
+                    ui.label("Root" if p == "root" else p).classes('text-blue-600 dark:text-blue-400 hover:text-blue-800 cursor-pointer font-bold text-lg hover:underline').on('click', make_breadcrumb_nav())
+                    if i < len(parts) - 1:
+                        ui.icon('chevron_right', color='gray').classes('text-gray-400')
+            
+            # EDITOR HEADER
+            with ui.row().classes('w-full items-center justify-between mb-4 pb-2 border-b border-gray-200 dark:border-slate-700'):
+                with ui.row().classes('items-center bg-slate-50 dark:bg-slate-900 gap-2'):
+                    prop_search = ui.input('Search properties...').classes('w-64').props('dense rounded outlined')
+                    
+                    def locate_in_tree(p=path):
+                        if self.tree:
+                            parts = p.split('/')
+                            paths_to_expand = ['/'.join(parts[:i+1]) for i in range(len(parts))]
+                            self.tree.expand(paths_to_expand)
+                            ui.notify('Located in tree', color='blue')
+
+                    ui.button(icon='my_location', on_click=locate_in_tree).props('flat round').classes('text-slate-600 dark:text-slate-400').tooltip('Locate in Tree')
+                    
+                    with ui.button(icon='add').props('flat round').classes('text-blue-500').tooltip('Add Property / Node'):
+                        with ui.menu() as add_menu:
+                            opts = self.get_allowed_options(path, data_node)
+                            if not opts:
+                                ui.menu_item('No actions available').classes('text-gray-400')
+                            for opt in opts:
+                                def make_add_callback(o=opt):
+                                    return lambda: self.handle_add_node(path, o)
+                                ui.menu_item(opt['label'], auto_close=True, on_click=make_add_callback()).classes('flex items-center gap-2')
+                                
+                    if path != "root":
+                        def delete_current_container():
+                            parent_path = "/".join(path.split('/')[:-1])
+                            node_key = path.split('/')[-1]
+                            parent_node = self.state.get_data_by_path(parent_path)
+                            if isinstance(parent_node, dict): parent_node.pop(node_key, None)
+                            elif isinstance(parent_node, list): parent_node.pop(int(node_key))
+                            self.state.commit()
+                            self.selected_path["value"] = parent_path
+                            self.refresh_tree_and_editor()
+
+                        ui.button(icon='delete', on_click=delete_current_container).props('flat round').classes('text-red-500').tooltip('Delete this entire container')
+            
+            # PRIMITIVES EDITOR
+            props_container = ui.column().classes('w-full gap-4')
+            
+            def render_primitive_input(k, v, parent_node):
+                def make_on_change(prop_key=k):
+                    def handler(e):
+                        self.state.set_data_by_path(self.selected_path["value"], str(prop_key), e.value)
+                        self.state.commit()
+                        self.update_save_btn_state()
+                    return handler
+                    
+                meta = self.schema_manager.get_meta(str(k))
+                is_required = meta.get('required', False)
+                label_text = f"{k} *" if is_required else str(k)
+                options = meta.get('options')
+                
+                with ui.row().classes('items-center flex-grow flex-nowrap gap-2 w-full'):
+                    if options:
+                        safe_options = list(options)
+                        if v not in safe_options: safe_options.append(v)
+                        inp = ui.select(safe_options, value=v, label=label_text).classes('flex-grow').on_value_change(make_on_change())
+                    elif isinstance(v, bool):
+                        inp = ui.switch(text=label_text, value=v).on_value_change(make_on_change())
+                    elif isinstance(v, (int, float)):
+                        inp = ui.number(label=label_text, value=v).classes('flex-grow').on_value_change(make_on_change())
+                    else:
+                        inp = ui.input(label=label_text, value=str(v)).classes('flex-grow').on_value_change(make_on_change())
+                        
+                    inp.on('focus', lambda _: self.update_footer(str(k)))
+                    
+                    if not is_required:
+                        def delete_prop(pk=k, pd=parent_node):
+                            if isinstance(pd, dict) and pk in pd: pd.pop(pk, None)
+                            elif isinstance(pd, list) and int(pk) < len(pd): pd.pop(int(pk))
+                            self.state.commit()
+                            self.refresh_tree_and_editor()
+                        ui.button(icon='delete_outline', color='red-400', on_click=delete_prop).props('flat round size=sm').tooltip('Remove Property').classes('mt-2')
+                
+            with props_container:
+                has_primitives = False
+                if isinstance(data_node, dict):
+                    for k, v in data_node.items():
+                        if not isinstance(v, (dict, list)):
+                            has_primitives = True
+                            with ui.row().classes('w-full items-center gap-2'):
+                                is_req = self.schema_manager.get_meta(str(k)).get('required', False)
+                                ui.icon('lock', size='sm').classes('text-gray-400 w-8') if is_req else ui.icon('edit', size='sm').classes('text-blue-400 w-8')
+                                render_primitive_input(k, v, data_node)
+                elif isinstance(data_node, list):
+                    for i, v in enumerate(data_node):
+                        if not isinstance(v, (dict, list)):
+                            has_primitives = True
+                            with ui.row().classes('w-full items-center gap-2'):
+                                ui.icon('edit', size='sm').classes('text-blue-400 w-8')
+                                render_primitive_input(i, v, data_node)
+                                
+                if not has_primitives:
+                    ui.label("This node contains no primitive properties directly.").classes('text-gray-400 italic mt-2')
+            
+            # SUB-CONTAINERS FOLDERS
+            sub_containers = []
+            if isinstance(data_node, dict):
+                for k, v in data_node.items():
+                    if isinstance(v, dict) or (isinstance(v, list) and not (isinstance(v, list) and all(not isinstance(x, (dict, list)) for x in v))):
+                        sub_containers.append((k, f"{path}/{k}"))
+            elif isinstance(data_node, list):
+                for i, v in enumerate(data_node):
+                    if isinstance(v, (dict, list)):
+                        item_label = self.schema_manager.get_item_label(v, f"{path}/{i}", self.state.config_data, f"Item [{i}]")
+                        sub_containers.append((item_label, f"{path}/{i}"))
+                        
+            if sub_containers:
+                ui.separator().classes('my-6')
+                ui.label("Sub-Containers").classes('text-xl font-bold text-slate-800 dark:text-slate-200 mb-4')
+                with ui.row().classes('w-full gap-4 flex-wrap'):
+                    for label, child_path in sub_containers:
+                        with ui.card().tight().classes('cursor-pointer hover:bg-blue-50 border border-gray-200 dark:bg-slate-800 shadow-sm w-48').on('click', lambda _, cp=child_path: (self.selected_path.update({"value": cp}), self.refresh_tree_and_editor())):
+                            with ui.row().classes('items-center p-3 gap-3 w-full'):
+                                ui.icon('folder', color='primary', size='sm')
+                                ui.label(str(label)).classes('font-bold text-slate-700 dark:text-slate-300 truncate w-32')
+
+    def render(self):
+        self.dark_mode = ui.dark_mode()
+        ui.add_head_html('''
+            <style>
+                body.body--light { background-color: #f8fafc; }
+                body.body--dark { background-color: #0f172a; }
+                .q-tree__node-header { width: 100%; }
+                
+                body.body--dark .q-tree { color: #e2e8f0 !important; }
+                body.body--dark .q-field__native, body.body--dark .q-field__label { color: #e2e8f0 !important; }
+                body.body--dark .q-card { background-color: #1e293b !important; border-color: #334155 !important; color: #e2e8f0 !important; }
+                body.body--dark .bg-slate-50 { background-color: #0f172a !important; border-color: #334155 !important; }
+            </style>
+        ''')
+        
+        with ui.header().classes('bg-slate-800 text-white shadow-md p-4 flex justify-between items-center'):
+            with ui.row().classes('items-center gap-3 w-1/2 overflow-hidden'):
+                ui.icon('settings_input_component', size='md')
+                ui.label('StructUI Editor').classes('text-xl font-bold tracking-wide')
+                ui.badge().classes('text-xs ml-4 py-1 px-2 font-mono truncate max-w-sm').bind_text_from(self.state, 'data_dir', backward=lambda d: f"Workspace: {d}" if d else "No Workspace Loaded")
+            
+            with ui.row().classes('gap-2 items-center'):
+                ui.button(icon='dark_mode', on_click=lambda: self.dark_mode.set_value(not self.dark_mode.value)).props('flat round color=white')
+                ui.separator().props('vertical color=gray-500').classes('mx-2')
+                
+                # Load Configuration / Schema Buttons
+                async def pick_config_dir():
+                    result = await LocalFilePicker(directory=self.state.data_dir, dirs_only=True, upper_limit=None, show_hidden_files=True)
+                    if result:
+                        self.state.data_dir = result[0]
+                        self.state.load_files()
+                        self.selected_path["value"] = "root"
+                        self.refresh_tree_and_editor()
+                        ui.notify(f'Loaded Configs from {self.state.data_dir}', color='blue')
+
+                async def pick_schema_file():
+                    result = await LocalFilePicker(directory=os.path.dirname(os.path.abspath(self.schema_manager.schema_filepath)), multiple=False, upper_limit=None, show_hidden_files=True)
+                    if result:
+                        self.schema_manager.schema_filepath = result[0]
+                        self.schema_manager._load_schema()
+                        self.refresh_tree_and_editor()
+                        ui.notify(f'Loaded Schema from {os.path.basename(self.schema_manager.schema_filepath)}', color='blue')
+
+                ui.button('Load Configs', icon='folder_open', color='slate-600', on_click=pick_config_dir).props('outline').tooltip("Select configuration directory to load")
+                ui.button('Load Schema', icon='schema', color='slate-600', on_click=pick_schema_file).props('outline').tooltip("Select schema file to load")
+                
+                ui.separator().props('vertical color=gray-500').classes('mx-2')
+                
+                # Exit Dialog
+                with ui.dialog() as exit_dialog, ui.card():
+                    ui.label('Are you sure you want to exit?').classes('text-lg font-bold mb-4')
+                    with ui.row().classes('w-full justify-between mt-2'):
+                        ui.button('Cancel', color='gray', on_click=exit_dialog.close).props('outline')
+                        with ui.row().classes('gap-2'):
+                            ui.button('Exit without Saving', color='red', on_click=lambda: (ui.notify('Exiting...', type='warning'), ui.run_javascript('window.close()'), app.shutdown())).props('outline')
+                            ui.button('Save and Exit', color='green', on_click=lambda: (self.state.save_all_to_disk(), ui.notify('Saved! Exiting...', color='green'), ui.run_javascript('window.close()'), app.shutdown()))
+
+                ui.button(icon='undo', color='slate-600', on_click=lambda: self.refresh_tree_and_editor() if self.state.undo() else ui.notify('Nothing to undo', type='warning')).props('flat round')
+                ui.button(icon='redo', color='slate-600', on_click=lambda: self.refresh_tree_and_editor() if self.state.redo() else ui.notify('Nothing to redo', type='warning')).props('flat round')
+                ui.separator().props('vertical')
+                self.save_btn = ui.button(icon='save', color='primary', on_click=lambda: (self.state.save_all_to_disk(), ui.notify('Saved Configurations', color='green'), self.refresh_tree_and_editor())).props('round')
+                self.save_btn.tooltip('Save Configurations')
+                ui.button(icon='power_settings_new', color='red-500', on_click=exit_dialog.open).props('flat round').tooltip('Exit Application')
+        
+        with ui.row().classes('w-full h-[calc(100vh-80px)] overflow-hidden p-4 gap-4 flex-nowrap'):
+            with ui.column().classes('w-1/3 min-w-[300px] h-full gap-4'):
+                with ui.card().classes('w-full h-full p-0 shadow-md border border-gray-200 dark:border-slate-700 bg-white dark:bg-slate-800 flex flex-col'):
+                    with ui.row().classes('w-full p-4 border-b border-gray-200 dark:border-slate-700 bg-slate-50 dark:bg-slate-900 justify-between items-center'):
+                        ui.label("Configuration Tree").classes('font-bold text-slate-700 dark:text-slate-300 tracking-wide uppercase text-sm')
+                        with ui.row().classes('gap-1 items-center'):
+                            tree_search = ui.input('Search...').classes('w-48').props('dense rounded outlined clearable')
+                            ui.button(icon='unfold_less', on_click=lambda: self.tree.collapse() if self.tree else None).props('flat round size=sm').classes('text-slate-500').tooltip('Collapse All')
+                            ui.button(icon='unfold_more', on_click=lambda: self.tree.expand() if self.tree else None).props('flat round size=sm').classes('text-slate-500').tooltip('Expand All')
+                        
+                    with ui.scroll_area().classes('w-full bg-slate-50 dark:bg-slate-900 flex-grow p-4 pt-2'):
+                        self.tree = ui.tree([self.build_tree_nodes(self.state.config_data)], label_key='label', on_select=lambda e: (self.selected_path.update({"value": e.value}), self.refresh_tree_and_editor()) if e.value else None).classes('w-full custom-tree font-medium text-slate-700 dark:text-slate-300')
+                        if self.tree:
+                            self.tree._props['selected'] = self.selected_path["value"]
+                            self.tree.props('control-color=primary node-key=id')
+                            tree_search.on_value_change(lambda e: (self.tree._props.update({'filter': e.value}), self.tree.update()) if self.tree else None)
+                            self.tree.expand()
+                            
+                            def handle_expanded(e):
+                                if getattr(e, 'args', None) is not None:
+                                    old_expanded = set(self.tree._props.get('expanded', []))
+                                    new_expanded = set(e.args)
+                                    added = new_expanded - old_expanded
+                                    if added:
+                                        target = list(added)[0]
+                                        self.selected_path["value"] = target
+                                        self.refresh_tree_and_editor()
+                                    else:
+                                        self.tree._props['expanded'] = list(new_expanded)
+                                        self.tree.update()
+
+                            self.tree.on('update:expanded', handle_expanded)
+                        
+            with ui.column().classes('w-2/3 flex-grow bg-slate-50 dark:bg-slate-900 h-full gap-4'):
+                with ui.card().classes('w-full h-3/4 shadow-md border border-gray-200 dark:border-slate-700 bg-slate-50 dark:bg-slate-900 flex flex-col p-6 pt-4'):
+                    ui.label("Properties Editor").classes('font-bold text-slate-700 dark:text-slate-300 tracking-wide uppercase text-sm mb-2')
+                    self.editor_scroll_area = ui.scroll_area().classes('w-full flex-grow')
+                
+                with ui.card().classes('w-full h-1/4 shadow-md border border-gray-200 dark:border-slate-700 bg-slate-50 dark:bg-slate-900 p-4'):
+                    self.footer_pane = ui.column().classes('w-full')
+        
+        self.refresh_tree_and_editor()

structui-0.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: structui
+Version: 0.1.0
+Summary: A format-agnostic, schema-driven, hierarchical configuration UI.
+Author: structui contributors
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: nicegui>=1.4.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: pywin32>=300; sys_platform == "win32"
+
+# StructUI
+
+StructUI is a format-agnostic, schema-driven, hierarchical configuration UI engine built in Python. Designed as a flexible architectural backbone, it parses standard configuration files (YAML, JSON, CSV, XML) and dynamically generates a live web-based property editor based on constraints and metadata defined in a schema file. 
+
+The architecture is explicitly decoupled, making it readily extensible to strict domain-specific specifications (e.g., AUTOSAR configurators) and agent-driven programmatic workflows.
+
+## Features
+
+- **Pillar A: Format-Agnostic Parsers:** cleanly separate UI generation from underlying data formats. Out-of-the-box support for YAML and JSON, with abstract base classes easily extensible to XML or CSV.
+- **Pillar B: Hierarchical UI:** Dynamic tree-based rendering with full support for multidimensional containers, dynamic polymorphic list additions, and node mapping. Powered natively by NiceGUI.
+- **Pillar C: Data Validity:** Enforces schema metadata strictly at the UI layer. Missing fields gracefully populate via defaults, required flags trigger locking, and nested typings are continuously evaluated.
+- **Pillar D: Extensibility & Programmatic Control:** Decomposed core logic (App, Parser, State, Schema, UI) allowing external tools and wrappers (e.g. CLI, Agent Workflows) to invoke the editor or inject properties safely.
+
+## Installation & Setup
+
+StructUI leverages standard Python packaging mechanisms.
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/structui.git
+cd structui
+
+# Install the application locally
+pip install -e .
+```
+
+## Quick Start
+
+Launch the editor in the current directory against your local configuration files by simply typing:
+
+```bash
+structui --dir . --schema .structui_schema.yaml --port 8080
+```

structui-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+structui/__init__.py,sha256=X9solSS5AR_nnc7a5b6WzTEH2-YV1AID4uH_mI6FeIw,161
+structui/app.py,sha256=u8tkJFG2QHhBoFK2YdV2fBX9SlkhOF6h9qdYLOG2Ocw,558
+structui/cli.py,sha256=IQT6-i1Pd-d7-M-FFR36C3KEa9z9v8yVxpQUZbQCk4k,781
+structui/file_picker.py,sha256=fN5csaPKgMqf-bmrejQEPaH9awZVKDjDfHOPUj53AFM,3719
+structui/parser.py,sha256=APGoUBUM2gczwZnF7fMiHI1LbxTeNndIS7ya50idGjE,1607
+structui/schema.py,sha256=sAjJnYqblIzy8BhVjG-aRo52p2hXWELUxdz0ZjIxTg0,5403
+structui/state.py,sha256=cz1AUNodTXnQvqJnJbxXPGrrzoIvqSk1C-Hjcht9AKY,5474
+structui/ui.py,sha256=htO0YZmba0S2Q-nJ7hpRHd8g4H4lFvA9P6pFo0EWrxc,28751
+structui-0.1.0.dist-info/METADATA,sha256=dhya0ciM-54qux3UnJXWaZpqy58h8aSYLRnnUza9ZXg,2633
+structui-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+structui-0.1.0.dist-info/entry_points.txt,sha256=UdaDGP9j50oP075Ak_LoXYPCGqsv5LZhuuh0ot-1qLk,47
+structui-0.1.0.dist-info/top_level.txt,sha256=1EXWIhwYOrJkPjryNqLSFl1_beNghV48nZzEqQ1YEGg,9
+structui-0.1.0.dist-info/RECORD,,

structui-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

structui-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+structui = structui.cli:main

structui-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+structui