@thecb/components 11.5.2 → 11.6.0

package/README.md

@@ -1,6 +1,6 @@
 # CityBase Components
 
-This library contains CityBase React components for use across all current and future CB applications (NFE, RMD, Kiosk, POS).
+This library contains CityBase React components for use across all current and future CB applications (NFE, RMD, POS).
 
 <!-- TOC -->
 
@@ -177,6 +177,16 @@ To import multiple components
 
 - `import { ButtonWithAction, LoginForm, Box, Stack, Cluster } from "@thecb/components";`
 
+### AI Documentation (`ai-docs/`)
+
+The `ai-docs/` directory contains documentation specifically tailored for AI assistants:
+
+- **Architecture Overview** (`architecture.md`): System design patterns, atomic design principles, theming architecture, and build system information
+- **Component Structure** (`components.md`): Component hierarchy, layout primitives, form components, and usage patterns
+- **Coding Conventions** (`conventions.md`): Development standards, naming conventions, and best practices for component development
+- **Figma MCP Integration** (`figma-mcp.md`): Guidelines for using Figma MCP tools to generate components from designs
+- **Integration Guidelines** (`integration-guidelines.md`): Step-by-step process for implementing @thecb/components in applications, including required examination of source code, TypeScript definitions, and usage patterns
+
 ```
 
 ```

package/ai-docs/architecture.md

@@ -0,0 +1,71 @@
+# Architecture Overview
+
+## Project Type
+
+`@thecb/components` - React component library for CityBase apps (NFE, RMD, POS)
+
+## Core Patterns
+
+### Atomic Design
+
+- **Atoms**: Layout primitives, form controls, display components
+- **Molecules**: Composed components (forms, modals, navigation)
+- **Templates**: Page-level layouts
+
+### Layout-First Architecture
+
+- **Composition**: All components built using layout primitives (Box, Stack, Cluster, Center, Grid)
+- **Prop-Based Styling**: Styling via props, not custom CSS
+- **Layout Primitives**: Foundation atoms for all other components
+
+### Theming System
+
+- **FCS Integration**: Dynamic theming via Frontend Configuration Service
+- **Fallback Values**: `.theme.js` files with defaults
+- **Variants**: primary, secondary, danger, ghost, link
+- **Theme Context**: React Context + styled-components ThemeProvider
+- **Client Customization**: Per-client theme overrides
+
+### Build System
+
+- **Rollup**: Bundler outputting CommonJS + ES modules
+- **Tree Shaking**: ES module support
+- **TypeScript**: Declaration file generation
+- **Storybook**: Development environment
+
+## Component Philosophy
+
+- **Stateless**: Minimal internal state
+- **Reusable**: Multi-application usage only
+- **Separation**: Business logic in consuming apps
+- **Composable**: Built from smaller atoms
+
+## Technical Stack
+
+- **React**: Core framework
+- **Styled Components**: CSS-in-JS styling
+- **Redux-Freeform**: Form state management
+- **TypeScript**: Type definitions
+- **Rollup**: Build system
+- **Storybook**: Documentation
+
+## Directory Structure
+
+```
+src/
+├── components/     # Atoms, molecules, templates
+├── constants/      # Colors, styles, patterns
+├── hooks/         # React hooks
+├── types/         # TypeScript definitions
+├── util/          # Helper functions
+└── index.js      # Main export
+```
+
+## Key Decisions
+
+- **CSS-in-JS**: No global CSS conflicts
+- **Layout Primitives**: Standardized spacing/positioning
+- **Theme Integration**: Dynamic configuration support
+- **Semantic Versioning**: Manual version management
+- **ES Modules**: Tree-shaking enabled
+- **Accessibility**: ARIA support built-in

package/ai-docs/components.md

