@westpac/ui 1.0.0 → 1.1.1

package/.agents/AGENTS.md

@@ -0,0 +1,161 @@
+# @westpac/ui Component Conventions
+
+These conventions apply to all code in `packages/ui/`. Follow them when creating, modifying, or reviewing components.
+
+## File Structure
+
+Every component lives in `src/components/{kebab-case-name}/` with these files:
+
+- `index.ts` — Public exports (component + props type only, NOT styles)
+- `{name}.component.tsx` — Component implementation
+- `{name}.styles.ts` — Tailwind Variants styles
+- `{name}.types.ts` — TypeScript types
+- `{name}.spec.tsx` — Vitest + React Testing Library tests
+- `{name}.stories.tsx` — Storybook stories
+
+Optional: `{name}.utils.ts` for helpers, `components/` subdirectory for compound sub-components.
+
+## Import Conventions
+
+- **Always use `.js` extensions** in relative imports (e.g., `'./button.styles.js'`)
+- Import `ResponsiveVariants` from `../../types/responsive-variants.types.js`
+- Import `useBreakpoint` from `../../hook/breakpoints.hook.js`
+- Import `resolveResponsiveVariant` from `../../utils/breakpoint.util.js`
+- Import `IconProps` from `../icon/index.js`
+
+## Types (`*.types.ts`)
+
+- Derive variant types: `type Variants = VariantProps<typeof styles>`
+- Wrap responsive props: `ResponsiveVariants<Variants['propName']>`
+- JSDoc comment with `@default` tag on every prop
+- Extend appropriate HTML attributes (`HTMLAttributes<HTMLDivElement>`, `ButtonHTMLAttributes<Element>`, etc.)
+- Use `Omit<>` for conflicting HTML attributes (e.g., `Omit<InputHTMLAttributes, 'size'>`)
+
+## Styles (`*.styles.ts`)
+
+- Use `tv()` from `tailwind-variants`, exported as `styles`
+- Use `slots` for multi-element components
+- Use `compoundSlots` for variant combinations
+- Use GEL design tokens — never hardcode colors:
+  - Text: `text-text-body`, `text-text-muted`, `text-text-link`, `text-text-mono`
+  - Surface: `bg-surface-primary`, `bg-surface-hero`, `bg-surface-muted-pale`
+  - Hover: `hover:bg-surface-hover-*`
+  - Active: `active:bg-surface-active-*`
+  - Border: `border-border-primary`, `border-border-hero`, `border-border-muted-soft`
+  - Background: `bg-background-white`
+- Typography: `typography-body-*`
+- Focus: `focus-outline` (not custom focus rings)
+
+## Components (`*.component.tsx`)
+
+- Add `'use client';` directive when using hooks or interactivity
+- Use `forwardRef` pattern when appropriate: `Base{Name}` function + `forwardRef(Base{Name})` export
+- Destructure `className` and pass to `styles({ className })` or `styles.base({ className })`
+- Resolve responsive props: `resolveResponsiveVariant(prop, breakpoint)` with `useBreakpoint()`
+- Use `useFocusRing()` + `mergeProps()` from `react-aria` for interactive components
+- Use plain function declarations — do NOT use `React.FC`
+- Set sensible default values in prop destructuring
+
+## Index (`index.ts`)
+
+```ts
+export { ComponentName } from './component-name.component.js';
+export { type ComponentNameProps } from './component-name.types.js';
+```
+
+Do NOT re-export styles.
+
+## Tests (`*.spec.tsx`)
+
+- Use `@testing-library/react` for rendering, `userEvent.setup()` for interactions
+- Use `vi.fn()` for mocks, `waitFor()` for async assertions
+- Import from `.component.js` (not index)
+- Minimum: a "renders the component" test
+- Pre-mocked globals (do NOT re-mock): `window.scrollTo`, `window.matchMedia`, `ResizeObserver`, `window.URL.createObjectURL`
+- Style files (`*.styles.ts`) are excluded from test coverage
+
+## Stories (`*.stories.tsx`)
+
+- Import from `@storybook/react-vite`
+- Include `tags: ['autodocs']` and decorator `[(Story: StoryFn) => <Story />]`
+- JSDoc comments above stories use `>` blockquote format
+- Interactive stories using `useState` are defined as function components
+- Use `fn()` from `storybook/test` for callback props
+
+## Registering New Components
+
+After creating a component, add it to `src/components/index.ts`:
+
+```ts
+export * from './{kebab-case-name}/index.js';
+```
+
+## Key Patterns
+
+- **Responsive variants**: Use `ResponsiveVariants<T>` type, resolve with `resolveResponsiveVariant()` + `useBreakpoint()`
+- **Compound components**: Use React Context, place sub-components in `components/` subdirectory
+- **Icon props**: Type as `(props: IconProps) => JSX.Element`
+- **Polymorphic tag**: `tag?: keyof JSX.IntrinsicElements` or a constrained subset
+
+## TypeScript Best Practices
+
+- **No `any`** — Use proper types. If a type is truly unknown, use `unknown` and narrow it. The only acceptable escape hatch is `as unknown as TargetType` for complex generic interop (e.g., `forwardRef` with generics)
+- **Prefer `type` over `interface`** for props — keeps consistency with `VariantProps` intersections (`&`)
+- **Export types with `export { type ... }`** — use explicit `type` keyword for type-only exports
+- **Derive types from source** — don't duplicate: use `VariantProps<typeof styles>`, `Pick<>`, `Omit<>`, and mapped types
+- **Use `ReactNode` for children** — not `JSX.Element` or `React.ReactElement` (unless narrowing is required for compound components)
+- **Type event handlers precisely** — use `React.MouseEvent<HTMLButtonElement>`, not generic `React.SyntheticEvent`
+- **Avoid type assertions** — prefer type guards and narrowing over `as`. Use `satisfies` for validation without widening
+
+## React Best Practices
+
+### Component Design
+
+- **One component per file** — the main component in `*.component.tsx`, sub-components in their own files under `components/`
+- **Plain functions, not `React.FC`** — function declarations with explicit props typing: `function Button({ children }: ButtonProps)`
+- **Destructure props at the function signature** — not inside the body. Order: `className`, variant props, behavioural props, `children`, `...rest`
+- **Prefer composition over configuration** — use children and compound component patterns rather than deeply nested config objects (see Compacta, Repeater, ButtonGroup)
+- **Keep components pure** — no side effects in render. Move side effects to `useEffect`
+
+### Hooks
+
+- **`useMemo`** — for expensive computations or referentially stable objects/arrays passed to children. Don't over-use for primitive values
+- **`useCallback`** — for event handlers passed to memoized children or used in dependency arrays
+- **Custom hooks** — extract reusable logic into hooks in `src/hook/`. Prefix with `use`
+- **Dependency arrays** — list all dependencies. Suppress lint warnings only with a comment explaining why
+- **`useEffect` cleanup** — always clean up subscriptions, event listeners, and timers
+
+### Refs and DOM
+
+- **`forwardRef`** — use for components that render a single native element consumers might need to reference
+- **Type refs precisely** — `Ref<HTMLButtonElement>`, not `Ref<HTMLElement>` or `Ref<any>`
+- **Don't read refs during render** — access `.current` only in effects or event handlers
+
+### State Management
+
+- **Lift state only when needed** — keep state as close to where it's used as possible
+- **React Context for compound components** — share state between parent and children (Accordion, List, Compacta)
+- **`react-stately` for complex state** — use Adobe's hooks (`useDisclosureGroupState`, `useOverlayTriggerState`, etc.) instead of hand-rolling state machines
+- **Controlled vs uncontrolled** — support both patterns where sensible. Use `defaultValue`/`value` naming convention
+
+### Performance
+
+- **Don't prematurely optimise** — only add `memo()`, `useMemo`, `useCallback` when there's a measurable problem or the component is used in lists
+- **Avoid inline object/array literals in JSX** — these create new references every render. Extract to `useMemo` or module scope if they're static
+- **Key lists properly** — use stable, unique identifiers, never array index (unless the list is static and never reordered)
+
+### Patterns to Avoid
+
+- **No `React.FC`** — doesn't support generics well and adds implicit `children`
+- **No `default export` for components** — use named exports for better refactoring support and tree-shaking
+- **No `// @ts-ignore` or `// @ts-expect-error`** — fix the type issue instead. If absolutely unavoidable, add a comment explaining why
+- **No `useEffect` for derived state** — compute derived values directly or with `useMemo`, not by syncing state in effects
+- **No prop drilling beyond 2 levels** — use Context or composition instead
+
+## Available Skills
+
+Load these skills for specific tasks:
+
+- **`creating-gel-component`** — Step-by-step scaffolding workflow with file templates for new components
+- **`reviewing-gel-component`** — Checklist for auditing components against these conventions
+- **`writing-gel-tests`** — Detailed guide for Vitest + React Testing Library test patterns, categories, and coverage targets

