astrogators-shared-ui 0.6.0 → 0.6.1

package/README.md

@@ -1,172 +1,114 @@
-# @psytor/astrogators-shared-ui
+# astrogators-shared-ui
 
-Shared UI components and utilities for Astrogator's Table applications.
+Shared React components, auth, and API client for the Astrogator's Table
+frontends (`astrogators-hub`, `mod-ledger-ui`, `nightwatcher-ui`). Published
+to the public npm registry as `astrogators-shared-ui` (unscoped).
+
+> The git repo lives under `psytor/astrogators-shared-ui` on GitHub, but the
+> package itself is published to **npmjs.org**, not GitHub Packages. No
+> `.npmrc` scope config is needed to install.
+
+This is a library — there is no app shell here. See `PUBLISHING.md` for the
+release flow and `CLAUDE.md` for architecture notes.
 
 ## Installation
 
 ```bash
-npm install @psytor/astrogators-shared-ui
+npm install astrogators-shared-ui
 ```
 
-## Setup
-
-### 1. Initialize API Client
+Peer dependencies: `react` and `react-dom` (18 or 19).
 
-In your application's entry point (e.g., `main.tsx` or `App.tsx`):
-
-```tsx
-import { initializeApiClient } from '@psytor/astrogators-shared-ui';
+## Setup
 
-initializeApiClient({
-  baseURL: 'http://localhost:8000', // Your backend API URL
-  onUnauthorized: () => {
-    // Handle unauthorized (e.g., redirect to login)
-    window.location.href = '/login';
-  },
-});
-```
+### 1. Wrap the app in `AuthProvider`
 
-### 2. Wrap Application with AuthProvider
+`AuthProvider` initializes the API client with the given `apiBaseUrl` and
+manages auth, feature flags, and ally codes for the whole app. Pass the
+**prefixed** backend URL — workspace backends mount their routes under
+`/<service-name>` (see the workspace `CLAUDE.md`).
 
 ```tsx
-import { AuthProvider } from '@psytor/astrogators-shared-ui';
+import { AuthProvider } from 'astrogators-shared-ui';
+import 'astrogators-shared-ui/styles';
 
 function App() {
   return (
-    <AuthProvider>
-      {/* Your app content */}
+    <AuthProvider apiBaseUrl={import.meta.env.VITE_API_BASE_URL}>
+      {/* your app */}
     </AuthProvider>
   );
 }
 ```
 
-### 3. Import Global Styles
-
-```tsx
-import '@psytor/astrogators-shared-ui/styles';
-```
-
-## Components
+`VITE_API_BASE_URL` looks like `http://localhost:8000/astrogators-table` in
+dev.
 
-### Layout Components
+### 2. (Optional) Reconfigure the API client
 
-#### TopBar
+`AuthProvider` already calls `initializeApiClient`. Call it yourself only if
+you need a custom `onUnauthorized` handler (e.g. router-driven redirects):
 
 ```tsx
-import { TopBar } from '@psytor/astrogators-shared-ui';
+import { initializeApiClient } from 'astrogators-shared-ui';
 
-<TopBar
-  logo={<div>Astrogator's Table</div>}
-  rightContent={<button>Login</button>}
-/>
+initializeApiClient({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  onUnauthorized: () => navigate('/login'),
+});
 ```
 
-#### Container
-
-```tsx
-import { Container } from '@psytor/astrogators-shared-ui';
+## Components
 
-<Container maxWidth="lg" padding>
-  {/* Content */}
-</Container>
-```
+All components are styled via CSS Modules and the global design tokens in
+`./styles`. Override the design system by redefining CSS variables on `:root`
+(see "Theming").
 
-#### Footer
+### Layout
 
 ```tsx
-import { Footer } from '@psytor/astrogators-shared-ui';
+import { TopBar, Container, Footer } from 'astrogators-shared-ui';
 
+<TopBar logo={<Logo />} rightContent={<UserMenu />} />
+<Container maxWidth="lg" padding>{children}</Container>
 <Footer />
 ```
 
-### Form Components
-
-#### Button
+### Forms
 
 ```tsx
-import { Button } from '@psytor/astrogators-shared-ui';
+import { Button, Input, Select, AllyCodeDropdown } from 'astrogators-shared-ui';
 
-<Button variant="primary" size="md" onClick={handleClick}>
-  Click Me
-</Button>
+<Button variant="primary" size="md" loading={submitting}>Save</Button>
+<Input label="Email" type="email" required error={errors.email} />
+<Select label="Profile" options={profiles} placeholder="Choose…" />
 
-<Button variant="outline" loading>
-  Loading...
-</Button>
+// Wired into useAuth — manages the user's ally codes (DB-backed when
+// authenticated, localStorage when anonymous):
+<AllyCodeDropdown />
 ```
 
