@shanyucoder/flowgrid 0.1.0

package/templates/schemas/spec.schema.json

@@ -0,0 +1,718 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Portal Feature Spec",
+  "type": "object",
+  "required": ["id", "title", "requirements"],
+  "properties": {
+    "id": { "type": "string", "description": "Stable feature slug." },
+    "title": { "type": "string", "description": "Human-readable feature title." },
+    "status": { "type": "string", "description": "Feature lifecycle status." },
+    "owner": { "type": "string", "description": "Feature owner." },
+    "summary": { "type": "string", "description": "Short business summary." },
+    "userStories": {
+      "description": "Structured in-depth user stories and screen journey.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" },
+        { "type": "array" }
+      ]
+    },
+    "requirements": {
+      "type": "array",
+      "description": "Business requirements for the feature.",
+      "items": { "$ref": "#/$defs/requirement" }
+    },
+    "ui": {
+      "type": "object",
+      "description": "Frontend contract and page-level intent.",
+      "properties": {
+        "routes": {
+          "type": "array",
+          "description": "Canonical route entries for the feature.",
+          "items": { "$ref": "#/$defs/route" }
+        },
+        "list": {
+          "type": "object",
+          "description": "List page contract.",
+          "properties": {
+            "titleField": { "type": "string" },
+            "subtitleField": { "type": "string" },
+            "columns": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/listColumn" }
+            },
+            "filters": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/filterField" }
+            },
+            "rowActions": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/actionItem" }
+            },
+            "bulkActions": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/actionItem" }
+            },
+            "pagination": { "$ref": "#/$defs/pagination" },
+            "emptyState": { "$ref": "#/$defs/emptyState" }
+          },
+          "additionalProperties": true
+        },
+        "form": {
+          "type": "object",
+          "description": "Create/edit form contract.",
+          "properties": {
+            "layout": { "$ref": "#/$defs/formLayout" },
+            "sections": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/formSection" }
+            },
+            "fields": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/formField" }
+            },
+            "submit": { "$ref": "#/$defs/formSubmit" },
+            "emptyState": { "$ref": "#/$defs/emptyState" }
+          },
+          "additionalProperties": true
+        },
+        "detail": {
+          "type": "object",
+          "description": "Detail/read-only page contract.",
+          "properties": {
+            "header": { "$ref": "#/$defs/detailHeader" },
+            "sections": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/detailSection" }
+            },
+            "actions": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/actionItem" }
+            },
+            "emptyState": { "$ref": "#/$defs/emptyState" }
+          },
+          "additionalProperties": true
+        },
+        "validationMessages": {
+          "type": "object",
+          "description": "Common UI validation copy defaults for the feature.",
+          "$ref": "#/$defs/validationMessages"
+        },
+        "composition": { "type": "object" },
+        "filters": { "type": "array" },
+        "columns": { "type": "array" },
+        "testIds": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "design": {
+      "type": "object",
+      "description": "Page composition: nested sections, nav/sidebar, and on-screen items.",
+      "properties": {
+        "nav": { "$ref": "#/$defs/pageNav" },
+        "sections": {
+          "type": "array",
+          "description": "Nested visual tree (header / container / card / form / …).",
+          "items": { "$ref": "#/$defs/uiSection" }
+        },
+        "zones": {
+          "type": "array",
+          "description": "Flat fallback inventory. Prefer sections[] when the page has nested layout.",
+          "items": { "$ref": "#/$defs/uiSection" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "api": {
+      "type": "object",
+      "description": "Backend API contract.",
+      "additionalProperties": true
+    },
+    "acceptance": {
+      "type": "array",
+      "description": "Acceptance criteria.",
+      "items": { "type": "string" }
+    },
+    "notes": {
+      "type": "array",
+      "description": "Optional implementation notes.",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "requirement": {
+      "type": "object",
+      "required": ["id", "title", "description"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "priority": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "route": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string" },
+        "legacyPath": { "type": "string" },
+        "pageTestId": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "kindType": {
+      "type": "string",
+      "enum": [
+        "text",
+        "heading",
+        "search",
+        "select",
+        "multiselect",
+        "checkbox",
+        "radio",
+        "switch",
+        "button",
+        "link",
+        "badge",
+        "chip",
+        "table",
+        "column",
+        "pagination",
+        "toolbar",
+        "dialog",
+        "empty-state",
+        "icon",
+        "avatar",
+        "header",
+        "container",
+        "card",
+        "form",
+        "sidebar",
+        "nav",
+        "breadcrumb",
+        "locale-switcher",
+        "other"
+      ]
+    },
+    "widgetType": {
+      "type": "string",
+      "enum": [
+        "text",
+        "textarea",
+        "select",
+        "multiselect",
+        "radio",
+        "checkbox",
+        "date",
+        "number",
+        "switch",
+        "search",
+        "button",
+        "link",
+        "badge",
+        "chip",
+        "table",
+        "column",
+        "pagination",
+        "dialog",
+        "icon",
+        "avatar",
+        "heading",
+        "toolbar",
+        "empty-state",
+        "other"
+      ]
+    },
+    "variantType": {
+      "type": "string",
+      "enum": ["primary", "secondary", "destructive", "ghost", "outline", "link"]
+    },
+    "zoneItemCopy": {
+      "type": "object",
+      "properties": {
+        "placeholder": { "type": "string" },
+        "helper": { "type": "string" },
+        "empty": { "type": "string" },
+        "toast": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "uiVisual": {
+      "type": "object",
+      "description": "Surface CSS for BA/QA plus FE. Extra keys allowed.",
+      "properties": {
+        "primitive": { "type": "string", "description": "Shadcn primitive e.g. #ui: Card, #ui: Dialog, #ui: Table, #ui: Select, #ui: Form" },
+        "colorToken": { "type": "string", "description": "Theme color token e.g. #common:primary, #common:status-chip, bg-muted" },
+        "className": { "type": "string", "description": "Tailwind / CSS class string e.g. grid grid-cols-1 md:grid-cols-2 gap-4 border rounded-xl" },
+        "typography": { "type": "string", "description": "Font styling e.g. text-lg font-semibold tracking-tight" },
+        "variant": { "type": "string" },
+        "size": { "type": "string" },
+        "layoutMode": { "type": "string" },
+        "background": { "type": "string" },
+        "color": { "type": "string" },
+        "borderRadius": { "type": "string" },
+        "border": { "type": "string" },
+        "shadow": { "type": "string" },
+        "padding": { "type": "string" },
+        "margin": { "type": "string" },
+        "align": { "type": "string" },
+        "position": { "type": "string" },
+        "width": { "type": "string" },
+        "height": { "type": "string" },
+        "minWidth": { "type": "string" },
+        "minHeight": { "type": "string" },
+        "maxWidth": { "type": "string" },
+        "maxHeight": { "type": "string" },
+        "overflow": { "type": "string" },
+        "scroll": {}
+      },
+      "additionalProperties": true
+    },
+    "uiInteraction": {
+      "type": "object",
+      "description": "hover / blur / focus / active — copy for BA + CSS/behavior for FE.",
+      "properties": {
+        "hover": { "type": "object", "additionalProperties": true },
+        "blur": { "type": "object", "additionalProperties": true },
+        "focus": { "type": "object", "additionalProperties": true },
+        "active": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": true
+    },
+    "zoneItemBind": {
+      "type": "object",
+      "properties": {
+        "field": { "type": "string" },
+        "columnKey": { "type": "string" },
+        "actionId": { "type": "string" },
+        "apiRef": { "type": "string" },
+        "hidden": { "type": "boolean" },
+        "default": {}
+      },
+      "additionalProperties": true
+    },
+    "zoneItemStates": {
+      "type": "object",
+      "properties": {
+        "visibleWhen": { "type": "string" },
+        "disabledWhen": { "type": "string" },
+        "hiddenWhen": { "type": "string" },
+        "loadingWhen": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "dbMapping": {
+      "type": "object",
+      "description": "Database schema mapping for backend integration",
+      "properties": {
+        "schema": { "type": "string" },
+        "field": { "type": "string" },
+        "enumMapping": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": true
+    },
+    "zoneItem": {
+      "type": "object",
+      "required": ["id", "kind", "label"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "$ref": "#/$defs/kindType" },
+        "label": { "type": "string" },
+        "meaning": { "type": "string" },
+        "purpose": { "type": "string" },
+        "copy": { "$ref": "#/$defs/zoneItemCopy" },
+        "widget": { "$ref": "#/$defs/widgetType" },
+        "variant": { "$ref": "#/$defs/variantType" },
+        "color": { "type": "string" },
+        "icon": { "type": "string" },
+        "position": { "type": "string" },
+        "visual": { "$ref": "#/$defs/uiVisual" },
+        "interaction": { "$ref": "#/$defs/uiInteraction" },
+        "validation": { "$ref": "#/$defs/fieldValidation" },
+        "messages": { "$ref": "#/$defs/fieldMessages" },
+        "bind": { "$ref": "#/$defs/zoneItemBind" },
+        "db": { "$ref": "#/$defs/dbMapping" },
+        "states": { "$ref": "#/$defs/zoneItemStates" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "extract": { "type": "string" },
+        "apiRefs": { "type": "array", "items": { "type": "string" } },
+        "hidden": { "type": "boolean" },
+        "testId": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "navNode": {
+      "type": "object",
+      "required": ["id", "label"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "href": { "type": "string" },
+        "icon": { "type": "string" },
+        "active": { "type": "boolean" },
+        "children": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/navNode" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "pageNav": {
+      "type": "object",
+      "properties": {
+        "sidebar": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "position": { "type": "string" },
+            "purpose": { "type": "string" },
+            "levels": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/navNode" }
+            }
+          },
+          "additionalProperties": true
+        },
+        "breadcrumb": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": { "type": "string" },
+              "href": { "type": "string" }
+            },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "uiSection": {
+      "type": "object",
+      "required": ["id", "label"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "$ref": "#/$defs/kindType" },
+        "label": { "type": "string" },
+        "meaning": { "type": "string" },
+        "purpose": { "type": "string" },
+        "primitive": { "type": "string", "description": "Shadcn primitive tag e.g. #ui: Card, #ui: Dialog, #ui: Table, #ui: Form, #ui: Select, #ui: Badge" },
+        "visual": { "$ref": "#/$defs/uiVisual" },
+        "interaction": { "$ref": "#/$defs/uiInteraction" },
+        "dynamicProps": { "type": "object", "description": "Dynamic section props e.g. layout mode, responsive breakpoint, theme tokens, state handlers" },
+        "validation": { "$ref": "#/$defs/fieldValidation" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Component/API tags, e.g. #needs-component: BlockName"
+        },
+        "extract": { "type": "string" },
+        "apiRefs": { "type": "array", "items": { "type": "string" } },
+        "hidden": { "type": "boolean" },
+        "position": {},
+        "container": { "type": "object" },
+        "hint": { "type": "string" },
+        "notes": { "type": "string" },
+        "items": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/zoneItem" }
+        },
+        "sections": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/uiSection" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "zone": { "$ref": "#/$defs/uiSection" },
+    "listColumn": {
+      "type": "object",
+      "required": ["key"],
+      "properties": {
+        "key": { "type": "string" },
+        "title": { "type": "string" },
+        "meaning": { "type": "string" },
+        "purpose": { "type": "string" },
+        "widget": { "$ref": "#/$defs/widgetType" },
+        "variant": { "$ref": "#/$defs/variantType" },
+        "color": { "type": "string" },
+        "sortable": { "type": "boolean" },
+        "render": { "type": "string" },
+        "component": { "type": "string" },
+        "componentProp": { "type": "string" },
+        "db": { "$ref": "#/$defs/dbMapping" }
+      },
+      "additionalProperties": true
+    },
+    "filterField": {
+      "type": "object",
+      "required": ["name", "label", "type"],
+      "properties": {
+        "name": { "type": "string" },
+        "label": { "type": "string" },
+        "meaning": { "type": "string" },
+        "purpose": { "type": "string" },
+        "type": { "type": "string" },
+        "widget": { "$ref": "#/$defs/widgetType" },
+        "color": { "type": "string" },
+        "placeholder": { "type": "string" },
+        "source": { "$ref": "#/$defs/fieldSource" },
+        "db": { "$ref": "#/$defs/dbMapping" },
+        "validation": { "$ref": "#/$defs/fieldValidation" },
+        "messages": { "$ref": "#/$defs/fieldMessages" }
+      },
+      "additionalProperties": true
+    },
+    "actionItem": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "text": { "type": "string" },
+        "label": { "type": "string" },
+        "meaning": { "type": "string" },
+        "purpose": { "type": "string" },
+        "icon": { "type": "string" },
+        "variant": { "$ref": "#/$defs/variantType" },
+        "color": { "type": "string" },
+        "position": { "type": "string" },
+        "testId": { "type": "string" },
+        "testIdPattern": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "pagination": {
+      "type": "object",
+      "properties": {
+        "defaultPageSize": { "type": "number" },
+        "pageSizeOptions": {
+          "type": "array",
+          "items": { "type": "number" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "emptyState": {
+      "type": "object",
+      "properties": {
+        "title": { "type": "string" },
+        "message": { "type": "string" },
+        "ctaText": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "formLayout": {
+      "type": "object",
+      "properties": {
+        "mode": { "type": "string" },
+        "sections": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/formSection" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "formSection": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "fields": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/formFieldRef" }
+        },
+        "columns": { "type": "number" },
+        "notes": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "detailHeader": {
+      "type": "object",
+      "properties": {
+        "titleField": { "type": "string" },
+        "subtitleField": { "type": "string" },
+        "badges": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "detailSection": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "fields": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/detailFieldRef" }
+        },
+        "notes": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "formFieldRef": {
+      "type": "string"
+    },
+    "detailFieldRef": {
+      "oneOf": [
+        { "type": "string" },
+        { "$ref": "#/$defs/detailFieldObject" }
+      ]
+    },
+    "detailFieldObject": {
+      "type": "object",
+      "required": ["key"],
+      "properties": {
+        "key": { "type": "string" },
+        "label": { "type": "string" },
+        "render": { "type": "string" },
+        "helpText": { "type": "string" },
+        "db": { "$ref": "#/$defs/dbMapping" }
+      },
+      "additionalProperties": true
+    },
+    "formField": {
+      "type": "object",
+      "required": ["key", "label", "type"],
+      "properties": {
+        "key": { "type": "string" },
+        "label": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["string", "int", "bool", "date", "array", "object"]
+        },
+        "widget": { "$ref": "#/$defs/widgetType" },
+        "purpose": { "type": "string" },
+        "variant": { "$ref": "#/$defs/variantType" },
+        "color": { "type": "string" },
+        "required": { "type": "boolean" },
+        "nullable": { "type": "boolean" },
+        "readonly": { "type": "boolean" },
+        "disabled": { "type": "boolean" },
+        "multiple": { "type": "boolean" },
+        "placeholder": { "type": "string" },
+        "helpText": { "type": "string" },
+        "default": {},
+        "validation": { "$ref": "#/$defs/fieldValidation" },
+        "messages": { "$ref": "#/$defs/fieldMessages" },
+        "source": { "$ref": "#/$defs/fieldSource" },
+        "db": { "$ref": "#/$defs/dbMapping" },
+        "dependsOn": { "$ref": "#/$defs/fieldDependsOn" }
+      },
+      "additionalProperties": true
+    },
+    "fieldValidation": {
+      "type": "object",
+      "properties": {
+        "min": { "type": "number" },
+        "max": { "type": "number" },
+        "minLength": { "type": "number" },
+        "maxLength": { "type": "number" },
+        "pattern": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "fieldMessages": {
+      "type": "object",
+      "properties": {
+        "required": { "type": "string" },
+        "min": { "type": "string" },
+        "max": { "type": "string" },
+        "minLength": { "type": "string" },
+        "maxLength": { "type": "string" },
+        "pattern": { "type": "string" },
+        "type": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "fieldSource": {
+      "type": "object",
+      "required": ["kind", "ref"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["enum", "master_list", "relation", "api"]
+        },
+        "ref": { "type": "string" },
+        "valueKey": { "type": "string" },
+        "labelKey": { "type": "string" },
+        "path": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "fieldDependsOn": {
+      "type": "object",
+      "properties": {
+        "field": { "type": "string" },
+        "value": {}
+      },
+      "additionalProperties": true
+    },
+    "formSubmit": {
+      "type": "object",
+      "properties": {
+        "label": { "type": "string" },
+        "testId": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "validationMessages": {
+      "type": "object",
+      "properties": {
+        "required": { "type": "string" },
+        "email": { "type": "string" },
+        "phone": { "type": "string" },
+        "minLength": { "type": "string" },
+        "maxLength": { "type": "string" },
+        "min": { "type": "string" },
+        "max": { "type": "string" },
+        "pattern": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "screenAccess": {
+      "type": "object",
+      "properties": {
+        "accessType": {
+          "type": "string",
+          "enum": ["directRoute", "sidebarMenu", "contextualAction"]
+        },
+        "directRoute": {
+          "type": "object",
+          "properties": {
+            "routePath": { "type": "string" },
+            "isPublic": { "type": "boolean" },
+            "urlParams": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "sidebarMenu": {
+          "type": "object",
+          "properties": {
+            "menuHierarchy": { "type": "array", "items": { "type": "string" } },
+            "menuLabel": { "type": "string" },
+            "icon": { "type": "string" },
+            "badge": { "type": "string" }
+          }
+        },
+        "contextualAction": {
+          "type": "object",
+          "properties": {
+            "sourceScreen": { "type": "string" },
+            "triggerControl": { "type": "string" },
+            "navigationType": {
+              "type": "string",
+              "enum": ["pageRedirect", "modalDialog", "drawer", "tabSwitch"]
+            },
+            "inputsReceived": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}