@nysds/components 1.13.0 → 1.13.1

package/dist/packages/mcp-server/src/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * NYSDS MCP Server Entry Point
+ *
+ * Starts the MCP server with stdio transport for local execution.
+ * Run via: npx @nysds/mcp-server
+ */
+export {};

package/dist/packages/mcp-server/src/lib/cem-parser.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Custom Elements Manifest Parser
+ *
+ * Reads and parses the custom-elements.json manifest from @nysds/components.
+ */
+export interface CEMAttribute {
+    name: string;
+    type?: {
+        text: string;
+    };
+    default?: string;
+    description?: string;
+    fieldName?: string;
+}
+export interface CEMMember {
+    kind: "field" | "method";
+    name: string;
+    type?: {
+        text: string;
+    };
+    default?: string;
+    description?: string;
+    privacy?: "public" | "private" | "protected";
+    attribute?: string;
+}
+export interface CEMEvent {
+    name: string;
+    type?: {
+        text: string;
+    };
+    description?: string;
+}
+export interface CEMSlot {
+    name: string;
+    description?: string;
+}
+export interface CEMCssProperty {
+    name: string;
+    default?: string;
+    description?: string;
+}
+export interface CEMCssPart {
+    name: string;
+    description?: string;
+}
+export interface CEMDeclaration {
+    kind: "class";
+    name: string;
+    tagName?: string;
+    summary?: string;
+    description?: string;
+    attributes?: CEMAttribute[];
+    members?: CEMMember[];
+    events?: CEMEvent[];
+    slots?: CEMSlot[];
+    cssProperties?: CEMCssProperty[];
+    cssParts?: CEMCssPart[];
+    superclass?: {
+        name: string;
+        package?: string;
+    };
+}
+export interface CEMModule {
+    kind: "javascript-module";
+    path: string;
+    declarations?: CEMDeclaration[];
+    exports?: Array<{
+        kind: string;
+        name: string;
+        declaration: {
+            name: string;
+        };
+    }>;
+}
+export interface CustomElementsManifest {
+    schemaVersion: string;
+    readme?: string;
+    modules: CEMModule[];
+}
+/**
+ * Load and parse the Custom Elements Manifest
+ */
+export declare function getCEM(): CustomElementsManifest;
+/**
+ * Get all component declarations from the manifest
+ */
+export declare function getAllComponents(): CEMDeclaration[];
+/**
+ * Get a specific component by tag name
+ */
+export declare function getComponent(tagName: string): CEMDeclaration | undefined;
+/**
+ * Clear the cached CEM (useful for testing)
+ */
+export declare function clearCache(): void;

package/dist/packages/mcp-server/src/lib/search.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Search Utilities
+ *
+ * Fuzzy search functionality for components and tokens.
+ */
+export interface SearchResult {
+    tagName: string;
+    name: string;
+    summary: string;
+    score: number;
+}
+/**
+ * Search components by name or description
+ */
+export declare function searchComponents(query: string): SearchResult[];
+/**
+ * Check if a string matches a search query
+ */
+export declare function matchesQuery(text: string, query: string): boolean;

