@sebgroup/green-core 3.1.0 → 3.5.0

package/bin/mcp-server/handlers.js

@@ -10,12 +10,14 @@ import {
   loadComponentsIndex,
   loadGlobalIndex,
   loadIconsIndex,
+  loadTokensIndex,
   parseResourceUri,
   readMcpFile
 } from "./utils.js";
 import {
   validateGetComponentDocsInput,
   validateGetGuideInput,
+  validateGetTokensInput,
   validateListGuidesInput,
   validateSearchComponentsInput
 } from "./validation.js";
@@ -346,10 +348,118 @@ async function handleResolveUri(uri) {
     content: [{ type: "text", text: content }]
   };
 }
+function isColorCategory(data) {
+  return "subcategories" in data;
+}
+function stripStyleInfo(cat) {
+  const { styleExpressionProperties, styleExpressionUsage, ...rest } = cat;
+  return rest;
+}
+function stripColorSubStyleInfo(sub) {
+  const { styleExpressionProperties, styleExpressionUsage, ...rest } = sub;
+  return rest;
+}
+async function handleGetTokens(input) {
+  const validatedInput = validateGetTokensInput(input);
+  const {
+    category = "all",
+    colorSubcategory = "all",
+    includeStyleExpressionInfo = true
+  } = validatedInput;
+  const tokensIndex = await loadTokensIndex();
+  if (!tokensIndex) {
+    throw new NotFoundError(
+      "Tokens data not available. The MCP data may need to be regenerated.",
+      "index",
+      "tokens"
+    );
+  }
+  let result;
+  if (category === "all") {
+    const categories = {};
+    for (const [key, data] of Object.entries(tokensIndex.categories)) {
+      if (isColorCategory(data)) {
+        if (colorSubcategory === "all") {
+          categories[key] = includeStyleExpressionInfo ? data : {
+            description: data.description,
+            subcategories: Object.fromEntries(
+              Object.entries(data.subcategories).map(([k, v]) => [
+                k,
+                stripColorSubStyleInfo(v)
+              ])
+            )
+          };
+        } else {
+          const sub = data.subcategories[colorSubcategory];
+          if (sub) {
+            categories[key] = {
+              description: data.description,
+              subcategories: {
+                [colorSubcategory]: includeStyleExpressionInfo ? sub : stripColorSubStyleInfo(sub)
+              }
+            };
+          }
+        }
+      } else {
+        categories[key] = includeStyleExpressionInfo ? data : stripStyleInfo(data);
+      }
+    }
+    result = { generatedAt: tokensIndex.generatedAt, categories };
+  } else if (category === "color") {
+    const colorData = tokensIndex.categories.color;
+    if (!colorData || !isColorCategory(colorData)) {
+      throw new NotFoundError(
+        "Color token data not available",
+        "category",
+        "color"
+      );
+    }
+    if (colorSubcategory === "all") {
+      result = includeStyleExpressionInfo ? colorData : {
+        description: colorData.description,
+        subcategories: Object.fromEntries(
+          Object.entries(colorData.subcategories).map(([k, v]) => [
+            k,
+            stripColorSubStyleInfo(v)
+          ])
+        )
+      };
+    } else {
+      const sub = colorData.subcategories[colorSubcategory];
+      if (!sub) {
+        throw new NotFoundError(
+          `Color subcategory not found: ${colorSubcategory}`,
+          "colorSubcategory",
+          colorSubcategory
+        );
+      }
+      result = includeStyleExpressionInfo ? sub : stripColorSubStyleInfo(sub);
+    }
+  } else {
+    const data = tokensIndex.categories[category];
+    if (!data) {
+      throw new NotFoundError(
+        `Token category not found: ${category}`,
+        "category",
+        category
+      );
+    }
+    result = includeStyleExpressionInfo ? data : stripStyleInfo(data);
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
 export {
   handleGetComponentDocs,
   handleGetGuide,
   handleGetInstructions,
+  handleGetTokens,
   handleListGuides,
   handleResolveUri,
   handleSearchComponents

package/bin/mcp-server/resources.js

@@ -10,6 +10,7 @@ import {
   loadComponentsIndex,
   loadGlobalIndex,
   loadIconsIndex,
+  loadTokensIndex,
   parseResourceUri,
   readMcpFile
 } from "./utils.js";
@@ -82,6 +83,31 @@ function setupResourceHandlers(server) {
             mimeType: "text/markdown"
           });
         }
+        if (globalIndex.tokens) {
+          const tokenCategories = [
+            "space",
+            "radius",
+            "color",
+            "typography",
+            "viewport",
+            "shadow",
+            "motion"
+          ];
+          resources.push({
+            uri: "green://tokens",
+            name: "Design Tokens (all)",
+            description: "All design tokens with values and style expression usage information",
+            mimeType: "application/json"
+          });
+          for (const cat of tokenCategories) {
+            resources.push({
+              uri: `green://tokens/${cat}`,
+              name: `Design Tokens (${cat})`,
+              description: `${cat} design tokens with values and style expression usage`,
+              mimeType: "application/json"
+            });
+          }
+        }
       }
       return { resources };
     } catch (error) {
@@ -111,6 +137,45 @@ function setupResourceHandlers(server) {
           ]
         };
       }
