@nysds/components 1.19.2 → 1.20.0-alpha1

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

@@ -162,6 +162,7 @@ export declare class NysButton extends LitElement {
     private _internals;
     private _hasPrefixSlot;
     private _hasSuffixSlot;
+    private _hasCircleSlot;
     /**
      * Lifecycle methods
      * --------------------------------------------------------------------------
@@ -176,6 +177,7 @@ export declare class NysButton extends LitElement {
     private _generateUniqueId;
     private _onPrefixSlotChange;
     private _onSuffixSlotChange;
+    private _onCircleSlotChange;
     private _manageFormAction;
     /**
      * Event Handlers

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

@@ -0,0 +1,2 @@
+export * from "./nys-verticalnav";
+export * from "./nys-verticalnavgroup";

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

@@ -0,0 +1,188 @@
+import { LitElement } from "lit";
+import "./nys-verticalnavgroup";
+type HeaderLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+/**
+ * Vertical navigation component with responsive desktop/mobile behavior.
+ *
+ * Renders as a side vertical navigation with heading and slotted link list on desktop. On tablet/mobile
+ * it collapses into a `<nys-accordion>`. The default slot accepts a
+ * `<ul>` of links; subheader `<li>` items (containing `<h2>`-`<h6>`). Use the `header` slot to replace the
+ * auto-generated heading, and the `footer` slot for metadata or extra actions
+ * below the link list.
+ *
+ * @summary Responsive vertical navigation — nav on desktop, accordion on mobile.
+ * @element nys-verticalnav
+ *
+ * @example Basic usage
+ * ```html
+ * <nys-verticalnav header="Freshwater Fishing" headerLevel="h2">
+ *   <ul>
+ *     <li><a href="/">Home</a></li>
+ *     <li><a href="/services">Services</a></li>
+ *     <li>
+ *       <h3>Freshwater Fishing Regulations</h3>
+ *       <ul>
+ *         <li><a href="">Places to Fish</a></li>
+ *         <li><a href="">Learn to Fish</a></li>
+ *         <li><a href="">Ice Fishing</a></li>
+ *       </ul>
+ *     </li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example With custom header slot
+ * ```html
+ * <nys-verticalnav header="Freshwater Fishing" headerLevel="h2">
+ *   <div slot="header">
+ *     <h2>Freshwater Fishing</h2>
+ *     <p>2026 Season Open</p>
+ *   </div>
+ *   <ul>
+ *     <li><a href="/">Home</a></li>
+ *     <li><a href="/services">Services</a></li>
+ *     <li>
+ *       <h3>Freshwater Fishing Regulations</h3>
+ *       <ul>
+ *         <li><a href="">Places to Fish</a></li>
+ *         <li><a href="">Learn to Fish</a></li>
+ *         <li><a href="">Ice Fishing</a></li>
+ *       </ul>
+ *     </li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example With footer slot
+ * ```html
+ * <nys-verticalnav header="Freshwater Fishing" headerLevel="h2">
+ *   <ul>
+ *     <li><a href="/">Home</a></li>
+ *     <li><a href="/services">Services</a></li>
+ *     <li>
+ *       <h3>Freshwater Fishing Regulations</h3>
+ *       <ul>
+ *         <li><a href="">Places to Fish</a></li>
+ *         <li><a href="">Learn to Fish</a></li>
+ *         <li><a href="">Ice Fishing</a></li>
+ *       </ul>
+ *     </li>
+ *   </ul>
+ *   <div slot="footer">
+ *     <nys-divider></nys-divider>
+ *     <p>Regulations last updated: January 2026</p>
+ *     <a href="/contact-dec">Contact the DEC for fishing inquiries</a>
+ *   </div>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example With dropdown group
+ * ```html
+ * <nys-verticalnav header="NYS Design System" headerLevel="h2">
+ *   <ul>
+ *     <li><a href="/">Foundations</a></li>
+ *     <li><a href="/components">Components</a></li>
+ *     <li>
+ *       <nys-verticalnavgroup label="Accessibility">
+ *         <ul>
+ *           <li><a href="">WCAG Guidelines</a></li>
+ *           <li><a href="">Screen Readers</a></li>
+ *           <li><a href="">Color Contrast</a></li>
+ *         </ul>
+ *       </nys-verticalnavgroup>
+ *     </li>
+ *     <li>
+ *       <h3>Resources</h3>
+ *       <ul>
+ *         <li><a href="">Design Tokens</a></li>
+ *         <li><a href="">Utilities</a></li>
+ *       </ul>
+ *     </li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example With active link (aria-current="page")
+ * ```html
+ * <nys-verticalnav header="NYS Design System" headerLevel="h2">
+ *   <ul>
+ *     <li><a href="/">Foundations</a></li>
+ *     <li><a href="/components">Components</a></li>
+ *     <li>
+ *       <nys-verticalnavgroup label="Accessibility">
+ *         <ul>
+ *           <li><a aria-current="page" href="">WCAG Guidelines</a></li>
+ *           <li><a href="">Screen Readers</a></li>
+ *           <li><a href="">Color Contrast</a></li>
+ *         </ul>
+ *       </nys-verticalnavgroup>
+ *     </li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example With disabled links and group
+ * ```html
+ * <nys-verticalnav header="NYS Design System" headerLevel="h2">
+ *   <ul>
+ *     <li><a href="/">Foundations</a></li>
+ *     <li>
+ *       <nys-verticalnavgroup disabled label="Accessibility">
+ *         <ul>
+ *           <li><a aria-disabled="true">WCAG Guidelines</a></li>
+ *           <li><a href="">Screen Readers</a></li>
+ *         </ul>
+ *       </nys-verticalnavgroup>
+ *     </li>
+ *     <li>
+ *       <h3>Resources</h3>
+ *       <ul>
+ *         <li><a aria-disabled="true">Design Tokens</a></li>
+ *         <li><a href="">Utilities</a></li>
+ *       </ul>
+ *     </li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example Hidden header (aria-label used instead)
+ * ```html
+ * <nys-verticalnav header="Section nav" hideHeader>
+ *   <ul>
+ *     <li><a href="/home">Home</a></li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ */
+export declare class NysVerticalnav extends LitElement {
+    static styles: import("lit").CSSResult;
+    id: string;
+    header: string;
+    hideHeader: boolean;
+    headerLevel: HeaderLevel;
+    private _isMobile;
+    private _mediaQuery;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
+    private _handleResize;
+    private _applyActiveState;
+    /**
+     * Helper Render Functions
+     * --------------------------------------------------------------------------
+     */
+    private _renderHeader;
+    private renderContentDesktop;
+    private renderContentMobile;
+    render(): import("lit-html").TemplateResult<1>;
+}
+export {};

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

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

package/dist/packages/nys-verticalnav/src/nys-verticalnavgroup.d.ts

@@ -0,0 +1,74 @@
+import { LitElement } from "lit";
+/**
+ * Collapsible dropdown group for use inside `<nys-verticalnav>`.
+ *
+ * Renders a toggle button and an expandable panel for a nested `<ul>` of links.
+ * Designed to be placed as a direct child of a `<li>` inside the vertical nav's
+ * default slot. Use `expanded` to open it by default, and `disabled` to prevent
+ * interaction. Set `aria-current="page"` on an `<a>` inside to automatically
+ * expand the group and apply the active state.
+ *
+ * @summary Collapsible link group for use within `<nys-verticalnav>`.
+ * @element nys-verticalnavgroup
+ *
+ * @example Basic usage
+ * ```html
+ * <nys-verticalnav header="NYS Design System">
+ *   <ul>
+ *     <li><a href="/foundations">Foundations</a></li>
+ *     <li>
+ *       <nys-verticalnavgroup label="Accessibility">
+ *         <ul>
+ *           <li><a href="">WCAG Guidelines</a></li>
+ *           <li><a href="">Screen Readers</a></li>
+ *           <li><a href="">Color Contrast</a></li>
+ *         </ul>
+ *       </nys-verticalnavgroup>
+ *     </li>
+ *   </ul>
+ * </nys-verticalnav>
+ * ```
+ *
+ * @example With active link — group auto-expands
+ * ```html
+ * <nys-verticalnavgroup label="Accessibility">
+ *   <ul>
+ *     <li><a aria-current="page" href="">WCAG Guidelines</a></li>
+ *     <li><a href="">Screen Readers</a></li>
+ *     <li><a href="">Color Contrast</a></li>
+ *   </ul>
+ * </nys-verticalnavgroup>
+ * ```
+ *
+ * @example Expanded by default
+ * ```html
+ * <nys-verticalnavgroup label="Resources" expanded>
+ *   <ul>
+ *     <li><a href="">Design Tokens</a></li>
+ *     <li><a href="">Utilities</a></li>
+ *   </ul>
+ * </nys-verticalnavgroup>
+ * ```
+ *
+ * @example Disabled group with disabled links
+ * ```html
+ * <nys-verticalnavgroup disabled label="Accessibility">
+ *   <ul>
+ *     <li><a aria-disabled="true">WCAG Guidelines</a></li>
+ *     <li><a href="">Screen Readers</a></li>
+ *     <li><a href="">Color Contrast</a></li>
+ *   </ul>
+ * </nys-verticalnavgroup>
+ * ```
+ */
+export declare class NysVerticalnavGroup extends LitElement {
+    static styles: import("lit").CSSResult;
+    id: string;
+    label: string;
+    expanded: boolean;
+    disabled: boolean;
+    active: boolean;
+    connectedCallback(): void;
+    private _toggle;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/src/index.d.ts

@@ -30,4 +30,5 @@ 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-verticalnav/src/index";
 export * from "../packages/nys-video/src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.19.2",
+  "version": "1.20.0-alpha1",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [

package/packages/react/NysVerticalnav.d.ts

@@ -0,0 +1,60 @@
+import React from "react";
+import { NysVerticalnav as NysVerticalnavElement } from "../../dist/nysds.es.js";
+
+export type { NysVerticalnavElement };
+
+export interface NysVerticalnavProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  hideHeader?: boolean;
+
+  /** undefined */
+  id?: NysVerticalnavElement["id"];
+
+  /** undefined */
+  header?: NysVerticalnavElement["header"];
+
+  /** undefined */
+  headerLevel?: NysVerticalnavElement["headerLevel"];
+
+  /** 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;
+}
+
+/**
+ * Responsive vertical navigation — nav on desktop, accordion on mobile.
+ * ---
+ *
+ */
+export const NysVerticalnav: React.ForwardRefExoticComponent<NysVerticalnavProps>;

package/packages/react/NysVerticalnav.js

@@ -0,0 +1,24 @@
+import React, { forwardRef } from "react";
+import "../../dist/nysds.es.js";
+
+export const NysVerticalnav = forwardRef((props, forwardedRef) => {
+  const { hideHeader, id, header, headerLevel, ...filteredProps } = props;
+
+  return React.createElement(
+    "nys-verticalnav",
+    {
+      ...filteredProps,
+      id: props.id,
+      header: props.header,
+      headerLevel: props.headerLevel,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      hideHeader: props.hideHeader ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/NysVerticalnavGroup.d.ts

@@ -0,0 +1,72 @@
+import React from "react";
+import {
+  NysVerticalnavGroup as NysVerticalnavGroupElement,
+  CustomEvent,
+} from "../../dist/nysds.es.js";
+
+export type { NysVerticalnavGroupElement, CustomEvent };
+
+export interface NysVerticalnavGroupProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  expanded?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  active?: boolean;
+
+  /** undefined */
+  id?: NysVerticalnavGroupElement["id"];
+
+  /** undefined */
+  label?: NysVerticalnavGroupElement["label"];
+
+  /** 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;
+
+  /** undefined */
+  onNysChildResize?: (event: CustomEvent) => void;
+}
+
+/**
+ * Collapsible link group for use within `<nys-verticalnav>`.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **nys-child-resize**
+ */
+export const NysVerticalnavGroup: React.ForwardRefExoticComponent<NysVerticalnavGroupProps>;

package/packages/react/NysVerticalnavGroup.js

@@ -0,0 +1,38 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
+
+export const NysVerticalnavGroup = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const { expanded, disabled, active, id, label, ...filteredProps } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-child-resize", props.onNysChildResize);
+
+  return React.createElement(
+    "nys-verticalnavgroup",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      id: props.id,
+      label: props.label,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      expanded: props.expanded ? true : undefined,
+      disabled: props.disabled ? true : undefined,
+      active: props.active ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/packages/react/index.d.ts

@@ -39,4 +39,6 @@ export * from "./NysToggle.js";
 export * from "./NysTooltip.js";
 export * from "./NysUnavFooter.js";
 export * from "./NysUnavHeader.js";
+export * from "./NysVerticalnav.js";
+export * from "./NysVerticalnavGroup.js";
 export * from "./NysVideo.js";

package/packages/react/index.js

@@ -39,4 +39,6 @@ export * from "./NysToggle.js";
 export * from "./NysTooltip.js";
 export * from "./NysUnavFooter.js";
 export * from "./NysUnavHeader.js";
+export * from "./NysVerticalnav.js";
+export * from "./NysVerticalnavGroup.js";
 export * from "./NysVideo.js";

package/packages/react/nysds-jsx.d.ts

@@ -1021,6 +1021,33 @@ export type NysUnavHeaderProps = {
   languages?: Language[];
 };
 
+export type NysVerticalnavProps = {
+  /**  */
+  id?: string;
+  /**  */
+  header?: string;
+  /**  */
+  hideHeader?: boolean;
+  /**  */
+  headerLevel?: HeaderLevel;
+};
+
+export type NysVerticalnavGroupProps = {
+  /**  */
+  id?: string;
+  /**  */
+  label?: string;
+  /**  */
+  expanded?: boolean;
+  /**  */
+  disabled?: boolean;
+  /**  */
+  active?: boolean;
+
+  /**  */
+  "onnys-child-resize"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
 export type NysVideoProps = {
   /** Full YouTube URL — required. Component will not render if invalid. */
   id?: string;
@@ -1602,6 +1629,23 @@ export type CustomElements = {
    */
   "nys-unavheader": Partial<NysUnavHeaderProps & BaseProps & BaseEvents>;
 
+  /**
+   * Responsive vertical navigation — nav on desktop, accordion on mobile.
+   * ---
+   *
+   */
+  "nys-verticalnav": Partial<NysVerticalnavProps & BaseProps & BaseEvents>;
+
+  /**
+   * Collapsible link group for use within `<nys-verticalnav>`.
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **nys-child-resize**
+   */
+  "nys-verticalnavgroup": Partial<NysVerticalnavGroupProps & BaseProps & BaseEvents>;
+
   /**
    * YouTube video player with thumbnail preview and accessibility announcements.
    * ---