@pamfilico/uicomponents

A collection of reusable UI components for Material UI and other frameworks.

Installation

``bash
npm install @pamfilico/uicomponents
`

Quick Start

`tsx
import { AuthButtonVariant1, HeroSectionVariant1 } from "@pamfilico/uicomponents";
// Or use subpath imports for specific categories
import { AuthButtonVariant1 } from "@pamfilico/uicomponents/material/auth";
import { HeroSectionVariant1 } from "@pamfilico/uicomponents/material/hero";

function App() {
return (
<>
onLogin={() => console.log("Login clicked")}
onSignup={() => console.log("Signup clicked")}
/>
title="Welcome to Our Platform"
subtitle="Build amazing things"
/>

);
}
`

Components

$3

Located at @pamfilico/uicomponents/material/auth

#### AuthButtonVariant1

A simple authentication button component.

`tsx
import { AuthButtonVariant1 } from "@pamfilico/uicomponents/material/auth";

onLogin={() => handleLogin()}
onSignup={() => handleSignup()}
/>
`

#### AuthButtonVariant2

Alternative authentication button variant.

`tsx
import { AuthButtonVariant2 } from "@pamfilico/uicomponents/material/auth";

onLogin={() => handleLogin()}
onSignup={() => handleSignup()}
/>
`

---

$3

Located at @pamfilico/uicomponents/material/header

#### SectionNavigationVariant1

Navigation component for scrolling to different sections.

`tsx
import { SectionNavigationVariant1 } from "@pamfilico/uicomponents/material/header";

sections={[
{ id: "features", label: "Features" },
{ id: "pricing", label: "Pricing" },
{ id: "contact", label: "Contact" }
]}
/>
`

#### HeaderScrollToSectionButtonVariant1

Button component for smooth scrolling to sections.

`tsx
import { HeaderScrollToSectionButtonVariant1 } from "@pamfilico/uicomponents/material/header";

targetId="features"
label="View Features"
/>
`

#### HeaderScrollToSectionButtonVariant2

Alternative scroll button variant.

`tsx
import { HeaderScrollToSectionButtonVariant2 } from "@pamfilico/uicomponents/material/header";

targetId="pricing"
label="See Pricing"
/>
`

---

$3

Located at @pamfilico/uicomponents/material/header/homepage

Complete homepage header layouts with multiple variants and sub-components.

#### HomePageHeaderVariant1Component

`tsx
import { HomePageHeaderVariant1Component } from "@pamfilico/uicomponents/material/header/homepage";


`

#### HomePageHeaderVariant2Component

Multi-section header with top and bottom components.

`tsx
import { HomePageHeaderVariant2Component } from "@pamfilico/uicomponents/material/header/homepage";


`

#### Sub-components

For more granular control:

`tsx
import {
HomePageHeaderParentComponent,
HomePageHeaderVariant2TopLeftComponent,
HomePageHeaderVariant2TopRightComponent,
HomePageHeaderVariant2BottomLeftComponent,
HomePageHeaderVariant2BottomRightComponent
} from "@pamfilico/uicomponents/material/header/homepage";
`

---

$3

Located at @pamfilico/uicomponents/material/hero

#### HeroSectionVariant1

Hero section component for landing pages.

`tsx
import { HeroSectionVariant1 } from "@pamfilico/uicomponents/material/hero";

title="Build Amazing Products"
subtitle="The fastest way to ship your ideas"
ctaText="Get Started"
onCtaClick={() => router.push("/signup")}
/>
`

---

$3

Located at @pamfilico/uicomponents/material/home

#### FeatureSectionVariant1

Feature showcase section with cards.

`tsx
import { FeatureSectionVariant1 } from "@pamfilico/uicomponents/material/home";

features={[
{
title: "Fast",
description: "Lightning quick performance",
icon:
},
{
title: "Secure",
description: "Enterprise-grade security",
icon:
}
]}
/>
`

#### FeatureCardVariant1

Individual feature card component.

`tsx
import { FeatureCardVariant1 } from "@pamfilico/uicomponents/material/home";

title="Real-time Sync"
description="Stay up to date with instant synchronization"
icon={}
/>
`

#### FaqSectionVariant1

FAQ section with accordion-style questions.

`tsx
import { FaqSectionVariant1 } from "@pamfilico/uicomponents/material/home";

