noob-components/.trellis/tasks/archive/2026-03/03-24-plugs-composables-spec/prd.md

Fill plugs/composables spec

Goal

Analyze the plugs/composables/ directory and fill the coding spec with real code patterns, examples, and anti-patterns from the actual codebase.

Context

Project Overview

• Type: Vue 3 Component Library (Element Plus based)
• Framework: Vue 3 + TypeScript + Vite
• Key Patterns: Composables, API Layer, Store Pattern, Element UI Wrappers

Architecture

This is a Vue 3 component library built on Element Plus. The plugs/composables/ directory contains reusable Vue composition API functions that encapsulate complex stateful logic.

Key Composables (from GitNexus analysis)

Composable	File	Purpose
useListTable	plugs/composables/useListTable.ts	List/table management with pagination
useModifyForm	plugs/composables/useModifyForm.ts	Form open/edit/add flow
useLoading	plugs/composables/useLoading.ts	Loading state management
useActionPers	plugs/composables/useActionPers.ts	Action permissions
useRefreshFlags	plugs/composables/useRefreshFlags.ts	Refresh flag management for auto-refresh
useSysDict	plugs/composables/useSysDict.ts	System dictionary
useWatchOnce	plugs/composables/useWatchOnce.ts	One-time watch utility

Execution Flows (from GitNexus)

• OpenAdd → NormalizeValue → ClearObject (useModifyForm flow)
• OpenEdit → NormalizeValue → ClearObject (useModifyForm flow)
• DeleteById → Loading → Close (CRUD flow)

Tools Available

You have two MCP servers configured — use both for accurate specs:

GitNexus MCP (architecture-level: clusters, execution flows, impact)

Tool	Purpose	Example
gitnexus_query	Find execution flows by concept	gitnexus_query({query: "useListTable"})
gitnexus_context	360-degree symbol view	gitnexus_context({name: "useListTable"})
gitnexus_impact	Blast radius analysis	gitnexus_impact({target: "useListTable", direction: "upstream"})
gitnexus_cypher	Direct graph queries	gitnexus_cypher({query: "MATCH (f:Function) WHERE f.name STARTS WITH 'use' RETURN f.name, f.filePath"})

ABCoder MCP (symbol-level: AST nodes, signatures, cross-file deps)

Tool	Purpose	Example
get_repo_structure	Full file listing	get_repo_structure({repo_name: "noob-components"})
get_file_structure	All nodes in a file	get_file_structure({repo_name: "noob-components", file_path: "plugs/composables/useListTable.ts"})
get_ast_node	Code + deps + refs	get_ast_node({repo_name: "noob-components", node_ids: [...]})

Recommended Workflow

1. GitNexus first — find relevant execution flows and clusters
2. ABCoder second — get exact code patterns and signatures
3. Read source files — for full context where needed
4. Write specs — with real code examples from steps 2-3

Files to Fill

Primary files to analyze and document:

1. plugs/composables/useListTable.ts - Main list/table composable

   • Pagination handling
   • Table data management
   • Search/filter integration

2. plugs/composables/useModifyForm.ts - Form manipulation

   • OpenAdd, OpenEdit, ClearObject flow
   • Form state normalization
   • Props interface: FormProp, Options

3. plugs/composables/useLoading.ts - Loading state

   • Simple boolean toggle
   • Async operation wrapping

4. plugs/composables/useRefreshFlags.ts - Auto-refresh flags

   • Flag-based refresh triggers
   • Timer management

5. plugs/composables/useActionPers.ts - Action permissions

   • Permission checking integration

6. plugs/composables/useSysDict.ts - System dictionary

   • Dictionary data fetching

7. plugs/composables/useWatchOnce.ts - One-time watcher

   • Watch logic that auto-unmonuts

Supporting files:

• plugs/composables/index.ts - Public exports

Important Rules

Spec files are NOT fixed — adapt to reality

• Delete template files that don't apply
• Create new files for patterns templates don't cover
• Rename files if template names don't fit
• Update index.md to reflect the final set

Parallel agents — stay in your lane

• ONLY modify files under your assigned spec directory
• DO NOT modify source code, other spec directories, or task files
• DO NOT run git commands
• You may read any file for analysis

Acceptance Criteria

• Real code examples from the actual codebase (with file paths)
• Each composable has documented: purpose, signature, usage pattern
• Anti-patterns documented (if any found)
• No placeholder text remaining
• index.md reflects actual file set

Technical Notes

• Language: TypeScript
• Framework: Vue 3 Composition API
• Related: Element Plus, VueUse patterns
• Imports often from: plugs/http/axios, plugs/element/message, plugs/api/*