Add interfaces[], defaultInterface, icon, and group fields to schemas

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/spec/src/ui/app.test.ts

@@ -605,3 +605,79 @@ describe('defineApp', () => {
     })).toThrow();
   });
 });
+
+describe('AppSchema with interfaces[] field', () => {
+  it('should accept app with interfaces array', () => {
+    const app = AppSchema.parse({
+      name: 'sales_app',
+      label: 'Sales App',
+      interfaces: ['sales_workspace', 'lead_review', 'sales_analytics'],
+    });
+
+    expect(app.interfaces).toHaveLength(3);
+    expect(app.interfaces).toEqual(['sales_workspace', 'lead_review', 'sales_analytics']);
+  });
+
+  it('should accept app with defaultInterface', () => {
+    const app = AppSchema.parse({
+      name: 'crm_app',
+      label: 'CRM',
+      interfaces: ['sales_workspace', 'lead_review'],
+      defaultInterface: 'sales_workspace',
+    });
+
+    expect(app.defaultInterface).toBe('sales_workspace');
+  });
+
+  it('should accept app with both interfaces and navigation', () => {
+    const app = AppSchema.parse({
+      name: 'modern_app',
+      label: 'Modern App',
+      interfaces: ['main_workspace', 'analytics'],
+      defaultInterface: 'main_workspace',
+      navigation: [
+        { id: 'nav_settings', label: 'Settings', type: 'page', pageName: 'admin_settings' },
+        { id: 'nav_help', label: 'Help', type: 'url', url: 'https://help.example.com' },
+      ],
+    });
+
+    expect(app.interfaces).toHaveLength(2);
+    expect(app.navigation).toHaveLength(2);
+    expect(app.defaultInterface).toBe('main_workspace');
+  });
+
+  it('should accept app without interfaces (backward compatibility)', () => {
+    const app = AppSchema.parse({
+      name: 'legacy_app',
+      label: 'Legacy App',
+      navigation: [
+        { id: 'nav_accounts', label: 'Accounts', type: 'object', objectName: 'account' },
+      ],
+    });
+
+    expect(app.interfaces).toBeUndefined();
+    expect(app.navigation).toHaveLength(1);
+  });
+
+  it('should accept empty interfaces array', () => {
+    const app = AppSchema.parse({
+      name: 'empty_app',
+      label: 'Empty App',
+      interfaces: [],
+    });
+
+    expect(app.interfaces).toHaveLength(0);
+  });
+
+  it('should accept defaultInterface without interfaces array', () => {
+    // This is technically allowed even though it may not be meaningful
+    const app = AppSchema.parse({
+      name: 'test_app',
+      label: 'Test App',
+      defaultInterface: 'some_interface',
+    });
+
+    expect(app.defaultInterface).toBe('some_interface');
+    expect(app.interfaces).toBeUndefined();
+  });
+});

packages/spec/src/ui/app.zod.ts

