@nysds/mcp-server 1.19.3 → 1.20.0

package/data/guides/form-validation.md

@@ -165,5 +165,5 @@ The following NYSDS 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**: NYSDS components automatically set `aria-invalid` and `aria-describedby`
+3. **ARIA attributes**: NYSDS form components automatically set `aria-invalid` on the control and associate the error message via `aria-errormessage`, and associate the visible `<nys-label>` with the control via `aria-labelledby` — no manual wiring needed
 4. **Clear error messages**: Use specific, actionable error text

package/data/tokens/tokens.css

@@ -1,5 +1,5 @@
 /*!
- * New York State Design System v1.19.3
+ * New York State Design System v1.20.0
  * Description: A design system for New York State's digital products.
  * Repository: https://github.com/its-hcd/nysds
  * License: MIT

package/dist/lib/guides.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Guide Loading & Indexing
+ *
+ * Single source of truth for reading guide markdown from data/guides/.
+ * Also builds a reverse index of which guides mention which component tags,
+ * so component lookups can point at the guides that actually cover them.
+ */
+export declare const GUIDE_TOPICS: readonly ["installation", "form-validation", "styles", "fonts", "page-structure", "themes"];
+export declare const GUIDE_FRAMEWORKS: readonly ["angular", "react", "dotnet", "drupal", "vanilla"];
+export type GuideTopic = (typeof GUIDE_TOPICS)[number];
+export type GuideFramework = (typeof GUIDE_FRAMEWORKS)[number];
+/**
+ * Load a topic guide's markdown content.
+ */
+export declare function loadTopicGuide(topic: GuideTopic): string;
+/**
+ * Load a framework-specific guide's markdown content.
+ */
+export declare function loadFrameworkGuide(framework: GuideFramework): string;
+export interface GuideReference {
+    /** Human-readable name of the guide, e.g. "form-validation" */
+    guide: string;
+    /** Topic guide key, e.g. "form-validation" */
+    topic: GuideTopic;
+    /** Framework guide key, when the reference came from a framework guide */
+    framework?: GuideFramework;
+    /** The get_guide call that retrieves it */
+    call: string;
+}
+/**
+ * Get the guides that mention a given component tag.
+ *
+ * Framework guides are collapsed into a single "see framework guides" hint
+ * rather than five near-identical entries, since every framework guide uses
+ * nys-button and nys-alert as its example markup.
+ */
+export declare function getGuidesMentioning(tagName: string): GuideReference[];
+/**
+ * Clear the cached index (useful for testing).
+ */
+export declare function clearGuideCache(): void;
+//# sourceMappingURL=guides.d.ts.map

package/dist/lib/guides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guides.d.ts","sourceRoot":"","sources":["../../src/lib/guides.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,eAAO,MAAM,YAAY,6FAOf,CAAC;AAEX,eAAO,MAAM,gBAAgB,8DAMnB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAW/D;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CASpE;AAMD,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,KAAK,EAAE,UAAU,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAmED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAcrE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/lib/guides.js