+      if (uri === "green://tokens" || uri.startsWith("green://tokens/")) {
+        const tokensIndex = await loadTokensIndex();
+        if (!tokensIndex) {
+          throw new NotFoundError(
+            "Tokens data not available",
+            "file",
+            PATHS.TOKENS_INDEX
+          );
+        }
+        if (uri === "green://tokens") {
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(tokensIndex, null, 2)
+              }
+            ]
+          };
+        }
+        const categoryName = uri.replace("green://tokens/", "");
+        const categoryData = tokensIndex.categories[categoryName];
+        if (!categoryData) {
+          throw new NotFoundError(
+            `Token category not found: ${categoryName}`,
+            "category",
+            categoryName
+          );
+        }
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(categoryData, null, 2)
+            }
+          ]
+        };
+      }
       const parsed = parseResourceUri(uri);
       if (!parsed) {
         throw new NotFoundError(`Invalid resource URI format`, "uri", uri);

package/bin/mcp-server/tools.js

@@ -9,6 +9,7 @@ import {
   handleGetComponentDocs,
   handleGetGuide,
   handleGetInstructions,
+  handleGetTokens,
   handleListGuides,
   handleSearchComponents
 } from "./handlers.js";
@@ -137,6 +138,42 @@ function setupToolHandlers(server) {
             properties: {},
             required: []
           }
+        },
+        {
+          name: "get_tokens",
+          description: 'Get available design tokens (spacing, colors, typography, radius, etc.) with their values and style expression usage. Tokens are the building blocks for styling \u2014 use SHORT token names (e.g. "m", "positive-01", "heading-m") in style expression properties on layout components. The tool explains how each token category maps to component properties. Returns CSS variable names for direct CSS usage.',
+          inputSchema: {
+            type: "object",
+            properties: {
+              category: {
+                type: "string",
+                enum: [
+                  "space",
+                  "radius",
+                  "color",
+                  "typography",
+                  "viewport",
+                  "shadow",
+                  "motion",
+                  "all"
+                ],
+                description: "Filter by token category. Default: 'all'. Use 'space' for padding/margin/gap tokens, 'color' for background/content/border colors, 'typography' for font sizes and weights.",
+                default: "all"
+              },
+              colorSubcategory: {
+                type: "string",
+                enum: ["background", "border", "content", "state", "all"],
+                description: "When category is 'color' or 'all', filter to a specific color context. Default: 'all'",
+                default: "all"
+              },
+              includeStyleExpressionInfo: {
+                type: "boolean",
+                description: "Include information about which style expression properties use these tokens and how short names are inferred. Default: true",
+                default: true
+              }
+            },
+            required: []
+          }
         }
       ]
     };
@@ -155,6 +192,8 @@ function setupToolHandlers(server) {
           return await handleGetGuide(args);
         case "get_instructions":
           return await handleGetInstructions();
+        case "get_tokens":
+          return await handleGetTokens(args);
         default:
           throw new Error(`Unknown tool: ${name}`);
       }

package/bin/mcp-server/types.d.ts

