@4kk11/cooklang-sankey 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,408 @@
+import { CooklangRecipe, Value, Quantity, Step } from '@cooklang/cooklang';
+export { Content, CooklangParser, CooklangRecipe, Ingredient, Item, Quantity, Section, Step, Value, getNumericValue, quantity_display } from '@cooklang/cooklang';
+
+/**
+ * Cooklang Parser wrapper using official @cooklang/cooklang package.
+ *
+ * @remarks
+ * This module provides a thin wrapper around the official Cooklang parser,
+ * re-exporting types and adding metadata extraction utilities.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Metadata extracted from a parsed Cooklang recipe.
+ *
+ * @remarks
+ * Contains standard recipe metadata fields plus any custom metadata
+ * defined in the recipe using the `>> key: value` syntax.
+ */
+interface RecipeMetadata {
+    /** Recipe title from `>> title:` */
+    title?: string;
+    /** Recipe description from `>> description:` */
+    description?: string;
+    /** Array of tags from `>> tags:` */
+    tags?: string[];
+    /** Formatted cooking time string (e.g., "prep: 10min, cook: 30min") */
+    cookingTime?: string;
+    /** Servings range or value (e.g., "4" or "4-6") */
+    servings?: string;
+    /** Additional custom metadata fields */
+    [key: string]: unknown;
+}
+/**
+ * Extracts metadata from a parsed Cooklang recipe.
+ *
+ * @param recipe - The parsed CooklangRecipe object
+ * @returns An object containing extracted metadata fields
+ *
+ * @example
+ * ```ts
+ * import { CooklangParser } from "@cooklang/cooklang";
+ * import { extractMetadata } from "./parser";
+ *
+ * const parser = new CooklangParser();
+ * const [recipe] = parser.parse(`
+ *   >> title: Pasta Carbonara
+ *   >> servings: 4
+ *   @pasta{400g} を茹でる
+ * `);
+ *
+ * const metadata = extractMetadata(recipe);
+ * // { title: "Pasta Carbonara", servings: "4" }
+ * ```
+ */
+declare function extractMetadata(recipe: CooklangRecipe): RecipeMetadata;
+
+/**
+ * Sankey diagram type definitions (framework-agnostic)
+ *
+ * @remarks
+ * These types are designed to be independent of any specific visualization library,
+ * allowing integration with D3.js, ECharts, or other charting libraries.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Category of a node in the Sankey diagram.
+ *
+ * - `ingredient` - Raw ingredients from the recipe
+ * - `process` - Cooking steps/processes
+ * - `final` - The completed dish
+ */
+type NodeCategory = "ingredient" | "process" | "final";
+/**
+ * Type of transformation occurring between nodes.
+ *
+ * - `cooking` - Heat-based transformation (frying, boiling, etc.)
+ * - `preparation` - Mechanical transformation (chopping, mixing, etc.)
+ * - `timing` - Time-based step (marinating, resting, etc.)
+ * - `combination` - Combining multiple ingredients
+ * - `completion` - Final step to complete the dish
+ */
+type TransformationType = "cooking" | "preparation" | "timing" | "combination" | "completion";
+/**
+ * Value extracted from an ingredient quantity.
+ *
+ * @example
+ * ```ts
+ * // Numeric value with unit
+ * const numericValue: ExtractedValue = {
+ *   type: "number",
+ *   value: 200,
+ *   label: "200g"
+ * };
+ *
+ * // Text-only value (e.g., "a pinch")
+ * const textValue: ExtractedValue = {
+ *   type: "text",
+ *   label: "a pinch"
+ * };
+ * ```
+ */
+type ExtractedValue = {
+    /** Indicates a numeric value was extracted */
+    type: "number";
+    /** The numeric portion of the quantity */
+    value: number;
+    /** Human-readable display label (e.g., "200g") */
+    label: string;
+} | {
+    /** Indicates only text was available */
+    type: "text";
+    /** Human-readable display label */
+    label: string;
+};
+/**
+ * Metadata associated with a node.
+ */
+interface BaseNodeMetadata {
+    /** Step number in the recipe (1-indexed) */
+    stepNumber?: number;
+    /** Name of the recipe section containing this node */
+    sectionName?: string;
+    /** Duration string for timer nodes (e.g., "5 minutes") */
+    timerDuration?: string;
+    /** Original index in the ingredient/step array */
+    originalIndex?: number;
+}
+/**
+ * Metadata associated with a link.
+ */
+interface BaseLinkMetadata {
+    /** Step number where this link originates */
+    stepNumber?: number;
+    /** Type of transformation this link represents */
+    transformationType?: TransformationType;
+}
+/**
+ * Base structure for a Sankey diagram node.
+ */
+interface BaseSankeyNode {
+    /** Unique identifier for the node */
+    id: string;
+    /** Display name of the node */
+    name: string;
+    /** Category of the node */
+    category: NodeCategory;
+    /** Normalized value for visualization sizing */
+    value: number;
+    /** Short label for display (e.g., step number, quantity) */
+    label: string;
+    /** Original value before normalization */
+    originalValue?: number;
+}
+/**
+ * Base structure for a Sankey diagram link.
+ */
+interface BaseSankeyLink {
+    /** ID of the source node */
+    source: string;
+    /** ID of the target node */
+    target: string;
+    /** Flow value determining link width */
+    value: number;
+    /** Original value before normalization */
+    originalValue?: number;
+}
+/**
+ * Sankey node with optional metadata.
+ *
+ * @see {@link BaseSankeyNode} for base properties
+ * @see {@link BaseNodeMetadata} for metadata properties
+ */
+interface SankeyNode extends BaseSankeyNode {
+    /** Additional node metadata */
+    metadata?: BaseNodeMetadata;
+}
+/**
+ * Sankey link with optional metadata.
+ *
+ * @see {@link BaseSankeyLink} for base properties
+ * @see {@link BaseLinkMetadata} for metadata properties
+ */
+interface SankeyLink extends BaseSankeyLink {
+    /** Additional link metadata */
+    metadata?: BaseLinkMetadata;
+}
+/**
+ * Complete Sankey diagram data structure.
+ *
+ * @example
+ * ```ts
+ * const data: SankeyData = {
+ *   nodes: [
+ *     { id: "0", name: "flour", category: "ingredient", value: 1, label: "200g" },
+ *     { id: "step_main_1", name: "Mix ingredients", category: "process", value: 1, label: "1" },
+ *     { id: "final_dish", name: "Bread", category: "final", value: 1, label: "" }
+ *   ],
+ *   links: [
+ *     { source: "0", target: "step_main_1", value: 1 },
+ *     { source: "step_main_1", target: "final_dish", value: 1 }
+ *   ]
+ * };
+ * ```
+ */
+interface SankeyData {
+    /** Array of nodes in the diagram */
+    nodes: SankeyNode[];
+    /** Array of links connecting nodes */
+    links: SankeyLink[];
+}
+/**
+ * DAG (Directed Acyclic Graph) node with dependency tracking.
+ *
+ * @remarks
+ * Extends SankeyNode with input/output arrays for topological sorting
+ * and value propagation calculations.
+ *
+ * @see {@link SankeyNode} for base properties
+ */
+interface DAGNode extends SankeyNode {
+    /** IDs of nodes that flow into this node */
+    inputs: string[];
+    /** IDs of nodes that this node flows to */
+    outputs: string[];
+}
+/**
+ * Edge in the DAG representing a flow between nodes.
+ */
+interface DAGEdge {
+    /** ID of the source node */
+    from: string;
+    /** ID of the target node */
+    to: string;
+    /** Additional edge metadata */
+    metadata?: BaseLinkMetadata;
+}
+
+/**
+ * Sankey diagram data generator from Cooklang recipes.
+ *
+ * @remarks
+ * Main module for transforming parsed Cooklang recipes into
+ * Sankey diagram data structures. Orchestrates the DAG building,
+ * value calculation, and normalization pipeline.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Configuration options for Sankey diagram generation.
+ *
+ * @example
+ * ```ts
+ * const options: SankeyGeneratorOptions = {
+ *   finalNodeName: "Carbonara",
+ *   normalization: "logarithmic",
+ *   minLinkValue: 0.1
+ * };
+ * ```
+ */
+interface SankeyGeneratorOptions {
+    /**
+     * Display name for the final dish node.
+     * @defaultValue "完成品"
+     */
+    finalNodeName?: string;
+    /**
+     * Method for normalizing ingredient values.
+     * - `logarithmic`: Compress large ranges (recommended)
+     * - `linear`: Linear scaling
+     * - `none`: Use raw values
+     * @defaultValue "logarithmic"
+     */
+    normalization?: "logarithmic" | "linear" | "none";
+    /**
+     * Minimum value for links to ensure visibility.
+     * @defaultValue 0.1
+     */
+    minLinkValue?: number;
+}
+/**
+ * Generates Sankey diagram data from a parsed Cooklang recipe.
+ *
+ * @remarks
+ * This is the main entry point for the library. It transforms a parsed
+ * Cooklang recipe into a Sankey diagram data structure by:
+ * 1. Creating nodes for ingredients, steps, and the final dish
+ * 2. Building edges representing ingredient flow
+ * 3. Performing topological sort for correct value propagation
+ * 4. Normalizing values for balanced visualization
+ *
+ * @param recipe - A parsed CooklangRecipe object
+ * @param options - Optional configuration for generation
+ * @returns SankeyData structure, or null if generation fails
+ *
+ * @example
+ * ```ts
+ * import { CooklangParser, generateSankeyData } from 'cooklang-sankey';
+ *
+ * const parser = new CooklangParser();
+ * const [recipe] = parser.parse(`
+ *   @pasta{400g} を茹でる。
+ *   @卵{3個}と@チーズ{100g}を混ぜる。
+ * `);
+ *
+ * const data = generateSankeyData(recipe, {
+ *   finalNodeName: "Carbonara",
+ *   normalization: "logarithmic"
+ * });
+ * ```
+ */
+declare const generateSankeyData: (recipe: CooklangRecipe, options?: SankeyGeneratorOptions) => SankeyData | null;
+/**
+ * Validates and optimizes Sankey data for visualization.
+ *
+ * @remarks
+ * Performs three optimization steps:
+ * 1. **Remove invalid links**: Filters out links referencing non-existent nodes
+ * 2. **Remove orphaned nodes**: Keeps only nodes connected to valid links
+ *    (final nodes are always preserved)
+ * 3. **Normalize link values**: Scales values relative to minimum for
+ *    stable visualization (ensures all values >= 1)
+ *
+ * @param data - The SankeyData to optimize
+ * @returns A new SankeyData with optimizations applied
+ *
+ * @example
+ * ```ts
+ * const rawData = generateSankeyData(recipe);
+ * if (rawData) {
+ *   const optimized = optimizeSankeyData(rawData);
+ *   // Use optimized data for visualization
+ * }
+ * ```
+ */
+declare const optimizeSankeyData: (data: SankeyData) => SankeyData;
+
+/**
+ * Value formatting utilities using official @cooklang/cooklang package.
+ *
+ * @remarks
+ * Provides utilities for converting Cooklang quantity and value types
+ * into human-readable string representations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Formats a Cooklang Value to a string representation.
+ *
+ * @param value - The Value object to format (number, range, or text)
+ * @returns A string representation of the value, or empty string if null/undefined
+ *
+ * @example
+ * ```ts
+ * formatValue({ type: "number", value: 200 }); // "200"
+ * formatValue({ type: "range", value: { start: 2, end: 3 } }); // "2-3"
+ * formatValue({ type: "text", value: "some" }); // "some"
+ * formatValue(null); // ""
+ * ```
+ */
+declare const formatValue: (value: Value | null | undefined) => string;
+/**
+ * Formats a Cooklang Quantity into separate value and unit strings.
+ *
+ * @param quantity - The Quantity object to format
+ * @returns An object with `quantity` (numeric string) and `unit` (unit string)
+ *
+ * @example
+ * ```ts
+ * formatQuantityAmount({ value: { type: "number", value: 200 }, unit: "g" });
+ * // { quantity: "200", unit: "g" }
+ *
+ * formatQuantityAmount(null);
+ * // { quantity: "", unit: "" }
+ * ```
+ */
+declare const formatQuantityAmount: (quantity: Quantity | null | undefined) => {
+    quantity: string;
+    unit: string;
+};
+/**
+ * Generates complete text from step items by resolving references.
+ *
+ * @remarks
+ * Converts a Step's items array into a readable string by:
+ * - Keeping text items as-is
+ * - Resolving ingredient references to "name(quantity)" format
+ * - Resolving cookware references to their names
+ * - Resolving timer references to their display values
+ *
+ * @param step - The Step object containing items to format
+ * @param recipe - The parent CooklangRecipe for resolving references
+ * @returns A concatenated string of all step items
+ *
+ * @example
+ * ```ts
+ * // For a step with text "Cook " + ingredient(pasta, 400g) + " until done"
+ * generateStepText(step, recipe);
+ * // "Cook pasta(400g) until done"
+ * ```
+ */
+declare const generateStepText: (step: Step, recipe: CooklangRecipe) => string;
+
+export { type BaseLinkMetadata, type BaseNodeMetadata, type BaseSankeyLink, type BaseSankeyNode, type DAGEdge, type DAGNode, type ExtractedValue, type NodeCategory, type RecipeMetadata, type SankeyData, type SankeyGeneratorOptions, type SankeyLink, type SankeyNode, type TransformationType, extractMetadata, formatQuantityAmount, formatValue, generateSankeyData, generateStepText, optimizeSankeyData };