@@ -81,6 +81,11 @@ export const UrlNavItemSchema = BaseNavItemSchema.extend({
  * 5. Interface Navigation Item
  * Navigates to a specific Interface (self-contained multi-page surface).
  * Bridges AppSchema (navigation container) with InterfaceSchema (content surface).
+ * 
+ * **Note:** While this schema remains for backward compatibility, the preferred pattern
+ * is now to use `AppSchema.interfaces[]` to declare interfaces, which automatically
+ * generates a two-level Interface→Pages sidebar menu. This navigation item type is 
+ * retained for explicit interface navigation and global utility entries.
  */
 export const InterfaceNavItemSchema = BaseNavItemSchema.extend({
   type: z.literal('interface'),
@@ -152,16 +157,21 @@ export const AppBrandingSchema = z.object({
  * App Configuration Schema
  * Defines a business application container, including its navigation, branding, and permissions.
  * 
- * @example CRM App
+ * The new architecture makes App an "Interface switcher" where the sidebar content is 
+ * auto-generated from `interfaces[]`, rendering a two-level Interface→Pages menu. The 
+ * `navigation[]` field is retained for global utility entries only (Settings, Help, 
+ * external links) and is rendered at the bottom of the sidebar.
+ * 
+ * @example CRM App with new Interface-driven pattern
  * {
  *   name: "crm",
  *   label: "Sales CRM",
  *   icon: "briefcase",
+ *   interfaces: ["sales_workspace", "lead_review", "sales_analytics"],
+ *   defaultInterface: "sales_workspace",
  *   navigation: [
- *     { type: "object", id: "nav_leads", label: "Leads", objectName: "leads" },
- *     { type: "object", id: "nav_deals", label: "Deals", objectName: "deals" }
- *   ],
- *   requiredPermissions: ["app.crm.access"]
+ *     { type: "page", id: "nav_settings", label: "Settings", pageName: "admin_settings" }
+ *   ]
  * }
  */
 export const AppSchema = z.object({
@@ -190,10 +200,28 @@ export const AppSchema = z.object({
   isDefault: z.boolean().optional().default(false).describe('Is default app'),
 
   /** 
-   * Navigation Tree Structure.
-   * Replaces the old flat 'tabs' list with a structured menu.
+   * Interface names registered in this App.
+   * Sidebar renders as a two-level menu: Interface (collapsible group) → Pages (menu items).
+   * The runtime auto-generates the sidebar navigation from these interfaces and their pages.
+   */
+  interfaces: z.array(z.string()).optional()
+    .describe('Interface names available in this App. Sidebar renders as Interface→Pages two-level menu.'),
+
+  /** Default interface to activate on App launch */
+  defaultInterface: z.string().optional()
+    .describe('Default interface to show when the App opens'),
+  
+  /** 
+   * Navigation Tree Structure (Global Utility Entries Only).
+   * This field is now repurposed for global utility navigation items only (Settings, Help, 
+   * external links, etc.) that are rendered at the bottom of the sidebar. The main sidebar 
+   * content is auto-generated from `interfaces[]`.
+   * 
+   * For backward compatibility, this field remains optional and can still contain the full 
+   * navigation tree. However, the new recommended pattern is to use `interfaces[]` for 
+   * the main navigation and reserve this field for global utility entries.
    */
-  navigation: z.array(NavigationItemSchema).optional().describe('Structured navigation menu tree'),
+  navigation: z.array(NavigationItemSchema).optional().describe('Global utility navigation items (Settings, Help, external links) — rendered at bottom of sidebar'),
 
   /** 
    * App-level Home Page Override
@@ -241,7 +269,20 @@ export const App = {
  *
  * Validates the config at creation time using Zod `.parse()`.
  *
- * @example
+ * @example New Interface-driven pattern
+ * ```ts
+ * const crmApp = defineApp({
+ *   name: 'crm',
+ *   label: 'CRM',
+ *   interfaces: ['sales_workspace', 'lead_review', 'sales_analytics'],
+ *   defaultInterface: 'sales_workspace',
+ *   navigation: [
+ *     { id: 'nav_settings', label: 'Settings', type: 'page', pageName: 'settings' },
+ *   ],
+ * });
+ * ```
+ * 
+ * @example Legacy navigation tree pattern (backward compatible)
  * ```ts
  * const crmApp = defineApp({
  *   name: 'crm',

packages/spec/src/ui/interface.test.ts

@@ -403,6 +403,84 @@ describe('defineInterface', () => {
   });
 });
 
+describe('InterfaceSchema with icon and group fields', () => {
+  it('should accept interface with icon', () => {
+    const iface = InterfaceSchema.parse({
+      name: 'sales_workspace',
+      label: 'Sales Workspace',
+      icon: 'briefcase',
+      pages: [],
+    });
+
+    expect(iface.icon).toBe('briefcase');
+  });
+
+  it('should accept interface with group', () => {
+    const iface = InterfaceSchema.parse({
+      name: 'service_portal',
+      label: 'Service Portal',
+      group: 'Service Cloud',
+      pages: [],
+    });
+
+    expect(iface.group).toBe('Service Cloud');
+  });
+
+  it('should accept interface with both icon and group', () => {
+    const iface = InterfaceSchema.parse({
+      name: 'analytics_dashboard',
+      label: 'Analytics Dashboard',
+      icon: 'chart-bar',
+      group: 'Analytics',
+      pages: [],
+    });
+
+    expect(iface.icon).toBe('chart-bar');
+    expect(iface.group).toBe('Analytics');
+  });
+
+  it('should accept interface without icon or group (backward compatibility)', () => {
+    const iface = InterfaceSchema.parse({
+      name: 'legacy_interface',
+      label: 'Legacy Interface',
+      pages: [],
+    });
+
+    expect(iface.icon).toBeUndefined();
+    expect(iface.group).toBeUndefined();
+  });
+
+  it('should accept full interface with all new fields', () => {
+    const iface = InterfaceSchema.parse({
+      name: 'complete_interface',
+      label: 'Complete Interface',
+      description: 'Full-featured interface',
+      icon: 'layout-dashboard',
+      group: 'Sales Cloud',
+      object: 'opportunity',
+      pages: [
+        {
+          name: 'page_dashboard',
+          label: 'Dashboard',
+          type: 'dashboard',
+          regions: [],
+        },
+      ],
+      homePageName: 'page_dashboard',
+      branding: {
+        primaryColor: '#1A73E8',
+      },
+      assignedRoles: ['sales_rep'],
+      isDefault: true,
+    });
+
+    expect(iface.icon).toBe('layout-dashboard');
+    expect(iface.group).toBe('Sales Cloud');
+    expect(iface.object).toBe('opportunity');
+    expect(iface.pages).toHaveLength(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Content Elements in PageComponentType
 // ---------------------------------------------------------------------------

packages/spec/src/ui/interface.zod.ts

@@ -23,19 +23,38 @@ export const InterfaceBrandingSchema = AppBrandingSchema.extend({
  * an Interface is a focused, role-specific surface that stitches together
  * views, elements, and actions into a cohesive experience.
  *
- * An App can contain multiple Interfaces.
- *
- * Pages within an Interface use the unified `PageSchema` with interface page types
- * (dashboard, grid, kanban, record_review, etc.).
+ * An App can contain multiple Interfaces. When used with `AppSchema.interfaces[]`,
+ * the interface's `icon` and `group` properties control sidebar rendering.
  *
  * **NAMING CONVENTION:**
  * Interface names must be lowercase snake_case.
  *
- * @example
+ * @example Sales Workspace Interface
+ * ```ts
+ * const salesInterface = defineInterface({
+ *   name: 'sales_workspace',
+ *   label: 'Sales Workspace',
+ *   icon: 'briefcase',
+ *   group: 'Sales Cloud',
+ *   object: 'opportunity',
+ *   pages: [
+ *     {
+ *       name: 'pipeline',
+ *       label: 'Pipeline',
+ *       type: 'kanban',
+ *       object: 'opportunity',
+ *       regions: [],
+ *     },
+ *   ],
+ * });
+ * ```
+ * 
+ * @example Order Review Interface
  * ```ts
  * const reviewInterface = defineInterface({
  *   name: 'order_review',
  *   label: 'Order Review',
+ *   icon: 'clipboard-check',
  *   object: 'order',
  *   pages: [
  *     {
@@ -61,6 +80,14 @@ export const InterfaceSchema = z.object({
   label: I18nLabelSchema.describe('Interface display label'),
   description: I18nLabelSchema.optional().describe('Interface purpose description'),
 
+  /** Icon for sidebar display in the App's Interface→Pages menu */
+  icon: z.string().optional()
+    .describe('Icon name for sidebar display (Lucide icon)'),
+
+  /** Business group for sidebar grouping (rendered as a section separator label) */
+  group: z.string().optional()
+    .describe('Business group label for sidebar grouping (e.g. "Sales Cloud", "Service Cloud")'),
+
   /** Primary object binding */
   object: z.string().optional().describe('Primary object binding (snake_case)'),