@@ -0,0 +1,133 @@
+/**
+ * Guide Loading & Indexing
+ *
+ * Single source of truth for reading guide markdown from data/guides/.
+ * Also builds a reverse index of which guides mention which component tags,
+ * so component lookups can point at the guides that actually cover them.
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Path to guides directory (relative to dist/lib/)
+const GUIDES_DIR = join(__dirname, "../../data/guides");
+export const GUIDE_TOPICS = [
+    "installation",
+    "form-validation",
+    "styles",
+    "fonts",
+    "page-structure",
+    "themes",
+];
+export const GUIDE_FRAMEWORKS = [
+    "angular",
+    "react",
+    "dotnet",
+    "drupal",
+    "vanilla",
+];
+const TOPIC_TO_FILE = {
+    installation: "installation.md",
+    "form-validation": "form-validation.md",
+    styles: "styles.md",
+    fonts: "fonts.md",
+    "page-structure": "page-structure.md",
+    themes: "themes.md",
+};
+/**
+ * Load a topic guide's markdown content.
+ */
+export function loadTopicGuide(topic) {
+    try {
+        return readFileSync(join(GUIDES_DIR, TOPIC_TO_FILE[topic]), "utf-8");
+    }
+    catch {
+        return `Guide not found: ${topic}`;
+    }
+}
+/**
+ * Load a framework-specific guide's markdown content.
+ */
+export function loadFrameworkGuide(framework) {
+    try {
+        return readFileSync(join(GUIDES_DIR, "frameworks", `${framework}.md`), "utf-8");
+    }
+    catch {
+        return `Framework guide not found: ${framework}`;
+    }
+}
+let cachedTagIndex = null;
+const TAG_PATTERN = /nys-[a-z][a-z0-9-]*/g;
+function indexGuide(content, ref, index) {
+    const seen = new Set();
+    for (const match of content.matchAll(TAG_PATTERN)) {
+        const tag = match[0];
+        if (seen.has(tag))
+            continue;
+        seen.add(tag);
+        const existing = index.get(tag);
+        if (existing) {
+            existing.push(ref);
+        }
+        else {
+            index.set(tag, [ref]);
+        }
+    }
+}
+/**
+ * Build (and cache) the tag -> guides index.
+ *
+ * The index is keyed on every `nys-*` string found in guide markdown, which
+ * includes non-component matches like CSS variables (`--nys-color-*`) and
+ * utility classes (`nys-grid-col-6`). Callers are expected to look up real
+ * component tag names, so those extra keys are never read.
+ */
+function getTagIndex() {
+    if (cachedTagIndex)
+        return cachedTagIndex;
+    const index = new Map();
+    for (const topic of GUIDE_TOPICS) {
+        indexGuide(loadTopicGuide(topic), {
+            guide: topic,
+            topic,
+            call: `get_guide({ topic: "${topic}" })`,
+        }, index);
+    }
+    for (const framework of GUIDE_FRAMEWORKS) {
+        indexGuide(loadFrameworkGuide(framework), {
+            guide: `${framework} setup`,
+            topic: "installation",
+            framework,
+            call: `get_guide({ topic: "installation", framework: "${framework}" })`,
+        }, index);
+    }
+    cachedTagIndex = index;
+    return index;
+}
+/**
+ * Get the guides that mention a given component tag.
+ *
+ * Framework guides are collapsed into a single "see framework guides" hint
+ * rather than five near-identical entries, since every framework guide uses
+ * nys-button and nys-alert as its example markup.
+ */
+export function getGuidesMentioning(tagName) {
+    const refs = getTagIndex().get(tagName.toLowerCase()) ?? [];
+    const topicRefs = refs.filter((r) => !r.framework);
+    const frameworkRefs = refs.filter((r) => r.framework);
+    const result = [...topicRefs];
+    if (frameworkRefs.length > 0) {
+        result.push({
+            guide: `framework setup (${frameworkRefs.map((r) => r.framework).join(", ")})`,
+            topic: "installation",
+            call: `get_guide({ topic: "installation", framework: "${frameworkRefs[0].framework}" })`,
+        });
+    }
+    return result;
+}
+/**
+ * Clear the cached index (useful for testing).
+ */
+export function clearGuideCache() {
+    cachedTagIndex = null;
+}

