daybrush/guides

A Guides component that can draw ruler and manage guidelines.

Guides

A Guides component that can draw ruler and manage guidelines.

Demo / API / Ruler / Main Project

⚙️ Installation

npm

$ npm i @scena/guides

scripts

<script src="//daybrush.com/guides/release/latest/dist/guides.min.js"></script>

🚀 How to use

import Guides from "@scena/guides";

const guides = new Guides(document.body, {
    type: "horizontal",
}).on("changeGuides", e => {
    console.log(e.guides);
});


let scrollX = 0;
let scrollY = 0;
window.addEventListener("resize", () => {
    guides.resize();
});

window.addEventListener("wheel", e => {
    scrollX += e.deltaX;
    scrollY += e.deltaY;

    guides.scrollGuides(scrollY);
    guides.scroll(scrollX);
});

Ruler Units

The default unit is px, and a line is drawn every 50px. If you want to use a different unit instead of the px unit, use it like this:

• 1px (Default)
  • zoom: 1
  • unit: 50 (every 50px)
• 1cm = 37.7952px
  • zoom: 37.7952
  • unit: 1 (every 1cm)
• 1in = 96px = 2.54cm
  • zoom: 96
  • unit: 1 (every 1in)

See:

• https://www.w3schools.com/cssref/css_units.asp
• https://www.scaler.com/topics/css/css-units/

⚙️ Developments

The guides repo is managed as a monorepo with yarn.

yarn config set registry https://registry.npmjs.org/

⭐️ Show Your Support

Please give a ⭐️ if this project helped you!

👏 Contributing

If you have any questions or requests or want to contribute to guides or other packages, please write the issue or give me a Pull Request freely.

🐞 Bug Report

If you find a bug, please report to us opening a new Issue on GitHub.

📝 License

This project is MIT licensed.

MIT License

Copyright (c) 2019 Daybrush

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

guides's Issues

Ability to see position without moving guides

Environments
Framework name: React
Framework version: 17.0.1
Component name: @scena/react-guides
Component version: 0.15.1
Testable Address(optional):

Description
Hey @daybrush, this is a really cool library. I had one small request. Is there a way that we can see the position of the guide while we are not moving it? Like when we drag the guide, we can see the position by adding this prop displayDragPos={true}. But it only works when I am moving the guide. Is there a option to always see the position of the guide irrespective of the fact that it's moving or not?

Thanks.

Use vue-guides component in Vue 2.x, loading report error Object(...) is not a function

Environments

• Framework name: Vue
• Framework version: 2.6.13
• Component name: vue-guides
• Component version: 0.16.0
• Testable Address(optional):

Description

Hi @daybrush ,
When i use vue-guides in vue template, the component report a error

the following is error message

Please add snapable for guides

Just like your library 'moveable'. If this package has snapable that snap to artboard objects when dragging, that will be helpful

Other metric units

Thanks for this great guides module.
I just wanted to know is it possible to have other metric units such as cm, mm...?

Feature: Set custom guide color and guideline style through a prop

Environments

• Framework name: react-guides

Description

In my app I needed to be able to dynamically set the guide color in the properties panel via a prop, allowing the user to choose the color on the fly. I also needed the guide line to be dashed instead of solid.

I have made some changes in my fork to allow for this and wanted to post an issue here to see if this is something the community might want me to PR.

I added a guideColor prop and can add a prop to allow selecting a dashed or solid line.

Uncaught TypeError: Cannot assign to read only property

Environments

• Framework name: react-guides 12.1.0

I first got this when saving a non cloned element to redux. We fixed it by cloning the guides array [...guides] before setting it to redux. Then I got this error with it happening on dragEnd and scratched my head. The only place setting a read only value could be inside the library in this case.

guides.esm.js:203 Uncaught TypeError: Cannot assign to read only property '2' of object '[object Array]'
    at Object.Guides._this.onDragEnd [as listener] (guides.esm.js:203)
    at event-emitter.esm.js:211
    at Array.forEach (<anonymous>)
    at Gesto.__proto.emit (event-emitter.esm.js:210)
    at HTMLBodyElement.Gesto._this.onDragEnd (gesto.esm.js:444)

I went through and changed all the references to this.state.guides to [...this.state.guides], recompiled, and no more read only error.

