@cobwds/mcp-server 1.19.3 → 1.23.1

package/data/frameworks.json

@@ -0,0 +1,14 @@
+{
+  "react": {
+    "packageName": "@cobwds/react",
+    "version": "1.23.1"
+  },
+  "vue": {
+    "packageName": "@cobwds/vue",
+    "version": "1.23.1"
+  },
+  "angular": {
+    "packageName": "@cobwds/angular",
+    "version": "1.23.1"
+  }
+}

package/data/guides/form-validation.md

@@ -165,5 +165,5 @@ The following COBWDS components support `showError` and `errorMessage`:
 
 1. **Error summary links**: Include anchor links to fields for keyboard navigation
 2. **Focus management**: Move focus to error summary or first error field on validation failure
-3. **ARIA attributes**: COBWDS components automatically set `aria-invalid` and `aria-describedby`
+3. **ARIA attributes**: COBWDS form components automatically set `aria-invalid` on the control and associate the error message via `aria-errormessage`, and associate the visible `<cob-label>` with the control via `aria-labelledby` — no manual wiring needed
 4. **Clear error messages**: Use specific, actionable error text

package/data/guides/frameworks/angular.md

@@ -1,16 +1,32 @@
-# COBWDS with Angular
+<!--
+  GENERATED FILE. Do not edit directly.
+  Source: packages/angular/README.md
+  Regenerate with: npm run sync:guides -w @cobwds/mcp-server
+-->
+# @cobwds/angular
 
-> **Note:** Angular integration is currently untested. The guidance below is based on standard web component usage patterns and may require adjustments.
+Angular components for the City of Boston Web Design System (COBWDS). Generated from the COBWDS web components library, with full support for template-driven forms, Reactive Forms, and Signal Forms.
 
-## Installation
+## Install
+
+### Setup a new Angular project
+
+```bash
+npm install -g @angular/cli
+ng new my-angular-app
+```
+
+### Install NYS Design System 
 
 ```bash
-npm install @cobwds/components @cobwds/styles
+npm install @cobwds/angular @cobwds/styles
 ```
 
+Peer dependencies: Angular `>=20.0.0` (core, common, forms).
+
 ## Load styles
 
-Add the COBWDS stylesheet to `angular.json`:
+Add COBWDS styles to your `angular.json`:
 
 ```json
 {
@@ -20,8 +36,7 @@ Add the COBWDS stylesheet to `angular.json`:
         "build": {
           "options": {
             "styles": [
-              "node_modules/@cobwds/styles/dist/cobwds-full.min.css",
-              "src/styles.css"
+              "node_modules/@cobwds/styles/cobwds-full.min.css"
             ]
           }
         }
@@ -31,41 +46,184 @@ Add the COBWDS stylesheet to `angular.json`:
 }
 ```
 
-Use `cobwds-full.min.css` for new projects (includes reset, typography, and utilities) or `cobwds.min.css` for existing projects (CSS variables only).
+## First component
+
+Import standalone components directly into your component:
 
-## Configuration
+```typescript
+import { Component, signal } from '@angular/core';
+import { RouterOutlet } from '@angular/router';
+import { CobButtonComponent } from '@cobwds/angular';
+@Component({
+  imports: [RouterOutlet, CobButtonComponent],
+  selector: 'app-root',
+  styleUrl: './app.css',
+  templateUrl: './app.html',
+})
+export class App {
+  protected readonly title = signal('my-angular-app');
+  handleSubmit() {
+    console.log('Button clicked!');
+  }
+}
+```
+
+## NgModule support has been deprecated
+
+Use "Standalone Components" instead.
+
+## Inputs, outputs, and two-way binding
+
+All properties are typed inputs; events are typed outputs. No `CUSTOM_ELEMENTS_SCHEMA` needed:
+
+```html
+<cob-textinput
+  [label]="'Email'"
+  [required]="true"
+  (nysChange)="onEmailChange($event)"
+></cob-textinput>
+```
 
-Add `CUSTOM_ELEMENTS_SCHEMA` to your module so Angular allows custom element tags:
+Event detail is typed:
 
 ```typescript
-import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+onEmailChange(event: CobTextinputChangeEvent) {
+  console.log(event.detail.value); // autocompletes
+}
+```
 
