0.8.20 • Published 3d ago

@weareconceptstudio/cs-admin

Licence

ISC

Version

0.8.20

Deps

Size

24 kB

Vulns

Weekly

Summary Dependency Versions

CS Admin

A comprehensive React-based admin panel system built with modern technologies and designed for scalability and flexibility.

Features

Resource Management: Full CRUD operations with dynamic actions
Form Builder: Advanced form components with validation
Media Management: File upload, organization, and manipulation
User Management: Authentication, authorization, and user roles
Internationalization: Multi-language support
Responsive Design: Mobile-first approach
Extensible Architecture: Plugin system and custom components
Design System: Comprehensive UI component library
Performance: Optimized for large datasets
Security: Built-in security best practices

Installation
Quick Start
Architecture
Core Features
Form Components
Design System
Configuration
Advanced Features
Styling
Documentation
API Reference
Migration Guide
Contributing
License

Installation

npm install @weareconceptstudio/cs-admin

Peer Dependencies

npm install react react-dom react-router-dom

Required Icons

# Download and include icon fonts
# Place in your public directory and import in your main CSS
@import './icons/style.css';

Quick Start

import React from 'react';
import { render } from 'react-dom';
import { Admin, Resource, createAdminConfig } from '@weareconceptstudio/cs-admin';

// Import icons
import './icons/style.css';

// Admin configuration (same pattern as Laravel config/admin.php → media)

