question-bank-framework 0.0.0-stage → 0.1.0

package/framework/components/ui/sheet.tsx

@@ -0,0 +1,140 @@
+import * as React from "react"
+import { cn } from '../../lib/utils.ts'
+import { XIcon } from "lucide-react"
+import { Dialog as SheetPrimitive } from "radix-ui"
+
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />
+}
+
+function SheetTrigger({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
+}
+
+function SheetClose({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Close>) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
+}
+
+function SheetPortal({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
+}
+
+function SheetOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+  return (
+    <SheetPrimitive.Overlay
+      data-slot="sheet-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/50 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SheetContent({
+  className,
+  children,
+  side = "right",
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+  side?: "top" | "right" | "bottom" | "left"
+  showCloseButton?: boolean
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Content
+        data-slot="sheet-content"
+        className={cn(
+          "fixed z-50 flex flex-col gap-4 bg-background shadow-lg transition ease-in-out data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
+          side === "right" &&
+            "inset-y-0 right-0 h-full w-3/4 border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm",
+          side === "left" &&
+            "inset-y-0 left-0 h-full w-3/4 border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm",
+          side === "top" &&
+            "inset-x-0 top-0 h-auto border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
+          side === "bottom" &&
+            "inset-x-0 bottom-0 h-auto border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close className="absolute top-4 right-4 rounded-xs opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none data-[state=open]:bg-secondary">
+            <XIcon className="size-4" />
+            <span className="sr-only">Close</span>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Content>
+    </SheetPortal>
+  )
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn("flex flex-col gap-1.5 p-4", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Title>) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn("font-semibold text-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+}

package/framework/components/ui/table.tsx

@@ -0,0 +1,121 @@
+"use client"
+
+import * as React from "react"
+import { cn } from '../../lib/utils.ts'
+
+type TableProps = React.ComponentProps<"table"> & {
+  containerRef?: React.Ref<HTMLDivElement>
+  containerClassName?: string
+}
+
+function Table({ className, containerRef, containerClassName, ...props }: TableProps) {
+  return (
+    <div
+      ref={containerRef}
+      data-slot="table-container"
+      className={cn("relative w-full overflow-x-auto", containerClassName)}
+    >
+      <table
+        data-slot="table"
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return (
+    <thead
+      data-slot="table-header"
+      className={cn("[&_tr]:border-b", className)}
+      {...props}
+    />
+  )
+}
+
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn("[&_tr:last-child]:border-0", className)}
+      {...props}
+    />
+  )
+}
+
+function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+  return (
+    <tfoot
+      data-slot="table-footer"
+      className={cn(
+        "border-t bg-muted/50 font-medium [&>tr]:last:border-b-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn(
+        "border-b transition-colors hover:bg-muted/50 has-aria-expanded:bg-muted/50 data-[state=selected]:bg-muted",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn(
+        "h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn(
+        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn("mt-4 text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+}

package/framework/convex/questionStatuses.ts

@@ -0,0 +1,30 @@
+import { mutationGeneric as mutation, queryGeneric as query } from 'convex/server'
+import { v } from 'convex/values'
+
+const statusValidator = v.union(v.literal('unanswered'), v.literal('revisit'), v.literal('complete'))
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => await ctx.db.query('questionStatuses').collect(),
+})
+
+export const set = mutation({
+  args: {
+    questionId: v.string(),
+    status: statusValidator,
+  },
+  handler: async (ctx, { questionId, status }) => {
+    const existing = await ctx.db.query('questionStatuses')
+      .withIndex('by_question_id', (q) => q.eq('questionId', questionId))
+      .first()
+    const updatedAt = Date.now()
+
+    if (existing) {
+      await ctx.db.patch(existing._id, { status, updatedAt })
+    } else {
+      await ctx.db.insert('questionStatuses', { questionId, status, updatedAt })
+    }
+
+    return updatedAt
+  },
+})

package/framework/convex/quizzes.ts

@@ -0,0 +1,50 @@
+import { mutationGeneric as mutation, queryGeneric as query } from 'convex/server'
+import { v } from 'convex/values'
+
+export const create = mutation({
+  args: {
+    title: v.string(),
+    questionIds: v.array(v.string()),
+  },
+  handler: async (ctx, { title, questionIds }) => {
+    const createdAt = Date.now()
+    return await ctx.db.insert('quizzes', {
+      title,
+      questionIds,
+      answers: {},
+      currentQuestion: 0,
+      completed: false,
+      createdAt,
+    })
+  },
+})
+
+export const get = query({
+  args: { quizId: v.id('quizzes') },
+  handler: async (ctx, { quizId }) => await ctx.db.get(quizId),
+})
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => await ctx.db.query('quizzes').withIndex('by_created_at').order('desc').collect(),
+})
+
+export const remove = mutation({
+  args: { quizId: v.id('quizzes') },
+  handler: async (ctx, { quizId }) => {
+    await ctx.db.delete(quizId)
+  },
+})
+
+export const saveProgress = mutation({
+  args: {
+    quizId: v.id('quizzes'),
+    title: v.string(),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
+    currentQuestion: v.number(),
+    completed: v.boolean(),
+  },
+  handler: async (ctx, { quizId, title, answers, currentQuestion, completed }) => {
+    await ctx.db.patch(quizId, { title, answers, currentQuestion, completed })
+  },
+})

package/framework/convex/schema.ts

@@ -0,0 +1,18 @@
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+
+export default defineSchema({
+  quizzes: defineTable({
+    title: v.string(),
+    questionIds: v.array(v.string()),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
+    currentQuestion: v.number(),
+    completed: v.boolean(),
+    createdAt: v.number(),
+  }).index('by_created_at', ['createdAt']),
+  questionStatuses: defineTable({
+    questionId: v.string(),
+    status: v.union(v.literal('unanswered'), v.literal('revisit'), v.literal('complete')),
+    updatedAt: v.number(),
+  }).index('by_question_id', ['questionId']),
+})

package/framework/index.ts

@@ -0,0 +1,26 @@
+// Public framework surface. Import from "question-bank-framework/framework".
+// Every file under framework/ is ejectable via `qb reveal <path>`.
+
+export { QuestionBank } from './components/question-bank.tsx';
+export { QuizPage } from './components/quiz-page.tsx';
+export { QuizList } from './components/quiz-list.tsx';
+export { AppShell } from './components/app-shell.tsx';
+export { FilterBuilder } from './components/filter-builder.tsx';
+export { MarkdownContent } from './components/markdown-content.tsx';
+
+export {
+  createFilterFields,
+  matchesFilters,
+  matchesSearch,
+  questionStatusLabels,
+  defaultOperatorByType,
+  fieldTypeLabels,
+  operatorLabels,
+} from './lib/question-filter.ts';
+export type { FilterField, FilterMatch, FilterOperatorId, FilterRule } from './lib/question-filter.ts';
+
+export { createQuestionFilterStore, useQuestionFilterStore } from './lib/question-filter-store.ts';
+export { createQuiz, deleteQuiz, getQuiz, listQuizzes, saveQuizLocally, saveQuizProgress } from './lib/quiz-storage.ts';
+export { getQuestionStatuses, setQuestionStatus } from './lib/question-status-storage.ts';
+export { convexApi } from './lib/convex-api.ts';
+export { cn } from './lib/utils.ts';

package/framework/lib/convex-api.ts

@@ -0,0 +1,36 @@
+// Typed Convex function references. No value imports — safe to eject.
+// Framework-owned: eject with `qb reveal framework/lib/convex-api.ts`.
+
+import { makeFunctionReference } from 'convex/server';
+import type { QuestionStatus, QuizAnswer, QuizSession } from '../../core/types.ts';
+
+type CreateQuizArgs = { title: string; questionIds: string[] };
+type ProgressArgs = {
+  quizId: string;
+  title: string;
+  answers: Record<string, QuizAnswer>;
+  currentQuestion: number;
+  completed: boolean;
+};
+type QuizDocument = QuizSession & { _id: string; _creationTime: number };
+type QuestionStatusDocument = {
+  _id: string;
+  _creationTime: number;
+  questionId: string;
+  status: QuestionStatus;
+  updatedAt: number;
+};
+
+export const convexApi = {
+  quizzes: {
+    create: makeFunctionReference<'mutation', CreateQuizArgs, string>('quizzes:create'),
+    get: makeFunctionReference<'query', { quizId: string }, QuizDocument | null>('quizzes:get'),
+    list: makeFunctionReference<'query', Record<string, never>, QuizDocument[]>('quizzes:list'),
+    remove: makeFunctionReference<'mutation', { quizId: string }, null>('quizzes:remove'),
+    saveProgress: makeFunctionReference<'mutation', ProgressArgs, null>('quizzes:saveProgress'),
+  },
+  questionStatuses: {
+    list: makeFunctionReference<'query', Record<string, never>, QuestionStatusDocument[]>('questionStatuses:list'),
+    set: makeFunctionReference<'mutation', { questionId: string; status: QuestionStatus }, number>('questionStatuses:set'),
+  },
+};

package/framework/lib/question-filter-store.ts

@@ -0,0 +1,116 @@
+// Persisted filter UI state, namespaced per bank.
+// Framework-owned: eject with `qb reveal framework/lib/question-filter-store.ts`.
+
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import {
+  defaultOperatorByType,
+  filterFieldType,
+  type FilterField,
+  type FilterMatch,
+  type FilterOperatorId,
+  type FilterRule,
+} from './question-filter.ts';
+
+type QuestionFilterValues = {
+  search: string;
+  filters: FilterRule[];
+  filterMatch: FilterMatch;
+};
+
+type QuestionFilterActions = {
+  setSearch: (search: string) => void;
+  addFilter: (field: string, operator?: FilterOperatorId) => void;
+  updateFilter: (id: string, patch: Partial<Omit<FilterRule, 'id'>>) => void;
+  removeFilter: (id: string) => void;
+  clearFilters: () => void;
+  setFilterMatch: (match: FilterMatch) => void;
+};
+
+type QuestionFilterStore = QuestionFilterValues & QuestionFilterActions;
+
+let filterIdCounter = 0;
+
+const createFilterId = () => {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  filterIdCounter += 1;
+  return `filter-${Date.now()}-${filterIdCounter}`;
+};
+
+/**
+ * The store is created per bank namespace so two banks in one origin don't
+ * share filter state. Call once per app (e.g. in your BankProvider setup).
+ */
+export function createQuestionFilterStore(namespace: string, fields: readonly FilterField[]) {
+  return create<QuestionFilterStore>()(
+    persist(
+      (set) => ({
+        search: '',
+        filters: [],
+        filterMatch: 'and',
+        setSearch: (search) => set({ search }),
+        addFilter: (field, operator) =>
+          set((state) => ({
+            filters: [
+              ...state.filters,
+              {
+                id: createFilterId(),
+                field,
+                operator: operator ?? defaultOperatorByType[filterFieldType(fields, field)],
+                value: [],
+              },
+            ],
+          })),
+        updateFilter: (id, patch) =>
+          set((state) => ({
+            filters: state.filters.map((rule) => (rule.id === id ? { ...rule, ...patch } : rule)),
+          })),
+        removeFilter: (id) =>
+          set((state) => ({
+            filters: state.filters.filter((rule) => rule.id !== id),
+          })),
+        clearFilters: () => set({ filters: [] }),
+        setFilterMatch: (filterMatch) => set({ filterMatch }),
+      }),
+      {
+        name: `${namespace}-question-bank-filters`,
+        version: 2,
+        skipHydration: true,
+        partialize: ({ search, filters, filterMatch }) => ({ search, filters, filterMatch }),
+      },
+    ),
+  );
+}
+
+/** Default singleton for single-bank apps. Create via `createQuestionFilterStore` for multi-bank. */
+export const useQuestionFilterStore = create<QuestionFilterStore>()(
+  persist(
+    (set) => ({
+      search: '',
+      filters: [],
+      filterMatch: 'and' as FilterMatch,
+      setSearch: (search: string) => set({ search }),
+      addFilter: (field: string, operator?: FilterOperatorId) =>
+        set((state) => ({
+          filters: [...state.filters, { id: createFilterId(), field, operator: operator ?? 'contains', value: [] }],
+        })),
+      updateFilter: (id: string, patch: Partial<Omit<FilterRule, 'id'>>) =>
+        set((state) => ({
+          filters: state.filters.map((rule) => (rule.id === id ? { ...rule, ...patch } : rule)),
+        })),
+      removeFilter: (id: string) =>
+        set((state) => ({
+          filters: state.filters.filter((rule) => rule.id !== id),
+        })),
+      clearFilters: () => set({ filters: [] }),
+      setFilterMatch: (filterMatch: FilterMatch) => set({ filterMatch }),
+    }),
+    {
+      name: 'question-bank-filters',
+      version: 2,
+      skipHydration: true,
+      partialize: ({ search, filters, filterMatch }) => ({ search, filters, filterMatch }),
+    },
+  ),
+);