{"id":17968760,"url":"https://github.com/williamngan/react-pts-canvas","last_synced_at":"2025-03-25T10:32:38.220Z","repository":{"id":34029620,"uuid":"165025149","full_name":"williamngan/react-pts-canvas","owner":"williamngan","description":"Pts Canvas React Component","archived":false,"fork":false,"pushed_at":"2024-05-04T01:14:17.000Z","size":9283,"stargazers_count":30,"open_issues_count":21,"forks_count":14,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-20T01:11:20.706Z","etag":null,"topics":["canvas","pts","react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/williamngan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-10T08:54:05.000Z","updated_at":"2024-08-31T19:10:10.000Z","dependencies_parsed_at":"2024-05-04T02:25:42.687Z","dependency_job_id":null,"html_url":"https://github.com/williamngan/react-pts-canvas","commit_stats":{"total_commits":94,"total_committers":8,"mean_commits":11.75,"dds":"0.44680851063829785","last_synced_commit":"2f07cdf62828b7f76b34a535bef73a8c5fd5c977"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Freact-pts-canvas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Freact-pts-canvas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Freact-pts-canvas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Freact-pts-canvas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamngan","download_url":"https://codeload.github.com/williamngan/react-pts-canvas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245444466,"owners_count":20616384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["canvas","pts","react"],"created_at":"2024-10-29T14:41:31.166Z","updated_at":"2025-03-25T10:32:37.237Z","avatar_url":"https://github.com/williamngan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-pts-canvas\n\n[![NPM](https://img.shields.io/npm/v/react-pts-canvas.svg)](https://www.npmjs.com/package/react-pts-canvas)\n\n![cover](./cover.png)\n\n`react-pts-canvas` includes React components for canvas drawing using [Pts](https://ptsjs.org). You can also check out some usage examples in the `src` folder here, and more in [`react-pts-canvas-examples`](https://williamngan.github.io/react-pts-canvas-examples/build/) repo.\n\n\u003e ### Breaking changes in v0.4\n\u003e\n\u003e 1. `onReady: (space, form, bound) =\u003e void` replaces the old handler `onStart: (bound, space, form) =\u003e void`\n\u003e\n\u003e 2. Legacy class based component are removed. Please use the 0.3.x version if you still need the class component\n\n[Pts](https://ptsjs.org) is a javascript library for visualization and creative-coding. You may use Pts by itself, or with React and other frameworks.\n\nIf you are getting started with Pts, take a look at the [demos](https://ptsjs.org/demo) and read the [guides](https://ptsjs.org/guide).\n\n## Install\n\n```bash\nnpm install --save react-pts-canvas\n```\n\n## Examples\n\n- See examples in [react-pts-canvas-examples](https://github.com/williamngan/react-pts-canvas-examples) repo\n- The [src](./src) folder in this repo also provides some quick examples\n\n## PtsCanvas functional component\n\n`PtsCanvas` is a functional component that helps you get started on Pts in React. A quick example as follows (please refer to [this guide](https://ptsjs.org/guide/space-0500) to learn more about these functions).\n\n`PtsCanvas`\n\n```jsx\n/* App.js */\n\u003cPtsCanvas\n  name='myClassName'\n  onReady={ (space, form, bound) =\u003e {...} }\n  onAnimate={ (space, form, time, ftime) =\u003e {...} }\n  onResize={ (space, form, size, evt) =\u003e {...} }\n  onAction={ (space, form, type, px, py, evt) =\u003e {...} }\n/\u003e\n```\n\n```css\n/* App.css */\n.myClassName {\n  position: absolute;\n  top: 0;\n  left: 0;\n  right: 0;\n  bottom: 0;\n}\n```\n\n`PtsCanvas` component makes use of the `useEffect` hook to handle lifecycle events, and the `useRef` hook to maintain reference to the space, form, and canvas elements. It provides the following props:\n\n- `name`\n  - The css class name of the container `\u003cdiv\u003e`. Default value is \"pts-react\". Use this class name to set custom styles in your .css file.\n- `className`\n  - Additional class names to be appended\n- `background`\n  - background fill color of the canvas. Default value is \"#9ab\".\n- `onReady`\n  - onReady handler function\n- `onAnimate`\n  - onAnimate handler function\n- `onResize`\n  - onResize handler function\n- `onAction`\n  - onAction handler function\n- `play`\n  - A boolean value to set whether the canvas should animate. Default is `true`.\n- `resize`\n  - A boolean value to indicate whether the canvas should auto resize. Default is `true`.\n- `retina`\n  - A boolean value to indicate whether the canvas should support retina resolution. Default is `true`.\n- `touch`\n  - A boolean value to set whether the canvas should track mouse and touch events. Default is `true`.\n- `style`\n  - Optionally override css styles of the container `\u003cdiv\u003e`.\n- `canvasStyle`\n  - Optionally override css styles of the `\u003ccanvas\u003e` itself. Avoid using this except for special use cases.\n- `tempo`\n  - a `Tempo` object. In a parent component, you can create a ref to a tempo object, add functions to it via `Tempo.every` in your onReady handler, then pass that `Tempo`'s ref.current as this prop. The `tempo` will be added to the space with the other handlers.\n- `spaceRef`\n  - a ref returned from `useRef(null)` if you need reference to the space in your parent component\n- `formRef`\n  - a ref returned from `useRef(null)` if you need reference to the form in your parent component\n\n### Canvas ref access\n\n`PtsCanvas` is wrapped with `forwardRef`, so you can pass a ref to the component itself if you need\naccess to the canvas ref within your parent component:\n\n```jsx\nimport React, {createRef} from 'react'\n\nconst ParentComponent = () =\u003e {\n  const ref = createRef\u003cHTMLCanvasElement\u003e()\n\n  return (\n    \u003cPtsCanvas\n      ref={ref}\n      onAnimate={() =\u003e {...}}\n    \u003e\n  )\n}\n```\n\nSee [`example/src/App-ParentRef.tsx`](./example/src/App-ParentRef.tsx)\n\n### Common issues\n\n- If you are getting sourcemap warnings, create a file called '.env' in your project folder and add `GENERATE_SOURCEMAP=false` into it.\n\n## Develop\n\nIn v0.4+, we use a Vite template to create this library. Here are the steps to start the dev environment\n\n```bash\n# Install pnpm global if you don't have it already\nnpm install -g pnpm\n\n# Install dependencies\npnpm i\n\n# Develop\npnpm run dev\n\n```\n\n#\n\n## Legacy Components\n\nNote that these old class components are removed in v0.4. If you still need it, please use v0.3.x packages.\n\n### QuickStartCanvasLegacy class component\n\n`\u003cQuickStartCanvasLegacy\u003e` helps you get started quickly. Here is a minimal example that draws a point the follows the cursor, by passing a callback function to `onAnimate` property:\n\n```jsx\nimport React from 'react';\nimport { QuickStartCanvasLegacy } from 'react-pts-canvas';\n\n// ...\n\u003cQuickStartCanvasLegacy\n  onAnimate={(space, form, time) =\u003e form.point(space.pointer, 10)}\n/\u003e;\n// ...\n```\n\nIn addition to the props in `PtsCanvas` (see below), `QuickStartCanvas` provides 4 callback props that correspond to the [player functions](https://ptsjs.org/guide/space-0500) in Pts. The `space` and `form` instances are also passed as parameters.\n\n```jsx\n\u003cQuickStartCanvasLegacy\nonStart={ (bound, space) =\u003e {...} }\nonAnimate={ (space, form, time, ftime) =\u003e {...} }\nonResize={ (space, form, size, evt) =\u003e {...} }\nonAction={ (space, form, type, px, py, evt) =\u003e {...} }\n/\u003e\n```\n\n### PtsCanvasLegacy class component\n\n`PtsCanvasLegacy` is a class component that you may extend to implement your own drawings and animations on canvas using Pts. Like this:\n\n```jsx\nclass MyCanvas extends PtsCanvasLegacy {\n\n  animate (time, ftime, space) {\n    // your code for drawing and animation\n  }\n\n  start (bound, space) {\n    // Optional code for canvas init\n  }\n\n  action: (type, x, y, event) {\n    // Optional code for interaction\n  }\n\n  resize (size, event) {\n    // Optional code for resize\n  }\n}\n```\n\nThere are 4 functions in Pts that you can (optionally) overrides: `animate`, `start`, `resize`, and `action`. [See this guide](https://ptsjs.org/guide/space-0500) to learn more about how these functions work.\n\nOnce you have implemented your own canvas, you can use it as a component like this:\n\n```jsx\nimport React from 'react';\nimport { PtsCanvas } from 'react-pts-canvas';\n\nclass Example extends React.Component {\n  render() {\n    return \u003cMyCanvas background=\"#abc\" play={true} /\u003e;\n  }\n}\n```\n\n`PtsCanvasLegacy` component provides the following props:\n\n- `name`\n  - The css class name of the container `\u003cdiv\u003e`. Default value is \"pts-react\". Use this class name to set custom styles in your .css file.\n- `background`\n  - background fill color of the canvas. Default value is \"#9ab\".\n- `resize`\n  - A boolean value to indicate whether the canvas should auto resize. Default is `true`.\n- `retina`\n  - A boolean value to indicate whether the canvas should support retina resolution. Default is `true`.\n- `play`\n  - A boolean value to set whether the canvas should animate. Default is `true`.\n- `touch`\n  - A boolean value to set whether the canvas should track mouse and touch events. Default is `true`.\n- `style`\n  - Optionally override css styles of the container `\u003cdiv\u003e`.\n- `canvasStyle`\n  - Optionally override css styles of the `\u003ccanvas\u003e` itself. Avoid using this except for special use cases.\n\n## License\n\nApache License 2.0. See LICENSE file for details.\nCopyright © 2017-current by [William Ngan](https://williamngan.com) and contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamngan%2Freact-pts-canvas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamngan%2Freact-pts-canvas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamngan%2Freact-pts-canvas/lists"}