@chrono-os/image-editor-react 0.2.0

package/README.md

@@ -0,0 +1,424 @@
+# @chrono-os/image-editor-react
+
+![npm](https://img.shields.io/npm/v/@chrono-os/image-editor-react)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+
+Editor de imagens com crop visual + preview de badge. Inclui `<ImagePicker>` controlado (preview + modal de edição com crop draggable, snap nas bordas, zoom, filtros saturação/sépia, cor de fundo, espelhar), `<ImageCropPicker>` standalone (sem o wrapper), `<BadgeOverlay>` reutilizável e os editores de badge `<BadgeEditorCard>` / `<BadgePartControls>` / `<SliderRow>` (admin).
+
+## Install
+
+```bash
+yarn add @chrono-os/image-editor-react
+```
+
+Publicado em `registry.npmjs.org` público — sem auth pra consumir.
+
+Peer dependencies: `react@>=18` `react-dom@>=18`.
+
+## Setup tema (recomendado)
+
+Importar o CSS de tokens no layout root (Next.js App Router):
+
+```ts
+// app/layout.tsx
+import '@chrono-os/image-editor-react/theme.css'
+```
+
+E sobrescrever as CSS vars no `globals.css` do consumer (ou em qualquer ancestor com classe `.image-editor-root`):
+
+```css
+:root {
+  --ie-accent: #C9A961;        /* default electric blue #556FFF */
+  --ie-accent-hover: #A88842;
+  --ie-border: #d4d4d8;
+  --ie-bg: #fafafa;
+  --ie-text: #404040;
+  --ie-text-muted: #737373;
+  --ie-danger: #dc2626;
+}
+```
+
+Os componentes usam `text-[color:var(--ie-accent,#556FFF)]`/`bg-[color:var(--ie-accent,#556FFF)]` (Tailwind arbitrary values), então qualquer wrapper aplicando essas vars é suficiente.
+
+## Setup Tailwind (opcional)
+
+Funciona com Tailwind 3+ sem config extra — as classes usadas são todas core utilities + arbitrary values. Se o consumer tiver `purge`/`content` configurado, garantir que o `node_modules/@chrono-os/image-editor-react/dist/**/*.{js,cjs}` está incluído:
+
+```ts
+// tailwind.config.ts
+export default {
+  content: [
+    './app/**/*.{ts,tsx}',
+    './node_modules/@chrono-os/image-editor-react/dist/**/*.{js,cjs}',
+  ],
+  // ...
+}
+```
+
+## Exemplo: `<ImagePicker>` completo
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+import {
+  ImagePicker,
+  type UploadAdapter,
+  type CropValue,
+  type BadgeData,
+  type ImagePreset,
+} from '@chrono-os/image-editor-react'
+import '@chrono-os/image-editor-react/theme.css'
+
+const uploadAdapter: UploadAdapter = {
+  list: async () => {
+    const r = await fetch('/api/admin/uploads', { credentials: 'include' })
+    if (!r.ok) throw new Error('Falha ao listar')
+    const data = await r.json()
+    return data.items
+  },
+  upload: async (file) => {
+    const form = new FormData()
+    form.append('file', file, file.name)
+    const r = await fetch('/api/admin/uploads', {
+      method: 'POST',
+      body: form,
+      credentials: 'include',
+    })
+    if (!r.ok) throw new Error('Upload falhou')
+    return r.json()
+  },
+  delete: async (filename) => {
+    const r = await fetch(
+      `/api/admin/uploads/${encodeURIComponent(filename)}`,
+      { method: 'DELETE', credentials: 'include' },
+    )
+    return r.ok
+  },
+}
+
+const presets: ImagePreset[] = [
+  { label: 'Hero Naírio', url: '/branding/hero-nairio.webp' },
+  { label: 'Background ABS', url: '/branding/abs-pattern.webp' },
+]
+
+export function HeroImageField() {
+  const [url, setUrl] = useState('')
+  const [crop, setCrop] = useState<CropValue>({})
+  const badge: BadgeData = {
+    numero: '201',
+    label: 'advogado',
+    numeroEnabled: true,
+    labelEnabled: true,
+  }
+
+  return (
+    <ImagePicker
+      label="Foto do hero"
+      hint="Recomendado: 1200×1600px (3:4)"
+      value={url}
+      onChange={(next) => setUrl(next)}
+      aspect="3/4"
+      crop={crop}
+      onCropChange={setCrop}
+      badge={badge}
+      uploadAdapter={uploadAdapter}
+      presets={presets}
+    />
+  )
+}
+```
+
+## Exemplo: `<BadgeOverlay>` standalone
+
+Pra renderizar só o badge sobreposto (sem o picker — útil em previews de listagem, cards, etc):
+
+```tsx
+import { BadgeOverlay } from '@chrono-os/image-editor-react/badge'
+
+export function HeroCard({ imageUrl }: { imageUrl: string }) {
+  return (
+    <div
+      className="relative aspect-[3/4] overflow-hidden rounded-lg"
+      style={{ containerType: 'inline-size' }}
+    >
+      <img src={imageUrl} alt="" className="h-full w-full object-cover" />
+      <BadgeOverlay
+        badge={{
+          numero: '201',
+          label: 'advogado',
+          numeroEnabled: true,
+          labelEnabled: true,
+        }}
+      />
+    </div>
+  )
+}
+```
+
+> **Importante:** o pai do `<BadgeOverlay>` precisa de `containerType: 'inline-size'` no CSS pra que os `cqw` (container query width) funcionem proporcionalmente em qualquer tamanho.
+
+## Exemplo: `<BadgeEditorCard>` no `extraCards`
+
+Renderiza um subcard completo de edição de parte do badge (título + checkbox "Exibir" + texto + cor + sliders). Encaixa direto no `extraCards` do `<ImagePicker>`:
+
+```tsx
+'use client'
+
+import {
+  ImagePicker,
+  BadgeEditorCard,
+  type BadgePartState,
+  type RecentColorsAdapter,
+} from '@chrono-os/image-editor-react'
+
+// Adapter opcional pra integrar com sistema de cores recentes do consumer.
+const recentColors: RecentColorsAdapter = {
+  colors: { text: ['#13203B', '#C9A961', '#FFFFFF'] },
+  addColor: (hex, kind) => {
+    // persistir no DB do consumer
+  },
+}
+
+export function HeroBadgeFields({
+  badge,
+  onBadgeChange,
+}: {
+  badge: { numero?: BadgePartState; label?: BadgePartState }
+  onBadgeChange: (next: typeof badge) => void
+}) {
+  return (
+    <ImagePicker
+      // ...props do ImagePicker
+      value="/img/hero.webp"
+      onChange={() => {}}
+      uploadAdapter={uploadAdapter}
+      extraCards={[
+        <BadgeEditorCard
+          key="numero"
+          title="Badge — Número"
+          enabledLabel="Exibir número"
+          value={badge.numero ?? {}}
+          onChange={(next) => onBadgeChange({ ...badge, numero: next })}
+          defaultColor="#C9A961"
+          defaultPosX={6}
+          defaultPosY={84}
+          recentColors={recentColors}
+        />,
+        <BadgeEditorCard
+          key="label"
+          title="Badge — Label"
+          enabledLabel="Exibir label"
+          value={badge.label ?? {}}
+          onChange={(next) => onBadgeChange({ ...badge, label: next })}
+          defaultColor="#FFFFFF"
+          defaultPosX={36}
+          defaultPosY={88}
+          recentColors={recentColors}
+        />,
+      ]}
+    />
+  )
+}
+```
+
+A interface `BadgePartState` é:
+
+```ts
+export interface BadgePartState {
+  enabled?: boolean  // undefined === true (exibe), false === oculto
+  text?: string
+  color?: string     // #RRGGBB
+  size?: number      // % do default (50-500)
+  offsetX?: number   // % horizontal (0-100)
+  offsetY?: number   // % vertical (0-100)
+}
+```
+
+## Exemplo: `<BadgePartControls>` standalone
+
+Se você já tem o subcard externo (título + checkbox + texto) e quer só os controles compactos de cor + sliders:
+
+```tsx
+'use client'
+
+import { BadgePartControls } from '@chrono-os/image-editor-react'
+
+export function MyBadgeControls({ partState, onPatch }) {
+  return (
+    <BadgePartControls
+      color={partState.color}
+      defaultColor="#C9A961"
+      size={partState.size}
+      offsetX={partState.offsetX}
+      offsetY={partState.offsetY}
+      defaultPosX={6}
+      defaultPosY={84}
+      onColorChange={(v) => onPatch({ color: v })}
+      onSizeChange={(v) => onPatch({ size: v })}
+      onOffsetXChange={(v) => onPatch({ offsetX: v })}
+      onOffsetYChange={(v) => onPatch({ offsetY: v })}
+    />
+  )
+}
+```
+
+## Exemplo: `<ImageCropPicker>` standalone
+
+Pra quem só quer o editor de crop sem o wrapper de upload/preview:
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+import { ImageCropPicker, type CropValue } from '@chrono-os/image-editor-react'
+
+export function CropOnly({ imageUrl }: { imageUrl: string }) {
+  const [crop, setCrop] = useState<CropValue>({})
+  return (
+    <ImageCropPicker
+      imageUrl={imageUrl}
+      targetAspect={3 / 4}
+      value={crop}
+      onChange={setCrop}
+      maxHeight={520}
+    />
+  )
+}
+```
+
+## Props do `<ImagePicker>`
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` | `string` | — | URL atual da imagem (controlado). |
+| `onChange` | `(url: string, aspectRatio?: number) => void` | — | Chamado quando o consumer escolhe nova imagem. |
+| `uploadAdapter` | `UploadAdapter` | — | Adapter contra o backend (list/upload/delete/resolveUrl). |
+| `label` | `string` | — | Rótulo do field acima do preview. |
+| `hint` | `string` | — | Texto de ajuda abaixo do label. |
+| `aspect` | `'1/1'\|'3/4'\|'16/9'\|'4/3'` | `'3/4'` | Aspect ratio do frame de destino. |
+| `crop` | `CropValue` | `{}` | Valor de crop (position/scale/mirror/filters/backdrop). |
+| `onCropChange` | `(crop: CropValue) => void` | — | Chamado quando o usuário ajusta o crop no modal. |
+| `badge` | `BadgeData` | — | Badge sobreposto na preview (número + label). |
+| `extraCards` | `ReactNode[]` | — | Cards extras ao lado direito do preview (slots de UI custom). |
+| `presets` | `ImagePreset[]` | — | Atalhos de imagem curados (mostrados na aba "Imagens"). |
+
+## Interface `UploadAdapter`
+
+```ts
+export interface UploadAdapter {
+  /** Lista uploads existentes (ordem decrescente por createdAt no consumer). */
+  list: () => Promise<UploadItem[]>
+  /** Sobe um arquivo e devolve o item criado. */
+  upload: (file: File) => Promise<UploadItem>
+  /** Remove um upload por filename. Retorna true em sucesso. */
+  delete: (filename: string) => Promise<boolean>
+  /**
+   * Resolve uma URL armazenada (relativa ou absoluta) pra URL absoluta usada
+   * no <img src>. Default = identity. Útil quando backend serve /uploads/*
+   * em domínio diferente sem rewrite.
+   */
+  resolveUrl?: (url: string) => string
+}
+
+export interface UploadItem {
+  filename: string
+  url: string
+  sizeBytes: number
+  createdAt?: string
+  width?: number
+  height?: number
+}
+```
+
+## Interface `CropValue`
+
+```ts
+export interface CropValue {
+  /** CSS object-position style: "50% 50%" ou "center top". */
+  position?: string
+  /** Zoom. 1 = cover normal, >1 = zoom in, <1 = zoom out (mostra backdrop). */
+  scale?: number
+  mirror?: boolean
+  grayscale?: number
+  saturation?: number
+  sepia?: number
+  sepiaColor?: string
+  /** Cor de fundo do container (#RRGGBB ou 'transparent'). */
+  backdropColor?: string
+  /** Opacidade da cor de backdrop 0-100. */
+  backdropOpacity?: number
+  /** Translate offset adicional (frame fora da imagem). */
+  overflowX?: number
+  overflowY?: number
+}
+```
+
+## Interface `BadgeData`
+
+```ts
+export interface BadgeData {
+  numero?: string
+  label?: string
+  numeroEnabled?: boolean
+  labelEnabled?: boolean
+  numeroColor?: string
+  numeroSize?: number      // 50-500% (default 100)
+  numeroOffsetX?: number   // %, default 6
+  numeroOffsetY?: number   // %, default 84
+  labelColor?: string
+  labelSize?: number       // 50-500% (default 100)
+  labelOffsetX?: number    // %, default 36
+  labelOffsetY?: number    // %, default 88
+}
+```
+
+## Props do `<BadgeEditorCard>`
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `title` | `string` | — | Título do subcard (ex `"Badge — Número"`). |
+| `value` | `BadgePartState` | — | Estado controlado (enabled/text/color/size/offsetX/offsetY). |
+| `onChange` | `(next: BadgePartState) => void` | — | Recebe o estado completo a cada edição. |
+| `defaultColor` | `string` | — | Hex mostrado quando `value.color` é undefined. |
+| `defaultPosX` | `number` | — | % horizontal exibida no slider quando undefined. |
+| `defaultPosY` | `number` | — | % vertical exibida no slider quando undefined. |
+| `enabledLabel` | `string` | `'Exibir'` | Label da checkbox. |
+| `textPlaceholder` | `string` | — | Placeholder do field texto. |
+| `recentColors` | `RecentColorsAdapter` | — | Adapter pra cores recentes (sumir swatches se ausente). |
+| `recentKind` | `string` | `'text'` | Chave de cor pra agrupar recentes (do adapter). |
+| `seedColors` | `string[]` | `['#FFFFFF', '#000000']` | Sementes quando recentes acabam. |
+| `sizeMin` | `number` | `50` | Mínimo do slider de Tamanho (%). |
+| `sizeMax` | `number` | `500` | Máximo do slider de Tamanho (%). |
+
+## Props do `<BadgePartControls>`
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `color` | `string \| undefined` | — | Hex atual (undefined cai pra `defaultColor`). |
+| `defaultColor` | `string` | — | Hex placeholder quando `color` é undefined. |
+| `size` | `number \| undefined` | — | Tamanho atual (%). |
+| `offsetX` | `number \| undefined` | — | Posição X atual (%). |
+| `offsetY` | `number \| undefined` | — | Posição Y atual (%). |
+| `defaultPosX` | `number` | — | Posição X exibida quando `offsetX` é undefined. |
+| `defaultPosY` | `number` | — | Posição Y exibida quando `offsetY` é undefined. |
+| `onColorChange` | `(v?: string) => void` | — | Emit. Recebe undefined em reset. |
+| `onSizeChange` | `(v?: number) => void` | — | Emit. undefined em reset. |
+| `onOffsetXChange` | `(v?: number) => void` | — | idem. |
+| `onOffsetYChange` | `(v?: number) => void` | — | idem. |
+| `recentColors` | `RecentColorsAdapter` | — | Adapter opcional de cores recentes. |
+| `recentKind` | `string` | `'text'` | Chave do adapter. |
+| `seedColors` | `string[]` | `['#FFFFFF', '#000000']` | Sementes neutras. |
+| `sizeMin` | `number` | `50` | Mínimo do slider Tamanho. |
+| `sizeMax` | `number` | `500` | Máximo do slider Tamanho. |
+
+## Roadmap
+
+- Drag-and-drop de arquivos no card de uploads
+- Mais aspect ratios (`2/3`, `9/16`)
+- Animações suaves na troca de modal/preview
+- Adapter de recentes (cores usadas anteriormente nos badges)
+
+## License
+
+MIT

package/dist/badge-BRjFgV8X.d.cts

@@ -0,0 +1,130 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Tipos compartilhados do `@chrono-os/image-editor-react`.
+ */
+
+/**
+ * Valor do crop aplicado à imagem. Persistido pelo consumer no schema
+ * (geralmente JSONB).
+ */
+interface CropValue {
+    position?: string;
+    /** Zoom. 1 = cover normal, >1 = zoom in, <1 = zoom out (mostra backdrop). */
+    scale?: number;
+    mirror?: boolean;
+    grayscale?: number;
+    saturation?: number;
+    sepia?: number;
+    sepiaColor?: string;
+    /**
+     * Cor de fundo do container (visível em PNG transparente ou zoom out).
+     * Pode ser `#RRGGBB` ou `"transparent"`. Quando undefined, consumer usa
+     * o default dele.
+     */
+    backdropColor?: string;
+    /** Opacidade da cor de backdrop 0-100 (default 100). */
+    backdropOpacity?: number;
+    /** Translate offset additional to focal — em target frac signed. Permite frame fora da imagem. */
+    overflowX?: number;
+    overflowY?: number;
+}
+/** Item de upload listado/criado pelo `UploadAdapter`. */
+interface UploadItem {
+    filename: string;
+    url: string;
+    sizeBytes: number;
+    createdAt?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Resultado do upload (subset extendido do `UploadItem` retornado pelo
+ * `upload()`). Compatível com `UploadItem`.
+ */
+type UploadedImage = UploadItem;
+/**
+ * Adapter de uploads — o consumer implementa essa interface contra o backend
+ * dele (REST, GraphQL, mock, etc.) e passa para `<ImagePicker>` via prop.
+ *
+ * Erros propagam (rejeitam a promise). `ImagePicker` mostra mensagem amigável.
+ */
+interface UploadAdapter {
+    /** Lista uploads existentes (ordem decrescente por createdAt no consumer). */
+    list: () => Promise<UploadItem[]>;
+    /** Sobe um arquivo e devolve o item criado. */
+    upload: (file: File) => Promise<UploadItem>;
+    /** Remove um upload por filename. Retorna true em sucesso. */
+    delete: (filename: string) => Promise<boolean>;
+    /**
+     * Resolve uma URL armazenada (relativa ou absoluta) pra URL absoluta usada
+     * no `<img src>`. Default = identity (string passa direto).
+     * Útil quando o backend serve `/uploads/*` e o frontend roda em domínio
+     * diferente sem rewrite — consumer prefixa com baseUrl.
+     */
+    resolveUrl?: (url: string) => string;
+}
+/** Preset de imagem do site (atalhos curados — opcional). */
+interface ImagePreset {
+    label: string;
+    url: string;
+}
+/**
+ * Adapter de cores recentes — opcional. Quando ausente, `BadgePartControls`
+ * (consumer) não mostra o swatch.
+ */
+interface RecentColorsAdapter {
+    colors: {
+        [kind: string]: string[];
+    };
+    addColor: (hex: string, kind: string) => void;
+    seed?: {
+        [kind: string]: string[];
+    };
+}
+/**
+ * Dados do badge sobreposto à imagem. Renderer real fica no consumer (ex
+ * @chrono-os/lp-react); aqui só usamos pra preview visual no editor.
+ */
+interface BadgeData {
+    numero?: string;
+    label?: string;
+    numeroEnabled?: boolean;
+    labelEnabled?: boolean;
+    numeroColor?: string;
+    numeroSize?: number;
+    numeroOffsetX?: number;
+    numeroOffsetY?: number;
+    labelColor?: string;
+    labelSize?: number;
+    labelOffsetX?: number;
+    labelOffsetY?: number;
+}
+type ImagePickerAspect = '1/1' | '3/4' | '16/9' | '4/3';
+/** Props do `<ImagePicker>` controlado. */
+interface ImagePickerProps {
+    value: string;
+    onChange: (url: string, aspectRatio?: number) => void;
+    /** Adapter pra upload/list/delete contra o backend do consumer. */
+    uploadAdapter: UploadAdapter;
+    label?: string;
+    hint?: string;
+    aspect?: ImagePickerAspect;
+    crop?: CropValue;
+    onCropChange?: (crop: CropValue) => void;
+    /** Badge opcional (número + label) sobreposto na imagem no preview. */
+    badge?: BadgeData;
+    /** Slots opcionais — cada um vira um subcard ao lado direito do preview. */
+    extraCards?: ReactNode[];
+    /** Presets de imagem do site (mostrados na aba "Imagens" abaixo dos uploads). */
+    presets?: ImagePreset[];
+}
+
+interface BadgeOverlayProps {
+    badge?: BadgeData;
+    size?: 'sm' | 'md';
+}
+declare function BadgeOverlay({ badge }: BadgeOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+export { type BadgeData as B, type CropValue as C, type ImagePickerAspect as I, type RecentColorsAdapter as R, type UploadAdapter as U, BadgeOverlay as a, type ImagePickerProps as b, type ImagePreset as c, type UploadItem as d, type UploadedImage as e };

package/dist/badge-BRjFgV8X.d.ts

@@ -0,0 +1,130 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Tipos compartilhados do `@chrono-os/image-editor-react`.
+ */
+
+/**
+ * Valor do crop aplicado à imagem. Persistido pelo consumer no schema
+ * (geralmente JSONB).
+ */
+interface CropValue {
+    position?: string;
+    /** Zoom. 1 = cover normal, >1 = zoom in, <1 = zoom out (mostra backdrop). */
+    scale?: number;
+    mirror?: boolean;
+    grayscale?: number;
+    saturation?: number;
+    sepia?: number;
+    sepiaColor?: string;
+    /**
+     * Cor de fundo do container (visível em PNG transparente ou zoom out).
+     * Pode ser `#RRGGBB` ou `"transparent"`. Quando undefined, consumer usa
+     * o default dele.
+     */
+    backdropColor?: string;
+    /** Opacidade da cor de backdrop 0-100 (default 100). */
+    backdropOpacity?: number;
+    /** Translate offset additional to focal — em target frac signed. Permite frame fora da imagem. */
+    overflowX?: number;
+    overflowY?: number;
+}
+/** Item de upload listado/criado pelo `UploadAdapter`. */
+interface UploadItem {
+    filename: string;
+    url: string;
+    sizeBytes: number;
+    createdAt?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Resultado do upload (subset extendido do `UploadItem` retornado pelo
+ * `upload()`). Compatível com `UploadItem`.
+ */
+type UploadedImage = UploadItem;
+/**
+ * Adapter de uploads — o consumer implementa essa interface contra o backend
+ * dele (REST, GraphQL, mock, etc.) e passa para `<ImagePicker>` via prop.
+ *
+ * Erros propagam (rejeitam a promise). `ImagePicker` mostra mensagem amigável.
+ */
+interface UploadAdapter {
+    /** Lista uploads existentes (ordem decrescente por createdAt no consumer). */
+    list: () => Promise<UploadItem[]>;
+    /** Sobe um arquivo e devolve o item criado. */
+    upload: (file: File) => Promise<UploadItem>;
+    /** Remove um upload por filename. Retorna true em sucesso. */
+    delete: (filename: string) => Promise<boolean>;
+    /**
+     * Resolve uma URL armazenada (relativa ou absoluta) pra URL absoluta usada
+     * no `<img src>`. Default = identity (string passa direto).
+     * Útil quando o backend serve `/uploads/*` e o frontend roda em domínio
+     * diferente sem rewrite — consumer prefixa com baseUrl.
+     */
+    resolveUrl?: (url: string) => string;
+}
+/** Preset de imagem do site (atalhos curados — opcional). */
+interface ImagePreset {
+    label: string;
+    url: string;
+}
+/**
+ * Adapter de cores recentes — opcional. Quando ausente, `BadgePartControls`
+ * (consumer) não mostra o swatch.
+ */
+interface RecentColorsAdapter {
+    colors: {
+        [kind: string]: string[];
+    };
+    addColor: (hex: string, kind: string) => void;
+    seed?: {
+        [kind: string]: string[];
+    };
+}
+/**
+ * Dados do badge sobreposto à imagem. Renderer real fica no consumer (ex
+ * @chrono-os/lp-react); aqui só usamos pra preview visual no editor.
+ */
+interface BadgeData {
+    numero?: string;
+    label?: string;
+    numeroEnabled?: boolean;
+    labelEnabled?: boolean;
+    numeroColor?: string;
+    numeroSize?: number;
+    numeroOffsetX?: number;
+    numeroOffsetY?: number;
+    labelColor?: string;
+    labelSize?: number;
+    labelOffsetX?: number;
+    labelOffsetY?: number;
+}
+type ImagePickerAspect = '1/1' | '3/4' | '16/9' | '4/3';
+/** Props do `<ImagePicker>` controlado. */
+interface ImagePickerProps {
+    value: string;
+    onChange: (url: string, aspectRatio?: number) => void;
+    /** Adapter pra upload/list/delete contra o backend do consumer. */
+    uploadAdapter: UploadAdapter;
+    label?: string;
+    hint?: string;
+    aspect?: ImagePickerAspect;
+    crop?: CropValue;
+    onCropChange?: (crop: CropValue) => void;
+    /** Badge opcional (número + label) sobreposto na imagem no preview. */
+    badge?: BadgeData;
+    /** Slots opcionais — cada um vira um subcard ao lado direito do preview. */
+    extraCards?: ReactNode[];
+    /** Presets de imagem do site (mostrados na aba "Imagens" abaixo dos uploads). */
+    presets?: ImagePreset[];
+}
+
+interface BadgeOverlayProps {
+    badge?: BadgeData;
+    size?: 'sm' | 'md';
+}
+declare function BadgeOverlay({ badge }: BadgeOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+export { type BadgeData as B, type CropValue as C, type ImagePickerAspect as I, type RecentColorsAdapter as R, type UploadAdapter as U, BadgeOverlay as a, type ImagePickerProps as b, type ImagePreset as c, type UploadItem as d, type UploadedImage as e };