@cobwds/mcp-server 1.19.3 → 1.23.1

package/data/guides/frameworks/vue.md

@@ -0,0 +1,356 @@
+<!--
+  GENERATED FILE. Do not edit directly.
+  Source: packages/vue/README.md
+  Regenerate with: npm run sync:guides -w @cobwds/mcp-server
+-->
+# @cobwds/vue
+
+Vue 3 components for the City of Boston Web Design System (COBWDS). Generated from the COBWDS web components library.
+
+You get two ways to use the design system, and can mix them freely:
+
+- **Wrapper components** (`<CobTextinput>`) — real Vue components with
+  typed props, `@cob-*` events, `<template #slot>` slots, and `v-model`
+  on form controls.
+- **Raw `<cob-*>` tags** — the custom elements themselves, typed in
+  templates and TSX.
+
+Requires Vue 3.4 or later (tested on 3.4 and 3.5).
+
+## Install
+
+### Setup a new React project
+
+```bash
+npm create vue@latest
+```
+
+### Install NYS Design System
+```bash
+npm install @cobwds/vue @cobwds/styles
+```
+
+## Load styles
+
+Import the design system stylesheet once, in your app's main.ts:
+
+```tsx
+import "@cobwds/styles/full";
+```
+
+Vue's default TypeScript config rejects side-effect imports it can't
+resolve, and a stylesheet isn't a module. If `npm run build` fails with
+`TS2882: Cannot find module or type declarations for side-effect import of
+'@cobwds/styles/full'`, declare the stylesheets once in `env.d.ts`:
+
+```ts
+// env.d.ts
+declare module "@cobwds/styles/*";
+```
+
+Optional agency theme: `<html data-theme="health">`. Themes: `admin`,
+`business`, `environment`, `health`, `local`, `safety`, `transportation`.
+Fonts aren't bundled. Load them the way your agency normally does.
+
+### 4. Use a component
+
+```vue
+<script setup lang="ts">
+import { CobAlert, CobButton } from "@cobwds/vue";
+
+const start = () => console.log("started");
+
+</script>
+
+<template>
+  <CobAlert type="info" heading="Welcome" />
+  <CobButton label="Start" @cob-click="start" />
+</template>
+```
+
+Importing a wrapper registers its custom element as a side effect — no
+`app.use()` call or global registration. Run `npm run dev`; you should see
+a styled alert and button.
+
+That's the whole setup. No compiler options are needed for wrapper
+components. If you'd rather write raw `<cob-*>` tags, see
+[Raw tags](#raw-tags).
+
+## Props, events, slots, and refs
+
+**Props** are typed from the underlying element class and set as DOM
+properties. Use camelCase or kebab-case in templates, whichever you
+prefer (`appName` and `app-name` are the same prop). Bind numbers and
+booleans with `:` so they keep their type:
+
+```vue
+<CobPagination :total-pages="5" :current-page="1" />
+<CobTextinput label="Name" required :disabled="locked" />
+```
+
+A prop you don't pass is left alone, so the element keeps its own
+default.
+
+**Events** keep their full COBWDS names. Listen with `@cob-change`,
+`@cob-input`, and so on. The handler parameter is the typed event, so
+`e.detail` autocompletes:
+
+```vue
+<CobTextinput
+  label="First name"
+  @cob-input="(e) => console.log(e.detail.value)"
+/>
+```
+
+Use the `cob-*` events rather than native `@input` and `@change`: they
+are COBWDS's public event contract, they carry typed details, and they cover
+cases native events don't (a combobox selection, a date picked from the
+calendar).
+
+**Slots** work with `<template #name>`. The default slot renders as direct
+children:
+
+```vue
+<CobTextinput label="Email">
+  <template #description>We'll never share it.</template>
+</CobTextinput>
+
+<CobTooltip text="Tooltip text">
+  <CobButton label="Hover me" />
+</CobTooltip>
+```
+
+Named slot content is wrapped in a `<span slot="…" style="display:
+contents">` so any content (text, components, fragments) can fill it. You
+can also put a plain `slot="name"` attribute on your own child element.
+
+**Refs** on a wrapper resolve to the Vue component instance. The element
+itself is `$el`, typed as the element class:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CobTextinput } from "@cobwds/vue";
+
+const name = ref<InstanceType<typeof CobTextinput> | null>(null);
+const check = () => name.value?.$el.checkValidity();
+</script>
+
+<template>
+  <CobTextinput ref="name" label="Name" />
+</template>
+```
+
+## Forms
+
+### `v-model`
+
+Every form control supports `v-model`. It binds the property the
+component's form contract defines:
+
+| Component | `v-model` value |
+| --- | --- |
+| `CobTextinput`, `CobTextarea`, `CobSelect`, `CobCombobox`, `CobDatepicker`, `CobRadiogroup` | `string` |
+| `CobCheckboxgroup` | `string[]` |
+| `CobCheckbox`, `CobToggle` | `boolean` |
+
+```vue
+<script setup lang="ts">
+import { reactive } from "vue";
+import {
+  CobCheckbox,
+  CobCheckboxgroup,
+  CobRadiobutton,
+  CobRadiogroup,
+  CobTextinput,
+} from "@cobwds/vue";
+
+const model = reactive({
+  firstName: "",
+  agree: false,
+  languages: [] as string[],
+  contact: "",
+});
+</script>
+
+<template>
+  <CobTextinput v-model="model.firstName" label="First name" required />
+  <CobCheckbox v-model="model.agree" label="I agree to the terms" />
+
+  <CobCheckboxgroup v-model="model.languages" label="Languages">
+    <CobCheckbox label="English" value="en" />
+    <CobCheckbox label="Spanish" value="es" />
+  </CobCheckboxgroup>
+
+  <CobRadiogroup v-model="model.contact" label="Preferred contact" name="contact">
+    <CobRadiobutton label="Email" name="contact" value="email" />
+    <CobRadiobutton label="Phone" name="contact" value="phone" />
+  </CobRadiogroup>
+</template>
+```
+
+- Bind checkbox and radio groups on `CobCheckboxgroup` and
+  `CobRadiogroup`, not on each child.
+- The model updates on the component's `cob-input` and `cob-change`
+  events. Add `.lazy` (`v-model.lazy`) to update on `cob-change` alone, as
+  on a native input.
+- **File input** has no `v-model`. Listen for the change event and read
+  the files from its detail:
+
+  ```vue
+  <CobFileinput
+    label="Resume"
+    @cob-change="(e) => (model.resume = e.detail.files[0]?.name ?? '')"
+  />
+  ```
+
+### Submit and validate with a native form
+
+COBWDS form components are form-associated custom elements: they submit
+with a plain `<form>` like native inputs, and `required`, `pattern`, and
+the rest drive the component's own validation and error display.
+
+```vue
+<form @submit.prevent="onSubmit">
+  <CobTextinput v-model="model.firstName" label="First name" required />
+  <CobButton type="submit" label="Submit" />
+</form>
+```
+
+`cob-button type="submit"` submits through `form.requestSubmit()`, so an
+invalid form blocks `@submit` and the component shows its error.
+
+To drive errors from your own validation library instead, set the
+component's error props:
+
+```vue
+<CobTextinput
+  v-model="model.firstName"
+  label="First name"
+  :show-error="!!errors.firstName"
+  :error-message="errors.firstName"
+/>
+```
+
+### Reset
+
+Setting the model back to its initial values resets every control. The
+file input has no bound value, so also call `reset()` on the form:
+
+```ts
+const form = ref<HTMLFormElement | null>(null);
+
+function reset() {
+  Object.assign(model, initialModel());
+  form.value?.reset();
+}
+```
+
+## Raw tags
+
+If you prefer the custom elements directly, import the package once for
+its side effects and types, then tell Vue's compiler that `cob-*` tags are
+custom elements so it doesn't try to resolve them as components:
+
+```ts
+// vite.config.ts
+import vue from "@vitejs/plugin-vue";
+
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: { isCustomElement: (tag) => tag.startsWith("cob-") },
+      },
+    }),
+  ],
+};
+```
+
+```vue
+<script setup lang="ts">
+import { reactive } from "vue";
+import "@cobwds/vue"; // registers every element and adds the tag types
+
+const model = reactive({ firstName: "" });
+</script>
+
+<template>
+  <cob-textinput
+    label="First name"
+    :value="model.firstName"
+    @cob-input="(e) => (model.firstName = e.detail.value)"
+  />
+</template>
+```
+
+Raw tags are typed in `.vue` templates (checked by `vue-tsc`) and in TSX.
+Bind properties with `:` and update your state from the `@cob-*`
+listener.
+
+**Raw tags have no working `v-model`.** Vue's built-in `v-model` listens for
+native `input` events instead of the `cob-*` events that make up COBWDS's
+contract, so it misses updates (a combobox selection, a calendar pick, a
+checkbox). Use a wrapper component, or bind `:value` and `@cob-input`
+yourself as above.
+
+## TypeScript
+
+- `CobTextinputProps` is the full prop type, including the `on*` event
+  handlers and, for form controls, `modelValue`.
+- `CobTextinputElement` is the element class type.
+- `CobTextinputSlots` and `CobTextinputSlotName` describe the slots.
+- Event detail types come from the component packages:
+  `import type { CobTextinputInputEvent } from "@cobwds/cob-textinput"`.
+- Run `vue-tsc --noEmit` in your build to type-check templates. Unknown
+  props on a wrapper are compile errors; slot names are checked in `.vue`
+  files but not in TSX.
+
+## SSR and Nuxt
+
+The package is safe to import in Node, and a wrapper renders its bare
+element on the server. Components upgrade and become interactive in the
+browser; there is no declarative shadow DOM rendering in this release, and
+hydration has not been verified. For SSR frameworks such as Nuxt, render
+COBWDS components inside client-only boundaries (`<ClientOnly>`) until you
+have tested hydration in your app.
+
+## Troubleshooting
+
+**The element renders but has no styling or behavior.** The custom
+element didn't upgrade. Import the component from `@cobwds/vue` (the import
+registers it) and check the browser console for load errors. If you use
+raw `<cob-*>` tags, add `import "@cobwds/vue"` yourself.
+
+**Everything renders unstyled.** Import `@cobwds/styles/full` once at your
+entry file.
+
+**`Failed to resolve component: cob-…`.** You used a raw tag without the
+`isCustomElement` compiler option. Add it (see [Raw tags](#raw-tags)) or
+use the wrapper component instead.
+
+**`v-model` on a raw `<cob-*>` tag doesn't update.** See
+[Raw tags](#raw-tags): use a wrapper, or bind `:value` and `@cob-input`.
+
+**A prop change doesn't reach the element.** Bind numbers and booleans
+with `:` (`:total-pages="5"`), not as plain attributes, so Vue passes the
+typed value.
+
+**Slot content has an extra wrapper.** Named slot content sits inside a
+`display: contents` span. To avoid it, put a `slot="name"` attribute on
+your own child element instead of using `<template #name>`.
+
+**`app.use(router)` or the `<cob-*>` types break with two Vue versions.**
+Two copies of Vue in `node_modules` give TypeScript two sets of types. Run
+`npm ls vue` and dedupe. In a monorepo where you pin a different Vue in one
+workspace, map `vue` in that app's `tsconfig.json`:
+
+```json
+{ "compilerOptions": { "baseUrl": ".", "paths": { "vue": ["./node_modules/vue"] } } }
+```
+
+## How this package is built
+
+`src/generated/` is written by the `@cobwds/codegen` CEM plugin on every
+`npm run cem` and is not committed. The one hand-written file is
+`src/runtime.ts`, which builds each wrapper from the generated metadata.

