@stll/workspace-ui 0.0.1-placeholder.0 → 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @stll/workspace-ui
+
+Reusable React presentation modules for Stella workspaces: field values,
+property icons, sorting chips, condition builders, table loading rows, and
+column calculations.
+
+The package owns view-level rendering contracts while the surrounding workspace
+supplies its data, labels, and locale. The condition builder resolves no
+strings itself; labels and field options arrive through its props.
+
+## Imports
+
+Use the explicit subpaths for focused modules:
+
+```tsx
+import { ConditionBuilder } from "@stll/workspace-ui/conditions";
+import { FieldValue } from "@stll/workspace-ui/field-value";
+import { SortChips } from "@stll/workspace-ui/sorts";
+```
+
+The package also exposes a root entry for code that uses several workspace
+surfaces together. The subpaths remain the clearest way to declare a module's
+boundary.
+
+## Development
+
+```sh
+bun run build       # tsdown, one output module per source module
+bun run test        # bun test src
+bun run typecheck
+bun run lint
+```
+
+Peer dependencies: `react`, `react-dom`, `@base-ui/react`, TanStack React Table,
+and Tailwind CSS v4. The package's components use Tailwind utility classes; the
+host owns the Tailwind entry point and token configuration.
+
+Include both published component packages in that entry point so Tailwind scans
+their shipped class names:
+
+```css
+@import "tailwindcss";
+@import "@stll/ui/theme.css";
+@source "../node_modules/@stll/ui/dist";
+@source "../node_modules/@stll/workspace-ui/dist";
+```
+
+This package is published, so public API changes need a changeset.

package/dist/calculation-format.d.ts

@@ -0,0 +1,54 @@
+import { CalculationResult } from "@stll/calculations";
+import { CentsAmount } from "@stll/money";
+//#region src/calculation-format.d.ts
+type CalculationFormatters = {
+  number: (value: number) => string;
+  money: (amountCents: CentsAmount, currency: string) => string;
+  percent: (ratio: number) => string;
+};
+type CalculationLabels = {
+  /** The reduction's short name, e.g. "Sum". */
+  kind: string;
+  /** Stands in for a value the reduction cannot produce. */
+  unavailable: string;
+};
+type FormattedCalculation = {
+  /** One compact line, for the column header. */
+  summary: string;
+  /**
+   * One line per currency, for the tooltip. Empty when the summary already
+   * says everything: there is nothing to expand for a single unit.
+   */
+  breakdown: readonly string[];
+};
+type FormatCalculationParams = {
+  result: CalculationResult;
+  formatters: CalculationFormatters;
+  labels: CalculationLabels;
+};
+declare const formatCalculationResult: ({ result, formatters, labels }: FormatCalculationParams) => FormattedCalculation;
+/**
+ * How many minor units make a major one, for this currency: 100 for CZK, 1 for
+ * JPY, 1000 for KWD. It is a property of the currency and not of the reader, so
+ * the lookup is deliberately locale-independent.
+ *
+ * A malformed code makes the `Intl.NumberFormat` constructor throw, before any
+ * `?? 2` on its result could help, so the fallback has to wrap the call.
+ */
+declare const currencyMinorUnitDigits: (currency: string) => number;
+type FormatMoneyCentsParams = {
+  amountCents: number;
+  currency: string;
+  locale: string;
+};
+/**
+ * Money is stored in minor units, and how many of them make a major one is a
+ * property of the currency. Ask the currency rather than assuming a hundred.
+ *
+ * A code `Intl` rejects falls back to the amount beside the raw code: a column
+ * showing "1500 A1C" is wrong-looking data, which is the truth, where a thrown
+ * RangeError would take the whole board down with it.
+ */
+declare const formatMoneyCents: ({ amountCents, currency, locale }: FormatMoneyCentsParams) => string;
+//#endregion
+export { CalculationFormatters, CalculationLabels, FormatCalculationParams, FormatMoneyCentsParams, FormattedCalculation, currencyMinorUnitDigits, formatCalculationResult, formatMoneyCents };

package/dist/calculation-format.js

