pupt-react 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pupt-react contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,275 @@
 # pupt-react
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+A headless React component library for integrating [pupt-lib](https://github.com/apowers313/pupt-lib) into web applications. Provides hooks and render-prop components for prompt transformation, rendering, and user input collection.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Features
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+- **Headless Components**: Full UI flexibility with render-prop patterns
+- **React Hooks**: Access pupt-lib functionality with idiomatic React APIs
+- **Ask System Integration**: Collect and validate user inputs with type-safe forms
+- **Search Support**: Built-in prompt search functionality
+- **Post-Actions**: Handle post-execution actions from prompts
+- **TypeScript**: Full type definitions included
 
-## Purpose
+## Installation
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `pupt-react`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```bash
+npm install pupt-react pupt-lib react react-dom
+```
 
-## What is OIDC Trusted Publishing?
+## Quick Start
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+### Basic Setup
 
-## Setup Instructions
+Wrap your application with `PuptProvider` to enable pupt-lib integration:
 
-To properly configure OIDC trusted publishing for this package:
+```tsx
+import { PuptProvider, PromptRenderer } from "pupt-react";
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+function App() {
+  return (
+    <PuptProvider>
+      <MyPromptComponent />
+    </PuptProvider>
+  );
+}
+```
 
-## DO NOT USE THIS PACKAGE
+### Rendering a Prompt
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+Use `PromptRenderer` with the render-prop pattern for full control over rendering:
 
-## More Information
+```tsx
+import { PromptRenderer } from "pupt-react";
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+function MyPromptComponent() {
+  const source = `<Prompt name="greeting">
+  <Task>Say hello to the user.</Task>
+</Prompt>`;
 
----
+  return (
+    <PromptRenderer source={source} autoRender>
+      {({ output, error, isRendering, copyToClipboard }) => (
+        <div>
+          {isRendering ? (
+            <p>Rendering...</p>
+          ) : error ? (
+            <p>Error: {error.message}</p>
+          ) : (
+            <>
+              <pre>{output}</pre>
+              <button onClick={copyToClipboard}>Copy</button>
+            </>
+          )}
+        </div>
+      )}
+    </PromptRenderer>
+  );
+}
+```
 
-**Maintained for OIDC setup purposes only**
+### Using Hooks Directly
+
+For more control, use the hooks directly:
+
+```tsx
+import { usePupt, usePromptRender } from "pupt-react";
+
+function MyComponent() {
+  const { transformer, registry } = usePupt();
+  const { output, render, isRendering, error } = usePromptRender({
+    source: { type: "source", value: "<Prompt><Task>Hello</Task></Prompt>" },
+    autoRender: true,
+  });
+
+  return <div>{output}</div>;
+}
+```
+
+## Components
+
+### PuptProvider
+
+Context provider that initializes pupt-lib and provides configuration to child components.
+
+```tsx
+<PuptProvider
+  registry={customRegistry}  // Optional custom ComponentRegistry
+  searchEngine={searchEngine} // Optional SearchEngine instance
+>
+  {children}
+</PuptProvider>
+```
+
+### PromptRenderer
+
+Headless component for transforming and rendering prompts.
+
+```tsx
+<PromptRenderer
+  source={source}           // Prompt source string
+  inputs={inputsMap}        // Map of user input values
+  autoRender={true}         // Auto-render when source changes
+>
+  {(props) => (
+    // props: output, error, isRendering, pendingInputs, copyToClipboard, isCopied
+  )}
+</PromptRenderer>
+```
+
+### PromptEditor
+
+Headless component for editing prompt source with transformation preview.
+
+```tsx
+<PromptEditor
+  defaultValue={source}
+  onChange={handleChange}
+  debounce={300}
+>
+  {({ inputProps, value, error, isTransforming }) => (
+    <textarea {...inputProps} />
+  )}
+</PromptEditor>
+```
+
+### AskHandler
+
+Headless component for handling Ask input requirements.
+
+```tsx
+<AskHandler
+  element={element}
+  onComplete={(inputs) => console.log(inputs)}
+>
+  {({ requirements, current, progress, getInputProps, next, previous }) => (
+    // Render your custom form UI
+  )}
+</AskHandler>
+```
+
+## Hooks
+
+### usePupt
+
+Access the PuptProvider context:
+
+```tsx
+const { transformer, registry, searchEngine, isLoading, error } = usePupt();
+```
+
+### usePromptRender
+
+Transform and render prompts:
+
+```tsx
+const {
+  source,
+  setSource,
+  element,
+  output,
+  error,
+  isTransforming,
+  isRendering,
+  inputRequirements,
+  render,
+  transform,
+} = usePromptRender({
+  source: { type: "source", value: promptString },
+  inputs: inputsMap,
+  autoRender: true,
+});
+```
+
+### useAskIterator
+
+Iterate through Ask inputs and collect validated responses:
+
+```tsx
+const {
+  current,
+  currentIndex,
+  totalInputs,
+  inputs,
+  isDone,
+  submit,
+  next,
+  previous,
+  reset,
+  getValue,
+  setValue,
+} = useAskIterator({
+  element,
+  onComplete: (inputs) => console.log("All inputs collected", inputs),
+});
+```
+
+### usePromptSearch
+
+Search through available prompts:
+
+```tsx
+const { query, setQuery, results, isSearching, clear } = usePromptSearch({
+  debounce: 300,
+  limit: 10,
+});
+```
+
+### usePostActions
+
+Handle post-execution actions:
+
+```tsx
+const { pendingActions, executedActions, execute, executeAll, dismiss } =
+  usePostActions({
+    actions,
+    handlers: {
+      openUrl: (url) => window.open(url),
+    },
+  });
+```
+
+## Demo
+
+A demo website showcasing pupt-react capabilities is included. To run locally:
+
+```bash
+npm run dev:demo
+```
+
+Or build for production:
+
+```bash
+npm run build:demo
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint code
+npm run lint
+
+# Build library
+npm run build
+
+# Build demo
+npm run build:demo
+```
+
+## Requirements
+
+- React 18.0.0 or later
+- pupt-lib (peer dependency)
+
+## License
+
+MIT