@affinda/react 0.0.11 → 0.0.13

package/README.md

@@ -5,11 +5,65 @@ React components for Affinda UI - built on web components with Stencil.
 ## Installation
 
 ```bash
-npm install @affinda/react
+npm install @affinda/react @affinda/css
 # or
-pnpm add @affinda/react
+pnpm add @affinda/react @affinda/css
 ```
 
+## Quick Start
+
+### 1. Import Styles and Initialize Components
+
+```tsx
+// In your main.tsx or index.tsx
+import '@affinda/css'; // Loads reset, fonts, tokens, base styles
+import { defineCustomElements } from '@affinda/wc/loader';
+
+// Initialize web components
+defineCustomElements();
+```
+
+### 2. Use Components
+
+```tsx
+import { Button, Navbar, Card } from '@affinda/react';
+
+function App() {
+  return (
+    <div>
+      <Navbar>
+        <Button variant="primary">Get Started</Button>
+      </Navbar>
+    </div>
+  );
+}
+```
+
+### 3. Load NeuSans Font (Recommended)
+
+Affinda components use the **NeuSans** font family. To get the authentic Affinda look:
+
+1. Obtain NeuSans font files (contact Affinda or your design team)
+2. Add @font-face declarations in your global CSS:
+
+```css
+@font-face {
+  font-family: 'NeuSans';
+  font-style: normal;
+  font-weight: 500; /* Book weight for headings */
+  src: url('/fonts/NeuSans-Book.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'NeuSans';
+  font-style: normal;
+  font-weight: 400; /* Regular weight */
+  src: url('/fonts/NeuSans-Regular.woff2') format('woff2');
+}
+```
+
+**Don't have NeuSans?** The components will gracefully fall back to Inter and system fonts.
+
 ## Usage
 
 ### Import Components
@@ -34,10 +88,230 @@ import { Button, Heading, TypographyLockup } from '@affinda/react';
 - **TypographyLockup** / AfTypographyLockup - Composite heading + text + button layouts
 - **Container** / AfContainer - Layout containers with max-width
 - **AspectRatio** / AfAspectRatio - Maintain aspect ratios for media
+- **Card** / AfCard - Content cards with optional borders and shadows
 - **ColorSwatch** / AfColorSwatch - Display color swatches
 - **Logo** / AfLogo - Affinda logo component
 - **Navbar** / AfNavbar - Navigation bar
 - **NavItem** / AfNavItem - Navigation items
