gd-design-library 1.8.1 → 1.8.3

package/README.md

@@ -1,347 +1,240 @@
 # GridKit – Grid Dynamics Design System
 
-![GridKit Logo](./gridKit_logo.png)
+![GridKit Logo](https://unpkg.com/gd-design-library/gridKit_logo.png)
 
-**GridKit** is the official design system and component library from Grid Dynamics.  
-It provides a set of reusable, accessible, and themeable React UI components designed to accelerate the development of consistent, scalable applications – with a focus on e-commerce and enterprise platforms.
+**GridKit** is Grid Dynamics' official React component library — 64 accessible, themeable components built for e-commerce and enterprise applications. It connects directly to Figma design tokens and includes a built-in AI layer that lets LLMs generate and render UI at runtime.
 
----
-
-## ✨ Features
-
-- 🧩 55+ modular components (atoms, molecules, organisms, layout)
-- 🎨 Theming support with dynamic runtime switching
-- 🔗 Design tokens synced with Figma
-- 📦 Optimized build using Vite
-- 📚 Fully documented via Storybook
-- ♿ WCAG 2.1 AA-compliant components
-- ⚙️ Type-safe and fully tested with Vitest + RTL
+**Browse components:** [Storybook](https://storybook.cto-rnd-system-design.griddynamics.net)
 
 ---
 
-## 📦 Installation
-
-Start by ensuring that you already have `@emotion/react` and `@emotion/styled` installed. Then, run one of the following commands to install the dependencies:
-
-```bash
-npm install gd-design-library @emotion/styled @emotion/react
-# or
-yarn add gd-design-library @emotion/styled @emotion/react
-```
+## At a glance
 
-Make sure you're using Node.js **version ≥22.17.0**.
-
-Note: Since this package is private, you need to configure your `.npmrc` with a valid auth token:
-
-```bash
-//registry.npmjs.org/:_authToken=<npm_token>
-```
+|                |                                                     |
+| -------------- | --------------------------------------------------- |
+| Components     | 64 — atoms, molecules, organisms, layout            |
+| Theming        | Runtime switching, Figma-synced design tokens       |
+| Accessibility  | WCAG 2.1 AA                                         |
+| AI integration | LLM → React/TSX code **or** A2UI JSON → rendered UI |
+| Testing        | Vitest + React Testing Library                      |
+| Build          | Vite, ESM + CJS, tree-shakeable                     |
 
 ---
 
-## 🧑‍💻 Getting Started
+## Quick start
 
-### Prerequisites
-
-- Node.js (22.17.0 or higher)
-- Yarn or npm
-
-### Clone & Install
+### 1. Install
 
 ```bash
-git clone https://github.com/griddynamics/cto-rnd-system-design.git
-cd gd-design-system
-yarn install
+npm install gd-design-library @emotion/styled @emotion/react
 ```
 
----
-
-## 🚀 Development
+### 2. Wrap your app
 
-Start the local dev server with Vite:
+```tsx
+import { ThemeProvider } from 'gd-design-library';
+import 'gd-design-library/styles.css'; // optional: GD global styles, reset, fonts
 
-```bash
-yarn dev
+function App() {
+  return (
+    <ThemeProvider isDefault>
+      <YourApp />
+    </ThemeProvider>
+  );
+}
 ```
 
-Open [http://localhost:5173](http://localhost:5173) in your browser.
+### 3. Use a component
 
-### Run Storybook
+```tsx
+import { Button, Typography } from 'gd-design-library';
 
-```bash
-yarn storybook
+function Hero() {
+  return (
+    <>
+      <Typography variant="h1">Hello GridKit</Typography>
+      <Button variant="primary" onClick={() => alert('clicked')}>
+        Get started
+      </Button>
+    </>
+  );
+}
 ```
 
----
-
-## 🏗️ Project Structure
-
-```bash
-gd-design-system/
-├── src/
-│   ├── components/
-│   │   ├── atoms/              # 21 basic building blocks (Button, Input, etc.)
-│   │   ├── molecules/          # 18 simple combinations (Accordion, Table, etc.)
-│   │   ├── organisms/          # 10 complex sections (Card, Chart, Modal, etc.)
-│   │   └── layout/             # 6 structural components (Row, Column, FlexContainer, etc.)
-│   ├── ai/                    # AI integration system (code mode + A2UI mode)
-│   ├── tokens/                 # Design tokens from Figma
-│   ├── hooks/                  # Shared React hooks
-│   └── utils/                  # Utility functions
-├── .storybook/                 # Storybook config
-├── vite.config.ts              # Vite config
-├── tsconfig.json               # TypeScript config
-├── README.md
-```
+That's it. Open [Storybook](https://storybook.cto-rnd-system-design.griddynamics.net) to browse all 64 components with live props and code samples.
 
 ---
 
-## 🧪 Testing & Linting
+## Theming
 
-### Run Tests
+### Use the built-in default theme
 
-```bash
-yarn test
-```
+Pass `isDefault` to `ThemeProvider` — applies GD tokens and global styles automatically.
 
-### Lint Code
-
-```bash
-yarn lint
-```
-
-### Format Code
-
-```bash
-yarn format
-```
-
-### Check Formatting
-
-```bash
-yarn format:check
+```tsx
+<ThemeProvider isDefault>
+  <App />
+</ThemeProvider>
 ```
 
----
-
-## 🧰 Component Generator
-
-Use our CLI script to quickly scaffold new components:
+### Extend the default theme
 
-### Add Execution Permission (first time)
+Override only the tokens you need. Everything else inherits from `defaultTheme`.
 
-```bash
-chmod +x ./bin/create-component.js
-```
+```tsx
+import { ThemeProvider, defaultTheme } from 'gd-design-library';
+import myBrandTokens from './myBrandTokens';
 
-### Create a Component
+const theme = { ...defaultTheme, ...myBrandTokens };
 
-```bash
-yarn crc ButtonGroup
+<ThemeProvider initialTheme={theme}>
+  <App />
+</ThemeProvider>;
 ```
 
-You’ll be prompted to select:
-
-- `core`
-- `domainSpecific`
+### Switch themes at runtime
 
-The script will generate boilerplate files and update exports automatically.
+Use the `useTheme` hook and `updateThemeTokens` to create and activate a custom theme dynamically.
 
----
+```tsx
+import { useEffect } from 'react';
+import { updateThemeTokens, defaultTheme, useTheme } from 'gd-design-library';
 
-## 🧩 Usage
+export function useCustomTheme() {
+  const { addTheme, setTheme } = useTheme();
 
-Wrap your app in the `ThemeProvider` with `isDefault` to apply default GD global styles and tokens:
+  useEffect(() => {
+    const custom = { ...defaultTheme, name: 'brand' };
 
-```tsx
-import { ThemeProvider } from 'gd-design-library';
-// OPTIONAL: default GD global styles, reset, font.
-import 'gd-design-library/styles.css';
+    updateThemeTokens(custom, {
+      'button.default': { borderRadius: '32px' },
+      'select.dropdown': { backgroundColor: '#f5f5f5', borderRadius: '8px' },
+    });
 
-function App() {
-  return (
-    <ThemeProvider isDefault>
-      <YourAppRoutes />
-    </ThemeProvider>
-  );
+    addTheme(custom.name, custom);
+    setTheme(custom.name);
+  }, []);
 }
 ```
 
-or `initialTheme` to install custom one as default initially
+Call `useCustomTheme()` anywhere in your tree — components update immediately.
+
+**Token shape example** (`myBrandTokens.json`):
 
 ```json
 {
-  "name": "myCustomTheme",
-  "componentAStyles": {
-    "style": "value"
-  }
+  "name": "brand",
+  "button.default": { "borderRadius": "4px" },
+  "chatbubble.question": { "background": "#F1F5FA" }
 }
 ```
 
-```tsx
-import { ThemeProvider, defaultTheme } from 'gd-design-library';
-import myCustomTheme from 'PROJECT_PATH/myCustomTheme'; // JSON or any js/ts and similliar with object return
+---
 