-#### Input
+`Button` variants: `primary | secondary | outline | ghost | danger`.
 
-```tsx
-import { Input } from '@psytor/astrogators-shared-ui';
-
-<Input
-  label="Email"
-  type="email"
-  placeholder="Enter your email"
-  required
-  error={errors.email}
-/>
-```
-
-#### Select
+### Display
 
 ```tsx
-import { Select } from '@psytor/astrogators-shared-ui';
-
-<Select
-  label="Choose Profile"
-  options={[
-    { value: 'standard', label: 'Standard' },
-    { value: 'speed', label: 'Speed Focus' },
-  ]}
-  placeholder="Select a profile"
-/>
-```
-
-### Display Components
-
-#### Card
-
-```tsx
-import { Card } from '@psytor/astrogators-shared-ui';
+import { Card, Badge, Modal } from 'astrogators-shared-ui';
 
 <Card variant="elevated" chamfered chamferSize="md" padding="lg" hoverable>
-  <h3>The Mod Ledger</h3>
-  <p>Analyze your mods</p>
+  …
 </Card>
-```
-
-#### Badge
-
-```tsx
-import { Badge } from '@psytor/astrogators-shared-ui';
 
 <Badge variant="success">Active</Badge>
 <Badge variant="warning" size="sm">Beta</Badge>
-```
 
-#### Modal
-
-```tsx
-import { Modal } from '@psytor/astrogators-shared-ui';
-
-<Modal
-  isOpen={isOpen}
-  onClose={() => setIsOpen(false)}
-  title="Login"
-  size="md"
->
-  {/* Modal content */}
-</Modal>
+<Modal isOpen={open} onClose={close} title="Login" size="md">…</Modal>
 ```
 
-### Feedback Components
-
-#### Loader
+### Feedback
 
 ```tsx
-import { Loader } from '@psytor/astrogators-shared-ui';
+import { Loader } from 'astrogators-shared-ui';
 
 <Loader size="md" variant="spinner" />
 <Loader size="lg" variant="dots" />
@@ -174,82 +116,96 @@ import { Loader } from '@psytor/astrogators-shared-ui';
 
 ## Authentication
 
-### useAuth Hook
+`useAuth` returns the full auth + ally-code surface. The hook must be called
+inside `AuthProvider`.
 
 ```tsx
-import { useAuth } from '@psytor/astrogators-shared-ui';
+import { useAuth } from 'astrogators-shared-ui';
 
-function MyComponent() {
-  const { user, isAuthenticated, login, logout, isLoading } = useAuth();
+const {
+  // session
+  user, isAuthenticated, isLoading,
+  login, register, logout, refreshUser,
+  forgotPassword, resetPassword, resendVerification,
 
-  const handleLogin = async () => {
-    try {
-      await login({
-        email: 'user@example.com',
-        password: 'password',
-      });
-    } catch (error) {
-      console.error('Login failed:', error);
-    }
-  };
+  // backend feature flags (e.g. auth_enabled)
+  authEnabled, isLoadingFeatures,
 
-  if (isLoading) return <Loader />;
+  // ally codes — DB-backed when logged in, localStorage when anonymous
+  allyCodes, selectedAllyCode, isLoadingAllyCodes,
+  fetchAllyCodes, addAllyCode, removeAllyCode,
+  selectAllyCode, updateAllyCodeLastUsed,
 
-  return (
-    <div>
-      {isAuthenticated ? (
-        <div>
-          <p>Welcome, {user?.username}!</p>
-          <button onClick={logout}>Logout</button>
-        </div>
-      ) : (
-        <button onClick={handleLogin}>Login</button>
-      )}
-    </div>
-  );
-}
+  // localStorage → DB migration prompt for users who sign up after
+  // adding ally codes anonymously
+  migrationPrompt, dismissMigrationPrompt, migrateLocalStorageCodes,
+} = useAuth();
 ```
 
-## API Client
+Tokens are stored in `localStorage`. Registration does **not** auto-login —
+it requires email verification.
 
-### Using the API Client
+## API client
 
 ```tsx
