@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.4

package/src/atoms/index.ts

@@ -1,600 +0,0 @@
-/**
- * Compile-Time Atom Stubs — markers for the compiler to recognize.
- *
- * These are NOT runtime components — they are compile-time type stubs that
- * the @mindmatrix/react-compiler recognizes in JSX and maps to IRExperienceNode
- * entries. At runtime, the frontend's ComponentTreeRenderer resolves the
- * component name string to the actual registered React component.
- *
- * Usage in .workflow.tsx files:
- *   import { Stack, Row, Text, Button, TextInput } from '@mindmatrix/react/atoms';
- *
- *   return (
- *     <Stack gap={4}>
- *       <Text variant="h2">Hello</Text>
- *       <Row>
- *         <TextInput bind="message" placeholder="Type..." />
- *         <Button onClick={send}>Send</Button>
- *       </Row>
- *     </Stack>
- *   );
- *
- * The compiler extracts this JSX into an IRExperienceNode tree.
- * The CTR (ComponentTreeRenderer) renders it at runtime.
- *
- * ALL core atoms + sub-experience components are stubbed here,
- * matching the frontend's component-registry.ts exactly.
- */
-
-import type { FC, ReactNode } from 'react';
-
-// =============================================================================
-// Base Props (shared across all atoms)
-// =============================================================================
-
-interface BaseAtomProps {
-  children?: ReactNode;
-  visible_when?: string;
-  'data-slot'?: string;
-  className?: string;
-  /** Style object — maps to CSS properties at runtime. */
-  sx?: Record<string, unknown>;
-  /** Common layout shortcuts — passed through to the CTR renderer. */
-  flex?: number | string;
-  width?: number | string;
-  height?: number | string;
-  minWidth?: number | string;
-  minHeight?: number | string;
-  maxWidth?: number | string;
-  maxHeight?: number | string;
-  margin?: number | string;
-  marginTop?: number | string;
-  marginBottom?: number | string;
-  marginLeft?: number | string;
-  marginRight?: number | string;
-  padding?: number | string;
-  paddingTop?: number | string;
-  paddingBottom?: number | string;
-  paddingLeft?: number | string;
-  paddingRight?: number | string;
-  overflow?: string;
-  border?: string;
-  borderTop?: string;
-  borderBottom?: string;
-  borderLeft?: string;
-  borderRight?: string;
-  borderRadius?: number | string;
-  background?: string;
-  position?: string;
-  display?: string;
-  opacity?: number;
-}
-
-// =============================================================================
-// Layout Atoms
-// =============================================================================
-
-interface StackProps extends BaseAtomProps {
-  gap?: number | string;
-  align?: 'start' | 'center' | 'end' | 'stretch';
-  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'space-between' | 'space-around';
-}
-
-interface RowProps extends BaseAtomProps {
-  gap?: number | string;
-  align?: 'start' | 'center' | 'end' | 'stretch';
-  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'space-between' | 'space-around';
-  wrap?: boolean;
-}
-
-interface GridProps extends BaseAtomProps {
-  columns?: number | string;
-  gap?: number | string;
-  minChildWidth?: string;
-}
-
-interface DividerProps extends BaseAtomProps {
-  orientation?: 'horizontal' | 'vertical';
-}
-
-interface SpacerProps extends BaseAtomProps {
-  size?: number | string;
-}
-
-// =============================================================================
-// Content Atoms
-// =============================================================================
-
-interface TextProps extends BaseAtomProps {
-  variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'body' | 'caption' | 'code' | 'label' | 'muted';
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  weight?: 'normal' | 'medium' | 'semibold' | 'bold' | string;
-  value?: string;
-  bind?: string;
-  color?: string;
-  align?: 'left' | 'center' | 'right';
-}
-
-interface HeadingProps extends BaseAtomProps {
-  level?: 1 | 2 | 3 | 4;
-  value?: string;
-  weight?: 'normal' | 'medium' | 'semibold' | 'bold' | string;
-}
-
-interface FieldProps extends BaseAtomProps {
-  name?: string;
-  bind?: string;
-  label?: string;
-  editable?: boolean;
-}
-
-interface ImageProps extends BaseAtomProps {
-  src?: string;
-  alt?: string;
-  width?: number | string;
-  height?: number | string;
-  bind?: string;
-}
-
-interface BadgeProps extends BaseAtomProps {
-  value?: string;
-  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
-  bind?: string;
-}
-
-// =============================================================================
-// Action Atoms
-// =============================================================================
-
-interface ButtonProps extends BaseAtomProps {
-  variant?: 'default' | 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';
-  size?: 'sm' | 'md' | 'lg' | 'icon';
-  disabled?: boolean;
-  loading?: boolean;
-  onClick?: (() => void) | string;
-  onPress?: (() => void) | string;
-  label?: string;
-  icon?: string;
-  fullWidth?: boolean;
-}
-
-interface LinkProps extends BaseAtomProps {
-  href?: string;
-  to?: string;
-  target?: '_blank' | '_self';
-  bind?: string;
-}
-
-// =============================================================================
-// Control Flow Atoms
-// =============================================================================
-
-interface ShowProps extends BaseAtomProps {
-  when?: unknown;
-  fallback?: ReactNode;
-}
-
-interface EachProps<T = unknown> extends BaseAtomProps {
-  items?: T[];
-  as?: string;
-  bind?: string;
-}
-
-// =============================================================================
-// Grouping Atoms
-// =============================================================================
-
-interface CardProps extends BaseAtomProps {
-  title?: string;
-  collapsible?: boolean;
-  defaultCollapsed?: boolean;
-  onClick?: (() => void) | string;
-}
-
-interface TabsProps extends BaseAtomProps {
-  defaultTab?: string;
-  tabs?: Array<{ id: string; label: string }>;
-}
-
-interface AccordionProps extends BaseAtomProps {
-  type?: 'single' | 'multiple';
-  defaultValue?: string;
-}
-
-interface SectionProps extends BaseAtomProps {
-  title?: string;
-  description?: string;
-}
-
-interface ModalProps extends BaseAtomProps {
-  title?: string;
-  open?: boolean;
-  onClose?: (() => void) | string;
-}
-
-// =============================================================================
-// Input Atoms
-// =============================================================================
-
-interface TextInputProps extends BaseAtomProps {
-  bind?: string;
-  value?: string;
-  onChange?: ((value: string) => void) | string;
-  placeholder?: string;
-  label?: string;
-  multiline?: boolean;
-  rows?: number;
-  maxLength?: number;
-  submitOnEnter?: boolean;
-  onSubmit?: (() => void) | string;
-  disabled?: boolean;
-}
-
-interface SelectProps extends BaseAtomProps {
-  bind?: string;
-  value?: string;
-  onChange?: ((value: string) => void) | string;
-  options?: Array<{ value: string; label: string }> | string[];
-  placeholder?: string;
-  label?: string;
-  disabled?: boolean;
-}
-
-interface MarkdownProps extends BaseAtomProps {
-  content?: string;
-  bind?: string;
-}
-
-interface ScrollAreaProps extends BaseAtomProps {
-  maxHeight?: number | string;
-}
-
-// =============================================================================
-// Creative/Visualization Atoms
-// =============================================================================
-
-interface Canvas3DProps extends BaseAtomProps {
-  shape?: 'cube' | 'sphere' | 'torus' | 'torusKnot';
-  color?: string;
-  wireframe?: boolean;
-  autoRotate?: boolean;
-}
-
-interface DataGridProps extends BaseAtomProps {
-  bind?: string;
-  /** Model definition or slug to query data from. */
-  source?: unknown;
-  columns?: Array<{ field: string; header: string; editable?: boolean }>;
-  /** Filter params for the data query. */
-  filters?: Record<string, unknown>;
-}
-
-interface AnimatedBoxProps extends BaseAtomProps {
-  animation?: 'pulse' | 'bounce' | 'spin' | 'slide-in' | 'fade-in' | 'scale-up' | 'glow' | 'shake' | 'flip' | 'morph';
-  duration?: number;
-}
-
-interface ServerGridProps extends BaseAtomProps {
-  bind?: string;
-  endpoint?: string;
-  columns?: Array<{ field: string; header: string; sortable?: boolean }>;
-  pageSize?: number;
-}
-
-interface ChartProps extends BaseAtomProps {
-  type?: 'bar' | 'line' | 'area' | 'pie' | 'sparkline';
-  bind?: string;
-  data?: unknown[];
-  xField?: string;
-  yField?: string;
-  color?: string;
-}
-
-interface MetricCardProps extends BaseAtomProps {
-  value?: number | string;
-  label?: string;
-  format?: 'currency' | 'number' | 'percentage';
-  trend?: 'up' | 'down' | 'flat';
-  sparkline?: boolean;
-  bind?: string;
-}
-
-// =============================================================================
-// Slot Atom (for blueprint contributions)
-// =============================================================================
-
-interface SlotProps extends BaseAtomProps {
-  name: string;
-  fallback?: ReactNode;
-}
-
-// =============================================================================
-// Module Composition Atoms
-// =============================================================================
-
-interface ModuleOutletProps extends BaseAtomProps {
-  /** Module slug to render views from. */
-  module: string;
-  /** Base path for the module's routes within this outlet. */
-  basePath?: string;
-  /** Fallback content when no module route matches. */
-  fallback?: ReactNode;
-}
-
-// =============================================================================
-// Sub-Experience Components
-// =============================================================================
-
-interface MetricsGridProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface AdaptiveCardGridProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface AdaptiveFiltersProps extends BaseAtomProps {
-  bind?: string;
-  fields?: string[];
-}
-
-interface PaginationProps extends BaseAtomProps {
-  bind?: string;
-  pageSize?: number;
-}
-
-interface EntityHeaderProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface ProgressTrackerProps extends BaseAtomProps {
-  bind?: string;
-  steps?: string[];
-}
-
-interface RatingWidgetProps extends BaseAtomProps {
-  bind?: string;
-  max?: number;
-}
-
-interface FieldSectionProps extends BaseAtomProps {
-  title?: string;
-  fields?: string[];
-}
-
-interface TransitionActionsProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface ChildInstanceListProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface BreakdownChartsProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface TabbedLayoutProps extends BaseAtomProps {
-  tabs?: Array<{ id: string; label: string }>;
-}
-
-interface HierarchyBreadcrumbProps extends BaseAtomProps {
-  bind?: string;
-}
-
-interface SearchInputProps extends BaseAtomProps {
-  bind?: string;
-  placeholder?: string;
-}
-
-interface SortControlProps extends BaseAtomProps {
-  bind?: string;
-  fields?: string[];
-}
-
-interface AggregateStatsProps extends BaseAtomProps {
-  bind?: string;
-}
-
-// =============================================================================
-// Stub factory — creates a compile-time-only component.
-// At runtime these throw; the CTR resolves components by name, not by import.
-// =============================================================================
-
-function stub<P>(displayName: string): FC<P> {
-  const Component: FC<P> = () => {
-    throw new Error(
-      `<${displayName}> is a compile-time stub from @mindmatrix/react/atoms. ` +
-      `It should only appear in .workflow.tsx files processed by the compiler. ` +
-      `At runtime, use the ComponentTreeRenderer which resolves "${displayName}" from the component registry.`
-    );
-  };
-  Component.displayName = displayName;
-  return Component;
-}
-
-// =============================================================================
-// Layout
-// =============================================================================
-export const Stack = stub<StackProps>('Stack');
-export const Row = stub<RowProps>('Row');
-export const Column = stub<RowProps>('Column');
-export const Grid = stub<GridProps>('Grid');
-export const Divider = stub<DividerProps>('Divider');
-export const Spacer = stub<SpacerProps>('Spacer');
-
-// =============================================================================
-// Content
-// =============================================================================
-export const Text = stub<TextProps>('Text');
-export const Heading = stub<HeadingProps>('Heading');
-export const Field = stub<FieldProps>('Field');
-export const Image = stub<ImageProps>('Image');
-export const Badge = stub<BadgeProps>('Badge');
-export const Icon = stub<BaseAtomProps & { name?: string; size?: number | string; color?: string }>('Icon');
-
-// =============================================================================
-// Actions
-// =============================================================================
-export const Button = stub<ButtonProps>('Button');
-export const Link = stub<LinkProps>('Link');
-
-// =============================================================================
-// Control Flow
-// =============================================================================
-export const Show = stub<ShowProps>('Show');
-export const Each = stub<EachProps>('Each');
-
-// =============================================================================
-// Grouping
-// =============================================================================
-export const Card = stub<CardProps>('Card');
-export const Tabs = stub<TabsProps>('Tabs');
-export const Accordion = stub<AccordionProps>('Accordion');
-export const Section = stub<SectionProps>('Section');
-export const Modal = stub<ModalProps>('Modal');
-
-// =============================================================================
-// Input
-// =============================================================================
-export const TextInput = stub<TextInputProps>('TextInput');
-export const Select = stub<SelectProps>('Select');
-export const Markdown = stub<MarkdownProps>('Markdown');
-export const ScrollArea = stub<ScrollAreaProps>('ScrollArea');
-
-// =============================================================================
-// Creative/Visualization
-// =============================================================================
-export const Canvas3D = stub<Canvas3DProps>('Canvas3D');
-export const DataGrid = stub<DataGridProps>('DataGrid');
-export const AnimatedBox = stub<AnimatedBoxProps>('AnimatedBox');
-export const ServerGrid = stub<ServerGridProps>('ServerGrid');
-export const Chart = stub<ChartProps>('Chart');
-export const MetricCard = stub<MetricCardProps>('MetricCard');
-
-// =============================================================================
-// Slot
-// =============================================================================
-export const Slot = stub<SlotProps>('Slot');
-
-// =============================================================================
-// Module Composition
-// =============================================================================
-export const ModuleOutlet = stub<ModuleOutletProps>('ModuleOutlet');
-
-// =============================================================================
-// Sub-Experience Components
-// =============================================================================
-export const MetricsGrid = stub<MetricsGridProps>('MetricsGrid');
-export const AdaptiveCardGrid = stub<AdaptiveCardGridProps>('AdaptiveCardGrid');
-export const AdaptiveFilters = stub<AdaptiveFiltersProps>('AdaptiveFilters');
-export const Pagination = stub<PaginationProps>('Pagination');
-export const EntityHeader = stub<EntityHeaderProps>('EntityHeader');
-export const ProgressTracker = stub<ProgressTrackerProps>('ProgressTracker');
-export const RatingWidget = stub<RatingWidgetProps>('RatingWidget');
-export const FieldSection = stub<FieldSectionProps>('FieldSection');
-export const TransitionActions = stub<TransitionActionsProps>('TransitionActions');
-export const ChildInstanceList = stub<ChildInstanceListProps>('ChildInstanceList');
-export const BreakdownCharts = stub<BreakdownChartsProps>('BreakdownCharts');
-export const TabbedLayout = stub<TabbedLayoutProps>('TabbedLayout');
-export const HierarchyBreadcrumb = stub<HierarchyBreadcrumbProps>('HierarchyBreadcrumb');
-export const SearchInput = stub<SearchInputProps>('SearchInput');
-export const SortControl = stub<SortControlProps>('SortControl');
-export const AggregateStats = stub<AggregateStatsProps>('AggregateStats');
-
-// =============================================================================
-// Routing Atoms
-// =============================================================================
-
-interface RouterProps extends BaseAtomProps {
-  /** Base path prefix for all child routes. */
-  basePath?: string;
-  /** Default/initial route path. */
-  defaultRoute?: string;
-}
-
-interface RouteProps extends BaseAtomProps {
-  /** Route path pattern (e.g., '/rides/:id'). */
-  path: string;
-  /** Route guard — expression that must be truthy for route to render. */
-  guard?: string;
-  /** Redirect path if guard fails. */
-  redirect?: string;
-  /** Route metadata. */
-  meta?: Record<string, unknown>;
-  /** Whether this is a catch-all/fallback route. */
-  fallback?: boolean;
-}
-
-interface NavLinkProps extends BaseAtomProps {
-  /** Target route path. */
-  to: string;
-  /** Link label text. */
-  label?: string;
-  /** Icon name (lucide icon). */
-  icon?: string;
-  /** Visual variant. */
-  variant?: 'default' | 'tab' | 'pill' | string;
-  /** Route guard expression. */
-  guard?: string;
-  /** Active class name override. */
-  activeClassName?: string;
-}
-
-interface RoleGuardProps extends BaseAtomProps {
-  /** Role name required to render children. */
-  role: string;
-  /** Role hierarchy for comparison (highest to lowest). */
-  hierarchy?: string[];
-  /** Whether to include higher roles (default: true). */
-  includeHigher?: boolean;
-  /** Fallback content when role check fails. */
-  fallback?: ReactNode;
-}
-
-export const Router = stub<RouterProps>('Router');
-export const Route = stub<RouteProps>('Route');
-export const NavLink = stub<NavLinkProps>('NavLink');
-export const RoleGuard = stub<RoleGuardProps>('RoleGuard');
-
-// =============================================================================
-// Type Re-exports (for .workflow.tsx authoring)
-// =============================================================================
-export type {
-  BaseAtomProps,
-  StackProps,
-  RowProps,
-  GridProps,
-  DividerProps,
-  SpacerProps,
-  TextProps,
-  HeadingProps,
-  FieldProps,
-  ImageProps,
-  BadgeProps,
-  ButtonProps,
-  LinkProps,
-  ShowProps,
-  EachProps,
-  CardProps,
-  TabsProps,
-  AccordionProps,
-  SectionProps,
-  ModalProps,
-  TextInputProps,
-  SelectProps,
-  MarkdownProps,
-  ScrollAreaProps,
-  Canvas3DProps,
-  DataGridProps,
-  AnimatedBoxProps,
-  ServerGridProps,
-  ChartProps,
-  MetricCardProps,
-  SlotProps,
-  ModuleOutletProps,
-  RouterProps,
-  RouteProps,
-  NavLinkProps,
-  RoleGuardProps,
-};

