@histoire/shared 0.10.2 → 0.10.5

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from './codegen/index.js';
-export * from './types.js';
+export * from './types/index.js';
 export * from './state.js';
 export * from './type-utils.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export * from './codegen/index.js';
-export * from './types.js';
+export * from './types/index.js';
 export * from './state.js';
 export * from './type-utils.js';

package/dist/types/config.d.ts

@@ -0,0 +1,173 @@
+import type { UserConfig as ViteConfig, ConfigEnv as ViteConfigEnv } from 'vite';
+import type MarkdownIt from 'markdown-it';
+import type { ServerTreeFile } from './story.js';
+import type { Plugin } from './plugin.js';
+export interface SupportMatchPattern {
+    id: string;
+    patterns: string[];
+    pluginIds: string[];
+}
+export declare type CustomizableColors = 'primary' | 'gray';
+export declare type ColorKeys = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+export declare type GrayColorKeys = ColorKeys | '750' | '850' | '950';
+export interface ResponsivePreset {
+    label: string;
+    width: number;
+    height: number;
+}
+export interface BackgroundPreset {
+    label: string;
+    color: string;
+}
+export interface TreeGroupConfig {
+    title: string;
+    id?: string;
+    include?: (file: ServerTreeFile) => boolean;
+}
+export interface HistoireConfig {
+    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 `'histoire'` 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;
+    };
+    /**
+     * 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;
+    /**
+     * Setup code created by plugins
+     */
+    setupCode?: string[];
+    /**
+     * Predefined responsive sizes for story playgrounds.
+     */
+    responsivePresets?: ResponsivePreset[];
+    /**
+     * Background color of the story preview.
+     */
+    backgroundPresets?: BackgroundPreset[];
+    /**
+     * Class added to the html root of the story preview when dark mode is enabled.
+     */
+    sandboxDarkClass?: string;
+    /**
+     * 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>);
+    /**
+     * Transpile dependencies when collecting stories on Node.js
+     */
+    viteNodeInlineDeps?: 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[];
+    };
+}
+export declare type ConfigMode = 'build' | 'dev';

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './config.js';
+export * from './plugin.js';
+export * from './story.js';

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export * from './config.js';
+export * from './plugin.js';
+export * from './story.js';

package/dist/types/plugin.d.ts

@@ -0,0 +1,88 @@
+import type path from 'pathe';
+import type fs from 'fs-extra';
+import type pc from 'picocolors';
+import type chokidar from 'chokidar';
+import type { ServerStoryFile, ServerStory, ServerVariant } from './story.js';
+import type { HistoireConfig, ConfigMode } from './config.js';
+export interface SupportPlugin {
+    id: string;
+    moduleName: string;
+    setupFn: string;
+    importStoriesPrepend?: string;
+    importStoryComponent: (file: ServerStoryFile, index: number) => string;
+}
+export interface FinalSupportPlugin extends SupportPlugin {
+}
+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: any[]) => void;
+    warn: (...msg: any[]) => void;
+    error: (...msg: any[]) => void;
+    addStoryFile: (file: string) => void;
+}
+export interface PluginApiDev extends PluginApiBase {
+    watcher: typeof chokidar;
+}
+export declare type BuildEndCallback = () => Promise<void> | void;
+export declare type PreviewStoryCallback = (payload: {
+    file: string;
+    story: ServerStory;
+    variant: ServerVariant;
+    url: string;
+}) => Promise<void> | void;
+export interface PluginApiBuild extends PluginApiBase {
+    buildEndCallbacks: BuildEndCallback[];
+    previewStoryCallbacks: PreviewStoryCallback[];
+    onBuildEnd: (cb: BuildEndCallback) => void;
+    onPreviewStory: (cb: PreviewStoryCallback) => void;
+}
+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: HistoireConfig, mode: ConfigMode) => Partial<HistoireConfig> | null | void | Promise<Partial<HistoireConfig> | 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: HistoireConfig, mode: ConfigMode) => Partial<HistoireConfig> | null | void | Promise<Partial<HistoireConfig> | null | void>;
+    /**
+     * Use this hook to read and store the final resolved histoire config.
+     */
+    configResolved?: (config: HistoireConfig) => void | Promise<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: () => void | Promise<void>) => void) => void | Promise<void>;
+    /**
+     * Use this hook to do processing during production build.
+     */
+    onBuild?: (api: PluginApiBuild) => void | Promise<void>;
+    /**
+     * This plugin exposes a support plugin (example: Vue, Svelte, etc.)
+     */
+    supportPlugin?: SupportPlugin;
+}

package/dist/types/plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/{types.d.ts → types/story.d.ts}

@@ -169,12 +169,3 @@ export interface ServerRunPayload {
     storyData: ServerStory[];
     el: HTMLElement;
 }
