@abeedoo/radish-schemas 1.7.7

package/schemas/ui.schema.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://radish.dev/schemas/ui.schema.json",
+  "title": "Radish UI Blueprint",
+  "description": "Schema for defining UI routes, pages, layouts, and content blocks. Content blocks are entity-driven and reference entities defined in the types blueprint.",
+  "type": "object",
+  "required": [
+    "version",
+    "routes",
+    "pages"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Blueprint spec version"
+    },
+    "app": {
+      "type": "object",
+      "description": "Application metadata for UI context (name, description used in templates)",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Application name for display in UI"
+        },
+        "description": {
+          "type": "string",
+          "description": "Application description for display in UI"
+        }
+      },
+      "additionalProperties": false
+    },
+    "routes": {
+      "type": "array",
+      "description": "Route definitions mapping URL paths to pages",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/route"
+      }
+    },
+    "pages": {
+      "type": "object",
+      "description": "Page definitions keyed by page identifier",
+      "minProperties": 1,
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "$ref": "#/definitions/page"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "definitions": {
+    "route": {
+      "type": "object",
+      "required": [
+        "path",
+        "page"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL path pattern. Use [param] for dynamic segments (e.g., /courses/[id])",
+          "pattern": "^/"
+        },
+        "page": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Page identifier referencing a key in the pages object",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "title": {
+          "type": "string",
+          "description": "Page title for navigation and breadcrumbs"
+        },
+        "access": {
+          "$ref": "#/definitions/access"
+        }
+      }
+    },
+    "access": {
+      "description": "Access control for a route. Can be a simple string or a role/permission object.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "public",
+            "authenticated"
+          ],
+          "description": "Simple access level"
+        },
+        {
+          "type": "object",
+          "description": "Role and/or permission-based access control",
+          "additionalProperties": false,
+          "properties": {
+            "roles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Required roles (any match grants access)"
+            },
+            "permissions": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Required permissions (any match grants access)"
+            }
+          }
+        }
+      ]
+    },
+    "page": {
+      "type": "object",
+      "required": [
+        "content"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "layout": {
+          "$ref": "#/definitions/layout"
+        },
+        "content": {
+          "type": "array",
+          "description": "Ordered list of content blocks to render on the page",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/contentBlock"
+          }
+        }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "description": "Page layout structure",
+      "additionalProperties": false,
+      "properties": {
+        "header": {
+          "type": "boolean",
+          "description": "Show application header"
+        },
+        "navigation": {
+          "type": "boolean",
+          "description": "Show main navigation"
+        },
+        "sidebar": {
+          "type": "boolean",
+          "description": "Show sidebar"
+        },
+        "footer": {
+          "type": "boolean",
+          "description": "Show application footer"
+        }
+      }
+    },
+    "contentBlock": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "description": "A content block rendered on a page",
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "hero" } },
+            "required": ["type"]
+          },
+          "then": {
+            "additionalProperties": false,
+            "required": ["type", "title"],
+            "properties": {
+              "type": { "const": "hero" },
+              "title": {
+                "type": "string",
+                "description": "Hero title. Supports interpolation with {app.name}, {app.description}"
+              },
+              "subtitle": {
+                "type": "string",
+                "description": "Hero subtitle. Supports interpolation"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "entity-list" } },
+            "required": ["type"]
+          },
+          "then": {
+            "additionalProperties": false,
+            "required": ["type", "entity"],
+            "properties": {
+              "type": { "const": "entity-list" },
+              "entity": {
+                "type": "string",
+                "description": "Entity name from types blueprint (PascalCase)",
+                "pattern": "^[A-Z][A-Za-z0-9]*$"
+              },
+              "title": {
+                "type": "string",
+                "description": "Section heading"
+              },
+              "display": {
+                "type": "string",
+                "enum": ["table", "grid", "list"],
+                "description": "Display mode for the list",
+                "default": "table"
+              },
+              "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum items to display"
+              },
+              "fields": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Fields to display. If omitted, auto-detected from entity metadata"
+              },
+              "filter": {
+                "$ref": "#/definitions/filter"
+              },
+              "sort": {
+                "$ref": "#/definitions/sort"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "entity-detail" } },
+            "required": ["type"]
+          },
+          "then": {
+            "additionalProperties": false,
+            "required": ["type", "entity"],
+            "properties": {
+              "type": { "const": "entity-detail" },
+              "entity": {
+                "type": "string",
+                "description": "Entity name from types blueprint (PascalCase)",
+                "pattern": "^[A-Z][A-Za-z0-9]*$"
+              },
+              "title": {
+                "type": "string",
+                "description": "Section heading"
+              },
+              "fields": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Fields to display. If omitted, auto-detected from entity metadata"
+              },
+              "actions": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["edit", "delete"]
+                },
+                "description": "Action buttons to show on the detail view"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "entity-form" } },
+            "required": ["type"]
+          },
+          "then": {
+            "additionalProperties": false,
+            "required": ["type", "entity"],
+            "properties": {
+              "type": { "const": "entity-form" },
+              "entity": {
+                "type": "string",
+                "description": "Entity name from types blueprint (PascalCase)",
+                "pattern": "^[A-Z][A-Za-z0-9]*$"
+              },
+              "title": {
+                "type": "string",
+                "description": "Form heading"
+              },
+              "action": {
+                "type": "string",
+                "enum": ["create", "edit"],
+                "description": "Form action type",
+                "default": "create"
+              },
+              "fields": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Fields to include in form. If omitted, auto-detected from entity metadata"
+              }
+            }
+          }
+        }
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["hero", "entity-list", "entity-detail", "entity-form"],
+          "description": "Content block type"
+        }
+      }
+    },
+    "filter": {
+      "type": "object",
+      "description": "Filter to apply when loading entity data",
+      "required": ["field", "value"],
+      "additionalProperties": false,
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to filter on"
+        },
+        "value": {
+          "type": "string",
+          "description": "Filter value. Supports interpolation with route params (e.g., {courseId}, {course.id})"
+        }
+      }
+    },
+    "sort": {
+      "type": "object",
+      "description": "Default sort order for entity lists",
+      "required": ["field"],
+      "additionalProperties": false,
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name to sort by"
+        },
+        "direction": {
+          "type": "string",
+          "enum": ["asc", "desc"],
+          "default": "asc",
+          "description": "Sort direction"
+        }
+      }
+    }
+  }
+}

