DOCSEARCHbyAlgolia
Submit Docs

mydraft.cc Documentation

repository·master·Indexed 21 days ago

https://github.com/mydraft-cc/ui

An open-source wireframing tool providing a modern alternative to commercial software. This documentation covers local development, production builds, and Docker Compose setup. It includes detailed guides on extending the tool via the ShapePlugin interface for custom shapes, using the React-based UI layer (including ClipboardContainer and useClipboard hook), and interacting with the wireframe engine's Engine, EngineLayer, and Listener interfaces for rendering and event handling.

Tokens
9K
Snippets
28
Records
39
Agent score
74%

What's inside mydraft.cc

  1. Core concepts for custom shapes

    master

    When implementing a ShapePlugin, understand these five core concepts:

    • Appearance: A collection of properties (e.g., colors, text, states) that define how the shape looks.
    • Identifier: A unique string name for the shape type.
    • Configurables: A definition of how appearance values are displayed and edited in the UI sidebar (using a ConfigurableFactory).
    • Constraints: Logic that restricts size calculations (e.g., making height dependent on font size).
    • Default Size: The initial { x, y } dimensions applied when the shape is first added to a diagram.

  2. How to create new shapes

    master
    If you want to extend the wireframing capabilities by adding new shapes, refer to the specific documentation located at src/wireframes/shapes/README.md for implementation details and requirements.

  3. Steps to implement and register a new shape

    master

    Follow these steps to ensure your custom shape is correctly integrated:

    1. Create the class: Implement the ShapePlugin interface in a new class.
    2. Prepare the asset: Create a PNG image of your shape and name it {{identifier}}.png (replacing {{identifier}} with your shape's unique identifier).
    3. Register the shape: Add your new shape class to the index.ts file of the shapes module.
    4. Verify and update asset: Add the shape to a diagram, take a screenshot, and replace the initial {{identifier}}.png with this actual screenshot to ensure visual consistency.

  4. Build the mydraft.cc application for production

    master

    To create a production build, install dependencies and run the build script. The resulting static files will be located in the dist folder, which you can then copy to your web server.

    npm i
npm run build

  5. How to write a custom shape

    master

    To create a custom shape in mydraft.cc, you must implement the ShapePlugin interface and follow a specific asset and registration workflow. The shape's visual representation is handled by an imperative render method that uses a RenderContext to draw SVG elements. The system performs a diffing process to update, add, or destroy SVG elements whenever the shape's appearance changes.

    export class Toggle implements ShapePlugin {
    public identifier(): string {
        return 'Toggle';
    }

    public defaultAppearance() {
        return DEFAULT_APPEARANCE;
    }

    public defaultSize() {
        return { x: 60, y: 30 };
    }

    public configurables(factory: ConfigurableFactory) {
        return [
            factory.selection(STATE, 'State', [
                STATE_NORMAL,
                STATE_CHECKED,
            ]),
        ];
    }

    public render(ctx: RenderContext) {
        // Use ctx.renderer2 to draw shapes
        ctx.renderer2.rectangle(0, radius, ctx.rect, p => {
            p.setBackgroundColor(barColor);
        });
    }
}

  6. Run the mydraft.cc application locally

    master

    To run the application in a development environment, ensure you have Node.js installed, then use npm to install dependencies and start the development server. The application will be accessible at https://localhost:3002.

    npm i
npm start

  7. Set up the Clipboard system with ClipboardContainer

    master

    To enable clipboard functionality (copy, paste, cut) within your application, you must wrap your component tree with the ClipboardContainer. This component provides the necessary React context and sets up global document event listeners for paste, copy, and cut events, while ensuring standard HTML INPUT and TEXTAREA elements are ignored to prevent interfering with normal text editing.

    import { ClipboardContainer } from './src/core/react/Clipboard';

function App() {
  return (
    <ClipboardContainer>
      <YourApplicationComponents />
    </ClipboardContainer>
  );
}

  8. Run mydraft.cc using Docker Compose

    master

    You can run the mydraft.cc application using Docker Compose. The service is named mydraft. By default, the application maps port 8080 on your host machine to port 5173 inside the container.

    services:
  mydraft:
    build: .
    ports:
      - "8080:5173"

  9. Access the mydraft.cc wireframe engine interfaces

    master
    The src/wireframes/engine/index.ts file serves as the public entrypoint for the wireframe engine. It re-exports all types, interfaces, and core definitions from the ./interface module. Developers should use this entrypoint to import the necessary contracts and types required to interact with or extend the wireframe engine.

  10. Use the mydraft.cc wireframe model API

    master

    The src/wireframes/model/index.ts file serves as the primary entrypoint for the wireframe model. It exports the core logic for manipulating wireframe data through three main modules:

    • Actions: Functions and logic used to perform operations on the wireframe state.
    • Projections: Logic for deriving specific views or computed data from the underlying wireframe model.
    • Internal: Core model structures and internal logic (use with caution as these may be subject to change).

    To interact with the wireframe model, you should primarily use the exported actions to modify state and projections to read or transform state for the UI.

  11. Configure shape appearance with ShapeProperties

    master

    The ShapeProperties interface provides a fluent API to set the visual attributes of a shape element during rendering. Methods return ShapeProperties to allow chaining.

    Supported configuration methods:

    • setForegroundColor(color: RendererColor)
    • setBackgroundColor(color: RendererColor)
    • setStrokeColor(color: RendererColor)
    • setStrokeStyle(cap: string, join: string)
    • setFontSize(fontSize: RendererText | number)
    • setFontFamily(fontFamily: RendererText | string)
    • setOpacity(opacity: RendererOpacity)
    • setText(text: RendererText | string, markdown?: boolean)
    • setTextDecoration(decoration: TextDecoration)

  12. Manage EngineObject properties

    master

    All renderable elements (Rects, Ellipses, Lines, Text, Items) inherit from EngineObject. This interface provides common controls for visibility and interaction:

    • cursor(value: string | number): Sets the CSS cursor style (e.g., 'pointer') when hovering over the object.
    • remove(): Removes the object from its parent layer.
    • show(): Makes the object visible.
    • hide(): Hides the object.
    • disable(): Disables the object (typically affecting interaction/hit-testing).