From 3c94101b92d143f4714feb805024280476cb8d5b Mon Sep 17 00:00:00 2001
From: Rachel Marconi <dec11rll@gmail.com>
Date: Thu, 8 Aug 2024 17:42:40 -0400
Subject: [PATCH] add layercake components, stories and docs

---
 .storybook/preview.js                  |   1 +
 CHANGELOG.md                           |   1 +
 src/lib/Layercake/AxisX.docs.md        |  13 +++
 src/lib/Layercake/AxisX.stories.svelte |  84 +++++++++++++++++
 src/lib/Layercake/AxisX.svelte         | 120 +++++++++++++++++++++++++
 src/lib/Layercake/AxisY.docs.md        |  13 +++
 src/lib/Layercake/AxisY.stories.svelte |  97 ++++++++++++++++++++
 src/lib/Layercake/AxisY.svelte         | 107 ++++++++++++++++++++++
 src/lib/Layercake/data.json            |   8 ++
 src/lib/index.js                       |   2 +
 10 files changed, 446 insertions(+)
 create mode 100644 src/lib/Layercake/AxisX.docs.md
 create mode 100644 src/lib/Layercake/AxisX.stories.svelte
 create mode 100644 src/lib/Layercake/AxisX.svelte
 create mode 100644 src/lib/Layercake/AxisY.docs.md
 create mode 100644 src/lib/Layercake/AxisY.stories.svelte
 create mode 100644 src/lib/Layercake/AxisY.svelte
 create mode 100644 src/lib/Layercake/data.json