@@ -0,0 +1,72 @@
+import { Result } from "better-result";
+//#region src/calculation-format.ts
+/**
+* Turning a calculation result into the two strings a view shows: the compact
+* line in the header, and the breakdown behind it.
+*
+* Formatting is separate from reducing because the reduction is the same
+* everywhere and the formatting is not: it needs the reader's locale, and a
+* monetary reduction has one line per currency to lay out.
+*/
+const formatCalculationResult = ({ result, formatters, labels }) => {
+	switch (result.type) {
+		case "count":
+		case "number": return line(labels.kind, formatters.number(result.value));
+		case "ratio": return line(labels.kind, formatters.percent(result.value));
+		case "money": {
+			const amounts = result.totals.map((total) => formatters.money(total.amountCents, total.currency));
+			if (amounts.length === 0) return line(labels.kind, labels.unavailable);
+			return {
+				summary: `${labels.kind} ${amounts.join(SEPARATOR)}`,
+				breakdown: amounts.length > 1 ? amounts : []
+			};
+		}
+		case "unsupported": return line(labels.kind, labels.unavailable);
+		default: return result;
+	}
+};
+/**
+* Two, the ISO 4217 default, used when a stored code is one `Intl` will not
+* accept. Validation at the API boundary keeps those out, but a row written
+* before that constraint existed must still render rather than throw.
+*/
+const DEFAULT_MINOR_UNIT_DIGITS = 2;
+/**
+* How many minor units make a major one, for this currency: 100 for CZK, 1 for
+* JPY, 1000 for KWD. It is a property of the currency and not of the reader, so
+* the lookup is deliberately locale-independent.
+*
+* A malformed code makes the `Intl.NumberFormat` constructor throw, before any
+* `?? 2` on its result could help, so the fallback has to wrap the call.
+*/
+const currencyMinorUnitDigits = (currency) => {
+	const resolved = Result.try(() => new Intl.NumberFormat("en", {
+		style: "currency",
+		currency
+	}).resolvedOptions().maximumFractionDigits);
+	if (resolved.isErr()) return DEFAULT_MINOR_UNIT_DIGITS;
+	return resolved.value ?? DEFAULT_MINOR_UNIT_DIGITS;
+};
+/**
+* Money is stored in minor units, and how many of them make a major one is a
+* property of the currency. Ask the currency rather than assuming a hundred.
+*
+* A code `Intl` rejects falls back to the amount beside the raw code: a column
+* showing "1500 A1C" is wrong-looking data, which is the truth, where a thrown
+* RangeError would take the whole board down with it.
+*/
+const formatMoneyCents = ({ amountCents, currency, locale }) => {
+	const major = amountCents / 10 ** currencyMinorUnitDigits(currency);
+	const formatted = Result.try(() => new Intl.NumberFormat(locale, {
+		style: "currency",
+		currency
+	}).format(major));
+	return formatted.isErr() ? `${major} ${currency}` : formatted.value;
+};
+const SEPARATOR = " · ";
+const line = (kind, value) => ({
+	summary: `${kind} ${value}`,
+	breakdown: []
+});
+//#endregion
+export { currencyMinorUnitDigits, formatCalculationResult, formatMoneyCents };

package/dist/calculation-selection.d.ts

@@ -0,0 +1,15 @@
+import { CalculationKind } from "@stll/calculations";
+//#region src/calculation-selection.d.ts
+type CalculationSelection = {
+  propertyId: string;
+  kind: CalculationKind;
+};
+type ApplyCalculationSelectionParams = {
+  selections: readonly CalculationSelection[];
+  propertyId: string;
+  /** The reduction to show, or null to stop showing one. */
+  kind: CalculationKind | null;
+};
+declare const applyCalculationSelection: ({ selections, propertyId, kind }: ApplyCalculationSelectionParams) => CalculationSelection[];
+//#endregion
+export { ApplyCalculationSelectionParams, CalculationSelection, applyCalculationSelection };

package/dist/calculation-selection.js

@@ -0,0 +1,14 @@
+//#region src/calculation-selection.ts
+const applyCalculationSelection = ({ selections, propertyId, kind }) => {
+	if (kind === null) return selections.filter((selection) => selection.propertyId !== propertyId);
+	if (selections.some((selection) => selection.propertyId === propertyId)) return selections.map((selection) => selection.propertyId === propertyId ? {
+		propertyId,
+		kind
+	} : selection);
+	return [...selections, {
+		propertyId,
+		kind
+	}];
+};
+//#endregion
+export { applyCalculationSelection };

package/dist/calculations.d.ts

