@object-ui/types 0.3.0 → 0.5.0

package/src/zod/README.md

@@ -0,0 +1,329 @@
+# ObjectUI Zod Validation Schemas
+
+Complete Zod validation schemas for all ObjectUI components, following the @objectstack/spec UI specification format.
+
+## Overview
+
+This directory contains runtime validation schemas using [Zod](https://github.com/colinhacks/zod) for all ObjectUI component types. These schemas provide:
+
+- **Type-safe runtime validation** of component configurations
+- **Compliance with @objectstack/spec** UI specification format  
+- **Auto-completion and IntelliSense** through TypeScript integration
+- **Detailed error messages** for invalid configurations
+
+## Installation
+
+The Zod schemas are included in the `@object-ui/types` package:
+
+```bash
+npm install @object-ui/types zod
+# or
+pnpm add @object-ui/types zod
+```
+
+## Usage
+
+### Basic Validation
+
+```typescript
+import { ButtonSchema, InputSchema } from '@object-ui/types/zod';
+
+// Validate a button configuration
+const buttonConfig = {
+  type: 'button',
+  label: 'Click Me',
+  variant: 'primary',
+  onClick: () => console.log('clicked'),
+};
+
+const result = ButtonSchema.safeParse(buttonConfig);
+
+if (result.success) {
+  console.log('Valid config:', result.data);
+} else {
+  console.error('Validation errors:', result.error);
+}
+```
+
+### Form Validation
+
+```typescript
+import { FormSchema } from '@object-ui/types/zod';
+
+const formConfig = {
+  type: 'form',
+  fields: [
+    {
+      name: 'email',
+      label: 'Email',
+      type: 'input',
+      inputType: 'email',
+      required: true,
+    },
+    {
+      name: 'password',
+      label: 'Password',
+      type: 'input',
+      inputType: 'password',
+      required: true,
+    },
+  ],
+  submitLabel: 'Sign In',
+  layout: 'vertical',
+};
+
+const result = FormSchema.safeParse(formConfig);
+```
+
+### Runtime Type Inference
+
+```typescript
+import { z } from 'zod';
+import { ButtonSchema, InputSchema } from '@object-ui/types/zod';
+
+// Infer TypeScript type from schema
+type Button = z.infer<typeof ButtonSchema>;
+type Input = z.infer<typeof InputSchema>;
+```
+
+### Generic Component Validation
+
+```typescript
+import { AnyComponentSchema } from '@object-ui/types/zod';
+
+function validateComponent(config: unknown) {
+  const result = AnyComponentSchema.safeParse(config);
+  
+  if (!result.success) {
+    throw new Error(`Invalid component: ${result.error.message}`);
+  }
+  
+  return result.data;
+}
+```
+
+## Available Schemas
+
+### Base Schemas
+- `BaseSchema` - Foundation for all components
+- `SchemaNodeSchema` - Recursive schema node type
+
+### Layout Components (17)
+- `DivSchema`, `SpanSchema`, `TextSchema`
+- `ImageSchema`, `IconSchema`, `SeparatorSchema`
+- `ContainerSchema`, `FlexSchema`, `StackSchema`
+- `GridSchema`, `CardSchema`, `TabsSchema`
+- `ScrollAreaSchema`, `ResizableSchema`
+- `AspectRatioSchema`, `PageSchema`
+
+### Form Components (17)
+- `ButtonSchema`, `InputSchema`, `TextareaSchema`
+- `SelectSchema`, `CheckboxSchema`, `RadioGroupSchema`
+- `SwitchSchema`, `ToggleSchema`, `SliderSchema`
+- `FileUploadSchema`, `DatePickerSchema`, `CalendarSchema`
+- `InputOTPSchema`, `ComboboxSchema`, `LabelSchema`
+- `CommandSchema`, `FormSchema`
+
+### Data Display Components (14)
+- `AlertSchema`, `BadgeSchema`, `AvatarSchema`
+- `ListSchema`, `TableSchema`, `DataTableSchema`
+- `MarkdownSchema`, `TreeViewSchema`, `ChartSchema`
+- `TimelineSchema`, `BreadcrumbSchema`
+- `KbdSchema`, `HtmlSchema`, `StatisticSchema`
+
+### Feedback Components (8)
+- `LoadingSchema`, `ProgressSchema`, `SkeletonSchema`
+- `ToastSchema`, `ToasterSchema`, `SpinnerSchema`
+- `EmptySchema`, `SonnerSchema`
+
+### Disclosure Components (3)
+- `AccordionSchema`, `CollapsibleSchema`, `ToggleGroupSchema`
+
+### Overlay Components (10)
+- `DialogSchema`, `AlertDialogSchema`, `SheetSchema`
+- `DrawerSchema`, `PopoverSchema`, `TooltipSchema`
+- `HoverCardSchema`, `DropdownMenuSchema`
+- `ContextMenuSchema`, `MenubarSchema`
+
+### Navigation Components (6)
+- `HeaderBarSchema`, `SidebarSchema`, `BreadcrumbSchema`
+- `PaginationSchema`, `NavigationMenuSchema`, `ButtonGroupSchema`
+
+### Complex Components (5)
+- `KanbanSchema`, `CalendarViewSchema`
+- `FilterBuilderSchema`, `CarouselSchema`, `ChatbotSchema`
+
+## Schema Structure
+
+All component schemas follow the @objectstack/spec UI specification format:
+
+```typescript
+{
+  // Required
+  type: string,              // Component type identifier
+  
+  // Common Optional Properties
+  id?: string,               // Unique identifier
+  name?: string,             // Component name
+  label?: string,            // Display label
+  className?: string,        // Tailwind classes
+  visible?: boolean,         // Visibility control
+  disabled?: boolean,        // Disabled state
+  
+  // Type-specific properties...
+}
+```
+
+## Validation Features
+
+### Type Safety
+- Strict type checking for all properties
+- Enum validation for predefined values
+- Recursive validation for nested structures
+
+### Error Messages
+```typescript
+const result = ButtonSchema.safeParse({
+  type: 'button',
+  variant: 'invalid-variant'
+});
+
+// result.error.errors:
+// [
+//   {
+//     code: 'invalid_enum_value',
+//     path: ['variant'],
+//     message: "Invalid enum value. Expected 'default' | 'secondary' | ...",
+//   }
+// ]
+```
+
+### Nested Validation
+```typescript
+// Validates nested components in Card
+const cardWithChildren = CardSchema.parse({
+  type: 'card',
+  title: 'My Card',
+  children: [
+    { type: 'text', value: 'Hello' },
+    { type: 'button', label: 'Click' }
+  ]
+});
+```
+
+## Best Practices
+
+1. **Use safeParse()** for user input validation
+   ```typescript
+   const result = ButtonSchema.safeParse(userInput);
+   if (!result.success) {
+     // Handle errors gracefully
+   }
+   ```
+
+2. **Use parse()** for internal configurations
+   ```typescript
+   // Throws error on invalid data
+   const config = ButtonSchema.parse(internalConfig);
+   ```
+
+3. **Validate at boundaries**
+   - API endpoints receiving component configs
+   - Form submissions
+   - Configuration file parsing
+   - Component registration
+
+4. **Combine with TypeScript types**
+   ```typescript
+   import type { ButtonSchema as ButtonType } from '@object-ui/types';
+   import { ButtonSchema } from '@object-ui/types/zod';
+   
+   // Use type for declarations
+   const config: ButtonType = { ... };
+   
+   // Use schema for validation
+   ButtonSchema.parse(config);
+   ```
+
+## Performance
+
+Zod schemas are designed for runtime validation:
+
+- **Lazy evaluation** for recursive schemas (trees, menus)
+- **Optional validation** - only validate when needed
+- **Partial validation** - validate specific properties
+- **Caching** - Zod internally caches schema structures
+
+## Integration Examples
+
+### With React Hook Form
+```typescript
+import { zodResolver } from '@hookform/resolvers/zod';
+import { FormSchema } from '@object-ui/types/zod';
+
+const form = useForm({
+  resolver: zodResolver(FormSchema),
+});
+```
+
+### With API Routes
+```typescript
+import { ButtonSchema } from '@object-ui/types/zod';
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const result = ButtonSchema.safeParse(body);
+  
+  if (!result.success) {
+    return Response.json(
+      { error: result.error },
+      { status: 400 }
+    );
+  }
+  
+  // Process valid data
+  return Response.json(result.data);
+}
+```
+
+### With Component Registry
+```typescript
+import { AnyComponentSchema } from '@object-ui/types/zod';
+
+function registerComponent(config: unknown) {
+  // Validate before registration
+  const validated = AnyComponentSchema.parse(config);
+  registry.set(validated.type, validated);
+}
+```
+
+## Migration from TypeScript-only Types
+
+If you're currently using only TypeScript types:
+
+```typescript
+// Before (TypeScript only)
+import type { ButtonSchema } from '@object-ui/types';
+const button: ButtonSchema = { ... };
+
+// After (with runtime validation)
+import type { ButtonSchema as ButtonType } from '@object-ui/types';
+import { ButtonSchema } from '@object-ui/types/zod';
+
+const button: ButtonType = { ... };
+const validated = ButtonSchema.parse(button);
+```
+
+## Contributing
+
+When adding new component types:
+
+1. Define TypeScript interface in `src/`
+2. Create corresponding Zod schema in `src/zod/`
+3. Export from `src/zod/index.zod.ts`
+4. Add tests in `examples/zod-validation-example.ts`
+5. Update this README
+
+## License
+
+MIT - Copyright (c) 2024-present ObjectStack Inc.

package/src/zod/app.zod.ts

@@ -0,0 +1,72 @@
+/**
+ * ObjectUI
+ * 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.
+ */
+
+/**
+ * @object-ui/types/zod - Application Schema Zod Validators
+ * 
+ * Zod validation schemas for top-level application configuration.
+ * Following @objectstack/spec UI specification format.
+ * 
+ * @module zod/app
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+import { BaseSchema } from './base.zod.js';
+
+/**
+ * Menu Item Schema - Navigation menu item
+ */
+export const MenuItemSchema: z.ZodType<any> = z.lazy(() => z.object({
+  type: z.enum(['item', 'group', 'separator']).optional().describe('Item type'),
+  label: z.string().optional().describe('Display label'),
+  icon: z.string().optional().describe('Icon name (Lucide)'),
+  path: z.string().optional().describe('Target path (route)'),
+  href: z.string().optional().describe('External link'),
+  children: z.array(MenuItemSchema).optional().describe('Child items (submenu)'),
+  badge: z.union([z.string(), z.number()]).optional().describe('Badge or count'),
+  hidden: z.union([z.boolean(), z.string()]).optional().describe('Visibility condition'),
+}));
+
+/**
+ * App Action Schema - Application header/toolbar action
+ */
+export const AppActionSchema = z.object({
+  type: z.enum(['button', 'dropdown', 'user']).describe('Action type'),
+  label: z.string().optional().describe('Action label'),
+  icon: z.string().optional().describe('Icon name'),
+  onClick: z.string().optional().describe('Click handler expression'),
+  avatar: z.string().optional().describe('User avatar URL (for type="user")'),
+  description: z.string().optional().describe('Additional description (e.g., email for user)'),
+  items: z.array(MenuItemSchema).optional().describe('Dropdown menu items (for type="dropdown" or "user")'),
+  shortcut: z.string().optional().describe('Keyboard shortcut'),
+  variant: z.enum(['default', 'destructive', 'outline', 'secondary', 'ghost', 'link']).optional().describe('Button variant'),
+  size: z.enum(['default', 'sm', 'lg', 'icon']).optional().describe('Button size'),
+});
+
+/**
+ * App Schema - Top-level application configuration
+ */
+export const AppSchema = BaseSchema.extend({
+  type: z.literal('app'),
+  name: z.string().optional().describe('Application name (system ID)'),
+  title: z.string().optional().describe('Display title'),
+  description: z.string().optional().describe('Application description'),
+  logo: z.string().optional().describe('Logo URL or icon name'),
+  favicon: z.string().optional().describe('Favicon URL'),
+  layout: z.enum(['sidebar', 'header', 'empty']).optional().default('sidebar').describe('Global layout strategy'),
+  menu: z.array(MenuItemSchema).optional().describe('Global navigation menu'),
+  actions: z.array(AppActionSchema).optional().describe('Global actions (user profile, settings, etc.)'),
+});
+
+/**
+ * Export type inference helpers
+ */
+export type MenuItemSchemaType = z.infer<typeof MenuItemSchema>;
+export type AppActionSchemaType = z.infer<typeof AppActionSchema>;
+export type AppSchemaType = z.infer<typeof AppSchema>;

package/src/zod/base.zod.ts

@@ -0,0 +1,229 @@
+/**
+ * ObjectUI
+ * 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.
+ */
+
+/**
+ * @object-ui/types/zod - Base Schema Zod Validators
+ * 
+ * Zod validation schemas for base component types.
+ * These schemas follow the @objectstack/spec UI specification format.
+ * 
+ * @module zod/base
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema Node - Can be a schema object or primitive value
+ */
+export const SchemaNodeSchema: z.ZodType<any> = z.lazy(() =>
+  z.union([
+    BaseSchemaCore,
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.undefined(),
+  ])
+);
+
+/**
+ * Base Schema - Core validation schema that all components extend
+ * 
+ * This is the foundation for all UI component schemas in ObjectUI.
+ * Following @objectstack/spec UI specification format.
+ */
+const BaseSchemaCore = z.object({
+  /**
+   * Component type identifier
+   */
+  type: z.string().describe('Component type identifier'),
+
+  /**
+   * Unique identifier for the component
+   */
+  id: z.string().optional().describe('Unique component identifier'),
+
+  /**
+   * Human-readable name
+   */
+  name: z.string().optional().describe('Component name'),
+
+  /**
+   * Display label
+   */
+  label: z.string().optional().describe('Display label'),
+
+  /**
+   * Description text
+   */
+  description: z.string().optional().describe('Description text'),
+
+  /**
+   * Placeholder text
+   */
+  placeholder: z.string().optional().describe('Placeholder text'),
+
+  /**
+   * Tailwind CSS classes
+   */
+  className: z.string().optional().describe('Tailwind CSS classes'),
+
+  /**
+   * Inline styles
+   */
+  style: z.record(z.string(), z.union([z.string(), z.number()])).optional().describe('Inline CSS styles'),
+
+  /**
+   * Arbitrary data
+   */
+  data: z.any().optional().describe('Custom data payload'),
+
+  /**
+   * Child components or content
+   */
+  body: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Child components'),
+
+  /**
+   * Alternative children property
+   */
+  children: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Child components (React-style)'),
+
+  /**
+   * Visibility control
+   */
+  visible: z.boolean().optional().describe('Visibility control'),
+
+  /**
+   * Conditional visibility expression
+   */
+  visibleOn: z.string().optional().describe('Expression for conditional visibility'),
+
+  /**
+   * Hidden control
+   */
+  hidden: z.boolean().optional().describe('Hidden control'),
+
+  /**
+   * Conditional hidden expression
+   */
+  hiddenOn: z.string().optional().describe('Expression for conditional hiding'),
+
+  /**
+   * Disabled state
+   */
+  disabled: z.boolean().optional().describe('Disabled state'),
+
+  /**
+   * Conditional disabled expression
+   */
+  disabledOn: z.string().optional().describe('Expression for conditional disabling'),
+
+  /**
+   * Test ID for automated testing
+   */
+  testId: z.string().optional().describe('Test identifier'),
+
+  /**
+   * Accessibility label
+   */
+  ariaLabel: z.string().optional().describe('Accessibility label'),
+}).passthrough(); // Allow additional properties for type-specific extensions
+
+/**
+ * Base Schema - Export for use in other schemas
+ */
+export const BaseSchema = BaseSchemaCore;
+
+/**
+ * Component Input Configuration
+ */
+export const ComponentInputSchema = z.object({
+  name: z.string().describe('Property name'),
+  type: z.enum([
+    'string',
+    'number',
+    'boolean',
+    'enum',
+    'array',
+    'object',
+    'color',
+    'date',
+    'code',
+    'file',
+    'slot',
+  ]).describe('Input control type'),
+  label: z.string().optional().describe('Display label'),
+  defaultValue: z.any().optional().describe('Default value'),
+  required: z.boolean().optional().describe('Required flag'),
+  enum: z.union([
+    z.array(z.string()),
+    z.array(z.object({
+      label: z.string(),
+      value: z.any(),
+    })),
+  ]).optional().describe('Enum options'),
+  description: z.string().optional().describe('Help text'),
+  advanced: z.boolean().optional().describe('Advanced option flag'),
+  inputType: z.string().optional().describe('Specific input type'),
+  min: z.number().optional().describe('Minimum value'),
+  max: z.number().optional().describe('Maximum value'),
+  step: z.number().optional().describe('Step value'),
+  placeholder: z.string().optional().describe('Placeholder text'),
+});
+
+/**
+ * Component Metadata
+ */
+export const ComponentMetaSchema = z.object({
+  label: z.string().optional().describe('Display name'),
+  icon: z.string().optional().describe('Icon name or SVG'),
+  category: z.string().optional().describe('Component category'),
+  inputs: z.array(ComponentInputSchema).optional().describe('Configurable properties'),
+  defaultProps: z.record(z.string(), z.any()).optional().describe('Default property values'),
+  defaultChildren: z.array(SchemaNodeSchema).optional().describe('Default children'),
+  examples: z.record(z.string(), z.any()).optional().describe('Example configurations'),
+  isContainer: z.boolean().optional().describe('Can have children'),
+  resizable: z.boolean().optional().describe('Can be resized'),
+  resizeConstraints: z.object({
+    width: z.boolean().optional(),
+    height: z.boolean().optional(),
+    minWidth: z.number().optional(),
+    maxWidth: z.number().optional(),
+    minHeight: z.number().optional(),
+    maxHeight: z.number().optional(),
+  }).optional().describe('Resize constraints'),
+  tags: z.array(z.string()).optional().describe('Search tags'),
+  description: z.string().optional().describe('Component description'),
+});
+
+/**
+ * Component Configuration
+ */
+export const ComponentConfigSchema = ComponentMetaSchema.extend({
+  type: z.string().describe('Component type identifier'),
+  component: z.any().describe('Component renderer'),
+});
+
+/**
+ * HTML Attributes (generic)
+ */
+export const HTMLAttributesSchema = z.record(z.string(), z.any()).describe('HTML attributes');
+
+/**
+ * Event Handlers
+ */
+export const EventHandlersSchema = z.record(z.string(), z.function()).describe('Event handlers');
+
+/**
+ * Style Props
+ */
+export const StylePropsSchema = z.object({
+  className: z.string().optional(),
+  style: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+}).describe('Style properties');