feat: add support to scaffold themes (#15)

Author: HiDeoo

.changeset/tough-hats-enjoy.md

@@ -0,0 +1,5 @@
+---
+'@hideoo/generator-starlight-plugin': minor
+---
+
+Adds support for scaffolding themes.

src/index.ts

@@ -4,7 +4,7 @@ import Generator, { type BaseOptions } from 'yeoman-generator'
 
 import { copy, copyTpl } from './libs/fs.js'
 import { fetchDependencyVersions } from './libs/npm.js'
-import { promptForEmoji, promptForName, promptForText } from './libs/prompt.js'
+import { promptForEmoji, promptForLayer, promptForName, promptForText, promptForTheme } from './libs/prompt.js'
 
 export default class StarlightPluginGenerator extends Generator<BaseOptions & Configuration> {
   configuration: Configuration
@@ -25,6 +25,8 @@ export default class StarlightPluginGenerator extends Generator<BaseOptions & Co
       type: String,
       description: 'Single emoji representing the Starlight plugin (used in the documentation)',
     })
+    this.option('theme', { type: Boolean, description: 'Define if the plugin is a theme' })
+    this.option('layer', { type: String, description: 'Name of the theme CSS cascade layer (only used for themes)' })
     this.option('ghUsername', { type: String, description: 'GitHub username' })
   }
 
@@ -41,6 +43,8 @@ export default class StarlightPluginGenerator extends Generator<BaseOptions & Co
       'My awesome Starlight plugin',
     )
     await promptForEmoji(this)
+    await promptForTheme(this)
+    if (this.configuration.theme) await promptForLayer(this)
     await promptForText(this, 'ghUsername', 'What is your GitHub username?', 'ghost')
   }
 
@@ -66,6 +70,10 @@ export default class StarlightPluginGenerator extends Generator<BaseOptions & Co
 
     copyTpl(this, 'packages/plugin', pluginPath)
     copy(this, 'npmignore', `${pluginPath}/.npmignore`)
+
+    if (this.configuration.theme) {
+      copyTpl(this, 'styles.css', `${pluginPath}/styles.css`)
+    }
   }
 
   install() {
@@ -89,5 +97,7 @@ export interface Configuration {
   description?: string
   emoji?: string
   ghUsername?: string
+  layer?: string
+  theme?: boolean
   year: string
 }

src/libs/prompt.ts

@@ -1,7 +1,7 @@
 import type StarlightPluginGenerator from '../index.js'
 import type { Configuration } from '../index.js'
 
-import { validateEmoji, validateName, validateNonEmptyString } from './validator.js'
+import { validateEmoji, validateLayer, validateName, validateNonEmptyString } from './validator.js'
 
 export async function promptForName(generator: StarlightPluginGenerator) {
   const name = generator.options.name
@@ -15,16 +15,38 @@ export async function promptForName(generator: StarlightPluginGenerator) {
     type: 'input',
     name: 'name',
     message: 'What is the name of your Starlight plugin?',
-    default: `starlight-plugin-name`,
+    default: 'starlight-plugin-name',
     validate: validateName,
   })
 
   generator.configuration.name = answers.name
 }
 
