@alexandregme/zljs 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Alexandre Mendes
+
+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,60 @@
+# zljs — Enterprise Frontend Framework
+
+A modern, TypeScript-based, open-source frontend framework for building scalable web applications.
+
+## Packages
+
+| Package  | Description                                                  | Links                                |
+| -------- | ------------------------------------------------------------ | ------------------------------------ |
+| `core/`  | Component library — Button, DataGrid, Forms, Modal, and more | [Storybook](https://zljs.vercel.app) |
+| `agent/` | AI-powered UI generation agent                               | [README](./agent/README.md)          |
+
+## AI Roadmap
+
+- [x] Conversational UI Generation (`agent/`)
+- [ ] AI-Powered Testing Automation (via zl-quality-kit)
+- [ ] Intelligent Component Recommendations
+- [ ] Predictive Quality Gates
+- [ ] Accessibility Validation via AI
+
+## Install
+
+```bash
+pnpm add @alexandregme/zljs
+```
+
+Peer dependencies: `react@19`, `react-dom@19`, `next@>=16`, `next-auth@4`, `@reduxjs/toolkit@2`, `react-redux@9`.
+
+Import the global styles once (e.g. in your root layout) and let Tailwind CSS v4 scan the library classes:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@alexandregme/zljs/styles.css";
+@source "../node_modules/@alexandregme/zljs/dist";
+```
+
+```tsx
+import { Button } from "@alexandregme/zljs";
+import { RootLayout } from "@alexandregme/zljs/next";
+import { FormProvider, FormInput } from "@alexandregme/zljs/rhf";
+
+<Button onClick={handleClick}>Submit</Button>;
+```
+
+## Getting Started
+
+```bash
+pnpm install
+pnpm storybook    # Component library docs
+pnpm agent:dev    # AI agent
+pnpm test         # Run tests
+```
+
+## Tech Stack
+
+TypeScript, React 19, Tailwind CSS v4, Storybook 10, Radix UI, pnpm workspaces, GitHub Actions, Vercel
+
+## License
+
+MIT

package/dist/chunk-WAQLH7A5.js

@@ -0,0 +1,129 @@
+"use client";
+
+// core/rhf/form-provider/form-provider.tsx
+import {
+  useForm,
+  FormProvider as RHFFormProvider
+} from "react-hook-form";
+import { jsx } from "react/jsx-runtime";
+var FormProvider = ({
+  children,
+  onSubmit,
+  defaultValues,
+  resolver
+}) => {
+  const methods = useForm({
+    defaultValues,
+    resolver
+  });
+  return /* @__PURE__ */ jsx(RHFFormProvider, { ...methods, children: /* @__PURE__ */ jsx("form", { onSubmit: methods.handleSubmit(onSubmit), children }) });
+};
+
+// core/rhf/form-input/form-input.tsx
+import { useFormContext } from "react-hook-form";
+
+// core/forms/input/input.tsx
+import { forwardRef, useId } from "react";
+
+// core/forms/error/error.styles.ts
+import { tv } from "tailwind-variants";
+var error = tv({
+  base: "text-sm text-red-600"
+});
+
+// core/forms/error/error.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var Error = ({ message }) => {
+  if (!message) {
+    return null;
+  }
+  return /* @__PURE__ */ jsx2("span", { role: "alert", className: error(), children: message });
+};
+
+// core/forms/input/input.styles.ts
+import { tv as tv2 } from "tailwind-variants";
+var wrapper = tv2({
+  base: "flex flex-col gap-1"
+});
+var label = tv2({
+  base: "text-sm font-medium text-gray-700"
+});
+var input = tv2({
+  base: "px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent disabled:bg-gray-100 disabled:cursor-not-allowed"
+});
+
+// core/forms/input/input.tsx
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
+var Input = forwardRef(
+  ({
+    label: labelText,
+    "aria-label": ariaLabel,
+    name,
+    type = "text",
+    placeholder,
+    value,
+    error: error2,
+    disabled,
+    onChange,
+    onBlur,
+    onKeyDown
+  }, ref) => {
+    const id = useId();
+    return /* @__PURE__ */ jsxs("div", { className: wrapper(), children: [
+      labelText && /* @__PURE__ */ jsx3("label", { htmlFor: id, className: label(), children: labelText }),
+      /* @__PURE__ */ jsx3(
+        "input",
+        {
+          ref,
+          id,
+          name,
+          type,
+          placeholder,
+          value,
+          disabled,
+          onChange,
+          onBlur,
+          onKeyDown,
+          "aria-label": ariaLabel,
+          className: input()
+        }
+      ),
+      error2 && /* @__PURE__ */ jsx3(Error, { message: error2 })
+    ] });
+  }
+);
+
+// core/rhf/form-input/form-input.tsx
+import { jsx as jsx4 } from "react/jsx-runtime";
+var FormInput = ({
+  name,
+  label: label2,
+  type = "text",
+  placeholder,
+  disabled
+}) => {
+  const {
+    register,
+    formState: { errors }
+  } = useFormContext();
+  const fieldError = errors[name];
+  const errorMessage = fieldError?.message;
+  return /* @__PURE__ */ jsx4(
+    Input,
+    {
+      label: label2,
+      type,
+      placeholder,
+      disabled,
+      error: errorMessage,
+      ...register(name)
+    }
+  );
+};
+
+export {
+  Error,
+  Input,
+  FormProvider,
+  FormInput
+};

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+import * as react from 'react';
+import { ReactNode, ChangeEvent, FormEvent, FocusEvent, KeyboardEvent } from 'react';
+export { FormInput, FormInputProps, FormProvider, FormProviderProps } from './rhf/index.js';
+export { toast } from 'sonner';
+import * as zustand from 'zustand';
+import { Store, Reducer, Middleware, Dispatch } from '@reduxjs/toolkit';
+import 'react-hook-form';
+
+declare const iconNames: readonly ["Check", "X", "Plus", "Minus", "Search", "Menu", "ChevronDown", "ChevronUp", "ChevronLeft", "ChevronRight", "Pencil", "Trash2", "Save", "RefreshCw", "Home", "MessageSquare", "Users", "Store", "ShoppingCart", "BarChart3", "Brain", "Send", "LogOut", "User", "Key", "Contact", "Package", "Warehouse", "HandCoins", "Stethoscope", "LogIn", "Megaphone", "LayoutDashboard", "Smile", "Frown", "Cat", "ArrowRight", "Loader", "CheckCircle", "XCircle", "AlertTriangle", "Info", "Map", "CloudDownload", "Wrench", "GitMerge", "SiWhatsapp", "SiFacebook", "SiInstagram", "SiShopify"];
+
+type IconName = (typeof iconNames)[number];
+interface IconProps {
+    name: IconName;
+}
+
+/**
+ * Semantic colors for action-oriented components (Button, Heading, etc.)
+ */
+type SemanticColor = "primary" | "success" | "danger" | "warning" | "info" | "none";
+/**
+ * Literal colors for data visualization components (StatsCard, etc.)
+ */
+type DataColor = "blue" | "red" | "yellow" | "green" | "gray" | "orange";
+
+type ButtonVariant = "default" | "icon" | "ghost" | "link";
+interface ButtonProps {
+    children?: ReactNode;
+    type?: "button" | "submit" | "reset";
+    variant?: ButtonVariant;
+    color?: SemanticColor;
+    icon?: IconName;
+    iconPosition?: "left" | "right";
+    disabled?: boolean;
+    "aria-label"?: string;
+    onClick?: () => void;
+}
+
+declare const Button: ({ children, type, variant: variantProp, color, icon, iconPosition, disabled, "aria-label": ariaLabel, onClick, }: ButtonProps) => react.JSX.Element;
+
+interface DataGridCellParams<T extends Record<string, unknown> = Record<string, unknown>> {
+    value?: any;
+    data?: T;
+}
+interface DataGridColumn<T extends Record<string, unknown> = Record<string, unknown>> {
+    field: string;
+    headerName: string;
+    cellRenderer?: (params: DataGridCellParams<T>) => ReactNode;
+    pinned?: "left" | "right";
+    filter?: boolean;
+    width?: number;
+    cellStyle?: (params: DataGridCellParams<T>) => Record<string, string | number | undefined> | undefined;
+    valueFormatter?: (params: DataGridCellParams<T>) => string;
+}
+interface DataGridProps<T extends Record<string, unknown> = Record<string, unknown>> {
+    columns: DataGridColumn<T>[];
+    data: T[];
+    showSearch?: boolean;
+}
+
+declare const DataGrid: <T extends Record<string, unknown> = Record<string, unknown>>({ columns, data, showSearch, }: DataGridProps<T>) => react.JSX.Element;
+
+interface CheckboxProps {
+    label: string;
+    checked?: boolean;
+    disabled?: boolean;
+    error?: string;
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+declare const Checkbox: ({ label: labelText, checked, disabled, error, onChange, }: CheckboxProps) => react.JSX.Element;
+
+interface ErrorProps {
+    message: string;
+}
+
+declare const Error: ({ message }: ErrorProps) => react.JSX.Element | null;
+
+interface FormProps {
+    children: ReactNode;
+    onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
+    disabled?: boolean;
+}
+
+declare const Form: ({ children, onSubmit, disabled }: FormProps) => react.JSX.Element;
+
+interface InputProps {
+    label?: string;
+    "aria-label"?: string;
+    name?: string;
+    type?: "text" | "password" | "email";
+    placeholder?: string;
+    value?: string;
+    error?: string;
+    disabled?: boolean;
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+}
+
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface RadioProps {
+    label: string;
+    name: string;
+    value: string;
+    checked?: boolean;
+    disabled?: boolean;
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+declare const Radio: ({ label: labelText, name, value, checked, disabled, onChange, }: RadioProps) => react.JSX.Element;
+
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface SelectProps {
+    label: string;
+    options: SelectOption[];
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    error?: string;
+    onChange?: (event: ChangeEvent<HTMLSelectElement>) => void;
+}
+
+declare const Select: ({ label: labelText, options, value, placeholder, disabled, error, onChange, }: SelectProps) => react.JSX.Element;
+
+interface TextAreaProps {
+    label: string;
+    placeholder?: string;
+    value?: string;
+    rows?: number;
+    error?: string;
+    disabled?: boolean;
+    onChange?: (event: ChangeEvent<HTMLTextAreaElement>) => void;
+}
+
+declare const TextArea: ({ label: labelText, placeholder, value, rows, error, disabled, onChange, }: TextAreaProps) => react.JSX.Element;
+
+declare const Icon: ({ name }: IconProps) => react.JSX.Element;
+
+interface StatsCardProps {
+    label: string;
+    value: string | number;
+    color: DataColor;
+}
+
+declare const StatsCard: ({ label, value, color }: StatsCardProps) => react.JSX.Element;
+
+type ModalSize = "sm" | "md" | "lg" | "xl" | "full";
+interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    description?: string;
+    children?: ReactNode;
+    size?: ModalSize;
+}
+
+declare const Modal: ({ open, onClose, title, description, children, size, }: ModalProps) => react.JSX.Element;
+
+interface WhatsAppButtonProps {
+    phone: string;
+    message?: string;
+    children?: string;
+    onClick?: () => void;
+}
+
+declare const WhatsAppButton: ({ phone, message, children, onClick, }: WhatsAppButtonProps) => react.JSX.Element;
+
+interface HeadingProps {
+    children: ReactNode;
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    color?: SemanticColor;
+}
+
+declare const Heading: ({ children, level, color }: HeadingProps) => react.JSX.Element;
+
+interface SidebarItem {
+    icon: IconName;
+    label: string;
+    href: string;
+}
+interface SidebarSection {
+    items: SidebarItem[];
+}
+interface SidebarUser {
+    name: string;
+    email: string;
+}
+interface SidebarProps {
+    sections: SidebarSection[];
+    user: SidebarUser;
+    activeHref?: string;
+    defaultCollapsed?: boolean;
+    collapseLabel: string;
+    homeHref?: string | false;
+    homeLabel?: string;
+    onLogout: () => void;
+}
+
+declare const Sidebar: ({ sections, user, activeHref, defaultCollapsed, collapseLabel, homeHref, homeLabel, onLogout, }: SidebarProps) => react.JSX.Element;
+
+interface TagProps {
+    children: ReactNode;
+    color?: "blue" | "green" | "red" | "yellow" | "gray";
+    onRemove?: () => void;
+    className?: string;
+}
+declare const Tag: ({ children, color, onRemove, className, }: TagProps) => react.JSX.Element;
+
+declare const Toaster: () => react.JSX.Element;
+
+interface AppState {
+    fetchingCalls: number;
+    fetching: boolean;
+    startFetching: () => void;
+    finishFetching: () => void;
+}
+
+declare const useAppStore: zustand.UseBoundStore<Omit<zustand.StoreApi<AppState>, "setState" | "devtools"> & {
+    setState(partial: AppState | Partial<AppState> | ((state: AppState) => AppState | Partial<AppState>), replace?: false | undefined, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    setState(state: AppState | ((state: AppState) => AppState), replace: true, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    devtools: {
+        cleanup: () => void;
+    };
+}>;
+
+type ToastType = "success" | "error" | "info" | "warning";
+interface Toast {
+    id: number;
+    message: string;
+    type: ToastType;
+}
+interface ToastState {
+    toasts: Toast[];
+    addToast: (message: string, type?: ToastType) => number;
+    removeToast: (id: number) => void;
+    success: (message: string) => number;
+    error: (message: string) => number;
+    info: (message: string) => number;
+    warning: (message: string) => number;
+}
+
+declare const useToastStore: zustand.UseBoundStore<Omit<zustand.StoreApi<ToastState>, "setState" | "devtools"> & {
+    setState(partial: ToastState | Partial<ToastState> | ((state: ToastState) => ToastState | Partial<ToastState>), replace?: false | undefined, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    setState(state: ToastState | ((state: ToastState) => ToastState), replace: true, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    devtools: {
+        cleanup: () => void;
+    };
+}>;
+
+interface ModalEntry {
+    name: string;
+    payload?: unknown;
+}
+interface ModalState {
+    modals: ModalEntry[];
+    openModal: (name: string) => void;
+    openModalWithPayload: (name: string, payload: unknown) => void;
+    closeModal: (name: string) => void;
+    isOpen: (name: string) => boolean;
+    getPayload: (name: string) => unknown | undefined;
+}
+
+declare const useModalStore: zustand.UseBoundStore<Omit<zustand.StoreApi<ModalState>, "setState" | "devtools"> & {
+    setState(partial: ModalState | Partial<ModalState> | ((state: ModalState) => ModalState | Partial<ModalState>), replace?: false | undefined, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    setState(state: ModalState | ((state: ModalState) => ModalState), replace: true, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    devtools: {
+        cleanup: () => void;
+    };
+}>;
+
+interface ExtendedStore extends Store {
+    setDynamicReducers?: (reducers: Record<string, Reducer>) => void;
+}
+interface GlobalStateProps {
+    children: ReactNode;
+    reducers?: Record<string, Reducer>;
+    middlewares?: Middleware[];
+    preloadedState?: Record<string, unknown>;
+    coreReducers?: Record<string, Reducer>;
+}
+
+declare const GlobalState: ({ children, reducers, middlewares, preloadedState, coreReducers, }: GlobalStateProps) => react.JSX.Element;
+
+interface RouterState {
+    urlAsPath: string;
+    query: Record<string, string>;
+    setRoute: (urlAsPath: string) => void;
+}
+
+declare const useRouterStore: zustand.UseBoundStore<Omit<zustand.StoreApi<RouterState>, "setState" | "devtools"> & {
+    setState(partial: RouterState | Partial<RouterState> | ((state: RouterState) => RouterState | Partial<RouterState>), replace?: false | undefined, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    setState(state: RouterState | ((state: RouterState) => RouterState), replace: true, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    devtools: {
+        cleanup: () => void;
+    };
+}>;
+
+declare const splitURLasPath: (urlAsPath: string) => Record<string, string>;
+
+interface PageState {
+    title: string;
+    setTitle: (title: string) => void;
+}
+
+declare const usePageStore: zustand.UseBoundStore<Omit<zustand.StoreApi<PageState>, "setState" | "devtools"> & {
+    setState(partial: PageState | Partial<PageState> | ((state: PageState) => PageState | Partial<PageState>), replace?: false | undefined, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    setState(state: PageState | ((state: PageState) => PageState), replace: true, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    devtools: {
+        cleanup: () => void;
+    };
+}>;
+
+type InitPageFunction = (dispatch: Dispatch) => void;
+interface PageWrapperProps {
+    title: string;
+    children?: ReactNode;
+    reducers?: Record<string, Reducer>;
+    initPage?: InitPageFunction;
+}
+
+declare const PageWrapper: ({ reducers, title, initPage, children, }: PageWrapperProps) => react.JSX.Element;
+
+interface ConnectedModalProps {
+    modalId: string;
+    title: string;
+    description?: string;
+    size?: ModalSize;
+    children?: ReactNode;
+}
+
+declare const ConnectedModal: ({ modalId, title, description, size, children, }: ConnectedModalProps) => react.JSX.Element;
+
+interface SpinnerProps {
+    className?: string;
+}
+
+declare const Spinner: ({ className }: SpinnerProps) => react.JSX.Element;
+
+interface LoaderProps {
+    label?: string;
+}
+
+declare const Loader: ({ label }: LoaderProps) => react.JSX.Element | null;
+
+interface AppWrapperProps {
+    children: ReactNode;
+    reducers?: Record<string, Reducer>;
+    middlewares?: Middleware[];
+    coreReducers?: Record<string, Reducer>;
+}
+
+declare const AppWrapper: ({ children, reducers, middlewares, coreReducers, }: AppWrapperProps) => react.JSX.Element;
+
+interface DocumentWrapperProps {
+    children: ReactNode;
+    lang?: string;
+    className?: string;
+}
+
+declare const DocumentWrapper: ({ children, lang, className, }: DocumentWrapperProps) => react.JSX.Element;
+
+interface HttpClientConfig {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}
+interface HttpRequestConfig {
+    payload?: FormData | object;
+    params?: object;
+    headers?: Record<string, string>;
+    silent?: boolean;
+}
+
+declare class HTTPClient {
+    baseUrl: string;
+    headers: Record<string, string>;
+    constructor(config?: HttpClientConfig);
+    private request;
+    get<T = unknown>(url: string, config?: HttpRequestConfig): Promise<T | undefined>;
+    post<T = unknown>(url: string, config?: HttpRequestConfig): Promise<T | undefined>;
+    put<T = unknown>(url: string, config?: HttpRequestConfig): Promise<T | undefined>;
+    delete<T = unknown>(url: string, config?: HttpRequestConfig): Promise<T | undefined>;
+    patch<T = unknown>(url: string, config?: HttpRequestConfig): Promise<T | undefined>;
+}
+
+export { AppWrapper, Button, Checkbox, ConnectedModal, DataGrid, DocumentWrapper, Error, Form, GlobalState, HTTPClient, Heading, Icon, Input, Loader, Modal, PageWrapper, Radio, Select, Sidebar, Spinner, StatsCard, Tag, TextArea, Toaster, WhatsAppButton, splitURLasPath, useAppStore, useModalStore, usePageStore, useRouterStore, useToastStore };
+export type { AppState, AppWrapperProps, ButtonProps, ButtonVariant, CheckboxProps, ConnectedModalProps, DataGridColumn, DataGridProps, DocumentWrapperProps, ErrorProps, ExtendedStore, FormProps, GlobalStateProps, HeadingProps, HttpClientConfig, HttpRequestConfig, IconName, InitPageFunction, InputProps, LoaderProps, ModalEntry, ModalProps, ModalState, PageState, PageWrapperProps, RadioProps, RouterState, SelectOption, SelectProps, SidebarItem, SidebarProps, SidebarSection, SidebarUser, SpinnerProps, StatsCardProps, TagProps, TextAreaProps, Toast, ToastState, ToastType, WhatsAppButtonProps };