@mapples/types

TypeScript type definitions for the Mapples Open Kit. This package provides all the core type definitions used across the Mapples ecosystem, including component registration, form configurations, and asset management.

Installation

npm install @mapples/types
# or
yarn add @mapples/types

Overview

The @mapples/types package contains essential TypeScript interfaces and types that define the structure and behavior of components, forms, and assets in the Mapples system. These types ensure type safety and provide clear contracts for developers working with the Mapples Open Kit.

Core Types

Action Types

Action

Represents a user action that occurred in the application. Actions are used for tracking user interactions, analytics, and state management.

interface Action {
  time: number; // Timestamp when the action occurred (in milliseconds since epoch)
  type?: string; // Optional string identifier for the type of action
  payload?: ActionPayload; // Optional payload containing additional data about the action
}

ActionPayload

Represents the payload data that can be attached to an action.

interface ActionPayload {
  originalEventData?: any[]; // Original event data from the source event
  data?: any; // Custom data payload specific to the action
}

Example:

import { Action, ActionPayload } from '@mapples/types';

const userAction: Action = {
  time: Date.now(),
  type: 'BUTTON_PRESSED',
  payload: {
    data: { buttonId: 'submit', userId: '123' },
    originalEventData: ['button', 'press', { x: 100, y: 200 }],
  },
};

Mapplet Types

MappletType<State>

Represents the configuration interface for a Mapplet application. A Mapplet is a self-contained application that can be embedded or run standalone.

interface MappletType<State extends object = object> {
  state?: State; // Optional initial state object for the Mapplet
  onAction?: (action: Action) => void; // Optional callback function to handle actions
}

Example:

import { MappletType, Action } from '@mapples/types';

interface MyAppState {
  user: { name: string; email: string };
  settings: { theme: string };
}

const myMapplet: MappletType<MyAppState> = {
  state: {
    user: { name: 'John', email: 'john@example.com' },
    settings: { theme: 'dark' },
  },
  onAction: (action: Action) => {
    console.log('Mapplet action:', action);
    // Handle analytics, logging, etc.
  },
};

Asset Types

AssetType

Represents the different types of assets that can be used in the Mapples system.

type AssetType = 'image' | 'video' | 'icon' | 'font' | 'json';

Example:

import { AssetType } from '@mapples/types';

const imageAsset: AssetType = 'image';
const videoAsset: AssetType = 'video';

Component Types

RegisteredComponent<T>

Defines the structure for registering components in the Mapples component system. This interface contains all the metadata needed to make a component available in the visual editor.

interface RegisteredComponent<T extends object = object> {
  type: string; // Unique component identifier
  groupId: string; // Group this component belongs to
  label: string; // Display name
  Component: ComponentType<PropsWithChildren<T>>; // React component
  Icon: ComponentType<SvgProps>; // Icon for component palette
  initialProps: T; // Default props
  styleKeys: StyleKey[]; // Available style properties
  props: PropsFormField[]; // Property form fields
  actionProps: string[]; // Action-triggering properties
  hidden?: boolean; // Hide from palette
  hasChildren?: boolean; // Can contain children
}

Example:

import { RegisteredComponent } from '@mapples/types';

interface ButtonProps {
  text: string;
  disabled?: boolean;
  onPress?: () => void;
}

const buttonComponent: RegisteredComponent<ButtonProps> = {
  type: 'Button',
  groupId: 'inputs',
  label: 'Button',
  Component: Button,
  Icon: ButtonIcon,
  initialProps: { text: 'Click me' },
  styleKeys: [backgroundColorStyle, textColorStyle],
  props: [textField, disabledField],
  actionProps: ['onPress'],
};

RegisteredComponentsGroup

Represents a group of components in the component palette.

interface RegisteredComponentsGroup {
  id: string; // Unique group identifier
  label: string; // Display name
  Icon: ComponentType<SvgProps>; // Group icon
}

RegisteredComponents

A registry mapping component types to their definitions.

type RegisteredComponents = Record<string, RegisteredComponent>;

StyleKey

Defines a style property configuration.

interface StyleKey {
  label: string; // Human-readable label
  value: string; // CSS property name
  forms: StyleFormType[]; // Applicable form types
}

Form Types

StyleFormType

Enum representing different categories of style forms.

enum StyleFormType {
  Dimension = 'Dimension', // Width, height, min/max dimensions
  Image = 'Image', // Background images, object fit
  Text = 'Text', // Text color, alignment
  Typography = 'Typography', // Font family, size, weight
  Position = 'Position', // Top, left, right, bottom
  Surface = 'Surface', // Background color, opacity
  ScrollSurface = 'ScrollSurface', // Scrollable surface properties
  Borders = 'Borders', // Border width, color, radius
  Shadow = 'Shadow', // Box shadow, elevation
  Spacing = 'Spacing', // Margin, padding
  Svg = 'Svg', // SVG-related properties
}

PropsFormType

Enum for property form field types.

