From 1357ab34eba86c77f1142d13ddf22648616e171f Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Mon, 2 Jun 2025 12:16:27 +0200 Subject: [PATCH] :books: Move library rework changes to its own changelog --- CHANGES.md | 64 +++------------------------------------------ library/CHANGES.md | 65 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 68 insertions(+), 61 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index c831cd20cc..1da1371879 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -6,67 +6,11 @@ ### :boom: Breaking changes & Deprecations -**Breaking changes on penpot library:** +**Penpot Library** -The library entrypoint API object has been changed. From now you start creating a new -build context, from where you can add multiple files and attach media. This change add the -ability to build more than one file at same time and export them in an unique .penpot -file. - -```js -const context = penpot.createBuildContext() - -context.addFile({name:"aa"}) -context.addPage({name:"aa"}) -context.closePage() -context.closeFile() - -;; barray is instance of Uint8Array -const barray = penpot.exportAsBytes(context); -``` - -The previous `file.export()` method has been removed and several alternatives are -added as first level functions on penpot library API entrypoint: - -- `exportAsBytes(BuildContext context) -> Promise` -- `exportAsBlob(BuildContext context) -> Promise` -- `exportStream(BuildContext context, WritableStream stream) -> Promise` - -The stream variant allows writting data as it is generated to the stream, without the need -to store the generated output entirelly in the memory. - -There are also relevant semantic changes in how components should be created: this -refactor removes all notions of the old components (v1). Since v2, the shapes that are -part of a component live on a page. So, from now on, to create a component, you should -first create a frame, then add shapes and/or groups to that frame, and then create a -component by declaring that frame as the component root. - -A non exhaustive list of changes: - -- Change the signature of the `addPage` method: it now accepts an object (as a single argument) where you can pass `id`, - `name`, and `background` props (instead of the previous positional arguments) -- Rename the `createRect` method to `addRect` -- Rename the `createCircle` method to `addCircle` -- Rename the `createPath` method to `addPath` -- Rename the `createText` method to `addText` -- Rename the `addArtboard` method to `addBoard` -- Rename `startComponent` to `addComponent` (to preserve the naming style) -- Rename `createComponentInstance` to `addComponentInstance` (to preserve the naming style) -- Remove `lookupShape` -- Remove `asMap` -- Remove `updateLibraryColor` (use `addLibraryColor` if you just need to replace a color) -- Remove `deleteLibraryColor` (this library is intended to build files) -- Remove `updateLibraryTypography` (use `addLibraryTypography` if you just need to replace a typography) -- Remove `deleteLibraryTypography` (this library is intended to build files) -- Remove `add/update/deleteLibraryMedia` (they are no longer supported by Penpot and have been replaced by components) -- Remove `deleteObject` (this library is intended to build files) -- Remove `updateObject` (this library is intended to build files) -- Remove `finishComponent` (it is no longer necessary; see below for more details on component creation changes) - -- Change the `getCurrentPageId` function to a read-only `currentPageId` property -- Add `currentFileId` read-only property -- Add `currentFrameId` read-only property -- Add `lastId` read-only property +The initial prototype is completly reworked for provide a more consistent API +and to have proper validation and params decoding. All the details can be found +on [its own changelog](library/CHANGES.md) ### :heart: Community contributions (Thank you!) diff --git a/library/CHANGES.md b/library/CHANGES.md index 6601125e39..fce8735a99 100644 --- a/library/CHANGES.md +++ b/library/CHANGES.md @@ -7,6 +7,7 @@ - Add sample-bool.js to the playground directory - Fix compatibility issue on file media with penpot 2.7.x + ## 1.0.1 - Make the library generate a .penpot file compatible with penpot 2.7.x @@ -15,5 +16,67 @@ ## 1.0.0 -- Initial release after big refactor (from the first MVP prototype) +The library entrypoint API object has been changed. From now you start creating a new +build context, from where you can add multiple files and attach media. This change add the +ability to build more than one file at same time and export them in an unique .penpot +file. +```js +const context = penpot.createBuildContext() + +context.addFile({name:"aa"}) +context.addPage({name:"aa"}) +context.closePage() +context.closeFile() + +;; barray is instance of Uint8Array +const barray = penpot.exportAsBytes(context); +``` + +The previous `file.export()` method has been removed and several alternatives are +added as first level functions on penpot library API entrypoint: + +- `exportAsBytes(BuildContext context) -> Promise` +- `exportAsBlob(BuildContext context) -> Promise` +- `exportStream(BuildContext context, WritableStream stream) -> Promise` + +The stream variant allows writting data as it is generated to the stream, without the need +to store the generated output entirelly in the memory. + +There are also relevant semantic changes in how components should be created: this +refactor removes all notions of the old components (v1). Since v2, the shapes that are +part of a component live on a page. So, from now on, to create a component, you should +first create a frame, then add shapes and/or groups to that frame, and then create a +component by declaring that frame as the component root. + +A non exhaustive list of changes: + +- Change the signature of the `addPage` method: it now accepts an object (as a single argument) where you can pass `id`, + `name`, and `background` props (instead of the previous positional arguments) +- Rename the `createRect` method to `addRect` +- Rename the `createCircle` method to `addCircle` +- Rename the `createPath` method to `addPath` +- Rename the `createText` method to `addText` +- Rename the `addArtboard` method to `addBoard` +- Rename `startComponent` to `addComponent` (to preserve the naming style) +- Rename `createComponentInstance` to `addComponentInstance` (to preserve the naming style) +- Remove `lookupShape` +- Remove `asMap` +- Remove `updateLibraryColor` (use `addLibraryColor` if you just need to replace a color) +- Remove `deleteLibraryColor` (this library is intended to build files) +- Remove `updateLibraryTypography` (use `addLibraryTypography` if you just need to replace a typography) +- Remove `deleteLibraryTypography` (this library is intended to build files) +- Remove `add/update/deleteLibraryMedia` (they are no longer supported by Penpot and have been replaced by components) +- Remove `deleteObject` (this library is intended to build files) +- Remove `updateObject` (this library is intended to build files) +- Remove `finishComponent` (it is no longer necessary; see below for more details on component creation changes) + +- Change the `getCurrentPageId` function to a read-only `currentPageId` property +- Add `currentFileId` read-only property +- Add `currentFrameId` read-only property +- Add `lastId` read-only property + + +## 0.0.0 + +Unreleased, initial protype version.