@arbor-education/design-system.components 0.21.1 → 0.23.0

package/dist/utils/hooks/useRovingFocus.d.ts

@@ -0,0 +1,18 @@
+import { type RefObject } from 'react';
+type UseRovingFocusOptions<Target extends string> = {
+    targets: readonly Target[];
+    returnFocusRef?: RefObject<HTMLElement | null>;
+    onActiveTargetChange?: (target: Target | null) => void;
+    onDeleteKey?: (target: Target, event: React.KeyboardEvent<HTMLElement>) => boolean | void;
+};
+export declare const useRovingFocus: <Target extends string>({ targets, returnFocusRef, onActiveTargetChange, onDeleteKey, }: UseRovingFocusOptions<Target>) => {
+    activeTarget: Target | null;
+    focusTarget: (target: Target) => void;
+    getTargetTabIndex: (target: Target) => 0 | -1;
+    handleTargetKeyDown: (event: React.KeyboardEvent<HTMLElement>, target: Target) => void;
+    queueFocusRecovery: (target: Target) => void;
+    registerTarget: (target: Target, node: HTMLElement | null) => void;
+    setActiveTarget: (target: Target | null) => void;
+};
+export {};
+//# sourceMappingURL=useRovingFocus.d.ts.map

package/dist/utils/hooks/useRovingFocus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRovingFocus.d.ts","sourceRoot":"","sources":["../../../src/utils/hooks/useRovingFocus.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6D,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAMlG,KAAK,qBAAqB,CAAC,MAAM,SAAS,MAAM,IAAI;IAClD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACvD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,KAAK,OAAO,GAAG,IAAI,CAAC;CAC3F,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,MAAM,EAAE,iEAKnD,qBAAqB,CAAC,MAAM,CAAC;;0BAaW,MAAM;gCAkHA,MAAM,KAAG,CAAC,GAAG,CAAC,CAAC;iCAlDd,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,UAAU,MAAM;iCA9ChD,MAAM;6BATV,MAAM,QAAQ,WAAW,GAAG,IAAI;8BAd/B,MAAM,GAAG,IAAI;CAwI3D,CAAC"}

package/dist/utils/hooks/useRovingFocus.js

