Fix docs crash when navigating with hotkeys #6861

evansjohnson · 2024-06-24T18:40:55Z

Fixes #6381

Checklist

[n/a] Includes tests
[n/a] Update documentation

Changes proposed in this pull request:

Ignore non-navigational headers so that navigating with hotkeys does not crash the page, and users cannot get to a page with no useful info.

Reviewers should focus on:

Unintended changes
Any ideas on improving the targeting of non-navigational headers

Also considered

Allowing these headers to be navigated to, but you end up on a useless page

Screenshot

Current:

This PR:

changelog-app · 2024-06-24T18:41:00Z

Generate changelog in `packages/docs-app/changelog/@unreleased`

What do the change types mean?

feature: A new feature of the service.
improvement: An incremental improvement in the functionality or operation of the service.
fix: Remedies the incorrect behaviour of a component of the service in a backwards-compatible way.
break: Has the potential to break consumers of this service's API, inclusive of both Palantir services
and external consumers of the service's API (e.g. customer-written software or integrations).
deprecation: Advertises the intention to remove service functionality without any change to the
operation of the service itself.
manualTask: Requires the possibility of manual intervention (running a script, eyeballing configuration,
performing database surgery, ...) at the time of upgrade for it to succeed.
migration: A fully automatic upgrade migration task with no engineer input required.

Note: only one type should be chosen.

How are new versions calculated?

❗The break and manual task changelog types will result in a major release!
🐛 The fix changelog type will result in a minor release in most cases, and a patch release version for patch branches. This behaviour is configurable in autorelease.
✨ All others will result in a minor version release.

Type

Description

Fix docs crash when navigating with hotkeys

Generate changelog in `packages/docs-theme/changelog/@unreleased`

What do the change types mean?

feature: A new feature of the service.
improvement: An incremental improvement in the functionality or operation of the service.
fix: Remedies the incorrect behaviour of a component of the service in a backwards-compatible way.
break: Has the potential to break consumers of this service's API, inclusive of both Palantir services
and external consumers of the service's API (e.g. customer-written software or integrations).
deprecation: Advertises the intention to remove service functionality without any change to the
operation of the service itself.
manualTask: Requires the possibility of manual intervention (running a script, eyeballing configuration,
performing database surgery, ...) at the time of upgrade for it to succeed.
migration: A fully automatic upgrade migration task with no engineer input required.

Note: only one type should be chosen.

How are new versions calculated?

❗The break and manual task changelog types will result in a major release!
🐛 The fix changelog type will result in a minor release in most cases, and a patch release version for patch branches. This behaviour is configurable in autorelease.
✨ All others will result in a minor version release.

Type

Description

Fix docs crash when navigating with hotkeys

Check the box to generate changelog(s)

Generate changelog entry

evansjohnson · 2024-06-24T18:41:36Z

packages/docs-theme/src/components/documentation.tsx

