@inkdropapp/theme-dev-helpers 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkdropapp/theme-dev-helpers",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "A helper module for creating themes for Inkdrop",
   "keywords": [
     "inkdrop",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@inkdropapp/base-ui-theme": "^0.7.5",
-    "@inkdropapp/css": "^0.6.7",
+    "@inkdropapp/css": "^0.6.8",
     "@vitejs/plugin-react": "^6.0.2",
     "commander": "^15.0.0",
     "puppeteer": "^25.1.0",

package/pnpm-workspace.yaml

@@ -1,6 +1,6 @@
 allowBuilds:
-  esbuild: set this to true or false
-  puppeteer: set this to true or false
+  esbuild: true
+  puppeteer: true
 minimumReleaseAgeExclude:
   - '@inkdropapp/base-ui-theme'
   - '@inkdropapp/css'

package/src/dev-server/variables.tsx

@@ -1,4 +1,4 @@
-import themeVariableNames from '@inkdropapp/base-ui-theme/lib/variable-names.json'
+import themeVariableNames from '@inkdropapp/css/variables.json'
 import { getCSSVariables } from './get-css-variables'
 
 export const VariablesPage = () => {

package/src/generate-palette.ts

@@ -4,7 +4,7 @@ import path from 'path'
 import { pathToFileURL } from 'url'
 import { Command } from 'commander'
 import packageJson from '../package.json'
-import { buildPreviewHTML, mapThemeVariables } from './palette'
+import { buildPreviewHTML, deriveAppearance, mapThemeVariables, resolveLightDark } from './palette'
 
 const program = new Command()
 
@@ -13,7 +13,10 @@ program
   .name('generate-palette')
   .description('CLI tool for extracting CSS variables from a theme package for Inkdrop')
   .version(packageJson.version)
-  .option('-a, --appearance <light/dark>', 'Force the UI appearance ("light" or "dark")')
+  .option(
+    '-a, --appearance <light/dark>',
+    'Force the UI appearance ("light" or "dark"); defaults to the theme\'s declared appearance'
+  )
   .option('-o, --output <path>', 'Output file path (default: ./palette.json)', './palette.json')
   .parse(process.argv)
 
@@ -22,10 +25,20 @@ const options = program.opts()
 const outputPath = options.output as string
 const appearance = options.appearance as 'light' | 'dark' | undefined
 
+const baseStyleSheetSpecifiers = [
+  '@inkdropapp/css/reset.css',
+  '@inkdropapp/css/tokens.css',
+  '@inkdropapp/css/ui.css',
+  '@inkdropapp/css/tags.css',
+  '@inkdropapp/css/status.css',
+  '@inkdropapp/css/task-progress.css',
+  '@inkdropapp/base-ui-theme/styles/theme.css'
+]
+
 // Function to extract theme CSS variables
 async function extractPalette(outputPath: string) {
   const themePackageJson = await import(path.join(process.cwd(), 'package.json'))
-  const themeVariableNames: string[] = (await import(`@inkdropapp/css/ui.json`)).default
+  const themeVariableNames: string[] = (await import(`@inkdropapp/css/variables.json`)).default
 
   const browser = await puppeteer.launch()
   const page = await browser.newPage()
@@ -38,8 +51,18 @@ async function extractPalette(outputPath: string) {
     })
     .on('pageerror', (error) => console.error(error instanceof Error ? error.message : error))
 
+  // Fall back to the theme's declared appearance so `light-dark()` resolves to
+  // the branch the theme actually ships, even when no --appearance is forced.
+  const resolvedAppearance = appearance ?? deriveAppearance(themePackageJson)
+
   const baseUrl = pathToFileURL(process.cwd()).toString() + '/'
-  const content = buildPreviewHTML(themePackageJson, baseUrl, appearance)
+  const baseStyleSheetURLs = baseStyleSheetSpecifiers.map((spec) => import.meta.resolve(spec))
+  const content = buildPreviewHTML(
+    themePackageJson,
+    baseUrl,
+    baseStyleSheetURLs,
+    resolvedAppearance
+  )
 
   await page.goto(baseUrl)
   await page.setContent(content)
@@ -58,9 +81,18 @@ async function extractPalette(outputPath: string) {
 
   const themeCSSVariables = mapThemeVariables(themeVariableNames, computedCSSVariables)
 
+  // Resolve `light-dark()` to raw values so non-CSS consumers (e.g. the mobile
+  // app's React Native renderer) don't have to evaluate it themselves.
+  const resolvedVariables = Object.fromEntries(
+    Object.entries(themeCSSVariables).map(([name, value]) => [
+      name,
+      typeof value === 'string' ? resolveLightDark(value, resolvedAppearance) : value
+    ])
+  )
+
   // Write to the output file
   const outputFilePath = path.resolve(outputPath)
-  await writeFile(outputFilePath, JSON.stringify(themeCSSVariables, null, 2))
+  await writeFile(outputFilePath, JSON.stringify(resolvedVariables, null, 2))
 
   await browser.close()
 }

package/src/palette.test.ts

@@ -1,52 +1,106 @@
 import { describe, expect, test } from 'bun:test'
-import { buildPreviewHTML, mapThemeVariables } from './palette'
+import { buildPreviewHTML, deriveAppearance, mapThemeVariables, resolveLightDark } from './palette'
 
 describe('buildPreviewHTML', () => {
   const baseUrl = 'file:///themes/acme/'
+  const baseStyleSheetURLs = [
+    'file:///pkgs/@inkdropapp/css/reset.css',
+    'file:///pkgs/@inkdropapp/base-ui-theme/styles/theme.css'
+  ]
 
-  test('emits the base href so relative links resolve', () => {
-    const html = buildPreviewHTML({ name: 'acme' }, baseUrl)
+  test('emits the base href so relative theme links resolve', () => {
+    const html = buildPreviewHTML({ name: 'acme' }, baseUrl, [])
     expect(html).toContain(`<base href="${baseUrl}" />`)
   })
 
-  test('always includes the Inkdrop base stylesheets', () => {
-    const html = buildPreviewHTML({ name: 'acme' }, baseUrl)
-    expect(html).toContain('node_modules/@inkdropapp/css/reset.css')
-    expect(html).toContain('node_modules/@inkdropapp/css/tokens.css')
-    expect(html).toContain('node_modules/@inkdropapp/css/tags.css')
-    expect(html).toContain('node_modules/@inkdropapp/base-ui-theme/styles/theme.css')
+  test('links each resolved Inkdrop base stylesheet as an absolute URL', () => {
+    const html = buildPreviewHTML({ name: 'acme' }, baseUrl, baseStyleSheetURLs)
+    for (const href of baseStyleSheetURLs) {
+      expect(html).toContain(`<link rel="stylesheet" href="${href}" />`)
+    }
   })
 
   test('links each declared theme stylesheet under styles/', () => {
     const html = buildPreviewHTML(
       { name: 'acme', styleSheets: ['base.css', 'syntax.css'] },
-      baseUrl
+      baseUrl,
+      []
     )
     expect(html).toContain('<link rel="stylesheet" href="styles/base.css" />')
     expect(html).toContain('<link rel="stylesheet" href="styles/syntax.css" />')
   })
 
   test('omits theme stylesheet links when none are declared', () => {
-    const html = buildPreviewHTML({ name: 'acme' }, baseUrl)
+    const html = buildPreviewHTML({ name: 'acme' }, baseUrl, [])
     expect(html).not.toContain('href="styles/')
   })
 
   test('sets the body class to the theme name', () => {
-    const html = buildPreviewHTML({ name: 'acme-dark' }, baseUrl)
+    const html = buildPreviewHTML({ name: 'acme-dark' }, baseUrl, [])
     expect(html).toContain('<body class="acme-dark">')
   })
 
   test('appends an appearance-mode class when an appearance is forced', () => {
-    const html = buildPreviewHTML({ name: 'acme' }, baseUrl, 'dark')
+    const html = buildPreviewHTML({ name: 'acme' }, baseUrl, [], 'dark')
     expect(html).toContain('<body class="acme dark-mode">')
   })
 
   test('adds no appearance class when appearance is omitted', () => {
-    const html = buildPreviewHTML({ name: 'acme' }, baseUrl)
+    const html = buildPreviewHTML({ name: 'acme' }, baseUrl, [])
     expect(html).not.toContain('-mode')
   })
 })
 
+describe('deriveAppearance', () => {
+  test('is dark when the name contains "dark"', () => {
+    expect(deriveAppearance({ name: 'solarized-dark-ui' })).toBe('dark')
+  })
+
+  test('is dark when themeAppearance is "dark"', () => {
+    expect(deriveAppearance({ name: 'acme-ui', themeAppearance: 'dark' })).toBe('dark')
+  })
+
+  test('is light otherwise', () => {
+    expect(deriveAppearance({ name: 'acme-light-ui' })).toBe('light')
+    expect(deriveAppearance({ name: 'acme-ui', themeAppearance: 'light' })).toBe('light')
+    expect(deriveAppearance({})).toBe('light')
+  })
+})
+
+describe('resolveLightDark', () => {
+  test('keeps the first branch for light, the second for dark', () => {
+    expect(resolveLightDark('light-dark(red, blue)', 'light')).toBe('red')
+    expect(resolveLightDark('light-dark(red, blue)', 'dark')).toBe('blue')
+  })
+
+  test('leaves values without light-dark untouched', () => {
+    expect(resolveLightDark('hsl(192deg 100% 5%)', 'dark')).toBe('hsl(192deg 100% 5%)')
+  })
+
+  test('ignores commas nested inside the branches', () => {
+    const value = 'light-dark(hsl(215deg 14% 34%), hsl(218deg 11% 65% / 40%))'
+    expect(resolveLightDark(value, 'dark')).toBe('hsl(218deg 11% 65% / 40%)')
+    expect(resolveLightDark(value, 'light')).toBe('hsl(215deg 14% 34%)')
+  })
+
+  test('resolves nested light-dark within the chosen branch', () => {
+    const value = 'light-dark(light-dark(a, b), c)'
+    expect(resolveLightDark(value, 'light')).toBe('a')
+    expect(resolveLightDark(value, 'dark')).toBe('c')
+  })
+
+  test('resolves light-dark embedded in a larger value', () => {
+    const value = '0px 1px 2px 0 light-dark(rgba(0, 0, 0, 0.1), hsl(0deg 0% 0% / 20%)) inset'
+    expect(resolveLightDark(value, 'dark')).toBe('0px 1px 2px 0 hsl(0deg 0% 0% / 20%) inset')
+  })
+
+  test('resolves multiple light-dark occurrences in one value', () => {
+    const value = 'light-dark(a, b), light-dark(c, d)'
+    expect(resolveLightDark(value, 'light')).toBe('a, c')
+    expect(resolveLightDark(value, 'dark')).toBe('b, d')
+  })
+})
+
 describe('mapThemeVariables', () => {
   test('maps each declared name to its computed value, ignoring extras', () => {
     const result = mapThemeVariables(['--accent', '--bg'], {

package/src/palette.ts

@@ -4,25 +4,45 @@
  * browser lives in `generate-palette.ts`.
  */
 
+export type ThemeAppearance = 'light' | 'dark'
+
 /** Theme metadata read from a theme package's `package.json`. */
 export interface ThemePackage {
   name?: string
+  /** Explicit appearance declared by the theme (`"light"` | `"dark"`). */
+  themeAppearance?: ThemeAppearance
   styleSheets?: string[]
 }
 
-export type ThemeAppearance = 'light' | 'dark'
+/**
+ * Derives a theme's appearance the way Inkdrop's desktop app does (see
+ * `ThemePackage#getAppearance`): dark when the package name contains "dark" or
+ * `themeAppearance` is "dark", otherwise light. Used to pick which branch of a
+ * `light-dark()` value to keep.
+ *
+ * @param theme - The theme package's metadata.
+ * @returns The resolved appearance.
+ */
+export function deriveAppearance(theme: ThemePackage): ThemeAppearance {
+  return theme.name?.includes('dark') || theme.themeAppearance === 'dark' ? 'dark' : 'light'
+}
 
 /**
  * Builds the standalone HTML document that is loaded into a headless browser to
  * compute a theme's CSS custom properties.
  *
  * It pulls in Inkdrop's base CSS plus the theme's own stylesheets so that the
- * computed style of `<body>` resolves every themed variable. A `<base href>` is
- * emitted so the relative `node_modules/` and `styles/` links resolve against
+ * computed style of `<body>` resolves every themed variable. Inkdrop's base
+ * stylesheets are passed in as already-resolved absolute URLs (they live in
+ * this package's own dependencies, not the theme's), while the theme's own
+ * `styles/` links stay relative and resolve against the `<base href>` — i.e.
  * the theme project root.
  *
  * @param theme - The theme package's metadata (`name`, `styleSheets`).
- * @param baseUrl - File URL used as the document `<base href>`.
+ * @param baseUrl - File URL used as the document `<base href>`; the theme's own
+ *   `styles/` links resolve against it.
+ * @param baseStyleSheetURLs - Absolute URLs of Inkdrop's base stylesheets,
+ *   resolved from this package's dependency graph by the caller.
  * @param appearance - Optional forced appearance; adds a `<appearance>-mode`
  *   body class when provided.
  * @returns The full HTML document as a string.
@@ -30,8 +50,13 @@ export type ThemeAppearance = 'light' | 'dark'
 export function buildPreviewHTML(
   theme: ThemePackage,
   baseUrl: string,
+  baseStyleSheetURLs: string[],
   appearance?: ThemeAppearance
 ): string {
+  const baseCSSLinks = baseStyleSheetURLs
+    .map((href) => `<link rel="stylesheet" href="${href}" />`)
+    .join('\n')
+
   const themeCSSLinks = (theme.styleSheets ?? [])
     .map((filePath) => `<link rel="stylesheet" href="styles/${filePath}" />`)
     .join('\n')
@@ -42,10 +67,7 @@ export function buildPreviewHTML(
   <html>
     <head>
       <base href="${baseUrl}" />
-      <link rel="stylesheet" href="node_modules/@inkdropapp/css/reset.css" />
-      <link rel="stylesheet" href="node_modules/@inkdropapp/css/tokens.css" />
-      <link rel="stylesheet" href="node_modules/@inkdropapp/css/tags.css" />
-      <link rel="stylesheet" href="node_modules/@inkdropapp/base-ui-theme/styles/theme.css" />
+      ${baseCSSLinks}
       ${themeCSSLinks}
     </head>
     <body class="${bodyClass}">
@@ -76,3 +98,64 @@ export function mapThemeVariables(
     {} as Record<string, string>
   )
 }
+
+/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
+function matchingParen(value: string, openIndex: number): number {
+  let depth = 0
+  for (let i = openIndex; i < value.length; i++) {
+    if (value[i] === '(') depth++
+    else if (value[i] === ')' && --depth === 0) return i
+  }
+  return -1
+}
+
+/**
+ * Splits `value` at its first top-level (paren-depth-zero) comma into
+ * `[before, after]`. Commas inside nested function calls (e.g. `hsl(…)`) are
+ * ignored. Returns `[value, '']` when there is no top-level comma.
+ */
+function splitTopLevelComma(value: string): [string, string] {
+  let depth = 0
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i]
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    else if (ch === ',' && depth === 0) return [value.slice(0, i), value.slice(i + 1)]
+  }
+  return [value, '']
+}
+
+/**
+ * Replaces every `light-dark(<light>, <dark>)` in a CSS value with the branch
+ * matching `appearance`, recursively and in place.
+ *
+ * Inkdrop's mobile app (React Native) can't evaluate the CSS `light-dark()`
+ * function, so the generated palette must carry already-resolved raw values.
+ * The browser leaves `light-dark()` unresolved inside custom properties, so we
+ * pick the branch ourselves — mirroring how the desktop app selects light/dark
+ * via the body's `color-scheme`. Nested calls (the kept branch may itself
+ * contain `light-dark()`) and calls embedded in larger values (shadows,
+ * gradients, borders) are handled.
+ *
+ * @param value - A CSS value that may contain one or more `light-dark()` calls.
+ * @param appearance - Which branch to keep (`light` → first, `dark` → second).
+ * @returns The value with all `light-dark()` calls resolved.
+ */
+export function resolveLightDark(value: string, appearance: ThemeAppearance): string {
+  const marker = 'light-dark('
+  const start = value.indexOf(marker)
+  if (start === -1) return value
+
+  const open = start + marker.length - 1
+  const close = matchingParen(value, open)
+  if (close === -1) return value // unbalanced — leave the value untouched
+
+  const [light, dark] = splitTopLevelComma(value.slice(open + 1, close))
+  const chosen = (appearance === 'dark' ? dark : light).trim()
+
+  return (
+    value.slice(0, start) +
+    resolveLightDark(chosen, appearance) +
+    resolveLightDark(value.slice(close + 1), appearance)
+  )
+}