-
-
Notifications
You must be signed in to change notification settings - Fork 640
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
178 changed files
with
1,898 additions
and
1,609 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,195 +1,14 @@ | ||
| # Turborepo Design System Starter | ||
|
|
||
| This guide explains how to use a React design system starter powered by: | ||
|
|
||
| - 🏎 [Turborepo](https://turborepo.org) — High-performance build system for Monorepos | ||
| - 🚀 [React](https://reactjs.org/) — JavaScript library for user interfaces | ||
| - 🛠 [Tsup](https://github.com/egoist/tsup) — TypeScript bundler powered by esbuild | ||
| - 📖 [Storybook](https://storybook.js.org/) — UI component environment powered by Vite | ||
|
|
||
| As well as a few others tools preconfigured: | ||
|
|
||
| - [TypeScript](https://www.typescriptlang.org/) for static type checking | ||
| - [ESLint](https://eslint.org/) for code linting | ||
| - [Prettier](https://prettier.io) for code formatting | ||
| - [Changesets](https://github.com/changesets/changesets) for managing versioning and changelogs | ||
| - [GitHub Actions](https://github.com/changesets/action) for fully automated package publishing | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Clone the design system example locally or [from GitHub](https://github.com/vercel/turborepo/tree/main/examples/design-system): | ||
|
|
||
| ```bash | ||
| npx degit vercel/turborepo/examples/design-system design-system | ||
| cd design-system | ||
| yarn install | ||
| git init . && git add . && git commit -m "Init" | ||
| ``` | ||
|
|
||
| ### Useful Commands | ||
|
|
||
| - `yarn build` - Build all packages including the Storybook site | ||
| - `yarn dev` - Run all packages locally and preview with Storybook | ||
| - `yarn lint` - Lint all packages | ||
| - `yarn changeset` - Generate a changeset | ||
| - `yarn clean` - Clean up all `node_modules` and `dist` folders (runs each package's clean script) | ||
|
|
||
| ## Turborepo | ||
|
|
||
| [Turborepo](https://turborepo.org) is a high-performance build system for JavaScript and TypeScript codebases. It was designed after the workflows used by massive software engineering organizations to ship code at scale. Turborepo abstracts the complex configuration needed for monorepos and provides fast, incremental builds with zero-configuration remote caching. | ||
|
|
||
| Using Turborepo simplifes managing your design system monorepo, as you can have a single lint, build, test, and release process for all packages. [Learn more](https://vercel.com/blog/monorepos-are-changing-how-teams-build-software) about how monorepos improve your development workflow. | ||
|
|
||
| ## Apps & Packages | ||
|
|
||
| This Turborepo includes the following packages and applications: | ||
|
|
||
| - `apps/docs`: Component documentation site with Storybook | ||
| - `packages/core`: Core library | ||
| - `packages/utilities`: Shared utilities | ||
| - `packages/@dnd-kit/config-ts`: Shared `tsconfig.json`s used throughout the Turborepo | ||
| - `packages/config-eslint`: ESLint preset | ||
|
|
||
| Each package and app is 100% [TypeScript](https://www.typescriptlang.org/). Yarn Workspaces enables us to "hoist" dependencies that are shared between packages to the root `package.json`. This means smaller `node_modules` folders and a better local dev experience. To install a dependency for the entire monorepo, use the `-W` workspaces flag with `yarn add`. | ||
|
|
||
| This example sets up your `.gitignore` to exclude all generated files, other folders like `node_modules` used to store your dependencies. | ||
|
|
||
| ### Compilation | ||
|
|
||
| To make the core library code work across all browsers, we need to compile the raw TypeScript and React code to plain JavaScript. We can accomplish this with `tsup`, which uses `esbuild` to greatly improve performance. | ||
|
|
||
| Running `yarn build` from the root of the Turborepo will run the `build` command defined in each package's `package.json` file. Turborepo runs each `build` in parallel and caches & hashes the output to speed up future builds. | ||
|
|
||
| For `dnd-kit-core`, the `build` command is the following: | ||
|
|
||
| ```bash | ||
| tsup src/index.tsx --format esm,cjs --dts --external react | ||
| ``` | ||
|
|
||
| `tsup` compiles `src/index.tsx`, which exports all of the components in the design system, into both ES Modules and CommonJS formats as well as their TypeScript types. The `package.json` for `dnd-kit-core` then instructs the consumer to select the correct format: | ||
|
|
||
| ```json:dnd-kit-core/package.json | ||
| { | ||
| "name": "@dnd-kit/abstract", | ||
| "version": "0.0.0", | ||
| "main": "./dist/index.js", | ||
| "module": "./dist/index.mjs", | ||
| "types": "./dist/index.d.ts", | ||
| "sideEffects": false, | ||
| } | ||
| ``` | ||
|
|
||
| Run `yarn build` to confirm compilation is working correctly. You should see a folder `dnd-kit-core/dist` which contains the compiled output. | ||
|
|
||
| ```bash | ||
| dnd-kit-core | ||
| └── dist | ||
| ├── index.d.ts <-- Types | ||
| ├── index.js <-- CommonJS version | ||
| └── index.mjs <-- ES Modules version | ||
| ``` | ||
|
|
||
| ## Components | ||
|
|
||
| Each file inside of `dnd-kit-core/src` is a component inside our design system. For example: | ||
|
|
||
| ```tsx:dnd-kit-core/src/Button.tsx | ||
| import * as React from 'react'; | ||
|
|
||
| export interface ButtonProps { | ||
| children: React.ReactNode; | ||
| } | ||
|
|
||
| export function Button(props: ButtonProps) { | ||
| return <button>{props.children}</button>; | ||
| } | ||
|
|
||
| Button.displayName = 'Button'; | ||
| ``` | ||
|
|
||
| When adding a new file, ensure the component is also exported from the entry `index.tsx` file: | ||
|
|
||
| ```tsx:dnd-kit-core/src/index.tsx | ||
| import * as React from "react"; | ||
| export { Button, type ButtonProps } from "./Button"; | ||
| // Add new component exports here | ||
| ``` | ||
|
|
||
| ## Storybook | ||
|
|
||
| Storybook provides us with an interactive UI playground for our components. This allows us to preview our components in the browser and instantly see changes when developing locally. This example preconfigures Storybook to: | ||
|
|
||
| - Use Vite to bundle stories instantly (in milliseconds) | ||
| - Automatically find any stories inside the `stories/` folder | ||
| - Support using module path aliases like `@dnd-kit-core` for imports | ||
| - Write MDX for component documentation pages | ||
|
|
||
| For example, here's the included Story for our `Button` component: | ||
|
|
||
| ```js:apps/docs/stories/button.stories.mdx | ||
| import { Button } from '@dnd-kit-core/src'; | ||
| import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks'; | ||
|
|
||
| <Meta title="Components/Button" component={Button} /> | ||
|
|
||
| # Button | ||
|
|
||
| Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec euismod, nisl eget consectetur tempor, nisl nunc egestas nisi, euismod aliquam nisl nunc euismod. | ||
|
|
||
| ## Props | ||
|
|
||
| <Props of={Box} /> | ||
|
|
||
| ## Examples | ||
|
|
||
| <Preview> | ||
| <Story name="Default"> | ||
| <Button>Hello</Button> | ||
| </Story> | ||
| </Preview> | ||
| ``` | ||
|
|
||
| This example includes a few helpful Storybook scripts: | ||
|
|
||
| - `yarn dev`: Starts Storybook in dev mode with hot reloading at `localhost:6006` | ||
| - `yarn build`: Builds the Storybook UI and generates the static HTML files | ||
| - `yarn preview-storybook`: Starts a local server to view the generated Storybook UI | ||
|
|
||
| ## Versioning & Publishing Packages | ||
|
|
||
| This example uses [Changesets](https://github.com/changesets/changesets) to manage versions, create changelogs, and publish to npm. It's preconfigured so you can start publishing packages immediately. | ||
|
|
||
| You'll need to create an `NPM_TOKEN` and `GITHUB_TOKEN` and add it to your GitHub repository settings to enable access to npm. It's also worth installing the [Changesets bot](https://github.com/apps/changeset-bot) on your repository. | ||
|
|
||
| ### Generating the Changelog | ||
|
|
||
| To generate your changelog, run `yarn changeset` locally: | ||
|
|
||
| 1. **Which packages would you like to include?** – This shows which packages and changed and which have remained the same. By default, no packages are included. Press `space` to select the packages you want to include in the `changeset`. | ||
| 1. **Which packages should have a major bump?** – Press `space` to select the packages you want to bump versions for. | ||
| 1. If doing the first major version, confirm you want to release. | ||
| 1. Write a summary for the changes. | ||
| 1. Confirm the changeset looks as expected. | ||
| 1. A new Markdown file will be created in the `changeset` folder with the summary and a list of the packages included. | ||
|
|
||
| ### Releasing | ||
|
|
||
| When you push your code to GitHub, the [GitHub Action](https://github.com/changesets/action) will run the `release` script defined in the root `package.json`: | ||
|
|
||
| ```bash | ||
| turbo run build --filter=docs^... && changeset publish | ||
| ``` | ||
|
|
||
| Turborepo runs the `build` script for all publishable packages (excluding docs) and publishes the packages to npm. By default, this example includes `dnd-kit` as the npm organization. To change this, do the following: | ||
|
|
||
| - Rename folders in `packages/*` to replace `dnd-kit` with your desired scope | ||
| - Search and replace `dnd-kit` with your desired scope | ||
| - Re-run `yarn install` | ||
|
|
||
| To publish packages to a private npm organization scope, **remove** the following from each of the `package.json`'s | ||
|
|
||
| ```diff | ||
| - "publishConfig": { | ||
| - "access": "public" | ||
| - }, | ||
| ``` | ||
| <p align="center"> | ||
| <a href="https://dndkit.com"> | ||
| <img alt="@dnd-kit – the modern drag & drop toolkit for React" src=".github/assets/dnd-kit-hero-banner.svg"> | ||
| </a> | ||
| </p> | ||
|
|
||
| - **Feature packed:** customizable collision detection algorithms, multiple activators, custom drag feedback, drag handles, auto-scrolling, activation constraints, and so much more. | ||
| - **Framework agnostic:** The `@dnd-kit/abstract` library is meant to work with any framework and in any environment. Currently, DOM and React are the two supported targets, with more to come later. | ||
| - **Supports a wide range of use cases:** lists, grids, multiple containers, nested contexts, variable sized items, virtualized lists, 2D Games, and more. | ||
| - **Built-in support for multiple input methods:** Pointer, mouse, touch and keyboard sensors. | ||
| - **Fully customizable & extensible:** Customize every detail: animations, transitions, behaviours, styles. Build your own sensors, collision detection algorithms, customize key bindings and much more. | ||
| - **Accessibility:** Keyboard support, sensible default aria attributes, customizable screen reader instructions and live regions built-in. | ||
| - **Performance:** It was built with performance in mind in order to support silky smooth animations. | ||
| - **Presets:** Need to build a sortable interface? Check out `@dnd-kit/dom/sortable`, which is a thin layer built on top of `@dnd-kit/dom`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| import type {Meta, StoryObj} from '@storybook/react'; | ||
| import {pointerIntersection} from '@dnd-kit/collision'; | ||
|
|
||
| import {SortableExample} from '../SortableExample'; | ||
|
|
||
| const meta: Meta<typeof SortableExample> = { | ||
| title: 'React/Sortable/Grid', | ||
| component: SortableExample, | ||
| }; | ||
|
|
||
| export default meta; | ||
| type Story = StoryObj<typeof SortableExample>; | ||
|
|
||
| const defaultArgs = { | ||
| debug: false, | ||
| layout: 'grid', | ||
| getItemStyle() { | ||
| return { | ||
| height: 180, | ||
| width: 180, | ||
| }; | ||
| }, | ||
| } as const; | ||
|
|
||
| export const Grid: Story = { | ||
| name: 'Basic setup', | ||
| args: defaultArgs, | ||
| }; | ||
|
|
||
| export const DragHandle: Story = { | ||
| name: 'Drag handle', | ||
| args: { | ||
| ...defaultArgs, | ||
| dragHandle: true, | ||
| }, | ||
| }; | ||
|
|
||
| export const LargeFirstTile: Story = { | ||
| name: 'Large first tile', | ||
| args: { | ||
| ...defaultArgs, | ||
| collisionDetector: pointerIntersection, | ||
| getItemStyle(_, index) { | ||
| if (index === 0) { | ||
| return { | ||
| maxWidth: 'initial', | ||
| gridRowStart: 'span 2', | ||
| gridColumnStart: 'span 2', | ||
| }; | ||
| } | ||
|
|
||
| return { | ||
| height: 150, | ||
| width: 150, | ||
| }; | ||
| }, | ||
| }, | ||
| }; | ||
|
|
||
| export const Clone: Story = { | ||
| name: 'Clone feedback', | ||
| args: { | ||
| ...defaultArgs, | ||
| collisionDetector: pointerIntersection, | ||
| getItemStyle(_, index) { | ||
| if (index === 0) { | ||
| return { | ||
| maxWidth: 'initial', | ||
| gridRowStart: 'span 2', | ||
| gridColumnStart: 'span 2', | ||
| }; | ||
| } | ||
|
|
||
| return { | ||
| height: 150, | ||
| width: 150, | ||
| }; | ||
| }, | ||
| feedback: 'clone', | ||
| }, | ||
| }; |
Oops, something went wrong.