@@ -62,6 +62,7 @@ export interface GlobalIndex {
     instructions?: string;
     components: string;
     icons: string;
+    tokens?: string;
     guides: GuideEntry[];
 }
 /**
@@ -114,3 +115,79 @@ export interface ListGuidesInput {
 export interface GetGuideInput {
     name: string;
 }
+/**
+ * Token category types
+ */
+export type TokenCategory = 'space' | 'radius' | 'color' | 'typography' | 'viewport' | 'shadow' | 'motion' | 'all';
+/**
+ * Color subcategory types
+ */
+export type ColorSubcategory = 'background' | 'border' | 'content' | 'state' | 'all';
+/**
+ * Token entry from tokens.json
+ */
+export interface TokenEntry {
+    name: string;
+    cssVariable: string;
+    value?: string;
+    description?: string;
+    pairings?: string[];
+    fontSize?: string;
+    lineHeight?: string;
+    fontWeight?: string;
+}
+/**
+ * Typography meta information
+ */
+export interface TypographyMeta {
+    [role: string]: {
+        tone: string;
+        description: string;
+    };
+}
+/**
+ * Token category data (non-color)
+ */
+export interface TokenCategoryData {
+    description: string;
+    cssVariablePrefix: string;
+    styleExpressionProperties: string[];
+    styleExpressionUsage: string;
+    tokens: TokenEntry[];
+    meta?: TypographyMeta;
+}
+/**
+ * Color subcategory data
+ */
+export interface ColorSubcategoryData {
+    description: string;
+    cssVariablePrefix: string;
+    styleExpressionProperties: string[];
+    styleExpressionUsage: string;
+    levels?: Record<string, {
+        tokens: TokenEntry[];
+    }>;
+    tokens?: TokenEntry[];
+}
+/**
+ * Color category data
+ */
+export interface ColorCategoryData {
+    description: string;
+    subcategories: Record<string, ColorSubcategoryData>;
+}
+/**
+ * Tokens index structure
+ */
+export interface TokensIndex {
+    generatedAt: string;
+    categories: Record<string, TokenCategoryData | ColorCategoryData>;
+}
+/**
+ * Tool input for get_tokens
+ */
+export interface GetTokensInput {
+    category?: TokenCategory;
+    colorSubcategory?: ColorSubcategory;
+    includeStyleExpressionInfo?: boolean;
+}

package/bin/mcp-server/utils.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentEntry, ComponentsIndex, GlobalIndex, IconEntry, IconsIndex } from './types.js';
+import type { ComponentEntry, ComponentsIndex, GlobalIndex, IconEntry, IconsIndex, TokensIndex } from './types.js';
 /**
  * Resolve the path to the MCP data directory
  * When compiled: Server is at dist/libs/core/src/bin/mcp-server/
@@ -26,6 +26,11 @@ export declare function loadIconsIndex(): Promise<IconsIndex | null>;
  * @returns Global index or null if failed
  */
 export declare function loadGlobalIndex(): Promise<GlobalIndex | null>;
+/**
+ * Load the tokens index
+ * @returns Tokens index or null if failed
+ */
+export declare function loadTokensIndex(): Promise<TokensIndex | null>;
 /**
  * Normalize component name for matching
  * Handles both 'gds-button' and 'button' formats
@@ -70,12 +75,6 @@ export declare function findIcon(name: string, icons: IconEntry[]): IconEntry |
  * readMcpFile('guides/angular.md')
  */
 export declare function readMcpFile(relativePath: string): Promise<string | null>;
-/**
- * Check if a file exists in the MCP data directory
- * @param relativePath - Path relative to MCP data directory
- * @returns True if file exists, false otherwise
- */
-export declare function fileExists(relativePath: string): Promise<boolean>;
 /**
  * Build a resource URI for a component/icon documentation file
  * @param category - Resource category

package/bin/mcp-server/utils.js

@@ -67,6 +67,17 @@ async function loadGlobalIndex() {
     return null;
   }
 }
+async function loadTokensIndex() {
+  try {
+    const dataPath = getMcpDataPath();
+    return await loadJsonFile(
+      path.join(dataPath, PATHS.TOKENS_INDEX)
+    );
+  } catch (error) {
+    logError(error, "loadTokensIndex");
+    return null;
+  }
+}
 function normalizeComponentName(name) {
   const lower = name.toLowerCase().trim();
   if (lower.startsWith("gds-")) {
@@ -117,16 +128,6 @@ async function readMcpFile(relativePath) {
     return null;
   }
 }
-async function fileExists(relativePath) {
-  try {
-    const dataPath = getMcpDataPath();
-    const fullPath = path.join(dataPath, relativePath);
-    await fs.access(fullPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
 function buildResourceUri(category, name, docType) {
   if (docType) {
     return `green://${category}/${name}/${docType}`;
@@ -142,7 +143,6 @@ function parseResourceUri(uri) {
 }
 export {
   buildResourceUri,
-  fileExists,
   findComponent,
   findIcon,
   getMcpDataPath,
@@ -150,6 +150,7 @@ export {
   loadComponentsIndex,
   loadGlobalIndex,
   loadIconsIndex,
+  loadTokensIndex,
   normalizeComponentName,
   parseResourceUri,
   readMcpFile

package/bin/mcp-server/validation.d.ts

@@ -1,7 +1,7 @@
 /**
  * Input validation for MCP server tools
  */
