feat: support slot ID aliases (#178)

Add idAliases prop to Slot, allowing operations configured under
deprecated slot IDs to continue applying after a slot is renamed.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: brian-smith-tcril

runtime/slots/Slot.test.tsx

@@ -4,6 +4,8 @@ import { useContext } from 'react';
 import { useLayoutForSlotId } from './layout/hooks';
 import Slot from './Slot';
 import SlotContext from './SlotContext';
+import { getSiteConfig, setSiteConfig } from '../config';
+import { WidgetOperationTypes } from '.';
 
 jest.mock('./layout/hooks');
 
@@ -38,3 +40,33 @@ describe('Slot component', () => {
     expect(getByText('Custom Layout Element')).toBeInTheDocument();
   });
 });
+
+const TestSlot = () => <Slot id="new-slot.ui" idAliases={['old-slot.ui']} />;
+
+describe('Slot component with site config operations', () => {
+  beforeEach(() => {
+    (useLayoutForSlotId as jest.Mock).mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    setSiteConfig({ ...getSiteConfig(), apps: [] });
+  });
+
+  it('renders widgets configured under the primary slot id', async () => {
+    setSiteConfig({
+      ...getSiteConfig(),
+      apps: [{ appId: 'test-app', slots: [{ slotId: 'new-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: <div>Primary Widget</div> }] }],
+    });
+    const { findByText } = render(<MemoryRouter><TestSlot /></MemoryRouter>);
+    await findByText('Primary Widget');
+  });
+
+  it('renders widgets configured under an alias slot id', async () => {
+    setSiteConfig({
+      ...getSiteConfig(),
+      apps: [{ appId: 'test-app', slots: [{ slotId: 'old-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: <div>Alias Widget</div> }] }],
+    });
+    const { findByText } = render(<MemoryRouter><TestSlot /></MemoryRouter>);
+    await findByText('Alias Widget');
+  });
+});

runtime/slots/Slot.tsx

@@ -2,15 +2,18 @@ import { ComponentType, createElement, isValidElement, ReactNode } from 'react';
 import DefaultSlotLayout from './layout/DefaultSlotLayout';
 import { useLayoutForSlotId } from './layout/hooks';
 import SlotContext from './SlotContext';
+import { useSlotContext } from './hooks';
 
 interface SlotProps {
   id: string,
+  idAliases?: string[],
   children?: ReactNode,
   layout?: ComponentType | ReactNode,
   [key: string]: unknown,
 }
 
-export default function Slot({ id, children, layout = DefaultSlotLayout, ...props }: SlotProps) {
+function SlotRenderer({ layout }: { layout: ComponentType | ReactNode }) {
+  const { id } = useSlotContext();
   let layoutElement: ComponentType | ReactNode = layout;
 
   const overrideLayout = useLayoutForSlotId(id);
@@ -24,9 +27,13 @@ export default function Slot({ id, children, layout = DefaultSlotLayout, ...prop
     layoutElement = createElement(layoutElement as ComponentType);
   }
 
+  return <>{layoutElement}</>;
+}
+
+export default function Slot({ id, idAliases, children, layout = DefaultSlotLayout, ...props }: SlotProps) {
   return (
-    <SlotContext.Provider value={{ id, children, ...props }}>
-      {layoutElement}
+    <SlotContext.Provider value={{ id, idAliases, children, ...props }}>
+      <SlotRenderer layout={layout} />
     </SlotContext.Provider>
   );
 }

runtime/slots/SlotContext.tsx

@@ -1,6 +1,6 @@
 import { createContext, ReactNode } from 'react';
 
-const SlotContext = createContext<{ id: string, children?: ReactNode, [key: string]: unknown }>({
+const SlotContext = createContext<{ id: string, idAliases?: string[], children?: ReactNode, [key: string]: unknown }>({
   id: '',
   children: null,
 });

runtime/slots/hooks.ts

@@ -12,7 +12,7 @@ import { createWidgetAppendOperation } from './widget';
  * config as it changes.
  */
 export function useSlotOperations(id: string) {
-  const { children } = useSlotContext();
+  const { children, idAliases } = useSlotContext();
   const location = useLocation();
   const [operations, setOperations] = useState<SlotOperation[]>([]);
 
@@ -21,11 +21,11 @@ export function useSlotOperations(id: string) {
     // when [children] props change.  This avoids an endless render loop.  After all, the whole
     // point of a slot is to modify its children via slot operations.
     const defaultOperation = createWidgetAppendOperation('defaultContent', id, children);
-    setOperations(getSlotOperations(id, defaultOperation));
+    setOperations(getSlotOperations([id, ...(idAliases ?? [])], defaultOperation));
 
     // We depend on [location] to force re-renders on navigation.  This guarantees changes in active
     // roles (and thus, changes in what conditional widgets are shown) properly.
-  }, [id, children, location]);
+  }, [id, children, idAliases, location]);
 
   return operations;
 }

runtime/slots/utils.test.ts

@@ -8,20 +8,20 @@ jest.mock('../config');
 describe('getSlotOperations', () => {
   it('should return an empty array if no apps are configured', () => {
     (getSiteConfig as jest.Mock).mockReturnValue({ apps: [] });
-    const result = getSlotOperations('test-slot.ui');
+    const result = getSlotOperations(['test-slot.ui']);
     expect(result).toEqual([]);
   });
 
   it('should return an empty array if no slots are present in apps', () => {
     (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: [] }] });
-    const result = getSlotOperations('test-slot.ui');
+    const result = getSlotOperations(['test-slot.ui']);
     expect(result).toEqual([]);
   });
 
   it('should return an empty array if no matching slotId is found', () => {
     const mockSlots: SlotOperation[] = [{ slotId: 'other-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' }];
     (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: mockSlots }] });
-    const result = getSlotOperations('test-slot.ui');
+    const result = getSlotOperations(['test-slot.ui']);
     expect(result).toEqual([]);
   });
 
@@ -32,7 +32,7 @@ describe('getSlotOperations', () => {
       { slotId: 'other-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget3', element: '' },
     ];
     (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: mockSlots }] });
-    const result = getSlotOperations('test-slot.ui');
+    const result = getSlotOperations(['test-slot.ui']);
     expect(result).toEqual([
       { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
       { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
@@ -55,10 +55,24 @@ describe('getSlotOperations', () => {
         }
       ]
     });
-    const result = getSlotOperations('test-slot.ui');
+    const result = getSlotOperations(['test-slot.ui']);
     expect(result).toEqual([
       { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
       { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
     ]);
   });
+
+  it('should return operations matching both the primary id and an alias id', () => {
+    const mockSlots: SlotOperation[] = [
+      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
+      { slotId: 'test-slot-alias.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
+      { slotId: 'other-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget3', element: '' },
+    ];
+    (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: mockSlots }] });
+    const result = getSlotOperations(['test-slot.ui', 'test-slot-alias.ui']);
+    expect(result).toEqual([
+      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
+      { slotId: 'test-slot-alias.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
+    ]);
+  });
 });

runtime/slots/utils.ts

@@ -2,7 +2,7 @@ import { getAuthenticatedUser } from '../auth';
 import { getActiveRoles, getSiteConfig } from '../config';
 import { SlotOperation } from './types';
 
-export function getSlotOperations(id: string, defaultOperation?: SlotOperation) {
+export function getSlotOperations(ids: string[], defaultOperation?: SlotOperation) {
   const { apps } = getSiteConfig();
   const ops: SlotOperation[] = [];
 
@@ -14,7 +14,7 @@ export function getSlotOperations(id: string, defaultOperation?: SlotOperation)
     apps.forEach((app) => {
       if (Array.isArray(app.slots)) {
         app.slots.forEach((operation) => {
-          if (operation.slotId === id) {
+          if (ids.includes(operation.slotId)) {
             ops.push(operation);
           }
         });