@ckc-net/puck-extended 0.2.1 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Hugo Debard
+Copyright (c) 2025 CKC-Net
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,182 @@
+![puck-extended](/.github/puck-extended-banner.jpg)
+
+# Puck Extended
+
+A component library that extends [Puck](https://github.com/puckeditor/puck) — the open-source, headless visual page editor for React — with additional UI components, field overrides, media/page pickers, rich text extensions, and design system utilities.
+
+## What is Puck?
+
+[Puck](https://puckeditor.com/) is an open-source visual editor for React that lets developers build custom drag-and-drop page builders. You define your components and their editable fields; Puck provides the editing interface and renders the result. `puck-extended` is a companion package that augments Puck with ready-to-use components and helpers.
+
+## Installation
+
+```bash
+npm install @ckc-net/puck-extended
+```
+
+## Features
+
+### Editor overrides plugin
+
+Drop-in replacements for Puck's default editor UI: improved field labels with tooltips, grouped fields, and polished inputs (text, textarea, number with unit, select, radio, checkbox).
+
+```tsx
+import { createPuckOverridesPlugin } from '@ckc-net/puck-extended'
+
+const puckConfig = {
+  components: { /* ... */ },
+  plugins: [createPuckOverridesPlugin()],
+}
+```
+
+### MediaPicker
+
+A full-featured media browser field: paginated library, search, drag-and-drop upload with progress, and support for images, videos and PDFs. Works in URL mode or ID-reference mode.
+
+```tsx
+import { MediaPicker } from '@ckc-net/puck-extended'
+
+// Inside a Puck field render
+<MediaPicker
+  value={value}
+  onChange={onChange}
+  mode="reference"
+/>
+```
+
+Resolve a media reference to a URL at render time:
+
+```tsx
+import { useMediaUrl } from '@ckc-net/puck-extended'
+
+const url = useMediaUrl(value) // returns resolved URL string
+```
+
+### PagePicker
+
+Browse and search published pages, returning either a URL string or a page reference object. Useful for internal link fields.
+
+```tsx
+import { PagePicker } from '@ckc-net/puck-extended'
+
+<PagePicker value={value} onChange={onChange} />
+```
+
+```tsx
+import { usePageUrl } from '@ckc-net/puck-extended'
+
+const url = usePageUrl(value)
+```
+
+### ColorPicker
+
+Color selection with a predefined palette (Tailwind-inspired swatches), a grayscale row, and a free hex input.
+
+```tsx
+import { ColorPicker } from '@ckc-net/puck-extended'
+
+<ColorPicker value={color} onChange={setColor} />
+```
+
+### Rich text extensions
+
+Extensions for Puck's rich text toolbar (requires Tiptap):
+
+- **RichTextMenuColorPicker** — inline text color picker with preset colors and custom hex input
+- **RichTextMenuLink** — link insertion popover backed by PagePicker
+
+```tsx
+import { RichTextMenuColorPicker, RichTextMenuLink } from '@ckc-net/puck-extended'
+```
+
+### Template block
+
+Save and restore full page layouts. Supports localStorage (default) or a REST API backend for sharing templates across users.
+
+```tsx
+import { createTemplateBlock } from '@ckc-net/puck-extended'
+
+const TemplateBlock = createTemplateBlock({
+  storageKey: 'my-project',
+  // optional: use a REST API instead of localStorage
+  apiUrl: () => '/api/templates',
+  getHeaders: () => ({ 'X-CSRF-TOKEN': getCsrfToken() }),
+})
+```
+
+Register `TemplateBlock` as a Puck component to let editors save and reload layouts.
+
+### UI components
+
+A set of accessible Base UI wrapper components, all styled with Tailwind CSS:
+
+| Component | Description |
+|-----------|-------------|
+| `Accordion` | Collapsible sections |
+| `Badge` | Status labels |
+| `Button` | Action button with variants |
+| `Checkbox` | Controlled checkbox |
+| `Dialog` | Modal dialog |
+| `Input` / `InputGroup` | Text input with optional addons |
+| `Menu` | Dropdown menu |
+| `Pagination` | Page navigation |
+| `Popover` | Floating popover |
+| `Radio` / `RadioGroup` | Radio selection |
+| `ScrollArea` | Custom scrollable container |
+| `Select` | Dropdown select |
+| `Switch` | Toggle switch |
+| `Tabs` | Tabbed panels |
+| `Textarea` | Multi-line input |
+| `Toast` | Notification toasts |
+| `Tooltip` | Hover tooltip |
+
+### Design utilities
+
+Field-ready helpers for common CSS properties, ready to plug into any Puck component config:
+
+```ts
+import {
+  animation,
+  customClasses,
+  display,
+  fontWeight,
+  lineHeight,
+  margin,
+  padding,
+  position,
+  size,
+  spacing,
+  textAlign,
+  textColor,
+  textDecoration,
+  textSize,
+  textTransform,
+  typography,
+} from '@ckc-net/puck-extended'
+```
+
+Each utility exports a Puck field definition (or a set of fields) that can be spread into a component's `fields` config.
+
+### Image optimization hook
+
+Generate responsive `srcSet` and `sizes` attributes from a single image URL:
+
+```tsx
+import { useOptimizedImage } from '@ckc-net/puck-extended'
+
+const { src, srcSet, sizes } = useOptimizedImage(url, {
+  breakpoints: [640, 1024, 1920],
+})
+```
+
+## Development
+
+```bash
+npm run dev        # Watch mode (JS + CSS)
+npm run build      # Production build
+npm run format     # Prettier
+```
+
+## License
+
+MIT — [CKC-Net](https://github.com/ckc-net)