-import type { Category, Framework, GetComponentDocsInput, GetGuideInput, GuideCategory, ListGuidesInput, SearchComponentsInput } from './types.js';
+import type { Category, Framework, GetComponentDocsInput, GetGuideInput, GetTokensInput, GuideCategory, ListGuidesInput, SearchComponentsInput } from './types.js';
 /**
  * Validate framework parameter
  * @param framework - Framework value to validate
@@ -89,3 +89,10 @@ export declare function validateListGuidesInput(input: unknown): ListGuidesInput
  * @throws ValidationError if validation fails
  */
 export declare function validateGetGuideInput(input: unknown): GetGuideInput;
+/**
+ * Validate GetTokensInput
+ * @param input - Input to validate
+ * @returns Validated input
+ * @throws ValidationError if validation fails
+ */
+export declare function validateGetTokensInput(input: unknown): GetTokensInput;

package/bin/mcp-server/validation.js

@@ -1,5 +1,11 @@
 import "../../chunks/chunk.CAV4X6PU.js";
-import { CATEGORIES, FRAMEWORKS, GUIDE_CATEGORIES } from "./constants.js";
+import {
+  CATEGORIES,
+  COLOR_SUBCATEGORIES,
+  FRAMEWORKS,
+  GUIDE_CATEGORIES,
+  TOKEN_CATEGORIES
+} from "./constants.js";
 import { ValidationError } from "./errors.js";
 function validateEnum(value, allowed, fieldName) {
   if (typeof value !== "string") {
@@ -185,6 +191,35 @@ function validateGetGuideInput(input) {
     name: sanitized
   };
 }
+function validateGetTokensInput(input) {
+  if (!input || typeof input !== "object") {
+    throw new ValidationError("Invalid input: must be an object", "input");
+  }
+  const obj = input;
+  const result = {};
+  if (obj.category !== void 0) {
+    result.category = validateEnum(
+      obj.category,
+      TOKEN_CATEGORIES,
+      "category"
+    );
+  }
+  if (obj.colorSubcategory !== void 0) {
+    result.colorSubcategory = validateEnum(
+      obj.colorSubcategory,
+      COLOR_SUBCATEGORIES,
+      "colorSubcategory"
+    );
+  }
+  if (obj.includeStyleExpressionInfo !== void 0) {
+    result.includeStyleExpressionInfo = validateBoolean(
+      obj.includeStyleExpressionInfo,
+      "includeStyleExpressionInfo",
+      true
+    );
+  }
+  return result;
+}
 export {
   sanitizeComponentName,
   validateBoolean,
@@ -192,6 +227,7 @@ export {
   validateFramework,
   validateGetComponentDocsInput,
   validateGetGuideInput,
+  validateGetTokensInput,
   validateGuideCategory,
   validateListGuidesInput,
   validateNumber,

package/components/button/button.component.js

@@ -27,6 +27,7 @@ import {
 import { GdsFormControlElement } from "../form/form-control.js";
 import ButtonStyles from "./button.styles.js";
 const ariaForwards = ["aria-label", "aria-haspopup", "aria-expanded"];
+const attributeForwards = [...ariaForwards, "gds-tabindex"];
 const html = stripWhitespace(customElementHtml);
 class Button extends GdsFormControlElement {
   constructor() {
@@ -116,7 +117,7 @@ class Button extends GdsFormControlElement {
         @click="${__privateGet(this, _handleClick)}"
         @keydown="${__privateGet(this, _handleKeyDown)}"
         ${forwardAttributes(
-      (attr) => attr.name.startsWith("gds-aria") || attr.name === "gds-role" || ariaForwards.includes(attr.name)
+      (attr) => attr.name.startsWith("gds-aria") || attr.name === "gds-role" || attributeForwards.includes(attr.name)
     )}
       >
         <slot name="lead"></slot>

package/components/context-menu/context-menu.component.d.ts

@@ -17,7 +17,7 @@ declare const GdsContextMenu_base: (new (...args: any[]) => import("../../utils/
  */
 export declare class GdsContextMenu extends GdsContextMenu_base {
     #private;
-    static styles: import("lit").CSSResult[][];
+    static styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     static shadowRootOptions: ShadowRootInit;
     /**
      * Whether the context menu popover is open.
@@ -35,6 +35,10 @@ export declare class GdsContextMenu extends GdsContextMenu_base {
      * The label for the popover and menu. Should describe the context of the menu.
      */
     label: string;
+    /**
+     * Maximum height of the menu list.
+     */
+    maxHeight: number;
     /**
      * The placement of the popover relative to the trigger.
      */

package/components/context-menu/context-menu.component.js

@@ -5,8 +5,9 @@ import {
   __privateMethod,
   __privateSet
 } from "../../chunks/chunk.CAV4X6PU.js";
-var _elTriggerBtn, _setupButton, _handleTriggerSlotChange, _renderPopover, _handleItemClick, handleItemClick_fn;
+var _elTriggerBtn, _setupButton, _handleTriggerSlotChange, _renderPopover, _handleItemClick, handleItemClick_fn, _calcMaxHeight;
 import { localized, msg } from "@lit/localize";
+import { css } from "lit";
 import { property, query } from "lit/decorators.js";
 import { when } from "lit/directives/when.js";
 import { GdsElement } from "../../gds-element.js";
@@ -41,6 +42,7 @@ let GdsContextMenu = class extends withMarginProps(
     this.buttonLabel = msg("Open context menu");
     this.showLabel = false;
     this.label = "";
+    this.maxHeight = 500;
     this.placement = "bottom-start";
     __privateAdd(this, _elTriggerBtn, void 0);
     __privateAdd(this, _setupButton, () => {
@@ -80,9 +82,11 @@ let GdsContextMenu = class extends withMarginProps(
       .label=${this.label}
       .placement=${this.placement}
       .popupRole=${"menu"}
+      .calcMaxHeight=${__privateGet(this, _calcMaxHeight)}
       @gds-ui-state=${(e) => this.open = e.detail.open}
     >
       <gds-menu
+        class="menu"
         aria-label=${this.label ?? this.buttonLabel}
         @gds-menu-item-click=${__privateMethod(this, _handleItemClick, handleItemClick_fn)}
       >
@@ -90,6 +94,10 @@ let GdsContextMenu = class extends withMarginProps(
       </gds-menu>
     </gds-popover>`;
     });
+    __privateAdd(this, _calcMaxHeight, () => {
+      const height = Math.min(window.innerHeight, this.maxHeight);
+      return `${height - 16}px`;
+    });
   }
   connectedCallback() {
     super.connectedCallback();
@@ -134,7 +142,15 @@ _handleItemClick = new WeakSet();
 handleItemClick_fn = function() {
   this.open = false;
 };
-GdsContextMenu.styles = [tokens];
+_calcMaxHeight = new WeakMap();
+GdsContextMenu.styles = [
+  tokens,
+  css`
+      .menu {
+        overflow: auto;
+      }
+    `
+];
 GdsContextMenu.shadowRootOptions = {
   mode: "open",
   delegatesFocus: true
@@ -156,6 +172,9 @@ __decorateClass([
 __decorateClass([
   property()
 ], GdsContextMenu.prototype, "label", 2);
+__decorateClass([
+  property({ type: Number, attribute: "max-height" })
+], GdsContextMenu.prototype, "maxHeight", 2);
 __decorateClass([
   property()
 ], GdsContextMenu.prototype, "placement", 2);

package/components/details/details.component.js

@@ -85,7 +85,7 @@ let GdsDetails = class extends withSizeXProps(
           rank="tertiary"
           size=${this.size === "small" ? "xs" : "medium"}
           role="presentation"
-          tabindex="-1"
+          gds-tabindex="-1"
         >
           <gds-icon-details .open=${this.open}></gds-icon-details>
         </gds-button>

package/components/form-summary/summary.component.d.ts

@@ -6,12 +6,14 @@ import { GdsElement } from '../../gds-element';
  * When a user attempts to submit a form with errors, this component displays a summary of those errors.
  * Including an error summary greatly assists users in promptly identifying and addressing multiple errors
  * in a consolidated manner. It provides a clear indication of what went wrong and what needs to be corrected.
+ *
+ * @slot header - Optional slot for customizing the header of the summary.
  */
 export declare class GdsFormSummary extends GdsElement {
     #private;
     static styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     /**
-     * Whether to hide the error messages under the labels.
+     * @deprecated This no longer has any effect, and will be removed in a future release.
      */
     hideErrors: boolean;
     /**
@@ -35,7 +37,7 @@ export declare class GdsFormSummary extends GdsElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * Refresh the component to reflext the current state of the form.
+     * Refresh the component to reflect the current state of the form.
      */
     refresh(): void;
     render(): any;