package/.agents/skills/creating-gel-component/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: creating-gel-component
+description: 'Scaffolds a new GEL design system UI component following project conventions. Use when creating a new component, adding a component, or scaffolding a component in packages/ui.'
+---
+
+# Creating a GEL Component
+
+Scaffolds a new React component in `packages/ui/src/components/`. All conventions (file naming, imports, patterns) are defined in the `packages/ui/.agents/AGENTS.md` — follow those automatically.
+
+## Step-by-Step Workflow
+
+### 1. Create the types file (`{name}.types.ts`)
+
+```tsx
+import { HTMLAttributes } from 'react';
+import { type VariantProps } from 'tailwind-variants';
+
+import { ResponsiveVariants } from '../../types/responsive-variants.types.js';
+
+import { styles } from './{kebab-case-name}.styles.js';
+
+type Variants = VariantProps<typeof styles>;
+
+export type {PascalName}Props = {
+  /**
+   * Description of variant prop
+   * @default defaultValue
+   */
+  variantProp?: ResponsiveVariants<Variants['variantProp']>;
+} & HTMLAttributes<HTMLElement>;
+```
+
+### 2. Create the styles file (`{name}.styles.ts`)
+
+```ts
+import { tv } from 'tailwind-variants';
+
+export const styles = tv({
+  base: '',
+  variants: {},
+});
+```
+
+### 3. Create the component file (`{name}.component.tsx`)
+
+```tsx
+'use client';
+
+import React, { forwardRef, Ref } from 'react';
+import { mergeProps, useFocusRing } from 'react-aria';
+
+import { useBreakpoint } from '../../hook/breakpoints.hook.js';
+import { resolveResponsiveVariant } from '../../utils/breakpoint.util.js';
+
+import { styles as componentStyles } from './{kebab-case-name}.styles.js';
+import { type {PascalName}Props } from './{kebab-case-name}.types.js';
+
+function Base{PascalName}(
+  { className, variant = 'default', ...props }: {PascalName}Props,
+  ref: Ref<HTMLDivElement>,
+) {
+  const breakpoint = useBreakpoint();
+  const { isFocusVisible, focusProps } = useFocusRing();
+
+  return (
+    <div
+      ref={ref}
+      className={componentStyles({
+        className,
+        variant: resolveResponsiveVariant(variant, breakpoint),
+        isFocusVisible,
+      })}
+      {...mergeProps(props, focusProps)}
+    />
+  );
+}
+
+export const {PascalName} = forwardRef(Base{PascalName});
+```
+
+### 4. Create the index file (`index.ts`)
+
+```ts
+export { {PascalName} } from './{kebab-case-name}.component.js';
+export { type {PascalName}Props } from './{kebab-case-name}.types.js';
+```
+
+### 5. Create the test file (`{name}.spec.tsx`)
+
+```tsx
+import { render } from '@testing-library/react';
+
+import { {PascalName} } from './{kebab-case-name}.component.js';
+
+describe('{PascalName}', () => {
+  it('renders the component', () => {
+    const { container } = render(<{PascalName} />);
+    expect(container).toBeInTheDocument();
+  });
+});
+```
+
+See the `writing-gel-tests` skill for comprehensive testing guidance.
+
+### 6. Create the stories file (`{name}.stories.tsx`)
+
+```tsx
+import { type Meta, StoryFn, type StoryObj } from '@storybook/react-vite';
+
+import { {PascalName} } from './{kebab-case-name}.component.js';
+
+const meta: Meta<typeof {PascalName}> = {
+  title: 'Components/{PascalName}',
+  component: {PascalName},
+  tags: ['autodocs'],
+  decorators: [(Story: StoryFn) => <Story />],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * > Default usage example
+ */
+export const Default: Story = {
+  args: {},
+};
+```
+
+Interactive stories using `useState` can be defined as function components:
+
+```tsx
+export const Example = () => {
+  const [state, setState] = useState(initialValue);
+
+  return <Component prop={state} onChange={setState} />;
+};
+```
+
+### 7. Register the component
+
+Add the export to `packages/ui/src/components/index.ts`:
+
+```ts
+export * from './{kebab-case-name}/index.js';
+```
+
+### 8. Verify
+
+Run these commands from `packages/ui/`:
+
+- `pnpm vitest run src/components/{kebab-case-name}` — Run tests
+- `pnpm build` — Verify build

