gantri-components 2.210.0 → 2.211.0

package/CLAUDE.md

@@ -0,0 +1,452 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Building and Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the library
+yarn build
+
+# Clean and build (removes dist folder first)
+yarn clean-build
+
+# Start Storybook development server
+yarn storybook
+
+# Build Storybook static site
+yarn build-storybook
+
+# Generate icons (create React components from SVG files)
+yarn generate-icons
+
+# Type checking
+yarn typecheck
+```
+
+### Testing
+
+```bash
+# Run tests in watch mode (default)
+yarn test
+
+# Run specific tests
+yarn test -- <file-pattern> # e.g. yarn test -- button.test
+
+# Run tests with coverage report
+yarn test:coverage
+
+# Run tests in CI mode
+yarn test:ci
+```
+
+## Repository Structure and Architecture
+
+The Gantri Components library is a React component library implementing Gantri's design system. It provides a set of reusable UI components built with React and styled-components.
+
+### Core Architecture
+
+- `src/components/`: Contains all UI components in separate directories
+  - Each component typically follows this structure:
+    - `index.ts` - Re-exports everything from the component directory
+    - `component-name.tsx` - Main component implementation
+    - `component-name.types.ts` - TypeScript interfaces and types
+    - `component-name.styles.tsx` - Styled components
+    - `component-name.presets.ts` - Default props and variations
+    - `component-name.stories.tsx` - Storybook stories
+    - `__tests__/` - Test files
+
+- `src/styles/`: Contains theme definitions and styling utilities
+  - `theme.tsx` - The theme object with colors, typography, spacing
+  - `animations.ts` - Animation definitions
+  - `media.ts` - Media query utilities for responsive design
+
+- `src/assets/`: Contains static assets
+  - `icons/` - SVG icon files organized by category
+  - `fonts/` - Font files
+
+- `src/helpers/`: Utility functions and hooks
+  - Various helper modules for common tasks
+
+### Design System
+
+The design system is based around these key concepts:
+
+1. **Theming** - Light and dark themes defined in `src/styles/theme.tsx`
+2. **Colors** - Comprehensive color palette with semantic colors
+3. **Typography** - Predefined typography styles (h1-h6, p0-p3, etc.)
+4. **Spacing** - Consistent spacing based on an 8px grid
+5. **Breakpoints** - Responsive design with predefined breakpoints
+
+### Component Architecture
+
+Components use a composition pattern where simpler components are combined to create more complex ones:
+
+- `Box` - The foundation component for layout with space, color, and flexbox properties
+- `Flex` - Extends Box with flexbox container properties 
+- `Typography` - Text rendering with predefined styles
+- etc.
+
+Most components accept:
+- Standard HTML props for their base elements
+- Theme-based styling props (colors, spacing, etc.)
+- Component-specific functionality props
+
+## Theme System
+
+### 4 Themes
+- `lightTheme` (id: `classic-light`) - Classic light
+- `darkTheme` (id: `classic-dark`) - Classic dark
+- `modernLightTheme` (id: `modern-light`) - Modern light with opacity/glass effects
+- `modernDarkTheme` (id: `modern-dark`) - Modern dark with luminosity blends
+
+### Theme Structure
+```typescript
+theme.name       // 'light' | 'dark' - base mode for backward compatibility
+theme.id         // unique identifier: 'classic-light', 'modern-dark', etc.
+theme.fallbacks  // resolution chain for themeStyle: ['modern-dark', 'dark']
+```
+
+### Adding Modern Theme Styles
+Use `themeStyle` utility for theme-specific CSS. **Never** check `theme.id` directly.
+
+```typescript
+import { themeStyle } from 'gantri-components';
+
+// themeStyle MUST be inside the main interpolation block
+const StyledBox = styled.div<StyledBoxProps>`
+  ${({ theme }) => css`
+    background: ${theme.colors.surfaces.monochrome.t1};
+
+    ${themeStyle<StyledBoxProps>({
+      'modern-dark': ({ $prop }: StyledBoxProps) => css`
+        background: rgba(204, 204, 204, 0.13);
+      `,
+    })}
+  `}
+`;
+```
+
+**CRITICAL**: Always add explicit type annotations to themeStyle callback params to avoid TS7031.
+
+### Modern Theme Design Tokens
+
+**Flat (modern-light):**
+- Input bg: `rgba(0,0,0,0.07)`, hover: `rgba(0,0,0,0.19)`
+- Text: primary `rgba(0,0,0,0.9)`, secondary `rgba(0,0,0,0.5)`, tertiary `rgba(0,0,0,0.35)`
+- Border radius: 12px inputs, 40px buttons
+- Hover glow: `inset 0 0 48px white`
+
+**Dynamic (modern-dark):**
+- Input bg: luminosity `rgba(204,204,204,0.13)` + backdrop-blur 32px
+- Text: primary `white`, secondary `rgba(242,242,242,0.7)`, tertiary `rgba(229,229,229,0.6)`
+- Hover glow: same with luminosity blend
+
+## Component Quick Reference
+
+### Button
+
+**How to identify variants from Figma:**
+
+| What you see in Figma | Variant to use |
+|---|---|
+| Green/brand color filled button | `primary` |
+| Dark/black filled button | `primaryContrast` |
+| Light gray or translucent filled button (not prominent) | `secondary` |
+| Same as secondary but with visible border | `tertiary` |
+| Transparent button, no background, text only | `ghost` |
+| Red/danger filled button | `primaryAlert` |
+| On dark backgrounds: bright/white glass-like button | `primaryContrast` |
+| On dark backgrounds: subtle translucent button | `secondaryContrast` |
+| On dark backgrounds: transparent, no background | `ghostContrast` |
+
+**How to identify sizes from Figma:**
+
+| Figma height | Size prop |
+|---|---|
+| ~36-40px | `small` |
+| ~48px | `medium` |
+| ~56-64px | `large` |
+| ~80px | `extraLarge` |
+
+**Icon-only**: If the button is a perfect circle with just an icon (no text), pass `icon` without `text`.
+
+- Modern themes: pill shape (40px radius), inner glow, no border
+- Classic themes: square corners (theme.borderRadius), solid borders
+
+### TextField / TextArea
+
+**How to identify from Figma:**
+
+| What you see | Props |
+|---|---|
+| Input with solid/tinted background, no underline | `variant="filled"` |
+| Input with only a bottom border line | `variant="line"` |
+| Floating label inside the input that shrinks on focus | Size `L` (large) — label is inside |
+| External label above the input | Size `M` (medium) — label is outside |
+| "(Optional)" text next to label | `required` is false (default) |
+| No "(Optional)" text | `required={true}` |
+
+- **Sizes**: `small`, `medium` (default), `large`
+- Label uses `Label` component internally
+
+### OptionSelector
+- Grid of selectable options with `columns`, `gap`, `size`, `optionMaxWidth`
+- Supports string items or `{ value, label, badge?, disabled? }` objects
+- `labelText` for built-in label, `required` prop
+- Formik compatible via `FormikInput` `Field` prop
+
+### Banner
+
+**How to identify variants from Figma:**
+
+| What you see | Variant |
+|---|---|
+| Green background | `success` |
+| Blue/purple background | `info` |
+| Orange background | `warning` |
+| Red background | `alert` |
+| Light gray/subtle background | `subtle` |
+| Dark/black background | `contrast` |
+| Glass/blur background on dark surface | `dynamic` |
+| Solid vibrant color | `emphasized={true}` (default) |
+| Light tinted/muted color | `emphasized={false}` |
+| Label + chevron `>` on right, single row | `layout="horizontal"` |
+| Label + caption + "Action" button below | `layout="vertical"` |
+
+### Typography
+
+**CRITICAL: Always use Typography for text. Never put raw text in JSX.**
+
+```typescript
+<Typography text="Hello" variant="p2" color="t1" />
+```
+
+**How to identify variant from Figma:**
+
+| Figma font size | Variant | Font |
+|---|---|---|
+| 130px | `mh1` | Roboto Mono |
+| 50px | `mh2` | Roboto Mono |
+| 25px | `mp1` | Roboto Mono |
+| 16px | `mp2` | Roboto Mono |
+| 12px (mono) | `mp3` / `mh3`-`mh6` | Roboto Mono |
+| 52px | `h1` | Söhne |
+| 44px | `h2` | Söhne |
+| 28px | `h3` | Söhne |
+| 22px | `h4` | Söhne |
+| 20px | `h5` | Söhne |
+| 15px (heading) | `h6` | Söhne |
+| 32px | `p0` | Söhne |
+| 20px (body) | `p1` | Söhne |
+| 15px (body) | `p2` | Söhne |
+| 12px (body) | `p3` | Söhne |
+
+**Color prop values:** `t1` (primary), `t2` (secondary), `t3` (tertiary), `alt` (white/contrast), `link` (green), `alert` (red), `success`, `warning`
+
+**Spacing:** Typography extends ElementSpacingProps — use `marginTop="2x"`, `paddingBottom="x"`, etc.
+
+**Bold text:** Use `fontWeight={700}`, NOT `textStyle="bold"`
+
+### Grid / Cell (Layout System)
+
+**Use Grid+Cell for page-level section layouts, not Flex.**
+
+```typescript
+<Grid columns={{ lg: 12, md: 4 }}>
+  <Cell width={{ lg: 6, md: 4 }} row={{ md: 2 }}>
+    <LeftContent />
+  </Cell>
+  <Cell column={{ lg: 8 }} width={{ lg: 5, md: 4 }} row={{ md: 1 }}>
+    <RightContent />
+  </Cell>
+</Grid>
+```
+
+**Responsive cascade:** Values cascade downward: `lg → md → sm`. If `md` is set but not `sm`, `sm` inherits `md`.
+
+**Desktop:** 12 columns. **Mobile:** 4 columns.
+
+### Box
+
+Foundation layout component. All spacing props use `BoxDimension` values.
+
+```typescript
+<Box marginTop="3x" paddingLeft="2x" />
+```
+
+**BoxDimension values:** `.5x` (4px), `x` (8px), `2x` (16px), `3x` (24px), `4x` (32px), `5x` (40px), `6x` (48px), `8x` (64px), `10x` (80px), `12x` (96px), `16x` (128px), `20x` (160px), `24x` (192px)
+
+### Flex
+
+Extends Box with flexbox props.
+
+```typescript
+<Flex direction="column" justifyContent="space-between" alignItems="center" gap="2x">
+  <Child />
+</Flex>
+```
+
+**Props:** `direction` (not `flexDirection`), `justifyContent` (not `justify`), `alignItems` (not `align`), `gap`
+
+### Stack
+
+Vertical stack with padding.
+
+```typescript
+<Stack horizontalPadding="2x" verticalPadding="3x">
+  <Child />
+</Stack>
+```
+
+### Icon
+
+```typescript
+<Icon name="category:icon_name" size="24px" color="t1" />
+```
+
+**Categories:** `actions`, `alert`, `arrows`, `docs`, `media`, `ui-control`, `view`, `work`
+
+**Common icons:**
+- `ui-control:plus`, `ui-control:x`, `ui-control:check_mark`
+- `arrows:arrow_right`, `arrows:arrow_left`, `arrows:arrow_chevron_right`, `arrows:arrow_chevron_down`
+- `view:magnifying_glass`, `docs:pencil`, `alert:i_circle`
+- `work:box`, `work:light_bulb`
+
+### Modal
+
+```typescript
+<Modal closeable header="Title" footer={footerJSX} maxWidth="520px" onClose={onClose}>
+  <Content />
+</Modal>
+```
+
+Always use gantri-components Modal, never custom modal wrappers.
+
+### Dropdown
+
+```typescript
+<Dropdown items={[{ value: 1, label: 'Option' }]} labelText="Select" placeholder="Choose..." />
+```
+
+Delegates to TextField internally for label/input rendering.
+
+### SearchField
+
+```typescript
+<SearchField items={items} labelText="Search" placeholder="Type..." maxHeight={300} />
+```
+
+### FormikInput (Formik Integration)
+
+Wraps any component for Formik form binding:
+
+```typescript
+<FormikInput name="fieldName" labelText="Label" placeholder="..." />
+<FormikInput name="selection" Field={<OptionSelector items={[...]} />} />
+<FormikInput name="color" Field={<ColorPicker />} />
+<FormikInput name="agree" Field={<Checkbox labelText="I agree" />} />
+```
+
+### Conditional / Responsive
+
+```typescript
+<Conditional condition={isLoading} Fallback={<Content />}>
+  <LoadingScreen />
+</Conditional>
+
+<Responsive sm={<MobileView />} md={<TabletView />} lg={<DesktopView />} />
+```
+
+### Label
+- Shows "(Optional)" when `required` is false/undefined
+- Used internally by TextField, TextArea, OptionSelector
+
+### Checkbox / Radio / Toggle
+
+**How to identify from Figma:**
+
+| What you see | Component |
+|---|---|
+| Square/rounded-square check box | `Checkbox` |
+| Circle with dot inside | `Radio` |
+| Pill-shaped sliding switch | `Toggle` |
+| Grid of selectable card/tile options | `RadioList` with `showAsTiles` or `OptionSelector` |
+| Simple text options in a row | `RadioList` inline |
+
+- Modern themes: 24px size, no border, luminosity/solid fills, inner glow when checked
+- Classic themes: 20px, bordered, green fill when checked
+
+## Styling Rules
+
+- Always use CSS variables: `var(--surface-secondary)`, `var(--text-t1)`, `var(--spacing-2x)`
+- Styled components: wrap dynamic styles in `${() => css\`\`}`
+- Use `$` prefix for styled-component-only props
+- 8px spacing grid: `x`=8px, `2x`=16px, `.5x`=4px
+
+## Exports
+```typescript
+import {
+  Button, TextField, TextArea, OptionSelector, Banner, Label,
+  Checkbox, Radio, RadioList, Toggle, Icon, Typography,
+  Flex, Box, Grid, Cell, Modal, Stack, FormikInput,
+  lightTheme, darkTheme, modernLightTheme, modernDarkTheme,
+  ThemeProvider, createTheme, themeStyle,
+  palette, spacing, media,
+} from 'gantri-components';
+```
+
+## Best Practices
+
+### Adding New Components
+
+1. Follow the existing component structure (create all necessary files)
+2. Start from `Box` or another primitive component when possible
+3. Use theme values for colors, spacing, typography
+4. Ensure components are fully typed
+5. Write tests (use React Testing Library)
+6. Create Storybook stories for documentation
+
+### Testing
+
+- Tests use Jest and React Testing Library
+- Components should have unit tests covering functionality
+- Use `renderWithThemeProvider` from test-utils for rendering components with theme context
+- Follow the "Arrange-Act-Assert" pattern in tests
+
+### Working with Icons
+
+When adding new icons:
+
+1. Add SVG files to appropriate category in `/src/assets/icons/`
+2. Follow the naming convention (lowercase, no spaces)
+3. Run `yarn generate-icons` to create React components
+
+### Commit Guidelines
+
+The repository uses conventional commits for automated versioning:
+
+- `feat:` - A new feature (minor version)
+- `fix:` - A bug fix (patch version)
+- `docs:` - Documentation only changes
+- `style:` - Changes that don't affect the meaning of the code
+- `refactor:` - Code change that neither fixes a bug nor adds a feature
+- `perf:` - Performance improvements
+- `test:` - Adding missing tests or correcting existing tests
+- `chore:` - Changes to the build process or auxiliary tools
+
+Note: `chore` commit prefixes do not trigger a new version deployment.
+
+### Publishing Process
+
+To deploy changes, merge them into the appropriate branch:
+
+- `main` - For production releases
+- `beta` - For beta releases (can be installed with `yarn add gantri-components@beta`)
+
+Semantic Release automates versioning and publishing based on commit messages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gantri-components",
-  "version": "2.210.0",
+  "version": "2.211.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "umd": "dist/index.umd.js",
@@ -173,7 +173,8 @@
     "uuid": "^8.3.2"
   },
   "files": [
-    "dist"
+    "dist",
+    "CLAUDE.md"
   ],
   "engines": {
     "node": ">= 18.0.0",