Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(soup): persist filters and last open tab per view (#5142)

dev-rb6b7f2a317b3b
diff --git a/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx b/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx
index ee06d03724..c2bf28e5c1 100644
--- a/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx
+++ b/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx
@@ -24,6 +24,7 @@ import {
type Query,
type QueryStore,
} from '@app/features/next-soup/filters/filter-store/query-store';
+import { VIEW_TAB_PRESETS } from '@app/features/next-soup/sidebar/soup-filter-presets';
import { createGroupedSoupQueries } from '@app/features/next-soup/soup-view/create-grouped-soup-queries';
import { createSearchState } from '@app/features/next-soup/soup-view/create-search-state';
import {
@@ -40,6 +41,7 @@ import {
scopeChannelNotificationsForEntity,
} from '@app/features/next-soup/utils';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
+import { makeFlaggedPersisted } from '@app/preferences/make-flagged-persisted';
import { useDealStages } from '@companies/crm/deal-stages';
import { useGlobalNotificationSource } from '@components/app/GlobalAppState';
import { useEntryState } from '@components/app/split-layout/entry-state';
@@ -50,6 +52,8 @@ import {
ENABLE_GRAPHQL_SOUP_OVERRIDE,
ENABLE_NEW_INBOX_FLAG,
ENABLE_NEW_INBOX_OVERRIDE,
+ ENABLE_SOUP_FILTER_PERSISTENCE_FLAG,
+ ENABLE_SOUP_FILTER_PERSISTENCE_OVERRIDE,
ENABLE_SUPPORTED_SOUP_FOREIGN_ENTITIES_FLAG,
ENABLE_SUPPORTED_SOUP_FOREIGN_ENTITIES_OVERRIDE,
} from '@core/constant/featureFlags';
@@ -77,6 +81,7 @@ import { soupKeys } from '@queries/soup/keys';
import { useReactiveSoupAstItemsQuery } from '@queries/soup/reactive-items';
import { mapApiSoupItemToEntity } from '@queries/soup/transform-utils';
import type { SoupApiItem, SoupPage } from '@service-storage/generated/schemas';
+import { makePersisted } from '@solid-primitives/storage';
import type { InfiniteData } from '@tanstack/solid-query';
import {
type Accessor,
@@ -119,6 +124,8 @@ type SoupViewInitializeOptions = {
initialQuery?: Query;
initialClientFilters?: SetPredicatesInput<string>;
initialSearchText?: string;
+ /** Explicit navigation state (for example a shared view) wins over storage. */
+ preferInitialFilters?: boolean;
disableLocalSearch?: boolean;
additionalEntities?: Accessor<EntityData[]>;
/**
@@ -151,6 +158,8 @@ interface SoupViewContextValues {
isSearchServiceLoading: Accessor<boolean>;
isLocalSearchSettling: Accessor<boolean>;
queryFilters: QueryStore;
+ restorePersistedQueryFilters: (tabId: string) => boolean;
+ restorePersistedPredicates: (tabId: string) => boolean;
tagFilter: TagFilter;
filterByTag: (optionId: string) => void;
assigneeFilter: Accessor<string[]>;
@@ -163,6 +172,7 @@ interface SoupViewContextValues {
setInboxFilter: Setter<string[] | undefined>;
activeTab: Accessor<string | undefined>;
setActiveTab: Setter<string | undefined>;
+ getPersistedActiveTab: (view: ListView) => string | undefined;
viewMode: Accessor<SoupViewMode>;
setViewMode: Setter<SoupViewMode>;
readFilter: Accessor<ReadFilter>;
@@ -194,6 +204,57 @@ interface SoupViewContextProviderProps extends SoupViewInitializeOptions {
initialEnabled?: boolean;
}
+type PersistedViewQueryFilters =
+ | QueryState
+ | Partial<Record<string, QueryState>>;
+type PersistedQueryFilters = Partial<
+ Record<ListView, PersistedViewQueryFilters>
+>;
+
+// Shared by every split so one provider cannot overwrite another provider's
+// saved views with a stale local copy of the persisted map.
+const [persistedQueryFilters, setPersistedQueryFilters] = makePersisted(
+ createSignal<PersistedQueryFilters>({}),
+ { name: 'soup-view-query-filters' }
+);
+
+const [persistedPredicates, setPersistedPredicates] = makePersisted(
+ createSignal<
+ Partial<
+ Record<ListView, Partial<Record<string, SetPredicatesInput<string>>>>
+ >
+ >({}),
+ { name: 'soup-view-predicates' }
+);
+
+const [persistedActiveTabs, setPersistedActiveTabs] = makePersisted(
+ createSignal<Partial<Record<ListView, string>>>({}),
+ { name: 'soup-view-active-tabs' }
+);
+
+const isQueryState = (value: unknown): value is QueryState =>
+ typeof value === 'object' &&
+ value !== null &&
+ 'include' in value &&
+ 'exclude' in value;
+
+const persistedQueryFor = (
+ view: ListView,
+ tabId: string
+): QueryState | undefined => {
+ const saved = persistedQueryFilters()[view];
+ if (!saved) return;
+
+ // Migrate the previous per-view shape by using it as the first restored tab.
+ return isQueryState(saved) ? saved : saved[tabId];
+};
+
+const persistedPredicatesFor = (
+ view: ListView,
+ tabId: string
+): SetPredicatesInput<string> | undefined =>
+ persistedPredicates()[view]?.[tabId];
+
type ApiSortMethod = Exclude<
NonNullable<SoupParams['sort_method']>,
'frecency'
@@ -225,12 +286,19 @@ export const SoupViewContextProvider: FlowComponent<
initialQuery: props.initialQuery,
initialClientFilters: props.initialClientFilters,
initialSearchText: props.initialSearchText,
+ preferInitialFilters: props.preferInitialFilters,
disableLocalSearch: props.disableLocalSearch,
additionalEntities: props.additionalEntities,
itemMembershipFilter: props.itemMembershipFilter,
});
const queryClient = useQueryClient();
+ const soupFilterPersistenceFF = useFeatureFlag(
+ ENABLE_SOUP_FILTER_PERSISTENCE_FLAG,
+ { enabledOverride: ENABLE_SOUP_FILTER_PERSISTENCE_OVERRIDE }
+ );
+ const filterPersistenceEnabled = () => soupFilterPersistenceFF().enabled;
+
const useGraphqlSoupFF = useFeatureFlag(ENABLE_GRAPHQL_SOUP_FLAG, {
enabledOverride: ENABLE_GRAPHQL_SOUP_OVERRIDE,
});
@@ -260,10 +328,45 @@ export const SoupViewContextProvider: FlowComponent<
};
});
+ const initialEntryState = panel.handle.currentEntryState();
+ const initialEntryQuery = initialEntryState?.['search.filters'] as
+ | Query
+ | undefined;
+ const initialEntryPredicates = initialEntryState?.['search.predicates'] as
+ | SetPredicatesInput<string>
+ | undefined;
+ const initialView = activeListView();
+ const initialTab = initialView
+ ? ((initialEntryState?.['soup.tab'] as string | undefined) ??
+ (filterPersistenceEnabled()
+ ? persistedActiveTabs()[initialView]
+ : undefined) ??
+ VIEW_TAB_PRESETS[initialView].default)
+ : undefined;
+ const initialPersistedQuery =
+ filterPersistenceEnabled() && initialView && initialTab
+ ? persistedQueryFor(initialView, initialTab)
+ : undefined;
+ const initialPersistedPredicates =
+ filterPersistenceEnabled() && initialView && initialTab
+ ? persistedPredicatesFor(initialView, initialTab)
+ : undefined;
+
const store = createQueryStore({
- initial: props.initialQuery,
+ initial:
+ initialEntryQuery ??
+ (props.preferInitialFilters ? props.initialQuery : undefined) ??
+ initialPersistedQuery ??
+ props.initialQuery,
});
+ const initialPredicates =
+ initialEntryPredicates ??
+ (props.preferInitialFilters ? props.initialClientFilters : undefined) ??
+ initialPersistedPredicates ??
+ props.initialClientFilters;
+ if (initialPredicates) soup.predicates.set(initialPredicates);
+
const filterCaptorTeardown = panel.handle.registerEntryStateCaptor(
'search.filters',
() => structuredClone(unwrap(store.state)) as Query
@@ -307,45 +410,125 @@ export const SoupViewContextProvider: FlowComponent<
);
};
+ // Keep filters per list view and tab so refreshing or returning to a tab
+ // restores its refinements without leaking them into another view or tab.
+ let initializing = false;
+ let changedWhilePersistenceDisabled = false;
+ const persistQueryFilters = () => {
+ if (!filterPersistenceEnabled()) {
+ if (enabled() && !initializing) {
+ changedWhilePersistenceDisabled = true;
+ }
+ return;
+ }
+
+ const view = activeListView();
+ if (!view) return;
+
+ const tabId = activeTab() ?? VIEW_TAB_PRESETS[view].default;
+ const snapshot = structuredClone(unwrap(store.state)) as QueryState;
+ setPersistedQueryFilters((current) => {
+ const savedForView = current[view];
+ const filtersByTab =
+ savedForView && !isQueryState(savedForView) ? savedForView : {};
+
+ return {
+ ...current,
+ [view]: {
+ ...filtersByTab,
+ [tabId]: snapshot,
+ },
+ };
+ });
+ };
+
const queryFilters: QueryStore = {
...store,
set: (query) => {
trimToFirstPage();
store.set(query);
+ persistQueryFilters();
},
replace: (query) => {
trimToFirstPage();
store.replace(query);
+ persistQueryFilters();
},
add: (query) => {
trimToFirstPage();
store.add(query);
+ persistQueryFilters();
},
remove: (query) => {
trimToFirstPage();
store.remove(query);
+ persistQueryFilters();
},
};
+
+ const getPersistedActiveTab = (view: ListView): string | undefined =>
+ filterPersistenceEnabled() ? persistedActiveTabs()[view] : undefined;
+
+ const restorePersistedQueryFilters = (tabId: string): boolean => {
+ if (!filterPersistenceEnabled()) return false;
+
+ const view = activeListView();
+ if (!view) return false;
+
+ const persistedQuery = persistedQueryFor(view, tabId);
+ if (!persistedQuery) return false;
+
+ queryFilters.replace(persistedQuery);
+ return true;
+ };
+
+ const restorePersistedPredicates = (tabId: string): boolean => {
+ if (!filterPersistenceEnabled()) return false;
+
+ const view = activeListView();
+ if (!view) return false;
+
+ const predicates = persistedPredicatesFor(view, tabId);
+ if (!predicates) return false;
+
+ soup.predicates.set(predicates);
+ return true;
+ };
+
const tagFilter = createTagFilter(queryFilters);
const filterByTag = (optionId: string) => tagFilter.onChange([optionId]);
const [searchPaused, setSearchPaused] = createSignal(false);
const sourceSearchPaused = createMemo(() => searchPaused() || !enabled());
- const [assigneeFilter, setAssigneeFilter] = useEntryState<string[]>(
- 'soup.assigneeFilter',
- { default: [] }
+ const [assigneeFilter, setAssigneeFilter] = makeFlaggedPersisted(
+ useEntryState<string[]>('soup.assigneeFilter', { default: [] }),
+ {
+ enabled: filterPersistenceEnabled,
+ name: 'soup-view-assignee-filter',
+ }
);
- const [ownerFilter, setOwnerFilter] = useEntryState<string[]>(
- 'soup.ownerFilter',
- { default: [] }
+ const [ownerFilter, setOwnerFilter] = makeFlaggedPersisted(
+ useEntryState<string[]>('soup.ownerFilter', { default: [] }),
+ {
+ enabled: filterPersistenceEnabled,
+ name: 'soup-view-owner-filter',
+ }
);
- const [stageFilter, setStageFilter] = useEntryState<string[]>(
- 'soup.stageFilter',
- { default: [] }
+ const [stageFilter, setStageFilter] = makeFlaggedPersisted(
+ useEntryState<string[]>('soup.stageFilter', { default: [] }),
+ {
+ enabled: filterPersistenceEnabled,
+ name: 'soup-view-stage-filter',
+ }
);
- const [inboxFilter, setInboxFilter] = useEntryState<string[] | undefined>(
- INBOX_FILTER_ENTRY_KEY,
- { default: undefined }
+ const [inboxFilter, setInboxFilter] = makeFlaggedPersisted(
+ useEntryState<string[] | undefined>(INBOX_FILTER_ENTRY_KEY, {
+ default: undefined,
+ }),
+ {
+ enabled: filterPersistenceEnabled,
+ name: 'soup-view-inbox-filter',
+ }
);
// Expose the mail view's inbox filter to consumers outside the split tree
@@ -366,16 +549,104 @@ export const SoupViewContextProvider: FlowComponent<
});
const [activeTab, setActiveTab] = useEntryState<string | undefined>(
'soup.tab',
- { default: undefined }
+ { default: initialTab }
);
+
+ createEffect(
+ on(
+ () => [activeListView(), activeTab()] as const,
+ ([view, tabId]) => {
+ if (!view || !tabId) return;
+ if (!filterPersistenceEnabled()) {
+ if (enabled()) changedWhilePersistenceDisabled = true;
+ return;
+ }
+
+ setPersistedActiveTabs((current) => ({
+ ...current,
+ [view]: tabId,
+ }));
+ },
+ { defer: true }
+ )
+ );
+
+ createEffect(
+ on(
+ () => [soup.predicates.andIds(), soup.predicates.orIds()] as const,
+ ([and, or]) => {
+ if (!enabled()) return;
+ if (!filterPersistenceEnabled()) {
+ changedWhilePersistenceDisabled = true;
+ return;
+ }
+
+ const view = activeListView();
+ if (!view) return;
+ const tabId = activeTab() ?? VIEW_TAB_PRESETS[view].default;
+
+ setPersistedPredicates((current) => ({
+ ...current,
+ [view]: {
+ ...current[view],
+ [tabId]: { and: [...and], or: [...or] },
+ },
+ }));
+ },
+ { defer: true }
+ )
+ );
+
+ // PostHog can resolve after this provider mounts. Hydrate query-backed
+ // state once on the disabled -> enabled transition; entry state remains the
+ // higher-priority source when navigating through split history.
+ let filterPersistenceHydrated = filterPersistenceEnabled();
+ createEffect(
+ on(filterPersistenceEnabled, (persistenceEnabled) => {
+ if (!persistenceEnabled || filterPersistenceHydrated) return;
+ filterPersistenceHydrated = true;
+
+ if (changedWhilePersistenceDisabled || config().preferInitialFilters) {
+ return;
+ }
+
+ const view = activeListView();
+ if (!view) return;
+
+ const entryState = panel.handle.currentEntryState();
+ const tabId =
+ (entryState?.['soup.tab'] as string | undefined) ??
+ persistedActiveTabs()[view] ??
+ activeTab() ??
+ VIEW_TAB_PRESETS[view].default;
+ const query =
+ entryState && 'search.filters' in entryState
+ ? undefined
+ : persistedQueryFor(view, tabId);
+ const predicates =
+ entryState && 'search.predicates' in entryState
+ ? undefined
+ : persistedPredicatesFor(view, tabId);
+
+ batch(() => {
+ setActiveTab(tabId);
+ if (query) queryFilters.replace(query);
+ if (predicates) soup.predicates.set(predicates);
+ });
+ })
+ );
+
// List/board display mode — per-entry state so back/forward restores the
// mode the user left each entry with.
const [viewMode, setViewMode] = useEntryState<SoupViewMode>('soup.viewMode', {
default: 'board',
});
- const [readFilter, setReadFilter] = useEntryState<ReadFilter>(
- 'soup.readFilter',
- { default: 'unread' }
+ const [readFilter, setReadFilter] = makeFlaggedPersisted(
+ useEntryState<ReadFilter>('soup.readFilter', { default: 'unread' }),
+ {
+ enabled: filterPersistenceEnabled,
+ name: 'soup-view-read-filter',
+ }
);
// Date grouping is done client-side (see the date branch in `rows()`): the
@@ -538,13 +809,57 @@ export const SoupViewContextProvider: FlowComponent<
});
const initialize = (options: SoupViewInitializeOptions = {}) => {
- batch(() => {
- setConfig(options);
- queryFilters.replace(options.initialQuery ?? null);
- soup.predicates.set(options.initialClientFilters ?? {});
- setSearchText(options.initialSearchText ?? '');
- setEnabled(true);
- });
+ initializing = true;
+ try {
+ batch(() => {
+ setConfig(options);
+
+ const entryState = panel.handle.currentEntryState();
+ const entryQuery = entryState?.['search.filters'] as Query | undefined;
+ const view = activeListView();
+ const tabId = view
+ ? ((entryState?.['soup.tab'] as string | undefined) ??
+ (filterPersistenceEnabled()
+ ? persistedActiveTabs()[view]
+ : undefined) ??
+ VIEW_TAB_PRESETS[view].default)
+ : undefined;
+ if (tabId) setActiveTab(tabId);
+
+ const persistedQuery =
+ filterPersistenceEnabled() && view && tabId
+ ? persistedQueryFor(view, tabId)
+ : undefined;
+ const entryPredicates = entryState?.['search.predicates'] as
+ | SetPredicatesInput<string>
+ | undefined;
+ const savedPredicates =
+ filterPersistenceEnabled() && view && tabId
+ ? persistedPredicatesFor(view, tabId)
+ : undefined;
+
+ queryFilters.replace(
+ entryQuery ??
+ (options.preferInitialFilters ? options.initialQuery : undefined) ??
+ persistedQuery ??
+ options.initialQuery ??
+ null
+ );
+ soup.predicates.set(
+ entryPredicates ??
+ (options.preferInitialFilters
+ ? options.initialClientFilters
+ : undefined) ??
+ savedPredicates ??
+ options.initialClientFilters ??
+ {}
+ );
+ setSearchText(options.initialSearchText ?? '');
+ setEnabled(true);
+ });
+ } finally {
+ initializing = false;
+ }
};
const showSupportedForeignEntitiesFF = useFeatureFlag(
@@ -1187,6 +1502,8 @@ export const SoupViewContextProvider: FlowComponent<
isSearchServiceLoading: search.isSearchServiceLoading,
isLocalSearchSettling: search.isLocalSearchSettling,
queryFilters,
+ restorePersistedQueryFilters,
+ restorePersistedPredicates,
tagFilter,
filterByTag,
assigneeFilter,
@@ -1199,6 +1516,7 @@ export const SoupViewContextProvider: FlowComponent<
setInboxFilter,
activeTab,
setActiveTab,
+ getPersistedActiveTab,
viewMode,
setViewMode,
readFilter,
diff --git a/apps/web/src/features/next-soup/soup-view/soup-view-tabs.tsx b/apps/web/src/features/next-soup/soup-view/soup-view-tabs.tsx
index 896eb7e2a7..5076c258ed 100644
--- a/apps/web/src/features/next-soup/soup-view/soup-view-tabs.tsx
+++ b/apps/web/src/features/next-soup/soup-view/soup-view-tabs.tsx
@@ -108,8 +108,14 @@ export const shouldPreserveFiltersOnTabChange = (view: ListView) =>
export const useApplyPreset = () => {
const soup = useSoup();
- const { queryFilters, setActiveTab, activeTab, assigneeFilter } =
- useSoupView();
+ const {
+ queryFilters,
+ restorePersistedQueryFilters,
+ restorePersistedPredicates,
+ setActiveTab,
+ activeTab,
+ assigneeFilter,
+ } = useSoupView();
const user = useUserContext();
const isTeamAdmin = useIsTeamAdmin();
@@ -195,8 +201,12 @@ export const useApplyPreset = () => {
batch(() => {
setActiveTab(tabId);
- queryFilters.replace(nextFilters);
- soup.predicates.set(nextClientFilters);
+ if (!restorePersistedQueryFilters(tabId)) {
+ queryFilters.replace(nextFilters);
+ }
+ if (!restorePersistedPredicates(tabId)) {
+ soup.predicates.set(nextClientFilters);
+ }
soup.grouping.setActiveGroupId(preset.groupBy);
});
return true;
diff --git a/apps/web/src/features/next-soup/soup-view/soup-view.tsx b/apps/web/src/features/next-soup/soup-view/soup-view.tsx
index 21f0297b54..1e3ce66f84 100644
--- a/apps/web/src/features/next-soup/soup-view/soup-view.tsx
+++ b/apps/web/src/features/next-soup/soup-view/soup-view.tsx
@@ -417,6 +417,7 @@ export const SoupView = (props: SoupViewProps) => {
initialSearchText: initialCrmView
? (initialCrmView.searchText ?? '')
: (persistedSearchText ?? props.initialSearchText),
+ preferInitialFilters: initialCrmView !== undefined,
disableLocalSearch: props.disableLocalSearch,
additionalEntities: props.additionalEntities,
});
@@ -432,7 +433,13 @@ export const SoupView = (props: SoupViewProps) => {
initialSortIds = ['updated_at'];
}
- let initialActiveTab = initialCrmView?.activeTab ?? persistedActiveTab;
+ const persistedViewActiveTab = isListViewID(contentId)
+ ? soupView.getPersistedActiveTab(contentId)
+ : undefined;
+ let initialActiveTab =
+ initialCrmView?.activeTab ??
+ persistedActiveTab ??
+ persistedViewActiveTab;
if (initialActiveTab === undefined && isListViewID(contentId)) {
initialActiveTab = VIEW_TAB_PRESETS[contentId].default;
diff --git a/apps/web/src/features/next-soup/soup-view/views/companies/use-apply-crm-view.ts b/apps/web/src/features/next-soup/soup-view/views/companies/use-apply-crm-view.ts
index 4ca3d5991a..f375f57107 100644
--- a/apps/web/src/features/next-soup/soup-view/views/companies/use-apply-crm-view.ts
+++ b/apps/web/src/features/next-soup/soup-view/views/companies/use-apply-crm-view.ts
@@ -23,6 +23,7 @@ export function useApplyCrmView() {
return (config: CrmViewConfig) => {
batch(() => {
+ if (config.activeTab !== undefined) setActiveTab(config.activeTab);
queryFilters.replace((config.filters as Query | undefined) ?? null);
soup.predicates.set(config.clientFilters ?? {});
setSearchText(config.searchText ?? '');
@@ -45,7 +46,6 @@ export function useApplyCrmView() {
soup.predicates.toggle({ and: ['company-owner'] });
}
setViewMode(config.viewMode ?? 'board');
- if (config.activeTab !== undefined) setActiveTab(config.activeTab);
});
};
}
diff --git a/apps/web/src/lib/core/constant/featureFlags.ts b/apps/web/src/lib/core/constant/featureFlags.ts
index f5e269285d..2ade02583c 100644
--- a/apps/web/src/lib/core/constant/featureFlags.ts
+++ b/apps/web/src/lib/core/constant/featureFlags.ts
@@ -422,6 +422,14 @@ export const ENABLE_TEAM_INVITE_TIERS_OVERRIDE = DEV_MODE_ENV
export const ENABLE_SOUP_GROUP_BY_OVERRIDE = DEV_MODE_ENV ? true : undefined;
+// Persist soup filters, predicates and tabs across reloads. PostHog controls
+// production rollout; VITE_ENABLE_SOUP_FILTER_PERSISTENCE overrides locally.
+export const ENABLE_SOUP_FILTER_PERSISTENCE_FLAG =
+ 'enable-soup-filter-persistence';
+export const ENABLE_SOUP_FILTER_PERSISTENCE_OVERRIDE = getFeatureFlagOverride(
+ 'ENABLE_SOUP_FILTER_PERSISTENCE'
+);
+
export const ENABLE_TASK_DUPLICATES_FLAG = 'enable-task-duplicates';
export const ENABLE_TASK_DUPLICATES_OVERRIDE = DEV_MODE_ENV ? true : undefined;
diff --git a/apps/web/src/lib/preferences/make-flagged-persisted.ts b/apps/web/src/lib/preferences/make-flagged-persisted.ts
new file mode 100644
index 0000000000..203350f134
--- /dev/null
+++ b/apps/web/src/lib/preferences/make-flagged-persisted.ts
@@ -0,0 +1,81 @@
+import { makePersisted, type SyncStorage } from '@solid-primitives/storage';
+import { type Accessor, createEffect, on, type Signal } from 'solid-js';
+
+type FlaggedPersistenceOptions<T> = {
+ /** Whether persistence should currently be active. */
+ enabled: Accessor<boolean>;
+ /** The localStorage key. */
+ name: string;
+ /** Optional value serializer. Defaults to JSON.stringify. */
+ serialize?: (value: T) => string;
+ /** Optional value deserializer. Defaults to JSON.parse. */
+ deserialize?: (value: string) => T;
+};
+
+/**
+ * Wraps a signal with localStorage persistence controlled by a reactive flag.
+ *
+ * When the flag resolves from disabled to enabled, the signal hydrates once
+ * from storage. If the signal was changed while persistence was disabled, its
+ * live value wins instead of being overwritten by stale storage.
+ */
+export function makeFlaggedPersisted<T>(
+ signal: Signal<T>,
+ options: FlaggedPersistenceOptions<T>
+): Signal<T> {
+ const localStorage = globalThis.localStorage;
+ const serialize =
+ options.serialize ?? ((value: T) => JSON.stringify(value) as string);
+ const disabledBaseline = serialize(signal[0]());
+ let changedWhileDisabled = false;
+ let hydrated = options.enabled();
+
+ const storage: SyncStorage = {
+ getItem: (key) =>
+ options.enabled() ? (localStorage?.getItem(key) ?? null) : null,
+ setItem: (key, value) => {
+ if (!options.enabled()) {
+ if (value !== disabledBaseline) changedWhileDisabled = true;
+ return;
+ }
+ localStorage?.setItem(key, value);
+ },
+ removeItem: (key) => {
+ if (!options.enabled()) {
+ if (disabledBaseline !== undefined) changedWhileDisabled = true;
+ return;
+ }
+ localStorage?.removeItem(key);
+ },
+ };
+
+ const [value, setValue] = makePersisted(signal, {
+ name: options.name,
+ storage,
+ serialize: options.serialize,
+ deserialize: options.deserialize,
+ });
+
+ createEffect(
+ on(options.enabled, (enabled) => {
+ if (!enabled || hydrated) return;
+ hydrated = true;
+
+ if (changedWhileDisabled) return;
+
+ const serialized = localStorage?.getItem(options.name);
+ if (serialized === null || serialized === undefined) return;
+
+ try {
+ const restored = options.deserialize
+ ? options.deserialize(serialized)
+ : (JSON.parse(serialized) as T);
+ signal[1](() => restored);
+ } catch {
+ return;
+ }
+ })
+ );
+
+ return [value, setValue];
+}