diff --git a/README.md b/README.md index dcbfce0..68be917 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,186 @@ -# @operatoruplift/ui +
-> **v0.1.0** — Shared UI component library for all Operator Uplift applications. +@operatoruplift/ui, marked Superseded. React, Tailwind, Storybook. A component kit for agent apps. 49 React components, 17 hooks and one set of design tokens, written in April 2026 for Operator Uplift's AI-assistant platform. 49 components, 17 hooks, 168 stories, 119 tests pass. npm run storybook. Beside it, the local Storybook at localhost:6006 shows the Agent group and the AgentCard grid story. -47 components, 13 hooks, Storybook documentation, and a full design token system — published as a single npm package. +

-## Used By +Run the Storybook   +See all 49 components   +Operator Uplift today -| App | Environment | -|-----|-------------| -| **Website** (`operatoruplift/website`) | Next.js (SSR) | -| **Developer Console** (`operatoruplift/developer-console`) | Next.js (SSR) | -| **Desktop App** (`operatoruplift/desktop`) — webview | Tauri (CSR) | +

+ +Status: superseded +49 components +React 18 or 19 +Tailwind CSS 3.4 +Storybook 8.6 +npm: not published +License: MIT + +

React components for agent apps, from Operator Uplift's AI-assistant era.

+ +Build  →  Pack  →  Install  →  Import  →  Compose + +
+ +How it works  ·  +Status  ·  +Where it fit  ·  +Run it locally  ·  +Components + +
+ +
+ + + + Four Storybook stories. 01, show the agent's work: ConversationThread mixes chat bubbles with tool call rows for file_read and file_edit, each with its timing and a success check. 02, show what it remembers: MemoryPanel searches and filters memories by type (user, feedback, project, reference); pass it entries from the useMemory hook or your own store. 03, move from the keyboard: CommandPalette groups commands under Navigation and Actions, filters as you type and moves with the arrow keys. 04, watch every agent: Table lists agents with running, idle and error badges, their model and API calls, and pages through rows. + + +

Captured from a local Storybook build on 30 October 2026.

+ +**`@operatoruplift/ui` is the React component library written in April 2026 for Operator Uplift's AI agent apps.** It packs 49 components, from buttons and tables to agent cards, tool call rows and a memory panel, plus 17 hooks and one set of dark, orange design tokens, into a single package with a Tailwind preset and a Storybook. It was meant to be shared by the website, the developer console and the desktop shell, but it was never published to npm and none of them imported it. Operator Uplift pivoted to commitment infrastructure on 22 May 2026, so this repo is a record of that earlier platform. It still builds, type-checks, tests and renders. + +The repo started in December 2025 as an Electron desktop assistant (`aven-assistant`, renamed Uplift Assistant in January 2026), begun by Dhruv Aggarwal. The library replaced it in [pull request 1](https://github.com/operatoruplift/UI/pull/1) on 1 April 2026, and the old app's source is still in `src/`. + +
+ +## How it works + + + + Library, Package and Your app. Library, the source: 49 components and 17 hooks in TypeScript, colors and radii kept in CSS variables, a story for every component. Package, the build: ESM and CJS bundles with type declarations, styles.css compiled by Tailwind, a Tailwind preset with the same tokens. Your app consumes it: import styles.css once, add the preset to your Tailwind config, import components by name. Library to Package: vite build and tailwindcss. Package to Your app: npm pack, then npm install. + + + + + + + + +
Tokens live in CSS variables
Colors and radii are --ou-* variables in src/styles/globals.css. The compiled styles.css, the Tailwind preset and the exported designTokens object carry the same values, so an app can retheme by overriding variables.
Ready for server rendering
40 of the 49 components start with the "use client" directive for the Next.js App Router. A packed build renders through react-dom/server and imports from both ESM and CommonJS.
No keys, no network
The library reads no environment variables and makes no network requests. The memory hooks store through an adapter you pass in, and a localStorage adapter ships with them.
+ +

React 18 and 19 · TypeScript 5 · Tailwind CSS 3.4 · class-variance-authority · tailwind-merge · lucide-react · Vite 6 library mode · vite-plugin-dts · Storybook 8.6 · Vitest 2 · Testing Library · happy-dom