It's getting hung up on this line.

guides[index] = pos;

Where guides is read only and can't add pos, throwing the type error.

Wrong ruler display when zoom <<< 1

Hi @daybrush
When zoom <<< 1, the rulers are not display well. Please consider support it in next release!
Thanks,

Ability to put more precise values on guides

Environments

• Framework name: React
• Framework version: 17.0.1
• Component name: @scena/react-guides
• Component version: 0.15.1
• Testable Address(optional):

Description

Is it possible to customize the guides position values in order to have them more precise, with float numbers instead of only integers?

rulers should indicate the edge of the template at 0 and grow from there

Hi i am using Angular 8.0 to build a photo editing app. I am trying to use your rulers/guides component to show with my app for editing purpose.

1. I need the rulers in such a way that the edge of the template starts at 0 and and grows from there . i am attaching what i see in Illustrator for reference. Can you please let me know how i can do this

Can you please explain to me in code how i can use other units like inches and centimetres for my rulers?

I am using your guides component in my angular app used for editing text and images
I am trying ti change the units to Inches from the default pixels. The below code shows it in pixels
I tried changing unit=1 which did not work for me. Can you please explain in code , how i can make this work for inches. thank you
<ngx-guides #guides1 type="horizontal" unit="50" displayDragPos="true">

This app doesn't compile for me.

Environments

• Framework name:
• Framework version:
• Component name:
• Component version:
• Testable Address(optional):

Description

textOffset is not working in guide.

Environments

• Framework name: React
• Framework version: latest
• Component name: guides
• Component version: 15.1
• Testable Address(optional):

Description

Hello.

I want to change guide's text offset. I used it like this,
"guide textOffset={[0,7]}"
but it isn't working.

So I tested textOffset in ruler(7.1).
"ruler textOffset={[0,7]} "
It's working well.

How can I use 'textOffset' prop in guide?

Graduation lines thickness on vertical ruler

Environments

• Framework name: Vanilla
• Framework version: Vanilla
• Component name: Guides
• Component version: Latest Vanilla version
• Testable Address(optional): issu shows on your demo website

Description

Hi ! I've started using your components a few days ago since they're pretty much perfect for what I need to do right now. I just noticed something weird with the rulers generated by your Guides component. Seems like graduation lines/marks don't have the same thickness on the horizontal ruler than on the vertical one. I saw the same thing on your Guides demo website. Do you have a workaround for this ?

Thanks for your work !

how to set guidePos offset

Environments

• Framework name: vue3
• Framework version: vue3
• Component name: guides
• Component version: 0.18.2
• Testable Address(optional):

Description

vGuides = new Guides(document.getElementById("designer-ruler-vertical"), {
    type: "vertical",
    zoom: 0.342,
    longLineSize: 7,
    shortLineSize: 4,
    textOffset: [8, 0],
    displayDragPos: true,
    displayGuidePos: true,
    rulerStyle: { top: "40px", height: "calc(100% - 40px)", width: "100%" }
  });

when I set zoom the guild pos not correct,how I set the pos offset?

It seems like the latest version is 0.12.1, But It isn't published to npm repo

Environments

• Framework name: Vue
• Framework version: 2.0
• Component name: vue-guides
• Component version: : 0.12.1
• Testable Address(optional):

Description

Thanks for your hard work!
I was trying to update from 0.10.3 to the latest to use the new feature. It seems like the latest version is 0.12.1, But It isn't published to npm repo. Repo. has the 0.11.1 version

Could you check the latest version? 0.11.1 has an error of dependency missing.

The changeGuides event does not trigger

• component name: ngx-guides

• component version: 0.17.1
  issue：The changeGuides event does not trigger!!!

  ` <ngx-guides
  #horizontalGuides
  type="horizontal"
  class="guides horizontal"
  [snaps]="horizontalSnapGuides"
  [snapThreshold]="5"
  [displayDragPos]="true"
  [zoom]="eds.scale_val / 100"
  [unit]="50"
  (changeGuides)="onChangeGuides($event)"

  `

  onChangeGuides(e) { alert(1); console.log(e.guides); }

Ability to get a guide on click on the ruler

Environments
Framework name: React
Framework version: 17.0.1
Component name: @scena/react-guides
Component version: 0.15.1
Testable Address(optional):

