@ffsm/html-factory

A lightweight utility for creating React HTML factory components with proper TypeScript support, ref forwarding, and className merging.

Features

• 🚀 Create reusable HTML components with custom defaults
• 🔄 Automatic className merging with deduplication
• 📦 TypeScript-first with full type safety
• 🔗 Forward refs properly to DOM elements
• 🎨 Perfect for design systems and component libraries

Installation

1# npm
2npm i @ffsm/html-factory
3
4# yarn
5yarn add @ffsm/html-factory
6
7# pnpm
8pnpm add @ffsm/html-factory

Usage

Basic Example

1import { factory } from '@ffsm/html-factory';
2
3// Create typesafe HTML components with default props
4const Heading = factory('h1', 'Heading', { className: 'text-2xl font-bold' });
5const Paragraph = factory('p', 'Paragraph', { className: 'text-base mb-4' });
6
7// Use them in your components
8function Article() {
9  return (
10    <article>
11      <Heading className="text-blue-600">
12        This heading combines default and custom classes
13      </Heading>
14      <Paragraph>This paragraph has the default classes applied.</Paragraph>
15    </article>
16  );
17}

Creating a Component Library

1// components/typography.tsx
2import { factory } from '@ffsm/html-factory';
3
4export const H1 = factory('h1', 'H1', { className: 'text-4xl font-bold mb-4' });
5export const H2 = factory('h2', 'H2', { className: 'text-3xl font-bold mb-3' });
6export const H3 = factory('h3', 'H3', { className: 'text-2xl font-bold mb-2' });
7export const P = factory('p', 'P', { className: 'text-base mb-4' });
8export const Blockquote = factory('blockquote', 'Blockquote', {
9  className: 'pl-4 border-l-4 border-gray-300 italic',
10});

Using with Refs

1import { factory } from '@ffsm/html-factory';
2import { useRef } from 'react';
3
4const Button = factory('button', 'Button', {
5  className: 'px-4 py-2 bg-blue-500 text-white rounded',
6  type: 'button',
7});
8
9function Form() {
10  const buttonRef = useRef<HTMLButtonElement>(null);
11
12  return (
13    <form>
14      {/* Refs are properly forwarded */}
15      <Button ref={buttonRef} onClick={() => buttonRef.current?.focus()}>
16        Click me
17      </Button>
18    </form>
19  );
20}

Using the clsx Utility

1import { clsx } from '@ffsm/html-factory';
2
3// Combines classes with automatic deduplication
4const className = clsx(
5  'base-class',
6  isActive && 'active',
7  isPrimary && 'primary',
8  'base-class' // Duplicated class will be removed
9);

API

factory<El>(tag, displayName, initialProps?)

Creates a React component factory for the specified HTML tag.

• tag: The HTML tag name (e.g., 'div', 'span', 'button')
• displayName: The React component display name
• initialProps: (Optional) Default props to apply to all instances

Returns a React component with forwarded refs.

clsx(...classes)

Utility to combine class names with deduplication.

• classes: Any number of string, boolean, null, or undefined values
• Returns a clean, deduplicated string of class names

propsHTML<El>(overrideProps, ref?, initialProps?)

Internal utility for processing HTML props.

• overrideProps: Props passed by the user
• ref: React ref to forward
• initialProps: Default props from factory

License

MIT © FFSM Team