bubble-toolbar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 el_jijuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# 🫧 Bubble Toolbar
+
+> Componente de barra flotante responsiva con efecto **blurred glass** (glassmorphism) para **React 18 y 19** con **TypeScript**, organizado por grupos y con morfología adaptativa inteligente (círculo ↔ cápsula).
+
+![Bubble Toolbar Morphology](https://raw.githubusercontent.com/ElJijuna/bubble-toolbar/main/assets/banner.png)
+
+---
+
+## ✨ Características
+
+- ⚛️ **Compatibilidad Total**: Diseñado y probado con **React 18** y **React 19** usando `forwardRef` y tipado estricto en TypeScript.
+- 🔮 **Definición por Grupos**: Define la barra pasando arreglos de nodos o mediante sintaxis de componentes compuestos (`BubbleToolbar.Group`).
+- 🔘 **Morfología Adaptativa Dinámica**:
+  - **1 solo nodo** $\rightarrow$ se renderiza como un **círculo** perfecto (`aspect-ratio: 1/1`).
+  - **Más de 1 nodo** $\rightarrow$ se convierte en un **rectángulo redondeado (cápsula / pill)**, respetando la curvatura en los extremos para mantener el equilibrio visual exacto con las burbujas circulares.
+- 🪟 **Blurred Glass (Frosted Glassmorphism)**: Efecto translúcido con desenfoque de fondo (`backdrop-filter: blur(16px)`), bordes frosted, sombras suaves y soporte para temas claro, oscuro o automático.
+- 📱 **Flotante y Responsivo**: Posicionamiento fijo o relativo, centrado automático y desplazamiento horizontal suave sin barras de scroll invasivas en pantallas móviles.
+- 🧪 **100% Testeado con Jest**: Suite integral de pruebas unitarias y de integración con `@testing-library/react`.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install bubble-toolbar
+# o con yarn / pnpm / bun
+pnpm add bubble-toolbar
+```
+
+---
+
+## 🚀 Uso Rápido
+
+### Ejemplo con definición por grupos (prop `groups`)
+
+Tal como en tu especificación:
+
+```tsx
+import React from 'react';
+import { BubbleToolbar, BubbleIconButton, BubbleArea } from 'bubble-toolbar';
+import 'bubble-toolbar/styles.css'; // Opcional, los estilos inline glass ya vienen incluidos
+
+function App() {
+  return (
+    <BubbleToolbar
+      position="bottom"
+      theme="glass"
+      groups={[
+        // Grupo 1: 1 solo nodo => Círculo
+        [<Logo key="logo" />],
+
+        // Grupo 2: Múltiples nodos => Rectángulo redondeado (Pill)
+        [
+          <BubbleIconButton key="search" name="search" />,
+          <BubbleArea key="area">
+            <input placeholder="Buscar o escribir /" />
+          </BubbleArea>,
+        ],
+
+        // Grupos 3, 4 y 5: 1 solo nodo cada uno => Círculos
+        [<BubbleIconButton key="theme" name="theme" />],
+        [<BubbleIconButton key="chat" name="chat" />],
+        [<BubbleIconButton key="notif" name="notifications" badge={3} />],
+      ]}
+    />
+  );
+}
+```
+
+### Ejemplo con Componentes Compuestos (`BubbleToolbar.Group`)
+
+```tsx
+import { BubbleToolbar, BubbleIconButton, BubbleArea } from 'bubble-toolbar';
+
+function FloatingMenu() {
+  return (
+    <BubbleToolbar position="bottom" theme="glass">
+      {/* 1 nodo: Círculo */}
+      <BubbleToolbar.Group>
+        <Logo />
+      </BubbleToolbar.Group>
+
+      {/* 2 nodos: Rectángulo redondeado (Cápsula) */}
+      <BubbleToolbar.Group>
+        <BubbleIconButton name="search" />
+        <BubbleArea>
+          <input placeholder="Buscar..." />
+        </BubbleArea>
+      </BubbleToolbar.Group>
+
+      {/* 1 nodo: Círculo */}
+      <BubbleToolbar.Group>
+        <BubbleIconButton name="theme" />
+      </BubbleToolbar.Group>
+    </BubbleToolbar>
+  );
+}
+```
+
+---
+
+## 📐 Morfología Visual
+
+| Contenido del Grupo | Forma Resultante | Comportamiento |
+| :--- | :---: | :--- |
+| **1 Nodo** (`[<Logo />]`) | 🟡 **Círculo** | Ancho y alto fijados a `--bubble-size` (por defecto `48px`). `aspect-ratio: 1 / 1`. Contenido centrado. |
+| **> 1 Nodo** (`[<Search />, <Area />]`) | 💊 **Cápsula / Pill** | Altura fijada a `--bubble-size`, ancho dinámico según contenido con padding lateral. Los extremos redondeados coinciden exactamente con el diámetro de las burbujas circulares adyacentes para una armonía visual simétrica. |
+
+---
+
+## 🛠️ API Reference
+
+### `<BubbleToolbar />`
+
+| Prop | Tipo | Por defecto | Descripción |
+| :--- | :--- | :---: | :--- |
+| `groups` | `ReactNode[][]` | `undefined` | Arreglo de arreglos con los nodos agrupados. |
+| `children` | `ReactNode` | `undefined` | Elementos JSX hijos (ej. `<BubbleToolbar.Group>`). |
+| `position` | `'bottom' \| 'top' \| 'static' \| 'custom'` | `'bottom'` | Posicionamiento de la barra en pantalla. |
+| `theme` | `'glass' \| 'light' \| 'dark' \| 'auto'` | `'glass'` | Estilo visual y translucidez. |
+| `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | Altura de la barra / diámetro de los círculos (40px, 48px, 56px o px numérico). |
+| `blurred` | `boolean` | `true` | Activa el efecto frosted glass (`backdrop-filter: blur`). |
+| `blurAmount`| `number \| string` | `16` | Cantidad de desenfoque en píxeles. |
+| `groupGap` | `number \| string` | `8` | Espacio entre cada burbuja/grupo. |
+| `itemGap` | `number \| string` | `8` | Espacio entre elementos dentro de un grupo cápsula. |
+| `bordered` | `boolean` | `true` | Muestra bordes sutiles con brillo frosted. |
+| `shadow` | `boolean \| string` | `true` | Sombra flotante proyectada. |
+
+### `<BubbleGroup />` (o `<BubbleToolbar.Group />`)
+
+| Prop | Tipo | Por defecto | Descripción |
+| :--- | :--- | :---: | :--- |
+| `children` | `ReactNode` | `undefined` | Nodos que contiene el grupo. |
+| `shape` | `'circle' \| 'pill'` | Automático | Fuerza una forma específica omitiendo el cálculo automático por cantidad de nodos. |
+| `size` | `'sm' \| 'md' \| 'lg' \| number` | Heredado | Permite sobrescribir el tamaño para este grupo. |
+| `itemGap` | `number \| string` | Heredado | Espaciado entre elementos del grupo. |
+
+### `<BubbleIconButton />`
+
+| Prop | Tipo | Por defecto | Descripción |
+| :--- | :--- | :---: | :--- |
+| `name` | `'search' \| 'theme' \| 'chat' \| 'notifications' \| 'logo' \| 'close'` | `undefined` | Nombre del icono vectorial SVG pre-integrado. |
+| `icon` | `ReactNode` | `undefined` | Icono SVG personalizado. |
+| `badge` | `ReactNode \| number \| string` | `undefined` | Indicador o contador de notificación. |
+| `active` | `boolean` | `false` | Estado activo / seleccionado. |
+| `tooltip` | `string` | `undefined` | Texto emergente y accesible. |
+
+---
+
+## 🧪 Pruebas con Jest
+
+Ejecutar la suite completa de pruebas:
+
+```bash
+npm test
+```
+
+Ejecutar con reporte de cobertura de código:
+
+```bash
+npm run test:coverage
+```
+
+Ejecutar chequeo de tipos en TypeScript:
+
+```bash
+npm run typecheck
+```
+
+### Ejecutar Storybook en local
+
+Para explorar visualmente los componentes, probar el cambio dinámico de formas y los temas:
+
+```bash
+npm run storybook
+```
+
+Compilar Storybook estático:
+
+```bash
+npm run build-storybook
+```
+
+Compilar la librería para distribución (ESM, CJS y `.d.ts`):
+
+```bash
+npm run build
+```
+
+---
+
+## 📄 Licencia
+
+MIT © ElJijuna
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/index.d.mts

@@ -0,0 +1,188 @@
+import * as React from 'react';
+import React__default, { HTMLAttributes, ReactNode, CSSProperties, ButtonHTMLAttributes } from 'react';
+
+type BubbleToolbarTheme = 'light' | 'dark' | 'auto' | 'glass';
+type BubbleToolbarPosition = 'bottom' | 'top' | 'static' | 'custom';
+type BubbleToolbarSize = 'sm' | 'md' | 'lg' | number;
+type BubbleShape = 'circle' | 'pill';
+interface BubbleToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Definition of items by groups.
+     * Example:
+     * [
+     *   [<Logo />],
+     *   [<IconButton name="search" />, <ToolbarArea />],
+     *   [<IconButton name="theme" />],
+     *   [<IconButton name="chat" />],
+     *   [<IconButton name="notifications" />]
+     * ]
+     */
+    groups?: ReactNode[][];
+    /**
+     * Alternatively, declarative composition using BubbleToolbar.Group children.
+     */
+    children?: ReactNode;
+    /**
+     * Placement on the screen.
+     * @default 'bottom'
+     */
+    position?: BubbleToolbarPosition;
+    /**
+     * Visual theme styling.
+     * @default 'glass'
+     */
+    theme?: BubbleToolbarTheme;
+    /**
+     * Toolbar height / bubble diameter.
+     * Preset 'sm' (40px), 'md' (48px), 'lg' (56px) or numeric pixels.
+     * @default 'md'
+     */
+    size?: BubbleToolbarSize;
+    /**
+     * Whether to apply the blurred frosted glass effect (backdrop-filter: blur).
+     * @default true
+     */
+    blurred?: boolean;
+    /**
+     * Amount of backdrop blur in pixels or CSS string.
+     * @default 16
+     */
+    blurAmount?: number | string;
+    /**
+     * Spacing between bubble groups.
+     * @default 8
+     */
+    groupGap?: number | string;
+    /**
+     * Spacing between elements inside a multi-node pill group.
+     * @default 8
+     */
+    itemGap?: number | string;
+    /**
+     * Whether to display subtle borders around bubbles.
+     * @default true
+     */
+    bordered?: boolean;
+    /**
+     * Whether to render floating shadow, or custom shadow CSS string.
+     * @default true
+     */
+    shadow?: boolean | string;
+    /**
+     * Custom CSS class name for toolbar container.
+     */
+    className?: string;
+    /**
+     * Inline CSS styles for toolbar container.
+     */
+    style?: CSSProperties;
+    /**
+     * Accessible ARIA label for toolbar.
+     * @default 'Toolbar'
+     */
+    ariaLabel?: string;
+}
+interface BubbleGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Elements inside this group.
+     * 1 node renders as a circle.
+     * More than 1 node renders as a pill / rounded rectangle.
+     */
+    children?: ReactNode;
+    /**
+     * Force shape instead of auto-calculating from children count.
+     */
+    shape?: BubbleShape;
+    /**
+     * Override bubble size / height for this specific group.
+     */
+    size?: BubbleToolbarSize;
+    /**
+     * Gap between items in this group.
+     */
+    itemGap?: number | string;
+    /**
+     * Custom CSS class name.
+     */
+    className?: string;
+    /**
+     * Inline CSS styles.
+     */
+    style?: CSSProperties;
+}
+interface BubbleIconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Icon identifier or label for standard icons.
+     */
+    name?: string;
+    /**
+     * Custom icon element or SVG.
+     */
+    icon?: ReactNode;
+    /**
+     * Active or toggled state.
+     * @default false
+     */
+    active?: boolean;
+    /**
+     * Optional badge count or indicator.
+     */
+    badge?: ReactNode | number | string;
+    /**
+     * Tooltip text.
+     */
+    tooltip?: string;
+    /**
+     * Explicit accessible label.
+     */
+    ariaLabel?: string;
+}
+interface BubbleAreaProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Content inside the toolbar area (e.g. search input, label, sliders).
+     */
+    children?: ReactNode;
+    /**
+     * Minimum width for the area.
+     */
+    minWidth?: number | string;
+    /**
+     * Maximum width for the area.
+     */
+    maxWidth?: number | string;
+}
+
+declare const BubbleGroup: React__default.ForwardRefExoticComponent<BubbleGroupProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface BubbleToolbarComponent extends React__default.ForwardRefExoticComponent<BubbleToolbarProps & React__default.RefAttributes<HTMLDivElement>> {
+    Group: typeof BubbleGroup;
+}
+declare const BubbleToolbar: BubbleToolbarComponent;
+
+declare const BubbleIconButton: React__default.ForwardRefExoticComponent<BubbleIconButtonProps & React__default.RefAttributes<HTMLButtonElement>>;
+
+declare const BubbleArea: React__default.ForwardRefExoticComponent<BubbleAreaProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface BubbleToolbarContextValue {
+    size: BubbleToolbarSize;
+    theme: BubbleToolbarTheme;
+    blurred: boolean;
+    blurAmount: number | string;
+    itemGap: number | string;
+    bordered: boolean;
+    shadow: boolean | string;
+}
+declare const BubbleToolbarContext: React.Context<BubbleToolbarContextValue>;
+declare const useBubbleToolbar: () => BubbleToolbarContextValue;
+
+/**
+ * Returns an array of non-null, non-undefined, non-boolean child elements.
+ * Unpacks React.Fragment if encountered at the top level.
+ */
+declare function getValidChildren(children: ReactNode): ReactNode[];
+
+declare function resolveSize(size: BubbleToolbarSize): number;
+declare function formatPx(val: number | string): string;
+declare function getGlassStyles(theme: BubbleToolbarTheme, blurred: boolean, blurAmount: number | string, bordered: boolean, shadow: boolean | string): CSSProperties;
+
+export { BubbleArea, type BubbleAreaProps, BubbleGroup, type BubbleGroupProps, BubbleIconButton, type BubbleIconButtonProps, type BubbleShape, BubbleToolbar, type BubbleToolbarComponent, BubbleToolbarContext, type BubbleToolbarPosition, type BubbleToolbarProps, type BubbleToolbarSize, type BubbleToolbarTheme, formatPx, getGlassStyles, getValidChildren, resolveSize, useBubbleToolbar };

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+import * as React from 'react';
+import React__default, { HTMLAttributes, ReactNode, CSSProperties, ButtonHTMLAttributes } from 'react';
+
+type BubbleToolbarTheme = 'light' | 'dark' | 'auto' | 'glass';
+type BubbleToolbarPosition = 'bottom' | 'top' | 'static' | 'custom';
+type BubbleToolbarSize = 'sm' | 'md' | 'lg' | number;
+type BubbleShape = 'circle' | 'pill';
+interface BubbleToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Definition of items by groups.
+     * Example:
+     * [
+     *   [<Logo />],
+     *   [<IconButton name="search" />, <ToolbarArea />],
+     *   [<IconButton name="theme" />],
+     *   [<IconButton name="chat" />],
+     *   [<IconButton name="notifications" />]
+     * ]
+     */
+    groups?: ReactNode[][];
+    /**
+     * Alternatively, declarative composition using BubbleToolbar.Group children.
+     */
+    children?: ReactNode;
+    /**
+     * Placement on the screen.
+     * @default 'bottom'
+     */
+    position?: BubbleToolbarPosition;
+    /**
+     * Visual theme styling.
+     * @default 'glass'
+     */
+    theme?: BubbleToolbarTheme;
+    /**
+     * Toolbar height / bubble diameter.
+     * Preset 'sm' (40px), 'md' (48px), 'lg' (56px) or numeric pixels.
+     * @default 'md'
+     */
+    size?: BubbleToolbarSize;
+    /**
+     * Whether to apply the blurred frosted glass effect (backdrop-filter: blur).
+     * @default true
+     */
+    blurred?: boolean;
+    /**
+     * Amount of backdrop blur in pixels or CSS string.
+     * @default 16
+     */
+    blurAmount?: number | string;
+    /**
+     * Spacing between bubble groups.
+     * @default 8
+     */
+    groupGap?: number | string;
+    /**
+     * Spacing between elements inside a multi-node pill group.
+     * @default 8
+     */
+    itemGap?: number | string;
+    /**
+     * Whether to display subtle borders around bubbles.
+     * @default true
+     */
+    bordered?: boolean;
+    /**
+     * Whether to render floating shadow, or custom shadow CSS string.
+     * @default true
+     */
+    shadow?: boolean | string;
+    /**
+     * Custom CSS class name for toolbar container.
+     */
+    className?: string;
+    /**
+     * Inline CSS styles for toolbar container.
+     */
+    style?: CSSProperties;
+    /**
+     * Accessible ARIA label for toolbar.
+     * @default 'Toolbar'
+     */
+    ariaLabel?: string;
+}
+interface BubbleGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Elements inside this group.
+     * 1 node renders as a circle.
+     * More than 1 node renders as a pill / rounded rectangle.
+     */
+    children?: ReactNode;
+    /**
+     * Force shape instead of auto-calculating from children count.
+     */
+    shape?: BubbleShape;
+    /**
+     * Override bubble size / height for this specific group.
+     */
+    size?: BubbleToolbarSize;
+    /**
+     * Gap between items in this group.
+     */
+    itemGap?: number | string;
+    /**
+     * Custom CSS class name.
+     */
+    className?: string;
+    /**
+     * Inline CSS styles.
+     */
+    style?: CSSProperties;
+}
+interface BubbleIconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Icon identifier or label for standard icons.
+     */
+    name?: string;
+    /**
+     * Custom icon element or SVG.
+     */
+    icon?: ReactNode;
+    /**
+     * Active or toggled state.
+     * @default false
+     */
+    active?: boolean;
+    /**
+     * Optional badge count or indicator.
+     */
+    badge?: ReactNode | number | string;
+    /**
+     * Tooltip text.
+     */
+    tooltip?: string;
+    /**
+     * Explicit accessible label.
+     */
+    ariaLabel?: string;
+}
+interface BubbleAreaProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Content inside the toolbar area (e.g. search input, label, sliders).
+     */
+    children?: ReactNode;
+    /**
+     * Minimum width for the area.
+     */
+    minWidth?: number | string;
+    /**
+     * Maximum width for the area.
+     */
+    maxWidth?: number | string;
+}
+
+declare const BubbleGroup: React__default.ForwardRefExoticComponent<BubbleGroupProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface BubbleToolbarComponent extends React__default.ForwardRefExoticComponent<BubbleToolbarProps & React__default.RefAttributes<HTMLDivElement>> {
+    Group: typeof BubbleGroup;
+}
+declare const BubbleToolbar: BubbleToolbarComponent;
+
+declare const BubbleIconButton: React__default.ForwardRefExoticComponent<BubbleIconButtonProps & React__default.RefAttributes<HTMLButtonElement>>;
+
+declare const BubbleArea: React__default.ForwardRefExoticComponent<BubbleAreaProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface BubbleToolbarContextValue {
+    size: BubbleToolbarSize;
+    theme: BubbleToolbarTheme;
+    blurred: boolean;
+    blurAmount: number | string;
+    itemGap: number | string;
+    bordered: boolean;
+    shadow: boolean | string;
+}
+declare const BubbleToolbarContext: React.Context<BubbleToolbarContextValue>;
+declare const useBubbleToolbar: () => BubbleToolbarContextValue;
+
+/**
+ * Returns an array of non-null, non-undefined, non-boolean child elements.
+ * Unpacks React.Fragment if encountered at the top level.
+ */
+declare function getValidChildren(children: ReactNode): ReactNode[];
+
+declare function resolveSize(size: BubbleToolbarSize): number;
+declare function formatPx(val: number | string): string;
+declare function getGlassStyles(theme: BubbleToolbarTheme, blurred: boolean, blurAmount: number | string, bordered: boolean, shadow: boolean | string): CSSProperties;
+
+export { BubbleArea, type BubbleAreaProps, BubbleGroup, type BubbleGroupProps, BubbleIconButton, type BubbleIconButtonProps, type BubbleShape, BubbleToolbar, type BubbleToolbarComponent, BubbleToolbarContext, type BubbleToolbarPosition, type BubbleToolbarProps, type BubbleToolbarSize, type BubbleToolbarTheme, formatPx, getGlassStyles, getValidChildren, resolveSize, useBubbleToolbar };