@osiloke/chalo 0.1.0

package/dist/types/components/SmartDrawer.d.ts

@@ -0,0 +1,3 @@
+export declare function SmartDrawer({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/components/TargetHighlight.d.ts

@@ -0,0 +1,7 @@
+interface TargetHighlightProps {
+    selector: string;
+    label?: string;
+    pulse?: boolean;
+}
+export declare function TargetHighlight({ selector, label, pulse }: TargetHighlightProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/engine/action-engine.d.ts

@@ -0,0 +1,11 @@
+import { Action, ActionResult, ExecutionContext, ActionHandler, ActionType } from '../types';
+export declare class ActionEngine {
+    private handlers;
+    private abortController;
+    registerHandler(type: ActionType, handler: ActionHandler): void;
+    getHandler(type: ActionType): ActionHandler | undefined;
+    executeAction(action: Action, context: ExecutionContext): Promise<ActionResult>;
+    executeSequence(actions: Action[], context: ExecutionContext, onProgress?: (results: Record<string, ActionResult>) => void): Promise<Record<string, ActionResult>>;
+    cancel(): void;
+}
+export declare const actionEngine: ActionEngine;

package/dist/types/engine/index.d.ts

@@ -0,0 +1 @@
+export { ActionEngine, actionEngine } from './action-engine';

package/dist/types/hooks/use-chalo.d.ts

@@ -0,0 +1,70 @@
+import { MissionId, StepId, SuccessCondition } from '../types';
+import { UseFormReturn, RegisterOptions, FieldValues, Path } from 'react-hook-form';
+export interface UseChaloOptions<TFieldValues extends FieldValues = FieldValues> {
+    form?: UseFormReturn<TFieldValues>;
+    onMissionComplete?: (missionId: MissionId) => void;
+    onStepChange?: (stepId: StepId) => void;
+    /** Enable debug logging to console. Default: false. */
+    debug?: boolean;
+}
+export declare function useChalo<TFieldValues extends FieldValues = FieldValues>(options?: UseChaloOptions<TFieldValues>): {
+    activeMissionId: string | null;
+    currentStepId: string | null;
+    isCompleted: boolean;
+    isPaused: boolean;
+    missions: Record<string, import("..").Mission>;
+    fieldValues: Record<string, unknown>;
+    fieldStates: Record<string, "idle" | "focused" | "valid" | "invalid">;
+    interactionHistory: import("..").ChatInteraction[];
+    startMission: (missionId: MissionId) => void;
+    pauseMission: () => void;
+    resumeMission: () => void;
+    completeMission: () => void;
+    goToStep: (stepId: StepId) => void;
+    reset: () => void;
+    resetMission: () => void;
+    dismissAllTours: () => void;
+    markMissionCompleted: (missionId: MissionId) => void;
+    completedMissions: string[];
+    executionContext: import("..").ExecutionContext;
+    registerActionHandler: (type: import("..").ActionType, handler: import("..").ActionHandler) => void;
+    executeAction: (action: import("..").Action) => Promise<import("..").ActionResult>;
+    executeActionSequence: (actions: import("..").Action[], stepId?: string) => Promise<Record<string, import("..").ActionResult>>;
+    cancelExecution: () => void;
+    addInteraction: (stepId: string, actionText: string) => void;
+    registerMission: (mission: import("..").Mission) => void;
+    activeMission: import("..").Mission | null;
+    currentStep: import("..").Step | null;
+    missionProgress: number;
+    fieldErrors: {};
+    nextStep: () => void;
+    prevStep: () => void;
+    registerField: (name: Path<TFieldValues>, rhfOptions?: RegisterOptions<TFieldValues>) => {
+        id: string;
+        name: Path<TFieldValues>;
+        'data-chalo-field': string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => void;
+        onFocus: () => void;
+        onBlur: () => void;
+    } | {
+        id: string;
+        'data-chalo-field': string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => Promise<void>;
+        onBlur: (e: React.FocusEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => Promise<void>;
+        ref: import("react-hook-form").RefCallBack;
+        name: Path<TFieldValues>;
+        min?: string | number;
+        max?: string | number;
+        maxLength?: number;
+        minLength?: number;
+        pattern?: string;
+        required?: boolean;
+        disabled?: boolean;
+        onFocus?: undefined;
+    };
+    registerElement: (name: string) => (el: HTMLElement | null) => void;
+    fillField: (name: string, value: unknown) => void;
+    recordTourEntry: (missionId: MissionId, stepId: StepId, completed: boolean) => void;
+    tourHistory: Record<string, import("..").TourEntry>;
+    evaluateCondition: (condition?: SuccessCondition) => boolean;
+};

package/dist/types/index.d.mts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './store';
+export * from './hooks/use-chalo';
+export * from './components/SmartDrawer';
+export * from './components/TargetHighlight';

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './store';
+export * from './hooks/use-chalo';
+export * from './components/SmartDrawer';
+export * from './components/TargetHighlight';

package/dist/types/store.d.ts

@@ -0,0 +1,14 @@
+import { ChaloStore } from './types';
+export declare const useChaloStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<ChaloStore>, "setState" | "persist"> & {
+    setState(partial: ChaloStore | Partial<ChaloStore> | ((state: ChaloStore) => ChaloStore | Partial<ChaloStore>), replace?: false | undefined): unknown;
+    setState(state: ChaloStore | ((state: ChaloStore) => ChaloStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<ChaloStore, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: ChaloStore) => void) => () => void;
+        onFinishHydration: (fn: (state: ChaloStore) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<ChaloStore, unknown, unknown>>;
+    };
+}>;

package/dist/types/types.d.ts

@@ -0,0 +1,174 @@
+import { ReactNode } from 'react';
+export type MissionId = string;
+export type StepId = string;
+export type ActionType = 'click' | 'scroll' | 'fill_field' | 'api_call' | 'wait' | 'conditional' | 'navigate' | 'custom';
+export type ActionStatus = 'pending' | 'running' | 'success' | 'failed' | 'cancelled' | 'skipped';
+export interface RetryConfig {
+    maxAttempts: number;
+    backoff: 'fixed' | 'exponential';
+    delayMs: number;
+}
+export interface RollbackConfig {
+    enabled: boolean;
+}
+export interface ClickActionConfig {
+    /** CSS selector to find the element */
+    selector?: string;
+    /** Named element registered via `registerElement` (preferred over `selector`) */
+    field?: string;
+}
+export interface ScrollActionConfig {
+    selector?: string;
+    behavior?: 'smooth' | 'instant';
+}
+export interface FillFieldActionConfig {
+    field: string;
+    value: unknown;
+}
+export interface ApiCallActionConfig {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+export interface WaitActionConfig {
+    durationMs: number;
+}
+export interface ConditionalActionConfig {
+    condition: SuccessCondition;
+    thenActions?: string[];
+    elseActions?: string[];
+}
+export interface NavigateActionConfig {
+    path: string;
+}
+export interface CustomActionConfig {
+    handlerId: string;
+    params?: Record<string, unknown>;
+}
+export type ActionConfig = ClickActionConfig | ScrollActionConfig | FillFieldActionConfig | ApiCallActionConfig | WaitActionConfig | ConditionalActionConfig | NavigateActionConfig | CustomActionConfig;
+export interface Action {
+    id: string;
+    type: ActionType;
+    config: ActionConfig;
+    label?: string;
+    retry?: RetryConfig;
+    rollback?: RollbackConfig;
+    dependsOn?: string[];
+    condition?: SuccessCondition;
+}
+export interface ActionResult {
+    id: string;
+    status: ActionStatus;
+    data?: unknown;
+    error?: string;
+    attempts: number;
+    startedAt?: number;
+    completedAt?: number;
+}
+export interface ExecutionContext {
+    results: Record<string, ActionResult>;
+    variables: Record<string, unknown>;
+    isRunning: boolean;
+    currentActionId: string | null;
+}
+export type ActionHandler = (config: ActionConfig, context: ExecutionContext) => Promise<unknown>;
+export interface Mission {
+    id: MissionId;
+    title: string;
+    description?: string;
+    steps: Step[];
+    metadata?: Record<string, unknown>;
+    onComplete?: () => void;
+    allowCompletion?: boolean;
+    actions?: Action[];
+}
+export type BubbleType = 'message' | 'input' | 'select' | 'action-group' | 'custom';
+export interface Bubble {
+    id: string;
+    type: BubbleType;
+    content?: string | ReactNode;
+    targetField?: string;
+    options?: Array<{
+        label: string;
+        value: unknown;
+    }>;
+    actions?: StepAction[];
+}
+export interface Step {
+    id: StepId;
+    title: string;
+    content: string | ReactNode;
+    bubbles?: Bubble[];
+    targetField?: string;
+    targetElement?: string;
+    successCondition?: SuccessCondition;
+    waitFor?: SuccessCondition;
+    condition?: SuccessCondition;
+    navigationRules?: {
+        canGoBack?: boolean;
+        canSkip?: boolean;
+    };
+    actions?: StepAction[];
+    actionSequence?: Action[];
+}
+export interface StepAction {
+    label: string;
+    type: 'next' | 'prev' | 'complete' | 'custom' | 'fill_field' | 'input_manual' | 'trigger_action' | 'click';
+    data?: unknown;
+    onClick?: () => void;
+}
+export interface SuccessCondition {
+    type: 'field_value' | 'field_touched' | 'custom';
+    field?: string;
+    value?: unknown;
+    predicate?: (value: unknown, formState: unknown) => boolean;
+}
+export interface ChatInteraction {
+    stepId: string;
+    actionText: string;
+    timestamp: number;
+}
+export interface TourEntry {
+    missionId: MissionId;
+    lastStepId: StepId;
+    completed: boolean;
+    lastAccessed: number;
+}
+export interface ChaloState {
+    activeMissionId: MissionId | null;
+    currentStepId: StepId | null;
+    missionProgress: number;
+    fieldValues: Record<string, unknown>;
+    fieldStates: Record<string, 'idle' | 'focused' | 'valid' | 'invalid'>;
+    missions: Record<string, Mission>;
+    interactionHistory: ChatInteraction[];
+    tourHistory: Record<string, TourEntry>;
+    completedMissions: MissionId[];
+    executionContext: ExecutionContext;
+    isPaused: boolean;
+    isCompleted: boolean;
+    error: string | null;
+}
+export interface ChaloStore extends ChaloState {
+    registerMission: (mission: Mission) => void;
+    startMission: (missionId: MissionId) => void;
+    pauseMission: () => void;
+    resumeMission: () => void;
+    completeMission: () => void;
+    goToStep: (stepId: StepId) => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    updateField: (name: string, value: unknown, status?: ChaloState['fieldStates'][string]) => void;
+    addInteraction: (stepId: string, actionText: string) => void;
+    recordTourEntry: (missionId: MissionId, stepId: StepId, completed: boolean) => void;
+    markMissionCompleted: (missionId: MissionId) => void;
+    registerActionHandler: (type: ActionType, handler: ActionHandler) => void;
+    executeAction: (action: Action) => Promise<ActionResult>;
+    executeActionSequence: (actions: Action[], stepId?: string) => Promise<Record<string, ActionResult>>;
+    cancelExecution: () => void;
+    dismissAllTours: () => void;
+    resetMission: () => void;
+    reset: () => void;
+    setError: (error: string | null) => void;
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@osiloke/chalo",
+  "version": "0.1.0",
+  "description": "A modern React component library for intelligent UI interactions and guided experiences",
+  "type": "module",
+  "private": false,
+  "main": "./dist/chalo.cjs",
+  "module": "./dist/chalo.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.mts",
+        "default": "./dist/chalo.mjs"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/chalo.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "react",
+    "component-library",
+    "ui",
+    "zustand",
+    "framer-motion",
+    "guided-experience"
+  ],
+  "author": "Osiloke Harold Emoekpere",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/osiloke/chalo.git",
+    "directory": "packages/chalo"
+  },
+  "peerDependencies": {
+    "framer-motion": ">=12.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "zustand": ">=5.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:types && vite build && npm run copy:types",
+    "build:types": "tsc --project tsconfig.json",
+    "copy:types": "cp dist/types/index.d.ts dist/types/index.d.mts",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --ext ts,tsx --fix",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "coverage": "vitest run --coverage",
+    "prepublishOnly": "vitest run --passWithNoTests && npm run build"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^15.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^6.14.0",
+    "@typescript-eslint/parser": "^6.14.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^1.6.0",
+    "@vitest/ui": "^1.6.0",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "framer-motion": "^12.38.0",
+    "jsdom": "^29.0.1",
+    "prettier": "^3.2.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^1.6.0",
+    "zustand": "^5.0.12"
+  }
+}