package/dist/packages/mcp-server/src/lib/token-parser.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Design Token Parser
+ *
+ * Reads and parses NYSDS design tokens with a CSS-centric approach.
+ * Returns data aligned with tokens.css output (not JSON internals).
+ *
+ * Key transformations:
+ * - Token paths are converted to CSS variable names
+ * - Alias references become var() expressions
+ * - Layer prefixes (primitive, applied) are stripped
+ */
+/**
+ * Legacy interface for backward compatibility
+ */
+export interface DesignToken {
+    name: string;
+    value: string;
+    category: string;
+    description?: string;
+}
+/**
+ * CSS-centric token info aligned with tokens.css output
+ */
+export interface CSSTokenInfo {
+    /** CSS variable name, e.g., "--nys-color-text" */
+    cssVariable: string;
+    /** CSS value as it appears in tokens.css, e.g., "var(--nys-color-neutral-900)" or "#1b1b1b" */
+    cssValue: string;
+    /** If this is an alias, the variable it references, e.g., "--nys-color-neutral-900" */
+    referencesVariable?: string;
+    /** Fully resolved value for previews, e.g., "#1b1b1b" */
+    resolvedValue?: string;
+    /** Token description from $description field */
+    description?: string;
+    /** Token category (color, font, space, etc.) */
+    category: string;
+    /** Token layer (primitive, applied, color, etc.) */
+    layer: string;
+    /** Original JSON path for debugging */
+    jsonPath: string;
+}
+/**
+ * Token dependency graph node
+ */
+export interface TokenGraphNode {
+    cssVariable: string;
+    referencesVariable?: string;
+    usedBy: string[];
+}
+export interface TokenGroup {
+    category: string;
+    tokens: DesignToken[];
+}
+/**
+ * Get the path to tokens.json file
+ * Uses ESM-compatible path resolution with fallbacks for different contexts
+ */
+export declare function getTokensPath(): string | null;
+/**
+ * Get the path to tokens.css file
+ */
+export declare function getTokensCSSPath(): string | null;
+/**
+ * Transform a JSON token path to CSS variable name
+ *
+ * Examples:
+ * - "primitive.color.neutral.900" → "--nys-color-neutral-900"
+ * - "applied.color.text.default" → "--nys-color-text"
+ * - "color.theme.default" → "--nys-color-theme"
+ * - "font.size.md" → "--nys-font-size-md"
+ */
+export declare function toCSSVariable(jsonPath: string): string;
+/**
+ * Convert an alias reference to CSS var() syntax
+ *
+ * Examples:
+ * - "{primitive.color.neutral.900}" → "var(--nys-color-neutral-900)"
+ * - "{font.size.md}" → "var(--nys-font-size-md)"
+ */
+export declare function aliasToVarRef(aliasValue: string): {
+    cssValue: string;
+    referencesVariable: string;
+};
+/**
+ * Build a dependency graph of tokens
+ * Shows which tokens reference which, and which tokens are used by which
+ */
+export declare function buildTokenGraph(): Map<string, TokenGraphNode>;
+/**
+ * Get all tokens in CSS-centric format
+ */
+export declare function getCSSTokens(): CSSTokenInfo[];
+/**
+ * Get CSS tokens filtered by category
+ */
+export declare function getCSSTokensByCategory(category: string): CSSTokenInfo[];
+/**
+ * Get CSS tokens filtered by layer
+ */
+export declare function getCSSTokensByLayer(layer: string): CSSTokenInfo[];
+/**
+ * Search CSS tokens by variable name, value, or description
+ */
+export declare function searchCSSTokens(query: string): CSSTokenInfo[];
+/**
+ * Get a single token by CSS variable name
+ */
+export declare function getCSSTokenByVariable(variableName: string): CSSTokenInfo | undefined;
+/**
+ * Get all unique categories
+ */
+export declare function getCSSTokenCategories(): {
+    category: string;
+    count: number;
+}[];
+/**
+ * Get raw tokens.css content
+ */
+export declare function getTokensCSS(): string | null;
+/**
+ * Load all design tokens (legacy format)
+ */
+export declare function getAllTokens(): DesignToken[];
+/**
+ * Get tokens filtered by category (legacy format)
+ */
+export declare function getTokensByCategory(category: string): DesignToken[];
+/**
+ * Search tokens by name or value (legacy format)
+ */
+export declare function searchTokens(query: string): DesignToken[];
+/**
+ * Get available token categories (legacy format)
+ */
+export declare function getTokenCategories(): string[];
+/**
+ * Clear all cached tokens (useful for testing)
+ */
+export declare function clearTokenCache(): void;

package/dist/packages/mcp-server/src/prompts/nysds-mode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * NYSDS Mode Prompt
+ *
+ * Activates NYSDS-aware coding assistance.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;

package/dist/packages/mcp-server/src/resources/components.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Component Resources
+ *
+ * MCP resources for NYSDS component documentation.
+ *
+ * P0 Resources:
+ * - nysds://components - Component overview list
+ * - nysds://component/{tag} - Individual component docs
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerComponentResources(server: McpServer): void;

package/dist/packages/mcp-server/src/resources/guides.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Guide Resources
+ *
+ * MCP resources for NYSDS installation and usage guides.
+ *
+ * P0 Resources:
+ * - nysds://installation - Installation guide
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGuideResources(server: McpServer): void;

