Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 9 additions & 159 deletions apps/docs/lib/shiki-theme.ts
Original file line number Diff line number Diff line change
@@ -1,35 +1,13 @@
import type { ThemeRegistrationRaw } from 'shiki'

/**
* Sim's syntax theme for docs code blocks.
*
* The platform highlights code with PrismJS through `@sim/emcn`'s `Code` component, whose
* token colors live in `packages/emcn/src/components/code/code.css`. Docs highlight with
* Shiki, which is TextMate-scoped rather than Prism-tokenized, so parity has to be
* expressed as a scope-to-color mapping rather than a shared stylesheet. The palette follows
* `code.css` in light mode, with darker hues for readable contrast. Dark mode consumes the
* Sim's syntax theme for docs code blocks. The scope mapping is shared with the app in
* `@sim/emcn/syntax-theme`; docs supply their own palettes. Light mode
* follows `code.css` with darker hues for readable contrast, and dark mode consumes the
* docs semantic tokens so authored MDX and generated examples share the reading palette.
*
* The mapping was derived by highlighting the same snippets through both engines and
* comparing output. Two places where the grammars genuinely disagree, and the choice made:
*
* - Prism only colors a shell command when it recognises the binary, so `npm` highlights
* but `sim` does not. TextMate scopes the first word of a statement as the command
* regardless, so `sim` highlights too. Shiki's reading is the correct one and is kept.
* - TextMate scopes every bare shell argument as `string.unquoted.argument`, which would
* paint most of a command line in the string color. Prism leaves those plain, so the
* scope is pinned back to the base foreground and only genuinely quoted strings carry
* the string color.
*
* Bare `variable` is deliberately unmapped. TextMate scopes declared JavaScript
* identifiers as `variable.other.*`, and coloring those would make JS and TS far busier
* than the platform editor, which leaves them at the base foreground. Only the things
* Prism actually calls out — object and config keys, shell flags and shell expansions —
* are mapped to the variable color.
*/
import { buildSyntaxTheme, type SyntaxColors } from '@sim/emcn/syntax-theme'