+- **Testimonial** / AfTestimonial - Customer testimonials with background images, stats, and quotes
+- **TestimonialCarousel** / AfTestimonialCarousel - Carousel for sliding between multiple testimonials
+- **TestimonialStat** / AfTestimonialStat - Individual statistics within testimonials
+
+## Component Guide
+
+### When to Use Each Component
+
+#### Layout & Structure
+
+**Container**
+- Use for all page sections to maintain consistent max-width and horizontal padding
+- Creates responsive layouts that don't span the full viewport on large screens
+- Best practice: Wrap each major section of your page in a Container
+
+```tsx
+<Container>
+  <Heading level="2">Section Title</Heading>
+  <Text>Section content goes here...</Text>
+</Container>
+```
+
+**AspectRatio**
+- Maintain consistent dimensions for images, videos, or media
+- Prevents layout shift during content loading
+- Common ratios: `16/9` (video), `1/1` (square), `4/3` (legacy video)
+
+```tsx
+<AspectRatio ratio="16/9">
+  <img src="video-thumbnail.jpg" alt="Preview" />
+</AspectRatio>
+```
+
+**Card**
+- Group related content with visual separation
+- Use for feature highlights, product listings, or content previews
+- Supports borders and elevation for depth
+
+```tsx
+<Card>
+  <Heading level="3">Feature Title</Heading>
+  <Text>Feature description...</Text>
+</Card>
+```
+
+#### Typography
+
+**Heading**
+- Use semantic heading levels (1-6) for SEO and accessibility
+- Level 1: Page title (use once per page)
+- Level 2: Major sections
+- Level 3-4: Subsections
+- Never skip heading levels
+
+```tsx
+<Heading level="1">Page Title</Heading>
+<Heading level="2">Section Title</Heading>
+<Heading level="3">Subsection</Heading>
+```
+
+**Text**
+- Use for all body text, descriptions, and paragraphs
+- Variants: `default`, `small`, `large`
+- Automatically uses NeuSans font
+
+```tsx
+<Text variant="large">Introductory paragraph with emphasis</Text>
+<Text>Standard body text</Text>
+<Text variant="small">Fine print or captions</Text>
+```
+
+**TypographyLockup**
+- Composite component for hero sections and major content blocks
+- Automatically handles heading + description + buttons layout
+- Supports different breakpoints and alignments
+- Use for: Hero sections, feature highlights, CTAs
+
+```tsx
+<TypographyLockup
+  headingSize={1}
+  textAlignment="center"
+  buttonAlignment="horizontal"
+>
+  <Heading level="1">Automate Your Workflow</Heading>
+  <Text slot="description">Extract data from documents in seconds</Text>
+  <div slot="buttons">
+    <Button variant="primary">Get Started</Button>
+    <Button variant="secondary">Learn More</Button>
+  </div>
+</TypographyLockup>
+```
+
+#### Buttons & Actions
+
+**Button**
+- Primary actions: Use `variant="primary"` (sparingly, 1-2 per screen)
+- Secondary actions: Use `variant="secondary"`
+- Sizes: `small`, `default`, `large`
+- Can include icons in left or right slots
+
+```tsx
+<Button variant="primary" size="large">Sign Up Now</Button>
+<Button variant="secondary">Learn More</Button>
+```
+
+**ButtonGroup**
+- Group related buttons with consistent spacing
+- Maintains visual hierarchy and alignment
+
+```tsx
+<ButtonGroup>
+  <Button variant="primary">Save</Button>
+  <Button variant="secondary">Cancel</Button>
+</ButtonGroup>
+```
+
+**IconButton**
+- Use for toolbar actions, navigation controls, or when space is limited
+- Always include aria-label for accessibility
+- Common uses: Close buttons, navigation arrows, menu toggles
+
+```tsx
+<IconButton variant="secondary" aria-label="Close dialog">
+  <svg>...</svg>
+</IconButton>
+```
+
+#### Navigation
+
+**Navbar**
+- Site-wide navigation header
+- Responsive design with mobile menu support
+- Include Logo in the `logo` slot
+
+```tsx
+<Navbar>
+  <Logo slot="logo" />
+  <NavItem hierarchy="primary" href="/">Home</NavItem>
+  <NavItem hierarchy="primary" href="/about">About</NavItem>
+  <NavItem hierarchy="secondary" href="/login">Log In</NavItem>
+</Navbar>
+```
+
+**NavItem**
+- Individual navigation links
+- Hierarchy: `primary` (main nav), `secondary` (utility nav)
+- Variant: Controls visual style
+
+#### Social Proof & Testimonials
+
+**Testimonial**
+- Showcase customer success stories with rich media
+- Include: background image, logo, quote, attribution, and statistics
+- Use within TestimonialCarousel for multiple testimonials
+
+```tsx
+<Testimonial
+  backgroundImage="https://example.com/background.jpg"
+  logoImage="https://example.com/company-logo.png"
+  quote="Affinda transformed our document processing workflow."
+  attribution="– Jane Doe, CEO, Company Name"
+  readMoreLink="https://example.com/case-study"
+>
+  <div slot="stats">
+    <TestimonialStat value="95%" description="reduction in processing time" />
+    <TestimonialStat value="10×" description="increase in throughput" />
+  </div>
+</Testimonial>
+```
+
+**TestimonialCarousel**
+- Automatically handles navigation between multiple testimonials
+- Includes slide animations and progress indicators
+- Navigation buttons positioned for optimal UX
+- Just wrap multiple Testimonial components
+
+```tsx
+<TestimonialCarousel>
+  <Testimonial {...testimonial1Props}>
+    <div slot="stats">...</div>
+  </Testimonial>
+  <Testimonial {...testimonial2Props}>
+    <div slot="stats">...</div>
+  </Testimonial>
+</TestimonialCarousel>
+```
+
+**TestimonialStat**
+- Display key metrics within testimonials
+- Use 2-4 stats per testimonial for best impact
+- Optional accent border for qualitative statements
+
+```tsx
+<TestimonialStat value="99%" description="accuracy rate" />
+<TestimonialStat 
+  value="" 
+  description="Reduced manual errors significantly" 
+  accentBorder={true} 
+/>
+```
+
+#### Branding
+
+**Logo**
+- Affinda logo component with consistent sizing
+- Use in Navbar and footer
+- Automatically handles light/dark variants
+
+```tsx
+<Logo />
+```
+
+**ColorSwatch**
+- Display color palettes or design tokens
+- Useful for style guides and documentation
+
+```tsx
+<ColorSwatch color="#C6D5D1" label="Mist Green" />
+```
 
 ### Icons
 

