squarified 0.5.0 → 0.6.0

package/README.md

@@ -1,25 +1,250 @@
 # Squarified
 
-`squarified` is a minimal and powerful treemap component.
+A minimal and powerful treemap visualization library for creating interactive hierarchical data visualizations.
 
-## Install
+## Features
+
+- 🚀 **Lightweight**: Minimal bundle size with maximum performance
+- 🎨 **Customizable**: Rich theming and styling options
+- 🔌 **Plugin System**: Extensible architecture with built-in plugins
+- 📱 **Responsive**: Automatic resizing
+- ⚡ **Interactive**: Built-in zoom, drag, highlight, and menu interactions
+- 🎯 **TypeScript**: Full type safety and excellent DX
+
+## Installation
 
 ```shell
-$ yarn add squarified
+npm install squarified
+# or
+yarn add squarified
+# or
+pnpm add squarified
 ```
 
-### Document
+## Quick Start
 
-nonzzz.github.io/squarified/
+```typescript
+import { c2m, createTreemap, sortChildrenByKey } from 'squarified'
 
-### Auth
+// Create a treemap instance
+const treemap = createTreemap({
+  plugins: [
+    // Add built-in plugins for interactions
+  ]
+})
 
-Kanno
+// Initialize with a DOM element
+const container = document.querySelector('#treemap-container')
+treemap.init(container)
+
+// Set your data
+treemap.setOptions({
+  data: [
+    {
+      id: 'root',
+      label: 'Root',
+      weight: 100,
+      groups: [
+        { id: 'child1', label: 'Child 1', weight: 60 },
+        { id: 'child2', label: 'Child 2', weight: 40 }
+      ]
+    }
+  ]
+})
+```
+
+## Complete Example
+
+```typescript
+import {
+  c2m,
+  createTreemap,
+  presetColorPlugin,
+  presetDragElementPlugin,
+  presetHighlightPlugin,
+  presetMenuPlugin,
+  presetScalePlugin,
+  presetZoomablePlugin,
+  sortChildrenByKey
+} from 'squarified'
+
+// Create treemap with plugins
+const treemap = createTreemap({
+  plugins: [
+    presetColorPlugin,
+    presetZoomablePlugin,
+    presetHighlightPlugin,
+    presetDragElementPlugin,
+    presetScalePlugin(),
+    presetMenuPlugin({
+      style: {
+        borderRadius: '5px',
+        padding: '6px 12px',
+        backgroundColor: 'rgba(0, 0, 0, 0.8)',
+        color: 'white',
+        cursor: 'pointer',
+        userSelect: 'none'
+      },
+      render: () => [
+        { html: '<span>🔍 Zoom In</span>', action: 'zoom' },
+        { html: '<span>🔄 Reset</span>', action: 'reset' }
+      ],
+      onClick(action, module) {
+        switch (action) {
+          case 'zoom':
+            if (module?.node.id) {
+              treemap.zoom(module.node.id)
+            }
+            break
+          case 'reset':
+            treemap.resize()
+            break
+        }
+      }
+    })
+  ]
+})
+
+// Convert and prepare data
+async function loadData() {
+  const response = await fetch('/api/data')
+  const rawData = await response.json()
+
+  // Transform data structure
+  const convertedData = rawData.map((item) => ({
+    ...item,
+    groups: item.children?.map((child) => convertChildrenToGroups(child))
+  }))
+
+  // Convert to treemap format and sort
+  const treemapData = sortChildrenByKey(
+    convertedData.map((item) =>
+      c2m(item, 'value', (d) => ({
+        ...d,
+        id: d.path,
+        label: d.name
+      }))
+    ),
+    'weight'
+  )
+
+  return treemapData
+}
+
+// Initialize
+const container = document.querySelector('#app')
+treemap.init(container)
+
+// Load and set data
+loadData().then((data) => {
+  treemap.setOptions({ data })
+})
+
+// Handle events
+treemap.on('click', (event, module) => {
+  console.log('Clicked:', module?.node)
+})
+
+// Auto-resize on container changes
+new ResizeObserver(() => {
+  treemap.resize()
+}).observe(container)
+```
+
+## API Reference
+
+### Creating a Treemap
+
+#### `createTreemap(options?)`
+
+Creates a new treemap instance.
+
+```typescript
+interface CreateTreemapOptions {
+  plugins?: Plugin[]
+}
+```
+
+### Instance Methods
+
+#### `init(element: HTMLElement)`
+
+Initialize the treemap with a DOM container.
+
+#### `setOptions(options: TreemapOptions)`
 
