[docs] design shuffle (#2951)
This PR incorporates design tweaks from #2922 without the home page or content changes. These are: - Replacing all `hello@tldraw.com` with `sales@tldraw.com` - Fix mailto links. - Showing the first item in a section on direct routes to the section - Splitting the article page for human-written content from article page for generated content - Splitting the layout for the landing page from the rest of the site (temporarily identical to the regular content) - Removing headings from left sidebar - Restoring headings in right sidebar for human-written pages with > 1 heading link - Styling block quote - Adjusting section link appearance / layout in header / menu - Changing the order of search results to preference docs over examples - Updating copy on events - Removing copy on user interface menus - Adding hero as prop to all articles - Updated icon - Fixing a few broken links - Replaces the sandpack code blocks with hljs code blocks, except in examples. ### Change Type - [x] `documentation` — Changes to the documentation only[^2]
This commit is contained in:
Steve Ruiz
GitHub
parent
3f5803729d
commit
9a6f4e8c4b
47 changed files with 1587 additions and 1299 deletions
|
|
@ -9,14 +9,14 @@
|
|||
{
|
||||
"id": "tldraw",
|
||||
"name": "tldraw",
|
||||
"email": "hello@tldraw.com",
|
||||
"email": "sales@tldraw.com",
|
||||
"twitter": "tldraw",
|
||||
"image": "tldraw.jpg"
|
||||
},
|
||||
{
|
||||
"id": "api",
|
||||
"name": "API",
|
||||
"email": "hello@tldraw.com",
|
||||
"email": "sales@tldraw.com",
|
||||
"twitter": "tldraw",
|
||||
"image": "api.jpg"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ tldraw uses a dual licensing model to support the development of the project.
|
|||
|
||||
The project's source code, libraries, and distributions are provided under the [tldraw licence](https://github.com/tldraw/tldraw/blob/master/LICENSE.md).
|
||||
|
||||
This license does not permit commercial use. If you wish to use this project in commercial product or enterprise, you need to purchase a commercial license.
|
||||
This license does not permit commercial use. If you wish to use this project in a commercial product or enterprise, you need to purchase a commercial license.
|
||||
|
||||
To purchase a commercial license, or for more information, please contact us at [sales@tldraw.com](mailto:sales@tldraw.com).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: User Interface
|
||||
title: User interface
|
||||
status: published
|
||||
author: steveruizok
|
||||
date: 3/22/2023
|
||||
|
|
@ -39,6 +39,27 @@ All of our user interface works by controlling the editor via its `Editor` metho
|
|||
|
||||
The source for these examples are available in the [tldraw repository](https://github.com/tldraw/tldraw/blob/main/apps/examples/src) or in a [sandbox here](https://stackblitz.com/github/tldraw/tldraw/tree/examples?file=src%2Findex.tsx).
|
||||
|
||||
## Events
|
||||
|
||||
The [Tldraw](?) component has a prop, `onUiEvent`, that the user interface will call when certain events occur.
|
||||
|
||||
```tsx
|
||||
function Example() {
|
||||
function handleEvent(name, data) {
|
||||
// do something with the event
|
||||
}
|
||||
|
||||
return <Tldraw onUiEvent={handleEvent} />
|
||||
}
|
||||
```
|
||||
|
||||
The `onUiEvent` callback is called with the name of the event as a string and an object with information about the event's source (e.g. `menu` or `context-menu`) and possibly other data specific to each event, such as the direction in an `align-shapes` event.
|
||||
|
||||
Note that `onUiEvent` is only called when interacting with the user interface. It is not called when running commands manually against the app, e.g. calling [Editor#alignShapes](?) will not call `onUiEvent`.
|
||||
|
||||
See the [tldraw repository](https://github.com/tldraw/tldraw/tree/main/apps/examples) for an example of how to customize tldraw's user interface.
|
||||
|
||||
|
||||
## Overrides
|
||||
|
||||
The content of tldraw's menus can be controlled via the `overrides` prop. This prop accepts a [TLUiOverrides](/reference/tldraw/TLUiOverrides) object, which has methods for each part of the user interface, such as the `toolbar` or `keyboardShortcutsMenu`.
|
||||
|
|
@ -99,70 +120,6 @@ const myOverrides: TLUiOverrides = {
|
|||
|
||||
The `tools` object is a map of [TLUiToolItem](/reference/tldraw/TLUiToolItem)s, with each item keyed under its `id`.
|
||||
|
||||
### Toolbar and Menus
|
||||
|
||||
The remaining overrides are for toolbar and the various menus: the main menu, actions menu, context menu, help menu, and the keyboard shortcuts menu.
|
||||
|
||||
Each of these overrides accepts a method that receives the default menu schema and returns a mutated version of that schema.
|
||||
|
||||
```ts
|
||||
const myOverrides: TLUiOverrides = {
|
||||
actions(editor, actions) {
|
||||
// Create a new action or replace an existing one
|
||||
actions['my-new-action'] = {
|
||||
id: 'my-new-action',
|
||||
label: 'My new action',
|
||||
readonlyOk: true,
|
||||
kbd: '$u',
|
||||
onSelect(source: any) {
|
||||
window.alert('My new action just happened!')
|
||||
},
|
||||
}
|
||||
return actions
|
||||
},
|
||||
contextMenu(editor, contextMenu, { actions }) {
|
||||
const newMenuItem = menuItem(actions['my-new-action'])
|
||||
const newMenuGroup = menuGroup('my-items', newMenuItem)
|
||||
contextMenu.unshift(newMenuItem)
|
||||
return contextMenu
|
||||
},
|
||||
menu(editor, menu, { actions }) {
|
||||
// using the findMenuItem helper
|
||||
const fileMenu = findMenuItem(menu, ['menu', 'file'])
|
||||
if (fileMenu.type === 'submenu') {
|
||||
// add the new item to the file menu's children
|
||||
const newMenuItem = menuItem(actions['my-new-action'])
|
||||
fileMenu.children.unshift(newMenuItem)
|
||||
}
|
||||
return menu
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
A menu schema is an array of either [submenus](/reference/tldraw/TLUiSubMenu), [groups](/reference/tldraw/TLUiMenuGroup), [items](/reference/tldraw/TLUiMenuItem), or [custom items](/reference/tldraw/TLUiCustomMenuItem). Each group or submenu may include any of the other types as its children.
|
||||
|
||||
The menu schema is stateful. Referencing atomic properties (such as computed values in the editor) will cause the menu to update when those values change. If you wish for a menu item to disappear from the menu, you can return `null` from the menu method. You can also provide additional options for each item, `disabled` or `checked`.
|
||||
|
||||
```ts
|
||||
const myOverrides: TLUiOverrides = {
|
||||
menu(editor, menu, { actions }) {
|
||||
const selectedShapes = editor.getSelectedShapeIds().length
|
||||
|
||||
const newMenuGroup = menuGroup(
|
||||
'my-actions',
|
||||
selectedShapes > 0 ? menuItem(actions['action-a']) : null,
|
||||
menuItem(actions['action-b'], { disabled: selectedShapes < 3 })
|
||||
)
|
||||
|
||||
menu.unshift(newMenuGroup)
|
||||
|
||||
return menu
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
It's recommmended to explore the [default menu schema](https://github.com/tldraw/tldraw/blob/main/packages/tldraw/src/lib/ui/hooks/useMenuSchema.tsx) in order to understand how menu items work.
|
||||
|
||||
### Translations
|
||||
|
||||
The `translations` method accepts a table of new translations. For example, if you wanted a tool to reference a key `"tools.card"`, then you should at minimum provide an english translation for this key.
|
||||
|
|
@ -176,23 +133,3 @@ const myOverrides: TLUiOverrides = {
|
|||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Events
|
||||
|
||||
The [Tldraw](?) component has a prop, `onUiEvent`, that the user interface will call when certain events occur.
|
||||
|
||||
```tsx
|
||||
function Example() {
|
||||
function handleEvent(name, data) {
|
||||
// do something with the event
|
||||
}
|
||||
|
||||
return <Tldraw onUiEvent={handleEvent} />
|
||||
}
|
||||
```
|
||||
|
||||
The `onUiEvent` callback is called with the name of the event as a string and an object with information about the event's source (e.g. `menu` or `context-menu`) and possibly other data specific to each event, such as the direction in an `align-shapes` event.
|
||||
|
||||
Note that `onUiEvent` is only called when interacting with the user interface. It is not called when running commands manually against the app, e.g. calling [Editor#alignShapes](?) will not call `onUiEvent`.
|
||||
|
||||
See the [tldraw repository](https://github.com/tldraw/tldraw/tree/main/apps/examples) for an example of how to customize tldraw's user interface.
|
||||
|
|
|
|||
|
|
@ -12,71 +12,64 @@ The tldraw SDK provides a really simple way to craft infinite canvas experiences
|
|||
|
||||
By the end of this guide you will have made something that looks like this:
|
||||
|
||||
<Embed className="article__embed--quickstart" src="https://vite-template-five.vercel.app/" />
|
||||
<Embed className="article__embed--quickstart" src="https://examples.tldraw.com/develop" />
|
||||
|
||||
### 1. Installation
|
||||
|
||||
<hr />
|
||||
<ol className="ordered-list__quickstart">
|
||||
<li>
|
||||
### Installation
|
||||
- Set up a React project however you normally do. [We recommend Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).
|
||||
- Install the tldraw library using this command:
|
||||
|
||||
- Set up a React project however you normally do. [We recommend Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).
|
||||
- Install the tldraw library using this command:
|
||||
|
||||
```bash
|
||||
npm install tldraw@beta
|
||||
```
|
||||
</li>
|
||||
<li>
|
||||
### Import Styles
|
||||
<br />
|
||||
To import fonts and CSS for tldraw:
|
||||
```bash
|
||||
npm install @tldraw/tldraw@beta
|
||||
```
|
||||
|
||||
- Create or edit a css file called `index.css`
|
||||
- Copy and paste this into the file:
|
||||
```CSS
|
||||
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&family=Roboto+Mono:wght@400;700&display=swap");
|
||||
@import url("tldraw/tldraw.css");
|
||||
### 2. Import Styles
|
||||
|
||||
body {
|
||||
font-family: "Inter";
|
||||
}
|
||||
```
|
||||
</li>
|
||||
<li>
|
||||
### Render Tldraw Component
|
||||
<br />
|
||||
To render the Tldraw component
|
||||
To import fonts and CSS for tldraw:
|
||||
|
||||
- Import the `<Tldraw />` component from `tldraw`
|
||||
- Import the `index.css` CSS file from earlier
|
||||
- Wrap the Tldraw component in a `<div>` element with the style attribute set to: `{ position: 'fixed', inset: 0 }`
|
||||
|
||||
<p className="">This will render a full screen canvas:</p>
|
||||
- Create or edit a css file called `index.css`
|
||||
- Copy and paste this into the file:
|
||||
|
||||
```javascript
|
||||
import { Tldraw } from "tldraw";
|
||||
import "./index.css";
|
||||
```CSS
|
||||
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@500;700;&display=swap");
|
||||
@import url("@tldraw/tldraw/tldraw.css");
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<div style={{ position: 'fixed', inset: 0 }}>
|
||||
<Tldraw />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
</li>
|
||||
</ol>
|
||||
body {
|
||||
font-family: "Inter";
|
||||
}
|
||||
```
|
||||
|
||||
<hr />
|
||||
### 3. Render Tldraw Component
|
||||
|
||||
### Next Steps
|
||||
To render the Tldraw component
|
||||
|
||||
You did it! Now that you have your canvas working, you may be wondering: what next? You can try:
|
||||
- Import the `<Tldraw />` component from `@tldraw/tldraw`
|
||||
- Import the `index.css` CSS file from earlier
|
||||
- Wrap the Tldraw component in a `<div>` element with the style attribute set to: `{ position: 'fixed', inset: 0 }`
|
||||
|
||||
This will render a full screen canvas:
|
||||
|
||||
```javascript
|
||||
import { Tldraw } from "@tldraw/tldraw";
|
||||
import "./index.css";
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<div style={{ position: 'fixed', inset: 0 }}>
|
||||
<Tldraw />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you have your canvas working, you may be wondering: what next?
|
||||
|
||||
You can try:
|
||||
|
||||
- Giving the editor a makeover by [customizing the UI](/docs/user-interface)
|
||||
- Adding your own [shapes](/docs/shapes) and [tools](/docs/tools)
|
||||
- Providing collaboration using [multiplayer](https://github.com/tldraw/tldraw-yjs-example)
|
||||
|
||||
We provide the above examples and more in our [examples section](/examples/basic/develop). Go build something creative and please do share it with us in our [#show-and-tell](https://discord.com/invite/SBBEVCA4PG) channel on Discord!
|
||||
We provide the above examples and more in our [examples section](/examples). Go build something creative and please do share it with us in our [#show-and-tell](https://discord.com/invite/SBBEVCA4PG) channel on Discord!
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
{
|
||||
"id": "docs",
|
||||
"title": "Learn tldraw",
|
||||
"description": "Developer documentation for tldraw.",
|
||||
"description": "Learn to use the tldraw SDK.",
|
||||
"categories": [],
|
||||
"sidebar_behavior": "show-links"
|
||||
},
|
||||
|
|
@ -58,7 +58,8 @@
|
|||
"id": "Namespace",
|
||||
"path": null
|
||||
}
|
||||
]
|
||||
],
|
||||
"hero": null
|
||||
},
|
||||
{
|
||||
"id": "store",
|
||||
|
|
@ -93,7 +94,8 @@
|
|||
"id": "Namespace",
|
||||
"path": null
|
||||
}
|
||||
]
|
||||
],
|
||||
"hero": null
|
||||
},
|
||||
{
|
||||
"id": "tldraw",
|
||||
|
|
@ -128,7 +130,8 @@
|
|||
"id": "Namespace",
|
||||
"path": null
|
||||
}
|
||||
]
|
||||
],
|
||||
"hero": null
|
||||
},
|
||||
{
|
||||
"id": "tlschema",
|
||||
|
|
@ -163,7 +166,8 @@
|
|||
"id": "Namespace",
|
||||
"path": null
|
||||
}
|
||||
]
|
||||
],
|
||||
"hero": null
|
||||
},
|
||||
{
|
||||
"id": "validate",
|
||||
|
|
@ -198,9 +202,11 @@
|
|||
"id": "Namespace",
|
||||
"path": null
|
||||
}
|
||||
]
|
||||
],
|
||||
"hero": null
|
||||
}
|
||||
],
|
||||
"sidebar_behavior": "reference"
|
||||
"sidebar_behavior": "reference",
|
||||
"hero": null
|
||||
}
|
||||
]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue