@shipfox/client-workspace-settings 22.0.2 → 23.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-workspace-settings",
   "license": "MIT",
-  "version": "22.0.2",
+  "version": "23.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -29,10 +29,10 @@
     "@tanstack/react-form": "^1.32.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
     "@shipfox/client-api": "6.0.1",
-    "@shipfox/client-auth": "22.0.2",
-    "@shipfox/client-shell": "22.0.2",
-    "@shipfox/client-ui": "22.0.2",
-    "@shipfox/react-ui": "2.1.1"
+    "@shipfox/client-auth": "23.0.0",
+    "@shipfox/client-shell": "23.0.0",
+    "@shipfox/client-ui": "22.0.3",
+    "@shipfox/react-ui": "2.2.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.101.0",

package/src/components/show-setup-guide-link.test.tsx

@@ -0,0 +1,69 @@
+import {
+  clearWorkspaceSetupChecklistDismissal,
+  dismissWorkspaceSetupChecklist,
+  isWorkspaceSetupChecklistDismissed,
+} from '@shipfox/client-shell/runtime';
+import {fireEvent, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {ShowSetupGuideLink} from './show-setup-guide-link.js';
+
+const CURRENT_WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+const OTHER_WORKSPACE_ID = '22222222-2222-4222-8222-222222222222';
+
+describe('ShowSetupGuideLink', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  test('is absent while the setup guide is not dismissed', () => {
+    render(<ShowSetupGuideLink workspaceId={CURRENT_WORKSPACE_ID} />);
+
+    expect(screen.queryByRole('button', {name: 'Show the setup guide'})).not.toBeInTheDocument();
+  });
+
+  test('is present while the setup guide is dismissed for the current workspace', () => {
+    dismissWorkspaceSetupChecklist(CURRENT_WORKSPACE_ID);
+
+    render(<ShowSetupGuideLink workspaceId={CURRENT_WORKSPACE_ID} />);
+
+    expect(screen.getByRole('button', {name: 'Show the setup guide'})).toBeInTheDocument();
+  });
+
+  test('does not use another workspace dismissal flag', () => {
+    dismissWorkspaceSetupChecklist(OTHER_WORKSPACE_ID);
+
+    render(<ShowSetupGuideLink workspaceId={CURRENT_WORKSPACE_ID} />);
+
+    expect(screen.queryByRole('button', {name: 'Show the setup guide'})).not.toBeInTheDocument();
+    expect(isWorkspaceSetupChecklistDismissed(OTHER_WORKSPACE_ID)).toBe(true);
+  });
+
+  test('re-reads the dismissal flag when the window regains focus', () => {
+    render(<ShowSetupGuideLink workspaceId={CURRENT_WORKSPACE_ID} />);
+    dismissWorkspaceSetupChecklist(CURRENT_WORKSPACE_ID);
+
+    fireEvent.focus(window);
+
+    expect(screen.getByRole('button', {name: 'Show the setup guide'})).toBeInTheDocument();
+
+    clearWorkspaceSetupChecklistDismissal(CURRENT_WORKSPACE_ID);
+    fireEvent.focus(window);
+
+    expect(screen.queryByRole('button', {name: 'Show the setup guide'})).not.toBeInTheDocument();
+  });
+
+  test('clears the dismissal flag and announces where the guide will appear', async () => {
+    dismissWorkspaceSetupChecklist(CURRENT_WORKSPACE_ID);
+    const user = userEvent.setup();
+    render(<ShowSetupGuideLink workspaceId={CURRENT_WORKSPACE_ID} />);
+
+    await user.click(screen.getByRole('button', {name: 'Show the setup guide'}));
+
+    expect(isWorkspaceSetupChecklistDismissed(CURRENT_WORKSPACE_ID)).toBe(false);
+    expect(screen.queryByRole('button', {name: 'Show the setup guide'})).not.toBeInTheDocument();
+    expect(screen.getByRole('status')).toHaveTextContent(
+      'The setup guide will appear on the Projects page.',
+    );
+    expect(document.activeElement).toBe(screen.getByRole('status'));
+  });
+});

