@ramme-io/ui 1.0.3 → 1.1.0

package/README.md

@@ -2,34 +2,27 @@
 
 [![NPM Version](https://img.shields.io/npm/v/@ramme-io/create-app.svg)](https://www.npmjs.com/package/@ramme-io/ui) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**The structural frame for the modern web.**
+**The blocks for the build kit.**
 
-Ramme UI is a curated bundle of industry-standard libraries, accessible components, and architectural best practices designed for rapid prototyping.
-
-It creates a "Golden Path" for product designers and engineers who need to validate ideas quickly without getting bogged down in configuration. By bundling the best open-source tools into a cohesive system, Ramme allows you to build high-fidelity, interactive prototypes that are production-ready from day one.
+Ramme UI is a basic bundle of standard, accessible components, and best practices ready for rapid prototyping.
 
 ---
 
-## The Architecture
-Ramme (Danish for "Frame") is not about reinventing the wheel. It is about providing a solid steel frame so you can focus on the walls and windows.
+## The Basics
 
-We have orchestrated the most robust third-party libraries in the ecosystem into a single, opinionated toolkit:
+We have collected popular third-party libraries into a single build kit:
 
 * **Engine:** React 19+
-* **Styling:** Tailwind CSS (configured for rapid iteration)
-* **Primitives:** Radix UI (for unstyled, accessible interactive elements)
-* **Motion:** Framer Motion (for high-fidelity interaction design)
+* **Styling:** Tailwind CSS 
+* **Primitives:** Radix UI 
+* **Motion:** Framer Motion 
 * **Icons:** Lucide React
 
-This is not a "walled garden." It is a standardized set of building materials that respects your need for speed and flexibility.
-
 ---
 
 ## Quick Start
 
-The fastest way to start building is to use our CLI tool, which scaffolds a Vite-powered application with the Ramme Design System pre-configured.
-
-Run the following command in your terminal:
+To spin up a new project, run the initialization command in your terminal. This will generate a new folder with all resources linked and configured.
 
 *(Replace `my-new-project` with your desired folder name).*
 
@@ -41,11 +34,11 @@ This single command will:
 1.  **Scaffold** a high-performance Vite project structure.
 2.  **Install** React 19, TypeScript, and Tailwind CSS.
 3.  **Configure** the `@ramme-io/ui` component library and design tokens.
-4.  **Optimize** linting and build settings for immediate deployment.
+4.  **Optimize** limited configuration for customization.
 
 ---
 
-## Launch Sequence
+## Getting Started
 
 Once the scaffolding is complete, initialize your local environment:
 
@@ -60,18 +53,18 @@ pnpm install
 # or npm install
 ```
 
-**3. Ignite the dev server**
+**3. Start the dev server**
 ```bash
 pnpm run dev
 ```
 
-Your prototype is now live at `http://localhost:5173`.
+Your prototype is running locally at `http://localhost:5173`.
 
 ---
 
 ## The Tech Stack
 
-This starter kit is not a proprietary framework; it is an opinionated orchestration of the best open-source tools available:
+This starter kit is an opinionated selection of the best open-source tools available:
 
 * **Vite:** Next-generation tooling for instant server start and lightning-fast HMR (Hot Module Replacement).
 * **React:** The standard library for building composable user interfaces.
@@ -130,7 +123,7 @@ export default LandingPage;
 
 ## Local Development
 
-If you want to contribute to the framework or customize the primitives, you can run our component workbench locally.
+If you want to contribute to the project or customize the primitives, you can run our component workbench locally.
 
 1. Install Dependencies:
 
@@ -145,18 +138,16 @@ pnpm run storybook
 ```
 ---
 
-## The Ramme Ecosystem
-
-This tool is part of a suite of developer resources maintained by **Excesspool Limited Liability Company**:
+## Project Links
 
 * **`@ramme-io/ui`**: The core library of visual primitives.
-* **`@ramme-io/create-app`** (This Repository): The CLI scaffolding tool.
+* **`@ramme-io/create-app`** (This Repository): The quick start kit.
 
 ---
 
 ## Contributing
 
-We welcome contributions from the community. Please fork the repository and submit a pull request. For major architectural changes, please open an issue first to discuss the proposed direction.
+We welcome contributions from the community. Just fork the repository and submit a pull request. For major changes, please open an issue first to discuss.
 
 ## License
 

package/dist/blocks/iot/DeviceCard.d.ts

@@ -0,0 +1,57 @@
+import { default as React } from 'react';
+import { IconName } from '../../components/ui/Icon';
+
+declare const statusColorMap: {
+    readonly online: "success";
+    readonly offline: "secondary";
+    readonly error: "danger";
+    readonly warning: "outline";
+    readonly active: "primary";
+};
+export type DeviceStatus = keyof typeof statusColorMap;
+/**
+ * @wizard
+ * @name DeviceCard
+ * @description A specialized card designed to represent a physical device or a digital entity with live state. Features slots for status, live values, and interactive controls.
+ * @tags layout, iot, device, card, dashboard
+ * @category layout
+ * @props
+ * - name: title
+ * type: string
+ * description: The name of the device or entity (e.g., "Living Room Thermostat").
+ * - name: description
+ * type: string
+ * description: A subtitle, often used for location or ID (e.g., "Floor 2 • ID: #442").
+ * - name: icon
+ * type: IconName
+ * description: The icon representing the device type.
+ * - name: status
+ * type: 'online' | 'offline' | 'error' | 'warning' | 'active'
+ * description: The current operational state of the device. Changes the badge color.
+ * default: 'offline'
+ * - name: value
+ * type: string | number
+ * description: The primary "live" metric to display (e.g., "72°", "1,240 rpm").
+ * - name: trend
+ * type: string
+ * description: Optional secondary metric to show change (e.g., "+2%").
+ * - name: children
+ * type: React.ReactNode
+ * description: Interactive controls to place at the bottom of the card (e.g., a ToggleSwitch or Button).
+ * - name: className
+ * type: string
+ * description: Optional additional CSS classes.
+ */
+export interface DeviceCardProps {
+    title: string;
+    description?: string;
+    icon?: IconName;
+    status?: DeviceStatus;
+    value?: string | number;
+    trend?: string;
+    children?: React.ReactNode;
+    className?: string;
+    onClick?: () => void;
+}
+export declare const DeviceCard: React.FC<DeviceCardProps>;
+export {};

package/dist/{charts → components/data-display}/ChartWithTable.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { TableHeader } from '../data-display/Table';
+import { TableHeader } from './Table';
 
 export interface ChartWithTableProps {
     /** The title of the chart. */

package/dist/{charts → components/data-display}/LineChart.d.ts

@@ -13,5 +13,7 @@ export interface LineChartProps {
  * @wizard
  * @name LineChart
  * @description A theme-aware line chart component...
+ * @tags charts, data-visualization, rechart
+ * @category charts
  */
 export declare const LineChart: React.FC<LineChartProps>;

package/dist/{form → components/forms}/FormTemplate.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { MultiSelectOption } from '../form/MultiSelect';
+import { MultiSelectOption } from '../forms/MultiSelect';
 
 interface FormFieldBase {
     name: string;
@@ -65,5 +65,25 @@ export interface FormTemplateProps {
     className?: string;
     children?: React.ReactNode;
 }
+/**
+ * @wizard
+ * @name FormTemplate
+ * @description A data-driven form builder that renders a grid of input fields from a configuration array, handling internal state and submission.
+ * @category form
+ * @tags form, template, builder, input, layout
+ * @props
+ * - name: fields
+ * type: FormField[]
+ * description: An array of field definition objects (name, label, type, etc.) that determine the form structure.
+ * - name: onSubmit
+ * type: (formData: Record<string, any>) => void
+ * description: Callback function triggered when the form is submitted, receiving the collected data.
+ * - name: className
+ * type: string
+ * description: Optional additional CSS classes for the form container.
+ * - name: children
+ * type: React.ReactNode
+ * description: Content to render at the bottom of the form, typically used for action buttons like "Save" or "Cancel".
+ */
 export declare const FormTemplate: React.FC<FormTemplateProps>;
 export {};

package/dist/{form → components/forms}/Input.d.ts

@@ -13,8 +13,9 @@ export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>
 /**
  * @wizard
  * @name Input
- * @description A theme-aware text input component with support for labels, icons, helper text, and validation states.
+ * @description A theme-aware text input component with support for labels, icons, helper text, and validation states. Supports all standard HTML input attributes.
  * @tags form, input, ui, text
+ * @category form
  * @props
  * - name: label
  * type: string
@@ -40,7 +41,5 @@ export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>
  * - name: containerClassName
  * type: string
  * description: Optional additional CSS classes for the container.
- * - name: All other standard HTML input attributes are also supported.
- * @category form
  */
 export declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/{layout → components/layout}/Sidebar.d.ts

@@ -11,6 +11,7 @@ export declare const SidebarProvider: ({ children }: {
 }) => import("react/jsx-runtime").JSX.Element;
 /**
  * @wizard
+ * @name Sidebar
  * @description A collapsible, responsive sidebar component.
  * @props
  * @prop {React.ReactNode} children - The content of the sidebar.

package/dist/components/ui/Button.d.ts

@@ -0,0 +1,44 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+import { IconName } from './Icon';
+
+/** @wizard
+ * @name Button
+ * @description The primary interactive element. Supports polymorphism (rendering as a link) via the 'asChild' prop.
+ * @category Input
+ * @props
+ * - name: variant
+ * type: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger' | 'link'
+ * description: The visual style of the button.
+ * default: 'primary'
+ * - name: size
+ * type: 'sm' | 'md' | 'lg' | 'icon'
+ * description: The size of the button.
+ * default: 'md'
+ * - name: loading
+ * type: boolean
+ * description: If true, replaces content with a spinner.
+ * default: false
+ * - name: iconLeft
+ * type: IconName
+ * description: Optional icon to display before the text.
+ * - name: asChild
+ * type: boolean
+ * description: If true, delegates rendering to the child element (e.g. for Links).
+ * default: false
+ * - name: onClick
+ * type: () => void
+ * description: Callback fired when the button is clicked.
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "ghost" | "primary" | "danger" | "outline" | "secondary" | "accent" | null | undefined;
+    size?: "sm" | "md" | "lg" | "icon" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+    loading?: boolean;
+    iconLeft?: IconName;
+    iconRight?: IconName;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export { Button, buttonVariants };

package/dist/data/mockData.d.ts

@@ -1,7 +1,7 @@
 /**
  * @wizard
- * @name Mock Data Sets
- * @description Pre-defined datasets for prototyping tables, charts, and other data-driven components.
+ * @name mockChartData
+ * @description Pre-defined datasets for prototyping charts and other data-driven components.
  * @tags data, mock, example
  * @category data
  */
@@ -10,6 +10,13 @@ export declare const mockChartData: {
     uv: number;
     pv: number;
 }[];
+/**
+ * @wizard
+ * @name mockTableData
+ * @description Pre-defined datasets for prototyping tables and other data-driven components.
+ * @tags data, mock, example
+ * @category data
+ */
 export declare const mockTableData: {
     make: string;
     model: string;

package/dist/index.d.ts

@@ -1,59 +1,60 @@
 
-export type * from './types/wizard.d';
+export type * from './lib/types/wizard';
 export type { ThemeName } from './contexts/ThemeContext';
-export type { MultiSelectOption } from './form/MultiSelect';
+export type { MultiSelectOption } from './components/forms/MultiSelect';
 export type { ColDef, ColGroupDef, GridOptions, GridApi, ColumnApi, ValueFormatterParams, ValueGetterParams, ICellRendererParams, CellClickedEvent, RowSelectedEvent, IHeaderParams, } from 'ag-grid-community';
 export * from './data/mockData';
-export * from './charts/BarChart';
-export * from './charts/ChartWithTable';
-export * from './charts/LineChart';
-export * from './charts/PieChart';
+export * from './blocks/ai/Loader';
+export * from './blocks/ai/Actions';
+export * from './blocks/ai/PromptInput';
+export * from './blocks/ai/Message';
+export * from './blocks/ai/Conversation';
+export * from './blocks/ai/ChatFAB';
 export * from './contexts/ThemeContext';
-export * from './data-display/DataTable';
-export * from './data-display/Table';
-export * from './feedback/Alert';
-export * from './feedback/EmptyState';
-export * from './feedback/TippyTooltip';
-export * from './feedback/Toast';
-export * from './feedback/ToastProvider';
-export * from './form/ButtonGroup';
-export * from './form/Checkbox';
-export * from './form/ComboBox';
-export * from './form/DatePicker';
-export * from './form/FileUpload';
-export * from './form/FormTemplate';
-export * from './form/Input';
-export * from './form/MultiSelect';
-export * from './form/Radio';
-export * from './form/SearchInput';
-export * from './form/Select';
-export * from './form/Textarea';
-export * from './form/ToggleSwitch';
-export * from './hooks/useDataFetch';
-export * from './layout/Accordion';
-export * from './layout/Card';
-export * from './layout/Drawer';
-export * from './layout/List';
-export * from './layout/Modal';
-export * from './layout/Sidebar';
-export * from './navigation/Breadcrumbs';
-export * from './navigation/Menu';
-export * from './navigation/Pagination';
-export * from './navigation/Stepper';
-export * from './navigation/Tabs';
-export * from './templates-patterns/ActionBar';
-export * from './templates-patterns/ActivityFeed';
-export * from './templates-patterns/PageHeader';
-export * from './templates-patterns/SectionHeader';
-export * from './templates-patterns/StatCard';
-export * from './ui/Avatar';
-export * from './ui/Badge';
-export * from './ui/Button';
-export * from './ui/ChatFAB';
-export * from './ui/Icon';
-export * from './ui/CodeBlock';
-export * from './ai/Loader';
-export * from './ai/Actions';
-export * from './ai/PromptInput';
-export * from './ai/Message';
-export * from './ai/Conversation';
+export * from './components/data-display/ActivityFeed';
+export * from './components/data-display/DataTable';
+export * from './components/data-display/Table';
+export * from './components/data-display/BarChart';
+export * from './components/data-display/ChartWithTable';
+export * from './components/data-display/LineChart';
+export * from './components/data-display/PieChart';
+export * from './components/data-display/CodeBlock';
+export * from './components/data-display/StatCard';
+export * from './components/feedback/Alert';
+export * from './components/feedback/EmptyState';
+export * from './components/feedback/TippyTooltip';
+export * from './components/feedback/Toast';
+export * from './components/feedback/ToastProvider';
+export * from './components/forms/ButtonGroup';
+export * from './components/forms/Checkbox';
+export * from './components/forms/ComboBox';
+export * from './components/forms/DatePicker';
+export * from './components/forms/FileUpload';
+export * from './components/forms/FormTemplate';
+export * from './components/forms/Input';
+export * from './components/forms/MultiSelect';
+export * from './components/forms/Radio';
+export * from './components/forms/SearchInput';
+export * from './components/forms/Select';
+export * from './components/forms/Textarea';
+export * from './components/forms/ToggleSwitch';
+export * from './lib/hooks/useDataFetch';
+export * from './blocks/iot/DeviceCard';
+export * from './components/layout/Accordion';
+export * from './components/layout/Card';
+export * from './components/layout/Drawer';
+export * from './components/layout/List';
+export * from './components/layout/Modal';
+export * from './components/layout/Sidebar';
+export * from './components/layout/ActionBar';
+export * from './components/layout/PageHeader';
+export * from './components/layout/SectionHeader';
+export * from './components/navigation/Breadcrumbs';
+export * from './components/navigation/Menu';
+export * from './components/navigation/Pagination';
+export * from './components/navigation/Stepper';
+export * from './components/navigation/Tabs';
+export * from './components/ui/Avatar';
+export * from './components/ui/Badge';
+export * from './components/ui/Button';
+export * from './components/ui/Icon';