Skip to content

AI-native design editor. Open-source Figma alternative.

fix(pen): resolve variables in every pen.dev theme (#1413)

Danila Poyarkovd136c2c46272
diff --git a/changes/1413/fixed.md b/changes/1413/fixed.md
new file mode 100644
index 000000000..ab85e9c2d
--- /dev/null
+++ b/changes/1413/fixed.md
@@ -0,0 +1 @@
+- `.pen` variables resolve in every theme a layer and its parents set, across several theme axes, with aliases and boolean visibility.
diff --git a/packages/pen/src/layout.ts b/packages/pen/src/layout.ts
index 55fc05ac8..66f423640 100644
--- a/packages/pen/src/layout.ts
+++ b/packages/pen/src/layout.ts
@@ -6,10 +6,18 @@ import type {
SceneGraph,
SceneNode
} from '@open-pencil/scene-graph'
-import { paddingFromShorthand, parseAutoLayoutDirection } from '@open-pencil/scene-graph/layout'
+import { parseAutoLayoutDirection } from '@open-pencil/scene-graph/layout'
import type { PenNode, PenNumber } from './schema'
-import { isVarRef, resolveNumber, type VarContext } from './variables'
+import { bindIfVar, isVarRef, resolveNumber, type VarContext } from './variables'
+
+const CORNERS = [
+ 'topLeftRadius',
+ 'topRightRadius',
+ 'bottomRightRadius',
+ 'bottomLeftRadius'
+] as const
+const PADDING = ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'] as const
export function applyCornerRadius(
node: SceneNode,
@@ -18,24 +26,31 @@ export function applyCornerRadius(
): void {
if (radius === undefined) return
if (Array.isArray(radius)) {
- const values = radius.map((value) => parseSize(value, 0, ctx).value)
node.independentCorners = true
- node.topLeftRadius = values[0] ?? 0
- node.topRightRadius = values[1] ?? 0
- node.bottomRightRadius = values[2] ?? 0
- node.bottomLeftRadius = values[3] ?? 0
+ for (const [index, field] of CORNERS.entries()) {
+ node[field] = resolveNumber(radius[index], ctx)
+ bindIfVar(node, field, radius[index], ctx)
+ }
return
}
- node.cornerRadius = parseSize(radius, 0, ctx).value
+ node.cornerRadius = resolveNumber(radius, ctx)
+ bindIfVar(node, 'cornerRadius', radius, ctx)
+}
+
+/** pen.dev padding: one value, vertical and horizontal, or top, right, bottom, and left. */
+function paddingSides(padding: NonNullable<PenNode['padding']>): PenNumber[] {
+ if (!Array.isArray(padding)) return [padding, padding, padding, padding]
+ if (padding.length === 2) return [padding[0], padding[1], padding[0], padding[1]]
+ return padding
}
export function applyPadding(node: SceneNode, padding: PenNode['padding'], ctx: VarContext): void {
if (padding === undefined) return
- const resolve = (value: PenNumber): number => resolveNumber(value, ctx)
- Object.assign(
- node,
- paddingFromShorthand(Array.isArray(padding) ? padding.map(resolve) : [resolve(padding)])
- )
+ const sides = paddingSides(padding)
+ for (const [index, field] of PADDING.entries()) {
+ node[field] = resolveNumber(sides[index], ctx)
+ bindIfVar(node, field, sides[index], ctx)
+ }
}
interface ParsedSize {
diff --git a/packages/pen/src/read.ts b/packages/pen/src/read.ts
index da92b2145..7c0d2e283 100644
--- a/packages/pen/src/read.ts
+++ b/packages/pen/src/read.ts
@@ -182,16 +182,21 @@ function applyAllRefProps(penNodes: PenNode[], build: Build): void {
}
}
-function applyTheme(theme: Record<string, string>, ctx: VarContext): void {
- const themeName = Object.values(theme)[0]
- if (themeName) ctx.setActiveTheme(themeName)
+/** Builds a layer and its children in the layer's theme, merged over its parent's. */
+function createSceneNode(pen: PenNode, parentId: string, build: Build): string | null {
+ const { ctx } = build
+ if (pen.type === 'prompt') return null
+ const leaveTheme = pen.theme ? ctx.enterTheme(pen.theme) : undefined
+ try {
+ return buildSceneNode(pen, parentId, build)
+ } finally {
+ leaveTheme?.()
+ }
}
// eslint-disable-next-line complexity -- .pen node mapping touches many format-specific fields
-function createSceneNode(pen: PenNode, parentId: string, build: Build): string | null {
+function buildSceneNode(pen: PenNode, parentId: string, build: Build): string {
const { graph, ctx } = build
- if (pen.type === 'prompt') return null
- if (pen.theme) applyTheme(pen.theme, ctx)
const { w, h, layout, isTextLike } = resolveSizing(pen, ctx)
const overrides = buildBaseOverrides(pen, ctx)
@@ -215,6 +220,11 @@ function createSceneNode(pen: PenNode, parentId: string, build: Build): string |
}
const node = graph.createNode(mapNodeType(pen), parentId, overrides)
+ if (pen.theme) node.variableModes = { [ctx.collectionId]: ctx.modeId() }
+ bindIfVar(node, 'visible', pen.enabled, ctx)
+ bindIfVar(node, 'opacity', pen.opacity, ctx)
+ bindIfVar(node, 'width', pen.width, ctx)
+ bindIfVar(node, 'height', pen.height, ctx)
const placement = penPlacement(pen, ctx)
if (pen.type === 'group') build.groupIds.push(node.id)
if (layout !== 'NONE' && pen.justifyContent === 'space_around') build.aroundIds.push(node.id)
@@ -377,32 +387,6 @@ function collectComponentIds(nodes: PenNode[], map: Map<string, string>): void {
}
}
-function resolveNodeVars(node: SceneNode, graph: SceneGraph, ctx: VarContext): void {
- for (const [key, varId] of Object.entries(node.boundVariables)) {
- const variable = graph.variables.get(varId)
- if (!variable) continue
- const modeVal =
- variable.valuesByMode[ctx.activeModeId] ?? Object.values(variable.valuesByMode)[0]
- const paint = /^(fills|strokes)\/(\d+)\/color$/.exec(key)
- if (!paint || typeof modeVal !== 'object' || !('r' in modeVal)) continue
- const target = node[paint[1] === 'fills' ? 'fills' : 'strokes'].at(Number(paint[2]))
- if (target) target.color = modeVal
- }
- for (const childId of node.childIds) {
- const child = graph.getNode(childId)
- if (child) resolveNodeVars(child, graph, ctx)
- }
-}
-
-function resolveThemeVariables(penNodes: PenNode[], graph: SceneGraph, ctx: VarContext): void {
- for (const pen of penNodes) {
- if (pen.theme) applyTheme(pen.theme, ctx)
- const node = graph.getNode(pen.id)
- if (node) resolveNodeVars(node, graph, ctx)
- if (pen.children) resolveThemeVariables(pen.children, graph, ctx)
- }
-}
-
function fixInstanceWidths(graph: SceneGraph): void {
for (const node of graph.getAllNodes()) {
if (node.type !== 'INSTANCE' || !node.componentId) continue
@@ -451,7 +435,7 @@ export function parsePenFile(json: string, options: PenReadOptions = {}): SceneG
graph.deleteNode(page.id)
}
- const ctx = buildVarContext(graph, doc.variables ?? {}, doc.themes ?? {})
+ const ctx = buildVarContext(graph, doc)
const build: Build = {
graph,
ctx,
@@ -471,7 +455,6 @@ export function parsePenFile(json: string, options: PenReadOptions = {}): SceneG
populateInstances(build)
walkAndApplyOverrides(doc.children, build)
populateInstances(build)
- resolveThemeVariables(doc.children, graph, ctx)
fixInstanceWidths(graph)
options.layout?.(graph)
diff --git a/packages/pen/src/variables.ts b/packages/pen/src/variables.ts
index 6cbe142e0..9a2383a91 100644
--- a/packages/pen/src/variables.ts
+++ b/packages/pen/src/variables.ts
@@ -3,7 +3,6 @@ import {
type SceneGraph,
type SceneNode,
type Variable,
- type VariableCollection,
type VariableCollectionMode,
type VariableType,
type VariableValue
@@ -12,52 +11,40 @@ import { parseColor } from '@open-pencil/scene-graph/color'
import { BLACK } from '@open-pencil/scene-graph/constants'
import type { Color } from '@open-pencil/scene-graph/primitives'
-import type { PenNumber, PenVariable, PenVariableScalar } from './schema'
+import type { PenDocument, PenNumber, PenVariable, PenVariableScalar } from './schema'
+type Theme = Record<string, string>
+
+/**
+ * A document's variables, resolved in the theme of the layer being read. pen.dev themes are axes,
+ * such as `mode` and `density`, each with its values; every combination of one value per axis is
+ * one mode of a single collection, since a variable can depend on several axes at once.
+ */
export interface VarContext {
- byName: Map<string, { id: string; variable: Variable }>
- activeModeId: string
collectionId: string
- modeByThemeName: Map<string, string>
+ byName: Map<string, Variable>
resolveColor(ref: string): Color
resolveNumber(ref: string): number
resolveString(ref: string): string
resolveBoolean(ref: string): boolean
- setActiveTheme(themeName: string): void
-}
-
-function penVarTypeToSceneType(t: string): VariableType {
- if (t === 'color') return 'COLOR'
- if (t === 'number') return 'FLOAT'
- if (t === 'boolean') return 'BOOLEAN'
- return 'STRING'
-}
-
-function penValueToSceneValue(raw: PenVariableScalar, type: VariableType): VariableValue {
- if (type === 'COLOR' && typeof raw === 'string') return parseColor(raw)
- if (type === 'STRING') return String(raw)
- return raw
-}
-
-function defaultForType(type: VariableType): VariableValue {
- if (type === 'COLOR') return { ...BLACK }
- if (type === 'FLOAT') return 0
- if (type === 'BOOLEAN') return false
- return ''
+ /** Merges a layer's theme over its parent's until the returned function is called. */
+ enterTheme(theme: Theme): () => void
+ /** The mode of the theme being read. */
+ modeId(): string
}
-export function isVarRef(val: unknown): val is string {
+export function isVarRef(val: unknown): val is `$${string}` {
return typeof val === 'string' && val.startsWith('$') && val.length > 1
}
function varName(ref: string): string {
- return ref.replace(/^\$/, '')
+ return ref.slice(1)
}
export function bindIfVar(node: SceneNode, field: string, val: unknown, ctx: VarContext): void {
if (!isVarRef(val)) return
- const entry = ctx.byName.get(varName(val))
- if (entry) node.boundVariables[field] = entry.id
+ const variable = ctx.byName.get(varName(val))
+ if (variable) node.boundVariables[field] = variable.id
}
/** A number, or the value of the number variable it references. */
@@ -85,122 +72,151 @@ export function resolveColor(value: string, ctx: VarContext): Color {
return isVarRef(value) ? ctx.resolveColor(value) : parseColor(value)
}
-export function buildVarContext(
- graph: SceneGraph,
- penVars: Record<string, PenVariable>,
- themes: Record<string, string[]>
-): VarContext {
- const collectionId = generateId()
- const modes: VariableCollectionMode[] = []
- const themeKeys = Object.keys(themes)
+function sceneType(type: string): VariableType {
+ if (type === 'color') return 'COLOR'
+ if (type === 'number') return 'FLOAT'
+ if (type === 'boolean') return 'BOOLEAN'
+ return 'STRING'
+}
- if (themeKeys.length > 0) {
- const themeKey = themeKeys[0]
- for (const modeName of themes[themeKey]) {
- modes.push({ modeId: generateId(), name: modeName })
- }
+/** pen.dev leaves a variable without a value in a theme no entry matches: black, zero, or empty. */
+function emptyValue(type: VariableType): VariableValue {
+ if (type === 'COLOR') return { ...BLACK }
+ if (type === 'FLOAT') return 0
+ if (type === 'BOOLEAN') return false
+ return ''
+}
+
+type Axis = [name: string, values: string[]]
+
+/** Every combination of one value per axis, the first values first. */
+function combinations(axes: Axis[]): Theme[] {
+ return axes.reduce<Theme[]>(
+ (themes, [axis, values]) =>
+ themes.flatMap((theme) => values.map((value) => ({ ...theme, [axis]: value }))),
+ [{}]
+ )
+}
+
+/**
+ * A variable's raw value in a full theme. An entry applies when each of its axes has its value in
+ * the theme, and a later one replaces an earlier one, as pen.dev 2.21 resolves them.
+ */
+function rawValue(definition: PenVariable, theme: Theme): PenVariableScalar | undefined {
+ if (!Array.isArray(definition.value)) return definition.value
+ let found: PenVariableScalar | undefined
+ for (const entry of definition.value) {
+ const entryTheme = Object.entries(entry.theme ?? {})
+ if (entryTheme.every(([axis, value]) => theme[axis] === value)) found = entry.value
}
- if (modes.length === 0) {
- modes.push({ modeId: generateId(), name: 'Default' })
+ return found
+}
+
+function sceneValue(
+ raw: PenVariableScalar | undefined,
+ type: VariableType,
+ ids: ReadonlyMap<string, string>
+): VariableValue {
+ if (raw === undefined) return emptyValue(type)
+ if (isVarRef(raw)) {
+ const aliasId = ids.get(varName(raw))
+ return aliasId ? { aliasId } : emptyValue(type)
}
+ if (type === 'COLOR') return typeof raw === 'string' ? parseColor(raw) : emptyValue(type)
+ if (type === 'FLOAT') return typeof raw === 'number' ? raw : Number(raw) || 0
+ if (type === 'BOOLEAN') return typeof raw === 'boolean' ? raw : raw === 'true'
+ return String(raw)
+}
+
+function themeKey(theme: Theme, axes: Axis[]): string {
+ return axes.map(([axis]) => theme[axis]).join('\u0000')
+}
- const collection: VariableCollection = {
+export function buildVarContext(graph: SceneGraph, doc: PenDocument): VarContext {
+ const axes: Axis[] = Object.entries(doc.themes ?? {}).filter(([, values]) => values.length > 0)
+ const themes = combinations(axes)
+ const modes: VariableCollectionMode[] = themes.map((theme) => ({
+ modeId: generateId(),
+ name: axes.length === 0 ? 'Default' : axes.map(([axis]) => theme[axis]).join(' / ')
+ }))
+ const modeByTheme = new Map(themes.map((theme, index) => [themeKey(theme, axes), modes[index]]))
+ const collectionId = generateId()
+ graph.addCollection({
id: collectionId,
- name: 'Variables',
+ name: axes.length === 1 ? axes[0][0] : 'Theme',
modes,
defaultModeId: modes[0].modeId,
variableIds: []
- }
- graph.addCollection(collection)
-
- const modeByThemeValue = new Map<string, string>()
- if (themeKeys.length > 0) {
- const themeKey = themeKeys[0]
- for (const mode of modes) {
- modeByThemeValue.set(`${themeKey}:${mode.name}`, mode.modeId)
- }
- }
-
- const byName = new Map<string, { id: string; variable: Variable }>()
-
- for (const [name, def] of Object.entries(penVars)) {
- const varId = generateId()
- const varType = penVarTypeToSceneType(def.type)
- const valuesByMode: Record<string, VariableValue> = {}
-
- if (Array.isArray(def.value)) {
- for (const entry of def.value) {
- if (entry.theme) {
- const [tKey, tVal] = Object.entries(entry.theme)[0]
- const modeId = modeByThemeValue.get(`${tKey}:${tVal}`)
- if (modeId) valuesByMode[modeId] = penValueToSceneValue(entry.value, varType)
- } else {
- valuesByMode[modes[0].modeId] = penValueToSceneValue(entry.value, varType)
- }
- }
- } else {
- valuesByMode[modes[0].modeId] = penValueToSceneValue(def.value, varType)
- }
-
- for (const mode of modes) {
- if (!(mode.modeId in valuesByMode)) {
- valuesByMode[mode.modeId] = valuesByMode[modes[0].modeId] ?? defaultForType(varType)
- }
- }
-
+ })
+
+ const definitions = Object.entries(doc.variables ?? {})
+ const ids = new Map(definitions.map(([name]) => [name, generateId()]))
+ const byName = new Map<string, Variable>()
+ const byId = new Map<string, Variable>()
+ for (const [name, definition] of definitions) {
+ const type = sceneType(definition.type)
const variable: Variable = {
- id: varId,
+ id: ids.get(name) ?? generateId(),
name,
- type: varType,
+ type,
collectionId,
- valuesByMode,
+ valuesByMode: Object.fromEntries(
+ themes.map((theme, index) => [
+ modes[index].modeId,
+ sceneValue(rawValue(definition, theme), type, ids)
+ ])
+ ),
description: '',
hiddenFromPublishing: false
}
graph.addVariable(variable)
- byName.set(name, { id: varId, variable })
+ byName.set(name, variable)
+ byId.set(variable.id, variable)
}
- let activeModeId = modes[0].modeId
+ let current: Theme = themes[0]
+ const modeId = () => modeByTheme.get(themeKey(current, axes))?.modeId ?? modes[0].modeId
- function resolveVal(ref: string): VariableValue | undefined {
- const entry = byName.get(varName(ref))
- if (!entry) return undefined
- return (
- entry.variable.valuesByMode[activeModeId] ?? Object.values(entry.variable.valuesByMode)[0]
- )
+ /** A variable's value in the current theme, following aliases. */
+ function resolve(ref: string): VariableValue | undefined {
+ let variable = byName.get(varName(ref))
+ for (let hops = 0; variable && hops <= byName.size; hops++) {
+ const value = variable.valuesByMode[modeId()]
+ if (typeof value !== 'object' || !('aliasId' in value)) return value
+ variable = byId.get(value.aliasId)
+ }
+ return undefined
}
return {
- byName,
- activeModeId,
collectionId,
- modeByThemeName: modeByThemeValue,
- resolveColor(ref: string): Color {
- const val = resolveVal(ref)
- if (val === undefined) return parseColor(ref)
- if (typeof val === 'object' && 'r' in val) return val
- if (typeof val === 'string') return parseColor(val)
- return { ...BLACK }
+ byName,
+ resolveColor(ref) {
+ const value = resolve(ref)
+ return typeof value === 'object' && 'r' in value ? value : { ...BLACK }
},
- resolveNumber(ref: string): number {
- const val = resolveVal(ref)
- return typeof val === 'number' ? val : 0
+ resolveNumber(ref) {
+ const value = resolve(ref)
+ return typeof value === 'number' ? value : 0
},
- resolveString(ref: string): string {
- const val = resolveVal(ref)
- return typeof val === 'string' ? val : ''
+ resolveString(ref) {
+ const value = resolve(ref)
+ return typeof value === 'string' ? value : ''
},
- resolveBoolean(ref: string): boolean {
- const val = resolveVal(ref)
- return typeof val === 'boolean' ? val : val !== undefined && val !== 'false'
+ resolveBoolean(ref) {
+ const value = resolve(ref)
+ return typeof value === 'boolean' ? value : value !== undefined && value !== 'false'
},
- setActiveTheme(themeName: string) {
- const modeId = modeByThemeValue.get(`theme:${themeName}`)
- if (modeId) {
- activeModeId = modeId
- graph.activeMode.set(collectionId, modeId)
+ enterTheme(theme) {
+ const outer = current
+ const known = Object.entries(theme).filter(([axis, value]) =>
+ axes.some(([name, values]) => name === axis && values.includes(value))
+ )
+ current = { ...outer, ...Object.fromEntries(known) }
+ return () => {
+ current = outer
}
- }
+ },
+ modeId
}
}
diff --git a/packages/pen/tests/variables.test.ts b/packages/pen/tests/variables.test.ts
index 26e72675f..1889b3ea2 100644
--- a/packages/pen/tests/variables.test.ts
+++ b/packages/pen/tests/variables.test.ts
@@ -146,3 +146,123 @@ describe.each(['', '--'])('parsePenFile — $%sname references (#563)', (prefix)
expect(graph.getNode('text')).toMatchObject({ fontFamily: '', boundVariables: {} })
})
})
+
+// Measured on pen.dev 2.21 with two theme axes.
+describe('parsePenFile — themes', () => {
+ const themes = { mode: ['light', 'dark'], density: ['compact', 'cozy'] }
+ const variables: PenDocument['variables'] = {
+ accent: {
+ type: 'color',
+ value: [
+ { value: '#CC0000', theme: { mode: 'light', density: 'compact' } },
+ { value: '#00CC00', theme: { mode: 'dark' } },
+ { value: '#0000CC', theme: { mode: 'light', density: 'cozy' } }
+ ]
+ },
+ alias: { type: 'color', value: '$accent' },
+ gap: {
+ type: 'number',
+ value: [
+ { value: 4, theme: { density: 'compact' } },
+ { value: 16, theme: { density: 'cozy' } }
+ ]
+ },
+ shown: {
+ type: 'boolean',
+ value: [
+ { value: true, theme: { mode: 'light' } },
+ { value: false, theme: { mode: 'dark' } }
+ ]
+ },
+ darkOnly: { type: 'number', value: [{ value: 10, theme: { mode: 'dark' } }] }
+ }
+
+ function swatches(theme?: Record<string, string>, inner?: Record<string, string>) {
+ const graph = parsePenFile(
+ JSON.stringify({
+ version: '2.21',
+ themes,
+ variables,
+ children: [
+ {
+ id: 'outer',
+ type: 'frame',
+ layout: 'vertical',
+ gap: '$darkOnly',
+ ...(theme ? { theme } : {}),
+ children: [
+ {
+ id: 'inner',
+ type: 'frame',
+ layout: 'vertical',
+ gap: '$gap',
+ ...(inner ? { theme: inner } : {}),
+ children: [
+ { id: 'accent', type: 'rectangle', width: 10, height: 10, fill: '$accent' },
+ { id: 'alias', type: 'rectangle', width: 10, height: 10, fill: '$alias' },
+ { id: 'shown', type: 'rectangle', width: 10, height: 10, enabled: '$shown' }
+ ]
+ }
+ ]
+ }
+ ]
+ })
+ )
+ const node = (id: string) => expectDefined(graph.getNode(id), id)
+ return {
+ graph,
+ accent: node('accent').fills[0]?.color,
+ alias: node('alias').fills[0]?.color,
+ shown: node('shown').visible,
+ gap: node('inner').itemSpacing,
+ outerGap: node('outer').itemSpacing
+ }
+ }
+
+ test('puts every combination of axis values in one collection', () => {
+ const { graph } = swatches()
+ const collection = expectDefined([...graph.variableCollections.values()][0], 'collection')
+ expect(collection.modes.map((mode) => mode.name)).toEqual([
+ 'light / compact',
+ 'light / cozy',
+ 'dark / compact',
+ 'dark / cozy'
+ ])
+ })
+
+ test('reads an unthemed layer in the first value of each axis', () => {
+ expect(swatches()).toMatchObject({
+ accent: { r: 0.8, g: 0, b: 0 },
+ gap: 4,
+ shown: true,
+ outerGap: 0
+ })
+ })
+
+ test('resolves aliases in the layer theme', () => {
+ const { accent, alias } = swatches({ mode: 'dark' })
+ expect(alias).toEqual(accent)
+ expect(accent).toMatchObject({ r: 0, g: 0.8, b: 0 })
+ })
+
+ test('merges a nested theme over its parent, axis by axis', () => {
+ expect(swatches({ mode: 'dark' }, { density: 'cozy' })).toMatchObject({
+ accent: { r: 0, g: 0.8, b: 0 },
+ gap: 16,
+ shown: false,
+ outerGap: 10
+ })
+ })
+
+ test('gives themed layers their mode, which their children inherit', () => {
+ const { graph } = swatches({ mode: 'dark' }, { density: 'cozy' })
+ const collection = expectDefined([...graph.variableCollections.values()][0], 'collection')
+ const id = collection.id
+ const modeName = (nodeId: string) =>
+ collection.modes.find((mode) => mode.modeId === graph.getNode(nodeId)?.variableModes[id])
+ ?.name
+ expect(modeName('outer')).toBe('dark / compact')
+ expect(modeName('inner')).toBe('dark / cozy')
+ expect(graph.getNode('accent')?.variableModes[id]).toBeUndefined()
+ })
+})