repository·master·Indexed 18 days ago
https://github.com/daybrush/guidesA Guides component for drawing rulers and managing guidelines. It provides a core library (@scena/guides) and framework-specific wrappers for React (@daybrush/react-guides), Angular (ngx-guides), Preact (@daybrush/preact-guides), and others. Key features include customizable ruler units (px, cm, in), snapping behavior, zoom control, and event-driven updates for guideline changes.
The default unit is px with a line drawn every 50px. To use different units (like cm or in), you must adjust the zoom and unit properties.
Examples:
zoom: 1, unit: 50 (every 50px)zoom: 37.7952, unit: 1 (every 1cm)zoom: 96, unit: 1 (every 1in)To use the Guides component in your project, install the @scena/guides package using npm.
$ npm i @scena/guidesYou can include the Guides component directly in your HTML using a script tag pointing to the latest distribution.
<script src="//daybrush.com/guides/release/latest/dist/guides.min.js"></script>Initialize the Guides component by passing a container element (e.g., document.body) and an options object. You can listen to the changeGuides event to react to guideline changes. To ensure the ruler stays aligned during window resizing or scrolling, call .resize(), .scroll(), or .scrollGuides() manually.
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);
});When instantiating Guides, you can pass a Partial<GuidesOptions> object.
Key option:
warpSelf: (boolean) If true, the guides will render directly into the provided container instead of creating a new div wrapper. If false (default), a new div is appended to the container.const guides = new Guides(container, {
warpSelf: true
});The GuidesOptions interface defines the configuration for the Guides component. It extends RulerProps and includes settings for snapping, styling, and display behavior.
className: CSS class name for the guides container. (Default: "")rulerStyle: CSS style object for the ruler. (Default: { width: '100%', height: '100%' })snapThreshold: The interval to snap to. (Default: 5)snaps: An array of specific positions to snap to. (Default: [])displayDragPos: Whether to show the moving position during dragging. (Default: false)guidesZoom: Zoom level for guides (side zoom). If not set, it defaults to the ruler's zoom. (Default: zoom)dragPosFormat: A function to format the drag position value. (Default: self)defaultGuides: Initial array of guideline positions. (Default: [])showGuides: Whether to render the guidelines. (Default: true)lockGuides: Prevents adding, changing, or removing guides via interaction. Can be true or an array of specific actions: "add" | "change" | "remove". (Default: false)digit: Number of decimal places for guidelines. (Default: 0)guideStyle: CSS style object for guide elements. (Default: "{}")displayGuidePos: Whether to show the guide position text. (Default: false)scrollOptions: Configuration for automatic scrolling via DragScrollOptions. (Default: null)guidesOffset: Numerical offset from the guideline position. (Default: 0)The Svelte guides package uses @daybrush/builder's buildHelper to generate multiple output formats (CJS and ESM) from a single configuration. The build process utilizes rollup-plugin-svelte with @pyoner/svelte-ts-preprocess for TypeScript support within Svelte components.
Key configuration details:
./src/index.js.svelte is marked as an external dependency.dist/guides.cjs.jsdist/guides.esm.jsimport buildHelper from "@daybrush/builder";
import svelte from 'rollup-plugin-svelte';
import { preprocess } from "@pyoner/svelte-ts-preprocess";
const defaultOptions = {
tsconfig: "",
input: './src/index.js',
commonjs: true,
external: {
"svelte": "svelte",
},
plugins: [
svelte({
preprocess: preprocess(),
}),
],
}
export default buildHelper([
{
...defaultOptions,
output: "dist/guides.cjs.js",
format: "cjs",
},
{
...defaultOptions,
output: "dist/guides.esm.js",
format: "es",
},
]);The forceUpdate method triggers a re-render of the guides instance, bypassing the standard state comparison. It accepts an optional callback function that executes after the update.
guides.forceUpdate(() => {
console.log("Guides re-rendered");
});@scena/react-guides/declaration/types. Use these exported types to ensure type safety when working with guide configurations and state in React environments.The core Guides class is the default export of the package. You can import it to manage and orchestrate guides within your application.
import Guides from "@daybrush/guides";The packages/vue3-guides package provides a Guides component that serves as the primary entry point for displaying guides within a Vue 3 application. You can import it as a default export.
import Guides from '@daybrush/guides/vue3';
// Use <Guides /> in your Vue templateThe @daybrush/preact-guides package provides a default export named Guides. You can import this component to integrate guides into your Preact application. It also re-exports type declarations from @scena/react-guides/declaration/types to ensure type safety when working with guide configurations and structures.
import Guides from "@daybrush/preact-guides";