-@NgModule({
-  schemas: [CUSTOM_ELEMENTS_SCHEMA]
-})
-export class AppModule {}
+## Signal Forms Known Limitations
+
+When using Angular's Signal Forms with `[formField]`, be aware of these constraints:
+
+- **name property overwrite**: The `[formField]` binding overwrites the `name` attribute. This is an Angular Signal Forms limitation; there is no workaround on the component side. Use a different approach for form arrays that require distinct names.
+- **pattern validation on empty array**: Angular's Signal Forms passes an empty array for unset pattern metadata. The component defensively ignores these writes; no action needed on your side.
+
+## Forms
+
+### Template-driven forms
+
+Use `[(ngModel)]` with form components:
+
+```html
+<form>
+  <cob-textinput [(ngModel)]="email" name="email"></cob-textinput>
+  <cob-checkbox [(ngModel)]="agreed" name="agreed"></cob-checkbox>
+</form>
 ```
 
-For standalone components:
+### Reactive Forms
+
+Use `formControl` or `formControlName`:
 
 ```typescript
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+form = this.fb.group({
+  email: ["", [Validators.required, Validators.email]],
+  agreed: [false, Validators.required],
+});
+```
 
-@Component({
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: `<cob-button label="Click me"></cob-button>`
-})
-export class MyComponent {}
+```html
+<form [formGroup]="form">
+  <cob-textinput formControlName="email"></cob-textinput>
+  <cob-checkbox formControlName="agreed"></cob-checkbox>
+</form>
+```
+
+### Signal Forms (Angular 21+)
+
+Use `[formField]` with a form field definition:
+
+```typescript
+email = signal<string>("");
+emailControl = new FormControl<string>("", Validators.required);
+```
+
+```html
+<cob-textinput [formField]="emailControl"></cob-textinput>
+```
+
+### Group controls
+
+`cob-checkboxgroup` and `cob-radiogroup` bind at group level:
+
+```typescript
+form = this.fb.group({
+  languages: [["en"], Validators.required],
+});
+```
+
+```html
+<cob-checkboxgroup formControlName="languages">
+  <cob-checkbox value="en">English</cob-checkbox>
+  <cob-checkbox value="es">Spanish</cob-checkbox>
+</cob-checkboxgroup>
+```
+
+### Validation
+
+By default, the component owns validation. Its `required` and `pattern` attributes drive ElementInternals validation, shown on blur.
+
+To let Angular own validation instead, add the `nysControlErrors` directive:
+
+```html
+<cob-textinput
+  formControlName="email"
+  nysControlErrors
+></cob-textinput>
 ```
 
-## Usage
+The directive subscribes to `control.errors` and sets the component's `showError` and `errorMessage`. Override the default messages:
 
-Import components in the component or module where they're used:
+```typescript
+providers: [
+  {
+    provide: NYS_ERROR_MESSAGES,
+    useValue: {
+      required: () => "Please fill in this field",
+      email: () => "Enter a valid email",
+    },
+  },
+]
+```
+
+### Disabled state
+
+`FormControl({ disabled: true })` disables the component:
 
 ```typescript
-import '@cobwds/cob-button';
+control = new FormControl({ value: "", disabled: true });
+```
+
+```html
+<cob-textinput [formControl]="control"></cob-textinput>
 ```
 
+## Server-side rendering
+
+The components render client-side. For SSR, wrap containers in `ngSkipHydration`:
+
 ```html
-<cob-button label="Click me"></cob-button>
+<div ngSkipHydration>
+  <cob-textinput></cob-textinput>
+</div>
 ```
+
+Or use `provideClientHydration` if registering components client-only.
+
+## Zoneless
+
+The component outputs use Angular's `output()` function, which integrates with zoneless change detection. Zoneless apps work without extra configuration.
+
+## Subpath imports
+
+Import individual components:
+
+```typescript
+import { CobTextinputComponent } from "@cobwds/angular/textinput";
+import { CobCheckboxComponent } from "@cobwds/angular/checkbox";
+```
+
+## License
+
+MIT

package/data/guides/frameworks/react-additions.md