package/.agents/skills/reviewing-gel-component/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: reviewing-gel-component
+description: 'Reviews GEL design system components for convention compliance, accessibility, and best practices. Use when reviewing a component, checking component quality, or auditing GEL components.'
+---
+
+# Reviewing a GEL Component
+
+Reviews components in `packages/ui/src/components/` against the conventions defined in `packages/ui/.agents/AGENTS.md`.
+
+## Review Checklist
+
+### 1. File Structure
+
+- [ ] All required files exist: `index.ts`, `*.component.tsx`, `*.styles.ts`, `*.types.ts`, `*.spec.tsx`, `*.stories.tsx`
+- [ ] File names use kebab-case matching the directory name
+- [ ] Component is exported from `packages/ui/src/components/index.ts`
+
+### 2. Types
+
+- [ ] `Variants` type alias derived from `VariantProps<typeof styles>`
+- [ ] Responsive props wrapped with `ResponsiveVariants<Variants['...']>`
+- [ ] Every prop has a JSDoc comment with `@default` tag where applicable
+- [ ] Extends correct HTML attributes type
+- [ ] Uses `Omit<>` for conflicting HTML attributes
+- [ ] `.js` extensions on relative imports
+
+### 3. Styles
+
+- [ ] Uses tailwind styling except when animations/dynamic styles are required
+- [ ] Uses `tv()` from `tailwind-variants`, exported as `styles`
+- [ ] Uses GEL design tokens — no hardcoded colors
+- [ ] Uses `typography-body-*` for text, `focus-outline` for focus
+- [ ] Uses `slots` for multi-element components
+- [ ] Uses `compoundSlots` for variant combinations
+
+### 4. Component
+
+- [ ] Has `'use client';` if using hooks or client-side rendering
+- [ ] Uses `forwardRef` pattern when appropriate
+- [ ] Destructures `className` and passes to styles
+- [ ] Uses `useBreakpoint()` + `resolveResponsiveVariant()` for responsive props
+- [ ] Uses `useFocusRing()` + `mergeProps()` from `react-aria` where appropriate
+- [ ] All props are used (no unused props)
+- [ ] `.js` extensions on all relative imports
+- [ ] Plain function declarations (not `React.FC`)
+
+### 5. Accessibility
+
+- [ ] Interactive elements use appropriate ARIA attributes
+- [ ] Decorative icons use `aria-hidden`
+- [ ] `react-aria` hooks used for focus and accessibility where appropriate
+- [ ] Semantic HTML elements used
+- [ ] `react-stately` hooks for state management where applicable
+
+### 6. Index
+
+- [ ] Exports component and props type only
+- [ ] Does NOT re-export styles
+- [ ] `.js` extensions
+
+### 7. Tests
+
+- [ ] At minimum a "renders the component" test
+- [ ] Uses `userEvent.setup()` (not `fireEvent`) for interactions
+- [ ] Imports from `.component.js` (not index)
+
+### 8. Stories
+
+- [ ] Imports from `@storybook/react-vite`
+- [ ] Has `tags: ['autodocs']` and standard decorator
+- [ ] Covers: default state, looks/variants, sizes, responsive, disabled
+- [ ] Interactive stories defined as function components
+
+## Severity Levels
+
+### Critical
+
+- Missing `'use client'` on components with hooks
+- Hardcoded colors instead of design tokens
+- Missing `forwardRef` on components rendering native elements
+- Custom focus styles instead of `focus-outline`
+- Missing `.js` extensions in imports
+
+### Warnings
+
+- Missing JSDoc `@default` tags
+- No responsive variant support where beneficial
+- Minimal test coverage
+- Missing `aria-*` attributes on interactive elements
+
+### Style
+
+- Using `React.FC` instead of function declarations
+- Inconsistent prop destructuring order
+- Styles not using `slots` for multi-element components
+
+## How to Run
+
+1. Read all files in the component directory
+2. Check each item above
+3. Report findings grouped by severity
+4. Suggest specific fixes with code examples

