Document composables as an established pattern in AGENTS.md, once #134 proves the model
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6
- Forks
- 1
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 10
Description
TL;DR: Once both PRs in #134 have landed — the scroll-arrows proof of concept, then the deliberate extension to the rest — and the model has held up in practice, write it into AGENTS.md as an established pattern — including a reuse ladder specific to composables. Kept as its own issue rather than folded into #134, so #134 stays scoped to the code work and doesn't become two concerns at once.
Detail
Sequence
- #134's PR 1 lands: the scroll-arrows extraction as proof of concept.
- #134's PR 2 lands: deliberately extended as the model across the other identified clusters (create-from-template dialog, view-mode toggle, active-creator/routing sync).
- Once that's done and the shape feels right in practice — not guessed at in advance — this issue's work begins.
What to write, once there's real code to point at
Most of the conventions should be a light pointer, not a prescriptive block — matching how AGENTS.md already handles this (e.g. "see TemplateSection.vue" for the onUnmounted cleanup pattern, rather than re-explaining the pattern in prose). Once 3-4 real composables exist in src/composables/, most of their shape is self-teaching by example: return individual refs (not a reactive() object), use the shared lifecycle test helper for composables with onMounted/onUnmounted.
One thing does need an explicit line rather than a pointer, because it's a process step invisible in the finished code: a reuse ladder specific to composables, extending AGENTS.md's existing "Reuse before you write" ladder (currently OCP → @nextcloud/* packages → @nextcloud/vue components/tokens → existing src/ patterns) with a new rung —
- Before writing a new composable: can an existing composable in
src/composables/be extended to cover it? - If not, does
@vueuse/corealready have it? (Verified during #134's scoping thatuseScrollcovers the scroll-arrows case exactly — this is a real, not hypothetical, first hit.) - Only then write a new one.
That's a genuine trade-off analysis a reader can't infer just by reading the resulting code, so it earns its own line rather than relying on the code to teach it.
Related
- #134 — the code work this documents. Do not merge this issue's scope into that one.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Wait for both PRs in #134 to land, then inspect AGENTS.md and the resulting examples in src/composables/, including the shared lifecycle test helper guidance. Update AGENTS.md with pointers to the established composable patterns and add the composable-specific reuse ladder; the work is done when the conventions and decision process are documented against real examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 62/100