sigpro-ui/docs/quick.md

SigPro-UI Quick Reference

Status: Active / WIP

Global Initialization

import "sigpro-ui";
import "sigpro-ui/css";

// 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 validation	Input({ value: $name, validate: (v) => !v ? "Required" : "" })
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")
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, validate: validateEmail })
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 })

---

Input Validation

The Input component supports real-time validation via the validate prop:

const email = $('');

Input({
  type: 'email',
  value: email,
  placeholder: 'Enter your email',
  icon: 'icon-[lucide--mail]',
  validate: (value) => {
    if (!value) return '';
    if (!value.includes('@')) return 'Email must contain @';
    if (!value.includes('.')) return 'Email must contain .';
    return '';
  },
  oninput: (e) => email(e.target.value)
})

How it works:

• Returns '' or null → no error
• Returns a string → shows error message and adds input-error class
• Validates on every keystroke
• No external state needed for error messages

---

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({ value: () => count() }, 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)
Tooltip	Hover tooltip wrapper	Tooltip({ tip: "Help text", ui: "tooltip-top" }, 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({ value: () => unread() }, Button(...))

---

Internationalization (i18n)

Built-in locale system with Spanish and English support.

// Set global UI language
Locale("en");

// Get translated string (returns a reactive signal)
const closeText = tt("close"); // "Close" or "Cerrar"

---

Implementation Notes

1. Atomic Reactivity: Components accepting value or checked bind directly to SigPro Signals. Updates happen instantly without full page re-renders.

2. DaisyUI v5: Pass any daisyUI styling via the class attribute.

   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

const name = $("");

Input({
  value: name,
  placeholder: "Name",
  validate: (value) => {
    if (!value) return "Name is required";
    if (value.length < 3) return "Name too short";
    return "";
  },
  oninput: (e) => name(e.target.value)
})

API Request Pattern

const userId = $("123");
const userData = $(null);

$watch(userId, async (id) => {
  loading(true);
  userData(await fetch(`/api/user/${id}`).then(r => r.json()));
  loading(false);
});

// In template
$if(() => userData(), () => Alert({ type: "success" }, userData()?.name))

Modal with Confirm Action

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, icon
Input	value, validate, type, placeholder, icon, disabled
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
Datepicker	value, range, label, placeholder
Autocomplete	options, value, onSelect, label
Indicator	value (function that returns number/string)
Tooltip	tip, ui (tooltip-top/bottom/left/right)