package/src/components/show-setup-guide-link.tsx

@@ -0,0 +1,66 @@
+import {
+  clearWorkspaceSetupChecklistDismissal,
+  isWorkspaceSetupChecklistDismissed,
+} from '@shipfox/client-shell/runtime';
+import {ButtonLink} from '@shipfox/react-ui/button';
+import {useEffect, useRef, useState} from 'react';
+
+const SETUP_GUIDE_REOPENED_MESSAGE = 'The setup guide will appear on the Projects page.';
+
+export function ShowSetupGuideLink({workspaceId}: {workspaceId: string}) {
+  const [dismissed, setDismissed] = useState(() => isWorkspaceSetupChecklistDismissed(workspaceId));
+  const [statusMessage, setStatusMessage] = useState<string>();
+  const statusRef = useRef<HTMLParagraphElement>(null);
+
+  useEffect(() => {
+    const refreshDismissal = () => {
+      const nextDismissed = isWorkspaceSetupChecklistDismissed(workspaceId);
+      setDismissed(nextDismissed);
+      if (nextDismissed) setStatusMessage(undefined);
+    };
+
+    refreshDismissal();
+    window.addEventListener('focus', refreshDismissal);
+    window.addEventListener('storage', refreshDismissal);
+
+    return () => {
+      window.removeEventListener('focus', refreshDismissal);
+      window.removeEventListener('storage', refreshDismissal);
+    };
+  }, [workspaceId]);
+
+  useEffect(() => {
+    if (statusMessage) statusRef.current?.focus();
+  }, [statusMessage]);
+
+  if (!dismissed && !statusMessage) return null;
+
+  return (
+    <>
+      {dismissed ? (
+        <ButtonLink asChild variant="interactive" underline>
+          <button
+            type="button"
+            onClick={() => {
+              clearWorkspaceSetupChecklistDismissal(workspaceId);
+              setDismissed(false);
+              setStatusMessage(SETUP_GUIDE_REOPENED_MESSAGE);
+            }}
+          >
+            Show the setup guide
+          </button>
+        </ButtonLink>
+      ) : null}
+      {statusMessage ? (
+        <p
+          ref={statusRef}
+          role="status"
+          tabIndex={-1}
+          className="text-sm text-foreground-neutral-muted outline-none"
+        >
+          {statusMessage}
+        </p>
+      ) : null}
+    </>
+  );
+}

package/src/hooks/api/list-invitations.ts

@@ -1,12 +1,19 @@
 import {listInvitationsResponseSchema} from '@shipfox/api-workspaces-dto';
 import {checkedApiRequest} from '@shipfox/client-api';
-import {queryOptions, useQuery} from '@tanstack/react-query';
+import {queryOptions, type UseQueryOptions, useQuery} from '@tanstack/react-query';
 import type {PendingInvitation} from '#core/membership.js';
 import {toInvitation} from './invitation-mapper.js';
 
 export const listInvitationsQueryKey = (workspaceId: string) =>
   ['workspaces', workspaceId, 'invitations'] as const;
 