-import { apiClient } from '@psytor/astrogators-shared-ui';
+import { apiClient } from 'astrogators-shared-ui';
 
-// GET request
-const data = await apiClient.get('/api/v1/game-data/characters');
-
-// POST request
+const characters = await apiClient.get('/api/v1/game-data/characters');
 const result = await apiClient.post('/api/v1/mod-ledger/evaluate/123456789', {
   profile_name: 'standard',
 });
 ```
 
-The API client automatically:
-- Injects JWT access token in Authorization header
-- Refreshes expired tokens
-- Retries failed requests after token refresh
-- Calls `onUnauthorized` callback on auth failure
+The client:
+- injects the access token into `Authorization`
+- on `401`, transparently refreshes via `/api/v1/auth/refresh-token` and
+  retries the original request once
+- calls `onUnauthorized` if refresh fails
+
+Endpoints are written **without** the service prefix — the prefix lives in
+the configured `baseURL`.
 
-## TypeScript Types
+## Ally code utilities
 
-All TypeScript types are exported:
+For UI that needs to format/validate the 9-digit SWGOH player IDs outside the
+context of `useAuth`:
+
+```tsx
+import {
+  formatAllyCode,        // "123456789" → "123-456-789"
+  unformatAllyCode,      // "123-456-789" → "123456789"
+  getAllyCodesFromStorage,
+  saveAllyCodeToStorage,
+  removeAllyCodeFromStorage,
+  getSelectedAllyCode,
+  setSelectedAllyCode,
+  clearAllyCodes,
+} from 'astrogators-shared-ui';
+```
+
+Prefer `useAuth` when you can — it keeps DB and localStorage in sync.
+
+## TypeScript
+
+All public types are re-exported from the package root, including:
 
 ```tsx
 import type {
-  User,
-  LoginRequest,
-  LoginResponse,
-  ParsedMod,
-  ModEvaluation,
-  ApiError,
-} from '@psytor/astrogators-shared-ui';
+  User, LoginRequest, LoginResponse,
+  RegisterRequest, ForgotPasswordRequest, ResetPasswordRequest,
+  AllyCode, AllyCodeCreate, AllyCodeListResponse, StoredAllyCode,
+  ApiResponse, ApiError, PaginatedResponse,
+  ParsedMod, ModStat, ModEvaluation, EvaluationRequest, EvaluationResponse,
+} from 'astrogators-shared-ui';
 ```
 
-## CSS Variables
+Consumers should set `"moduleResolution": "bundler"` (or `"node16"`) in
+`tsconfig.json` so the bundled `.d.ts` files resolve.
 
-Customize the design system by overriding CSS variables:
+## Theming
+
+Design tokens are CSS variables on `:root`. Override anything you need in
+your own stylesheet, loaded after the library styles:
 
 ```css
 :root {
@@ -261,57 +217,35 @@ Customize the design system by overriding CSS variables:
 }
 ```
 
-## Chamfered Boxes
+### Chamfered boxes
 
-Use the chamfered box effect on any element:
+Sci-fi cut-corner effect, available as utility classes or via `Card`:
 
 ```tsx
-<div className="chamfered-box">
-  {/* Content with cut corners */}
-</div>
-
-<div className="chamfered-box-lg">
-  {/* Large chamfered corners */}
-</div>
+<div className="chamfered-box">…</div>
+<div className="chamfered-box-sm">…</div>
+<div className="chamfered-box-lg">…</div>
 
-<div className="chamfered-box-sm">
-  {/* Small chamfered corners */}
-</div>
-```
-
-Or use the Card component:
-
-```tsx
-<Card chamfered chamferSize="lg">
-  {/* Content */}
-</Card>
+<Card chamfered chamferSize="lg">…</Card>
 ```
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build library
-npm run build
-
-# Type check
-npm run type-check
+npm run build        # tsc && vite build → dist/
+npm run type-check   # tsc --noEmit
 ```
 
-## Publishing
+There is no `dev` server worth running (this is a library, not an app).
+Iterate by rebuilding and reinstalling in a consumer.
 
-```bash
-# Bump version
-npm version patch  # or minor, or major
-
-# Build
-npm run build
-
-# Publish to GitHub Packages
-npm publish
-```
+See `PUBLISHING.md` for the release procedure. Two non-negotiable rules:
+- **Always `npm run build` before `npm publish`** — `dist/` is gitignored
+  but is the only thing shipped, so skipping the build re-publishes stale
+  code.
+- **`npm login` and `npm publish` must be run by the user**, not by Claude
+  — publishing needs interactive npm auth.
 
 ## License
 