+            } else if (isPageNode(node)) {
+                this.routeToPage[node.route] = node.reference;
+            } else if (parents[0] != null) {
+                this.routeToPage[node.route] = parents[0].reference;


the ! was probably fine but no reason to not gracefully fail here I think rather than error out if we end up with something unexpected

svc-palantir-github · 2024-06-24T18:49:08Z

fix nav issue with docs page

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

gluxon · 2024-06-24T19:28:05Z

packages/docs-theme/src/components/documentation.tsx

+            if (isNavSection(node)) {
+                return;


nit: Might be worth a comment that we never want to put the user on a "nav section" since these aren't click-able and don't have a real page. They're just presentational groupings of pages.

gluxon · 2024-06-24T19:32:48Z

packages/docs-theme/src/components/documentation.tsx

+// HACKHACK: this is brittle
+// detect Components page and subheadings
+const COMPONENTS_PATTERN = /\/components(\.[\w-]+)?$/;
+const CONTEXT_PATTERN = /\/context(\.[\w-]+)?$/;
+const HOOKS_PATTERN = /\/hooks(\.[\w-]+)?$/;
+const LEGACY_PATTERN = /\/legacy(\.[\w-]+)?$/;
+export const isNavSection = ({ route }: HeadingNode) =>
+    COMPONENTS_PATTERN.test(route) ||
+    CONTEXT_PATTERN.test(route) ||
+    HOOKS_PATTERN.test(route) ||
+    LEGACY_PATTERN.test(route);


Moving this from docs-app to docs-theme feels a bit strange. I think docs-theme is meant to be generalizable outside of the Blueprint repo, and these regex patterns look specific to Blueprint's docs-app.

ah I didn't understand what the distinction was for, I suppose some other project could rely on docs-theme to use the blueprint docs styling and provide their own content?

Yup! I think that's the intention. I'm not sure how many other projects actually do that though.

gluxon · 2024-06-24T19:33:18Z

packages/docs-theme/src/components/documentation.tsx

-            this.routeToPage[node.route] = reference;
+            if (isNavSection(node)) {
+                return;
+            } else if (isPageNode(node)) {


Is the "components" navigation section passing the isPageNode check? Could that be a bug in Documentalist or are we setting up the components section in a weird/unexpected way?

going on intuition haven't dug into the code much here but I believe "components" is a page node because it has sub-pages - /docs/#core/components/breadcrumbs

evansjohnson · 2024-06-27T13:33:05Z

packages/docs-theme/src/components/documentation.tsx

-        const navItemElement = this.navElement.querySelector<HTMLElement>(`a[href="#${activeSectionId}"]`)!;
+        const navItemElement = this.navElement.querySelector<HTMLElement>(`a[href="#${activeSectionId}"]`);
+        if (navItemElement == null) {
+            return;


this is what was actually crashing, and is all that is needed to avoid crashing. but without the rest of this diff users end up here which isn't really useful/seems like a bug on it's own

svc-palantir-github · 2024-06-27T13:44:12Z

diff

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

gluxon

Thanks! 🥳

gluxon · 2024-06-27T18:22:11Z

packages/docs-theme/src/components/documentation.tsx

-            const { reference } = isPageNode(node) ? node : parents[0]!;
-            this.routeToPage[node.route] = reference;
+            if (isPageNode(node)) {
+                if (this.props.navigatorExclude?.(node)) {


Oh nice! I see we were already setting this prop.

gluxon · 2024-06-27T18:22:23Z

packages/docs-theme/src/components/documentation.tsx

-        const navItemElement = this.navElement.querySelector<HTMLElement>(`a[href="#${activeSectionId}"]`)!;
+        const navItemElement = this.navElement.querySelector<HTMLElement>(`a[href="#${activeSectionId}"]`);
+        if (navItemElement == null) {
+            return;


fix nav issue with docs page

01abca0

evansjohnson requested a review from gluxon June 24, 2024 18:40

evansjohnson commented Jun 24, 2024

View reviewed changes

gluxon self-assigned this Jun 24, 2024

gluxon reviewed Jun 24, 2024

View reviewed changes

evansjohnson added 3 commits June 27, 2024 09:25

use existing navigatorexclude prop

fad3220

comment

759c55a

diff

571f046

evansjohnson commented Jun 27, 2024

View reviewed changes

evansjohnson requested a review from gluxon June 27, 2024 13:33

gluxon approved these changes Jun 27, 2024

View reviewed changes

evansjohnson merged commit ceea422 into develop Jun 27, 2024
12 of 14 checks passed

evansjohnson deleted the evanj/docs-nav-fix branch June 27, 2024 19:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix docs crash when navigating with hotkeys #6861

Fix docs crash when navigating with hotkeys #6861

evansjohnson commented Jun 24, 2024

changelog-app bot commented Jun 24, 2024

evansjohnson Jun 24, 2024 •

edited

Loading

svc-palantir-github commented Jun 24, 2024

gluxon Jun 24, 2024

gluxon Jun 24, 2024

evansjohnson Jun 27, 2024

gluxon Jun 27, 2024

gluxon Jun 24, 2024

evansjohnson Jun 27, 2024

evansjohnson Jun 27, 2024

gluxon Jun 27, 2024

svc-palantir-github commented Jun 27, 2024

gluxon left a comment

gluxon Jun 27, 2024

gluxon Jun 27, 2024

Fix docs crash when navigating with hotkeys #6861

Fix docs crash when navigating with hotkeys #6861

Conversation

evansjohnson commented Jun 24, 2024

Fixes #6381

Checklist

Changes proposed in this pull request:

Reviewers should focus on:

Also considered

Screenshot

changelog-app bot commented Jun 24, 2024

Generate changelog in packages/docs-app/changelog/@unreleased

Generate changelog in packages/docs-theme/changelog/@unreleased

evansjohnson Jun 24, 2024 • edited Loading

Choose a reason for hiding this comment

svc-palantir-github commented Jun 24, 2024

fix nav issue with docs page

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

svc-palantir-github commented Jun 27, 2024

diff

gluxon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Generate changelog in `packages/docs-app/changelog/@unreleased`

Generate changelog in `packages/docs-theme/changelog/@unreleased`

evansjohnson Jun 24, 2024 •

edited

Loading