@nysds/mcp-server 1.21.0 → 1.22.0

package/data/frameworks.json

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

package/data/guides/frameworks/angular.md

@@ -1,16 +1,32 @@
-# NYSDS with Angular
+<!--
+  GENERATED FILE. Do not edit directly.
+  Source: packages/angular/README.md
+  Regenerate with: npm run sync:guides -w @nysds/mcp-server
+-->
+# @nysds/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 New York State Design System (NYSDS). Generated from the NYSDS 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 @nysds/components @nysds/styles
+npm install @nysds/angular @nysds/styles
 ```
 
+Peer dependencies: Angular `>=20.0.0` (core, common, forms).
+
 ## Load styles
 
-Add the NYSDS stylesheet to `angular.json`:
+Add NYSDS styles to your `angular.json`:
 
 ```json
 {
@@ -20,8 +36,7 @@ Add the NYSDS stylesheet to `angular.json`:
         "build": {
           "options": {
             "styles": [
-              "node_modules/@nysds/styles/dist/nysds-full.min.css",
-              "src/styles.css"
+              "node_modules/@nysds/styles/nysds-full.min.css"
             ]
           }
         }
@@ -31,41 +46,184 @@ Add the NYSDS stylesheet to `angular.json`:
 }
 ```
 
-Use `nysds-full.min.css` for new projects (includes reset, typography, and utilities) or `nysds.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 { NysButtonComponent } from '@nysds/angular';
+@Component({
+  imports: [RouterOutlet, NysButtonComponent],
+  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
+<nys-textinput
+  [label]="'Email'"
+  [required]="true"
+  (nysChange)="onEmailChange($event)"
+></nys-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: NysTextinputChangeEvent) {
+  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>
+  <nys-textinput [(ngModel)]="email" name="email"></nys-textinput>
+  <nys-checkbox [(ngModel)]="agreed" name="agreed"></nys-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: `<nys-button label="Click me"></nys-button>`
-})
-export class MyComponent {}
+```html
+<form [formGroup]="form">
+  <nys-textinput formControlName="email"></nys-textinput>
+  <nys-checkbox formControlName="agreed"></nys-checkbox>
+</form>
+```
+
+### Signal Forms (Angular 21+)
+
+Use `[formField]` with a form field definition:
+
+```typescript
+email = signal<string>("");
+emailControl = new FormControl<string>("", Validators.required);
+```
+
+```html
+<nys-textinput [formField]="emailControl"></nys-textinput>
+```
+
+### Group controls
+
+`nys-checkboxgroup` and `nys-radiogroup` bind at group level:
+
+```typescript
+form = this.fb.group({
+  languages: [["en"], Validators.required],
+});
+```
+
+```html
+<nys-checkboxgroup formControlName="languages">
+  <nys-checkbox value="en">English</nys-checkbox>
+  <nys-checkbox value="es">Spanish</nys-checkbox>
+</nys-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
+<nys-textinput
+  formControlName="email"
+  nysControlErrors
+></nys-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 '@nysds/nys-button';
+control = new FormControl({ value: "", disabled: true });
+```
+
+```html
+<nys-textinput [formControl]="control"></nys-textinput>
 ```
 
+## Server-side rendering
+
+The components render client-side. For SSR, wrap containers in `ngSkipHydration`:
+
 ```html
-<nys-button label="Click me"></nys-button>
+<div ngSkipHydration>
+  <nys-textinput></nys-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 { NysTextinputComponent } from "@nysds/angular/textinput";
+import { NysCheckboxComponent } from "@nysds/angular/checkbox";
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,69 @@
+## Using the stepper in React (multi-page pattern)
+
+`nys-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 `NysStep`.
+- `viewingStep` — which step's content is currently displayed. Maps to the `selected` prop on `NysStep`.
+
+**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 `NysStep` (not on `NysStepper`). 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 `<NysStepper>` inside a `<form>` element.**
+
+```tsx
+import { useState } from 'react';
+import { NysStepper, NysStep, NysButton } from '@nysds/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="nys-grid-row">
+      <NysStepper label="Application" className="nys-grid-col-12 nys-desktop:nys-grid-col-3">
+        {STEPS.map((step, i) => (
+          <NysStep
+            key={i}
+            label={step.label}
+            current={i === currentStep}
+            selected={i === viewingStep}
+            onNysStepClick={(e) => { e.preventDefault(); setViewingStep(i); }}
+          />
+        ))}
+        <div slot="actions">
+          <NysButton label="Save & Exit" variant="outline" fullWidth />
+        </div>
+      </NysStepper>
+
+      <main className="nys-grid-col-12 nys-desktop:nys-grid-col-9">
+        {STEPS[viewingStep].content}
+        <div style={{ display: 'flex', gap: '8px', marginTop: '16px' }}>
+          {viewingStep > 0 && (
+            <NysButton label="Back" variant="outline"
+              onNysClick={() => setViewingStep((v) => v - 1)} />
+          )}
+          {viewingStep === currentStep && currentStep < STEPS.length - 1 && (
+            <NysButton label="Continue" onNysClick={handleContinue} />
+          )}
+        </div>
+      </main>
+    </div>
+  );
+}
+```