const config = createAdminConfig({
	siteName: 'My Admin Panel',
	apiPrefix: '/api/admin/',
	adminPrefix: '/admin',
	media: {
		libraryPath: '/media-library',
		canDimensionChange: true,
		showInMenu: true,
	},
	languages: [
		{ id: 'en', name: 'English' },
		{ id: 'es', name: 'Spanish' },
	],
	menu: {
		main: [
			{
				title: 'Content',
				children: [
					{
						title: 'Posts',
						path: '/admin/posts',
						icon: 'posts',
						key: 'posts',
					},
				],
			},
		],
	},
};

// Resource configuration
const postConfig = {
	title: 'Posts',
	path: 'posts/*',
	name: 'posts',
	columns: [
		{ title: 'Title', dataIndex: 'title', key: 'title' },
		{ title: 'Status', dataIndex: 'status', key: 'status' },
		{ title: 'Created', dataIndex: 'created_at', key: 'created_at' },
	],
	form: PostForm,
};

render(
	<Admin {...config}>
		<Resource {...postConfig} />
	</Admin>,
	document.getElementById('root')
);

Architecture

CS Admin is built with a modular architecture consisting of three main packages:

1. `@weareconceptstudio/cs-admin-core`

Core functionality and utilities:

State Management: Zustand-based stores for data and media
API Layer: Axios-based HTTP client with interceptors
Hooks: Custom React hooks for common operations
Context Providers: React context for global state
Utilities: Helper functions and data manipulation

2. `@weareconceptstudio/cs-admin-ui`

UI components and layouts:

Design System: Reusable UI components
Form Components: Advanced form fields and validation
Resource Management: List, create, edit, and show views
Layout Components: Header, sidebar, and page layouts
Media Manager: File upload and management interface

3. `@weareconceptstudio/cs-admin`

Main package that combines core and UI:

Admin Component: Main admin panel wrapper
Resource Component: CRUD resource management
Pages Component: Custom page management
Exports: All components and utilities

Core Features

Resource Management

Create full CRUD interfaces with minimal configuration:

<Resource
	title='Users'
	path='users/*'
	name='users'
	columns={[
		{ title: 'Name', dataIndex: 'name' },
		{ title: 'Email', dataIndex: 'email' },
		{ title: 'Role', dataIndex: 'role' },
	]}
	form={UserForm}
	// Dynamic actions
	dynamicActions={{
		edit: (record) => ({
			show: record.canEdit,
			disabled: record.isLocked,
		}),
		delete: {
			condition: (record) => record.canDelete,
		},
	}}
	// Custom actions
	customActions={[
		{
			key: 'activate',
			iconName: 'check',
			text: 'Activate',
			condition: (record) => record.status === 'inactive',
			onClick: (record) => activateUser(record.id),
		},
	]}
/>

Dynamic Actions System

The new dynamic actions system allows for sophisticated action management:

// Conditional actions based on record data
dynamicActions: {
  edit: (record, context) => ({
    show: record.status !== 'archived',
    disabled: record.isLocked,
    iconColor: record.isDraft ? 'orange' : 'black'
  }),

  delete: {
    condition: (record) => record.canDelete && record.orderCount === 0,
    iconColor: 'red'
  }
}

// Custom actions with full flexibility
customActions: [
  {
    key: 'approve',
    iconName: 'check',
    text: 'Approve',
    condition: (record) => record.status === 'pending',
    onClick: (record, context) => {
      approveRecord(record.id);
      context.refreshList?.();
    }
  }
]

Form Builder

Advanced form components with validation and media support:

import {
	FormContainer,
	InputField,
	SelectField,
	MediaPicker,
	Editor,
	DateTimePicker,
	ColorPicker,
} from '@weareconceptstudio/cs-admin';

const PostForm = ({ action, current, onFinish }) => {
	return (
		<FormContainer
			onFinish={onFinish}
			initialValues={current}
			layout='vertical'>
			<InputField
				name='title'
				label='Title'
				rules={[{ required: true, message: 'Title is required' }]}
			/>

			<Editor
				name='content'
				label='Content'
				config={{
					toolbar: ['heading', 'bold', 'italic', 'link'],
				}}
			/>

			<MediaPicker
				name='featured_image'
				label='Featured Image'
				accept={['image/*']}
				maxFiles={1}
			/>

			<SelectField
				name='category'
				label='Category'
				options={categoryOptions}
				mode='multiple'
			/>

			<DateTimePicker
				name='publish_date'
				label='Publish Date'
				showTime
			/>
		</FormContainer>
	);
};

Media Management

Comprehensive media handling with file organization:

import { MediaPicker, MediaManager } from '@weareconceptstudio/cs-admin';

// In forms
<MediaPicker
  name="gallery"
  label="Gallery"
  accept={['image/*', 'video/*']}
  maxFiles={10}
  multiple
/>

// Standalone media manager
<MediaManager
  onSelect={(files) => console.log('Selected files:', files)}
  accept={['image/*']}
  maxFiles={5}
/>

Internationalization

Built-in multi-language support:

const config = {
	languages: [
		{ id: 'en', name: 'English' },
		{ id: 'es', name: 'Spanish' },
		{ id: 'fr', name: 'French' },
	],
	defaultLanguage: 'en',
};

// In forms
<FormContainer trans={true}>
	<InputField
		name='title'
		label='Title'
		trans={true} // Enables translation fields
	/>
</FormContainer>;

User Management

Complete user management system:

// User management is built-in
const config = {
	menu: {
		main: [
			{
				title: 'Users',
				children: [
					{
						title: 'All Users',
						path: '/admin/users',
						key: 'users',
					},
					{
						title: 'My Account',
						path: '/admin/account/my-account',
						key: 'my-account',
					},
				],
			},
		],
	},
};

Design System

CS Admin includes a comprehensive design system:

Components

Button: Various button styles and sizes
InputField: Text inputs with validation
SelectField: Dropdown and multi-select
Table: Data tables with sorting and filtering
Modal: Popups and confirmations
Status: Status indicators
Loader: Loading states
Icon: Icon system
Color: Color picker and display
Container: Layout containers
Tabs: Tab navigation
Switch: Toggle switches
Pagination: Page navigation

Form Components

CS Admin includes a comprehensive set of form components for building complex admin interfaces:

FormContainer: Main form wrapper with layout, validation, and form management
InputField: Versatile input component supporting text, textarea, number, search, checkbox, and switch types
SelectField: Dropdown selection with single/multiple selection and option grouping
Editor: Rich text editor based on CKEditor 5 with image upload support
MediaPicker: File upload and media selection with dimension requirements
DateTimePicker: Date and time selection with multiple picker types
ColorPicker: Visual color selection with color picker interface
ColorField: Color selection from predefined color options
ArrayField: Dynamic array fields with drag-and-drop reordering
TreeSelectField: Hierarchical selection for tree-structured data
SlugField: Automatic URL-friendly slug generation
MetaInputs: Predefined SEO meta fields (title, description, image)

Complete Form Components Documentation: See FORM_COMPONENTS.md for detailed API reference, usage examples, and best practices for all form components.

Configuration

Admin Configuration

import { createAdminConfig } from '@weareconceptstudio/cs-admin';

const config = createAdminConfig({
	// Branding
	siteName: 'My Admin Panel',
	logo: '/path/to/logo.svg',

	// Routing / API
	adminPrefix: '/admin/',
	apiPrefix: '/api/admin/',
	homePage: '/admin/dashboard',
	loginRedirectPage: '/admin/dashboard',

	// Admin interface language (panel UI)
	adminLanguage: 'en',
	hasAdminLanguageSwitcher: true,
	adminLanguages: [
		{ id: 'en', name: 'English' },
		{ id: 'hy', name: 'Հայերեն' },
		{ id: 'ru', name: 'Русский' },
	],

	// Content languages (translatable resources)
	defaultLanguage: 'en',
	languages: [
		{ id: 'en', name: 'English' },
		{ id: 'es', name: 'Spanish' },
	],

	// Authentication (OTP)
	hasOtpAuth: true,
	otpVerifyPath: 'login/verify-otp',
	otpResendPath: 'login/resend-otp',

	// Notifications
	notification: true,
	notificationStatusPath: 'notification-status',
	notificationsPath: 'notifications',
	notificationLinkPrefix: '/admin',

	// Header account menu
	headerMenuItems: [
		{ name: 'my_account', path: 'account/my-account', roles: 'all' },
		{ name: 'users', path: 'account/users', roles: ['developer', 'admin'] },
	],

	// Sidebar menu
	menu: {
		main: [
			{
				title: 'general',
				children: [
					{
						title: 'dashboard',
						path: '/admin/dashboard',
						icon: 'dashboard',
						key: 'dashboard',
					},
				],
			},
		],
		collapsed: {
			settings: {
				title: 'settings',
				children: [{ title: 'general', path: '/admin/settings/general' }],
			},
		},
	},

	// Global input constraints
	inputConfig: {
		characterCounts: {
			h1: 50,
			h2: 100,
			h3: 200,
			h4: 300,
			h5: 400,
			h6: 500,
			p1: 600,
			p2: 700,
			body: 800,
		},
	},

	// Custom translation dictionary overrides
	translations: {},

	// Media library (preferred nested config)
	media: {
		libraryPath: '/media-library',
		canDimensionChange: true,
		showInMenu: true,
		menuTitle: 'media_library',
		menuIcon: 'admin-media-library',
		menuSection: 'main', // currently supports "main"
		folders: {
			enabled: true,
			nameMaxLength: 120,
			syncDirectoryToUrl: true,
			urlParam: 'directory',
		},
		endpoints: {
			folders: 'media-folders',
			assets: 'medias',
			move: 'medias-move',
			copy: 'medias-copy',
			crop: 'medias-crop',
			replace: 'medias-replace',
			resize: 'medias-change-dimensions',
			download: 'medias-download',
			source: 'medias-source',
		},
	},

	// Legacy media keys (still supported, mapped to media.*)
	mediaLibraryPath: '/media-library',
	canMediaDimensionChange: true,
});

Notes:

Use createAdminConfig() so defaults are merged and legacy keys are normalized.
Prefer media.libraryPath and media.canDimensionChange; mediaLibraryPath and canMediaDimensionChange are backward-compatible aliases.
Endpoints are relative to apiPrefix.

Resource Configuration

const resourceConfig = {
	// Basic settings
	title: 'Posts',
	name: 'posts',
	path: 'posts/*',
	primaryKey: 'id',

	// Display options
	hasList: true,
	hasCreate: { path: true, button: true },
	hasEdit: true,
	hasShow: true,
	hasDelete: true,
	hasReplicate: false,

	// Table configuration
	columns: [
		{ title: 'Title', dataIndex: 'title', key: 'title' },
		{ title: 'Status', dataIndex: 'status', key: 'status' },
	],
	tableProps: {
		expandable: true,
		scroll: { x: 1000 },
	},

	// Pagination
	hasPagination: true,
	defaultPage: 1,
	defaultPageSize: 15,

	// Filtering and search
	hasFilter: true,
	hasSearch: true,
	hasSortBy: true,

	// Form configuration
	form: PostForm,

	// Dynamic actions
	dynamicActions: {
		edit: (record) => ({ show: record.canEdit }),
		delete: { condition: (record) => record.canDelete },
	},

	// Custom actions
	customActions: [
		{
			key: 'publish',
			iconName: 'check',
			text: 'Publish',
			condition: (record) => record.status === 'draft',
			onClick: (record) => publishPost(record.id),
		},
	],
};

Advanced Features

Custom Hooks

import { useList, useCurrent, useMedia, useNotification, useUpload } from '@weareconceptstudio/cs-admin';

// Data management
const { list, loading, getList, create, update, delete: deleteItem } = useList();

// Media management
const { upload, uploads, remove } = useMedia();

// Notifications
const { openNotification } = useNotification();

// File upload
const { uploadFile, progress } = useUpload();

Custom Components

import { withUIContext } from '@weareconceptstudio/cs-admin-core';

const CustomComponent = ({ openPopup, winWidth }) => {
	return (
		<div>
			<h3>Custom Component</h3>
			<button onClick={() => openPopup(<MyModal />)}>Open Modal</button>
		</div>
	);
};

export default withUIContext(CustomComponent, ['openPopup', 'winWidth']);

API Integration

import { api } from '@weareconceptstudio/cs-admin-core';

// Custom API calls
const fetchCustomData = async () => {
	try {
		const response = await api.get('/custom-endpoint');
		return response.data;
	} catch (error) {
		console.error('API Error:', error);
	}
};

Styling

CS Admin uses styled-components for styling and supports:

Theme Customization: Override default colors and styles
Responsive Design: Mobile-first approach
Component Styling: Individual component customization
Global Styles: Site-wide style overrides

import { ThemeProvider } from 'styled-components';

const theme = {
	colors: {
		primary: '#1890ff',
		secondary: '#52c41a',
		danger: '#ff4d4f',
	},
	fonts: {
		primary: 'Inter, sans-serif',
	},
};

<ThemeProvider theme={theme}>
	<Admin {...config}>{/* Your admin content */}</Admin>
</ThemeProvider>;

Complete Form Components Documentation - Detailed API reference, usage examples, and best practices for all form components including FormContainer, InputField, SelectField, Editor, MediaPicker, and more.

Resource Structure

Resource Structure Documentation - Comprehensive guide to the Resource component, including configuration options, dynamic actions, custom actions, and usage examples.

DesignSystem Components

DesignSystem Components Documentation - Complete reference for all reusable UI components including Button, Table, Status, Switch, and more.

Core Stores

Core Stores Documentation - Comprehensive guide to state management with Global Store, List Store, Current Store, Media Store, and Core Context.

Examples

Check the examples/ directory for complete working examples:

demo-admin: Basic admin panel setup
demo-murakami: E-commerce admin interface
demo-uniqueorn: Content management system

Quick Start

Basic Setup

import React from 'react';
import { render } from 'react-dom';
import { Admin, Resource } from '@weareconceptstudio/cs-admin';

// Import icons
import './icons/style.css';

const config = {
	siteName: 'My Admin Panel',
	apiPrefix: 'http://localhost:8000/api/admin/',
	adminPrefix: '/admin',
	languages: [
		{ id: 'en', name: 'English' },
		{ id: 'es', name: 'Spanish' },
	],
	menu: {
		main: [
			{
				title: 'Content',
				children: [
					{
						title: 'Posts',
						path: '/admin/posts',
						icon: 'posts',
						key: 'posts',
					},
				],
			},
		],
	},
};

render(
	<Admin {...config}>
		<Resource
			title='Posts'
			path='posts/*'
			name='posts'
			columns={[
				{ title: 'Title', dataIndex: 'title' },
				{ title: 'Status', dataIndex: 'status' },
			]}
			form={PostForm}
		/>
	</Admin>,
	document.getElementById('root')
);

Dynamic Actions Example

<Resource
	title='Users'
	path='users/*'
	name='users'
	columns={[
		{ title: 'Name', dataIndex: 'name' },
		{ title: 'Email', dataIndex: 'email' },
		{ title: 'Role', dataIndex: 'role' },
	]}
	form={UserForm}
	// Dynamic actions based on record data
	dynamicActions={{
		edit: (record) => ({
			show: record.canEdit,
			disabled: record.isLocked,
		}),
		delete: {
			condition: (record) => record.canDelete,
		},
	}}
	// Custom actions
	customActions={[
		{
			key: 'activate',
			iconName: 'check',
			text: 'Activate',
			condition: (record) => record.status === 'inactive',
			onClick: (record) => activateUser(record.id),
		},
	]}
/>

Migration Guide

From showOptions to Dynamic Actions

// Old (showOptions - deprecated)
const oldConfig = {
	showOptions: {
		url: (record) => `/articles/${record.slug}`,
		onClick: (record) => openInModal(record),
	},
};

// New (dynamicActions.show)
const newConfig = {
	dynamicActions: {
		show: {
			path: (record) => `/articles/${record.slug}`,
			onClick: (record, context) => openInModal(record, context),
			condition: (record) => record.isPublic,
			iconColor: 'blue',
		},
	},
};

API Reference

Admin Component Props

Prop	Type	Default	Description
`siteName`	string	-	Site name displayed in header
`logo`	string	-	Logo image path
`apiPrefix`	string	-	API base URL
`adminPrefix`	string	`/admin`	Admin route prefix
`languages`	array	`[]`	Available languages
`defaultLanguage`	string	`'en'`	Default language
`menu`	object	`{}`	Navigation menu configuration
`homePage`	string	-	Home page route
`loginRedirectPage`	string	-	Post-login redirect
`mediaLibraryPath`	string	`/`	Media library route
`notification`	boolean	`false`	Enable notifications

Resource Component Props

Prop	Type	Default	Description
`title`	string	-	Resource title
`name`	string	-	Resource name (API endpoint)
`path`	string	-	Route path pattern
`primaryKey`	string	`'id'`	Primary key field
`columns`	array	`[]`	Table columns configuration
`form`	component	-	Form component
`hasList`	boolean	`true`	Enable list view
`hasCreate`	boolean/object	`true`	Enable create view
`hasEdit`	boolean	`true`	Enable edit view
`hasShow`	boolean	`false`	Enable show view
`hasDelete`	boolean	`true`	Enable delete action
`hasReplicate`	boolean	`false`	Enable replicate action
`dynamicActions`	object	`{}`	Dynamic action configuration
`customActions`	array	`[]`	Custom action definitions

License

This project is licensed under the ISC License - see the LICENSE file for details.

Support

Documentation: Check our comprehensive docs above
Email: info@conceptstudio.am

Acknowledgments

Built with React
UI components based on Ant Design
Rich text editing powered by CKEditor 5
State management with Zustand

Built with by Concept Studio

Keywords

react admin dashboard cms form-builder crud typescript ui-components design-system admin-panel