@misoto22/design 0.3.1 → 0.6.0

package/dist/charts/BarList/BarList.d.ts

@@ -0,0 +1,57 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface BarListItem {
+    /** What the row is. Doubles as its key, so it must be unique. */
+    name: string;
+    value: number;
+    /** Turns the row's name into a link. */
+    href?: string;
+    /** Drawn before the name — a favicon, a status dot, a flag. */
+    icon?: ReactNode;
+}
+interface BarListProps {
+    /** What the list ranks. Required: it names the table for a screen reader. */
+    label: string;
+    /** Prints the label above the list instead of hiding it from sight. */
+    showLabel?: boolean;
+    items: BarListItem[];
+    /** Keeps the top N and folds the rest into one "Other" row. */
+    limit?: number;
+    /** Formats each value. Defaults to the same compact form the axes use. */
+    formatValue?: (value: number) => string;
+    /**
+     * The scale's ceiling. Derived from the largest row when omitted.
+     *
+     * Pin it to compare two lists side by side — on independent scales the
+     * leading row of each fills its track, and two very different numbers look
+     * identical.
+     */
+    max?: number;
+    /** Sorts descending before rendering. */
+    sort?: boolean;
+    className?: string;
+}
+/**
+ * A ranked list, with the bar behind the name rather than beside it.
+ *
+ * The answer to "top referrers", "slowest endpoints", "biggest accounts" — and
+ * a better one than a horizontal bar chart, which spends a third of its width
+ * on a category axis repeating labels the rows could simply contain. Reading a
+ * name off a y-axis and matching it to a bar is two steps; reading it off the
+ * bar is none.
+ *
+ * It is a `<table>`, because that is what it is: two columns, a header, and one
+ * row per thing. The bar is a background on the name cell, so it never becomes
+ * a second element a screen reader has to walk past.
+ *
+ * Reach for `<BarChart orientation="horizontal">` instead when the categories
+ * are few and fixed and the axis is doing real work — a scale a reader needs to
+ * read values off, rather than a ranking they need to skim.
+ *
+ * @example
+ * <BarList label="Top referrers" items={referrers} limit={5} />
+ */
+declare function BarList({ label, showLabel, items, limit, formatValue, max, sort, className, }: BarListProps): react.JSX.Element;
+
+export { BarList, type BarListItem, type BarListProps, BarList as default };

package/dist/charts/BarList/BarList.js

@@ -0,0 +1,71 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+import { defaultTick } from "../lib/format.js";
+function BarList({
+  label,
+  showLabel = false,
+  items,
+  limit,
+  formatValue = defaultTick,
+  max,
+  sort = true,
+  className
+}) {
+  const ordered = sort ? [...items].sort((a, b) => b.value - a.value) : items;
+  const shown = limit !== void 0 && ordered.length > limit ? [
+    ...ordered.slice(0, limit),
+    {
+      name: "Other",
+      value: ordered.slice(limit).reduce((sum, item) => sum + item.value, 0)
+    }
+  ] : ordered;
+  const ceiling = max ?? Math.max(1, ...shown.map((item) => item.value));
+  return /* @__PURE__ */ jsx("div", { className: cn("flex w-full flex-col gap-2", className), children: /* @__PURE__ */ jsxs("table", { className: "w-full border-collapse text-sm", children: [
+    /* @__PURE__ */ jsx(
+      "caption",
+      {
+        className: cn(
+          "text-start",
+          showLabel ? "mb-2 eyebrow text-(--ink-3-aa)" : "sr-only"
+        ),
+        children: label
+      }
+    ),
+    /* @__PURE__ */ jsx("thead", { className: "sr-only", children: /* @__PURE__ */ jsxs("tr", { children: [
+      /* @__PURE__ */ jsx("th", { scope: "col", children: "Name" }),
+      /* @__PURE__ */ jsx("th", { scope: "col", children: "Value" })
+    ] }) }),
+    /* @__PURE__ */ jsx("tbody", { children: shown.map((item) => {
+      const share = Math.max(0, Math.min(1, item.value / ceiling));
+      return /* @__PURE__ */ jsxs("tr", { className: "align-middle", children: [
+        /* @__PURE__ */ jsx("th", { scope: "row", className: "w-full py-1 pe-3 text-start font-normal", children: /* @__PURE__ */ jsxs(
+          "span",
+          {
+            className: "flex h-8 items-center gap-2 rounded-(--radius-sm) px-2 text-(--ink)",
+            style: {
+              background: `linear-gradient(to right, color-mix(in srgb, var(--series-1) calc(var(--chart-fill) * 100%), transparent) ${share * 100}%, transparent ${share * 100}%)`
+            },
+            children: [
+              item.icon && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "flex shrink-0 items-center text-(--ink-3-aa)", children: item.icon }),
+              item.href ? /* @__PURE__ */ jsx(
+                "a",
+                {
+                  href: item.href,
+                  className: "truncate underline-offset-2 hover:underline focus-visible:underline",
+                  children: item.name
+                }
+              ) : /* @__PURE__ */ jsx("span", { className: "truncate", children: item.name })
+            ]
+          }
+        ) }),
+        /* @__PURE__ */ jsx("td", { className: "py-1 text-end font-mono text-xs whitespace-nowrap tabular-nums text-(--ink-2)", children: formatValue(item.value) })
+      ] }, item.name);
+    }) })
+  ] }) });
+}
+var BarList_default = BarList;
+export {
+  BarList,
+  BarList_default as default
+};
+//# sourceMappingURL=BarList.js.map