faqs={[
{
question: "How does it work?",
answer: "Our platform uses advanced technology..."
},
{
question: "What's included?",
answer: "You get access to all features..."
}
]}
/>
`

#### TrustedByApplicationsSectionVariant1

Showcase logos of companies/applications using your product.

`tsx
import { TrustedByApplicationsSectionVariant1 } from "@pamfilico/uicomponents/material/home";

applications={[
{ name: "Company A", logo: "/logos/company-a.png" },
{ name: "Company B", logo: "/logos/company-b.png" }
]}
/>
`

---

$3

Located at @pamfilico/uicomponents/material/music

Components for chord chart editing and viewing with transposition and ChordPro support.

#### ChordEditorComponent

A rich text editor with inline chord support, transposition, and ChordPro-style bracket chord conversion.

`tsx
import { ChordEditorComponent } from "@pamfilico/uicomponents/material/music";

function SongEditor() {
const handleContentChange = (content) => {
console.log("Editor content:", content);
};

return (
onContentChange={handleContentChange}
isDarkMode={true}
showControls={true}
initialContent={[
{
type: "paragraph",
content: [
"Type lyrics here ",
{ type: "chord", props: { symbol: "C" } },
" and more lyrics ",
{ type: "chord", props: { symbol: "G/B" } }
]
}
]}
/>
);
}
`

Features:
- Insert chords inline with lyrics
- Transpose all chords up/down by semitones
- Convert ChordPro-style [C] bracket chords to inline tokens
- Quick chord insertion with @ trigger
- Dark/light mode support
- Help icon with usage instructions

#### ChordSelectionDialog

A dialog for selecting and inserting chords with a visual grid of common chords.

`tsx
import { ChordSelectionDialog } from "@pamfilico/uicomponents/material/music";

function MyComponent() {
const [open, setOpen] = useState(false);

const handleChordSelect = (chord) => {
console.log("Selected chord:", chord);
setOpen(false);
};

return (
<>
setOpen(true)}>Choose Chord
open={open}
onClose={() => setOpen(false)}
onChordSelect={handleChordSelect}
/>

);
}
`

#### ReadOnlyBlockNoteViewer

A read-only viewer for displaying BlockNote content with chord tokens.

`tsx
import { ReadOnlyBlockNoteViewer } from "@pamfilico/uicomponents/material/music";

function SongDisplay({ songContent }) {
return (
content={songContent}
isDarkMode={false}
/>
);
}
`

Props:
- content: BlockNote JSON content array
- isDarkMode: Boolean to toggle dark/light theme

#### SaveVersionComponent

A component for transposing chord charts and saving them in different keys. Accepts a custom key select component as a prop for maximum flexibility.

`tsx
import { SaveVersionComponent, SelectItemServerVariant1 } from "@pamfilico/uicomponents/material/music";

function SongVersionManager({ songId, songContent, originalKey }) {
const handleSave = (versionData) => {
console.log("Saving version:", versionData);
// Save to your API
fetch(/api/songs/${songId}/versions, {
method: "POST",
body: JSON.stringify(versionData.data)
});
};

// Create your custom key select component
const keySelectComponent = (
valueItemId={null}
onChange={() => {}}
fetchOptions={async () => [
{ id: "C", name: "C" },
{ id: "D", name: "D" },
{ id: "E", name: "E" },
{ id: "F", name: "F" },
{ id: "G", name: "G" },
{ id: "A", name: "A" },
{ id: "B", name: "B" },
// Add minor keys, sharps, flats...
]}
label="Key"
/>
);

return (
songId={songId}
originalContent={songContent}
originalKey={originalKey}
keySelectComponent={keySelectComponent}
onSave={handleSave}
showControls={true}
tActions={(key) => key} // Optional: translation function
tLabels={(key) => key} // Optional: translation function
tMessages={(key) => key} // Optional: translation function
/>
);
}
`

Props:
- songId: String identifier for the song
- originalContent: BlockNote JSON content array
- originalKey: String representing the original key (e.g., "C", "Dm")
- keySelectComponent: React element for key selection (required)
- onSave: Callback function when version is saved (versionData) => void
- showControls: Boolean to show/hide transpose controls (default: true)
- tActions: Optional translation function for action strings
- tLabels: Optional translation function for label strings
- tMessages: Optional translation function for message strings
- className: Optional CSS class name

Features:
- Live preview of transposed chord chart
- Transpose up/down with visual feedback
- Preview mode (read-only without controls)
- Customizable key selection through prop injection
- Internationalization support through translation functions

#### SelectItemServerVariant1

A generic autocomplete select component for server-side data fetching. Can be used for any dropdown that needs to fetch options from an API.

`tsx
import { SelectItemServerVariant1 } from "@pamfilico/uicomponents/material/music";