package/dist/packages/mcp-server/src/resources/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Resources Registration
+ *
+ * Registers all NYSDS resources with the MCP server.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/packages/mcp-server/src/resources/tokens.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Token Resources
+ *
+ * MCP resources for NYSDS design tokens.
+ *
+ * Resources:
+ * - nysds://tokens - All tokens in CSS-centric format
+ * - nysds://tokens/css - Raw tokens.css file content
+ * - nysds://tokens/graph - Token dependency graph with stats
+ * - nysds://tokens/color - Color tokens only
+ * - nysds://tokens/font - Typography tokens
+ * - nysds://tokens/space - Spacing tokens
+ * - nysds://tokens/size - Size tokens
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTokenResources(server: McpServer): void;

package/dist/packages/mcp-server/src/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * NYSDS MCP Server Setup
+ *
+ * Configures the MCP server with tools, resources, and prompts
+ * for the New York State Design System.
+ */
+export interface NysdsMcpServer {
+    start(): Promise<void>;
+}
+export declare function createServer(): Promise<NysdsMcpServer>;

package/dist/packages/mcp-server/src/tools/component-tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Component Tools
+ *
+ * MCP tools for working with NYSDS components.
+ *
+ * P0 Tools:
+ * - list_components: List all NYSDS components with summaries
+ * - get_component_docs: Full documentation for a specific component
+ * - find_components: Search by name/description (fuzzy)
+ * - get_usage_guide: Installation and usage patterns
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerComponentTools(server: McpServer): void;

package/dist/packages/mcp-server/src/tools/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Tools Registration
+ *
+ * Registers all NYSDS tools with the MCP server.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTools(server: McpServer): void;

package/dist/packages/mcp-server/src/tools/token-tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Token Tools
+ *
+ * MCP tools for working with NYSDS design tokens.
+ *
+ * Tools:
+ * - get_design_tokens: Get tokens with filtering and options
+ * - find_tokens: Search tokens by CSS variable, value, or description
+ * - list_themes: List all 8 agency themes
+ * - get_token_value: Get detailed info for a specific token
+ * - validate_token_usage: Validate token usage in context
+ * - list_token_categories: List categories with token counts
+ * - get_token_graph: Get token dependency graph
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTokenTools(server: McpServer): void;

package/dist/packages/mcp-server/src/tools/validation-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation Tools
+ *
+ * MCP tools for validating NYSDS component usage.
+ *
+ * P1 Tools:
+ * - validate_component_api: Validate prop/attribute usage
+ * - setup_framework: Framework-specific guides
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerValidationTools(server: McpServer): void;

package/dist/packages/nys-accordion/src/nys-accordion.d.ts

@@ -1,22 +1,39 @@
 import { LitElement } from "lit";
 import "./nys-accordionitem";
 /**
- * `<nys-accordion>` groups one or more `<nys-accordionitem>` elements.
+ * A container for grouping `nys-accordionitem` components with coordinated expand/collapse behavior.
  *
- * Features:
- * - Optionally enforces single-expanded-item behavior via `singleSelect`.
- * - Propagates shared visual `bordered` property to child items.
- * - Generates a stable unique identifier if none is provided.
+ * Place `nys-accordionitem` elements as children. Set `singleSelect` to allow only one item open at a time.
+ * The `bordered` style propagates to all children automatically.
  *
- * @slot default - Place one or more `<nys-accordionitem>` components here.
+ * @summary Container for accordion items with optional single-select and bordered styling.
+ * @element nys-accordion
  *
- * @fires nys-accordionitem-toggle - Fired when a child `<nys-accordionitem>` is toggled.
- *   Event detail includes `{ id: string, heading: string, expanded: boolean }`.
+ * @slot - Default slot for `nys-accordionitem` elements.
+ *
+ * @example Basic accordion
+ * ```html
+ * <nys-accordion>
+ *   <nys-accordionitem heading="Section 1">Content for section 1</nys-accordionitem>
+ *   <nys-accordionitem heading="Section 2">Content for section 2</nys-accordionitem>
+ * </nys-accordion>
+ * ```
+ *
+ * @example Single-select accordion
+ * ```html
+ * <nys-accordion singleSelect bordered>
+ *   <nys-accordionitem heading="FAQ 1" expanded>Answer 1</nys-accordionitem>
+ *   <nys-accordionitem heading="FAQ 2">Answer 2</nys-accordionitem>
+ * </nys-accordion>
+ * ```
  */
 export declare class NysAccordion extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Only one item can be expanded at a time. Expanding one collapses others. */
     singleSelect: boolean;
