@bettercms/ui

Status: Scaffolded — Not yet published to npm.

Shared page-builder block components for BetterCMS. Contains presentation-only React components for the 7 core block types: Heading, Text, Image, Button, Spacer, Columns, and Video.

These components are intentionally dumb (presentational only) — no selection state, no toolbar, no inline editing. That logic lives in the admin app (bettercms-admin).

Design Philosophy

This package follows the shadcn/ui studio model:

• Each block has multiple style variants and animation presets that can be composed.
• Components are owned by you — copy, modify, extend freely.
• The package is a starting point, not a locked dependency.
• Animation and style variation work ships post-MVP.

Block Types

| Type | Component | Purpose | |------|-----------|---------| | heading | Heading | H1–H3 text headings | | text | Text | Rich text / HTML content | | image | Image | Images with alt text & caption | | button | Button | CTA buttons with variants | | spacer | Spacer | Vertical spacing blocks | | columns | Columns | Multi-column layouts with nested blocks | | video | Video | YouTube, Vimeo, or native video embeds |

Usage

import { BlocksRenderer } from "@bettercms/ui";
import type { ContentBlock } from "@betttercms/types";

// Use with @betttercms/types block JSON
const blocks: ContentBlock[] = [
  { type: "heading", id: "1", props: { text: "Hello", level: 1 } },
  { type: "text",   id: "2", props: { html: "<p>Welcome!</p>" } },
];

export function Page() {
  return <BlocksRenderer blocks={blocks} />;
}

With a custom block renderer (e.g., admin app adds selection state)

import { BlockRenderer } from "@bettercms/ui";

function AdminCanvas({ block, isSelected, onSelect }) {
  return (
    <div
      onClick={() => onSelect(block.id)}
      className={isSelected ? "ring-2 ring-primary" : ""}
    >
      <BlockRenderer block={block} />
    </div>
  );
}

Adding new blocks

1. Create src/blocks/MyBlock.tsx
2. Export from src/blocks/index.ts
3. Add entry to src/registry.ts
4. Update src/index.ts

Adding animation variants (post-MVP)

Each block should eventually expose:

• animation prop (e.g., "fade-in", "slide-up", "stagger")
• duration prop (ms)
• delay prop (ms)

These are pre-defined via Tailwind keyframes in tailwind.config.ts.

Development

# Install dependencies (run from backend root)
bun install

# Type-check
bun run --filter @bettercms/ui typecheck

# Add a new shadcn/ui component
cd packages/ui && npx shadcn@latest add -p ../../ button

Note on npm publishing

This package is not yet published to npm. Admin and web repos use their own local shadcn/ui copies for non-page-builder UI (Dialog, Sheet, Table, etc.). The @bettercms/ui blocks are consumed via workspace references during local development, and will be published after MVP when the block variants and animation system are finalized.