@poveste/shared 0.1.0

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './codegen/index.js'
+export * from './state.js'
+export * from './story.js'
+export * from './type-utils.js'
+export * from './types/index.js'

package/src/state.ts

@@ -0,0 +1,42 @@
+export function clone(data) {
+  try {
+    return structuredClone(data)
+  }
+  catch (e) {
+    console.warn(e, `Fallback to JSON cloning`)
+    try {
+      return JSON.parse(JSON.stringify(data))
+    }
+    catch (e) {
+      console.error(e)
+    }
+    return data
+  }
+}
+
+export function omit(data, keys: string[]) {
+  const copy = {}
+  for (const key in data) {
+    if (!keys.includes(key)) {
+      copy[key] = data[key]
+    }
+  }
+  return copy
+}
+
+export function applyState(target: any, state: any, override = false) {
+  for (const key in state) {
+    // iframe sync needs to update properties without overriding them
+    if (!override && target[key] && !key.startsWith('_h') && typeof target[key] === 'object' && !Array.isArray(target[key])) {
+      Object.assign(target[key], state[key])
+    }
+    else {
+      try {
+        target[key] = state[key]
+      }
+      catch (e) {
+        // noop
+      }
+    }
+  }
+}

package/src/story.ts

@@ -0,0 +1,10 @@
+export const omitInheritStoryProps = [
+  'id',
+  'title',
+  'group',
+  'layout',
+  'variants',
+  'file',
+  'slots',
+  'lastSelectedVariant',
+]

package/src/type-utils.ts

@@ -0,0 +1 @@
+export type Awaitable<T> = Promise<T> | T

package/src/types/command.ts

@@ -0,0 +1,38 @@
+import type { RouteLocationNormalizedLoaded } from 'vue-router'
+import type { Prompt } from './prompt.js'
+import type { Story, Variant } from './story.js'
+
+export interface CommonCommandOptions {
+  icon?: string
+  searchText?: string
+  prompts?: Prompt[]
+}
+
+export interface Command extends CommonCommandOptions {
+  id: string
+  label: string
+}
+
+export interface ClientCommandOptions extends CommonCommandOptions {
+  showIf?: (ctx: ClientCommandContext) => boolean
+  getParams?: (ctx: ClientCommandContext & { answers?: Record<string, any> }) => Record<string, any>
+  clientAction?: (params: Record<string, any>, ctx: ClientCommandContext) => unknown
+}
+
+/**
+ * A command that can be executed from the search bar.
+ */
+export type ClientCommand = Command & ClientCommandOptions
+
+export interface ClientCommandContext {
+  route: RouteLocationNormalizedLoaded
+  currentStory: Story
+  currentVariant: Variant
+}
+
+export interface PluginCommand<
+  TParams = Record<string, any>,
+> extends Command {
+  serverAction?: (params: TParams) => unknown // @TODO ctx
+  clientSetupFile?: string | { file: string, importName: string }
+}

package/src/types/config.ts

