Refactor app metadata: rename 'name' to 'label', update menu types

hotlong · hotlong · commit 782641e426a9 · 2026-01-10T01:57:03.000+08:00
Standardizes app metadata by renaming the display property from 'name' to 'label' and making 'name' the unique identifier. Updates documentation, example YAML, and TypeScript types accordingly. Improves menu item and section typing, adds default values, and refines sidebar menu rendering logic for robustness and consistency.
diff --git a/docs/spec/metadata-format.md b/docs/spec/metadata-format.md
@@ -212,8 +212,8 @@ App files define application interfaces with custom navigation menus, similar to
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `code` | `string` | Unique identifier for the app, default to id if not specified. |
-| `name` | `string` | **Required.** Display name of the app. |
+| `name` | `string` | Unique identifier for the app, default to id if not specified. |
+| `label` | `string` | **Required.** Display name of the app. |
 | `description` | `string` | Description of the app's purpose. |
 | `icon` | `string` | Icon identifier (e.g., `ri-dashboard-line`). |
 | `color` | `string` | Color theme for the app (e.g., `blue`, `gray`). |
@@ -283,8 +283,8 @@ The `menu` property defines the left-side navigation structure. It can be either
 ### 6.4 Complete App Example
 
 ```yaml
-code: projects
-name: Project Management
+name: projects
+label: Project Management
 description: Manage and track your projects efficiently.
 icon: ri-dashboard-line
 color: blue
diff --git a/examples/project-management/src/projects.app.yml b/examples/project-management/src/projects.app.yml
@@ -1,8 +1,9 @@
 # ==========================================
 # 1. 应用基础信息 (App Identity)
 # ==========================================
-code: projects
-name: Projects Management
+
+name: projects
+label: Projects Management
 description: Manage and track your projects efficiently.
 dark: true
 color: gray
diff --git a/packages/client/src/App.tsx b/packages/client/src/App.tsx
@@ -1,4 +1,4 @@
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef } from 'react';
 import AppList from './pages/AppList';
 import Login from './pages/Login';
 import Dashboard from './pages/Dashboard';
@@ -26,7 +26,7 @@ function AppContent() {
       if (parts[1] === 'app' && parts[2]) {
           const appName = parts[2];
           // Simple cache check/avoid refetch if same app
-          if (currentAppMetadata && (currentAppMetadata.id === appName || currentAppMetadata.content?.code === appName)) {
+          if (currentAppMetadata && (currentAppMetadata.name === appName || currentAppMetadata.id === appName)) {
               return;
           }
           
diff --git a/packages/client/src/components/app-sidebar.tsx b/packages/client/src/components/app-sidebar.tsx
@@ -34,12 +34,13 @@ export function AppSidebar({ objects, appMetadata, ...props }: React.ComponentPr
   const currentApp = parts[1] === 'app' ? parts[2] : null;
   const getObjectPath = (name: string) => currentApp ? `/app/${currentApp}/object/${name}` : `/object/${name}`;
   
-  const rawMenu = appMetadata?.content?.menu;
+  const rawMenu = appMetadata?.menu;
   
-  // Normalize menu structure to always be a list of sections (groups)
-  // If the first item has a 'type' or doesn't look like a section container, wrap it in a default section.
-  const isGrouped = Array.isArray(rawMenu) && rawMenu.length > 0 && 
-                    (rawMenu[0].items && !rawMenu[0].type); 
+  // Robust check for grouped vs flat menu structure
+  // A section has 'items' but NO 'type', 'object', or 'url'
+  const isSection = (item: any) => item && item.items && Array.isArray(item.items) && !item.type && !item.object && !item.url;
+
+  const isGrouped = Array.isArray(rawMenu) && rawMenu.length > 0 && isSection(rawMenu[0]);
   
   const menuSections = rawMenu ? (isGrouped ? rawMenu : [{ label: 'Menu', items: rawMenu }]) : [];
 
@@ -51,48 +52,53 @@ export function AppSidebar({ objects, appMetadata, ...props }: React.ComponentPr
         return <div key={idx} className="my-2 h-px bg-border" />;
     }
 
+    // Default label if missing (e.g. for dividers context or malformed data)
+    const label = item.label || '';
+    const itemType = item.type || 'page';
+
     // Determine active state
     let isActive = false;
-    if (item.type === 'object') {
+    if (itemType === 'object') {
         isActive = path.includes(`/object/${item.object}`);
-    } else if (item.type === 'page' || item.type === 'url') {
+    } else if (itemType === 'page' || itemType === 'url') {
         isActive = item.url ? path.endsWith(item.url) : false;
     }
 
     const handleClick = () => {
-        if (item.type === 'object' && item.object) {
+        if (itemType === 'object' && item.object) {
             navigate(getObjectPath(item.object));
-        } else if (item.type === 'page' && item.url) {
+        } else if (itemType === 'page' && item.url) {
             navigate(item.url);
-        } else if (item.type === 'url' && item.url) {
+        } else if (itemType === 'url' && item.url) {
            window.open(item.url, '_blank');
         }
     };
 
     // Handle Nested Items (Submenus)
     if (item.items && item.items.length > 0) {
         return (
-            <Collapsible key={idx} asChild defaultOpen={item.collapsed === false} className="group/collapsible">
+            <Collapsible key={idx} asChild defaultOpen={false} className="group/collapsible">
                 <SidebarMenuItem>
                     <CollapsibleTrigger asChild>
-                        <SidebarMenuButton tooltip={item.label}>
-                             <DynamicIcon name={item.icon} fallback={item.type === 'object' ? LucideIcons.FileText : LucideIcons.Layout} />
-                             <span>{item.label}</span>
+                        <SidebarMenuButton tooltip={label}>
+                             <DynamicIcon name={item.icon} fallback={itemType === 'object' ? LucideIcons.FileText : LucideIcons.Layout} />
+                             <span>{label}</span>
                              <LucideIcons.ChevronRight className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
                         </SidebarMenuButton>
                     </CollapsibleTrigger>
                     <CollapsibleContent>
                         <SidebarMenuSub>
                             {item.items.map((subItem: any, subIdx: number) => {
                                 if (subItem.visible === false) return null;
+                                const subItemType = subItem.type || 'page';
                                 return (
                                 <SidebarMenuSubItem key={subIdx}>
                                     <SidebarMenuSubButton 
-                                        isActive={subItem.type === 'object' ? path.includes(`/object/${subItem.object}`) : path.endsWith(subItem.url)}
+                                        isActive={subItemType === 'object' ? path.includes(`/object/${subItem.object}`) : path.endsWith(subItem.url)}
                                         onClick={() => {
-                                            if (subItem.type === 'object') navigate(getObjectPath(subItem.object));
-                                            else if (subItem.type === 'page') navigate(subItem.url);
-                                            else if (subItem.type === 'url') window.open(subItem.url, '_blank');
+                                            if (subItemType === 'object') navigate(getObjectPath(subItem.object));
+                                            else if (subItemType === 'page') navigate(subItem.url);
+                                            else if (subItemType === 'url') window.open(subItem.url, '_blank');
                                         }}
                                     >
                                         <span>{subItem.label}</span>
@@ -114,8 +120,8 @@ export function AppSidebar({ objects, appMetadata, ...props }: React.ComponentPr
                 isActive={isActive}
                 onClick={handleClick}
             >
-                <DynamicIcon name={item.icon} fallback={item.type === 'object' ? LucideIcons.FileText : LucideIcons.Layout} />
-                <span>{item.label}</span>
+                <DynamicIcon name={item.icon} fallback={itemType === 'object' ? LucideIcons.FileText : LucideIcons.Layout} />
+                <span>{label}</span>
                 {item.badge && <SidebarMenuBadge>{item.badge}</SidebarMenuBadge>}
             </SidebarMenuButton>
         </SidebarMenuItem>
@@ -132,16 +138,15 @@ export function AppSidebar({ objects, appMetadata, ...props }: React.ComponentPr
                 <LucideIcons.Database className="size-4" />
               </div>
               <div className="grid flex-1 text-left text-sm leading-tight">
-                <span className="truncate font-semibold">{appMetadata?.content?.name || 'ObjectQL'}</span>
+                <span className="truncate font-semibold">{appMetadata?.name || 'ObjectQL'}</span>
                 <span className="truncate text-xs">Data Browser</span>
               </div>
             </SidebarMenuButton>
           </SidebarMenuItem>
         </SidebarMenu>
       </SidebarHeader>
       <SidebarContent>
-        {menuSections.length > 0 ? (
-            menuSections.map((section: any, idx: number) => {
+        {menuSections.map((section: any, idx: number) => {
                 const isCollapsible = section.collapsible === true;
                 const isCollapsed = section.collapsed === true;
                 
@@ -184,28 +189,7 @@ export function AppSidebar({ objects, appMetadata, ...props }: React.ComponentPr
                         </SidebarGroupContent>
                     </SidebarGroup>
                 );
-            })
-        ) : (
-            // Render Default Object List
-            <SidebarGroup>
-            <SidebarGroupLabel>Collections</SidebarGroupLabel>
-            <SidebarGroupContent>
-                <SidebarMenu>
-                {Object.entries(objects).map(([name, schema]) => (
-                    <SidebarMenuItem key={name}>
-                    <SidebarMenuButton 
-                        isActive={path.includes(`/object/${name}`)}
-                        onClick={() => navigate(getObjectPath(name))}
-                        >
-                        <LucideIcons.FileText />
-                        <span>{schema.label || schema.title || name}</span>
-                    </SidebarMenuButton>
-                    </SidebarMenuItem>
-                ))}
-                </SidebarMenu>
-            </SidebarGroupContent>
-            </SidebarGroup>
-        )}
+            })}
       </SidebarContent>
       <SidebarFooter>
          <NavUser user={{
diff --git a/packages/client/src/pages/Dashboard.tsx b/packages/client/src/pages/Dashboard.tsx
@@ -70,7 +70,6 @@ export default function Dashboard() {
                         });
                     }
                     
-                    const objNames = Object.keys(objectsMap);
                     setObjects(objectsMap);
                     // Auto-redirect removed to show App List
                     setLoading(false);
diff --git a/packages/metadata/src/plugins/objectql.ts b/packages/metadata/src/plugins/objectql.ts
@@ -37,7 +37,7 @@ export function registerObjectQLPlugins(loader: MetadataLoader) {
         handler: (ctx) => {
             try {
                 const doc = yaml.load(ctx.content) as any;
-                const id = doc.id || doc.name;
+                const id = doc.code || doc.id || doc.name;
                 if (id) {
                     ctx.registry.register('app', {
                         type: 'app',
diff --git a/packages/metadata/src/types.ts b/packages/metadata/src/types.ts
@@ -119,19 +119,19 @@ export interface ObjectConfig {
 export interface AppMenuItem {
     /** Unique identifier for the menu item */
     id?: string;
-    /** Display label for the menu item */
-    label?: string;
+    /** **Required.** Display label for the menu item */
+    label: string;
     /** Icon identifier (e.g., remixicon class name like 'ri-home-line') */
     icon?: string;
-    /** Type of menu item */
+    /** Type of menu item. Default: 'page' */
     type?: 'object' | 'page' | 'url' | 'divider';
     /** Reference to an object name (for type: 'object') */
     object?: string;
     /** URL path (for type: 'url' or 'page') */
     url?: string;
     /** Badge text or count to display */
     badge?: string | number;
-    /** Whether this item is visible */
+    /** Whether this item is visible. Default: true */
     visible?: boolean;
     /** Nested sub-menu items */
     items?: AppMenuItem[];
@@ -145,9 +145,9 @@ export interface AppMenuSection {
     label?: string;
     /** **Required.** Menu items in this section. */
     items: AppMenuItem[];
-    /** Whether this section is collapsible */
+    /** Whether this section is collapsible. Default: false */
     collapsible?: boolean;
-    /** Whether this section is collapsed by default */
+    /** Whether this section is collapsed by default. Default: false */
     collapsed?: boolean;
 }
 
@@ -171,22 +171,24 @@ export function isAppMenuSection(entry: AppMenuSection | AppMenuItem): entry is
 export interface AppConfig {
     /** Unique identifier or code for the app */
     id?: string;
-    /** App name */
+    /** App name. Unique identifier for the app, default to id if not specified. */
     name: string;
-    /** App code/slug */
+    /** App code/slug (Legacy, use name or id) */
     code?: string;
-    /** Description of the app */
+    /** **Required.** Display name of the app. */
+    label: string;
+    /** Description of the app's purpose. */
     description?: string;
-    /** App icon identifier */
+    /** Icon identifier (e.g., `ri-dashboard-line`). */
     icon?: string;
-    /** Color theme for the app */
+    /** Color theme for the app (e.g., `blue`, `gray`). */
     color?: string;
-    /** Dark mode preference */
+    /** Whether to use dark mode by default. */
     dark?: boolean;
     /** Base ID this app belongs to (optional, for Base layer support) */
     baseId?: string;
     /** 
-     * Left-side menu configuration.
+     * Left-side navigation menu configuration.
      * Can be either:
      * - An array of menu sections (recommended for organized menus with groups)
      * - An array of menu items (for simple flat menus)

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,6 @@ export default function Dashboard() {`
`70`	`70`	`});`
`71`	`71`	`}`
`72`	`72`
`73`		`- const objNames = Object.keys(objectsMap);`
`74`	`73`	`setObjects(objectsMap);`
`75`	`74`	`// Auto-redirect removed to show App List`
`76`	`75`	`setLoading(false);`