Description
Hey @daybrush , Can we have the ability to click on a particular pixel on a ruler and a guideline appears at that position along the direction of the other ruler? Like, currently if we want a guide, we have to drag the guide from the starting to the whole way down. Instead, we can give an optional option that suppose if you click on the horizontal ruler at 100px (or any other unit), a vertical guide appears at 100px which then can be draggable like any other normal guide?
If this is an existing feature, can you tell me how to enable it, if not can I work on it?

Thanks.

Vue: Module not found

Environments

• Framework name: Vue
• Framework version: 2.x

Description

I installed vue-guides via npm. Then I included it like in the description.
However, it does not compile, I always get:
Module not found: Error: Can't resolve 'vue-guides'

Workaround: If I go into the directory node_modules/vue-guides and build the project, then it works.

Reactive properties in svelte

Environments

• Framework name: svelte
• Framework version: 3.49.0
• Component name: Guides
• Component version: latest
• Testable Address(optional): https://svelte.dev/repl/fcb3ca74d65e44f4b98d5772394d5c21?version=3.49.0

Description

Is there a way to make properties like zoom and unit reactive? I would like to have it so that when a user zooms in, the guides scale accordingly. Couldn't find an API for updating the properties after initialiasation.

Many thanks.

If the background is white and the font color is black, the text is a little blurry

Environments

• Framework name:
• Framework version:
• Component name:
• Component version:
• Testable Address(optional):

Description

Guides option set width/height not work, can not custom guides size

Environments

• Framework name:
• Framework version:
• Component name:
• Component version:
• Testable Address(optional):

Description

Hi @daybrush, i find guides option set width/height not work, i can't set my custom guides size

When the zoom changes, the guide show the wrong position

Environments

• Framework name:
• Framework version:
• Component name:
• Component version:
• Testable Address(optional):

Description

When I changed zoom, I found that my guides were out of position

Guides do not follow mouse position when container is scaled

Environments

• Framework name: none
• Framework version: none
• Component name: demo
• Component version: https://daybrush.com/moveable/

Description

I've noticed that whenever the container is scaled (i.e. zoom != 1), the guides do not move along with the position of the mouse:

I've seen this issue in the demo page for the moveable project and I assumed it has to do with the guides component.

Thank you and awesome work!!

I am having trouble using this component

I am looking for a component that can be used with angular project
which one should i use between these two. i am confused there are two of these.
are both these projects updated regularly and can be used
https://www.npmjs.com/package/ngx-guides
https://www.npmjs.com/package/@scena/guides

Snapping Issue When Using Custom Units

I need to render my rulers using inches as the unit, rather than pixels. So I supply the following two props to the Guides component:

unit={1}
zoom={zoomValue * 72} // 72 px/in

where zoomValue is a decimal representing how far the user has zoomed in/out of the canvas.

The base rendering and scrolling of the rulers is working great. Here is what my 8.5x11 document looks like on the canvas:

However, the guides cannot be placed in the correct position by the user for 2 reasons:

1. On initial placement, the guides will "snap" to the nearest integer unit, which in my case, is to the nearest inch. Here I have demonstrated this below:

   

2. You can eventually finagle the guide to a non-integer unit, however once the user zooms in/out (changes the zoomValue), the guides will snap again to the nearest integer (which again, in my case, is to the nearest inch). Demonstration below:

   

I have tried using the snapThreshold prop to try to make the snap threshold more granular or to even turn the snapping off altogether, but it doesn't seem to respect values less than 1.

Furthermore, when trying to display drag position via the dragPosFormat function, the value supplied into this function is a also a whole number, so if my guide is placed between 0-0.5 inches, it will tell me the drag position is 0, and if the guide is between 0.5-1.5 inches it will tell me the drag position is 1. We need more granularity in these values.

Seems like in general, we just need to allow this library to support more granular values for all the props / functionality to enable usage with custom units.

This issue may be related to #26.

Feature: Dragging new guide when guides are locked unlocks the guides

Environments

• Framework name: react-guides 13
• Framework version: guides 14

Description

The new guides prop worked well for me with a boolean value, but using the string values in an array didn't cause any changes. Maybe what I'm trying to accomplish here would be best accomplished with those string values?