-const App = () => {
-  // In case you want extend default theme, by overwriting only particular components
-  const initialTheme = Object.assign({}, defaultTheme, myCustomTheme);
-  return (
-    <ThemeProvider initialTheme={initialTheme}>
-      <YourAppRoutes />
-    </ThemeProvider>
-  );
-};
-```
+## AI integration — A2UI
 
-You can now use components like this:
+A2UI (Agent-to-UI) lets an LLM output a structured JSON spec. GridKit renders it as real React components — no JSX on your side.
 
-```tsx
-import { Button } from 'gd-design-library';
+### How it works
 
-<Button variant="primary">Click me</Button>;
+```text
+User message → LLM (with system prompt from buildA2UISystemPrompt)
+                    → A2UISpec JSON (validated against schema)
+                          → renderA2UISpec → React components
 ```
 
-## Adding new theme
+Two functions, one shared `actions` array:
 
-Here’s a minimal React app example showing how to create and apply custom theme based on default, exactly like in your snippet.
-Example structure:
+| Function                         | What it does                                                                                    |
+| -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `buildA2UISystemPrompt(options)` | Generates the LLM system instruction. Injects your `actions` as the only callable action types. |
+| `renderA2UISpec(spec, actions)`  | Maps the validated JSON spec to GridKit components and wires action handlers.                   |
 
