@ist-group/commonui-components-react

A comprehensive React components library with Tailwind CSS integration.

Installation

npm install @ist-group/commonui-components-react

Peer Dependencies

Make sure you have React 18+ installed:

npm install react react-dom

Usage

Basic Setup

Import the design tokens CSS in your application entry point:

import "@ist-group/commonui-components-react/style.css";

CuiApp Component

The CuiApp component provides the main application layout with menu, header, and content areas using a slot pattern (similar to Vue slots):

import { CuiApp, template } from "@ist-group/commonui-components-react";

function App() {
  return (
    <CuiApp
      initialMenuCollapsed={false}
      dashboard={true}
      onMenuToggle={(collapsed) => console.log("Menu:", collapsed)}
    >
      <template.menu>
        <YourMenu />
      </template.menu>
      <template.header>
        <YourHeader />
      </template.header>
      <YourContent />
    </CuiApp>
  );
}

Alternative: Using slot-name Attribute

You can also use the slot-name attribute on child elements:

<CuiApp>
  <div slot-name="menu">
    <YourMenu />
  </div>
  <div slot-name="header">
    <YourHeader />
  </div>
  <YourContent />
</CuiApp>

Using the App Context

Access app state and methods in any descendant component:

import { useCuiApp } from "@ist-group/commonui-components-react";

function MyComponent() {
  const { isMenuCollapsed, toggleMenu, isMobile, breadcrumbItems } =
    useCuiApp();

  return (
    <button onClick={toggleMenu}>
      {isMenuCollapsed ? "Open Menu" : "Close Menu"}
    </button>
  );
}

Optional Context Access

For components that work both inside and outside CuiApp:

import { useCuiAppOptional } from "@ist-group/commonui-components-react";

function FlexibleComponent() {
  const appContext = useCuiAppOptional();

  // Safe to use outside CuiApp
  const isMobile = appContext?.isMobile ?? false;

  return <div>{isMobile ? "Mobile View" : "Desktop View"}</div>;
}

Slots

CuiApp uses the @beqa/react-slots library for Vue-like slot support:

| Slot | Description | | --------- | ---------------------------- | | menu | Navigation menu content | | header | Header content | | default | Main content area (children) |

Creating Custom Slot Components

You can use the re-exported slot utilities to create your own slotted components:

import {
  createTemplate,
  useSlot,
  Slot,
  SlotChildren,
} from "@ist-group/commonui-components-react";

type MyComponentSlots = SlotChildren<Slot<"header"> | Slot<"footer"> | Slot>;

const myTemplate = createTemplate<MyComponentSlots>();

function MyComponent({ children }: { children: MyComponentSlots }) {
  const { slot } = useSlot(children);

  return (
    <div>
      <slot.header />
      <slot.default />
      <slot.footer />
    </div>
  );
}

Props

CuiApp Props

| Prop | Type | Default | Description | | ---------------------- | ----------------------------------- | ------- | ----------------------------------- | | initialMenuCollapsed | boolean | false | Initial collapsed state of the menu | | breadcrumbItems | BreadcrumbItem[] | [] | Initial breadcrumb items | | mobileBreakpoint | number | 768 | Mobile breakpoint in pixels | | dashboard | boolean | false | Dashboard mode (gray background) | | onMenuToggle | (collapsed: boolean) => void | - | Called when menu state changes | | onViewportChange | (isMobile: boolean) => void | - | Called on viewport changes | | onBreadcrumbsUpdate | (items: BreadcrumbItem[]) => void | - | Called when breadcrumbs update | | children | CuiAppSlots | - | Slotted content |

BreadcrumbItem

interface BreadcrumbItem {
  key?: string;
  label: string;
  href?: string;
  disabled?: boolean;
  data?: unknown;
}

Context Value

The useCuiApp() hook returns:

| Property | Type | Description | | ------------------- | ----------------------------------- | ----------------------------- | | isMenuCollapsed | boolean | Current menu collapsed state | | isMobile | boolean | Current mobile viewport state | | isDashboard | boolean | Current dashboard mode state | | breadcrumbItems | BreadcrumbItem[] | Current breadcrumb items | | toggleMenu | () => void | Toggle menu state | | closeMenu | () => void | Close (collapse) the menu | | updateBreadcrumbs | (items: BreadcrumbItem[]) => void | Replace all breadcrumbs | | addBreadcrumb | (item: BreadcrumbItem) => void | Add breadcrumb to end | | popBreadcrumb | () => void | Remove last breadcrumb | | clearBreadcrumbs | () => void | Clear all breadcrumbs |

License

MIT