feat(builder): advertise the format-token autocomplete - #1570
Merged
Conversation
Closes #1542. Typing `{{` in a format field opens a list of every token, each with a one-line description (shipped in #1549). Nothing in the UI said so - the reporter only found it by typing `{{` on a hunch while looking for the syntax. Ask 1 of #1542 was deliberately left open because its two natural homes belonged to #1541 (docs links in the UI) and #1544 (a worked-example placeholder); both have shipped, and #1541 explicitly left "docs links inside the builders" here. The affordance is two characters, so the honest fix is to name the two characters, right below the caret: Type {{ to insert a token · Format syntax "Format syntax" is the docs entry point #1541 deferred: the token language is the one part of the builder you cannot work out by looking at it. The hint hides once the value contains `{{`. It has done its job, and a line that never goes away is the permanent chrome an "Insert token" button was rejected for. On three of the five token-autocomplete fields: Capture format, File name format, and Capture to - the only one a brand-new Capture builder renders, since the other two sit behind default-off toggles. Deliberately NOT on insert-after / insert-before: their own descriptions tell you to type a literal heading like `## Tasks`, so a token-less value is the documented normal state there and the hint would nag forever. Also considered and rejected: - Triggering the popup on a single `{`, which would make `{` + Enter insert a token instead of a newline in a capture format holding JSON or code. - Opening the list on focus: fires on every builder open, and races the file suggester on "Capture to". - Persisting a `hasUsedTokenAutocomplete` setting. Settings mutations rewrite the whole data.json, so the suggester would write to disk on a keystroke; no Svelte component subscribes to the store, so it would not be reactive; settings are per-vault, so "user lifetime" is false; and one stray `{{` would delete the affordance vault-wide with no way back. - Teaching via the placeholder alone: it vanishes on the first keystroke and on every existing choice, and cannot carry the docs link.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughFormat token guidance was added to three choice-builder fields through a reusable Svelte component. The component links to format syntax documentation, hides after token insertion, and is covered by tests and modal-specific styling. ChangesFormat token guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Sequence Diagram(s)sequenceDiagram
participant User
participant ChoiceBuilder
participant FormatTokenHint
participant FormatSyntaxDocs
User->>ChoiceBuilder: Enter a format value
ChoiceBuilder->>FormatTokenHint: Pass the current value
FormatTokenHint->>FormatTokenHint: Check for {{
FormatTokenHint->>FormatSyntaxDocs: Open format syntax link
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying quickadd with
|
| Latest commit: |
6665d44
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6e1a579e.quickadd.pages.dev |
| Branch Preview URL: | https://chhoumann-1542-advertise-tok.quickadd.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1542. Supersedes #1561, which GitHub closed permanently when its base
branch (#1560) was merged and deleted — same commit, rebased onto master.
The problem
Typing
{{in a format field opens a list of every token, each with a one-linedescription (that part shipped in #1549). Nothing in the UI said so. The reporter
found it by typing
{{on a hunch while looking for the syntax; a new user hasno reason to try that, and no other in-app way to learn which tokens exist.
Ask 1 was deliberately left out of #1549 because its two natural homes belonged
to siblings from the same walkthrough: #1541 (docs links in the UI) and #1544 (a
worked-example placeholder). Both have now shipped, and #1541 explicitly left
"docs links inside the builders" to this issue. So this closes #1542.
The change
The affordance is two characters, so the honest fix is to name the two
characters, right below the caret:
"Format syntax" is the docs entry point #1541 deferred here: the token language
is the one part of the builder you cannot work out by looking at it.
Decisions worth arguing with
It hides once the value contains
{{. The hint has done its job, and a linethat never goes away is exactly the permanent chrome an "Insert token" button
was rejected for in the issue thread. Stateless — no setting, no migration.
Three of the five token fields, not all five. Capture format, File name
format, and Capture to — the last being the only format field a brand-new
Capture builder renders, since the other two sit behind default-off toggles.
Deliberately not on insert-after / insert-before: their own descriptions tell
you to type a literal heading like
## Tasks, so a token-less value is thedocumented normal state there and the hint would nag forever. Not on the template
path field either — it has no token autocomplete at all.
Not a persisted "you've seen this" flag. It was the obvious alternative and
it is worse in four ways:
settingsStoremutations rewrite the wholedata.json, so the suggester would write to disk on a keystroke; no Sveltecomponent subscribes to the store, so the flag would not be reactive and the
hint would linger until the builder was reopened; settings are per-vault, so
"user lifetime" is false; and one stray
{{would delete the affordancevault-wide with no way to bring it back.
Not the placeholder alone. It vanishes on the first keystroke and on every
existing choice, and cannot carry the docs link. #1544 already shipped that
pattern on "Capture to" without closing this ask.
Not
{as the trigger, and not open-on-focus. Both were rejected in theissue thread:
{+ Enter would insert a token instead of a newline in a captureformat holding JSON or code, and open-on-focus fires on every builder open and
races the file suggester on "Capture to".
Validation
5e18213e(master, post-fix(builder): make the live format preview inert #1560/fix(ui): call folders folders, and match Obsidian's sentence case in settings #1562/fix: show empty folders as a dead end before the click, not after it #1569). Cherry-picked clean —the only overlap with the merged preview work was
styles.css, and the twoblocks are adjacent, not conflicting.
pnpm run build,pnpm lint,tsc --noEmit, full suite: 4068 passed, 0 failed.rel/target, hide-on-{{,show-again-when-tokens-removed).
of merged master, not just in tests:
{{DATE}}into the format field drops it to 1; clearing back to plaintext restores it to 2
{{VALUE:title|case:pasc}}produces 0 Notices, one inline diagnostic, and the visually-hidden
"Warning: "severity is still in the DOMSummary by CodeRabbit
New Features
Documentation
Tests