-- `main.tsx`: wraps the app with `ThemeProvider`
+### Minimal example
 
 ```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import App from './App';
-
-import { ThemeProvider } from 'gd-design-library';
+import { buildA2UISystemPrompt, renderA2UISpec } from 'gd-design-library/ai';
+import type { A2UIActionDefinition } from 'gd-design-library/ai';
+
+// Define actions once — shared by prompt builder and renderer
+const actions: A2UIActionDefinition[] = [
+  {
+    type: 'add-to-cart',
+    description: 'Add a product to the cart. payload: { productId: string, quantity: number }',
+    handler: ({ payload }) => addToCart(payload),
+  },
+];
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <ThemeProvider isDefault>
-      <App />
-    </ThemeProvider>
-  </React.StrictMode>
-);
+// Build the system prompt for your LLM
+const systemPrompt = buildA2UISystemPrompt({
+  agentId: 'shop-agent',
+  agentName: 'Shop Assistant',
+  context: 'E-commerce product catalog.',
+  actions,
+});
+
+// Render whatever the LLM returns
+function AgentResponse({ spec }) {
+  return <>{renderA2UISpec(spec, actions)}</>;
+}
 ```
 
-- `useCustomTheme.tsx`: theme hook
+### Gemini structured output
 
-\*\* Can be used on top level instead `isDefault`, use `initialTheme`, based on `updateThemeTokens` & `defaultTheme` from hook snippet
+Pass the schema directly to `responseSchema` — the model returns valid JSON every time.
 
 ```tsx
-import { useEffect } from 'react';
-import { updateThemeTokens, defaultTheme, useTheme } from 'gd-design-library';
-
-export default function useCustomTheme() {
-  const { addTheme, setTheme } = useTheme();
-  const customTheme = {
-    ...defaultTheme,
-    name: 'CustomTheme',
-  };
-  useEffect(() => {
-    // Customise tokens
-    updateThemeTokens(customTheme, {
-      'select.dropdown': {
-        backgroundColor: 'red',
-        borderRadius: '10px',
-        boxShadow: '0 0 10px rgba(0, 0, 0, 0.1)',
-        padding: '10px',
-        width: '200px',
-        height: '200px',
-        zIndex: 1000,
-        position: 'absolute',
-        top: '50%',
-        left: '50%',
-      },
-      // any other theme overwrites here
-      'button.default': {
-        borderRadius: '32px',
-      },
-      'chatbubble.question': {
-        background: '#F1F5FA',
-      },
-    });
-    // Add customTheme in a theme scope
-    addTheme(customTheme.name, customTheme);
-    //Set customTheme as an active, optional on demand to apply as an active
-    setTheme(customTheme.name);
-  }, []);
-}
+import { buildA2UIGeminiRequest, A2UI_SPEC_SCHEMA } from 'gd-design-library/ai';
+
+const model = genAI.getGenerativeModel({
+  model: 'gemini-2.5-flash',
+  generationConfig: {
+    responseMimeType: 'application/json',
+    responseSchema: A2UI_SPEC_SCHEMA,
+  },
+});
+
+const result = await model.generateContent(
+  buildA2UIGeminiRequest('Show a product analytics dashboard', {
+    agentId: 'analytics-agent',
+    context: 'Product analytics for an e-commerce platform.',
+    actions,
+  })
+);
 ```
 