package/dist/index.js

@@ -417,29 +417,41 @@ var x = "astrogators_access_token", S = "astrogators_refresh_token", C = () => l
 			y(!1);
 		}
 	}, [r]), I = n(async (e) => {
+		r && typeof e == "number" ? (await N.put(`/api/v1/users/me/ally-codes/${e}/use`, {}), await F()) : !r && typeof e == "string" && (B(e), h(L()));
+	}, [r, F]), G = n((e) => {
+		if (_(e), H(e), e && r) {
+			let t = m.find((t) => "ally_code" in t && t.ally_code === e);
+			t && "id" in t && I(t.id);
+		} else e && !r && B(e);
+	}, [
+		r,
+		m,
+		I
+	]), K = n(async (e) => {
 		if (!/^\d{9}$/.test(e)) throw Error("Ally code must be exactly 9 digits");
 		if (r) {
 			let t = await N.post("/api/v1/users/me/ally-codes", { ally_code: e });
-			h((e) => [t, ...e]), m.length === 0 && K(e);
+			h((e) => [t, ...e]), m.length === 0 && G(e);
 		} else {
 			let t = await N.get(`/api/v1/player-data/player/${e}`);
 			if (!t) throw Error("Invalid ally code - player not found");
 			R({
 				ally_code: e,
-				player_name: t?.data?.name || null,
+				player_name: t.data?.name ?? null,
 				last_used_at: (/* @__PURE__ */ new Date()).toISOString()
-			}), h(L()), m.length === 0 && K(e);
+			}), h(L()), m.length === 0 && G(e);
 		}
-	}, [r, m.length]), G = n(async (e) => {
-		r && typeof e == "number" ? (await N.delete(`/api/v1/users/me/ally-codes/${e}`), h((t) => t.filter((t) => "id" in t && t.id !== e))) : !r && typeof e == "string" && (z(e), h(L()), g === e && K(null));
-	}, [r, g]), K = n((e) => {
-		if (_(e), H(e), e && r) {
-			let t = m.find((t) => "ally_code" in t && t.ally_code === e);
-			t && "id" in t && q(t.id);
-		} else e && !r && B(e);
-	}, [r, m]), q = n(async (e) => {
-		r && typeof e == "number" ? (await N.put(`/api/v1/users/me/ally-codes/${e}/use`, {}), await F()) : !r && typeof e == "string" && (B(e), h(L()));
-	}, [r, F]), J = n(() => {
+	}, [
+		r,
+		m.length,
+		G
+	]), q = n(async (e) => {
+		r && typeof e == "number" ? (await N.delete(`/api/v1/users/me/ally-codes/${e}`), h((t) => t.filter((t) => "id" in t && t.id !== e))) : !r && typeof e == "string" && (z(e), h(L()), g === e && G(null));
+	}, [
+		r,
+		g,
+		G
+	]), J = n(() => {
 		x({
 			show: !1,
 			localStorageCodes: []
@@ -448,14 +460,14 @@ var x = "astrogators_access_token", S = "astrogators_refresh_token", C = () => l
 		if (!r) return;
 		let e = L();
 		for (let t of e) try {
-			await I(t.ally_code);
+			await K(t.ally_code);
 		} catch (e) {
 			console.error(`Failed to migrate ally code ${t.ally_code}:`, e);
 		}
 		U(), J();
 	}, [
 		r,
-		I,
+		K,
 		J
 	]);
 	i(() => {
@@ -478,10 +490,10 @@ var x = "astrogators_access_token", S = "astrogators_refresh_token", C = () => l
 		selectedAllyCode: g,
 		isLoadingAllyCodes: v,
 		fetchAllyCodes: F,
-		addAllyCode: I,
-		removeAllyCode: G,
-		selectAllyCode: K,
-		updateAllyCodeLastUsed: q,
+		addAllyCode: K,
+		removeAllyCode: q,
+		selectAllyCode: G,
+		updateAllyCodeLastUsed: I,
 		migrationPrompt: b,
 		dismissMigrationPrompt: J,
 		migrateLocalStorageCodes: Y

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrogators-shared-ui",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Shared UI components and utilities for Astrogator's Table applications",
   "type": "module",
   "main": "./dist/index.js",