@giddaa-housing/ui 0.1.0

package/dist/tree-map.d.ts

@@ -0,0 +1,127 @@
+import * as React from 'react';
+import { ChartCard, ChartValueType } from './chart.js';
+import { ComponentSize } from './size-context.js';
+import 'class-variance-authority/types';
+import 'class-variance-authority';
+import 'recharts';
+
+/**
+ * A treemap — part-to-whole composition drawn as proportionally sized, nested
+ * rectangles. Reach for one to compare category shares at a glance (portfolio
+ * mix, holdings by type, regional distribution).
+ *
+ * Two shapes share one component: `flat` lays out a single level of categories;
+ * `nested` groups subcategories beneath a shared group colour (each leaf inherits
+ * its group's colour unless it sets its own `fill`). Both reuse the same palette,
+ * in-tile labels, legend, frame, and tooltip — only the data depth differs.
+ *
+ * Per the chart architecture the recharts `Treemap` primitive is rendered
+ * directly here; only the giddaa frame, palette, tile content, and legend are
+ * supplied around it. Tiles are sized by `value`; the in-tile label (name + share
+ * of the whole) is hidden on tiles too small to fit it.
+ *
+ * @example
+ * <TreeMap
+ *   data={[
+ *     { label: "Lekki", value: 40 },
+ *     { label: "Ikoyi", value: 30 },
+ *     { label: "V.I.", value: 18 },
+ *     { label: "Yaba", value: 12 },
+ *   ]}
+ *   title="Portfolio mix"
+ *   description="Share of holdings by location"
+ *   tooltip
+ * />
+ *
+ * @example
+ * // Nested — subcategories grouped under a shared group colour
+ * <TreeMap
+ *   data={[
+ *     { label: "Residential", children: [
+ *       { label: "Apartments", value: 27 },
+ *       { label: "Duplexes", value: 21 },
+ *     ] },
+ *     { label: "Commercial", children: [
+ *       { label: "Offices", value: 17 },
+ *       { label: "Retail", value: 13 },
+ *     ] },
+ *     { label: "Land", children: [{ label: "Plots", value: 14 }] },
+ *   ]}
+ *   title="Portfolio mix"
+ *   description="Holdings by category & type"
+ * />
+ */
+/** Treemap sizes line up with the three shared `ComponentSize` values. */
+type TreeMapSize = ComponentSize;
+/** Where the colour-key legend sits relative to the plot. */
+type TreeMapLegendPlacement = "right" | "bottom";
+type TreeMapDatum = {
+    /** Category name, shown in the tile label, legend, and tooltip. */
+    label: string;
+    /** Tile value — drives the tile's area. Omit on a group with `children`. */
+    value?: number;
+    /** Tile/group colour; defaults to the palette in order. Leaves inherit it. */
+    fill?: string;
+    /** Subcategories for a `nested` treemap. */
+    children?: TreeMapDatum[];
+};
+/**
+ * Tile palette, ordered by share: forest → brass → moss → clay → stone. Each
+ * entry pairs a tile `fill` with the `text` colour that reads on it (a tonal
+ * tint of the same scale). Giddaa has no `chart-1`…`chart-N` tokens yet, so these
+ * map to the brand scales; assign by order, or override per datum with `fill`.
+ */
+declare const TREE_MAP_PALETTE: readonly [{
+    readonly fill: "var(--color-forest-700)";
+    readonly text: "var(--color-forest-100)";
+}, {
+    readonly fill: "var(--color-brass-500)";
+    readonly text: "var(--color-brass-900)";
+}, {
+    readonly fill: "var(--color-moss-600)";
+    readonly text: "var(--color-moss-100)";
+}, {
+    readonly fill: "var(--color-clay-500)";
+    readonly text: "var(--color-clay-50)";
+}, {
+    readonly fill: "var(--color-stone-500)";
+    readonly text: "var(--color-stone-50)";
+}];
+type TreeMapLayout = {
+    /** Plot box height in px. Width stays fluid via the ResponsiveContainer. */
+    height: number;
+    /** Inset around every tile in px — straddles edges to read as a gap. */
+    gap: number;
+    /** Tile corner radius in px. */
+    radius: number;
+    /** Tile label padding from the top-left corner in px. */
+    labelPadding: number;
+    /** Tile label (name) font size in px. */
+    nameFontSize: number;
+    /** Tile label (share) font size in px. */
+    shareFontSize: number;
+    /** Smallest tile width/height in px that still shows its label. */
+    labelMinSide: number;
+};
+declare const TREE_MAP_LAYOUT: Record<TreeMapSize, TreeMapLayout>;
+type TreeMapProps = Omit<React.ComponentProps<typeof ChartCard>, "size" | "children"> & {
+    /** Categories — flat leaves, or groups carrying `children` (nested). */
+    data: TreeMapDatum[];
+    /** Explicit size; otherwise inherited from the nearest `SizeProvider`. */
+    size?: TreeMapSize;
+    /** Chart heading. Omit to hide the title. */
+    title?: React.ReactNode;
+    /** Supporting metadata (period, source). Omit to hide the description. */
+    description?: React.ReactNode;
+    /** Enable the hover value tooltip. Default false. */
+    tooltip?: boolean;
+    /** Legend placement — a right column or a wrapped bottom row. Default right. */
+    legend?: TreeMapLegendPlacement;
+    /** Format the tile value in the tooltip. Defaults to a localised number. */
+    valueFormatter?: (value: number) => string;
+    /** Value formatting for the tooltip. Defaults to `number`. */
+    valueType?: ChartValueType;
+};
+declare function TreeMap({ data, size, title, description, tooltip, legend, valueFormatter, valueType, className, ...props }: TreeMapProps): React.JSX.Element;
+
+export { TREE_MAP_LAYOUT, TREE_MAP_PALETTE, TreeMap, type TreeMapDatum, type TreeMapLayout, type TreeMapLegendPlacement, type TreeMapProps, type TreeMapSize };