Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(palette): settings search — deep-link focus + completeness guard

Juan Denise0a47bbb9d83
diff --git a/frontend/package.json b/frontend/package.json
index 29cd483f..3c7bedb7 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -6,7 +6,8 @@
"scripts": {
"dev": "vite",
"build": "vite build",
- "lint": "eslint .",
+ "lint": "eslint . && node scripts/check-settings-index.mjs",
+ "lint:settings-index": "node scripts/check-settings-index.mjs",
"preview": "vite preview"
},
"optionalDependencies": {
diff --git a/frontend/scripts/check-settings-index.mjs b/frontend/scripts/check-settings-index.mjs
new file mode 100644
index 00000000..300deecd
--- /dev/null
+++ b/frontend/scripts/check-settings-index.mjs
@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Completeness guard for the settings search index (plan 41, Phase 2).
+//
+// Every settings tab declared in pages/Settings.jsx (VALID_TABS) must have at
+// least one entry in data/settingsIndex.js, so a future settings tab can't ship
+// invisible to the command palette. Also checks that ids are unique and that no
+// entry points at a tab that doesn't exist. Dependency-free; wired into the
+// frontend `lint` script (the frontend has no unit-test runner, so a lint-stage
+// guard is the house-consistent check).
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, '..');
+
+// Tabs intentionally NOT indexed (dev-only surfaces with no user-facing
+// settings). Keep this list tiny and justified.
+const EXEMPT = new Set(['developer']);
+
+function fail(msg) {
+ console.error(`\n✖ settings-index check failed:\n ${msg}\n`);
+ process.exit(1);
+}
+
+// 1. Extract VALID_TABS from pages/Settings.jsx (can't import JSX in node).
+const settingsSrc = readFileSync(resolve(root, 'src/pages/Settings.jsx'), 'utf8');
+const match = settingsSrc.match(/const VALID_TABS\s*=\s*\[([^\]]*)\]/);
+if (!match) fail('could not find VALID_TABS in src/pages/Settings.jsx');
+const tabs = [...match[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
+if (tabs.length === 0) fail('VALID_TABS parsed as empty');
+
+// 2. Import the settings index (pure ESM data module, no runtime deps).
+const { SETTINGS_INDEX } = await import(new URL('../src/data/settingsIndex.js', import.meta.url));
+if (!Array.isArray(SETTINGS_INDEX)) fail('SETTINGS_INDEX is not an array');
+
+// 3. Every non-exempt tab must have at least one entry.
+const tabsWithEntries = new Set(SETTINGS_INDEX.map((e) => e.tab));
+const missing = tabs.filter((t) => !EXEMPT.has(t) && !tabsWithEntries.has(t));
+if (missing.length) {
+ fail(`settings tabs with no entry in data/settingsIndex.js: ${missing.join(', ')}`);
+}
+
+// 4. Ids must be globally unique (they are the ?focus=setting:<id> deep-link key).
+const ids = SETTINGS_INDEX.map((e) => e.id);
+const dupes = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))];
+if (dupes.length) fail(`duplicate settings index ids: ${dupes.join(', ')}`);
+
+// 5. No entry may reference an unknown tab.
+const validTab = new Set(tabs);
+const stray = [...tabsWithEntries].filter((t) => !validTab.has(t));
+if (stray.length) fail(`settingsIndex entries reference unknown tabs: ${stray.join(', ')}`);
+
+console.log(`✓ settings-index: ${SETTINGS_INDEX.length} entries cover ${tabsWithEntries.size} settings tabs`);
diff --git a/frontend/src/components/settings/NotificationsTab.jsx b/frontend/src/components/settings/NotificationsTab.jsx
index 300e6183..da841e95 100644
--- a/frontend/src/components/settings/NotificationsTab.jsx
+++ b/frontend/src/components/settings/NotificationsTab.jsx
@@ -8,9 +8,11 @@ import { Switch } from '@/components/ui/switch';
import { Badge } from '@/components/ui/badge';
import { Checkbox } from '@/components/ui/checkbox';
import EmptyState from '../EmptyState';
+import useSettingFocus from '../../hooks/useSettingFocus';
const NotificationsTab = () => {
const { isAdmin, user } = useAuth();
+ const register = useSettingFocus();
const [loading, setLoading] = useState(true);
const [saving, setSaving] = useState(false);
const [testing, setTesting] = useState(null);
@@ -143,7 +145,7 @@ const NotificationsTab = () => {
const userPrefsUI = (
<div className="user-notification-prefs">
- <div className="settings-card">
+ <div {...register('notifications-enable', 'settings-card')}>
<div className="form-group">
<div className="flex items-center gap-3">
<Switch
@@ -155,7 +157,7 @@ const NotificationsTab = () => {
</div>
</div>
- <div className="settings-card">
+ <div {...register('notifications-channels', 'settings-card')}>
<h3>Notification Channels</h3>
<p>Choose how you want to receive notifications</p>
<div className="channel-toggles">
@@ -177,7 +179,7 @@ const NotificationsTab = () => {
</div>
{userPrefs.channels?.includes('email') && (
- <div className="settings-card">
+ <div {...register('notifications-email', 'settings-card')}>
<h3>Email Settings</h3>
<div className="form-group">
<Label>Notification Email (optional)</Label>
@@ -193,7 +195,7 @@ const NotificationsTab = () => {
)}
{userPrefs.channels?.includes('discord') && (
- <div className="settings-card">
+ <div {...register('notifications-discord-webhook', 'settings-card')}>
<h3>Personal Discord Webhook</h3>
<div className="form-group">
<Label>Webhook URL</Label>
@@ -209,7 +211,7 @@ const NotificationsTab = () => {
)}
{userPrefs.channels?.includes('telegram') && (
- <div className="settings-card">
+ <div {...register('notifications-telegram', 'settings-card')}>
<h3>Personal Telegram</h3>
<div className="form-group">
<Label>Your Chat ID</Label>
@@ -224,7 +226,7 @@ const NotificationsTab = () => {
</div>
)}
- <div className="settings-card">
+ <div {...register('notifications-severity', 'settings-card')}>
<h3>Severity Levels</h3>
<p>Which alert types do you want to receive?</p>
<div className="severity-toggles">
@@ -245,7 +247,7 @@ const NotificationsTab = () => {
</div>
</div>
- <div className="settings-card">
+ <div {...register('notifications-categories', 'settings-card')}>
<h3>Notification Categories</h3>
<p>What types of events should trigger notifications?</p>
<div className="category-toggles">
@@ -269,7 +271,7 @@ const NotificationsTab = () => {
</div>
</div>
- <div className="settings-card">
+ <div {...register('notifications-quiet-hours', 'settings-card')}>
<h3>Quiet Hours</h3>
<p>Pause non-critical notifications during these hours</p>
<div className="form-group">
diff --git a/frontend/src/components/settings/SecuritySettingsTab.jsx b/frontend/src/components/settings/SecuritySettingsTab.jsx
index b02ff337..fae579d8 100644
--- a/frontend/src/components/settings/SecuritySettingsTab.jsx
+++ b/frontend/src/components/settings/SecuritySettingsTab.jsx
@@ -1,6 +1,8 @@
import { useState, useEffect } from 'react';
import { useAuth } from '../../contexts/AuthContext';
import api from '../../services/api';
+import useSettingFocus from '../../hooks/useSettingFocus';
+import TwoFactorPolicyCard from './TwoFactorPolicyCard';
import SSOProviderIcon from '../SSOProviderIcon';
import Modal from '../Modal';
import { Button } from '@/components/ui/button';
@@ -8,7 +10,7 @@ import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Badge } from '@/components/ui/badge';
-const LinkedAccounts = () => {
+const LinkedAccounts = ({ register }) => {
const { ssoProviders } = useAuth();
const [identities, setIdentities] = useState([]);
const [loading, setLoading] = useState(true);
@@ -65,7 +67,7 @@ const LinkedAccounts = () => {
const availableToLink = (ssoProviders || []).filter(p => !linkedProviderIds.includes(p.id));
return (
- <div className="settings-card">
+ <div {...register('security-linked-accounts', 'settings-card')}>
<h3>Linked Accounts</h3>
<p className="text-secondary">Connect external identity providers to your account</p>
@@ -116,7 +118,8 @@ const LinkedAccounts = () => {
};
const SecuritySettingsTab = () => {
- const { updateUser, user } = useAuth();
+ const { updateUser, user, isAdmin } = useAuth();
+ const register = useSettingFocus();
const [formData, setFormData] = useState({
currentPassword: '',
newPassword: '',
@@ -295,7 +298,7 @@ Keep these codes in a safe place.`;
)}
{/* Two-Factor Authentication Section */}
- <div className="settings-card two-fa-card">
+ <div {...register('security-2fa', 'settings-card two-fa-card')}>
<div className="two-fa-header">
<div className="two-fa-icon">
<svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" fill="none" strokeWidth="2">
@@ -365,7 +368,7 @@ Keep these codes in a safe place.`;
)}
</div>
- <form onSubmit={handleSubmit} className="settings-form">
+ <form onSubmit={handleSubmit} {...register('security-password', 'settings-form')}>
<h3>Change Password</h3>
<div className="form-group">
@@ -408,7 +411,7 @@ Keep these codes in a safe place.`;
</div>
</form>
- <div className="settings-card">
+ <div {...register('security-sessions', 'settings-card')}>
<h3>Sessions</h3>
<p>Manage your active sessions</p>
<div className="session-item current">
@@ -427,8 +430,11 @@ Keep these codes in a safe place.`;
</div>
</div>
+ {/* Require-2FA policy (admin only) — a policy, never a default. */}
+ {isAdmin && <TwoFactorPolicyCard {...register('security-2fa-policy', 'settings-card')} />}
+
{/* Linked Accounts */}
- <LinkedAccounts />
+ <LinkedAccounts register={register} />
{/* 2FA Setup Modal */}
{showSetupModal && setupData && (
diff --git a/frontend/src/components/settings/TwoFactorPolicyCard.jsx b/frontend/src/components/settings/TwoFactorPolicyCard.jsx
index 4e9d8954..6da3d30c 100644
--- a/frontend/src/components/settings/TwoFactorPolicyCard.jsx
+++ b/frontend/src/components/settings/TwoFactorPolicyCard.jsx
@@ -16,7 +16,9 @@ const POLICY_LABELS = {
all: 'Everyone — all accounts must enrol',
};
-const TwoFactorPolicyCard = () => {
+// `props` are spread onto the card root so a parent can attach a ref /
+// focus-highlight class (see useSettingFocus / command-palette deep links).
+const TwoFactorPolicyCard = (props) => {
const [policy, setPolicy] = useState('off');
const [graceDays, setGraceDays] = useState(7);
const [loading, setLoading] = useState(true);
@@ -55,7 +57,7 @@ const TwoFactorPolicyCard = () => {
if (loading) return null;
return (
- <div className="settings-card">
+ <div className="settings-card" {...props}>
<h3>Two-Factor Authentication Policy</h3>
<p className="form-help" style={{ marginTop: 0 }}>
Require accounts to protect themselves with a passkey or authenticator
diff --git a/frontend/src/hooks/useSettingFocus.js b/frontend/src/hooks/useSettingFocus.js
new file mode 100644
index 00000000..124a425b
--- /dev/null
+++ b/frontend/src/hooks/useSettingFocus.js
@@ -0,0 +1,67 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import useFocusParam from './useFocusParam';
+
+/**
+ * Settings deep-link focus (plan 41, Phase 2). A settings tab calls this hook
+ * once and spreads `register(id)` onto each card it wants to be landable from
+ * the command palette. When the tab is opened via `/settings/<tab>?focus=setting:<id>`
+ * the matching card is scrolled into view and flashed with `is-setting-focused`
+ * for ~2s, then the highlight clears.
+ *
+ * Rides the plan-33 `useFocusParam` rail with a new `setting` kind — the param
+ * fires once and is cleared, so a refresh doesn't re-trigger it.
+ *
+ * Usage — pass the card's own class as the second arg so the flash class is
+ * composed onto it (no extra wrapper element, no layout shift):
+ * const register = useSettingFocus();
+ * <div {...register('security-2fa', 'settings-card')}> … </div>
+ *
+ * @returns {(id: string, baseClassName?: string) => { ref: Function, className: string|undefined }}
+ */
+export default function useSettingFocus() {
+ const [focusedId, setFocusedId] = useState(null);
+ const refs = useRef(new Map());
+
+ useFocusParam('setting', useCallback((id) => {
+ setFocusedId(id);
+ }, []));
+
+ useEffect(() => {
+ if (!focusedId) return undefined;
+ let attempts = 0;
+ let clearTimer;
+ let retryTimer;
+
+ // The target card may not be mounted yet (the tab is still loading its
+ // data), so poll briefly for it before giving up.
+ const tryScroll = () => {
+ const el = refs.current.get(focusedId);
+ if (el) {
+ el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+ clearTimer = setTimeout(() => setFocusedId(null), 2000);
+ return;
+ }
+ if (attempts++ < 20) {
+ retryTimer = setTimeout(tryScroll, 100);
+ } else {
+ setFocusedId(null);
+ }
+ };
+ retryTimer = setTimeout(tryScroll, 50);
+
+ return () => {
+ clearTimeout(retryTimer);
+ clearTimeout(clearTimer);
+ };
+ }, [focusedId]);
+
+ return useCallback((id, baseClassName) => ({
+ ref: (el) => {
+ if (el) refs.current.set(id, el);
+ else refs.current.delete(id);
+ },
+ className: [baseClassName, focusedId === id ? 'is-setting-focused' : null]
+ .filter(Boolean)
+ .join(' ') || undefined,
+ }), [focusedId]);
+}
diff --git a/frontend/src/styles/components/_command-palette.scss b/frontend/src/styles/components/_command-palette.scss
index f11701d2..6185f3f4 100644
--- a/frontend/src/styles/components/_command-palette.scss
+++ b/frontend/src/styles/components/_command-palette.scss
@@ -206,3 +206,29 @@
.ui-command-item[data-selected='true'] .command-palette__item-icon {
color: $text-primary;
}
+
+// --------------------------------------------
+// Settings deep-link flash (plan 41, Phase 2): a palette result lands on the
+// exact card via ?focus=setting:<id>; useSettingFocus scrolls it into view and
+// adds .is-setting-focused for ~2s. Token-based ring + brief background wash.
+// --------------------------------------------
+.is-setting-focused {
+ scroll-margin-top: $space-6;
+ animation: setting-focus-flash 2s ease-out;
+ border-radius: $radius-md;
+}
+
+@keyframes setting-focus-flash {
+ 0% {
+ box-shadow: 0 0 0 3px var(--accent-bright);
+ background-color: var(--accent-bg-soft);
+ }
+ 70% {
+ box-shadow: 0 0 0 3px var(--accent-bright);
+ background-color: var(--accent-bg-soft);
+ }
+ 100% {
+ box-shadow: 0 0 0 0 transparent;
+ background-color: transparent;
+ }
+}