-### Credits
+Update treemap configuration and data.
 
-Algorithm is ported from [esbuild Bundle Size Analyzer](https://esbuild.github.io/analyze/) by [Evan Wallace](https://github.com/evanw). Refactor algorithm to adjusted the layout.
+#### `resize()`
 
-### LICENSE
+Manually trigger a resize recalculation.
+
+#### `on(event: string, handler: Function)`
+
+Subscribe to treemap events.
+
+#### `dispose()`
+
+Clean up the treemap instance.
+
+### Data Format
+
+```typescript
+interface TreemapNode {
+  id: string
+  label: string
+  weight: number
+  groups?: TreemapNode[]
+  // Custom properties...
+}
+```
+
+### Utility Functions
+
+#### `c2m(data, weightKey, transform?)`
+
+Convert hierarchical data to treemap format.
+
+#### `sortChildrenByKey(data, key)`
+
+Sort treemap nodes by a specific key.
+
+## Built-in Plugins
+
+- **presetColorPlugin**: Automatic color assignment
+- **presetZoomablePlugin**: Zoom interactions
+- **presetHighlightPlugin**: Hover highlighting
+- **presetDragElementPlugin**: Drag interactions
+- **presetScalePlugin**: Scaling controls
+- **presetMenuPlugin**: Context menus
+
+## Browser Support
+
+- Chrome/Edge 80+
+- Firefox 75+
+- Safari 13+
+
+## Performance
+
+Squarified is optimized for performance with:
+
+- Canvas-based rendering
+- Efficient layout algorithms
+- Smart redraw optimizations
+- Memory-conscious design
+
+## Contributing
+
+Contributions are welcome! Please read our [contributing guide](CONTRIBUTING.md) for details.
+
+## License
 
 [MIT](./LICENSE)
+
+## Auth
+
+Kanno
+
+## Credits
+
+Algorithm ported from [esbuild Bundle Size Analyzer](https://esbuild.github.io/analyze/) by [Evan Wallace](https://github.com/evanw), refactored and optimized for general-purpose treemap visualization.

package/dist/index.d.mts

@@ -1 +1,352 @@
-export { B as BasicTreemapInstance, c as CreateTreemapOptions, D as DOMEventType, a1 as DefaultMap, E as ExposedEventCallback, n as ExposedEventDefinition, o as ExposedEventMethods, x as GraphicConfig, w as GraphicFont, G as GraphicLayout, Q as InheritedCollections, U as InheritedCollectionsWithParamter, L as LayoutModule, M as Module, N as NativeModule, k as Plugin, P as PluginContext, l as PluginHooks, p as PrimitiveEventMetadata, S as Series, e as TreemapInstance, y as TreemapInstanceAPI, T as TreemapOptions, O as applyCanvasTransform, f as c2m, K as createCanvasElement, H as createRoundBlock, I as createTitleText, d as createTreemap, m as definePlugin, g as findRelativeNode, h as findRelativeNodeById, i as flattenModule, j as getNodeDepth, z as hashCode, q as isClickEvent, r as isContextMenuEvent, X as isMacOS, t as isMouseEvent, a0 as isScrollWheelOrRightButtonOnMouseupAndDown, u as isWheelEvent, R as mixin, V as mixinWithParams, F as noop, A as perferNumeric, W as prettyStrJoin, J as raf, $ as smoothFrame, s as sortChildrenByKey, Z as stackMatrixTransform, _ as stackMatrixTransformWithGraphAndLayer, Y as typedForIn, v as visit } from './index-Dskgz6nc.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Any = any
+
+type AnyObject = Record<keyof Any, Any>
+
+
+interface MatrixLoc {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+declare class Matrix2D implements MatrixLoc {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+    constructor(loc?: Partial<MatrixLoc>);
+    create(loc: MatrixLoc): this;
+    transform(x: number, y: number, scaleX: number, scaleY: number, rotation: number, skewX: number, skewY: number): this;
+    translation(x: number, y: number): this;
+    scale(a: number, d: number): this;
+    private skew;
+    private roate;
+}
+
+declare const enum DisplayType {
+    Graph = "Graph",
+    Box = "Box",
+    Text = "Text",
+    RoundRect = "RoundRect",
+    Bitmap = "Bitmap"
+}
+declare abstract class Display {
+    parent: Display | null;
+    id: number;
+    matrix: Matrix2D;
+    abstract get __instanceOf__(): DisplayType;
+    constructor();
+    destory(): void;
+}
+
+declare abstract class C extends Display {
+    elements: Display[];
+    constructor();
+    abstract get __instanceOf__(): DisplayType;
+    add(...elements: Display[]): void;
+    remove(...elements: Display[]): void;
+    destory(): void;
+}
+declare class Box extends C {
+    elements: Display[];
+    constructor();
+    add(...elements: Display[]): void;
+    remove(...elements: Display[]): void;
+    destory(): void;
+    get __instanceOf__(): DisplayType.Box;
+    clone(): Box;
+}
+
+interface RGBColor {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+interface HLSColor {
+    h: number;
+    l: number;
+    s: number;
+    a?: number;
+}
+interface ColorDecoratorResultHLS {
+    mode?: 'hsl';
+    desc: HLSColor;
+}
+interface ColorDecoratorResultRGB {
+    mode: 'rgb';
+    desc: RGBColor;
+}
+type ColorDecoratorResult = ColorDecoratorResultHLS | ColorDecoratorResultRGB;
+
+type EventCallback<P = Any[]> = P extends Any[] ? (...args: P) => Any : never;
+type DefaultEventDefinition = Record<string, EventCallback>;
+type BindThisParameter<T, C = unknown> = T extends (...args: infer P) => infer R ? (this: C, ...args: P) => R : never;
+interface EventCollectionData<EvtDefinition extends DefaultEventDefinition, C = unknown> {
+    name: string;
+    handler: BindThisParameter<EvtDefinition[keyof EvtDefinition], C>;
+    ctx: C;
+    silent: boolean;
+}
+type EventCollections<EvtDefinition extends DefaultEventDefinition> = Record<keyof EvtDefinition, EventCollectionData<EvtDefinition>[]>;
+declare class Event<EvtDefinition extends DefaultEventDefinition = DefaultEventDefinition> {
+    eventCollections: EventCollections<EvtDefinition>;
+    constructor();
+    on<C, Evt extends keyof EvtDefinition>(evt: Evt, handler: BindThisParameter<EvtDefinition[Evt], unknown extends C ? this : C>, c?: C): void;
+    off(evt: keyof EvtDefinition, handler?: BindThisParameter<EvtDefinition[keyof EvtDefinition], unknown>): void;
+    silent(evt: keyof EvtDefinition, handler?: BindThisParameter<EvtDefinition[keyof EvtDefinition], unknown>): void;
+    active(evt: keyof EvtDefinition, handler?: BindThisParameter<EvtDefinition[keyof EvtDefinition], unknown>): void;
+    emit(evt: keyof EvtDefinition, ...args: Parameters<EvtDefinition[keyof EvtDefinition]>): void;
+    bindWithContext<C>(c: C): (evt: keyof EvtDefinition, handler: BindThisParameter<EvtDefinition[keyof EvtDefinition], unknown extends C ? this : C>) => void;
+}
+
+interface RenderViewportOptions {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+    shaow?: boolean;
+}
+declare class Canvas {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    constructor(options: RenderViewportOptions);
+    setOptions(options: RenderViewportOptions): void;
+}
+declare class Render {
+    options: RenderViewportOptions;
+    private container;
+    constructor(to: HTMLElement, options: RenderViewportOptions);
+    clear(width: number, height: number): void;
+    get canvas(): HTMLCanvasElement;
+    get ctx(): CanvasRenderingContext2D;
+    initOptions(userOptions?: Partial<RenderViewportOptions>): void;
+    destory(): void;
+}
+
+type ApplyTo = string | HTMLElement;
+declare class Schedule<D extends DefaultEventDefinition = DefaultEventDefinition> extends Box {
+    render: Render;
+    to: HTMLElement;
+    event: Event<D>;
+    constructor(to: ApplyTo, renderOptions?: Partial<RenderViewportOptions>);
+    update(): void;
+    execute(render: Render, graph?: Display): void;
+}
+
+declare const DOM_EVENTS: readonly ["click", "mousedown", "mousemove", "mouseup", "mouseover", "mouseout", "wheel"];
+type DOMEventType = typeof DOM_EVENTS[number];
+interface DOMLoc {
+    x: number;
+    y: number;
+}
+interface DOMEventMetadata<T extends keyof HTMLElementEventMap = Any> {
+    native: HTMLElementEventMap[T];
+    loc: DOMLoc;
+}
+type DOMEventCallback<T extends DOMEventType> = (metadata: DOMEventMetadata<T>) => void;
+type DOMEventDefinition<API = unknown> = {
+    [K in DOMEventType]: BindThisParameter<DOMEventCallback<K>, API>;
+};
+
+declare abstract class Cache {
+    abstract key: string;
+    abstract get state(): boolean;
+    abstract flush(...args: never): void;
+    abstract destroy(): void;
+}
+declare class RenderCache extends Canvas implements Cache {
+    key: string;
+    private $memory;
+    constructor(opts: RenderViewportOptions);
+    get state(): boolean;
+    flush(treemap: TreemapLayout, matrix?: Matrix2D): void;
+    destroy(): void;
+}
+declare class FontCache implements Cache {
+    key: string;
+    private fonts;
+    ellispsis: Record<string, number>;
+    constructor();
+    get state(): boolean;
+    flush(treemap: TreemapLayout, matrix?: Matrix2D): void;
+    destroy(): void;
+    queryFontById(id: string, byDefault: () => number): number;
+}
+
+type ColorMappings = Record<string, ColorDecoratorResult>;
+type Rect = {
+    w: number;
+    h: number;
+};
+type Series<T> = {
+    max: T;
+    min: T;
+};
+interface RenderColor {
+    mappings: ColorMappings;
+}
+interface RenderLayout {
+    titleAreaHeight: Series<number>;
+    rectBorderRadius: number;
+    rectBorderWidth: number;
+    rectGap: number;
+}
+interface RenderFont {
+    color: string;
+    fontSize: Series<number>;
+    fontFamily: string;
+}
+interface RenderDecorator {
+    color: RenderColor;
+    layout: RenderLayout;
+    font: RenderFont;
+}
+declare const defaultLayoutOptions: {
+    titleAreaHeight: {
+        max: number;
+        min: number;
+    };
+    rectGap: number;
+    rectBorderRadius: number;
+    rectBorderWidth: number;
+};
+declare const defaultFontOptions: {
+    color: string;
+    fontSize: {
+        max: number;
+        min: number;
+    };
+    fontFamily: string;
+};
+declare function presetDecorator(app: TreemapLayout): void;
+
+declare function sortChildrenByKey<T extends AnyObject, K extends keyof T = 'weight'>(data: T[], ...keys: K[]): T[];
+declare function c2m<T extends AnyObject & {
+    groups: Any[];
+}, K extends keyof T>(data: T, key: K, modifier?: (data: T) => T): T & {
+    weight: number;
+};
+declare function flatten<T extends AnyObject & {
+    groups: T[];
+}>(data: T[]): Omit<T, "groups">[];
+type Module = ReturnType<typeof c2m>;
+declare function bindParentForModule<T extends Module & {
+    parent: Module;
+}>(modules: Module[], parent?: Module): T[];
+type NativeModule = ReturnType<typeof bindParentForModule>[number] & {
+    id: string;
+    parent: NativeModule;
+    groups: NativeModule[];
+};
+declare function getNodeDepth(node: NativeModule): number;
+declare function visit<T extends AnyObject>(data: T[], fn: (data: T) => boolean | void): T | null;
+declare function findRelativeNode(p: {
+    x: number;
+    y: number;
+}, layoutNodes: LayoutModule[]): LayoutModule | null;
+declare function findRelativeNodeById(id: string, layoutNodes: LayoutModule[]): LayoutModule | null;
+
+type LayoutModule = {
+    node: NativeModule;
+    layout: [number, number, number, number];
+    children: LayoutModule[];
+    decorator: {
+        titleHeight: number;
+        rectBorderRadius: number;
+        rectGap: number;
+        rectBorderWidth: number;
+    };
+};
+
+interface PrimitiveEventMetadata<T extends keyof HTMLElementEventMap> {
+    native: HTMLElementEventMap[T];
+    module: LayoutModule | null;
+}
+type ExposedEventCallback<T extends DOMEventType> = (metadata: PrimitiveEventMetadata<T>) => void;
+type ExposedEventDefinition = {
+    [K in DOMEventType]: BindThisParameter<ExposedEventCallback<K>, TreemapInstanceAPI>;
+};
+interface ExposedEventMethods<C = TreemapInstanceAPI, D = ExposedEventDefinition> {
+    on<Evt extends keyof D>(evt: Evt, handler: BindThisParameter<D[Evt], unknown extends C ? this : C>): void;
+    off<Evt extends keyof D>(evt: keyof D, handler?: BindThisParameter<D[Evt], unknown extends C ? this : C>): void;
+}
+declare const INTERNAL_EVENT_MAPPINGS: {
+    readonly ON_ZOOM: 1;
+    readonly ON_CLEANUP: 3;
+};
+type InternalEventType = typeof INTERNAL_EVENT_MAPPINGS[keyof typeof INTERNAL_EVENT_MAPPINGS];
+interface InternalEventMappings {
+    [INTERNAL_EVENT_MAPPINGS.ON_ZOOM]: (node: LayoutModule) => void;
+    [INTERNAL_EVENT_MAPPINGS.ON_CLEANUP]: () => void;
+}
+type InternalEventDefinition = {
+    [key in InternalEventType]: InternalEventMappings[key];
+};
+
+interface TreemapOptions {
+    data: Module[];
+}
+type UseKind = 'decorator';
+interface App {
+    init: (el: HTMLElement) => void;
+    dispose: () => void;
+    setOptions: (options: TreemapOptions) => void;
+    resize: () => void;
+    use: (using: UseKind, register: (app: TreemapLayout) => void) => void;
+    zoom: (id: string) => void;
+}
+/**
+ * This interface isn't stable it might be remove at next few versions.
+ * If you want set custom decorator pls see 'presetDecorator' for details.
+ */
+type unstable_use = (app: TreemapLayout) => void;
+declare class Highlight extends Schedule<DOMEventDefinition> {
+    reset(): void;
+    get canvas(): HTMLCanvasElement;
+    setZIndexForHighlight(zIndex?: string): void;
+    init(): void;
+}
+declare class TreemapLayout extends Schedule<InternalEventDefinition> {
+    data: NativeModule[];
+    layoutNodes: LayoutModule[];
+    decorator: RenderDecorator;
+    bgBox: Box;
+    fgBox: Box;
+    highlight: Highlight;
+    renderCache: RenderCache;
+    fontCache: FontCache;
+    constructor(...args: ConstructorParameters<typeof Schedule>);
+    drawBackgroundNode(node: LayoutModule): void;
+    drawForegroundNode(node: LayoutModule): void;
+    reset(refresh?: boolean): void;
+    get api(): {
+        zoom: (node: LayoutModule | null) => void;
+    };
+}
+declare function createTreemap(): App & ExposedEventMethods;
+type TreemapInstanceAPI = TreemapLayout['api'];
+
+/**
+ * @deprecated compat `PrimitiveEvent` using `DOMEventType` replace it. (will be removed in the next three versions.)
+ */
+type PrimitiveEvent = DOMEventType;
+/**
+ * @deprecated compat `EventMethods` using `ExposedEventMethods` replace it. (will be removed in the next three versions.)
+ */
+type EventMethods = ExposedEventMethods;
+/**
+ * @deprecated compat `PrimitiveEventCallback` using `ExposedEventCallback` replace it. (will be removed in the next three versions.)
+ */
+type PrimitiveEventCallback<T extends PrimitiveEvent> = ExposedEventCallback<T>;
+/**
+ * @deprecated compat `PrimitiveEventDefinition` using `ExposedEventDefinition` replace it. (will be removed in the next three versions.)
+ */
+type PrimitiveEventDefinition = ExposedEventDefinition;
+
+export { TreemapLayout, c2m, createTreemap, defaultFontOptions, defaultLayoutOptions, findRelativeNode, findRelativeNodeById, flatten as flattenModule, getNodeDepth, presetDecorator, sortChildrenByKey, visit };
+export type { App, ColorMappings, DOMEventType, EventMethods, ExposedEventCallback, ExposedEventDefinition, ExposedEventMethods, LayoutModule, Module, NativeModule, PrimitiveEvent, PrimitiveEventCallback, PrimitiveEventDefinition, PrimitiveEventMetadata, Rect, RenderColor, RenderDecorator, RenderFont, RenderLayout, Series, TreemapInstanceAPI, TreemapOptions, unstable_use };