@frequencyads/components 0.1.0

package/llms.txt

@@ -0,0 +1,182 @@
+# @frequencyads/components
+
+Mantine-based UI component library for Frequency products. Import from `@frequencyads/components`.
+Requires `@frequencyads/brand/mantine` theme via `<MantineProvider theme={frequencyTheme}>`.
+
+## When to use these components
+
+ALWAYS prefer these over inline styles, Tailwind, or raw HTML. If a component exists here, use it.
+For anything not listed, use Mantine primitives (Paper, Card, SimpleGrid, Table, Group, Stack, Text, Title, Button, ActionIcon, etc.) — never raw HTML with Tailwind classes.
+
+## Components
+
+### AnimatedCounter
+Scroll-triggered animated number counter. Counts from 0 to target with easing. Auto-formats large numbers with K suffix.
+```tsx
+import { AnimatedCounter } from '@frequencyads/components';
+<AnimatedCounter value={2500} suffix="+" size="xl" fw={700} />
+<AnimatedCounter value={98.7} suffix="%" decimals={1} duration={3000} />
+<AnimatedCounter value={1250000} prefix="$" abbreviate />
+```
+Props: value, suffix, prefix, duration (ms), threshold (0-1), abbreviate (K suffix for 1000+), decimals, plus all Mantine TextProps
+
+### ExpandableCard
+Auto-expanding card that reveals more content when scrolled into view. Framer Motion animations with icon badge.
+```tsx
+import { ExpandableCard } from '@frequencyads/components';
+<ExpandableCard title="Show Management" description="Manage your catalog." expandedContent="Full details here..." icon={IconRadio} color="blue" />
+```
+Props: title, description, expandedContent (string|ReactNode), icon, color (MantineColor), iconSize, collapsedHeight (px), threshold, delay (ms), expanded (controlled), onExpandedChange
+
+### SplitSection
+Two-column marketing section with heading area (45%) and content area (55%). Supports two-tone titles, badges, CTAs, sticky heading, and reversed layout. Stacks on mobile.
+```tsx
+import { SplitSection } from '@frequencyads/components';
+<SplitSection preTitle="Complex Campaigns." title="Simplified" titleColor="blue" description="Automate your workflow." stickyHeading>
+  <Stack gap="md">{/* cards, grids, etc. */}</Stack>
+</SplitSection>
+<SplitSection badge="New" subtitle="Premium Publisher Network" preTitle="Where Premium Meets" title="Performance" titleColor="violet" actions={<Button>Learn more</Button>}>
+  <SimpleGrid cols={2}>{/* feature cards */}</SimpleGrid>
+</SplitSection>
+```
+Props: badge, badgeColor, subtitle, preTitle, title, titleColor, description, actions (ReactNode), heading (ReactNode — overrides structured props), children, stickyHeading, py, reversed, id, className
+
+### Hero
+Full-screen hero section with logo or gradient text variant, optional video background and waveform.
+```tsx
+import { Hero } from '@frequencyads/components';
+<Hero variant="logo" tagline="Audio teams use Frequency to work faster." />
+<Hero variant="text" heading="Frequency" gradient="frequencyAlive" shimmer />
+```
+Props: variant ("logo"|"text"), heading, tagline, logoSrc, gradient (GradientName), shimmer, primaryAction ({label,href}), secondaryAction, backgroundVideoSrc, showWaveform
+
+### AudioPlayer
+Full audio player with play/pause, time display, waveform visualization, volume slider, and download button.
+```tsx
+import { AudioPlayer } from '@frequencyads/components';
+<AudioPlayer src="/audio/demo.mp3" filename="demo.mp3" />
+```
+Props: src, filename, playButtonColor, playButtonSize, waveColor, progressColor, waveHeight, barWidth, barGap, showVolume, showDownload
+
+### MiniAudioPlayer
+Compact inline audio player with play button and mini waveform. Three sizes.
+```tsx
+import { MiniAudioPlayer } from '@frequencyads/components';
+<MiniAudioPlayer audioUrl="/audio/clip.mp3" size="compact" />
+```
+Props: audioUrl, size ("mini"|"small"|"compact"), waveColor, progressColor, onPlay, onPause
+
+### AudioWaveform
+Standalone mock waveform visualization with seek support. Used internally by AudioPlayer and MiniAudioPlayer.
+```tsx
+import { AudioWaveform } from '@frequencyads/components';
+<AudioWaveform audioRef={audioRef} onSeek={handleSeek} height={60} />
+```
+Props: audioRef, currentTime, onSeek, loading, waveColor, progressColor, height, barWidth, barGap
+
+### SpeedDial
+Floating action button that expands to show multiple actions. Like MUI SpeedDial but built with Mantine.
+```tsx
+import { SpeedDial } from '@frequencyads/components';
+<SpeedDial actions={[{ icon: <IconCopy size={18} />, label: "Copy", onClick: handleCopy }]} direction="up" />
+```
+Props: actions ({icon,label,onClick}[]), icon, openIcon, direction ("up"|"down"|"left"|"right"), color, size, open, onOpenChange
+
+### PrincipleCard
+Accent-bordered card for displaying design principles, values, or guidelines with optional do/don't hints.
+```tsx
+import { PrincipleCard } from '@frequencyads/components';
+<PrincipleCard accentColor="#169BDE" title="Clarity Over Complexity" description="Every element should serve a purpose." doHint="Clean layouts" dontHint="Visual clutter" />
+```
+Props: accentColor, title, description, doHint, dontHint
+
+### DosDonts
+Side-by-side Do/Don't comparison cards with green/red coloring and check/X icons.
+```tsx
+import { DosDonts } from '@frequencyads/components';
+<DosDonts items={[{ do: "Create better audio ads, faster.", dont: "Leverage our cutting-edge solution..." }]} />
+```
+Props: items ({do,dont}[])
+
+### HintBadge
+Green "Do" or red "Don't" pill badge. Used inside PrincipleCard but available standalone.
+```tsx
+import { HintBadge } from '@frequencyads/components';
+<HintBadge variant="do">Clean layouts</HintBadge>
+<HintBadge variant="dont">Visual clutter</HintBadge>
+```
+Props: variant ("do"|"dont"), children
+
+### ColorSwatch
+Color preview card with hex label and click-to-copy.
+```tsx
+import { ColorSwatch } from '@frequencyads/components';
+<ColorSwatch name="Blue" hex="#169BDE" label="Primary" />
+```
+Props: name, hex, label
+
+### ColorPalette
+10-shade color grid for a single color scale. Click any shade to copy hex.
+```tsx
+import { ColorPalette } from '@frequencyads/components';
+import { blue } from '@frequencyads/brand/colors';
+<ColorPalette name="blue" shades={[...blue]} mainIndex={5} />
+```
+Props: name, shades (string[]), mainIndex
+
+### GradientSwatch
+Gradient preview card with CSS string copy.
+```tsx
+import { GradientSwatch } from '@frequencyads/components';
+import { gradients } from '@frequencyads/brand/colors';
+<GradientSwatch name="Frequency Alive" colors={[gradients.frequencyAlive.from, gradients.frequencyAlive.to]} description="Primary brand gradient" />
+```
+Props: name, colors ([from,to]), description
+
+### CodeBlock
+Code viewer with filename label and copy button. For displaying code snippets.
+```tsx
+import { CodeBlock } from '@frequencyads/components';
+<CodeBlock filename="install.sh" code="npm install @frequencyads/brand" height={60} />
+```
+Props: filename, code, height
+
+### Copyable
+Click-to-copy wrapper. Shows toast notification on copy. Wrap any element.
+```tsx
+import { Copyable } from '@frequencyads/components';
+<Copyable value="#169BDE"><span>Click me to copy</span></Copyable>
+```
+Props: value, children
+
+### FadeInSection
+Scroll-triggered fade-in animation wrapper using IntersectionObserver.
+```tsx
+import { FadeInSection } from '@frequencyads/components';
+<FadeInSection delay={200}><Card>...</Card></FadeInSection>
+```
+Props: children, delay (ms), threshold (0-1), plus all Mantine BoxProps
+
+### AnimatedWaveform
+SVG waveform with animated gradient bars (Framer Motion). Used as decoration in Hero.
+```tsx
+import { AnimatedWaveform } from '@frequencyads/components';
+<AnimatedWaveform barCount={140} duration={3} repeatDelay={3} />
+```
+Props: barCount, duration, repeatDelay
+
+### FrequencyWave
+Canvas-based animated wave decoration with idle/active/pulsing states. Brand gradient colors.
+```tsx
+import { FrequencyWave } from '@frequencyads/components';
+<FrequencyWave isActive={false} height={60} />
+```
+Props: isActive, height
+
+### VideoBackground
+Full-bleed video background element. Used internally by Hero.
+```tsx
+import { VideoBackground } from '@frequencyads/components';
+<VideoBackground src="/video/bg.mp4" opacity={0.3} />
+```
+Props: src, opacity

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@frequencyads/components",
+  "version": "0.1.0",
+  "description": "Shared Mantine UI components for Frequency apps",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@mantine/core": "^7",
+    "@mantine/hooks": "^7",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "dependencies": {
+    "@frequencyads/brand": "^1.1.0",
+    "@tabler/icons-react": "^3",
+    "framer-motion": "^11"
+  },
+  "devDependencies": {
+    "@frequencyads/eslint-config": "^0.1.0",
+    "@frequencyads/tsconfig": "^0.1.0",
+    "@mantine/core": "^7",
+    "@mantine/hooks": "^7",
+    "@types/react": "^19",
+    "postcss-preset-mantine": "^1",
+    "postcss-simple-vars": "^7",
+    "tsup": "^8",
+    "typescript": "^5"
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}