this.gui 1.0.15 → 1.0.17

package/README.md

@@ -1,76 +1,205 @@
 <img src="https://suign.github.io/assets/imgs/this_GUI.svg" alt="Cleaker Me" width="377" height="377">
 
-# THIS.GUI
-The goal is to automate the **GUI** generation process so users only pass data or configurations, and **this.GUI** handles the rest.
-The package exports:
-	•	Pre-defined components.
-	•	MDX and Theme Providers.
-	•	An MDX editor interface.
-
-Install `this.gui` via **npm**:
-```shell
+
+
+# **THIS.GUI**
+
+**this.GUI** aims to automate the **GUI** generation process by allowing users to pass data or configurations. It then dynamically builds the UI based on these inputs. This package exports pre-defined components, theme providers, MDX integration, and a Site/App builder for rapid prototyping and deployment.
+
+#### **Installation & Setup**
+
+Install this.gui via **npm**:
+
+```bash
 npm install this.gui
 ```
-Then run command:
-```bash
+
+After installation, you can start the development server using:
+
+```bas
 npm start
+```
+
+This command will initialize the app, allowing you to use the **Site Builder** and **Component Library**.
+
+#### **Key Features**
+
+**1. Pre-built Components**
+
+​	•	**Atoms**: Smallest building blocks like buttons, inputs, text elements, etc.
+
+​	•	**Molecules**: Combinations of atoms to form reusable UI elements like cards, forms, tables, etc.
+
+​	•	**Organisms**: More complex components that combine multiple molecules.
+
+​	•	**Layouts & Templates**: Predefined page structures that can be customized using the JSON configuration.
+
+#### **2. MDX & Theme Providers**
+
+​	•	MDX integration for dynamic content rendering.
+
+​	•	Easy-to-use theme providers for switching between light and dark modes.
+
+#### **3. Site & App Builder**
+
+​	•	Drag-and-drop interface for building entire pages or applications.
+
+​	•	Generates JSON configuration that maps to your UI structure.
+
+​	•	The JSON-based UI renderer automatically handles rendering of components based on the passed configuration.
+
+**Getting Started**
+
+Here’s a quick overview of how to use **this.GUI** in your project.
+
+**1. Direct JSX Usage**
+
+The **index.js** file allows you to import and use pre-built components directly in your JSX/JS files.
+
+```jsx
+import { Button, TextInput } from 'this.gui/Atoms';
 
+function MyComponent() {
+ return (
+    <div>
+   <Button label="Click Me" color="primary" />
+   <TextInput placeholder="Enter text" />
+  </div>
+ );
+}
 ```
-a. Export Pre-built Components
-Components are categorized (Atoms, Molecules, etc.) and are exportable so users can easily import them into their MDX files or directly in their React components.
 
-## **Explanation of Grouping:**
-​	•	**Atomic**: Smallest components that are not broken down further.
-Alert, Audio, Badge, Button, Caption, Checkbox, Container, Divider, Heading, Icon,  Image, Label, Link , Loader, Paragraph, ProgressBar, RadioButton, RangeInput, Select, Slider, Snackbar, Spacer, Spinner, Tag, TextArea, TextInput, Toggle, Tooltip, Video.
+**2. Dynamic UI via JSON**
+
+Use the **ComponentRegistry** and **renderComponent** function to build dynamic UIs from JSON configurations.
+
+Example JSON:
+
+```json
+{
+ "layout": [
+  {
+   "type": "Button",
+   "props": { "label": "Click Me", "color": "primary" }
+  },
+  {
+   "type": "Heading",
+   "props": { "text": "Welcome to Our Site", "level": 1 }
+  }
+ ]
+}
+```
+
+Rendering the above JSON with **this.GUI**:
+
+```jsx
+import React from 'react';
+import { Page } from 'this.gui/Page';
+
+const config = {
+ layout: [
+  { type: 'Button', props: { label: 'Click Me', color: 'primary' } },
+  { type: 'Heading', props: { text: 'Welcome to Our Site', level: 1 } }
+ ]
+};
+
+function App() {
+ return <Page config={config} />;
+}
+```
+
+**3. Component Registry & JSON Mapping**
+
+**ComponentRegistry** maps JSON keys to the corresponding React components. This allows dynamic rendering of components via JSON without directly importing each component.
+
+```jsx
+const ComponentRegistry = {
+ Button: Atoms.Button,
+ Heading: Atoms.Heading,
+ Paragraph: Atoms.Paragraph,
+ *// More mappings...*
+};
+```
+
+**Component Categories**
+
+​	•	**Atoms**: Small, reusable components like Buttons, Inputs, Paragraphs.
+
+​	•	Examples: Button, TextInput, Paragraph, Image, Icon, etc.
+
+​	•	**Molecules**: Components that combine multiple atoms.
+
+​	•	Examples: Card, Navbar, Breadcrumbs, FormField, AudioPlayer, etc.
 
