@andreagiugni/tailwind-dashboard-ui 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Andrea Giugni
+Copyright (c) 2023 TailAdmin (original TailAdmin dashboard this library was extracted from)
+
+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

@@ -0,0 +1,282 @@
+# @andreagiugni/tailwind-dashboard-ui
+
+Reusable React + Tailwind CSS v4 dashboard components extracted from TailAdmin. Every primitive
+ships with its Tailwind styling, extends the underlying element's native HTML attributes (so
+`onClick`, `onDoubleClick`, `aria-*`, `data-*`, … just work), exposes named style variants, and —
+where visually meaningful — accepts inline `bgColor` / `textColor` / `borderColor` overrides.
+
+Dual ESM + CJS builds with TypeScript types. Every component — including the data-viz widgets
+(charts, calendar, map) — is exported from the single package entry point.
+
+## Install
+
+```bash
+npm i @andreagiugni/tailwind-dashboard-ui
+```
+
+### Peer dependencies
+
+The core package requires:
+
+- **React 18 or 19** (`react`, `react-dom`)
+- **Tailwind CSS v4** (`tailwindcss@^4`)
+
+`clsx`, `tailwind-merge`, and `flatpickr` (used by `DatePicker`) are bundled runtime dependencies —
+you do not need to install them yourself.
+
+The following heavy libraries are **optional** peers, only needed if you use the matching
+data-viz component:
+
+| Component | Optional peer deps |
+|---|---|
+| `BarChart`, `LineChart` | `apexcharts`, `react-apexcharts` |
+| `Calendar` | `@fullcalendar/core`, `@fullcalendar/react`, `@fullcalendar/daygrid`, `@fullcalendar/timegrid`, `@fullcalendar/list`, `@fullcalendar/interaction` |
+| `CountryMap` | `@react-jvectormap/core`, `@react-jvectormap/world` |
+| `Editor` (WYSIWYG) | `@tiptap/react`, `@tiptap/pm`, `@tiptap/starter-kit`, `@tiptap/extension-link`, `@tiptap/extension-placeholder` |
+
+Install only the ones for the components you use, e.g.:
+
+```bash
+npm i apexcharts react-apexcharts          # for BarChart / LineChart
+npm i @tiptap/react @tiptap/pm @tiptap/starter-kit @tiptap/extension-link @tiptap/extension-placeholder  # for Editor
+```
+
+> **SSR note:** the data-viz components and the `Editor` touch `window`/the DOM at render time.
+> In server-rendered frameworks (e.g. Next.js) render them client-only — for example with
+> `next/dynamic(() => import('@andreagiugni/tailwind-dashboard-ui').then(m => m.BarChart), { ssr: false })`.
+> They are code-split into their own chunks and never executed unless you actually import them, so
+> the rest of the library stays SSR-safe and light.
+
+## Tailwind setup
+
+The library ships its design tokens as an importable stylesheet. Add this line to your app's
+Tailwind entry CSS (the file that already contains `@import 'tailwindcss';`):
+
+```css
+@import '@andreagiugni/tailwind-dashboard-ui/theme.css';
+```
+
+`theme.css` registers the full TailAdmin token set (brand / blue-light / gray / orange / success /
+error / warning palettes, `--text-theme-*`, `--shadow-theme-*`, `--z-index-*`) inside an `@theme`
+block, plus base layer rules.
+
+**Dark mode** is driven by the `.dark` class. The theme defines a custom `dark` variant against an
+ancestor `.dark`, so toggle dark mode by adding/removing the `dark` class on `<html>` (or any
+ancestor):
+
+```html
+<html class="dark">
+```
+
+The `ThemeToggleButton` component is controllable for this purpose (`theme` + `onToggle` props).
+
+## Importing components
+
+Everything is exported from the single package entry point:
+
+```tsx
+import {
+  Button,
+  Badge,
+  Alert,
+  Input,
+  Select,
+  Modal,
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableCell,
+  // hero-ui parity additions
+  Accordion,
+  AccordionItem,
+  Tabs,
+  Tab,
+  Tooltip,
+  Popover,
+  Drawer,
+  Chip,
+  Progress,
+  Spinner,
+  Skeleton,
+  Slider,
+  Code,
+  Snippet,
+  // data viz + editor (see SSR note above)
+  BarChart,
+  LineChart,
+  Calendar,
+  CountryMap,
+  Editor,
+} from '@andreagiugni/tailwind-dashboard-ui';
+```
+
+## Props model
+
+Three conventions apply across the library:
+
+1. **Native handlers via HTML-attribute extension.** Each component's props extend the root
+   element's React HTML attribute type (e.g. `ButtonHTMLAttributes`), so every native handler and
+   attribute (`onClick`, `onDoubleClick`, `onMouseEnter`, `aria-*`, `data-*`, …) is available with
+   zero extra wiring and is forwarded onto the underlying element.
+2. **Named variants.** Visual states are selected with discrete props such as `variant`, `size`,
+   and `color` instead of class strings.
+3. **Inline color overrides.** Where meaningful, components accept `bgColor`, `textColor`, and
+   `borderColor`. These map to inline `style` (`backgroundColor` / `color` / `borderColor`) and let
+   you escape the named palette for one-off colors. A consumer-supplied `style` prop always wins.
+
+```tsx
+import { Button, Badge } from '@andreagiugni/tailwind-dashboard-ui';
+import '@andreagiugni/tailwind-dashboard-ui/theme.css'; // in your Tailwind entry CSS
+
+<Button variant="primary" onDoubleClick={handle}>Save</Button>
+<Button bgColor="#ff5722" textColor="#fff">Custom</Button>
+<Badge color="success">Active</Badge>
+```
+
+## Component reference
+
+Legend: **(+native)** = also extends the element's native HTML attributes.
+**(+override)** = accepts `bgColor` / `textColor` / `borderColor`.
+
+### Core UI
+
+| Component | Key props |
+|---|---|
+| `Button` | `variant` (primary/outline), `size` (sm/md), `startIcon`, `endIcon`, `disabled`, (+native button) (+override) |
+| `Badge` | `variant` (light/solid), `color` (primary/success/error/warning/info/light/dark), `size` (sm/md), `startIcon`, `endIcon`, (+native span) (+override) |
+| `Ribbon` | `variant` (corner/rounded/flag), `color` (primary/success/error/warning/info/dark), `position` (top-left/top-right/bottom-left/bottom-right), `children` (label), (+native span) (+override) — place inside a `relative` host (corner needs `overflow-hidden`) |
+| `Alert` | `variant` (success/error/warning/info), `title`, `message`, `showLink`, `linkHref`, `linkText`, `icon?` (override icon), (+native div) |
+| `Avatar` | `src`, `alt`, `size` (xsmall…xxlarge), `status` (online/offline/busy/none), `statusColor?`, (+native img) |
+| `AvatarText` | `children`, `className`, (+native div) |
+| `Dropdown` | `isOpen`, `onClose`, `children`, (+native div) |
+| `DropdownItem` | `variant` (default/primary/outline, like Button), `bgColor`/`textColor`/`borderColor` overrides, `tag` (a/button), `href`, `onClick`, `onItemClick`, `baseClassName` (full override) |
+| `Modal` | `isOpen`, `onClose`, `showCloseButton`, `isFullscreen`, `closeOnBackdrop?`, `closeOnEsc?`; **alert preset** → `variant` (`success`/`info`/`warning`/`danger`) + `title`, `description`, `actionText?`, `onAction?`; (+native div) |
+| `Table` / `TableHeader` / `TableBody` / `TableRow` / `TableCell` | `children`, `isHeader` (cell), (+native table elements; `onClick` / `onDoubleClick` on rows & cells) |
+| `Pagination` | `currentPage`, `totalPages`, `onPageChange` |
+| `DataTable` | `data`, `columns` (`key`, `header`, `sortable?`, `align?`, `render?`), `rowsPerPage?`, `rowsPerPageOptions?`, `searchable?`, `searchKeys?`, `defaultSortKey?` / `defaultSortDirection?`, `pagination?`, `showSizeSelector?`, `onRowClick?`, `getRowId?`, `emptyContent?` — generic, search + per-column sort + pagination built in |
+| `Breadcrumb` | `pageTitle`, `items?`, (+native) |
+| `ThemeToggleButton` | `theme?` (controlled), `onToggle?`, (+native button) |
+| `Accordion` / `AccordionItem` | `selectionMode` (single/multiple), `expandedKeys` / `defaultExpandedKeys`, `onExpandedChange`; item: `itemKey`, `title`, `startContent?`, `disabled` |
+| `Tabs` / `Tab` | `variant` (underline/solid/pill), `selectedKey` / `defaultSelectedKey`, `onSelectionChange`, `color?`; tab: `tabKey`, `title`, `disabled` |
+| `Chip` | `color`, `variant` (light/solid), `size`, `startIcon`, `endIcon`, `avatar?`, `onClose?`, (+native span) (+override) |
+| `Code` | `color` (primary/success/error/warning/info/default), `size` (sm/md), (+native code) (+override) |
+| `Snippet` | `code` (string \| string[]), `symbol?`, `hideCopyButton?`, `hideSymbol?`, `size`, (+override) |
+| `Progress` | `value`, `maxValue?`, `color`, `size` (sm/md/lg), `label?`, `showValueLabel?`, `isIndeterminate?` |
+| `Spinner` | `size` (sm/md/lg), `color`, `label?` |
+| `Skeleton` | `isLoaded`, `width?`, `height?`, `className`, `children?` |
+
+### Overlays
+
+| Component | Key props |
+|---|---|
+| `Tooltip` | `content`, `placement` (top/right/bottom/left), `delay?`, `disabled?`, (+native span) (+override) |
+| `Popover` | `trigger`, `placement`, `isOpen?` / `defaultOpen?` / `onOpenChange?`, `closeOnOutsideClick?`, `closeOnEsc?` |
+| `Drawer` | `isOpen`, `onClose`, `placement` (left/right/top/bottom), `showCloseButton?`, `closeOnBackdrop?`, `closeOnEsc?`, `size?`, (+native div) |
+
+### Form controls
+
+| Component | Key props |
+|---|---|
+| `Input` | `type`, `value` / `defaultValue`, `onChange`, `success`, `error`, `hint`, `disabled`, (+native input) (+override) |
+| `Label` | `htmlFor`, `children`, (+native label) |
+| `Select` | `options`, `placeholder`, `defaultValue`, `onChange(value)`, `disabled` |
+| `MultiSelect` | `options`, `selected` / `defaultSelected`, `onChange`, `placeholder`, `disabled` |
+| `Checkbox` | `label`, `checked`, `onChange(checked)`, `disabled`, `checkedColor?` |
+| `Radio` / `RadioSm` | `id`, `name`, `value`, `checked`, `label`, `onChange(value)`, `disabled` |
+| `Switch` | `label`, `checked` / `defaultChecked`, `onChange(checked)`, `color` (blue/gray), `disabled` |
+| `TextArea` | `value`, `onChange`, `rows`, `success`, `error`, `hint`, `disabled` |
+| `FileInput` | `onChange`, `accept`, `multiple`, (+native input) |
+| `PasswordInput` | password field with a show/hide eye toggle, (+native input attrs) |
+| `Dropzone` | `onDrop(files)`, `accept?`, `multiple?`, `title?`, `description?`, `browseLabel?` — drag-and-drop upload, dependency-free |
+| `DatePicker` | `id`, `mode` (single/multiple/range/time), `defaultDate`, `onChange`, `label`, `placeholder` |
+| `DateTimePicker` | `id`, `label?`, `placeholder?`, `defaultDate?`, `defaultTime?` (`"HH:MM"`), `onChange?({ date, time })` — flatpickr date calendar + a compact `HH:MM` time input |
+| `Slider` | `value` / `defaultValue`, `onChange(value)`, `min`, `max`, `step`, `color`, `label?`, `showValue?`, `disabled` |
+| `Editor` (WYSIWYG) | `content`, `onChange(html)`, `placeholder?`, `editable?`, `toolbar?` (ordered tool ids or custom buttons), `editorClassName?` — optional Tiptap peers; render client-only (see Data viz) |
+
+### Data viz
+
+These wrap optional heavy peer deps and must be rendered client-only under SSR (see the SSR note
+in [Peer dependencies](#peer-dependencies)).
+
+| Component | Key props |
+|---|---|
+| `BarChart` | `series`, `categories`, `colors?`, `height?`, `options?` (merged over defaults) |
+| `LineChart` | `series`, `categories`, `colors?`, `height?`, `options?` |
+| `Calendar` | `events`, `onEventClick`, `onDateSelect`, `initialView` |
+| `CountryMap` | `markers`, `markerColor?`, `mapColor?` |
+| `Editor` (WYSIWYG) | `content`, `onChange(html)`, `placeholder?`, `editable?`, `toolbar?` — Tiptap-powered, customizable toolbar |
+
+> The data-viz components default their data to sensible demo values, so they render
+> out-of-the-box and are fully overridable via the props above.
+
+The `Editor` is a Tiptap-powered rich-text editor with a fully customizable toolbar. Pass an
+ordered `toolbar` array of built-in tool ids (`"bold" | "italic" | "strike" | "code" |
+"heading1" | "heading2" | "heading3" | "bulletList" | "orderedList" | "blockquote" |
+"codeBlock" | "link" | "undo" | "redo" | "divider"`) or custom `{ id, icon, title, onClick,
+isActive? }` button objects. Set `editable={false}` for a read-only view (toolbar hidden).
+
+```tsx
+import dynamic from 'next/dynamic';
+const Editor = dynamic(
+  () => import('@andreagiugni/tailwind-dashboard-ui').then((m) => m.Editor),
+  { ssr: false }
+);
+
+<Editor
+  content="<p>Hello <strong>world</strong></p>"
+  onChange={(html) => save(html)}
+  toolbar={['bold', 'italic', 'divider', 'bulletList', 'orderedList', 'link']}
+/>
+```
+
+## Data table
+
+`DataTable` is a generic, batteries-included table: pass your `data` array and a `columns`
+definition and you get live search, per-column click-to-sort, a "Show N entries" selector and
+pagination out of the box. Light/dark styling follows the standard `.dark` variant.
+
+```tsx
+import { DataTable, type DataTableColumn } from '@andreagiugni/tailwind-dashboard-ui';
+
+type Person = { name: string; office: string; salary: number };
+
+const people: Person[] = [
+  { name: 'Abram Schleifer', office: 'Edinburgh', salary: 89500 },
+  { name: 'Carla George', office: 'London', salary: 15500 },
+  // …
+];
+
+const columns: DataTableColumn<Person>[] = [
+  { key: 'name', header: 'User', sortable: true },
+  { key: 'office', header: 'Office', sortable: true },
+  {
+    key: 'salary',
+    header: 'Salary',
+    sortable: true,
+    align: 'right',
+    render: (row) => `$${row.salary.toLocaleString()}`, // custom cell
+  },
+];
+
+<DataTable
+  data={people}
+  columns={columns}
+  rowsPerPage={5}
+  rowsPerPageOptions={[5, 10, 25]}
+  defaultSortKey="name"
+  searchKeys={['name', 'office']}
+  onRowClick={(row) => console.log(row)}
+/>
+```
+
+Key props: `data`, `columns` (each: `key`, `header`, `sortable?`, `align?`, `render?`,
+`className?`), `rowsPerPage` (default 10), `rowsPerPageOptions` (default `[5,10,25,50]`),
+`searchable` / `searchPlaceholder` / `searchKeys`, `defaultSortKey` / `defaultSortDirection`,
+`pagination`, `showSizeSelector`, `onRowClick`, `getRowId`, `emptyContent`. It is built on the
+exported `Table`, `Input` and `Pagination` primitives — drop down to those directly if you need
+full control over the markup.
+
+## License
+
+MIT © Andrea Giugni

package/dist/Editor-uOYxR3HX.d.cts

@@ -0,0 +1,53 @@
+import React, { CSSProperties } from 'react';
+import { Editor as Editor$1 } from '@tiptap/react';
+
+interface ColorOverrideProps {
+    /** Inline background color override (any CSS color). */
+    bgColor?: string;
+    /** Inline text color override (any CSS color). */
+    textColor?: string;
+    /** Inline border color override (any CSS color). */
+    borderColor?: string;
+}
+declare function styleOverride({ bgColor, textColor, borderColor, }: ColorOverrideProps): CSSProperties;
+
+/** Built-in toolbar tool ids. */
+type ToolbarItemId = "bold" | "italic" | "strike" | "code" | "heading1" | "heading2" | "heading3" | "bulletList" | "orderedList" | "blockquote" | "codeBlock" | "link" | "undo" | "redo" | "divider";
+/** A fully custom toolbar button. */
+interface CustomToolbarItem {
+    id: string;
+    icon: React.ReactNode;
+    title: string;
+    onClick: (editor: Editor$1) => void;
+    isActive?: (editor: Editor$1) => boolean;
+}
+/** A toolbar entry: either a built-in id or a custom button object. */
+type EditorToolItem = ToolbarItemId | CustomToolbarItem;
+/** @deprecated Alias kept for naming flexibility. Use `EditorToolItem`. */
+type ToolbarItem = EditorToolItem;
+interface EditorProps extends ColorOverrideProps {
+    /** Initial HTML content. */
+    content?: string;
+    /** Fires with the current HTML whenever the document changes. */
+    onChange?: (html: string) => void;
+    /** Placeholder shown when the document is empty. */
+    placeholder?: string;
+    /** When false the editor is read-only and the toolbar is hidden. */
+    editable?: boolean;
+    /** Ordered toolbar configuration. Defaults to a sensible full set. */
+    toolbar?: EditorToolItem[];
+    /** Wrapper class. */
+    className?: string;
+    /** Class for the prose content area. */
+    editorClassName?: string;
+}
+/**
+ * Tiptap-powered WYSIWYG editor.
+ *
+ * Heavy, optional peer-dependency component (`@tiptap/*`). It is a client
+ * component and touches the DOM at import time, so in SSR frameworks render it
+ * client-only (e.g. next/dynamic with `ssr:false`), like the charts.
+ */
+declare const Editor: React.FC<EditorProps>;
+
+export { type ColorOverrideProps as C, Editor as E, type ToolbarItem as T, type EditorProps as a, type EditorToolItem as b, type CustomToolbarItem as c, type ToolbarItemId as d, styleOverride as s };

package/dist/Editor-uOYxR3HX.d.ts

@@ -0,0 +1,53 @@
+import React, { CSSProperties } from 'react';
+import { Editor as Editor$1 } from '@tiptap/react';
+
+interface ColorOverrideProps {
+    /** Inline background color override (any CSS color). */
+    bgColor?: string;
+    /** Inline text color override (any CSS color). */
+    textColor?: string;
+    /** Inline border color override (any CSS color). */
+    borderColor?: string;
+}
+declare function styleOverride({ bgColor, textColor, borderColor, }: ColorOverrideProps): CSSProperties;
+
+/** Built-in toolbar tool ids. */
+type ToolbarItemId = "bold" | "italic" | "strike" | "code" | "heading1" | "heading2" | "heading3" | "bulletList" | "orderedList" | "blockquote" | "codeBlock" | "link" | "undo" | "redo" | "divider";
+/** A fully custom toolbar button. */
+interface CustomToolbarItem {
+    id: string;
+    icon: React.ReactNode;
+    title: string;
+    onClick: (editor: Editor$1) => void;
+    isActive?: (editor: Editor$1) => boolean;
+}
+/** A toolbar entry: either a built-in id or a custom button object. */
+type EditorToolItem = ToolbarItemId | CustomToolbarItem;
+/** @deprecated Alias kept for naming flexibility. Use `EditorToolItem`. */
+type ToolbarItem = EditorToolItem;
+interface EditorProps extends ColorOverrideProps {
+    /** Initial HTML content. */
+    content?: string;
+    /** Fires with the current HTML whenever the document changes. */
+    onChange?: (html: string) => void;
+    /** Placeholder shown when the document is empty. */
+    placeholder?: string;
+    /** When false the editor is read-only and the toolbar is hidden. */
+    editable?: boolean;
+    /** Ordered toolbar configuration. Defaults to a sensible full set. */
+    toolbar?: EditorToolItem[];
+    /** Wrapper class. */
+    className?: string;
+    /** Class for the prose content area. */
+    editorClassName?: string;
+}
+/**
+ * Tiptap-powered WYSIWYG editor.
+ *
+ * Heavy, optional peer-dependency component (`@tiptap/*`). It is a client
+ * component and touches the DOM at import time, so in SSR frameworks render it
+ * client-only (e.g. next/dynamic with `ssr:false`), like the charts.
+ */
+declare const Editor: React.FC<EditorProps>;
+
+export { type ColorOverrideProps as C, Editor as E, type ToolbarItem as T, type EditorProps as a, type EditorToolItem as b, type CustomToolbarItem as c, type ToolbarItemId as d, styleOverride as s };