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(home): add dismissible Getting Started link (#6811)

Peter Chinman4a7fc4a02beb
diff --git a/apps/web/src/features/home/home-getting-started-link.tsx b/apps/web/src/features/home/home-getting-started-link.tsx
new file mode 100644
index 0000000000..eab5fe50db
--- /dev/null
+++ b/apps/web/src/features/home/home-getting-started-link.tsx
@@ -0,0 +1,44 @@
+import XIcon from '@phosphor/x.svg';
+import { A } from '@solidjs/router';
+import { Tooltip } from '@ui';
+import { Show } from 'solid-js';
+import { useGettingStartedEnabled } from '../getting-started/account-gate';
+import type { HomePreferences } from './home-prefs';
+
+export function HomeGettingStartedLink(props: {
+ preferences: HomePreferences;
+}) {
+ const enabled = useGettingStartedEnabled();
+
+ return (
+ <Show
+ when={
+ (import.meta.env.DEV || enabled()) &&
+ !props.preferences.isDismissed('getting-started-link')
+ }
+ >
+ <div class="mt-2 flex items-center justify-between gap-3 pl-[53.75px] pr-[7.5px] text-xs text-ink-extra-muted">
+ <span>
+ New to Macro? See the{' '}
+ <A
+ href="/component/getting-started"
+ class="rounded-sm text-ink-muted underline-offset-4 transition-colors hover:text-ink hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent"
+ >
+ Getting Started
+ </A>
+ {' page.'}
+ </span>
+ <Tooltip label="Dismiss" class="shrink-0">
+ <button
+ type="button"
+ class="flex size-[33.75px] shrink-0 items-center justify-center rounded-full transition-colors hover:bg-hover hover:text-ink focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent"
+ aria-label="Dismiss Getting Started link"
+ onClick={() => props.preferences.dismiss('getting-started-link')}
+ >
+ <XIcon class="size-3.5" aria-hidden="true" />
+ </button>
+ </Tooltip>
+ </div>
+ </Show>
+ );
+}
diff --git a/apps/web/src/features/home/home-prefs-context.test.tsx b/apps/web/src/features/home/home-prefs-context.test.tsx
new file mode 100644
index 0000000000..3c75f169a7
--- /dev/null
+++ b/apps/web/src/features/home/home-prefs-context.test.tsx
@@ -0,0 +1,92 @@
+import { cleanup, render, screen } from '@solidjs/testing-library';
+import { batch, createSignal } from 'solid-js';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+ type HomePreferences,
+ HomePreferencesProvider,
+ useHomePreferences,
+} from './home-prefs';
+
+function mountPreferences(initialUserId = 'user-1') {
+ const [userId, setUserId] = createSignal<string | undefined>(initialUserId);
+ const consumers: HomePreferences[] = [];
+ function Consumer() {
+ const preferences = useHomePreferences();
+ consumers.push(preferences);
+ return (
+ <span>
+ {preferences.isDismissed('getting-started-link') ? 'hidden' : 'visible'}
+ </span>
+ );
+ }
+ const view = render(() => (
+ <HomePreferencesProvider userId={userId}>
+ <Consumer />
+ <Consumer />
+ </HomePreferencesProvider>
+ ));
+ return { ...view, consumers, setUserId };
+}
+
+afterEach(() => {
+ cleanup();
+ localStorage.clear();
+});
+
+describe('shared Home preferences', () => {
+ it('updates all mounted consumers immediately and preserves other dismissals', () => {
+ const { consumers } = mountPreferences();
+ const [home, homeChatStart] = consumers;
+ expect(home).toBe(homeChatStart);
+ expect(screen.getAllByText('visible')).toHaveLength(2);
+
+ home.dismiss('setup');
+ homeChatStart.dismiss('getting-started-link');
+ expect(screen.getAllByText('hidden')).toHaveLength(2);
+ expect(homeChatStart.isDismissed('setup')).toBe(true);
+ expect(
+ JSON.parse(localStorage.getItem('macro:home:dismissed:user-1') ?? '[]')
+ ).toEqual(['setup', 'getting-started-link']);
+
+ home.restore('getting-started-link');
+ expect(screen.getAllByText('visible')).toHaveLength(2);
+ expect(homeChatStart.isDismissed('setup')).toBe(true);
+ });
+
+ it('keeps dismissals isolated when users change, including same-turn writes', () => {
+ localStorage.setItem('macro:home:dismissed:user-2', '["setup"]');
+ const { consumers, setUserId } = mountPreferences();
+ const [preferences] = consumers;
+ preferences.dismiss('getting-started-link');
+
+ batch(() => {
+ setUserId('user-2');
+ preferences.dismiss('examples');
+ });
+ expect(screen.getAllByText('visible')).toHaveLength(2);
+ expect(preferences.isDismissed('setup')).toBe(true);
+ expect(
+ JSON.parse(localStorage.getItem('macro:home:dismissed:user-2') ?? '[]')
+ ).toEqual(['setup', 'examples']);
+
+ setUserId(undefined);
+ expect(preferences.isDismissed('setup')).toBe(false);
+ preferences.dismiss('examples');
+ setUserId('user-1');
+ expect(screen.getAllByText('hidden')).toHaveLength(2);
+ expect(preferences.isDismissed('setup')).toBe(false);
+ expect(preferences.isDismissed('examples')).toBe(false);
+ expect(localStorage.getItem('macro:home:dismissed:user-1')).toBe(
+ '["getting-started-link"]'
+ );
+ });
+
+ it('restores persisted dismissals when the provider remounts', () => {
+ const first = mountPreferences();
+ first.consumers[0].dismiss('getting-started-link');
+ first.unmount();
+
+ mountPreferences();
+ expect(screen.getAllByText('hidden')).toHaveLength(2);
+ });
+});
diff --git a/apps/web/src/features/home/home-prefs.test.ts b/apps/web/src/features/home/home-prefs.test.ts
index 586933c8db..139a07be76 100644
--- a/apps/web/src/features/home/home-prefs.test.ts
+++ b/apps/web/src/features/home/home-prefs.test.ts
@@ -3,10 +3,9 @@ import { parseDismissedCards } from './home-prefs';
describe('parseDismissedCards', () => {
it('accepts known home cards', () => {
- expect(parseDismissedCards('["examples","setup"]')).toEqual([
- 'examples',
- 'setup',
- ]);
+ expect(
+ parseDismissedCards('["examples","setup","getting-started-link"]')
+ ).toEqual(['examples', 'setup', 'getting-started-link']);
});
it('drops unknown and non-string entries', () => {
diff --git a/apps/web/src/features/home/home-prefs.ts b/apps/web/src/features/home/home-prefs.ts
index 3f38df2597..ec8e29b05b 100644
--- a/apps/web/src/features/home/home-prefs.ts
+++ b/apps/web/src/features/home/home-prefs.ts
@@ -1,12 +1,17 @@
-import { useUserId } from '@core/context/user';
+import { createAssertedContextProvider } from '@core/context/createContext';
import { createUserScopedStorage } from '@core/util/userScopedStorage';
-import { createEffect, createSignal, on } from 'solid-js';
+import type { ContextProviderProps } from '@solid-primitives/context';
+import { type Accessor, createMemo, createSignal } from 'solid-js';
/** Dismissible home surfaces. Dismissals persist in localStorage. */
-export type HomeCard = 'examples' | 'setup';
+export type HomeCard = 'examples' | 'setup' | 'getting-started-link';
const storage = createUserScopedStorage('macro:home:dismissed');
-const HOME_CARDS: readonly HomeCard[] = ['examples', 'setup'];
+const HOME_CARDS: readonly HomeCard[] = [
+ 'examples',
+ 'setup',
+ 'getting-started-link',
+];
export function parseDismissedCards(raw: string | null): HomeCard[] {
if (raw === null) return [];
@@ -35,30 +40,35 @@ function persist(userId: string | undefined, cards: Set<HomeCard>): void {
export type HomePreferences = ReturnType<typeof createHomePreferences>;
/** User-scoped, reactive dismissal preferences for the home surface. */
-export function createHomePreferences() {
- const userId = useUserId();
- const [dismissed, setDismissed] = createSignal<Set<HomeCard>>(new Set());
+export function createHomePreferences(userId: Accessor<string | undefined>) {
+ const state = createMemo(() => {
+ const id = userId();
+ const [dismissed, setDismissed] = createSignal(new Set(load(id)));
- createEffect(
- on(userId, (id) => {
- setDismissed(new Set(load(id)));
- })
- );
+ const update = (card: HomeCard, shouldDismiss: boolean) => {
+ setDismissed((previous) => {
+ if (previous.has(card) === shouldDismiss) return previous;
+ const next = new Set(previous);
+ if (shouldDismiss) next.add(card);
+ else next.delete(card);
+ persist(id, next);
+ return next;
+ });
+ };
- const update = (card: HomeCard, shouldDismiss: boolean) => {
- setDismissed((previous) => {
- if (previous.has(card) === shouldDismiss) return previous;
- const next = new Set(previous);
- if (shouldDismiss) next.add(card);
- else next.delete(card);
- persist(userId(), next);
- return next;
- });
- };
+ return { dismissed, update };
+ });
return {
- isDismissed: (card: HomeCard) => dismissed().has(card),
- dismiss: (card: HomeCard) => update(card, true),
- restore: (card: HomeCard) => update(card, false),
+ isDismissed: (card: HomeCard) => state().dismissed().has(card),
+ dismiss: (card: HomeCard) => state().update(card, true),
+ restore: (card: HomeCard) => state().update(card, false),
};
}
+
+/** One preference instance shared by every Home surface in the app. */
+export const [HomePreferencesProvider, useHomePreferences] =
+ createAssertedContextProvider<
+ HomePreferences,
+ ContextProviderProps & { userId: Accessor<string | undefined> }
+ >('HomePreferences', (props) => createHomePreferences(props.userId));
diff --git a/apps/web/src/features/home/home.tsx b/apps/web/src/features/home/home.tsx
index 6e67c9795f..39e1b3d5f8 100644
--- a/apps/web/src/features/home/home.tsx
+++ b/apps/web/src/features/home/home.tsx
@@ -11,8 +11,9 @@ import { Navigate } from '@solidjs/router';
import { HomeBackfillProgress } from './home-backfill-progress';
import { HomeChatInput } from './home-chat-input';
import { HomeExamples } from './home-examples';
+import { HomeGettingStartedLink } from './home-getting-started-link';
import { GettingStartedSection, RecommendedSection } from './home-hub';
-import { createHomePreferences } from './home-prefs';
+import { useHomePreferences } from './home-prefs';
import { HomeSectionBoundary } from './home-section-boundary';
const MACRO_LOGO_PATH =
@@ -68,7 +69,7 @@ export function Home() {
function HomeContent() {
const user = useUserContext();
- const preferences = createHomePreferences();
+ const preferences = useHomePreferences();
const firstName = () => {
const name = user.author();
@@ -133,6 +134,7 @@ function HomeContent() {
<FloatRegionOrInline region="accessory">
<div class="mx-auto w-full max-w-3xl shrink-0 px-4 pb-3 pointer-events-auto touch:px-(--mobile-chrome-gutter) touch:pb-0">
<HomeChatInput />
+ <HomeGettingStartedLink preferences={preferences} />
</div>
</FloatRegionOrInline>
</main>
diff --git a/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx b/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx
index fa92401b32..071f318b15 100644
--- a/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx
+++ b/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx
@@ -1,6 +1,7 @@
import { cleanup, render, screen } from '@solidjs/testing-library';
import type { JSX } from 'solid-js';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { HomePreferencesProvider } from '../../home/home-prefs';
import { HomeChatStart } from './HomeChatStart';
type ChildrenProps = { children?: JSX.Element };
@@ -44,6 +45,9 @@ vi.mock('@core/component/AI/context', () => ({
vi.mock('../../home/home-chat-input', () => ({
HomeChatInput: () => <div data-testid="home-chat-input" />,
}));
+vi.mock('../../home/home-getting-started-link', () => ({
+ HomeGettingStartedLink: () => <div data-testid="getting-started-link" />,
+}));
vi.mock('../../home/components/home-recommended-actions', () => ({
HomeRecommendedActions: () => <div data-testid="home-suggestions" />,
}));
@@ -55,9 +59,17 @@ beforeEach(() => {
});
afterEach(cleanup);
+function renderHome() {
+ return render(() => (
+ <HomePreferencesProvider userId={() => 'user-1'}>
+ <HomeChatStart />
+ </HomePreferencesProvider>
+ ));
+}
+
describe('Home agent composer alignment', () => {
it('matches the Agents new-conversation topbar and padding when the list is open', () => {
- render(() => <HomeChatStart />);
+ renderHome();
const grid = document.querySelector('[data-home-composer-align="agents"]');
expect(grid).toBeTruthy();
expect(grid?.className).toContain('pt-6');
@@ -70,7 +82,7 @@ describe('Home agent composer alignment', () => {
it('uses the real Home topbar instead of a spacer when the list is collapsed', () => {
mocks.asideCollapsed = true;
- render(() => <HomeChatStart />);
+ renderHome();
expect(document.querySelector('[data-testid="home-topbar"]')).toBeTruthy();
expect(
document.querySelector('[data-home-composer-topbar-align]')
@@ -82,7 +94,7 @@ describe('Home agent composer alignment', () => {
it('keeps the legacy 32px-above-center composer when agents are disabled', () => {
mocks.agentsEnabled = false;
- render(() => <HomeChatStart />);
+ renderHome();
const grid = document.querySelector('[data-home-composer-align="legacy"]');
expect(grid).toBeTruthy();
expect(grid?.className).toContain('pb-16');
diff --git a/apps/web/src/features/inbox-view/components/HomeChatStart.tsx b/apps/web/src/features/inbox-view/components/HomeChatStart.tsx
index 2f73b8ffa0..75f7685f0c 100644
--- a/apps/web/src/features/inbox-view/components/HomeChatStart.tsx
+++ b/apps/web/src/features/inbox-view/components/HomeChatStart.tsx
@@ -10,11 +10,14 @@ import { enableChatV3Agents } from '@core/constant/featureFlags';
import { Show } from 'solid-js';
import { HomeRecommendedActions } from '../../home/components/home-recommended-actions';
import { HomeChatInput } from '../../home/home-chat-input';
+import { HomeGettingStartedLink } from '../../home/home-getting-started-link';
+import { useHomePreferences } from '../../home/home-prefs';
/** Desktop Home's idle pane uses the single-line chat composer and send flow. */
export function HomeChatStart() {
const shell = useViewShell();
const agents = useFeatureFlag(enableChatV3Agents);
+ const preferences = useHomePreferences();
const showHomeTopBar = () =>
shell.aside.isCollapsed() || shell.aside.isOverlay();
return (
@@ -65,6 +68,7 @@ export function HomeChatStart() {
autoFocusOnMount={false}
/>
<div class="min-h-0 min-w-0 pb-8">
+ <HomeGettingStartedLink preferences={preferences} />
<HomeRecommendedActions />
</div>
</div>
diff --git a/apps/web/src/routes/Root.tsx b/apps/web/src/routes/Root.tsx
index 4bdd7a0d28..8fd61c6ef0 100644
--- a/apps/web/src/routes/Root.tsx
+++ b/apps/web/src/routes/Root.tsx
@@ -9,6 +9,7 @@ import { ChannelInviteAcceptance } from '@app/features/channel-invitations/Chann
import { InviteLinksPortal } from '@app/features/gtm-invite/InviteLinksPortal';
import { InviteWelcome } from '@app/features/gtm-invite/InviteWelcome';
import { usePendingInviteRedemption } from '@app/features/gtm-invite/usePendingInviteRedemption';
+import { HomePreferencesProvider } from '@app/features/home/home-prefs';
import { GlobalShareInboxConflictDialog } from '@app/features/inbox/ShareInboxConflictDialog';
import { usePendingNotificationNavigationEffect } from '@app/features/notifications/PendingNotificationNavigationEffect';
import { InteractiveOnboardingModal } from '@app/features/onboarding/InteractiveOnboardingModal';
@@ -384,6 +385,7 @@ const ROUTES: RouteDefinition[] = [
];
function ConfiguredGlobalAppStateProvider(props: ParentProps) {
+ const userId = useUserId();
// Initialize global notification helpers
const notifInterface = usePlatformNotificationState();
useChatRenameWebsocketSync();
@@ -417,7 +419,9 @@ function ConfiguredGlobalAppStateProvider(props: ParentProps) {
notificationSource={notificationSource}
blockOrchestrator={blockOrchestrator}
>
- {props.children}
+ <HomePreferencesProvider userId={userId}>
+ {props.children}
+ </HomePreferencesProvider>
</GlobalAppStateProvider>
);
}
diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.md
index 5460cb94bd..c64ce976d9 100644
--- a/docs/AGENT_GUIDE/surfaces.md
+++ b/docs/AGENT_GUIDE/surfaces.md
@@ -150,7 +150,13 @@ are restored, including before a chat-limit paywall opens. With agents disabled,
the input stays 32px above the vertical center as suggestions load. With agents
enabled, the composer uses the same topbar offset and 24/64 padding as the
Agents new-conversation page so the two inputs share a baseline; suggestions
-still load below it without moving the input. Up to three cached AI
+still load below it without moving the input. Eligible newer accounts (all
+accounts in development) see “New to Macro? See the **Getting Started** page.” directly
+below the composer, above suggestions. The link opens
+`/app/component/getting-started`; **Dismiss Getting Started link** hides it and
+remembers the dismissal per user in this browser across reloads. Dismissals update
+all open Home panes immediately and stay isolated when switching accounts. This
+dismissal is independent of the Getting Started sidebar link. Up to three cached AI
suggestions appear below the
composer, using the existing fast/smart recommendation projections. Compact rows
use one line: reason — Phosphor icon and item name, followed by Open, all at the same font size. Clicking a
@@ -787,6 +793,9 @@ creation can be retried.
Greeting, getting-started checklist, example prompt buttons (`Draft a document`,
`Draft an email`, `Search & research`), and the ubiquitous `Ask AI` composer.
+Eligible newer accounts (all accounts in development) also see the same
+dismissible **Getting Started** link below
+the composer, with its dismissal shared with the desktop Home starting pane.
On phones, shared confirmations (including Remove Member and Cancel Invitation)
use a glass sheet with a title, description, Close confirmation button, and