@communitiesuk/svelte-component-library 0.1.19-beta.2 → 0.1.19-beta.21

package/README.md

@@ -103,6 +103,13 @@ Make sure you are on your main development branch you want to release (e.g., `ma
 
 Use the `npm version` command to update `package.json` and `package-lock.json`, create a commit, and create an annotated Git tag. Choose **one** of the following based on [Semantic Versioning (SemVer)](https://semver.org/):
 
+
+- **Pre-Release:**
+
+  ```bash
+  npm version prerelease --preid=alpha
+  ```
+
 - **Patch Release (Bug fixes, tiny changes - e.g., 1.0.0 → 1.0.1):**
 
   ```bash

package/dist/components/data-vis/Histogram.svelte

@@ -0,0 +1,282 @@
+<script>
+  import { scaleLinear } from "d3-scale";
+  import { bin, range as d3range } from "d3-array";
+  import Axis from "./axis/Axis.svelte";
+  import chroma from "chroma-js";
+
+  let {
+    averageValue = undefined,
+    distribution = [],
+    minX = 0,
+    maxX = 1,
+    minY = 0,
+    maxY = 100,
+    showXAxis = true,
+    showYAxis = true,
+    showArrows = true,
+    midColor = "#DDDDDD",
+    startColor = "#B70000",
+    endColor = "#2D6644",
+    floor = undefined,
+    ceiling = undefined,
+    fill = "grey",
+    nBins = 10,
+    padding = 0,
+    height = 50,
+    polarity = "standard",
+    annotationValue = 0,
+    annotationText = "",
+    labelFormatter = (tick, index, numberOfTicks, values) => {
+      return tick;
+    },
+    containerWidth = $bindable(100),
+    numberOfTicks,
+    customColorScale = undefined,
+    skew = true,
+    showGridlines = true,
+    showTickMarks = false,
+    tickStrokeWidth = 0.25,
+    barStrokeWidth = 0,
+    barStrokeColor = "white",
+    topLabel = true,
+    includeOutliers = true,
+  } = $props();
+
+  let xTicks = $state([]);
+  let yTicks = $state([]);
+
+  let xTickFirst = $derived(xTicks.length ? xTicks[0] : 0);
+  let xTickLast = $derived(xTicks.length ? xTicks.at(-1) : 1);
+
+  let domainXMin = $derived(Math.min(xTickFirst, xTickLast));
+  let domainXMax = $derived(Math.max(xTickFirst, xTickLast));
+
+  let yTickFirst = $derived(yTicks.length ? yTicks[0] : 0);
+  let yTickLast = $derived(yTicks.length ? yTicks.at(-1) : 1);
+
+  let domainYMin = $derived(Math.min(yTickFirst, yTickLast));
+  let domainYMax = $derived(Math.max(yTickFirst, yTickLast));
+
+  let useRange = $derived(
+    polarity === "standard"
+      ? [0, containerWidth - padding]
+      : [containerWidth - padding, 0],
+  );
+
+  let xScale = $derived(
+    scaleLinear().domain([domainXMin, domainXMax]).range(useRange),
+  );
+
+  const segmentScale = $derived(
+    scaleLinear().domain([0, nBins]).range([domainXMin, domainXMax]),
+  );
+
+  const binThresholds = $derived(d3range(1, nBins).map(segmentScale));
+
+  const binner = $derived(
+    bin().domain([domainXMin, domainXMax]).thresholds(binThresholds),
+  );
+  const clampedDistribution = $derived(
+    distribution.map((d) => Math.min(Math.max(d, domainXMin), domainXMax)),
+  );
+
+  const binnedDistribution = $derived(
+    binner(includeOutliers ? clampedDistribution : distribution),
+  );
+
+  const bins = $derived(
+    polarity === "reverse"
+      ? binnedDistribution.toReversed()
+      : binnedDistribution,
+  );
+
+  const proportionsInBins = $derived(
+    bins.map((b) => b.length / distribution.length),
+  );
+
+  let proportionInExtremeBins = $derived([
+    proportionsInBins[0],
+    proportionsInBins.at(-1),
+  ]);
+
+  let yScale = $derived(
+    scaleLinear()
+      .domain([0, Math.max(...bins.map((b) => b.length))])
+      .range([0, height]),
+  );
+
+  function interpolateColors(
+    startColor,
+    endColor,
+    nSegments,
+    midColor = null,
+    skew,
+  ) {
+    const colorArray = [startColor, midColor, endColor].filter(Boolean);
+
+    if (!skew) {
+      return chroma.scale(colorArray).colors(nSegments);
+    } else {
+      const extremeColors = chroma
+        .scale([startColor, midColor, endColor])
+        .padding([
+          proportionInExtremeBins[0] / 2,
+          proportionInExtremeBins[1] / 2,
+        ])
+        .colors(2);
+
+      const averageNormalised =
+        (averageValue - xTickFirst) / (xTickLast - xTickFirst);
+
+      const binColors = chroma
+        .scale([extremeColors[0], midColor, extremeColors[1]])
+        .domain([
+          0,
+          polarity === "reverse" ? 1 - averageNormalised : averageNormalised,
+          1,
+        ])
+        .colors(10);
+
+      return binColors;
+    }
+  }
+
+  let colorScale = $derived(
+    customColorScale ??
+      interpolateColors(startColor, endColor, nBins, midColor, skew),
+  );
+
+  $inspect({ colorScale });
+
+  const layout = $derived.by(() => {
+    let y = 0;
+
+    const topLabelY = topLabel ? y : null;
+    if (topLabel) y += 20;
+
+    const annotationY = annotationText ? y : null;
+    if (annotationText) y += 25;
+
+    const chartY = y;
+    y += height;
+
+    const xAxisY = showXAxis ? y : null;
+    if (showXAxis) y += 25;
+
+    return {
+      topLabelY,
+      annotationY,
+      chartY,
+      xAxisY,
+      totalHeight: y,
+    };
+  });
+</script>
+
+{#key containerWidth}
+  <div class="scale-container" bind:clientWidth={containerWidth}>
+    <svg width={containerWidth} height={layout.totalHeight}>
+      <g transform="translate({padding / 2}, 0)">
+        {#if topLabel && layout.topLabelY !== null}
+          <text x={0} y={layout.topLabelY + 14} fill="#666" font-size="0.75em">
+            Number of areas
+          </text>
+        {/if}
+
+        {#if annotationText && layout.annotationY !== null}
+          <g
+            transform="translate({xScale(
+              annotationValue,
+            )}, {layout.annotationY})"
+          >
+            <text
+              fill="#555555"
+              font-size="0.8em"
+              text-anchor="middle"
+              dominant-baseline="hanging"
+            >
+              <tspan x="0" dy="0">{annotationText}</tspan>
+              <tspan x="0" dy="12">▼</tspan>
+            </text>
+          </g>
+        {/if}
+
+        <g transform="translate(0, {layout.chartY})">
+          {#if showYAxis}
+            <Axis
+              bind:ticksArray={yTicks}
+              chartHeight={height}
+              chartWidth={containerWidth - padding}
+              orientation={{ axis: "y", position: "left" }}
+              min={minY}
+              max={maxY}
+              domain={[yTickLast, 0]}
+              range={[0, height]}
+              fontSize={0}
+              numberOfTicks={3}
+              {showGridlines}
+              {showTickMarks}
+              strokeWidth={tickStrokeWidth}
+            />
+          {/if}
+
+          {#each bins as bin, i}
+            {#key bin.x0}
+              {@const fullWidth = Math.abs(xScale(bin.x1) - xScale(bin.x0))}
+              {@const barWidth = fullWidth * 0.97}
+              {@const offset = (fullWidth - barWidth) / 2}
+              <rect
+                x={(polarity === "reverse" ? xScale(bin.x1) : xScale(bin.x0)) +
+                  offset}
+                y={height - yScale(bin.length)}
+                width={barWidth}
+                height={yScale(bin.length)}
+                fill={fill ?? colorScale[i]}
+              ></rect>
+            {/key}
+          {/each}
+        </g>
+
+        {#if showXAxis && layout.xAxisY !== null}
+          <g transform="translate(0, {layout.xAxisY})">
+            <Axis
+              bind:ticksArray={xTicks}
+              chartHeight={height}
+              chartWidth={containerWidth - padding}
+              orientation={{ axis: "x", position: "bottom" }}
+              domain={[xTickFirst, xTickLast]}
+              min={minX}
+              max={maxX}
+              range={useRange}
+              fontSize={13}
+              {floor}
+              {ceiling}
+              {labelFormatter}
+              {numberOfTicks}
+            />
+          </g>
+        {/if}
+      </g>
+    </svg>
+  </div>
+{/key}
+
+<div style="content-visibility: hidden;">
+  {#if !showXAxis}
+    <Axis
+      bind:ticksArray={xTicks}
+      chartHeight={height}
+      chartWidth={containerWidth - padding}
+      orientation={{ axis: "x", position: "bottom" }}
+      domain={[xTickFirst, xTickLast]}
+      min={minX}
+      max={maxX}
+      range={useRange}
+      fontSize={13}
+      {floor}
+      {ceiling}
+      {labelFormatter}
+      {numberOfTicks}
+    ></Axis>
+  {/if}
+</div>

package/dist/components/data-vis/Histogram.svelte.d.ts

@@ -0,0 +1,75 @@
+export default Histogram;
+type Histogram = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const Histogram: import("svelte").Component<{
+    averageValue?: any;
+    distribution?: any[];
+    minX?: number;
+    maxX?: number;
+    minY?: number;
+    maxY?: number;
+    showXAxis?: boolean;
+    showYAxis?: boolean;
+    showArrows?: boolean;
+    midColor?: string;
+    startColor?: string;
+    endColor?: string;
+    floor?: any;
+    ceiling?: any;
+    fill?: string;
+    nBins?: number;
+    padding?: number;
+    height?: number;
+    polarity?: string;
+    annotationValue?: number;
+    annotationText?: string;
+    labelFormatter?: Function;
+    containerWidth?: number;
+    numberOfTicks: any;
+    customColorScale?: any;
+    skew?: boolean;
+    showGridlines?: boolean;
+    showTickMarks?: boolean;
+    tickStrokeWidth?: number;
+    barStrokeWidth?: number;
+    barStrokeColor?: string;
+    topLabel?: boolean;
+    includeOutliers?: boolean;
+}, {}, "containerWidth">;
+type $$ComponentProps = {
+    averageValue?: any;
+    distribution?: any[];
+    minX?: number;
+    maxX?: number;
+    minY?: number;
+    maxY?: number;
+    showXAxis?: boolean;
+    showYAxis?: boolean;
+    showArrows?: boolean;
+    midColor?: string;
+    startColor?: string;
+    endColor?: string;
+    floor?: any;
+    ceiling?: any;
+    fill?: string;
+    nBins?: number;
+    padding?: number;
+    height?: number;
+    polarity?: string;
+    annotationValue?: number;
+    annotationText?: string;
+    labelFormatter?: Function;
+    containerWidth?: number;
+    numberOfTicks: any;
+    customColorScale?: any;
+    skew?: boolean;
+    showGridlines?: boolean;
+    showTickMarks?: boolean;
+    tickStrokeWidth?: number;
+    barStrokeWidth?: number;
+    barStrokeColor?: string;
+    topLabel?: boolean;
+    includeOutliers?: boolean;
+};

package/dist/components/data-vis/axis/Axis.svelte

@@ -1,51 +1,162 @@
-<script>
-  import { FolderArrowRightSolid } from "flowbite-svelte-icons";
+<script lang="ts">
+  import {
+    scaleLinear,
+    type ScaleContinuousNumeric,
+    type ScaleLinear,
+  } from "d3-scale";
   import Ticks from "./Ticks.svelte";
 
+  type AxisName = "x" | "y";
+  type AxisPosition = "bottom" | "top" | "left" | "right";
+  type Orientation = { axis: AxisName; position: AxisPosition };
+  type AxisProjector = (value: number) => number;
+  type LabelFormatter = (
+    tick: number,
+    index: number,
+    ticksArrayLength: number,
+  ) => string | number;
+
+  type Polarity = "standard" | "reverse";
+
   let {
-    chartHeight,
-    chartWidth,
-    numberOfTicks,
-    ticksArray = $bindable(),
-    axisFunction,
-    values,
-    orientation,
-    prefix,
-    suffix,
-    floor,
-    ceiling,
-    yearsInput,
+    chartHeight = 100,
+    chartWidth = $bindable<number>(200),
+
+    numberOfTicks = undefined as number | undefined,
+
+    // Bindable, but avoid binding undefined – initialize as [] for safety
+    ticksArray = $bindable<number[]>([]),
+
+    // Values to derive ticks/domain from if ticksArray not provided
+    min = undefined as number | undefined,
+    max = undefined as number | undefined,
+
+    orientation = { axis: "x", position: "bottom" } as Orientation,
+
+    floor = undefined as number | undefined,
+    ceiling = undefined as number | undefined,
+
+    paddingTop = 100,
+    paddingBottom = 100,
+    paddingLeft = 0,
+    paddingRight = 0,
+
+    labelFormatter = undefined as LabelFormatter | undefined,
+
+    // --- New inputs for D3 scale + optional overrides ---
+    // A ready-made D3 continuous scale (linear/log/time, etc.)
+    // For this component we use numeric-only; time scales also implement numeric mapping.
+    scale = undefined as ScaleContinuousNumeric<number, number> | undefined,
+
+    // Optional overrides for domain/range applied to a COPY of the provided scale
+    domain = undefined as [number, number] | undefined,
+    range = undefined as [number, number] | undefined,
+    fontSize = 19,
+    polarity = "standard",
+    showGridlines = false,
+    showTickMarks = false,
+    strokeWidth = 2,
+  }: {
+    chartHeight?: number;
+    chartWidth?: number;
+    numberOfTicks?: number;
+    ticksArray?: number[];
+    min?: number;
+    max?: number;
+
+    orientation?: Orientation;
+    floor?: number;
+    ceiling?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    labelFormatter?: LabelFormatter;
+
+    // New
+    scale?: ScaleContinuousNumeric<number, number>;
+    domain?: [number, number];
+    range?: [number, number];
+    fontSize?: number;
+    polarity?: Polarity;
+    gridlines?: Boolean;
+    strokeWidth?: Number;
+    showGridlines?: Boolean;
+    showTickMarks?: Boolean;
   } = $props();
+
+  // --- Helpers to compute default domain/range when not supplied ---
+  const innerWidth = $derived(Math.max(0, chartWidth));
+  const innerHeight = $derived(Math.max(0, chartHeight));
+
+  function computeDefaultDomain(): [number, number] {
+    const arr =
+      (ticksArray && ticksArray.length ? ticksArray : [min, max]) ?? [];
+    const dMin =
+      floor ?? (arr.length ? arr.reduce((a, b) => (a < b ? a : b)) : 0);
+    const dMax =
+      ceiling ?? (arr.length ? arr.reduce((a, b) => (a > b ? a : b)) : 1);
+    return [dMin, dMax];
+  }
+
+  function computeDefaultRange(innerWidth, innerHeight): [number, number] {
+    if (orientation.axis === "x") {
+      return [0, innerWidth];
+    } else {
+      return [innerHeight, 0];
+    }
+  }
+  //Returns d3 scale function
+  const resolvedScale = $derived(() => {
+    const base: ScaleContinuousNumeric<number, number> = scale
+      ? scale.copy()
+      : scaleLinear<number, number>();
+
+    const useDomain = domain ?? computeDefaultDomain();
+    base.domain(useDomain);
+
+    const useRange = range ?? computeDefaultRange(innerWidth, innerHeight);
+    base.range(useRange);
+
+    return base;
+  });
+  const axisFunction: AxisProjector = $derived((v: number) => resolvedScale(v));
 </script>
 
 <g
   data-role="{orientation.axis}-axis"
-  transform="translate({orientation.position != 'right'
+  transform="translate({orientation.position !== 'right'
     ? 0
     : chartWidth},{orientation.position === 'bottom' ? chartHeight : 0})"
 >
   <line
-    x1="0"
+    x1={range[0]}
     y1="0"
-    x2={orientation.axis === "x" ? chartWidth : 0}
+    x2={orientation.axis === "x" ? range[1] : 0}
     y2={orientation.axis === "y" ? chartHeight : 0}
-    stroke="black"
+    stroke="grey"
     stroke-width="2px"
   ></line>
-  {#key numberOfTicks}
-    <Ticks
-      bind:ticksArray
-      {chartWidth}
-      {chartHeight}
-      {axisFunction}
-      {values}
-      {numberOfTicks}
-      {orientation}
-      {floor}
-      {ceiling}
-      {yearsInput}
-      {suffix}
-      {prefix}
-    ></Ticks>
-  {/key}
+  {#if ticksArray || (min && max)}
+    {#key numberOfTicks}
+      <Ticks
+        bind:ticksArray
+        {chartWidth}
+        {chartHeight}
+        {axisFunction}
+        {min}
+        {max}
+        {numberOfTicks}
+        {orientation}
+        {floor}
+        {ceiling}
+        {labelFormatter}
+        {fontSize}
+        {polarity}
+        {showGridlines}
+        {showTickMarks}
+        {strokeWidth}
+      />
+    {/key}
+  {/if}
 </g>

package/dist/components/data-vis/axis/Axis.svelte.d.ts

@@ -1,33 +1,37 @@
-export default Axis;
-type Axis = {
-    $on?(type: string, callback: (e: any) => void): () => void;
-    $set?(props: Partial<$$ComponentProps>): void;
+import { type ScaleContinuousNumeric } from "d3-scale";
+type AxisName = "x" | "y";
+type AxisPosition = "bottom" | "top" | "left" | "right";
+type Orientation = {
+    axis: AxisName;
+    position: AxisPosition;
 };
-declare const Axis: import("svelte").Component<{
-    chartHeight: any;
-    chartWidth: any;
-    numberOfTicks: any;
-    ticksArray?: any;
-    axisFunction: any;
-    values: any;
-    orientation: any;
-    prefix: any;
-    suffix: any;
-    floor: any;
-    ceiling: any;
-    yearsInput: any;
-}, {}, "ticksArray">;
+type LabelFormatter = (tick: number, index: number, ticksArrayLength: number) => string | number;
+type Polarity = "standard" | "reverse";
 type $$ComponentProps = {
-    chartHeight: any;
-    chartWidth: any;
-    numberOfTicks: any;
-    ticksArray?: any;
-    axisFunction: any;
-    values: any;
-    orientation: any;
-    prefix: any;
-    suffix: any;
-    floor: any;
-    ceiling: any;
-    yearsInput: any;
+    chartHeight?: number;
+    chartWidth?: number;
+    numberOfTicks?: number;
+    ticksArray?: number[];
+    min?: number;
+    max?: number;
+    orientation?: Orientation;
+    floor?: number;
+    ceiling?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    labelFormatter?: LabelFormatter;
+    scale?: ScaleContinuousNumeric<number, number>;
+    domain?: [number, number];
+    range?: [number, number];
+    fontSize?: number;
+    polarity?: Polarity;
+    gridlines?: Boolean;
+    strokeWidth?: Number;
+    showGridlines?: Boolean;
+    showTickMarks?: Boolean;
 };
+declare const Axis: import("svelte").Component<$$ComponentProps, {}, "ticksArray" | "chartWidth">;
+type Axis = ReturnType<typeof Axis>;
+export default Axis;