@@ -0,0 +1,69 @@
+## Using the stepper in React (multi-page pattern)
+
+`cob-stepper` requires careful state management in React. Two state variables are needed:
+
+- `currentStep` — the furthest step the user has reached (progress boundary). Maps to the `current` prop on `CobStep`.
+- `viewingStep` — which step's content is currently displayed. Maps to the `selected` prop on `CobStep`.
+
+**Always pass both `current` and `selected` explicitly from React state.** Without explicit `selected`, the stepper's internal fallback will override the user's sidebar navigation on every React re-render.
+
+**Event listening:** Use `onCobStepClick` on each `CobStep` (not on `CobStepper`). Always call `e.preventDefault()` to suppress `href`-based page navigation.
+
+**Do not use `href` for SPA routing.** Omit `href` and handle step changes entirely in React state.
+
+**Do not place `<CobStepper>` inside a `<form>` element.**
+
+```tsx
+import { useState } from 'react';
+import { CobStepper, CobStep, CobButton } from '@cobwds/react';
+
+const STEPS = [
+  { label: 'Personal Info',   content: <PersonalInfoForm /> },
+  { label: 'Contact Details', content: <ContactForm /> },
+  { label: 'Review',          content: <ReviewForm /> },
+];
+
+export function MultiStepForm() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [viewingStep, setViewingStep] = useState(0);
+
+  function handleContinue() {
+    if (viewingStep < STEPS.length - 1) {
+      setCurrentStep(viewingStep + 1);
+      setViewingStep(viewingStep + 1);
+    }
+  }
+
+  return (
+    <div className="cob-grid-row">
+      <CobStepper label="Application" className="cob-grid-col-12 cob-desktop:cob-grid-col-3">
+        {STEPS.map((step, i) => (
+          <CobStep
+            key={i}
+            label={step.label}
+            current={i === currentStep}
+            selected={i === viewingStep}
+            onCobStepClick={(e) => { e.preventDefault(); setViewingStep(i); }}
+          />
+        ))}
+        <div slot="actions">
+          <CobButton label="Save & Exit" variant="outline" fullWidth />
+        </div>
+      </CobStepper>
+
+      <main className="cob-grid-col-12 cob-desktop:cob-grid-col-9">
+        {STEPS[viewingStep].content}
+        <div style={{ display: 'flex', gap: '8px', marginTop: '16px' }}>
+          {viewingStep > 0 && (
+            <CobButton label="Back" variant="outline"
+              onCobClick={() => setViewingStep((v) => v - 1)} />
+          )}
+          {viewingStep === currentStep && currentStep < STEPS.length - 1 && (
+            <CobButton label="Continue" onCobClick={handleContinue} />
+          )}
+        </div>
+      </main>
+    </div>
+  );
+}
+```

package/data/guides/frameworks/react.md

@@ -1,48 +1,230 @@
-# COBWDS with React
+<!--
+  GENERATED FILE. Do not edit directly.
+  Source: packages/react/README.md + data/guides/frameworks/react-additions.md
+  Regenerate with: npm run sync:guides -w @cobwds/mcp-server
+-->
+# @cobwds/react
 
-> **Note:** React integration is currently untested. The guidance below is based on standard web component usage patterns and may require adjustments.
+React components for the City of Boston Web Design System (COBWDS). Generated from the COBWDS web components library.
 
-## Installation
+Works with React 18 and React 19, including Next.js App Router.
+
+## Install
+
+### Setup a new React project
 
 ```bash
-npm install @cobwds/components @cobwds/styles
+npm create vite@latest my-app -- --template react-ts
+```
+
+### Install City of Boston Web Design System
+```sh
+npm install @cobwds/react @cobwds/styles
 ```
 
 ## Load styles
 