package/validators/index.js

@@ -0,0 +1,175 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { typesSchema, rolesSchema, appSchema, uiSchema, componentsSchema, themeSchema } from '../schemas/index.js';
+
+// Initialize AJV
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+
+// Compile validators
+const validators = {
+  types: ajv.compile(typesSchema),
+  roles: ajv.compile(rolesSchema),
+  app: ajv.compile(appSchema),
+  ui: ajv.compile(uiSchema),
+  components: ajv.compile(componentsSchema),
+  theme: ajv.compile(themeSchema)
+};
+
+/**
+ * Validate a blueprint against its schema
+ * @param {any} data - Parsed JSON data to validate
+ * @param {'types' | 'roles' | 'app' | 'ui' | 'components' | 'theme'} type - Schema type to validate against
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+export function validateBlueprint(data, type) {
+  const validate = validators[type];
+  if (!validate) {
+    throw new Error(`Unknown schema type: ${type}`);
+  }
+
+  const isValid = validate(data);
+
+  return {
+    valid: isValid,
+    errors: validate.errors || []
+  };
+}
+
+/**
+ * Get the raw JSON schemas
+ * @returns {{ types: object, roles: object, app: object, ui: object }}
+ */
+export function getSchemas() {
+  return {
+    types: typesSchema,
+    roles: rolesSchema,
+    app: appSchema,
+    ui: uiSchema,
+    components: componentsSchema,
+    theme: themeSchema
+  };
+}
+
+/**
+ * Format validation errors for display
+ * @param {Array} errors - AJV validation errors
+ * @returns {string} Formatted error message
+ */
+export function formatValidationErrors(errors) {
+  if (!errors || errors.length === 0) {
+    return 'No errors';
+  }
+
+  return errors
+    .map(err => {
+      const path = err.instancePath || '/';
+      const message = err.message;
+      const params = err.params ? JSON.stringify(err.params) : '';
+      return `${path}: ${message} ${params}`.trim();
+    })
+    .join('\n');
+}
+
+/**
+ * Parse a JSON string and validate against a schema
+ * @param {string} jsonString - Raw JSON string to parse and validate
+ * @param {'types' | 'roles' | 'app' | 'ui' | 'components' | 'theme'} type - Schema type to validate against
+ * @returns {{ valid: boolean, errors: Array, data: object|null }}
+ */
+export function validateFromJSON(jsonString, type) {
+  let data;
+  try {
+    data = JSON.parse(jsonString);
+  } catch (err) {
+    return {
+      valid: false,
+      errors: [{ instancePath: '/', message: `Invalid JSON: ${err.message}`, params: {} }],
+      data: null
+    };
+  }
+
+  const result = validateBlueprint(data, type);
+  return { ...result, data };
+}
+
+/**
+ * Convert a blueprint object to YAML string for display purposes
+ * @param {object} data - Blueprint data object
+ * @param {number} indent - Indentation level (default: 2)
+ * @returns {string} YAML-formatted string
+ */
+export function toYAML(data, indent = 2) {
+  return jsonToYaml(data, 0, indent);
+}
+
+/**
+ * Simple JSON-to-YAML converter for display purposes.
+ * No external dependencies required.
+ */
+function jsonToYaml(value, level, indent) {
+  const pad = ' '.repeat(level * indent);
+  const childPad = ' '.repeat((level + 1) * indent);
+
+  if (value === null || value === undefined) {
+    return 'null';
+  }
+
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+
+  if (typeof value === 'string') {
+    if (value.includes('\n') || value.includes(': ') || value.includes('#') ||
+        value.startsWith('{') || value.startsWith('[') || value.startsWith('"') ||
+        value.startsWith("'") || value === '' || value === 'true' || value === 'false' ||
+        value === 'null' || /^\d+(\.\d+)?$/.test(value)) {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    // Check if all items are simple (non-object) values
+    const allSimple = value.every(item => typeof item !== 'object' || item === null);
+    if (allSimple) {
+      const items = value.map(item => jsonToYaml(item, 0, indent));
+      if (items.join(', ').length < 80) {
+        return `[${items.join(', ')}]`;
+      }
+    }
+    return '\n' + value.map(item => {
+      if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+        const entries = Object.entries(item);
+        if (entries.length === 0) return `${childPad}- {}`;
+        const [firstKey, firstVal] = entries[0];
+        const firstLine = `${childPad}- ${firstKey}: ${jsonToYaml(firstVal, level + 2, indent)}`;
+        const rest = entries.slice(1).map(([k, v]) => {
+          return `${childPad}  ${k}: ${jsonToYaml(v, level + 2, indent)}`;
+        });
+        return [firstLine, ...rest].join('\n');
+      }
+      return `${childPad}- ${jsonToYaml(item, level + 1, indent)}`;
+    }).join('\n');
+  }
+
+  if (typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    return '\n' + entries.map(([key, val]) => {
+      const rendered = jsonToYaml(val, level + 1, indent);
+      if (typeof val === 'object' && val !== null && !Array.isArray(val) && Object.keys(val).length > 0) {
+        return `${childPad}${key}:${rendered}`;
+      }
+      if (Array.isArray(val) && val.length > 0 && val.some(item => typeof item === 'object' && item !== null)) {
+        return `${childPad}${key}:${rendered}`;
+      }
+      return `${childPad}${key}: ${rendered}`;
+    }).join('\n');
+  }
+
+  return String(value);
+}
+
+export { typesSchema, rolesSchema, appSchema, uiSchema, componentsSchema, themeSchema, validators };