package/dist/charts/BarList/BarList.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/charts/BarList/BarList.tsx"],"sourcesContent":["import type { ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\nimport { defaultTick } from '../lib/format'\n\nexport interface BarListItem {\n  /** What the row is. Doubles as its key, so it must be unique. */\n  name: string\n  value: number\n  /** Turns the row's name into a link. */\n  href?: string\n  /** Drawn before the name — a favicon, a status dot, a flag. */\n  icon?: ReactNode\n}\n\nexport interface BarListProps {\n  /** What the list ranks. Required: it names the table for a screen reader. */\n  label: string\n  /** Prints the label above the list instead of hiding it from sight. */\n  showLabel?: boolean\n  items: BarListItem[]\n  /** Keeps the top N and folds the rest into one \"Other\" row. */\n  limit?: number\n  /** Formats each value. Defaults to the same compact form the axes use. */\n  formatValue?: (value: number) => string\n  /**\n   * The scale's ceiling. Derived from the largest row when omitted.\n   *\n   * Pin it to compare two lists side by side — on independent scales the\n   * leading row of each fills its track, and two very different numbers look\n   * identical.\n   */\n  max?: number\n  /** Sorts descending before rendering. */\n  sort?: boolean\n  className?: string\n}\n\n/**\n * A ranked list, with the bar behind the name rather than beside it.\n *\n * The answer to \"top referrers\", \"slowest endpoints\", \"biggest accounts\" — and\n * a better one than a horizontal bar chart, which spends a third of its width\n * on a category axis repeating labels the rows could simply contain. Reading a\n * name off a y-axis and matching it to a bar is two steps; reading it off the\n * bar is none.\n *\n * It is a `<table>`, because that is what it is: two columns, a header, and one\n * row per thing. The bar is a background on the name cell, so it never becomes\n * a second element a screen reader has to walk past.\n *\n * Reach for `<BarChart orientation=\"horizontal\">` instead when the categories\n * are few and fixed and the axis is doing real work — a scale a reader needs to\n * read values off, rather than a ranking they need to skim.\n *\n * @example\n * <BarList label=\"Top referrers\" items={referrers} limit={5} />\n */\nexport function BarList({\n  label,\n  showLabel = false,\n  items,\n  limit,\n  formatValue = defaultTick,\n  max,\n  sort = true,\n  className,\n}: BarListProps) {\n  const ordered = sort ? [...items].sort((a, b) => b.value - a.value) : items\n\n  // The tail is summed rather than dropped: a \"top five\" that silently discards\n  // the other forty misstates the whole, and the reader has no way to tell.\n  const shown =\n    limit !== undefined && ordered.length > limit\n      ? [\n          ...ordered.slice(0, limit),\n          {\n            name: 'Other',\n            value: ordered.slice(limit).reduce((sum, item) => sum + item.value, 0),\n          },\n        ]\n      : ordered\n\n  const ceiling = max ?? Math.max(1, ...shown.map((item) => item.value))\n\n  return (\n    <div className={cn('flex w-full flex-col gap-2', className)}>\n      <table className=\"w-full border-collapse text-sm\">\n        <caption\n          className={cn(\n            'text-start',\n            showLabel ? 'mb-2 eyebrow text-(--ink-3-aa)' : 'sr-only',\n          )}\n        >\n          {label}\n        </caption>\n        <thead className=\"sr-only\">\n          <tr>\n            <th scope=\"col\">Name</th>\n            <th scope=\"col\">Value</th>\n          </tr>\n        </thead>\n        <tbody>\n          {shown.map((item) => {\n            const share = Math.max(0, Math.min(1, item.value / ceiling))\n\n            return (\n              <tr key={item.name} className=\"align-middle\">\n                <th scope=\"row\" className=\"w-full py-1 pe-3 text-start font-normal\">\n                  {/* The bar is a background on the cell, not a sibling: an\n                      empty <div> beside the name would be one more thing in the\n                      accessibility tree saying nothing. */}\n                  <span\n                    className=\"flex h-8 items-center gap-2 rounded-(--radius-sm) px-2 text-(--ink)\"\n                    style={{\n                      background: `linear-gradient(to right, color-mix(in srgb, var(--series-1) calc(var(--chart-fill) * 100%), transparent) ${share * 100}%, transparent ${share * 100}%)`,\n                    }}\n                  >\n                    {item.icon && (\n                      <span aria-hidden className=\"flex shrink-0 items-center text-(--ink-3-aa)\">\n                        {item.icon}\n                      </span>\n                    )}\n                    {item.href ? (\n                      <a\n                        href={item.href}\n                        className=\"truncate underline-offset-2 hover:underline focus-visible:underline\"\n                      >\n                        {item.name}\n                      </a>\n                    ) : (\n                      <span className=\"truncate\">{item.name}</span>\n                    )}\n                  </span>\n                </th>\n                <td className=\"py-1 text-end font-mono text-xs whitespace-nowrap tabular-nums text-(--ink-2)\">\n                  {formatValue(item.value)}\n                </td>\n              </tr>\n            )\n          })}\n        </tbody>\n      </table>\n    </div>\n  )\n}\n\nexport default BarList\n"],"mappings":"AAuFQ,cASE,YATF;AAtFR,SAAS,UAAU;AACnB,SAAS,mBAAmB;AAuDrB,SAAS,QAAQ;AAAA,EACtB;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA;AAAA,EACA,cAAc;AAAA,EACd;AAAA,EACA,OAAO;AAAA,EACP;AACF,GAAiB;AACf,QAAM,UAAU,OAAO,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,IAAI;AAItE,QAAM,QACJ,UAAU,UAAa,QAAQ,SAAS,QACpC;AAAA,IACE,GAAG,QAAQ,MAAM,GAAG,KAAK;AAAA,IACzB;AAAA,MACE,MAAM;AAAA,MACN,OAAO,QAAQ,MAAM,KAAK,EAAE,OAAO,CAAC,KAAK,SAAS,MAAM,KAAK,OAAO,CAAC;AAAA,IACvE;AAAA,EACF,IACA;AAEN,QAAM,UAAU,OAAO,KAAK,IAAI,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC;AAErE,SACE,oBAAC,SAAI,WAAW,GAAG,8BAA8B,SAAS,GACxD,+BAAC,WAAM,WAAU,kCACf;AAAA;AAAA,MAAC;AAAA;AAAA,QACC,WAAW;AAAA,UACT;AAAA,UACA,YAAY,mCAAmC;AAAA,QACjD;AAAA,QAEC;AAAA;AAAA,IACH;AAAA,IACA,oBAAC,WAAM,WAAU,WACf,+BAAC,QACC;AAAA,0BAAC,QAAG,OAAM,OAAM,kBAAI;AAAA,MACpB,oBAAC,QAAG,OAAM,OAAM,mBAAK;AAAA,OACvB,GACF;AAAA,IACA,oBAAC,WACE,gBAAM,IAAI,CAAC,SAAS;AACnB,YAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,KAAK,QAAQ,OAAO,CAAC;AAE3D,aACE,qBAAC,QAAmB,WAAU,gBAC5B;AAAA,4BAAC,QAAG,OAAM,OAAM,WAAU,2CAIxB;AAAA,UAAC;AAAA;AAAA,YACC,WAAU;AAAA,YACV,OAAO;AAAA,cACL,YAAY,6GAA6G,QAAQ,GAAG,kBAAkB,QAAQ,GAAG;AAAA,YACnK;AAAA,YAEC;AAAA,mBAAK,QACJ,oBAAC,UAAK,eAAW,MAAC,WAAU,gDACzB,eAAK,MACR;AAAA,cAED,KAAK,OACJ;AAAA,gBAAC;AAAA;AAAA,kBACC,MAAM,KAAK;AAAA,kBACX,WAAU;AAAA,kBAET,eAAK;AAAA;AAAA,cACR,IAEA,oBAAC,UAAK,WAAU,YAAY,eAAK,MAAK;AAAA;AAAA;AAAA,QAE1C,GACF;AAAA,QACA,oBAAC,QAAG,WAAU,iFACX,sBAAY,KAAK,KAAK,GACzB;AAAA,WA9BO,KAAK,IA+Bd;AAAA,IAEJ,CAAC,GACH;AAAA,KACF,GACF;AAEJ;AAEA,IAAO,kBAAQ;","names":[]}

package/dist/charts/BigNumber/BigNumber.d.ts

@@ -0,0 +1,56 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Which way a change is good. */
+type DeltaIntent = 'up-is-good' | 'down-is-good' | 'neutral';
+interface BigNumberDelta {
+    /** The change, already computed. Positive is up, whatever that means here. */
+    value: number;
+    /** What it is a change from — "vs last week". */
+    label?: ReactNode;
+    /**
+     * Which direction counts as good.
+     *
+     * Required rather than assumed, because the assumption is wrong half the
+     * time: revenue up is good, error rate up is not, and a component that
+     * guesses will confidently colour a bad number green.
+     */
+    intent?: DeltaIntent;
+    /** Formats the change. Defaults to a signed percentage. */
+    format?: (value: number) => string;
+}
+interface BigNumberProps {
+    /** What the number counts. */
+    label: ReactNode;
+    /** The number, already formatted — this component does not guess a unit. */
+    value: ReactNode;
+    delta?: BigNumberDelta;
+    /** A sparkline, a note, a caveat. Sits under the number. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * One number, at the size of a headline.
+ *
+ * The form most dashboards need most often and most chart libraries do not
+ * ship, on the grounds that it is not a chart. It is the right answer whenever
+ * there is exactly one figure to report: a plot of a single value is a plot
+ * whose shape carries nothing, and the reader has to decode an axis to recover
+ * a number that could simply have been printed.
+ *
+ * The delta is where this earns its place over a `<p>`. Direction is stated by
+ * the CALL SITE (`intent`), never inferred: "errors down 12%" is good news and
+ * "revenue down 12%" is not, and no component can tell which it is holding.
+ * Where the direction is known, the arrow and the word carry it — the status
+ * colour is the third signal, never the only one.
+ *
+ * @example
+ * <BigNumber
+ *   label="Monthly revenue"
+ *   value="$48,210"
+ *   delta={{ value: 0.124, label: 'vs last month', intent: 'up-is-good' }}
+ * />
+ */
+declare function BigNumber({ label, value, delta, children, className }: BigNumberProps): react.JSX.Element;
+
+export { BigNumber, type BigNumberDelta, type BigNumberProps, type DeltaIntent, BigNumber as default };

package/dist/charts/BigNumber/BigNumber.js

@@ -0,0 +1,31 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+const signed = (value) => `${value > 0 ? "+" : ""}${(value * 100).toFixed(1).replace(/\.0$/, "")}%`;
+function BigNumber({ label, value, delta, children, className }) {
+  const intent = delta?.intent ?? "neutral";
+  const format = delta?.format ?? signed;
+  const rising = (delta?.value ?? 0) > 0;
+  const flat = (delta?.value ?? 0) === 0;
+  const good = intent === "neutral" ? null : intent === "up-is-good" ? rising : !rising;
+  const tone = flat || good === null ? "text-(--ink-2)" : good ? "text-(--ok)" : "text-(--danger)";
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-1", className), children: [
+    /* @__PURE__ */ jsx("span", { className: "eyebrow text-(--ink-3-aa)", children: label }),
+    /* @__PURE__ */ jsx("span", { className: "font-heading text-[length:var(--fs-lead)] leading-none text-(--ink) tabular-nums", children: value }),
+    delta && /* @__PURE__ */ jsxs("span", { className: cn("flex items-baseline gap-1.5 mono-meta", tone), children: [
+      /* @__PURE__ */ jsx("span", { "aria-hidden": true, children: flat ? "\u2192" : rising ? "\u2191" : "\u2193" }),
+      /* @__PURE__ */ jsx("span", { children: format(delta.value) }),
+      /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+        flat ? "no change" : rising ? "up" : "down",
+        good === null ? "" : good ? ", better" : ", worse"
+      ] }),
+      delta.label && /* @__PURE__ */ jsx("span", { className: "text-(--ink-3-aa)", children: delta.label })
+    ] }),
+    children && /* @__PURE__ */ jsx("div", { className: "mt-2", children })
+  ] });
+}
+var BigNumber_default = BigNumber;
+export {
+  BigNumber,
+  BigNumber_default as default
+};
+//# sourceMappingURL=BigNumber.js.map