-Import the COBWDS stylesheet in your app entry point (e.g., `index.tsx` or `App.tsx`):
+Import the design system stylesheet once, in your app's main.tsx:
+
+```tsx
+import "@cobwds/styles/full";
+```
+
+Without it, components render unstyled. `@cobwds/styles` ships the
+design tokens and global styles; component-level styles live in each
+component's shadow DOM and need no extra setup.
+
+## First component
+
+Edit your App.tsx file to import COBWDS components
+
+```tsx
+import { CobButton } from "@cobwds/react/button";
+<CobButton label="Submit" variant="filled" />
+```
+
+## Props, events, refs
+
+**Props** are typed from the underlying element class and set as DOM
+properties, not attributes. Use the camelCase property names
+(`showError`, `errorMessage`), not the kebab-case attribute names.
+
+**Events** keep their full COBWDS names, mapped to `onCob*` props:
+`cob-change` becomes `onCobChange`, `cob-input` becomes `onCobInput`.
+The handler parameter is the typed event, so `e.detail` autocompletes:
 
 ```tsx
-// New project: includes reset, typography, and utility classes
-import '@cobwds/styles/dist/cobwds-full.min.css';
+<CobTextinput
+  label="First name"
+  onCobInput={(e) => console.log(e.detail.value)}
+/>
+```
+
+There is no synthetic `onChange`. React's `onChange` prop attaches a
+native `change` listener, which COBWDS components don't dispatch — use
+`onCobChange`.
+
+**Refs** resolve to the element instance:
 
-// Existing project: CSS variables only (styles components, nothing else)
-// import '@cobwds/styles/dist/cobwds.min.css';
+```tsx
+const ref = React.useRef<CobTextinputElement>(null);
+<CobTextinput ref={ref} label="Name" />;
+// ref.current?.checkValidity()
 ```
 
-## Usage
+## Forms
+
+### Controlled
 
-Import components and use them in JSX:
+Bind `value` and update state from `onCobInput`:
 
 ```tsx
-import '@cobwds/cob-button';
-import '@cobwds/cob-alert';
+const [name, setName] = React.useState("");
+
+<CobTextinput
+  label="Name"
+  value={name}
+  onCobInput={(e) => setName(e.detail.value)}
+/>;
+```
 
-function App() {
+The wrapper re-sets properties on every commit, so re-rendering with
+the same value snaps the element back to your state.
+
+### Uncontrolled with a native form
+
+COBWDS form components are form-associated custom elements: they submit
+with a plain `<form>` like native inputs.
+
+```tsx
+function ContactForm() {
   return (
-    <div>
-      <cob-button label="Click me"></cob-button>
-      <cob-alert type="info">This is an alert.</cob-alert>
-    </div>
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        console.log(data.get("email"));
+      }}
+    >
+      <CobTextinput label="Email" name="email" type="email" />
+      <CobButton type="submit" label="Send" />
+    </form>
   );
 }
 ```
 
-## Notes on web components in React
+### React Hook Form
+
+Use `Controller` and wire the field through the event detail:
+
+```tsx
+<Controller
+  name="firstName"
+  control={control}
+  render={({ field }) => (
+    <CobTextinput
+      label="First name"
+      value={field.value}
+      onCobInput={(e) => field.onChange(e.detail.value)}
+      onCobBlur={field.onBlur}
+    />
+  )}
+/>
+```
+
+The `useCobField` helper collapses that to a prop bag. Pass the kind of
+form control: `"value"` (default), `"checked"`, or `"files"`.
+
+```tsx
+<Controller
+  name="subscribed"
+  control={control}
+  render={({ field }) => (
+    <CobCheckbox label="Subscribe" {...useCobField(field, "checked")} />
+  )}
+/>
+```
+
+To surface validation errors through the component's own error slot:
+
+```tsx
+<CobTextinput
+  label="Name"
+  showError={!!errors.name}
+  errorMessage={errors.name?.message}
+  {...useCobField(field)}
+/>
+```
+
+## SSR and Next.js
+
+Every wrapper carries a `"use client"` directive, so the App Router
+works with a normal import — no `"use client"` needed in your own files
+unless they hold state:
+
+```tsx
+// app/page.tsx (server component)
+import { Signup } from "./signup"; // a client component that renders COBWDS wrappers
+```
+
+- **App Router:** import wrappers from any client component. A server
+  component can't render a wrapper directly; pass it through a client
+  boundary like the `Signup` example.
+- **Pages Router:** import and use anywhere.
+- Components render client side. There is no declarative shadow DOM
+  server rendering in this release.
+
+## TypeScript tips
+
+- `CobTextinputProps` is the full prop type:
+  `React.ComponentProps<typeof CobTextinput>`.
+- `CobTextinputElement` is the element class type — use it for refs and
+  `e.target` casts.
+- Event detail types come from the component packages:
+  `import type { CobTextinputInputEvent } from "@cobwds/cob-textinput"`.
+- Unknown props are compile errors. If a prop is missing, check the
+  component's documented API — the wrapper exposes every public
+  property.
+
+## Troubleshooting
+
+**The element renders but has no styling or behavior.** The custom
+element didn't upgrade. Import the component from `@cobwds/react` (the
+import registers it); check the browser console for load errors. If you
+render raw `<cob-*>` tags instead of wrappers, import the
+`@cobwds/cob-*` package yourself.
+
+**Everything renders unstyled.** Import `@cobwds/styles` once at the app
+entry (see Load styles).
+
+**Hooks error or "Invalid hook call".** Usually a duplicate React.
+Check `npm ls react` and dedupe; `@cobwds/react` declares React as a
+peer dependency, so a single copy must win.
+
+**`onChange` never fires.** COBWDS components dispatch `cob-*` events.
+Use `onCobChange` / `onCobInput`, not React's `onChange`.
+
+**Rejecting user input from a handler.** If your handler sets state to
+a value React considers unchanged, React skips the re-render and the
+element keeps the user's text. Force a commit (state that always
+changes) or write the property directly in the handler:
+
+```tsx
+onCobInput={(e) => {
+  const next = sanitize(e.detail.value);
+  setValue(next);
+  (e.target as CobTextinputElement).value = next;
+}}
+```
+
+## How this package is built
+
+`src/generated/` is written by the `@cobwds/codegen` CEM plugin on every
+`npm run cem` and is not committed. Hand-written wrappers in
+`src/overrides/` replace a generated file by class name. See
+`src/overrides/README.md`.
 
