From f15fb36d8931a86727f4a8cd088a532f34e93eb6 Mon Sep 17 00:00:00 2001 From: natxocc Date: Mon, 30 Mar 2026 15:17:47 +0200 Subject: [PATCH] uploading docs, preview --- docs/README.md | 32 +++--- docs/_sidebar.md | 63 ++++++++--- docs/components/button.md | 221 ++++++++++++++++++++++++++++++++++++++ docs/install.md | 129 ++++++++++++++++++++++ docs/quick.md | 206 +++++++++++++++++++++++++++++++++++ 5 files changed, 622 insertions(+), 29 deletions(-) create mode 100644 docs/components/button.md create mode 100644 docs/install.md create mode 100644 docs/quick.md diff --git a/docs/README.md b/docs/README.md index e7a5782..d91f266 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,10 +7,10 @@

SigPro UI

-
Reactive Design System
-
"Atomic components for high-performance interfaces. Zero-boilerplate, pure Tailwind v4 elegance."
+
Reactive Design System for SigPro
+
"Atomic components for high-performance interfaces. Zero-boilerplate, pure DaisyUI v5 elegance."
- View Components → + View Components →
@@ -102,15 +102,19 @@ The visual DNA. All components are mapped to daisyUI v5 semantic classes, provid ----- -\
-\
-\
-\

Design at Runtime.\ -\

Combine the best of three worlds: \SigPro\ for logic, \Tailwind v4\ for speed, and \daisyUI v5\ for beauty. Build interfaces that feel as fast as they look.\ -\ -\ -\ +

+
+
+

Design at Runtime.

+

+ Combine the best of three worlds: SigPro for logic, + Tailwind v4 for speed, and daisyUI v5 for beauty. + Build interfaces that feel as fast as they look. +

