@object-ui/types 0.3.1 → 0.5.0

package/src/views.ts

@@ -0,0 +1,429 @@
+/**
+ * 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 - View Component Schemas
+ * 
+ * Type definitions for various view components (List, Detail, Grid, Kanban, Calendar).
+ * These schemas enable building different data visualization interfaces.
+ * 
+ * @module views
+ * @packageDocumentation
+ */
+
+import type { BaseSchema, SchemaNode } from './base';
+import type { ActionSchema } from './crud';
+import type { TableColumn } from './data-display';
+import type { FormField } from './form';
+
+/**
+ * View Type
+ */
+export type ViewType = 'list' | 'detail' | 'grid' | 'kanban' | 'calendar' | 'timeline' | 'map';
+
+/**
+ * Detail View Field Configuration
+ */
+export interface DetailViewField {
+  /**
+   * Field name/path
+   */
+  name: string;
+  /**
+   * Display label
+   */
+  label?: string;
+  /**
+   * Field type for rendering
+   */
+  type?: 'text' | 'image' | 'link' | 'badge' | 'date' | 'datetime' | 'json' | 'html' | 'markdown' | 'custom';
+  /**
+   * Format string (e.g., date format)
+   */
+  format?: string;
+  /**
+   * Custom renderer
+   */
+  render?: SchemaNode;
+  /**
+   * Field value
+   */
+  value?: any;
+  /**
+   * Whether field is read-only
+   */
+  readonly?: boolean;
+  /**
+   * Field visibility condition
+   */
+  visible?: boolean | string;
+  /**
+   * Span across columns (for grid layout)
+   */
+  span?: number;
+}
+
+/**
+ * Detail View Section/Group
+ */
+export interface DetailViewSection {
+  /**
+   * Section title
+   */
+  title?: string;
+  /**
+   * Section description
+   */
+  description?: string;
+  /**
+   * Section icon
+   */
+  icon?: string;
+  /**
+   * Fields in this section
+   */
+  fields: DetailViewField[];
+  /**
+   * Collapsible section
+   */
+  collapsible?: boolean;
+  /**
+   * Default collapsed state
+   */
+  defaultCollapsed?: boolean;
+  /**
+   * Grid columns for field layout
+   */
+  columns?: number;
+  /**
+   * Section visibility condition
+   */
+  visible?: boolean | string;
+}
+
+/**
+ * Detail View Tab
+ */
+export interface DetailViewTab {
+  /**
+   * Tab key/identifier
+   */
+  key: string;
+  /**
+   * Tab label
+   */
+  label: string;
+  /**
+   * Tab icon
+   */
+  icon?: string;
+  /**
+   * Tab content
+   */
+  content: SchemaNode | SchemaNode[];
+  /**
+   * Tab visibility condition
+   */
+  visible?: boolean | string;
+  /**
+   * Badge count
+   */
+  badge?: string | number;
+}
+
+/**
+ * Detail View Schema - Display detailed information about a single record
+ * Enhanced in Phase 2 with better organization and features
+ */
+export interface DetailViewSchema extends BaseSchema {
+  type: 'detail-view';
+  /**
+   * Detail title
+   */
+  title?: string;
+  /**
+   * API endpoint to fetch detail data
+   */
+  api?: string;
+  /**
+   * Resource ID to display
+   */
+  resourceId?: string | number;
+  /**
+   * Object name (for ObjectQL integration)
+   */
+  objectName?: string;
+  /**
+   * Data to display (if not fetching from API)
+   */
+  data?: any;
+  /**
+   * Layout mode
+   */
+  layout?: 'vertical' | 'horizontal' | 'grid';
+  /**
+   * Grid columns (for grid layout)
+   */
+  columns?: number;
+  /**
+   * Field sections for organized display
+   */
+  sections?: DetailViewSection[];
+  /**
+   * Direct fields (without sections)
+   */
+  fields?: DetailViewField[];
+  /**
+   * Actions available in detail view
+   */
+  actions?: ActionSchema[];
+  /**
+   * Tabs for additional content
+   */
+  tabs?: DetailViewTab[];
+  /**
+   * Show back button
+   * @default true
+   */
+  showBack?: boolean;
+  /**
+   * Back button URL
+   */
+  backUrl?: string;
+  /**
+   * Custom back action
+   */
+  onBack?: string;
+  /**
+   * Show edit button
+   */
+  showEdit?: boolean;
+  /**
+   * Edit button URL
+   */
+  editUrl?: string;
+  /**
+   * Show delete button
+   */
+  showDelete?: boolean;
+  /**
+   * Delete confirmation message
+   */
+  deleteConfirmation?: string;
+  /**
+   * Whether to show loading state
+   * @default true
+   */
+  loading?: boolean;
+  /**
+   * Custom header content
+   */
+  header?: SchemaNode;
+  /**
+   * Custom footer content
+   */
+  footer?: SchemaNode;
+  /**
+   * Related records section
+   */
+  related?: Array<{
+    /**
+     * Relation title
+     */
+    title: string;
+    /**
+     * Relation type
+     */
+    type: 'list' | 'grid' | 'table';
+    /**
+     * API endpoint for related data
+     */
+    api?: string;
+    /**
+     * Static data
+     */
+    data?: any[];
+    /**
+     * Columns for table view
+     */
+    columns?: TableColumn[];
+    /**
+     * Fields for list view
+     */
+    fields?: string[];
+  }>;
+}
+
+/**
+ * View Switcher Schema - Toggle between different view modes
+ * New in Phase 2
+ */
+export interface ViewSwitcherSchema extends BaseSchema {
+  type: 'view-switcher';
+  /**
+   * Available view types
+   */
+  views: Array<{
+    /**
+     * View type
+     */
+    type: ViewType;
+    /**
+     * View label
+     */
+    label?: string;
+    /**
+     * View icon
+     */
+    icon?: string;
+    /**
+     * View schema
+     */
+    schema?: SchemaNode;
+  }>;
+  /**
+   * Default/active view
+   */
+  defaultView?: ViewType;
+  /**
+   * Current active view
+   */
+  activeView?: ViewType;
+  /**
+   * Switcher variant
+   */
+  variant?: 'tabs' | 'buttons' | 'dropdown';
+  /**
+   * Switcher position
+   */
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  /**
+   * View change callback
+   */
+  onViewChange?: string;
+  /**
+   * Persist view preference
+   */
+  persistPreference?: boolean;
+  /**
+   * Storage key for persisting view
+   */
+  storageKey?: string;
+}
+
+/**
+ * Filter UI Schema - Enhanced filter interface
+ * New in Phase 2
+ */
+export interface FilterUISchema extends BaseSchema {
+  type: 'filter-ui';
+  /**
+   * Available filters
+   */
+  filters: Array<{
+    /**
+     * Filter field
+     */
+    field: string;
+    /**
+     * Filter label
+     */
+    label?: string;
+    /**
+     * Filter type
+     */
+    type: 'text' | 'number' | 'select' | 'date' | 'date-range' | 'boolean';
+    /**
+     * Filter operator
+     */
+    operator?: 'equals' | 'contains' | 'startsWith' | 'gt' | 'lt' | 'between' | 'in';
+    /**
+     * Options for select filter
+     */
+    options?: Array<{ label: string; value: any }>;
+    /**
+     * Placeholder
+     */
+    placeholder?: string;
+  }>;
+  /**
+   * Current filter values
+   */
+  values?: Record<string, any>;
+  /**
+   * Filter change callback
+   */
+  onChange?: string;
+  /**
+   * Show clear button
+   */
+  showClear?: boolean;
+  /**
+   * Show apply button
+   */
+  showApply?: boolean;
+  /**
+   * Filter layout
+   */
+  layout?: 'inline' | 'popover' | 'drawer';
+}
+
+/**
+ * Sort UI Schema - Enhanced sort interface
+ * New in Phase 2
+ */
+export interface SortUISchema extends BaseSchema {
+  type: 'sort-ui';
+  /**
+   * Sortable fields
+   */
+  fields: Array<{
+    /**
+     * Field name
+     */
+    field: string;
+    /**
+     * Field label
+     */
+    label?: string;
+  }>;
+  /**
+   * Current sort configuration
+   */
+  sort?: Array<{
+    /**
+     * Field to sort by
+     */
+    field: string;
+    /**
+     * Sort direction
+     */
+    direction: 'asc' | 'desc';
+  }>;
+  /**
+   * Sort change callback
+   */
+  onChange?: string;
+  /**
+   * Allow multiple sort fields
+   */
+  multiple?: boolean;
+  /**
+   * UI variant
+   */
+  variant?: 'dropdown' | 'buttons';
+}
+
+/**
+ * Union type of all view schemas
+ */
+export type ViewComponentSchema =
+  | DetailViewSchema
+  | ViewSwitcherSchema
+  | FilterUISchema
+  | SortUISchema;

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/blocks.zod.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 - Block Schema Zod Validators
+ * 
+ * Zod validation schemas for reusable component blocks.
+ * Following @objectstack/spec UI specification format.
+ * 
+ * @module zod/blocks
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+import { BaseSchema, SchemaNodeSchema } from './base.zod.js';
+
+/**
+ * Block Variable Schema
+ */
+export const BlockVariableSchema = z.object({
+  name: z.string().describe('Variable name'),
+  label: z.string().optional().describe('Display label'),
+  type: z.enum(['string', 'number', 'boolean', 'object', 'array', 'component']).optional().describe('Variable type'),
+  defaultValue: z.any().optional().describe('Default value'),
+  description: z.string().optional().describe('Description/help text'),
+  required: z.boolean().optional().describe('Whether this variable is required'),
+  validation: z.any().optional().describe('Validation rules'),
+  enum: z.array(z.any()).optional().describe('Enum options (for string/number types)'),
+});
+
+/**
+ * Block Slot Schema
+ */
+export const BlockSlotSchema = z.object({
+  name: z.string().describe('Slot name'),
+  label: z.string().optional().describe('Display label'),
+  description: z.string().optional().describe('Description'),
+  defaultContent: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Default content'),
+  allowedTypes: z.array(z.string()).optional().describe('Allowed component types'),
+  maxChildren: z.number().optional().describe('Maximum number of children'),
+  required: z.boolean().optional().describe('Whether this slot is required'),
+});
+
+/**
+ * Block Metadata Schema
+ */
+export const BlockMetadataSchema = z.object({
+  name: z.string().describe('Block name/identifier'),
+  label: z.string().optional().describe('Display label'),
+  description: z.string().optional().describe('Block description'),
+  category: z.string().optional().describe('Block category'),
+  icon: z.string().optional().describe('Block icon'),
+  tags: z.array(z.string()).optional().describe('Block tags for search'),
+  author: z.string().optional().describe('Author/creator'),
+  version: z.string().optional().describe('Version'),
+  license: z.string().optional().describe('License'),
+  repository: z.string().optional().describe('Repository URL'),
+  preview: z.string().optional().describe('Preview image URL'),
+  premium: z.boolean().optional().describe('Is this a premium/paid block'),
+});
+
+/**
+ * Block Schema
+ */
+export const BlockSchema = BaseSchema.extend({
+  type: z.literal('block'),
+  meta: BlockMetadataSchema.optional().describe('Block metadata'),
+  variables: z.array(BlockVariableSchema).optional().describe('Block variables/props'),
+  slots: z.array(BlockSlotSchema).optional().describe('Block slots for content injection'),
+  template: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Block template (component tree)'),
+  values: z.record(z.string(), z.any()).optional().describe('Variable values (when using a block)'),
+  slotContent: z.record(z.string(), z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)])).optional().describe('Slot content (when using a block)'),
+  blockRef: z.string().optional().describe('Block reference (for reusing saved blocks)'),
+  editable: z.boolean().optional().describe('Enable edit mode'),
+});
+
+/**
+ * Block Library Item Schema
+ */
+export const BlockLibraryItemSchema = z.object({
+  id: z.string().describe('Unique identifier'),
+  meta: BlockMetadataSchema.describe('Block metadata'),
+  schema: BlockSchema.describe('Block schema'),
+  installs: z.number().optional().describe('Installation count'),
+  rating: z.number().optional().describe('Rating (1-5)'),
+  ratingCount: z.number().optional().describe('Number of ratings'),
+  updatedAt: z.string().optional().describe('Last updated timestamp'),
+  createdAt: z.string().optional().describe('Created timestamp'),
+});
+
+/**
+ * Block Library Schema
+ */
+export const BlockLibrarySchema = BaseSchema.extend({
+  type: z.literal('block-library'),
+  apiEndpoint: z.string().optional().describe('Library API endpoint'),
+  category: z.string().optional().describe('Filter by category'),
+  searchQuery: z.string().optional().describe('Search query'),
+  tags: z.array(z.string()).optional().describe('Filter by tags'),
+  showPremium: z.boolean().optional().describe('Show premium blocks'),
+  blocks: z.array(BlockLibraryItemSchema).optional().describe('Blocks to display'),
+  loading: z.boolean().optional().describe('Loading state'),
+  onInstall: z.string().optional().describe('Install callback'),
+  onPreview: z.string().optional().describe('Preview callback'),
+});
+
+/**
+ * Block Editor Schema
+ */
+export const BlockEditorSchema = BaseSchema.extend({
+  type: z.literal('block-editor'),
+  block: BlockSchema.optional().describe('Block being edited'),
+  showVariables: z.boolean().optional().describe('Show variable editor'),
+  showSlots: z.boolean().optional().describe('Show slot editor'),
+  showTemplate: z.boolean().optional().describe('Show template editor'),
+  showPreview: z.boolean().optional().describe('Show preview'),
+  onSave: z.string().optional().describe('Save callback'),
+  onCancel: z.string().optional().describe('Cancel callback'),
+});
+
+/**
+ * Block Instance Schema
+ */
+export const BlockInstanceSchema = BaseSchema.extend({
+  type: z.literal('block-instance'),
+  blockId: z.string().describe('Block reference ID'),
+  blockName: z.string().optional().describe('Block name (for local blocks)'),
+  values: z.record(z.string(), z.any()).optional().describe('Variable values'),
+  slotContent: z.record(z.string(), z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)])).optional().describe('Slot content'),
+  overrideStyles: z.boolean().optional().describe('Override styles'),
+});
+
+/**
+ * Component Schema
+ */
+export const ComponentSchema = BaseSchema.extend({
+  type: z.literal('component'),
+  componentName: z.string().optional().describe('Component name/identifier'),
+  props: z.record(z.string(), z.any()).optional().describe('Component props'),
+  children: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Component children'),
+});
+
+/**
+ * Union of all block schemas
+ */
+export const BlockComponentSchema = z.union([
+  BlockSchema,
+  BlockLibrarySchema,
+  BlockEditorSchema,
+  BlockInstanceSchema,
+  ComponentSchema,
+]);
+
+/**
+ * Export type inference helpers
+ */
+export type BlockVariableSchemaType = z.infer<typeof BlockVariableSchema>;
+export type BlockSlotSchemaType = z.infer<typeof BlockSlotSchema>;
+export type BlockMetadataSchemaType = z.infer<typeof BlockMetadataSchema>;
+export type BlockSchemaType = z.infer<typeof BlockSchema>;
+export type BlockLibraryItemSchemaType = z.infer<typeof BlockLibraryItemSchema>;
+export type BlockLibrarySchemaType = z.infer<typeof BlockLibrarySchema>;
+export type BlockEditorSchemaType = z.infer<typeof BlockEditorSchema>;
+export type BlockInstanceSchemaType = z.infer<typeof BlockInstanceSchema>;
+export type ComponentSchemaType = z.infer<typeof ComponentSchema>;

package/src/zod/complex.zod.ts

@@ -17,7 +17,7 @@
  */
 
 import { z } from 'zod';
-import { BaseSchema, SchemaNodeSchema } from './base.zod';
+import { BaseSchema, SchemaNodeSchema } from './base.zod.js';
 
 /**
  * Kanban Card Schema