-export interface SupportPlugin {
-    id: string;
-    moduleName: string;
-    setupFn: string;
-    importStoriesPrepend?: string;
-    importStoryComponent: (file: ServerStoryFile, index: number) => string;
-}
-export interface FinalSupportPlugin extends SupportPlugin {
-}

package/dist/types/story.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@histoire/shared",
-  "version": "0.10.2",
+  "version": "0.10.5",
   "description": "Shared utilities for Histoire",
   "license": "MIT",
   "author": {
@@ -24,9 +24,19 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
-  "dependencies": {},
+  "dependencies": {
+    "@types/fs-extra": "^9.0.13",
+    "@types/markdown-it": "^12.2.3",
+    "chokidar": "^3.5.3",
+    "pathe": "^0.2.0",
+    "picocolors": "^1.0.0"
+  },
+  "peerDependencies": {
+    "vite": "^2.9.0 || ^3.0.0"
+  },
   "devDependencies": {
-    "typescript": "^4.7.4"
+    "typescript": "^4.7.4",
+    "vite": "^3.0.5"
   },
   "scripts": {
     "build": "rimraf dist && tsc -d",

package/src/index.ts

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

package/src/types/config.ts

@@ -0,0 +1,183 @@
+import type {
+  UserConfig as ViteConfig,
+  ConfigEnv as ViteConfigEnv,
+} from 'vite'
+import type MarkdownIt from 'markdown-it'
+import type { ServerTreeFile } from './story.js'
+import type { Plugin } from './plugin.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
+}
+
+export interface TreeGroupConfig {
+  title: string
+  id?: string
+  include?: (file: ServerTreeFile) => boolean
+}
+
+export interface HistoireConfig {
+  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 `'histoire'` 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
+  }
+  /**
+   * 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
+  /**
+   * Setup code created by plugins
+   */
+  setupCode?: string[]
+  /**
+   * Predefined responsive sizes for story playgrounds.
+   */
+  responsivePresets?: ResponsivePreset[]
+  /**
+   * Background color of the story preview.
+   */
+  backgroundPresets?: BackgroundPreset[]
+  /**
+   * Class added to the html root of the story preview when dark mode is enabled.
+   */
+  sandboxDarkClass?: string
+  /**
+   * 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>)
+  /**
+   * Transpile dependencies when collecting stories on Node.js
+   */
+  viteNodeInlineDeps?: 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[]
+  }
+}
+
+export type ConfigMode = 'build' | 'dev'

package/src/types/index.ts

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

package/src/types/plugin.ts

@@ -0,0 +1,103 @@
+import type path from 'pathe'
+import type fs from 'fs-extra'
+import type pc from 'picocolors'
+import type chokidar from 'chokidar'
+import type {
+  ServerStoryFile,
+  ServerStory,
+  ServerVariant,
+} from './story.js'
+import type {
+  HistoireConfig,
+  ConfigMode,
+} from './config.js'
+
+export interface SupportPlugin {
+  id: string
+  moduleName: string
+  setupFn: 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
+
+  addStoryFile: (file: string) => void
+}
+
+export interface PluginApiDev extends PluginApiBase {
+  watcher: typeof chokidar
+}
+
+export type BuildEndCallback = () => Promise<void> | void
+export type PreviewStoryCallback = (payload: { file: string, story: ServerStory, variant: ServerVariant, url: string }) => Promise<void> | void
+
+export interface PluginApiBuild extends PluginApiBase {
+  buildEndCallbacks: BuildEndCallback[]
+  previewStoryCallbacks: PreviewStoryCallback[]
+
+  onBuildEnd: (cb: BuildEndCallback) => void
+  onPreviewStory: (cb: PreviewStoryCallback) => void
+}
+
+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: HistoireConfig, mode: ConfigMode) => Partial<HistoireConfig> | null | void | Promise<Partial<HistoireConfig> | 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: HistoireConfig, mode: ConfigMode) => Partial<HistoireConfig> | null | void | Promise<Partial<HistoireConfig> | null | void>
+  /**
+   * Use this hook to read and store the final resolved histoire config.
+   */
+  configResolved?: (config: HistoireConfig) => void | Promise<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: () => void | Promise<void>) => void) => void | Promise<void>
+  /**
+   * Use this hook to do processing during production build.
+   */
+  onBuild?: (api: PluginApiBuild) => void | Promise<void>
+  /**
+   * This plugin exposes a support plugin (example: Vue, Svelte, etc.)
+   */
+  supportPlugin?: SupportPlugin
+}

package/src/{types.ts → types/story.ts}

@@ -188,15 +188,3 @@ export interface ServerRunPayload {
   storyData: ServerStory[]
   el: HTMLElement
 }
-
-export interface SupportPlugin {
-  id: string
-  moduleName: string
-  setupFn: string
-  importStoriesPrepend?: string
-  importStoryComponent: (file: ServerStoryFile, index: number) => string
-}
-
-export interface FinalSupportPlugin extends SupportPlugin {
-  // For now, no additional properties
-}