feat(gradebook): add weighted view UI — table, config dialog, column picker

- add GradebookWeightedTable with 3-row sticky header showing per-tab
  additive weighted subtotals and per-student totals
- add ConfigureWeightsPrompt for managers to edit tab weights (0–100)
  with real-time sum-to-100 warning and integer validation
- add All vs By-weight view toggle in GradebookIndex (role-aware)
- add column picker (Student info, Gamification groups); External ID
  defaults visible when any student has one, hidden otherwise
- add computeWeighted helpers (computeTabSubtotal, computeStudentTotal,
  sumWeights) with full test coverage
- add useDismissibleOnce hook for one-time dismissible hint UI

Author: LWS49

app/controllers/components/course/gradebook_component.rb

@@ -7,6 +7,12 @@ def self.display_name
   end
 
   def sidebar_items
+    main_sidebar_items + settings_sidebar_items
+  end
+
+  private
+
+  def main_sidebar_items
     return [] unless can?(:read_gradebook, current_course)
 
     [
@@ -20,4 +26,17 @@ def sidebar_items
       }
     ]
   end
+
+  def settings_sidebar_items
+    return [] unless can?(:manage_gradebook_settings, current_course)
+
+    [
+      {
+        key: self.class.key,
+        type: :settings,
+        weight: 14,
+        path: course_admin_gradebook_path(current_course)
+      }
+    ]
+  end
 end

client/app/__test__/mocks/localeMock.js

@@ -0,0 +1,2 @@
+// File used for jest moduleNameMapper - empty locale messages for tests
+module.exports = {};

client/app/__test__/setup.js

@@ -65,3 +65,15 @@ jest.mock('react-router-dom', () => ({
   useNavigate: jest.fn(),
   unstable_usePrompt: jest.fn(),
 }));
+
+// Replace I18nProvider with a synchronous stub so tests using test-utils
+// don't stall on async locale loading.
+jest.mock('lib/components/wrappers/I18nProvider', () => {
+  const { IntlProvider } = require('react-intl');
+  const SyncI18nProvider = ({ children }) => (
+    <IntlProvider defaultLocale="en" locale="en" messages={{}}>
+      {children}
+    </IntlProvider>
+  );
+  return { __esModule: true, default: SyncI18nProvider };
+});

client/app/api/course/Gradebook.ts

@@ -1,4 +1,4 @@
-import { GradebookData } from 'types/course/gradebook';
+import { GradebookData, UpdateWeightsPayload } from 'types/course/gradebook';
 
 import { APIResponse } from 'api/types';
 