@@ -0,0 +1,67 @@
+import { FormattedCalculation } from "./calculation-format.js";
+import { CalculationSelection } from "./calculation-selection.js";
+import { CalculationKind, CalculationResult, CalculationValue } from "@stll/calculations";
+import { ReactNode } from "react";
+//#region src/calculations.d.ts
+/** A property a view can calculate over, with the reductions its values allow. */
+type CalculationProperty = {
+  id: string;
+  name: string;
+  kinds: readonly CalculationKind[];
+};
+type WorkspaceCalculationLabels = {
+  choose: string;
+  kinds: Record<CalculationKind, string>;
+  noProperties: string;
+  none: string;
+  unavailable: string;
+};
+type CalculationPickerProps = {
+  labels: WorkspaceCalculationLabels;
+  properties: readonly CalculationProperty[];
+  selections: readonly CalculationSelection[];
+  onChange: (selections: CalculationSelection[]) => void;
+  /** Trigger content. Defaults to the calculation glyph. */
+  children?: ReactNode;
+};
+/**
+ * Choose what a view calculates: a property, then a reduction. Every step is a
+ * menu item, so the whole choice is reachable from the keyboard.
+ */
+declare const CalculationPicker: ({ labels, properties, selections, onChange, children }: CalculationPickerProps) => import("react").JSX.Element;
+type CalculationKindPickerProps = {
+  labels: WorkspaceCalculationLabels;
+  /** Reductions this column's values allow. */
+  kinds: readonly CalculationKind[];
+  /** The reduction currently shown, or null for none. */
+  value: CalculationKind | null;
+  onChange: (kind: CalculationKind | null) => void;
+  /** Trigger content. Defaults to the calculation glyph. */
+  children?: ReactNode;
+};
+/**
+ * Choose one column's reduction. The board picks a property first (it shows one
+ * line for the whole board); a table column already is the property.
+ */
+declare const CalculationKindPicker: ({ labels, kinds, value, onChange, children }: CalculationKindPickerProps) => import("react").JSX.Element;
+type CalculationSummaryProps = {
+  calculation: FormattedCalculation;
+};
+/**
+ * The calculation as one compact line. When it reduces to several currencies
+ * the line stays short and the full set sits behind a tooltip.
+ */
+declare const CalculationSummary: ({ calculation }: CalculationSummaryProps) => import("react").JSX.Element;
+type UseCalculationParams = {
+  kind: CalculationKind;
+  labels: WorkspaceCalculationLabels;
+  values: readonly CalculationValue[];
+  /** Every value in the view, for a reduction relative to the whole. */
+  scopeValues?: readonly CalculationValue[] | undefined;
+};
+/** Reduce a column's values and format the answer for the reader's locale. */
+declare const useCalculation: ({ kind, labels, values, scopeValues }: UseCalculationParams) => FormattedCalculation;
+/** One configured calculation, reduced over a column and rendered compactly. */
+declare const ColumnCalculation: (params: UseCalculationParams) => import("react").JSX.Element;
+//#endregion
+export { CalculationKindPicker, CalculationKindPickerProps, CalculationPicker, CalculationPickerProps, CalculationProperty, type CalculationResult, type CalculationSelection, CalculationSummary, CalculationSummaryProps, ColumnCalculation, UseCalculationParams, WorkspaceCalculationLabels, useCalculation };

package/dist/calculations.js