-​	•	**Molecules**: Simple combinations of atomic components that together form a small UI feature.
-Accordion, AudioPlayer, AvatarWithName, Breadcrumbs, ButtonGroup, Card, ComparisonTable, DataTable, FileUpload, FormField, Header, IconButton, ImageWithCaption, InputGroup, InputWithLabel, List, MediaCard, Modal, Navbar, Notification, PricingTable, SearchBar, Sidebar, VideoWithDescription.
+​	•	**Organisms**: More complex components combining multiple molecules.
 
-​	•	**Organisms**: More complex, combining molecules and atomic components to create larger, more detailed features.
-​	•	**Layout**: Components related to structuring and organizing content across the page.
-​	•	**Templates**: Layouts of full pages, combining organisms and layout components.
-​	•	**Pages**: Complete and functional pages made up of templates and content.
-​	•	**Miscellaneous**: Utility components that don’t fit into the above categories but provide important functions, such as popovers, overlays, and media controls.
+​	•	Examples: LoginForm, SidebarLayout, etc.
 
-On installation this.GUI will be setup as:
+​	•	**Layouts & Templates**: Complete page structures.
 
+​	•	Examples: TwoColumnLayout, LandingPageTemplate, etc.
 
-├── /GUI                # Dedicated directory for GUI components and MDX pages
-│   ├── /components     # Custom components created by the user
-│   ├── /mdx            # MDX files defining pages and content using components
-│   └── /styles         # Custom styles for components (optional)
 
-Breakdown of Each Subdirectory:
-/components:
-This is where users build their custom React components. They can create new components, extend existing ones from this.GUI, or modify them as needed. These components can then be used throughout the MDX files.
 
-/mdx:
-This folder is used to store MDX files that act as pages or sections of the application. Users can import and use components from the /components folder or from the generic set provided by this.GUI. This allows for a highly modular and customizable interface creation.
+**Key Components**
 
-/styles:
-This optional directory can be used for custom CSS or style files that modify the look and feel of the components and layouts. Users can define global styles, component-specific styles, or themes to match their brand.
+1. **Component Registry**
 
-Workflow for Users:
-Install this.GUI:
-npm install this.GUI will automatically set up the /GUI directory with the necessary subdirectories.
+•	Maps JSON keys to components for dynamic rendering.
 
-Create Components:
-Users can start creating their own components in /components, using the provided components as a base or inspiration.
+2. **JSON Configuration Files**
 
-Build Pages with MDX:
-MDX files in the /mdx folder can be used to assemble pages, where users can directly import and use the components they've created.
+•	Define the layout and structure of your UI in JSON.
+
+3. **Rendering Engine**
+
+•	Reads the JSON configuration and renders the appropriate components dynamically.
+
+
+
+**Example Usage**
+
+Here’s an example that showcases how to use the JSON configuration for rendering a dynamic UI.
+
+```json
+{
+ "layout": [
+  {
+   "type": "Card",
+   "props": { "variant": "solid", "color": "primary-color", "width": "300px" },
+   "children": [
+    {
+     "type": "Paragraph",
+     "props": { "text": "Welcome to our site!" }
+    }
+   ]
+  }
+ ]
+}
+```
+
+
+
+You can pass this JSON configuration to the Page component to render the UI dynamically:
+
+```jsx
+import { Page } from 'this.gui/Page';
+import config from './config.json'; *// Import the JSON configuration*
+
+function App() {
+ return <Page config={config} />;
+}
+```
 
-Style Customization:
-Any additional styling or theming can be managed in the /styles directory, keeping design consistent and organized.
+**Additional Resources**
 
-Run and Test:
-Users run their main app using their existing development setup, and the MDX files will render the React components, effectively creating the desired GUI.
+​	•	**Storybook**: For browsing and testing all pre-built components. Launch Storybook with:
 
-Build for Production:
-Once development is complete, the GUI directory can be built into a dist folder, packaging the components, pages, and styles for deployment or distribution.
+npm run storybook
 
-This approach keeps the GUI modular, maintainable, and focused on user experience design, while the backend and other logic remain separate and manageable.
+​	•**MDX Editor**: Edit and visualize MDX content in real time.
 
+**this.GUI** is part of the **Neurons.me** ecosystem, a set of modular data structures designed to work together across multiple domains.
 
 # About All.This
 ###### Modular Data Structures