+    /** Adds borders around each accordion item. Propagates to all children. */
     bordered: boolean;
     /**
      * Lifecycle methods

package/dist/packages/nys-accordion/src/nys-accordionitem.d.ts

@@ -1,21 +1,33 @@
 import { LitElement } from "lit";
 /**
- * `<nys-accordionitem>` represents a single collapsible item inside a `<nys-accordion>`.
+ * A collapsible content panel used within `nys-accordion`. Supports keyboard navigation and smooth animations.
  *
- * @slot - Default slot for the content inside the accordion panel.
+ * Place inside `nys-accordion`. Set `expanded` to open by default. The heading acts as a toggle button
+ * accessible via click, Enter, or Space. Parent accordion controls `bordered` and `singleSelect` behavior.
  *
- * @event nys-accordionitem-toggle - Fired when the item is expanded or collapsed.
- *   @type {CustomEvent<{id: string, heading: string, expanded: boolean}>}
+ * @summary Collapsible panel for use within nys-accordion with keyboard support.
+ * @element nys-accordionitem
  *
- * Features:
- * - Click or keyboard (Enter/Space) toggles expansion.
- * - Animates height changes when expanding/collapsing.
+ * @slot - Default slot for panel content shown when expanded.
+ *
+ * @fires nys-accordionitem-toggle - Fired when expanded state changes. Detail: `{id, heading, expanded}`.
+ *
+ * @example Expanded item
+ * ```html
+ * <nys-accordionitem heading="How do I apply?" expanded>
+ *   <p>Visit ny.gov and complete the online application.</p>
+ * </nys-accordionitem>
+ * ```
  */
 export declare class NysAccordionItem extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Heading text displayed in the clickable toggle button. */
     heading: string;
+    /** Whether the content panel is visible. Toggle via click or keyboard. */
     expanded: boolean;
+    /** Adds border styling. Set by parent `nys-accordion`, not directly. */
     bordered: boolean;
     /**
      * Lifecycle methods

package/dist/packages/nys-alert/src/nys-alert.d.ts

@@ -1,30 +1,53 @@
 import { LitElement } from "lit";
 /**
- * `<nys-alert>` renders an informational, success, warning, or error alert.
+ * Displays contextual feedback messages with semantic styling. Uses ARIA live regions for screen reader announcements.
  *
- * @slot - Default slot for additional alert content.
+ * Use `info` for neutral information, `success` for confirmations, `warning` for caution, `danger` for errors,
+ * and `emergency` for critical system-wide alerts. Set `dismissible` to let users close the alert.
  *
- * @event nys-close - Fired when alert is dismissed (manual or timeout).
- *   @type {CustomEvent<{id: string, type: string, label: string}>}
+ * @summary Alert for contextual feedback with semantic types and live region support.
+ * @element nys-alert
  *
- * Features:
- * - Accessible ARIA roles and live-region announcements.
- * - Auto-close via `duration`.
- * - Handles default slot content or fallback `text`.
- * - Optional dismiss button.
+ * @slot - Default slot for custom body content. Overrides `text` prop when provided.
+ *
+ * @fires nys-close - Fired when alert is dismissed. Detail: `{id, type, label}`.
+ *
+ * @example Info alert
+ * ```html
+ * <nys-alert type="info" heading="Update available" text="A new version is ready to install."></nys-alert>
+ * ```
+ *
+ * @example Dismissible success alert
+ * ```html
+ * <nys-alert type="success" heading="Application submitted" dismissible></nys-alert>
+ * ```
  */
 export declare class NysAlert extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Bold heading text displayed at the top of the alert. */
     heading: string;
+    /** Custom icon name. Defaults to type-appropriate icon if not set. */
     icon: string;
+    /** Shows close button allowing users to dismiss the alert. */
     dismissible: boolean;
+    /** Auto-dismiss after specified milliseconds. Set to 0 to disable. */
     duration: number;
+    /** Body text content. Ignored if slot content is provided. */
     text: string;
