@robosophy/ui-react

React component library for shared Robosophy UI.

Documentation

Interactive component documentation, examples, props, and usage notes are available via Storybook:

npm run storybook:react

Then open http://localhost:6007/

Install

With PrimeReact:

npm install @robosophy/ui-react @robosophy/prime-theme react react-dom primereact

Without PrimeReact:

npm install @robosophy/ui-react @robosophy/tokens react react-dom

PrimeReact theme

PrimeReact 10 usa un sistema de temas CSS. Necesitas importar el tema fluent-light seguido de los overrides de Robosophy:

// app/layout.tsx o pages/_app.tsx
import { PrimeReactProvider } from "primereact/api";
import "primereact/resources/themes/fluent-light/theme.css";
import "@robosophy/prime-theme/prime.css";
import "@robosophy/ui-react/styles.css";

function MyApp({ Component, pageProps }) {
  return (
    <PrimeReactProvider>
      <Component {...pageProps} />
    </PrimeReactProvider>
  );
}

Orden de importación (crítico):

1. Tema base de PrimeReact (ej: fluent-light/theme.css) — estilos estructurales
2. @robosophy/prime-theme/prime.css — aplica tokens --rs-* a componentes de PrimeReact

prime.css ya importa @robosophy/tokens/tokens.css, así que no dupliques ese import.

Solo fluent-light es compatible con los overrides de Robosophy.

If your app doesn't use PrimeReact, import tokens once:

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

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:

// 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:

robosophyMaterialSymbols({
  include: [
    "home",
    { family: "rounded", name: "settings" },
  ],
});

PrimeReact

For PrimeReact APIs that receive icon as a string, use the helper:

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:

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:

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

npm run build -w @robosophy/ui-react
npm run test -w @robosophy/ui-react
npm run build:storybook -w @robosophy/ui-react