+ +
+ +## Status + + + + + + + + + + + + +
SupersededThe component library, version 0.1.0. On 30 October 2026 it installed, type-checked, passed 119 of 119 Vitest tests, built its package and built a Storybook of 168 stories. It was never published to npm, and the apps it was written for never imported it. The current product is Operator Uplift: one small daily action, proved with a photo, and an AI Game Master decides whether the day counts.operatoruplift.com
ArchivedThe Uplift Assistant Electron app in src/ (December 2025 to January 2026): Supabase sign-in, chat, voice chat, an agent store and a workspace for installed agents. Its dependencies and build scripts left package.json in April 2026, so it no longer builds from this repo.Pull request 1
+ +
+ +## Where it fit + +Operator Uplift was first pitched as AI for your inbox and calendar, built across several repos. This one held the shared interface. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RepoRole in the AI-assistant platform
UI (this repo)Shared React components and design tokens. Before April 2026, the Uplift Assistant desktop app.
webviewThe Tauri desktop shell and an Android WebView shell, both loading operatoruplift.com.
developer_console (private)A Vite and React console for agent builders: prompt playground, debugger, logs, memory and MCP pages.
core (private)The agent runtime that the console and the desktop shell were meant to reach on localhost:3001.
calendar_agent, x402-agent, project_space (private)Google Calendar tools, x402 agent payments on Solana, and an internal project tracker.
uplift-ai-chatbotA deployment of Vercel's Chat SDK template.
+ +
+ +## Run it locally + + + + + + + +
Prerequisites
Node 22 and npm. Checked with Node 22.22.0 and npm 10.9.4 on 30 October 2026.
Read first
CONTRIBUTING.md: how to add a component with its story and test, and the token, border and radius conventions.
What the checks prove
119 Vitest tests in 26 files render components in happy-dom and check variants and states; 12 of the files also simulate clicks or typing. tsc covers the library. Nothing here runs a real Next.js or Tauri app.
+ +### 1. Browse the components -## Installation +```bash +npm ci +npm run storybook # Storybook at http://localhost:6006 (npm run dev does the same) +``` + +### 2. Check and build ```bash -npm install @operatoruplift/ui +npm run lint # tsc over the library +npm test # 119 Vitest tests in 26 files +npm run build # dist/: ESM and CJS bundles, type declarations and styles.css +npm run build-storybook # a static Storybook in storybook-static/ ``` -## Setup +### 3. Use it in an app + +The package is not on npm, so build it and install the tarball: + +```bash +npm run build && npm pack # writes operatoruplift-ui-0.1.0.tgz +cd ../your-app +npm install path/to/UI/operatoruplift-ui-0.1.0.tgz +``` -### 1. Import the stylesheet +Import the stylesheet once, at the root of your app: ```tsx import "@operatoruplift/ui/styles.css"; ``` -### 2. Extend your Tailwind config +Add the preset to a Tailwind CSS 3 config, so your own classes use the same tokens: ```ts // tailwind.config.ts +import type { Config } from "tailwindcss"; import { upliftPreset } from "@operatoruplift/ui/tailwind-preset"; export default { presets: [upliftPreset], - content: [ - "./src/**/*.{ts,tsx}", - "./node_modules/@operatoruplift/ui/dist/**/*.js", - ], -}; + content: ["./src/**/*.{ts,tsx}", "./node_modules/@operatoruplift/ui/dist/**/*.js"], +} satisfies Config; ``` -## Usage +Then compose: ```tsx import { Button, Badge, Card, CardContent } from "@operatoruplift/ui"; -function App() { +export function App() { return ( @@ -60,123 +194,40 @@ function App() { } ``` -## Components +
+The memory system +
-### Primitives - -| Component | Description | -|-----------|-------------| -| `Button` | Primary, outline, ghost, danger variants with loading & icon support | -| `Badge` | Status labels: default, primary, success, warning, danger | -| `Card` | Container: default, glass, glass-dark variants with header/content/footer | -| `Input` | Text, password (show/hide), search with icon & error state | -| `Textarea` | Auto-resizing textarea with label and error state | -| `Toggle` | Animated on/off switch | -| `Select` | Dropdown with search and multi-select | -| `Tooltip` | Hover tooltips with arrow positioning | -| `Toast` | Auto-dismiss notifications: success, error, warning, info | -| `Alert` | Inline alert banners: info, success, warning, error with dismiss | -| `Avatar` | User/agent avatars with image, fallback initials, and status dot | -| `AvatarGroup` | Stacked avatar group with overflow count | -| `Dropdown` | Generic dropdown menu with items, dividers, danger items | -| `Tabs` | Tabbed navigation: default, pills, underline variants | -| `Breadcrumb` | Navigation breadcrumbs with custom separator | -| `Kbd` / `Shortcut` | Keyboard shortcut display | -| `Divider` | Horizontal/vertical dividers with optional label | -| `LoadingSpinner` | Spinner with label, optional fullscreen overlay | -| `CopyButton` | Copy-to-clipboard button with confirmation | - -### Layout - -| Component | Description | -|-----------|-------------| -| `Sidebar` | Collapsible nav with sections and icons | -| `Header` | Logo, nav links, user menu | -| `PageWrapper` | Standard page layout with max-width | -| `Modal` | Centered overlay with backdrop blur, close on Escape | -| `CommandPalette` | Cmd+K command palette with search, groups, keyboard navigation | - -### Data Display - -| Component | Description | -|-----------|-------------| -| `Table` | Sortable columns, pagination, row selection | -| `StatCard` | Value + label + change indicator | -| `ProgressBar` | Determinate and indeterminate | -| `Skeleton` | Loading placeholders (text, circular, rectangular) | -| `EmptyState` | Icon + message + action button | -| `CodeBlock` | Code display with filename, line numbers, copy button | -| `StatusDot` | Animated status indicator (online, offline, running, error, etc.) | -| `TokenCounter` | Token usage display with breakdown and progress bar | -| `CostDisplay` | Cost/spend display with change indicator | -| `StreamingText` | Animated text streaming with cursor | - -### Agent-Specific - -| Component | Description | -|-----------|-------------| -| `AgentCard` | Avatar, name, status dot, model badge, install button | -| `RiskBadge` | A/B/C/D/F grade with color coding | -| `SessionIndicator` | Active session count with animated dot | -| `PermissionChip` | Icon + label for permission types | -| `ModelSelector` | Provider-aware model dropdown | -| `ChatBubble` | User/assistant message bubbles with copy button | -| `ToolCallCard` | Expandable tool call display with status and I/O | -| `ConversationThread` | Mixed message + tool call conversation thread | -| `MemoryCard` | Expandable memory entry with on-demand content fetch | -| `MemoryPanel` | Full memory management panel with search, filter, CRUD | - -### Effects - -| Component | Description | -|-----------|-------------| -| `SpotlightCard` | Mouse-following gradient highlight | -| `GlowButton` | Animated glow on hover | -| `FadeIn` | Intersection observer fade-in animation | -| `DotGlobe` | Animated rotating dot grid globe | - -### Providers - -| Component | Description | -|-----------|-------------| -| `ThemeProvider` | Dark/light/system theme with persistence | -| `ToastProvider` | Toast notification context | - -## Hooks - -| Hook | Description | -|------|-------------| -| `useLocalStorage` | Persistent state synced across tabs | -| `useMediaQuery` | Responsive breakpoint detection | -| `useIsMobile` / `useIsTablet` / `useIsDesktop` | Convenience breakpoint hooks | -| `useDebounce` / `useDebouncedCallback` | Debounced values and callbacks | -| `useClipboard` | Copy to clipboard with auto-reset | -| `useKeyboard` / `useHotkey` | Keyboard shortcut handling | -| `useOnClickOutside` | Click outside detection | -| `useStreamingText` | Animated text streaming for AI responses | -| `useCostTracker` | Token/cost tracking for AI sessions | -| `useMemory` | 3-layer memory system (index/topic/search) | -| `useMemoryConsolidation` | Memory dedup, pruning, and merging | -| `useTheme` | Theme accessor from ThemeProvider | -| `useToast` | Toast notification accessor from ToastProvider | - -## Memory System - -The library includes a structured memory system for agentic applications: +`useMemory` keeps agent memories in three layers: an index that is always loaded (pointers only, capped at 200 entries), topic files fetched on demand, and a search across topics. It writes the topic first and the index second, so the index never points at a missing topic. `useMemoryConsolidation` merges, prunes and removes duplicates. ```tsx -import { useMemory, createLocalStorageAdapter } from "@operatoruplift/ui"; +import { MemoryPanel, createLocalStorageAdapter, useMemory } from "@operatoruplift/ui"; const adapter = createLocalStorageAdapter("my-app"); -const { entries, addMemory, searchMemories } = useMemory({ adapter }); + +export function Memories() { + const { index, save, search, remove, count, atCapacity } = useMemory({ adapter }); + + async function remember() { + await save({ name: "Prefers short replies", description: "Keep answers brief", type: "feedback", content: "Skip recaps." }); + const results = await search("replies"); // each result has the entry, a 0 to 1 score and a snippet + console.log(results.map((r) => r.entry.name)); + } + + return ; +} ``` -**3-layer architecture**: Index (always loaded, pointers only) -> Topics (on-demand) -> Search (grep-style) +Memory types are `user`, `feedback`, `project` and `reference`. Any storage works if it implements `MemoryStorageAdapter`. + +
-## Design Tokens +
+Design tokens +
-| Token | Value | CSS Variable | -|-------|-------|-------------| +| Token | Value | CSS variable | +|---|---|---| | Primary (Operator Orange) | `#E77630` | `--ou-primary` | | Secondary (Amber) | `#F59E0B` | `--ou-secondary` | | Background (Void) | `#050508` | `--ou-background` | @@ -185,47 +236,156 @@ const { entries, addMemory, searchMemories } = useMemory({ adapter }); | Muted text | `#9ca3af` | `--ou-muted-foreground` | | Border | `rgba(255,255,255,0.05)` | `--ou-border` | | Destructive | `#ef4444` | `--ou-destructive` | +| Radius | `0.25rem`, `0.375rem`, `0.5rem`, `0.75rem` | `--ou-radius-sm`, `-md`, `-lg`, `-xl` | -Access tokens programmatically: +Read them in code with `designTokens`, which also carries success `#22c55e`, warning `#f59e0b` and info `#3b82f6`: ```ts import { designTokens } from "@operatoruplift/ui"; console.log(designTokens.primary); // "#E77630" ``` -## Storybook +Known limit: the token colors are plain `var()` values, so Tailwind cannot apply opacity modifiers to them. Classes such as `bg-primary/20` (26 uses in the components) generate no CSS. -```bash -npm run dev -# or -npm run storybook -``` +
-Open http://localhost:6006 to browse all components with interactive controls. +
+Hooks +
-## Development +| Hook | Use | +|---|---| +| `useLocalStorage` | State persisted to `localStorage` and synced across tabs | +| `useMediaQuery`, `useIsMobile`, `useIsTablet`, `useIsDesktop` | Responsive breakpoints | +| `useDebounce`, `useDebouncedCallback` | Debounced values and callbacks | +| `useClipboard` | Copy to the clipboard with an auto-reset flag | +| `useKeyboard`, `useHotkey` | Keyboard shortcuts | +| `useOnClickOutside` | Clicks outside an element | +| `useStreamingText` | Text revealed as it streams, for AI responses | +| `useCostTracker` | Token and cost tracking for AI sessions | +| `useMemory`, `useMemoryConsolidation` | The memory system above | +| `useTheme`, `useToast` | Accessors for `ThemeProvider` and `ToastProvider` | -```bash -npm install # Install dependencies -npm run dev # Start Storybook -npm run build # Build library -npm run test # Run tests -npm run lint # Type check -``` +
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on adding new components. +
+Repository layout +
-## Compatibility +| Path | Contents | +|---|---| +| `src/components/*.tsx` | The 49 library components, each with a `.stories.tsx`; 26 also have a `.test.tsx` | +| `src/hooks/` | The 17 hooks, with the memory system in `src/hooks/memory/` | +| `src/index.ts` | The barrel export: every component, hook, type and the tokens | +| `src/tailwind-preset.ts`, `tailwind.config.ts` | The tokens as a Tailwind preset, and the config the library's CSS is built with | +| `src/styles/globals.css` | The `--ou-*` variables and base styles compiled into `dist/styles.css` | +| `.storybook/` | Storybook config, with the dark "void" background | +| `src/App.tsx`, `src/main.ts`, `src/preload.ts`, `src/renderer.*`, `src/views/`, `src/services/`, `src/store/`, `src/components/ui/`, `src/components/auth/`, `src/config/`, `src/models/`, `src/types/`, `src/lib/supabase.ts`, `src/lib/timeout.ts`, `src/styles/input.css`, `tailwind.config.js`, `index.html`, `assets/`, `.env.example` | The old Uplift Assistant Electron app. Not built, exported or type-checked. | -- React 18+ and React 19+ -- Next.js (SSR) and Tauri (CSR) -- Keyboard accessible interactive components -- Full TypeScript support with exported types +
-## Security +
-This library contains no API keys, secrets, or proprietary logic. All design tokens, components, and hooks are safe to publish publicly. The `src/` directory has been scanned to confirm zero references to `ANTHROPIC`, `SUPABASE`, `SECRET`, `KEY`, or `TOKEN` strings in library code. - -## License +## Components -MIT - Copyright (c) 2026 Operator Uplift. See [LICENSE](./LICENSE). +49 components in six Storybook groups, every one exported from `src/index.ts` with its props type. + +
+Primitives (19) +
+ +| Component | What it does | +|---|---| +| `Button` | Primary, outline, ghost and danger variants, three sizes, loading state and icons | +| `Badge` | Status labels: default, primary, success, warning and danger | +| `Card` | Default, glass and glass-dark containers with header, title, content and footer parts | +| `Input` | Text, password with show and hide, and search, with icon and error states | +| `Textarea` | Label, error state and auto-resize | +| `Toggle` | An animated on and off switch | +| `Select` | A dropdown with search and multi-select | +| `Tooltip` | Hover tooltips on any side, with an arrow | +| `Toast` | Auto-dismissing success, error, warning and info notices, through `ToastProvider` | +| `Alert` | Inline info, success, warning and error banners that can be dismissed | +| `Avatar` | Image, initials fallback and status dot | +| `AvatarGroup` | Stacked avatars with an overflow count | +| `Dropdown` | A menu with items, dividers and danger items | +| `Tabs` | Default, pills and underline variants | +| `Breadcrumb` | Breadcrumbs with a custom separator | +| `Kbd`, `Shortcut` | Keyboard keys and shortcuts | +| `Divider` | Horizontal or vertical, with an optional label | +| `LoadingSpinner` | A spinner with a label and an optional fullscreen overlay | +| `CopyButton` | Copy to the clipboard with a confirmation | + +
+ +
+Layout (5) +
+ +| Component | What it does | +|---|---| +| `Sidebar` | Collapsible navigation with sections and icons | +| `Header` | Logo, navigation links and a slot for a user menu | +| `PageWrapper` | A page layout with a maximum width | +| `Modal` | A centered overlay with a blurred backdrop that closes on Escape | +| `CommandPalette` | Grouped commands, filtering and arrow-key navigation; your app decides when it opens | + +
+ +
+Data display (7) +
+ +| Component | What it does | +|---|---| +| `Table` | Sortable columns, pagination and row selection | +| `StatCard` | A value, a label and a change indicator | +| `ProgressBar` | Determinate and indeterminate progress | +| `Skeleton` | Text, circular and rectangular placeholders | +| `EmptyState` | An icon, a message and an action | +| `CodeBlock` | Code with a filename, line numbers and a copy button | +| `StatusDot` | An animated dot for online, offline, idle, busy, away, running and error | + +
+ +
+Agent (12) +
+ +| Component | What it does | +|---|---| +| `AgentCard` | Avatar, name, status dot, model badge and install button | +| `ChatBubble` | User and assistant messages with a copy button | +| `ConversationThread` | Messages and tool calls in one thread | +| `ToolCallCard` | An expandable tool call with status, timing, input and output | +| `MemoryCard` | An expandable memory entry that fetches its content on demand | +| `MemoryPanel` | Search, type filters and create, edit and delete callbacks for memories | +| `ModelSelector` | A model dropdown with a badge for each provider | +| `TokenCounter` | Token usage with a breakdown and a limit bar | +| `CostDisplay` | Spend with a change indicator | +| `SessionIndicator` | An active session count with an animated dot | +| `PermissionChip` | An icon and label for a granted or denied permission | +| `RiskBadge` | An A to F grade with color coding | + +
+ +
+Effects (5) and providers (1) +
+ +| Component | What it does | +|---|---| +| `SpotlightCard` | A gradient highlight that follows the mouse | +| `GlowButton` | A button with an animated glow on hover | +| `FadeIn` | Fades content in when it scrolls into view (IntersectionObserver) | +| `DotGlobe` | A rotating globe of dots drawn on a canvas | +| `StreamingText` | Text that streams in with a cursor | +| `ThemeProvider` | Dark, light or system theme, remembered in `localStorage` | + +
+ +
+ +

