tldraw/packages/tlschema
alex f2d8fae6ea
hoist opacity out of props (#1526)
This change hoists opacity out of props and changes it to a number
instead of an enum.

The change to a number is to make tldraw more flexible for library
consumers who might want more expressivity with opacity than our 5
possible values allow. the tldraw editor will now happily respect any
opacity between 0 and 1. The limit to our supported values is enforced
only in the UI. I think this is limited enough that it's a reasonable
tradeoff between in-app simplicity and giving external developers the
flexibility they need.

There's a new `opacityForNextShape` property on the instance. This works
exactly the same way as propsForNextShape does, except... it's just for
opacity. With this, there should be no user-facing changes to how
opacity works in tldraw. There are also new `opacity`/`setOpacity` APIs
in the editor that work with it/selections similar to how props do.

@ds300 do you mind reviewing the migrations here?

### Change Type

- [x] `major` — Breaking Change

### Test Plan

- [x] Unit Tests
- [ ] Webdriver tests

### Release Notes

[internal only for now]
2023-06-06 16:15:12 +00:00
..
src hoist opacity out of props (#1526) 2023-06-06 16:15:12 +00:00
api-extractor.json transfer-out: transfer out 2023-04-25 12:01:25 +01:00
api-report.md hoist opacity out of props (#1526) 2023-06-06 16:15:12 +00:00
CHANGELOG.md transfer-out: transfer out 2023-04-25 12:01:25 +01:00
LICENSE transfer-out: transfer out 2023-04-25 12:01:25 +01:00
package.json update lazyrepo 2023-06-05 18:32:32 +01:00
README.md TLSchema readme (#1506) 2023-06-03 08:24:58 +00:00
tsconfig.json Rename tlstore to store (#1507) 2023-06-03 08:59:04 +00:00

@tldraw/tlschema

This package houses type definitions, schema migrations, and other type metadata for the tldraw editor's default persisted data.

There are three main kinds of types:

  • Record types

    These are root record types added to the Store class. They are defined in the ./src/records directory.

  • Shape types

    These are subtypes of the root TLShape record type. They allow specifying a unique name and custom props for a particular kind of shape.

  • Asset types

    These are subtypes of the root TLAsset record type. They allow specifying a unique name and custom props for a particular kind of asset.

Adding migrations

If you make any kind of change to any persisted data shape in this package, you must add migrations that are able to convert old versions to new versions, and vice-versa.

If you are making a change that affects the structure of a record, shape, or asset, update the migrations in the same file as the record, shape, or asset is defined.

If you are making a change that affects the structure of the store (e.g. renaming or deleting a type, consolidating two shape types into one, etc), add your changes in the migrations in schema.ts.

After making your changes, add a new version number, using a meaninful name. For example, if you add a new property to the TLShape type called ownerId that points to a user, you might do this:

In TLShape.ts

 const Versions = {
   RemoveSomeProp: 1,
+  AddOwnerId: 2,
 } as const

and then in the TLShape type

   x: number
   y: number
+  ownerId: ID<TLUser> | null
   props: Props
   parentId: ID<TLShape> | ID<TLPage>

and then adding a migration:

 export const shapeTypeMigrations = defineMigrations({
   currentVersion: Versions.Initial,
   firstVersion: Versions.Initial,
   migrators: {
+    [Versions.AddOwnerId]: {
+      // add ownerId property
+      up: (shape) => ({...shape, ownerId: null}),
+      // remove ownerId property
+      down: ({ownerId, ...shape}) => shape,
+    }
   },

After you've added your migration, make sure to add a test for it in src/migrations.test.ts. It will complain if you do not!

License

The source code in this repository (as well as our 2.0+ distributions and releases) are currently licensed under Apache-2.0. These licenses are subject to change in our upcoming 2.0 release. If you are planning to use tldraw in a commercial product, please reach out at hello@tldraw.com.