• I'm trying to figure out how to set it up so if the guides are locked, dragging a new guide unlocks the guides. The way it's currently implemented if the guides are locked, none of the events fire, so this onDragStart function never runs.

I already setup something similar using onDragStart to show guides if they are off when dragging a new guide.

export const onDragStart = ({ lockGuides, showGuides }: OnDragStartPayload) => {
  return (e: OnDragStart) => {
    console.debug('onDragStart', e);
    if (!showGuides) toggleGuides(true); // works
    if (lockGuides) toggleLockGuides(false); // does not
  };
};

• Looking at my logs it looks like the onDragStart would fire when changing an existing element as well as a new element from the ruler.

Is there a way to treat new guides differently than existing guides?

Describe specific value infromation

Theguides is coooool and very useful!
I have a small wish. I want to change the unit of the rule, but I don't know which props to change.
Would you describe the props more specific please?

export interface GuidesProps {
    type?: "horizontal" | "vertical";
    width?: number;
    height?: number;
    unit?: number;   <-- maybe this?
    zoom?: number;
    style?: IObject<any>;
    backgroundColor?: string;
    lineColor?: string;
    setGuides?: (guides: number[]) => any;
    rulerStyle?: IObject<any>;
}

Thank you!

Feature: lockGuides prop for locking changes

Environments

• Framework name: react-guides

Description

using e.stop() is still letting click events change state when hovering over a guide.

Just like how there is a showGuides prop for toggling guides, it would be great if there were a lockGuides prop for toggling locking the guides.

Will be adding to my fork in the future.

Question：Drag guideline position offset 10px with ruler tick label

Environments

• Framework name: Vue
• Framework version: 2.6.13
• Component name: @scena/guides
• Component version: 0.17.0
• Testable Address(optional):

Description

Hi @daybrush, i just find drag guideline from ruler appera 10px offset with ruler tick label,
This is my guide component config

This is effect

Multiple lines in different colors?

Hello is it possible to draw multiple Guide-Lines in different colors? Like, the first line red, the second blue and the third yellow?

Greetings

how to remove a guide line by double click it

Environments

• Framework name: Vue
• Framework version: 2.x
• Component name:

Description

how to remove a guide line by double click it

Locking the guides

@daybrush - loving Moveable, Selecto and Guides!

How can I lock the guides so they don't scroll?

The distribution directory `dist` is missing in the released package for `vue-guides`.

Environments

• Framework name: @scena/guides
• Framework version: 0.6.0
• Component name: vue-guides
• Component version: 0.5.0
• Testable Address(optional):

Description

The distribution directory dist is missing in the released package for vue-guides.

When will it be supported in vue3

When I inherited vue-guides in the project, I found that it does not work properly

`TextFormat` not working

Environments

• Framework name: React
• Framework version: latest
• Component name: guides
• Component version: 0.9.0
• Testable Address(optional):

Description

The textFormat prop is not passed to the internal Ruler. It's missing in the source.

As a result, the following does not work:

<Guides textFormat={scale => `${scale + 10}`>...</Guides>

Cheers, Adam.

Scale the ruler

Description

Hi @daybrush!
When I scale the ruler, I get the wrong behavior when I click on the guide. Could you please advise how can I fix this?

Thanks!
screen.mov.zip

onChangeGuides not firing on delete or change

Environments

• Framework name: "react": "^16.13.1",
• Component name: "@scena/react-guides": "^0.6.1",
• Testable Address(optional):

Description

The event onChangeGuides doesn't fire when I delete or move/change a guide.

<Guides
 type="vertical"
                    zoom={zoom}
                    unit={unit}
                    style={{height: 'calc(297mm * ${pageAmount} + 30px'}}
                    rulerStyle={{ top: "30px", height: 'calc(297mm * ${pageAmount}', width: "100%" }}
                    displayDragPos={true}
                    onChangeGuides={({ guides }) => {
                        console.log(guides)
                        setVerticalGuidelines(guides)
                    }}
                />
</div>

set line style and ruler text line-height

Environments

• Framework name:react-guides

Description

How to set line style and ruler text line-height.
When the page scrolls, the ruler style is floating. At this point, I want this line to scroll with the page。the style is absolute ，not translateY，translateX.
the ruler text margin top is 0px ，I want to center it vertically

Remove all guides

Environments

• Framework:
  ReactJS (16.13.0)

Description

Hi @daybrush!
Thx a lot for your guides component!
But I have one question:
how to remove all guides after clicking on some element, e.g.:
https://prnt.sc/tlssem

Can we get the distance between each individual line?

Environments

• Framework name: React
• Framework version: 17.0.1
• Component name: @scena/react-guides
• Component version: 0.15.1
• Testable Address(optional):

Description

Is there a way to like press a shortcut and get the distance between each gridlines and also separate the area under each section? Something like this?

Please add digital display

Can this show the location number of the guide in the way shown in the screenshot
Can the drag process also real-time display guide location number

Please add a parameter to turn off auxiliary drag

Can you provide parameters to control the drag range, or turn off the drag function.

textColor Setting the font color has no effect

Style Property: Vue Warning

Environments

• Framework name: Vue
• Framework version: 2.x

Description

Vue does not allow to use style as a property and triggers a warning in the console:
[Vue warn]: "style" is a reserved attribute and cannot be used as component prop.

The problem is the 'style' property in PROPERTIES (https://github.com/daybrush/guides/blob/master/src/consts.ts), which Vue does not like.

Horizontal Guide Not Rendering Properly

Environments

• Framework name: react
• Framework version: 17.0.2
• Component name: @scena/react-guides
• Component version: 0.16.0

Description

After upgrading from @scena/react-guides version 0.14.0 --> 0.16.0, my horizontal ruler stopped rendering/loading properly:

When I manually trigger topRulerEl.current.resize();, the horizontal ruler then renders properly and is interactive again:

How can I control guides 0 position?

Environments

• Framework name: React
• Framework version: 17.0.1
• Component name: @scena/react-guides
• Component version: 0.12.0
• Testable Address(optional): Using Demo code

Description

Hello.
I want to use these module in my project. so I tested Guides Demo code(guides/packages/react-guides/src/demo/App.tsx ).
so I changed width & height 30px to 20px. but I couldn't control guides 0 position.
Guide's 0 point was still under 10px. I try to find interface, but I'm failed.

If you change 30px to 20px in demo code. you understand what I said.

How can I change guide 0 position?

using other measurement unit

I wish to use cm instead of px and i found it quite hard to figure out how to solve it. could you help me?

here is my relevant InfiniteViewer + Guides

    const horizontalGuides = new Guides($("#horizontal"), {
      unit: 'cm', ??? // don't work
      snaps: [0, ???],
    }).on("changeGuides", ({ guides }) => {
      moveable.horizontalGuidelines = guides
    });
    const verticalGuides = new Guides($("#vertical"), {
      type: "vertical",
      unit: 'cm', ??? // don't work
      snaps: [0, ???],
    }).on("changeGuides", ({ guides }) => {
      moveable.verticalGuidelines = guides
    });

    const viewer = new InfiniteViewer(
      viewer,
      viewport,
      {}
    )
    .on('scroll', evt => {
      horizontalGuides.scroll(evt.scrollLeft)
      horizontalGuides.scrollGuides(evt.scrollTop)
      verticalGuides.scroll(evt.scrollTop)
      verticalGuides.scrollGuides(evt.scrollLeft)
    })

my viewport is:

    #viewport {
      width: 8.56cm;
      height: 5.398cm;
    }

if it helps here is the result of viewport.getClientRect of the div
height: 204.015625 === 5.398cm
width: 323.515625 === 8.56cm
my dpi is 96 if that is to any use.

is there some formel to tweak the zoom or anything like that?
or some method to change the guides to use another unit other then px?

Feature: While dragging a new guide, snap guide to moveable elements

Environments

• Framework name: react-guides

Description

In the app I'm writing the guides need to snap to elements just as the elements need to snap to guides. I have been reading the react-guides chunk of the library and would like to write this.

It seems like react-guides would need a new prop, an array with the x or y coordinates of all the edges of moveable objects. If guide comes within snapToElementThreshold pixels from a snap point, snap the guide to that point.

Any suggestions for how to contribute to the repo? I have a fork at the moment, but I think the features I need to add would help everybody.

I need an example of scaling，zoom? and unit？

Environments

• Framework name:
• Framework version:
• Component name:
• Component version:
• Testable Address(optional):

Description

Load/set Guides

Please add possibility to load/set guides from code.