@unicitylabs/sphere-ui 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# @unicitylabs/sphere-ui
+
+Shared UI library for the Sphere ecosystem. Provides a unified design system, components, and hooks used across all Sphere applications.
+
+## Packages that use sphere-ui
+
+| App | Description |
+|-----|-------------|
+| [sphere](https://github.com/unicity-sphere/sphere) | Wallet & marketplace |
+| [sphere-dev](https://github.com/unicity-sphere/sphere-dev) | Developer Portal |
+| [sphere-backoffice](https://github.com/unicity-sphere/sphere-backoffice) | Admin panel |
+| [sphere-quest](https://github.com/unicity-sphere/sphere-quest) | Quest frontend (iframe) |
+
+## Installation
+
+```bash
+npm install @unicitylabs/sphere-ui
+```
+
+For local development, link from the monorepo:
+
+```bash
+npm install file:../sphere-ui
+```
+
+## Usage
+
+### Styles
+
+Import the design system in your app's entry point:
+
+```typescript
+import '@unicitylabs/sphere-ui/styles';
+```
+
+This provides:
+- Tailwind 4 theme tokens (colors, fonts, shadows, radii)
+- Light/dark mode CSS variables
+- Component classes (`sphere-card`, `btn-primary`, `badge-*`, `sphere-input`, etc.)
+
+### Components
+
+```typescript
+import {
+  Field,
+  Section,
+  FormModal,
+  ConfirmDialog,
+  DataTable,
+  StatusBadge,
+  SearchInput,
+  EmptyState,
+  CustomSelect,
+  PageShell,
+  AlertBanner,
+  AddressDisplay,
+  JsonPanel,
+  JsonToggleButton,
+  ChainInput,
+  MemoConditionsEditor,
+} from '@unicitylabs/sphere-ui';
+```
+
+### Hooks
+
+```typescript
+import {
+  useCanvasState,
+  useAchievementCanvasState,
+  useTestMode,
+  useChainMode,
+  useAchievementTestMode,
+  useAchievementChainMode,
+} from '@unicitylabs/sphere-ui/hooks';
+```
+
+### Icons
+
+```typescript
+import {
+  IconBack, IconUndo, IconEdit, IconTrash, IconPlus,
+  IconSearch, IconCheck, IconX, IconChain, IconPlay,
+  IconStar, IconDiamond, IconCircle,
+  // ... and more
+} from '@unicitylabs/sphere-ui';
+```
+
+### Types
+
+```typescript
+import type {
+  QuestData,
+  TrackData,
+  AchievementData,
+  QuestFormApi,
+  TrackFormApi,
+  AchievementFormApi,
+  QueryKeys,
+} from '@unicitylabs/sphere-ui';
+```
+
+## Design System
+
+### Tailwind Theme Tokens
+
+Defined in `src/styles/tokens.css` via `@theme {}` block:
+
+| Token | Light | Dark |
+|-------|-------|------|
+| `--color-bg-primary` | `#f5f5f5` | `#060606` |
+| `--color-bg-card` | `#ffffff` | `#111111` |
+| `--color-text-primary` | `#171717` | `#fefefe` |
+| `--color-text-muted` | `#a3a3a3` | `rgba(255,255,255,0.28)` |
+| `--color-brand-orange` | `#FF6F00` | `#FF6F00` |
+| `--font-display` | Anton | Anton |
+| `--font-sans` | Geist | Geist |
+| `--font-mono` | Geist Mono | Geist Mono |
+
+### Component Classes
+
+| Class | Description |
+|-------|-------------|
+| `sphere-card` | Card with border, radius, hover effect |
+| `sphere-card-glow` | Card with orange glow shadow |
+| `sphere-input` | Text input with focus ring |
+| `sphere-textarea` | Multi-line text input |
+| `sphere-select` | Select dropdown |
+| `sphere-table` | Table with header/row styles |
+| `btn-primary` | Orange primary button |
+| `btn-secondary` | Outlined secondary button |
+| `btn-danger` | Red danger button |
+| `badge-green` | Green status badge |
+| `badge-orange` | Orange status badge |
+| `badge-gray` | Gray status badge |
+| `badge-red` | Red status badge |
+| `badge-blue` | Blue status badge |
+| `badge-purple` | Purple status badge |
+| `badge-yellow` | Yellow status badge |
+
+Backward-compatible aliases `admin-card`, `admin-input`, etc. are also available.
+
+## Development
+
+```bash
+npm install      # Install dependencies
+npm run build    # Build with tsup (ESM + DTS)
+npm run dev      # Watch mode
+npm run typecheck # TypeScript check
+```
+
+### Build Output
+
+```
+dist/
+  index.js        # Base components + types
+  index.d.ts
+  forms/index.js  # Quest/Track/Achievement form exports
+  canvas/index.js # Canvas component exports
+  panels/index.js # Panel component exports
+  hooks/index.js  # Hook exports
+```
+
+## Architecture
+
+```
+src/
+  styles/
+    tokens.css       # Tailwind 4 @theme tokens + light/dark CSS vars
+    components.css   # Reusable utility classes
+    index.css        # Barrel CSS import
+  components/        # 15 base UI components
+  hooks/             # 6 canvas/chain/test mode hooks
+  forms/             # Quest/Track/Achievement form barrel
+  canvas/            # Canvas component barrel
+  panels/            # Panel component barrel
+  types.ts           # Shared TypeScript interfaces
+  index.ts           # Main barrel export
+```
+
+## Peer Dependencies
+
+- `react` ^19.0.0
+- `react-dom` ^19.0.0
+- `@tanstack/react-query` ^5.0.0
+- `@tanstack/react-table` ^8.0.0
+- `@dnd-kit/core` ^6.0.0
+- `@dnd-kit/sortable` ^8.0.0
+- `lucide-react` ^0.400.0
+
+## License
+
+MIT

package/dist/canvas/index.d.ts

@@ -0,0 +1,3 @@
+export { a as AchSelectedItem, C as CanvasAchievement, b as CanvasQuest, c as CanvasTrack, S as SelectedItem } from '../index-DsEO4kM1.js';
+import 'react';
+import '@dnd-kit/core';

package/dist/forms/index.d.ts

@@ -0,0 +1 @@
+export { A as AchievementData, a as AchievementFormApi, b as QuestData, c as QuestFormApi, T as TrackData, d as TrackFormApi } from '../index-DMHfA7fr.js';

package/dist/hooks/index.d.ts

@@ -0,0 +1,122 @@
+export { A as AchPendingChange, a as AchSelectedItem, C as CanvasAchievement, b as CanvasQuest, c as CanvasTrack, P as PendingChange, S as SelectedItem, d as chainColor, g as getAchLaneId, e as getLaneId, u as useAchievementCanvasState, f as useCanvasState } from '../index-DsEO4kM1.js';
+import 'react';
+import '@dnd-kit/core';
+
+type QuestTestState = 'locked' | 'ready' | 'verifying' | 'passed' | 'failed';
+interface TestModeState {
+    active: boolean;
+    withVerification: boolean;
+    ignoreChain: boolean;
+    completedIds: Set<string>;
+    verifyingId: string | null;
+    failedIds: Map<string, string>;
+}
+/** Minimal quest interface for test state computation */
+interface TestableQuest {
+    _id: string;
+    status: string;
+    prerequisites?: string[];
+    chains?: Record<string, number>;
+}
+/**
+ * Compute the test-mode display state for a single quest.
+ * - ignoreChain=true  -> all ACTIVE quests are READY
+ * - ignoreChain=false -> respect chains map + prerequisites
+ */
+declare function computeQuestTestState(quest: TestableQuest, state: TestModeState, allQuests: TestableQuest[]): QuestTestState;
+declare function useTestMode(verifyFn?: (questId: string) => Promise<{
+    passed: boolean;
+    reason?: string;
+}>): {
+    testMode: TestModeState;
+    enterTestMode: () => void;
+    exitTestMode: () => void;
+    toggleVerification: () => void;
+    toggleIgnoreChain: () => void;
+    claimQuest: (questId: string) => Promise<void>;
+    resetTest: () => void;
+};
+
+/** Minimal interface for chainable items */
+interface ChainableItem {
+    _id: string;
+    chains?: Record<string, number>;
+    [key: string]: unknown;
+}
+interface ChainModeState {
+    active: boolean;
+    selectedChain: string | null;
+}
+interface ChainModeActions {
+    toggle: () => void;
+    selectChain: (group: string) => void;
+    deselectChain: () => void;
+    exit: () => void;
+}
+interface ChainModeComputed<T> {
+    chainMap: Map<string, T[]>;
+    chainGroups: string[];
+}
+type ChainMode<T> = ChainModeState & ChainModeActions & ChainModeComputed<T>;
+declare function useChainMode<T extends ChainableItem>(items: T[]): ChainMode<T>;
+
+type AchTestState = 'locked' | 'ready' | 'completed' | 'claimed';
+interface AchievementProgressEntry {
+    achievementId: string;
+    current?: number;
+    completed?: boolean;
+    claimed?: boolean;
+    [key: string]: unknown;
+}
+interface AchTestModeState {
+    active: boolean;
+    walletAddress: string;
+    ignoreChain: boolean;
+    progressMap: Map<string, AchievementProgressEntry>;
+    loading: boolean;
+    error: string | null;
+}
+/** Minimal achievement interface for test state computation */
+interface TestableAchievement {
+    _id: string;
+    status: string;
+    chains?: Record<string, number>;
+}
+/**
+ * Compute the test-mode display state for a single achievement.
+ */
+declare function computeAchTestState(ach: TestableAchievement, state: AchTestModeState, allAchievements: TestableAchievement[]): AchTestState;
+declare function useAchievementTestMode(fetchProgressFn?: (address: string) => Promise<AchievementProgressEntry[]>): {
+    testMode: AchTestModeState;
+    enterTestMode: () => void;
+    exitTestMode: () => void;
+    toggleIgnoreChain: () => void;
+    setWalletAddress: (address: string) => void;
+    fetchProgress: (address?: string) => Promise<void>;
+    clearProgress: () => void;
+};
+
+/** Minimal interface for chainable achievements */
+interface ChainableAchievement {
+    _id: string;
+    chains?: Record<string, number>;
+    [key: string]: unknown;
+}
+interface AchChainModeState {
+    active: boolean;
+    selectedChain: string | null;
+}
+interface AchChainModeActions {
+    toggle: () => void;
+    selectChain: (group: string) => void;
+    deselectChain: () => void;
+    exit: () => void;
+}
+interface AchChainModeComputed<T> {
+    chainMap: Map<string, T[]>;
+    chainGroups: string[];
+}
+type AchChainMode<T> = AchChainModeState & AchChainModeActions & AchChainModeComputed<T>;
+declare function useAchievementChainMode<T extends ChainableAchievement>(achievements: T[]): AchChainMode<T>;
+
+export { type AchChainMode, type AchChainModeActions, type AchChainModeComputed, type AchChainModeState, type AchTestModeState, type AchTestState, type AchievementProgressEntry, type ChainMode, type ChainModeActions, type ChainModeComputed, type ChainModeState, type QuestTestState, type TestModeState, computeAchTestState, computeQuestTestState, useAchievementChainMode, useAchievementTestMode, useChainMode, useTestMode };