@@ -0,0 +1,252 @@
+import type MarkdownIt from 'markdown-it'
+import type {
+  UserConfig as ViteConfig,
+  ConfigEnv as ViteConfigEnv,
+} from 'vite'
+import type { Plugin } from './plugin.js'
+import type { ServerTreeFile, StoryProps } from './story.js'
+
+export interface SupportMatchPattern {
+  id: string
+  patterns: string[]
+  pluginIds: string[]
+}
+
+export type CustomizableColors = 'primary' | 'gray'
+export type ColorKeys = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'
+export type GrayColorKeys = ColorKeys | '750' | '850' | '950'
+
+export interface ResponsivePreset {
+  label: string
+  width: number
+  height?: number
+}
+
+export interface BackgroundPreset {
+  label: string
+  color: string
+  contrastColor?: string
+}
+
+export interface TreeGroupConfig {
+  title: string
+  id?: string
+  include?: (file: ServerTreeFile) => boolean
+}
+
+/**
+ * @deprecated Use `PovesteConfig` instead. Kept for drop-in compat with histoire.
+ */
+export type HistoireConfig = PovesteConfig
+
+export interface PovesteConfig {
+  plugins: Plugin[]
+  /**
+   * Output directory.
+   */
+  outDir: string
+  /**
+   * Glob patterns for story files to include.
+   */
+  storyMatch: string[]
+  /**
+   * Glob patterns to ignore files while searching for story files.
+   */
+  storyIgnored: string[]
+  /**
+   * Patterns to match stories to support plugins automatically.
+   */
+  supportMatch: SupportMatchPattern[]
+  /**
+   * How to generate the story tree.
+   */
+  tree: {
+    /**
+     * Use `'title'` to create the path from the title of the story, using `/` as the separator.
+     *
+     * Use `'path'` use the real folder structure on your computer.
+     */
+    file?: 'title' | 'path' | ((file: ServerTreeFile) => string[])
+    order?: 'asc' | ((a: string, b: string) => number)
+    groups?: TreeGroupConfig[]
+  }
+  /**
+   * Customize the look of the histoire book.
+   */
+  theme: {
+    /**
+     * Main page title. For example: 'Acme Inc.'
+     */
+    title?: string
+    /**
+     * Custom logo files. Should be import paths (processed by Vite).
+     *
+     * Example: `'/src/assets/my-logo.svg'`
+     */
+    logo?: {
+      /**
+       * Square logo without text.
+       */
+      square?: string
+      /**
+       * Full logo for light theme.
+       */
+      light?: string
+      /**
+       * Full logo for dark theme.
+       */
+      dark?: string
+    }
+    /**
+     * Href to the favicon file (**not** processed by Vite). Put the file in the `public` directory.
+     *
+     * Example: `'/favicon.ico'`
+     */
+    favicon?: string
+    /**
+     * Customize the colors. Each color should be an object with shades as keys.
+     *
+     * Example: ```{ primary: { 50: '#eef2ff', 100: '#e0e7ff', ..., 900: '#312e81' } }```
+     *
+     * You can import `defaultColors` from `'poveste'` to use predefined colors or you can create your own colors from scratch.
+     */
+    colors?: {
+      [key in CustomizableColors]?: key extends 'gray' ? {
+        [key in GrayColorKeys]?: string
+      } : {
+        [key in ColorKeys]?: string
+      }
+    }
+    /**
+     * Add a link to the main logo
+     */
+    logoHref?: string
+    /**
+     * Default color scheme for the app.
+     */
+    defaultColorScheme?: 'light' | 'dark' | 'auto'
+    /**
+     * Hides the dark mode button in the toolbar.
+     */
+    hideColorSchemeSwitch?: boolean
+    /**
+     * Enable persistence of the color scheme in the browser.
+     */
+    storeColorScheme?: boolean
+    /**
+     * Class added to the story preview when dark mode is enabled.
+     */
+    darkClass?: string
+  }
+  /**
+   * Setup file exporting a default function executed when setting up each story preview.
+   *
+   * Import custom CSS files from this file.
+   *
+   * Example: `'/src/histoire-setup.ts'`
+   */
+  setupFile?: string | {
+    /**
+     * Only loaded in the browser client.
+     */
+    browser: string
+  } | {
+    /**
+     * Only loaded while collecting stories in the node server.
+     */
+    server: string
+  } | {
+    /**
+     * Only loaded in the browser client.
+     */
+    browser: string
+    /**
+     * Only loaded while collecting stories in the node server.
+     */
+    server: string
+  }
+  /**
+   * Setup code created by plugins
+   */
+  setupCode?: string[]
+  /**
+   * Predefined responsive sizes for story playgrounds.
+   */
+  responsivePresets?: ResponsivePreset[]
+  /**
+   * Background color of the story preview.
+   */
+  backgroundPresets?: BackgroundPreset[]
+  /**
+   * Automatically apply the current background preset's contrast color to the story preview text.
+   */
+  autoApplyContrastColor?: boolean
+  /**
+   * Class added to the html root of the story preview when dark mode is enabled.
+   * @deprecated use `theme.darkClass` instead
+   */
+  sandboxDarkClass?: string
+  /**
+   * Default props for stories.
+   */
+  defaultStoryProps?: Omit<StoryProps, 'id' | 'setupApp' | 'title' | 'source'>
+  /**
+   * Customize the markdown-it renderer
+   */
+  markdown?: (md: MarkdownIt) => MarkdownIt | Promise<MarkdownIt>
+  /**
+   * Change the router mode.
+   * - history: use HTML history with cleaner URLs
+   * - hash: use hashtag hack in the URL to support more hosting services
+   */
+  routerMode?: 'history' | 'hash'
+  /**
+   * Vite config override
+   */
+  vite?: ViteConfig | ((config: ViteConfig, env: ViteConfigEnv) => void | ViteConfig | Promise<void | ViteConfig>)
+  /**
+   * Remove those plugins from the Vite configuration
+   */
+  viteIgnorePlugins?: string[]
+  /**
+   * Transpile dependencies when collecting stories on Node.js
+   */
+  viteNodeInlineDeps?: (string | RegExp)[]
+  /**
+   * Determine the transform method of modules
+   */
+  viteNodeTransformMode?: {
+    /**
+     * Use SSR transform pipeline for the specified files.
+     * Vite plugins will receive `ssr: true` flag when processing those files.
+     *
+     * @default [/\.([cm]?[jt]sx?|json)$/]
+     */
+    ssr?: RegExp[]
+    /**
+     * First do a normal transform pipeline (targeting browser),
+     * then then do a SSR rewrite to run the code in Node.
+     * Vite plugins will receive `ssr: false` flag when processing those files.
+     *
+     * @default other than `ssr`
+     */
+    web?: RegExp[]
+  }
+  /**
+   * Maximum number of threads used to collect stories.
+   * By default based on available number of cores.
+   */
+  collectMaxThreads?: number
+  /**
+   * Build options
+   */
+  build?: {
+    /**
+     * By default all dependencies in `node_modules` are bundled into a single 'vendors' file.
+     * You can use this option to exclude some dependencies from this file.
+     */
+    excludeFromVendorsChunk?: (string | RegExp)[]
+  }
+}
+
+export type ConfigMode = 'build' | 'dev'

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from './command.js'
+export * from './config.js'
+export * from './plugin.js'
+export * from './prompt.js'
+export * from './story.js'