package/dist/lib/relationships.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Component Relationships & Integration
+ *
+ * Derives how components connect to each other, to their npm packages, and to
+ * the guides that cover them — all from the Custom Elements Manifest, so it
+ * stays in sync as components are added or renamed.
+ *
+ * Two derivation passes:
+ *
+ * 1. **Family** — components declared under the same `packages/<name>/` source
+ *    directory ship in the same npm package. Containment *within* a family is
+ *    read from the docs rather than the directory name, which is unreliable
+ *    (`packages/nys-checkbox` contains the container `nys-checkboxgroup`):
+ *
+ *    a. A container's slot descriptions name its children — "Default slot for
+ *       `nys-checkbox` elements", "Accepts `<nys-tab>` and `<nys-tabpanel>`".
+ *    b. A child's description names its container — "for use within
+ *       `nys-select`", "a single step within `nys-stepper`".
+ *    c. A component marked "**Slotted component.**" or "**Internal
+ *       component.**" falls back to the only unmarked member of its family.
+ *
+ *    This is how `nys-option` is known to belong inside `nys-select`, and
+ *    `nys-checkbox` inside `nys-checkboxgroup` rather than the reverse.
+ *
+ * 2. **Mentions** — component JSDoc names sibling and alternative components in
+ *    prose (`For 7+ options, use \`nys-select\``). Scanning descriptions, slots,
+ *    and attribute docs recovers those edges in both directions.
+ *
+ * Mentions are filtered against the set of registered tag names, which drops
+ * event names (`nys-change`, `nys-input`), CSS variables, and stale references
+ * to components that no longer exist. A tag that is *also* an event name
+ * (`nys-select` is both a component and an event emitted by `nys-textarea`) is
+ * additionally checked against its surrounding phrasing so an "emits
+ * `nys-select`" sentence does not fabricate a component relationship.
+ */
+import { type CEMDeclaration } from "./cem-parser.js";
+import { type GuideReference } from "./guides.js";
+export type RelationKind = "parent" | "child" | "sibling" | "mentions" | "mentioned-by" | "mutual";
+export interface RelatedComponent {
+    tagName: string;
+    summary: string;
+    relation: RelationKind;
+    /** Why this edge exists, in one line */
+    note: string;
+    /** Same npm package as the component being described */
+    samePackage: boolean;
+}
+export interface ComponentIntegration {
+    package: string;
+    install: string;
+    imports: {
+        component: string;
+        allComponents: string;
+        react: string;
+        styles: string;
+    };
+    stylesNote: string;
+    /** Subcomponents / parents that must be present for correct usage */
+    requires: RelatedComponent[];
+    /** Components commonly used alongside this one */
+    usedWith: RelatedComponent[];
+    /** Components the docs point to as alternatives for other situations */
+    alternatives: RelatedComponent[];
+    guides: GuideReference[];
+    styling: {
+        cssCustomProperties: {
+            name: string;
+            description?: string;
+        }[];
+        spacing: string;
+        tokens: string;
+    };
+    nextSteps: string[];
+}
+/**
+ * Get the npm package a component ships in.
+ * Subcomponents resolve to their parent's package.
+ */
+export declare function getPackageName(tagName: string): string;
+export interface ComponentRelationships {
+    /** The npm package family this component belongs to */
+    package: string;
+    /** Container component, when this is a subcomponent */
+    parent?: RelatedComponent;
+    /** Subcomponents this component contains */
+    children: RelatedComponent[];
+    /** Other subcomponents in the same package */
+    siblings: RelatedComponent[];
+    /** Components referenced across package boundaries */
+    related: RelatedComponent[];
+}
+export declare function getRelationships(tagName: string): ComponentRelationships;
+/**
+ * Build the full integration payload for a component: what to install, what to
+ * import, what has to be nested inside it, and which guides cover it.
+ */
+export declare function getIntegration(component: CEMDeclaration): ComponentIntegration;
+/**
+ * Clear cached derivations (useful for testing).
+ */
+export declare function clearRelationshipCache(): void;
+//# sourceMappingURL=relationships.d.ts.map

package/dist/lib/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/lib/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAMvE,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,OAAO,GACP,SAAS,GACT,UAAU,GACV,cAAc,GACd,QAAQ,CAAC;AAEb,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,wEAAwE;IACxE,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,OAAO,EAAE;QACP,mBAAmB,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC9D,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAuKD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAItD;AAyHD,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,sDAAsD;IACtD,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAqFxE;AAWD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,cAAc,GACxB,oBAAoB,CAuEtB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C"}