@robosophy/ui-react 1.0.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# Robosophy UI React Agent Notes
+
+Use `@robosophy/ui-react` before creating project-local UI components from scratch.
+
+## Consumer Rules
+
+- Import shared components from `@robosophy/ui-react`.
+- Read `dist/index.d.ts` when exact prop, callback, or type names are needed.
+- Keep app-specific behavior in the consuming project: router pushes, stores, API calls, permissions, logout, redirects, and module switching.
+- Prefer props and callback handlers over hardcoded actions inside components.
+- Use render props for project-specific content when the component exposes one.
+- Use PrimeReact `Button` for actions in PrimeReact apps.
+- Use `RsSidebar` for module navigation.
+- Use `@robosophy/tokens` CSS variables (`--rs-*`) for new styles.
+- Do not duplicate `@robosophy/tokens/tokens.css` when the app already imports `@robosophy/prime-theme/prime.css`.
+
+## Sub-exports for selective imports
+
+If your app does not use PrimeReact, import components individually to avoid loading PrimeReact:
+
+```tsx
+import RsIcon from "@robosophy/ui-react/RsIcon";
+import RsSidebar from "@robosophy/ui-react/RsSidebar";
+```
+
+The main barrel (`@robosophy/ui-react`) loads all components including PrimeReact dependencies. Use sub-exports when you only need specific components without PrimeReact.
+
+## CSS Imports
+
+PrimeReact apps:
+
+```tsx
+import { PrimeReactProvider } from "primereact/api";
+import RobosophyPreset from "@robosophy/prime-theme";
+import "@robosophy/prime-theme/prime.css";
+import "@robosophy/ui-react/styles.css";
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <PrimeReactProvider value={{ theme: { preset: RobosophyPreset } }}>
+      <Component {...pageProps} />
+    </PrimeReactProvider>
+  );
+}
+```
+
+Non-PrimeReact apps:
+
+```tsx
+import "@robosophy/tokens/tokens.css";
+import "@robosophy/ui-react/styles.css";
+```
+
+Component styles are carried by the component entrypoints. Import `@robosophy/ui-react/styles.css` once in your app.
+
+## Next.js Integration
+
+For Next.js apps, import CSS in your root layout:
+
+```tsx
+// app/layout.tsx
+import "@robosophy/tokens/tokens.css";
+import "@robosophy/ui-react/styles.css";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+For the Material Symbols plugin, add it to your `next.config.js`:
+
+```js
+// next.config.js
+const { robosophyMaterialSymbols } = require("@robosophy/ui-react/vite");
+
+module.exports = {
+  webpack: (config) => {
+    config.plugins.push(robosophyMaterialSymbols());
+    return config;
+  },
+};
+```

package/README.md

@@ -0,0 +1,197 @@
+# @robosophy/ui-react
+
+React component library for shared Robosophy UI.
+
+## Documentation
+
+Interactive component documentation, examples, props, and usage notes are available via Storybook:
+
+```sh
+npm run storybook:react
+```
+
+Then open http://localhost:6007/
+
+## Install
+
+With PrimeReact:
+
+```sh
+npm install @robosophy/ui-react @robosophy/prime-theme react react-dom primereact
+```
+
+Without PrimeReact:
+
+```sh
+npm install @robosophy/ui-react @robosophy/tokens react react-dom
+```
+
+## PrimeReact theme
+
+If your app uses PrimeReact, configure the Robosophy preset and load its tokens/overrides once:
+
+```tsx
+// app/layout.tsx or pages/_app.tsx
+import { PrimeReactProvider } from "primereact/api";
+import RobosophyPreset from "@robosophy/prime-theme";
+import "@robosophy/prime-theme/prime.css";
+import "@robosophy/ui-react/styles.css";
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <PrimeReactProvider value={{ theme: { preset: RobosophyPreset } }}>
+      <Component {...pageProps} />
+    </PrimeReactProvider>
+  );
+}
+```
+
+`prime.css` already imports `@robosophy/tokens/tokens.css`, so don't duplicate that import.
+
+If your app doesn't use PrimeReact, import tokens once:
+
+```tsx
+import "@robosophy/tokens/tokens.css";
+import "@robosophy/ui-react/styles.css";
+```
+
+Components carry their own local styles through their component entrypoint.
+
+## AI agent context
+
+For agents working inside a consuming project, read these package files first:
+
+- `node_modules/@robosophy/ui-react/AGENTS.md`: short rules for prioritizing Robosophy components.
+- `node_modules/@robosophy/ui-react/dist/index.d.ts`: exact exported types and component contracts.
+
+Use `@robosophy/ui-react` components before creating local equivalents. Keep router, stores, fetches, permissions, and logout in the consuming app.
+
+## Usage
+
+```tsx
+import { RsIcon, RsSidebar, rsPrimeIcon } from "@robosophy/ui-react";
+import type { RsSidebarItem, RsSidebarModule } from "@robosophy/ui-react";
+
+const sidebarItems: RsSidebarItem[] = [
+  { id: "dashboard", label: "Dashboard", icon: "dashboard", active: true },
+  { id: "settings", label: "Configuracion", icon: "settings" },
+];
+
+const sidebarModules: RsSidebarModule[] = [
+  { text: "Mi Alta", link: "/alta" },
+  { text: "Mi Cuenta y Orden", link: "/cyo", active: true },
+  { text: "Mi Cuenta Corriente", link: "/cc" },
+];
+
+function App() {
+  const handleItemClick = (item: RsSidebarItem) => {
+    console.log("Item clicked:", item);
+  };
+
+  const handleModuleSelect = (module: RsSidebarModule) => {
+    console.log("Module selected:", module);
+  };
+
+  return (
+    <>
+      <RsSidebar
+        items={sidebarItems}
+        modules={sidebarModules}
+        navigateOnModuleSelect={false}
+        onItemClick={handleItemClick}
+        onModuleSelect={handleModuleSelect}
+      />
+
+      <RsIcon name="home" />
+    </>
+  );
+}
+```
+
+## Material Symbols
+
+`RsIcon` renders inline SVG icons. Combine it with the Vite plugin that downloads only the necessary SVGs from the official Google repository and generates a sprite injected into the HTML:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { robosophyMaterialSymbols } from "@robosophy/ui-react/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    robosophyMaterialSymbols(),
+  ],
+});
+```
+
+The plugin automatically scans for `<RsIcon name="..." />`, `rsPrimeIcon("...")`, and objects with `icon: "..."` in the source code. No need to declare icons manually. During build, it downloads SVGs from the GitHub CDN, caches them locally, and generates an inline SVG sprite. No font files are loaded.
+
+The sprite includes variants for fill (outlined/filled) and grade (-25, 0, 200).
+
+### Dynamic icons (optional)
+
+If an icon is calculated at runtime (API, permissions, remote config, etc.), declare it in `include` so the scanner includes it:
+
+```ts
+robosophyMaterialSymbols({
+  include: [
+    "home",
+    { family: "rounded", name: "settings" },
+  ],
+});
+```
+
+### PrimeReact
+
+For PrimeReact APIs that receive `icon` as a string, use the helper:
+
+```tsx
+import { Button } from "primereact/button";
+import { rsPrimeIcon } from "@robosophy/ui-react";
+
+<Button label="Inicio" icon={rsPrimeIcon("home")} />
+<Button label="Configurar" icon={rsPrimeIcon("settings", { family: "rounded" })} />
+```
+
+For full control over props (fill, grade, etc.), use the `icon` slot:
+
+```tsx
+import { Button } from "primereact/button";
+import { RsIcon } from "@robosophy/ui-react";
+
+<Button label="Favorito" icon={<RsIcon name="favorite" fill color="danger" />} />
+```
+
+## Component Structure
+
+Every public component must be self-contained:
+
+```txt
+src/components/RsSidebar/
+  RsSidebar.tsx
+  RsSidebar.css
+  RsSidebar.types.ts
+  RsSidebar.test.tsx
+  RsSidebar.stories.tsx
+  index.ts
+```
+
+Rules:
+
+- use `@robosophy/tokens` variables for visual decisions;
+- keep styles local to the component folder;
+- add tests and Storybook stories with every exported component;
+- use props for stable API and render props for flexible project content;
+- use PrimeReact only when it provides behavior that belongs inside the component.
+- use PrimeReact `Button` for actions in PrimeReact apps.
+- use `RsSidebar` for reusable module navigation instead of project-local navbars.
+
+## Scripts
+
+```sh
+npm run build -w @robosophy/ui-react
+npm run test -w @robosophy/ui-react
+npm run build:storybook -w @robosophy/ui-react
+```

package/dist/RsIcon.types-eBKVmRTF.d.ts

@@ -0,0 +1,23 @@
+type RsIconFamily = "outlined" | "rounded" | "sharp";
+type RsIconSize = "sm" | "md" | "lg" | number;
+type RsIconColor = "primary" | "secondary" | "success" | "warning" | "danger" | "inherit" | (string & {});
+type RsIconWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700;
+type RsIconProps = {
+    name: string;
+    family?: RsIconFamily;
+    size?: RsIconSize;
+    color?: RsIconColor;
+    fill?: boolean;
+    weight?: RsIconWeight;
+    grade?: number;
+    interactive?: boolean;
+    ariaLabel?: string;
+    notification?: boolean;
+    notificationColor?: string;
+    className?: string;
+};
+type RsPrimeIconOptions = {
+    family?: RsIconFamily;
+};
+
+export type { RsIconColor as R, RsIconFamily as a, RsIconProps as b, RsIconSize as c, RsIconWeight as d, RsPrimeIconOptions as e };