mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-24 13:54:57 +00:00
docs: styles,validator,validation (2 files)
This commit is contained in:
Richard Ward
@@ -1,288 +0,0 @@
|
||||
# Styles System - Complete Implementation
|
||||
|
||||
## Summary
|
||||
|
||||
Successfully implemented a comprehensive styling system for MetaBuil der based on CSS as an abstract deterministic function rather than a syntax-focused format.
|
||||
|
||||
## What Was Done
|
||||
|
||||
### 1. Created Stub styles.json for All Packages (40 packages)
|
||||
|
||||
Generated stub `seed/styles.json` files for all packages that were missing them:
|
||||
- admin_dialog, arcade_lobby, audit_log, code_editor, codegen_studio
|
||||
- config_summary, dashboard, data_table, dbal_demo, form_builder
|
||||
- forum_forge, github_tools, irc_webchat, lua_test, media_center
|
||||
- nav_menu, notification_center, package_validator, quick_guide
|
||||
- role_editor, schema_editor, screenshot_analyzer, smtp_config
|
||||
- social_hub, stats_grid, stream_cast, ui_auth, ui_dialogs
|
||||
- ui_intro, ui_level2-6, ui_login, ui_pages, ui_permissions
|
||||
- user_manager, workflow_editor
|
||||
|
||||
### 2. Updated All metadata.json Files
|
||||
|
||||
Added `seed` section to all 44 package metadata files:
|
||||
|
||||
```json
|
||||
{
|
||||
"seed": {
|
||||
"styles": "seed/styles.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Updated Package Validator
|
||||
|
||||
**Files Modified:**
|
||||
|
||||
1. **[structure_config.lua](packages/package_validator/seed/scripts/structure_config.lua)**
|
||||
- Added `seed/styles.json` to optional structure
|
||||
|
||||
2. **[validate_metadata.lua](packages/package_validator/seed/scripts/validate_metadata.lua)**
|
||||
- Added validation for `seed` section
|
||||
- Validates `seed.styles` as string path
|
||||
- Validates `seed.data` for future use
|
||||
|
||||
3. **[validate_styles.lua](packages/package_validator/seed/scripts/validate_styles.lua)** (NEW)
|
||||
- Validates styles.json structure
|
||||
- Checks required fields (id, type, css in V1)
|
||||
- Validates type enum values
|
||||
- Detects duplicate IDs
|
||||
- Provides warnings for empty CSS
|
||||
|
||||
4. **[validate_package.lua](packages/package_validator/seed/scripts/validate_package.lua)**
|
||||
- Integrated styles validation into package validation flow
|
||||
- Added skipStyles option
|
||||
|
||||
### 4. Created Schema V2: CSS as Abstract System
|
||||
|
||||
**[CSS_SCHEMA_V2.md](packages/shared/seed/CSS_SCHEMA_V2.md)** - Complete specification
|
||||
|
||||
#### Core Abstraction
|
||||
|
||||
```
|
||||
CSS = f(Style Rules, Element Tree, Environment) → Computed Styles
|
||||
```
|
||||
|
||||
#### 10 Layered Systems
|
||||
|
||||
1. **Identity Layer** (Object Inspector)
|
||||
- Objects with ID, type, classes, attributes, states
|
||||
- GUI: Tree view with property inspector
|
||||
|
||||
2. **Selection Layer** (Selector Builder)
|
||||
- Selectors as predicates, not strings
|
||||
- GUI: Visual constructor with dropdowns
|
||||
|
||||
3. **Cascade Layer** (Rule Priority Stack)
|
||||
- Rules ordered by importance → specificity → source order
|
||||
- GUI: Draggable rule cards with priority indicators
|
||||
|
||||
4. **Value System** (Typed Property Editors)
|
||||
- Typed values: color, length, number, enum, transform
|
||||
- GUI: Type-specific editors (color picker, slider, etc.)
|
||||
|
||||
5. **Computed Values** (Debug & Explainability)
|
||||
- Read-only resolved snapshots with source attribution
|
||||
- GUI: Computed style panel showing "why"
|
||||
|
||||
6. **Layout System** (Constraint Systems)
|
||||
- Layout as constraint satisfaction (flex, grid, absolute)
|
||||
- GUI: Layout mode switcher with visual handles
|
||||
|
||||
7. **Paint & Effects** (Layer Compositor)
|
||||
- Painting as stacked effects (background, border, shadow)
|
||||
- GUI: Layered appearance editor (Photoshop-style)
|
||||
|
||||
8. **Environment & Context** (Context Simulator)
|
||||
- Context-dependent rules (viewport, color scheme, DPI)
|
||||
- GUI: Environment toolbar with simulators
|
||||
|
||||
9. **Tokens & Variables** (Global Palette)
|
||||
- Design tokens as first-class values
|
||||
- GUI: Token editor with palettes
|
||||
|
||||
10. **Animation & Transitions** (State Machines)
|
||||
- Animations as state machines with keyframes
|
||||
- GUI: Timeline editor
|
||||
|
||||
### 5. Updated ui_home with V2 Schema
|
||||
|
||||
**[packages/ui_home/seed/styles.json](packages/ui_home/seed/styles.json)**
|
||||
|
||||
Converted from CSS-syntax format to abstract system with:
|
||||
|
||||
- **Tokens**: 7 color tokens, spacing scale, typography
|
||||
- **Selectors**: 5 predicates (hero title, subtitle, cards, icons)
|
||||
- **Effects**: 4 effect definitions (typography, transforms)
|
||||
- **Appearance**: 9 appearance layers (gradients for 6 levels)
|
||||
- **Layouts**: 2 constraint systems (flex, grid with responsiveness)
|
||||
- **Transitions**: 1 state-based transition
|
||||
- **Rules**: 4 cascade rules with priority
|
||||
- **Environments**: 3 responsive breakpoints
|
||||
|
||||
## Schema Comparison
|
||||
|
||||
### V1 (CSS-Syntax Focused) ❌
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "hero_title_styles",
|
||||
"type": "component",
|
||||
"css": ".hero-title { font-size: 4rem; ... }"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
- CSS syntax in JSON
|
||||
- Not GUI-editable
|
||||
- No semantic structure
|
||||
- No cascade representation
|
||||
|
||||
### V2 (Abstract System) ✅
|
||||
|
||||
```json
|
||||
{
|
||||
"selectors": [{
|
||||
"predicate": {
|
||||
"targetType": "Text",
|
||||
"classes": ["hero-title"]
|
||||
}
|
||||
}],
|
||||
"effects": [{
|
||||
"properties": {
|
||||
"fontSize": {
|
||||
"type": "responsive",
|
||||
"breakpoints": {
|
||||
"md": { "value": 4, "unit": "rem" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}],
|
||||
"rules": [{
|
||||
"selector": "hero_title_selector",
|
||||
"effects": { "ref": "hero_title_typography" },
|
||||
"priority": { "specificity": {...} }
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Fully GUI-editable
|
||||
- Semantic structure
|
||||
- Cascade explicitly modeled
|
||||
- Type-safe values
|
||||
- Responsive by design
|
||||
|
||||
## GUI Mental Model
|
||||
|
||||
Users are **NOT** "writing CSS". They are:
|
||||
|
||||
1. **Tagging objects** (identity)
|
||||
2. **Defining conditions** (selection)
|
||||
3. **Assigning visual outcomes** (effects + appearance)
|
||||
4. **Resolving conflicts** (priority stack)
|
||||
5. **Previewing result** (computed values)
|
||||
|
||||
## Compilation to CSS
|
||||
|
||||
The system **generates** CSS as output:
|
||||
|
||||
```javascript
|
||||
function compileToCSS(schema) {
|
||||
// 1. Resolve all tokens
|
||||
// 2. Build selectors from predicates
|
||||
// 3. Apply cascade resolution
|
||||
// 4. Generate CSS text
|
||||
return cssString;
|
||||
}
|
||||
```
|
||||
|
||||
CSS is a **compilation target**, not the authoring format.
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
### New Files
|
||||
1. `packages/shared/seed/CSS_SCHEMA_V2.md` - Complete V2 specification
|
||||
2. `packages/package_validator/seed/scripts/validate_styles.lua` - Styles validator
|
||||
3. 40x `packages/*/seed/styles.json` - Stub files for all packages
|
||||
|
||||
### Modified Files
|
||||
1. `packages/ui_home/seed/styles.json` - Updated to V2 schema
|
||||
2. `packages/package_validator/seed/scripts/structure_config.lua` - Added styles to structure
|
||||
3. `packages/package_validator/seed/scripts/validate_metadata.lua` - Added seed validation
|
||||
4. `packages/package_validator/seed/scripts/validate_package.lua` - Integrated styles validation
|
||||
5. 44x `packages/*/seed/metadata.json` - Added seed.styles reference
|
||||
|
||||
## Database Integration
|
||||
|
||||
The schema supports the original vision of loading CSS from database:
|
||||
|
||||
```sql
|
||||
CREATE TABLE styles (
|
||||
id VARCHAR(255) PRIMARY KEY,
|
||||
package_id VARCHAR(255),
|
||||
schema_version VARCHAR(10),
|
||||
data JSON, -- Complete V2 schema
|
||||
compiled_css TEXT, -- Generated CSS
|
||||
enabled BOOLEAN
|
||||
);
|
||||
```
|
||||
|
||||
The CSS Designer package can:
|
||||
- Load V2 schema from database
|
||||
- Provide GUI editors for each layer
|
||||
- Compile to CSS on save
|
||||
- Live-inject updates
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Implement V2 Compiler**
|
||||
- Write `compileToCSS(schema)` function
|
||||
- Handle all layer types
|
||||
- Generate optimized CSS
|
||||
|
||||
2. **Build GUI Designer**
|
||||
- Object inspector
|
||||
- Selector builder
|
||||
- Property editors per type
|
||||
- Rule priority stack
|
||||
- Live preview
|
||||
|
||||
3. **Create Migration Tool**
|
||||
- Convert existing CSS to V2
|
||||
- Extract tokens automatically
|
||||
- Build predicate selectors
|
||||
|
||||
4. **Database Loader**
|
||||
- Seed V2 schemas to database
|
||||
- Runtime compilation
|
||||
- Hot reloading
|
||||
|
||||
## Validation
|
||||
|
||||
All packages now pass validation with styles.json:
|
||||
|
||||
```bash
|
||||
# Run validator
|
||||
lua packages/package_validator/seed/scripts/cli.lua ui_home
|
||||
```
|
||||
|
||||
Validates:
|
||||
- metadata.json structure
|
||||
- components.json structure
|
||||
- Package folder structure
|
||||
- **styles.json structure** (NEW)
|
||||
- Lua script exports
|
||||
|
||||
## The Vision Realized
|
||||
|
||||
✅ CSS can be loaded from database
|
||||
✅ CSS can be edited in GUI (CSS Designer)
|
||||
✅ CSS is structured data, not syntax
|
||||
✅ Styling is deterministic function
|
||||
✅ All packages have styles infrastructure
|
||||
✅ Package validator enforces standards
|
||||
|
||||
This is the foundation for a true visual styling system where users manipulate **abstract styling concepts** through **visual interfaces**, not CSS syntax.
|
||||
235
packages/package_validator/STYLES_VALIDATION.md
Normal file
235
packages/package_validator/STYLES_VALIDATION.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Styles Validation Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The package validator now validates both V1 (CSS-syntax) and V2 (abstract system) schema formats for `styles.json`.
|
||||
|
||||
## Schema Detection
|
||||
|
||||
The validator automatically detects the schema version:
|
||||
|
||||
- **V2**: Has `schema_version` or `package` field (object format)
|
||||
- **V1**: Array format (legacy CSS-syntax)
|
||||
|
||||
## V1 Schema Validation
|
||||
|
||||
### Required Fields
|
||||
- `id` (string, unique)
|
||||
- `type` (enum: global, component, utility, animation)
|
||||
- `css` (string, non-empty)
|
||||
|
||||
### Optional Fields
|
||||
- `priority` (number)
|
||||
- `className` (string)
|
||||
- `description` (string)
|
||||
- `category` (string)
|
||||
|
||||
### Checks
|
||||
- Duplicate ID detection
|
||||
- Valid type enum values
|
||||
- CSS content not empty
|
||||
- Proper field types
|
||||
|
||||
## V2 Schema Validation
|
||||
|
||||
### Top-Level Structure
|
||||
|
||||
```lua
|
||||
{
|
||||
schema_version: string (semver),
|
||||
package: string,
|
||||
tokens: object,
|
||||
selectors: array,
|
||||
effects: array,
|
||||
appearance: array,
|
||||
layouts: array,
|
||||
transitions: array,
|
||||
rules: array,
|
||||
environments: array
|
||||
}
|
||||
```
|
||||
|
||||
### 1. Tokens Validation
|
||||
|
||||
Validates:
|
||||
- `tokens.colors` is object
|
||||
- `tokens.spacing` is object
|
||||
- `tokens.typography` is object
|
||||
|
||||
### 2. Selectors Validation (Selection Layer)
|
||||
|
||||
Each selector must have:
|
||||
- `id` (string, unique)
|
||||
- `predicate` (object)
|
||||
- `targetType` (string, warning if missing)
|
||||
- `classes` (array, optional)
|
||||
- `states` (array, optional)
|
||||
- `relationship` (object, optional)
|
||||
|
||||
### 3. Effects Validation (Value System)
|
||||
|
||||
Each effect must have:
|
||||
- `id` (string, unique)
|
||||
- `properties` (object)
|
||||
|
||||
### 4. Appearance Validation (Paint & Effects Layer)
|
||||
|
||||
Each appearance must have:
|
||||
- `id` (string, unique)
|
||||
- `layers` (array)
|
||||
|
||||
Each layer must have:
|
||||
- `type` (enum: background, foreground, border, shadow, filter)
|
||||
- `properties` (object)
|
||||
|
||||
### 5. Layouts Validation (Constraint Systems)
|
||||
|
||||
Each layout must have:
|
||||
- `id` (string, unique)
|
||||
- `type` (enum: flow, flex, grid, absolute, sticky)
|
||||
- `constraints` (object, warning if missing)
|
||||
|
||||
### 6. Transitions Validation (State Machines)
|
||||
|
||||
Each transition must have:
|
||||
- `id` (string, unique)
|
||||
- `trigger` (object, warning if missing)
|
||||
- `properties` (array, warning if missing)
|
||||
|
||||
### 7. Rules Validation (Cascade Layer)
|
||||
|
||||
Each rule must have:
|
||||
- `id` (string, unique)
|
||||
- `selector` (string reference to selector id)
|
||||
- `priority` (object, warning if missing)
|
||||
- `importance` (string, warning if missing)
|
||||
- `specificity` (object)
|
||||
- `ids` (number)
|
||||
- `classes` (number)
|
||||
- `types` (number)
|
||||
- `sourceOrder` (number)
|
||||
- `enabled` (boolean, optional)
|
||||
|
||||
### 8. Environments Validation (Context Simulator)
|
||||
|
||||
Each environment must have:
|
||||
- `id` (string, unique)
|
||||
- `conditions` (object)
|
||||
|
||||
## Error vs Warning
|
||||
|
||||
### Errors (fail validation)
|
||||
- Missing required fields
|
||||
- Invalid types
|
||||
- Duplicate IDs
|
||||
- Invalid enum values
|
||||
- Malformed JSON
|
||||
|
||||
### Warnings (pass but flag)
|
||||
- Missing optional but recommended fields
|
||||
- Empty CSS content (V1)
|
||||
- Schema version not semver
|
||||
- Missing constraints in layouts
|
||||
- Missing priority in rules
|
||||
|
||||
## Usage
|
||||
|
||||
```lua
|
||||
local validate_styles = require("validate_styles")
|
||||
|
||||
-- Validate a package
|
||||
local result = validate_styles("/path/to/package")
|
||||
|
||||
if result.success then
|
||||
print("Validation passed!")
|
||||
for _, msg in ipairs(result.messages) do
|
||||
print(" [INFO] " .. msg)
|
||||
end
|
||||
else
|
||||
print("Validation failed!")
|
||||
for _, err in ipairs(result.messages) do
|
||||
print(" [ERROR] " .. err)
|
||||
end
|
||||
end
|
||||
|
||||
for _, warn in ipairs(result.warnings) do
|
||||
print(" [WARN] " .. warn)
|
||||
end
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
The styles validator is integrated into the main package validator:
|
||||
|
||||
```lua
|
||||
-- In validate_package.lua
|
||||
local validate_styles = require("validate_styles")
|
||||
|
||||
-- 5. Validate styles.json (optional)
|
||||
if not options.skipStyles then
|
||||
local styles_result = validate_styles(package_path)
|
||||
-- ... handle results
|
||||
end
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
### V1 Schema
|
||||
|
||||
```
|
||||
[INFO] V1 schema: Found 11 style entries
|
||||
[WARN] Style entry #1 has empty CSS content
|
||||
```
|
||||
|
||||
### V2 Schema
|
||||
|
||||
```
|
||||
[INFO] V2 schema validated
|
||||
[WARN] Selector #1 predicate missing targetType
|
||||
[WARN] Rule #1 priority missing importance
|
||||
[WARN] Layout #1 missing constraints
|
||||
```
|
||||
|
||||
## Validation Rules Summary
|
||||
|
||||
| Section | Required Fields | Validates |
|
||||
|---------|----------------|-----------|
|
||||
| **Tokens** | - | Structure of color/spacing/typography |
|
||||
| **Selectors** | id, predicate | Predicate structure, no duplicates |
|
||||
| **Effects** | id, properties | Properties exist, no duplicates |
|
||||
| **Appearance** | id, layers | Layer types valid, no duplicates |
|
||||
| **Layouts** | id, type | Type enum, constraints structure |
|
||||
| **Transitions** | id | Trigger and properties structure |
|
||||
| **Rules** | id, selector | Priority and specificity structure |
|
||||
| **Environments** | id, conditions | Conditions exist, no duplicates |
|
||||
|
||||
## Extending Validation
|
||||
|
||||
To add new validation rules:
|
||||
|
||||
1. Add validation function for new section:
|
||||
```lua
|
||||
function validate_new_section(section, result)
|
||||
-- validation logic
|
||||
end
|
||||
```
|
||||
|
||||
2. Call from `validate_styles_v2`:
|
||||
```lua
|
||||
if styles.new_section then
|
||||
validate_new_section(styles.new_section, result)
|
||||
end
|
||||
```
|
||||
|
||||
3. Update this documentation
|
||||
|
||||
## Schema Evolution
|
||||
|
||||
The validator is designed to handle schema evolution:
|
||||
|
||||
- V1 → V2 migration supported
|
||||
- Future V3 can be added with `elseif` branch
|
||||
- Backward compatibility maintained
|
||||
- Version detected automatically
|
||||
|
||||
This ensures packages can gradually migrate from V1 to V2 without breaking validation.
|
||||
Reference in New Issue
Block a user