package/dist/generated/components.d.ts

@@ -13,6 +13,9 @@ import { AfIconButton as AfIconButtonElement } from "@affinda/wc/dist/components
 import { AfLogo as AfLogoElement } from "@affinda/wc/dist/components/af-logo.js";
 import { AfNavItem as AfNavItemElement } from "@affinda/wc/dist/components/af-nav-item.js";
 import { AfNavbar as AfNavbarElement } from "@affinda/wc/dist/components/af-navbar.js";
+import { AfTestimonialCarousel as AfTestimonialCarouselElement } from "@affinda/wc/dist/components/af-testimonial-carousel.js";
+import { AfTestimonialStat as AfTestimonialStatElement } from "@affinda/wc/dist/components/af-testimonial-stat.js";
+import { AfTestimonial as AfTestimonialElement } from "@affinda/wc/dist/components/af-testimonial.js";
 import { AfText as AfTextElement } from "@affinda/wc/dist/components/af-text.js";
 import { AfTypographyLockup as AfTypographyLockupElement } from "@affinda/wc/dist/components/af-typography-lockup.js";
 import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
@@ -38,6 +41,12 @@ export type AfNavItemEvents = NonNullable<unknown>;
 export declare const AfNavItem: StencilReactComponent<AfNavItemElement, AfNavItemEvents>;
 export type AfNavbarEvents = NonNullable<unknown>;
 export declare const AfNavbar: StencilReactComponent<AfNavbarElement, AfNavbarEvents>;
+export type AfTestimonialEvents = NonNullable<unknown>;
+export declare const AfTestimonial: StencilReactComponent<AfTestimonialElement, AfTestimonialEvents>;
+export type AfTestimonialCarouselEvents = NonNullable<unknown>;
+export declare const AfTestimonialCarousel: StencilReactComponent<AfTestimonialCarouselElement, AfTestimonialCarouselEvents>;
+export type AfTestimonialStatEvents = NonNullable<unknown>;
+export declare const AfTestimonialStat: StencilReactComponent<AfTestimonialStatElement, AfTestimonialStatEvents>;
 export type AfTextEvents = NonNullable<unknown>;
 export declare const AfText: StencilReactComponent<AfTextElement, AfTextEvents>;
 export type AfTypographyLockupEvents = NonNullable<unknown>;

package/dist/generated/components.js