package/data/guides/frameworks/react.md

@@ -1,48 +1,230 @@
-# NYSDS 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 @nysds/mcp-server
+-->
+# @nysds/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 New York State Design System (NYSDS). Generated from the NYSDS 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 @nysds/components @nysds/styles
+npm create vite@latest my-app -- --template react-ts
+```
+
+### Install NYS Design System
+```sh
+npm install @nysds/react @nysds/styles
 ```
 
 ## Load styles
 
-Import the NYSDS 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 "@nysds/styles/full";
+```
+
+Without it, components render unstyled. `@nysds/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 NYSDS components
+
+```tsx
+import { NysButton } from "@nysds/react/button";
+<NysButton 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 NYSDS names, mapped to `onNys*` props:
+`nys-change` becomes `onNysChange`, `nys-input` becomes `onNysInput`.
+The handler parameter is the typed event, so `e.detail` autocompletes:
 
 ```tsx
-// New project: includes reset, typography, and utility classes
-import '@nysds/styles/dist/nysds-full.min.css';
+<NysTextinput
+  label="First name"
+  onNysInput={(e) => console.log(e.detail.value)}
+/>
+```
+
+There is no synthetic `onChange`. React's `onChange` prop attaches a
+native `change` listener, which NYSDS components don't dispatch — use
+`onNysChange`.
+
+**Refs** resolve to the element instance:
 
-// Existing project: CSS variables only (styles components, nothing else)
-// import '@nysds/styles/dist/nysds.min.css';
+```tsx
+const ref = React.useRef<NysTextinputElement>(null);
+<NysTextinput ref={ref} label="Name" />;
+// ref.current?.checkValidity()
 ```
 
-## Usage
+## Forms
+
+### Controlled
 
-Import components and use them in JSX:
+Bind `value` and update state from `onNysInput`:
 
 ```tsx
-import '@nysds/nys-button';
-import '@nysds/nys-alert';
+const [name, setName] = React.useState("");
+
+<NysTextinput
+  label="Name"
+  value={name}
+  onNysInput={(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
+
+NYSDS form components are form-associated custom elements: they submit
+with a plain `<form>` like native inputs.
+
+```tsx
+function ContactForm() {
   return (
-    <div>
-      <nys-button label="Click me"></nys-button>
-      <nys-alert type="info">This is an alert.</nys-alert>
-    </div>
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        console.log(data.get("email"));
+      }}
+    >
+      <NysTextinput label="Email" name="email" type="email" />
+      <NysButton 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 }) => (
+    <NysTextinput
+      label="First name"
+      value={field.value}
+      onNysInput={(e) => field.onChange(e.detail.value)}
+      onNysBlur={field.onBlur}
+    />
+  )}
+/>
+```
+
+The `useNysField` 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 }) => (
+    <NysCheckbox label="Subscribe" {...useNysField(field, "checked")} />
+  )}
+/>
+```
+
+To surface validation errors through the component's own error slot:
+
+```tsx
+<NysTextinput
+  label="Name"
+  showError={!!errors.name}
+  errorMessage={errors.name?.message}
+  {...useNysField(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 NYSDS 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
+
+- `NysTextinputProps` is the full prop type:
+  `React.ComponentProps<typeof NysTextinput>`.
+- `NysTextinputElement` is the element class type — use it for refs and
+  `e.target` casts.
+- Event detail types come from the component packages:
+  `import type { NysTextinputInputEvent } from "@nysds/nys-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 `@nysds/react` (the
+import registers it); check the browser console for load errors. If you
+render raw `<nys-*>` tags instead of wrappers, import the
+`@nysds/nys-*` package yourself.
+
+**Everything renders unstyled.** Import `@nysds/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; `@nysds/react` declares React as a
+peer dependency, so a single copy must win.
+
+**`onChange` never fires.** NYSDS components dispatch `nys-*` events.
+Use `onNysChange` / `onNysInput`, 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
+onNysInput={(e) => {
+  const next = sanitize(e.detail.value);
+  setValue(next);
+  (e.target as NysTextinputElement).value = next;
+}}
+```
+
+## How this package is built
+
+`src/generated/` is written by the `@nysds/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: `<nys-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: `<nys-button disabled={true} />`
+## MCP guide additions
 
 ## Using the stepper in React (multi-page pattern)
 
@@ -61,7 +243,7 @@ function App() {
 
 ```tsx
 import { useState } from 'react';
-import { NysStepper, NysStep, NysButton } from '@nysds/components/react';
+import { NysStepper, NysStep, NysButton } from '@nysds/react';
 
 const STEPS = [
   { label: 'Personal Info',   content: <PersonalInfoForm /> },