package/src/authoring.ts

@@ -1,92 +0,0 @@
-/**
- * Authoring-time API — compile-time declarations for the @mindmatrix/react
- * workflow DSL.
- *
- * These functions are used when writing .workflow.tsx files. The Babel plugin
- * (@mindmatrix/react-compiler) transforms them at compile time into IR.
- * They are NOT called at runtime — the compiler replaces them with runtime
- * equivalents (useExperienceState, useTransition with 1 arg, etc.).
- *
- * Exporting them here allows TypeScript to type-check authored workflow files
- * without errors, and IDEs to provide autocompletion.
- */
-
-import type { TransitionHandle } from './hooks/useTransition';
-
-// =============================================================================
-// useState — field binding (NOT React.useState)
-// =============================================================================
-
-/**
- * Declare a workflow field with a default value.
- * The Babel plugin extracts this into the IR's `fields` array.
- *
- * @param defaultValue - The field's default value (also determines its type).
- * @returns A [value, setter] tuple (like React.useState).
- *
- * @example
- * ```tsx
- * const [email, setEmail] = useState<string>("");
- * const [count, setCount] = useState<number>(0);
- * const [active, setActive] = useState<boolean>(true);
- * ```
- */
-export function useState<T = unknown>(defaultValue: T): [T, (value: T) => void];
-
-/**
- * Declare a workflow field bound to a named field key.
- * Used when the field name differs from the variable name.
- *
- * @param fieldKey - The field key in the workflow definition.
- * @returns A [value, setter] tuple.
- *
- * @example
- * ```tsx
- * const [ride, setRide] = useState("rideData");
- * ```
- */
-export function useState<T = unknown>(fieldKey: string): [T, (value: T) => void];
-
-// Implementation signature (not visible to consumers)
-export function useState<T = unknown>(_defaultOrKey?: T | string): [T, (value: T) => void] {
-  // This function is never actually called — the Babel plugin replaces it.
-  // Return a dummy tuple for runtime safety if somehow invoked.
-  return [undefined as T, () => {}];
-}
-
-// =============================================================================
-// useTransition — authoring overload (2-arg form)
-// =============================================================================
-
-export interface TransitionConfig {
-  from: string;
-  to: string;
-  requiredFields?: string[];
-  conditions?: string[];
-}
-
-/**
- * Declare a workflow transition with from/to states.
- * The Babel plugin extracts this into the IR's `transitions` array.
- *
- * @param name - Transition name.
- * @param config - Transition configuration (from, to, requiredFields).
- * @returns A TransitionHandle with `.fire()` method.
- *
- * @example
- * ```tsx
- * const login = useTransition("login", {
- *   from: "unauthenticated",
- *   to: "authenticating",
- *   requiredFields: ["email", "password"],
- * });
- * // In JSX: onClick={() => login.fire()}
- * ```
- */
-export function useTransitionAuthoring(
-  _name: string,
-  _config: TransitionConfig,
-): TransitionHandle {
-  // Compile-time only — never called at runtime.
-  return { fire: async () => ({ success: true } as any), available: true, pending: false };
-}