function GenreSelector() {
const [selectedGenreId, setSelectedGenreId] = useState(null);

const fetchGenres = async () => {
const response = await fetch("/api/genres");
const genres = await response.json();
return genres.map(g => ({ id: g.id, name: g.name }));
};

return (
valueItemId={selectedGenreId}
onChange={setSelectedGenreId}
fetchOptions={fetchGenres}
label="Select Genre"
helperText="Choose a music genre"
disabled={false}
/>
);
}
`

Props:
- valueItemId: Currently selected item ID (string | null | undefined)
- onChange: Callback when selection changes (itemId: string | null) => void
- fetchOptions: Async function that returns Promise
- SelectItemOption: { id: string, name: string }
- label: Optional label for the select input
- helperText: Optional helper text shown below the input
- disabled: Optional boolean to disable the select

Use Cases:
- Key selection for music transposition
- Genre/category selection
- Artist/band selection
- Any server-fetched dropdown options

Utility Functions:

The music package also exports utility functions for chord manipulation:

`tsx
import {
transposeChordSymbol,
parseChordSymbol,
canonicalizeNote,
transposeNote,
SHARP_NOTES,
ENHARMONIC,
BRACKET_CHORD_REGEX
} from "@pamfilico/uicomponents/material/music";

// Transpose a chord
const transposed = transposeChordSymbol("C", 2); // Returns "D"

// Parse a chord symbol
const parsed = parseChordSymbol("Am7/G"); // { root: "A", quality: "m7", bass: "G", original: "Am7/G" }

// Canonicalize a note
const note = canonicalizeNote("Db"); // Returns "C#"

// Transpose a single note
const newNote = transposeNote("C", 2); // Returns "D"
`

---

$3

Located at @pamfilico/uicomponents/utils

Utility functions for common tasks.

`tsx
import { scrollToSection, generateSeoMetadata } from "@pamfilico/uicomponents/utils";

// Smooth scroll to a section
scrollToSection("features");

// Generate SEO metadata for Next.js
const metadata = generateSeoMetadata({
title: "My Page",
description: "Page description"
});
`

---

Subpath Exports

The package supports multiple import paths for better organization:

`tsx
// Main entry (exports everything)
import { AuthButtonVariant1 } from "@pamfilico/uicomponents";

// Category-specific imports
import { AuthButtonVariant1 } from "@pamfilico/uicomponents/material/auth";
import { SectionNavigationVariant1 } from "@pamfilico/uicomponents/material/header";
import { HomePageHeaderVariant1Component } from "@pamfilico/uicomponents/material/header/homepage";
import { HeroSectionVariant1 } from "@pamfilico/uicomponents/material/hero";
import { FeatureSectionVariant1 } from "@pamfilico/uicomponents/material/home";
import { ChordEditorComponent } from "@pamfilico/uicomponents/material/music";
import { scrollToSection } from "@pamfilico/uicomponents/utils";
`

---

Features

- 🎨 Material UI Components - Built with Material UI for consistent theming
- 📱 Responsive Design - All components adapt to mobile, tablet, and desktop
- 🔧 TypeScript Support - Full type definitions included
- ⚛️ Next.js Compatible - All components use "use client" directive
- 📦 Tree-shakeable - Import only what you need with subpath exports
- 🎯 Storybook Documentation - Interactive component demos and documentation
- 🌐 Framework Agnostic Architecture - Organized by framework for future expansion

---

Development

See TEMPLATE_PACKAGE.md for comprehensive development guidelines and patterns.

`bash


Install dependencies

npm install

Start development mode (watch)

npm run dev

Build the package

npm run build

Run Storybook

npm run storybook

Build and deploy Storybook

npm run deploy-storybook
`

---

Documentation

- TEMPLATE_PACKAGE.md - Comprehensive guide for building UI component packages
- STORYBOOK_PACKAGE_SETUP.md - Storybook setup and deployment guide
- CLAUDE.md - Development guidelines for working with this codebase

---

Peer Dependencies

This package requires the following dependencies in your project:

`json
{
"@emotion/react": "^11.14.0",
"@emotion/styled": "^11.14.1",
"@mui/icons-material": "^7.3.1",
"@mui/material": "^7.3.1",
"next": "^15.0.0",
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0"
}
``

---

License

MIT