@object-ui/types 0.3.0

package/dist/base.d.ts

@@ -0,0 +1,360 @@
+/**
+ * @object-ui/types - Base Schema Types
+ *
+ * The foundational type definitions for the Object UI schema protocol.
+ * These types define the universal interface for all UI components.
+ *
+ * @module base
+ * @packageDocumentation
+ */
+/**
+ * Base schema interface that all component schemas extend.
+ * This is the fundamental building block of the Object UI protocol.
+ *
+ * @example
+ * ```typescript
+ * const schema: BaseSchema = {
+ *   type: 'text',
+ *   id: 'greeting',
+ *   className: 'text-lg font-bold',
+ *   data: { message: 'Hello World' }
+ * }
+ * ```
+ */
+export interface BaseSchema {
+    /**
+     * Component type identifier. Determines which renderer to use.
+     * @example 'input', 'button', 'form', 'grid'
+     */
+    type: string;
+    /**
+     * Unique identifier for the component instance.
+     * Used for state management, event handling, and React keys.
+     */
+    id?: string;
+    /**
+     * Human-readable name for the component.
+     * Used for form field names, labels, and debugging.
+     */
+    name?: string;
+    /**
+     * Display label for the component.
+     * Often used in forms, cards, and other UI elements.
+     */
+    label?: string;
+    /**
+     * Descriptive text providing additional context.
+     * Typically rendered as help text below the component.
+     */
+    description?: string;
+    /**
+     * Placeholder text for input components.
+     * Provides hints about expected input format or content.
+     */
+    placeholder?: string;
+    /**
+     * Tailwind CSS classes to apply to the component.
+     * This is the primary styling mechanism in Object UI.
+     * @example 'bg-blue-500 text-white p-4 rounded-lg'
+     */
+    className?: string;
+    /**
+     * Inline CSS styles as a JavaScript object.
+     * Use sparingly - prefer className with Tailwind.
+     * @example { backgroundColor: '#fff', padding: '16px' }
+     */
+    style?: Record<string, string | number>;
+    /**
+     * Arbitrary data attached to the component.
+     * Can be used for custom properties, state, or context.
+     */
+    data?: any;
+    /**
+     * Child components or content.
+     * Can be a single component, array of components, or primitive values.
+     */
+    body?: SchemaNode | SchemaNode[];
+    /**
+     * Alternative name for children (React-style).
+     * Some components use 'children' instead of 'body'.
+     */
+    children?: SchemaNode | SchemaNode[];
+    /**
+     * Controls whether the component is visible.
+     * When false, component is not rendered (display: none).
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Expression for conditional visibility.
+     * Evaluated against the current data context.
+     * @example "${data.role === 'admin'}"
+     */
+    visibleOn?: string;
+    /**
+     * Controls whether the component is hidden (but still rendered).
+     * When true, component is rendered but not visible (visibility: hidden).
+     * @default false
+     */
+    hidden?: boolean;
+    /**
+     * Expression for conditional hiding.
+     * @example "${!data.isActive}"
+     */
+    hiddenOn?: string;
+    /**
+     * Controls whether the component is disabled.
+     * Applies to interactive components like buttons and inputs.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Expression for conditional disabling.
+     * @example "${data.status === 'locked'}"
+     */
+    disabledOn?: string;
+    /**
+     * Test ID for automated testing.
+     * Rendered as data-testid attribute.
+     */
+    testId?: string;
+    /**
+     * Accessibility label for screen readers.
+     * Rendered as aria-label attribute.
+     */
+    ariaLabel?: string;
+    /**
+     * Additional properties specific to the component type.
+     * This index signature allows type-specific extensions.
+     */
+    [key: string]: any;
+}
+/**
+ * A schema node can be a full schema object or a primitive value.
+ * This union type supports both structured components and simple content.
+ *
+ * @example
+ * ```typescript
+ * const nodes: SchemaNode[] = [
+ *   { type: 'text', value: 'Hello' },
+ *   'Plain string',
+ *   { type: 'button', label: 'Click' }
+ * ]
+ * ```
+ */
+export type SchemaNode = BaseSchema | string | number | boolean | null | undefined;
+/**
+ * Component renderer function type.
+ * Accepts a schema and returns a rendered component.
+ * Framework-agnostic - can be React, Vue, or any other renderer.
+ */
+export interface ComponentRendererProps<TSchema extends BaseSchema = BaseSchema> {
+    /**
+     * The schema object to render
+     */
+    schema: TSchema;
+    /**
+     * Additional properties passed to the renderer
+     */
+    [key: string]: any;
+}
+/**
+ * Input field configuration for component metadata.
+ * Describes what properties a component accepts in the designer/editor.
+ */
+export interface ComponentInput {
+    /**
+     * Property name (must match schema property)
+     */
+    name: string;
+    /**
+     * Input control type
+     */
+    type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
+    /**
+     * Display label in the editor
+     */
+    label?: string;
+    /**
+     * Default value for new instances
+     */
+    defaultValue?: any;
+    /**
+     * Whether this property is required
+     */
+    required?: boolean;
+    /**
+     * Enum options (for type='enum')
+     */
+    enum?: string[] | {
+        label: string;
+        value: any;
+    }[];
+    /**
+     * Help text or description
+     */
+    description?: string;
+    /**
+     * Whether this is an advanced/expert option
+     */
+    advanced?: boolean;
+    /**
+     * Specific input type (e.g., 'email', 'password' for string)
+     */
+    inputType?: string;
+    /**
+     * Minimum value (for number/date)
+     */
+    min?: number;
+    /**
+     * Maximum value (for number/date)
+     */
+    max?: number;
+    /**
+     * Step value (for number)
+     */
+    step?: number;
+    /**
+     * Placeholder text
+     */
+    placeholder?: string;
+}
+/**
+ * Component metadata for registration and designer integration.
+ * Describes the component's capabilities, defaults, and documentation.
+ */
+export interface ComponentMeta {
+    /**
+     * Display name in designer/palette
+     */
+    label?: string;
+    /**
+     * Icon name or SVG string
+     */
+    icon?: string;
+    /**
+     * Category for grouping (e.g., 'Layout', 'Form', 'Data Display')
+     */
+    category?: string;
+    /**
+     * Configurable properties
+     */
+    inputs?: ComponentInput[];
+    /**
+     * Default property values for new instances
+     */
+    defaultProps?: Record<string, any>;
+    /**
+     * Default children for container components
+     */
+    defaultChildren?: SchemaNode[];
+    /**
+     * Example configurations for documentation
+     */
+    examples?: Record<string, any>;
+    /**
+     * Whether the component can have children
+     */
+    isContainer?: boolean;
+    /**
+     * Whether the component can be resized in the designer
+     */
+    resizable?: boolean;
+    /**
+     * Resize constraints (which dimensions can be resized)
+     */
+    resizeConstraints?: {
+        width?: boolean;
+        height?: boolean;
+        minWidth?: number;
+        maxWidth?: number;
+        minHeight?: number;
+        maxHeight?: number;
+    };
+    /**
+     * Tags for search/filtering
+     */
+    tags?: string[];
+    /**
+     * Description for documentation
+     */
+    description?: string;
+}
+/**
+ * Complete component configuration combining renderer and metadata.
+ */
+export interface ComponentConfig extends ComponentMeta {
+    /**
+     * Unique component type identifier
+     */
+    type: string;
+    /**
+     * The component renderer (framework-specific)
+     */
+    component: any;
+}
+/**
+ * Common HTML attributes that can be applied to components
+ */
+export interface HTMLAttributes {
+    id?: string;
+    className?: string;
+    style?: Record<string, any>;
+    title?: string;
+    role?: string;
+    'aria-label'?: string;
+    'aria-describedby'?: string;
+    'data-testid'?: string;
+}
+/**
+ * Event handler types
+ */
+export interface EventHandlers {
+    onClick?: (event?: any) => void | Promise<void>;
+    onChange?: (value: any, event?: any) => void | Promise<void>;
+    onSubmit?: (data: any, event?: any) => void | Promise<void>;
+    onFocus?: (event?: any) => void;
+    onBlur?: (event?: any) => void;
+    onKeyDown?: (event?: any) => void;
+    onKeyUp?: (event?: any) => void;
+    onMouseEnter?: (event?: any) => void;
+    onMouseLeave?: (event?: any) => void;
+}
+/**
+ * Common style properties using Tailwind's semantic naming
+ */
+export interface StyleProps {
+    /**
+     * Padding (Tailwind scale: 0-96)
+     */
+    padding?: number | string;
+    /**
+     * Margin (Tailwind scale: 0-96)
+     */
+    margin?: number | string;
+    /**
+     * Gap between flex/grid items (Tailwind scale: 0-96)
+     */
+    gap?: number | string;
+    /**
+     * Background color
+     */
+    backgroundColor?: string;
+    /**
+     * Text color
+     */
+    textColor?: string;
+    /**
+     * Border width
+     */
+    borderWidth?: number | string;
+    /**
+     * Border color
+     */
+    borderColor?: string;
+    /**
+     * Border radius
+     */
+    borderRadius?: number | string;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"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"}

package/dist/base.js

@@ -0,0 +1,10 @@
+/**
+ * @object-ui/types - Base Schema Types
+ *
+ * The foundational type definitions for the Object UI schema protocol.
+ * These types define the universal interface for all UI components.
+ *
+ * @module base
+ * @packageDocumentation
+ */
+export {};