package/.agents/skills/writing-gel-tests/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: writing-gel-tests
+description: 'Writes Vitest + React Testing Library tests for GEL design system components. Use when writing tests, adding tests, or improving test coverage for components in packages/ui.'
+---
+
+# Writing GEL Component Tests
+
+Guides writing tests for components in `packages/ui/src/components/`. Test conventions are also summarised in `packages/ui/.agents/AGENTS.md`.
+
+## Test Environment
+
+- **Runner**: Vitest with `jsdom` environment
+- **Rendering**: `@testing-library/react` (`render`, `screen`, `waitFor`)
+- **User Events**: `@testing-library/user-event` (`userEvent.setup()`)
+- **Mocks**: `vi` from `vitest`
+- **Matchers**: `@testing-library/jest-dom` (loaded via `vitest.setup.ts`)
+- **Excluded from tests**: `*.styles.ts` files (excluded in vitest config)
+
+### Pre-mocked Globals
+
+Already mocked in `vitest.setup.ts` — do NOT re-mock:
+
+- `window.scrollTo`
+- `window.URL.createObjectURL` / `revokeObjectURL`
+- `window.matchMedia`
+- `ResizeObserver`
+
+## Test File Structure
+
+```tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { vi } from 'vitest';
+
+import { ComponentName } from './component-name.component.js';
+
+describe('ComponentName', () => {
+  const user = userEvent.setup();
+
+  it('renders the component', () => {
+    const { container } = render(<ComponentName />);
+    expect(container).toBeInTheDocument();
+  });
+});
+```
+
+Import from `./component-name.component.js` (NOT from `index`), sub-components from `./components/index.js`, icons from `../icon/index.js`. Always use `.js` extensions.
+
+## Test Categories
+
+### 1. Render Tests (Required)
+
+```tsx
+it('renders the component', () => {
+  const { container } = render(<ComponentName />);
+  expect(container).toBeInTheDocument();
+});
+```
+
+### 2. Variant Rendering
+
+```tsx
+it('renders as an anchor tag', () => {
+  render(
+    <Button tag="a" href="#">
+      Link
+    </Button>,
+  );
+  expect(screen.getByRole('link', { name: 'Link' })).toBeInTheDocument();
+});
+```
+
+### 3. User Interactions
+
+Always use `userEvent.setup()` (NOT `fireEvent`):
+
+```tsx
+it('calls onClick when clicked', async () => {
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click me</Button>);
+
+  act(() => {
+    user.click(screen.getByRole('button', { name: 'Click me' }));
+  });
+
+  await waitFor(() => {
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### 4. Visibility / State
+
+```tsx
+it('shows content when expanded', async () => {
+  const { getByText } = render(
+    <Accordion>
+      <AccordionItem key="item1" id="item1" title="Title">
+        Hidden content
+      </AccordionItem>
+    </Accordion>,
+  );
+
+  user.click(getByText('Title'));
+
+  await waitFor(() => {
+    expect(getByText('Hidden content')).toBeVisible();
+  });
+});
+```
+
+### 5. Icon Rendering
+
+```tsx
+it('renders an icon when passed', () => {
+  render(<Button iconBefore={ArrowRightIcon} />);
+  expect(screen.getByRole('img', { hidden: true })).toBeInTheDocument();
+});
+```
+
+### 6. Utility Functions
+
+```tsx
+describe('ComponentName utils', () => {
+  it('maps correct values', () => {
+    expect(utilFunction('input')).toBe('expected');
+  });
+
+  it('handles responsive values', () => {
+    expect(utilFunction({ initial: 'small', md: 'large' })).toStrictEqual({ initial: 'xsmall', md: 'small' });
+  });
+});
+```
+
+## Querying Elements
+
+Prefer accessible queries:
+
+1. `screen.getByRole('button', { name: 'Text' })` — interactive elements
+2. `screen.getByText('Text')` — content assertions
+3. `screen.getByLabelText('Label')` — form elements
+4. `container.querySelector()` — last resort only
+
+## Coverage Targets
+
+```js
+branches: 80,
+functions: 80,
+lines: 80,
+statements: 80,
+```
+
+## Running Tests
+
+```bash
+pnpm vitest run src/components/{name}    # Specific component
+pnpm vitest run                          # All tests
+pnpm vitest src/components/{name}        # Watch mode
+pnpm vitest run --coverage               # With coverage
+```
+
+## What NOT to Test
+
+- Style files (`*.styles.ts`) — excluded in vitest config
+- Tailwind class names — don't assert on specific CSS classes
+- Internal implementation details — test behavior, not implementation
+- Storybook stories — tested separately via Storybook

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @westpac/ui
 
+## 1.1.1
+
+### Patch Changes
+
+- 2eebb35: - fix issue with font import in style config
+  - fix security issues
+
+## 1.1.0
+
+### Minor Changes
+
+- bd3422f: add onPasteComplete handler to passcode
+
 ## 1.0.0
 
 ### 📦 Major Changes — @westpac/ui & @westpac/style-config