@lantos1618/better-ui 0.2.2 → 0.3.1

package/dist/index.mjs

@@ -0,0 +1,491 @@
+// src/tool.tsx
+import { memo } from "react";
+import { jsx } from "react/jsx-runtime";
+var Tool = class {
+  constructor(config) {
+    this.name = config.name;
+    this.description = config.description;
+    this.inputSchema = config.input;
+    this.outputSchema = config.output;
+    this.tags = config.tags || [];
+    this.cacheConfig = config.cache;
+    this.clientFetchConfig = config.clientFetch;
+    this._initView();
+  }
+  /**
+   * Define server-side implementation
+   * Runs on server (API routes, server components, etc.)
+   */
+  server(handler) {
+    this._server = handler;
+    return this;
+  }
+  /**
+   * Define client-side implementation
+   * Runs in browser. If not specified, auto-fetches to /api/tools/{name}
+   */
+  client(handler) {
+    this._client = handler;
+    return this;
+  }
+  /**
+   * Define view component for rendering results
+   * Our differentiator from TanStack AI
+   */
+  view(component) {
+    this._view = component;
+    this._initView();
+    return this;
+  }
+  /**
+   * Execute the tool
+   * Automatically uses server or client handler based on environment
+   *
+   * SECURITY: Server handlers only run on server. Client automatically
+   * fetches from /api/tools/execute if no client handler is defined.
+   */
+  async run(input, ctx) {
+    const validated = this.inputSchema.parse(input);
+    const isServer = ctx?.isServer ?? typeof window === "undefined";
+    const context = {
+      cache: ctx?.cache || /* @__PURE__ */ new Map(),
+      fetch: ctx?.fetch || globalThis.fetch?.bind(globalThis),
+      isServer,
+      // Only include server-sensitive fields when actually on server
+      ...isServer ? {
+        env: ctx?.env,
+        headers: ctx?.headers,
+        cookies: ctx?.cookies,
+        user: ctx?.user,
+        session: ctx?.session
+      } : {
+        // Client-only fields
+        optimistic: ctx?.optimistic
+      }
+    };
+    if (this.cacheConfig && context.cache) {
+      const cacheKey = this.cacheConfig.key ? this.cacheConfig.key(validated) : `${this.name}:${JSON.stringify(validated)}`;
+      const cached = context.cache.get(cacheKey);
+      if (cached && cached.expiry > Date.now()) {
+        return cached.data;
+      }
+    }
+    let result;
+    if (context.isServer) {
+      if (!this._server) {
+        throw new Error(`Tool "${this.name}" has no server implementation`);
+      }
+      result = await this._server(validated, context);
+    } else {
+      if (this._client) {
+        result = await this._client(validated, context);
+      } else if (this._server) {
+        result = await this._defaultClientFetch(validated, context);
+      } else {
+        throw new Error(`Tool "${this.name}" has no implementation`);
+      }
+    }
+    if (this.outputSchema) {
+      try {
+        result = this.outputSchema.parse(result);
+      } catch (error) {
+        console.error(`Output validation failed for tool "${this.name}":`, error);
+        if (error instanceof Error && "errors" in error) {
+          console.error("Validation errors:", error.errors);
+        }
+        throw error;
+      }
+    }
+    if (this.cacheConfig && context.cache) {
+      const cacheKey = this.cacheConfig.key ? this.cacheConfig.key(validated) : `${this.name}:${JSON.stringify(validated)}`;
+      context.cache.set(cacheKey, {
+        data: result,
+        expiry: Date.now() + this.cacheConfig.ttl
+      });
+    }
+    return result;
+  }
+  /**
+   * Make the tool callable directly: await weather({ city: 'London' })
+   */
+  async call(input, ctx) {
+    return this.run(input, ctx);
+  }
+  /**
+   * Default client fetch when no .client() is defined
+   *
+   * SECURITY: This ensures server handlers never run on the client.
+   * The server-side /api/tools/execute endpoint handles execution safely.
+   */
+  async _defaultClientFetch(input, ctx) {
+    const endpoint = this.clientFetchConfig?.endpoint || "/api/tools/execute";
+    const response = await ctx.fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ tool: this.name, input })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.message || error.error || `Tool execution failed: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.result ?? data.data ?? data;
+  }
+  _initView() {
+    const viewFn = this._view;
+    const name = this.name;
+    const ViewComponent = (props) => {
+      if (!viewFn) {
+        if (props.loading) return null;
+        if (props.error) return null;
+        if (!props.data) return null;
+        return /* @__PURE__ */ jsx("pre", { children: JSON.stringify(props.data, null, 2) });
+      }
+      if (!props.data && !props.loading && !props.error) {
+        return null;
+      }
+      return viewFn(props.data, {
+        loading: props.loading,
+        error: props.error,
+        onAction: props.onAction
+      });
+    };
+    ViewComponent.displayName = `${name}View`;
+    this.View = memo(ViewComponent, (prevProps, nextProps) => {
+      if (prevProps.data !== nextProps.data) return false;
+      if (prevProps.loading !== nextProps.loading) return false;
+      if (prevProps.error !== nextProps.error) return false;
+      return true;
+    });
+  }
+  /**
+   * Check if tool has a view
+   */
+  get hasView() {
+    return !!this._view;
+  }
+  /**
+   * Check if tool has server implementation
+   */
+  get hasServer() {
+    return !!this._server;
+  }
+  /**
+   * Check if tool has custom client implementation
+   */
+  get hasClient() {
+    return !!this._client;
+  }
+  /**
+   * Convert to plain object (for serialization)
+   *
+   * SECURITY: This intentionally excludes handlers and schemas to prevent
+   * accidental exposure of server logic or validation details.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      description: this.description,
+      tags: this.tags,
+      hasServer: this.hasServer,
+      hasClient: this.hasClient,
+      hasView: this.hasView,
+      hasCache: !!this.cacheConfig
+      // Intentionally NOT included: handlers, schemas, clientFetchConfig
+    };
+  }
+  /**
+   * Convert to AI SDK format (Vercel AI SDK v5 compatible)
+   */
+  toAITool() {
+    return {
+      description: this.description || this.name,
+      inputSchema: this.inputSchema,
+      execute: async (input) => {
+        return this.run(input, { isServer: true });
+      }
+    };
+  }
+};
+function tool(nameOrConfig) {
+  if (typeof nameOrConfig === "string") {
+    return new ToolBuilder(nameOrConfig);
+  }
+  return new Tool(nameOrConfig);
+}
+var ToolBuilder = class {
+  constructor(name) {
+    this._tags = [];
+    this._name = name;
+  }
+  description(desc) {
+    this._description = desc;
+    return this;
+  }
+  /**
+   * Define input schema - enables type inference for handlers
+   *
+   * NOTE: Uses type assertion internally. This is safe because:
+   * 1. The schema is stored and used correctly at runtime
+   * 2. The return type correctly reflects the new generic parameter
+   * 3. TypeScript doesn't support "this type mutation" in fluent builders
+   */
+  input(schema) {
+    this._input = schema;
+    return this;
+  }
+  /**
+   * Define output schema - enables type inference for results
+   */
+  output(schema) {
+    this._output = schema;
+    return this;
+  }
+  tags(...tags) {
+    this._tags.push(...tags);
+    return this;
+  }
+  cache(config) {
+    this._cache = config;
+    return this;
+  }
+  /** Configure auto-fetch endpoint for client-side execution */
+  clientFetch(config) {
+    this._clientFetch = config;
+    return this;
+  }
+  server(handler) {
+    this._serverHandler = handler;
+    return this;
+  }
+  client(handler) {
+    this._clientHandler = handler;
+    return this;
+  }
+  view(component) {
+    this._viewComponent = component;
+    return this;
+  }
+  /**
+   * Build the final Tool instance
+   */
+  build() {
+    if (!this._input) {
+      throw new Error(`Tool "${this._name}" requires an input schema`);
+    }
+    const t = new Tool({
+      name: this._name,
+      description: this._description,
+      input: this._input,
+      output: this._output,
+      tags: this._tags,
+      cache: this._cache,
+      clientFetch: this._clientFetch
+    });
+    if (this._serverHandler) t.server(this._serverHandler);
+    if (this._clientHandler) t.client(this._clientHandler);
+    if (this._viewComponent) t.view(this._viewComponent);
+    return t;
+  }
+  /**
+   * Auto-build when accessing Tool methods
+   */
+  async run(input, ctx) {
+    return this.build().run(input, ctx);
+  }
+  get View() {
+    return this.build().View;
+  }
+  toJSON() {
+    return this.build().toJSON();
+  }
+  toAITool() {
+    return this.build().toAITool();
+  }
+};
+
+// src/react/useTool.ts
+import { useState, useCallback, useEffect, useRef } from "react";
+function useTool(tool2, initialInput, options = {}) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [executed, setExecuted] = useState(false);
+  const inputRef = useRef(initialInput);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const executionIdRef = useRef(0);
+  const pendingCountRef = useRef(0);
+  const execute = useCallback(
+    async (input) => {
+      const finalInput = input ?? inputRef.current;
+      if (finalInput === void 0) {
+        const err = new Error("No input provided to tool");
+        setError(err);
+        optionsRef.current.onError?.(err);
+        return null;
+      }
+      const currentExecutionId = ++executionIdRef.current;
+      pendingCountRef.current++;
+      setLoading(true);
+      setError(null);
+      try {
+        const context = {
+          cache: /* @__PURE__ */ new Map(),
+          fetch: globalThis.fetch?.bind(globalThis),
+          isServer: false,
+          ...optionsRef.current.context
+        };
+        const result = await tool2.run(finalInput, context);
+        if (currentExecutionId === executionIdRef.current) {
+          setData(result);
+          setExecuted(true);
+          optionsRef.current.onSuccess?.(result);
+        }
+        return result;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        if (currentExecutionId === executionIdRef.current) {
+          setError(error2);
+          optionsRef.current.onError?.(error2);
+        }
+        return null;
+      } finally {
+        pendingCountRef.current--;
+        if (pendingCountRef.current === 0) {
+          setLoading(false);
+        }
+      }
+    },
+    [tool2]
+  );
+  const reset = useCallback(() => {
+    setData(null);
+    setError(null);
+    setLoading(false);
+    setExecuted(false);
+  }, []);
+  useEffect(() => {
+    if (options.auto && initialInput !== void 0) {
+      inputRef.current = initialInput;
+      execute(initialInput);
+    }
+  }, [options.auto, initialInput, execute]);
+  return {
+    data,
+    loading,
+    error,
+    execute,
+    reset,
+    executed
+  };
+}
+function useTools(tools, options = {}) {
+  const toolsRef = useRef(tools);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  if (process.env.NODE_ENV !== "production") {
+    const prevKeys = Object.keys(toolsRef.current);
+    const currKeys = Object.keys(tools);
+    if (prevKeys.length !== currKeys.length || !currKeys.every((k) => prevKeys.includes(k))) {
+      console.warn(
+        "useTools: The tools object keys changed between renders. This may cause unexpected behavior. Define tools outside the component or memoize with useMemo."
+      );
+    }
+    toolsRef.current = tools;
+  }
+  const [state, setState] = useState(() => {
+    const initial = {};
+    for (const name of Object.keys(tools)) {
+      initial[name] = {
+        data: null,
+        loading: false,
+        error: null,
+        executed: false
+      };
+    }
+    return initial;
+  });
+  const createExecute = useCallback(
+    (toolName, tool2) => {
+      return async (input) => {
+        if (input === void 0) {
+          const err = new Error("No input provided to tool");
+          setState((prev) => ({
+            ...prev,
+            [toolName]: { ...prev[toolName], error: err }
+          }));
+          optionsRef.current.onError?.(err);
+          return null;
+        }
+        setState((prev) => ({
+          ...prev,
+          [toolName]: { ...prev[toolName], loading: true, error: null }
+        }));
+        try {
+          const context = {
+            cache: /* @__PURE__ */ new Map(),
+            fetch: globalThis.fetch?.bind(globalThis),
+            isServer: false,
+            ...optionsRef.current.context
+          };
+          const result = await tool2.run(input, context);
+          setState((prev) => ({
+            ...prev,
+            [toolName]: {
+              data: result,
+              loading: false,
+              error: null,
+              executed: true
+            }
+          }));
+          optionsRef.current.onSuccess?.(result);
+          return result;
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState((prev) => ({
+            ...prev,
+            [toolName]: { ...prev[toolName], loading: false, error }
+          }));
+          optionsRef.current.onError?.(error);
+          return null;
+        }
+      };
+    },
+    []
+  );
+  const createReset = useCallback((toolName) => {
+    return () => {
+      setState((prev) => ({
+        ...prev,
+        [toolName]: {
+          data: null,
+          loading: false,
+          error: null,
+          executed: false
+        }
+      }));
+    };
+  }, []);
+  const results = {};
+  for (const [name, tool2] of Object.entries(tools)) {
+    const toolName = name;
+    const toolState = state[toolName];
+    results[toolName] = {
+      data: toolState?.data ?? null,
+      loading: toolState?.loading ?? false,
+      error: toolState?.error ?? null,
+      executed: toolState?.executed ?? false,
+      execute: createExecute(toolName, tool2),
+      reset: createReset(toolName)
+    };
+  }
+  return results;
+}
+export {
+  Tool,
+  ToolBuilder,
+  tool,
+  useTool,
+  useTools
+};

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@lantos1618/better-ui",
-  "version": "0.2.2",
-  "description": "A modern UI framework for building AI-powered applications",
-  "main": "lib/aui/index.ts",
-  "types": "lib/aui/index.ts",
+  "version": "0.3.1",
+  "description": "A minimal, type-safe AI-first UI framework for building tools",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
   "files": [
-    "lib/**/*",
+    "dist",
     "README.md",
     "LICENSE"
   ],
@@ -14,39 +22,70 @@
     "framework",
     "ai",
     "react",
-    "nextjs"
+    "tools",
+    "typescript"
   ],
   "author": "Lyndon Leong",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lantos1618/better-ui"
+  },
   "scripts": {
     "dev": "next dev",
-    "build": "next build",
+    "build": "npm run build:lib && npm run build:next",
+    "build:lib": "tsup src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.lib.json",
+    "build:next": "next build",
     "start": "next start",
     "lint": "eslint .",
     "test": "jest",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build:lib"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^2.0.20",
-    "@sendgrid/mail": "^8.1.5",
-    "ai": "^5.0.23",
-    "magicpath-ai": "^1.1.2",
-    "next": "^15.5.0",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
-    "zod": "^3.22.0"
+    "@ai-sdk/openai": "^2.0.77",
+    "@ai-sdk/react": "^2.0.107",
+    "ai": "^5.0.107",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
     "@eslint/eslintrc": "^3.3.1",
     "@jest/globals": "^29.7.0",
+    "@tailwindcss/postcss": "^4.1.17",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^20",
-    "@types/react": "^18",
-    "@types/react-dom": "^18",
-    "eslint": "^8",
-    "eslint-config-next": "14.2.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "autoprefixer": "^10.4.22",
+    "eslint": "^9",
+    "eslint-config-next": "^16.0.1",
+    "framer-motion": "^12.23.12",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "lucide-react": "^0.543.0",
+    "next": "^16.0.1",
+    "postcss": "^8.5.6",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "tailwindcss": "^4.1.17",
     "ts-jest": "^29.4.1",
+    "tsup": "^8.5.1",
     "typescript": "^5"
   }
 }