@@ -12,4 +12,10 @@ export default class GradebookAPI extends BaseCourseAPI {
   index(): APIResponse<GradebookData> {
     return this.client.get(this.#urlPrefix);
   }
+
+  updateWeights(
+    payload: UpdateWeightsPayload,
+  ): APIResponse<UpdateWeightsPayload> {
+    return this.client.patch(`${this.#urlPrefix}/weights`, payload);
+  }
 }

client/app/bundles/course/gradebook/__tests__/ConfigureWeightsPrompt.test.tsx

@@ -0,0 +1,131 @@
+import { fireEvent, render, screen, waitFor } from 'test-utils';
+
+import ConfigureWeightsPrompt from '../components/ConfigureWeightsPrompt';
+import * as operations from '../operations';
+
+jest
+  .spyOn(operations, 'updateGradebookWeights')
+  .mockReturnValue(async () => {});
+
+const categories = [{ id: 1, title: 'Missions' }];
+const tabs = [
+  { id: 10, title: 'Assignments', categoryId: 1, gradebookWeight: 50 },
+  { id: 11, title: 'Optional', categoryId: 1, gradebookWeight: 50 },
+];
+const assessments = [
+  { id: 101, title: 'Assignment 1', tabId: 10, maxGrade: 100 },
+  { id: 102, title: 'Assignment 2', tabId: 10, maxGrade: 100 },
+];
+
+const setup = (overrides = {}): ReturnType<typeof render> =>
+  render(
+    <ConfigureWeightsPrompt
+      assessments={assessments}
+      categories={categories}
+      onClose={jest.fn()}
+      open
+      tabs={tabs}
+      {...overrides}
+    />,
+  );
+
+describe('<ConfigureWeightsPrompt />', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('renders one input per tab grouped by category', () => {
+    setup();
+    expect(screen.getByText('Missions')).toBeInTheDocument();
+    expect(screen.getByLabelText('Assignments')).toHaveValue(50);
+    expect(screen.getByLabelText('Optional')).toHaveValue(50);
+  });
+
+  it('shows Total: 100% with no warning when sum = 100', () => {
+    setup();
+    expect(screen.getByText(/Total:\s*100%/)).toBeInTheDocument();
+    expect(screen.queryByText(/do not sum to 100/i)).not.toBeInTheDocument();
+  });
+
+  it('shows warning when sum != 100', () => {
+    setup();
+    fireEvent.change(screen.getByLabelText('Optional'), {
+      target: { value: '30' },
+    });
+    expect(screen.getByText(/Total:\s*80%/)).toBeInTheDocument();
+    expect(screen.getByText(/do not sum to 100/i)).toBeInTheDocument();
+  });
+
+  it('shows inline error for >100', () => {
+    setup();
+    fireEvent.change(screen.getByLabelText('Assignments'), {
+      target: { value: '101' },
+    });
+    expect(screen.getByText(/must be at most 100/i)).toBeInTheDocument();
+  });
+
+  it('shows inline error for negative', () => {
+    setup();
+    fireEvent.change(screen.getByLabelText('Optional'), {
+      target: { value: '-1' },
+    });
+    expect(screen.getByText(/must be at least 0/i)).toBeInTheDocument();
+  });
+
+  it('Save dispatches updateGradebookWeights with { tabId, weight } only', async () => {
+    setup();
+    fireEvent.change(screen.getByLabelText('Optional'), {
+      target: { value: '40' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /save/i }));
+    await waitFor(() => {
+      expect(operations.updateGradebookWeights).toHaveBeenCalledWith([
+        { tabId: 10, weight: 50 },
+        { tabId: 11, weight: 40 },
+      ]);
+    });
+  });
+
+  it('Cancel does not dispatch', () => {
+    setup();
+    fireEvent.change(screen.getByLabelText('Optional'), {
+      target: { value: '40' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /cancel/i }));
+    expect(operations.updateGradebookWeights).not.toHaveBeenCalled();
+  });
+
+  it('assessment list is hidden by default and shown on expand', () => {
+    setup();
+    expect(screen.queryByText('Assignment 1')).not.toBeVisible();
+    const expandBtns = screen.getAllByRole('button', { name: '' });
+    fireEvent.click(expandBtns[0]);
+    expect(screen.getByText('Assignment 1')).toBeVisible();
+    expect(screen.getByText('Assignment 2')).toBeVisible();
+  });
+
+  it('shows derived % of grade that updates live when weight changes', () => {
+    setup();
+    const expandBtns = screen.getAllByRole('button', { name: '' });
+    fireEvent.click(expandBtns[0]);
+    // weight=50, each assessment is 50% of tab → 25.0% of grade each
+    expect(screen.getAllByText('25.0% of grade')).toHaveLength(2);
+    fireEvent.change(screen.getByLabelText('Assignments'), {
+      target: { value: '60' },
+    });
+    expect(screen.getAllByText('30.0% of grade')).toHaveLength(2);
+  });
+
+  it('disables expand button for tabs with no assessments', () => {
+    setup();
+    const expandBtns = screen.getAllByRole('button', { name: '' });
+    expect(expandBtns[1]).toBeDisabled();
+  });
+
+  it('does not render an Exclude checkbox', () => {
+    setup();
+    expect(
+      screen.queryByRole('checkbox', { name: /exclude/i }),
+    ).not.toBeInTheDocument();
+  });
+});

client/app/bundles/course/gradebook/__tests__/GradebookIndex.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen, waitFor } from 'test-utils';
+import { fireEvent, render, screen, waitFor, within } from 'test-utils';
 
 import toast from 'lib/hooks/toast';
 
@@ -33,6 +33,8 @@ const emptyState = {
     submissions: [],
     gamificationEnabled: false,
     userId: 0,
+    weightedViewEnabled: false,
+    canManageWeights: false,
   },
 };
 
@@ -45,6 +47,8 @@ const noStudentsState = {
     submissions: [],
     gamificationEnabled: false,
     userId: 0,
+    weightedViewEnabled: false,
+    canManageWeights: false,
   },
 };
 
