@thecb/components 12.0.0-beta.0 → 12.0.0-beta.1

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 -->
 
@@ -8,10 +8,9 @@ This library contains CityBase React components for use across all current and f
 - [Component styles](#component-styles)
 - [Storybook](#storybook)
   - [Storybook addons](#storybook-addons)
+  - [Storybook deployment](#storybook-deployment)
 - [Adding new components](#adding-new-components)
 - [Version bumping and publishing](#version-bumping-and-publishing)
-  - [Version bumping](#version-bumping)
-  - [Publishing new versions to NPM](#publishing-new-versions-to-npm)
 - [Consuming in your application](#consuming-in-your-application)
 
   - [Adding to existing application](#adding-to-existing-application)
@@ -43,18 +42,21 @@ The following statement will inheritly be called with `yarn`, but you can run it
 
 ## Storybook
 
-This repo uses [React Storybook](https://storybook.js.org/basics/guide-react/) for interactive component display.
-
-### Storybook addons
-
-- [Actions](https://github.com/storybooks/storybook/tree/master/addons/actions)
-- [Knobs](https://github.com/storybooks/storybook/tree/master/addons/knobs)
+This repo uses [React Storybook](https://storybook.js.org/basics/guide-react/) v8 for interactive component display.
 
 Please include new component stories as this library will also be a sandbox.
 
 - `yarn storybook`
 - open browser to localhost:9001
 
+### Storybook addons
+
+The repo uses all of the standard addons that come with Storybook v8, including the box model visualizer, measuring tool, and themes. The themes are currently static themes derived from FCS output. For the time being, when changes are made to themes in FCS, those changes need to be replicated inside of the `.storybook/themes/` directory in order for component stories to pick up on them. Ideally in the future a script will dynamically pull FCS themes from UAT.
+
+### Storybook deployment
+
+Storybook is deployed to GitHub Pages via a workflow action. This action will run on pushes to the master branch. When new PRs are merged to master the action should run on the merge commit and update the deployed version of Storybook. The deployed version lives here: [GH Pages Storybook](https://citybaseinc.github.io/cb-components/). The code for this action lives in `.github/workflows/deploy-github-pages.yml`.
+
 ## Adding new components
 
 - New components may be added to this library via pull request. Only components that are currently used in, or expected to be used in, more than one CB frontend should be present in this library. Very niche application specific components should be kept in the `components/atoms` and `components/molecules` directory of their parent application.
@@ -100,9 +102,15 @@ export * from "./button-with-action";
 
 ## Version bumping and publishing
 
-### Version bumping and Publishing to NPM
+Publishing to NPM is automated. When a PR is merged to master, the package will automatically be built and published to NPM using the version specified in `package.json`. **Developers no longer need to manually run `yarn build && yarn publish`.**
 
-- Authors of PRs are responsible for bumping the version of the package prior to merging an approved PR to master. Once your pending PR has been approved, before merging to master, run `yarn build && yarn publish` in the main directory to create and publish a new build to NPM. This step should happen immediately before you merge your PR to master, to minimize conflicts between built versions.
+### How it works
+
+1. Before merging your PR, bump the version in `package.json` to an appropriate new version following semantic versioning (see below).
+2. Ensure the version you set has **not already been published** to NPM. If you merge a PR with a version that has already been published, the automated publish will fail and you will need to create a follow-up PR that bumps the version to an unpublished one.
+3. Merge your PR to master. The CI pipeline will automatically build and publish the new version.
+
+### Semantic versioning
 
 - CB Components follows semantic versioning practices, which divides version upgrades into three categories: "Patch" (e.g., `6.0.1` -> `6.0.2`), "Minor" (e.g., `6.0.2` -> `6.1.0`), and "Major" (e.g., `6.1.0` -> `7.0.0`)
 
@@ -173,6 +181,20 @@ 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
+
 ```
 
 ```
+
+### Publishing Storybook to GitHub Pages
+
+This is a test to see if the GH Actions publishing workflow is functional.

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" }}
+/>;
+```