/** Light-mode platform hues adjusted to meet WCAG AA text contrast on the code surface. */
const LIGHT = {
const LIGHT: SyntaxColors = {
/** `--text-primary` — the platform's base code foreground. */
foreground: '#1a1a1a',
/** `--surface-5` — the fill `chipFieldSurfaceClass` puts under a code surface. */
Expand All @@ -43,10 +21,10 @@ const LIGHT = {
function: '#854d0e',
regex: '#be123c',
deleted: '#b91c1c',
} as const
}

/** Dark syntax roles resolve through the shared docs theme, including portal surfaces. */
const DARK = {
const DARK: SyntaxColors = {
foreground: 'var(--docs-text)',
background: 'var(--docs-surface)',
comment: 'var(--docs-green)',
Expand All @@ -58,138 +36,10 @@ const DARK = {
function: 'var(--docs-orange)',
regex: 'var(--docs-red)',
deleted: 'var(--docs-red)',
} as const

type TokenColors = typeof LIGHT | typeof DARK

/**
* Builds a Shiki theme from one palette. Scope order matters: TextMate resolves a token by
* longest matching scope, so the narrower entries below (`string.unquoted.argument`,
* `keyword.operator`) intentionally follow and override the broader ones.
*/
function buildTheme(name: string, type: 'light' | 'dark', c: TokenColors): ThemeRegistrationRaw {
return {
name,
type,
settings: [
{ settings: { background: c.background, foreground: c.foreground } },

/** Prism `comment` / `block-comment` / `prolog` / `doctype` / `cdata`. */
{
scope: ['comment', 'punctuation.definition.comment', 'string.comment'],
settings: { foreground: c.comment },
},

/** Prism `keyword` / `atrule` — plus TextMate's storage scopes, which Prism folds into keywords. */
{
scope: [
'keyword',
'keyword.control',
'keyword.other',
'storage',
'storage.type',
'storage.modifier',
'meta.import keyword',
'meta.export keyword',
],
settings: { foreground: c.keyword },
},

/** Prism `function` and `class-name`. */
{
scope: [
'entity.name.function',
'entity.name.command',
'support.function',
'meta.function-call.generic',
'entity.name.class',
'entity.name.type',
'support.class',
'support.type',
],
settings: { foreground: c.function },
},

/**
* Prism `property` / `attr-name` / `variable` — object and config keys, markup
* attributes, shell flags and shell expansions. Bare `variable` is excluded on
* purpose; see the module docblock.
*/
{
scope: [
'support.type.property-name',
'meta.object-literal.key',
'entity.name.tag.yaml',
'entity.other.attribute-name',
'constant.other.option',
'variable.other.normal',
'variable.other.special',
'punctuation.definition.variable',
],
settings: { foreground: c.variable },
},

/** Prism `number` / `boolean` / `constant` / `tag`. */
{
scope: [
'constant.numeric',
'constant.language',
'constant.character',
'support.constant',
'entity.name.tag',
'variable.language',
],
settings: { foreground: c.constant },
},

/** Prism `string` / `char` / `inserted`. */
{
scope: [
'string',
'string.quoted',
'string.template',
'punctuation.definition.string',
'markup.inserted',
],
settings: { foreground: c.string },
},

/**
* Bare shell arguments. TextMate calls these strings; Prism leaves them plain, and
* plain is what keeps a command line readable. Declared after `string` so it wins.
*/
{ scope: ['string.unquoted.argument'], settings: { foreground: c.foreground } },

/** Prism `punctuation` / `operator` / `entity` / `symbol`. */
{
scope: [
'punctuation',
'meta.brace',
'keyword.operator',
'punctuation.separator',
'punctuation.terminator',
'punctuation.accessor',
],
settings: { foreground: c.punctuation },
},

/** Prism `regex` / `important`. */
{
scope: ['string.regexp', 'constant.regexp', 'keyword.other.important'],
settings: { foreground: c.regex },
},

/** Prism `deleted`, plus TextMate's invalid scopes. */
{
scope: ['markup.deleted', 'invalid', 'invalid.illegal'],
settings: { foreground: c.deleted },
},
],
}
}

const simShikiLight = buildTheme('sim-light', 'light', LIGHT)
const simShikiDark = buildTheme('sim-dark', 'dark', DARK)
const simShikiLight = buildSyntaxTheme('sim-light', 'light', LIGHT)
const simShikiDark = buildSyntaxTheme('sim-dark', 'dark', DARK)

/** Shared syntax palette for build-time MDX and generated API examples. */
export const simShikiOptions = {
Expand Down
21 changes: 17 additions & 4 deletions apps/docs/scripts/compile-content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ import { buildSearchCatalog, buildSearchIndex } from '@/lib/search/build'

const logger = createLogger('DocsContent')
const DOCS_ROOT = path.resolve(import.meta.dirname, '..')
/** The Shiki scope mapping docs highlight with; it lives in emcn, outside the docs tree. */
const SYNTAX_THEME_FILE = path.resolve(
DOCS_ROOT,
'../../packages/emcn/src/components/code/syntax-theme.ts'
)
const CONTENT_ROOT = path.join(DOCS_ROOT, 'content/docs')
const OUTPUT_ROOT = path.join(DOCS_ROOT, '.content')
const MAX_CONTENT_BYTES = 64 * 1024 * 1024
Expand Down Expand Up @@ -197,6 +202,7 @@ async function generate() {
path.join(DOCS_ROOT, 'lib/content/markdown.ts'),
path.join(DOCS_ROOT, 'lib/content/output.ts'),
path.join(DOCS_ROOT, 'lib/shiki-theme.ts'),
SYNTAX_THEME_FILE,
path.join(DOCS_ROOT, 'components/workflow-preview/examples.ts'),
path.join(DOCS_ROOT, 'components/workflow-preview/block-display-workflows.ts'),
path.join(DOCS_ROOT, 'package.json'),
Expand Down Expand Up @@ -449,6 +455,12 @@ if (process.argv.includes('--watch')) {
}
}
}
const scheduleRefresh = () => {
clearTimeout(timer)
timer = setTimeout(() => {
void refresh()
}, 150)
}
watch(DOCS_ROOT, { recursive: true }, (_, filename) => {
const changed = filename?.toString().replaceAll('\\', '/') ?? ''
if (
Expand All @@ -459,10 +471,11 @@ if (process.argv.includes('--watch')) {
!['scripts/compile-content.ts', 'lib/shiki-theme.ts', ...OPENAPI_SPEC_FILES].includes(changed)
)
return
clearTimeout(timer)
timer = setTimeout(() => {
void refresh()
}, 150)
scheduleRefresh()
})
/* Editors save by replacing the file, which ends a watch on the file itself; watch its folder. */
watch(path.dirname(SYNTAX_THEME_FILE), (_, filename) => {
if (filename?.toString() === path.basename(SYNTAX_THEME_FILE)) scheduleRefresh()
})
logger.info('Watching documentation source')
await refresh()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,41 @@ import {
isBlankValue,
isSentenceLike,
toDiffText,
type ValueKind,
} from '@/app/workspace/[workspaceId]/w/components/workflow-diff/utils'
import type { SubBlockConfig } from '@/blocks/types'
import { formatParameterLabel } from '@/tools/params'

/** Code languages blocks offer, as the highlighter names them. */
const CODE_DIFF_LANGUAGES = new Map([
['javascript', 'javascript'],
['typescript', 'typescript'],
['python', 'python'],
['shell', 'bash'],
['json', 'json'],
])

/**
* The syntax a text diff highlights as: JSON for structured values, plain text for prose, and
* for code the first language that names one the highlighter knows: the block's `language`
* setting after the change, then before it (a removed block has only that), then the field's
* own default.
*/
function diffLanguage(
config: SubBlockConfig | undefined,
kind: ValueKind,
targetValues: Record<string, unknown>,
baseValues: Record<string, unknown>
): string {
if (kind === 'json') return 'json'
if (config?.type !== 'code') return 'text'
for (const value of [targetValues.language, baseValues.language, config.language]) {
const language = typeof value === 'string' ? CODE_DIFF_LANGUAGES.get(value) : undefined
if (language) return language
}
return 'javascript'
}

interface FieldChangeRowProps {
blockType: string
scope: 'block' | 'subblock' | 'container'
Expand Down Expand Up @@ -117,7 +149,11 @@ export function FieldChangeRow({
/>
)}
{textual && !sameDisplayValue && !emptyTextChange && (
<TextDiff oldText={oldText} newText={newText} />
<TextDiff
oldText={oldText}
newText={newText}
language={diffLanguage(config, kind, targetValues, baseValues)}
/>
)}
{scalar &&
!sameDisplayValue &&
Expand Down
Loading
Loading