@@ -0,0 +1,108 @@
+import { formatCalculationResult, formatMoneyCents } from "./calculation-format.js";
+import { applyCalculationSelection } from "./calculation-selection.js";
+import { CheckIcon, SigmaIcon } from "lucide-react";
+import { useFormatter, useLocale } from "use-intl";
+import { runCalculation } from "@stll/calculations";
+import { Button } from "@stll/ui/button";
+import { Menu, MenuItem, MenuPopup, MenuSub, MenuSubPopup, MenuSubTrigger, MenuTrigger } from "@stll/ui/menu";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "@stll/ui/tooltip";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/calculations.tsx
+/**
+* Choose what a view calculates: a property, then a reduction. Every step is a
+* menu item, so the whole choice is reachable from the keyboard.
+*/
+const CalculationPicker = ({ labels, properties, selections, onChange, children }) => {
+	const select = (propertyId, kind) => {
+		onChange(applyCalculationSelection({
+			selections,
+			propertyId,
+			kind
+		}));
+	};
+	return /* @__PURE__ */ jsxs(Menu, { children: [/* @__PURE__ */ jsx(MenuTrigger, {
+		"aria-label": labels.choose,
+		render: /* @__PURE__ */ jsx(Button, {
+			size: "icon-xs",
+			variant: "ghost"
+		}),
+		children: children ?? /* @__PURE__ */ jsx(SigmaIcon, {})
+	}), /* @__PURE__ */ jsxs(MenuPopup, { children: [properties.length === 0 && /* @__PURE__ */ jsx(MenuItem, {
+		disabled: true,
+		children: labels.noProperties
+	}), properties.map((property) => {
+		const selected = selections.find((selection) => selection.propertyId === property.id);
+		return /* @__PURE__ */ jsxs(MenuSub, { children: [/* @__PURE__ */ jsx(MenuSubTrigger, { children: property.name }), /* @__PURE__ */ jsxs(MenuSubPopup, { children: [/* @__PURE__ */ jsxs(MenuItem, {
+			onClick: () => select(property.id, null),
+			children: [selected === void 0 ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx("span", {}), labels.none]
+		}), property.kinds.map((kind) => /* @__PURE__ */ jsxs(MenuItem, {
+			onClick: () => select(property.id, kind),
+			children: [selected?.kind === kind ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx("span", {}), labels.kinds[kind]]
+		}, kind))] })] }, property.id);
+	})] })] });
+};
+/**
+* Choose one column's reduction. The board picks a property first (it shows one
+* line for the whole board); a table column already is the property.
+*/
+const CalculationKindPicker = ({ labels, kinds, value, onChange, children }) => /* @__PURE__ */ jsxs(Menu, { children: [/* @__PURE__ */ jsx(MenuTrigger, {
+	"aria-label": labels.choose,
+	render: /* @__PURE__ */ jsx(Button, {
+		size: "icon-xs",
+		variant: "ghost"
+	}),
+	children: children ?? /* @__PURE__ */ jsx(SigmaIcon, {})
+}), /* @__PURE__ */ jsxs(MenuPopup, { children: [/* @__PURE__ */ jsxs(MenuItem, {
+	onClick: () => onChange(null),
+	children: [value === null ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx("span", {}), labels.none]
+}), kinds.map((kind) => /* @__PURE__ */ jsxs(MenuItem, {
+	onClick: () => onChange(kind),
+	children: [value === kind ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx("span", {}), labels.kinds[kind]]
+}, kind))] })] });
+/**
+* The calculation as one compact line. When it reduces to several currencies
+* the line stays short and the full set sits behind a tooltip.
+*/
+const CalculationSummary = ({ calculation }) => {
+	if (calculation.breakdown.length === 0) return /* @__PURE__ */ jsx("span", {
+		className: "text-muted-foreground shrink-0 text-xs tabular-nums",
+		children: calculation.summary
+	});
+	return /* @__PURE__ */ jsxs(Tooltip, { children: [/* @__PURE__ */ jsx(TooltipTrigger, {
+		render: /* @__PURE__ */ jsx("span", { className: "text-muted-foreground shrink-0 text-xs tabular-nums" }),
+		children: calculation.summary
+	}), /* @__PURE__ */ jsx(TooltipPopup, { children: /* @__PURE__ */ jsx("ul", { children: calculation.breakdown.map((entry) => /* @__PURE__ */ jsx("li", { children: entry }, entry)) }) })] });
+};
+/** Reduce a column's values and format the answer for the reader's locale. */
+const useCalculation = ({ kind, labels, values, scopeValues }) => {
+	const formatters = useCalculationFormatters();
+	return formatCalculationResult({
+		result: runCalculation({
+			kind,
+			values,
+			scopeValues
+		}),
+		formatters,
+		labels: {
+			kind: labels.kinds[kind],
+			unavailable: labels.unavailable
+		}
+	});
+};
+/** One configured calculation, reduced over a column and rendered compactly. */
+const ColumnCalculation = (params) => /* @__PURE__ */ jsx(CalculationSummary, { calculation: useCalculation(params) });
+const useCalculationFormatters = () => {
+	const format = useFormatter();
+	const locale = useLocale();
+	return {
+		number: (value) => format.number(value),
+		money: (amountCents, currency) => formatMoneyCents({
+			amountCents,
+			currency,
+			locale
+		}),
+		percent: (ratio) => format.number(ratio, { style: "percent" })
+	};
+};
+//#endregion
+export { CalculationKindPicker, CalculationPicker, CalculationSummary, ColumnCalculation, useCalculation };

package/dist/colors.d.ts

@@ -0,0 +1,2 @@
+import { ColorVariants, OptionColor, emptyColor, optionColors, resolveOptionColor } from "@stll/ui/option-color";
+export { type ColorVariants, type OptionColor, emptyColor, optionColors, resolveOptionColor };

package/dist/colors.js

@@ -0,0 +1,2 @@
+import { emptyColor, optionColors, resolveOptionColor } from "@stll/ui/option-color";
+export { emptyColor, optionColors, resolveOptionColor };

