@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

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

1. Configure the API Client

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

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

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

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:

// 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