@@ -66,6 +70,8 @@ const populatedState = {
     submissions: [{ studentId: 1, assessmentId: 100, grade: 8 }],
     gamificationEnabled: false,
     userId: 0,
+    weightedViewEnabled: false,
+    canManageWeights: false,
   },
 };
 
@@ -76,6 +82,39 @@ const populatedStateWithGamification = {
   },
 };
 
+const populatedStateWithWeightedView = {
+  gradebook: {
+    ...populatedState.gradebook,
+    weightedViewEnabled: true,
+    canManageWeights: false,
+  },
+};
+
+const populatedStateWithWeightedViewAndGamification = {
+  gradebook: {
+    ...populatedState.gradebook,
+    weightedViewEnabled: true,
+    gamificationEnabled: true,
+    canManageWeights: false,
+  },
+};
+
+const populatedStateManagerWeightedOff = {
+  gradebook: {
+    ...populatedState.gradebook,
+    weightedViewEnabled: false,
+    canManageWeights: true,
+  },
+};
+
+const populatedStateManagerWeightedOn = {
+  gradebook: {
+    ...populatedState.gradebook,
+    weightedViewEnabled: true,
+    canManageWeights: true,
+  },
+};
+
 beforeEach(() => {
   jest.clearAllMocks();
   mockFetchGradebook.mockReturnValue((): Promise<void> => Promise.resolve());
@@ -147,4 +186,66 @@ describe('GradebookIndex', () => {
       ),
     ).toBeInTheDocument();
   });
+
+  it('does not render view toggle when weightedViewEnabled is false', async () => {
+    render(<GradebookIndex />, { state: populatedState });
+    // Wait for loading to finish
+    await screen.findByRole('button', { name: /export/i });
+    expect(screen.queryByText(/by weight/i)).not.toBeInTheDocument();
+  });
+
+  it('renders view toggle when weightedViewEnabled is true', async () => {
+    render(<GradebookIndex />, { state: populatedStateWithWeightedView });
+    expect(await screen.findByText(/all assessments/i)).toBeInTheDocument();
+    expect(await screen.findByText(/by weight/i)).toBeInTheDocument();
+  });
+
+  it('switches to By weight view on toggle click', async () => {
+    render(<GradebookIndex />, { state: populatedStateWithWeightedView });
+    const byWeightButton = await screen.findByText(/by weight/i);
+    fireEvent.click(byWeightButton);
+    expect(
+      await screen.findByTestId('gradebook-weighted-table'),
+    ).toBeInTheDocument();
+  });
+
+  it('weighted view exposes gamification columns in picker when gamification is enabled', async () => {
+    render(<GradebookIndex />, {
+      state: populatedStateWithWeightedViewAndGamification,
+    });
+    const byWeightButton = await screen.findByText(/by weight/i);
+    fireEvent.click(byWeightButton);
+    await screen.findByTestId('gradebook-weighted-table');
+    fireEvent.click(
+      await screen.findByRole('button', { name: /select columns/i }),
+    );
+    const dialog = await screen.findByRole('dialog');
+    expect(within(dialog).getByText('Level')).toBeInTheDocument();
+    expect(within(dialog).getByText('Total XP')).toBeInTheDocument();
+  });
+
+  describe('weighted-view discoverability hint', () => {
+    it('shows the hint to managers when the weighted view is off', async () => {
+      render(<GradebookIndex />, { state: populatedStateManagerWeightedOff });
+      expect(
+        await screen.findByRole('link', { name: /gradebook settings/i }),
+      ).toBeInTheDocument();
+    });
+
+    it('does not show the hint once the weighted view is enabled', async () => {
+      render(<GradebookIndex />, { state: populatedStateManagerWeightedOn });
+      await screen.findByText(/by weight/i); // wait for data to load
+      expect(
+        screen.queryByRole('link', { name: /gradebook settings/i }),
+      ).not.toBeInTheDocument();
+    });
+
+    it('does not show the hint to staff who cannot manage weights', async () => {
+      render(<GradebookIndex />, { state: populatedState });
+      await screen.findByRole('button', { name: /export/i }); // wait for load
+      expect(
+        screen.queryByRole('link', { name: /gradebook settings/i }),
+      ).not.toBeInTheDocument();
+    });
+  });
 });