uikit-react-public 0.14.21 → 0.17.4

package/dist/utils/__tests__/announce.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/announce.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Announces a message to screen readers.
+ */
+declare const announce: (message: string, force?: boolean) => void;
+export declare const __resetForTesting: () => void;
+export default announce;

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { default as announce } from './announce';

package/lib/components/Accordion/Accordion.Heading.tsx

@@ -1,14 +1,13 @@
-import React, { HTMLAttributes, JSX } from 'react';
+import React, { HTMLAttributes } from 'react';
 import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
 import Icon from '../Icon/Icon';
 import { useAccordionContext } from './Accordion';
 
-export const NAME = 'ucl-accordion__heading';
+export const NAME = 'ucl-uikit-accordion__heading';
 
-interface AccordionHeadingProps
-  extends HTMLAttributes<HTMLElement> {
-  as?: keyof JSX.IntrinsicElements;
+export interface AccordionHeadingProps extends HTMLAttributes<HTMLElement> {
+  as?: keyof HTMLElementTagNameMap;
   testId?: string;
 }
 
@@ -19,13 +18,21 @@ const AccordionHeading: React.FC<AccordionHeadingProps> = ({
   className,
 }) => {
   const [theme] = useTheme();
-  const { isOpen, toggleAccordion, disabled, size } =
-    useAccordionContext();
+  const { isOpen, toggleAccordion, disabled, size } = useAccordionContext();
+
+  const handleKeyDown: React.KeyboardEventHandler<HTMLElement> = (e) => {
+    if (disabled) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      toggleAccordion();
+    }
+  };
 
   const headingStyle = cx(
     NAME,
     css`
       display: flex;
+      position: relative;
       justify-content: space-between;
       align-items: center;
       padding: ${theme.padding.p16};
@@ -35,6 +42,14 @@ const AccordionHeading: React.FC<AccordionHeadingProps> = ({
       transition:
         background-color 0.3s ease,
         box-shadow 0.3s ease;
+      margin: 0;
+      border: none;
+      outline: none;
+      text-decoration: none;
+      box-sizing: border-box;
+      width: 100%;
+      font-size: inherit;
+      line-height: inherit;
 
       &:hover {
         background-color: ${!disabled
@@ -45,6 +60,7 @@ const AccordionHeading: React.FC<AccordionHeadingProps> = ({
       &:focus-visible {
         outline: none;
         box-shadow: ${theme.boxShadow.focus};
+        z-index: 20;
       }
     `,
     className
@@ -54,6 +70,7 @@ const AccordionHeading: React.FC<AccordionHeadingProps> = ({
     <Component
       className={headingStyle}
       data-testid={testId}
+      onKeyDown={handleKeyDown}
       onClick={!disabled ? toggleAccordion : undefined}
       role='button'
       tabIndex={0}
@@ -65,7 +82,9 @@ const AccordionHeading: React.FC<AccordionHeadingProps> = ({
         className={css`
           transform: rotate(${isOpen ? '180deg' : '0deg'});
           transition: transform 0.15s ease;
-          color: ${theme.color.interaction.blue70};
+          color: ${disabled
+            ? theme.color.text.disabled
+            : theme.color.interaction.blue70};
         `}
       />
     </Component>

package/lib/components/Accordion/Accordion.Panel.tsx

@@ -3,10 +3,9 @@ import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
 import { useAccordionContext } from './Accordion';
 
-export const NAME = 'ucl-accordion__panel';
+export const NAME = 'ucl-uikit-accordion__panel';
 
-interface AccordionPanelProps
-  extends HTMLAttributes<HTMLDivElement> {
+export interface AccordionPanelProps extends HTMLAttributes<HTMLDivElement> {
   testId?: string;
 }
 
@@ -24,12 +23,21 @@ const AccordionPanel: React.FC<AccordionPanelProps> = ({
     NAME,
 
     css`
+      position: relative;
+      width: 100%;
+      max-width: 100%;
+      min-width: 0;
+      flex-shrink: 1;
       padding: ${theme.padding.p16};
       font-family: ${theme.font.family.primary};
       font-weight: ${theme.font.weight.regular};
       background-color: ${theme.color.neutral.white};
       font-size: ${theme.font.size.f16};
       color: ${theme.color.text.primary};
+      box-sizing: border-box;
+      overflow: hidden;
+      overflow-wrap: break-word;
+      word-break: break-word;
     `,
     className
   );

package/lib/components/Accordion/Accordion.stories.tsx

@@ -0,0 +1,139 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Accordion from './Accordion';
+
+const meta = {
+  title: 'Components/Accordion',
+  component: Accordion,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    size: {
+      options: ['small', 'medium'],
+      control: { type: 'select' },
+      type: 'string',
+    },
+    disabled: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+    },
+    isOpen: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+    },
+    testId: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+    className: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+  },
+  args: {
+    isOpen: false,
+    disabled: false,
+    size: 'medium',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Accordion>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    isOpen: false,
+    disabled: false,
+    size: 'medium',
+  },
+  render: (args) => (
+    <Accordion {...args}>
+      <Accordion.Heading>Heading</Accordion.Heading>
+      <Accordion.Panel>Panel Content</Accordion.Panel>
+    </Accordion>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    isOpen: false,
+    disabled: true,
+    size: 'medium',
+  },
+  render: (args) => (
+    <Accordion {...args}>
+      <Accordion.Heading>Heading</Accordion.Heading>
+      <Accordion.Panel>Panel Content</Accordion.Panel>
+    </Accordion>
+  ),
+};
+
+export const SmallSize: Story = {
+  args: {
+    isOpen: false,
+    disabled: false,
+    size: 'small',
+  },
+  render: (args) => (
+    <Accordion {...args}>
+      <Accordion.Heading>Heading</Accordion.Heading>
+      <Accordion.Panel>Panel Content</Accordion.Panel>
+    </Accordion>
+  ),
+};
+
+export const CustomHeadingElement: Story = {
+  args: {
+    isOpen: false,
+    disabled: false,
+    size: 'medium',
+  },
+  render: (args) => (
+    <Accordion {...args}>
+      <Accordion.Heading as='h2'>Custom Heading as H2</Accordion.Heading>
+      <Accordion.Panel>
+        <p>This is the content of the accordion.</p>
+      </Accordion.Panel>
+    </Accordion>
+  ),
+};
+
+export const MultipleAccordions: Story = {
+  args: {
+    isOpen: false,
+    disabled: false,
+    size: 'medium',
+  },
+  render: (args) => (
+    <div style={{ width: '100%', maxWidth: 660 }}>
+      <Accordion {...args}>
+        <Accordion.Heading>Heading</Accordion.Heading>
+        <Accordion.Panel>
+          <p>
+            This accordion reveals additional details. For enquiries, email
+            <a href='mailto:admissions@ucl.ac.uk'> admissions@ucl.ac.uk</a>.
+          </p>
+          <p>
+            You can also visit our FAQs for more information and guidance on
+            next steps.
+          </p>
+        </Accordion.Panel>
+      </Accordion>
+      <Accordion {...args}>
+        <Accordion.Heading>Heading</Accordion.Heading>
+        <Accordion.Panel>
+          <p>
+            This accordion reveals additional details. For enquiries, email
+            <a href='mailto:admissions@ucl.ac.uk'> admissions@ucl.ac.uk</a>.
+          </p>
+          <p>
+            You can also visit our FAQs for more information and guidance on
+            next steps.
+          </p>
+        </Accordion.Panel>
+      </Accordion>
+    </div>
+  ),
+};

package/lib/components/Accordion/Accordion.tsx

@@ -9,7 +9,7 @@ import AccordionPanel from './Accordion.Panel';
 import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
 
-export const NAME = 'ucl-accordion';
+export const NAME = 'ucl-uikit-accordion';
 
 interface AccordionContextProps {
   isOpen: boolean;
@@ -18,9 +18,9 @@ interface AccordionContextProps {
   size: 'small' | 'medium';
 }
 
-const AccordionContext = createContext<
-  AccordionContextProps | undefined
->(undefined);
+const AccordionContext = createContext<AccordionContextProps | undefined>(
+  undefined
+);
 
 export const useAccordionContext = () => {
   const context = useContext(AccordionContext);
@@ -32,8 +32,7 @@ export const useAccordionContext = () => {
   return context;
 };
 
-export interface AccordionProps
-  extends HTMLAttributes<HTMLDivElement> {
+export interface AccordionProps extends HTMLAttributes<HTMLDivElement> {
   testId?: string;
   size?: 'small' | 'medium';
   disabled?: boolean;
@@ -63,11 +62,15 @@ const Accordion: React.FC<AccordionProps> & {
   const accordionStyle = cx(
     NAME,
     css`
-      max-width: 600px;
+      width: 660px;
+      min-width: 288px;
+      max-width: 660px;
+      box-sizing: border-box;
       border: 1px solid ${theme.color.neutral.grey10};
       background-color: ${theme.color.neutral.white};
       font-family: ${theme.font.family.primary};
       font-size: ${theme.font.size.f16};
+      flex-shrink: 1;
     `,
     size === 'small' &&
       css`
@@ -83,7 +86,6 @@ const Accordion: React.FC<AccordionProps> & {
         pointer-events: none;
         background-color: ${theme.color.link.disabled};
         color: ${theme.color.text.muted};
-        // border-color: ${theme.color.text.muted};
       `,
     className
   );

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

@@ -3,13 +3,13 @@
 exports[`Accordion > snapshot: no props 1`] = `
 <div
   aria-disabled="false"
-  class="ucl-accordion css-1czwoas"
-  data-testid="ucl-accordion"
+  class="ucl-uikit-accordion css-rs0koa"
+  data-testid="ucl-uikit-accordion"
 >
   <div
     aria-expanded="false"
-    class="ucl-accordion__heading css-11x7r0n"
-    data-testid="ucl-accordion__heading"
+    class="ucl-uikit-accordion__heading css-1yg3n9"
+    data-testid="ucl-uikit-accordion__heading"
     role="button"
     tabindex="0"
   >
@@ -38,13 +38,13 @@ exports[`Accordion > snapshot: no props 1`] = `
 exports[`Accordion > snapshot: testId prop 1`] = `
 <div
   aria-disabled="false"
-  class="ucl-accordion css-1czwoas"
+  class="ucl-uikit-accordion css-rs0koa"
   data-testid="abc"
 >
   <div
     aria-expanded="false"
-    class="ucl-accordion__heading css-11x7r0n"
-    data-testid="ucl-accordion__heading"
+    class="ucl-uikit-accordion__heading css-1yg3n9"
+    data-testid="ucl-uikit-accordion__heading"
     role="button"
     tabindex="0"
   >

package/lib/components/Accordion/index.ts

@@ -1,2 +1,4 @@
 export { default } from './Accordion';
 export type { AccordionProps } from './Accordion';
+export type { AccordionHeadingProps } from './Accordion.Heading';
+export type { AccordionPanelProps } from './Accordion.Panel';

package/lib/components/Alert/Alert.stories.tsx

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

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/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/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

@@ -36,6 +36,7 @@ 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'>;