package/dist/charts/BigNumber/BigNumber.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/charts/BigNumber/BigNumber.tsx"],"sourcesContent":["import type { ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\n/** Which way a change is good. */\nexport type DeltaIntent = 'up-is-good' | 'down-is-good' | 'neutral'\n\nexport interface BigNumberDelta {\n  /** The change, already computed. Positive is up, whatever that means here. */\n  value: number\n  /** What it is a change from — \"vs last week\". */\n  label?: ReactNode\n  /**\n   * Which direction counts as good.\n   *\n   * Required rather than assumed, because the assumption is wrong half the\n   * time: revenue up is good, error rate up is not, and a component that\n   * guesses will confidently colour a bad number green.\n   */\n  intent?: DeltaIntent\n  /** Formats the change. Defaults to a signed percentage. */\n  format?: (value: number) => string\n}\n\nexport interface BigNumberProps {\n  /** What the number counts. */\n  label: ReactNode\n  /** The number, already formatted — this component does not guess a unit. */\n  value: ReactNode\n  delta?: BigNumberDelta\n  /** A sparkline, a note, a caveat. Sits under the number. */\n  children?: ReactNode\n  className?: string\n}\n\nconst signed = (value: number): string =>\n  `${value > 0 ? '+' : ''}${(value * 100).toFixed(1).replace(/\\.0$/, '')}%`\n\n/**\n * One number, at the size of a headline.\n *\n * The form most dashboards need most often and most chart libraries do not\n * ship, on the grounds that it is not a chart. It is the right answer whenever\n * there is exactly one figure to report: a plot of a single value is a plot\n * whose shape carries nothing, and the reader has to decode an axis to recover\n * a number that could simply have been printed.\n *\n * The delta is where this earns its place over a `<p>`. Direction is stated by\n * the CALL SITE (`intent`), never inferred: \"errors down 12%\" is good news and\n * \"revenue down 12%\" is not, and no component can tell which it is holding.\n * Where the direction is known, the arrow and the word carry it — the status\n * colour is the third signal, never the only one.\n *\n * @example\n * <BigNumber\n *   label=\"Monthly revenue\"\n *   value=\"$48,210\"\n *   delta={{ value: 0.124, label: 'vs last month', intent: 'up-is-good' }}\n * />\n */\nexport function BigNumber({ label, value, delta, children, className }: BigNumberProps) {\n  const intent = delta?.intent ?? 'neutral'\n  const format = delta?.format ?? signed\n  const rising = (delta?.value ?? 0) > 0\n  const flat = (delta?.value ?? 0) === 0\n\n  const good = intent === 'neutral' ? null : intent === 'up-is-good' ? rising : !rising\n  const tone = flat || good === null ? 'text-(--ink-2)' : good ? 'text-(--ok)' : 'text-(--danger)'\n\n  return (\n    <div className={cn('flex flex-col gap-1', className)}>\n      <span className=\"eyebrow text-(--ink-3-aa)\">{label}</span>\n\n      {/* The serif, at the record-title step. A number this size is the page's\n          headline, and the system sets headlines in the editorial face. */}\n      <span className=\"font-heading text-[length:var(--fs-lead)] leading-none text-(--ink) tabular-nums\">\n        {value}\n      </span>\n\n      {delta && (\n        <span className={cn('flex items-baseline gap-1.5 mono-meta', tone)}>\n          {/* The arrow is the second carrier and the word is the third, so the\n              reading survives greyscale, forced colours and colour blindness —\n              which the status tint alone does not. */}\n          <span aria-hidden>{flat ? '→' : rising ? '↑' : '↓'}</span>\n          <span>{format(delta.value)}</span>\n          <span className=\"sr-only\">\n            {flat ? 'no change' : rising ? 'up' : 'down'}\n            {good === null ? '' : good ? ', better' : ', worse'}\n          </span>\n          {delta.label && <span className=\"text-(--ink-3-aa)\">{delta.label}</span>}\n        </span>\n      )}\n\n      {children && <div className=\"mt-2\">{children}</div>}\n    </div>\n  )\n}\n\nexport default BigNumber\n"],"mappings":"AAsEM,cAeI,YAfJ;AArEN,SAAS,UAAU;AAiCnB,MAAM,SAAS,CAAC,UACd,GAAG,QAAQ,IAAI,MAAM,EAAE,IAAI,QAAQ,KAAK,QAAQ,CAAC,EAAE,QAAQ,QAAQ,EAAE,CAAC;AAwBjE,SAAS,UAAU,EAAE,OAAO,OAAO,OAAO,UAAU,UAAU,GAAmB;AACtF,QAAM,SAAS,OAAO,UAAU;AAChC,QAAM,SAAS,OAAO,UAAU;AAChC,QAAM,UAAU,OAAO,SAAS,KAAK;AACrC,QAAM,QAAQ,OAAO,SAAS,OAAO;AAErC,QAAM,OAAO,WAAW,YAAY,OAAO,WAAW,eAAe,SAAS,CAAC;AAC/E,QAAM,OAAO,QAAQ,SAAS,OAAO,mBAAmB,OAAO,gBAAgB;AAE/E,SACE,qBAAC,SAAI,WAAW,GAAG,uBAAuB,SAAS,GACjD;AAAA,wBAAC,UAAK,WAAU,6BAA6B,iBAAM;AAAA,IAInD,oBAAC,UAAK,WAAU,oFACb,iBACH;AAAA,IAEC,SACC,qBAAC,UAAK,WAAW,GAAG,yCAAyC,IAAI,GAI/D;AAAA,0BAAC,UAAK,eAAW,MAAE,iBAAO,WAAM,SAAS,WAAM,UAAI;AAAA,MACnD,oBAAC,UAAM,iBAAO,MAAM,KAAK,GAAE;AAAA,MAC3B,qBAAC,UAAK,WAAU,WACb;AAAA,eAAO,cAAc,SAAS,OAAO;AAAA,QACrC,SAAS,OAAO,KAAK,OAAO,aAAa;AAAA,SAC5C;AAAA,MACC,MAAM,SAAS,oBAAC,UAAK,WAAU,qBAAqB,gBAAM,OAAM;AAAA,OACnE;AAAA,IAGD,YAAY,oBAAC,SAAI,WAAU,QAAQ,UAAS;AAAA,KAC/C;AAEJ;AAEA,IAAO,oBAAQ;","names":[]}

package/dist/charts/BoxPlot/BoxPlot.d.ts

@@ -0,0 +1,177 @@
+import { ChartTooltipSlotProps } from '../AreaChart/AreaChart.js';
+import { ChartXAxisProps, ChartYAxisProps } from '../BarChart/BarChart.js';
+import * as react from 'react';
+import { ReactNode, ComponentProps } from 'react';
+import { BarChart, Bar, CartesianGrid } from 'recharts';
+import { ChartConfig } from '../lib/chart.js';
+import { ChartEmptyProps } from '../lib/empty.js';
+import { ChartBackgroundVariant } from '../lib/background.js';
+import { ReferenceLine, ReferenceBand, Annotation } from '../lib/annotations.js';
+import '../lib/values.js';
+import '../lib/sonify-control.js';
+import '../lib/sonify.js';
+import '../lib/brush.js';
+import '../lib/toolbar.js';
+import '../lib/zoom.js';
+import '../lib/figure.js';
+import '../lib/paint.js';
+import '../lib/dot.js';
+import '../lib/legend.js';
+import '../lib/tooltip.js';
+import 'recharts/types/component/DefaultTooltipContent';
+
+/** Which way the boxes run. */
+type BoxPlotOrientation = 'vertical' | 'horizontal';
+/** A category summarised into the five numbers a box is drawn from. */
+interface BoxPlotSummary {
+    /** What the box describes. Doubles as its key, so it must be unique. */
+    name: string;
+    /** The low whisker's end — the smallest observation inside the fence. */
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    /** The high whisker's end — the largest observation inside the fence. */
+    max: number;
+    /** Points outside the fences, drawn one dot each. */
+    outliers?: number[];
+    /**
+     * How many observations the box stands for.
+     *
+     * Needed for a notch, and worth carrying anyway: a box drawn from six points
+     * and a box drawn from six thousand look identical, and only one of them
+     * means anything.
+     */
+    count?: number;
+}
+/** A category handed over as raw observations, for the chart to summarise. */
+interface BoxPlotSample {
+    /** What the box describes. Doubles as its key, so it must be unique. */
+    name: string;
+    /** Every observation in this category, in any order. */
+    values: number[];
+    min?: never;
+    q1?: never;
+    median?: never;
+    q3?: never;
+    max?: never;
+}
+/**
+ * One category: either the raw observations, or the summary itself.
+ *
+ * Both forms exist because both are real. A chart fed from a warehouse gets
+ * percentiles back from the query and never sees a row; a chart fed from a
+ * browser has the array in hand and should not have to compute quartiles to
+ * draw them.
+ */
+type BoxPlotDatum = BoxPlotSample | (BoxPlotSummary & {
+    values?: never;
+});
+interface BoxPlotProps {
+    /**
+     * The single series — its label and its paint. Only the FIRST entry is read;
+     * a box plot has one measurement and as many categories as it has boxes.
+     */
+    config?: ChartConfig;
+    /** One entry per category, as raw observations or as a summary. */
+    data: BoxPlotDatum[];
+    /**
+     * What the chart shows, in a sentence a reader could act on. Required, and
+     * announced to a screen reader even when it is not printed.
+     */
+    title: string;
+    /** Prints the title above the plot instead of hiding it from sight. */
+    showTitle?: boolean;
+    /** A line under the title — the unit, the window, the caveat. */
+    description?: ReactNode;
+    /** The composed parts — axes, grid, tooltip, and `<BoxPlot.Boxes>`. */
+    children: ReactNode;
+    /** Merged onto the figure, last, so a call site can size or space it. */
+    className?: string;
+    /** Escape hatch onto the raw Recharts chart element. */
+    chartProps?: ComponentProps<typeof BarChart>;
+    /**
+     * Which way the boxes run. Reach for `horizontal` when the category names
+     * are long enough to need rotating under a column.
+     */
+    orientation?: BoxPlotOrientation;
+    /** Formats every number the chart prints — ticks, tooltip, table. */
+    formatValue?: (value: number) => string;
+    /** Drops the hidden table view. Only correct when the page prints the data itself. */
+    hideDataTable?: boolean;
+    /**
+     * What the chart shows when it has nothing to draw. `false` keeps the axes,
+     * for a chart whose emptiness is itself the reading.
+     */
+    empty?: ChartEmptyProps | false;
+}
+/**
+ * The spread of a measurement, per category — median, middle half, reach, and
+ * the points that sit outside it.
+ *
+ * The form to reach for when the question is "how variable is this", and the
+ * one that answers it in a tenth of the ink a histogram per category would
+ * take. Six response-time distributions fit across one screen as six boxes;
+ * as six histograms they do not fit at all.
+ *
+ * **What a box plot hides is multimodality.** A box is five numbers, and five
+ * numbers cannot tell a single hump from two. A bimodal distribution — a fast
+ * cache path and a slow database path, two cohorts inside one average — draws
+ * exactly the same box as a smooth one centred in the same place, and the
+ * reader has no way to tell from the picture that the middle of the box is a
+ * value almost nothing takes. It also hides sample size: a box over six points
+ * and a box over six thousand are drawn identically, which is why `count` is
+ * worth carrying and why a notch, which does read `count`, is worth turning on
+ * when medians are being compared. When the SHAPE of one distribution is the
+ * question, reach for `<Histogram>`; when there are few enough observations to
+ * draw them all, reach for `<ScatterChart>` and plot the points.
+ *
+ * Recharts earns its place here: the boxes need a shared value axis with real
+ * ticks, a category axis, a grid and a tooltip, which is most of a cartesian
+ * chart. What it does not have is a box mark, so each box is drawn as a custom
+ * shape over a range bar — the bar supplies the category band and the scale,
+ * and the glyph inside it is ours.
+ *
+ * @example
+ * <BoxPlot title="Response time by region" data={regions}>
+ *   <BoxPlot.Grid />
+ *   <BoxPlot.XAxis />
+ *   <BoxPlot.YAxis label="ms" />
+ *   <BoxPlot.Tooltip />
+ *   <BoxPlot.Boxes showOutliers />
+ * </BoxPlot>
+ *
+ * @example
+ * // Raw observations, summarised for you with Tukey's fences.
+ * const data = [{ name: 'Sydney', values: [180, 194, 210, 205, 640] }]
+ */
+declare function BoxPlot({ config, data, title, showTitle, description, children, className, chartProps, orientation, formatValue, hideDataTable, empty, }: BoxPlotProps): react.JSX.Element;
+declare namespace BoxPlot {
+    var Boxes: ({ showOutliers, notch, barProps }: BoxPlotBoxesProps) => react.JSX.Element;
+    var XAxis: ({ dataKey, tickLine, axisLine, tickMargin, minTickGap, type, label, tickFormatter, domain, ...rest }: ChartXAxisProps) => react.JSX.Element;
+    var YAxis: ({ dataKey, tickLine, axisLine, tickMargin, minTickGap, width, type, label, tickFormatter, domain, ...rest }: ChartYAxisProps) => react.JSX.Element;
+    var Grid: ({ strokeDasharray, vertical, horizontal, ...rest }: ComponentProps<typeof CartesianGrid>) => react.JSX.Element;
+    var Tooltip: ({ variant, roundness, defaultIndex }: ChartTooltipSlotProps) => react.JSX.Element;
+    var Background: ({ variant }: {
+        variant: ChartBackgroundVariant;
+    }) => react.JSX.Element;
+    var ReferenceLine: typeof ReferenceLine;
+    var ReferenceBand: typeof ReferenceBand;
+    var Annotation: typeof Annotation;
+}
+interface BoxPlotBoxesProps {
+    /** Draws the points outside the fences as individual dots. */
+    showOutliers?: boolean;
+    /**
+     * Pinches the box in at the median by `1.58 × IQR / √n`.
+     *
+     * A confidence interval on the median drawn INSIDE the shape it belongs to,
+     * which is the only place a reader will actually look at it. Needs `count`
+     * on every box; a box without one is drawn square.
+     */
+    notch?: boolean;
+    /** Escape hatch onto the range bar the boxes are drawn over. */
+    barProps?: ComponentProps<typeof Bar>;
+}
+
+export { BoxPlot, type BoxPlotBoxesProps, type BoxPlotDatum, type BoxPlotOrientation, type BoxPlotProps, type BoxPlotSample, type BoxPlotSummary, BoxPlot as default };