mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-18 14:33:19 +00:00
chore: add in-app What's New scaffolding (#1767)
* feat: add whats-new entries data model * feat: add useWhatsNewPreference hook * feat: add whats-new breathing animation * feat: add WhatsNewTrigger sparkle icon * feat: add whatsNew slot to TopBar * feat: add WhatsNewModal * feat: wire whats-new sparkle icon and modal into EditorLayout * feat: add What's New opt-out toggle to Settings * fix: seed What's New watermark for zero-entry releases A release that ships with entries.json still empty must stamp a watermark on first run, or an existing install can never distinguish itself from a genuinely fresh install once a later release adds its first real entry, silently swallowing that entry's unseen signal. * fix: constrain WhatsNewModal height and clarify settings copy Bound the dialog to 85vh as a flex column so ModalBody's fill can constrain the entry list to scroll while the header and footer stay pinned, matching ConfirmModal's pattern. Also clarifies the "Show What's New" helper text in Settings. * fix: drop What's New screenshots that fail to load Screenshots are authored by hand alongside the entry, so a typo'd or not-yet-added filename is a realistic mistake. Previously that left the browser's broken-image placeholder and alt text inside the card; now the image is dropped and the title, blurb, and doc link still render. * style: replace em dash in watermark comment with a comma * fix: make "Never show again" actually hide What's New Turning the feature off previously only stopped the breathing animation and left the sparkle icon in the top bar, which is not what that label means anywhere else. Opting out now removes the trigger entirely and closes the modal, and Settings > About is the single way back. Also brings the trigger in line with its top bar siblings: it now uses the search trigger's hover treatment and gains a visible keyboard focus ring, and the modal bounds itself with dvh rather than vh so the footer cannot sit under a mobile URL bar. The modal is rendered in the desktop branch only, since the bespoke mobile screens drop the top bar that carries its trigger. * test: cover the empty-entries and loader paths of What's New The shipped state has an empty entries.json, so the branch where there is no newest entry is the one actually running, yet nothing exercised it. Adds a sibling hook test mocking that state to pin the empty-string watermark write, and a loader test for the newest-is-last contract the watermark depends on plus the malformed-entry filter. Drops the unreachable array check in the loader and the assertion that mirrored it: TypeScript types the JSON import, so a non-array file fails the build rather than reaching that branch. * refactor: fold the What's New storage writers into one helper writeEnabled and writeLastSeenId were identical apart from the key and the value encoding, duplicating the comment explaining why a failed write is non-fatal. The boolean encoding now sits at its single call site. Also hoists the reversed entry list to module scope, since the source array is a module constant, and factors the repeated preference mock in the trigger test behind a helper. * chore: keep the What's New icon hidden until an entry exists With entries.json empty there is nothing to announce, so a permanent sparkle in the top bar would only ever open a modal reading "Nothing new to show yet". The trigger now renders nothing in that state, leaving the modal's empty state as a runtime fallback for entries that fail validation rather than the shipping experience. This keeps the scaffolding invisible until the first entry is authored, which is the change that actually surfaces the feature to users.
This commit is contained in:
Anso
@@ -0,0 +1,48 @@
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { renderHook, act } from '@testing-library/react';
|
||||
import { vi } from 'vitest';
|
||||
|
||||
// This file exists separately from useWhatsNewPreference.test.ts purely to mock
|
||||
// a different module state: latestWhatsNewEntryId === null, which is what ships
|
||||
// whenever entries.json is still empty. That is the branch running in
|
||||
// production today, so it needs its own coverage rather than relying on the
|
||||
// sibling file's non-null mock.
|
||||
vi.mock('@/whats-new/entries', () => ({ latestWhatsNewEntryId: null }));
|
||||
|
||||
import { useWhatsNewPreference } from '../useWhatsNewPreference';
|
||||
|
||||
const LAST_SEEN_KEY = 'sencho.whatsNew.lastSeenId';
|
||||
|
||||
describe('useWhatsNewPreference with no entries authored yet', () => {
|
||||
beforeEach(() => {
|
||||
localStorage.clear();
|
||||
});
|
||||
|
||||
it('stamps an empty-string watermark on a fresh install so the next release is detected', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
// The write itself is the point: without it, a later release adding its
|
||||
// first entry would still see `stored === null` and silently catch up,
|
||||
// swallowing the very first unseen signal on an existing install.
|
||||
expect(localStorage.getItem(LAST_SEEN_KEY)).toBe('');
|
||||
expect(result.current.hasUnseen).toBe(false);
|
||||
});
|
||||
|
||||
it('reports nothing unseen and leaves the preference enabled by default', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(result.current.hasUnseen).toBe(false);
|
||||
expect(result.current.enabled).toBe(true);
|
||||
});
|
||||
|
||||
it('markSeen is a no-op that does not overwrite the watermark', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
act(() => { result.current.markSeen(); });
|
||||
expect(localStorage.getItem(LAST_SEEN_KEY)).toBe('');
|
||||
expect(result.current.hasUnseen).toBe(false);
|
||||
});
|
||||
|
||||
it('still honours an explicit opt-out', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
act(() => { result.current.setEnabled(false); });
|
||||
expect(result.current.enabled).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,67 @@
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
|
||||
import { renderHook, act } from '@testing-library/react';
|
||||
|
||||
vi.mock('@/whats-new/entries', () => ({ latestWhatsNewEntryId: 'entry-b' }));
|
||||
|
||||
import { useWhatsNewPreference } from '../useWhatsNewPreference';
|
||||
|
||||
describe('useWhatsNewPreference', () => {
|
||||
beforeEach(() => localStorage.clear());
|
||||
afterEach(() => localStorage.clear());
|
||||
|
||||
it('defaults enabled to true when never set', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(result.current.enabled).toBe(true);
|
||||
});
|
||||
|
||||
it('respects a stored disabled preference', () => {
|
||||
localStorage.setItem('sencho.whatsNew.enabled', '0');
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(result.current.enabled).toBe(false);
|
||||
});
|
||||
|
||||
it('setEnabled persists and updates state', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
act(() => result.current.setEnabled(false));
|
||||
expect(result.current.enabled).toBe(false);
|
||||
expect(localStorage.getItem('sencho.whatsNew.enabled')).toBe('0');
|
||||
});
|
||||
|
||||
it('a fresh install (no stored watermark) silently catches up, so hasUnseen starts false', () => {
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(localStorage.getItem('sencho.whatsNew.lastSeenId')).toBe('entry-b');
|
||||
expect(result.current.hasUnseen).toBe(false);
|
||||
});
|
||||
|
||||
it('a release that shipped with zero entries stamps a "" watermark, so the next release\'s first real entry is detected as unseen for an existing install', () => {
|
||||
// Simulates: release N had entries.json === [], the hook already ran once
|
||||
// on this install and (per the fixed initializer) stamped '' as the
|
||||
// watermark. Release N+1 now adds the first real entry. The install is
|
||||
// NOT fresh (a key already exists), so it must not silently catch up.
|
||||
localStorage.setItem('sencho.whatsNew.lastSeenId', '');
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(result.current.hasUnseen).toBe(true);
|
||||
});
|
||||
|
||||
it('an existing watermark behind the latest entry reports hasUnseen true', () => {
|
||||
localStorage.setItem('sencho.whatsNew.lastSeenId', 'entry-a');
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(result.current.hasUnseen).toBe(true);
|
||||
});
|
||||
|
||||
it('markSeen clears hasUnseen and persists the watermark', () => {
|
||||
localStorage.setItem('sencho.whatsNew.lastSeenId', 'entry-a');
|
||||
const { result } = renderHook(() => useWhatsNewPreference());
|
||||
expect(result.current.hasUnseen).toBe(true);
|
||||
act(() => result.current.markSeen());
|
||||
expect(result.current.hasUnseen).toBe(false);
|
||||
expect(localStorage.getItem('sencho.whatsNew.lastSeenId')).toBe('entry-b');
|
||||
});
|
||||
|
||||
it('a second hook instance picks up a change made by the first (window event sync)', () => {
|
||||
const a = renderHook(() => useWhatsNewPreference());
|
||||
const b = renderHook(() => useWhatsNewPreference());
|
||||
act(() => a.result.current.setEnabled(false));
|
||||
expect(b.result.current.enabled).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,91 @@
|
||||
import { useCallback, useEffect, useState } from 'react';
|
||||
import { latestWhatsNewEntryId } from '@/whats-new/entries';
|
||||
|
||||
const ENABLED_KEY = 'sencho.whatsNew.enabled';
|
||||
const LAST_SEEN_KEY = 'sencho.whatsNew.lastSeenId';
|
||||
const CHANGE_EVENT = 'sencho:whats-new-changed';
|
||||
|
||||
function readEnabled(): boolean {
|
||||
try {
|
||||
const raw = localStorage.getItem(ENABLED_KEY);
|
||||
return raw === null ? true : raw === '1';
|
||||
} catch {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
function readLastSeenId(): string | null {
|
||||
try {
|
||||
return localStorage.getItem(LAST_SEEN_KEY);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function writeSetting(key: string, value: string) {
|
||||
try {
|
||||
localStorage.setItem(key, value);
|
||||
} catch {
|
||||
// Quota exhaustion is non-fatal for this preference; in-memory state still
|
||||
// reflects the user's choice for this session.
|
||||
}
|
||||
window.dispatchEvent(new Event(CHANGE_EVENT));
|
||||
}
|
||||
|
||||
export interface UseWhatsNewPreferenceResult {
|
||||
enabled: boolean;
|
||||
setEnabled: (next: boolean) => void;
|
||||
hasUnseen: boolean;
|
||||
markSeen: () => void;
|
||||
}
|
||||
|
||||
export function useWhatsNewPreference(): UseWhatsNewPreferenceResult {
|
||||
const [enabled, setEnabledState] = useState(readEnabled);
|
||||
// The watermark is stamped unconditionally the first time this hook ever
|
||||
// runs, even when entries.json is currently empty (using '' as the seed).
|
||||
// This is deliberate: if we only stamped when latestWhatsNewEntryId was
|
||||
// non-null, an install that first loads while entries are empty would
|
||||
// never get a watermark written, so `stored === null` would still be true
|
||||
// once a later release adds its first real entry, indistinguishable from
|
||||
// a genuinely fresh install, silently swallowing the very first "unseen"
|
||||
// signal. Stamping '' up front means any later real id no longer equals
|
||||
// the stored watermark, so hasUnseen correctly flips to true for existing
|
||||
// installs while a truly fresh install (no key at all) still catches up
|
||||
// silently. Strict Mode may invoke this initializer twice; the write is
|
||||
// idempotent.
|
||||
const [lastSeenId, setLastSeenIdState] = useState<string | null>(() => {
|
||||
const stored = readLastSeenId();
|
||||
if (stored !== null) return stored;
|
||||
const seed = latestWhatsNewEntryId ?? '';
|
||||
writeSetting(LAST_SEEN_KEY, seed);
|
||||
return seed;
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
const handler = () => {
|
||||
setEnabledState(readEnabled());
|
||||
setLastSeenIdState(readLastSeenId());
|
||||
};
|
||||
window.addEventListener(CHANGE_EVENT, handler);
|
||||
window.addEventListener('storage', handler);
|
||||
return () => {
|
||||
window.removeEventListener(CHANGE_EVENT, handler);
|
||||
window.removeEventListener('storage', handler);
|
||||
};
|
||||
}, []);
|
||||
|
||||
const setEnabled = useCallback((next: boolean) => {
|
||||
writeSetting(ENABLED_KEY, next ? '1' : '0');
|
||||
setEnabledState(next);
|
||||
}, []);
|
||||
|
||||
const markSeen = useCallback(() => {
|
||||
if (latestWhatsNewEntryId === null) return;
|
||||
writeSetting(LAST_SEEN_KEY, latestWhatsNewEntryId);
|
||||
setLastSeenIdState(latestWhatsNewEntryId);
|
||||
}, []);
|
||||
|
||||
const hasUnseen = latestWhatsNewEntryId !== null && lastSeenId !== latestWhatsNewEntryId;
|
||||
|
||||
return { enabled, setEnabled, hasUnseen, markSeen };
|
||||
}
|
||||
Reference in New Issue
Block a user