diff --git a/.storybook/preview.js b/.storybook/preview.js
index 0ec5f26..0a749ee 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -23,6 +23,7 @@ const preview = {
           ["Theme", "Fonts"],
           "Examples",
           "Components",
+          "Layercake",
           "Layout",
           "Logos",
           "Maps",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5cf4a34..cfdbf0a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@
 - Patch: Update method of declaring Storybook component descriptions and add import instructions to components
 - Patch: Remove description field from top level `meta` object in component `.stories.svelte` files (do not render)
 - Feature: CLI command to generate new component boilerplate (`npm run create-component`)
+- Feature: Add Layercake AxisX and AxisY components and docs
 
 ## v0.10.2
 
diff --git a/src/lib/Layercake/AxisX.docs.md b/src/lib/Layercake/AxisX.docs.md
new file mode 100644
index 0000000..b9cd5fd
--- /dev/null
+++ b/src/lib/Layercake/AxisX.docs.md
@@ -0,0 +1,13 @@
+Layercake components can be useful for out-of-the-box Svelte charts. Often, however, they are not built according to Urban style. This AxisX component takes those available in Layercake and updates them to use Urban font family, colors, and sizes. 
+
+Furthermore, while Layercake components are often externally updated, this axis here is set in time at a stage where they will not break our builds. Any updates to merge in newer Layercake code will happen not project to project but here, at source, when decided necessary. Therefore, this axis will always work with expected parameters.
+
+
+## Usage
+
+Layercake axes must be built inside a Layercake component and context, and, further, within an Svg component. Both can be imported from the layercake package. The Layercake object must be passed flat array (not object) data and domain before anything can be initialized and rendered, and these are used across all components used to craft a chart.
+
+
+```js
+import { AxisX } from "@urbaninstitute/dataviz-components";
+```
diff --git a/src/lib/Layercake/AxisX.stories.svelte b/src/lib/Layercake/AxisX.stories.svelte
new file mode 100644
index 0000000..d64cfbd
--- /dev/null
+++ b/src/lib/Layercake/AxisX.stories.svelte
@@ -0,0 +1,84 @@
+<script context="module">
+  import AxisX from "./AxisX.svelte";
+  import docs from "./AxisX.docs.md?raw";
+
+  export const meta = {
+    title: "Layercake/AxisX",
+    component: AxisX,
+    tags: ["autodocs"],
+    argTypes: {
+      gridlines: {
+        control: "boolean",
+      },
+      tickMarks: {
+        control: "boolean",
+      },
+      baseline: {
+        control: "boolean",
+      },
+      snapTicks: {
+        control: "boolean"
+      },
+      ticks: {
+        control: {
+          type: "range",
+          min: 1,
+          max: 20,
+        },
+      },
+      xTick: {
+        control: "number"
+      },
+      yTick: {
+        control: "number"
+      },
+      axisLabel: {
+        control: "text"
+      }
+    },
+    parameters: {
+      backgrounds: {
+        default: "light",
+        values: [
+          { name: "light", value: "#ffffff" },
+          { name: "dark", value: "#0A4C6A" }
+        ]
+      },
+      docs: {
+        description: {
+          component: docs
+        }
+      },
+      githubLink: {
+        url: "/Layercake/AxisX.svelte"
+      }
+    }
+  };
+</script>
+
+<script>
+  import { Story, Template } from "@storybook/addon-svelte-csf";
+  import { LayerCake, Svg } from "layercake";
+  import data from "./data.json"
+
+  const xKey = 'value';
+  const yKey = 'year';
+</script>
+
+<Template let:args>
+  <div style="height: 150px;">
+  <LayerCake
+      {data} 
+      xDomain={[0, 20]}
+      yDomain={[0,10]}
+      y={yKey}
+      x={xKey}
+  >
+        <Svg>
+            <AxisX {...args}/>
+        </Svg>
+    </LayerCake>
+  </div>
+</Template>
+
+<Story name="Default" />
diff --git a/src/lib/Layercake/AxisX.svelte b/src/lib/Layercake/AxisX.svelte
new file mode 100644
index 0000000..99932ba
--- /dev/null
+++ b/src/lib/Layercake/AxisX.svelte
@@ -0,0 +1,120 @@
+<!--
+  @component
+  Generates an SVG x-axis. This component is also configured to detect if your x-scale is an ordinal scale. If so, it will place the markers in the middle of the bandwidth.
+ -->
+ <script>
+    import { getContext } from 'svelte';
+    const { width, height, xScale, yRange } = getContext('LayerCake');
+  
+    /** @type {Boolean} [gridlines=true] - Extend lines from the ticks into the chart space */
+    export let gridlines = false;
+  
+    /** @type {Boolean} [tickMarks=false] - Show a vertical mark for each tick. */
+    export let tickMarks = true;
+  
+    /** @type {Boolean} [baseline=false] – Show a solid line at the bottom. */
+    export let baseline = true;
+  
+    /** @type {Boolean} [snapTicks=false] - Instead of centering the text on the first and the last items, align them to the edges of the chart. */
+    export let snapTicks = false;
+  
+    /** @type {Function} [formatTick=d => d] - A function that passes the current tick value and expects a nicely formatted value in return. */
+    export let formatTick = d => d;
+  
+    /** @type {Number|Array|Function} [ticks] - If this is a number, it passes that along to the [d3Scale.ticks](https://github.com/d3/d3-scale) function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return. If nothing, it uses the default ticks supplied by the D3 function. */
+    export let ticks = undefined;
+  
+    /** @type {Number} [xTick=0] - How far over to position the text marker. */
+    export let xTick = 0;
+  
+    /** @type {Number} [yTick=16] - The distance from the baseline to place each tick value. */
+    export let yTick = 16;
+  
+    /** @type {String|null} [axisLabel=null] An optional label for the y axis*/
+    export let axisLabel = null;
+  
+    $: isBandwidth = typeof $xScale.bandwidth === 'function';
+  
+    $: tickVals = Array.isArray(ticks) ? ticks :
+      isBandwidth ?
+        $xScale.domain() :
+        typeof ticks === 'function' ?
+          ticks($xScale.ticks()) :
+            $xScale.ticks(ticks);
+  
+    function textAnchor(i) {
+      if (snapTicks === true) {
+        if (i === 0) {
+          return 'start';
+        }
+        if (i === tickVals.length - 1) {
+          return 'end';
+        }
+      }
+      return 'middle';
+    }
+  </script>
+  
+  <g class="axis x-axis" class:snapTicks>
+    {#each tickVals as tick, i (tick)}
+      <g class="tick tick-{i}" transform="translate({$xScale(tick)},{Math.max(...$yRange)})">
+        {#if gridlines !== false}
+          <line class="gridline" y1={$height * -1} y2="0" x1="0" x2="0" />
+        {/if}
+        {#if tickMarks === true}
+          <line
+            class="tick-mark"
+            y1={0}
+            y2={6}
+            x1={isBandwidth ? $xScale.bandwidth() / 2 : 0}
+            x2={isBandwidth ? $xScale.bandwidth() / 2 : 0}
+          />
+        {/if}
+        <text
+          x={isBandwidth ? ($xScale.bandwidth() / 2 + xTick) : xTick}
+          y={yTick}
+          dx=""
+          dy=""
+          text-anchor={textAnchor(i)}>{formatTick(tick)}</text
+        >
+      </g>
+    {/each}
+    {#if baseline === true}
+      <line class="baseline" y1={$height + 0.5} y2={$height + 0.5} x1="0" x2={$width} />
+    {/if}
+    {#if axisLabel}
+      <text class="axis-label" x={$width / 2} y={$height + 40} dy="-4" fill={"#000"} text-anchor="middle">{axisLabel}</text>
+    {/if}
+  </g>
+  
+  <style>
+    .tick {
+      font-size: 12px;
+      font-weight: 400;
+      font-family: var(--font-family-sans-serif);
+    }
+  
+    line,
+    .tick line {
+      stroke: #DEDDDD;
+    }
+  
+    .tick text {
+      fill: #000000;
+    }
+  
+    .tick .tick-mark,
+    .baseline {
+      stroke: #000000;
+    }
+    /* This looks slightly better */
+    .axis.snapTicks .tick:last-child text {
+      transform: translateX(3px);
+    }
+    .axis.snapTicks .tick.tick-0 text {
+      transform: translateX(-3px);
+    }
+    .axis-label {
+      font-size: 12px;
+    }
+  </style>
\ No newline at end of file
diff --git a/src/lib/Layercake/AxisY.docs.md b/src/lib/Layercake/AxisY.docs.md
new file mode 100644
index 0000000..a7a56db
--- /dev/null
+++ b/src/lib/Layercake/AxisY.docs.md
@@ -0,0 +1,13 @@
+Layercake components can be useful for out-of-the-box Svelte charts. Often, however, they are not built according to Urban style. This AxisY component takes those available in Layercake and updates them to use Urban font family, colors, and sizes. 
+
+Furthermore, while Layercake components are often externally updated, this axis here is set in time at a stage where they will not break our builds. Any updates to merge in newer Layercake code will happen not project to project but here, at source, when decided necessary. Therefore, this axis will always work with expected parameters.
+
+
+## Usage
+
+Layercake axes must be built inside a Layercake component and context, and, further, within an Svg component. Both can be imported from the layercake package. The Layercake object must be passed flat array (not object) data and domain before anything can be initialized and rendered, and these are used across all components used to craft a chart.
+
+
+```js
+import { AxisY } from "@urbaninstitute/dataviz-components";
+```
diff --git a/src/lib/Layercake/AxisY.stories.svelte b/src/lib/Layercake/AxisY.stories.svelte
new file mode 100644
index 0000000..d932c30
--- /dev/null
+++ b/src/lib/Layercake/AxisY.stories.svelte
@@ -0,0 +1,97 @@
+<script context="module">
+  import AxisY from "./AxisY.svelte";
+  import docs from "./AxisY.docs.md?raw";
+
+  export const meta = {
+    title: "Layercake/AxisY",
+    component: AxisY,
+    tags: ["autodocs"],
+    argTypes: {
+      gridlines: {
+        control: "boolean"
+      },
+      tickMarks: {
+        control: "boolean"
+      },
+      ticks: {
+        control: {
+          type: "range",
+          min: 1,
+          max: 10,
+        },
+      },
+      xTick: {
+        control: "number",
+        description: "Equal to dxTick."
+      },
+      yTick: {
+        control: "number",
+        description: "Equal to dyTick."
+      },
+      dxTick: {
+        control: "number",
+        description: "Equal to xTick."
+      },
+      dyTick: {
+        control: "number",
+        description: "Equal to yTick."
+      },
+      textAnchor: {
+        control: "select",
+        options: ["start","middle","end"]
+      },
+      tickLabelColor: {
+        control: {
+          type: "color"
+        }
+      },
+      axisLabel: {
+        control: "text"
+      }
+    },
+    parameters: {
+      backgrounds: {
+        default: "light",
+        values: [
+          { name: "light", value: "#ffffff" },
+          { name: "dark", value: "#0A4C6A" }
+        ]
+      },
+      docs: {
+        description: {
+          component: docs
+        }
+      },
+      githubLink: {
+        url: "/Layercake/AxisY.svelte"
+      }
+    }
+  };
+</script>
+
+<script>
+  import { Story, Template } from "@storybook/addon-svelte-csf";
+  import { LayerCake, Svg } from "layercake";
+  import data from "./data.json"
+
+  const xKey = 'value';
+  const yKey = 'year';
+</script>
+
+<Template let:args>
+  <div style="height: 150px; width:100%;">
+  <LayerCake
+      {data} 
+      xDomain={[0, 20]}
+      yDomain={[0,10]}
+      y={yKey}
+      x={xKey}
+  >
+        <Svg>
+            <AxisY {...args} />
+        </Svg>
+    </LayerCake>
+  </div>
+</Template>
+
+<Story name="Default" />
diff --git a/src/lib/Layercake/AxisY.svelte b/src/lib/Layercake/AxisY.svelte
new file mode 100644
index 0000000..cf7f05c
--- /dev/null
+++ b/src/lib/Layercake/AxisY.svelte
@@ -0,0 +1,107 @@
+<!--
+  @component
+  Generates an SVG y-axis. This component is also configured to detect if your y-scale is an ordinal scale. If so, it will place the markers in the middle of the bandwidth.
+ -->
+ <script>
+    import { getContext } from "svelte";
+  
+    const { padding, xRange, yScale, yDomain, xDomain, xScale, width } = getContext("LayerCake");
+  
+    /** @type {Boolean} [gridlines=true] - Extend lines from the ticks into the chart space */
+    export let gridlines = true;
+  
+    /** @type {Boolean} [tickMarks=false] - Show a vertical mark for each tick. */
+    export let tickMarks = false;
+  
+    /** @type {Function} [formatTick=d => d] - A function that passes the current tick value and expects a nicely formatted value in return. */
+    export let formatTick = (d) => d;
+  
+    /** @type {Number|Array|Function} [ticks=4] - If this is a number, it passes that along to the [d3Scale.ticks](https://github.com/d3/d3-scale) function. If this is an array, hardcodes the ticks to those values. If it"s a function, passes along the default tick values and expects an array of tick values in return. */
+    export let ticks = 4;
+  
+    /** @type {Number} [xTick=0] - How far over to position the text marker. */
+    export let xTick = 0;
+  
+    /** @type {Number} [yTick=0] - How far up and down to position the text marker. */
+    export let yTick = 0;
+  
+    /** @type {Number} [dxTick=-4] - Any optional value passed to the `dx` attribute on the text marker and tick mark (if visible). This is ignored on the text marker if your scale is ordinal. */
+    export let dxTick = -4;
+  
+    /** @type {Number} [dyTick=0] - Any optional value passed to the `dy` attribute on the text marker and tick mark (if visible). This is ignored on the text marker if your scale is ordinal. */
+    export let dyTick = 0;
+  
+    /** @type {String} [textAnchor="end"] The CSS `text-anchor` passed to the label. This is automatically set to "end" if the scale has a bandwidth method, like in ordinal scales. */
+    export let textAnchor = "end";
+  
+    export let tickLabelColor = "#000000";
+  
+    /** @type {String|null} [axisLabel=null] An optional label for the y axis*/
+    export let axisLabel = null;
+  
+    export let labelDx = 0;
+  
+    $: isBandwidth = typeof $yScale.bandwidth === "function";
+  
+    $: tickVals = Array.isArray(ticks)
+      ? ticks
+      : isBandwidth
+      ? $yScale.domain()
+      : typeof ticks === "function"
+      ? ticks($yScale.ticks())
+      : $yScale.ticks(ticks);
+  </script>
+  
+  <g class="axis y-axis" transform="translate({-$padding.left}, 0)">
+    {#each tickVals as tick (tick)}
+      <g
+        class="tick tick-{tick}"
+        transform="translate({$xRange[0] + $padding.left}, {$yScale(tick)})"
+      >
+        {#if gridlines !== false}
+          <line
+            class="gridline"
+            x1={0}
+            x2={$width}
+            y1={isBandwidth ? $yScale.bandwidth() / 2 : 0}
+            y2={isBandwidth ? $yScale.bandwidth() / 2 : 0}
+          />
+        {/if}
+        {#if tickMarks === true}
+          <line
+            class="tick-mark"
+            x1="0"
+            x2={isBandwidth ? -6 : 6}
+            y1={isBandwidth ? $yScale.bandwidth() / 2 : 0}
+            y2={isBandwidth ? $yScale.bandwidth() / 2 : 0}
+          />
+        {/if}
+        <text
+          x={xTick}
+          y={isBandwidth ? $yScale.bandwidth() / 2 + yTick : yTick}
+          dx={isBandwidth ? -9 : dxTick}
+          dy={isBandwidth ? 4 : dyTick}
+          fill={tickLabelColor}
+          style="text-anchor:{isBandwidth ? 'end' : textAnchor}; alignment-baseline:middle;"
+          >{formatTick(tick)}</text
+        >
+      </g>
+    {/each}
+    {#if axisLabel}
+      <text class="axis-label" x={$padding.left} y="0" dy="-8" dx={labelDx} fill={tickLabelColor}>{axisLabel}</text>
+    {/if}
+  </g>
+  
+  <style>
+    .tick, .axis-label {
+      font-size: 12px;
+      font-family: var(--font-family-sans-serif);
+    }
+  
+    .tick line {
+      stroke: #dedddd;
+    }
+    .tick:first-of-type line {
+      stroke: #000000;
+    }
+  </style>
\ No newline at end of file
diff --git a/src/lib/Layercake/data.json b/src/lib/Layercake/data.json
new file mode 100644
index 0000000..55e6a46
--- /dev/null
+++ b/src/lib/Layercake/data.json
@@ -0,0 +1,8 @@
+[
+["year","value"],
+[1979, 2],
+[1980, 3],
+[1981, 5],
+[1982, 8],
+[1983, 18]
+]
\ No newline at end of file
diff --git a/src/lib/index.js b/src/lib/index.js
index e03e915..f35f7b1 100644
--- a/src/lib/index.js
+++ b/src/lib/index.js
@@ -27,3 +27,5 @@ export { default as Headline } from "./Headline/Headline.svelte";
 export { default as PymChild } from "./Pym/PymChild.svelte";
 export { default as LoadingWrapper } from "./LoadingWrapper/LoadingWrapper.svelte";
 export { default as Tooltip } from "./Tooltip/Tooltip.svelte";
+export { default as AxisY } from "./Layercake/AxisY.svelte";
+export { default as AxisX } from "./Layercake/AxisX.svelte";
\ No newline at end of file