@@ -0,0 +1,167 @@
+# Component Structure
+
+## Atomic Design Hierarchy
+
+### Atoms (`src/components/atoms/`)
+
+#### Layout Primitives
+
+Core atoms for all other components:
+
+- **Box**: Container with padding, borders, styling
+- **Stack**: Vertical/horizontal spacing with margins
+- **Cluster**: Wrapping elements with consistent gaps
+- **Center**: Horizontal centering with gutters
+- **Grid**: Responsive auto-fill grid layout
+- **Cover**: Full viewport with header/footer
+- **Frame**: Aspect ratio container
+- **Switcher**: Responsive horizontal/vertical layout
+
+#### Form Components
+
+- **FormInput**: Complete input with validation (see source code and TypeScript definitions)
+- **FormSelect**: Dropdown with form integration (see source code and TypeScript definitions)
+- **Dropdown**: Accessible combobox with search (see source code and TypeScript definitions)
+- **ButtonWithAction**: Primary button (variants: primary, secondary, danger)
+- **Checkbox**: Form checkbox with label
+- **ToggleSwitch**: On/off toggle
+- **TypeaheadInput**: Autocomplete input
+
+#### Display Components
+
+- **Table**: 6-component table system (see source code and TypeScript definitions)
+- **Alert**: Notifications (variants: info, warning, error, success)
+- **Badge**: Status indicators
+- **Card**: Content containers
+- **Text**: Typography component with variants
+- **Title**: Responsive headings
+- **Loading**: Spinners and skeletons
+
+#### Navigation Components
+
+- **Breadcrumb**: Navigation breadcrumbs
+- **NavTabs**: Tab navigation
+- **Search**: Search input
+
+### Molecules (Composed Components)
+
+Located in `src/components/molecules/` - These combine multiple atoms to create more complex functionality.
+
+#### Form Molecules
+
+- **AddressForm**: Complete address input form
+- **ChangePasswordForm**: Password change form
+- **EditNameForm**: Name editing form
+- **EmailForm**: Email input form
+- **ForgotPasswordForm**: Password reset request form
+- **LoginForm**: User login form
+- **PhoneForm**: Phone number input form
+- **RegistrationForm**: User registration form
+- **ResetPasswordForm**: Password reset form
+- **ResetConfirmationForm**: Password reset confirmation
+- **ResetPasswordSuccess**: Success state for password reset
+
+#### Payment Molecules
+
+- **PaymentDetails**: Payment information display
+- **PaymentFormACH**: ACH payment form
+- **PaymentFormCard**: Credit card payment form
+- **PaymentButtonBar**: Payment action buttons
+- **PartialAmountForm**: Partial payment amount form
+
+#### UI Molecules
+
+- **Banner**: Page banner component
+- **CollapsibleSection**: Expandable content section
+- **Copyable**: Copy-to-clipboard component
+- **EditableList**: List with inline editing
+- **EditableTable**: Table with inline editing
+- **HeroImage**: Hero image with overlay content
+- **IdleModal**: Session timeout modal
+- **LinkCard**: Card with link functionality
+- **Modal**: Modal dialog component
+- **Module**: Content section with title
+- **Obligation**: User account display component
+- **Pagination**: Page navigation
+- **Popover**: Popup content
+- **PopupMenu**: Context menu
+- **RadioGroup**: Group of radio buttons
+- **RadioSection**: Radio button section
+- **Tabs**: Tabbed interface
+- **TabSidebar**: Sidebar with tabs
+- **ToastNotification**: Toast notification
+- **WelcomeModule**: Welcome message component
+
+#### Navigation Molecules
+
+- **FooterWithSubfooter**: Footer with sub-footer
+- **NavMenu**: Navigation menu
+- **TabNavigation**: Tab-based navigation
+- **TabSidebar**: Sidebar with tab navigation
+
+#### Specialized Molecules
+
+- **ContactCard**: Contact information display
+- **MultipleSelectFilter**: Multi-select filter component
+- **PeriscopeDashboardIframe**: Dashboard iframe embed
+- **RegistrationBanner**: Registration promotion banner
+- **TermsAndConditions**: Terms and conditions display
+- **TermsAndConditionsModal**: Terms modal
+- **Timeout**: Session timeout component
+- **TurnstileWidget**: Cloudflare Turnstile widget
+- **WorkflowTile**: Workflow step tile
+
+### Templates (Page Layouts)
+
+Located in `src/components/templates/` - High-level page structure components.
+
+- **CenterSingle**: Centered single column layout
+- **CenterStack**: Centered stacked layout
+- **DefaultPageTemplate**: Standard page template
+- **SidebarSingleContent**: Sidebar with single content area
+- **SidebarStackContent**: Sidebar with stacked content areas
+
+### Component Directory Structure
+
+For detailed directory structure and file organization patterns, see [Coding Conventions](./conventions.md#directory-structure).
+
+Each component follows a consistent directory structure:
+
+```
+component-name/
+├── ComponentName.js          # Main component file
+├── ComponentName.styled.js   # Styled components
+├── ComponentName.theme.js    # Theme configuration
+├── ComponentName.stories.js  # Storybook stories
+├── ComponentName.mdx         # Documentation
+└── index.js                  # Export file
+```
+
+## Component Variants
+
+Most components support variants for different use cases:
+
+- **ButtonWithAction**: primary, secondary, danger, ghost, link
+- **Alert**: info, warning, error, success
+- **Badge**: danger, neutral, success, warning
+- **Card**: default, elevated, outlined
+
+## Theme Integration
+
+> **Note**: For comprehensive theming system details, see [Architecture Overview](./architecture.md#theming-system).
+
+Each component includes:
+
+- **Theme File**: `.theme.js` with fallback values
+- **Theme Props**: `themeValues`, `variant`, `metadata` props
+- **Styled Components**: Theme-aware styling
+- **FCS Integration**: Dynamic theming via Frontend Configuration Service
+
+## Component Exports
+
+Components are exported through index files:
+
+- `src/components/atoms/index.js` - All atom exports
+- `src/components/molecules/index.js` - All molecule exports
+- `src/components/templates/index.js` - All template exports
+- `src/index.js` - Main library export

package/ai-docs/conventions.md

@@ -0,0 +1,162 @@
+# Coding Conventions
+
+## File Structure
+
+### Component Files (Required)
+
+- `ComponentName.js` - Main component (PascalCase)
+- `ComponentName.theme.js` - Theme configuration with fallbacks
+- `ComponentName.stories.js` - Storybook stories
+- `index.js` - Export file
+- `index.d.ts` - TypeScript definitions
+- Optional: `ComponentName.styled.js`, `ComponentName.mdx`
+
+### Directory Naming
+
+- Component directories: `kebab-case` (e.g., `button-with-action/`)
+- Files: `camelCase.js` for utilities, constants
+
+## Component Structure Pattern
+
+```javascript
+import React, { forwardRef } from "react";
+import { themeComponent } from "../../../util/themeUtils";
+import { fallbackValues } from "./ComponentName.theme";
+import { Box, Stack } from "../../atoms/layouts";
+
+const ComponentName = forwardRef(
+  ({ variant = "default", children, ...props }, ref) => {
+    return (
+      <Box ref={ref} {...props}>
+        {children}
+      </Box>
+    );
+  }
+);
+
+export default themeComponent(
+  ComponentName,
+  "ComponentName",
+  fallbackValues,
+  "default"
+);
+```
+
+### Required Imports Order
+
+1. React imports: `import React, { forwardRef } from "react"`
+2. Layout imports: `import { Box, Stack } from "../../atoms/layouts"`
+3. Utilities: `import { themeComponent } from "../../../util/themeUtils"`
+4. Constants: `import { PRIMARY_BLUE } from "../../../constants/colors"`
+5. Local: `import { fallbackValues } from "./ComponentName.theme"`
+
+## Theming Pattern
+
+```javascript
+// ComponentName.theme.js
+export const fallbackValues = {
+  backgroundColor: {
+    primary: "#0074D9",
+    secondary: "#6C757D",
+    danger: "#DC3545"
+  },
+  padding: { small: "0.5rem", medium: "1rem", large: "1.5rem" },
+  fontSize: "1rem"
+};
+```
+
+### Styled Components (when needed)
+
+```javascript
+// ComponentName.styled.js
+import styled from "styled-components";
+
+export const ComponentNameWrapper = styled.div`
+  padding: ${props => props.padding || "1rem"};
+  background-color: ${props => props.themeValues?.backgroundColor || "white"};
+`;
+```
+
+## Component Props Convention
+
+### Base Props (Standard)
+
+- `variant` - Component variant (primary, secondary, danger, ghost, link)
+- `themeValues` - Theme overrides object
+- `metadata` - Component metadata
+- `children` - React children
+- Layout props: `padding`, `margin`, `width`, `height`
+- HTML props: Spread remaining props to DOM elements
+
+## TypeScript Pattern
+
+```typescript
+// index.d.ts
+import React from "react";
+import Expand from "../../../util/expand";
+
+export interface ComponentNameProps {
+  variant?: "primary" | "secondary" | "danger";
+  children?: React.ReactNode;
+  onClick?: () => void;
+}
+
+export const ComponentName: React.FC<Expand<ComponentNameProps> &
+  React.HTMLAttributes<HTMLElement>>;
+```
+
+## Storybook Stories Pattern
+
+```javascript
+// ComponentName.stories.js
+import ComponentName from "./ComponentName";
+
+export default {
+  title: "Atoms/ComponentName",
+  component: ComponentName,
+  argTypes: {
+    variant: {
+      control: { type: "select" },
+      options: ["primary", "secondary", "danger"]
+    }
+  }
+};
+
+export const Primary = {
+  args: { variant: "primary", children: "Example" }
+};
+```
+
+## Development Standards
+
+### Code Style
+
+- Use modern JS (ES6+), functional components, destructuring
+- Use `forwardRef` for ref passing
+- Use `React.memo` for performance optimization
+- Follow atomic design with layout primitives (Box, Stack, Cluster)
+
+### Git Conventions
+
+- Commits: `type(scope): description` (feat, fix, docs, style, refactor, test, chore)
+- Branches: `feature/component-name`, `fix/issue-description`
+
+### Testing & Quality
+
+- Storybook stories for all variants
+- Visual testing with Chromatic
+- Accessibility testing with axe-playwright
+- Cross-application integration testing
+
+### Performance
+
+- ES modules for tree shaking
+- Minimize external dependencies
+- Use layout primitives instead of custom CSS
+
+### Accessibility Requirements
+
+- Proper ARIA labels and roles
+- Keyboard navigation support
+- Semantic HTML elements
+- Screen reader compatibility

package/ai-docs/figma-mcp.md

@@ -0,0 +1,66 @@
+# AI-Optimized Figma Integration Guide
+
+**Quick Reference**: Essential workflow and patterns for converting Figma designs to CityBase Components.
+
+## Mandatory Workflow
+
+1. **`get_code`** → structured component representation
+2. **`get_screenshot`** → visual reference
+3. **Download assets** → icons, images if needed
+4. **Translate** → project conventions (layout primitives, theme tokens)
+5. **Validate** → 1:1 visual parity with Figma
+
+## Translation Rules
+
+### Code Conversion
+
+- **Figma MCP output** = design reference only (ignore Tailwind classes)
+- **Use layout primitives**: Box, Stack, Cluster (not custom CSS)
+- **Map to existing components**: Text, Title, Detail, Button
+- **Apply theme tokens**: colors, typography, spacing from constants
+
+### Design System Integration
+
+```javascript
+// Colors
+import { COLORS, ALERT_COLORS } from 'src/constants/colors.js';
+
+// Typography
+<Text variant="p"> // Use Text component variants
+<Title level={2}> // Use Title for headings
+
+// Spacing
+<Box padding={SPACING.lg}> // Use SPACING constants
+<Stack gap={SPACING.md}> // Apply through layout primitives
+```
+
+## Implementation Checklist
+
+**Component Creation**:
+
+- [ ] Main component with `themeComponent` wrapper
+- [ ] `.theme.js` with fallback values
+- [ ] `.stories.js` with all variants
+- [ ] `index.d.ts` TypeScript definitions
+- [ ] Export in appropriate index files
+
+**Visual Validation**:
+
+- [ ] 1:1 parity with Figma screenshot
+- [ ] All interactive states work
+- [ ] Responsive behavior correct
+- [ ] Theme variants applied
+
+**Icons**:
+
+- [ ] SVG components in `src/components/atoms/icons/`
+- [ ] Use theme colors directly in SVG
+- [ ] Name as `[Descriptive]Icon`
+- [ ] Export from icons index
+
+## Quick Reference Locations
+
+**Constants**: `src/constants/colors.js`, `src/constants/style_constants.js`  
+**Layout Primitives**: `src/components/atoms/layouts/`  
+**Theme Utils**: `src/util/themeUtils.js`  
+**Component Pattern**: See source code and TypeScript definitions in component directories

package/ai-docs/integration-guidelines.md

@@ -0,0 +1,142 @@
+# @thecb/components Integration Guidelines
+
+## Component Documentation
+
+For detailed component implementation guidance, refer to the source code and TypeScript definitions:
+
+- **Layout primitives**: `src/components/atoms/layouts/` - Box, Stack, Cluster, Center, Grid
+- **Form components**: `src/components/atoms/form-layouts/`, `src/components/atoms/form-select/`, `src/components/atoms/dropdown/`
+- **Display components**: `src/components/atoms/table/`, `src/components/molecules/modal/`
+
+## Implementation Process
+
+1. **Examine Source Code**: Review component implementation in source files
+2. **Verify Types**: Confirm TypeScript interface in `index.d.ts`
+3. **Check Themes**: Review `.theme.js` if component uses theming
+4. **Follow Patterns**: Use documented usage patterns and examples
+
+## Architecture Overview
+
+```
+@thecb/components/
+├── atoms/
+│   ├── layouts/           # Box, Stack, Cluster, Center, Grid
+│   ├── form-layouts/      # FormInput
+│   ├── form-select/       # FormSelect
+│   ├── dropdown/          # Dropdown
+│   └── table/            # Table system
+├── molecules/
+│   └── modal/            # Modal
+└── templates/            # Page layouts
+```
+
+## Core Patterns
+
+### Layout Primitives (No Theming)
+
+- Box: Generic container with styling props
+- Stack: Vertical/horizontal spacing with flexbox
+- Cluster: Wrapping elements with consistent gaps
+- Center: Horizontal centering with gutters
+- Grid: Responsive auto-fill grid layout
+
+### Form Components (With Theming)
+
+- FormInput: Complete input with validation
+- FormSelect: Dropdown with form integration
+- Dropdown: Accessible combobox with search
+
+### Display Components
+
+- Table: 6-component table system
+- Modal: Accessible dialog with versions
+
+## Integration Rules
+
+### Props
+
+- All components accept `extraStyles` for custom CSS
+- Themed components accept `themeValues` object
+- Layout components use `children` prop
+- Event handlers follow React naming (`onClick`, `onSelect`)
+
+### TypeScript
+
+- Interfaces use `Expand` utility for prop merging
+- All components extend `React.HTMLAttributes<HTMLElement>`
+- Optional props use `?:` syntax
+
+### Theming
+
+- Components using `themeComponent` wrapper have fallback values
+- Theme files define color/style mappings
+- Variants: "default", "primary", "secondary", "danger"
+
+### Accessibility
+
+- Form components include ARIA labeling
+- Dropdown/Modal use focus management
+- Screen reader support via semantic HTML
+
+### Import Patterns
+
+```javascript
+// Named imports
+import { Box, Stack, FormInput } from "@thecb/components";
+
+// Table system
+import {
+  Table,
+  TableHead,
+  TableBody,
+  TableRow,
+  TableHeading,
+  TableCell
+} from "@thecb/components";
+```
+
+## Form Field Integration
+
+Form components expect field objects with:
+
+- `rawValue`: Current value
+- `hasErrors`: Boolean error state
+- `errors`: Array of error keys
+- `dirty`: Boolean touched state
+
+Field actions expect:
+
+- `set(value)`: Update field value
+
+## Common Anti-patterns
+
+- Don't use Box for complex layouts (use Stack/Cluster/Grid)
+- Don't bypass form field integration in FormInput/FormSelect
+- Don't ignore accessibility props in interactive components
+- Don't use layout primitives without understanding spacing behavior
+
+## Quick Reference
+
+| Component | Purpose    | Key Props                 | Theming |
+| --------- | ---------- | ------------------------- | ------- |
+| Box       | Container  | `padding`, `as`, `srOnly` | No      |
+| Stack     | Spacing    | `childGap`, `direction`   | No      |
+| FormInput | Text input | `field`, `fieldActions`   | Yes     |
+| Dropdown  | Select     | `options`, `onSelect`     | Yes     |
+| Modal     | Dialog     | `modalOpen`, `hideModal`  | No      |
+
+## Example Implementation
+
+```javascript
+// Examine source code and TypeScript definitions first, then implement:
+import { FormInput } from "@thecb/components";
+
+<FormInput
+  field={emailField}
+  fieldActions={emailFieldActions}
+  labelTextWhenNoError="Email Address"
+  type="email"
+  isRequired={true}
+  errorMessages={{ required: "Email is required" }}
+/>;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecb/components",
-  "version": "11.5.2",
+  "version": "11.6.0",
   "description": "Common lib for CityBase react components",
   "main": "dist/index.cjs.js",
   "typings": "dist/index.d.ts",
@@ -22,7 +22,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "ai-docs"
   ],
   "homepage": "https://github.com/CityBaseInc/cb-components#readme",
   "devDependencies": {