Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 132 additions & 5 deletions docs/src/pages/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,13 @@ import EnhancedAddons from '@site/src/components/EnhancedAddons';
import PickerShowcase from '@site/src/components/PickerShowcase';
import AiReady from '@site/src/components/AiReady';
import Heading from '@theme/Heading';
import { useStorageSlot } from '@docusaurus/theme-common';
import {
PACKAGE_MANAGERS,
DEFAULT_PACKAGE_MANAGER,
TAB_STORAGE_KEY,
renderCommand,
} from '@site/src/components/PackageManagerTabs/translate.mjs';
import {
Skeleton,
Grid,
Expand Down Expand Up @@ -167,14 +174,87 @@ const formSlides = [
},
];

/** The command the hero advertises, in pnpm's authoring vocabulary. */
const HERO_COMMAND = 'add @allxsmith/bestax-bulma';

function HomepageHeader() {
const { siteConfig } = useDocusaurusContext();
const [copied, setCopied] = React.useState(false);
Comment on lines 180 to 182

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Remove the unused siteConfig destructure.

ESLint reports siteConfig as assigned but never used inside HomepageHeader. No reference to siteConfig exists in this function's body. Remove the unused destructure, since this is on a changed line in this PR and can fail an ESLint gate in CI.

🧹 Proposed fix
 function HomepageHeader() {
-  const { siteConfig } = useDocusaurusContext();
   const [copied, setCopied] = React.useState(false);
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
function HomepageHeader() {
const { siteConfig } = useDocusaurusContext();
const [copied, setCopied] = React.useState(false);
function HomepageHeader() {
const [copied, setCopied] = React.useState(false);
🧰 Tools
🪛 ESLint

[error] 181-181: 'siteConfig' is assigned a value but never used.

(no-unused-vars)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/pages/index.js` around lines 180 - 182, Remove the unused siteConfig
destructure and the now-unneeded useDocusaurusContext call from HomepageHeader,
while preserving the existing copied state and component behavior.

Source: Linters/SAST tools


const handleCopyNpm = () => {
navigator.clipboard.writeText('pnpm add @allxsmith/bestax-bulma');
// The same storage slot Docusaurus uses for the docs tab group, so a choice
// made here is already selected on every docs page and vice versa. The key is
// imported rather than written out: it and the `groupId` it derives from have
// to agree exactly, and a mismatch degrades silently to "hero and docs no
// longer share a choice" with nothing failing.
// useStorageSlot rather than localStorage directly: its server snapshot is null,
// so SSR renders the default and hydration matches, and its setter dispatches a
// synthetic storage event that live-updates any mounted tab group.
const [storedManager, managerSlot] = useStorageSlot(TAB_STORAGE_KEY);
const manager = PACKAGE_MANAGERS.includes(storedManager)
? storedManager
: DEFAULT_PACKAGE_MANAGER;
const command = renderCommand(HERO_COMMAND, manager);

// Held in a ref so a second copy restarts the window instead of inheriting the
// first one's deadline — without this, two clicks 1.9s apart clear "Copied!"
// 100ms after the second. Cleared on unmount so the timer can't setState on a
// gone component.
const copyTimer = React.useRef(null);
React.useEffect(() => () => clearTimeout(copyTimer.current), []);

const handleCopy = async () => {
try {
await navigator.clipboard.writeText(command);
} catch {
// Denied permission, or a non-secure context. Leaving the icon unchanged
// is the honest signal — claiming "Copied!" when the clipboard is
// untouched is worse than doing nothing, and an unhandled rejection here
// would surface as a console error on a page that looks fine.
return;
}
setCopied(true);
setTimeout(() => setCopied(false), 2000);
clearTimeout(copyTimer.current);
copyTimer.current = setTimeout(() => setCopied(false), 2000);
};

const handleCopyKeyDown = event => {
if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
handleCopy();
}
};

// Focus has to move with the selection, or a second arrow press would start
// from whatever the browser still considers focused. Queried out of the group
// rather than held in a ref array so adding a manager needs no bookkeeping.
const switcherRef = React.useRef(null);
const selectManager = index => {
const wrapped = (index + PACKAGE_MANAGERS.length) % PACKAGE_MANAGERS.length;
const next = PACKAGE_MANAGERS[wrapped];
managerSlot.set(next);
switcherRef.current
?.querySelector(`[data-manager="${next}"]`)
?.focus({ preventScroll: true });
};

// The radiogroup key contract. Arrows move *and* select — that is the pattern,
// not an extra — and they wrap, so the group has no dead ends.
const handleSwitcherKeyDown = event => {
const current = PACKAGE_MANAGERS.indexOf(manager);
const move = {
ArrowRight: current + 1,
ArrowDown: current + 1,
ArrowLeft: current - 1,
ArrowUp: current - 1,
Home: 0,
End: PACKAGE_MANAGERS.length - 1,
}[event.key];

if (move === undefined) return;
// Claim only the keys actually handled, so Tab still leaves the group and
// PageUp/PageDown still scroll the page.
event.preventDefault();
selectManager(move);
};

// GitHub Icon SVG
Expand Down Expand Up @@ -230,12 +310,59 @@ function HomepageHeader() {
</p>
<div
className={styles.npmInstallBox}
onClick={handleCopyNpm}
onClick={handleCopy}
onKeyDown={handleCopyKeyDown}
role="button"
tabIndex={0}
title={copied ? 'Copied!' : 'Click to copy'}
>
<code>pnpm add @allxsmith/bestax-bulma</code>
<code>{command}</code>
{copied ? <CheckIcon /> : <CopyIcon />}
</div>
Comment on lines +313 to 321

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Move CopyIcon/CheckIcon (and GitHubIcon) definitions out of HomepageHeader.

ESLint (react-hooks/static-components) reports that line 320's conditional render creates CheckIcon/CopyIcon during render, since both are defined inside HomepageHeader. Components declared inside a render function are recreated on every render, which resets their identity and triggers unnecessary remounts. Declare GitHubIcon, CopyIcon, and CheckIcon outside HomepageHeader (module scope) so they keep a stable identity across renders.

♻️ Proposed fix
+const GitHubIcon = () => (
+  <svg className={styles.githubIcon} viewBox="0 0 16 16" aria-hidden="true">
+    <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59..." />
+  </svg>
+);
+
+const CopyIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" style={{ marginLeft: '8px' }}>
+    ...
+  </svg>
+);
+
+const CheckIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" style={{ marginLeft: '8px' }}>
+    ...
+  </svg>
+);
+
 function HomepageHeader() {
   const [copied, setCopied] = React.useState(false);
   ...
-  // GitHub Icon SVG
-  const GitHubIcon = () => (...);
-  // Copy Icon SVG
-  const CopyIcon = () => (...);
-  // Check Icon SVG (for copied state)
-  const CheckIcon = () => (...);
🧰 Tools
🪛 ESLint

[error] 320-320: Error: Cannot create components during render

Components created during render will reset their state each time they are created. Declare components outside of render.

318 | >
319 | {command}

320 | {copied ? : }
| ^^^^^^^^^ This component is created during render
321 |
322 | {/*
323 | Outside the copy box on purpose: nesting these inside it would bubble

280 |
281 | // Check Icon SVG (for copied state)

282 | const CheckIcon = () => (
| ^^^^^^^
283 | <svg
| ^^^^^^^^
284 | width="16"
…
| ^^^^^^^^
291 |
| ^^^^^^^^
292 | );
| ^^^^ The component is created during render here
293 |
294 | return (
295 | <header className={clsx('hero hero--primary', styles.heroBanner)}>

(react-hooks/static-components)


[error] 320-320: Error: Cannot create components during render

Components created during render will reset their state each time they are created. Declare components outside of render.

318 | >
319 | {command}

320 | {copied ? : }
| ^^^^^^^^ This component is created during render
321 |
322 | {/*
323 | Outside the copy box on purpose: nesting these inside it would bubble

266 |
267 | // Copy Icon SVG

268 | const CopyIcon = () => (
| ^^^^^^^
269 | <svg
| ^^^^^^^^
270 | width="16"
…
| ^^^^^^^^
278 |
| ^^^^^^^^
279 | );
| ^^^^ The component is created during render here
280 |
281 | // Check Icon SVG (for copied state)
282 | const CheckIcon = () => (

(react-hooks/static-components)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/src/pages/index.js` around lines 313 - 321, Move the GitHubIcon,
CopyIcon, and CheckIcon component definitions out of HomepageHeader to module
scope, preserving their existing implementations and usage. Ensure the
conditional copied render continues using the stable module-level CheckIcon and
CopyIcon components.

Source: Linters/SAST tools

{/*
Outside the copy box on purpose: nesting these inside it would bubble
every switch into handleCopy, so picking "npm" would flash "Copied!"
and put the previous manager's command on the clipboard.

A real radiogroup, not toggle buttons: "exactly one of these four" is
what this control means, and aria-pressed only says "each of these is
on or off". Claiming the role means honouring its whole interaction
contract, which is why the key handling below exists rather than the
roles alone:

- one tab stop for the group, via roving tabindex — only the checked
option is reachable with Tab, so the group is a single stop rather
than four
- arrows move *and* select, wrapping at both ends, with Home/End for
the extremes
- focus follows selection, or the next arrow press would start from
wherever focus was left behind
*/}
<div
className={styles.pmSwitcher}
role="radiogroup"
aria-label="Package manager"
ref={switcherRef}
onKeyDown={handleSwitcherKeyDown}
>
{PACKAGE_MANAGERS.map(name => (
<button
key={name}
type="button"
role="radio"
aria-checked={name === manager}
tabIndex={name === manager ? 0 : -1}
data-manager={name}
className={clsx(
styles.pmSwitcherItem,
name === manager && styles.pmSwitcherItemActive
)}
onClick={() => managerSlot.set(name)}
>
{name}
</button>
))}
</div>
<div className={styles.buttons}>
<Link
className={clsx(
Expand Down
72 changes: 71 additions & 1 deletion docs/src/pages/index.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,9 @@
border: 2px solid var(--ifm-color-emphasis-300);
border-radius: 8px;
padding: 1rem 1.5rem;
margin: 2rem auto;
/* Bottom margin tightened from 2rem so .pmSwitcher reads as belonging to this
box rather than floating between it and .buttons. */
margin: 2rem auto 0.6rem;
max-width: 500px;
font-family: var(--ifm-font-family-monospace);
font-size: 1rem;
Expand Down Expand Up @@ -187,6 +189,74 @@
color: inherit;
}

/*
* Package-manager switches under the install box. Deliberately small and quiet —
* these are an affordance, not a call to action; Get Started and GitHub below are
* the CTAs. Writes the same storage slot as the docs pages' <Tabs>, so the choice
* follows the reader into the guides.
*/
.pmSwitcher {
display: flex;
align-items: center;
justify-content: center;
gap: 0.25rem;
}

.pmSwitcherItem {
background: none;
border: none;
border-radius: 4px;
/* Vertical padding keeps the hit target at 24px+, per WCAG 2.2 target size. */
padding: 0.25rem 0.5rem;
font-family: var(--ifm-font-family-monospace);
font-size: 0.8rem;
line-height: 1.4;
color: var(--ifm-color-emphasis-700);
cursor: pointer;
transition:
color 0.15s ease,
background-color 0.15s ease;
}

.pmSwitcherItem:hover {
background: var(--ifm-color-emphasis-200);
color: var(--ifm-color-emphasis-900);
}

.pmSwitcherItem:focus-visible {
outline: 2px solid var(--ifm-color-primary);
outline-offset: 1px;
}

.pmSwitcherItemActive,
.pmSwitcherItemActive:hover {
color: var(--bestax-primary);
font-weight: 700;
background: var(--ifm-color-emphasis-200);
}

[data-theme='dark'] .pmSwitcherItem {
color: var(--ifm-color-emphasis-600);
}

[data-theme='dark'] .pmSwitcherItem:hover {
background: var(--ifm-color-emphasis-200);
color: var(--ifm-color-emphasis-800);
}

/*
* Dark mode drops the brand hue for the active label on purpose. Against the
* emphasis-200 chip no primary variant reaches WCAG AA at this size — the
* lightest gets 3.8:1 — which would leave the *selected* item the least legible
* one in the row. The chip background and bold weight already carry the
* selection, so this uses a high-contrast foreground (8.4:1) instead.
*/
[data-theme='dark'] .pmSwitcherItemActive,
[data-theme='dark'] .pmSwitcherItemActive:hover {
color: var(--ifm-color-emphasis-900);
background: var(--ifm-color-emphasis-200);
}

.buttons {
display: flex;
align-items: center;
Expand Down
Loading