@heyramzi/ui 2.24.0 → 3.1.0

package/src/charts/dashboard/data-table.svelte.d.ts

@@ -0,0 +1,86 @@
+import type { Snippet } from "svelte";
+/** Narrow screens drop the columns that only add detail. */
+export type DataColumnBreakpoint = "sm" | "md" | "lg";
+/** One column after the lead. Give it `value`, `rating` or a `cell` snippet. */
+export type DataColumn<T> = {
+    key: string;
+    label: string;
+    /** The long form of the head, as its tooltip. */
+    hint?: string;
+    /** A Tailwind width class. Fixed widths are what keep the lead column wide. */
+    width: string;
+    /** Figures run to the end, so digits line up. Text, pills and bars start. */
+    align?: "start" | "end";
+    /** Makes the head rank the table. Higher is better; a new column starts descending. */
+    sort?: (row: T) => number;
+    /** Null draws the table's empty label, muted. */
+    value?: (row: T) => string | null;
+    rating?: (row: T) => {
+        grade: string;
+        hint?: string;
+    } | null;
+    cell?: Snippet<[T]>;
+    /** 0 to 1, a share-of-max track drawn before the value. */
+    bar?: (row: T) => number;
+    /** Cell tooltip. */
+    title?: (row: T) => string | undefined;
+    muted?: boolean | ((row: T) => boolean);
+    /** A loss, an overrun: the value turns the destructive colour. */
+    negative?: (row: T) => boolean;
+    /** The column the eye lands on first. */
+    strong?: boolean;
+    /** A hairline before this column, opening a group. */
+    rule?: boolean;
+    /** Hidden under this breakpoint. */
+    hideBelow?: DataColumnBreakpoint;
+};
+import { type SortState } from "../../components/data-table/index.js";
+declare function $$render<T>(): {
+    props: {
+        rows: T[];
+        columns: DataColumn<T>[];
+        rowKey: (row: T) => string;
+        leadLabel: string;
+        lead: Snippet<[T]>;
+        /** Drawn where a value or rating is null. */
+        emptyLabel: string;
+        /** A Tailwind width class. Omit and the lead takes whatever the figures leave. */
+        leadWidth?: string;
+        /** A Tailwind min-width class, past which the panel scrolls sideways. */
+        minWidth?: string;
+        /** Omit for every row on one page. */
+        pageSize?: number;
+        /** The ranked column and its direction. Bind it; a column with `sort` sets it. */
+        sort?: SortState;
+        page?: number;
+        /** The row opens a page. The lead becomes the link. */
+        rowHref?: (row: T) => string;
+        /** The row opens in place: a panel, a detail view. The lead becomes the button. */
+        onRowClick?: (row: T) => void;
+        /** Placeholder rows while the data is on its way. */
+        loading?: boolean;
+        /** Drawn in place of the body when there are no rows. */
+        empty?: Snippet;
+    };
+    exports: {};
+    bindings: "sort" | "page";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "sort" | "page";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<T> = InstanceType<typeof $$Component<T>>;
+export default $$Component;

package/src/charts/dashboard/index.ts

@@ -1,4 +1,3 @@
-export { default as DataPanel } from "../../lib/panel.svelte";
 export {
   default as DataTable,
   type DataColumn,

package/src/charts/dashboard/panel-grid.svelte

@@ -9,7 +9,7 @@
 	// TYPES
 	// =========================
 	interface Props {
-		/** `<DataPanel>` children, or tiles standing beside one. */
+		/** `<DetailPanel>` children, or tiles standing beside one. */
 		children: Snippet;
 		/**
 		 * Panels per row: two charts, three breakdowns, or `main`, where the first

package/src/charts/dashboard/panel-grid.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from "svelte";
+interface Props {
+    /** `<DetailPanel>` children, or tiles standing beside one. */
+    children: Snippet;
+    /**
+     * Panels per row: two charts, three breakdowns, or `main`, where the first
+     * child takes two thirds and the rates beside it one third.
+     */
+    columns?: 2 | 3 | "main";
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/charts/dashboard/period-filter.svelte.d.ts

@@ -0,0 +1,37 @@
+import { type TabDef } from "../../components/segmented/index.js";
+declare function $$render<T extends string>(): {
+    props: {
+        options: readonly TabDef<T>[];
+        value: T;
+        /**
+         * Give this and the strip is links, so the choice survives reload, back and a
+         * shared link. Omit it and the strip is a `<SegmentedFilter>` the caller owns.
+         */
+        href?: (value: T) => string;
+        /** Filter mode only. Ignored when `href` is set. */
+        onValueChange?: (value: T) => void;
+        ariaLabel: string;
+        class?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends string> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends string>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<T extends string> = InstanceType<typeof $$Component<T>>;
+export default $$Component;

package/src/charts/dashboard/rating-chip.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    grade: string;
+    /** What the letter hides: the score and what it was charged for. */
+    hint?: string;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/charts/dashboard/stat-band.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from "svelte";
+interface Props {
+    /** `<StatTile>` children. Four to a row on a desk, two on a phone. */
+    children: Snippet;
+    /**
+     * Cards per row at the widest breakpoint, four unless the set is smaller.
+     * Five and six are only for a fixed scorecard. The headline stays one row.
+     */
+    columns?: 2 | 3 | 4 | 5 | 6;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/charts/dashboard/stat-tile.svelte

@@ -123,7 +123,7 @@
 	)}
 >
 	{#snippet tileIcon()}
-		{#if Icon}<Icon size={14} class="shrink-0" />{/if}
+		{#if Icon}<Icon aria-hidden="true" size={14} class="shrink-0" />{/if}
 	{/snippet}
 
 	<NumberChart
@@ -174,9 +174,13 @@
 <!-- STYLE -->
 <!-- =========================== -->
 <style>
-	/* WHY scoped here: `NumberChart` has no
-	   series, so the sparkline's bottom room is added on the tile that draws it. */
-	.hr-stat-tile[data-series] :global(.hr-number-chart) {
-		padding-bottom: 4.25rem;
+	@layer theme, base, components, utilities;
+
+	@layer components {
+		/* WHY scoped here: `NumberChart` has no
+		   series, so the sparkline's bottom room is added on the tile that draws it. */
+		.hr-stat-tile[data-series] :global(.hr-number-chart) {
+			padding-bottom: 4.25rem;
+		}
 	}
 </style>

package/src/charts/dashboard/stat-tile.svelte.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Which way a metric has to move to be good news. `neutral` fits a figure like
+ * spend, which isn't a win or a loss until the return sits beside it.
+ */
+export type StatDirection = "up-good" | "down-good" | "neutral";
+import type { Snippet } from "svelte";
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+interface Props {
+    label: string;
+    /** Already formatted. The tile never guesses a currency or a locale. */
+    value: string;
+    /**
+     * Percent change against the previous period. `null` means nothing to
+     * compare yet and draws a dash. Omit it when the figure has no period at all.
+     */
+    deltaPct?: number | null;
+    direction?: StatDirection;
+    /** The one figure the screen was opened to read. Set it on exactly one tile. */
+    lead?: boolean;
+    /** A quiet line under the value: what it was measured over, or why it is a dash. */
+    hint?: string;
+    /**
+     * 0 to 1, drawn as a track under the value: share of a total or progress to
+     * a target. Omit it for a cash balance.
+     */
+    share?: number;
+    /** What `share` is measured against, e.g. "of revenue". Only with `share`. */
+    shareLabel?: string;
+    /** Track colour. The first series token unless a tile means something else. */
+    color?: string;
+    /**
+     * A shape behind the figure, oldest first, bled along the card's bottom.
+     * The treatment every tile gives a number with a history. Omit when there
+     * is none.
+     */
+    series?: number[];
+    /** Leading mark before the label. */
+    icon?: PhosphorIcon;
+    /**
+     * Makes the tile a link, like a balance that opens the bank. It lives here so
+     * a linked figure isn't drawn as a second, different card style.
+     */
+    href?: string;
+    /** What the link opens, shown on hover. Only with `href`. */
+    hrefLabel?: string;
+    /**
+     * `_blank` for a figure that leaves the app (a bank, a provider console),
+     * `_self` for one that is another page of this app. Only with `href`.
+     */
+    target?: "_self" | "_blank";
+    /**
+     * A chip at the end of the label row: the limit the figure is judged against,
+     * the state it is in. Wins over `hrefLabel`, which is only a hover hint.
+     */
+    badge?: Snippet;
+    /** A loss or an overrun: the figure turns the destructive colour. */
+    negative?: boolean;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/charts/donut-chart.css

@@ -1,56 +1,62 @@
+@layer theme, base, components, utilities;
+
 /* Styles for DonutChart. Plain stylesheet (see area-chart.css for why).
    Selectors are namespaced under `.hr-donut-chart`. */
 
-.hr-donut-chart {
-  width: 100%;
-  display: flex;
-  justify-content: center;
-}
-
-.hr-donut-chart .empty {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 100%;
-  border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
-  border-radius: 0.5rem;
-}
-.hr-donut-chart .empty p {
-  font-size: 0.8125rem;
-  color: var(--chart-label, oklch(0.5 0.01 286));
-  margin: 0;
-}
+@layer components {
+  .hr-donut-chart {
+    width: 100%;
+    display: flex;
+    justify-content: center;
+  }
 
-/* The slice slides out a little slower than it slides back: a close is always the quicker. */
-.hr-donut-chart .hr-donut-arc {
-  cursor: pointer;
-  transition:
-    opacity var(--chart-motion-fast, 150ms) ease,
-    translate var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out);
-}
-.hr-donut-chart .hr-donut-arc[data-hovered] {
-  transition:
-    opacity var(--chart-motion-fast, 150ms) ease,
-    translate var(--duration-fast, 250ms) var(--ease-smooth-out);
-}
+  .hr-donut-chart .empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
+    border-radius: 0.5rem;
+  }
 
-.hr-donut-chart .hr-donut-center-value {
-  fill: var(--foreground, oklch(0.18 0.02 240));
-  font-size: 16px;
-  font-weight: 600;
-  font-feature-settings: "tnum";
-  transition: opacity 180ms ease;
-}
+  .hr-donut-chart .empty p {
+    font-size: 0.8125rem;
+    color: var(--chart-label, oklch(0.5 0.01 286));
+    margin: 0;
+  }
 
-.hr-donut-chart .hr-donut-center-label {
-  fill: var(--chart-label, oklch(0.5 0.01 286));
-  font-size: 11px;
-  transition: opacity 180ms ease;
-}
+  /* The slice slides out a little slower than it slides back: a close is always the quicker. */
+  .hr-donut-chart .hr-donut-arc {
+    cursor: pointer;
+    transition:
+      opacity var(--chart-motion-fast, 150ms) ease,
+      translate var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out);
+  }
 
-@media (prefers-reduced-motion: reduce) {
-  .hr-donut-chart .hr-donut-arc,
   .hr-donut-chart .hr-donut-arc[data-hovered] {
-    transition: opacity 120ms ease;
+    transition:
+      opacity var(--chart-motion-fast, 150ms) ease,
+      translate var(--duration-fast, 250ms) var(--ease-smooth-out);
+  }
+
+  .hr-donut-chart .hr-donut-center-value {
+    fill: var(--foreground, oklch(0.18 0.02 240));
+    font-size: 16px;
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    transition: opacity 180ms ease;
+  }
+
+  .hr-donut-chart .hr-donut-center-label {
+    fill: var(--chart-label, oklch(0.5 0.01 286));
+    font-size: 11px;
+    transition: opacity 180ms ease;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .hr-donut-chart .hr-donut-arc,
+    .hr-donut-chart .hr-donut-arc[data-hovered] {
+      transition: opacity 120ms ease;
+    }
   }
 }

package/src/charts/donut-chart.svelte.d.ts

@@ -0,0 +1,39 @@
+import "./chart-tokens.css";
+import "./donut-chart.css";
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: {
+        data: TData[];
+        valueKey: keyof TData & string;
+        labelKey: keyof TData & string;
+        colorKey?: keyof TData & string;
+        height?: number;
+        innerRadius?: number;
+        outerRadius?: number;
+        /** Center label shown when nothing is hovered */
+        centerLabel?: string;
+        /** Format the center value */
+        formatValue?: (v: number) => string;
+        class?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData extends Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData extends Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<TData extends Record<string, unknown>> = InstanceType<typeof $$Component<TData>>;
+export default $$Component;

package/src/charts/dual-axis.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vite-plus/test";
+import { dualAxis, niceStep } from "./dual-axis.js";
+
+describe("niceStep", () => {
+  it("rounds up to 1, 2, 2.5 or 5 times a power of ten", () => {
+    expect(niceStep(40)).toBe(50);
+    expect(niceStep(1500)).toBe(2000);
+    expect(niceStep(2100)).toBe(2500);
+    expect(niceStep(0.3)).toBeCloseTo(0.5);
+    expect(niceStep(0)).toBe(1);
+  });
+});
+
+describe("dualAxis", () => {
+  it("gives clicks and impressions the same number of grid lines", () => {
+    const { left, right } = dualAxis(160, 6000);
+    expect(left).toEqual({ max: 200, ticks: [0, 50, 100, 150, 200] });
+    expect(right).toEqual({ max: 8000, ticks: [0, 2000, 4000, 6000, 8000] });
+  });
+
+  it("keeps every point inside both domains", () => {
+    for (const [l, r] of [
+      [7, 9_999],
+      [123_456, 3],
+      [1, 1],
+      [0.42, 87],
+    ]) {
+      const { left, right } = dualAxis(l, r);
+      expect(left.max).toBeGreaterThanOrEqual(l);
+      expect(right.max).toBeGreaterThanOrEqual(r);
+      expect(left.ticks.length).toBe(right.ticks.length);
+    }
+  });
+
+  it("draws one interval for an empty series instead of dividing by zero", () => {
+    const { left, right } = dualAxis(0, 0);
+    expect(left.ticks).toEqual([0, 1]);
+    expect(right.ticks).toEqual([0, 1]);
+  });
+});

package/src/charts/dual-axis.ts

@@ -0,0 +1,43 @@
+/**
+ * Two value axes that share one set of grid lines.
+ *
+ * A right axis with its own nice ticks lands its labels between the left axis's grid lines, so a
+ * reader can't trace either. Both axes here get the same number of intervals: the left picks a nice
+ * step for its data, and the right picks the smallest nice step that fits its data in that many.
+ */
+
+export type AxisScale = { max: number; ticks: number[] };
+
+const NICE = [1, 2, 2.5, 5, 10];
+
+/** The smallest 1, 2, 2.5 or 5 times a power of ten that is at least `raw`. */
+export function niceStep(raw: number): number {
+  if (!(raw > 0) || !Number.isFinite(raw)) return 1;
+  const power = 10 ** Math.floor(Math.log10(raw));
+  // WHY the epsilon: 0.3 / 0.1 is 2.9999999999999996, which would skip 3 x 0.1 for the next step.
+  const multiple = NICE.find((m) => m * power >= raw * (1 - 1e-9)) ?? 10;
+  return multiple * power;
+}
+
+function ticksOf(step: number, count: number): number[] {
+  // Rounded so 0.1 x 3 reads 0.3 on the axis, not 0.30000000000000004.
+  return Array.from({ length: count + 1 }, (_, i) => Number((i * step).toPrecision(12)));
+}
+
+/**
+ * Left and right domains from 0, with the same tick count so both axes sit on one grid.
+ * `target` is the number of intervals wanted; the left data may round it to one more or less.
+ */
+export function dualAxis(
+  leftMax: number,
+  rightMax: number,
+  target = 4,
+): { left: AxisScale; right: AxisScale } {
+  const leftStep = niceStep(Math.max(0, leftMax) / target);
+  const count = Math.max(1, Math.ceil(Math.max(0, leftMax) / leftStep - 1e-9));
+  const rightStep = niceStep(Math.max(0, rightMax) / count);
+  return {
+    left: { max: leftStep * count, ticks: ticksOf(leftStep, count) },
+    right: { max: rightStep * count, ticks: ticksOf(rightStep, count) },
+  };
+}

package/src/charts/edge-fade.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    /** Mask id. Apply it to the shape with `mask="url(#id)"`. */
+    id: string;
+    /** Fraction of the shape's width faded at each side, 0-0.45. */
+    amount?: number;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;