# @carnelian-diagram/shapes

> Shape collection for Carnelian Diagram library

Latest version **0.4.1** (published 2023-09-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @carnelian-diagram/shapes
pnpm add @carnelian-diagram/shapes
yarn add @carnelian-diagram/shapes
bun add @carnelian-diagram/shapes
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.1 |
| Published | 2023-09-01 |
| First published | 2023-05-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 175.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 22 |
| Author | Yuri Spektor |
| Maintainers | yspektor |
| Keywords | diagram, interactive, typescript, react, svg, vector graphics, drawing, visualization, shapes |

## Links

- npm: https://www.npmjs.com/package/@carnelian-diagram/shapes
- Repository: https://github.com/YMSpektor/carnelian-diagram
- Issues: https://github.com/YMSpektor/carnelian-diagram/issues
- npm.io page: https://npm.io/package/@carnelian-diagram/shapes

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.4.1 (latest) — 2023-09-01
- 0.4.0 — 2023-08-25
- 0.3.0 — 2023-08-22
- 0.2.2 — 2023-08-14
- 0.2.1 — 2023-06-12
- 0.2.0 — 2023-05-30
- 0.1.0 — 2023-05-12

## README

# Carnelian Diagram
**Carnelian Diagram** is a typescript library that allows you to create interactive diagrams for your web applications.

## Motivation
The library aims to achieve several goals. First and foremost, it is not just a collection of pre-built tools and features, but also an engine that enables you to create your own.

Secondly, **Carnelian Diagram** is designed to have similarities with the popular React library. If you are already familiar with React, your skills will be transferrable to this library as well. You can develop custom interactive elements using similar concepts, such as functional components (using custom and standard hooks like useState and useEffect), JSX syntax, and higher-order components. This familiarity makes it easy to learn and integrate **Carnelian Diagram** into your projects.

However, it is important to note that **Carnelian Diagram** is not based on React and does not require its installation in your project. You can use the library with vanila TypeScript/JavaScript or alongside other tools. The library utilizes its own engine, similar to React but simpler and designed to meet specific needs.

## Installation

**Carnelian Diagram** is available as a set of several npm packages.

### @carnelian-diagram/core
This package is a core of **Carnelian Diagram** library and contains base functionality to create and render diagrams.

```sh
npm install @carnelian-diagram/core
```

### @carnelian-diagram/interactivity
This package contains tools to make a diagram and its elements respond to a user's input.

```sh
npm install @carnelian-diagram/interactivity
```

### @carnelian-diagram/shapes
This package containt some ready to use basic diagram elements and shapes: rectangle, ellipse, polygons, lines, text elements, etc.

```sh
npm install @carnelian-diagram/shapes
```

## Examples

### Example - Basic usage

```typescript
import { Diagram, DiagramDOM, DiagramRoot } from "@carnelian-diagram/core";
import { InteractionController, withInteractivity } from "@carnelian-diagram/interactivity";
import { 
    InteractiveRoundedRect as RoundedRect,
    InteractiveCircle as Circle 
} from "@carnelian-diagram/shapes/basic";

const root = document.getElementById("root");
if (root && root instanceof SVGGraphicsElement) {
    const diagram = new Diagram();
    diagram.add(RoundedRect, { x: 100, y: 100, width: 200, height: 150, radius: "25%", style: { fill: "yellow" } });
    diagram.add(Circle, { x: 280, y: 220, radius: 80, style: { fill: "blue" }});

    const controller = new InteractionController(diagram);
    const diagramDOM = DiagramDOM.createRoot(diagram, root, withInteractivity(DiagramRoot, controller));

    controller.attach(root);
    diagramDOM.attach();
}
```

### Example - Custom elements

Firstly, you need to configure JSX for typescript. Add the following lines to your tsconfig.json:
```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@carnelian-diagram/core"
  }
}
```
Instead of adding `jsxImportSource` to the tsconfig.json, you can define the typescript pragma at the beginning of your .tsx files. This can be useful when your project has already had some other JSX configuration (e.g. React projects) and you need to overwrite it for your custom diagram elements.

```typescript
/** @jsxImportSource @carnelian-diagram/core */

// The rest of the .tsx file
...
```

Here is the example for a simple interactive rectangle:
```typescript
/** @jsxImportSource @carnelian-diagram/core */

import { DiagramElement } from "@carnelian-diagram/core";
import { withInteractiveRect } from "@carnelian-diagram/interactivity";

export interface RectProps {
    x: number;
    y: number;
    width: number;
    height: number;
    style?: any;
}

export const Rect: DiagramElement<RectProps> = function(props) {
    const { x, y, width, height, style } = props;

    return (
        <rect x={x} y={y} width={width} height={height} style={style} />
    );
};

export const InteractiveRect = withInteractiveRect(Rect);
```

See [Examples folder](https://github.com/YMSpektor/carnelian-diagram/tree/main/examples) for more examples of using the library and [@carnelian-diagram/shapes](https://github.com/YMSpektor/carnelian-diagram/tree/main/packages/shapes/src/basic) package source for creating custom elements.

## Documentation

* [Carnelian Diagram core](https://github.com/YMSpektor/carnelian-diagram/blob/main/docs/core.md)
* [Interactivity](https://github.com/YMSpektor/carnelian-diagram/blob/main/docs/interactivity.md)
* [Tutorial: Creating custom interactive elements](https://github.com/YMSpektor/carnelian-diagram/blob/main/docs/custom-elements.md)

## Demo application

Demo application is available [here](https://ymspektor.github.io/carnelian-diagram).

## License

This project is licensed under the terms of the MIT license.

---
_Source: https://npm.io/package/@carnelian-diagram/shapes · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._