# Workspace Guide

A lesson shows its text next to the code. These parts make that text: `WorkspaceGuide` is the guide pane with Back and Next at the bottom, `WorkspaceSteps` is the steps menu for the bar, `WorkspaceTask` is the task box of a step, `WorkspaceFileLink` opens a file in the editor, and `WorkspaceIssues` lists the problems of the last render. Put them in the slots of `WorkspaceShell` with the `guide-top` or `guide-side` layout.

_Interactive preview available on the rendered documentation page._


## Installation

Install `@vite-hub/ui` as described in [Installation](https://vitehub.dev/docs/ui/installation). The parts are in the workspace entry:

```ts
import { WorkspaceFileLink, WorkspaceGuide, WorkspaceIssues, WorkspaceSteps, WorkspaceTask } from "vite-hub/ui/workspace";
```

## Usage

The guide never parses Markdown. Render the text of the step yourself, such as with `ContentRenderer`, and put it in the default slot. The guide shows the position and the title of the step over the text, and Back and Next at the bottom of its pane. Bind the same step to the guide and to the steps menu in the bar, so both move together:

```vue
<script setup lang="ts">
import { WorkspaceGuide, WorkspaceShell, WorkspaceSteps } from "vite-hub/ui/workspace";

// `pages` holds the parsed Markdown of each step, such as from Nuxt Content.
const { pages } = defineProps<{ pages: { title: string }[] }>();
const steps = computed(() => pages.map(page => ({ title: page.title })));
const step = ref(0);
</script>

<template>
  <WorkspaceShell layout="guide-side">
    <template #bar>
      <WorkspaceSteps v-model:step="step" :steps label="Translate an app" />
    </template>
    <template #guide>
      <WorkspaceGuide v-model:step="step" :steps>
        <ContentRenderer :value="pages[step]" />
      </WorkspaceGuide>
    </template>
  </WorkspaceShell>
</template>
```

### Steps menu

`WorkspaceSteps` shows the current step as a menu of every step, the position, and Previous and Next buttons. Pick a step in the menu to go to it.

_Interactive preview available on the rendered documentation page._


### Task

`WorkspaceTask` is the box under the text that tells the reader what to do next.

_Interactive preview available on the rendered documentation page._


### File links

`WorkspaceFileLink` shows the name of a file and opens its path in the editor. The workspace gives the opener with `provideWorkspaceFileOpener({ show })`, and every link under it calls `show(path)`. The link also emits `open`, so a page without an opener can listen to it.

_Interactive preview available on the rendered documentation page._


### Issues

`WorkspaceIssues` lists the issues of the last render, each with its line when it has one. An issue with a `file` shows `file:line` as a button that emits `show` with the path, and `Workspace` opens that file. The Issues tab of `render()` shows it. Without issues it hides, or shows the `empty` text.

_Interactive preview available on the rendered documentation page._


## Accessibility

The guide is an `article`, and its title is an `h2`. A new step starts at the top of the text. Back and Next are in a `nav` named "Step navigation", and Back names the step it goes to. The steps menu is a `nav` named "Steps": its button names the current step, and Previous and Next are off at the first and last step. A file link is a button whose title holds the full path. The task box has the `note` role. The issues list is named "Issues" and is a polite live region, so screen readers hear each new list. The file of an issue is a button whose title names the file.

## API Reference

### WorkspaceGuide

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `WorkspaceStep[]` | `[]` | The steps of the lesson, each `{ title, description? }`. |
| `step` | `number` | | The current step, from 0. Use `v-model:step`. Without it, the guide keeps its own step. |
| `title` | `string` | | The title over the text. Without it, the guide shows the title of the current step. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:step` | `number` | Back, Next, or a slot moved to another step. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ step, total, next, previous }` | The rendered text of the step. |
| `footer` | `{ step, total, next, previous }` | Replaces Back and Next. |
| `finish` | `{ step, total, next, previous }` | Shows in place of Next on the last step, such as a link back to the lessons. |

### WorkspaceSteps

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `WorkspaceStep[]` | Required | The steps of the lesson. The menu shows each `description` under its title. |
| `step` | `number` | | The current step, from 0. Use `v-model:step`. |
| `label` | `string` | | The heading of the menu, such as the name of the lesson. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:step` | `number` | The reader picked a step or pressed Previous or Next. |

### WorkspaceTask

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Try it"` | The heading of the box. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | | The task. |
| `title` | | Replaces the heading. |

### WorkspaceFileLink

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | Required | The path of the file in the workspace. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `open` | `string` | The reader clicked the link. The payload is the path. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | | Replaces the file name. |

### WorkspaceIssues

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `issues` | `WorkspaceIssue[]` | Required | The issues, each `{ message, file?, line? }`. |
| `empty` | `string` | | The text to show when there are no issues. Without it, the list hides. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `show` | `string` | The reader clicked the file of an issue. The payload is its path. |

## Related

- [Workspace](https://vitehub.dev/docs/ui/workspace)
- [File tree](https://vitehub.dev/docs/ui/file-tree)

<!-- vitehub-docs:section-links -->
## In this section

- [Start](https://vitehub.dev/raw/docs/ui.md)
- [AI components](https://vitehub.dev/raw/docs/ui/ai-components.md)
- [Blocks](https://vitehub.dev/raw/docs/ui/blocks/chat-app.md)
- [Parts](https://vitehub.dev/raw/docs/ui/message.md)
- [Chat](https://vitehub.dev/raw/docs/ui/chat.md)
- [Collaboration](https://vitehub.dev/raw/docs/ui/avatar-stack.md)
- Agent work
  - [Tool List](https://vitehub.dev/raw/docs/ui/tool-list.md)
  - [Diff](https://vitehub.dev/raw/docs/ui/diff.md)
  - [Code View](https://vitehub.dev/raw/docs/ui/code-view.md)
  - [File Tree](https://vitehub.dev/raw/docs/ui/file-tree.md)
  - [Device Frame](https://vitehub.dev/raw/docs/ui/device-frame.md)
  - [Workspace](https://vitehub.dev/raw/docs/ui/workspace.md)
  - [Workspace Bar](https://vitehub.dev/raw/docs/ui/workspace-bar.md)
  - [Workspace Code](https://vitehub.dev/raw/docs/ui/workspace-code.md)
  - [Workspace Guide](https://vitehub.dev/raw/docs/ui/workspace-guide.md) (this page)
- [Utilities](https://vitehub.dev/raw/docs/ui/attachments.md)

Next: [Diagnostics](https://vitehub.dev/raw/docs/ui/diagnostics.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
