npm package: @micahgoodman/checklists
Description: A complete checklists module SDK for React with backend API client, adapter system, and UI components. Supports library, standalone, and embedded SDK modes.
Author: Micah Goodman
Latest version: 1.1.1

# @micahgoodman/checklists

A complete checklists module SDK for React with backend API client, adapter system, and UI components. Supports **library**, **standalone**, and **embedded SDK** modes.

## Features

- 📋 **Complete Checklist Management** - Create, read, update, and delete checklists with items
- ✅ **Item Tracking** - Track completion status for each checklist item
- 🔄 **Real-time Updates** - Optional Supabase integration for live synchronization
- 🎨 **Ready-to-Use Components** - Pre-built React components for lists, cards, and detail views
- 🔌 **Adapter Pattern** - Standardized interface for consistent data management
- 📦 **TypeScript Support** - Full type definitions included
- 🌐 **Context-Aware** - Associate checklists with other entities (projects, lessons, etc.)
- 🔐 **Built-in Authentication** - Keycloak OAuth and email/password support via @micahgoodman/auth
- 🚀 **Three Modes** - Use as library, standalone app, or embedded SDK
- 🔗 **Single Sign-On** - Federated identity across multiple apps

## Three Modes of Operation

### 📦 Library Mode (Default)
Import as npm package into your React app. You control the UI, auth, and backend.

### 🚀 Standalone Mode  
Deploy as a complete checklists application with built-in Keycloak authentication.

### 🔗 Embedded SDK Mode (Recommended for Multi-App)
Import components into a parent app. User logs in once via Keycloak, components authenticate silently against this module's backend.

## Quick Start

### Library Mode

```bash
npm install @micahgoodman/checklists @supabase/supabase-js
```

**1. Configure the API Client**

```typescript
import { createClient } from '@supabase/supabase-js';
import { configureChecklistsApi, createChecklistsAdapter } from '@micahgoodman/checklists';

const supabase = createClient(
  process.env.VITE_SUPABASE_URL!,
  process.env.VITE_SUPABASE_ANON_KEY!
);

// Configure API
configureChecklistsApi({
  apiBase: process.env.VITE_API_BASE!,
  supabaseClient: supabase,
  supabaseAnonKey: process.env.VITE_SUPABASE_ANON_KEY!
});

// Create adapter
export const ChecklistAdapter = createChecklistsAdapter(supabase);
```

### 2. Use in Your Components

```typescript
import React from 'react';
import { useModuleList, ChecklistListItem, ChecklistDetailView } from '@micahgoodman/checklists';
import { ChecklistAdapter } from './config/checklistAdapter';

function ChecklistsPage() {
  const { items, loading, refresh } = useModuleList(ChecklistAdapter);
  const [selected, setSelected] = React.useState<string | null>(null);
  
  const selectedChecklist = items.find(c => c.id === selected) || null;

  if (loading) return <div>Loading...</div>;

  return (
    <div style={{ display: 'flex' }}>
      <aside style={{ width: '300px', borderRight: '1px solid #ddd' }}>
        {items.map((checklist, index) => (
          <ChecklistListItem
            key={checklist.id}
            item={checklist}
            isSelected={checklist.id === selected}
            onSelect={() => setSelected(checklist.id)}
            index={index}
          />
        ))}
      </aside>
      <main style={{ flex: 1 }}>
        <ChecklistDetailView
          checklist={selectedChecklist}
          onUpdated={refresh}
          onDeleted={() => {
            setSelected(null);
            refresh();
          }}
          onShowToast={(msg) => console.log(msg)}
        />
      </main>
    </div>
  );
}
```

## API Reference

### Types

```typescript
type ChecklistItem = {
  text: string;
  completed: boolean;
};

type Checklist = {
  id: string;
  title: string;
  items: ChecklistItem[];
  dateCreated: string;
};

type Context = {
  type: string;
  id: string;
};
```

### API Functions

- `configureChecklistsApi(config)` - Configure the API client
- `fetchChecklists()` - Fetch all checklists
- `fetchChecklistsByContext(contextType, contextId)` - Fetch checklists by context
- `createChecklist(input)` - Create a new checklist
- `updateChecklist(id, input)` - Update an existing checklist
- `deleteChecklist(id)` - Delete a checklist
- `associateChecklist(body)` - Associate a checklist with another entity
- `disassociateChecklist(body)` - Disassociate a checklist from an entity

### Components

- `ChecklistListItem` - Sidebar list item with progress indicator
- `WhiteboardChecklistCard` - Card view for whiteboard layouts
- `ChecklistDetailView` - Full detail view with editing capabilities
- `ChecklistDetailModal` - Modal wrapper for detail view
- `CreateChecklistModal` - Modal for creating new checklists

### Hooks

- `useModuleList(adapter, opts?)` - Manage list of checklists with loading/error states
- `useChecklistSelection(checklists)` - Manage checklist selection state

### Adapter

```typescript
const ChecklistAdapter = createChecklistsAdapter(supabaseClient);
```

The adapter provides:
- `list(opts)` - List checklists (optionally filtered by context)
- `create(input)` - Create a new checklist
- `update(id, patch)` - Update a checklist
- `remove(id, opts)` - Remove or disassociate a checklist
- `getKey(item)` - Get unique key for a checklist
- `getTitle(item)` - Get display title for a checklist
- `subscribe(callback, opts)` - Subscribe to real-time updates (if Supabase configured)

## Context-Aware Usage

Associate checklists with other entities:

```typescript
// Create a checklist within a project context
await createChecklist({
  title: 'Project Tasks',
  items: [
    { text: 'Setup environment', completed: false },
    { text: 'Write documentation', completed: false }
  ],
  context: {
    type: 'project',
    id: 'project-123'
  }
});

// Fetch checklists for a specific context
const { items } = useModuleList(ChecklistAdapter, {
  context: { type: 'project', id: 'project-123' }
});
```

## Backend Requirements

This module works with the universal `module_data` table and uses the module type `checklist`. 

Your backend should support:
- `/concepts?filter=checklist` - List all checklists
- `/concepts?filter=checklist&contextType=X&contextId=Y` - List by context
- `POST /concepts?filter=checklist` - Create checklist
- `PATCH /concepts/:id` - Update checklist
- `DELETE /concepts/:id` - Delete checklist

## TypeScript

Full TypeScript support with complete type definitions included.

## License

MIT