uikit-react-public 0.11.24 → 0.17.4

package/lib/components/Avatar/Avatar.mdx

@@ -0,0 +1,117 @@
+import * as AvatarStories from "./Avatar.stories";
+import { Meta, Title, Subtitle, Canvas, Controls, ArgTypes } from "@storybook/blocks";
+
+export const usage = {
+  image: `<Avatar
+  variant="image"
+  imageUrl="/sample-avatar-photo.jpg"
+  name="Jane Doe"
+/>`,
+  initials: `<Avatar variant="initials" name="Beverley Haggis" />`,
+  icon: `<Avatar variant="icon" aria-label="Default avatar" />`,
+  size: `<Avatar
+  variant="image"
+  imageUrl="/sample-avatar-photo.jpg"
+  name="Avatar size"
+  size={72}
+/>`,
+  disabled: `<Avatar
+  variant="image"
+  imageUrl="/sample-avatar-photo.jpg"
+  name="Disabled avatar"
+  disabled
+/>`,
+  fallback: `<Avatar
+  variant="image"
+  imageUrl="https://example.com/does-not-exist.jpg"
+  name="Fallback to initials"
+/>`,
+};
+
+<Meta of={AvatarStories} />
+<Title />
+<Subtitle>A circular avatar with graceful fallbacks for images, initials, and icons.</Subtitle>
+
+Use `<Avatar>` anywhere you need a compact visual identifier for a user or entity. The component renders a button for easy focus styling and clickability, and progressively falls back from an image to initials to icon, based on the props you provide.
+
+Key points:
+- `variant="image"` tries to render `imageUrl` first, then initials (from `name`) if the image fails.
+- `variant="initials"` renders initials from `name`; if none are found, it falls back to the icon.
+- `variant="icon"` always renders the default icon.
+- Fixed size options (`48 | 56 | 72 | 80`).
+- Disabled state mutes colors and blocks interaction.
+
+## Variants
+
+### Image (default)
+Renders a photo when `imageUrl` is available. If the image fails to load, initials are shown instead.
+
+<Canvas
+  of={AvatarStories.Image}
+  sourceState="shown"
+  source={{ code: usage.image }}
+/>
+
+### Initials
+Pass a `name` to derive initials (up to two characters). Use when you don't have a photo or want to avoid loading images.
+
+<Canvas
+  of={AvatarStories.Initials}
+  sourceState="shown"
+  source={{ code: usage.initials }}
+/>
+
+### Icon
+Always displays the default avatar icon. Helpful as a generic placeholder.
+
+<Canvas
+  of={AvatarStories.Icon}
+  sourceState="shown"
+  source={{ code: usage.icon }}
+/>
+
+## Sizes
+Pick from the supported sizes to match your layout. Larger sizes are useful for profile headers; smaller for lists or chips.
+
+<Canvas
+  of={AvatarStories.Sizes}
+  sourceState="shown"
+  source={{ code: usage.size }}
+/>
+
+## Disabled
+Prevents interaction and applies muted colors while keeping layout intact.
+
+<Canvas
+  of={AvatarStories.Disabled}
+  sourceState="shown"
+  source={{ code: usage.disabled }}
+/>
+
+## Fallback behaviour
+Image errors are handled gracefully: the component logs an error, then switches to initials. If no initials are available, it renders the icon.
+
+<Canvas
+  of={AvatarStories.BrokenImageFallback}
+  sourceState="shown"
+  source={{ code: usage.fallback }}
+/>
+
+## Accessibility
+- Under the hood, the avatar is a `<button>`. It can receive focus and `onClick` if provided.
+- Provide a meaningful `aria-label` when no visible text is present (e.g. the icon variant).
+- `alt` text on the image defaults to `name` for screen readers.
+- Sizes remain square circles; focus styles come from the theme for keyboard visibility.
+
+## Props
+
+Full props specification for `<Avatar>` is below.
+
+<Canvas
+  of={AvatarStories.Default}
+  sourceState="hidden"
+/>
+
+You can use these controls to manipulate the `<Avatar>` component above.
+
+<Controls of={AvatarStories.Default} />