+    /** URL for the primary action link. */
     primaryAction: string;
+    /** URL for the secondary action link. */
     secondaryAction: string;
+    /** Label text for primary action link. */
     primaryLabel: string;
+    /** Label text for secondary action link. */
     secondaryLabel: string;
+    /**
+     * Semantic alert type affecting color and ARIA role. `danger`/`emergency` use assertive live region.
+     * @default "base"
+     */
     type: "base" | "info" | "success" | "warning" | "danger" | "emergency";
     private _alertClosed;
     private _slotHasContent;

package/dist/packages/nys-avatar/src/nys-avatar.d.ts

@@ -1,25 +1,44 @@
 import { LitElement } from "lit";
 /**
- * `<nys-avatar>` displays a user avatar as an image, initials, or icon.
+ * Displays a user representation as image, initials, or icon with automatic fallback chain.
  *
- * @slot - Default slot for custom icon content. Fallback icon is used if slot is empty.
+ * Priority: `image` > `initials` > `icon` > default icon. Set `color` to customize background;
+ * foreground auto-adjusts for contrast. Use `interactive` for clickable avatars (e.g., profile menus).
  *
- * Features:
- * - Computes foreground color for sufficient contrast based on background.
- * - Supports interactive avatars with button role.
- * - Fallback to icon when image or initials are missing.
- * - Lazy loading for performance optimization.
+ * @summary User avatar with image, initials, or icon fallback and contrast-aware colors.
+ * @element nys-avatar
+ *
+ * @slot - Custom icon content. Overrides default icon when no image or initials.
+ *
+ * @example Image avatar
+ * ```html
+ * <nys-avatar image="/path/to/photo.jpg" ariaLabel="Jane Smith"></nys-avatar>
+ * ```
+ *
+ * @example Initials avatar with custom color
+ * ```html
+ * <nys-avatar initials="JS" color="var(--nys-color-theme)" ariaLabel="Jane Smith"></nys-avatar>
+ * ```
  */
 export declare class NysAvatar extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Accessible label for screen readers. Required when no image `alt` is available. */
     ariaLabel: string;
+    /** Image URL. Takes priority over initials and icon. */
     image: string;
+    /** 1-2 character initials. Used when no image is provided. */
     initials: string;
+    /** Custom icon name. Falls back to `account_circle` if not set. */
     icon: string;
+    /** Background color. Foreground auto-adjusts for contrast. Accepts CSS values or variables. */
     color: string;
+    /** Makes avatar clickable with button role and focus ring. */
     interactive: boolean;
+    /** Prevents interaction when `interactive` is true. */
     disabled: boolean;
+    /** Enables lazy loading for the image. */
     lazy: boolean;
     private _slotHasContent;
     /**

package/dist/packages/nys-backtotop/src/nys-backtotop.d.ts

@@ -1,18 +1,28 @@
 import { LitElement } from "lit";
 /**
- * `<nys-backtotop>` renders a button that scrolls the page to the top.
+ * A floating "Back to top" button that appears after scrolling. Smooth-scrolls to page top when clicked.
  *
- * Features:
- * - Automatically appears after scrolling past 1.5 viewport heights
- *   if the page is at least 4 screens tall.
- * - Adapts to mobile screens (renders as a circle button when narrow).
- * - Can be explicitly shown with the `visible` attribute.
+ * Auto-shows after scrolling 1.5 viewports on pages 4+ screens tall. Set `visible` to force display.
+ * Renders as circle button on mobile. Position with `position` prop (`left` or `right`).
  *
- * @fires nys-click - Fired when the button is clicked (scrolls page to top).
+ * @summary Floating back-to-top button with auto-show behavior and smooth scroll.
+ * @element nys-backtotop
+ *
+ * @example Auto-appearing button
+ * ```html
+ * <nys-backtotop></nys-backtotop>
+ * ```
+ *
+ * @example Always visible, left position
+ * ```html
+ * <nys-backtotop visible position="left"></nys-backtotop>
+ * ```
  */
 export declare class NysBacktotop extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Horizontal position: `left` or `right`. */
     position: string;
+    /** Force button visibility. Overrides auto-show scroll behavior. */
     visible: boolean;
     private isMobile;
     private forceVisible;