enum PropsFormType {
  Text = 'Text', // Text input field
  Select = 'Select', // Single selection dropdown
  Switch = 'Switch', // Boolean toggle
  MultiSelect = 'MultiSelect', // Multiple selection dropdown
}

PropsFormField

Configuration for component property form fields.

interface PropsFormField {
  propsKey: string; // Property key in component props
  label: string; // Form field label
  options?: PropsFormFieldOptions; // Options for select fields
  type: PropsFormType; // Form field type
  dataProp?: boolean; // Can be bound to data sources
}

Example:

import { PropsFormField, PropsFormType } from '@mapples/types';

const textField: PropsFormField = {
  propsKey: 'text',
  label: 'Button Text',
  type: PropsFormType.Text,
};

const sizeField: PropsFormField = {
  propsKey: 'size',
  label: 'Size',
  type: PropsFormType.Select,
  options: [
    { label: 'Small', value: 'sm' },
    { label: 'Medium', value: 'md' },
    { label: 'Large', value: 'lg' },
  ],
};

PropsFormFieldOption

Represents an option in select/multi-select fields.

interface PropsFormFieldOption {
  label: string; // Display text
  value: string; // Stored value
}

PropsFormFieldOptions

Union type for form field options.

type PropsFormFieldOptions =
  | PropsFormFieldOption[] // Array of options
  | 'typography' // Special typography type
  | AssetType; // Asset type for asset selection

ActionFormProps

Configuration for action properties.

interface ActionFormProps {
  propsKey: string; // Action property key
  label: string; // Form field label
}

PropsFieldConfig

Mapping of form types to their React components.

type PropsFieldConfig = Record<PropsFormType, ComponentType<PropsFormField>>;

Usage Examples

Registering a Component

import {
  RegisteredComponent,
  PropsFormField,
  PropsFormType,
  StyleFormType,
  StyleKey,
} from '@mapples/types';

// Define component props
interface MyButtonProps {
  text: string;
  variant: 'primary' | 'secondary';
  disabled?: boolean;
}

// Create style keys
const backgroundColorStyle: StyleKey = {
  label: 'Background Color',
  value: 'backgroundColor',
  forms: [StyleFormType.Surface],
};

// Create form fields
const textField: PropsFormField = {
  propsKey: 'text',
  label: 'Button Text',
  type: PropsFormType.Text,
};

const variantField: PropsFormField = {
  propsKey: 'variant',
  label: 'Variant',
  type: PropsFormType.Select,
  options: [
    { label: 'Primary', value: 'primary' },
    { label: 'Secondary', value: 'secondary' },
  ],
};

// Register the component
const myButtonComponent: RegisteredComponent<MyButtonProps> = {
  type: 'MyButton',
  groupId: 'custom',
  label: 'My Button',
  Component: MyButton,
  Icon: MyButtonIcon,
  initialProps: {
    text: 'Click me',
    variant: 'primary',
  },
  styleKeys: [backgroundColorStyle],
  props: [textField, variantField],
  actionProps: ['onPress'],
};

Creating a Component Group

import { RegisteredComponentsGroup } from '@mapples/types';

const customGroup: RegisteredComponentsGroup = {
  id: 'custom',
  label: 'Custom Components',
  Icon: CustomIcon,
};

Working with Form Fields

import {
  PropsFormField,
  PropsFormType,
  PropsFormFieldOptions,
} from '@mapples/types';

// Text field
const nameField: PropsFormField = {
  propsKey: 'name',
  label: 'Name',
  type: PropsFormType.Text,
};

// Select field with options
const statusField: PropsFormField = {
  propsKey: 'status',
  label: 'Status',
  type: PropsFormType.Select,
  options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' },
    { label: 'Pending', value: 'pending' },
  ],
};

// Asset selection field
const imageField: PropsFormField = {
  propsKey: 'image',
  label: 'Image',
  type: PropsFormType.Select,
  options: 'image', // AssetType
};

// Typography field
const fontField: PropsFormField = {
  propsKey: 'font',
  label: 'Font',
  type: PropsFormType.Select,
  options: 'typography',
};

Integration with Other Packages

This types package is used throughout the Mapples ecosystem:

• @mapples/action: Uses Action and ActionPayload types for action management
• @mapples/state: Uses state-related types for state management
• @mapples/ui: Uses RegisteredComponent and related types for component registration
• @mapples/form: Uses PropsFormField and form-related types for property editing
• @mapples/style: Uses StyleKey and StyleFormType for styling configuration
• @mapples/render: Uses component types for rendering components

Type Safety

All types in this package are designed to provide maximum type safety and IntelliSense support. When working with Mapples components, you'll get:

• Autocomplete for all properties
• Type checking for component props
• Validation for form field configurations
• IntelliSense for style properties

Contributing

When adding new types to this package:

1. Follow the existing naming conventions
2. Add comprehensive TSDoc comments
3. Include usage examples
4. Update this README with new types
5. Ensure all types are exported from the main index file

License

MIT

Interfaces

• ActionPayload
• Action
• RegisteredComponent
• DataProp
• SvgSource
• MappletType

Type Aliases

• RegisteredComponents
• DataProps