gd-design-library 0.7.1 → 0.7.3

package/README.md

@@ -198,6 +198,103 @@ import { Button } from 'gd-design-library';
 <Button variant="primary">Click me</Button>;
 ```
 
+## Adding new theme
+
+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:
+
+- `main.tsx`: wraps the app with `ThemeProvider`
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+import { ThemeProvider } from 'gd-design-library';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ThemeProvider isDefault>
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>
+);
+```
+
+- `useCustomTheme.tsx`: theme hook
+
+\*\* Can be used on top level instead `isDefault`, use `initialTheme`, based on `updateThemeTokens` & `defaultTheme` from hook snippet
+
+```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);
+  }, []);
+}
+```
+
+- `App.tsx`: renders a `Select` to demonstrate the change
+
+```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' },
+];
+
+export default function App() {
+  useCustomTheme();
+
+  return (
+    <FlexContainer>
+      <Typography>Custom Themed Select</Typography>
+      <Row>
+        <Select items={items} />
+      </Row>
+    </FlexContainer>
+  );
+}
+```
+
 ---
 
 ## 📘 Documentation

package/ai/README.md

@@ -0,0 +1,137 @@
+# AI prompt and codegen usage for gd-design-library (GridKit)
+
+This README explains how to use the AI helpers in `/ai` to reliably generate React/TSX that only uses `gd-design-library`. It consolidates the hard rules, guardrails, and helper APIs exposed by this folder.
+
+Why these rules exist:
+
+- Consistency: a single design system source makes UI consistent and themable.
+- Accessibility: components provide sensible defaults and ARIA support.
+- Maintainability: no ad‑hoc CSS/HTML or third‑party UI imports.
+
+Core rule (must follow):
+
+- Use ONLY components exported by `gd-design-library` for layout, forms, feedback, display, and navigation. Do not invent components. Do not import from other UI libraries.
+
+Single-source import (enforced):
+
+- Correct: `import { Form, Input, Button, Typography, FlexContainer, Column, Card, Link } from 'gd-design-library';`
+- Incorrect: `import Button from 'some-ui-lib';`, `import { Box } from '@mui/material';`, or using `./styles.css` for layout spacing.
+
+How to use the AI helpers
+
+1. Programmatic prompt builder (recommended)
+
+- Import from the AI helpers barrel:
+  - `import { buildClaudeSystemPrompt } from 'gd-design-library/ai';`
+- Build your system+task prompt:
+  - `const prompt = buildClaudeSystemPrompt('Create a sign-in form with email and password');`
+    What this does:
+- Includes a live list of available components and composition tips from `./ai/schemas/components.ts` and `./ai/schemas/components/*`.
+- Enforces single-source imports from `gd-design-library` and accessibility/theming guardrails.
+
+2. Legacy/basic builder
+
+- `buildGDLibraryPrompt(request: string)` is kept for compatibility. It defers to `buildClaudeSystemPrompt`.
+
+3. Direct constant (advanced)
+
+- `CLAUDE_GRIDKIT_SYSTEM_PROMPT` contains the full system instructions. You can append your task to it manually if needed.
+
+Practical generation tips (what the model should output)
+
+- Output ONLY valid React TSX. No markdown fences or commentary.
+- Prefer composition using the provided layout primitives (FlexContainer, Column, Row, Card.\* subcomponents, etc.).
+- Keep custom styles minimal; use component props for spacing, alignment, sizing.
+- Always ensure accessibility: label all form controls (Label or Input label prop), use appropriate aria-\* attributes, and keep keyboard navigation sensible.
+- Do not inline the ThemeProvider inside leaf components; provide it at the app root. See Theme provider/hook entries in the schema.
+- Keep imports consolidated to one source: `gd-design-library`.
+
+API guardrails from the schema/prompt (must-follow)
+
+- Row/Column/Card.Row/Card.Column: use `isWrap` (boolean), NOT `wrap`.
+- Image and Card.Image: `width` and `height` props are numbers only (e.g., `width={96}`), not strings like `"96px"`.
+- Card.Title and other Card subcomponents: `sizeVariant` only accepts `CardSizeVariant.Default` or `CardSizeVariant.Sm`.
+- Counter and Card.Counter: use `initial` (not `value`) for the starting quantity; use `onCounterChange` as the change handler.
+- Button `variant` must be one of `ButtonVariant.Contained | ButtonVariant.Outlined | ButtonVariant.Text | ButtonVariant.Inherit`.
+- Button `color` must be one of `ButtonColorVariant.Primary | ButtonColorVariant.Secondary`.
+
+Component catalog
+
+- The authoritative, up-to-date list of supported components, their props, examples, and composition tips is generated from:
+  - `./schemas/components.ts` (registry)
+  - `./schemas/components/*` (per-component schemas)
+- The list includes layout, forms, feedback, display, navigation, and theme provider/hook entries. Always consult these when unsure.
+- Quick categories (from schema v1.0.0):
+  - Theme: useTheme.provider (ThemeProvider), useTheme.hook (useTheme)
+  - Layout: FlexContainer, Column, Row, Wrapper, Scroll, Separator
+  - Forms: Form, Input, Select, Search, Label, Textarea, Switch, Toggle, RadioGroup, Slider, InputFile, DragAndDropFiles
+  - Feedback & overlays: InlineNotification, Loader, Skeleton, Snackbar, SnackbarManager, Tooltip, Modal, Portal
+  - Navigation & structure: Breadcrumbs, Tabs, Stepper, List, Accordion, Link
+  - Display & content: Typography, Button, Icon, Image, Card, Avatar, Carousel, ContentCarousel, Counter, Price, ProgressBar, Rating, ChatContainer, ChatBubble
+- Not part of gd-design-library (do not request/use): Grid, Stack, Alert, Toast, Table, Badge, ButtonGroup, Dropdown, Drawer, Popover, Pagination, Heading, Spinner.
+
+Patterns from stories (grounded tips)
+
+- Textarea:
+  - Control resizing with the `resize` prop using the `TextareaResize` enum (e.g., None, Horizontal, Vertical, Both). Prefer `dynamicHeightAdjustment` for auto-growing content.
+  - Use `rows` for fixed height or `minHeight`/`maxHeight` for constraints.
+  - Controlled vs uncontrolled: use `value` with `onChange` for controlled; use `defaultValue` for uncontrolled.
+  - Accessibility: use `ariaDescribedBy` to connect helper/error text; set `readOnly`/`disabled` as needed; `autoFocus` is available.
+  - Limits and events: `maxLength` to constrain length; `onCustomResize` receives `{ height, width }` when user resizes.
+- Buttons:
+  - Variants: `ButtonVariant.Contained | Outlined | Text | Inherit`; Colors: `ButtonColorVariant.Primary | Secondary`. For icon-only buttons, set `isIcon`.
+- Forms and labels:
+  - Always provide a visible label via the `label` prop or a separate `<Label htmlFor>` paired with the input `name/id`. Wrap controls with `<Form>` and handle submit via `onSubmit`.
+- Layout composition:
+  - Use `FlexContainer` with `Column`/`Row` and `gap` to manage spacing. Avoid raw CSS margins except where necessary.
+- Cards and images:
+  - `Card.Title` uses `sizeVariant={CardSizeVariant.Default | CardSizeVariant.Sm}` only. `Card.Image` and `Image` require numeric `width`/`height` props.
+
+Example: Correct usage
+
+```
+import { Form, Input, Button, Typography, FlexContainer, Column, Card, Link } from 'gd-design-library';
+
+export function LoginCard() {
+  return (
+    <FlexContainer alignItems="center" justifyContent="center" minHeight="100vh" padding="24px">
+      <Card width={360} padding="24px">
+        <Column gap="12px">
+          <Typography as="h1" variant="h2">Sign in</Typography>
+          <Form onSubmit={(e) => { e.preventDefault(); /* TODO: submit */ }}>
+            <Column gap="12px">
+              <Input variant="email" label="Email" name="email" />
+              <Input variant="password" label="Password" name="password" />
+              <Button type="submit" fullWidth>Sign in</Button>
+            </Column>
+          </Form>
+          <Typography variant="small">
+            Don’t have an account? <Link href="#">Sign up</Link>
+          </Typography>
+        </Column>
+      </Card>
+    </FlexContainer>
+  );
+}
+```
+
+Incorrect usage (anti-patterns)
+
+```
+import Button from 'some-ui-lib';
+import { Box } from '@mui/material';
+
+export function Login() {
+  return (
+    <div className="container"> {/* Do not build layout with raw divs/CSS */}
+      <button>Sign in</button>   {/* Do not use native elements for styled UI */}
+    </div>
+  );
+}
+```
+
+Troubleshooting and notes
+
+- If a component/prop isn’t recognized, verify it exists in `gd-design-library` exports and the AI schemas under `./ai/schemas/components/*`.
+- When new components are added to the design system, update their schema and the central registry in `./ai/schemas/components.ts` so prompts stay accurate.
+- The default intro string in code (`defaultAIPromptIntro`) is aligned with the schema. Prefer the schema-driven builders (e.g., `buildClaudeSystemPrompt`) for the most accurate, current catalog.

package/ai/schemas/components/Row.d.ts

@@ -7,12 +7,32 @@ declare const _default: {
             name: string;
             type: string;
             description: string;
-            default: string;
+            enum: string[];
+            default?: undefined;
+        } | {
+            name: string;
+            type: string;
+            description: string;
+            default: number;
+            enum?: undefined;
         } | {
             name: string;
             type: string;
             description: string;
+            default: boolean;
+            enum?: undefined;
+        } | {
+            name: string;
+            type: string;
+            description: string;
+            enum?: undefined;
             default?: undefined;
+        } | {
+            name: string;
+            type: string;
+            description: string;
+            default: string;
+            enum?: undefined;
         })[];
         examples: string[];
     };

package/index.d.ts

@@ -2,4 +2,3 @@ export * from './hooks';
 export * from './components';
 export * from './tokens';
 export * from './assets';
-export * from './ai';