npm - @etus/ui - Versions diffs - 0.1.1 → 0.1.3 - Mend

@etus/ui 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1080) hide show

package/src/components/advanced/Portal/README.md DELETED Viewed

@@ -1,326 +0,0 @@
-# Portal
-## Visão Geral
-O Portal e um componente utilitario que renderiza seus filhos em um no DOM diferente do ponto de montagem do componente pai. Essencial para modals, tooltips, dropdowns e outros elementos que precisam escapar do contexto de overflow ou z-index.
-### Classificacao Atomica
-- **Categoria**: Utilities
-- **Subcategoria**: DOM Manipulation
-### Casos de Uso Comuns
-- Modals e dialogs
-- Tooltips e popovers
-- Dropdown menus
-- Toast notifications
-- Overlays e backdrops
-- Context menus
-### Relacao com Outros Componentes
-- **Dialog**: Usa Portal para renderizacao
-- **Popover**: Usa Portal para posicionamento
-- **Tooltip**: Usa Portal para exibicao
-- **DropdownMenu**: Usa Portal para menu
-- **Toast**: Usa Portal para notificacoes
-## Design Specs
-### Comportamento
-O Portal:
-1. Cria ou utiliza um container existente no DOM
-2. Renderiza children nesse container via React Portal
-3. Limpa o container ao desmontar (se criou)
-4. Preserva contexto React (Context, eventos)
-### Container Padrao
-- ID: `"etus-portal-root"` ou customizado
-- Posicao: Fim do `<body>` por padrao
-- Pode ser qualquer elemento DOM valido
-## API
-### Props
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `children` | `ReactNode` | required | Conteudo a ser portado |
-| `container` | `Element \| null` | `document.body` | Container de destino |
-| `key` | `string` | - | Key unica para o portal |
-| `disabled` | `boolean` | `false` | Renderiza inline (sem portal) |
-### Interfaces TypeScript
-```typescript
-export interface PortalProps {
-  children: React.ReactNode
-  container?: Element | DocumentFragment | null
-  key?: string | null
-  disabled?: boolean
-}
-```
-### Comparacao com Referencias
-| Design System | Caracteristicas |
-|---------------|-----------------|
-| **Radix UI** | Portal primitivo |
-| **Chakra UI** | Portal com container customizado |
-| **MUI** | Portal com disable option |
-| **Headless UI** | Portal para transicoes |
-| **React** | createPortal nativo |
-## Acessibilidade (A11y)
-### Consideracoes
-- Preserva ordem de foco logica
-- Mantem contexto ARIA
-- Nao quebra landmarks
-- Focus trap em modals (via componente pai)
-### Focus Management
-- Portal nao gerencia foco por si
-- Componentes que usam Portal devem gerenciar foco
-- Retorno de foco ao desmontar
-## Exemplos
-### Uso Basico
-```tsx
-import { Portal } from "@etus/ui"
-export function BasicPortal() {
-  return (
-    <Portal>
-      <div className="fixed inset-0 bg-black/50 z-50">
-        <div className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-background p-6 rounded-lg">
-          Modal Content
-        </div>
-      </div>
-    </Portal>
-  )
-}
-```
-### Com Container Customizado
-```tsx
-import { Portal } from "@etus/ui"
-export function CustomContainerPortal() {
-  const [container, setContainer] = React.useState<HTMLElement | null>(null)
-  return (
-    <>
-      <div ref={setContainer} id="custom-portal-container" />
-      <Portal container={container}>
-        <div>Content in custom container</div>
-      </Portal>
-    </>
-  )
-}
-```
-### Condicional
-```tsx
-import { Portal } from "@etus/ui"
-export function ConditionalPortal({ isOpen }) {
-  if (!isOpen) return null
-  return (
-    <Portal>
-      <div className="modal">
-        Content only rendered when open
-      </div>
-    </Portal>
-  )
-}
-```
-### Desabilitado (Inline)
-```tsx
-import { Portal } from "@etus/ui"
-export function InlinePortal({ inline }) {
-  return (
-    <Portal disabled={inline}>
-      <div>
-        {inline ? "Rendered inline" : "Rendered in portal"}
-      </div>
-    </Portal>
-  )
-}
-```
-### Multiplos Portals
-```tsx
-import { Portal } from "@etus/ui"
-export function MultiplePortals() {
-  return (
-    <>
-      <Portal key="notifications">
-        <div className="fixed top-4 right-4">Notifications</div>
-      </Portal>
-      <Portal key="modal">
-        <div className="fixed inset-0">Modal</div>
-      </Portal>
-      <Portal key="tooltip">
-        <div className="absolute">Tooltip</div>
-      </Portal>
-    </>
-  )
-}
-```
-### Com Transicao
-```tsx
-import { Portal } from "@etus/ui"
-import { Transition } from "@headlessui/react"
-export function AnimatedPortal({ show }) {
-  return (
-    <Portal>
-      <Transition
-        show={show}
-        enter="transition-opacity duration-200"
-        enterFrom="opacity-0"
-        enterTo="opacity-100"
-        leave="transition-opacity duration-150"
-        leaveFrom="opacity-100"
-        leaveTo="opacity-0"
-      >
-        <div className="fixed inset-0 bg-black/50" />
-      </Transition>
-    </Portal>
-  )
-}
-```
-### SSR Safe
-```tsx
-import { Portal } from "@etus/ui"
-export function SSRSafePortal({ children }) {
-  const [mounted, setMounted] = React.useState(false)
-  React.useEffect(() => {
-    setMounted(true)
-  }, [])
-  if (!mounted) return null
-  return <Portal>{children}</Portal>
-}
-```
-## Testes
-### Estrategias de Teste
-```typescript
-describe("Portal", () => {
-  it("renders children in document.body", () => {})
-  it("renders in custom container", () => {})
-  it("renders inline when disabled", () => {})
-  it("cleans up on unmount", () => {})
-  it("preserves React context", () => {})
-})
-```
-### Exemplo de Teste
-```typescript
-import { render, screen } from "@testing-library/react"
-import { Portal } from "./Portal"
-describe("Portal", () => {
-  it("renders content in body by default", () => {
-    render(
-      <div data-testid="parent">
-        <Portal>
-          <div data-testid="portal-content">Content</div>
-        </Portal>
-      </div>
-    )
-    const parent = screen.getByTestId("parent")
-    const content = screen.getByTestId("portal-content")
-    // Content should not be inside parent
-    expect(parent).not.toContainElement(content)
-    // Content should be in document body
-    expect(document.body).toContainElement(content)
-  })
-  it("renders in custom container", () => {
-    const container = document.createElement("div")
-    document.body.appendChild(container)
-    render(
-      <Portal container={container}>
-        <div data-testid="content">Content</div>
-      </Portal>
-    )
-    expect(container).toContainElement(screen.getByTestId("content"))
-    document.body.removeChild(container)
-  })
-  it("renders inline when disabled", () => {
-    render(
-      <div data-testid="parent">
-        <Portal disabled>
-          <div data-testid="content">Content</div>
-        </Portal>
-      </div>
-    )
-    const parent = screen.getByTestId("parent")
-    const content = screen.getByTestId("content")
-    expect(parent).toContainElement(content)
-  })
-  it("preserves React context", () => {
-    const TestContext = React.createContext("default")
-    render(
-      <TestContext.Provider value="custom">
-        <Portal>
-          <TestContext.Consumer>
-            {(value) => <div data-testid="content">{value}</div>}
-          </TestContext.Consumer>
-        </Portal>
-      </TestContext.Provider>
-    )
-    expect(screen.getByTestId("content")).toHaveTextContent("custom")
-  })
-})
-```
-## Roadmap / Features Futuras
-- Usa `ReactDOM.createPortal` internamente
-- SSR: Renderiza null no servidor
-- Cleanup automatico do container
-- Suporte a refs
-- Preserva event bubbling
-## Referências
-- [React createPortal](https://react.dev/reference/react-dom/createPortal)
-- [Radix Portal](https://www.radix-ui.com/primitives/docs/utilities/portal)
-- [MDN Portal](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/portal)

package/src/components/advanced/Portal/index.ts DELETED Viewed

@@ -1,9 +0,0 @@
-export type { PortalProps } from "./Portal.types"
-export { Portal } from "./Portal"
-export {
-  portalContainerVariants,
-  portalContentVariants,
-  portalOverlayVariants,
-} from "./Portal.variants"

package/src/components/advanced/RichTextEditor/README.md DELETED Viewed

@@ -1,383 +0,0 @@
-# RichTextEditor
-## Visão Geral
-O RichTextEditor e um editor de texto WYSIWYG (What You See Is What You Get) completo. Oferece formatacao visual em tempo real, suporte a midias, tabelas, mentions e extensibilidade via plugins. Construido sobre Tiptap/ProseMirror.
-### Classificacao Atomica
-- **Categoria**: Organisms
-- **Subcategoria**: Form / Text Editor
-### Casos de Uso Comuns
-- Editores de email
-- CMS e blogs
-- Documentacao
-- Comentarios ricos
-- Colaboracao em tempo real
-- Formularios com formatacao
-### Relacao com Outros Componentes
-- **MarkdownEditor**: Alternativa baseada em Markdown
-- **Toolbar**: Barra de formatacao
-- **Popover**: Menus de link/imagem
-- **Dialog**: Modais de insercao
-## Design Specs
-### Subcomponentes
-- **RichTextEditor**: Container principal com editor
-- **RichTextToolbar**: Barra de ferramentas flutuante ou fixa
-- **RichTextMenuBar**: Menu bar estilo documento
-- **RichTextBubbleMenu**: Menu contextual na selecao
-- **RichTextFloatingMenu**: Menu ao criar nova linha
-### Features Padrao
-- **Formatacao**: Bold, italic, underline, strikethrough
-- **Headings**: H1-H6
-- **Listas**: Ordered, unordered, task lists
-- **Blocos**: Quote, code block, horizontal rule
-- **Inline**: Links, inline code, highlight
-- **Media**: Imagens, videos, embeds
-- **Tabelas**: Criar e editar tabelas
-- **Mentions**: @users, #tags
-### Estados
-- **Editing**: Edicao ativa
-- **ReadOnly**: Apenas visualizacao
-- **Focused**: Editor com foco
-- **Disabled**: Edicao desabilitada
-- **Collaborative**: Edicao colaborativa
-### Tokens de Design
-#### Cores
-- Background: `bg-background`
-- Toolbar: `bg-muted`
-- Selection: `bg-primary/20`
-- Placeholder: `text-muted-foreground`
-#### Espacamento
-- Editor padding: `p-4`
-- Toolbar gap: `gap-1`
-- Block spacing: `mb-4`
-#### Tipografia
-- Body: System font stack
-- Code: `font-mono`
-- Headings: Hierarquia visual
-## API
-### Props
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `content` | `string \| JSONContent` | `""` | Conteudo inicial |
-| `onChange` | `(content: JSONContent) => void` | - | Callback de mudanca |
-| `onUpdate` | `(props: EditorEvents) => void` | - | Callback de update |
-| `placeholder` | `string` | - | Texto placeholder |
-| `editable` | `boolean` | `true` | Permite edicao |
-| `autofocus` | `boolean \| "start" \| "end"` | `false` | Auto focus |
-| `extensions` | `Extension[]` | `[]` | Extensoes adicionais |
-| `showToolbar` | `boolean` | `true` | Exibe toolbar |
-| `toolbarPosition` | `"top" \| "bottom" \| "floating"` | `"top"` | Posicao da toolbar |
-| `showBubbleMenu` | `boolean` | `true` | Menu na selecao |
-| `showFloatingMenu` | `boolean` | `false` | Menu em linha vazia |
-| `onImageUpload` | `(file: File) => Promise<string>` | - | Upload de imagem |
-### Interfaces TypeScript
-```typescript
-import type { Editor, JSONContent } from "@tiptap/react"
-export interface RichTextEditorProps {
-  content?: string | JSONContent
-  defaultContent?: string | JSONContent
-  onChange?: (content: JSONContent) => void
-  onUpdate?: (props: { editor: Editor }) => void
-  onBlur?: (props: { editor: Editor }) => void
-  onFocus?: (props: { editor: Editor }) => void
-  placeholder?: string
-  editable?: boolean
-  autofocus?: boolean | "start" | "end" | "all"
-  extensions?: Extension[]
-  showToolbar?: boolean
-  toolbarPosition?: "top" | "bottom" | "floating"
-  showBubbleMenu?: boolean
-  showFloatingMenu?: boolean
-  onImageUpload?: (file: File) => Promise<string>
-  className?: string
-  ref?: React.Ref<RichTextEditorRef>
-}
-export interface RichTextEditorRef {
-  editor: Editor | null
-  getHTML: () => string
-  getJSON: () => JSONContent
-  getText: () => string
-  setContent: (content: string | JSONContent) => void
-  focus: () => void
-  blur: () => void
-}
-```
-### Comparacao com Referencias
-| Design System | Caracteristicas |
-|---------------|-----------------|
-| **Tiptap** | Editor extensivel baseado em ProseMirror |
-| **Slate** | Framework de editor customizavel |
-| **Lexical** | Editor do Facebook/Meta |
-| **Quill** | Editor WYSIWYG classico |
-| **Draft.js** | Framework de editor do Facebook |
-| **CKEditor** | Editor enterprise |
-## Acessibilidade (A11y)
-### Atributos ARIA
-- `role="textbox"`: Area de edicao
-- `aria-multiline="true"`: Suporte a multiplas linhas
-- `aria-label`: Label do editor
-- Toolbar com `role="toolbar"`
-### Navegacao por Teclado
-- `Tab`: Move entre toolbar e editor
-- `Ctrl/Cmd + B`: Bold
-- `Ctrl/Cmd + I`: Italic
-- `Ctrl/Cmd + U`: Underline
-- `Ctrl/Cmd + K`: Inserir link
-- `Ctrl/Cmd + Z/Y`: Undo/Redo
-### Conformidade WCAG
-- **Nivel alvo**: WCAG 2.1 AA
-- Toolbar navegavel por teclado
-- Anuncio de formatacao aplicada
-- Mensagens de erro acessiveis
-## Exemplos
-### Uso Basico
-```tsx
-import { RichTextEditor } from "@etus/ui"
-export function BasicEditor() {
-  const [content, setContent] = React.useState("")
-  return (
-    <RichTextEditor
-      content={content}
-      onChange={(json) => setContent(JSON.stringify(json))}
-      placeholder="Start writing..."
-    />
-  )
-}
-```
-### Com Todas as Features
-```tsx
-import { RichTextEditor } from "@etus/ui"
-export function FullFeaturedEditor() {
-  return (
-    <RichTextEditor
-      content={initialContent}
-      onChange={handleChange}
-      showToolbar
-      showBubbleMenu
-      showFloatingMenu
-      onImageUpload={async (file) => {
-        const url = await uploadImage(file)
-        return url
-      }}
-      placeholder="Write something amazing..."
-    />
-  )
-}
-```
-### ReadOnly / Preview
-```tsx
-import { RichTextEditor } from "@etus/ui"
-export function ContentViewer({ content }) {
-  return (
-    <RichTextEditor
-      content={content}
-      editable={false}
-      showToolbar={false}
-    />
-  )
-}
-```
-### Com Extensoes Custom
-```tsx
-import { RichTextEditor } from "@etus/ui"
-import { Mention } from "@tiptap/extension-mention"
-import { Placeholder } from "@tiptap/extension-placeholder"
-export function ExtendedEditor() {
-  return (
-    <RichTextEditor
-      extensions={[
-        Mention.configure({
-          suggestion: mentionSuggestion,
-        }),
-        Placeholder.configure({
-          placeholder: "Type @ to mention someone...",
-        }),
-      ]}
-    />
-  )
-}
-```
-### Com Formulario
-```tsx
-import { RichTextEditor } from "@etus/ui"
-import { useForm, Controller } from "react-hook-form"
-export function EditorForm() {
-  const { control, handleSubmit } = useForm()
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <Controller
-        name="body"
-        control={control}
-        rules={{ required: true }}
-        render={({ field }) => (
-          <RichTextEditor
-            content={field.value}
-            onChange={(content) => field.onChange(content)}
-            onBlur={field.onBlur}
-          />
-        )}
-      />
-      <Button type="submit">Save</Button>
-    </form>
-  )
-}
-```
-### Toolbar Flutuante
-```tsx
-import { RichTextEditor } from "@etus/ui"
-export function FloatingToolbarEditor() {
-  return (
-    <RichTextEditor
-      toolbarPosition="floating"
-      showBubbleMenu
-      className="min-h-[300px]"
-    />
-  )
-}
-```
-### Colaborativo (Conceitual)
-```tsx
-import { RichTextEditor } from "@etus/ui"
-import { Collaboration } from "@tiptap/extension-collaboration"
-import * as Y from "yjs"
-import { WebsocketProvider } from "y-websocket"
-const ydoc = new Y.Doc()
-const provider = new WebsocketProvider("ws://localhost:1234", "room", ydoc)
-export function CollaborativeEditor() {
-  return (
-    <RichTextEditor
-      extensions={[
-        Collaboration.configure({
-          document: ydoc,
-        }),
-      ]}
-    />
-  )
-}
-```
-## Testes
-### Estrategias de Teste
-```typescript
-describe("RichTextEditor", () => {
-  it("renders editor", () => {})
-  it("applies formatting", () => {})
-  it("handles content change", () => {})
-  it("shows bubble menu on selection", () => {})
-  it("inserts links", () => {})
-  it("uploads images", () => {})
-})
-```
-### Exemplo de Teste
-```typescript
-import { render, screen } from "@testing-library/react"
-import userEvent from "@testing-library/user-event"
-import { RichTextEditor } from "./RichTextEditor"
-describe("RichTextEditor", () => {
-  it("renders with placeholder", () => {
-    render(<RichTextEditor placeholder="Start typing..." />)
-    expect(screen.getByText("Start typing...")).toBeInTheDocument()
-  })
-  it("applies bold formatting", async () => {
-    const onChange = vi.fn()
-    render(<RichTextEditor onChange={onChange} />)
-    const editor = screen.getByRole("textbox")
-    await userEvent.type(editor, "Hello World")
-    // Select text
-    await userEvent.tripleClick(editor)
-    // Click bold button
-    await userEvent.click(screen.getByRole("button", { name: /bold/i }))
-    expect(onChange).toHaveBeenCalled()
-    // Verify content contains bold marks
-  })
-  it("shows bubble menu on selection", async () => {
-    render(<RichTextEditor content="<p>Hello World</p>" showBubbleMenu />)
-    const editor = screen.getByRole("textbox")
-    await userEvent.tripleClick(editor)
-    await waitFor(() => {
-      expect(screen.getByRole("toolbar")).toBeVisible()
-    })
-  })
-})
-```
-## Roadmap / Features Futuras
-- Construido sobre Tiptap v2 / ProseMirror
-- Schema configuravel para validacao
-- Output: HTML, JSON, ou Markdown
-- Suporte a colaboracao via Yjs
-- Extensoes modulares
-## Referências
-- [Tiptap Documentation](https://tiptap.dev/)
-- [ProseMirror](https://prosemirror.net/)
-- [Lexical](https://lexical.dev/)
-- [WCAG Rich Text Editor](https://www.w3.org/WAI/tutorials/forms/custom-controls/)