next branch release

.claude/rules/common-utilities.md

@@ -0,0 +1,48 @@
+# Common Utilities — Use These, Don't Reinvent Them
+
+All utilities are in `libs/web-components/src/common/`. Always check here before writing your own.
+
+## utils.ts
+
+| Function | Purpose |
+|----------|---------|
+| `typeValidator(msg, values, opts)` | Creates runtime validator + TypeScript type from same array |
+| `toBoolean(value)` | String to boolean (`"false"` -> false, `""` -> true) |
+| `fromBoolean(value)` | Boolean to string (`true` -> `"true"`) |
+| `dispatch(el, name, detail, opts)` | External consumer events (underscore-prefixed names) |
+| `relay(el, name, data, opts)` | Internal parent-child messaging (form components) |
+| `receive(el, handler)` | Listen for internal relay messages |
+| `getSlottedChildren(rootEl)` | Get elements assigned to a slot |
+| `announceToScreenReader(text)` | Temporary aria-live announcement |
+| `performOnce(timeoutId, action, delay)` | Debounce |
+| `validateRequired(name, props)` | Check required props have values |
+| `findFirstFocusableNode(nodes)` | Find first focusable element (supports shadow DOM) |
+| `generateRandomId()` | 7-char random alphanumeric |
+| `clamp(value, min, max)` | Numeric clamping |
+| `watch(fn, deps)` | Explicit dependency tracking for `$:` blocks |
+| `styles(...css)` | Conditional style string builder |
+
+## styling.ts
+
+| Function | Purpose |
+|----------|---------|
+| `calculateMargin(mt, mr, mb, ml)` | Converts Spacing values to inline margin styles |
+| `Spacing` type | `"none" \| "3xs" \| "2xs" \| "xs" \| "s" \| "m" \| "l" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| null` |
+
+## Other files
+
+| File | Purpose |
+|------|---------|
+| `context-store.ts` | Cross-shadow-DOM context API (replaces Svelte's native context) |
+| `calendar-date.ts` | Timezone-safe date class for DatePicker/Calendar |
+| `no-scroll.ts` | Body scroll lock action for Modal/Drawer |
+| `breakpoints.ts` | `MOBILE_BP` (624px), `TABLET_BP` (1024px) |
+| `validators.ts` | `isValidDimension()` for CSS dimension strings |
+| `urls.ts` | URL matching for navigation active state |
+
+## relay() vs dispatch() — The Boundary Rule
+
+- `relay()` / `receive()`: Internal, between DS components only. Uses single `"msg"` event with action discriminator. For form parent-child coordination.
+- `dispatch()`: External, for consumer applications. Named events with underscore prefix (`_click`, `_change`).
+
+If the message is between two DS components, use relay. If it's for the consuming app, use dispatch.

.claude/rules/component-authoring.md

@@ -0,0 +1,74 @@
+# Component Authoring Standards
+
+## Script Section Order
+
+Every Svelte component script follows this order:
+
+1. Imports
+2. Validators (`typeValidator` declarations)
+3. Type declarations
+4. Exported props (ordered: required > content > state > visual > a11y > version > margins)
+5. Private state (underscore prefix: `_rootEl`, `_isOpen`)
+6. Reactive declarations (`$:`)
+7. Lifecycle (`onMount`, `onDestroy`)
+8. Event handlers / functions
+
+## Universal Props
+
+Every component must include:
+
+- `testid: string = ""` with `data-testid={testid}` on root element
+- `mt, mr, mb, ml: Spacing = null` with `style={calculateMargin(mt, mr, mb, ml)}`
+- `version: "1" | "2" = "1"` with `class:v2={version === "2"}`
+
+## Boolean Props
+
+Web component attributes are always strings. Boolean props: `export let disabled: string = "false"` with `$: isDisabled = toBoolean(disabled)`.
+
+Note: `toBoolean("")` returns `true` (HTML attribute semantics).
+
+## Enum Props
+
+Always use `typeValidator` for enum/union props. Use the object form `{ required: true }` over the boolean shorthand.
+
+```typescript
+const [Types, validateType] = typeValidator("Button type", ["primary", "secondary"], { required: true });
+type ButtonType = (typeof Types)[number];
+export let type: ButtonType = "primary";
+onMount(() => { validateType(type); });
+```
+
+## Events
+
+- External (for consumers): `dispatch(_rootEl, "_change", { name, value }, { bubbles: true })`
+- Internal (between DS components): `relay()` / `receive()` -- never use `dispatch()` for parent-child coordination
+- Event details must be objects (for future extensibility), not bare values
+- Use separate events for separate operations
+
+## Lifecycle
+
+- Validate all typeValidators in `onMount`
+- rootEl event listeners auto-clean on removal. Do NOT add removeEventListener for rootEl in onDestroy.
+- document/window listeners DO need cleanup in onDestroy.
+
+## Slots
+
+Slot names are lowercase. Check existence before rendering with `$$slots`. Use **props** for simple text, **slots** for rich content, both when either should work:
+
+```svelte
+{#if $$slots.heading}
+  <slot name="heading" />
+{:else if heading}
+  <span>{heading}</span>
+{/if}
+```
+
+Use `getSlottedChildren()` from `common/utils.ts` to access child elements in slots.
+
+## Naming
+
+- Prop names: always lowercase (`leadingicon` not `leadingIcon`)
+- Private state: underscore prefix (`_isOpen`)
+- Functions: must have verbs (`handleClick`, `getMenuLinks`)
+- Size values: use `"default"` not `"regular"`
+- Locale: `en-CA` always

.claude/rules/framework-wrappers.md

@@ -0,0 +1,98 @@
+# Framework Wrapper Standards
+
+## Cross-Framework Rule
+
+Every Svelte change requires corresponding React and Angular updates. Props must match across all three frameworks (required/optional, naming, types, data formats). This is the #1 source of review rounds.
+
+## React Wrapper Template
+
+Two interfaces: WCProps (private, lowercase, strings) and GoabXxxProps (exported, camelCase, real types).
+
+```typescript
+interface WCProps extends Margins {
+  name: string;
+  disabled?: string;
+  testid?: string;
+}
+
+export interface GoabXxxProps extends Margins, DataAttributes {
+  name: string;
+  disabled?: boolean;
+  onChange?: (detail: GoabXxxOnChangeDetail) => void;
+  testId?: string;
+  children?: ReactNode;
+}
+
+export function GoabXxx({ disabled, onChange, children, ...rest }: GoabXxxProps): JSX.Element {
+  const el = useRef<HTMLElement>(null);
+  const _props = transformProps<WCProps>(rest, lowercase);
+
+  useEffect(() => {
+    if (!el.current) return;
+    const current = el.current;
+    const listener = (e: Event) => {
+      const detail = (e as CustomEvent<GoabXxxOnChangeDetail>).detail;
+      onChange?.({ ...detail, event: e });
+    };
+    current.addEventListener("_change", listener);
+    return () => current.removeEventListener("_change", listener);
+  }, [el, onChange]);
+
+  return (
+    <goa-xxx ref={el} {..._props} disabled={disabled ? "true" : undefined}>
+      {children}
+    </goa-xxx>
+  );
+}
+```
+
+Key: Boolean props pass `"true"` or `undefined`, never `"true"` or `"false"`. Event callbacks always spread detail and add `event: e`. Types from `@abgov/ui-components-common`.
+
+## Angular Wrapper Template
+
+Non-form components extend `GoabBaseComponent`. Form controls extend `GoabControlValueAccessor`.
+
+```typescript
+@Component({
+  standalone: true,
+  selector: "goab-xxx",
+  template: `
+    @if (isReady) {
+      <goa-xxx
+        [attr.type]="type"
+        [attr.disabled]="disabled ? 'true' : undefined"
+        [attr.testid]="testId"
+        [attr.mt]="mt" [attr.mb]="mb" [attr.ml]="ml" [attr.mr]="mr"
+        (_click)="_onClick($event)"
+      >
+        <ng-content />
+      </goa-xxx>
+    }
+  `,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class GoabXxx extends GoabBaseComponent implements OnInit {
+  @Input() type?: GoabXxxType;
+  @Input({ transform: booleanAttribute }) disabled?: boolean;
+  @Output() onClick = new EventEmitter<GoabXxxOnClickDetail>();
+
+  isReady = false;
+  constructor(private cdr: ChangeDetectorRef) { super(); }
+
+  ngOnInit(): void {
+    setTimeout(() => {
+      this.isReady = true;
+      this.cdr.detectChanges();
+    }, 0);
+  }
+
+  _onClick(e: Event) {
+    this.onClick.emit({
+      ...(e as CustomEvent<GoabXxxOnClickDetail>).detail,
+      event: e,
+    });
+  }
+}
+```
+
+Key: `isReady` + `setTimeout(0)` is non-negotiable (every component). Use `[attr.xxx]` for web component attributes. Use `booleanAttribute` transform for boolean inputs. Form controls add `#goaComponentRef`, `NG_VALUE_ACCESSOR`, `markAsTouched()`.

.claude/rules/styling.md

@@ -0,0 +1,44 @@
+# Styling Standards
+
+## Design Tokens
+
+All styling uses CSS custom properties. No exceptions. No hardcoded colors, font sizes, border-radius, or spacing.
+
+Token naming: `--goa-[component]-[variant]-[state]-[property]`
+
+Use `rem` over `px` even when there is no token value (`20px` = `1.25rem`).
+
+## :host
+
+Every component starts with:
+
+```css
+:host {
+  box-sizing: border-box;
+  font-family: var(--goa-font-family-sans);
+}
+```
+
+## V2 Token Fallbacks (Mandatory)
+
+Every V2 CSS variable must fall back to V1. This is the most repeated review feedback on V2 PRs.
+
+```css
+color: var(--goa-component-v2-token, var(--goa-v1-fallback));
+```
+
+## Class Binding
+
+Variant classes use string interpolation. State classes use `class:` directive.
+
+```svelte
+<div class="goa-badge badge-{type}" class:v2={version === "2"} class:disabled={isDisabled}>
+```
+
+## Responsive
+
+Use PostCSS aliases: `@media (--mobile) { ... }`. Breakpoints: mobile = 624px, tablet = 1024px.
+
+## CSS Simplification
+
+Prefer `gap` over margins between items. Remove redundant CSS properties. No consumer CSS customization by design (no `::part()`, no exposed custom properties).

.claude/rules/testing.md

@@ -0,0 +1,58 @@
+# Testing Standards
+
+## Testing Tiers
+
+| Tier | Framework | When to Use |
+|------|-----------|-------------|
+| WC Unit | Vitest + @testing-library/svelte | Prop rendering, basic state, margins |
+| React Unit | Vitest + @testing-library/react | Wrapper prop transformation |
+| React Browser | Vitest + Playwright (Chromium + Firefox) | Event behavior, interactions, shadow DOM |
+| Angular | Jest + TestBed | Wrapper attribute binding, form integration |
+
+**Browser tests for events, unit tests for props.**
+
+## Enforced Patterns
+
+**Locators are always truthy. Don't assert on them.**
+`getBy*` always returns an object. `expect(el).toBeTruthy()` is meaningless. Assert on actual state instead.
+
+**Declare locators outside `waitFor`.**
+Putting locators inside `waitFor` defeats its purpose.
+
+```typescript
+// Bad
+await vi.waitFor(() => {
+  const el = result.getByTestId("button");
+  expect(el).toHaveTextContent("Submit");
+});
+
+// Good
+const el = result.getByTestId("button");
+await vi.waitFor(() => {
+  expect(el).toHaveTextContent("Submit");
+});
+```
+
+**No timeout hacks.** Browser tests already retry. Default `waitFor` timeout is 1000ms.
+
+**Use `click()`, not `dispatchEvent`** in browser tests.
+
+**Use `data-testid` for selectors**, but prefer `getByText` when it makes the test more accessible.
+
+**Tests must test what they claim.** If named "should show error state", assert on error state, not just element existence.
+
+**Use `it()` not `test()`.**
+
+## What to Test
+
+Every component: basic rendering, all prop variants, event dispatch, margins, disabled state, `data-*` passthrough, ARIA where applicable.
+
+V2 components need their own browser tests.
+
+## Angular Testing
+
+Use a test host component (test as a consumer would). `fakeAsync` + `tick()` for the `setTimeout(0)` pattern. Double `detectChanges()` (before and after `tick()`). Query via `By.css("goa-xxx")`.
+
+## PR Playground Files
+
+`feat{N}` not `feat-{N}` (no hyphen). Bug pages in `apps/prs/react/src/routes/bugs/`, features in `features/`.

.github/workflows/pull-request.yml

@@ -1,4 +1,7 @@
 name: Pull Request Check
+permissions:
+  contents: read
+  pull-requests: write
 
 on:
   pull_request:
@@ -12,17 +15,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
+
       - name: Install npm 11
         run: npm install -g npm@11
+
       - run: npm ci
 
-      # Run with the target branch as the base.
       - name: Lint
         run: npm run lint