+
+
+
-\
-Atomic UI System — Built for SigPro — NatxoCC -\ +
+ Atomic UI System — Built for SigPro — NatxoCC +
diff --git a/docs/_sidebar.md b/docs/_sidebar.md index c089820..25c37ae 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,21 +1,54 @@ + + * [**Home**](README.md) * **Introduction** * [Installation](install.md) - * [Examples](examples.md) - * [Vite Plugin](vite/plugin.md) + * [Quick Reference](quick.md) -* **API Reference** - * [Quick Start](api/quick.md) - * [$ signals](api/signal.md) - * [$watch](api/watch.md) - * [$if](api/if.md) - * [$for](api/for.md) - * [$router](api/router.md) - * [$mount](api/mount.md) - * [$html](api/html.md) - * [Tags](api/tags.md) - * [Global Store](api/global.md) +* **Forms & Inputs** + * [Button](components/button.md) + * [Input](components/input.md) + * [Select](components/select.md) + * [Autocomplete](components/autocomplete.md) + * [Datepicker](components/datepicker.md) + * [Colorpicker](components/colorpicker.md) + * [Checkbox](components/checkbox.md) + * [Radio](components/radio.md) + * [Range](components/range.md) + * [Rating](components/rating.md) + * [Swap](components/swap.md) -* **UI Components** - * [Quick Start](ui/quick.md) \ No newline at end of file +* **Data Display** + * [Table](components/table.md) + * [List](components/list.md) + * [Badge](components/badge.md) + * [Stat](components/stat.md) + * [Timeline](components/timeline.md) + * [Stack](components/stack.md) + * [Indicator](components/indicator.md) + +* **Feedback & Overlays** + * [Alert](components/alert.md) + * [Modal](components/modal.md) + * [Toast](components/toast.md) + * [Loading](components/loading.md) + * [Tooltip](components/tooltip.md) + +* **Navigation & Layout** + * [Navbar](components/navbar.md) + * [Menu](components/menu.md) + * [Drawer](components/drawer.md) + * [Tabs](components/tabs.md) + * [Accordion](components/accordion.md) + * [Dropdown](components/dropdown.md) + * [Fieldset](components/fieldset.md) + +* **Utilities** + * [Fab](components/fab.md) + * [Toast](components/toast.md) + +* **Advanced** + * [Reactivity Guide](advanced/reactivity.md) + * [i18n Guide](advanced/i18n.md) + * [Theming](advanced/theming.md) \ No newline at end of file diff --git a/docs/components/button.md b/docs/components/button.md new file mode 100644 index 0000000..84df933 --- /dev/null +++ b/docs/components/button.md @@ -0,0 +1,221 @@ +# Button + +Styled button with full DaisyUI support and reactive states. + +## Tag + +`Button` + +## Props + +| Prop | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `class` | `string` | `''` | Additional CSS classes (DaisyUI + Tailwind) | +| `disabled` | `boolean \| Signal` | `false` | Disabled state | +| `loading` | `boolean \| Signal` | `false` | Shows loading spinner | +| `badge` | `string \| Signal` | `-` | Badge text displayed on corner | +| `badgeClass` | `string` | `'badge-secondary'` | Badge styling classes | +| `tooltip` | `string \| Signal` | `-` | Tooltip text on hover | +| `icon` | `string \| VNode \| Signal` | `-` | Icon displayed before text | +| `onclick` | `function` | `-` | Click event handler | +| `type` | `string` | `'button'` | Native button type | + +## Live Examples + +### Basic Button + +
+ + + +```javascript +Button({ class: "btn-primary" }, "Click Me") +``` + +### With Loading State + +
+ + + +```javascript +const isSaving = $(false); + +Button({ + class: "btn-success", + loading: isSaving, + onclick: async () => { + isSaving(true); + await saveData(); + isSaving(false); + } +}, "Save Changes") +``` + +### With Badge + +
+ + + +```javascript +Button({ + class: "btn-outline", + badge: "3", + badgeClass: "badge-accent" +}, "Notifications") +``` + +### With Tooltip + +
+ + + +```javascript +Button({ + class: "btn-ghost", + tooltip: "Delete item" +}, "Delete") +``` + +### Disabled State + +
+ + + +```javascript +const isDisabled = $(true); + +Button({ + class: "btn-primary", + disabled: isDisabled +}, "Submit") +``` + +### All Variants + +
+ + + +```javascript +Div({ class: "flex flex-wrap gap-2" }, [ + Button({ class: "btn-primary" }, "Primary"), + Button({ class: "btn-secondary" }, "Secondary"), + Button({ class: "btn-accent" }, "Accent"), + Button({ class: "btn-ghost" }, "Ghost"), + Button({ class: "btn-outline" }, "Outline") +]) +``` +``` + +## Ventajas de este enfoque: + +1. **Ejecución real** - Los ejemplos son interactivos y funcionales +2. **Código visible** - Debajo de cada ejemplo se muestra el código fuente +3. **Aprendizaje visual** - Los usuarios pueden ver y probar los componentes +4. **Reactivo** - Los ejemplos con signals demuestran la reactividad en acción + +## Consejos adicionales: + +Para mejorar la experiencia, podrías agregar estilos a los contenedores de los ejemplos: + +```css +/* En tu HTML, dentro de + + +
+ + + +``` + +## Troubleshooting + +| Problem | Solution | +| :--- | :--- | +| Components don't look styled | Check that `app.css` is imported and contains the Tailwind + daisyUI directives. | +| `UI is not defined` | Make sure you call `UI()` **before** using any component like `Button`, `Input`, etc. | +| Locale not working | Verify you passed a valid locale (`"es"` or `"en"`) to `UI()`. | +| Build errors with Tailwind v4 | Ensure Tailwind CSS v4 and daisyUI v5 are correctly installed and configured. | + + +**Happy coding!** 🎉 + diff --git a/docs/quick.md b/docs/quick.md new file mode 100644 index 0000000..57cccb3 --- /dev/null +++ b/docs/quick.md @@ -0,0 +1,206 @@ +# SigPro-UI Quick Reference + +**Version:** daisyUI v5 + Tailwind v4 Plugin +**Status:** Active / WIP + +> **Prerequisites:** Tailwind CSS v4+ and DaisyUI v5+ installed. + +## Global Initialization + +```javascript +import { UI } from 'sigpro-ui'; + +// Injects all components into window and sets default language +UI('en'); // 'es' or 'en' + +// All components (Button, Input, Table, Toast, etc.) are now globally available. +``` + +--- + +## Core Components + +| Component | Purpose | Basic Example | +| :--- | :--- | :--- | +| **Button** | Styled button with DaisyUI | `Button({ class: "btn-primary" }, "Submit")` | +| **Input** | Reactive text field with floating label | `Input({ label: "Name", value: $name })` | +| **Select** | Dropdown selection menu | `Select({ options: ["Admin", "User"], value: $role })` | +| **Checkbox** | Binary toggle (boolean) | `Checkbox({ label: "Active", checked: $isActive })` | +| **Table** | Data grid with column rendering | `Table({ items: $data, columns: [...] })` | +| **Modal** | Overlay dialog controlled by a Signal | `Modal({ open: $show, title: "Alert" }, "Message")` | +| **Badge** | Small status indicator or tag | `Badge({ class: "badge-outline" }, "Beta")` | +| **Alert** | Contextual notification | `Alert({ type: "info" }, "Update available")` | +| **Loading** | Loading indicators (spinner, dots) | `Loading({ show: $isLoading })` | +| **Dropdown** | Contextual overlay menu | `Dropdown({ label: "Menu" }, [Link1, Link2])` | +| **Tabs** | Reactive tab-based navigation | `Tabs({ items: ["Home", "Settings"], active: $index })` | +| **Stat** | Statistical data block (KPIs) | `Stat({ label: "Sales", value: "$400" })` | +| **Toast** | Temporary floating notification | `Toast("Done!", "alert-success", 3000)` | + +--- + +## Forms & Inputs + +| Component | Description | Example | +| :--- | :--- | :--- | +| **Input** | Text input with floating label, validation, password toggle | `Input({ label: "Email", type: "email", value: $email })` | +| **Select** | Dropdown selector | `Select({ label: "Role", options: ["Admin", "User"], value: $role })` | +| **Autocomplete** | Searchable dropdown with filtering | `Autocomplete({ label: "Country", options: countryList, value: $country })` | +| **Datepicker** | Date picker (single or range mode) | `Datepicker({ label: "Date", value: $date, range: false })` | +| **Colorpicker** | Visual color picker with palette | `Colorpicker({ label: "Theme", value: $color })` | +| **Checkbox** | Checkbox or toggle switch | `Checkbox({ label: "Remember me", value: $remember })` | +| **Radio** | Radio button | `Radio({ label: "Option 1", value: $selected, name: "group" })` | +| **Range** | Slider control | `Range({ label: "Volume", min: 0, max: 100, value: $volume })` | +| **Rating** | Star rating component | `Rating({ value: $stars, count: 5 })` | +| **Swap** | Toggle between two states (sun/moon) | `Swap({ on: "🌞", off: "🌙", value: $isDark })` | + +--- + +## Data Display + +| Component | Description | Example | +| :--- | :--- | :--- | +| **Table** | Reactive data grid with columns | `Table({ items: $users, columns: [{ label: "Name", key: "name" }] })` | +| **List** | Vertical list with custom rendering | `List({ items: $items, render: (item) => item.name })` | +| **Badge** | Small status indicators | `Badge({ class: "badge-primary" }, "New")` | +| **Stat** | Statistical data blocks (KPIs) | `Stat({ label: "Total", value: "1.2k", desc: "Monthly" })` | +| **Timeline** | Vertical/horizontal timeline | `Timeline({ items: [{ title: "Step 1", detail: "Completed" }] })` | +| **Stack** | Stacked elements | `Stack({}, [Card1, Card2, Card3])` | +| **Indicator** | Badge on corner of element | `Indicator({ badge: "3" }, Button(...))` | + +--- + +## Feedback & Overlays + +| Component | Description | Example | +| :--- | :--- | :--- | +| **Alert** | Inline contextual notification | `Alert({ type: "success" }, "Changes saved!")` | +| **Modal** | Dialog overlay | `Modal({ open: $isOpen, title: "Confirm" }, "Are you sure?")` | +| **Toast** | Floating notification (auto-stacking) | `Toast("Action completed", "alert-info", 3000)` | +| **Loading** | Full-screen or inline loading indicator | `Loading({ show: $isLoading })` | +| **Tooltip** | Hover tooltip wrapper | `Tooltip({ tip: "Help text" }, Button(...))` | + +--- + +## Navigation & Layout + +| Component | Description | Example | +| :--- | :--- | :--- | +| **Navbar** | Top navigation bar | `Navbar({}, [Logo, Menu, Avatar])` | +| **Menu** | Vertical navigation menu | `Menu({ items: [{ label: "Home", onclick: goHome }] })` | +| **Drawer** | Side drawer (off-canvas) | `Drawer({ id: "my-drawer", open: $isOpen, content: Main, side: SideMenu })` | +| **Tabs** | Content switching | `Tabs({ items: [{ label: "Tab1", content: Panel1 }] })` | +| **Accordion** | Collapsible sections | `Accordion({ title: "Details" }, "Hidden content")` | +| **Dropdown** | Contextual menus | `Dropdown({ label: "Options" }, [MenuLink("Edit")])` | +| **Fieldset** | Form grouping with legend | `Fieldset({ legend: "Personal Info" }, [Input(...)])` | + +--- + +## Interaction & Utilities + +| Component | Description | Example | +| :--- | :--- | :--- | +| **Fab** | Floating Action Button with actions | `Fab({ icon: "+", actions: [{ label: "Add", onclick: add }] })` | +| **Indicator** | Badge indicator wrapper | `Indicator({ badge: "99+" }, Button(...))` | + +--- + +## Internationalization (i18n) + +Built-in locale system with Spanish and English support. + +```javascript +// Set global UI language +Locale("en"); // or "es" + +// Get translated string (returns a reactive signal) +const closeText = tt("close"); // "Close" or "Cerrar" + +// Available keys: close, confirm, cancel, search, loading, nodata +``` + +--- + +## Implementation Notes + +1. **Atomic Reactivity**: Components accepting `value` or `checked` bind directly to **SigPro Signals**. Updates happen instantly without full page re-renders. + +2. **Tailwind v4 + DaisyUI v5**: Pass any Tailwind utility class via the `class` attribute to override default DaisyUI styling. + + ```javascript + Button({ class: "btn-primary btn-sm rounded-full shadow-lg" }, "Click") + ``` + +3. **Zero Imports (Global Mode)**: After calling `UI()`, all components are attached to `window`. No manual imports needed. + +4. **Self-Cleaning**: Components internally manage `_cleanups` to destroy observers and event listeners when removed from the DOM. + +--- + +## Advanced Examples + +### Reactive Form with Validation + +```javascript +const name = $(""); +const error = $(null); + +Input({ + label: "Full Name", + value: name, + error: error, + oninput: (e) => { + name(e.target.value); + error(e.target.value.length < 3 ? "Name too short" : null); + } +}) +``` + +### API Request Pattern + +```javascript +const userId = $("123"); +const userData = $(null); +const loading = $(false); + +$watch(userId, async (id) => { + loading(true); + userData(await fetch(`/api/user/${id}`).then(r => r.json())); + loading(false); +}); + +// In template +Loading({ show: loading }); +$if(() => userData(), () => Alert({ type: "success" }, userData()?.name)) +``` + +### Modal with Confirm Action + +```javascript +const showModal = $(false); + +Modal({ + open: showModal, + title: "Delete Item", + buttons: [ + Button({ class: "btn-error", onclick: () => { deleteItem(); showModal(false); } }, "Delete") + ] +}, "Are you sure you want to delete this item?"); +``` + +--- + +## Component Props Quick Reference + +| Component | Key Props | +| :--- | :--- | +| `Button` | `class`, `disabled`, `loading`, `badge`, `tooltip`, `icon` | +| `Input` | `label`, `value`, `error`, `type`, `placeholder`, `disabled`, `tip` | +| `Select` | `label`, `options`, `value`, `disabled` | +| `Modal` | `open`, `title`, `buttons` | +| `Table` | `items`, `columns`, `zebra`, `pinRows`, `empty` | +| `Alert` | `type` (info/success/warning/error), `soft`, `actions` | +| `Toast` | `message`, `type`, `duration` | +| `Loading` | `show` | +| `Datepicker` | `value`, `range`, `label`, `placeholder` | +| `Autocomplete` | `options`, `value`, `onSelect`, `label` | +