kss-modern 1.1.0 → 1.2.0-beta.1

package/README.md

@@ -89,7 +89,7 @@ Markup: templates/components/card.pug
 ```bash
 bun install
 bun run build          # Build: Vite (client assets) then Unbuild (Node.js library)
-bun run dev            # Build + run dev server with Deno (watches test/ content)
+bun run dev            # Build + run dev server with Deno (watches test-styleguide/ content)
 bun run lint           # ESLint
 bun run test           # Vitest unit + integration tests
 bun run release        # Lint + version bump via bumpp

package/dist/node/lib/index.d.mts

@@ -1,3 +1,9 @@
+interface SectionMeta {
+    modifiers: {
+        name: string;
+    }[];
+}
+
 interface ColorObject {
     name?: string;
     color: string;
@@ -44,6 +50,45 @@ interface in2SecondLevelSection extends in2Section {
     sections: in2Section[];
 }
 
+/** Title + message for a boxed log entry. */
+interface LogBox {
+    title: string;
+    message: string;
+}
+/**
+ * Styleguide logger. Intentionally a small, fixed surface so the underlying
+ * logging library (currently consola) stays an implementation detail and can
+ * be swapped without touching call sites.
+ *
+ * The message methods are variadic pass-throughs, so a leading message can be
+ * paired with an Error/unknown value — `logger.error('Build failed', err)` —
+ * and consola renders the error (and its stack) below the message.
+ */
+interface Logger {
+    /** Informational message. */
+    info: (message: unknown, ...args: unknown[]) => void;
+    /** Successful operation. */
+    success: (message: unknown, ...args: unknown[]) => void;
+    /** Non-fatal warning. */
+    warn: (message: unknown, ...args: unknown[]) => void;
+    /** Error — a message, an Error/unknown value, or a message followed by one. */
+    error: (message: unknown, ...args: unknown[]) => void;
+    /** Boxed, highlighted message used for grouped summaries. */
+    box: (box: LogBox) => void;
+}
+/**
+ * Create a {@link Logger} backed by consola. consola is wrapped rather than
+ * exposed directly so consumers depend only on the {@link Logger} contract.
+ *
+ * Every entry leads with a blue `tag` badge — styled like consola's own
+ * WARN/ERROR badges — passed as part of the message so it always sits at the
+ * start of the line. (consola's built-in `tag` option is right-aligned by the
+ * fancy reporter and scrolls off a wide terminal.)
+ */
+declare function createLogger(tag?: string): Logger;
+/** Shared styleguide logger instance. */
+declare const logger: Logger;
+
 interface StyleguideConfiguration {
     mode: 'development' | 'production';
     outDir: string;
@@ -85,6 +130,43 @@ interface StyleguideBuildOutput {
         overwrittenSectionsIds?: string[];
     };
 }
+interface MenuSectionMapping {
+    title: string;
+    items: {
+        label: string;
+        href: string;
+        status?: string;
+    }[];
+}
+/**
+ * Expensive, parse-derived state computed once and reused across incremental rebuilds.
+ * A markup-only edit never changes section structure, so the parsed tree, navigation mappings,
+ * and lookups stay valid; only affected sections are recompiled and rewritten.
+ */
+interface StyleguideContext {
+    baseDirectory: string;
+    parsedContent: in2FirstLevelSection[];
+    overwrittenSectionsIds: string[];
+    sectionsById: Map<string, SectionMeta>;
+    /** section id -> original (pre-compile) markup, i.e. the compile input */
+    rawMarkupBySection: Map<string, string>;
+    /** section id -> compiled markup that is NOT yet <insert-markup>-resolved (persistent) */
+    compiledRepository: Map<string, {
+        markup: string;
+    }>;
+    /** refId -> ids whose compiled markup embeds <insert-markup>refId</insert-markup> */
+    insertMarkupConsumers: Map<string, Set<string>>;
+    headerHtml: string;
+    searchHtml: string;
+    menuSectionMapping: MenuSectionMapping[];
+    /** section id (second & third level) -> its parsed node */
+    nodeById: Map<string, in2Section>;
+    /** any section id -> the location of its owning second-level section (for preview regen) */
+    ownerLocationById: Map<string, {
+        firstLevelIndex: number;
+        secondLevelIndex: number;
+    }>;
+}
 /**
  * Parse given contentDir and get structured data for further processing
  */
@@ -92,18 +174,44 @@ declare function parseStyleguide(contentDir: StyleguideConfiguration['contentDir
     content: in2FirstLevelSection[];
     overwrittenSectionsIds: string[];
 }>;
+/**
+ * Full build: parse, compile every section, and write all fullpage + preview files. Returns the
+ * reusable context so the watcher can perform targeted incremental rebuilds afterwards.
+ */
+declare function buildAll(config: StyleguideConfiguration): Promise<{
+    errors: StyleguideBuildOutput['errors'];
+    context: StyleguideContext;
+}>;
 /**
  * Builds the styleguide
  * @param config - The configuration for the styleguide
  */
 declare function buildStyleguide(config: StyleguideConfiguration): Promise<StyleguideBuildOutput>;
+/**
+ * Incrementally rebuild only the sections affected by a markup change: recompile their pug
+ * (cache-aware), re-resolve <insert-markup>, and rewrite just their fullpage + owning preview files.
+ * `changedSectionIds` are the sections whose pug (or a dependency) changed.
+ */
+declare function rebuildSections(config: StyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
+/**
+ * What triggered a {@link watchStyleguide} rebuild:
+ * - `structural` — a CSS/SCSS/Markdown edit that can change section structure; the whole styleguide is rebuilt.
+ * - `markup` — a Pug/HTML edit; only `sections` (those depending on `file`) are rebuilt.
+ */
+type StyleguideChange = {
+    type: 'structural';
+} | {
+    type: 'markup';
+    file: string;
+    sections: string[];
+};
 /**
  * Builds the styleguide and watches for changes
  * @param config - The configuration for the styleguide
- * @param onChange - Optional callback function to call when the styleguide is changed
+ * @param onChange - Optional callback invoked after each rebuild, with the change that triggered it
  * @param onError - Optional callback function to call when an error occurs while building the styleguide
  */
-declare function watchStyleguide(config: StyleguideConfiguration, onChange?: () => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
+declare function watchStyleguide(config: StyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
 
-export { buildStyleguide, parseStyleguide, watchStyleguide };
-export type { StyleguideConfiguration };
+export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, watchStyleguide };
+export type { LogBox, Logger, StyleguideChange, StyleguideConfiguration, StyleguideContext };

package/dist/node/lib/index.d.ts

@@ -1,3 +1,9 @@
+interface SectionMeta {
+    modifiers: {
+        name: string;
+    }[];
+}
+
 interface ColorObject {
     name?: string;
     color: string;
@@ -44,6 +50,45 @@ interface in2SecondLevelSection extends in2Section {
     sections: in2Section[];
 }
 
+/** Title + message for a boxed log entry. */
+interface LogBox {
+    title: string;
+    message: string;
+}
+/**
+ * Styleguide logger. Intentionally a small, fixed surface so the underlying
+ * logging library (currently consola) stays an implementation detail and can
+ * be swapped without touching call sites.
+ *
+ * The message methods are variadic pass-throughs, so a leading message can be
+ * paired with an Error/unknown value — `logger.error('Build failed', err)` —
+ * and consola renders the error (and its stack) below the message.
+ */
+interface Logger {
+    /** Informational message. */
+    info: (message: unknown, ...args: unknown[]) => void;
+    /** Successful operation. */
+    success: (message: unknown, ...args: unknown[]) => void;
+    /** Non-fatal warning. */
+    warn: (message: unknown, ...args: unknown[]) => void;
+    /** Error — a message, an Error/unknown value, or a message followed by one. */
+    error: (message: unknown, ...args: unknown[]) => void;
+    /** Boxed, highlighted message used for grouped summaries. */
+    box: (box: LogBox) => void;
+}
+/**
+ * Create a {@link Logger} backed by consola. consola is wrapped rather than
+ * exposed directly so consumers depend only on the {@link Logger} contract.
+ *
+ * Every entry leads with a blue `tag` badge — styled like consola's own
+ * WARN/ERROR badges — passed as part of the message so it always sits at the
+ * start of the line. (consola's built-in `tag` option is right-aligned by the
+ * fancy reporter and scrolls off a wide terminal.)
+ */
+declare function createLogger(tag?: string): Logger;
+/** Shared styleguide logger instance. */
+declare const logger: Logger;
+
 interface StyleguideConfiguration {
     mode: 'development' | 'production';
     outDir: string;
@@ -85,6 +130,43 @@ interface StyleguideBuildOutput {
         overwrittenSectionsIds?: string[];
     };
 }
+interface MenuSectionMapping {
+    title: string;
+    items: {
+        label: string;
+        href: string;
+        status?: string;
+    }[];
+}
+/**
+ * Expensive, parse-derived state computed once and reused across incremental rebuilds.
+ * A markup-only edit never changes section structure, so the parsed tree, navigation mappings,
+ * and lookups stay valid; only affected sections are recompiled and rewritten.
+ */
+interface StyleguideContext {
+    baseDirectory: string;
+    parsedContent: in2FirstLevelSection[];
+    overwrittenSectionsIds: string[];
+    sectionsById: Map<string, SectionMeta>;
+    /** section id -> original (pre-compile) markup, i.e. the compile input */
+    rawMarkupBySection: Map<string, string>;
+    /** section id -> compiled markup that is NOT yet <insert-markup>-resolved (persistent) */
+    compiledRepository: Map<string, {
+        markup: string;
+    }>;
+    /** refId -> ids whose compiled markup embeds <insert-markup>refId</insert-markup> */
+    insertMarkupConsumers: Map<string, Set<string>>;
+    headerHtml: string;
+    searchHtml: string;
+    menuSectionMapping: MenuSectionMapping[];
+    /** section id (second & third level) -> its parsed node */
+    nodeById: Map<string, in2Section>;
+    /** any section id -> the location of its owning second-level section (for preview regen) */
+    ownerLocationById: Map<string, {
+        firstLevelIndex: number;
+        secondLevelIndex: number;
+    }>;
+}
 /**
  * Parse given contentDir and get structured data for further processing
  */
@@ -92,18 +174,44 @@ declare function parseStyleguide(contentDir: StyleguideConfiguration['contentDir
     content: in2FirstLevelSection[];
     overwrittenSectionsIds: string[];
 }>;
+/**
+ * Full build: parse, compile every section, and write all fullpage + preview files. Returns the
+ * reusable context so the watcher can perform targeted incremental rebuilds afterwards.
+ */
+declare function buildAll(config: StyleguideConfiguration): Promise<{
+    errors: StyleguideBuildOutput['errors'];
+    context: StyleguideContext;
+}>;
 /**
  * Builds the styleguide
  * @param config - The configuration for the styleguide
  */
 declare function buildStyleguide(config: StyleguideConfiguration): Promise<StyleguideBuildOutput>;
+/**
+ * Incrementally rebuild only the sections affected by a markup change: recompile their pug
+ * (cache-aware), re-resolve <insert-markup>, and rewrite just their fullpage + owning preview files.
+ * `changedSectionIds` are the sections whose pug (or a dependency) changed.
+ */
+declare function rebuildSections(config: StyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
+/**
+ * What triggered a {@link watchStyleguide} rebuild:
+ * - `structural` — a CSS/SCSS/Markdown edit that can change section structure; the whole styleguide is rebuilt.
+ * - `markup` — a Pug/HTML edit; only `sections` (those depending on `file`) are rebuilt.
+ */
+type StyleguideChange = {
+    type: 'structural';
+} | {
+    type: 'markup';
+    file: string;
+    sections: string[];
+};
 /**
  * Builds the styleguide and watches for changes
  * @param config - The configuration for the styleguide
- * @param onChange - Optional callback function to call when the styleguide is changed
+ * @param onChange - Optional callback invoked after each rebuild, with the change that triggered it
  * @param onError - Optional callback function to call when an error occurs while building the styleguide
  */
-declare function watchStyleguide(config: StyleguideConfiguration, onChange?: () => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
+declare function watchStyleguide(config: StyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
 
-export { buildStyleguide, parseStyleguide, watchStyleguide };
-export type { StyleguideConfiguration };
+export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, watchStyleguide };
+export type { LogBox, Logger, StyleguideChange, StyleguideConfiguration, StyleguideContext };