@object-ui/components 0.5.0 → 2.0.0

package/src/renderers/layout/page.tsx

@@ -1,53 +1,396 @@
 /**
- * ObjectUI
+ * ObjectUI — Page Renderer
  * Copyright (c) 2024-present ObjectStack Inc.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
+ *
+ * The Page renderer interprets PageSchema into structured layouts.
+ * It supports four page types (record, home, app, utility) and
+ * renders named regions (header, sidebar, main, footer, aside) with
+ * configurable widths. When no regions are defined, it falls back to
+ * body/children for backward compatibility.
  */
 
-import React from 'react';
-import { PageSchema } from '@object-ui/types';
-import { SchemaRenderer } from '@object-ui/react';
+import React, { useMemo } from 'react';
+import type { PageSchema, PageRegion, SchemaNode } from '@object-ui/types';
+import { SchemaRenderer, PageVariablesProvider } from '@object-ui/react';
 import { ComponentRegistry } from '@object-ui/core';
-import { cn } from '../../lib/utils'; // Keep internal import for utils
-
-export const PageRenderer: React.FC<{ schema: PageSchema; className?: string; [key: string]: any }> = ({ 
-  schema, 
-  className,
-  ...props 
-}) => {
-  // Support regions (spec compliant), body (legacy), and children
-  let nodes: any[] = [];
-  
+import { cn } from '../../lib/utils';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Map region width enum values to Tailwind width classes */
+function getRegionWidthClass(width?: string): string {
+  switch (width) {
+    case 'small':
+      return 'w-64';
+    case 'medium':
+      return 'w-80';
+    case 'large':
+      return 'w-96';
+    case 'full':
+      return 'w-full';
+    default:
+      return width ? width : 'w-full';
+  }
+}
+
+/** Max-width constraint by page type */
+function getPageMaxWidth(pageType?: string): string {
+  switch (pageType) {
+    case 'utility':
+      return 'max-w-4xl';
+    case 'home':
+      return 'max-w-screen-2xl';
+    case 'app':
+      return 'max-w-screen-xl';
+    case 'record':
+    default:
+      return 'max-w-7xl';
+  }
+}
+
+/** Find a named region (case-insensitive) */
+function findRegion(regions: PageRegion[] | undefined, name: string): PageRegion | undefined {
+  return regions?.find((r) => r.name?.toLowerCase() === name.toLowerCase());
+}
+
+/** Get all regions that are NOT in the named set */
+function getRemainingRegions(regions: PageRegion[] | undefined, exclude: string[]): PageRegion[] {
+  if (!regions) return [];
+  const lowerSet = new Set(exclude.map((n) => n.toLowerCase()));
+  return regions.filter((r) => !lowerSet.has(r.name?.toLowerCase() ?? ''));
+}
+
+// ---------------------------------------------------------------------------
+// RegionContent — renders all components inside a single region
+// ---------------------------------------------------------------------------
+
+const RegionContent: React.FC<{
+  region: PageRegion;
+  className?: string;
+}> = ({ region, className }) => {
+  const components = region.components || [];
+  if (components.length === 0) return null;
+
+  return (
+    <div
+      className={cn('space-y-4', region.className, className)}
+      data-region={region.name}
+    >
+      {components.map((node: SchemaNode, idx: number) => (
+        <SchemaRenderer key={(node as any)?.id || `${region.name}-${idx}`} schema={node} />
+      ))}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// RegionLayout — structured layout with named slots
+// ---------------------------------------------------------------------------
+
+const RegionLayout: React.FC<{
+  regions: PageRegion[];
+  pageType?: string;
+  className?: string;
+}> = ({ regions, pageType, className }) => {
+  const header = findRegion(regions, 'header');
+  const sidebar = findRegion(regions, 'sidebar');
+  const main = findRegion(regions, 'main');
+  const aside = findRegion(regions, 'aside');
+  const footer = findRegion(regions, 'footer');
+
+  // Remaining regions that don't match named slots → append below main
+  const extras = getRemainingRegions(regions, ['header', 'sidebar', 'main', 'aside', 'footer']);
+
+  // If there's no named layout structure, just stack everything
+  const hasStructure = header || sidebar || main || aside || footer;
+  if (!hasStructure) {
+    return (
+      <div className={cn('space-y-6', className)} data-page-layout={pageType}>
+        {regions.map((region, idx) => (
+          <RegionContent key={region.name || idx} region={region} />
+        ))}
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn('flex flex-col gap-6', className)} data-page-layout={pageType}>
+      {/* Header region */}
+      {header && (
+        <RegionContent
+          region={header}
+          className={cn(getRegionWidthClass(header.width as string))}
+        />
+      )}
+
+      {/* Body: sidebar + main + aside */}
+      <div className="flex flex-1 gap-6">
+        {sidebar && (
+          <aside className={cn('shrink-0', getRegionWidthClass(sidebar.width as string || 'small'))}>
+            <RegionContent region={sidebar} />
+          </aside>
+        )}
+
+        <div className="flex-1 min-w-0 space-y-6">
+          {main && <RegionContent region={main} />}
+          {extras.map((region, idx) => (
+            <RegionContent key={region.name || `extra-${idx}`} region={region} />
+          ))}
+        </div>
+
+        {aside && (
+          <aside className={cn('shrink-0', getRegionWidthClass(aside.width as string || 'small'))}>
+            <RegionContent region={aside} />
+          </aside>
+        )}
+      </div>
+
+      {/* Footer region */}
+      {footer && (
+        <RegionContent
+          region={footer}
+          className={cn(getRegionWidthClass(footer.width as string))}
+        />
+      )}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// FlatContent — legacy body/children fallback
+// ---------------------------------------------------------------------------
+
+const FlatContent: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  const content = schema.body || schema.children;
+  const nodes: SchemaNode[] = Array.isArray(content)
+    ? content
+    : content
+      ? [content as SchemaNode]
+      : [];
+
+  if (nodes.length === 0) return null;
+
+  return (
+    <div className="space-y-6">
+      {nodes.map((node: any, index: number) => (
+        <SchemaRenderer key={node?.id || index} schema={node} />
+      ))}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Template layouts — predefined layout templates
+// ---------------------------------------------------------------------------
+
+/** Template: full-width single column */
+const FullWidthTemplate: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  if (schema.regions && schema.regions.length > 0) {
+    return <RegionLayout regions={schema.regions} pageType={schema.pageType} />;
+  }
+  return <FlatContent schema={schema} />;
+};
+
+/** Template: header-sidebar-main — header spanning full width, sidebar + main below */
+const HeaderSidebarMainTemplate: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  const regions = schema.regions || [];
+  if (regions.length === 0) return <FlatContent schema={schema} />;
+
+  const header = findRegion(regions, 'header');
+  const sidebar = findRegion(regions, 'sidebar');
+  const main = findRegion(regions, 'main');
+  const extras = getRemainingRegions(regions, ['header', 'sidebar', 'main']);
+
+  return (
+    <div className="flex flex-col gap-6" data-template="header-sidebar-main">
+      {header && <RegionContent region={header} />}
+      <div className="flex flex-1 gap-6">
+        {sidebar && (
+          <aside className={cn('shrink-0', getRegionWidthClass(sidebar.width as string || 'medium'))}>
+            <RegionContent region={sidebar} />
+          </aside>
+        )}
+        <div className="flex-1 min-w-0 space-y-6">
+          {main && <RegionContent region={main} />}
+          {extras.map((region, idx) => (
+            <RegionContent key={region.name || `extra-${idx}`} region={region} />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+/** Template: three-column — sidebar + main + aside */
+const ThreeColumnTemplate: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  const regions = schema.regions || [];
+  if (regions.length === 0) return <FlatContent schema={schema} />;
+
+  const header = findRegion(regions, 'header');
+  const sidebar = findRegion(regions, 'sidebar');
+  const main = findRegion(regions, 'main');
+  const aside = findRegion(regions, 'aside');
+  const footer = findRegion(regions, 'footer');
+  const extras = getRemainingRegions(regions, ['header', 'sidebar', 'main', 'aside', 'footer']);
+
+  return (
+    <div className="flex flex-col gap-6" data-template="three-column">
+      {header && <RegionContent region={header} />}
+      <div className="flex flex-1 gap-6">
+        {sidebar && (
+          <aside className={cn('shrink-0', getRegionWidthClass(sidebar.width as string || 'small'))}>
+            <RegionContent region={sidebar} />
+          </aside>
+        )}
+        <div className="flex-1 min-w-0 space-y-6">
+          {main && <RegionContent region={main} />}
+          {extras.map((region, idx) => (
+            <RegionContent key={region.name || `extra-${idx}`} region={region} />
+          ))}
+        </div>
+        {aside && (
+          <aside className={cn('shrink-0', getRegionWidthClass(aside.width as string || 'small'))}>
+            <RegionContent region={aside} />
+          </aside>
+        )}
+      </div>
+      {footer && <RegionContent region={footer} />}
+    </div>
+  );
+};
+
+/** Template: dashboard — 2x2 grid of regions */
+const DashboardTemplate: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  const regions = schema.regions || [];
+  if (regions.length === 0) return <FlatContent schema={schema} />;
+
+  const header = findRegion(regions, 'header');
+  const footer = findRegion(regions, 'footer');
+  const contentRegions = getRemainingRegions(regions, ['header', 'footer']);
+
+  return (
+    <div className="flex flex-col gap-6" data-template="dashboard">
+      {header && <RegionContent region={header} />}
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        {contentRegions.map((region, idx) => (
+          <RegionContent key={region.name || `region-${idx}`} region={region} />
+        ))}
+      </div>
+      {footer && <RegionContent region={footer} />}
+    </div>
+  );
+};
+
+/** Template registry — maps template names to layout components */
+const TEMPLATE_REGISTRY: Record<string, React.FC<{ schema: PageSchema }>> = {
+  'default': FullWidthTemplate,
+  'full-width': FullWidthTemplate,
+  'header-sidebar-main': HeaderSidebarMainTemplate,
+  'three-column': ThreeColumnTemplate,
+  'dashboard': DashboardTemplate,
+};
+
+/** Resolve template: if the schema specifies a template name, use the matching layout */
+function resolveTemplate(schema: PageSchema): React.FC<{ schema: PageSchema }> | null {
+  if (!schema.template) return null;
+  return TEMPLATE_REGISTRY[schema.template] || null;
+}
+
+// ---------------------------------------------------------------------------
+// Page type variant layouts
+// ---------------------------------------------------------------------------
+
+/** Record page — detail-oriented, narrower max-width */
+const RecordPageLayout: React.FC<{ schema: PageSchema }> = ({ schema }) => {
   if (schema.regions && schema.regions.length > 0) {
-    // If regions are present, flatten their components into the main flow
-    // Ideally, we might want a grid layout here, but linear stacking works for simple single-region pages
-    nodes = schema.regions.flatMap(r => r.components || []);
-  } else {
-    // Fallback to direct children/body
-    const content = schema.body || schema.children;
-    nodes = Array.isArray(content) ? content : (content ? [content] : []);
+    return <RegionLayout regions={schema.regions} pageType="record" />;
   }
+  return <FlatContent schema={schema} />;
+};
+
+/** Home page — dashboard-style, wider layout */
+const HomePageLayout: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  if (schema.regions && schema.regions.length > 0) {
+    return <RegionLayout regions={schema.regions} pageType="home" />;
+  }
+  return <FlatContent schema={schema} />;
+};
+
+/** App page — application shell, full-width capable */
+const AppPageLayout: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  if (schema.regions && schema.regions.length > 0) {
+    return <RegionLayout regions={schema.regions} pageType="app" />;
+  }
+  return <FlatContent schema={schema} />;
+};
+
+/** Utility page — compact, focused, narrower */
+const UtilityPageLayout: React.FC<{ schema: PageSchema }> = ({ schema }) => {
+  if (schema.regions && schema.regions.length > 0) {
+    return <RegionLayout regions={schema.regions} pageType="utility" />;
+  }
+  return <FlatContent schema={schema} />;
+};
+
+// ---------------------------------------------------------------------------
+// Main PageRenderer
+// ---------------------------------------------------------------------------
+
+export const PageRenderer: React.FC<{
+  schema: PageSchema;
+  className?: string;
+  [key: string]: any;
+}> = ({ schema, className, ...props }) => {
+  const pageType = schema.pageType || 'record';
 
   // Extract designer-related props
-  const { 
-      'data-obj-id': dataObjId, 
-      'data-obj-type': dataObjType,
-      style, 
-      ...pageProps 
+  const {
+    'data-obj-id': dataObjId,
+    'data-obj-type': dataObjType,
+    style,
+    ...pageProps
   } = props;
 
-  return (
-    <div 
-      className={cn("min-h-full w-full bg-background p-4 md:p-6 lg:p-8", className)}
-      {...pageProps}
-      // Apply designer props
+  // Select the layout variant based on template or page type
+  const layoutElement = useMemo(() => {
+    const TemplateLayout = resolveTemplate(schema);
+    if (TemplateLayout) {
+      // Template takes priority over page type
+      // eslint-disable-next-line react-hooks/static-components -- TemplateLayout is resolved from a stable template registry
+      return <TemplateLayout schema={schema} />;
+    }
+    switch (pageType) {
+      case 'home':
+        return <HomePageLayout schema={schema} />;
+      case 'app':
+        return <AppPageLayout schema={schema} />;
+      case 'utility':
+        return <UtilityPageLayout schema={schema} />;
+      case 'record':
+      default:
+        return <RecordPageLayout schema={schema} />;
+    }
+  }, [schema, pageType]);
+
+  const pageContent = (
+    <div
+      className={cn(
+        'min-h-full w-full bg-background p-4 md:p-6 lg:p-8',
+        className,
+      )}
+      data-page-type={pageType}
       data-obj-id={dataObjId}
       data-obj-type={dataObjType}
       style={style}
+      {...pageProps}
     >
-      <div className="mx-auto max-w-7xl space-y-8">
+      <div className={cn('mx-auto space-y-8', getPageMaxWidth(pageType))}>
+        {/* Page header */}
         {(schema.title || schema.description) && (
           <div className="space-y-2">
             {schema.title && (
@@ -56,27 +399,33 @@ export const PageRenderer: React.FC<{ schema: PageSchema; className?: string; [k
               </h1>
             )}
             {schema.description && (
-              <p className="text-muted-foreground">
-                {schema.description}
-              </p>
+              <p className="text-muted-foreground">{schema.description}</p>
             )}
           </div>
         )}
-        
-        <div className="space-y-6">
-          {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
-          {nodes.map((node: any, index: number) => (
-            <SchemaRenderer 
-              key={node?.id || index} 
-              schema={node} 
-            />
-          ))}
-        </div>
+
+        {/* Page body — type-specific layout */}
+        {layoutElement}
       </div>
     </div>
   );
+
+  // Wrap with PageVariablesProvider when variables are defined
+  if (schema.variables && schema.variables.length > 0) {
+    return (
+      <PageVariablesProvider definitions={schema.variables}>
+        {pageContent}
+      </PageVariablesProvider>
+    );
+  }
+
+  return pageContent;
 };
 
+// ---------------------------------------------------------------------------
+// ComponentRegistry registration
+// ---------------------------------------------------------------------------
+
 const pageMeta: any = {
   namespace: 'ui',
   label: 'Page',
@@ -85,13 +434,28 @@ const pageMeta: any = {
   inputs: [
     { name: 'title', type: 'string', label: 'Title' },
     { name: 'description', type: 'string', label: 'Description' },
-    { 
-      name: 'body', 
-      type: 'array', 
-      label: 'Content',
-      itemType: 'component' 
-    }
-  ]
+    { name: 'pageType', type: 'string', label: 'Page Type' },
+    { name: 'object', type: 'string', label: 'Object Name' },
+    { name: 'template', type: 'string', label: 'Template' },
+    {
+      name: 'regions',
+      type: 'array',
+      label: 'Regions',
+      itemType: 'object',
+    },
+    {
+      name: 'variables',
+      type: 'array',
+      label: 'Variables',
+      itemType: 'object',
+    },
+    {
+      name: 'body',
+      type: 'array',
+      label: 'Content (Legacy)',
+      itemType: 'component',
+    },
+  ],
 };
 
 ComponentRegistry.register('page', PageRenderer, pageMeta);

package/src/renderers/navigation/sidebar.tsx

@@ -75,6 +75,7 @@ ComponentRegistry.register('sidebar-header',
     <SidebarHeader {...props}>{renderChildren(schema.body)}</SidebarHeader>
   ),
   { 
+    namespace: 'ui',
     label: 'Sidebar Header',
     defaultChildren: [
       { type: 'text', content: 'Sidebar Header' }
@@ -87,6 +88,7 @@ ComponentRegistry.register('sidebar-content',
     <SidebarContent {...props}>{renderChildren(schema.body)}</SidebarContent>
   ),
   { 
+    namespace: 'ui',
     label: 'Sidebar Content',
     defaultChildren: [
       { type: 'sidebar-group' }
@@ -123,6 +125,7 @@ ComponentRegistry.register('sidebar-menu',
     <SidebarMenu {...props}>{renderChildren(schema.body)}</SidebarMenu>
   ),
   { 
+    namespace: 'ui',
     label: 'Sidebar Menu',
     defaultChildren: [
       { type: 'sidebar-menu-item' },
@@ -136,6 +139,7 @@ ComponentRegistry.register('sidebar-menu-item',
     <SidebarMenuItem {...props}>{renderChildren(schema.body)}</SidebarMenuItem>
   ),
   { 
+    namespace: 'ui',
     label: 'Sidebar Menu Item',
     defaultChildren: [
       { type: 'sidebar-menu-button' }
@@ -171,6 +175,7 @@ ComponentRegistry.register('sidebar-footer',
     <SidebarFooter {...props}>{renderChildren(schema.body)}</SidebarFooter>
   ),
   { 
+    namespace: 'ui',
     label: 'Sidebar Footer',
     defaultChildren: [
       { type: 'text', content: 'Footer' }
@@ -183,6 +188,7 @@ ComponentRegistry.register('sidebar-inset',
     <SidebarInset {...props}>{renderChildren(schema.body)}</SidebarInset>
   ),
   { 
+    namespace: 'ui',
     label: 'Sidebar Inset',
     defaultChildren: [
       { type: 'div', className: 'p-4', body: [{ type: 'text', content: 'Main content area' }] }

package/src/renderers/placeholders.tsx

@@ -90,8 +90,8 @@ const PROTOCOL_COMPONENTS = [
   'widget:metric', 'widget:bar', 'widget:line', 'widget:pie', 'widget:funnel', 
   'widget:radar', 'widget:scatter', 'widget:heatmap', 'widget:pivot', 'widget:table', 'widget:text', 'widget:image',
 
-  // 14. Smart Actions
-  'action:button', 'action:group', 'action:menu', 'action:icon',
+  // 14. Smart Actions (implemented in ./action/)
+  // 'action:button', 'action:group', 'action:menu', 'action:icon',
 
   // 15. AI
   'ai:chat_window', 'ai:input', 'ai:suggestion', 'ai:feedback'

package/src/stories/Introduction.mdx

@@ -1,34 +1,61 @@
 import { Meta } from "@storybook/blocks";
 
-<Meta title="Introduction" />
+<Meta title="Getting Started/Introduction" />
 
-# Welcome to Object UI
+# ObjectUI — Server-Driven UI Engine
 
-Object UI is a **Universal, Server-Driven UI (SDUI) Engine** built on React + Tailwind + Shadcn.
+**ObjectUI** is a universal, server-driven UI (SDUI) engine built on **React + Tailwind + Shadcn**.
+It interprets JSON metadata into pixel-perfect, accessible, and interactive enterprise interfaces.
 
-It is designed to interpret JSON metadata into pixel-perfect, accessible, and interactive Enterprise Interfaces.
+## 🏗 Architecture
 
-## Core Concepts
-
-- **Protocol Agnostic**: Works with any backend via Data Adapters.
-- **Server Driven**: The UI structure is defined by JSON schemas.
-- **Shadcn Compatible**: Uses standard Shadcn UI primitives.
-- **Action System**: declaratively define behavior (clicks, validation, navigation).
-
-## Packages
-
-| Package | Description |
+| Package | Role |
 |---|---|
-| `@object-ui/core` | The logic engine (Validation, Expressions, Registry). |
-| `@object-ui/components` | The base UI atoms (Button, Card, Input). |
-| `@object-ui/fields` | Standardized input fields. |
-| `@object-ui/layout` | Page skeletons and shells. |
-| `@object-ui/plugin-*` | Specialized widgets (Grids, Charts, Maps). |
-
-## Getting Started
-
-Check the **Guide** section for tutorials on how to use the SchemaRenderer.
-
-## Architecture
-
-This project is a monorepo managed with PNPM.
+| `@object-ui/types` | JSON Protocol — Pure TypeScript interfaces |
+| `@object-ui/core` | Engine — Schema registry, validation, expressions |
+| `@object-ui/components` | Primitives — Shadcn UI wrappers (Button, Card, Badge…) |
+| `@object-ui/fields` | Field Widgets — 47+ input field renderers |
+| `@object-ui/layout` | Shell — Header, Sidebar, AppShell |
+| `@object-ui/react` | Runtime — `SchemaRenderer`, `useRenderer` |
+| `@object-ui/plugin-*` | Plugins — Grid, Kanban, Charts, Gantt, Map… |
+| `@object-ui/data-*` | Data Adapters — REST, ObjectQL, ObjectStack |
+
+## 🎯 How It Works
+
+Everything is driven by **JSON schemas**. A UI tree is a recursive structure of `UIComponent` nodes:
+
+```json
+{
+  "type": "page",
+  "children": [
+    {
+      "type": "grid",
+      "props": { "cols": 3, "gap": 4 },
+      "children": [
+        { "type": "metric", "label": "Revenue", "value": "$45,231" },
+        { "type": "metric", "label": "Users", "value": "2,350" },
+        { "type": "metric", "label": "Growth", "value": "12.5%" }
+      ]
+    }
+  ]
+}
+```
+
+The `SchemaRenderer` recursively walks this tree and resolves each `type` to a registered React component.
+
+## 📖 Storybook Guide
+
+This Storybook is organized by capability:
+
+- **Getting Started** — Introduction and data binding guides.
+- **Primitives** — Atomic Shadcn UI wrappers driven by JSON (Button, Card, Input, Dialog…).
+- **Fields** — All 47+ field widget renderers (text, number, select, date, lookup…).
+- **Plugins** — Complex views powered by specialized libraries (Grid, Kanban, Gantt, Charts, Map…).
+- **Templates** — Composed page-level layouts (Dashboard, Page, Reports, Sidebar).
+- **Apps** — Full application demos (CRM) using all of the above.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/objectstack-ai/objectui)
+- [ObjectStack Spec](https://github.com/objectstack-ai/spec)
+- [Shadcn UI](https://ui.shadcn.com/)