From 211c6401e97277621c91b66494cb44a6d3d7f41a Mon Sep 17 00:00:00 2001 From: Valerio Ageno <51341197+Valerioageno@users.noreply.github.com> Date: Thu, 30 Jan 2025 21:04:15 +0100 Subject: [PATCH] docs: refine UI (#466) --- .../MdxProvider/MdxTitle/MdxTitle.tsx | 76 ++++++++++++++++--- .../src/components/MdxWrapper/MdxWrapper.tsx | 1 - .../src/components/Sidebar/sidebarElements.ts | 22 +----- .../TableOfContents/TableOfContents.tsx | 2 + .../documentation/application-state.mdx | 2 + .../src/routes/documentation/cli.mdx | 2 + .../routes/documentation/components/link.mdx | 2 + .../routes/documentation/configuration.mdx | 12 +-- .../contributing/pull-requests.mdx | 2 + .../routes/documentation/hooks/use-router.mdx | 2 + .../src/routes/documentation/installation.mdx | 2 +- .../documentation/routing/defining-routes.mdx | 4 +- .../routes/documentation/routing/layouts.mdx | 14 ---- .../routing/link-and-navigation.mdx | 2 + .../documentation/routing/loading-state.mdx | 14 ---- .../routes/documentation/routing/pages.mdx | 14 ---- .../documentation/routing/redirecting.mdx | 14 ---- .../documentation/styles/tailwind-css.mdx | 2 + .../documentation/tutorial/components.mdx | 2 + .../documentation/tutorial/conclusion.mdx | 7 +- .../documentation/tutorial/error-handling.mdx | 2 + .../routes/documentation/tutorial/index.mdx | 2 + .../documentation/tutorial/production.mdx | 6 +- .../documentation/tutorial/redirections.mdx | 2 + .../src/routes/documentation/tutorial/seo.mdx | 5 +- apps/documentation/src/routes/index.mdx | 2 + 26 files changed, 116 insertions(+), 101 deletions(-) delete mode 100644 apps/documentation/src/routes/documentation/routing/layouts.mdx delete mode 100644 apps/documentation/src/routes/documentation/routing/loading-state.mdx delete mode 100644 apps/documentation/src/routes/documentation/routing/pages.mdx delete mode 100644 apps/documentation/src/routes/documentation/routing/redirecting.mdx diff --git a/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx b/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx index 48adb3c7..e67de5bc 100644 --- a/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx +++ b/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx @@ -1,17 +1,71 @@ -import type { ElementType, JSX, ReactNode } from 'react' -import { Title, type TitleProps } from '@mantine/core' +import type { ElementType, JSX, MouseEventHandler, ReactNode } from 'react' +import { useCallback } from 'react' +import { Title, Anchor, Box } from '@mantine/core' +import type { TitleProps } from '@mantine/core' +import { IconLink } from '@tabler/icons-react' +import { useHover } from '@mantine/hooks' -export default function MdxTitle(props: TitleProps): JSX.Element { - const headingId = getIdFrom(props.children) +export default function MdxTitle({ + children, + order, + ...rest +}: TitleProps): JSX.Element { + const headingId = getIdFrom(children) + const { hovered, ref } = useHover() + + const handleAnchorClick: MouseEventHandler = useCallback( + (e) => { + e.preventDefault() + if (ref.current) { + history.pushState( + null, + '', + `#${(ref.current.firstChild as HTMLHeadingElement).id} `, + ) + ref.current.scrollIntoView({ + behavior: 'instant', + block: 'start', + }) + } + }, + [ref], + ) return ( - + <Box + ref={ref} + data-order={order} + style={{ + scrollMargin: 80, + marginTop: order === 1 ? 0 : 20, + }} + {...rest} + > + <Title + data-heading={headingId} + id={headingId} + data-order={order} + display="inline" + style={{ + scrollMargin: 80, + marginTop: order === 1 ? 0 : 20, + }} + {...rest} + > + {children} + {hovered && order !== 1 && ( + <Anchor + onClick={handleAnchorClick} + display="inline-flex" + ml={8} + mb={2} + style={{ alignItems: 'center', verticalAlign: 'middle' }} + > + <IconLink width={20} height={20} /> + </Anchor> + )} + + ) } diff --git a/apps/documentation/src/components/MdxWrapper/MdxWrapper.tsx b/apps/documentation/src/components/MdxWrapper/MdxWrapper.tsx index 8fbbfbf0..3578c58b 100644 --- a/apps/documentation/src/components/MdxWrapper/MdxWrapper.tsx +++ b/apps/documentation/src/components/MdxWrapper/MdxWrapper.tsx @@ -24,7 +24,6 @@ export function MdxWrapper({ children }: MdxWrapperProps): JSX.Element { id="mdx-root" component="article" mt="xl" - px={16} py={36} className={classes.wrapper} > diff --git a/apps/documentation/src/components/Sidebar/sidebarElements.ts b/apps/documentation/src/components/Sidebar/sidebarElements.ts index fc02880f..21ef2a4b 100644 --- a/apps/documentation/src/components/Sidebar/sidebarElements.ts +++ b/apps/documentation/src/components/Sidebar/sidebarElements.ts @@ -108,7 +108,7 @@ export const sidebarElements: Array = [ children: [ { type: 'element', - label: 'Defining routes', + label: 'Pages and layout', href: '/documentation/routing/defining-routes', }, { @@ -121,26 +121,6 @@ export const sidebarElements: Array = [ label: 'Link and navigation', href: '/documentation/routing/link-and-navigation', }, - { - type: 'element', - label: 'Pages', - href: '/documentation/routing/pages', - }, - { - type: 'element', - label: 'Loading state', - href: '/documentation/routing/loading-state', - }, - { - type: 'element', - label: 'Layouts', - href: '/documentation/routing/layouts', - }, - { - type: 'element', - label: 'Redirecting', - href: '/documentation/routing/redirecting', - }, ], }, { diff --git a/apps/documentation/src/components/TableOfContents/TableOfContents.tsx b/apps/documentation/src/components/TableOfContents/TableOfContents.tsx index 09f6b23c..15c41df5 100644 --- a/apps/documentation/src/components/TableOfContents/TableOfContents.tsx +++ b/apps/documentation/src/components/TableOfContents/TableOfContents.tsx @@ -72,6 +72,8 @@ export function TableOfContents(): JSX.Element | null { event.preventDefault() const element = document.getElementById(id) if (element) { + history.pushState(null, '', `#${element.id} `) + element.scrollIntoView({ behavior: 'instant', block: 'start', diff --git a/apps/documentation/src/routes/documentation/application-state.mdx b/apps/documentation/src/routes/documentation/application-state.mdx index 3e2109ce..311f5c1a 100644 --- a/apps/documentation/src/routes/documentation/application-state.mdx +++ b/apps/documentation/src/routes/documentation/application-state.mdx @@ -12,6 +12,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Application state +## Overview + The main reason Tuono is fast is that it loads just the features that are needed for the project. To define them, you need to fill the `ApplicationState` struct in the `./src/app.rs` file, and diff --git a/apps/documentation/src/routes/documentation/cli.mdx b/apps/documentation/src/routes/documentation/cli.mdx index 02c51bc6..a3c16a34 100644 --- a/apps/documentation/src/routes/documentation/cli.mdx +++ b/apps/documentation/src/routes/documentation/cli.mdx @@ -12,6 +12,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # CLI +## Overview + Tuono is the CLI that provides all the needed commands to handle the full-stack project. > ☝️ Check the [installation](/documentation/installation) page if you haven't installed the diff --git a/apps/documentation/src/routes/documentation/components/link.mdx b/apps/documentation/src/routes/documentation/components/link.mdx index 1c27b2cb..b475f421 100644 --- a/apps/documentation/src/routes/documentation/components/link.mdx +++ b/apps/documentation/src/routes/documentation/components/link.mdx @@ -11,6 +11,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Link +## Overview + Tuono provides a `Link` component for clientside navigation between pages of your app. `Link` prefetches pages from any links above the fold, allowing for faster navigations without a full reload. ```tsx diff --git a/apps/documentation/src/routes/documentation/configuration.mdx b/apps/documentation/src/routes/documentation/configuration.mdx index 66f9515e..a764c040 100644 --- a/apps/documentation/src/routes/documentation/configuration.mdx +++ b/apps/documentation/src/routes/documentation/configuration.mdx @@ -11,6 +11,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Configuration +## Overview + Tuono can be configured using the `tuono.config.ts` file, which allows you to customize various aspects of the build process and development environment. @@ -34,7 +36,7 @@ Tuono leverages Vite, a modern and fast build tool and development server for we As a result, **some** Vite configuration properties can be set in the `tuono.config.ts` file under the `vite` property. -### vite.alias +### `vite.alias` Useful for configuring custom source alias paths during imports @@ -43,13 +45,13 @@ Useful for configuring custom source alias paths during imports - `Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>` - [Vite documentation: resolve.alias](https://vite.dev/config/shared-options#resolve-alias) -### vite.optimizeDeps +### `vite.optimizeDeps` Vite's dependency optimizer used only during dev - [Vite documentation: Dep Optimization Options](https://vite.dev/config/dep-optimization-options) -### vite.plugins +### `vite.plugins` Useful for extending vite's functionality @@ -60,7 +62,7 @@ Useful for extending vite's functionality The following options configure the server. -## server.host +### server.host - Type: `string` - Default: `'localhost'` @@ -68,7 +70,7 @@ The following options configure the server. The hostname or IP address of the server. It can be a domain name (e.g., `"example.com"`) or an IP address (e.g., `"127.0.0.1"`) -## server.port +### `server.port` - Type: `number` - Default: `3000` diff --git a/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx b/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx index ec9d089b..ab2a2a98 100644 --- a/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx +++ b/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx @@ -17,6 +17,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Pull Requests +## Overview + Once your changes are ready, you can create a PR! If you are not familiar with GitHub pull requests, diff --git a/apps/documentation/src/routes/documentation/hooks/use-router.mdx b/apps/documentation/src/routes/documentation/hooks/use-router.mdx index 7bbe93d9..53d7a5bd 100644 --- a/apps/documentation/src/routes/documentation/hooks/use-router.mdx +++ b/apps/documentation/src/routes/documentation/hooks/use-router.mdx @@ -11,6 +11,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # useRouter +## Overview + The `useRouter` hook provides access to various data about the current route, as well as methods to navigate between pages, as seen in the below example: ```tsx diff --git a/apps/documentation/src/routes/documentation/installation.mdx b/apps/documentation/src/routes/documentation/installation.mdx index 689b8532..659244f4 100644 --- a/apps/documentation/src/routes/documentation/installation.mdx +++ b/apps/documentation/src/routes/documentation/installation.mdx @@ -24,7 +24,7 @@ languages. Since then, you need the following tools installed on your computer t > Node.js is needed just for the development environment. The final output will run on a Rust server. -## Installation +## How to install The tuono `CLI` is hosted on [crates.io](https://crates.io/crates/tuono) to download and install it, just run it on a terminal: diff --git a/apps/documentation/src/routes/documentation/routing/defining-routes.mdx b/apps/documentation/src/routes/documentation/routing/defining-routes.mdx index 5bb8fd4b..495f7c48 100644 --- a/apps/documentation/src/routes/documentation/routing/defining-routes.mdx +++ b/apps/documentation/src/routes/documentation/routing/defining-routes.mdx @@ -9,7 +9,9 @@ import Breadcrumbs from '@/components/Breadcrumbs' -# Defining routes +# Pages and layouts + +## Overview Tuono has a file-system based router built on the concept of routes. diff --git a/apps/documentation/src/routes/documentation/routing/layouts.mdx b/apps/documentation/src/routes/documentation/routing/layouts.mdx deleted file mode 100644 index d4c4cbef..00000000 --- a/apps/documentation/src/routes/documentation/routing/layouts.mdx +++ /dev/null @@ -1,14 +0,0 @@ -import MetaTags from '@/components/MetaTags' - - - -import Breadcrumbs from '@/components/Breadcrumbs' - - - -# Layouts - -Todo diff --git a/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx b/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx index 46b09c4a..597ad961 100644 --- a/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx +++ b/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx @@ -11,6 +11,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Link and navigation +## Overview + The Tuono router facilitates client-side route transitions between pages, enhancing the user experience by: - Enabling smooth navigation in single-page applications (SPAs) diff --git a/apps/documentation/src/routes/documentation/routing/loading-state.mdx b/apps/documentation/src/routes/documentation/routing/loading-state.mdx deleted file mode 100644 index 0c30320f..00000000 --- a/apps/documentation/src/routes/documentation/routing/loading-state.mdx +++ /dev/null @@ -1,14 +0,0 @@ -import MetaTags from '@/components/MetaTags' - - - -import Breadcrumbs from '@/components/Breadcrumbs' - - - -# Loading state - -Todo diff --git a/apps/documentation/src/routes/documentation/routing/pages.mdx b/apps/documentation/src/routes/documentation/routing/pages.mdx deleted file mode 100644 index bf976d95..00000000 --- a/apps/documentation/src/routes/documentation/routing/pages.mdx +++ /dev/null @@ -1,14 +0,0 @@ -import MetaTags from '@/components/MetaTags' - - - -import Breadcrumbs from '@/components/Breadcrumbs' - - - -# Pages - -Todo diff --git a/apps/documentation/src/routes/documentation/routing/redirecting.mdx b/apps/documentation/src/routes/documentation/routing/redirecting.mdx deleted file mode 100644 index c990ea2c..00000000 --- a/apps/documentation/src/routes/documentation/routing/redirecting.mdx +++ /dev/null @@ -1,14 +0,0 @@ -import MetaTags from '@/components/MetaTags' - - - -import Breadcrumbs from '@/components/Breadcrumbs' - - - -# Redirecting - -Todo diff --git a/apps/documentation/src/routes/documentation/styles/tailwind-css.mdx b/apps/documentation/src/routes/documentation/styles/tailwind-css.mdx index 4e655e7d..ed1dda34 100644 --- a/apps/documentation/src/routes/documentation/styles/tailwind-css.mdx +++ b/apps/documentation/src/routes/documentation/styles/tailwind-css.mdx @@ -11,6 +11,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Tailwind CSS +## Overview + [Tailwind CSS](https://tailwindcss.com) is a popular utility-first CSS framework. Tuono support begins with Tailwind CSS v4. diff --git a/apps/documentation/src/routes/documentation/tutorial/components.mdx b/apps/documentation/src/routes/documentation/tutorial/components.mdx index 30400bfd..16f1beb3 100644 --- a/apps/documentation/src/routes/documentation/tutorial/components.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/components.mdx @@ -69,6 +69,8 @@ Now that the link is done, let’s import it into the `index.tsx` file Now the links work. Clicking on any of them, we get redirected to the 404 page because we haven’t yet implemented the `pokemons/[pokemon]` page. As previously said, CSS modules are enabled out of the box, so let’s make those links a little bit nicer. +## Styling the component + Create alongside the `PokemonLink.tsx` component the CSS module `PokemonLink.module.css` and copy the following content into it: ```css diff --git a/apps/documentation/src/routes/documentation/tutorial/conclusion.mdx b/apps/documentation/src/routes/documentation/tutorial/conclusion.mdx index 0d8b679d..91a0c3d1 100644 --- a/apps/documentation/src/routes/documentation/tutorial/conclusion.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/conclusion.mdx @@ -17,13 +17,16 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Conclusion +## What a tutorial :) + That’s it! You just created a multi thread full stack application with Rust and React. The project is still under heavy development and many features are not ready yet, but I hope you got the taste of what is like working with rust and react in the same stack. -As I mentioned in the introduction, I'd love to hear what you thought about the framework and the tutorial - feel free to reach me -at [valerioageno@yahoo.it](mailto:valerioageno@yahoo.it) or in Twitter (X) DMs [@valerioageno](https://twitter.com/valerioageno). +As I mentioned in the introduction, I'd love to hear what you thought about the +framework and the tutorial - feel free to join the [official discord server](https://discord.com/invite/khQzPa654B) +or to reach me on Twitter (X) [@valerioageno](https://twitter.com/valerioageno). Ciao diff --git a/apps/documentation/src/routes/documentation/tutorial/error-handling.mdx b/apps/documentation/src/routes/documentation/tutorial/error-handling.mdx index 49b93e79..31cc56c5 100644 --- a/apps/documentation/src/routes/documentation/tutorial/error-handling.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/error-handling.mdx @@ -17,6 +17,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Error handling +## Return a 404 Error + With the current setup, all the routes always return a `200 Success` HTTP status, no matter the response type. In order to return a more meaningful status code to the browser, the `Props` struct can also be initialized with the diff --git a/apps/documentation/src/routes/documentation/tutorial/index.mdx b/apps/documentation/src/routes/documentation/tutorial/index.mdx index 411a699b..5d769f24 100644 --- a/apps/documentation/src/routes/documentation/tutorial/index.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/index.mdx @@ -12,6 +12,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Tutorial +## Overview + This tutorial is meant to give you a sneak peek at the framework and is intended to evolve during the development - be sure to have [installed](/documentation/installation) the [latest version](https://crates.io/crates/tuono). diff --git a/apps/documentation/src/routes/documentation/tutorial/production.mdx b/apps/documentation/src/routes/documentation/tutorial/production.mdx index 62484d3a..6145b31a 100644 --- a/apps/documentation/src/routes/documentation/tutorial/production.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/production.mdx @@ -17,6 +17,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Production build +## Building the production assets + The source is now ready to be released. Both server and client have been managed in an unoptimized way to ease the development experience. To build the project to the production state, just run: @@ -24,7 +26,9 @@ to ease the development experience. To build the project to the production state tuono build ``` -This command just created the final assets within the `out` directory. To run the production server, +## Running the production server + +The above command just created the final assets within the `out` directory. To run the production server, run: ```sh diff --git a/apps/documentation/src/routes/documentation/tutorial/redirections.mdx b/apps/documentation/src/routes/documentation/tutorial/redirections.mdx index e803cceb..6becee62 100644 --- a/apps/documentation/src/routes/documentation/tutorial/redirections.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/redirections.mdx @@ -17,6 +17,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Redirections +## Redirecting to a different page + What if there is a Pokémon among all of them that should be considered the GOAT? What we are going to do right now is creating a new route `/pokemons/GOAT` that points to the best Pokémon of the first generation. diff --git a/apps/documentation/src/routes/documentation/tutorial/seo.mdx b/apps/documentation/src/routes/documentation/tutorial/seo.mdx index f16fec2b..8d8f2a85 100644 --- a/apps/documentation/src/routes/documentation/tutorial/seo.mdx +++ b/apps/documentation/src/routes/documentation/tutorial/seo.mdx @@ -17,12 +17,13 @@ import Breadcrumbs from '@/components/Breadcrumbs' # SEO and meta tags +## Adding the page title + The website now works and the HTTP errors are meaningful, but we should also take care to be meaningful for the web crawlers. The best way to do it is to enrich the meta tags like the `` and the `<description>`. -To do so `tuono` fully supports [React19 -tags](https://react.dev/reference/react-dom/components/title). Let's update the `/` and the +To do so `tuono` fully supports the [React19 components](https://react.dev/reference/react-dom/components/title). Let's update the `/` and the `/pokemons/[pokemon]` routes with this. ```diff diff --git a/apps/documentation/src/routes/index.mdx b/apps/documentation/src/routes/index.mdx index 8df50a44..1b643536 100644 --- a/apps/documentation/src/routes/index.mdx +++ b/apps/documentation/src/routes/index.mdx @@ -12,6 +12,8 @@ import Breadcrumbs from '@/components/Breadcrumbs' # Tuono +## Overview + Tuono is a full-stack web framework for building React applications using Rust as the backend with a strong focus on usability and performance.