-- `App.tsx`: renders a `Select` to demonstrate the change
+### Validate before rendering
 
 ```tsx
-import React from 'react';
-
-import { FlexContainer, Typography, Row, Select, type Option } from 'gd-design-library';
-
-import useCustomTheme from './useCustomTheme';
-
-const items: Option[] = [
-  { name: 'Option 1', value: 'option1' },
-  { name: 'Option 2', value: 'option2' },
-  { name: 'Option 3', value: 'option3' },
-];
+import schema from 'gd-design-library/ai/ui-specification-schema.json';
+import Ajv from 'ajv';
 
-export default function App() {
-  useCustomTheme();
+const validate = new Ajv().compile(schema);
 
-  return (
-    <FlexContainer>
-      <Typography>Custom Themed Select</Typography>
-      <Row>
-        <Select items={items} />
-      </Row>
-    </FlexContainer>
-  );
+if (!validate(spec)) {
+  console.error('Invalid A2UI spec:', validate.errors);
 }
 ```
 
----
+Full reference: [`./ai/README.md`](./ai/README.md) and [`./ai/PROMPT_USAGE_MANUAL.md`](./ai/PROMPT_USAGE_MANUAL.md)
 
-## 🤖 AI Integration
+---
 
-GridKit ships a built-in AI integration layer at [`./ai`](./ai/README.md) that lets LLMs generate UI — either as **React/TSX code** or as **A2UI JSON specs** rendered at runtime.
+## Project structure
 
 ```text
-./ai/
-├── README.md                        # AI integration overview
-├── PROMPT_USAGE_MANUAL.md           # Full prompt usage guide
-├── index.d.ts                       # Main exports (code mode + A2UI mode)
-├── prompts.d.ts                     # buildClaudeSystemPrompt, buildGPT4Prompt, buildGeminiPrompt
-├── discovery.d.ts                   # Component discovery utilities
-├── validation.d.ts                  # Schema & generated-code validation
-├── a2ui/                            # A2UI JSON spec mode
-│   ├── A2UI_PROTOCOL.md             # Protocol specification
-│   ├── index.d.ts                   # A2UI exports
-│   ├── component-map.d.ts           # A2UI type → GridKit component mapping
-│   ├── system-prompt.d.ts           # buildA2UISystemPrompt(), buildA2UIGeminiRequest()
-│   ├── spec-schema.d.ts             # A2UISpec TypeScript types
-│   └── ui-specification-schema.json # AJV/Gemini responseSchema
-└── schemas/                         # Component AI schemas (52 components)
-    ├── index.d.ts
-    ├── components.d.ts
-    ├── components/                  # Per-component schemas
-    └── hooks/
-        └── useTheme.d.ts
+libs/ui/src/
+├── components/
+│   ├── atoms/       # 21 primitives — Button, Input, Badge, …
+│   ├── molecules/   # 18 composites — Accordion, Table, …
+│   ├── organisms/   # 10 sections — Card, Chart, Modal, …
+│   └── layout/      # 6 containers — Row, Column, FlexContainer, …
+├── ai/              # AI integration (code mode + A2UI mode)
+├── tokens/          # Design tokens (synced from Figma)
+├── hooks/           # Shared React hooks
+└── utils/           # Utility functions
 ```
 
-See [`./ai/README.md`](./ai/README.md) for full documentation.
-
----
-
-## 📘 Documentation
+## License
 
-Explore our hosted Storybook:
-
-👉 [https://storybook.cto-rnd-system-design.griddynamics.net](https://storybook.cto-rnd-system-design.griddynamics.net)
-
----
-
-## 📄 License
-
-© Grid Dynamics. All rights reserved.  
-This package is for internal and authorized client use only.
-
----
+© Grid Dynamics. All rights reserved. For internal and authorized client use only.

package/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));exports.__toESM=s;