@torpor/ui 0.4.0 → 1.0.0

package/dist/Charts/index.d.ts

@@ -5,23 +5,41 @@ interface BarChartProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	series: DataSeries[],
-	height?: number,
-	width?: number,
-	xLabel?: string,
-	yLabel?: string,
-	maxValue?: number,
-	stepCount?: number,
-	stepValue?: number,
-	hideXAxis?: boolean,
-	hideYAxis?: boolean,
-	showHLines?: boolean,
-	showVLines?: boolean,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	series: DataSeries[];
+	height?: number;
+	width?: number;
+	xLabel?: string;
+	yLabel?: string;
+	maxValue?: number;
+	stepCount?: number;
+	stepValue?: number;
+	showHLines?: boolean;
+	showVLines?: boolean;
 }
 
+/**
+ * A bar chart: one thick horizontal bar per series, drawn from the left
+ * edge towards its first value, with category labels down the side and the
+ * value scale along the bottom.
+ *
+ * This is a preset over the layered chart components:
+ *
+ * ```
+ * <Chart>
+ * 	<ChartYAxis />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartBars />
+ * </Chart>
+ * ```
+ *
+ * For a vertical column per value, use ColumnChart instead.
+ */
 declare function BarChart(
 	$parent: ParentNode,
 	$anchor: Node | null,
@@ -32,15 +50,222 @@ declare function BarChart(
 
 
 
+interface ChartProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	/** The series that layers draw from (layers reference them by index) */
+	series: DataSeries[];
+	/** Fixed height in pixels (default 200) */
+	height?: number;
+	/** Fixed width in pixels (default: fills the container, minimum 400) */
+	width?: number;
+	/** Label under the x axis */
+	xLabel?: string;
+	/** Label beside the y axis */
+	yLabel?: string;
+	/** The value at the top of the value axis, instead of the series' maximum */
+	maxValue?: number;
+	/** The number of steps between 0 and the maximum value (default 2) */
+	stepCount?: number;
+	/** The size of each step, instead of being calculated */
+	stepValue?: number;
+}
+
+/**
+ * A container for layered chart components. It measures its text, works out
+ * the plot geometry and provides it to whatever axes, grid lines and marks
+ * are slotted inside:
+ *
+ * ```
+ * <Chart ariaLabel="Revenue" series={revenue}>
+ * 	<ChartYAxis side="right" />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartColumns />
+ * 	<ChartLines seriesIndex={1} showPoints />
+ * </Chart>
+ * ```
+ *
+ * Layers can be mixed freely -- columns with a line overlaid, an axis on
+ * either side, only a y axis with no x axis -- so a preset like LineChart is
+ * just one such combination.
+ *
+ * See also the ready-made presets: BarChart, ColumnChart, LineChart,
+ * ScatterChart.
+ */
+declare function Chart(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ChartProps | undefined,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * Horizontal bar marks for a Chart: one thick horizontal bar per series,
+ * drawn from the left edge of the plot towards its value.
+ *
+ * For a column per value grouped under each label, use ChartColumns --
+ * those run vertically.
+ */
+declare function ChartBars(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ChartBarsProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * Vertical column marks for a Chart: every value in the chosen series is
+ * drawn as a vertical column, grouped under its label.
+ *
+ * For one thick bar per series, use ChartBars -- those run horizontally.
+ */
+declare function ChartColumns(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ChartColumnsProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * Grid lines for a Chart: horizontal lines at each value step and/or
+ * vertical lines through each category slot.
+ */
+declare function ChartGrid(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ChartGridProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * Line marks for a Chart: draws the chosen series as a connected line
+ * across the category slots.
+ *
+ * Add alongside ChartColumns or ChartBars for overlaid layers -- or use two
+ * ChartLines with different `seriesIndex` to compare series.
+ */
+declare function ChartLines(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ChartLinesProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * The x axis for a chart. For vertical marks (columns, lines) it runs along
+ * the bottom with each series' label centered under its slot; for
+ * horizontal marks (bars) it becomes the value scale, with a tick for each
+ * step along the bottom.
+ */
+declare function ChartXAxis(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ChartXAxisProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+/**
+ * The y axis for a chart. For vertical marks (columns, lines) it is the
+ * value scale -- a line down the `side` edge with a tick for each step
+ * between 0 and the maximum value. For horizontal marks (bars) it carries
+ * the category labels, one per band down the left.
+ *
+ * Drawing it on either side does not change the plot geometry; overlaying
+ * an axis is purely presentational.
+ */
+declare function ChartYAxis(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props?: ChartYAxisProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
+interface ColumnChartProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	series: DataSeries[];
+	height?: number;
+	width?: number;
+	xLabel?: string;
+	yLabel?: string;
+	maxValue?: number;
+	stepCount?: number;
+	stepValue?: number;
+	showHLines?: boolean;
+	showVLines?: boolean;
+}
+
+/**
+ * A column chart: each value in each series is drawn as a vertical column,
+ * grouped under the series' label along the bottom axis.
+ *
+ * This is a preset over the layered chart components:
+ *
+ * ```
+ * <Chart>
+ * 	<ChartValueAxis />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartColumns />
+ * </Chart>
+ * ```
+ *
+ * Compose those directly to customize -- e.g. the value axis on the right,
+ * or a line overlaid with ChartLines.
+ */
+declare function ColumnChart(
+	$parent: ParentNode,
+	$anchor: Node | null,
+	$props: ColumnChartProps,
+	$context?: Record<PropertyKey, any>,
+	$slots?: Record<string, SlotRender>,
+): void;
+
+
+
 interface GridLinesProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	showHLines?: boolean,
-	showVLines?: boolean,
+	style?: StyleValue;
+	showHLines?: boolean;
+	showVLines?: boolean;
 	width: number;
 	labels: string[];
 	xStepValue: number;
@@ -68,24 +293,42 @@ interface LineChartProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	series: DataSeries[],
-	height?: number,
-	width?: number,
-	xLabel?: string,
-	yLabel?: string,
-	maxValue?: number,
-	stepCount?: number,
-	stepValue?: number,
-	showPoints?: boolean,
-	hideXAxis?: boolean,
-	hideYAxis?: boolean,
-	showHLines?: boolean,
-	showVLines?: boolean,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	series: DataSeries[];
+	height?: number;
+	width?: number;
+	xLabel?: string;
+	yLabel?: string;
+	maxValue?: number;
+	stepCount?: number;
+	stepValue?: number;
+	showPoints?: boolean;
+	showHLines?: boolean;
+	showVLines?: boolean;
 }
 
+/**
+ * A line chart: each series drawn as a connected line across the category
+ * slots.
+ *
+ * This is a preset over the layered chart components:
+ *
+ * ```
+ * <Chart>
+ * 	<ChartValueAxis />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartLines seriesIndex={0} />
+ * </Chart>
+ * ```
+ *
+ * Compose those directly for overlaid layers (columns plus a line, multiple
+ * separately-indexed lines etc).
+ */
 declare function LineChart(
 	$parent: ParentNode,
 	$anchor: Node | null,
@@ -100,13 +343,15 @@ interface PieChartProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	data: PieData[],
-	size?: number,
-	radius?: number,
-	cutout?: number,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	data: PieData[];
+	size?: number;
+	radius?: number;
+	cutout?: number;
 }
 
 declare function PieChart(
@@ -123,22 +368,24 @@ interface ScatterChartProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	series: DataSeries[],
-	height?: number,
-	width?: number,
-	xLabel?: string,
-	yLabel?: string,
-	xStepCount?: number,
-	xStepValue?: number,
-	yStepCount?: number,
-	yStepValue?: number,
-	hideXAxis?: boolean,
-	hideYAxis?: boolean,
-	showHLines?: boolean,
-	showVLines?: boolean,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	series: DataSeries[];
+	height?: number;
+	width?: number;
+	xLabel?: string;
+	yLabel?: string;
+	xStepCount?: number;
+	xStepValue?: number;
+	yStepCount?: number;
+	yStepValue?: number;
+	hideXAxis?: boolean;
+	hideYAxis?: boolean;
+	showHLines?: boolean;
+	showVLines?: boolean;
 }
 
 declare function ScatterChart(
@@ -155,13 +402,15 @@ interface SparkLineProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
 	data: number[];
-	color?: string,
-	height?: number,
-	width?: number,
+	color?: string;
+	height?: number;
+	width?: number;
 }
 
 declare function SparkLine(
@@ -175,17 +424,17 @@ declare function SparkLine(
 
 
 interface XAxisProps {
-	showAxis: boolean,
-	height: number,
-	width: number,
-	itemWidth: number,
-	textHeight: number,
-	xLabel: string,
-	labels: string[] ,
-	stepLabels:number[] ,
-	stepValue: number,
-	chartLeft: number,
-	chartBottom: number,
+	showAxis: boolean;
+	height: number;
+	width: number;
+	itemWidth: number;
+	textHeight: number;
+	xLabel: string;
+	labels: string[];
+	stepLabels: number[];
+	stepValue: number;
+	chartLeft: number;
+	chartBottom: number;
 }
 
 declare function XAxis(
@@ -199,14 +448,14 @@ declare function XAxis(
 
 
 interface YAxisProps {
-	showAxis: boolean,
-	valueHeight: number,
-	textHeight: number,
-	yLabel: string,
-	stepLabels: number[],
-	stepValue: number,
-	chartLeft: number,
-	chartBottom: number,
+	showAxis: boolean;
+	valueHeight: number;
+	textHeight: number;
+	yLabel: string;
+	stepLabels: number[];
+	stepValue: number;
+	chartLeft: number;
+	chartBottom: number;
 }
 
 declare function YAxis(
@@ -217,4 +466,4 @@ declare function YAxis(
 	$slots?: Record<string, SlotRender>,
 ): void;
 
-export { BarChart, GridLines, LineChart, PieChart, ScatterChart, SparkLine, XAxis, YAxis };
+export { BarChart, Chart, ChartBars, ChartColumns, ChartGrid, ChartLines, ChartXAxis, ChartYAxis, ColumnChart, GridLines, LineChart, PieChart, ScatterChart, SparkLine, XAxis, YAxis };

package/dist/Charts/index.js

@@ -1,34 +1,17 @@
-// src/Charts/BarChart.torp
-import BarChart_default from "./BarChart.torp";
-
-// src/Charts/GridLines.torp
-import GridLines_default from "./GridLines.torp";
-
-// src/Charts/LineChart.torp
-import LineChart_default from "./LineChart.torp";
-
-// src/Charts/PieChart.torp
-import PieChart_default from "./PieChart.torp";
-
-// src/Charts/ScatterChart.torp
-import ScatterChart_default from "./ScatterChart.torp";
-
-// src/Charts/SparkLine.torp
-import SparkLine_default from "./SparkLine.torp";
-
-// src/Charts/XAxis.torp
-import XAxis_default from "./XAxis.torp";
-
-// src/Charts/YAxis.torp
-import YAxis_default from "./YAxis.torp";
-export {
-  BarChart_default as BarChart,
-  GridLines_default as GridLines,
-  LineChart_default as LineChart,
-  PieChart_default as PieChart,
-  ScatterChart_default as ScatterChart,
-  SparkLine_default as SparkLine,
-  XAxis_default as XAxis,
-  YAxis_default as YAxis
-};
-//# sourceMappingURL=index.js.map
+import BarChart from "./BarChart.torp";
+import Chart from "./Chart.torp";
+import ChartBars from "./ChartBars.torp";
+import ChartColumns from "./ChartColumns.torp";
+import ChartGrid from "./ChartGrid.torp";
+import ChartLines from "./ChartLines.torp";
+import ChartXAxis from "./ChartXAxis.torp";
+import ChartYAxis from "./ChartYAxis.torp";
+import ColumnChart from "./ColumnChart.torp";
+import GridLines from "./GridLines.torp";
+import LineChart from "./LineChart.torp";
+import PieChart from "./PieChart.torp";
+import ScatterChart from "./ScatterChart.torp";
+import SparkLine from "./SparkLine.torp";
+import XAxis from "./XAxis.torp";
+import YAxis from "./YAxis.torp";
+export { BarChart, Chart, ChartBars, ChartColumns, ChartGrid, ChartLines, ChartXAxis, ChartYAxis, ColumnChart, GridLines, LineChart, PieChart, ScatterChart, SparkLine, XAxis, YAxis };

package/dist/ColorPicker/ColorPalette.torp

@@ -0,0 +1,154 @@
+import type { Bindable, ClassValue, StyleValue } from "@torpor/view";
+import {
+	type FieldContext,
+	FieldContextName,
+	type FormContext,
+	FormContextName,
+} from "../Form/FormTypes";
+import FormValues from "../Form/FormValues.torp";
+import { createFocusGroup, type FocusItemState } from "../utils/focusGroup";
+import { defaultPalette, parseHex } from "../utils/colorUtils";
+import createFormField from "../utils/formField";
+
+interface ColorPaletteProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The selected color as "#rrggbb"; undefined if nothing is selected */
+	value?: Bindable<string | undefined>;
+	/** The colors to offer (default: a built-in gray + hue palette) */
+	colors?: string[];
+	/** If set to true, the user cannot interact with this palette */
+	disabled?: boolean;
+	/** An accessible name for the palette */
+	ariaLabel?: string;
+	/** The name of the component's form data field */
+	name?: string;
+	/** Raised when a color has been selected or deselected */
+	onchange?: (value: string | undefined) => void;
+}
+
+/**
+ * A grid of color swatches that behaves like a radio group: one swatch can
+ * be selected, clicking it again deselects, and the arrow keys move through
+ * the swatches selecting as they go.
+ *
+ * Use ColorPicker instead when arbitrary hex values should be enterable
+ * alongside the palette.
+ */
+export default function ColorPalette($props: ColorPaletteProps | undefined) {
+	let root: HTMLElement;
+
+	// Wire up the enclosing Form and Field, if any
+	const form = createFormField(
+		$props?.name,
+		$context[FormContextName] as FormContext | undefined,
+		$context[FieldContextName] as FieldContext | undefined,
+	);
+
+	function getDisabled(): boolean {
+		return $props?.disabled === true;
+	}
+
+	function getColors(): string[] {
+		return $props?.colors ?? defaultPalette;
+	}
+
+	let $state = $watch({
+		value: undefined as string | undefined,
+	});
+
+	$bind($state, $props, "value");
+
+	const group = createFocusGroup<FocusItemState>();
+
+	function normalized(color: string | undefined | null): string {
+		return parseHex(color) ?? "";
+	}
+
+	function isSelected(color: string): boolean {
+		return $state.value !== undefined && normalized($state.value) === normalized(color);
+	}
+
+	function select(color: string) {
+		if (getDisabled()) return;
+		const next = normalized(color);
+		// Selecting the current swatch clears it, like Rating's allowClear
+		$state.value = isSelected(color) ? undefined : next || undefined;
+		form.handleInput();
+		$props?.onchange?.($state.value);
+	}
+
+	function handleKey(index: number, e: KeyboardEvent) {
+		if (getDisabled()) return;
+		switch (e.key) {
+			case "Enter":
+			case " ": {
+				e.preventDefault();
+				select(getColors()[index]);
+				break;
+			}
+			default: {
+				const before = group.getFocusIndex();
+				group.handleGroupKey(index, e);
+				const after = group.getFocusIndex();
+				if (after !== before && after >= 0) {
+					group.handleItemFocus(after);
+					select(getColors()[after]);
+				}
+				break;
+			}
+		}
+	}
+
+	// Only blur when focus leaves the whole palette
+	function handleFocusOut(e: FocusEvent) {
+		if (!root.contains(e.relatedTarget as Node | null)) {
+			form.handleBlur();
+		}
+	}
+
+	@render {
+		<div
+			{$props?.id}
+			class={["torp-color-palette", $props?.class]}
+			{$props?.style}
+			role="radiogroup"
+			aria-label={$props?.ariaLabel}
+			aria-disabled={getDisabled() ? "true" : undefined}
+			data-valid={form.valid ? "valid" : "invalid"}
+			aria-describedby={form.messageId}
+			onfocusout={handleFocusOut}
+			&ref={root}
+		>
+			@for (let [i, color] of getColors().entries()) {
+				@key = color
+				<button
+					type="button"
+					class="torp-color-palette-swatch"
+					role="radio"
+					tabindex={group.isTabStop(i) ? 0 : -1}
+					aria-checked={isSelected(color) ? "true" : "false"}
+					aria-label={normalized(color)}
+					aria-disabled={getDisabled() ? "true" : undefined}
+					data-color={color}
+					data-selected={isSelected(color) ? "selected" : undefined}
+					disabled={getDisabled()}
+					style={`background-color:${color}`}
+					onclick={() => select(color)}
+					onkeydown={(e: KeyboardEvent) => handleKey(i, e)}
+					onmount={(el: HTMLElement) => {
+						const item: FocusItemState = { setFocused: () => el.focus() };
+						group.registerItem(item);
+						return () => group.removeItem(item.index!);
+					}}
+				/>
+			}
+		</div>
+
+		<FormValues name={form.name} value={$state.value} />
+	}
+}