@@ -0,0 +1,130 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+export const useRovingFocus = ({ targets, returnFocusRef, onActiveTargetChange, onDeleteKey, }) => {
+    const [activeTarget, setActiveTargetState] = useState(null);
+    const targetRefs = useRef(new Map());
+    const pendingFocusRecoveryRef = useRef(null);
+    const returnFocusRefRef = useRef(returnFocusRef);
+    returnFocusRefRef.current = returnFocusRef;
+    const setActiveTarget = useCallback((target) => {
+        setActiveTargetState(target);
+        onActiveTargetChange?.(target);
+    }, [onActiveTargetChange]);
+    const focusTarget = useCallback((target) => {
+        targetRefs.current.get(target)?.focus();
+    }, []);
+    const moveFocus = useCallback((target) => {
+        focusTarget(target);
+        setActiveTarget(target);
+    }, [focusTarget, setActiveTarget]);
+    const registerTarget = useCallback((target, node) => {
+        if (node) {
+            targetRefs.current.set(target, node);
+        }
+        else {
+            targetRefs.current.delete(target);
+        }
+    }, []);
+    const queueFocusRecovery = useCallback((target) => {
+        const targetIndex = targets.indexOf(target);
+        if (targetIndex < 0)
+            return;
+        pendingFocusRecoveryRef.current = { targetIndex };
+    }, [targets]);
+    useEffect(() => {
+        if (targets.length === 0) {
+            if (activeTarget !== null) {
+                setActiveTarget(null);
+            }
+            return;
+        }
+        if (activeTarget === null || !targets.includes(activeTarget)) {
+            setActiveTarget(targets[0] ?? null);
+        }
+    }, [activeTarget, setActiveTarget, targets]);
+    useLayoutEffect(() => {
+        const pendingFocusRecovery = pendingFocusRecoveryRef.current;
+        if (!pendingFocusRecovery)
+            return;
+        pendingFocusRecoveryRef.current = null;
+        if (targets.length > 0) {
+            const nextTarget = targets[Math.min(pendingFocusRecovery.targetIndex, targets.length - 1)];
+            if (nextTarget !== undefined) {
+                moveFocus(nextTarget);
+                return;
+            }
+        }
+        returnFocusRef?.current?.focus();
+        setActiveTarget(null);
+    }, [moveFocus, returnFocusRef, setActiveTarget, targets]);
+    useLayoutEffect(() => () => {
+        if (!pendingFocusRecoveryRef.current)
+            return;
+        pendingFocusRecoveryRef.current = null;
+        returnFocusRefRef.current?.current?.focus();
+    }, []);
+    const handleTargetKeyDown = useCallback((event, target) => {
+        const targetIndex = targets.indexOf(target);
+        if (targetIndex < 0)
+            return;
+        switch (event.key) {
+            case 'ArrowLeft':
+            case 'ArrowUp': {
+                event.preventDefault();
+                const previousTarget = targets[Math.max(0, targetIndex - 1)];
+                if (previousTarget !== undefined) {
+                    moveFocus(previousTarget);
+                }
+                break;
+            }
+            case 'ArrowRight':
+            case 'ArrowDown': {
+                event.preventDefault();
+                const nextTarget = targets[Math.min(targets.length - 1, targetIndex + 1)];
+                if (nextTarget !== undefined) {
+                    moveFocus(nextTarget);
+                }
+                break;
+            }
+            case 'Home':
+                event.preventDefault();
+                if (targets[0] !== undefined) {
+                    moveFocus(targets[0]);
+                }
+                break;
+            case 'End': {
+                event.preventDefault();
+                const lastTarget = targets[targets.length - 1];
+                if (lastTarget !== undefined) {
+                    moveFocus(lastTarget);
+                }
+                break;
+            }
+            case 'Backspace':
+            case 'Delete': {
+                const shouldRecoverFocus = onDeleteKey?.(target, event);
+                if (shouldRecoverFocus) {
+                    queueFocusRecovery(target);
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }, [moveFocus, onDeleteKey, queueFocusRecovery, targets]);
+    const getTargetTabIndex = useCallback((target) => {
+        if (activeTarget === null) {
+            return targets[0] === target ? 0 : -1;
+        }
+        return activeTarget === target ? 0 : -1;
+    }, [activeTarget, targets]);
+    return {
+        activeTarget,
+        focusTarget,
+        getTargetTabIndex,
+        handleTargetKeyDown,
+        queueFocusRecovery,
+        registerTarget,
+        setActiveTarget,
+    };
+};
+//# sourceMappingURL=useRovingFocus.js.map

package/dist/utils/hooks/useRovingFocus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRovingFocus.js","sourceRoot":"","sources":["../../../src/utils/hooks/useRovingFocus.ts"],"names":[],"mappings":"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"}

package/dist/utils/hooks/useRovingFocus.test.d.ts

@@ -0,0 +1,2 @@
+import '@testing-library/jest-dom/vitest';
+//# sourceMappingURL=useRovingFocus.test.d.ts.map

package/dist/utils/hooks/useRovingFocus.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRovingFocus.test.d.ts","sourceRoot":"","sources":["../../../src/utils/hooks/useRovingFocus.test.tsx"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC"}

package/dist/utils/hooks/useRovingFocus.test.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useRef, useState } from 'react';
+import { describe, expect, test } from 'vitest';
+import { useRovingFocus } from './useRovingFocus.js';
+const labels = {
+    one: 'One',
+    two: 'Two',
+    three: 'Three',
+};
+const RovingExample = ({ initialTargets = ['one', 'two', 'three'], returnFocusOnEmpty = false, }) => {
+    const [targets, setTargets] = useState(initialTargets);
+    const returnFocusRef = useRef(null);
+    const { getTargetTabIndex, handleTargetKeyDown, registerTarget, } = useRovingFocus({
+        targets,
+        returnFocusRef,
+        onDeleteKey: (target) => {
+            setTargets(currentTargets => currentTargets.filter(currentTarget => currentTarget !== target));
+            return true;
+        },
+    });
+    return (_jsxs(_Fragment, { children: [targets.map(target => (_jsx("button", { ref: node => registerTarget(target, node), tabIndex: getTargetTabIndex(target), type: "button", onKeyDown: event => handleTargetKeyDown(event, target), children: labels[target] }, target))), returnFocusOnEmpty && (_jsx("button", { ref: returnFocusRef, type: "button", children: "Return target" }))] }));
+};
+describe('useRovingFocus', () => {
+    test('moves focus through targets with arrow keys and Home/End', async () => {
+        const user = userEvent.setup();
+        render(_jsx(RovingExample, {}));
+        expect(screen.getByRole('button', { name: 'One' })).toHaveAttribute('tabindex', '0');
+        expect(screen.getByRole('button', { name: 'Two' })).toHaveAttribute('tabindex', '-1');
+        await user.tab();
+        expect(screen.getByRole('button', { name: 'One' })).toHaveFocus();
+        await user.keyboard('{ArrowRight}');
+        expect(screen.getByRole('button', { name: 'Two' })).toHaveFocus();
+        expect(screen.getByRole('button', { name: 'Two' })).toHaveAttribute('tabindex', '0');
+        await user.keyboard('{End}');
+        expect(screen.getByRole('button', { name: 'Three' })).toHaveFocus();
+        await user.keyboard('{Home}');
+        expect(screen.getByRole('button', { name: 'One' })).toHaveFocus();
+    });
+    test('recovers focus to the next target after deletion', async () => {
+        const user = userEvent.setup();
+        render(_jsx(RovingExample, { initialTargets: ['one', 'two'] }));
+        await user.tab();
+        expect(screen.getByRole('button', { name: 'One' })).toHaveFocus();
+        await user.keyboard('{Delete}');
+        expect(screen.getByRole('button', { name: 'Two' })).toHaveFocus();
+    });
+    test('returns focus to the fallback element when all targets are removed', async () => {
+        const user = userEvent.setup();
+        render(_jsx(RovingExample, { initialTargets: ['one'], returnFocusOnEmpty: true }));
+        await user.tab();
+        expect(screen.getByRole('button', { name: 'One' })).toHaveFocus();
+        await user.keyboard('{Delete}');
+        expect(screen.getByRole('button', { name: 'Return target' })).toHaveFocus();
+    });
+});
+//# sourceMappingURL=useRovingFocus.test.js.map

package/dist/utils/hooks/useRovingFocus.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRovingFocus.test.js","sourceRoot":"","sources":["../../../src/utils/hooks/useRovingFocus.test.tsx"],"names":[],"mappings":"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"}

package/dist/utils/spacedWidths.d.ts

@@ -0,0 +1,3 @@
+export declare const sumSpacedWidths: (widths: number[], gap: number, visibleCount?: number) => number;
+export declare const fitSpacedWidths: (availableWidth: number, widths: number[], gap: number) => number;
+//# sourceMappingURL=spacedWidths.d.ts.map

package/dist/utils/spacedWidths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spacedWidths.d.ts","sourceRoot":"","sources":["../../src/utils/spacedWidths.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,GAC1B,QAAQ,MAAM,EAAE,EAChB,KAAK,MAAM,EACX,eAAc,MAAsB,KACnC,MAaF,CAAC;AAEF,eAAO,MAAM,eAAe,GAC1B,gBAAgB,MAAM,EACtB,QAAQ,MAAM,EAAE,EAChB,KAAK,MAAM,KACV,MAaF,CAAC"}

package/dist/utils/spacedWidths.js

@@ -0,0 +1,28 @@
+export const sumSpacedWidths = (widths, gap, visibleCount = widths.length) => {
+    const boundedCount = Math.max(0, Math.min(visibleCount, widths.length));
+    if (boundedCount === 0)
+        return 0;
+    let usedWidth = 0;
+    for (let index = 0; index < boundedCount; index += 1) {
+        usedWidth += widths[index] ?? 0;
+        if (index > 0) {
+            usedWidth += gap;
+        }
+    }
+    return usedWidth;
+};
+export const fitSpacedWidths = (availableWidth, widths, gap) => {
+    if (availableWidth <= 0 || widths.length === 0)
+        return 0;
+    let usedWidth = 0;
+    let visibleCount = 0;
+    for (let index = 0; index < widths.length; index += 1) {
+        const requiredWidth = (widths[index] ?? 0) + (index > 0 ? gap : 0);
+        if (usedWidth + requiredWidth > availableWidth)
+            break;
+        usedWidth += requiredWidth;
+        visibleCount += 1;
+    }
+    return visibleCount;
+};
+//# sourceMappingURL=spacedWidths.js.map

package/dist/utils/spacedWidths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spacedWidths.js","sourceRoot":"","sources":["../../src/utils/spacedWidths.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,MAAgB,EAChB,GAAW,EACX,eAAuB,MAAM,CAAC,MAAM,EAC5B,EAAE;IACV,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,IAAI,YAAY,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEjC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,YAAY,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,SAAS,IAAI,GAAG,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,cAAsB,EACtB,MAAgB,EAChB,GAAW,EACH,EAAE;IACV,IAAI,cAAc,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEzD,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,aAAa,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,IAAI,SAAS,GAAG,aAAa,GAAG,cAAc;YAAE,MAAM;QACtD,SAAS,IAAI,aAAa,CAAC;QAC3B,YAAY,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC,CAAC"}

package/dist/utils/spacedWidths.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spacedWidths.test.d.ts.map

package/dist/utils/spacedWidths.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spacedWidths.test.d.ts","sourceRoot":"","sources":["../../src/utils/spacedWidths.test.ts"],"names":[],"mappings":""}

package/dist/utils/spacedWidths.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'vitest';
+import { fitSpacedWidths, sumSpacedWidths } from './spacedWidths.js';
+describe('spacedWidths', () => {
+    test('sums widths with gaps between visible items', () => {
+        expect(sumSpacedWidths([40, 50, 60], 8, 2)).toBe(98);
+    });
+    test('returns zero summed width when no items are visible', () => {
+        expect(sumSpacedWidths([40, 50, 60], 8, 0)).toBe(0);
+    });
+    test('fits the number of items that can be shown within the available width', () => {
+        expect(fitSpacedWidths(102, [40, 50, 60], 8)).toBe(2);
+    });
+    test('returns zero fitted items when no width is available', () => {
+        expect(fitSpacedWidths(0, [40, 50], 8)).toBe(0);
+    });
+});
+//# sourceMappingURL=spacedWidths.test.js.map

package/dist/utils/spacedWidths.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spacedWidths.test.js","sourceRoot":"","sources":["../../src/utils/spacedWidths.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAErE,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,IAAI,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC/D,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,uEAAuE,EAAE,GAAG,EAAE;QACjF,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbor-education/design-system.components",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "The component library for the design system (the baby)",
   "main": "dist/index.js",
   "type": "module",

package/src/components/articleCard/ArticleCard.stories.tsx

@@ -37,7 +37,7 @@ const USAGE_GUIDANCE = [
   '|---|---|',
   '| Displaying a metric or statistic | [`KPICard`](?path=/docs/components-card-kpicard--docs) |',
   '| Full control over interior layout | [`Card`](?path=/docs/components-card--docs) directly |',
-  '| Icon + text without a card shell | [`IcoText`](?path=/docs/components-icotext--docs) |',
+  '| Icon + text without a card shell | [`IconText`](?path=/docs/components-icontext--docs) |',
   '| Selecting from a list (radio/checkbox semantics) | `RadioGroup` or selection list pattern |',
 ].join('\n');
 
@@ -64,7 +64,7 @@ const DEVELOPER_NOTES = [
   '### Accessibility',
   '',
   '- **Linked mode**: the `<a>` wrapping `title` is the accessible link target.',
-  '  If the title text is not self-descriptive, use `aria-label` to override the accessible name.',
+  '  Use self-descriptive link text in `title`, because the outer `aria-label` does not rename the inner link.',
   '- **Shell mode**: `aria-label` or `aria-labelledby` is required when `onClick` is provided.',
   '- **Decorative icons**: omit `iconScreenReaderText` — the icon is `aria-hidden="true"` automatically.',
   '',
@@ -81,7 +81,7 @@ const DEVELOPER_NOTES = [
 const RELATED_COMPONENTS = [
   '## Related components',
   '',
-  '[Card](?path=/docs/components-card--docs) · [KPICard](?path=/docs/components-card-kpicard--docs) · [IcoText](?path=/docs/components-icotext--docs) · [Tag](?path=/docs/components-tag--docs)',
+  '[Card](?path=/docs/components-card--docs) · [KPICard](?path=/docs/components-card-kpicard--docs) · [IconText](?path=/docs/components-icontext--docs) · [Tag](?path=/docs/components-tag--docs)',
 ].join('\n');
 
 const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
@@ -137,7 +137,7 @@ const meta = {
     'icon': {
       control: { type: 'select' },
       options: [undefined, 'eye', 'guardians', 'date', 'book-open', 'file', 'settings', 'info', 'triangle-alert'],
-      description: 'Icon displayed in the left rail via `IcoText.Icon`. Omit for icon-free layout.',
+      description: 'Icon displayed in the left rail via `IconText.Icon`. Omit for icon-free layout.',
       table: { type: { summary: 'IconName' } },
     },
     'iconColor': {
@@ -176,8 +176,13 @@ const meta = {
       description: 'Accessible name. Required on interactive shell cards (when `onClick` is provided).',
       table: { type: { summary: 'string' } },
     },
-    'href': {
+    'aria-labelledby': {
       control: 'text',
+      description: 'Alternative accessible name for interactive shell cards when a visible label already exists in the card content.',
+      table: { type: { summary: 'string' } },
+    },
+    'href': {
+      control: false,
       description: 'URL. Mutually exclusive with `onClick`. When provided with `title` + `!disabled`, the title renders as a navigable `<a>`.',
       table: { type: { summary: 'string' } },
     },
@@ -190,7 +195,7 @@ const meta = {
 } satisfies Meta<typeof ArticleCard>;
 
 export default meta;
-type Story = StoryObj<typeof ArticleCard>;
+type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
 // Helper: attach a per-story description to docs
@@ -356,7 +361,7 @@ function FullCompositionExample() {
       iconColor="var(--color-semantic-warning-600)"
       tagText="Pending review"
       tagColor="yellow"
-      onClick={() => console.log('navigate to report')}
+      onClick={() => {}}
       aria-label="Spring term behaviour report"
     />
   );
@@ -375,7 +380,7 @@ export default FullCompositionExample;
           iconColor="var(--color-semantic-warning-600)"
           tagText="Pending review"
           tagColor="yellow"
-          onClick={fn()}
+          onClick={() => {}}
           aria-label="Spring term behaviour report"
         />
       </div>
@@ -440,7 +445,7 @@ import { ArticleCard } from '@arbor-education/design-system.components';
 function InteractiveShellExample() {
   return (
     <ArticleCard
-      onClick={() => console.log('card clicked')}
+      onClick={() => {}}
       aria-label="Year 10 progress report"
       title="Year 10 progress report"
       paragraph="Mid-year review — targets, attainment, and next steps."
@@ -456,7 +461,7 @@ export default InteractiveShellExample;
     render: () => (
       <div style={{ maxWidth: '400px' }}>
         <ArticleCard
-          onClick={fn()}
+          onClick={() => {}}
           aria-label="Year 10 progress report"
           title="Year 10 progress report"
           paragraph="Mid-year review — targets, attainment, and next steps."
@@ -498,7 +503,7 @@ export default DisabledExample;
     render: () => (
       <div style={{ maxWidth: '400px' }}>
         <ArticleCard
-          onClick={fn()}
+          onClick={() => {}}
           aria-label="Summer term report — not yet available"
           title="Summer term report"
           paragraph="This report will be available at the end of term."
@@ -508,7 +513,7 @@ export default DisabledExample;
       </div>
     ),
   },
-  '`disabled=true` dims the card and suppresses all interaction. In interactive shell mode, `onClick` does not fire. The card is removed from the tab order.',
+  '`disabled=true` dims the card and suppresses activation. In interactive shell mode, `onClick` no longer fires, but the card still renders with `role="button"`, `tabIndex={0}`, and `aria-disabled={true}`.',
 );
 
 export const LinkedDisabled: Story = withDescription(

package/src/components/articleCard/ArticleCard.tsx

@@ -1,16 +1,16 @@
 import classNames from 'classnames';
-import type { IcoTextIconProps } from 'Components/icoText/IcoText';
+import type { IconTextIconProps } from 'Components/iconText/IconText';
 import type { TagColor } from 'Components/tag/Tag';
 import { Tag } from 'Components/tag/Tag';
 import type { IconName } from 'Components/icon/allowedIcons';
 import { Card, getCardInteractionProps } from 'Components/card/Card';
-import { IcoText } from 'Components/icoText/IcoText';
+import { IconText } from 'Components/iconText/IconText';
 
 type ArticleCardBaseProps = {
   className?: string;
   paragraph?: React.ReactNode;
   icon?: IconName;
-  iconColor?: IcoTextIconProps['color'];
+  iconColor?: IconTextIconProps['color'];
   disabled?: boolean;
   tagText?: string;
   tagColor?: TagColor;
@@ -62,16 +62,16 @@ export const ArticleCard = (props: ArticleCardProps): React.JSX.Element => {
 
   const content = (
     <article className="ds-article-card">
-      <IcoText>
+      <IconText>
         {icon && (
-          <IcoText.Icon
+          <IconText.Icon
             color={iconColor}
             name={icon}
             screenReaderText={iconScreenReaderText}
           />
         )}
         {title && (
-          <IcoText.Heading>
+          <IconText.Heading>
             {hasPrimaryLink
               ? (
                   <a className="ds-article-card__primary-link" href={href}>
@@ -79,11 +79,11 @@ export const ArticleCard = (props: ArticleCardProps): React.JSX.Element => {
                   </a>
                 )
               : title}
-          </IcoText.Heading>
+          </IconText.Heading>
         )}
-        {paragraph && <IcoText.Paragraph>{paragraph}</IcoText.Paragraph>}
+        {paragraph && <IconText.Paragraph>{paragraph}</IconText.Paragraph>}
         {tagText && <Tag color={tagColor}>{tagText}</Tag>}
-      </IcoText>
+      </IconText>
     </article>
   );