+type ListInvitationsQueryOptions = UseQueryOptions<
+  PendingInvitation[],
+  Error,
+  PendingInvitation[],
+  ReturnType<typeof listInvitationsQueryKey>
+>;
+
 async function listInvitations(workspaceId: string): Promise<PendingInvitation[]> {
   const response = await checkedApiRequest(
     listInvitationsResponseSchema,
@@ -15,7 +22,7 @@ async function listInvitations(workspaceId: string): Promise<PendingInvitation[]
   return response.invitations.map(toInvitation);
 }
 
-export function listInvitationsQueryOptions(workspaceId: string) {
+export function listInvitationsQueryOptions(workspaceId: string): ListInvitationsQueryOptions {
   return queryOptions({
     queryKey: listInvitationsQueryKey(workspaceId),
     queryFn: () => listInvitations(workspaceId),

package/src/hooks/api/list-members.ts

@@ -1,12 +1,19 @@
 import {listMembersResponseSchema} from '@shipfox/api-workspaces-dto';
 import {checkedApiRequest} from '@shipfox/client-api';
-import {queryOptions, useQuery} from '@tanstack/react-query';
+import {queryOptions, type UseQueryOptions, useQuery} from '@tanstack/react-query';
 import type {WorkspaceMember} from '#core/membership.js';
 import {toWorkspaceMember} from './membership-mapper.js';
 
 export const listMembersQueryKey = (workspaceId: string) =>
   ['workspaces', workspaceId, 'members'] as const;
 
+type ListMembersQueryOptions = UseQueryOptions<
+  WorkspaceMember[],
+  Error,
+  WorkspaceMember[],
+  ReturnType<typeof listMembersQueryKey>
+>;
+
 async function listMembers(workspaceId: string): Promise<WorkspaceMember[]> {
   const response = await checkedApiRequest(
     listMembersResponseSchema,
@@ -15,7 +22,7 @@ async function listMembers(workspaceId: string): Promise<WorkspaceMember[]> {
   return response.members.map(toWorkspaceMember);
 }
 
-export function listMembersQueryOptions(workspaceId: string) {
+export function listMembersQueryOptions(workspaceId: string): ListMembersQueryOptions {
   return queryOptions({
     queryKey: listMembersQueryKey(workspaceId),
     queryFn: () => listMembers(workspaceId),

package/src/index.ts

@@ -1 +1,3 @@
+export * from './hooks/api/list-invitations.js';
+export * from './hooks/api/list-members.js';
 export * from './pages/members-settings-page.js';

package/src/pages/general-settings-page.tsx

@@ -15,6 +15,7 @@ import {useForm} from '@tanstack/react-form';
 import {useNavigate} from '@tanstack/react-router';
 import {useState} from 'react';
 import {workspaceGeneralErrorToFormError} from '#components/general/form-errors.js';
+import {ShowSetupGuideLink} from '#components/show-setup-guide-link.js';
 import {WorkspaceSettingsShell} from '#components/workspace-settings-shell.js';
 
 interface WorkspaceGeneralValues {
@@ -184,6 +185,8 @@ function WorkspaceGeneralForm({workspace}: {workspace: ReturnType<typeof useActi
             </form>
           </PanelBody>
         </Panel>
+
+        <ShowSetupGuideLink workspaceId={workspace.id} />
       </div>
 
       <SlugChangeWarning

package/src/public-api.test.ts

@@ -0,0 +1,27 @@
+import {
+  listInvitationsQueryKey,
+  listInvitationsQueryOptions,
+  listMembersQueryKey,
+  listMembersQueryOptions,
+} from './index.js';
+
+const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+
+describe('@shipfox/client-workspace-settings public query API', () => {
+  test('exports membership and invitation query contracts from the package root', () => {
+    expect(listMembersQueryKey(WORKSPACE_ID)).toEqual(['workspaces', WORKSPACE_ID, 'members']);
+    expect(listInvitationsQueryKey(WORKSPACE_ID)).toEqual([
+      'workspaces',
+      WORKSPACE_ID,
+      'invitations',
+    ]);
+
+    const members = listMembersQueryOptions(WORKSPACE_ID);
+    const invitations = listInvitationsQueryOptions(WORKSPACE_ID);
+
+    expect(members.queryKey).toEqual(['workspaces', WORKSPACE_ID, 'members']);
+    expect(members.queryFn).toEqual(expect.any(Function));
+    expect(invitations.queryKey).toEqual(['workspaces', WORKSPACE_ID, 'invitations']);
+    expect(invitations.queryFn).toEqual(expect.any(Function));
+  });
+});