package/src/types/plugin.ts

@@ -0,0 +1,135 @@
+import type chokidar from 'chokidar'
+import type fs from 'fs-extra'
+import type path from 'pathe'
+import type pc from 'picocolors'
+import type { InlineConfig as ViteInlineConfig, Plugin as VitePlugin } from 'vite'
+import type { Awaitable } from '../type-utils.js'
+import type {
+  PluginCommand,
+} from './command.js'
+import type {
+  ConfigMode,
+  PovesteConfig,
+} from './config.js'
+import type {
+  ServerStory,
+  ServerStoryFile,
+  ServerVariant,
+} from './story.js'
+
+export interface SupportPlugin {
+  id: string
+  moduleName: string
+  setupFn: string | string[]
+  importStoriesPrepend?: string
+  importStoryComponent: (file: ServerStoryFile, index: number) => string
+}
+
+export interface FinalSupportPlugin extends SupportPlugin {
+  // For now, no additional properties
+}
+
+export interface ModuleLoader {
+  clearCache: () => void
+  loadModule: (file: string) => Promise<any>
+  destroy: () => void
+}
+
+export interface PluginApiBase {
+  colors: typeof pc
+  path: typeof path
+  fs: typeof fs
+  moduleLoader: ModuleLoader
+
+  readonly pluginTempDir: string
+
+  log: (...msg) => void
+  warn: (...msg) => void
+  error: (...msg) => void
+
+  getStories: () => ServerStory[]
+  addStoryFile: (file: string) => void
+
+  getConfig: () => PovesteConfig
+}
+
+export interface PluginApiDev extends PluginApiBase {
+  watcher: typeof chokidar
+}
+
+export type ChangeViteConfigCallback = (config: ViteInlineConfig) => Awaitable<void>
+export type BuildEndCallback = () => Awaitable<void>
+export type PreviewStoryCallback = (payload: { file: string, story: ServerStory, variant: ServerVariant, url: string }) => Awaitable<void>
+
+export interface PluginApiBuild extends PluginApiBase {
+  changeViteConfigCallbacks: ChangeViteConfigCallback[]
+  buildEndCallbacks: BuildEndCallback[]
+  previewStoryCallbacks: PreviewStoryCallback[]
+
+  changeViteConfig: (cb: ChangeViteConfigCallback) => void
+  onBuildEnd: (cb: BuildEndCallback) => void
+  onPreviewStory: (cb: PreviewStoryCallback) => void
+}
+
+export interface PluginApiDevEvent extends PluginApiBase {
+  event: string
+  payload: any
+}
+
+export interface Plugin {
+  /**
+   * Name of the plugin
+   */
+  name: string
+  /**
+   * Modify histoire default config. The hook can either mutate the passed config or
+   * return a partial config object that will be deeply merged into the existing
+   * config. User config will have higher priority than default config.
+   *
+   * Note: User plugins are resolved before running this hook so injecting other
+   * plugins inside  the `config` hook will have no effect.
+   */
+  defaultConfig?: (defaultConfig: PovesteConfig, mode: ConfigMode) => Partial<PovesteConfig> | null | void | Promise<Partial<PovesteConfig> | null | void>
+  /**
+   * Modify histoire config. The hook can either mutate the passed config or
+   * return a partial config object that will be deeply merged into the existing
+   * config.
+   *
+   * Note: User plugins are resolved before running this hook so injecting other
+   * plugins inside  the `config` hook will have no effect.
+   */
+  config?: (config: PovesteConfig, mode: ConfigMode) => Partial<PovesteConfig> | null | void | Promise<Partial<PovesteConfig> | null | void>
+  /**
+   * Use this hook to read and store the final resolved histoire config.
+   */
+  configResolved?: (config: PovesteConfig) => Awaitable<void>
+  /**
+   * Use this hook to do processing during development. The `onCleanup` hook
+   * should handle cleanup tasks when development server is closed.
+   */
+  onDev?: (api: PluginApiDev, onCleanup: (cb: () => Awaitable<void>) => void) => Awaitable<void>
+  /**
+   * Use this hook to do processing during production build.
+   */
+  onBuild?: (api: PluginApiBuild) => Awaitable<void>
+  /**
+   * Use this hook to do processing when preview is started.
+   */
+  onPreview?: () => Awaitable<void>
+  /**
+   * This plugin exposes a support plugin (example: Vue, Svelte, etc.)
+   */
+  supportPlugin?: SupportPlugin
+  /**
+   * This plugin exposes commands that can be executed from the search bar in development mode.
+   */
+  commands?: PluginCommand[]
+  /**
+   * Handle a custom event from the client in development mode.
+   */
+  onDevEvent?: (api: PluginApiDevEvent) => Awaitable<any>
+  /**
+   * Use this hook to manipulate Vite plugins before they are passed to Vite.
+   */
+  vitePlugins?: (plugins: VitePlugin[]) => Awaitable<void>
+}

package/src/types/prompt.ts

@@ -0,0 +1,22 @@
+import type { Awaitable } from '../type-utils.js'
+
+export interface PromptBase<TValue> {
+  field: string
+  label: string
+  required?: boolean
+  defaultValue?: TValue | ((answers: Record<string, any>) => TValue)
+}
+
+export interface TextPrompt extends PromptBase<string> {
+  type: 'text'
+}
+
+export type SelectPromptOption = string | { value: string, label: string }
+
+export interface SelectPrompt extends PromptBase<string> {
+  type: 'select'
+  options: SelectPromptOption[] | ((search: string, answers: Record<string, any>) => Awaitable<SelectPromptOption[]>)
+}
+
+export type Prompt<TValue = any> = TextPrompt
+  | SelectPrompt