+export async function promptForTheme(generator: StarlightPluginGenerator) {
+  const theme = generator.options.theme
+
+  if (theme !== undefined) {
+    generator.configuration.theme = theme
+    return
+  }
+
+  const answers = await generator.prompt<{ theme: boolean }>({
+    type: 'list',
+    name: 'theme',
+    message: 'Is your plugin a theme?',
+    choices: [
+      { name: 'Yes', value: true },
+      { name: 'No', value: false },
+    ],
+    default: false,
+  })
+
+  generator.configuration.theme = answers.theme
+}
+
 export async function promptForText(
   generator: StarlightPluginGenerator,
-  key: keyof Configuration,
+  key: TextConfigurationKeys,
   message: string,
   defaultValue: string,
 ) {
@@ -65,3 +87,28 @@ export async function promptForEmoji(generator: StarlightPluginGenerator) {
 
   generator.configuration.emoji = answers.emoji
 }
+
+export async function promptForLayer(generator: StarlightPluginGenerator) {
+  const layer = generator.options.layer
+
+  if (layer && validateLayer(layer) === true) {
+    generator.configuration.layer = layer
+    return
+  }
+
+  const answers = await generator.prompt<{ layer: string }>({
+    type: 'input',
+    name: 'layer',
+    message: 'What is the name of your theme CSS cascade layer?',
+    default: `my-theme`,
+    validate: validateLayer,
+  })
+
+  generator.configuration.layer = answers.layer
+}
+
+type TextConfigurationKeys = NonNullable<
+  {
+    [K in keyof Configuration]: Configuration[K] extends string | undefined ? K : never
+  }[keyof Configuration]
+>

src/libs/validator.ts

@@ -1,5 +1,6 @@
 const nameValidationRegex = /^(?:@[\da-z~-][\d._a-z~-]*\/)?[\da-z~-][\d._a-z~-]*$/
 const emojiValidationRegex = /^\p{Emoji_Presentation}\p{Emoji_Modifier}*$/u
+const layerValidationRegex = /^[a-zA-Z][_a-zA-Z0-9-]*$/
 
 export function validateName(name: string) {
   return nameValidationRegex.test(name) ? true : 'Invalid plugin name'
@@ -12,3 +13,7 @@ export function validateNonEmptyString(value: string) {
 export function validateEmoji(emoji: string) {
   return emojiValidationRegex.test(emoji) ? true : 'Invalid emoji'
 }
+
+export function validateLayer(name: string) {
+  return layerValidationRegex.test(name) ? true : 'Invalid theme CSS cascade layer name'
+}

templates/packages/plugin/index.ts

@@ -4,7 +4,7 @@ export default function <%= importName %>(): StarlightPlugin {
   return {
     name: '<%= name %>',
     hooks: {
-      'config:setup'({ logger }) {
+      'config:setup'({ <% if(theme){ %>config, logger, updateConfig<% } else{ %>logger<% } %> }) {
         /**
          * This is the entry point of your Starlight plugin.
          * The `config:setup` hook is called when Starlight is initialized (during the Astro `astro:config:setup`
@@ -15,7 +15,17 @@ export default function <%= importName %>(): StarlightPlugin {
          * @see https://starlight.astro.build/reference/plugins/
          */
         logger.info('Hello from the <%= name %> plugin!')
-      },
+<% if (theme) { %>
+        /**
+         * Update the provided Starlight user configuration by appending the theme CSS file to the `customCss` array.
+         *
+         * @see https://starlight.astro.build/reference/plugins/#updateconfig
+         * @see https://starlight.astro.build/reference/configuration/#customcss
+         */
+        updateConfig({
+          customCss: [...(config.customCss ?? []), '<%= name %>/styles'],
+        })
+<% } -%>      },
     },
   }
 }

templates/packages/plugin/package.json

@@ -6,7 +6,8 @@
   "author": "<%= ghUsername %>",
   "type": "module",
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts"<% if (theme) { %>,
+    "./styles": "./styles.css"<% } %>
   },
   "devDependencies": {
     <%- dep("@astrojs/starlight") %>,

templates/styles.css

@@ -0,0 +1,59 @@
+/**
+ * Just like Starlight uses cascade layers to manage the order of its styles, the theme will also use its own layer.
+ * We first define a default, but still overridable, layer order for the theme relative to Starlight's layers.
+ *
+ * @see https://starlight.astro.build/guides/css-and-tailwind/#cascade-layers
+ * @see https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers
+ */
+@layer starlight, <%= layer %>;
+
+/**
+ * Scope the theme styles to its own layer so that user styles can override them easily.
+ */
+@layer <%= layer %> {
+  :root,
+  ::backdrop {
+    /**
+     * Override some CSS custom properties used by Starlight for the dark theme.
+     *
+     * @see https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css
+     */
+    --sl-color-accent-low: #002b27;
+    --sl-color-accent: #007a72;
+    --sl-color-accent-high: #8cdad0;
+    --sl-color-white: #ffffff;
+    --sl-color-gray-1: #ffe6ec;
+    --sl-color-gray-2: #edadbf;
+    --sl-color-gray-3: #d45d86;
+    --sl-color-gray-4: #982353;
+    --sl-color-gray-5: #6b0034;
+    --sl-color-gray-6: #4d0024;
+    --sl-color-black: #320316;
+  }
+
+  :root[data-theme='light'],
+  [data-theme='light'] ::backdrop {
+    /**
+     * Override some CSS custom properties used by Starlight for the light theme.
+     */
+    --sl-color-accent-low: #abe4dc;
+    --sl-color-accent: #007169;
+    --sl-color-accent-high: #003b36;
+    --sl-color-white: #320316;
+    --sl-color-gray-1: #4d0024;
+    --sl-color-gray-2: #6b0034;
+    --sl-color-gray-3: #982353;
+    --sl-color-gray-4: #d45d86;
+    --sl-color-gray-5: #edadbf;
+    --sl-color-gray-6: #ffe6ec;
+    --sl-color-gray-7: #fff3f6;
+    --sl-color-black: #ffffff;
+  }
+
+  /**
+   * Add rounded corners to cards.
+   */
+  .card {
+    border-radius: 0.75rem;
+  }
+}