package/data/tokens/tokens.css

@@ -1,5 +1,5 @@
 /*!
- * City of Boston Web Design System v1.19.3
+ * City of Boston Web Design System v1.23.1
  * Description: A web design system for the City of Boston's digital products.
  * Repository: https://github.com/CityOfBoston/nywds-poc
  * License: MIT
@@ -12,7 +12,7 @@
   --cob-border-width-lg: 4px;
   --cob-border-width-md: 2px;
   --cob-border-width-sm: 1px;
-  --cob-color-accent: var(--cob-color-freedom-trail-red);
+  --cob-color-accent: var(--cob-color-red-400);
   --cob-color-admin-orange-10: #fcf4ef;
   --cob-color-admin-orange-50: #f9e9e0;
   --cob-color-admin-orange-100: #f3d3c1;
@@ -37,16 +37,16 @@
   --cob-color-black-transparent-700: #000000b3;
   --cob-color-black-transparent-800: #000000cc;
   --cob-color-black-transparent-900: #000000e6;
-  --cob-color-blue-10: #e8f4fc;
-  --cob-color-blue-50: #cee4f4;
-  --cob-color-blue-100: #b4d3ec;
-  --cob-color-blue-200: #9ac3e4;
-  --cob-color-blue-300: #80b2dc;
-  --cob-color-blue-400: #66a2d5;
-  --cob-color-blue-500: #4c92cd;
-  --cob-color-blue-600: #3281c5;
-  --cob-color-blue-700: var(--cob-color-optimistic-blue);
-  --cob-color-blue-800: #104876;
+  --cob-color-blue-10: #f0f7fd;
+  --cob-color-blue-50: #e3f0fb;
+  --cob-color-blue-100: #c7e1f8;
+  --cob-color-blue-200: #93c5f1;
+  --cob-color-blue-300: #5fa9ea;
+  --cob-color-blue-400: #268be3;
+  --cob-color-blue-500: var(--cob-color-optimistic-blue);
+  --cob-color-blue-600: #145b99;
+  --cob-color-blue-700: #0f4575;
+  --cob-color-blue-800: #0b3051;
   --cob-color-blue-900: var(--cob-color-charles-blue);
   --cob-color-business-teal-10: #f2f6f6;
   --cob-color-business-teal-50: #e5eded;
@@ -90,24 +90,13 @@
   --cob-color-green-700: #165923;
   --cob-color-green-800: #0f3d18;
   --cob-color-green-900: #08210d;
-  --cob-color-health-purple-10: #f4f4f8;
-  --cob-color-health-purple-50: #e9eaf1;
-  --cob-color-health-purple-100: #d3d5e3;
-  --cob-color-health-purple-200: #bbb8cc;
-  --cob-color-health-purple-300: #a39bb6;
-  --cob-color-health-purple-400: #8b7fa0;
-  --cob-color-health-purple-500: #736289;
-  --cob-color-health-purple-600: #5b4573;
-  --cob-color-health-purple-700: #43285d;
-  --cob-color-health-purple-800: #2c1a3e;
-  --cob-color-health-purple-900: #160d1f;
   --cob-color-info: var(--cob-color-blue-600);
   --cob-color-info-strong: var(--cob-color-blue-800);
   --cob-color-info-weak: var(--cob-color-blue-50);
   --cob-color-ink: var(--cob-color-neutral-900);
   --cob-color-ink-reverse: var(--cob-color-white);
   --cob-color-link: var(--cob-color-blue-600);
-  --cob-color-link-neutral: var(--cob-color-neutral-900);
+  --cob-color-link-neutral: var(--cob-color-blue-900);
   --cob-color-link-reverse: var(--cob-color-neutral-300);
   --cob-color-link-reverse-neutral: var(--cob-color-white);
   --cob-color-link-reverse-strong: var(--cob-color-neutral-50);
@@ -137,17 +126,28 @@
   --cob-color-neutral-800: #323435;
   --cob-color-neutral-900: #1b1b1b;
   --cob-color-optimistic-blue: #1871bd;
-  --cob-color-red-10: #fbf4f4;
-  --cob-color-red-50: #f7eaea;
-  --cob-color-red-100: #f0d5d5;
-  --cob-color-red-200: #e4b3b3;
-  --cob-color-red-300: #d89191;
-  --cob-color-red-400: #cc6f6f;
-  --cob-color-red-500: #c04d4d;
-  --cob-color-red-600: #b52c2c;
-  --cob-color-red-700: #932424;
-  --cob-color-red-800: #721c1c;
-  --cob-color-red-900: #511414;
+  --cob-color-purple-10: #f4f4f8;
+  --cob-color-purple-50: #e9eaf1;
+  --cob-color-purple-100: #d3d5e3;
+  --cob-color-purple-200: #bbb8cc;
+  --cob-color-purple-300: #a39bb6;
+  --cob-color-purple-400: #8b7fa0;
+  --cob-color-purple-500: #736289;
+  --cob-color-purple-600: #5b4573;
+  --cob-color-purple-700: #43285d;
+  --cob-color-purple-800: #2c1a3e;
+  --cob-color-purple-900: #160d1f;
+  --cob-color-red-10: #fff3f2;
+  --cob-color-red-50: #fee8e6;
+  --cob-color-red-100: #fed1ce;
+  --cob-color-red-200: #fda9a4;
+  --cob-color-red-300: #fc7e76;
+  --cob-color-red-400: var(--cob-color-freedom-trail-red);
+  --cob-color-red-500: #e51205;
+  --cob-color-red-600: #c20f04;
+  --cob-color-red-700: #9e0d03;
+  --cob-color-red-800: #7c0a03;
+  --cob-color-red-900: #590702;
   --cob-color-safety-gray-10: #f2f5f6;
   --cob-color-safety-gray-50: #e5ebed;
   --cob-color-safety-gray-100: #cdd6da;
@@ -159,17 +159,6 @@
   --cob-color-safety-gray-700: #435d6e;
   --cob-color-safety-gray-800: #30424f;
   --cob-color-safety-gray-900: #1d2830;
-  --cob-color-state-blue-10: #f7fafd;
-  --cob-color-state-blue-50: #eff6fb;
-  --cob-color-state-blue-100: #cddde9;
-  --cob-color-state-blue-200: #abc4d8;
-  --cob-color-state-blue-300: #89abc7;
-  --cob-color-state-blue-400: #6792b6;
-  --cob-color-state-blue-500: #457aa5;
-  --cob-color-state-blue-600: #2d618c;
-  --cob-color-state-blue-700: #154973;
-  --cob-color-state-blue-800: #0e324f;
-  --cob-color-state-blue-900: #081b2b;
   --cob-color-success: var(--cob-color-green-600);
   --cob-color-success-strong: var(--cob-color-green-800);
   --cob-color-success-weak: var(--cob-color-green-50);
@@ -185,11 +174,11 @@
   --cob-color-text-weak: var(--cob-color-neutral-700);
   --cob-color-text-weaker: var(--cob-color-neutral-500);
   --cob-color-text-weakest: var(--cob-color-neutral-200);
-  --cob-color-theme: var(--cob-color-optimistic-blue);
+  --cob-color-theme: var(--cob-color-blue-500);
   --cob-color-theme-faint: var(--cob-color-blue-10);
-  --cob-color-theme-mid: var(--cob-color-blue-500);
+  --cob-color-theme-mid: var(--cob-color-blue-200);
   --cob-color-theme-strong: var(--cob-color-blue-800);
-  --cob-color-theme-stronger: var(--cob-color-charles-blue);
+  --cob-color-theme-stronger: var(--cob-color-blue-900);
   --cob-color-theme-weak: var(--cob-color-blue-100);
   --cob-color-theme-weaker: var(--cob-color-blue-50);
   --cob-color-transparent: #ffffff00;
@@ -435,13 +424,13 @@
 
 [data-theme="health"],
 .cob-theme-health {
-  --cob-color-theme: var(--cob-color-health-purple-700);
-  --cob-color-theme-faint: var(--cob-color-health-purple-10);
-  --cob-color-theme-mid: var(--cob-color-health-purple-500);
-  --cob-color-theme-strong: var(--cob-color-health-purple-800);
-  --cob-color-theme-stronger: var(--cob-color-health-purple-900);
-  --cob-color-theme-weak: var(--cob-color-health-purple-100);
-  --cob-color-theme-weaker: var(--cob-color-health-purple-50);
+  --cob-color-theme: var(--cob-color-purple-700);
+  --cob-color-theme-faint: var(--cob-color-purple-10);
+  --cob-color-theme-mid: var(--cob-color-purple-500);
+  --cob-color-theme-strong: var(--cob-color-purple-800);
+  --cob-color-theme-stronger: var(--cob-color-purple-900);
+  --cob-color-theme-weak: var(--cob-color-purple-100);
+  --cob-color-theme-weaker: var(--cob-color-purple-50);
 }
 
 [data-theme="local"],