MIT licensed, copyright 2026 Operator Uplift (see LICENSE); dependencies keep their own licenses.

+ +

Built by Matt Sim, founder of Operator Uplift. More builds at github.com/operatoruplift. Want one built for your product? Book a 15-minute call.

diff --git a/docs/readme/banner.png b/docs/readme/banner.png new file mode 100644 index 0000000..0dd0bcb Binary files /dev/null and b/docs/readme/banner.png differ diff --git a/docs/readme/flow-dark.png b/docs/readme/flow-dark.png new file mode 100644 index 0000000..c3eb517 Binary files /dev/null and b/docs/readme/flow-dark.png differ diff --git a/docs/readme/flow-light.png b/docs/readme/flow-light.png new file mode 100644 index 0000000..b667e12 Binary files /dev/null and b/docs/readme/flow-light.png differ diff --git a/docs/readme/screens-dark.png b/docs/readme/screens-dark.png new file mode 100644 index 0000000..091f94e Binary files /dev/null and b/docs/readme/screens-dark.png differ diff --git a/docs/readme/screens-light.png b/docs/readme/screens-light.png new file mode 100644 index 0000000..206b7ac Binary files /dev/null and b/docs/readme/screens-light.png differ diff --git a/package.json b/package.json index fab138e..96c39f7 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "scripts": { "dev": "storybook dev -p 6006", "build": "vite build && npm run build:css", - "build:css": "tailwindcss -i ./src/styles/globals.css -o ./dist/styles.css --minify", + "build:css": "tailwindcss -c ./tailwind.config.ts -i ./src/styles/globals.css -o ./dist/styles.css --minify", "lint": "tsc --noEmit", "test": "vitest run", "test:watch": "vitest", diff --git a/postcss.config.js b/postcss.config.js index 2aa7205..181793e 100644 --- a/postcss.config.js +++ b/postcss.config.js @@ -1,6 +1,9 @@ export default { plugins: { - tailwindcss: {}, + // The library's config. tailwind.config.js belongs to the old Electron app and would + // otherwise win Tailwind's lookup order, compiling token classes such as bg-primary + // against variables the library never defines. + tailwindcss: { config: "./tailwind.config.ts" }, autoprefixer: {}, }, }; diff --git a/tsconfig.json b/tsconfig.json index 1e8a685..1c096e9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -23,5 +23,12 @@ } }, "include": ["src/**/*"], - "exclude": ["node_modules", "dist", "**/*.stories.tsx", "**/*.test.tsx"] + "exclude": [ + "node_modules", "dist", "**/*.stories.tsx", "**/*.test.tsx", + // The old Electron app (Uplift Assistant) still sits in src/, but its dependencies left + // package.json when the library replaced it in April 2026. Nothing in the library imports it. + "src/App.tsx", "src/main.ts", "src/preload.ts", "src/renderer.ts", "src/renderer.tsx", + "src/components/auth", "src/components/ui", "src/config", "src/lib/supabase.ts", "src/lib/timeout.ts", + "src/models", "src/services", "src/store", "src/types", "src/views" + ] }