# Syntax Theme

## Usage

`SyntaxTheme` is the provider for code colors. It sets `--astryx-code-syntax-*` and `--astryx-code-block-background` for every `CodeBlock` inside it. `useSyntaxTheme()` reads the nearest syntax theme, including one set with `defineTheme({ syntax })`.

A single block can take the `syntaxTheme` prop instead of a wrapper. Use the wrapper when a region of code should share one preset.

Presets are exported from `@astryx-vue/core/Code`: `oneDarkPro`, `dracula`, `monokai`, `nord`, `tokyoNight`, `catppuccinMocha`, `githubDark`, `githubLight`, `solarizedLight`, `oneLight`, `catppuccinLatte`, and `tokyoNightLight`. `defineSyntaxTheme()` builds another one. All 14 color tokens are required. Five diff slots are optional and use the same `--astryx-code-syntax-*` names: `added`, `removed`, `diff-header`, `added-marker`, and `removed-marker`. Leave them out and the markers follow the punctuation color, with no extra header paint. A `[light, dark]` tuple is stored as `light-dark()`.

```vue
<script setup lang="ts">
import { CodeBlock, dracula, SyntaxTheme } from '@astryx-vue/core/Code'

const code = `const status = response.ok ? 'success' : 'error'`
</script>

<template>
  <SyntaxTheme :theme="dracula">
    <CodeBlock :code="code" language="ts" />
  </SyntaxTheme>
</template>
```

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Set <code>syntax</code> on <code>defineTheme()</code> when the whole app should share one code palette. |
| Do | Use <code>SyntaxTheme</code> when one section needs a different preset. |
| Do | Pass <code>syntaxTheme</code> on a single <code>CodeBlock</code> instead of wrapping that one block. |
| Don't | Recolor a code block with one-off CSS. A preset keeps the token colors and the background together. |

## Examples

### SyntaxTheme — Dark Preset

Wrap a code block in SyntaxTheme to apply a dark syntax preset such as Dracula.

```vue
<script setup lang="ts">
import { CodeBlock, dracula, SyntaxTheme } from '@astryx-vue/core/Code'

const code = `function greet(name: string) {
  return \`Hello, \${name}!\`;
}`
</script>

<template>
  <SyntaxTheme :theme="dracula" style="width: min(100%, 420px)">
    <CodeBlock :code="code" language="tsx" title="Dracula preset" width="100%" />
  </SyntaxTheme>
</template>
```

### SyntaxTheme — Light Preset

Use a light syntax preset for code examples that need to sit on light documentation surfaces.

```vue
<script setup lang="ts">
import { CodeBlock, githubLight, SyntaxTheme } from '@astryx-vue/core/Code'

const code = `const status = response.ok ? 'success' : 'error';
console.log({status});`
</script>

<template>
  <SyntaxTheme :theme="githubLight" style="width: min(100%, 420px)">
    <CodeBlock :code="code" language="tsx" title="GitHub Light preset" width="100%" />
  </SyntaxTheme>
</template>
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `SyntaxThemeDefinition` | — | A preset, or a theme from `defineSyntaxTheme()`. |

## Slots

| Name | Description |
| --- | --- |
| `default` | Code components that inherit these colors. |

## Tokens

`keyword`, `string`, `comment`, `number`, `function`, `type`, `variable`, `operator`, `constant`, `tag`, `attribute`, `property`, `punctuation`, and `background`.

## useSyntaxTheme

Returns `null` when no `SyntaxTheme` or theme `syntax` field is present.

| Field | Description |
| --- | --- |
| <code>name</code> | Syntax theme name. |
| <code>mode</code> | Mode used to pick a <code>light-dark()</code> stop. |
| <code>token(name)</code> | One syntax token for that mode. |
| <code>tokens</code> | Every syntax token for that mode. |

## Native attributes

The root is a `div`. `class` and `style` are applied to it.