diff --git a/Documentation/index.mdx b/Documentation/index.mdx index 98171019..0ed71cac 100644 --- a/Documentation/index.mdx +++ b/Documentation/index.mdx @@ -1,6 +1,6 @@ --- title: Components -description: The React component library for Cratis — command dialogs, forms, and data tables that consume Arc's generated proxies. +description: The React component library for CQRS and event-sourced applications with Cratis — command dialogs, typed forms, and query-backed data tables that consume Arc's generated proxies. --- import { CardGrid } from '@astrojs/starlight/components'; @@ -59,4 +59,18 @@ Command dialogs, forms, and data tables that consume [Arc's](/arc/) generated pr +## Related + + + + The CQRS application framework for ASP.NET Core that generates the proxies these components consume. + + + The event-sourcing database and runtime behind the read models your screens render. + + + Inspect and diagnose Chronicle — events, observers, projections, and read models — from the terminal. + + + Components renders [Arc's](/arc/) proxies over [Chronicle](/chronicle/) read models — see [Why developers choose Cratis](/why-cratis/) for the full stack. diff --git a/README.md b/README.md index f85d488a..0de56ed7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Cratis Components +React components for CQRS and event-sourced applications built with [Cratis Arc](https://github.com/Cratis/Arc) — command dialogs, typed forms, and query-backed data tables. + ## Packages [![NPM](https://img.shields.io/npm/v/@cratis/components?label=@cratis/components&logo=npm)](https://www.npmjs.com/package/@cratis/components) @@ -11,7 +13,59 @@ ## Description -A collection of React components designed to work seamlessly with the constructs found in the Arc universe. These components provide a rich set of UI elements for building modern applications, including command dialogs, data tables, schema editors, and more. +Cratis Components is a React component library aligned with the patterns of [Arc](https://github.com/Cratis/Arc), the Cratis CQRS application framework for ASP.NET Core. The components consume Arc's generated TypeScript proxies, so commands, queries, and read models flow fully typed from your backend into the UI — including event-sourced applications backed by [Chronicle](https://github.com/Cratis/Chronicle), the Cratis event-sourcing database and runtime. + +The library builds on PrimeReact and ships with flexible styling: use the Cratis baseline theme, PrimeReact's styled mode, your own palette, or go fully unstyled with a `pt` preset. + +`@cratis/components` itself is MIT licensed. Version 3.x builds on PrimeReact 11, which carries its own license terms — see the [licensing section in the package README](./Source/README.md#licensing) for details. + +## Install + +```bash +npm install @cratis/components primereact @primereact/core @primereact/headless @primereact/hooks primeicons +``` + +```tsx +import '@cratis/components/tokens'; +import '@cratis/components/styles'; +import { CratisComponentsProvider } from '@cratis/components'; +import { DataPage } from '@cratis/components/DataPage'; + +export const App = () => ( + + + +); +``` + +See the [package README](./Source/README.md) for peer dependencies, stylesheets, and styling setups, and the [getting started guide](https://www.cratis.io/components/getting-started/) for a full walkthrough. + +## What's in the box + +| Component | What it does | +|---|---| +| `CommandDialog` / `CommandStepper` | Instantiates, validates, and executes a generated Arc command — single-step or multi-step | +| `CommandForm` | Typed input fields bound to command properties — text, number, dropdown, date, and more | +| `DataPage` | A resizable page that lists query data with toolbar actions and detail panels | +| `DataTables` | Data-table wrappers that render an Arc query or observable query, with filtering and paging | +| `Dialogs` | Data-collection dialogs that return values without executing a command | +| `Chat` | Topic-based chat with host-supplied data, mentions, emoji, and per-message actions | +| `SchemaEditor` | Edit JSON schemas visually | +| `TimeMachine` | Navigate state over time — a natural fit for event-sourced read models | +| `PivotViewer` | Explore collections across multiple dimensions | +| `Notifications`, `Toolbar`, `Dropdown`, `Display`, … | Supporting building blocks — see the [full export list](./Source/README.md#available-subpath-exports) | + +## The Cratis ecosystem + +This project is part of [Cratis](https://www.cratis.io) — free, MIT-licensed tools for building event-sourced and CQRS applications. + +- **[Chronicle](https://github.com/Cratis/Chronicle)** — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. [Docs](https://www.cratis.io/chronicle/) +- **Chronicle clients** — first-class [.NET SDK](https://github.com/Cratis/Chronicle), plus [TypeScript](https://github.com/Cratis/Chronicle.TypeScript), [Kotlin/Java](https://github.com/Cratis/Chronicle.Kotlin), and [Elixir](https://github.com/Cratis/Chronicle.Elixir); [Python](https://github.com/Cratis/Chronicle.Python) coming soon (pre-alpha). AI agents connect through the [Chronicle MCP server](https://github.com/Cratis/Chronicle.Mcp). +- **[Arc](https://github.com/Cratis/Arc)** — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. [Docs](https://www.cratis.io/arc/) +- **Components** — this repository. [Docs](https://www.cratis.io/components/) +- **[CLI](https://github.com/Cratis/cli) + Workbench** — inspect and diagnose Chronicle from the terminal or the browser. [Docs](https://www.cratis.io/cli/) +- **Supporting** — [Fundamentals](https://github.com/Cratis/Fundamentals), [Specifications](https://github.com/Cratis/Specifications), [Synopsis](https://github.com/Cratis/Synopsis), [Lens](https://github.com/Cratis/Lens), [Narrator](https://github.com/Cratis/Narrator) +- **[Samples](https://github.com/Cratis/Samples)** — runnable event sourcing and CQRS samples for the whole stack ## Support diff --git a/Source/README.md b/Source/README.md index 50c4b07e..877eba6c 100644 --- a/Source/README.md +++ b/Source/README.md @@ -1,6 +1,6 @@ # Cratis Components -A collection of React components for building modern applications with Cratis. +React components for CQRS and event-sourced applications built with [Cratis Arc](https://github.com/Cratis/Arc) — command dialogs, typed forms, and query-backed data tables. The components consume Arc's generated TypeScript proxies, so commands, queries, and read models flow fully typed from your ASP.NET Core backend into the UI, including event-sourced applications backed by [Cratis Chronicle](https://github.com/Cratis/Chronicle). ## Requirements @@ -809,3 +809,13 @@ If using TypeScript 4.7+, try updating your `tsconfig.json`: ### Import Errors Ensure you're using the correct import paths. The package uses case-sensitive paths that match the actual component names. + +## Part of the Cratis ecosystem + +Cratis Components is part of [Cratis](https://www.cratis.io) — tools for building event-sourced and CQRS applications: + +- [Arc](https://github.com/Cratis/Arc) — the CQRS application framework for ASP.NET Core whose generated proxies these components consume +- [Chronicle](https://github.com/Cratis/Chronicle) — the event-sourcing database and runtime at the center of the stack +- [Fundamentals](https://github.com/Cratis/Fundamentals) — the shared .NET and TypeScript building blocks beneath the stack + +Read the docs at [cratis.io](https://www.cratis.io/components/) or join the community on [Discord](https://discord.gg/kt4AMpV8WV). diff --git a/Source/package.json b/Source/package.json index d41efb4e..8618a8d3 100644 --- a/Source/package.json +++ b/Source/package.json @@ -1,8 +1,24 @@ { "name": "@cratis/components", "version": "3.0.0", - "description": "", + "description": "React components for CQRS and event-sourced apps — command dialogs, typed forms, and query-backed data tables for Cratis Arc", + "keywords": [ + "react", + "react-components", + "component-library", + "cqrs", + "event-sourcing", + "cratis", + "arc", + "chronicle", + "commands", + "queries", + "data-table", + "forms", + "typescript" + ], "author": "Cratis", + "homepage": "https://www.cratis.io/components/", "license": "MIT", "repository": { "type": "git",