nextcloud / nextcloud/office

Document composables as an established pattern in AGENTS.md, once #134 proves the model

Open Beginner friendly
#139 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

0. Needs triage documentation
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
  1. #134's PR 1 lands: the scroll-arrows extraction as proof of concept.
  2. #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).
  3. 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/core already have it? (Verified during #134's scoping that useScroll covers 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.