-- String attributes work normally: `<cob-button label="Click me" />`
-- For event listeners, use `ref` and `addEventListener` — React's synthetic event system doesn't forward to custom elements
-- Boolean attributes should be set explicitly: `<cob-button disabled={true} />`
+## MCP guide additions
 
 ## Using the stepper in React (multi-page pattern)
 
@@ -53,7 +235,7 @@ function App() {
 
 **Always pass both `current` and `selected` explicitly from React state.** Without explicit `selected`, the stepper's internal fallback will override the user's sidebar navigation on every React re-render.
 
-**Event listening:** Use `onNysStepClick` on each `CobStep` (not on `CobStepper`). Always call `e.preventDefault()` to suppress `href`-based page navigation.
+**Event listening:** Use `onCobStepClick` on each `CobStep` (not on `CobStepper`). Always call `e.preventDefault()` to suppress `href`-based page navigation.
 
 **Do not use `href` for SPA routing.** Omit `href` and handle step changes entirely in React state.
 
@@ -61,7 +243,7 @@ function App() {
 
 ```tsx
 import { useState } from 'react';
-import { CobStepper, CobStep, CobButton } from '@cobwds/components/react';
+import { CobStepper, CobStep, CobButton } from '@cobwds/react';
 
 const STEPS = [
   { label: 'Personal Info',   content: <PersonalInfoForm /> },
@@ -89,7 +271,7 @@ export function MultiStepForm() {
             label={step.label}
             current={i === currentStep}
             selected={i === viewingStep}
-            onNysStepClick={(e) => { e.preventDefault(); setViewingStep(i); }}
+            onCobStepClick={(e) => { e.preventDefault(); setViewingStep(i); }}
           />
         ))}
         <div slot="actions">
@@ -102,10 +284,10 @@ export function MultiStepForm() {
         <div style={{ display: 'flex', gap: '8px', marginTop: '16px' }}>
           {viewingStep > 0 && (
             <CobButton label="Back" variant="outline"
-              onNysClick={() => setViewingStep((v) => v - 1)} />
+              onCobClick={() => setViewingStep((v) => v - 1)} />
           )}
           {viewingStep === currentStep && currentStep < STEPS.length - 1 && (
-            <CobButton label="Continue" onNysClick={handleContinue} />
+            <CobButton label="Continue" onCobClick={handleContinue} />
           )}
         </div>
       </main>