docs(dashboards): document the user-attribute default on the time granularity switcher

[mngr]

What

The Controls page documents the User attribute default setting for filters, field switchers and parent controls. The Time granularity switcher section stopped at the static default — the switcher now takes a per-viewer default too (cubedevinc/cubejs-enterprise#14627), so one dashboard can open daily for the operations team and monthly for the executives reading the same charts.

What's added

A User attribute default section under Time granularity switcher, matching the shape of the three that already exist, and covering the parts that differ:

• the value is matched against the granularity names (week, Month), not the localized labels the control renders — so one tenant-wide attribute resolves the same for viewers in every language;
• a value outside the switcher's allowed granularities is ignored rather than forced, falling back to the default granularity;
• where the attribute sits in the precedence order: a URL parameter and the viewer's own pick outrank it, and a parent control's mapping decides the granularity when one drives the switcher.

Plus the three cross-references that list which controls support the setting, and the "never a personalized default" bullet under Sharing the current selection — an attribute-resolved granularity stays out of the shared link, exactly as an attribute-resolved filter value does.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Sep 1, 2026, 6:18 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @mngr's task in 1m 58s —— View job

---

Docs-only change, well-integrated — 0 high, 1 medium, 2 low, all posted inline

Full review

• Read the diff
• Verify anchors and cross-references resolve
• Check consistency with the sibling user-attribute-default sections
• Check Mintlify component/frontmatter conventions
• Post review

Scope

One file, docs-mintlify/docs/explore-analyze/dashboards/widgets/controls.mdx (+38/−3). Correct site per CLAUDE.md — the legacy /docs tree is untouched. No new page, so no docs.json change is needed; this extends an existing page, which is what the docs guidelines ask for.

What's right

• Anchors all resolve. #allowed-granularities (L87), #default-granularity (L95), #visibility (L318), #parent (L196), #children (L216), #sharing-the-current-selection (L293) and the three {#...-user-attribute-default} ids all exist. The explicit id avoids the collision that four identically-titled "User attribute default" headings would otherwise produce; #default-granularity also doesn't collide with ### Default granularity per option (L160). [ref-user-attributes] is defined at L382.
• Cross-references updated in all directions. L40 (filter bullet), L172 (field switcher) and L311 (sharing) now name the time granularity switcher, so no section claims a support list that excludes it.
• Section shape matches its siblings — intro, motivating example, <Steps>, attribute-type table, fallback paragraph, <Note>, precedence paragraph. A reader who has read the parent control's version will find this one exactly where they expect.
• The precedence ordering (URL > viewer's pick > attribute > default granularity) is consistent with the equivalent claims at L73, L176 and L291, and with the sharing bullets at L310–L311.

Findings

#	Severity	Location	Issue
1	Medium	L132	Parent-control clause is unconditional, but the Children table defines a Left empty state where the parent leaves the child alone — on a partly-driven switcher the attribute should still seed it.
2	Low	L119	Sentence enumerates the full built-in granularity set as the match target; the table row and L126 both scope matching to the switcher's allowed granularities.
3	Low	L99	"The default above is one granularity for everyone" is borrowed from the parent's ####-under-### section; here it's a ### sibling, so "above" points at a peer. Judgment call — both shapes already exist in the file.

Not applicable

No code, tests, queries, or auth logic in this diff — the security, performance and test-coverage passes have nothing to bite on. The behavioral claims (case-insensitive matching, array-first-match, out-of-range values ignored rather than forced) originate in cubedevinc/cubejs-enterprise#14627 and can't be verified against this repo; they read as internally consistent, but someone with access to that PR should confirm the matching semantics and the "Below Visibility" placement in step 2.

Verification

No prior review threads on this PR, so nothing to resolve or deduplicate against. Prose-only change — no build or lint run; yarn dev in docs-mintlify would be the check if you want to eyeball the rendered <Steps> and tables.

· [`docs/time-granularity-user-attribute-default`](https://github.com/cube-js/cube/tree/docs/time-granularity-user-attribute-default)

[claude]

Claude finished @mngr's task in 1m 3s —— View job

---

All 3 prior findings addressed — 0 high, 0 medium, 1 low (new Reset to default claim, posted inline)

Full review

• Re-read the diff after the new commit
• Check prior review threads, resolve stale ones
• Verify anchors and cross-references still resolve
• Review the newly added claims
• Post review

What changed since the last round

Commit 73eb6c5 addresses all three findings from the previous review:

Prior finding	Resolution
Medium — unconditional parent-control clause	Scoped to options that map a granularity, plus an explicit clause for Left empty (attribute still seeds) and for Reset to default
Low — enumeration implied the full built-in set	Now "the granularity names the switcher allows"
Low — ### sibling made "the default above" point at a peer	Now #### User attribute default nested under ### Default granularity, matching the filter's and parent's shape

All three threads were mine, outdated, and genuinely addressed — resolved them. No human reviewer threads exist on this PR, so nothing was touched there.

Two things also improved unprompted: the <Steps> now carry title attributes (the sibling sections' steps do too), and the field-switcher/sharing cross-references were kept in sync with the new anchor.

Anchors re-verified

Every target in the new section resolves against the current file: #allowed-granularities (L87), #default-granularity (L95, no collision with ### Default granularity per option at L160), #visibility (L318), #parent (L196), #children (L216), #sharing-the-current-selection (L293), and the three explicit {#…-user-attribute-default} ids. [ref-user-attributes] is still defined. The heading-level change didn't break anything because the anchor is explicit.

Remaining finding

#	Severity	Location	Issue
1	Low	L132	The new Reset to default clause asserts the switcher goes to the static default granularity rather than re-resolving the attribute. The Children table says only "cleared back to its own default", which doesn't disambiguate the two readings for a viewer who has an attribute. Posted inline — worth a check against the enterprise PR, or dropping the clause.

Not applicable

Docs-only, prose-only. No code, tests, queries, or auth logic — the security, performance and test-coverage passes have nothing to bite on. The behavioral claims (case-insensitive matching, array-first-match, out-of-range values ignored, the "Below Visibility" placement) originate in cubedevinc/cubejs-enterprise#14627 and can't be verified from this repo; they read as internally consistent. Correct site per CLAUDE.md — the legacy /docs tree is untouched, and no docs.json change is needed since this extends an existing page.

No build or lint run; yarn dev in docs-mintlify is the check if you want to eyeball the rendered <Steps> and tables.

· [`docs/time-granularity-user-attribute-default`](https://github.com/cube-js/cube/tree/docs/time-granularity-user-attribute-default)

[claude]

Claude finished @mngr's task in 54s —— View job

---

Clean — all four prior findings resolved, no new issues (0 high, 0 medium, 0 low)

Full review

• Read the new commit's diff
• Check prior review threads
• Verify anchors and cross-references
• Post review

What changed since the last round

dc822c2 is a one-line edit to the precedence paragraph (L132), and it closes the only remaining finding — the ambiguous Reset to default claim:

-one set to **Reset to default** sends the switcher to the [default granularity](#default-granularity) saved on it, not to the viewer's attribute.
+one set to **Reset to default** sends the switcher to the [default granularity](#default-granularity) saved on it rather than re-resolving the attribute, and leaves the switcher untouched when no default granularity was saved.

Two things make this the right resolution rather than a reword:

• The claim is now verified rather than asserted — the commit message names resolveParentApplications resolving a TIME_GRAIN reset to the child's saved defaultGrain without consulting userAttributeName, with both branches pinned by tests in parent-widget.spec.ts. That's exactly what the last round asked for, and it picks the reading the docs had already guessed.
• It adds the third branch the previous wording silently omitted: when no default granularity is saved, the reset skips the child and the attribute-resolved value survives. A reader configuring a parent over an attribute-seeded switcher now has all three outcomes (maps a granularity / left empty / reset, with and without a saved default) stated, which is more than the Children table's "cleared back to its own default" conveys on its own.

Cumulative state of the four findings

Round	Finding	Resolution
1	Medium — unconditional parent-control clause	Scoped to options that map a granularity, with Left empty called out separately
1	Low — enumeration implied the full built-in set	Now "the granularity names the switcher allows"
1	Low — ### sibling made "the default above" point at a peer	Now #### User attribute default under ### Default granularity (L99), matching the filter's (L44) and parent's (L254) shape
2	Low — Reset to default claim not settled by the page	Verified against resolveParentApplications, plus the no-saved-default branch

All four threads were mine and are already resolved and outdated — nothing left to resolve, and no human reviewer threads exist on this PR.

Anchors re-verified against the current file

#allowed-granularities (L87), #default-granularity (L95 — still no collision with ### Default granularity per option at L160), #visibility (L318), #parent (L196), #children (L216), #sharing-the-current-selection (L293), the three explicit {#…-user-attribute-default} ids (L99, L170, L254), and [ref-user-attributes] (L382). The <Steps> carry title attributes as the sibling sections' do.

Not applicable

Docs-only, prose-only, single file, correct site per CLAUDE.md — the legacy /docs tree is untouched and no docs.json change is needed since this extends an existing page. No code, tests, queries, or auth logic, so the security, performance, test-coverage and comment-hygiene passes have nothing to bite on.

No build or lint run here; yarn dev in docs-mintlify is the check if you want to eyeball the rendered <Steps> and tables before merge. The remaining unverifiable-from-this-repo claims (case-insensitive matching, array first-match, out-of-range values ignored, the "Below Visibility" placement) come from cubedevinc/cubejs-enterprise#14627 and read as internally consistent.

· [`docs/time-granularity-user-attribute-default`](https://github.com/cube-js/cube/tree/docs/time-granularity-user-attribute-default)