@@ -15,6 +15,9 @@ import { AfIconButton as AfIconButtonElement, defineCustomElement as defineAfIco
 import { AfLogo as AfLogoElement, defineCustomElement as defineAfLogo } from "@affinda/wc/dist/components/af-logo.js";
 import { AfNavItem as AfNavItemElement, defineCustomElement as defineAfNavItem } from "@affinda/wc/dist/components/af-nav-item.js";
 import { AfNavbar as AfNavbarElement, defineCustomElement as defineAfNavbar } from "@affinda/wc/dist/components/af-navbar.js";
+import { AfTestimonialCarousel as AfTestimonialCarouselElement, defineCustomElement as defineAfTestimonialCarousel } from "@affinda/wc/dist/components/af-testimonial-carousel.js";
+import { AfTestimonialStat as AfTestimonialStatElement, defineCustomElement as defineAfTestimonialStat } from "@affinda/wc/dist/components/af-testimonial-stat.js";
+import { AfTestimonial as AfTestimonialElement, defineCustomElement as defineAfTestimonial } from "@affinda/wc/dist/components/af-testimonial.js";
 import { AfText as AfTextElement, defineCustomElement as defineAfText } from "@affinda/wc/dist/components/af-text.js";
 import { AfTypographyLockup as AfTypographyLockupElement, defineCustomElement as defineAfTypographyLockup } from "@affinda/wc/dist/components/af-typography-lockup.js";
 import { createComponent } from '@stencil/react-output-target/runtime';
@@ -107,6 +110,30 @@ export const AfNavbar = /*@__PURE__*/ createComponent({
     events: {},
     defineCustomElement: defineAfNavbar
 });
+export const AfTestimonial = /*@__PURE__*/ createComponent({
+    tagName: 'af-testimonial',
+    elementClass: AfTestimonialElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: {},
+    defineCustomElement: defineAfTestimonial
+});
+export const AfTestimonialCarousel = /*@__PURE__*/ createComponent({
+    tagName: 'af-testimonial-carousel',
+    elementClass: AfTestimonialCarouselElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: {},
+    defineCustomElement: defineAfTestimonialCarousel
+});
+export const AfTestimonialStat = /*@__PURE__*/ createComponent({
+    tagName: 'af-testimonial-stat',
+    elementClass: AfTestimonialStatElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: {},
+    defineCustomElement: defineAfTestimonialStat
+});
 export const AfText = /*@__PURE__*/ createComponent({
     tagName: 'af-text',
     elementClass: AfTextElement,

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export * from './generated/components.js';
-export { AfAspectRatio as AspectRatio, AfButton as Button, AfButtonGroup as ButtonGroup, AfCard as Card, AfColorSwatch as ColorSwatch, AfContainer as Container, AfHeading as Heading, AfIconButton as IconButton, AfLogo as Logo, AfNavItem as NavItem, AfNavbar as Navbar, AfText as Text, AfTypographyLockup as TypographyLockup } from './generated/components.js';
+export { AfAspectRatio as AspectRatio, AfButton as Button, AfButtonGroup as ButtonGroup, AfCard as Card, AfColorSwatch as ColorSwatch, AfContainer as Container, AfHeading as Heading, AfIconButton as IconButton, AfLogo as Logo, AfNavItem as NavItem, AfNavbar as Navbar, AfText as Text, AfTestimonial as Testimonial, AfTestimonialCarousel as TestimonialCarousel, AfTestimonialStat as TestimonialStat, AfTypographyLockup as TypographyLockup } from './generated/components.js';
 export * from '@affinda/icons/react';

package/dist/index.js

@@ -2,6 +2,6 @@
 export * from './generated/components.js';
 // Note: defineCustomElements should be imported directly from @affinda/wc/loader/index.js in your app
 // Re-export components without the 'Af' prefix for cleaner React usage
-export { AfAspectRatio as AspectRatio, AfButton as Button, AfButtonGroup as ButtonGroup, AfCard as Card, AfColorSwatch as ColorSwatch, AfContainer as Container, AfHeading as Heading, AfIconButton as IconButton, AfLogo as Logo, AfNavItem as NavItem, AfNavbar as Navbar, AfText as Text, AfTypographyLockup as TypographyLockup } from './generated/components.js';
+export { AfAspectRatio as AspectRatio, AfButton as Button, AfButtonGroup as ButtonGroup, AfCard as Card, AfColorSwatch as ColorSwatch, AfContainer as Container, AfHeading as Heading, AfIconButton as IconButton, AfLogo as Logo, AfNavItem as NavItem, AfNavbar as Navbar, AfText as Text, AfTestimonial as Testimonial, AfTestimonialCarousel as TestimonialCarousel, AfTestimonialStat as TestimonialStat, AfTypographyLockup as TypographyLockup } from './generated/components.js';
 // Re-export React icon components from icons package
 export * from '@affinda/icons/react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affinda/react",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "private": false,
   "type": "module",
   "files": ["dist", "README.md"],
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@affinda/icons": "^0.0.3",
-    "@affinda/wc": "^0.0.5",
+    "@affinda/wc": "^0.0.7",
     "@stencil/react-output-target": "^1.2.0"
   },
   "scripts": {