Merge pull request #132 from QuackbackIO/feat/help-center-category-hierarchy

Help center: category hierarchy, inline portal, full-page editor, admin polish

Author: mortondev

apps/web/src/components/admin/help-center/category-form-dialog.tsx

@@ -1,4 +1,5 @@
-import { useState, useEffect } from 'react'
+import { useState, useEffect, useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
 import {
   Dialog,
   DialogContent,
@@ -8,11 +9,25 @@ import {
   DialogTitle,
 } from '@/components/ui/dialog'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Switch } from '@/components/ui/switch'
 import { useCreateCategory, useUpdateCategory } from '@/lib/client/mutations/help-center'
+import { helpCenterQueries } from '@/lib/client/queries/help-center'
+import {
+  MAX_CATEGORY_DEPTH,
+  collectDescendantIdsIncludingSelf,
+  getCategoryDepth,
+  getSubtreeMaxDepth,
+} from '@/lib/server/domains/help-center/category-tree'
 import type { HelpCenterCategoryId } from '@quackback/ids'
 
 const CATEGORY_EMOJIS = [
@@ -77,14 +92,18 @@ interface CategoryFormDialogProps {
     description: string | null
     icon: string | null
     isPublic: boolean
+    parentId: HelpCenterCategoryId | null
   }
+  /** Pre-selected parent when creating a new category (ignored if initialValues is set). */
+  defaultParentId?: HelpCenterCategoryId | null
   onCreated?: (categoryId: string) => void
 }
 
 export function CategoryFormDialog({
   open,
   onOpenChange,
   initialValues,
+  defaultParentId,
   onCreated,
 }: CategoryFormDialogProps) {
   const isEdit = !!initialValues
@@ -95,6 +114,7 @@ export function CategoryFormDialog({
   const [name, setName] = useState('')
   const [description, setDescription] = useState('')
   const [isPublic, setIsPublic] = useState(true)
+  const [parentId, setParentId] = useState<HelpCenterCategoryId | null>(null)
   const [emojiOpen, setEmojiOpen] = useState(false)
 
   useEffect(() => {
@@ -103,8 +123,43 @@ export function CategoryFormDialog({
       setName(initialValues?.name || '')
       setDescription(initialValues?.description || '')
       setIsPublic(initialValues?.isPublic ?? true)
+      setParentId(initialValues?.parentId ?? defaultParentId ?? null)
+    }
+  }, [open, initialValues, defaultParentId])
+
+  const { data: allCategories = [] } = useQuery({
+    ...helpCenterQueries.categories(),
+    enabled: open,
+  })
+
+  const eligibleParents = useMemo(() => {
+    const flat = allCategories as Array<{
+      id: string
+      parentId: string | null
+      name: string
+      icon: string | null
+      articleCount: number
+    }>
+
+    // Exclude self + descendants of self (cycle / self-parent)
+    const excluded = new Set<string>()
+    if (initialValues?.id) {
+      for (const ex of collectDescendantIdsIncludingSelf(flat, initialValues.id)) {
+        excluded.add(ex)
+      }
     }
-  }, [open, initialValues])
+
+    // Compute the editing category's subtree height (0 for a new category)
+    const subtreeHeight = initialValues?.id ? getSubtreeMaxDepth(flat, initialValues.id) : 0
+
+    return flat.filter((cat) => {
+      if (excluded.has(cat.id)) return false
+      const parentDepth = getCategoryDepth(flat, cat.id)
+      // New depth = parentDepth + 1; deepest leaf after placement = that + subtreeHeight
+      // Depths are 0-indexed with cap MAX_CATEGORY_DEPTH, so max depth index is MAX - 1
+      return parentDepth + 1 + subtreeHeight <= MAX_CATEGORY_DEPTH - 1
+    })
+  }, [allCategories, initialValues?.id])
 
   const isPending = createCategory.isPending || updateCategory.isPending
 
@@ -121,13 +176,15 @@ export function CategoryFormDialog({
         description: trimmedDesc || null,
         icon,
         isPublic,
+        parentId,
       })
     } else {
       const result = await createCategory.mutateAsync({
         name: trimmedName,
         description: trimmedDesc || undefined,
         icon,
         isPublic,
+        parentId,
       })
       onCreated?.(result.id)
     }
@@ -196,6 +253,31 @@ export function CategoryFormDialog({
             />
           </div>
 
+          <div className="space-y-2">
+            <Label htmlFor="category-parent">Parent category</Label>
+            <Select
+              value={parentId ?? '__none__'}
+              onValueChange={(value) =>
+                setParentId(value === '__none__' ? null : (value as HelpCenterCategoryId))
+              }
+            >
+              <SelectTrigger id="category-parent">
+                <SelectValue placeholder="No parent (top-level)" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="__none__">No parent (top-level)</SelectItem>
+                {eligibleParents.map((cat) => (
+                  <SelectItem key={cat.id} value={cat.id}>
+                    {cat.icon ?? '📁'} {cat.name}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <p className="text-xs text-muted-foreground">
+              Maximum depth is {MAX_CATEGORY_DEPTH} levels. Parents that would exceed it are hidden.
+            </p>
+          </div>
+
           <div className="flex items-center justify-between">
             <div>
               <Label>Public</Label>

apps/web/src/components/admin/help-center/create-article-dialog.tsx

@@ -1,4 +1,5 @@
 import { useState, useCallback } from 'react'
+import { useNavigate } from '@tanstack/react-router'
 import { useKeyboardSubmit } from '@/lib/client/hooks/use-keyboard-submit'
 import { ModalFooter } from '@/components/shared/modal-footer'
 import { useForm } from 'react-hook-form'
@@ -18,12 +19,24 @@ import {
 } from './help-center-metadata-sidebar'
 import type { JSONContent } from '@tiptap/react'
 
-export function CreateArticleDialog() {
-  const [open, setOpen] = useState(false)
+interface CreateArticleDialogProps {
+  /** Controlled open state. When provided, the built-in trigger button is hidden. */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+export function CreateArticleDialog({
+  open: openProp,
+  onOpenChange,
+}: CreateArticleDialogProps = {}) {
+  const [internalOpen, setInternalOpen] = useState(false)
+  const isControlled = openProp !== undefined
+  const open = isControlled ? openProp : internalOpen
   const [contentJson, setContentJson] = useState<JSONContent | null>(null)
   const [categoryId, setCategoryId] = useState('')
   const [mobileSettingsOpen, setMobileSettingsOpen] = useState(false)
   const createArticleMutation = useCreateArticle()
+  const navigate = useNavigate()
 
   const form = useForm({
     resolver: standardSchemaResolver(createArticleSchema),
@@ -59,18 +72,26 @@ export function CreateArticleDialog() {
         contentJson: contentJson as TiptapContent | null,
       },
       {
-        onSuccess: () => {
-          setOpen(false)
+        onSuccess: (newArticle) => {
+          handleOpenChange(false)
           form.reset()
           setContentJson(null)
           setCategoryId('')
+          void navigate({
+            to: '/admin/help-center/articles/$articleId',
+            params: { articleId: newArticle.id as string },
+          })
         },
       }
     )
   })
 
   function handleOpenChange(isOpen: boolean) {
-    setOpen(isOpen)
+    if (isControlled) {
+      onOpenChange?.(isOpen)
+    } else {
+      setInternalOpen(isOpen)
+    }
     if (!isOpen) {
       form.reset()
       setContentJson(null)
@@ -83,12 +104,14 @@ export function CreateArticleDialog() {
 
   return (
     <Dialog open={open} onOpenChange={handleOpenChange}>
-      <DialogTrigger asChild>
-        <Button size="sm">
-          <PlusIcon className="h-4 w-4 mr-1.5" />
-          New Article
-        </Button>
-      </DialogTrigger>
+      {!isControlled && (
+        <DialogTrigger asChild>
+          <Button size="sm">
+            <PlusIcon className="h-4 w-4 mr-1.5" />
+            New Article
+          </Button>
+        </DialogTrigger>
+      )}
       <DialogContent
         className="w-[95vw] sm:w-[90vw] lg:max-w-5xl xl:max-w-6xl h-[85vh] p-0 gap-0 overflow-hidden flex flex-col"
         onKeyDown={handleKeyDown}
@@ -119,7 +142,7 @@ export function CreateArticleDialog() {
             </div>
 
             <ModalFooter
-              onCancel={() => setOpen(false)}
+              onCancel={() => handleOpenChange(false)}
               submitLabel={createArticleMutation.isPending ? 'Saving...' : 'Save Draft'}
               isPending={createArticleMutation.isPending}
             >

apps/web/src/components/admin/help-center/help-center-active-filters-bar.tsx

@@ -0,0 +1,91 @@
+import { XMarkIcon } from '@heroicons/react/16/solid'
+import { useQuery } from '@tanstack/react-query'
+import { cn } from '@/lib/shared/utils'
+import { helpCenterQueries } from '@/lib/client/queries/help-center'
+import type { HelpCenterStatusFilter } from './use-help-center-filters'
+
+interface HelpCenterActiveFiltersBarProps {
+  status: HelpCenterStatusFilter
+  category?: string
+  showDeleted?: boolean
+  onClearStatus: () => void
+  onClearCategory: () => void
+  onClearShowDeleted: () => void
+  onClearAll: () => void
+}
+
+interface Chip {
+  key: string
+  label: string
+  onRemove: () => void
+}
+
+export function HelpCenterActiveFiltersBar({
+  status,
+  category,
+  showDeleted,
+  onClearStatus,
+  onClearCategory,
+  onClearShowDeleted,
+  onClearAll,
+}: HelpCenterActiveFiltersBarProps) {
+  const { data: categories } = useQuery(helpCenterQueries.categories())
+  const categoryName = category
+    ? (categories?.find((c) => c.id === category)?.name ?? 'Category')
+    : null
+
+  const chips: Chip[] = []
+
+  if (status && status !== 'all') {
+    chips.push({
+      key: 'status',
+      label: `Status: ${status === 'draft' ? 'Draft' : 'Published'}`,
+      onRemove: onClearStatus,
+    })
+  }
+  if (categoryName) {
+    chips.push({
+      key: 'category',
+      label: `Category: ${categoryName}`,
+      onRemove: onClearCategory,
+    })
+  }
+  if (showDeleted) {
+    chips.push({
+      key: 'deleted',
+      label: 'Showing deleted',
+      onRemove: onClearShowDeleted,
+    })
+  }
+
+  if (chips.length === 0) return null
+
+  return (
+    <div className="mt-2 flex flex-wrap items-center gap-1.5">
+      {chips.map((chip) => (
+        <button
+          key={chip.key}
+          type="button"
+          onClick={chip.onRemove}
+          className={cn(
+            'group inline-flex items-center gap-1 rounded-full px-2 py-0.5',
+            'bg-muted text-xs text-foreground/80',
+            'hover:bg-muted/70 transition-colors'
+          )}
+        >
+          <span>{chip.label}</span>
+          <XMarkIcon className="h-3 w-3 text-muted-foreground group-hover:text-foreground" />
+        </button>
+      ))}
+      {chips.length > 1 && (
+        <button
+          type="button"
+          onClick={onClearAll}
+          className="ml-1 text-xs text-muted-foreground hover:text-foreground underline underline-offset-2"
+        >
+          Clear all
+        </button>
+      )}
+    </div>
+  )
+}