@nysds/components 1.16.0-alpha3 → 1.16.0-alpha5

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

@@ -43,6 +43,11 @@ export interface CEMCssPart {
     name: string;
     description?: string;
 }
+export interface CEMExample {
+    title: string;
+    code: string;
+    lang?: string;
+}
 export interface CEMDeclaration {
     kind: "class";
     name: string;
@@ -59,6 +64,7 @@ export interface CEMDeclaration {
         name: string;
         package?: string;
     };
+    examples?: CEMExample[];
 }
 export interface CEMModule {
     kind: "javascript-module";

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

@@ -0,0 +1,21 @@
+/**
+ * Format Utilities
+ *
+ * Helpers for formatting MCP tool responses.
+ */
+/**
+ * JSON replacer that strips null and undefined values from objects.
+ * Use with JSON.stringify(obj, stripNulls, 2) for cleaner output.
+ */
+export declare function stripNulls(_key: string, value: unknown): unknown;
+/**
+ * Format an object as JSON, stripping null/undefined values and empty arrays.
+ */
+export declare function formatResponse(data: unknown): string;
+/**
+ * Create a text content response for MCP tools.
+ */
+export declare function textContent(data: unknown): {
+    type: "text";
+    text: string;
+};

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

@@ -3,11 +3,9 @@
  *
  * 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
+ * Tools:
+ * - find_components: Search or list all components
+ * - get_component: Full documentation for a specific component
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerComponentTools(server: McpServer): void;

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

@@ -0,0 +1,8 @@
+/**
+ * Guide Tools
+ *
+ * Consolidated MCP tool for NYSDS guides and documentation.
+ * Loads guide content from data/guides/ markdown files.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGuideTools(server: McpServer): void;

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

@@ -4,12 +4,9 @@
  * MCP tools for working with NYSDS design tokens.
  *
  * Tools:
- * - get_design_tokens: Get tokens with filtering and options
+ * - get_tokens: Get tokens, categories, or themes
  * - 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_info: Get detailed token info with optional context validation
  * - get_token_graph: Get token dependency graph
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

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

@@ -0,0 +1,7 @@
+/**
+ * Utility Tools
+ *
+ * MCP tools for NYSDS utility classes.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerUtilityTools(server: McpServer): void;

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

@@ -3,9 +3,8 @@
  *
  * MCP tools for validating NYSDS component usage.
  *
- * P1 Tools:
+ * 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-button/src/nys-button.d.ts

@@ -159,7 +159,6 @@ export declare class NysButton extends LitElement {
      * @default "_self"
      */
     target: "_self" | "_blank" | "_parent" | "_top" | "framename";
-    getButtonElement(): Promise<HTMLElement | null>;
     private _internals;
     /**
      * Lifecycle methods
@@ -183,10 +182,14 @@ export declare class NysButton extends LitElement {
     private _handleClick;
     private _handleKeydown;
     /**
-     * Vanilla JS & Native HTML keydown solution:
-     * The <nys-button onClick="doFunction();"></nys-button> onClick is an attribute here.
-     * Thus, we call it here. Otherwise, at this point, this.onClick is null as it isn't props, but a string attribute
-     * In vanilla HTML/JS, clicking with execute the attribute function, BUT now with keydown, hence this solution.
+     * A Solution to the Vanilla JS & Native HTML keydown:
+     *
+     * Handles inline onClick attributes set as strings in vanilla HTML
+     * (e.g. <nys-button onClick="doSomething()">).
+     *
+     * When onClick is set this way, it is a DOM attribute (not a property)
+     * so this.onClick remains null. Native clicks execute the attribute
+     * automatically, but keydown events do not, so we invoke it manually here.
      */
     private _handleAnyAttributeFunction;
     focus(options?: FocusOptions): void;

package/dist/packages/nys-checkbox/src/nys-checkboxgroup.d.ts

@@ -97,6 +97,7 @@ export declare class NysCheckboxgroup extends LitElement {
     private _handleCheckboxChange;
     private _handleChildError;
     private _handleChildErrorClear;
+    private _handleOtherInput;
     private _checkOtherInputs;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -81,6 +81,7 @@ export declare class NysRadiobutton extends LitElement {
     formResetUpdate(): void;
     private _handleResize;
     private _clearOtherState;
+    private _dispatchClearErrorEvent;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------

package/dist/packages/nys-radiobutton/src/nys-radiogroup.d.ts

@@ -104,5 +104,7 @@ export declare class NysRadiogroup extends LitElement {
     private _handleRadioButtonChange;
     private _handleInvalid;
     private _handleChildError;
+    private _handleChildErrorClear;
+    private _handleOtherInput;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-stepper/src/nys-step.d.ts

@@ -5,6 +5,41 @@ import { LitElement } from "lit";
  * Mark as `current` to indicate active progress point. Previous steps become clickable for navigation.
  * Set `href` for page-based navigation or listen to `nys-step-click` for SPA routing.
  *
+ * ## Step States
+ *
+ * Understanding the three step states is critical for proper stepper usage:
+ *
+ * - **`selected`** - Which step is currently being displayed/viewed. This controls which step's
+ *   content is shown. Defaults to `current` if not set. Cannot be set on a step after `current`.
+ *   Users can click previous steps to change `selected` without changing `current`.
+ *
+ * - **`current`** - The furthest step the user has reached. This is the progress boundary.
+ *   Update this as the user completes steps and advances. Steps after `current` are not navigable.
+ *   Only one step should have `current` at a time.
+ *
+ * - **`previous`** - Auto-applied by the stepper to all steps before `current`. Do not set manually.
+ *   Steps with `previous` are clickable and allow the user to navigate back.
+ *
+ * ## Common Patterns
+ *
+ * **Initial state:** Set `current` on the first step. `selected` will default to it.
+ * ```html
+ * <nys-step label="Step 1" current></nys-step>
+ * <nys-step label="Step 2"></nys-step>
+ * ```
+ *
+ * **User completed step 1, now on step 2:**
+ * ```html
+ * <nys-step label="Step 1"></nys-step>
+ * <nys-step label="Step 2" current></nys-step>
+ * ```
+ *
+ * **User went back to review step 1 (but progress is still at step 2):**
+ * ```html
+ * <nys-step label="Step 1" selected></nys-step>
+ * <nys-step label="Step 2" current></nys-step>
+ * ```
+ *
  * @summary Individual step for use within nys-stepper with navigation support.
  * @element nys-step
  *

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

@@ -5,6 +5,7 @@ import "./nys-step";
  *
  * Add `nys-step` elements as children. Mark one step as `current` to indicate progress; previous steps become
  * navigable. Compact view on mobile expands to show all steps. Use `actions` slot for navigation buttons.
+ * Do not place the stepper inside a form element.
  *
  * @summary Multi-step progress indicator with navigation and mobile-friendly compact view.
  * @element nys-stepper
@@ -20,6 +21,43 @@ import "./nys-step";
  *   <nys-step label="Review"></nys-step>
  * </nys-stepper>
  * ```
+ *
+ * @example Grid layout with sidebar placement
+ * Use NYSDS grid utilities to position the stepper as a sidebar alongside form content.
+ * **Layout requirements:**
+ * - Wrap in `nys-grid-container` > `nys-grid-row`
+ * - Use mobile-first classes: `nys-grid-col-12` (stacks on mobile) plus `nys-desktop:nys-grid-col-*`
+ * - Columns must total 12 (e.g., 3+9 or 4+8)
+ * - Recommended: stepper 3-4 cols, content 8-9 cols
+ * ```html
+ * <div class="nys-grid-container">
+ *   <div class="nys-grid-row">
+ *     <nys-stepper label="Application" class="nys-grid-col-12 nys-desktop:nys-grid-col-3">
+ *       <nys-step label="Personal Info"></nys-step>
+ *       <nys-step label="Contact" current></nys-step>
+ *       <nys-step label="Review"></nys-step>
+ *     </nys-stepper>
+ *     <main class="nys-grid-col-12 nys-desktop:nys-grid-col-9" id="main-content">
+ *       <!-- Form content for current step -->
+ *       <nys-textinput label="Email" required></nys-textinput>
+ *       <nys-textinput label="Phone"></nys-textinput>
+ *     </main>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @example Navigation buttons in actions slot
+ * Add Previous/Next buttons using the actions slot. Wrap buttons in a `<div>`.
+ * ```html
+ * <nys-stepper label="Application">
+ *   <nys-step label="Step 1"></nys-step>
+ *   <nys-step label="Step 2" current></nys-step>
+ *   <nys-step label="Step 3"></nys-step>
+ *   <div slot="actions">
+ *     <nys-button label="Save and Exit" variant="outline" size="sm" fullWidth></nys-button>
+ *   </div>
+ * </nys-stepper>
+ * ```
  */
 export declare class NysStepper extends LitElement {
     static styles: import("lit").CSSResult;

package/dist/packages/nys-video/src/index.d.ts

@@ -0,0 +1 @@
+export * from "./nys-video";

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

@@ -0,0 +1,71 @@
+import { LitElement } from "lit";
+declare global {
+    interface Window {
+        YT: any;
+        onYouTubeIframeAPIReady: () => void;
+    }
+}
+export declare class NysVideo extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** Full YouTube URL — required. Component will not render if invalid. */
+    id: string;
+    /** Title text for the thumbnail of the video */
+    titleText: string;
+    /** Full YouTube URL — required. Component will not render if invalid. */
+    videourl: string;
+    /**
+     * Largest size for the video player.
+     * If not set, size is determined automatically by viewport width.
+     */
+    size: "full" | "md" | "sm" | "";
+    loading: "lazy" | "eager";
+    /** Time in seconds where playback begins. **/
+    starttime: number;
+    /**
+     * Custom thumbnail image path.
+     * Falls back to YouTube's auto-generated thumbnail if not provided.
+     */
+    thumbnail: string | null;
+    /** Triggers autoplay when the iframe loads */
+    autoplay: boolean;
+    /** Prevents the video from being played */
+    disabled: boolean;
+    /** Tracks whether the user has clicked to load the player */
+    private _playerActive;
+    /** Screen reader announcement text */
+    private _announcement;
+    /** Tracks whether an ad is currently playing to suppress false "Video is playing" announcements */
+    private _adPlaying;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
+    private _isValidYouTubeUrl;
+    private _getVideoId;
+    private _getThumbnailUrl;
+    private _getEmbedUrl;
+    /**
+     * Because I need to know if Youtube ADs are playing, I need to call YT's API.
+     * Hence, the YT API setup below. The VO has 2 types of announcements:
+     * - "Advertisement is playing"
+     * - "Video is playing"
+     *
+     * YT IFrame Player API: https://developers.google.com/youtube/iframe_api_reference
+     */
+    private _announceVideoVO;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
+    private _handleThumbnailClick;
+    /**
+     * Render Helpers
+     * --------------------------------------------------------------------------
+     */
+    private _renderAnnouncer;
+    private _renderPlayIcon;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/packages/nys-video/src/nys-video.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index.d.ts

@@ -28,3 +28,4 @@ export * from "../packages/nys-unavheader/src/index";
 export * from "../packages/nys-globalheader/src/index";
 export * from "../packages/nys-globalfooter/src/index";
 export * from "../packages/nys-unavfooter/src/index";
+export * from "../packages/nys-video/src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.16.0-alpha3",
+  "version": "1.16.0-alpha5",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [
@@ -32,16 +32,17 @@
     "build": "tsc --emitDeclarationOnly && vite build",
     "build:umd": "cross-env BUILD_FORMAT=umd vite build",
     "tsc:packages": "tsc -b tsconfig.build.json",
-    "build:packages": "npm run tsc:packages && turbo run build --filter='./packages/*'",
+    "build:packages": "npm run tsc:packages && turbo run build --filter='./packages/*' --log-order=grouped",
     "build:root": "cross-env NODE_ENV=production npm run build && cross-env NODE_ENV=production npm run build:umd",
-    "build:all": "npm run clean:dist && npm run lint && npm run lit-analyze || true && cross-env NODE_ENV=production npm run build:packages && npm run build:root && npm run cem && npm run mcp-server:build",
+    "build:all": "npm run clean:dist && npm run lint && npm run lit-analyze || true && cross-env NODE_ENV=production npm run build:packages && npm run build:root && npm run cem && npm run build:mcp",
+    "build:mcp": "npm run build -w @nysds/mcp-server",
     "build:link": "npm run build:all && npm link && cd packages/styles && npm link",
     "lint": "eslint --cache --cache-location node_modules/.cache/eslint && stylelint **/*.scss || true",
     "lint:fix": "eslint --fix && stylelint **/*.scss --fix",
     "lit-analyze": "find ./packages/nys-*/ -name '*.ts' ! -name '*.figma.*' | xargs lit-analyzer {}",
     "release": "cross-env NODE_ENV=production npm run build:all && cross-env NODE_ENV=production npm run test && npm run cem && cross-env NODE_ENV=production npm publish --workspaces --access public && cross-env NODE_ENV=production npm publish --access public",
     "release:dry-run": "cross-env NODE_ENV=production npm run build:all && cross-env NODE_ENV=production npm run test && npm run cem && node src/scripts/publish-dry-run.js",
-    "release:alpha": "npm run build && npm run build:umd && npm publish --tag next",
+    "release:alpha": "cross-env NODE_ENV=production npm run build:all && cross-env NODE_ENV=production npm run test && npm run cem && cross-env NODE_ENV=production npm publish --workspaces --access public --tag next && cross-env NODE_ENV=production npm publish --access public --tag next",
     "release:zip": "npm run build:all && node src/scripts/create-release-zip.js",
     "test": "npx playwright install && wtr --node-resolve",
     "test:build": "npm run build:all && npm run test",
@@ -85,8 +86,8 @@
     "@web/test-runner": "^0.20.2",
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.1",
+    "cem-plugin-examples": "github:its-hcd/cem-plugin-examples",
     "cross-env": "^10.1.0",
-    "custom-element-jsx-integration": "^1.6.0",
     "custom-element-react-wrappers": "^1.7.3",
     "custom-element-vs-code-integration": "^1.5.0",
     "dotenv-cli": "^10.0.0",
@@ -98,6 +99,7 @@
     "lit": "^3.3.1",
     "lit-analyzer": "^2.0.3",
     "plop": "^4.0.4",
+    "prettier": "^3.8.1",
     "rollup-plugin-esbuild-minify": "^1.3.0",
     "rollup-plugin-minify-template-literals": "^1.1.7",
     "rollup-plugin-visualizer": "^6.0.5",

package/packages/react/NysVideo.d.ts

@@ -0,0 +1,77 @@
+import React from "react";
+import { NysVideo as NysVideoElement } from "../../dist/nysds.es.js";
+
+export type { NysVideoElement };
+
+export interface NysVideoProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Triggers autoplay when the iframe loads */
+  autoplay?: boolean;
+
+  /** Prevents the video from being played */
+  disabled?: boolean;
+
+  /** Full YouTube URL — required. Component will not render if invalid. */
+  id?: NysVideoElement["id"];
+
+  /** Title text for the thumbnail of the video */
+  titleText?: NysVideoElement["titleText"];
+
+  /** Full YouTube URL — required. Component will not render if invalid. */
+  videourl?: NysVideoElement["videourl"];
+
+  /** Largest size for the video player.
+If not set, size is determined automatically by viewport width. */
+  size?: NysVideoElement["size"];
+
+  /** undefined */
+  loading?: NysVideoElement["loading"];
+
+  /** Time in seconds where playback begins. * */
+  starttime?: NysVideoElement["starttime"];
+
+  /** Custom thumbnail image path.
+Falls back to YouTube's auto-generated thumbnail if not provided. */
+  thumbnail?: NysVideoElement["thumbnail"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: any;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+}
+
+/**
+ *
+ * ---
+ *
+ */
+export const NysVideo: React.ForwardRefExoticComponent<NysVideoProps>;

package/packages/react/NysVideo.js

@@ -0,0 +1,40 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysVideo = forwardRef((props, forwardedRef) => {
+  const {
+    autoplay,
+    disabled,
+    id,
+    titleText,
+    videourl,
+    size,
+    loading,
+    starttime,
+    thumbnail,
+    ...filteredProps
+  } = props;
+
+  return React.createElement(
+    "nys-video",
+    {
+      ...filteredProps,
+      id: props.id,
+      titleText: props.titleText,
+      videourl: props.videourl,
+      size: props.size,
+      loading: props.loading,
+      starttime: props.starttime,
+      thumbnail: props.thumbnail,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      autoplay: props.autoplay ? true : undefined,
+      disabled: props.disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/index.d.ts

@@ -35,3 +35,4 @@ export * from "./NysToggle.js";
 export * from "./NysTooltip.js";
 export * from "./NysUnavFooter.js";
 export * from "./NysUnavHeader.js";
+export * from "./NysVideo.js";

package/packages/react/index.js

@@ -35,3 +35,4 @@ export * from "./NysToggle.js";
 export * from "./NysTooltip.js";
 export * from "./NysUnavFooter.js";
 export * from "./NysUnavHeader.js";
+export * from "./NysVideo.js";