tldraw/packages/tlschema/api-report.md

1235 lines
38 KiB
Markdown
Raw Normal View History

2023-04-25 11:01:25 +00:00
## API Report File for "@tldraw/tlschema"
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
import { BaseRecord } from '@tldraw/store';
import { Migrations } from '@tldraw/store';
import { RecordId } from '@tldraw/store';
import { RecordType } from '@tldraw/store';
import { Signal } from 'signia';
import { Store } from '@tldraw/store';
import { StoreSchema } from '@tldraw/store';
import { StoreSnapshot } from '@tldraw/store';
import { T } from '@tldraw/validate';
import { UnknownRecord } from '@tldraw/store';
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const alignValidator: T.Validator<"end" | "middle" | "start">;
// @internal (undocumented)
export const arrowShapeMigrations: Migrations;
// @internal (undocumented)
export const arrowShapeProps: ShapeProps<TLArrowShape>;
// @public
export const assetIdValidator: T.Validator<TLAssetId>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const assetMigrations: Migrations;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const AssetRecordType: RecordType<TLAsset, "props" | "type">;
// @internal (undocumented)
export const assetValidator: T.Validator<TLAsset>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const bookmarkShapeMigrations: Migrations;
// @internal (undocumented)
export const bookmarkShapeProps: ShapeProps<TLBookmarkShape>;
// @public
2023-04-25 11:01:25 +00:00
export interface Box2dModel {
// (undocumented)
h: number;
// (undocumented)
w: number;
// (undocumented)
x: number;
// (undocumented)
y: number;
}
// @public (undocumented)
export const CameraRecordType: RecordType<TLCamera, never>;
// @public
export const canvasUiColorTypeValidator: T.Validator<"accent" | "black" | "laser" | "muted-1" | "selection-fill" | "selection-stroke" | "white">;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export function CLIENT_FIXUP_SCRIPT(persistedStore: StoreSnapshot<TLRecord>): StoreSnapshot<TLRecord>;
// @internal (undocumented)
export const colorValidator: T.Validator<"black" | "blue" | "green" | "grey" | "light-blue" | "light-green" | "light-red" | "light-violet" | "orange" | "red" | "violet" | "yellow">;
// @public
2023-04-25 11:01:25 +00:00
export function createAssetValidator<Type extends string, Props extends object>(type: Type, props: T.Validator<Props>): T.ObjectValidator<{
id: TLAssetId;
typeName: 'asset';
type: Type;
props: Props;
}>;
// @public (undocumented)
export const createPresenceStateDerivation: ($user: Signal<{
id: string;
color: string;
name: string;
}>) => (store: TLStore) => Signal<null | TLInstancePresence>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export function createShapeId(id?: string): TLShapeId;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export function createShapeValidator<Type extends string, Props extends object>(type: Type, props?: {
[K in keyof Props]: T.Validatable<Props[K]>;
}): T.ObjectValidator<{
2023-04-25 11:01:25 +00:00
id: TLShapeId;
typeName: "shape";
x: number;
y: number;
rotation: number;
index: string;
parentId: TLParentId;
type: Type;
isLocked: boolean;
opacity: number;
props: Props | Record<string, unknown>;
2023-04-25 11:01:25 +00:00
}>;
// @public
export function createTLSchema({ shapes }: {
shapes: Record<string, SchemaShapeInfo>;
}): TLSchema;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const dashValidator: T.Validator<"dashed" | "dotted" | "draw" | "solid">;
// @public (undocumented)
export const DocumentRecordType: RecordType<TLDocument, never>;
// @internal (undocumented)
export const drawShapeMigrations: Migrations;
// @internal (undocumented)
export const drawShapeProps: ShapeProps<TLDrawShape>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const EMBED_DEFINITIONS: readonly [{
readonly type: "tldraw";
readonly title: "tldraw";
readonly hostnames: readonly ["beta.tldraw.com", "lite.tldraw.com", "www.tldraw.com"];
readonly minWidth: 300;
readonly minHeight: 300;
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: true;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "codesandbox";
readonly title: "CodeSandbox";
readonly hostnames: readonly ["codesandbox.io"];
readonly minWidth: 300;
readonly minHeight: 300;
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "codepen";
readonly title: "Codepen";
readonly hostnames: readonly ["codepen.io"];
readonly minWidth: 300;
readonly minHeight: 300;
readonly width: 520;
readonly height: 400;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "scratch";
readonly title: "Scratch";
readonly hostnames: readonly ["scratch.mit.edu"];
readonly width: 520;
readonly height: 400;
readonly doesResize: false;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "youtube";
readonly title: "YouTube";
readonly hostnames: readonly ["*.youtube.com", "youtube.com", "youtu.be"];
readonly width: 800;
readonly height: 450;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly overridePermissions: {
readonly 'allow-presentation': true;
};
readonly isAspectRatioLocked: true;
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "figma";
readonly title: "Figma";
readonly hostnames: readonly ["figma.com"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: true;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "google_maps";
readonly title: "Google Maps";
readonly hostnames: readonly ["google.*"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "google_calendar";
readonly title: "Google Calendar";
readonly hostnames: readonly ["calendar.google.*"];
readonly width: 720;
readonly height: 500;
readonly minWidth: 460;
readonly minHeight: 360;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly instructionLink: "https://support.google.com/calendar/answer/41207?hl=en";
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "google_slides";
readonly title: "Google Slides";
readonly hostnames: readonly ["docs.google.*"];
readonly width: 720;
readonly height: 500;
readonly minWidth: 460;
readonly minHeight: 360;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "github_gist";
readonly title: "GitHub Gist";
readonly hostnames: readonly ["gist.github.com"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: true;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "replit";
readonly title: "Replit";
readonly hostnames: readonly ["replit.com"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "felt";
readonly title: "Felt";
readonly hostnames: readonly ["felt.com"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "spotify";
readonly title: "Spotify";
readonly hostnames: readonly ["open.spotify.com"];
readonly width: 720;
readonly height: 500;
readonly minHeight: 500;
readonly overrideOutlineRadius: 12;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "vimeo";
readonly title: "Vimeo";
readonly hostnames: readonly ["vimeo.com", "player.vimeo.com"];
readonly width: 640;
readonly height: 360;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly isAspectRatioLocked: true;
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "excalidraw";
readonly title: "Excalidraw";
readonly hostnames: readonly ["excalidraw.com"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly isAspectRatioLocked: true;
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}, {
readonly type: "observable";
readonly title: "Observable";
readonly hostnames: readonly ["observablehq.com"];
readonly width: 720;
readonly height: 500;
readonly doesResize: true;
readonly canUnmount: false;
2023-04-25 11:01:25 +00:00
readonly isAspectRatioLocked: false;
readonly backgroundColor: "#fff";
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
}];
// @public (undocumented)
export type EmbedDefinition = {
readonly type: string;
readonly title: string;
readonly hostnames: readonly string[];
readonly minWidth?: number;
readonly minHeight?: number;
readonly width: number;
readonly height: number;
readonly doesResize: boolean;
readonly canUnmount: boolean;
2023-04-25 11:01:25 +00:00
readonly isAspectRatioLocked?: boolean;
readonly overridePermissions?: TLEmbedShapePermissions;
readonly instructionLink?: string;
readonly backgroundColor?: string;
readonly overrideOutlineRadius?: number;
readonly toEmbedUrl: (url: string) => string | undefined;
readonly fromEmbedUrl: (url: string) => string | undefined;
};
// @internal (undocumented)
export const embedShapeMigrations: Migrations;
// @public
export const embedShapePermissionDefaults: {
readonly 'allow-downloads-without-user-activation': false;
readonly 'allow-downloads': false;
readonly 'allow-modals': false;
readonly 'allow-orientation-lock': false;
readonly 'allow-pointer-lock': false;
readonly 'allow-popups': true;
readonly 'allow-popups-to-escape-sandbox': false;
readonly 'allow-presentation': false;
readonly 'allow-storage-access-by-user-activation': false;
readonly 'allow-top-navigation': false;
readonly 'allow-top-navigation-by-user-activation': false;
readonly 'allow-scripts': true;
readonly 'allow-same-origin': true;
readonly 'allow-forms': true;
};
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const embedShapeProps: ShapeProps<TLEmbedShape>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const fillValidator: T.Validator<"none" | "pattern" | "semi" | "solid">;
// @internal (undocumented)
export function fixupRecord(oldRecord: TLRecord): {
record: any;
issues: string[];
};
// @internal (undocumented)
export const fontValidator: T.Validator<"draw" | "mono" | "sans" | "serif">;
// @internal (undocumented)
export const frameShapeMigrations: Migrations;
// @internal (undocumented)
export const frameShapeProps: ShapeProps<TLFrameShape>;
// @internal (undocumented)
export const geoShapeMigrations: Migrations;
// @internal (undocumented)
export const geoShapeProps: ShapeProps<TLGeoShape>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const geoValidator: T.Validator<"arrow-down" | "arrow-left" | "arrow-right" | "arrow-up" | "check-box" | "diamond" | "ellipse" | "hexagon" | "octagon" | "oval" | "pentagon" | "rectangle" | "rhombus-2" | "rhombus" | "star" | "trapezoid" | "triangle" | "x-box">;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export function getDefaultTranslationLocale(): TLLanguage['locale'];
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const groupShapeMigrations: Migrations;
// @internal (undocumented)
export const groupShapeProps: ShapeProps<TLGroupShape>;
// @internal (undocumented)
export const highlightShapeMigrations: Migrations;
// @internal (undocumented)
export const highlightShapeProps: ShapeProps<TLHighlightShape>;
// @internal (undocumented)
export const iconShapeMigrations: Migrations;
// @internal (undocumented)
export const iconShapeProps: ShapeProps<TLIconShape>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const iconValidator: T.Validator<"activity" | "airplay" | "alert-circle" | "alert-octagon" | "alert-triangle" | "align-center" | "align-justify" | "align-left" | "align-right" | "anchor" | "aperture" | "archive" | "arrow-down-circle" | "arrow-down-left" | "arrow-down-right" | "arrow-down" | "arrow-left-circle" | "arrow-left" | "arrow-right-circle" | "arrow-right" | "arrow-up-circle" | "arrow-up-left" | "arrow-up-right" | "arrow-up" | "at-sign" | "award" | "bar-chart-2" | "bar-chart" | "battery-charging" | "battery" | "bell-off" | "bell" | "bluetooth" | "bold" | "book-open" | "book" | "bookmark" | "briefcase" | "calendar" | "camera-off" | "camera" | "cast" | "check-circle" | "check-square" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "chevron-up" | "chevrons-down" | "chevrons-left" | "chevrons-right" | "chevrons-up" | "chrome" | "circle" | "clipboard" | "clock" | "cloud-drizzle" | "cloud-lightning" | "cloud-off" | "cloud-rain" | "cloud-snow" | "cloud" | "codepen" | "codesandbox" | "coffee" | "columns" | "command" | "compass" | "copy" | "corner-down-left" | "corner-down-right" | "corner-left-down" | "corner-left-up" | "corner-right-down" | "corner-right-up" | "corner-up-left" | "corner-up-right" | "cpu" | "credit-card" | "crop" | "crosshair" | "database" | "delete" | "disc" | "divide-circle" | "divide-square" | "divide" | "dollar-sign" | "download-cloud" | "download" | "dribbble" | "droplet" | "edit-2" | "edit-3" | "edit" | "external-link" | "eye-off" | "eye" | "facebook" | "fast-forward" | "feather" | "figma" | "file-minus" | "file-plus" | "file-text" | "file" | "film" | "filter" | "flag" | "folder-minus" | "folder-plus" | "folder" | "framer" | "frown" | "geo" | "gift" | "git-branch" | "git-commit" | "git-merge" | "git-pull-request" | "github" | "gitlab" | "globe" | "grid" | "hard-drive" | "hash" | "headphones" | "heart" | "help-circle" | "hexagon" | "home" | "image" | "inbox" | "info" | "instagram" | "italic" | "key" | "layers" | "layout" | "life-buoy" | "link-2" | "link" | "linkedin" | "list" | "loader" | "lock" | "log-in" | "log-out" | "mail" | "map-pin" | "map" | "maximize-2" | "maximize" | "meh" | "menu" | "message-circle" | "message-square" | "mic-off" | "mic" | "minimize-2" | "minimize" | "minus-circle" | "minus-square" | "minus" | "monitor" | "moon" | "more-horizontal" | "more-vertical" | "mouse-pointer" | "move" | "music" | "navigation-2" | "navigation" | "octagon" | "package" | "paperclip" | "pause-circle" | "pause" | "pen-tool" | "percent" | "phone-call" | "phone-forwarded" | "phone-incoming" | "phone-missed" | "phone-off" | "phone-outgoing" | "phone" | "pie-chart" | "play-circle" | "play" | "plus-circle" | "plus-square" | "plus" | "pocket" | "power" | "printer" | "radio" | "refresh-ccw" | "refresh-cw" | "repeat" | "rewind" | "rotate-ccw" | "rotate-cw" | "rss" | "save" | "scissors" | "search" | "send" | "server" | "settings" | "share-2" | "share" | "shield-off" | "shield" | "shopping-bag" | "shopping-cart" | "shuffle" | "sidebar" | "skip-back" | "skip-forward" | "slack" | "slash" | "sliders" | "smartphone" | "smile" | "speaker" | "square" | "star" | "stop-circle" | "sun" | "sunrise" | "sunset" | "table" | "tablet" | "tag" | "target" | "terminal" | "thermometer" | "thumbs-down" | "thumbs-up" | "toggle-left" | "toggle-right" | "tool" | "trash-2" | "trash" | "trello" | "trending-down" | "trending-up" | "triangle" | "truck" | "tv" | "twitch" | "twitter" | "type" | "umbrella" | "underline" | "unlock" | "upload-cloud" | "upload" | "user-check" | "user-minus" | "user-plus" | "user-x" | "user" | "users" | "video-off" | "video" | "voicemail" | "volume-1" | "volume-2" | "volume-x" | "volume" | "watch" | "wifi-off" | "wifi" | "wind" | "x-circle" | "x-octagon" | "x-square" | "x" | "youtube" | "zap-off" | "zap" | "zoom-in" | "zoom-out">;
// @internal (undocumented)
export function idValidator<Id extends RecordId<UnknownRecord>>(prefix: Id['__type__']['typeName']): T.Validator<Id>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const imageShapeMigrations: Migrations;
// @internal (undocumented)
export const imageShapeProps: ShapeProps<TLImageShape>;
// @public (undocumented)
Independent instance state persistence (#1493) This PR - Removes UserDocumentRecordType - moving isSnapMode to user preferences - moving isGridMode and isPenMode to InstanceRecordType - deleting the other properties which are no longer needed. - Creates a separate pipeline for persisting instance state. Previously the instance state records were stored alongside the document state records, and in order to load the state for a particular instance (in our case, a particular tab) you needed to pass the 'instanceId' prop. This prop ended up totally pervading the public API and people ran into all kinds of issues with it, e.g. using the same instance id in multiple editor instances. There was also an issue whereby it was hard for us to clean up old instance state so the idb table ended up bloating over time. This PR makes it so that rather than passing an instanceId, you load the instance state yourself while creating the store. It provides tools to make that easy. - Undoes the assumption that we might have more than one instance's state in the store. - Like `document`, `instance` now has a singleton id `instance:instance`. - Page state ids and camera ids are no longer random, but rather derive from the page they belong to. This is like having a foreign primary key in SQL databases. It's something i'd love to support fully as part of the RecordType/Store api. Tests to do - [x] Test Migrations - [x] Test Store.listen filtering - [x] Make type sets in Store public and readonly - [x] Test RecordType.createId - [x] Test Instance state snapshot loading/exporting - [x] Manual test File I/O - [x] Manual test Vscode extension with multiple tabs - [x] Audit usages of store.query - [x] Audit usages of changed types: InstanceRecordType, 'instance', InstancePageStateRecordType, 'instance_page_state', 'user_document', 'camera', CameraRecordType, InstancePresenceRecordType, 'instance_presence' - [x] Test user preferences - [x] Manual test isSnapMode and isGridMode and isPenMode - [ ] Test indexedDb functions - [x] Add instanceId stuff back ### Change Type - [x] `major` — Breaking Change ### Test Plan 1. Add a step-by-step description of how to test your PR here. 2. - [ ] Unit Tests - [ ] Webdriver tests ### Release Notes - Add a brief release note for your PR here.
2023-06-05 14:11:07 +00:00
export const InstancePageStateRecordType: RecordType<TLInstancePageState, "pageId">;
// @public (undocumented)
Independent instance state persistence (#1493) This PR - Removes UserDocumentRecordType - moving isSnapMode to user preferences - moving isGridMode and isPenMode to InstanceRecordType - deleting the other properties which are no longer needed. - Creates a separate pipeline for persisting instance state. Previously the instance state records were stored alongside the document state records, and in order to load the state for a particular instance (in our case, a particular tab) you needed to pass the 'instanceId' prop. This prop ended up totally pervading the public API and people ran into all kinds of issues with it, e.g. using the same instance id in multiple editor instances. There was also an issue whereby it was hard for us to clean up old instance state so the idb table ended up bloating over time. This PR makes it so that rather than passing an instanceId, you load the instance state yourself while creating the store. It provides tools to make that easy. - Undoes the assumption that we might have more than one instance's state in the store. - Like `document`, `instance` now has a singleton id `instance:instance`. - Page state ids and camera ids are no longer random, but rather derive from the page they belong to. This is like having a foreign primary key in SQL databases. It's something i'd love to support fully as part of the RecordType/Store api. Tests to do - [x] Test Migrations - [x] Test Store.listen filtering - [x] Make type sets in Store public and readonly - [x] Test RecordType.createId - [x] Test Instance state snapshot loading/exporting - [x] Manual test File I/O - [x] Manual test Vscode extension with multiple tabs - [x] Audit usages of store.query - [x] Audit usages of changed types: InstanceRecordType, 'instance', InstancePageStateRecordType, 'instance_page_state', 'user_document', 'camera', CameraRecordType, InstancePresenceRecordType, 'instance_presence' - [x] Test user preferences - [x] Manual test isSnapMode and isGridMode and isPenMode - [ ] Test indexedDb functions - [x] Add instanceId stuff back ### Change Type - [x] `major` — Breaking Change ### Test Plan 1. Add a step-by-step description of how to test your PR here. 2. - [ ] Unit Tests - [ ] Webdriver tests ### Release Notes - Add a brief release note for your PR here.
2023-06-05 14:11:07 +00:00
export const InstancePresenceRecordType: RecordType<TLInstancePresence, "currentPageId" | "userId" | "userName">;
// @public (undocumented)
export const InstanceRecordType: RecordType<TLInstance, "currentPageId">;
// @internal (undocumented)
2023-04-25 11:01:25 +00:00
export const instanceTypeValidator: T.Validator<TLInstance>;
// @public (undocumented)
export function isPageId(id: string): id is TLPageId;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export function isShape(record?: UnknownRecord): record is TLShape;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export function isShapeId(id?: string): id is TLShapeId;
// @public (undocumented)
export const LANGUAGES: readonly [{
readonly locale: "ar";
readonly label: "عربي";
}, {
readonly locale: "ca";
readonly label: "Català";
}, {
readonly locale: "da";
readonly label: "Danish";
}, {
readonly locale: "de";
readonly label: "Deutsch";
}, {
readonly locale: "en";
readonly label: "English";
}, {
readonly locale: "es";
readonly label: "Español";
}, {
readonly locale: "fa";
readonly label: "فارسی";
}, {
readonly locale: "fi";
readonly label: "Suomi";
}, {
readonly locale: "fr";
readonly label: "Français";
}, {
readonly locale: "gl";
readonly label: "Galego";
}, {
readonly locale: "he";
readonly label: "עברית";
}, {
readonly locale: "it";
readonly label: "Italiano";
}, {
readonly locale: "ja";
readonly label: "日本語";
}, {
readonly locale: "ko-kr";
readonly label: "한국어";
}, {
readonly locale: "ku";
readonly label: "کوردی";
}, {
readonly locale: "hi-in";
readonly label: "हिन्दी";
}, {
readonly locale: "hu";
readonly label: "Magyar";
}, {
readonly locale: "my";
readonly label: "မြန်မာစာ";
}, {
readonly locale: "ne";
readonly label: "नेपाली";
}, {
readonly locale: "no";
readonly label: "Norwegian";
}, {
readonly locale: "pl";
readonly label: "Polski";
}, {
readonly locale: "pt-br";
readonly label: "Português - Brasil";
}, {
readonly locale: "pt-pt";
readonly label: "Português - Europeu";
}, {
readonly locale: "ro";
readonly label: "Română";
}, {
readonly locale: "ru";
readonly label: "Russian";
}, {
readonly locale: "sv";
readonly label: "Svenska";
}, {
readonly locale: "te";
readonly label: "తెలుగు";
}, {
readonly locale: "th";
readonly label: "ภาษาไทย";
}, {
readonly locale: "tr";
readonly label: "Türkçe";
}, {
readonly locale: "uk";
readonly label: "Ukrainian";
}, {
readonly locale: "vi";
readonly label: "Tiếng Việt";
}, {
readonly locale: "zh-cn";
readonly label: "Chinese - Simplified";
}, {
readonly locale: "zh-tw";
readonly label: "繁體中文 (台灣)";
}];
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const lineShapeMigrations: Migrations;
// @internal (undocumented)
export const lineShapeProps: ShapeProps<TLLineShape>;
// @internal (undocumented)
export const noteShapeMigrations: Migrations;
// @internal (undocumented)
export const noteShapeProps: ShapeProps<TLNoteShape>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const opacityValidator: T.Validator<number>;
2023-04-25 11:01:25 +00:00
Independent instance state persistence (#1493) This PR - Removes UserDocumentRecordType - moving isSnapMode to user preferences - moving isGridMode and isPenMode to InstanceRecordType - deleting the other properties which are no longer needed. - Creates a separate pipeline for persisting instance state. Previously the instance state records were stored alongside the document state records, and in order to load the state for a particular instance (in our case, a particular tab) you needed to pass the 'instanceId' prop. This prop ended up totally pervading the public API and people ran into all kinds of issues with it, e.g. using the same instance id in multiple editor instances. There was also an issue whereby it was hard for us to clean up old instance state so the idb table ended up bloating over time. This PR makes it so that rather than passing an instanceId, you load the instance state yourself while creating the store. It provides tools to make that easy. - Undoes the assumption that we might have more than one instance's state in the store. - Like `document`, `instance` now has a singleton id `instance:instance`. - Page state ids and camera ids are no longer random, but rather derive from the page they belong to. This is like having a foreign primary key in SQL databases. It's something i'd love to support fully as part of the RecordType/Store api. Tests to do - [x] Test Migrations - [x] Test Store.listen filtering - [x] Make type sets in Store public and readonly - [x] Test RecordType.createId - [x] Test Instance state snapshot loading/exporting - [x] Manual test File I/O - [x] Manual test Vscode extension with multiple tabs - [x] Audit usages of store.query - [x] Audit usages of changed types: InstanceRecordType, 'instance', InstancePageStateRecordType, 'instance_page_state', 'user_document', 'camera', CameraRecordType, InstancePresenceRecordType, 'instance_presence' - [x] Test user preferences - [x] Manual test isSnapMode and isGridMode and isPenMode - [ ] Test indexedDb functions - [x] Add instanceId stuff back ### Change Type - [x] `major` — Breaking Change ### Test Plan 1. Add a step-by-step description of how to test your PR here. 2. - [ ] Unit Tests - [ ] Webdriver tests ### Release Notes - Add a brief release note for your PR here.
2023-06-05 14:11:07 +00:00
// @internal (undocumented)
export const pageIdValidator: T.Validator<TLPageId>;
// @public (undocumented)
export const PageRecordType: RecordType<TLPage, "index" | "name">;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const parentIdValidator: T.Validator<TLParentId>;
// @public (undocumented)
export const PointerRecordType: RecordType<TLPointer, never>;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const rootShapeMigrations: Migrations;
[refactor] User-facing APIs (#1478) This PR updates our user-facing APIs for the Tldraw and TldrawEditor components, as well as the Editor (App). It mainly incorporates surface changes from #1450 without any changes to validators or migrators, incorporating feedback / discussion with @SomeHats and @ds300. Here we: - remove the TldrawEditorConfig - bring back a loose version of shape definitions - make a separation between "core" shapes and "default" shapes - do not allow custom shapes, migrators or validators to overwrite core shapes - but _do_ allow new shapes ## `<Tldraw>` component In this PR, the `Tldraw` component wraps both the `TldrawEditor` component and our `TldrawUi` component. It accepts a union of props for both components. Previously, this component also added local syncing via a `useLocalSyncClient` hook call, however that has been pushed down to the `TldrawEditor` component. ## `<TldrawEditor>` component The `TldrawEditor` component now more neatly wraps up the different ways that the editor can be configured. ## The store prop (`TldrawEditorProps.store`) There are three main ways for the `TldrawEditor` component to be run: 1. with an externally defined store 2. with an externally defined syncing store (local or remote) 3. with an internally defined store 4. with an internally defined locally syncing store The `store` prop allows for these configurations. If the `store` prop is defined, it may be defined either as a `TLStore` or as a `SyncedStore`. If the store is a `TLStore`, then the Editor will assume that the store is ready to go; if it is defined as a SyncedStore, then the component will display the loading / error screens as needed, or the final editor once the store's status is "synced". When the store is left undefined, then the `TldrawEditor` will create its own internal store using the optional `instanceId`, `initialData`, or `shapes` props to define the store / store schema. If the `persistenceKey` prop is left undefined, then the store will not be synced. If the `persistenceKey` is defined, then the store will be synced locally. In the future, we may also here accept the API key / roomId / etc for creating a remotely synced store. The `SyncedStore` type has been expanded to also include types used for remote syncing, e.g. with `ConnectionStatus`. ## Tools By default, the App has two "baked-in" tools: the select tool and the zoom tool. These cannot (for now) be replaced or removed. The default tools are used by default, but may be replaced by other tools if provided. ## Shapes By default, the App has a set of "core" shapes: - group - embed - bookmark - image - video - text That cannot by overwritten because they're created by the app at different moments, such as when double clicking on the canvas or via a copy and paste event. In follow up PRs, we'll split these out so that users can replace parts of the code where these shapes are created. ### Change Type - [x] `major` — Breaking Change ### Test Plan - [x] Unit Tests
2023-06-01 15:47:34 +00:00
// @public (undocumented)
export type SchemaShapeInfo = {
migrations?: Migrations;
props?: Record<string, {
validate: (prop: any) => any;
}>;
};
// @internal (undocumented)
export const scribbleValidator: T.Validator<TLScribble>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const shapeIdValidator: T.Validator<TLShapeId>;
// @public (undocumented)
export type ShapeProps<Shape extends TLBaseShape<any, any>> = {
[K in keyof Shape['props']]: T.Validator<Shape['props'][K]>;
};
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const sizeValidator: T.Validator<"l" | "m" | "s" | "xl">;
// @internal (undocumented)
export const splineValidator: T.Validator<"cubic" | "line">;
// @internal (undocumented)
export const textShapeMigrations: Migrations;
// @internal (undocumented)
export const textShapeProps: ShapeProps<TLTextShape>;
// @public (undocumented)
export const TL_ALIGN_TYPES: Set<"end" | "middle" | "start">;
// @public (undocumented)
export const TL_ARROWHEAD_TYPES: Set<"arrow" | "bar" | "diamond" | "dot" | "inverted" | "none" | "pipe" | "square" | "triangle">;
// @public
export const TL_CANVAS_UI_COLOR_TYPES: Set<"accent" | "black" | "laser" | "muted-1" | "selection-fill" | "selection-stroke" | "white">;
// @public (undocumented)
export const TL_COLOR_TYPES: Set<"black" | "blue" | "green" | "grey" | "light-blue" | "light-green" | "light-red" | "light-violet" | "orange" | "red" | "violet" | "yellow">;
// @public (undocumented)
export const TL_DASH_TYPES: Set<"dashed" | "dotted" | "draw" | "solid">;
// @public (undocumented)
export const TL_FILL_TYPES: Set<"none" | "pattern" | "semi" | "solid">;
// @public (undocumented)
export const TL_FONT_TYPES: Set<"draw" | "mono" | "sans" | "serif">;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const TL_GEO_TYPES: Set<"arrow-down" | "arrow-left" | "arrow-right" | "arrow-up" | "check-box" | "diamond" | "ellipse" | "hexagon" | "octagon" | "oval" | "pentagon" | "rectangle" | "rhombus-2" | "rhombus" | "star" | "trapezoid" | "triangle" | "x-box">;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const TL_SIZE_TYPES: Set<"l" | "m" | "s" | "xl">;
// @public (undocumented)
export const TL_SPLINE_TYPES: Set<"cubic" | "line">;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export const TL_STYLE_TYPES: Set<"align" | "arrowheadEnd" | "arrowheadStart" | "color" | "dash" | "fill" | "font" | "geo" | "icon" | "labelColor" | "size" | "spline" | "verticalAlign">;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export interface TLAlignStyle extends TLBaseStyle {
// (undocumented)
id: TLAlignType;
// (undocumented)
type: 'align';
}
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLAlignType = SetValue<typeof TL_ALIGN_TYPES>;
// @public (undocumented)
export interface TLArrowheadEndStyle extends TLBaseStyle {
// (undocumented)
id: TLArrowheadType;
// (undocumented)
type: 'arrowheadEnd';
}
// @public (undocumented)
export interface TLArrowheadStartStyle extends TLBaseStyle {
// (undocumented)
id: TLArrowheadType;
// (undocumented)
type: 'arrowheadStart';
}
// @public (undocumented)
export type TLArrowheadType = SetValue<typeof TL_ARROWHEAD_TYPES>;
// @public (undocumented)
export type TLArrowShape = TLBaseShape<'arrow', TLArrowShapeProps>;
// @public (undocumented)
export type TLArrowShapeProps = {
labelColor: TLColorType;
color: TLColorType;
fill: TLFillType;
dash: TLDashType;
size: TLSizeType;
arrowheadStart: TLArrowheadType;
arrowheadEnd: TLArrowheadType;
font: TLFontType;
start: TLArrowTerminal;
end: TLArrowTerminal;
bend: number;
text: string;
};
// @public (undocumented)
export type TLArrowTerminal = {
type: 'binding';
boundShapeId: TLShapeId;
normalizedAnchor: Vec2dModel;
isExact: boolean;
} | {
type: 'point';
x: number;
y: number;
};
// @public (undocumented)
export type TLArrowTerminalType = SetValue<typeof TL_ARROW_TERMINAL_TYPE>;
// @public (undocumented)
export type TLAsset = TLBookmarkAsset | TLImageAsset | TLVideoAsset;
// @public (undocumented)
export type TLAssetId = RecordId<TLBaseAsset<any, any>>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLAssetPartial<T extends TLAsset = TLAsset> = T extends T ? {
id: TLAssetId;
type: T['type'];
props?: Partial<T['props']>;
} & Partial<Omit<T, 'id' | 'props' | 'type'>> : never;
// @public (undocumented)
export type TLAssetShape = Extract<TLShape, {
props: {
assetId: TLAssetId;
};
}>;
// @public (undocumented)
export interface TLBaseAsset<Type extends string, Props> extends BaseRecord<'asset', TLAssetId> {
2023-04-25 11:01:25 +00:00
// (undocumented)
props: Props;
// (undocumented)
type: Type;
}
// @public (undocumented)
export interface TLBaseShape<Type extends string, Props extends object> extends BaseRecord<'shape', TLShapeId> {
2023-04-25 11:01:25 +00:00
// (undocumented)
index: string;
// (undocumented)
isLocked: boolean;
// (undocumented)
opacity: TLOpacityType;
// (undocumented)
2023-04-25 11:01:25 +00:00
parentId: TLParentId;
// (undocumented)
props: Props;
// (undocumented)
rotation: number;
// (undocumented)
type: Type;
// (undocumented)
x: number;
// (undocumented)
y: number;
}
// @public
2023-04-25 11:01:25 +00:00
export type TLBookmarkAsset = TLBaseAsset<'bookmark', {
title: string;
description: string;
image: string;
src: null | string;
}>;
// @public (undocumented)
export type TLBookmarkShape = TLBaseShape<'bookmark', TLBookmarkShapeProps>;
// @public
export interface TLCamera extends BaseRecord<'camera', TLCameraId> {
2023-04-25 11:01:25 +00:00
// (undocumented)
x: number;
// (undocumented)
y: number;
// (undocumented)
z: number;
}
// @public
export type TLCameraId = RecordId<TLCamera>;
// @public
export type TLCanvasUiColor = SetValue<typeof TL_CANVAS_UI_COLOR_TYPES>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export interface TLColorStyle extends TLBaseStyle {
// (undocumented)
id: TLColorType;
// (undocumented)
type: 'color';
}
// @public (undocumented)
export type TLColorType = SetValue<typeof TL_COLOR_TYPES>;
2023-04-25 11:01:25 +00:00
// @public
2023-04-25 11:01:25 +00:00
export interface TLCursor {
// (undocumented)
color: TLCanvasUiColor;
2023-04-25 11:01:25 +00:00
// (undocumented)
rotation: number;
// (undocumented)
type: TLCursorType;
}
// @public
2023-04-25 11:01:25 +00:00
export type TLCursorType = SetValue<typeof TL_CURSOR_TYPES>;
// @public (undocumented)
export interface TLDashStyle extends TLBaseStyle {
// (undocumented)
id: TLDashType;
// (undocumented)
type: 'dash';
}
// @public (undocumented)
export type TLDashType = SetValue<typeof TL_DASH_TYPES>;
// @public
export type TLDefaultShape = TLArrowShape | TLBookmarkShape | TLDrawShape | TLEmbedShape | TLFrameShape | TLGeoShape | TLGroupShape | TLHighlightShape | TLIconShape | TLImageShape | TLLineShape | TLNoteShape | TLTextShape | TLVideoShape;
2023-04-25 11:01:25 +00:00
// @public
export interface TLDocument extends BaseRecord<'document', RecordId<TLDocument>> {
2023-04-25 11:01:25 +00:00
// (undocumented)
gridSize: number;
Add support for project names (#1340) This PR adds some things that we need for the Project Name feature on tldraw.com. It should be reviewed alongside https://github.com/tldraw/tldraw-lite/pull/1814 ## Name Property This PR adds a `name` property to `TLDocument`. We use this to store a project's name. <img width="454" alt="Screenshot 2023-05-09 at 15 47 26" src="https://github.com/tldraw/tldraw/assets/15892272/f3be438e-aa0f-4dec-8f51-8dfd9f9d0ced"> ## Top Zone This PR adds a `topZone` area of the UI that we can add stuff to, similar to how `shareZone` works. It also adds an example to show where the `topZone` and `shareZone` are: <img width="1511" alt="Screenshot 2023-05-12 at 10 57 40" src="https://github.com/tldraw/tldraw/assets/15892272/f5e1cd33-017e-4aaf-bfee-4d85119e2974"> ## Breakpoints This PR change's the UI's breakpoints a little bit. It moves the action bar to the bottom a little bit earlier. (This gives us more space at the top for the project name). ![2023-05-12 at 11 08 26 - Fuchsia Bison](https://github.com/tldraw/tldraw/assets/15892272/34563cea-b1d1-47be-ac5e-5650ee0ba02d) ![2023-05-12 at 13 45 04 - Tan Mole](https://github.com/tldraw/tldraw/assets/15892272/ab190bd3-51d4-4a8b-88de-c72ab14bcba6) ## Input Blur This PR adds an `onBlur` parameter to `Input`. This was needed because 'clicking off' the input wasn't firing `onComplete` or `onCancel`. <img width="620" alt="Screenshot 2023-05-09 at 16 12 58" src="https://github.com/tldraw/tldraw/assets/15892272/3b28da74-0a74-4063-8053-e59e47027caf"> ## Create Project Name This PR adds an internal `createProjectName` property to `TldrawEditorConfig`. Similar to `derivePresenceState`, you can pass a custom function to it. It lets you control what gets used as the default project name. We use it to set different names in our local projects compared to shared projects. In the future, when we add more advanced project features, we could handle this better within the UI. <img width="454" alt="Screenshot 2023-05-09 at 15 47 26" src="https://github.com/tldraw/tldraw/assets/15892272/da9a4699-ac32-40d9-a97c-6c682acfac41"> ### Test Plan 1. Gradually reduce the width of the browser window. 2. Check that the actions menu jumps to the bottom before the style panel moves to the bottom. --- 1. In the examples app, open the `/zones` example. 2. Check that there's a 'top zone' at the top. - [ ] Unit Tests - [ ] Webdriver tests ### Release Note - [dev] Added a `topZone` area where you can put stuff. - [dev] Added a `name` property to `TLDocument` - and `app` methods for it. - [dev] Added an internal `createProjectName` config property for controlling the default project name. - [dev] Added an `onBlur` parameter to `Input`. - Moved the actions bar to the bottom on medium-sized screens. --------- Co-authored-by: Steve Ruiz <steveruizok@gmail.com>
2023-06-01 18:46:26 +00:00
// (undocumented)
name: string;
2023-04-25 11:01:25 +00:00
}
// @public (undocumented)
export const TLDOCUMENT_ID: RecordId<TLDocument>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLDrawShape = TLBaseShape<'draw', TLDrawShapeProps>;
// @public (undocumented)
export type TLDrawShapeSegment = {
type: SetValue<typeof TL_DRAW_SHAPE_SEGMENT_TYPE>;
points: Vec2dModel[];
};
// @public (undocumented)
export type TLEmbedShape = TLBaseShape<'embed', TLEmbedShapeProps>;
// @public (undocumented)
export type TLEmbedShapePermissions = {
[K in keyof typeof embedShapePermissionDefaults]?: boolean;
2023-04-25 11:01:25 +00:00
};
// @public (undocumented)
export interface TLFillStyle extends TLBaseStyle {
// (undocumented)
id: TLFillType;
// (undocumented)
type: 'fill';
}
// @public (undocumented)
export type TLFillType = SetValue<typeof TL_FILL_TYPES>;
// @public (undocumented)
export interface TLFontStyle extends TLBaseStyle {
// (undocumented)
id: TLFontType;
// (undocumented)
type: 'font';
}
// @public (undocumented)
export type TLFontType = SetValue<typeof TL_FONT_TYPES>;
// @public (undocumented)
export type TLFrameShape = TLBaseShape<'frame', TLFrameShapeProps>;
// @public (undocumented)
export type TLGeoShape = TLBaseShape<'geo', TLGeoShapeProps>;
// @public (undocumented)
export interface TLGeoStyle extends TLBaseStyle {
// (undocumented)
id: TLGeoType;
// (undocumented)
type: 'geo';
}
// @public (undocumented)
export type TLGeoType = SetValue<typeof TL_GEO_TYPES>;
// @public (undocumented)
export type TLGroupShape = TLBaseShape<'group', TLGroupShapeProps>;
// @public
export interface TLHandle {
// (undocumented)
canBind?: boolean;
id: string;
// (undocumented)
index: string;
// (undocumented)
type: TLHandleType;
// (undocumented)
x: number;
// (undocumented)
y: number;
}
// @public
export type TLHandleType = SetValue<typeof TL_HANDLE_TYPES>;
// @public (undocumented)
export type TLHighlightShape = TLBaseShape<'highlight', TLHighlightShapeProps>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLIconShape = TLBaseShape<'icon', TLIconShapeProps>;
// @public (undocumented)
export interface TLIconStyle extends TLBaseStyle {
// (undocumented)
id: TLIconType;
// (undocumented)
type: 'icon';
}
// @public (undocumented)
export type TLIconType = SetValue<typeof TL_ICON_TYPES>;
// @public
2023-04-25 11:01:25 +00:00
export type TLImageAsset = TLBaseAsset<'image', {
w: number;
h: number;
name: string;
isAnimated: boolean;
mimeType: null | string;
src: null | string;
}>;
// @public (undocumented)
export type TLImageCrop = {
topLeft: Vec2dModel;
bottomRight: Vec2dModel;
};
// @public (undocumented)
export type TLImageShape = TLBaseShape<'image', TLImageShapeProps>;
// @public (undocumented)
export type TLImageShapeProps = {
url: string;
playing: boolean;
w: number;
h: number;
assetId: null | TLAssetId;
crop: null | TLImageCrop;
};
// @public
export interface TLInstance extends BaseRecord<'instance', TLInstanceId> {
2023-04-25 11:01:25 +00:00
// (undocumented)
brush: Box2dModel | null;
// (undocumented)
currentPageId: TLPageId;
// (undocumented)
cursor: TLCursor;
// (undocumented)
exportBackground: boolean;
// (undocumented)
followingUserId: null | string;
2023-04-25 11:01:25 +00:00
// (undocumented)
isDebugMode: boolean;
// (undocumented)
isFocusMode: boolean;
// (undocumented)
Independent instance state persistence (#1493) This PR - Removes UserDocumentRecordType - moving isSnapMode to user preferences - moving isGridMode and isPenMode to InstanceRecordType - deleting the other properties which are no longer needed. - Creates a separate pipeline for persisting instance state. Previously the instance state records were stored alongside the document state records, and in order to load the state for a particular instance (in our case, a particular tab) you needed to pass the 'instanceId' prop. This prop ended up totally pervading the public API and people ran into all kinds of issues with it, e.g. using the same instance id in multiple editor instances. There was also an issue whereby it was hard for us to clean up old instance state so the idb table ended up bloating over time. This PR makes it so that rather than passing an instanceId, you load the instance state yourself while creating the store. It provides tools to make that easy. - Undoes the assumption that we might have more than one instance's state in the store. - Like `document`, `instance` now has a singleton id `instance:instance`. - Page state ids and camera ids are no longer random, but rather derive from the page they belong to. This is like having a foreign primary key in SQL databases. It's something i'd love to support fully as part of the RecordType/Store api. Tests to do - [x] Test Migrations - [x] Test Store.listen filtering - [x] Make type sets in Store public and readonly - [x] Test RecordType.createId - [x] Test Instance state snapshot loading/exporting - [x] Manual test File I/O - [x] Manual test Vscode extension with multiple tabs - [x] Audit usages of store.query - [x] Audit usages of changed types: InstanceRecordType, 'instance', InstancePageStateRecordType, 'instance_page_state', 'user_document', 'camera', CameraRecordType, InstancePresenceRecordType, 'instance_presence' - [x] Test user preferences - [x] Manual test isSnapMode and isGridMode and isPenMode - [ ] Test indexedDb functions - [x] Add instanceId stuff back ### Change Type - [x] `major` — Breaking Change ### Test Plan 1. Add a step-by-step description of how to test your PR here. 2. - [ ] Unit Tests - [ ] Webdriver tests ### Release Notes - Add a brief release note for your PR here.
2023-06-05 14:11:07 +00:00
isGridMode: boolean;
// (undocumented)
isPenMode: boolean;
// (undocumented)
2023-04-25 11:01:25 +00:00
isToolLocked: boolean;
// (undocumented)
opacityForNextShape: TLOpacityType;
// (undocumented)
2023-04-25 11:01:25 +00:00
propsForNextShape: TLInstancePropsForNextShape;
// (undocumented)
screenBounds: Box2dModel;
// (undocumented)
scribble: null | TLScribble;
// (undocumented)
zoomBrush: Box2dModel | null;
}
Independent instance state persistence (#1493) This PR - Removes UserDocumentRecordType - moving isSnapMode to user preferences - moving isGridMode and isPenMode to InstanceRecordType - deleting the other properties which are no longer needed. - Creates a separate pipeline for persisting instance state. Previously the instance state records were stored alongside the document state records, and in order to load the state for a particular instance (in our case, a particular tab) you needed to pass the 'instanceId' prop. This prop ended up totally pervading the public API and people ran into all kinds of issues with it, e.g. using the same instance id in multiple editor instances. There was also an issue whereby it was hard for us to clean up old instance state so the idb table ended up bloating over time. This PR makes it so that rather than passing an instanceId, you load the instance state yourself while creating the store. It provides tools to make that easy. - Undoes the assumption that we might have more than one instance's state in the store. - Like `document`, `instance` now has a singleton id `instance:instance`. - Page state ids and camera ids are no longer random, but rather derive from the page they belong to. This is like having a foreign primary key in SQL databases. It's something i'd love to support fully as part of the RecordType/Store api. Tests to do - [x] Test Migrations - [x] Test Store.listen filtering - [x] Make type sets in Store public and readonly - [x] Test RecordType.createId - [x] Test Instance state snapshot loading/exporting - [x] Manual test File I/O - [x] Manual test Vscode extension with multiple tabs - [x] Audit usages of store.query - [x] Audit usages of changed types: InstanceRecordType, 'instance', InstancePageStateRecordType, 'instance_page_state', 'user_document', 'camera', CameraRecordType, InstancePresenceRecordType, 'instance_presence' - [x] Test user preferences - [x] Manual test isSnapMode and isGridMode and isPenMode - [ ] Test indexedDb functions - [x] Add instanceId stuff back ### Change Type - [x] `major` — Breaking Change ### Test Plan 1. Add a step-by-step description of how to test your PR here. 2. - [ ] Unit Tests - [ ] Webdriver tests ### Release Notes - Add a brief release note for your PR here.
2023-06-05 14:11:07 +00:00
// @public (undocumented)
export const TLINSTANCE_ID: TLInstanceId;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLInstanceId = RecordId<TLInstance>;
2023-04-25 11:01:25 +00:00
// @public
export interface TLInstancePageState extends BaseRecord<'instance_page_state', TLInstancePageStateId> {
2023-04-25 11:01:25 +00:00
// (undocumented)
croppingId: null | TLShapeId;
// (undocumented)
editingId: null | TLShapeId;
// (undocumented)
erasingIds: TLShapeId[];
// (undocumented)
focusLayerId: null | TLShapeId;
// (undocumented)
hintingIds: TLShapeId[];
// (undocumented)
hoveredId: null | TLShapeId;
// (undocumented)
pageId: RecordId<TLPage>;
2023-04-25 11:01:25 +00:00
// (undocumented)
selectedIds: TLShapeId[];
}
derived presence state (#1204) This PR adds - A new `TLInstancePresence` record type, to collect info about the presence state in a particular instance of the editor. This will eventually be used to sync presence data instead of sending instance-only state across the wire. - **Record Scopes** `RecordType` now has a `scope` property which can be one of three things: - `document`: the record belongs to the document and should be synced and persisted freely. Currently: `TLDocument`, `TLPage`, `TLShape`, and `TLAsset` - `instance`: the record belongs to a single instance of the store and should not be synced at all. It should not be persisted directly in most cases, but rather compiled into a kind of 'instance configuration' to store alongside the local document data so that when reopening the associated document it can remember some of the previous instance state. Currently: `TLInstance`, `TLInstancePageState`, `TLCamera`, `TLUser`, `TLUserDocument`, `TLUserPresence` - `presence`: the record belongs to a single instance of the store and should not be persisted, but may be synced using the special presence sync protocol. Currently just `TLInstancePresence` This sets us up for the following changes, which are gonna be pretty high-impact in terms of integrating tldraw into existing systems: - Removing `instanceId` as a config option. Each instance gets a randomly generated ID. - We'd replace it with an `instanceConfig` option that has stuff like selectedIds, camera positions, and so on. Then it's up to library users to get and reinstate the instance config at persistence boundaries. - Removing `userId` as config option, and removing the `TLUser` type altogether. - We might need to revisit when doing auth-enabled features like locking shapes, but I suspect that will be separate.
2023-04-27 18:03:19 +00:00
// @public (undocumented)
export interface TLInstancePresence extends BaseRecord<'instance_presence', TLInstancePresenceID> {
derived presence state (#1204) This PR adds - A new `TLInstancePresence` record type, to collect info about the presence state in a particular instance of the editor. This will eventually be used to sync presence data instead of sending instance-only state across the wire. - **Record Scopes** `RecordType` now has a `scope` property which can be one of three things: - `document`: the record belongs to the document and should be synced and persisted freely. Currently: `TLDocument`, `TLPage`, `TLShape`, and `TLAsset` - `instance`: the record belongs to a single instance of the store and should not be synced at all. It should not be persisted directly in most cases, but rather compiled into a kind of 'instance configuration' to store alongside the local document data so that when reopening the associated document it can remember some of the previous instance state. Currently: `TLInstance`, `TLInstancePageState`, `TLCamera`, `TLUser`, `TLUserDocument`, `TLUserPresence` - `presence`: the record belongs to a single instance of the store and should not be persisted, but may be synced using the special presence sync protocol. Currently just `TLInstancePresence` This sets us up for the following changes, which are gonna be pretty high-impact in terms of integrating tldraw into existing systems: - Removing `instanceId` as a config option. Each instance gets a randomly generated ID. - We'd replace it with an `instanceConfig` option that has stuff like selectedIds, camera positions, and so on. Then it's up to library users to get and reinstate the instance config at persistence boundaries. - Removing `userId` as config option, and removing the `TLUser` type altogether. - We might need to revisit when doing auth-enabled features like locking shapes, but I suspect that will be separate.
2023-04-27 18:03:19 +00:00
// (undocumented)
brush: Box2dModel | null;
// (undocumented)
camera: {
x: number;
y: number;
z: number;
};
// (undocumented)
color: string;
// (undocumented)
currentPageId: TLPageId;
// (undocumented)
cursor: {
x: number;
y: number;
type: TLCursor['type'];
rotation: number;
};
// (undocumented)
followingUserId: null | string;
derived presence state (#1204) This PR adds - A new `TLInstancePresence` record type, to collect info about the presence state in a particular instance of the editor. This will eventually be used to sync presence data instead of sending instance-only state across the wire. - **Record Scopes** `RecordType` now has a `scope` property which can be one of three things: - `document`: the record belongs to the document and should be synced and persisted freely. Currently: `TLDocument`, `TLPage`, `TLShape`, and `TLAsset` - `instance`: the record belongs to a single instance of the store and should not be synced at all. It should not be persisted directly in most cases, but rather compiled into a kind of 'instance configuration' to store alongside the local document data so that when reopening the associated document it can remember some of the previous instance state. Currently: `TLInstance`, `TLInstancePageState`, `TLCamera`, `TLUser`, `TLUserDocument`, `TLUserPresence` - `presence`: the record belongs to a single instance of the store and should not be persisted, but may be synced using the special presence sync protocol. Currently just `TLInstancePresence` This sets us up for the following changes, which are gonna be pretty high-impact in terms of integrating tldraw into existing systems: - Removing `instanceId` as a config option. Each instance gets a randomly generated ID. - We'd replace it with an `instanceConfig` option that has stuff like selectedIds, camera positions, and so on. Then it's up to library users to get and reinstate the instance config at persistence boundaries. - Removing `userId` as config option, and removing the `TLUser` type altogether. - We might need to revisit when doing auth-enabled features like locking shapes, but I suspect that will be separate.
2023-04-27 18:03:19 +00:00
// (undocumented)
lastActivityTimestamp: number;
// (undocumented)
screenBounds: Box2dModel;
// (undocumented)
scribble: null | TLScribble;
// (undocumented)
selectedIds: TLShapeId[];
// (undocumented)
userId: string;
derived presence state (#1204) This PR adds - A new `TLInstancePresence` record type, to collect info about the presence state in a particular instance of the editor. This will eventually be used to sync presence data instead of sending instance-only state across the wire. - **Record Scopes** `RecordType` now has a `scope` property which can be one of three things: - `document`: the record belongs to the document and should be synced and persisted freely. Currently: `TLDocument`, `TLPage`, `TLShape`, and `TLAsset` - `instance`: the record belongs to a single instance of the store and should not be synced at all. It should not be persisted directly in most cases, but rather compiled into a kind of 'instance configuration' to store alongside the local document data so that when reopening the associated document it can remember some of the previous instance state. Currently: `TLInstance`, `TLInstancePageState`, `TLCamera`, `TLUser`, `TLUserDocument`, `TLUserPresence` - `presence`: the record belongs to a single instance of the store and should not be persisted, but may be synced using the special presence sync protocol. Currently just `TLInstancePresence` This sets us up for the following changes, which are gonna be pretty high-impact in terms of integrating tldraw into existing systems: - Removing `instanceId` as a config option. Each instance gets a randomly generated ID. - We'd replace it with an `instanceConfig` option that has stuff like selectedIds, camera positions, and so on. Then it's up to library users to get and reinstate the instance config at persistence boundaries. - Removing `userId` as config option, and removing the `TLUser` type altogether. - We might need to revisit when doing auth-enabled features like locking shapes, but I suspect that will be separate.
2023-04-27 18:03:19 +00:00
// (undocumented)
userName: string;
}
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLInstancePropsForNextShape = Pick<TLShapeProps, TLStyleType>;
// @public (undocumented)
export type TLLanguage = (typeof LANGUAGES)[number];
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLLineShape = TLBaseShape<'line', TLLineShapeProps>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLNoteShape = TLBaseShape<'note', TLNoteShapeProps>;
// @public (undocumented)
export type TLNullableShapeProps = {
[K in TLShapeProp]?: null | TLShapeProps[K];
};
// @public (undocumented)
export type TLOpacityType = number;
2023-04-25 11:01:25 +00:00
// @public
export interface TLPage extends BaseRecord<'page', TLPageId> {
2023-04-25 11:01:25 +00:00
// (undocumented)
index: string;
// (undocumented)
name: string;
}
// @public (undocumented)
export type TLPageId = RecordId<TLPage>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLParentId = TLPageId | TLShapeId;
// @public (undocumented)
export const TLPOINTER_ID: TLPointerId;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
Independent instance state persistence (#1493) This PR - Removes UserDocumentRecordType - moving isSnapMode to user preferences - moving isGridMode and isPenMode to InstanceRecordType - deleting the other properties which are no longer needed. - Creates a separate pipeline for persisting instance state. Previously the instance state records were stored alongside the document state records, and in order to load the state for a particular instance (in our case, a particular tab) you needed to pass the 'instanceId' prop. This prop ended up totally pervading the public API and people ran into all kinds of issues with it, e.g. using the same instance id in multiple editor instances. There was also an issue whereby it was hard for us to clean up old instance state so the idb table ended up bloating over time. This PR makes it so that rather than passing an instanceId, you load the instance state yourself while creating the store. It provides tools to make that easy. - Undoes the assumption that we might have more than one instance's state in the store. - Like `document`, `instance` now has a singleton id `instance:instance`. - Page state ids and camera ids are no longer random, but rather derive from the page they belong to. This is like having a foreign primary key in SQL databases. It's something i'd love to support fully as part of the RecordType/Store api. Tests to do - [x] Test Migrations - [x] Test Store.listen filtering - [x] Make type sets in Store public and readonly - [x] Test RecordType.createId - [x] Test Instance state snapshot loading/exporting - [x] Manual test File I/O - [x] Manual test Vscode extension with multiple tabs - [x] Audit usages of store.query - [x] Audit usages of changed types: InstanceRecordType, 'instance', InstancePageStateRecordType, 'instance_page_state', 'user_document', 'camera', CameraRecordType, InstancePresenceRecordType, 'instance_presence' - [x] Test user preferences - [x] Manual test isSnapMode and isGridMode and isPenMode - [ ] Test indexedDb functions - [x] Add instanceId stuff back ### Change Type - [x] `major` — Breaking Change ### Test Plan 1. Add a step-by-step description of how to test your PR here. 2. - [ ] Unit Tests - [ ] Webdriver tests ### Release Notes - Add a brief release note for your PR here.
2023-06-05 14:11:07 +00:00
export type TLRecord = TLAsset | TLCamera | TLDocument | TLInstance | TLInstancePageState | TLInstancePresence | TLPage | TLPointer | TLShape;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLSchema = StoreSchema<TLRecord, TLStoreProps>;
// @public
2023-04-25 11:01:25 +00:00
export type TLScribble = {
points: Vec2dModel[];
size: number;
color: TLCanvasUiColor;
2023-04-25 11:01:25 +00:00
opacity: number;
state: SetValue<typeof TL_SCRIBBLE_STATES>;
delay: number;
2023-04-25 11:01:25 +00:00
};
// @public
export type TLShape = TLDefaultShape | TLUnknownShape;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLShapeId = RecordId<TLUnknownShape>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLShapePartial<T extends TLShape = TLShape> = T extends T ? {
id: TLShapeId;
type: T['type'];
props?: Partial<T['props']>;
} & Partial<Omit<T, 'id' | 'props' | 'type'>> : never;
// @public (undocumented)
export type TLShapeProp = keyof TLShapeProps;
// @public (undocumented)
export type TLShapeProps = Identity<UnionToIntersection<TLDefaultShape['props']>>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export interface TLSizeStyle extends TLBaseStyle {
// (undocumented)
id: TLSizeType;
// (undocumented)
type: 'size';
}
// @public (undocumented)
export type TLSizeType = SetValue<typeof TL_SIZE_TYPES>;
// @public (undocumented)
export interface TLSplineStyle extends TLBaseStyle {
2023-04-25 11:01:25 +00:00
// (undocumented)
id: TLSplineType;
// (undocumented)
type: 'spline';
}
// @public (undocumented)
export type TLSplineType = SetValue<typeof TL_SPLINE_TYPES>;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLStore = Store<TLRecord, TLStoreProps>;
// @public (undocumented)
export type TLStoreProps = {
Add support for project names (#1340) This PR adds some things that we need for the Project Name feature on tldraw.com. It should be reviewed alongside https://github.com/tldraw/tldraw-lite/pull/1814 ## Name Property This PR adds a `name` property to `TLDocument`. We use this to store a project's name. <img width="454" alt="Screenshot 2023-05-09 at 15 47 26" src="https://github.com/tldraw/tldraw/assets/15892272/f3be438e-aa0f-4dec-8f51-8dfd9f9d0ced"> ## Top Zone This PR adds a `topZone` area of the UI that we can add stuff to, similar to how `shareZone` works. It also adds an example to show where the `topZone` and `shareZone` are: <img width="1511" alt="Screenshot 2023-05-12 at 10 57 40" src="https://github.com/tldraw/tldraw/assets/15892272/f5e1cd33-017e-4aaf-bfee-4d85119e2974"> ## Breakpoints This PR change's the UI's breakpoints a little bit. It moves the action bar to the bottom a little bit earlier. (This gives us more space at the top for the project name). ![2023-05-12 at 11 08 26 - Fuchsia Bison](https://github.com/tldraw/tldraw/assets/15892272/34563cea-b1d1-47be-ac5e-5650ee0ba02d) ![2023-05-12 at 13 45 04 - Tan Mole](https://github.com/tldraw/tldraw/assets/15892272/ab190bd3-51d4-4a8b-88de-c72ab14bcba6) ## Input Blur This PR adds an `onBlur` parameter to `Input`. This was needed because 'clicking off' the input wasn't firing `onComplete` or `onCancel`. <img width="620" alt="Screenshot 2023-05-09 at 16 12 58" src="https://github.com/tldraw/tldraw/assets/15892272/3b28da74-0a74-4063-8053-e59e47027caf"> ## Create Project Name This PR adds an internal `createProjectName` property to `TldrawEditorConfig`. Similar to `derivePresenceState`, you can pass a custom function to it. It lets you control what gets used as the default project name. We use it to set different names in our local projects compared to shared projects. In the future, when we add more advanced project features, we could handle this better within the UI. <img width="454" alt="Screenshot 2023-05-09 at 15 47 26" src="https://github.com/tldraw/tldraw/assets/15892272/da9a4699-ac32-40d9-a97c-6c682acfac41"> ### Test Plan 1. Gradually reduce the width of the browser window. 2. Check that the actions menu jumps to the bottom before the style panel moves to the bottom. --- 1. In the examples app, open the `/zones` example. 2. Check that there's a 'top zone' at the top. - [ ] Unit Tests - [ ] Webdriver tests ### Release Note - [dev] Added a `topZone` area where you can put stuff. - [dev] Added a `name` property to `TLDocument` - and `app` methods for it. - [dev] Added an internal `createProjectName` config property for controlling the default project name. - [dev] Added an `onBlur` parameter to `Input`. - Moved the actions bar to the bottom on medium-sized screens. --------- Co-authored-by: Steve Ruiz <steveruizok@gmail.com>
2023-06-01 18:46:26 +00:00
defaultName: string;
2023-04-25 11:01:25 +00:00
};
// @public (undocumented)
export type TLStoreSchema = StoreSchema<TLRecord, TLStoreProps>;
// @public (undocumented)
export type TLStoreSnapshot = StoreSnapshot<TLRecord>;
// @public (undocumented)
export interface TLStyleCollections {
// (undocumented)
align: TLAlignStyle[];
// (undocumented)
arrowheadEnd: TLArrowheadEndStyle[];
// (undocumented)
arrowheadStart: TLArrowheadStartStyle[];
// (undocumented)
color: TLColorStyle[];
// (undocumented)
dash: TLDashStyle[];
// (undocumented)
fill: TLFillStyle[];
// (undocumented)
font: TLFontStyle[];
// (undocumented)
geo: TLGeoStyle[];
// (undocumented)
size: TLSizeStyle[];
// (undocumented)
spline: TLSplineStyle[];
// (undocumented)
verticalAlign: TLVerticalAlignStyle[];
2023-04-25 11:01:25 +00:00
}
// @public (undocumented)
export type TLStyleItem = TLAlignStyle | TLArrowheadEndStyle | TLArrowheadStartStyle | TLColorStyle | TLDashStyle | TLFillStyle | TLFontStyle | TLGeoStyle | TLSizeStyle | TLSplineStyle | TLVerticalAlignStyle;
2023-04-25 11:01:25 +00:00
// @public (undocumented)
export type TLStyleProps = Pick<TLShapeProps, TLStyleType>;
// @public (undocumented)
export type TLStyleType = SetValue<typeof TL_STYLE_TYPES>;
// @public (undocumented)
export type TLTextShape = TLBaseShape<'text', TLTextShapeProps>;
// @public (undocumented)
export type TLTextShapeProps = {
color: TLColorType;
size: TLSizeType;
font: TLFontType;
align: TLAlignType;
w: number;
text: string;
scale: number;
autoSize: boolean;
};
// @public
2023-04-25 11:01:25 +00:00
export type TLUnknownShape = TLBaseShape<string, object>;
// @public (undocumented)
export type TLVerticalAlignType = SetValue<typeof TL_VERTICAL_ALIGN_TYPES>;
// @public
2023-04-25 11:01:25 +00:00
export type TLVideoAsset = TLBaseAsset<'video', {
w: number;
h: number;
name: string;
isAnimated: boolean;
mimeType: null | string;
src: null | string;
}>;
// @public (undocumented)
export type TLVideoShape = TLBaseShape<'video', TLVideoShapeProps>;
// @public
2023-04-25 11:01:25 +00:00
export interface Vec2dModel {
// (undocumented)
x: number;
// (undocumented)
y: number;
// (undocumented)
z?: number;
}
// @internal (undocumented)
export const verticalAlignValidator: T.Validator<"end" | "middle" | "start">;
2023-04-25 11:01:25 +00:00
// @internal (undocumented)
export const videoShapeMigrations: Migrations;
// @internal (undocumented)
export const videoShapeProps: ShapeProps<TLVideoShape>;
2023-04-25 11:01:25 +00:00
// (No @packageDocumentation comment for this package)
```