package/lib/components/Avatar/Avatar.stories.tsx

@@ -1,10 +1,81 @@
+import type { CSSProperties } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import Avatar from './Avatar';
+import Avatar, { type AvatarProps } from './Avatar';
 import sampleAvatarPhoto from '../../../public/sample-avatar-photo.jpg';
 
+type AvatarSize = NonNullable<AvatarProps['size']>;
+const avatarSizes: AvatarSize[] = [48, 56, 72, 80];
+
+const avatarRowStyle: CSSProperties = {
+  display: 'flex',
+  gap: 16,
+  alignItems: 'center',
+  flexWrap: 'wrap',
+};
+
 const meta = {
-  title: 'Components/Ready to use/Avatar',
+  title: 'Components/Avatar',
   component: Avatar,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      description: 'Controls which representation to render',
+      options: ['image', 'initials', 'icon'],
+      control: { type: 'select' },
+      table: { type: { summary: "'image' | 'initials' | 'icon'" } },
+    },
+    imageUrl: {
+      description: 'Image source used when `variant` is `image`',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    name: {
+      description:
+        'Name used for initials and as the fallback alt text for the image',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    size: {
+      description: 'Diameter of the avatar in pixels',
+      options: avatarSizes,
+      control: { type: 'inline-radio' },
+      table: { type: { summary: avatarSizes.join(' | ') } },
+    },
+    disabled: {
+      description: 'Disable interaction and mute colors',
+      control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
+    },
+    testId: {
+      description: 'Applied to the button for testing',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    className: {
+      description: 'Custom className for the root element',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    onClick: {
+      description: 'Click handler forwarded to the underlying button',
+      action: 'clicked',
+      table: {
+        type: {
+          summary: '(event: React.MouseEvent<HTMLButtonElement>) => void',
+        },
+      },
+    },
+  },
+  args: {
+    variant: 'image',
+    imageUrl: sampleAvatarPhoto,
+    name: 'Jane Doe',
+    size: 56,
+    disabled: false,
+  },
+  tags: ['autodocs'],
 } satisfies Meta<typeof Avatar>;
 
 export default meta;
@@ -29,5 +100,42 @@ export const Initials: Story = {
 export const Icon: Story = {
   args: {
     variant: 'icon',
+    name: 'Icon avatar',
+  },
+};
+
+export const Sizes: Story = {
+  name: 'Sizes',
+  args: {
+    imageUrl: sampleAvatarPhoto,
+    name: 'Avatar size',
+  },
+  render: (args) => (
+    <div style={avatarRowStyle}>
+      {avatarSizes.map((size) => (
+        <Avatar
+          key={size}
+          {...args}
+          size={size}
+          aria-label={`Avatar ${size}`}
+        />
+      ))}
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    name: 'Disabled avatar',
+  },
+};
+
+export const BrokenImageFallback: Story = {
+  name: 'Broken image fallback',
+  args: {
+    variant: 'image',
+    imageUrl: 'https://example.com/does-not-exist.jpg',
+    name: 'Fallback to initials',
   },
 };

package/lib/components/Badge/Badge.stories.tsx

@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Badge from './Badge';
+
+const meta = {
+  title: 'Components/Work in progress/Badge',
+  component: Badge,
+  parameters: {
+    layout: 'centered',
+  },
+  args: {
+    children: 'Badge',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Badge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/lib/components/Badge/Badge.tsx

@@ -0,0 +1,48 @@
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+
+export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement> {
+  testId?: string;
+  className?: string;
+}
+
+const NAME = 'ucl-uikit-badge';
+
+const Badge = ({
+  testId = NAME,
+  className,
+  children,
+  ...props
+}: BadgeProps) => {
+  const [theme] = useTheme();
+
+  const baseStyle = css`
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    height: 24px;
+    padding: ${theme.padding.p8};
+    color: ${theme.color.text.secondary};
+    background-color: #e4e4e4; // TODO: Add design token
+    font-family: ${theme.font.family.primary};
+    font-size: ${theme.font.size.f14};
+    font-weight: ${theme.font.weight.regular};
+    border-radius: ${theme.radius.r4};
+    white-space: nowrap;
+  `;
+
+  const style = cx(baseStyle, NAME, className);
+
+  return (
+    <div
+      data-testid={testId}
+      className={style}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export default Badge;

package/lib/components/Badge/index.ts

@@ -0,0 +1,2 @@
+export { default } from './Badge';
+export type { BadgeProps } from './Badge';

package/lib/components/Blanket/Blanket.stories.tsx

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import Blanket from './Blanket';
 
 const meta = {
-  title: 'Components/Ready to use/Blanket',
+  title: 'Components/Blanket',
   component: Blanket,
   parameters: {
     layout: 'fullscreen',

package/lib/components/Breadcrumbs/__tests__/__snapshots__/Breadcrumbs.test.tsx.snap

@@ -36,7 +36,7 @@ exports[`Breadcrumbs > Snapshot: No props 1`] = `
     class="css-4ys53n"
   >
     <a
-      class="ucl-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-hr2cbw"
+      class="ucl-uikit-base-link ucl-uikit-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-c7kkpi"
       data-testid="ucl-timetable-breadcrumb"
       href="/showcase"
     >
@@ -64,7 +64,7 @@ exports[`Breadcrumbs > Snapshot: No props 1`] = `
     class="css-4ys53n"
   >
     <a
-      class="ucl-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-hr2cbw"
+      class="ucl-uikit-base-link ucl-uikit-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-c7kkpi"
       data-testid="ucl-timetable-breadcrumb"
       href="/showcase/breadcrumbs"
     >
@@ -110,7 +110,7 @@ exports[`Breadcrumbs > snapshot: Custom Test ID 1`] = `
     class="css-4ys53n"
   >
     <a
-      class="ucl-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-hr2cbw"
+      class="ucl-uikit-base-link ucl-uikit-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-c7kkpi"
       data-testid="custom-testid-2"
       href="/showcase"
     >
@@ -138,7 +138,7 @@ exports[`Breadcrumbs > snapshot: Custom Test ID 1`] = `
     class="css-4ys53n"
   >
     <a
-      class="ucl-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-hr2cbw"
+      class="ucl-uikit-base-link ucl-uikit-link ucl-timetable-breadcrumb ucl-timetable-breadcrumb--inactive css-c7kkpi"
       data-testid="custom-testid-3"
       href="/showcase/breadcrumbs"
     >

package/lib/components/Button/Button.stories.tsx

@@ -24,7 +24,7 @@ const commonMarginPropsInfo = {
 };
 
 const meta = {
-  title: 'Components/Ready to use/Button',
+  title: 'Components/Button',
   component: Button,
   parameters: {
     layout: 'centered',

package/lib/components/Button/Button.tsx

@@ -11,8 +11,10 @@ import useTheme from '../../theme/useTheme';
 import buttonPrimaryStyle from './buttonPrimaryStyle';
 import buttonSecondaryStyle from './buttonSecondaryStyle';
 import buttonTertiaryStyle from './buttonTertiaryStyle';
-import { Spinner, Overlay, Tooltip } from '../';
-import marginsStyle from '../common/marginsStyle';
+import Spinner from '../Spinner/Spinner';
+import Overlay from '../Overlay/Overlay';
+import Tooltip from '../Tooltip/Tooltip';
+import marginsStyle, { MarginProps } from '../common/marginsStyle';
 
 export const NAME = 'ucl-uikit-button';
 
@@ -34,7 +36,9 @@ export interface ButtonBaseProps {
 export type ButtonProps<C extends ElementType = 'button'> = {
   as?: C;
   ref?: PolymorphicRef<C>;
+  className?: string;
 } & ButtonBaseProps &
+  MarginProps &
   Omit<ComponentPropsWithRef<C>, keyof ButtonBaseProps | 'as'>;
 
 const Button = <C extends ElementType = 'button'>({

package/lib/components/Calendar/Calendar.stories.tsx

@@ -34,17 +34,12 @@ const dateToISOString = (date: Date) => {
 export const Default: Story = {
   render: () => {
     const [args, updateArgs] = useArgs();
-    args.pickedDate = args.pickedDate
-      ? parseDateFromUNIXTimestamp(args.pickedDate)
-      : null;
+    args.pickedDate = args.pickedDate ? parseDateFromUNIXTimestamp(args.pickedDate) : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
-      <Calendar
-        {...args}
-        onDatePick={onDatePick}
-      />
+      <Calendar {...args} onDatePick={onDatePick} />
     );
-  },
+  }
 };
 
 // Story repeated in Datepicker.stories.tsx
@@ -76,17 +71,12 @@ export const WithEvents: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    args.pickedDate = args.pickedDate
-      ? parseDateFromUNIXTimestamp(args.pickedDate)
-      : null;
+    args.pickedDate = args.pickedDate ? parseDateFromUNIXTimestamp(args.pickedDate) : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
-      <Calendar
-        {...args}
-        onDatePick={onDatePick}
-      />
+      <Calendar {...args} onDatePick={onDatePick} />
     );
-  },
+  }
 };
 
 const academicWeeks: AcademicWeek[] = [
@@ -155,17 +145,12 @@ export const WithAcademicWeeks: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    args.pickedDate = args.pickedDate
-      ? parseDateFromUNIXTimestamp(args.pickedDate)
-      : null;
+    args.pickedDate = args.pickedDate ? parseDateFromUNIXTimestamp(args.pickedDate) : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
-      <Calendar
-        {...args}
-        onDatePick={onDatePick}
-      />
+      <Calendar {...args} onDatePick={onDatePick} />
     );
-  },
+  }
 };
 
 // Story repeated in Datepicker.stories.tsx
@@ -195,15 +180,10 @@ export const MinMaxDates: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    args.pickedDate = args.pickedDate
-      ? parseDateFromUNIXTimestamp(args.pickedDate)
-      : null;
+    args.pickedDate = args.pickedDate ? parseDateFromUNIXTimestamp(args.pickedDate) : null;
     const onDatePick = (date: Date | null) => updateArgs({ pickedDate: date });
     return (
-      <Calendar
-        {...args}
-        onDatePick={onDatePick}
-      />
+      <Calendar {...args} onDatePick={onDatePick} />
     );
-  },
+  }
 };

package/lib/components/Calendar/__tests__/Calendar.test.tsx

@@ -8,12 +8,15 @@ const defaultTestId = 'ucl-uikit-calendar';
 const customRender = (ui: React.ReactElement) => {
   return render(ui, {
     wrapper: ({ children }) => (
-      <ThemeContextProvider>{children}</ThemeContextProvider>
+      <ThemeContextProvider>
+        {children}
+      </ThemeContextProvider>
     ),
   });
 };
 
-describe('Calendar', () => {
+describe("Calendar", () => {
+
   beforeAll(() => {
     // Snapshot tests will fail because the Calendar Grid includes styling for "today's date".
     // Therefore, we need to use Vitest to mock the current date.
@@ -21,43 +24,48 @@ describe('Calendar', () => {
     vi.setSystemTime(new Date('2025-03-10')); // Arbitrary fixed date -- Alex's birthday :)
   });
 
-  // Snapshot tests
+  // Snapshot tests 
 
-  test('Snapshot: no date provided', () => {
-    const renderResult = customRender(<Calendar />);
+  test("Snapshot: no date provided", () => {
+    const renderResult = customRender(
+      <Calendar />
+    );
     expect(renderResult.container.firstChild).toMatchSnapshot();
   });
 
-  test('Snapshot: with date provided', () => {
+  test("Snapshot: with date provided", () => {
     const renderResult = customRender(
       <Calendar pickedDate={new Date('2025-01-06')} />
     );
     expect(renderResult.container.firstChild).toMatchSnapshot();
   });
 
-  // Unit tests
+  // Unit tests 
 
-  test('Can be found via default test id', () => {
-    customRender(<Calendar />);
+  test("Can be found via default test id", () => {
+    customRender(
+      <Calendar />
+    );
     const calendar = screen.getByTestId(defaultTestId);
     expect(calendar).toBeInTheDocument();
   });
 
-  test('Can be found custom test id', () => {
+  test("Can be found custom test id", () => {
     const customTestId = '123';
-    customRender(<Calendar testId={customTestId} />);
+    customRender(
+      <Calendar testId={customTestId} />
+    );
     const calendar = screen.getByTestId(customTestId);
     expect(calendar).toBeInTheDocument();
   });
 
-  test('Can pick a date', () => {
+  test("Can pick a date", () => {
     const dateToPick = new Date('2025-03-22');
     const onDatePick = vi.fn();
     customRender(
       <Calendar
-        pickedDate={new Date('2025-03-01')} // To ensure the calendar is displayed for March 2025
-        onDatePick={onDatePick}
-      />
+        pickedDate={new Date('2025-03-01')} // To ensure the calendar is displayed for March 2025 
+        onDatePick={onDatePick} />
     );
     const dayButton = screen.getByText('22');
 

package/lib/components/Calendar/index.ts

@@ -1,6 +1,2 @@
 export { default } from './Calendar';
-export type {
-  CalendarProps,
-  CalendarEvent,
-  AcademicWeek,
-} from './Calendar.types';
+export type { CalendarProps, CalendarEvent, AcademicWeek } from './Calendar.types';

package/lib/components/Calendar/subcomponents/AcademicWeeks.tsx

@@ -13,6 +13,7 @@ interface AcademicWeeksProps {
 }
 
 const AcademicWeeks = ({ date, weeks }: AcademicWeeksProps) => {
+
   const [theme] = useTheme();
 
   const academicWeekNumbers = getAcademicWeekNumbers(weeks, date);
@@ -41,6 +42,6 @@ const AcademicWeeks = ({ date, weeks }: AcademicWeeksProps) => {
       ))}
     </div>
   );
-};
+}
 
 export default AcademicWeeks;

package/lib/components/Calendar/subcomponents/ColumnHeading.tsx

@@ -9,7 +9,11 @@ interface ColumnHeadingProps {
 
 const NAME = 'ucl-uikit-calendar__column-heading';
 
-const ColumnHeading = ({ index, day, isWeekend }: ColumnHeadingProps) => {
+const ColumnHeading = ({
+  index,
+  day,
+  isWeekend
+}: ColumnHeadingProps) => {
   const [theme] = useTheme();
 
   const baseStyle = css`

package/lib/components/Calendar/subcomponents/EventDot.tsx

@@ -9,6 +9,7 @@ interface EventDotProps {
 }
 
 const EventDot = ({ inverted, inCurrentMonth }: EventDotProps) => {
+
   const [theme] = useTheme();
 
   const invertedColour = theme.color.neutral.white;
@@ -33,7 +34,7 @@ const EventDot = ({ inverted, inCurrentMonth }: EventDotProps) => {
     <div
       data-testid={NAME}
       className={style}
-    />
+    />  
   );
 };
 

package/lib/components/Calendar/subcomponents/Grid.tsx

@@ -41,7 +41,6 @@ function createEventsMap(
     }
     eventsMap.get(dateKey)!.push(event);
   });
-  console.log('Events map created:', eventsMap);
   return eventsMap;
 }
 

package/lib/components/Calendar/subcomponents/index.ts

@@ -4,4 +4,4 @@ export { default as AcademicWeek } from './AcademicWeek';
 export { default as Grid } from './Grid';
 export { default as ColumnHeading } from './ColumnHeading';
 export { default as Day } from './Day';
-export { default as EventDot } from './EventDot';
+export { default as EventDot } from './EventDot';