package/dist/conditions/builder.d.ts

@@ -0,0 +1,98 @@
+import { ConditionOperator, FieldOption, FieldValueType, ValueEditorKind } from "./logic.js";
+import { ReactNode } from "react";
+import { ConditionNode, GroupNode } from "@stll/conditions";
+//#region src/conditions/builder.d.ts
+/**
+ * Every string the builder draws. The module resolves none of them: a host
+ * brings its own catalogue, and an exported module that reached into one would
+ * only work inside the app whose messages it happened to know.
+ */
+type ConditionBuilderLabels = {
+  /** "+ Add condition". */
+  addCondition: string;
+  /** "+ Add group". */
+  addGroup: string;
+  /** Leads the first row: "When". */
+  when: string;
+  /** Accessible name of the and/or select. */
+  match: string;
+  and: string;
+  or: string;
+  /** Removes one row or group. */
+  remove: string;
+  /** Placeholder in the field select. */
+  fieldPlaceholder: string;
+  /** Placeholder in the value editor. */
+  valuePlaceholder: string;
+  /** The "ƒ Calculated value…" item. */
+  useFormula: string;
+  /** The date editor's own three. */
+  clearDate: string;
+  selectDate: string;
+  today: string;
+  /** How an operator reads for a given value type. */
+  operator: (valueType: FieldValueType, op: ConditionOperator) => string;
+};
+/** Capability flags and host injections that let one recursive builder serve
+ *  both the View filter surface and the template rule surface. The host owns
+ *  the field list and (optionally) the value editors; the builder owns the
+ *  tree shape, the gutter, nesting, and the formula escape hatch. */
+type ConditionCapabilities = {
+  /** Operands the picker may target (property / builtin / kind / path). */
+  fields: FieldOption[];
+  /** Allow nested groups (the "+ Add group" affordance + bordered subgroups). */
+  allowNesting?: boolean;
+  /** Offer a "ƒ Calculated value…" item that switches a leaf's left operand to
+   *  a formula edited via `FormulaCell`. */
+  allowFormula?: boolean;
+  /** Numeric operands a formula leaf may reference; required for `allowFormula`. */
+  formulaNumberFields?: readonly {
+    path: string;
+    label: string;
+  }[];
+  /** Host-injected value editor (e.g. faceted selects). Return null to fall back
+   *  to the builder's built-in editor for that kind. */
+  renderValueEditor?: (ctx: ValueEditorRenderCtx) => React.ReactNode | null;
+  /** Draws the formula cell for a formula leaf; required for `allowFormula`. */
+  renderFormulaCell?: (ctx: FormulaCellRenderCtx) => ReactNode;
+  /** Restrict the operator set per value type (e.g. the template surface only
+   *  exposes operators its serializer can render). Defaults to the logic's
+   *  `operatorsFor`. */
+  operatorsFor?: (valueType: FieldValueType) => readonly ConditionOperator[];
+  /** Override how a value type renders its value editor. Defaults to the logic's
+   *  `valueEditorFor`. */
+  valueEditorFor?: (valueType: FieldValueType, op: ConditionOperator) => ValueEditorKind;
+};
+/**
+ * The formula editor is a slot: its expression language belongs to the host,
+ * so the builder hands it the expression and takes back either a new one or a
+ * request to go back to an ordinary field. Rebuilding the leaf stays here,
+ * because that is AST work.
+ */
+type FormulaCellRenderCtx = {
+  expr: string;
+  numberFields: readonly {
+    path: string;
+    label: string;
+  }[];
+  onChangeExpr: (expr: string) => void;
+  onUseField: () => void;
+};
+type ValueEditorRenderCtx = {
+  editorKind: ValueEditorKind;
+  field: FieldOption;
+  node: ConditionNode;
+  operator: ConditionOperator;
+  emit: (value: string | string[]) => void;
+};
+type ConditionBuilderProps = {
+  value: ConditionNode | null;
+  onChange: (next: GroupNode) => void;
+  capabilities: ConditionCapabilities;
+  labels: ConditionBuilderLabels;
+  /** Formatting locale for the date editor. */
+  locale: string;
+};
+declare const ConditionBuilder: ({ value, onChange, capabilities, labels, locale }: ConditionBuilderProps) => import("react").JSX.Element;
+//#endregion
+export { ConditionBuilder, ConditionBuilderLabels, ConditionCapabilities, FormulaCellRenderCtx, ValueEditorRenderCtx };